Saltcorn 安装部署指南（Ubuntu 22.04）

Ubuntu 22.04.5 LTS 从零安装 Saltcorn v1.6.2：PostgreSQL 14 + Node.js 20 + npm 全局安装 + systemd 托管全流程实测回显，含弱口令被拒与多 worker session_secret 两大排障实录，附升级与卸载。

SaltcornSaltcornNode.jsPostgreSQLUbuntu 22.04低代码2026/10/28

Saltcorn 安装部署指南（Ubuntu 22.04）

本文在 Ubuntu 22.04.5 LTS 服务器上从零实装 Saltcorn v1.6.2（npm 官方安装线），全部命令与回显均来自实测环境，日期 2026-10-28。安装前建议先阅读同系列《Saltcorn v1.6.2 介绍与选型指南》确认版本与选型结论。

一、安装前准备

1.1 环境与版本基线

实测服务器软件基线如下（安装后 saltcorn info 回显确认）：

组件实测版本说明
操作系统Ubuntu 22.04.5 LTScat /etc/os-release 确认
PostgreSQL14.24 (Ubuntu 14.24-0ubuntu0.22.04.1)Ubuntu 22.04 官方仓库自带
Node.jsv20.20.2NodeSource setup_20.x 线
npm10.8.2随 Node.js 20 附带
Saltcorn@saltcorn/cli/1.6.2 linux-x64npm latest 稳定版

版本溯源说明：v1.6.2 为 2026-10-28 查询时 npm latest 与 GitHub 稳定标签双重认定的最新稳定版（预发布线已推进到 v1.6.3-beta.5 与 v1.7.0-beta.3）。Saltcorn 官方对 Node.js 的基线要求为 v18 及以上（GitHub README 安装章节），本文选用更保守的 Node.js 20 LTS 线。

资源画像：空库冷启动后 systemctl status saltcorn 显示主服务内存约 999 MB（含 6 个 worker 进程），进程数为 1 主 + 6 worker（Saltcorn 默认并发 worker 数 defaultNWorkers=6，与 CPU 核数相关）。生产建议至少准备 2 核 / 4 GB 内存，并预留文件存储空间。

1.2 安装路径决策

Saltcorn 有两条官方安装路径：npm 全局安装（npm install -g @saltcorn/cli）与 GitHub 源码安装。本文选 npm 安装线，理由：

  1. npm 是官方发行主通道，@saltcorn/cli 将 monorepo 内全部运行时组件（data/server/builder 等）作为依赖一次拉齐；
  2. 版本可钉住（@saltcorn/cli@1.6.2），升级/回滚路径清晰；
  3. 无需手工处理源码构建链。

二、安装基础依赖

2.1 安装 PostgreSQL 14

Ubuntu 22.04 官方仓库的 PostgreSQL 版本为 14.x，满足 Saltcorn 要求，直接安装：

apt-get update
DEBIAN_FRONTEND=noninteractive apt-get install -y postgresql postgresql-contrib build-essential python3 curl git

实测回显（尾部）：

Running hooks in /etc/ca-certificates/update.d...
done.

安装完成即由 systemd 接管，启动并确认状态：

systemctl start postgresql
systemctl is-active postgresql

实测回显：

active

2.2 安装 Node.js 20 LTS

Ubuntu 22.04 自带 apt 源中的 nodejs 为 12.x，过旧，改用 NodeSource 脚本接入 20.x 线：

curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt-get install -y nodejs
node -v
npm -v

实测回显（节选）：

2026-10-28 01:12:28 - To install N|solid Runtime, run: apt install nsolid -y
Setting up nodejs (20.20.2-1nodesource1) ...
v20.20.2
10.8.2

三、安装 Saltcorn 与初始化

3.1 确认发行版本并全局安装

先向 npm 查询当前 latest，确认与预期稳定版一致后再钉版本安装：

npm view @saltcorn/cli version

实测回显：

1.6.2

执行全局安装：

npm install -g @saltcorn/cli@1.6.2

实测回显（尾部）：

changed 1496 packages in 37s

213 packages are looking for funding
  run `npm fund` for details

验证 CLI 可用与安装路径：

saltcorn --version
which saltcorn

实测回显：

@saltcorn/cli/1.6.2 linux-x64 node-v20.20.2
/usr/bin/saltcorn

3.2 创建数据库角色与 Saltcorn 配置文件

Saltcorn 连接 PostgreSQL 需要角色 + 数据库 + 连接配置文件三件套。先在 psql 中创建（口令在真实环境请使用强随机值，本文为实验环境演示值）：

runuser -u postgres -- psql -c "CREATE ROLE saltcorn LOGIN PASSWORD 'q1w2e3r4' CREATEDB;"
runuser -u postgres -- psql -c 'CREATE DATABASE saltcorn OWNER saltcorn;'

实测回显：

CREATE ROLE
CREATE DATABASE

写入连接配置文件。Saltcorn v1.6.2 的连接层配置文件路径为 /root/.config/.saltcorn（~/.config/.saltcorn，可用 saltcorn info 的 configFilePath 字段验证）：

mkdir -p /root/.config
cat > /root/.config/.saltcorn <<'EOF'
{
  "user": "saltcorn",
  "password": "q1w2e3r4",
  "database": "saltcorn",
  "host": "localhost",
  "port": 5432,
  "multi_tenant": false,
  "session_secret": "sc-lab-2026-oct-fixed-secret-42"
}
EOF

字段说明：

字段作用
user / password / database / host / portPostgreSQL 连接四要素，与 3.2 建库建角色一致
multi_tenant是否开启多租户模式，单应用部署固定 false
session_secret会话签名密钥，必须显式固定，原因见 5.2 排障实录——不设置时多 worker 进程各自随机生成，登录会话将随机失效

配置优先级（从高到低）：命令行/调用参数 > 环境变量（PGUSER/PGHOST/PGPORT/PGPASSWORD/PGDATABASE 及 SALTCORN_* 系列）> 配置文件 > 内置默认值。因此生产环境也可完全用环境变量替代配置文件。

3.3 初始化数据库 schema

Saltcorn 首次使用需向目标库写入自身 schema（表、迁移记录、配置表）。v1.6.2 的 saltcorn setup 为交互式向导，自动化场景直接用非交互的 add-schema 并加 -f 跳过确认：

saltcorn add-schema -f

实测回显：

Successfully ran the 'add-schema' command

3.4 创建管理员账号

saltcorn create-user -e admin@example.com -p 'Q1w2E3r4!sc' -a

实测回显：

Success: User admin@example.com created successfully

注意：Saltcorn 内置弱口令策略，常见弱口令会被直接拒绝（实测 q1w2e3r4 被拒，详见 5.1）。创建后用 list-users 验证：

saltcorn list-users

实测回显：

┌─────────┬─────────────────────┐
│ (index) │ email               │
├─────────┼─────────────────────┤
│ 0       │ 'admin@example.com' │
└─────────┴─────────────────────┘

四、systemd 服务托管

4.1 编写服务单元

创建 /etc/systemd/system/saltcorn.service：

[Unit]
Description=Saltcorn low-code application server
After=network.target postgresql.service

[Service]
Type=simple
User=root
WorkingDirectory=/root
Environment=HOME=/root
ExecStart=/usr/bin/saltcorn serve -p 8148
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

要点：After 引入 postgresql.service 保证数据库先起；serve -p 8148 指定监听端口（默认 3000）；HOME 必须显式设置，Saltcorn 依赖 $HOME 定位 ~/.config/.saltcorn 配置文件；Restart=on-failure 提供进程崩溃自动拉起。

启用并启动：

systemctl daemon-reload
systemctl enable --now saltcorn

实测回显：

Created symlink /etc/systemd/system/multi-user.target.wants/saltcorn.service → /etc/systemd/system/saltcorn.service.

4.2 启动验证

服务状态：

systemctl status saltcorn --no-pager -l

实测回显（节选）：

● saltcorn.service - Saltcorn low-code application server
     Loaded: loaded (/etc/systemd/system/saltcorn.service; enabled; vendor preset: enabled)
     Active: active (running) since Wed 2026-10-28 01:17:27 UTC; 16s ago
   Main PID: 7371 (node)
      Tasks: 77 (limit: 2932)
     Memory: 999.2M
        CPU: 8.767s
             ├─7371 node /usr/bin/saltcorn serve -p 8148
             ├─7396 /usr/bin/node /usr/bin/saltcorn serve -p 8148
             ├─7397 /usr/bin/node /usr/bin/saltcorn serve -p 8148
             ...

启动日志：

journalctl -u saltcorn --no-pager -n 8

实测回显：

Oct 28 01:17:27 saltcorn-lab systemd[1]: Started Saltcorn low-code application server.
Oct 28 01:17:30 saltcorn-lab saltcorn[7398]: Saltcorn listening on http://localhost:8148/
Oct 28 01:17:30 saltcorn-lab saltcorn[7397]: Saltcorn listening on http://localhost:8148/
Oct 28 01:17:30 saltcorn-lab saltcorn[7396]: Saltcorn listening on http://localhost:8148/
...

6 个 worker 各自输出一行 listening 即多 worker 就绪。HTTP 探活：

curl -s -o /dev/null -w 'HTTP %{http_code}\n' http://localhost:8148/
curl -s -o /dev/null -w 'HTTP %{http_code}\n' http://localhost:8148/auth/login

实测回显：

HTTP 302
Found. Redirecting to /auth/login
HTTP 200

根路径 302 跳转登录页、登录页 200，即部署成功。最后用 saltcorn info 做安装体检（口令与 jwt_secret 字段已脱敏）：

saltcornVersion: 1.6.2
configFilePath: /root/.config/.saltcorn
nodeVersion: v20.20.2
databaseVendor: PostgreSQL
defaultNWorkers: 6
databaseVersion: >-
  PostgreSQL 14.24 (Ubuntu 14.24-0ubuntu0.22.04.1) on x86_64-pc-linux-gnu, ...
configuration:
  sc_version: 1.6.2
  user: saltcorn
  host: localhost
  port: 5432
  password: ****（脱敏）
  database: saltcorn
  jwt_secret: ****（脱敏）
  multi_tenant: false
  multi_node: false
  file_store: /root/.local/share/saltcorn
  default_schema: public

Web 登录验证（浏览器访问 http://<服务器IP>:8148，以 admin@example.com / Q1w2E3r4!sc 登录出现欢迎页即全链路打通）。

五、排障实录

5.1 管理员弱口令被 Saltcorn 拒绝

现象：按习惯用 q1w2e3r4 创建管理员：

saltcorn create-user -e admin@example.com -p q1w2e3r4 -a

实测报错：

Error: Password not accepted: Password too common

定位：Saltcorn 服务端内置口令强度校验，命中常见弱口令字典直接拒绝，CLI 与 Web 注册同样生效。这是平台级行为而非环境故障。

解决：改用带大小写与符号的口令后成功（Q1w2E3r4!sc）。数据库侧角色口令（PostgreSQL 自身不启用该字典）仍可用 q1w2e3r4，但生产环境建议统一强口令。

5.2 未固定 session_secret 导致 Web 登录全部失败（invalid csrf token）

现象：安装与 CLI 全部正常，但浏览器登录任意正确账号都回到登录页，无任何错误提示。服务端日志刷屏：

Oct 28 01:19:57 saltcorn-lab saltcorn[7415]: invalid csrf token
Oct 28 01:20:18 saltcorn-lab saltcorn[7399]: invalid csrf token
Oct 28 01:20:32 saltcorn-lab saltcorn[7416]: invalid csrf token

定位过程：

  1. 先排除凭据问题：用 bcryptjs.compare 对比数据库 users.password 哈希与已知口令，password match: true，凭据无误；
  2. 观察日志 PID：GET 请求落在 7396/7397/7398 等不同 worker，POST 也随机落点，而 invalid csrf token 分布在不同 PID 上；
  3. systemctl status 显示主进程 1 + worker 6（defaultNWorkers=6）；saltcorn info 中 configuration 无 session_secret 字段——未设置时每个 worker 进程启动时各自随机生成会话签名密钥；
  4. 结论：express-session 会话 Cookie 由 worker A 的密钥签发，POST 命中 worker B 时签名校验失败被当作全新会话，其中的 CSRF 密钥随之丢失，于是所有 POST（包括登录）一律 invalid csrf token。

解决：在 /root/.config/.saltcorn 中显式固定 session_secret（任意足够长的随机串），systemctl restart saltcorn 后登录即恢复正常（登录后返回欢迎页，日志不再出现 invalid csrf token）。

经验：这一坑只在多 worker + 未固定 session_secret同时出现时触发，单 worker 环境难以复现，属于 Saltcorn 部署的高频隐形坑。所有多进程部署（无论 systemd 还是其他进程管理器）都必须显式固定该密钥。

六、升级与卸载

6.1 升级到新版本

npm 线升级为「换包 + 迁移 + 重启」三步（以下为命令与预期结果，本文未实测跨版本升级）：

npm install -g @saltcorn/cli@latest   # 预期：changed N packages 输出
saltcorn migrate                      # 预期：Successfully ran the 'migrate' command
systemctl restart saltcorn            # 预期：服务重启，journal 重新输出 listening

升级前务必先备份：saltcorn backup -o /root/pre-upgrade.sql（pg_dump 格式，见《Saltcorn 常用命令与运维详解》）。若需锁旧稳定线，可安装对应 dist-tag（如 stable-1.5.x 线的 @saltcorn/cli@1.5.10）。

6.2 卸载

systemctl disable --now saltcorn   # 停止并取消开机自启（预期：Removed 输出）
rm -f /etc/systemd/system/saltcorn.service && systemctl daemon-reload
npm uninstall -g @saltcorn/cli     # 移除 CLI（预期：removed 1 package in Ns）
runuser -u postgres -- psql -c 'DROP DATABASE IF EXISTS saltcorn;'
runuser -u postgres -- psql -c 'DROP ROLE IF EXISTS saltcorn;'
rm -rf /root/.config/.saltcorn /root/.local/share/saltcorn   # 清理配置、文件存储

文件存储目录 /root/.local/share/saltcorn 内含用户上传文件，确认不再保留后再删。

七、同系列导航