Solução de Problemas: Ambiente Dev, Banco de Dados e WuzAPI

Data: 01/01/2026

Este documento registra os problemas críticos encontrados durante a configuração do ambiente de desenvolvimento Chatwoot + WuzAPI e suas soluções definitivas.

1. O Problema do Banco de Dados "Fantasma" (Vazio)

Sintoma: Ao reiniciar, o Rails apresentava erro de migrações pendentes ou PG::UndefinedTable: relation "messages" does not exist, mesmo o sistema tendo funcionado minutos antes. Causa: O ambiente possui duas instâncias de Postgres:

Porta 5432: Instância vazia/quebrada (padrão local ou outro container).
Porta 5438: Instância Docker correta (chatwoot-develop-postgres-1) contendo os dados. O Rails, por padrão, tentava conectar na 5432.

Solução: Forçar a variável de ambiente POSTGRES_PORT no comando de inicialização.

export POSTGRES_PORT=5438

2. O Problema do Ruby/Bundler (Ambiente Shell)

Sintoma: Erros como Gem::GemNotFoundException, ruby 2.6.10 ou Could not find 'bundler'. Causa: O terminal macOS revertia para o Ruby do sistema (2.6) ao abrir novas abas ou reiniciar, ignorando a versão do projeto (3.4.4).

Solução: Sempre reinicializar o gerenciador de versões (rbenv) antes de rodar comandos Ruby.

eval "$(rbenv init -)"

3. O Mistério do "Canal Inativo" (Webhook Ignorado)

Sintoma:

Webhook recebido com sucesso (HTTP 200).
Log do Rails: Inactive WhatsApp channel: unknown - 5561991544165.
Nenhuma mensagem aparecia na tela. Causa: Incompatibilidade de formato telefônico:
WuzAPI: Enviava o remetente como 5561991544165 (Com DDI 55).
Banco de Dados: O canal estava cadastrado como 61991544165 (Sem DDI). O Chatwoot não conseguia casar os números.

Solução: Atualizar o registro no banco de dados para incluir o DDI 55.

# Comando rodado via Rails Runner ou Console
Channel::Whatsapp.find(ID_DO_CANAL).update(phone_number: '5561991544165')

4. Túnel SSH Instável (Serveo)

Sintoma: Mensagens paravam de chegar no Webhook. Causa: O túnel serveo.net encerrava ao fechar o terminal, gerando uma NOVA URL ao reiniciar. Solução: Sempre verificar se o túnel está de pé e se a URL no WuzAPI bate com a URL ativa no terminal.

🚀 O "Comando Mestre" de Reinicialização

Para reiniciar a aplicação garantindo que todos os problemas acima (1 e 2) sejam evitados, use sempre este comando combinado:

eval "$(rbenv init -)" && export POSTGRES_PORT=5438 && (pkill -f rails || true) && (pkill -f sidekiq || true) && (pkill -f foreman || true) && rm -f tmp/pids/server.pid && bundle exec foreman start -f Procfile.dev

O que ele faz:

eval ...: Garante Ruby 3.4.4.
export ...: Garante Banco de Dados correto (Porta 5438).
pkill ...: Mata processos velhos/travados.
rm ...: Remove travas de PID antigas.
foreman start: Inicia tudo limpo.

3.0 KiB Raw Blame History