Ir al contenido

Architectuurhandleiding: Veilige implementatie van n8n bij Portelcore

Technische gids voor de inbedrijfstelling van n8n via Docker Compose, een persistente PostgreSQL relationele database en Zero Trust-routing met Cloudflare Tunnels.

0lecturas

Deze gids beschrijft de implementatie van een n8n-instantie (geavanceerd platform voor workflowautomatisering) gericht op productie. De architectuur is ontworpen met prioriteit voor de principes van isolatie, veerkracht en perimeterbeveiliging.

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

1.1 Belangrijkste architectuurbeslissingen

Sección titulada «1.1 Decisiones Arquitectónicas Clave»
  • Runtimeomgeving: Gevirtualiseerde Ubuntu Server die geïsoleerd draait op een Proxmox VE hypervisor.
  • Container-orchestratie: Docker en Docker Compose om immutabele, draagbare en gemakkelijk auditeerbare omgevingen te garanderen.
  • Relationele database: Migratie van de standaardopslag (SQLite) naar PostgreSQL 16. Deze beslissing voorkomt write-locks bij een hoge mate van concurrency en legt de basis voor toekomstige horizontale schaalbaarheid (via de Queue-modus met extra workers).
  • Seguridad Perimetral (Zero Trust): Implementación de Cloudflare Tunnels (cloudflared).
    • Belangrijkste voordeel: De Ubuntu-host legt geen enkele inkomende poort bloot (geen 80, 443 of 5678) aan het internet. De tunnelcontainer maakt een directe, veilige en versleutelde uitgaande verbinding met de Cloudflare Edge, waardoor het lokale netwerk wordt beschermd tegen kwaadaardige scans en de SSL-certificaten (HTTPS) aan de Edge worden gedelegeerd.
  • Infrastructure as Code (IaC): De infrastructuur wordt declaratief gedefinieerd via docker-compose.yml bestanden en niet-gevoelige .env omgevingsvariabelen, wat back-ups en de replicatie van de stack vergemakkelijkt.

2. Voorbereiding van het besturingssysteem (Ubuntu)

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

Er wordt een statisch IP ingesteld op de Ubuntu-host om een transparante resolutie van services te garanderen en botsingen door de DHCP-server van het lokale netwerk te voorkomen. In dit high-entropy laboratorium reageert de node op het adres 172.22.40.231.

Bewerk het systeemnetwerkbestand:

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

Stem de configuratie af op het interne bedrijfsnetwerk:

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

Pas de wijzigingen toe:

Ventana de terminal
sudo netplan apply

2.2 Installatie van Docker Engine-afhankelijkheden

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

Zorg voor de installatie van de bijgewerkte engine en de officiële orkestratiebibliotheken:

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] Kritieke operationele stap: Onthoud dat je de actieve consolesessie (exit) moet sluiten en opnieuw moet inloggen via SSH om de privileges van je gebruikers token in de lokale Docker-socket te vernieuwen.


Voordat we de containers op de host initialiseren, bereiden we de veilige tunnel voor in de Cloudflare-console:

  1. Ga naar je portal Cloudflare Zero Trust > Networks > Tunnels.
  2. Maak een nieuwe tunnel aan van het type Cloudflared (voorbeeldnaam: portel-n8n-tunnel).
  3. Kopieer de TUNNEL_TOKEN (een lange alfanumerieke tekstblok die door Cloudflare wordt verstrekt om je container te authenticeren).
  4. Configura la ruta pública (Public Hostname):
    • Publiek domein: n8n.portelcore.com
    • Type service: HTTP
    • Interne URL (Bestemming): n8n:5678 (Opmerking: Maakt gebruik van de interne DNS-resolutie die wordt geleverd door het virtuele Docker Compose-netwerk).

4. Structuur en Samenstelling van de Stack (IaC)

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

Onze gehele infrastructuur bevindt zich georganiseerd in de directory ~/n8n-docker.

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

Dit bestand slaat op een gecentraliseerde manier de fictieve luisterpoorten, databasewachtwoorden en authenticatietokens op. Het is ten strengste verboden om dit bestand met echte geheimen te uploaden naar openbare broncode-repositories.

Bestand: ~/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 Meerlaagse orkestratie (docker-compose.yml)

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

Dit bestand declareert de relationele database-engine (Postgres 16), de n8n-workflowserver en de Cloudflare tunnel agent. Geavanceerde gezondheidscontroles (healthchecks) zijn inbegrepen om service-uitval te beperken en schone logische afhankelijkheden te garanderen.

Bestand: ~/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 Initiële Implementatie en Opstarten van de Stack

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

Om de volledige gedocumenteerde infrastructuur voor de eerste keer op de achtergrond op te zetten (of na wijzigingen in het bestand .env):

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

Om de gegevensstroom analytisch te monitoren of opstartfouten te diagnosticeren:

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] Destructieve bewerking: De volgende opdracht verwijdert permanent alle containers en lokale volumes van de host (waarbij referenties, gebruikers en geschiedenis van n8n-flows worden verwijderd). Gebruik dit alleen in laboratoria of bij ernstige noodsituaties.

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 voor Operationeel Succes

Sección titulada «📊 Checklist de Éxito Operativo»
  • ✓ Strikte HTTPS-encryptie: End-to-end versleuteld verkeer dat natief via de Cloudflare Edge naar n8n.portelcore.com wordt gerouteerd.
  • ✓ Relationele persistentie: PostgreSQL 16 database-engine geverifieerd via geautomatiseerde healthchecks.
  • ✓ Geïsoleerde netwerkbeveiliging: Nul hostpoorten open op het publieke netwerk, waarbij intern verkeer via een gesloten Docker-virtueel bridge-netwerk wordt geleid.
  • ✓ Declaratieve standaard: IaC-bestanden (docker-compose.yml en .env) vrij van hardcoded secrets en geïntegreerd met gecontroleerde stopinstructies.