Stump 0.1.12 配置参数详解

目标：以实测生成的 /config/Stump.toml（30 键全量）为底本，逐类讲清 Stump 0.1.12 的参数体系、默认值、TOML/环境变量双通道与优先级行为，并给出可落地的生产配置模板。参数语义对照官方 Server Config 文档（查询日期 2026-11-01），全部修改与验证命令为 2026-11-02 在 《Stump 0.1.12 Docker Compose 部署指南》 部署的 stump-0.1.12-stack 栈上实测照抄。组件选型见 《Stump 0.1.12 介绍与选型指南》。

一、环境信息

二、前置条件

1. 已按 《Stump 0.1.12 Docker Compose 部署指南》 部署 stump-0.1.12-stack 且 docker compose ps 为 Up；
2. 服务器可读写配置卷目录 /srv/stump/config；
3. 改参数前先备份：cp /srv/stump/config/Stump.toml /srv/stump/config/Stump.toml.bak。

三、参数查看与修改方式

3.1 查看当前生效配置

配置目录里的 Stump.toml 即当前生效全量配置（首启自动生成所有键）：

$ cat /srv/stump/config/Stump.toml
ip = "0.0.0.0"
port = 10801
verbosity = 1
pretty_logs = true
colorful_logs = false
db_timeout_secs = 30
client_dir = "/app/client"
config_dir = "/config"
allowed_origins = []
enable_playground = false
enable_koreader_sync = false
enable_kobo_sync = false
enable_opds_progression = false
password_hash_cost = 12
session_ttl = 259200
access_token_ttl = 86400
refresh_token_ttl = 2592000
expired_session_cleanup_interval = 86400
parallelism_multiplier = 2
max_image_upload_size = 20971520
enable_upload = true
max_file_upload_size = 20971520
pdf_render_dpi = 150
pdf_max_dimension = 1200
pdf_render_format = "webp"
pdf_cache_pages = true
pdf_prerender_range = 5
pdf_high_quality = true
trust_proxy_headers = false

（输出节选，实测全量 30 键照抄；其中 client_dir/config_dir 的取值由部署环境决定，裸机部署时分别为 ./dist 与 ~/.stump。）

3.2 编辑 TOML 后重启生效

参数在进程启动瞬间读取，改文件后必须重启：

$ sed -i 's/^verbosity = 2/verbosity = 1/' /srv/stump/config/Stump.toml
$ grep -n verbosity /srv/stump/config/Stump.toml
3:verbosity = 1
$ cd /srv/stump && docker compose restart
 Container stump-0.1.12-server Restarting
 Container stump-0.1.12-server Started
$ docker compose logs --since 20s | grep "Tracing initialized"
stump-0.1.12-server  |   2026-11-02T06:46:23.411670Z  INFO stump_core::config::logging: Tracing initialized, verbosity: LevelFilter::INFO, verbosity_num: 1

日志级别从 DEBUG 回到 INFO，修改生效（该组回显为实测的「改回默认」过程，正向修改同理）。

3.3 环境变量覆盖（Docker 推荐通道）

compose 的 environment: 注入 STUMP_<大写键名> 即覆盖同名 TOML 键。实测加入 STUMP_VERBOSITY=2 重建：

$ cd /srv/stump && docker compose up -d
 Container stump-0.1.12-server Recreate
 Container stump-0.1.12-server Recreated
 Container stump-0.1.12-server Starting
 Container stump-0.1.12-server Started
$ docker compose logs --since 30s | grep "Tracing initialized"
stump-0.1.12-server  |   2026-11-02T06:45:06.464403Z  INFO stump_core::config::logging: Tracing initialized, verbosity: LevelFilter::DEBUG, verbosity_num: 2

3.4 优先级与回写行为（实测结论）

环境变量覆盖只发生在启动装配时，且会把生效值持久化写回 Stump.toml。实测链：

1. 加 STUMP_VERBOSITY=2 重建 → 日志 LevelFilter::DEBUG, verbosity_num: 2，且 Stump.toml 第 3 行变为 verbosity = 2；
2. 移除该环境变量再 down/up → 日志仍是 LevelFilter::DEBUG, verbosity_num: 2（TOML 里的持久化值继续生效）；
3. 手工把 Stump.toml 改回 verbosity = 1 并 restart → 日志恢复 LevelFilter::INFO, verbosity_num: 1。

⚠️ 注意：「删掉 compose 里的环境变量」不等于「回退到默认值」。回退的正确姿势是直接编辑 Stump.toml（3.2），或整段删除该键后重启。

四、参数总览

4.1 分类与键数

官方 Server Config 将参数按九域组织（来源：官方文档，查询日期 2026-11-01；「实测 TOML」列指 3.1 全量文件是否出现该键）：

4.2 命名映射规则

• 环境变量 = STUMP_ + TOML 键大写：verbosity ↔ STUMP_VERBOSITY，trust_proxy_headers ↔ STUMP_TRUST_PROXY_HEADERS；
• OIDC 例外：TOML 嵌套在 [oidc] 表（[oidc].enabled），环境变量仍是平铺的 STUMP_OIDC_ENABLED；
• 官方明确「未配置的键使用默认值，只需覆盖你想改的」，Stump.toml 不必写全 30 键。

五、核心参数分类详解

5.1 Core：监听与部署形态

5.2 Database：存储引擎与连接

💡 技术拓展：Stump 支持的两种元数据库——

引擎	配置方式	适用
SQLite（默认）	db_path 指目录即可	单实例/家庭 NAS，零运维，1GB 内存场景首选
PostgreSQL	STUMP_DB_URL 或 HOST/PORT/USER/PASSWORD/NAME 组	已有 PG 基础设施、多实例共享元数据

本文实测环境用默认 SQLite（/config/stump.db）；官方文档明确 SQLite 场景优先用 db_path 而非 URL。

5.3 Logging：日志

级别切换实测见 3.3/3.4：Tracing initialized, verbosity: LevelFilter::DEBUG, verbosity_num: 2。

5.4 Authentication & Sessions：认证与会话时效

5.5 OIDC：外部身份源（[oidc] 表）

启用后用户可用外部身份提供方登录；TOML 内全部键嵌套在 [oidc] 表：

port = 10801

[oidc]
enabled = true
issuer_url = "https://auth.example.com"
client_id = "stump"
client_secret = "example-secret"

5.6 Integrations：同步类开关

5.7 PDF Rendering：渲染管线

💡 技术拓展：PDF 渲染输出格式常见三选项——webp（默认，压缩率/质量均衡）、jpeg（兼容最广、无透明通道）、png（无损、体积大）。Stump 默认选 webp 兼顾带宽与清晰度；低端设备可降 pdf_render_dpi 而非改格式。

5.8 File Uploads：上传

实测开启后 uploadBooks 变更上传 CBZ 成功入库（状态 READY），见 《Stump 0.1.12 Docker Compose 部署指南》 4.8 的媒体读回。

5.9 Performance / Developer：并发与调试

六、生产配置模板

以「家庭 NAS（2 核 2GB、单实例 SQLite、反代 HTTPS 接入、允许网页上传）」为场景的 /config/Stump.toml 模板：

# 监听：容器内保持默认
ip = "0.0.0.0"
port = 10801

# 日志：生产保持 1，排障时临时改 2 重启
verbosity = 1
pretty_logs = true

# 数据库：SQLite 留在配置目录卷内（默认即可），无需 db_path
db_timeout_secs = 30

# 会话：NAS 个人使用可维持 3 天
session_ttl = 259200
password_hash_cost = 12

# 反代场景：信任 X-Forwarded-For；跨域来源按需追加
trust_proxy_headers = true
allowed_origins = ["https://books.example.com"]

# 上传：2GB 大书放宽到 200MB
enable_upload = true
max_file_upload_size = 209715200
max_image_upload_size = 20971520

# 弱机降并发
parallelism_multiplier = 1

# PDF 渲染：内存紧张时降 DPI 与预渲染
pdf_render_dpi = 120
pdf_prerender_range = 2

# 调试面关闭
enable_playground = false

（模板为参数组合示例；键名/默认值均取自 3.1 实测 TOML 与官方 Server Config 文档，2026-11-02。）

七、常见问题

7.1 expired_session_cleanup_interval 文档默认 60，实测 86400

官方 Server Config 页写默认「60 秒清理一次过期会话」，但 0.1.12 实测生成的 Stump.toml 中该键为 86400（一天）。对使用无实质影响（只决定过期会话从库里清除的节奏，过期会话本身已不可用）；在意残留会话记录及时清理的，显式设 expired_session_cleanup_interval = 60 即可，以显式配置为准。

7.2 环境变量删了，参数却没回退

见 3.4 实测链：STUMP_* 覆盖会写回 Stump.toml，删除环境变量后 TOML 持久化值继续生效。回退请直接编辑 TOML（3.2）或删键后重启。

7.3 OIDC 配置不生效

检查 TOML 里是否把 OIDC 键写在了顶层——它们必须位于 [oidc] 表内（enabled、issuer_url 等），STUMP_OIDC_* 环境变量则不受表结构限制。enabled=true 时 issuer_url/client_id/client_secret 为必填，缺一即不生效。

7.4 裸机部署 PDF 无法渲染

pdfium_path 默认值 /lib/libpdfium.so 只在官方 Docker 镜像内存在；裸机需按官方文档自行下载对应平台 PDFium 二进制并显式配置该键指向实际路径。

7.5 反代后部分生成 URL 不对

trust_proxy_headers 默认 false 时 Stump 完全忽略 X-Forwarded-For/X-Real-IP，仅用原始连接信息，反代后生成的 URL 可能错误。确认反代正确设置这些头后置 true（同时知晓 IP 伪造风险增大，官方文档原话）。

八、参考链接

• 官方 Server Config：https://stumpapp.github.io/configuration/server-config
• 官方 Database：https://stumpapp.github.io/configuration/database
• 官方 API（认证与 JWT）：https://stumpapp.github.io/developer/api
• 站内：《Stump 0.1.12 介绍与选型指南》、《Stump 0.1.12 Docker Compose 部署指南》、同类配置参考 《Kavita 0.9.1.4 配置参数详解》