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

如何用 Docker 在 VPS 自架 ERPNext

完整說明用 Docker 自架 ERPNext:VPS 規格、11 個容器、TLS、外寄郵件、版本固定,以及實際測試過的還原流程。

執行此部署代表的責任

在 VPS 上自行代管 ERPNext 是維運工作,不是執行一個指令就能完成的安裝作業。官方 Docker Compose stack 包含 11 個容器,並保存總帳與客戶資料。因此,以下每個步驟都必須採用更嚴格的標準:備份必須實際還原過,才能算是備份;未固定版本的 image tag 則可能隨時觸發 schema migration。

本文會反覆使用幾個名稱。ERPNext 是商務應用程式。Frappe 是其底層的 Python framework。Bench 是管理 sites 的 command line 工具,已預先安裝在容器內。site 代表一個 tenant:包含一個 MariaDB database,以及一個存放上傳檔案的目錄。本文幾乎所有指令都會在 backend 容器內,以 bench 對其中一個指定的 site 執行。

本指南使用 frappe_docker repository,這是專案維護的部署版本。以下所有指令都已在 2026 年 8 月針對該 repository 完成驗證。如果你不熟悉 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 的 buffer pool,以及建置報表的 Python worker。記憶體壓力過大時,核心的 out of memory killer 可能會停止容器;此時在容器上執行 docker inspect 會顯示 "OOMKilled": true,退出碼為 137。worker 若在工作中途被終止,已提交的文件可能只完成一半背景處理。

若公司每天使用 ERPNext,請先以 8 GB RAM、4 vCPU 及 100 GB SSD 規劃,再測試實際工作負載。RAM 通常會先耗盡。磁碟成長速度往往超出預期,因為每個附件和每份本機備份都會儲存在與資料庫相同的 volume 上。

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 不會啟動任何服務。它會合併基礎檔案與覆寫檔案,並輸出已替換所有變數的結果。接著使用產生的檔案啟動服務。這個額外步驟很有用:執行中的 stack 會固定在一個可讀取的檔案中,因此即使有人修改 env 檔案或您更新儲存庫,設定也不會在執行期間改變。Docker Compose 多個檔案的合併方式 詳細說明覆寫規則。

COMPOSE_FILE export 會讓下方指令使用產生的檔案。每次開啟新的 shell 都要重新執行;在 cron 中則明確傳入 -f ~/gitops/erpnext.yaml。

等待 db 啟動並等待 configurator 結束,這需要幾秒鐘,然後建立 site。

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=% 會讓新 site 的資料庫使用者使用萬用字元主機範圍,因此即使 Docker 將不同位址指派給 app container,該使用者仍可登入。若未設定此選項,Frappe 會將使用者限制在目前連線的主機。app container 會透過 Docker network 連線到 MariaDB,因此會以遠端主機身分連入;限制於 localhost 的資料庫使用者無法從該處登入。此選項修改的是 site 的資料庫使用者,而不是 root 帳戶。% 範圍允許任何能連線到 MariaDB 的主機建立連線,因此請將資料庫保留在私有 Docker network 中。

第二個問題是 site 名稱。前端預設會根據 HTTP Host 標頭選擇要提供的 site,因此即使兩者都存在,以 erpnext 建立的 site 也無法透過 erp.example.com 存取。請依網域名稱命名 site,如上例所示;或者在 env 檔案中將 FRAPPE_SITE_NAME_HEADER 設為 site 名稱,然後再次產生 compose 檔案。

HTTPS,以及啟用前必須滿足的條件

compose.https.yaml 覆寫設定會讓 Traefik 在 443 埠執行、將 80 埠重新導向至 443,並向 Let's Encrypt 申請憑證。TLS(傳輸層安全性)可避免發票內容與工作階段 cookie 以純文字形式在網路上傳輸。

必須同時滿足兩項條件,否則永遠不會核發憑證。erp.example.com 的 DNS A 記錄必須已指向 VPS。由於 Let's Encrypt 會透過 80 埠的 HTTP-01 challenge 驗證你是否控制該網域,因此 80 和 443 埠都必須能從網際網路連線。請同時檢查供應商的網路防火牆與伺服器上的防火牆。這是兩個獨立的控制項,而控制面板中的防火牆最容易被忽略。

憑證會儲存在 cert-data volume 的 /letsencrypt/acme.json。如果瀏覽器顯示預設憑證而不是你的憑證,請在 docker compose --project-name erpnext ps 找出 proxy 服務名稱,並檢查其日誌中的 ACME(自動憑證管理環境)錯誤。要在同一台伺服器上執行其他 Web 應用程式嗎?由一個 Traefik 執行個體代理多個 Docker Compose 應用程式說明如何共用 proxy,避免爭用 443 埠。像這樣的伺服器上,第二個應用程式通常會直接面向客戶,而自架 Chatwoot 客服服務台也會位於同一個 proxy 後方,因此處理發票的人員可以在同一處回覆客戶電子郵件與聊天訊息。

外寄電子郵件,否則發票永遠離不開伺服器

這是大多數 ERPNext 指南會略過的步驟,但它決定了系統是否實用。外寄郵件無法正常運作時,發票無法送達客戶、密碼重設郵件不會送出,排程報表也無法交付。此堆疊不包含郵件伺服器。

不要嘗試從 VPS 直接透過 port 25 寄信。AWS 等供應商預設會封鎖外寄 port 25,而幾乎沒有寄信紀錄的新 IP 也會增加遭拒收或被歸入垃圾郵件的風險。這兩種結果都不是必然的。請使用 port 587 上經過驗證的 relay,並先確認供應商的外寄規則:DigitalOcean 預設會封鎖 Droplet 上的 port 25、465 和 587。

支援的做法是在 ERPNext 介面中使用 Email Account 畫面;該畫面會以加密方式儲存密碼。您也可以將這些設定寫入 site config:

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 site config 金鑰。

接著傳送一封實際郵件。建立 Sales Invoice,將其寄到您能控制的電子郵件地址,並在操作時監看佇列:

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

外寄郵件是背景工作,因此郵件始終未送達時,通常會在該日誌中顯示為失敗的工作,而不是瀏覽器中的錯誤。也請為寄信網域發布 SPF(sender policy framework)和 DKIM(domainkeys identified mail)記錄,然後加入 DMARC 政策。若沒有驗證機制,即使發票格式正確,也可能遭拒收或被歸入垃圾郵件。若您希望自行掌控完整流程,自架的 Mailcow 郵件伺服器可提供您自行控制的 relay,並可與 ERP 分開部署在另一台伺服器上。

能夠實際還原的備份

單獨的資料庫傾印不算 ERPNext 的備份。附件與私有檔案位於 sites 目錄,不在 MariaDB 中。只還原資料庫時,每張已上傳的採購單都會變成失效連結。

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

這會在 sites volume 內的 sites/erp.example.com/private/backups 寫入 4 個檔案:

  • -database.sql.gz 傾印檔
  • 公開檔案的 -files.tar 封存檔
  • 私有檔案的 -private-files.tar 封存檔
  • 網站設定的 -site_config_backup.json 副本

第 4 個檔案最常被丟棄,但它造成的問題最嚴重。它包含 encryption_key,也就是 Frappe 用來加密儲存密碼的金鑰:電子郵件帳號憑證、付款閘道金鑰,以及所有整合服務的 secret。還原資料庫時若沒有相符的金鑰,網站仍會正常載入,但寄信會失敗:

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

務必始終將這 4 個檔案放在一起。

接著將它們移出伺服器。volume 內的備份無法在伺服器故障後保留,而且 bench 會自動清理這些檔案:預設會刪除該目錄中超過 23 小時的備份。Frappe 16.20.0 和 15.114.0 之前的預設值是 24 小時;網站設定中的 keep_backups_for_hours key 可以覆寫這項設定。

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

請從 cron 執行這項工作,然後將該目錄推送到不由你管理的位置。加密後使用 restic 備份至異地儲存 是適合的工具,因為它會在上傳前加密,而 restic check 可確認 repository 仍可讀取。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 的容器;MIGRATE_SITES 預設為啟用。這項功能很方便,但也表示 docker compose up 若使用變更後的標籤,可能在無人監看時遷移正式環境的資料庫。在業務系統上,應將執行 migrate 視為當天明確決定的操作。

存放客戶紀錄的主機強化

首次登入時變更 Administrator 密碼。評估用 compose 檔案將 admin 設為該密碼,而這種做法可能延續到正式環境。

將 DB_PASSWORD 改成不同於 example.env 中 123 的值。該值會以純文字寫入產生的 ~/gitops/erpnext.yaml,因此請 chmod 600 該檔案,並避免將它存放在任何 git repository 中。若要使用更強的方式,overrides/compose.mariadb-secrets.yaml 會從 Docker secret 檔案讀取密碼,而不是從環境變數讀取。在 Docker Compose 中處理環境檔案與 secret 說明其中的取捨。

只發布必要的內容。使用 HTTPS override 時,只有 80 和 443 會對外暴露。不要在 db service 上新增 ports mapping,讓資料庫用戶端更容易連線,因為這會讓 MariaDB 暴露在公開網際網路上。請改用 docker compose --project-name erpnext exec backend bench mariadb。在主機上允許 22、80 和 443,拒絕其餘連線,並確認供應商另設的 network firewall 也已完成設定。

在 System Settings 中,為所有擁有 System Manager role 的帳戶啟用雙因素驗證。該 role 可以變更 System Settings,因此應將它視為 administrator account,而不是為了方便而授予的權限。若執行多個自架應用程式,使用 Authentik 作為自架 single sign-on provider 會比為每個應用程式各設一組密碼更合適。

為主機安裝修補程式,並在 kernel 更新後重新開機。在確認 stack 能夠恢復運作前,先檢查產生的檔案,確認每個 service 都有 restart policy,因為沒有該設定的 stack 會在重新開機後維持停止狀態。讓 Docker Compose stack 在重新開機後再次啟動 說明 systemd 端的設定方式。

當 ERPNext 在一台 VPS 上不再應付自如

一台 VPS 長期支撐小型公司的運作。以下跡象表示它已經不敷使用:

  • 背景工作逐漸堆積,電子郵件與匯入作業延遲數分鐘甚至數小時。
  • docker inspect 回報容器出現 "OOMKilled": true 或結束碼 137。
  • 原本需要 2 秒的報表現在需要 30 秒,而 MariaDB 是占用 CPU 的程序。
  • 備份執行時間過長,導致一次備份尚未完成,下一次排程就已經開始。

先為 MariaDB 提供不與其他服務共用的資源。資料庫與 Python worker 會競用相同的記憶體,而 buffer pool 正是最需要更多記憶體的部分。擴充應用程式伺服器的效果通常不如預期。在 Docker 或主機上執行資料庫涵蓋這項選擇,而在 Docker Compose 中設定記憶體限制可避免單一容器耗盡其他容器的資源。

接著應增加 queue worker,而不是擴充 web capacity。ERPNext 的慢速工作屬於背景工作,例如報表產生與大量匯入。增加 worker 需要 CPU 與記憶體餘裕;在已經飽和的 VPS 上增加容器,並不會提高容量。

FAQ

VPS 需要多少 RAM 才能執行 ERPNext?

若要進行評估,請先配置 4 GB RAM 與 2 vCPU。若公司每天使用,建議配置 8 GB RAM、4 vCPU,以及 100 GB SSD。記憶體不足時,kernel 的 out of memory killer 可能會停止容器;docker inspect 會將此情況回報為 "OOMKilled": true,結束代碼為 137。這些數值是起始配置,不是實測結果,因此請在第一個月持續監控實際記憶體使用量。

可以在 production 執行 pwd.yml 嗎?

不可以。專案的 README 說明,該檔案僅供短期評估使用,也指出無法在其中安裝自訂 app。請使用 compose.yaml 搭配 MariaDB、Redis 與 HTTPS override,再以 docker compose config 將它們產生為單一檔案,並執行該檔案。

為什麼建立 ERPNext site 後立即無法連線?

frontend 預設會根據 HTTP Host header 選擇要提供的 site,因此 site 名稱必須與瀏覽器中的網域相符。若 site 建立為 erpnext,就不會在 erp.example.com 提供服務。請以網域作為 site 名稱建立 site,或在 env 檔案中將 FRAPPE_SITE_NAME_HEADER 設為 site 名稱,重新產生 compose 檔案後,再重新啟動 stack。

ERPNext 備份必須包含哪些內容?

必須將以下 4 個檔案放在一起:-database.sql.gz dump、-files.tar 與 -private-files.tar archive,以及 -site_config_backup.json config 複本。執行 bench --site erp.example.com backup --with-files 會產生這 4 個檔案。config 複本包含 encryption_key,因此還原時若缺少該檔案,儲存的整合密碼將無法解密,並顯示為 Encryption key is invalid! Please check site_config.json。

如何升級 ERPNext 才不會破壞資料?

先使用 --with-files 備份,啟用 maintenance mode,修改 env 檔案中的 ERPNEXT_VERSION,重新產生 compose 檔案,執行 pull、啟動 stack,接著執行 bench --site erp.example.com migrate,最後關閉 maintenance mode。每次只升級 1 個 major version,並先閱讀 release notes,因為 migrate 會改寫 schema 與 document data,且無法復原。若要 rollback,必須還原開始時建立的備份。

這篇文章對您有幫助嗎?