Skip to content
xiaoxuraPublic

About

阅迹(ReadTrace)——基于 Go 的自托管微信读书阅读时长自动化管理面板,支持扫码登录、多账号、定时任务、书池管理、实时进度、阅读统计与多渠道推送。单文件部署,数据本地存储。

Topics

Resources

Security policy

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

阅迹 · ReadTrace

每一次阅读,都留下痕迹。

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 加密存储;复制数据目录即可迁移。
账号 运行记录
书池 推送渠道
定时任务 设置
更新日志 移动端

快速开始

1. 构建

需要 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

2. 启动

# Windows
.\readtrace.exe

# Linux / macOS
./readtrace

默认监听 http://127.0.0.1:8720 并自动打开浏览器。首次访问会要求设置管理密码——这不是微信读书密码,只用于保护面板。

3. 绑定账号

在「账号」页点 扫码添加,用手机微信扫一扫并在手机上确认;如果手机显示 4 位验证码,就在面板里填入。或者点 粘贴 Cookie 导入浏览器里抓到的 read 请求。

扫码链路:GET /api/auth/getLoginUid → 二维码内容 https://weread.qq.com/web/confirm?uid=... → 持续长轮询 GET /api/auth/getLoginInfo。扫码后可能返回 NEED_OTP(手机显示验证码)或直接返回登录凭据,两条路径都已支持,最终写入 wr_vid / wr_skey。整个过程在服务端完成,不依赖浏览器插件。

扫码登录

4. 开始阅读 / 设置定时

  • 在总览页点 开始阅读,选择时长即可。
  • 在「定时」页新建任务,例如每天 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 秒随机延迟,避免固定的节奏指纹。

单次心跳流程:

  1. 从账号配置加载请求模板(即该账号保存的专属抓包/生成模板,模板唯一来源,不内置默认书)。
  2. 按阅读模式决定本次心跳读的书与章节:顺序书单按书池顺序逐章推进(读满一章的字数预算才切换,读完整本自动下一本并循环);随机轮换从池中随机抽取;指定书籍固定一本书并模拟翻页推进。
  3. 更新 ct、rt、ts、rn,重新计算 sg 与 s。
  4. POST /web/book/read,检查 succ / synckey。
  5. 没有 synckey 时调用 /web/book/chapterInfos 修复;连续失败会停止并提示。
  6. 登录态异常时调用 /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,默认开启,可在「账号 → 设置」关闭)、最终失败(自动重试后仍未恢复)与确认登录失效。手动停止保持安静;重试期间不单独推送。运行日志和页面状态始终照常更新;「测试推送」仍会按用户操作立即发送测试消息。


常见问题

阅读时长不涨 / 涨得不对

  1. 确认请求模板可用:在「账号 → 编辑」里按提示保存一份抓包模板(浏览器 F12 → Network → 复制 read 请求的 curl),或点「生成模板」免抓包生成。面板不内置任何默认书/模板;导入书籍时若没有模板也会自动生成一份。
  2. 阅读模式建议使用顺序书单(默认),并把书放入账号的书池;随机轮换需要池里同时存在书籍与章节。
  3. 心跳间隔保持 30 秒;过短可能被服务端判定异常。
  4. 在「记录」页打开本次运行,日志会带上当前读的《书名》· 章节名与 synckey/错误码。

微信读书里显示 29 分钟,比设定的 30 分钟少

v0.2.2 已修复。微信读书按每次心跳上报的整数 rt(秒)累计阅读时长,而 rt 向下取整到整秒:30 秒的心跳每拍少报不足 1 秒,30 分钟累计约少 30 秒,手机端再按分钟截断就显示 29 分钟。旧版只看本地墙钟、到 30 分钟就停;现在引擎按「已上报 rt 总和」补足计划并留 10 秒余量,会多跑一小段(默认心跳约半分钟),微信端累计到的时长不会少于 30 分钟。面板与统计仍按计划值记录,不会多算今日目标。升级到 v0.2.2 后新发起的运行即可;已经记录掉的时长无法补回。

如果你看到的是明显少很多(例如只记了几分钟),那不是取整问题,请按上一条检查模板、书池与心跳日志。

阅读完成没有收到推送

  1. 先确认账号已绑定渠道:「账号」列表最右侧的提醒渠道不能是「不提醒」。
  2. 再确认账号的「阅读完成推送」开关是打开的(「账号 → 设置」,默认开启)。
  3. 完成推送只在运行正常结束时发送;手动停止不推送,最终失败与登录失效走另一条提醒。
  4. 仍然收不到时,到「推送」页点「测试」确认渠道本身可用;推送失败的原因会写进该次运行的日志(推送通知失败:...)。

扫码后手机显示什么

有两种情况,面板都支持:

  • 手机显示「登录成功」:面板会自动收到凭据并完成绑定;
  • 手机显示 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 工具链,保证“单二进制”这一目标。

发布 Release

仓库内置了 .github/workflows/release.yml。推送 v* 标签后会自动:

  1. 在 Linux 上执行 go test ./...;
  2. 交叉编译 linux、macOS、windows 的 amd64 / arm64 版本;
  3. 生成 SHA256SUMS;
  4. 创建同名 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 标签一致。


免责声明

  • 本项目与腾讯 / 微信读书官方无关。
  • 微信读书接口可能随时变化,本项目不保证长期可用。
  • 使用本工具产生的任何账号风险、数据丢失或协议纠纷,由使用者自行承担。
  • 请遵守相关服务条款,仅将本项目用于个人学习与技术研究。

License

本项目以 AGPL-3.0 协议开源。

  • 以 AGPL-3.0 发布意味着:任何人都可以自由使用、修改与再分发本项目,但修改版的源码必须以相同协议开放。
  • 如果将本项目(或其修改版)作为网络服务运行,必须向使用该服务的用户提供对应修改版的源代码(AGPL-3.0 第 13 条)。把面板包壳后闭源运营、或以修改版对外提供代刷服务而不开放源码,均违反本协议。
  • 协议约束的是代码与衍生品;README「免责声明」中对微信读书用户协议与使用方式的提示仍然适用,与开源协议互不替代。

About

阅迹(ReadTrace)——基于 Go 的自托管微信读书阅读时长自动化管理面板,支持扫码登录、多账号、定时任务、书池管理、实时进度、阅读统计与多渠道推送。单文件部署,数据本地存储。

Topics

Resources

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Contributors

Languages