Saltcorn 配置详解

本文基于 Saltcorn v1.6.2 在 Ubuntu 22.04.5 LTS 上的实测环境逐项拆解配置体系，所有命令、回显与源码引用均来自实测服务器（2026-10-28）。环境搭建见《Saltcorn 安装部署指南（Ubuntu 22.04）》。

一、配置体系总览

1.1 三级配置模型

Saltcorn v1.6.2 的配置分三级，职责不同、互不混存：

连接层的判定逻辑（@saltcorn/data 包 db/connect.js 源码实读，路径 /usr/lib/node_modules/@saltcorn/cli/node_modules/@saltcorn/data/dist/db/connect.js）：优先级为 调用参数 > 环境变量 > 配置文件 > 默认值，逐键独立生效；当 user + password + database 三键齐备即走 PostgreSQL，若给 sqlite_path 则走 SQLite，三无状态回退到默认路径的 SQLite 文件库（~/.local/share/saltcorn/saltcorndb.sqlite）。因此配置文件路径写错不会报错，只会悄悄落到 SQLite——排障时应先用 saltcorn info 核对 databaseVendor。

1.2 配置文件体检入口

saltcorn info 是配置体检总入口，实测回显（口令与 jwt_secret 已脱敏）：

saltcornVersion: 1.6.2
configFilePath: /root/.config/.saltcorn
nodeVersion: v20.20.2
cliPath: /usr/lib/node_modules/@saltcorn/cli/src/commands
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
  fixed_configuration: {}
  exposed_configuration: {}

注意三点：configFilePath 直接给出配置文件真实路径；databaseVendor 立即暴露是否误落 SQLite；jwt_secret 在配置文件未给 jwt_secret 时由服务启动随机生成，重启会变——依赖 JWT 的移动端接入场景必须在配置文件显式固定。

二、连接层配置逐项详解

2.1 配置文件字段全表

实测环境 /root/.config/.saltcorn 全文：

{
  "user": "saltcorn",
  "password": "q1w2e3r4",
  "database": "saltcorn",
  "host": "localhost",
  "port": 5432,
  "multi_tenant": false,
  "session_secret": "sc-lab-2026-oct-fixed-secret-42"
}

字段逐项说明（判定依据：connect.js 源码 setKey 调用清单）：

另有三个源码级特殊环境变量：DATABASE_URL（给出即改用连接串，忽略零散字段）、FORCE_SQLITE=true、NO_DB_CONNECTION=true（跳过连库，供诊断用）。

2.2 环境变量方式的两种落地形态

形态一：进程级注入（systemd 单元 Environment= 行），适合全托管。形态二：命令级前缀，适合临时验证，例如用环境变量完整替代配置文件启动一次性实例：

PGUSER=saltcorn PGPASSWORD=q1w2e3r4 PGDATABASE=saltcorn PGHOST=localhost PGPORT=5432 saltcorn info

预期结果：databaseVendor: PostgreSQL 且 configuration 中四要素取自环境变量（优先级高于配置文件，仅当配置文件被移除或键缺省时可观察到差异；本文实测以环境变量前缀方式运行 saltcorn info 正常输出，与配置文件方式结果一致）。

2.3 官方文档补充的环境变量

官方 wiki「OS Environment Variables」页（查询日期 2026-10-28）还记录了 SALTCORN_DEFAULT_SCHEMA（默认 schema）与 SALTCORN_DISABLE_UPGRADE（禁用平台自动升级提示，布尔值），与源码清单一致，可放心用于生产加固。

三、运行层配置（_sc_config 表）

3.1 set-cfg / get-cfg 基本用法

运行层配置不落文件、全部进 PostgreSQL _sc_config 表，读写走一对 CLI：

saltcorn set-cfg base_url 'http://10.89.72.10:8148'
saltcorn get-cfg base_url

实测回显：

"http://10.89.72.10:8148"

（set-cfg 执行后回显设置值；get-cfg 以 JSON 值打印。）两个行为细节实测确认：

1. 值会尝试 JSON 解析：set-cfg log_sql true 存入布尔 true；set-cfg site_name 'Saltcorn 实验室' 因非法 JSON 降级为字符串存入。需要字符串形态的数字或布尔时请显式加引号；
2. 读不存在的键不报错：saltcorn get-cfg not_exist_key 回显 undefined，退出码 0，脚本判断需自行判空。

所有运行层配置落表可直接 SQL 审计：

saltcorn run-sql -s "select key, value from _sc_config"

实测回显（节选）：

│ 11      │ 'home_page_by_role'          │ { v: {} }                         │
│ 12      │ 'menu_items'                 │ { v: [Array] }                    │
│ 14      │ 'next_hourly_event'          │ { v: '2026-10-28T01:36:30.299Z' } │
│ 15      │ 'next_daily_event'          │ { v: '2026-10-28T05:17:30.301Z' } │
│ 17      │ 'site_name'                  │ { v: 'Saltcorn 实验室' }          │

3.2 关键运行键清单（源码实读 + 实测）

3.3 log_sql 调试开关：改值-验证-还原实测

saltcorn set-cfg log_sql true

此后任意 CLI 命令都会回显其执行的 SQL。实测 saltcorn get-cfg log_sql 顺带回显了底层查询：

SELECT * FROM "public"."_sc_plugins"   []
SELECT * FROM "public"."users"   []
SELECT * FROM "public"."_sc_roles"  order by "id" []
SELECT * FROM "public"."_sc_tables"  order by lower("name") []
...
SELECT * FROM "public"."_sc_config"   []
true

最后一行 true 即 get-cfg 本身的输出。验证完毕还原：

saltcorn set-cfg log_sql false
saltcorn get-cfg log_sql

实测回显：

false

注意：log_sql 对 Web 端同样生效（会写服务日志），排障结束务必还原 false，否则日志膨胀且可能泄露业务数据。

四、会话与安全配置要点

结合安装篇 5.2 排障实录，安全相关配置有三条硬经验：

1. session_secret 必须显式固定：多 worker 部署下不固定会签名漂移，表现为所有登录 POST 报 invalid csrf token（日志定位），修复即配置文件加一行并重启。
2. 登录自带两级限流：同 IP 100 次/小时、同账号 5 次/5 分钟（auth 路由源码常量），触发后直接重定向回登录页并在日志输出 Failed login attempt for: <email> from <ip>。压测或脚本批量登录前要规划节流，避免误伤真实用户。
3. CSRF 全局启用：所有 POST 默认校验 _csrf，跨脚本调用 Web API 时需先 GET 登录页取 token 并全程携带会话 Cookie；确实无头对接的少量路由可用 disable_csrf_routes 精确豁免，不建议全关。

五、文件存储与目录结构

file_store 默认 /root/.local/share/saltcorn（saltcorn info 的 file_store 字段确认）。实测目录结构：

find /root/.local/share/saltcorn -maxdepth 2

/root/.local/share/saltcorn
/root/.local/share/saltcorn/public

public/ 存放公开访问的上传文件（未配置外部对象存储时站点文件都在此处）。三件与目录相关的运维事实：

• 备份文件不落 file_store：saltcorn backup -o 的输出路径由参数指定（运维篇实测输出到 /tmp）；
• 改 file_store 需迁移旧文件：键值只影响新文件写入，历史文件需手工 rsync 到新路径；
• SQLite 模式的库文件也在该目录：saltcorndb.sqlite 与上传文件同层，备份策略需同时覆盖。

六、多租户与多节点

连接层两个开关对应两种扩展形态：

• multi_tenant: true：单实例承载多租户，每租户独立 schema 与独立运行层配置；配套 CLI saltcorn create-tenant <name> 建租户、list-tenants/rm-tenant/delete-tenants（清理不活跃租户）管理，set-cfg/get-cfg 的 -t <租户名> 参数可将运行层配置按租户隔离设置。
• multi_node: true：多节点共享一个 PostgreSQL 的横向扩展模式，节点间靠数据库同步状态，生产配合 SALTCORN_FIXED_CONFIGURATION（各节点强制一致的关键配置 JSON）使用，避免节点漂移。

本文实测环境为单应用 multi_tenant: false；切换多租户属于结构性变更，建议先备份再改，租户管理命令的实操见《Saltcorn 常用命令与运维详解》。

七、生产配置模板

综合以上实测，给出可直接套用的最小生产模板（口令与密钥请替换为强随机值）：

{
  "user": "saltcorn",
  "password": "<强口令>",
  "database": "saltcorn",
  "host": "localhost",
  "port": 5432,
  "multi_tenant": false,
  "session_secret": "<openssl rand -hex 32 生成>",
  "jwt_secret": "<openssl rand -hex 32 生成，仅接入移动端时需要>",
  "file_store": "/srv/saltcorn/files",
  "default_schema": "public"
}

配套运行层基线：set-cfg base_url 'https://<对外域名>'、set-cfg site_name '<站点名>'，并保持 log_sql=false。改完 systemctl restart saltcorn 后用 saltcorn info 复核 databaseVendor、file_store、configuration 三处即可上线。

八、同系列导航

• 认知选型：《Saltcorn v1.6.2 介绍与选型指南》
• 安装落地：《Saltcorn 安装部署指南（Ubuntu 22.04）》
• 日常运维：《Saltcorn 常用命令与运维详解》