Ubuntu 服务器上的 Headless BotBrowser 设置

BotBrowser 可以为经过授权的 headless 工作负载提供受控浏览器运行环境，但不会加固主机、授予权限，也不能证明应用结果。本指南把 Ubuntu 与 Xvfb 的主机基线、浏览器行为、配置文件中的敏感数据和应用健康状态分开说明。

摘要

只安装必要的 Ubuntu 库，使用固定的 Xvfb 显示和非特权服务账户，并验证一个用户可见的小任务。不要把配置文件、凭据、页面内容或客户标识符写入日志。主机、浏览器版本、配置文件或图形后端变化后，要重复相同检查。

内容导航

• 主机基线与虚拟显示
• 安装与启动
• 验证、健康与恢复
• 变更控制与版本批准
• 关于 headless Ubuntu 主机的问题
• 部署决定

主机基线与虚拟显示

在 headless Ubuntu 服务器上运行 BotBrowser 是大多数生产部署的基础。服务器没有物理显示器，图形驱动与桌面系统不同，而浏览器依赖的系统库在最小化服务器镜像中默认并未安装。把这些细节处理好，环境才会稳定，否则就会出现难以诊断的间歇性故障。

生产环境的 Ubuntu 主机需要必要的系统库、稳定的显示策略、受监管的浏览器服务，以及对配置文件和用户数据的明确归属。这些要求适用于由 Playwright 或 Puppeteer 驱动的无人值守 BotBrowser 会话，并引出针对每一类主机的版本批准流程。

桌面环境会自动处理显示管理、图形初始化和字体渲染。最小化服务器镜像缺少浏览器工作负载使用的许多共享库和字体包，也没有任何显示。BotBrowser 部署文档指出，在 headless 服务器上，即使以 headless 模式运行，BotBrowser 也需要虚拟显示。

不完整的设置可能产生明显的故障，例如 "cannot open display"，也可能产生不易察觉的问题，例如空白截图、缺失字符或不稳定的媒体播放。请把每一种结果都视为版本检查失败，并在投入生产前修正主机。

请在每台主机上规划虚拟显示。文档以 :10.0 上的 Xvfb 显示为起点，并说明每个 BotBrowser 进程都必须设置 DISPLAY=:10.0。在该显示上运行 Xvfb，在每个浏览器服务中设置 DISPLAY，并明确服务之间的依赖关系。显示本身不能取代验证：批准前，请在每一类主机上检查有代表性的渲染、媒体和截图。

Xvfb（X 虚拟帧缓冲）

Xvfb 是一种虚拟显示服务器，无需显示硬件即可实现 X11 协议。BotBrowser 即使在 headless 模式下也需要 X11 显示，在服务器上由 Xvfb 提供。

主要配置参数：

• 显示编号（:10）：任意标识符。使用 :10 可避免与桌面安装可能使用的 :0 冲突。
• 屏幕规格（1920x1080x24）：宽度、高度和色深。请用有代表性的截图和渲染工作负载验证所选色深。
• DISPLAY 环境变量（DISPLAY=:10.0）：为每个 BotBrowser 进程设置，包括每个服务单元和每次手动测试。

浏览器系统依赖

BotBrowser 使用共享库来完成渲染、音频、网络和无障碍功能。桌面版 Ubuntu 通常已包含其中大部分。在最小化服务器镜像上，请显式安装它们。

关键类别如下：

• 图形：libdrm2、libgbm1、libxcomposite1、libxdamage1、libxrandr2，用于显示合成
• 界面工具包：libgtk-3-0、libatk-bridge2.0-0、libatk1.0-0，用于无障碍和控件
• 安全：libnss3、libnspr4，用于 TLS 和证书处理
• 音频：libasound2，用于音频初始化，即使不播放声音也需要
• 字体：fonts-liberation，提供基本字体
• 桌面集成：xdg-utils，用于 MIME 类型处理
• 辅助库：libcups2、libdbus-1-3、libxkbcommon0、libpango-1.0-0、libpangocairo-1.0-0、libwayland-client0、libwayland-server0、libatspi2.0-0、libxss1

步骤 1 会安装完整列表。安装后，运行验证部分中的 ldd 检查，找出仍然缺失的库。

为什么 headless 模式仍需要显示

部署文档指出，BotBrowser 即使在 --headless 模式下也需要 X11 显示，因此没有显示的服务器可能因 "cannot open display" 之类的错误而失败。请把虚拟显示视为主机基线的一部分，而不是可选服务。

不要为了节省资源而移除显示服务。如果后续版本记录了另一条受支持的启动路径，请先重新查阅文档，并在每一类主机上验证该路径，然后再修改基线。

缺少字体包

没有显示时实际会发生什么

上一节解释了为什么虚拟显示仍是受支持 headless 部署的一部分。值得把这条要求与「没有显示时浏览器会做什么」分开看，因为两者结果不同，而且差异可以测量。下面的观察来自同一台主机：基于 Debian 的镜像，Chromium 的共享库全部解析成功，NSS、ATK、CUPS、GBM、ALSA 相关库都在，配合一个固定的探针页，用来报告是否成功创建了 WebGL 上下文。

启动条件	WebGL 上下文	报告的渲染器	是否存在显示 socket
不设显示变量	已创建	SwiftShader（软件）	否
显示变量指向未运行的虚拟显示服务	未创建	无	否
不设显示变量，重复两次	两次都创建	SwiftShader（软件）	否

中间那一行最让运维意外。把进程指向一个没有服务在监听的显示编号，并不会退回到软件渲染；上下文干脆初始化失败，依赖 WebGL 的页面记录到的是「功能缺失」，而不是「变慢」。第一行和第三行说明：完全不带显示变量的 headless 启动仍会通过软件后端渲染，所以一个没有虚拟显示服务的容器在页面加载上可能看起来正常，行为却与受支持的配置不同。

要看结果，不要看意图。只确认页面加载成功的健康检查，在第一行和第二行都会通过，因此无法告诉你部署走了哪条路径。应当探测真正依赖的功能，记录是哪个渲染器应答的，再与原本打算运行的配置对比。

有两条限制。上面的渲染器字符串是本机软件后端的名字，描述的是这个镜像而不是所有服务器；带 GPU 驱动的主机可能报告别的适配器。这些内容也不能替代上一节的受支持配置，那套配置把真实的虚拟显示与部署所需的依赖集配对使用。

Ubuntu Server 自带的字体支持很少。请安装文档中列出的软件包，然后检查有代表性的页面，查看是否有缺失字符、被裁剪的标签、换行变化和文档分页问题。把已批准的软件包集合保留在服务器镜像中，使可比较的 worker 产生稳定的可见结果。

不正确的显示深度

请从 24 位屏幕开始，例如 Xvfb :10 -screen 0 1920x1080x24。在批准部署之前，用有代表性的渲染和截图流程验证所选色深。

以 root 运行与 sandbox 错误

当服务以 root 身份或在容器内运行时，Chromium 的 sandbox 可能无法启动。请用非 root 用户运行服务。如果容器需要 sandbox 标志，请遵循部署指南，并测试这一具体组合，而不要在不同环境之间照搬标志。

配置文件、主机与版本行为

BotBrowser 支持 headless 服务器部署。屏幕尺寸、字体和 GPU 信息等指纹属性来自所选配置文件包，而不是服务器硬件，主机则提供系统库和图形后端。请在你计划使用的每一类主机上验证完整配置。

对于可比较的运行，请使用相同的已批准配置文件、浏览器版本、依赖、图形后端和启动策略。驱动、库、媒体支持和工作负载的差异仍可能改变可见输出或容量。

服务器通常没有物理 GPU，因此渲染依赖软件后端。文档比较了通过 ANGLE GL 的 Mesa llvmpipe、SwiftShader 和 Mesa lavapipe，并推荐大多数 Ubuntu 主机使用 llvmpipe。请在版本记录中写明主机类别和图形路径，因为在一类主机上获得批准的运行并不代表另一类也获得批准。

安装与启动

步骤 1：安装系统依赖

sudo apt-get update && sudo apt-get install -y \
  fonts-liberation libasound2 libatk-bridge2.0-0 \
  libatk1.0-0 libatspi2.0-0 libcups2 libdbus-1-3 \
  libdrm2 libgbm1 libgtk-3-0 libnspr4 libnss3 \
  libpango-1.0-0 libpangocairo-1.0-0 libwayland-client0 \
  libwayland-server0 libxcomposite1 libxdamage1 \
  libxkbcommon0 libxrandr2 libxss1 xdg-utils xvfb

在 Ubuntu 24.04 上，部分软件包名称已更改。如果 apt 提示未知软件包，请用 apt-cache search 查找改名后的版本，或从下面这个精简列表开始：

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

在任何 BotBrowser 进程之前，先在显示 :10 上启动 Xvfb，并让每个浏览器 worker 连接到它。

用于即时测试：

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

从 BotBrowser 发布页面下载与你的架构匹配的 Linux 软件包。架构支持取决于具体版本，请在该页面确认。安装指南说明，Ubuntu 二进制文件需要 ENT Plan Tier 1 或更高级别的订阅。

# 安装已下载的软件包
sudo dpkg -i botbrowser_<version>_amd64.deb

# 解决 dpkg 报告的缺失依赖
sudo apt-get install -f

# 验证安装
chromium-browser --version

步骤 4：下载配置文件

使用与已安装浏览器版本匹配的配置文件包。BotBrowser 150 及更新版本的配置文件可通过订阅或支持渠道获得。请让该文件包只能被服务账号读取，示例中的服务账号名为 botbrowser。

sudo mkdir -p /var/lib/botbrowser
sudo install -o botbrowser -g botbrowser -m 600 \
  /path/to/<matching-profile>.enc /var/lib/botbrowser/profile.enc

步骤 5：测试启动

使用步骤 6 中的 Playwright 冒烟任务来测试完整的启动路径。请用准备用于生产的服务账号、配置文件包、工作目录和图形路径运行它，并设置 DISPLAY=:10.0。成功的测试会打开已批准的页面，完成其中的小操作，并正常关闭。

步骤 6：Playwright 集成

npm install playwright-core

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

(async () => {
  const browser = await chromium.launch({
    executablePath: '/usr/bin/chromium-browser',
    args: ['--bot-profile=/var/lib/botbrowser/profile.enc', '--proxy-server=socks5://user:[email protected]: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=:10.0 node script.js

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

对于长期运行的自动化 worker：

# /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=on-failure
RestartSec=10
User=botbrowser
Group=botbrowser

[Install]
WantedBy=multi-user.target

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

让每个服务单元只负责一个明确的工作负载和一个数据目录。应用应自行控制浏览器的启动和关闭，使监管程序看到清晰的进程状态。这样的安排也便于把日志、资源限制和重启策略与产生它们的工作负载对应起来。

当应用的发布节奏、图形要求或安全边界不同时，请创建单独的服务单元。不要在多个配置文件启动外面套一层 shell 循环。循环会掩盖究竟是哪个任务失败，还可能在父进程退出后留下仍在运行的子进程。

重启行为请交给服务管理器处理。设置两次尝试之间的延迟和启动次数上限，避免无效的配置文件或损坏的镜像造成持续的重启循环。在修复根本配置之前，失败的工作负载应一直对监控可见。

验证、健康与恢复

完成设置后，请验证显示、浏览器依赖以及一次 headless 启动：

# 检查 Xvfb 是否在运行
systemctl status xvfb

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

# 检查浏览器依赖是否满足
ldd /usr/bin/chromium-browser | grep "not found"

# 在设置了显示的 headless 模式下启动并验证导航
DISPLAY=:10.0 node -e "
const { chromium } = require('playwright-core');
(async () => {
  const b = await chromium.launch({
    executablePath: '/usr/bin/chromium-browser',
    args: ['--bot-profile=/var/lib/botbrowser/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();
})();
"

浏览器应当在不打开可见提示窗口的情况下启动，完成导航并干净退出。请把终端输出和进程退出码与部署日志一起保存。

故障排查顺序

当 headless Ubuntu 主机能够运行但返回错误渲染时，请按固定顺序检查，让每一步只排除一层原因：显示服务、显示本身、图形渲染器、配置文件包，最后是应用任务。直接跳到应用层会把主机漂移掩盖成一个无关的缺陷报告。

1. 运行 systemctl status xvfb。通过的标准是 active (running)、运行时间稳定，且重启计数没有增长。
2. 运行 DISPLAY=:10.0 xdpyinfo | head -5。通过的标准是输出已批准的尺寸与深度，例如 dimensions: 1920x1080 pixels 和 depth of root window: 24 planes。
3. 运行 DISPLAY=:10.0 glxinfo -B。通过的标准是 OpenGL renderer string 显示已批准的软件渲染器，例如 llvmpipe (LLVM ...)。
4. 读取浏览器会话内的渲染器字符串，并与第 3 步比对。不一致说明启动参数选择的路径与主机默认路径不同。
5. 把 sha256sum /var/lib/botbrowser/profile.enc 与已批准值比对。数值不同说明加载了错误的包，而不是渲染故障。
6. 用相同的显示、配置文件与参数重跑步骤 6 的冒烟任务，并把截图与已批准基线比对。

在第一个失败的步骤停下，先修复该层再重复整个顺序。第 2 步失败就能解释其下所有视觉症状，而调整参数无法救活一个已停止的服务单元。

症状	检查	决定
启动以 "cannot open display" 退出	systemctl status xvfb 与 systemctl is-active xvfb	先修复或重启显示服务，再去改动浏览器参数
页面加载但文字缺少字形	用 fc-list 计数与已批准镜像的包列表比对	视为字体包漂移，重建镜像
Canvas、WebGL 或媒体区域空白	glxinfo -B 的渲染器字符串	让启动参数与已批准后端一致，然后重跑冒烟任务
截图被裁切或缩放	用 xdpyinfo 尺寸与配置文件屏幕尺寸比对	提高 Xvfb 屏幕或修正配置文件选择
同一配置文件在两台主机渲染不同	两台主机的渲染器字符串与 sha256sum 输出	在解释清差异前按主机类别拆分资源池

同一配置文件，两台主机，不同渲染

更难处理的是静默故障。两台主机都返回成功任务，但同一个已批准配置文件在文字、canvas 或视频上渲染不同。进程检查会把两台主机都判为健康，差异只出现在像素比对或操作员报告中。请用三轮排查定位原因，每轮只改变一个输入并固定另外两个。

先查显示。比对两台主机上的 DISPLAY=:10.0 xdpyinfo：尺寸、深度与屏幕数量必须与已批准配置一致。屏幕为 16 位或帧缓冲较小主机会在浏览器绘制之前就缩放或裁切内容。

再查 GPU 后端。比对两台主机上的 glxinfo -B，读取 OpenGL renderer string 与 OpenGL version string。两台都报告 llvmpipe，或一台 llvmpipe、一台 SwiftShader，即使都通过冒烟任务，也属于不同的部署类别。请把后端记入发布记录，让比对可重复。

最后查配置文件。比对两台主机上的 sha256sum /var/lib/botbrowser/profile.enc 与配置文件版本。某台主机加载了旧包，或在为另一个浏览器版本构建的包，会在仍返回 HTTP 200 的同时产生不同的字体、屏幕数值或媒体行为。

当三个输入中有两个一致时，剩余差异就指向第三个，资源池应按主机类别拆分，直到有负责人解释清楚。不要对两者结果取平均，也不要把更快的主机设为参照。

服务就绪与健康检查

就绪状态应由工作负载来定义，而不能仅凭浏览器进程存在就认定。有用的启动检查会确认服务已接受配置、创建了浏览器会话、打开了一个已批准的页面，并完成了一项小的应用操作；例如用 systemctl is-active botbrowser-worker.service 和一个返回 HTTP 200 的 /healthz 请求同时检查服务与会话。任何一步失败时，检查都应迅速停止。

让健康检查与客户流量分开。使用专用的测试账号，或不含个人数据的公开页面。检查结果应说明应用能否启动、导航并干净关闭。

区分启动健康与持续健康。启动健康用于保护部署和重启决策。持续健康应覆盖队列进展、最近完成的任务、进程退出状态、可用磁盘空间、内存压力，以及所需显示服务的状态。worker 可能仍然存活，而其应用已经停止推进，因此仅凭进程运行时间并不足够。

根据正常工作负载为每项检查设定合理的期限。把反复超时视为服务故障，并保留能说明最后完成步骤的应用输出。避免使用过于激进的检查间隔，以免与生产工作争用资源，或反复启动完整的浏览器会话。

检查失败时，先把 worker 从新任务分配中移除，再重启。只有应用能够安全完成时，才允许当前任务结束。否则，请记录被中断的任务，停止服务，并在监管程序再次尝试之前把数据目录恢复到已知状态。

日志与失败恢复

把应用输出和浏览器终端输出发送到平台常规的日志位置。包含服务修订版本、BotBrowser 版本、配置文件包版本、服务器镜像和任务标识。排除页面内容、凭据、路由密钥和客户记录。目标是解释服务事件，而不是把日志变成浏览会话的副本。

在日志和崩溃产物占满 worker 磁盘之前对其进行轮转。保留足够的历史，以便把候选版本与上一个已批准版本比较，然后应用组织常规的保留策略。固定的保留期限不如与事件响应和隐私要求挂钩的策略有用。

按运维人员需要采取的动作对故障分类。配置故障需要修正服务或配置文件包。依赖故障需要修复服务器镜像。资源故障需要审查工作负载或容量。应用故障归应用负责人处理。这种简单的责任模型可以防止反复重启掩盖持续存在的部署问题。

在预发布环境中测试恢复。在已批准的测试任务运行期间停止服务，重启主机，并暂时让某个必需依赖不可用。确认监控报告了正确的服务，监管程序遵守其重启上限，并且下一个任务从已批准的状态开始。恢复证据应成为镜像审查的一部分。

变更控制与版本批准

把操作系统镜像、浏览器版本、配置文件包、服务单元和应用视为一个被记录的部署组合。任何一层的变更都可能影响启动、渲染、媒体或资源使用。测试前先记录每个候选组合，例如 Ubuntu 24.04、BotBrowser 150、DISPLAY=:10.0 和镜像摘要，以便审查者能够复现。

让镜像变更与应用变更走同一条预发布路径。软件包更新、字体包、图形库、容器运行时变更和安全策略更新都值得跑一个有代表性的浏览器任务。把基础镜像与浏览器工作负载分开批准，会留下一个重要的缺口。

分小批推进变更。当多个层必须一起变化时，保留上一个组合并记录回滚顺序。回滚应恢复完整的已批准组合，而不是把旧浏览器与未经审查的配置文件或服务文件混用。

推进之后，在正常的发布窗口内观察任务完成情况、重启频率、磁盘增长和资源压力。把这些结果与已批准的预发布运行对比。启动正常但在日常工作下表现退化的候选版本，应在影响更多任务之前从池中移除。

Headless 启动与配置文件提示

BotBrowser 150 在 headless 启动时不会打开可见的配置文件提示窗口。缺失、过期、无效或版本不匹配的配置文件包会在终端输出中报告，进程随后沿正常的启动失败路径处理。有界面的启动仍会保留面向用户的提示。

这对 Playwright 集群和 CI worker 很重要，因为启动问题不应产生对桌面的隐藏依赖，也不应弹出意外窗口。请把浏览器的 stderr 与任务日志一起保存，把配置文件提示视为启动失败，并在重试之前替换配置文件包。

容器日志仍可能提到不可用的桌面或图形服务。请根据会话是否创建成功、已批准的冒烟任务是否完成以及所选图形后端来判断就绪。主机的库和配置文件包仍需要与部署指南保持一致。

运行规则

在每个 BotBrowser 服务中设置 DISPLAY=:10.0。 把它放在每个服务文件中，而不是依赖登录 shell，使服务重启和主机重启都从相同的环境开始。

验证 Xvfb 的屏幕配置。 24 位屏幕是实用的起点，但批准应当基于有代表性的渲染和截图检查。当配置文件的屏幕尺寸超过 Xvfb 的分辨率时，请提高 Xvfb 的分辨率。

监控磁盘使用。 浏览器会把崩溃转储和缓存数据写入 --user-data-dir 指定的目录。请设置日志轮转或定期清理，防止磁盘耗尽。

保持依赖更新。 定期运行 apt-get upgrade。库版本不一致可能导致不易察觉的渲染问题。

设置资源限制。 使用 systemd 的 MemoryMax 和 CPUQuota，防止失控的服务占用服务器的全部资源。

版本批准

把服务器镜像和 BotBrowser 版本作为一个部署组合来批准。记录 Ubuntu 版本、BotBrowser 版本、配置文件包、图形路径、Xvfb 的屏幕配置、服务文件修订版本和应用修订版本。其他镜像上的通过结果是有用的参考，但不能替代在将进入生产的镜像上的验证。

先在干净的 worker 上做一次冷启动。确认服务进入就绪状态，打开有代表性的页面，完成一项正常任务，并干净地关闭。在服务重启后和主机重启后重复同一任务。这些运行能发现交互式 shell 可能掩盖的缺失环境变量、权限、挂载时机和服务顺序问题。

接着审查用户可见的输出。包括一个普通的应用页面、一个文字较多的页面、一个截图或文档流程，以及产品用到的媒体。查找缺失字符、被裁剪的控件、空白区域、播放失败和页面尺寸的意外变化。验收规则应来自应用负责人，而不是某个固定的通用容差。

容量批准需要有代表性的任务组合。逐步提高并发度，同时观察内存、CPU、共享内存、文件描述符、磁盘增长和任务完成时间。为操作系统、日志记录和短暂的负载高峰留出足够余量。为这一确切的镜像记录已批准的范围，并在页面组合或浏览器版本变化时重新评估。

故障处理是版本批准的一部分。在任务运行期间停止一个 worker，在受控的预发布运行中提供过期或不匹配的配置文件，并验证监管程序记录了失败并让 worker 回到已知状态。重试不应复用已损坏的用户数据目录。日志必须能识别版本和 worker，同时不包含客户机密。

只有当有代表性的任务在每一类将接收该镜像的主机上都通过后，才推进镜像。如果同时使用带 GPU 的池和软件渲染的池，请把它们视为不同的部署类别。在候选版本完成组织常规的观察期之前，保留上一个已批准的镜像以便回滚。

关于 headless Ubuntu 主机的问题

BotBrowser 能在 Ubuntu 24.04 上运行吗？

文档列出的是 Ubuntu 20.04 或更高版本。在 24.04 上部分软件包名称已更改，例如 libasound2 变成了 libasound2t64，因此请使用步骤 1 中的替代安装命令，并在你的主机上验证结果。

可以使用更高的 Xvfb 分辨率吗？

可以。你可以用 -screen 0 2560x1440x24 或工作负载所需的任何尺寸启动 Xvfb。当配置文件的屏幕尺寸超过默认值时请调高它，并用有代表性的截图确认。

服务器上需要 GPU 吗？

这取决于工作负载和所选的 Linux 图形后端。基础自动化可以使用经过验证的软件路径，而涉及媒体、WebGL 或大量截图的工作负载在其他图形路径上可能表现不同。请在目标主机上测试预期的版本配置。

在 headless 模式下还需要 Xvfb 吗？

需要。在目标主机上运行 echo "$DISPLAY"、xdpyinfo | grep dimensions 和一次截图，确认每个 BotBrowser 进程都使用 DISPLAY=:10.0，而不是只确认进程仍然存在。请安装 Xvfb，在该显示上运行它，并在每个服务中设置该变量；随后在每一类主机上验证渲染、媒体和截图。

headless 启动失败时为什么没有窗口？

headless 运行通过终端输出报告启动提示，而不是打开桌面窗口。请把该输出与 worker 日志一起保存，并在重试前修正配置文件或主机问题。

每台服务器可以运行多少个实例？

这取决于主机和页面工作负载。请用预期的配置文件、图形后端、媒体、截图和 worker 活动来测量有代表性的页面。为操作系统保留余量，监控内存和 swap 压力，并在主机变得不稳定之前降低并发度。

如何检查缺失的库？

运行 ldd /usr/bin/chromium-browser | grep "not found"。列出 "not found" 的库都需要安装。可以用 apt-file search libname.so 找到提供某个库的软件包。

可以在基于 ARM 的 Ubuntu 服务器上运行 BotBrowser 吗？

架构支持取决于具体版本。在规划 ARM 池之前，请查看 GitHub 发布页面列出的架构。

如何更新 BotBrowser？

下载最新版本，并与匹配的配置文件包一起在预发布环境中准备。推进之前审查服务配置、依赖、图形路径和有代表性的工作负载，因为版本变化可能影响部署假设。在更新通过正常观察期之前，保留上一个已批准的组合。

部署决定

在 headless Ubuntu 服务器上设置 BotBrowser，需要正确的系统依赖、经过测试的图形后端和可靠的服务配置。请在显示 :10.0 上运行 Xvfb，并为每个 BotBrowser 服务设置 DISPLAY。在设定并发上限之前先测量有代表性的页面，为操作系统保留容量余量，并把私有数据排除在日志之外。下载 BotBrowser 即可开始。

BotBrowser 以两种有文档说明的方式支持 headless 服务器集群。它从所选配置文件包而不是服务器硬件读取屏幕尺寸、字体和 GPU 信息等指纹属性，并在 headless 启动时于终端输出中报告缺失、无效、过期或版本不匹配的配置文件状态，使 worker 明确失败而不是藏在隐藏窗口之后。这样，已批准主机之间的属性保持一致，运维人员也能在任务日志中看到可读的消息。BotBrowser 不能安装主机的库、字体或图形后端，不保证不同主机类别之间的渲染、媒体或容量完全一致，也不能替代生产前对每个镜像和工作负载的验证。

容器化部署请参阅 Docker 部署指南。容量规划请参阅 BotBrowser 性能优化。CLI 参数组合请参阅 CLI 配方。

实用结论

请把主机、浏览器版本、配置文件、图形路径和工作负载视为一个经过测试的组合。BotBrowser 可以让经过授权的浏览器会话更易重复，但主机依赖、权限、应用结果和隐私控制仍由运营方负责。

想在依赖任一模式之前先测量有头与无头会话的差异，可参阅无头与有头浏览器信号对比方法。

公开来源

• BotBrowser 文档：Headless 服务器设置
• BotBrowser 文档：Linux GPU 后端选择
• BotBrowser 发布页面
• systemd.service 手册