Frappe HR 16.52.0 常用 CLI 命令与工具详解

目标：详解 Frappe HR v16.52.0 的命令行工具面——Frappe HR 本身不注册独立 CLI，其全部命令行能力由 Frappe 框架随 bench CLI（5.31.0）提供，本文按「应用与版本 → 站点生命周期 → 进程托管 → 备份恢复 → 配置读写 → 开发调试」六大类逐条讲解常用命令的参数与实测回显。本文全部命令与回显已在 Ubuntu 22.04 + hrms 16.52.0 + frappe 16.53.0 + bench 5.31.0 环境实测通过。

一、环境信息

操作系统：Ubuntu 22.04 LTS（x86_64）
bench CLI：5.31.0（bench --version 实测回显：5.31.0）
应用版本：hrms 16.52.0 + erpnext 16.52.1 + frappe 16.53.0（bench version 实测）
bench 目录：/home/frappe/frappe-bench，主站点 hr.example.com
依赖服务：MariaDB 11.8（127.0.0.1:3306）、Redis 8.10.2（127.0.0.1:6379）
选用说明：任务按文档决策树在「bench CLI 命令篇」与「REST API 篇」之间选型——hrms 不注册自有 CLI，命令行运维面即 bench；API 调用基础（login/frappe.client.set_value 等）已在《Frappe HR 16.52.0 配置参数详解》3.4 节实测覆盖，故本文聚焦 bench CLI。

二、工具概览

bench 是 Frappe 体系的应用编排器：一个 bench 目录 = 一个独立运行单元（apps/ 应用代码 + env/ Python 虚拟环境 + sites/ 站点集合 + logs/）。bench --help 实测的命令清单分两层——bench 层（管理 bench 目录与应用，30+ 命令）与 Framework 命令层（针对站点的运维，100+ 命令）。按用途分类：

类别	代表命令	用途
bench 生命周期	init / find / update / retry-upgrade	建目录、升级、失败重试
应用管理	get-app / install-app / uninstall-app / remove-app / list-apps / switch-to-branch	应用从仓库到站点
站点生命周期	new-site / drop-site / use / list-sites / reinstall	建站、删站、默认站点
进程托管	serve / worker / schedule / start / restart / socketio	开发与生产进程
数据库与结构	migrate / rebuild-global-search / trim-database / reload-doc	补丁与结构同步
备份恢复	backup / backup-all-sites / restore / partial-restore	数据安全
配置读写	set-config / show-config / config	bench 与站点配置
开发调试	execute / request / console / jupyter / run-tests / doctor	远程函数、请求、诊断

HR 业务相关的命令没有专用入口——考勤/休假/薪资数据的操作走 HR Desk 或 REST API；bench 的价值在应用、站点与进程三个层面。

三、前置条件

bench 已安装（pip install frappe-bench），且当前用户与 bench 目录属主一致（root 执行会得到 WARN: You should not run this command as root 并可能直接退出）；
命令分两种执行位置：bench 层命令在 frappe-bench 目录内执行；Framework 命令多数需要 --site <站点名>（或在 sites/currentsite.txt 有默认站点）；
MariaDB/Redis 可达（站点命令全程要用）；
bench 的 shell 补全可用 bench completions bash 安装（实测命令清单中的 completions 子命令）。

四、核心命令详解

4.1 版本与清单：version / list-apps / list-sites

bench version

实测回显：

erpnext 16.52.1 HEAD (ade850b)
frappe 16.53.0 HEAD (e8d41dd)
hrms 16.52.0 HEAD (5c72c06)

bench --site hr.example.com list-apps

实测回显：

frappe  16.53.0 HEAD
erpnext 16.52.1 HEAD
hrms    16.52.0 HEAD

bench list-sites

实测回显（输出当前 bench 的 sites 目录清单）：

apps.json
apps.txt
assets
common_site_config.json
hr.example.com

💡 说明：list-sites 实际列出 sites/ 目录内容（含配置文件），站点目录与文件混排；version 与 list-apps 的区别是前者读全部已装包、后者针对指定站点。

4.2 应用管理：get-app / install-app / uninstall-app

get-app（克隆应用进 bench，bench get-app --help 实测参数表）：

Usage: bench  get-app [OPTIONS] [NAME]... GIT_URL

Options:
  --branch TEXT         branch to checkout
  --overwrite
  --skip-assets         Do not build assets
  --soft-link           Create a soft link to git repo instead of clone.
  --init-bench          Initialize Bench if not in one
  --resolve-deps        Resolve dependencies before installing app
  --cache-key TEXT      Caches get-app artifacts if provided (only first 10 chars is used)
  --compress-artifacts  Whether to gzip get-app artifacts that are to be cached

实测（hrms 拉取）：

bench get-app https://github.com/frappe/hrms.git --branch v16.52.0

实测回显（节选）：

Getting hrms
$ git clone https://github.com/frappe/hrms.git --branch v16.52.0 --depth 1 --origin upstream
Cloning into 'hrms'...
Installing hrms
$ uv pip install --quiet -e /home/frappe/frappe-bench/apps/hrms  --python /home/frappe/frappe-bench/env/bin/python
$ bench build --app hrms
✔ Application Assets Linked

install-app（把 bench 内已存在的应用装进站点）：

bench --site hr.example.com install-app hrms

实测回显（erpnext 已装时 hrms 依赖检测的提示）：

App erpnext already installed

Installing hrms...

Setting up Frappe HR...

Patching Existing Data...
rename_field: kra_title not found in table for: Appraisal Template
rename_field: kra_template not found in table for: Appraisal
Thank you for installing Frappe HR!
Updating Dashboard for hrms

uninstall-app（从站点卸载应用，数据表保留与否有 --drop 类选项控制，先 bench uninstall-app --help 确认）；remove-app（连同 apps/ 目录与构建产物整个移除）。

4.3 站点生命周期：new-site / use / drop-site

new-site（bench new-site --help 实测关键参数）：

Usage: bench  new-site [OPTIONS] SITE

Options:
  --db-name TEXT                  Database name
  --db-password TEXT              Database password
  --db-type [mariadb|postgres|sqlite]  Default is "mariadb"
  --db-host TEXT                  Database Host
  --db-port INTEGER               Database Port
  --db-root-username TEXT         Default is "root"
  --db-root-password TEXT         Root password for MariaDB or PostgreSQL
  --admin-password TEXT           Administrator password for new site
  --install-app TEXT              Install app after installation
  --set-default                   Set the new site as default site
  --setup-db / --no-setup-db      Create user and database
  --force                         Force restore if site/database already exists
  --source-sql TEXT               Initiate database with a SQL file

实测（独立测试站点 test.local，进度条逐行刷新，中间行省略）：

bench new-site test.local --mariadb-root-password q1w2e3r4 --admin-password q1w2e3r4

Installing frappe...
Updating DocTypes for frappe        : [                                        ] 0%
...（进度条逐行刷新至 100%，此处省略）
Updating DocTypes for frappe        : [========================================] 100%
Updating Dashboard for frappe
*** Scheduler is disabled ***

use（设置默认站点，写入 sites/currentsite.txt，之后 Framework 命令可省 --site）：

bench use hr.example.com

drop-site（删站，自动先做最终备份再删库归档）：

bench drop-site test.local --root-password q1w2e3r4 --force

实测回显：

Private : /home/frappe/frappe-bench/sites/test.local/private/backups/20261023_114416-test_local-private-files.tar 10.0KiB
Dropping site database and user
Moving site to archive under /home/frappe/frappe-bench/archived/sites

💡 说明：drop-site 先把私有文件备份到 archived/sites 再移除，误删可从归档救回。

4.4 进程托管：serve / worker / schedule / start / restart

serve（Werkzeug 开发 Web 服务器，bench serve --help 实测参数）：

Options:
  --port INTEGER
  --profile
  --proxy          The development server may be run behind a proxy
  --noreload
  --nothreading
  --with-coverage

实测（启动后另终端验证）：

nohup bench --site hr.example.com serve --port 8000 &
curl --noproxy "*" -s http://127.0.0.1:8000/api/method/ping

{"message":"pong"}

worker（后台队列消费进程，bench worker --help 实测参数）：

Options:
  --queue TEXT                    Queue to consume from. Multiple queues can be specified using comma-separated string.
                                  If not specified all queues are consumed.
  --quiet                         Hide Log Outputs
  -u, --rq-username TEXT          Redis ACL user
  -p, --rq-password TEXT          Redis ACL user password
  --burst                         Run Worker in Burst mode.

生产化用法（与 frappe_docker 编排一致）：

bench worker --queue short,default   # 短任务队列
bench worker --queue long,default,short  # 长任务队列
bench schedule                        # 定时调度进程

start（开发模式一键拉起 web/socketio/redis/ watch 全套进程组，需要 Procfile）；restart（生产形态重启 supervisor 进程组或 systemd 单元，bench setup production 之后可用）。

4.5 备份恢复：backup / restore

backup（单站备份）：

bench --site hr.example.com backup

实测回显：

Backup Summary for hr.example.com at 2026-10-23 11:43:40.278387
Config  : /home/frappe/frappe-bench/sites/hr.example.com/private/backups/20261023_114339-hr_example_com-site_config_backup.json 186.0B
Database: /home/frappe/frappe-bench/sites/hr.example.com/private/backups/20261023_114339-hr_example_com-database.sql.gz 1.1MiB
Backup for Site hr.example.com has been successfully completed

加 --with-files 追加公共/私有文件包（实测产物四件套样例见《Frappe HR 16.52.0 Docker Compose 部署指南》10.3 节）；backup-all-sites 遍历当前 bench 全部站点。

restore（恢复库与文件，⚠️ --db-root-password 是 restore 的子命令选项，放在 SQL 路径之后）：

bench --site hr.example.com restore /path/to/20261023_114339-hr_example_com-database.sql.gz \
  --db-root-password q1w2e3r4 \
  --with-public-files /path/to/20261023_114144-frontend-files.tar \
  --with-private-files /path/to/20261023_114144-frontend-private-files.tar

实测回显：

App frappe already installed
*** Scheduler is disabled ***
Site frontend has been restored with files

4.6 结构同步与缓存：migrate / build / clear-cache / enable-scheduler

bench --site hr.example.com migrate

实测回显（尾部；补丁与表结构同步全过程，成功标志是 after_migrate hooks 执行）：

Executing `after_migrate` hooks...

Queued rebuilding of search index for hr.example.com

bench --site hr.example.com clear-cache

实测回显：无输出（静默成功）。

bench --site hr.example.com enable-scheduler

实测回显：

Enabled for hr.example.com

build（编译前端资产，get-app 内部自动调用）：

bench build --app hrms

实测回显（节选）：

✔ Application Assets Linked

4.7 开发调试三件套：execute / request / console

execute（以站点环境直接调用任意 Python 函数，排障与运维脚本利器）：

bench --site hr.example.com execute frappe.utils.now

实测回显：

2026-10-23 11:43:33.671776

业务查询示例（Leave Type 清单，返回 JSON）：

bench --site hr.example.com execute frappe.client.get_list \
  --kwargs '{"doctype":"Leave Type", "filters":{}}'

实测回显：

[{"name": "Casual Leave"}, {"name": "Compensatory Off"}, {"name": "Sick Leave"}, {"name": "Privilege Leave"}, {"name": "Leave Without Pay"}, {"name": "年假(实测)"}]

request（以管理员身份发起 HTTP 请求并回显）；console（IPython 交互环境，加载站点上下文，可直接 frappe.get_doc() 调试）；doctor/show-pending-jobs（后台 worker 诊断）。

4.8 配置读写：set-config / show-config

bench set-config -gp db_port 3306          # -g 全局 -p 按类型解析
bench --site hr.example.com show-config    # 查看（输出合并表格，实测样例见配置篇 3.1）

⚠️ 注意：bench 5.31.0 已移除 get-config（实测报 Error: No such command: get-config），读取一律用 show-config 或直接读 JSON；set-config 只有 -g/-p 两个选项（实测 --help），删除键需编辑文件。详解见《Frappe HR 16.52.0 配置参数详解》第三章。

五、注意事项

命令的两层归属：init/get-app/remove-app/update 管理 bench 目录本身，必须在 bench 目录内执行；new-site/backup/migrate 等站点命令带 --site（或先 bench use 设默认），在 bench 内任意子目录均可。
root 限制：所有 bench 命令都以 bench 属主用户（本文 frappe）执行，root 会收到 WARN: You should not run this command as root，部分命令直接退出。
--depth 1 浅克隆：shallow_clone: true（默认）下 get-app 只拉单提交，够用且快；要本地提交补丁需 git fetch --unshallow。
migrate 前必备份：migrate 执行补丁不可自动回退，升级与补丁回放前先 bench --site <站点> backup。
scheduler 状态：新站默认 *** Scheduler is disabled ***（new-site 回显可见），生产启用：bench --site <站点> enable-scheduler。
敏感产物位置：备份落在 sites/<站点>/private/backups/（含 db_password），归档站落在 archived/sites/，均需纳入备份迁移清单并控权限。

六、常见问题（FAQ）

Q1：bench --site xxx 报 Site xxx does not exist？

站点名必须与 sites/ 下目录名完全一致（bench list-sites 核对）；或当前 bench 目录不对（bench find /home 可递归定位 bench 目录）。

Q2：execute 调用带参数的函数怎么传参？

--kwargs 传 JSON 字典（实测见 4.7 节），位置参数用 --args 传 JSON 数组；引号嵌套建议单引号包 JSON、内部全双引号。

Q3：serve 起了但 curl 502/无响应？

Werkzeug 是前台进程，注意进程是否还活着（ss -ltnp | grep 8000）；另注意 shell 环境里的 http_proxy 变量会让 curl 走代理回环失败，测试时用 curl --noproxy "*"（本文实测同因，绕过后正常）。

Q4：drop-site 之后想恢复？

归档在 frappe-bench/archived/sites/<站点名>/（含最终备份），把目录移回 sites/ 并恢复对应数据库即可；备份 SQL 可直接对同名新站 bench restore。

Q5：升级三件套的正确顺序？

bench --site <站点> backup → bench update（拉代码+环境）→ bench --site <站点> migrate（结构同步）→ bench build（资产）→ bench --site <站点> clear-cache；失败用 bench retry-upgrade 重试。

七、参考链接

bench 官方仓库与命令文档：https://github.com/frappe/bench
bench 命令参考（官方 docs）：https://docs.frappe.io/framework/user/en/bench
Frappe Framework 官方文档（CLI 背景与站点模型）：https://docs.frappe.io/framework
Frappe HR 仓库：https://github.com/frappe/hrms
本系列关联文档：《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 配置参数详解》