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.
1. Prehľad architektúry
Sección titulada «1. Visión General de la Arquitectura»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 end1.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
80ani443ani5678) 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.
- Hlavný prínos: Hostiteľ Ubuntu neexponuje žiadne vstupné porty (ani
- Infrastruktúra ako kód (IaC): Infrastruktúra je definovaná deklaratívne prostredníctvom súborov
docker-compose.ymla premenných prostredia.env, ktoré nie sú citlivé, čo uľahčuje zálohovanie a replikáciu zásobníka.
2. Príprava operačného systému (Ubuntu)
Sección titulada «2. Preparación del Sistema Operativo (Ubuntu)»2.1 Konfigurácia siete (Netplan)
Sección titulada «2.1 Configuración de Red (Netplan)»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:
sudo nano /etc/netplan/50-cloud-init.yamlZarovnajte 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: 2Použite zmeny:
sudo netplan apply2.2 Inštalácia závislostí Docker Engine
Sección titulada «2.2 Instalación de Dependencias del Motor Docker»Zabezpečte inštaláciu aktualizovaného motora a jeho oficiálnych knižníc orchestrácie:
# 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] 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:
- Získajte prístup k vášmu portálu Cloudflare Zero Trust > Networks > Tunnels.
- Vytvorte nový tunel typu Cloudflared (príklad názvu:
portel-n8n-tunnel). - Skopírujte
TUNNEL_TOKEN(dlhý alfanumerický textový blok poskytnutý spoločnosťou Cloudflare na autentifikáciu vášho kontajnera). - 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).
- Verejná doména:
4. Štruktúra a zloženie stohu (IaC)
Sección titulada «4. Estructura y Composición del Stack (IaC)»Všetka naša infraštruktúra je organizovane umiestnená v adresári ~/n8n-docker.
mkdir -p ~/n8n-docker && cd ~/n8n-docker4.1 Súbor premenných prostredia (.env)
Sección titulada «4.1 Archivo de Variables de Entorno (.env)»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.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 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 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. Operácie konzoly a diagnostika
Sección titulada «5. Operaciones de Consola y Diagnóstico»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):
cd ~/n8n-dockerdocker compose up -d5.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:
# 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 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.
cd ~/n8n-docker# Detiene el stack eliminando los volúmenes asociadosdocker compose down -v
# Reconstruye el entorno desde cerodocker 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.ymla.env) čisté z pevných tajných údajov a integrované s direktívami riadeného zastavenia.

