【AI工作流搭建】—— n8n 自部署完全指南：从 Docker 安装到第一个自动化工作流

n8n 自部署完全指南：从 Docker 安装到第一个自动化工作流

一句话说清楚：n8n 是一个开源的工作流自动化平台，可以理解为"可以自己部署的 Zapier"，但它比 Zapier 灵活太多------400+ 集成、原生 AI 支持、完全掌控数据，而且免费。

为什么选 n8n 而不是 Zapier/Make？

用过 Zapier 的人都知道，免费版限制多到离谱，稍微复杂一点的工作流就得掏钱。n8n 不一样------自部署版完全免费，功能不打折扣。我们团队之前用 Make（原 Integromat），一个月账单能到 $200，迁移到 n8n 之后，服务器成本不到$ 10。

说直白点，n8n 适合这几类人：

想自动化但不想为每个 task 付费的技术团队
有数据合规要求、不能把数据送到第三方的公司
需要深度定制工作流逻辑的开发者
想用 AI 做自动化的（n8n 原生支持 LangChain/OpenAI 集成）

维度	n8n（自部署）	Zapier	Make
费用	免费（服务器成本）	$20+/月起	$9+/月起
数据主权	完全自控	云端	云端
集成数量	400+	7000+	2000+
自定义代码	JS/Python 节点	有限	有限
AI 集成	原生 LangChain	需第三方	需第三方
学习曲线	中等	低	低-中

环境准备

本文以 Ubuntu 22.04 / Debian 12 为例，macOS 也可以跑，但生产环境建议 Linux。

组件	最低要求	推荐配置	备注
Docker	20.10+	最新稳定版	必须
Docker Compose	V2	最新稳定版	生产环境推荐
内存	1GB	2GB+	AI 工作流需要更多
磁盘	10GB	20GB+	取决于工作流数量
端口	5678	可自定义	n8n 默认端口

先确认 Docker 已经装好：

bash 复制代码

docker --version
docker compose version

没装的话，Ubuntu 一条命令搞定：

bash 复制代码

curl -fsSL https://get.docker.com | sh

快速上手：5 分钟跑起来

想最快看到效果？两行命令就行：

bash 复制代码

docker volume create n8n_data
docker run -it --rm --name n8n -p 5678:5678 -v n8n_data:/home/node/.n8n docker.n8n.io/n8nio/n8n

打开浏览器访问 http://localhost:5678，注册管理员账号，就能开始玩了。

⚠️ 注意：这种方式用的是 SQLite，数据存在 n8n_data 这个 Docker volume 里。个人玩玩完全够用，但生产环境别这么搞。

✅ 成功标志：

浏览器能打开 n8n 界面
能正常注册并登录
点 "Execute workflow" 不报错

生产部署：Docker Compose + PostgreSQL

坑就坑在这里。很多人直接用上面的 docker run 跑在服务器上，结果重启一次数据全没了，或者并发一高就卡死。生产环境必须用 PostgreSQL + Docker Compose。

docker-compose.yml

yaml 复制代码

version: "3.8"

services:
  postgres:
    image: postgres:15
    container_name: n8n-postgres
    restart: always
    environment:
      POSTGRES_USER: n8n
      POSTGRES_PASSWORD: your_strong_password_here  # ⚠️ 改成你自己的
      POSTGRES_DB: n8n
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U n8n"]
      interval: 10s
      timeout: 5s
      retries: 5

  n8n:
    image: docker.n8n.io/n8nio/n8n:latest
    container_name: n8n
    restart: always
    depends_on:
      postgres:
        condition: service_healthy
    ports:
      - "5678:5678"
    environment:
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_PORT=5432
      - DB_POSTGRESDB_DATABASE=n8n
      - DB_POSTGRESDB_USER=n8n
      - DB_POSTGRESDB_PASSWORD=your_strong_password_here  # ⚠️ 和上面保持一致
      - GENERIC_TIMEZONE=Asia/Shanghai
      - TZ=Asia/Shanghai
      - N8N_ENCRYPTION_KEY=your_random_encryption_key  # ⚠️ 生成一个随机字符串
      - N8N_HOST=your-domain.com  # ⚠️ 改成你的域名或公网 IP
      - N8N_PORT=5678
      - N8N_PROTOCOL=https  # 生产环境用 https
      - WEBHOOK_URL=https://your-domain.com/  # ⚠️ Webhook 回调地址
    volumes:
      - n8n_data:/home/node/.n8n

volumes:
  postgres_data:
  n8n_data:

启动

bash 复制代码

# 启动
docker compose up -d

# 查看日志
docker compose logs -f n8n

# 确认两个容器都在运行
docker compose ps

🔴 重点：N8N_ENCRYPTION_KEY 一定要自己生成一个随机值，别偷懒留空。这个 key 用来加密你存在 n8n 里的所有凭据（API Key、OAuth Token 之类的）。丢了这个 key，你的凭据就全废了。

生成随机 key：

bash 复制代码

openssl rand -hex 32

把这个输出贴到 N8N_ENCRYPTION_KEY 里就行。

本章小结

配置项	必须改	说明
`POSTGRES_PASSWORD`	是	数据库密码
`DB_POSTGRESDB_PASSWORD`	是	和上面一致
`N8N_ENCRYPTION_KEY`	是	凭据加密 key
`N8N_HOST`	是	你的域名或 IP
`WEBHOOK_URL`	是	Webhook 回调地址
`N8N_PROTOCOL`	生产环境必须	设为 `https`
`GENERIC_TIMEZONE`	建议改	你所在的时区

反向代理配置（Nginx）

n8n 跑起来之后，生产环境一般不会直接暴露 5678 端口。用 Nginx 做反向代理 + SSL 是标准做法。

nginx 复制代码

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

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:5678;
        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;

        # WebSocket 支持（n8n 需要）
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

⚠️ 注意：WebSocket 那两行配置别漏了，不然 n8n 的前端会一直断连重连，体验极差。

第一个工作流：Webhook + HTTP Request

光部署没用，得跑通一个工作流才算真正上手。我们来做一个最实用的：接收 Webhook 请求 → 调用外部 API → 返回结果。

Step 1：创建 Webhook 触发器

打开 n8n 界面，点 "Create Workflow"
搜索 "Webhook" 节点，拖进来
HTTP Method 选 GET 或 POST
Path 填 test-hook
点 "Listen for Test Event"

这时候 n8n 会给你一个测试 URL，类似：

复制代码

http://localhost:5678/webhook-test/test-hook

Step 2：添加 HTTP Request 节点

从 Webhook 节点连线到一个新的 "HTTP Request" 节点
URL 填一个公开 API，比如 https://httpbin.org/get
Method 选 GET

Step 3：添加 Respond to Webhook 节点

从 HTTP Request 连线到 "Respond to Webhook" 节点
Response Body 里用表达式引用上游数据：{``{ $json }}

Step 4：测试

用 curl 触发：

bash 复制代码

# GET 请求
curl --request GET http://localhost:5678/webhook-test/test-hook

# POST 请求（带数据）
curl --request POST http://localhost:5678/webhook-test/test-hook \
  --header 'Content-Type: application/json' \
  --data '{"name": "test", "value": 42}'

✅ 成功标志：curl 返回的 JSON 里包含 httpbin 的响应数据。

激活工作流之后，测试 URL 会变成正式 URL（去掉 -test）：

复制代码

http://localhost:5678/webhook/test-hook

数据处理：表达式 vs Code 节点

n8n 处理数据有两种方式，选哪个取决于复杂度。

表达式（Expressions）

简单的数据提取、格式化，用表达式就够了。语法是 {``{ }} 包裹的 JavaScript：

复制代码

{{ $json.data.name }}          // 取嵌套字段
{{ $json.items.length }}       // 数组长度
{{ $now.format('yyyy-MM-dd') }} // 当前日期

$json 是当前节点的输入数据，$now 是当前时间，这两个是最常用的内置变量。

Code 节点

需要循环、条件判断、复杂数据转换的时候，上 Code 节点。支持 JavaScript 和 Python：

javascript 复制代码

// Code 节点示例：过滤并转换数据
const items = $input.all();
const filtered = items.filter(item => item.json.status === 'active');
return filtered.map(item => ({
  json: {
    id: item.json.id,
    displayName: `${item.json.firstName} ${item.json.lastName}`,
    processedAt: new Date().toISOString()
  }
}));

🔴 重点：Code 节点必须返回一个数组，每个元素是 { json: {...} } 格式。这是 n8n 的数据模型，搞错了节点会报错。

什么时候用哪个？

场景	用什么	示例
取单个字段	表达式	{``{ $json.email }}
简单格式化	表达式	{``{ $json.name.toUpperCase() }}
数据过滤/转换	Code 节点	过滤、映射、聚合
调用外部库	Code 节点	加密、解析特殊格式
条件分支	If 节点	不需要写代码

AI 工作流：让 n8n 变成 AI Agent

这是 n8n 最让我兴奋的功能。它原生集成了 LangChain，可以拖拽式地构建 AI Agent。

基础 LLM Chain

最简单的用法：用户输入 → 调用 OpenAI → 返回结果。

添加 "Chat Trigger" 节点（提供聊天界面）
添加 "OpenAI Chat Model" 节点（配置你的 API Key）
添加 "AI Agent" 节点，把 Chat Model 连到它的 "AI Model" 输入

这就完了一个基础的聊天机器人。

带工具的 AI Agent

更实用的场景：AI 调用你的 API 获取数据，然后基于数据回答问题。

在上面的基础上，添加一个 "Call n8n Workflow Tool" 节点
这个 Tool 节点连接到另一个 n8n 工作流（比如查询数据库的工作流）
AI Agent 会自动决定什么时候调用这个 Tool

n8n 的 AI Agent 支持这些配置：

Description：告诉 AI 这个工具是干什么的
Max Iterations：防止 AI 无限循环
System Message：设定 AI 的行为准则
Batch Processing：处理大量数据时的批处理控制

OpenAI 限流处理

实际项目中，OpenAI 的 rate limit 是个大坑。n8n 的官方做法是用 "Loop Over Items" + "Wait" 节点做批处理：

复制代码

Loop Over Items (batchSize: 500)
  → OpenAI 节点
  → Wait (delay: 1 分钟)
  → 回到 Loop

别问我怎么知道的------我们之前没加 Wait 节点，批量处理 1000 条数据，直接被 OpenAI 限流了。

常见问题排查

问题 1：容器重启后数据丢失

原因：没挂载 volume，数据存在容器内部，容器销毁就没了。

解决方案 ：确保 docker-compose.yml 里有 volume 配置：

yaml 复制代码

volumes:
  - n8n_data:/home/node/.n8n

验证：docker volume ls | grep n8n，能看到 n8n_data。

问题 2：Webhook 调用返回 404

原因：工作流没有激活。测试 URL 和正式 URL 是两回事。

解决方案：

测试时用 webhook-test 路径，并且要点 "Listen for Test Event"
生产用 webhook 路径，并且要点右上角的 "Active" 开关

验证：检查 n8n 界面右上角，工作流状态应该是绿色的 "Active"。

问题 3：连不上 PostgreSQL

原因：Docker 网络隔离，n8n 容器找不到 postgres 容器。

解决方案：

确认两个容器在同一个 docker-compose.yml 里（自动在同一个网络）
DB_POSTGRESDB_HOST 写的是服务名 postgres，不是 localhost

验证：docker compose exec n8n ping postgres，能通就行。

问题 4：Webhook 回调地址不对

原因：WEBHOOK_URL 没设置，或者设成了 localhost。

解决方案：在环境变量里设置你的公网地址：

yaml 复制代码

- WEBHOOK_URL=https://n8n.your-domain.com/

验证：创建一个 Webhook 节点，看生成的 URL 是不是你的域名。

问题 5：凭据迁移后全部失效

原因：换了服务器但没迁移 N8N_ENCRYPTION_KEY。

解决方案：迁移时必须带上这个 key。如果丢了......说实话，只能重新配置所有凭据。

验证：检查旧服务器的 ~/.n8n/config 文件，里面有 encryption key。

升级 n8n

Docker Compose 升级非常简单：

bash 复制代码

# 拉取最新镜像
docker compose pull

# 停掉旧版本
docker compose down

# 启动新版本
docker compose up -d

⚠️ 注意：升级前建议先备份数据库和 n8n_data volume。虽然 n8n 的升级一般很平滑，但不怕一万就怕万一。

备份命令：

bash 复制代码

# 备份 PostgreSQL
docker compose exec postgres pg_dump -U n8n n8n > n8n_backup_$(date +%Y%m%d).sql

# 备份 n8n 数据
docker run --rm -v n8n_data:/data -v $(pwd):/backup alpine tar czf /backup/n8n_data_$(date +%Y%m%d).tar.gz /data

MCP Server 集成

n8n 还支持作为 MCP（Model Context Protocol）服务器，让外部 AI Agent 直接调用你的 n8n 工作流。这个功能比较新，但很适合构建复杂的 AI 系统。

python 复制代码

# 用 Google ADK 连接 n8n MCP Server
from google.adk.agents import Agent
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPServerParams

N8N_INSTANCE_URL = "https://your-n8n-domain.com"
N8N_MCP_TOKEN = "YOUR_N8N_MCP_TOKEN"

root_agent = Agent(
    model="gemini-2.5-pro",
    name="n8n_agent",
    instruction="Help users manage and execute workflows in n8n",
    tools=[
        McpToolset(
            connection_params=StreamableHTTPServerParams(
                url=f"{N8N_INSTANCE_URL}/mcp-server/http",
                headers={
                    "Authorization": f"Bearer {N8N_MCP_TOKEN}",
                },
            ),
        )
    ],
)

总结：你真正需要记住的 5 件事

n8n 自部署免费，但服务器要花钱------最低配的 VPS（1C1G）就能跑。
生产环境必须用 PostgreSQL + Docker Compose，别用 SQLite 对付。
N8N_ENCRYPTION_KEY 是命根子，丢了就等于丢了所有凭据。
WEBHOOK_URL 必须设对，不然第三方回调全废。
AI 集成是杀手级功能，但注意 OpenAI 的 rate limit。

验证清单

部署完成后逐项检查：

⭐ docker compose ps 显示 n8n 和 postgres 都在运行
浏览器能打开 n8n 界面并登录
创建一个简单工作流能正常执行
Webhook 节点能接收外部请求
凭据保存后重启容器不丢失
N8N_ENCRYPTION_KEY 已设置自定义值
WEBHOOK_URL 指向正确的公网地址
反向代理配置正确（如果使用）
数据库备份脚本已就位

参考资源

n8n 官方文档：https://docs.n8n.io/
n8n Docker 部署文档：https://docs.n8n.io/hosting/installation/docker/
n8n 环境变量配置：https://docs.n8n.io/hosting/configuration/environment-variables/
n8n GitHub 仓库：https://github.com/n8n-io/n8n
n8n 社区论坛：https://community.n8n.io/