BookOrbit 是一个功能强大的自托管阅读平台，支持电子书、PDF、有声书和漫画，并能在Kobo、KOReader和网页间同步阅读进度。以下是基于官方文档和社区实践整理的详细部署教程。

📋 部署方案选择

BookOrbit 推荐使用 Docker 进行部署，这是最简单、最通用的方式。根据你的技术背景，可以选择：

方案 适用人群 特点
标准 Docker 部署 熟悉命令行的用户 最通用，官方推荐，控制力强
图形化面板部署 群晖NAS、Portainer、Easypanel等用户 界面操作，相对直观
Proxmox VE 脚本部署 Proxmox VE用户 一键创建容器，高度自动化

本教程将重点介绍标准 Docker 部署流程。

🚀 标准 Docker 部署指南

第 1 步：准备环境与下载文件

  1. 确保已安装 Docker 和 Docker Compose。在终端中执行以下命令检查：

    1
    2
    docker --version
    docker compose version

  2. 创建项目目录并进入：

    1
    mkdir bookorbit && cd bookorbit

  3. 下载官方配置文件：

    1
    2
    3
    4
    # 下载环境变量示例文件
    curl -fsSLo .env https://raw.githubusercontent.com/bookorbit/bookorbit/main/.env.example
    # 下载 Docker Compose 编排文件
    curl -fsSLo docker-compose.yml https://raw.githubusercontent.com/bookorbit/bookorbit/main/docker-compose.yml

第 2 步：创建数据目录（关键）

在项目目录下，创建三个文件夹用于持久化存储数据，避免容器重建后数据丢失。

1
mkdir -p books data/app data/postgres
  • books: 用来存放你的电子书、有声书等文件。你可以把已有的书都放在这里。
  • data/app: 存储应用数据，如封面、缩略图、配置等。
  • data/postgres: 存储 PostgreSQL 数据库文件。

第 3 步：配置环境变量 (.env)

这是最重要的一步。用文本编辑器打开刚才下载的 .env 文件，必须修改以下核心参数：

变量名 说明 示例值 如何生成
APP_URL 关键：你访问 BookOrbit 的完整URL。 http://你的服务器IP:3000 (内网) 或 https://你的域名 (公网) 根据你的网络环境填写。
BOOKS_HOST_PATH 关键：存放书籍的宿主机文件夹绝对路径。 ./books (相对路径) 或 /path/to/your/books (绝对路径，NAS建议用绝对路径) 使用 pwd 命令查看当前目录，然后拼接 /books。
POSTGRES_PASSWORD 数据库密码。 一个强密码 终端执行 openssl rand -hex 24。
JWT_SECRET 用于签名登录令牌。 一个强密码 终端执行 openssl rand -hex 32。
SETUP_BOOTSTRAP_TOKEN 关键：首次启动设置管理员账户的一次性令牌。 一个强密码 终端执行 openssl rand -hex 16。请务必记下这个令牌！

⚠️ 文件权限特别注意（尤其是 NAS 用户）：
如果 books 文件夹的拥有者不是 UID 1000（Docker容器默认用户），扫描时可能会报权限错误。请在 .env 文件中设置 PUID 和 PGID 为拥有该文件夹的用户的 ID。

1
2
3
4
5
# 假设你的用户名是 admin，执行以下命令查看其 UID 和 GID
id admin
# 将输出中的 uid=XXX(admin) 和 gid=XXX(admin) 填入 .env
PUID=XXX
PGID=XXX

第 4 步：启动服务

在 bookorbit 目录下，执行以下命令启动所有服务：

1
docker compose up -d

Docker 会自动拉取镜像并启动容器。你可以使用 docker compose logs -f 查看实时日志，确认是否启动成功。

第 5 步：完成初始化设置

  1. 打开浏览器，访问你在 APP_URL 中设置的地址（例如 http://你的服务器IP:3000）。
  2. 页面会要求你输入 SETUP_BOOTSTRAP_TOKEN，请输入你在第3步生成的令牌。
  3. 按照向导创建你的管理员账号，即可开始使用。

✨ 部署后的配置建议

  1. 设置反向代理（如需公网访问）：为了安全地通过公网访问，建议使用 Nginx、Caddy 等工具配置 HTTPS 反向代理，并将 APP_URL 更新为你的 HTTPS 域名。
  2. 配置外部存储（可选）：如果想使用自己已有的 PostgreSQL 数据库，可以在 .env 中配置 DATABASE_URL 并注释掉 docker-compose.yml 中的 postgres 服务。
  3. 开启 SSO（可选）：BookOrbit 支持 Authentik、Keycloak 等 OIDC 提供商。配置好后，若希望强制使用 SSO 登录，可将 .env 中的 DISABLE_LOCAL_AUTH 设置为 true。

🔧 常见问题排查

  • 权限错误（Permission denied）：这几乎总是由于 PUID/PGID 设置不正确，或 books 文件夹权限不足。请再次确认文件夹所有者 ID，并检查 books 文件夹是否具有读写权限。
  • 无法访问 APP_URL：检查服务器防火墙是否开放了 3000 端口（或你修改后的端口）。如果使用云服务器，请检查安全组规则。
  • 扫描不到书籍：确认 BOOKS_HOST_PATH 路径正确，且书籍文件格式在支持列表内（EPUB, PDF, CBZ, M4B等）。

如果遇到其他问题，可以查阅官方文档（bookorbit.app）或在 GitHub 仓库提交 Issue。