n8n Docker 部署教程:一行命令安装、Compose、PostgreSQL 与上生产清单
n8n 官方推荐用 curl -fsSL https://get.n8n.io | sh 一行命令完成 Docker 部署。本文按官方文档讲解三种 Docker 方式、Windows 安装、默认 SQLite 与沙箱安全、换用 PostgreSQL、升级和上生产前的检查清单。
n8n 官方现在推荐的 Docker 部署方式是一行命令:装好 Docker 之后运行 curl -fsSL https://get.n8n.io | sh,脚本会创建 n8n 文件夹、写好 compose.yml 和 .env、下载镜像并启动,完成后在浏览器打开 http://localhost:5678 就能用。需要自己掌控配置时,再按官方的 Docker Compose 指南手动搭建。下面按 n8n 官方文档讲清三种 Docker 部署方式的区别、步骤、升级方法,以及上生产前必须处理的数据库、反向代理和安全问题。
先确认:自托管适不适合你
n8n 文档在 Docker 安装页开头就写明,自托管需要一定的技术基础,包括配置服务器和容器、管理资源和扩容、保护服务器和应用,以及配置 n8n 本身。官方建议专家用户自托管,因为操作失误可能导致数据丢失、安全问题和停机;不熟悉服务器管理的用户,官方推荐使用 n8n Cloud。站内另一篇文章比较了社区版和 Cloud Starter 的成本,本文只讲自托管怎么部署。
另一个需要知道的变化是安装渠道。官方一行命令安装页说明,这个命令取代了过去的 npm install n8n 和 npx n8n 方式,从 n8n 3.0 起后者不再可用,n8n 只通过 Docker 分发。现有的 npm 安装暂时还能运行,但新安装和以后的升级都应该改用 Docker。截至本文核对时,官方 Docker 页显示的当前稳定版是 2.47.7,测试版是 2.48.4。官方说明稳定版用于生产,测试版可能不稳定。
三种 Docker 部署方式怎么选
官方安装选项页列出了一行命令安装、Docker Compose 手动安装、npm 安装、Docker 安装和云服务商部署几种方式。和 Docker 有关的是三种。
一行命令安装:最快,适合全新安装,不需要懂 Docker,只要装好并运行 Docker 即可。脚本自动生成配置和密钥。
Docker Compose 手动安装:适合想完全掌控配置,或要把 n8n 并入已有 Compose 项目的人。你自己写 .env、compose.yml 等文件。
docker run 单容器:官方 Docker 安装页现在顶部标着“此内容已过时”,并指向 Docker Compose 作为推荐方式。它仍然可以用来快速试用,但不再是首选。
如果你只是想用 docker run 快速看一眼,官方页给出的写法是先 docker volume create n8n_data 创建数据卷,再运行 n8nio/n8n 镜像,映射 5678 端口,并把数据卷挂载到容器内的 /home/node/.n8n,这样容器重启后数据还在。命令里有两个时区变量要换成你自己的时区:TZ 控制系统时间,GENERIC_TIMEZONE 决定定时触发器等按时间运行的节点使用哪个时区,所以两个变量都要设成你实际所在的时区,例如亚洲新加坡对应 Asia/Singapore。
判断方法很直接:第一次部署、只想尽快跑起来,用一行命令;已经有自己的 Compose 文件,继续用自己的,官方说明不必切换到脚本;要换 PostgreSQL、改网络和安全设置,用 Compose 手动搭建。
一行命令安装的步骤和日常命令
前提是装好 Docker,Docker Desktop 已经包含 Docker Compose。官方特别说明,这个命令要求的是 docker compose v2 插件,不是旧的独立 docker-compose 程序,并且会检查 Docker 守护进程是否在运行。用 Podman、Colima 等兼容引擎的话,需要安装带 compose 插件的 docker 命令行,并把 DOCKER_HOST 指向它们的套接字。
运行命令后,脚本会依次做四件事:检查 Docker 是否安装并运行,不满足时告诉你怎么修;在当前目录创建 n8n 文件夹;写入 n8n 需要的配置文件,包括 compose.yml、searxng-settings.yml 和生成了独立密钥的 .env;下载镜像并启动。重复运行是安全的,如果文件夹里已经装过,它只会提示已存在,不会改动任何东西。第一次启动需要一点时间,脚本会等服务就绪后才打印访问地址。
如果不想直接运行网上的脚本,官方给了替代做法:先用 curl -fsSL https://get.n8n.io -o get-n8n.sh 下载,审阅内容后再用 sh get-n8n.sh 执行。
日常命令有四条:停止是 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 的 down 命令再删除文件夹。注意 -v 会删除全部 n8n 数据,执行前务必备份。
脚本还支持几个参数:--version 单独使用时显示脚本版本和将要安装的 n8n 版本,后面跟版本号时安装或升级到指定版本;--no-start 只生成配置文件不启动;--help 显示全部选项。
Windows 用户要注意,这个命令需要能运行 shell 脚本的终端,普通的命令提示符和 PowerShell 不行。官方建议在 WSL 中运行,并打开 Docker Desktop 的 WSL2 集成;Git Bash 也能运行 POSIX 脚本,但官方没有对一行命令安装做完整验证。
默认装了什么:SQLite 和 n8n Assistant 沙箱
一行命令默认安装三部分。第一是 n8n 编辑器本身,运行在 5678 端口。第二是内置数据库 SQLite,保存工作流、凭据和执行历史,是一个文件型轻量数据库,不需要单独安装数据库服务。第三是 n8n Assistant 的支持服务:一个安全运行 Assistant 所写代码的沙箱,以及一个内置搜索工具。这些服务会随 n8n 一起启动,但 Assistant 本身默认关闭,要在实例的 AI 设置里填入模型 API 密钥,或在 .env 的 N8N_INSTANCE_AI_MODEL_API_KEY 中填写后重启才会启用。
这里有一条重要的安全提醒。官方说明内置沙箱只用于开发和测试,不适合生产:它的运行器 sandbox-runner-1 以特权模式运行 Docker-in-Docker,隔离很弱,代码一旦逃出沙箱就能触及宿主机,应该把它视同宿主机的 root 权限。官方要求把这套环境运行在没有其他用途的独立机器或虚拟机上,并且不要暴露到互联网。默认情况下只有 n8n 的 5678 端口对外可达,其他服务保持私有。手动 Compose 方案还要求至少 4GB 内存和 2 个 vCPU,因为沙箱需要更多资源。
手动 Docker Compose 和换用 PostgreSQL
手动搭建的步骤是:建项目文件夹;创建 .env,填入 n8n 版本号、沙箱服务版本号和几组自己生成的密钥,并且不要提交到版本库;创建 searxng-settings.yml 打开搜索的 JSON 接口;创建 compose.yml,内容参考官方仓库的模板;然后运行 docker compose up -d 和 docker compose ps,等 sandbox-api 显示 healthy 后,其他服务会自动启动。验证时可以用 curl -sf http://localhost:5678/healthz 确认 n8n 已经运行。
官方说明 SQLite 适合试用,生产环境如果要支持多个用户或全天运行的工作流,应该换成 PostgreSQL。做法是在 .env 里加上数据库用户名、密码和库名,在 compose.yml 里加一个 postgres:18 服务和数据卷,再给 n8n 服务加上 DB_TYPE: postgresdb 等连接变量。官方有两条警告:PostgreSQL 18 改了默认数据目录,配置里的 PGDATA 一行不能删,否则数据会写到数据卷以外,数据库会变成空的;已有的 SQLite 数据不会自动迁移,这套做法只适用于新实例。
升级和备份
一行命令安装的升级会同时更新 n8n 和沙箱服务,只修改 .env 里的 N8N_VERSION 和 N8N_SANDBOX_VERSION 两行,数据、密钥和其他设置保持不变。用 Compose 部署的,官方步骤是进入 compose 文件所在目录,执行 docker compose pull 拉取新镜像,再停止旧版本并重新启动。
官方的升级建议是:经常更新,至少每月一次,避免一次跨越多个版本;更新前查看版本说明里的破坏性变更;如果条件允许,先在测试环境更新验证。即使使用 PostgreSQL,也建议继续为 .n8n 目录挂载持久卷,因为这个目录里还有加密密钥、实例日志等重要数据。
上生产前的检查清单
官方生产要求页给出了明确方向。数据库方面,生产推荐 PostgreSQL,SQLite 不支持队列模式,也不推荐用于多用户生产环境。系统方面,推荐 64 位 Linux 主机。网络方面,不要把 n8n 进程直接暴露到互联网,前面要放反向代理或负载均衡,并在那里终止 TLS;为主机名配置 DNS,并设置 N8N_HOST、N8N_EDITOR_BASE_URL 和 N8N_WEBHOOK_URL,其中 N8N_WEBHOOK_URL 从 2.30.0 开始可用,更早的版本用 WEBHOOK_URL;在反向代理之后还要设置 N8N_PROXY_HOPS。
清单里还有几项:生成加密密钥并安全保存,多实例时每个实例使用相同的值,官方给出的生成命令是 openssl rand -hex 32;准备持久卷;确定备份策略;配置防火墙,云防火墙上只开放 n8n 的端口。
n8n 还能用 npm 安装吗
n8n 2.x 仍支持 npm 安装,但官方说明从 n8n 3.0 起只支持基于 Docker 的部署,新安装建议直接用 Docker。
n8n Docker 默认用什么数据库
默认是内置的 SQLite。官方建议生产环境、多用户或全天运行时换成 PostgreSQL。
n8n Docker 部署要多少内存
手动 Compose 方案要求至少 4GB 内存和 2 个 vCPU,因为内置沙箱使用 Docker-in-Docker。
Windows 上怎么跑一行命令安装
在 WSL 中运行,并打开 Docker Desktop 的 WSL2 集成,项目文件夹放在 WSL 文件系统内。
