作者： Next

基准版本

用法

bench version [OPTIONS]

说明

version 命令会显示当前 bench 目录中所有已安装应用的编译信息。你可以选择自己喜欢的输出格式：纯文本、JSON 或 ASCII 表格。--format plain 选项会以纯文本形式显示版本信息，就像 bench version 一样，但会包含更多信息。

$ bench version --format plain
erpnext 14.0.3 version-14 (4e88dcf)
frappe 14.0.1 version-14 (f8ec3d7)

--format json 选项会以格式化 JSON 字符串的形式显示版本信息。如果你要在 bench CLI 之上构建工具，这会特别有用。

$ bench version --format json
[
 {
 "app": "erpnext",
 "branch": "version-14",
 "commit": "4e88dcf",
 "version": "14.0.3"
 },
 {
 "app": "frappe",
 "branch": "version-14",
 "commit": "ef0a5e9",
 "version": "14.0.1"
 }
]

--format table 选项会以 ASCII 表格的形式显示版本信息。

$ bench version --format table
+-------------------------+------------+------------------------------+---------+
| App | Version | Branch | Commit |
+-------------------------+------------+------------------------------+---------+
| erpnext | 14.0.3 | version-14 | 4e88dcf |
| frappe | 14.0.1 | version-14 | f8ec3d7 |
+-------------------------+------------+------------------------------+---------+

选项

  • -f、--format 选择显示当前 bench 中已安装应用版本的格式。可用选项有 “plain”、”table”、”json”、”legacy”。该值默认为 “legacy”。

示例

  1. 获取当前 bench 上已安装应用的人类可读信息，并包含提交消息。
bench version --format plain
  1. 以 JSON 格式获取 bench 版本信息。
bench version -f json

基准部分恢复

用法

bench partial-restore [OPTIONS] SQL_FILE_PATH

说明

你可能只想恢复已备份到某个站点的特定数据表。你很可能使用了 bench backup 中的 --only、--exclude 选项进行了部分备份。

partial-restore 命令可用于通过部分备份来恢复站点。部分备份文件可以是 gzip 压缩文件或纯 SQL 文件。本质上，你可以使用此命令从 SQL 文件中恢复任何内容。

参数

  • SQL_FILE_PATH 数据库源文件的路径。该路径可以是相对于 bench 目录根目录或 sites 文件夹的相对路径，也可以是绝对路径。

如需了解有关相对路径和绝对路径的更多信息，请在维基百科上点击此处。

选项

  • -v、--verbose 增加详细输出

示例

  1. 在站点上使用部分备份进行恢复。
bench --site {site} partial-restore -v {/path/to/sql/file}

基准恢复

用法

bench restore [OPTIONS] SQL_FILE_PATH

说明

Bench CLI 可用于将现有站点恢复到之前的状态。使用
bench restore 命令，可以通过指定的数据库和
文件恢复来还原站点。Frappe 站点不支持降级；当检测到降级时，
在站点恢复开始之前会弹出一个交互式提示。

执行恢复操作的最低要求是在本地文件系统上拥有数据库
文件。指定的路径可以是相对于 bench
或 sites 文件夹的路径，不过绝对路径通常效果最好。

指定的数据库备份文件可以具有 sql.gz 或 sql 扩展名。对于
公共和私有文件备份归档，默认是 tar，但自 版本
13 起，也支持扩展名为 tgz 的压缩归档。

注意：截至目前，无法使用此
命令仅恢复文件。

参数

  • SQL_FILE_PATH 数据库源文件的路径。该路径可以相对于
    bench 目录根或 sites 文件夹。也可以是绝对路径。

要了解有关相对路径和绝对路径的更多信息，请在 Wikipedia 上点击此处。

选项

  • --db-root-username MariaDB 或 Postgres 的 root 用户名
  • --db-root-password MariaDB 或 Postgres 的 root 密码
  • --db-name 站点数据库名称，如果它是新站点
  • --admin-password 新站点的管理员密码
  • --install-app 安装后安装应用
  • --with-public-files 恢复站点的公共文件，给定其
    归档文件的路径
  • --with-private-files 恢复站点的私有文件，给定其
    归档文件的路径

标志

  • --force 忽略站点降级警告（如果适用）。除非你完全了解
    后果，否则不推荐这样做

示例

  1. 使用文件恢复站点
bench --site {site} restore {path/to/database/file}
--with-public-files {path/to/public/archive}
--with-private-files {path/to/private/archive}
  1. 通过在选项中传递值来绕过 DBMS root 交互式提示
bench --site {site} restore {path/to/database/file}
--db-root-username {db-user}
--db-root-password {db-pass}
  1. 指定站点恢复后要安装的新应用
bench --site {site} restore {path/to/database/file}
--install-app {app}
  1. 为恢复的站点指定自定义数据库名称
bench --site {site} restore {path/to/database/file}
--db-name {custom-db-name}
  1. 重置恢复站点的管理员密码
bench --site {site} restore {path/to/database/file}
--admin-password {admin-pass}

基准执行

bench execute 命令让你可以从命令行运行 Python 函数。这对于执行一次性任务、调试或运行自定义脚本非常有用。

该命令会自动建立数据库连接并为站点初始化 Frappe 框架，因此你可以直接调用与数据库交互的函数，无需编写任何初始化代码。

基本用法

bench --site [site-name] execute [path.to.method]

简单示例

bench --site frappe.test execute frappe.clear_cache

这会在你的站点上运行 frappe.clear_cache() 函数。

bench --site frappe.test execute frappe.utils.get_site_info

这会在你的站点上运行 frappe.utils.get_site_info() 函数并打印输出结果。

传递参数

你可以直接在方法名后面传递参数：

bench --site frappe.test execute frappe.get_doc User Administrator

这会调用 frappe.get_doc("User", "Administrator")。

bench --site frappe.test execute frappe.db.get_value DocType User name

这会调用 frappe.db.get_value("DocType", "User", "name")。

JSON 参数

参数会尽可能自动解析为 JSON：

bench --site frappe.test execute frappe.db.exists User Administrator

字符串 “Administrator” 会保持为字符串，但数字和布尔值会被转换：

bench --site frappe.test execute some_function 123 true false

这会传入整数 123 以及布尔值 True 和 False。

命名参数（kwargs）

使用 -- 前缀来指定命名参数：

bench --site frappe.test execute frappe.db.get_value --doctype User --filters '{"name":"Administrator"}' --fieldname email

这会调用：

frappe.db.get_value(doctype="User", filters={"name": "Administrator"}, fieldname="email")

布尔标志

不带值的命名参数会变为 True：

bench --site frappe.test execute frappe.get_list User --ignore_permissions

这会调用 frappe.get_list("User", ignore_permissions=True)。

混合使用位置参数和命名参数

bench --site frappe.test execute frappe.get_list User --limit 5

这会调用 frappe.get_list("User", limit=5)。

运行 Python 表达式

你可以直接运行 Python 表达式：

bench --site frappe.test execute "frappe.db.count('User')"

你可以调用不同类型的 Python 可调用对象：

# Method on a returned object
bench --site frappe.test execute "frappe.get_doc('User', 'Administrator').reload()"

更多示例

# Clear cache for a specific DocType
bench --site frappe.test execute frappe.clear_cache --doctype "Sales Order"

# Get a document
bench --site frappe.test execute frappe.get_doc User Administrator

# Count records
bench --site frappe.test execute frappe.db.count User

# Run a whitelisted method
bench --site frappe.test execute myapp.api.my_function --param1 value1 --param2 value2

# Check if a record exists
bench --site frappe.test execute frappe.db.exists User guest

# Get configuration value
bench --site frappe.test execute frappe.conf.get developer_mode

# Execute a DocType method
bench --site frappe.test execute "frappe.get_doc('User', 'Administrator').get_fullname()"

# Chain operations with Python expressions
bench --site frappe.test execute "frappe.get_doc('User', 'Administrator').add_roles('System Manager')"

性能分析

使用 --profile 标志来查看性能统计信息：

bench --site frappe.test execute frappe.db.get_list --profile --doctype "Sales Order" --limit 1000

这会按累计时间排序列出前 50% 的函数调用。

        42084 function calls (41224 primitive calls) in 0.094 seconds

   Ordered by: cumulative time
   List reduced from 801 to 401 due to restriction <0.5>

   ncalls  tottime  percall  cumtime  percall filename:lineno(function)
      3/2    0.000    0.000    0.091    0.046 {built-in method builtins.eval}
        1    0.000    0.000    0.091    0.091 <bench execute>:1(<module>)
        1    0.000    0.000    0.091    0.091 ~/frappe-bench/apps/frappe/frappe/database/database.py:830(get_list)
     11/1    0.000    0.000    0.091    0.091 ~/frappe-bench/apps/frappe/frappe/__init__.py:1337(get_list)
       31    0.000    0.000    0.073    0.002 ~/frappe-bench/apps/frappe/frappe/database/database.py:183(sql)
       29    0.000    0.000    0.072    0.002 ~/frappe-bench/apps/frappe/frappe/query_builder/utils.py:126(execute_query)
     18/5    0.000    0.000    0.071    0.014 ~/frappe-bench/apps/frappe/frappe/utils/caching.py:125(site_cache_wrapper)
    20/12    0.000    0.000    0.070    0.006 ~/frappe-bench/apps/frappe/frappe/model/meta.py:72(get_meta)
      7/3    0.000    0.000    0.070    0.023 ~/frappe-bench/apps/frappe/frappe/model/utils/__init__.py:132(is_virtual_doctype)
        2    0.000    0.000    0.069    0.034 ~/frappe-bench/apps/frappe/frappe/model/meta.py:149(__init__)
       31    0.000    0.000    0.066    0.002 ~/frappe-bench/apps/frappe/frappe/database/database.py:371(execute_query)
       31    0.000    0.000    0.066    0.002 ~/frappe-bench/env/lib/python3.14/site-packages/MySQLdb/cursors.py:162(execute)
       31    0.000    0.000    0.066    0.002 ~/frappe-bench/env/lib/python3.14/site-packages/MySQLdb/cursors.py:325(_query)
       31    0.000    0.000    0.065    0.002 ~/frappe-bench/env/lib/python3.14/site-packages/MySQLdb/connections.py:276(query)
       31    0.065    0.002    0.065    0.002 {function Connection.query at 0x10be545c0}
       16    0.000    0.000    0.056    0.003 ~/frappe-bench/apps/frappe/frappe/database/database.py:592(get_values)
        2    0.000    0.000    0.034    0.017 ~/frappe-bench/apps/frappe/frappe/model/meta.py:166(process)
     31/2    0.000    0.000    0.034    0.017 ~/frappe-bench/apps/frappe/frappe/model/document.py:187(__init__)
        2    0.000    0.000    0.034    0.017 ~/frappe-bench/apps/frappe/frappe/model/meta.py:157(load_from_db)
        2    0.000    0.000    0.034    0.017 ~/frappe-bench/apps/frappe/frappe/model/document.py:233(load_from_db)
     11/1    0.000    0.000    0.025    0.025 ~/frappe-bench/apps/frappe/frappe/model/qb_query.py:26(execute)
    27/13    0.000    0.000    0.022    0.002 ~/frappe-bench/apps/frappe/frappe/query_builder/utils.py:62(get_query)
        2    0.000    0.000    0.021    0.011 ~/frappe-bench/apps/frappe/frappe/model/meta.py:422(apply_property_setters)
        2    0.000    0.000    0.018    0.009 ~/frappe-bench/apps/frappe/frappe/model/document.py:304(load_children_from_db)
    27/13    0.000    0.000    0.018    0.001 ~/frappe-bench/apps/frappe/frappe/database/query.py:215(get_query)
        2    0.000    0.000    0.016    0.008 ~/frappe-bench/apps/frappe/frappe/database/database.py:514(get_value)
    27/13    0.000    0.000    0.015    0.001 ~/frappe-bench/apps/frappe/frappe/database/query.py:344(apply_fields)
        1    0.000    0.000    0.014    0.014 ~/frappe-bench/apps/frappe/frappe/database/query.py:1280(apply_field_permissions)
        1    0.000    0.000    0.013    0.013 ~/frappe-bench/apps/frappe/frappe/database/query.py:928(_get_cached_permitted_fields)
        1    0.000    0.000    0.013    0.013 ~/frappe-bench/apps/frappe/frappe/model/__init__.py:216(get_permitted_fields)
        1    0.000    0.000    0.013    0.013 ~/frappe-bench/apps/frappe/frappe/model/meta.py:677(get_permitted_fieldnames)
        1    0.000    0.000    0.013    0.013 ~/frappe-bench/apps/frappe/frappe/model/meta.py:720(get_permlevel_access)
        2    0.000    0.000    0.013    0.007 ~/frappe-bench/apps/frappe/frappe/__init__.py:384(get_roles)
        2    0.000    0.000    0.013    0.007 ~/frappe-bench/apps/frappe/frappe/permissions.py:522(get_roles)
        2    0.000    0.000    0.013    0.007 ~/frappe-bench/apps/frappe/frappe/utils/redis_wrapper.py:230(hget)
        1    0.000    0.000    0.013    0.013 ~/frappe-bench/apps/frappe/frappe/permissions.py:530(get)
        1    0.000    0.000    0.012    0.012 ~/frappe-bench/env/lib/python3.14/site-packages/redis/client.py:1163(get_message)
        1    0.000    0.000    0.012    0.012 ~/frappe-bench/env/lib/python3.14/site-packages/redis/client.py:979(parse_response)
        1    0.000    0.000    0.012    0.012 ~/frappe-bench/env/lib/python3.14/site-packages/redis/client.py:960(_execute)
       13    0.000    0.000    0.009    0.001 ~/frappe-bench/apps/frappe/frappe/model/meta.py:108(get_table_columns)
       13    0.000    0.000    0.009    0.001 ~/frappe-bench/apps/frappe/frappe/database/database.py:1356(get_table_columns)
       13    0.000    0.000    0.009    0.001 ~/frappe-bench/apps/frappe/frappe/database/database.py:1337(get_db_table_columns)

在多个站点上运行

在所有站点上执行命令：

bench --site all execute frappe.clear_cache

或在指定站点上执行：

bench --site site1.local --site site2.local execute frappe.clear_cache

注意事项

  • 数据库：成功时更改会自动提交，出错时会回滚
  • 返回值：返回值会以 JSON 格式打印；None 不打印任何内容
  • 错误处理：出错时会以错误码退出并打印完整的堆栈跟踪
  • 安全性：任何 Python 函数都可以执行，不仅限于白名单中的函数——在生产环境中请谨慎使用

使用 –args 和 –kwargs 选项（旧版）

> 注意：--args 和 --kwargs 选项是旧格式，不推荐使用。请改用上面展示的直接传参方式。

你必须使用 Python 语法来配合 --args 和 --kwargs 选项。这些值必须用引号括起来，并且会作为 Python 代码进行求值（使用 eval()），而不是作为 JSON 解析。

传递参数列表

bench --site frappe.test execute frappe.db.get_value --args "['User', 'Administrator', 'email']"

传递关键字参数字典

bench --site frappe.test execute frappe.db.set_value --kwargs "{'doctype': 'User', 'name': 'Administrator', 'fieldname': 'enabled', 'value': 1}"

组合使用

bench --site frappe.test execute frappe.db.get_value --args "['User', 'Administrator']" --kwargs "{'fieldname': 'email'}"

基准配置设置

用法

bench set-config [OPTIONS] KEY VALUE

说明

Bench 提供了一个包装命令，用于在站点配置文件中插入或更新值。
你可以通过同一个命令更新站点中的 site_config.json，以及
bench 目录中的 common_site_config.json。

如需了解更多关于站点配置和键优先级的内容，请参阅
此处的文档。

参数

  • -g, --global 在 Bench 的通用站点配置中设置值
  • -p, --parse 解析给定的值而不是按字符串处理。你可以用它来设置
    字典和列表类型的值。在早期版本中，这个参数是 --as-dict。

示例

  1. 为指定站点启用测试。
bench --site {site} set-config allow_tests true
  1. 为所有站点启用测试。
bench --site all set-config allow_tests true

使用上面的命令，每个站点的 site_config.json 中都会有
键值对 "allow_tests": true。这样就可以在所有
站点上运行测试了。

bench set-config -g allow_tests true

使用上面的命令，bench 的 common_site_config.json 中会有
键值对 "allow_tests": true。这样 bench 上的每个站点都可以
运行测试，除非它们在 site_config.json 中为 sma 定义了
值。

  1. 在站点的 frappe.conf 中设置一个字典值
bench --site {site} set-config backup '{"includes": ["Not", "ToDo"]}' --parse

现在你可以在代码中通过 frappe.conf.backup.get("includes") 来访问这个列表。

查看配置

用法

bench show-config [OPTIONS]

说明

你站点的生效配置是由 bench 目录下的 common_site_config.json 和站点自身的 site_config.json 组合而成的。Bench 提供了一个界面，可以查看你站点当前生效的 frappe.conf 值。你可以选择以表格或 JSON 格式来查看这些信息。

想进一步了解站点配置以及键的优先级规则，请参阅这里的文档。

参数选项

  • -f、--format 选择列出指定站点上已安装应用的格式，可选值为 “text” 和 “json”。默认为 “text”。

示例

  1. 以 JSON 格式显示所有站点的配置。
bench --site all show-config -f json
  1. 以表格形式显示站点配置。
bench --site {site} show-config --format text

bench --site {site} show-config -f text

bench --site {site} show-config

卸载应用

用法

bench uninstall-app [OPTIONS] APP

说明

从站点中移除应用程序及其关联的文档类型和模块。执行
原生命令时，会先检查站点上是否存在该应用，然后再尝试删除
其模块和文档类型。运行 uninstall-app 命令时，该应用不一定
已安装在 bench 上。

选项

  • -y、--yes 跳过卸载应用的确认提示
  • --dry-run 列出所有将被删除的文档类型
  • --no-backup 不备份站点
  • --force 强制从站点移除该应用

示例

  1. 执行一次试运行，查看在特定站点上运行会发生什么。
bench --site {site} uninstall-app {app} --dry-run
  1. 在卸载应用操作之前不进行备份。
bench --site {site} uninstall-app {app} --no-backup
  1. 使用强制方式从站点卸载应用。
bench --site {site} uninstall-app {app} --force
  1. 跳过卸载确认的交互式提示。
bench --site {site} uninstall-app {app} --yes

基准应用列表

用法

bench list-apps [OPTIONS]

说明

列出指定站点上安装的所有 Frappe 应用。该命令显示的
信息来自 已安装应用
DocType，它记录了站点迁移到的最新应用版本。
全局默认值 installed_apps 用作回退。

多站点支持已在版本 13 中添加。要查看所有
站点的摘要，请将站点值设为 all 来运行该命令。

选项

  • --format、-f 选择列出指定站点上已安装应用的
    格式，可选值为“text”和“json”。默认值为“json”。

示例

  1. 列出所有站点上安装的应用。
bench --site all list-apps
  1. 以可解析的 JSON 格式列出所有站点上安装的应用。
bench --site all list-apps --format json
  1. 以文本格式列出特定站点上安装的应用。
bench --site {site} list-apps --format text

bench --site {site} list-apps -f text

bench --site {site} list-apps

工作台重新安装

用法

bench reinstall [OPTIONS]

描述

使用当前应用重新安装站点。这将清除所有站点数据并重新开始。
这被视为破坏性操作，因此默认包含交互式确认提示。

注意：此功能目前仅适用于 MariaDB 站点。将来，
可能会扩展以支持 PostgreSQL。

选项

  • --admin-password 重新安装站点的管理员密码
  • --mariadb-root-username MariaDB 的 root 用户名
  • --mariadb-root-password MariaDB 的 root 密码

标志

  • --yes 跳过重新安装的确认

示例

  1. 重新安装站点并跳过以下提示：
  • 操作确认
  • MariaDB Root 密码
  • 管理员密码
bench reinstall --site {site} --yes
--mariadb-root-password {db-pass}
--admin-password {admin-pass}
  1. 使用具有 DBMS SUPER 权限的替代用户重新安装站点。
bench reinstall
--mariadb-root-username {db-user}
--mariadb-root-password {db-pass}

工作台备份

用法

bench backup [OPTIONS]

说明

备份指定的站点。执行原生命令将创建数据库转储、压缩它，并将数据保存在默认备份位置 ./sites/{site}/private/backups 下。

如果已设置当前站点，只需运行 bench backup 命令即可备份该站点。

选项

  • --backup-path 设置本次操作中所有文件的保存路径
  • --backup-path-db 设置数据库文件的保存路径
  • --backup-path-conf 设置配置文件的保存路径
  • --backup-path-files 设置公共文件的保存路径
  • --backup-path-private-files 设置私有文件的保存路径
  • --exclude、-e 指定不备份的 DocType，用逗号分隔
  • --only、--include、-i 指定要备份的 DocType，用逗号分隔

标志

  • --ignore-backup-conf 忽略配置中设置的排除/包含项
  • --with-files 备份时包含私有和公共文件
  • --compress 压缩私有和公共文件
  • --verbose 增加详细输出

示例

  1. 备份站点的私有和公共文件。
bench --site {site} backup --with-files
  1. 压缩公共和私有文件（如需要）。这会将文件保存为 tgz 格式，而不是默认的 tar 格式。
bench --site {site} backup --with-files --compress
  1. 更改备份文件的保存路径。
bench --site {site} backup --backup-path {backup_path}
  1. 更改特定备份文件的路径。对于每个未指定的选项，相应文件将保存在默认位置。
bench --site {site} backup --with-files
   --backup-path-conf {conf_path}
   --backup-path-db {db_path}
   --backup-path-files {files_path}
   --backup-path-private-files {private_path}
  1. 为 Bench CLI 内部管理的各个阶段增加详细输出。
bench --site {site} backup --verbose
  1. 仅备份站点上的某些 DocType。
bench --site {site} backup --only 'ToDo,Note,Task,Project,Sales Invoice'
  1. 备份除某些 DocType 之外的所有表。
bench --site {site} backup --exclude 'Error Log,Access Log,Activity Log,Version'
  1. 备份整个站点，忽略已指定的 frappe.conf.backup.* 值。
bench --site {site} backup --ignore-backup-conf

如果备份过程失败（引发任何异常），文件将被删除，以避免占用额外的磁盘空间。