아키텍처 매뉴얼: Portelcore에서의 n8n 안전한 배포
Docker Compose를 통한 n8n 시작 가이드, 지속 가능한 관계형 PostgreSQL 데이터베이스 및 Cloudflare Tunnels를 통한 Zero Trust 라우팅
이 가이드는 n8n(워크플로우 자동화 고급 플랫폼)의 프로덕션 인스턴스 구현을 설명합니다. 아키텍처는 격리, 회복력 및 경계 보안 원칙을 우선시하여 설계되었습니다.
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 핵심 아키텍처 결정
Sección titulada «1.1 Decisiones Arquitectónicas Clave»- 실행 환경: Proxmox VE 하이퍼바이저에서 단독으로 실행되는 가상화된 Ubuntu Server 서버.
- 컨테이너 오케스트레이션: 불변, 이동 가능 및 쉽게 감사할 수 있는 환경을 보장하기 위한 Docker 및 Docker Compose.
- 관계형 데이터베이스: 기본 저장소(SQLite)에서 PostgreSQL 16으로의 마이그레이션. 이 결정은 고복잡도에서 쓰기 차단을 방지하고 향후 수평 확장(추가 워커를 통한 Queue 모드)을 위한 기반을 마련합니다.
- 경계 보안(제로 트러스트): Cloudflare Tunnels 구현(
cloudflared).- 주요 이점: Ubuntu 호스트는 인터넷에 인바운드 포트(
80및443및5678)를 전혀 노출하지 않습니다. 터널 컨테이너는 Cloudflare Edge와 직접적인 안전하고 암호화된 아웃바운드 연결을 설정하여 로컬 네트워크를 악의적 스캔으로부터 보호하고 SSL(HTTPS) 인증서를 Edge에 위임합니다.
- 주요 이점: Ubuntu 호스트는 인터넷에 인바운드 포트(
- 인프라 as 코드(IaC):
docker-compose.yml파일과 비감성적 환경 변수.env를 사용하여 인프라를 선언적으로 정의하여 스택 백업 및 복제를 용이하게 합니다.
2. 운영 체제(Ubuntu) 준비
Sección titulada «2. Preparación del Sistema Operativo (Ubuntu)»2.1 네트워크 설정(Netplan)
Sección titulada «2.1 Configuración de Red (Netplan)»Ubuntu 호스트에 정적 IP를 설정하여 네트워크 로컬 DHCP 서버에서 발생하는 충돌을 방지하고 서비스 해석을 투명하게 보장합니다. 이 고엔트로피 실험실에서 노드는 172.22.40.231 주소에 응답합니다.
시스템 네트워크 파일을 편집하십시오:
sudo nano /etc/netplan/50-cloud-init.yaml내부 기업 네트워크에 설정을 일치시키십시오:
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변경 사항을 적용하십시오:
sudo netplan apply업데이트된 엔진과 공식 오케스트레이션 라이브러리 설치를 보장하십시오:
# 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] 중요 운영 단계: 활성화된 콘솔 세션(
exit)을 닫고 SSH를 통해 다시 로그인하여 Docker 로컬 소켓의 사용자 토큰 권한을 갱신해야 함을 기억하십시오.
3. Cloudflare Zero Trust 설정 (터널)
Sección titulada «3. Configuración de Cloudflare Zero Trust (El Túnel)»호스트에서 컨테이너를 초기화하기 전에 Cloudflare 콘솔에서 안전한 터널을 준비합니다.
- 당신의 Cloudflare Zero Trust 포털 > Networks > Tunnels에 접근하십시오.
- Cloudflared 유형의 새 터널을 생성하십시오 (예:
portel-n8n-tunnel). - Cloudflare가 제공하는 컨테이너 인증용 긴 알파벳 숫자 블록
TUNNEL_TOKEN을 복사하십시오. - 공개 경로(Public Hostname) 구성:
- 공개 도메인:
n8n.portelcore.com - 서비스 유형:
HTTP - 내부 URL (목적지):
n8n:5678(참고: Docker Compose 가상 네트워크에서 제공하는 내부 DNS 해석을 사용합니다).
- 공개 도메인:
4. 스택 구조 및 구성 (IaC)
Sección titulada «4. Estructura y Composición del Stack (IaC)»우리의 모든 인프라스트럭처는 ~/n8n-docker 디렉토리에 정리된 방식으로 저장됩니다.
mkdir -p ~/n8n-docker && cd ~/n8n-docker4.1 환경 변수 파일 (.env)
Sección titulada «4.1 Archivo de Variables de Entorno (.env)»이 파일은 가상 포트, 데이터베이스 비밀번호 및 인증 토큰을 중앙에서 저장합니다. 실제 시크릿을 포함한 이 파일을 공개 코드 저장소에 업로드하는 것은 엄격히 금지됩니다.
파일: ~/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 멀티레이어 오케스트레이션 (docker-compose.yml)
Sección titulada «4.2 Orquestación Multicapa (docker-compose.yml)»이 파일은 관계형 데이터베이스 (Postgres 16), n8n 플로우 서버 및 Cloudflare 터널 에이전트를 선언합니다. 서비스 중단을 완화하고 논리적 의존성을 보장하기 위해 고급 건강 검사 (healthchecks)가 포함되어 있습니다.
파일: ~/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.1 초기 배포 및 스택 시작
Sección titulada «5.1 Despliegue Inicial y Arranque del Stack»첫 번째로 선언된 모든 인프라스트럭처를 백그라운드에서 시작하려면 (혹은 .env 파일을 수정한 후):
cd ~/n8n-dockerdocker compose up -d분석적으로 데이터 흐름을 모니터링하거나 시작 오류를 진단하기 위해:
# 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 공장 초기화 (긴급 유지보수)
Sección titulada «5.3 Restablecimiento de Fábrica (Mantenimiento de Emergencia)»[!CAUTION] 파괴적 작업: 다음 명령은 호스트의 모든 컨테이너와 로컬 볼륨을 영구적으로 삭제합니다(n8n 워크플로우 자격 증명, 사용자 및 히스토리 포함). 실험실 또는 심각한 비상 상황에서만 사용하십시오.
cd ~/n8n-docker# Detiene el stack eliminando los volúmenes asociadosdocker compose down -v
# Reconstruye el entorno desde cerodocker compose up -d📊 운영 성공 체크리스트
Sección titulada «📊 Checklist de Éxito Operativo»- ✓ 엄격한 HTTPS 암호화: Cloudflare 엣지에서
n8n.portelcore.com로 직접 라우팅되는 엔드투엔드 암호화 트래픽. - ✓ 관계형 지속성: 자동화된 건강 검사로 검증된 PostgreSQL 16 데이터베이스 엔진.
- ✓ 격리된 네트워크 보안: 공공 네트워크에 호스트 포트가 열려 있지 않으며, 내부 라우팅은 Docker의 닫힌 가상 브리지로 전달됩니다.
- ✓ 선언형 표준: 시크릿이 고정되지 않은 IaC 파일 (
docker-compose.yml및.env)과 제어된 중지 정책이 통합되어 있습니다.

