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 遵循 stable 更新通道， 仅更新到版本化的发布版本。 canary 通道则跟踪部署到 Bencher Cloud 的滚动 canary 构建。

默认情况下，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 环境变量设置。

    --update-channel <UPDATE_CHANNEL>

    自动更新使用的更新通道，stable 或 canary。 默认使用 stable。 stable 通道更新到版本化的发布版本。 canary 通道跟踪滚动 canary 构建， 每当 runner 在 Bencher Cloud 部署中发生变化时，该构建都会重新构建。 也可以通过 BENCHER_UPDATE_CHANNEL 环境变量设置。 与 --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 | Last Updated: Tue, July 7, 2026 at 8:00:00 AM UTC