ERPNext v16 · Wiki

ERPNext 安装教程：Ubuntu + Docker 部署 checklist

Q: ERPNext 升级前要做什么？

先备份数据库和站点文件，确认版本兼容性，在测试环境跑一遍升级和关键业务流程，再安排维护窗口操作。

ERPNext v16 在 Ubuntu 上用 Docker 部署的 checklist：服务器准备、Compose 启动、建站、HTTPS、备份和常见报错。

更新于 2026-11-04 约 9 分钟 15 篇文档

这篇不是官方文档的替代，而是一份部署 checklist。我把它分成“准备、启动、建站、反代、备份”五段，目的是让你知道每一步在做什么，以及容易卡在哪里。具体命令请以当前版本的 frappe_docker 官方 README 为准。

适用场景：小团队、单机或少量节点、想用 Docker 快速跑起 ERPNext。如果你需要多租户、高可用或深度定制，建议先看官方生产部署文档，再决定是否用 bench 原生部署。

一、先确认版本和部署方式#

ERPNext 常见有两种部署方式：Docker Compose 和 bench 原生部署。 Docker 的好处是依赖打包好、迁移方便；坏处是出问题时需要同时懂 Docker 和 Frappe。 bench 更贴近开发环境，但对 Ubuntu 版本、Python、Node、MariaDB 的版本匹配要求更高。

方式	适合	注意
Docker Compose	快速上线、单机、小团队	数据卷、备份、升级要提前规划
bench 原生	开发、定制、多站点	依赖多，版本升级容易踩坑

二、准备服务器#

系统：Ubuntu 22.04/24.04 LTS，64 位。
配置：测试 2 核 4G 起步；正式使用建议 4 核 8G，磁盘留足备份空间。
域名：准备一个子域名，例如 erp.example.com，提前解析到服务器。
端口：80/443 对外，数据库和 Redis 不要暴露到公网。
时区：建议统一为 Asia/Shanghai，避免单据时间和报表对不上。

# 以 Ubuntu 为例
sudo timedatectl set-timezone Asia/Shanghai
sudo apt update
sudo apt install -y git curl ca-certificates

三、安装 Docker 和 Compose#

用 Docker 官方脚本安装最简单，但生产环境建议先看官方文档，确认版本和仓库来源。

curl -fsSL https://get.docker.com | sudo sh
sudo systemctl enable --now docker
docker --version
docker compose version

装完后用 docker run hello-world 验证。如果服务器在国内，拉取镜像可能较慢，可以配置镜像加速，但要注意镜像源的可靠性。

四、获取 frappe_docker 并配置#

git clone https://github.com/frappe/frappe_docker.git
cd frappe_docker
cp example.env .env

编辑 .env，至少确认数据库密码、站点名、时区、管理员密码等变量。不要把 .env 提交到 Git，也不要把数据库端口映射到公网。

注意：frappe_docker 的 compose 文件会随版本调整，不要直接照抄旧教程里的文件名。以仓库当前 README 为准，先用 docker compose config 检查配置。

五、启动服务#

常见的组合是 MariaDB + Redis + 后端 + 前端 + 队列。如果前面已有 Nginx 做 HTTPS，可以用 compose.noproxy.yaml 只暴露后端端口。具体文件组合以官方文档为准，下面只是示意：

docker compose --project-name erpnext \
  -f compose.yaml \
  -f overrides/compose.mariadb.yaml \
  -f overrides/compose.redis.yaml \
  -f overrides/compose.noproxy.yaml up -d

docker compose --project-name erpnext ps

第一次启动会拉取镜像、初始化数据库，时间取决于网络和磁盘。用 docker compose logs -f backend 看启动日志，确认没有数据库连接错误。

六、创建站点#

服务起来后，创建第一个站点。站点名通常就是域名，数据库 root 密码和管理员密码要换成你自己的强密码。

docker compose --project-name erpnext exec backend \
  bench new-site erp.example.com \
  --mariadb-root-password '你的数据库root密码' \
  --admin-password '你的管理员密码'

创建完成后，把站点设为默认站点，并确认 scheduler、worker 正常运行。如果页面能打开但后台任务不跑，先看 worker 和 scheduler 的日志。

七、反向代理和 HTTPS#

生产环境不建议直接把 8000 端口暴露到公网。用 Nginx 监听 80/443，再把请求转发到 Frappe 前端端口，证书可以用 Let's Encrypt。

# Nginx 站点示例（片段）
server {
    listen 80;
    server_name erp.example.com;
    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

注意 Frappe 对 Host 和 X-Forwarded-Proto 比较敏感，配错会出现站点找不到、静态资源 404 或登录后跳回 http。配完先用 curl -I https://erp.example.com 检查响应头。

八、初始化与备份#

站点能登录后，不要急着录业务数据。先做三件事：

按初始化顺序建公司、财年、科目、仓库、物料和客商。
用采购到入库跑一笔测试业务，确认库存和财务都过账。
配置自动备份，并实际恢复一次，确认备份文件可用。

# 备份命令示例，具体路径以你的 compose 项目为准
docker compose --project-name erpnext exec backend \
  bench --site erp.example.com backup --with-files

备份不要只留在服务器本机。至少同步到另一台机器或对象存储，并定期检查备份文件大小和恢复结果。升级前一定先备份，具体检查项可以看备份与升级。

九、常见卡点#

现象	常见原因	排查方向
站点打不开	Host 或站点名不匹配	检查 Nginx Host、site_name、DNS
数据库连接失败	密码、服务名、网络不对	看 backend 日志和 MariaDB 日志
静态资源 404	反代路径或 build 未完成	检查 `bench build` 和 Nginx 配置
后台任务不跑	worker/scheduler 未启动	看 compose ps 和队列日志
磁盘满	镜像、日志、备份堆积	清理旧镜像和日志，迁移备份

最后提醒一句：部署只是开始，真正影响使用的是主数据和流程。装好之后建议先读先理解单据流，再按初始化顺序一步步来。

常见问题#

ERPNext 用 Docker 还是 bench 部署？

想快速上线、单机小团队可以优先用 Docker Compose；需要深度定制、多站点或开发环境，bench 更灵活，但依赖和版本管理更复杂。

ERPNext 最低需要什么配置？

测试环境 2 核 4G 可以起步，正式使用建议 4 核 8G，并预留磁盘空间给数据库、镜像和备份。

ERPNext 安装后打不开怎么办？

先看 backend 日志和 Nginx 配置，重点检查站点名、Host、X-Forwarded-Proto、数据库连接和静态资源构建。

ERPNext 升级前要做什么？