Ir al contenido

Manuál architektúry: Bezpečné nasadenie n8n na Portelcore

Technický návod pre uvedenie do prevádzky n8n pomocou Docker Compose, perzistentnej relačnej databáze PostgreSQL a smerovania Zero Trust s Cloudflare Tunnels.

0lecturas

Táto príručka podrobne popisuje implementáciu inštancie n8n (pokročilá platforma automatizácie pracovných tokov) orientovanej na produkciu. Architektúra je navrhnutá s prioritou izolácie, odolnosti a bezpečnosti hraníc.

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 Kľúčové architektonické rozhodnutia

Sección titulada «1.1 Decisiones Arquitectónicas Clave»
  • Prostredie spustenia: Virtualizovaný server Ubuntu Server spustenie v izolovanom režime na hypervizore Proxmox VE.
  • Orchester kontajnerov: Docker a Docker Compose pre zabezpečenie nemenných, prenosných a ľahko auditovateľných prostredí.
  • Relačná databáza: Migrácia predvoleného úložiska (SQLite) na PostgreSQL 16. Toto rozhodnutie zabraňuje zámkom zápisu pri vysokej súbežnosti a vytvára základ pre budúcu horizontálnu škálovateľnosť (režim Queue prostredníctvom dodatočných pracovníkov).
  • Perimeter Security (Zero Trust): Implementácia Cloudflare Tunnels (cloudflared).
    • Hlavný prínos: Hostiteľ Ubuntu neexponuje žiadne vstupné porty (ani 80 ani 443 ani 5678) na internet. Kontajner tunela vytvára bezpečné a šifrované výstupné spojenie priamo s Cloudflare Edge, chráni lokálnu sieť pred škodlivými skenmi a deleguje SSL certifikáty (HTTPS) na Edge.
  • Infrastruktúra ako kód (IaC): Infrastruktúra je definovaná deklaratívne prostredníctvom súborov docker-compose.yml a premenných prostredia .env, ktoré nie sú citlivé, čo uľahčuje zálohovanie a replikáciu zásobníka.

Na hostiteľovi Ubuntu je nastavená statická IP adresa, aby bola zabezpečená transparentná rezolúcia služieb a predchádzanie kolíziám v lokálnej sieti vygenerovaným serverom DHCP. V tomto vysoko entropickom laboratóriu uzol reaguje na adrese 172.22.40.231.

Editujte súbor sieťovej konfigurácie systému:

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

Zarovnajte konfiguráciu so sieťou korporácie:

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

Použite zmeny:

Ventana de terminal
sudo netplan apply

Zabezpečte inštaláciu aktualizovaného motora a jeho oficiálnych knižníc orchestrácie:

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] Kritický operačný krok: Nezabudnite zatvoriť aktívnu reláciu konzoly (exit) a znovu sa prihlásiť cez SSH, aby ste obnovili privilégiá vášho používateľského tokenu v lokálnom socketu Docker.


3. Konfigurácia Cloudflare Zero Trust (The Tunnel)

Sección titulada «3. Configuración de Cloudflare Zero Trust (El Túnel)»

Pred inicializáciou kontajnerov na hostiteľovi pripravíme bezpečný tunel v konzole Cloudflare:

  1. Získajte prístup k vášmu portálu Cloudflare Zero Trust > Networks > Tunnels.
  2. Vytvorte nový tunel typu Cloudflared (príklad názvu: portel-n8n-tunnel).
  3. Skopírujte TUNNEL_TOKEN (dlhý alfanumerický textový blok poskytnutý spoločnosťou Cloudflare na autentifikáciu vášho kontajnera).
  4. Konfigurácia verejnej cesty (Public Hostname):
    • Verejná doména: n8n.portelcore.com
    • Typ služby: HTTP
    • Interná adresa URL (ciel): n8n:5678 (Poznámka: Používa sa interná DNS rezolúcia poskytovaná virtuálnou sieťou Docker Compose).

Všetka naša infraštruktúra je organizovane umiestnená v adresári ~/n8n-docker.

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

Tento súbor centralizovane ukladá fiktívne počúvacie porty, heslá databáze a tokeny autentifikácie. Je prísne zakázané nahrať tento súbor so skutočnými tajnými údajmi do verejných repozitárov riadenia kódu.

Súbor: ~/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 Viacúrovňová orchestrácia (docker-compose.yml)

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

Tento súbor deklaruje motor relačnej databáze (Postgres 16), server tokov n8n a agenta tunela Cloudflare. Sú zahrnuté pokročilé kontroly zdravia (healthchecks) na zmiernenie výpadkov služieb a zabezpečenie čistých logických závislostí.

Súbor: ~/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čiatočné nasadenie a spustenie stohu

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

Na zvýšenie celej infraštruktúry deklarovanej na pozadí prvýkrát (alebo po vykonaní zmien v súbore .env):

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

5.2 Čítanie protokolov v reálnom čase

Sección titulada «5.2 Lectura de Logs en Tiempo Real»

Na analytické monitorovanie toku dát alebo diagnostiku problémov so spustením:

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 Obnovenie továrenského nastavenia (údržba v núdzových situáciách)

Sección titulada «5.3 Restablecimiento de Fábrica (Mantenimiento de Emergencia)»

[!CAUTION] Destruktívna operácia: Nasledujúci príkaz trvalo odstráni všetky kontajnery a lokálne objemy na hostiteľovi (vymazanie poverení, používateľov a histórie tokov n8n). Používajte ho iba v laboratóriách alebo pri vážnych výnimkách.

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ý zoznam úspešnej operácie

Sección titulada «📊 Checklist de Éxito Operativo»
  • ✓ Prísne HTTPS šifrovanie: Šifrovaný prenos z konca na koniec smerovaný pôvodne Edgeom Cloudflare do n8n.portelcore.com.
  • ✓ Relácia perzistencie: Overený motor relačnej databáze PostgreSQL 16 prostredníctvom automatizovaných kontrol zdravia.
  • ✓ Bezpečnosť izolovanej siete: Žiadne porty hostiteľa nie sú otvorené v verejnej sieti, smerovanie interných trás cez uzavretý virtuálny most Docker.
  • ✓ Declaratívny štandard: Súbory IaC (docker-compose.yml a .env) čisté z pevných tajných údajov a integrované s direktívami riadeného zastavenia.