简介：基于VMware虚拟机环境，以Ubuntu 22.04为操作系统，文档聚焦如何用Docker快速部署ERPNext 14全功能ERP系统，面向需要轻量搭建业务管理环境的运维人员、中小型企业IT管理员，以及学习开源ERP的开发者，可显著降低从零配置的时间成本。资源包内包含1个docx文档，约321KB，已获得629人浏览学习。文档按实际安装顺序记录，从Git安装、Docker与Docker Compose部署，到配置daemon.json镜像加速器解决拉取失败问题，再通过汉化开箱即用版完成ERPNext 14的启动与初始化。每一步都列出命令与验证方法，并针对阿里云源、GPG密钥、用户组权限及镜像加速配置等易错环节做了详细说明。读者只需跟随文档操作，即可在虚拟机中跑通包含财务、销售、库存等模块的ERP系统，并为后续扩展容器化应用打下基础，方便根据业务变化快速调整部署规模。
1. 虚拟机跑 ERPNext 14：为什么说是最省心的开源 ERP 落地方式
ERPNext 14 是目前开源 ERP 里少有的、能在一个晚上装完并跑起来的完整业务系统，覆盖财务、采购、销售、库存、HR、制造这些核心模块。它基于 Frappe 框架，和传统那种"一个安装包点下一步"的 ERP 完全不同——它是一套 Python 应用加 MariaDB 数据库加 Redis 缓存加前端静态资源的组合体。正因为组件多，直接装在物理机上反而容易把环境搞乱，虚拟机里用 Ubuntu 22.04 做承载，是目前社区里最主流、踩坑最少的路径。我一般会选 VirtualBox 或 VMware 装一台最小化 Ubuntu 22.04 Server，给 4 核 CPU、8G 内存、80G 磁盘，这个配置跑 demo 或小团队内部使用完全够。这套方案最吸引人的地方是：快照功能让你在安装前随便折腾，装坏了回滚就行，这对第一次接触 ERPNext 的人来说是巨大的心理安慰。
整个安装过程不需要编译源码，官方提供了 installer 脚本和生产环境用的 easy-install 脚本；如果你只是想快速看效果，还可以用 docker-compose。但注意，docker 方式跑 ERPNext 14 在低配虚拟机上性能损耗明显，而且数据卷备份恢复比裸装复杂。所以这篇文章的路线是：Ubuntu 22.04 虚拟机 + 官方生产安装脚本 + 手动修正几个脚本覆盖不到的环节。你会看到从零到能登录系统、创建公司的完整路径，以及我实际踩过的坑——尤其是 Python 版本、Node.js 版本、以及 MariaDB 配置这三个最容易让人卡住的地方。
2. 先搞懂 ERPNext 14 的组件结构：安装本质是在装什么
2.1 五个核心组件各自的角色
ERPNext 14 不是单一程序，而是一套各司其职的组件协同工作。搞清楚它们的分工，后续排错才能不抓瞎。第一是MariaDB 数据库：ERPNext 所有业务数据都存在这里，包括单据、账目、序列号、权限设置。ERPNext 14 对 MariaDB 版本有要求，Ubuntu 22.04 默认仓库里的版本通常够用；第二是Redis，它承担两类职责——缓存常用查询结果、以及作为后台任务队列的消息代理，安装时会启动两个 Redis 实例，分别用不同的端口；第三是Node.js 与 Yarn：ERPNext 14 的前端资源（JavaScript 和 CSS 打包）依赖 Node 环境，生产安装脚本会要求 Node 14 或 16，Ubuntu 22.04 默认源里的 Node 12 就是不行的，这是第一个容易翻车的点；第四是Python 3.10 与 Frappe Framework：整个 ERPNext 的 Web 后端基于 Frappe，用 pip 以开发模式安装到 bench 管理的虚拟环境里；最后是Nginx 与 Supervisor：前者做反向代理和静态文件服务，后者守护后端进程和后台任务进程，保证系统重启后服务自动拉起。
这五个组件的安装顺序基本是固定的：先装系统依赖，再装数据库和缓存，最后通过 bench 命令初始化站点和安装 ERPNext。官方 installer 脚本会自动完成大部分步骤，但它的执行时间和网络状况关系很大，国内网络环境下经常卡在 apt 源或 pip 源上。我习惯的做法是：不直接用官方的一键脚本，而是手动执行每一步。虽然命令多一点，但每一步失败都能立刻定位到原因，不会被一个中途失败的大脚本卡住不知道从哪查起。
2.2 为什么选 Ubuntu 22.04 而不是其他版本
ERPNext 14 官方支持列表里明确写了 Ubuntu 20.04 和 22.04。选 22.04 而不是 20.04 的理由很实际：22.04 自带 Python 3.10，正好满足 Frappe 框架对 Python 版本的要求，省去用 pyenv 编译老版本 Python 的麻烦。而 Ubuntu 22.04 的 Node.js 版本是 12，不符合要求，需要手动加 NodeSource 源装 Node 16，这刚好是官方脚本没处理好的地方之一，后面会有详细步骤。如果你用 CentOS 或 Debian，不是说不行，但社区里踩坑记录的密度明显更高，很多报错信息搜出来的解决方案都是基于 Ubuntu 的，没必要给自己加难度。虚拟机上装 Ubuntu 22.04 Server 版就好，不需要图形界面，能省下 1G 左右内存给 ERPNext。
2.3 虚拟机资源配置的底线与推荐值
ERPNext 14 对资源的需求不是线性增长的——登录页和简单单据录入时占用很低，但报表查询和后台任务批量运行时 CPU 会瞬间拉满。我的经验是：2 核 4G 内存能跑，但只能算"能启动"；4 核 8G 才是舒服的起点。磁盘方面，Ubuntu 22.04 系统本身占 5G 左右，ERPNext 源码和虚拟环境加起来大约 3G，但数据库和文件存储会慢慢涨，所以 80G 是比较合理的预留。虚拟机的网络模式建议选"桥接"而不是 NAT，这样同一个局域网里的其他机器也能直接访问 ERPNext 的 Web 界面；如果只用 NAT，后续做测试还得配端口转发，多一层麻烦。
还有一个小经验：虚拟机的 CPU 设置里，最好开启"嵌套虚拟化"或者给够双核以上的真实核心。ERPNext 的搜索索引和报表引擎在单核虚拟机上反应很慢，虽然不影响数据正确性，但页面加载时间会长到让人怀疑装坏了。
3. 从零开始安装：完整命令与每一段的坑
3.1 系统更新与创建专用用户
安装 ERPNext 之前先把系统基础环境准备好。这里有个关键决定：绝对不要用 root 直接跑安装。bench 管理工具在 root 下会有权限混乱的问题，后续升级和备份会出现莫名其妙的文件属主错误。我一般先创建一个 sudo 用户。
# 更新软件源并升级现有软件包 sudo apt update && sudo apt upgrade -y # 安装基础工具，curl 和 git 后续都会用到 sudo apt install -y curl git build-essential # 创建 erpnext 用户并加入 sudo 组，用于后续所有操作 sudo adduser erpnext sudo usermod -aG sudo erpnext # 切换到新用户，确认环境干净 su - erpnext这段命令的逻辑很简单：先保证系统软件源是新的，再装编译工具——因为后续 pip 安装某些 Python 包时需要编译原生扩展。创建单独的 erpnext 用户是为了隔离权限，就算 ERPNext 被入侵，攻击者也只拿到普通用户权限，而不是 root。需要留意的是：adduser 命令会交互式询问密码等信息，密码至少要 8 位，后续使用 sudo 时还会再确认一次密码。
3.2 安装 Python 3.10、Node.js 16 和 Redis
Ubuntu 22.04 自带 Python 3.10，所以 Python 部分只需要确认版本即可，真正需要手动处理的是 Node.js。ERPNext 14 要求 Node 14 或 16，默认源里只有 12，不升级的话前端打包会直接报语法错误。下面是完整操作：
# 确认 Python 版本，3.10 是 ERPNext 14 的推荐版本 python3 --version # 安装 pip 和虚拟环境工具 sudo apt install -y python3-pip python3-venv python3-dev # 配置 NodeSource 仓库并安装 Node.js 16 curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash - sudo apt install -y nodejs # 安装 yarn 作为前端包管理器，安装 redis 做缓存和队列 sudo npm install -g yarn sudo apt install -y redis-server # 验证版本 node --version yarn --version redis-cli ping这段的顺序是有讲究的：先装 Python 开发头文件（python3-dev），否则后续 pip 安装 psutil、gevent 这类需要编译的包时会失败；NodeSource 仓库是官方维护的，比用 nvm 自己编译省事得多。最后用 redis-cli ping 验证 Redis 是否返回 PONG，是的话就说明 Redis 服务已正常启动。这里有第一个容易踩的坑：如果系统之前装过旧版 Node，安装新版本后要确认 /usr/bin/node 指向的是 16，可以用 which node 查看路径。
3.3 安装 MariaDB 并配置字符集
MariaDB 是 ERPNext 的数据核心，安装本身不难，但配置上有两个关键点：字符集必须是 utf8mb4，排序规则必须是 utf8mb4_unicode_ci，否则 ERPNext 安装时会拒绝创建数据库。直接用默认配置的话，插入中文数据可能出现乱码或排序问题。
# 安装 MariaDB 服务端和客户端 sudo apt install -y mariadb-server mariadb-client # 启动服务并设置开机自启 sudo systemctl start mariadb sudo systemctl enable mariadb # 执行安全初始化，按提示设置 root 密码 sudo mysql_secure_installationmysql_secure_installation 会问你一系列问题，包括是否设置 root 密码、是否移除匿名用户、是否禁止 root 远程登录——这些全部都选 yes 就行。接下来是最关键的手动配置：
# 编辑 MariaDB 配置文件 sudo nano /etc/mysql/mariadb.conf.d/50-server.cnf在[mysqld]段落里加入或修改以下内容：
[mysqld] character-set-server = utf8mb4 collation-server = utf8mb4_unicode_ci innodb-file-format = barracuda innodb-file-per-table = 1 innodb-large-prefix = 1然后重启 MariaDB 并验证配置：
sudo systemctl restart mariadb # 登录检查字符集设置 sudo mysql -u root -p登录后执行：
SHOW VARIABLES LIKE 'character_set_server'; SHOW VARIABLES LIKE 'collation_server';如果输出的字符集是 utf8mb4、排序规则是 utf8mb4_unicode_ci，这一步就通过了。我遇到过的情况是：配置文件改了但忘记重启，结果 ERPNext 安装时仍提示 "Collation not supported"，排查了半小时才发现是服务没重启。所以这一步务必重启后再验证。
3.4 安装 Frappe Bench 并初始化 ERPNext 14
Frappe Bench 是管理 ERPNext 生命周期的核心工具，它负责创建项目目录、管理虚拟环境、安装应用、创建站点、启动开发服务器或配置生产环境。首先安装它：
# 全局安装 frappe-bench sudo -H pip3 install frappe-bench # 验证安装成功 bench --version然后初始化一个 bench 目录，并获取 ERPNext 14 的代码：
# 创建 bench 目录，名字可以自定义，但建议用 frappe-bench mkdir ~/frappe-bench && cd ~/frappe-bench # 初始化 bench 环境，拉取 frappe 框架代码 bench init --python python3.10 --version version-14 frappe-bench初始化过程会创建虚拟环境、安装 Python 依赖、下载并且构建前端资源，时长取决于网络状况，通常在 10 到 30 分钟之间。如果中途失败，最常见的原因是 pip 下载超时，解决方案是配置国内 pip 镜像：
pip3 config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple然后重新执行 bench init。这个命令里的--version version-14是指拉取 Frappe 框架的 version-14 分支，不是 ERPNext 应用的版本；ERPNext 自身在下一步下载。
3.5 安装 ERPNext 应用到 bench 并创建站点
bench init 完成之后，需要把 ERPNext 应用本身装进 bench 环境：
# 进入 bench 目录 cd ~/frappe-bench/frappe-bench # 从 GitHub 拉取 ERPNext 的 version-14 分支 bench get-app erpnext --branch version-14这个命令会把 ERPNext 源码下载到apps/erpnext目录。下载完成后创建站点——站点是 ERPNext 的数据容器，一个 ERPNext 安装可以跑多个站点，每个站点有独立的数据库和配置：
# 创建新站点，用 yourdomain.com 替换成你自己的域名或 IP 用途名 bench new-site yourdomain.com --db-root-password 你的数据库root密码执行后会提示设置管理员（Administrator）密码，这个密码就是将来登录 ERPNext 的初始管理员密码，务必记牢。创建成功后，把 ERPNext 应用安装到这个站点上：
# 安装 ERPNext 应用到站点，这一步会创建数据库表并初始化数据 bench --site yourdomain.com install-app erpnextinstall-app 执行时间较长，通常在 5 到 15 分钟之间，取决于虚拟机性能。完成后你会看到数据库表创建和初始化数据的日志输出。最后启动开发模式验证：
# 以开发模式启动，便于验证安装是否正确 bench start3.6 生产模式部署：Nginx 与 Supervisor 配置
bench start 启动的是开发服务器，性能差且不支持后台任务守护，生产环境必须切换为生产模式。这里用官方提供的命令，它会自动生成 Nginx 配置和 Supervisor 进程配置：
# 切换到生产模式 sudo bench setup production erpnext这一步会自动配置 Nginx、Supervisor，并重启相关服务。如果执行成功，浏览器访问http://yourdomain.com就能看到 ERPNext 的登录页面。常见问题是服务器上的 80 端口被占用，这时候需要先停掉占用进程或者改 Nginx 配置。
3.7 防火墙规则与 HTTPS 跳转
生产模式下，防火墙是必配项。如果虚拟机开了 ufw，需要放行 HTTP 和 HTTPS 端口：
sudo ufw allow 80/tcp sudo ufw allow 443/tcp sudo ufw enable另外，默认生产配置会把所有 HTTP 请求跳转到 HTTPS，这在没有配置 SSL 证书时会导致访问返回重定向循环错误。如果暂时不配证书，可以把跳转关掉：
# 修改 Nginx 配置文件 sudo nano /etc/nginx/sites-available/erpnext找到包含return 301 https://的行并注释掉。重启 Nginx：
sudo systemctl restart nginx然后直接访问http://yourdomain.com就能看到登录页了。
4. 必踩的五个坑：现象、原因与解决办法
4.1 坑一：Node.js 版本过低导致前端构建失败
现象：执行bench build或bench init过程中，前端资源构建步骤报出SyntaxError: Unexpected token或类似 JavaScript 解析错误，构建过程中断。
原因：系统默认 Node.js 版本是 12，而 ERPNext 14 的前端代码使用 Node 14 以上才支持的语法特性，Node 12 解析时会直接报错。如果之前用过 apt 装过 nodejs，版本可能更低。
解决：用 NodeSource 仓库安装 Node.js 16，并确认/usr/bin/node指向的是 16 而不是旧版本。装好后执行node --version确认输出 v16.x，再重新执行bench build。如果之前构建失败导致依赖缓存混乱，可以先删除node_modules目录再重建。
4.2 坑二：MariaDB 字符集配置不生效
现象：执行bench new-site时提示Collation not supported，或者安装 ERPNext 后中文内容出现乱码、排序异常。
原因：MariaDB 收到了连接请求中的字符集配置，但服务器端默认字符集仍然是 latin1 或 utf8mb3，导致 ERPNext 的建库语句执行失败。
解决：修改/etc/mysql/mariadb.conf.d/50-server.cnf文件后，先重启 MariaDB，再去 mysql 命令行里用SHOW VARIABLES LIKE 'character_set_server';确认配置真正生效。不要只改配置文件不重启就继续跑安装——这个问题我在 4.1 节里也提到了，但它的变种之多值得再单独强调一次。
4.3 坑三：中文用户名或数据写入报错
现象：创建客户、供应商或物料时输入中文，保存后提示Data too long或直接报 500 错误，查看日志发现是数据库层面报错。
原因：建库时字符集用对了，但某个表或字段的排序规则是旧的utf8mb3_general_ci，与全局utf8mb4_unicode_ci不一致，导致写入数据时发生隐式转换失败。
解决：最彻底的方法是重建数据库：先bench drop-site再bench new-site，确保从一开始就使用正确的字符集。如果已经积累了数据不想丢，可以用ALTER DATABASE和ALTER TABLE修改排序规则，但操作复杂，不如重建干净。
4.4 坑四：pip 下载超时导致安装中断
现象：bench init或install-app过程中，日志停在Downloading...或直接报ReadTimeoutError，安装进度卡住不动。
原因：Python 包默认从官方 PyPI 源下载，国内网络环境下访问不稳定，大包如 torch、pandas 等下载经常超时。
解决：提前配置 pip 使用清华大学或阿里云的镜像源，具体命令已在前面给出。配置后再执行bench init，速度会明显提升。如果中途失败，重新运行命令时会从上一步继续，不需要完全重来。
4.5 坑五：虚拟机快照回滚后服务无法启动
现象：安装过程中发现搞乱了配置，直接回滚到安装前的快照，但重新执行安装命令时报错说某些文件已存在或服务端口被占用。
原因：快照回滚不会恢复 Redis 或 MariaDB 的 socket 文件状态，有时候进程虽然列表里没有，但 socket 文件还存在；也可能 bench 目录里的部分文件在快照前已经创建，回滚后处于版本不一致的状态。
解决：回滚后先执行sudo systemctl stop mariadb redis-server并删除/run/mysqld/mysqld.sock（如果存在），再把整个~/frappe-bench目录删掉重新执行安装。虽然多花时间，但环境是干净的，比在旧基础上试着修要省心。
5. 安装后的必要检查：确认系统真的活着
5.1 检查进程是否全部在跑
安装完成后，用 supervisorctl 或系统服务命令检查所有关键进程的状态：
# 查看 supervisor 管理的进程状态 sudo supervisorctl status正常情况下至少应该看到这些进程在运行(RUNNING)：nginx 由系统管理，而 ERPNext 相关的有 frappe 的 web 进程、worker 进程、schedule 进程。如果某个进程显示 FATAL，直接用sudo supervisorctl restart 进程名重启。如果 restart 后还是 FATAL，查看对应日志，路径通常在~/frappe-bench/frappe-bench/logs/目录，按进程名区分文件。
5.2 验证 Web 前端可访问
浏览器访问http://yourserver-ip-or-domain，应该看到 ERPNext 的登录界面。登录界面上会显示版本号，确认是 14.x 而不是 13 或 15。用之前设置的 Administrator 密码登录，进入系统后创建一个公司（Company）——如果公司创建成功，说明数据库读写正常；如果保存时报错，优先检查 MariaDB 的字符集和排序规则设置。
5.3 验证后台任务调度正常
ERPNext 大量功能依赖后台定时任务，比如邮件通知、自动记账、库存重算。检查后台任务是否在跑：
# 查看 bench 的 schedule 日志 tail -f ~/frappe-bench/frappe-bench/logs/schedule.log正常时每 1 分钟左右会出现一次任务循环执行的日志。如果日志停在一个错误上不动，最常见的错误是 Redis 连接失败。检查 Redis 是否在运行，再确认~/frappe-bench/frappe-bench/sites/common_site_config.json文件里的 redis 配置是否指向正确端口。这个文件里的配置是安装时自动生成的，通常不需要手动改，但如果 Redis 端口被其他服务占用导致指向不同实例，就会在这里卡住。
5.4 备份与恢复的最小约定
确认系统能跑之后，立刻做一次备份并测试恢复，这是一条保命绳。
# 在 bench 目录下执行备份 cd ~/frappe-bench/frappe-bench bench --site yourdomain.com backup备份完成后，backups/目录下会出现数据库备份和文件备份两个文件。把这俩文件复制到虚拟机外的位置，比如宿主机或网络存储。备份很快，但恢复才是关键：
# 先建一个空数据库再恢复 bench --site yourdomain.com restore backups/备份文件路径如果恢复过程中出现字符集报错，大概率又是排序规则问题，按前面第 4.3 节的方法重建即可。备份这件事，建议固定每周一次，配置 cron 自动执行，别等数据丢了再后悔。
6. 让 ERPNext 14 真正跑顺的四个常用参数与技巧
生产环境安装完成后，有几项配置能显著提升使用体验和运维便利性。第一项是Nginx 的上传大小限制，默认 1MB 对于传图片和附件有时不够，可以改到 20MB。编辑/etc/nginx/sites-available/erpnext文件，在server块里加上client_max_body_size 20m;然后重启 Nginx。第二项是系统设置里的 Session 过期时间，登录后在「设置」->「系统设置」里找到 Session Expiry，默认 6 小时，如果是内部使用可以扩到 24 小时，省得员工总被踢下线。
第三项是bench 的 auto update 设置。ERPNext 的版本更新频率不算低，但生产环境不建议天天拉新代码，毕竟业务数据不敢开玩笑。把~/frappe-bench/frappe-bench/sites/common_site_config.json里的auto_update改成false，然后用 cron 定期手动执行更新：
# 手动更新 ERPNext 和 Frappe 框架 cd ~/frappe-bench/frappe-bench bench update --pull --build --migrate这个命令会先同步代码，再重新构建前端资源，最后执行数据库迁移。执行前务必先做一次完整备份，迁移过程如果有报错，立刻停止并检查数据库。
第四项是Gunicorn worker 数量，它直接决定 ERPNext 能同时处理多少请求。配置文件在~/frappe-bench/frappe-bench/sites/common_site_config.json里，默认 worker 数量是 CPU 核心数乘以 2 加 1。4 核虚拟机默认就是 9 个 worker，但每个 worker 会占 300 到 500MB 内存，加上后台 worker 和 Redis，内存很快就吃紧。如果你的虚拟机是 4 核 8G，建议把 gunicorn worker 数手动改成 5，给后台任务留出内存余量。修改后重启进程：
sudo supervisorctl restart frappe-web还有一个纯粹基于经验的做法：登录 ERPNext 后，先别急着录数据，把「设置」->「公司设置」里的默认货币、时区、会计科目模板一次性配好。因为 ERPNext 的会计模块预设一套科目后，后面再改科目结构会比较麻烦。配好之后再创建第一个用户，用这个用户测试完整的采购到付款流程，确认所有环节都跑通了，再正式投入使用。
我在多次安装部署中形成的习惯是：每做一步环境变更，先做一次数据库备份并打个快照。这样即便后面的操作翻车，也能快速回到一个已知正常的状态继续排查，而不是从头再来一遍。ERPNext 14 在 Ubuntu 22.04 上跑起来之后是相当稳定的，偶尔重启虚拟机它也能自己恢复服务，只要 Supervisor 配置没有问题。希望这篇文章能帮你在 ERPNext 的路上少走一些弯路，顺利把自己的业务流程跑起来。
本文还有配套的精品资源，点击获取
