hectorqinandClaude Opus 5.5
120827bad6
Audit of README, docs/, android/README.md, android/contract.md and CLAUDE.md against the current server, web and Android code: V3 navigation and settings locations, Docker Hub release images, GitHub clone URL and CI, missing API endpoints and error codes, architecture of lazy chunks/themes/sources, media pages and routes, the Android bridge contract, and the new file-management and member-upload permissions. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
9.8 KiB
使用手册
本页介绍安装后的日常使用。部署参数见配置指南，协议细节见 API。
书架与书库
- 书架是当前账号的阅读列表，可筛选、排序、调整密度并查看阅读进度。顶部可按「全部 / 在读 / 想读 / 已读」筛选（手机上可左右滑动切换），「分组」按系列或标签筛选。每本书的「⋯」菜单可标记想读、在读、已读，清除标记或从书架拿掉；未手动标记时按进度判断在读或已读。
- 书库按挂载目录浏览本地书籍，可将书加入书架。
- 文件管理仅供管理员检查磁盘目录。挂载可写且目录权限允许时，可上传、改名、移动、删除和新建目录。
- 上传书籍：普通成员没有文件管理；管理员在「我的 → 系统设置 → 服务配置 → 书库」开启「允许成员上传书籍」（默认开启）时，成员可在书库浏览页头部点「上传书籍」，把书传到当前文件夹。成员只能新增书籍文件：不支持的格式会被跳过，
.zip/.cbz按漫画压缩包原样保存不解包，重名时保留两份，不能覆盖已有文件。
从书架移除只改变该账号的书架记录，不删除书文件。文件管理中的删除会修改磁盘，请按界面确认提示操作。书籍的改名或移动按已有身份更新路径，保留阅读记录。
管理员上传 .zip/.cbz 时会作为合集解包，保留必要的目录层级。单纯想把 CBZ 作为书籍扫描时，也可以直接把文件放到宿主机书库目录。重名上传支持保留两份、跳过、覆盖或拒绝整批，具体错误语义见 上传 API。
支持格式
| 格式 | 日常使用 |
|---|---|
| EPUB | 保留出版方排版、内嵌字体、目录、脚注、竖排和振假名等内容 |
| TXT | 自动识别 UTF-8、GB18030、Big5、UTF-16，支持手动切换编码和章节推断 |
| CBZ / ZIP | 按自然顺序展示页面，支持漫画分页 |
| 图片目录 | 将符合条件的图片目录作为漫画书，支持卷结构 |
| 基础查看，不解析成可重排正文；功能取决于浏览器或设备查看器 |
.rar/.cbr 不支持；ZIP64、加密和分卷压缩包不支持。reader 不提供 EPUB、TXT、PDF 之间的通用转换。
扫描与元数据
默认每 60 秒自动检查书库变化，服务启动时也扫描一次；管理员可在「我的 → 系统设置 → 服务配置 → 扫描设置」调整间隔（0 关闭）。扫描先比较大小和修改时间，再按需计算内容哈希。.git、@eaDir、#recycle 等目录被跳过，符号链接不跟随。
图片目录会结合图片、卷目录和压缩包结构识别。目录中包含其他书籍文件时，不应将这些书吞并为一个漫画目录；目录识别和分页资源规则见架构及 API。
书籍身份与内容有关，不直接依赖文件路径。移动或重命名通常保留身份，相同内容副本会合并；修改文件内容可能改变识别结果。
手动元数据覆盖保存在数据库中，优先于书内信息和文件名解析，重新扫描不会覆盖手动值。撤销手动字段后回到提取值。本地书籍当前没有内置在线元数据抓取服务；影音资料匹配见影音手册。
阅读设置
字号、主题和界面设置按设备保存；阅读进度和笔记随账号同步。
重新打开书籍时会比较本机与服务端进度，采用更新时间较新的位置；离线或服务端暂时不可达时使用本机记录。切到后台会先保存待写入的位置再尝试同步，关闭页面仍受浏览器生命周期限制。出现“阅读位置保存失败”时先保持页面打开，检查设备可用空间后重试，避免刷新丢失尚未保存的记录。
| 设置 | 作用 |
|---|---|
| 分页 / 滚动 | 按屏翻页或连续阅读 |
| 字号、行距、页边距、对齐 | 调整正文，部分设置可选择沿用原书 |
| 字体 | 在原字体栈之前加入选定字体 |
| 纸色 | 跟随主题，或选择白纸、暖黄、浅绿、灰调、夜间；可设置应用为深色时换成主题的深色 |
| 主题 | 跟随应用或黑白灰；明暗可跟随系统、浅色或深色 |
| 亮度 | 界面叠加调暗，不等同于修改设备系统亮度 |
| 图片适配 | 固定版式内容完整显示或适宽 |
| 翻页方向 | 漫画等固定版式内容支持左右方向切换 |
| TXT 编码 | 自动识别异常时手动选择 |
点击正文中央可切换工具栏，左右区域翻页（可在设置中改为左进右退）；手机上分页模式可左右滑动翻页，页面跟随手指，快速划动或拖过约 30% 宽度后松手即翻页。也可使用目录跳转章节。工具栏、目录和设置面板覆盖正文，避免显隐时重新挤压正文布局。电脑端支持方向键、PageUp/PageDown；Android 可通过外壳处理音量翻页。
EPUB 章节按需加载，长书的目录与传输窗口分开处理，跨窗口跳转会先取相应章节。图标为 Lucide SVG，界面布局与交互规范见 UI 文档。
朗读
可使用三种语音来源：Android 系统 TextToSpeech、浏览器 speechSynthesis，或管理员配置的 HTTP 语音服务。
- 从当前位置或选区开始，按句朗读并高亮。
- 支持上一句、下一句、暂停、继续和停止。
- 可调整语速、选择可用语音；音调等选项由引擎能力决定。
- 可设置章末继续下一章或停止。
没有中文语音时，先检查设备安装的语音包和当前引擎。需要服务端语音时，参照 HTTP 朗读配置。
OPDS 书库
从书架的「书源」入口进入书源中心；管理员可在「书源管理」中添加 OPDS 服务地址。需要认证时配置当前账号的凭据。打开来源可浏览、搜索并获取书籍，下载完成后加入书架。也可以通过只读 OPDS 服务把 Reader 中的文件书提供给外部阅读器。
影音入口
打开站点默认进入「首页」，可继续最近的阅读与播放。底部（宽屏为左侧）导航有首页、书架、影音、我的四个标签；宽屏侧栏的搜索框可同时搜索书籍和影音。「影音」内通过频道切换影视、音乐和有声书，手机上可左右滑动切换分类。阅读与影音共用「我的 → 外观与主题」中的主题；影音浏览密度与播放偏好在「我的 → 影音浏览」「我的 → 播放」中设置。
管理员可添加本地目录或 OpenList 媒体库，配置权限、扫描与刮削；用户浏览已授权的内容并播放。建库、歌词、字幕、队列、倍速及睡眠定时见影音使用说明。
多用户与离线
首个账号是管理员，后续成员默认由管理员创建。每个账号的书架、进度、笔记和高亮独立。阅读界面参数属于当前设备，不随账号覆盖其他设备的设置。
离线时可使用已经缓存的内容，重新连通后同步阅读状态。在阅读器底部「工具 → 离线缓存」可下载TXT 的指定范围，或下载完整 EPUB、PDF、CBZ；自定义目录的 TXT 下载完整文件。任务支持暂停、继续和取消，关闭面板会暂停，已下载内容保留。默认设备账号配额为 256 MiB，可调整或按书清理；不自动淘汰，也不删除原书、进度、笔记。服务端缓存与当前设备缓存独立，只有本设备完成下载的内容才能保证断网读取。图片目录暂不支持整书下载。
进一步阅读
阅读工具：搜索、笔记与内容整理
- 书内搜索：打开「工具 → 书内搜索」，输入文字后逐章检索，最多展示 200 个命中，支持停止。点结果定位并高亮原文，再次打开工具可返回搜索前的位置。支持 EPUB/TXT；扫描 PDF 和图片不提供 OCR。未缓存章节需要联网。
- 高亮和批注：先在正文选择文字，再打开「工具 → 笔记」，选择颜色并保存。填写批注即可形成笔记；无选区也可保存当前位置书签。支持编辑、删除、点击回正文，联网后沿用账号同步。原文变化导致定位不唯一时不会猜测位置。
- 多级目录：EPUB nav/NCX 保留三级及更深层级和章内锚点，有子项的目录可展开、折叠，选择章节后关闭面板。
- 内容整理：先选择文字，在「工具 → 内容整理」填写替换内容，留空可以过滤选区。修改以个人覆盖层保存在服务器 DATA_DIR 的 SQLite 中，不修改书籍文件。支持逐项移除和撤销上一次修改；跨设备并发保存冲突时需重新打开书籍。保存需联网，已缓存规则可离线应用。
- TXT 目录：可选择中文章回、Chapter、方括号模板，或输入自定义标题前缀，预览后应用；留空恢复默认识别。规则匹配不超过 80 字的标题行，不执行任意正则。重新划分章节后从首章打开，旧笔记保留但可能需要重新定位。预览需要完整 TXT 文件。
- 朗读检测：按当前引擎试听。HTTP 引擎先实际请求合成，分别提示未配置、鉴权失败、超时、非音频和空音频。关闭面板或点击停止会释放试听；浏览器仍可能要求允许声音播放。
电纸书
阅读设置中的“应用电纸书预设”会切换为浅色、分页和无翻页动画，仅影响当前设备；其他选项仍可调整。该预设不控制电纸书全刷或硬件残影。浏览器验收范围与 OPDS/WebDAV 后续边界见 生态互通方案。