ezbookkeeping 2.1.0 常用 CLI 命令与工具详解

目标：面向已部署 ezBookkeeping v2.1.0、需要通过命令行完成用户管理、数据维护、安全运维的读者，逐条实测官方单二进制的 6 大命令组共 30 余个子命令：参数说明与真实回显一一对应，覆盖用户增删改禁、会话签发与吊销、交易导出导入闭环、数据一致性校验、定时任务、密钥生成与请求 ID 解析等全部场景。本文全部输出在 Ubuntu 22.04.4 LTS 实测采集，未做任何模拟。

ezbookkeeping财务记账自托管2026/10/23

ezbookkeeping 2.1.0 常用 CLI 命令与工具详解

目标：面向已部署 ezBookkeeping v2.1.0、需要通过命令行完成用户管理、数据维护、安全运维的读者，逐条实测官方单二进制的 6 大命令组共 30 余个子命令：参数说明与真实回显一一对应，覆盖用户增删改禁、会话签发与吊销、交易导出导入闭环、数据一致性校验、定时任务、密钥生成与请求 ID 解析等全部场景。本文全部输出在 Ubuntu 22.04.4 LTS 实测采集，未做任何模拟。

一、环境信息

项目值
软件版本ezBookkeeping v2.1.0（commit ff168cf，--version 实测输出 ezBookkeeping version 2.1.0 (commit ff168cf)）
运行形态官方二进制部署于 /usr/local/bin/ezbookkeeping/（安装方式见 B1 安装指南），SQLite 数据库
实测环境Ubuntu 22.04.4 LTS（内核 6.8.0-138-generic）
实测日期2026-10-23
关联文档《ezbookkeeping 2.1.0 介绍与选型指南》、《ezbookkeeping 2.1.0 Docker Compose 部署指南》、《ezbookkeeping 2.1.0 配置参数详解》

二、工具概览

ezBookkeeping 的 CLI 与服务端是同一个二进制，不带子命令直接运行即报错，--help 输出顶层命令组：

$ ./ezbookkeeping --help
NAME:
   ezBookkeeping - An open source, powerful, self-hosted personal finance app that is easy to use.

USAGE:
   ezBookkeeping [global options] [command [command options]]

VERSION:
   2.1.0 (commit ff168cf)

COMMANDS:
   server    ezBookkeeping web server operation
   database  ezBookkeeping database maintenance
   userdata  ezBookkeeping user data maintenance
   cron      ezBookkeeping cron job utilities
   security  ezBookkeeping security utilities
   utility   ezBookkeeping utilities
   help, h   Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --conf-path FILE  Custom config FILE path
   --no-boot-log     Disable boot log
   --help, -h        show help
   --version, -v     print the version

6 个命令组职责一览：

命令组职责子命令数
serverWeb 服务进程管理1（run）
database数据库表结构维护1（update）
userdata用户与记账数据维护21
cron定时任务查看与手动触发2（list / run）
security安全密钥生成1（gen-secret-key）
utility请求 ID 解析、测试邮件2

全局选项两个都有用：--conf-path 指定非默认位置的配置文件；--no-boot-log 屏蔽启动日志，脚本采集输出时更干净。

三、前置条件

  1. 已完成部署且服务至少成功启动过一次（多数子命令直接读写数据库，配置文件中的数据库连接必须有效）；
  2. 在安装目录下执行（见第五章坑点 1），本文示例统一使用 cd /usr/local/bin/ezbookkeeping && ./ezbookkeeping ... 形态；
  3. 涉及会话/令牌的命令需配置文件中 [security] enable_api_token = true（默认 false，见 4.3 节实测）；
  4. 交易导入导出命令在服务端本地读写文件，容器化部署时注意宿主与容器内路径映射。

四、各工具详解

4.1 server run：启动 Web 服务

$ ./ezbookkeeping server run

前台启动 Web 服务，加载配置、维护表结构、注册定时任务、监听 8080，与 systemd 单元内的启动命令一致。生产环境不建议手工裸跑（退出即停服），统一交给 systemd 或容器管理。

4.2 database update：表结构维护

$ ./ezbookkeeping database update

实测输出（节选）：

[INFO] [database.updateAllDatabaseTablesStructure] user custom icon table maintained successfully
[INFO] [database.updateAllDatabaseTablesStructure] user custom exchange rate table maintained successfully
[INFO] [database.updateAllDatabaseTablesStructure] insights explorer table maintained successfully
[INFO] [database.updateDatabaseStructure] all tables maintained successfully

升级新版本后如未开启 auto_update_database，或需要主动确认表结构状态时使用。幂等可重复执行。

4.3 userdata 用户管理

创建用户：

$ ./ezbookkeeping userdata user-add -n admin -m admin@example.com -i admin -p q1w2e3r4 -c CNY
[Uid] 3849848393941647360
[Username] admin
...
[UpdatedAt] 2026-10-23 05:11:53 (1792732313)
[LastLoginAt] 2026-10-23 05:11:53 (1792732313)

参数：-n 用户名、-m 邮箱、-i 昵称、-p 密码、-c 默认货币。这是管理员建号的推荐方式（配合 [user] enable_register = false 关闭自助注册）。

查询用户（输出含全量偏好设置与状态字段）：

$ ./ezbookkeeping userdata user-get -n test3
[Uid] 3849863580946006016
[Username] test3
[Email] test3@example.com
[DefaultCurrency] CNY
[FeatureRestriction]  (0)
[Deleted] false
[EmailVerified] true
[CreatedAt] 2026-10-23 05:13:51 (1792732431)

实测要点：EmailVerified 字段可直接验证 user-set-email-verified 的执行效果；禁用状态字段不在输出中，以命令日志为准。

改密 / 禁用 / 启用 / 标记邮箱已验证 / 关闭两步验证：

$ ./ezbookkeeping userdata user-modify-password -n test3 -p n3wPass123
（执行成功无业务输出，仅 INFO 日志；实测用新密码经 Web API 登录成功）

$ ./ezbookkeeping userdata user-disable -n test3
[INFO] [user_data.disableUser] user "test3" has been set disabled

$ ./ezbookkeeping userdata user-enable -n test3
（成功无业务输出）

$ ./ezbookkeeping userdata user-set-email-verified -n test3
（成功无业务输出，user-get 中 EmailVerified 变为 true）

$ ./ezbookkeeping userdata user-2fa-disable -n test3
2026/10/23 05:14:15 Failed to run ezBookkeeping with [...]: two-factor is not enabled

注意：对未启用两步验证的用户执行 user-2fa-disable 报错 two-factor is not enabled，属预期行为（该命令用于用户丢失验证器后的强制解绑）。

删除用户：

$ ./ezbookkeeping userdata user-delete -n test2
[INFO] [user_data.deleteUser] user "test2" has been deleted

能力限制（配合 [security]/[user] 配置，编码含义见配置详解篇 5.11 节）：

$ ./ezbookkeeping userdata user-set-restrict-features -n test3 -t 17,13
（设置后该用户生成 API 令牌实测报错：you are not permitted to perform this action）

配套还有 user-add-restrict-features / user-remove-restrict-features 增量调整。注意语义是"限制清单"——填 17 表示禁止生成 API 令牌。

会话管理三件套：

$ ./ezbookkeeping userdata user-session-list -n admin
[CreatedAt] 2026-10-23 04:24:47 (1792729487)
[ExpiredAt] 2026-10-23 05:24:47 (1792733087)
[LastSeen] 2026-10-23 04:24:47 (1792729487)
[UserAgent] ezBookkeeping Cli
---
（多条记录以 --- 分隔）

签发离线会话令牌（为指定用户创建 JWT，供脚本/集成调用）：

$ ./ezbookkeeping userdata user-session-new -n admin -t api -e 3600
[CreatedAt] 2026-10-23 05:11:25 (1792732285)
[ExpiredAt] 2026-10-23 06:11:25 (1792735885)
[UserAgent] ezBookkeeping Cli
[NewToken] eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyVG9rZW5JZCI6IjIxODU0NzAwNTgxMTQ2Mjk1NDIiLCJqdGkiOiIzODQ5ODQ4MzkzOTQxNjQ3MzYwIiwidXNlcm5hbWUiOiJhZG1pbiIsInR5cGUiOjgsImlhdCI6MTc5MjczMjI4NSwiZXhwIjoxNzkyNzM1ODg1fQ.uErW_GeOGgDzmzz9bGihmaUm3sGHAXylegK5TRAv9Hw

参数：-t 令牌类型（api / mcp，默认 api）、-e 有效秒数（0 永不过期）。JWT 中间段 base64 解码可见 "type":8（API 令牌类型码，与 Web API 的 tokens/list 一致）。默认配置下此命令报错 api token is not enabled（排障实录见第六章 Q1）。

吊销单个会话 / 清空全部会话：

$ ./ezbookkeeping userdata user-session-revoke -n admin --token-id <列表中的令牌ID>
$ ./ezbookkeeping userdata user-session-clear -n test3

user-session-clear 实测成功无业务输出，用户所有端被迫重新登录。

4.4 userdata 记账数据维护

数据一致性校验（核对全部交易流水与账户余额，运维巡检利器）：

$ ./ezbookkeeping userdata transaction-check -n test3
[INFO] [user_data.checkUserTransactionAndAccount] starting checking user "test3" data
[INFO] [user_data.checkUserTransactionAndAccount] user transactions and accounts data has been checked successfully, there is no problem with user data

实测经验：该命令能抓出"未来时间交易导致余额不符"类异常（本文实测曾检出 expected 与 actual 金额不一致的账目并把问题交易定位到具体时间，修正后复检通过）。建议纳入月度巡检。

导出交易：

$ ./ezbookkeeping userdata transaction-export -n test3 -f /tmp/test3_tx.csv -t csv
[INFO] [user_data.exportUserTransaction] user transactions have been exported to /tmp/test3_tx.csv

导出文件实测内容（前 3 行）：

Time,Timezone,Type,Category,Sub Category,Account,Account Currency,Amount,Account2,Account2 Currency,Account2 Amount,Geographic Location,Tags,Description
2026-10-23 12:30:21,+08:00,Expense,餐饮,日常餐食,现金钱包,CNY,25.50,,,,,,
2026-10-23 12:29:21,+08:00,Transfer,账户互转,日常互转,招行储蓄卡,CNY,1000.00,现金钱包,CNY,1000.00,,,

-t 支持 csv / tsv。目标文件已存在时直接报错（第六章 Q5），不覆盖。

导入交易（支持格式：ezbookkeeping_csv、ezbookkeeping_tsv，即官方导出格式回导）：

$ ./ezbookkeeping userdata transaction-import -n test3 -f /tmp/admin_tx.csv -t ezbookkeeping_csv
[WARNING] [transactions.doCreateTransaction] cannot create trasaction, because UNIQUE constraint failed: transaction.uid, transaction.transaction_time, regenerate transaction time value
[INFO] [user_data.importUserTransaction] transactions have been imported to user "test3"

导入是前置校验失败即中止的模式，实测在全新用户上导入一份含 3 类交易 + 2 条建账记录的文件，依次触发并修复以下校验（每步报错后补齐再导）：

  1. there are 2 accounts (现金钱包,招行储蓄卡) need to be created, please create them manually → 需先手工为该用户创建同名账户；
  2. there are 1 expense categories (日常餐食) need to be created → 需建同名支出分类，且必须是二级分类（建父组"餐饮"+子分类"日常餐食"，只建一级分类无法通过校验）；
  3. 同理补齐收入分类（工资→月薪）与转账分类（账户互转→日常互转）；
  4. failed to create transaction, because balance modification transaction cannot add when other transaction exists → 若 CSV 含建账记录（Balance Modification 行），目标账户创建时初始余额必须为 0，否则建账交易与既有流水冲突；
  5. 全部就绪后导入成功，transaction-check 复检通过，重导出行数与原文件一致（实测 5 行闭环）。

WARNING 说明：导入器遇到"同用户同交易时间"的唯一约束冲突时会自动再生时间值（毫秒级偏移）并继续，不中断。

4.5 cron 定时任务

列出已启用任务：

$ ./ezbookkeeping cron list
[Name] RemoveExpiredTokens
[Description] Periodically remove expired user tokens from the database.
[Interval] Every 24h0m0s
---
[Name] CreateScheduledTransaction
[Description] Periodically create transaction by scheduled transaction template.
[Interval] Every 15m0s

手动触发：

$ ./ezbookkeeping cron run -n RemoveExpiredTokens
[INFO] [cron-job-removeexpiredtokens-1792732299] [tokens.DeleteAllExpiredTokens] no expired tokens have been deleted
[INFO] [cron-job-removeexpiredtokens-1792732299] [cron_job.doRun] run job "RemoveExpiredTokens" successfully, cost 0ms

适合定时任务异常后排障（手动执行观察日志）与验证任务逻辑变更。

4.6 security gen-secret-key：生成登录密钥

$ ./ezbookkeeping security gen-secret-key
[Secret Key] 4N7ZBHttloeHDxdpV18jaF6rKRXrgkCX

$ ./ezbookkeeping security gen-secret-key -l 64
[Secret Key] ixqGKNWcK2qRShGQxYVz9E1j3St9pgtnAyS4eAa5924DXpJ0ycRRm55feRmtkrR0

-l 指定长度（实测 32 与 64 均有效）。产出的密钥写入 [security] secret_key；一旦有用户数据即不可更换，务必生成后立即安全保存。

4.7 utility 诊断工具

解析请求 ID（配合响应头 X-Request-Id 定位请求来源）：

$ ./ezbookkeeping utility parse-default-request-id --id 85a87d04-1f11-c322-0000-00060a594601
[RequestId] 85a87d04-1f11-c322-0000-00060a594601
[ServerUniqId] 34216 (Current Server 34216)
[InstanceUniqId] 32004 (Current Server 32004)
[SecondsElapsedToday] 15907 (04:25:07)
[RequestSeqId] 1
[IsClientIpv6] false
[ClientIpv4] 10.89.70.1
[ClientPort] 49954

传入编造的 ID 会报错（第六章 Q2）。排障路径：客户端拿到 4xx/5xx 响应头中的 X-Request-Id → 本命令解析出时间与客户端 IP:Port → 到服务端日志检索同 ID。

发送测试邮件：

$ ./ezbookkeeping utility send-test-mail --to admin@example.com

验证 [mail] 配置是否可用。SMTP 未启用时直接报 SMTP server is not enabled（第六章 Q3）；配置正确但服务器不可达时报 dial tcp ...: connect: connection refused 类网络错误——两种报错的差异用于区分"没配置"与"连不上"。

五、注意事项

  1. 必须从安装目录运行：默认配置路径按当前工作目录解析。实测在其他目录执行报错 cannot get default configuration path, because stat /conf/ezbookkeeping.ini: no such file or directory（它把配置找去了 <CWD>/conf/）。统一 cd 到安装目录，或显式 --conf-path /usr/local/bin/ezbookkeeping/conf/ezbookkeeping.ini。
  2. 配置快照日志是每个命令的前缀输出：几乎所有子命令启动时打印一段完整配置 JSON（敏感项脱敏），脚本采集输出时先过滤，或加 --no-boot-log。
  3. 写库命令直接操作数据库文件：user-add、transaction-import 等不经过 Web API，容器化部署时必须在容器内执行或保证配置指向同一数据库文件，且建议停服窗口操作避免并发写。
  4. 导入导出是官方格式闭环：ezbookkeeping_csv/tsv 即本工具导出格式；迁移/备份演练建议"导出 → 新用户导入 → transaction-check → 重导出比对行数"四步闭环验证。
  5. 分类必须二级：交易只能挂二级分类，导入校验同样按"父组+子分类"名称匹配，一级分类建得再多也无法通过导入校验。
  6. 枚举数值差异：交易类型（1 余额修改 / 2 收入 / 3 支出 / 4 转账）与分类类型（1 收入 / 2 支出 / 3 转账）数值不一致，脚本处理时易混，导出 CSV 中为英文名称（Expense/Income/Transfer/Balance Modification）。
  7. 删除用户后用户名与邮箱不释放：实测 user-delete 后立即 user-add 同名或同邮箱报 UNIQUE constraint failed: user.username / user.email，重建需换名（数据库为软删除设计）。

六、常见问题

Q1：user-session-new 报 api token is not enabled

[security] enable_api_token 默认 false。改为 true 并重启服务后重新执行即可；实测签发成功且 user-session-list 可见 UserAgent: ezBookkeeping Cli 记录。该报错同样会出现在 Web API 的令牌生成接口上。

Q2：parse-default-request-id 报 request id is invalid

传入的必须是服务端真实生成的请求 ID（格式为 8-4-4 段复合编码，见 4.7 节实例），自造字符串无法解析。从任意 API 响应头 X-Request-Id 获取真实值再解析。

Q3：send-test-mail 报 SMTP server is not enabled

[mail] enable_smtp = true 后重启再试；若变为 connection refused 则配置门已通过，进入网络层排查 SMTP 地址与端口。

Q4：transaction-import 报 operation failed 但没说原因

向上翻日志，[ERROR] [user_data.ImportTransaction] there are N accounts/categories ... need to be created 才是根因——导入器的"operation failed"是外层包装，按 4.4 节的校验链逐步补齐账户与二级分类。

Q5：transaction-export 报 file already exists

导出不覆盖既有文件，换文件名或先删除目标文件再导。

Q6：导入时报 balance modification transaction cannot add when other transaction exists

CSV 中的建账记录（Balance Modification）与目标账户已有的流水冲突。目标账户初始余额保持 0，让导入文件自带的建账记录来设置余额。

Q7：命令找不到配置文件

见第五章坑点 1：换到安装目录运行或用 --conf-path 指定绝对路径。

七、参考链接

  1. 官方命令行文档：https://ezbookkeeping.mayswind.net/command_line
  2. GitHub 仓库（mayswind/ezbookkeeping）：https://github.com/mayswind/ezbookkeeping
  3. 站内关联阅读：《ezbookkeeping 2.1.0 介绍与选型指南》、《ezbookkeeping 2.1.0 Docker Compose 部署指南》、《ezbookkeeping 2.1.0 配置参数详解》

以上全部命令与回显均在 Ubuntu 22.04.4 LTS、ezBookkeeping v2.1.0 官方二进制上实测采集，实测日期 2026-10-23。