Documentação FTP/SFTP - Lumina Flow Builder

Visão Geral

Este diretório contém a documentação completa de 15 tools para transferência de arquivos via FTP e SFTP.

FTP vs FTPS vs SFTP - Entenda as Diferenças

Protocolo	Porta Padrão	Segurança	Tecnologia Base	Quando Usar
FTP	21	❌ Nenhuma (texto puro)	File Transfer Protocol	Servidores antigos, dados não-sensíveis
FTPS	990 ou 21	⚠️ SSL/TLS (opcional)	FTP + SSL/TLS	Upgrade de FTP com criptografia
SFTP	22	✅ Sempre criptografado	SSH File Transfer	RECOMENDADO para dados sensíveis

IMPORTANTE: SFTP ≠ FTPS! São protocolos completamente diferentes: - FTPS = FTP com camada SSL/TLS (extensão do protocolo FTP) - SFTP = Subsistema do SSH (não tem nada a ver com FTP)

Tools FTP (8 nodes)

Conexão e Operações Básicas

ftp_connect.md - Conectar ao servidor FTP/FTPS
ftp_upload.md - Enviar arquivo para servidor FTP
ftp_download.md - Baixar arquivo do servidor FTP
ftp_list.md - Listar arquivos e diretórios

Gerenciamento de Arquivos

ftp_delete.md - Apagar arquivo no servidor
ftp_rename.md - Renomear/mover arquivo

Gerenciamento de Diretórios

ftp_mkdir.md - Criar novo diretório
ftp_rmdir.md - Remover diretório vazio

Tools SFTP (7 nodes)

Conexão e Operações Básicas

sftp_connect.md - Conectar via SSH File Transfer Protocol
sftp_upload.md - Enviar arquivo com criptografia SSH
sftp_download.md - Baixar arquivo com criptografia SSH
sftp_list.md - Listar arquivos via SSH

Gerenciamento e Segurança

sftp_delete.md - Apagar arquivo (auditado via SSH)
sftp_chmod.md - Alterar permissões Unix/Linux
sftp_exists.md - Verificar existência de arquivo

Casos de Uso Comuns

1. Upload de Relatório Diário

START → FTP_UPLOAD → FTP_LIST (confirmar) → END

Use: ftp_upload.md + ftp_list.md

2. Download e Processamento de Arquivo Bancário (SEGURO)

START → SFTP_EXISTS → SFTP_DOWNLOAD → Processar → SFTP_DELETE → END

Use: sftp_exists.md + sftp_download.md + sftp_delete.md

3. Backup Diário Organizado

START → FTP_MKDIR (/backups/2025/01/15/) → FTP_UPLOAD → END

Use: ftp_mkdir.md + ftp_upload.md

4. Processar Lote de Arquivos

START → FTP_LIST → LOOP → FTP_DOWNLOAD → FTP_DELETE → END

Use: ftp_list.md + LOOP + ftp_download.md + ftp_delete.md

5. Upload de Script e Tornar Executável (SFTP)

START → SFTP_UPLOAD → SFTP_CHMOD (755) → END

Use: sftp_upload.md + sftp_chmod.md

Quando Usar FTP vs SFTP?

Use FTP quando:

✅ Servidor não suporta SSH (sistemas legados)
✅ Dados não são sensíveis (arquivos públicos)
✅ Performance é crítica (pequeno overhead)
✅ Simplicidade é prioridade

Use SFTP quando:

✅ Dados sensíveis (financeiros, médicos, pessoais)
✅ Compliance (PCI-DSS, HIPAA, LGPD)
✅ Segurança obrigatória (bancos, governo)
✅ Servidor tem SSH (maioria dos servidores modernos)

Estrutura de um Flow FTP Típico

{
  "name": "Exemplo FTP Upload",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "ftp_1",
      "type": "ftp",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Upload FTP",
        "parameters": {
          "host": "ftp.example.com",
          "port": 21,
          "username": "user",
          "password": "pass",
          "operation": "upload",
          "localFilePath": "/tmp/arquivo.pdf",
          "remoteFilePath": "/uploads/arquivo.pdf",
          "outputVariable": "ftp_result"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "Arquivo enviado: {{ftp_result.size}} bytes"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "ftp_1" },
    { "source": "ftp_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Parâmetros Comuns

Conexão (todos os nodes)

host (string, obrigatório) - Endereço do servidor
port (number, opcional) - FTP: 21, FTPS: 990, SFTP: 22
username (string, obrigatório) - Usuário
password (string, obrigatório FTP/FTPS) - Senha
privateKey (string, opcional SFTP) - Chave SSH privada
secure (boolean, opcional FTP) - Ativar FTPS (SSL/TLS)

Operações Específicas

operation (string, obrigatório) - Tipo: upload, download, list, delete, rename, mkdir, rmdir, chmod, exists
localFilePath - Arquivo local (upload)
remoteFilePath - Arquivo remoto (upload/download)
remotePath - Diretório (list, mkdir)
mode - Permissões Unix (chmod - ex: "755", "644")
outputVariable (string, opcional) - Variável de resultado (padrão: ftp_result ou sftp_result)

Boas Práticas Gerais

✅ SIM:

Segurança: Use SFTP para dados sensíveis
Autenticação: Prefira chaves SSH ao invés de senhas (SFTP)
Validação: Use FTP_LIST/SFTP_EXISTS antes de download/delete
Organização: Crie estrutura de pastas lógica (/ano/mes/dia/)
Backup: Sempre baixe antes de apagar (download + delete)
Error Handling: Trate erros com CONDITION nodes
Auditoria: Use SFTP para operações auditáveis

❌ NÃO:

Senhas Expostas: Não hardcode senhas - use variáveis
FTP para Dados Sensíveis: Sempre use SFTP
Apagar Sem Backup: Sempre baixe antes de deletar
Ignore Erros: Sempre trate falhas de conexão/transfer
Permissões Abertas: Não use chmod 777 (inseguro)

Troubleshooting

Erro: Connection Refused

✅ Verifique se porta está correta (FTP: 21, SFTP: 22)
✅ Confirme que firewall permite conexão
✅ Teste conectividade: telnet host porta ou ssh user@host

Erro: Authentication Failed

✅ Verifique username e password
✅ Para SFTP com chave: confirme caminho da chave privada
✅ Verifique permissões da chave SSH (deve ser 600)

Erro: Permission Denied

✅ Usuário não tem permissão para ler/escrever/listar
✅ Verifique permissões do diretório remoto
✅ Confirme ownership do arquivo

Erro: File Not Found

✅ Confirme caminho completo do arquivo
✅ Use FTP_LIST/SFTP_LIST para verificar arquivos disponíveis
✅ Atenção: caminhos são case-sensitive em Unix/Linux

Status de Implementação

✅ FTP (Implementado)

Código: /home/zielinski/develop/gptapi/src/whatsapp-flows/executors/ftp-executor.service.ts
Operações: connect, upload, download, list, delete, rename
Biblioteca: basic-ftp

⚠️ SFTP (Não Implementado)

Status: Documentação completa, implementação necessária
Executor: /src/whatsapp-flows/executors/sftp-executor.service.ts (criar)
Biblioteca recomendada: ssh2-sftp-client
Operações: connect, upload, download, list, delete, chmod, exists

Comandos Úteis

Testar Conexão FTP

ftp ftp.example.com
# Username: user
# Password: pass
# ls, cd, get, put, quit

Testar Conexão SFTP

sftp user@sftp.example.com
# Password: pass
# ls, cd, get, put, quit

Gerar Chave SSH (SFTP)

ssh-keygen -t ed25519 -C "email@example.com"
# Chave privada: ~/.ssh/id_ed25519
# Chave pública: ~/.ssh/id_ed25519.pub

Adicionar Chave Pública no Servidor

ssh-copy-id user@sftp.example.com
# Ou manualmente adicionar conteúdo de id_ed25519.pub em ~/.ssh/authorized_keys

Referências

FTP RFC: RFC 959 (File Transfer Protocol)
FTPS: FTP + TLS/SSL (RFC 4217)
SFTP: SSH File Transfer Protocol (RFC draft)
Biblioteca FTP: basic-ftp NPM
Biblioteca SFTP: ssh2-sftp-client NPM

Contribuindo

Para documentar novos nodes FTP/SFTP: 1. Siga estrutura do /home/zielinski/develop/gptapi/docs/DOCUMENTATION_GUIDE.md 2. Inclua código TypeScript real do executor 3. Forneça flows JSON completos e testáveis 4. Explique casos de uso reais 5. Adicione boas práticas e dicas

Total de Tools Documentadas: 15 - FTP: 8 tools - SFTP: 7 tools

Última atualização: 2025-01-15