Skip to content

About

网络小说扫榜工作站:QQ阅读会员榜/新书榜采集 + 可视化看板 + Docker 部署

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

网文工作站 · 多平台扫榜

把 QQ阅读 的会员榜 / 新书榜 / 新书月票榜(33 个数据集)和 番茄小说 的新书总榜、 新书榜(都市脑洞、玄幻脑洞)真实抓下来,存进 SQLite,用一个零构建的网页看板看排名、筛题材、比热度。

不逆向签名、不依赖任何第三方包。采集端只要一台能上网的电脑, 不需要模拟器、不需要装 App、不需要登录,一轮约 20 秒。库和看板可以放在任何地方。

任何一台能上网的电脑                服务器 / Docker(后端)          任意托管(前端)
collect_all.py → 各平台榜单接口  →  POST /api/ingest  →  SQLite  →  GET /api/*  →  看板页面

这是什么

网文选题、跟榜、判断题材冷热,靠的是"榜单上现在有什么"。但 QQ阅读 的榜单只存在于 App 里, 没有公开接口,网页版也没有同样的细分类榜单。

这个项目解决的就是这一件事:把 App 里的榜单原样变成可以查询、排序、导出的数据。

它不走逆向签名路线。榜单请求走腾讯网关,签名在 native 层,硬算维护成本极高。 这里换了两个思路:

  1. 接口直连(默认):App 请求榜单时打的是明文 HTTP 接口 GET https://commontgw.reader.qq.com/v7_6_6/listDispatch?actionId=<榜单id>&action=rank…, 不需要登录、不需要 cookie、不需要签名,返回的是完整 JSON。每个榜单一个 actionId, 一页 200 条即全量。36 个数据集跑完约 30 秒,字段与 App 里看到的完全一致。
  2. 模拟器兜底(备选):如果哪天接口加了校验,可以退回「让 App 自己请求、再从它本地缓存里 把响应读回来」的老办法——collector/collect.py + MuMu 模拟器 + ROOT,一轮 3~5 分钟。

两条路输出同一种 JSON,后端不用改,WB_COLLECT_SCRIPT 切一下就行。

特点

数据是真的 接口返回什么就存什么,精确字数、榜单热度原样保留,不做任何估算
零依赖 后端和采集器只用 Python 标准库,不需要 pip install 任何东西
零构建 前端 Vue 3 + Element Plus 全在 frontend/vendor/,不访问任何 CDN,内网/离线可用
半分钟一轮 直连接口,36 个数据集约 30 秒;跨平台,Windows / macOS / Linux 都能采
可拆分 采集、存储、展示三块独立,笔记本采集 + 服务器看板是最常见的用法
可重放 每轮采集的原始 JSON 都落盘在 data/raw/,后端挂了也能重新导入

看板上能做什么

  • 左侧「扫榜」按平台拆成两个子菜单:QQ阅读、番茄小说,各看各的榜
  • QQ阅读 三个标签页:会员榜 / 新书榜 / 新书月票榜,前两个各 16 个分类子榜, 新书月票榜是创世本月入V新书的月票排行
  • 番茄小说 两个标签页:新书总榜(男频连载按热度,跨分类 200 条)、新书榜 (都市脑洞 / 玄幻脑洞两个分类,靠右上角分类下拉切换)
  • 番茄两个榜都按「在读人数」排序,书名和作者是从字体里还原出来的(见下文)
  • 按分类筛选、按书名或作者搜索
  • 按排名、热度、字数、加入书架人数排序
  • 番茄的两个榜多一列日增(近 24 小时新增在读),点表头按增量排序
  • 分页浏览,点击书名看详情(简介、标签、近 24 小时新增收藏 / 新增在读、它在各榜单里的当前位置)
  • 左侧「拆书」:详情里点「拆书」,把这本书丢进「拆书列表」并抓下免费章节
  • 「拆书列表」:拆过的书按封面铺开,点封面进拆书阅读;卡片右上角可以移除
  • 阅读时给任意段落写批注、给整章写章纲;这些笔记自动攒成一份「拆书文件」
  • 一键导出当前结果
  • 页面上直接触发采集并显示进度(仅本机可用)

适用的和不适用的

适合:想系统看榜、做选题参考、观察某类题材在榜情况的人;想长期把榜单数据留在自己手里的人。

不适合:想要历史趋势的人。库里只保存当前最新一版,每次采集整榜覆盖,不留时间序列。 这是有意的设计(榜单本来就只有"现在"),如果你要做"这本书这周涨了多少名", 需要自己在采集时把 entries 快照落到另一张表里。


快速开始

完整步骤(含每一步的预期输出和排障)见 QUICKSTART.md。

方式一:Docker(推荐,起来就有数据)

git clone https://github.com/comeding/novel-workbench.git
cd novel-workbench
docker compose up -d --build

打开 http://localhost:8765(局域网里换成机器 IP)——第一次打开会看到进度条, 十几秒后自动变成完整榜单,不用再做任何事。

容器里带了采集器,默认自己采:空库时启动就采一轮,之后每 6 小时巡检一次,数据过期自动补。 库和原始 JSON 都落在宿主机的 ./data/,重建容器不丢。

docker compose logs -f        # 看采集进度
docker compose restart        # 改了配置后重启

容器出不了公网(内网 NAS、公司网络)时,页面会提示「没能抓到数据」, 这时把 WB_ALLOW_COLLECT 设为 0 变成只读看板,改由别的机器推数据—— 见下面「方式三」。

方式二:本机双击(Windows,不用 Docker)

git clone https://github.com/comeding/novel-workbench.git 小说工作站

装好 Python 3.10+,双击 ③ 环境自检.bat(看到「接口连通 OK」就行), 再双击 ① 看榜单.bat,浏览器自动打开 http://localhost:8765,空库会自动抓一轮。 想手动补一轮就双击 ② 采集数据.bat,或在页面右上角点「立即采集」。

命令行一样简单:

python collector/api_rank.py --check        # 自检:网络 / 接口 / 本机服务
python collector/collect_all.py             # 两个平台都采,约 20 秒,自动入库

方式三:只读看板 + 采集机推送

适合「看板放公网、采集在内网」的分工:看板容器设 WB_ALLOW_COLLECT=0, 采集机(任何能上网的电脑)跑

python collector/api_rank.py --push http://看板地址:8765 --token 口令

data/.token 里就是口令。三种方式的数据结构完全一致,随时可以换。

更新到最新版

就一条链,从头到尾:

本地改代码  →  容器里自动生效  →  git push  →  打开看板点「更新」拉下来

一、本地开发。 项目目录整个挂进容器(docker-compose.override.yml),改 backend/ frontend/ collector/ 下的文件,前端刷新即生效,后端 1~3 秒自动重启, 不用重建镜像、不用重启容器。

二、推上去。

git add -A && git commit -m "..." && git push

三、拉到部署环境。 任何一台按 docker compose up -d 起来的实例——本机、NAS、 别的电脑——打开看板 → 左侧「版本控制」→「立即更新部署」。容器自己 git pull, 拉下来的文件经挂载落回项目目录,几秒后新代码生效。也可以打开「自动更新」,按 30 分钟 / 1 小时 / 6 小时 / 每天自查一次。

更新全程只做 git pull,不动镜像,所以不用在机器上另跑脚本,也不吃 docker 权限。 浏览器只跟看板服务器通信,从另一台设备打开这个看板一样能点。

首次部署只有两条命令,之后走上面同一条更新路径:

git clone https://github.com/comeding/novel-workbench
cd novel-workbench
docker compose up -d

三个边界:

  • docker compose 别加 -f docker-compose.yml。那是纯镜像形态,容器里没有 .git, 页面会如实提示不支持,改用 python dev/update.py。
  • 只有改了 Dockerfile 或镜像里的环境变量,才需要 docker compose up -d --build 重建一次。
  • data/ 和 .env 不在版本控制里,更新不会覆盖数据和口令。

命令行等价物(不进页面时用):

python dev/update.py           # 拉代码 → 重建 → 重启 → 探活
python dev/update.py --check   # 只看差几个版本,什么都不动

三种部署形态(挂载 / 纯镜像 / 裸机)的差别、回滚、升级前备份,见 DEPLOY.md 更新到最新版。

部署细节(反向代理、HTTPS、开机自启、备份、升级)见 DEPLOY.md。


目录结构

小说工作站/
├─ backend/                     后端服务,只用标准库
│  ├─ server.py                 启动入口(--host / --port / --no-open / --collect)
│  ├─ app/
│  │  ├─ main.py                HTTP 服务 + 静态文件 + gzip + 路由分发
│  │  ├─ config.py              全部配置走环境变量,本机与容器共用一套
│  │  ├─ db.py                  SQLite 连接、建表、统计
│  │  ├─ schema.sql             表定义(榜单 + 拆书缓存)
│  │  ├─ auth.py                上报鉴权(X-Token)
│  │  ├─ router.py              极简路由
│  │  ├─ routes/                health / boards / books / runs / ingest / collect / reader
│  │  └─ services/              入库事务、采集进程管理、详情补采
│  └─ tools/                    import_legacy.py(重放 json)、backfill_exact.py(补精确字数)
├─ collector/                   采集端
│  ├─ collect_all.py            主入口(默认):分派 QQ阅读 与 番茄,页面「立即采集」跑的就是它
│  ├─ api_rank.py               QQ阅读:直连榜单接口,33 个数据集约 15 秒
│  ├─ fanqie.py                 番茄:新书榜(都市脑洞 / 玄幻脑洞)+ 新书总榜,含书名还原
│  ├─ fanqie_font.json          番茄榜单页的私有区字符 → 汉字对照表(362 条)
│  ├─ fanqie_font_lib.json      番茄书库页(新书总榜)的对照表,另一套字体
│  ├─ collect.py                备选入口:模拟器方案,自检 → 采两个榜 → 补详情 → 上报
│  ├─ rank_cids.json            可选,覆盖内置的榜单 actionId 表(接口改版时改这里)
│  ├─ collectors/qqreader_app.py  模拟器方案的榜单采集(ADB 驱动 + 缓存读取)
│  ├─ detail.py                 加入书架人数补采(走网页版)
│  ├─ chapter.py                拆书(QQ阅读):抓目录和章节正文,也能单独跑
│  ├─ fanqie_chapter.py         拆书(番茄小说):同一套接口,目录明码标免费/锁定
│  ├─ shelf_snapshot.py         每日书架数快照,供「近 24 小时新增收藏」做差
│  ├─ push.py                   单份 json 上报
│  ├─ env.py                    ADB / MuMu / 设备 / root / 分辨率 探测与自检(仅模拟器方案)
│  └─ adb.py                    adb 命令薄封装(仅模拟器方案)
├─ frontend/                    纯静态,零构建
│  ├─ index.html                Vue 模板 + Element 组件
│  ├─ assets/                   style.css / api.js / app.js
│  └─ vendor/                   Vue 3.5、Element Plus 2.9、图标、中文包(约 1.7MB)
├─ dev/                         开发与运维小工具
│  ├─ supervisor.py             监听 .py 改动自动重启(容器里跑的就是它)
│  ├─ updater.py                更新内核:查版本 / 拉代码 / 重建 / 探活
│  ├─ update.py                 命令行一键更新(纯镜像与裸机用)
│  ├─ make_fanqie_font.py       重建番茄的字体对照表(加 --lib 生成书库那套)
│  └─ agent.py                  宿主执行器:纯镜像部署时的兜底,一般用不到
├─ config.json                  采集端可选配置(模拟器方案的 adb 路径、设备序列号等)
├─ Dockerfile / docker-compose.yml
├─ data/                        运行时生成,不进仓库
│  ├─ workbench.db              SQLite 库
│  ├─ raw/                      每轮采集的原始 JSON(可重放)
│  ├─ archive/                  上报归档
│  └─ .token                    未设 WB_TOKEN 时自动生成的口令
├─ ① 看榜单.bat                 起服务 + 打开看板
├─ ② 采集数据.bat               接口采一轮并入账
├─ ③ 环境自检.bat               检查 Python / 网络 / 接口 / 本机服务
└─ ④ 更新代码.bat               拉最新代码(纯镜像形态用)

data/、_legacy/、rev/、_qqreader/ 都在 .gitignore 里,克隆下来不会包含 数据库和调试遗留物——仓库里只有代码和文档,没有任何数据文件。


环境要求

采集端(路线 A) 服务端(路线 B)
系统 任意(Windows / macOS / Linux) 任意(Linux / macOS / Windows / 容器)
运行时 Python 3.10+(3.9 实测也能跑) Python 3.10+ 或 Docker
网络 能访问 commontgw.reader.qq.com 即可 采集端能访问到它
模拟器 / App / ROOT 都不需要(只有退回模拟器方案时才要) 不需要

第一次:确认能采集

只做一次,两件事:

  1. 确认这台机器能上网,浏览器能打开 https://qq.com 就行(公司网络要走代理的话, 给 Python 配上 HTTPS_PROXY 环境变量)。
  2. 双击 ③ 环境自检.bat,看到「接口连通 OK」就齐了:
Python      3.13.14(C:\...\python.exe)
采集脚本    C:\...\collector\api_rank.py
榜单配置    5 个榜单 / 36 个数据集(内置表)
接口地址    https://commontgw.reader.qq.com/v7_6_6/listDispatch
接口连通    OK  0.2 秒,返回 1 条(pageSize=1)
本机服务    http://127.0.0.1:8765  未运行(TimeoutError)

结论:可以采集,直接跑 python collector/api_rank.py

「本机服务 未运行」是正常的——自检时你还没双击 ① 看榜单.bat。

接口哪天不通了,先看 python collector/api_rank.py --list 能不能打出榜单 id; 如果 id 变了(App 改版会换),把新的填进 collector/rank_cids.json 覆盖内置表即可。


采集

python collector/collect_all.py              # QQ阅读 + 番茄,约 30 秒,采完自动入库
python collector/collect_all.py 番茄新书总榜  # 只采番茄的新书总榜
python collector/collect_all.py 番茄新书榜    # 只采番茄的新书榜
python collector/collect_all.py 会员榜 番茄新书榜  # 指定几个榜
python collector/collect_all.py --no-upload  # 只落盘到 data/raw,不入库
python collector/collect_all.py --push http://1.2.3.4:8765  # 推到别的机器

python collector/api_rank.py --check         # 自检(网络 / 接口 / 本机服务)
python collector/api_rank.py --list          # QQ阅读的榜单 id 表
python collector/fanqie.py --list            # 番茄的分类与 cid

collect_all.py 只是分派:QQ 的榜交给 api_rank.py,番茄的交给 fanqie.py, 两个脚本各自采完各自上报,所以单独跑其中一个也没问题。

采集结果存两份:data/raw/*.json(原始响应,可重放)和数据库里的当前快照。 三种触发方式等价:命令行、双击 ② 采集数据.bat、看板右上角「立即采集」。

后端没起来时采集不算失败:数据照样落盘,脚本会提示你先双击 ① 看榜单.bat, 再用 python collector/push.py data/raw/xxx.json 补推。

采集原理(改脚本前先看一眼)

抓包定位到的就是 App 自己用的那个接口,明文 GET,无签名无登录:

GET https://commontgw.reader.qq.com/v7_6_6/listDispatch
    ?actionId=516604&action=rank&actionTag=boy&pagestamp=1&pageSize=200&rankFlag=1&cateId=0

每个 actionId 对应一个榜单或分类子榜(516604 是会员榜全部,533292 是会员榜-玄幻, 535331 是新书榜全部,549720 是新书月票榜……),完整表在 collector/api_rank.py 的 DEFAULT_CIDS。 pagestamp=2 返回空,说明一页 200 条就是全量,不用翻页。

新书月票榜(549720)对应创世中文网的 https://chuangshi.qq.com/rank/549720_1, 榜名「创世新书月票榜」,口径是「本月入V的创世新书在 QQ阅读 的月票量排行」。 它没有分类子榜——cateId 传任何值返回的都是同一份数据,App 里它就只有一个总榜。 列表里的 num 是本月月票数,所以看板上这一列的表头写「月票」而不是「加入书架」。

响应里的 bookList 字段(bid / title / author / catel2name / totalWords / lastChapter / num / free / vipstatus / sellWords / updateTime)与 App 缓存里 缓存的一模一样,所以这条路和模拟器方案采出来的数据逐本一致。

接口是明文的,但请求会走 TLS,且 Dart 侧的请求绕过系统代理——当初是用设备上的 tcpdump 抓 ClientHello 的 SNI 找到 commontgw.reader.qq.com,再把流量 DNAT 到 mitmproxy 才看到明文体。普通使用不需要任何这些操作,只有接口改版要重新定位时才用得上。

番茄小说(书名是字体混淆的)

番茄的榜单页和接口在同一个域名下,接口一次给全 100 条:

GET https://fanqienovel.com/api/rank/category/list
    ?app_id=2503&rank_list_type=3&offset=0&limit=100
    &category_id=262&rank_version=&gender=1&rankMold=1

category_id 就是页面地址里的最后一段(262 都市脑洞、257 玄幻脑洞), rank_list_type=3 是新书榜,gender=1 男频。两个坑:

一、书名和作者是私有区字符。 接口返回的是 \ue3ea\ue4f3防御… 这种, 网页靠一个 SourceHanSansSC-Normal 的子集字体把它们画成汉字(字体地址 awesome-font/c/dc027189e0ba4cd.woff2,目前是固定的)。脚本不解析字体渲染, 而是读 collector/fanqie_font.json 里那张 362 条的对照表直接替换。这张表是 把子集字体的每个字形轮廓和思源黑体原字体逐一比对、找到同形字反查出来的。 番茄换了字体时脚本会打印 ! 混淆字体换了,那时重建一次映射:

python -m pip install fonttools brotli
python dev/make_fanqie_font.py

二、少传 gender / rankMold 会静默退回阅读榜。 这是最容易踩的一个: 只给 category_id 接口照样返回 200、照样给满 100 条,但拿回来的是阅读榜的书 (《寿命唯尊》这种两三百万字的老书),跟页面上 20 万字的新书完全对不上, 不对比一下根本看不出来。必须带 gender=1&rankMold=1。

rank_version 反倒可有可无,传空字符串就返回最新一版,不用像以前那样猜版本号。

三、新书总榜在「书库」页,是另一套接口、另一套字体。 页面地址 /library/audience1-stat1-count0/page_1?sort=hottes 是纯客户端渲染的,HTML 里 什么都没有,数据走:

GET https://fanqienovel.com/api/author/library/book_list/v0/
    ?page_count=18&page_index=0&gender=1&category_id=-1
    &creation_status=1&word_count=0&book_type=-1&sort=0

地址栏里的 audience1-stat1-count0 对应 gender=1(男频)、creation_status=1 (连载中)、word_count=0(不限字数);sort=0 就是页面上的 ?sort=hottes(热度)。 接口不用签名,翻页从 0 开始,前 5 页 18 条/页、再往后 10 条/页,脚本按 200 条封顶。

这个接口有两个和榜单页不一样的地方:

  • 字数和在读也是混淆的字符串,形如 74.1万人在读、23.3万字,不是数字, 得先还原汉字再解析中文数量级(万 / 亿)
  • 字体 key 藏在响应头里:x-tt-zhal: k=..;f=e26e946d8b2ccb7;d1=..。书库页用 的是另一套子集字体,和榜单页不通用,所以对照表单独存成 fanqie_font_lib.json, 重建时加 --lib:
python dev/make_fanqie_font.py --lib

书库接口不返回分类,所以总榜没有「分类」这一列(同一本书在「新书榜」里出现过的, 会沿用那边带下来的分类);也不返回章节名,只给一个更新时间,所以详情里的 「最新章节」显示占位。

番茄没有「加入书架」这个指标,列表里的 read_count 是在读人数,所以这一列 表头写「在读」,旁边多一列「日增」——那是在读人数的近 24 小时净增,靠每日快照相减 算出来(见下文「番茄 · 每日新增在读」)。这些书没有 QQ 的详情页,所以抽屉里多给一个 「去番茄看」直跳官网,「拆书」照常可用(走 collector/fanqie_chapter.py)。

备选:模拟器方案

接口哪天加了校验,就切回老路子(Windows + MuMu + ROOT + QQ阅读 登录):

WB_COLLECT_SCRIPT=collector/collect.py python backend/server.py   # 让网页按钮走模拟器
python collector/collect.py --check      # adb / root / App / 缓存库 自检
python collector/collect.py              # 两个榜都采,约 3 分钟,采完上报

原理是「让 App 自己请求,再从它本地缓存里把响应读回来」:清 http_cache 里的榜单响应 → force-stop 重启 App → 进排行榜 → 逐个分类点一遍 → 把这一批新响应捞出来。 两条经验:横滑切分类的手势要落在标签条下方的书目区(y≈319),滑在标签条上只会滚标签; App 切某个分类时会预取邻近分类,所以脚本是「点一下、把新到的全收下」。

加入书架人数(详情补采)

榜单接口只返回 num(榜单热度),不是「加入书架」人数。真正的书架数在书籍详情页, 由 detail.py 单独补(可选,不跑也能用,只是那一栏空着)。模拟器方案的 collect.py 跑完会自动接一段;接口方案的 api_rank.py 只跑 15 秒,所以详情要自己按需补:

python collector/detail.py                  # 补缺的
python collector/detail.py --all            # 全部重采
python collector/detail.py --limit 50       # 先试 50 本
python collector/detail.py --workers 8      # 并发数(默认见脚本)
python collector/detail.py --no-upload      # 只落盘

走的是网页版 book.qq.com/book-detail/{bid}(SSR 里的 rating-item--favor), 和 App 详情页的 introinfo.staticScoreInfo 是同一个统计口径,只是网页更新更勤。 2849 本约 5 分钟,全程不需要模拟器。

极少数老书(bid 很小的早期作品)网页版没有详情页,会 404;这些书的「加入书架」 一栏会退回显示榜单热度,鼠标悬停有说明。

近 24 小时新增收藏(每日快照)

这个数不是接口给的,是自己算出来的。 QQ阅读 三个渠道(榜单接口、App 详情、网页详情) 给的都只有累计的「加书架」人数,没有任何地方直接给增量。所以只能:

今天采到的书架数 - 约 24 小时前采到的书架数 = 这段时段的净增

shelf_snapshot.py 就是「每天记一笔」的那个动作,服务端每 24 小时自动跑一次 (WB_SHELF_EVERY=24,设 0 关闭):

python collector/shelf_snapshot.py                 # 新书榜 372 本,约 20 秒
python collector/shelf_snapshot.py --board vip     # 会员榜(2600 本,约 4 分钟)
python collector/shelf_snapshot.py --no-upload     # 只落盘

每次采到的书架数会同时写进 books(当前值)和 shelf_history(历史一笔), 详情页打开时后端取「18 小时前及更早」的最新一条做差。

三条要知道的限制:

情况 页面表现
还没攒够一天历史 显示 —,副标题「需一天基线」
采集不规律,跨度是 47 小时 显示「近 47 小时」,不假装是 24 小时
书架数超过 1 万 网页只给「1.6万」,误差约 ±1000,只能看个大概

最后一条决定了这个指标只对新书榜可信:新书榜的书基本都在 1 万以下,网页给的是 精确个位(340、9331),差值准确;会员榜的头部书动辄几百万,算出来只能当趋势看。

采集器为什么走 /api/bids 拿书目而不是直连 SQLite:库通常挂在容器里, Windows 宿主机进程和容器里的 Linux 进程同时打开同一个 WAL 文件会直接 disk I/O error(开发时实测踩过,库没坏但服务会 500)。

番茄 · 每日新增在读

番茄的榜单接口直接给在读人数(不像 QQ 要给详情页的加入书架数),但接口只给当前值, 所以日增还是自己攒快照相减:

这次采到的在读 - 约 24 小时前采到的在读 = 这段时段的净增

不需要额外跑脚本:每次采集入库时 ingest 会顺手往 reads_hist 落一条 (只有 unit 是「在读」的榜才记,QQ 的榜单热度不算人数)。列表里多一列「日增」, 点表头可排序;抽屉里那一格是「新增在读」。

情况 页面表现
还没攒够一天历史(第一次采集当天) 显示 —,抽屉副标题「需一天基线」
采集不规律,跨度 47 小时 显示「近 47 小时」,不假装是 24 小时
某本书的精确值没补到 后端标 dx=0,这一格误差约 ±1000

两个榜的精度不一样。 新书榜接口给的是个位精确的 read_count(481151),日增准到个位; 新书总榜只有「74.1万人在读」这种,折成整数只剩万级(±500),两次相减误差最大 ±1000, 所以总榜的日增只能看千位以上的变化,几百的涨跌会被舍入吃掉。

试过从详情页 /page/{bid} 的 SSR 里抠 "readCount":740518 来补精确值,但那个数走 CDN 缓存——同一本书连着请求会在新旧两版之间来回跳(实测 734770 / 740518 交替,差 5700), 比接口的舍入还不可靠,而榜单接口自己刷得反倒快(7 分钟内 74.1万 → 73.5万)。 既然日增要跨天相减,两次必须同口径,所以总榜干脆统一用接口值。详情页只用来补 精确字数(那个不会跳),200 本 8 并发约 12 秒。

换句话说:这列要每天至少采一次才有数,而且第一天永远是 —。

重新导入

后端当时没起来、或者换了机器,可以用落盘的 JSON 补回来:

python backend/tools/import_legacy.py                      # 扫 data/raw,按榜取各自最新一份
python collector/push.py data/raw/xxx.json                 # 单份上报到本机
python collector/push.py data/raw/xxx.json --push http://1.2.3.4:8765 --token xxx

拆书:只看免费章节

扫榜列表里点书名 → 详情底部「拆书」,页面直接跳到左侧「拆书 / 拆书列表」, 同时开始抓这本书的目录——列表里先摆一张「正在抓目录」的占位卡,抓完变成正常封面卡。 点这张卡进「拆书阅读」,左边目录右边正文,点章节直接看。左侧菜单「拆书 / 拆书阅读」 也能直接进,会自动接上上次读的那本。

QQ阅读 和番茄小说都能拆,两边共用同一套阅读 / 笔记 / 拆书文件,抓取各走各的模块: collector/chapter.py 管 QQ,collector/fanqie_chapter.py 管番茄,对外接口一样 (fetch_toc / fetch_chapter / mark_free),后端按 read_books.pf 选一个。 番茄那边的免费判断更简单——目录里 isChapterLock=True 的只给 160 字试读, needPay 也是明码,不像 QQ 要拿第 1 章反推 free 变量;正文同样是混淆字体, 直接用 collector/fanqie_font.json 那张表还原。番茄上架久一点的书一般只放开前 10 章左右,剩下的 isChapterLock=True 只有试读,所以番茄书的「免费 N 章」常常是 10。

拆书列表:左侧菜单「拆书 / 拆书列表」把拆过的书按封面铺开,一本一张卡。 每张卡上的「已存 N 章」是这台机器上真的缓存下来的正文,不是目录规模; 点封面直接进这本书的拆书页,接着上次的章节读。卡片顺序按最近动过的排前面。 卡片右上角的图标可以把它从列表里移除:二次确认后会连目录、已缓存的正文、阅读进度 一起从库里删掉(扫榜数据不动),以后重新拆就是全新的一份。 封面来自目录页的 og:image,抓目录时一并存进 read_books.cover;老记录没有封面时按 QQ阅读 的封面 CDN 规则兜底(cover/{bid % 1000}/{bid}/t5_{bid}.jpg),再失败就显示书名首字。 番茄的封面是带签名的 CDN 地址、一天就过期,所以库里存原地址、前端拿的是 /api/reader/cover/{bid} 这个代理:后端按 x-expires 判断快到期就重新取一次页面换新签名。

目录只列免费章节。 一本 1.3 万章的长篇,免费章往往只有前 30 章加几章限免, 付费章网页只给两百字试读,列出来除了浪费点击没别的用——所以拆书页从头到尾只有免费章节。

做笔记:正文里鼠标移到任意一段,段落左边会冒出一个小圆按钮,点开就在这一段下面 写批注(再点一次是改,右上角能删);一章读完,正文末尾有「本章章纲」,两三句话记下 这章讲了什么。有笔记的章,目录里会带一个黄点,回头找得快。Ctrl + Enter 直接保存。 批注按「第几章 + 第几段」锚定,同时存下这一段的前 40 个字——万一正文重抓后段落重排, 还能靠原文对位。

拆书文件:左侧菜单「拆书 / 拆书文件」,版式和拆书列表一样,一本书一张封面卡, 卡上写作「N 条笔记 / 章纲几条 / 批注几条」。点封面进去是按章排好的文档: 每章一段章纲、下面跟着这一章的批注(带原文摘录)。批注默认折起来,只露章纲—— 先看骨架,想看细节再点章末那条「本章批注 N 条」展开;有批注的章多于一章时, 标题区还有「展开全部批注 / 收起全部批注」一次摊开。文件不是另存的一份快照, 而是笔记的实时汇总——改一条批注,文件立刻跟着变,不会出现两份对不上的内容。 右上角「复制全文」把按章整理好的 Markdown 直接贴进笔记软件。 拆书阅读页右上角的「拆书文件」按钮会带上这本书的笔记条数,一点就跳过来。

数据来自 QQ阅读 网页版,不用登录、不用模拟器:

目录  https://book.qq.com/book-chapter/{bid}      一次给全书(实测 1.3 万章也一次拿完)
正文  https://book.qq.com/book-read/{bid}/{第几章}  免费章节给全文

两个页面都是服务端直出,章节列表和正文原本就内嵌在 HTML 里,直接解析即可。

目录里的免费标记怎么来的。 每章虽然有 free 字段,但网页直出时被压缩成变量名 (free:a / free:d),值读不出来。抓第 1 章看它是免费还是付费,就能反推出这个变量代表什么, 一次请求标好全本。实测《校花的贴身高手》13297 章里标出 38 章免费,抽查第 30/31 章、 308/309 章的边界都和实际一致。

整本目录仍会落库(read_chapters 存全量,带免费标记),接口只把免费的发给页面: 以后要放宽到付费试读,改一处筛选即可,不用重新抓。如果某本书一本免费章都没有, 页面上会直接说明,不会列出读不了的章节。

目录和正文都缓存在库里(read_books / read_chapters / read_text), 所以第二次打开是秒开的。新章节出来了点页面右上角「重抓目录」。

看正文嫌目录占地方,点目录标题栏右侧的箭头把左边收起,正文会铺开; 收起后左边留一条窄栏,点一下「目录」就回来。收不收的状态记在浏览器里,下次进来还是上次那样。

命令行也能用:

python collector/chapter.py 61592341                    # QQ阅读:看免费章节列表
python collector/chapter.py 61592341 --read 1           # QQ阅读:看第 1 章
python collector/fanqie_chapter.py 7691315202393902142  # 番茄:看目录(标出哪些锁了)
python collector/fanqie_chapter.py 7691315202393902142 --read 1

配置

config.json(采集端,可选)

{
  "adb": "",                    // 仅模拟器方案:adb.exe 完整路径,留空自动探测
  "serial": "",                 // 仅模拟器方案:设备序列号,如 127.0.0.1:16384
  "base_size": [1080, 1920],    // 仅模拟器方案:坐标基准分辨率,一般不用改
  "boards": ["会员榜", "新书榜"]  // 默认采集的榜单
}

环境变量(服务端 + 采集端)

变量 默认 说明
WB_HOST 127.0.0.1 监听地址,容器内必须 0.0.0.0
WB_PORT 8765 端口;被占用时自动往后试 12 个
WB_DB data/workbench.db 库文件位置
WB_FRONTEND frontend 静态目录
WB_RAW data/raw 原始 JSON 目录
WB_ARCHIVE data/archive 上报归档目录
WB_TOKEN 自动生成 上报口令;不设则生成随机值写进 data/.token
WB_ALLOW_COLLECT 本机自动判断 是否允许网页触发采集,0 关 / 1 开
WB_AUTO_COLLECT 未设 0 启动不采;1 每次启动都采;不设则空库或超时才采
WB_AUTO_COLLECT_AGE 6 「超时」的阈值,单位小时
WB_COLLECT_EVERY 0(容器里 6) 常驻时每几小时巡检一次,过期就补采;0 关闭
WB_SHELF_EVERY 24 每几小时记一次书架数快照(新增收藏的基准);0 关闭
WB_COLLECT_SCRIPT collector/api_rank.py 网页触发采集时执行的脚本;换回模拟器就填 collector/collect.py
WB_PUSH http://127.0.0.1:8765 采集端上报地址(push.py 读)
WB_DEV 未设 1 时静态资源不缓存(docker-compose.override.yml 默认开启,配合热重载)

WB_TOKEN 同时也是采集端的口令变量,两个角色共用一个名字:服务端用它做校验基准, 采集端用它作为请求凭据。


接口

GET  /api/health                          存活 + 是否允许采集
GET  /api/stats                           库统计(在榜条数、书目数、体积、采集时间)
GET  /api/boards                          榜单列表 + 各自条数
GET  /api/dataset                         整包数据(看板首屏用)
GET  /api/boards/{key}/cats               分类子榜及 cid
GET  /api/boards/{key}/books?cat=&q=&sort=&page=&size=     分页查询
GET  /api/books/{bid}                     详情 + 它在各榜单里的当前位置
GET  /api/runs                            采集日志
POST /api/ingest                          采集端上报,需 X-Token
POST /api/details                         书籍详情上报(加入书架人数),需 X-Token
POST /api/collect                         触发本机采集
GET  /api/collect/status                  采集进度 + 日志尾部
POST /api/collect/cancel                  中止
GET  /api/reader/books                    拆书:拆过的书(封面、已存章节数、读到哪)
DELETE /api/reader/books/{bid}            拆书:从列表里删掉这本书(目录 + 正文 + 进度)
GET  /api/reader/{bid}/toc                拆书:目录(?refresh=1 重抓,?pf=fq 首次抓番茄书)
GET  /api/reader/{bid}/chapter/{no}       拆书:某一章正文(?refresh=1 重抓)
GET  /api/reader/cover/{bid}              番茄封面代理(302 到当前可用的签名地址)
GET  /api/reader/history                  拆书:最近读过的书
GET  /api/reader/{bid}/notes              拆书:这本书的全部笔记(批注 + 章纲)
POST /api/reader/{bid}/notes              拆书:写 / 改一条笔记(text 传空 = 删除)
DELETE /api/reader/{bid}/notes/{no}/{para} 拆书:删一条笔记(?kind=outline 删章纲)
GET  /api/reader/docs                     拆书文件:写过笔记的书
GET  /api/reader/docs/{bid}               拆书文件:某本书的章纲 + 批注 + markdown(复制全文用)

key 取值:vip(会员榜)、new(新书榜)、ticket(新书月票榜)。

读接口不鉴权——看板本身是公开的。写接口(ingest、details)必须带 X-Token, 或者用 ?token= 查询参数。


数据结构

只保存当前最新一版,六张表:

表 说明
boards 会员榜 / 新书榜 / 新书月票榜 / 番茄新书榜 / 番茄新书总榜,各自的 cid 和排序说明
categories 36 个分类子榜(会员榜 16 + 新书榜 16 + 新书月票榜 1 + 番茄新书榜 2 + 番茄新书总榜 1),每个都是接口真实返回的独立榜单
books 书目维表,bid 主键,同一本书在多个分类里只存一份简介;shelf/fans/score 来自详情页
entries 当前在榜记录,(榜单, 分类, 书) 唯一,存名次与指标
shelf_history 书架数的历史快照,(bid, at) 唯一;唯一一张不覆盖的表,只增不改,用来算新增收藏
runs 采集日志(什么时候采的、多少条),删了不影响数据

拆书另有四张缓存表和一张笔记表,和榜单数据互不影响,删掉只是下次重新抓一遍:

表 说明
read_books 一本书的目录概要:书名、作者、封面、总章数、免费章数、校准用的标记(一行就是拆书列表里的一张卡)
read_chapters 章节目录:第几章、章节名、是否免费
read_text 正文缓存:免费章节存全文,付费章节存试读片段(paid=1)
read_history 最近读过的书,拆书页空态时列出来
read_marks 拆书笔记:kind=note 是段落批注(带段落序号和原文摘录),kind=outline 是本章章纲;只有这张表是人手写的

入库是按分类覆盖:本次采到的分类,先清空该分类的旧 entries 再写新的; 本次没采到的分类原样保留。所以中途失败只影响采到的那部分,不会把整榜清空。 采到该榜全部分类时,视为完整重采,App 里已下线的分类会被一并清掉。 采集结束后 books 会清掉已经不在榜的书。入库整体在一个事务里,中途失败全部回滚。

entries 上有 (board_key, cat, rank) 和 (bid) 两个索引,分页和详情都是直查。

关于数值精度:App 返回的 totalWords 是精确整数(如 255930),num 是精确的榜单热度(如 119715)。 采集端把两者都原样存下来,entries.words_exact 存精确字数、collect_num 存榜单热度。 entries.words 只是除以 10000 后的万位小数,供列表紧凑显示用,详情一律读精确值。

页面上「加入书架」一栏用的不是 num,而是详情页的书架人数 books.shelf(App 原样字符串, 如 14.3万,一万以下给精确值如 5269),books.shelf_num 是折成的整数,只用于排序和比例条。 两者口径不同:一本新书可能热度很高但书架人数很少,别再混着用。 番茄的书没有书架数,接口只给 read_count(在读人数),所以那一列在番茄榜下叫「在读」, 显示的就是 entries.collect_num 的原值。

早期采集的 json 没有 total_words 字段,这些记录 words_exact 为 0,详情退回显示「25.6 万字」。 补精确值有两种方式:

python backend/tools/backfill_exact.py      # 从 App 缓存补(只能补缓存覆盖到的书)
python collector/collect.py                 # 重新采一轮,全量精确

前端

纯静态、零构建:index.html 直接用 <script src> 引 Vue 3 和 Element Plus, 模板写在 HTML 里,逻辑在 assets/app.js。所有依赖都放在 frontend/vendor/, 运行时不访问任何 CDN,内网 / 离线机器一样能开。

要升级前端依赖,重新下一遍就行(版本号自己改):

cd frontend/vendor
curl -O https://unpkg.com/vue@3.5.13/dist/vue.global.prod.js
curl -O https://unpkg.com/element-plus@2.9.1/dist/index.full.min.js
curl -O https://unpkg.com/element-plus@2.9.1/dist/index.css
curl -O https://unpkg.com/element-plus@2.9.1/dist/locale/zh-cn.min.js
curl -O https://unpkg.com/@element-plus/icons-vue@2.3.1/dist/index.iife.min.js

主题改 assets/style.css 顶部的变量即可:主色 --el-color-primary,背景 --bg, 卡片圆角 --radius。Element 自身的样式不覆盖,靠 CSS 变量和少量 .el-* 补充。

想单独托管前端:在 index.html 里加一行 window.WB_API_BASE = 'https://你的后端', 或者用 ?api= 参数覆盖。后端已放开 CORS。


常见问题

Q:③ 环境自检.bat 说「接口连通 ✗」 先确认浏览器能不能打开 https://qq.com。要走代理的机器给 Python 设 HTTPS_PROXY, 或者检查防火墙是否拦了 443。接口本身不需要登录,能上网就能采。

Q:以前能采,今天一条都采不到 多半是 actionId 变了(App 大版本改版会换)。用 python collector/api_rank.py --list 看着是通的,就把新 id 填进 collector/rank_cids.json——格式与 api_rank.py 里的 DEFAULT_CIDS 一样,会整体覆盖内置表。定位新 id 的办法:模拟器里打开对应分类, 抓一次请求看 actionId。

Q:采集卡在某个分类 / 只回了几条 接口那边偶发超时,脚本自带 3 次重试。还不行就单独采这个榜: python collector/api_rank.py 会员榜,日志会打印每个分类的条数与失败原因。

Q:网页上一片空白 / 报「数据库里还没有榜单数据」 库里没数据。跑一次 python collector/api_rank.py,或 python backend/tools/import_legacy.py 导入已有 json。

Q:采集到一半断了,库里会不会只剩半份数据? 不会。入库在一个事务里完成,中途失败整体回滚,库里仍是上一份完整数据。

Q:服务器上「立即采集」按钮是灰的 正常。collect_enabled() 要求「服务跑在本机 + 采集脚本存在」,部署到服务器上不满足, 按钮就该禁用。数据用 api_rank.py --push http://服务器:8765 推过去。

Q:端口 8765 被占用 server.py 会自动往后试 12 个端口,启动日志里会打印实际地址。想固定就 --port 或 WB_PORT。


文档

  • QUICKSTART.md — 新用户十步走,每一步的预期输出与排障
  • DEPLOY.md — Docker / systemd / 反向代理 / HTTPS / 备份 / 升级

说明与边界

  • 采集对象是 QQ阅读 公开可见的榜单数据,不涉及登录凭据、不读取用户隐私内容。 接口无签名,但请自觉控制频率:一轮 20 秒、35 个请求,日常几小时一次足够, 别写循环去压它。
  • 拆书读的是网页版游客就能看的正文,且只做免费章节:目录里只列免费的, 正文只取免费的。付费章节平台本来只给两百字试读,本项目既不展示也不去请求, 更不绕过任何付费墙。要读完整内容请到 QQ阅读 App 里订阅。
  • 项目仅供个人研究与选题参考,请遵守 QQ阅读 的用户协议,不要用于商业转载或数据倒卖。
  • 榜单口径、分类划分都归平台方所有,本项目只做本地留存与展示。
  • rev/、_qqreader/、_legacy/、_scan/ 是开发期留下的调试资料,不在仓库内,与运行无关。

About

网络小说扫榜工作站:QQ阅读会员榜/新书榜采集 + 可视化看板 + Docker 部署

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages