n8n 自托管教程：把自动化工作流装到自己的 VPS 上

这篇 n8n 教程不是把官方 README 抄一遍。我把官方文档里 Docker Compose 部署、反向代理环境变量、许可证边界这几块逐行核对过，能抄的部分给完整配置，容易抄错的部分讲清楚每一行在干什么，最后再补上我作为自托管用户的维护清单和踩坑记录。

n8n 是什么，为什么有人要把它装到自己的机器上

n8n 是一个可视化流程自动化平台：把节点拖到画布上连起来，一个节点负责一件事，从触发器开始，到请求、判断、代码、发消息、写数据库，整条流程跑一遍就是一次“执行”。它内置的官方节点覆盖了主流 SaaS、数据库、邮件、IM 和各类 API，不够用的时候可以直接写 JavaScript 或 Python 代码节点，也可以自己写自定义节点装进去。

和 Zapier、Make 这类同赛道产品比，n8n 的差异点很直接：

• 计费口径不同。Zapier 和 Make 按“任务/操作”计费，一个流程里节点越多，单次运行烧掉的任务数越多；n8n 按整条流程的执行次数计费，步骤不限，官方原话是“为完整的执行付费，而不是为每一步付费”。自托管版连执行次数都不花钱。
• 部署方式不同。n8n 官方提供 Docker 镜像和完整 Compose 示例，装到自己的 VPS 上跑，数据库、凭证、执行记录都在你自己的机器里，不会经过厂商的云。
• 代码友好度不同。n8n 的编辑器里可以随时插代码节点、跑 bash、调自定义 API，适合“半个程序员”和完整程序员。

为什么有人放着现成的云服务不用，非要自己装？我总结是三类需求：一是成本，高频批量流程在云端按执行次数算下来不便宜，自托管是固定成本，一台 VPS 多少钱就是多少钱；二是数据边界，流程要连内网数据库、要处理客户数据时，很多人不愿意让数据经过第三方平台；三是自由度，官方云对并发、单次执行时长、节点行为有各种限制，自己装可以把这些限制全拆掉。

需要先泼一盆冷水：n8n 的源码公开在 GitHub 上，但它用的不是 OSI 意义上的开源许可证，而是 Sustainable Use License（fair-code 体系）：个人和公司自托管使用免费，但条款里有使用边界（比如不能拿它做直接竞争的托管服务），商用之前把官方 LICENSE 读一遍，别想当然。

自托管 vs n8n Cloud：先算清楚钱再动手

官方云的价格按“每月执行次数”分档，所有档位都不限用户数和工作流数量。写作当天从官方定价页核到的价格如下（欧元计价）：

年付比月付省 17%，表里两个价格都来自官方页面同一份数据。免费试用云端的 Pro 级功能时，官方给的试用额度是 1,000 次执行、5 并发、单次执行 180 秒超时，试用期结束后要么买档位要么换自托管，别指望云端长期白嫖。

自托管这边的成本账很简单：一台能跑 Docker 的 VPS 加一个域名，订阅费为零。下面两篇是我写过的选购和部署实录，机器和部署链路的坑都在里面：

• VPS 选购指南：怎么挑机房、看配置、比价格；
• WordPress VPS 部署指南：装 Docker、配 Nginx、开 HTTPS 的完整链路，和本文后半段是同一套动作。

怎么选其实一句话：只想把流程跑起来、不想管服务器，买 Cloud 的 Starter 或 Pro；流程高频、量大、要接自家内网，或者单纯想省订阅费，走下面的自托管路线。

准备工作：域名解析和 VPS 配置

先准备一个子域名，比如 n8n.example.com，把 DNS 的 A 记录指到你的 VPS 公网 IP。后面 Nginx、证书、n8n 的对外地址全部要用这个域名，先把解析做好，避免部署完才发现域名没生效，在 HTTPS 证书那一步卡住。

VPS 配置给两个口径：

• 想装官方那套完整 Compose（带 AI 助手沙箱、代码沙箱那一大串服务）的话，官方文档白纸黑字要求至少 4GB 内存和 2 核 CPU，沙箱是 Docker-in-Docker，吃内存比普通容器凶得多；
• 只跑普通自动化（定时、Webhook、HTTP、邮件这类常规节点），按本文下面的最小配置装 sqlite 单容器版，内存占用要小一个量级，2GB 内存的机器够日常用。这个口径官方没有书面承诺，官方只对 4GB 那套给过明确数字，机器买小了先别怪 n8n。

系统建议 Debian/Ubuntu，省事。如果你机器上还跑着别的东西，建议先看下我的另一篇部署记录，里面讲了怎么在同一台机器上隔离多个自托管服务，避免互相抢端口和内存：Hermes Agent VPS 部署指南。

在 VPS 上部署：从 Docker 到 HTTPS 一步步来

第一步：装 Docker 和 Compose 插件

Docker 官方提供了各发行版的安装说明，Ubuntu/Debian 可以直接用官方安装脚本，装完确认两个命令都在：

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

docker --version
docker compose version

注意 n8n 官方文档要求的是 docker compose 的 v2 插件（命令中间没有横杠），不是老版的 docker-compose 独立二进制。装完把当前用户加进 docker 组，或者全程用 sudo 跑，二选一：

sudo usermod -aG docker $USER
exec sg docker newgrp

第二步：建目录，写 .env

官方文档的做法是建一个项目目录，把环境变量和 Compose 文件放一起，方便以后整目录备份和迁移：

mkdir n8n && cd n8n
mkdir local-files

local-files 是给 Read/Write Files from Disk 节点用的共享目录，先建好能保证属主正确。然后写 .env：

# 对外域名，DNS、Nginx、下面的 WEBHOOK_URL 全都要和它一致
N8N_DOMAIN=n8n.example.com

# 凭证加密密钥，先生成一个：openssl rand -hex 32
# 官方默认是首次启动时自动生成、存在数据目录的 config 文件里；
# 显式写进 .env，备份和迁移时就不用去卷里捞密钥文件
N8N_ENCRYPTION_KEY=这里替换成openssl生成的值

# 定时类节点（Cron、Schedule Trigger）用的时区
# 官方默认是 America/New_York，国内机器不改的话定时全按纽约时间跑
GENERIC_TIMEZONE=Asia/Shanghai

# 容器系统时区，影响 date 这类命令的输出
TZ=Asia/Shanghai

生成密钥的命令是 openssl rand -hex 32，在服务器上跑一下把输出粘进去。这个密钥一旦丢了或换了，数据库里已保存的凭证将无法解密，所以它和数据库文件一样重要，这就是为什么要显式写出来而不是让它藏在卷里。

第三步：写 compose.yaml（SQLite 单容器版）

官方目前推荐的自托管组合是：n8n 容器 + 一个反代容器（文档示例用 Traefik，托管仓库里另有 Caddy 版）。本文教程按你的习惯换成了 Nginx 做反代，n8n 本身的配置逐行对齐官方示例。先看文件：

services:
  n8n:
    image: n8nio/n8n
    restart: always
    ports:
      - "127.0.0.1:5678:5678"
    environment:
      - N8N_HOST=${N8N_DOMAIN}
      - N8N_PORT=5678
      - N8N_PROTOCOL=https
      - N8N_WEBHOOK_URL=https://${N8N_DOMAIN}/
      - N8N_PROXY_HOPS=1
      - NODE_ENV=production
      - GENERIC_TIMEZONE=${GENERIC_TIMEZONE}
      - TZ=${TZ}
      - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}
      - N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true
      - N8N_RESTRICT_FILE_ACCESS_TO=/files
    volumes:
      - n8n_data:/home/node/.n8n
      - ./local-files:/files

volumes:
  n8n_data:

逐行说人话：

• image 用官方镜像 n8nio/n8n，不带版本 tag 就是 stable 频道，官方每周发新版本，stable 用于生产；
• 端口只绑 127.0.0.1，意思是只有本机能访问 5678，公网直连被挡在门外，Nginx 从本机转发进去。这是官方 Traefik 示例的同款做法，别改成 0.0.0.0:5678:5678 裸奔；
• N8N_HOST、N8N_PORT、N8N_PROTOCOL 决定 n8n 眼里自己的地址；因为前面有反代终结 HTTPS，所以协议写 https、域名写你的子域；
• N8N_WEBHOOK_URL 手动指定对外 Webhook 地址。官方反代配置页的原话：n8n 默认拿 N8N_PROTOCOL/HOST/PORT 拼 Webhook URL，反代场景下会拼错，必须手动设。注意 2.35 起官方用 N8N_WEBHOOK_URL 取代了 WEBHOOK_URL，老变量还能用但会打弃用日志，新配置直接写新的；
• N8N_PROXY_HOPS=1 告诉 n8n 前面有一层代理，配合 Nginx 透传的 X-Forwarded-* 头才能拿到真实协议和来源；
• 数据卷挂到 /home/node/.n8n，这是官方规定的数据目录，SQLite 数据库文件和自动生成的配置都在这；
• N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true 是官方 Docker 示例统一带的，收紧配置文件权限；N8N_RESTRICT_FILE_ACCESS_TO=/files 限制文件节点只能读写共享目录，两个都照抄官方示例。

启动并验证：

docker compose up -d
docker compose ps
curl -sf http://127.0.0.1:5678/healthz

/healthz 返回 OK 就说明 n8n 本体活了。此时公网还访问不到它，接下来上 Nginx。

第四步：Nginx 反代 + HTTPS 证书

先装 Nginx 和 certbot：

sudo apt update
sudo apt install -y nginx certbot python3-certbot-nginx

写站点配置 /etc/nginx/sites-available/n8n：

server {
    listen 80;
    server_name n8n.example.com;

    # n8n Webhook 默认接收上限是 16MB；Nginx 默认只有 1MB，
    # 不调大的话，超过 1MB 的 Webhook 请求会在 Nginx 这层被直接拒掉
    client_max_body_size 16m;

    location / {
        # 目标就是 compose 里绑定的回环端口，三层必须对得上
        proxy_pass http://127.0.0.1:5678;
        proxy_http_version 1.1;

        # 官方反代文档要求透传这三个头，和容器里的 N8N_PROXY_HOPS=1 配套
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_set_header Host $host;

        # 编辑器里的实时连接要升级成 WebSocket，保留这两行
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

启用并让 Nginx 吃进配置：

sudo ln -s /etc/nginx/sites-available/n8n /etc/nginx/sites-enabled/n8n
sudo nginx -t
sudo systemctl reload nginx

然后签证书，certbot 的 Nginx 插件会自动改配置、开 443 并配置自动续期：

sudo certbot --nginx -d n8n.example.com

最后处理防火墙。Ubuntu 的 ufw 或云厂商安全组二选一，原则相同：放行 22、80、443，不要放行 5678（它本来就只绑在回环上，公网到不了）：

sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw enable

现在浏览器打开 https://n8n.example.com，注册第一个账号。第一个注册的账号就是实例所有者（owner），后续所有账号都由它审批加入。到这部署就完成了，整条链路是：浏览器 → Nginx(443) → 127.0.0.1:5678 → n8n 容器。如果打不开，按这个顺序查：DNS 解析是否生效、ufw/安全组是否放行 80/443、nginx -t 是否报错、curl http://127.0.0.1:5678/healthz 在服务器本机是否通。

第一个 workflow：用 Webhook 把外部请求接进来

部署完先别急着搭复杂流程，从 Webhook 触发开始，五分钟能验证整条链路通不通。在画布上加一个 Webhook 节点（触发器），方法选 POST，路径保持自动生成的随机值就行。节点面板顶部有两个 URL：测试 URL 和生产 URL。区别要记牢：测试 URL 配合“Listen for test event”按钮用，点执行后它才临时注册；生产 URL 要等 workflow 处于 Active 状态才真正对外生效，外部服务一律填生产 URL。

# 流程激活后，用 curl 模拟外部服务推数据
curl -X POST https://n8n.example.com/webhook/你的路径 \
  -H "Content-Type: application/json" \
  -d '{"name": "gk", "channel": "vps"}'

# 看到 "Workflow got started" 就说明 n8n 收到了

Webhook 后面再接一个 Set 节点改改字段、接一个 HTTP Request 节点转发到别处，保存并激活，一个能收外部事件的自动化就成立了。想定时跑的话，把触发器换成 Schedule Trigger，注意它走的是 GENERIC_TIMEZONE，也就是 .env 里配的 Asia/Shanghai，别再用默认的纽约时间做业务判断。

Webhook 节点面板里还有个 Respond 选项，控制 n8n 什么时候回包：立即回、等最后一个节点跑完再回、还是用专门的 Respond to Webhook 节点决定内容。拿 n8n 当轻量 API 后端用的人基本都选后两种。

AI Agent：自托管 n8n 现在能玩到什么程度

n8n 的 AI 玩法核心是 AI Agent 节点：它是个根节点，下面挂一个 Chat Model 子节点（模型）、至少一个 Tool 子节点（工具）、可选记忆和向量库。模型节点覆盖 OpenAI、Anthropic Claude、Google Gemini、国内的 Qwen、Moonshot Kimi、MiniMax，也有 Groq 和本地模型 Ollama，自托管场景下填自己的 API Key 就能用，数据流不经过 n8n 的云。想用本地模型的话，Ollama 节点直接把请求发到你自己的机器，模型权重和对话数据都不出服务器。

工具这边现在最值得关注的是 MCP：n8n 提供 MCP Client 节点，可以一键把一个 MCP 服务器注册成 Agent 的工具，等于 Agent 的能力边界从内置节点扩展到了整个 MCP 生态。官方还有人工审批的流程示例，让 Agent 在执行敏感工具前停下来等人点确认，跑自动化时这个设计比想象中重要。

版本边界说清楚，免得踩坑：

• 官方从 1.82 起弃用了 AI Agent 节点的 agent type 选择，所有 Agent 现在统一按 Tools Agent 模式工作；老版本节点（带类型选择那种 v1 形态）会在 3.0 被移除，自托管升级前记得看官方更新说明；
• AI Agent 节点必须至少连一个 Tool 子节点才能跑，光挂个模型不挂工具会报错；
• 云端套餐里送的 AI 额度、AI Assistant 是 Cloud 的功能，自托管没有这层额度体系，模型费用全部走你自己的 API Key；自托管要开实例级 AI Assistant 需要额外部署官方沙箱服务栈，生产环境官方目前推荐 Daytona 方案，属于进阶玩法，这篇教程先不展开。

想系统了解可以看官方Integrate AI 文档和AI Agent 节点说明。想对比模型 API 自托管接入方案的话，我写过一篇 DeepSeek 调用指南，模型选择和 API 接入的口径可以互相参考：DeepSeek 调用与工作流搭配指南。我的总体感受是：自托管 n8n 的 AI 上限取决于你愿意接多少工具、模型选什么，下限取决于你自己的运维水平——模型 Key 泄露、工具权限过宽这些风险，在自托管环境里没有厂商帮你兜底。

安全与维护：Webhook 鉴权、备份、升级

Webhook 鉴权：别把裸 URL 当安全

Webhook 的生产 URL 一旦激活就是公网可访问的，任何拿到 URL 的人都能往你的流程里推数据。默认路径是随机字符串，但随机不是安全。官方 Webhook 节点支持四种鉴权方式：Basic auth、Header auth、JWT auth，或者不鉴权。接外部服务时至少选 Header auth：在 n8n 里给 Webhook 节点配一组 Webhook 凭证（自定义 Header 名和值），外部请求带上这个头才放行。想再收紧的话，官方安全文档里还有几件顺手能做的事：不用公共 API 就关掉它、开启 SSRF 防护、给账号开 2FA、关掉遥测上报。

备份：SQLite 在线备份，不停机

本文用的是 SQLite 单容器，备份不需要停服务。网上很多教程教你先 docker compose stop 再拷文件，那是停机备份，日常备份别这么干。SQLite 自带在线备份接口，实例跑着就能安全地导出一致快照，写入繁忙时它会自己排队等锁。步骤：

# 第一步：确认容器里数据目录的实际文件名（通常是 database.sqlite，以 ls 为准）
docker compose exec n8n ls -la /home/node/.n8n

# 第二步：找到数据卷在宿主机上的挂载点
docker volume ls | grep n8n_data
docker volume inspect 上面查到的卷名 --format '{{ .Mountpoint }}'

# 第三步：宿主机装 sqlite3（Debian/Ubuntu）
sudo apt install -y sqlite3

# 第四步：在线备份，实例全程不停
sqlite3 /var/lib/docker/volumes/你的卷名/_data/database.sqlite \
  ".backup '$HOME/n8n-backup-$(date +%F).sqlite'"

# 第五步：校验备份文件完整性
sqlite3 ~/n8n-backup-2026-09-03.sqlite "PRAGMA integrity_check;"

卷的实际名字取决于你 compose 目录的名字，一般是“目录名_n8n_data”，用 docker volume ls 查实再填。除了数据库，还要保住两样东西：一是 .env 里的 N8N_ENCRYPTION_KEY（我们已经显式写出来了，备份 .env 即可）；二是数据卷里除数据库外的其他文件（比如二进制文件、配置）。想省事可以定期把整个卷打成 tar：

docker run --rm -v 你的卷名:/data -v $HOME/n8n-backups:/backup \
  alpine tar czf /backup/n8n-volume-$(date +%F).tar.gz /data

恢复是停机操作，别在实例运行时覆盖数据库：docker compose down，把备份文件拷回挂载点覆盖 database.sqlite（原文件先改名留底），再 docker compose up -d。恢复后打不开凭证，先检查 .env 的加密密钥和备份时是否一致。

升级：每月一次，先备份再看更新说明

官方建议至少每个月升一次，避免一次跨太多版本；升级前先看 Release Notes 里的 breaking changes。Compose 部署的官方升级序列是：

docker compose pull
docker compose down
docker compose up -d

先跑一遍上面的备份再执行。docker compose down 会停掉并移除旧容器，但数据卷原样保留，不用担心数据被删。升级后打开页面确认登录和几个关键流程都正常，再算完成。如果你在 1.x 老版本上想直升 2.x，务必先看官方迁移说明，跨大版本不是简单 pull 就能了事。

常见坑：内存、时区、许可证边界

• 定时任务时间不对：八成是 GENERIC_TIMEZONE 没设，官方默认 America/New_York。检查 .env 里有没有 Asia/Shanghai，改完 docker compose up -d 重建容器生效；
• 内存被打满：n8n 官方文档明说它不限制单节点能拉多少数据，Code 节点处理大数组、手动执行（前端会复制一份数据）、多个流程并发，都是内存大户。报错长这样：“Execution stopped at this node (n8n may have run out of memory while executing it)”。Docker 版遇到 OOM 会自动重启，但正在跑的流程会断。对策是给机器加内存，或者把数据处理拆成小块分批跑；
• 忘了 N8N_WEBHOOK_URL 和 N8N_PROXY_HOPS：症状是编辑器里显示的 Webhook 地址是 http://127.0.0.1:5678 开头的内网地址，外部服务注册了也调不通。反代部署这两行必设，官方反代配置页专门写了一段讲这个；
• 大 Webhook 被静默拒收：Nginx 默认只收 1MB 请求体，n8n 默认上限是 16MB。如果你改了 n8n 的 N8N_PAYLOAD_SIZE_MAX，Nginx 的 client_max_body_size 要跟着改，两边的口子要一样大；
• 许可证边界搞混：社区版免费、不限用户数和工作流数，但项目共享、SSO、Git 版本控制、环境管理、外部密钥存储这些是付费功能（自托管 Business 起或云端对应档位）。个人单用户基本无感，团队协作前先对表。另外免费注册一下邮箱能拿到 Registered Community 的免费许可，文件夹、编辑器内调试这些功能就能用了，注册入口在设置里的 Usage and plan；
• 把 5678 暴露到公网：端口映射写成 0.0.0.0:5678:5678 等于把没加密的管理界面直接挂网上。照本文绑 127.0.0.1，让 Nginx 管 TLS。

常见问题

n8n 自托管真的免费吗？社区版少了什么？

免费。社区版包含几乎全部功能，不限用户数和工作流数，代码节点、公共 API、队列模式都在。不含的是：项目/共享、SSO（SAML/LDAP）、Git 版本控制、环境管理、外部密钥存储、日志流、多主模式这些偏团队和企业的功能。个人自用基本碰不到付费墙。

要什么配置的 VPS？1GB 内存的小鸡能跑吗？

官方对完整 Compose（含 AI 沙箱）的书面要求是至少 4GB 内存和 2 核 CPU。本文的 sqlite 单容器最小配置要轻得多，2GB 内存日常够用，但我没有在 1GB 机器上长期跑过，给不出承诺。买机器建议按官方数字往上走，VPS 选购的详细对比可以看我的选购指南。

Webhook 被陌生人调用怎么办？

给 Webhook 节点配鉴权凭证：官方支持 Basic auth、Header auth、JWT auth 三种，接外部服务推荐 Header auth，自定义一个只有你和调用方知道的 Header。URL 的随机路径只是防扫描，不是安全措施。

升级会不会丢工作流和数据？

正常升级不会，数据库在数据卷里，docker compose down 不碰卷。但升级前务必先备份，并看官方 Release Notes 有没有 breaking changes；跨大版本（1.x 到 2.x）尤其要读迁移说明。

为什么我的 Cron 触发的时间不对？

因为官方默认时区是 America/New_York。在 .env 里设 GENERIC_TIMEZONE=Asia/Shanghai 并重建容器，所有定时节点立刻按北京时间跑。

n8n 和 Zapier、Make 比，价格到底谁便宜？

口径不同：Zapier/Make 按任务数（操作数）计费，流程越长单次运行烧得越多；n8n 按执行次数计费，步骤不限。同一条多步骤流程，n8n 云端通常更省，自托管则完全没有执行费用，只有服务器成本。但要把自己维护服务器的时间算进成本里，时间也是钱。

听说 n8n 3.0 之后不能 npm 安装了？

官方已明确：从 3.0 起 n8n 只通过 Docker 分发，npm 方式不再提供新安装。这也意味着 Docker/Compose 路线就是官方标准安装方式，现在照着本文学 Docker 部署不算走弯路。

最后交代一下维护预期：自托管 n8n 是典型的“省了订阅费，交了维护费”。每周有新版本、每月要抽十分钟升级、出问题要自己看日志。如果你觉得这些都不叫事，那这套方案能给你省下真金白银；如果你看到“自己维护”四个字就头疼，直接买官方云，把时间花在搭流程上更值。文章里的价格和版本号会过时，我会随官方页面更新，你发现对不上时以 n8n.io/pricing 和官方文档为准。