bench-commands

用途

Bench CLI 命令参考，提供 Frappe Bench 命令行界面的完整说明，用于管理 Frappe/ERPNext 安装。当需要运行 bench 命令进行开发、管理 Frappe 站点、安装和更新应用、运行迁移与构建、搭建生产环境或排查常见问题时，可参考本技能。

主要能力

站点管理

• 创建站点：bench new-site mysite.local，支持指定数据库名、MariaDB root 密码、管理员密码、从 SQL 文件创建、跳过默认用户等参数。
• 使用站点：bench use mysite.local 设置默认站点；bench --site mysite.local migrate 在指定站点运行命令；bench --site all migrate 在所有站点运行。
• 站点操作：列出所有站点、删除站点（支持强制）、设置维护模式、启用/禁用调度器。
• 备份与恢复：备份站点（可含文件）、备份所有站点、从备份恢复（可含私有/公共文件）。

应用管理

• 获取应用：从 GitHub 获取（支持指定分支或标签）、从本地路径获取、获取并安装到所有站点。
• 安装/卸载应用：在指定站点或所有站点安装应用；卸载应用（支持强制卸载并删除数据）。
• 创建新应用：bench new-app my_app，生成应用目录结构及 hooks.py、modules.txt、patches.txt、requirements.txt 等文件。
• 更新应用：bench update 更新所有应用，支持跳过迁移、指定应用、跳过拉取、跳过构建、重置为全新安装。
• 移除应用：从 bench 移除应用（需先从站点卸载）。

开发命令

• 启动开发服务器：bench start 启动 web、redis、调度器；bench serve 仅启动 web 服务器，可指定端口。
• 构建资源：bench build 构建 JS/CSS，支持指定应用、详细输出、生产构建、压缩、监听变更。
• 迁移：运行迁移，支持所有站点、指定应用、跳过失败补丁。
• 清除缓存：清除站点缓存、网站缓存、redis 缓存。
• 控制台：打开 Python 控制台、执行 Python 脚本（可带参数）、打开 MariaDB 控制台并运行 SQL 查询。
• 运行测试：运行所有测试、指定应用测试、指定模块测试、覆盖率、指定 DocType、并行测试、跳过测试设置。
• 翻译：更新、导出、导入翻译文件。

生产环境搭建

• 生产设置：sudo bench setup production frappe-user 配置 systemd、nginx、supervisor；可单独设置 supervisor、systemd、nginx、Redis、fail2ban。
• SSL/Let's Encrypt：设置 Let's Encrypt SSL、续期证书。
• 重启服务：重启 supervisor 全部或指定进程、重启 systemd 服务、查看状态。

调度器与工作进程

• 调度器：启用/禁用调度器、查看调度器状态、运行特定计划任务。
• 后台任务：显示排队任务、清除失败任务、运行指定队列（default/short/long）、清除任务。

配置

• 站点配置：显示站点配置、设置配置值（支持 JSON 值）、设置公共配置（所有站点）、移除配置。
• 常见配置项：site_config.json 中的数据库、加密密钥、开发者模式、维护模式、邮件服务器、限制等。
• Bench 配置：列出 bench 配置、设置 bench 配置（如端口、开发者模式、工作进程数）。

故障排查

• 日志：查看 frappe.log、web.error.log、worker.error.log、scheduler.error.log 及站点特定日志。
• 调试：检查站点健康、显示数据库大小、显示表大小、检查计划任务、重置密码、添加系统管理员。
• 修复常见问题：重建搜索索引、重置权限、清除锁、重装、部分恢复。

版本管理

• 检查版本、切换分支（如 version-14、develop）、设置 bench 版本。

多租户

• 启用 DNS 多租户、为站点添加/移除域名、设置通配符 SSL。

使用方式

通过命令行运行 bench 命令。常用工作流包括：

• 全新安装：安装 bench、初始化、获取 ERPNext、创建站点、安装 ERPNext、启动开发服务器。
• 日常开发：拉取最新变更、清除缓存、构建资源。
• 部署更新：在生产服务器上设置维护模式、备份、更新、迁移、构建生产资源、清除缓存、重启服务、关闭维护模式。

适用场景

适用于 Frappe/ERPNext 的站点管理、应用管理、开发调试、生产部署与运维、故障排查等场景。

限制

本资料为命令参考，未提供具体版本兼容性、性能数据或收费信息。部分命令参数可能因版本而异，请以实际环境为准。