Self-Hosted Bare Metal Runner

Self-Hosted Runner 是一个由你自己运行和管理的 Bare Metal Runner， 而不是使用 Bencher 托管的 On-Demand 或 Dedicated Runner。 你将 runner 二进制文件指向某个 Bencher API 服务器， 它便会在你自己的硬件上认领并执行 Job。

在以下场景中自托管 Runner 是一个不错的选择：

  • 在 Bencher Cloud 未提供的特定硬件上运行基准测试
  • 将基准测试工作负载保留在你自己的网络或气隙（air-gapped）环境内
  • 端到端运行 Bencher Self-Hosted

本指南将逐步介绍如何注册 Runner、用 Spec 描述其硬件、 将两者关联起来，以及启动 runner 二进制文件。 关于 Runner、Spec、Sandbox 和 Job 如何协同工作的概念性概述， 请参阅 Bare Metal 概述。

🐰 Firecracker 沙箱需要启用了 KVM 的 Linux。 仅服务于非沙箱化 Spec 的 Runner 可以在任何受支持的主机上运行。

创建 Runner

Runner 是用于向你的 Bencher API 服务器认证 runner 二进制文件的资源。 可以使用 bencher CLI、 Runners REST API 或 Bencher Console 创建一个。

Terminal window
bencher runner create \
  --host https://api.bencher.example.com \
  --name "My Runner"

Bencher 会返回新的 Runner 及其密钥：

{
  "uuid": "...",
  "key": "bencher_runner_..."
}

该密钥只显示一次，因此请妥善保管。 你将在启动 Runner 时把它传给 runner 二进制文件。 如果密钥丢失或泄露，请使用 POST /v0/runners/{runner}/key API 轮换它， 这会立即使之前的密钥失效。

创建 Spec

Spec 描述 Runner 提供的硬件： 操作系统、CPU 架构、Sandbox 类型、CPU 数量、内存、磁盘和网络访问。 Job 声明它所需的 Spec，而 Runner 只认领其所支持的 Spec 对应的 Job。

可以使用 bencher CLI、 Specs REST API 或 Bencher Console 创建 Spec：

Terminal window
bencher spec create \
  --host https://api.bencher.example.com \
  --name "Intel v1" \
  --os linux \
  --architecture x86_64 \
  --sandbox firecracker \
  --cpu 4 \
  --memory 51539607552 \
  --disk 137438953472

省略 --sandbox 可定义一个非沙箱化的 Spec， 如果允许该 Spec 上的 Job 进行网络访问，则传入 --network。 内存和磁盘以字节为单位指定。 关于 Spec 以及 Testbed 如何记录每个 Report 所使用的 Spec 的更多信息， 请参阅 Testbed 与 Spec。

将 Spec 分配给 Runner

Runner Spec 将一个 Spec 关联到一个 Runner。 一个 Runner 可以支持多个 Spec，一个 Spec 也可以由多个 Runner 支持。 Runner 只认领其被分配的 Spec 对应的 Job。

可以使用 bencher CLI 或 Runner Specs REST API 将 Spec 添加到 Runner：

Terminal window
bencher runner spec add my-runner \
  --host https://api.bencher.example.com \
  --spec intel-v1

之后可使用 DELETE /v0/runners/{runner}/specs/{spec} API 移除该关联。

启动 Runner

在创建好 Runner 并至少分配一个 Spec 后， 使用 runner up 在你的硬件上启动 runner 二进制文件。 提供 API 服务器主机、Runner 的 UUID 或 slug，以及 Runner 密钥， 既可以作为标志，也可以作为环境变量：

Terminal window
runner up \
  --host https://api.bencher.example.com \
  --runner my-runner \
  --key bencher_runner_...
Terminal window
export BENCHER_HOST=https://api.bencher.example.com
export BENCHER_RUNNER=my-runner
export BENCHER_RUNNER_KEY=bencher_runner_...
runner up

runner 二进制文件向 API 服务器打开单个 WebSocket 连接， 轮询与其 Spec 匹配的 Job，逐个执行，并将结果报告回去。 该连接在多个 Job 之间保持打开， 并且当有新版本可用时，二进制文件会在 Job 之间自我更新。

默认情况下，Runner 会拒绝任何其 Spec 没有 Sandbox 的 Job。 要让 Runner 直接在主机上执行非沙箱化的 Job， 请使用 --danger-allow-no-sandbox 标志 启动它。

  • runner up

    runner up

    启动 runner，轮询并执行基准测试 Job。 这是用于操作 Self-Hosted Runner 的长时间运行命令。 runner 向 API 服务器打开单个 WebSocket 连接， 认领与其 Spec 匹配的 Job，执行它们，并将结果报告回去。

    runner up [OPTIONS]

    选项

    --host <HOST>

    要连接的 Bencher API 服务器。 默认使用 https://api.bencher.dev。 也可以通过 BENCHER_HOST 环境变量设置。

    --runner <RUNNER>

    要作为其运行的 Runner 的 UUID 或 slug。 也可以通过 BENCHER_RUNNER 环境变量设置。

    --key <KEY>

    创建 Runner 时返回的 Runner 认证密钥（bencher_runner_...）。 也可以通过 BENCHER_RUNNER_KEY 环境变量设置。

    --poll-timeout <POLL_TIMEOUT>

    等待 Job 时的长轮询超时（秒），介于 1 和 900 之间。 默认使用 55。

    --danger-allow-no-sandbox

    允许在没有 Sandbox 的情况下执行 Job。 如果没有此标志，其 Spec 没有 Sandbox 的 Job 会在运行时被拒绝。 非沙箱化的 Job 直接在主机上运行，因此仅对受信任的工作负载启用此项。 也可以通过 BENCHER_DANGER_ALLOW_NO_SANDBOX 环境变量设置。

    --sandbox-log-level <SANDBOX_LOG_LEVEL>

    沙箱进程的日志级别。 默认使用 warning。

    --no-auto-update

    禁用来自服务器的自动更新。 默认情况下，当服务器提供新版本时，runner 会在 Job 之间自我更新。 也可以通过 BENCHER_NO_AUTO_UPDATE 环境变量设置。

    --max-download-size <MAX_DOWNLOAD_SIZE>

    自我更新二进制文件的最大下载大小（字节）。 默认使用 500 MiB。 与 --no-auto-update 冲突。

    --max-output-size <MAX_OUTPUT_SIZE>

    收集的 stdout 和 stderr 的最大大小（字节）。 默认使用 25 MiB。

    --max-file-count <MAX_FILE_COUNT>

    要解码的输出文件的最大数量。 默认使用 255。

    --max-symlinks <MAX_SYMLINKS>

    路径解析期间要跟随的符号链接的最大数量， 与 Linux 内核的 MAXSYMLINKS 限制相匹配。 默认使用 40。 仅在非沙箱化模式下使用。

    --grace-period <GRACE_PERIOD>

    基准测试退出后、最终输出收集前的宽限期（秒）。

    主机调优

    在每次基准测试之前，runner 会应用主机调优以减少测量噪声。 默认情况下，它会禁用 ASLR、NMI 看门狗、SMT / 超线程和睿频加速（turbo boost）； 将 CPU 调频调速器（governor）设为 performance，swappiness 设为 10，perf_event_paranoid 设为 -1。 下面的标志会改为将各项优化保持在其主机默认值。

    --no-tuning

    禁用所有主机调优优化。

    --aslr

    保持 ASLR 启用（默认：基准测试时禁用）。

    --nmi-watchdog

    保持 NMI 看门狗启用（默认：基准测试时禁用）。

    --smt

    保持 SMT / 超线程启用（默认：基准测试时禁用）。

    --turbo

    保持睿频加速启用（默认：基准测试时禁用）。

    --swappiness <SWAPPINESS>

    设置 swappiness 值。 默认使用 10。

    --governor <GOVERNOR>

    设置 CPU 调频调速器。 默认使用 performance。

    --perf-event-paranoid <PERF_EVENT_PARANOID>

    设置 perf_event_paranoid 值。 默认使用 -1。

    --help

    打印帮助。

有关每个选项，请参阅 runner CLI 参考， 有关与服务器交换的消息，请参阅 Runner 协议 参考。

Self-Hosted Runner 工作流

一旦 Runner 连接好，你提交基准测试的方式与任何 Bare Metal Runner 相同： 构建并推送一个 Image，然后使用匹配的 Spec 运行 bencher run --image。 下图展示了从注册 Runner 到执行 Job 的完整路径。

OCI Registryrunner binaryAPI ServerOCI Registryrunner binaryAPI ServerAdminbencher runner createRunner + keybencher spec createbencher runner spec addrunner up --host --runner --keyConnect (WebSocket) and poll for JobsAssign matching JobPull ImageImage layersRun benchmarkSubmit resultsAdmin

继续学习：runner CLI 参考 ➡

🤖 该文档由 AI 自动翻译。 它可能不准确并且可能包含错误。 如果您发现任何错误，请在 GitHub 上提出问题.

Published: Fri, June 19, 2026 at 8:00:00 AM UTC