Stump 0.1.12 常用 CLI 命令与工具详解

Stump 服务器与 CLI 共用同一二进制的设计下，逐项实测 account（list/lock/unlock/reset-password/reset-owner/migrate-oidc）与 system set-journal-mode 子命令，含锁号登录熔断闭环。

StumpStump自托管Rust2026/11/02

Stump 0.1.12 常用 CLI 命令与工具详解

目标：讲清 Stump「服务器与 CLI 同一二进制」的设计，逐项实测 stump 的 account/system 两大子命令族（含锁号/解锁的完整闭环与登录效果验证），作为无 Web 登录态时的应急运维手册。全部命令与回显为 2026-11-02 在 《Stump 0.1.12 Docker Compose 部署指南》 的 stump-0.1.12-stack 栈上实测照抄，演示账号 admin / q1w2e3r4。

一、环境信息

项目值
应用版本Stump 0.1.12（/app/stump --version 实测输出 stump 0.1.12）
二进制位置官方镜像 aaronleopold/stump:latest 内 /app/stump（不在 PATH，见 FAQ 6.1）
调用形态docker exec stump-0.1.12-server /app/stump <子命令>（裸机部署则直接 ./stump，官方 CLI 文档假设在二进制同目录执行）
配置目录--config-dir 或 STUMP_CONFIG_DIR，须与服务一致（本栈 /config）
实测栈stump-0.1.12-stack（Web :8141，SQLite /config/stump.db）

二、工具概览

Stump 没有独立的 CLI 发行件：同一个可执行文件既是服务器也是管理工具——不带子命令运行时启动 HTTP 服务，带子命令时执行管理操作（来源：官方文档 Developer/CLI 页与 --help 首行描述，查询日期 2026-11-01）。顶层能力一览（实测 --help）：

$ docker exec stump-0.1.12-server /app/stump --help
A CLI for Stump. If no subcommand is provided, the server will be started

Usage: stump [OPTIONS] [COMMAND]

Commands:
  account  Subcommands for interacting with Stump accounts
  system   Subcommands for interacting with the system commands
  help     Print this message or the help of the given subcommand(s)

Options:
      --config-dir <CONFIG_DIR>
          The path to the configuration directory
      --password-hash-cost <PASSWORD_HASH_COST>
          The desired cost for password hashing. Defaults to 12
  -h, --help
          Print help
  -V, --version
          Print version

两个全局选项：--config-dir 指定配置目录（多实例区分用），--password-hash-cost 覆盖口令哈希成本（默认 12，与 Stump.toml 的 password_hash_cost 同义，见 《Stump 0.1.12 配置参数详解》 5.4）。

版本确认（实测）：

$ docker exec stump-0.1.12-server /app/stump --version
stump 0.1.12

三、前置条件

  1. 已按 《Stump 0.1.12 Docker Compose 部署指南》 部署 Stump 0.1.12，或裸机部署了同版本二进制；
  2. 有服务器 root/属主权限（可执行 docker exec 或访问二进制与配置目录）；
  3. CLI 操作的配置目录与服务一致——account/system 直接读写 stump.db，指错目录等于操作另一套库。

四、各工具详解

4.1 account 子命令族总览

$ docker exec stump-0.1.12-server /app/stump account --help
Subcommands for interacting with Stump accounts

Usage: stump account <COMMAND>

Commands:
  lock            Lock an account, preventing any further logins until unlocked
  unlock          Unlock an account, allowing logins again
  list            List all accounts, optionally filtering by locked status
  reset-password  Reset the password for an account
  reset-owner     Enter a flow to change the server owner to another account
  migrate-oidc    Migrate a local user account to an OIDC account
  help            Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help

六个业务子命令，覆盖「查、锁、解、改密、换属主、迁 OIDC」，全部以 --username 定位账号（reset-owner 除外，为交互流程）。

4.2 account list：账号盘点

$ docker exec stump-0.1.12-server /app/stump account list
+---------+----------+
| Account | Status   |
+---------+----------+
| admin   | unlocked |
+---------+----------+

支持按锁定状态过滤（--help 实测）：

List all accounts, optionally filtering by locked status

Usage: stump account list [OPTIONS]

Options:
      --locked <LOCKED>  Only list locked accounts [possible values: true, false]
  -h, --help             Print help

--locked true 只列锁定账号，--locked false 只列正常账号。

4.3 account lock / unlock：锁定与解锁（完整闭环实测）

锁定属主、验证列表、解锁、再验证（四步实测照抄）：

$ docker exec stump-0.1.12-server /app/stump account lock --username admin
$ docker exec stump-0.1.12-server /app/stump account list
+---------+--------+
| Account | Status |
+---------+--------+
| admin   | locked |
+---------+--------+
$ docker exec stump-0.1.12-server /app/stump account unlock --username admin
$ docker exec stump-0.1.12-server /app/stump account list
+---------+----------+
| Account | Status   |
+---------+----------+
| admin   | unlocked |
+---------+----------+

lock/unlock 成功时静默返回（退出码 0），效果以 list 复核。两命令参数一致：--username <USERNAME>（The username of the account to lock/unlock）。

锁定对登录接口的实际效果（实测）：锁定期内口令登录被服务端直接拒绝——

$ curl -s -o /tmp/lock_login.json -w "%{http_code}\n" -X POST http://localhost:8141/api/v2/auth/login -H "Content-Type: application/json" -d '{"username":"admin","password":"q1w2e3r4"}'
403
$ cat /tmp/lock_login.json
{"message":"Your account has been locked by an administrator","status":403}

解锁后同一请求恢复 HTTP 200 并返回用户 JSON（含 isLocked:false）。即 lock 是服务端强制的登录熔断，适合「账号被盗先熔断」场景，且完全可逆。

4.4 account reset-password：重置口令

参数形态（实测 --help）：

Reset the password for an account

Usage: stump account reset-password --username <USERNAME>

Options:
      --username <USERNAME>  The username of the account to reset the password for
  -h, --help                 Print help

仅 --username 一个业务参数，新口令经交互输入；用于用户忘记口令、Web 端无法自助修改时的管理员重置。与 --password-hash-cost 全局选项配合可在重置时指定哈希成本。

4.5 account reset-owner：变更服务器属主

Enter a flow to change the server owner to another account

Usage: stump account reset-owner

Options:
  -h, --help  Print help

无参数，进入交互式流程把服务器属主身份转移给另一账号——属主账号失联/需交接时的兜底工具。

4.6 account migrate-oidc：本地账号迁移到 OIDC

Migrate a local user account to an OIDC account

Usage: stump account migrate-oidc --username <USERNAME> --oidc-email <OIDC_EMAIL>

Options:
      --username <USERNAME>      The username of the local account to migrate
      --oidc-email <OIDC_EMAIL>  The email of the OIDC account to migrate to
  -h, --help                     Print help

把本地口令账号绑定到 OIDC 身份（按邮箱匹配），配合 《Stump 0.1.12 配置参数详解》 5.5 的 [oidc] 参数使用；迁移后该用户走外部身份源登录。

4.7 system set-journal-mode：数据库日志模式

$ docker exec stump-0.1.12-server /app/stump system --help
Subcommands for interacting with the system commands

Usage: stump system <COMMAND>

Commands:
  set-journal-mode  Set the journal mode for the database. Please use this command with caution!
  help              Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help
$ docker exec stump-0.1.12-server /app/stump system set-journal-mode --help
Set the journal mode for the database. Please use this command with caution!

Usage: stump system set-journal-mode --mode <MODE>

Options:
      --mode <MODE>  The journal mode to set
  -h, --help         Print help

--mode 直接改 SQLite 的 journal mode（如 WAL 类设置）。官方在描述里两次强调 use with caution——它绕过服务配置面直接动数据库属性，本文未在生产形态实测执行；确有并发读写瓶颈需求时，先停服、备份 /config/stump.db 再操作，并观察启动日志确认无迁移冲突（参考 《Stump 0.1.12 Docker Compose 部署指南》 FAQ 11.1 的库残留报错形态）。

五、注意事项

  • CLI 与服务共用一个二进制、直接读写同一 stump.db：account 族在服务运行中可正常执行（4.3 实测在服务 Up 时锁/解锁即时生效），但 system set-journal-mode 这类改库属性的操作建议停服进行；
  • 配置目录必须对齐：不带 --config-dir/STUMP_CONFIG_DIR 时 CLI 按默认 ~/.stump 找库，容器内执行务必通过 compose 已注入的环境变量（本栈 STUMP_CONFIG_DIR=/config）或显式 --config-dir 指定，否则会操作空库；
  • CLI 能力面小于 API：建库、上传、OPDS 等日常功能没有 CLI 子命令，需走 GraphQL/REST（见 《Stump 0.1.12 Docker Compose 部署指南》 4.8）；CLI 定位是账号与库级应急运维；
  • 裸机部署路径假设：官方文档示例均以 ./stump（二进制同目录、含相邻 client 目录）为前提，容器内对应 /app/stump。

六、常见问题

6.1 docker exec 报 executable file not found in $PATH

$ docker exec stump-0.1.12-server stump --version
OCI runtime exec failed: exec failed: unable to start container process: exec: "stump": executable file not found in $PATH

官方镜像把二进制放在 /app/stump 且未加入 PATH（实测报错原文）。用绝对路径即可：

$ docker exec stump-0.1.12-server /app/stump --version
stump 0.1.12

6.2 lock 后 Web 登录报 403

这是 lock 的预期行为（实测 403 + Your account has been locked by an administrator），不是故障。account unlock --username <名> 后登录恢复 200（实测闭环）。

6.3 account list 输出空表格/查不到用户

九成是配置目录指错（见五、注意事项第 2 条）：CLI 读了另一套 stump.db。确认 docker exec 环境继承 compose 的 STUMP_CONFIG_DIR，或显式加 --config-dir /config。

6.4 属主密码忘了，Web 又进不去

用 account reset-password --username admin 重置口令（4.4）；若属主身份本身需要转移给别的账号，用 account reset-owner 交互流程（4.5）。

七、参考链接

Stump 0.1.12 常用 CLI 命令与工具详解 - Quzuo