Files
LFReader/docs/LFReader-构想与调研.md
T
2026-10-28 17:58:30 +08:00

25 KiB
Raw Blame History

LFReader · 构想与调研记录

状态:草案 v0.3 | 更新:2026-10-28 | 范围:个人自用,不对外分发 命名:项目名 LFReader。首期唯一上游是番茄小说,但产品、接口与数据模型都不绑定单一来源(见 4.3)。


1. 目标

1.1 硬约束

约束 说明
墨水屏优先 手机、平板、墨水屏三端都要能用;墨水屏不是“顺便支持”,而是主要使用场景
目标机型 主用掌阅 Tango2(6.13" / 1648×842 / 300ppi / SmartOS);手机、平板为辅助端
段评只读 书评、章评、段评都要能看,但不点赞、不发评论、不写任何内容
自己的账号 使用本人番茄账号登录,可开通 VIP;不为“免付费”做任何绕过
自建服务 NAS 上跑一个 Docker 个人书库服务,作为唯一上游出口与缓存中心
官方书架同步 只读拉取番茄官方书架/进度,本地书架为准,不回写

1.2 产品形态

Android 阅读客户端(手机 / 平板 / 墨水屏)
        ↕ 内网 / Tailscale(外出时经 Cloudflare Tunnel 或 frp,TLS + 固定 Token)
NAS 上的 LFReader 服务端(Docker:账号会话 + 取数 + 缓存 + 书库 + 导出)
        ↕
番茄官方账号与内容接口

1.3 使用环境

  • 客户端:主用掌阅 Tango2(墨水屏,掌阅 SmartOS,支持安装第三方应用);手机/平板用于碎片阅读与调试。
  • 服务端:NAS 上的 Docker 容器,日常只走内网;外出阅读经 Cloudflare Tunnel 或 frp 访问,入口用启动时注入的固定 Token 鉴权。
  • 预期而非需求:翻页水波纹等动效。这类效果由设备刷新策略或阅读器自身实现决定,第三方应用未必可控,不作为验收项。

1.4 明确不做

  • 不做付费章节破解、设备权益伪造、代理池、批量注册。
  • 不做公开下载站、共享书库、资源分发。
  • 不做评论/点赞/刷时长等任何写操作。
  • 首期不接番茄以外的实际书源;但接口与数据模型必须为多源预留(见 4.3)。

2. 结论先行

  1. 客户端用 Flutter,一套代码覆盖手机/平板/墨水屏;墨水屏刷新优先接厂商插件,掌阅若不开放则退化为“零动画 + 系统快刷档”(见 §7)。Tauri 2 因为依赖系统 WebView,残影与老设备兼容性不可控,不作为主选。若只锁定少数机型,Kotlin + Compose 是更稳的备选。
  2. 服务端用 Rust(axum + SQLite),单容器、单二进制、镜像小,签名与协议实现方便做黄金向量测试;Go 是最省心的备选。
  3. 取数依靠“自己的账号 + VIP”解决授权问题,签名与设备身份解决传输问题,两者独立。段评只有 App 通道有完整数据,是必须保留的一环。
  4. 同步只做单向拉取:官方书架 → 本地书库;本地进度不回写,避免以账号身份产生写行为。
  5. 真正的可靠性来自“多源回退 + 整本缓存 + 服务端集中限速”,而不是某一个接口的稳定性。
  6. 找书四件事(搜索 / 推荐 / 榜单 / 分类)都能取到,但除头条搜索外几乎都落在 App 通道 → 设备身份是长期维护成本,不是一次性搭建成本。
  7. 多源是架构要求,不是首期功能:源适配器与内部 ID 映射现在就留好,将来加第二源不用改客户端。
  8. 部署以“内网为常态、外网为附加”:Cloudflare Tunnel / frp 只做通道,鉴权靠固定 Token,公网只开放只读面。

3. 现状调研(首期源:番茄小说)

3.1 fqapp(什锦铺)

  • 形态:Flutter UI + 进程内 Rust 核心(libfqapi_core.so),无自建服务器,GPL-3.0。
  • 取数:番茄 App 端接口(aid=1967)+ 虚拟设备池 + Argus551/Ladon 签名 + 设备 secret_key 解密;另开 127.0.0.1:18921 的 loopback 供 Legado 等外部阅读器调用。
  • 覆盖:搜书、目录、正文、书评、段评、插图、听书、短剧、漫画,最全。
  • 可借鉴:段评接口与解密链路的协议参考;/api/v1/* 的归一化设计;Rust 核心的签名/设备分层。
  • 不建议照搬:设备池轮换、给虚拟设备发 30 天权益那一套(滥用风险最高、最易被封),以及它整体偏重的实现。

3.2 POf-L/Fanqie-novel-Downloader

  • 形态:Tauri 系跨平台打包(发布脚本含 cargo-tauri),Windows/macOS/Linux/Android/iOS;应用源码未公开,仓库只放 Issue 表单、发布脚本与文档。
  • 功能:搜书、TXT/EPUB 下载、阅读器、段评浏览、番茄官方书架登录后同步、漫画/短剧、本地书导入、fanqie serve(本机/局域网服务)。
  • 产品边界(写在 CONTRIBUTING 里,值得直接照抄):
    • 不解锁付费、会员或未上架内容,只读“接口本来就返回给当前账号或游客”的内容;
    • 不对抗风控:限速、熔断、冷却;设备轮换默认关闭;
    • 不做公开下载服务、共享书库;serve 只用于本机或自己的局域网;
    • 不自建账号体系、不运营云同步;书架只走番茄官方;
    • 不写评论、不点赞、不刷时长;只读段评保留;
    • 只做番茄系,不做通用书源。
  • 对本案的价值:它已经验证了“自有账号 + 只读段评 + 官方书架 + 本地服务”这条产品路线是可行的;同时说明 Tauri 能跑 Android,但解决不了墨水屏(残影、老 WebView、无 EPD 控制)。

3.3 其他参考项目

项目 技术 取数方式 可参考点 局限
h13637404183-hub/fanqie-api Python/Flask,Docker 番茄 PC 网页 API + HTML 解析 REST 设计、Docker 部署、详情/目录/正文的网页通道 无评论;搜索需移动端签名,直接用网页通道做不了
denniemok/fanqie-novel-reader React PWA 自建代理 + 多个第三方 API 镜像 阅读器 UI、PWA 离线、繁简转换、API 健康监控 后端代理不公开,依赖镜像,随时失效
shing-yu/fanqie-novel-download Python 早期网页抓取 正文 DOM 与字符映射处理 维护停滞,接口已变
youshen2/Sine-NovelDownloader - 第三方“鲸落 API” 多源切换思路 依赖第三方服务
legado(阅读)书源生态 Kotlin 规则化书源 书源规则与章节缓存模型 番茄源质量参差,评论基本没有

3.4 三条取数通道对比

通道 覆盖 稳定性 账号依赖 结论
A. 头条小说通道(aid=13):api.fanqiesdk.com 搜索、novel.snssdk.com 目录/正文 搜书/目录/正文 中 弱(device/openudid;正文需 DH 解密) 正文主力,实现成本最低
B. 网页端 fanqienovel.com 搜书/目录/正文/书评 中 中(a_bogus、msToken、字体映射、风控) 兜底与详情补充;搜索覆盖有限
C. App 端(aid=1967) 全,含段评、插图 低-中 强(设备 + 签名 + secret_key) 只为段评和缺失章节保留

关键判断:A 和 B 都拿不到完整的段评。段评是硬需求,所以 C 无法完全去掉;但可以把 C 的使用范围压到“只读评论 + 兜底正文”,账号用本人 VIP,不做设备池。

3.5 账号与 VIP 能解决什么

能解决 不能解决
付费/VIP 章节的访问授权(自己付费) 反爬签名(a_bogus / Argus / Ladon)
官方书架、阅读进度、分组 设备绑定与会话风控
降低“虚拟设备领权益”这类高风险做法 段评数据仍只在 App 通道
让整条链路在道义与版权上更站得住 上游接口变更后的维护成本

一句话:账号是授权层,签名是传输层,两者不能互相替代。

3.6 找书能力盘点(搜索 / 推荐 / 榜单 / 分类)

能力 上游端点 通道 可得性 备注
搜书(主) /reading/bookapi/search/tab/v C 高 支持 tab_type 与翻页;登录态下结果更全
搜书(轻签名) api.fanqiesdk.com/.../search/v1 A 高 aid=13,签名要求最低,适合作主力或回退
搜索联想 search_predict A/C 高 输入补全,非必需
热搜 / 搜索落地页 /reading/bookapi/plan/v(scene=10) C 高 返回 search_tag_data 聚合,可当“热门搜索”
推荐流(书城首页) /reading/bookapi/bookmall/tab/v C 中 按 tab_index 返回 cell_data[],offset 翻页;是运营位而非个性流
频道表 同端点,带 tab_type / last_tab_type C 中 tab_item[] 的 title / tab_type 即频道条,服务端配置驱动
榜单 rank_data(cell_id = rank_id) C 中 参数含 genre_tab、rank_sub_info_id、offset;榜单名集合见 main_algo_name(推荐/完本/新书/书友/追更/黑马/巅峰/书荒/礼物/阅读/作者榜)
分类页 /reading/bookapi/new_category/front/v C 高 男频/女频 + 分类瓦片,一次返回整页
书籍详情 详情/分享类端点 A/B/C 高 三通道都有,按可用性挑
书评 book_reviews / idea_list C 高 与段评同族接口

结论:

  1. 四件事全部可得,形态统一为“服务端聚合 → 客户端只读列表”,不需要客户端自己拼接口。
  2. 除头条搜索外几乎全在 App 通道(aid=1967 + 设备签名)。所以“去掉设备身份、只留网页通道”会在找书上明显退化:网页端搜索覆盖窄,推荐/榜单/分类基本没有。
  3. 榜单的 rank_id 不是稳定常量表,通常要从推荐流的 cell_data 里取 → 服务端必须缓存一份“榜单目录”,否则客户端无法自己拼(列入 §11 待验证)。
  4. 推荐流是运营位,字段随版本变动概率高,客户端要把“区块解析失败”做成静默降级,而不是报错。

4. 目标架构

flowchart LR
  subgraph Clients["LFReader 客户端"]
    E[墨水屏设备]
    P[手机 / 平板]
  end

  subgraph NAS["LFReader 服务端(NAS)"]
    API[REST / OPDS]
    CORE[源适配层<br/>限速 · 重试 · 熔断]
    ACC[账号会话<br/>Cookie / 设备身份]
    DB[(SQLite + 书库文件)]
    EXP[EPUB / TXT 导出]
  end

  F[番茄官方接口<br/>书架 / 目录 / 正文 / 段评]

  E -->|内网 / Tailscale| API
  P -->|内网 / Tailscale| API
  E -.->|外出| T["Cloudflare Tunnel / frp<br/>TLS + 固定 Token"]
  T -.-> API
  API --> CORE
  CORE --> ACC
  CORE --> DB
  CORE --> F
  F --> CORE
  ACC -->|只读拉取| F
  DB --> EXP
  EXP --> API

4.1 NAS 服务职责

  1. 保存账号 Cookie 与设备身份(加密存储),维持会话,过期时提示重新登录。
  2. 集中做签名、限速、重试、熔断——客户端永远不直接访问上游。
  3. 搜书、详情、目录、正文、书评/段评的归一化与缓存。
  4. 书库存储:整本正文、评论快照、封面、EPUB/TXT 导出。
  5. 书架同步:只读拉取官方书架与进度,合并到本地书库。
  6. 对外只暴露 REST + OPDS;内网直连,外网经 Cloudflare Tunnel / frp 转发,入口固定 Token 鉴权(见 6.4),不做路由器端口映射。

4.2 客户端职责

  1. 只做 UI 与本地阅读:分页、主题、字体、离线包管理。
  2. 从 NAS 下载“整本包”(元数据 + 目录 + 已缓存章节 + 评论快照),断网可读。
  3. 阅读进度本地保存,可选上报给 NAS;不回写官方。
  4. 墨水屏专项:全刷策略、无动画、按键翻页、低内存。

4.3 多源预留(当前只做番茄,但不做死)

原则:能力接口化、源实现可插拔、内部 ID 与外部 ID 解耦。

  1. 统一领域模型:Book / Chapter / Comment 只存在于内部;源特有字段一律进 raw_json,不污染主表。
  2. 源适配器契约(每个源实现同一组方法,缺的能力显式返回 Unsupported): search(q, page)、detail(ext_id)、catalog(ext_id)、chapter(ext_id)、book_comments(ext_id)、paragraph_comments(chapter_ext_id)、shelf()、progress()。
  3. 能力矩阵:每个源声明 capabilities {search, recommend, rank, category, comments, paragraph_comments, shelf};客户端据此隐藏 UI,而不是“调用后才发现没有”。
  4. ID 解耦:内部 books.id 用 ULID;book_sources(book_id, source, ext_id, is_primary) 承担映射,一本书可挂多个源。
  5. 结构归一:卷/章统一映射为 (volume, idx);正文用内容 hash 做跨源去重,为将来“换源续读”留位。
  6. 选源策略:未指定源时按 sources.priority + health 选择;?source= 可强制指定,仅用于调试。
  7. 客户端完全不感知源:只调 /api/v1/*,换源发生在服务端。

4.4 客户端信息架构

入口 内容 数据来源 首期
书架 本地书架为主,可叠加官方书架只读副本;分组、最近阅读、更新提示 shelf + /sync/shelf 必需
发现 推荐区块、榜单入口、分类入口 /discover、/rank/{id}、/categories 必需(可先只做榜单 + 分类)
搜索 输入联想 + 热搜 + 结果列表(多通道合并去重) /search、/search/suggest、/search/hot 必需
阅读 目录、正文、段评/章评/书评、进度、离线包 /catalog、/chapters、/comments 必需
设置 服务地址 + Token、字体与翻页刷新策略、缓存管理、账号状态 本地 + /healthz 必需

设计原则:

  • 不照搬官方书城的“无限运营位 + 视频/短剧混排”,只保留书籍形态,非书籍区块整块跳过。
  • 发现页做成可配置区块列表:区块类型(榜单 / 分类格 / 横滑书单)由服务端下发,客户端只实现 5-6 种基础类型。
  • 书架是首页,找书是第二入口;不为“像官方 App”牺牲墨水屏的信息密度与翻页速度。
  • 推荐流字段易变,解析失败时静默降级为“榜单 + 分类”,不向用户报错。

5. 技术选型

5.1 客户端(墨水屏权重最高)

方案 墨水屏适配 三端一致性 生态/成本 主要风险 结论
Flutter 好:自绘渲染 + 原生插件调 EPD SDK 高 成熟,招人/查资料容易 需按厂商写刷新插件 推荐
Kotlin + Compose 最好:直接调厂商 SDK 中:一套 UI 自适应 成熟 Compose 动画/内存需专门处理;老设备性能吃紧 备选(只锁定少数机型)
Kotlin + 自定义 View 最好 低 工作量大 无现成组件 不考虑
Tauri 2 差:系统 WebView 残影、老版本 WebView 高 Web 前端复用 墨水屏体验不可控 不推荐
Rust + Slint / egui 中:软件渲染省电 低 早期 中文排版、分页、输入法成本高 观察

选 Flutter 的核心理由:墨水屏需要“完全可控的文字排版 + 可插拔的刷新策略”,Flutter 两端都能满足,且 fqapp 已经证明这条路在 Android 上走得通。

5.2 服务端

方案 镜像/部署 开发效率 协议实现 结论
Rust(axum + sqlx + SQLite) 单二进制,镜像小 中 签名/解密移植最合适,可做黄金向量测试 推荐
Go 单二进制,最省心 高 足够 备选
Python(FastAPI) 镜像较大 高(参考实现多) 快速验证协议 适合 M0 验证
Node/TS 镜像大、常驻内存高 高 一般 不优先

6. 数据与接口草案

6.1 数据表(SQLite)

表 关键字段 说明
books id, title, author, cover, status, word_count, score, updated_at, raw_json 详情快照
chapters id, book_id, idx, volume, title, word_count, is_vip, fetched_at 目录
contents chapter_id, text, format, source, hash, fetched_at 正文,按章缓存
comments id, book_id, chapter_id, para_index, user, content, like_count, created_at, scope 书评/章评/段评
shelf book_id, added_at, last_chapter, progress, source 本地书架
accounts id, cookie_enc, device_id, install_id, secret_key_enc, expires_at 账号与会话(加密)
sources name, enabled, priority, health, last_error 源健康状态
book_sources book_id, source, ext_id, is_primary 内部 ID ↔ 源 ID 映射(多源预留)
discover_cache source, kind, payload, fetched_at 推荐/榜单/分类的区块快照

6.2 REST 草案

GET  /api/v1/discover?source=       # 发现页聚合:榜单入口 + 分类入口 + 推荐区块(可降级)
GET  /api/v1/rank/{rankId}?page=
GET  /api/v1/categories?tab=
GET  /api/v1/search?q=&type=&source=
GET  /api/v1/search/suggest?q=
GET  /api/v1/search/hot
GET  /api/v1/books/{id}
GET  /api/v1/books/{id}/catalog
GET  /api/v1/books/{id}/comments?scope=book|chapter|paragraph
GET  /api/v1/chapters/{id}?include=comments
GET  /api/v1/shelf
POST /api/v1/sync/shelf          # 触发只读拉取
GET  /api/v1/offline/{bookId}    # 整本离线包
GET  /api/v1/export/{bookId}.epub
GET  /opds
GET  /healthz

鉴权:固定 Bearer Token(容器启动时注入),详见 6.4。

6.3 同步语义

  • 官方书架 → 本地:只新增/更新元数据,不删除本地书。
  • 官方进度 → 本地:只读取展示,不覆盖本地更靠后的进度。
  • 本地 → 官方:不回写。若确实需要“加入官方书架”,做成显式手动动作并二次确认。

6.4 公网访问与鉴权

  • 通道:容器只监听内网;外出统一走 Cloudflare Tunnel 或 frp,不在路由器上做端口映射。
  • Token:首次启动生成固定 token(或从环境变量 LFREADER_TOKEN 注入),写入 .env,不落日志、不回显。
    • 客户端用 Authorization: Bearer <token>;不支持自定义头的 OPDS 客户端允许 ?token=(仅 TLS 下)。
    • 比较用常量时间;失败计数 + 短时封禁,避免被扫描。
  • 传输:Tunnel / frp 侧必须 TLS,容器内不做明文公网监听。
  • 暴露面分级:
    • 公网可访问:搜索、发现、详情、目录、正文、评论、离线包、OPDS(全部只读)。
    • 仅内网 / VPN:账号登录与会话管理、同步触发、导出、配置与健康详情。
  • 反代细节:Tunnel 取 CF-Connecting-IP 做限速维度;frp 需 X-Forwarded-For。/healthz 公网只返回状态码,不泄露版本与配置。
  • 客户端配置项:一个「服务地址」+「Token」两个字段即可完成接入,避免多套配置分散。

7. 墨水屏专项清单

  • 翻页后全刷,菜单/光标用局部刷新,避免残影累积。
  • 分页结果按“字体 + 字号 + 屏宽”预计算并持久化,重开秒进。
  • 内置可读性好的中文字体,避免不同设备系统字体差异。
  • 关闭所有动画、阴影、半透明、滚动惯性。
  • 支持音量键/蓝牙翻页器;点击区域大且可配置。
  • 纯离线包阅读,禁止后台轮询,降低耗电。
  • 主用机型 掌阅 Tango2(6.13" / 1648×842 / 300ppi,掌阅 SmartOS):实机确认第三方 APK 安装路径、后台保活、系统“快刷”档位能否被应用影响。
  • 确认掌阅是否向第三方应用开放 EPD / 刷新接口;若不开放,退化为“零动画 + 系统快刷档 + 整页刷新”,并把该限制写进 M4 验收说明。
  • 在 Tango2 上对比 Flutter 自绘与 WebView 的残影/闪烁差异(这是拒绝 Tauri 的实证依据)。
  • 动效定位:不做水波纹 / 仿真翻页,只提供“无动画切换 + 可选整页刷新”;系统或官方阅读器的动效不在控制范围内(见 1.3)。
  • 分页按 1648×842 / 300ppi 校准,手机与平板沿用同一算法换参数。
  • 性能门槛:冷启动 < 3s、翻页 < 300ms、内存峰值 < 200MB、连续翻页 50 次无明显残影。

8. 可靠性工程

  1. 源适配层:每个通道实现同一组能力(搜索/详情/目录/正文/评论),带 health 标记,按优先级回退。
  2. 缓存优先:正文按章不可变;目录 TTL;评论快照 TTL;失败时返回旧缓存并标注时间。
  3. 限速:全局令牌桶 + 随机抖动 + 指数退避;服务端统一控制,客户端不直连。
  4. 签名隔离:签名/设备身份独立成模块,配黄金向量测试;上游变更只改一处。
  5. 契约测试:录制真实响应做 fixture,字段变更时先失败再修。
  6. 配置化:端点版本、超时、限速参数放配置文件,容器更新即可调整,无需发 APK。
  7. 备份:SQLite 定时快照 + EPUB 导出,防止账号或上游异常导致内容不可用。

9. 风险与边界

风险 应对
账号被风控/封禁 只用本人账号、低频、只读;保留 EPUB 导出作为兜底
上游接口变更 多源回退 + 服务端集中升级;不把逻辑写死在客户端
版权与平台条款 个人自用、局域网、不传播、不公开服务
代码许可 fqapp 为 GPL-3.0,直接移植会继承许可;POf-L 未标注许可证且源码未公开,只能参考产品行为
NAS 单点故障 定期备份;客户端保留完整离线包,短时断服可读

10. 里程碑

阶段 内容 验收标准
M0 协议验证 验证 6 个能力:搜索、榜单、分类、目录、正文、段评;确认本人账号下 VIP 章可读、书架可拉 每个能力有可复现的请求与响应;确认段评分页方式、榜单 rank_id 来源、推荐流字段结构
M1 服务端闭环 Rust/Go 服务 + SQLite + 限速 + 缓存 + Docker Compose 核心接口可用(搜索、发现、目录、正文、段评),重启不丢缓存,限速与 Token 鉴权生效
M2 客户端 MVP Flutter 阅读器:书架、找书(搜索 / 榜单 / 分类,推荐可后置)、详情、目录、正文、离线包 手机/平板上完整读一本书,断网可继续;找书入口可用
M3 段评与同步 段评气泡/侧栏;官方书架只读同步 段评按段落定位准确;同步不产生任何写请求
M4 墨水屏适配 EPD 刷新插件、字体、按键、机型验证 通过第 7 节性能与残影门槛
M5 稳定性 多源回退、监控、自动更新、备份 单源故障时阅读不中断;容器可一键升级

11. 待验证问题

  1. 本人账号的 Cookie 能否直接调用 App 端段评接口,还是必须绑定设备身份?
  2. VIP 章节在自有账号下取回的正文是否仍为设备密钥加密?密钥与账号还是与设备绑定?
  3. 官方书架/进度的拉取频率上限,以及字段是否包含分组与排序?
  4. 段评是否支持按章节批量拉取,还是必须逐段/逐章请求?
  5. Tango2 实机的中文渲染表现(字形、行距、灰度层次),据此决定是否内置字体。
  6. 是否需要听书/短剧(建议先不做,控制范围)。
  7. 离线包格式:自定义 JSON 包还是直接 EPUB + 旁挂评论数据库?
  8. 掌阅 Tango2 是否向第三方应用开放 EPD / 刷新接口;不开放时,系统的快刷档位能否被应用指定。
  9. 榜单 rank_id 的稳定来源(推荐流 cell_data 还是固定常量表),以及各榜单的分页上限与刷新频率。
  10. 推荐流 / 分类页的 schema 波动幅度,是否需要服务端做字段兼容层。
  11. Cloudflare Tunnel 下主流 OPDS 客户端(静读天下 / KOReader / Thorium)能否带自定义 Header 或 query token。
  12. 同一本书在 App / 头条 / 网页三通道的 ID 是否可直接互转(决定多源 ID 映射与“换源续读”的可行性)。

12. 参考链接