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.
1. Panoramica dell'Architettura
Sección titulada «1. Visión General de la Arquitectura»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 end1.1 Decisioni Architetturali Chiave
Sección titulada «1.1 Decisiones Arquitectónicas Clave»- 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é
80né443né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.
- Beneficio Principale: L'host Ubuntu non espone alcuna porta di ingresso (né
- Infrastruttura come Codice (IaC): L'infrastruttura viene definita in modo dichiarativo tramite file
docker-compose.ymle variabili d'ambiente.envnon 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)»2.1 Configurazione di Rete (Netplan)
Sección titulada «2.1 Configuración de Red (Netplan)»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:
sudo nano /etc/netplan/50-cloud-init.yamlAllinea 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: 2Applica le modifiche:
sudo netplan apply2.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:
# 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] 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:
- Accedi al tuo portale Cloudflare Zero Trust > Networks > Tunnels.
- Crea un nuovo tunnel di tipo Cloudflared (esempio di nome:
portel-n8n-tunnel). - Copia il
TUNNEL_TOKEN(stringa alfanumerica lunga fornita da Cloudflare per autenticare il tuo contenitore). - 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).
- Dominio Pubblico:
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.
mkdir -p ~/n8n-docker && cd ~/n8n-docker4.1 File delle variabili d'ambiente (.env)
Sección titulada «4.1 Archivo de Variables de Entorno (.env)»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.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 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 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. Operazioni di Console e Diagnostica
Sección titulada «5. Operaciones de Consola y Diagnóstico»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):
cd ~/n8n-dockerdocker compose up -d5.2 Lettura dei Log in Tempo Reale
Sección titulada «5.2 Lectura de Logs en Tiempo Real»Per monitorare in modo analitico il flusso di dati o diagnosticare errori di avvio:
# 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 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.
cd ~/n8n-docker# Detiene el stack eliminando los volúmenes asociadosdocker compose down -v
# Reconstruye el entorno desde cerodocker compose up -d📊 Checklist di Successo Operativo
Sección titulada «📊 Checklist de Éxito Operativo»- ✓ 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.ymle.env) puliti da segreti rigidi e integrati con direttive di arresto controllato.

