Su aplicación se detuvo. Encuentre la primera pista útil.

Defina un fallo observable

“Detenido” puede significar un error HTTP, un tiempo de espera, un trabajo que no terminó o un proceso que salió. Anote una URL o acción, su última hora de funcionamiento conocida, la primera hora de fallo y su zona horaria. Incluya si todos se ven afectados o solo un cliente. Mantenga abierta la sesión SSH actual mientras investiga; cambiar las reglas de acceso no es una primera respuesta necesaria a un error de aplicación.

Esta guía asume un host Linux usando systemd, un servicio de aplicación llamado first-api.service, y un endpoint de salud local en 127.0.0.1:3000/healthz. Estos valores predeterminados coinciden con la primera guía de despliegue de API. Sustituya sus nombres reales. La inspección puede requerir permiso de administrador para ver los procesos o registros de otros usuarios. Los comandos y resultados a continuación son ilustrativos; no se probó ninguna instancia de proveedor para esta guía.

Mantenga las notas fuera del propio directorio de la aplicación que falla. Registre observaciones antes de las interpretaciones: “conexión rechazada a las 09:18 UTC” es un hecho; “el VPS necesita más CPU” sigue siendo una hipótesis. Si el servidor en sí no es accesible, use su acceso de recuperación establecido y recopile los detalles de conexión en lugar de asumir que es posible reiniciar la aplicación.

Lea el estado del proceso y su historial reciente

systemctl status first-api.service --no-pager --full
systemctl show first-api.service -p ActiveState -p SubState -p Result -p ExecMainStatus -p NRestarts

La vista de estado describe la invocación actual o más reciente e incluye mensajes recientes del diario. Las propiedades seleccionadas le ofrecen un registro compacto para comparar más adelante. Un estado fallido o un recuento de reinicios en aumento merece investigación; un proceso activo aún necesita una prueba de solicitud. Estas son comprobaciones diferentes, como se describe en la referencia upstream de systemctl.

Si falta la unidad, primero verifique su nombre y el método de despliegue. Una aplicación iniciada en una terminal interactiva, un contenedor y un servicio systemd tienen diferentes propietarios y registros. Crear un nuevo servicio de inmediato podría dejar dos copias compitiendo por el mismo puerto. Identifique la configuración existente antes de cambiarla.

Compruebe el listener y haga una solicitud local

sudo ss -ltnp
curl --silent --show-error --max-time 5 http://127.0.0.1:3000/healthz

Busque la dirección y el puerto esperados, luego identifique el proceso propietario. Un proceso escuchando en otro puerto puede estar saludable pero ser inalcanzable por el proxy configurado. Un proceso diferente puede haber reclamado el puerto esperado. El manual de ss define las opciones de listener y proceso.

Si la solicitud local funciona y la solicitud pública HTTPS falla, continúe con las comprobaciones de DNS, TLS y proxy. Si el listener está ausente, examine el fallo de inicio. Si la conexión tiene éxito pero la aplicación devuelve un error, investigue esa ruta y sus dependencias. Curl sin --fail puede completarse correctamente para una respuesta de error HTTP, así que lea la respuesta en lugar de confiar solo en su código de salida. Consulte las opciones de respuesta y fallo de curl.

Lea alrededor del primer fallo, no solo la última línea

sudo journalctl -u first-api.service --since "30 minutes ago" --no-pager -n 100
sudo journalctl -k --since "30 minutes ago" --no-pager -n 100

La primera consulta selecciona el servicio; la segunda selecciona los mensajes del kernel. Ajuste el intervalo para incluir la última solicitud exitosa y el cambio que precedió a la interrupción. El acceso y la retención determinan qué permanece disponible. La referencia upstream de journalctl explica los filtros de unidad, tiempo y kernel. Redacte tokens, datos de clientes y cadenas de conexión antes de compartir extractos.

Extracto ilustrativo de una aplicación separada con una función de carga:

09:18:03 field-api: opening upload directory
09:18:03 field-api: EACCES: permission denied, open '/var/lib/field-api/uploads/index.json'
09:18:03 field-api: startup aborted

Esto apunta al acceso del usuario del servicio a una ruta específica. Verifique la propiedad del archivo y del directorio padre según las instrucciones de la versión. No otorgue acceso de escritura amplio a todo el sistema de archivos. Un mensaje posterior del proxy ‘upstream no disponible’ sería una consecuencia en este escenario, por lo que reparar primero el proxy pasaría por alto la causa.

Compare los recursos con la versión más reciente

free -h
df -h / /opt/first-api
df -i / /opt/first-api

Estas instantáneas le ayudan a preguntar si la presión de memoria, el espacio del sistema de archivos o el agotamiento de inodos coincidieron con el fallo. Su interpretación corresponde a la guía de memoria y disco; una sola lectura ocupada no establece la causa. Un servicio también puede alcanzar su propio límite de recursos mientras el resto del host tiene capacidad.

Compare el identificador de versión desplegado, el comando de inicio, los nombres de variables de entorno requeridos y las rutas de datos con la última versión que funcionó. No vuelque valores de entorno secretos en un informe. Busque un directorio renombrado, una dependencia de tiempo de ejecución faltante, un cambio de puerto o una migración de base de datos incompatible. Indique qué cambió y qué predice el error que debería encontrar.

Haga una corrección justificada y verifique la recuperación

Elija la corrección más pequeña respaldada por la evidencia. Para el fallo de permisos ilustrativo, eso significa restaurar el acceso previsto para la cuenta de servicio, luego hacer un intento de inicio controlado. Si en su lugar usa una versión de código que sabe que funciona, primero establezca si su esquema de base de datos sigue siendo compatible. Una reversión de código no puede revertir automáticamente una migración de datos.

Después de la corrección, repita las mismas comprobaciones del servicio, punto de enlace local y solicitud pública. Confirme que una acción representativa de la aplicación funciona, que los nuevos errores se han detenido y que el proceso permanece estable durante la siguiente carga de trabajo normal. Las políticas de reinicio pueden ayudar a recuperar un proceso, pero no vuelven saludable a un programa persistentemente roto; consulte la referencia de servicio de systemd para la política real.

Termine su nota de incidente con el síntoma, la primera pista útil, el cambio realizado y el resultado de la verificación. Si la causa sigue siendo incierta, informe esa incertidumbre con evidencia redactada en lugar de etiquetar un reinicio temporal como una solución permanente. Mejore la lista de verificación de la versión con la comprobación que habría detectado este fallo antes.