n8n 本地部署指南

一、部署方式概览

部署方式	难度	适合场景	特点
Docker（推荐）	★★☆☆	快速测试、生产环境	隔离性好，配置简单
npm 安装	★★★☆	开发调试、定制需求	直接控制，便于调试
二进制包	★★☆☆	Windows用户、简单使用	开箱即用，无需安装依赖
Kubernetes	★★★★	企业级、高可用部署	可扩展性强，管理复杂

二、Docker 部署（推荐）

2.1 基础 Docker 部署

# 创建数据目录
mkdir -p ~/.n8n
chmod -R 777 ~/.n8n

# 拉取并运行最新版本
docker run -it --rm \
  --name n8n \
  -p 5678:5678 \
  -v ~/.n8n:/home/node/.n8n \
  n8nio/n8n

2.2 使用 Docker Compose（推荐用于生产）

# docker-compose.yml
version: '3.8'

services:
  n8n:
    image: n8nio/n8n
    container_name: n8n
    restart: unless-stopped
    ports:
      - "5678:5678"
      - "5679:5679"  # 如果需要Webhook端口
    environment:
      # 基础配置
      - N8N_PROTOCOL=http
      - N8N_HOST=localhost
      - N8N_PORT=5678
      
      # 安全配置（强烈建议设置）
      - N8N_SECURE_COOKIE=false  # 本地HTTP设为false，HTTPS设为true
      - N8N_USER_MANAGEMENT_JWT_SECRET=${JWT_SECRET:-请替换为强密码}
      - N8N_ENCRYPTION_KEY=${ENCRYPTION_KEY:-请替换为强密码}
      
      # 外部访问URL（重要！）
      - WEBHOOK_URL=http://localhost:5678
      - N8N_EDITOR_BASE_URL=http://localhost:5678
      
      # 数据库配置（默认SQLite，建议生产环境用PostgreSQL）
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_PORT=5432
      - DB_POSTGRESDB_DATABASE=n8n
      - DB_POSTGRESDB_USER=n8n
      - DB_POSTGRESDB_PASSWORD=${DB_PASSWORD:-请替换密码}
      
      # 邮件配置（用于密码重置等）
      - N8N_SMTP_HOST=smtp.gmail.com
      - N8N_SMTP_PORT=587
      - N8N_SMTP_USER=${SMTP_USER:-your-email@gmail.com}
      - N8N_SMTP_PASS=${SMTP_PASS:-your-app-password}
      - N8N_SMTP_SENDER=${SMTP_USER:-your-email@gmail.com}
      
      # 性能配置
      - EXECUTIONS_DATA_PRUNE=true
      - EXECUTIONS_DATA_MAX_AGE=168  # 执行日志保留7天（小时）
      - EXECUTIONS_DATA_PRUNE_MAX_COUNT=10000
      
      # 其他配置
      - GENERIC_TIMEZONE=Asia/Shanghai
      - N8N_METRICS=false  # 禁用指标收集
      - N8N_DIAGNOSTICS_ENABLED=false  # 禁用诊断数据
    volumes:
      - n8n_data:/home/node/.n8n
      - ./custom:/usr/local/lib/node_modules/n8n/dist/custom  # 自定义节点
    depends_on:
      - postgres
    networks:
      - n8n-network
    # 健康检查
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:5678/healthz"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

  postgres:
    image: postgres:15-alpine
    container_name: n8n-postgres
    restart: unless-stopped
    environment:
      - POSTGRES_USER=n8n
      - POSTGRES_PASSWORD=${DB_PASSWORD:-请替换密码}
      - POSTGRES_DB=n8n
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./init.sql:/docker-entrypoint-initdb.d/init.sql
    command:
      - "postgres"
      - "-c"
      - "max_connections=200"
      - "-c"
      - "shared_buffers=256MB"
      - "-c"
      - "work_mem=8MB"
    networks:
      - n8n-network
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U n8n"]
      interval: 30s
      timeout: 10s
      retries: 3

  # Redis缓存（可选，提升性能）
  redis:
    image: redis:7-alpine
    container_name: n8n-redis
    restart: unless-stopped
    command: redis-server --requirepass ${REDIS_PASSWORD:-请替换密码}
    volumes:
      - redis_data:/data
    networks:
      - n8n-network
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 30s
      timeout: 10s
      retries: 3

  # Nginx反向代理（可选，用于HTTPS）
  nginx:
    image: nginx:alpine
    container_name: n8n-nginx
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
      - ./ssl:/etc/nginx/ssl:ro
    depends_on:
      - n8n
    networks:
      - n8n-network

volumes:
  n8n_data:
  postgres_data:
  redis_data:

networks:
  n8n-network:
    driver: bridge

2.3 Nginx 配置文件

# nginx.conf
events {
    worker_connections 1024;
}

http {
    upstream n8n_backend {
        server n8n:5678;
        keepalive 32;
    }

    server {
        listen 80;
        server_name your-domain.com;
        
        # 重定向到HTTPS
        return 301 https://$server_name$request_uri;
    }

    server {
        listen 443 ssl http2;
        server_name your-domain.com;

        ssl_certificate /etc/nginx/ssl/fullchain.pem;
        ssl_certificate_key /etc/nginx/ssl/privkey.pem;
        
        # SSL优化配置
        ssl_protocols TLSv1.2 TLSv1.3;
        ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384;
        ssl_prefer_server_ciphers off;
        ssl_session_cache shared:SSL:10m;
        ssl_session_timeout 10m;

        # 安全头
        add_header X-Frame-Options DENY;
        add_header X-Content-Type-Options nosniff;
        add_header X-XSS-Protection "1; mode=block";
        add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

        # 上传大小限制
        client_max_body_size 50M;

        location / {
            proxy_pass http://n8n_backend;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection 'upgrade';
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
            
            # 超时设置
            proxy_connect_timeout 300s;
            proxy_send_timeout 300s;
            proxy_read_timeout 300s;
            
            # WebSocket支持
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "Upgrade";
        }

        # 健康检查端点
        location /healthz {
            access_log off;
            return 200 "healthy\n";
        }
    }
}

2.4 启动脚本

#!/bin/bash
# deploy-n8n.sh

set -e

# 配置环境变量
export JWT_SECRET=$(openssl rand -hex 32)
export ENCRYPTION_KEY=$(openssl rand -hex 32)
export DB_PASSWORD=$(openssl rand -hex 16)
export REDIS_PASSWORD=$(openssl rand -hex 16)

# 创建必要的目录
mkdir -p ./ssl ./custom

# 生成环境文件
cat > .env << EOF
JWT_SECRET=$JWT_SECRET
ENCRYPTION_KEY=$ENCRYPTION_KEY
DB_PASSWORD=$DB_PASSWORD
REDIS_PASSWORD=$REDIS_PASSWORD
# 邮件配置（根据实际情况修改）
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password
EOF

echo "✅ 环境变量已生成到 .env 文件"

# 检查Docker和Docker Compose
if ! command -v docker &> /dev/null; then
    echo "❌ Docker未安装"
    exit 1
fi

if ! command -v docker-compose &> /dev/null; then
    echo "❌ Docker Compose未安装"
    exit 1
fi

# 拉取镜像
echo "🔧 拉取Docker镜像..."
docker-compose pull

# 启动服务
echo "🚀 启动n8n服务..."
docker-compose up -d

echo ""
echo "=========================================="
echo "✅ n8n 部署完成！"
echo ""
echo "访问地址:"
echo "- 本地: http://localhost:5678"
echo "- 通过Nginx: https://your-domain.com"
echo ""
echo "数据库信息:"
echo "- 主机: postgres:5432"
echo "- 数据库: n8n"
echo "- 用户: n8n"
echo ""
echo "管理命令:"
echo "查看日志: docker-compose logs -f n8n"
echo "停止服务: docker-compose down"
echo "备份数据: docker-compose exec postgres pg_dump -U n8n n8n > backup.sql"
echo "=========================================="

三、npm 本地安装（开发环境）

3.1 安装步骤

# 1. 安装Node.js（版本>=16）
# 访问 https://nodejs.org 下载安装

# 2. 安装n8n
npm install n8n -g

# 3. 启动n8n
n8n start

# 或者使用自定义配置启动
n8n start \
  --tunnel \
  --port=5678 \
  --host=localhost \
  --webhook-url=http://localhost:5678

3.2 配置脚本

// ~/.n8n/config.js
module.exports = {
    // 基础配置
    host: 'localhost',
    port: 5678,
    protocol: 'http',
    
    // 数据库配置
    database: {
        type: 'postgres',
        host: 'localhost',
        port: 5432,
        username: 'n8n',
        password: 'your-password',
        database: 'n8n'
    },
    
    // 安全配置
    security: {
        jwtSecret: 'your-jwt-secret',
        encryptionKey: 'your-encryption-key'
    },
    
    // 邮件配置
    email: {
        smtp: {
            host: 'smtp.gmail.com',
            port: 587,
            secure: false,
            auth: {
                user: 'your-email@gmail.com',
                pass: 'your-app-password'
            }
        },
        sender: 'your-email@gmail.com'
    },
    
    // 外部访问URL
    externalHookFilesUrl: 'http://localhost:5678',
    
    // 执行配置
    executions: {
        // 保存执行数据
        saveDataOnSuccess: 'all',
        saveDataOnError: 'all',
        
        // 自动清理
        pruneData: true,
        pruneDataMaxAge: 168, // 保留7天
        pruneDataMaxCount: 10000
    },
    
    // 日志配置
    logs: {
        level: 'info',
        output: 'console'
    },
    
    // 性能优化
    queue: {
        bull: {
            redis: {
                host: 'localhost',
                port: 6379,
                password: 'your-redis-password'
            }
        }
    }
};

四、Windows 二进制包安装

4.1 安装步骤

1. 下载n8n

   • 访问 n8n Releases
   • 下载 n8n-x.x.x-win-x64.exe（最新版本）

2. 安装和运行

   # 创建安装目录
   mkdir C:\n8n
   cd C:\n8n
   
   # 下载并重命名
   # 从GitHub下载后，重命名为 n8n.exe
   
   # 第一次运行会生成配置文件
   .\n8n.exe
   
   # 配置启动参数
   .\n8n.exe start --port=5678 --host=0.0.0.0
   

3. 创建Windows服务（可选）

   # 使用NSSM创建服务
   # 1. 下载NSSM: https://nssm.cc/download
   # 2. 安装服务
   nssm install n8n "C:\n8n\n8n.exe" start
   nssm set n8n AppDirectory "C:\n8n"
   nssm set n8n AppParameters "start --port=5678 --host=0.0.0.0"
   nssm set n8n AppStdout "C:\n8n\log.txt"
   nssm set n8n AppStderr "C:\n8n\error.txt"
   
   # 3. 启动服务
   nssm start n8n
   

五、生产环境高级配置

5.1 数据库初始化脚本

-- init.sql
-- 创建扩展（如果需要）
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

-- 创建索引优化查询性能
CREATE INDEX IF NOT EXISTS idx_executions_created_at ON executions(created_at DESC);
CREATE INDEX IF NOT EXISTS idx_executions_status ON executions(status);
CREATE INDEX IF NOT EXISTS idx_workflow_entity_updated_at ON workflow_entity(updated_at DESC);

-- 设置表空间（可选）
-- TABLESPACE fast_space;

5.2 备份和恢复脚本

#!/bin/bash
# backup-n8n.sh

set -e

BACKUP_DIR="/backup/n8n"
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_FILE="$BACKUP_DIR/n8n_backup_$DATE.tar.gz"

# 创建备份目录
mkdir -p "$BACKUP_DIR"

echo "🔧 开始备份n8n..."

# 1. 备份数据库
echo "📦 备份PostgreSQL数据库..."
docker-compose exec -T postgres pg_dump -U n8n n8n > "$BACKUP_DIR/database_$DATE.sql"

# 2. 备份Redis数据（如果有）
if docker-compose ps | grep -q redis; then
    echo "📦 备份Redis数据..."
    docker-compose exec -T redis redis-cli --rdb /data/dump.rdb
    docker cp "$(docker-compose ps -q redis)":/data/dump.rdb "$BACKUP_DIR/redis_$DATE.rdb"
fi

# 3. 备份n8n配置文件和数据
echo "📦 备份n8n配置文件..."
tar -czf "$BACKUP_FILE" \
    ~/.n8n \
    docker-compose.yml \
    .env \
    "$BACKUP_DIR/database_$DATE.sql" \
    "$BACKUP_DIR/redis_$DATE.rdb" 2>/dev/null || true

# 清理临时文件
rm -f "$BACKUP_DIR/database_$DATE.sql" "$BACKUP_DIR/redis_$DATE.rdb"

# 保留最近7天的备份
find "$BACKUP_DIR" -name "n8n_backup_*.tar.gz" -mtime +7 -delete

echo "✅ 备份完成: $BACKUP_FILE"
echo "📊 备份大小: $(du -h "$BACKUP_FILE" | cut -f1)"

5.3 监控配置

# prometheus.yml 配置
scrape_configs:
  - job_name: 'n8n'
    static_configs:
      - targets: ['n8n:5678']
    metrics_path: '/metrics'
    
  - job_name: 'postgres'
    static_configs:
      - targets: ['postgres-exporter:9187']
      
  - job_name: 'redis'
    static_configs:
      - targets: ['redis-exporter:9121']

# docker-compose.monitoring.yml
version: '3.8'

services:
  prometheus:
    image: prom/prometheus:latest
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
      - prometheus_data:/prometheus
    ports:
      - "9090:9090"
    networks:
      - n8n-network

  grafana:
    image: grafana/grafana:latest
    volumes:
      - grafana_data:/var/lib/grafana
    ports:
      - "3000:3000"
    networks:
      - n8n-network

  node-exporter:
    image: prom/node-exporter:latest
    volumes:
      - /proc:/host/proc:ro
      - /sys:/host/sys:ro
      - /:/rootfs:ro
    command:
      - '--path.procfs=/host/proc'
      - '--path.rootfs=/rootfs'
      - '--path.sysfs=/host/sys'
      - '--collector.filesystem.mount-points-exclude=^/(sys|proc|dev|host|etc)($$|/)'
    networks:
      - n8n-network

  postgres-exporter:
    image: prometheuscommunity/postgres-exporter:latest
    environment:
      DATA_SOURCE_NAME: "postgresql://n8n:${DB_PASSWORD}@postgres:5432/n8n?sslmode=disable"
    networks:
      - n8n-network

  redis-exporter:
    image: oliver006/redis_exporter:latest
    environment:
      REDIS_ADDR: "redis://redis:6379"
      REDIS_PASSWORD: "${REDIS_PASSWORD}"
    networks:
      - n8n-network

六、故障排除和优化

6.1 常见问题解决

# 1. 端口被占用
# 检查端口占用
sudo lsof -i :5678
# 或者
netstat -tulpn | grep :5678

# 2. 数据库连接问题
# 检查PostgreSQL日志
docker-compose logs postgres

# 3. 内存不足
# 查看容器内存使用
docker stats

# 4. 权限问题
# 修复文件权限
sudo chown -R 1000:1000 ~/.n8n

# 5. 启动失败
# 查看详细日志
docker-compose logs --tail=100 n8n

6.2 性能优化建议

# docker-compose.override.yml（性能优化配置）
version: '3.8'

services:
  n8n:
    deploy:
      resources:
        limits:
          memory: 2G
          cpus: '2'
        reservations:
          memory: 1G
          cpus: '1'
    environment:
      # 增加执行线程
      - EXECUTIONS_PROCESS_MAIN_CONCURRENCY=2
      - EXECUTIONS_PROCESS_WORKER_CONCURRENCY=2
      
      # 启用队列处理
      - EXECUTIONS_MODE=queue
      
      # 调整超时设置
      - EXECUTIONS_TIMEOUT_MAX=3600
      - EXECUTIONS_TIMEOUT=300
      
      # 启用Gzip压缩
      - N8N_COMPRESSION=true

  postgres:
    deploy:
      resources:
        limits:
          memory: 1G
          cpus: '1'
    environment:
      - POSTGRES_SHARED_BUFFERS=256MB
      - POSTGRES_EFFECTIVE_CACHE_SIZE=512MB
      - POSTGRES_MAINTENANCE_WORK_MEM=64MB
      - POSTGRES_WORK_MEM=8MB

6.3 健康检查脚本

#!/bin/bash
# health-check.sh

check_url() {
    local url=$1
    local timeout=$2
    local status=$(curl -s -o /dev/null -w "%{http_code}" --max-time $timeout $url)
    
    if [ "$status" -eq 200 ] || [ "$status" -eq 302 ]; then
        echo "✅ $url - 正常 (状态码: $status)"
        return 0
    else
        echo "❌ $url - 异常 (状态码: $status)"
        return 1
    fi
}

echo "🩺 开始健康检查..."
echo "=============================="

# 检查n8n服务
check_url "http://localhost:5678/healthz" 10

# 检查数据库
if docker-compose exec -T postgres pg_isready -U n8n &> /dev/null; then
    echo "✅ PostgreSQL - 正常"
else
    echo "❌ PostgreSQL - 异常"
fi

# 检查Redis
if docker-compose exec -T redis redis-cli ping &> /dev/null; then
    echo "✅ Redis - 正常"
else
    echo "❌ Redis - 异常"
fi

# 检查磁盘空间
DISK_USAGE=$(df -h / | awk 'NR==2 {print $5}' | sed 's/%//')
if [ "$DISK_USAGE" -lt 90 ]; then
    echo "✅ 磁盘空间 - 正常 ($DISK_USAGE% 已使用)"
else
    echo "⚠️  磁盘空间 - 警告 ($DISK_USAGE% 已使用)"
fi

# 检查内存使用
MEM_FREE=$(free -m | awk 'NR==2 {print $4}')
if [ "$MEM_FREE" -gt 100 ]; then
    echo "✅ 内存 - 正常 (剩余: ${MEM_FREE}MB)"
else
    echo "⚠️  内存 - 警告 (剩余: ${MEM_FREE}MB)"
fi

echo "=============================="
echo "健康检查完成"

七、安全加固指南

7.1 安全配置

# docker-compose.security.yml
version: '3.8'

services:
  n8n:
    environment:
      # 强制HTTPS
      - N8N_PROTOCOL=https
      - N8N_SECURE_COOKIE=true
      
      # 启用用户管理
      - N8N_USER_MANAGEMENT_ENABLED=true
      - N8N_USER_MANAGEMENT_JWT_DURATION_HOURS=24
      
      # API限流
      - N8N_RATE_LIMITER_ENABLED=true
      - N8N_RATE_LIMITER_MAX=100
      - N8N_RATE_LIMITER_WINDOW=900  # 15分钟
      
      # CORS配置
      - N8N_CORS_ORIGIN=https://your-domain.com
      - N8N_CORS_CREDENTIALS=true
      
      # 禁用危险功能
      - N8N_DIAGNOSTICS_ENABLED=false
      - N8N_METRICS=false
      - N8N_PERSONALIZATION_ENABLED=false
      
      # 日志脱敏
      - N8N_LOG_MASK_DISABLE=false
      
      # Webhook认证
      - N8N_WEBHOOK_URL=https://your-domain.com
      - N8N_WEBHOOK_TEST_AWAIT_TIME=3000
      
      # SSH隧道禁用
      - N8N_TUNNEL_SUBDOMAIN_ENABLED=false

7.2 防火墙配置

#!/bin/bash
# firewall-setup.sh

# 只允许必要端口
sudo ufw default deny incoming
sudo ufw default allow outgoing

# 开放SSH端口
sudo ufw allow 22/tcp

# 开放n8n Web界面端口（仅限本地网络）
sudo ufw allow from 192.168.1.0/24 to any port 5678 proto tcp

# 开放HTTPS端口（如果使用Nginx）
sudo ufw allow 443/tcp

# 启用防火墙
sudo ufw --force enable
sudo ufw status verbose

八、更新和维护

8.1 更新脚本

#!/bin/bash
# update-n8n.sh

echo "🔄 开始更新n8n..."

# 备份当前配置
./backup-n8n.sh

# 停止服务
docker-compose down

# 拉取最新镜像
docker-compose pull

# 启动服务
docker-compose up -d

# 等待服务启动
sleep 30

# 运行数据库迁移（如果需要）
docker-compose exec n8n n8n update

# 检查服务状态
./health-check.sh

echo "✅ n8n更新完成"

九、总结

部署方案选择建议：

1. 开发测试环境：

   • 使用 Docker 单容器部署
   • 无需复杂配置
   • 快速启动

2. 中小型生产环境：

   • 使用 Docker Compose 多容器部署
   • 配置 PostgreSQL + Redis
   • 启用 Nginx 反向代理和 HTTPS

3. 大型企业环境：

   • 使用 Kubernetes 部署
   • 配置监控、日志、备份
   • 实现高可用和自动扩缩容

关键注意事项：

1. 安全第一：

   • 必须设置强密码的 JWT_SECRET 和 ENCRYPTION_KEY
   • 生产环境必须使用 HTTPS
   • 启用用户管理和权限控制

2. 数据持久化：

   • 数据库必须使用持久化存储
   • 定期备份数据
   • 监控磁盘空间

3. 性能监控：

   • 配置资源限制
   • 监控执行队列
   • 定期清理旧数据

4. 更新策略：

   • 定期更新到稳定版本
   • 更新前备份数据
   • 测试工作流兼容性

通过以上配置，你可以根据具体需求部署一个稳定、安全、高效的本地 n8n 实例。