n8n自托管部署指南：从Docker Compose到生产环境配置

如果你正在搜索“n8n 安装指南”大概率已经被 Zapier、Make 这类平台的计费规则折磨过一阵子了。n8n 的价值在于它可以自托管——工作流引擎跑在自己的服务器上没有按次计费的限制数据链路完全可控社区生态也足够丰富。但我必须提醒你n8n 的安装并不难难的是安装完之后让它在生产环境里稳定跑下去。本篇文章把我从第一次跑通 n8n 到后来做企业级部署的完整过程梳理出来覆盖四种部署方式的取舍、Docker Compose 和 npm 两条安装路径、Nginx 反代、PostgreSQL 迁移、凭证配置以及装完以后最容易踩的坑全部按可复现的标准写清楚。1. 装之前先想明白哪种部署方式适合你1.1 四种方案的真实差异n8n 官方提供了四种主流部署路径npm 全局安装、Docker 单容器、Docker Compose以及官方托管云服务 n8n Cloud。我见过很多初学者一上来就选 npm理由是“看起来最简单”也有直接docker run跑起来的但跑了几天后升级、备份、改配置全乱套。这里先做一个横向对比。部署方式适合场景数据持久化方式升级与回滚运维成本npm 全局安装本机快速体验、开发调试~/.n8n目录需要手工管理 Node 与 n8n 版本中低Docker 单容器临时测试、个人轻量使用Docker volume 挂载换镜像 tag 即可低Docker Compose生产环境、长时间运行、多服务联动Named volume 或宿主机目录改 yml 后docker compose up -d低n8n Cloud不想自运维、预算充足官方托管官方自动升级最低我的建议很简单只想在笔记本上体验用 npm真正打算长期使用并接业务数据最好直接上 Docker Compose别在单容器方案上徘徊太久。单容器适合验证但一旦涉及环境变量、数据库迁移、日志查看和版本锁定Compose 的声明式配置会让你省掉大量重复操作。1.2 我为什么把 Docker Compose 作为首选如果你问我生产环境推荐什么我会毫不犹豫地写 Docker Compose。核心原因有三个。第一环境隔离彻底。n8n 依赖 Node.js 运行环境npm 方式下 Node 主版本升级、全局包冲突都可能把 n8n 搞崩容器方案把运行时、依赖和配置全部封装在镜像内宿主机只需要有 Docker 即可。第二升级回滚最可控。Compose 文件里把镜像版本写成n8nio/n8n:1.75.2这样的固定 tag升级就改版本号再执行docker compose up -d一旦新版本有问题把 tag 改回去就能快速回滚。npm 方式想要回滚版本就得处理全局包和数据库兼容性非常被动。第三多服务编排无缝衔接。生产环境里 n8n 通常要和 PostgreSQL、Redis、Nginx 一起跑Compose 可以统一管理这些服务的网络、卷和依赖关系。到后面讲企业级部署时你会发现没有 Compose 的话单容器方案会寸步难行。1.3 服务器最低配置与网络检查官方对 n8n 的硬件要求写得比较含蓄实际经验是生产环境建议2 核 4G 起步如果你要同时跑大量 webhook、定时任务和 AI 相关节点8G 内存会更从容。这是内存大户尤其在工作流执行过程中每个节点都要加载各自的处理逻辑。动手前先做三个检查# 确认 Docker 已安装 docker --version # 确认 Compose 插件可用 docker compose version # 确认端口 5678 未被占用 ss -lntp | grep 5678如果你的服务器不在 Docker Hub 快速访问区域拉取 n8n 镜像可能会非常慢。此时可以配置 Docker 的镜像加速器registry mirror修改/etc/docker/daemon.json{ registry-mirrors: [ https://docker.m.daocloud.io ] }改完后执行systemctl restart docker。这一步能显著减少镜像拉取等待时间属于国内部署必做项。2. Docker Compose 安装 n8n从目录规划到执行启动2.1 创建目录结构与数据卷设计我推荐把 n8n 的数据目录放在/opt/n8n而不是家目录或/root下。原因很朴素生产服务器上/opt通常是给第三方应用预留的位置权限边界更清晰也方便多项目并行管理。mkdir -p /opt/n8n/data mkdir -p /opt/n8n/backup cd /opt/n8n这里data目录是 n8n 存储工作流、凭证、设置和 SQLite 数据库的位置backup目录留给后续的定时备份脚本。目录权限注意不要随便chmod 777普通用户能读写即可容器内部会用node用户运行映射宿主目录时天然有权限要求。2.2 docker-compose.yml 核心配置逐行拆解在/opt/n8n下新建docker-compose.yml以下是一个经过验证可稳定运行的基础版本services: n8n: image: n8nio/n8n:1.75.2 container_name: n8n restart: unless-stopped ports: - 5678:5678 environment: - N8N_HOSTn8n.example.com - N8N_PORT5678 - N8N_PROTOCOLhttps - NODE_ENVproduction - TZAsia/Shanghai - GENERIC_TIMEZONEAsia/Shanghai - N8N_SECURE_COOKIEfalse - WEBHOOK_URLhttps://n8n.example.com/ volumes: - /opt/n8n/data:/home/node/.n8n - /etc/localtime:/etc/localtime:ro每项配置背后都有实际意义我逐个说明image生产环境必须锁定具体版本号不要用latest。latest 会在你不知情的情况下升级工作流节点和第三方认证的兼容性可能在升级后突变。restart: unless-stopped服务器重启后容器自动拉起这是生产环境的基本要求。N8N_HOST和N8N_PROTOCOL告知 n8n 对外服务的域名和协议。配置不当会导致 webhook 回调地址生成错误、OAuth 流程失败。WEBHOOK_URL生产环境配 https 反代时必须设置否则 n8n 返回的 webhook URL 可能是错误的 IP 或协议。N8N_SECURE_COOKIEfalse如果你暂时没有配 HTTPS而是直接通过 IP 访问必须关闭 secure cookie否则浏览器无法保存会话 Cookie。配好 HTTPS 后建议改回true。TZ与GENERIC_TIMEZONE设置时区为Asia/Shanghai避免定时触发节点按 UTC 时间执行导致“差 8 小时”的问题。数据卷映射把容器内/home/node/.n8n映射到宿主机/opt/n8n/data这层映射决定了升级容器时数据不丢失。注意N8N_SECURE_COOKIEfalse只是开发阶段的临时方案一旦通过域名 HTTPS 对外提供服务一定要把它改回 true否则会有明显的安全隐患。2.3 启动、日志排查与升级命令配置写好后启动docker compose up -d启动后检查容器状态docker ps | grep n8n如果容器没有正常运行查看日志定位原因docker compose logs -f n8n这是排查安装问题最直接的手段。常见问题如端口冲突、volume 目录权限不足、环境变量拼写错误都会在日志里暴露出来。升级 n8n 时执行以下流程docker compose pull n8n docker compose up -d这会拉取新的镜像并重建容器。只要数据卷映射正确工作流和凭证都会保留。升级前我强烈建议先备份整个/opt/n8n/data目录后面会详细讲备份脚本。3. 另一种常见路径npm 方式安装的版本兼容陷阱3.1 用 nvm 管理 Node.js 版本如果你只是在本机或一台闲置服务器上做快速体验npm 方式依然有效。但这里有个经常被忽略的硬性要求n8n 对 Node.js 版本有明确要求通常需要 Node 18 或 20 的较新版本。直接用系统自带的 Node 12/14 启动大概率会直接报错。推荐用 nvm 安装和管理 Nodecurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20然后安装 n8nnpm install -g n8n n8n --version启动 n8nn8n start默认监听 5678 端口浏览器访问http://localhost:5678即可进入初始化界面。3.2 npm 方式的环境变量配置与守护进程npm 方式下环境变量可以直接在 shell 中导出也可以写在启动脚本里。比较稳妥的做法是创建/etc/profile.d/n8n.sh或使用 systemd 服务统一管理。下面是一个实用示例export N8N_HOSTlocalhost export N8N_PROTOCOLhttp export WEBHOOK_URLhttp://localhost:5678/ export TZAsia/Shanghainpm 方式启动的进程默认是前台运行的一旦 SSH 断开服务就停了。生产环境若执意用 npm 方式建议用 systemd 或 PM2 守护。我见过不少人用nohup n8n start 启动重启服务器后进程丢失又找不到原因。要么写 systemd service要么直接回到 Docker 方案。3.3 npm 与 Docker 的取舍经验npm 方式在数据持久化上依赖~/.n8n目录该目录中有database.sqlite、config和credentials等文件。升级 n8n 时如果包依赖冲突老版本数据可能无法被新版本读取。Docker 方式则通过卷隔离帮你绕开了绝大多数依赖冲突。我个人的经验是npm 方式只用来做 10 分钟内的功能体验任何超过一周的部署计划都应该迁移到 Docker Compose。这不仅是运维习惯也是对数据安全负责。4. 企业级部署方案反向代理、HTTPS 与 PostgreSQL 迁移4.1 为什么告别 SQLite切换到 PostgreSQLn8n 默认会把数据写入database.sqlite单机小规模场景下完全够用。但生产环境并发写入多、历史执行数据增长快SQLite 的锁机制和单文件瓶颈会逐步显现。官方文档和企业实践都推荐使用 PostgreSQL 作为后端数据库。在 Docker Compose 中增加 PostgreSQL 服务的示例services: postgres: image: postgres:15 container_name: n8n-postgres restart: unless-stopped environment: - POSTGRES_USERn8n - POSTGRES_PASSWORDchange-me - POSTGRES_DBn8n volumes: - /opt/n8n/postgres-data:/var/lib/postgresql/data healthcheck: test: [CMD-SHELL, pg_isready -U n8n] interval: 5s timeout: 5s retries: 10 n8n: image: n8nio/n8n:1.75.2 container_name: n8n restart: unless-stopped depends_on: postgres: condition: service_healthy ports: - 5678:5678 environment: - DB_TYPEpostgresdb - DB_POSTGRESDB_HOSTpostgres - DB_POSTGRESDB_PORT5432 - DB_POSTGRESDB_USERn8n - DB_POSTGRESDB_PASSWORDchange-me - DB_POSTGRESDB_DATABASEn8n - N8N_HOSTn8n.example.com - N8N_PROTOCOLhttps - WEBHOOK_URLhttps://n8n.example.com/ - TZAsia/Shanghai volumes: - /opt/n8n/data:/home/node/.n8n关键点是healthcheck确保 PostgreSQL 就绪后才启动 n8n否则首次启动时 n8n 会因为数据库连不上而初始化失败。密码变量不要写在明文 Compose 里长期保存生产环境建议使用.env文件配合env_file引用。4.2 Nginx 反向代理与 HTTPS 配置端口 5678 不应该直接暴露到公网标准的做法是让 Nginx 监听 80/443然后反向代理到本机的 5678。docker-compose.yml中可以将 n8n 端口改为127.0.0.1:5678:5678避免外网直接访问。Nginx 关键配置server { listen 443 ssl http2; server_name n8n.example.com; ssl_certificate /etc/letsencrypt/live/n8n.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/n8n.example.com/privkey.pem; location / { proxy_pass http://127.0.0.1:5678; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_http_version 1.1; proxy_read_timeout 3600s; } } server { listen 80; server_name n8n.example.com; return 301 https://$host$request_uri; }Upgrade和Connection两行是给 n8n 的 WebSocket 和 SSE 功能使用的少了会导致某些实时节点异常。证书自动续期我用 acme.sh 的--cron定时任务完成续期后执行nginx -s reload即可。4.3 定时备份与恢复脚本生产环境不能把数据安全寄托在“应该没问题”上。n8n 的数据包括三部分工作流定义、凭证加密信息、执行历史。备份方案核心是把整个数据目录和 PostgreSQL 数据库都纳入备份范围。参考脚本/opt/n8n/backup/backup.sh#!/bin/bash BACKUP_DIR/opt/n8n/backup DATE$(date %F_%H%M%S) # 备份 n8n 数据目录 tar -czf $BACKUP_DIR/n8n_data_$DATE.tar.gz -C /opt/n8n data # 备份 PostgreSQL docker exec n8n-postgres pg_dump -U n8n -d n8n $BACKUP_DIR/n8n_db_$DATE.sql # 保留最近 7 天的备份 find $BACKUP_DIR -name *.tar.gz -mtime 7 -delete find $BACKUP_DIR -name *.sql -mtime 7 -delete给脚本加执行权限并配置 crontabchmod x /opt/n8n/backup/backup.sh crontab -e添加定时任务0 3 * * * /opt/n8n/backup/backup.sh恢复时只要在新环境中把数据目录和 SQL 文件导入即可。这里有经验之谈恢复前一定要确保 n8n 容器处于停止状态否则可能产生数据覆盖冲突。4.4 多用户、加密密钥与执行模式补充生产环境部署时还需要注意三个环境变量N8N_USER_MANAGEMENT_DISABLED默认不设置启用用户管理。如果设为true会退回到单用户模式企业多成员协作时千万别开。N8N_ENCRYPTION_KEY用于加密凭证信息的密钥。这个值一旦固定更换服务器时必须沿用同一个值否则已保存的所有 OAuth、API Key 都无法解密。生成方式openssl rand -hex 32写入.env文件。N8N_RUNNERS_ENABLED默认建议为 true。n8n 从 1.0 之后引入了代码节点独立运行器的概念默认开启可以提升复杂 JS 节点的稳定性和日志隔离性。5. 安装完成后绕不开的收尾工作登录、凭证与连接大模型5.1 首次登录、时区与语言设置安装完成后浏览器访问http://IP:5678如果打开了N8N_SECURE_COOKIEfalse则可以用非 HTTPS 方式访问。首次初始化需要设置管理员邮箱和密码这一步之后进入控制台第一件事就是检查左下角用户设置里的时区。n8n 官方界面目前以英文为主但内建了多语言支持框架通过浏览器自动翻译一般也能正常使用。社区中文资源已经很多网上的文章、教程、节点命名大多有中文对照初学阶段不必为了界面语言焦虑。5.2 Credentials 凭证体系从 API Key 到自定义凭据n8n 里所有涉及外部服务认证的节点都需要配置 Credentials不能跳过。凭证体系的核心逻辑是把认证信息与工作流定义分离工作流可以导出分享但凭证只会以加密形式存储在服务端数据库。以 HTTP Request 节点为例你可以创建两种常用凭证Header Auth在请求头里加Authorization: Bearer xxx适合调用大多数现代 API。OAuth2适合 Google、GitHub 等平台n8n 可以帮你完成整个授权回调流程。这里有个容易踩的坑同一套 Credentials 可以被多个工作流引用但导出工作流 JSON 时凭证不会跟着导出。如果要把工作流迁移到另一台 n8n 实例必须在目标实例上重新创建凭证然后在对应节点上选择新的凭证。很多人迁移后节点报 401都是因为忽略了这个环节。5.3 用 n8n 连接 Ragflow 与本地大模型一个实际案例“n8n 连接 Ragflow”是近期社区里讨论度很高的话题。Ragflow 是一个面向 RAG检索增强生成场景的知识库服务而 n8n 可以把它作为 HTTP API 接入工作流。以调用 Ragflow 的文档问答接口为例新增一个 HTTP Request 节点方法选择POSTURL 填 Ragflow 的 API 地址/api/v1/chats/{chat_id}Header 加 Authorization Bearer TokenBody 按官方 API 格式传入question参数。后置节点可以接Switch对结果做分支处理或接Execute Workflow把问答结果继续送入其他流程。如果你的目标是“本地大模型自动发布内容”思路也类似先用 HTTP Request 调用 Ollama 的/api/generate接口生成文案再通过后续节点推送到对应平台或 IM。这是 n8n 在大模型场景下最典型的组合用法——n8n 负责编排和调度模型服务负责生成各司其职。5.4 忘记密码的三种自救方案忘记 n8n 登录密码是高频问题尤其是部署完隔了几个月再想登录的人。三种方案按顺序尝试。方案一如果已经配置了 SMTP 邮箱服务在登录页点“Forgot your password”n8n 会发送重置邮件点链接即可重置。这是最省事的方法。方案二如果没配 SMTP可以进入服务器直接操作数据库。n8n 的密码字段存储在数据库User表中以 bcrypt 哈希保存。你可以用 Node.js 生成一个新的 bcrypt 哈希然后更新数据库记录。参考命令node -e console.log(require(bcryptjs).hashSync(NewPassword123, 10))然后将输出的哈希写入数据库docker exec -it n8n-postgres psql -U n8n -d n8n UPDATE User SET password 输出的哈希值 WHERE email 你的邮箱;方案三如果计划重建 owner 用户直接清空用户表再重启 n8n 会触发重新初始化但这会导致原有账号关联信息丢失不推荐。方案二操作过程中不要启动多个 n8n 实例避免内存数据库缓存导致更新未生效。6. 安装与运行中的高频坑位笔记6.1 端口、内存与 Docker 日志的经典问题我在实际部署中遇到过多次“容器起来了但访问不了”的情况。排查顺序一般是先docker ps看容器是否在运行再ss -lntp | grep 5678确认端口监听状态接着检查 Nginx 配置是否生效最后看 n8n 日志。内存问题更容易被忽视。n8n 容器默认没有内存上限限制但系统内存不足时内核会触发 OOM表现为容器突然退出且日志末尾只有Killed字样。建议在 Compose 中配置mem_limit: 4g并配合docker stats监控内存使用。6.2 环境变量写错导致的后台静默失败n8n 的某些环境变量并不会在启动时报错而是表现为运行期行为异常。最典型的两个WEBHOOK_URL忘配置或有误工作流中的 Webhook 节点生成的回调 URL 不正确外部系统调用时 404。N8N_PROTOCOLhttps但 Nginx 未配置 SSLOAuth 和部分回调流程可能陷入无限重定向。这类问题定位耗时较长。建议修改环境变量后先查看启动日志确认配置被正确加载再实际跑一个测试工作流验证。6.3 从零恢复整个 n8n 服务的思路整机迁移或故障恢复时最稳妥的路径是备份数据目录和数据库 → 新服务器安装 Docker Compose 环境 → 恢复备份 → 重新设置N8N_ENCRYPTION_KEY为原值 → 用原域名解析到新服务器。只要加密密钥一致凭证解密就没有问题。还有一种常见情况是只想导出工作流到另一台实例。操作路径是在工作流列表中选中工作流 → Export → 下载 JSON。但要注意Import from File时节点引用的 Credentials 需要逐个重新配置。我前后部署过不下五套 n8n 环境从最开始的 npm 装到个人笔记本再到后来的 Docker Compose 生产集群最大的体会是安装本身只占 20% 的精力剩下 80% 都在配置、备份和排错上。如果你是被“最详细安装指南”吸引来的新手先把 Docker Compose 这条路走通再逐渐补 Nginx、PostgreSQL 和备份策略基本可以避开我踩过的大部分坑。最后建议你把N8N_ENCRYPTION_KEY和备份脚本这两件事放在安装清单的第一优先级它们决定了你后续运维时是从容还是狼狈。