wangjia
caeef20df3
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>
59 lines
2.4 KiB
Markdown
59 lines
2.4 KiB
Markdown
# 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 Studio（C++ 桌面负载）。
|
||
- 拉取内核二进制（在仓库根，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 适配器随
|
||
进程退出自动移除。
|