Troubleshooting

Guía de depuración de problemas comunes

Árbol de Decisión

¿El servicio está corriendo?
├── NO → Ver "Servicio no inicia"
└── SÍ → ¿Responde en localhost?
    ├── NO → Ver "Servicio no responde"
    └── SÍ → ¿Responde via dominio?
        ├── NO → Ver "Problemas de Caddy"
        └── SÍ → ¿Hay errores?
            └── Ver "Errores de aplicación"

Servicio No Inicia

1. Verificar estado

systemctl status proyecto.service

Buscar: Active: failed o Active: inactive

2. Ver logs de inicio

journalctl -u proyecto.service -n 50 --no-pager

3. Errores comunes

“Module not found”

cd /srv/projects/proyecto
./venv/bin/pip install -r requirements.txt

“Address already in use”

# Ver qué usa el puerto
ss -tlnp | grep 8105
# Matar proceso si es necesario
kill -9 <PID>

“Permission denied”

# Verificar ownership
ls -la /srv/projects/proyecto/
# Corregir si es necesario
sudo chown -R illanes00:illanes00 /srv/projects/proyecto/

Servicio No Responde

El servicio corre pero no responde a requests.

1. Probar localmente

curl -v http://localhost:8105/healthz

2. Verificar binding

Asegurarse que la app escucha en 0.0.0.0:

ss -tlnp | grep 8105
# Debe mostrar 0.0.0.0:8105, no 127.0.0.1:8105

3. Ver logs de la app

journalctl -u proyecto.service -f
# Hacer request en otra terminal
curl http://localhost:8105/

Problemas de Caddy

502 Bad Gateway

El upstream no responde.

# 1. Verificar servicio backend
systemctl status proyecto.service

# 2. Probar conexión directa
curl http://localhost:8105/healthz

# 3. Verificar configuración Caddy
cat /srv/projects/proyecto/deploy/caddy.caddy

503 Service Unavailable

Caddy no puede conectar.

# Ver logs de Caddy
journalctl -u caddy -f

Certificado inválido

# Verificar fecha del certificado
echo | openssl s_client -connect proyecto.illanes00.cl:443 2>/dev/null | openssl x509 -noout -dates

# Forzar renovación
sudo rm -rf /var/lib/caddy/.local/share/caddy/certificates/*/proyecto.illanes00.cl/
sudo systemctl reload caddy

Errores de Aplicación

500 Internal Server Error

# Ver logs de la app
journalctl -u proyecto.service -f

# Buscar tracebacks
journalctl -u proyecto.service | grep -A 20 "Traceback"

Conexión a Base de Datos

# Probar conexión PostgreSQL
psql -h localhost -U usuario -d database -c "SELECT 1"

# Verificar PgBouncer
psql -h localhost -p 6432 -U usuario -d database -c "SELECT 1"

# Ver conexiones activas
psql -c "SELECT * FROM pg_stat_activity WHERE datname='database'"

Problemas de Memoria

# Ver uso de memoria del proceso
ps aux | grep proyecto

# Ver logs de OOM killer
dmesg | grep -i "killed process"

Comandos de Diagnóstico

# Estado general
systemctl status proyecto.service

# Logs recientes
journalctl -u proyecto.service -n 100 --no-pager

# Puertos en uso
ss -tlnp

# Uso de recursos
htop -p $(pgrep -f "proyecto")

# Conexiones de red
netstat -tuln | grep 8105

# DNS
dig proyecto.illanes00.cl

# Certificado SSL
curl -vI https://proyecto.illanes00.cl 2>&1 | head -30

Checklist de Deploy

Antes de reportar un problema, verificar: