Bigcapital v0.25.44 常用 CLI 命令与工具详解

Bigcapital 的服务端日常管理围绕一套自带的迁移 CLI（node dist/cli.js）展开，覆盖系统库与租户库的迁移、回滚、迁移文件生成、租户列表、数据种子、OpenAPI 文档导出与 ClickHouse 分析回填，共 12 个子命令；配合 pnpm 生命周期脚本完成前后端构建。本文基于 v0.25.44 在 Ubuntu 22.04 源码直装环境中对全部子命令逐条实测，给出真实回显、参数说明与排障实录。

部署路径与 CLI 的安装来源见《Ubuntu 22.04 安装 Bigcapital v0.25.44 指南》；环境变量见《Bigcapital v0.25.44 配置参数详解》；容器化形态的迁移初始化见《Bigcapital v0.25.44 Docker Compose 部署指南》。

本文全部命令与回显在实测环境中逐条执行采集（2026-10-22），涉及破坏性操作的子命令（回滚类）按文中的风险提示处理。

一、环境信息

项目	说明
软件	Bigcapital v0.25.44（官方发布源码包，源码直装）
服务器	Ubuntu 22.04.5 LTS，12 核 31 GiB
运行时	Node.js v18.20.8 / pnpm 9.0.5 / MariaDB 10.6.23 / Redis 6.0.16
CLI 入口	`/opt/bigcapital/packages/server/dist/cli.js`
数据状态	系统库 31 个迁移（Batch 1）；2 个已初始化组织（租户库各 70 张表）

二、工具概览

工具	用途	入口
迁移 CLI	系统库/租户库迁移、回滚、迁移文件生成、租户列表、种子、OpenAPI 导出、分析回填	`cd /opt/bigcapital/packages/server && node dist/cli.js <子命令>`
pnpm 脚本	前后端构建	`cd /opt/bigcapital && pnpm build:server` / `pnpm build:webapp`
MariaDB 客户端	库表核查、手工备份	`mysql -u bigcapital -p`
Redis 客户端	队列健康检查	`redis-cli`
systemd/journalctl	服务管理与日志	`systemctl status bigcapital-server` / `journalctl -u bigcapital-server -f`

CLI 帮助全文（node dist/cli.js --help 实测）：

Usage: cli [options] [command]

Options:
  -h, --help                          display help for command

Commands:
  system:migrate:latest               Migrate latest migration of the system
                                      database.
  system:migrate:rollback             Rollback the last batch of system
                                      migrations.
  system:migrate:make <name>          Create a named migration file to the
                                      system database.
  tenants:migrate:latest [options]    Migrate all tenants or the given tenant
                                      id.
  tenants:migrate:rollback [options]  Rollback the last batch of tenants
                                      migrations.
  tenants:migrate:make <name>         Create a named migration file to the
                                      tenants database.
  tenants:list [options]              Retrieve a list of all system tenants
                                      databases.
  system:seed:latest                  Seed system database with the latest data
  tenants:seed:latest                 Seed all tenant databases with the latest
                                      data
  openapi:export                      Export the OpenAPI document from the
                                      NestJS app to shared/sdk-ts/openapi.json
  analytics:backfill [options]        Backfill the ClickHouse analytics store
                                      with the ledger data of all the
                                      initialized tenant databases (or a
                                      specific organization with
                                      --organization).
  help [command]                      display help for command

三、前置条件

必须在 packages/server 目录下执行迁移 CLI：迁移目录按「当前工作目录 + ./src/database/system/migrations」解析，在源码根目录执行会报 ENOENT（排障见 6.1）。
数据库账号就绪且具备 bigcapital% 前缀库权限（安装指南 4.5 的授权）。
建议以运行账号（bigcapital）而非 root 执行，避免构建缓存与文件属主混乱。
认识各子命令的风险等级再动手：

风险	子命令	说明
只读	`tenants:list`、`--help` 系列	无副作用
幂等写入	`system:migrate:latest`、`tenants:migrate:latest`、`openapi:export`	已执行过的迁移自动跳过
结构变更	`system:migrate:make`、`tenants:migrate:make`	仅生成迁移文件，需手工编写后再迁移
破坏性	`system:migrate:rollback`、`tenants:migrate:rollback`	回滚迁移批次，可能删表删列，执行前必须备份

四、各工具详解

4.1 system:migrate:latest：系统库迁移到最新

cd /opt/bigcapital/packages/server
node dist/cli.js system:migrate:latest

全新系统库上的实测回显：

Batch 1 run: 31 migrations

已全部执行时再次运行（幂等）：

Already up to date

升级到新版源码后执行时，只运行新增迁移（实测 v0.25.42 → v0.25.44 升级）：

Batch 2 run: 1 migrations

执行后系统库共 31 个迁移记录、17 张表（含 2 张 knex 迁移账目表）。

4.2 system:migrate:rollback：回滚系统库最近一个迁移批次

cd /opt/bigcapital/packages/server
node dist/cli.js system:migrate:rollback

⚠️ 该命令为破坏性操作，且回滚粒度是「最后一个批次」。实测环境的教训值得完整记录：由于全新安装时 31 个迁移落在同一批次（Batch 1），执行回滚意味着一次性倒放全部 31 个迁移的 down() 函数，结果在旧迁移 20240728123419_add_trial_columns_to_subscription_table.js 处失败：

migration file "20240728123419_add_trial_columns_to_subscription_table.js" failed
migration failed with error: table.dropColumn(...).nullable is not a function

且回滚启动时会先给迁移账目表加锁，中途失败后锁未释放，下次再执行报：

Error: Migration table is already locked

完整排障过程（锁表核查、解锁 SQL、根因分析与库重建恢复）见 6.2 与 6.3。生产环境执行回滚前务必：mysqldump 完整备份系统库、用 SELECT * FROM knex_migrations; 确认批次构成、评估批次内全部 down() 的可逆性。

4.3 system:migrate:make：生成系统库迁移文件

node dist/cli.js system:migrate:make add_demo_column

Created Migration: /opt/bigcapital/packages/server/src/database/system/migrations/20261022181642_add_demo_column.js

生成的迁移骨架（实测文件内容，up/down 默认为空函数）：

/**
 * @param { import("knex").Knex } knex
 * @returns { Promise<void> }
 */
exports.up = function(knex) {

};

/**
 * @param { import("knex").Knex } knex
 * @returns { Promise<void> }
 */
exports.down = function(knex) {

};

在骨架中编写完 up/down 后，用 4.1 的 system:migrate:latest 应用。文件名前缀为生成时间戳，保证执行顺序。

4.4 tenants:migrate:latest：租户库迁移到最新

对全部已初始化租户库执行：

node dist/cli.js tenants:migrate:latest

实测回显（两个租户，均已是最新）：

All tenants are migrated.

仅迁移指定组织（-t / --tenant_id 参数，值为组织 ID）：

node dist/cli.js tenants:migrate:latest -t 4f65c9taovmvjv7avc

Tenant bigcapital_tenant_4f65c9taovmvjv7avc > Batch 2 run: 0 migrations
-------------------

-t 的帮助说明（node dist/cli.js tenants:migrate:latest --help）：

Migrate all tenants or the given tenant id.

Options:
  -t, --tenant_id [tenant_id]  Which organization id do you migrate.
  -h, --help                   display help for command

组织初始化（网页注册后首次进入）会自动对租户库执行一轮迁移，因此日常升级时该命令通常显示 0 migrations。

4.5 tenants:migrate:rollback：回滚租户库迁移批次（高危）

node dist/cli.js tenants:migrate:rollback

帮助说明（--help 实测）：

Rollback the last batch of tenants migrations.

Options:
  -t, --tenant_id [tenant_id]  Which organization id do you rollback.
  -h, --help                   display help for command

语义与 4.2 相同，但作用于全部或指定租户库。本文未在生产样例数据上执行该命令——租户库存放组织全部账套数据，回滚批次会删表删列且财务数据不可再生；确需回滚时按「单库备份 → -t 指定单组织 → 验证 → 逐组织推进」的流程操作。

4.6 tenants:migrate:make：生成租户库迁移文件

node dist/cli.js tenants:migrate:make add_demo_column

Created Migration: /opt/bigcapital/packages/server/dist/database/tenant/migrations/20261022181644_add_demo_column.js

注意与 4.3 的差异（实测确认的不对称行为）：系统库迁移生成到 src/ 源码目录，租户库迁移生成到 dist/ 构建产物目录。二者骨架内容一致（同 4.3），生成后均需手工编写再应用。

4.7 tenants:list：列出全部租户库

node dist/cli.js tenants:list

实测回显（两个已初始化组织）：

ID: 1 | Organization ID: 4f65c9taovmvjv7avc | DB Name: bigcapital_tenant_4f65c9taovmvjv7avc
ID: 2 | Organization ID: 4f65c9taovmvjv7ay1 | DB Name: bigcapital_tenant_4f65c9taovmvjv7ay1

带 -a（--all）时包含未完成初始化的租户。该命令是核查「组织 ↔ 租户库」对应关系的第一工具，数据库侧可用 SHOW DATABASES LIKE 'bigcapital_tenant%'; 交叉验证。

4.8 system:seed:latest 与 tenants:seed:latest：数据种子

node dist/cli.js system:seed:latest

System seeding with latest data - No operation performed

node dist/cli.js tenants:seed:latest

Tenants seeding with latest data - No operation performed

两条命令用于把官方预置的基础数据（种子）补入系统库/租户库，实测环境无待执行种子，均提示无操作。正常安装流程中迁移与初始化已覆盖所需数据，该命令主要在新版本附带新种子时使用。

4.9 openapi:export：导出 OpenAPI 接口文档

node dist/cli.js openapi:export

OpenAPI spec written to /opt/bigcapital/shared/sdk-ts/openapi.json

产物为 1.4 MB 的 OpenAPI JSON，覆盖全部 REST 接口定义，可用于生成客户端 SDK 或导入接口调试工具。Server 运行期也可直接访问 http://127.0.0.1:3000/swagger 查看（实测 HTTP 200）。

4.10 analytics:backfill：ClickHouse 分析数据回填

node dist/cli.js analytics:backfill

帮助说明（--help 实测）：

Backfill the ClickHouse analytics store with the ledger data of all the
initialized tenant databases (or a specific organization with --organization).

Options:
  -o, --organization <organizationId>  Rebuild the data of a specific
                                       organization only.
  -h, --help                           display help for command

未启用 ClickHouse 时的实测报错：

Error: ClickHouse is not enabled. Set CLICKHOUSE_ENABLED=true.

该命令依赖 .env 中 CLICKHOUSE_ENABLED=true 与可用 ClickHouse 实例（参数详见配置详解 5.10），用于把账套数据回填进分析库或按组织重建汇总。

4.11 pnpm 构建脚本

源码根目录的两个核心脚本（构建产物是 CLI 与服务运行的前提）：

cd /opt/bigcapital && pnpm build:server

实测回显（头部）：


> bigcapital-monorepo@ build:server /opt/bigcapital
> lerna run build --scope "@bigcapital/server" --scope "@bigcapital/utils" --scope "@bigcapital/pdf-templates" --scope "@bigcapital/email-components"

lerna notice cli v8.1.3

实测回显（尾部）：


 Lerna (powered by Nx)   Successfully ran target build for 4 projects

pnpm build:webapp 结构相同（scope 为 webapp/utils/pdf-templates/sdk-ts，同样 4 个项目）。安装期依赖命令为 pnpm install（2864 个包）。

4.12 配套运维工具

MariaDB 核查（租户库清单与表数量）：

mysql -u bigcapital -pq1w2e3r4 -e "SHOW DATABASES LIKE 'bigcapital%';"

Database (bigcapital%)
bigcapital_system
bigcapital_tenant_4f65c9taovmvjv7avc
bigcapital_tenant_4f65c9taovmvjv7ay1

mysql -u bigcapital -pq1w2e3r4 -e "SELECT COUNT(*) AS tenant_tables FROM information_schema.tables WHERE table_schema='bigcapital_tenant_4f65c9taovmvjv7avc';"

tenant_tables
70

Redis 健康检查（任务队列依赖）：

redis-cli ping

PONG

MariaDB 运行状态：

mysqladmin -u bigcapital -pq1w2e3r4 status

Uptime: 3179  Threads: 9  Questions: 1838  Slow queries: 0  Opens: 1207  Open tables: 49  Queries per second avg: 0.578

服务日志（源码直装形态）：

journalctl -u bigcapital-server -f

五、注意事项

执行目录：迁移 CLI 一律在 packages/server 目录运行，其他目录会因迁移目录解析失败报 ENOENT。
执行账号：统一使用 bigcapital 运行账号（sudo -u bigcapital），root 与普通账号混用会在构建缓存与迁移锁上产生权限类故障。
顺序：升级后先 system:migrate:latest 再 tenants:migrate:latest——租户库迁移依赖系统库中的租户登记。
回滚前必备份：system:migrate:rollback/tenants:migrate:rollback 均为破坏性操作；全新安装的迁移集中在同一批次，回滚会倒放全部迁移（见 6.3 的真实教训）。
单租户灰度：租户库操作优先用 -t 指定组织，确认无误后再放开全量。

六、常见问题

6.1 迁移报 ENOENT：scandir src/database/system/migrations

现象：在源码根目录执行迁移 CLI 时报：

Error: ENOENT: no such file or directory, scandir '/opt/bigcapital/src/database/system/migrations'

原因与解决：迁移目录按当前工作目录解析（./src/database/system/migrations）。切换到 packages/server 目录执行即可：

cd /opt/bigcapital/packages/server && node dist/cli.js system:migrate:latest

6.2 迁移报 Error: Migration table is already locked

现象：执行迁移或回滚时报：

Error: Migration table is already locked

定位：knex 在迁移账目表 knex_migrations_lock 上用 is_locked=1 防并发。锁残留的两种来源：其一是迁移进程被中途杀死（如手工 kill 构建或服务进程时迁移正在运行）；其二是回滚执行失败后锁未释放（本环境实测遇到的就是这种，见 6.3）。核查锁状态：

mysql -u bigcapital -pq1w2e3r4 -e "SELECT * FROM bigcapital_system.knex_migrations_lock;"

index   is_locked
1       1

解决：确认没有任何迁移进程在跑后，手工复位锁再重跑：

mysql -u bigcapital -pq1w2e3r4 -e "UPDATE bigcapital_system.knex_migrations_lock SET is_locked=0;"

若解锁后重跑仍失败，说明锁之外还有根因（本环境即 6.3 的回滚 bug），需按 6.3 处理。

6.3 回滚失败：table.dropColumn(...).nullable is not a function

现象：system:migrate:rollback 报：

migration file "20240728123419_add_trial_columns_to_subscription_table.js" failed
migration failed with error: table.dropColumn(...).nullable is not a function

定位：该 2024 年旧迁移的 down() 使用了与当前 knex 版本不兼容的链式写法；且回滚以「批次」为单位，全新安装时 31 个迁移同属 Batch 1，一次回滚要倒放全部 31 个 down()，倒放到该文件即中断——此时部分表结构已被回滚、锁表残留，系统库处于不一致状态。

恢复（实测环境做法）：由于是测试环境，直接重建系统库并重新执行迁移，随后重新注册账号、重建组织：

mysql -u bigcapital -pq1w2e3r4 -e "DROP DATABASE bigcapital_system; CREATE DATABASE bigcapital_system CHARACTER SET utf8 COLLATE utf8_general_ci;"
cd /opt/bigcapital/packages/server && node dist/cli.js system:migrate:latest

Batch 1 run: 31 migrations

生产环境教训：不要对「单批次全量迁移」的系统库执行整批回滚；确需回退时，以升级前的 mysqldump 备份做库级恢复替代迁移倒放（备份恢复无 down() 兼容性风险）。

6.4 启动日志中的 Redis 版本提示

Server 启动与 CLI 执行时日志反复出现：

It is highly recommended to use a minimum Redis version of 6.2.0
             Current: 6.0.16

这是兼容性建议而非错误：Ubuntu 22.04 官方仓库的 Redis 为 6.0.16，实测队列功能（组织初始化、租户库创建）正常。生产环境建议升级到 6.2+（配置详解 5.10 亦有 ClickHouse 相关约束说明）。

七、参考链接

Bigcapital 官方仓库：https://github.com/bigcapitalhq/bigcapital
v0.25.44 发布页：https://github.com/bigcapitalhq/bigcapital/releases/tag/v0.25.44
站内相关文档：
- 《Bigcapital v0.25.44 介绍与选型指南》——软件定位与选型
- 《Ubuntu 22.04 安装 Bigcapital v0.25.44 指南》——源码直装全流程
- 《Bigcapital v0.25.44 Docker Compose 部署指南》——整套部署形态
- 《Bigcapital v0.25.44 配置参数详解》——环境变量逐项说明