Calibre Web 0.6.27 Docker Compose 部署指南
Calibre Web 0.6.27 Docker Compose 从零部署实录：镜像选型与版本锚定、卷挂载与数据持久化、书库初始化、calibre/kepubify 转换二进制 0→1 注入与验证，附六类真实排障记录。
Calibre Web 0.6.27 Docker Compose 部署指南
目标：在一台 Ubuntu 24.04 服务器上，用 Docker Compose 把 Calibre Web 0.6.27 完整跑起来：书库初始化、管理员登录、样例书上转、kepubify/calibre 转换二进制注入、EPUB→MOBI/KEPUB 转换验证，并把过程中每一个真实报错与修复动作记录成排障清单。组件选型与功能背景见《Calibre Web 0.6.27 介绍与选型指南》（https://www.quzuo.net/document/aCwBuRNpnK2Z）。
一、环境信息
| 项目 | 值 |
|---|---|
| 操作系统 | Ubuntu 24.04 LTS |
| 内核架构 | x86_64 |
| Docker Engine | 29.8.1 |
| Docker Compose | v5.5.1 |
| 组件版本 | Calibre Web 0.6.27（linuxserver 镜像） |
| 服务端口 | 8135（对外）/ 8083（服务内部端口） |
| 部署目录 | /srv/calibre-web |
| 服务器地址 | http://10.89.62.2:8135 |
Calibre Web 0.6.27 的镜像与版本锚定方式（Docker Hub 标签页，检索日期 2026-10-26）：
| 标签 | 说明 |
|---|---|
0.6.27 | 版本锚定标签（本篇采用，amd64 层约 251 MB，2026-10-25 更新） |
0.6.27-ls407 | 版本 + 构建号锚定（可复现性最强） |
latest | 滚动最新（升级不可控，不建议生产使用） |
nightly | 每日构建（尝鲜用） |
linuxserver 镜像的优势：内置 kepubify 转换二进制（v4.0.4）、标准化的 PUID/PGID 权限体系、支持通过 DOCKER_MODS 机制注入 calibre 完整运行时。官方仓库 janeczku/calibre-web 自身不发布可拉取的官方镜像，linuxserver.io 是 README 推荐的镜像维护方（来源：官方 README，检索日期 2026-10-26）。
二、前置条件
- 服务器已安装 Docker Engine 与 Compose 插件（
docker compose version可执行）； - 服务器可访问外网（拉取镜像；受限网络环境下拉取超时可为 Docker 配置 HTTP 代理）；
- 选定一个空闲端口（本篇用 8135），确认未被占用：
ss -ltn | grep 8135无输出； - 准备书库目录与配置目录的宿主路径：/srv/calibre-web/books（书库）与 /srv/calibre-web/config（站点数据）。
三、部署步骤
3.1 编写 docker-compose.yml
mkdir -p /srv/calibre-web/config /srv/calibre-web/books
cat > /srv/calibre-web/docker-compose.yml << 'EOF'
name: calibreweb-0.6.27-stack
services:
calibre-web:
image: lscr.io/linuxserver/calibre-web:0.6.27
container_name: calibreweb-0.6.27-app
environment:
- PUID=1000
- PGID=1000
- TZ=Asia/Shanghai
volumes:
- /srv/calibre-web/config:/config
- /srv/calibre-web/books:/books
ports:
- "8135:8083"
restart: unless-stopped
EOF
要点说明：
- image 用版本号标签锚定 0.6.27，避免 latest 升级漂移；
- PUID/PGID=1000：linuxserver 镜像以该 UID/GID 运行服务进程，挂载目录的属主必须与之匹配（本篇排障实录 3 正是这个坑）；
- /config 挂载：存放 app.db（站点配置/用户/书架）、日志、kepubify 路径配置等，是备份的核心目录；
- /books 挂载：Calibre 书库目录（metadata.db 与书籍文件），与 Calibre 桌面版可共用；
- 8135:8083：8083 是 Calibre Web 默认服务端口，对外映射到 8135。
3.2 拉取并启动
cd /srv/calibre-web
docker compose pull
docker compose up -d
实测回显（首次启动日志，节选）：
[migrations] started
[migrations] 00-recursive-execute-all-migration-scripts skipped
[ls.io-init] done.
Connection to localhost (127.0.0.1) 8083 port [tcp/*] succeeded!
First time run, creating app.db...
Creating a new user: admin, password: admin123
Successfully set kepubify paths in /config/app.db
首次启动自动完成三件事：创建 app.db、创建管理员 admin（初始密码 admin123）、写入内置 kepubify 路径。
3.3 首次登录与书库初始化
- 浏览器打开 http://10.89.62.2:8135 ，使用 admin / admin123 登录；
- 首次登录会强制跳转到「数据库配置」页（/admin/dbconfig），要求指定书库位置；
- 书库位置填 /books。
此时书库目录还是空的，提交会被拒绝——这是第一个必然遇到的报错（排障实录 1）：
DB Location is not Valid, Please Enter Correct Path
New db location is invalid, please enter valid path
原因：Calibre Web 要求书库位置必须是「已含 Calibre 元数据文件 metadata.db 的目录」，空目录无效。解决方案是用 calibredb 创建一个空书库（见 3.4）。
3.4 初始化空书库（calibredb restore_database）
metadata.db 由 Calibre 工具链创建。此时镜像内还没有 calibre 工具链，先执行第 4 节的转换二进制注入，再回来建库；若只需要"先跑起来"，按本节手动创建空书库即可。
calibredb 属于 calibre 工具链。本篇采用第 4.2 节的官方独立安装器方案安装 calibre 9.17.0 后，在服务器上执行：
mkdir -p /books/.calnotes
calibredb restore_database --really-do-it --with-library /books
实测回显：
Preparing /books...
Creating database files...
ID: 1, Title: Unknown
Restored database to /books with 0 books.
两个细节：
- .calnotes 目录必须先建：calibre 9.x 的 restore_database 依赖该目录，缺失时直接报错退出（排障实录 2）；
- 目录权限：书库目录需要归服务运行账号（PUID=1000）可写，否则下一步保存配置时报"DB is not Writeable"（排障实录 3）：
chown -R 1000:1000 /books
书库就绪后回到「数据库配置」页提交 /books，提示「Database Settings updated」，进入书库主界面。
3.5 修改管理员密码并验证
管理后台 → 用户 → admin → 编辑，设置新密码 q1w2e3r4 并保存，提示：
用户"admin"已更新
退出后用新密码重新登录验证通过。注意：0.6.27 默认开启密码强度校验（最少 8 位且要求数字/大小写/特殊字符），弱口令会被拒绝——报错回显与策略调整方法见《Calibre Web 0.6.27 配置参数详解》账户策略一节。
四、数据持久化说明
| 数据 | 位置 | 说明 |
|---|---|---|
| 站点配置/用户/书架 | /srv/calibre-web/config/app.db | SQLite，备份核心 |
| 服务日志 | /srv/calibre-web/config/calibre-web.log | 排障第一现场 |
| 书库元数据 | /srv/calibre-web/books/metadata.db | Calibre 书库格式 |
| 书籍文件 | /srv/calibre-web/books/作者/书名 (id)/ | 按作者/书名组织 |
| kepubify 转换器 | 服务内部 /usr/bin/kepubify | 镜像自带，随镜像更新 |
备份策略：定期备份 config/ 与 books/ 两个目录即可完整覆盖站点与书库；转换生成的 MOBI/KEPUB 文件直接落在 books 目录内（见 4.4），随书库一起备份。
五、环境变量表
| 变量 | 必填 | 默认 | 说明 |
|---|---|---|---|
| PUID | 否 | 1000 | 服务进程运行 UID，需与挂载目录属主一致 |
| PGID | 否 | 1000 | 服务进程运行 GID |
| TZ | 否 | Etc/UTC | 时区，建议 Asia/Shanghai |
| DOCKER_MODS | 否 | 空 | 注入扩展运行时，见 4.1 |
| OAUTHLIB_RELAX_TOKEN_SCOPE | 否 | 空 | 仅 Google Drive/OAuth 集成需要 |
六、配置文件挂载
Calibre Web 没有传统意义的静态配置文件，全部配置存于 /config/app.db（SQLite）中，通过管理界面修改。部署层需要挂载的只有两处：
- /srv/calibre-web/config → /config：站点数据（app.db、日志）；
- /srv/calibre-web/books → /books：书库（metadata.db + 书籍文件）。
若需使用自签 TLS 证书终止在服务层，可用 cps.py 的 -c/-k 参数（见《Calibre Web 0.6.27 常用 CLI 命令详解》），证书文件同样放入 config 目录挂载进服务。
七、转换二进制注入（0→1 实测）
默认镜像具备"浏览/阅读/下载"全部能力，但格式转换处于 0 态。实测 0 态确认（进入服务内部执行）：
ebook-convert: NOT FOUND
calibredb: NOT FOUND
kepubify --version → kepubify 4.0.4
即：kepubify 已就绪（KEPUB 转换开箱可用），calibre 工具链缺失（MOBI/AZW3 等完整转换矩阵不可用）。下面按"先轻后重"的两条路径完成 0→1。
7.1 方案 A：DOCKER_MODS 注入 calibre 运行时（官方推荐）
在 compose 的 environment 中追加：
- DOCKER_MODS=linuxserver/mods:universal-calibre
重建服务 docker compose up -d，启动时自动下载 calibre 运行时。实测在受限网络环境下连续两次重试均失败（排障实录 4），启动日志回显：
[mod-init] Downloading linuxserver/mods:universal-calibre.
[mod-init] (ERROR) Invalid tarball for linuxserver/mods:universal-calibre, skipping
该报错说明 mod 镜像层下载不完整/校验失败。处理链：先重试一次（排除网络抖动），仍失败则改走方案 B。
7.2 方案 B：官方独立安装器部署 calibre（降级方案，实测可用）
- 安装系统依赖（calibre 独立包依赖图形库，缺哪个报哪个，一次装齐）：
apt-get update
apt-get install -y libegl1 libopengl0 libxkbcommon0 libgl1 \
libglib2.0-0t64 libxcb-cursor0 xz-utils
- 下载并执行官方安装器：
curl -fsSL -o /tmp/linux-installer.sh https://download.calibre-ebook.com/linux-installer.sh
sh /tmp/linux-installer.sh
实测回显（安装器自动识别发行版、下载 193 MB 独立包并解压）：
Using python executable: /usr/bin/python3
Installing to /opt/calibre
Downloading calibre-9.17.0-x86_64.txz
Extracting files to /opt/calibre ...
- 验证安装：
/opt/calibre/ebook-convert --version
ebook-convert (calibre 9.17.0)
7.3 服务侧路径配置（实测要点）
管理后台 → 配置 → 基础配置：
- calibre 程序目录填
/opt/calibre（0.6.27 的转换器路径由该目录自动派生，保存后配置库中 ebook-convert 路径生效为 /opt/calibre/ebook-convert）； - kepubify 转换器：0.6.27 对二进制文件名有白名单校验，只接受 kepubify-linux-64bit 等标准命名（排障实录 5），需先复制一份合规命名的二进制：
cp /usr/bin/kepubify /usr/bin/kepubify-linux-64bit
然后在配置中把 kepubify 转换器指向 /usr/bin/kepubify-linux-64bit。保存成功后配置库实际记录的是其所在目录（/usr/bin），服务运行时按白名单文件名拼接定位，这是 0.6.27 的实现细节。
7.4 转换验证（1 态实测）
- 网页端：打开一本书详情页 → 「转换书」→ 选择 EPUB→MOBI / EPUB→KEPUB 提交，任务完成后详情页出现对应格式下载项；
- 产物落盘验证（书库目录）：
/books/Lewis Carroll/Alice's Adventures in Wonderland (1)/
Alice's Adventures in Wonderland - Lewis Carroll.epub
Alice's Adventures in Wonderland - Lewis Carroll.mobi
Alice's Adventures in Wonderland - Lewis Carroll.kepub
KEPUB 转换由 kepubify 4.0.4 完成，MOBI 转换由 ebook-convert（calibre 9.17.0）完成，服务日志出现 MOBI output written to ... 与 1 converted, 0 errored 字样，0→1 链路闭环。
八、等价启动命令（docker run）
与上述 compose 等价的最小启动命令（便于理解参数映射，生产建议仍用 compose）：
docker run -d \
--name calibreweb-0.6.27-app \
-e PUID=1000 -e PGID=1000 -e TZ=Asia/Shanghai \
-p 8135:8083 \
-v /srv/calibre-web/config:/config \
-v /srv/calibre-web/books:/books \
--restart unless-stopped \
lscr.io/linuxserver/calibre-web:0.6.27
九、常用运维命令
cd /srv/calibre-web
docker compose ps # 服务状态
docker compose logs -f # 跟踪启动/运行日志（mod 注入错误在这里看）
docker compose restart # 重启
docker compose pull && docker compose up -d # 升级到新版本标签
docker compose down # 停止并移除（数据在宿主目录，不受影响）
升级注意：0.6.x 版本内升级直接换镜像标签即可；跨大版本升级前先备份 config/ 与 books/。
十、常见问题（实测排障实录）
10.1 书库位置校验失败
现象：首次登录的数据库配置页提交 /books 后报 DB Location is not Valid, Please Enter Correct Path。
原因：目录内没有 Calibre 元数据文件 metadata.db，空目录不被接受。
解决：calibredb restore_database 建库（3.4 节），或先用 Calibre 桌面版在该目录建库。
10.2 calibredb 建库直接退出
现象：restore_database 无输出失败。
原因：calibre 9.x 建库依赖书库目录下的 .calnotes 目录。
解决：mkdir -p /books/.calnotes 后重试。
10.3 配置保存报 DB is not Writeable
现象：数据库配置提交后提示 DB is not Writeable。
原因：挂载目录属主是 root，而服务进程以 PUID=1000 运行，无写权限。
解决：chown -R 1000:1000 /books（config 目录同理）。
10.4 DOCKER_MODS 注入失败
现象：启动日志报 [mod-init] (ERROR) Invalid tarball for linuxserver/mods:universal-calibre, skipping，ebook-convert 未出现。
原因：mod 扩展层下载不完整或校验失败，受限网络环境多发。
解决：重启重试一次；仍失败改用官方独立安装器方案（7.2 节），并按 7.3 节在配置界面指定程序目录。
10.5 kepubify 路径校验失败
现象：基础配置保存时报 Kepubify binary not found，且整个配置表单保存中断。
原因：0.6.27 对转换二进制按标准文件名（kepubify-linux-64bit/32bit）做白名单校验，镜像内置的 /usr/bin/kepubify 命名不合规。
解决：复制为合规命名（cp /usr/bin/kepubify /usr/bin/kepubify-linux-64bit）再在配置中指向该路径。
10.6 EPUB 转 PDF 失败（MOBI/KEPUB 正常）
现象：转换任务报 ImportError: cannot import name 'QWebEnginePage' from 'qt.webengine'。
原因：ebook-convert 的 PDF 输出依赖 Qt WebEngine 图形栈；精简环境缺相关系统库。
解决：补齐图形依赖库（方案 B 的 apt 依赖清单为最小集），或避开 PDF 目标格式改走 MOBI/AZW3/KEPUB。
十一、部署验证清单
按序自检，全部通过即部署完成：
docker compose ps状态为 running；- http://10.89.62.2:8135 可打开登录页，admin/q1w2e3r4 登录成功；
- 上传一本 EPUB 后详情页书名/作者/封面正确显示；
- 「阅读」按钮可打开在线阅读器；
- EPUB→MOBI、EPUB→KEPUB 转换各执行一次并出现下载项；
- OPDS 访问 http://10.89.62.2:8135/opds 返回 XML 目录（需 Basic 认证）。
十二、参考链接
- 本专栏选型篇：《Calibre Web 0.6.27 介绍与选型指南》 https://www.quzuo.net/document/aCwBuRNpnK2Z
- linuxserver/calibre-web 镜像文档：https://docs.linuxserver.io/images/calibre-web/
- Calibre Web 官方仓库：https://github.com/janeczku/calibre-web
- Calibre Web 官方 Wiki（部署与常见问题）：https://github.com/janeczku/calibre-web/wiki
- calibre 官方下载（Linux 独立安装器）：https://download.calibre-ebook.com/
- kepubify 官方仓库：https://github.com/pgaskin/kepubify