Frappe Helpdesk 1.31 常用 CLI 命令与工具详解

目标：汇总 Frappe Helpdesk 运维中最常用的 bench CLI 命令，按「环境初始化 → 站点生命周期 → 应用管理 → 日常运维 → 配置管理」组织，每条命令附参数表（--help 原文）与实测回显。全部输出为 2026-10-23 在 Ubuntu 22.04.5（bench 5.31.0 / Frappe 15.124.0 / Helpdesk 1.31.0）环境实测的原始结果。部署上下文见《Frappe Helpdesk 1.31 Ubuntu 22.04 安装指南（bench 手工部署）》。

一、环境信息

项目	实测值
bench CLI	5.31.0（`pip3 install frappe-bench`）
Frappe Framework	15.124.0（version-15 分支）
Helpdesk / telephony	1.31.0 / 0.0.1
示例站点	`hd.local`（示例密码统一 `q1w2e3r4`）
工作目录	`/home/frappe/frappe-bench`（下文所有命令默认在该目录执行）

bench 命令分两层：直接子命令（init、start、config 等，作用于 bench 目录本身）与「站点级命令」（bench --site <站点名> <命令>，作用于具体站点）。bench --site hd.local use 执行过一次后，默认站点被记住，站点级命令可省略 --site 前缀。

二、命令总览

bench --help 实测全文（146 行，分两部分照录）：

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

Options:
  --version
  --use-feature TEXT
  -v, --verbose
  --help              Show this message and exit.

Commands:
  app-cache                View or remove items belonging to bench...
  backup-all-sites         Backup all sites in current bench
  completions              Install shell completion for bench (bash or zsh).
  config                   Change bench configuration
  disable-production       Disables production environment for the bench.
  download-translations    Download latest translations
  drop
  exclude-app              Exclude app from updating
  find                     Finds benches recursively from location
  get                      Clone an app from the internet or filesystem...
  get-app                  Clone an app from the internet or filesystem...
  include-app              Include app for updating
  init                     Initialize a new bench instance in the...
  install                  Install system dependencies for setting up...
  migrate-env              Migrate Virtual Environment to desired Python...
  new-app                  Create a new Frappe application under apps folder
  pip                      For pip help use `bench pip help [COMMAND]` or...
  remote-reset-url         Reset app remote url to frappe official
  remote-set-url           Set app remote url
  remote-urls              Show apps remote url
  remove                   Completely remove app from bench and re-build...
  remove-app               Completely remove app from bench and re-build...
  renew-lets-encrypt       Sets Up latest cron and Renew Let's Encrypt...
  restart                  Restart supervisor processes or systemd units
  retry-upgrade            Retry a failed upgrade
  rm                       Completely remove app from bench and re-build...
  set-mariadb-host         Set MariaDB host for bench
  set-nginx-port           Set NGINX port for site
  set-redis-cache-host     Set Redis cache host for bench
  set-redis-queue-host     Set Redis queue host for bench
  set-redis-socketio-host  Set Redis socketio host for bench
  set-ssl-certificate      Set SSL certificate path for site
  set-ssl-key              Set SSL certificate private key path for site
  set-url-root             Set URL root for site
  setup                    Setup command group for enabling setting up a...
  socketio                 Run the realtime (socketio) server.
  src                      Prints bench source folder path, which can be...
  start                    Start Frappe development processes
  switch-to-branch         Switch all apps to specified branch, or...
  switch-to-develop        Switch frappe and erpnext to develop branch
  update                   Performs an update operation on current bench.
  validate-dependencies    Validates that all requirements specified in...

框架层命令（同样通过 bench 入口调用，节选运维常用）：

Framework commands:

  add-system-manager          Add a new system manager to a site
  add-to-hosts                Add site to hosts
  backup                      Backup
  browse                      Opens the site on web browser
  build                       Compile JS and CSS source files
  clear-cache                 Clear cache, doctype cache and defaults
  console                     Start ipython console for a site
  db-console                  Enter into the Database console for given...
  disable-scheduler           Disable scheduler
  doctor                      Get diagnostic info about background workers
  drop-site                   Remove a site from database and filesystem.
  enable-scheduler            Enable scheduler
  execute                     Execute a function
  install-app                 Install a new app to site, supports...
  list-apps                   List apps in site.
  mariadb                     Enter into mariadb console for a given site.
  migrate                     Run patches, sync schema and rebuild...
  new-site                    Create a new site
  reinstall                   Reinstall site ie.
  restore                     Restore site database from an sql file
  scheduler                   Control scheduler state.
  serve                       Start development web server
  set-admin-password          Set Administrator password for a site
  set-config                  Insert/Update a value in site_config.json
  set-maintenance-mode        Put the site in maintenance mode for upgrades.
  show-config                 Print configuration file to STDOUT in...
  show-pending-jobs           Get diagnostic info about background jobs
  uninstall-app               Remove app and linked modules from site
  use                         Set a default site
  version                     Show the versions of all the installed apps.
  worker                      Start a background worker

完整清单以 bench --help 实际输出为准（上两段为原文节选，未删减条目顺序）。

三、环境初始化命令

3.1 bench init（初始化 bench）

Usage: bench init [OPTIONS] PATH

  Initialize a new bench instance in the specified path

Options:
  --version, --frappe-branch TEXT
                                  Clone a particular branch of frappe
  --ignore-exist                  Ignore if Bench instance exists.
  --python TEXT                   Path to Python Executable.
  --apps_path TEXT                path to json files with apps to install
                                  after init
  --frappe-path TEXT              path to frappe repo
  --clone-from TEXT               copy repos from path
  --clone-without-update          copy repos from path without update
  --no-procfile                   Do not create a Procfile
  --no-backups                    Do not set up automatic periodic backups for
                                  all sites on this bench
  --skip-redis-config-generation  Skip redis config generation if already
                                  specifying the common-site-config file
  --skip-assets                   Do not build assets
  --install-app TEXT              Install particular app after initialization
  --verbose                       Verbose output during install
  --dev                           Enable developer mode and install
                                  development dependencies.
  --help                          Show this message and exit.

实测用法（成功末尾回显 SUCCESS: Bench frappe-bench initialized）：

bench init frappe-bench --frappe-branch version-15

常用变体：--install-app helpdesk 在初始化后立即安装应用；--clone-from 从本机既有 bench 拷贝仓库加速离线部署。

3.2 bench new-site（创建站点）

Usage: bench  new-site [OPTIONS] SITE

  Create a new site

Options:
  --db-name TEXT                  Database name
  --db-password TEXT              Database password
  --db-type [mariadb|postgres]    Optional "postgres" or "mariadb". Default is
                                  "mariadb"
  --db-host TEXT                  Database Host
  --db-port INTEGER               Database Port
  --db-root-username, --mariadb-root-username TEXT
                                  Root username for MariaDB or PostgreSQL,
                                  Default is "root"
  --db-root-password, --mariadb-root-password TEXT
                                  Root password for MariaDB or PostgreSQL
  --db-socket, --mariadb-db-socket TEXT
                                  Database socket for MariaDB or folder
                                  containing database socket for PostgreSQL
  --no-mariadb-socket             DEPRECATED: Set MariaDB host to % and use
                                  TCP/IP Socket instead of using the UNIX
                                  Socket
  --mariadb-user-host-login-scope TEXT
                                  Set the mariadb host for the user login
                                  scope if you don't want to use the current
                                  host as login scope which typically is
                                  ''@'localhost' - may be used when
                                  initializing a user on a remote host. See
                                  the mariadb docs on account names for more
                                  info.
  --admin-password TEXT           Administrator password for new site
  --verbose                       Verbose

实测用法与回显（末段）：

bench new-site hd.local --mariadb-root-password q1w2e3r4 --admin-password q1w2e3r4

Installing frappe...
Updating DocTypes for frappe        : [========================================] 100%
Updating Dashboard for frappe
*** Scheduler is disabled ***

新站点默认停用调度器，随即 bench --site hd.local enable-scheduler 打开。

3.3 bench use（设置默认站点）

Usage: bench  use [OPTIONS] SITE

  Set a default site

Options:
  --help  Show this message and exit.

bench use hd.local   # 之后站点级命令可省略 --site hd.local

3.4 bench drop-site（删除站点）

Usage: bench  drop-site [OPTIONS] SITE

  Remove a site from database and filesystem.

Options:
  --db-root-username, --mariadb-root-username, --root-login TEXT
                                  Root username for MariaDB or PostgreSQL,
                                  Default is "root"
  --db-root-password, --mariadb-root-password, --root-password TEXT
                                  Root password for MariaDB or PostgreSQL
  --archived-sites-path TEXT
  --no-backup
  --force                         Force drop-site even if an error is
                                  encountered
  --help                          Show this message and exit.

实测用法（⚠️ 管道输入确认时必须显式传 root 密码，否则密码提示会吃掉管道内容报 1045 拒绝）：

echo y | bench drop-site hd.local --no-backup --db-root-password q1w2e3r4

Dropping site database and user
Moving site to archive under /home/frappe/frappe-bench/archived/sites

四、应用管理命令

4.1 bench get-app（拉取应用）

Usage: bench get-app [OPTIONS] [NAME]... GIT_URL

  Clone an app from the internet or filesystem and set it up in your bench

Options:
  --branch TEXT         branch to checkout
  --overwrite
  --skip-assets         Do not build assets
  --soft-link           Create a soft link to git repo instead of clone.
  --init-bench          Initialize Bench if not in one
  --resolve-deps        Resolve dependencies before installing app
  --cache-key TEXT      Caches get-app artifacts if provided (only first 10
                        chars is used)
  --compress-artifacts  Whether to gzip get-app artifacts that are to be
                        cached
  --help                Show this message and exit.

实测用法（Helpdesk 1.31.0 与其声明的 telephony 依赖）：

bench get-app https://github.com/frappe/telephony
# Done in 4.74s.
# Compiling translations for telephony
bench get-app https://github.com/frappe/helpdesk --branch v1.31.0

4.2 bench install-app（安装到站点）

Usage: bench  install-app [OPTIONS] [APPS]...

  Install a new app to site, supports multiple apps

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

bench --site hd.local install-app helpdesk
# Updating Dashboard for helpdesk
# []

4.3 bench build（构建前端资源）

Usage: bench  build [OPTIONS]

  Compile JS and CSS source files

Options:
  --app TEXT        Build assets for app
  --apps TEXT       Build assets for specific apps
  --hard-link       Copy the files instead of symlinking
  --production      Build assets in production mode
  --verbose         Verbose
  --force           Force build assets instead of downloading available
  --save-metafiles  Saves esbuild metafiles for built assets. Useful for
                    analyzing bundle size. More info:
                    https://esbuild.github.io/api/#metafile
  --help            Show this message and exit.

bench build --app helpdesk   # 实测 32 秒完成，末尾输出各语言 MO 文件清单

4.4 bench list-apps / bench version（版本核对）

bench --site hd.local list-apps

frappe    15.124.0 version-15
telephony 0.0.1    develop
helpdesk  1.31.0   HEAD

bench version
# frappe 15.124.0
# helpdesk 1.31.0
# telephony 0.0.1

两者差异：list-apps 带分支信息（站点安装视角），bench version 仅版本号（bench 目录视角），升级后核对建议两个都跑。

五、日常运维命令

5.1 bench start（开发模式进程组）

Usage: bench start [OPTIONS]

  Start Frappe development processes

Options:
  --no-dev
  --no-prefix             Hide process name from bench start log
  -c, --concurrency TEXT
  -p, --procfile TEXT
  -m, --man TEXT          Process Manager of your choice ;)
  --help                  Show this message and exit.

按 Procfile 拉起 redis_cache、redis_queue、web、socketio、watch、schedule、worker 七类进程（honcho 管理）。仅用于开发调试，生产用 supervisor/systemd 托管。

5.2 bench doctor（后台任务诊断）

Usage: bench  doctor [OPTIONS]

  Get diagnostic info about background workers

Options:
  --site TEXT  site name
  --help       Show this message and exit.

实测回显（调度器已启用、worker 在线时）：

-----Checking scheduler status-----
Workers online: 1
-----None Jobs-----

若站点调度器未开启，输出会多出 Scheduler disabled for <站点名> 两行提示。

5.3 bench backup（备份）

Usage: bench  backup [OPTIONS]

  Backup

Options:
  --with-files                    Take backup with files
  -i, --include, --only TEXT      Specify the DocTypes to backup seperated by
                                  commas
  -e, --exclude TEXT              Specify the DocTypes to not backup seperated
                                  by commas
  --backup-path TEXT              Set path for saving all the files in this
                                  operation
  --backup-path-db TEXT           Set path for saving database file
  --backup-path-files TEXT        Set path for saving public file
  --backup-path-private-files TEXT
                                  Set path for saving private file
  --backup-path-conf TEXT         Set path for saving config file
  --ignore-backup-conf            Ignore excludes/includes set in config
  --verbose                       Add verbosity
  --compress                      Compress private and public files
  --old-backup-metadata           Use older backup metadata
  --help                          Show this message and exit.

实测用法与回显（四件套：配置/数据库/公共文件/私有文件）：

bench --site hd.local backup --with-files

Backup Summary for hd.local at 2026-10-23 11:59:12.509461
Config  : ./hd.local/private/backups/20261023_115912-hd_local-site_config_backup.json 118.0B
Database: ./hd.local/private/backups/20261023_115912-hd_local-database.sql.gz         277.0KiB
Public  : ./hd.local/private/backups/20261023_115912-hd_local-files.tar               10.0KiB
Private : ./hd.local/private/backups/20261023_115912-hd_local-private-files.tar       10.0KiB
Backup for Site hd.local has been successfully completed with files

产物落在 sites/<站点名>/private/backups/ 下，文件名前缀即时间戳（YYYYMMDD_HHMMSS）。

5.4 bench restore（恢复）

Usage: bench  restore [OPTIONS] SQL_FILE_PATH

  Restore site database from an sql file

Options:
  --db-root-username, --mariadb-root-username TEXT
                                  Root username for MariaDB or PostgreSQL,
                                  Default is "root"
  --db-root-password, --mariadb-root-password TEXT
                                  Root password for MariaDB or PostgreSQL
  --db-name TEXT                  Database name for site in case it is a new
                                  one
  --admin-password TEXT           Administrator password for new site
  --install-app TEXT              Install app after installation
  --with-public-files TEXT        Restores the public files of the site, given
                                  path to its tar file
  --with-private-files TEXT       Restores the private files of the site, given
                                  path to its tar file
  --force                         Ignore the validations and downgrade
                                  warnings. This action is not recommended
  --encryption-key TEXT           Backup encryption key
  --help                          Show this message and exit.

实测用法（完整恢复闭环已在部署篇 10.1 节验证通过，恢复成功末行 Site hd.example.com has been restored with files）：

bench --site hd.local restore /path/to/backup-database.sql.gz \
  --db-root-password q1w2e3r4 \
  --with-public-files /path/to/backup-files.tar \
  --with-private-files /path/to/backup-private-files.tar

⚠️ 不传 --db-root-password 时命令会交互式询问 MySQL root password:，脚本场景直接挂住；带附件恢复需 --with-public-files / --with-private-files 成对传入。

5.5 bench migrate（补丁与结构同步）

Usage: bench  migrate [OPTIONS]

  Run patches, sync schema and rebuild files/translations

Options:
  --skip-failing       Skip patches that fail to run
  --skip-search-index  Skip search indexing for web documents
  --help               Show this message and exit.

bench --site hd.local migrate

升级应用、切换分支、恢复旧备份之后都应执行一次。

5.6 bench update（bench 整体升级）

Usage: bench update [OPTIONS]

  Performs an update operation on current bench. Without any flags will
  backup, pull, setup requirements, build, run patches and restart bench.
  Using specific flags will only do certain tasks instead of all

Options:
  --pull                Pull updates for all the apps in bench
  --apps TEXT
  --patch               Run migrations for all sites in the bench
  --build               Build JS and CSS assets for the bench
  --requirements        Update requirements. If run alone, equivalent to
                        `bench setup requirements`
  --restart-supervisor  Restart supervisor processes after update
  --restart-systemd     Restart systemd units after update
  --no-backup           If this flag is set, sites won't be backed up prior to
                        updates. Note: This is not recommended in production.
  --no-compile          [DEPRECATED] This flag doesn't do anything now.
  --force               Forces major version upgrades
  --reset               Hard resets git branch's to their new states
                        overriding any changes and overriding rebase on pull
  --help                Show this message and exit.

生产升级标准姿势：bench update（自动先备份各站点）→ 按配置联动重启（restart_supervisor_on_update 置 true 时）。

5.7 调度器与缓存

bench --site hd.local enable-scheduler
# Enabled for hd.local
bench --site hd.local disable-scheduler
bench --site hd.local clear-cache
bench --site hd.local show-pending-jobs

六、配置管理命令

6.1 bench set-config / show-config

Usage: bench  set-config [OPTIONS] KEY VALUE

  Insert/Update a value in site_config.json

Options:
  -g, --global  Set value in bench config
  -p, --parse   Evaluate as Python Object
  --help        Show this message and exit.

实测往返（详见本专栏配置详解篇第二章）：

bench --site hd.local set-config maintenance_mode 1
#  "maintenance_mode": 1      ← 写入站点 site_config.json
bench --site hd.local set-config maintenance_mode 0
bench set-config -g redis_cache redis://127.0.0.1:13000   # -g 写公共配置
bench --site hd.local set-config -p demo_ports "[8000, 8080]"   # -p 写数组
bench --site hd.local show-config   # 合并视图表格输出

6.2 密码与维护快捷命令

bench --site hd.local set-admin-password 新密码      # 重置 Administrator 密码
bench --site hd.local set-password --user <用户>      # 重置普通用户密码
bench --site hd.local set-maintenance-mode on|off

6.3 交互式工具

bench --site hd.local console     # 站点上下文 ipython
bench --site hd.local mariadb     # 直连站点数据库
bench --site hd.local execute frappe.db.count --args "[\"HD Ticket\"]"
# 2                                ← execute 任意服务端函数，实测计数工单
bench --site hd.local browse      # 用系统浏览器打开站点

execute 是最常用的诊断入口：无需写代码即可调用任意框架函数（上例统计 HD Ticket 数量，实测返回 2）。

七、参考链接

bench 官方命令速查表：https://frappeframework.com/docs/user/en/bench/resources/bench-commands-cheatsheet
bench 官方仓库（frappe/bench）：https://github.com/frappe/bench
Helpdesk 官方文档：https://docs.frappe.io/helpdesk
配置文件逐键详解：本专栏《Frappe Helpdesk 1.31 配置参数详解》
bench 手工安装与生产托管：本专栏《Frappe Helpdesk 1.31 Ubuntu 22.04 安装指南（bench 手工部署）》
备份恢复闭环实测：本专栏《Frappe Helpdesk 1.31 Docker Compose 部署指南》第十章
产品定位与选型对比：[《Frappe Helpdesk 1.31 介绍与选型指南》](https://www.quzuo.net/document/xtxb3uZrBRAB)