CLI 基础知识和安装
9 个解答了解 PandaVPN CLI 是什么、它与桌面应用程序有何不同以及如何安装它。
Q Panda CLI 是什么？
Panda CLI 是 Panda 的命令行客户端，支持通过终端完成：
- 登录与账号管理
- 节点刷新与节点连接
- PandaVPN / Proxy / WireGuard / Auto 模式切换
- 系统代理配置
- Split rules 分流规则
- Split DNS 配置
- Kill-switch 防护
- Auto-connect
- 日志和诊断
它适合内测用户、开发者、高级用户和需要脚本化操作的测试场景。
Q Panda CLI 和桌面客户端有什么区别？
Panda CLI 通过命令行操作，更适合：
- 自动化测试
- 远程排查
- 脚本化连接
- 查看详细诊断信息
- 验证 Kill-switch、DNS、路由、系统代理等底层行为
桌面客户端更适合普通用户日常图形化操作。
注意：旧 Qt 桌面客户端和 CLI 不建议同时管理 VPN / 系统代理，避免互相覆盖配置。
Q Panda CLI 为什么需要 daemon / service？
部分能力需要系统级权限，例如：
- 创建 TUN / WireGuard 网络接口
- 修改 DNS
- 设置系统代理
- 应用 Kill-switch
- 修复路由
- 管理 packet VPN runtime
因此 CLI 会通过平台对应的 daemon / service 执行这些操作。
不同平台的 daemon 形式：
| 平台 | daemon 形式 |
|---|---|
| macOS | LaunchDaemon / privileged helper |
| Linux | systemd service |
| Windows | Windows Service |
Q Windows / macOS / Linux 的安装方式有什么区别？
核心区别是：Windows 和 macOS 通常通过安装包自动安装服务，Linux 通常需要用户手动执行 sudo panda service install。
| 平台 | 推荐安装方式 | 是否需要手动安装 service |
|---|---|---|
| Windows | 安装包 | 通常不需要；安装包会提权并注册 Windows Service |
| macOS | .pkg 安装包 | 通常不需要；安装包会安装 LaunchDaemon / helper |
| Linux | binary + systemd service | 需要执行 sudo panda service install |
Windows 只有在不使用安装包、手动放置二进制文件时，才需要管理员 PowerShell 执行：
panda service install windows
macOS 只有在开发调试、未使用 .pkg 安装包，或 daemon 未自动启动时，才需要：
sudo panda start
Linux 推荐：
sudo panda service install panda service status
Q Windows ARM64 和 AMD64 / x64 的安装步骤一样吗？
一样。区别主要是下载的安装包架构不同。
| 架构 | 适用设备 |
|---|---|
| Windows x64 / AMD64 | 大多数 Intel / AMD Windows 电脑 |
| Windows ARM64 | Windows on ARM 设备 |
安装步骤、命令和服务管理方式一致。安装包会自动提权并注册 Windows Service。
连接方式和路由
10 个解答了解 CLI 连接模式、路由选项、智能连接、节点和当前状态。
Q Panda CLI 支持哪些模式？
主要支持：
| 模式 | 说明 |
|---|---|
| auto | 默认模式。按 API / 节点元数据推荐 runtime，失败时回退到 PandaVPN global |
| proxy | 本地 SOCKS5 / HTTP / PAC 代理 |
| pandavpn | PandaVPN packet VPN / TUN runtime |
| wireguard | WireGuard packet VPN |
常用设置：
panda mode auto panda mode pandavpn global panda mode proxy global panda mode wireguard
openvpn 当前不建议作为用户文档中的主线模式展示。
Q auto、proxy、pandavpn、wireguard 应该怎么选？
建议：
| 场景 | 推荐模式 |
|---|---|
| 新用户 / 日常连接 | auto |
| 想固定使用全局 VPN | pandavpn global |
| 只想让浏览器或系统代理走 Panda | proxy |
| 需要 Kill-switch | auto、pandavpn 或 wireguard |
| 节点提供 WireGuard metadata | auto 或 wireguard |
| 需要 Split rules / Split DNS 深度验证 | pandavpn |
注意：mode proxy 与 Kill-switch 互斥。
Q mode auto 是什么？
mode auto 是新版默认模式。
它的行为是：
- API node / smart connect 按 meta.protocol 优先选择 runtime；
- 如果推荐 WireGuard，会优先尝试 WireGuard；
- 如果 WireGuard 元数据、地址分配、runtime 启动、handshake 或连通性探测失败，会回退到 SS payload 编译的 PandaVPN global；
- SS、OPENVPN、未知或缺失协议会使用 PandaVPN global 兜底；
- mode auto 不接受 policy 参数，解析出的 runtime 恒为 global。
推荐新用户使用：
panda mode auto panda connect
Q global、gfwlist、direct-region、proxy-region 有什么区别？
| Policy | 含义 |
|---|---|
| global | 全部走代理 / 隧道 |
| gfwlist | default direct；GFWList 命中走代理 / 隧道 |
| direct-region in | default proxy / tunnel；in 两字母国家码命中直连 |
| proxy-region us | default direct；us 两字母国家码命中走代理 / 隧道 |
direct-region 是推荐写法；bypass-region / bypass 是兼容别名。
例如：
panda mode pandavpn direct-region in
等价于兼容别名：
panda mode pandavpn bypass-region in
Q PandaVPN 的显式 split 长命令是什么？
新版支持更完整的 split profile 写法：
panda mode pandavpn split default direct proxy-region <cc> panda mode pandavpn split default proxy direct-region <cc>
常见 token：
| Token | 含义 |
|---|---|
| default direct | 未命中规则默认直连 |
| default proxy | 未命中规则默认走隧道 |
| proxy-region <cc> | 指定地区走隧道 |
| direct-region <cc> | 指定地区直连 |
| gfwlist | 启用 GFWList source |
| direct-lan | LAN 直连 |
| proxy-lan | LAN 也走隧道 |
| custom-rules | 启用自定义 split rules |
| exclude-custom-rules | 不加载自定义 split rules |
示例：
panda mode pandavpn split default direct proxy-region us custom-rules panda mode pandavpn split default proxy direct-region in direct-lan custom-rules
新手文档不建议展示长命令，适合放在高级分流文档中。
Diagnostics and logs
9 个解答将这些问题用于医生、修复、日志、系统代理、拆分规则、拆分 DNS 和终止开关行为。
Q panda doctor 是做什么的？
doctor 是只读诊断命令，用于查看当前 Panda CLI 关键状态。
panda doctor panda doctor --json
短写：
panda do
重点关注：
runtime kill_switch selected_node vpn_dns dns_lockdown split_policy system_proxy_state vpn_routes last_error
Q panda trace 是什么？
trace 用于查看某个目标会走哪条规则、DNS action 和 route。
panda trace example.com:443 panda trace 8.8.8.8:53 --json
注意：完整 trace 能力需要 active PandaVPN packet runtime。无兼容 runtime 时，只能做有限校验或回退 legacy trace。
Q 为什么会出现两个 Panda daemon 抢路由？
通常是因为既安装了正式 service / LaunchDaemon，又手动执行过：
sudo panda start
sudo panda start 会启动一个 unmanaged / 脱管 daemon，可能与正式 daemon 同时管理：
- VPN 路由
- DNS
- TUN
- 系统代理
- Kill-switch
处理原则是：只保留一个 daemon。
macOS / Linux 常用处理：
panda disconnect panda kill-switch off sudo panda stop panda repair panda doctor
Linux 如果使用 systemd service，随后重启正式服务：
sudo panda service restart panda doctor
macOS 如果使用 .pkg 安装，通常让 LaunchDaemon / helper 管理 daemon，不要长期使用 sudo panda start 作为日常启动方式。
Q Panda daemon 怎么退出？
如果只是断开 VPN，不需要退出 daemon：
panda disconnect panda kill-switch off
如果确实要停止 daemon：
sudo panda stop
确认：
panda status
如果显示 panda daemon unavailable，说明主 daemon 已停止。
注意：macOS .pkg 安装的 LaunchDaemon / helper 可能会被系统管理，不建议普通用户频繁手动停服务。
Q 如何查看日志？
panda log panda log --lines 200 panda log --all
清理日志：
panda log clear
临时打开 debug：
panda log level debug dns,tcp --ttl 10m
恢复默认：
panda log level reset
Proxy and repair
5 个解答将这些问题用于医生、修复、日志、系统代理、拆分规则、拆分 DNS 和终止开关行为。
Q panda repair 和 panda proxy repair 有什么区别？
panda repair 更综合，可能修复：
- VPN route
- DNS 快照
- Kill-switch guard
- 系统代理相关状态
panda proxy repair 主要修复当前用户的系统代理漂移。
panda repair panda proxy repair
Q 系统代理默认会开启吗？
Fresh install 默认 proxy system-proxy on。
如果用户显式保存过 off，会保留该配置。
查看或设置：
panda proxy system-proxy on panda proxy system-proxy off panda proxy system-proxy lock-on
注意：在 mode auto、pandavpn、wireguard 下，VPN runtime 会忽略持久化的 system proxy 偏好；VPN companion proxy 仍可用并走 scoped egress。
Q Windows 上为什么系统代理没有生效？
Windows 系统代理是当前用户 HKCU WinINET 设置，需要 per-user user-agent。
如果是在 SSH 或非交互会话里，proxy repair 不一定能自动启动 user-agent。
建议：
panda proxy status panda proxy repair panda doctor
如果仍无效，请在桌面登录会话中重试。
Q Linux 上为什么系统代理显示 unsupported？
Linux Phase 1 主要支持 GNOME gsettings。
KDE / XFCE 等环境可能显示 unsupported。
这不一定影响 PandaVPN packet runtime，但可能影响系统代理模式体验。
Q 为什么 Kill-switch 不能和 proxy mode 一起用？
Kill-switch 的语义是只允许流量经过 TUN，其它普通流量被阻断。
proxy mode 是 standalone 本地代理模式，没有 packet VPN / TUN，也没有同等 DNS 和路由保护。因此 Kill-switch 不支持 standalone proxy mode。
需要 Kill-switch 时，请使用：
panda mode auto panda kill-switch on
或：
panda mode pandavpn global panda kill-switch on
或：
panda mode wireguard panda kill-switch on
Split rules and Kill-switch
11 个解答将这些问题用于医生、修复、日志、系统代理、拆分规则、拆分 DNS 和终止开关行为。
Q Auto-connect 是断线自动重连吗？
不是。
Auto-connect 主要覆盖 daemon / service 启动时的 best-effort connect，以及启动时暂时无网络时的 pending retry。
开启：
panda config auto-connect on
关闭：
panda config auto-connect off
它不是通用的 runtime 自动重连机制。
Q Split rules 是什么？
Split rules 用于指定某些域名、关键词、正则或 IP 走 proxy、direct 或 block。
规则文件：
split/rules/proxy.txt split/rules/direct.txt split/rules/block.txt
常用命令：
panda split rules list panda split rules add proxy suffix:github.com panda split rules add direct ip-cidr:10.0.0.0/8 panda split rules add block keyword:adservice
Q 登录后会自动触发 pending auto-connect 吗？
当前已知限制：login 后不会自动 wake 待重试的 pending auto-connect。
建议登录后手动执行：
panda connect
Q Split rules 支持哪些语法？
| Pattern | 示例 | 含义 | |---|---|---| | 裸域名 | example.com | 后缀匹配 | | domain: | domain:api.example.com | 精确主机 | | suffix: | suffix:google.com | 后缀匹配 | | || | ||google.com | 后缀匹配 | | keyword: | keyword:netflix | 子串匹配 | | regexp: | regexp:.*\.cdn\.example\.com | Go 正则 | | ip-cidr: | ip-cidr:10.0.0.0/8 | IP 规则 |
Q Split DNS 改完需要 reconnect 吗？
通常不需要。Split DNS 配置变更会热加载。
常用命令：
panda split dns status panda split dns local set 223.5.5.5 114.114.114.114 panda split dns policy tunnel-only panda split dns fake-ip on
如果平台不支持某些 local DNS 来源，doctor 会给出 warning。