Manual d'Arquitectura: Despliegament Segur de n8n a Portelcore
Guia tècnica per a la posada en marxa de n8n mitjançant Docker Compose, base de dades relacional PostgreSQL persistent i enrutament Zero Trust amb Cloudflare Tunnels.
1. Visió general de l'arquitectura
Sección titulada «1. Visión General de la Arquitectura»Aquesta guia detalla la implementació d'una instància de n8n (plataforma avançada d'automatització de fluxos de treball) orientada a producció. L'arquitectura s'ha dissenyat prioritzant els principis d'aïllament, resiliència i seguretat 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 Decisions arquitectòniques clau
Sección titulada «1.1 Decisiones Arquitectónicas Clave»- Entorn d'execució: Servidor virtualitzat Ubuntu Server executant-se de forma aïllada en un hipervisor Proxmox VE.
- Orquestació de contenidors: Docker i Docker Compose per garantir entorns immutables, portables i fàcilment audidables.
- Base de dades relacional: Migració de l'emmagatzematge per defecte (SQLite) a PostgreSQL 16. Aquesta decisió evita bloquejos d'escriptura sota alta concurrència i estableix les bases per a una escalabilitat horitzontal futura (mode Queue mitjançant workers addicionals).
- Seguretat Perimètrica (Zero Trust): Implementació de Cloudflare Tunnels (
cloudflared).- Benefici principal: L'host Ubuntu no exposa cap port d'entrada (ni
80ni443ni5678) a Internet. El contenidor del túnel estableix una connexió de sortida segura i xifrada directa amb l'Edge de Cloudflare, protegint la xarxa local d'escanejos maliciosos i delegant els certificats SSL (HTTPS) a l'Edge.
- Benefici principal: L'host Ubuntu no exposa cap port d'entrada (ni
- Infraestructura com a codi (IaC): La infraestructura es defineix de forma declarativa mitjançant fitxers
docker-compose.ymli variables d'entorn.envno sensibles, facilitant les còpies de seguretat i la replicació de l'stack.
2. Preparació del sistema operatiu (Ubuntu)
Sección titulada «2. Preparación del Sistema Operativo (Ubuntu)»2.1 Configuració de xarxa (Netplan)
Sección titulada «2.1 Configuración de Red (Netplan)»Es estableix una IP estàtica a l'host Ubuntu per garantir la resolució transparent de serveis i evitar col·lisions generades pel servidor DHCP de la xarxa local. En aquest laboratori d'alta entropia, el node respon a l'adreça 172.22.40.231.
Editeu l'arxiu de xarxa del sistema:
sudo nano /etc/netplan/50-cloud-init.yamlAlineeu la configuració amb la xarxa 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: 2Apliqueu els canvis:
sudo netplan apply2.2 Instal·lació de dependències del motor Docker
Sección titulada «2.2 Instalación de Dependencias del Motor Docker»Assegureu la instal·lació del motor actualitzat i les seves llibreries d'orquestació oficials:
# 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] Pas Operatiu Crític: Recorda tancar la teva sessió de consola activa (
exit) i tornar a entrar via SSH per actualitzar els privilegis del teu token d'usuari al socket local de Docker.
3. Configuració de Cloudflare Zero Trust (El Túnel)
Sección titulada «3. Configuración de Cloudflare Zero Trust (El Túnel)»Abans d'inicialitzar els contenidors a l'host, preparem el túnel segur a la consola de Cloudflare:
- Accediu al vostre portal Cloudflare Zero Trust > Networks > Tunnels.
- Creeu un nou túnel de tipus Cloudflared (exemple de nom:
portel-n8n-tunnel). - Copieu el
TUNNEL_TOKEN(bloc de text alfanumèric llarg proporcionat per Cloudflare per autenticar el vostre contèiner). - Configura la ruta pública (Public Hostname):
- Domini Públic:
n8n.portelcore.com - Tipus de Servei:
HTTP - URL Interna (Destí):
n8n:5678(Nota: S'utilitza la resolució DNS interna proporcionada per la xarxa virtual de Docker Compose).
- Domini Públic:
4. Estructura i Composició de l'Stack (IaC)
Sección titulada «4. Estructura y Composición del Stack (IaC)»Toda la nostra infraestructura reside de manera organitzada al directori ~/n8n-docker.
mkdir -p ~/n8n-docker && cd ~/n8n-docker4.1 Fitxer de Variables d'Entorn (.env)
Sección titulada «4.1 Archivo de Variables de Entorno (.env)»Aquest fitxer emmagatzena de manera centralitzada els ports d'escolta ficticis, contrasenyes de bases de dades i tokens d'autenticació. Queda estrictament prohibit pujar aquest fitxer amb secrets reals a repositoris de control de codi públics.
Fitxer: ~/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ó Multicapa (docker-compose.yml)
Sección titulada «4.2 Orquestación Multicapa (docker-compose.yml)»Aquest fitxer declara el motor de base de dades relacional (Postgres 16), el servidor de fluxos de n8n i l'agent del túnel de Cloudflare. S'inclouen verificacions de salut avançades (healthchecks) per mitigar caigudes de serveis i assegurar dependències lògiques netes.
Fitxer: ~/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. Operacions de consola i diagnòstic
Sección titulada «5. Operaciones de Consola y Diagnóstico»5.1 Despliegament inicial i arranque de l'stack
Sección titulada «5.1 Despliegue Inicial y Arranque del Stack»Per aixecar tota la infraestructura declarada en segon pla per primera vegada (o després de realitzar canvis en l'arxiu .env):
cd ~/n8n-dockerdocker compose up -d5.2 Lectura de logs en temps real
Sección titulada «5.2 Lectura de Logs en Tiempo Real»Per monitoritzar de forma analítica el flux de dades o diagnosticar fallades d'arrancament:
# 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 Restableixement de fàbrica (Manteniment d'emergència)
Sección titulada «5.3 Restablecimiento de Fábrica (Mantenimiento de Emergencia)»[!CAUTION] Operació Destructiva: L'endemà següent comandament elimina permanentment tots els contenidors i els volums locals de l'host (esborrant credencials, usuaris i historials de fluxos de n8n). Utilitza'l només en laboratoris o contingències greus.
cd ~/n8n-docker# Detiene el stack eliminando los volúmenes asociadosdocker compose down -v
# Reconstruye el entorno desde cerodocker compose up -d📊 Checklist d'èxit operatiu
Sección titulada «📊 Checklist de Éxito Operativo»- ✓ Cifrat HTTPS estricte: Trànsit cifrat de punta a punta enrutat de manera nativa per l'Edge de Cloudflare cap a
n8n.portelcore.com. - ✓ Persistència relacional: Motor de base de dades PostgreSQL 16 verificat mitjançant verificacions de salut automatitzades.
- ✓ Seguretat de xarxa aïllada: Zero ports de l'host oberts a la xarxa pública, canalitzant l'enrutament intern a través d'un pont virtual tancat de Docker.
- ✓ Estàndard declaratiu: Arxius IaC (
docker-compose.ymli.env) lliures de secrets rígids i integrats amb directives de parada controlada.

