Calibre Web 0.6.27 配置参数详解

目标：把 Calibre Web 0.6.27 的配置参数逐一过一遍——参数名、所在页面、取值、保存行为全部以实测为准，关键参数每个都做「修改 → 验证 → 恢复」闭环，并把过程中踩到的报错沉淀成排障实录。组件定位与选型背景见《Calibre Web 0.6.27 介绍与选型指南》（https://www.quzuo.net/document/aCwBuRNpnK2Z），部署过程见《Calibre Web 0.6.27 Docker Compose 部署指南》（https://www.quzuo.net/document/AGUdUkTOyiZ7）。

本文所有实测基于以下环境（与部署篇同一套服务）：

一、配置体系总览

1.1 两个配置库与四个配置入口

Calibre Web 把配置存在两个 SQLite 数据库中，实测目录 /config 下可见：

• app.db：站点级配置——服务参数、认证策略、上传与转换路径、邮件服务器、界面设置、用户账户（含权限位）。管理后台改的就是它。
• metadata.db：书库数据（Calibre 标准格式），与配置无关，由「书库位置」参数指向。

对应的配置入口共四个（均需管理员登录，实测全部可达）：

实测抓取两个页面的标题回显：

GET /admin/mailsettings -> 200
title: Calibre-Web | 编辑邮件服务器设置
GET /admin/viewconfig -> 200
title: Calibre-Web | 界面配置

1.2 配置的保存机制：AJAX 端点与整页提交

两类页面的提交端点不同，这是实测得出的关键差异：

• 基本配置（/admin/config）：表单不直接 POST 回本页——实测直接向 /admin/config 提交返回 405。真正的保存端点是 /admin/ajaxconfig，提交全部表单字段后返回 JSON。
• 界面配置（/admin/viewconfig）与邮件设置（/admin/mailsettings）：直接 POST 回本页，成功后页面闪现提示。

保存成功的响应与提示（实测回显）：

POST /admin/ajaxconfig -> 200
{"result": "Calibre-Web 配置已更新", ...}
POST /admin/viewconfig -> 200
flash: ['Calibre-Web 配置已更新']

两个端点都要求携带页面上的 csrf_token 隐藏字段，缺失时返回 400（排障实录 10.5）。

1.3 基本配置的 66 个参数

枚举 /admin/config 页面全部表单字段（实测抓取，共 71 个，剔除 csrf_token 等非配置项后 config_ 前缀参数 66 个）：

config_1_oauth_client_id, config_1_oauth_client_secret, config_2_oauth_client_id,
config_2_oauth_client_secret, config_access_log, config_access_logfile,
config_allow_reverse_proxy_header_login, config_anonbrowse, config_binariesdir,
config_calibre, config_certfile, config_check_extensions, config_embed_metadata,
config_external_port, config_goodreads_api_key, config_googlebooks_api_key,
config_kepubifypath, config_keyfile, config_kobo_proxy, config_kobo_sync,
config_ldap_authentication, config_ldap_cacert_path, config_ldap_cert_path,
config_ldap_dn, config_ldap_encryption, config_ldap_group_members_field,
config_ldap_group_name, config_ldap_group_object_filter, config_ldap_key_path,
config_ldap_member_user_object, config_ldap_openldap, config_ldap_port,
config_ldap_provider_url, config_ldap_serv_password_e, config_ldap_serv_username,
config_ldap_user_object, config_limiter_options, config_limiter_uri,
config_log_level, config_logfile, config_login_type, config_password_character,
config_password_lower, config_password_min_length, config_password_number,
config_password_policy, config_password_special, config_password_upper,
config_port, config_public_reg, config_rarfile_location, config_ratelimiter,
config_register_email, config_remote_login, config_reverse_proxy_login_header_name,
config_reverse_proxy_login_header_secret_e, config_reverse_proxy_login_secret_header_name,
config_reverse_proxy_trusted_ips, config_reverse_proxy_use_shared_secret,
config_session, config_trustedhosts, config_unicode_filename, config_updatechannel,
config_upload_formats, config_uploading, config_use_goodreads

下文按功能组逐项讲解，参数当前值均为实测回显。

二、服务基础与日志参数

2.1 服务端口与访问参数

实测当前值：

config_port          = '8083'
config_external_port = '8083'
config_trustedhosts  = ''

2.2 日志与运行模式

下拉参数实测选项（照抄页面 option）：

config_updatechannel  options=[('0', '稳定版'), ('2', '夜间版')]
config_log_level      options=[('10', 'DEBUG'), ('20', 'INFO'), ('30', 'WARNING'), ('40', 'ERROR')]
config_session        options=[('0', '基本'), ('1', '强')]

文本参数实测值：config_logfile = ''（空表示输出到标准输出）、config_access_log = 未勾选、config_access_logfile = ''。

实测排障提示：ajaxconfig 提交时这些下拉字段不能为空串——config_login_type、config_log_level 等整型字段若提交空值，服务端 int('') 直接抛 500（排障实录 10.1）。正确做法是按页面第一个选项的值提交（上表每组的第一个即浏览器未选择时的默认值）。

三、登录认证与账户策略

3.1 认证方式与登录类型

config_login_type 的三个选项（实测照抄）：0=使用标准认证、1=使用 LDAP 认证、2=使用 OAuth 认证。

标准认证之外的两套参数组在页面中平行存在：LDAP 组（config_ldap_provider_url、config_ldap_port、config_ldap_dn、config_ldap_encryption、config_ldap_authentication 等 16 个参数）与 OAuth 组（config_1/2_oauth_client_id/secret）。本实例使用标准认证，未展开实测这两组。

反向代理登录相关参数组：config_allow_reverse_proxy_header_login、config_reverse_proxy_login_header_name、config_reverse_proxy_login_secret_header_name、config_reverse_proxy_trusted_ips 等；配合限速参数 config_ratelimiter（开关）与 config_limiter_uri、config_limiter_options。

3.2 密码策略参数（实测关闭弱密码限制）

密码策略共 7 个参数：总开关 config_password_policy、长度下限 config_password_min_length，以及 5 个字符类要求开关 config_password_number、config_password_lower、config_password_upper、config_password_character、config_password_special（字段名实测照抄，5 个开关分别约束数字、小写、大写与其他字符类的组合）。

实测结论：默认策略开启时，把 admin 密码改为 q1w2e3r4 被拒绝（8 位但强度不足策略要求）；将上述策略开关字段从提交载荷中剔除（HTML 表单未勾选的 checkbox 不提交，等价于取消勾选）后再次提交 ajaxconfig，改密成功——此后全部实测均以 admin / q1w2e3r4 登录。

这是 Calibre Web 配置机制的重要细节：checkbox 参数「不提交」与「提交空值」都表示关闭，而漏提交整型参数则可能引发 500，见排障实录。

3.3 注册策略参数（开放注册闭环）

两个相关参数：

• config_public_reg：开放注册总开关。
• config_register_email：注册需邮箱验证。

修改-验证-恢复闭环（实测回显）：

config_public_reg initial: on | checked: checked
LOOP3 POST ajaxconfig(public_reg off) -> 200 | state: unchecked
LOOP3 GET /register (off) -> 404
LOOP3 POST ajaxconfig(public_reg on) -> 200 | state: checked
LOOP3 GET /register (on) -> 200 | 注册表单可见: True

结论：config_public_reg 关闭后，未登录访问 /register 直接 404（不是 403，注册页对外彻底隐身）；重新开启后恢复 200 且注册表单可见。config_register_email 开关切换不影响 /register 页面可达性（实测 off 时 /register 仍 200），它只影响注册流程是否要求邮箱验证环节。

3.4 匿名浏览参数（含 OPDS 联动）

config_anonbrowse：开启后未登录访客以内置 Guest 身份浏览书库。

修改-验证-恢复闭环（实测回显）：

LOOP2 POST ajaxconfig(anon off) -> 200 | state: unchecked
LOOP2 GET / (noauth, off) -> 302
LOOP2 POST ajaxconfig(anon on) -> 200 | state: checked
LOOP2 GET / (noauth, on) -> 200 | Calibre-Web | Books

结论：关闭后未登录访问首页被 302 重定向到登录页；开启后返回 200 且标题为「Calibre-Web | Books」。

该参数还有一处不显眼的联动——OPDS 端点的认证行为（见第八章 8.1 实测）：关闭时 OPDS 未认证返回 401 要求 Basic 认证，开启时未认证也能以 Guest 身份拿到订阅源。

3.5 远程登录参数

config_remote_login：登录页展示「远程登录」按钮，配合移动端扫码场景；本实例未启用，仅确认参数存在且可勾选。

四、上传配置

4.1 上传总开关与允许格式（修改-验证闭环）

config_uploading 是上传功能总开关；config_upload_formats 控制允许的文件格式。实测当前值：

config_uploading  = on
config_upload_formats = 'mp3,odt,azw3,txt,fb2,wav,cbz,mp4,epub,pdf,opus,docx,cbr,cbt,cb7,flac,djvu,m4a,kepub,rtf,m4b,mobi,ogg,doc,lit,prc,djv,html,azw'

共 29 种格式，覆盖电子书（epub/mobi/azw3/kepub/fb2/…）、漫画（cbz/cbr/cbt/cb7）、音频（mp3/m4a/opus/flac/ogg/wav/m4b）与文档（pdf/docx/doc/html/rtf/txt/lit/prc）。

修改-验证-恢复闭环（实测回显）：

LOOP1 POST ajaxconfig(upload off) -> 200 | result: {"config_upload": "mp3,odt,azw3,txt,fb2,...", ...}
LOOP1 state config_uploading: unchecked
LOOP1 POST /upload (off) -> 400
LOOP1 POST ajaxconfig(upload on) -> 200 | state: checked

结论：关闭总开关后，以管理员身份向 /upload 提交合法 EPUB 得到 400（上传动作在配置层被拦下，与管理员个人的上传权限无关）；重新开启后上传恢复。

注意双层校验：全局开关 config_uploading 之外，每个用户还有自己的上传权限位（第九章），两者同时满足才能上传。实测中管理员账号曾因权限位缺失（role=475，缺上传位）得到 403——把权限位补齐（role=479）后恢复，这正是位掩码中「上传」位的值 4（详见 9.1）。

4.2 上传行为参数

• config_unicode_filename：上传文件名是否允许 Unicode 字符。关闭时中文文件名会被转写，开启后保留原名。实测书库中的中文书名文件上传后正常入库。
• config_check_extensions：上传时校验扩展名与文件实际内容（防扩展名伪装）。

五、格式转换参数

5.1 三个路径参数

实测当前值：

config_calibre      = '/opt/calibre/calibredb'
config_kepubifypath = '/usr/bin'
config_binariesdir  = '/opt/calibre'

5.2 kepubify 路径的白名单校验

实测排障结论：0.6.27 保存 config_kepubifypath 时按标准文件名（kepubify-linux-64bit 等）做白名单校验——把路径指向 /usr/bin/kepubify 时提交被拒（flash 提示 Kepubify binary not found，且整个表单都不会保存）。解决方案是先复制一份合规命名副本再指向它：

cp /usr/bin/kepubify /usr/bin/kepubify-linux-64bit

提交 /usr/bin/kepubify-linux-64bit 成功后，回读页面 config_kepubifypath 显示 /usr/bin——校验通过后落库的是其所在目录，运行时按白名单文件名拼接定位。

5.3 config_binariesdir 与转换器派生

0.6.27 没有为 ebook-convert 提供独立的提交入口，转换器路径由 config_binariesdir 派生：提交 config_binariesdir=/opt/calibre 后，服务端在该目录下定位 ebook-convert。实测注入 calibre 套件前后对比：注入前转换请求报「转换器未找到」；注入并提交路径后，EPUB→MOBI/KEPUB/AZW3 转换全部成功（部署篇第七章有完整 0→1 注入过程）。

5.4 内嵌元数据开关

config_embed_metadata：开启后下载/推送时把书库元数据写回电子书文件本体。开关性质同上传参数（checkbox）。

六、界面配置详解

6.1 界面配置参数总表

枚举 /admin/viewconfig 页面全部表单字段（实测抓取，40 个）：

config_calibre_web_title, config_books_per_page, config_random_books,
config_authors_max, config_theme, config_columns_to_ignore, config_read_column,
config_restricted_column, config_title_regex, admin_role, download_role,
viewer_role, upload_role, edit_role, delete_role, passwd_role, edit_shelf_role,
config_default_locale, config_default_language, show_16, show_65536, show_128,
show_256, show_32, show_8, show_4, show_64, show_4096, show_2, show_8192,
show_16384, show_32768, show_131072, Show_detail_random, add_element,
submit_allow, submit_deny

当前值实测回显（关键项）：

config_calibre_web_title = 'Calibre-Web'
config_books_per_page    = '60'
config_random_books      = '4'
config_authors_max       = '0'
config_title_regex       = "^(A|The|An|Der|Die|Das|Den|Ein|Eine|Einen|Dem|Des|Einem|Eines|Le|La|Les|L'|Un|Une)(\\s+|(?<='))"
viewconfig checked: ['Show_detail_random', 'admin_role', 'delete_role', 'download_role',
 'edit_role', 'edit_shelf_role', 'passwd_role', 'show_128', 'show_131072', 'show_16',
 'show_16384', 'show_2', 'show_256', 'show_32', 'show_32768', 'show_4', 'show_4096',
 'show_64', 'show_65536', 'show_8', 'show_8192', 'upload_role', 'viewer_role']

6.2 站点标题与列表分页（修改-验证-恢复闭环）

实测把标题改为「我的书库」、每页数量改为 24，提交后立即回首页验证：

POST viewconfig(我的书库/24) -> 200 | flash: ['Calibre-Web 配置已更新'] | 验证 title: 我的书库 | 书籍
POST viewconfig(Calibre-Web/60) -> 200 | 验证 title: Calibre-Web | 书籍

闭环成立：config_calibre_web_title 直接决定浏览器标题前缀；config_books_per_page 控制书库列表每页条数。

6.3 主题与语言

下拉参数实测选项（照抄页面 option）：

config_theme            options=[('0', '标准主题'), ('1', '黑暗主题')]
config_default_locale   options=[('de', 'Deutsch'), ('en', 'English'), ('es', 'Español'), ('fr', 'Français'), ('gl', 'Galego'), ('id', 'Indonesia'), ('it', 'Italiano'), ('hu', 'Magyar'), ...]
config_default_language options=[('all', '显示全部'), ('zho', '中文'), ('eng', '英语'), ...]

• config_theme：0/1 两档，即标准与黑暗主题。
• config_default_locale：新用户与匿名访客的界面语言（完整选项含 20+ 语言），本实例部署时用户级别已设 zh_Hans_CN。
• config_default_language：书库元数据语言过滤默认值，zho 即中文。

6.4 标题排序正则与作者显示

• config_title_regex：排序时从书名开头剔除的冠词正则，默认值如上（A/The/An + 德语/法语冠词）。中文书名不受影响。
• config_authors_max：书籍卡片最多展示的作者数，0 表示不限制。
• config_columns_to_ignore / config_read_column / config_restricted_column：自定义列相关——read_column 选择「已读」标记的自定义列、restricted_column 选择权限过滤列，下拉选项实测为 [('0', '')] 与 [('0', '无')]（书库未建自定义列）。

6.5 侧栏显示开关（show_* 位标识）

show_2、show_4、show_8、show_16、show_32、show_64、show_128、show_256、show_4096、show_8192、show_16384、show_32768、show_65536、show_131072 共 14 个开关，对应侧栏各功能入口（热门、最近、随机、分类、系列、作者、出版社、格式、归档、阅读列表等），位值与用户权限位体系同源。实测当前全部勾选。

Show_detail_random：随机书籍卡片是否显示详情，实测勾选。

6.6 新用户默认角色组

admin_role、download_role、viewer_role、upload_role、edit_role、delete_role、passwd_role、edit_shelf_role 8 个开关定义新注册用户的默认权限位，实测当前全部勾选（即新用户默认可下载、可阅读、可上传等）。与用户级权限位的关系见 9.1。

七、邮件推送配置

7.1 邮件服务器参数总表

枚举 /admin/mailsettings 字段（实测抓取）：

mail_server_type  select
mail_server       input  mail.example.org
mail_port         input  25
mail_use_ssl      select
mail_login        input  mail@example.com
mail_password_e   input
mail_from         input  automailer <mail@example.com>
mail_size         input  25
domainname        input

7.2 修改-验证-恢复闭环

实测把 mail_server 改为 smtp.invalid.example 提交，回读验证，再恢复：

LOOP4 origin mail_server='mail.example.org' mail_port='25' mail_from='automailer <mail@example.com>' mail_server_type='0' mail_use_ssl='0'
LOOP4 POST mailsettings(server=smtp.invalid.example) -> 200 | flash: ['邮件服务器设置已更新']
LOOP4 verify mail_server = smtp.invalid.example
LOOP4 restore -> 200 | verify mail_server = mail.example.org

闭环成立：mailsettings 整页 POST（需带 csrf_token）即时生效，flash 提示「邮件服务器设置已更新」。注意 mail_from 的值形如 automailer <mail@example.com>，包含尖括号时页面以 HTML 实体回显（</>），提交时无需转义。

八、OPDS 与 Kobo 配置

8.1 OPDS 端点与匿名浏览联动

基本配置页面没有专门的 OPDS 开关——OPDS 订阅源默认可用，其可见性由 config_anonbrowse 间接控制。实测三组请求：

OPDS /opds (basic) -> 200 | entries: 3 | titles: ['Calibre-Web', '字母排序书籍', '最近添加的书籍', '书架列表']
OPDS noauth (anon off) -> 401
OPDS noauth (anon on) -> 200 | entries: 3
OPDS basic (anon on) -> 200 | entries: 3

实测结论：

• 带管理员 HTTP Basic 认证访问 /opds 恒为 200，返回根订阅源（3 本书）。
• 未认证访问的行为随 config_anonbrowse 切换：关闭时 401（强制 Basic 认证），开启时 200（以 Guest 身份、Guest 可见范围）。阅读器类 App 接 OPDS 时按此选择：公开书库可留空认证，私有书库务必关闭匿名浏览。

8.2 Kobo 同步参数与设备令牌

Kobo 相关参数共两个开关：config_kobo_sync（启用 Kobo 同步端点）与 config_kobo_proxy（启用官方 Kobo 代理兼容模式）。

开启与令牌生成（实测回显）：

kobo_sync on -> [{'message': 'Calibre-Web 配置已更新', 'type': 'success'}] | reboot: False
GET /kobo_auth/generate_auth_token/1 -> 200
  page urls: ['http://10.89.62.2:8135/kobo/af7c5fa4947f9927166c885d34e2d8c9']

generate_auth_token/<用户id> 页面直接给出该用户的专属同步 URL（token 为 32 位十六进制）。首次开启 config_kobo_sync 时响应会带 reboot 标志要求重启服务，之后重复提交不再要求（本例 reboot: False）。

同步端点验证（实测回显，Kobo 设备 UA）：

GET /kobo/<token>/v1/library/sync -> 200 | len: 1338
  body[:160]: [{"ChangedReadingState": {"ReadingState": {"EntitlementId": "06f1c6b5-14c1-42d3-a98a-4e3a335396eb", ...
bogus token -> 401

合法 token 返回 200 与同步载荷（阅读状态 JSON）；非法 token 直接 401。

九、用户与权限参数

9.1 用户编辑页与角色位掩码

每个用户的权限存在 app.db 的 user.role 整型字段中，是位掩码：管理后台用户编辑页的每个权限 checkbox 对应一个位。实测关键结论：

• admin 用户 role=479；Guest 内置账户 role=32（各占不同位组合）。
• 上传权限对应位值 4：实测 admin 曾为 475（缺上传位）时上传返回 403，把 475 | 4 = 479 写回后上传恢复——差值正是 upload_role 那一位。

用户编辑页可改的参数：name、email、password、locale、kindle_mail（Kindle 推送收件地址）及全部权限 checkbox。

9.2 内置访客账户参数

内置 Guest 用户（id=2）就是匿名浏览的化身。实测其编辑页：

GET /admin/user/2 -> 200 | Calibre-Web | 编辑用户 Guest
  Guest checked: ['Show_detail_random']

Guest 默认只勾选「随机书籍详情」展示项，其余权限（下载、阅读等）按需勾选授予。开启 config_anonbrowse 后，Guest 的权限位决定未登录访客能看到什么——实测默认状态下游客可浏览书单（首页 200），但下载等动作受权限位约束。

十、常见配置问题排障实录

10.1 提交整型参数空值导致 500

现象：向 /admin/ajaxconfig 提交时，config_login_type、config_log_level 等下拉字段值为空串，服务端 int('') 抛异常，返回 500，配置不落库。 原因：页面 select 无显式 selected 项时，直接提交抓到的空值而非选项值。 解决：对每个 select 字段取第一个 option 的 value 兜底提交（浏览器行为即如此），如 config_login_type=0、config_log_level=10。

10.2 kepubify 校验失败导致整表单不保存

现象：提交含 config_kepubifypath=/usr/bin/kepubify 的表单，返回 Kepubify binary not found，且同表单内其他修改一并未保存。 原因：0.6.27 按标准文件名（kepubify-linux-64bit/32bit）白名单校验，且校验失败时放弃整次提交。 解决：复制合规命名副本 cp /usr/bin/kepubify /usr/bin/kepubify-linux-64bit 再指向该路径（5.2）。

10.3 强密码策略拒绝自定义密码

现象：改 admin 密码为 q1w2e3r4 被拒。 原因：默认密码策略 7 项参数全开，8 位纯「字母+数字」不满足要求。 解决：取消 config_password_policy 及关联 6 项勾选后提交（3.2）。

10.4 直接 POST 配置页返回 405

现象：向 /admin/config 发起 POST 得到 405 Method Not Allowed。 原因：基本配置页的保存走独立 AJAX 端点 /admin/ajaxconfig，本页不接受 POST。 解决：改向 /admin/ajaxconfig 提交全部字段（1.2）。

10.5 邮件设置提交缺少令牌返回 400

现象：POST /admin/mailsettings 返回 400。 原因：提交载荷遗漏了页面上的 csrf_token 隐藏字段。 解决：抓取页面 csrf_token 一并提交，返回 200（7.2）。viewconfig 同理。

十一、配置验证清单

十二、参考链接

1. 项目仓库：https://github.com/janeczku/calibre-web
2. 项目 Wiki（配置说明）：https://github.com/janeczku/calibre-web/wiki
3. 《Calibre Web 0.6.27 介绍与选型指南》：https://www.quzuo.net/document/aCwBuRNpnK2Z
4. 《Calibre Web 0.6.27 Docker Compose 部署指南》：https://www.quzuo.net/document/AGUdUkTOyiZ7