Kresus 0.26.0 常用 CLI 命令详解

目标：讲清 Kresus 0.26.0 的命令行体系——kresus 主命令的启动参数与五个管理子命令（配置生成、用户增删查），以及银行同步引擎 Woob 的命令行交互，全部命令与回显在运行环境内实测采集。已在 Ubuntu 22.04.4 LTS + Docker 29.8.1 环境（官方制品 bnjbvr/kresus:0.26.0）实测通过，Woob 3.7、PostgreSQL 16、Node.js v24.22.1。

一、环境信息

操作系统：Ubuntu 22.04.4 LTS（内核 6.8.0-138-generic，x86_64）
Docker：29.8.1；Docker Compose：v5.5.1
Kresus：0.26.0（官方制品 bnjbvr/kresus:0.26.0，构建于 2026-10-22）
数据库：PostgreSQL 16；Woob：3.7（Python 3.11.2）
CLI 实测路径：运行环境内 /home/user/app/bin/kresus（官方制品固定入口，见 3.1 节）
部署编排：kresus-0.26.0-stack（部署过程见《Kresus 0.26.0 Docker Compose 部署指南》）
实测用户基础：实例初始仅 1 个用户（首次启动自动生成的 user，id=1，管理员）；本文 4.x 节实测中额外创建了演示用户 demo（id=5，非管理员）

二、前置条件

2.1 确认 CLI 可调用

Kresus 的 CLI 即其启动二进制本身（无独立管理工具包）。官方制品内的调用路径固定为 /home/user/app/bin/kresus（官方入口脚本的启动命令形态即 /home/user/app/bin/kresus --config /opt/config.ini）。验证可调用：

docker exec kresus-0.26.0-app /home/user/app/bin/kresus --help

实测回显（完整）：

Usage: /home/user/app/bin/kresus
	-h or --help or help: displays this message.
	-c $path or --config $path: path to the configuration file.
	create:config: creates an empty configuration file up to date.
	create:user $login [--admin]: creates a new user with given login,
		and assigns it an ID. Pass "--admin" to create an administrator.
	delete:user $login: deletes a user with given login
	list:users: lists all the users with their id, login and admin status.

帮助信息显示 Kresus CLI 全景：主命令（启动服务）+ --config 启动参数 + 三个管理子命令（create:config/create:user/delete:user/list:users）。裸装形态下同一路径为源码目录的 bin/kresus.js，经 npm 全局安装后可直接使用 kresus 命令。

2.2 调用形态说明

本文实测均采用 docker exec 进入运行环境调用（与部署篇编排一致）：

# 固定形态：docker exec <实例名> /home/user/app/bin/kresus <子命令>
docker exec kresus-0.26.0-app /home/user/app/bin/kresus list:users

💡 说明：管理子命令（list:users 等）需要数据库连接，实测容器形态下无需显式传 --config——运行环境已内置全部数据库环境变量（KRESUS_DB_*），子命令按环境变量连接数据库后执行。裸装形态无环境变量时，管理命令需与启动一样传 --config /path/to/config.ini。

三、启动命令形态

kresus 主命令（不带子命令）即启动 Web 服务，两种实测形态：

3.1 生产标准启动：`kresus --config <路径>`

官方入口脚本的启动形态（生产模式要求显式配置文件）：

kresus --config /opt/config.ini
# 等价短参数形态：kresus -c /opt/config.ini

启动后依次执行：配置读取与权限校验（生产模式要求 config.ini 权限至多属主读写/属组可读）→ 数据库连接与迁移 → 参数生效回显（apply-config 段）→ 监听端口。实测启动日志尾部：

[2026-10-23T18:01:52.949] [INFO] models/index - database is ready
[2026-10-23T18:01:52.954] [INFO] models/index - Default user “user“ is set with id 1 (admin: true)
[2026-10-23T18:01:52.960] [INFO] poller - All accounts have been polled.
[2026-10-23T18:01:52.960] [INFO] report-manager - No emailer found, skipping reports management.
[2026-10-23T18:01:52.960] [INFO] init - Server is ready, let's start the show!

3.2 无参数启动的行为

docker exec kresus-0.26.0-app /home/user/app/bin/kresus

实测回显（进程持续运行，日志节选头部）：

Configuration file not provided. If this is intentional and you did not provide configuration directives through environment variables you'll see error messages during database setup.
[2026-10-23T18:20:19.665] [INFO] apply-config - Running Kresus 0.26.0 with the following parameters:
[2026-10-23T18:20:19.665] [INFO] apply-config - NODE_ENV = production
[2026-10-23T18:20:19.665] [INFO] apply-config - KRESUS_DIR = /home/user/data
...
[2026-10-23T18:20:19.665] [INFO] apply-config - PORT = 9876
[2026-10-23T18:20:19.665] [INFO] apply-config - HOST = 0.0.0.0

行为解读：无 --config 时 Kresus 打印警告但不拒绝启动——若环境变量已提供全部必需配置（如 Docker 编排内的 KRESUS_DB_*）则可正常运行；环境变量缺失时会在数据库连接阶段报错退出。裸装生产部署始终显式传 --config。

⚠️ 注意：同一环境重复启动第二个 Kresus 进程会因端口（9876）被主实例占用而失败退出；管理操作请用子命令而非另起服务进程。

四、用户管理命令

4.1 列出用户：`kresus list:users`

docker exec kresus-0.26.0-app /home/user/app/bin/kresus list:users

实测回显（初始单用户状态；节选，头部为配置初始化行）：

[2026-10-23T18:05:15.599] [INFO] cli - Listing users: setting up database.
[2026-10-23T18:05:15.642] [INFO] cli - Database set up; listing users...
[2026-10-23T18:05:15.644] [INFO] cli - Found 1 users.
[2026-10-23T18:05:15.644] [INFO] cli - - id=1 login=user isAdmin=true

输出含义：每行一个用户，含数字 ID、登录名与是否管理员。首次启动自动创建的 user（id=1）为管理员。

4.2 创建用户：`kresus create:user <login> [--admin]`

docker exec kresus-0.26.0-app /home/user/app/bin/kresus create:user demo --admin

实测回显：

[2026-10-23T18:06:02.475] [INFO] cli - User demo created with success! id=3
[2026-10-23T18:06:02.475] [INFO] cli - You will have to restart your kresus instance to access it.

不带 --admin 则创建普通用户：

docker exec kresus-0.26.0-app /home/user/app/bin/kresus create:user demo

实测回显（此时 demo 已被删除重创，新分配 id=5）：

[2026-10-23T18:20:20.629] [INFO] cli - User demo created with success! id=5
[2026-10-23T18:20:20.629] [INFO] cli - You will have to restart your kresus instance to access it.

两点重要语义（官方帮助与回显均印证）：

create:user 返回的 id 即 config.ini userid 参数要填的值（多用户共享数据库场景）；
新用户需重启 Kresus 实例后方可访问（回显第二行明示）。

创建后复查：

[2026-10-23T18:20:20.308] [INFO] cli - Found 2 users.
[2026-10-23T18:20:20.308] [INFO] cli - - id=1 login=user isAdmin=true
[2026-10-23T18:20:20.308] [INFO] cli - - id=5 login=demo isAdmin=false

💡 说明：Kresus 的「用户」是数据隔离单元而非登录账号——应用无内置认证，Web 界面不凭用户名密码登录；user_login_http_header 预认证或 auth Basic Auth 才是访问控制入口（配置细节见《Kresus 0.26.0 配置参数详解》）。

4.3 删除用户：`kresus delete:user <login>`

docker exec kresus-0.26.0-app /home/user/app/bin/kresus delete:user demo

实测回显（正常删除）：

[2026-10-23T18:06:12.437] [INFO] cli - User demo deleted with success!

删除后 list:users 复查仅剩 user（id=1）。重复删除同一用户会报错退出：

Error: Couldn't delete user demo: No user with this login
    at Object.deleteUser (cli.js:43:15)

报错首行为业务语义（无此登录名），后随 Node.js 调用栈；属预期行为，不是数据损坏。

⚠️ 提醒：删除用户会级联清理其名下全部业务数据（账户、交易、分类等，PostgreSQL 中按 userid 关联的行），且不可恢复；执行前务必确认目标登录名，生产环境先做数据库备份。

4.4 用户管理速查

命令	参数	作用	实测要点
`list:users`	无	列出用户（id/login/admin）	每次执行先做数据库连接与迁移检查
`create:user <login>`	login，可选 `--admin`	创建用户并分配 ID	回显 id 即 `userid` 配置值；需重启实例生效
`delete:user <login>`	login	删除用户及其全部数据	级联删除不可恢复；目标不存在时报 `No user with this login`

五、配置生成命令：`kresus create:config`

# 输出到 stdout，重定向保存
docker exec kresus-0.26.0-app /home/user/app/bin/kresus create:config > config.ini

实测生成 289 行文件：六节（[kresus]/[woob]/[email]/[notifications]/[logs]/[db]）28 个参数，每个参数附官方注释（默认值 + 环境变量覆盖说明），全部参数留空待填。该母本与当前运行版本（0.26.0）严格同步，是升级版本后核对配置增减的标准手段——比沿用旧版配置文件更安全（官方管理文档推荐做法）。逐参数详解见《Kresus 0.26.0 配置参数详解》。

六、Woob 命令行交互

Woob 是 Kresus 银行同步的执行引擎（Python 生态，制品内置 3.7）。Kresus 的管理命令不覆盖模块维护，银行模块排查需直接使用 Woob CLI：

6.1 版本确认：`woob --version`

docker exec kresus-0.26.0-app woob --version

实测回显：

woob v3.7
Copyright(C) 2010-2026 Romain Bignon

6.2 通用帮助：`woob --help`

docker exec kresus-0.26.0-app woob --help

实测回显（头部与子命令段节选）：

usage: woob [-h] [--version] [-d DEBUG] [-a] command ...

Use the woob command to update or interact with woob.

commands:
  version       display version and help
  update        update woob
  repositories  manage repositories
  applications  search applications
  config        edit configuration
  ...（中间省略为其余内置能力命令行）...
  video         search and download videos
  weather       fetch weather forecasts

woob 是多能力聚合 CLI（视频/天气/翻译等十余个域），Kresus 实际只使用其 bank（银行）域与核心更新机制。

6.3 银行模块列表：`woob bank list`

docker exec kresus-0.26.0-app woob bank list

实测回显（头部节选）：

There is currently no configured backend for bank

Available modules:
 1) [ ] abeilleassurances   Abeille Assurances
 2) [ ] afer                Association française d'épargne et de retraite
 3) [ ] allianzbanque       Allianz Banque
 4) [ ] amazonstorecard     Amazon Store Card
 5) [ ] americanexpress     American Express

实测统计：模块行 96 条（编号 1—96，从 Abeille Assurances 到 Yomoni），覆盖法国及部分欧美银行/保险机构；输出末行出现 Select a backend to create: 交互提示（列表后默认进入交互选择）。模块名前的 [ ] 为启用状态位。

⚠️ 中文语境注意：96 个模块中无中国内地银行与支付平台。中文用户的交易数据走 Kresus 手工录入或文件导入；Woob 模块生态的边界与选型影响详见《Kresus 0.26.0 介绍与选型指南》。

6.4 模块更新机制

实测观测到的更新链路（官方入口脚本，每次实例启动自动执行）：

[ENTRYPOINT] Installing or upgrading woob...
Collecting woob
  Downloading woob-3.7-py3-none-any.whl (514 kB)
...
[ENTRYPOINT] Done installing.

即 pip 升级 Woob 本体（银行模块随包分发）；另一次实测（模块仓库在线更新）日志形态：

New modules available, only from secure sources: banks
Assuming YES for update...
2026-10-23 17:34:41,442:INFO:root:All modules are up-to-date

手动更新形态（排查模块失效时）：woob update（核心仓库更新）。生产环境无需手动例行执行——实例每次重启都会自动完成升级检查。

七、常用 CLI 命令速查表

命令	作用	关键实测行为
`kresus --help` / `-h` / `help`	帮助	列出全部子命令
`kresus --config $path` / `-c $path`	以指定配置启动服务	生产模式必须显式提供
`kresus create:config`	生成最新配置母本（stdout）	289 行六节 28 参数，随版本同步
`kresus create:user <login> [--admin]`	创建用户	回显 id；需重启实例生效
`kresus delete:user <login>`	删除用户及数据	级联删除；目标不存在报 `No user with this login`
`kresus list:users`	列出用户	含 id/login/isAdmin
`woob --version`	Woob 版本	实测 v3.7
`woob bank list`	银行模块列表	实测 96 模块；末行进入交互选择
`woob update`	手动更新模块仓库	例行无需手动（启动自动升级）

八、常见问题（FAQ）

Q1：管理命令报数据库连接错误？ 子命令需要数据库配置。Docker 编排形态内环境变量已齐备可直接执行；裸装形态请与管理启动一致地传 --config（kresus --config /path/config.ini list:users），并确认 PostgreSQL 可达。

Q2：create:user 成功后界面里看不到新用户？ 官方回显明示需重启实例（You will have to restart your kresus instance to access it.）。执行 docker compose restart kresus 后生效。

Q3：删除用户时报 No user with this login？ 登录名拼写错误或用户此前已删除。用 list:users 核对当前存在的登录名后再执行。

Q4：为什么 Kresus 用户不等于登录账号？ Kresus 无内置登录认证（官方文档明确警告），用户仅是数据隔离单元；公网访问控制走反向代理认证或 config.ini 的 auth Basic Auth（配置见《Kresus 0.26.0 配置参数详解》）。

Q5：woob bank list 后光标停在 Select a backend to create:？ 列表展示完默认进入交互式 backend 创建流程；CLI 场景直接 Ctrl-C 退出即可，不影响模块数据。

九、参考链接

官方管理文档：https://kresus.org/en/admin.html
Woob 项目：https://woob.tech/
代码仓库（CLI 实现位于 bin/kresus.js 与 server/lib/cli.js）：https://git.kresus.org/kresus/kresus
本平台同组件文档：《Kresus 0.26.0 介绍与选型指南》、《Kresus 0.26.0 Docker Compose 部署指南》、《Kresus 0.26.0 配置参数详解》

Kresus 0.26.0 常用 CLI 命令详解

Kresus 0.26.0 常用 CLI 命令详解

一、环境信息

二、前置条件

2.1 确认 CLI 可调用

2.2 调用形态说明

三、启动命令形态

3.1 生产标准启动：kresus --config <路径>

3.2 无参数启动的行为

四、用户管理命令

4.1 列出用户：kresus list:users

4.2 创建用户：kresus create:user <login> [--admin]

4.3 删除用户：kresus delete:user <login>

4.4 用户管理速查

五、配置生成命令：kresus create:config

六、Woob 命令行交互

6.1 版本确认：woob --version

6.2 通用帮助：woob --help

6.3 银行模块列表：woob bank list

6.4 模块更新机制

七、常用 CLI 命令速查表

八、常见问题（FAQ）

九、参考链接

3.1 生产标准启动：`kresus --config <路径>`

4.1 列出用户：`kresus list:users`

4.2 创建用户：`kresus create:user <login> [--admin]`

4.3 删除用户：`kresus delete:user <login>`

五、配置生成命令：`kresus create:config`

6.1 版本确认：`woob --version`

6.2 通用帮助：`woob --help`

6.3 银行模块列表：`woob bank list`