hectorqin
7bff77eaf8
Add reliable reading progress, verified backup and restore, reading tools, offline downloads, source quality checks, personal credential status, OPDS serving and verified WebDAV backup uploads.
6.9 KiB
入门指南
本文带你完成 Docker 部署、注册账号和读取第一本书。直接从源码运行请看开发指南。
本指南对应当前 Node 版工作区。CI 发布 main（开发分支）和提交短哈希标签，没有发布 latest 的配置；标签可用性以对应构建成功为准。部署后核对版本，长期使用建议固定提交标签。旧 Java 版镜像、/storage 数据和 Legado JSON 书源不与新版直接兼容。
1. 准备环境
- 安装 Docker Engine 或 Docker Desktop，以及 Docker Compose 插件。
- 准备一个书籍目录和一个独立的数据目录。
- 确保主机的
8080端口可用；也可修改 Compose 左侧端口，例如8090:8080。
容器同时提供 API 和 Web 界面，无需单独部署前端。以下命令从仓库根目录执行。
2. 获取部署配置
git clone https://cnb.cool/hectorqin/reader.git
cd reader
编辑 docker-compose.yml，把宿主机书籍路径替换为自己的路径：
volumes:
- /path/to/your/books:/books:ro
- ./data:/data
例如 Linux 使用 /srv/books:/books:ro，Windows Docker Desktop 可使用 "D:/books:/books:ro"。相对路径 ./data 位于 Compose 文件所在目录。
| 目录 | 用途 |
|---|---|
/books（BOOKS_DIR） |
现有书籍文件 |
/data（DATA_DIR） |
数据库、账号、阅读记录、封面缓存、上传暂存、下载文件和插件数据 |
DATA_DIR 不能与 BOOKS_DIR 相同，也不能位于其中；启动时会检查这项约束。元数据保存在数据目录，不会在书旁生成封面或 .calibre 文件。
选择只读或可写书库
- 只浏览和阅读：保留
:ro。通过宿主机或 NAS 放入新书，等待扫描。 - 在网页管理文件：改为
:rw，并确保服务进程对该目录有写权限。管理员可以在书库文件管理页上传、改名、移动、删除和新建目录。
只读书库不会妨碍进度、笔记或书架保存，这些数据写入 /data。挂载和权限的详细说明见部署配置。
3. 启动与首次登录
docker compose up -d
docker compose ps
docker compose logs --tail=100 reader
打开 http://localhost:8080；在另一台设备上使用 http://<服务器IP>:8080。
- 注册第一个账号，该账号自动成为管理员。
- 等待初次扫描，在书架或书库中打开一本书。
- 为家人或其他成员创建账号。首个账号创建后默认关闭公开注册。
如需开放后续注册，在 Compose 的 environment 中设置 ALLOW_REGISTRATION: "true"，然后执行 docker compose up -d。
健康检查地址为 /api/v1/health。若启动失败、目录为空或无法写入，请看故障排查。
若镜像尚未发布或无法拉取，可从当前检出的源码构建：
docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build
此方式仍需能下载 Node 基础镜像和 npm 依赖。后续管理该部署时继续使用同样的两个 -f 参数。发布镜像部署可在 .env 设置 READER_IMAGE=cnb.cool/hectorqin/reader:<已发布的提交标签> 固定版本。
不使用 Compose
在 Linux/macOS 的 POSIX shell 中，也可使用绝对路径启动容器：
mkdir -p ./data
docker run -d --name reader --restart unless-stopped \
-p 8080:8080 \
-v /path/to/your/books:/books:ro \
-v "$(pwd)/data:/data" \
cnb.cool/hectorqin/reader:main
Windows 推荐使用上面的 Compose 配置，避免不同 shell 的路径和换行语法差异。
4. 添加书籍与来源
本地书籍
把 EPUB、TXT、PDF、CBZ/ZIP 或漫画图片目录放到挂载的书库中。默认每 30 分钟定时扫描，每 60 秒检查变化；管理员也可手动触发扫描。可写挂载下，上传入口位于管理员文件管理页。
书架显示可阅读的书籍；书库按磁盘目录浏览。从书架移除书籍与删除磁盘文件是两种不同操作。详见使用手册。
OPDS
管理员在「书源」添加 OPDS 来源并设置服务地址。需要认证时填写当前账号的来源凭据。打开来源后可浏览或搜索目录，获取书籍并加入书架。
外部书源插件
通用来源插件不是 Legado JSON 解析器。旧版书源 JSON 或订阅链接不能直接当 npm 包安装；只有明确声明支持该格式的独立插件才能提供兼容，是否支持以该插件说明为准。尚无适用插件时，请使用本地书库或 OPDS。
管理员打开「书源 → 插件管理」，确认信任插件代码后，输入 npm 包名（可带版本或标签），或上传 npm pack 生成的 .tgz 安装包（最大 100 MiB），安装成功后自动启用。无需手动部署包目录。随后在「书源管理」选择插件提供的来源类型创建实例，从该实例的管理入口配置。一个插件可创建多个独立实例；具体功能与运行依赖由插件声明。
插件拥有服务端进程权限，请只安装可信代码。服务端需要 Node.js 和 npm；npm 包及未打包的依赖需要联网下载。安装期间禁用 npm 生命周期脚本，插件应预先构建并打包运行所需文件。所有安装文件与临时文件保存在 DATA_DIR，不会写入书库目录。
5. 更新与备份
推荐使用离线备份与恢复工具，可验证文件清单和数据库完整性，并恢复到新目录。首次从没有维护命令的旧构建升级时，仍可按以下停机复制方式保留完整数据。
更新前备份书籍目录和数据目录。对 SQLite 采用简单文件备份时，先停止服务，再复制完整 /data（包括数据库及其辅助文件），避免复制运行中的不一致状态。
docker compose stop
# 在此备份宿主机上的书籍目录和 ./data
docker compose pull
docker compose up -d
不要删除数据目录：其中包含账号、阅读记录、签名密钥和插件状态。插件包需单独升级；替换包前先在界面停用插件。
从旧 Java 版迁移时，先保留其完整备份，使用独立的新数据目录部署新版。本地书文件可挂载到新书库；账号、书架、进度、笔记和旧书源配置目前没有自动迁移工具，不要直接用旧 /storage 覆盖新 /data。源码构建部署更新时使用两份 Compose 文件重新构建，不能仅执行 pull。