这是一份面向 VPS、NAS、家用服务器或 1Panel 用户的 BookLore 部署笔记，目标是用 Docker Compose 搭建一个可自托管、多用户、可阅读、可同步、可整理元数据的数字书库。公网访问统一走 HTTPS 反代入口，数据、数据库和配置都掌握在自己手里。

引子：你的电子书，真的"管理"起来了吗？

先问几个扎心的问题：

• 硬盘里攒了上千本 EPUB、PDF、漫画，却全躺在 下载/ 和 小说/ 里，找一本书要翻半天？
• 文件名要么是一串乱码，要么是「某某小说完整版(精校).epub」，作者、封面、简介一概没有？
• 手机上看一半，换平板要从头翻；Kobo 里想塞点自己的书，还得折腾 Calibre 同步？
• 想给家人开个账号共享书库，要么全权限暴露，要么干脆放弃？

如果你中了两条以上，那 BookLore 值得你花十分钟看看。它不是又一个"能看书的网页"，而是把电子书文件、元数据、阅读器、阅读进度、书架、系列、OPDS 和设备同步整合成一个自托管书库中心的开源方案。

下面先把优点讲透，再上详细部署教程。

一、这套方案是什么

BookLore 是一个自托管、多用户的数字书库应用，把电子书、漫画、元数据、阅读进度、设备同步和导入流程统一放在自己的服务器里管理。

它适合用来管理：

• EPUB
• PDF
• MOBI / AZW3 等常见电子书格式
• CBZ / CBR 等漫画格式
• 多格式同书
• 系列书籍
• 多用户家庭书库

官方项目描述中提到，BookLore 支持智能书架、自动元数据、Kobo 与 KOReader 同步、BookDrop 导入、OPDS，以及 EPUB/PDF/漫画的内置阅读器。

官方参考：

• GitHub：booklore-app/booklore
• 官方文档：BookLore Docs
• Docker 镜像：ghcr.io/booklore-app/booklore

二、为什么是 BookLore：它到底好在哪

2.1 先说痛点：你现在的电子书管理有多尴尬

BookLore 的定位，正好补齐这一整片空白：在自己的服务器上，拥有一个带封面、带简介、能在线读、能跨设备同步的私人书库。

2.2 BookLore 的 7 大优点（详解）

① 智能书架——大型书库的导航仪支持自定义书架和动态规则书架，可以按作者、系列、格式、标签、阅读状态、元数据字段等条件筛选图书。对几百上千本书来说，这比单纯按文件夹浏览灵活太多：你可以一键筛出"已读完的科幻系列""老婆还没看过的漫画""所有 PDF 扫描版"，而不用挨个目录翻。

② 自动元数据——告别手动补封面BookLore 可以从 Google Books、Open Library、Amazon 等来源拉取封面、简介、评分、评论等元数据。自动匹配后仍可人工编辑，特别适合处理标题不规范、系列信息缺失、封面错误的情况。拖一堆"无名氏"进去，出来就是整整齐齐的书架。

③ 内置阅读器——浏览器就是 Kindle浏览器里可以直接阅读 EPUB、PDF 和漫画文件，并记录阅读进度。手机、平板、电脑上打开同一个 Web 地址，就能无缝继续阅读，不用再装第三方阅读 App，也不用担心 App 停止维护。

④ 多设备同步——Kobo / KOReader 也能接支持 OPDS，也支持 Kobo、KOReader 等阅读链路。它可以作为电子书客户端和硬件阅读器之间的书库中心。手里有 Kobo 的话，这意味着你能把自己的书库直接同步进墨水屏，而不是被某家商店生态绑死。

⑤ 多用户——一家人共用一个书库每个用户可以有自己的书架、阅读进度、偏好和访问范围。家庭书库或小团队共享书库会非常方便：孩子看童书、你看技术书、爱人看小说，进度互不干扰。

⑥ BookDrop 自动导入——批量整理新书的捷径BookDrop 是一个投递目录，把书放进去后，BookLore 会自动检测、提取信息、拉取元数据，并进入审核导入流程。你只需要"丢进去——网页上点确认"，适合一次性整理几百本新书。

⑦ 自托管可控——数据真正属于你书库文件、数据库和配置都在自己的服务器里，备份策略、访问权限、反向代理和内网访问都可自己控制。没有会员费、没有隐私收割、没有"服务终止即书库消失"的风险。

2.3 横向对比：BookLore 处在什么位置

能力随版本演进，下表按各项目公开定位整理，具体以官方文档为准。

一句话：如果你要的是"一个能自动整理、能在线读、能同步 Kobo、还能给全家开账号"的综合性自托管书库，BookLore 是目前少有的把这些都做齐的开源项目。

2.4 谁最适合用 BookLore

✅ 电子书/漫画堆了几百 G，想彻底整理的人✅ 有多台设备、想随时续读的人✅ 手里有 Kobo / KOReader，想接自己书库的人✅ 想给家人开共享书库的家庭用户✅ 已经在玩 NAS / 1Panel / Docker 的自托管玩家

❌ 只想在手机上随便看两本、不想维护服务器的人——这类需求用现成 App 更省事。

三、推荐架构

推荐结构：

用户浏览器 -> HTTPS 反向代理 -> BookLore 容器 -> MariaDB 数据库书库文件 -> 挂载到 BookLore 容器BookDrop 投递目录 -> 挂载到 BookLore 容器

更具体一点：

• 反向代理负责 HTTPS、域名、证书和公网入口。
• BookLore 容器负责 Web UI、API、阅读器、元数据处理、导入队列。
• MariaDB 容器负责保存用户、书籍、元数据、阅读进度等结构化数据。
• books/
   保存电子书原文件。
• bookdrop/
   保存待自动导入的投递文件。
• data/
   保存 BookLore 应用数据。

四、最容易踩的坑：网络存储必须设 DISK_TYPE

这是部署 BookLore 最容易翻车的地方，单独拎出来说。

官方 README 明确提醒：BookLore 的文件写入、重命名、整理等操作是按本地文件系统设计的。NAS、NFS、SMB/CIFS、云盘 FUSE 等网络存储可能因为延迟、缓存、锁机制或文件系统语义差异，导致静默损坏、写入不完整、文件丢失等风险。

如果书库目录在 NAS、NFS、SMB/CIFS 或其他网络挂载上，必须使用：

# 指定 BookLore 使用网络存储模式，避免直接改写网络书库文件DISK_TYPE=NETWORK

网络存储模式下，BookLore 会把元数据保存在数据库里，并禁用会直接修改文件的整理功能。这是网络书库更稳的方式。

如果书库目录是服务器本地磁盘，可以使用：

# 指定 BookLore 使用本地磁盘模式，允许本地文件系统上的整理和写入能力DISK_TYPE=LOCAL

公开分享部署教程时，建议专门强调这点：NAS 书库优先 DISK_TYPE=NETWORK。

五、部署流程总览

整体流程：

1. 安装 Docker 和 Docker Compose。
2. 创建部署目录。
3. 创建 .env。
4. 创建 docker-compose.yml。
5. 启动 MariaDB 和 BookLore。
6. 登录 Web 页面创建管理员账号。
7. 添加书库目录。
8. 配置元数据、书架、BookDrop、OPDS。
9. 设置 HTTPS 反向代理。
10. 配置备份和升级策略。

六、创建部署目录

示例目录使用 1Panel 常见 Compose 路径，也可以换成普通 Docker Compose 目录。

sudo mkdir -p /opt/1panel/docker/compose/booklorecd /opt/1panel/docker/compose/bookloresudo mkdir -p data books bookdrop mariadb/configsudo chown -R 1000:1000 data books bookdrop mariadb

如果不确定 UID/GID：

idid -uid -g

七、创建 .env

建议把密码和可变参数放在 .env，不要直接硬编码到 docker-compose.yml。

生成随机密码：

openssl rand -base64 32# 数据库用户密码，可填入 DB_PASSWORDopenssl rand -base64 32# MariaDB root 密码，可填入 MYSQL_ROOT_PASSWORD

创建 .env：

# BookLore 容器运行用户 UID，需和宿主机目录权限匹配APP_USER_ID=1000# BookLore 容器运行用户 GID，需和宿主机目录权限匹配APP_GROUP_ID=1000# 容器时区，国内服务器通常使用 Asia/ShanghaiTZ=Asia/Shanghai# BookLore 连接 MariaDB 的 JDBC 地址，服务名 mariadb 来自 composeDATABASE_URL=jdbc:mariadb://mariadb:3306/booklore# BookLore 使用的数据库用户名DB_USER=booklore# BookLore 使用的数据库密码，部署时必须替换为随机强密码DB_PASSWORD=CHANGE_ME_DB_PASSWORD# 存储模式；本地磁盘用 LOCAL，NAS/NFS/SMB 网络存储建议用 NETWORKDISK_TYPE=NETWORK# MariaDB 容器运行用户 UID，通常与宿主机目录权限一致DB_USER_ID=1000# MariaDB 容器运行用户 GID，通常与宿主机目录权限一致DB_GROUP_ID=1000# MariaDB root 密码，部署时必须替换为随机强密码MYSQL_ROOT_PASSWORD=CHANGE_ME_MYSQL_ROOT_PASSWORD# MariaDB 初始化数据库名MYSQL_DATABASE=booklore

注意：.env 中的密码占位符必须替换为真实随机强密码；不要把 .env 上传到公开仓库。

八、docker-compose.yml（推荐版）

下面是可分享的通用模板，不包含真实路径、真实端口和真实密码。

services:  booklore:    image: ghcr.io/booklore-app/booklore:latest    container_name: booklore    restart: unless-stopped    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    healthcheck:      test: wget -q -O - http://localhost:6060/api/v1/healthcheck      interval: 60s      retries: 5      start_period: 60s      timeout: 10s    networks:      - booklore  mariadb:    image: lscr.io/linuxserver/mariadb:11.4.5    container_name: booklore-mariadb    restart: unless-stopped    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    healthcheck:      test: [”CMD”, ”mariadb-admin”, ”ping”, ”-h”, ”localhost”]      interval: 10s      timeout: 5s      retries: 10    networks:      - booklorenetworks:  booklore:

说明：宿主机端口 6060 映射到容器 6060；books/ 是书库目录，生产环境可替换成自己的书库路径；bookdrop/ 是自动导入投递目录；mariadb/config 持久化数据库文件。

九、启动服务

启动前检查配置：

cd /opt/1panel/docker/compose/bookloredocker compose config

拉取镜像并启动：

docker compose pulldocker compose up -ddocker compose logs -f

检查状态：

docker ps --format ”table {{.Names}}\t{{.Status}}\t{{.Ports}}”curl -I http://127.0.0.1:6060/

正常情况下应看到：

booklore          Up ...          0.0.0.0:6060->6060/tcpbooklore-mariadb  Up ... healthy  3306/tcp

然后打开 http://YOUR_SERVER_LAN_IP:6060/，首次进入页面后按提示创建管理员账号。

十、反向代理与 HTTPS

生产环境建议放到 HTTPS 域名后面，不建议长期直接暴露 http://IP:6060。

Nginx / OpenResty 示例：

server {    listen 443 ssl;    server_name books.example.com;    ssl_certificate /path/to/fullchain.pem;    ssl_certificate_key /path/to/privkey.pem;    client_max_body_size 1024m;# 允许上传较大的电子书或漫画压缩包    location / {        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;        proxy_http_version 1.1;    }}

如果 80/443 被封，可以使用自定义 HTTPS 端口：

listen 8443 ssl;# 实际端口请按自己的环境调整

自定义端口访问示例：https://books.example.com:8443/

如果通过 1Panel 配置反向代理：网站类型选反向代理、代理地址填 http://127.0.0.1:6060、开启 HTTPS 证书、上传文件较大时调高上传大小限制、若使用自定义 HTTPS 端口要确认 OpenResty 已监听该端口。

十一、书库目录规划

建议书库结构尽量清楚，但不要为了 BookLore 过度改动原始文件。

books/# 主书库根目录  小说/# 按类型或主题划分的一级分类    示例书名/# 同一本书的多格式文件可放在同一个文件夹      示例书名.epub      示例书名.pdf  漫画/# 漫画或图像类书籍分类    示例漫画.cbzbookdrop/# 自动导入投递目录  待导入.epub

实践建议：

• 同一本书的不同格式放在同一个书名文件夹，便于后续合并为一本书的多个格式。
• 系列图书放在系列文件夹里，再在 BookLore 中检查系列元数据。
• NAS 网络挂载书库建议 DISK_TYPE=NETWORK。
• 不要让自动整理工具和 BookLore 同时改同一批文件。
• 批量导入前先备份原始书库。

十二、BookDrop 与元数据流程

BookDrop 的典型流程：

1. 把文件放入 bookdrop/。
2. BookLore 自动检测新增文件。
3. 解析文件名、格式和基础元数据。
4. 从元数据源拉取封面、简介、作者、评分等信息。
5. 在 Web 页面审核。
6. 确认后导入书库。

如果元数据匹配错误，优先在入库前人工修正，尤其是：同名不同作者、套装书、多卷系列、中英文混合书名、扫描版 PDF、漫画卷号。

十三、OPDS、Kobo 与 KOReader

BookLore 可以作为电子书客户端的服务端书库：

• 支持 OPDS 的阅读器可通过 OPDS 地址浏览书库。
• Kobo 可用于同步书籍和阅读进度。
• KOReader 可用于跨设备阅读体验。

公开部署 OPDS 时要注意：

• 不要把无认证的 OPDS 暴露到公网。
• 尽量放在 HTTPS 后面。
• 多用户环境下检查每个用户的书库权限。
• 如果走反向代理，确认外部访问地址和代理头设置正确。

十四、备份与恢复

必须备份：

docker-compose.yml# 容器编排、端口、卷挂载和环境变量引用.env# 数据库密码、UID/GID、时区和存储模式data/# BookLore 应用数据mariadb/config/# MariaDB 数据库文件books/# 电子书原始文件bookdrop/# 待导入文件，按需要备份

简单备份命令：

cd /opt/1panel/docker/composetar -czf booklore-backup-$(date +%F).tar.gz booklore

更稳的备份策略：

• 数据库目录和书库目录都要备份。
• 升级前单独做一次完整压缩包。
• 书库在 NAS 上时，确认 NAS 端也有快照或版本备份。
• 大书库建议用 restic、kopia、rsync、ZFS 快照等工具增量备份。

恢复时的基本顺序：

cd /opt/1panel/docker/composetar -xzf booklore-backup-YYYY-MM-DD.tar.gzcd bookloredocker compose up -ddocker compose logs -f

十五、升级方法

升级前先备份：

cd /opt/1panel/docker/composetar -czf booklore-before-upgrade-$(date +%F).tar.gz booklore

升级：

cd /opt/1panel/docker/compose/bookloredocker compose pulldocker compose up -ddocker compose logs -f

检查：

docker ps --format ”table {{.Names}}\t{{.Status}}\t{{.Ports}}”curl -I http://127.0.0.1:6060/

升级注意：

• 不要在未备份数据库的情况下升级。
• 不要随意更换 MariaDB 主版本。
• 如果从 latest 切到固定版本，要先确认版本迁移说明。
• 升级后检查登录、书库列表、封面、阅读器、OPDS 和 BookDrop。
• 如果使用 1Panel 编辑容器配置，注意它可能覆盖手工修改过的 compose 文件。

十六、常见故障排查

十七、安全上线清单

上线前逐项检查：

• 使用 HTTPS。
• 管理员账号使用强密码。
• 不公开无认证 OPDS。
• 不公开数据库端口。
• .env
   不分享、不上传公开仓库。
• 反向代理限制上传大小但不要无限放开。
• NAS 书库使用 DISK_TYPE=NETWORK。
• 数据库和书库目录都有备份。
• 外网访问时尽量加反向代理认证或访问控制。

十八、一句话结论

BookLore 的价值在于：它把电子书文件、元数据、阅读器、阅读进度、书架、系列、OPDS 和设备同步整合成一个自托管书库中心。部署时最重要的不是"跑起来"，而是把存储模式、数据库备份、书库备份和 HTTPS 入口设计好。

你是在 NAS、家用小主机，还是云 VPS 上折腾书库？BookLore 的 BookDrop 自动导入和 Kobo 同步，你更想先用哪一个？欢迎在评论区聊聊。