Referência
O Load Balance tem duas superfícies que não se misturam: o proxy, que o seu cliente chama, e o painel, que o admin administra. Abaixo estão as três referências — o caminho exato, o parâmetro e a resposta — e os guias que explicam cada uma antes de você precisar do detalhe.
Referência ou guia
A referência diz como chamar: rota, parâmetro, resposta. O guia diz por que: a estratégia por trás. Se você está escolhendo uma URL ou uma estratégia agora, abra o guia; quando precisar do endpoint exato, volte para cá.
Proxy — o que o seu cliente chama#
Seu cliente fala com o proxy por uma chave de serviço sk-lb- e uma URL. O proxy escolhe, requisição a requisição, qual das chaves de provedor cadastradas atende. Não há sessão de admin nesse caminho: a autenticação é a própria chave de cliente, validada dentro do handler.
As rotas que o Claude Code, o Codex ou qualquer cliente compatível com a API Messages chama — mensagens, contagem de tokens e o HEAD de preflight — e o que cada uma devolve em caso de erro.
proxy
v1/messages
count_tokens
sk-lb-
HEAD
Como a URL que seu cliente acessa resolve para uma config, quais chaves de serviço podem usá-la e o que a forma legada sem org faz com URLs repetidas.
guia
customUrl
orgSlug
grupos de config
Como o stream atravessa o proxy sem ser cortado, e o que o tempo até o primeiro token diz sobre cada chave antes de você promover o melhor grupo.
guia
SSE
TTFT
streaming
Painel — o que o admin administra#
O painel é uma SPA React servida na porta 3016 que fala com o backend Fastify na 3018. As rotas do backend não têm prefixo: cada arquivo escreve o caminho completo. Toda rota exige sessão por cookie assinado, e toda mutação exige também o header X-CSRF-Token. O piso é automático — GET e HEAD exigem MEMBER; POST, PUT, PATCH e DELETE exigem ADMIN.
Todas as rotas de painel: chaves de provedor, grupos, configs de URL, requests, métricas, modelos, OAuth, organizações e a área de plataforma — com método, papel exigido e resposta.
painel
/api
RBAC
X-CSRF-Token
A ordem em que o LB escolhe a chave upstream dentro de um grupo, o que cada estratégia faz e quando uma chave sai do rodízio.
guia
round_robin
priority
rated
hedge
race
As janelas de 5h e semanal que tiram a conta do rodízio antes de ela estourar o limite do plano upstream.
guia
janela de 5h
semanal
usageCutoffPct
Os adapters que o LB conhece, o que muda entre eles e a conversão de formato que acontece antes de o corpo chegar ao provedor.
guia
providers
adapters
conversão
Configuração — o que o operador define#
As variáveis de ambiente decidem o que o backend sobe e o que ele recusa no boot. Esta seção aponta a lista completa e o comportamento da cifragem de segredos em repouso.
Cada variável lida pelo backend, com o default e o que acontece quando está vazia: as obrigatórias sempre, as obrigatórias só em produção, e as que desligam um recurso inteiro quando ausentes.
config
env vars
boot
retenção
O que a chave de criptografia controla em repouso: o formato enc:v1:, o AAD que amarra linha e campo, a rotação com chave anterior e o que o boot recusa quando a chave não decifra.
segredos
AES-256-GCM
backfill
rotação
Painel de operação — health, WebSocket e limpeza#
Estas rotas são públicas e não passam pelo guard de sessão: é o balanceador e o monitor que as consultam. Elas dizem se a instância está de pé, e são o que você olha quando algo começa a dar errado.
As rotas de operação: /api/health e /api/health/db com 503 quando Postgres ou Redis caem, /api/pool-stats com o in-flight por host, o stream /ws/requests e a limpeza sob demanda.
operação
health
pool
WebSocket
Como ler o que está acontecendo agora: o log de requisições em tempo real, os agregados de tráfego e o que cada métrica responde.
guia
métricas
requests
insights
Os jobs que rodam em processo, a retenção de cada dado, o shutdown e o que você precisa conferir antes de mexer na config em produção.
guia
jobs
retenção
shutdown
Próximos passos#
Escolha por onde continuar.
Depois de dominar o básico, explore além: