一站式自托管阅读平台BookOrbit

发表于 分类于 Waline： 阅读次数： 本文字数： 6.1k 阅读时长 ≈ 6 分钟
BookOrbit 是一个自托管的数字图书馆和阅读平台，支持电子书、PDF、漫画和有声书。

简介

什么是 BookOrbit ？

BookOrbit 是一个开源的自托管数字图书馆和阅读平台。它可以帮助你把散落在 NAS、服务器或本地硬盘里的 EPUB、PDF、漫画包和有声书整理成一个统一的阅读空间——内置多种格式阅读器、自动元数据补全、多用户权限管理，还支持 Kobo/KOReader 同步和阅读统计分析。

主要特点

  • 内置多格式阅读器：无需额外安装插件，直接在浏览器中阅读 EPUB、KEPUB、MOBI、AZW3、PDF、CBZ/CBR/CB7 漫画以及 M4B/MP3/FLAC 等有声书
  • 丰富的元数据来源：支持从 Google Books、Amazon、Goodreads、Open Library、iTunes、Audible、ComicVine 等 9 个来源自动抓取书籍元数据，可自定义字段规则
  • 智能书架与集合：支持手动收藏和基于规则的 Smart Scopes 动态过滤视图，让书架管理更灵活
  • Kobo/KOReader 同步：自动推送书籍到 Kobo 设备，通过 OPDS 与 KOReader 实现双向阅读进度同步
  • 多用户与 OIDC/SSO：支持细粒度权限控制、独立的阅读数据隔离，可对接 Authentik、Keycloak、Authelia 等身份认证提供商
  • 阅读统计与分析：每日阅读时间统计、热力图、连续阅读记录、阅读目标追踪和书库健康仪表盘
  • 开源免费：基于 AGPL-3.0 协议开源，可免费使用和修改

应用场景

  • 个人数字书库管理：将分散在各处的电子书集中管理，自动补全封面、作者、简介等元数据
  • 家庭共享阅读：为家庭成员创建独立账号，各自管理阅读进度和书架，互不干扰
  • Kobo/Kindle 用户：通过 OPDS 推送到 Kobo 设备，支持 Send-to-Kindle 邮件投递
  • 有声书管理：支持 M4B、MP3、FLAC 等格式，内置浏览器端有声书播放器
  • 开发者测试：开发人员可以快速搭建测试环境，体验完整的自托管阅读平台功能

BookOrbit 是一个功能全面的一站式自托管阅读平台，将电子书管理、多格式阅读、元数据补全和多用户协作整合在一起。

安装

在群晖上以 Docker 方式安装。

提示：BookOrbit 的镜像托管在 ghcr.io，群晖 Docker 套件无法直接搜索，需要通过命令行拉取镜像

BookOrbit 采用多容器架构（应用 + PostgreSQL 数据库），推荐使用 docker-compose 进行部署。

env.txt

老苏用 AI 翻译了一下 https://github.com/bookorbit/bookorbit/blob/main/.env.example 中的注释

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
# 运行的 Docker 镜像。为更严格的部署请固定为 sha-* 标签或 @sha256 摘要。
APP_IMAGE=ghcr.io/bookorbit/bookorbit:latest

# 主机上应用公开的端口
APP_PORT=3622

# 主机上在容器内映射为 /books 的文件夹。
# 将其指向你的图书馆根目录；在 NAS 或 Portainer 安装中请使用绝对路径。
BOOKS_HOST_PATH=./books

# 可选：Book Dock 投放区在主机上的文件夹（在容器内映射为 /data/book-dock）。
# 将电子书复制或移动到此处，Book Dock 会自动拾取并处理它们。
# 如果未设置，投放文件夹位于 ./data/app/book-dock（默认应用数据卷）内。
# 在挂载 NAS 共享或使用应用数据目录之外管理的文件夹时请使用绝对路径。
# BOOK_DROP_HOST_PATH=/mnt/nas/book-drop

# 容器运行时写入应用管理的数据文件夹时使用的 UID/GID。
# 大多数用户可保留这些默认值。
PUID=1000
PGID=1000

# 数据库凭据
POSTGRES_USER=bookorbit
POSTGRES_PASSWORD=change-this-password
POSTGRES_DB=bookorbit

# 应用密钥
JWT_SECRET=change-this-to-a-long-random-secret

# 用于初次调用 /auth/setup 端点（x-setup-token 请求头）的必需项
SETUP_BOOTSTRAP_TOKEN=change-this-to-a-long-random-secret

# 用于电子邮件和 Kobo 端点的外部/公共 URL
APP_URL=https://bookorbit.example.com

# Node.js JavaScript 堆内存上限，单位为 MB。对于非常大的图书库请提高该值。
NODE_MAX_OLD_SPACE_SIZE=2048

# --- 可选覆盖项（取消注释以设置） ---

# 如果你已经运行自己的 PostgreSQL，请设置 DATABASE_URL 并从 docker-compose.yml 中移除 postgres 服务。你的实例必须启用
# uuid-ossp、pg_trgm 和 vector (pgvector) 扩展。
# DATABASE_URL=postgres://user:password@yourhost:5432/bookorbit
# 或者分别设置各个字段（POSTGRES_HOST、POSTGRES_PORT、POSTGRES_USER、POSTGRES_PASSWORD、POSTGRES_DB）

# 客户端前端在与 APP_URL 不同域名下提供服务时的 CORS 来源
# CLIENT_URL=https://app.example.com

# 仅在你的平台外部管理绑定挂载所有权时将其设置为 false。
# BOOKORBIT_FIX_PERMISSIONS=true

# 如果你存储 SMTP 提供商凭据，建议设置（生成方法：openssl rand -hex 32）
# EMAIL_ENCRYPTION_KEY=

# 如果你存储迁移源凭据，建议设置（生成方法：openssl rand -hex 32）
# MIGRATION_ENCRYPTION_KEY=

# 日志级别（默认：info）。设置为 debug 可输出详细日志。
# LOG_LEVEL=info

# 允许解析到私有/本地域名的 OIDC issuer/discovery URL。
# 默认 false。仅在受信任的自托管网络中启用。
# OIDC_ALLOW_LOCAL_ISSUERS=false

# 可选：在使用自动设置时允许 Cloudflare Web Analytics 信标。
# 保持不设置或 false 可保留严格的内容安全策略（CSP）（`script-src 'self'`）。
# CSP_ALLOW_CLOUDFLARE_INSIGHTS=false

下面是一个简单的示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
# 应用设置
APP_IMAGE=ghcr.io/bookorbit/bookorbit:latest
APP_PORT=3622

BOOKS_HOST_PATH=./books

# UID/GID
PUID=1000
PGID=1000

# 数据库凭据
POSTGRES_USER=bookorbit
POSTGRES_PASSWORD=bookorbit123
POSTGRES_DB=bookorbit

# 应用密钥可以用 openssl rand -hex 32 生成
JWT_SECRET=bf7dd22b68918a7a0044d0ec115c1f930e53de49d97a091c017fcd9318751100

# 用于初次调用 /auth/setup 端点（x-setup-token 请求头）的必需项
SETUP_BOOTSTRAP_TOKEN=adde1f95b500d897e64bbf12198a4b2f9b426bac9162eb5c7edbeaff9d648f57

# 用于电子邮件和 Kobo 端点的外部/公共 URL
APP_URL=http://192.168.0.197:3622

# Node.js JavaScript 堆内存上限，单位为 MB。对于非常大的图书库请提高该值。
NODE_MAX_OLD_SPACE_SIZE=2048

说明：SETUP_BOOTSTRAP_TOKEN 用于首次安装时的身份验证，安装完成后可以移除以禁用设置向导入口。

docker-compose.yml

下面是完整的 docker-compose.yml 配置（已添加中文注释，保存时记得采用 UTF-8 格式）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
version: '3.8'

services:
  app:
    image: ${APP_IMAGE}
    container_name: bookorbit-app
    restart: unless-stopped
    init: true
    env_file:
      - env.txt
    ports:
      - "${APP_PORT}:${PORT:-3000}"
    environment:
      NODE_ENV: production
    depends_on:
      postgres:
        condition: service_healthy
    volumes:
      - ./books:/books                             # 电子书存放目录
      - ./data/app:/data                           # 应用数据目录
      - ./data/app/book-dock:/data/book-dock       # 自动摄入目录
    read_only: true
    tmpfs:
      - /tmp
    cap_drop:
      - ALL
    cap_add:
      - CHOWN
      - DAC_OVERRIDE
      - FOWNER
      - SETGID
      - SETUID
    security_opt:
      - no-new-privileges:true
    stop_grace_period: 30s
    healthcheck:
      test:
        [
          "CMD-SHELL",
          'node -e "fetch(''http://127.0.0.1:''+(process.env.PORT||3000)+''/api/v1/health'').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"',
        ]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 20s
      
  postgres:
    image: pgvector/pgvector:pg16
    container_name: bookorbit-db
    restart: unless-stopped
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
      PGDATA: /var/lib/postgresql/data/pgdata
    volumes:
      - ./data/postgres:/var/lib/postgresql/data   # 数据库持久化
    healthcheck:
      test: ["CMD-SHELL", 'pg_isready -U "${POSTGRES_USER}" -d "${POSTGRES_DB}"']
      interval: 10s
      timeout: 5s
      retries: 10
      start_period: 20s

然后通过 SSH 登录到您的群晖，执行下面的命令：

1
2
3
4
5
6
7
8
9
10
# 新建文件夹 bookorbit 和 子目录
mkdir -p /volume1/docker/bookorbit/{books,data/{app/book-dock,postgres}}

# 进入 bookorbit 目录
cd /volume1/docker/bookorbit

# 将 docker-compose.yml 放入当前目录

# 一键启动
docker-compose --env-file env.txt up -d

运行

在浏览器中访问 http://<群晖IP>:3622 即可进入设置界面，创建管理员账号

其中 Setup Token 的值为你在 env.txt 中设置的 SETUP_BOOTSTRAP_TOKEN

进入主界面，有设置向导进行功能说明

创建书库

创建你的书库

设置书库名称

配置书库目录，指向 /books，点 Add 添加即可

选择扫描的模式，老苏选择了 File as Book，BookOrbit 支持的格式还是很多的

其他按需要进行设置。如果你已经上传了图书

会看到扫描的进度

扫描速度还是很快的

也可以直接体验官方 Demo：访问 https://demo.bookorbit.app 无需安装即可体验全部功能。

OPDS

进入 Settings –> OPDS 可以找到端点

点 Add 添加 OPDS 的账号和密码

以 静读天下 为例

确定之后，会弹出账号和密码输入框，认证通过之后，就可以浏览了

注意事项

  1. 数据持久化：./books 目录存放你的电子书文件，./data/postgres 存放数据库，建议定期备份这两个目录
  2. 端口冲突：如果 3000 端口已被占用，可以在 env.txt 中修改 APP_PORT=3622
  3. 文件权限：如果遇到文件权限问题，可以在 env.txt 中调整 PUID 和 PGID 为你的用户 ID
  4. 大书库优化：如果书库非常大，可以在 env.txt 中增加 NODE_MAX_OLD_SPACE_SIZE=4096 来提升 Node.js 内存限制
  5. 安全建议：生产环境建议配置反向代理（如 Nginx）并启用 HTTPS；安装完成后建议移除 SETUP_BOOTSTRAP_TOKEN

参考文档

BookOrbit: Your Reading Space
地址：https://github.com/bookorbit/bookorbit

BookOrbit 官方网站
地址：https://bookorbit.app

GHCR 镜像页面
地址：https://ghcr.io/bookorbit/bookorbit

BookOrbit 安装文档
地址：https://bookorbit.app/installation.html