Manual de Arquitectura: Despliegue Seguro de n8n en Portelcore
Guía técnica para la puesta en marcha de n8n mediante Docker Compose, base de datos relacional PostgreSQL persistente y enrutamiento Zero Trust con Cloudflare Tunnels.
1. Visão Geral da Arquitetura
Sección titulada «1. Visión General de la Arquitectura»Esta guía detalla la implementación de una instancia de n8n (plataforma avanzada de automatización de flujos de trabajo) orientada a producción. La arquitectura se ha diseñado priorizando los principios de aislamiento, resiliencia y seguridad perimetral.
graph TD Client([Cliente en Internet]) -->|HTTPS / Cifrado Estricto| CFEdge[Edge de Cloudflare] subgraph Servidor Ubuntu (Proxmox VE - Red Privada) direction LR CFEdge -->|Canal Seguro / Sin Puertos Abiertos| CFTunnel[Contenedor: cloudflared] CFTunnel -->|Red Virtual Docker| n8nServer[Contenedor: n8n_server] n8nServer -->|Persistencia Local| pgData[(Volumen: n8n_db_data)] n8nServer -->|Conexión Segura| pgServer[Contenedor: n8n_postgres] pgServer --> pgData end1.1 Principais Decisões Arquitetônicas
Sección titulada «1.1 Decisiones Arquitectónicas Clave»- Entorno de Ejecución: Servidor virtualizado Ubuntu Server ejecutándose de forma aislada en un hipervisor Proxmox VE.
- Orquestación de Contenedores: Docker y Docker Compose para garantizar entornos inmutables, portables y fácilmente auditables.
- Base de Datos Relacional: Migración del almacenamiento por defecto (SQLite) a PostgreSQL 16. Esta decisión previene bloqueos de escritura bajo alta concurrencia y sienta las bases para escalabilidad horizontal futura (modo Queue mediante workers adicionales).
- Seguridad Perimetral (Zero Trust): Implementación de Cloudflare Tunnels (
cloudflared).- Beneficio Principal: El host Ubuntu no expone ningún puerto de entrada (ni 80 ni 443 ni 5678) a Internet. El contenedor del túnel establece una conexión de salida segura y cifrada directa con el Edge de Cloudflare, protegiendo la red local de escaneos maliciosos y delegando los certificados SSL (HTTPS) al Edge.
- Infraestructura como Código (IaC): La infraestructura se define de forma declarativa mediante archivos docker-compose.yml y variables de entorno .env no sensibles, facilitando los respaldos y la replicación del stack.
2. Preparação do Sistema Operacional (Ubuntu)
Sección titulada «2. Preparación del Sistema Operativo (Ubuntu)»2.1 Configuração de Rede (Netplan)
Sección titulada «2.1 Configuración de Red (Netplan)»Se establece una IP estática en el host Ubuntu para garantizar la resolución transparente de servicios y evitar colisiones generadas por el servidor DHCP de red local. En este laboratorio de alta entropía, el nodo responde en la dirección 172.22.40.231.
Edite o arquivo de rede do sistema:
sudo nano /etc/netplan/50-cloud-init.yamlAlinhe a configuração à rede interna corporativa:
network: ethernets: ens18: dhcp4: no addresses: - 172.22.40.231/24 routes: - to: default via: 172.22.40.1 nameservers: addresses: - 1.1.1.1 - 8.8.8.8 version: 2Aplique as alterações:
sudo netplan apply2.2 Instalação de Dependências do Motor Docker
Sección titulada «2.2 Instalación de Dependencias del Motor Docker»Garanta a instalação do motor atualizado e de suas bibliotecas de orquestração oficiais:
# 1. Actualización y parche de repositorios del sistemasudo apt update && sudo apt upgrade -y
# 2. Instalación de utilidades de red y certificados segurossudo apt install -y ca-certificates curl gnupg lsb-release
# 3. Importación de las llaves GPG oficiales del registro de Dockersudo install -m 0755 -d /etc/apt/keyringscurl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpgsudo chmod a+r /etc/apt/keyrings/docker.gpg
# 4. Registro del repositorio estableecho \ "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \ $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \ sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
# 5. Instalación del motor oficial y del plugin Compose V2sudo apt updatesudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
# 6. Permisos de grupo al usuario del sistema (portel_user)sudo usermod -aG docker $USER[!IMPORTANT]\r\nPasso Operativo Crítico: Lembre-se de fechar sua sessão de console ativa (
exit) e voltar a entrar via SSH para refrescar os privilégios do seu token de usuário no socket local do Docker.
3. Configuração do Cloudflare Zero Trust (O Túnel)
Sección titulada «3. Configuración de Cloudflare Zero Trust (El Túnel)»Antes de inicializar os contêineres no host, preparamos o túnel seguro no console da Cloudflare:
- Acesse seu portal Cloudflare Zero Trust > Networks > Tunnels.
- Crie um novo túnel do tipo Cloudflared (exemplo de nome:
portel-n8n-tunnel). - Copie o
TUNNEL_TOKEN(bloco de texto alfanumérico longo fornecido pela Cloudflare para autenticar seu contêiner). - Configura la ruta pública (Public Hostname):
- Dominio Público: n8n.portelcore.com
- Tipo de Serviço: HTTP
- URL Interna (Destino): n8n:5678
(Nota: Se utiliza a resolução DNS interna fornecida pela rede virtual de Docker Compose).
- Dominio Público: n8n.portelcore.com
4. Estrutura e Composição do Stack (IaC)
Sección titulada «4. Estructura y Composición del Stack (IaC)»Toda nossa infraestrutura reside de forma organizada no diretório ~/n8n-docker.
mkdir -p ~/n8n-docker && cd ~/n8n-docker4.1 Arquivo de Variáveis de Ambiente (.env)
Sección titulada «4.1 Archivo de Variables de Entorno (.env)»Este arquivo armazena de forma centralizada as portas de escuta fictícias, senhas de banco de dados e tokens de autenticação. É estritamente proibido enviar este arquivo com segredos reais para repositórios de controle de código públicos.
Arquivo: ~/n8n-docker/.env
# ==========================================# Configuración del Entorno y Dominio# ==========================================N8N_HOST=n8n.portelcore.comN8N_PROTOCOL=httpsTIMEZONE=Europe/Madrid
# ==========================================# Credenciales de Base de Datos (PostgreSQL)# ==========================================POSTGRES_USER=portel_n8n_sec_usrPOSTGRES_PASSWORD=pg_pass_secure_demo_987654321_! # Ejemplo demostrativo y de laboratorioPOSTGRES_DB=n8n_production_db
# ==========================================# Credenciales de Seguridad (Cloudflare)# ==========================================# Sustituye este marcador por tu token obtenido en la consola de CloudflareCLOUDFLARE_TUNNEL_TOKEN=eyJh...[TU_TOKEN_DE_TÚNEL_SEGURO_AQUÍ]...4.2 Orquestração Multicamada (docker-compose.yml)
Sección titulada «4.2 Orquestación Multicapa (docker-compose.yml)»Este arquivo declara o motor de base de dados relacional (Postgres 16), o servidor de fluxos de n8n e o agente do túnel de Cloudflare. Se incluem chequeos de saúde avançados (healthchecks) para mitigar caídas de serviços e garantir dependências lógicas limpas.
Arquivo: ~/n8n-docker/docker-compose.yml
version: '3.8'
services: # 1. Capa de Persistencia y Base de Datos Relacional postgres: image: postgres:16-alpine container_name: n8n_postgres restart: unless-stopped environment: - POSTGRES_USER=${POSTGRES_USER} - POSTGRES_PASSWORD=${POSTGRES_PASSWORD} - POSTGRES_DB=${POSTGRES_DB} volumes: - pg_data:/var/lib/postgresql/data networks: - n8n_network healthcheck: test: ["CMD-SHELL", "pg_isready -h localhost -U ${POSTGRES_USER} -d ${POSTGRES_DB}"] interval: 10s timeout: 5s retries: 5
# 2. Servidor de Automatización (Lógica de Negocio) n8n: image: docker.n8n.io/n8nio/n8n:latest container_name: n8n_server restart: unless-stopped # Nota de Seguridad: No mapeamos puertos físicos del host a internet. # Todo tráfico es recibido localmente a través de la red de Docker por el túnel. environment: - DB_TYPE=postgresdb - DB_POSTGRESDB_HOST=postgres - DB_POSTGRESDB_PORT=5432 - DB_POSTGRESDB_DATABASE=${POSTGRES_DB} - DB_POSTGRESDB_USER=${POSTGRES_USER} - DB_POSTGRESDB_PASSWORD=${POSTGRES_PASSWORD} - N8N_HOST=${N8N_HOST} - N8N_PORT=5678 - N8N_PROTOCOL=${N8N_PROTOCOL} - NODE_ENV=production - WEBHOOK_URL=${N8N_PROTOCOL}://${N8N_HOST}/ - GENERIC_TIMEZONE=${TIMEZONE} volumes: - n8n_data:/home/node/.n8n networks: - n8n_network depends_on: postgres: condition: service_healthy
# 3. Capa de Enlace Zero Trust (Cloudflare Tunnel) cloudflared: image: cloudflare/cloudflared:latest container_name: n8n_tunnel restart: unless-stopped # Desactivar autoupdate evita que actualizaciones autónomas rompan la infraestructura local command: tunnel --no-autoupdate run environment: - TUNNEL_TOKEN=${CLOUDFLARE_TUNNEL_TOKEN} networks: - n8n_network
# Definición de volúmenes persistentes locales del hostvolumes: n8n_data: name: n8n_app_data pg_data: name: n8n_db_data
# Red virtual privada aisladanetworks: n8n_network: name: n8n_internal_net driver: bridge5. Operações de Console e Diagnóstico
Sección titulada «5. Operaciones de Consola y Diagnóstico»5.1 Implantação Inicial e Inicialização do Stack
Sección titulada «5.1 Despliegue Inicial y Arranque del Stack»Para levantar toda a infraestrutura declarada em segundo plano por primeira vez (ou após realizar alterações no arquivo .env):
cd ~/n8n-dockerdocker compose up -d5.2 Leitura de Logs em Tempo Real
Sección titulada «5.2 Lectura de Logs en Tiempo Real»Para monitorar de forma analítica o fluxo de dados ou diagnosticar falhas de inicialização:
# Ver logs de todo el stack de serviciosdocker compose logs -f
# Diagnóstico específico del túnel de Cloudflaredocker logs -f n8n_tunnel5.3 Redefinição de Fábrica (Manutenção de Emergência)
Sección titulada «5.3 Restablecimiento de Fábrica (Mantenimiento de Emergencia)»[!CAUTION]\r\nOperação Destrutiva: O seguinte comando elimina permanentemente todos os contêineres e os volumes locais do host (apagando credenciais, usuários e históricos de fluxos de n8n). Use-o apenas em laboratórios ou contingências graves.
cd ~/n8n-docker# Detiene el stack eliminando los volúmenes asociadosdocker compose down -v
# Reconstruye el entorno desde cerodocker compose up -d📊 Checklist de Sucesso Operacional
Sección titulada «📊 Checklist de Éxito Operativo»- ✓ Cifrado HTTPS Estricto: Tráfego cifrado de extremo a extremo encaminhado de forma nativa pelo Edge de Cloudflare para n8n.portelcore.com
. - ✓ Persistência Relacional: Motor de base de dados PostgreSQL 16 verificado por meio de chequeos de saúde automatizados.
- ✓ Segurança de Rede Aislada: Zero portas do host abertas na rede pública, canalizando o encaminhamento interno por meio de um ponte virtual fechado de Docker.
- ✓ Estándar Declarativo: Arquivos IaC (docker-compose.yml
e .env) limpos de segredos rígidos e integrados com diretrizes de parada controlada.

