# 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 适配器随
  进程退出自动移除。