ERPNext v16 常用命令与运维实战
ERPNext v16.52.1 bench 工具链实战：version/list-sites、execute/console 免登录执行、备份四件套与多站点备份、new-site→restore→验证→drop-site 全恢复演练、migrate 迁移与缓存清理、管理员密码重置，含真实踩坑实录。
ERPNext v16 常用命令与运维实战
目标：本篇系统梳理 ERPNext v16.52.1 的 bench 工具链——版本与站点管理、execute/console 执行环境、备份与恢复全演练（new-site → restore → 验证 → drop-site 清理闭环实测）、migrate 升级迁移与缓存清理；全部命令与回显均在 v16.52.1 实测环境逐条验证，含真实踩坑实录。
一、环境信息
本篇全部命令与回显来自以下实测环境（实测日期 2026-10-27/28）：
- 操作系统：Ubuntu 22.04（x86_64）
- ERPNext：erpnext 16.52.1 + frappe 框架 16.53.0（
bench version实测） - 数据库：MariaDB 11.8；缓存/队列：Redis 6.2 双实例
- 默认站点：frontend（已装 frappe + erpnext，含一条已提交的销售订单 SAL-ORD-2026-00001 作验证数据）
- bench 工程路径：/home/frappe/frappe-bench
- 部署形态：官方 frappe_docker pwd.yml 多服务栈（部署过程见《ERPNext v16 Docker Compose 部署实战》）
二、工具概览
bench 是 Frappe 体系的核心工程管理 CLI，承担站点全生命周期操作：建站/删站、备份恢复、版本迁移、配置读写与调试执行。它在 bench 工程根目录（本环境 /home/frappe/frappe-bench）运行，工程下每个子目录 sites/<站点名> 对应一个独立站点。
顶层命令全景（bench --help 实测回显，节选）：
Commands:
app-cache View or remove items belonging to bench...
backup-all-sites Backup all sites in current bench
completions Install shell completion for bench (bash or zsh).
config Change bench configuration
disable-production Disables production environment for the bench.
download-translations Download latest translations
drop
exclude-app Exclude app from updating
find Finds benches recursively from location
get-app Clone an app from the internet or filesystem...
init Initialize a new bench instance in the...
new-app Create a new Frappe application under apps folder
remove-app Completely remove app from bench and re-build...
renew-lets-encrypt Sets Up latest cron and Renew Let's Encrypt...
restart Restart supervisor processes or systemd units
retry-upgrade Retry a failed upgrade
set-mariadb-host Set MariaDB host for bench
set-nginx-port Set NGINX port for site
set-redis-cache-host Set Redis cache host for bench
set-redis-queue-host Set Redis queue host for bench
set-redis-socketio-host Set Redis socketio host for bench
setup Setup command group for enabling setting up a...
start Start Frappe development processes
switch-to-branch Switch all apps to specified branch, or...
update Performs an update operation on current bench.
validate-dependencies Validates that all requirements specified in...
（框架侧站点命令在帮助后半段：backup/restore/new-site/drop-site/migrate/console/execute/clear-cache 等，本文 5.x 逐组详解。）
💡 技术拓展：bench 命令的两个作用域容易混淆——
作用域 形态 示例 工程级 不带 --site，作用于整个 bench 工程 bench version、bench set-config -g、bench backup-all-sites站点级 带 --site <站点名>，作用于单站点bench --site frontend backup、bench --site frontend migrate数据类操作（备份/迁移/清缓存）务必确认 --site 目标，工程级与站点级混用是误操作高发点。
三、前置条件
- bench 工程就绪：在 bench 工程根目录执行命令（
ls sites/能看到 common_site_config.json 与站点目录即就绪）； - 站点已初始化：本文以 frontend 站点为操作对象（建站过程见部署篇 4.4）；
- 数据库 root 凭据在手：new-site/restore/drop-site 需要数据库 root 权限（本环境 root/q1w2e3r4）；
- 磁盘预留：备份产物为站点数据库压缩 SQL + 文件 tar 包，实测本站点全量备份约 1 MB 量级，生产数据按库体积 1:1 预留并外送。
四、各工具详解
4.1 版本与站点管理
查看已装应用与版本（工程级）：
cd /home/frappe/frappe-bench && bench version
erpnext 16.52.1 ()
frappe 16.53.0 ()
列出工程内全部站点：
bench list-sites
Available sites:
* frontend
（* 标记当前默认站点。）
站点信息速查：站点级事实（库名、已装应用、密码）在 sites/<站点>/site_config.json，版本锁定在 sites/apps.json——两文件的键义详解见《ERPNext v16 配置参数详解》3.1/5.7 节。
4.2 bench execute：免登录执行框架方法
bench execute 直接调用框架任意可导入方法，适合巡检与脚本化运维，不需要 Web 登录态。
查站点数据库体积（单位 MB，实测）：
bench --site frontend execute frappe.db.get_database_size
48.60406876
查服务器时间（验证站点时区上下文，实测）：
bench --site frontend execute frappe.utils.now_datetime
2026-10-28 00:58:13.495306
带参调用：--args 传位置参数（JSON 数组）、--kwargs 传关键字参数（JSON 对象），例如统计文档数：
bench --site frontend execute frappe.db.count --args '["Sales Order"]'
1
（实测环境恰好 1 张销售订单，回显与数据一致。）
4.3 bench console：交互式 Python 调试环境
bench console 打开该站点的 IPython 环境，预载 frappe 上下文（frappe.local、frappe.db 可直接用），是排查数据问题的最强工具。非交互用法支持标准输入直接喂代码（实测）：
echo 'import frappe
print("站点:", frappe.local.site)
print("公司数:", frappe.db.count("Company"))
doc = frappe.get_doc("Sales Order", "SAL-ORD-2026-00001")
print("订单:", doc.name, doc.status, doc.grand_total)
' | bench --site frontend console
实测回显（节选）：
In [2]: 站点: frontend
In [3]: 公司数: 1
In [5]: 订单: SAL-ORD-2026-00001 To Deliver and Bill 16000.0
In [6]: Do you really want to exit ([y]/n)?
要点：
- console 里的数据变更默认不自动提交，显式
frappe.db.commit()后才落库（只读查询无此顾虑）； - 交互退出按 Ctrl+D，非交互管道模式结束即退出（回显中的退出确认按回车即可）；
- console 与 execute 的分工：execute 适合单方法调用进巡检脚本，console 适合多步探索与打印对象。
4.4 备份命令族
单站点备份（含文件）：
bench --site frontend backup --with-files
实测回显：
Backup Summary for frontend at 2026-10-28 00:48:54.462911
Config : /home/frappe/frappe-bench/sites/frontend/private/backups/20261028_004852-frontend-site_config_backup.json 176.0B
Database: /home/frappe/frappe-bench/sites/frontend/private/backups/20261028_004852-frontend-database.sql.gz 999.1KiB
Public : /home/frappe/frappe-bench/sites/frontend/private/backups/20261028_004852-frontend-files.tar 10.0KiB
Private : /home/frappe/frappe-bench/sites/frontend/private/backups/20261028_004852-frontend-private-files.tar 10.0KiB
Backup for Site frontend has been successfully completed with files
备份四件套说明：
| 文件 | 内容 | 恢复时的对应选项 |
|---|---|---|
| *-site_config_backup.json | 站点配置快照（db 凭据等） | 参考/比对手工用 |
| *-database.sql.gz | 全库压缩 SQL | restore 的主参数 |
| *-files.tar | 公共文件（用户上传的公开附件） | --with-public-files |
| *-private-files.tar | 私有文件（备份自身、敏感附件） | --with-private-files |
多站点批量备份（工程级，实测）：
bench backup-all-sites
Backup Summary for frontend at 2026-10-28 00:59:51.002067
Config : /home/frappe/frappe-bench/sites/frontend/private/backups/20261028_005949-frontend-site_config_backup.json 200.0B
Database: /home/frappe/frappe-bench/sites/frontend/private/backups/20261028_005949-frontend-database.sql.gz 999.5KiB
Backup for Site frontend has been successfully completed
⚠️ 踩坑实录：
backup-all-sites不支持--with-files选项（实测报No such option: --with-files），它只备数据库与配置，不备文件包。多站点环境需要文件备份时逐站点跑bench --site <站点> backup --with-files。
备份产物统一落在 sites/<站点>/private/backups/，文件名含时间戳与站点名。生产节奏建议：数据库备份每日（可用系统 cron 调 bench backup）、文件备份变化后手动/周任务执行，并把 backups 目录外送到远端存储。
4.5 备份恢复全演练（new-site → restore → 验证 → 清理）
本节是一套完整可复现的恢复演练：把 frontend 的备份恢复到一个新站点 restore.local，验证数据完整后清理。生产故障换机恢复就是同一条路径。
第 1 步：生成最新备份（回显见 4.4，本演练使用 20261028_005829 批次）。
第 2 步：新建空站点：
bench new-site restore.local --mariadb-user-host-login-scope='%' --admin-password=q1w2e3r4 --db-root-username=root --db-root-password=q1w2e3r4
实测回显（节选；DocType 更新进度条略）：
Installing frappe...
Updating DocTypes for frappe : [== ] 5%...
Current Site set to: restore.local
⚠️ 踩坑实录：老教程里的
--no-mariadb-socket选项已弃用，实测会打印警告：--no-mariadb-socket is DEPRECATED; use --mariadb-user-host-login-scope='%' (wildcard) or --mariadb-user-host-login-scope=<myhostscope>, instead.v16 一律改用--mariadb-user-host-login-scope='%'（数据库用户允许从任意主机连入，容器/独立库服务器场景必需）。
第 3 步：全量恢复备份到新站点：
bench --site restore.local restore sites/frontend/private/backups/20261028_005829-frontend-database.sql.gz \
--with-private-files sites/frontend/private/backups/20261028_005829-frontend-private-files.tar \
--with-public-files sites/frontend/private/backups/20261028_005829-frontend-files.tar \
--db-root-username root --db-root-password q1w2e3r4
实测回显（节选）：
File sites/frontend/private/backups/20261028_005829-frontend-database.sql.gz not found. Trying to check in alternative directories.
File /home/frappe/frappe-bench/sites/frontend/private/backups/20261028_005829-frontend-database.sql.gz found.
App frappe already installed
*** Scheduler is disabled ***
Site restore.local has been restored with files
两点解读：
- 第一行的 "not found... found" 是 bench 的相对路径自动补全（先按相对路径找、再按 bench 内部路径找），回显正常；
- restore 直接恢复了备份里的 installed_apps（frappe + erpnext），无需提前在空站点装应用。
⚠️ 踩坑实录两则： ① restore 没有
--with-files选项，文件包选项是--with-private-files与--with-public-files（实测报错No such option '--with-files'. (Did you mean one of: '--with-private-files', '--with-public-files'?），与 backup 的 --with-files 命名不对称，极易踩）； ② 不传--db-root-username/--db-root-password时 restore 会交互式询问 MySQL root 密码（实测卡在MySQL root password:提示），脚本化恢复必须显式传凭据。
第 4 步：验证恢复完整性（console 查三处关键数据，实测）：
echo 'print("公司:", frappe.db.get_value("Company", "Quzuo Trading", "default_currency"))
print("订单:", frappe.db.get_value("Sales Order", "SAL-ORD-2026-00001", ["status","grand_total"], as_dict=True))
print("客户数:", frappe.db.count("Customer"))
' | bench --site restore.local console
In [1]: 公司: CNY
In [2]: 订单: {'status': 'To Deliver and Bill', 'grand_total': 16000.0}
In [3]: 客户数: 1
公司/订单/客户与主站完全一致，恢复闭环验证通过。
第 5 步：清理演练站点（drop-site 自带删站前自动备份，实测）：
bench drop-site restore.local --db-root-username root --db-root-password q1w2e3r4 --force
Taking backup of restore.local
Backup Summary for restore.local at 2026-10-28 00:59:24.906918
Config : /home/frappe/frappe-bench/sites/restore.local/private/backups/20261028_005923-restore_local-site_config_backup.json 163.0B
Database: /home/frappe/frappe-bench/sites/restore.local/private/backups/20261028_005923-restore_local-database.sql.gz 999.1KiB
Public : /home/frappe/frappe-bench/sites/restore.local/private/backups/20261028_005923-restore_local-files.tar 10.0KiB
Private : /home/frappe/frappe-bench/sites/restore.local/private/backups/20261028_005923-restore_local-private-files.tar 10.0KiB
Dropping site database and user
Moving site to archive under /home/frappe/frappe-bench/archived/sites
bench list-sites
Available sites:
* frontend
drop-site 的行为三连：先自动做一次全量备份（双保险）→ 删库删用户 → 站点目录移入 archived/sites 归档（不直接删除）。彻底清理归档可手工移除 archived/sites 下对应目录。
4.6 migrate：版本迁移
应用版本变化后（升级 erpnext/frappe、安装新应用）执行迁移，把 DocType 补丁、数据结构变更应用到数据库：
bench --site frontend migrate
实测回显（节选，主线为补丁与结构变更进度输出，收尾段如下）：
Removing orphan Pages
Removing orphan Reports
Removing orphan Notifications
Removing orphan Sidebars
Removing orphan Docks
Removing orphan List Filters
Removing orphan Kanban Boards
Removing orphan Desktop Icons
要点：
- migrate 前必须先
bench --site <站点> backup --with-files（迁移不可逆，回滚靠备份恢复）； - 已是最新版本时 migrate 照常可跑（补丁清单为空，快速收尾），常用于验证迁移链路；
- 多站点环境用
bench --site all migrate逐站点迁移（每站点输出独立）。
4.7 缓存清理
bench --site frontend clear-cache
（无输出即成功，静默完成）
bench --site frontend clear-website-cache
（无输出即成功）
clear-cache 清框架层缓存（文档缓存、元数据缓存、Redis cache 实例内容），DocType 改动后页面行为异常、权限改后不生效时使用；clear-website-cache 清门户层页面缓存。清理后验证服务正常（实测）：
curl -s http://127.0.0.1:8135/api/method/ping
{"message":"pong"}
4.8 管理员密码重置
bench --site frontend set-admin-password q1w2e3r4
（无输出即成功）
忘记 Administrator 密码时的正规重置通道（实测重设为原值验证命令可用）。生产环境应设强密码并遵守密码策略。
五、注意事项
- Scheduler is disabled 是正常回显：new-site/restore 过程中看到
*** Scheduler is disabled ***不是故障——迁移期间调度器有意停用，站点恢复后由 scheduler 进程按配置接管； - 备份必须外送：backups 目录与站点同盘（sites 卷内），磁盘故障时备份数据与业务数据同生共死，务必同步到远端；
- restore/new-site 的凭据参数：脚本化操作显式传
--db-root-username/--db-root-password，否则命令卡在交互式密码输入（4.5 踩坑实录②）； - drop-site 不是立即删除：站点目录归档到 archived/sites 且删站前自动备份，误删有双重补救窗口；
- console 写操作要 commit：console 内的数据变更不自动提交，
frappe.db.commit()才落库； - 配置类命令（set-config/set-admin-password 等）的完整语义与值类型陷阱见《ERPNext v16 配置参数详解》3.2 节，本篇不重复展开。
六、常见问题（FAQ）
Q1：restore 报 No such option '--with-files'？
backup 用 --with-files 打包文件，restore 的对应选项拆成了两个：--with-private-files <私有 tar> 与 --with-public-files <公共 tar>（4.5 踩坑实录①）。命令命名不对称是 v16 的既定行为，按报错提示（Did you mean...）选对即可。
Q2：restore/new-site 卡在 MySQL root password 提示？
命令进入交互式输密。脚本化场景显式传 --db-root-username root --db-root-password <密码>；人工执行也可在提示处直接输入。
Q3：new-site 报 --no-mariadb-socket 已弃用？
v16 用 --mariadb-user-host-login-scope='%' 替代（语义为数据库用户允许的登录主机范围，'%' 表示任意主机）。官方 pwd.yml 的 create-site 命令即用此新参数。
Q4：bench execute 怎么执行带参数的方法？
--args 传位置参数数组、--kwargs 传关键字对象，均为 JSON 形态：bench --site frontend execute frappe.db.count --args '["Sales Order"]'（实测回显 1）。
Q5：console 里改了数据但界面上没生效？
console 不自动提交。写操作后执行 frappe.db.commit()；若界面还显示旧值，再清一次缓存（bench --site <站点> clear-cache）刷新文档缓存。
Q6：升级后应用行为异常如何回退？
升级 = 替换代码 + migrate 两步。代码回退用 bench switch-to-branch（切回旧版本分支）或重新部署旧版本镜像；数据回退只能靠升级前的备份（bench restore，路径见 4.5）。所以 migrate 前的备份是唯一可靠回退点，不可省略。
七、参考链接
- bench 官方命令文档：https://docs.frappe.io/framework/user/en/bench
- Frappe 框架仓库：https://github.com/frappe/frappe
- ERPNext GitHub 仓库：https://github.com/frappe/erpnext
- 官方部署仓库 frappe_docker：https://github.com/frappe/frappe_docker
- 本专栏背景认知：《ERPNext 介绍与选型指南》
- 本专栏部署实战：《ERPNext v16 Docker Compose 部署实战》
- 本专栏配置详解：《ERPNext v16 配置参数详解》