交流群:778213624/339426057/1063542188
摘要 Legado(阅读)是 Android 上最完整的开源阅读器,它的价值不在界面,而在积累下来的数千条社区书源规则。但这套规则只能在 Android 客户端里执行,桌面上没有等价实现,飞牛 fnOS 这类 NAS 系统更无从使用。本文把 Legado 的书源能力重做成一个跑在 NAS 上的 Web 应用:服务端用 Node.js 重新实现规则引擎(CSS、XPath、JSONPath、正则、@ 选择器链、索引语法、@js: 沙箱),客户端是零构建步骤的原生 JS 单页应用,整体按飞牛 FPK 应用格式打包,通过系统统一网关暴露。移植过程中真正花时间的不是把规则跑通,而是三类摩擦:一是 Legado 规则里的 PCRE 写法与 JavaScript 正则的语义差异,二是书源站点普遍存在的「最新章节」与「完整目录」两套结构,三是 fnOS 平台自身的约束——覆盖安装不生效、WebView 缓存旧页面、应用没有系统安装权限。全文记录了这些问题的现象、定位依据与处理方式。当前版本 2.3.1,安装包 6.9 MB(含 Python 规则引擎与本地电子书解析引擎),端到端测试 35 条断言全绿,实测导入书源 1062 条,缓存命中的翻页约 20 ms,整本导出 TXT 单本 860 KB。
关键词 Legado 书源;规则引擎;飞牛 fnOS;FPK;WebDAV;Node.js
Legado 的书源是一份 JSON 描述:搜索地址、列表选择器、各字段抽取规则、目录与正文规则。规则里可以嵌 CSS 选择器、XPath、正则替换,也能写 @js: 调用脚本。这套机制让同一个客户端适配了几千个站点,但执行环境被绑死在 Android —— 规则解析器是 Kotlin 写的,java.ajax 之类的 API 只在安卓运行时里存在。
NAS 用户的实际诉求很朴素:不想为了看小说再开一台设备。飞牛 fnOS 提供了应用商店与一键安装的 FPK 格式,缺的只是一个能跑规则的阅读器。于是有了本文的工作:用 Node.js 重写规则引擎,把 Legado 的书源直接搬进 NAS 的浏览器。
移植路线上有两个约束是硬的,先摆出来。其一,Legado 的规则语法没有正式规范,只能对着社区书源反推语义,所以引擎必须「宽容」——遇到不认识的写法要降级而不是崩溃。其二,fnOS 的更新链路与 Linux 包管理完全不同:appcenter-cli install-fpk 对已安装应用返回成功但不替换文件,应用本身也没有系统安装权限。后文的设计选择大多由这两点推出来。
| 项 | 取值 |
|---|---|
| 宿主 | 飞牛 fnOS(Debian 系),应用以 legado 用户运行 |
| 运行时 | nodejs_v22(平台依赖应用,安装时自动拉起) |
| 入口 | 统一网关 /app/legado-web/,同时监听 :1122 与 app.sock |
| 数据目录 | /vol{n}/@appdata/legado-web(升级保留;安装到哪个卷就在哪个卷) |
| 包格式 | FPK(manifest + config/privilege + cmd/main + app/) |
| 产物大小 | 588 KB(含前端、服务端 bundle 与更新日志) |
服务端按职责拆成 12 个模块,彼此单向依赖:
| 模块 | 职责 |
|---|---|
server.js |
HTTP 路由、SSE 搜索、下载任务、更新检查、手机 API、生命周期 |
books.js |
搜索 / 详情 / 目录 / 正文的完整流程,结果过滤与目录补全 |
rules.js |
规则解析与求值(@ 链、class./text. 前缀、索引、##替换##) |
xpath.js |
精简 XPath 引擎(//a/@href、text()、position()) |
jsrules.js |
@js: 规则沙箱(node:vm),模拟少量 java.* API |
util.js |
出站请求:超时、重试、全局并发信号量(4) |
store.js / minidb.js |
书源 / 书架 / 配置落盘;JSONL 键值库 |
cache.js / searchcache.js |
章节正文磁盘缓存;搜索结果缓存(键带版本前缀) |
replace.js |
替换 / 屏蔽规则(兼容 Legado exportReplaceRule.json) |
article.js |
订阅条目正文抽取 |
dav.js |
WebDAV:/dav/books 只读、/dav/backup 读写 |
Legado 的规则没有规范文档,这里按社区书源的实际用法归纳出四层:
- 选择器层:
class.xx、tag.xx、id.xx、text.xx,对应 CSS 的.xx、xx、#xx与文本匹配; - 链式层:
@分隔多级选择,例如id.chapterlist@p@a; - 索引层:
a.0(第 0 个)、p!0(倒数第 0 个)、li.1:2:3(多个下标); - 后处理层:
##正则##替换与:正则提取。
其中 @ 链与索引是移植重点——它们不是标准 CSS,必须自己解析。实现上把规则切成段落(parseSegment),逐段求值并把结果集传给下一段,遇到属性写法(@href、@text)直接在当前节点上取值。
书源里的正则大量使用 PCRE 特性,直接 new RegExp 会报错。实测一份 38 条规则的 exportReplaceRule.json,其中 20 条是正则,有 5 条在 JS 里无法直接编译:
| PCRE 写法 | JS 处理 |
|---|---|
(?i) / (?mi) 内联修饰符 |
提取为 i / m flag,出现在中间的删掉 |
\h(水平空白) |
改写为 [ \t] |
\R(任意换行) |
改写为 \n |
| 变长后行断言 | V8 支持,直接保留 |
改写后 20/20 全部编译通过。单条规则失败被 try/catch 吞掉,不影响其余规则。
规则里的 replacement 允许写 @js: 脚本,Legado 里这些脚本能调 java.ajax、base64Decode 等。移植时用 node:vm 建沙箱,提供 result、getString、base64Encode/Decode、md5Encode 等常用函数;java.ajax 用同步 HTTP 兜底并要求显式超时——早期版本正是因为在下载线程里同步执行 java.ajax 导致应用假死。
期刊杂志类站点会把「2026年第11期」这类期号当成书名返回。判定规则分三档:
^\d{4}年\s*(第)?\d{1,2}期 → 期刊期号,丢弃
^\d{4}[-./年]\d{1,2}([-./月]\d{1,2})?$ → 纯日期,丢弃
第\d{1,3}期$ 且作者为「未知作者」 → 丢弃
单纯含「第…期」但作者正常的结果保留,避免误杀正经书名。
书源站点常见两套结构:书页顶部「最新章节」(十几条)与单独的完整目录页。若 ruleToc.chapterList 命中的是前者,用户看到的就是「这本书只有 12 章」。
处理方式是补全后校验:
- 目录少于 30 章时,先在书页上找「全部章节 / 完整目录」链接;
- 再尝试
<书页>/index.html、<书页>/all.html; - 新目录必须比原目录多 50% 以上、且包含原目录至少一半的章节才采用。
实测某书源的书页只暴露 12 章(第 38–49 章),换到另一个书源后为 497 章(首章「后记」,末章「李檀斯」)——这也正是「换源」功能存在的意义。
数据全部落在 /vol2/@appdata/legado-web,升级不丢:
| 文件 | 内容 |
|---|---|
sources.json |
书源数组(实测 1062 条) |
books.json |
书架(含阅读进度) |
config.json |
设置、apiToken、保存目录 |
downloads.json |
下载索引 |
library.json |
已缓存书籍清单(书名 / 来源 / 章节数) |
db/search-cache.jsonl |
搜索结果缓存 |
cache/ |
章节正文缓存 |
webdav/backup/ |
WebDAV 备份区 |
两级缓存各管一段:
- 搜索结果缓存:键为「最终请求 URL + 请求体」的 SHA1(带
v3版本前缀,改逻辑就换前缀)。命中直接返回,空结果只缓存 10 分钟。实测同一关键词连搜两次,缓存条目数不变,说明全部命中。 - 章节缓存:正文落盘并按章节索引预取后两章,缓存命中的翻页约 20 ms。
前端是单个 app.js(约 1900 行)+ style.css,按 renderXxx() 划分页面,无框架、无构建步骤。
采用类 Kindle 的排版(图 3):顶栏半透明毛玻璃、衬线正文、首行缩进 2em、两端对齐;底部固定条显示 4 / 50 · 8% 与一条 2 px 进度线。顶栏右侧的 ⇄ 为换源入口,☰ 为目录抽屉(带章节序号与「共 N 章」)。
搜索结果流式返回(SSE),可按「仅可用 / 全部书源 / 分组」筛选,并显示「其中 N 个命中缓存」(图 2)。点卡片进入详情页(图 4),详情页可直接加入书架,或在书架中直接开始阅读。
换源按书名跨源重搜,按「完全一致 → 包含 → 被包含」排序,最多 30 条;切换后按章节标题定位,尽量停在原来那一章。软总线有手机在线时,换源会额外让手机用它的解析器搜一轮,结果里带 viaPhone 标记。
正版接口源默认不参与搜索(2.1.0 起)。起点、QQ阅读、掌阅、番茄、七猫、百度小说、17K 这类「官方接口源」多数要登录态、风控也紧,默认跳过,只在两种情况下参与:搜索页勾选「正版源」,或在书源列表里显式选中具体源。跳过时前端会提示 已跳过 N 个正版接口源,/api/search 的 done 事件里也带 officialSkipped 字段。
书架去重按「章数最多」优先(2.1.0 起):同名同作者的多条记录只保留目录最全的那一条,其余来源写进 altOrigins(含各自章数),换源时可直接看到「哪个源更全」。
服务端扫描指定目录里的 epub / mobi / pdf / txt,登记进 ebook/index.json,以 ebook://<sha1> 呈现:
- EPUB/MOBI 默认派给在线手机解析(
ebook-parse),无设备或超时由服务端兜底;PDF/TXT 只走本机 - TXT 由本地 Python 引擎分章(
legado_bridge.py txt),结果落盘后渲染直读 JSON - 书架同名书改为「挂载本地副本」:保留原书源与
.nb缓存,阅读页本/网按钮可随时切回网文源 - 支持 toc-only(仅目录先行):客户端只回传 part0(
tocOnly:true),正文按需用needChapter信号补齐
RSS / Atom 条目可一键「加入书架」,同一订阅永远映射到同一本书(bookUrl = feed://<订阅地址>),刷新时按条目链接去重,只把新条目插到最前。正文按条目链接抓取原文,抽取优先级为 article → .post-content → #content → main,结果进内存缓存(上限 300 条)。
tools/build-fpk.sh 做四件事:esbuild 把服务端打成单文件 bundle → 组装 build/legado-web/ → 校验关键文件 → fnpack build 产出 588 KB 安装包。更新日志随后打进 app/web/docs/changelog.txt,应用内「更新日志」弹窗直接读这个文件。
静态资源带 ?v=<版本> 指纹,服务端对 .html/.js/.css/.txt 下发 no-cache。早期版本给 app.js 设了 max-age=86400,结果用户端缓存了旧页面、界面一直显示旧版本号——这个坑的解法是页面自校验:
fetch('./api/health?ts=' + Date.now(), { cache: 'no-store' })
.then(r => r.json())
.then(d => {
if (d.version !== meta.content) location.replace(url + '?b=' + d.version);
});带 b= 参数时不再重载,避免服务端与页面版本不一致时的死循环。
/api/update/check 读 GitHub Release 并比对版本;/api/update/download 把 fpk 下到 更新包/ 子目录。国内网络下 github.com 的 release 资源会跳转到 release-assets.githubusercontent.com,该域名直连超时,因此下载按顺序回退四个通道(直链 + 三个镜像),并校验文件大小(<10 KB 视为失败)。
自动安装需要免密权限。tools/enable-update-permission.sh 写入一条 sudoers 规则:
legado ALL=(root) NOPASSWD: /usr/local/bin/appcenter-cli
有权限时后台执行 stop → install-fpk → start(应用会被自己停掉,所以必须 detach),无权限则回退为手动安装指引。
| 能力 | 路径 | 鉴权 |
|---|---|---|
| WebDAV | /dav/books/(只读)、/dav/backup/(读写) |
Basic,密码 = apiToken |
| 同步 | /api/m/sync(书架 + 进度 + 书源汇总)、/api/m/sources.json |
X-Api-Token |
| 书源双向同步 | GET/POST /api/m/sources/sync(lastUpdateTime 为准,支持删除) |
X-Api-Token |
| 阅读 | /api/m/shelf、/library、/toc、/content、/progress(支持批量) |
X-Api-Token |
| 书源桥 | /api/m/booksource、/api/m/legado/{search,book,toc} |
X-Api-Token |
WebDAV 让 Legado 的「备份与恢复 → WebDAV」直接指向 NAS;书源桥则把书架包装成一条 Legado 书源,安卓端导入后即可读 NAS 上的内容。
自建客户端只需一次请求:
GET /api/m/sync?token=<令牌> # 书架 + 阅读进度 + 书源汇总
GET /api/m/sync?since=<毫秒时间戳> # 增量:只返回有变动的书
GET /api/m/sync?full=1 # 书源 items 带完整规则
GET /api/m/sources.json?token=<令牌> # 书源配置文件(Legado 数组格式,可直接导入)
POST /api/m/progress/batch # 批量回传阅读进度/api/m/sync 返回 shelf(书名/作者/封面/来源/目录总数/阅读进度)、progress(可单独做进度同步)、
sources(总数/启用数/分组统计/源列表)。字段与示例响应见 docs/APP同步接口.md。
要把客户端已缓存的书整本推到 NAS,见 docs/客户端缓存上传指南.md(扫描 .nb 缓存文件 → POST /api/m/cache,服务端负责转码)。
简介抓取在服务端是残的(起点反爬、晋江字体混淆),由客户端补全:见 docs/简介补全接口.md(bookinfo 任务)。
test/e2e.js 自带模拟书源站,覆盖导入、搜索、加入书架、目录、正文分页、进度、下载、订阅等 35 条断言,全部通过。
| 指标 | 实测值 |
|---|---|
| 安装包 | 588 KB |
| 书源导入 | 1062 条(历史最大 1146 条) |
| 单章翻页 | 约 20 ms(缓存命中) |
| 搜索(3 源) | 164 本,其中 3 源命中缓存 |
| 整本 TXT | 单本 860 KB(2494 段) |
| WebDAV 取书 | 200,860 KB |
| 替换规则 | 38 条导入,20 条正则全部编译通过 |
- 规则覆盖不全:书源语法没有规范,冷门写法仍可能失败;
- 目录可能不完整:若站点既无「全部章节」链接、也无
index.html,且规则只匹配最新章节区块,则无法补全——此时应换源; - 无法原地覆盖安装:
appcenter-cli install-fpk对已安装应用不替换文件,升级必须uninstall → install(数据目录保留); - 下载源受网络影响:release 资源依赖镜像回退,镜像失效时需手动下载;
- 反爬与 WebView 规则:依赖 WebView 执行的规则无法在服务端还原,这类书源会被跳过。
项目刻意做成「AI 友好」:无构建步骤、无框架、目录扁平、测试自带模拟站。把仓库交给 AI 后粘下面这段即可开工(更细的说明见 docs/AI构建指南.md,内含 8 段可直接复制的提示词)。
你是 FnReader(飞牛 fnOS 上的 Legado 书源阅读器)的开发者。请先按顺序读:
1. docs/AI构建指南.md 2. legado-web/manifest
3. server/src/server.js 4. server/src/books.js
5. app/web/app.js 6. test/e2e.js
读完向我复述:服务端有哪些模块、前端有几个页面、数据存在哪里、怎样才能发一版。
不要先写代码。
约定(AI 与人都遵守):
- 服务端接口放
server.js的route(),移动端接口走checkApiToken; - 前端新页面 =
renderXxx()+router注册;样式追加到style.css末尾; - 不引入前端框架与新的 npm 依赖;
- 改动要补
test/e2e.js断言; - 每次改动都要推源码并发版:
bash tools/publish.sh "说明"。
legado-web/ FPK 工程
├── manifest 版本、依赖、端口
├── config/ privilege(run-as package)、resource
├── cmd/ start / stop / status 生命周期
├── app/ui/ 桌面入口与图标
├── app/web/ 前端(index.html / app.js / style.css)
└── app/server/src/ 服务端 12 个模块
tools/ build-fpk.sh / publish.sh / release.py / deploy.sh / backup.sh
docs/ 使用说明、更新日志、AI 构建指南、手机 API、WebDAV
dist/ 发布产物与示例书源
test/ e2e.js、mock-site.js、preview.js
图 1 书架:封面、阅读进度与长按菜单
图 2 搜索:多源流式返回,状态栏显示缓存命中数
图 3 阅读页:类 Kindle 排版,顶栏 ⇄ 为换源,底部为章节进度
图 4 详情页:封面、来源、简介与加入书架
图 5 书源管理:分组与勾选批量删除
图 6 设置:手机接入、屏蔽规则、版本更新
- gedoor. Legado(阅读)[EB/OL]. https://github.com/gedoor/legado
- 飞牛 fnOS 开发者文档:应用开发与 fnpack [EB/OL]. https://developer.fnnas.com/docs/
- 本项目源码与发布 [EB/OL]. https://github.com/TZYLXS/FnReader




