docs(client/windows): 更新 README — 真机构建验证 + 字体打包 + 安装包 + 踩坑
记录:已真机 build 通过;ATL 前置;LNK1327/mt.exe(MANIFESTUAC)与 fetch SHA pin 排错; flutter build + ISCC 出安装包步骤;待人工验证清单(运行期连通/托盘/卸载)。 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
wangjia
+67
-22
@@ -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-<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。见 `runner/runner.exe.manifest`。
|
||||
- 未做 Inno Setup 安装包 / 代码签名 / CI Windows job（后续切片）。
|
||||
避免每次 UAC，类比 macOS 的 SMJobBless。
|
||||
- 代码签名 / CI Windows job 未做。
|
||||
- 停止用 `Process.kill`（Dart 在 Windows 映射为 TerminateProcess）；wintun 适配器随
|
||||
进程退出自动移除。
|
||||
|
||||
Reference in New Issue
Block a user