从部署到AI Agent：n8n工作流编排实战指南

前阵子有朋友问我：现在Dify、FastGPT、扣子这些AI平台一个比一个火，为什么还要折腾n8n这种“老牌自动化工具”？我的回答是：你把n8n理解成一条总装流水线就明白了——大模型只是其中一个工位，前后还能挂上你们公司的订单库、企业微信、邮件、数据库。这篇文章就是一篇纯入门练习笔记，我把n8n从部署、接大模型API、搭AI Agent，到Webhook落地和企业部署的关键点都过了一遍，适合想用n8n把AI能力接到真实业务里的开发者、测试、运维，以及对可视化编排好奇的产品朋友。

1. 先说清楚：n8n到底是做什么的，为什么AI时代反而更火了

1.1 从“开源Zapier”到“AI编排器”

n8n是一款开源的自动化工作流编排工具，核心玩法是拖拽节点、连线、配参数，就能在不同系统之间搬运和处理数据。它最早的定位是“一个能私有化部署的Zapier”，把Gmail、Slack、数据库、HTTP API之类的东西连接起来。但这两年AI浪潮起来之后，n8n的热度反而更高了，原因很简单：大模型成了可以编排的对象，AI Agent也能作为一个节点放进流程里。

在n8n里，一个工作流（Workflow）就是一张画布。画布上有触发器（Trigger）负责启动流程，有动作节点（Action Node）负责具体干活，节点之间用连线传递数据。数据流本质上就是一组JSON，从一个节点流向下一个节点。你不需要写一大堆胶水代码，也不需要自己去维护队列、回调、重试这些基础设施，n8n把底层的执行逻辑帮你管好了。

1.2 n8n 和 Dify、FastGPT、扣子的真实区别

很多人一开口就问“n8n和Dify哪个好”，其实这俩不是一个赛道的东西。我整理了一张对比表，方便你判断：

注意，这个表格只代表“侧重”，不代表谁不能做到另一件事。Dify也有工作流，n8n也能做知识库，但各自的舒服区完全不同。n8n最舒服的地方在于：它不是为AI而生的，它是一个通用的流程引擎，AI只是它调度的一个能力。

1.3 什么时候选择n8n

我的判断标准是这样：如果你的需求是“我要做一个AI应用，把RAG、Agent、模型管理这些集成起来”，那Dify这类平台效率更高；但如果你的需求是“我的业务有一堆乱七八糟的系统：Excel表、老接口、飞书机器人、MQ队列，现在想把AI模型插进这个流程里”，那n8n就是更顺手的工具。

还有一个很现实的因素：n8n可以私有化部署，数据和流程都在自己手里，很多公司在这点上比较看重。当然，n8n的许可从2024年起从Apache 2.0改成了fair-code/可持续使用许可，个人学习和实验没问题，如果要在商业环境里大规模使用，建议先读一遍官方许可说明。

2. 启动你的第一个n8n实例：部署方式与界面认知

2.1 用Docker Compose一次拉起整套环境

n8n单机演示最快的方式是直接跑一个容器，但既然你要练习，我建议一步到位用Docker Compose把n8n、PostgreSQL、Redis都拉起来。这样后面做并发测试、队列模式的时候不用重新折腾。

先创建一个目录，比如 n8n-practice，里面放一个 docker-compose.yml：

yaml复制services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: n8n
      POSTGRES_PASSWORD: n8npass
      POSTGRES_DB: n8n
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U n8n"]
      interval: 5s
      timeout: 5s
      retries: 10

  redis:
    image: redis:7-alpine
    volumes:
      - redisdata:/data

  n8n:
    image: docker.n8n.io/n8nio/n8n
    ports:
      - "5678:5678"
    environment:
      - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}
      - N8N_SECURE_COOKIE=false
      - GENERIC_TIMEZONE=Asia/Shanghai
      - TZ=Asia/Shanghai
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_PORT=5432
      - DB_POSTGRESDB_DATABASE=n8n
      - DB_POSTGRESDB_USER=n8n
      - DB_POSTGRESDB_PASSWORD=n8npass
    volumes:
      - n8ndata:/home/node/.n8n
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_started

volumes:
  pgdata:
  redisdata:
  n8ndata:

启动前，在同一个目录下创建一个 .env 文件，写入一个固定的加密密钥：

code复制N8N_ENCRYPTION_KEY=please-change-me-to-a-long-random-string

然后执行 docker compose up -d。等容器起来之后，浏览器打开 http://localhost:5678，第一次访问会让你创建一个管理员账号。

提示：N8N_ENCRYPTION_KEY 是用于加密你保存的所有Credentials（连接凭据）的密钥，务必要显式设置并妥善保存。如果这个密钥在容器重启时变化，之前保存的API Key会全部无法解密，这个坑我在第4章会细说。

2.2 初始化账号和三个必改参数

创建完管理员账号，我建议你先不要急着拖节点，先把三个东西确认掉：

1. 时区。右上角头像 → Settings → Workflow，把Timezone改成 Asia/Shanghai。不然你后面做定时任务，触发时间全是UTC偏移，看着难受。
2. 加密密钥是否生效。去容器里看一下环境变量：docker compose exec n8n env | grep N8N_ENCRYPTION。如果没输出，说明这个密钥没被读到，后面保存Credentials一定会踩坑。
3. 默认工作流命名规范。虽然现在只是练习，但最好从第一个工作流开始就起一个有意义的名字，比如“ai-agent-weather-demo”。n8n的工作流多了之后，没有命名规范会非常痛苦。

2.3 Workflow、Node、Connection到底指什么

我第一次看到n8n画布的时候，觉得它像一张电路图，这个类比其实挺准确的：

• 节点（Node） 是电路板上的元件，每个节点做一件事：接收一个输入JSON，处理后输出一个JSON。比如HTTP Request节点是发出网络请求，Code节点是运行一段自定义JS，AI Agent节点是让大模型做推理。
• 连线（Connection） 是导线，决定数据从哪个节点流向哪个节点。数据流不是你在界面上看到的“一行一行传”，而是上游节点的输出完整地传给下游节点。
• 工作流（Workflow） 是整块电路板。n8n底层会按你画好的连线，依次执行每个节点，并传递数据。

理解这一点非常重要，因为后面写表达式（比如 {{ $json.xxx }}）时，你脑子里的模型就是“我现在站在某个节点上，手里拿到的是上一个节点传过来的JSON”。每个节点执行完，右边面板都会显示这次执行的输入/输出数据，你在调试的时候应该时刻盯着这个面板看。

3. 第一次把大模型接进工作流：不写一行代码的API调用练习

3.1 先认识几个基础节点

这一章做一个小练习：手动触发一个工作流，调用大模型的HTTP API，把模型返回的内容显示出来。

需要的节点只有三个：

• Manual Trigger（手动触发）：画布上放一个起点，点右上角“Execute Workflow”时就是从这个节点开始执行。
• HTTP Request（请求）：用来调外部API，可以配置URL、Header、Body、认证方式。
• NoOp（空操作）：用来承接数据，方便你查看前一个节点的输出。其实Set节点也可以，但NoOp更纯粹。

3.2 用HTTP Request节点调用兼容OpenAI接口的模型

假设你现在没有可用的OpenAI账号，或者网络环境不允许直连，也没关系。现在很多国内模型都提供“OpenAI兼容接口”，你拿任意一个API Key，把Base URL替换掉就行。我这里用通用的写法演示。

把HTTP Request节点拖到画布上，连接到Manual Trigger后面，配置如下：

• Method：POST
• URL：https://api.openai.com/v1/chat/completions（或你的兼容接口地址）
• Authentication：选择 Generic Credential 或直接在 Header 里写 Authorization: Bearer sk-xxxx
• Body Content Type：JSON
• Body：填下面这个JSON：

json复制{
  "model": "gpt-4o-mini",
  "messages": [
    { "role": "system", "content": "你是一个乐于助人的助手。" },
    { "role": "user", "content": "用一句话解释什么是大模型。" }
  ],
  "temperature": 0.7
}

然后我习惯在HTTP Request后面再接一个NoOp节点，专门用来看结果。保存工作流，点击“Execute Workflow”，然后点HTTP Request节点，右边Output面板就能看到完整的响应结构。

响应大概长这样：

json复制{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "大模型是一种基于海量数据训练的深度学习系统，通过预测文本序列来生成自然语言回复。"
      }
    }
  ]
}

3.3 从$json到数据流：n8n表达式的入门理解

到这里，你已经把模型API接进来了。但“能调通”和“会用”之间还差一步：怎么把 choices[0].message.content 这块内容从一堆JSON里提出来，交给下一个环节用。

在n8n里，节点之间传数据靠的是表达式（Expression），写法是用双花括号包裹一段类似JavaScript的代码。最常见的写法是：

code复制{{ $json.choices[0].message.content }}

这里的 $json 表示“当前节点接收到的输入数据”。如果你想把HTTP Request的输出内容再加工一下，可以再加一个Set节点，新建一个字段叫 result，字段值填上面这个表达式。执行之后，Set节点的输出就变成 { "result": "大模型是一种..." }，这样后面的节点就只关心 $json.result 这一个字段，逻辑清楚多了。

3.4 我在这步踩过的三个坑

这个练习虽然简单，但我当时实打实踩了几个坑，列出来帮你避掉：

1. 401认证失败。最容易犯的错是把API Key直接放在了Body里，或者Header格式不对。正确姿势是在Header里写 Authorization: Bearer sk-xxx。建议先在Postman或Apifox里把请求完整跑通，再往n8n里填配置，这样能缩小排查范围。
2. JSON被转义。在HTTP Request节点里，Body有几种模式可选。如果你选“JSON”模式，直接填上方的JSON对象就好，不要在外面包一层字符串，也不要从其他地方复制带转义符的文本。n8n如果识别到body是字符串，请求发出去的时候content-type可能都会不对。
3. 取不到字段。表达式取不到值，八成是因为你把响应结构弄错了。比如响应体其实在 body.choices 里，但你以为在 $json.choices。这时候一定要先看节点Output面板，逐层展开，确认字段路径，再写表达式。

4. 进入AI Agent：把“调API”升级成“让模型自己决定调什么”

4.1 AI Agent节点的工作机制和它所在的LangChain节点组

用HTTP Request调大模型API，本质上是“你告诉模型做什么”。但Agent不一样，Agent是“你告诉模型目标，模型自己规划步骤、调用工具、最后给你答案”。

n8n在画布上提供了完整的LangChain节点组，包括：

• AI Agent节点：Agent本体，负责推理和决定下一步动作。
• Language Model节点：绑定大模型，比如OpenAI、Anthropic，或者兼容OpenAI接口的Ollama、DeepSeek等。
• Tool节点：给Agent准备的“手”，让Agent能调用外部能力，比如HTTP Request Tool、Code Tool、Workflow Tool。
• Memory节点：给Agent保存对话历史，实现多轮记忆。
• Vector Store节点：连接向量数据库，做语义检索。

AI Agent的工作机制简单理解就是：模型提出一个计划 → 调用工具 → 拿到工具结果 → 再判断下一步 → 直到认为问题解决了。而n8n让你用可视化连线把所有零件拼起来。

4.2 Credentials的配置逻辑，以及“重启后凭据失效”的惨痛经历

使用AI Agent节点之前，你需要先配置模型节点的Credentials。在n8n里，Credentials不是简单填在节点里的字段，而是一个全局复用资产，中文可以理解为“连接凭据”。它专门用来存Api Key、密码这类敏感信息，字段值会经过加密保存。

配置路径：选中节点 → Credential → 点击“Create New Credential” → 选择类型（比如OpenAI API）→ 填写API Key。保存后，其他节点在认证方式里选择“Predefined Credential Type”就能复用同一份凭据，不用重复填Key。

我当时在Docker里练习，遇到过一个特别恼火的问题：容器重启之后，所有节点上的Credential都报错“Unable to decrypt the data”。后来查了一圈才发现，是因为我第一版 docker-compose.yml 里没有设置 N8N_ENCRYPTION_KEY，每次重启容器，n8n都会随机生成一个新的加密密钥，旧凭据自然解不开了。

这个坑的教训就是：部署n8n的第一件事，就是把 N8N_ENCRYPTION_KEY 设成一个固定的随机字符串，而且以后扩容、迁移、加Worker节点，所有实例都必须用同一个密钥。

4.3 动手搭一个“天气查询+穿衣建议”Agent

下面这个案例我强烈建议你自己动手敲一遍：一个Agent，知道自己可以查天气，然后根据天气给穿衣建议。

需要的节点：

1. Manual Trigger
2. AI Agent节点（注意选择“AI Agent”类型，而不是“Basic LLM Chain”）
3. Language Model节点：选一个模型并配置Credentials，比如一个兼容OpenAI接口的模型。
4. Tool节点：选HTTP Request Tool。这个Tool的作用是让Agent在需要的时候自己发起请求去查天气。把Tool的URL配成一个天气API地址，Method设为GET。

画好连线后，关键步骤是把Tool节点连接到AI Agent节点上的“Tool”输入点。然后执行工作流，在AI Agent的“Prompt”输入框里写：

code复制今天北京天气怎么样？适合穿什么衣服？

Agent执行的时候，你不是直接让它调用API，而是它自己决定“我需要查天气”，于是触发Tool节点，拿到天气数据，再结合自己的知识生成穿衣建议。你把Output面板展开，能看到Agent内部调用了哪些工具，这一步是理解Agent机制最好的方式。

提示：如果执行报“Model not connected”之类的错误，检查一下Language Model节点有没有正确连到AI Agent节点的“Model”输入点。AI Agent节点不是自动读取默认模型的，它必须有一个显式连接的模型节点。

4.4 多AI协作的简单练习：串联两个Agent完成“总结+起标题”

多AI协作是我个人很喜欢的n8n场景。最简单但很实用的做法：用两个Agent串联，第一个负责总结长文本，第二个负责根据总结起标题。

工作流长这样：

code复制Manual Trigger → Agent1（总结） → Set（把Agent1的输出映射成Agent2的输入） → Agent2（起标题） → NoOp

Agent1的Prompt写“请将用户输入的这段文字总结为3个要点，输出简洁的markdown列表”，Agent2的Prompt写“你是一个新媒体编辑，根据上文总结生成3个适合公众号发布的标题，中文，不超过25字”。

这里要特别注意：Agent1的输出不能直接接到Agent2的输入上，因为Agent2的Prompt需要你把“上文”作为变量传进去。处理方法是在两个Agent之间加一个Set节点，设置一个字段比如 context，值填 {{ $json.output }}（具体路径以Agent1的输出结构为准），然后在Agent2的Prompt里用 {{ $json.context }} 引用。

为什么建议用“两个独立Agent串联”而不是用一个Agent同时做两件事？因为不同任务对模型的要求不一样——总结可能用便宜快速的模型就够，标题生成可能需要更强创意的模型。拆开之后，你可以给Agent1和Agent2配置不同的模型，成本控制更精细，出问题也更好排查。这也算是“多AI协作”的入门版本了。

5. 让工作流被外部调用：Webhook触发的完整实践

5.1 Test URL和Production URL的差异

画布上的Webhook节点是n8n给外部系统留的“门”。别人通过HTTP请求打到你的Webhook地址，工作流就被触发。这个非常实用，比如飞书机器人、企业微信、或者你公司的后端服务，都可以通过Webhook把消息丢给n8n处理。

Webhook节点在配置时，下面会出现两个地址：

• Test URL：测试地址，形如 http://localhost:5678/webhook-test/xxx
• Production URL：正式地址，形如 http://localhost:5678/webhook/xxx

我在这里踩过一个特别无语的坑：配置好Webhook后，怎么用curl访问Test URL都没反应。后来才发现，Webhook节点需要先点击“Listen for Test Event”按钮，处于监听状态时，Test URL才会临时生效。每次修改节点配置后，这个监听状态都可能要重新打开。Production URL则不用监听，工作流保存后它就常驻生效了。

5.2 一个能跑的完整链路：Webhook收消息→AI识别意图→机器人返回结果

下面这个链路是我练完所有基础节点后组装的一个“客服意图识别”Demo，完整覆盖了外部接入场景。

节点链路：

code复制Webhook Trigger（接收POST JSON）
  → AI Agent（判断用户想干什么）
    → Switch（按意图分流）
      → 分支1：调用订单查询API（HTTP Request）
      → 分支2：直接回复FAQ话术（NoOp + Set）
  → Respond to Webhook（把结果返回给调用方）

外部系统往Webhook地址发这个JSON：

json复制{
  "user": "张三",
  "message": "我的订单什么时候发货？"
}

Webhook节点把 message 字段传给AI Agent，Agent根据上下文判断出“用户是在查订单（order_status）”，然后Switch节点匹配到“order”分支，调用你自己的订单查询接口，最后通过Respond to Webhook节点把数据以JSON形式返回给请求方。

用curl模拟调用：

bash复制curl -X POST http://localhost:5678/webhook/xxx \
  -H "Content-Type: application/json" \
  -d '{"user":"张三","message":"我的订单什么时候发货？"}'

这个链路的价值在于：你不需要把业务逻辑硬编码在一个机器人代码里，n8n负责把“接收消息、理解意图、调用系统、返回结果”全部串起来。以后新增一个意图，只需要改Switch分支，或者加一个Agent节点，不用改整个流程。

5.3 n8n表达式里$json、$node、$('节点名')的区别

写复杂工作流时，表达式用得越来越多，这三个写法容易混淆，我直接给你区分：

简单判断：如果A节点直接连向B节点，在B的字段里就优先用 $json.xxx；如果整个画布绕了一圈，你想拿的是某个分支里固定节点的输出，就用 $node["节点名"].json.xxx。

6. 从练习到落地：部署、并发和企业级部署的几个关键思考

6.1 个人练习版和团队使用的差异

前面所有练习，本质上都是“单机单用户”模式。你在本地部署的n8n社区版里创建的账号是管理员，但这不等于团队版。n8n社区版是不支持多用户和角色权限管理的，也没有内置的SSO。如果团队要协作，需要买企业版license，或者自己想办法做用户隔离。

所以做技术选型时一定要提前评估：如果只是个人或小团队用，社区版完全足够；如果是公司级多团队使用，license成本、用户管理、审计这些都要提前纳入规划。

6.2 队列模式的部署思路：主实例、Worker、Redis和PostgreSQL

n8n单实例执行任务时，任务都在主进程里跑，简单但并发能力有限。企业级部署一般会拆成“主实例 + Worker”的队列模式，用Redis作为任务队列，用PostgreSQL存持久化数据。

关键配置就是在环境变量里打开队列模式：

code复制N8N_EXECUTIONS_MODE=queue
N8N_EXECUTIONS_QUEUE_TYPE=redis
N8N_REDIS_URL=redis://redis:6379

主实例负责调度和提供Web界面，Worker节点只负责执行工作流，可以开多个。这样大量耗时的AI请求不会把主实例的响应卡死。启动多个Worker时，有几点必须注意：

• 所有实例共享同一个PostgreSQL和Redis。
• 所有实例的 N8N_ENCRYPTION_KEY 必须完全一致，否则Worker拉取工作流后无法解密Credentials。
• 工作流执行数据会写进PostgreSQL，方便统一审计和重试。

6.3 我个人给初学者的工作流设计建议

最后说几个我从练习到落地阶段感觉特别有用的习惯：

1. 节点命名要看得懂。不要用默认的“HTTP Request”当名字，改成“查订单接口”，日志里一眼能看出来是哪个节点出了问题。
2. 先手动跑通，再挂触发器。任何工作流，先点上方的Execute Workflow手动执行，确认每个节点输出符合预期，再接Webhook或定时触发器。不要一上来就搞自动化，不然报错都不知道从哪查。
3. 敏感信息别直接写在字段里。能用Credential的地方就用Credential，不要在HTTP Request节点里把Authorization硬编码在Header配置中，密钥会跟着工作流导出而被泄露。
4. 工作流本身是最轻的备份单位。n8n的每个工作流都可以一键导出成JSON，这就是你的“基础设施即代码”。本地练习阶段可以不做备份，但一旦开始维护复杂流程，建议每次改动前导出一份JSON存档。
5. 先动手做一遍，再谈优化。网上关于n8n的中文教程其实不算多，官方文档虽然全，但面对新手还是太啰嗦。我的经验是：先照着这篇文章把“HTTP调用模型”和“AI Agent串联”两个练习跑通，再去看官方模板库里的案例，你会发现读模板的速度快很多，因为你已经知道节点和数据流是怎么回事了。

我在实际练习中还有一个体会：n8n真正锻炼人的地方不是“拖节点”这个动作，而是“把一个需求拆成输入、处理、判断、输出”的流程思维。这种思维放到任何工具上都是通用的。如果你已经把前面几个案例跑通了，下一步可以自己试着给它接个飞书机器人，或者加一个定时触发器，让这个Agent每天早上自动整理一份昨天的业务摘要发给你——能做到这一步，说明你已经从“了解n8n”进入到“用n8n解决问题”的阶段了。