分类： 工作台 – 参考

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

2. 以表格形式显示站点配置。

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

2. 跳过卸载确认的交互式提示。

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

2. 压缩公共和私有文件（如需要）。这会将文件保存为 tgz 格式，而不是默认的 tar 格式。

bench --site {site} backup --with-files --compress

3. 更改备份文件的保存路径。

bench --site {site} backup --backup-path {backup_path}

4. 更改特定备份文件的路径。对于每个未指定的选项，相应文件将保存在默认位置。

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}

5. 为 Bench CLI 内部管理的各个阶段增加详细输出。

bench --site {site} backup --verbose

6. 仅备份站点上的某些 DocType。

bench --site {site} backup --only 'ToDo,Note,Task,Project,Sales Invoice'

7. 备份除某些 DocType 之外的所有表。

bench --site {site} backup --exclude 'Error Log,Access Log,Activity Log,Version'

8. 备份整个站点，忽略已指定的 frappe.conf.backup.* 值。

bench --site {site} backup --ignore-backup-conf

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

用法

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}