Ir al contenido

Manuale di Architettura: Deployment Sicuro di n8n su Portelcore

Guida tecnica per il deployment di n8n tramite Docker Compose, database relazionale PostgreSQL persistente e routing Zero Trust con Cloudflare Tunnels.

0letture

Questa guida descrive l'implementazione di un'istanza di n8n (piattaforma avanzata di automazione dei flussi di lavoro) orientata alla produzione. L'architettura è stata progettata priorizzando i principi di isolamento, resilienza e sicurezza perimetrale.

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
  • Ambiente di Esecuzione: Server virtualizzato Ubuntu Server in esecuzione in modo isolato su un hypervisor Proxmox VE.
  • Orchestrazione dei Container: Docker e Docker Compose per garantire ambienti immutabili, portabili e facilmente auditabili.
  • Database Relazionale: Migrazione dello storage predefinito (SQLite) a PostgreSQL 16. Questa decisione previene i blocchi di scrittura in condizioni di alta concorrenza e getta le basi per una futura scalabilità orizzontale (modalità Queue tramite worker aggiuntivi).
  • Sicurezza Perimetrale (Zero Trust): Implementazione di Cloudflare Tunnels (cloudflared).
    • Beneficio Principale: L'host Ubuntu non espone alcuna porta di ingresso (né 80 né 443 né 5678) a Internet. Il container del tunnel stabilisce una connessione in uscita sicura e cifrata direttamente con l'Edge di Cloudflare, proteggendo la rete locale da scansioni malevole e delegando i certificati SSL (HTTPS) all'Edge.
  • Infrastruttura come Codice (IaC): L'infrastruttura viene definita in modo dichiarativo tramite file docker-compose.yml e variabili d'ambiente .env non sensibili, facilitando i backup e la replicazione dello stack.

2. Preparazione del Sistema Operativo (Ubuntu)

Sección titulada «2. Preparación del Sistema Operativo (Ubuntu)»

Viene impostata un'IP statica sull'host Ubuntu per garantire la risoluzione trasparente dei servizi ed evitare collisioni generate dal server DHCP della rete locale. In questo laboratorio ad alta entropia, il nodo risponde all'indirizzo 172.22.40.231.

Modifica il file di rete del sistema:

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

Allinea la configurazione alla rete interna aziendale:

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

Applica le modifiche:

Ventana de terminal
sudo netplan apply

2.2 Installazione delle Dipendenze del Motore Docker

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

Assicurati dell'installazione del motore aggiornato e delle sue librerie di orchestrazione ufficiali:

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] Passo Operativo Critico: Ricorda di chiudere la sessione di console attiva (exit) e di rientrare tramite SSH per aggiornare i privilegi del token utente nel socket locale di Docker.


3. Configurazione di Cloudflare Zero Trust (Il Tunnel)

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

Prima di inizializzare i container sull'host, prepariamo il tunnel sicuro nella console di Cloudflare:

  1. Accedi al tuo portale Cloudflare Zero Trust > Networks > Tunnels.
  2. Crea un nuovo tunnel di tipo Cloudflared (esempio di nome: portel-n8n-tunnel).
  3. Copia il TUNNEL_TOKEN (stringa alfanumerica lunga fornita da Cloudflare per autenticare il tuo contenitore).
  4. Configura il percorso pubblico (Public Hostname):
    • Dominio Pubblico: n8n.portelcore.com
    • Tipo di Servizio: HTTP
    • URL interna (destinazione): n8n:5678 (Nota: si utilizza la risoluzione DNS interna fornita dalla rete virtuale di Docker Compose).

4. Struttura e Composizione dello Stack (IaC)

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

Tutta la nostra infrastruttura risiede in modo organizzato nella directory ~/n8n-docker.

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

Questo file archivia in modo centralizzato le porte di ascolto fittizie, le password dei database e i token di autenticazione. È severamente vietato caricare questo file con segreti reali su repository di controllo del codice pubblici.

File: ~/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 Orchestrazione Multilivello (docker-compose.yml)

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

Questo file dichiara il motore del database relazionale (Postgres 16), il server di workflow di n8n e l'agente del tunnel di Cloudflare. Sono inclusi controlli di stato avanzati (healthchecks) per mitigare le interruzioni dei servizi e garantire dipendenze logiche pulite.

File: ~/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 Distribuzione Iniziale e Avvio dello Stack

Sección titulada «5.1 Despliegue Inicial y Arranque del Stack»

Per avviare l'intera infrastruttura dichiarata in background per la prima volta (o dopo aver apportato modifiche al file .env):

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

Per monitorare in modo analitico il flusso di dati o diagnosticare errori di avvio:

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 Ripristino alle Impostazioni di Fabbrica (Manutenzione di Emergenza)

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

[!CAUTION] Operazione Distruttiva: Il comando seguente elimina permanentemente tutti i container e i volumi locali dell'host (cancellando credenziali, utenti e cronologie dei flussi di n8n). Utilizzarlo solo in laboratori o contingenze gravi.

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

  • ✓ Crittografia HTTPS Rigida: Traffico cifrato end-to-end instradato nativamente dall'Edge di Cloudflare verso n8n.portelcore.com.
  • ✓ Persistenza Relazionale: Motore di database PostgreSQL 16 verificato tramite controlli di salute automatizzati.
  • ✓ Sicurezza della Rete Isolata: Nessuna porta dell'host aperta nella rete pubblica, instradando il routing interno attraverso un ponte virtuale chiuso di Docker.
  • ✓ Standard Declarativo: File IaC (docker-compose.yml e .env) puliti da segreti rigidi e integrati con direttive di arresto controllato.