Frappe Helpdesk 1.31 配置参数详解

目标：逐键讲清 Frappe Helpdesk 站点的两个 JSON 配置文件——bench 级 common_site_config.json 与站点级 site_config.json——的查看方式、修改命令、生效机制与生产建议值。文中文件内容、命令回显均为 2026-10-23 在 Ubuntu 22.04.5（bench 5.31.0 / Frappe 15.124.0 / Helpdesk 1.31.0）环境实测的原始输出。部署路径见本专栏《Frappe Helpdesk 1.31 Ubuntu 22.04 安装指南（bench 手工部署）》，产品定位见[《Frappe Helpdesk 1.31 介绍与选型指南》](https://www.quzuo.net/document/xtxb3uZrBRAB)。

一、配置分层与文件位置

Frappe 站点的配置是「两级 JSON」模型，全部位于 bench 的 sites/ 目录：

文件	作用域	本文实测路径
`common_site_config.json`	bench 级公共配置，全部站点共享（数据库/Redis 地址、进程端口等）	`/home/frappe/frappe-bench/sites/common_site_config.json`
`sites/<站点名>/site_config.json`	站点级私有配置，按站点隔离	`/home/frappe/frappe-bench/sites/hd.local/site_config.json`

查找优先级：站点配置覆盖公共配置同名键。Helpdesk 本身没有独立配置文件，其可定制项（SLA、分派规则、邮件账号、知识库）都在数据库 DocType 中通过 Web 界面配置；JSON 配置全部属于 Frappe 框架层，对同站点的其他 App 同样生效。

二、查看与修改方式

2.1 直接查看文件

cat /home/frappe/frappe-bench/sites/hd.local/site_config.json

实测回显（新建站点后的原始内容，数据库账号由 bench new-site 自动生成）：

{
 "db_name": "_5d00a979683836f3",
 "db_password": "YfYIbrhfDD3QT29J",
 "db_type": "mariadb"
}

cat /home/frappe/frappe-bench/sites/common_site_config.json

实测回显（bench init 生成、bench setup supervisor 后的状态）：

{
 "background_workers": 1,
 "file_watcher_port": 6787,
 "frappe_user": "frappe",
 "gunicorn_workers": 25,
 "live_reload": true,
 "rebase_on_pull": false,
 "redis_cache": "redis://127.0.0.1:13000",
 "redis_queue": "redis://127.0.0.1:11000",
 "redis_socketio": "redis://127.0.0.1:13000",
 "restart_supervisor_on_update": true,
 "restart_systemd_on_update": false,
 "serve_default_site": true,
 "shallow_clone": true,
 "socketio_port": 9000,
 "use_redis_auth": false,
 "webserver_port": 8000
}

2.2 合并视图：bench show-config

两条配置合并后的生效视图（实测，表格为 bench 原生输出）：

bench --site hd.local show-config

+------------------------------+-------------------------+
| Config                       | Value                   |
+------------------------------+-------------------------+
| background_workers           | 1                       |
| file_watcher_port            | 6787                    |
| frappe_user                  | frappe                  |
| gunicorn_workers             | 25                      |
| live_reload                  | True                    |
| rebase_on_pull               | False                   |
| redis_cache                  | redis://127.0.0.1:13000 |
| redis_queue                  | redis://127.0.0.1:11000 |
| redis_socketio               | redis://127.0.0.1:13000 |
| restart_supervisor_on_update | True                    |
| restart_systemd_on_update    | False                   |
| serve_default_site           | True                    |
| shallow_clone                | True                    |
| socketio_port                | 9000                    |
| use_redis_auth               | False                   |
| webserver_port               | 8000                    |
| db_name                      | _5d00a979683836f3       |
| db_password                  | YfYIbrhfDD3QT29J        |
| db_type                      | mariadb                 |
| maintenance_mode             | 0                       |
| db_socket                    | None                    |
| db_host                      | 127.0.0.1               |
+------------------------------+-------------------------+

2.3 修改命令：bench set-config

bench set-config --help

实测回显：

Usage: bench  set-config [OPTIONS] KEY VALUE

  Insert/Update a value in site_config.json

Options:
  -g, --global  Set value in bench config
  -p, --parse   Evaluate as Python Object
  --help        Show this message and exit.

三条规则（均为实测）：

不带 -g：写入当前站点（需 bench --site <站点名> 前缀），落 sites/<站点名>/site_config.json；
带 -g：写入 bench 级 common_site_config.json，全部站点生效；
带 -p：把 VALUE 当 Python 字面量求值后写入（可写入数组/布尔/数字，非纯字符串）。

站点级往返实测（maintenance_mode 1 → 0）：

bench --site hd.local set-config maintenance_mode 1
grep maintenance sites/hd.local/site_config.json
#  "maintenance_mode": 1
bench --site hd.local set-config maintenance_mode 0
grep maintenance sites/hd.local/site_config.json
#  "maintenance_mode": 0

developer_mode 往返实测：

bench --site hd.local set-config developer_mode 1
grep developer sites/hd.local/site_config.json
#  "developer_mode": 1
bench --site hd.local set-config developer_mode 0
grep developer sites/hd.local/site_config.json
#  "developer_mode": 0

公共级 -g 实测（写入 common_site_config.json）：

bench set-config -g demo_key 1
grep demo sites/common_site_config.json
#  "demo_key": 1,
bench set-config -g demo_key 0

-p 解析数组实测：

bench --site hd.local set-config -p demo_ports "[8000, 8080]"
grep -A2 demo_ports sites/hd.local/site_config.json
#  "demo_ports": [
#   8000,
#   8080
#  ],

2.4 生效机制

改动的键	是否需要重启
`maintenance_mode`、`developer_mode` 等站点业务键	否，请求即时读取
`redis_cache` / `redis_queue` / `db_host` 等连接键	需要，web/worker 进程在启动时建立连接
`gunicorn_workers`、`webserver_port`、`socketio_port` 等进程键	需要，且 supervisor 下要 `supervisorctl restart <组>`

生产托管状态下的标准重启方式：

sudo supervisorctl restart frappe-bench-web:frappe-bench-frappe-web
sudo supervisorctl restart frappe-bench-workers:      # 冒号结尾=整组

三、site_config.json 参数详解（站点级）

3.1 数据库键（new-site 自动生成，勿手工改）

键	实测值	说明
`db_name`	`_5d00a979683836f3`	数据库名，bench 自动生成（下划线 + 站点哈希），避免多站点同名冲突
`db_password`	`YfYIbrhfDD3QT29J`	随机 16 位密码，建站时同步创建同名数据库用户
`db_type`	`mariadb`	数据库类型；Frappe 主线支持 `mariadb` 与 `postgres`
`db_host`	`127.0.0.1`	数据库地址（show-config 实查默认值）；远程数据库时改为对端 IP
`db_socket`	`None`	Unix socket 路径；默认走 TCP，填 socket 路径后改走本机 socket

迁移数据库时的标准改法（改 db_host 后重启 web 与 worker）：

bench --site hd.local set-config db_host 192.0.2.10
sudo supervisorctl restart frappe-bench-web: frappe-bench-workers:

3.2 运维开关键

键	实测值	说明
`maintenance_mode`	`0`	1 时站点进入维护模式：登录用户见维护提示页，未登录访问被拒绝；升级/批量导入期间常用
`developer_mode`	`0`	1 时开启开发者模式（允许 DocType 在线修改、暴露调试信息），生产必须为 0

配套的快捷命令（效果等同 set-config，语义更明确）：

bench --site hd.local set-maintenance-mode on
bench --site hd.local set-admin-password 新密码

四、common_site_config.json 参数详解（bench 级）

以下 16 键为实测文件全集，按用途分组：

4.1 进程与端口

键	实测值	说明
`webserver_port`	`8000`	bench serve 开发服务器端口（生产由 gunicorn 接管，监听地址见 supervisor 配置）
`socketio_port`	`9000`	Node.js 实时服务端口
`file_watcher_port`	`6787`	开发热重载的文件监听端口
`gunicorn_workers`	`25`	生产 gunicorn 进程数建议值（`bench setup supervisor` 生成的配置遵循该值）
`background_workers`	`1`	bench start 模式下拉起后台 worker 的开关
`frappe_user`	`frappe`	bench 归属用户，supervisor 配置以它运行进程
`live_reload`	`true`	开发模式前端热更新；生产置 false 减少开销
`serve_default_site`	`true`	Host 头无法匹配站点时是否回落默认站点

4.2 Redis 连接

键	实测值	说明
`redis_cache`	`redis://127.0.0.1:13000`	缓存实例（bench 自带两实例的 cache 口）
`redis_queue`	`redis://127.0.0.1:11000`	任务队列实例
`redis_socketio`	`redis://127.0.0.1:13000`	实时服务用的 Redis（实测与 cache 同实例）
`use_redis_auth`	`false`	Redis 是否启用 ACL 密码认证（生产共享 Redis 时置 true 并配 `create-rq-users`）

拆分实例的典型改法（Redis 与应用不同机时）：

bench set-config -g redis_cache redis://192.0.2.20:6379
bench set-config -g redis_queue redis://192.0.2.21:6379

4.3 升级与运维联动

键	实测值	说明
`restart_supervisor_on_update`	`true`（setup supervisor 自动改写）	`bench update` 后自动 `supervisorctl restart`
`restart_systemd_on_update`	`false`	systemd 托管时的对应联动开关
`rebase_on_pull`	`false`	`bench update` 拉取应用更新时是否 rebase
`shallow_clone`	`true`	应用仓库用浅克隆（省流量，首次 init 明显加速）

五、生产环境配置要点

结合本文实测环境，生产站点建议核对以下键（均为实测可执行命令）：

bench --site hd.local set-config maintenance_mode 0
bench --site hd.local set-config developer_mode 0
bench set-config -g restart_supervisor_on_update true   # setup supervisor 已自动写入
bench set-config -g live_reload false                   # 关闭开发期热更新

远程化依赖三件套（数据库/Redis 独立部署时）：

bench --site hd.local set-config db_host <数据库IP>
bench set-config -g redis_cache redis://<缓存IP>:6379
bench set-config -g redis_queue redis://<队列IP>:6379

改完统一重启并复核：

sudo supervisorctl restart frappe-bench-web: frappe-bench-workers:
bench --site hd.local show-config | head -25

Docker Compose 部署形态下的对应关系：官方编排由一次性 configurator 服务自动写入公共配置（db_host=db、db_port=3306、redis_cache=redis-cache:6379、redis_queue=redis-queue:6379、socketio_port=9000、chromium_path），文件落在 sites 卷中，修改方式同样是 exec backend bench set-config ...，详见《Frappe Helpdesk 1.31 Docker Compose 部署指南》第七章。

六、常见问题

6.1 手工编辑 JSON 后格式破坏导致站点全挂 JSON 不允许尾逗号与注释，手工编辑前先备份；推荐一律走 bench set-config（自动保证合法 JSON）。改坏了的现象是 bench 任何命令直接抛 JSONDecodeError，从备份恢复文件即可。

6.2 set-config 写入后行为未变 先分清层级：站点级用 bench --site <站点> set-config，bench 级要加 -g；再对照 2.4 节生效机制判断是否需要重启进程。show-config 看到的是合并后视图，确认键真的写进去了再用它核对。

6.3 db_password 忘了能否查看 能：cat sites/<站点>/site_config.json 里的 db_password 就是当前数据库账号密码（明文存储是 Frappe 的设计，注意文件权限）。root 数据库密码不在这里，是建库时的 MariaDB root 密码。

6.4 maintenance_mode 1 之后自己也被挡住 维护模式只放行 Administrator 会话；用 bench --site <站点> set-maintenance-mode off 或 set-config 0 恢复，无需重启。

6.5 删除一个配置键 set-config 只做插入/更新，不做删除。需要删除时手工编辑对应 JSON 文件去掉该键（改前备份、改后用 python3 -m json.tool <文件> 校验合法性），连接类键删除后重启进程。

七、参考链接

Frappe Framework 配置文档（bench set-config / site_config 机制）：https://frappeframework.com/docs/user/en/bench/resources/bench-commands-cheatsheet
Helpdesk 官方文档：https://docs.frappe.io/helpdesk
bench 命令全集与实测回显：本专栏《Frappe Helpdesk 1.31 常用 CLI 命令与工具详解》
bench 手工安装与生产托管：本专栏《Frappe Helpdesk 1.31 Ubuntu 22.04 安装指南（bench 手工部署）》
Docker Compose 部署与环境变量：本专栏《Frappe Helpdesk 1.31 Docker Compose 部署指南》
产品定位与选型对比：[《Frappe Helpdesk 1.31 介绍与选型指南》](https://www.quzuo.net/document/xtxb3uZrBRAB)