wangjia
118 lines
6.2 KiB
Markdown
118 lines
6.2 KiB
Markdown
# Windows 桌面端（全局代理）
|
||
|
||
Windows 版与 macOS 桌面同路线：Flutter 应用 + `sing-box.exe` 子进程 + **wintun** TUN
|
||
接管整机流量（全局代理）。提权方式：应用 manifest 设了 `requireAdministrator`，
|
||
启动时 UAC 提权，`sing-box.exe` 子进程继承管理员权以创建 TUN 适配器。
|
||
|
||
UI 复用桌面 shell（`DesktopShell`，原生标题栏 + 侧栏 + 内容区），无 Windows 专属页面。
|
||
字体随应用本地打包（拉丁全量 + Noto Sans SC GB2312 子集），离线可用，不依赖联网拉字体。
|
||
|
||
> 状态（2026-06-22）：**已在真 Windows 11(23H2)机器上 `flutter build windows` 构建通过**，
|
||
> 产物结构、内核二进制捆绑、`requireAdministrator` 清单均验证无误；Inno Setup 安装包
|
||
> 编译通过。**登录→连接→出网的运行期端到端验证尚需在交互桌面 + 后端节点下人工完成**
|
||
> （见末尾「待人工验证」）。
|
||
|
||
## 前置
|
||
|
||
- Windows 10/11，已装 Flutter（含 Windows 桌面支持）、Visual Studio 或 **Build Tools**
|
||
2022（C++ 桌面负载）。
|
||
- **必须含 ATL 组件**：`flutter_secure_storage_windows` 依赖 `atlstr.h`。缺则链接报
|
||
`C1083: atlstr.h`。安装：Visual Studio Installer → 修改 → 单个组件 → 勾「C++ ATL
|
||
for latest v143 build tools (x86 & x64)」；或命令行（管理员）：
|
||
```powershell
|
||
& "C:\Program Files (x86)\Microsoft Visual Studio\Installer\vs_installer.exe" modify `
|
||
--installPath "C:\BuildTools" --add Microsoft.VisualStudio.Component.VC.ATL --quiet --norestart
|
||
```
|
||
- 拉取内核二进制（仓库根，Git Bash 下跑；脚本下载 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}
|
||
```
|
||
> 注：sing-box 自 v1.13 起 Release 不再发布 `checksums.txt`，脚本已改为内置各压缩包
|
||
> SHA256 校验（升级 `app/kernel/VERSION` 的 `SINGBOX_VERSION` 时须同步更新脚本内 case 表）。
|
||
> 国内网络若下载失败：开代理重试，或手动放置二进制到该目录。
|
||
|
||
## 开发运行（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）
|
||
|
||
**推荐：一键脚本**（拉内核 → 带 dart-define 构建 → 出安装包，自动避开漏 `--dart-define` 的坑）：
|
||
|
||
```powershell
|
||
powershell -ExecutionPolicy Bypass -File client\windows\build.ps1 -ApiUrl http://<后端IP>:8080
|
||
# 只构建不出安装包：加 -SkipInstaller
|
||
```
|
||
|
||
或手动分步：
|
||
|
||
```powershell
|
||
cd client
|
||
# 必须带 --dart-define 指定后端，否则默认连 localhost:8080，登录会「网络请求失败」
|
||
flutter build windows --dart-define=PANGOLIN_API_URL=http://<后端IP>:8080
|
||
```
|
||
> ⚠️ `kApiBaseUrl`（见 `lib/services/api_config.dart`）当前默认值是联调测试节点（临时，发版前会改回 localhost/正式域名）。
|
||
> 正式 Release 包**务必显式** `--dart-define=PANGOLIN_API_URL=...` 指定后端，构建期烘进二进制；
|
||
> 一旦默认值改回 localhost，漏传 dart-define 就会复现登录「网络请求失败」。
|
||
|
||
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。
|
||
|
||
产物：`client\build\windows\x64\runner\Release\`（含 `pangolin_vpn.exe`、Flutter 运行时、
|
||
插件 DLL、`sing-box.exe`、`wintun.dll`、`data\`(含打包字体)）。
|
||
|
||
## 出安装包（Inno Setup）
|
||
|
||
需装 **Inno Setup 6**。脚本在 `client/windows/installer/pangolin.iss`，简中语言包
|
||
`ChineseSimplified.isl` 随仓库附带（本机 Inno Setup 若未含官方简中包，脚本相对引用之）。
|
||
|
||
```powershell
|
||
# 先 flutter build windows(Release),再编译安装包
|
||
& "C:\Program Files (x86)\Inno Setup 6\ISCC.exe" client\windows\installer\pangolin.iss
|
||
# 产物：client\windows\installer\Output\pangolin-setup-<ver>.exe（约 24MB）
|
||
```
|
||
安装包：装到 `Program Files\Pangolin`，建开始菜单 + 桌面快捷方式，卸载清理
|
||
`%LOCALAPPDATA%\Pangolin`。
|
||
|
||
## 待人工验证（交互桌面 + 后端节点）
|
||
|
||
以下需在 Windows 桌面前操作（SSH 无交互/UAC 桌面，无法替代）：
|
||
|
||
1. 管理员运行 `flutter run -d windows`（或装好的安装包），弹一次 UAC → 进主界面。
|
||
2. 登录 → 选节点 → connect → `curl https://api.ipify.org` 出口应为节点公网 IP。
|
||
3. 停止/重连/kill-switch/托盘(关闭最小化、显示、退出)/开机自启；退出后
|
||
`tasklist | findstr sing-box` 无残留、网络适配器无残留 wintun TUN。
|
||
4. 安装包安装→运行→卸载干净；高分屏(125%/150%)界面不糊不溢出。
|
||
|
||
## 已知坑 / 构建排错（真机踩过）
|
||
|
||
- **`C1083: atlstr.h`**：VS 缺 ATL 组件，按「前置」装上。
|
||
- **`LNK1327` / `mt.exe c1010001 "level not equal"`**：`runner.exe.manifest` 的
|
||
`requireAdministrator` 与链接器默认注入的 `asInvoker` UAC 清单冲突。已在
|
||
`windows/runner/CMakeLists.txt` 加 `/MANIFESTUAC:NO` 修复（仅用 manifest 文件的 level）。
|
||
- **`jni` 出现在 `generated_plugins.cmake` 的 FFI 列表**：经 `path_provider_android`
|
||
传递引入，其 Windows CMake 用 `find_package(JNI)`(非 REQUIRED)，无 JVM 时优雅产出空
|
||
bundled libs，**不影响 Windows 构建**（已验证）。
|
||
- **fetch 脚本 404**：见「前置」——sing-box 停发 checksums.txt，已改内置 SHA pin。
|
||
|
||
## BACKLOG
|
||
|
||
- 提权用 `requireAdministrator`（每次启动弹一次 UAC）。正式版可换**特权 helper 服务**
|
||
避免每次 UAC，类比 macOS 的 SMJobBless。
|
||
- 代码签名 / CI Windows job 未做。
|
||
- 停止用 `Process.kill`（Dart 在 Windows 映射为 TerminateProcess）；wintun 适配器随
|
||
进程退出自动移除。
|