API 服务器配置

Bencher API 服务器在启动时需要一个 JSON 配置。 这个配置可以通过以下三种方式提供：

• BENCHER_CONFIG 环境变量：该值应设置为 JSON 配置
• BENCHER_CONFIG_PATH 环境变量：该值应设置为包含 JSON 配置文件的路径
• /etc/bencher/bencher.json 文件：此位置的文件包含 JSON 配置

如果没有找到配置，则加载默认配置。

示例 JSON 配置：

{
  "console": {
    "url": "https://bencher.example.com"
  },
  "security": {
    "issuer": "https://api.bencher.example.com",
    "secret_key": "UJu7Cpxb-zFaJYqXD-3mDDSDyj-ZvfxZFZs-X58xjxPy"
  },
  "server": {
    "bind_address": "0.0.0.0:6610",
    "request_body_max_bytes": 1048576,
    "tls": {
      "type": "as_file",
      "cert_file": "/path/to/cert.pem",
      "key_file": "/path/to/key.pem"
    }
  },
  "logging": {
    "name": "Bencher API",
    "log": {
      "stderr_terminal": {
        "level": "info"
      }
    }
  },
  "database": {
    "file": "/var/lib/bencher/data/bencher.db",
    "busy_timeout": 5000,
    "cache_size": 65536
  },
  "smtp": {
    "hostname": "mailbonobo.com",
    "port": 587,
    "starttls": true,
    "username": "bencher",
    "secret": "WM3F2u9cqSNdBPLfy9sJ5kk9",
    "from_name": "Bencher",
    "from_email": "info@bencher.example.com"
  },
  "plus": {
    "disaster_recovery": {
      "replica": {
        "scheme": "s3",
        "bucket": "my-bucket",
        "path": "path/to/replicate",
        "access_key_id": "ABC123DoRemMiABC123",
        "secret_access_key": "AA3Chr-JSF5sUQqKwayx-FvCfZKsMev-5BqPpcFC3m7"
      }
    },
    "registry": {
      "url": "https://registry.bencher.example.com",
      "storage": {
        "scheme": "s3",
        "bucket": "my-bucket",
        "path": "registry",
        "endpoint": "https://s3.example.com",
        "region": "auto",
        "access_key_id": "AKIAIOSFODNN7EXAMPLE",
        "secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
        "chunk_size": 5242880
      },
      "upload_timeout": 3600,
      "max_body_size": 1073741824
    },
    "runners": {
      "heartbeat_timeout": 90,
      "job_timeout_grace_period": 60,
      "update_base_url": "https://example.com/downloads/"
    },
    "rate_limiting": {
      "window": 86400,
      "unclaimed_limit": 255,
      "claimed_limit": 65536,
      "plus_limit": 1048576,
      "public": {
        "requests": {
          "minute": 1024,
          "hour": 4096,
          "day": 8192
        },
        "attempts": {
          "minute": 32,
          "hour": 64,
          "day": 128
        },
        "runs": {
          "minute": 64,
          "hour": 128,
          "day": 256
        }
      },
      "user": {
        "requests": {
          "minute": 2048,
          "hour": 8192,
          "day": 16384
        },
        "attempts": {
          "minute": 2,
          "hour": 4,
          "day": 8
        },
        "credentials": {
          "minute": 4,
          "hour": 8,
          "day": 16
        },
        "organizations": {
          "minute": 2,
          "hour": 4,
          "day": 8
        },
        "invites": {
          "minute": 8,
          "hour": 16,
          "day": 32
        },
        "runs": {
          "minute": 64,
          "hour": 1024,
          "day": 4096
        }
      },
      "project": {
        "requests": {
          "minute": 2048,
          "hour": 8192,
          "day": 16384
        },
        "runs": {
          "minute": 64,
          "hour": 1024,
          "day": 4096
        }
      },
      "runner": {
        "requests": {
          "minute": 16,
          "hour": 256,
          "day": 4096
        }
      },
      "oci_bandwidth": {
        "unclaimed": 1073741824,
        "free": 10737418240,
        "plus": 107374182400
      }
    },
    "stats": {
      "offset": 11242,
      "enabled": true
    },
    "mcp": {
      "openai_apps_challenge": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
    },
    "oauth": {
      "issuer": "https://api.bencher.example.com",
      "resources": [
        "https://mcp.bencher.example.com/mcp",
        "https://api.bencher.example.com/mcp"
      ],
      "signing_key": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASC...\n-----END PRIVATE KEY-----\n"
    }
  }
}

console

security

server

此部分基于Dropshot服务器配置。

logging

本节基于 Dropshot logging 配置。

database

smtp

本节指定了SMTP服务配置。整个部分是可选的。如果未指定，所有消息将被发送到logging。

plus

此部分用于介绍由Bencher Plus License覆盖的特性。

plus.github

此部分指定了用于 OAuth2 认证的 GitHub 应用的配置。 服务器上至少有一个组织必须拥有有效的 Bencher Plus 企业 许可证。 整个部分是可选的。 如果未指定，则不会启用与 GitHub 的认证。

plus.google

本节指定用于 用于 OAuth2 身份验证的 Google 客户端 的配置。您必须为服务器上的至少一个组织拥有有效的 Bencher Plus 企业版 许可证。整个部分为可选。如果未指定，则不会启用 Google 认证。

plus.disaster_recovery

此部分指定了灾难恢复配置。 Bencher支持连续复制所有数据库更改。

有两种复制scheme：

• file: 复制到本地文件路径
  • path: 复制路径
• s3: 复制到任何S3兼容的Blob存储
  • bucket: 存储桶名称
  • path: （可选）存储桶中的路径
  • endpoint: （AWS：可选 | 非AWS：必需）复制端点
  • region: （可选）存储桶区域
  • access_key_id: S3访问密钥
  • secret_access_key: S3密钥

以上两种复制scheme均有以下附加选项：

• snapshot.interval: （可选）指定创建新快照的频率。这用于减少恢复时间，因为较新的快照将有较少的WAL帧需要应用。保留仍然适用于这些快照。如果未设置快照间隔，则每次执行保留时都会创建新快照。默认情况下，每24小时进行一次保留。
• snapshot.retention: （可选）快照和WAL文件保留的时间。保留期过后，会创建新的快照并删除旧的。在最旧快照之前存在的WAL文件也将被删除。默认值为24h。
• validation.interval: （可选）如果指定，Bencher将自动恢复并验证副本上的数据与本地副本是否匹配。默认情况下禁用。启用此选项可能会显著增加运行Bencher的成本，因为大多数云服务会为下载收费。
• sync_interval: （可选）将帧推送到副本的频率。默认值为1s。增加频率可能显著增加云存储成本。
• checkpoint.interval: （可选）Litestream执行非阻塞PASSIVE检查点的频率，不受页面数量影响。如果有活跃的读取器或写入器，Litestream将跳过检查点。默认值为1m。
• checkpoint.min_page_count: （可选）触发非阻塞PASSIVE检查点前的最小WAL页面数（每页约4KB）。如果有活跃的读取器或写入器，Litestream将跳过检查点。默认值为1000（约4MB）。
• checkpoint.truncate_page_n: （可选）阻塞TRUNCATE检查点的页面数阈值。当达到此阈值时，Litestream会执行阻塞检查点，等待所有读取器和写入器完成，这可能在负载下导致database is locked错误。默认值为0（禁用）。 仅在需要WAL文件大小上限并了解阻塞影响的情况下才设置为非零值。

plus.registry

此部分指定 OCI（Open Container Initiative）注册表存储配置。 Bencher 可以作为符合 OCI 标准的容器/工件注册表运行。

如果未配置此部分，Bencher 将使用本地文件系统存储， 存储在数据库文件旁边的 registry 目录中。 这适用于开发和单实例部署。

对于多实例的生产部署或需要持久性时， 请配置 S3 兼容的存储。

有两种存储 scheme：

• file：将 OCI 工件存储在本地文件系统中（默认）
  • path：（可选）注册表数据的目录。默认为数据库文件旁边的 registry 目录。
• s3：将 OCI 工件存储在任何 S3 兼容的 Blob 存储中
  • bucket：存储桶名称
  • path：（可选）存储桶中的键前缀。开头、结尾和重复的斜杠会被移除，因此 registry、registry/ 和 /registry 都存储在 registry 下。
  • endpoint：（AWS：可选 | 非AWS：必需）存储端点
  • region：（可选）存储桶区域。AWS 必需。默认为 auto，这是 S3 兼容存储所期望的值。
  • access_key_id：S3 访问密钥
  • secret_access_key：S3 密钥
  • chunk_size：（可选）上传数据存储之前缓冲的最小块大小（字节）。默认值：5 MB。 HTTP 请求正文以小型网络帧的形式到达（通常为 8 到 64 KB）。如果不进行缓冲，每个帧都会成为一个单独的对象，每层会创建数千个对象。此值也与 S3 分段上传的最小分段大小一致。

请设置存储桶生命周期规则以中止未完成的分段上传。Blob 上传完成过程中崩溃会留下一个未完成的分段上传，服务器不会中止它。

如果您之前配置的 path 以斜杠开头或结尾，请在升级前将现有对象移动到规范化的前缀。path 为 registry/ 时，键存储在 registry//<project>/... 下，现在存储在 registry/<project>/... 下。path 的每个段如果包含 ASCII 控制字符、非 ASCII 字符或 \ {` `^` `} % ` ] " > [ ~ < # | * ? 之一，也会在存储的键中被百分号编码；恰好为 . 或 .. 的段会存储为 %2E 或 %2E%2E。其他所有字符（包括空格、+、=、@ 和 :）都按原样存储，因此 team#1 变为 team%231，而 team+1 仍为 team+1。存储在现在会被编码的前缀下的数据也需要同样的迁移。在移动任何数据之前，请列出存储桶中实际存储的键，并与新的前缀进行比较。

plus.runners

此部分配置用于裸机基准测试执行的运行器系统。 运行器是服务器范围的代理，负责认领和执行基准测试作业。

如果未配置此部分，Bencher 将使用默认值。

plus.rate_limiting

本节指定 API 服务器的速率限制。 整节内容是可选的。 如果未指定，将使用列出的默认值。

为防止创建unclaimed项目，请将unclaimed_limit设置为0。

public

public速率限制器按IP地址应用于未认证的请求。 每个子字段包含minute、hour和day限制。 整节内容是可选的。 如果未指定，将使用列出的默认值。

user

user速率限制器按认证用户应用。 每个子字段包含minute、hour和day限制。 整节内容是可选的。 如果未指定，将使用列出的默认值。

project

project速率限制器按项目应用。 每个子字段包含minute、hour和day限制。 整节内容是可选的。 如果未指定，将使用列出的默认值。

runner

runner速率限制器按运行器应用。 每个子字段包含minute、hour和day限制。 整节内容是可选的。 如果未指定，将使用列出的默认值。

oci_bandwidth

oci_bandwidth指定每个组织层级的每日OCI注册表带宽限制。 整节内容是可选的。 如果未指定，将使用列出的默认值。

plus.stats

该部分指定是否以及何时收集服务器统计信息。 整个部分是可选的。 如果未指定，将使用列出的默认值。 也就是说，服务器统计信息是默认启用的。 设置enabled为false以禁用服务器统计。

plus.mcp

此部分配置 Bencher MCP 服务器。 整个部分是可选的。

plus.oauth

此部分让 ChatGPT、claude.ai 和 Claude Code 等 MCP 客户端可以通过 OAuth 登录 Bencher MCP。 API 服务器会成为它们的 OAuth 授权服务器，用户在位于 console.url 的 Bencher Console 上批准每个应用。 整个部分是可选的。 如果未指定，则 OAuth 处于关闭状态：其端点返回 404 Not Found，并且 Bencher MCP 只接受 API 密钥和匿名请求。

JSON 字符串不能包含换行符，因此请将 signing_key 中的每个换行写作 \n。 例如，生成一个密钥并将其输出为 JSON 字符串，而不写入文件：

openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 | jq -Rs .

要轮换签名密钥，替换它即可。这不会断开任何应用的连接。

API 服务器在 issuer 的根路径下提供其 OAuth 端点和元数据。 如果反向代理在路径前缀下提供 API 服务器，例如 https://bencher.example.com/api， 请将 issuer 设置为源（https://bencher.example.com），并在 resources 中列出 MCP 端点的完整 URL（https://bencher.example.com/api/mcp）。 此时，代理必须将源上的 /oauth/、/.well-known/oauth-authorization-server 和 /.well-known/openid-configuration 路由到 API 服务器上的相同路径， 并将每个资源的元数据路径（此处为 /.well-known/oauth-protected-resource/api/mcp）路由到 API 服务器上的 /.well-known/oauth-protected-resource/mcp。 当有多个资源时，代理还必须原样传递 Host 请求头，因为 API 服务器根据它选择要公布的资源。