从零搭建 ERPNext V15：Docker 部署完整步骤及常见问题解决（适用于生产环境）

gemhe2cn

4023人浏览 · 2026-01-09 17:01:12

gemhe2cn · 2026-01-09 17:01:12 发布

当你循着标题打开这篇文章时，估计你已经基本知道了ERPNext是什么系统，能做什么事情，有什么优势，所以，我也就不再费劲巴拉地去介绍ERPNext的功能和优点了。

虽然ERPNext = 免费 + 全能 + 好上手，但要很好地、随心所欲地部署好她，还是需要花费一些功夫的。

本文将引导你一步步对ERPNext系统进行个性化部署，避免你踩坑。
注意：本文以ErpNext 15为例说明。

一、部署环境要求

建议在Linux环境下部署，比如Ubuntu，以下文档将以Ubuntu24.04环境为例进行描述。

你的系统必须具备以下应用：

部署资源位于https://github.com/frappe/frappe_docker.git。

你可以克隆该资源到本地，命令如下：

cd ~/
git clone -b v2.0.1 https://github.com/frappe/frappe_docker
cd frappe_docker

以上命令执行完毕，将在当前用户家目录下生成目录“~/frappe_docker”。

其中“~/frappe_docker/docs/”目录下有相关参考文档可以阅读。

二、用于展示的简单部署

如果你只是部署一个临时环境，方便演示、学习和了解ERPNext，而不是用于生产环境，你可以很容易完成部署。

cd ~/frappe_docker
docker compose -f pwd.yml up -d

耐心等待，大概几分钟以后你将可以在本机的浏览器8080端口打开系统界面，使用用户名“administrator”和密码“admin”登录系统，随后你将会享受到ERPNext带来的无限乐趣。

三、个性化环境部署

个性化环境部署ERPNext其实也并不复杂，系统为你考虑了各种情况的部署。在"~/frappe_docker/images"下，系统提供了以下镜像生成文件：

bench

仅搭建 Bench 命令行工具（CLI）。用于开发或调试场景。仅提供命令行工具集，不包含运行时服务。

custom

基于基础 Python 镜像构建的多用途 Python 后端。包含通过 Compose 配置运行 Frappe 实例所需的全部组件，会安装 apps.json 文件中定义的应用。适用于生产和测试环境。当你需要对依赖项（例如尝鲜新版本的 Python 或 Node）进行控制时，该镜像为理想选择。

layered

最终包含的内容与 custom 镜像一致，但基于 Docker Hub 上的预构建镜像构建。非常适合生产环境构建场景，如果你接受由 Frappe 官方管理的依赖版本（可能比较过时），则推荐使用。由于基础镜像层已提前构建完成，因此构建速度会大幅提升。

production

与 custom 镜像类似（基于 Python 基础镜像构建），但仅安装 Frappe 和 ERPNext 核心应用，无法通过 apps.json 进行自定义配置。最适合快速启动或功能探索场景。虽然直译为“生产”，实际并不适合生产环境部署。

本文以下内容将基于你创建的自定义 apps.json 构建 layered 镜像，其它镜像可参照自行学习构建。

1、下载镜像

推荐提前下载必要的docker images，包括：

frappe/build version-15
frappe/base version-15
redis 6.2-alpine
mariadb 11.8

如果使用外部已安装的数据库（mysql、mariadb或Postgres），则无需下载mariadb 11.8；同样，如果使用外部已安装的redis服务，则无需下载。下载命令为：

docker pull frappe/build:version-15
docker pull frappe/base:version-15
docker pull redis:6.2-alpine
docker pull mariadb:11.8

注意：以上redis和mariadb的版本可能会调整，可根据ERPNext要求或推荐下载合适的版本。

2、构建Frappe镜像

ERPNext最新版本中，已经将部分应用分离出来了。在部署系统前，你需要根据企业需求，规划要安装的额外应用。

以下假设需要额外增加安装hrms和payments两个应用。你可以打开https://github.com/frappe/链接了解更多应用。

创建文件“~/frappe_docker/apps.json”，内容如下：

[
    {
        "url": "https://github.com/frappe/erpnext.git",
        "branch": "version-15"
    },
    {
        "url": "https://github.com/frappe/hrms.git",
        "branch": "version-15"
    },
    {
        "url": "https://github.com/frappe/payments.git",
        "branch": "version-15"
    } 
]

执行以下命令，设置环境变量APPS_JSON_BASE64：

export APPS_JSON_BASE64=$(base64 -w 0 ~/frappe_docker/apps.json)

可以用以下命令检查上述命令是否执行正确：

echo -n ${APPS_JSON_BASE64} | base64 -d

如果显示的内容与文件“~/frappe_docker/apps.json“内容一致，则环境变量设置成功。

接下来生成自己的镜像

    docker build \
     --build-arg=FRAPPE_PATH=https://github.com/frappe/frappe \
     --build-arg=FRAPPE_BRANCH=version-15 \
     --build-arg=APPS_JSON_BASE64=$APPS_JSON_BASE64 \
     --tag=myimages/custom:1.0.0 \
     --file=images/layered/Containerfile .

这条命令执行时间会比较长，生成过程会自动下载各类资源，所以必须保证你的计算机互联网连接正常。执行过程中如果出现错误，一般是因为资源下载的问题，可以检查网络后试着重新执行，直到正常执行完毕。

可以通过docker images命令查看构建镜像的结果，如果看到--tag指定的镜像，则构建成功：
在这里插入图片描述

3、创建环境变量

接下来执行以下命令，用于使用模板生成环境变量文件：

cd ~/frappe_docker/
cp example.env custom.env

custom.env就是我们后续要使用的环境变量文件。用vi或你熟悉的编辑器修改“~/frappe_docker/custom.env”文件（命令为vi ~/frappe_docker/custom.env），参考以下内容：

…
DB_PASSWORD=root123
DB_HOST=
DB_PORT=
…
REDIS_CACHE=
REDIS_QUEUE=
…
FRAPPE_SITE_NAME_HEADER=frontend
…
CUSTOM_IMAGE=myimages/custom
CUSTOM_TAG=1.0.0
PULL_POLICY=missing
…

以上配置假设使用新创建的基于docker的mariadb数据库，且数据库root用户密码设置为”root123“，可根据需要调整，但注意后续密码设置必须一致。

如果使用已有的外部数据库，则DB_HOST后填写数据库IP地址，比如：”DB_HOST=192.168.10.12“；DB_PORT后填写数据库端口号，比如：“DB_PORT=3306”；DB_PASSWORD后填写管理员用户root的登录密码，如果数据库管理员密码是加密文件，则需要在“DB_PASSWORD_SECRETS_FILE=”参数后填写文件路径和名称。

如果使用外部的redis服务，则“REDIS_CACHE”后填写用于缓存的 Redis 主机名；“REDIS_QUEUE”后填写用于任务队列和实时更新的 Redis 主机名。

“FRAPPE_SITE_NAME_HEADER=”后边必须填写“frontend”，否则部署后网站无法访问。原因我目前也没搞明白，有兴趣可以查阅相关资料。

“CUSTOM_IMAGE”和“CUSTOM_TAG”是生成镜像的名称和版本，可以根据你的喜好设置。“PULL_POLIY”设置为“missing”以优先使用本地镜像。

其它参数可以参阅相关文档，本文不再赘述。

4、创建最终的 Compose 文件

执行以下命令

cd ~/frappe_docker/
docker compose --env-file custom.env \
  -f compose.yaml \
  -f overrides/compose.mariadb.yaml \
  -f overrides/compose.redis.yaml \
  -f overrides/compose.noproxy.yaml \
  config > compose.custom.yaml

上述命令将生成“~/frappe_docker/compose.custom.yaml”文件。

以上参数使用请注意：

如果使用已有的外部数据库，则删除“-f overrides/compose.mariadb.yaml”一行内容。

如果使用已有的redis服务，则删除“-f overrides/compose.redis.yaml”一行。

使用“-f overrides/compose.noproxy.yaml”参数将不通过反向代理，直接将应用暴露在 8080 端口；而如果使用 Traefik 作为 HTTP 反向代理，监听 80端口，则使用“-f overrides/compose.proxy.yaml”参数；而如果使用 Traefik 作为 HTTPS 反向代理，监听443端口，并自动将 HTTP 请求重定向至 HTTPS，则使用“-f overrides/https.proxy.yaml”。

其它参数可参阅资源文档。

5、启动容器

现在，你就可以启动容器了。执行以下命令部署并启动容器：

cd ~/frappe_docker/
docker compose -p frappe -f compose.custom.yaml up -d

正常情况下，你将看到如下结果：
在这里插入图片描述

如果你的服务器配置低运行速度慢，数据库服务启动后的健康检测可能超时，将出现如下结果：
在这里插入图片描述
此时，你可以等待一会后用docker ps查看frappe-db-1的状态，直到其状态显示Healthy，然后执行以下命令重启服务：

docker compose -p frappe -f ~/frappe_docker/compose.custom.yaml restart

顺便介绍一下相关服务启停和重新部署的命令。

停止服务，使用以下命令：

docker compose -p frappe -f ~/frappe_docker/compose.custom.yaml stop

重新启动服务，使用以下命令：

docker compose -p frappe -f ~/frappe_docker/compose.custom.yaml restart

如果需要重新部署容器，则需要删除所有容器。停止和删除容器的命令为：

docker compose -p frappe -f ~/frappe_docker/compose.custom.yaml down

注意，重新部署和启动容器前需要删除所有已有的重名卷，命令如下：

docker volume rm frappe_docker_db-dat
docker volume rm frappe_docker_redis-queue-data
docker volume rm frappe_docker_sites

6、创建站点并安装应用

此时 Frappe 已启动，但尚未完成配置。你需要创建一个站点并安装所需应用。

首先需要创建站点。在确保上节所属容器都启动正常后，执行以下命令：

docker compose -p frappe exec backend bench new-site \
  --mariadb-user-host-login-scope='%' \
  --admin-password=admin \
  --db-root-username=root \
  --db-root-password=root123 \
  --install-app erpnext \
  --set-default frontend

注意上边的“db-root-username”和“db-root-password”是数据库管理员用户名和密码，必须与之前配置一致。

“admin-password”是网站管理员密码，指定后需牢记，首次管理员账号登录时要填写。

如果命令执行后你看到以下信息，祝贺你，基础平台frappe和基础应用erpnext安装完成：
在这里插入图片描述
接下来继续安装应用，参考之前构建镜像时创建的apps.json中的应用进行安装，命令如下：

docker compose -p frappe exec backend bench --site frontend install-app hrms
docker compose -p frappe exec backend bench --site frontend install-app payments

如果看到以下结果，祝贺你额外的应用安装也完成了
在这里插入图片描述