架构手册:在 Portelcore 上安全部署 n8n
通过 Docker Compose 部署 n8n 的技术指南,使用持久化关系型 PostgreSQL 数据库和 Cloudflare Tunnels 实现零信任路由
本指南详细说明了 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 服务器虚拟机。
- 容器编排: 使用 Docker 和 Docker Compose 确保不可变、可移植且易于审计的环境。
- 关系型数据库: 将默认存储(SQLite)迁移至 PostgreSQL 16。此决策可防止高并发下的写入阻塞,并为未来的横向扩展(通过额外工作者模式 Queue)奠定基础。
- 边界安全(零信任):部署 Cloudflare Tunnels(
cloudflared)。- 主要优势:Ubuntu 主机不向互联网暴露任何入站端口(无论是
80、443还是5678)。隧道容器与 Cloudflare Edge 建立一条安全加密的出站连接,保护本地网络免受恶意扫描,并将 SSL(HTTPS)证书委托给 Edge。
- 主要优势:Ubuntu 主机不向互联网暴露任何入站端口(无论是
- 基础设施即代码(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 apply2.2 Docker引擎依赖项安装
Sección titulada «2.2 Instalación de Dependencias del Motor Docker»确保安装了更新的引擎及其官方编排库:
# 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)。 - 复制
TUNNEL_TOKEN(由 Cloudflare 提供的长字母数字文本块,用于对容器进行身份验证)。 - 配置公共路径(Public Hostname):
- 公共域名:
n8n.portelcore.com - 服务类型:
HTTP - 内部 URL(目标):
n8n:5678(注:使用由 Docker Compose 虚拟网络提供的内部 DNS 解析)。
- 公共域名:
我们的全部基础设施都井井有条地存放在目录 ~/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: bridge要首次在后台启动所有声明式的基础设施(或在修改文件 .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_tunnel[!CAUTION]\n破坏性操作:以下命令会永久删除主机上的所有容器和本地卷(同时清除 n8n 的凭据、用户和工作流历史)。仅在实验室或严重故障恢复时使用。
cd ~/n8n-docker# Detiene el stack eliminando los volúmenes asociadosdocker compose down -v
# Reconstruye el entorno desde cerodocker compose up -d- ✓ 严格 HTTPS 加密:端到端加密流量通过 Cloudflare Edge 原生路由至
n8n.portelcore.com。 - ✓ 关系型持久化:通过自动化健康检查验证的PostgreSQL 16数据库引擎。
- ✓ 隔离网络安全性:主机在公共网络上无开放端口,通过Docker封闭虚拟桥接进行内部路由。
- ✓ 声明式标准:IaC 文件(
docker-compose.yml和.env)不含硬编码密钥,并集成了受控停止策略。

