From ec0e3d14986ff869c42721044526af3a8c379c78 Mon Sep 17 00:00:00 2001 From: wangjia <809946525@qq.com> Date: Mon, 22 Jun 2026 09:08:19 +0800 Subject: [PATCH] =?UTF-8?q?docs(client/windows):=20=E6=9B=B4=E6=96=B0=20RE?= =?UTF-8?q?ADME=20=E2=80=94=20=E7=9C=9F=E6=9C=BA=E6=9E=84=E5=BB=BA?= =?UTF-8?q?=E9=AA=8C=E8=AF=81=20+=20=E5=AD=97=E4=BD=93=E6=89=93=E5=8C=85?= =?UTF-8?q?=20+=20=E5=AE=89=E8=A3=85=E5=8C=85=20+=20=E8=B8=A9=E5=9D=91?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 记录:已真机 build 通过;ATL 前置;LNK1327/mt.exe(MANIFESTUAC)与 fetch SHA pin 排错; flutter build + ISCC 出安装包步骤;待人工验证清单(运行期连通/托盘/卸载)。 Co-Authored-By: Claude Opus 4.8 --- client/windows/README.md | 89 ++++++++++++++++++++++++++++++---------- 1 file changed, 67 insertions(+), 22 deletions(-) diff --git a/client/windows/README.md b/client/windows/README.md index 33cd533..c9896ea 100644 --- a/client/windows/README.md +++ b/client/windows/README.md @@ -4,24 +4,39 @@ Windows 版与 macOS 桌面同路线：Flutter 应用 + `sing-box.exe` 子进程 接管整机流量（全局代理）。提权方式：应用 manifest 设了 `requireAdministrator`， 启动时 UAC 提权，`sing-box.exe` 子进程继承管理员权以创建 TUN 适配器。 -> 状态：代码就绪，**未在真 Windows 机器上构建/验证过**（开发在 macOS）。以下为 -> 在 Windows 上首次构建运行的步骤。 +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（C++ 桌面负载）。 -- 拉取内核二进制（在仓库根，Git Bash / WSL 下跑；脚本会下载 sing-box.exe + wintun.dll - 并校验 SHA256）： - +- 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`，无需手动放置： +`kernel_process.dart` 的 `_resolveBinaryPath` 会从可执行目录向上查找 +`app/kernel/dist/desktop/windows-amd64/sing-box.exe`，无需手动放置： ```powershell # 必须用「管理员」终端（TUN 需要管理员权） @@ -34,25 +49,55 @@ flutter run -d windows --dart-define=PANGOLIN_API_URL=http://<后端IP>:8080 ## 打包（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。 +```powershell +cd client +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。 -## 端到端验证（连通出网） +产物：`client\build\windows\x64\runner\Release\`（含 `pangolin_vpn.exe`、Flutter 运行时、 +插件 DLL、`sing-box.exe`、`wintun.dll`、`data\`(含打包字体)）。 -1. 管理员终端 `flutter run -d windows`（或运行打包后的 `.exe`，会弹 UAC）。 -2. 登录 → 选节点 → connect。 -3. 验证全局代理生效： +## 出安装包（Inno Setup） - ```powershell - curl https://api.ipify.org # 出口 IP 应为节点公网 IP - ``` +需装 **Inno Setup 6**。脚本在 `client/windows/installer/pangolin.iss`，简中语言包 +`ChineseSimplified.isl` 随仓库附带（本机 Inno Setup 若未含官方简中包，脚本相对引用之）。 -## 已知限制 / BACKLOG +```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-.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。见 `runner/runner.exe.manifest`。 -- 未做 Inno Setup 安装包 / 代码签名 / CI Windows job（后续切片）。 + 避免每次 UAC，类比 macOS 的 SMJobBless。 +- 代码签名 / CI Windows job 未做。 - 停止用 `Process.kill`（Dart 在 Windows 映射为 TerminateProcess）；wintun 适配器随 进程退出自动移除。