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
  • 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. Preparación del Sistema Operativo (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 el archivo de red del sistema:

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

Alinee la configuración a la red 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 los cambios:

Ventana de terminal
sudo netplan apply

2.2 Instalación de Dependencias del Motor Docker

Sección titulada «2.2 Instalación de Dependencias del Motor Docker»

Asegure la instalación del motor actualizado y sus librerías de orquestación oficiales:

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] Paso Operativo Crítico: Recuerda cerrar tu sesión de consola activa (exit) y volver a ingresar vía SSH para refrescar los privilegios de tu token de usuario en el socket local de Docker.


3. Configuración de Cloudflare Zero Trust (El Túnel)

Sección titulada «3. Configuración de Cloudflare Zero Trust (El Túnel)»

Antes de inicializar los contenedores en el host, preparamos el túnel seguro en la consola de Cloudflare:

  1. Accede a tu portal Cloudflare Zero Trust > Networks > Tunnels.
  2. Crea un nuevo túnel de tipo Cloudflared (ejemplo de nombre: portel-n8n-tunnel).
  3. Copia el TUNNEL_TOKEN (bloque de texto alfanumérico largo proporcionado por Cloudflare para autenticar tu contenedor).
  4. Configura la ruta pública (Public Hostname):
    • Dominio Público: n8n.portelcore.com
    • Tipo de Servicio: HTTP
    • URL Interna (Destino): n8n:5678 (Nota: Se utiliza la resolución DNS interna provista por la red virtual de Docker Compose).

4. Estructura y Composición del Stack (IaC)

Sección titulada «4. Estructura y Composición del Stack (IaC)»

Toda nuestra infraestructura reside de forma organizada en el directorio ~/n8n-docker.

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

Este archivo almacena de manera centralizada los puertos de escucha ficticios, contraseñas de bases de datos y tokens de autenticación. Queda estrictamente prohibido subir este archivo con secretos reales a repositorios de control de código públicos.

Archivo: ~/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 Orquestación Multicapa (docker-compose.yml)

Sección titulada «4.2 Orquestación Multicapa (docker-compose.yml)»

Este archivo declara el motor de base de datos relacional (Postgres 16), el servidor de flujos de n8n y el agente del túnel de Cloudflare. Se incluyen chequeos de salud avanzados (healthchecks) para mitigar caídas de servicios y asegurar dependencias lógicas limpias.

Archivo: ~/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

Para levantar toda la infraestructura declarada en segundo plano por primera vez (o tras realizar cambios en el archivo .env):

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

Para monitorizar de forma analítica el flujo de datos o diagnosticar fallos de arranque:

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 Restablecimiento de Fábrica (Mantenimiento de Emergencia)

Sección titulada «5.3 Restablecimiento de Fábrica (Mantenimiento de Emergencia)»

[!CAUTION] Operación Destructiva: El siguiente comando elimina permanentemente todos los contenedores y los volúmenes locales del host (borrando credenciales, usuarios e historiales de flujos de n8n). Úsalo únicamente en laboratorios o contingencias 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áfico cifrado de extremo a extremo enrutado de manera nativa por el Edge de Cloudflare hacia n8n.portelcore.com.
  • ✓ Persistencia Relacional: Motor de base de datos PostgreSQL 16 verificado mediante chequeos de salud automatizados.
  • ✓ Seguridad de Red Aislada: Cero puertos del host abiertos en la red pública, canalizando el enrutamiento interno a través de un puente virtual cerrado de Docker.
  • ✓ Estándar Declarativo: Archivos IaC (docker-compose.yml y .env) limpios de secretos rígidos e integrados con directivas de parada controlada.