发布: · 最后更新:
摘要: 本文手把手讲 n8n 自托管:用 Docker Compose 把 n8n、PostgreSQL 和 Caddy(自动 HTTPS)跑起来,再做出第一个真正有用的自动化流程——定时检查网站,异常时推送到飞书群。本文以单机部署为起点;2 核 4 GB 仅为编辑建议的试用配置,稳定性仍需按实际工作流、并发和数据量验证。部署时重点核对 WEBHOOK_URL、加密密钥、时区和备份这四件事有没有一次配对。适合想把数据留在自己手里、想省掉云版订阅费、或需要接入内网系统的读者;按部署、首个流程、备份和升级的顺序逐步完成。
配套视频教程
n8n 自托管教程:Docker 部署与首个工作流|12分钟实战。12 分钟按本文顺序讲完部署、首个飞书告警流程与备份升级,可边看视频边对照下方步骤操作;章节时间点见视频教程页。
YouTube 视频
Bilibili 视频
核心结论
先确认具备 SSH、Docker 与域名配置基础,再按步骤部署;耗时取决于镜像拉取、网络、证书签发和排错情况,本文不承诺固定完成时间。实施路径是:用 Docker Compose 启动 n8n + PostgreSQL,服务器正式使用时再加一个 Caddy 自动申请 HTTPS 证书;部署完先手动运行一个“网站巡检 + 飞书告警”的小流程,确认触发、请求、判断、通知四个环节都通,再点 Publish 让它定时运行。
- 值不值得自托管:工作流多、执行频繁、需要访问内网或想完全掌控数据时值得;只跑三五个简单流程、不想维护服务器的话,云版更省心。
- 最关键的四个配置:
WEBHOOK_URL(决定外部回调地址)、N8N_ENCRYPTION_KEY(丢了凭证就解不开)、GENERIC_TIMEZONE(决定定时任务几点跑)、数据库备份。 - n8n 2.x 的新变化要注意:工作流改成“发布(Publish)”才生效;表达式和 Code 节点默认不能读取环境变量;错误工作流本身也必须发布,否则告警不会发出。
- 数据库建议直接用 PostgreSQL:官方镜像默认用 SQLite,单人试用没问题;准备长期使用、有多个工作流同时跑时,一开始就上 PostgreSQL,省得以后迁移。
- 实施建议:先在本机“本地试用”跑通,再上服务器;固定镜像版本号,升级前必须先备份数据库。
自托管 n8n 和云版怎么选
结论: 自托管省的是订阅费和数据边界,付出的是运维时间;先想清楚你更在意哪一个。
n8n 是一个可视化的工作流自动化工具,可以把“定时触发 → 调接口 → 判断 → 写表格 → 发通知”这类重复工作拖拽成流程。它有官方托管的云版,也允许你用 Docker 部署在自己的服务器上(社区版自托管)。两者的编辑器和节点基本一致,差别主要在谁来维护服务器、数据存放在哪里、能不能访问你的内网资源。
自托管的典型理由有三个。第一,数据边界:你可以控制 n8n 实例、数据库与执行记录的存放位置,但自托管不等于数据不会外发。工作流调用外部模型、飞书、邮箱或其他 SaaS 时,相关请求内容会发送到对应服务,具体取决于节点配置与服务的数据处理规则。本文网站巡检示例会向目标网站发送 HTTP 请求;触发告警时,会将配置的告警内容提交到飞书机器人接口。请仅发送必要的网站状态信息,勿将客户电话、凭据或完整接口返回写入通知。第二,内网访问:n8n 跑在你的服务器上,可以直接调用同一内网的数据库、ERP 或 NAS,而云版要访问内网就得额外开放端口或做隧道。第三,执行量大时的成本:自托管社区版按服务器资源付费,不按执行次数计费,适合每小时巡检、每天采集这类高频流程。
反过来,自托管意味着你要自己负责升级、备份、HTTPS 证书和安全加固。本文示例使用 n8n 2.41.6;选择升级版本时应查阅目标版本的发布说明,每次升级都可能带数据库迁移,没有备份就升级是最常见的事故来源。
n8n 2.x 相比 1.x 有几处会直接影响自托管的变化,老教程里很多没写:
- 编辑器里原来的“Active 开关”变成了 Publish(发布),工作流导入后默认未发布,定时和 Webhook 都不会生效;
- 代码执行改由 任务运行器(task runner) 处理,官方 Docker 文档里的
N8N_RUNNERS_ENABLED在 2.0 起已不再需要单独设置;n8n 2.41.6 启动时还会提示 internal 模式将来会被移除,建议规模化部署时改用 external 模式; - 表达式和 Code 节点默认禁止读取环境变量。我们在 2.41.6 的源码里确认:只有把
N8N_BLOCK_ENV_ACCESS_IN_NODE明确设为false才放行,这和部分文档描述的默认值不一致,以你实际运行的版本为准; - 官方 Docker Compose 示例新增了 AI 助手相关的沙箱和搜索组件,并提醒 PostgreSQL 18 改变了默认数据目录。本文的配置不包含这些可选的 AI 组件,数据库固定为 PostgreSQL 16。
下表是四种常见部署方式的对比,帮你先定方向:
手机上可左右滑动下表,查看完整对照内容。
| 部署方式 | 数据库 | HTTPS | 适合谁 | 主要代价 |
|---|---|---|---|---|
| n8n 云版 | 官方托管 | 自带 | 不想碰服务器、流程不多的个人和团队 | 按套餐与执行量付费,数据在官方云 |
Docker 单容器(官方 docker run 示例) |
SQLite(数据卷里的文件) | 需自己加反向代理 | 本机体验、学习节点用法 | 并发和数据量上来后不好迁移 |
| Docker Compose:n8n + PostgreSQL + Caddy(本文) | PostgreSQL 16 | Caddy 自动申请证书 | 长期使用的个人、小团队、自媒体和外包服务 | 需要一台服务器和一个域名,自己做备份与升级 |
| npm 直接安装 | SQLite 或 PostgreSQL | 需自己配置 | 开发调试、二次开发 | 需要 Node.js 24,n8n 2.41.6 已提示非容器运行方式将被弃用 |
如果你还在比较 n8n、Dify、Coze 这类工具,可以先看站内的 n8n 相关教程合集,再回来部署。
部署架构:三个容器各管什么
结论: 一个 docker-compose.yml 里放三个服务——PostgreSQL 存数据、n8n 跑流程、Caddy 管 HTTPS,n8n 的 5678 端口只对本机开放。
为什么这样分工:
- PostgreSQL:保存工作流、凭证(加密后)、执行记录和去重历史。n8n 官方文档说明可以通过
DB_TYPE=postgresdb和一组DB_POSTGRESDB_*变量切换到 PostgreSQL。我们给它加了健康检查,n8n 会等数据库就绪后才启动。 - n8n:编辑器和执行引擎在同一个容器里。数据卷
n8n_data挂到/home/node/.n8n,里面有一个保存加密密钥的配置文件;./local-files挂到/files,方便读写文件类节点使用。 - Caddy:放在
https档位(profile)里,本地试用时不启动;上服务器时加--profile https,它会自动为你的域名申请并续期证书,再把请求转发给 n8n。
端口只绑定 127.0.0.1:5678 是刻意的:公网访问一律经过 Caddy 的 443 端口,避免有人绕过 HTTPS 直接访问 5678。也正因为前面多了一层代理,.env 里要把 N8N_PROXY_HOPS 设为 1,让 n8n 正确识别客户端真实 IP 和协议。
这是 compose 文件中 n8n 服务的核心部分(完整文件在免费资料里):
n8n:
image: docker.n8n.io/n8nio/n8n:${N8N_VERSION:-2.41.6}
restart: unless-stopped
ports:
# 只绑定本机回环地址;公网访问一律走下面的 Caddy(HTTPS)
- "127.0.0.1:5678:5678"
environment:
# —— 数据库 ——
DB_TYPE: postgresdb
DB_POSTGRESDB_HOST: postgres
DB_POSTGRESDB_PORT: 5432
DB_POSTGRESDB_DATABASE: ${POSTGRES_DB}
DB_POSTGRESDB_USER: ${POSTGRES_USER}
DB_POSTGRESDB_PASSWORD: ${POSTGRES_PASSWORD}
Caddy 的配置只有几行,{$N8N_HOST} 会读取环境变量里的域名:
{$N8N_HOST} {
encode gzip
reverse_proxy n8n:5678
}
适用边界:这套架构是单机部署,本文未提供吞吐或容量压测。能承载多少次执行取决于节点耗时、并发、数据量和第三方限流,不能仅凭每日执行次数判断。需要多机横向扩展时,要改用 n8n 的队列模式(queue mode,配合 Redis 和多个 worker),那是另一套架构,本文不展开。
安装步骤:从零到能打开编辑器
结论: 本地试用只需要“复制模板 → 改两个密码 → 启动”三步;服务器正式使用多两步:解析域名、改 4 个访问地址变量。
下面以一台 Ubuntu 云服务器为例,Windows 和 macOS 本机试用时,用 Docker Desktop 执行同样的 docker compose 命令即可。
步骤 1:准备服务器和 Docker
个人或小团队试用,2 核 4 GB 内存、20 GB 以上磁盘起步较稳(编辑经验,按工作流数量和执行频率增减)。按 Docker 官方文档安装 Docker Engine 和 Compose v2 插件,然后确认版本:
docker compose version
步骤 2:校准服务器时间
定时触发、飞书机器人签名都依赖准确的时间,先确认 NTP 同步已开启:
timedatectl status
步骤 3:(服务器正式使用)解析域名并放行端口
在域名服务商把一条 A 记录(例如 n8n.你的域名)指向服务器公网 IP;在云厂商安全组和系统防火墙放行 80、443。不要放行 5678。
步骤 4:放好三个文件,复制 .env
把免费资料里的 docker-compose.yml、.env.example、Caddyfile 放到同一个目录(例如 /opt/n8n),然后:
cp .env.example .env && chmod 600 .env
步骤 5:生成两个随机值
数据库密码和加密密钥都不要手写:
openssl rand -base64 24
openssl rand -hex 32
第一个填 POSTGRES_PASSWORD,第二个填 N8N_ENCRYPTION_KEY,并把加密密钥另存到密码管理器。
步骤 6:按场景改访问地址
本地试用保持默认;服务器正式使用,把 .env 里这几行改成你的域名(模板中已经写好注释,取消注释即可):
# N8N_HOST=n8n.example.com
# N8N_PROTOCOL=https
# WEBHOOK_URL=https://n8n.example.com/
# N8N_PROXY_HOPS=1
步骤 7:检查配置并启动
先让 Compose 解析配置。--quiet 只进行配置校验而不打印结果;需要结合命令退出状态及警告判断是否通过。静态校验不能证明密码正确、镜像可拉取、数据库可连接或容器能启动,仍需继续做下一步运行验证。参见 Docker 官方 config 命令说明:
docker compose config --quiet
本地试用:
docker compose up -d
服务器正式使用(同时启动 Caddy):
docker compose --profile https up -d
步骤 8:验证
以下命令应在运行 Compose 的那台机器上、原项目目录中执行;远程服务器部署时,请在服务器的 SSH 终端执行。这里的 127.0.0.1 指执行命令的机器。依次确认容器状态、日志和两个健康检查接口:
docker compose ps
curl -s http://127.0.0.1:5678/healthz
curl -s http://127.0.0.1:5678/healthz/readiness
/healthz 只说明进程活着;/healthz/readiness 会检查数据库连接。首次启动时,进程存活与数据库就绪可能不同步,应等待迁移完成并分别检查两个接口。readiness 可作为数据库就绪检查之一,但不能代替公网 HTTPS、账号登录及工作流运行验收。
步骤 9:按部署位置打开编辑器并创建 Owner 账号
- Docker 运行在当前电脑:在同一台电脑的浏览器打开
http://localhost:5678。 - Docker 运行在远程服务器:完成域名解析、HTTPS 配置并启动 Caddy 后,在电脑浏览器打开
https://你的域名。电脑浏览器的localhost指电脑自身,不能直接访问远程服务器。 - 远程服务器尚未配置域名和 HTTPS:先完成步骤 3、6、7 的服务器配置。本文模板将 5678 绑定在服务器回环地址,直接访问公网 IP 或局域网 IP 的 5678 端口不属于本模板的访问路径。
确认访问的是自己的实例、远程访问证书有效后,再按提示创建首个 Owner 账号、设置强密码并开启两步验证。
出现 secure cookie 提示时,先核对访问协议、域名和反向代理配置;服务器部署应使用 HTTPS,并保持 N8N_SECURE_COOKIE=true。不要将关闭 cookie 保护或开放公网 5678 作为排错捷径。健康检查成功而域名仍打不开时,应继续检查 DNS、80/443 端口、Caddy 运行状态及证书签发情况,不能据此认定整个部署已通过验收。
关键环境变量逐个讲清楚
结论: 免费资料的 .env 只有十几个变量,但每一个都对应一个真实的坑,改之前先看懂它管什么。
手机上可左右滑动下表,查看完整对照内容。
| 变量 | 本文取值 | 作用 | 设错会怎样 |
|---|---|---|---|
N8N_HOST / N8N_PROTOCOL |
localhost+http 或 你的域名+https |
编辑器生成链接时使用的主机名和协议 | 页面里的链接、OAuth 回调地址不对 |
WEBHOOK_URL |
https://你的域名/ |
告诉 n8n 对外的 Webhook 前缀 | 编辑器里显示的回调地址变成 http://localhost:5678/…,外部系统调不进来 |
N8N_PROXY_HOPS |
有 Caddy 时为 1 | 信任几层反向代理(默认 0) | 识别不到真实协议和 IP,部分功能告警 |
N8N_ENCRYPTION_KEY |
64 位十六进制随机值 | 加密保存的凭证 | 与数据卷里已保存的不一致时 n8n 拒绝启动;丢失则凭证无法解密 |
N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS |
true |
强制配置文件权限为 600 | 不设时文件权限可能过宽(官方 Docker 示例也设为 true) |
N8N_SECURE_COOKIE |
true |
只通过 HTTPS 发送登录 cookie | 设成 false 后在公网上有会话被截获的风险 |
GENERIC_TIMEZONE / TZ |
Asia/Shanghai |
定时触发节点使用的时区 / 系统时区 | 定时任务差 8 小时 |
EXECUTIONS_DATA_MAX_AGE |
336(小时) | 执行记录保留时长 | 设太大数据库持续膨胀 |
EXECUTIONS_DATA_PRUNE_MAX_COUNT |
10000 | 执行记录最多保留条数 | 同上 |
N8N_VERSION |
2.41.6 |
固定镜像版本 | 用 latest 时可能在你不知情的情况下升级并迁移数据库 |
其中执行记录清理的两个默认值(开启清理、保留 336 小时、最多 10000 条)来自 n8n 2.41.6 源码中的配置默认值,我们在 compose 里显式写出来,方便你调整。
关于加密密钥,我们专门做了一个实验:先用一个密钥启动,再换一个不同的密钥启动,n8n 直接拒绝运行,报错为 “Mismatching encryption keys. The encryption key in the settings file … does not match the N8N_ENCRYPTION_KEY env var”。这说明两件事:第一,密钥一旦定下来就不要改;第二,重装服务器时,要连同 .env 一起恢复,而不是重新生成。
第一个自动化流程:网站巡检 + 飞书告警
结论: 免费模板包含 5 个节点:手动触发、定时触发、HTTP 请求、IF 判断和飞书通知,覆盖触发、请求、判断、通知四类操作。手动跑通、制造一次故障、再发布,三步走完你就掌握了 n8n 的基本用法。
我们选“网站巡检”作为第一个流程,原因是它几乎人人用得上,而且不需要申请任何 API Key,只要一个飞书群机器人。流程是:
- 手动运行 / 定时触发:手动入口用来测试,定时触发设为每 30 分钟一次(cron 表达式
*/30 * * * *); - 检查网站:HTTP Request 节点,GET 你的网址,打开“返回完整响应”和“不因错误状态码报错”,超时 10 秒,并把节点设置为出错时继续执行,这样连接失败也能进入下一步;
- 状态码不是 200?:IF 节点,左值
{{ $json.statusCode }},条件“不等于 200”; - 发到飞书群:只接在 IF 的“真”分支上,POST 到飞书自定义机器人地址,消息里带状态码、错误信息和时间。
操作步骤:
- 创建飞书群机器人。 在飞书群设置里添加“自定义机器人”,复制 Webhook 地址。安全设置建议选“自定义关键词”,关键词填“网站”(这个流程的消息一定以“网站异常”开头)。
- 导入流程。 在 n8n 编辑器右上角选择 Import from File,导入免费资料里的
first-workflow.json。 - 替换两个地址。 在“检查网站”节点把
https://YOUR_DOMAIN/换成你的网址,在“发到飞书群”节点把YOUR_TOKEN那段换成你的机器人地址。 - 手动运行。 点 Execute workflow,选择“手动运行”入口。网站正常时,IF 节点的 false 分支输出 1 条,飞书群不会收到消息——这是预期行为。
- 制造一次故障。 把网址改成一个不存在的路径或关闭的端口,再运行一次,飞书群应收到“网站异常:…”。测试至少覆盖三种情况:正常返回 200 时不告警、返回 503 时告警、连接被拒绝时告警,并核对各分支的节点输出。
- 改回网址,点 Publish。 发布后定时触发才会生效,在 Executions 页面能看到每 30 分钟一条执行记录。
飞书节点显示成功后,还要验收什么?
免费 JSON 中的飞书节点发送文本消息体,未实现签名计算,之后也没有独立的业务响应校验节点。此模板按前述关键词模式演示;机器人若已启用签名校验,需按 飞书官方自定义机器人指南补齐签名配置,并保留原有安全校验。
验收时同时检查飞书接口返回的业务响应和目标测试群的实际消息;仅看到 HTTP 请求完成或节点绿色勾号,不能单独认定告警已送达。响应报错、关键词不匹配或群内无消息时,记录节点输出并继续排查,先不要发布定时任务。
几个值得记住的细节:
- 为什么要“出错时继续”:HTTP Request 默认遇到连接失败会让整个执行报错停止,你反而收不到告警。打开“继续执行”后,错误信息会放进
$json.error,由 IF 节点判断。 - 为什么不在 IF 的两个分支都接通知:正常时也推送会很快变成噪音,大家就不看了。告警类流程只在异常时说话。
- 频率别太高:每分钟检查一次会产生大量执行记录。每 30 分钟或每小时一次,配合执行记录自动清理,足够个人网站使用。
如果你想看更多类似的实战流程,可以搜索站内的 自动化工作流教程。
上线前检查、备份与升级
结论: 上线前先完成备份,并在隔离测试环境做恢复演练;所需时间取决于数据量和环境,不能只凭生成了备份文件判断可恢复。
备份至少包括三样:PostgreSQL 数据库、n8n_data 数据卷(里面有加密密钥配置文件)、.env。数据库备份可以用 pg_dump,放进 crontab 每天执行,并定期拷贝到另一台机器或对象存储:
docker compose exec -T postgres pg_dump -U n8n -d n8n > n8n-$(date +%F).sql
备份完成后,先核对这四项
- 上面的命令只适用于数据库用户名和数据库名都为
n8n的配置;如果修改过POSTGRES_USER或POSTGRES_DB,请同步替换-U和-d后的值。 - 检查命令退出状态和标准错误输出。重定向可能在导出失败时仍留下空文件或不完整文件;文件存在或非空均不能单独证明备份成功。
- 另存部署配置、原加密密钥与实际使用的文件目录(如
./local-files);备份包含敏感数据,应限制访问并加密保存。工作流 JSON、数据库导出和附件目录各有范围,不能互相替代。 - 用可信备份在隔离环境恢复,并禁用定时、外发通知及写入生产系统的操作,再核对工作流、凭证解密和所需文件。恢复验收通过后再安排升级;不要直接用生产实例试恢复。
依据 PostgreSQL 16 官方 pg_dump 文档,该命令导出单个数据库,并需检查标准错误中的警告;全局角色等对象需要另行规划备份。数据库备份与恢复需在你自己的隔离环境完成验收。
工作流还可以单独导出成 JSON,每个工作流一个文件;提交 Git 前仍需检查硬编码地址、Token 和其他敏感信息:
docker compose exec n8n n8n export:workflow --backup --output=/home/node/.n8n/backups/
导出后核对文件数量与工作流清单。该命令只导出工作流定义,不包含凭证和执行记录,不能替代数据库备份。
升级流程建议固定成下面的顺序:
升级步骤 1:阅读目标版本的发布说明
读目标版本的发布说明,重点看 Breaking changes;
升级步骤 2:备份数据库
执行上面的数据库备份;
升级步骤 3:修改目标版本号
修改 .env 里的 N8N_VERSION;
升级步骤 4:仅拉取并重建 n8n 服务
以下命令适用于现有 PostgreSQL 已正常运行、只修改 n8n 版本的升级。先完成备份与兼容性评估,在原 Compose 目录执行:
docker compose pull n8n && docker compose up -d --no-deps n8n
仅升级 n8n 时,应指定服务名,避免直接运行未指定服务的全栈更新命令。pull n8n 将拉取范围限定为 n8n,--no-deps 不启动其依赖服务。PostgreSQL 与 Caddy 的升级应另行安排;若同时改动数据库、网络或代理配置,本节命令不适合作为完整升级流程。参见 Docker pull 文档与 Docker up 文档。
升级步骤 5:验证迁移与关键工作流
看日志确认数据库迁移完成,readiness 返回 ok,抽查两三个关键工作流。
回滚要特别小心:n8n 升级时会执行数据库迁移,迁移不会自动撤销。想退回旧版本,必须先用升级前的备份恢复数据库,再改回旧版本号。PostgreSQL 本身做大版本升级(例如 16 升 18)时,官方文档也提醒要先用 pg_dumpall 备份,并注意 18 版本数据目录的变化。
进阶:把现成的工作流接进来
结论: 部署好的 n8n 真正产生价值,是在你把日报、采集、通知这类重复工作接进来之后;接入前先统一好“配置放哪里、出错怎么告警”两件事。
我们在准备付费资料包时,把 20 个工作流统一做了几条约定,你自己搭流程时也可以参考:
- 配置集中管理:模板可通过环境变量引用接口地址、表格 ID 和机器人地址,减少把密钥直接写入 JSON 的机会;这不能保证导出、分享或备份不含敏感信息。分享前仍需检查节点参数、认证请求头、固定测试数据及凭证名称。若模板要求将
N8N_BLOCK_ENV_ACCESS_IN_NODE设为false,应先评估工作流编辑者可读取环境变量的风险;多人实例优先使用 n8n 凭证管理并限制权限,不要为方便导入而直接放开; - 接口返回统一检查:飞书接口返回
code不为 0、微信接口返回errcode不为 0 时,主动让执行失败,而不是“看起来成功、实际没写进去”; - 全局错误工作流:用 Error Trigger 节点做一个告警流程,在每个工作流的 Settings 里选它作为 Error workflow;
- 跨执行去重:采集类流程可用 Remove Duplicates 的 “Remove Items Processed in Previous Executions” 过滤历史记录,但效果依赖去重字段、作用域和历史状态。它不等同于当前批次去重,也不能单独保证下游绝不重复写入;涉及重试或并发写入时,目标端还应按业务唯一标识设计幂等校验,并用重复输入和失败重试验收。
官方说明:工作流 JSON 仍可能含敏感节点参数;当前输入去重与跨执行去重需要分别配置。本节是接入建议,不代表所有模板均已通过真实业务验收。
想了解飞书、企业微信等通知渠道的更多接法,可以看站内的 飞书相关教程。
对比与选型建议
结论: 不确定选哪种方式时,按“是否需要公网 Webhook”和“是否长期使用”两个问题来判断。
- 只是想学 n8n:本机 Docker Desktop + 本文 compose 的本地试用模式,或者官方单容器命令;先确认镜像拉取与本机资源满足要求;
- 个人长期使用、需要接收外部回调(表单、支付通知、GitHub Webhook):一台云服务器 + 域名 + 本文的 n8n + PostgreSQL + Caddy;
- 团队使用、多人编辑:同样的架构,但要收紧权限——环境变量里不要放敏感密钥,改用 n8n 凭证;为每个成员单独开账号;
- 执行量很大、需要高可用:考虑队列模式和多 worker,或者直接评估云版和企业版。
配套资料:先部署,再扩展业务流程
还没装好 n8n:先领取免费部署包,包含 Docker Compose 配置、环境变量示例、Caddyfile、第一个网站巡检工作流和部署检查清单。
已完成部署、需要更多业务场景:¥99 套餐提供 20 个工作流 JSON,覆盖采集、日报周报、飞书同步及备份监控,附配置模板、接入文档、清单表格和测试工具,共 52 个文件。
付费模板仍需填写自己的账号和配置;第三方 API、服务器费用另计。部分第三方接口使用本地模拟测试,请先查看商品页测试范围,并在自己的测试群、测试表验证。
部署后继续扩展:初次搭建智能体可接着阅读 n8n Agents 从零入门;需要生成与排错流程时,可对照 n8n Assistant 生成、运行与排错教程;希望建立验证与修复循环时,再阅读 n8n MCP Server 工作流自动修复教程。每项扩展均需按对应教程确认版本与权限边界。
风险、限制与注意事项
结论: 自托管最大的风险不是“装不上”,而是密钥泄露、没有备份、以及把 AI 或自动化的结果不加审核地发出去。
运行时重点检查以下 4 类问题:
- 错误工作流必须发布。 如果日志提示错误工作流 “is not active and cannot be executed”,先检查错误工作流是否已发布,再核对告警中的工作流名称、出错节点和错误信息。
- 环境变量默认读不到。 表达式里写
$env.XXX会报 “access to env vars denied”,需要按前文说明显式放行,并接受相应风险。 - 去重节点参数写错不报错。 参数不匹配时,流程可能没有报错却仍放行全部数据。所以凡是自己改过的去重逻辑,都要连续运行两次,确认第二次没有新数据通过。
- 去重历史有上限。 Remove Duplicates 会记住历史值,历史数量加上本次输入超过 History Size(默认 10000)时会直接报错,高频采集流程要调大或定期清理。
其他需要注意的限制:
- 安全:
.env和工作流配置文件里有数据库密码、加密密钥和各种 Token,权限设为 600,不要提交到 Git;对外开放的 Webhook 至少加口令校验,并在反向代理上限流。 - 第三方依赖:飞书、公众号、各家大模型的接口和权限会调整,频率限制也不同。凡是会发消息、写数据、发布内容的流程,正式启用前先用测试群、测试表手动运行。
- AI 输出:用大模型写摘要、日报、文案时,结果可能出错或编造,对外发布前要人工确认;涉及发布内容、删除数据、改权限的操作,建议加人工审批节点。
- 镜像获取:国内服务器拉取 Docker Hub 镜像可能较慢或失败,可按云厂商文档配置镜像加速;配置后先单独拉取目标镜像,确认仓库域名和版本标签可用。
FAQ
n8n 自托管是免费的吗?
社区版自托管不收软件授权费,你需要支付的是服务器、域名和自己的维护时间。一台 2 核 4 GB 的云服务器足够个人和小团队起步。部分企业功能(例如更细的权限管理、单点登录等)属于付费版本,具体以 n8n 官网的定价与授权说明为准。
一定要用 PostgreSQL 吗,SQLite 不行吗?
不是一定,但长期使用建议直接用 PostgreSQL。官方单容器示例默认用 SQLite,数据存放在数据卷里的一个文件中,学习和轻量使用没有问题;当工作流变多、执行频繁、需要用 pg_dump 做标准备份时,PostgreSQL 更稳妥,也免去了以后从 SQLite 迁移的麻烦。
WEBHOOK_URL 不设置会怎样?
编辑器里 Webhook 节点显示的地址会变成 http://localhost:5678/webhook/...,你把这个地址交给表单、支付平台或 GitHub,它们当然调不进来。只要部署在服务器上并且要接收外部回调,就必须把 WEBHOOK_URL 设成 https://你的域名/,改完执行 docker compose up -d 重建容器。
加密密钥丢了怎么办?
已保存的凭证(各种 API Key、OAuth 授权)将无法解密,只能逐个重新填写,工作流本身不受影响。如果密钥还在但和 .env 不一致,n8n 会以 “Mismatching encryption keys” 拒绝启动,把 .env 改回原来的值即可。所以第一次生成密钥后,务必单独保存到密码管理器。
为什么导入的工作流不按时运行?
n8n 2.x 中导入的工作流默认未发布,定时触发和 Webhook 都不会生效。打开工作流点右上角的 Publish 即可。如果已发布仍然时间不对,检查 GENERIC_TIMEZONE 是否为 Asia/Shanghai,以及服务器时间是否准确。
国内服务器拉不下 n8n 镜像怎么办?
免费包的 Compose 使用 docker.n8n.io/n8nio/n8n:${N8N_VERSION:-2.41.6}。拉取失败时,请先核对实际仓库域名、版本标签及报错,再按 n8n 官方镜像说明和所用云厂商文档排查;不要仅凭“配置了 Docker Hub 加速”判断这个仓库已经连通。部署前先拉取目标镜像,确认成功后再启动服务。
n8n 的 Code 节点能用 require 引入模块吗?
默认不能引入 Node.js 内置模块或外部模块。需要时用 NODE_FUNCTION_ALLOW_BUILTIN 放行指定的内置模块(例如 crypto),只放行真正需要的那几个。外部 npm 模块还需要自定义镜像,复杂度和风险都更高,能用现成节点解决的就不要写代码。
自托管 n8n 安全吗?
安全程度取决于你的配置。按本文做法——只开放 443、5678 只绑定本机、HTTPS、强密码加两步验证、.env 权限 600、对外 Webhook 加口令、定期备份——可作为基础防护起点,不能据此保证安全;仍需结合版本漏洞、账号权限、工作流内容和网络边界评估。多人共用的实例还要避免把敏感密钥放进环境变量,改用 n8n 凭证管理。
事实依据与来源
依据说明
- 官方文档:Docker 单容器启动命令、
N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true的用法、更新镜像的方式、PostgreSQL 相关变量来自 n8n 官方 “Install with Docker” 页面;官方 Compose 示例的组成(含 AI 沙箱与搜索组件)和 PostgreSQL 18 数据目录提醒来自 “Install using Docker Compose” 页面。 - 飞书接口:自定义机器人的添加方式与安全设置依据飞书开放平台官方文档。
- 编辑判断:服务器配置“2 核 4 GB 起步”、部署方式选型建议、检查频率建议,属于编辑经验,不代表官方结论。
- 实施建议:备份频率、升级顺序、权限收紧方式属于实施建议,请结合你的业务调整。
官方文档与版本信息
n8n 部署与工作流资料
以下资料专用于 n8n:先完成部署,再选择业务工作流;其他软件请使用对应教程附件。





