Chartbrew 6.0.0 常用 CLI 命令与运维实操

Chartbrew 6.0.0 的命令行运维面实测：npm scripts 脚本矩阵（迁移/保留期清理/画像回填/渲染冒烟）、PM2 进程托管、mysqldump 备份恢复闭环与 redis-cli 巡检，全部命令真实回显。

ChartbrewCLI 命令运维运维Node.jsMySQLRedis2026/11/03

Chartbrew 6.0.0 常用 CLI 命令与运维实操

目标：给出一套 Chartbrew 6.0.0 的日常命令行运维手册——启停、迁移、数据治理脚本、进程托管、备份恢复、缓存巡检，每条命令附 2026-11-03 在 /opt/chartbrew 部署实例上的真实回显。配置参数语义见 《Chartbrew 6.0.0 配置参数详解》，安装过程见 《Chartbrew Docker Compose 部署指南》。

一、环境信息

  • 应用：Chartbrew 6.0.0，安装目录 /opt/chartbrew（下文脚本类命令均在 /opt/chartbrew/server 执行）
  • 运行时：Node v22.23.4 / npm 10.9.9；进程托管 PM2 7.1.1（npm install -g pm2 实装）
  • 依赖服务：MySQL 8.4.13（192.168.1.200:3306，库 chartbrew/63 表，账号 chartbrew 与 root，密码均 q1w2e3r4）、Redis 7.4.12（6379，AOF 开）
  • 端点：API 0.0.0.0:4019，前端 8129（演示账号 admin@quzuo.net / q1w2e3r4）
  • 环境要求：脚本连接库与 Redis 依赖 /opt/chartbrew/.env 中的 CB_DB_*/CB_REDIS_*；跨网主机执行时显式带 CB_DB_HOST/CB_REDIS_HOST 环境变量（见各节）

二、工具总览

先说清一个易踩的认知坑：Chartbrew 没有独立的 chartbrew 命令行程序——npm 公共仓库不存在 chartbrew 包（registry 实查 404，2026-11-03），它的 CLI 面就是三类现成工具的组合：

工具位置用途
node index.js/opt/chartbrew/server后端启动入口（NODE_ENV=production）
npm scripts/opt/chartbrew/server/package.json（实测 15 条）迁移、数据治理、渲染冒烟等运维脚本
PM2 7.1.1全局进程守护、cluster、日志、开机自启
mysql / mysqldumpmysql 客户端元数据库备份恢复与 SQL 巡检
redis-cliredis 客户端队列/缓存巡检
npx serve前端产物静态服务单独托管 client/dist（镜像内置 serve 14.2.6）

server/package.json 的 scripts 全量清单（实测回显，节选运维相关）：

$ node -e "const s=require('./package.json').scripts;for(const k in s)console.log(k+' = '+s[k])"
start = node index.js
db:create = sequelize db:create
db:migrate = sequelize db:migrate
db:migrate:undo = sequelize db:migrate:undo
db:seed:create = sequelize seed:create
db:seed:generate = node ./scripts/generateSeed
db:seed = sequelize db:seed --seed 20220905000000-create-demo-data.js
db:seed:undo:all = sequelize db:seed:undo --seed 20220905000000-create-demo-data.js
db:seed:undo:dev = sequelize db:seed:undo --seed 20240827120000-create-dev-data.js
db:seed:dev = sequelize db:seed --seed 20240827120000-create-dev-data.js
db:undo:all = sequelize db:migrate:undo:all
retention:run = node scripts/runRetention.js
intelligence:backfill = node scripts/backfillDatasetIntelligence.js
image:smoke = node scripts/runImageSmoke.js
observations:audit-report = node scripts/runObservationsAuditReport.js
maps:import = node scripts/importMaps.js

三、前置条件

  1. 服务已按部署篇就绪，/opt/chartbrew/server 下 npm ls sequelize-cli 可解析；
  2. 运维账号可连通元数据库与 Redis；
  3. 执行数据治理脚本前完成一次备份（见 4.7），涉及库结构的命令（db:undo:all、seed）务必先备份再动。

四、各工具详解

4.1 启动与停止

前台启动（生产模式，端口经 CB_API_PORT 指定，优先级 PORT > CB_API_PORT > 4019）：

$ cd /opt/chartbrew/server
$ CB_REDIS_HOST=redis CB_DB_HOST=db NODE_ENV=production CB_API_PORT=4025 node index.js &
[runtime-cache] using Redis via CB_REDIS settings
Socket.IO Redis Sub Client ready
Socket.IO Redis Pub Client ready
✓ Socket.IO Redis adapter enabled for cross-process communication
Running server on port 4025
[retention-cleanup] Starting scheduled cleanup

Running server on port 4025 即就绪；Socket.IO Redis adapter enabled 表示跨进程广播可用。停止与验证：

$ kill 1468
$ node -e "fetch('http://127.0.0.1:4025/').catch(e=>console.log('after kill:',e.cause?.code||e.message))"
after kill: ECONNREFUSED 127.0.0.1:4025

⚠️ 注意：多实例并存时只有主实例（未设 NODE_APP_INSTANCE 或值为 0）挂载队列面板并跑定时任务；从实例只做 API/Socket 负载。运维排查「面板 404/任务没跑」先确认打到的是不是主实例（配置篇 5.7）。

4.2 数据库迁移

升级或改表后用 db:migrate 对齐 schema（幂等，已最新时无副作用）：

$ npm run db:migrate
Database schema is up to date!

全新安装时同一条命令会顺序执行 59 个迁移、建出 63 张表（部署篇首启日志即此过程）。回滚类命令 db:migrate:undo/db:undo:all 存在但生产禁用——Sequelize 的 undo 会真删表数据，版本回退请用备份恢复（4.7）替代。

4.3 保留期清理 retention:run

按配置篇 5.11 的 7 组保留期参数清理历史数据，可手动执行也可等内置定时器（启动日志可见 [retention-cleanup] Starting scheduled cleanup）：

$ npm run retention:run
> node scripts/runRetention.js
[retention-cleanup] Starting cleanup
[retention-cleanup] Starting workspace learning cleanup
[retention-cleanup] Workspace learning cleanup completed
[retention-cleanup] Starting observation cleanup
[retention-cleanup] Observation cleanup completed
[retention-cleanup] Starting update audit cleanup
[retention-cleanup] Update audit cleanup completed
[retention-cleanup] Completed cleanup
{
  "workspaceLearning": {
    "actionAudits": { "cutoff": "2025-11-02T23:15:32.316Z", "matched": 0, "deleted": 0 },
    ...
  },
  "observations": {
    "runs": { "cutoff": "2024-11-02T23:15:32.316Z", "matched": 0, "deleted": 0 },
    ...
  },
  "updateAudits": {
    "default": {
      "cutoff": "2025-11-02T23:15:32.316Z",
      "matched": 0,
      "deleted": 0,
      "batches": 0,
      "runtimeMs": 2
    }
  }
}
[retention-cleanup] Completed

回显 JSON 逐类给出 cutoff/matched/deleted，是核对保留期配置是否生效的最直接手段（30 天档 cutoff 恰为执行时刻减 30 天）。

4.4 数据集画像回填 intelligence:backfill

v6 数据集智能画像的存量补齐脚本，按 CB_DATASET_INTELLIGENCE_BACKFILL_BATCH_SIZE 分批：

$ npm run intelligence:backfill
> node scripts/backfillDatasetIntelligence.js
[dataset-intelligence] backfill completed {
  processed: 0,
  profiled: 0,
  failed: 0,
  skipped: 0
}

演示库无真实业务数据集，故计数全 0；接入数据源后该命令会为缺画像的数据集批量生成字段画像（命令语义见官方文档 environment-variables 篇）。

4.5 图表渲染冒烟 image:smoke

验证 Chromium 渲染链路（邮件快照/图片导出的底座）是否可用：

$ npm run image:smoke
> node scripts/runImageSmoke.js
Image smoke test passed: {"name":"line","path":"/opt/chartbrew/server/tmp/image-smoke/line.png"}

返回 passed 且落出 PNG 即渲染链路健康；失败通常是缺浏览器依赖或内存不足。

4.6 观测审计报告 observations:audit-report

导出观测子系统的 LLM 审计结果（影子模式 off 时输出空集）：

$ npm run observations:audit-report
> node scripts/runObservationsAuditReport.js
Observations audit report
  "status": "shadow",
  "total": 5000,
  "audited": 0,
  "anomalies": 0,
  "falsePositives": 0,
  "missed": 0,
  "precision": null,
  "recall": null,
  "f1": null

total: 5000 是扫描窗口内的观测记录数，audited: 0 对应默认 CB_OBSERVATIONS_LLM_AUDIT_MODE=off（未做 LLM 审计）。

4.7 元数据库备份与恢复（mysqldump）

备份（--single-transaction 不锁表，适合在线库）：

$ mysqldump -uchartbrew -pq1w2e3r4 --single-transaction --routines --triggers chartbrew > /tmp/cb-backup.sql
$ ls -lh /tmp/cb-backup.sql
95K /tmp/cb-backup.sql
$ grep -c "CREATE TABLE" /tmp/cb-backup.sql
63

恢复演练（写入独立库验证，不动生产库）：

$ mysql -uroot -pq1w2e3r4 -e "CREATE DATABASE IF NOT EXISTS cb_restore_test;"
$ mysql -uroot -pq1w2e3r4 cb_restore_test < /tmp/cb-backup.sql
$ mysql -uroot -pq1w2e3r4 -N -e "SELECT COUNT(*) FROM information_schema.tables WHERE table_schema='cb_restore_test'; SELECT email FROM cb_restore_test.User LIMIT 2;"
63
admin@quzuo.net
ops@quzuo.net
$ mysql -uroot -pq1w2e3r4 -e "DROP DATABASE cb_restore_test;"
RESTORE_OK

⚠️ 两个实操坑：① Chartbrew 的表名是单数（User、Team、Chart），手写巡检 SQL 按单数写；② 业务账号 chartbrew 默认没有 information_schema 跨库统计权限，恢复验证类查询要用 root 执行（实测报 ERROR 1142 (42000) at line 1: SELECT command denied to user 'chartbrew'@'%' for table 'TABLES'）。备份文件必须与 .env 里的 CB_ENCRYPTION_KEY 同批保存，缺密钥的库备份无法还原数据源凭证。

4.8 Redis 巡检（redis-cli）

$ redis-cli PING
PONG
$ redis-cli DBSIZE
16
$ redis-cli INFO server | grep -E "redis_version|redis_mode"
redis_version:7.4.12
redis_mode:standalone
$ redis-cli --scan | head -5
bull:chartImageRender:completed
bull:dashboardSnapshot:marker
bull:datasetIntelligence:marker
bull:chartDataUpdate:marker
bull:chartDataUpdate:limiter
$ redis-cli CONFIG GET appendonly
1) "appendonly"
2) "yes"

bull:* 键即 8 条 BullMQ 队列的任务与限流元数据；DBSIZE 持续增长且含 wait/delayed 后缀键时，去队列面板（/apps/queues，凭据见配置篇 5.7）看积压详情。

4.9 PM2 进程托管

安装与版本：

$ npm install -g pm2
added 77 packages in 12s
$ pm2 -v
7.1.1

托管启动（等价 4.1 的手工启动，带守护与日志管理）：

$ cd /opt/chartbrew/server
$ NODE_ENV=production CB_API_PORT=4025 pm2 start index.js --name chartbrew-api
[PM2][WARN] Applications chartbrew-api not running, starting...
[PM2] App [chartbrew-api] launched (1 instances)
┌────┬───────────────────┬─────────────┬─────────┬──────────┬────────┬──────┬───────────┬──────────┬──────────┬──────────┬──────────┐
│ id │ name              │ mode        │ ↺       │ status   │ cpu    │ mem  │ user      │ watching │
│ 0  │ chartbrew-api     │ fork        │ 0       │ online   │ 0%     │ 405… │ root      │ disabled │
└────┴───────────────────┴─────────────┴─────────┴──────────┴────────┴──────┴───────────┴──────────┴──────────┴──────────┴──────────┘

日志、快照与停止：

$ pm2 logs chartbrew-api --lines 5 --nostream
0|chartbre | Socket.IO Redis Pub Client ready
0|chartbre | ✓ Socket.IO Redis adapter enabled for cross-process communication
0|chartbre | Running server on port 4025
0|chartbre | [retention-cleanup] Starting scheduled cleanup

$ pm2 save          # 固化进程表，配合 pm2 startup 做开机自启
$ pm2 restart chartbrew-api / stop / delete chartbrew-api
$ pm2 kill          # 整台 PM2 下线

cluster 多进程示例（主实例约束见 4.1 注意框）：

# /opt/chartbrew/ecosystem.config.js
module.exports = { apps: [{
  name: "chartbrew", cwd: "/opt/chartbrew/server", script: "index.js",
  instances: 2, exec_mode: "cluster",
  env_production: { NODE_ENV: "production", CB_API_PORT: 4019 }
}]}
$ pm2 start ecosystem.config.js -e production

4.10 健康检查（无专用端点）

Chartbrew v6 没有 /api/health（请求返回 Cannot GET /api/health 404，实测）。拨测用两条既有语义：

$ curl -s -o /dev/null -w "%{http_code}\n" http://192.168.1.200:8129/     # 前端
200
$ curl -s -o /dev/null -w "%{http_code}\n" -X POST http://192.168.1.200:4019/user/login \
  -H 'Content-Type: application/json' -d '{"email":"admin@quzuo.net","password":"q1w2e3r4"}'   # API+DB 链路
200

第二条同时验证了 API 进程与元数据库连通性，比匿名端点更接近真实可用性。

五、注意事项

  1. 所有运维脚本（4.2～4.6）读取 /opt/chartbrew/.env 的库/Redis 配置，跨主机执行时记得显式带 CB_DB_HOST、CB_REDIS_HOST；
  2. db:seed* 系列会写入演示数据，生产禁用；db:undo:all 会删表，永远用备份恢复替代；
  3. PM2 与「部署篇」的服务形态二选一：若已用部署篇方式托管，勿再叠加 PM2 起同端口实例；
  4. retention:run 与内置定时器重复执行无害（按 cutoff 幂等删除）；
  5. 备份节奏建议：每日 mysqldump + 每周校验恢复演练 + .env 变更后立即归档密钥。

六、常见问题

6.1 npm run db:migrate 报连接失败

脚本走 .env 的 CB_DB_*：先 mysql -h<CB_DB_HOST> -uchartbrew -p chartbrew -e 'SELECT 1' 验证连通，再检查 CB_DB_DIALECT 与实际库类型是否一致（mysql 配置连 postgres 端口即此症状）。

6.2 队列面板 404 而非 401

访问到了非主实例或该实例 Redis 初始化失败（机理见配置篇 5.7 与 4.1 注意框）。在主实例端口验证：curl -u chartbrew:q1w2e3r4 http://127.0.0.1:4019/apps/queues 应 200。

6.3 邮件快照图片空白/失败

先跑 npm run image:smoke（4.5）定位渲染链路；passed 则问题在 SMTP 配置（配置篇 5.13），failed 则补 Chromium 依赖或加大内存。

6.4 恢复备份后登录 500

大概率密钥与库不配套：.env 的 CB_ENCRYPTION_KEY 与该备份生成时间不一致，数据源凭证解密失败。恢复时 .env 与 SQL 必须同批还原（4.7 注意框）。

七、参考链接

Chartbrew 6.0.0 常用 CLI 命令与运维实操 - Quzuo