Tutoriales de VPS
wg-easy 15 en una VPS: WireGuard, Caddy HTTPS y recuperación
Despliegue wg-easy 15 con Compose y Caddy. Restrinja el panel, configure confianza del proxy y claves por dispositivo, compruebe rutas IPv4/IPv6/DNS y copie el estado completo para recuperación aislada y actualizaciones seguras.

wg-easy reúne configuración de dispositivos WireGuard, códigos QR y administración. Aun así necesita un panel HTTPS protegido, entrada UDP, rutas y estado recuperable. Esta guía usa wg-easy 15, Docker Compose y Caddy para dispositivos personales o acceso remoto pequeño con túnel IPv4.
La configuración original procede de documentación oficial; no informa pruebas reales de rendimiento VPS o interoperabilidad de clientes, y esta edición no las presenta como nuevas pruebas. Revise puertos y subredes si ya usa WireGuard. Para claves manuales, consulte WireGuard básico.
Evalúe 1 vCPU, 1 GB RAM y 10 GB SSD para pocos dispositivos; aproximadamente 2 GB si comparte aplicaciones. No garantiza ancho de banda ni usuarios. CPU, enlace compartido, pérdida y red del cliente influyen.
Compruebe soporte WireGuard del kernel, NET_ADMIN en contenedores, UDP entrante y transferencia suficiente. KVM suele dar más control; una VPS contenedorizada restringida necesita comprobar permisos explícitamente.
| Dirección | Uso | Valor |
|---|---|---|
wg-admin.example.com | Administración web | Registro A a IPv4 público VPS |
vpn.example.com | Endpoint cliente | Registro A a IPv4 público VPS |
| IPv4 público del administrador | Lista de acceso | Su salida actual, no la dirección VPS |
Use DNS directo, sin CDN/proxy adicional. Retire AAAA incorrectos en IPv4 solamente. WireGuard UDP llega directamente; Caddy gestiona únicamente HTTPS del panel.
El ejemplo fija ghcr.io/wg-easy/wg-easy:15. 15 sigue esa familia principal; el original advierte que latest puede referirse a otra anterior. Revise política actual en Getting Started, registre digests y copie antes de actualizar.
v15 mueve ajustes antiguos a la interfaz. No copie todo WG_HOST/PASSWORD_HASH de v14. Conserve wg0.json y las variables para el asistente de migración. Migrar no permite usar el estado actualizado nuevamente en v14.
Use shell root en Ubuntu 24.04 con Docker/Compose instalado; véase 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
Revise TCP 80/443 y UDP 51820. 10.42.42.0/24 no debe solaparse con Docker, casa o empresa. Use docker network inspect y cambie subred/IP fijas conjuntamente. Revise también la subred cliente elegida al inicializar.
Guarde /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 Compose oficial a IPv4, elimina 51821 del host y conserva estado en directorios. NET_ADMIN y SYS_MODULE son permisos potentes: use imágenes confiables y proteja el host; no añada privileged: true. Si el host aporta el módulo y la configuración soportada lo permite, evite cargar módulos desde el contenedor.
La documentación actual define TRUSTED_PROXIES para metadatos originales detrás del proxy. Fije IP de Caddy y confíe solo en ella antes de iniciar. Modifique estas secciones manteniendo los demás ajustes; el fragmento no sustituye todo el archivo:
services:
wg-easy:
environment:
TRUSTED_PROXIES: "10.42.42.43"
caddy:
networks:
wg:
ipv4_address: 10.42.42.43
Si cambia la subred, actualice ambas IP y confianza. Recree contenedores al cambiar redes/variables.
DISABLE_IPV6=true desactiva IPv6 del túnel/clientes según opciones, pero no el IPv6 original del dispositivo.
Cree /opt/wg-easy/Caddyfile, sustituyendo dominio y 198.51.100.25/32 por su 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
}
La dirección documental no sirve sin cambiar. Mantenga restricción para inicializar y administrar si corresponde; actualícela por SSH independiente cuando cambie de red. Restringe HTTP, no UDP. Con otro proxy, remote_ip identifica otro peer: revise matchers Caddy sin confiar en cabeceras arbitrarias.
Permita TCP 80/443 y UDP 51820 en host/proveedor, conservando SSH. No abra TCP 51821 ni use 51820 solo TCP. Compruebe firewall real de Docker; UFW por sí solo no prueba protección.
Con DNS correcto:
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 desde el equipo permitido. HTTPS automático obtiene/renueva certificado público; tls internal corresponde a confianza interna. Véase ejemplo Caddy.
Mantenga INSECURE=false y HTTPS; no publique administración en claro para sortear errores. Si ya hay proxy en 80/443, integre el sitio allí, sin iniciar otro en conflicto. Consulte Caddy.
Cree administrador con contraseña larga única; instalación nueva sin configuración antigua. Host vpn.example.com, Port 51820: dirección real del Endpoint, sin https:// ni IP Docker. Véase campos iniciales.
Active TOTP en Account, verifique código y guarde información de recuperación documentada. Consulte 2FA. Protege login del panel, no cada handshake.
Cree peer por dispositivo, como phone-main y laptop-work. Use cliente oficial para QR móvil o archivo escritorio. Contienen claves privadas; no comparta en tickets/capturas públicos. Desactive/elimine un dispositivo perdido, sin reutilizar configuración entre equipos.
Compruebe handshakes:
cd /opt/wg-easy
docker compose exec wg-easy wg show
Verifique handshake reciente, bytes y acceso al servicio previsto desde el cliente. Panel correcto prueba HTTPS, no UDP. Pruebe Wi-Fi y red móvil cuando corresponda.
Para un servicio controlado, enrute solo IP/subred necesaria. 0.0.0.0/0 envía todo IPv4 por VPS. Destinos necesitan ruta del servidor, forwarding y retorno; AllowedIPs no los crea.
AllowedIPs no autoriza acceso servidor: el cliente puede modificarlo. Use firewall por cliente soportado o reglas equivalentes, revise ajustes cliente y pruebe accesos permitidos y rechazados.
Aquí no hay salida IPv6 del túnel. IPv6 nativo puede salir por la red original. Para túnel completo, compruebe rutas IPv4/IPv6/DNS y bloqueo externo soportado o diseño dual-stack. Añadir ::/0 no crea conectividad IPv6.
Use DNS alcanzable. DNS interno necesita rutas y permiso de firewall. Distinga IP inaccesible de resolución fallida antes de cambiar MTU.
/etc/wireguard contiene más que configuración manual WireGuard. Preserve directorio completo, Compose, Caddy e imágenes. El archivo consistente detiene túneles: utilice SSH ajeno a esta VPN y conserve consola del proveedor.
Guarde /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, no down -v. El trap intenta arrancar tras error, pero revise contenedores y un handshake. Un archivo legible no demuestra recuperación funcional. Confirme RepoDigests válidos y disponibles; una imagen local sin digest necesita preservar artefacto/identidad aparte.
Cifre claves, cuentas y certificados, copie fuera de VPS y guarde credenciales de descifrado separadas. Incluya altas/bajas y rutas en el plan. Restaurar estado antiguo puede reactivar peers revocados: aplique revocaciones antes de exponerlo.
En VPS limpia, instale Docker equivalente. Coloque archivo confiable y .sha256 en /root/wg-restore/backups/, conservando nombres/estructura. Cambie fechas de ejemplo:
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
La etiqueta original backups/文件名 significa backups/
Fije ambas imágenes a digests de image-digests.txt, revise puertos/redes y arranque. Para reemplazo real, actualice DNS y lista de administrador. Endpoint cambiado puede requerir modificar configuración o reconectar para resolver DNS otra vez.
docker compose up -d
docker compose logs --tail=100 wg-easy
docker compose exec wg-easy wg show
Use VPS aislada, dominio de prueba y peers temporales. Compruebe login, lista, handshake y servicios; no deje que prueba y producción atiendan los mismos peers a la vez. Véase ensayo de recuperación.
Antes de actualizar, copie de forma recuperable y conserve digests anteriores. Revise versión destino, descargue/recree en mantenimiento y cambie digests fijados explícitamente. Revertir puede necesitar imagen anterior y estado previo, porque versiones viejas no siempre leen datos migrados.
Revise allowlist Caddy: túnel completo puede cambiar IP pública del navegador. Actualice/recargue por SSH independiente, sin permitir todas las fuentes.
Revise DNS Endpoint, UDP, reglas y logs. Compare otra red controlada si bloquean UDP. Una prueba TCP no confirma UDP 51820.
Revise rutas, forwarding, NAT, enlace del servicio y DNS. Ejecute docker compose exec wg-easy ip route dentro del contenedor; el host puede no tener wg0. Ajuste MTU cuando haya evidencia y vuelva a probar.
Si lo necesita, evalúe Persistent Keepalive de 25 segundos según Quick Start. Añade tráfico periódico; no es obligatorio para todos.
No: cada peer usa sus claves. Desactive/elimine el dispositivo y confirme que ya no accede. Complete configuración, handshake, servicio, revocación y prueba de restauración con un dispositivo antes de añadir el resto.