feat(client): 新增 Windows 桌面端(sing-box TUN 全局代理)
ci-pangolin / Lint — shellcheck (push) Has been cancelled
ci-pangolin / Unit Tests — nginx cfg + compose (push) Has been cancelled
ci-pangolin / OpenAPI Sync Check (push) Has been cancelled
ci-pangolin / Redline Scan — 脱敏 (UI 文案) (push) Has been cancelled
ci-pangolin / Flutter — analyze + test (push) Has been cancelled
ci-pangolin / Image Build — pangolin-edge (push) Has been cancelled

Windows 与 macOS 桌面同路线:Flutter 应用 + sing-box.exe 子进程 + wintun TUN
接管整机流量。Dart/桥接层此前已 Windows-ready(kernel_process._buildCommand /
_resolveBinaryPath、desktop_vpn_bridge 配置路径、fetch-desktop-bin.sh),本次补
原生外壳 + 提权 + 打包:

- flutter create --platforms=windows 生成 windows/ runner(flutter_secure_storage
  已注册 windows 插件,token 存储可用)。
- runner.exe.manifest 设 requestedExecutionLevel=requireAdministrator:启动 UAC
  提权,sing-box 子进程继承管理员权以创建 wintun TUN(与 _buildCommand 既有设计一致)。
- windows/CMakeLists.txt 增 install 规则:打包时把 app/kernel/dist/desktop/windows-*/
  {sing-box.exe,wintun.dll} 拷到 app exe 同级目录(存在才拷,缺失告警,类比 android
  build.gradle 占位)。
- kernel_process.dart 启动时校验 wintun.dll 与 sing-box.exe 同目录,缺失早警。
- windows/README.md:拉内核二进制 / 管理员终端 flutter run / 打包 / 出网验证步骤。

提权用 requireAdministrator(每次 UAC),正式版可换特权 helper(BACKLOG,类比 SMJobBless)。

本机(macOS)验证:flutter analyze 无 error。Windows 真机 build/连通验证待后续
(无 Windows 机器,状态同 Android/iOS:代码就绪、未真机验证)。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
wangjia
2026-06-17 07:49:26 +08:00
parent f1bd35afd9
commit caeef20df3
21 changed files with 1212 additions and 1 deletions
+58
View File
@@ -0,0 +1,58 @@
# Windows 桌面端(全局代理)
Windows 版与 macOS 桌面同路线:Flutter 应用 + `sing-box.exe` 子进程 + **wintun** TUN
接管整机流量(全局代理)。提权方式:应用 manifest 设了 `requireAdministrator`
启动时 UAC 提权,`sing-box.exe` 子进程继承管理员权以创建 TUN 适配器。
> 状态:代码就绪,**未在真 Windows 机器上构建/验证过**(开发在 macOS)。以下为
> 在 Windows 上首次构建运行的步骤。
## 前置
- Windows 10/11,已装 Flutter(含 Windows 桌面支持)、Visual StudioC++ 桌面负载)。
- 拉取内核二进制(在仓库根,Git Bash / WSL 下跑;脚本会下载 sing-box.exe + wintun.dll
并校验 SHA256):
```bash
app/kernel/fetch-desktop-bin.sh windows amd64
# 产物:app/kernel/dist/desktop/windows-amd64/{sing-box.exe, wintun.dll}
```
## 开发运行(flutter run
从仓库内直接跑时,`kernel_process.dart` 的 `_resolveBinaryPath` 会从可执行目录向上
查找 `app/kernel/dist/desktop/windows-amd64/sing-box.exe`,无需手动放置:
```powershell
# 必须用「管理员」终端(TUN 需要管理员权)
cd client
flutter run -d windows --dart-define=PANGOLIN_API_URL=http://<后端IP>:8080
```
也可用环境变量显式指定二进制:
`set PANGOLIN_SINGBOX_BIN=C:\path\to\sing-box.exe`(同目录须有 `wintun.dll`)。
## 打包(release
`flutter build windows` 后,CMake 的 install 步骤会自动把
`app/kernel/dist/desktop/windows-*/{sing-box.exe, wintun.dll}` 拷到 app `.exe` 同级目录
(见 `windows/CMakeLists.txt` 的 “Pangolin sing-box kernel” 段)。**wintun.dll 必须与
sing-box.exe 同目录**,否则 sing-box 无法创建 TUN。
## 端到端验证(连通出网)
1. 管理员终端 `flutter run -d windows`(或运行打包后的 `.exe`,会弹 UAC)。
2. 登录 → 选节点 → connect。
3. 验证全局代理生效:
```powershell
curl https://api.ipify.org # 出口 IP 应为节点公网 IP
```
## 已知限制 / BACKLOG
- 提权用 `requireAdministrator`(每次启动弹一次 UAC)。正式版可换**特权 helper 服务**
避免每次 UAC,类比 macOS 的 SMJobBless。见 `runner/runner.exe.manifest`。
- 未做 Inno Setup 安装包 / 代码签名 / CI Windows job(后续切片)。
- 停止用 `Process.kill`Dart 在 Windows 映射为 TerminateProcess);wintun 适配器随
进程退出自动移除。