Ir al contenido

Manuel d'architecture : Déploiement sécurisé de n8n sur Portelcore

Guide technique pour la mise en œuvre de n8n via Docker Compose, une base de données relationnelle PostgreSQL persistante et un routage Zero Trust avec Cloudflare Tunnels.

0vues

Ce guide détaille l'implémentation d'une instance de n8n (plateforme avancée d'automatisation des flux de travail) orientée production. L'architecture a été conçue en privilégiant les principes d'isolation, de résilience et de sécurité périmétrique.

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
  • Environnement d'exécution : Serveur virtualisé Ubuntu Server s'exécutant de manière isolée sur un hyperviseur Proxmox VE.
  • Orchestration de conteneurs : Docker et Docker Compose pour garantir des environnements immuables, portables et facilement auditables.
  • Base de données relationnelle : Migration du stockage par défaut (SQLite) vers PostgreSQL 16. Cette décision prévient les blocages d'écriture sous haute concurrence et jette les bases d'une future scalabilité horizontale (mode Queue via des workers supplémentaires).
  • Sécurité Périmétrique (Zero Trust) : Implémentation de Cloudflare Tunnels (cloudflared).
    • Avantage principal : L'hôte Ubuntu n'expose aucun port d'entrée (ni 80 ni 443 ni 5678) à Internet. Le conteneur du tunnel établit une connexion de sortie sécurisée et chiffrée directe avec l'Edge de Cloudflare, protégeant le réseau local des scans malveillants et déléguant les certificats SSL (HTTPS) à l'Edge.
  • Infrastructure as Code (IaC) : L'infrastructure est définie de manière déclarative via des fichiers docker-compose.yml et des variables d'environnement .env non sensibles, facilitant les sauvegardes et la réplication de la stack.

2. Préparation du système d'exploitation (Ubuntu)

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

Une adresse IP statique est configurée sur l'hôte Ubuntu pour garantir la résolution transparente des services et éviter les collisions générées par le serveur DHCP du réseau local. Dans ce laboratoire à haute entropie, le nœud répond à l'adresse 172.22.40.231.

Modifiez le fichier réseau du système :

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

Alignez la configuration sur le réseau interne de l'entreprise :

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

Appliquez les modifications :

Ventana de terminal
sudo netplan apply

2.2 Installation des dépendances du moteur Docker

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

Assurez-vous de l'installation du moteur mis à jour et de ses bibliothèques d'orchestration officielles :

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] Étape Opérative Critique : N'oubliez pas de fermer votre session de console active (exit) et de vous reconnecter via SSH pour rafraîchir les privilèges de votre jeton d'utilisateur sur le socket local Docker.


3. Configuration de Cloudflare Zero Trust (Le tunnel)

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

Avant d'initialiser les conteneurs sur l'hôte, nous préparons le tunnel sécurisé dans la console Cloudflare :

  1. Accédez à votre portail Cloudflare Zero Trust > Networks > Tunnels.
  2. Créez un nouveau tunnel de type Cloudflared (exemple de nom : portel-n8n-tunnel).
  3. Copiez le TUNNEL_TOKEN (long bloc de texte alphanumérique fourni par Cloudflare pour authentifier votre conteneur).
  4. Configurez le chemin public (Nom d'Hôte Public) :
    • Domaine Public : n8n.portelcore.com
    • Type de Service : HTTP
    • URL Interne (Destination) : n8n:5678 (Note : La résolution DNS interne fournie par le réseau virtuel de Docker Compose est utilisée).

4. Structure et Composition de la Stack (IaC)

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

Toute notre infrastructure réside de manière organisée dans le répertoire ~/n8n-docker.

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

4.1 Fichier des variables d'environnement (.env)

Sección titulada «4.1 Archivo de Variables de Entorno (.env)»

Ce fichier stocke de manière centralisée les ports d'écoute fictifs, les mots de passe des bases de données et les jetons d'authentification. Il est strictement interdit de télécharger ce fichier avec de vrais secrets sur des dépôts de contrôle de code publics.

Fichier : ~/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 Orchestration multicouche (docker-compose.yml)

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

Ce fichier déclare le moteur de base de données relationnelle (Postgres 16), le serveur de flux n8n et l'agent de tunnel Cloudflare. Des contrôles de santé avancés (healthchecks) sont inclus pour atténuer les interruptions de service et assurer des dépendances logiques propres.

Fichier : ~/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 Déploiement Initial et Démarrage de la Stack

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

Pour déployer toute l'infrastructure déclarée en arrière-plan pour la première fois (ou après avoir effectué des modifications dans le fichier .env) :

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

Pour surveiller de manière analytique le flux de données ou diagnostiquer les échecs de démarrage :

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

[!CAUTION] Opération Destructive : La commande suivante supprime définitivement tous les conteneurs et les volumes locaux de l'hôte (en supprimant les informations d'identification, les utilisateurs et les historiques de flux de n8n). Utilisez-le uniquement dans les laboratoires ou en cas de problèmes graves.

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

📊 Checklist de Succès Opérationnel

Sección titulada «📊 Checklist de Éxito Operativo»
  • ✓ Chiffrement HTTPS strict : Trafic chiffré de bout en bout routé nativement par l'Edge de Cloudflare vers n8n.portelcore.com.
  • ✓ Persistance relationnelle : Moteur de base de données PostgreSQL 16 vérifié par des contrôles de santé automatisés.
  • ✓ Sécurité réseau isolée : Aucun port de l'hôte ouvert sur le réseau public, canalisant le routage interne via un pont virtuel Docker fermé.
  • ✓ Standard déclaratif : Fichiers IaC (docker-compose.yml et .env) exempts de secrets en dur et intégrés avec des directives d'arrêt contrôlé.