BookLore 详细部署教程

BookLore 是一个功能强大的自托管数字图书馆应用，支持智能书架、自动元数据抓取、设备同步、BookDrop 自动导入以及内置阅读器等功能。本教程将引导你通过 Docker Compose 完成 BookLore 的完整部署。

一、部署前提

在开始之前，请确保你的服务器满足以下条件：

  • 已安装 Docker 和 Docker Compose
  • 拥有一个用于存放应用数据和图书文件的目录
  • （可选）如需外网访问，准备好域名和 SSL 证书

BookLore 官方提供两个镜像仓库，你可以任选其一：

  • GitHub Container Registry: ghcr.io/booklore-app/booklore
  • Docker Hub: booklore/booklore

二、创建配置文件

首先，创建一个用于存放部署文件的目录，例如 /opt/booklore，然后进入该目录：

1
2
mkdir -p /opt/booklore
cd /opt/booklore

1. 创建 .env 文件

在目录中创建 .env 文件，用于集中管理环境变量。你可以直接复制以下内容，然后根据实际情况修改：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# 应用程序设置
APP_USER_ID=1000          # BookLore 容器运行的用户 ID
APP_GROUP_ID=1000         # BookLore 容器运行的用户组 ID
TZ=Asia/Shanghai          # 时区，国内建议设置为 Asia/Shanghai

# 数据库连接设置
DATABASE_URL=jdbc:mariadb://mariadb:3306/booklore
DB_USER=booklore
DB_PASSWORD=ChangeMe_BookLoreApp_2025!   # 请务必修改为强密码

# 存储类型：LOCAL（本地存储）或 NETWORK（网络存储）
DISK_TYPE=LOCAL

# MariaDB 容器设置
DB_USER_ID=1000           # MariaDB 容器运行的用户 ID
DB_GROUP_ID=1000          # MariaDB 容器运行的用户组 ID
MYSQL_ROOT_PASSWORD=ChangeMe_MariaDBRoot_2025!   # 请务必修改为强密码
MYSQL_DATABASE=booklore

关键说明：

  • APP_USER_ID 和 APP_GROUP_ID 应设置为宿主机上用于运行容器的用户 ID。你可以通过 id -u 和 id -g 命令查看当前用户 ID。
  • DB_PASSWORD 和 MYSQL_ROOT_PASSWORD 是数据库的敏感信息，强烈建议修改为强密码。
  • DISK_TYPE 默认为 LOCAL，适用于本地磁盘。如果你的图书文件存放在 NAS 或网络存储上，需要设置为 NETWORK（详见第六节）。

2. 创建 docker-compose.yml 文件

在同一目录下创建 docker-compose.yml 文件：

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
services:
  booklore:
    image: ghcr.io/booklore-app/booklore:latest
    # 备选镜像: booklore/booklore:latest
    container_name: booklore
    environment:
      - USER_ID=${APP_USER_ID}
      - GROUP_ID=${APP_GROUP_ID}
      - TZ=${TZ}
      - DATABASE_URL=${DATABASE_URL}
      - DATABASE_USERNAME=${DB_USER}
      - DATABASE_PASSWORD=${DB_PASSWORD}
      - DISK_TYPE=${DISK_TYPE}
    depends_on:
      mariadb:
        condition: service_healthy
    ports:
      - "6060:6060"
    volumes:
      - ./data:/app/data          # 应用数据（配置、缓存等）
      - ./books:/books            # 图书库目录
      - ./bookdrop:/bookdrop      # BookDrop 自动导入目录
    healthcheck:
      test: wget -q -O - http://localhost:6060/api/v1/healthcheck
      interval: 60s
      retries: 5
      start_period: 60s
      timeout: 10s
    restart: unless-stopped

  mariadb:
    image: lscr.io/linuxserver/mariadb:11.4.5
    container_name: mariadb
    environment:
      - PUID=${DB_USER_ID}
      - PGID=${DB_GROUP_ID}
      - TZ=${TZ}
      - MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
      - MYSQL_DATABASE=${MYSQL_DATABASE}
      - MYSQL_USER=${DB_USER}
      - MYSQL_PASSWORD=${DB_PASSWORD}
    volumes:
      - ./mariadb/config:/config
    restart: unless-stopped
    healthcheck:
      test: [ "CMD", "mariadb-admin", "ping", "-h", "localhost" ]
      interval: 5s
      timeout: 5s
      retries: 10

目录映射说明：

  • ./data：存放 BookLore 的应用数据，建议定期备份。
  • ./books：你的图书库，所有导入的图书文件都会存放在这里。
  • ./bookdrop：将电子书文件放入此目录，BookLore 会自动检测并处理。
  • ./mariadb/config：MariaDB 数据库的持久化数据，非常重要，请定期备份。

三、启动 BookLore

配置完成后，使用以下命令启动所有服务：

1
docker compose up -d

该命令会后台启动 BookLore 和 MariaDB 两个容器。首次启动时，MariaDB 需要初始化数据库，BookLore 会等待数据库就绪后才开始运行。

你可以通过以下命令查看启动日志，确认服务是否正常运行：

1
docker compose logs -f

当看到 BookLore 日志显示应用已启动后，在浏览器中访问：

1
http://你的服务器IP:6060

首次访问时，系统会引导你创建管理员账户。设置完成后，你就可以开始构建自己的数字图书馆了。

四、BookDrop 自动导入

BookDrop 是 BookLore 的一项特色功能，能够实现“零操作”导入：你只需将电子书文件（EPUB、PDF、漫画等）放入 bookdrop 目录，BookLore 就会自动：

  1. 监控该目录
  2. 检测并解析新文件
  3. 抓取元数据（封面、简介等）
  4. 将文件排队等待你审核后导入书库

这一功能极大地简化了批量导入图书的流程。

五、配置 HTTPS（可选但推荐）

如果你需要通过公网访问，强烈建议配置 HTTPS。最推荐的方式是使用 Nginx 反向代理。你可以在 Nginx 配置中添加如下 server 块：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;

    location / {
        proxy_pass http://booklore:6060;  # 如果 Nginx 和 BookLore 在同一 Docker 网络
        # 或 proxy_pass http://127.0.0.1:6060;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

注意： 如果 Nginx 和 BookLore 在不同的 Docker 网络中，你需要创建一个共享网络，并将两个容器都连接到该网络。

六、网络存储（NAS / NFS / SMB）的重要说明

BookLore 的文件操作功能（如元数据写入、文件重命名、文件组织）仅针对本地文件系统设计和测试。官方明确表示不支持网络附加存储（NAS、NFS、SMB/CIFS 挂载、云备份 FUSE 等），因为网络延迟、缓存和文件系统语义差异可能导致文件损坏、写入不完整或文件丢失等问题。

如果你的图书文件存放在网络存储上，必须在 .env 文件中设置：

1
DISK_TYPE=NETWORK

这会将 BookLore 置于网络存储模式，该模式会禁用所有文件写入和重组功能。元数据仅存储在数据库中，你的原始文件永远不会被修改。这是官方唯一支持的网络存储配置。

七、常用维护命令

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# 查看容器状态
docker compose ps

# 查看日志
docker compose logs -f booklore
docker compose logs -f mariadb

# 停止所有服务
docker compose down

# 停止并删除数据（谨慎使用）
docker compose down -v

# 更新 BookLore 到最新版本
docker compose pull
docker compose up -d

# 重启服务
docker compose restart

八、数据备份建议

定期备份以下目录至关重要：

  1. ./mariadb/config：包含所有图书元数据、用户信息、阅读进度等核心数据。
  2. ./data：应用配置和缓存。
  3. ./books：你的原始图书文件。

建议设置定时任务将上述目录备份到其他存储位置。

九、进阶功能配置

BookLore 还支持许多进阶功能，部署完成后可以按需配置：

  • Kobo / KOReader 同步：在 BookLore 设置中找到同步服务器地址，在设备端配置即可实现阅读进度同步。
  • OPDS 支持：任何支持 OPDS 协议的阅读器（如 KOReader、Moon+ Reader）都可以通过 BookLore 的 OPDS 端点浏览和下载图书。
  • 多用户管理：管理员可以在设置中创建多个用户账户，每个用户拥有独立的书架和阅读进度。
  • 邮件发送：配置 SMTP 后，可以一键将图书发送到 Kindle 或他人邮箱。

部署完成后，你就可以通过浏览器访问 BookLore，开始整理、阅读和同步你的个人数字图书馆了。如果在部署过程中遇到问题，建议先查看 docker compose logs 的输出，通常能从中找到线索。