Stump 0.1.12 Docker Compose 部署指南
用一份 Docker Compose 文件部署 Stump 0.1.12 官方镜像，完成健康检查、属主认领、建库扫描、重启持久化的端到端实测闭环，含环境变量覆盖与配置回写行为实录。
Stump 0.1.12 Docker Compose 部署指南
目标：在一台 Linux 服务器上用一份 Docker Compose 文件部署 Stump 0.1.12 官方镜像，并完成「健康检查 → 创建属主 → 登录 → 建库扫描 → 重启持久化」的端到端实测闭环。全部命令与回显均为 2026-11-02 在
stump-0.1.12-stack栈上实测照抄，示例账号admin/q1w2e3r4。组件定位与选型见 《Stump 0.1.12 介绍与选型指南》；参数逐项详解见本专栏 《Stump 0.1.12 配置参数详解》；CLI 用法见 《Stump 0.1.12 常用 CLI 命令与工具详解》。
一、环境信息
| 项目 | 值 |
|---|---|
| 操作系统 | Linux（x86_64，内核 7.0.0-38-generic） |
| 容器运行时 | Docker 29.9.2（build a82e528），Docker Compose v2 |
| 应用版本 | Stump 0.1.12（官方镜像 aaronleopold/stump:latest，构建 rev 0769a29，编译时间 2026-11-01T17:07:58Z） |
| 对外端口 | 8141（映射到服务默认端口 10801） |
| 专用网络 | stump-0.1.12-net，子网 10.89.56.0/24（compose 显式声明，避免与其他栈冲突） |
| 配置/数据目录 | /srv/stump/config:/config（Stump.toml 与 stump.db）、/srv/stump/data:/data（书库媒体） |
| 演示账号 | admin / q1w2e3r4（首次认领创建的服务器属主） |
二、镜像选型说明
Stump 官方 Docker 安装路径使用 Docker Hub 上的 aaronleopold/stump 镜像（作者维护，来源：官方文档 Installation/Docker 页，查询日期 2026-11-01）。本部署取 :latest 标签，实际内容为当前最新稳定版 v0.1.12——启动后可用版本接口复核（见 4.7 实测回显，semver 为 0.1.12）。
💡 技术拓展：容器化部署 Stump 的标签策略选择——
策略 写法 取舍 latest aaronleopold/stump:latest始终最新，但重建时版本可能漂移 固定版本 aaronleopold/stump:0.1.12（以 Releases 为准）可复现，升级需显式改标签 本文用
:latest与官方文档示例一致，并在环境信息中固化实测版本号，生产环境建议改用固定标签。
三、前置条件
- 服务器已安装 Docker 与 Compose v2 插件（
docker --version确认 29.9.2）； - 端口 8141 未被占用（
ss -ltn | grep 8141无输出）； - 已准备书库媒体目录（本文用
/srv/stump/data，放入 EPUB/CBZ/CBR/PDF 文件即可）； - 官方镜像拉取可用（
docker pull aaronleopold/stump:latest，国内网络慢时按下载降级链先试国内加速器、再走代理）。
四、部署步骤
4.1 准备目录
# 配置目录（Stump.toml + stump.db 落盘处）与书库数据目录
mkdir -p /srv/stump/config /srv/stump/data
4.2 编写 compose 文件
/srv/stump/docker-compose.yml（实测使用的完整内容）：
name: stump-0.1.12-stack
services:
stump:
image: aaronleopold/stump:latest
container_name: stump-0.1.12-server
volumes:
- /srv/stump/config:/config
- /srv/stump/data:/data
ports:
- "8141:10801"
environment:
- PUID=0
- PGID=0
- STUMP_CONFIG_DIR=/config
- STUMP_ENABLE_UPLOAD=true
restart: unless-stopped
networks:
- stumpnet
networks:
stumpnet:
name: stump-0.1.12-net
driver: bridge
ipam:
config:
- subnet: 10.89.56.0/24
逐项说明：
name:显式声明 compose 项目名，多栈并存时down不会误伤其他项目；PUID/PGID按官方文档应设为配置与数据目录属主（echo -e "PUID=$(id -u)\nPGID=$(id -g)"可打印当前值）；本文以 root 属主目录演示故取 0；STUMP_CONFIG_DIR=/config与挂载点对齐，保证 Stump.toml 与数据库落在持久化卷；STUMP_ENABLE_UPLOAD=true开启网页上传（官方默认关闭）；- 子网
10.89.56.0/24显式固定，避免 Docker 自动分配撞上其他栈网段。
4.3 启动服务
$ cd /srv/stump && docker compose up -d
Network stump-0.1.12-net Creating
Network stump-0.1.12-net Created
Container stump-0.1.12-server Creating
Container stump-0.1.12-server Created
Container stump-0.1.12-server Starting
Container stump-0.1.12-server Started
状态确认：
$ docker compose ps
NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
stump-0.1.12-server aaronleopold/stump:latest "/entrypoint.sh" stump 4 seconds ago Up 4 seconds 0.0.0.0:8141->10801/tcp, [::]:8141->10801/tcp
4.4 启动日志与 Web 入口验证
$ docker compose logs --tail 8
stump-0.1.12-server | If you face any issues, or encounter any bugs: https://github.com/stumpapp/stump/issues/new/choose
stump-0.1.12-server | If you would like to join the Stump Community Discord Server: https://discord.gg/63Ybb7J3as
stump-0.1.12-server | Enjoy!
stump-0.1.12-server | 2026-11-02T06:46:00.409210Z INFO stump_server::http_server: ⚡️ Stump HTTP server starting on http://0.0.0.0:10801
stump-0.1.12-server | at apps/server/src/http_server.rs:136
日志出现 ASCII 横幅与 Stump HTTP server starting on http://0.0.0.0:10801 即服务就绪。Web 入口验证：
$ curl -sI http://localhost:8141/
HTTP/1.1 200 OK
content-type: text/html
accept-ranges: bytes
last-modified: Sun, 01 Nov 2026 17:07:45 GMT
content-length: 8496
cache-control: no-cache, no-store, must-revalidate
4.5 健康检查
$ curl -s http://localhost:8141/api/v2/ping
pong
$ curl -s http://localhost:8141/api/v2/health
{"dependencies":{"database":{"status":"ok"},"spa":{"status":"ok"}},"status":"ok"}
$ curl -s http://localhost:8141/api/v2/auth/claim
{"isClaimed":false}
database 与 spa 双 ok、isClaimed:false 表示全新实例等待认领属主。
4.6 创建属主账号并登录
浏览器打开 http://<服务器>:8141 会进入首次引导页；等价 REST 实测（属主注册即首次 register，无用户时自动成为服务器属主）：
$ curl -s -o /dev/null -w "%{http_code}\n" -X POST http://localhost:8141/api/v2/auth/register -H "Content-Type: application/json" -d '{"username":"admin","password":"q1w2e3r4"}'
200
$ curl -s http://localhost:8141/api/v2/auth/claim
{"isClaimed":true}
$ curl -s -c /tmp/stump_ck.txt -o /dev/null -w "%{http_code}\n" -X POST http://localhost:8141/api/v2/auth/login -H "Content-Type: application/json" -d '{"username":"admin","password":"q1w2e3r4"}'
200
登录成功响应头下发服务端会话 Cookie（set-cookie 中 stump_session 值，属性 HttpOnly; SameSite=Lax; Max-Age=259200，有效期即默认 session_ttl 3 天），后续 GraphQL 请求以 -b /tmp/stump_ck.txt 携带。
4.7 版本复核
$ curl -s -b /tmp/stump_ck.txt -X POST http://localhost:8141/api/v2/version
{"semver":"0.1.12","buildChannel":"stable","rev":"0769a29","compileTime":"2026-11-01T17:07:58.582423267+00:00"}
$ curl -s -b /tmp/stump_ck.txt http://localhost:8141/api/v2/check-for-update
{"currentSemver":"0.1.12","latestSemver":"0.1.12","hasUpdateAvailable":false}
确认镜像内容即最新稳定版 0.1.12，且无更新可用。
4.8 功能闭环：建库、扫描、读回
Stump 核心 API 是 GraphQL（端点 /api/graphql）。创建指向 /data 的书库（实测回显，节选）：
$ curl -s -b /tmp/stump_ck.txt -X POST http://localhost:8141/api/graphql -H "Content-Type: application/json" -d '{"query":"mutation { createLibrary(input: { name: \"quzuo-test\", path: \"/data\", description: \"S9 实测书库\" }) { id name path createdAt } }"}'
{"data":{"createLibrary":{"id":"b106a108-8b78-4182-ab7e-9399cd0a58c7","name":"quzuo-test","path":"/data","createdAt":"2026-11-02T05:07:24.178986125+00:00"}}}
扫描作业与媒体读回（实测回显）：
$ curl -s -b /tmp/stump_ck.txt -X POST http://localhost:8141/api/graphql -H "Content-Type: application/json" -d '{"query":"{ jobs { nodes { name status msElapsed } } }"}'
{"data":{"jobs":{"nodes":[{"name":"library_scan","status":"COMPLETED","msElapsed":6},{"name":"library_scan","status":"COMPLETED","msElapsed":7}]}}}
$ curl -s -b /tmp/stump_ck.txt -X POST http://localhost:8141/api/graphql -H "Content-Type: application/json" -d '{"query":"{ media { nodes { name extension pages status } } }"}'
{"data":{"media":{"nodes":[{"name":"test-book","extension":"epub","pages":3,"status":"READY"},{"name":"test-manga","extension":"cbz","pages":3,"status":"READY"},{"name":"upload-demo","extension":"cbz","pages":3,"status":"READY"}]}}}
library_scan 作业 COMPLETED（毫秒级完成）、媒体状态 READY，即部署端到端可用。
💡 技术拓展：Stump 建库的三种触达方式——
方式 入口 适用 Web UI 管理页「新建书库」表单 日常操作 GraphQL API createLibrary变更（本文实测）脚本化/自动化 CLI 同二进制 stump的account/system子命令（不含建库，见 《Stump 0.1.12 常用 CLI 命令与工具详解》）无 Web 登录态时运维 本文验证用 GraphQL，因其为 Stump 核心 API；Web UI 路径行为一致。
4.9 重启与持久化验证
$ docker compose down
Container stump-0.1.12-server Stopping
Container stump-0.1.12-server Stopped
Container stump-0.1.12-server Removing
Container stump-0.1.12-server Removed
Network stump-0.1.12-net Removing
Network stump-0.1.12-net Removed
$ docker compose up -d
Network stump-0.1.12-net Creating
Network stump-0.1.12-net Created
Container stump-0.1.12-server Creating
Container stump-0.1.12-server Created
Container stump-0.1.12-server Starting
Container stump-0.1.12-server Started
$ curl -s -o /dev/null -w "%{http_code}\n" -X POST http://localhost:8141/api/v2/auth/login -H "Content-Type: application/json" -d '{"username":"admin","password":"q1w2e3r4"}'
200
down 后重建网络、up 后属主账号登录仍 200、书库与媒体数据完整（4.8 读回即重建后所查），持久化成立。
五、数据持久化说明
两个卷即全部持久化面：
| 宿主目录 | 容器内 | 内容 | 丢失后果 |
|---|---|---|---|
/srv/stump/config | /config | Stump.toml、stump.db（用户/会话/书库元数据/缩略图记录）、JWT 签名密钥 | 需重新认领属主、重扫全部书库 |
/srv/stump/data | /data | 你的书籍文件本体 | 媒体丢失 |
数据库为 SQLite 单文件（/config/stump.db），备份只需停服务后拷贝该目录；书库元数据可经 GraphQL 重建，但阅读进度、API Keys 均在库内，务必纳入备份。
六、环境变量表
compose 的 environment: 即配置覆盖通道（完整参数语义见本专栏 《Stump 0.1.12 配置参数详解》），常用如下：
| 环境变量 | 对应 TOML 键 | 默认值 | 说明 |
|---|---|---|---|
PUID / PGID | —（entrypoint） | — | 容器内运行身份，设为配置/数据目录属主 |
STUMP_IP | ip | 0.0.0.0 | 监听地址 |
STUMP_PORT | port | 10801 | 服务端口（容器内） |
STUMP_CONFIG_DIR | config_dir | ~/.stump | 配置目录，Docker 部署务必指向挂载点 |
STUMP_VERBOSITY | verbosity | 1 | 日志级别 0–3（见 7.2 实测） |
STUMP_ENABLE_UPLOAD | enable_upload | false | 网页上传开关 |
STUMP_DB_PATH | db_path | 配置目录父级 | SQLite 库文件目录 |
STUMP_ALLOWED_ORIGINS | allowed_origins | Tauri 相关 | 跨域白名单（API 从别的域名访问时配置） |
STUMP_TRUST_PROXY_HEADERS | trust_proxy_headers | false | 反代后置真时启用 |
STUMP_SESSION_TTL | session_ttl | 259200 | 会话有效期（秒） |
STUMP_OIDC_ENABLED 等 | [oidc].* | false | OIDC 登录接入（详见 《Stump 0.1.12 配置参数详解》） |
七、配置参数说明
7.1 双通道配置模型
Stump 所有参数可在 Stump.toml 与环境变量两处设置，环境变量以 STUMP_ 前缀覆盖同名 TOML 键；未设置的键使用内置默认值（来源：官方文档 Server Config，查询日期 2026-11-01）。
7.2 环境变量覆盖实测
在 compose 中加入 STUMP_VERBOSITY=2 后重建：
$ 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
日志级别由默认 LevelFilter::INFO（1）切换为 LevelFilter::DEBUG（2），覆盖生效。
7.3 覆盖值会写回 Stump.toml（重要行为）
上述覆盖后检查配置文件：verbosity = 2 已被持久化写入 /config/Stump.toml；随后移除环境变量并重建，服务仍按 TOML 中的 2 启动（实测日志仍为 LevelFilter::DEBUG, verbosity_num: 2）。即环境变量只在「设置时」生效一次并落盘，回退需直接编辑 Stump.toml 改回默认再重启（见 FAQ 11.3）。
八、配置文件挂载
首次启动时服务在 /config 自动生成全量 Stump.toml（实测生成 30 个键，节选首段）：
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
（输出节选，实测首段；其中 client_dir/config_dir 为镜像内路径，其余键的完整语义与默认值对照见 《Stump 0.1.12 配置参数详解》。）该文件位于持久化卷内，可直接编辑后 docker compose restart 生效，适合与 compose 环境变量混合使用：常驻参数进 TOML，环境差异化参数用 STUMP_* 注入。
九、等价 docker run
不用 Compose 时官方给出的等价命令（形态来源：官方文档 Installation/Docker「Docker CLI」，查询日期 2026-11-01；端口/目录按本栈调整）：
docker create \
--name=stump-0.1.12-server \
-e "PUID=0" \
-e "PGID=0" \
-e "STUMP_CONFIG_DIR=/config" \
-e "STUMP_ENABLE_UPLOAD=true" \
-p 8141:10801 \
--volume "/srv/stump/config:/config" \
--volume "/srv/stump/data:/data" \
--restart unless-stopped \
aaronleopold/stump:latest
docker start stump-0.1.12-server
官方文档同时说明可用 --mount 形式替换 --volume 行。两种形态数据目录一致，可随时互换。
十、常用运维命令
# 查看状态
docker compose ps
# 跟踪日志
docker compose logs -f stump
# 重启（改 Stump.toml 后生效）
docker compose restart
# 停止并移除（数据卷在宿主目录，不受影响）
docker compose down
升级（官方文档 Update the container 流程）：
docker compose pull stump
docker compose up -d
升级前后用版本接口对照（实测 4.7）：POST /api/v2/version 看当前运行版，GET /api/v2/check-for-update 看 latestSemver 与 hasUpdateAvailable。0.1.x 系列升级注意官方 Breaking changes 页。
账号应急运维（CLI 与服务同镜像，详见 《Stump 0.1.12 常用 CLI 命令与工具详解》）：
$ docker exec stump-0.1.12-server /app/stump account list
+---------+----------+
| Account | Status |
+---------+----------+
| admin | unlocked |
+---------+----------+
十一、常见问题
11.1 启动 panic：index idx_media_annotations_user_media already exists
复用旧实验残留的配置目录时，迁移与残留库冲突，启动即崩溃（实测报错原文）：
thread 'main' panicked at core/src/context.rs:53:6:
Failed to connect to database: DBError(Exec(SqlxError(Database(SqliteError { code: 1, message: "index idx_media_annotations_user_media already exists" }))))
定位：报错指向 SQLite 索引重复创建，说明 /config/stump.db 是旧版本/旧栈遗留库。解决：停服后清掉配置目录内的数据库文件（mv /srv/stump/config/stump.db /srv/stump/config/stump.db.bak）再启动，服务重新建库并正常打出启动横幅（实测清库重启后 Stump HTTP server starting on http://0.0.0.0:10801 成功）。数据目录 /data 的书籍文件不受影响，重新建库扫描即可。
11.2 启动日志出现 addgroup: gid '0' in use
PUID=0/PGID=0 时镜像 entrypoint 尝试创建 stump 用户/组会与 root 的 uid/gid 冲突，每次启动打印：
Adding group stump with gid 0
addgroup: gid '0' in use
Adding user stump with uid 0
adduser: unknown group stump
该告警无害，服务照常启动（实测两轮启动均出现且随后 HTTP 正常监听）。规范做法是把 PUID/PGID 设为数据目录属主的真实 uid/gid（id -u/id -g），告警即消失。
11.3 移除环境变量后配置没回退
见 7.3：STUMP_* 覆盖会持久化写进 Stump.toml，删除环境变量不等于回退。回退方法：直接编辑 Stump.toml 将键改回默认值（或删键）后 docker compose restart（实测改回 verbosity = 1 重启后日志恢复 LevelFilter::INFO, verbosity_num: 1）。
11.4 端口 10801 冲突
宿主机映射端口冲突改 ports: 左侧即可（如 8141:10801）；若要改容器内监听端口，需同时设 STUMP_PORT 并同步映射右侧。
十二、参考链接
- 官方 Docker 安装文档：https://stumpapp.github.io/installation/docker
- 官方 Server Config：https://stumpapp.github.io/configuration/server-config
- 官方 GitHub 仓库：https://github.com/stumpapp/stump
- 站内：《Stump 0.1.12 介绍与选型指南》、同类部署参考 《Kavita 0.9.1.4 Docker Compose 部署指南》