FlotillasGPS - Sistema completo de monitoreo de flotillas GPS

Sistema completo para monitoreo y gestion de flotas de vehiculos con: - Backend FastAPI con PostgreSQL/TimescaleDB - Frontend React con TypeScript y TailwindCSS - App movil React Native con Expo - Soporte para dispositivos GPS, Meshtastic y celulares - Video streaming en vivo con MediaMTX - Geocercas, alertas, viajes y reportes - Autenticacion JWT y WebSockets en tiempo real Documentacion completa y guias de usuario incluidas.
2026-01-21 08:18:00 +00:00
commit 51d78bacf4
248 changed files with 50171 additions and 0 deletions
--- a/docs/guias/troubleshooting.md
+++ b/docs/guias/troubleshooting.md
@@ -0,0 +1,557 @@
+# Solucion de Problemas
+
+Guia para diagnosticar y resolver problemas comunes en FlotillasGPS.
+
+## Diagnostico Rapido
+
+### Verificar Estado de Servicios
+
+```bash
+# Ver estado de todos los servicios
+systemctl status flotillas-api flotillas-web traccar mediamtx cloudflared redis postgresql
+
+# Resumen rapido
+for svc in flotillas-api flotillas-web traccar mediamtx cloudflared; do
+  echo "$svc: $(systemctl is-active $svc)"
+done
+```
+
+### Verificar Logs
+
+```bash
+# API Backend
+journalctl -u flotillas-api -f
+
+# Frontend
+journalctl -u flotillas-web -f
+
+# Traccar (GPS)
+journalctl -u traccar -f
+
+# Cloudflare Tunnel
+journalctl -u cloudflared -f
+```
+
+### Verificar Conectividad
+
+```bash
+# 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 flotillas -d flotillas_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:
+```bash
+systemctl status cloudflared
+cloudflared tunnel info flotillas
+```
+
+2. Estado del frontend:
+```bash
+systemctl status flotillas-web
+curl http://localhost:3000
+```
+
+**Soluciones**:
+
+- Reiniciar el tunnel:
+```bash
+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**:
+```bash
+systemctl status flotillas-api
+curl http://localhost:8000/api/v1/health
+```
+
+**Soluciones**:
+```bash
+# Reiniciar backend
+systemctl restart flotillas-api
+
+# Ver logs de error
+journalctl -u flotillas-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:
+```bash
+# Desde el servidor
+netstat -tlnp | grep 5055
+
+# Desde fuera (otra maquina)
+nc -zv IP_SERVIDOR 5055
+```
+
+2. Traccar funcionando:
+```bash
+systemctl status traccar
+journalctl -u traccar -f
+```
+
+3. Firewall:
+```bash
+ufw status
+# Debe mostrar 5055/tcp ALLOW
+```
+
+**Soluciones**:
+
+- Abrir puerto en firewall:
+```bash
+ufw allow 5055/tcp
+```
+
+- Verificar configuracion del GPS:
+  - IP/dominio del servidor correcto
+  - Puerto 5055
+  - Protocolo correcto (ver manual del GPS)
+
+- Reiniciar Traccar:
+```bash
+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:
+```bash
+# 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**:
+```bash
+# Ver ubicaciones recientes en DB
+psql -U flotillas -d flotillas_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**:
+```bash
+# Ver ultimas ubicaciones de apps
+journalctl -u flotillas-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**:
+```bash
+# Ver logs de notificaciones
+journalctl -u flotillas-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
+
+```bash
+# 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:
+```bash
+df -h /opt/flotillas/videos
+```
+
+2. Permisos:
+```bash
+ls -la /opt/flotillas/videos
+```
+
+**Solucion**:
+```bash
+# Liberar espacio
+find /opt/flotillas/videos -name "*.mp4" -mtime +30 -delete
+
+# Arreglar permisos
+chown -R www-data:www-data /opt/flotillas/videos
+```
+
+---
+
+## Problemas de Base de Datos
+
+### Error de conexion a PostgreSQL
+
+```bash
+# Verificar estado
+systemctl status postgresql
+
+# Verificar que acepta conexiones
+psql -U flotillas -d flotillas_db -c "SELECT 1"
+```
+
+**Soluciones**:
+```bash
+# Reiniciar PostgreSQL
+systemctl restart postgresql
+
+# Ver logs
+journalctl -u postgresql -f
+```
+
+### Base de datos lenta
+
+**Verificar**:
+```bash
+# Ver consultas lentas
+psql -U flotillas -d flotillas_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:
+```bash
+psql -U flotillas -d flotillas_db -c "VACUUM ANALYZE;"
+```
+
+2. Verificar indices:
+```bash
+psql -U flotillas -d flotillas_db -c "\di"
+```
+
+### Disco lleno por ubicaciones
+
+**Verificar**:
+```bash
+psql -U flotillas -d flotillas_db -c "
+  SELECT pg_size_pretty(pg_total_relation_size('ubicaciones'));
+"
+```
+
+**Solucion**: Comprimir datos antiguos (TimescaleDB):
+```bash
+psql -U flotillas -d flotillas_db -c "
+  SELECT compress_chunk(c)
+  FROM show_chunks('ubicaciones', older_than => INTERVAL '7 days') c;
+"
+```
+
+---
+
+## Problemas de Rendimiento
+
+### Servidor lento
+
+**Verificar recursos**:
+```bash
+# 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**:
+```bash
+# Tiempo de respuesta
+time curl http://localhost:8000/api/v1/health
+
+# Workers activos
+ps aux | grep uvicorn
+```
+
+**Soluciones**:
+
+1. Aumentar workers en el servicio:
+```bash
+# Editar /etc/systemd/system/flotillas-api.service
+# Cambiar --workers 4 a --workers 8
+systemctl daemon-reload
+systemctl restart flotillas-api
+```
+
+2. Verificar conexiones a Redis:
+```bash
+redis-cli info clients
+```
+
+---
+
+## Problemas de Meshtastic
+
+### Nodos no aparecen
+
+**Verificar MQTT**:
+```bash
+# Estado de Mosquitto
+systemctl status mosquitto
+
+# Suscribirse para ver mensajes
+mosquitto_sub -h localhost -t "flotillas/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**:
+```bash
+journalctl -u flotillas-api | grep "meshtastic\|mesh"
+```
+
+**Solucion**: Verificar que el servicio MQTT esta corriendo en el backend.
+
+---
+
+## Backup y Restauracion
+
+### Backup falla
+
+**Verificar**:
+```bash
+# Espacio en disco
+df -h /opt/flotillas/backups
+
+# Permisos
+ls -la /opt/flotillas/scripts/backup.sh
+```
+
+**Ejecutar manualmente para ver errores**:
+```bash
+/opt/flotillas/scripts/backup.sh 2>&1 | tee /tmp/backup.log
+```
+
+### Restauracion falla
+
+**Verificar integridad del backup**:
+```bash
+gunzip -t /opt/flotillas/backups/db_FECHA.sql.gz
+```
+
+**Restaurar paso a paso**:
+```bash
+# Parar servicios
+systemctl stop flotillas-api
+
+# Recrear base de datos
+psql -U postgres -c "DROP DATABASE flotillas_db;"
+psql -U postgres -c "CREATE DATABASE flotillas_db OWNER flotillas;"
+
+# Restaurar
+gunzip -c backup.sql.gz | psql -U flotillas -d flotillas_db
+
+# Iniciar servicios
+systemctl start flotillas-api
+```
+
+---
+
+## Comandos Utiles de Diagnostico
+
+```bash
+# Estado general del sistema
+systemctl status flotillas-api flotillas-web traccar mediamtx cloudflared
+
+# Uso de recursos
+htop
+df -h
+free -h
+
+# Logs en tiempo real
+journalctl -u flotillas-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 flotillas -d flotillas_db -c "SELECT COUNT(*) FROM vehiculos;"
+
+# Ultimas ubicaciones
+psql -U flotillas -d flotillas_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 flotillas -d flotillas_db -c "
+  SELECT COUNT(*) as pendientes FROM alertas WHERE atendida = false;
+"
+```
+
+---
+
+## Contacto de Soporte
+
+Si no puedes resolver el problema:
+
+1. Recolectar informacion:
+```bash
+# Crear archivo de diagnostico
+{
+  echo "=== FECHA ==="
+  date
+  echo "=== SERVICIOS ==="
+  systemctl status flotillas-api flotillas-web traccar mediamtx cloudflared
+  echo "=== RECURSOS ==="
+  free -h
+  df -h
+  echo "=== LOGS RECIENTES ==="
+  journalctl -u flotillas-api -n 50 --no-pager
+} > /tmp/diagnostico.txt
+```
+
+2. Enviar `diagnostico.txt` al equipo de soporte