groales/netbox
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Page: Solución de Problemas
Pages
Actualización Backup y Restauración Configuración Inicial Home NPM Personalización Solución de Problemas Traefik
Clone
Solución de Problemas
groales edited this page 2025-12-04 12:59:24 +01:00
Table of Contents

Solución de Problemas

Diagnóstico y resolución de problemas comunes en NetBox.

Diagnóstico General

Ver Logs

# Logs de NetBox
docker logs netbox --tail 100 -f

# Logs de PostgreSQL
docker logs netbox-db --tail 50

# Logs de Redis
docker logs netbox-redis --tail 50

# Logs del stack completo
docker compose logs -f

Verificar Estado

# Estado de contenedores
docker ps -a | grep netbox

# Uso de recursos
docker stats netbox netbox-db netbox-redis --no-stream

# Redes
docker network inspect netbox-internal
docker network inspect proxy

Problemas Comunes

NetBox No Inicia

Síntomas: Contenedor se reinicia constantemente

Diagnóstico:

docker logs netbox | grep -i error
docker logs netbox | grep -i fatal

Causas comunes:

  1. PostgreSQL no está listo

    docker logs netbox-db
docker exec netbox-db pg_isready -U netbox

    Solución: Esperar o reiniciar PostgreSQL

    docker restart netbox-db
sleep 10
docker restart netbox

  2. Redis no accesible

    docker exec netbox-redis redis-cli --pass "PASSWORD" ping

    Solución: Verificar REDIS_PASSWORD en .env

  3. Permisos incorrectos

    docker exec netbox ls -la /config

    Solución:

    docker run --rm -v netbox_config:/config alpine chown -R 1000:1000 /config
docker restart netbox

  4. Error "cannot stat /app/netbox/netbox/media"

    Síntomas: En los logs aparece:

    mv: cannot stat '/app/netbox/netbox/media': No such file or directory

    Causa: El directorio /config/media no existe en el primer inicio

    Solución:

    # Crear directorio media en volumen persistente
docker exec netbox mkdir -p /config/media
docker exec netbox chown -R abc:users /config/media
docker restart netbox

    Verificar:

    docker logs netbox --tail 30

Error de Conexión a Base de Datos

Síntomas:

could not connect to server: Connection refused
FATAL: password authentication failed

Soluciones:

# Verificar que PostgreSQL está corriendo
docker ps | grep netbox-db

# Verificar password en .env
cat .env | grep DB_PASSWORD

# Verificar conexión desde NetBox
docker exec netbox ping netbox-db

# Resetear conexión
docker restart netbox-db
sleep 10
docker restart netbox

Error 502 Bad Gateway (NPM/Traefik)

Síntomas: Proxy no puede conectar con NetBox

Diagnóstico:

# Verificar que NetBox está corriendo
docker ps | grep netbox

# Verificar puerto 8000
docker exec netbox netstat -tlnp | grep 8000

# Verificar desde proxy
docker exec npm ping netbox

Soluciones:

  • Verificar que NetBox está en red proxy
  • Verificar que el contenedor se llama netbox
  • Reiniciar NetBox: docker restart netbox

Lentitud Extrema

Diagnóstico:

# Ver uso de CPU/RAM
docker stats netbox netbox-db netbox-redis

# Ver queries lentas en PostgreSQL
docker exec netbox-db psql -U netbox -c "SELECT query, calls, total_exec_time FROM pg_stat_statements ORDER BY total_exec_time DESC LIMIT 10;"

Soluciones:

  1. Limpiar caché de Redis

    docker exec netbox-redis redis-cli --pass "PASSWORD" FLUSHALL
docker restart netbox

  2. Optimizar PostgreSQL

    docker exec netbox-db psql -U netbox -c "VACUUM ANALYZE;"
docker exec netbox-db psql -U netbox -c "REINDEX DATABASE netbox;"

  3. Incrementar recursos (editar compose):

    services:
  netbox:
    deploy:
      resources:
        limits:
          memory: 2G
        reservations:
          memory: 1G

Error de Migración de Base de Datos

Síntomas:

django.db.migrations.exceptions.InconsistentMigrationHistory

Solución:

# Ver migraciones aplicadas
docker exec netbox python /app/netbox/manage.py showmigrations

# Aplicar migraciones faltantes
docker exec netbox python /app/netbox/manage.py migrate

# Si persiste, forzar
docker exec netbox python /app/netbox/manage.py migrate --fake

Certificado SSL no Funciona

Síntomas: Certificado inválido o HTTPS no funciona

Soluciones:

Con Traefik:

# Ver logs de Traefik
docker logs traefik | grep -i acme
docker logs traefik | grep netbox

# Verificar DNS
nslookup netbox.tudominio.com

# Forzar renovación
docker exec traefik rm /letsencrypt/acme.json
docker restart traefik

Con NPM:

  • Verificar que DNS apunta correctamente
  • Intentar con DNS Challenge si 80/443 bloqueados
  • Regenerar certificado en NPM UI

Plugin No Funciona

Diagnóstico:

# Ver plugins instalados
docker exec netbox pip list | grep netbox

# Ver logs de plugin
docker logs netbox | grep -i plugin

Soluciones:

# Reinstalar plugin
docker exec netbox pip install --force-reinstall netbox-plugin-name

# Verificar configuration.py
docker exec netbox cat /config/configuration.py | grep PLUGINS

# Reiniciar
docker restart netbox

Comandos de Emergencia

Reiniciar Todo

docker restart netbox netbox-redis netbox-db

Recrear NetBox (Mantiene Datos)

docker stop netbox
docker rm netbox
docker compose up -d netbox

Limpiar y Reiniciar

# Redis usa tmpfs - simplemente reiniciar el contenedor limpia la caché
docker restart netbox-redis
sleep 5
docker restart netbox

Acceso de Emergencia a Django Shell

# Shell de Django
docker exec -it netbox python /app/netbox/manage.py shell

# Ejemplo: crear superusuario
>>> from django.contrib.auth import get_user_model
>>> User = get_user_model()
>>> User.objects.create_superuser('admin', 'admin@example.com', 'password')

Resetear Password de Admin

docker exec -it netbox python /app/netbox/manage.py changepassword admin

Reconstruir Índices de Búsqueda

docker exec netbox python /app/netbox/manage.py reindex --lazy

Limpiar Sesiones Antiguas

docker exec netbox python /app/netbox/manage.py clearsessions

Recuperación de Desastres

NetBox Corrupto - Restaurar desde Backup

# 1. Detener todo
docker stop netbox netbox-redis netbox-db

# 2. Eliminar volúmenes corruptos
docker volume rm netbox_db netbox_config

# 3. Recrear volúmenes
docker volume create netbox_db
docker volume create netbox_config

# 4. Iniciar PostgreSQL
docker start netbox-db
sleep 10

# 5. Restaurar BD
gunzip < /backups/netbox/netbox-backup-FECHA.sql.gz | docker exec -i netbox-db psql -U netbox netbox

# 6. Restaurar config
docker run --rm -v netbox_config:/restore -v /backups/netbox:/source alpine tar xzf /source/netbox-config-FECHA.tar.gz -C /restore

# 7. Iniciar todo
docker start netbox-redis
sleep 5
docker start netbox

PostgreSQL Corrupto

# Intentar reparar
docker exec netbox-db pg_resetwal /var/lib/postgresql/data

# Si falla, restaurar desde backup
docker stop netbox-db
docker volume rm netbox_db
docker volume create netbox_db
docker start netbox-db
sleep 10
cat netbox-backup.sql | docker exec -i netbox-db psql -U netbox netbox

Obtener Ayuda

Información del Sistema

# Versión de NetBox
docker exec netbox python /app/netbox/manage.py version

# Versión de Python
docker exec netbox python --version

# Versión de PostgreSQL
docker exec netbox-db psql --version

# Variables de entorno
docker exec netbox env | grep -E "DB_|REDIS_|SUPER"

# Compose usado
docker inspect netbox | grep -A 20 Labels

Recursos Oficiales

Prevención

Monitorización

# Script de health check
#!/bin/bash
if docker exec netbox curl -f http://localhost:8000/api/ > /dev/null 2>&1; then
    echo "✓ NetBox OK"
else
    echo "✗ NetBox DOWN"
    docker logs netbox --tail 50
fi

Alertas

Configura alertas en tu sistema de monitorización (Prometheus, Zabbix, etc.):

  • CPU > 80%
  • RAM > 90%
  • Disco > 85%
  • NetBox no responde

Próximos Pasos

  1. Backup - Automatiza backups para prevenir desastres
  2. Actualización - Mantén NetBox actualizado
  3. Comunidad - Pregunta si no encuentras solución

NetBox Wiki

🚀 Inicio

📦 Despliegue

⚙️ Configuración

💾 Mantenimiento