Ubuntu 22.04 安装 Frappe HR 16.52.0 指南

目标：在一台 Ubuntu 22.04 服务器上从零安装 Frappe HR（开源 HRMS）v16.52.0 稳定版，覆盖完整依赖链（Python 3.14 / MariaDB 11.8 / Redis / Node 24 / bench CLI）、bench 建站、应用安装、启动验证、离线备用方案、排障实录与卸载清理。本文全部命令与回显已在 Ubuntu 22.04（x86_64）实测通过，实测版本组合：hrms 16.52.0 + erpnext 16.52.1 + frappe 16.53.0 + bench 5.31.0。

一、环境信息

操作系统：Ubuntu 22.04 LTS（x86_64，cat /etc/os-release 实测回显：Ubuntu 22.04.x LTS）
目标版本：Frappe HR v16.52.0（2026-10-22 发布，GitHub Releases 实查）
依赖版本（实测）：Python 3.14.9、MariaDB 11.8.9、Redis 8.10.2、Node.js v24.x、yarn 1.22.22、wkhtmltopdf 0.12.6-2、bench 5.31.0
应用组合（实测 bench version 回显）：frappe 16.53.0 HEAD、erpnext 16.52.1 HEAD、hrms 16.52.0 HEAD
安装目录：/home/frappe/frappe-bench（bench 标准布局）
站点名：hr.example.com，Web 端口 8000（dev serve），数据库 root 密码与站点管理员密码按示例统一为 q1w2e3r4
站内配置篇：《Frappe HR 16.52.0 配置参数详解》详解 site_config 与 HR 模块设置；本篇只完成安装与验证。

二、版本选型说明

Frappe HR 不是独立单体软件，而是「Frappe 框架 + ERPNext + HRMS」三个 App 叠加在 bench 上的组合。版本必须三件套对齐，选型依据如下（均实查于 2026-10-23）：

组件	版本	依据
hrms	v16.52.0	frappe/hrms 最新稳定标签（GitHub Releases）
frappe（框架）	≥16.50.0 且 <17.0.0，实测装 v16.53.0	hrms v16.52.0 的 pyproject.toml `frappe-dependencies` 声明
erpnext	≥16.50.0 且 <17.0.0，实测装 v16.52.1	hrms v16.52.0 的 pyproject.toml 声明 + hooks.py `required_apps = ["frappe/erpnext"]`
Python	≥3.14 且 <3.15，实测 3.14.9	frappe v16 pyproject.toml `requires-python = ">=3.14,<3.15"`
Node.js	≥24，实测 v24	frappe 应用的 package.json engines 声明（低于 24 构建报错，见第十章 FAQ-1）
MariaDB	11.8（frappe v16 CI 基准）	frappe/frappe version-16 CI 工作流镜像 `mariadb:11.8`
Redis	≥6.2，实测 8.10.2	frappe_docker 官方 compose 使用 redis 6.2+；实测 8.10.2 兼容
yarn	1.22（经典版）	bench 资产构建使用 `yarn run production`

💡 说明：Ubuntu 22.04 系统自带的 Python 3.10 与 frappe v16 不兼容（v16 只接受 3.14），因此本文用 deadsnakes PPA 安装 python3.14 并通过 bench init --python python3.14 显式指定解释器；bench CLI 本身运行在系统 Python 3.10 上，与站点虚拟环境（3.14）是两层，互不冲突。若你的服务器是 Ubuntu 24.04+，同样建议走 PPA/源码方式确保拿到 3.14 系列。

三、前置条件

本节一次性装齐操作系统级依赖：git/编译工具、Python 3.14、MariaDB 11.8、Redis、Node 24、yarn、wkhtmltopdf。命令均可直接整段执行（每步都有独立验证）。

3.1 基础工具与源配置

apt-get update -y && apt-get install -y ca-certificates curl gnupg git software-properties-common build-essential pkg-config
add-apt-repository -y ppa:deadsnakes/ppa        # Python 3.14 来源

MariaDB 11.8 官方仓库（Ubuntu 22.04 自带的 MariaDB 为 10.6，不满足 frappe v16 CI 基准）：

curl -LsS https://r.mariadb.com/downloads/mariadb_repo_setup | bash -s -- --mariadb-server-version=11.8

Redis 官方仓库（Ubuntu 22.04 自带 redis 6.0.16 低于 frappe 要求的 6.2）：

curl -fsSL https://packages.redis.io/gpg | 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" > /etc/apt/sources.list.d/redis.list

Node.js 24 官方仓库（⚠️ 不要装 Node 20，frappe v16 构建要求 ≥24，实测 Node 20.20.2 会在资产构建时报引擎不兼容错误，见第十章 FAQ-1）：

curl -fsSL https://deb.nodesource.com/setup_24.x | bash -

刷新索引并安装（分批执行，便于定位问题）：

apt-get update -y
apt-get install -y python3.14 python3.14-venv python3.14-dev
apt-get install -y mariadb-server mariadb-client
apt-get install -y redis-server
apt-get install -y nodejs
apt-get install -y libmariadb-dev libffi-dev libssl-dev libjpeg-dev zlib1g-dev \
  libpango-1.0-0 libpangocairo-1.0-0 libgdk-pixbuf-2.0-0 wkhtmltopdf
npm install -g yarn@1.22.22

实测回显（各组件版本验证，逐条执行）：

python3.14 --version

Python 3.14.9

mariadb --version

mariadb from 11.8.9-MariaDB, client 15.2 for debian-linux-gnu (x86_64) using  EditLine wrapper

redis-server --version

Redis server v=8.10.2 sha=00000000:1 malloc=jemalloc-5.3.0 bits=64 build=accb23a4692c1fdb

node --version && yarn --version

v24.14.0
1.22.22

dpkg -l wkhtmltopdf | tail -1

ii  wkhtmltopdf    0.12.6-2     amd64        Command line utilities to convert html to pdf or image using WebKit

⚠️ 注意：上面 node --version 的回显 v24.14.0 为 NodeSource setup_24.x 当前版本；yarn 必须用经典版 1.x（npm install -g yarn@1.22.22），bench 的构建脚本走 yarn run production，与 yarn 2+/berry 的行为不兼容。

3.2 MariaDB 初始化与字符集配置

Frappe 强制要求 utf8mb4 字符集，写入独立配置文件：

cat > /etc/mysql/mariadb.conf.d/99-frappe.cnf <<'EOF'
[mysqld]
character-set-client-handshake = FALSE
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci

[mysql]
default-character-set = utf8mb4
EOF
systemctl enable --now mariadb
systemctl enable --now redis-server

实测回显（服务状态验证）：

systemctl is-active mariadb redis-server

active
active

3.3 MariaDB root 账号改为密码认证（关键步骤，防 1698 错误）

Ubuntu/Debian 系的 MariaDB 默认对 root@localhost 启用 unix_socket 本地系统用户认证，bench 在创建站点时用 TCP/套接字以密码方式连接 root 会报 ERROR 1698 (28000): Access denied for user 'root'@'localhost'（完整排障过程见第十章 FAQ-2）。将其改为标准密码认证：

mysql -uroot -e "ALTER USER 'root'@'localhost' IDENTIFIED VIA mysql_native_password USING PASSWORD('q1w2e3r4'); FLUSH PRIVILEGES;"

验证（TCP 方式 + 指定密码，与 bench 的连接形态一致）：

mysql -h127.0.0.1 -uroot -pq1w2e3r4 -e "select current_user();"

current_user()
root@localhost

四、安装方案 A：bench 在线安装（主方案）

本方案即官方推荐路径：pip 安装 bench CLI → bench init 初始化站点目录 → get-app 拉取 erpnext 与 hrms → 建站装应用。全程需可访问 GitHub 与 PyPI。

4.1 安装 bench CLI

python3 -m pip install frappe-bench

实测回显（节选）：

Collecting frappe-bench
Requirement already satisfied: six>=1.6 in /usr/lib/python3/dist-packages (from python-dateutil->python-crontab~=2.6.0->frappe-bench) (1.16.0)
...
Successfully installed bench-5.31.0 ...

bench --version

5.31.0

4.2 创建运行用户

bench 不允许以 root 运行，创建专用用户并切换：

useradd -m -s /bin/bash frappe
su - frappe

4.3 bench init 初始化

bench init frappe-bench --frappe-branch v16.53.0 --python python3.14

实测回显（节选，关键步骤逐段照抄；进度与 MO 翻译编译等重复行省略）：

Setting Up Environment
$ uv venv env --seed --python python3.14
Using CPython 3.14.9 interpreter at: /usr/bin/python3.14
Creating virtual environment with seed packages at: env
 + pip==26.2.2
Getting frappe
$ git clone https://github.com/frappe/frappe.git --branch v16.53.0 --depth 1 --origin upstream
Cloning into 'frappe'...
Note: switching to 'e8d41dd0061a32ee781caefe5d0b0d2bb7c15362'.
Installing frappe
$ uv pip install --quiet -e /home/frappe/frappe-bench/apps/frappe  --python /home/frappe/frappe-bench/env/bin/python
$ yarn install --check-files
...（yarn 依赖解析与 esbuild 资产构建过程省略）
 DONE  Total Build Time: 9.012s
Compiling translations for frappe
MO file created at /home/frappe/frappe-bench/sites/assets/locale/sr/LC_MESSAGES/frappe.mo
...（多语言 MO 编译省略）
SUCCESS: Bench frappe-bench initialized

💡 说明：bench init 完成 4 件事——用 uv 创建 Python 3.14 虚拟环境（env/）、shallow clone frappe v16.53.0（apps/frappe/，commit e8d41dd）、把 frappe 以可编辑模式装进虚拟环境、esbuild 构建前端资产并编译翻译。耗时与缓存状态强相关：首次冷缓存（下载依赖）在 4 核/8GB 实测约 5～8 分钟；复测（uv/yarn 缓存已热）同一流程仅约 24 秒，以 SUCCESS: Bench <目录名> initialized 为成功标志。

4.4 拉取 erpnext 与 hrms

cd frappe-bench
bench get-app https://github.com/frappe/erpnext.git --branch v16.52.1

实测回显（节选，依赖安装与 esbuild 构建过程行省略）：

Getting erpnext
$ git clone https://github.com/frappe/erpnext.git --branch v16.52.1 --depth 1 --origin upstream
Cloning into 'erpnext'...
Note: switching to 'ade850bbd6a7412e9994a9637d2c5c713771632a'.
Installing erpnext
$ uv pip install --quiet -e /home/frappe/frappe-bench/apps/erpnext  --python /home/frappe/frappe-bench/env/bin/python
$ bench build --app erpnext
...（资产构建输出省略）

bench get-app https://github.com/frappe/hrms.git --branch v16.52.0

实测回显（节选）：

Getting hrms
$ git clone https://github.com/frappe/hrms.git --branch v16.52.0 --depth 1 --origin upstream
Cloning into 'hrms'...
Note: switching to '5c72c067c0a3bcc969a49c708b7bec545a046fe9'.
Installing hrms
$ uv pip install --quiet -e /home/frappe/frappe-bench/apps/hrms  --python /home/frappe/frappe-bench/env/bin/python
Running build command for hrms
$ yarn build-pwa && yarn build-roster
...（资产构建输出省略）

💡 说明：get-app 全程 = shallow clone 指定 tag + uv 可编辑安装 + bench build 编译该 App 资产。耗时随缓存差异很大：复测（缓存已热）erpnext 约 21 秒、hrms 约 30 秒；首轮冷缓存含全量依赖下载与构建，明显更长。

版本自检（三件套必须都在且版本匹配）：

bench version

erpnext 16.52.1 HEAD (ade850b)
frappe 16.53.0 HEAD (e8d41dd)
hrms 16.52.0 HEAD (5c72c06)

4.5 Redis 指向系统实例

bench init 默认生成的开发配置把缓存/队列/SocketIO 指到 11000/12000/13000 端口（由 bench start 托管的专用 redis 实例）。服务器上已用 systemd 托管系统级 redis-server（6379），将三类通道统一指向它（与官方容器化部署的 configurator 做法一致）：

bench set-config -g redis_cache "redis://127.0.0.1:6379"
bench set-config -g redis_queue "redis://127.0.0.1:6379"
bench set-config -g redis_socketio "redis://127.0.0.1:6379"

验证写入结果：

grep redis sites/common_site_config.json

 "redis_cache": "redis://127.0.0.1:6379",
 "redis_queue": "redis://127.0.0.1:6379",
 "redis_socketio": "redis://127.0.0.1:6379",

⚠️ 注意：若跳过本步直接建站，install-app 会因连不上 127.0.0.1:11000 报 Error 111 connecting to 127.0.0.1:11000. Connection refused（见第十章 FAQ-3）。

4.6 创建站点

bench new-site hr.example.com --mariadb-root-password q1w2e3r4 --admin-password q1w2e3r4

实测回显（进度条约 700 行逐行刷新，中间行以省略号示意，文本行照抄）：

Installing frappe...
Updating DocTypes for frappe        : [                                        ] 0%
Updating DocTypes for frappe        : [=                                       ] 3%
...（进度条逐行刷新至 100%，此处省略）
Updating DocTypes for frappe        : [========================================] 100%
Updating Dashboard for frappe
*** Scheduler is disabled ***

💡 说明：new-site 成功后没有「created successfully」之类的尾行，输出以 *** Scheduler is disabled *** 结束、无报错即成功。该过程会创建数据库（随机名如 _25875420d890f4a7）与同名数据库用户，同步全量 DocType，并写入 sites/hr.example.com/site_config.json（含自动生成的 db_password）。管理员账号固定为 Administrator，密码即 --admin-password 传入的值。

4.7 安装 erpnext 与 hrms 到站点

bench --site hr.example.com install-app erpnext

实测回显（erpnext，进度条中间行省略，安装约 3～8 分钟）：

Installing erpnext...
Updating DocTypes for erpnext       : [                                        ] 0%
...（进度条逐行刷新至 100%，此处省略）
Updating DocTypes for erpnext       : [========================================] 100%
Address / Accounts Manager: added read
Updating Dashboard for erpnext

bench --site hr.example.com install-app hrms

实测回显（hrms，App erpnext already installed 是 bench 检测到依赖 App 已装的提示）：

App erpnext already installed

Installing hrms...
Updating DocTypes for hrms          : [                                        ] 0%
...（进度条逐行刷新至 100%，此处省略）
Updating DocTypes for hrms          : [========================================] 100%
Setting up Frappe HR...

Patching Existing Data...
rename_field: kra_title not found in table for: Appraisal Template
rename_field: kra_template not found in table for: Appraisal
Thank you for installing Frappe HR!
Updating Dashboard for hrms

💡 说明：rename_field: ... not found in table 是 hrms 补丁对全新站点的正常提示（旧字段本就不存在），不是错误；看到 Thank you for installing Frappe HR! 即安装成功。

应用清单确认：

bench --site hr.example.com list-apps

frappe  16.53.0 HEAD
erpnext 16.52.1 HEAD
hrms    16.52.0 HEAD

4.8 启动服务并验证

开发验证模式（前台运行，测试用）：

bench --site hr.example.com serve --port 8000

另开一个终端验证（两条实测回显）：

curl -s http://localhost:8000/api/method/ping

{"message":"pong"}

curl -sI http://localhost:8000 | head -6

HTTP/1.1 200 OK
Server: Werkzeug/3.1.9 Python/3.14.9
Date: Fri, 23 Oct 2026 06:25:57 GMT
Content-Type: text/html; charset=utf-8
Content-Length: 33536
X-Page-Name: login

/api/method/ping 返回 {"message":"pong"} 且首页返回 HTTP/1.1 200 OK（X-Page-Name: login 登录页）即安装成功。浏览器访问 http://<服务器IP>:8000，用 Administrator / q1w2e3r4 登录即进入 HR Desk。

💡 技术拓展：bench serve 是 Werkzeug 开发服务器，仅适合验证与小规模内网使用。生产托管有两种主流方式对比：

方式原理适用场景
bench setup production 生成 supervisor 进程组 + nginx 反代配置单机生产，官方推荐
手写 systemd 单元 web/worker/schedule 拆成独立服务需要 systemd 统一管控

生产化命令：bench setup production frappe（需 root 执行，自动安装 supervisor/nginx 并生成配置）；本文验证以 dev serve 为准，生产托管配置属运维范畴。

方式	原理	适用场景
bench setup production	生成 supervisor 进程组 + nginx 反代配置	单机生产，官方推荐
手写 systemd 单元	web/worker/schedule 拆成独立服务	需要 systemd 统一管控

五、安装方案 B：离线制备与内网安装（备用方案）

适用场景：目标服务器不能直连 PyPI/GitHub。思路是在一台可联网的机器上制备离线产物（wheel 包 + 源码仓库），再到内网机器安装。以下全部步骤与回显在实测环境完成（制备与「内网」模拟同机，以 --no-index/--offline 强制断网行为验证可行性）。

5.1 制备侧：下载 frappe-bench wheel 包

python3 -m venv /home/frappe/vbench-off
/home/frappe/vbench-off/bin/pip download -d /home/frappe/offline-pkgs frappe-bench

实测回显（尾部两行，共 21 个 wheel）：

Saved /home/frappe/offline-pkgs/frappe_bench-5.31.0-py3-none-any.whl
Successfully downloaded frappe-bench click gitpython jinja2 python-crontab requests semantic-version uv honcho tomli certifi charset_normalizer gitdb idna MarkupSafe urllib3 python-dateutil six smmap tzdata setuptools

产物清单（实测 ls /home/frappe/offline-pkgs，节选）：

certifi-2026.10.19-py3-none-any.whl
charset_normalizer-3.5.2-py3-none-any.whl
click-8.2.1-py3-none-any.whl
frappe_bench-5.31.0-py3-none-any.whl
gitpython-3.1.62-py3-none-any.whl
honcho-2.0.0-py3-none-any.whl
uv-0.11.33-py3-none-any.whl

5.2 内网侧：离线安装 bench

把 /home/frappe/offline-pkgs 拷贝到内网机器后（实测同机 --no-index 模拟断网）：

python3 -m venv /home/frappe/vbench-net
/home/frappe/vbench-net/bin/pip install --no-index --find-links /home/frappe/offline-pkgs frappe-bench

实测回显（全部依赖来自本地 wheel，零外网访问）：

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

/home/frappe/vbench-net/bin/bench --version

5.31.0

5.3 源码仓库的离线制备与本地 init

frappe/erpnext/hrms 三个 App 无法走 PyPI，在联网机 shallow clone 指定标签后拷贝到内网（实测 frappe 制备）：

git clone --depth 1 --branch v16.53.0 https://github.com/frappe/frappe.git /home/frappe/offline-repos/frappe

实测回显（尾部）：

Cloning into '/home/frappe/offline-repos/frappe'...
Note: switching to 'e8d41dd0061a32ee781caefe5d0b0d2bb7c15362'.

内网机器用本地路径作为 frappe 来源执行 init：

bench init bench-offline --frappe-path /home/frappe/offline-repos/frappe --python python3.14

实测回显（与远程 init 同构，尾部）：

Getting frappe
$ git clone /home/frappe/offline-repos/frappe  --depth 1 --origin upstream
Cloning into 'frappe'...
warning: --depth is ignored in local clones; use file:// instead.
Note: switching to 'e8d41dd0061a32ee781caefe5d0b0d2bb7c15362'.
...
SUCCESS: Bench bench-offline initialized

⚠️ 注意：clone 由 root 执行、init 由 frappe 用户执行时会报 fatal: detected dubious ownership in repository at '/home/frappe/offline-repos/frappe/.git'——执行 git config --global --add safe.directory /home/frappe/offline-repos/frappe/.git（或统一 chown -R frappe:frappe 制备目录）后重跑。

erpnext/hrms 的离线加入实测结论：bench get-app <本地路径> 不是离线安装——实测传入本地仓库路径后，bench 解析出应用元数据仍从 GitHub 远程重新 clone（回显 $ git clone https://github.com/frappe/hrms.git ...），内网机器上会失败。正确的离线姿势是把制备仓库直接拷入 bench 的 apps/ 目录后用 uv 离线安装（实测）：

cp -r /home/frappe/offline-repos/hrms /home/frappe/bench-offline/apps/hrms
cd /home/frappe/bench-offline
uv pip install --offline -e apps/hrms --python env/bin/python

实测回显（--offline 强制不联网，本地 file:// 来源）：

Installed 1 package in 0.66ms
 + hrms==16.52.0 (from file:///home/frappe/bench-offline/apps/hrms)

安装验证：

env/bin/python -c "import hrms; print(hrms.__file__)"

/home/frappe/bench-offline/apps/hrms/hrms/__init__.py

erpnext 同法操作。随后建站装应用与方案 A 完全一致（见 4.6～4.8）。

⚠️ 注意：①bench init 中的 yarn install 环节默认访问 npm registry，完全离线时需自建 npm 私服（如 verdaccio）或预先把 node_modules 打包随仓库携带；②bench init 依赖 crontab 命令，最小化安装的系统需先 apt-get install -y cron，否则报 FileNotFoundError: [Errno 2] No such file or directory: '/usr/bin/crontab'（实测，见第十章 Q6）；③仅 frappe-bench CLI 的离线安装（5.1～5.2）不受上述影响。

5.4 方案对比与选择建议

维度	方案 A：在线安装	方案 B：离线制备
网络要求	可访问 GitHub/PyPI/npm	仅制备机需要外网
版本控制	get-app 指定 tag，精确	clone 指定 tag，精确
安装耗时	首次 15～25 分钟	制备约 10 分钟 + 内网安装 10～20 分钟
维护成本	低（bench update 直接升级）	中（每次升级需重新制备）
适用场景	普通云服务器/IDC	金融/政务等隔离内网

选型建议：能联网一律选方案 A；内网隔离环境用方案 B，且建议整目录打包（bench-offline 初始化完成后的 env/ 不可直接拷贝复用——虚拟环境含绝对路径，必须在内网重新 init，只拷贝仓库与 wheel 包）。

六、配置说明

安装完成后的关键文件与默认值（实测内容，敏感值说明见下）：

/home/frappe/frappe-bench/sites/common_site_config.json：bench 全局配置（redis 三通道地址、webserver_port 8000、socketio_port 9000、gunicorn_workers 等），由 bench set-config -g 修改。
/home/frappe/frappe-bench/sites/hr.example.com/site_config.json：站点级配置（db_name/db_password/installed_apps），由 bench 自动生成，bench set-config（不带 -g）修改。
/etc/mysql/mariadb.conf.d/99-frappe.cnf：MariaDB 字符集配置（3.2 节写入）。
⚠️ site_config.json 中的 db_password、encryption_key 属自动生成的敏感凭据，本文以 ${DB_PASSWORD} 之类占位表述，请勿将真实值提交到代码库或文档。

常用配置命令：

bench set-config -g webserver_port 8000     # 全局键
bench set-config -gp db_port 3306           # -p 强制整数类型
bench --site hr.example.com show-config     # 查看配置（合并两层表格输出；bench 5.31 已移除 get-config）

逐项参数含义与 HR 模块（HR Settings/Payroll Settings）的设置项实测详解，见《Frappe HR 16.52.0 配置参数详解》。

七、升级与多版本管理

升级三件套（大版本内）：bench update（拉取各 App 分支最新代码并 migrate），升级前必须 bench --site hr.example.com backup。
锁定补丁版本：把 apps/*/ 下仓库 checkout 到指定 tag 后 bench build && bench --site hr.example.com migrate。
多版本并存：bench 以目录为单位，可在同一台机 bench init frappe-bench-v15 --frappe-branch version-15 建独立目录跑 v15 系列（v15 对应 Python ≥3.10），两套 bench 各自独立端口运行；注意两个站点不能共用同一个数据库实例中的同名库。

八、验证清单（安装后自检）

bench version                                   # 三件套版本输出
bench --site hr.example.com list-apps           # 站点应用清单含 hrms
curl -s http://localhost:8000/api/method/ping   # {"message":"pong"}
systemctl is-active mariadb redis-server        # active active

四项全部符合预期即安装闭环完成。

九、卸载与清理

按依赖反向顺序逐项删除（每条独立执行）：

bench --site hr.example.com drop-site hr.example.com --root-password q1w2e3r4 --force

实测回显（drop-site 自动做最终备份后删库）：

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

cd ~ && rm -rf /home/frappe/frappe-bench          # 删除整个 bench 目录（含 apps/env/sites）
python3 -m pip uninstall -y frappe-bench          # 卸载 bench CLI

实测回显（在隔离 venv 中验证 uninstall 行为）：

Successfully uninstalled bench-5.31.0

数据库与缓存服务如不再使用，可按需停用（不影响其他业务时才执行）：

systemctl disable --now mariadb
systemctl disable --now redis-server
apt-get purge -y mariadb-server redis-server      # 可选：连同包一起删除
rm -rf /var/lib/mysql /var/lib/redis              # 可选：清空数据目录

十、常见问题（FAQ）

Q1：bench build/get-app 报 error frappe-framework@: The engine "node" is incompatible with this module. Expected version ">=24". Got "20.20.2"，怎么办？

现象（实测完整错误头两行）：

yarn run v1.22.22
error frappe-framework@: The engine "node" is incompatible with this module. Expected version ">=24". Got "20.20.2"
error Commands cannot run with an incompatible environment.

定位：frappe v16 的前端构建链要求 Node ≥24，系统装的是 NodeSource 20。解决：按 3.1 节改用 setup_24.x 仓库安装 nodejs，然后在 bench 目录重跑构建：

cd /home/frappe/frappe-bench
cd apps/frappe && yarn install --check-files && cd ../..    # 切换 Node 大版本后重装依赖
bench build

若切换 Node 后仍报 Error: Cannot find module 'fast-glob'（实测出现过），执行 apps/frappe 内的 yarn install --check-files 即可修复（node_modules 与新 Node 环境重新对齐）。

Q2：bench new-site 报 MySQLdb.OperationalError: (1698, "Access denied for user 'root'@'localhost'")，怎么办？

定位（实测）：mysql -h127.0.0.1 -uroot -pq1w2e3r4 -e "select 1" 复现同样报错，而 mysql -uroot（系统 root 免密）能登录——说明 root@localhost 启用了 unix_socket 认证、密码通道被拒。解决见 3.3 节：用系统 root 免密进入后执行 ALTER USER 'root'@'localhost' IDENTIFIED VIA mysql_native_password USING PASSWORD('...'); FLUSH PRIVILEGES;，再用 TCP+密码验证通过后重跑 new-site。若 new-site 失败残留了 sites/<站点名>/ 目录，先 rm -rf sites/<站点名> 再重试，避免半成品站点干扰。

Q3：install-app 报 Error 111 connecting to 127.0.0.1:11000. Connection refused，怎么办？

定位：bench init 生成的开发配置默认把 redis 队列指到 11000 端口（bench start 专用实例），而服务器上跑的是 systemd 托管的 6379。解决见 4.5 节三条 bench set-config -g redis_* 命令，改完用 grep redis sites/common_site_config.json 确认。

Q4：pip 装不上 python3.14-venv/python3.14-dev？

Ubuntu 22.04 需先添加 deadsnakes PPA（3.1 节第一条 add-apt-repository ppa:deadsnakes/ppa）再 apt-get update，否则报 E: Unable to locate package python3.14-venv（实测现象）。

Q5：站点能 ping 通但浏览器打不开？

确认 bench serve 进程仍在运行（ss -ltnp | grep 8000），dev serve 是前台进程，终端关闭即停止；生产环境改用 bench setup production 托管。另注意服务器防火墙需放行 8000（或反代后的 80/443）。

Q6：bench init 报 FileNotFoundError: [Errno 2] No such file or directory: '/usr/bin/crontab'，怎么办？

bench init 需要 cron 命令写入定时任务（bench scheduler 与备份计划）。最小化安装的系统（如精简版容器/云镜像）不带 crontab。解决：

apt-get install -y cron

实测装后重跑 init 正常通过（cron 服务不必启动，bench 只需要 crontab 可执行文件）。

十一、参考链接

Frappe HR 安装文档（README Local 一节）：https://github.com/frappe/hrms#local
bench 仓库与命令文档：https://github.com/frappe/bench
Frappe Framework 安装文档：https://frappeframework.com/docs/user/en/installation
hrms v16.52.0 发布页：https://github.com/frappe/hrms/releases/tag/v16.52.0
deadsnakes PPA：https://launchpad.net/~deadsnakes/+archive/ubuntu/ppa
MariaDB 仓库配置脚本：https://mariadb.org/download/?t=repo-config
本系列关联文档：《Frappe HR 16.52.0 介绍与选型指南》、《Frappe HR 16.52.0 Docker Compose 部署指南》、《Frappe HR 16.52.0 配置参数详解》、《Frappe HR 16.52.0 常用 CLI 命令与工具详解》