Wiki Bravonix › Infraestrutura › Adapter (LGPDQuest)

Ambientes do Adapter

Página de referência · atualizada em 18 de agosto de 2026

Esta página explica o que são os três ambientes do Adapter, por que eles existem separados e o que muda de um para o outro. Não contém credenciais.

Um ambiente é uma cópia completa e independente do sistema: tem os próprios servidores, o próprio banco de dados e o próprio endereço na internet. Desde agosto de 2026 o Adapter tem três — desenvolvimento, homologação e produção —, todos governados por um único painel de implantação, numa rede privada em São Paulo.

A ideia é a mesma de uma peça de teatro: o ensaio (dev) pode errar à vontade, o ensaio geral (homologação) tem figurino e plateia convidada, e a estreia (produção) é para o público pagante. O texto é o mesmo; o que muda é o custo do erro.

Conteúdo
  1. Os três ambientes
  2. Anatomia de um ambiente
    1. Um domínio, dois backends
    2. Uma branch por ambiente
  3. Como o código chega
  4. Dados e chaves
  5. Observabilidade
  6. Backup
  7. Convenção de nomes
  8. Problemas comuns
  9. Glossário

1. Os três ambientes

Cada ambiente tem um par de endereços: um para a interface que a pessoa usa, outro para a API que a interface consulta.

AmbienteEndereçosPara que serveTem dado real?
Desenvolvimentodev.adapter.bravonix.ia.br
api.dev.adapter.bravonix.ia.br		Integração contínua do time. Nasceu vazio.Não
Homologaçãohomolog.adapter.bravonix.ia.br
api.homolog.adapter.bravonix.ia.br		Validação antes de produção.Sim
Produção (nova)prod.adapter.bravonix.ia.br
api.prod.adapter.bravonix.ia.br		Ambiente-alvo, rodando em paralelo com a produção atual.Sim (cópia)
A produção que atende clientes ainda é a antiga Quem atende cliente hoje é adapter.lgpdnow.com.br, com API em adapter.bravonix.api.br, na infraestrutura anterior. O endereço prod.adapter.bravonix.ia.br roda com uma cópia dos dados e existe para validação. Os dois convivem até a virada de DNS ser autorizada. Não mande cliente para o endereço novo.
Por que produção não segue o padrão de domínio Ambientes internos ficam na zona bravonix.ia.br. A produção fica em lgpdnow.com.br porque é o endereço que os clientes já usam — trocá-lo é decisão comercial, não técnica.

2. Anatomia de um ambiente

Os três têm o mesmo desenho, o que é intencional: se o dev funciona, homologação e produção devem funcionar do mesmo jeito. Cada um tem cinco aplicações e quatro bancos.

PeçaTipoO que faz
adapteraplicaçãoInterface web, servida por nginx
adapter-apiaplicaçãoAPI principal (Koa) — dona do login e dos processos
bravocoreaplicaçãoAPI de IA/RAG, admin Django e documentação da API
bravocore-celery-workeraplicaçãoProcessamento assíncrono: ingestão de documentos, agentes
bravocore-celery-beataplicaçãoDispara as tarefas agendadas
adapter-db, bravocore-dbbancoPostgreSQL com pgvector
2 × RedisbancoFila de tarefas e cache
O worker consome a fila; o beat apenas alimenta a fila com tarefas na hora marcada. Nenhum banco tem porta aberta para a internet.

Fora do ambiente ficam duas coisas compartilhadas ou paralelas: um bucket de arquivos por ambiente e o Langfuse, que é único para os três.

2.1. Um domínio, dois backends

O endereço de API de cada ambiente atende duas aplicações diferentes, separadas por caminho:

CaminhoVai para
/api · /admin · /staticbravocore (Django)
todo o resto (/)adapter-api (Koa)
Dois logins parecidos, em aplicações diferentes POST /v1/auth/login é o login do Adapter. POST /api/v1/auth/login/ é o login do BravoCore. Chamar a rota errada devolve 401 e parece senha inválida — é o engano mais comum desta arquitetura.
O admin do Django fica em /administrator/, mas a regra diz /admin /admin não existe como rota da aplicação. Ele aparece na tabela porque a regra de roteamento casa por texto, não por segmento: /administrator começa com /admin, então é essa regra que leva o tráfego até o Django. Remover /admin por parecer inútil derrubaria o painel administrativo.

2.2. Uma branch por ambiente

RepositórioDevHomologaçãoProdução
adapterdevhomologmain
adapter-apidevhomologmain
BravoCoredevelophomologmain
O BravoCore usa develop, não dev É a única exceção. Apontar a branch errada falha já no clone, e o painel mostra apenas um erro genérico — não diz que a branch não existe.

3. Como o código chega no ambiente

Não há passo manual: o merge é o gatilho.

  1. Merge na branch do ambiente — o repositório avisa o painel, que enfileira a implantação.
  2. Build numa máquina dedicada — a imagem é construída fora do servidor do ambiente, para que o build não roube recurso de quem está usando o sistema.
  3. Publicação no registry privado — a imagem vai para <aplicação>-<ambiente>, com o commit como etiqueta.
  4. Troca do container — o servidor do ambiente baixa a imagem e substitui o que estava rodando.
Cada ambiente tem seu próprio repositório de imagem O mesmo commit em ambientes diferentes gera imagens diferentes, porque as variáveis usadas no build também são diferentes. Por isso a imagem de homologação nunca é reaproveitada em produção.
Deploy que dá certo derruba o site por alguns segundos; deploy que falha, não Parece contraintuitivo. Quando a implantação conclui, o container antigo é substituído pelo novo, e nessa troca há alguns segundos de erro 502. Quando ela falha no build, nada é trocado e o serviço segue no ar. É isso que decide a janela de deploy em ambiente que atende usuário.

Ressalva: falha por esgotamento de recurso da máquina (memória, por exemplo) pode, sim, deixar containers pela metade — o "não derruba nada" vale para erro de build, não para máquina saturada.
A variável do front é de build, não de execução O endereço da API que a interface usa é gravado dentro do pacote na hora do build. Mudar a variável sem refazer o build não muda nada — e o sintoma é o login falhar, o que leva a procurar no lugar errado.

4. Dados — o que cada ambiente contém

AmbienteOrigem dos dadosContém dado pessoal?
DesenvolvimentoNasceu vazio, sem restauraçãoNão
HomologaçãoRestaurado do ambiente antigo de homologaçãoSim — há usuários reais de cliente na base do BravoCore
Produção (nova)Cópia da produção atualSim
Cada ambiente tem chaves de criptografia próprias O BravoCore guarda e-mail cifrado no banco, e o Adapter cifra dados de segundo fator. Restaurar um dump de um ambiente em outro sem levar as chaves não dá erro de implantação: o ambiente sobe, responde normalmente, e os campos cifrados aparecem como lixo — com usuários que não conseguem entrar. Numa migração de produção, as chaves são copiadas da origem, nunca geradas.

Com senha de banco e de Redis vale o contrário: são novas em cada ambiente, porque autenticam em vez de cifrar.
Dev é uma barreira deliberada, não descuido As chaves de dev são diferentes das de homologação justamente para que um dump com dado real não funcione lá. Reproduzir um bug com dado de homologação exige levar as chaves junto — e isso passa a ser uma decisão consciente sobre dado pessoal, não um passo de rotina.

Cada ambiente também tem bucket de arquivos próprio, com credencial restrita a ele: credencial de dev não alcança arquivo de produção, e apagar um documento no ambiente novo não toca no arquivo do cliente.

5. Observabilidade — um Langfuse para os três

Os três ambientes enviam rastros de execução para uma instância só do Langfuse, em langfuse-2608.bravonix.ia.br, com um projeto por ambiente. As instâncias antigas continuam no ar apenas para consulta do histórico — nada novo é gravado nelas.

Tracing falha em silêncio Quando o endereço do Langfuse está errado, a aplicação não dá erro, não fica lenta e não registra nada no log: os rastros simplesmente não aparecem. Se um ambiente sumir do Langfuse, o primeiro lugar a olhar é a variável que aponta para ele.

6. Backup

O que é salvoFrequênciaOnde
Os bancos dos três ambientesDiário, em horários escalonadosBucket por ambiente
Configuração do painel — variáveis e acessos dos trêsDiárioBucket próprio
Volumes do LangfuseDiárioBucket próprio
Retenção de 14 dias, com credencial restrita por bucket — backup de produção não é alcançável por credencial de dev.

Há alerta por e-mail em três situações: quando um backup falha, quando o arquivo não chega ao destino e — a mais importante — quando o backup deixa de rodar. A falha silenciosa é a que mais engana, porque a ausência de erro parece sucesso.

As restaurações foram testadas de ponta a ponta Cada uma em destino descartável, comparando contagem de tabelas e de linhas com o original. Conferir que o arquivo chegou ao destino não é conferir que ele restaura algo — e a diferença entre os dois só aparece quando alguém restaura de verdade.
O backup mais importante não é o dos ambientes É o da configuração do painel: ele guarda as variáveis e as chaves de acesso dos três ambientes de uma vez. Perder essa máquina sem cópia é perder a configuração dos três — e a cópia só serve junto com a chave que decifra as variáveis.

7. Convenção de nomes

Servidores seguem bvx-<NN>-<ambiente>-<AAMM>: número apenas para ambiente, infraestrutura sem número, e a data de criação no fim — nessa ordem porque só assim a listagem alfabética fica em ordem cronológica.

O nome do servidor não diz quem está servindo o endereço A regra nasceu de um problema real: nomes com "novo" e "produção" espalhados por máquinas que serviam outra coisa. Quem responde por um domínio é o DNS, não o nome da máquina. Na dúvida, consulte o DNS.

8. Problemas comuns

SintomaCausa provávelO que fazer
Login devolve 401 com credencial certaRota trocada entre Adapter (/v1/auth/login) e BravoCore (/api/v1/auth/login/)Conferir qual das duas aplicações deveria autenticar
Login falha depois de mudar o domínioO endereço da API no front é de buildAtualizar a variável e refazer o build
Caminho da API responde 404 vindo da aplicaçãoPrefixo do caminho sendo removido antes de chegar no backendVerificar se a aplicação já serve naquele caminho
Deploy falha logo no início, sem log útilBranch inexistente — o BravoCore usa developConferir a branch configurada
Ambiente sobe, responde 200, mas quebra no primeiro usoBanco vazio: migrações não aplicadasConferir se o passo de migração rodou na implantação
Rastros pararam de aparecer no LangfuseEndereço do Langfuse errado — falha silenciosaConferir a variável e o projeto de destino
Erro 502 por alguns segundosTroca de container em implantação bem-sucedidaComportamento esperado; escolher a janela
Página responde 502 de forma permanenteRoteador apontando para a porta errada do containerDeclarar a porta explicitamente no domínio

9. Glossário

Ambiente
Cópia completa e independente do sistema, com servidores, banco e endereço próprios.
Container
Pacote isolado que roda uma aplicação com tudo de que ela precisa.
Imagem
O molde a partir do qual um container é criado. Construir a imagem é o "build".
Registry
Repositório onde as imagens ficam guardadas para os servidores baixarem.
Branch
Linha de desenvolvimento no repositório. Cada ambiente acompanha uma.
Migração (migration)
Script que altera a estrutura do banco. Roda na subida da aplicação.
Rastro (trace)
Registro do caminho de uma requisição de IA, usado para depurar e medir custo.
Bucket
Espaço de armazenamento de arquivos na nuvem, separado do banco.

Onde estão as credenciais: acessos ao painel, aos bancos e às contas de serviço ficam com a equipe de desenvolvimento — nunca nesta página. Solicite ao responsável pelo ambiente.

Página de referência interna da Bravonix. O endereço é público mas não indexado; trate como documento interno.