一个面向 NAS / 云服务器部署的 微信读书自动阅读助手,以 Docker 容器形式提供 Web 管理面板。 无头(headless)运行,无需图形桌面,扫码登录后自动按书架进度完成每日阅读目标,支持 Cookie 失效自动推码恢复。
本仓库为 Docker / Web 版本;Windows 桌面版见 WxRead。
- 📚 自动阅读调度:按书架进度驱动选书,顺序选章,防风控间隔,达成每日阅读目标后自动停止。
- 🌐 Web 管理面板:FastAPI + Uvicorn 提供浏览器管理界面(端口
5911),支持配置、书架同步、日志查看、运行报告。 - 📱 扫码登录:容器内 Playwright 无头 Chromium 生成微信读书登录二维码,手机扫码即可登录,无需桌面浏览器。
- 🔄 Cookie 失效自动恢复:登录态失效时自动唤起扫码,并将二维码图片推送到微信,手机长按识别即可恢复,全程无需打开面板。
- 🔌 Skill API 集成:对接微信读书 Skill 网关,查询书架、章节、进度与今日阅读统计(独立于 Cookie)。
- 📢 WxPusher 推送:每日开始/完成、Cookie 失效、登录成功等事件可推送到微信(文本 + 图片双通道)。
- 🔑 本地授权系统:首次启动 12 小时试用期,之后输入注册码激活(纯离线校验,无网络请求)。
- 🛡️ 安全设计:Bearer Token 鉴权、端口绑定策略、敏感配置段保护、Docker volume 数据持久化。
- 🐳 Docker 多阶段构建:linux/amd64 镜像,Playwright Chromium 预下载,含中文字体与运行库。
| 模块 | 技术 |
|---|---|
| Web 框架 | FastAPI + Uvicorn |
| 浏览器自动化 | Playwright (headless Chromium) |
| HTTP 客户端 | requests |
| 运行时 | Python 3.14(pure 模式,无 Qt 依赖) |
| 容器 | Docker 多阶段构建 (python:3.14-slim-bookworm) |
| 通知 | WxPusher |
wxread_docekr/
├── app/
│ ├── core/ # 核心逻辑
│ │ ├── weread_api.py # 微信读书 API(签名/阅读上报/Cookie 续期)
│ │ ├── scheduler.py # 阅读调度器(进度驱动 + 防风控)
│ │ ├── skill_api.py # Skill 网关调用
│ │ ├── notifier.py # WxPusher 推送
│ │ ├── licensing.py # 本地授权(注册码 + 试用期)
│ │ ├── local_db.py # 本地书架/进度持久化
│ │ ├── config.py # 配置读写
│ │ └── runtime.py # 运行时抽象(信号/线程)
│ ├── web/ # Web 面板
│ │ ├── app.py # FastAPI 应用工厂
│ │ ├── auth.py # Bearer Token 中间件
│ │ ├── routes/ # REST/SSE 路由
│ │ └── static/ # 前端静态资源
│ └── utils/
├── tools/
│ └── playwright_login.py # 无头扫码登录
├── docker/
│ └── Dockerfile # 多阶段构建
├── main_headless.py # 容器入口(uvicorn + 调度器)
├── docker-compose.yml # 编排文件
├── requirements-docker.txt # 运行时依赖
└── DEPLOY.md # 详细部署指南
- 已安装 Docker 与 docker compose(v2)
- 目标平台:linux/amd64(NAS x86_64 / Debian)
git clone https://github.com/SomnusWei/wxread_docker.git
cd wxread_docker国内环境可传入清华源加速 pip 与 Playwright 浏览器下载:
docker compose build \
--build-arg PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple \
--build-arg PLAYWRIGHT_DOWNLOAD_HOST=https://cdn.npmmirror.com/binaries/playwright复制 docker-compose.yml 中注释的环境变量,或创建 docker-compose.override.yml:
services:
wxread:
environment:
WXREAD_WEB_TOKEN: "<你的访问令牌>" # 建议设置,启用 Bearer 鉴权
WXREAD_LICENSE_CODE: "<授权码>" # 可选,启动时自动激活注册码可在本机项目目录生成:
python -c "import sys; sys.path.insert(0,'.'); from app.core.licensing import generate_code; print(generate_code())"
docker compose up -d容器端口默认发布到宿主机 127.0.0.1:5911。推荐通过 SSH 隧道访问:
ssh -L 15911:127.0.0.1:5911 user@<NAS_IP>浏览器打开 http://127.0.0.1:15911,输入 WXREAD_WEB_TOKEN 令牌即可。
如需局域网直接访问,可将
docker-compose.yml端口改为"5911:5911",但必须同时设置WXREAD_WEB_TOKEN,并建议外层套反向代理启用 HTTPS。
- 扫码登录:面板「扫码登录」→ 获取二维码 → 手机微信扫一扫确认。
- 同步书架:面板「书架」→ 同步书架,拉取书架列表。
- 配置 Skill:面板「配置」→ Skill 区填入 API Key → 保存 → 「维护」验证。
- 配置推送(可选):面板「配置」→ 推送区填写 WxPusher 凭证,开启 Cookie 失效自动推码。
- 三门禁(授权 + Cookie + 书架)通过后,调度器自动启动。
| 变量 | 默认 | 说明 |
|---|---|---|
WXREAD_WEB_TOKEN |
空 | Web 面板 Bearer Token;留空不启用鉴权(仅信任内网时) |
WXREAD_LICENSE_CODE |
空 | 启动时自动激活的注册码 |
WXREAD_LICENSE_ADV |
空 | 设为 1 开放「取消激活」入口 |
WXREAD_LOG_RETENTION_DAYS |
7 |
日志保留天数 |
WXREAD_WEB_HOST |
自动 | 显式指定监听地址(反代/host 网络场景) |
WXREAD_PORT |
5911 |
Web 服务端口 |
APPDATA |
/data |
数据目录(配置/Cookie/数据库/日志) |
TZ |
Asia/Shanghai |
时区 |
所有运行数据保存在 Docker volume wxread_data(挂载至容器 /data):
| 路径 | 用途 |
|---|---|
/data/WxReadAssistant/config.json |
配置(Cookie、Skill、推送等) |
/data/WxReadAssistant/local_db.json |
书架、进度、阅读统计 |
/data/WxReadAssistant/logs/ |
运行日志 |
/data/heartbeat |
健康检查心跳文件 |
重建镜像不会丢失数据,除非执行 docker compose down -v。
- 端口发布:
docker-compose.yml默认仅发布到宿主机回环127.0.0.1:5911,禁止公网直接暴露。 - 鉴权:设置
WXREAD_WEB_TOKEN后启用 Bearer Token 鉴权;公网暴露必须配合 HTTPS 反向代理。 - 敏感配置:
cookies/headers/scheduler等保护段不可通过 Web API 修改。 - 敏感文件:NAS SSH 凭据、本地测试数据、运行日志等已在
.gitignore/.dockerignore中排除,不会进入镜像或仓库。
容器内置 HEALTHCHECK,通过 /data/heartbeat 文件判断运行状态(每 60s 刷新,10 分钟无心跳判定不健康):
docker inspect --format='{{.State.Health.Status}}' wxreadassistant
curl http://127.0.0.1:5911/healthz# 查看日志
docker logs -f wxreadassistant
# 重启 / 停止
docker compose restart
docker compose stop # 优雅停机 ≤40s
# 更新代码后重建
docker compose up -d --build
# 清理旧镜像
docker image prune完整部署指南(含 WxPusher 配置、Skill Key、反向代理、常见问题等)见 DEPLOY.md。
本项目仅供学习与个人使用,请遵守微信读书用户协议及相关法律法规。作者不对因使用本项目导致的账号封禁、数据丢失等任何后果负责。