部署2026年1月21日

Ubuntu Headless 浏览器设置：完整服务器指南

Q: BotBrowser 是否支持 Ubuntu 24.04？

支持。某些包名称已更改（例如 libasound2 变为 libasound2t64 ）。步骤 1 中的替代安装命令涵盖了这些更改。

Q: 能否使用更高的 Xvfb 分辨率？

可以。你可以设置 Xvfb :10 -screen 0 2560x1440x24 或任何需要的分辨率。最好匹配配置文件的屏幕分辨率。

Q: 为什么不直接用 --headless=new 而不用 Xvfb？

可以直接使用 --headless=new 。当目标工作负载依赖 X11 或团队基线已验证 Xvfb 时，再启用 Xvfb 和 DISPLAY 。两种路径都应验证页面渲染、媒体和截图。

Q: 如何检查缺少的库？

运行 ldd /opt/botbrowser/chrome | grep "not found" 。任何列为 "not found" 的库都需要安装。使用 apt-file search libname.so 查找提供特定库的包。

如何在 Ubuntu 上设置 headless 浏览器自动化，包括 Xvfb、系统依赖、systemd 服务和生产配置。

文档中心

想直接看维护中的产品文档？

这篇文章对应的主题已经有文档中心页面。需要规范流程、当前参数和长期参考时，优先看 docs。

打开对应文档浏览部署

生产基准

在 headless Ubuntu 服务器上运行 BotBrowser 是大多数生产部署的基础。服务器没有物理显示器，GPU 驱动与桌面系统不同，BotBrowser 依赖的部分系统库在最小化服务器镜像上默认未安装。正确处理这些细节是稳定生产环境与间歇性崩溃之间的区别。

本文介绍系统依赖、按工作负载选择 Xvfb（X 虚拟帧缓冲）、使用 systemd 监督服务，以及通过 Playwright 或 Puppeteer 运行 BotBrowser。

为什么 Headless 服务器设置很重要

桌面环境会处理显示管理、图形初始化和字体渲染。最小化的 Ubuntu Server 安装可能缺少浏览器所需的共享库和字体包。只有选用 X11 图形路径的工作负载才需要显示服务器。

设置不完整时，可能出现 "cannot open display"、空白截图、缺字或媒体播放不稳定等现象。应把这些现象视为发布阻断问题，并在投入生产前修正宿主配置。

DISPLAY 只在部署选择 Xvfb 或其他 X11 显示服务时设置。原生 headless 路径不需要为了启动浏览器而强制配置 Xvfb。请使用目标页面、图形后端和媒体流程验证所选方案。

显示与系统要求

Xvfb（X 虚拟帧缓冲）

Xvfb 提供一个虚拟显示服务器，实现 X11 协议而不需要物理显示硬件。BotBrowser 连接到 Xvfb 后，可以正常完成图形初始化。

关键配置参数：

显示号（:10）：任意标识符。使用 :10 避免与桌面安装可能使用的 :0 冲突。
屏幕规格（1920x1080x24）：宽度、高度和颜色深度。24 位颜色深度对于准确渲染是必需的。
DISPLAY 环境变量（DISPLAY=:10.0）：使用 Xvfb 时，为启动浏览器的服务和脚本设置同一显示号。

浏览器系统依赖

BotBrowser 使用用于渲染、音频、网络和辅助功能的共享库。桌面 Ubuntu 通常已经包含大部分依赖，最小服务器镜像则需要明确安装。

关键类别：

图形：libdrm2, libgbm1, libxcomposite1, libxdamage1, libxrandr2 用于显示合成
UI 工具包：libgtk-3-0, libatk-bridge2.0-0, libatk1.0-0 用于辅助功能和部件渲染
安全：libnss3, libnspr4 用于 TLS 和证书处理
音频：libasound2 用于音频子系统初始化（即使不播放音频）
字体：fonts-liberation 用于基本字体可用性
桌面集成：xdg-utils 用于 MIME 类型处理

无界面服务器部署 BotBrowser 配合虚拟显示服务和所需 Linux 系统库运行。 Headless 服务器架构 BotBrowser BotBrowser + 配置文件 Headless 模式 Xvfb :10 虚拟显示 1920x1080x24 系统库 GTK, NSS, GBM 字体、音频 Ubuntu 22.04 LTS (Headless) 环境中设置 DISPLAY=:10.0

常见设置问题

不使用 Xvfb 运行

原生 headless 可以在不启动 Xvfb 的情况下运行。Xvfb 适用于依赖 X11、需要虚拟显示器或已按该路径验证的工作负载。两种方式都应在目标 Linux 图形后端上完成页面、媒体和截图验证，再选定生产配置。

缺少字体包

Ubuntu Server 只提供基础字体支持。安装文档要求的字体包，再用代表性页面检查缺字、标签裁切、换行和文档分页。把批准后的包集合固定在服务器镜像中。

不正确的显示深度

如果选择 Xvfb，请使用经过验证的显示尺寸和色深。示例采用 24 位色深，实际值应与部署基线一致。

以 Root 身份运行且未设置沙箱标志

BotBrowser 的沙箱需要特定的内核能力。在 Docker 容器中或以 root 身份运行时，沙箱可能无法正常启动。在这些环境中应按照部署文档配置所需权限。

发布行为

BotBrowser 支持无界面服务器部署。配置文件协调平台、字体和图形行为，服务器仍需提供与目标工作负载兼容的系统库和图形后端。请在生产所用主机上验证页面渲染、媒体和截图，不要假设不同主机配置会自动产生相同结果。

Xvfb 是可选图形路径。只有采用 X11 虚拟显示方案时才需要运行显示服务器并设置 DISPLAY。

BotBrowser 150.0.7871.46 在无界面模式下不会打开可见的配置提示窗口。缺少、无效、过期或版本不匹配的配置状态会写入终端输出，随后浏览器按启动失败路径退出。桌面有界面启动仍保留面向用户的图形提示。

这对 systemd、容器编排和工作节点管理更清楚。健康检查应同时观察进程退出状态、终端日志和获准任务结果，不应等待服务器上不会出现的窗口。配置文件包必须与 BotBrowser 主版本匹配，并在创建第一个页面前完成验证。

容器日志中可能出现与桌面服务或图形服务有关的提示。判断部署是否健康时，应确认会话能够创建、获准任务能够完成，并且选定的图形后端与系统库可用。资源紧张时，应先降低新任务接收速度并检查宿主压力。

安装与启动

步骤 1: 安装系统依赖

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

对于 Ubuntu 24.04，某些包名称已更改：

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

步骤 2：按需启动 Xvfb

用于即时测试：

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

生产环境创建 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

启用并启动服务：

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

步骤 3: 安装 BotBrowser

# 把占位符替换成发布页面中匹配的 Linux 资源
curl -fL -o botbrowser.tar.gz \
  "https://github.com/botswin/BotBrowser/releases/download/<release-tag>/<linux-archive>"

# 解压到 /opt
sudo mkdir -p /opt/botbrowser
sudo tar -xzf botbrowser.tar.gz -C /opt/botbrowser/
sudo chmod +x /opt/botbrowser/chrome

# 验证安装
DISPLAY=:10.0 /opt/botbrowser/chrome --version

步骤 4: 下载配置文件

sudo mkdir -p /opt/botbrowser/profiles
sudo install -m 600 /path/to/<matching-profile>.enc \
  /opt/botbrowser/profiles/profile.enc

步骤 5: 测试启动

使用步骤 6 的最小 Playwright 任务检查完整启动路径。以生产环境计划使用的服务账号、配置文件包、工作目录和图形路径运行。只有 Xvfb 配置才添加 DISPLAY=:10.0。检查应打开获准页面、完成一个小型应用动作并正常关闭。

步骤 6: 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();
})();

使用 display 变量运行：

DISPLAY=:10.0 node script.js

步骤 7: 用于自动化的 systemd 服务

# /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

每个服务管理一个工作负载

每个服务单元只负责一个明确的工作负载和一个数据目录。应用负责浏览器的启动与关闭，使监督程序能够获得清晰的进程状态。日志、资源限制和重启策略也能准确归属到对应工作负载。

发布周期、图形要求或安全边界不同的应用，应使用独立服务。不要用 shell 循环启动多个配置文件。循环会掩盖具体失败任务，并可能在父进程退出后留下子进程。

把恢复策略交给服务管理器。设置重试间隔和启动次数限制，避免无效配置文件或损坏镜像形成持续重启。配置修复前，失败状态应对监控保持可见。

验证

完成设置后验证一切正常：

# 检查 Xvfb 是否运行
systemctl status xvfb

# 检查显示是否可访问
DISPLAY=:10.0 xdpyinfo | head -5

# 检查 BotBrowser 依赖是否满足
ldd /opt/botbrowser/chrome | grep "not found"

# 启动并验证页面导航
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();
})();
"

浏览器应能打开代表性页面、完成导航并正常退出。把终端输出和退出状态保存在部署日志中。