作者： Next

用法

bench migrate [OPTIONS]

说明

migrate 命令会将站点状态更新到当前可用的应用。它
按顺序执行一系列任务：

• 运行 before_migrate 钩子
• 运行应用补丁
• 同步数据库架构和后台任务
• 同步固定数据
• 同步仪表盘、桌面图标和网页
• 更新翻译
• 为所有路由重建搜索索引
• 运行 after_migrate 钩子

此操作还会更新相应文件的 touched_tables.json 文件，
并更新“已安装应用”DocType 中的应用版本。

参数

• --skip-failing 跳过运行失败的补丁
• --skip-search-index 跳过网页文档的搜索索引

示例

1. 在现有站点上运行迁移。

bench --site {site} migrate

1. 运行迁移时跳过为网页文档重建搜索索引

bench --site {site} migrate --skip-search-index

2. 运行迁移时跳过任何失败的补丁。

bench --site {site} migrate --skip-failing

注意：不建议在生产环境中跳过失败的补丁

用法

bench drop-site [OPTIONS] SITE

说明

删除一个已有的站点。在此操作中，数据库会被删除，并且相应站点的文件夹会从 ./sites 移动到你的 Bench 上的 ./archived_sites （除非另有指定）。在此之前会先对站点进行完整备份。

选项

• --db-root-username 具有删除数据库权限的 DBMS 用户名。
  默认为 root
• --db-root-password DBMS 用户的密码
• --archived-sites-path 指定站点文件夹要移动到的路径

标志

• --no-backup 在删除站点前跳过备份
• --force 即使遇到错误也强制删除站点

示例

1. 通过传入 root 密码来跳过交互式提示。

bench drop-site {site} --db-root-password {db-root-pass}

1. 在删除站点前跳过备份。

bench drop-site {site} --no-backup

1. 将站点文件夹移动到其他文件夹，而不是标准的
   ./archived_sites。

bench drop-site {site} --archived-sites-path {path/to/archive}

用法

bench new-site [OPTIONS] SITE

说明

创建一个新的 Frappe 站点。此操作会在 ./sites 下创建一个新文件夹，其中将包含该站点的所有站点信息，同时还会在你的数据库管理系统中创建一个新数据库，并安装 Frappe 的所有模块和 DocType。

站点配置位于 ./sites/{site}/site_config.json 下，用于维护站点的状态信息。如需了解更多相关信息，请查看本指南。

如果站点创建因任何原因失败，系统会提示你是否要回滚所做的更改，包括创建的站点目录，以及创建的数据库和数据库用户。

选项

• --db-name 设置新站点的数据库名称——如果未单独指定，也会用作数据库用户名
• --db-user 从 v16 起，选择数据库用户名，或指定一个已有的用户名+密码组合
• --db-password 设置新站点的数据库密码，或指定已有数据库用户的密码。
• --db-type 选择新站点的数据库类型，可选值为 “postgres” 或 “mariadb”。默认为 “mariadb”
• --db-host 设置新站点的数据库主机
• --db-port 设置新站点的数据库端口
• --db-root-username 指定 MariaDB 或 Postgres 的 Root 用户名
• --db-root-password 指定 MariaDB 或 Postgres 的 Root 密码
• --admin-password 指定新站点的管理员密码
• --source_sql 使用 SQL 文件初始化数据库
• --install-app 安装后安装应用

标志

• --no-mariadb-socket 将 MariaDB 主机设置为 %，并使用 TCP/IP Socket 代替 UNIX Socket
• --verbose 增加详细输出
• --force 如果站点或同名数据库已存在，则强制恢复

示例

1. 创建一个新站点。

bench new-site {site}

2. 创建一个新的 PostgreSQL 站点。

bench new-site {site} --db-type postgres

3. 创建一个新站点，同时跳过以下交互式提示：

   • 提交站点的 管理员 密码
   • 提交 MariaDB Root 密码

   bench new-site {site}
      --admin-password {admin-password}
      --db-root-password {mariadb-password}
   

4. 使用非默认值和自动生成的值创建一个新站点。

bench new-site {site} --db-type {type}
   --db-name {name}
   --db-user {user}
   --db-password {pass}
   --db-host {host}
   --db-port {port}

5. 使用具有数据库创建权限的 MariaDB 非 root 用户创建一个新站点。

bench new-site {site}
   --db-root-username {user}
   --db-root-password {pass}

6. 创建一个新站点，并安装一个应用 （在当前 bench 中可用）。

bench new-site {site} --install-app {app}

Frappe 和 Bench 下命令的手册，可通过 Bench 命令行界面访问。

站点命令

1. 新建站点
2. 删除站点
3. 迁移
4. 备份
5. 重新安装
6. 列出应用
7. 安装应用
8. 卸载应用
9. 显示配置
10. 设置配置
11. 恢复
12. 部分恢复

Frappe 实用命令

1. 版本

数据库维护命令

1. 转换数据库
2. 精简数据库
3. 精简数据表

翻译管理

1. 生成 POT 文件
2. 将 CSV 迁移为 PO
3. 更新 PO 文件
4. 将 PO 编译为 MO

除了框架自带的命令之外，Frappe 的 bench_manager 模块还会搜索
你的自定义应用中的任何命令。因此，bench 会与
对应 bench 的 Frappe 进行通信，而 Frappe 又会检查
所有应用中可用的命令。

要让你的自定义命令对 bench 可用，只需在你的父模块下创建一个 commands 模块，
并使用 click 包装器编写命令，同时定义一个
名为 commands 的变量，其中包含一组 click 函数，也就是你自己的
命令。

带有 Frappe 应用 flags 的目录结构可以这样理解：

frappe-bench
|──apps
 |── frappe
 ├── flags
 │ ├── README.md
 │ ├── flags
 │ │ ├── commands <------ commands module
 │ ├── license.txt
 │ ├── requirements.txt
 │ └── setup.py

commands 模块可以是一个单独的文件，比如 commands.py，也可以是一个
包含 __init__.py 文件的目录。对于一个名为 ‘flags’ 的自定义应用，
可以举例如下

# file_path: frappe-bench/apps/flags/flags/commands.py
import click

@click.command('set-flags')
@click.argument('state', type=click.Choice(['on', 'off']))
def set_flags(state):
 from flags.utils import set_flags
 set_flags(state=state)

commands = [
 set_flags
]

并且在当前 bench 的上下文中，这个命令可以简单地这样执行

➜ bench set-flags
Flags are set to state: 'on'

本页面仅涉及 bench 项目中存在的命令，
这些命令是 CLI 工具的直接组成部分。这些命令定义在
frappe/bench 下。

有关任何框架命令的参考，请查看 Frappe 命令。

使用 bench CLI

➜ bench
Usage: bench [OPTIONS] COMMAND [ARGS]...

 Bench manager for Frappe

Options:
 --version
 --help Show this message and exit.

Commands:
 backup Backup single site
 backup-all-sites Backup all sites in current bench
 config Change bench configuration
 disable-production Disables production environment for the bench.
 download-translations Download latest translations
 exclude-app Exclude app from updating
 find Finds benches recursively from location
 get-app Clone an app from the internet or filesystem and...

同样，可以通过使用 --help 标志单独执行命令来检查所有可用的标志和选项。例如 init 命令：

➜ bench init --help
Usage: bench init [OPTIONS] PATH

 Initialize a new bench instance in the specified path

Options:
 --python TEXT Path to Python Executable.
 --ignore-exist Ignore if Bench instance exists.
 --apps_path TEXT path to json files with apps to install
 after init

命令

在 Click 的结构下，bench 是主命令组，目前 bench 下有三个主要的命令组，分别是

通用命令

一组不能广泛归类到其他命令中的命令。诸如 init、get-app、find 等命令属于此类别。这些命令直接属于 bench 组，因此可以在 shell 中直接以 bench 为前缀调用。因此，这些命令的用法如下

➜ bench COMMAND [ARGS]...

常用命令

• init：在指定路径初始化一个新的 bench 实例。这会创建一个完整的 bench 文件夹，其中包含一个 apps 文件夹（包含当前 bench 中所有可用的 Frappe 应用）、一个 sites 文件夹（按各个站点文件夹存储所有站点数据）、一个 config 文件夹（包含你的 redis、NGINX 和 supervisor 配置文件）。env 文件夹包含当前 bench 的所有 Python 依赖以及已安装的 Frappe 应用所具有的依赖。

• restart：重启 web、supervisor、systemd 进程单元。用于生产环境设置。

• update：如果在 bench 目录中执行且不带任何标志，将执行备份、拉取、设置依赖、构建、运行补丁并重启 bench。使用特定标志则只执行某些任务而非全部。

• migrate-env：将虚拟环境迁移到所需的 Python 版本。这会使用指定的 Python 版本重新生成 env 文件夹。

• retry-upgrade：重试失败的升级

• disable-production：禁用 bench 的生产环境。

• renew-lets-encrypt：为站点 SSL 续期 Let’s Encrypt 证书。

• backup：备份单个站点数据。也可用于备份文件。

• backup-all-sites：备份当前 bench 中的所有站点。

• get-app：从互联网或文件系统下载应用并在你的 bench 中进行设置。这会克隆 Frappe 项目的 git 仓库并将其安装到 bench 环境中。

• remove-app：从当前 bench 中完全移除指定的 Frappe 应用，如果该应用未安装在任何站点上，则重新构建资源。

• exclude-app：在 bench update 期间排除应用不进行更新

• include-app：包含应用以进行更新。所有 Frappe 应用在安装时默认都会被包含。

• remote-set-url：设置应用远程 URL

• remote-reset-url：将应用远程 URL 重置为 frappe 官方地址

• remote-urls：显示应用的远程 URL

• switch-to-branch：将所有应用切换到指定分支，或用空格分隔指定多个应用

• switch-to-develop：将 Frappe 和 ERPNext 切换到 develop 分支

高级设置相关

• set-nginx-port：设置站点的 NGINX 端口
• set-ssl-certificate：设置站点的 SSL 证书路径
• set-ssl-key：设置站点的 SSL 证书私钥路径
• set-url-root：设置站点的 URL 根路径
• set-mariadb-host：设置 bench 的 MariaDB 主机
• set-redis-cache-host：设置 bench 的 Redis 缓存主机
• set-redis-queue-host：设置 bench 的 Redis 队列主机
• set-redis-socketio-host：设置 bench 的 Redis socketio 主机
• use：设置 bench 的默认站点
• download-translations：下载最新翻译

开发

• start：启动 Frappe 开发进程。使用 Procfile 启动 Frappe 开发环境。
• src：打印 bench 源文件夹路径，可通过 cd $(bench src) 用于 cd 进入 bench 安装仓库。
• find：从当前位置或指定路径递归查找 bench。
• pip：使用当前 bench 的 pip 来管理 Python 包。有关 pip 用法的帮助：bench pip help [COMMAND] 或 bench pip [COMMAND] -h。
• new-app：在 apps 文件夹下创建一个新的 Frappe 应用。

发布 bench

• release：创建 Frappe 应用的发布版本
• prepare-beta-release：从 develop 分支准备主要 beta 版本

设置命令

此命令组包含用于操作 Frappe 环境所需的要求和环境的命令。用于在当前 bench 上下文中设置 Frappe 环境的设置命令需要使用 bench setup 作为前缀来执行。因此，这些命令的一般用法是

➜ bench setup COMMAND [ARGS]...

• sudoers：将命令添加到 sudoers 列表，以允许无需 root 密码执行 bench 命令

• env：为您的 bench 设置 Python 虚拟环境。这会在 bench 目录根下设置一个 env 文件夹。

• redis：生成 Redis 的配置

• fonts：将 Frappe 字体添加到系统

• config：生成或覆盖 sites/common_site_config.json

• backups：为 bench 备份添加 cronjob

• socketio：为 socketio 服务器设置 node 依赖

• requirements：设置 Python 和 Node 依赖

• manager：使用 Bench Manager 应用设置 bench-manager.local 站点，这是一个安装在它上面的 bench GUI。

• procfile：为 bench start 生成 Procfile

• production：为指定用户设置 Frappe 生产环境。这会安装 ansible、NGINX、supervisor、fail2ban 并生成相应的配置文件。

• nginx：为 NGINX 生成配置文件

• fail2ban：设置 fail2ban，这是一个入侵预防软件框架，保护计算机服务器免受暴力攻击

• systemd：为 systemd 生成配置

• firewall：为系统设置防火墙

• ssh-port：设置系统的 SSH 端口

• reload-nginx：检查 NGINX 配置文件并重新加载服务

• supervisor：为 supervisor 生成配置

• lets-encrypt：为站点设置 lets-encrypt SSL

• wildcard-ssl：为多租户 bench 设置通配符 SSL 证书

• add-domain：为特定站点添加自定义域名

• remove-domain：从站点移除自定义域名

• sync-domains：检查域名是否有变化。如果有，更新域名列表。

• role：通过 ansible 角色安装依赖

配置命令

配置命令组处理当前 bench（不是 CLI 工具）配置的更改。配置组命令用于在当前 bench 上下文中操作配置。这些命令的用法是

➜ bench config COMMAND [ARGS]...

• set-common-config：在通用配置中设置值，参数为 -c、configs 或 –config
• remove-common-config：从当前 bench 的通用配置中移除特定键
• update_bench_on_update：在运行 bench update 时启用/禁用 bench 更新
• restart_supervisor_on_update：启用/禁用 supervisor 进程的自动重启
• restart_systemd_on_update：启用/禁用 systemd 单元的自动重启
• dns_multitenant：在运行 bench update 时启用/禁用 bench 多租户
• serve_default_site：配置 nginx 在端口 80 上服务默认站点
• http_timeout：设置 HTTP 超时

安装命令

安装命令组处理用于安装系统依赖以设置 Frappe 环境的命令。这些命令的用法是

 bench install COMMAND [ARGS]...

• prerequisites：安装先决条件库、基本工具如 b2zip、htop、screen、vim、x11-fonts、python 库、cups 和 Redis
• nodejs：安装 Node.js v8
• nginx：安装 NGINX。如果指定了用户，则为该用户设置 sudoers
• packer：安装 Oracle virtualbox 和 packer 1.2.1
• psutil：通过 pip 安装 psutil
• mariadb：安装并设置指定版本的 MariaDB 和 root 密码
• wkhtmltopdf：为 linux 安装 wkhtmltopdf v0.12.3
• supervisor：安装 supervisor。如果指定了用户，则为该用户设置 sudoers
• fail2ban：安装 fail2ban，这是一个入侵预防软件框架，保护计算机服务器免受暴力攻击
• virtualbox：安装 virtualbox。

一般用法

本节涵盖 Bench CLI 的一般用法，足以让您熟悉基本用法。

创建一个新 bench

init 命令将创建一个安装了 frappe 框架的 bench 目录。它将设置为定期备份。

➜ bench init frappe-bench && cd frappe-bench

添加站点

Frappe 应用由 frappe 站点运行，您必须至少创建一个站点。new-site 命令允许您这样做。

➜ bench new-site site1.local

添加应用

get-app 命令会从远程 git 仓库获取远程 frappe 应用并
安装它们。例如：erpnext

➜ bench get-app erpnext https://github.com/frappe/erpnext

安装应用

要在新站点上安装应用，请使用 bench install-app 命令。

➜ bench --site site1.local install-app erpnext

启动 bench

要开始使用 bench，请使用 bench start 命令

➜ bench start

要登录 Frappe / ERPNext，请打开浏览器并访问
[your-external-ip]:8000，可能是 localhost:8000

默认用户名是“Administrator”，密码是你在
创建新站点时设置的密码。

更新 bench

从你的 bench 目录更新所有应用和站点。此操作会为你执行
备份、设置依赖、构建资源、运行迁移并重启你的
进程管理器。

➜ bench update

更新 Bench 配置

要更新你的 bench 的通用站点配置，你可以使用
config 命令组下的 set-common-config 和 remove-common-config 命令。
要了解更多可用的 Frappe 站点配置，
请查看 Site Config 和 Bench Config 文档。

要添加或更新现有的配置键，你可以运行类似这样的命令

➜ bench config set-common-config -c enable_frappe_logger true

要删除现有的配置键，你可以运行类似这样的命令

➜ bench config remove-common-config enable_frappe_logger

Bench Manager

如需基于 UI 的方式来管理你的部署，请查看 Bench Manager。

➜ bench setup manager

你可以通过在任意现有 bench 上运行上述命令来轻松设置它。

这会做什么？

1. 创建一个新站点 bench-manager.local
2. 获取 bench_manager 应用
3. 在站点 bench-manager.local 上安装 Bench Manager 应用

你可以使用这个站点通过
bench-manager.local 的 /desk 视图来管理你的 bench 操作。

Bench 是一个用于管理 Frappe 部署的命令行工具。它提供了一个简便的界面，帮助你轻松设置和管理基于 Frappe 框架的多个站点和应用。

不过，“bench”这个词在不同语境下含义可能不同。我们既用它指代命令行工具，也用它指代目录，这经常会造成混淆。

“你更新 bench 了吗？”

“更新了，这次最新版本的迁移顺利多了。”

“什么？！我是让你更新命令行工具！”

“但愿客户会喜欢第 13 版。”

为了避免这类情况，我们用 “Bench” 指代 bench 目录，用 “Bench CLI” 指代命令行工具。

要安装 Bench CLI 并搭建 Frappe 环境，请按照安装说明操作。

你可能会惊讶地发现，很多 bench 命令其实是由 Frappe 框架提供的，而不是 Bench CLI 本身。一般来说，这些命令都是针对特定站点运行的（可以使用 --site 参数）。即使是像 bench update 这样的命令，也只是对 Frappe 框架命令（如 backup 和 migrate）的简单封装，再加上一些必要的 bench 和系统级操作。

参考资料

1. Bench 命令
2. Frappe 命令
3. 命令参考
4. 扩展 CLI