Erpnext¶

Overview¶

ERPNext 係一套開源企業資源規劃（ERP）系統，由 Frappe Technologies 開發，底層用 Frappe Framework。功能包括會計、銷售、採購、庫存、CRM、人力資源、項目管理、製造、資產管理等。benhoweb 喺 Oracle Cloud 上自架 ERPNext，版本 v16.32.3，定位係「小型公司 / 4GB RAM 限額版」。為咗喺有限資源下穩定運行，架構做咗精簡：worker 合一、Redis 共用 redis-main（db3/4/5）、MariaDB 獨立。對外只經 Cloudflare Tunnel（CF Tunnel），主機唔 expose 任何 port，所有固定 IP 集中喺 172.21.0.67 至 .72。2026-08-04 修正：原本 .61-.63/.65 已經俾 BigCapital 用，所以 ERPNext 改用 .67-.72，避免 IP 衝突。

Architecture¶

整體架構係 Oracle Cloud VM + Docker Compose。外部用戶經 Cloudflare DNS / Tunnel 入嚟，Tunnel 再轉去 cf_network 內嘅 ERPNext 服務。因為唔開 host port，就算 VM 有 public IP，都唔會直接暴露 ERPNext 或 MariaDB。

核心元件：

MariaDB 11.8：Frappe 硬性要求，所以獨立一個容器 erpnext-mariadb，固定 IP 172.21.0.67，mem_limit: 1536m。資料存放喺 volume erpnext-db-data。
Configurator：一次性容器，用 frappe/erpnext:v16.32.3，負責寫入 common_site_config.json，設定 DB 同 Redis 連線。
ERPNext / Frappe 元件：backend、frontend、websocket、scheduler、worker。為節省 RAM，worker 唔再分 short / default / long 多個容器，而係合一。
Redis：唔另開新容器，改用共用嘅 redis-main。ERPNext 使用 db3（cache）、db4（queue）、db5（socketio）。
網絡：cf_network，固定 IP 段 .67-.72；對外只經 CF Tunnel。

以下係 MariaDB 服務節錄（2026-08-04 版）：

services:
  mariadb:
    image: mariadb:11.8
    container_name: erpnext-mariadb
    networks:
      cf_network:
        ipv4_address: 172.21.0.67
    mem_limit: 1536m
    command:
      - --character-set-server=utf8mb4
      - --collation-server=utf8mb4_unicode_ci
      - --skip-character-set-client-handshake
      - --innodb-buffer-pool-size=536870912
    environment:
      TZ: Asia/Hong_Kong
      MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
      MARIADB_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
    volumes:
      - erpnext-db-data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      start_period: 30s
      interval: 10s
      timeout: 5s
      retries: 10
    restart: unless-stopped

Deployment¶

部署前提：Oracle Cloud 實例、Docker、Docker Compose、已存在嘅 external network cf_network、Cloudflare Tunnel、redis-main 同 .env 檔案。

步驟：

建立或確認 cf_network，subnet 172.21.0.0/16。
喺 .env 設定 DB_ROOT_PASSWORD，以及 Redis 連線：
REDIS_CACHE_URL=redis://redis-main:6379/3
REDIS_QUEUE_URL=redis://redis-main:6379/4
REDIS_SOCKETIO_URL=redis://redis-main:6379/5
準備 docker-compose.yml，加入 mariadb、configurator、backend、frontend、websocket、scheduler、worker 等服務。所有服務接入 cf_network，並按需要指定 .67-.72。
先啟動 MariaDB：docker compose up -d erpnext-mariadb，等 healthcheck 變 healthy。
執行 configurator：docker compose run --rm erpnext-configurator，寫入 common_site_config.json。
啟動其餘服務：docker compose up -d。
首次安裝 site：可用 bench new-site 或 ERPNext Docker 內置 create-site 流程，設定 admin 密碼、公司資料。
Cloudflare Tunnel 新增 ingress：erp.benhoweb.com → http://erpnext-frontend:8080（實際 service name 按 compose 而定）。唔需要喺 VM 開 80/443。
驗證：docker compose ps、docker compose logs -f erpnext-mariadb、瀏覽 https://erp.benhoweb.com。

Configuration¶

MariaDB 設定重點：

utf8mb4 / utf8mb4_unicode_ci，支援中文同 emoji。
skip-character-set-client-handshake，避免 client 字元集不一致。
innodb-buffer-pool-size=536870912（512MB），喺 4GB RAM 下平衡效能同記憶體。
TZ=Asia/Hong_Kong，方便 log 同排程時間。
healthcheck 用 healthcheck.sh --connect --innodb_initialized，確保 DB 真係 ready 先俾其他服務連。

Redis 設定：common_site_config.json 需要指向 redis-main：

{
  "db_host": "erpnext-mariadb",
  "db_port": 3306,
  "redis_cache": "redis://redis-main:6379/3",
  "redis_queue": "redis://redis-main:6379/4",
  "redis_socketio": "redis://redis-main:6379/5"
}

ERPNext 設定：

固定 image tag frappe/erpnext:v16.32.3，避免意外升級。
worker 合一：用單一 worker 容器處理 default、short、long queue，減少記憶體開銷。
scheduler 只開一個，避免重複排程。
對外 domain 由 CF Tunnel 管理，frontend 只需喺內網監聽。

Operations¶

日常操作：

啟動：docker compose up -d
停止：docker compose down
重啟單一服務：docker compose restart erpnext-mariadb
睇 log：docker compose logs -f erpnext-mariadb
資源監控：docker stats，特別留意 MariaDB 同 worker 記憶體。
備份：mysqldump 匯出 ERPNext database，再配合 Oracle Cloud block volume snapshot 備份 erpnext-db-data。
更新：先備份，再改 image tag（例如 v16.32.4），docker compose pull、docker compose up -d，最後執行 bench migrate。
故障排查：
MariaDB healthcheck fail：檢查 RAM、volume 權限、InnoDB buffer pool 設定。
Redis 連線錯誤：確認 redis-main 運行中，db3/4/5 無被其他服務佔用。
網站 502：檢查 frontend / backend log，以及 CF Tunnel ingress 係咪指向正確 service。
IP 衝突：確認 .67-.72 無同 BigCapital 或其他服務撞。

FAQ¶

Q1：點解 MariaDB 要獨立？
Frappe 對 MariaDB 有硬性要求，獨立容器可以控制版本、參數同備份，亦避免同其他服務互相影響。

Q2：4GB RAM 真係夠？
針對小型公司、少量並發用戶，架構已將 worker 合一、Redis 共用、MariaDB buffer pool 設為 512MB、mem_limit 1.5GB。若用戶或數據量增加，應升級 RAM 或分離 worker。

Q3：點解唔 expose host port？
所有對外流量經 Cloudflare Tunnel，主機唔開 80/443，可以減少掃描同攻擊面。只有 Docker 內網服務互通。

Q4：Redis db3/4/5 會唔會同其他服務撞？
唔會。redis-main 係共用 Redis，但各服務用唔同 database index。ERPNext 專用 db3/4/5，其他服務應使用其他 db。

Q5：點解 IP 係 .67-.72？
2026-08-04 修正：.61-.63/.65 已俾 BigCapital 使用，為避免衝突，ERPNext 改用 .67-.72。

Q6：可唔可以用 MySQL？
雖然 MariaDB 同 MySQL 相近，但本部署跟隨 Frappe 硬性要求，使用 MariaDB 11.8，唔建議隨便轉。

docker
docker-compose
oracle-cloud
cloudflare-tunnel
MariaDB
redis
Frappe Framework
erpnext
bigcapital
litellm
Wiki.benhoweb.com

Source¶

Coverage auto (container scan)