Pular para o conteúdo principal

Runbooks

Última atualização: 16/09/2026.

Procedimentos curtos para quando produção (ou HML) quebra. Sempre sanitize logs antes de colar em chat. Canal de segurança: SECURITY.md.

0. Primeiros 5 minutos (qualquer alerta)​

  1. GET /backend/api/health.php — se 503, é env/banco; se 200, o PHP sobe.
  2. docker compose logs --tail=200 app (ou log do painel).
  3. Tabela / arquivo backend/logs/<modulo>/ do horário do incidente.
  4. Confirme se o incidente é só um WL ou global (isso muda rollback).

Não reinicie o container em loop: sessões e uploads estão em volume, mas restart no meio de migration deixa schema pela metade.

Login recusado para todo mundo​

Sintomas: 401 genérico, overlay infinito, rate limit.

HipóteseChecagemAção
Banco forahealth db: falsesubir MySQL, conferir max_connections
DB_* errado no painelwarning no entrypointcorrigir env e recriar container
Cookie secure em HTTPSESSION_SECURE=1 sem TLSalinhar proxy/TRUST_PROXY
Fingerprint UA (app móvel / PWA)logs sessionnão desligar fingerprint; ajustar proxy UA
Rate limit saturadobackend_rate_limitslimpar linhas da ação login daquele IP depois de confirmar que não é brute force

Usuário único inativo: status em users.status. Senha: fluxo forgot.

Health 503 / “limite de conexões”​

Mensagem amigável mapeada em backend_map_exception_for_client.

  1. SHOW STATUS LIKE 'Threads_connected';
  2. Matar sleep queries longas de polling de credenciamento se estiverem empilhadas.
  3. Não aumentar max_user_connections no susto — o PHP abre conexão por request e os *_ensure_schema() pesam.

Dashboard / transações vazios​

  1. Token Movingpay: MOVINGPAY_TOKEN_USAGE_TRANSACOES HML vs PROD.
  2. customer_id bate com o ambiente?
  3. Permissão transacoes.visualizar / dashboard.ver_todos e recorte de WL.
  4. Polling do browser: backend/api/transacoes/polling.php e assets/js/polling-transacoes.js.
  5. Relógio do servidor vs filtro de período.

Credenciamento / terminal preso em pendente​

  1. Logs backend/logs do módulo estabelecimentos / movingpay.
  2. Daemon CLI de polling (polling_background_service.php) — só corre em CLI. Se ninguém disparou o processo, o HTTP de polling precisa ser chamado.
  3. Estabelecimento local vs remoto (listar-remotos).
  4. Após rename Entrepay → Adquirente: código velho falando nome antigo de tabela indica imagem desatualizada.

Upload / Google Drive​

  1. GET /backend/api/storage/drive-health.php (sessão admin).
  2. No container: JSON em backend/secrets/ ou env GOOGLE_DRIVE_SERVICE_ACCOUNT_JSON.
  3. Bind mount do compose exige arquivo no host antes do up.
  4. Pasta GOOGLE_DRIVE_USER_MEDIA_FOLDER_ID compartilhada com a service account (Shared Drive).
  5. nginx client_max_body_size 200m — uploads maiores falham no proxy, não no PHP.

Arquivo local: uploads/ no volume. Sem volume, recriar container “apaga” binários que não foram para o Drive.

Autentique: documento não muda de status​

  1. Webhook chegou? Tabela assinatura_webhook_eventos (event_hash).
  2. Header X-Autentique-Signature vs AUTENTIQUE_SIGNATURE_SECRET.
  3. URL pública do webhook acessível sem sessão (assinaturas/webhook.php).
  4. Token GraphQL (AUTENTIQUE_TOKEN) não expirou.

Tarefas / Comercial sumiram do menu​

  1. tenant_modules para tasks / módulo comercial daquele white_label_id.
  2. Flags tarefas.* / leads.* no usuário e no escopo do WL.
  3. Fail-safe: exceção na consulta de módulo esconde o grupo inteiro — veja log PHP.

Comissões divergentes​

  1. Confirme modelo de taxa (MDR vs custo efetivo) do WL.
  2. Período e estabelecimento filtro.
  3. API externa financeiro/external/comissoes.php usa token, não cookie. Token vazado: revogue em financeiro_api_tokens e emita outro.
  4. Não recarregue apuração em cima de export já enviado ao parceiro sem registrar o recálculo.

CPU / disco​

  • Logs JSON sem rotação: truncar backend/logs com mais de N dias (manter 14 dias em prod, 3 em HML) depois de backup.
  • Polling agressivo no browser: várias abas do dashboard.
  • ensure_schema em todo request de módulo novo — sintoma de schema ainda não aplicado; rode a migration e o custo cai.

Incidente de segurança (vazamento / auth bypass)​

  1. Não discuta PoC em issue pública.
  2. Rotacione todos os segredos que possam ter saído (DB, Movingpay, Autentique, Drive, SMTP, OpenAI, tokens financeiros).
  3. Invalide sessões (apague o volume sessions ou os arquivos em backend/storage/sessions).
  4. Siga SECURITY.md e registre request_id dos logs.

Contatos​

  • Código / deploy: time dono do repo (CODEOWNERS).
  • Banco: DBA / painel do MySQL do ambiente.
  • Gateway: suporte Movingpay / Autentique / PayUp com o customer_id de HML/prod correto (nunca misturar).