Operação

Aqui você leva o Load Balance do código local até o ar: o caminho real do deploy, as migrations que valem para todo ambiente, a chave que cifra as chaves de provedor e os portões que provam que a mudança não quebrou nada. Você também encontra o que verificar quando o container não sobe ou quando uma chave aparece em texto puro.

Pré-requisitos#

Antes de qualquer operação você precisa destes quatro itens:

Tudo isso passa por um schema Zod único, executado no import do módulo de env: o ZodError vira Environment validation failed: e derruba o processo. Em produção quatro travas são throw, não warn — AUTH_DISABLED=true, COOKIE_SECRET vazia, COOKIE_SECRET menor que COOKIE_SECRET_MIN_LENGTH = 32 e CORS_ORIGINS vazia. O motivo está escrito no código: “operadores esquecem env vars e o serviço sobe silenciosamente aberto”.

Topologia#

São quatro processos e duas superfícies. O painel administra; o proxy e a API de painel vivem no mesmo processo Fastify, o que faz o /health cobrir os dois.

O compose.override.yml da raiz define só três deles — postgres, redis e backend — e é explicitamente para dev local. Ele não declara command: de propósito, e leva AUTH_DISABLED: 'true' e TRUST_PROXY_HOPS: '0'. Não copie esse arquivo para um host de produção.

Deploy#

Não existe CI. O fluxo real tem quatro passos manuais, nesta ordem.

1. Passe GIT_SHA como build-arg

   O backend/Dockerfile tem ARG GIT_SHA=unknown e o expõe como ENV GIT_SHA. Nada reescreve esse valor: o painel preenche o build-arg à mão, por deploy.

   copiar

   bash

   # no painel, ao construir a imagem do backend
   --build-arg GIT_SHA=<sha curto da main>

2. Passe os três build-args do painel, no mesmo deploy

   O frontend/Dockerfile precisa de VITE_API_URL, VITE_PROXY_PUBLIC_URL e GIT_SHA. O Dockerfile explica por que cada um existe: sem VITE_PROXY_PUBLIC_URL o painel mostra e copia a URL do SPA em vez da do proxy, que é o host do backend — foi um defeito reportado pelo dono. Sem GIT_SHA o buildStampPlugin grava desconhecido no index.html. Os dois args têm de entrar juntos: um build que carimba desconhecido e mostra a URL do SPA é o estado em que a validação de tela acontece com menos informação.

   copiar

   bash

   --build-arg VITE_API_URL=https://painel.exemplo \
   --build-arg VITE_PROXY_PUBLIC_URL=https://proxy.exemplo \
   --build-arg GIT_SHA=<sha curto da main>

3. Publique pelo painel, lado alterado

   Push em main não constrói imagem nem reinicia container. O build usa a branch configurada e dispara o deploy daquela imagem; se você mexeu no painel, publique só o painel, e vice-versa.

4. Prove que o código no ar é o que você quer

   Com o CI desligado, o assert-build-fresh é a única resposta verificável para “qual código está no ar?”. Ele compara o sha que o /health devolve contra a sua ref local, por revisões git — não por hash de bundle, mtime nem artefato de build.

   copiar

   bash

   curl -s https://proxy.exemplo/api/health > /tmp/health.json
   cd backend && npm run assert:build-fresh -- --health-json /tmp/health.json

   bash

   [assert-build-fresh] sha no ar: b71f9c3
     ref main -> b71f9c3
   [assert-build-fresh] VERDE: o build no ar é o mesmo código da ref (b71f9c3).

O gate tem seis vereditos, e só um devolve 0 sem ressalva.

No servidor de produção, o frontend/server.js serve o build/ como estático e faz proxy de /api, /auth/sso e /auth/callback. Sem API_ORIGIN ele serve só estáticos e /api devolve 404, esperando um reverse proxy externo.

Migrations#

As migrations rodam no CMD do Dockerfile do backend, não no compose e não num job separado:

CMD ["sh", "-c", "npx prisma migrate deploy && node dist/index.js"]

Esse é o único ponto que vale para todo ambiente — compose local, Easypanel, Fly, Railway, k8s, docker run puro. As migrations viviam só no command: do compose, que é lido apenas no dev; as plataformas que buildam pelo Dockerfile ignoravam aquele command: e subiam código novo contra banco antigo. Foi a causa do incidente B-A6-017: o backend passou a fazer SELECT de uma coluna que ainda não existia e derrubou /api/stats e todo o proxy com P2022.

O && é deliberado: se a migration falhar, o servidor não sobe. O shell encerra com código diferente de zero e o node dist/index.js nunca executa.

São 21 entradas em backend/prisma/migrations/: 20 pastas de migration e o migration_lock.toml, de 20260922144123_init a 20261012120000_group_hedge_config. Duas compartilham o prefixo 20260929000000, o que o Prisma aceita porque ordena alfabeticamente pelo nome completo.

Fora do container, o script npm equivalente roda o mesmo comando — ele serve para inspecionar o estado do schema sem subir aplicação:

cd backend && npm run prisma:migrate

Segredos#

A variável que decide se as chaves de provedor são cifradas ou gravadas em claro é KEY_ENCRYPTION_KEY: base64 de 32 bytes.

openssl rand -base64 32

Quando presente e não-vazia, ela precisa decodificar para exatamente 32 bytes — senão o boot falha em qualquer ambiente. O complemento de rotação é KEY_ENCRYPTION_KEY_PREVIOUS.

A cifragem é AES-256-GCM, com o formato armazenado enc:v1:::: em base64url sem padding e IV de 12 bytes aleatório por cifragem. O kid é k1 (atual) ou k0 (anterior, durante a rotação). São três alvos: ApiKey.key, ApiKey.refreshToken e os tokens dentro de ApiKey.metadata.

O AAD amarra o valor cifrado à linha e ao campo (loadbalance:apikey::), então trocar um valor cifrado de linha ou de campo faz a decifragem falhar — não passa em silêncio.

Sem a chave, a escrita de segredo cai em texto puro (legado) com console.warn. A leitura de um valor cifrado falha fechada: o processo nunca manda enc:v1:... ao provedor. No boot, assertSecretsReadable roda logo após connectDatabase() e varre toda linha de api_keys com segredo cifrado, cobrindo a API e os jobs — que são o mesmo processo.

O backfill e a ordem segura

Cifrar um banco que já tem chaves em claro é feito por backend/scripts/backfill-secrets.ts, idempotente — rodar duas vezes dá o mesmo resultado.

A chave é obrigatória inclusive no --dry-run: sem ela o plano de ida não cifra nada e contaria 0. O script lê e grava com o PrismaClient puro, sem extensions, sobre os valores crus; trabalha em lotes por cursor de id com uma transação por lote — ou o lote inteiro entra, ou nada entra. As flags são --dry-run e --batch=N, com 200 como default.

A ordem de produção não é negociável:

Trabalhando no código#

Os dois apps têm portões diferentes, porque são dois apps independentes — não é monorepo com workspaces, cada um tem seu package.json e seu package-lock.json.

Painel: um portão só

O gates é a porta única do frontend. Com o CI removido do repositório, ele é o único portão que existe:

cd frontend && npm run gates
# check-lock → typecheck → lint → cycles → format:check → test → test:a11y → build

Backend: sem agregador

O backend não tem comando agregador equivalente. Rode os que importam:

O test:it resolve as duas variáveis do ambiente e, se faltarem, de backend/.env — só as chaves TENANCY_IT_*; o resto do .env nunca entra no processo do teste. Ele não roda containers: quem cria o schema e o banco Redis é o test/globalSetup.ts, um por execução (o PID), justamente para que o TRUNCATE … CASCADE global de um arquivo não atravesse o outro.

O relatório é apagado antes de cada rodada. Sem isso, um vitest que morre antes de escrever o JSON deixa o relatório da rodada anterior e o gate leria como se fosse o de agora.

Se nenhuma das duas variáveis existir, o test:it imprime um aviso e roda a suíte assim mesmo — de propósito, “para que o gate possa dizer quantos testes foram deixados de fora”. Ele não faz exit. O banco de teste precisa ser descartável.

Os códigos de saída são 1 se reprovou, 2 para flag desconhecida e 0 no sucesso. Ele reprova em cinco casos independentes: relatório ausente, relatório sem os campos de contagem, contagem total zero (o “verde mais silencioso que existe”), teste pulado — nomeando cada arquivo — e teste falhando.

Importar muitas chaves#

Para subir um lote grande num grupo, o caminho é backend/scripts/import-keys-lote.ts. Ele usa o mesmo caminho da UI (loadBalancer.addKey por chave), então a tenancy e a cifragem do key no banco acontecem sozinhas, e os caches do pool em Redis são invalidados a cada inserção — depois do --apply as instâncias do LB passam a ver as chaves sem restart.

O arquivo de chaves tem uma chave por linha. Linha vazia ou começando com # é ignorada; o valor pode vir cru ou como nome=valor / nome: valor, e nesse caso só o valor entra.

cd backend
npx tsx scripts/import-keys-lote.ts \
  --provider=openrouter \
  --group=lote-marco \
  --file=/tmp/chaves.txt

org: workspace_nommand (…)
grupo 'lote-marco' não existe — seria CRIADO (strategy round_robin) no --apply
provider=openrouter baseUrl=https://openrouter.ai/api authType=api_key chaves=240 nomes=lote-marco-001..lote-marco-240 active=true cifragem=ON
--- dry-run: nada foi escrito. Releia os prefixos abaixo e rode com --apply ---
  lote-marco-001  sk-or-…(68)
  … +230

Nenhum valor de chave aparece no log. O mascaramento mostra os 4 ou 6 primeiros caracteres mais o comprimento, e o relatório final mostra só contagens e prefixos. O próprio cabeçalho do script é explícito: o arquivo de chaves e as envs ficam só na máquina que executa — nunca cole chave em argumento de comando nem em log.

O script também recusa, antes de escrever: chave repetida no arquivo, nome que já existe naquela org (nomeando até 10), provider desconhecido e --name-width fora da faixa 1 a 10. Os nomes saem numerados com o prefixo que você definir em --name-prefix, começando em --start; a org dona é --org.

Depois do --apply, ele relê a coluna crua com um cliente puro e confirma que nada entrou em texto puro — se algo entrar, ele falha nomeando as linhas:

OK: 240/240 chaves em 'lote-marco' em 4.7s; 240 linhas no banco, 0 em texto puro (esperado: 0)

Para ver os ids e a baseUrl padrão dos providers antes de importar, rode --list-providers. Ele funciona sem banco: só precisa de um DATABASE_URL qualquer no ambiente para o schema Zod passar.

Quando algo está errado#

Os quatro sintomas que mais aparecem em produção, cada um com o que procurar e o que fazer.

Chave de provedor aparece em texto puro

Sintoma: a verificação final do import reporta texto puro, ou o seu próprio SQL — um SELECT LEFT(key, 7) — mostra algo que não começa com enc:v1.

COOKIE_SECRET curta ou vazia

CORS_ORIGINS vazia em produção

Banco fora de sync e o container não sobe