Ir al contenido

아키텍처 매뉴얼: Portelcore에서의 n8n 안전한 배포

Docker Compose를 통한 n8n 시작 가이드, 지속 가능한 관계형 PostgreSQL 데이터베이스 및 Cloudflare Tunnels를 통한 Zero Trust 라우팅

0조회

이 가이드는 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
end
  • 실행 환경: Proxmox VE 하이퍼바이저에서 단독으로 실행되는 가상화된 Ubuntu Server 서버.
  • 컨테이너 오케스트레이션: 불변, 이동 가능 및 쉽게 감사할 수 있는 환경을 보장하기 위한 Docker 및 Docker Compose.
  • 관계형 데이터베이스: 기본 저장소(SQLite)에서 PostgreSQL 16으로의 마이그레이션. 이 결정은 고복잡도에서 쓰기 차단을 방지하고 향후 수평 확장(추가 워커를 통한 Queue 모드)을 위한 기반을 마련합니다.
  • 경계 보안(제로 트러스트): Cloudflare Tunnels 구현(cloudflared).
    • 주요 이점: Ubuntu 호스트는 인터넷에 인바운드 포트(80 및 443 및 5678)를 전혀 노출하지 않습니다. 터널 컨테이너는 Cloudflare Edge와 직접적인 안전하고 암호화된 아웃바운드 연결을 설정하여 로컬 네트워크를 악의적 스캔으로부터 보호하고 SSL(HTTPS) 인증서를 Edge에 위임합니다.
  • 인프라 as 코드(IaC): docker-compose.yml 파일과 비감성적 환경 변수 .env를 사용하여 인프라를 선언적으로 정의하여 스택 백업 및 복제를 용이하게 합니다.

Ubuntu 호스트에 정적 IP를 설정하여 네트워크 로컬 DHCP 서버에서 발생하는 충돌을 방지하고 서비스 해석을 투명하게 보장합니다. 이 고엔트로피 실험실에서 노드는 172.22.40.231 주소에 응답합니다.

시스템 네트워크 파일을 편집하십시오:

Ventana de terminal
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

변경 사항을 적용하십시오:

Ventana de terminal
sudo netplan apply

업데이트된 엔진과 공식 오케스트레이션 라이브러리 설치를 보장하십시오:

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] 중요 운영 단계: 활성화된 콘솔 세션(exit)을 닫고 SSH를 통해 다시 로그인하여 Docker 로컬 소켓의 사용자 토큰 권한을 갱신해야 함을 기억하십시오.


호스트에서 컨테이너를 초기화하기 전에 Cloudflare 콘솔에서 안전한 터널을 준비합니다.

  1. 당신의 Cloudflare Zero Trust 포털 > Networks > Tunnels에 접근하십시오.
  2. Cloudflared 유형의 새 터널을 생성하십시오 (예: portel-n8n-tunnel).
  3. Cloudflare가 제공하는 컨테이너 인증용 긴 알파벳 숫자 블록 TUNNEL_TOKEN을 복사하십시오.
  4. 공개 경로(Public Hostname) 구성:
    • 공개 도메인: n8n.portelcore.com
    • 서비스 유형: HTTP
    • 내부 URL (목적지): n8n:5678 (참고: Docker Compose 가상 네트워크에서 제공하는 내부 DNS 해석을 사용합니다).

우리의 모든 인프라스트럭처는 ~/n8n-docker 디렉토리에 정리된 방식으로 저장됩니다.

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

이 파일은 가상 포트, 데이터베이스 비밀번호 및 인증 토큰을 중앙에서 저장합니다. 실제 시크릿을 포함한 이 파일을 공개 코드 저장소에 업로드하는 것은 엄격히 금지됩니다.

파일: ~/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 멀티레이어 오케스트레이션 (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 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

첫 번째로 선언된 모든 인프라스트럭처를 백그라운드에서 시작하려면 (혹은 .env 파일을 수정한 후):

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

분석적으로 데이터 흐름을 모니터링하거나 시작 오류를 진단하기 위해:

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

[!CAUTION] 파괴적 작업: 다음 명령은 호스트의 모든 컨테이너와 로컬 볼륨을 영구적으로 삭제합니다(n8n 워크플로우 자격 증명, 사용자 및 히스토리 포함). 실험실 또는 심각한 비상 상황에서만 사용하십시오.

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

  • ✓ 엄격한 HTTPS 암호화: Cloudflare 엣지에서 n8n.portelcore.com로 직접 라우팅되는 엔드투엔드 암호화 트래픽.
  • ✓ 관계형 지속성: 자동화된 건강 검사로 검증된 PostgreSQL 16 데이터베이스 엔진.
  • ✓ 격리된 네트워크 보안: 공공 네트워크에 호스트 포트가 열려 있지 않으며, 내부 라우팅은 Docker의 닫힌 가상 브리지로 전달됩니다.
  • ✓ 선언형 표준: 시크릿이 고정되지 않은 IaC 파일 (docker-compose.yml 및 .env)과 제어된 중지 정책이 통합되어 있습니다.