Ir al contenido

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.

0Lesungen

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
end
  • 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 80 noch 443 noch 5678) 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.
  • Infrastructure as Code (IaC): Die Infrastruktur wird deklarativ mittels docker-compose.yml-Dateien und nicht sensiblen Umgebungsvariablen .env definiert, was Backups und die Replikation des Stacks erleichtert.

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:

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

Passen 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: 2

Wenden Sie die Änderungen an:

Ventana de terminal
sudo netplan apply

2.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:

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] 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:

  1. Greife auf dein Portal Cloudflare Zero Trust > Networks > Tunnels zu.
  2. Erstelle einen neuen Tunnel vom Typ Cloudflared (Beispielname: portel-n8n-tunnel).
  3. Kopiere den TUNNEL_TOKEN (einen langen alphanumerischen Textblock, der von Cloudflare zur Authentifizierung deines Containers bereitgestellt wird).
  4. 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).

Unsere gesamte Infrastruktur ist organisiert im Verzeichnis ~/n8n-docker untergebracht.

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

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.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 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 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 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:

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

Um den Datenfluss analytisch zu überwachen oder Startfehler zu diagnostizieren:

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 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.

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

📊 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.com geroutet 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.yml und .env) frei von Hardcoded Secrets und integriert mit kontrollierten Shutdown-Richtlinien.