mtfyun/reader
1
0 Fork 0
mirror of https://github.com/hectorqin/reader.git synced 2026-11-10 21:11:08 +08:00
Code Issues Packages Projects Releases Wiki Activity
110 Commits 15 Branches 1 Tag
d60d7e67f90aa8fb2f707c21a3f5241f6b3da49b
T
Clone
Open with VS Code Open with VSCodium Open with Intellij IDEA
Download ZIP Download TAR.GZ Download BUNDLE

README.md

reader

自部署精品书库阅读器。 把你自己磁盘上的书籍挂载成书库，用 Android 或浏览器以「精品级排版」阅读。

书文件始终留在你自己的磁盘上，不经过任何厂商服务器。开源免费，AGPL-3.0。

三个部分：

部分 位置 说明
服务端 server/ Node.js + TypeScript，单容器，扫描书库并同步进度
渲染层 web/ TypeScript + Vite，EPUB 精排、TXT、漫画、PDF
Android 壳 android/ Kotlin + WebView，复用上面那一份渲染层

一条命令跑起来

git clone https://cnb.cool/hectorqin/reader.git
cd reader

# 把 /path/to/your/books 换成你自己的书库目录
sed -i 's#/path/to/your/books#/home/me/books#' docker-compose.yml

docker compose up -d

打开 http://<你的主机>:8080，第一个注册的账号自动成为管理员。

这时你已经有一个能用的 H5 阅读器了——服务端镜像里已经带了客户端，不用再起第二个容器。 手机浏览器打开同一个地址即可阅读。要原生 App 见下面的「Android 客户端」。

只有第一次注册是开放的。之后新账号由管理员在后台创建（默认关闭公开注册）， 这样你的实例不会被陌生人占用。想让家人自行注册，在 docker-compose.yml 里 把 ALLOW_REGISTRATION 设为 "true"。

最小化运行（不用 compose）

docker run -d --name reader \
  -p 8080:8080 \
  -v /path/to/your/books:/books:ro \
  -v ./data:/data \
  cnb.cool/hectorqin/reader:latest

书库目录：只读，永不写回

volumes:
  - /path/to/your/books:/books:ro   # 你的书，只读挂载
  - ./data:/data                    # 服务端写的一切

服务端绝不写入 /books。所有写操作——SQLite 数据库、封面缓存、扫描记录——都在 /data。 这一条是硬约束，代码里有断言保护：DATA_DIR 落在 BOOKS_DIR 里面时服务会直接拒绝启动。

你的书籍目录不会被污染：不会多出封面文件、.calibre 之类的元数据文件、转换产物。

支持格式

格式 状态 说明
EPUB 精排 保留出版方样式、嵌入字体、脚注跳转、图文混排、竖排、振假名
TXT 支持 自动识别 UTF-8 / GB18030 / Big5 / UTF-16，按章节标题切分
CBZ / ZIP 支持 按页自然排序，逐页铺满屏幕
图片目录 支持 一个文件夹（可含卷子目录与卷压缩包）当一本书，逐页取图
PDF 保底可读 用浏览器自带阅读器，页数与进度照常上报，服务端不解析内容

TXT 是本地书库里最容易被忽视的一块。相当一部分中文 TXT 没有 BOM、没有编码声明， 解码成 UTF-8 会满屏乱码。客户端先严格校验 UTF-8；失败时不是按顺序试 GB18030 再试 Big5，而是两种都解一遍挑更干净的那个——这两个编码的字节范围重叠， 同一串字节往往两边都能解出字符，按顺序试就永远走不到第二个，繁体书会整本变乱码。 选中的编码会显示在界面上，可手动覆盖。 章节同样没有结构，只能从标题推断——推测不出时按长度分段，不会整本卡死。

阅读界面

界面设置按设备保存，不跟着账号同步：字号和主题是「手里这块屏幕」的属性， 把手机的字号推到平板上比不同步更糟。阅读进度和笔记才跟账号走。

排版

设置 说明
翻页方式 滚动（保留作者连续排版）/ 翻页（CSS 多列分页，一页一屏）
字号 0.8×–2.2×，只改基准字号
行距 默认「原书」。选具体值才覆盖，否则一行都不动
页边距 0–4rem，控制每行字数
对齐 默认「原书」，可强制左对齐 / 两端对齐
字体 默认「原书」。可选系统黑体 / 宋体 / 楷体 / 苹方，作为字体栈的前缀而不是替换
主题 白 / 米黄 / 浅绿 / 夜间
亮度 35%–100%，叠加式调暗，文字与纸色的对比关系不变
图片适配 仅固定版式（漫画、PDF）：完整显示 / 适宽
翻页方向 仅固定版式：左→右 / 右→左（日漫）
TXT 编码 仅 TXT：自动 / UTF-8 / GB18030 / Big5 / UTF-16LE

一条原则贯穿全部：每个排版开关的默认值都是「不动」，不是「我们的默认值」。 「原书」不是营销话术而是实现——行距的默认值是 inherit，页边距和字号挂在容器的 继承变量上，所以一本按章节变行距的书不会被压平，一本给段落写死 font-size: 14px 的书也不会被字号滑块踩掉。这与「所有书看起来一致」的 Readium 路线正好相反。

界面与图标

阅读页以手机浏览器为优先：顶部显示返回、书名和章节，底部集中目录、朗读、界面、设置。 工具栏和半屏面板覆盖正文，显隐不改变正文区域尺寸。界面设置可分别选择顶部左/右、底部左/右显示书名、章节名、章节进度、时间或不显示；默认顶部左侧章节名、底部左侧章内页码与全书百分比、底部右侧时间，按设备保存。 底栏上方保留一个日夜切换按钮，随工具栏一起收起。

图标使用 Lucide SVG，通过统一的 Icon 组件控制尺寸、线宽和无障碍标签，不再加载字体图标。 界面规范见 docs/ui.md，手机回归可运行 cd web && npm run ui:review。

翻页与章节导航

  • 点击区域：中间呼出/隐藏工具栏，左右翻页；可切换「左进右退」适配左右手。
  • 上一章 / 下一章：页脚中间的翻页按钮直接换章，不用先滚到章末。 到达书的第一章 / 最后一章时按钮置灰。跨窗口换章（一千二百章的书按 40 章一窗） 会先取那一窗再落章，页脚在取窗期间显示「正在切换…」。
  • 页脚报位置：第 100/120 章 · 本章 1/3 页 · 40%。章内页码与进度条同源、 同一次量测，所以两者不会互相矛盾。
  • 目录即跳转：点任意一章直接跳过去，不在当前窗口的会先拉取那一窗。 跳转失败的章会明说「这一章暂时无法跳转」，不会静默无反应。
  • 翻页动画：滑动 / 淡入 / 无。系统开启「减少动态效果」时自动不播。
  • 硬件翻页键：← / →、PageUp / PageDown，空格播放/暂停朗读。 Android 外壳把音量键映射成方向键，所以音量键翻页、蓝牙翻页器都走同一条路。

朗读（TTS）

三种引擎，一套控制。用哪一个是 auto 决定的，也可以手动指定：

引擎 声音来自 什么时候用
系统语音（原生） Android 外壳的 TextToSpeech Android 客户端默认
系统语音（浏览器） 浏览器 / WebView 的 speechSynthesis Web 端默认
HTTP 朗读 服务端 TTS_URL 指向的合成服务 前两者不可用时

为什么 Android 要用原生引擎：WebView 自带的合成器和系统的是两个引擎， 手机上系统装好的中文语音经常不在 WebView 的语音列表里——于是读者听到英文或听不到声音， 而 Web 层拿到的列表本身就是缺的，无从修起。这是「朗读没有中文声音」最常见的原因。

HTTP 朗读：给没有 speechSynthesis 的浏览器（比如 Linux 上的 Firefox）、 或者没有中文语音的设备用。服务端只做代理，不内置合成模型——容器体积和 NAS 的 CPU 预算 都不该为它买单。在 docker-compose.yml 里加：

environment:
  TTS_URL: "http://host.docker.internal:5002/tts"   # edge-tts / Piper 等兼容服务
  # TTS_TOKEN: "..."          # 需要鉴权的上游
  # TTS_VOICES_URL: "..."     # 语音列表；默认 <TTS_URL>/voices
  # TTS_CACHE_BYTES: "268435456"  # 音频磁盘缓存上限，0 关闭

共同行为：

  • 按句切分：中文按 。！？；…，西文按 . ! ? 且避开 Mr. / 3.14 / e.g.。 逐句朗读才能做到朗读位置跟随显示高亮，也能让「暂停/继续」和「改语速」都只影响下一句。
  • 从当前位置开始：默认从句首读起；若先选中一段文字再按朗读，就从选中处开始。
  • 句子级控制：上一句 / 下一句 / 进度条直接跳句。
  • 语速、音调、音量：语速 0.5×–2.5×，改动即时生效（不重读整段，只重读当前句）。 音调只对系统/原生引擎显示——合成音频没有不改变语速的音调控制，所以那一行直接不出现。
  • 语音可选：列出当前引擎所有可用语音（含语言标签），默认「跟随系统」。
  • 章节播完：可选「继续下一章」或「停在章末」——后者就是有声书的「一次一章」。
  • 高亮：正在朗读的句子用半透明底色标出，并用 Range 绘制，不改写书的 DOM， 所以开始朗读不会让章节重新分页。

一个引擎都没有时，设置面板会直接说明原因和解决办法，而不是给一个按了没反应的按钮。

首页（书架）

  • 先看到书，再看到控件：标题和封面在最上面，搜索在后，排序与数量贴在它们要作用的 那一节上。旧版把搜索框、数量、四个排序 chip 依次排在封面之前——三行控件才轮到第一本书。

  • 排序栏是唯一吸顶的东西：它承载的是「有多少本」和「按什么排」这两件读者会滚回去改的事； 标题吸顶只会用永远占掉手机 4rem 高度去说一件读者已经知道的事。

  • 空状态给一条出路：空书库不是「这里什么都没有」，而是「打开书库 / 刷新」两个按钮； 搜不到结果时给的是「清除搜索」。空态居中的是那块留白，不是文字。

  • 骨架屏：冷启动时按当前密度画出网格的形状，而不是先白屏再弹出一整屏封面—— 密度不对的骨架屏比没有更糟，读者会看到布局动两次。

  • 宽屏是更大的封面，不是更多的封面：内容列封顶 68rem，封面随断点变大。 不然 1600px 的窗口会排出十一个 130px 的封面和十二个字的书名，比手机上的三列更难扫。

  • 深链与返回：#/book/<id> 直接打开那本书，刷新后还在；#/library/<路径> 指向 书库里的一个目录，可以发给别人。返回键走应用自己的屏幕轨迹。

  • 排序：最近阅读（默认） / 最近入库 / 书名 / 作者，书架上一键切换，并记住选择。 两个「最近」问的是两个不同的时间——上次读和进库——而不是同一个「文件改动时间」。 中文书名按数字大小排（第9章 在 第10章 前），不是按字符码。

  • 密度：紧凑 / 适中 / 宽松，封面一行放几个。手机上从一行三个到一行两个。

  • 显示：可关掉作者、可关掉封面上的进度条。书架安静下来之后更像书库，不像仪表盘。

  • 封面进度条：读过的书在封面底部画一条，扫一眼就知道哪本在读。 书架顶部没有单独的「继续阅读」横排：那一条画的是下面网格里已经有的十本， 而「我读到哪了」现在由顺序回答——默认按阅读时间排，读过的自然在前面。

  • 搜索：输入即搜（防抖 250ms），带一键清空；回车立刻搜不等防抖。

  • 下拉刷新：在顶部再往下拉一次，手动重新拉取（刚扫完目录时用）。

  • 书库：书架右上角的 ▮▮ 打开，看的是 BOOKS_DIR 本身而不是目录库。 它有两个页面：预览（默认，这个文件夹里的书，可以点开读、可以把不在书架上的 一键加回书架）和文件（文件管理器）。

  • 离线优先：先画本地镜像再换成服务端数据，离线时书架照常可用； 离线下的排序规则与服务端一致，所以断网不会让书架重排。

书库

书架回答「我能读什么」，书库回答「磁盘上有什么」。两件事都需要，因为书籍记录里 从不带路径——「刚扫完目录，可为什么书架上没有这本书」这个问题，在书库之外 没有任何地方能回答。

书架右上角的 ▮▮ 打开。它是一个屏幕、两个页面：

  • 预览：这个文件夹里的书，用的是书架的网格。不在你书架上的那几本， 封面角上有一个「加入书架」，按一下就把那个文件对应的书加回来—— 这就是上面那个问题的一条出路，而且是一步。
  • 文件：下面那套文件管理器。

两页共用面包屑、位置和 URL（#/library/files/<路径>），所以来回切是标签， Back 走的是「离开书库」而不是「切回上一个页面」。

文件页

  • 列的是挂载点本身，不是整理后的目录视图。面包屑可点，路径就是你 BOOKS_DIR 里的路径。

  • 列的是挂载点本身，不是整理后的目录视图。面包屑可点，路径就是你 BOOKS_DIR 里的路径。

  • 被扫描忽略的条目照样显示，只打一个「扫描忽略」标记。.trash、@eaDir 是设计上 不扫的；在界面上也把它们藏起来，就正好藏掉了读者正在找的那批文件。

  • 长按进多选，多选后才出现改名 / 移动到… / 删除。点一行是浏览，不是选择： 在一个上万文件的 NAS 书库里滚动，每行都挂一个删除按钮，离误删只有一次手滑。

  • 删除要再确认一次，且会说明「不进回收站、需要重新扫描」。

  • 只读挂载上写操作按钮直接不出现。:ro 是文档里推荐的部署方式，所以「这个页面只能看」 是常态；给一排按下去必然 403 的按钮，只会教读者不信任界面。

  • 上传：直接往当前目录传书。.zip / .cbz 当合集解开（单层包裹目录抹平，更深的树保留， 因为漫画的卷结构就是深层目录）。重名可选保留两份 / 跳过 / 覆盖 / 整批拒绝。

  • 批量管理：长按多选后可以一次改一批的元数据、一起从书架拿掉、一起移动。 改元数据和「从书架拿掉」都不动磁盘——remove 只是 hidden = 1，书还在索引里，放得回去。

写操作都做两件事：

  • 走 rename 而不是复制删除。同挂载点改名不动字节、不动 mtime，扫描器视为未变化， 书籍主键（identifier + 内容哈希）因此不变——进度和笔记都还在。 索引同时被指向新路径，不用等下一次扫描。
  • 先探测挂载是否可写（真建一个临时目录再删），再动手。drwxr-xr-x 的只读 bind mount 看起来可写，写起来 EPERM；探测一次比从 EROFS 栈里推断便宜得多。

敢开这个页面，就等于接受「能改书库的人能改书库里的任何文件」——和 POST /library/scan 已有的信任级别一样。在这之上再叠一层按路径的权限只是安全表演。

书库扫描

  • 增量扫描：先用 mtime + size 快速判断，再用内容哈希确认。绝大多数文件在第一阶段就被跳过。
  • 目录挂载：递归扫描挂载目录，自动跳过 .git、@eaDir、#recycle 等目录，不跟随符号链接。
  • 自动扫描：默认每 30 分钟全量、每 60 秒增量轮询。设 SCAN_INTERVAL=0 / WATCH_INTERVAL=0 可关闭。
  • 手动触发：POST /api/v1/library/scan（管理员）。

一个文件夹什么时候是一本书

漫画在 NAS 上的常见存放方式是「一个系列一个文件夹，下面按卷分」。判定规则很短， 但它决定了一本书会不会从书架上消失：

  • 文件夹里有别的格式的书文件（epub / pdf / txt / 单张图）→ 这是书架，不是漫画。 夹着一本书的目录绝不会因为图片多就把那本书吞掉；这条规则会递归到嵌套层级。
  • 否则，有两页以上的散图或压缩包 → 这个文件夹就是一本漫画。
  • 或者，卷子目录与卷压缩包并列（第01卷.cbz 与 第02卷/ 同时存在）→ 整卷系列，算一本。

卷压缩包里的页按「一个压缩包一页」计，包内页码由 /assets?ref=page:卷:页 寻址； /books/:id/file 服务的路径与 manifest 列出的完全一致。

书籍主键：为什么不按文件路径

书籍主键是 sha256(dc:identifier + 文件内容哈希)，不是文件路径。

用路径做主键的话，用户重命名或移动一下文件，阅读进度和笔记就会全部丢失—— 这是自建书库产品最常见的差评来源。当前设计下：

  • 重命名 / 移动文件 → 主键不变，进度和笔记保留 ✅
  • 同一本书的多份副本 → 自动合并成一条书架记录 ✅
  • 重新编码过的同名文件 → 视为不同副本，不会被误认 ✅

元数据优先级

1. 用户手动修改      最高，永不自动覆盖
2. EPUB 内嵌元数据    次高，扫描不会覆盖手动修改
3. 在线刮削 provider  只填补空缺字段，标注来源，可一键撤销
4. 文件名解析        最弱，仅在以上都缺时使用

在线刮削是可插拔的 provider 机制。第一版只做内嵌元数据 + 文件名解析 + 手动补全， 不接任何在线源——避免引入网络依赖与限流问题，也避开豆瓣的合规风险。 后续接入 Google Books、Open Library 时，实现 MetadataProvider 接口注册即可，索引层不用改。

手动修改存在独立的覆盖层，扫描永远碰不到它。撤销单个字段用 DELETE /api/v1/books/:id/metadata/:field，会回落到内嵌值。

多用户

单个部署实例内的多账号，适合家庭或小圈子。两级权限：

  • admin：创建/停用账号、触发扫描、查看实例信息
  • member：只能看自己的书架、进度和笔记

每个账号有独立的书架、阅读进度、笔记与高亮。新账号注册后自动看到整个共享书库， 不需要逐本添加。

阅读体验：一次只取一章

打开一本书是一次请求。服务端的 manifest 默认只带第一个窗口的条目， 不是整本书的清单——一本 1200 章的全集打开时只传一个窗口，翻到下一章才取下一章。

  • 分窗：/items?group=N 一次返回一个窗口（epub 是 40 章，漫画是一卷）。 每个 group 自带 offset，所以客户端拿到单窗也能定位到全书位置。 省略 group 等于 group=0；要完整结构用 ?group=all。
  • 目录是目录：/toc 返回真正的完整目录。它和分窗是两件事：分窗是传输边界， 目录必须完整才有用。把它们合成一个接口，目录就会显示成「第 1 章 – 第 40 章」 ——服务端的分页边界漏进 UI。
  • 章节按路径寻址：items[].href（xhtml:OEBPS/ch1.xhtml）是章节身份。 不按下标寻址：分窗返回的是 spine 前缀，按下标算出的章节在完整 spine 里指向另一章。
  • HTTP Range：PDF 跳页、漫画跳卷、断点续传靠它。压缩方式为 stored 的条目 可字节定位；deflate 的会诚实上报 Accept-Ranges: none。 尾部范围（bytes=-N）无法靠前向流跳过，大文件时会退化为整包响应而不是空读全文件。
  • 目录跳转跨窗口：点第 900 章会先取窗口 22，而不是「什么都没发生」。 章节 id 是唯一跨窗口稳定的身份，进度也存它。

客户端三态

服务端是唯一真相源，客户端只做「渲染 + 缓存」。客户端有三种状态：

状态 行为
局域网直连 正常同步
公网可达 正常同步
完全离线 读本地缓存，恢复后合并进度

同步的只有轻量数据：书架元数据、阅读进度、笔记、高亮。书文件不走同步。

两端的关系

Android 端不重写渲染。它是一个 Kotlin 原生外壳，只负责文件缓存、手势、账号与书架， 渲染复用同一份 web/ 产物。原因很直接：排版策略一旦出现两份实现，就一定会分叉， 而「忠于精排」正是这个产品的差异点。外壳只做 WebView 做不到或做不好的事：

  • 连通性：WebView 里的 navigator.onLine 只要有网卡就说「在线」—— 连上一个没有出口的 Wi-Fi 时它会骗人，客户端于是转圈而不是读缓存。 Android 侧用系统的 NET_CAPABILITY_VALIDATED 判断。
  • 稳定的设备名：UA 里的型号会随 Chrome 升级变化，作为「上次在哪个设备读的」标签不可靠。
  • 原生提示：一行 Kotlin 的 Toast，不用在 Web 层造一套通知 UI。

还有一条刻意的例外：固定版式的整页图由原生画。一页漫画或一张扫描图在 WebView 里 要走完解码、样式布局、合成三次开销，而屏幕上的结果和 ImageView 一模一样； 对一章文字这些都是必要的，对「把这张图画满屏」则全是白付的。 规则是「只画整页图，且全有或全无」——画不了就交给 WebView，绝不出现空白页。 EPUB 永远留在 WebView：文字排版是差异点，只能有一份实现。

离线合并语义

进度和笔记都带 updatedAt，冲突按 last-writer-wins 解决：

  • 离线设备重连后推的旧数据不会回滚你在别处读到的新进度
  • 笔记删除是**墓碑（tombstone）**而不是硬删除，所以离线设备无法让已删除的笔记复活
  • GET /api/v1/sync?since=<上次的 serverTime> 只返回增量，重连很便宜

配置

环境变量 默认值 说明
BOOKS_DIR /books 书库目录，只读挂载
DATA_DIR ./data 服务端写入目录，不能在 BOOKS_DIR 内
PORT 8080 监听端口
PUBLIC_URL 空 对外地址，反代后设置
SCAN_INTERVAL 1800 全量扫描间隔（秒），0 关闭
WATCH_INTERVAL 60 增量轮询间隔（秒），0 关闭
ALLOW_REGISTRATION false 是否允许公开注册
ACCESS_TOKEN_TTL 86400 访问令牌有效期（秒）
REFRESH_TOKEN_TTL 31536000 刷新令牌有效期（秒）
READER_TOKEN_SECRET 自动生成 签名密钥。留空则生成并持久化到 /data
LOG_LEVEL info 日志级别
CORS_ORIGINS 空 允许跨域调用的来源，逗号分隔。空表示反射任意来源
WEB_DIR ./web H5 客户端产物目录，镜像里已设好
TTS_URL 空 HTTP 朗读上游地址。不设则关闭 HTTP 朗读
TTS_TOKEN 空 转发给上游的 Bearer 令牌
TTS_VOICES_URL <TTS_URL>/voices 上游语音列表地址
TTS_TIMEOUT_MS 20000 单次合成超时（毫秒）
TTS_CACHE_BYTES 268435456 音频磁盘缓存上限，存放于 DATA_DIR/tts-cache；0 关闭

READER_TOKEN_SECRET 留空时会在首次启动生成并存到 DATA_DIR/token.secret。 只要 /data 还在，重启不会踢掉所有客户端。删掉 /data 会清空所有账号和进度。

故障排查

启动即退出：EACCES: permission denied, open '/data/token.secret'

fatal: Error: EACCES: permission denied, open '/data/token.secret'
    at loadOrCreateSecret (file:///app/dist/config/index.js:27:5)

/data 挂上了，但容器里的服务进程写不进去。服务端以非特权用户 reader （uid/gid 100:100）运行，而 /data 若是 bind mount（./data:/data）， 挂载点的属主来自宿主机目录，会覆盖镜像里构建时做的 chown——宿主机上 ./data 不存在时 Docker 会以 root:root 新建它，于是非特权用户写不了。 命名卷（named volume）继承镜像里的 chown，不受影响。

镜像的入口脚本已经会在启动时自动把 /data 的属主改成 reader 再降权运行， 所以正常用官方镜像不会遇到这个问题。仍然报错时按顺序检查：

  1. 拉的是最新镜像：docker compose pull && docker compose up -d。
  2. 自己加了 user: / docker run --user 覆盖了启动用户，去掉它。
  3. /data 所在文件系统不支持改属主（NFS / SMB / NTFS 挂载，如群晖的部分共享目录）， 此时给 READER_TOKEN_SECRET 设一个 ≥16 字符的随机串，服务端就不需要写密钥文件： 
    openssl rand -base64 48          # 生成一个
    在 compose 里加 READER_TOKEN_SECRET: "<上面的值>"。
  4. 手动修宿主机目录属主（Linux；群晖等 NAS 上 uid 可能不同）： 
    sudo chown -R 100:100 ./data

自建的镜像若来自 server/Dockerfile，注意 ENTRYPOINT 不能被覆盖，否则降权 那一步不会执行。服务端本身在写密钥失败时会直接报出「DATA_DIR 必须可写」 并给出一键修法，不会再只抛一个 errno。

让外网访问（内网穿透 / 域名 / HTTPS）

自部署最大的门槛在这里，所以单独说清楚。三种常见做法：

1. 只在局域网用（最简单） 不用做任何事，直接访问 http://<NAS的局域网IP>:8080。

2. 反向代理 + HTTPS（推荐） 用 Caddy 最省事，自动申请证书：

reader.example.com {
    reverse_proxy 127.0.0.1:8080
}

然后设置 PUBLIC_URL=https://reader.example.com，下载链接才会正确。

3. 内网穿透（没有公网 IP） 用 frp / Tailscale / Cloudflare Tunnel 任选一个。Tailscale 最简单： 在 NAS 和手机上装 Tailscale，直接用 Tailscale 分配的 IP 访问，不用配证书。

服务端设计上不依赖域名和 HTTPS，所以三种方式都能工作。但公网暴露时 务必套一层 HTTPS，否则令牌是明文传输的。

Android 客户端

APK 走 GitHub Releases / 侧载分发，不上商店。开源项目没有收入覆盖 Apple 的 99 美元开发者账号，所以 Android 先做、iOS 等有赞助再说（这条是设计文档 §5 定的）。

自己构建

# 1. 先把 H5 渲染层构建好并放进 assets
sh android/scripts/build-web-assets.sh

# 2. 构建 APK
cd android
./gradlew :app:assembleDebug
# 产物：android/app/build/outputs/apk/debug/app-debug.apk

# 想预置服务端地址（个人自用构建）：
./gradlew :app:assembleRelease -PdefaultServerUrl=http://nas.local:8080

不预置地址是刻意的：没有人知道你会用什么 IP 访问自己的 NAS， 所以首次启动时问一次、之后记住。

装好之后

打开 App → 填服务端地址（如 http://192.168.1.10:8080）→ 登录。 之后所有书和进度都跟着账号走，与浏览器端互通。

为什么允许明文 HTTP

主要部署场景就是局域网 IP，而私有 IP 拿不到证书。要求 HTTPS 等于把用户挡在门外， 这正是设计文档里说的「部署门槛是最大的获客阻力」。 但对公网暴露时请务必套一层 HTTPS，否则令牌是明文传输的。

从源码开发

# 服务端
cd server
npm install
npm test            # 137 个测试用例
npm run typecheck
npm run dev         # 开发模式，热重载

# 指向一个测试书库
BOOKS_DIR=/tmp/books DATA_DIR=/tmp/data npm run dev

# 客户端（另开一个终端）
cd web
npm install
npm test            # 336 个测试用例（307 vitest + 29 node:test）
npm run dev         # http://localhost:5174，自动把 /api 代理到 8080
npm run build       # 产出 web/dist，服务端会在 / 上直接托管

项目结构

server/src/
  config/      运行时配置（含「DATA_DIR 不得在 BOOKS_DIR 内」的启动断言）
  db/          SQLite schema 与访问层（node:sqlite，无原生依赖）
  indexer/
    identity.ts   书籍主键：dc:identifier + 内容哈希
    filename.ts   文件名解析（保守策略，宁可留空不猜错）
    metadata.ts   EPUB/PDF 元数据与封面提取
    scanner.ts    增量扫描、变更检测、清理
  providers/   可插拔刮削 provider 接口
  services/
    users.ts     账号、角色、令牌
    shelf.ts     书架查询、手动覆盖层
    sync.ts      进度/笔记同步与冲突合并
    merge.ts     元数据优先级链
  http/        Fastify 路由（含 CORS 与 H5 静态托管）

web/src/
  api/         服务端契约与请求层（令牌刷新在这里，全局只做一次）
  core/        平台抽象、同步引擎
    platform.ts      两端共同接口：传输、存储、连通性
    sync.ts          待发送队列 + 增量拉取 + 退避重试
    android-platform.ts  Android 侧的实现（很薄）
  store/
    offline.ts   本地镜像与待发送队列
    idb.ts       IndexedDB 包装，不可用时降级到内存
  formats/     格式层：拆包、编码识别、章节切分
    epub.ts      OPF/spine/nav 解析、资源重写
    txt.ts       编码探测 + 章节推断 + 超长分段
    comic.ts     CBZ / 图片目录
    detect.ts    魔数优先的格式识别
  ui/
    router.ts        路由：fragment ↔ route，以及应用自己的屏幕轨迹
    mount.ts         组件树与类式屏幕之间唯一的接缝
    toolkit.tsx      按钮/分段控件/开关/面板这些原语
    icon.tsx         图标组件（字体的唯一使用点）
    icon-names.ts    码位表，由生成器写出，不要手改
    vendor/preact.ts 框架的唯一入口（换版本/换实现只改这一处）
    *-screen.tsx     书架、登录、书库、阅读器（铬层）
    reader-chrome.tsx  阅读器的顶栏/页脚/目录/设置/朗读条
    reader-view.ts   分页、滚动、手势、定位（命令式，零框架）
    locator.ts       阅读位置格式
    shadow.ts        书的样式与 App 样式隔离
    resources.ts     资源按需解出，不预展开
  styles/
    reader.css         ← 干预策略都在这里，注释说明每条为什么必要
    reader-icons.ttf   图标字体（生成物，见 tools/icons/）
  tools/icons/      图标字体的生成器：描边路径 → 字体

android/app/src/main/java/cool/cnb/reader/
  MainActivity.kt            单 Activity，只做三件事
  web/WebHost.kt             WebView 配置与资源装载
  bridge/ReaderBridge.kt     暴露给 JS 的原生方法
  bridge/ConnectivityMonitor.kt  真正的连通性判断

技术选型说明

  • Node.js 22+（engines: >=22，内置 node:sqlite 与 scrypt 所在的最低版本）+ TypeScript + Fastify：单容器体积可控（约 150MB），迭代最快， node:sqlite 与 scrypt 都是内置模块，没有原生编译依赖——这让镜像构建稳定， 也兑现了「一条命令跑起来」。
  • 不用 better-sqlite3 / argon2 / bcrypt：它们需要构建时工具链（make、gcc）， 会把镜像撑大并让安装变脆。
  • SQLite 存 metadata，不存书：schema 里的 books 表可以随时重建，书本身才是真相源。

客户端技术选型说明

  • UI 层用 Preact + hooks，排版层不用框架：这条线划在「有没有布局要量测」上。 书架、登录、书库、阅读器的铬层（顶栏/页脚/目录/设置面板/朗读条）是状态与 事件，用组件描述；而阅读舞台——分页、注入文档、shadow root、量测列宽——仍然是 命令式 DOM，一个虚拟 DOM 加在代码和它要量测的布局之间，恰好是这个产品最不该透过它 去调试的东西。ReaderScreen 把这两半拼在一个文件里：stage 节点由类持有并交给 ReaderView，其余全部是 ChromeState 的函数。 选型对比见 docs/architecture.md §8；产物是一个 252KB（gzip 79KB）的单文件 bundle。
  • 图标是一个自带的字体：37 个字形、16KB、随 bundle 走。理由和生成方式见 docs/ui.md §1。一句话：字体把字形变成字符，它继承 color 和 font-size，因此没有可以漂移的几何——而三十个内联 SVG 组件里，颜色、尺寸、线宽 每一项都是单个字形可以漂移的位置。
  • 界面用 URL 表达：每个屏幕都有地址——#/shelf、#/book/<id>、#/library/<路径>。 用 fragment 而不是路径，是因为同一份产物要被 WebView（appassets.androidplatform.net， 没有服务端）和 reader 服务端（没有客户端路由回落）同时加载，只有 fragment 在两边都成立。 换来的是：一本书可以分享、可以收藏、刷新不丢；Android 返回手势和浏览器返回键 走应用自己的屏幕轨迹；走进书库子目录用 replace，所以返回是退出管理器而不是逐层退目录。 带着链接进来而尚未登录时，链接会等在登录页后面，登录后直接落到那本书。
  • 单文件 bundle、相对路径：产物要被两个宿主消费——服务端托管给浏览器、Android 打进 assets。file:// 或 WebView 里加载同源分片会踩平台特异性，所以 inlineDynamicImports 打成一份，base: './'。这条约束也是选 Preact 而不是 React/Vue 的关键： preact/compat 不进包、没有 react-dom，只引入 preact 与 preact/hooks， 两个模块压缩前合计约 15KB。
  • 不注入 reset 样式：见 web/src/styles/reader.css 顶部。整个产品的差异点是「忠于 出版方的排版」，而一份 reset 正好会抹掉出版方的字体、缩进和行距。 可调项全部是可继承的自定义属性，默认值是 inherit——「关」的意思是「不动它」， 不是「用我们的默认值」。
  • 书的样式装进 shadow root：书里一条 p { color: red } 不能改到书架。 用 iframe 也能隔离，但每次换章要重建文档，会丢滚动位置、在 Android 上多花几倍内存。
  • 书的内容不允许联网：章节里所有本地引用在加载时被改写成内部 reader-res: 协议， 由渲染层从内存里的资源表解出。绝对 URL 原样保留，然后被 CSP 挡掉—— 一本来路不明的书不能把阅读行为报到远端。

API

所有业务接口在 /api/v1 下，用 Authorization: Bearer <token> 认证。 响应错误统一为 { "error": { "code": "...", "message": "..." } }。

服务端 API 承诺长期向后兼容：自部署用户不会及时升级，破坏性变更只允许 「加新字段 / 加新端点」，不允许改已有字段语义。

端点列表

公开

  • GET /api/v1/health — 健康检查
  • GET /api/v1/instance — 实例信息（是否开放注册、账号数）
  • POST /api/v1/auth/register — 注册（仅首次或开启 ALLOW_REGISTRATION）
  • POST /api/v1/auth/login — 登录
  • POST /api/v1/auth/refresh — 刷新令牌

需认证

  • GET /api/v1/auth/me
  • POST /api/v1/auth/password
  • POST /api/v1/auth/logout
  • GET /api/v1/books — 书架列表，支持 search author series tag format path sort page
  • GET /api/v1/books/:id
  • GET /api/v1/books/:id/manifest — 打开一本书的全部所需：文件清单 + 可寻址结构，一次请求
  • GET /api/v1/books/:id/items — 可寻址结构（章节/页/卷），?group=N 取单卷
  • GET /api/v1/books/:id/toc — 完整目录，与分窗分开
  • GET /api/v1/books/:id/assets?ref=<ref> — 单个资源（章节文档、页图、字体）
  • GET /api/v1/books/:id/file?path=<rel_path> — 目录书的单页，只认 manifest 列出的路径
  • GET /api/v1/library/formats — 本实例支持的格式清单
  • GET /api/v1/books/:id/content — 书文件流
  • GET /api/v1/books/:id/cover — 封面
  • PATCH /api/v1/books/:id/metadata — 手动补全元数据
  • DELETE /api/v1/books/:id/metadata/:field — 撤销单个字段
  • GET /api/v1/library/facets — 作者/系列/标签/格式聚合
  • GET /api/v1/library/continue — 继续阅读
  • GET /api/v1/sync?since=<ms> — 增量拉取
  • POST /api/v1/sync — 批量合并
  • GET/PUT /api/v1/sync/progress/:bookId
  • GET /api/v1/notes / POST /api/v1/notes / DELETE /api/v1/notes/:id

书库（读写 /books；挂载只读时任何写操作返回 403 READ_ONLY_MOUNT）

  • GET /api/v1/library/browse?path=<相对路径> — 列一个目录，带面包屑与标记
  • POST /api/v1/library/browse/move — 移动到另一个目录
  • POST /api/v1/library/browse/rename — 改名
  • POST /api/v1/library/browse/mkdir — 新建文件夹
  • POST /api/v1/library/browse/delete — 删除（递归）
  • POST /api/v1/library/browse/metadata — 批量改元数据（路径可以是目录，等于目录里每本书）
  • POST /api/v1/library/browse/shelf — 批量加入书架 / 从书架拿掉（只动 user_books，不动磁盘）
  • POST /api/v1/library/upload — 上传书籍（multipart；.zip/.cbz 按合集解开）
  • GET /api/v1/library/upload — 挂载是否可写，客户端在开始传之前先问

管理员

  • POST /api/v1/library/scan
  • GET /api/v1/library/scan
  • GET /api/v1/library/stats
  • GET/POST/PATCH /api/v1/admin/users
  • GET /api/v1/providers

范围边界（第一版）

做：目录挂载扫描、元数据刮削、两级权限、同步 API、Docker 单容器、Android 客户端、EPUB 精排、PDF 保底、按书离线缓存。

不做：在线书城、iOS、桌面端、社交、AI 问答、全格式转换、移动端批注输入。

.cbr / .rar 不在支持列表里——它需要 RAR 解码器，而当前依赖树刻意不含任何原生模块。

已知边界

写在明处，避免预期错位：

  • PDF 只做保底可读：不解析页数、书签，也不重排。页数上报 null 而不是猜一个数字 —— 猜错会让客户端的进度条错乱，比没有更糟。
  • 文本不做精品排版：TXT 按行渲染，不折行重排、不调字号。精品排版是 EPUB 的承诺。
  • 不做全格式转换：不把 epub 转 pdf、不把 txt 转 epub。
  • ZIP 不支持 ZIP64 / 加密 / 分卷：超限会明确报错，不会静默解出坏数据。
  • 漫画目录的嵌套有上限：卷目录下面还有目录时会继续往下收页（文件系统里读到第 4 层为止）， 再深会把一个杂乱目录变成几千页的巨型漫画。图片目录里内嵌的压缩包不再展开，一个压缩包算一页。 页序是真自然序（1, 2, 10，不是 1, 10, 2），排错不是观感问题，是故事被静默打乱。
  • 没有内置 HTTPS 与限流：给反向代理留位置，不重复造轮子。

许可

AGPL-3.0。选择 AGPL 而非 GPL：自部署产品最怕别人拿去做闭源付费服务， AGPL 的网络分发条款正好卡住这条路径（Kavita、Audiobookshelf 用的 GPL-3.0 更松一档）。

贡献

欢迎提交 Issue 和 PR。请先跑通 npm test，并为新行为补测试。

Reference in new issue View Git Blame Copy Permalink
S
Description
Reader - book source reading service
Readme AGPL-3.0
26 MiB
0 Stars 1 Watchers 0 Forks
Languages
TypeScript 77.7%
JavaScript 11.2%
CSS 7.4%
Kotlin 3.2%
Shell 0.2%
Other 0.2%