Solución de problemas

Problemas habituales, qué los causa y cómo resolverlos. Casi siempre se empieza por el mismo sitio: los Logs del servicio, que tienen la salida de la compilación y la de la propia aplicación (Registros).

Servidores

La configuración no logra conectar

• Conexión agotada o rechazada: el puerto SSH está cerrado en el cortafuegos o grupo de seguridad del proveedor, o la dirección o el puerto son incorrectos. Permite el puerto SSH desde cualquier origen mientras dura la configuración; después puedes cerrarlo (Requisitos).
• Falla la autenticación: revisa el usuario SSH. Las imágenes en la nube suelen desactivar el acceso como root; usa ubuntu, debian o ec2-user. La clave debe ser la privada, no el archivo .pub, y sin frase de contraseña (Añadir un servidor).
• sudo pide contraseña: el usuario necesita sudo sin contraseña, o conéctate como root.
• La clave del host ha cambiado: Zenavo se niega a conectar cuando la huella del servidor no coincide con la de la primera configuración. Si reinstalaste la máquina a propósito, quita el servidor y vuelve a añadirlo; si no, averigua el motivo antes de seguir.

La configuración falla durante la instalación

Lee las últimas líneas del registro de configuración en la pestaña Status del servidor. Causas habituales:

• Los puertos 80 o 443 están ocupados por Docker, Nginx, Apache u otro servidor web. El servidor debería dedicarse a Zenavo; detenlos y desactívalos, y luego pulsa Retry setup.
• Falta memoria o disco: al menos 2 GB de memoria y 20 GB de disco libre (Requisitos).
• Las descargas se agotan en China continental: el registro muestra qué fuentes eligió la configuración (Servidores en China continental).
• El agente nunca conecta: el servidor necesita HTTPS saliente (puerto 443) hacia la consola de Zenavo.

Al reintentar se saltan los pasos que ya terminaron.

Un servidor aparece como Offline

Zenavo lleva unos minutos sin noticias del agente del servidor. Los proyectos siguen funcionando; solo se pausan los despliegues y los datos en vivo. Comprueba que la máquina esté encendida, que tenga HTTPS saliente y que no se haya quedado sin memoria ni disco. Cuando el agente vuelve, el estado regresa solo a Running. Si no, Settings → Run setup reinstala el agente sin tocar lo que se ejecuta (Gestionar un servidor).

Compilaciones

Zenavo detectó otro lenguaje o ningún plan

zbpack mira los archivos del directorio raíz. En un monorepo, pon el Root directory en la carpeta de la aplicación. Añade un Dockerfile para controlar la compilación por completo, o define zbpack options como ZBPACK_BUILD_COMMAND y ZBPACK_START_COMMAND (Plan de compilación).

La compilación falla

Abre Logs → Build Logs. El último error suele ser la causa: una dependencia que falta, un script de compilación que falla o un valor que la compilación necesita. Las variables de la pestaña Variables no llegan solas a la compilación: referencia las que necesite como argumentos de compilación. Prueba la misma compilación en local con docker build . para distinguir un problema de la aplicación de uno de la plataforma.

La compilación espera o se detiene

• Esperando una máquina de compilación: ya usas todas las compilaciones simultáneas de tu plan, o las máquinas compartidas están ocupadas (Cola de compilación).
• Tiempo agotado: las compilaciones se detienen al superar la duración máxima de tu plan (Uso y facturación).
• Rechazada: el espacio de trabajo ha gastado sus minutos de compilación del mes. Desplegar imágenes ya compiladas sigue funcionando.

Despliegues

El despliegue nunca está sano

La nueva instancia arrancó pero nunca superó su comprobación de salud; la instancia anterior sigue atendiendo. Normalmente:

• La aplicación escucha en localhost o en un puerto fijo. Escucha en 0.0.0.0 y en la variable PORT (Frameworks).
• El puerto no es el correcto. El puerto del servicio en Networking debe ser el que escucha la aplicación.
• La ruta de la comprobación devuelve 404, o la aplicación tarda más en arrancar. Corrige la ruta o aumenta el periodo de arranque.

El despliegue fallido muestra el motivo de la última comprobación y los registros más recientes de la instancia.

El servicio se cae una y otra vez o fue suspendido

El contenedor sale justo después de arrancar. Busca el error en Logs: una variable que falta, una base de datos inalcanzable o un fallo al arrancar. Un servicio que se detiene por usar demasiada memoria también se reinicia: sube su límite de memoria (Ajustes del servicio). Tras el número de reinicios fijado como límite de fallos, Zenavo suspende el servicio; corrige la causa y luego reanúdalo o vuelve a desplegar.

Los despliegues se rechazan por la transferencia de imágenes

El espacio de trabajo alcanzó su límite de gasto o agotó la transferencia de imágenes que incluye el plan Free. Los servicios en marcha siguen funcionando. Sube el límite o mejora el plan (Transferencia de imágenes y límite de gasto).

Un servicio no llega a otro

Usa el nombre de host privado del otro servicio, <hostname>.zenavo.internal, y el puerto en el que escucha, no su dominio público ni localhost. Ambos servicios deben estar en el mismo proyecto. La pestaña Networking del otro servicio muestra la dirección en Private (Red privada).

Dominios y HTTPS

El certificado sigue en Pending

Let's Encrypt aún no ha podido verificar el dominio. Pasa el ratón sobre Pending en el Overview del servicio para ver el motivo. Normalmente:

• El registro DNS todavía no apunta al servidor. Compruébalo con dig +short app.example.com; debería mostrar la IP del servidor. Los registros nuevos pueden tardar en propagarse.
• El puerto 80 está cerrado. Let's Encrypt verifica el dominio por HTTP.
• El proxy de Cloudflare está activado con SSL en Flexible. Ponlo en Full (strict) o desactiva el proxy hasta que se emita el certificado.

El estado se actualiza aproximadamente cada minuto (Dominios y HTTPS).

El dominio muestra 404 o una página de error

• 404 page not found: el dominio llega al servidor, pero ningún servicio lo tiene. Asócialo en la pestaña Networking del servicio.
• Bad gateway o Service unavailable: el dominio está asociado, pero el servicio no está en marcha o escucha en otro puerto distinto al que apunta el dominio.

Cuenta y acceso

No puedo añadir un servidor ni desplegar

Verifica primero tu correo: abre el enlace que te envió Zenavo o pide uno nuevo desde Account settings (Tu cuenta). Los Viewer no pueden desplegar ni cambiar nada; pide a un administrador del equipo el rol Member (Equipos y roles).

Perdí mi dispositivo de dos pasos

Inicia sesión con un código de recuperación (Autenticación en dos pasos). Si no tienes ninguno, escribe a info@zenavo.app desde el correo de la cuenta.

¿Sigues atascado?

Escribe a info@zenavo.app con el ID del proyecto o del servidor (cópialo desde Settings), la hora en que ocurrió y lo que muestran los registros. No envíes nunca contraseñas, claves ni valores de variables.