Saltcorn 常用命令与运维详解

本文基于 Saltcorn v1.6.2 在 Ubuntu 22.04.5 LTS 实测环境（2026-10-28）整理 CLI 命令全景与日常运维实操，除明确标注「预期结果」外全部命令与回显均为实测。环境搭建与配置基础分别见《Saltcorn 安装部署指南（Ubuntu 22.04）》与《Saltcorn 配置详解》。

一、CLI 全景

1.1 命令清单与职责分组

saltcorn --help 共暴露 40 余个子命令，按运维职责分七组（括号内为实测环境验证状态）：

1.2 使用前必知的三条约定

1. 多数命令要求连接数据库：缺连接配置时报连接错误而非用法错误，先跑 saltcorn info 确认 databaseVendor；
2. 位置参数敏感：run-sql 不接受裸位置参数，实测 saltcorn run-sql 'select ...' 直接报 Error: Unexpected argument: select ...，必须用 -s 传参；
3. 交互命令有确认门槛：add-schema 不带 -f 会弹 Continue? (y/N) 确认，非交互场景（脚本、SSH 管道）必须加 -f，否则以 ExitPromptError: User force closed the prompt 退出（实测踩坑）。

二、信息与诊断命令

2.1 info / paths：一键体检

saltcorn info

输出版本、配置文件路径、数据库厂商与版本、worker 数、完整连接配置（详见配置篇 1.2，口令与 jwt_secret 记得脱敏外发）。saltcorn paths 与 info 内容一致，用于快速确认 file_store（实测 /root/.local/share/saltcorn）与 configFilePath。

2.2 inspect：实体 JSON 结构化输出

inspect 支持 view|page|trigger|table 四类实体；省略实体名则列出全部名字。实测列出数据表：

saltcorn inspect table

users

查看 users 表完整定义（节选）：

saltcorn inspect table users

{
  "name": "users",
  "id": 1,
  "min_role_read": 1,
  "min_role_write": 1,
  "ownership_field_id": null,
  "versioned": false,
  "external": false,
  "fields": [ ... ]
}

该 JSON 可直接作为应用结构迁移、代码评审与巡检基线比对的数据源。

2.3 清单类命令

saltcorn list-users      # 实测输出 admin@example.com（表格）
saltcorn list-triggers   # 实测输出空表格（未配置触发器）
saltcorn plugins         # 实测输出两行：@saltcorn/base-plugin、@saltcorn/sbadmin2

plugins 列出当前实例已安装插件，全新安装即自带 base-plugin 与 sbadmin2 主题两个内置件，后续用 install-plugin 追加。

2.4 run-sql / run-js：双刃剑

run-sql 用 -s 传 SQL（或 -f 传 SQL 文件），输出为格式化表格。实测：

saltcorn run-sql -s 'select id, email, role_id from users'

current tenant: public
select id, email, role_id from users
┌─────────┬────┬─────────────────────┬─────────┐
│ (index) │ id │ email               │ role_id │
├─────────┼────┼─────────────────────┼─────────┤
│ 0       │ 1  │ 'admin@example.com' │ 1       │
└─────────┴────┴─────────────────────┴─────────┘

表名不带 schema 前缀（默认 default_schema=public）；实测写 sc.users 报 error: relation "sc.users" does not exist（错误码 42P01），排查表名问题时先确认 default_schema。

run-js 用 -c 传 JS 代码（或 -f 传脚本文件），运行在受控上下文里，可访问 Saltcorn 数据模型但不能 require 外部模块（实测 require 报 ReferenceError: require is not defined）。实测：

saltcorn run-js -c 'console.log("sc-ok:"+(6*7))'

sc-ok:42

注意：用 return 6*7 形式实测不回显返回值（退出码 0、无输出），脚本里要拿输出请用 console.log。

2.5 configuration-check 与 take-snapshot

saltcorn configuration-check          # 巡检配置一致性（预期结果：逐键输出检查项，异常键会标出）
saltcorn take-snapshot                # 实测输出 null：全新实例无快照；有快照时打印当前快照 JSON 到 stdout

建议纳入变更前巡检流程：改配置前跑一次 configuration-check 留底。

三、数据备份与恢复

3.1 backup：pg_dump 定制格式

saltcorn backup -o /tmp/sc_backup_test.sql
ls -la /tmp/sc_backup_test.sql

实测回显：

/tmp/sc_backup_test.sql
-rw-r--r- - 1 root root 83720 Oct 28 01:26 /tmp/sc_backup_test.sql

备份文件头确认是 pg_dump 定制格式（PGDMP），内含 CREATE DATABASE saltcorn ... 与逐表结构（CREATE TABLE public._sc_api_tokens (...) 等），即整库级备份。两种形态：

• saltcorn backup -o <file>：无参默认 pg_dump 整库（本文实测形态），恢复依赖 psql；
• saltcorn backup -z / -a / -t <租户>：Saltcorn 自有 zip 格式，包含文件存储与快照语义，-a 覆盖全部租户。

注意：pg_dump 形态只备数据库，上传文件目录（file_store）不随备份走，文件需另行归档（见配置篇第五节）。

3.2 restore：恢复流程

saltcorn restore /tmp/sc_backup_test.sql

命令签名 restore FILE [-t <租户>]，接受 zip 或 sqlc 格式（本文实测环境未执行整库恢复演练，以上为命令与预期结果：恢复备份中包含的数据库结构与数据，完成后建议立即 systemctl restart saltcorn 并用 saltcorn list-users 验证账号数据回归）。

3.3 备份策略建议

结合实测行为给出三条可落地策略：

1. 每日 pg_dump + 每周 zip 双轨：pg_dump 保结构数据快速恢复，zip（backup -z -a）保文件存储；
2. 升级前强制备份：saltcorn backup -o /root/pre-upgrade-$(date +%F).sql 写进升级 runbook；
3. 恢复演练纳入季度任务：restore 到临时库验证可用性，避免"备份从未被验证"的经典事故。

四、服务生命周期与 systemd 运维

4.1 启停与探活实测

systemctl stop saltcorn
curl -s -o /dev/null -w 'HTTP %{http_code}\n' --max-time 3 http://localhost:8148/
systemctl start saltcorn
sleep 10
curl -s -o /dev/null -w 'HTTP %{http_code}\n' http://localhost:8148/auth/login

实测回显：

stopped: HTTP 000
restarted: HTTP 200

HTTP 000（连接拒绝）→ 200 的探活对可作监控探针；注意启动到就绪约需 3~10 秒（6 worker 依次输出 listening），探针超时阈值建议 ≥15 秒。日常重启统一用 systemctl restart saltcorn（实测连接层配置变更后重启生效）。

4.2 日志观测

journalctl -u saltcorn --no-pager -n 50
journalctl -u saltcorn --no-pager --since '10 minutes ago' | grep -iE 'error|failed|invalid'

实测经验两条：启动成功标志是每个 worker 一行 Saltcorn listening on http://localhost:8148/；invalid csrf token（登录/表单提交失败）与 Failed login attempt for: ...（登录限流触发）是最高频的两类安全日志，巡检脚本应关注。

4.3 自愈与自启

安装篇交付的单元已含三重保障，实测行为：systemctl enable --now 输出 Created symlink ...（开机自启）；Restart=on-failure + RestartSec=5 在进程异常退出 5 秒后拉起；After=postgresql.service 保证数据库先就绪。验证自愈可执行 pkill -f 'saltcorn serve' 后 5~10 秒内复查 systemctl is-active saltcorn（预期结果：active）。

五、调度与自动化

5.1 scheduler 与内置调度器

saltcorn serve 默认内嵌调度器（serve -s 可关闭）。调度窗口存于 _sc_config（实测键 next_hourly_event / next_daily_event / next_weekly_event，如 2026-10-28T01:36:30.299Z），时间锚点用 set-daily-time 调整（帮助说明：设置默认每日事件的运行时刻，按当前时间偏移分钟数，需重启生效）。独立进程形态 saltcorn scheduler 供多节点部署把调度职责从 Web 进程剥离。

5.2 run-trigger：手动触发器

saltcorn run-trigger <触发器名>    # 立即执行指定触发器（预期结果：输出执行成功与动作日志）
saltcorn list-triggers            # 先列出可触发对象（实测全新实例为空表）

数据自动化排障时，先用 list-triggers 确认注册状态，再 run-trigger 手动重放，配合 log_sql 观察动作 SQL（配置篇 3.3）。

六、版本升级与锁线

升级三步（命令与预期结果，跨版本升级请先演练）：

saltcorn backup -o /root/pre-upgrade.sql     # 第 0 步：备份
npm install -g @saltcorn/cli@latest          # 预期：changed N packages in Ns
saltcorn migrate                             # 预期：Successfully ran the 'migrate' command
systemctl restart saltcorn                   # 预期：journal 重新输出 N 行 listening

需要锁稳定线时按 npm dist-tag 安装（v1.6.2 为 latest；历史稳定线 stable-1.5.x=1.5.10、stable-1.4.x=1.4.8；预发布线 next=1.7.0-beta.3，查询日期 2026-10-28）。生产禁用 @next/beta 线，升级窗口内用 saltcorn info 核对 saltcornVersion 与 migrate 后的版本号一致。

七、同系列导航

• 认知选型：《Saltcorn v1.6.2 介绍与选型指南》
• 安装落地：《Saltcorn 安装部署指南（Ubuntu 22.04）》
• 参数调优：《Saltcorn 配置详解》