Configuração do Servidor API

O Bencher API Server requer uma configuração JSON no momento da inicialização. A configuração pode ser fornecida de três maneiras:

• Variável de ambiente BENCHER_CONFIG: O valor deve ser definido para a configuração JSON
• Variável de ambiente BENCHER_CONFIG_PATH: O valor deve ser definido para o caminho de um arquivo que contenha a configuração JSON
• Arquivo /etc/bencher/bencher.json: Um arquivo neste local contendo a configuração JSON

Se nenhuma configuração for encontrada, uma configuração padrão será carregada.

Exemplo de configuração 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

Esta seção é baseada na configuração do servidor Dropshot.

logging

Esta seção é baseada na configuração de logging do Dropshot.

database

smtp

Esta seção especifica uma configuração de serviço SMTP. Toda a seção é opcional. Se não for especificada, todas as mensagens serão enviadas para logging.

plus

Esta seção é para recursos que são cobertos pela Licença Bencher Plus.

plus.github

Esta seção especifica a configuração para um aplicativo GitHub usado para autenticação OAuth2. Você deve ter uma licença Enterprise válida do Bencher Plus para pelo menos uma organização no servidor. A seção inteira é opcional. Se não especificada, a autenticação com o GitHub não será ativada.

plus.google

Esta seção especifica a configuração para um cliente Google usado para autenticação OAuth2. Você deve ter uma licença Bencher Plus Enterprise válida para pelo menos uma organização no servidor. Toda a seção é opcional. Se não for especificada, a autenticação com o Google não será ativada.

plus.disaster_recovery

Esta seção especifica a configuração de recuperação de desastres. O Bencher suporta a replicação contínua de todas as alterações no banco de dados.

Existem dois schemes de replicação:

• file: Replicar para um caminho de arquivo local
  • path: Caminho para replicar
• s3: Replicar para qualquer armazenamento de blob compatível com S3
  • bucket: Nome do bucket
  • path: (Opcional) Caminho no bucket
  • endpoint: (AWS: Opcional | Não-AWS: Obrigatório) Endpoint de replicação
  • region: (Opcional) Região do bucket
  • access_key_id: Chave de acesso do S3
  • secret_access_key: Chave de acesso secreta do S3

Ambos os schemes de replicação têm as seguintes opções adicionais:

• snapshot.interval: (Opcional) Especifica com que frequência novos snapshots serão criados. Isso é usado para reduzir o tempo de restauração, já que snapshots mais novos terão menos frames WAL para aplicar. A retenção ainda se aplica a esses snapshots. Se você não definir um intervalo de snapshot, um novo snapshot será criado sempre que a retenção for realizada. A retenção ocorre a cada 24 horas por padrão.
• snapshot.retention: (Opcional) A quantidade de tempo que os arquivos de snapshot e WAL serão mantidos. Após o período de retenção, um novo snapshot será criado e o antigo será removido. Arquivos WAL que existirem antes do snapshot mais antigo também serão removidos. O padrão é 24h.
• validation.interval: (Opcional) Quando especificado, o Bencher restaurará automaticamente e validará que os dados na réplica correspondem à cópia local. Desativado por padrão. Habilitar isso pode aumentar significativamente o custo de execução do Bencher, já que a maioria dos serviços em nuvem cobra pelos downloads.
• sync_interval: (Opcional) Frequência com que os frames são enviados para a réplica. O padrão é 1s. Aumentar a frequência pode aumentar significativamente os custos de armazenamento em nuvem.
• checkpoint.interval: (Opcional) Com que frequência o Litestream realiza um checkpoint PASSIVE não bloqueante independentemente da contagem de páginas. O Litestream pula o checkpoint se leitores ou escritores estiverem ativos. O padrão é 1m.
• checkpoint.min_page_count: (Opcional) Número mínimo de páginas WAL antes de um checkpoint PASSIVE não bloqueante ser acionado (~4KB por página). O Litestream pula o checkpoint se leitores ou escritores estiverem ativos. O padrão é 1000 (~4MB).
• checkpoint.truncate_page_n: (Opcional) Limite de páginas para um checkpoint TRUNCATE bloqueante. Quando este limite é atingido, o Litestream realiza um checkpoint bloqueante que aguarda a conclusão de todos os leitores e escritores, o que pode causar erros database is locked sob carga. O padrão é 0 (desativado). Defina um valor diferente de zero apenas se precisar de um limite superior no tamanho do arquivo WAL e compreender as implicações do bloqueio.

plus.registry

Esta seção especifica a configuração de armazenamento do registro OCI (Open Container Initiative). O Bencher pode funcionar como um registro de contêineres/artefatos compatível com OCI.

Se esta seção não estiver configurada, o Bencher usará armazenamento em sistema de arquivos local em um diretório registry adjacente ao arquivo de banco de dados. Isso é adequado para desenvolvimento e implantações de instância única.

Para implantações de produção com múltiplas instâncias ou para durabilidade, configure o armazenamento compatível com S3.

Há dois schemes de armazenamento:

• file: Armazenar artefatos OCI no sistema de arquivos local (padrão)
  • path: (Opcional) Diretório para os dados do registro. Por padrão, um diretório registry adjacente ao arquivo de banco de dados.
• s3: Armazenar artefatos OCI em qualquer armazenamento de blob compatível com S3
  • bucket: Nome do bucket
  • path: (Opcional) Prefixo de chave no bucket. Barras iniciais, finais e repetidas são removidas, portanto registry, registry/ e /registry armazenam todos sob registry.
  • endpoint: (AWS: Opcional | Não-AWS: Obrigatório) Endpoint de armazenamento
  • region: (Opcional) Região do bucket. Obrigatório para AWS. Por padrão auto, que é o esperado pelos armazenamentos compatíveis com S3.
  • access_key_id: Chave de acesso do S3
  • secret_access_key: Chave de acesso secreta do S3
  • chunk_size: (Opcional) Tamanho mínimo do fragmento em bytes para armazenamento em buffer dos dados de upload antes de salvar. Padrão: 5 MB. Os corpos de requisição HTTP chegam como pequenos frames de rede (tipicamente 8 a 64 KB). Sem armazenamento em buffer, cada frame se torna um objeto separado, criando milhares de objetos por camada. Este valor também corresponde ao tamanho mínimo de parte para uploads multipart do S3.

Defina uma regra de ciclo de vida do bucket que aborte uploads multipart incompletos. Uma falha no meio da conclusão de um upload de blob deixa um, e o servidor não o aborta.

Se você configurou anteriormente um path que começava ou terminava com uma barra, mova os objetos existentes para o prefixo normalizado antes de atualizar. Um path de registry/ armazenava chaves sob registry//<project>/... e agora as armazena sob registry/<project>/.... Cada segmento de path também é codificado em porcentagem na chave armazenada quando contém um caractere de controle ASCII, um caractere não ASCII ou um de \ {` `^` `} % ` ] " > [ ~ < # | * ?, e um segmento que seja exatamente . ou .. é armazenado como %2E ou %2E%2E. Qualquer outro caractere, incluindo espaços, +, =, @ e :, é armazenado como está, portanto team#1 torna-se team%231 enquanto team+1 continua team+1. Os dados armazenados sob um prefixo que agora é codificado precisam da mesma mudança. Antes de mover qualquer dado, liste as chaves realmente armazenadas no bucket e compare-as com o novo prefixo.

plus.runners

Esta seção configura o sistema de runners para execução de benchmarks em bare metal. Runners são agentes de escopo de servidor que reivindicam e executam trabalhos de benchmark.

Se esta seção não estiver configurada, o Bencher usará os valores padrão.

plus.rate_limiting

Esta seção especifica o limite de taxa para o servidor da API. Toda a seção é opcional. Se não especificado, os valores padrão listados serão usados.

Para evitar que projetos unclaimed sejam criados, defina unclaimed_limit como 0.

public

O limitador de taxa public se aplica por endereço IP para solicitações não autenticadas. Cada subcampo contém limites de minute, hour e day. Toda a seção é opcional. Se não especificado, os valores padrão listados serão usados.

user

O limitador de taxa user se aplica por usuário autenticado. Cada subcampo contém limites de minute, hour e day. Toda a seção é opcional. Se não especificado, os valores padrão listados serão usados.

project

O limitador de taxa project se aplica por projeto. Cada subcampo contém limites de minute, hour e day. Toda a seção é opcional. Se não especificado, os valores padrão listados serão usados.

runner

O limitador de taxa runner se aplica por runner. Cada subcampo contém limites de minute, hour e day. Toda a seção é opcional. Se não especificado, os valores padrão listados serão usados.

oci_bandwidth

O oci_bandwidth especifica os limites diários de largura de banda do registro OCI por nível de organização. Toda a seção é opcional. Se não especificado, os valores padrão listados serão usados.

plus.stats

Esta seção especifica se e quando as estatísticas do servidor são coletadas. A seção inteira é opcional. Se não especificado, os valores padrão listados serão usados. Ou seja, as estatísticas do servidor são opt-out. Defina enabled como false para desabilitar as estatísticas do servidor.

plus.mcp

Esta seção configura o servidor MCP do Bencher. A seção inteira é opcional.

plus.oauth

Esta seção permite que clientes MCP, como o ChatGPT, o claude.ai e o Claude Code, entrem no Bencher MCP com OAuth. O servidor de API passa a ser o servidor de autorização OAuth deles, e os usuários aprovam cada aplicativo no Bencher Console em console.url. A seção inteira é opcional. Se não especificada, o OAuth fica desativado: seus endpoints retornam 404 Not Found, e o Bencher MCP só aceita chaves de API e requisições anônimas.

Uma string JSON não pode conter quebras de linha, então escreva cada quebra de linha de signing_key como \n. Por exemplo, gere uma chave e imprima-a como uma string JSON, sem gravá-la em um arquivo:

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

Para fazer a rotação da chave de assinatura, substitua-a. Isso não desconecta nenhum aplicativo.

O servidor de API serve seus endpoints e metadados OAuth na raiz de issuer. Se um proxy reverso servir o servidor de API sob um prefixo de caminho, como https://bencher.example.com/api, defina issuer como a origem (https://bencher.example.com) e liste a URL completa do endpoint MCP em resources (https://bencher.example.com/api/mcp). O proxy deve então rotear /oauth/, /.well-known/oauth-authorization-server e /.well-known/openid-configuration na origem para os mesmos caminhos no servidor de API, e rotear o caminho de metadados de cada recurso, aqui /.well-known/oauth-protected-resource/api/mcp, para /.well-known/oauth-protected-resource/mcp no servidor de API. Com mais de um recurso, o proxy também deve repassar o cabeçalho Host sem alterações, pois o servidor de API escolhe por ele qual recurso anunciar.