n8n：可视化工作流与 AI 智能体自动化平台

官方信息表

项目背景

n8n 是一个用于构建和部署 AI 智能体与工作流的 fair-code 平台。按照官方 README 的定位：它把可视化画布和自定义代码结合在一起，既可以自托管，也可以用官方云服务；并且内置了 1500+ 集成，让你在从原型到生产的全过程中，都能跑起"你可以真正信任的 AI 自动化"。README 还特别强调：无论是做复杂的数据同步，还是让 AI 智能体自动处理工单，n8n 都能让你把"想法"在画布上快速拼成可运行的流程，而不需要从零写胶水代码。

官方 README 给出的六大关键能力如下：

• AI 原生的自动化平台：用你自己的数据、模型和工具来构建并落地 AI 工作流与多步骤智能体。
• 模型灵活、不锁定：可以接 OpenAI、Anthropic、Google，也可以接开源模型，切换供应商不用改架构。
• 从原型到生产：用逻辑、工具调用、人工审批和完整的可观测性来设计多步骤 AI 工作流。
• 需要写代码时就能写：在可视化搭建之外，用 JavaScript、Python 和 npm 包来实现高级 AI 工作流。
• 企业级就绪：自托管部署，配合基于角色的访问控制、审计日志，可放心处理敏感数据。
• 站在已有系统上：1500+ 集成和 9000+ 工作流模板，把 AI 直接接到你现有的系统里。

也就是说，n8n 的定位不是单一工具，而是一个"AI 智能体 + 自动化工作流"的一体化平台：既能在画布上拖拽出业务流程，也能在需要精确控制时写 JavaScript 或 Python；既能一条命令跑在本地，也能自托管到企业内网，把数据完全留在自己手里。

关于"n8n"这个名字，创始人 Jan Oberhauser 在 README 里亲自解释：短答案是它表示 "nodemation"，读作 n-eight-n；长答案是——当年想给项目起个带免费域名的好名字时，发现能想到的好名字都被注册了，于是从 Node-View、Node.js 取 "node-"，从 automation 取 "-mation"，合成 nodemation；但又觉得太长，每次在 CLI 里敲都麻烦，最后缩写成了 n8n（中间省略 8 个字母）。

官方 README 还列出了一份资源清单，方便新用户按图索骥：📚 完整文档在 docs.n8n.io；🔧 全部集成节点在 n8n.io/integrations；💡 示例工作流在 n8n.io/workflows；🤖 AI 与 LangChain 用法指南在官方文档；👥 社区论坛在 community.n8n.io；📖 社区教程合集在论坛教程版块。

环境要求

自托管 n8n 需要一定的技术基础，官方明确列出：会搭建和配置服务器与容器、会管理应用资源与扩容、会做服务器与应用的安全加固、会配置 n8n。官方建议自托管面向有经验的用户——操作失误可能导致数据丢失、安全问题和停机；如果不熟悉服务器管理，官方推荐直接用 n8n Cloud。

具体到运行环境，官方文档提供两条路线：

• Docker 路线：在 Mac/Windows/Linux 上装 Docker Desktop（内置 Docker Engine 和 Docker Compose）；Linux 无图形界面的机器也可以单独装 Docker Engine 和 Docker Compose。
• npm 路线：必须先装 Node.js，版本范围在 20.19 到 24.x（含两端）。注意官方文档注明：基于 npm 的安装方式从 n8n 3.0 起已废弃，且 npm 安装下不可使用 n8n Assistant。

版本方面，n8n 几乎每周发一个小版本：stable 是生产可用版本，beta 是最新发布但可能不稳定的版本（文档写作时 stable 为 2.45.4、beta 为 2.46.0）。

部署步骤

方式一：一键脚本（最快体验）

官方 README 提供了一行命令，前提是机器上已有 Docker：

curl -fsSL https://get.n8n.io | sh

官方文档详细解释了这个脚本：它取代了老的 npm install n8n / npx n8n 方式（这套方式从 n8n 3.0 起不再可用），是从零开始部署 n8n 最快的路径，无论你之前熟不熟悉 Docker 都能用。脚本要求的前置条件只有一个——装好并后台运行 Docker（需要 docker compose v2 插件，不是老的独立 docker-compose 二进制；用 Podman、Colima 等兼容引擎的话，装好带 compose 插件的 docker CLI 并把 DOCKER_HOST 指向其 socket 即可）。

执行后脚本会自动完成四件事：检查 Docker 是否安装并在运行（没装好会给出修复提示）、在当前目录创建 n8n 文件夹、写入运行所需配置文件、下载镜像并启动。它可以安全地重复运行——如果该目录已经装过 n8n，脚本只会提示"已存在"而不会改动任何东西。一次成功的输出长这样：

$ curl -fsSL https://get.n8n.io | sh

✓ Docker found (24.0.6)
✓ Docker Compose found (v2.24.0)
✓ Created ./n8n/compose.yml
✓ Created ./n8n/searxng-settings.yml
✓ Created ./n8n/.env (unique secrets generated)
Pulling images and starting (this can take a few minutes on first run)...
✓ Started n8n 2.32.0 and sandbox services

n8n is running at: http://localhost:5678
Data stored in:    ./n8n (Docker volume: n8n-data)
Config files:      ./n8n/compose.yml, ./n8n/.env

这套一键安装默认自带三样东西：n8n 工作流编辑器本体（跑在 5678 端口）、内置的 SQLite 轻量数据库（直接存文件，无需另装数据库服务器）、以及 n8n Assistant 的配套服务——一个安全运行 AI 写出代码的沙箱和一个内置搜索工具。沙箱和搜索服务会随 n8n 自动启动，但 Assistant 本身在你填入模型 API Key 之前是关闭的。官方提醒：如果是给团队或生产环境用，建议把数据库换成 PostgreSQL，沙箱在生产环境推荐用 Daytona 而不是内置沙箱。

日常运维命令：

# 停止
docker compose -f ./n8n/compose.yml down
# 再次启动
docker compose -f ./n8n/compose.yml up -d
# 升级到最新版
curl -fsSL https://get.n8n.io | sh -s -- --upgrade
# 卸载并删除数据（-v 会删除全部 n8n 数据）
docker compose -f ./n8n/compose.yml down -v
rm -rf ./n8n

升级命令会把 n8n 和内置沙箱服务一起升到新版本，只改动 .env 里的 N8N_VERSION 和 N8N_SANDBOX_VERSION 两行，你的数据、密钥和其他配置原样保留。想开启 n8n Assistant，最简单的方式是在 Web 界面的 AI 设置里填模型 API Key；也可以直接编辑脚本生成的 ./n8n/.env，在 N8N_INSTANCE_AI_MODEL_API_KEY 行填入 Key，然后 docker compose -f ./n8n/compose.yml up -d 重启即可。默认网页搜索走内置搜索工具，无需任何配置；想用 Brave Search 就把 Brave API Key 填到同一个 .env 的 INSTANCE_AI_BRAVE_SEARCH_API_KEY。注意默认只有 5678 端口对外暴露，其他服务都保持私有。

方式二：Docker 手动部署

官方推荐用 Docker 做大多数自托管——它提供干净、隔离的环境，避免操作系统和工具链兼容问题，数据库与环境管理也更简单。先创建数据卷再启动容器（把 <YOUR_TIMEZONE> 换成你所在时区，如 Asia/Shanghai）：

docker volume create n8n_data

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

这条命令做了什么：创建持久化数据卷、拉取 n8n 镜像、把容器 5678 端口映射到宿主机；TZ 设置系统时区（影响 date 等命令），GENERIC_TIMEZONE 设置调度类节点（如 Schedule Trigger）的时区；N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true 强制配置文件安全权限；把 n8n_data 卷挂载到 /home/node/.n8n，容器重启后数据不丢。启动后浏览器打开 http://localhost:5678 即可。官方文档还提示：N8N_RUNNERS_ENABLED 从 n8n 2.0 起已废弃，不再需要手动设置（1.x 时代必须设为 true 才能启用任务运行器）。

默认情况下 n8n 用 SQLite 保存凭据、历史执行记录和工作流；要换 PostgreSQL，加一组环境变量即可：

docker volume create n8n_data

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 \
 -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

注意：用 PostgreSQL 后，.n8n 目录不再存 SQLite 文件，但仍存放加密密钥、实例日志、源码管理资产等重要数据，官方仍然建议挂载持久卷。完整的 PostgreSQL docker-compose 文件见 n8n-hosting 仓库。

方式三：npm / npx

# 免安装直接试玩
npx n8n

# 全局安装
npm install n8n -g

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

# 安装 next（最新预览版）
npm install -g n8n@next

# 启动
n8n
# 或
n8n start

启动后同样访问 http://localhost:5678。更新用 npm update -g n8n。Windows 下遇到问题，按微软官方指引检查 Windows 上的 Node.js 环境。官方特别提醒：npm 安装方式从 n8n 3.0 起已废弃——届时 n8n 只通过 Docker 分发；现有的 npm 安装暂时还能跑，但新安装和未来升级都应该转向一键脚本或 Docker 方式。

更新与回滚

Docker 下更新：在 Docker Desktop 的 Images 页对 n8n 镜像选 Pull，或命令行拉取后重建容器：

docker pull n8nio/n8n          # 最新稳定版
docker pull n8nio/n8n:1.81.0   # 指定版本
docker pull n8nio/n8n:next     # 预览版

docker-compose 部署的更新流程是：docker compose pull → docker compose down → docker compose up -d。如果升级涉及数据库迁移后想回退，先查 release notes 有没有手动步骤，再在当前版本执行 n8n db:revert 回滚数据库（多步迁移需重复执行）。

使用方法与关键配置项

内置隧道（仅本地开发）

要用 GitHub 等外部服务的 Webhook 触发节点，n8n 必须能从公网访问。官方提供了基于 cloudflared 的隧道服务。官方明确警告：隧道只用于本地开发和测试，生产环境不安全；它属于开发便利工具，实现方式可能随版本变化。

官方给出两种隧道用法。第一种是全栈模式：n8n 和 cloudflared 都跑在容器里，启动时直接打印隧道 URL，一切自动接好：pnpm stack --tunnel。第二种是仅服务模式：如果你习惯用 pnpm dev 或 pnpm start 本地跑 n8n，就单独起 cloudflared 服务——第一个终端执行 pnpm --filter n8n-containers services --services cloudflared，第二个终端执行 pnpm dev。这个 services 命令会把 cloudflared 指向 host.docker.internal:5678，从 cloudflared 的 metrics 接口拿到公网隧道 URL，再写一份 .env 到 packages/cli/bin/.env（包含 WEBHOOK_URL 和 N8N_PROXY_HOPS=1），n8n 启动时自动用 dotenv 读入。用完执行 pnpm --filter n8n-containers services:clean 清理。

环境变量速查

自托管 n8n 的所有配置都可以通过环境变量完成；也支持给变量名加 _FILE 后缀，把敏感值放到单独文件里（适合把密码、密钥注入容器）。官方文档把变量按类分成了 20 多组：AI 助手、二进制数据、凭据、数据库、部署、端点、执行、表达式引擎、外部数据存储、外部钩子、外部密钥库、Insights 统计、日志、许可证、节点、OpenTelemetry、队列模式、调度器、安全、源码管理、SSO、SSRF 防护、任务运行器、时区与本地化、用户管理与 2FA、工作流与工作流历史等。代理变量有个细节：n8n 底层用的 proxy-from-env 包规定，同时存在大小写两个版本时，小写（如 http_proxy）优先级高于大写（如 HTTP_PROXY）。最常用的几个：

• N8N_HOST（默认 localhost）：n8n 运行的主机名。
• N8N_PORT（默认 5678）：HTTP 端口。
• N8N_PATH（默认 /）：部署路径；配合反向代理容易出目录问题，建议用子域名。
• N8N_PROTOCOL（默认 http，可选 https），配合 N8N_SSL_KEY、N8N_SSL_CERT 启用 HTTPS。
• N8N_EDITOR_BASE_URL：用户访问编辑器的公网 URL，也用于 n8n 发出的邮件和 SAML 跳转。
• N8N_ENCRYPTION_KEY：加密数据库中凭据的密钥；默认首启随机生成，生产环境建议固定。
• DB_TYPE=postgresdb + DB_POSTGRESDB_* 系列：切换 PostgreSQL。
• GENERIC_TIMEZONE / TZ：调度节点时区与系统时区。
• HTTP_PROXY / HTTPS_PROXY / NO_PROXY：节点出站请求走代理；注意小写 http_proxy 优先级高于大写。
• N8N_TEMPLATES_ENABLED（默认 true）：是否启用工作流模板库；N8N_TEMPLATES_HOST 可指向自建模板库。
• N8N_PUBLIC_API_DISABLED、N8N_PUBLIC_API_ENDPOINT（默认 api）：公共 API 开关与路径。
• N8N_DIAGNOSTICS_ENABLED（默认 true）：匿名遥测；关掉后 Code 节点里的 Ask AI 不可用。

完整变量清单按类组织在官方文档的环境变量总览页里，每一类都有独立页面逐项说明类型、默认值和注意事项；除了环境变量，n8n 也支持用 YAML 配置文件做同样的事，生产环境推荐用配置文件统一管理。

FAQ（官方问答）

问：n8n 到底是什么意思？ 答：是 "nodemation" 的缩写，读作 n-eight-n——node（Node.js / Node-View）+ automation（自动化）。

问：n8n 是开源的吗？ 答：它是 fair-code 分发：源码始终可见、可以自托管、可以自行扩展节点，但采用 Sustainable Use License（企业级功能另购 Enterprise License）。

问：npm 安装和 Docker 安装选哪个？ 答：官方推荐 Docker，npm 路线从 n8n 3.0 起已废弃，且 npm 安装下没有 n8n Assistant。

问：隧道能直接对外提供服务吗？ 答：不能。官方标注为 danger——隧道仅供本地开发调试 Webhook 使用，生产环境必须用正式的反向代理和公网入口。

问：升级后想退回旧版本怎么办？ 答：重装旧版即可；若涉及数据库迁移，需按 release notes 执行 n8n db:revert 回滚数据库。

问：遇到问题去哪里求助？ 答：官方社区论坛 community.n8n.io 是官方指定的支持渠道；提交 bug 或提需求前也可以先看贡献指南。

问：自托管需要哪些技术储备？ 答：官方要求会搭建和配置服务器与容器、管理应用资源与扩容、做安全加固、以及配置 n8n 本身。官方明确建议自托管面向有经验的用户，新手建议直接用 n8n Cloud。

问：内置数据库是什么？数据存在哪？ 答：默认是 SQLite，一个文件级轻量数据库，随容器持久卷保存；生产或团队场景推荐切到 PostgreSQL。一键安装方式的数据卷名为 n8n-data，配置文件在 ./n8n/compose.yml 和 ./n8n/.env。

跳转链接

• 项目仓库：n8n-io/n8n
• 官方文档：docs.n8n.io
• 集成目录：1500+ Integrations
• 工作流模板：n8n.io/workflows
• AI 与 LangChain 指南：AI & LangChain Guide
• 云服务：n8n Cloud
• 社区论坛：community.n8n.io
• 自托管配置库：n8n-hosting