Ir al contenido

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.

0čtení

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
end

1.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, ani 443, ani 5678) 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.
  • Infrastruktura jako kód (IaC): Infrastruktura je definována deklarativně pomocí souborů docker-compose.yml a necitlivých proměnných prostředí .env, což usnadňuje zálohování a replikaci stacku.

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:

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

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

Aplikujte změny:

Ventana de terminal
sudo netplan apply

Zajistěte instalaci aktualizovaného enginu a jeho oficiálních orchestračních knihoven:

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


Před inicializací kontejnerů na hostiteli připravíme bezpečný tunel v konzoli Cloudflare:

  1. Přístup k vašemu portálu Cloudflare Zero Trust > Networks > Tunnels.
  2. Vytvořte nový tunel typu Cloudflared (příklad názvu: portel-n8n-tunnel).
  3. Zkopírujte TUNNEL_TOKEN (dlouhý alfanumerický textový blok poskytnutý Cloudflare pro autentizaci vašeho kontejneru).
  4. 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škerá naše infrastruktura je organizovaně uložena v adresáři ~/n8n-docker.

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

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

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

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

Pro analytické monitorování toku dat nebo diagnostiku chyb při spouštění:

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

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

📊 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.yml a .env) čisté od tuhých tajemství a integrované s řízeným zastavením.