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.
1. Architectuuroverzicht
Sección titulada «1. Visión General de la Arquitectura»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 end1.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,443of5678) 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.
- Belangrijkste voordeel: De Ubuntu-host legt geen enkele inkomende poort bloot (geen
- Infrastructure as Code (IaC): De infrastructuur wordt declaratief gedefinieerd via
docker-compose.ymlbestanden en niet-gevoelige.envomgevingsvariabelen, 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)»2.1 Netwerkconfiguratie (Netplan)
Sección titulada «2.1 Configuración de Red (Netplan)»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:
sudo nano /etc/netplan/50-cloud-init.yamlStem 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: 2Pas de wijzigingen toe:
sudo netplan apply2.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:
# 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] 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.
3. Cloudflare Zero Trust-configuratie (De Tunnel)
Sección titulada «3. Configuración de Cloudflare Zero Trust (El Túnel)»Voordat we de containers op de host initialiseren, bereiden we de veilige tunnel voor in de Cloudflare-console:
- Ga naar je portal Cloudflare Zero Trust > Networks > Tunnels.
- Maak een nieuwe tunnel aan van het type Cloudflared (voorbeeldnaam:
portel-n8n-tunnel). - Kopieer de
TUNNEL_TOKEN(een lange alfanumerieke tekstblok die door Cloudflare wordt verstrekt om je container te authenticeren). - 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).
- Publiek domein:
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.
mkdir -p ~/n8n-docker && cd ~/n8n-docker4.1 Omgevingsvariabelen-bestand (.env)
Sección titulada «4.1 Archivo de Variables de Entorno (.env)»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.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 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 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. Console- en Diagnosebewerkingen
Sección titulada «5. Operaciones de Consola y Diagnóstico»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):
cd ~/n8n-dockerdocker compose up -d5.2 Realtime Logboeken Lezen
Sección titulada «5.2 Lectura de Logs en Tiempo Real»Om de gegevensstroom analytisch te monitoren of opstartfouten te diagnosticeren:
# 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 Fabrieksreset (Noodonderhoud)
Sección titulada «5.3 Restablecimiento de Fábrica (Mantenimiento de Emergencia)»[!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.
cd ~/n8n-docker# Detiene el stack eliminando los volúmenes asociadosdocker compose down -v
# Reconstruye el entorno desde cerodocker 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.comwordt 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.ymlen.env) vrij van hardcoded secrets en geïntegreerd met gecontroleerde stopinstructies.

