企业官网建设流程全解析

ReadMeABook 是一款全自动有声书请求与下载引擎，而它的E-book Sidecar（电子书旁挂）功能更进一步：每当一本有声书下载入库，系统会顺手从 Shadow Library（Anna's Archive）或 Prowlarr Indexer 搜索并下载对应的 EPUB/PDF 电子书，与有声书放在一起，让你一次请求、两份收藏。本文将带你快速完成配置与理解其工作原理。

什么是"旁挂"：Sidecar 工作机制

传统流程里，下载一本有声书和找一本电子书是两件独立的事。ReadMeABook 的 Sidecar 机制把二者绑定为"父子请求"：

• 有声书请求是父请求，电子书请求是子请求（type: 'ebook'），拥有独立的进度、状态和错误处理；
• 有声书文件整理完成后，系统自动创建电子书请求，全程不阻塞有声书流程；
• 电子书下载成功后，文件会被复制到有声书所在目录，命名为[书名] - [作者].epub，请求状态进入downloaded终态；
• 界面上电子书请求带有醒目的橙色徽标，方便与有声书区分。

两种电子书来源：Shadow Library 与 Indexer 搜索

Sidecar 支持两类来源，按优先级依次尝试（详见 ebook-sidecar.md）：

1️⃣ Anna's Archive（Shadow Library，直连 HTTP）

• 优先用ASIN 精确搜索（如asin:B09TWSRMCB），找不到再退化为"书名 + 作者"标题搜索；
• 通过 MD5 详情页获取 Slow Download 直链，由 direct-download.processor.ts 完成下载并跟踪进度；
• 该站点有 Cloudflare 防护，可选配置FlareSolverr（无头浏览器代理）来绕过。

2️⃣ Indexer Search（通过 Prowlarr）

• 当 Anna's Archive 未启用或无结果时，系统通过 Prowlarr 搜索电子书分类（默认7020 Books/EBook）；
• 结果按电子书专用评分算法排序：标题/作者匹配 60 分、格式匹配 10 分、体积质量 15 分、做种数 15 分，超过 20 MB 的文件会被直接过滤；
• 复用有声书的 download-torrent.processor.ts，经 qBittorrent（种子）或 SABnzbd（Usenet）下载，且下载后保留做种，尊重你的做种限制。

快速配置：三步开启 E-book Sidecar

配置入口位于Admin → Settings → E-book Sidecar标签页（EbookTab.tsx），共三个区域：

第 1 步：Anna's Archive 区域

第 2 步：Indexer Search 区域

开启ebook_indexer_search_enabled开关即可；各 Indexer 的电子书分类在Settings → Indexers → 编辑 Indexer → EBook 标签中按 Indexer 单独配置。

第 3 步：通用设置

💡 提示：未启用任何来源时，自动抓取会自动关闭，但管理端的手动 Fetch Ebook 按钮依然可用，适合只按需取书的场景。

FlareSolverr 快速部署（可选，用于绕过 Cloudflare）：

docker run -d --name flaresolverr -p 8191:8191 ghcr.io/flaresolverr/flaresolverr:latest

然后在 Sidecar 设置中填入http://localhost:8191。首次请求约 5–10 秒，之后每页 2–5 秒，整本书约 15–30 秒。

自动抓取与兜底机制：错过的书会自动补上

Sidecar 不只是"下载时顺手抓一下"，还内置了多层保险：

1. 自动创建：有声书整理完成即生成电子书请求，状态流转为pending → searching → downloading → processing → downloaded；
2. 每日兜底任务：find_missing_ebooks计划任务（默认每日午夜）会扫描最多 50 个downloaded/available状态的有声书，对缺失电子书的自动补抓，覆盖竞态条件、Indexer 短暂故障、Goodreads/Hardcover 同步导入等场景；
3. 重试上限：每本书最多自动重试 5 次（计数器为Request.ebookAutoRetryCount），超过后停止自动重试，但仍可手动抓取；
4. 手动入口：在有声书详情弹窗中点击Fetch Ebook按钮，或调用POST /api/audiobooks/[asin]/fetch-ebook（fetch-ebook/route.ts），即使该书是库外导入的"孤儿"有声书也支持。

失败时请求进入awaiting_search等待重试，且绝不影响有声书本身的入库——这是 Sidecar 设计上的非阻塞原则。

Kindle 用户福利：EPUB 兼容性自动修复

如果你选择 EPUB 作为首选格式，可以额外开启Kindle fix开关。它会在文件入库前（epub-fixer.ts）自动完成四项修复：

1. 为缺失的文件补充 UTF-8 XML 声明；
2. 移除导致 Kindle 超链接失效的#body/#bodymatter锚点片段；
3. 校验dc:language语言代码，不符合 Amazon KDP 规范时回退为en；
4. 清除没有src属性的游离<img>标签。

修复过程先写入临时文件再入库，原始下载文件保持完整（这对需要继续做种的种子文件很重要），且即使修复失败也不会中断流程。

常见限制与注意事项

• 📖仅支持英文书：Anna's Archive 标题搜索使用英文过滤条件；
• ⚠️同名书风险：标题搜索对常见书名可能匹配到错误的书，建议优先走 ASIN 精确匹配；
• 🗑️删除行为：删除电子书请求只移除.epub/.pdf等电子书文件，不会删除书名目录、有声书文件或后台库条目；
• 🔍格式识别：从种子标题判断格式可能不精确，超过 20 MB 的结果会被视为非电子书过滤掉。

延伸阅读

• Sidecar 完整技术文档
• 设置页配置说明
• 计划任务与调度器
• 文件整理系统
• 核心源码：search-ebook.processor.ts、file-organizer.ts、RequestCard.tsx

一句话总结：开启 E-book Sidecar 后，ReadMeABook 就能在你听有声书的同时，自动把对应电子书"旁挂"进书库——读、听两份收藏，一次请求全部搞定。