ATLAS/docs/guias/troubleshooting.md

Solucion de Problemas

Guia para diagnosticar y resolver problemas comunes en ATLAS.

Diagnostico Rapido

Verificar Estado de Servicios

# Ver estado de todos los servicios
systemctl status atlas-api atlas-web traccar mediamtx cloudflared redis postgresql

# Resumen rapido
for svc in atlas-api atlas-web traccar mediamtx cloudflared; do
  echo "$svc: $(systemctl is-active $svc)"
done

Verificar Logs

# API Backend
journalctl -u atlas-api -f

# Frontend
journalctl -u atlas-web -f

# Traccar (GPS)
journalctl -u traccar -f

# Cloudflare Tunnel
journalctl -u cloudflared -f

Verificar Conectividad

# Puerto GPS
netstat -tlnp | grep 5055

# Puerto API
curl http://localhost:8000/api/v1/health

# Puerto Frontend
curl http://localhost:3000

# Base de datos
psql -U atlas -d atlas_db -c "SELECT 1"

# Redis
redis-cli ping

---

Problemas de Acceso Web

No puedo acceder al dashboard

Sintomas: El navegador muestra error de conexion o timeout.

Verificar:

1. Estado del tunnel de Cloudflare:

systemctl status cloudflared
cloudflared tunnel info atlas

2. Estado del frontend:

systemctl status atlas-web
curl http://localhost:3000

Soluciones:

• Reiniciar el tunnel:

systemctl restart cloudflared

• Verificar configuracion DNS en Cloudflare dashboard

• Verificar que el dominio apunta al tunnel correcto

Error 502 Bad Gateway

Causa: El backend no esta respondiendo.

Verificar:

systemctl status atlas-api
curl http://localhost:8000/api/v1/health

Soluciones:

# Reiniciar backend
systemctl restart atlas-api

# Ver logs de error
journalctl -u atlas-api -n 100 --no-pager

Error de SSL/Certificado

Causa: Problema con Cloudflare.

Soluciones:

1. En Cloudflare dashboard, verificar que SSL este en "Full" o "Full (strict)"
2. Verificar que el dominio este activo
3. Esperar propagacion DNS (hasta 24 horas)

---

Problemas con GPS

Los dispositivos GPS no se conectan

Sintomas: Vehiculos aparecen offline, no se reciben ubicaciones.

Verificar:

1. Puerto 5055 abierto:

# Desde el servidor
netstat -tlnp | grep 5055

# Desde fuera (otra maquina)
nc -zv IP_SERVIDOR 5055

2. Traccar funcionando:

systemctl status traccar
journalctl -u traccar -f

3. Firewall:

ufw status
# Debe mostrar 5055/tcp ALLOW

Soluciones:

• Abrir puerto en firewall:

ufw allow 5055/tcp

• Verificar configuracion del GPS:

  • IP/dominio del servidor correcto
  • Puerto 5055
  • Protocolo correcto (ver manual del GPS)

• Reiniciar Traccar:

systemctl restart traccar

GPS conecta pero no aparece en el mapa

Causa: El dispositivo no esta vinculado a un vehiculo.

Solucion:

1. Verificar que el dispositivo esta registrado en Traccar:

# Ver dispositivos en Traccar
curl http://localhost:8082/api/devices

2. Vincular el dispositivo al vehiculo desde el dashboard

Ubicaciones con retraso

Causas posibles:

1. Problema de red del GPS
2. Intervalo de reporte muy largo
3. Problema de procesamiento

Verificar:

# Ver ubicaciones recientes en DB
psql -U atlas -d atlas_db -c "
  SELECT vehiculo_id, tiempo, lat, lng
  FROM ubicaciones
  ORDER BY tiempo DESC
  LIMIT 10;
"

---

Problemas con la App Movil

La app no envia ubicacion

Verificar en el telefono:

1. Permiso de ubicacion en "Siempre"
2. GPS activado
3. Datos moviles o WiFi activo
4. App no en modo ahorro de bateria

Verificar en el servidor:

# Ver ultimas ubicaciones de apps
journalctl -u atlas-api | grep "ubicacion" | tail -20

App no puede conectar al servidor

Causas:

1. Sin conexion a internet
2. Token expirado
3. Dispositivo no registrado

Solucion:

1. Verificar conexion a internet
2. Cerrar sesion y volver a entrar
3. Verificar que el conductor tiene dispositivo asignado

Notificaciones no llegan

Verificar:

1. Permiso de notificaciones en el telefono
2. App no silenciada
3. Token de push registrado

En el servidor:

# Ver logs de notificaciones
journalctl -u atlas-api | grep "push\|notification"

---

Problemas de Video

Camara no conecta

Verificar:

1. URL del stream correcta
2. Credenciales correctas
3. Camara accesible desde el servidor

# Probar conexion RTSP
ffprobe rtsp://usuario:password@IP_CAMARA/stream

Soluciones:

• Verificar que la camara y el servidor estan en la misma red (o hay ruta)
• Verificar puerto de la camara no bloqueado
• Probar con VLC desde otra maquina

Video con lag/retraso

Causas:

1. Ancho de banda insuficiente
2. Servidor sobrecargado
3. Configuracion de bitrate muy alto

Soluciones:

• Reducir calidad del stream en configuracion de camara
• Verificar uso de CPU/RAM del servidor
• Usar HLS en lugar de WebRTC para conexiones lentas

No se guardan grabaciones

Verificar:

1. Espacio en disco:

df -h /opt/atlas/videos

2. Permisos:

ls -la /opt/atlas/videos

Solucion:

# Liberar espacio
find /opt/atlas/videos -name "*.mp4" -mtime +30 -delete

# Arreglar permisos
chown -R www-data:www-data /opt/atlas/videos

---

Problemas de Base de Datos

Error de conexion a PostgreSQL

# Verificar estado
systemctl status postgresql

# Verificar que acepta conexiones
psql -U atlas -d atlas_db -c "SELECT 1"

Soluciones:

# Reiniciar PostgreSQL
systemctl restart postgresql

# Ver logs
journalctl -u postgresql -f

Base de datos lenta

Verificar:

# Ver consultas lentas
psql -U atlas -d atlas_db -c "
  SELECT pid, now() - pg_stat_activity.query_start AS duration, query
  FROM pg_stat_activity
  WHERE state != 'idle'
  ORDER BY duration DESC;
"

Soluciones:

1. Ejecutar VACUUM:

psql -U atlas -d atlas_db -c "VACUUM ANALYZE;"

2. Verificar indices:

psql -U atlas -d atlas_db -c "\di"

Disco lleno por ubicaciones

Verificar:

psql -U atlas -d atlas_db -c "
  SELECT pg_size_pretty(pg_total_relation_size('ubicaciones'));
"

Solucion: Comprimir datos antiguos (TimescaleDB):

psql -U atlas -d atlas_db -c "
  SELECT compress_chunk(c)
  FROM show_chunks('ubicaciones', older_than => INTERVAL '7 days') c;
"

---

Problemas de Rendimiento

Servidor lento

Verificar recursos:

# CPU y RAM
htop

# Disco
iostat -x 1

# Conexiones de red
ss -s

Soluciones:

1. Aumentar RAM de la VM
2. Agregar mas cores de CPU
3. Usar SSD para base de datos
4. Optimizar consultas lentas

API responde lento

Verificar:

# Tiempo de respuesta
time curl http://localhost:8000/api/v1/health

# Workers activos
ps aux | grep uvicorn

Soluciones:

1. Aumentar workers en el servicio:

# Editar /etc/systemd/system/atlas-api.service
# Cambiar --workers 4 a --workers 8
systemctl daemon-reload
systemctl restart atlas-api

2. Verificar conexiones a Redis:

redis-cli info clients

---

Problemas de Meshtastic

Nodos no aparecen

Verificar MQTT:

# Estado de Mosquitto
systemctl status mosquitto

# Suscribirse para ver mensajes
mosquitto_sub -h localhost -t "atlas/mesh/#" -u mesh_gateway -P password

Verificar configuracion del gateway:

• MQTT habilitado
• Servidor y credenciales correctos
• Topic correcto

Ubicaciones de mesh no se guardan

Verificar:

journalctl -u atlas-api | grep "meshtastic\|mesh"

Solucion: Verificar que el servicio MQTT esta corriendo en el backend.

---

Backup y Restauracion

Backup falla

Verificar:

# Espacio en disco
df -h /opt/atlas/backups

# Permisos
ls -la /opt/atlas/scripts/backup.sh

Ejecutar manualmente para ver errores:

/opt/atlas/scripts/backup.sh 2>&1 | tee /tmp/backup.log

Restauracion falla

Verificar integridad del backup:

gunzip -t /opt/atlas/backups/db_FECHA.sql.gz

Restaurar paso a paso:

# Parar servicios
systemctl stop atlas-api

# Recrear base de datos
psql -U postgres -c "DROP DATABASE atlas_db;"
psql -U postgres -c "CREATE DATABASE atlas_db OWNER atlas;"

# Restaurar
gunzip -c backup.sql.gz | psql -U atlas -d atlas_db

# Iniciar servicios
systemctl start atlas-api

---

Comandos Utiles de Diagnostico

# Estado general del sistema
systemctl status atlas-api atlas-web traccar mediamtx cloudflared

# Uso de recursos
htop
df -h
free -h

# Logs en tiempo real
journalctl -u atlas-api -f

# Conexiones activas
ss -tlnp

# Verificar puertos
netstat -tlnp

# Test de API
curl -s http://localhost:8000/api/v1/health | jq

# Test de base de datos
psql -U atlas -d atlas_db -c "SELECT COUNT(*) FROM vehiculos;"

# Ultimas ubicaciones
psql -U atlas -d atlas_db -c "
  SELECT v.nombre, u.tiempo, u.lat, u.lng, u.velocidad
  FROM ubicaciones u
  JOIN vehiculos v ON u.vehiculo_id = v.id
  ORDER BY u.tiempo DESC
  LIMIT 10;
"

# Alertas pendientes
psql -U atlas -d atlas_db -c "
  SELECT COUNT(*) as pendientes FROM alertas WHERE atendida = false;
"

---

Contacto de Soporte

Si no puedes resolver el problema:

1. Recolectar informacion:

# Crear archivo de diagnostico
{
  echo "=== FECHA ==="
  date
  echo "=== SERVICIOS ==="
  systemctl status atlas-api atlas-web traccar mediamtx cloudflared
  echo "=== RECURSOS ==="
  free -h
  df -h
  echo "=== LOGS RECIENTES ==="
  journalctl -u atlas-api -n 50 --no-pager
} > /tmp/diagnostico.txt

2. Enviar diagnostico.txt al equipo de soporte