每一次阅读,都留下痕迹。
Warning
本项目与腾讯 / 微信读书官方无关。它通过模拟微信读书网页端的心跳请求保持阅读时长,可能违反微信读书用户协议并导致账号被限制或封禁。请仅用于个人学习与自托管研究:
- 不要公开运营、不要提供代刷服务、不要收费或大规模滥用;
- 多用户部署请自行完成个人信息保护、数据安全与当地法律合规评估;
- 开源代码不构成对第三方服务的授权,作者不对账号封禁、数据丢失、协议变更或任何法律纠纷负责。
一个单文件、可自托管的微信读书阅读面板。扫码登录,实时看进度,自动跑定时,把阅读时长和数据都留在自己手里。
阅迹把“刷阅读时长”做成一个带可视化面板的常驻服务:Go 单二进制 + SQLite + 内嵌前端,打开浏览器就能管理账号、看实时进度、查历史趋势、配推送与定时任务。
| 能力 | 阅迹 · ReadTrace |
|---|---|
| 部署形态 | 单个二进制,内嵌前端,无需 Node/Python |
| 配置方式 | 可视化面板,配置存 SQLite |
| 登录方式 | 微信扫码登录,也支持 curl / Cookie 导入 |
| 运行状态 | SSE 实时进度 + 日志流,可随时停止 |
| 历史数据 | 每日时长、连续天数、累计趋势、运行记录 |
| 多账号 | 多账号独立配置与统计 |
| 定时任务 | 面板内 图形化 cron + 下次执行时间 + 启停 |
| Cookie 维护 | 自动续期,失败时标记失效并提示重扫 |
| 推送 | 13 种:PushPlus / WxPusher / Telegram / ServerChan / Server酱³ / Bark / Ntfy / Gotify / PushDeer / 飞书 / 企业微信 / 钉钉 / Apprise,面板内配置与测试 |
| 数据安全 | AES-256-GCM 加密落库,本机密钥 |
| 移动端 / 主题 | 响应式 + 默认浅色,可切换深色 |
- 扫码登录:面板直接向微信读书申请登录二维码,手机微信扫码并确认即可绑定;若手机显示 4 位验证码,填入面板即可,无需抓包。
- 实时阅读面板:进度环、已读分钟、心跳成功/失败次数、实时日志流,卡片随 SSE 自动更新。
- 历史与趋势:今日/本周/累计时长、连续阅读天数、最近 14 天柱状图、每次运行的完整日志(失败原因直接写进日志,运行记录一键筛选)。
- 多账号:每个账号独立设置默认时长、每日目标、心跳间隔、阅读模式、提醒渠道与专属抓包模板;账号表内即可一键绑定提醒渠道。
- 每日只补不足:手动与定时任务都受账号每日目标限制,今日已达标就跳过,未达标只运行计划时长与今日剩余时长中的较小值。
- 书池(阅读的书从哪来):「书籍导入」支持书架一键审查导入(先勾选再确认)、按书籍 ID / 书名查询导入,可选只导免费章节或全本导入(已购/会员);未购买的书会自动跳过。书池管理按账号归属:排序(顺序书单用)、参与/不参与开关、批量删除、逐章查看(含字数与付费标识),还能对照官方目录一键清理付费未购章节。面板不内置任何书籍或模板,池为空时无法发起阅读。
- 三种阅读模式:顺序书单(默认·推荐:按书池顺序逐本读完,读完一本自动下一本,读完循环回第一本;进入下一章的节奏按章节字数折算,进度跨次运行衔接)/随机轮换(每次心跳从池中随机抽取)/指定书籍 + 进度推进(像真实翻页一样推进页面参数)。
- 账号指纹模板:阅读心跳的设备/会话基底。每个账号保存自己的模板(curl 一键粘贴,签名自动重算;也可在我们导入的书籍中免抓包生成)。模板缺失时会在发起阅读前明确报错,导入书籍时自动生成。面板不内置任何默认书。
- 可视化定时任务:5 段 cron、常见时间预设、未来 3 次执行预览、启停开关、下次执行倒计时。
- 账号状态检测:后台按设定间隔自动校验登录态(可关闭),发现失效立即在面板标注,并可通过绑定的推送渠道提醒。临时性错误(如接口偶发 errCode)不会污染账号状态。
- 阅读自动重试:新账号默认失败自动重试 5 次、间隔 30 秒,可调整;登录已失效的情况不会盲目重试。
- 多种推送:PushPlus、WxPusher、Telegram(支持代理)、ServerChan、Server酱³、Bark、Ntfy、Gotify、PushDeer、飞书、企业微信、钉钉、Apprise(自建 API 服务桥接数十种服务),支持发送测试消息。
- 完成回执 + 安静的问题提醒:阅读正常跑完会向账号绑定的渠道推送「阅读完成」(账号级开关,默认开启,可在「账号 → 设置」关闭);手动停止保持安静;最终仍失败或确认登录失效时才提醒。同一失效状态不会反复提醒,可自定义完成 / 失败 / 失效消息模板,支持
{{account}}、{{elapsed}}等变量。 - 响应式界面:桌面侧边栏 / 移动端底部导航,默认浅色主题,可切换深色或跟随系统。
- 内置更新日志:「关于」下方的独立版本页,按版本记录已发布的功能与变化。
- 数据本地化:SQLite 单文件,账号 Cookie 与推送 Token 加密存储;复制数据目录即可迁移。
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
需要 Go 1.27+。
# Linux / macOS
./build.sh 0.2.2
# Windows PowerShell
.\build.ps1 -Version 0.2.2也可以直接用发布页的二进制,或在项目根目录执行:
go build -trimpath -ldflags "-s -w -X main.version=0.2.2" -o readtrace ./cmd/readtrace# Windows
.\readtrace.exe
# Linux / macOS
./readtrace默认监听 http://127.0.0.1:8720 并自动打开浏览器。首次访问会要求设置管理密码——这不是微信读书密码,只用于保护面板。
在「账号」页点 扫码添加,用手机微信扫一扫并在手机上确认;如果手机显示 4 位验证码,就在面板里填入。或者点 粘贴 Cookie 导入浏览器里抓到的 read 请求。
扫码链路:
GET /api/auth/getLoginUid→ 二维码内容https://weread.qq.com/web/confirm?uid=...→ 持续长轮询GET /api/auth/getLoginInfo。扫码后可能返回NEED_OTP(手机显示验证码)或直接返回登录凭据,两条路径都已支持,最终写入wr_vid/wr_skey。整个过程在服务端完成,不依赖浏览器插件。
- 在总览页点 开始阅读,选择时长即可。
- 在「定时」页新建任务,例如每天 01:00 自动阅读 30 分钟。
- 在「账号 → 设置」调整每日目标;在「推送」页添加渠道,并在账号列表为账号选择提醒渠道(完成推送默认开启,可在账号设置里关闭)。
每日目标按「设置」中的站点时区和本工具记录的时长计算。例如目标 30 分钟、今天已读 20 分钟,请求运行 30 分钟时实际只补 10 分钟;今天已达标时不会创建新运行。停止或失败前已计入的时长也参与统计。
旧账号的每日目标初始沿用原来的默认阅读时长,新账号为 30 分钟;可以单独修改,设为 0 关闭每日限制。默认阅读时长仍是单次请求的时长,修改目标从下一次任务生效。跨午夜的记录沿用现有自然日分摊方式,下一次任务会按新一天重新计算剩余量。
| 参数 | 默认值 | 说明 |
|---|---|---|
-addr |
127.0.0.1:8720 |
监听地址。局域网访问用 0.0.0.0:8720 |
-data |
可执行文件同级的 data 目录 |
数据目录,存放 SQLite 与密钥文件;也可用 READTRACE_DATA 指定 |
-no-open |
false |
启动后不自动打开浏览器 |
-log-level |
info |
debug / info / warn / error |
-retain-days |
90 |
运行详情(含日志)保留天数,超期自动清理;累计统计保留,0 表示永久保留详情 |
-host-allow |
空 | Host 白名单(逗号分隔主机名),为空不校验。绑定 0.0.0.0 时建议设置,可防 DNS 重绑定 |
-version |
输出版本号 | |
-reset-password |
清除面板密码(下次启动重新初始化),账号数据保留 |
对应环境变量:READTRACE_ADDR、READTRACE_DATA、READTRACE_LOG_LEVEL、READTRACE_RETAIN_DAYS、READTRACE_HOST_ALLOW。旧版的 WXREAD_* 仍会自动识别,wxread.db 也会在首次启动时重命名为 readtrace.db。
示例:
# 局域网 NAS 上运行
READTRACE_ADDR=0.0.0.0:8720 READTRACE_DATA=/volume1/docker/readtrace ./readtrace -no-open
# 忘记面板密码:先停止使用同一数据目录的服务
./readtrace -reset-password -data ./data数据目录结构(默认与二进制同目录,例如 C:\ReadTrace\readtrace.exe + C:\ReadTrace\data\):
readtrace(.exe)
data/
├── readtrace.db # SQLite:账号、运行记录、统计、日志、定时任务、推送渠道、设置
├── readtrace.db-wal # SQLite WAL(运行时可能存在)
├── readtrace.db-shm # SQLite 共享内存(运行时可能存在)
├── readtrace.lock # 数据目录实例锁;退出后文件可能保留,锁随进程释放
└── secret.key # 本地 AES-256-GCM 主密钥(32 字节)
- 账号 Cookie 与推送 Token 加密后写入数据库,数据库与密钥文件权限为
0600。 - 面板密码使用 bcrypt(cost 12) 哈希存储,登录会话写在 SQLite,30 天过期。
- 所有修改类接口要求同源会话 +
X-Requested-With头;默认只监听127.0.0.1。 - 迁移:停止服务,把整个
data/目录复制到新机器即可。 - 备份:定期复制
data/目录;丢失secret.key后加密数据无法恢复,需要重新登录账号。 - 同一数据目录只能由一个实例使用;密码重置也需先停止服务,不能通过换端口绕过实例锁。
- 保留策略:运行详情及其日志默认保留 90 天(
-retain-days可调,0为永久),启动时与每日自动清理超期详情;最小统计事实继续保留,用于累计和趋势。此修复不能恢复以前已经删除的统计数据。
通过公网访问时,请在前面加一层 HTTPS 反向代理(Nginx / Caddy / Traefik),否则管理密码与会话会以明文经过网络。HTTPS 下服务会自动给会话 Cookie 加上
Secure。
完整部署指南见 docs/deployment.md,包含:
- Linux 二进制 + systemd / 手动运行
- Windows 开机自启
- Docker / Docker Compose / NAS
- 1Panel Go 运行环境
- Nginx / Caddy 反向代理与 HTTPS
- 升级、回滚、备份与迁移
- 端口、权限、SSE 等常见问题排查
本地快速体验见上方「快速开始」。
微信读书网页端阅读时每 30 秒会向 /web/book/read 发送一次心跳,上报当前书籍、章节、阅读进度与时间差。每次请求都带两个签名:
sg = sha256(ts + rn + KEY)s = cal_hash("k=v&..." 按 key 排序、URL 编码)
阅迹用 Go 复刻了同一套签名逻辑(见 internal/weread/sign.go),并附带与官方 Python 实现逐字节对照的单元测试。rt 取自真实流逝时间并向下取整到整秒(与官方网页端一致);由于服务端按整数 rt 累计阅读时长,每拍少报的不足 1 秒会累积,引擎因此按「已上报 rt 总和」决定何时停止,并额外补足 10 秒余量,保证微信端累计到的时长不少于计划值。心跳间隔带 ±10% 抖动、定时任务触发带 0~90 秒随机延迟,避免固定的节奏指纹。
单次心跳流程:
- 从账号配置加载请求模板(即该账号保存的专属抓包/生成模板,模板唯一来源,不内置默认书)。
- 按阅读模式决定本次心跳读的书与章节:顺序书单按书池顺序逐章推进(读满一章的字数预算才切换,读完整本自动下一本并循环);随机轮换从池中随机抽取;指定书籍固定一本书并模拟翻页推进。
- 更新
ct、rt、ts、rn,重新计算sg与s。 - POST
/web/book/read,检查succ/synckey。 - 没有
synckey时调用/web/book/chapterInfos修复;连续失败会停止并提示。 - 登录态异常时调用
/web/login/renewal自动续期,失败则标记账号失效。
后端通过 SSE(/api/events)推送以下事件:run.start、run.tick、run.log、run.end、schedule.fire、schedule.skip、schedule.error。前端用原生 EventSource 订阅,进度环、日志流与全局提醒随事件更新。
统计不依赖微信读书官方接口,而是根据本工具每次运行的真实心跳记录聚合:按面板时区切分自然日,计算今日、本周、累计、连续天数与 14 天趋势。因此数据准确、可控,也避免了额外的接口风控。
使用 robfig/cron 解析标准 5 段表达式,时区跟随「设置」中的站点时区。任务触发时如果账号已在阅读,会跳过并记录原因。任务正常跑完后按账号的「阅读完成推送」开关发送回执(默认开启)。
后台任务按「设置 → 账号状态检测」配置的间隔自动校验每个账号的登录态(校验逻辑与手动「检查登录状态」一致:先验证,必要时续期一次再复判)。正在阅读的账号会跳过——它们的循环本身就在续期。检测确认失效后会把账号标记为「已失效」,并在该账号绑定了推送渠道时推送一次「账号失效」提醒(expired 模板可自定义)。
每个账号可配置失败自动重试次数与间隔(「账号 → 编辑」)。一次阅读会话(续期 + 心跳循环)失败后,若仍有重试额度且失败属于可重试类型,引擎会在间隔后重新开始会话,已读进度与心跳计数累计保留;登录已确认失效的情况不会自动重试。
推送分三类:阅读完成(账号级开关 notify_on_success,默认开启,可在「账号 → 设置」关闭)、最终失败(自动重试后仍未恢复)与确认登录失效。手动停止保持安静;重试期间不单独推送。运行日志和页面状态始终照常更新;「测试推送」仍会按用户操作立即发送测试消息。
- 确认请求模板可用:在「账号 → 编辑」里按提示保存一份抓包模板(浏览器 F12 → Network → 复制
read请求的 curl),或点「生成模板」免抓包生成。面板不内置任何默认书/模板;导入书籍时若没有模板也会自动生成一份。 - 阅读模式建议使用顺序书单(默认),并把书放入账号的书池;随机轮换需要池里同时存在书籍与章节。
- 心跳间隔保持 30 秒;过短可能被服务端判定异常。
- 在「记录」页打开本次运行,日志会带上当前读的《书名》· 章节名与
synckey/错误码。
v0.2.2 已修复。微信读书按每次心跳上报的整数 rt(秒)累计阅读时长,而 rt 向下取整到整秒:30 秒的心跳每拍少报不足 1 秒,30 分钟累计约少 30 秒,手机端再按分钟截断就显示 29 分钟。旧版只看本地墙钟、到 30 分钟就停;现在引擎按「已上报 rt 总和」补足计划并留 10 秒余量,会多跑一小段(默认心跳约半分钟),微信端累计到的时长不会少于 30 分钟。面板与统计仍按计划值记录,不会多算今日目标。升级到 v0.2.2 后新发起的运行即可;已经记录掉的时长无法补回。
如果你看到的是明显少很多(例如只记了几分钟),那不是取整问题,请按上一条检查模板、书池与心跳日志。
- 先确认账号已绑定渠道:「账号」列表最右侧的提醒渠道不能是「不提醒」。
- 再确认账号的「阅读完成推送」开关是打开的(「账号 → 设置」,默认开启)。
- 完成推送只在运行正常结束时发送;手动停止不推送,最终失败与登录失效走另一条提醒。
- 仍然收不到时,到「推送」页点「测试」确认渠道本身可用;推送失败的原因会写进该次运行的日志(
推送通知失败:...)。
有两种情况,面板都支持:
- 手机显示「登录成功」:面板会自动收到凭据并完成绑定;
- 手机显示 4 位验证码:把验证码填到面板的输入框里提交即可。
如果手机已经显示成功、面板却一直停在「等待微信扫码」,先点「刷新二维码」再扫一次;仍然不行的话,把服务端日志发出来,里面会打印每次轮询返回的 logic。
微信读书的扫码会话没有固定倒计时,面板会持续长轮询等待。如果等待超过 2 分钟仍无反应,点「刷新二维码」重新获取即可。
运行日志会出现 errCode=-2012/-2013,面板会尝试自动续期;仍失败时账号状态变为「已失效」,重新扫码即可(同一微信号会更新原账号,不会重复创建)。
./readtrace -addr 127.0.0.1:8721先停止使用该数据目录的阅迹服务,再执行:
./readtrace -reset-password -data ./data然后重新启动,按首次初始化流程设置新密码。账号与历史数据不会丢失。
不会。每个账号有独立的 Cookie、模板、设置、运行记录与统计;定时任务也按账号独立执行。
本工具通过模拟阅读心跳保持时长,可能违反微信读书用户协议并触发风控。请自行评估风险,仅用于个人学习与自动化研究,不要用于商业用途或大规模滥用。
# 运行测试
go test ./...
# 静态检查
go vet ./...
# 开发模式(前端是内嵌静态资源,改完 JS/CSS 需要重新 build)
go run ./cmd/readtrace -addr 127.0.0.1:8720 -data ./data目录结构:
cmd/readtrace/ 入口:参数、启动、优雅退出
internal/api/ HTTP API、认证、SSE、扫码流程
internal/checker/ 后台账号状态自动检测
internal/engine/ 阅读心跳引擎、事件中心
internal/sched/ cron 调度
internal/notify/ 推送渠道与消息模板
internal/store/ SQLite 数据层与迁移
internal/secure/ AES-GCM 加密
internal/weread/ 微信读书客户端、签名、curl 解析
internal/webui/assets/ 内嵌前端(原生 ES Module,无构建步骤)
docs/screenshots/ README 截图
docs/deployment.md 部署指南(Linux / Windows / Docker / 1Panel / 反代 / 升级备份)
前端刻意不使用打包器:go:embed 直接嵌入原生 ES Module、CSS 与 SVG 图标,改样式不需要 Node 工具链,保证“单二进制”这一目标。
仓库内置了 .github/workflows/release.yml。推送 v* 标签后会自动:
- 在 Linux 上执行
go test ./...; - 交叉编译
linux、macOS、windows的amd64/arm64版本; - 生成
SHA256SUMS; - 创建同名 GitHub Release,上传 6 个单文件可执行程序和校验文件。
发布时推送标签:
git tag v0.2.2
git push origin v0.2.2产物不套压缩包,也不在文件名里带版本号,直接是 readtrace_linux_amd64、readtrace_macos_arm64 这样的固定文件名(文件名里的 macos 即 Go 的 darwin 目标)。版本由 Release 标签和 readtrace -version 提供,服务器更新脚本始终使用同一个下载路径。Linux / macOS 下载后需要 chmod +x:
# 以后每个版本都使用同一个下载地址
curl -fLO https://github.com/xiaoxura/ReadTrace/releases/latest/download/readtrace_linux_amd64
chmod +x readtrace_linux_amd64
./readtrace_linux_amd64也可以在 GitHub 的 Releases → Draft a new release 中新建 v0.2.2 标签并发布;如果该标签没有自动触发构建,到 Actions → Release → Run workflow 填入同一个标签即可补发产物。main.version 会取自标签(去掉开头的 v),所以设置页显示的版本与 Release 标签一致。
- 本项目与腾讯 / 微信读书官方无关。
- 微信读书接口可能随时变化,本项目不保证长期可用。
- 使用本工具产生的任何账号风险、数据丢失或协议纠纷,由使用者自行承担。
- 请遵守相关服务条款,仅将本项目用于个人学习与技术研究。
本项目以 AGPL-3.0 协议开源。
- 以 AGPL-3.0 发布意味着:任何人都可以自由使用、修改与再分发本项目,但修改版的源码必须以相同协议开放。
- 如果将本项目(或其修改版)作为网络服务运行,必须向使用该服务的用户提供对应修改版的源代码(AGPL-3.0 第 13 条)。把面板包壳后闭源运营、或以修改版对外提供代刷服务而不开放源码,均违反本协议。
- 协议约束的是代码与衍生品;README「免责声明」中对微信读书用户协议与使用方式的提示仍然适用,与开源协议互不替代。









