DocsOperaciónTroubleshooting
Troubleshooting
Los errores de arranque nombran la variable exacta que hay que corregir. Los casos comunes, qué significan y cómo desatascarse.
Primera parada: los logs
$ docker compose logs -f vuzonvuzon se niega a arrancar con una configuración claramente insegura en vez de levantarse en un estado roto, y cada error de arranque nombra la variable que hay que corregir.
Casos comunes
| Síntoma | Causa | Solución |
|---|---|---|
| El contenedor termina justo tras arrancar | DOMAIN o CF_API_TOKEN vacíos, o todavía con un valor de plantilla |
Rellena ambos en .env y docker compose up -d de nuevo. |
| El error de arranque pide los IDs de zona/cuenta | La autodetección desde DOMAIN falló, o dos zonas comparten nombre |
Añade CF_ZONE_ID y CF_ACCOUNT_ID a .env. |
| «data directory not writable» | El volumen/ruta de datos no se puede escribir | Revisa el montaje del volumen vuzon-data, o VUZON_DATA_DIR si lo cambiaste. |
| Bloqueado tras varios logins fallidos | El login está limitado a 10 intentos / 15 min | Espera a que pase la ventana. Detrás de un proxy, define TRUST_PROXY para que el límite siga IPs reales. |
| El panel responde 502 en acciones de Cloudflare | Error upstream de Cloudflare — los 401/403 se normalizan a 502 a propósito | Revisa los tres permisos del token y sus restricciones de zona/cuenta. El error detallado de Cloudflare está en el log del servidor, nunca en el navegador. |
| El asistente de instalación reapareció | El volumen vuzon-data se perdió o se reemplazó |
Restáuralo desde una copia — ver Backups. |
| Un destino se niega a eliminarse | Un alias o el catch-all sigue reenviando ahí — la respuesta los nombra | Reapunta o borra esas reglas primero — ver Direcciones de destino. |
| «No se pudo verificar si este destino sigue en uso» | La revisión de uso no pudo llegar a Cloudflare; vuzon nunca borra a ciegas | Reinténtalo cuando Cloudflare vuelva a responder. No se borró nada. |
| Se cerró la sesión sin tocar nada | Las sesiones caducan a los 7 días (comprobado en el servidor), o un cambio de usuario/contraseña en otra sesión revocó las demás | Vuelve a iniciar sesión — ver Configuración inicial. |
El texto de error de Cloudflare se registra en el servidor y nunca se devuelve al navegador, así que la respuesta de verdad vive en el log.
¿Sigues atascado?
Abre una issue en GitHub. ¿Has encontrado un problema de seguridad? No abras una issue pública — ver Seguridad para reportarlo en privado.