Architecture zh Hant

🌐 English | 繁體中文

架構

概念性導覽 Player Club Private VPN 的組成方式，以及各部分在儲存庫中的位置。各區塊目前的建置／測試狀態請見 專案狀態。

架構圖

目標架構。 NAT／TUN／FEC／分流通道區塊與 IPC 層已建置完成；遊戲偵測與設定／設定檔儲存為規劃中項目，此處僅呈現預定的形狀。

flowchart TB
    subgraph UI["前端 — Tauri WebView（React + TS + Tailwind）"]
        Nav["側邊欄 + 麵包屑"]
        Diag["診斷<br/>拓撲 · 頻譜 · 封包記錄"]
        Set["設定<br/>Basic / Expert · JSON 設定檔"]
        Pers["主題（6 種）+ 多語系"]
    end

    subgraph Core["後端 — Rust 引擎（src-tauri）"]
        CMD["Tauri 命令／事件層（IPC）"]
        NAT["NAT 穿透"]
        TUN["TUN/TAP 介面卡管理"]
        FEC["前向錯誤更正"]
        SPLIT["分流通道"]
        GAME["遊戲偵測"]
        CFG["設定／設定檔儲存"]
    end

    OS[("作業系統網路堆疊<br/>虛擬介面卡")]
    Peers(("遠端對等節點"))

    UI <-->|命令 / 事件| CMD
    CMD --> NAT
    CMD --> TUN
    CMD --> FEC
    CMD --> SPLIT
    CMD --> GAME
    CMD --> CFG
    TUN <--> OS
    NAT <-->|UDP 打洞| Peers
    FEC <--> Peers
    SPLIT --> OS

Loading

兩大部分：引擎與外殼

Rust 引擎（src-tauri/src/engine/）擁有所有觸及網路或作業系統的部分：加密機制、NAT 穿透、虛擬介面卡、FEC 與分流通道政策。它執行於 Tauri 的非同步執行環境（async runtime）之上，並透過 Tauri 的 IPC 命令／事件橋接將狀態與事件暴露給前端——前端從不直接接觸通訊端或介面卡。

React 前端（src/）負責呈現與控制：應用程式外殼、診斷讀數、設定，以及網路／Minecraft 頁面。它反映引擎狀態並發送命令；本身不含任何網路邏輯。

完整連線生命週期

1. 身分識別 — 首次執行時，引擎會產生一組 X25519 金鑰對，並儲存於本機（見 法律與私隱）。
2. 信令 — 兩個對等節點交換包含公鑰與 NAT 穿透候選位址的 Offer/Answer 字串。可手動進行（將字串貼到任何您信任的地方），或於使用具名虛擬網路時透過對等節點代管的信令伺服器自動中繼。
3. NAT 穿透（打洞） — 雙方向對方的每個候選位址發送 UDP 封包；第一次成功送達的交換即被提名為勝出路徑。此步驟同時也作為傳輸層的交握。
4. 交握 — Noise IK 交握流程使用雙方的 X25519 身分互相驗證，並衍生出具防重放保護的 AEAD 連線。
5. 資料層 — 本機的虛擬介面卡（Wintun，Windows）將 IP 封包交給引擎，引擎套用分流通道政策、視需要加入前向錯誤更正（Reed-Solomon）冗餘資料、加密後透過已驗證的連線傳送——接收時則進行相反流程。
6. 即時遙測 — RTT、抖動、遺失率、輸送量，以及 FEC／政策計數器會持續串流至診斷頁面。

為何不提供中繼／TURN，也不提供站對站共用

兩者刻意排除在範圍之外，理由相同：兩者都需要超出「兩個同意連線、且可直接透過 UDP 互相觸及的對等節點」這個模型的基礎設施或信任假設，而這正是本專案所承諾的模型。位於 NAT 之後且未設定連接埠轉發的代管者，或是網路無法直接穿透的對等節點，屬於已知限制而非錯誤——目前逐項的取捨狀態請見 專案狀態。

提升權限與輔助程序

在 Windows 上建立 Wintun 介面卡需要系統管理員權限。相較於將整個應用程式以提升權限重新啟動，引擎正朝向使用一個小型的提升權限輔助程序發展，該程序僅負責介面卡生命週期，並透過具名管線與主程序（未提升權限）通訊。詳見 engine::tun::windows 模組，以及專案狀態中「提升權限輔助程序」相關項目，可了解此遷移工作的確切進度。

專案結構

.
├── .github/
│   ├── workflows/                # CI（Windows／Linux／macOS 發布建置）
│   ├── ISSUE_TEMPLATE/           # 錯誤回報／功能請求表單
│   └── DISCUSSION_TEMPLATE/      # 討論分類表單
├── src-tauri/                    # Rust／Tauri 後端（網路引擎）
│   ├── src/
│   │   ├── engine/                # 引擎本體
│   │   │   ├── crypto/            # X25519 身分、Noise IK、AEAD 連線、防重放
│   │   │   ├── transport/         # 共用 UDP 通訊端、封裝、保活／RTT
│   │   │   ├── nat/               # STUN + 候選位址收集
│   │   │   ├── signaling/         # 容錯的 PCPV1 offer/answer 字串
│   │   │   ├── tun/               # 虛擬介面卡（Wintun）+ 提升權限
│   │   │   ├── dataplane/         # 介面卡 ⇄ 非同步驅動橋接
│   │   │   ├── fec/               # 前向錯誤更正（XOR 校驗）
│   │   │   ├── split_tunnel/      # 傳出／傳入封包政策
│   │   │   ├── telemetry/         # 指標、封包記錄、資料匯入接口
│   │   │   ├── pipeline.rs        # 交握 → 穩定狀態連線驅動
│   │   │   └── connection.rs      # 對等連線生命週期
│   │   └── commands/              # Tauri IPC 命令處理器 + 事件橋接
│   ├── capabilities/              # Tauri 權限能力設定
│   ├── resources/wintun/          # 隨附已簽署的 wintun.dll（見 THIRD-PARTY-NOTICES）
│   └── icons/                     # 應用程式圖示
├── src/                           # React + TypeScript 前端
│   ├── components/                # 版面外殼、診斷、設定、基礎元件
│   ├── pages/                     # 路由頁面
│   ├── hooks/                     # React hooks
│   ├── stores/                    # 用戶端狀態（zustand）
│   ├── lib/                       # 前端工具函式／IPC 包裝
│   ├── styles/                    # 全域＋Tailwind 樣式
│   ├── themes/                    # 預定義視覺主題
│   ├── i18n/locales/              # 翻譯檔
│   └── types/                     # 共用 TypeScript 型別
├── public/                        # 靜態公開檔案
├── README.md                      # 概觀＋快速開始（英文）
├── README.zh-Hant.md              # 概觀＋快速開始（繁體中文）
├── CHANGELOG.md                   # 版本異動記錄（僅英文）
├── LICENSE                        # 專有授權條款＋免責聲明——使用前請詳閱（英文，正式效力版）
├── LICENSE.zh-Hant.md             # 授權條款（繁體中文參考譯本）
├── TERMS_OF_SERVICE.md            # 規範軟體與專案使用之條款（英文，正式效力版）
├── PRIVACY_POLICY.md              # 應用程式處理／不處理哪些資料（英文，正式效力版）
├── SECURITY.md                    # 漏洞回報政策
├── PLATFORM-SUPPORT.md            # Windows 與 Linux／macOS 各自的可用功能與原因
└── THIRD-PARTY-NOTICES.md         # 隨附／第三方元件授權條款