这是「Docker 好项目」系列的第 19 期。前 18 期我们把一堆服务一个个搬回了自己服务器:监控有 Uptime Kuma(第 1 期)、文档有 Paperless-ngx(第 14 期)、RSS 有 Miniflux(第 12 期)、网页变更监测有 changedetection.io(第 9 期)、推送通道有 ntfy(第 13 期)。东西是全了,但很快会发现一个尴尬的事实:这些服务彼此不认识。Paperless-ngx 收到一张新发票,想推一条消息到手机,得自己写脚本轮询它的 API;changedetection.io 盯的价格降了,想顺手把降价的商品抓下来写进一个表格,它只会给你发个通知,不会替你干活。每个服务都有自己的 API,可是"把 A 的数据搬给 B"这件事,最后全都变成了躺在 crontab 里的一次性脚本。n8n 就是来收这个尾的——它把四百多个服务的 API 做成了一个个"节点",你在一张画布上把它们连起来,剩下的判断、重试、定时、错误处理,它替你管。

n8n 效果图

痛点开场

先说一个真实场景:你用第 14 期的 Paperless-ngx 归档发票,用第 13 期的 ntfy 收推送。你想做到"新发票进来自动归类,金额超过一千块就推手机提醒"。拆开看,每一步都有现成能力——Paperless-ngx 有 webhook,ntfy 有 HTTP 接口——但中间那根"线"得你自己拉:

  • 写一次性脚本。curl 拿数据、Python 处理、再 curl 发出去,塞进 crontab。跑两周后需求变了,脚本没人敢动
  • 错误没人管。脚本半夜挂了,第二天你根本不知道。没有重试、没有记录、没有告警
  • 换一个服务就重写一遍。同样一套"拉数据 → 处理 → 发通知"的逻辑,对着 Immich 写一遍,对着 Gitea 又写一遍
  • 不会写代码的家庭成员完全无法参与。你想让"每天早上把昨天的订单汇总发到微信群",最后还是你自己写脚本

现成方案也分两派:Zapier / Make 这类云平台好用,但数据要过别人的服务器,价格按任务数涨,自托管党的信条就是不能接受这个;Huginn 这类老牌开源替代太老,Ruby 技术栈,节点生态基本停滞。n8n 是"云平台的体验 + 自托管的数据"两条都占的那个:画布式编辑器拖节点连线,四百多个现成集成,数据全程不出去,2025 年 12 月发布 2.0 之后迭代速度还非常猛——我写这篇文章时它的最新版本是 2.41.6,发布于 2026-10-02,前一天还在推代码,GitHub 上 20 万+ star。

名字顺带说一下:n8n 是 "nodemation" 的缩写,读作 "n-eight-n"——n 加上 nodemation 中间的八个字母,这是官方 README 里的说法。

能力边界

能干什么

  • 画布式工作流:拖节点、连线、看数据在节点之间流动,调试时每个节点可以单步看输入输出
  • 400+ 现成集成:HTTP 请求、Webhook、定时触发、邮件、各数据库,以及 Slack、Telegram、飞书、钉钉、飞书多维表格这些国内常用的都有官方节点
  • 触发器丰富:定时(Schedule Trigger)、Webhook、队列消息、文件变化,还有 Error Trigger(别的流程失败时触发)
  • 代码节点:JavaScript 和 Python 都能写(Python 走内置任务运行器),不想拖节点时一段代码解决
  • AI 原生:内置 LangChain 系节点,可以接 OpenAI / Ollama 之类搭 AI Agent 流程,这是它这两年最出圈的能力
  • 凭据管理:API key 存一次,所有节点复用,静态加密存储(这就是下面要反复强调的那个加密密钥)
  • 执行历史:每次跑都记数据,失败可以单节点重跑,不用从头来
  • Public API + MCP:自带 REST API(/api/v1/,带 Swagger 文档),2.x 还内置了 MCP server,AI 编程助手可以直接调你的工作流
  • PostgreSQL 支持:SQLite 默认够用,量大了切 Postgres,配置文件不用大改

不干什么

  • 它不是监控告警工具。服务挂没挂这件事归第 1 期 Uptime Kuma 管,n8n 适合做"发现问题之后的一连串动作"
  • 它不是给外人用的表单/应用平台。虽然有 Form Trigger,但定位是流程的一环,不是产品
  • 许可证不是 OSI 开源。n8n 用的是 Sustainable Use License(fair-code):自己用(个人、非商业、公司内部业务)完全免费,可以改、可以自部署,但不能把它包装成收费服务卖给外界。源码里带 .ee. 后缀的文件是 enterprise 代码,需要企业授权。自己用不用纠结,想拿它创业卖 SaaS 才需要看 license
  • 界面默认英文。N8N_DEFAULT_LOCALE 默认 en,而且我看了一下 2.41.6 的源码,语言包目录里只带了 en.json 一个文件——别信老教程里"设成 zh 就中文化"的说法
  • 队列模式要加东西。单机 SQLite 单容器是它的舒适区;要多实例高并发,就得 Postgres + Redis + worker 容器,复杂度上一个台阶
  • 吃内存。1Panel 商店给它的最低内存要求是 1024 MB,实际跑起来空载大概两三百 MB,跑重工作流(尤其 AI 节点)会明显上浮,2G 小内存的机器要先掂量

一句话:n8n 是"把你已经有的服务串起来的那根线",不是又一个数据服务。

部署前准备

  1. 一台跑着 Docker 的机器。1 核 2G 起步能跑,内存越宽裕越舒服;跟其他服务放同一台机器完全没问题
  2. 想清楚第一个自动化场景。n8n 的学习曲线在"节点太多不知道从哪开始",建议第一个流程就选一个两三步的:比如"每天早上九点抓一个 RSS 源(第 12 期 Miniflux)→ 过滤关键词 → 用第 13 期 ntfy 推到手机"
  3. 想好访问方式。只在局域网用,HTTP 直连就行;要从外网触发 webhook(比如让 changedetection.io 回调你),就得配域名和反代,见后面"反向代理与 HTTPS"
  4. 镜像源:官方主 registry 是 docker.n8n.io/n8nio/n8n(n8n 自建的 registry,我从这台机器实测可达);Docker Hub 上同名 n8nio/n8n 也能拉。国内拉不动官方源就走 Docker Hub,或者用 1Panel 自带的镜像加速

关于 tag,我实测了一遍(2026-10-03,官方最新 release 2.41.6):

tag 结果
2 404,不存在
2.41 404,不存在
2.41.6 200
latest 200,与 2.41.6 的 manifest 完全相同
stable 200,与 2.41.6 完全相同
2.40 404(对照组:上一个小版本同样没有滚动 tag)
2.40.0 200(对照组:全量版本号存在)
next 存在,但官方明确标注是不稳定通道

结论比往期都干脆:n8n 没有滚动次版本 tag,2 和 2.41 都不存在,必须钉全量版本号 2.41.6。另外两个别碰的写法:next 是滚动开发版;带 -pc 后缀的(比如 2.36.0-pc)是官方文档里写明的 n8n Cloud 内部变体,"不提供任何支持或稳定性保证"。

架构上 amd64 和 arm64 都有官方镜像,NAS 上也能跑。

docker run 一行版

mkdir -p /opt/n8n/data

docker run -d \
  --name n8n \
  --restart unless-stopped \
  -p 5678:5678 \
  -v /opt/n8n/data:/home/node/.n8n \
  -e TZ=Asia/Shanghai \
  -e GENERIC_TIMEZONE=Asia/Shanghai \
  -e N8N_SECURE_COOKIE=false \
  docker.n8n.io/n8nio/n8n:2.41.6

三个必须解释的地方:

  • /home/node/.n8n 是唯一要持久化的目录。官方镜像里工作流、凭据、执行历史、加密密钥全在这里(SQLite 模式下数据库也在里面)。注意镜像以 node 用户运行、不是 root——这是 Dockerfile 里 USER node 写死的。用 bind mount 时宿主目录的属主要跟容器里 node 用户的 UID 一致,不确定就先跑 docker run --rm --entrypoint id docker.n8n.io/n8nio/n8n:2.41.6 node 看一眼,或者干脆用命名卷(n8n_data:/home/node/.n8n)让 Docker 自己处理权限,最省事
  • GENERIC_TIMEZONE 和 TZ 要同时设。这是 n8n 的一个经典坑:GENERIC_TIMEZONE 管调度(Schedule Trigger 按哪个时区算"每天早上九点"),TZ 管系统输出(日志时间戳、Code 节点里 date 命令的结果)。只设一个就会出现"定时任务晚八个小时跑,日志时间却是对的"这种精神分裂现象。GENERIC_TIMEZONE 不设的话默认值是 America/New_York——我从源码里确认过,不是乱猜
  • N8N_SECURE_COOKIE=false 只在 HTTP 裸访问时需要。它默认是 true,意思是登录 cookie 带 Secure 标志——Secure cookie 在 HTTP 页面上会被浏览器直接丢弃,所以你用 http://IP:5678 访问时会发现登录不进去。反代上 HTTPS 之后要改回 true(见后面反代章节)

docker-compose 推荐版

services:
  n8n:
    image: docker.n8n.io/n8nio/n8n:2.41.6
    container_name: n8n
    restart: unless-stopped
    ports:
      - "5678:5678"
    volumes:
      - ./data:/home/node/.n8n
    environment:
      # —— 时区:两个都要 ——
      - TZ=Asia/Shanghai
      - GENERIC_TIMEZONE=Asia/Shanghai
      # —— 访问与安全 ——
      - N8N_SECURE_COOKIE=false            # 局域网 HTTP 访问用;上 HTTPS 后改回 true
      - N8N_PROXY_HOPS=0                   # 前面有几层反代就填几,走 NPM 反代后填 1
      # —— 隐私:关掉遥测(默认是开着的)——
      - N8N_DIAGNOSTICS_ENABLED=false
      - N8N_VERSION_NOTIFICATIONS_ENABLED=false
      - N8N_TEMPLATES_ENABLED=false
      # —— 数据治理:执行记录别让它无限堆 ——
      - EXECUTIONS_DATA_MAX_AGE=168        # 只保留 7 天(默认 336h = 14 天)
      - EXECUTIONS_DATA_PRUNE_MAX_COUNT=5000   # 最多留 5000 条(默认 10000)
      - N8N_PAYLOAD_SIZE_MAX=32            # webhook 请求体上限,默认 16MB,按需调
    healthcheck:
      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:5678/healthz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 60s

和官方示例相比,我改了这几处:

  • 镜像钉全量 2.41.6,理由前面说了:n8n 不发次版本 tag,写 2.41 直接拉不下来
  • 加了 healthcheck。官方镜像没有内置 HEALTHCHECK(我从镜像 config 里确认的),而 n8n 恰恰是最该被监控的服务——所有自动化都指着它。健康端点是 /healthz,我用 node -e fetch(...) 而不是 curl,因为镜像里不一定有 curl,但 node 一定有(这镜像本身就是 node 跑的)
  • 显式关掉三样对外请求:N8N_DIAGNOSTICS_ENABLED(匿名遥测,默认发数据到 telemetry.n8n.io 和 PostHog)、N8N_VERSION_NOTIFICATIONS_ENABLED(启动时查更新,请求 api.n8n.io)、N8N_TEMPLATES_ENABLED(工作流模板市场)。自托管图的就是数据不出门,这三个默认值都是开的,服务器在国外网络没问题,但国内机器上它们还拖慢启动
  • 执行记录收敛。n8n 默认保留 14 天 / 10000 条执行数据,每次执行的每个节点的输入输出都存 SQLite。工作流一多,数据库涨得飞快,SQLite 膨胀到几个 G 之后性能肉眼可见地往下掉。个人用 7 天 / 5000 条足够排障

配置项逐项解释

n8n 的环境变量非常多(官方文档专门有一大节),下面这张表是我从 2.41.6 源码里逐个核过默认值的、个人部署最常用的那些:

环境变量 默认值 说明与"为什么"
N8N_PORT 5678 容器内监听端口。配合 N8N_LISTEN_ADDRESS(默认 :: 双栈)。一般不动它,改宿主映射就行
N8N_HOST localhost 对外显示用的主机名。影响编辑器里拼出来的 webhook 预览地址。反代场景要填你的域名
N8N_PROTOCOL http 对外协议。反代 + HTTPS 后填 https
N8N_EDITOR_BASE_URL 空 编辑器的完整对外地址(如 https://n8n.example.com/)。设置后会用于邮件里的链接
N8N_WEBHOOK_URL 空 webhook 的完整对外基地址。这是 n8n 2.x 的新变量,官方注释明确写着它是"已废弃的 WEBHOOK_URL 的继任者"——网上老教程还在写 WEBHOOK_URL,能用但已经是要淘汰的写法。设了它,编辑器里给你的 webhook URL 才会是公网域名而不是 http://localhost:5678
N8N_SECURE_COOKIE true 登录 cookie 是否带 Secure。HTTPS 部署保持 true;HTTP 直连必须 false,否则永远登录不上
N8N_SAMESITE_COOKIE lax cookie 的 SameSite 属性,可选 strict / lax / none。一般不动
N8N_PROXY_HOPS 0 n8n 前面有几层反向代理。填了它 n8n 才会信任 X-Forwarded-For 头,否则所有访问都被当成来自反代的 IP
N8N_ENCRYPTION_KEY 空 凭据加密密钥。不设则首次启动自动生成,写进数据目录的 config 文件。这是整个 n8n 最要命的一个配置,单独讲,见下一节
N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS true 强制把 config 文件权限收到 600。2.0 起默认开启,多一层保险,别关
N8N_USER_FOLDER $HOME 数据根目录,.n8n 会拼在它后面。容器里 HOME 是 /home/node,所以数据在 /home/node/.n8n。一般不改
GENERIC_TIMEZONE America/New_York 调度时区。不改的话你的"每天 9 点"会在纽约时间 9 点跑
EXECUTIONS_TIMEOUT -1 单次执行超时(秒)。默认不限,EXECUTIONS_TIMEOUT_MAX 上限 3600。个人服务器建议设个 600 之类,防止一个写死的循环把机器拖死
EXECUTIONS_MODE regular regular 单机跑 / queue 队列模式(要 Redis + worker)。个人部署不用碰
N8N_PAYLOAD_SIZE_MAX 16 API/webhook 请求体上限(MB)。要传大文件调这个,同时反代的 client_max_body_size 也得跟着放
N8N_METRICS false 开了才有 /metrics(Prometheus 格式,前缀 n8n_)。要接监控再开,注意它不带鉴权,开了就要在反代层挡住
N8N_PUBLIC_API_DISABLED false Public API(/api/v1/)默认开着,Swagger UI 也默认提供。不用 API 又想收攻击面可以设 true
NODES_EXCLUDE executeCommand、localFileTrigger 2.0 起默认禁用这两个能碰宿主机文件/命令的节点。这是官方的安全默认,不建议为了方便改开
N8N_RUNNERS_MODE internal Code 节点的代码在哪跑:internal 是主进程的子进程(默认,开箱即用);external 是独立容器(官方为隔离代码执行推的方案,企业场景再考虑)

还有两个"声明式"的变量值得知道,因为它们解决了"第一次部署不想点界面"的问题:

  • N8N_INSTANCE_OWNER_MANAGED_BY_ENV=true + N8N_INSTANCE_OWNER_EMAIL + N8N_INSTANCE_OWNER_PASSWORD_HASH:用环境变量直接创建管理员。注意 PASSWORD_HASH 必须是 bcrypt 哈希($2b$ 开头那串),源码里写得很直白:"提供明文密码会直接得到一个无法登录的账号"
  • N8N_COMMUNITY_PACKAGES_MANAGED_BY_ENV + N8N_COMMUNITY_PACKAGES:用 JSON 声明要装哪些社区节点,启动时自动对齐。适合把部署做成代码

数据目录与加密密钥:这一节最好背下来

/home/node/.n8n 里大概长这样:

/home/node/.n8n/
├── database.sqlite        # 工作流、凭据、执行记录(SQLite 模式)
├── config                 # 加密密钥就在这个文件里!
├── binaryData/            # 二进制数据(2.0 起必须落盘,memory 模式已移除)
├── nodes/                 # 社区节点
└── custom/                # 自定义扩展

config 这个文件比数据库还重要。它存着加密密钥,所有凭据(你在界面上填的 API key、密码)都是用它加密后才进数据库的。官方 README 原话是:如果启动时找不到这份数据,n8n 会自动生成一个新密钥,而已有凭据将全部无法解密。

由此推出三条铁律:

  1. 备份必须连 config 一起备。只备 SQLite 文件没有用,恢复出来的是一堆解不开的密文
  2. 换机器迁移 = 数据目录整个搬走。数据库、config、binaryData 一个都不能少
  3. 想让密钥可控,就显式设 N8N_ENCRYPTION_KEY。可以明文写在环境变量里,也可以用 N8N_ENCRYPTION_KEY_FILE 指向一个挂载的文件(配合 Docker secret 更干净)。注意两边只能有一份真相——环境变量和数据目录里的密钥不一致时,n8n 会直接报 "Mismatching encryption keys" 拒绝工作,这是好事,说明它没拿旧密钥硬解

另外 N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS 默认开着,n8n 启动时发现 config 权限太宽会自动收紧到 600。如果你看到日志里有 "Permissions xxx are too wide" 的提示,不是故障,是它在替你补刀。

1Panel 面板怎么搞

1Panel 应用商店里有 n8n(归在 AI 分类,推荐指数 330,最低内存 1024 MB,amd64/arm64 都支持)。我拉了商店的编排源码看了下,几个关键点:

  • 商店目前带的版本是 2.41.3,官方最新是 2.41.6,落后 3 个 patch——差距不大,追新党可以自己改 compose 里的镜像 tag
  • 端口表单默认 5678,映射到容器 5678
  • 数据卷是 ./data:/home/node/.n8n,也就是落在 /opt/1panel/apps/n8n/n8n/data/
  • 预设环境变量只有一个:N8N_SECURE_COOKIE=false——商店假定你先用 HTTP 访问,这个默认是合理的,但上 HTTPS 之后记得改回 true

安装路径:应用商店 → 搜 n8n → 填端口 → 安装。装完之后想加环境变量,去 容器 → 编排,打开 /opt/1panel/apps/n8n/n8n/docker-compose.yml,在 environment 段里加(比如时区那两条),然后重建容器:

cd /opt/1panel/apps/n8n/n8n
docker compose up -d --force-recreate

两个提醒:

  • 商店版的编排没有挂时区环境变量,GENERIC_TIMEZONE 和 TZ 都要自己补,否则定时任务全按纽约时间跑
  • 商店版没有配 healthcheck,原因跟上面一样:官方镜像本身就没有。在意的话把推荐 compose 里那段 healthcheck 抄进去

如果你更愿意手动部署(不打应用商店),直接用上面的推荐 compose 建一个"容器 → 编排"就行,1Panel 会接管它的启停和日志。

首次访问

浏览器打开 http://<服务器IP>:5678,第一次会先进入 Set up owner account 页面:填邮箱、名、姓、密码,这就是管理员账号。提交后 n8n 会问你要不要填 license key——直接跳过(Skip),免费版功能完全够个人用,不填也不影响任何自动化能力。

进去之后就是那个标志性的画布界面:左边节点列表,中间画布,右上角 Inactive/Active 开关。官方仓库里那张经典示意图长这样:

n8n 编辑器画布

第一次上手建议别从空白开始:左侧 Templates 里官方维护着九百多个现成工作流模板(注意:模板列表数据来自 api.n8n.io,我在推荐 compose 里关了 N8N_TEMPLATES_ENABLED,想用模板服务就把这个开关临时打开,或者直接去 n8n.io/workflows 网页上抄 JSON 再导入)。

最小可用配置

十分钟跑通第一个流程,感受一下"节点连线"是怎么回事:

  1. 建凭据。左侧 Credentials → Add credential,先挑一个你已经有 key 的服务(比如 ntfy 填个 URL 就行,甚至不需要凭据)
  2. 拖一个 Schedule Trigger。设成每天早上 9 点——如果你按前面配了 GENERIC_TIMEZONE=Asia/Shanghai,它就是北京时间 9 点
  3. 加一个 HTTP Request 节点。比如请求你第 12 期 Miniflux 的 /v1/entries,或者任何一个公开 API。n8n 的 HTTP 节点强大到很多没有官方集成的服务,用它就够了
  4. 加一个 ntfy 节点(或 HTTP POST)。把上一步拿到的数据挑几个字段填进消息体
  5. 点 Execute workflow 手动跑一遍,看数据在节点之间的流动。没问题后把右上角开关拨到 Active,它就定时跑了

这一套下来你就有了第一条"每天自动干活"的流水线。第二个流程可以试试:Webhook Trigger + Respond to Webhook,把它当成一个可以对外提供的小 API——第 9 期 changedetection.io 的通知、第 1 期 Uptime Kuma 的告警都能直接回调它,进 n8n 之后想干嘛就干嘛(写表格、发邮件、查库存、调 AI 总结),这就是系列里那期 ntfy 说的"把通知通道变成自动化入口"的完整版。

告警/通知配置

n8n 在这个系列里的身份很特殊:往期项目是"怎么把告警发出去",n8n 是"告警进来之后怎么处理"。但它自己作为基础设施,也有两件事要配:

第一,n8n 自己挂了要知道。 靠 /healthz(官方支持自定义路径,默认就是它)接第 1 期 Uptime Kuma:

  • Uptime Kuma → Add New Monitor → HTTP(s),URL 填 http://<IP>:5678/healthz
  • 通知渠道选第 13 期 ntfy,挂了就推手机

第二,工作流跑失败了要知道。 三条路,按省事程度排:

  1. Error Workflow:Settings 里可以指定一个"错误工作流",任何工作流失败都会触发它。在里面接一个 ntfy 节点,把出错的工作流名、错误信息推出去。配一次,全站生效,个人部署选这条
  2. 邮件通知:设 N8N_EMAIL_MODE=smtp 加一组 N8N_SMTP_HOST / N8N_SMTP_PORT(默认 465)/ N8N_SMTP_USER / N8N_SMTP_PASS,n8n 会发"工作流失败"邮件(模板可以用 N8N_UM_EMAIL_TEMPLATES_WORKFLOW_FAILURE 覆盖)
  3. Prometheus 指标:N8N_METRICS=true 暴露执行成败计数,适合已经有监控栈的人

顺带一提执行历史的保留策略前面已经配了(7 天 / 5000 条),这既是省磁盘也是告警之外的兜底——排查"昨晚那条流程为什么没跑"时,执行记录就是黑匣子。

反向代理与 HTTPS

要在公网触发 webhook、或者在外面打开编辑器,就必须上 HTTPS——编辑器里全是你的凭据和业务数据,裸 HTTP 过公网等于把钥匙挂门上。用第 2 期的 NPM 举最短路径:

  1. Proxy Hosts → Add Proxy Host:Domain 填 n8n.example.com,Forward Hostname 填 n8n(同 Docker 网络用容器名),Forward Port 填 5678
  2. 勾上 Websockets Support。n8n 2.x 编辑器的实时推送默认走 WebSocket(N8N_PUSH_BACKEND 默认值已经是 websocket,老教程里写的 sse 是旧默认),不勾的话画布上的执行状态不会实时刷新
  3. SSL 标签页申请证书,勾 Force HTTPS

然后回 compose 改四个环境变量并重建:

environment:
  - N8N_SECURE_COOKIE=true                # HTTPS 了,cookie 该带 Secure 了
  - N8N_PROTOCOL=https
  - N8N_HOST=n8n.example.com
  - N8N_WEBHOOK_URL=https://n8n.example.com/
  - N8N_PROXY_HOPS=1                      # n8n 前面现在有一层 NPM

三个容易漏的细节:

  • N8N_WEBHOOK_URL 结尾带斜杠。n8n 拿它拼 webhook 完整地址,写成 https://n8n.example.com(没斜杠)会拼出 https://n8n.example.comwebhook/xxx 这种残废 URL。设完之后在编辑器里点开一个 Webhook 节点,看它给的 Test URL 对不对,一眼就能验证
  • 请求体大小两头都要放。n8n 默认 16MB(N8N_PAYLOAD_SIZE_MAX),Nginx 默认 1MB——不调 client_max_body_size,传稍大的文件第一个报错的反而是反代
  • 1Panel 的反代默认透传上游响应头,n8n 自己会发 CSP 相关的头(2.x 默认发 Report-Only 策略),所以不要在站点配置里手动加 add_header Content-Security-Policy 之类——第 16 期 Actual Budget 就是栽在"代理层和上游各设一份安全头"上,浏览器会判定策略无效。1Panel 的站点反代片段在 /opt/1panel/www/sites/<域名>/proxy/root.conf,需要微调 WebSocket 时改这里

改完做个验证:curl -I https://n8n.example.com/healthz 返回 200,浏览器打开编辑器、拨动一个节点的执行开关能看到实时状态,就是通了。

踩坑清单

  • HTTP 访问一直登录不上。cookie 带 Secure 被浏览器丢了。确认 N8N_SECURE_COOKIE=false(HTTP 场景)。反过来,上了 HTTPS 之后记得改回 true,别让这个图省事的配置跟着你进公网
  • 定时任务总是晚八个小时。GENERIC_TIMEZONE 没设(默认 America/New_York),或者只设了 TZ 没设它。两个都设成 Asia/Shanghai
  • 换了容器/搬了机器,所有凭据报错。加密密钥丢了(config 文件不在了)或者跟数据库对不上。把整个 .n8n 目录一起迁;显式设 N8N_ENCRYPTION_KEY 就永远不会有这个问题
  • webhook 地址是 http://localhost:5678/...。N8N_WEBHOOK_URL(或老的 WEBHOOK_URL)没设。设成公网地址后,外部服务才回调得进来
  • webhook 测试一直 404。编辑器里手动点"Listen"时用的是 /webhook-test/... 路径,工作流激活后才是 /webhook/...。外部系统对接生产流程时用后者,别拿着测试 URL 就去配
  • 从 1.x 升到 2.x 之后行为变了。2.0(2025-12-08 发布)动了几个默认值,升级前值得过一眼官方 BREAKING-CHANGES 文档:ExecuteCommand 和 LocalFileTrigger 节点默认禁用(想用得自己改 NODES_EXCLUDE,但要想清楚风险);--tunnel 命令行参数没了(以前本地开发用它暴露 webhook,现在只能走反代);binary data 的 memory 模式没了(必须落盘);N8N_CONFIG_FILES 环境变量没了
  • SQLite 数据库越来越大。执行记录堆积。除了收敛保留天数,还可以在停机后做一次 DB_SQLITE_VACUUM_ON_STARTUP=true 的启动(这个变量默认 false,它是个阻塞操作,会拖慢启动,平时别开)
  • 内存不够。官方商店给的最低值是 1024 MB,跑 AI 节点或大 JSON 流转时往上加。机器吃紧就把 EXECUTIONS_DATA_PRUNE_MAX_COUNT 再调小,并避免在一条流程里搬运超大二进制
  • 官网上那个 get.n8n.io 一键安装脚本别直接用于生产。它拉的 compose 是一套完整的"沙箱栈":sandbox-api、一个特权容器跑 Docker-in-Docker 的代码执行沙箱、SearXNG、独立 runner——那是给企业隔离代码执行用的。个人服务器用本文的单容器 compose 就好,简单、可控、资源省
  • 升级前先备份。n8n 启动时会自动跑数据库迁移,迁移不保证能回滚。升级 = 停容器 → 拷走整个数据目录 → 换镜像 tag → 起容器

备份

SQLite 模式的备份很简单,但有一条铁律:整个数据目录一起备,config 一个字符都不能少。

# 1) 先停写(最稳是停容器;不停容器也可以,n8n 的 SQLite 打开了 WAL,直接 cp 有拿到不一致快照的小概率风险)
docker stop n8n

# 2) 整目录打包(包含 config、database.sqlite、binaryData)
tar czf /opt/backups/n8n-$(date +%Y%m%d).tar.gz -C /opt/n8n data

# 3) 起回来
docker start n8n

想要不停机备份,n8n 自带 CLI 可以导出纯数据(不含凭据明文,凭据导出的是密文):

# 导出全部工作流为 JSON
docker exec n8n n8n export:workflow --all --output=/home/node/.n8n/backups/workflows.json

# 导出全部凭据(密文,恢复时仍需同一个加密密钥)
docker exec n8n n8n export:credentials --all --output=/home/node/.n8n/backups/credentials.json

注意这两条命令输出的文件落在数据目录里(容器内路径),所以宿主机上在 /opt/n8n/data/backups/ 下能看到。恢复用对应的 n8n import:workflow / n8n import:credentials。

还有一条容易被忽略的:加密密钥要单独抄一份放进密码管理器(比如第 3 期的 Vaultwarden)。磁盘整块挂掉时,config 文件和备份包往往一起陪葬,密钥单独存在另一个地方才是真正的兜底。

小结

适合谁

  • 已经自托管了三五个以上服务的人——这是 n8n 价值最低的门槛。只有一个服务时写个 curl 脚本更快;有五个服务、十种"想串起来"的念头时,n8n 开始回本
  • 被 crontab 一次性脚本折磨过的人。有界面、有执行历史、失败能重跑、错误能推送,这些正是脚本最缺的
  • 想把 AI 能力接进现有流程的人。接 Ollama 或 OpenAI 做个"邮件自动摘要""工单自动分类",是 n8n 这两年最火的用法
  • 在乎数据不出门的人。相比 Zapier/Make,数据和凭据全在自己服务器上,license 也允许公司内部业务免费用
  • 这个系列的读者。它能把前 18 期里几乎所有带 API 的项目串成流水线:Miniflux 的新文章、changedetection.io 的变更、Uptime Kuma 的告警、Paperless-ngx 的 webhook、Gitea 的事件,全都可以成为 n8n 的触发源

不适合谁

  • 只想要"定时抓个网页推个通知"的人。第 9 期 changedetection.io + 第 13 期 ntfy 两个容器就解决了,不需要 n8n 这套画布
  • 内存只有 1G 的机器。跑是能跑,但和 Jellyfin、Immich 挤在一起时得掂量。官方商店的最低要求 1024 MB 是实话
  • 想拿它对外提供 SaaS 赚钱的人。Sustainable Use License 明确不允许——把它包装成收费服务卖给别人越线了,自用和公司内部业务没问题
  • 完全不想学新概念的人。节点、凭据、触发器、表达式这些概念虽然不难,但第一次接触总要花个把小时建立心智模型

在这个系列里的位置:如果说第 18 期的 Homepage 是"把所有服务收进一个页面"的收口,那 n8n 就是"把所有服务连进一条流水线"的收口。一个管看,一个管动。到这里,这个系列讲的自托管已经不再是"把云服务搬回家"这种一对一的替代,而是真的开始长出云服务给不了的东西——你的数据在你手里,而且它们会自己干活。

项目地址

  • GitHub:https://github.com/n8n-io/n8n
  • 官网:https://n8n.io
  • 官方文档:https://docs.n8n.io
  • 环境变量总表:https://docs.n8n.io/hosting/configuration/environment-variables/
  • 工作流模板库:https://n8n.io/workflows
  • 破坏性变更清单:https://github.com/n8n-io/n8n/blob/master/packages/cli/BREAKING-CHANGES.md
  • Docker 镜像:docker.n8n.io/n8nio/n8n(官方主源)/ n8nio/n8n(Docker Hub)
  • 一键安装脚本(企业沙箱栈,个人慎用):https://get.n8n.io