Wg Easy¶

Overview¶

Wg Easy（全名 WG-Easy）係一套基於 WireGuard 嘅開源 VPN 管理工具，提供簡潔嘅 Web 介面。用戶唔需要直接編輯 WireGuard 嘅複雜設定檔，只需要透過瀏覽器就可以新增用戶、下載配置文件、啟用或停用 VPN 連接。Wg Easy 通常以 Docker 容器方式運行，特別適合部署喺雲端伺服器上，例如 Oracle Cloud 嘅 Always Free 運算實例。

呢篇百科頁面所描述嘅部署方式，係一套喺 Oracle Cloud 上以 Docker Compose 運行嘅 Wg Easy 實例。Compose 設定檔已經包含固定嘅 Docker 網絡位置、核心模組掛載、系統參數調整等，確保 WireGuard 喺雲端環境可以正常運作。

Architecture¶

Wg Easy 本身由兩個主要部分組成：

WireGuard 核心服務：負責處理 VPN 隧道封包，利用 Linux 核心嘅 WireGuard 模組。
Web 管理介面：提供圖像化嘅用戶管理、QR Code、配置文件下載等功能。

喺 Oracle Cloud 部署時，容器需要具備以下系統層級能力：

NET_ADMIN：允許容器修改網絡設定、建立 WireGuard 介面。
SYS_MODULE：允許容器載入核心模組。
net.ipv4.ip_forward=1：開啟 Linux 核心嘅 IP 封包轉發功能，令 VPN 客戶端可以訪問互聯網。
net.ipv4.conf.all.src_valid_mark=1：解決部分路由規則導致嘅封包無效標記問題。

上述 Compose 設定使用咗一個外部 Docker 網絡 cf_network，並將容器固定為 172.21.0.44。呢個網絡通常係為配合反向代理或防火牆規則而建立，令 Wg Easy 可以喺一個穩定嘅 IP 地址上提供服務。

WireGuard 使用預設嘅 UDP 連接埠 51820，而 Web 介面預設使用 TCP 51821。喺上述 Compose 設定入面，只有 51820/udp 被發佈到主機。如果用戶需要直接透過瀏覽器訪問管理介面，必須另外加入 51821:51821/tcp 嘅連接埠映射。

Deployment¶

前置條件¶

一部 Oracle Cloud 運算實例，建議使用 Ubuntu 或 Oracle Linux。
已安裝 Docker 及 Docker Compose Plugin。
已建立一個名為 cf_network 嘅 Docker 外部網絡，並確保其子網包含 172.21.0.44。
Oracle Cloud 防火牆（Security List）已開放 UDP 連接埠 51820。

建立目錄及設定檔¶

首先建立 Wg Easy 嘅持久化目錄：

mkdir -p /home/opc/wg-easy

然後將以下內容儲存為 /home/opc/wg-easy/docker-compose.yml：

version: '3.8'

networks:
  cf_network:
    external: true

services:
  wg-easy:
    image: ghcr.io/wg-easy/wg-easy:15
    container_name: wg-easy
    environment:
      - INSECURE=true
      - DISABLE_IPV6=true
      - TZ=Asia/Hong_Kong
    volumes:
      - /usr/share/zoneinfo:/usr/share/zoneinfo:ro
      - /home/opc/wg-easy:/etc/wireguard
      - /lib/modules:/lib/modules:ro
    ports:
      - "51820:51820/udp"
    restart: unless-stopped
    cap_add:
      - NET_ADMIN
      - SYS_MODULE
    sysctls:
      - net.ipv4.conf.all.src_valid_mark=1
      - net.ipv4.ip_forward=1
    networks:
      cf_network:
        ipv4_address: 172.21.0.44

啟動服務¶

執行以下指令：

cd /home/opc/wg-easy
docker compose up -d

服務啟動後，可以使用以下指令檢查容器狀態：

docker ps

如果一切正常，容器應該處於 Up 狀態。

Configuration¶

環境變數¶

Compose 檔案入面使用咗幾個重要環境變數：

INSECURE=true：代表 Wg Easy Web 介面唔需要密碼認證。呢個設定只適合喺受信任嘅內網或配合反向代理認證時使用。如果暴露到公網，強烈建議改用 PASSWORD 環境變數。
DISABLE_IPV6=true：停用 WireGuard 入面嘅 IPv6 支援。若然無 IPv6 路由需求，可以避免潛在嘅設定問題。
TZ=Asia/Hong_Kong：設定時區為香港時間，令日誌同記錄更符合本地使用習慣。

Volume 掛載¶

/home/opc/wg-easy:/etc/wireguard：持久化 WireGuard 嘅設定檔，包括 wg0.conf 同用戶資料。
/lib/modules:/lib/modules:ro：掛載主機核心模組目錄，令容器可以載入 WireGuard 模組。
/usr/share/zoneinfo:/usr/share/zoneinfo:ro：提供時區資料庫俾容器使用。

網絡設定¶

容器使用外部網絡 cf_network，並固定為 172.21.0.44。優點係：

其他容器可以通過固定 IP 訪問 Wg Easy。
反向代理（例如 Nginx Proxy Manager）可以穩定轉發流量。

缺點係必須確保 cf_network 子網唔可以同主機其他網絡衝突。

Web 介面連接埠¶

原版 Wg Easy Web 介面使用 TCP 51821。上述 Compose 未有將佢映射到主機，因此若然要直接訪問，請修改 ports：

    ports:
      - "51820:51820/udp"
      - "51821:51821/tcp"

修改後執行：

docker compose up -d

如果使用反向代理，亦可以將容器 172.21.0.44:51821 設為 upstream。

Operations¶

用戶管理¶

透過 Web 介面可以新增 VPN 用戶。每個用戶會獲得一個獨立嘅 WireGuard 配置文件。管理員可以隨時停用或刪除用戶，而毋需重啟整個容器。

日誌查看¶

如果需要檢查 WireGuard 連線記錄，可以執行：

docker logs -f wg-easy

更新 Wg Easy¶

當有新版映像發佈時，可以進行以下更新：

cd /home/opc/wg-easy
docker compose pull
docker compose up -d

由於 WireGuard 設定檔存放在 Volume 入面，更新容器通常唔會遺失用戶資料。

備份¶

只需備份 /home/opc/wg-easy 目錄即可。常用做法係壓縮整個目錄：

tar czf wg-easy-backup.tar.gz -C /home/opc wg-easy

防火牆設定¶

喺 Oracle Cloud 上，除咗實例內部嘅 iptables 或 firewalld，必須同時喺 OCI Console 嘅 Security List 開放 UDP 51820，否則 VPN 客戶端無法連接。

FAQ¶

問：點解 VPN 客戶端連接唔到？

首先確認 Oracle Cloud Security List 已開放 UDP 51820，然後檢查容器是否運行緊：

docker ps

再查看日誌：

docker logs wg-easy

如果日誌顯示「Link is not up」或類似錯誤，可能需要重啟容器，令 WireGuard 模組重新初始化。

問：INSECURE=true 係咪好危險？

係。任何人都可以訪問管理介面並新增或刪除用戶。如果 Web 介面需要暴露到公網，應該改用：

      - PASSWORD=your_password

同時建議加入 HTTPS 反向代理，加密管理流量。

問：Wg Easy 支持 IPv6 嗎？

支持，但需要移除 DISABLE_IPV6=true，同時確保主機同 Oracle Cloud 網絡都正確設定 IPv6。

問：如何刪除某個 VPN 用戶？

喺 Web 介面對應用戶嘅列表入面，按刪除按鈕即可。刪除後，該用戶嘅配置文件會即時失效。

問：可以將 Web 介面改為其他連接埠嗎？

可以。修改 Compose 入面嘅 ports 映射，例如：

      - "8080:51821/tcp"

然後重新啟動容器。

Source¶

Coverage auto (container scan)