Defguard Core

Overview

Defguard Core 係一套自我託管嘅身份管理、多因素認證（MFA）及 VPN 存取控制平台，屬於 Defguard 套件嘅核心元件。佢提供單一入口管理企業或個人嘅用戶身份，並結合 WebAuthn、FIDO2、TOTP 等認證方式，同埋 WireGuard VPN 用戶端設定分配，令遠端存取更安全且更易管理。

喺本 wiki 環境入面，Defguard Core 部署於 Oracle Cloud 嘅 Linux 伺服器，並透過 Docker Compose 運行。佢同其他自架服務（例如 litellm）共用同一套 Docker 基建，亦共用名為 pg-main 嘅 PostgreSQL 資料庫實例。Defguard Core 主要負責控制面（Control Plane）工作，而實際 VPN 連線則交由 Defguard Proxy 執行。整個系統可以理解為「Core 做決策、Proxy 做轉發」。

Architecture

Defguard Core 作為中央服務，喺網路架構上承擔以下角色：

• Web 管理介面：提供管理員登入後的用戶、群組、VPN、裝置及認證設定介面。
• 身份提供者（IdP）：支援本地用戶庫，並可與 LDAP、SAML、OIDC 等外部身份來源整合。
• MFA 驗證服務：處理 WebAuthn、安全金鑰、手機 TOTP 等第二因素驗證。
• gRPC API 端點：供 Defguard Proxy 或其他內部服務連接，進行 VPN 設定下發及狀態同步。
• 資料庫客戶端：連接至 pg-main 上的 PostgreSQL 18 資料庫，保存用戶、群組、裝置、設定等持久化資料。

喺 Docker Compose 環境中，Defguard Core 同 defguard-proxy 處於同一 Docker 網路，Core 透過 DEFGUARD_PROXY_URL 指定 Proxy 位址，而 Proxy 則透過 Core 開放嘅 gRPC 服務取得 VPN 設定。DEFGUARD_GRPC_URL 用於指定內部 gRPC 通訊位置，DEFGUARD_GRPC_BIND_ADDRESS 則令服務可以喺指定介面上監聽。

Deployment

Defguard Core 部署喺 Oracle Cloud 的 VM 執行個體，建議使用 Ubuntu Server 或 Debian，並先安裝好 Docker Engine 同 Docker Compose Plugin。部署流程大致如下：

1. 建立應用目錄，例如 /opt/defguard。
2. 喺目錄內建立 .env 檔案，存放所有敏感環境變數。
3. 建立 docker-compose.yml，內容包含 defguard-core 服務。
4. 執行 docker compose pull 下載映像檔。
5. 執行 docker compose up -d 啟動服務。
6. 設定 Nginx、Caddy 或其他反向代理，將 defguard.benhoweb.com 同 enroll.benhoweb.com 指向 Core 嘅 HTTP 埠。
7. 透過瀏覽器訪問 https://defguard.benhoweb.com，完成首次初始化。

以下係參考用嘅 Docker Compose 配置：

services:
  defguard-core:
    image: ghcr.io/defguard/defguard:latest
    container_name: defguard-core
    restart: unless-stopped
    environment:
      TZ: Asia/Hong_Kong
      DEFGUARD_URL: "https://defguard.benhoweb.com"
      DEFGUARD_PUBLIC_URL: "https://defguard.benhoweb.com"
      DEFGUARD_WEBAUTHN_RP_ID: "defguard.benhoweb.com"
      DEFGUARD_ENROLLMENT_URL: "https://enroll.benhoweb.com"
      DEFGUARD_PROXY_URL: "http://defguard-proxy:50051"
      DEFGUARD_GRPC_URL: "http://127.0.0.1:50055"
      DEFGUARD_HTTP_BIND_ADDRESS: "0.0.0.0"
      DEFGUARD_GRPC_BIND_ADDRESS: "0.0.0.0"

      DEFGUARD_AUTH_SECRET: ${DEFGUARD_AUTH_SECRET}
      DEFGUARD_YUBIBRIDGE_SECRET: ${DEFGUARD_YUBIBRIDGE_SECRET}
      DEFGUARD_GATEWAY_SECRET: ${DEFGUARD_GATEWAY_SECRET}
      DEFGUARD_SECRET_KEY: ${DEFGUARD_SECRET_KEY}
      DEFGUARD_DEFAULT_ADMIN_PASSWORD: ${DEFGUARD_DEFAULT_ADMIN_PASSWORD}
      DEFGUARD_LOG_LEVEL: ${DEFGUARD_LOG_LEVEL}

      # 共用 pg-main (PG18)
      DEFGUARD_DB_HOST: "pg-main"
      DEFGUARD_DB_PORT: "5432"
      DEFGUARD_DB_USER: "defguard"
      DEFGUARD_DB_PASSWORD: "${DEFGUARD_DB_PASSWORD}"
      DEFGUARD_DB_NAME: "defguard"

實際部署時，應將 DEFGUARD_AUTH_SECRET、DEFGUARD_SECRET_KEY、DEFGUARD_DB_PASSWORD 等敏感值放入 .env 檔案，並以 openssl rand -hex 32 等工具產生高強度隨機字串。

Configuration

Defguard Core 嘅設定主要透過環境變數完成，以下係常用項目：

• DEFGUARD_URL：Core 對外公開嘅網站位址，用於產生連結及 API 回應。
• DEFGUARD_PUBLIC_URL：當 Core 位於反向代理之後，需要用呢個變數指定用戶實際存取嘅公開 URL。
• DEFGUARD_WEBAUTHN_RP_ID：WebAuthn 嘅 Relying Party ID，必須同實際網域名稱一致，例如 defguard.benhoweb.com。
• DEFGUARD_ENROLLMENT_URL：用戶註冊或加入 VPN 時使用嘅公開邀請連結，由反向代理轉發至 Core。
• DEFGUARD_PROXY_URL：指向 Defguard Proxy 容器嘅 gRPC 位址，預設使用 50051 埠。
• DEFGUARD_GRPC_URL：定義 Core 內部 gRPC API 嘅 URL；同 DEFGUARD_GRPC_BIND_ADDRESS 配合使用。
• DEFGUARD_DB_HOST、DEFGUARD_DB_PORT、DEFGUARD_DB_USER、DEFGUARD_DB_PASSWORD、DEFGUARD_DB_NAME：PostgreSQL 連線參數，本環境指向共用嘅 pg-main 容器。
• TZ：設定時區為 Asia/Hong_Kong，確保時間記錄同認證時間戳正確。

注意：DEFGUARD_WEBAUTHN_RP_ID 唔可以包含 https:// 前綴，亦唔可以帶埠號，必須係純網域名稱。如果日後更改域名，所有已註冊嘅 WebAuthn 金鑰可能需要重新註冊。

Operations

日常操作需要用到 Docker Compose 指令。假設工作目錄為 /opt/defguard：

cd /opt/defguard
docker compose ps
docker compose logs -f defguard-core
docker compose restart defguard-core
docker compose pull
docker compose up -d

更新版本時，建議先備份 PostgreSQL 資料庫，再執行 docker compose pull && docker compose up -d。由於 Core 依賴 pg-main，任何 PostgreSQL 版本升級或密碼變更都必須同步更新 .env 入面嘅資料庫變數。

如果發現 VPN 用戶無法連線，可以檢查 Defguard Core 同 Defguard Proxy 之間嘅 Docker 網路是否正常。最簡單嘅方法係進入 Core 容器，嘗試連接 defguard-proxy:50051。另外，檢查防火牆是否開放 WebSocket／gRPC 所需嘅埠位。

FAQ

Defguard Core 係咪免費？
Defguard Core 本身係開源軟件，可以自我託管，唔需要按用戶付費。但你需要自行承擔 Oracle Cloud 執行個體、儲存空間及網絡流量成本。

可以喺 Oracle Cloud Free Tier 運行嗎？
可以。Oracle Cloud Always Free 提供 AMD 或 Ampere ARM 執行個體，理論上足以運行 Defguard Core、PostgreSQL 及一個小型 Proxy。不過如果用戶數量較多，建議至少 2 核 4GB RAM。

點解要設 DEFGUARD_PUBLIC_URL？
因為 Oracle Cloud 環境通常會用反向代理終止 TLS，Core 實際收嘅請求可能嚟自內部網路。指定 DEFGUARD_PUBLIC_URL 可以令 Core 知道外界存取佢嘅公開網址，正確產生 redirect、WebAuthn challenge 及 VPN 設定連結。

DEFGUARD_DB_PASSWORD 可以寫死喺 compose 檔嗎？
唔建議。資料庫密碼屬於敏感資料，應該放入 .env 或者使用 Docker Secrets。一旦 compose 檔被提交到 Git，密碼就會外洩。本 wiki 僅作示範，實際環境請改用環境變數管理。

點樣備份 Defguard Core？
主要備份 PostgreSQL 入面嘅 defguard database，可以使用 pg_dump 定時匯出。另外，.env 檔案同加密金鑰亦應該妥善保存，否則無法還原用戶認證同 VPN 設定。

Related Links

• docker
• litellm
• oracle-cloud
• postgres
• wireguard
• WebAuthn

Defguard Core 係一套功能完整嘅開源身份與 VPN 管理平台，喺 Oracle Cloud 上配合 Docker Compose 可以快速建立屬於自己嘅安全存取基建。透過妥善設定環境變數、反向代理同資料庫連接，即可長期穩定運行。

Source

Coverage auto (container scan)