Podręcznik Architektury: Bezpieczne wdrożenie n8n w Portelcore
Przewodnik techniczny dotyczący uruchomienia n8n za pomocą Docker Compose, bazy danych relacyjnej PostgreSQL i routingu Zero Trust z Cloudflare Tunnels.
1. Przegląd Architektury
Sección titulada «1. Visión General de la Arquitectura»Ten podręcznik szczegółowo opisuje wdrożenie instancji n8n (zaawansowanej platformy automatyzacji przepływów pracy) przeznaczonej do produkcji. Architektura została zaprojektowana z uwzględnieniem zasad izolacji, odporności i bezpieczeństwa obwodowego.
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 Kluczowe decyzje architektoniczne
Sección titulada «1.1 Decisiones Arquitectónicas Clave»- Środowisko Wykonywania: Wirtualny serwer Ubuntu Server działający w izolacji na hipervisorze Proxmox VE
- Orkiestracja Kontenerów: Docker i Docker Compose, aby zapewnić niezmienne, przenośne i łatwe do audytu środowiska
- Baza Danych Relacyjna: Migracja z domyślnego przechowywania (SQLite) do PostgreSQL 16. Ta decyzja zapobiega blokowaniu zapisu pod wysokim obciążeniem i stanowi podstawę dla przyszłej skalowalności poziomej (tryb Kolejka za pomocą dodatkowych workerów)
- Seguridad Perimetral (Zero Trust): Implementación de Cloudflare Tunnels (
cloudflared).- Główna Korzyść: Host Ubuntu nie naraża żadnego portu wejściowego (ani
80ani443ani5678) na Internet. Kontener tunelu ustanawia bezpieczne i szyfrowane połączenie wyjściowe bezpośrednio z Edge Cloudflare, chroniąc sieć lokalną przed skanowaniem i delegując certyfikaty SSL (HTTPS) do Edge
- Główna Korzyść: Host Ubuntu nie naraża żadnego portu wejściowego (ani
- Infrastruktura jako Kod (IaC): Infrastruktura jest definiowana deklaratywnie za pomocą plików
docker-compose.ymli zmiennych środowiskowych.envniezawierających informacji poufnych, co ułatwia tworzenie kopii zapasowych i replikację stosu
2. Przygotowanie systemu operacyjnego (Ubuntu)
Sección titulada «2. Preparación del Sistema Operativo (Ubuntu)»2.1 Konfiguracja sieci (Netplan)
Sección titulada «2.1 Configuración de Red (Netplan)»Ustawiono statyczny adres IP w hoście Ubuntu, aby zapewnić przejrzyste rozwiązywanie usług i uniknąć kolizji wygenerowanych przez serwer DHCP sieci lokalnej. W tym laboratorium o wysokiej entropii węzeł odpowiada pod adresem 172.22.40.231
Edytuj plik sieci systemowej:
sudo nano /etc/netplan/50-cloud-init.yamlDopasuj konfigurację do sieci wewnętrznej korporacyjnej:
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: 2Zastosuj zmiany:
sudo netplan apply2.2 Instalacja zależności silnika Docker
Sección titulada «2.2 Instalación de Dependencias del Motor Docker»Upewnij się o instalacji zaktualizowanego silnika i jego oficjalnych bibliotek orkiestracji:
# 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] Krytyczny krok operacyjny: Pamiętaj, aby zamknąć aktywną sesję konsoli (
exit) i ponownie zalogować się za pomocą SSH, aby odświeżyć uprawnienia tokena użytkownika w lokalnym gnieździe Docker.
3. Konfiguracja Cloudflare Zero Trust (Túnel)
Sección titulada «3. Configuración de Cloudflare Zero Trust (El Túnel)»Przed zainicjowaniem kontenerów na hoście przygotowujemy bezpieczny tunel w konsoli Cloudflare:
- Zaloguj się do swojego portalu Cloudflare Zero Trust > Sieci > Tunele.
- Utwórz nowy tunel typu Cloudflared (przykładowa nazwa:
portel-n8n-tunnel). - Skopiuj
TUNNEL_TOKEN(blok tekstu alfanumerycznego dostarczony przez Cloudflare w celu uwierzytelnienia kontenera). - Configura la ruta pública (Public Hostname):
- Domena publiczna:
n8n.portelcore.com - Typ usługi:
HTTP - Wewnętrzny adres URL (destynacja):
n8n:5678(Uwaga: Wykorzystuje się wewnętrzną rozdzielczość DNS dostarczoną przez sieć wirtualną Docker Compose).
- Domena publiczna:
4. Struktura i skład Stacka (IaC)
Sección titulada «4. Estructura y Composición del Stack (IaC)»Cała nasza infrastruktura znajduje się w sposób zorganizowany w katalogu ~/n8n-docker.
mkdir -p ~/n8n-docker && cd ~/n8n-docker4.1 Plik zmiennych środowiskowych (.env)
Sección titulada «4.1 Archivo de Variables de Entorno (.env)»Ten plik przechowuje scentralizowane dane, takie jak fikcyjne porty nasłuchiwania, hasła do baz danych i tokeny uwierzytelniania. Wgrywanie tego pliku z rzeczywistymi sekretami do publicznych repozytoriów kontroli kodu jest surowo zabronione.
Plik: ~/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 Orkiestracja wielowarstwowa (docker-compose.yml)
Sección titulada «4.2 Orquestación Multicapa (docker-compose.yml)»Ten plik deklaruje relacyjny silnik bazy danych (Postgres 16), serwer przepływów n8n i agent tunelu Cloudflare. Zawiera zaawansowane kontrole zdrowia (healthchecks), aby złagodzić awarie usług i zapewnić czyste zależności logiczne.
Plik: ~/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. Operacje konsoli i diagnostyka
Sección titulada «5. Operaciones de Consola y Diagnóstico»5.1 Wdrożenie początkowe i uruchomienie Stacka
Sección titulada «5.1 Despliegue Inicial y Arranque del Stack»Aby podnieść całą infrastrukturę deklarowaną w tle po raz pierwszy (lub po wprowadzeniu zmian w pliku .env):
cd ~/n8n-dockerdocker compose up -d5.2 Odczyt logów w czasie rzeczywistym
Sección titulada «5.2 Lectura de Logs en Tiempo Real»Aby monitorować analitycznie przepływ danych lub diagnozować awarie rozruchu:
# 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 Reset do ustawień fabrycznych (konserwacja awaryjna)
Sección titulada «5.3 Restablecimiento de Fábrica (Mantenimiento de Emergencia)»[!CAUTION] Destrukcyjna operacja: Poniższe polecenie trwale usuwa wszystkie kontenery i lokalne wolumeny hosta (usuwając dane uwierzytelniające, użytkowników i historię przepływów n8n). Użyj go tylko w laboratoriach lub w przypadku poważnych problemów.
cd ~/n8n-docker# Detiene el stack eliminando los volúmenes asociadosdocker compose down -v
# Reconstruye el entorno desde cerodocker compose up -d📊 Lista kontrolna sukcesu operacyjnego
Sección titulada «📊 Checklist de Éxito Operativo»- ✓ Ścisłe szyfrowanie HTTPS: Szyfrowany ruch punkt-punkt kierowany w sposób natywny przez Edge Cloudflare do
n8n.portelcore.com. - ✓ Relacyjna trwałość: Silnik bazy danych PostgreSQL 16 zweryfikowany za pomocą automatycznych kontroli zdrowia.
- ✓ Zabezpieczenie sieci izolowanej: Żadne porty hosta nie są otwarte w publicznej sieci, a routing wewnętrzny odbywa się za pomocą zamkniętego mostka wirtualnego Docker.
- ✓ Declaratywny standard: Pliki IaC (
docker-compose.ymli.env) wolne od twardych sekretów i zintegrowane z kontrolowanymi zasadami zatrzymania.

