这份详细的部署教程将指引您安装和运行 BookOrbit——一个功能强大的自托管图书馆与阅读平台。它支持电子书、PDF、有声书和漫画，并提供网页阅读器、Kobo/KOReader 设备同步、阅读统计和元数据管理等功能。

BookOrbit 的核心优势在于其**“三位一体”的同步体验**：您可以在网页阅读器、Kobo 电子阅读器或 KOReader 应用上阅读，进度、书签和高亮会自动双向同步。此外，它还能与 Hardcover、Readwise 和 StoryGraph 等第三方服务同步数据。

🐳 快速部署（使用 Docker）

Docker 是部署 BookOrbit 最推荐的方式，简单且能保证环境一致性。

第一步：准备环境与文件

在您的服务器上创建一个项目目录，并下载必要的配置文件。

1
2
3
4
5
6
7
8
9
# 1. 创建项目目录并进入
mkdir bookorbit && cd bookorbit

# 2. 创建数据存储目录
mkdir -p books data/app data/postgres

# 3. 下载示例配置文件和 Docker Compose 文件
curl -fsSLo .env https://raw.githubusercontent.com/bookorbit/bookorbit/main/.env.example
curl -fsSLo docker-compose.yml https://raw.githubusercontent.com/bookorbit/bookorbit/main/docker-compose.yml

第二步：配置关键参数

编辑下载的 .env 文件，设置以下必需的环境变量。您可以使用 openssl rand -hex 24 等命令生成安全的随机字符串。

1
2
3
4
5
6
# .env 文件中的关键配置
APP_URL=http://您的服务器IP:3000   # 您访问 BookOrbit 的地址
BOOKS_HOST_PATH=./books          # 存放电子书文件的本地路径
POSTGRES_PASSWORD=your_strong_password  # 数据库密码，建议生成
JWT_SECRET=your_jwt_secret       # 用于签名登录令牌，建议生成
SETUP_BOOTSTRAP_TOKEN=your_bootstrap_token # 首次设置的一次性令牌，建议生成

⚠️ 权限重要提示：
如果您的服务器上书籍文件的所有者不是 UID 1000，必须在 .env 文件中设置 PUID 和 PGID 以匹配该用户。您可以通过 id -u 和 id -g 命令查看当前用户的 ID。这是导致首次扫描权限错误的最常见原因。

第三步：启动服务

在 bookorbit 目录下执行以下命令，Docker 将自动拉取镜像并启动服务。

1
docker compose up -d

第四步：完成初始化设置

打开浏览器访问 http://您的服务器IP:3000，使用您在 .env 中设置的 SETUP_BOOTSTRAP_TOKEN 完成首次设置向导，创建管理员账户。

📚 使用与核心功能

  • 导入书籍：最简单的方式是将书籍文件（如 EPUB、PDF）放入 ./books 目录。BookOrbit 的自动扫描器会检测到它们。您也可以通过网页界面的“上传”功能或配置“Book Dock”自动导入文件夹来添加书籍。
  • 阅读书籍：点击任何书籍即可在浏览器中打开内置阅读器，支持 EPUB、PDF、漫画和有声书。
  • 配置 KOReader 同步：
    1. 在 BookOrbit 的 设置 > KOReader 中，创建凭证并点击 下载插件。
    2. 解压下载的 bookorbit.koplugin.zip 文件。
    3. 将解压出的 bookorbit.koplugin 文件夹复制到您 KOReader 设备的 koreader/plugins/ 目录下。
    4. 重启 KOReader，打开一本书，使用 Tools > BookOrbit Sync 连接。
    5. 该插件已预先配置好您的服务器地址和凭证，无需手动输入。
  • Kobo 设备同步：需要安装 NickelMenu 并配置同步 URL，详细步骤请参考 官方文档。
  • 元数据管理：BookOrbit 会从 Google Books、Open Library、ComicVine 等 14 个元数据提供商自动获取书籍信息（封面、简介、作者等），丰富您的图书馆。

🔧 配置反向代理（可选但推荐）

为了通过域名安全访问，您可以在 .env 中将 APP_URL 改为您的域名（如 https://books.yourdomain.com），然后配置 Nginx 或 Caddy 将请求反向代理到本地的 http://127.0.0.1:3000。具体配置示例可参考 官方安装文档。

❓ 常见问题与故障排查

  • 权限错误：这是最常出现的问题。确保 .env 中的 PUID 和 PGID 与您存放书籍的文件系统用户 ID 一致。
  • 端口占用：如果 3000 端口被占用，可以修改 docker-compose.yml 中 ports 的映射，如改为 "3001:3000"。
  • 数据库问题：PostgreSQL 数据保存在 ./data/postgres 目录。如需重置，请先停止容器，然后删除此目录，再重新启动。
  • 更多帮助：查阅 官方文档 或通过 GitHub Discussions 寻求社区帮助。

📄 总结

通过上述步骤，您应该拥有一个运行中的 BookOrbit 实例。Docker 方式极大简化了部署过程，让您能专注于享受阅读和整理藏书。