n8n 怎么安装？新手本地部署与首次运行完整教程
装 n8n 本身不难，难的是装完之后「数据会不会丢」这件事。我见过太多人一条命令跑起来，用了一周，删掉容器重建，工作流全没了——因为数据卷没挂对。
这篇把三种常见装法讲清楚，按「最少踩坑」的顺序排：Docker、Docker Compose、npm。装完你会有：一个能在浏览器里打开的 n8n，数据存在本地不会丢，时区是对的。
适合谁看，动手前需要什么
适合完全没部署过服务的人，但需要你能打开终端敲命令。Windows、macOS、Linux 都能装，本文以 Docker 为主，因为后面升级和迁移最省事。
如果只是想在别人机器上试一下、不做长期使用，直接跳到第三节的 npm 方式，两行命令就能跑，但别拿它放重要数据。
先决定装在哪
| 方式 | 适合谁 | 优点 | 代价 |
|---|---|---|---|
| Docker（单容器） | 个人电脑、轻量使用 | 隔离干净，删了就删了，升级只换镜像 | 要学一点 Docker |
| Docker Compose | 长期运行、要接数据库 | 配置写进文件，可以版本管理，重启自动拉起 | 多一个 yaml 要维护 |
| npm 全局安装 | 已经有 Node 环境、想省资源 | 不用容器，直连宿主机，性能损耗最小 | 依赖系统 Node 版本，升级容易乱 |
我的建议：个人用选 Docker Compose，别用单条 docker run。原因很实际——单条命令跑起来之后，你过两个月绝对想不起当时设了哪些参数。Compose 把参数写在文件里，出问题能看、能改、能备份。
检查环境
先确认 Docker 在不在。终端执行：
docker -v能看到版本号（形如 Docker version 29.5.3, build d1c06ef）就说明装好了。Windows 和 macOS 装 Docker Desktop 会自带；Linux 用 Docker Engine。
再确认 5678 端口没被占用。Linux：
ss -lntp | grep 5678macOS 或 Linux 也可以用 lsof -i :5678。有输出说明被占了，换个端口，比如 -p 5679:5678。Windows 用 netstat -ano | findstr 5678。
方式一：一条 docker run 跑起来
先建数据卷，再启动容器。这两步别合并成一步，卷单独建好，后面删容器重建也不会丢数据：
docker volume create n8n_data
docker run -d --name n8n
-p 5678:5678
-e GENERIC_TIMEZONE="Asia/Shanghai"
-e TZ="Asia/Shanghai"
-e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true
-e N8N_DEFAULT_LOCALE=zh-CN
-v n8n_data:/home/node/.n8n
--restart unless-stopped
n8nio/n8n逐个说清每个参数在干什么，这些是真正会踩坑的地方：
-d：后台运行。官方文档给的是-it --rm（前台运行、退出即删），那是给试玩用的。长期用一定要改成-d --restart unless-stopped，服务器重启后容器会自己起来。-p 5678:5678：把容器内的 5678 映射到宿主机。左边是宿主机端口，改左边就行。GENERIC_TIMEZONE和TZ：两个都要设。TZ管容器里系统命令的时间，GENERIC_TIMEZONE管定时类节点（比如 Schedule Trigger）按哪个时区算。只设一个，会出现「我设的早上 9 点，实际下午 5 点跑了」。-v n8n_data:/home/node/.n8n：最关键的一行。n8n 的 SQLite 数据库、加密密钥、日志都在这个目录里。不挂卷，容器一删全没。N8N_DEFAULT_LOCALE=zh-CN：界面默认中文。注意 n8n 的中文只翻了外壳，节点参数仍是英文。
启动后浏览器打开 http://localhost:5678。第一次会让你创建管理员账号，密码至少 8 位。这个账号是本地存储的，忘了只能重置，记好。
方式二：Docker Compose（推荐）
建一个目录，里面放 docker-compose.yml：
services:
n8n:
image: n8nio/n8n:latest
container_name: n8n
restart: unless-stopped
ports:
- "5678:5678"
environment:
- GENERIC_TIMEZONE=Asia/Shanghai
- TZ=Asia/Shanghai
- N8N_DEFAULT_LOCALE=zh-CN
- N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true
- N8N_SECURE_COOKIE=false
volumes:
- ./n8n_data:/home/node/.n8n然后在这个目录里执行：
docker compose up -d几点说明：
N8N_SECURE_COOKIE=false 这一行只在「本地用 http 访问」时需要。如果你已经配了域名和 HTTPS，把它删掉——开着 HTTPS 却写 false，反而降低安全性。很多人本地装完登录页一直转圈，就是被这个 cookie 设置卡的。
数据目录用的是 ./n8n_data，也就是跟 yml 同级的文件夹。好处是备份直接打包这个目录，不用去猜 Docker 卷藏在哪。
查看日志、判断有没有起来：
docker compose logs -f --tail=50看到编辑器地址和版本号那一行，就说明起来了。按 Ctrl+C 只退出日志，容器还在跑。
方式三：npm 全局安装
我自用的那台实例就是这种方式，不用容器，直接跑在宿主机上。前提是有 Node.js 环境，n8n 2.x 要求 Node 20 以上（我这台是 Node 24.21.0）。
npm install -g n8n
n8n start但直接这么跑有个问题：数据默认落在当前用户目录下的 .n8n，而且关掉终端就停了。生产环境通常会用环境变量指定数据目录，再用 systemd 或 pm2 托管。这台实例实际用的关键变量是这样的（值改成你自己的）：
N8N_USER_FOLDER=/data/n8n
N8N_HOST=127.0.0.1
N8N_PORT=5678
N8N_PROTOCOL=http
N8N_EDITOR_BASE_URL=https://你的域名/
N8N_DEFAULT_LOCALE=zh-CNN8N_HOST=127.0.0.1 配合 N8N_EDITOR_BASE_URL，是把 n8n 藏在 Nginx 后面、不直接暴露端口的常见做法，下一篇部署到服务器时会细讲。如果你只在本机用，把 HOST 设成 localhost 就行。
装完长什么样
登录之后进入的是「概览」页。左边是功能导航，中间是工作流、执行、凭据这些标签页，右上角是「创建工作流」按钮。
点「创建工作流」，会得到一个空画布，中间只有一行「添加第一步」：
第一个工作流：三个节点
点画布中间那个加号，右侧会弹出节点库。搜索框里输入 manual，选「Manual Trigger（手动触发）」，它就是这条流程的起点。
接着在手动触发节点右边的小加号上，加一个「Edit Fields（编辑字段）」，随便写两个字段，比如 city 填「福州」、temp 填 27。再往右加一个「Code（代码）」节点，代码框里贴：
return items.map(item => ({
json: {
message: `${item.json.city} 现在 ${item.json.temp} 度`
}
}));最后点画布下方的「执行」按钮。三个节点依次亮起，都变成绿色对勾，就说明整条链路是通的。这时候点开任意一个节点，右边的输出区能看到实际数据。
这一步的目的不是学会写代码，而是让你确认：装出来的这套东西，能跑。
怎么算真的装成功了
能打开界面不算成功。按下面四条走一遍，都过了才算：
- 能打开编辑器：浏览器访问不报错，能看到工作流列表。
- 能保存：新建一个工作流，随便加个节点，等它自动保存，然后刷新页面，内容还在。
- 重启不丢：
docker compose restart，再刷新，刚才那个工作流还在。这一条是检验数据卷有没有挂对的唯一办法。 - 能执行：跑一次手动工作流，节点变绿，点开能看到输出数据。
第三条最容易被跳过，也最要命。如果你重启后工作流没了，别怀疑 n8n，去检查 -v 后面的路径是不是写错了、或者用了匿名卷。
常见错误
端口被占用。报错里带 port is already allocated。换宿主机端口，比如 -p 5679:5678，然后用 5679 访问。
能打开但登录转圈。本地用 http 访问时，如果 N8N_SECURE_COOKIE 是默认的 true，浏览器会拒绝写入 cookie。本地测试时设成 false，配了 HTTPS 之后删掉这一行。
定时任务时间不对。只设了 TZ 没设 GENERIC_TIMEZONE，定时节点按 UTC 算。两个都设成 Asia/Shanghai。
重启后容器没起来。忘了加 --restart unless-stopped 或 yml 里的 restart。服务器重启后要手动 docker start n8n。
拉镜像很慢或失败。国内网络拉 Docker Hub 经常超时，配一个镜像加速器再拉，或者用 docker pull n8nio/n8n 时耐心等，镜像有几百 MB。
中文没生效。N8N_DEFAULT_LOCALE 只影响新会话的默认语言，已有的账号要自己去设置里改。而且如前所说，只有界面外壳是中文。
先别急着暴露到公网
装完就想用手机访问，于是把 5678 端口开到公网——这是最常见的错误。n8n 里放的是你各种系统的 API Key，裸奔在公网上等于把钥匙挂在门口。
正确的做法是：先在本机或内网用，确认要长期使用后，再按下一篇的流程绑域名、上 HTTPS、用 Nginx 反代，并且只让 127.0.0.1 监听。
另外，第一次登录后就去把管理员密码改成一个强口令，别用 admin123 这种。
关于版本
n8n 每周发一个小版本。写这篇时官方文档上标的稳定版是 2.44.5，beta 是 2.45.2；我这台实例跑的是 2.43.7，界面截图都取自它。
建议：生产环境不要用 latest。把镜像钉在具体版本号上，比如 n8nio/n8n:2.44.5，要升级时改数字再拉一次。用 latest 的后果是某天重启，版本悄悄变了，工作流行为也跟着变，排查起来很费劲。
怎么看自己的版本：登录后左侧最下面进设置，或者执行 docker exec n8n n8n --version。
下一步
装好了，接下来该学工作流本身。下一篇《第一个工作流与四个核心概念》排在 10 月 28 日，发布后会出现在课程总目录里。在那之前，建议你先用今天装的这套，把上面那条三节点的例子自己敲一遍，手比眼睛记得牢。
如果你更想先搞懂「为什么值得学」，回头看看上一篇：n8n 是什么，零基础入门与应用场景。
参考资料
最后更新：2026 年 10 月 22 日。Docker 那几条命令是照官方文档核的（当时标注的稳定版是 2.44.5），截图拍自我自己那台 2.43.7。
