Конфигурация API сервера

Сервер API Bencher требует 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://github.com/bencherdev/bencher/releases/download/"
    },
    "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.

database

smtp

Этот раздел определяет конфигурацию службы SMTP. Весь раздел является необязательным. Если не указано, все сообщения будут отправляться в logging.

plus

Этот раздел посвящен функциям, которые покрываются лицензией Bencher Plus.

plus.github

В этом разделе указывается конфигурация приложения GitHub, используемого для аутентификации OAuth2. У вас должна быть действующая лицензия Bencher Plus Enterprise для хотя бы одной организации на сервере. Весь раздел является необязательным. Если он не указан, то аутентификация с помощью GitHub не будет включена.

plus.google

В этом разделе задаётся конфигурация для Google-клиента, используемого для аутентификации через OAuth2. У вас должна быть действительная лицензия Bencher Plus Enterprise хотя бы для одной организации на сервере. Весь раздел является необязательным. Если раздел не указан, аутентификация через Google не будет включена.

plus.disaster_recovery

Этот раздел описывает конфигурацию восстановления после аварий. Bencher поддерживает непрерывное реплицирование всех изменений базы данных.

Существует две схемы репликации:

• file: Реплицирование в локальную файловую систему
  • path: Путь для репликации
• s3: Реплицирование в любое совместимое S3 хранилище
  • bucket: Имя bucket
  • path: (Опционально) Путь в bucket
  • endpoint: (AWS: Опционально | Не AWS: Обязательно) Конечная точка репликации
  • region: (Опционально) Регион bucket
  • access_key_id: Ключ доступа S3
  • secret_access_key: Секретный ключ доступа S3

Обе схемы репликации имеют следующие дополнительные опции:

• snapshot.interval: (Опционально) Указывает, как часто будут создаваться новые snapshots. Это используется для уменьшения времени восстановления, так как новые snapshots будут содержать меньшее количество WAL кадров для применения. Политика retention также применяется к этим snapshots. Если вы не указываете интервал создания snapshot, то новый snapshot будет создан при каждом выполнении retention. По умолчанию retention выполняется каждые 24 часа.
• snapshot.retention: (Опционально) Время, в течение которого будут сохраняться файлы snapshot и WAL. По истечении этого времени будет создан новый snapshot, а старый будет удален. Файлы WAL, которые существуют до самого старого snapshot, также будут удалены. Значение по умолчанию: 24h.
• validation.interval: (Опционально) Если указано, Bencher автоматически восстановит и проверит, что данные на реплике соответствуют локальной копии. По умолчанию отключено. Включение этой функции может значительно увеличить стоимость запуска Bencher, так как большинство облачных сервисов взимают плату за загрузки.
• sync_interval: (Опционально) Частота, с которой кадры передаются на реплику. Значение по умолчанию: 1s. Увеличение частоты может значительно повысить затраты на облачное хранилище.
• checkpoint.interval: (Опционально) Как часто Litestream выполняет неблокирующий PASSIVE чекпоинт вне зависимости от количества страниц. Litestream пропускает чекпоинт, если активны читатели или писатели. Значение по умолчанию: 1m.
• checkpoint.min_page_count: (Опционально) Минимальное количество WAL-страниц перед запуском неблокирующего PASSIVE чекпоинта (~4КБ на страницу). Litestream пропускает чекпоинт, если активны читатели или писатели. Значение по умолчанию: 1000 (~4МБ).
• 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 хранилище
  • bucket: Имя bucket
  • path: (Опционально) Префикс ключа в bucket. Ведущие, завершающие и повторяющиеся слеши удаляются, поэтому registry, registry/ и /registry сохраняют всё под registry.
  • endpoint: (AWS: Опционально | Не AWS: Обязательно) Конечная точка хранилища
  • region: (Опционально) Регион bucket. Обязателен для AWS. По умолчанию auto, что ожидают S3-совместимые хранилища.
  • access_key_id: Ключ доступа S3
  • secret_access_key: Секретный ключ доступа S3
  • chunk_size: (Опционально) Минимальный размер фрагмента в байтах для буферизации данных загрузки перед сохранением. По умолчанию: 5 МБ. Тела HTTP-запросов поступают в виде маленьких сетевых фреймов (обычно от 8 до 64 КБ). Без буферизации каждый фрейм становится отдельным объектом, создавая тысячи объектов на каждый слой. Это значение также соответствует минимальному размеру части для многочастной загрузки S3.

Задайте правило жизненного цикла bucket, которое прерывает незавершённые многочастные загрузки. Сбой в середине завершения загрузки блоба оставляет такую загрузку, и сервер её не прерывает.

Если ранее вы настроили path, начинающийся или заканчивающийся слешем, перенесите существующие объекты на нормализованный префикс перед обновлением. path вида registry/ сохранял ключи под registry//<project>/..., а теперь сохраняет их под registry/<project>/.... Каждый сегмент path также кодируется процентами в сохранённом ключе, если он содержит управляющий символ ASCII, символ вне ASCII или один из \ {` `^` `} % ` ] " > [ ~ < # | * ?, а сегмент, равный ровно . или .., сохраняется как %2E или %2E%2E. Все остальные символы, включая пробелы, +, =, @ и :, сохраняются как есть, поэтому team#1 становится team%231, а team+1 остаётся team+1. Данные, сохранённые под префиксом, который теперь кодируется, требуют того же переноса. Перед переносом любых данных выведите список ключей, фактически сохранённых в бакете, и сравните их с новым префиксом.

plus.runners

Этот раздел настраивает систему раннеров для выполнения бенчмарков на bare metal. Раннеры — это серверные агенты, которые запрашивают и выполняют задачи бенчмарков.

Если этот раздел не настроен, 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

Этот раздел настраивает MCP-сервер Bencher. Весь раздел является необязательным.

plus.oauth

Этот раздел позволяет MCP-клиентам, таким как ChatGPT, claude.ai и Claude Code, входить в Bencher MCP через OAuth. API-сервер становится для них сервером авторизации OAuth, а пользователи одобряют каждое приложение в Bencher Console по адресу console.url. Весь раздел является необязательным. Если он не указан, OAuth выключен: его эндпоинты возвращают 404 Not Found, а Bencher MCP принимает только API-ключи и анонимные запросы.

Строка JSON не может содержать перевод строки, поэтому записывайте каждый перевод строки в signing_key как \n. Например, сгенерируйте ключ и выведите его как строку JSON, не записывая в файл:

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

Чтобы сменить ключ подписи, замените его. Это не отключает ни одно приложение.

API-сервер обслуживает свои эндпоинты и метаданные OAuth в корне issuer. Если обратный прокси обслуживает API-сервер под префиксом пути, например https://bencher.example.com/api, укажите в issuer origin (https://bencher.example.com) и перечислите полный URL эндпоинта MCP в resources (https://bencher.example.com/api/mcp). Тогда прокси должен направлять запросы к /oauth/, /.well-known/oauth-authorization-server и /.well-known/openid-configuration в корне origin на те же пути API-сервера, а запросы к пути метаданных каждого ресурса, здесь /.well-known/oauth-protected-resource/api/mcp, на /.well-known/oauth-protected-resource/mcp API-сервера. Если ресурсов больше одного, прокси также должен передавать заголовок Host без изменений, поскольку по нему API-сервер выбирает, какой ресурс объявить.