Deploy e Migrações
Este runbook estabelece os procedimentos operacionais para implantação de código, orquestração de migrações relacionais e rotinas de contingência/rollback da plataforma EcomSmart Agents no servidor de produção (VPS).
Sequência de Inicialização e Dependências
Para evitar falhas de inicialização por dependências ausentes, os containers devem ser iniciados respeitando a seguinte ordem cronológica de prontidão:
flowchart TD
step1[1. Rede Compartilhada: ecomsmart-net] --> step2[2. Bancos de Dados: merchants-db, redis, minio, weaviate]
step2 --> step3[3. Tarefas de Boot: db-migrate e minio-init]
step3 --> step4[4. Core Backend: frontend-entrypoint, genai-wrapper, whatsapp-entrypoint, woocommerce-wrapper]
step4 --> step5[5. Agentes de Negócio: b2c, b2b e marketing]
step5 --> step6[6. Camada Web & Borda: landing, panel, flow-gateway, cloudflare-tunnel]
style step1 fill:#f8fafc,stroke:#64748b,stroke-width:1.5px,color:#1e293b
style step2 fill:#fefce8,stroke:#d97706,stroke-width:1.5px,color:#92400e
style step3 fill:#f0fdf4,stroke:#16a34a,stroke-width:1.5px,color:#166534
style step4 fill:#f0f9ff,stroke:#0284c7,stroke-width:1.5px,color:#0369a1
style step5 fill:#faf5ff,stroke:#9333ea,stroke-width:1.5px,color:#6b21a8
style step6 fill:#f0f9ff,stroke:#0284c7,stroke-width:2px,color:#0369a1
Governança de Migrações (Alembic)
As alterações estruturais no PostgreSQL (schemas platform e genai) são gerenciadas pelo Alembic através do container efêmero db-migrate (infra/db/Dockerfile). O container executa um preflight antes de alembic upgrade heads: ele cria o baseline quando necessário e repara apenas estados históricos conhecidos de alembic_version.
Comandos de Operação de Banco
# Aplicar preflight e todas as migrations pendentes.
# Este é o único comando normal de publicação de schema.
docker compose -f infra/docker-compose.yaml run --rm --no-deps db-migrate
# Consultar as revisões aplicadas diretamente no banco.
docker compose -f infra/docker-compose.yaml exec merchants-db \
psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" \
-c 'TABLE platform.alembic_version;'
Compatibilidade e rollback
Use operações idempotentes quando uma migration puder ser reexecutada com segurança, mas não mascare uma divergência de schema. Migrations destrutivas ou downgrade exigem backup validado e revisão das dependências. Evite DDL longo ou bloqueios exclusivos em horário de pico para não afetar o Agente B2C.
Seed de Dados de Demonstração e Testes
Após a conclusão das migrações do banco, é possível carregar o conjunto de dados demonstrativo (infra/db/seeds/admin_dashboard.sql), que popula 10 lojistas fictícios, planos de créditos, administradores e métricas de campanhas:
docker compose -f infra/docker-compose.yaml exec -T merchants-db \
sh -c 'psql -v ON_ERROR_STOP=1 -U "$POSTGRES_USER" -d "$POSTGRES_DB"' \
< infra/db/seeds/admin_dashboard.sql
Os usuários de teste são provisionados com a senha padrão EcomDemo@2026:
| Usuário | Perfil | |
|---|---|---|
| Super Administrador | marina@seed.ecomsmart.dev |
super_admin |
| Administrador Operacional | rafael@seed.ecomsmart.dev |
admin |
| Administrador Convidado | bianca@seed.ecomsmart.dev |
admin |
Procedimento de Deploy em Produção
Execute este roteiro na VPS para atualizar a plataforma com segurança:
# 1. Navegue para o checkout da VPS e baixe a referência que será publicada
cd <diretorio-do-repositorio>
git fetch origin
git switch <branch-ou-tag-estavel>
git pull --ff-only origin <branch-ou-tag-estavel>
# 2. Compile as novas imagens Docker antes de reiniciar os serviços
docker compose -f infra/docker-compose.yaml build
# 3. Execute o preflight e as migrações de banco pendentes
docker compose -f infra/docker-compose.yaml run --rm --no-deps db-migrate
# 4. Reinicie os containers atualizados
docker compose -f infra/docker-compose.yaml up -d --remove-orphans
# 5. Valide a integridade dos serviços
docker compose -f infra/docker-compose.yaml ps
curl --fail http://127.0.0.1:${FLOW_GATEWAY_PORT:-3080}/health
# 6. Limpe imagens Docker órfãs antigas para economizar espaço
docker image prune -f
Procedimento de Rollback de Emergência
Caso uma nova versão apresente falhas críticas em produção:
- Reverter Código para uma referência previamente validada:
- Avaliar o schema antes de revertê-lo: não execute
downgradecomo etapa automática. Aplique apenas uma migration de reversão revisada, ou restaure um backup compatível, se o código anterior não aceitar o schema atual. - Recompilar e subir os containers:
- Verificar Restauração: Monitore os logs dos agentes B2C e B2B para confirmar que os eventos de WhatsApp foram retomados: