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.
1. Aperçu de l'architecture
Sección titulada «1. Visión General de la Arquitectura»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 end1.1 Décisions architecturales clés
Sección titulada «1.1 Decisiones Arquitectónicas Clave»- 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
80ni443ni5678) à 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.
- Avantage principal : L'hôte Ubuntu n'expose aucun port d'entrée (ni
- Infrastructure as Code (IaC) : L'infrastructure est définie de manière déclarative via des fichiers
docker-compose.ymlet des variables d'environnement.envnon 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)»2.1 Configuration réseau (Netplan)
Sección titulada «2.1 Configuración de Red (Netplan)»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 :
sudo nano /etc/netplan/50-cloud-init.yamlAlignez 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: 2Appliquez les modifications :
sudo netplan apply2.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 :
# 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] É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 :
- Accédez à votre portail Cloudflare Zero Trust > Networks > Tunnels.
- Créez un nouveau tunnel de type Cloudflared (exemple de nom :
portel-n8n-tunnel). - Copiez le
TUNNEL_TOKEN(long bloc de texte alphanumérique fourni par Cloudflare pour authentifier votre conteneur). - 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).
- Domaine Public :
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.
mkdir -p ~/n8n-docker && cd ~/n8n-docker4.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.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 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 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. Opérations de Console et Diagnostic
Sección titulada «5. Operaciones de Consola y Diagnóstico»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) :
cd ~/n8n-dockerdocker compose up -d5.2 Lecture des Logs en Temps Réel
Sección titulada «5.2 Lectura de Logs en Tiempo Real»Pour surveiller de manière analytique le flux de données ou diagnostiquer les échecs de démarrage :
# 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 Réinitialisation d'Usine (Maintenance d'Urgence)
Sección titulada «5.3 Restablecimiento de Fábrica (Mantenimiento de Emergencia)»[!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.
cd ~/n8n-docker# Detiene el stack eliminando los volúmenes asociadosdocker compose down -v
# Reconstruye el entorno desde cerodocker 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.ymlet.env) exempts de secrets en dur et intégrés avec des directives d'arrêt contrôlé.

