n8n：可视化拖拽连接 1500+ 应用、内置 AI 节点的工作流自动化平台｜部署与使用全指南

项目仓库： https://github.com/n8n-io/n8n

许可模式：fair-code（社区版 Sustainable Use License + n8n Enterprise License，源码可见、可自托管，企业级特性需商业授权） · 主要语言：TypeScript / Node.js · 交付形态：Docker 镜像（自托管首选）、npm 包（自 n8n 3.0 起弃用新安装）、云端 SaaS · 默认端口 5678 · 默认数据库 SQLite，可切换 PostgreSQL · 官方文档：docs.n8n.io

非官方声明：n8n 是 n8n GmbH 维护的 fair-code 项目，与 GitHub、Google、OpenAI、Anthropic、Slack、OpenRouter 等平台与模型厂商不存在隶属或授权关系；文中出现的应用与服务名称仅用于说明集成目标。各连接器凭据、模型 API Key 与第三方服务条款由对应厂商约束。需要特别注意：n8n 并非 OSI 意义上的纯开源软件，社区版遵循 Sustainable Use License，部分角色管理、审计等企业能力受 Enterprise License 约束，商业二次发行前请先阅读官方许可说明。

1 项目简介

n8n（发音 “n-eight-n”，取自 “nodemation”）是一个面向 AI Agent 与工作流自动化的 fair-code 平台：在可视化画布上拖拽节点、连线编排流程，需要时直接写入 JavaScript、Python 或 npm 包代码；平台内置 1500+ 应用集成与 9000+ 工作流模板，并提供 LangChain 风格的 AI 节点来构建多步骤 Agent、工具调用、人工审批与可观测流程。工作流可以自托管在自己的服务器上，也可以运行在官方云服务。

1.1 核心信息一览

1.2 适用场景

• 把邮件、表单、CRM、数据库、消息队列、HTTP API 等系统串成自动流程：收到邮件 → 条件过滤 → AI 起草回复 → 写入草稿 → 发送通知。
• 构建多步 AI 工作流与 Agent：接入大模型做分类、抽取、总结、结构化输出，配合工具节点、分支、人工审批节点与错误重试。
• 定时任务与轮询触发：Schedule Trigger、Cron、轮询 HTTP / 数据库节点，按周期同步数据或生成报表。
• 团队与生产环境：角色与权限、凭据集中管理、执行历史与工作流版本历史、外部数据存储、队列模式水平扩展。
• 开发者二次扩展：编写自定义节点、复用 npm 包，或通过公共 REST API 与外部系统集成。

1.3 能力边界（官方口径）

• 官方 README 定位为 “Platform for AI Agents and Workflow Automation”，强调可视化画布与自定义代码结合、模型厂商不锁定、从原型到生产、1500+ 集成与 9000+ 模板。
• 官方明确提示：自托管需要服务器与容器管理、资源扩展、服务安全配置等技术能力；经验不足时建议使用 n8n Cloud，自托管配置不当可能导致数据丢失、安全问题与停机。
• n8n 自身不提供大模型、应用账号或 SaaS 订阅；模型与第三方集成的可用性、计费、风控由对应提供者决定。AI 节点能否调用工具、输出格式是否稳定取决于所选模型能力。
• 内置沙箱用于安全运行 n8n Assistant 生成的代码；官方在生产环境推荐改用 Daytona 等外部沙箱方案（见 Assistant 配置文档）。
• npm 安装方式自 n8n 3.0 起弃用，新版本仅通过 Docker 分发；旧 npm 实例可继续运行，但新安装与后续升级应改用 Docker。

2 功能特性

2.1 可视化画布与自定义代码并存

• 节点拖拽、连线、分支与错误回退在画布上完成；每个节点有参数面板与表达式（expression）支持字段引用。
• Code 节点支持 JavaScript、Python 与 npm 包，适合节点市场覆盖不到的自定义逻辑；用户代码由任务运行器在隔离环境中执行。

2.2 1500+ 集成与 9000+ 模板

• 内置覆盖 SaaS、数据库、消息、存储、协作工具等大量集成节点；官方模板库提供可直接导入的完整工作流，便于起步与二次修改。
• 连接器凭据集中在凭据管理中加密保存，工作流只引用凭据，不重复填写账号密钥。

2.3 AI 原生与多模型不锁定

• 提供 LangChain 风格 AI 节点：聊天模型、提示词、结构化输出解析器、工具调用、Agent 与记忆节点；可切换 OpenAI、Anthropic、Google、OpenRouter 与开源模型，不需要改动整体架构。
• n8n Assistant 为内置 AI 助手，可在画布上自然语言生成 / 调试工作流；默认关闭，需要在 AI 设置中填入模型 API Key 后开启，配套沙箱与内置搜索服务随 Compose 栈启动。

2.4 触发方式与执行可控

• 触发节点覆盖 Webhook、Schedule / Cron、轮询、手动、应用事件等；生产 Webhook 与测试 Webhook 使用不同路径，便于先调试再上线。
• 支持执行历史、工作流版本历史、执行数据裁剪与外部二进制数据存储，便于排障与审计。

2.5 自托管与扩展能力

• 默认 SQLite 适合试用；团队与生产环境可切换 PostgreSQL。支持队列模式（queue mode）多 Worker 扩展、外部数据存储、OpenTelemetry 链路追踪与 Prometheus 指标。
• 提供公共 REST API、SSRF 防护、公共 API 开关、节点黑白名单、外部密钥库、SSO / SAML / OIDC 等安全与集成选项。

2.6 环境变量与文件式配置

• 绝大多数行为可通过环境变量调整；部分敏感变量支持 _FILE 后缀从独立文件读取，便于容器编排与密钥管理。
• 配置文件 ~/.n8n/config 与环境变量配合，持久化目录 /home/node/.n8n 除 SQLite 外还存放加密密钥、实例日志与源码控制资产。

3 官方界面预览

下图为官方 README 中的工作流画布示例「Email Draft Assistant」：Gmail Trigger 收到邮件后经 FilterSender 条件分支，命中的邮件进入 ExtractEmailFields，再由 OpenRouter 聊天模型生成草稿、结构化输出解析器整理结果，随后调用 Gmail Create Draft 写回草稿箱，最后 Slack Notification 发送通知；未命中分支走到 Email Ignored 节点结束。

画布顶部为工作流名称与 Editor / Executions / Evaluations 切换标签，右侧 Publish 按钮发布工作流，底部中央为 Execute 手动执行按钮；更多节点参数、表达式与版本历史细节以安装版本为准，可在官方模板库中导入同类示例对照。

4 官方跳转链接汇总

5 前置要求与服务器配置

5.1 软件前提

• Docker Engine + Docker Compose v2：自托管首选方式；先执行 docker compose version 确认 Compose 插件可用。Windows 用户建议使用 WSL（Docker Desktop WSL2 后端），项目目录放在 WSL 文件系统内，避免跨 /mnt/c 挂载导致的慢盘与权限问题。
• Node.js（仅 npm 方式遗留使用）：npm 安装要求 Node.js 版本在 20.19 到 24.x（含边界）之间；新部署请直接使用 Docker。
• 模型凭据（可选，使用 AI 节点时）：OpenAI、Anthropic、Google、OpenRouter 等任一提供者 API Key；本地模型可走 OpenAI 兼容端点。
• 外部账号凭据（按需）：各 SaaS 连接器的 OAuth 授权或 API Token，在 n8n 凭据管理中填写。

5.2 硬件与系统建议

5.3 端口与目录

6 方式一：一键脚本与 Docker Compose 部署（推荐）

6.1 一键脚本自动初始化 Compose 栈

官方一键脚本会检查 Docker 与 Compose v2、在当前目录创建 n8n 文件夹、生成配置文件与随机密钥，拉取镜像并启动 n8n 与配套服务：

# 快速安装（需要本机已安装并运行 Docker）
curl -fsSL https://get.n8n.io | sh

启动成功后访问 http://localhost:5678。脚本日常命令：

# 停止
docker compose -f ./n8n/compose.yml down

# 再次启动
docker compose -f ./n8n/compose.yml up -d

# 升级到最新版本（仅更新 .env 中的版本号，保留数据与自定义配置）
curl -fsSL https://get.n8n.io | sh -s -- --upgrade

# 指定版本安装 / 升级
curl -fsSL https://get.n8n.io | sh -s -- --version 2.31.4

# 只生成配置文件、暂不启动
curl -fsSL https://get.n8n.io | sh -s -- --no-start

# 查看脚本全部参数
curl -fsSL https://get.n8n.io | sh -s -- --help

# 不愿直接执行远程脚本：先下载审阅再运行
curl -fsSL https://get.n8n.io -o get-n8n.sh
less get-n8n.sh
sh get-n8n.sh

卸载会删除全部数据：docker compose -f ./n8n/compose.yml down -v 后再 rm -rf ./n8n，其中 -v 会删除命名卷。

6.2 手动编写 Compose 文件（需要完全控制时）

脚本默认生成的组件与仓库 docker/get-n8n-compose.yml 一致，服务构成如下：

手动搭建时先创建项目目录与 .env（版本号从官方 Releases 页面取最新稳定值，不要照抄占位符）：

mkdir n8n && cd n8n

# n8n 版本：取自 https://github.com/n8n-io/n8n/releases 最新稳定版
N8N_VERSION=change-me-version-number
# 沙箱服务版本：取自 n8n-sandbox-service 最新稳定 release
N8N_SANDBOX_VERSION=change-me-sandbox-version-number
# 任务运行器认证 Token：自行生成随机值
N8N_RUNNERS_AUTH_TOKEN=change-me-runner-auth-token
# 沙箱服务密钥：自行取值
SANDBOX_API_KEYS=change-me-api-key
SANDBOX_API_RUNNER_REGISTRATION_TOKEN=change-me-registration-token
SANDBOX_API_RUNNER_API_KEY=change-me-runner-key
N8N_SANDBOX_SERVICE_API_KEY=change-me-api-key
# 内置搜索密钥
SEARXNG_SECRET=change-me-searxng-secret
N8N_INSTANCE_AI_SEARXNG_URL=http://searxng:8080

创建 searxng-settings.yml 开启 JSON 搜索接口：

use_default_settings: true
search:
  formats:
    - html
    - json

compose.yml 中 n8n 服务核心片段（完整文件以仓库 docker/get-n8n-compose.yml 为准）：

services:
  n8n:
    image: docker.io/n8nio/n8n:${N8N_VERSION}
    depends_on:
      sandbox-api:
        condition: service_healthy
    ports:
      - '5678:5678'   # 唯一应对外发布的端口
    env_file: .env
    volumes:
      - n8n-data:/home/node/.n8n

  runners:
    image: ghcr.io/n8n-io/runners:${N8N_VERSION}
    depends_on:
      - n8n
    environment:
      N8N_RUNNERS_AUTH_TOKEN: ${N8N_RUNNERS_AUTH_TOKEN}
      N8N_RUNNERS_TASK_BROKER_URI: http://n8n:5679
      N8N_RUNNERS_AUTO_SHUTDOWN_TIMEOUT: '15'
    # 执行 Code 节点用户代码，不要发布端口

启动：

docker compose up -d
docker compose logs -f n8n

6.3 接入 n8n Assistant（可选）

n8n 不配置模型 Key 也能完整使用工作流能力；Assistant 默认关闭。运行后在实例 AI 设置中添加模型 API Key 即可开启；也可在登录前编辑 ./n8n/.env：

# 模型提供者 API Key
N8N_INSTANCE_AI_MODEL_API_KEY=your-model-key
# 可选：使用 Brave 搜索时填入 Key
# INSTANCE_AI_BRAVE_SEARCH_API_KEY=your-brave-key

修改后重启生效：

docker compose -f ./n8n/compose.yml up -d

6.4 切换 PostgreSQL（团队 / 生产环境）

默认 SQLite 满足试用；需要独立数据库时，先准备 PostgreSQL 实例，再以环境变量覆盖数据库类型。官方完整 PostgreSQL Compose 配置见 n8n-hosting 仓库。使用 PostgreSQL 时仍建议挂载 `/home/node/.n8n` 持久化目录：其中保存加密密钥、实例日志与源码控制资产，并非只有 SQLite 文件。

7 方式二：手动 Docker 运行与本地源码运行

7.1 单容器手动 Docker 运行（最简试用）

# 创建持久化数据卷
docker volume create n8n_data

# 启动 n8n，暴露 5678，挂载数据卷，设置时区与安全文件权限
docker run -it --rm \
  --name n8n \
  -p 5678:5678 \
  -e GENERIC_TIMEZONE="<YOUR_TIMEZONE>" \
  -e TZ="<YOUR_TIMEZONE>" \
  -e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true \
  -v n8n_data:/home/node/.n8n \
  n8nio/n8n

• TZ 控制容器系统时区（date 等命令返回值）；GENERIC_TIMEZONE 控制 Schedule Trigger 等定时节点时区。
• N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true 强制配置文件使用安全权限。
• 访问 http://localhost:5678。

带 PostgreSQL 的手动运行：

docker run -it --rm \
  --name n8n \
  -p 5678:5678 \
  -e GENERIC_TIMEZONE="Asia/Shanghai" \
  -e TZ="Asia/Shanghai" \
  -e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true \
  -e DB_TYPE=postgresdb \
  -e DB_POSTGRESDB_DATABASE=<POSTGRES_DATABASE> \
  -e DB_POSTGRESDB_HOST=<POSTGRES_HOST> \
  -e DB_POSTGRESDB_PORT=<POSTGRES_PORT> \
  -e DB_POSTGRESDB_USER=<POSTGRES_USER> \
  -e DB_POSTGRESDB_SCHEMA=<POSTGRES_SCHEMA> \
  -e DB_POSTGRESDB_PASSWORD=<POSTGRES_PASSWORD> \
  -v n8n_data:/home/node/.n8n \
  n8nio/n8n

7.2 npm 本地运行（遗留方式，3.0 起弃用新安装）

# 无需安装即可试跑（Node.js 20.19–24.x）
npx n8n

# 全局安装
npm install n8n -g

# 指定版本
npm install -g n8n@0.126.1

# 启动
n8n
# 或
n8n start

升级与回退：

# 升级到最新
npm update -g n8n

# 切换 next 预览版
npm install -g n8n@next

# 数据库迁移后回退数据库（需要时按版本说明执行）
n8n db:revert

npm 方式不可用 n8n Assistant；从 3.0 起新安装请使用 Docker。

7.3 源码本地开发（开发者）

git clone https://github.com/n8n-io/n8n.git
cd n8n

# 仓库使用 pnpm 工作区，依赖安装与开发命令以 CONTRIBUTING.md 为准
# pnpm install
# pnpm dev
# pnpm start

源码包含核心服务、节点、编辑器与容器化脚本；贡献前先阅读仓库 CONTRIBUTING.md 的设置步骤与代码规范。

7.4 本地 Webhook 内网穿透（仅开发测试）

外部服务（如 GitHub）触发 Webhook 时需要 n8n 可从公网访问。官方提供基于 cloudflared 的隧道工具，仅供本地开发测试，生产环境不得使用该便利隧道：

• 全栈方式：n8n 与 cloudflared 都在容器中启动，启动时打印隧道公网地址。
• 服务方式：本地 pnpm dev 运行 n8n 时，单独启动 cloudflared 指向 host.docker.internal:5678，工具会把 WEBHOOK_URL 与 N8N_PROXY_HOPS=1 写入 .env；用完执行清理命令。

8 配置项说明

8.1 部署与访问基础变量

8.2 Webhook 与端点变量

8.3 数据库变量

8.4 时区、任务运行器与 AI 变量

8.5 安全与遥测变量（常用项）

以 _FILE 结尾的变量（如 DB_POSTGRESDB_PASSWORD_FILE）会从指定文件读取值，适合在容器编排中挂载 Secret 文件，避免在环境变量中直接落明文。

9 常用运维命令

# ---- Compose 日常操作（一键脚本目录 ./n8n）----
docker compose -f ./n8n/compose.yml up -d            # 启动
docker compose -f ./n8n/compose.yml down            # 停止并移除容器
docker compose -f ./n8n/compose.yml logs -f n8n    # 跟踪 n8n 日志
docker compose -f ./n8n/compose.yml ps             # 查看各服务状态
docker compose -f ./n8n/compose.yml pull             # 拉取最新镜像
docker compose -f ./n8n/compose.yml restart n8n   # 重启 n8n 服务

# ---- 单容器手动部署 ----
docker ps -a                                        # 查找容器 ID
docker stop <container_id>
docker rm <container_id>
docker run --name=<container_name> -d n8nio/n8n

# ---- 镜像版本 ----
docker pull n8nio/n8n                              # 最新稳定
docker pull n8nio/n8n:1.81.0                       # 指定版本（示例）
docker pull n8nio/n8n:next                          # 预览版（不稳定）

# ---- npm 遗留安装 ----
n8n start                                          # 启动
n8n db:revert                                      # 回退数据库迁移（按版本说明使用）
npm update -g n8n                                  # 全局升级

# ---- 备份 ----
# 持久化目录位于命名卷 n8n-data（/home/node/.n8n），备份卷与 PostgreSQL 数据目录
docker run --rm -v n8n-data:/data -v $(pwd):/backup alpine \
  tar czf /backup/n8n-data-backup.tar.gz -C /data .

日志与执行历史在画布 Executions 标签中查看；容器内日志通过 docker compose logs 或 docker logs <container_id> 获取。升级 Compose 部署前先备份数据卷与数据库，并阅读对应 Release 说明中的数据库迁移提示。

10 常见故障排查

10.1 5678 端口无法访问

• 先确认容器状态：docker compose ps / docker ps -a，查看 n8n 服务是否健康。
• 检查端口映射是否为 5678:5678，宿主机 5678 是否被其他进程占用；反向代理场景核对 N8N_EDITOR_BASE_URL、N8N_WEBHOOK_URL 与 N8N_PROXY_HOPS。
• 首次启动需要等待片刻，页面未加载成功时刷新；查看 docker compose logs n8n 中的启动报错。

10.2 Webhook 收不到外部请求

• 本地开发用隧道仅适合测试，生产环境必须配置公网域名与反向代理，并把 N8N_WEBHOOK_URL 设为公网基础地址。
• 区分生产 Webhook（/webhook/...）与测试 Webhook（/webhook-test/...）；测试地址只在工作流调试会话期间生效。
• 反向代理层级较多时设置 N8N_PROXY_HOPS 匹配代理跳数，避免客户端 IP 解析错误。

10.3 数据库连接失败或启动报迁移错误

• PostgreSQL 部署核对 DB_TYPE=postgresdb 与 DB_POSTGRESDB_* 主机、端口、库名、用户、Schema、密码；网络可达性与 SSL 选项一并检查。
• 升级后启动报数据库迁移错误时，先备份数据库，再对照 Release 说明执行 n8n db:revert 等回退步骤；不要在未备份的情况下反复跨大版本升降级。
• 使用 PostgreSQL 时仍要持久化 /home/node/.n8n：加密密钥与日志不在数据库内。

10.4 凭据丢失或解密失败

• N8N_ENCRYPTION_KEY 变更后，旧凭据无法用新密钥解密；生产环境应在首次部署时固定自定义密钥并妥善备份。
• 迁移服务器或重建容器时，必须连同数据卷中的密钥一起迁移；仅复制工作流 JSON 不会带走加密凭据。

10.5 Code 节点执行失败

• 任务运行器未就绪时，核对 N8N_RUNNERS_AUTH_TOKEN 在 n8n 与 runners 服务中一致，N8N_RUNNERS_TASK_BROKER_URI 网络可达。
• Code 节点依赖的第三方 npm 包需先确认任务运行器环境支持；执行错误在 Executions 历史中查看完整堆栈。
• 沙箱相关端口（8080 / 9090 / 9091）保持 Compose 内网调用，不要发布到公网。

10.6 AI 节点或 Assistant 不响应

• 确认模型 Key 已在 AI 设置或 .env 中配置，模型名与端点匹配提供者文档；本地模型走 OpenAI 兼容端点时核对基础地址。
• Assistant 依赖沙箱栈与搜索服务，检查 sandbox-api、sandbox-runner-1、searxng 健康状态；生产环境按官方文档评估外部沙箱方案。
• 本地模型不支持工具调用或结构化输出时，更换支持对应能力的模型或调整提示词与解析器节点。

10.7 Windows 下挂载慢或权限报错

项目目录放在 WSL 文件系统内（如 ~/n8n），不要放在 /mnt/c/...；使用 Docker Desktop WSL2 后端，避免跨边界绑定挂载导致的性能与权限问题。

10.8 资源不足导致沙箱或运行器崩溃

含 Assistant 沙箱栈需要至少 4 GB 内存、2 vCPU；sandbox-runner-1 为特权 Docker-in-Docker 容器。内存不足时先减少并行工作流数量、关闭不需要的沙箱服务，再按官方指南升级服务器规格。

10.9 请求体过大被拒绝

上传附件或二进制数据超过 N8N_PAYLOAD_SIZE_MAX（默认 16 MiB）或 N8N_FORMDATA_FILE_SIZE_MAX（默认 200 MiB）时按业务需要调大对应变量；大文件同时参考外部二进制数据存储配置，避免数据库膨胀。

11 风险与合规说明

以下条款整理自官方 README、许可文档与 docs.n8n.io 口径；如与官方原文不一致，以仓库 LICENSE.md、LICENSE_EE.md 与 docs.n8n.io 为准。

11.1 许可模式

n8n 采用 fair-code 双许可：社区代码遵循 Sustainable Use License，包含角色管理、审计跟踪等在内的部分企业功能遵循 n8n Enterprise License。源码可见、可自托管、可扩展，但不等于 OSI 定义的开源软件；商用二次发行、移除品牌标识或将 n8n 作为托管服务转售前，必须先阅读许可文档并在需要时联系 license@n8n.io 获取企业授权。

11.2 自托管安全责任

• 官方明确自托管需要服务器、容器、资源扩展与安全配置能力，配置不当可能造成数据丢失、安全漏洞与停机。
• 生产环境务必：设置强管理员密码与 2FA、限制 5678 端口访问、配置 HTTPS、关闭不需要的公共 API、按需启用 SSRF 防护与节点黑白名单、定期备份数据卷与数据库。
• 任务运行器与沙箱容器承载用户编写的代码，不要把特权沙箱端口暴露到公网；不要在不可信工作流中保留高权限凭据。

11.3 凭据与数据隐私

• 工作流会携带邮件正文、客户数据、文件与 API 调用上下文，按所选连接器与模型发送到第三方服务；处理敏感数据时优先使用本地模型、私有端点与私有网络部署。
• 第三方 SaaS 凭据、OAuth Token 与模型 Key 归对应厂商所有，受其服务条款、隐私政策与计费规则约束；n8n 只是凭据的存储与代理调用方。
• 关闭 N8N_DIAGNOSTICS_ENABLED 可停止匿名诊断上报；具体收集字段以官方遥测文档为准。

11.4 模型与工作流可靠性

• AI 节点的分类、抽取与代码生成结果可能出错；生产关键流程应加入人工审批、结果校验、错误回退与告警节点，不要把未审核的 AI 输出直接写入核心业务系统。
• 模型能力（工具调用、结构化输出、长上下文）因厂商与版本而异；工作流迁移到其他模型时需要重新测试提示词、解析器与分支逻辑。

11.5 商业使用与免责

n8n 按现状（AS-IS）提供，不保证模型与第三方集成持续可用、不保证工作流在特定环境下的正确性；使用者自行承担工作流逻辑、数据泄露、服务中断与业务损失风险。如认为仓库内特定文件侵犯合法权益，请通过 GitHub Issues 提交说明，不要在公开 Issue 或工作流示例中提交账号密码、API Token 或内部地址。