Perguntas frequentes sobre PandaVPN CLI

Panda CLI é o cliente de linha de comandos da Panda e permite realizar o seguinte através do terminal:

• Início de sessão e gestão da conta
• Atualização de nós e ligação a nós
• Alternância entre os modos PandaVPN / Proxy / WireGuard / Auto
• Configuração do proxy do sistema
• Regras Split rules para divisão de tráfego
• Configuração de Split DNS
• Proteção Kill-switch
• Auto-connect
• Registos e diagnósticos

É adequado para utilizadores de testes internos, programadores, utilizadores avançados e cenários de teste que exigem operações por script.

Panda CLI é operado através da linha de comandos e é mais adequado para:

• Testes automatizados
• Resolução remota de problemas
• Ligações por script
• Visualização de informações de diagnóstico detalhadas
• Validação de comportamentos de baixo nível, como Kill-switch, DNS, encaminhamento e proxy do sistema

O cliente de desktop é mais adequado para operações gráficas diárias de utilizadores comuns.

Nota: não é recomendado que o antigo cliente de desktop Qt e CLI façam a gestão de VPN / proxy do sistema ao mesmo tempo, para evitar que substituam mutuamente a configuração.

Algumas capacidades exigem permissões ao nível do sistema, por exemplo:

• Criar interfaces de rede TUN / WireGuard
• Modificar o DNS
• Configurar o proxy do sistema
• Aplicar o Kill-switch
• Reparar rotas
• Gerir o packet VPN runtime

Por isso, a CLI executa estas operações através do daemon / service correspondente à plataforma.

Formas de daemon nas diferentes plataformas:

A principal diferença é: no Windows e no macOS, o serviço é normalmente instalado automaticamente através do pacote de instalação, enquanto no Linux o utilizador normalmente tem de executar manualmente sudo panda service install.

No Windows, só se não utilizar o pacote de instalação e colocar manualmente o binário é que precisa de executar o seguinte no PowerShell como administrador:

panda service install windows

No macOS, isto só é necessário durante desenvolvimento e depuração, quando não se utiliza o pacote de instalação .pkg, ou quando o daemon não arranca automaticamente:

sudo panda start

No Linux, recomenda-se:

sudo panda service install
panda service status

Sim, são os mesmos. A principal diferença está na arquitetura do pacote de instalação descarregado.

Os passos de instalação, os comandos e a forma de gestão do serviço são os mesmos. O instalador elevará automaticamente os privilégios e registará o Windows Service.

Suporta principalmente:

Definições comuns:

panda mode auto
panda mode pandavpn global
panda mode proxy global
panda mode wireguard

Atualmente, não é recomendado apresentar openvpn como modo principal na documentação do utilizador.

Recomendação:

Nota: mode proxy e Kill-switch são mutuamente exclusivos.

mode auto é o modo predefinido da nova versão.

O seu comportamento é:

• API node / smart connect escolhe o runtime com prioridade com base em meta.protocol;
• Se WireGuard for recomendado, o WireGuard será tentado primeiro;
• Se os metadados do WireGuard, a atribuição de endereço, o arranque do runtime, o handshake ou a verificação de conectividade falharem, regressa ao PandaVPN global compilado a partir do SS payload;
• SS, OPENVPN e protocolos desconhecidos ou em falta usarão PandaVPN global como fallback;
• mode auto não aceita o parâmetro policy, e o runtime resolvido é sempre global.

Recomendado para novos utilizadores:

panda mode auto
panda connect

direct-region é a sintaxe recomendada; bypass-region / bypass são aliases de compatibilidade.

Por exemplo:

panda mode pandavpn direct-region in

Equivale ao alias de compatibilidade:

panda mode pandavpn bypass-region in

A nova versão suporta uma sintaxe de split profile mais completa:

panda mode pandavpn split default direct proxy-region <cc>
panda mode pandavpn split default proxy direct-region <cc>

Tokens comuns:

Exemplos:

panda mode pandavpn split default direct proxy-region us custom-rules
panda mode pandavpn split default proxy direct-region in direct-lan custom-rules

Não é recomendado apresentar comandos longos na documentação para principiantes; são mais adequados para documentação avançada de split.

doctor é um comando de diagnóstico só de leitura usado para ver os principais estados atuais do Panda CLI.

panda doctor
panda doctor --json

Forma curta:

panda do

Preste especial atenção a:

runtime
kill_switch
selected_node
vpn_dns
dns_lockdown
split_policy
system_proxy_state
vpn_routes
last_error

trace é usado para ver que regra, DNS action e route um destino irá usar.

panda trace example.com:443
panda trace 8.8.8.8:53 --json

Nota: a capacidade completa de trace exige active PandaVPN packet runtime. Sem um runtime compatível, só é possível fazer validação limitada ou fallback para legacy trace.

Isto geralmente acontece porque o service / LaunchDaemon oficial está instalado e também foi executado manualmente:

sudo panda start

sudo panda start inicia um daemon unmanaged / não gerido, que pode gerir ao mesmo tempo que o daemon oficial:

• VPN route
• DNS
• TUN
• system proxy
• Kill-switch

O princípio de tratamento é: manter apenas um daemon.

Tratamento comum em macOS / Linux:

panda disconnect
panda kill-switch off
sudo panda stop
panda repair
panda doctor

No Linux, se usar systemd service, reinicie depois o serviço oficial:

sudo panda service restart
panda doctor

No macOS, se a instalação foi feita com .pkg, normalmente deixe o LaunchDaemon / helper gerir o daemon e não use sudo panda start a longo prazo como método diário de arranque.

Se apenas quiser desligar a VPN, não precisa de sair do daemon:

panda disconnect
panda kill-switch off

Se realmente quiser parar o daemon:

sudo panda stop

Confirmar:

panda status

Se aparecer panda daemon unavailable, significa que o daemon principal foi parado.

Nota: o LaunchDaemon / helper instalado pelo macOS .pkg pode ser gerido pelo sistema; não se recomenda que utilizadores comuns parem manualmente o serviço com frequência.

panda log
panda log --lines 200
panda log --all

Limpar logs:

panda log clear

Ativar debug temporariamente:

panda log level debug dns,tcp --ttl 10m

Restaurar predefinição:

panda log level reset

panda repair é mais abrangente e pode reparar:

• VPN route
• DNS snapshot
• Kill-switch guard
• estado relacionado com system proxy

panda proxy repair repara principalmente o system proxy drift do utilizador atual.

panda repair
panda proxy repair

Numa Fresh install, o padrão é proxy system-proxy on.
Se o utilizador guardou explicitamente off, essa configuração será preservada.

Ver ou configurar:

panda proxy system-proxy on
panda proxy system-proxy off
panda proxy system-proxy lock-on

Nota: em mode auto, pandavpn e wireguard, o VPN runtime ignora a preferência persistida de system proxy; o VPN companion proxy continua disponível e usa scoped egress.

O Windows system proxy é uma configuração HKCU WinINET do utilizador atual e requer um per-user user-agent.
Se estiver numa sessão SSH ou não interativa, proxy repair poderá nem sempre conseguir iniciar automaticamente o user-agent.

Recomendado:

panda proxy status
panda proxy repair
panda doctor

Se continuar sem efeito, tente novamente numa sessão de início de sessão no ambiente de trabalho.

Linux Phase 1 suporta principalmente GNOME gsettings.
Ambientes como KDE / XFCE podem aparecer como unsupported.

Isto não afeta necessariamente o PandaVPN packet runtime, mas pode afetar a experiência do system proxy mode.

O significado de Kill-switch é permitir tráfego apenas através do TUN, enquanto outro tráfego normal é bloqueado.

proxy mode é um modo de proxy local standalone, sem packet VPN / TUN e sem proteção equivalente de DNS e encaminhamento. Por isso, Kill-switch não suporta standalone proxy mode.

Quando precisar de Kill-switch, use:

panda mode auto
panda kill-switch on

Ou:

panda mode pandavpn global
panda kill-switch on

Ou:

panda mode wireguard
panda kill-switch on

Não.

Auto-connect cobre principalmente o best-effort connect quando o daemon / service arranca, além do pending retry quando a rede fica temporariamente indisponível no arranque.

Ativar:

panda config auto-connect on

Desativar:

panda config auto-connect off

Não é um mecanismo geral de religação automática em runtime.

As Split rules são usadas para especificar que certos domínios, palavras-chave, regex ou IPs passem por proxy, direct ou block.

Ficheiros de regras:

split/rules/proxy.txt
split/rules/direct.txt
split/rules/block.txt

Comandos comuns:

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

Limitação conhecida atual: após iniciar sessão, o pending auto-connect a aguardar retry não será acordado automaticamente.

Após iniciar sessão, recomenda-se executar manualmente:

panda connect

Normalmente não. As alterações de configuração do Split DNS são carregadas por hot-load.

Comandos comuns:

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

Se a plataforma não suportar certas fontes de local DNS, doctor mostrará um warning.