Calibre Web 0.6.27 常用 CLI 命令详解
Calibre Web 0.6.27 常用 CLI 命令详解：cps.py 启动参数全表、calibredb 书库管理命令矩阵（list/search/add/set_metadata/export/remove 逐条实测）、ebook-convert 与 kepubify 转换命令实录。
Calibre Web 0.6.27 常用 CLI 命令详解
目标：把围绕 Calibre Web 0.6.27 的三组命令行工具——服务本体 cps.py、书库管理 calibredb、格式转换 ebook-convert/kepubify——逐一实测：参数全表照抄 help 输出，每条常用命令配真实执行回显，并把报错原样沉淀为排障实录。组件选型见《Calibre Web 0.6.27 介绍与选型指南》（https://www.quzuo.net/document/aCwBuRNpnK2Z），部署过程见《Calibre Web 0.6.27 Docker Compose 部署指南》（https://www.quzuo.net/document/AGUdUkTOyiZ7），参数含义见《Calibre Web 0.6.27 配置参数详解》（https://www.quzuo.net/document/TU99G1ze2gZR）。
本文所有命令均在部署服务的运行环境内执行（进入《Calibre Web 0.6.27 Docker Compose 部署指南》搭建的环境，服务安装目录为 /app/calibre-web，书库位于 /books，calibre 9.17.0 套件位于 /opt/calibre）。书库初始包含 3 本书：id 1《Alice's Adventures in Wonderland》、id 2《Frankenstein; or, The modern Prometheus》、id 3《中文元数据测试样例书》。
一、CLI 工具总览
1.1 三组命令与所在位置
| 命令 | 所在路径 | 管什么 |
|---|---|---|
| cps.py | /app/calibre-web/cps.py | 服务本体：启动、端口/地址、TLS、密码重置 |
| calibredb | /opt/calibre/calibredb | 书库：建库、查询、入库、元数据、导出、删除 |
| ebook-convert | /opt/calibre/ebook-convert | 格式转换：EPUB→MOBI/AZW3 等 |
| kepubify | /usr/bin/kepubify | KEPUB 专用轻量转换 |
calibredb 与 ebook-convert 来自 calibre 官方套件（部署篇第七章注入的 9.17.0），kepubify 是部署方式自带版本。
1.2 执行前置确认
先确认三件工具的版本（实测回显）：
$ python3 /app/calibre-web/cps.py -v
Calibre-Web version: 0.6.27 -2026-08-08T16:13:10+02:00
$ /opt/calibre/calibredb --version
calibredb (calibre 9.17)
$ /opt/calibre/ebook-convert --version
ebook-convert (calibre 9.17.0)
Created by: Kovid Goyal <kovid@kovidgoyal.net>
$ /usr/bin/kepubify --version
kepubify v4.0.4
Kepubify v4.0.4
二、cps.py 服务启动命令
2.1 启动参数全表
python3 /app/calibre-web/cps.py --help 输出全文（实测照抄）：
usage: cps.py [-h] [-p path] [-g path] [-c path] [-k path] [-o path] [-v]
[-i ip-address] [-m] [-s user:pass] [-l] [-d] [-r]
Calibre Web is a web app providing a interface for browsing, reading and
downloading eBooks
options:
-h, --help show this help message and exit
-p path path and name to settings db, e.g. /opt/cw.db
-g path path and name to gdrive db, e.g. /opt/gd.db
-c path path and name to SSL certfile, e.g. /opt/test.cert, works
only in combination with keyfile
-k path path and name to SSL keyfile, e.g. /opt/test.key, works only
in combination with certfile
-o path path and name Calibre-Web logfile
-v, --version Shows version number and exits Calibre-Web
-i ip-address Server IP-Address to listen
-m Use Memory-backend as limiter backend, use this parameter in
case of miss configured backend
-s user:pass Sets specific username to new password and exits Calibre-Web
-l Allow loading covers from localhost
-d Dry run of updater to check file permissions in advance and
exits Calibre-Web
-r Enable public database reconnect route under /reconnect
2.2 参数逐条说明
| 参数 | 用途 | 实测备注 |
|---|---|---|
| -p | 指定站点配置库路径 | 部署方式默认把配置库放在 /config/app.db 并以环境变量注入，无需手传；自建裸进程场景才需要 |
| -g | 指定云端硬盘集成库路径 | 未启用云存储集成时用不到 |
| -c / -k | TLS 证书与私钥 | 二者必须成对使用；证书放配置目录挂载进服务后，在启动命令上追加即可开启 HTTPS |
| -o | 指定日志文件路径 | 不传时日志输出到标准输出 |
| -i | 监听地址 | 默认监听所有地址；只需本机访问时传 127.0.0.1 |
| -m | 限速器改用内存后端 | 限速后端配置损坏时的自救参数 |
| -s | 离线重置指定用户密码 | user:pass 格式，执行后立即退出；管理员忘记密码时的最短恢复路径 |
| -l | 允许从 localhost 加载封面 | 特定网络隔离场景使用 |
| -d | 更新器预演（检查文件权限） | 升级前预检，检查完退出 |
| -r | 开放 /reconnect 公共路由 | 书库连接断开后供前端触发重连 |
2.3 常用启动组合示例
# 常规启动（部署方式默认形态，参数由环境变量注入）
python3 /app/calibre-web/cps.py
# 以指定配置库与监听地址启动
python3 /app/calibre-web/cps.py -p /config/app.db -i 0.0.0.0
# 开启 HTTPS（证书与私钥成对）
python3 /app/calibre-web/cps.py -c /config/cert.pem -k /config/key.pem
# 离线重置 admin 密码后退出（忘记密码恢复）
python3 /app/calibre-web/cps.py -s admin:NewPass@2026
三、calibredb 书库管理命令
3.1 命令清单
calibredb --help 列出的全部子命令（实测照抄）：
command is one of:
list
add
remove
add_format
remove_format
show_metadata
set_metadata
export
catalog
saved_searches
add_custom_column
custom_columns
remove_custom_column
set_custom
restore_database
check_library
list_categories
backup_metadata
clone
embed_metadata
search
fts_index
fts_search
子命令帮助：calibredb <command> --help。所有书库操作默认作用于「设置中记录的书库路径」，对 Calibre Web 的书库需显式追加 --with-library /books（即配置参数详解篇中 config_calibre 指向的 calibredb 操作同一目录）。
3.2 建库：restore_database
空目录不能直接当书库（部署篇排障实录 1），用 calibredb 生成元数据骨架：
$ /opt/calibre/calibredb restore_database --really-do-it --with-library /books
部署篇 3.4 节实测该命令的完整过程（含先建 .calnotes 辅助目录的前置动作）。建库完成后 Calibre Web 的书库位置校验即可通过。
3.3 查询：list / search / show_metadata
list 默认列（实测回显）：
$ /opt/calibre/calibredb list --with-library /books
id title authors
1 Alice's Adventures in Wonderland Lewis Carroll
2 Frankenstein; or, The modern Mary Wollstonecraft
Prometheus Shelley
3 中文元数据测试样例书 张三丰
list 自定义列（实测回显）：
$ /opt/calibre/calibredb list --with-library /books -f title -f authors -f author_sort
id author_sort
1 Carroll, Lewis
2 Shelley, Mary Wollstonecraft
3 张三丰
search 关键词检索（实测回显，返回命中 id 逗号分隔）：
$ /opt/calibre/calibredb search "Frankenstein" --with-library /books
2,5
$ /opt/calibre/calibredb search "张三丰" --with-library /books
3
中文关键词检索正常命中。
show_metadata 单本详情（实测回显，书 id=2）：
$ /opt/calibre/calibredb show_metadata 2 --with-library /books
Title : Frankenstein; or, The modern Prometheus
Title sort : Frankenstein; or, The modern Prometheus
Author(s) : Mary Wollstonecraft Shelley [Shelley, Mary Wollstonecraft]
Tags : Science fiction, Horror tales, Gothic fiction, Scientists -- Fiction, Monsters -- Fiction, Frankenstein, Victor (Fictitious character) -- Fiction, Frankenstein's monster (Fictitious character) -- Fiction
Languages : eng
Timestamp : 2026-10-26T11:46:26+00:00
Published : 1993-10-01T00:00:00+00:00
Identifiers : id:http://www.gutenberg.org/84
3.4 入库：add（含重复拒绝实录）
把一份 EPUB 副本入库（实测回显）：
$ /opt/calibre/calibredb add /tmp/d1tmp.epub --with-library /books
Failed to render /tmp/calibre-97iaqoci/w95xz6_y_epub_meta/OEBPS/nav.xhtml with errors:
Traceback (most recent call last):
...
ImportError: cannot import name 'QWebEnginePage' from 'qt.webengine' (.../qt/webengine.pyc)
The following books were not added as they already exist in the database (see --duplicates option or --automerge option):
中文元数据测试样例书
/tmp/d1tmp.epub
两点实测结论：
- 开头的 QWebEnginePage ImportError 是 calibre 渲染 EPUB 目录页时的告警，不影响 add 主流程（排障实录 5.1）。
- 与库中现有书判定重复时拒绝加入，需要
--duplicates（强制加入副本）或--automerge（合并格式）才会放行。本例一份中文样例 EPUB 的副本被拒，正好演示了去重行为。
换一份库里没有同名的 MOBI 文件即可正常入库（本篇 3.5 节的实测对象 id=5 即以这种方式存在于库中）。
3.5 元数据：set_metadata（中文作者与罗马化排序）
set_metadata 按 id 逐字段更新。实测把书 id=5 的作者改为中文并显式指定排序串：
$ /opt/calibre/calibredb set_metadata 5 --with-library /books --field authors:"张三丰" --field author_sort:"Zhang San Feng"
命令执行后立即回显更新后的元数据（节选）：
Author(s) : 张三丰 [Zhang San Feng]
再用 list 验证 author_sort 字段（实测回显）：
$ /opt/calibre/calibredb list --with-library /books -f title -f authors -f author_sort
id author_sort
1 Carroll, Lewis
2 Shelley, Mary Wollstonecraft
3 张三丰
5 Zhang San Feng
实测结论：--field author_sort 可以显式指定中文作者的拉丁排序串（Zhang San Feng），这正是 Calibre Web 网页端「字母排序」列表能正确归位中文作者的底层机制；不显式指定时（id=3），author_sort 保留作者原文「张三丰」。
3.6 导出：export
实测导出书 id=5 到指定目录：
$ /opt/calibre/calibredb export 5 --with-library /books --to-dir /tmp/d1export --dont-save-cover
$ find /tmp/d1export -type f
/tmp/d1export/Zhang San Feng/Frankenstein; or, The modern Prometheus/Frankenstein; or, The modern Prometheus - Zhang San Feng.opf
/tmp/d1export/Zhang San Feng/Frankenstein; or, The modern Prometheus/Frankenstein; or, The modern Prometheus - Zhang San Feng.mobi
导出目录按「作者排序串/书名/书名 - 作者排序串.格式」三级组织——改过 author_sort 后导出路径立即跟随（上例中的 Zhang San Feng 目录名），书目文件与 .opf 元数据伴随导出。
3.7 删除：remove
$ /opt/calibre/calibredb remove 5 --with-library /books --permanent
$ /opt/calibre/calibredb list --with-library /books
id title authors
1 Alice's Adventures in Wonderland Lewis Carroll
2 Frankenstein; or, The modern Mary Wollstonecraft
Prometheus Shelley
3 中文元数据测试样例书 张三丰
remove 成功时无输出，list 确认 id=5 已消失。--permanent 表示永久删除（不进回收式移除）。操作不存在的 id 会直接报错：No book with id: 4 in the database（export 的报错形态为 KeyError: 'No book with id 4 present'）。
3.8 书库一致性：check_library
对书库做文件级一致性核查（命令清单中的 check_library），无输出即代表书目与磁盘文件一一对应；该书库在全部增删实测结束后执行确认无残留。
四、格式转换命令
4.1 ebook-convert：EPUB→AZW3（成功实录）
$ /opt/calibre/ebook-convert /tmp/d1tmp.epub /tmp/d1out.azw3
Serializing resources...
Splitting markup on page breaks and flow limits, if any...
Creating KF8 output
Generating KF8 markup...
Compressing markup...
Creating indices...
AZW3 output written to /tmp/d1out.azw3
Output saved to /tmp/d1out.azw3
$ ls -la /tmp/d1out.azw3
-rw-r--r-- 1 root root 11681 Oct 26 20:28 /tmp/d1out.azw3
调用形态就是「输入文件 + 输出文件（扩展名即目标格式）」，MOBI/KEPUB 同理替换扩展名。Calibre Web 网页端发起的转换任务（配置参数详解篇 5.3）底层就是服务进程以等价参数调用该命令。
4.2 ebook-convert：EPUB→PDF（环境限制实录）
$ /opt/calibre/ebook-convert /tmp/d1tmp.epub /tmp/d1out.pdf
File "calibre/ebooks/conversion/plugins/pdf_output.py", line 215, in specialize_options
ImportError: cannot import name 'QWebEnginePage' from 'qt.webengine' (.../qt/webengine.pyc)
PDF 输出依赖 Qt WebEngine 图形栈，本部署环境按部署篇方案 B 注入的 calibre 套件缺该组件，转换失败。EPUB→AZW3/MOBI/KEPUB 不受影响。此为精简环境下的已知限制（部署篇排障实录 6 同源）。
4.3 kepubify：EPUB→KEPUB（成功实录）
$ /usr/bin/kepubify --output /tmp/d1out.kepub.epub /tmp/d1tmp.epub
Kepubify v4.0.4
[ 1/ 1] Converting /tmp/d1tmp.epub
1 total: 1 converted, 0 copied, 0 skipped, 0 errored
$ ls -la /tmp/d1out.kepub.epub
-rw------- 1 root root 2546 Oct 26 20:28 /tmp/d1out.kepub.epub
kepubify 是单二进制零依赖工具，--output 指定输出文件名（KEPUB 实质是带 Kobo 优化标记的 EPUB，输出扩展名保持 .epub）。
4.4 服务内转换与手动命令的分工
| 场景 | 用哪种 | 说明 |
|---|---|---|
| 常规单本/批量转换 | 网页端「转换书」 | 走服务任务队列，产物自动挂到书目下 |
| 脚本化批量/流水线 | ebook-convert / kepubify 手动执行 | 产物需自行入库（add/add_format） |
| Kobo 专用 KEPUB | 网页端或 kepubify | 服务端由 config_binariesdir/kepubify 路径驱动（配置参数详解篇第五章） |
五、排障实录
5.1 add 时渲染告警（QWebEnginePage）
现象：calibredb add 一本 EPUB 时先吐一段 nav.xhtml 渲染失败的 ImportError 堆栈。 结论：这是 calibre 元数据读取器渲染目录页的可选步骤失败告警，书本仍正常解析入库/去重判断；与 4.2 的 PDF 转换失败同源（缺 Qt WebEngine），但影响面小得多。
5.2 add 重复书被拒
现象：The following books were not added as they already exist in the database。
原因：calibredb 按书名+作者判重。
解决：确需保留副本时追加 --duplicates；同书多格式场景用 --automerge 合并。
5.3 PDF 输出依赖缺失
现象：ebook-convert 转 PDF 报 ImportError: cannot import name 'QWebEnginePage'。
原因：PDF 输出插件依赖 Qt WebEngine，注入的精简 calibre 环境未含该组件。
解决：补齐 Qt WebEngine 运行时，或放弃 PDF 目标格式改用 AZW3/MOBI/KEPUB。
5.4 操作不存在的书目 id
现象：set_metadata 报 No book with id: 4 in the database；export 报 KeyError: 'No book with id 4 present'。
原因：add 被判重拒收后 id 并未分配，后续按预想 id 操作落空。
解决：任何写入/导出前先 calibredb list 或 calibredb search 确认目标 id 真实存在。
六、命令速查表
| 目标 | 命令 |
|---|---|
| 看版本 | python3 /app/calibre-web/cps.py -v |
| 离线重置密码 | python3 /app/calibre-web/cps.py -s admin:NewPass@2026 |
| 建空书库 | /opt/calibre/calibredb restore_database --really-do-it --with-library /books |
| 列出书目 | /opt/calibre/calibredb list --with-library /books |
| 检索书目 | /opt/calibre/calibredb search "关键词" --with-library /books |
| 看单本详情 | /opt/calibre/calibredb show_metadata <id> --with-library /books |
| 入库 | /opt/calibre/calibredb add <文件> --with-library /books |
| 改元数据 | /opt/calibre/calibredb set_metadata <id> --with-library /books --field authors:"作者" --field author_sort:"排序串" |
| 导出 | /opt/calibre/calibredb export <id> --with-library /books --to-dir <目录> |
| 删除 | /opt/calibre/calibredb remove <id> --with-library /books --permanent |
| 转 AZW3/MOBI | /opt/calibre/ebook-convert <输入> <输出> |
| 转 KEPUB | /usr/bin/kepubify --output <输出> <输入> |
七、参考链接
- 项目仓库：https://github.com/janeczku/calibre-web
- calibre 官方手册 calibredb 章节：https://manual.calibre-ebook.com/generated/en/calibredb.html
- kepubify 官方仓库：https://github.com/pgaskin/kepubify
- 《Calibre Web 0.6.27 介绍与选型指南》：https://www.quzuo.net/document/aCwBuRNpnK2Z
- 《Calibre Web 0.6.27 Docker Compose 部署指南》：https://www.quzuo.net/document/AGUdUkTOyiZ7
- 《Calibre Web 0.6.27 配置参数详解》：https://www.quzuo.net/document/TU99G1ze2gZR