La tua app si è fermata. Trova il primo indizio utile.

Definisci un guasto osservabile

“Fermato” può significare un errore HTTP, un timeout, un job che non è terminato o un processo che è uscito. Annota un URL o un'azione, la sua ultima ora di funzionamento nota, l'ora del primo guasto e il tuo fuso orario. Includi se sono interessati tutti o un solo client. Tieni aperta la sessione SSH corrente durante l'indagine; cambiare le regole di accesso non è una prima risposta necessaria a un errore dell'applicazione.

Questa guida presuppone un host Linux che usa systemd, un servizio applicativo chiamato first-api.service, e un endpoint di salute locale su 127.0.0.1:3000/healthz. Questi valori predefiniti corrispondono alla guida al primo deployment API. Sostituisci con i tuoi nomi effettivi. L'ispezione può richiedere permessi di amministratore per vedere i processi o i log di altri utenti. I comandi e gli output seguenti sono illustrativi; nessuna istanza di provider è stata testata per questa guida.

Tieni le note fuori dalla directory dell'app in errore stessa. Registra le osservazioni prima delle interpretazioni: “connection refused alle 09:18 UTC” è un fatto; “il VPS ha bisogno di più CPU” è ancora un'ipotesi. Se il server stesso non è raggiungibile, usa il tuo accesso di recupero stabilito e raccogli i dettagli di connessione invece di presumere che sia possibile un riavvio dell'app.

Leggi lo stato del processo e la sua cronologia recente

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 journal. Las propiedades seleccionadas ofrecen un registro compacto para comparar más tarde. Un estado fallido o un recuento de reinicios en aumento merece investigación; un proceso activo aún necesita una prueba de solicitud. Son comprobaciones distintas, como se describe en la referencia upstream de systemctl.

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

Controlla il listener e fai una richiesta locale

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

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

Si la solicitud local funciona y la solicitud pública HTTPS falla, continúa con las comprobaciones de DNS, TLS y proxy. Si el listener está ausente, examina el fallo de arranque. Si la conexión se establece pero la app devuelve un error, investiga esa ruta y sus dependencias. Curl sin --fail puede completarse con éxito ante una respuesta de error HTTP, así que lee la respuesta en lugar de confiar solo en su código de salida. Consulta las opciones de respuesta y fallo de curl.

Leggi intorno al primo guasto, non solo l'ultima riga

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. Ajusta el intervalo para incluir la última solicitud que funcionó y el cambio que precedió a la caída. El acceso y la retención determinan qué sigue disponible. La referencia upstream de journalctl explica los filtros de unidad, tiempo y kernel. Redacta tokens, datos de clientes y cadenas de conexión antes de compartir extractos.

Extracto ilustrativo de una app distinta 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. Verifica la propiedad del archivo y del directorio padre según las instrucciones de la release. No otorgues acceso de escritura amplio a todo el sistema de archivos. Un mensaje posterior del proxy de "upstream no disponible" sería una consecuencia en este escenario, así que reparar primero el proxy pasaría por alto la causa.

Confronta le risorse con la release più recente

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

Estas instantáneas 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 única lectura de saturación no establece la causa. Un servicio también puede alcanzar su propio límite de recursos mientras el resto del host tiene capacidad.

Compara el identificador de release desplegado, el comando de inicio, los nombres de variables de entorno requeridos y las rutas de datos con la última release que funcionó. No vuelques valores secretos del entorno en un informe. Busca un directorio renombrado, una dependencia de runtime faltante, un cambio de puerto o una migración de base de datos incompatible. Indica qué cambió y qué predice el error que deberías encontrar.

Fai una correzione giustificata e verifica il ripristino

Elige 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 del servicio y luego hacer un intento de arranque controlado. Si en su lugar usas una release de código que se sabe que funciona, primero establece 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, repite las mismas comprobaciones de servicio, endpoint local y solicitud pública. Confirma que una acción representativa de la aplicación funciona, que los nuevos errores se han detenido y que el proceso se mantiene estable durante la siguiente carga de trabajo normal. Las políticas de reinicio pueden ayudar a recuperar un proceso, pero no hacen que un programa roto de forma persistente esté sano; consulta la referencia de servicio de systemd para la política real.

Termina tu 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, informa esa incertidumbre con evidencia redactada en lugar de etiquetar un reinicio temporal como una solución permanente. Mejora la lista de verificación de release con la comprobación que habría detectado este fallo antes.