Ir al contenido

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.

0lectures

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
end
  • 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 80 ni 443 ni 5678) 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.
  • Infraestructura com a codi (IaC): La infraestructura es defineix de forma declarativa mitjançant fitxers docker-compose.yml i variables d'entorn .env no sensibles, facilitant les còpies de seguretat i la replicació de l'stack.

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:

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

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

Apliqueu els canvis:

Ventana de terminal
sudo netplan apply

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

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

  1. Accediu al vostre portal Cloudflare Zero Trust > Networks > Tunnels.
  2. Creeu un nou túnel de tipus Cloudflared (exemple de nom: portel-n8n-tunnel).
  3. Copieu el TUNNEL_TOKEN (bloc de text alfanumèric llarg proporcionat per Cloudflare per autenticar el vostre contèiner).
  4. 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).

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.

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

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

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

Per monitoritzar de forma analítica el flux de dades o diagnosticar fallades d'arrancament:

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

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

  • ✓ 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.yml i .env) lliures de secrets rígids i integrats amb directives de parada controlada.