Frappe HR 16.52.0 配置参数详解

目标：逐项详解 Frappe HR v16.52.0 的四层配置体系——bench 全局配置（common_site_config.json）、站点配置（site_config.json）、HR 业务设置（HR Settings）与薪酬设置（Payroll Settings），覆盖查看命令、修改命令、字段含义与生产推荐值。本文全部命令与回显已在 Ubuntu 22.04 + hrms 16.52.0 + frappe 16.53.0 + bench 5.31.0 环境实测通过，敏感值以 ${VAR} 占位。

一、环境信息

• 操作系统：Ubuntu 22.04 LTS（x86_64）
• 应用版本：hrms 16.52.0 + erpnext 16.52.1 + frappe 16.53.0（bench version 实测）
• bench CLI：5.31.0（配置读写命令行为随 bench 大版本变化，本文以 5.31.0 为准）
• 安装目录：/home/frappe/frappe-bench（bench 标准布局），站点名 hr.example.com
• 配置文件清单（实测位置）：

• 站内安装篇：《Ubuntu 22.04 安装 Frappe HR 16.52.0 指南》；容器编排形态下前两层配置的自动写入机制见《Frappe HR 16.52.0 Docker Compose 部署指南》第七章。

二、前置条件

• bench 已完成安装并至少有一个可用站点（bench --site hr.example.com list-apps 能列出三 App）；
• MariaDB 与 Redis 正常运行（站点级配置校验依赖数据库连接）；
• 执行配置修改的用户为 bench 所属用户（本文为 frappe，root 执行 bench 会被拒绝：WARN: You should not run this command as root）；
• HR Settings/Payroll Settings 修改需以 Administrator 登录 HR Desk 或持有效 REST 会话。

三、参数查看与修改方式

3.1 bench 命令行（bench 层配置）

bench 5.31.0 的配置命令只有 set-config 与 show-config（实测 bench get-config 报 Error: No such command: get-config. (Did you mean one of: 'set-config', 'show-config'?)，老教程里的 get-config 已移除）。

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：写入当前站点 site_config.json（需 --site 指定站点）；
• -g：写入 bench 全局 common_site_config.json；
• -p：把 VALUE 按 Python 字面量解析（整数/布尔/列表必加，否则一律存为字符串）。

写入与查看实测（站点级）：

cd /home/frappe/frappe-bench
bench --site hr.example.com set-config hr_test_key hello
bench --site hr.example.com show-config

实测回显（show-config 输出 common + site 合并后的表格视图，节选）：

+------------------------------+-------------------------------+
| Config                       | Value                         |
+------------------------------+-------------------------------+
| background_workers           | 1                             |
| db_port                      | 3306                          |
| frappe_user                  | frappe                        |
| gunicorn_workers             | 25                            |
| live_reload                  | True                          |
+------------------------------+-------------------------------+

⚠️ 注意两点（实测）：①bench show-config 不带 --site 会报 Error: Please specify --site sitename，全局键也要借某个站点名查看合并结果；②bench 5.31.0 没有 --remove 选项，删除键需直接编辑 JSON 文件或用 python 读改写（本文实测用后者）。

3.2 配置文件直读

cat /home/frappe/frappe-bench/sites/common_site_config.json
cat /home/frappe/frappe-bench/sites/hr.example.com/site_config.json

修改 JSON 文件后需重启 web 进程才生效（dev serve 重启 bench serve；生产 supervisor 环境 bench restart 或 supervisorctl restart frappe-bench-web:*）。

3.3 HR Desk 界面（HR 业务配置）

HR Settings/Payroll Settings 是 Single DocType，入口在 HR Desk：搜索栏输入「HR Settings」/「Payroll Settings」打开设置页，逐项修改后保存即写库，即时生效（无需重启）。

3.4 REST API（HR 业务配置，实测）

以会话 Cookie 认证修改 HR Settings 单字段（B1 站点 serve 8000 实测）：

curl --noproxy "*" -s -c ck.txt -X POST http://127.0.0.1:8000/api/method/login \
  -d "usr=Administrator&pwd=q1w2e3r4"

{"message":"Logged In","home_page":"desk","full_name":"Administrator"}

curl --noproxy "*" -s -b ck.txt -X POST http://127.0.0.1:8000/api/method/frappe.client.set_value \
  -H "Content-Type: application/json" \
  -d '{"doctype":"HR Settings","name":"HR Settings","fieldname":"send_birthday_reminders","value":1}'

实测回显（返回整份 Single DocType，send_birthday_reminders 已变 1，节选）：

{"message":{"name":"HR Settings",...,"send_work_anniversary_reminders":1,
"send_birthday_reminders":1,"send_holiday_reminders":1,"frequency":"Weekly",...}}

回读（get_value 只取指定字段）：

curl --noproxy "*" -s -b ck.txt -X POST http://127.0.0.1:8000/api/method/frappe.client.get_value \
  -H "Content-Type: application/json" \
  -d '{"doctype":"HR Settings","fieldname":"send_birthday_reminders"}'

{"message":{"send_birthday_reminders":1}}

⚠️ 注意：读取 Single DocType 走 frappe.client.get/get_value 时 doctype 传 HR Settings（含空格需 JSON 体内传参）；不要用 /api/resource/HR%20Settings 形式（实测报 ProgrammingError，URL 路径形态对含空格 DocType 不友好）。

四、参数总览

实测全景：common_site_config.json 17 键 + site_config.json 6 键 + HR Settings 43 字段 + Payroll Settings 26 字段。

common_site_config.json（bench 全局，bench init 生成 + bench set-config -g 增改，实测全文）：

{
 "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:6379",
 "redis_queue": "redis://127.0.0.1:6379",
 "redis_socketio": "redis://127.0.0.1:6379",
 "restart_supervisor_on_update": false,
 "restart_systemd_on_update": false,
 "serve_default_site": true,
 "shallow_clone": true,
 "socketio_port": 9000,
 "use_redis_auth": false,
 "webserver_port": 8000
}

site_config.json（站点级，建站自动生成，实测全文，敏感值占位）：

{
 "db_name": "_25875420d890f4a7",
 "db_password": "${DB_PASSWORD}",
 "db_type": "mariadb",
 "db_user": "_25875420d890f4a7",
 "installed_apps": [
  "frappe",
  "erpnext",
  "hrms"
 ]
}

HR Settings 与 Payroll Settings 的字段清单见第五章逐项表。

五、核心参数分类详解

5.1 bench 全局参数（common_site_config.json）

修改示例（实测命令与效果）：

bench set-config -gp db_port 3306        # -p 整数落盘
bench set-config -g maintenance_mode 0   # 字符串/布尔按需

5.2 站点参数（site_config.json）

常用追加键（bench 官方支持，按需写入站点配置）：maintenance_mode（1=维护页）、allow_cors（跨域白名单）、limit_email_accounts 等；encryption_key 首次加密敏感字段时自动生成（如加密工资条邮件密码），丢失将无法解密既有密文，务必随 site_config 一并备份。

5.3 HR Settings 逐项详解（43 字段实测快照）

业务分组与默认值（frappe.client.get 实测，modified 2026-10-23）：

员工与提醒：

休假：

报销：

考勤与排班：

离职与招聘：

5.4 Payroll Settings 逐项详解（26 字段实测快照）

💡 说明：payroll_based_on=Leave 与 consider_unmarked_attendance_as=Present 是新装站点最容易踩坑的组合——「没录入考勤的人默认算出勤拿全薪」。按需改为 consider_unmarked_attendance_as=Absent 并规范考勤录入流程。

六、生产配置模板

以下为 8GB 内存 / 4 核云主机 / 200 员工规模的单机生产推荐（bench setup production frappe 托管形态，实测环境导出，按规模缩放）：

cd /home/frappe/frappe-bench
bench set-config -g live_reload false                 # 关闭开发热重载
bench set-config -g restart_supervisor_on_update true # 升级后自动重启
bench set-config -g serve_default_site false          # 多站点时关闭默认站点
bench set-config -g redis_cache "redis://127.0.0.1:6379"
bench set-config -g redis_queue "redis://127.0.0.1:6379"
bench set-config -g redis_socketio "redis://127.0.0.1:6379"
bench set-config -g maintenance_mode 0

七、常见问题（FAQ）

Q1：bench get-config 报 Error: No such command: get-config？

bench 5.31.0 已移除 get-config，读取用 bench --site <站点> show-config（合并表格）或直接 cat 配置文件。写配置仍用 bench set-config。

Q2：bench set-config -p 与不加 -p 的区别？

不加 -p 一律按字符串落盘（如 db_port 会存成 "3306"）；-p 按 Python 字面量解析（bench set-config -gp db_port 3306 存成整数 3306）。布尔/整数/列表键必加 -p，否则 frappe 读配置时类型不匹配。

Q3：改了 common_site_config.json 不生效？

bench 层配置在进程启动时读入：dev 模式重启 bench serve；生产 supervisor 形态执行 bench restart（或 supervisorctl restart frappe-bench-web:* frappe-bench-workers:*）。HR Settings/Payroll Settings 存数据库，保存即生效无需重启。

Q4：/api/resource/HR%20Settings 读取报 ProgrammingError？

含空格 DocType 走资源路径形态实测会触发数据库错误（frappe 把 URL 编码后的名字直传 SQL 层）。改用方法形态：POST /api/method/frappe.client.get，JSON 体传 {"doctype":"HR Settings"}（实测成功）。

Q5：site_config.json 里的 db_password/encryption_key 能改吗？

db_password 与数据库内 db_user 的密码是配对的：要改必须数据库与配置文件同步改（ALTER USER + bench set-config db_password <新值>）；encryption_key 只在首次加密时生成，之后改了会导致既有密文不可解密——两者都应只备份不重置。

八、参考链接

• frappe 官方站点配置文档：https://docs.frappe.io/framework/user/en/bench/resources/bench-config-yaml（bench 配置项清单）
• frappe 官方 frappe.conf 汇总页：https://docs.frappe.io/framework/user/en/bench/resources/list-of-bench-config-keys
• HR Settings 源码字段定义：https://github.com/frappe/hrms/blob/main/hrms/config/desktop.py 与 hrms/hr/doctype/hr_settings/hr_settings.json
• Payroll Settings 源码字段定义：https://github.com/frappe/hrms/blob/main/hrms/payroll/doctype/payroll_settings/payroll_settings.json
• bench 仓库（CLI 命令源码）：https://github.com/frappe/bench
• 本系列关联文档：《Frappe HR 16.52.0 介绍与选型指南》《Ubuntu 22.04 安装 Frappe HR 16.52.0 指南》《Frappe HR 16.52.0 Docker Compose 部署指南》《Frappe HR 16.52.0 常用 CLI 命令与工具详解》