Solución de problemas

El agente no arranca

Síntoma: el contenedor se detiene inmediatamente o entra en bucle de reinicios.

Comprueba los logs:

docker compose logs nubulus-tunnel

Causas más comunes:

Error en los logs	Causa	Solución
`TUNNEL_TOKEN is required`	Falta la variable de entorno	Añade `TUNNEL_TOKEN` al `docker-compose.yml`
`API error: status 401`	Token incorrecto o expirado	Genera un nuevo token en el panel
`API error: status 403`	El túnel está suspendido o eliminado	Verifica el estado en el panel
`no se pudo iniciar WireGuard`	Error de conectividad	Verifica acceso saliente UDP al puerto 51820

El túnel arranca pero no llegan peticiones

Síntoma: el agente muestra túnel conectado pero las peticiones al dominio no llegan.

Comprueba:

Que el dominio tiene un CNAME apuntando a la dirección que indica el panel de Nubulus.
Que las rutas están configuradas en el panel y tienen el hostname correcto.
Que el agente recibe tráfico (verifica rx en los logs de estadísticas):

docker compose logs nubulus-tunnel | grep "transfer stats"

Si rx es 0 después de varios minutos, el tráfico no está llegando al túnel. Revisa la configuración DNS de tu dominio.

Respuesta 502 Bad Gateway

Síntoma: el navegador muestra un error 502.

Comprueba los logs del agente en busca de:

"upstream connection failed"

Si aparece ese error, el agente sí recibe la petición pero no puede alcanzar tu servicio. Causas habituales:

El servicio no está en la misma red Docker que el agente. Añade ambos a la misma red en docker-compose.yml.
El nombre del upstream no coincide. El nombre en la ruta del panel debe ser exactamente el nombre del servicio en Docker Compose (sensible a mayúsculas y guiones).
El puerto es incorrecto. Verifica en qué puerto escucha tu servicio.

Si aparece "no matching route" en cambio, el hostname que envía el navegador no coincide con el configurado en las rutas del panel:

"no matching route" host="lo-que-llega" path="/"

Verifica que el hostname en la ruta del panel coincide exactamente con el dominio que estás usando.

Las rutas no se actualizan

Síntoma: cambias las rutas en el panel pero el agente sigue usando las anteriores.

El agente comprueba cambios cada 30 segundos por defecto. Espera un momento y vuelve a intentarlo.

Si tras un minuto siguen sin aplicarse, revisa los logs:

docker compose logs -f nubulus-tunnel | grep "poll\|rutas"

Si ves errores de conexión en el poll, puede haber un problema de acceso a la API de Nubulus desde tu servidor.

Cómo leer los logs

Los logs del agente son JSON estructurado. Puedes filtrarlos con jq:

# Solo errores y warnings
docker compose logs nubulus-tunnel | grep '"level":"error"\|"level":"warn"'

# Ver todas las peticiones proxiadas
docker compose logs nubulus-tunnel | grep '"message":"proxying request"'

# Ver estadísticas de transferencia
docker compose logs nubulus-tunnel | grep "transfer stats"

Para activar logs más detallados temporalmente:

docker compose stop nubulus-tunnel
LOG_LEVEL=debug docker compose up nubulus-tunnel