KillSwitch 设计与跨平台能力矩阵（知识库）

Pangolin 客户端 · 断网保护设计依据与现状 · 2026-06-22（2026-06-30 更新：macOS L0→L3 已实现）

KillSwitch 不是「一个开关」，而是分层能力——理想态、平台天花板、当前实现是三件不同的事。本文沉淀其设计依据与现状。

1. 本质：fail-closed

KillSwitch 的本质是 fail-closed：

隧道不处于活动状态时，禁止任何流量走明文/默认路径出去。

目标是堵住 VPN 掉线瞬间的 IP / DNS 泄漏。没有 KillSwitch 时，隧道一掉，流量静默回落到运营商默认路由，用户真实 IP 与 DNS 查询直接暴露——对科学上网场景是致命泄漏。

2. 理想设计的 5 条属性

默认关闭（fail-closed）：隧道一旦不可用，流量是「被丢弃」而非「放行」。
扛得住进程死亡 ← 最难。app/内核进程崩溃或被系统杀掉后，封锁依然生效。这要求封锁由 OS 内核/框架强制，而不是靠 app 进程内的路由表。
覆盖所有「缺口窗口」：开机后还没连上的窗口、掉线重连的窗口、进程崩溃的窗口——三个都要堵。
DNS 防泄漏：DNS 查询也强制走隧道或被一并阻断。
可控范围 + 诚实 UI：可选放行 LAN（局域网打印机等）、可选分应用；并如实告诉用户当前到底保护到了哪一层，不夸大。

3. 能力分级（统一标尺）

Level	机制	能堵什么	堵不住什么
L0 无	掉线即走明文	—	全泄漏
L1 内核路由绑定（软）	路由绑死隧道接口（如 sing-box `strict_route`）	进程活着、隧道未建/重连时不泄漏	进程一死、接口被拆 → 路由恢复 → 泄漏
L2 OS 防火墙强制（硬）	OS 级包过滤规则（NE 框架 / WFP / nftables）阻断非隧道流量	进程死了也照堵（规则在 OS 内核，不在 app）	开机到规则生效前的窗口
L3 常开 + 开机持久	L2 + OS 从开机起自动拉起 VPN 并强制阻断	开机窗口也堵，全程 fail-closed	（基本无死角）

理想态 = L3。

关键认知：L1 与 L2 之间有一条质变线——L1 是「app 进程内的约束」，L2/L3 是「OS 框架的约束」。只有跨过这条线才算「真 KillSwitch」。目前 Pangolin 各平台用的 strict_route 都还停在 L1。

4. 各平台能力天花板

平台	机制	天花板	说明
macOS	NetworkExtension System Extension	L3	`includeAllNetworks=true` 全量入隧道 + `NEOnDemandRule` 常开 + `enforceRoutes`。NE 守护进程（neagent）在系统级强制，扛 app 崩溃。Apple 平台原生支持最完整。
iOS	NetworkExtension	L3	同 NE 原语，甚至更干净；on-demand「按需常开」。⚠️ 目前无 iOS 客户端。
Android	VpnService	L3，但有条件	app 内只能到 L1（`strict_route`）；真正的 L2/L3 = 系统设置「始终开启 VPN + 无 VPN 时阻止连接」，OS 级强制、扛崩溃、开机生效。但 app 不能编程开启，只能深链引导用户手动开（或 Device Owner/MDM 下发）。
Windows	子进程 sing-box + wintun	L2（需开发）	现仅 `strict_route`（L1）。要到 L2 须让 app 装 WFP（Windows Filtering Platform）过滤器阻断非隧道流量；做成系统服务持久化才能扛崩溃。
Linux（非主目标）	子进程 + tun	L2（需开发）	L1 现成；L2 靠 nftables/iptables killswitch 链。

一句话：Apple 两端原生能直达 L3；Android 能到 L3 但要用户手动配合；Windows/Linux 要自己写 OS 防火墙规则才能上 L2。

5. 各平台当前实际实现（代码事实）

平台	当前 Level	真实状态	代码位置
Windows	L1	✅ 改 `strict_route` + 子进程重载 + 退避重连。进程被硬杀仍泄漏。	`desktop_vpn_bridge.dart:305`（`applyKillSwitchToConfig`）、`:178`
Linux	L1	同 Windows（共用 `DesktopVpnBridge`）。	同上
macOS	L3	✅ NE fail-closed(本轮 #1）：`includeAllNetworks`+`enforceRoutes`（L2 OS 强制、扛崩溃）+ `NEOnDemandRule` 常开（L3）。随 killswitch 开关即时切换；手动断开先关 on-demand 防反弹。详见 §6.5。	`VpnChannel.swift`（`configureKillSwitch`）、`PacketTunnelProvider.swift`（`includeAllNetworks()`）
Android	L0	❌ stub：`setKillSwitch` 只打日志（TODO 11G）。	`MainActivity.kt`（`setKillSwitch` 分支）
iOS	—	无客户端。	—

注：macOS 自 kUseNativeVpnMacOS=true（vpn_bridge_provider.dart:19）起走原生 System Extension，不再走 DesktopVpnBridge。所以 macOS 的 strict_route（Windows 路线）对它不生效，必须走 NE 原生路线。

6. Pangolin 现实判断与决策

能力与实现曾严重不匹配：macOS 明明能 L3，过去却是 L0（最差）；Windows 反而是唯一做了的（L1）。已修复 macOS 已补齐到 L3（见 §6.5）。
Android 客户端方案的 KillSwitch 定位（MVP+ 阶段）：app 内做到 L1（strict_route，与 Windows 一致），再引导用户开系统 Always-on 拿到 L3，UI 上诚实标注「彻底防泄漏需在系统设置开启」。这是「app 能力上限 + OS 兜底」的合理组合，不夸大。
跨端一致性缺口（按性价比排序）：
1. macOS 原生 11G（includeAllNetworks + on-demand）—— 天花板 L3、改动集中在 Swift，性价比最高。
2. Windows L1→L2（WFP 防火墙强制）—— 工作量较大（需原生过滤器 + 持久化服务）。
3. Android —— 受 OS 限制，编程上限就是 L1，剩下靠引导，无更高可做空间。

6.5 macOS L0→L3 实现方案（本轮 #1）

macOS 走原生 NE System Extension（kUseNativeVpnMacOS=true），strict_route 那套对它不生效，必须用 NE 原语。L0→L3 的达成路径：

目标 Level	NE 机制	效果
L2 OS 强制	`protocolConfiguration.includeAllNetworks=true` + `enforceRoutes=true`	全量流量入隧道、由 `neagent` 系统级强制，扛 app/内核崩溃（规则在 OS 不在 app 进程）
L3 常开+持久	L2 + `onDemandRules=[NEOnDemandRuleConnect()]` + `isOnDemandEnabled=true`	掉线/开机窗口也堵，OS 自动拉起，全程 fail-closed

改动（2 个原生文件，不动 Dart/服务端）

client/macos/Runner/VpnChannel.swift

新增缓存字段 killSwitchEnabled（默认 true，与 Dart AppSettings.killSwitch 默认对齐）。
setKillSwitch 落地：存标志；若 manager 已存在 → 重新 applyKillSwitchConfig + saveToPreferences 即时生效。
loadOrCreateManager 按标志设：includeAllNetworks / enforceRoutes=true / excludeLocalNetworks=true（放行 LAN 打印机等）/ onDemandRules + isOnDemandEnabled。
关键 gotcha — stop()：on-demand 常开时直接 stopVPNTunnel() 会被 OS 立刻拉回。手动断开须先 isOnDemandEnabled=false + saveToPreferences 再 stop；否则「断开」按钮失效。
start() 的 startVPNTunnel(options:) 附带 killSwitch 标志传给扩展。

client/macos/PacketTunnel/PacketTunnelProvider.swift

startTunnel(options:) 读取 killSwitch 选项并缓存。
libbox 回调 includeAllNetworks() 返回该缓存值（与 NE 层对齐，让 sing-box 不装绕行路由）。

无需新增 entitlement（packet-tunnel-provider 已有）；includeAllNetworks/enforceRoutes/excludeLocalNetworks/on-demand 均 macOS 10.15/11+ 可用，Runner 部署目标满足。

验证（NE 难单测，靠真机手测）

flutter build macos 通过、sysext 激活。
killswitch 开 + 连接 → 正常上网；杀扩展进程或拔隧道 → 流量被阻断（无 IP/DNS 泄漏）= 跨过 L1→L2 质变线。
on-demand：开机/掉线窗口隧道自动拉起；手动「断开」能真断、不反弹（验 stop() 的 on-demand 处理）。
killswitch 关 → on-demand 取消、回普通连接。

7. 关联待办

KillSwitch 相关待办见项目 todo/（/todo list），主要三条：

#1 mac macOS 原生 KillSwitch 补齐 L0→L3（includeAllNetworks + on-demand）
#2 Android Android KillSwitch L1（strict_route）+ 引导系统 Always-on（属 Android 客户端 11G）
#3 Windows Windows KillSwitch L1→L2（WFP 防火墙强制，backlog）

8. 参考实现位置索引

主题	文件
桥接契约（`setKillSwitch` 方法签名）	`client/lib/bridge/vpn_bridge.dart`
平台分派（哪个平台走哪个 bridge）	`client/lib/bridge/vpn_bridge_provider.dart`
Windows/Linux 实现（strict_route）	`client/lib/bridge/desktop_vpn_bridge.dart`
macOS 原生通道（stub）	`client/macos/Runner/VpnChannel.swift`
macOS 隧道 Provider	`client/macos/PacketTunnel/PacketTunnelProvider.swift`
Android 通道（stub）	`client/android/app/src/main/kotlin/com/pangolin/pangolin_vpn/MainActivity.kt`
Android VPN 服务	`client/android/app/src/main/kotlin/com/pangolin/pangolin_vpn/PangolinVpnService.kt`