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

terminal

$ docker compose logs -f vuzon

vuzon 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.

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 — repórtalo en privado vía GitHub Security Advisories.