Desktop WireGuard 架構與部署

SkyLab Connect 使用 WireGuard 建立桌面端到 Gateway VM 的加密 L3 網路。桌面端取得授權後，直接連到 VM 的實際位址與服務埠。

連線流程

1. Desktop Client 在本機產生 X25519 金鑰；私鑰只以 Electron safeStorage 加密保存。
2. Client 以登入 token 呼叫 POST /api/v1/desktop-client/wireguard/connect，只送出裝置 ID 與公鑰。
3. Backend 從既有 resources/my 授權邏輯取得使用者目前可控制、正在執行的 VM。
4. Backend 透過 Gateway 既有的 SSH 管理通道加入 WireGuard peer，並加入限時 nftables ACL。
5. Client 安裝短效 WireGuard tunnel，路由只包含 VM 子網，SSH/RDP 直接連線到 VM_IP:22 或 VM_IP:3389。
6. 使用者中斷或登出時，Client 移除本機 tunnel，Backend 同步移除 peer 與 ACL。

ACL tuple 為 client_tunnel_ip . vm_ip . tcp_port。LXC 僅開 SSH；QEMU VM 開 SSH 與 RDP。ACL 預設八小時到期，Gateway 即使無法收到中斷請求也會自動停止放行資料流。

Gateway VM

安裝腳本的預設值（每一項都能用 gateway/install.sh 開頭的同名環境變數覆寫；從「閘道 VM」頁「安裝服務」分頁一鍵安裝時，會依偵測到的網卡與後端的 WIREGUARD_* 設定自動填入）：

• WireGuard 介面：wg0／10.250.0.1/16（WG_INTERFACE、WG_ADDRESS）
• UDP 監聽 port：51821（WG_LISTEN_PORT；51820 留給 NetBird），由 eth0 接收（WG_INGRESS_INTERFACE）
• VM 網路：10.10.0.0/16，由 eth1 送出（WG_VM_SUBNET、WG_VM_INTERFACE）
• SNAT 位址：10.10.0.2，必須事先設在 eth1 上（WG_SNAT_ADDRESS）
• nftables table：inet skylab_wg
• systemd units：wg-quick@wg0、skylab-wg-firewall.service

Gateway 必須是 Debian 13（trixie）；其他系統（含 Debian 12，它的 nftables 太舊、不支援 nft destroy table）安裝腳本會在動到任何設定前拒絕執行。在新 Gateway 上先確認介面、位址與 UDP port 沒有衝突，再從「安裝服務」分頁執行安裝，或在 Gateway 上以 root 執行：

sudo ./gateway/install.sh

這是 Gateway 的唯一安裝入口，會安裝 nginx（Port 轉發與網域反向代理）、WireGuard、nftables ACL 與 SNAT，以及 Prometheus exporter；HTTPS 憑證由管理員自備。安裝腳本會先將網路、防火牆及服務設定備份到 /root/skylab-backups/，不會移除既有 NetBird，也不會清空整份 UFW ruleset。若 /etc/wireguard/wg0.conf 不是 SkyLab 管理的檔案，安裝腳本會拒絕覆寫。

Gateway 上游防火牆或 NAT 還必須將對外的 UDP 51821 轉送到 Gateway。若 Client 與 Gateway 位於同一個可路由網路，可直接使用 Gateway 的內部位址。

舊版安裝的 Gateway 仍使用 campus_cloud_wg 規則表。請先部署新版 Backend（它仍能操作舊規則），再從「安裝服務」分頁重新安裝。安裝腳本會保留 WireGuard 金鑰、建立 skylab_wg 與 skylab-wg-firewall.service、移除舊的 unit 與規則表，並更新 UFW 中舊名及新名的受管規則；不要手動改服務或規則表名稱。重新安裝會重建動態 ACL，需等 Backend 重播授權或讓 APP 重新連線。UFW 裡的 IPv4 與 (v6) 列，以及不同 VM IP 的 SSH ACL，是不同的規則，不是重複。

Backend 設定

WIREGUARD_ENDPOINT_HOST=vpn.example.edu      # Client 連得到的 DNS 名稱或公網 IP
WIREGUARD_ENDPOINT_PORT=51821
WIREGUARD_INTERFACE=wg0
WIREGUARD_CLIENT_SUBNET=10.250.0.0/16
WIREGUARD_VM_SUBNET=10.10.0.0/16
WIREGUARD_KEEPALIVE_SECONDS=25
WIREGUARD_SESSION_TTL_SECONDS=28800

除了 WIREGUARD_ENDPOINT_HOST，以上都是預設值；reconciler 相關設定（WIREGUARD_RECONCILE_*、WIREGUARD_REVOKED_RETENTION_DAYS、WIREGUARD_ALLOW_INACTIVE_PEER_TRANSFER）列在環境變數對照表。

WIREGUARD_VM_SUBNET 只是 IP 管理設定好之前的備援值。設定之後，桌面端路由、連線目標、Gateway ACL 與 SNAT 安裝一律以 IP 管理的平台子網為準。

正式環境的 WIREGUARD_ENDPOINT_HOST 應填 Client 可以到達的 DNS 名稱或公網 IP。留空時，Client 拿到的是「閘道 VM」連線設定裡的 Gateway 位址，也就是管理用的 SSH 位址，外部通常連不到。

Desktop Client

Windows 版本使用官方 WireGuard for Windows 的 tunnel service。正式 Setup EXE 內含經 SHA-256 與 Authenticode 驗證的官方 MSI，安裝 SkyLab Connect 時會一併安裝；portable EXE 若偵測到系統尚未安裝 WireGuard，會在第一次連線時要求 UAC 並安裝同一份 MSI。因此學生不需要事先另外下載 WireGuard。

WireGuard 是共用的系統網路元件，移除 SkyLab Connect 時不會連帶移除 WireGuard，以免中斷其他應用程式的 tunnel。第三方授權聲明會一起放在 App resources 的 wireguard/THIRD_PARTY_NOTICES.txt。

Client 不會把私鑰傳給 Backend，產生 tunnel 設定後也會立即刪除暫存明文設定檔。

驗證

Gateway 健康檢查：

systemctl is-active wg-quick@wg0 skylab-wg-firewall.service
wg show wg0
nft list set inet skylab_wg allowed_tcp

連線後應看到一個 peer，以及只屬於該使用者 VM 的限時 ACL。中斷後 peer 與對應 ACL 應立即消失。從 Client 測試時，應直接連 VM IP。