Ubuntu 24.04 部署 ERPNext v16 开发环境指南（中国本地化版）

针对在 Ubuntu 24.04 上搭建 ERPNext v16 开发环境的需求，以下是完全符合国内使用习惯（如时区、镜像源、中文支持）的本地部署教程。

⚠️ 重要提示

• 适用场景：本地虚拟机、个人电脑、内网测试服务器。

• 核心区别：开发模式不使用 Nginx/Supervisor，而是通过 bench start 直接运行，方便查看报错日志和调试代码。

• 用户权限：全程使用普通用户 frappe，严禁在生产命令前加 sudo（除非明确提示需要）。

---

第一步：系统基础准备 (Root/Admin 权限)

1. 更换国内镜像源 (加速下载)

在安装任何软件前，建议将 Ubuntu 源替换为阿里云或清华源，否则下载速度极慢。

sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak
# 编辑 sources.list，将 archive.ubuntu.com 替换为 mirrors.aliyun.com
sudo sed -i 's/archive.ubuntu.com/mirrors.aliyun.com/g' /etc/apt/sources.list
sudo apt update -y

2. 设置中国时区

sudo timedatectl set-timezone Asia/Shanghai
date # 检查时间是否为北京时间

3. 安装系统级依赖

sudo apt install git curl redis-server mariadb-server mariadb-client \
python3-dev python3-pip python3-setuptools python3-venv \
xvfb libfontconfig libmysqlclient-dev pkg-config \
software-properties-common net-tools -y

---

第二步：创建专用用户 (Root 权限)

ERPNext 禁止使用 root 运行，必须创建普通用户。

# 创建 frappe 用户并加入 sudo 组
sudo adduser frappe
# 设置密码（例如：frappe123），其余信息回车跳过
sudo usermod -aG sudo frappe

# 切换到 frappe 用户
su - frappe

注意：后续所有步骤都在 frappe 用户下执行，不要切回 root。

---

第三步：安装 Python 与 Node.js 环境

1. 安装 UV (Python 管理器)

curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc

# 安装 Python 3.12 (ERPNext v16 推荐稳定版本，3.14 可能过新)
uv python install 3.12 --default

2. 安装 Node.js (使用 nvm)

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc

# 安装 Node.js 18 (Frappe v16 官方推荐 LTS 版本)
nvm install 18
nvm use 18

# 验证版本
node -v  # 应显示 v18.x.x
npm -v

3. 安装 Yarn

npm install -g yarn

---

第四步：配置 MariaDB 数据库 (关键步骤)

1. 初始化数据库安全设置

sudo mysql_secure_installation

• Enter current password: 直接回车 (空)

• Switch to unix_socket: N

• Change root password: Y (设置一个强密码，如 Erp@123456)

• Remove anonymous users: Y

• Disallow root login remotely: Y

• Remove test database: Y

• Reload privilege tables: Y

2. 配置字符集 (支持中文)

sudo nano /etc/mysql/mariadb.conf.d/50-server.cnf

在 [mysqld] 部分添加/修改以下内容：

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

[mysql]
default-character-set = utf8mb4

保存退出：Ctrl+O -> Enter -> Ctrl+X

3. 重启数据库并验证

sudo service mysql restart
mysql -u root -p
# 输入刚才设置的密码进入数据库
SHOW VARIABLES LIKE 'character_set%'; 
# 确认大部分显示为 utf8mb4
exit;

---

第五步：初始化 Frappe Bench

1. 安装 Bench CLI

uv tool install frappe-bench
# 如果提示找不到 bench 命令，尝试刷新环境变量或重新登录终端
source ~/.bashrc

2. 初始化 Bench 目录

bench init --frappe-branch version-16 frappe-bench
cd frappe-bench

此过程会拉取 Frappe 框架代码，需等待几分钟。

---

第六步：创建站点并安装 ERPNext

1. 创建新站点

bench new-site site1.local

• MySQL root password: 输入你在第四步设置的数据库密码 (Erp@123456)

• Administrator Password: 设置后台管理员密码 (如 admin)

• Select language: 输入 zh 或选择 Chinese (Simplified)

• Region: 输入 CN

• Timezone: 输入 Asia/Shanghai

• Currency: 输入 CNY

2. 获取 ERPNext 应用

由于国内网络原因，建议使用 GitHub 代理或手动克隆。

方法 A：直接获取 (若网络通畅)

bench get-app --branch version-16 erpnext

方法 B：手动克隆 (推荐国内用户)

# 使用代理加速下载
git clone https://ghproxy.net/https://github.com/frappe/erpnext.git --branch version-16 apps/erpnext

# 或者如果没有代理，先克隆到临时目录再移动
# git clone https://github.com/frappe/erpnext.git --branch version-16
# mv erpnext apps/

3. 安装应用到站点

bench --site site1.local install-app erpnext

此过程会自动建表、导入数据，可能需要 5-10 分钟，请耐心等待直到出现 “Updating Dashboard for…” 字样。

---

第七步：启动开发服务器

这是开发环境与生产环境最大的不同点。

1. 启动服务

bench start

此时你会看到大量日志滚动，只要没有红色的 ERROR 或 CRITICAL 报错，且看到 web、worker、socketio 等进程启动成功即可。

2. 访问系统

• 打开浏览器访问：http://localhost:8000

• 用户名：Administrator

• 密码：你在第六步第1小步设置的密码。

---

�� 常见问题排查 (FAQ)

1. Redis 端口占用报错

如果 bench start 报错 Address already in use (端口 11000/13000)，说明上次非正常关闭导致 Redis 残留。 - 解决：按 Ctrl+C 停止当前进程，然后执行：

pkill -f redis
bench start

2. 界面显示英文

如果在创建站点时没选中文，可以在登录后点击右上角头像 -> My Settings -> Language -> 选择 Chinese (Simplified) -> Save。

3. PDF 打印乱码或不显示

开发环境默认未安装 wkhtmltopdf。如需打印功能，请执行：

sudo apt install wkhtmltopdf

4. 如何停止服务？

在运行 bench start 的终端窗口按 Ctrl + C 即可停止。下次使用时再次运行 bench start。