BotBrowser headless en Ubuntu: configuración del servidor

Fallos comunes de configuración

Ejecutar sin Xvfb

El modo headless nativo puede ejecutarse sin Xvfb. Utiliza Xvfb cuando la carga dependa de X11, necesite una pantalla virtual o ya haya sido validada con esa ruta. En ambos casos, revisa páginas, medios y capturas con el backend gráfico de destino antes de fijar la configuración de producción.

Paquetes de fuentes faltantes

Ubuntu Server incluye soporte tipográfico mínimo. Instala los paquetes documentados y revisa páginas representativas para detectar caracteres ausentes, etiquetas recortadas, cambios de línea y paginación. Conserva el conjunto aprobado en la imagen del servidor.

Profundidad de pantalla incorrecta

Si eliges Xvfb, usa dimensiones y profundidad de color verificadas. El ejemplo emplea 24 bits; la configuración final debe coincidir con la referencia del despliegue.

Ejecutar como root sin parámetros de sandbox

El sandbox de BotBrowser requiere capacidades específicas del kernel. En contenedores Docker o al ejecutar como root, siga la guía de despliegue para configurar los permisos y el sandbox.

Comportamiento de la versión

BotBrowser admite despliegues sin interfaz en servidores. El perfil coordina la plataforma, las fuentes y el comportamiento gráfico, mientras que el servidor debe proporcionar bibliotecas y un backend gráfico compatibles con la carga. Valida páginas, medios y capturas en los hosts de producción en lugar de asumir resultados idénticos entre configuraciones distintas.

Xvfb es una ruta gráfica opcional. El servidor de pantalla y DISPLAY solo son necesarios cuando el despliegue utiliza una pantalla virtual X11.

Instalación y lanzamiento

Paso 1: Instalar dependencias del sistema

sudo apt-get update && sudo apt-get install -y \
  wget ca-certificates fonts-liberation \
  libasound2 libatk-bridge2.0-0 libatk1.0-0 \
  libcups2 libdbus-1-3 libdrm2 libgbm1 \
  libgtk-3-0 libnspr4 libnss3 \
  libxcomposite1 libxdamage1 libxrandr2 \
  xdg-utils xvfb

Para Ubuntu 24.04, algunos nombres de paquetes han cambiado. Si encuentras errores, ejecuta:

sudo apt-get install -y \
  libasound2t64 libatk-bridge2.0-0 libatk1.0-0 \
  libcups2t64 libgbm1 libgtk-3-0t64 \
  libnss3 libxcomposite1 libxdamage1 \
  libxrandr2 xvfb fonts-liberation xdg-utils

Paso 2: Iniciar Xvfb cuando sea necesario

Para pruebas inmediatas:

Xvfb :10 -screen 0 1920x1080x24 &
export DISPLAY=:10.0

Para producción, crea un servicio systemd:

# /etc/systemd/system/xvfb.service
[Unit]
Description=X Virtual Frame Buffer
After=network.target

[Service]
Type=simple
ExecStart=/usr/bin/Xvfb :10 -screen 0 1920x1080x24
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Habilita e inicia el servicio:

sudo systemctl daemon-reload
sudo systemctl enable xvfb
sudo systemctl start xvfb

Paso 3: Instalar BotBrowser

# Sustituye los marcadores por el recurso Linux de la página de versiones
curl -fL -o botbrowser.tar.gz \
  "https://github.com/botswin/BotBrowser/releases/download/<release-tag>/<linux-archive>"

# Extraer en /opt
sudo mkdir -p /opt/botbrowser
sudo tar -xzf botbrowser.tar.gz -C /opt/botbrowser/
sudo chmod +x /opt/botbrowser/chrome

# Verificar la instalación
DISPLAY=:10.0 /opt/botbrowser/chrome --version

Paso 4: Descargar perfiles

sudo mkdir -p /opt/botbrowser/profiles
sudo install -m 600 /ruta/al/<perfil-compatible>.enc \
  /opt/botbrowser/profiles/profile.enc

Paso 5: Prueba de lanzamiento

Usa la tarea mínima de Playwright del Paso 6 para probar la ruta de inicio completa. Ejecútala con la cuenta de servicio, el perfil, el directorio de trabajo y la ruta gráfica previstos para producción. Añade DISPLAY=:10.0 únicamente en la configuración con Xvfb. La prueba debe abrir la página aprobada, completar una acción pequeña y cerrarse con normalidad.

Paso 6: Integración con Playwright

npm install playwright-core

const { chromium } = require('playwright-core');

(async () => {
  const browser = await chromium.launch({
    executablePath: '/opt/botbrowser/chrome',
    args: [
      '--disable-setuid-sandbox',
      '--bot-profile=/opt/botbrowser/profiles/profile.enc',
      '--proxy-server=socks5://user:pass@proxy.example.com:1080',
    ],
    headless: true,
  });

  const context = await browser.newContext();
  const page = await context.newPage();
  await page.goto('https://example.com');
  console.log('Title:', await page.title());
  await browser.close();
})();

Ejecuta con la variable de pantalla:

DISPLAY=:10.0 node script.js

Paso 7: Servicio systemd para automatización

Para tareas en segundo plano de automatización persistentes:

# /etc/systemd/system/botbrowser-worker.service
[Unit]
Description=BotBrowser Automation Worker
After=xvfb.service
Requires=xvfb.service

[Service]
Type=simple
Environment=DISPLAY=:10.0
WorkingDirectory=/opt/scripts
ExecStart=/usr/bin/node /opt/scripts/worker.js
Restart=always
RestartSec=10
User=botbrowser
Group=botbrowser

[Install]
WantedBy=multi-user.target

Gestionar una carga por servicio

Asigna a cada unidad una carga definida y un directorio de datos. La aplicación debe controlar el inicio y el cierre del navegador para que el supervisor reciba un estado claro. También resulta más sencillo asociar los logs, los límites de recursos y la política de reinicio con la carga correspondiente.

Crea unidades separadas cuando las aplicaciones tengan calendarios de publicación, requisitos gráficos o límites de seguridad diferentes. Evita los bucles de shell que inician varios perfiles. Esos bucles dificultan saber qué tarea falló y pueden dejar procesos activos después de terminar el proceso principal.

Deja la recuperación en manos del gestor de servicios. Configura una pausa entre intentos y un límite de inicios para que un perfil no válido o una imagen dañada no provoquen un ciclo continuo.

Verificación

Después de completar la configuración, verifica que todo funcione:

# Verificar que Xvfb esté en ejecución
systemctl status xvfb

# Verificar que la pantalla sea accesible
DISPLAY=:10.0 xdpyinfo | head -5

# Verificar que las dependencias de BotBrowser estén satisfechas
ldd /opt/botbrowser/chrome | grep "not found"

# Iniciar y verificar la navegación
DISPLAY=:10.0 node -e "
const { chromium } = require('playwright-core');
(async () => {
  const b = await chromium.launch({
    executablePath: '/opt/botbrowser/chrome',
    args: ['--bot-profile=/opt/botbrowser/profiles/profile.enc'],
    headless: true,
  });
  const p = await (await b.newContext()).newPage();
  await p.goto('https://example.com');
  console.log('Navigation completed:', await p.title());
  await b.close();
})();
"

El navegador debe iniciar sin abrir una ventana visible de orientación, completar la navegación y cerrarse de forma limpia. Conserve la salida del terminal y el código de salida con los registros del despliegue.

Estado de servicio y controles de salud

Define el estado listo a partir de la carga y no solo de la existencia del proceso. Una comprobación útil confirma que el servicio aceptó su configuración, creó una sesión, abrió una página aprobada y completó una acción pequeña. Debe terminar con rapidez cuando cualquiera de esos pasos falle.

Separa este control del tráfico de clientes. Usa una cuenta dedicada o una página pública sin datos personales. El resultado solo necesita indicar si la aplicación puede iniciar, navegar y cerrarse correctamente.

Distingue la salud de inicio de la salud continua. La primera protege despliegues y reinicios. La segunda debe cubrir avance de cola, finalización reciente de tareas, estado de salida, espacio disponible, presión de memoria y estado del servicio de pantalla cuando sea necesario. Un proceso activo puede haber dejado de avanzar.

Cuando falle el control, retira el worker de nuevas asignaciones antes de reiniciarlo. Conserva el último paso completado y devuelve el directorio de datos a un estado aprobado. Los reintentos no deben ocultar una configuración persistentemente defectuosa.

Logs y recuperación ante fallos

Envía la salida de la aplicación y del navegador al destino normal de logs. Incluye la revisión del servicio, la versión de BotBrowser, el paquete de perfil, la imagen y el identificador de tarea. Excluye contenido de páginas, credenciales, secretos de proxy y registros de clientes.

Rota logs y artefactos antes de que agoten el disco. Conserva suficiente historial para comparar la versión candidata con la última aprobada y aplica después la política habitual de retención y privacidad.

Clasifica los fallos según la acción necesaria. Una configuración requiere corregir el servicio o el perfil. Una dependencia requiere reparar la imagen. La presión de recursos requiere revisar la carga o la capacidad. Los fallos de aplicación corresponden al responsable de la aplicación.

Prueba la recuperación en staging. Detén el servicio durante una tarea autorizada, reinicia el host y simula la ausencia temporal de una dependencia. Confirma que la supervisión identifica el servicio, respeta el límite de reinicios y recupera un estado aprobado.

Control de cambios de la imagen

Trata la imagen del sistema, BotBrowser, el perfil, la unidad de servicio y la aplicación como una combinación registrada. Un cambio en cualquier capa puede afectar el inicio, el renderizado, los medios o el consumo de recursos.

Pasa las actualizaciones del sistema por la misma ruta de staging que la aplicación. Los paquetes de idioma, bibliotecas gráficas, runtime de contenedores y políticas de seguridad deben revisarse con una tarea representativa.

Promueve cambios en grupos pequeños. Mantén disponible la combinación anterior y documenta el orden de reversión. La reversión debe recuperar una combinación completa aprobada, no mezclar un navegador antiguo con un perfil o servicio sin revisar.

Inicio headless y validación del perfil

BotBrowser 150.0.7871.46 no abre una ventana visible para comunicar problemas de perfil durante un inicio headless. Un paquete ausente, no válido, caducado o incompatible con la versión aparece en la salida del terminal y el proceso sigue la ruta normal de fallo de inicio. Los lanzamientos con interfaz conservan la orientación visible para el usuario.

Las tareas de Playwright, systemd y contenedores deben conservar stdout, stderr y el código de salida. Comprueba el paquete de perfil antes de crear la primera página. Un servicio saludable debe crear una sesión, completar la tarea mínima aprobada y cerrarse de forma limpia.

En cargas concurrentes, inicie las tareas en segundo plano por lotes y cierre páginas, contextos y procesos al terminar cada tarea. Dimensione memoria, /dev/shm y descriptores de archivo según las páginas reales. El número de procesos por sí solo no describe el consumo de una carga de producción.

Reglas operativas

Configura DISPLAY según la ruta gráfica. Añádelo al servicio solo cuando utilices Xvfb u otra pantalla X11.

Usa profundidad de color de 24 bits para Xvfb. Profundidades menores producen salida de renderizado incorrecta.

Monitorea el uso de disco. BotBrowser escribe volcados de fallos y datos de caché en --user-data-dir. Configura la rotación de logs o limpieza periódica para prevenir el agotamiento del disco.

Mantén las dependencias actualizadas. Ejecuta apt-get upgrade periódicamente. Los desajustes en versiones de bibliotecas pueden causar problemas sutiles de renderizado.

Establece límites de recursos. Usa MemoryLimit y CPUQuota de systemd para prevenir que instancias descontroladas consuman todos los recursos del servidor.

Aprobación de la versión

Aprueba la imagen del servidor y la versión de BotBrowser como una sola combinación. Registra Ubuntu, BotBrowser, el paquete de perfil, la ruta gráfica, la elección de Xvfb, el servicio y la aplicación. Ejecuta una tarea representativa tras un arranque en frío, un reinicio del servicio y un reinicio del host.

Revisa una página normal, otra con mucho texto, una captura o documento y contenido multimedia cuando corresponda. Aumenta la concurrencia de forma gradual y conserva margen para el sistema operativo. Comprueba también que el supervisor registre un fallo controlado y devuelva el worker a un estado conocido. Promueve la imagen solo cuando todas las clases de host previstas hayan pasado.

Preguntas frecuentes

¿Funciona BotBrowser en Ubuntu 24.04?

Sí. Algunos nombres de paquetes han cambiado (por ejemplo, libasound2 se convirtió en libasound2t64). El comando de instalación alternativo en el Paso 1 cubre estos cambios.

¿Puedo usar una resolución de Xvfb más alta?

Sí. Puedes configurar Xvfb :10 -screen 0 2560x1440x24 o cualquier resolución que necesites. Haz que coincida con la resolución de pantalla del perfil para mejores resultados.

¿Necesito una GPU en el servidor?

No. BotBrowser usa los valores de GPU del perfil para el reporte de huella digital. La GPU real del servidor (o su ausencia) no afecta la salida de la huella digital.

¿Por qué no simplemente usar --headless=new sin Xvfb?

Puedes usar --headless=new sin Xvfb. Activa Xvfb y DISPLAY cuando la carga dependa de X11 o la referencia del equipo se haya validado con una pantalla virtual. Revisa el renderizado, los medios y las capturas en ambos casos.

¿Por qué no aparece una ventana cuando falla un inicio headless?

El modo headless escribe la orientación de inicio en la salida del terminal en lugar de abrir una ventana. Conserva esa salida en los logs y corrige el perfil o el host antes de reintentar.

¿Cuántas instancias puedo ejecutar por servidor?

Depende del host y de la carga. Mide páginas representativas, conserva margen para el sistema y reduce la concurrencia cuando la memoria, el procesador o el intercambio muestren presión sostenida.

¿Cómo verifico las bibliotecas faltantes?

Ejecuta ldd /opt/botbrowser/chrome | grep "not found". Cualquier biblioteca listada como "not found" necesita ser instalada. Usa apt-file search libname.so para encontrar el paquete que proporciona una biblioteca específica.

¿Puedo ejecutar BotBrowser en servidores Ubuntu basados en ARM?

BotBrowser proporciona builds de Linux para x86_64. El soporte para ARM depende de la versión específica. Consulta la página de publicaciones de GitHub para las arquitecturas disponibles.

¿Cómo actualizo BotBrowser?

Prepara la nueva versión con su paquete de perfil correspondiente. Revisa la configuración del servicio, las dependencias, la ruta gráfica y la carga representativa antes de promoverla. Mantén disponible la combinación anterior hasta completar el periodo normal de observación.

Decisión de despliegue

Ejecutar BotBrowser en Ubuntu requiere instalar las dependencias, elegir el backend gráfico y gestionar el entorno del servicio. Xvfb y DISPLAY solo se usan en cargas que elijan una pantalla virtual X11. Mide la capacidad con páginas reales y recursos del host.

Para despliegues en contenedores, consulta Docker. Para ajustar el rendimiento, consulta Rendimiento en producción. Para parámetros habituales, consulta Recetas de línea de comandos.