frappe-ops-bench

Bench CLI 完整参考

完整的 bench CLI 参考，涵盖站点管理、应用生命周期、配置和多租户。

版本：v14/v15/v16

---

快速参考：常用命令

任务	命令
创建 bench	bench init myproject --frappe-branch version-15
创建站点	bench new-site mysite.localhost --admin-password admin
设置默认站点	bench use mysite.localhost
获取应用	bench get-app erpnext --branch version-15
安装应用	bench --site mysite install-app erpnext
启动开发服务器	bench start
运行迁移	bench --site mysite migrate
构建资源	bench build --app myapp
备份站点	bench --site mysite backup
恢复备份	bench --site mysite restore /path/to/backup.sql.gz
打开控制台	bench --site mysite console
打开数据库 Shell	bench --site mysite mariadb
检查调度器	bench doctor
查看待处理任务	bench show-pending-jobs
更新所有内容	bench update
删除站点	bench drop-site mysite --force

---

工作流 1：创建新的 Bench

# Initialize bench with specific Frappe version
bench init myproject --frappe-branch version-15

# With Python version
bench init myproject --frappe-branch version-15 --python python3.11

# Enter bench directory (REQUIRED for all subsequent commands)
cd myproject

bench init 会创建以下内容：

myproject/
├── apps/           # Installed Frappe apps (frappe is default)
├── sites/          # All sites and shared config
│   └── common_site_config.json
├── config/         # Redis, Procfile, supervisor configs
├── env/            # Python virtual environment
├── logs/           # Log files
└── Procfile        # Process definitions for bench start

关键规则

• 务必指定 --frappe-branch 以固定 Frappe 版本
• 务必在 bench 目录中运行命令
• 切勿以 root 身份运行 bench 命令——请使用专用的 frappe 用户

---

工作流 2：站点管理

创建站点

# Basic site creation
bench new-site mysite.localhost --admin-password admin

# With specific database
bench new-site mysite.localhost --db-name mysite_db --admin-password admin

# With MariaDB root password
bench new-site mysite.localhost --mariadb-root-password rootpass --admin-password admin

# Install apps during creation
bench new-site mysite.localhost --admin-password admin --install-app erpnext

设置默认站点

bench use mysite.localhost
# OR set environment variable for current session:
export FRAPPE_SITE=mysite.localhost

删除站点

bench drop-site mysite.localhost --force
# Deletes database and archives site directory

站点目录结构

sites/mysite.localhost/
├── site_config.json     # Site-specific config (db credentials)
├── private/             # Auth-required files, backups
├── public/              # Publicly accessible files
├── locks/               # Scheduler lock files
└── task-logs/           # Scheduler task logs

---

工作流 3：应用管理

# Download app from GitHub
bench get-app erpnext --branch version-15
bench get-app https://github.com/org/custom-app.git --branch main

# Install app on a site
bench --site mysite install-app erpnext

# List installed apps
bench --site mysite list-apps

# Remove app from site (creates backup first)
bench --site mysite uninstall-app custom_app

# Remove app from bench entirely
bench remove-app custom_app

# Switch app branch
bench switch-to-branch version-15 erpnext frappe

# Exclude app from updates
bench exclude-app custom_app

# Re-include app in updates
bench include-app custom_app

关键规则

• 务必先运行 get-app，再运行 install-app——获取会下载应用，安装会激活应用
• 务必在运行 uninstall-app 前备份——它会删除与应用相关的数据
• 切勿手动删除应用文件夹——请使用 bench remove-app

---

工作流 4：bench update：它的作用

# Full update (pull + migrate + build + restart)
bench update

# Update specific app only
bench update --pull --app erpnext

# Skip build step
bench update --no-build

# Skip backup
bench update --no-backup

# Reset to upstream (DESTROYS local changes)
bench update --reset

bench update 按以下顺序执行这些步骤：

1. 备份所有站点
2. 拉取所有应用的最新代码（git pull）
3. 安装 Python/Node 依赖
4. 构建静态资源（bench build）
5. 在所有站点上运行迁移（bench migrate）
6. 重启 bench 进程

关键规则

• 务必在 screen/tmux 会话中运行 bench update——这需要一些时间
• 切勿在生产环境中使用 --reset，除非你清楚它会执行 git reset --hard
• 务必先在预发布环境中测试更新

---

工作流 5：bench migrate

# Migrate specific site
bench --site mysite migrate

# Migrate all sites
bench --site all migrate

# Check if safe to migrate (no pending jobs)
bench --site mysite ready-for-migration

bench migrate 的作用：

1. 运行架构同步（DocType 更改 → 数据库）
2. 运行补丁（数据迁移）
3. 重建搜索索引
4. 同步翻译
5. 重建 Dashboard 缓存

何时运行迁移

• bench update 后（会自动执行）
• 更改 hooks.py 后
• 添加或修改 DocType 后
• 拉取代码更改后
• 切勿在代码更改后跳过 migrate——这会导致架构不匹配

---

工作流 6：bench build

# Build all apps
bench build

# Build specific app
bench build --app myapp

# Build with bundle analyzer
bench build --app myapp --production

# Watch mode (auto-rebuild on file changes)
bench watch

何时构建

• 更改 JS/CSS 文件后
• bench get-app 后（会自动执行）
• 修改 package.json 后
• 修改客户端资源后，务必进行构建

---

工作流 7：控制台和数据库访问

# IPython console (with Frappe loaded)
bench --site mysite console
# In console:
# >>> frappe.get_doc("Sales Invoice", "INV-001")
# >>> frappe.db.sql("SELECT name FROM `tabUser` LIMIT 5")

# Auto-reload on code changes
bench --site mysite console --autoreload

# MariaDB shell
bench --site mysite mariadb
# >>> SELECT name, email FROM tabUser LIMIT 5;

# PostgreSQL shell
bench --site mysite postgres

# Execute a method directly
bench --site mysite execute myapp.tasks.daily_cleanup
bench --site mysite execute myapp.api.process --kwargs '{"name": "INV-001"}'

# Make authenticated request as Administrator
bench --site mysite request GET /api/resource/User

---

工作流 8：备份和恢复

# Backup (database + files)
bench --site mysite backup
# Creates: sites/mysite/private/backups/
#   YYYY-MM-DD_HHMMSS-mysite-database.sql.gz
#   YYYY-MM-DD_HHMMSS-mysite-files.tar
#   YYYY-MM-DD_HHMMSS-mysite-private-files.tar

# Backup all sites
bench backup-all-sites

# Backup with encryption
bench --site mysite backup --backup-encryption-key mykey

# Restore from backup
bench --site mysite restore /path/to/database.sql.gz

# Restore with files
bench --site mysite restore /path/to/database.sql.gz \
  --with-public-files /path/to/files.tar \
  --with-private-files /path/to/private-files.tar

# Partial restore
bench --site mysite partial-restore /path/to/database.sql.gz

关键规则

• 务必在运行 bench update、uninstall-app 或 drop-site 前备份
• 默认情况下，超过 24 小时的备份会自动删除——请配置 keep_backups_for_hours
• 务必先在预发布站点上测试恢复，再依赖备份

---

工作流 9：调度器和后台任务

# Enable/disable scheduler
bench --site mysite scheduler enable
bench --site mysite scheduler disable
bench --site mysite scheduler pause
bench --site mysite scheduler resume

# Check scheduler health
bench doctor

# View queued jobs
bench show-pending-jobs

# Purge pending jobs
bench --site mysite purge-jobs

# Manually trigger scheduler event
bench --site mysite trigger-scheduler-event hourly

# Start worker manually (for debugging)
bench worker --queue short

---

工作流 10：多租户

基于 DNS 的路由（推荐）

# Enable DNS multi-tenancy
bench config dns_multitenant on

# Create sites with proper hostnames
bench new-site site1.example.com --admin-password admin
bench new-site site2.example.com --admin-password admin

# Regenerate nginx config
bench setup nginx

# Reload nginx
sudo service nginx reload

请求会根据 Host 标头与站点名称的匹配结果进行路由。

基于端口的路由（替代方案）

bench config dns_multitenant off
bench new-site site2.localhost --admin-password admin
bench set-nginx-port site2.localhost 8082
bench setup nginx
sudo service nginx reload

自定义域名映射

# Add domain to site
bench setup add-domain site1.example.com --site mysite
bench setup nginx
sudo service nginx reload

---

配置：common_site_config.json

位于 sites/common_site_config.json——适用于所有站点。

关键配置项

配置项	默认值	用途
background_workers	1	后台作业工作进程数量
developer_mode	false	自动将 DocType 更改同步到文件
dns_multitenant	false	启用基于 DNS 的多租户
gunicorn_workers	2	Web 服务器工作进程数量（最小值：2）
maintenance_mode	0	使所有站点下线
pause_scheduler	0	暂停作业调度器
serve_default_site	—	主机不匹配时使用的默认站点
server_script_enabled	false	启用 Server Scripts
scheduler_tick_interval	60	调度器检查的间隔秒数
webserver_port	8000	开发服务器端口
socketio_port	9000	Socket.IO 端口
live_reload	false	资源重建时自动重新加载

Redis 配置

配置项	默认值
redis_cache	redis://localhost:13000
redis_queue	redis://localhost:11000
redis_socketio	redis://localhost:13000

设置配置值

# Set common config (all sites)
bench config set-common-config -c background_workers 4
bench config set-common-config -c developer_mode 1

# Set site-specific config
bench --site mysite set-config developer_mode 1
bench --site mysite set-config maintenance_mode 1

# View current config
bench --site mysite show-config

---

配置：site_config.json

站点级配置，位于 sites/<sitename>/site_config.json。

必填配置项

配置项	用途
db_type	mariadb 或 postgres
db_name	数据库名称
db_password	数据库密码

重要的可选配置项

配置项	用途
admin_password	管理员初始密码
host_name	站点完整 URL（含协议）
install_apps	还原／重新安装时要安装的应用
allow_cors	CORS 源（"*"、URL 或数组）
max_file_size	上传限制（默认值：10MB）
mute_emails	禁用所有发出的邮件
logging	调试级别（0-2，级别 2 会显示 SQL 查询）

环境变量覆盖

环境变量会覆盖配置文件。键映射：FRAPPE_REDIS_QUEUE、FRAPPE_REDIS_CACHE、FRAPPE_DB_HOST、FRAPPE_DB_PORT、FRAPPE_DB_NAME、FRAPPE_DB_PASSWORD。

优先级：环境变量 > site_config.json > common_site_config.json > 默认值

---

生产环境设置

sudo bench setup production frappe-user   # nginx + supervisor + fail2ban
bench setup lets-encrypt mysite.example.com  # SSL
sudo bench restart                          # Restart services
bench disable-production                    # Back to development

---

版本差异

功能	V14	V15	V16
bench init	是	是	是
调度器滴答间隔	~240s	~240s	60s
db_user 配置（单独配置）	否	否	是
console --autoreload	否	是	是
trim-tables 命令	否	是	是
trim-database 命令	否	是	是
request 命令	否	是	是
Gettext 翻译	否	否	是

---

参考文件

文件	内容
commands.md	包含所有选项的完整命令参考
examples.md	常见工作流示例
custom-commands.md	使用 Click 创建自定义 bench CLI 命令
anti-patterns.md	常见 bench 错误及修复方法