Pular para o conteúdo principal

Runbook Operacional

Introdução ao documento​

Este runbook descreve procedimentos operacionais para execução local, deploy, rollback e troubleshooting do serviço. Evidência: codex-promts.md:214 Evidência: .github/workflows/ci-cd-pipeline.yml:1

Versionamento​

  • Versão do documento: 2.0.0.
  • Última atualização: 2026-03-18. Evidência: codex-promts.md:16

Referencial teórico​

  • Operação baseada em scripts versionados do próprio repositório (npm, Docker, Helm, GitHub Actions). Evidência: package.json:7 Evidência: Dockerfile:1 Evidência: .github/workflows/ci-cd-pipeline.yml:69

Execução local​

Pré-requisitos​

  • Node 18.
  • Dependências NPM instaladas.
  • Arquivo .env com variáveis necessárias. Evidência: package.json:22 Evidência: README.md:44 Evidência: .env.example:1

Comandos​

npm install
npm run dev

Evidência: package.json:10

Smoke test​

curl --request GET --url 'http://localhost:4000/api/liveness'
curl --request GET --url 'http://localhost:4000/api/readiness'

Evidência: src/server.ts:168 Evidência: src/server.ts:176

Deploy​

Pipeline oficial​

  • Build/push da imagem Docker em todas as branches e PRs.
  • Deploy piloto condicionado à branch main.
  • Deploy essencia e prod condicionados à branch release. Evidência: .github/workflows/ci-cd-pipeline.yml:4 Evidência: .github/workflows/ci-cd-pipeline.yml:55 Evidência: .github/workflows/ci-cd-pipeline.yml:80 Evidência: .github/workflows/ci-cd-pipeline.yml:105

Comando-base de deploy (mesmo padrão do workflow)​

helm dependency build helm
helm upgrade --install --create-namespace -n <namespace> <release> helm \
  -f kubernetes/<cluster>/<namespace>/values.yaml \
  --set image.repository=<registry/repository/service> \
  --set image.tag=<sha>

Evidência: .github/workflows/ci-cd-pipeline.yml:71 Evidência: .github/workflows/ci-cd-pipeline.yml:72 Evidência: .github/workflows/ci-cd-pipeline.yml:74

Rollback​

Rollback Helm por revisão (inferência operacional baseada em uso de Helm no pipeline)​

helm -n <namespace> history <release>
helm -n <namespace> rollback <release> <revision>
helm -n <namespace> status <release>

Evidência: .github/workflows/ci-cd-pipeline.yml:71

Rollback por imagem SHA anterior​

helm upgrade --install --create-namespace -n <namespace> <release> helm \
  -f kubernetes/<cluster>/<namespace>/values.yaml \
  --set image.repository=<registry/repository/service> \
  --set image.tag=<sha-anterior>

Evidência: .github/workflows/ci-cd-pipeline.yml:49 Evidência: .github/workflows/ci-cd-pipeline.yml:74

Comandos úteis​

  • Build local:
npm run build
npm run start

Evidência: package.json:8 Evidência: package.json:9

  • Docker local:
docker compose up --build -d
docker compose logs -f onboarding-api

Evidência: docker-compose.yml:2 Evidência: docker-compose.yml:6

  • Diagnóstico de status:
curl --request GET --url 'http://localhost:4000/api/status'

Evidência: src/server.ts:204

  • Queue worker (logs de falha):
rg -n "GroupLinkWorker|Erro ao enfileirar" src

Evidência: src/workers/groupLinkDispatchWorker.ts:130 Evidência: src/flows/personal.ts:215

Troubleshooting (5 incidentes mais prováveis)​

1) 401/403 nos endpoints protegidos​

  • Sintoma: chamadas para /otp, /sendtemplate ou /sendreminder retornam 401/403.
  • Diagnóstico: validar presença de Authorization e valor de SERVICE_TOKEN.
  • Correção: ajustar token no caller e no runtime. Evidência: src/auth/serviceToken.ts:7 Evidência: src/auth/serviceToken.ts:22 Evidência: src/auth/serviceToken.ts:30

2) Erro 500/421/432 no callback POST /​

  • Sintoma: falhas no processamento de flow.
  • Diagnóstico: validar PRIVATE_KEY, PASSPHRASE, assinatura x-hub-signature-256 e campos criptografados.
  • Correção: atualizar chave privada/pública e segredo de assinatura. Evidência: src/server.ts:103 Evidência: src/server.ts:116 Evidência: src/server.ts:128 Evidência: src/encryption.ts:45

3) Readiness retornando 503​

  • Sintoma: pod sem prontidão.
  • Diagnóstico: verificar conectividade SQLite/path e erro de db.authenticate().
  • Correção: corrigir DATABASE_PATH/permissões do volume e reiniciar aplicação. Evidência: src/server.ts:180 Evidência: src/server.ts:192 Evidência: src/config/database.ts:5
  • Sintoma: envios não chegam e logs mostram retries/falha definitiva.
  • Diagnóstico: inspecionar tabela GroupLinkDispatchQueue e logs GroupLinkWorker.
  • Correção: revisar credenciais WhatsApp e limites de retry/delay. Evidência: src/workers/groupLinkDispatchWorker.ts:121 Evidência: src/workers/groupLinkDispatchWorker.ts:130 Evidência: src/workers/groupLinkDispatchWorker.ts:145

5) Webhook Meta não verifica (GET /webhook retorna 403)​

  • Sintoma: validação de webhook falha no setup da Meta.
  • Diagnóstico: conferir WEBHOOK_VERIFY_TOKEN no ambiente e no painel Meta.
  • Correção: alinhar token e repetir validação. Evidência: src/routes/webhook.ts:89 Evidência: src/routes/webhook.ts:95

Pendências​

  • Validar procedimento oficial de rollback com o time de plataforma (o repositório só evidencia comandos de upgrade/install).
  • Confirmar se há observabilidade centralizada externa (APM/SIEM) além de console.*. Evidência: .github/workflows/ci-cd-pipeline.yml:71 Evidência: src/server.ts:62