SSD Nodes Learn Hosting plans →
指南 Matt Connor作者: Matt Connor

Docker VPS 自托管 ERPNext:配置、备份与恢复

了解 ERPNext 的 11 容器 Docker 堆栈、VPS 配置、TLS、邮件、版本固定与恢复验证。1 GB 或 2 GB 内存可能触发 OOM,容器退出码为 137。

您将运行的系统

在 VPS 上自行托管 ERPNext 是一项运维工作,不是执行一条命令即可完成的安装。官方 Docker Compose 堆栈包含 11 个容器,其中保存总账和客户记录。因此,下面所有操作都必须遵循更高标准:备份经过恢复验证后,才算真正的备份;未固定版本的镜像标签,则可能随时触发数据库架构迁移。

文中会反复出现几个名称。ERPNext 是业务应用程序。Frappe 是其底层的 Python 框架。Bench 是用于管理站点的命令行工具,已安装在容器内。站点 是一个租户:包含一个 MariaDB 数据库和一个上传文件目录。本文几乎所有命令都在 backend 容器内通过 bench 针对一个指定站点执行。

本指南使用 frappe_docker 仓库,这是项目维护的部署方案。下面的每条命令都已在 2026 年 8 月针对该仓库进行验证。如果您不熟悉 Docker Compose,在 VPS 上运行 Docker Compose 介绍了本指南所需的基础知识。

ERPNext 需要多大的 VPS?

图表ERPNext sizing starting points (guidance, not a measurement)
此图表背后的数据
[
  {
    "label": "Evaluation",
    "vcpu": 2,
    "ram_gb": 4,
    "disk_gb": 40
  },
  {
    "label": "Small production",
    "vcpu": 4,
    "ram_gb": 8,
    "disk_gb": 100
  },
  {
    "label": "Room to grow",
    "vcpu": 4,
    "ram_gb": 16,
    "disk_gb": 160
  }
]

用于评估时,请从 2 vCPU 和 4 GB RAM 开始。这是评估配置。这些数值只是起点,并非本指南测量得出的结果;实际需求取决于您自己的文档数量。最后一行完全不是官方公布的最低配置。它只是提供更多内存余量,不能保证内存永远不会耗尽。

请如实评估小型配置。1 GB 或 2 GB 的 VPS 很难为 10 个长期运行的容器、MariaDB 的缓冲池,以及正在生成报表的 Python worker 同时提供足够余量。内存压力过大时,内核的 out of memory killer 可能会停止某个容器,此时 docker inspect 会显示 "OOMKilled": true,退出代码为 137。worker 在任务执行过程中被终止后,已提交的文档可能只完成了一半后台处理。

如果公司每天使用 ERPNext,请从 8 GB RAM、4 vCPU 和 100 GB SSD 开始规划,然后测试您的工作负载。RAM 通常会先耗尽。磁盘增长速度往往超出预期,因为每个附件和每个本地备份都会与数据库存储在同一个卷上。

11 个容器及其作用

堆栈启动且 10 个容器正在运行后,运行 docker compose ps。另一个容器 configurator 只执行一次任务,然后退出。11 个容器的总数正是由此而来。

  • backend 使用 gunicorn 运行 Frappe 应用。bench 位于此处。
  • frontend 是 nginx。它提供静态资源,并将其他请求转发到后端。
  • queue-short 和 queue-long 是 RQ(Redis Queue)worker。它们运行后台任务,例如发送邮件、导入数据和生成报表。
  • scheduler 执行基于时间的任务,包括计划报表和自动重复文档。
  • websocket 是浏览器实时更新所使用的 socket.io 进程。
  • db 是 MariaDB。
  • redis-cache 和 redis-queue 是两个独立的 Redis 实例,分别用于缓存和任务队列。
  • proxy 是由 HTTPS override 添加的 Traefik。它负责监听 80 和 443 端口并获取证书。

了解这种拆分方式很有用,因为它能告诉您应该查看哪个日志。邮件任务卡住通常是队列 worker 的问题,因此 docker compose logs -f queue-short 是正确的命令。页面可以加载,但通知徽章始终不更新,则是 websocket 问题。无论是哪种情况,查看 backend 日志都会浪费大量时间。

使用生产环境 compose 文件安装,不要使用演示文件

该仓库提供 pwd.yml,README 对此说明得很直接:“此配置仅用于短期评估。您无法在此配置中安装自定义应用。”您可以用它体验一个下午的 ERPNext。不要用它运行公司业务。

sudo apt update && sudo apt install -y git
curl -fsSL https://get.docker.com | bash
git clone https://github.com/frappe/frappe_docker
cd frappe_docker
mkdir -p ~/gitops
cp example.env ~/gitops/erpnext.env

打开 ~/gitops/erpnext.env,修改 4 个值。ERPNEXT_VERSION 固定镜像标签。示例文件中的 DB_PASSWORD 为 123。SITES_RULE 是 Traefik 路由规则,LETSENCRYPT_EMAIL 提供 ACME 账户电子邮件地址。Let's Encrypt 已于 June 4, 2025 停止发送证书到期通知邮件,因此请单独监控证书到期时间。

ERPNEXT_VERSION=v16.32.1
DB_PASSWORD=<a long random password>
SITES_RULE=Host(`erp.example.com`)
LETSENCRYPT_EMAIL=ops@example.com

现在生成一个 compose 文件,然后启动它。

docker compose --project-name erpnext \
  --env-file ~/gitops/erpnext.env \
  -f compose.yaml \
  -f overrides/compose.mariadb.yaml \
  -f overrides/compose.redis.yaml \
  -f overrides/compose.https.yaml \
  config > ~/gitops/erpnext.yaml

docker compose --project-name erpnext -f ~/gitops/erpnext.yaml up -d
export COMPOSE_FILE="$HOME/gitops/erpnext.yaml"

config 不会启动任何服务。它会合并基础文件和覆盖文件,并输出已替换所有变量的结果。然后使用生成的文件启动服务。增加这一步是值得的:运行中的服务栈由一个可读文件定义,因此当有人修改 env 文件或您拉取仓库时,运行配置不会随之改变。多个 Docker Compose 文件如何合并详细说明了覆盖规则。

COMPOSE_FILE 导出变量后,下面的命令会使用生成的文件。在每个新 shell 中重复导出;在 cron 中,请显式传递 -f ~/gitops/erpnext.yaml。

等待 db 启动,并等待 configurator 退出。这需要几秒钟。然后创建站点。

docker compose --project-name erpnext exec backend \
  bench new-site --mariadb-user-host-login-scope=% \
  --db-root-password '<your DB_PASSWORD>' \
  --install-app erpnext \
  --admin-password '<a strong admin password>' \
  erp.example.com

检查结果:

docker compose --project-name erpnext ps
docker compose --project-name erpnext exec backend bench --site erp.example.com list-apps

list-apps 应输出 frappe 和 erpnext 及其版本。健康的 ps 会在 running 状态下显示 10 个服务,在 restarting 状态下不显示任何服务。

这里经常会有两个问题。--mariadb-user-host-login-scope=% 会为新站点的数据库用户设置通配符主机范围,因此即使 Docker 为应用容器分配了不同地址,该用户仍可登录。没有此选项时,Frappe 会将用户限制为当前连接主机。应用容器通过 Docker 网络访问 MariaDB,因此会以远程主机身份连接;限制为 localhost 的数据库用户无法从该处登录。此选项修改的是站点的数据库用户,而不是 root 账户。% 范围允许任何能够访问 MariaDB 的主机建立连接,因此请将数据库保留在私有 Docker 网络中。

第二个问题是站点名称。默认情况下,前端根据 HTTP Host 请求头选择要提供的站点,因此,虽然 erpnext 和 erp.example.com 都存在,但创建为 erpnext 的站点无法通过 erp.example.com 访问。请像上面一样使用域名命名站点,或者在 env 文件中将 FRAPPE_SITE_NAME_HEADER 设置为站点名称,然后重新生成 compose 文件。

HTTPS,以及启用前必须满足的条件

compose.https.yaml override 会让 Traefik 监听 443 端口,将 80 端口重定向到 HTTPS,并从 Let's Encrypt 请求证书。TLS(传输层安全)可防止发票和会话 Cookie 以明文形式在网络上传输。

以下两项必须同时满足,否则永远不会签发证书。erp.example.com 的 DNS A 记录必须已经指向 VPS。由于 Let's Encrypt 会通过 80 端口上的 HTTP-01 challenge 验证您是否控制该域名,因此必须能从互联网访问 80 和 443 端口。请同时检查服务商的网络防火墙和服务器上的防火墙。它们是彼此独立的控制项,而面板防火墙最容易被忽略。

证书会保存到 cert-data 卷中的 /letsencrypt/acme.json。如果浏览器显示的是默认证书,而不是您的证书,请在 docker compose --project-name erpnext ps 中找到代理服务名称,并查看其日志中的 ACME(自动证书管理环境)错误。在同一台服务器上运行其他 Web 应用?在多个 Docker Compose 应用前使用一个 Traefik 实例介绍了如何共享代理,避免多个应用争用 443 端口。这类服务器上的第二个应用通常面向客户,而自托管 Chatwoot 客服平台也位于同一代理之后,因此处理发票的人员可以在同一处回复客户的电子邮件和聊天消息。

出站邮件,否则发票永远无法发出

这是大多数 ERPNext 指南都会跳过的一步,但它决定了系统是否真正可用。没有正常工作的出站邮件,发票无法发送给客户,密码重置邮件无法送达,计划报告也无法交付。该软件栈不包含邮件服务器。

不要尝试通过端口 25 直接从 VPS 发送邮件。AWS 等服务商默认会阻止出站端口 25,而全新的发送 IP 几乎没有历史信誉,会增加邮件被拒收或进入垃圾邮件文件夹的风险。这两种情况都不是必然结果。请使用端口 587 上经过身份验证的中继,并先检查服务商的出站规则:DigitalOcean 默认会阻止 Droplet 上的端口 25、465 和 587。

受支持的方式是使用 ERPNext 界面中的 Email Account 页面,该页面会加密存储密码。也可以将这些配置项写入站点配置:

docker compose --project-name erpnext exec backend \
  bench --site erp.example.com set-config mail_server smtp.example.com

docker compose --project-name erpnext exec backend \
  bench --site erp.example.com set-config mail_port 587 --parse

docker compose --project-name erpnext exec backend \
  bench --site erp.example.com set-config use_tls 1 --parse

docker compose --project-name erpnext exec backend \
  bench --site erp.example.com set-config mail_login 'erp@example.com'

docker compose --project-name erpnext exec backend \
  bench --site erp.example.com set-config auto_email_id 'erp@example.com'

--parse 会将 587 存储为数字,而不是字符串 "587"。重新读取文件,并确认这两个值未使用引号:

docker compose --project-name erpnext exec backend \
  cat sites/erp.example.com/site_config.json

如需加密存储密码,请在 Email Account 页面中同时配置出站服务器、登录名和密码。该页面的密码字段不会设置单独的 mail_password 站点配置项。

然后发送一封真实邮件。创建 Sales Invoice,将其发送到您可以访问的地址,并在发送过程中监控队列:

docker compose --project-name erpnext logs -f queue-short

出站邮件由后台任务处理,因此邮件始终无法送达时,通常会在该日志中显示为失败任务,而不是在浏览器中显示错误。还应为发送域发布 SPF(sender policy framework,发件人策略框架)和 DKIM(domainkeys identified mail,域名密钥识别邮件)记录,然后添加 DMARC 策略。没有身份验证,即使发票内容和配置都正确,也可能被拒收或放入垃圾邮件文件夹。如果您希望自行控制完整的邮件链路,自托管的 Mailcow 邮件服务器可以提供由您控制的中继,并将其部署在与 ERP 分开的服务器上。

可实际恢复的备份

单独的数据库转储不算 ERPNext 的备份。附件和私有文件位于 sites 目录中,而不在 MariaDB 中。只恢复数据库时,每个上传的采购订单都会变成失效链接。

docker compose --project-name erpnext exec backend \
  bench --site erp.example.com backup --with-files

该命令会在 sites 卷内的 sites/erp.example.com/private/backups 中写入 4 个文件:

  • 一个 -database.sql.gz 转储文件
  • 一个包含公共文件的 -files.tar 归档文件
  • 一个包含私有文件的 -private-files.tar 归档文件
  • 一份站点配置的 -site_config_backup.json 副本

第 4 个文件最容易被丢弃,但它造成的影响最严重。它包含 encryption_key,这是 Frappe 用于加密已存储密码的密钥,包括电子邮件账户凭据、支付网关密钥和所有集成密钥。使用不匹配的密钥恢复数据库时,站点可以正常加载,但发送邮件会失败,并显示:

frappe.exceptions.ValidationError: Encryption key is invalid! Please check site_config.json

始终将这 4 个文件放在一起。

然后将它们移出服务器。卷内的备份无法在服务器故障后保留,而且 bench 也会清理这些备份:默认情况下,它会删除该目录中超过 23 小时的备份。在 Frappe 16.20.0 和 15.114.0 之前,该默认值为 24 小时;站点配置中的 keep_backups_for_hours 密钥可以覆盖此设置。

docker compose --project-name erpnext cp \
  backend:/home/frappe/frappe-bench/sites/erp.example.com/private/backups \
  ~/erpnext-backups

通过 cron 运行该命令,然后将该目录推送到不由您管理的位置。将 restic 备份加密到异地存储 是合适的工具,因为它会在上传前加密数据,而 restic check 可以验证仓库仍可读取。ERP 备份是整个账本的副本,因此应静态加密,并存储在不属于本服务器的硬件上。

测试恢复流程

未经测试的备份只是猜测。将其恢复到同一台服务器上的第二个站点,绝不要恢复到线上站点。

docker compose --project-name erpnext exec backend \
  bench new-site --mariadb-user-host-login-scope=% \
  --db-root-password '<your DB_PASSWORD>' \
  --admin-password '<a strong admin password>' \
  restore-test.example.com

docker compose --project-name erpnext exec backend \
  bench --site restore-test.example.com --force restore \
  sites/erp.example.com/private/backups/<stamp>-erp_example_com-database.sql.gz \
  --with-public-files sites/erp.example.com/private/backups/<stamp>-erp_example_com-files.tar \
  --with-private-files sites/erp.example.com/private/backups/<stamp>-erp_example_com-private-files.tar \
  --db-root-password '<your DB_PASSWORD>'

将备份配置中的加密密钥复制到恢复的站点,否则其集成功能会失效:

docker compose --project-name erpnext exec backend \
  bench --site restore-test.example.com set-config encryption_key '<value from site_config_backup.json>'

现在按会计人员的方式检查恢复结果。打开应收账款报表,并将期末余额与线上站点进行比较。打开最近的一张采购发票,并下载其附件。站点能够显示登录页面,完全不能证明恢复成功。

完成后删除测试站点:

docker compose --project-name erpnext exec backend \
  bench drop-site restore-test.example.com

为什么 ERPNext 更需要固定版本

对于静态站点,未固定的镜像标签可能只会导致意外重启。对于 ERPNext,这意味着执行数据库架构迁移。bench migrate 会重写数据库表,也可能重写文档数据,并且无法撤销。回滚依赖从备份恢复,而不是执行 docker compose down。

因此应固定标签。ERPNEXT_VERSION=v16.32.1 是 2026 年 8 月仓库自带的 pwd.yml 中固定的版本。2026-11-16,pwd.yml 和 example.env 都固定为 v16.55.0。未经检查,不要继续使用这两个版本号。当前版本列在 frappe/erpnext 发布页面 中,现有镜像标签列在 Docker Hub 中。升级前先阅读目标版本的说明。

升级本身应从备份和维护模式开始。

docker compose --project-name erpnext exec backend \
  bench --site erp.example.com backup --with-files

docker compose --project-name erpnext exec backend \
  bench --site erp.example.com set-maintenance-mode on

编辑 ~/gitops/erpnext.env 中的 ERPNEXT_VERSION,然后渲染配置、拉取镜像并执行迁移。

docker compose --project-name erpnext \
  --env-file ~/gitops/erpnext.env \
  -f compose.yaml \
  -f overrides/compose.mariadb.yaml \
  -f overrides/compose.redis.yaml \
  -f overrides/compose.https.yaml \
  config > ~/gitops/erpnext.yaml

docker compose --project-name erpnext -f ~/gitops/erpnext.yaml pull
docker compose --project-name erpnext -f ~/gitops/erpnext.yaml up -d

docker compose --project-name erpnext exec backend \
  bench --site erp.example.com migrate

docker compose --project-name erpnext exec backend \
  bench --site erp.example.com set-maintenance-mode off

维护模式很重要,因为 migrate 运行时会修改数据库架构。用户在表完成迁移前提交文档,可能导致您不得不手动修复记录。

一次只升级一个主版本,并在每个步骤之间创建备份。继续操作前,先检查对应主版本的迁移指南。

该仓库还提供 overrides/compose.migrator.yaml。启用 MIGRATE_SITES 后(默认已启用),如果存在站点,它会添加一个容器,在启动时运行 bench --site all migrate。这很方便。但这也意味着,标签发生变化的 docker compose up 可能在无人监控的情况下迁移生产数据库。对于业务系统,应将执行 migrate 作为当天明确做出的决定。

存放客户记录的主机加固

首次登录时更改 Administrator 密码。评估用 compose 文件将 admin 设为该密码;如果不改,用户可能会把这种做法带入生产环境。

将 DB_PASSWORD 更改为不同于 example.env 中 123 的值。该值会以明文出现在渲染后的 ~/gitops/erpnext.yaml 中,因此请 chmod 600 该文件,并避免将其存入任何 git 仓库。如需更强的方案,overrides/compose.mariadb-secrets.yaml 会从 Docker secret 文件读取密码,而不是从环境变量读取。Docker Compose 中的环境变量文件和 secret 管理介绍了其中的权衡。

只发布必需的端口。使用 HTTPS 覆盖文件时,只有端口 80 和 443 对外暴露。不要向 db 服务添加 ports 映射来方便数据库客户端连接:这样会将 MariaDB 暴露到公网。改用 docker compose --project-name erpnext exec backend bench mariadb。在主机上放行 22、80 和 443,拒绝其余端口,同时检查云服务商单独配置的网络防火墙。

在 System Settings 中为所有拥有 System Manager 角色的账户启用双因素认证。该角色可以修改 System Settings,因此应将其视为管理员账户,而不是便利性账户。如果运行多个自托管应用,使用 Authentik 作为自托管单点登录提供商比为每个应用再设置一个密码更好。

为主机安装补丁,并在内核更新后重启。在确认堆栈能够恢复运行之前,检查渲染后的文件,确认每个服务都配置了 restart 策略;没有该策略的堆栈会在重启后保持停止状态。让 Docker Compose 堆栈在重启后再次启动介绍了 systemd 相关配置。

当 ERPNext 在一台 VPS 上不再运行得游刃有余

一台 VPS 可以长期承载一家小型公司的业务。出现以下迹象时,说明它已无法继续满足需求:

  • 后台任务不断堆积,邮件和导入任务会延迟几分钟甚至几小时。
  • docker inspect 报告容器出现 "OOMKilled": true 或退出代码 137。
  • 原本需要两秒的报表现在需要三十秒,而 MariaDB 是占用 CPU 的进程。
  • 备份运行时间过长,以至于一次备份会与下一次计划运行重叠。

首先为 MariaDB 分配不与其他服务共享的资源。数据库和 Python 工作进程会争用同一部分内存,而缓冲池通常最需要额外内存。单纯扩大应用服务器的规格,效果往往不如预期。在 Docker 中或主机上运行数据库介绍了这项选择,在 Docker Compose 中设置内存限制则可在调整期间防止某个容器耗尽其他容器的资源。

然后增加队列工作进程,而不是扩展 Web 容量。ERPNext 的慢任务属于后台任务,包括报表生成和批量导入。更多工作进程需要充足的 CPU 和内存余量;在已经饱和的 VPS 上增加容器并不会增加容量。

FAQ

ERPNext 在 VPS 上需要多少 RAM?

用于评估时,先配置 4 GB RAM 和 2 个 vCPU。公司日常使用时,计划配置 8 GB RAM、4 个 vCPU 和 100 GB SSD。内存压力过大时,内核的 out of memory killer 可能会停止容器,docker inspect 会将其报告为 "OOMKilled": true,退出码为 137。这些只是起始配置,不是实际测量结果,因此应在第一个月持续监控自身的内存使用情况。

可以在生产环境中运行 pwd.yml 吗?

不可以。项目的 README 说明该文件仅用于短期评估,并指出无法在其中安装自定义应用。请使用 compose.yaml,并加入 MariaDB、Redis 和 HTTPS 覆盖配置;然后使用 docker compose config 将这些配置渲染到一个文件中,再运行该文件。

为什么我创建 ERPNext 站点后,刚才创建的站点无法访问?

默认情况下,前端根据 HTTP Host 请求头选择要提供服务的站点,因此站点名称必须与浏览器中的域名一致。使用 erpnext 创建的站点不会在 erp.example.com 上提供服务。请使用域名作为站点名称创建站点,或者在 env 文件中将 FRAPPE_SITE_NAME_HEADER 设置为站点名称,然后重新渲染 compose 文件并重启堆栈。

ERPNext 备份必须包含哪些内容?

需要将以下 4 个文件放在一起:-database.sql.gz 转储文件、-files.tar 和 -private-files.tar 归档文件,以及 -site_config_backup.json 配置副本。运行 bench --site erp.example.com backup --with-files 会生成这 4 个文件。配置副本包含 encryption_key,因此不使用该文件进行恢复时,已存储的集成密码将无法解密,并表现为 Encryption key is invalid! Please check site_config.json。

如何升级 ERPNext,同时避免损坏数据?

使用 --with-files 进行备份,启用维护模式,在 env 文件中修改 ERPNEXT_VERSION,重新渲染 compose 文件,拉取镜像并启动堆栈,然后运行 bench --site erp.example.com migrate,最后关闭维护模式。每次只升级一个主版本,并先阅读发行说明,因为 migrate 会重写架构和文档数据,且无法撤销。回滚意味着恢复开始时创建的备份。

这篇文章对您有帮助吗?