【n8n教程】：自托管n8n配置完全指南

【n8n教程】：自托管n8n配置完全指南

什么是n8n配置？

n8n配置就像给一个应用设置"说明书"。通过配置，你可以告诉n8n：

• 使用什么数据库存储工作流和凭证
• 用户如何登录（邮件、密码等）
• 工作流如何运行（并发数、超时时间等）
• 如何处理敏感信息（加密、密钥等）

简单来说，配置就是用环境变量来定制n8n的行为。

---

环境变量基础

什么是环境变量？

环境变量是操作系统传递给应用程序的参数。比如：

DB_TYPE=postgresdb
DB_POSTGRESDB_HOST=localhost
DB_POSTGRESDB_PORT=5432

这三行告诉n8n："使用PostgreSQL数据库，地址是localhost，端口是5432"。

核心环境变量速查表

环境变量	说明	默认值	示例
DB_TYPE	数据库类型	sqlite	postgresdb / mysqldb
N8N_ENCRYPTION_KEY	加密密钥	自动生成	至少32个字符
N8N_HOST	访问地址	localhost	n8n.example.com
GENERIC_TIMEZONE	时区	America/New_York	Asia/Shanghai
N8N_LOG_LEVEL	日志级别	info	debug / warn / error
EXECUTIONS_TIMEOUT	执行超时(秒)	-1(无限)	3600

---

配置方法详解

方法1️⃣ : npm命令行设置

Linux/Mac (Bash):

export DB_TYPE=postgresdb
export N8N_HOST=localhost
npm start

Windows (CMD):

set DB_TYPE=postgresdb
set N8N_HOST=localhost
npm start

Windows (PowerShell):

$env:DB_TYPE="postgresdb"
$env:N8N_HOST="localhost"
npm start

方法2️⃣ : Docker参数传递

使用 -e 标志在启动时传递环境变量：

docker run -d \
  -e DB_TYPE=postgresdb \
  -e DB_POSTGRESDB_HOST=postgres \
  -e DB_POSTGRESDB_PASSWORD=yourpassword \
  -p 5678:5678 \
  n8nio/n8n

方法3️⃣ : Docker Compose文件（推荐）

创建 docker-compose.yml：

version: '3.8'

services:
  n8n:
    image: n8nio/n8n
    container_name: n8n
    ports:
      - "5678:5678"
    environment:
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_PORT=5432
      - DB_POSTGRESDB_DATABASE=n8n
      - DB_POSTGRESDB_USER=n8n_user
      - DB_POSTGRESDB_PASSWORD=secure_password_123
      - N8N_HOST=n8n.example.com
      - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}
      - GENERIC_TIMEZONE=Asia/Shanghai
    volumes:
      - n8n_data:/home/node/.n8n
    depends_on:
      - postgres
    networks:
      - n8n_network

  postgres:
    image: postgres:15
    container_name: postgres
    environment:
      - POSTGRES_USER=n8n_user
      - POSTGRES_PASSWORD=secure_password_123
      - POSTGRES_DB=n8n
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - n8n_network

volumes:
  n8n_data:
  postgres_data:

networks:
  n8n_network:
    driver: bridge

然后启动：

docker-compose up -d

方法4️⃣ : 使用文件存储敏感数据

不想在环境变量中暴露密码？使用 _FILE 后缀！

environment:
  - DB_POSTGRESDB_PASSWORD_FILE=/run/secrets/db_password
  - N8N_ENCRYPTION_KEY_FILE=/run/secrets/encryption_key

secrets:
  db_password:
    file: ./secrets/db_password.txt
  encryption_key:
    file: ./secrets/encryption_key.txt

n8n会自动从指定文件读取密钥。

---

数据库配置

SQLite（默认，适合开发）

environment:
  - DB_TYPE=sqlite
  - DB_SQLITE_DATABASE=database.sqlite
  - DB_SQLITE_POOL_SIZE=3

优点 ：开箱即用，无需额外设置 缺点：不适合生产环境，并发性能差

PostgreSQL（推荐生产环境）

完整的PostgreSQL配置示例：

environment:
  - DB_TYPE=postgresdb
  - DB_POSTGRESDB_HOST=postgres.example.com
  - DB_POSTGRESDB_PORT=5432
  - DB_POSTGRESDB_DATABASE=n8n_prod
  - DB_POSTGRESDB_USER=n8n_admin
  - DB_POSTGRESDB_PASSWORD=complex_password_here
  - DB_POSTGRESDB_SCHEMA=public
  - DB_POSTGRESDB_SSL_ENABLED=true
  - DB_POSTGRESDB_SSL_REJECT_UNAUTHORIZED=true
  - DB_POSTGRESDB_POOL_SIZE=20

SSL连接配置（如果数据库需要）：

environment:
  - DB_POSTGRESDB_SSL_CA_FILE=/certs/ca.pem
  - DB_POSTGRESDB_SSL_CERT_FILE=/certs/client-cert.pem
  - DB_POSTGRESDB_SSL_KEY_FILE=/certs/client-key.pem

MySQL（另一选择）

environment:
  - DB_TYPE=mysqldb
  - DB_MYSQLDB_HOST=mysql.example.com
  - DB_MYSQLDB_PORT=3306
  - DB_MYSQLDB_DATABASE=n8n
  - DB_MYSQLDB_USER=n8n_user
  - DB_MYSQLDB_PASSWORD=password123
  - DB_MYSQLDB_POOL_SIZE=10

快速迁移：SQLite → PostgreSQL

# 1. 备份SQLite数据
cp ~/.n8n/database.sqlite ./backup.sqlite

# 2. 停止n8n
docker-compose down

# 3. 在docker-compose.yml中改为PostgreSQL配置
# 4. 启动PostgreSQL并创建数据库
docker-compose up -d postgres

# 5. 创建n8n用户和数据库
docker exec postgres psql -U postgres -c "CREATE USER n8n_user WITH PASSWORD 'password';"
docker exec postgres psql -U postgres -c "CREATE DATABASE n8n OWNER n8n_user;"

# 6. 启动n8n（会自动创建表结构）
docker-compose up -d

---

用户管理设置

SMTP配置（邮件邀请）

用户邀请和密码重置需要邮件功能。配置SMTP：

environment:
  - N8N_EMAIL_MODE=smtp
  - N8N_SMTP_HOST=smtp.gmail.com
  - N8N_SMTP_PORT=587
  - N8N_SMTP_USER=your-email@gmail.com
  - N8N_SMTP_PASS=your_app_password
  - N8N_SMTP_SENDER=n8n <no-reply@example.com>
  - N8N_SMTP_SSL=false
  - N8N_SMTP_STARTTLS=true

🔐 Pro Tip: 使用Gmail应用专用密码，不要用主密码！

首次设置流程

1. 启动n8n后 ，访问 http://localhost:5678
2. 创建Owner账户：输入邮箱和密码（密码至少8字符，需大写+数字）
3. 邀请用户：左下角用户菜单 → Settings → Users → Invite
4. 用户收到邮件，点击链接加入

SSO集成（高级）

SAML配置：

environment:
  - N8N_SSO_SAML_LOGIN_ENABLED=true
  - N8N_SSO_SAML_LOGIN_LABEL=Corporate SAML

OIDC配置：

environment:
  - N8N_SSO_OIDC_LOGIN_ENABLED=true

LDAP配置：

environment:
  - N8N_SSO_LDAP_LOGIN_ENABLED=true
  - N8N_SSO_LDAP_LOGIN_LABEL=Company LDAP

---

Task Runners配置

什么是Task Runners？

Task Runners是独立的执行环境，用于运行Code节点中的JavaScript和Python代码。分为两种模式：

内部模式（开发用）

environment:
  - N8N_RUNNERS_ENABLED=true
  - N8N_RUNNERS_MODE=internal
  - N8N_RUNNERS_TASK_TIMEOUT=300

特点：简单易用，但n8n进程和运行器在同一进程，不推荐生产。

外部模式（生产推荐）

需要运行 n8nio/runners 容器：

version: '3.8'

services:
  n8n:
    image: n8nio/n8n
    environment:
      - N8N_RUNNERS_ENABLED=true
      - N8N_RUNNERS_MODE=external
      - N8N_RUNNERS_AUTH_TOKEN=your_secure_token_here
      - N8N_RUNNERS_BROKER_LISTEN_ADDRESS=0.0.0.0
      - N8N_RUNNERS_BROKER_PORT=5679
    ports:
      - "5678:5678"

  runners:
    image: n8nio/runners:latest  # 版本必须和n8n相同
    environment:
      - N8N_RUNNERS_AUTH_TOKEN=your_secure_token_here
      - N8N_RUNNERS_TASK_BROKER_URI=n8n:5679
      - N8N_RUNNERS_AUTO_SHUTDOWN_TIMEOUT=15
    depends_on:
      - n8n

---

其他重要配置

并发执行限制

environment:
  - N8N_CONCURRENCY_PRODUCTION_LIMIT=5      # 生产执行最多5个并发
  - N8N_CONCURRENCY_EVALUATION_LIMIT=10     # 测试执行最多10个并发
  - EXECUTIONS_TIMEOUT=3600                 # 单个工作流最多运行1小时

日志配置

environment:
  - N8N_LOG_LEVEL=info                       # info/debug/warn/error
  - N8N_LOG_OUTPUT=console,file             # 输出到控制台和文件
  - N8N_LOG_FILE_LOCATION=logs/n8n.log      # 日志文件位置
  - N8N_LOG_FILE_SIZE_MAX=16                # 单个日志最大16MB

监控和指标（Prometheus）

environment:
  - N8N_METRICS=true
  - N8N_METRICS_PREFIX=n8n_
  - N8N_METRICS_INCLUDE_DEFAULT_METRICS=true
  - N8N_METRICS_INCLUDE_API_ENDPOINTS=true

访问 http://localhost:5678/metrics 查看Prometheus指标。

加密和安全

environment:
  - N8N_ENCRYPTION_KEY=your_very_long_random_key_at_least_32_chars
  - N8N_SECURE_COOKIE=true
  - N8N_SAMESITE_COOKIE=strict
  - N8N_USER_MANAGEMENT_JWT_SECRET=another_long_random_secret

⚠️ 重要：生成强随机密钥：

openssl rand -base64 32

---

实操案例：完整工作流

场景：定时数据采集和邮件通知

这个工作流会：

1. ⏰ 每天早上9点运行
2. 📊 从API获取数据
3. 📈 处理和转换数据
4. 📧 发送邮件报告

Docker Compose完整配置

version: '3.8'

services:
  n8n:
    image: n8nio/n8n:latest
    container_name: n8n-app
    restart: unless-stopped
    ports:
      - "5678:5678"
    environment:
      # 数据库配置
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_PORT=5432
      - DB_POSTGRESDB_DATABASE=n8n
      - DB_POSTGRESDB_USER=n8n_user
      - DB_POSTGRESDB_PASSWORD=${DB_PASSWORD}
      
      # 访问配置
      - N8N_HOST=${N8N_HOST:-localhost}
      - WEBHOOK_TUNNEL_URL=${WEBHOOK_URL:-http://localhost:5678}
      
      # 安全配置
      - N8N_ENCRYPTION_KEY=${ENCRYPTION_KEY}
      - N8N_BASIC_AUTH_ACTIVE=true
      - N8N_BASIC_AUTH_USER=admin
      - N8N_BASIC_AUTH_PASSWORD=${ADMIN_PASSWORD}
      
      # 时区和日志
      - GENERIC_TIMEZONE=Asia/Shanghai
      - N8N_LOG_LEVEL=info
      
      # 并发和超时
      - N8N_CONCURRENCY_PRODUCTION_LIMIT=5
      - EXECUTIONS_TIMEOUT=3600
      
      # SMTP邮件配置
      - N8N_EMAIL_MODE=smtp
      - N8N_SMTP_HOST=${SMTP_HOST}
      - N8N_SMTP_PORT=${SMTP_PORT}
      - N8N_SMTP_USER=${SMTP_USER}
      - N8N_SMTP_PASS=${SMTP_PASSWORD}
      - N8N_SMTP_SENDER=${SMTP_SENDER}
    
    volumes:
      - n8n_data:/home/node/.n8n
      - ./workflows:/home/node/workflows
    
    depends_on:
      - postgres
    
    networks:
      - n8n_network
    
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:5678/api/v1/health"]
      interval: 30s
      timeout: 10s
      retries: 3

  postgres:
    image: postgres:15-alpine
    container_name: postgres-db
    restart: unless-stopped
    environment:
      - POSTGRES_USER=n8n_user
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=n8n
    
    volumes:
      - postgres_data:/var/lib/postgresql/data
    
    networks:
      - n8n_network
    
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U n8n_user"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  n8n_data:
  postgres_data:

networks:
  n8n_network:
    driver: bridge

.env文件

创建 .env 文件（保存敏感信息）：

# 数据库
DB_PASSWORD=your_secure_db_password_123

# n8n访问
N8N_HOST=n8n.example.com
WEBHOOK_URL=https://n8n.example.com

# 安全密钥（使用 openssl rand -base64 32 生成）
ENCRYPTION_KEY=your_very_long_encryption_key_here_minimum_32_chars
ADMIN_PASSWORD=your_secure_admin_password

# SMTP邮件配置
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASSWORD=your_app_specific_password
SMTP_SENDER=n8n <no-reply@example.com>

启动命令

# 1. 复制.env文件
cp .env.example .env
# 然后编辑.env填入你的实际值

# 2. 启动所有服务
docker-compose up -d

# 3. 查看日志
docker-compose logs -f n8n

# 4. 验证健康状态
docker-compose ps

# 5. 停止服务
docker-compose down

完整的n8n工作流JSON代码

{
  "name": "Daily Data Collection & Email Report",
  "nodes": [
    {
      "parameters": {
        "interval": [
          9
        ],
        "triggerAtHour": 9
      },
      "id": "schedule-trigger",
      "name": "Schedule Trigger",
      "type": "n8n-nodes-base.scheduleTrigger",
      "typeVersion": 1,
      "position": [
        250,
        300
      ]
    },
    {
      "parameters": {
        "url": "https://jsonplaceholder.typicode.com/posts",
        "method": "GET",
        "responseFormat": "json"
      },
      "id": "fetch-data",
      "name": "Fetch API Data",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.2,
      "position": [
        450,
        300
      ]
    },
    {
      "parameters": {
        "mode": "runOnceForAllItems",
        "jsCode": "// 处理获取的数据\nconst items = $input.getAll();\nconst data = items[0].json;\n\n// 统计和聚合\nconst summary = {\n  totalPosts: data.length,\n  sampleData: data.slice(0, 5),\n  timestamp: new Date().toISOString()\n};\n\nreturn summary;"
      },
      "id": "process-data",
      "name": "Process Data",
      "type": "n8n-nodes-base.code",
      "typeVersion": 2,
      "position": [
        650,
        300
      ]
    },
    {
      "parameters": {
        "fromEmail": "no-reply@example.com",
        "toEmail": "admin@example.com",
        "subject": "Daily Data Report - {{$json.timestamp}}",
        "emailType": "html",
        "htmlMessage": "<h2>Daily Data Collection Report</h2>\n<p><strong>Generated:</strong> {{$json.timestamp}}</p>\n<p><strong>Total Records:</strong> {{$json.totalPosts}}</p>\n<h3>Sample Data:</h3>\n<pre>{{JSON.stringify($json.sampleData, null, 2)}}</pre>"
      },
      "id": "send-email",
      "name": "Send Email",
      "type": "n8n-nodes-base.sendEmail",
      "typeVersion": 1,
      "position": [
        850,
        300
      ]
    },
    {
      "parameters": {
        "mode": "runOnceForAllItems",
        "jsCode": "// 记录日志\nconst message = `Workflow executed successfully at ${new Date().toISOString()}`;\nconsole.log(message);\n\nreturn { success: true, message };"
      },
      "id": "log-completion",
      "name": "Log Completion",
      "type": "n8n-nodes-base.code",
      "typeVersion": 2,
      "position": [
        1050,
        300
      ]
    }
  ],
  "connections": {
    "schedule-trigger": {
      "main": [
        [
          {
            "node": "fetch-data",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "fetch-data": {
      "main": [
        [
          {
            "node": "process-data",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "process-data": {
      "main": [
        [
          {
            "node": "send-email",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "send-email": {
      "main": [
        [
          {
            "node": "log-completion",
            "type": "main",
            "index": 0
          }
        ]
      ]
    }
  },
  "active": true,
  "settings": {
    "executionOrder": "v1"
  }
}

如何导入这个工作流

1. 在n8n中，点击 Create Workflow 或打开现有工作流
2. 点击 Menu (≡) → Open
3. 选择 Import from file 或 Import from URL
4. 上传JSON文件
5. 配置SMTP凭证并激活工作流

---

常见问题排查

问题	解决方案
无法连接数据库	检查 DB_POSTGRESDB_HOST、端口、密码
邮件无法发送	验证SMTP配置，检查防火墙和应用密码
工作流执行超时	增加 EXECUTIONS_TIMEOUT 值
权限错误	检查Docker卷权限，运行 chmod 755 -R ./data
内存不足	减少 N8N_RUNNERS_MAX_CONCURRENCY 或增加服务器内存

---

• 官方文档
• n8n系列教程