Defguard Gateway

Overview

Defguard Gateway 係一個用於建立安全 VPN 通道嘅自我託管服務，通常部署喺 Oracle Cloud Infrastructure（OCI）等雲端環境。佢係 Defguard 方案入面嘅重要組成部分，負責將 WireGuard VPN 用戶端流量轉發到內部網絡或者互聯網。

Defguard Gateway 同 Defguard Server 配合使用：Server 負責集中管理用戶、裝置、認證同權限；Gateway 則喺邊緣節點執行實際網絡功能，例如建立 WireGuard 介面、設定路由同執行 NAT。本頁面記錄一個典型嘅 Docker Compose 部署方式，尤其適合喺 Oracle Cloud 上快速啟動一個 VPN 閘道。

Defguard Gateway 嘅最大特點係以「宿主機網絡模式」運行，容器直接使用主機嘅網絡棧，避免 Docker 嘅連接埠轉發效應導致 UDP 效能下降。同時容器加入 NET_ADMIN capability，令到管理員可以喺容器內部修改網絡設定，包括建立 WireGuard tunnel 同 iptables 規則。

Architecture

Defguard Gateway 使用 gRPC 協議同 Defguard Server 通訊。兩者之間嘅關係可以理解為「控制平面」同「數據平面」之分：

• Defguard Server：作為控制中心，儲存用戶資料、裝置 finger print、VPN 配置、權限策略。Server 會將指定用戶或者裝置分配到唔同 Gateway。
• Defguard Gateway：作為邊緣節點，接收 Server 嘅指令，執行 WireGuard 介面建立、金鑰交換、流量轉發同 NAT。Gateway 本身唔保存持久化資料，所有配置都由 Server 推送。

喺 Docker 部署入面，network_mode: host 係關鍵設定。呢個模式令 Gateway 容器可以直接監聽主機嘅 UDP 埠（例如 51820），並直接存取主機嘅路由表同 iptables。cap_add: NET_ADMIN 提供容器修改呢啲網絡設定嘅權限。

DEFGUARD_MASQUERADE=true 表示啟用 IP masquerade，即係將 VPN 用戶端嘅內網 IP 轉換成主機嘅公網 IP，令 VPN 用戶可以正常上網。DEFGUARD_GRPC_BIND_ADDRESS 指定 gRPC 連接嘅目標地址；喺典型 Docker 網絡入面，172.21.0.1 係 Docker bridge 網絡嘅預設閘道地址，通常對應 Defguard Server 所在容器網絡。

Deployment

前置條件

• 一部 Oracle Cloud VM，建議使用 Ubuntu 22.04 或 24.04 LTS。
• 已安裝 Docker Engine 同 Docker Compose plugin。
• 已經部署好 Defguard Server，並取得：
• DEFGUARD_GRPC_URL：Server 嘅 gRPC 端點。
• DEFGUARD_TOKEN：用於認證嘅免責 token。
• DEFGUARD_GATEWAY_NAME：呢個 Gateway 嘅顯示名稱。
• 開放必要嘅防火牆埠，例如 WireGuard UDP 51820 同 gRPC TCP 50066。

docker-compose.yml

建立一個目錄，例如 ~/defguard-gateway，入面放 docker-compose.yml：

services:
  defguard-gateway:
    image: ghcr.io/defguard/gateway:latest
    container_name: defguard-gateway
    restart: unless-stopped
    network_mode: host
    cap_add:
      - NET_ADMIN
    environment:
      TZ: Asia/Hong_Kong
      DEFGUARD_GRPC_URL: ${DEFGUARD_GRPC_URL}
      DEFGUARD_TOKEN: ${DEFGUARD_TOKEN}
      DEFGUARD_GATEWAY_NAME: ${DEFGUARD_GATEWAY_NAME}
      DEFGUARD_GRPC_PORT: 50066
      DEFGUARD_GRPC_BIND_ADDRESS: "172.21.0.1"
      DEFGUARD_LOG_LEVEL: "info"
      DEFGUARD_MASQUERADE: "true"

.env 範例

喺同一個目錄建立 .env 檔案：

DEFGUARD_GRPC_URL=https://defguard.example.com
DEFGUARD_TOKEN=your_grpc_token_here
DEFGUARD_GATEWAY_NAME=oracle-gateway-01

啟動

執行以下指令啟動服務：

sudo docker compose up -d

檢查容器狀態：

sudo docker ps

如果一切正常，你應該見到 defguard-gateway 容器正在運行，並且日誌顯示已成功連接 Defguard Server。

Configuration

Defguard Gateway 嘅配置主要透過環境變數控制。以下係每個變數嘅詳細說明：

變數	說明
DEFGUARD_GRPC_URL	Defguard Server 嘅 gRPC 地址，可以係 IP 或域名。例如 https://vpn.example.com。
DEFGUARD_TOKEN	一串由 Defguard Server 管理員產生嘅 token，用於 Gateway 認證。
DEFGUARD_GATEWAY_NAME	喺 Defguard 控制台顯示嘅名稱，用於識別唔同 Gateway。
DEFGUARD_GRPC_PORT	gRPC 通訊埠，預設係 50066。
DEFGUARD_GRPC_BIND_ADDRESS	指定要連接嘅 Defguard Server 綁定地址。喺 host network 模式下，如果 Server 都係用 Docker 運行，可以設定為 Docker bridge 嘅閘道 IP 172.21.0.1。
DEFGUARD_LOG_LEVEL	日誌級別，可選 debug、info、warn、error。
DEFGUARD_MASQUERADE	設定為 true 時啟用 NAT masquerade，令 VPN 用戶可以透過主機 IP 存取互聯網。

Oracle Cloud 防火牆設定

Oracle Cloud 嘅網路安全清單（Security List）以及 VM 內部嘅 iptables 都可能需要開放連接埠。預設情況下，OCI 實例可能未開啟 IP forwarding，需要手動設定：

echo 'net.ipv4.ip_forward=1' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

同時確保防火牆允許 UDP 51820 同 TCP 50066 嘅流量。

Operations

查看日誌

常用嚟偵測問題：

sudo docker logs -f defguard-gateway

日誌會顯示 gRPC 連接狀態、WireGuard 介面建立情況同錯誤訊息。

重啟

修改咗環境變數或者主機網絡設定之後，可以重啟服務：

sudo docker restart defguard-gateway

更新

Defguard Gateway 會持續更新，可以透過以下指令升級：

sudo docker compose pull
sudo docker compose up -d

移除

如果需要完全移除服務：

sudo docker compose down

呢個指令會停止並移除容器，但唔會刪除 .env 或者 docker-compose.yml。

常見操作問題

• 如果 Gateway 無法連接 Server，檢查 DEFGUARD_GRPC_URL 同 DEFGUARD_TOKEN 是否正確。
• 如果 VPN 用戶端可以連接，但無法訪問互聯網，確認 DEFGUARD_MASQUERADE 為 true，並檢查 IP forwarding 是否開啟。
• 如果連接埠衝突，因為 host network mode 直接使用主機網絡，需要檢查主機上是否已經有其他程序佔用相同 UDP/TCP 埠。

FAQ

問：點解要用 network_mode: host？

答：WireGuard 依賴 UDP 連接埠，Docker bridge 模式會引入額外 NAT 層，可能造成效能損失或者連接不穩定。Host 模式令容器直接使用主機網絡，確保 VPN 流量轉發效率最高。

問：DEFGUARD_GRPC_BIND_ADDRESS 應該點樣設定？

答：如果 Defguard Server 同 Gateway 喺同一部主機上透過 Docker Compose 運行，通常可以設定為 Docker bridge 嘅預設閘道地址 172.21.0.1。如果 Server 喺另一部機器，就應該設定為 Server 嘅實際 IP 或域名，並確保 gRPC 埠可以訪問。

問：Oracle Cloud 上有冇特別需要注意嘅地方？

答：有。OCI 安全清單需要開放指定連接埠，同時 VM 內部 iptables 可能阻止流量。仲有，Oracle Linux 或 Ubuntu 預設可能未開啟 IP forwarding，需要手動設定 net.ipv4.ip_forward=1。

問：可以同時部署多個 Defguard Gateway 嗎？

答：可以。每個 Gateway 需要獨立名稱同 token，可以部署喺唔同區域，實現多點 VPN 接入，並由中央 Defguard Server 統一管理。

問：Defguard Gateway 同 WireGuard 有咩關係？

答：Defguard Gateway 係 WireGuard 嘅管理層封裝。佢唔係取代 WireGuard，而係喺 WireGuard 之上提供用戶管理、裝置認證同動態配置功能。底層仍然使用 WireGuard 協議傳輸數據。

Related Links

• docker
• litellm
• wireguard
• oracle-cloud
• Self-Hosted
• VPN
• NAT
• gRPC

Source

Coverage auto (container scan)