7.5 KiB
Solución de problemas
Empiece aquí: triage por síntoma
Use esta tabla para ir al primer check rápidamente.
¿Necesita definiciones de términos de licencia/scheduler? Vea el Glosario.
| Síntoma | Primer check | Ubicación en WebUI | Siguiente sección |
|---|---|---|---|
| No se puede acceder a la WebUI | systemctl status lqosd |
N/A (UI no disponible) | No hay WebUI en x.x.x.x:9123 |
| Hay tráfico pero no hace shaping | verificar to_internet / to_network y servicios |
WebUI Dashboard | LibreQoS está en ejecución, pero no hace shaping |
| Scheduler no saludable | revisar logs de lqosd y lqos_scheduler |
WebUI -> Scheduler Status | El estado del scheduler en WebUI aparece no saludable |
| Vistas de topología/flujo vacías | confirmar tráfico reciente y estado de lqosd |
WebUI -> Flow Globe / Tree / ASN Analysis | Flow Globe / Tree Overview / ASN Analysis aparecen en blanco |
| Aparece código urgente | abrir detalle y mapear código | WebUI -> Urgent Issues | Códigos de problemas urgentes y primeras acciones |
| Eventos de límite de circuitos | validar licencia y conteos mapped | Insight UI + WebUI -> Urgent Issues | Se alcanzó el límite de circuitos mapeados |
Problemas comunes
Dónde en la WebUI
- Estado de servicios y salud general:
WebUI -> Dashboard - Estado/readiness del scheduler:
WebUI -> Scheduler Status - Alertas prioritarias:
WebUI -> Urgent Issues - Visualización de topología/tráfico:
WebUI -> Network Tree OverviewyFlow Globe - Revisión de datos de shaping:
WebUI -> Shaped Devices Editor
Antes de pedir ayuda en chat: recolecte esta evidencia
sudo systemctl status lqosd lqos_scheduler
journalctl -u lqosd --since "30 minutes ago"
journalctl -u lqos_scheduler --since "30 minutes ago"
Si el problema es de integración, agregue:
ls -lh /opt/libreqos/src/network.json /opt/libreqos/src/ShapedDevices.csv
Incluya también:
- versión/build actual
- tipo de integración y estrategia
- síntoma exacto y hora de inicio
La contraseña de usuario no funciona
Elimine el archivo de usuarios:
sudo rm /opt/libreqos/src/lqusers.toml
sudo systemctl restart lqosd lqos_scheduler
Luego abra: IP_CAJA:9123/index.html.
No hay WebUI en x.x.x.x:9123
La WebUI depende de lqosd. En builds actuales, la mayoría de fallas de acceso WebUI se explican por lqosd no saludable.
sudo systemctl status lqosd
Luego siga el flujo completo en El servicio lqosd no se ejecuta o falla al iniciar.
LibreQoS está en ejecución, pero no hace shaping
Verifique en /etc/lqos.conf que to_internet y to_network estén correctos.
sudo systemctl restart lqosd lqos_scheduler
sudo systemctl status lqosd lqos_scheduler
On-a-stick: shaping incorrecto o una dirección débil
On-a-stick depende de split correcto por dirección. Si la detección TX o override_available_queues está mal, el mapeo puede degradarse.
sudo systemctl status lqosd
journalctl -u lqosd --since "10 minutes ago"
sudo systemctl restart lqosd lqos_scheduler
El servicio lqosd no se ejecuta o falla al iniciar
sudo systemctl status lqosd
journalctl -u lqosd --since "10 minutes ago"
Depuración avanzada de lqosd
sudo RUST_LOG=info /opt/libreqos/src/bin/lqosd
El servicio lqos_scheduler muestra errores
sudo journalctl -u lqos_scheduler --since "1 day ago" --no-pager > lqos_sched_log.txt
El estado del scheduler en WebUI aparece no saludable
Versiones recientes muestran estado/readiness del scheduler en WebUI.
Si aparece caído/desactualizado:
- Verifique ambos servicios.
- Revise logs recientes del scheduler.
- Revise logs de
lqosdpara eventos de scheduler ready/error. - Si hubo cambios recientes, reinicie servicios.
sudo systemctl status lqosd lqos_scheduler
journalctl -u lqos_scheduler --since "30 minutes ago"
journalctl -u lqosd --since "30 minutes ago"
sudo systemctl restart lqosd lqos_scheduler
Si oscila entre ready/error, valide credenciales y timeouts de integración en /etc/lqos.conf.
RTNETLINK answers: Invalid argument
Suele indicar que no se pudo agregar correctamente qdisc MQ en la NIC (colas RX/TX insuficientes). Verifique NICs recomendadas.
Python ModuleNotFoundError en Ubuntu 24.04
pip uninstall binpacking --break-system-packages --yes
sudo pip uninstall binpacking --break-system-packages --yes
sudo pip install binpacking --break-system-packages
pip uninstall apscheduler --break-system-packages --yes
sudo pip uninstall apscheduler --break-system-packages --yes
sudo pip install apscheduler --break-system-packages
pip uninstall deepdiff --break-system-packages --yes
sudo pip uninstall deepdiff --break-system-packages --yes
sudo pip install deepdiff --break-system-packages
Todas las IPs de clientes aparecen como Unknown IPs
cd /opt/libreqos/src
sudo systemctl stop lqos_scheduler
sudo python3 LibreQoS.py
Corrija errores en ShapedDevices.csv y/o network.json, luego:
sudo systemctl start lqos_scheduler
Flow Globe / Tree Overview / ASN Analysis aparecen en blanco
Algunas vistas requieren suficiente dato reciente para renderizar.
- Confirme que
lqosdestá saludable. - Espere acumulación de tráfico.
- Recargue la página tras 1-2 minutos.
- Revise logs:
journalctl -u lqosd --since "10 minutes ago"
Si sigue en blanco con tráfico normal, recolecte logs y abra issue.
Colisión de promoción de nodo virtual (network.json)
Si LibreQoS.py falla con Virtual node promotion collision: 'AP_A' already exists at this level., hay un nodo con "virtual": true cuyos hijos colisionan por nombre al promoverse.
Renombre nodos en conflicto o reestructure jerarquía para evitar colisiones. Para un visual del flujo lógico-a-físico y la asignación de CPU, consulte Referencia avanzada de configuración.
Se alcanzó el límite de circuitos mapeados
Si ve mensajes como:
Mapped circuit limit reachedBakery mapped circuit cap enforced
LibreQoS está aplicando un límite de circuitos mapeados.
Checks recomendados:
- Confirmar estado de licencia Insight en UI.
- Revisar logs de
lqosdpara requested/allowed/dropped. - Reducir circuitos mapeados (corto plazo) o ajustar licencia/límites (largo plazo).
Códigos de problemas urgentes y primeras acciones
WebUI muestra códigos legibles por máquina para triage rápido.
| Código | Significado | Primeros checks | Ruta de corrección típica |
|---|---|---|---|
MAPPED_CIRCUIT_LIMIT |
Bakery está forzando límite de circuitos mapeados. | Estado de licencia Insight y journalctl -u lqosd con requested/allowed/dropped. |
Reducir circuitos mapeados o actualizar licencia/límites. |
TC_U16_OVERFLOW |
IDs minor de clases/colas excedieron rango u16 de tc en una cola CPU. | journalctl -u lqos_scheduler -u lqosd, profundidad topológica y distribución por colas. |
Aumentar paralelismo de colas y/o simplificar/rebalancear jerarquía. |
Patrón operativo:
- Abra el detalle del problema urgente en WebUI (código/mensaje/contexto).
- Recolecte logs correlacionados de
lqosdylqos_scheduler. - Aplique mitigación inmediata.
- Reconozca/limpie el evento en UI cuando esté estable.