Frappe Helpdesk 1.31 Ubuntu 22.04 安装指南（bench 手工部署）

目标：在一台 Ubuntu 22.04 服务器上，通过 bench 手工路径完整安装 Frappe Helpdesk 1.31.0，覆盖系统依赖、MariaDB/Redis 版本准备、bench 初始化、站点创建、应用安装、前端构建、开发启动、生产托管（supervisor + nginx）、验证与卸载全流程。文中所有命令与回显均为 2026-10-23 在 Ubuntu 22.04.5 LTS 环境实测的原始输出，未做美化。产品定位与技术架构见[《Frappe Helpdesk 1.31 介绍与选型指南》](https://www.quzuo.net/document/xtxb3uZrBRAB)。

一、环境信息

本篇实测环境与各组件版本如下，全部为实查值（cat /etc/os-release、--version、bench version 等原始回显）：

项目	实测值
操作系统	Ubuntu 22.04.5 LTS（`PRETTY_NAME="Ubuntu 22.04.5 LTS"`）
Python	3.10.12（系统自带）
Node.js	v20.20.2（NodeSource 20.x 源）
npm	10.8.2
yarn	1.22.22（经典 1.x）
MariaDB	10.6.23（Ubuntu 22.04 仓库自带版本）
Redis	8.10.2（packages.redis.io 升级后）
bench	5.31.0（pip 安装 frappe-bench）
Frappe Framework	15.124.0（version-15 分支）
Frappe Helpdesk	1.31.0（v1.31.0 标签）
telephony	0.0.1（develop 分支，Helpdesk 声明式依赖）
supervisor	4.2.1（生产托管用）
nginx	1.18.0（生产托管用）

数据库root密码、站点管理员密码在下文示例中统一使用 q1w2e3r4（生产环境请替换为自己的强密码）。

二、前置条件

2.1 系统依赖包

Frappe 官方安装文档（frappeframework.com/docs/user/en/installation）对 Ubuntu 列出的基础依赖如下，一次装齐：

sudo apt-get update
sudo apt-get install -y build-essential python3-dev python3-venv python3-pip \
    libmariadb-dev pkg-config libffi-dev git cron

实测说明（⚠️ 排障重点）：cron 包必须安装。Ubuntu 22.04 最小安装默认不带 /usr/bin/crontab，而 bench 初始化过程会调用它，缺失时在 bench init 末尾直接报 FileNotFoundError: [Errno 2] No such file or directory: '/usr/bin/crontab'（详见第九章 9.2）。

2.2 Node.js 20 与 yarn

Frappe v15 官方要求 Node.js 18+，实测安装 NodeSource 20.x 线并配 yarn 经典版：

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
sudo npm install -g yarn

验证回显：

node --version
# v20.20.2
npm --version
# 10.8.2
yarn --version
# 1.22.22

2.3 MariaDB 10.6 与字符集配置

安装并启动 MariaDB（Ubuntu 22.04 仓库自带 10.6.23，满足 Frappe v15 的 10.6+ 要求）：

sudo apt-get install -y mariadb-server
sudo service mariadb start

实测回显：

 * Starting MariaDB database server mariadbd
   ...done.

mysqladmin --version
# mysqladmin  Ver 10.0 Distrib 10.6.23-MariaDB, for debian-linux-gnu on x86_64

为 root 账户设置密码（示例密码 q1w2e3r4）：

sudo mysql -e "ALTER USER 'root'@'localhost' IDENTIFIED BY 'q1w2e3r4'; FLUSH PRIVILEGES;"
mysql -uroot -pq1w2e3r4 -e "SELECT VERSION();"

实测回显（-p 后紧跟密码的写法会触发一次安全提示，输出中已略去）：

VERSION()
10.6.23-MariaDB-0ubuntu0.22.04.1

按 Frappe 官方文档要求写入字符集配置，新建 /etc/mysql/mariadb.conf.d/99-frappe.cnf：

[mysqld]
character-set-client-handshake = FALSE
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci

[mysql]
default-character-set = utf8mb4

重启生效（⚠️ 实测坑：Ubuntu 22.04 上 service mariadb restart 停止阶段会报 ...fail! 但服务实际尚未重载配置，属假象；正确做法是先 shutdown 再 start）：

sudo mysqladmin -uroot -pq1w2e3r4 shutdown
sudo service mariadb start
mysql -uroot -pq1w2e3r4 -e "SHOW VARIABLES LIKE 'character_set_server'; SHOW VARIABLES LIKE 'collation_server';"

实测回显：

character_set_server    utf8mb4
collation_server        utf8mb4_unicode_ci

2.4 Redis 升级（6.0 → 8.x 实录）

Ubuntu 22.04 仓库自带的 Redis 是 6.0.16，低于 Frappe v15 官方要求的 6.2+，必须先升级再初始化 bench。实测过程如下。

先确认自带版本：

redis-server --version
# Redis server v=6.0.16 sha=00000000:0 malloc=jemalloc-5.2.1 bits=64 build=d6ed09173b889769

添加官方 packages.redis.io 仓库并升级：

curl -fsSL https://packages.redis.io/gpg | sudo gpg --dearmor -o /usr/share/keyrings/redis-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/redis-archive-keyring.gpg] https://packages.redis.io/deb jammy main" | sudo tee /etc/apt/sources.list.d/redis.list
sudo apt-get update
sudo apt-get install -y redis
redis-server --version

实测回显（apt-get install 末段）：

Setting up redis (6:8.10.2-1rl1~jammy1) ...
Redis server v=8.10.2 sha=00000000:1 malloc=jemalloc-5.3.0 bits=64 build=accb23a4692c1fdb

⚠️ 排障实录：常规做法用 $(lsb_release -cs) 自动取发行版代号，但最小安装可能没有 lsb_release 命令，会生成一条空 Component 的源导致 apt-get update 报 E: Malformed entry 1 in list file /etc/apt/sources.list.d/redis.list (Component)。解决方式就是上例中的写死 jammy（Ubuntu 22.04 的代号）。

2.5 专用用户与目录规划

bench 出于安全考虑拒绝以 root 运行，为部署创建专用用户：

sudo adduser --disabled-password --gecos "Frappe" frappe
id frappe

实测回显：

uid=1000(frappe) gid=1000(frappe) groups=1000(frappe)

后续所有 bench 操作都以 frappe 身份执行，bench 目录规划为 /home/frappe/frappe-bench（bench 默认命名）。

三、版本选型

选型依据全部来自官方仓库实查（查询日期 2026-10-23）：

组件	选定版本	依据
Frappe Helpdesk	v1.31.0	GitHub Releases 最新稳定版（2026-10-14 发布）
Frappe Framework	version-15 分支（15.124.0）	Helpdesk `pyproject.toml` 声明 `frappe >=15.123.1,<17.0.0`，v15/v16 均兼容；v15 为当前长期主线
telephony	develop（0.0.1）	Helpdesk `pyproject.toml` 的 frappe-dependencies 强制依赖 `telephony >=0.0.1,<1.0.0`，`bench get-app` 默认拉 develop 分支
MariaDB	10.6.23	Frappe v15 官方安装文档要求 10.6+
Redis	8.10.2	官方要求 6.2+，取仓库最新稳定
Node.js	20.20.2	官方要求 18+，取 20.x LTS 线

两个 Python 硬门槛（pyproject.toml 实查）：requires-python >= 3.10（Ubuntu 22.04 自带 3.10.12 正好满足）；核心依赖仅 textblob，复杂性都在框架依赖链上。

四、方案 A：bench 手工部署

4.1 安装 bench CLI

sudo pip3 install frappe-bench
bench --version

实测回显：

Successfully installed MarkupSafe-3.0.4 certifi-2026.10.19 charset_normalizer-3.5.2 click-8.2.1 frappe-bench-5.31.0 gitdb-4.0.12 gitpython-3.1.62 honcho-2.0.0 idna-3.20 jinja2-3.1.6 python-crontab-2.6.0 python-dateutil-3.0.0 requests-2.33.1 semantic-version-2.10.0 setuptools-81.0.0 six-1.17.0 smmap-5.0.3 tomli-2.5.0 tzdata-2026.5 urllib3-2.8.0 uv-0.11.33
# pip 以 root 运行时会附带一条 WARNING 提示，不影响使用
bench --version
# 5.31.0

4.2 初始化 bench

切换到 frappe 用户执行初始化，--frappe-branch version-15 指定框架分支：

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

成功末尾回显：

MO file created at /home/frappe/frappe-bench/sites/assets/locale/hi/LC_MESSAGES/frappe.mo
...
SUCCESS: Bench frappe-bench initialized

实测耗时：网络通畅、uv/pip 缓存预热后约 21 秒；冷启动（首次拉取 frappe 仓库 + 全量装 Python/Node 依赖）约 1–3 分钟，取决于带宽。

⚠️ 排障实录一（GitHub 访问受限）：bench init 第一步会 git ls-remote https://github.com/frappe/frappe.git 校验分支，若服务器直连 GitHub 失败会报：

git.exc.GitCommandError: Cmd('git') failed due to: exit code(128)
  cmdline: git ls-remote --heads --tags https://github.com/frappe/frappe.git version-15
  stderr: 'fatal: unable to access 'https://github.com/frappe/frappe.git/': Failed to connect to github.com port 443 after 21039 ms: Connection refused'
bench.exceptions.InvalidRemoteException: Invalid frappe path: https://github.com/frappe/frappe.git

解决：给当前会话配置 HTTP 代理后重跑（代理地址按自身网络填写）：

export http_proxy=http://<代理地址:端口> https_proxy=http://<代理地址:端口>

⚠️ 排障实录二（缺 crontab）：初始化在编译完前端资产后报 FileNotFoundError: ... '/usr/bin/crontab' 并回滚询问 Do you want to rollback these changes? [y/N]。按 2.1 节补装 cron 包后重跑即可；重跑前建议清理半成品目录 rm -rf /home/frappe/frappe-bench。

⚠️ 排障实录三（缺 tzdata）：若系统没有 /usr/share/zoneinfo，初始化站点阶段会报 zoneinfo._common.ZoneInfoNotFoundError: 'No time zone found with key Asia/Kolkata'（Frappe 默认时区），sudo apt-get install -y tzdata 后重跑。

初始化完成后确认目录与框架版本：

ls frappe-bench
# Procfile  apps  config  env  logs  patches.txt  sites
grep -m1 __version__ frappe-bench/apps/frappe/frappe/__init__.py
# __version__ = "15.124.0"

4.3 创建站点

cd frappe-bench
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 自动生成（写入 sites/hd.local/site_config.json，键为 db_name/db_password，详见本专栏《Frappe Helpdesk 1.31 配置参数详解》）。*** Scheduler is disabled *** 是新站点默认状态，稍后用 enable-scheduler 打开。

4.4 获取 Helpdesk 应用及其依赖

telephony 是 Helpdesk 在 pyproject.toml 中声明的依赖，先装它：

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

实测回显（末段）：

MO file created at /home/frappe/frappe-bench/sites/assets/locale/ko/LC_MESSAGES/helpdesk.mo
...

完成后 apps/ 下共有三个应用：

ls apps
# frappe  helpdesk  telephony

4.5 在站点上安装应用

bench --site hd.local install-app helpdesk

实测回显（末段）：

Updating Dashboard for helpdesk
[]

4.6 构建前端资源

bench build --app helpdesk

实测耗时 32 秒，末段回显（编译产物与多语言 MO 文件）：

MO file already up to date at /home/frappe/frappe-bench/sites/assets/locale/bs/LC_MESSAGES/helpdesk.mo
MO file already up to date at /home/frappe/frappe-bench/sites/assets/locale/es/LC_MESSAGES/helpdesk.mo

⚠️ 若构建阶段见到 WARN Cannot connect to redis_cache to update assets_json，是因为 bench 自带的 Redis 实例（端口 13000/11000）尚未启动——bench start 或 supervisor 托管后即消失，不影响构建结果。

4.7 开发模式启动与验证

bench start

Procfile 各进程拉起后回显（节选）：

06:10:43 web.1         |  * Debugger PIN: 881-258-914
06:10:44 watch.1       | Browserslist: caniuse-lite is outdated. Please run:
06:10:49 watch.1       | Watching for changes...

⚠️ 高频坑：直接 curl http://localhost:8000 会得到 404。 bench 默认开启多站点，按 Host 头路由，localhost 不是任何站点名。实测对照：

curl -s http://localhost:8000/api/method/ping
# <!doctype html>
# <html lang=en>
# <title>404 Not Found</title>
# <h1>Not Found</h1>
# <p>localhost does not exist</p>

带上站点 Host 头即为正确姿势（或按 4.8 节把站点写进 /etc/hosts 后直接用域名访问）：

curl -s -H "Host: hd.local" http://localhost:8000/api/method/ping
# {"message":"pong"}
curl -s -o /dev/null -w "%{http_code}\n" -H "Host: hd.local" http://localhost:8000/helpdesk
# 200

登录接口实测（管理员账号 Administrator，密码为 new-site 时设置的 q1w2e3r4）：

curl -s -H "Host: hd.local" -d "usr=Administrator&pwd=q1w2e3r4" http://localhost:8000/api/method/login
# {"message":"Logged In","home_page":"/helpdesk","full_name":"Administrator"}

4.8 站点域名解析与调度器

add-to-hosts 需要 root 权限写 /etc/hosts（以 frappe 用户执行若无 sudo 会报 /bin/sh: 1: sudo: not found），两种等价方式任选其一：

bench --site hd.local add-to-hosts        # 有 sudo 的环境
# 或由 root 直接写：
echo "127.0.0.1 hd.local" | sudo tee -a /etc/hosts

开启调度器并复检：

bench --site hd.local enable-scheduler
# Enabled for hd.local
bench doctor

实测回显：

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

浏览器打开 http://hd.local:8000/helpdesk 即坐席端（Agent Portal），用 Administrator / q1w2e3r4 登录。实测 curl -s -o /dev/null -w "%{http_code}" http://hd.local:8000/helpdesk 返回 200。

五、方案 B：既有 bench 增量安装

已经有一个运行中的 bench 环境时（例如已有 ERPNext 站点），不需要重建，增量三步即可。以下命令在 /home/frappe/frappe-bench 内执行：

# 1. 拉取应用（含依赖 telephony）
bench get-app https://github.com/frappe/helpdesk --branch v1.31.0

# 2. 安装到目标站点
bench --site <目标站点名> install-app helpdesk

# 3. 构建前端资源
bench build --app helpdesk

get-app 与 install-app、build 的实测回显与方案 A 的 4.4–4.6 节完全一致（同一环境同一路径）。增量安装完成后执行 bench --site <目标站点名> migrate 校验补丁，再按第六章托管方式重启服务进程即可。

多应用共存提示：同一站点可同时安装多个 Frappe 应用，bench --site <站点> list-apps 实测输出：

frappe    15.124.0 version-15
telephony 0.0.1    develop
helpdesk  1.31.0   HEAD

六、方案对比与选择建议

维度	方案 A：bench 手工部署（本篇）	方案 B：既有 bench 增量安装	Docker Compose 编排（见本专栏部署篇）
适用场景	全新服务器、要完全掌控每层依赖	已有 Frappe 生态，追加客服工单能力	快速落地、环境一致性好
依赖控制	逐层手工安装，版本完全自选	复用既有依赖链	由官方编排文件固定
升级方式	`bench update`（git 拉新 + migrate）	同左，仅新增应用	换编排版本重建
上手成本	最高（本篇全流程实测约 30–60 分钟）	最低（三步）	中等
生产托管	supervisor + nginx（第七章）	沿用既有托管	编排自带

选型建议：需要二次开发、深度定制或与其他 Frappe 应用同站点共存的团队选 bench 路径；只想快速上线客服工单、不碰框架层的团队优先 Docker Compose 编排（含持久化与备份恢复闭环，见本专栏部署篇）。

七、生产环境托管（supervisor + nginx）

开发模式的 bench start 不适用于生产（单进程 web、无自动重启）。Frappe 官方托管方案 = supervisor 管进程 + nginx 反代。

7.1 一键命令的实测结论

sudo apt-get install -y supervisor nginx sudo
supervisord --version
# 4.2.1（会附带一条 pkg_resources 弃用 WARNING，可忽略）
nginx -v
# nginx version: nginx/1.18.0 (Ubuntu)

官方推荐的 bench setup production frappe 一键命令在 bench 5.31.0 实测会先安装 ansible 再执行 fail2ban 角色，本环境实测该角色执行失败终止：

fatal: [localhost]: FAILED! => { ... }
PLAY RECAP *********************************************************************
localhost                  : ok=6    changed=3    unreachable=0    failed=1    skipped=1    rescued=0    ignored=0
ERROR: Command '['ansible-playbook', '-c', 'local', 'site.yml', ... '-t', 'fail2ban']' returned non-zero exit status 2.

因此生产落地建议按 7.2/7.3 的拆分手工路径执行（生成配置 → 手工安装到系统目录 → 启动），这也是排障时最可控的方式。

7.2 supervisor 托管

bench 5.31.0 中该命令不再接受用户名参数（bench setup supervisor frappe 会报 Error: Got unexpected extra argument (frappe)），直接执行即可，配置写到 bench 的 config/supervisor.conf：

cd /home/frappe/frappe-bench
bench setup supervisor --yes

⚠️ 细节坑：以 root 身份执行会把配置里的 user= 写成 root；正确姿势是以 frappe 用户身份生成（grep -m1 '^user=' config/supervisor.conf 应显示 user=frappe），再用 sudo 拷贝安装：

sudo cp config/supervisor.conf /etc/supervisor/conf.d/frappe-bench.conf
sudo service supervisor start
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl status

实测 supervisorctl status 回显（7 个进程全部 RUNNING）：

frappe-bench-redis:frappe-bench-redis-cache               RUNNING   pid 9941, uptime 0:00:12
frappe-bench-redis:frappe-bench-redis-queue               RUNNING   pid 9946, uptime 0:00:12
frappe-bench-web:frappe-bench-frappe-web                  RUNNING   pid 9947, uptime 0:00:12
frappe-bench-web:frappe-bench-node-socketio               RUNNING   pid 9949, uptime 0:00:12
frappe-bench-workers:frappe-bench-frappe-long-worker-0    RUNNING   pid 9956, uptime 0:00:12
frappe-bench-workers:frappe-bench-frappe-schedule         RUNNING   pid 9950, uptime 0:00:12
frappe-bench-workers:frappe-bench-frappe-short-worker-0   RUNNING   pid 9951, uptime 0:00:12

启动 supervisor 前必须先停掉 bench start（Ctrl+C 退出），否则 8000 端口与 Redis 端口冲突。

7.3 nginx 反向代理

bench 生成的站点配置在 config/nginx.conf，安装到 nginx 并启用：

sudo cp config/nginx.conf /etc/nginx/sites-available/hd.local.conf
sudo ln -sf /etc/nginx/sites-available/hd.local.conf /etc/nginx/sites-enabled/hd.local.conf
sudo rm -f /etc/nginx/sites-enabled/default

⚠️ 实测坑：Ubuntu 的 nginx 未预定义 main 日志格式，直接 nginx -t 会报 nginx: [emerg] unknown log format "main" in /etc/nginx/sites-enabled/hd.local.conf:101。在配置文件最顶部（server 块之前）补一行：

log_format main '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"';

然后验证并启动：

sudo nginx -t
# nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
# nginx: configuration file /etc/nginx/nginx.conf test is successful
sudo service nginx start
#  * Starting nginx nginx
#    ...done.

生产入口验证（80 端口，无需再指定 8000）：

curl -s -o /dev/null -w "%{http_code}\n" http://hd.local/helpdesk
# 200
curl -s http://hd.local/api/method/ping
# {"message":"pong"}

7.4 后续升级

cd /home/frappe/frappe-bench
bench update

配置了 supervisor 托管后，bench update 完成会按 restart_supervisor_on_update 配置自动重启托管进程（该键由 bench setup supervisor 自动写入并置 true，见本专栏配置详解篇）。

八、部署验证清单

逐项实测核对（生产托管状态下）：

bench version
# frappe 15.124.0
# helpdesk 1.31.0
# telephony 0.0.1
bench --site hd.local list-apps
# frappe    15.124.0 version-15
# telephony 0.0.1    develop
# helpdesk  1.31.0   HEAD
bench doctor
# -----Checking scheduler status-----
# Workers online: 1
# -----None Jobs-----
sudo supervisorctl status   # 7 个进程 RUNNING
curl -s http://hd.local/api/method/ping        # {"message":"pong"}
curl -s -o /dev/null -w "%{http_code}" http://hd.local/helpdesk   # 200

浏览器验证：http://hd.local/helpdesk 进入坐席端登录页，Administrator 登录后可创建工单、配置 SLA 与知识库；客户门户入口为站点根路径 /helpdesk 下的门户视图。

九、常见问题与排障实录

9.1 bench init 报 Invalid frappe path / Connection refused 现象：git ls-remote 连接 github.com 443 端口被拒。原因：服务器无法直连 GitHub。解决：会话级导出 http_proxy/https_proxy 后重跑（见 4.2 排障实录一）。

9.2 bench init 末尾报 FileNotFoundError '/usr/bin/crontab' 原因：Ubuntu 最小安装不带 cron。解决：sudo apt-get install -y cron 后重跑；重跑前 rm -rf 半成品 bench 目录。

9.3 new-site 或 init 报 ZoneInfoNotFoundError: 'No time zone found with key Asia/Kolkata' 原因：缺 /usr/share/zoneinfo 时区数据。解决：sudo DEBIAN_FRONTEND=noninteractive apt-get install -y tzdata。若此前已生成半个站点，需清理后重跑：root 执行 mysql -uroot -p密码 -e "DROP DATABASE IF EXISTS <site_config 里的 db_name>;" 并 rm -rf sites/<站点名>，否则下次建站报 Database _5d00a979683836f3 already exists（实测原文，Site xxx already exists 同理）。

9.4 访问 8000 端口全部 404（localhost does not exist） 原因：Frappe 多站点按 Host 头路由。解决：用 -H "Host: <站点名>" 测试，或把站点名写入 /etc/hosts 后用域名访问（见 4.7）。

9.5 curl -u Administrator:密码调 API 返回 401 原因：Frappe 对 basic auth 的支持路径是 API Key/Secret（Authorization: token <key>:<secret>），网页登录密码要走 /api/method/login 表单会话。实测 -d "usr=Administrator&pwd=..." 登录成功返回 {"message":"Logged In",...}（见 4.7）。

9.6 bench --site <站点名> add-to-hosts 报 sudo: not found 原因：add-to-hosts 需要 root 写 /etc/hosts，当前用户无 sudo。解决：以具备 sudo 的用户执行，或 root 直接追加 hosts 记录（见 4.8）。

9.7 service mariadb restart 后字符集配置未生效且停止报 fail! 原因：Ubuntu 的 service 脚本停止阶段超时报 ...fail!，实际旧进程未被终止，restart 变成了「重启失败仍用旧配置」。解决：sudo mysqladmin -uroot -p密码 shutdown 后再 sudo service mariadb start，用 SHOW VARIABLES 复核（见 2.3）。

9.8 bench setup production 失败于 fail2ban 角色 现象：PLAY RECAP ... failed=1 + returned non-zero exit status 2。该一键命令还要求 root 权限（非 root 执行直接报 WARN: superuser privileges required for this command）。解决：按 7.2/7.3 拆分手工执行 supervisor 与 nginx 两步，效果等价且可控。

9.9 nginx -t 报 unknown log format "main" 原因：bench 生成的 nginx 配置引用 main 日志格式，Ubuntu 的 nginx 未预定义。解决：在配置文件顶部补 log_format main '...'; 一行（见 7.3）。

9.10 bench drop-site 报 Access denied for user 'root'@'localhost' (using password: YES) 原因：drop-site 交互式询问 root 密码，管道输入 y 会被当作密码吃掉。解决：显式传参 bench drop-site <站点名> --no-backup --db-root-password <root密码>（见第十章）。

十、卸载与清理

按依赖顺序逆序拆除（以下全部实测执行）：

# 1. 停托管进程与系统服务
sudo supervisorctl stop all
# frappe-bench-workers:frappe-bench-frappe-long-worker-0: stopped
# frappe-bench-workers:frappe-bench-frappe-short-worker-0: stopped
# frappe-bench-web:frappe-bench-frappe-web: stopped
sudo rm -f /etc/supervisor/conf.d/frappe-bench.conf
sudo service nginx stop
sudo service supervisor stop
# Stopping supervisor: supervisord.

# 2. 删除站点（库、账号、站点目录一起清）
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

# 3. 删除 bench 目录
rm -rf /home/frappe/frappe-bench

# 4. 卸载 bench CLI
sudo pip3 uninstall -y frappe-bench
# Successfully uninstalled frappe-bench-5.31.0
which bench || echo BENCH_GONE
# BENCH_GONE

# 5. 可选：回退系统级变更（按需执行）
sudo rm -f /etc/mysql/mariadb.conf.d/99-frappe.cnf /etc/nginx/sites-enabled/hd.local.conf /etc/nginx/sites-available/hd.local.conf /etc/sudoers.d/frappe /etc/apt/sources.list.d/redis.list
sudo apt-get purge -y supervisor nginx redis cron   # 若服务器无他用

⚠️ drop-site 默认会先做一次备份再归档站点目录（archived/sites 下），确认不需要数据时用 --no-backup 跳过。

十一、参考链接

Frappe Helpdesk 官方仓库：https://github.com/frappe/helpdesk（README 的 Development Setup 与 Production Setup 章节）
Helpdesk 官方文档：https://docs.frappe.io/helpdesk
Frappe Framework 安装文档（bench 依赖清单来源）：https://frappeframework.com/docs/user/en/installation
bench 常用命令速查：本专栏《Frappe Helpdesk 1.31 常用 CLI 命令与工具详解》
站点配置项逐键详解：本专栏《Frappe Helpdesk 1.31 配置参数详解》
Docker Compose 编排部署（含持久化与备份恢复闭环）：本专栏《Frappe Helpdesk 1.31 Docker Compose 部署指南》
产品定位与选型对比：[《Frappe Helpdesk 1.31 介绍与选型指南》](https://www.quzuo.net/document/xtxb3uZrBRAB)