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. Visión General de la Arquitectura
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 Decisiones Arquitectónicas Clave
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
80ni443ni5678) 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.
- Beneficio Principal: El host Ubuntu no expone ningún puerto de entrada (ni
- Infraestructura como Código (IaC): La infraestructura se define de forma declarativa mediante archivos
docker-compose.ymly variables de entorno.envno 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)»2.1 Configuración de Red (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 el archivo de red del sistema:
sudo nano /etc/netplan/50-cloud-init.yamlAlinee 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: 2Aplique los cambios:
sudo netplan apply2.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:
# 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] 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:
- Accede a tu portal Cloudflare Zero Trust > Networks > Tunnels.
- Crea un nuevo túnel de tipo Cloudflared (ejemplo de nombre:
portel-n8n-tunnel). - Copia el
TUNNEL_TOKEN(bloque de texto alfanumérico largo proporcionado por Cloudflare para autenticar tu contenedor). - 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).
- Dominio Público:
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.
mkdir -p ~/n8n-docker && cd ~/n8n-docker4.1 Archivo de Variables de Entorno (.env)
Sección titulada «4.1 Archivo de Variables de Entorno (.env)»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.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 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 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. Operaciones de Consola y Diagnóstico
Sección titulada «5. Operaciones de Consola y Diagnóstico»5.1 Despliegue Inicial y Arranque del Stack
Sección titulada «5.1 Despliegue Inicial y Arranque del Stack»Para levantar toda la infraestructura declarada en segundo plano por primera vez (o tras realizar cambios en el archivo .env):
cd ~/n8n-dockerdocker compose up -d5.2 Lectura de Logs en Tiempo Real
Sección titulada «5.2 Lectura de Logs en Tiempo Real»Para monitorizar de forma analítica el flujo de datos o diagnosticar fallos de arranque:
# 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 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.
cd ~/n8n-docker# Detiene el stack eliminando los volúmenes asociadosdocker compose down -v
# Reconstruye el entorno desde cerodocker compose up -d📊 Checklist de Éxito Operativo
Sección titulada «📊 Checklist de Éxito Operativo»- ✓ 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.ymly.env) limpios de secretos rígidos e integrados con directivas de parada controlada.

