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 / 節點 metadata 推薦 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 metadata、位址分配、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- 含義
- 後綴匹配
- Pattern
domain:- 範例
domain:api.example.com- 含義
- 精確主機
- Pattern
suffix:- 範例
suffix:google.com- 含義
- 後綴匹配
- Pattern
- 範例
- 含義
- google.com
- 後綴匹配
- Pattern
keyword:- 範例
keyword:netflix- 含義
- 子字串匹配
- Pattern
regexp:- 範例
regexp:.*\.cdn\.example\.com- 含義
- Go 正則
- Pattern
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。