三股水
BookOrbit Book Dock 完整使用教程与避坑指南
软件 2138 字 约 7 分钟
本文从 Obsidian 撰写发布

BookOrbit Book Dock 完整使用教程与避坑指南

本文档基于真实部署和长期使用经验整理，涵盖 Book Dock（自动导入）功能的工作原理、配置方法、常见问题及最佳实践。

一、什么是 Book Dock？

Book Dock 是 BookOrbit 的自动导入功能，相当于一个智能投递箱。你只需要把电子书文件放进指定的文件夹，BookOrbit 就会自动识别、处理并导入到书库中。

核心概念：

  • Book Dock：自动导入功能的名称
  • auto_ingest：你服务器上存放待导入文件的目录
  • /data/book-dock：容器内对应的监控目录
  • Finalize：确认入库（文件从待处理移到书库）
  • Confidence threshold：匹配度阈值，决定是否自动入库

二、环境准备（关键配置）

1. 目录映射必须正确

在 docker-compose.yml 中，确保 auto_ingest 映射到容器内的 /data/book-dock：

volumes:

  • ./auto_ingest:/data/book-dock # 正确
    # - ./auto_ingest:/app/data/book-dock # 错误

验证方法：
docker exec -it bookorbit-app ls -la /data/book-dock/

2. 容器用户权限必须匹配

在 docker-compose.yml 中添加 user: "1000:1000"，确保容器用户与宿主机目录所有者一致：

   services:
  bookorbit:
    image: ghcr.io/bookorbit/bookorbit:latest
    user: "1000:1000"   # 必须添加

验证方法：
docker exec -it bookorbit-app id

应显示 uid=1000(node) gid=1000(node)

3. 目录权限必须正确

cd /wwwroot/bookorbit
sudo chown -R 1000:1000 auto_ingest books data pgdata
sudo chmod -R 755 auto_ingest books data pgdata

三、Book Dock Web 界面设置

在 Web 界面中，进入「设置」→「Book Dock」，有以下关键选项：

基础设置：

  • Drop folder：显示容器内监控路径 /data/book-dock（只读）
  • Destination library：入库后放到哪个书库
  • Destination folder：入库后文件放到哪个目录（通常为 /books）

元数据设置：

  • Auto-fetch metadata from providers：是否自动联网抓取封面/作者/简介，新手建议开启，出问题时可关闭
  • Auto-finalize：是否自动完成入库（无需手动确认），建议开启
  • Confidence threshold：匹配度阈值，低于此值不会自动入库，建议 50%（最低）

Metadata mode（元数据合并模式）：

  • Safe merge（推荐）：只补充缺失的字段，不覆盖已有数据
  • Replace：用新数据完全覆盖旧数据

四、支持与不支持的文件格式

完全支持（经过验证）：

  • EPUB：最通用的电子书格式，支持最好
  • KEPUB：Kobo 专用格式
  • MOBI：Kindle 旧格式
  • PDF：支持，但元数据解析可能有问题
  • CBZ/CBR：漫画格式

特殊说明：

  • PDF：如果文件内部元数据包含异常字符（如 \u0000），可能会导致入库失败，建议通过 Web 界面上传或先用 Calibre 清理元数据
  • 有声书：M4B、MP3、M4A 等格式支持，但建议保持文件名简洁

五、文件命名规则（极其重要！）

错误命名（会导致处理失败）：

  • 完美伴侶 緩慢性愛_[日]Adam 德永 著 宋好 譯_24hbook.com.epub （中文、空格、括号、特殊符号过多）
  • 男女性功能障碍独特秘方绝招 (中国民间中医医药研究开发协会中药外治专业委员会) .pdf （中文、括号、空格）
  • book(1).epub （括号）
  • 书@#$.pdf （特殊符号）

正确命名：

  • book.epub 纯英文，最简单
  • sex_health.pdf 英文+下划线
  • slow_love.epub 英文+下划线
  • The_Great_Gatsby.epub 英文+下划线

命名规则总结：

  • 只用英文字母、数字、下划线 _，不要用中文
  • 不要用空格，用下划线替代
  • 不要用括号 () [] {}，直接删除
  • 不要用特殊符号，如 @ # $ % &
  • 文件名不要太长，控制在 50 个字符以内

六、完整工作流程

方式一：自动导入（推荐）

  1. 准备文件：确认文件名是纯英文（如 book.epub）
  2. 放入目录：用宝塔或 SCP 上传到 /wwwroot/bookorbit/auto_ingest/
  3. 等待处理：等待 30-60 秒，系统自动处理
  4. 检查结果：如果文件从 auto_ingest 消失说明处理成功；去 Web 界面书库查看应该能看到书；如果有封面和元数据就完美了

方式二：Web 界面上传（备用）

  1. 登录 Web 界面
  2. 进入书库
  3. 点击上传
  4. 选择文件（文件名可以是中文）
  5. 等待上传完成

方式三：手动入库（兜底）
如果自动导入失败：
cd /wwwroot/bookorbit
mv auto_ingest/*.epub books/ 2>/dev/null
mv auto_ingest/*.pdf books/ 2>/dev/null
然后登录 Web 界面，进入「设置」→「书库」→ 点击「扫描」

七、查看日志和状态

查看 BookDock 是否正常运行：
docker-compose logs bookorbit | grep -i "bookdock" | tail -10

正常输出：
{"level":30,"time":...,"context":"BookDockWatcherService","msg":"Watching Book Dock folder: /data/book-dock"}

查看文件处理状态：
ls -la /wwwroot/bookorbit/auto_ingest/
ls -la /wwwroot/bookorbit/books/
docker-compose logs bookorbit --tail 50

查看特定文件的处理记录：
docker-compose logs bookorbit | grep -i "你的文件名" | tail -20

八、常见问题与解决方案

Q1: 文件放入 auto_ingest 后没有反应
可能原因：文件名包含中文、空格、括号等特殊字符；BookDock 服务没有正常运行；目录映射路径不正确
解决方案：重命名为纯英文如 book.epub；重启 BookDock：docker-compose restart bookorbit；检查映射路径：docker exec -it bookorbit-app ls -la /data/book-dock/

Q2: 文件出现在 Book Dock 界面，但没有自动入库
原因：Auto-finalize 未开启；匹配度低于阈值
解决方案：在 Web 界面「设置」→「Book Dock」→ 开启 Enable auto-finalize；将 Confidence threshold 拉到最低（50%）；关闭 Auto-fetch metadata from providers（可选，避免卡住）

Q3: 文件卡在 auto_ingest 中无法入库
现象：文件在 auto_ingest 里，前端也能看到，但一直不消失
解决方案：
cd /wwwroot/bookorbit
mv auto_ingest/文件名.epub books/
然后 Web 界面手动扫描

Q4: Web 界面上传报错 Internal Server Error
原因：目录权限不足
解决方案：
sudo chown -R 1000:1000 /wwwroot/bookorbit/books
sudo chown -R 1000:1000 /wwwroot/bookorbit/data
sudo chmod -R 755 /wwwroot/bookorbit/books
sudo chmod -R 755 /wwwroot/bookorbit/data

Q5: 自动导入小文件可以，大文件不行
可能原因：内存不足；处理超时；文件内部元数据有异常
解决方案：监控内存 docker stats bookorbit-app；用 Web 界面上传大文件；用 Calibre 检查并修复文件内部元数据

Q6: 前端提示错误中包含 \u0000
原因：PDF 内部元数据包含空字符（NULL 字符），数据库拒绝写入
解决方案：使用 Calibre 打开 PDF → 编辑元数据 → 删除异常字符 → 重新导出；或者直接用 Web 界面上传（会自动过滤）；或者在 Book Dock 界面手动点击 Finalize

Q7: 如何确认 BookDock 是否正常？
docker-compose ps | grep bookorbit
docker-compose logs bookorbit | grep -i "bookdock" | tail -5
touch /wwwroot/bookorbit/auto_ingest/test.txt
sleep 5
ls -la /wwwroot/bookorbit/auto_ingest/test.txt

九、最终推荐配置

docker-compose.yml 关键配置：

services:
  bookorbit:
    image: ghcr.io/bookorbit/bookorbit:latest
    container_name: bookorbit-app
    user: "1000:1000"
    ports:
      - "8090:3000"
    volumes:
      - ./data:/app/data
      - ./books:/books
      - ./auto_ingest:/data/book-dock
    environment:
      - DB_HOST=postgres
      - DB_PORT=5432
      - PGUSER=bookorbit
      - PGPASSWORD=bookorbit@123
      - PGDATABASE=bookorbit
      - JWT_SECRET=your_secret
      - SETUP_BOOTSTRAP_TOKEN=your_token
      - HOST=0.0.0.0
      - PORT=3000
      - NODE_ENV=production
    depends_on:
      - postgres
    restart: unless-stopped
    networks:
      - bookorbit-net
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 1G

Web 界面 Book Dock 设置：

  • Auto-fetch metadata：保持开启，如果查不到就关闭
  • Auto-finalize：开启
  • Confidence threshold：50%（最低）
  • Metadata mode：Safe merge
  • Destination library：你的书库名

十、最佳实践总结

上传前检查清单：

  • 文件名是纯英文（如 book.epub）
  • 没有中文、空格、括号、特殊符号
  • 文件大小适中（建议一次只传 1-3 本）
  • 容器用户权限正确（user: "1000:1000"）
  • 目录映射正确（./auto_ingest:/data/book-dock）
  • BookDock 服务正常运行（查看日志）

日常使用流程：

  1. 放文件：把纯英文名的文件放到 auto_ingest
  2. 等处理：等待 30-60 秒，系统自动处理
  3. 检查：查看文件是否被移走，前端是否出现
  4. 补缺：如果封面缺失，手动编辑补全

故障排查流程：

  1. 检查文件位置：ls -la auto_ingest/ && ls -la books/
  2. 查看日志：docker-compose logs bookorbit | tail -50
  3. 检查 BookDock 状态：docker-compose logs bookorbit | grep -i bookdock
  4. 确认权限：ls -la /wwwroot/bookorbit/
  5. 重启服务：docker-compose restart bookorbit

绝对禁止：

  1. 使用宝塔面板文件管理器上传电子书到 auto_ingest 目录 → 可能触发文件监控死锁，导致服务器完全卡死
  2. 一次性上传大量书籍 → 资源耗尽
  3. 文件名包含中文、空格、括号、特殊符号 → 处理失败
  4. 上传超过 100MB 的单个文件 → 内存溢出风险
# BookOrbit
😊
提交