Skip to main content

Manual de administração

🔧 MANUAL DE ADMINISTRAÇÃO DO SISTEMA

Krayin CRM + Evolution API + n8n
Versão 2.1 | Janeiro 2026

📋 Sumário

  1. Visão Geral da Arquitetura
  2. Acesso Administrativo
  3. Gestão de Usuários
  4. Configuração do Krayin CRM
  5. Integração Evolution API (WhatsApp)
  6. Automações com n8n
  7. Backup e Recuperação
  8. Monitoramento e Logs
  9. Segurança
  10. Troubleshooting Avançado
  11. Manutenção Periódica

1. Visão Geral da Arquitetura

1.1 Stack Tecnológico

O sistema é composto por 3 componentes principais:

┌─────────────────────────────────────────────────────┐
│                                                     │
│  🌐 NGINX (Proxy Reverso)                          │
│                                                     │
├───────────────┬──────────────┬──────────────────────┤
│               │              │                      │
│  📊 KRAYIN    │  💬 EVOLUTION│  🔄 N8N              │
│  CRM          │  API         │  (Automações)        │
│               │  (WhatsApp)  │                      │
│  Laravel      │  Node.js     │  Node.js             │
│  PHP 8.2      │  TypeScript  │  Workflows           │
│               │              │                      │
└───────┬───────┴──────┬───────┴───────┬──────────────┘
        │              │               │
        ▼              ▼               ▼
   ┌─────────┐   ┌─────────┐    ┌─────────┐
   │ MariaDB │   │ MongoDB │    │  Redis  │
   │ (Dados) │   │ (Msgs)  │    │ (Cache) │
   └─────────┘   └─────────┘    └─────────┘

1.2 Componentes Detalhados

Krayin CRM (Core)

  • Função: Gestão de leads, funil, agenda, relatórios
  • Tecnologia: Laravel 10 (PHP 8.2)
  • Banco: MariaDB 10.11
  • Porta: 8000 (interna)
  • URL Pública: https://crm.seu-dominio.com

Evolution API (WhatsApp Gateway)

  • Função: Integração com WhatsApp Business
  • Tecnologia: Node.js 20 + TypeScript
  • Banco: MongoDB 7.0
  • Porta: 8080 (interna)
  • URL Pública: https://evolution.seu-dominio.com

n8n (Automações)

  • Função: Workflows automáticos (respostas, follow-ups)
  • Tecnologia: Node.js 20
  • Banco: PostgreSQL 16 (SQLite para dev)
  • Porta: 5678 (interna)
  • URL Pública: https://n8n.seu-dominio.com

1.3 Fluxo de Dados

1. LEAD ENTRA (WhatsApp)
   ↓
2. Evolution API recebe
   ↓
3. n8n processa (webhook)
   ↓
4. n8n cria lead no Krayin (API)
   ↓
5. n8n envia resposta automática
   ↓
6. Corretor recebe notificação

2. Acesso Administrativo

2.1 Credenciais Padrão

⚠️ ALTERAR APÓS PRIMEIRA INSTALAÇÃO!

Krayin CRM:

URL: https://crm.seu-dominio.com/admin
Usuário: admin@seu-dominio.com
Senha: [DEFINIDA NA INSTALAÇÃO]

Evolution API:

URL: https://evolution.seu-dominio.com
API Key: [DEFINIDA NA INSTALAÇÃO]

n8n:

URL: https://n8n.seu-dominio.com
Usuário: admin@seu-dominio.com
Senha: [DEFINIDA NA INSTALAÇÃO]

2.2 Servidor (SSH)

# Acesso via SSH
ssh usuario@seu-servidor.com

# OU via chave privada
ssh -i /path/to/key.pem usuario@seu-servidor.com

Diretórios importantes:

/home/usuario/
├── krayin/              # Código Krayin CRM
├── evolution-api/       # Código Evolution API
├── n8n/                 # Dados n8n
├── docker-compose.yml   # Orquestração
└── .env                 # Variáveis de ambiente

3. Gestão de Usuários

3.1 Criando Usuário no Krayin CRM

Via Interface Web:

  1. Login como admin
  2. Menu: "Configurações" → "Usuários"
  3. Clique em "+ Novo Usuário"
  4. Preencha: 
    Nome: João Silva
E-mail: joao@empresa.com
Função: Corretor / Gerente / Admin
Status: Ativo
Grupos: [Selecionar]
  5. "Salvar"

Via CLI (terminal):

# Entrar no container Krayin
docker exec -it krayin bash

# Criar usuário
php artisan user:create \
  --name="João Silva" \
  --email="joao@empresa.com" \
  --password="senha-temporaria" \
  --role="user"

# Listar usuários
php artisan user:list

3.2 Níveis de Permissão

FunçãoPermissões
Admin✅ Tudo (configurações, usuários, relatórios globais)
Gerente✅ Ver todos leads, relatórios equipe, configurações limitadas
Corretor✅ Apenas seus leads, editar perfil
Visualizador👁️ Apenas leitura (relatórios)

3.3 Resetar Senha de Usuário

Via Interface:

  1. "Configurações" → "Usuários"
  2. Selecione o usuário
  3. "Resetar Senha"
  4. Nova senha enviada por e-mail

Via CLI:

docker exec -it krayin bash
php artisan user:reset-password joao@empresa.com

4. Configuração do Krayin CRM

4.1 Configurações Gerais

Menu: "Configurações" → "Geral"

Informações da Empresa:
  Nome: Imobiliária ABC
  E-mail: contato@empresa.com
  Telefone: (11) 3333-4444
  CNPJ: 00.000.000/0001-00

Endereço:
  Rua: Av. Paulista, 1000
  Cidade: São Paulo
  Estado: SP
  CEP: 01310-100

Timezone: America/Sao_Paulo
Moeda: BRL (R$)
Formato Data: DD/MM/YYYY

4.2 Personalização do Funil

Menu: "Configurações" → "Pipeline"

Etapas Padrão:

  1. ⚪ Novo Lead
  2. 🔵 Qualificação
  3. 🟢 Agendamento
  4. 🟡 Visita Realizada
  5. 🟠 Negociação
  6. ✅ Fechamento

Como adicionar etapa:

  1. Clique em "+ Nova Etapa"
  2. Preencha: 
    Nome: Pré-Contrato
Cor: #9B59B6 (roxo)
Posição: Entre "Negociação" e "Fechamento"
Probabilidade: 80%
  3. "Salvar"

4.3 Campos Customizados

Menu: "Configurações" → "Campos Customizados"

Exemplo: Adicionar campo "Possui Pet?"

  1. Clique "+ Novo Campo"
  2. Configure: 
    Nome: Possui Pet?
Tipo: Sim/Não (Boolean)
Entidade: Lead
Obrigatório: Não
Ordem: 10
  3. "Salvar"

Tipos de campos disponíveis:

  • ✅ Texto
  • ✅ Número
  • ✅ Data
  • ✅ Sim/Não
  • ✅ Lista Suspensa (Dropdown)
  • ✅ Múltipla Escolha
  • ✅ Área de Texto

4.4 Configuração de E-mail (SMTP)

Menu: "Configurações" → "E-mail"

Exemplo (Gmail):

Método: SMTP
Host: smtp.gmail.com
Porta: 587
Criptografia: TLS
Usuário: seu-email@gmail.com
Senha: [Senha de App - não a senha normal!]
De (Nome): Imobiliária ABC
De (E-mail): contato@empresa.com

⚠️ Gmail: Ative "Senha de App" em: https://myaccount.google.com/apppasswords

Testar configuração:

  1. Clique em "Enviar E-mail de Teste"
  2. Digite seu e-mail
  3. Verifique recebimento

5. Integração Evolution API (WhatsApp)

5.1 Criando Instância WhatsApp

Via API (Postman/cURL):

# 1. Criar instância
curl -X POST https://evolution.seu-dominio.com/instance/create \
  -H "apikey: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceName": "imobiliaria-abc",
    "qrcode": true,
    "integration": "WHATSAPP-BAILEYS"
  }'

# Retorna:
{
  "instance": {
    "instanceName": "imobiliaria-abc",
    "status": "created"
  },
  "qrcode": {
    "base64": "data:image/png;base64,iVBORw0KG..."
  }
}

2. Escanear QR Code:

  • Copie o base64 retornado
  • Cole em: https://base64.guru/converter/decode/image
  • Escaneie com WhatsApp do celular

3. Verificar conexão:

curl https://evolution.seu-dominio.com/instance/connectionState/imobiliaria-abc \
  -H "apikey: SUA_API_KEY"

# Deve retornar: "state": "open"

5.2 Configurando Webhooks

Os webhooks permitem que o n8n receba mensagens em tempo real.

curl -X POST https://evolution.seu-dominio.com/webhook/set/imobiliaria-abc \
  -H "apikey: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://n8n.seu-dominio.com/webhook/whatsapp-receive",
    "webhook_by_events": true,
    "events": [
      "QRCODE_UPDATED",
      "MESSAGES_UPSERT",
      "MESSAGES_UPDATE",
      "CONNECTION_UPDATE"
    ]
  }'

Eventos importantes:

EventoQuando dispara
MESSAGES_UPSERTNova mensagem recebida
MESSAGES_UPDATEMensagem lida/entregue
CONNECTION_UPDATEStatus conexão mudou
QRCODE_UPDATEDNovo QR Code gerado

5.3 Enviando Mensagens Programaticamente

# Enviar mensagem de texto
curl -X POST https://evolution.seu-dominio.com/message/sendText/imobiliaria-abc \
  -H "apikey: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5511999999999",
    "text": "Olá! Sua visita está confirmada para amanhã às 14h."
  }'

# Enviar imagem com legenda
curl -X POST https://evolution.seu-dominio.com/message/sendMedia/imobiliaria-abc \
  -H "apikey: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5511999999999",
    "mediatype": "image",
    "mimetype": "image/jpeg",
    "media": "https://exemplo.com/foto-imovel.jpg",
    "caption": "Veja a foto da varanda! 🏠"
  }'

6. Automações com n8n

6.1 Estrutura de Workflows

O n8n organiza automações em workflows visuais.

Workflows essenciais instalados:

  1. whatsapp-novo-lead - Cria lead automático ao receber mensagem
  2. resposta-automatica - Responde < 1 min
  3. qualificacao-bot - Faz 6 perguntas
  4. confirmacao-visita-24h - Envia lembrete
  5. follow-up-pos-visita - Cadência 7 dias
  6. notificacao-corretor - Alerta lead quente

6.2 Exemplo: Workflow "Resposta Automática"

┌──────────────┐
│  WEBHOOK     │  ← Mensagem chega do Evolution
│  (Trigger)   │
└──────┬───────┘
       │
       ▼
┌──────────────┐
│  IF NODE     │  ← Verificar se é novo lead
│  (Decisão)   │
└──────┬───────┘
       │
       ▼
┌──────────────┐
│  HTTP REQ    │  ← Criar lead no Krayin
│  (Krayin API)│
└──────┬───────┘
       │
       ▼
┌──────────────┐
│  HTTP REQ    │  ← Enviar resposta WhatsApp
│  (Evolution) │
└──────────────┘

Código do Workflow (JSON simplificado):

{
  "nodes": [
    {
      "name": "Webhook",
      "type": "n8n-nodes-base.webhook",
      "parameters": {
        "path": "whatsapp-receive",
        "responseMode": "onReceived"
      }
    },
    {
      "name": "Verificar Novo Lead",
      "type": "n8n-nodes-base.if",
      "parameters": {
        "conditions": {
          "string": [
            {
              "value1": "={{$json.event}}",
              "value2": "messages.upsert"
            }
          ]
        }
      }
    },
    {
      "name": "Criar Lead Krayin",
      "type": "n8n-nodes-base.httpRequest",
      "parameters": {
        "url": "https://crm.seu-dominio.com/api/leads",
        "method": "POST",
        "authentication": "genericCredentialType",
        "bodyParameters": {
          "name": "={{$json.pushName}}",
          "phone": "={{$json.key.remoteJid}}",
          "source": "WhatsApp"
        }
      }
    },
    {
      "name": "Enviar Resposta",
      "type": "n8n-nodes-base.httpRequest",
      "parameters": {
        "url": "https://evolution.seu-dominio.com/message/sendText/imobiliaria-abc",
        "method": "POST",
        "headerParameters": {
          "apikey": "SUA_API_KEY"
        },
        "bodyParameters": {
          "number": "={{$json.key.remoteJid}}",
          "text": "Oi! Bem-vindo. Um corretor responderá em até 5 minutos!"
        }
      }
    }
  ]
}

6.3 Ativando/Desativando Workflows

Via Interface n8n:

  1. Login: https://n8n.seu-dominio.com
  2. Lista de workflows
  3. Toggle ativo/inativo (🔴/🟢)

Via CLI:

# Listar workflows
docker exec -it n8n n8n list:workflow

# Ativar workflow
docker exec -it n8n n8n update:workflow --id=1 --active=true

# Desativar
docker exec -it n8n n8n update:workflow --id=1 --active=false

6.4 Testando Workflows

  1. Abra o workflow
  2. Clique em "Execute Workflow" (canto superior direito)
  3. Para webhooks: Envie teste via Postman:
curl -X POST https://n8n.seu-dominio.com/webhook-test/whatsapp-receive \
  -H "Content-Type: application/json" \
  -d '{
    "event": "messages.upsert",
    "pushName": "João Teste",
    "key": {
      "remoteJid": "5511999999999@s.whatsapp.net"
    },
    "message": {
      "conversation": "Olá, quero informações"
    }
  }'
  1. Ver execução: "Executions" (menu lateral)

7. Backup e Recuperação

7.1 Backup Automático

Configurado via cron (diário às 2h):

# Ver crontab
crontab -l

# Backup diário está em:
0 2 * * * /home/usuario/scripts/backup.sh

Script de backup (backup.sh):

#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/home/usuario/backups"

# Backup MariaDB (Krayin)
docker exec krayin-db mysqldump -u root -p${DB_PASSWORD} krayin > \
  $BACKUP_DIR/krayin_$DATE.sql

# Backup MongoDB (Evolution)
docker exec evolution-mongo mongodump --out /backup/$DATE

# Backup arquivos n8n
docker exec n8n cp -r /home/node/.n8n /backup/n8n_$DATE

# Compactar
tar -czf $BACKUP_DIR/full_backup_$DATE.tar.gz $BACKUP_DIR/*$DATE*

# Manter apenas últimos 30 dias
find $BACKUP_DIR -name "*.tar.gz" -mtime +30 -delete

echo "Backup concluído: full_backup_$DATE.tar.gz"

7.2 Backup Manual

# 1. Entrar no servidor
ssh usuario@seu-servidor.com

# 2. Executar script
/home/usuario/scripts/backup.sh

# 3. Verificar
ls -lh /home/usuario/backups/

7.3 Restauração de Backup

# 1. Extrair backup
cd /home/usuario/backups
tar -xzf full_backup_20260123_020000.tar.gz

# 2. Restaurar MariaDB
docker exec -i krayin-db mysql -u root -p${DB_PASSWORD} krayin < \
  krayin_20260123_020000.sql

# 3. Restaurar MongoDB
docker exec evolution-mongo mongorestore /backup/20260123_020000

# 4. Restaurar n8n
docker exec n8n cp -r /backup/n8n_20260123_020000 /home/node/.n8n

# 5. Reiniciar serviços
docker-compose restart

8. Monitoramento e Logs

8.1 Visualizando Logs

Logs em tempo real:

# Todos containers
docker-compose logs -f

# Apenas Krayin
docker-compose logs -f krayin

# Apenas Evolution
docker-compose logs -f evolution-api

# Apenas n8n
docker-compose logs -f n8n

Logs salvos:

# Localização
/var/log/
├── krayin/
│   ├── laravel.log
│   └── error.log
├── evolution/
│   └── evolution.log
└── n8n/
    └── n8n.log

# Ver últimas 100 linhas
tail -n 100 /var/log/krayin/laravel.log

# Buscar erros
grep "ERROR" /var/log/krayin/laravel.log

8.2 Métricas do Sistema

Status dos containers:

docker ps

# Deve mostrar:
# krayin        Up 5 days
# evolution-api Up 5 days
# n8n           Up 5 days
# krayin-db     Up 5 days
# evolution-mongo Up 5 days

Uso de recursos:

docker stats

# Mostra CPU, RAM, Network por container

Espaço em disco:

df -h

# ALERTA se uso > 80%

8.3 Alertas Automáticos

Configurado via monit ou similar:

# Ver status monit
sudo monit status

# Regras configuradas:
# - CPU > 90% por 5 min → Email
# - RAM > 90% → Email
# - Disk > 85% → Email
# - Container down → Email + restart

9. Segurança

9.1 Firewall (UFW)

# Ver regras ativas
sudo ufw status

# Deve permitir apenas:
22/tcp    ALLOW   Anywhere  # SSH
80/tcp    ALLOW   Anywhere  # HTTP (redireciona HTTPS)
443/tcp   ALLOW   Anywhere  # HTTPS

❌ Portas internas NUNCA expostas:

  • 8000 (Krayin)
  • 8080 (Evolution)
  • 5678 (n8n)
  • 3306 (MariaDB)
  • 27017 (MongoDB)

9.2 SSL/TLS (Certbot)

Certificado válido para:

  • crm.seu-dominio.com
  • evolution.seu-dominio.com
  • n8n.seu-dominio.com

Auto-renovação:

# Ver status
sudo certbot certificates

# Renovação manual (se necessário)
sudo certbot renew

# Auto-renovação via cron (já configurado)
0 3 * * * /usr/bin/certbot renew --quiet

9.3 Alterando API Keys

Evolution API:

# Editar .env
nano /home/usuario/evolution-api/.env

# Alterar:
AUTHENTICATION_API_KEY=NOVA_KEY_AQUI_123456

# Reiniciar
docker-compose restart evolution-api

⚠️ ATENÇÃO: Atualizar API key no n8n também!

n8n Credentials:

  1. Login n8n
  2. "Credentials" → "Evolution API"
  3. Editar → Atualizar API Key
  4. Salvar

9.4 Auditoria de Acessos

# Logs de acesso SSH
sudo tail -n 50 /var/log/auth.log

# Ver IPs conectados
sudo last -a

# Ver tentativas de login falhadas
sudo grep "Failed password" /var/log/auth.log

10. Troubleshooting Avançado

10.1 Problema: Container não inicia

# Ver erro específico
docker-compose logs krayin

# Causas comuns:
# 1. Porta já em uso
sudo lsof -i :8000

# 2. Volume corrompido
docker volume rm krayin_data
docker-compose up -d

# 3. Falta de memória
free -h

10.2 Problema: Evolution não conecta WhatsApp

# 1. Ver logs
docker-compose logs evolution-api

# 2. Verificar instância
curl https://evolution.seu-dominio.com/instance/connectionState/imobiliaria-abc \
  -H "apikey: SUA_API_KEY"

# 3. Se "state": "close" → Refazer QR Code
curl -X POST https://evolution.seu-dominio.com/instance/restart/imobiliaria-abc \
  -H "apikey: SUA_API_KEY"

# 4. Gerar novo QR
curl -X GET https://evolution.seu-dominio.com/instance/qrcode/imobiliaria-abc \
  -H "apikey: SUA_API_KEY"

10.3 Problema: n8n não recebe webhooks

# 1. Testar webhook manualmente
curl -X POST https://n8n.seu-dominio.com/webhook/whatsapp-receive \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

# 2. Se erro 404 → Workflow inativo
# Ativar via interface n8n

# 3. Ver execuções falhadas
# n8n → Executions → Filtrar "error"

# 4. Verificar se webhook está registrado
curl https://evolution.seu-dominio.com/webhook/find/imobiliaria-abc \
  -H "apikey: SUA_API_KEY"

10.4 Problema: Banco de dados corrompido

# MariaDB (Krayin)
docker exec -it krayin-db bash
mysqlcheck -u root -p krayin --auto-repair

# MongoDB (Evolution)
docker exec -it evolution-mongo bash
mongod --repair

11. Manutenção Periódica

11.1 Checklist Semanal

  •  Verificar logs de erro
  •  Verificar uso de disco (< 80%)
  •  Verificar backups executaram
  •  Testar resposta automática WhatsApp
  •  Verificar SSL válido (> 30 dias restantes)
# Script automático semanal
/home/usuario/scripts/health-check.sh

11.2 Checklist Mensal

  •  Atualizar sistema operacional
  •  Limpar logs antigos (> 90 dias)
  •  Revisar usuários inativos
  •  Testar restauração de backup
  •  Revisar permissões
# Atualizar OS
sudo apt update && sudo apt upgrade -y

# Limpar logs
find /var/log -name "*.log" -mtime +90 -delete

# Limpar Docker
docker system prune -af

11.3 Atualizações de Versão

Krayin CRM:

cd /home/usuario/krayin

# Backup primeiro!
/home/usuario/scripts/backup.sh

# Atualizar código
git pull origin main

# Instalar dependências
docker-compose exec krayin composer install

# Migrar banco
docker-compose exec krayin php artisan migrate

# Limpar cache
docker-compose exec krayin php artisan cache:clear
docker-compose exec krayin php artisan config:clear

Evolution API:

cd /home/usuario/evolution-api

# Backup
/home/usuario/scripts/backup.sh

# Atualizar
git pull origin main
docker-compose build evolution-api
docker-compose up -d evolution-api

n8n:

# Atualizar para última versão
docker-compose pull n8n
docker-compose up -d n8n

12. Comandos Úteis Rápidos

Docker

# Reiniciar todos serviços
docker-compose restart

# Parar tudo
docker-compose down

# Iniciar tudo
docker-compose up -d

# Ver logs em tempo real
docker-compose logs -f

# Entrar em container
docker exec -it krayin bash

# Limpar tudo (⚠️ CUIDADO)
docker system prune -af --volumes

Krayin

# Limpar cache
docker exec krayin php artisan cache:clear

# Rodar migrations
docker exec krayin php artisan migrate

# Criar usuário admin
docker exec krayin php artisan user:create

# Listar rotas API
docker exec krayin php artisan route:list

Evolution

# Listar instâncias
curl https://evolution.seu-dominio.com/instance/fetchInstances \
  -H "apikey: SUA_API_KEY"

# Status instância
curl https://evolution.seu-dominio.com/instance/connectionState/imobiliaria-abc \
  -H "apikey: SUA_API_KEY"

# Reiniciar instância
curl -X POST https://evolution.seu-dominio.com/instance/restart/imobiliaria-abc \
  -H "apikey: SUA_API_KEY"

📞 Suporte Técnico

Problemas não resolvidos?

  • 📧 E-mail: devops@empresa.com
  • 📱 WhatsApp: (11) 98888-7777
  • 🌐 Documentação: https://docs.empresa.com
  • ⏰ Horário: 24/7 (emergências)

✅ Documento atualizado em: Janeiro 2026
📄 Versão: 2.1
👤 Autor: Equipe DevOps

🎯 PRÓXIMO PASSO: Leia o Guia do Usuário CRM para uso operacional diário.

Back to top