Tutoriais de VPS
wg-easy 15 na VPS: WireGuard, Caddy HTTPS e recuperação
Implante wg-easy 15 com Compose e Caddy. Restrinja o painel, configure confiança no proxy e chaves por dispositivo, confira rotas IPv4/IPv6/DNS e preserve estado completo para recuperação isolada e atualizações seguras.

wg-easy reúne configurações WireGuard, QR codes e administração. Você ainda precisa de painel HTTPS protegido, entrada UDP, rotas e estado recuperável. Este guia usa wg-easy 15, Docker Compose e Caddy para dispositivos pessoais ou acesso remoto pequeno com túnel IPv4.
A configuração original foi baseada na documentação oficial; não informa testes reais de vazão na VPS ou interoperabilidade dos clientes, e esta edição não apresenta esses testes como realizados agora. Confira portas/sub-redes se já usa WireGuard. Para chaves manuais, veja WireGuard básico.
Avalie 1 vCPU, 1 GB RAM e 10 GB SSD para poucos dispositivos; cerca de 2 GB ao compartilhar aplicações. Isso não garante banda nem quantidade de usuários. CPU, link compartilhado, perda e rede cliente influenciam.
Confirme WireGuard no kernel, NET_ADMIN em contêineres, UDP de entrada e transferência suficiente. KVM costuma dar mais controle; VPS contêiner restrita exige verificar permissões explicitamente.
| Endereço | Uso | Valor |
|---|---|---|
wg-admin.example.com | Administração web | Registro A para IPv4 público VPS |
vpn.example.com | Endpoint cliente | Registro A para IPv4 público VPS |
| IPv4 público do administrador | Lista de acesso | Sua saída atual, não o endereço VPS |
Use DNS direto, sem CDN/proxy adicional. Remova AAAA incorreto em implantação só IPv4. WireGuard UDP entra diretamente; Caddy trata apenas HTTPS do painel.
O exemplo fixa ghcr.io/wg-easy/wg-easy:15. 15 acompanha essa família principal; o original alerta que latest pode apontar para uma anterior. Confira a política em Getting Started, registre digests e faça backup antes de atualizar.
v15 move configurações antigas para a interface. Não copie todo WG_HOST/PASSWORD_HASH do v14. Preserve wg0.json e variáveis para o assistente de migração. Migrar não permite devolver estado atualizado ao v14.
Use shell root no Ubuntu 24.04 com Docker/Compose instalado; veja Docker:
uname -r
docker version
docker compose version
modprobe wireguard
ss -lntup
ip route
docker network ls
install -d -m 700 /opt/wg-easy
cd /opt/wg-easy
install -d -m 700 wireguard caddy-data caddy-config backups
Confira TCP 80/443 e UDP 51820. 10.42.42.0/24 não pode sobrepor Docker, casa ou empresa. Use docker network inspect e altere sub-rede/IPs fixos juntos. Confira também a sub-rede dos clientes escolhida na inicialização.
Salve /opt/wg-easy/compose.yaml:
name: wg-easy
services:
wg-easy:
image: ghcr.io/wg-easy/wg-easy:15
environment:
INSECURE: "false"
DISABLE_IPV6: "true"
volumes:
- ./wireguard:/etc/wireguard
- /lib/modules:/lib/modules:ro
ports:
- "51820:51820/udp"
cap_add:
- NET_ADMIN
- SYS_MODULE
sysctls:
net.ipv4.ip_forward: "1"
net.ipv4.conf.all.src_valid_mark: "1"
networks:
wg:
ipv4_address: 10.42.42.42
restart: unless-stopped
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"
caddy:
image: caddy:2-alpine
ports:
- "80:80/tcp"
- "443:443/tcp"
volumes:
- ./Caddyfile:/etc/caddy/Caddyfile:ro
- ./caddy-data:/data
- ./caddy-config:/config
networks:
- wg
restart: unless-stopped
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"
networks:
wg:
driver: bridge
ipam:
config:
- subnet: 10.42.42.0/24
Adapta o Compose oficial para IPv4, remove 51821 do host e preserva estado em diretórios. NET_ADMIN e SYS_MODULE são permissões poderosas: use imagens confiáveis e proteja o host; não adicione privileged: true. Se o host fornece o módulo e a configuração suportada permite, evite carregar módulos pelo contêiner.
A documentação atual define TRUSTED_PROXIES para metadados originais atrás do proxy. Fixe o IP do Caddy e confie somente nele antes de iniciar. Modifique as seções correspondentes preservando os demais ajustes; este fragmento não substitui todo o arquivo:
services:
wg-easy:
environment:
TRUSTED_PROXIES: "10.42.42.43"
caddy:
networks:
wg:
ipv4_address: 10.42.42.43
Se mudar a sub-rede, atualize os dois IPs e a confiança. Recrie os contêineres depois de alterar redes/variáveis.
DISABLE_IPV6=true desativa IPv6 do túnel/clientes conforme opções, mas não desativa o IPv6 original do dispositivo.
Crie /opt/wg-easy/Caddyfile, substituindo domínio e 198.51.100.25/32 pelo seu IPv4 público real:
wg-admin.example.com {
@outside not remote_ip 198.51.100.25/32
respond @outside "Forbidden" 403
reverse_proxy wg-easy:51821
}
O endereço documental não funciona sem substituição. Mantenha a restrição na inicialização e administração quando apropriado; atualize por SSH independente ao trocar de rede. Ela restringe HTTP, não UDP. Com outro proxy, remote_ip identifica outro peer: confira matchers Caddy sem confiar em headers arbitrários.
Permita TCP 80/443 e UDP 51820 no host/provedor, mantendo SSH. Não abra TCP 51821 nem use regra de 51820 apenas TCP. Verifique o firewall real do Docker; UFW sozinho não comprova proteção.
Com DNS correto:
cd /opt/wg-easy
docker compose config --quiet
docker compose pull
docker compose run --rm --no-deps caddy \
caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
docker compose up -d
docker compose ps
docker compose logs --tail=100 caddy
docker compose logs --tail=100 wg-easy
Abra https://wg-admin.example.com do computador permitido. HTTPS automático obtém/renova certificado público; tls internal é para confiança interna. Veja exemplo Caddy.
Mantenha INSECURE=false e HTTPS; não exponha administração em texto claro para contornar erros. Se já houver proxy em 80/443, integre nele, sem iniciar outro em conflito. Veja Caddy.
Crie administrador com senha longa única; instalação nova sem configuração antiga. Host vpn.example.com, Port 51820: endpoint real, sem https:// ou IP interno Docker. Veja campos iniciais.
Ative TOTP em Account, verifique o código e preserve as informações de recuperação documentadas. Veja 2FA. Protege login do painel, não cada handshake.
Crie um peer por dispositivo, como phone-main e laptop-work. Use cliente oficial para QR no celular ou arquivo no computador. Eles contêm chaves privadas: não publique em chamados/capturas. Desative/exclua dispositivo perdido, sem compartilhar configuração entre aparelhos.
Confira handshakes:
cd /opt/wg-easy
docker compose exec wg-easy wg show
Verifique handshake recente, bytes e acesso ao serviço previsto. Painel funcionando comprova HTTPS, não UDP. Teste Wi-Fi e rede móvel quando relevante.
Para um serviço controlado, roteie somente IP/sub-rede necessária. 0.0.0.0/0 envia todo IPv4 pela VPS. Destinos ainda exigem rota do servidor, forwarding e retorno; AllowedIPs não cria esses caminhos.
AllowedIPs não autoriza acesso servidor: o cliente pode alterá-lo. Use firewall por cliente suportado ou regras equivalentes; veja ajustes cliente e teste acesso permitido e negado.
Aqui não existe saída IPv6 pelo túnel. IPv6 nativo pode sair pela rede original. Para túnel completo, confira rotas IPv4/IPv6/DNS e bloqueio externo suportado ou desenho dual-stack. Adicionar ::/0 não cria conectividade IPv6.
Use DNS alcançável. DNS interno precisa de rota e permissão no firewall. Diferencie IP inacessível de resolução falhando antes de alterar MTU.
/etc/wireguard contém mais que configuração manual WireGuard. Preserve diretório completo, Compose, Caddy e imagens. O arquivo consistente interrompe os túneis: use SSH independente desta VPN e preserve console do provedor.
Salve /opt/wg-easy/backup.sh:
#!/usr/bin/env bash
set -euo pipefail
umask 077
cd /opt/wg-easy
backup_file="backups/wg-easy-$(date -u +%Y%m%dT%H%M%SZ).tar.gz"
test ! -e "$backup_file"
test ! -e "${backup_file}.partial"
{
for service in wg-easy caddy; do
image_id=$(docker compose images -q "$service")
test -n "$image_id"
printf '%s\n' "$service"
docker image inspect "$image_id" --format '{{json .RepoDigests}}'
done
} > image-digests.txt
trap 'docker compose up -d' EXIT
docker compose down
tar -czf "${backup_file}.partial" \
compose.yaml Caddyfile image-digests.txt wireguard caddy-data caddy-config
tar -tzf "${backup_file}.partial" > /dev/null
mv "${backup_file}.partial" "$backup_file"
sha256sum "$backup_file" > "${backup_file}.sha256"
docker compose up -d
trap - EXIT
printf 'Backup ready: %s\n' "$backup_file"
chmod 700 /opt/wg-easy/backup.sh
/opt/wg-easy/backup.sh
docker compose ps
Usa down/up, não down -v. O trap tenta reiniciar depois de falha; confira contêineres e um handshake. Arquivo legível não prova recuperação funcional. Verifique RepoDigests válidos e disponíveis; imagem local sem digest precisa de artefato/identidade preservado separadamente.
Criptografe chaves, contas e certificados, copie para fora da VPS e preserve credenciais de descriptografia separadas. Inclua adições/exclusões e rotas no plano. Restaurar estado antigo pode reativar peers revogados: reaplique revogações antes de expor o serviço.
Na VPS limpa, instale Docker equivalente. Coloque arquivo confiável e .sha256 em /root/wg-restore/backups/, preservando nomes/estrutura. Substitua datas de exemplo:
cd /root/wg-restore
backup_file='backups/wg-easy-YYYYMMDDTHHMMSSZ.tar.gz'
sha256sum -c "${backup_file}.sha256"
tar -tzf "$backup_file"
restore_dir=$(mktemp -d /opt/wg-easy-restore.XXXXXX)
tar -xzf "$backup_file" -C "$restore_dir"
cd "$restore_dir"
docker compose config --quiet
A descrição original backups/文件名 significa backups/
Fixe ambas as imagens aos digests de image-digests.txt, confira portas/redes e inicie. Na substituição real, atualize DNS e lista do administrador. Endpoint alterado pode exigir modificar configuração ou reconectar para resolver o domínio novamente.
docker compose up -d
docker compose logs --tail=100 wg-easy
docker compose exec wg-easy wg show
Use VPS isolada, domínio de teste e peers temporários. Confira login, lista, handshake e serviços; não deixe teste/produção atender os mesmos peers simultaneamente. Veja ensaio de recuperação.
Antes de atualizar, faça backup restaurável e preserve digests antigos. Revise a versão destino, baixe/recrie em manutenção e altere digests fixados explicitamente. Rollback pode exigir imagem antiga e estado anterior, pois versões antigas podem não ler dados migrados.
Confira allowlist Caddy: túnel completo pode mudar o IP público do navegador. Atualize/recarregue por SSH independente, sem permitir todas as origens.
Confira DNS Endpoint, UDP, regras e logs. Compare outra rede controlada se houver bloqueio UDP. Teste TCP não comprova UDP 51820.
Confira rotas, forwarding, NAT, endereço do serviço e DNS. Execute docker compose exec wg-easy ip route dentro do contêiner; o host pode não ter wg0. Ajuste MTU quando houver evidência e teste novamente.
Quando necessário, avalie Persistent Keepalive de 25 segundos conforme Quick Start. Adiciona tráfego periódico e não é obrigatório para todos.
Não: cada peer usa suas chaves. Desative/exclua o dispositivo e confirme que não acessa mais. Complete configuração, handshake, serviço, revogação e teste de restauração com um aparelho antes de adicionar os demais.