Architektonická příručka: Bezpečné nasazení n8n v Portelcore
Technická příručka pro uvedení n8n do provozu pomocí Docker Compose, persistentní relační databáze PostgreSQL a routování Zero Trust pomocí Cloudflare Tunnels.
1. Přehled architektury
Sección titulada «1. Visión General de la Arquitectura»Tento průvodce podrobně popisuje implementaci instance n8n (pokročilá platforma pro automatizaci pracovních postupů) určenou pro produkci. Architektura byla navržena se zaměřením na principy izolace, odolnosti a perimetrální bezpečnosti.
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 Klíčová architektonická rozhodnutí
Sección titulada «1.1 Decisiones Arquitectónicas Clave»- Provozní prostředí: Virtualizovaný server Ubuntu Server běžící izolovaně na hypervisoru Proxmox VE.
- Orchestrace kontejnerů: Docker a Docker Compose pro zajištění neměnných, přenosných a snadno auditovatelných prostředí.
- Relacionální databáze: Migrace výchozího úložiště (SQLite) na PostgreSQL 16. Toto rozhodnutí zabraňuje blokování zápisu při vysoké souběžnosti a pokládá základy pro budoucí horizontální škálovatelnost (režim Queue pomocí dalších workerů).
- Perimetrická Bezpečnost (Zero Trust): Implementace Cloudflare Tunnels (
cloudflared).- Hlavní přínos: Hostitel Ubuntu neexponuje žádný vstupní port (ani
80, ani443, ani5678) do internetu. Kontejner tunelu navazuje bezpečné a šifrované přímé odchozí spojení s Cloudflare Edge, čímž chrání lokální síť před škodlivým skenováním a deleguje SSL (HTTPS) certifikáty na Edge.
- Hlavní přínos: Hostitel Ubuntu neexponuje žádný vstupní port (ani
- Infrastruktura jako kód (IaC): Infrastruktura je definována deklarativně pomocí souborů
docker-compose.ymla necitlivých proměnných prostředí.env, což usnadňuje zálohování a replikaci stacku.
2. Příprava operačního systému (Ubuntu)
Sección titulada «2. Preparación del Sistema Operativo (Ubuntu)»2.1 Konfigurace sítě (Netplan)
Sección titulada «2.1 Configuración de Red (Netplan)»Na hostitelském počítači Ubuntu je nastavena statická IP adresa pro zajištění transparentního rozlišení služeb a vyhnutí se kolizím způsobeným místním DHCP serverem. V tomto vysoce entropickém laboratoři uzel odpovídá na adrese 172.22.40.231.
Upravte síťový soubor systému:
sudo nano /etc/netplan/50-cloud-init.yamlZarovnejte konfiguraci s interní firemní sítí:
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: 2Aplikujte změny:
sudo netplan apply2.2 Instalace závislostí Docker Engine
Sección titulada «2.2 Instalación de Dependencias del Motor Docker»Zajistěte instalaci aktualizovaného enginu a jeho oficiálních orchestračních knihoven:
# 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]\r Paso Operativo Crítico: Recuerda cerrar tu sesión de consola activa (
exit) y volver a ingresar vía SSH para refrescar los privilegios de tu token de usuario en el socket local de Docker.
3. Konfigurace Cloudflare Zero Trust (Tunel)
Sección titulada «3. Configuración de Cloudflare Zero Trust (El Túnel)»Před inicializací kontejnerů na hostiteli připravíme bezpečný tunel v konzoli Cloudflare:
- Přístup k vašemu portálu Cloudflare Zero Trust > Networks > Tunnels.
- Vytvořte nový tunel typu Cloudflared (příklad názvu:
portel-n8n-tunnel). - Zkopírujte
TUNNEL_TOKEN(dlouhý alfanumerický textový blok poskytnutý Cloudflare pro autentizaci vašeho kontejneru). - Konfigurujte veřejnou cestu (Public Hostname):
- Veřejná Doména:
n8n.portelcore.com - Typ služby:
HTTP - Interní URL (cílová):
n8n:5678(Poznámka: Používá se interní DNS rezoluce poskytovaná virtuální sítí Docker Compose).
- Veřejná Doména:
4. Struktura a složení stacku (IaC)
Sección titulada «4. Estructura y Composición del Stack (IaC)»Veškerá naše infrastruktura je organizovaně uložena v adresáři ~/n8n-docker.
mkdir -p ~/n8n-docker && cd ~/n8n-docker4.1 Soubor proměnných prostředí (.env)
Sección titulada «4.1 Archivo de Variables de Entorno (.env)»Tento soubor centrálně uchovává fiktivní naslouchací porty, hesla k databázím a ověřovací tokeny. Je přísně zakázáno nahrávat tento soubor se skutečnými tajnými údaji do veřejných repozitářů pro správu kódu.
Soubor: ~/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 Vrstvená orchestrace (docker-compose.yml)
Sección titulada «4.2 Orquestación Multicapa (docker-compose.yml)»Tento soubor definuje relační databázový engine (Postgres 16), server workflowů n8n a agenta Cloudflare tunelu. Jsou zahrnuty pokročilé kontroly stavu (healthchecks) pro zmírnění výpadků služeb a zajištění čistých logických závislostí.
Soubor: ~/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. Operace v konzoli a diagnostika
Sección titulada «5. Operaciones de Consola y Diagnóstico»5.1 Počáteční nasazení a spuštění stacku
Sección titulada «5.1 Despliegue Inicial y Arranque del Stack»Pro první spuštění celé deklarované infrastruktury na pozadí (nebo po provedení změn ve souboru .env):
cd ~/n8n-dockerdocker compose up -d5.2 Čtení logů v reálném čase
Sección titulada «5.2 Lectura de Logs en Tiempo Real»Pro analytické monitorování toku dat nebo diagnostiku chyb při spouštění:
# 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 Obnovení do továrního nastavení (Nouzová údržba)
Sección titulada «5.3 Restablecimiento de Fábrica (Mantenimiento de Emergencia)»[!CAUTION]\r Operación Destructiva: El siguiente comando elimina permanentemente todos los contenedores y los volúmenes locales del host (borrando credenciales, usuarios e historiales de flujos de n8n). Úsalo únicamente en laboratorios o contingencias graves.
cd ~/n8n-docker# Detiene el stack eliminando los volúmenes asociadosdocker compose down -v
# Reconstruye el entorno desde cerodocker compose up -d📊 Kontrolní seznam provozního úspěchu
Sección titulada «📊 Checklist de Éxito Operativo»- ✓ Striké Šifrování HTTPS: Koncové šifrování provozu nativně směrováno pomocí Edge Cloudflare směrem k
n8n.portelcore.com. - ✓ Relacionální Perzistence: Ověřený motor databáze PostgreSQL 16 pomocí automatizovaných zdravotních kontrol.
- ✓ Bezpečnost Izolované Sítě: Žádné hostitelské porty nejsou otevřeny v veřejné síti, vnitřní směrování je kanalizováno přes uzavřený virtuální most Docker.
- ✓ Declarativní Standard: Soubory IaC (
docker-compose.ymla.env) čisté od tuhých tajemství a integrované s řízeným zastavením.

