Visão geral do Load Balance
O Load Balance é um gateway de chaves de API: fica entre o seu cliente e os provedores upstream e escolhe, requisição a requisição, qual credencial atende. Esta página é o mapa — o que ele faz, o que você administra e onde ler sobre cada parte.
Comece por Quickstart — proxy: você aponta o cliente para uma URL do LB e recebe 200. Depois volte para cá para entender o que aconteceu por baixo.
Pré-requisitos#
Para usar o LB como cliente você precisa destes três itens, nesta ordem.
POST /v1/messages; o Claude Code ainda dispara um HEAD / de preflight contra ANTHROPIC_BASE_URL antes da primeira requisição real.organizationId é recusada com 403.sk-lb- pessoal ou de serviço. Só conta valor com esse prefixo, venha de x-api-key ou de Authorization: Bearer.Para administrar o LB você entra pelo painel, com a conta da Conta Nommand. Os papéis são OWNER, ADMIN e MEMBER, comparados por ranking — e quem nega acesso de verdade é o backend, não o menu.
As duas superfícies#
O produto tem duas superfícies, e elas não se misturam. Uma entrega tráfego; a outra administra o tráfego.
sk-lb-, escolhe a chave upstream e devolve a resposta. As rotas são POST /{orgSlug}/{customUrl}/v1/messages e o count_tokens irmão, sem prefixo de versão.3016, falando com o backend Fastify na 3018. Cadastra chaves, define estratégias, vê o log e corta limites.O que o Load Balance faz#
Antes de escolher uma chave, o LB tira da frente quem não pode atender agora: contas fora da janela de uso e chaves em cooldown. Depois disso, a estratégia do grupo decide. São cinco, e o padrão é round_robin.
round_robin — cursor incremental por grupo, módulo do tamanho da lista. Com uma chave só, ela atende sempre.priority — a primeira chave disponível do snapshot, que vem ordenado por priority asc. Uma chave de priority alta que dá 429 cascateia para a próxima antes de parar.rated — a de menor score entre as disponíveis, combinando TTFT, latência total e taxa de erro.hedge — a primária é escolhida como no rated; a reserva sai depois, por um atraso escalonado antes do primeiro token.race — a primária é a mesma; as concorrentes saem do mesmo ranqueamento, todas no instante zero.Em volta disso, o mesmo caminho trata o resto do trabalho: um 429 de uma chave põe aquela chave em cooldown em vez de desativá-la, todo non-2xx é retentável na próxima chave da lista, e o corpo é re-sanitizado do zero a cada tentativa porque cada chave pode ter o próprio formato de upstream. Se todas as contas estiverem fora da janela, a resposta é um 429 imediato com Retry-After real, sem tocar em nenhum provedor.
O LB também é onde a resposta é saneada antes de chegar a você: só bytes SSE válidos passam, o tempo até o primeiro token é carimbado no instante em que o primeiro byte útil atravessa, e o upstream nunca vaza — um erro terminal vira 503 genérico.
O LB resolve qual adapter atende pelo nome do provedor, pelo authType ou pela heurística do host da baseUrl, e converte o corpo para o formato nativo daquele provedor. O seu cliente continua falando Anthropic. A tabela completa está em Provedores upstream.
As duas chaves#
Este é o conceito que mais gera confusão, e é o que separa você de quem administra. Existem duas credenciais no mesmo caminho, e elas nunca se tocam.
# o que o SEU cliente envia
x-api-key: sk-lb-...
# o que o LB injeta no upstream, ja convertido
Authorization: Bearer sk-ant-oat01-...| Chave | Quem tem | Onde vive | Onde aparece |
|---|---|---|---|
sk-lb- | Você e a sua equipe | Banco, guardada só como hash — o segredo volta uma vez, na criação | No header x-api-key ou em Authorization: Bearer da requisição que seu cliente faz |
| Chave de provedor | O administrador, no painel | ApiKey, com baseUrl, authType e headers próprios | No header que o adapter injeta, já no formato do provedor |
A chave sk-lb- é removida dos headers logo depois da autorização: ela nunca segue para o upstream. É por isso que uma chave de serviço é revogável sem tocar em nenhuma credencial de provedor, e por isso que revogar a sua não derruba ninguém além de você.
Quando o contrato da empresa acaba na Conta, a resposta é 403 com error.code igual a ORG_SUSPENDED. Nada foi revogado: a mesma chave volta a valer se a empresa contratar de novo. É por esse código estável que o seu cliente distingue uma coisa da outra.
O painel#
As telas do painel e quem entra em cada uma. O menu esconde o item por papel; a rota nega o acesso direto pela URL; o backend é quem recusa de fato.
| Tela | O que você faz nela | Quem entra |
|---|---|---|
| Visão geral | KPIs e feed de tráfego em tempo real | Qualquer autenticado |
| Logs de requisições | Log paginado de requisições, com filtro e realtime | Qualquer autenticado |
| Métricas e Insights | Agregados por janela e leitura analítica do tráfego | Qualquer autenticado |
| Configs de URL | Quais URLs o proxy atende, e com quais chaves | Qualquer autenticado |
| Chaves de API | CRUD das chaves de provedor upstream | ADMIN |
| Limites de uso | As janelas de 5 h e semanal dos planos | ADMIN |
| Chaves de URL | Emissão e revogação das sk-lb- | ADMIN |
| Grupos de chaves | Grupos que rodíziam por estratégia, com arrastar e soltar na ordem de prioridade | ADMIN |
| Grupos de config | Agrupamento de Configs de URL | ADMIN |
| OAuth | Credenciais OAuth dos provedores | ADMIN |
| Minha conta | Perfil, tema e links para a Conta | Qualquer autenticado |
| Plataforma | A área da Nomad, sobre todas as organizações | PLATFORM |
A URL pública exibida e copiada em Configs de URL vem da variável PROXY_PUBLIC_URL, não do host em que o painel está servido — porque o seu cliente fala com o proxy, não com o painel.
Onde os dados vivem#
Duas dependências — Postgres pelo Prisma e Redis. O Postgres guarda o que precisa sobreviver a restart; o Redis guarda o que é quente e descartável.
| Dado | Onde | Identificador |
|---|---|---|
| Credencial de provedor, grupo, URL do proxy, log de requisições, organizações e auditoria | Postgres, via Prisma — 19 models | ApiKey, ApiKeyGroup, RequestConfig, Request, AuditLog |
| Rating de velocidade da chave (TTFT, latência, erros) | Redis | rating:v1:<orgId>:<keyId>, TTL 24 h |
| Cooldown das chaves | Redis, espelhado em Map in-memory | cooldown:<keyId> |
| Janelas de uso de 5 h e semanal por conta upstream | Redis | ulstate:<conta> e ullimit:<conta> |
| Sessão do painel | Redis | dashboard_session:<sessionId>, 7 dias |
O Redis é fail-open por desenho: o rating é um otimizador, e falhar nele não pode derrubar um request. Postgres é diferente — as migrations rodam antes do servidor no boot, e banco fora de sync derruba o container em vez de servir tráfego quebrado.
Próximos passos#
Você tem o mapa. Escolha por onde quer começar:
Depois de dominar o básico, explore além:
sk-lb-.