Resolução de Problemas de Instalação

A maioria dos problemas de instalação vem de mismatch de URL, SMTP em falta, portos bloqueados ou segredos perdidos. Começa pelo URL visível no teu browser e trabalha para dentro.

Links públicos abrem no meu computador mas não para clientes

Verifica qual URL foi copiado ou enviado.

• http://localhost/... funciona apenas na mesma máquina.
• http://192.168.x.x/... funciona apenas na LAN ou VPN. VPN pode ser uma ponte válida para equipas internas, mas não é uma estratégia de links públicos para clientes.
• https://crm.example.com/... funciona publicamente apenas quando DNS, HTTPS, proxy e firewall estão corretos.

Para links públicos de clientes, faz deploy com um domínio público usando servidor público Ubuntu ou Coolify.

O browser mostra erros de CORS

O CORS_ALLOWED_ORIGINS deve corresponder exatamente à origem do browser. Estas são origens diferentes:

https://crm.example.com
https://www.crm.example.com
http://crm.example.com
https://crm.example.com:8443

Corrige a variável, faz redeploy e tenta novamente numa sessão de browser fresca.

O email não é entregue

Verifica isto primeiro:

• SMTP_HOST e SMTP_PORT estão corretos.
• SMTP_AUTH=true quando o teu provider requer autenticação.
• SMTP_STARTTLS=true para o porto 587.
• SMTP_USERNAME e SMTP_PASSWORD são válidos.
• O provider permite login SMTP/app-password.
• NOTIFICATIONS_EMAIL_ENABLED=true quando emails de notificação devem ser enviados.

A partilha manual de links públicos e o download de PDF ainda funcionam sem SMTP.

Os links de preferências de notificação estão errados

Define:

NOTIFICATIONS_PUBLIC_PREFERENCES_URL=https://<frontend-domain>/notifications/preferences

Não os deixes a apontar para localhost num deployment público.

Os contentores Docker não estão saudáveis

Executa:

docker compose ps
docker compose logs -f backend
docker compose logs -f frontend
docker compose logs -f gotenberg

Causas comuns:

• O PostgreSQL ainda está a arrancar.
• O DB_PASSWORD difere entre o PostgreSQL e o backend.
• O DB_ENCRYPTION_KEY está em falta ou malformado.
• O Gotenberg não está saudável, logo a geração de PDF não pode arrancar.
• Portos 80/443 do host já estão a ser usados por outro serviço.

Após corrigir a configuração, reinicia o serviço afetado ou a stack:

docker compose restart backend
docker compose up -d

O meu IP está bloqueado — não consigo iniciar sessão

Existem duas causas comuns: a lista de IPs permitidos bloqueou o acesso ou a proteção contra força bruta bloqueou o teu IP após demasiadas tentativas falhadas de início de sessão.

Bloqueio pela lista de IPs permitidos

O QuoteNode tem uma lista de IPs permitidos configurável em Definições > Segurança > Lista de IPs permitidos (ou através da variável SECURITY_IP_WHITELIST). Quando ativa, protege toda a superfície de administração — incluindo os ecrãs de início de sessão e 2FA — pelo que um endereço excluído recebe 403 IP_NOT_ALLOWED e nem sequer consegue iniciar sessão. (Os health checks e os links públicos de propostas para clientes permanecem acessíveis.)

Primeiro aguarda dois minutos se acabaste de a alterar na aplicação. Uma ativação ou restrição na aplicação está protegida contra bloqueios: tem de ser reconfirmada pela tua sessão dentro de uma janela curta (120 s por omissão) e, se o teu endereço atual não estiver abrangido, a lista reverte automaticamente para a anterior. Assim, um autobloqueio acidental a partir do ecrã de Segurança resolve-se sozinho — aguarda e tenta novamente. (Esta rede de segurança não se aplica à variável SECURITY_IP_WHITELIST, que é aplicada no arranque.)

Recuperação (substituição do operador): se continuas bloqueado — p. ex. uma SECURITY_IP_WHITELIST do operador, uma lista guardada inválida ou não podes esperar — adiciona esta variável ao ambiente do contentor backend (.env ou secção environment: no docker-compose) e reinicia:

SECURITY_IP_WHITELIST_FORCE_DISABLE=true

docker compose restart backend

Isto desativa completamente a lista de permitidos e permite iniciar sessão. Após entrar, corrige a lista em Definições > Segurança, depois remove SECURITY_IP_WHITELIST_FORCE_DISABLE e reinicia novamente.

Não deixes SECURITY_IP_WHITELIST_FORCE_DISABLE=true em produção. Desativa todo o controlo de acesso por IP.

Bloqueio pela proteção contra força bruta

O QuoteNode bloqueia endereços IP após demasiadas tentativas falhadas de início de sessão numa hora:

Limiar	Falhas em 1 h	Efeito
Soft	10	Atraso progressivo (1 s por tentativa adicional, máx. 30 s)
Bloqueio temporário	20	Bloqueado durante 5 minutos
Bloqueio permanente	50	Bloqueado até desbloqueio manual

Como desbloquear:

1. Painel de administração — outro administrador abre Definições > Painel de Segurança > IPs bloqueados e clica em Desbloquear.
2. Aguardar — os bloqueios temporários expiram após SECURITY_TEMP_LOCK_MINUTES (5 minutos por defeito). Os bloqueios permanentes não expiram por si.
3. Elevar limiares temporariamente se estiveres bloqueado e nenhum outro admin puder ajudar. Adiciona ao .env, reinicia, inicia sessão e depois remove:

SECURITY_MAX_FAILED_LOGINS_SOFT=9999
SECURITY_MAX_FAILED_LOGINS_TEMP_LOCK=9999
SECURITY_MAX_FAILED_LOGINS_HARD_LOCK=9999

Restaura os valores predefinidos após recuperar o acesso.

Bloqueios de IP em links públicos

O limitador de taxa dos links públicos bloqueia endereços IP que excedem os limites de tentativas. Estes bloqueios estão em memória e expiram após PUBLIC_RATE_LIMIT_IP_BLOCK_MINUTES (60 minutos por defeito) ou após um reinício do backend.

O certificado HTTPS não é emitido

Para deployments públicos:

• O DNS deve apontar para o servidor de deployment.
• Os portos 80 e 443 devem ser acessíveis a partir da internet.
• Apenas um proxy deve terminar HTTPS para o mesmo domínio.
• Na Coolify, atribui o domínio ao serviço frontend.

Perdi o .env

Se perderes o .env, para e avalia antes de rodar valores.

• O DB_PASSWORD pode normalmente ser redefinido com acesso administrativo ao PostgreSQL.
• O TIMING_TOKEN_SECRET e o PUBLIC_LINK_PASSWORD_SESSION_SECRET podem ser regenerados, mas sessões/tokens existentes podem expirar.
• O DB_ENCRYPTION_KEY é crítico. Sem a chave original, valores cifrados não podem ser desencriptados.
• Se a cifragem de PII estiver ativada, campos de cliente/contacto cifrados dependem do DB_ENCRYPTION_KEY.

Restaura o .env a partir de backup sempre que possível.

Recuperação se .env for perdido mas existe cópia de segurança da base de dados

1. Cria um novo .env com novos segredos.
2. Restaura a base de dados a partir da tua cópia de segurança (pg_dump / pg_restore).
3. Todos os dados de negócio (clientes, propostas, produtos, utilizadores) serão totalmente acessíveis.
4. Apenas alguns campos são perdidos: códigos MFA (utilizadores re-inscrevem-se), password SMTP (reinserir nas definições), chave API FX (reinserir). Se ENCRYPT_PII=true estava ativo, os dados de clientes cifrados também são perdidos.

Se as tuas cópias de segurança estão cifradas com age (o padrão), precisas do ficheiro de identidade age do teu kit de recuperação para as desencriptar primeiro. Consulta o guia Backup e Recuperação.

Esqueci a password do administrador

Usa um caminho de recuperação não destrutivo:

1. Se o SMTP estiver configurado, usa a página de início de sessão: Esqueceste a tua password?
2. Se outro administrador consegue iniciar sessão, abre Utilizadores no painel de administração e redefine a password.
3. Se nenhum administrador consegue iniciar sessão e o fluxo de reposição por email não está disponível, restaura o acesso a partir de uma cópia de segurança em bom estado ou usa o teu procedimento de manutenção interno.

docker compose down -v não é um procedimento de reposição de password. Elimina todos os dados — utilizadores, propostas, clientes, definições e cópias de segurança. Usa-o apenas para ambientes de teste descartáveis.

A verificação da licença falha

Para deployments reais, mantém:

LICENSE_SKIP_SIGNATURE_CHECK=false

Se uma licença válida ainda falhar, verifica que o deployment tem a versão esperada da app e um relógio de sistema sincronizado com NTP. Confirma que a licença corresponde à edição/versão deployada, depois contacta o suporte ou substitui o ficheiro de licença através do caminho documentado de operador. Não definas o bypass de assinatura como true como workaround de produção.