Ir al contenido

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.

0lecturas

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
end

1.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)»

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:

Ventana de terminal
sudo nano /etc/netplan/50-cloud-init.yaml

Alinhe 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: 2

Aplique as alterações:

Ventana de terminal
sudo netplan apply

2.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:

Ventana de terminal
# 1. Actualización y parche de repositorios del sistema
sudo apt update && sudo apt upgrade -y
# 2. Instalación de utilidades de red y certificados seguros
sudo apt install -y ca-certificates curl gnupg lsb-release
# 3. Importación de las llaves GPG oficiales del registro de Docker
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
# 4. Registro del repositorio estable
echo \
"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 V2
sudo apt update
sudo 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:

  1. Acesse seu portal Cloudflare Zero Trust > Networks > Tunnels.
  2. Crie um novo túnel do tipo Cloudflared (exemplo de nome: portel-n8n-tunnel).
  3. Copie o TUNNEL_TOKEN (bloco de texto alfanumérico longo fornecido pela Cloudflare para autenticar seu contêiner).
  4. 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).

Toda nossa infraestrutura reside de forma organizada no diretório ~/n8n-docker.

Ventana de terminal
mkdir -p ~/n8n-docker && cd ~/n8n-docker

4.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.com
N8N_PROTOCOL=https
TIMEZONE=Europe/Madrid
# ==========================================
# Credenciales de Base de Datos (PostgreSQL)
# ==========================================
POSTGRES_USER=portel_n8n_sec_usr
POSTGRES_PASSWORD=pg_pass_secure_demo_987654321_! # Ejemplo demostrativo y de laboratorio
POSTGRES_DB=n8n_production_db
# ==========================================
# Credenciales de Seguridad (Cloudflare)
# ==========================================
# Sustituye este marcador por tu token obtenido en la consola de Cloudflare
CLOUDFLARE_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 host
volumes:
n8n_data:
name: n8n_app_data
pg_data:
name: n8n_db_data
# Red virtual privada aislada
networks:
n8n_network:
name: n8n_internal_net
driver: bridge

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):

Ventana de terminal
cd ~/n8n-docker
docker compose up -d

Para monitorar de forma analítica o fluxo de dados ou diagnosticar falhas de inicialização:

Ventana de terminal
# Ver logs de todo el stack de servicios
docker compose logs -f
# Diagnóstico específico del túnel de Cloudflare
docker logs -f n8n_tunnel

5.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.

Ventana de terminal
cd ~/n8n-docker
# Detiene el stack eliminando los volúmenes asociados
docker compose down -v
# Reconstruye el entorno desde cero
docker compose up -d

  • ✓ 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.