Inicio rápido: ruta de despliegue por WebUI

Use esta página para pasar de la instalación del paquete a un piloto seguro con la menor cantidad posible de ambigüedad.

Siga esta página en orden:

  1. Complete la base común de instalación.

  2. Abra la WebUI y cree el primer usuario administrador si hace falta.

  3. Use Complete Setup para elegir de dónde vendrán la topología y los suscriptores.

  4. Pase la verificación de salud de 10 minutos.

  5. Comience con tráfico piloto limitado antes de ampliar el despliegue.

¿Necesita definiciones de términos clave? Vea el Glosario.

1) Base común de instalación

Complete esto una sola vez antes de intentar regular tráfico en producción:

  1. Revise arquitectura y dimensionamiento:

  1. Prepare el host y el sistema operativo:

  1. Configure cómo pasará el tráfico por el equipo LibreQoS:

  1. Instale LibreQoS (.deb recomendado):

cd /tmp
sudo apt-get update
sudo apt-get upgrade
wget https://download.libreqos.com/libreqos_1.5-RC2.202510052233-1_amd64.deb
sudo apt install ./libreqos_1.5-RC2.202510052233-1_amd64.deb

Usar /tmp evita problemas de permisos con .deb locales cuando apt no puede leer un paquete guardado en un directorio home privado con el usuario _apt.

Hotfix de Ubuntu 24.04 si la instalación del .deb se detiene

En hosts Ubuntu 24.04 afectados que usan systemd-networkd, la instalación del .deb puede detenerse y mostrar un mensaje requiriendo el hotfix. Esto es esperado.

Si eso ocurre, ejecute:

sudo /opt/libreqos/src/systemd_hotfix.sh install
sudo reboot

El instalador del hotfix configura el repositorio APT firmado de LibreQoS en https://repo.libreqos.com, instala el conjunto parchado de paquetes systemd de Noble y fija esos paquetes para futuras actualizaciones. De forma predeterminada, selecciona la versión actual del hotfix desde ese repositorio. Si Soporte de LibreQoS te indica que tu paquete instalado es anterior a v2.2, usa este comando de recuperación en su lugar:

sudo HOTFIX_PACKAGE_VERSION=255.4-1ubuntu9999+libreqos1 /opt/libreqos/src/systemd_hotfix.sh install
sudo dpkg --configure -a
sudo reboot

Después del reinicio, reanude la instalación:

cd /tmp
wget https://download.libreqos.com/libreqos_1.5-RC2.202510052233-1_amd64.deb
sudo apt install ./libreqos_1.5-RC2.202510052233-1_amd64.deb

2) Abra la WebUI y complete el primer inicio de sesión

  1. Abra la WebUI en http://your_shaper_ip:9123.

  2. Si todavía no existen usuarios de WebUI, LibreQoS redirige a first-run.html.

  3. Cree el usuario administrador inicial si se lo pide.

  4. Inicie sesión y confirme que carga el Dashboard.

Opcional: si los operadores necesitan HTTPS, habilite Configuration -> SSL Setup después de iniciar sesión, o active la misma opción durante la configuración inicial. Vea HTTPS opcional con Caddy.

En este punto, que la WebUI responda no demuestra todavía que LibreQoS ya esté listo para hacer shaping de suscriptores.

Si Scheduler Status muestra Setup Required, eso es normal hasta que elija una fuente de topología y publique datos válidos de shaping.

3) Use Complete Setup para elegir la fuente de topología

Después de poder iniciar sesión, abra Complete Setup.

Esta página es donde la mayoría de los ISP deben tomar la siguiente decisión. Elija una sola fuente de verdad para los cambios permanentes de shaping:

Si esto describe su caso

Use esta ruta

Dónde deben hacerse los cambios permanentes

Usa un CRM/NMS soportado como UISP, Splynx, VISP, Netzur, Powercode, Sonar o WispGate

Integración incluida

Su sistema de integración y su configuración de LibreQoS

Ya tiene su propio importador interno

Importador personalizado

Su script o proceso externo

Quiere mantener los archivos manualmente de forma intencional

Archivos manuales

network.json y ShapedDevices.csv

Regla: elija un solo lugar para los cambios permanentes. No mezcle ediciones manuales con refrescos programados de integración salvo que realmente quiera esa complejidad.

Integración incluida

Esta es la ruta recomendada para la mayoría de los ISP.

Haga esto ahora:

  1. Abra desde Complete Setup la página de su proveedor.

  2. Guarde la configuración de la integración.

  3. Ejecute la sincronización inicial o espere la primera importación programada.

  4. Vuelva a Scheduler Status y confirme que LibreQoS ya no está esperando la configuración inicial.

Siguiente:

Importador personalizado

Elija esta opción solo si otro proceso interno ya escribe archivos compatibles con LibreQoS.

Haga esto ahora:

  1. Configure el comportamiento compartido de topología en Integration - Common.

  2. Publique network.json y ShapedDevices.csv desde su propio proceso.

  3. Use topology.compile_mode = "full" si los circuitos deben moldearse bajo la jerarquía nombrada por Parent Node en network.json.

  4. Recargue o espere al scheduler para que LibreQoS valide y use esos archivos.

No use topology.compile_mode = "flat" si espera que los valores Parent Node de ShapedDevices.csv creen colas superiores de shaping. En modo flat, LibreQoS asigna intencionalmente los circuitos a colas generadas por CPU, como Generated_PN_1.

Siguiente:

Archivos manuales

Elija esta opción solo si quiere que LibreQoS mantenga directamente esos archivos.

Haga esto ahora:

  1. Construya network.json.

  2. Construya ShapedDevices.csv.

  3. Configure topology.compile_mode = "full" si la columna Parent Node debe moldear bajo los nodos nombrados en network.json.

  4. Manténgalos con los editores de WebUI o con su flujo basado en archivos.

  5. Confirme que el scheduler acepta los datos y que aparece la topología esperada.

Use flat solo cuando quiera colas generadas por CPU en vez de colas padre basadas en jerarquía.

Siguiente:

4) Verificación de salud de 10 minutos

Después de terminar Complete Setup y de que su fuente elegida haya publicado datos válidos, ejecute:

sudo systemctl status lqosd lqos_scheduler
journalctl -u lqosd -u lqos_scheduler --since "10 minutes ago"

Confirme:

  • El Dashboard carga.

  • lqosd y lqos_scheduler están activos.

  • Scheduler Status ya no muestra Setup Required.

  • Scheduler Status está saludable, o muestra trabajo activo esperado sin errores de validación ni de arranque.

  • No aparecen problemas urgentes o fatales de inicio en los logs.

  • La topología o la lista esperada de suscriptores/dispositivos aparece en WebUI.

Si esto falla, vaya a Solución de problemas antes de pasar tráfico piloto.

5) Comience con un piloto limitado

No empiece con un despliegue inline amplio.

Empiece con un piloto pequeño y confirme:

  • un suscriptor o dispositivo de prueba hace shaping como se espera

  • aparecen los nodos padre y la profundidad de jerarquía esperados

  • Scheduler Status se mantiene saludable después de los refrescos

  • no aparecen nuevos errores urgentes en logs después de los primeros ciclos

Amplíe solo después de tener una base conocida y estable.

6) Errores comunes al inicio

  • Suponer que Dashboard loads significa que el shaping ya está listo.

  • Ignorar Setup Required y asumir que el scheduler ya está regulando clientes.

  • Mezclar datos controlados por integración con ediciones manuales de archivos.

  • Cambiar demasiados detalles de topología antes de una verificación limpia.

  • Empezar un despliegue amplio antes de validar un piloto pequeño.

7) El día 1 termina cuando

  • Puede iniciar sesión correctamente.

  • El Dashboard carga.

  • Complete Setup quedó terminado para el flujo elegido.

  • Scheduler Status ya no muestra Setup Required.

  • No quedan problemas urgentes o fatales de arranque.

  • Aparece la topología o la lista de suscriptores esperada.

  • Un suscriptor o dispositivo piloto se comporta como se espera.

8) Páginas relacionadas