pangolin/client/windows

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)」；或命令行（管理员）：

  & "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 校验）：

  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，无需手动放置：

# 必须用「管理员」终端（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 -ExecutionPolicy Bypass -File client\windows\build.ps1 -ApiUrl http://<后端IP>:8080
# 只构建不出安装包：加 -SkipInstaller

或手动分步：

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 若未含官方简中包，脚本相对引用之）。

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