Architekturhandbuch: Sichere Bereitstellung von n8n bei Portelcore
Technischer Leitfaden zur Inbetriebnahme von n8n mittels Docker Compose, einer persistenten PostgreSQL-Relationaldatenbank und Zero-Trust-Routing mit Cloudflare Tunnels.
1. Architekturübersicht
Sección titulada «1. Visión General de la Arquitectura»Diese Anleitung beschreibt detailliert die Implementierung einer produktionsorientierten n8n-Instanz (eine fortschrittliche Plattform zur Workflow-Automatisierung). Die Architektur wurde unter Priorisierung der Prinzipien Isolierung, Resilienz und Perimeter-Sicherheit entwickelt.
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 Wichtige Architekturentscheidungen
Sección titulada «1.1 Decisiones Arquitectónicas Clave»- Ausführungsumgebung: Virtualisierter Ubuntu Server, der isoliert auf einem Proxmox VE-Hypervisor läuft.
- Container-Orchestrierung: Docker und Docker Compose, um immutabile, portable und leicht prüfbare Umgebungen zu gewährleisten.
- Relationale Datenbank: Migration der Standard-Speicherung (SQLite) zu PostgreSQL 16. Diese Entscheidung verhindert Schreibsperren bei hoher Nebenläufigkeit und schafft die Grundlage für zukünftige horizontale Skalierbarkeit (im Queue-Modus über zusätzliche Worker).
- Perimeter-Sicherheit (Zero Trust): Implementierung von Cloudflare-Tunneln (
cloudflared).- Hauptvorteil: Der Ubuntu-Host öffnet keine eingehenden Ports (weder
80noch443noch5678) zum Internet. Der Tunnel-Container baut eine direkte, sichere und verschlüsselte ausgehende Verbindung zum Cloudflare Edge auf, wodurch das lokale Netzwerk vor bösartigen Scans geschützt wird und die SSL-Zertifikate (HTTPS) an den Edge delegiert werden.
- Hauptvorteil: Der Ubuntu-Host öffnet keine eingehenden Ports (weder
- Infrastructure as Code (IaC): Die Infrastruktur wird deklarativ mittels
docker-compose.yml-Dateien und nicht sensiblen Umgebungsvariablen.envdefiniert, was Backups und die Replikation des Stacks erleichtert.
2. Vorbereitung des Betriebssystems (Ubuntu)
Sección titulada «2. Preparación del Sistema Operativo (Ubuntu)»2.1 Netzwerkkonfiguration (Netplan)
Sección titulada «2.1 Configuración de Red (Netplan)»Auf dem Ubuntu-Host wird eine statische IP eingerichtet, um eine transparente Dienstauflösung zu gewährleisten und Kollisionen durch den DHCP-Server des lokalen Netzwerks zu vermeiden. In diesem High-Entropy-Labor antwortet der Knoten unter der Adresse 172.22.40.231.
Bearbeiten Sie die Netzwerkdatei des Systems:
sudo nano /etc/netplan/50-cloud-init.yamlPassen Sie die Konfiguration an das interne Unternehmensnetzwerk an:
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: 2Wenden Sie die Änderungen an:
sudo netplan apply2.2 Installation der Docker-Engine-Abhängigkeiten
Sección titulada «2.2 Instalación de Dependencias del Motor Docker»Stellen Sie die Installation der aktualisierten Engine und ihrer offiziellen Orchestrierungsbibliotheken sicher:
# 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] Kritischer Betriebsschritt: Denken Sie daran, Ihre aktive Konsolensitzung (
exit) zu schließen und erneut über SSH einzuloggen, um die Berechtigungen Ihres Benutzertokens im lokalen Docker-Socket zu aktualisieren.
3. Konfiguration von Cloudflare Zero Trust (Der Tunnel)
Sección titulada «3. Configuración de Cloudflare Zero Trust (El Túnel)»Bevor wir die Container auf dem Host initialisieren, bereiten wir den sicheren Tunnel in der Cloudflare-Konsole vor:
- Greife auf dein Portal Cloudflare Zero Trust > Networks > Tunnels zu.
- Erstelle einen neuen Tunnel vom Typ Cloudflared (Beispielname:
portel-n8n-tunnel). - Kopiere den
TUNNEL_TOKEN(einen langen alphanumerischen Textblock, der von Cloudflare zur Authentifizierung deines Containers bereitgestellt wird). - Konfiguriere den öffentlichen Pfad (Public Hostname):
- Öffentliche Domäne:
n8n.portelcore.com - Diensttyp:
HTTP - Interne URL (Ziel):
n8n:5678(Hinweis: Die interne DNS-Auflösung wird durch das virtuelle Netzwerk von Docker Compose bereitgestellt).
- Öffentliche Domäne:
4. Struktur und Aufbau des Stacks (IaC)
Sección titulada «4. Estructura y Composición del Stack (IaC)»Unsere gesamte Infrastruktur ist organisiert im Verzeichnis ~/n8n-docker untergebracht.
mkdir -p ~/n8n-docker && cd ~/n8n-docker4.1 Datei mit Umgebungsvariablen (.env)
Sección titulada «4.1 Archivo de Variables de Entorno (.env)»Diese Datei speichert zentral die fiktiven Listening-Ports, Datenbankpasswörter und Authentifizierungs-Tokens. Es ist strengstens untersagt, diese Datei mit echten Geheimnissen in öffentliche Versionskontroll-Repositories hochzuladen.
Datei: ~/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 Mehrschichtige Orchestrierung (docker-compose.yml)
Sección titulada «4.2 Orquestación Multicapa (docker-compose.yml)»Diese Datei definiert die relationale Datenbank-Engine (Postgres 16), den n8n-Workflow-Server und den Cloudflare-Tunnel-Agenten. Fortgeschrittene Gesundheitsprüfungen (healthchecks) sind enthalten, um Dienstausfälle zu minimieren und saubere logische Abhängigkeiten zu gewährleisten.
Datei: ~/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. Konsolenoperationen und Diagnose
Sección titulada «5. Operaciones de Consola y Diagnóstico»5.1 Initiales Deployment und Start des Stacks
Sección titulada «5.1 Despliegue Inicial y Arranque del Stack»Um die gesamte im Hintergrund deklarierte Infrastruktur zum ersten Mal (oder nach Änderungen an der Datei .env) hochzufahren:
cd ~/n8n-dockerdocker compose up -d5.2 Lesen von Logs in Echtzeit
Sección titulada «5.2 Lectura de Logs en Tiempo Real»Um den Datenfluss analytisch zu überwachen oder Startfehler zu diagnostizieren:
# 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 Zurücksetzen auf Werkseinstellungen (Notfallwartung)
Sección titulada «5.3 Restablecimiento de Fábrica (Mantenimiento de Emergencia)»[!CAUTION] Destruktive Operation: Der folgende Befehl löscht permanent alle Container und lokalen Volumes des Hosts (Löschen von Anmeldeinformationen, Benutzern und Verlauf von n8n-Flüssen). Verwenden Sie es nur in Laborumgebungen oder bei schweren Notfällen.
cd ~/n8n-docker# Detiene el stack eliminando los volúmenes asociadosdocker compose down -v
# Reconstruye el entorno desde cerodocker compose up -d📊 Checkliste für den operativen Erfolg
Sección titulada «📊 Checklist de Éxito Operativo»- ✓ Strikte HTTPS-Verschlüsselung: Ende-zu-Ende verschlüsselter Datenverkehr, der nativ über die Cloudflare-Edge zu
n8n.portelcore.comgeroutet wird. - ✓ Relationale Persistenz: PostgreSQL 16 Datenbank-Engine, verifiziert durch automatisierte Health-Checks.
- ✓ Isolierte Netzwerksicherheit: Keine Host-Ports im öffentlichen Netzwerk offen; das interne Routing wird über eine geschlossene Docker-Virtual-Bridge geleitet.
- ✓ Deklarativer Standard: IaC-Dateien (
docker-compose.ymlund.env) frei von Hardcoded Secrets und integriert mit kontrollierten Shutdown-Richtlinien.

