简介这是一份面向开发者与技术爱好者的N8N本地部署可运行资源包解决开源自动化工具从零安装、环境配置与二次开发入门问题。资源共4个文件压缩包约12KB包含Docker安装脚本、N8N代码库配置、环境说明与HTML介绍页类型轻量但覆盖部署关键环节便于快速跑通自动化工作流。已有207人学习下载适合需要搭建自有集成流程的初中级开发者。通过阅读和修改源码可深入理解N8N的节点类型、工作流设计及架构思路为后续复杂场景如企业流程自动化、IT运维数据处理打下基础。1. 本地部署 N8N一份能跑起来的源码包比云版省下的不止是月费N8N 这个可视化工作流工具真正用起来之后你会发现瓶颈不在功能而在数据安全和调度自由度。把业务数据交给云端意味着每次 webhook 触发都绕不开第三方服务器而自托管 N8N 之后工作流执行、凭证存储、定时任务全部落在自己机器上。这份「N8N 本地部署教程[可运行源码]」不是简单的安装文档它把 Docker 编排、源码启动、数据库初始化、凭证加密这些环节都拆开摆好了下载下来照着跑就能起来一个生产可用的实例。适合两类人一是公司内部要做流程自动化的运维或后端二是个人开发者想在自己的服务器上搭一套永远不限额的自动化中枢。下文按我实际踩坑的顺序写从部署前选型一直讲到企业级参数调优。2. 部署前准备Docker Compose 还是源码运行先想清楚再动手2.1 两种部署路径的取舍N8N 本地部署主流有两条路Docker Compose 拉起镜像以及用源码包直接跑。源码包的优势在于可以改内部逻辑、加自定义节点、调试时看堆栈更直接但编译和依赖管理成本高。Docker 部署则是生产环境最稳的方案升级回滚都方便而且这份源码包里已经写好了 docker-compose.yml相当于把最常见部署姿势固化成了模板。我一般建议第一次接触、只想快速看到工作流跑起来的人选 Docker Compose后面要二次开发、要写自己的 n8n 节点再切到源码模式。两条路共用一个前置条件——机器上要有 Docker 和 Docker Compose。如果你用的是国内云服务器别在这上面省事直接装官方源里的 docker-ce 和 docker-compose-plugin。2.2 资源规划别拿 1G 内存的小鸡硬扛N8N 本身是 Node.js 应用启动后内存占用比想象中高。空载实例大概占 250M 左右一旦跑复杂工作流尤其是并发 webhook 或者带大模型节点时内存会飙到 1G 以上。数据库方面N8N 默认用 SQLite但生产环境强烈建议切到 PostgreSQL后面讲 docker-compose 配置时会说明原因。资源项最低要求推荐配置备注CPU1 核2 核及以上工作流多时 CPU 会周期性满载内存1G4G含 PostgreSQL 和 Redis磁盘10G30G日志和 executions 数据增长很快系统Ubuntu 20.04 / Debian 11同左其他发行版问题不大2.3 源码包拿到手先看什么解压这份源码包之后第一件事不是急着跑而是看目录结构。合格的 N8N 源码包应该包含几个关键部分根目录的 docker-compose.yml、.env.example 环境变量模板、还有 packages 目录下的核心代码。如果压缩包里直接给你一个打包好的 build 目录那就要确认是不是和你的 Node 版本匹配。我先说 Docker 这条路径因为 90% 的人用这份源码包都是为了快速部署而不是改源码。3. 从零到可运行Docker Compose 部署步骤与配置解析3.1 编写 docker-compose.yml关键环境变量不能省这份源码包里自带的 docker-compose.yml 通常已经能直接用但是环境变量必须按自己机器改。下面是一个我实际用过的配置模板重点不在抄而在每个变量为什么这么设version: 3.8 services: n8n: image: n8nio/n8n container_name: n8n restart: unless-stopped ports: - 127.0.0.1:5678:5678 environment: - N8N_HOSTyour-domain.com - N8N_PORT5678 - N8N_PROTOCOLhttps - N8N_ENCRYPTION_KEYrandom-32-char-secret - DB_TYPEpostgresdb - DB_POSTGRESDB_HOSTpostgres - DB_POSTGRESDB_DATABASEn8n - DB_POSTGRESDB_USERn8n - DB_POSTGRESDB_PASSWORDstrong-password - N8N_PUBLIC_API_ENABLEDtrue - N8N_PUBLIC_API_DISABLEDfalse - GENERIC_TIMEZONEAsia/Shanghai volumes: - n8n_data:/home/node/.n8n networks: - n8n_net depends_on: - postgres postgres: image: postgres:15 container_name: n8n-postgres restart: unless-stopped environment: - POSTGRES_USERn8n - POSTGRES_PASSWORDstrong-password - POSTGRES_DBn8n volumes: - postgres_data:/var/lib/postgresql/data networks: - n8n_net volumes: n8n_data: postgres_data: networks: n8n_net: driver: bridgeN8N_HOST 决定了回调 URL 和 webhook 的拼接地址如果填 localhost 后续所有外部触发都会出问题这里必须填最终要访问的域名或 IP。N8N_ENCRYPTION_KEY 是凭证加密的种子一旦部署完成就不能改否则所有已保存的 credentials 都解密失败这条后面避坑章会细说。端口绑定写成 127.0.0.1:5678:5678 而不是直接 5678:5678是为了让 Nginx 反代在前面挡一层避免 N8N 裸奔到公网。3.2 数据库从 SQLite 切到 PostgreSQL 的理由源码包的默认环境变量如果没配 DB_TYPEN8N 会走 SQLite。本地测试没问题但生产环境有两个硬伤一是 SQLite 单文件并发写能力弱多个工作流同时写 executions 表会锁库二是数据备份必须停服务做不到热备。PostgreSQL 是 N8N 官方测试最充分的组合配合上面的 compose 文件depends_on 确保先起数据库再起 N8N。启动之前先建好 .env 文件把 compose 里写死的敏感信息抽出来。我的习惯是给 compose 里加 env_file 引用这样后续多环境切换只改一个 .env不用动 yaml 文件。3.3 首次启动与验证在源码包解压目录下执行docker compose up -d docker compose ps docker logs -f n8n第一个命令后台拉起全部服务第二个命令看容器状态第三个命令跟踪日志。等一下看到Editor is now accessible via http://localhost:5678就说明起来了。注意第一次启动要耐心等 30 秒左右因为要初始化 PostgreSQL 表结构别看到几秒没日志就 CtrlC 重来那会留下半初始化的数据目录。打开浏览器访问http://服务器IP:5678注册管理员账号。这里有一个所有人都容易忽略的步骤注册完第一个账号后立刻到设置里生成 API Key 并测试一次公共 API。因为后面做 webhook 触发、对接外部系统全靠这个 API Key 认证等工作流多了再回来开 API 会非常折腾。4. 源码模式运行pnpm 安装与构建细节4.1 源码包里的 packages 目录怎么读Docker 路径能满足一多半需求但如果你要改 n8n 源码、加自定义节点就得走源码模式。这份源码包的 packages 目录下有几个核心模块cli 是主进程core 是工作流引擎editor-ui 是前端界面。改前端的时候要单独编译 editor-ui改后端逻辑则要重新跑 cli build。需要提醒的是源码包和 Docker 镜像里的代码不是完全等价的。镜像里跑的是打包后的产物源码包则是未编译的 TypeScript。所以源码模式第一步是安装依赖并编译编译失败通常是因为 Node 版本不对。N8N 对 Node 版本要求很挑我用下来 Node 18 和 20 兼容性最好Node 21 以上经常在 node-gyp 环节报错。4.2 本地编译与启动命令源码包根目录一般会有 package.json 和 pnpm-workspace.yaml。先确认包管理器N8N 用的是 pnpm 而不是 npm直接用 npm install 会报 workspace 依赖错误。# 安装 pnpm如果机器上没有 npm install -g pnpm8 # 安装依赖在源码根目录 pnpm install --frozen-lockfile # 构建核心模块 pnpm build:backend pnpm build:frontend # 启动开发模式带热重载 pnpm dev--frozen-lockfile是必须的它严格按照 lock 文件装版本不然后装出来的依赖树和源码包预期不一致。pnpm build:backend会编译 cli 和 core 两个包生成 dist 目录。启动之后如果看到Starting n8n...但端口没监听多半是数据库连接串没配好。4.3 源码模式的环境变量配置源码模式和 Docker 模式的环境变量完全通用但源码模式更依赖 .env 文件。在根目录创建 .env 后重点配置数据库和加密密钥N8N_ENCRYPTION_KEYyour-random-key-here DB_TYPEpostgresdb DB_POSTGRESDB_HOST127.0.0.1 DB_POSTGRESDB_PORT5432 DB_POSTGRESDB_DATABASEn8n DB_POSTGRESDB_USERn8n DB_POSTGRESDB_PASSWORDstrong-password N8N_USER_MANAGEMENT_JWT_SECRETjwt-secret-change-meN8N_USER_MANAGEMENT_JWT_SECRET 在源码模式下尤其重要它负责用户登录态的签发生效。如果这个值在重启后变了所有已登录用户会被强制下线。和 ENCRYPTION_KEY 一样这两个密钥一旦确定就要固化到部署脚本里绝不能每次启动随机生成。源码模式跑起来之后验证方式和 Docker 路径一样但看日志更清晰——Node 进程直接输出到终端报错时能定位到具体行号这是做二次开发时最大的便利。5. 本地部署 N8N 避坑六个真实踩过的坑5.1 忘记管理员密码后只能动数据库现象登录页一直提示密码错误邮箱验证又没配 SMTP进不了控制台。原因N8N 没有内置的密码重置命令官方 UI 也没有“忘记密码”入口。解决直接操作数据库里的 user 表。先进入 PostgreSQL 容器然后用 SQL 把目标用户的密码清空并标记为需要重置docker exec -it n8n-postgres psql -U n8n -d n8nUPDATE user SET password NULL, resetToken NULL WHERE email adminexample.com;然后重启 N8N用该邮箱登录时会直接进入设置新密码的流程。注意 SQL 语句里表名和字段名用双引号因为 N8N 的表结构是 camelCase不加引号会报列不存在。5.2 更换服务器后所有 credentials 全部解密失败现象从旧机器备份数据恢复到新机器后工作流还在但每个凭证节点都报 Invalid credentials。原因N8N 用 N8N_ENCRYPTION_KEY 对 credentials 做 AES 加密备份数据只备份了数据库没有备份 .env 里的密钥。新机器用了新的随机密钥自然解不开旧数据。解决迁移时必须把旧服务器的 N8N_ENCRYPTION_KEY 原样带到新服务器而不是重新生成。我在迁移脚本里显式读取旧 .env 的 N8N_ENCRYPTION_KEY然后写入新环境的配置。如果密钥已经丢了那只有一条路——手动重建所有 credentials这个坑没有后悔药。5.3 定时任务永远差 8 小时现象工作流里设了每天早上 8 点触发实际执行时间是下午 4 点。原因N8N 容器默认时区是 UTCN8N 的 cron 表达式按容器时区解析但界面显示时间又按浏览器时区两边不一致。解决在环境变量里明确设置GENERIC_TIMEZONEAsia/Shanghai同时给容器加TZAsia/Shanghai。这两个缺一不可GENERIC_TIMEZONE 控制 N8N 内部调度TZ 控制 Node 进程系统时区。改完重启后看 Schedule Trigger 节点里显示的时间是否和本地一致。5.4 反向代理后 webhook 链接 404现象Nginx 配好 SSL 之后工作流里的 webhook 测试链接一直 404直接访问http://IP:5678却正常。原因N8N 生成的 webhook 回调地址是根据请求头里的 Host 拼的。Nginx 转发时如果没有保留原始 HostN8N 就会用内部容器名生成链接。解决Nginx 反代配置里加两行proxy_set_header Host $host; proxy_set_header X-Forwarded-Proto $scheme;同时 N8N 侧要设置N8N_HOST为对外域名N8N_PROTOCOL为 https。这一步属于典型的“玄学”问题表象在 N8N根子在代理层。5.5 升级版本后数据库 schema 不兼容现象从 0.214 升到 1.x执行docker compose pull后拉起新镜像启动日志报找不到某张表或某列。原因N8N 版本升级会执行 migration但如果你跨大版本跳级旧版数据可能缺少新版迁移脚本的前置条件。解决不要跳级升级。依次升级到中间版本并启动一次让它跑完各自的迁移。升级前用docker compose down干净停止再备份 postgres_data 卷。我个人习惯是先docker run一个 postgres 容器连旧数据卷做导出但更省事的是直接用 pg_dump 把整个库倒在外部文件里出问题还能回滚。5.6 内存被 Executions 数据拖垮现象跑了几个月的实例内存持续走高明明没几个活跃工作流。原因N8N 默认保存所有执行记录每次执行都会把输入输出 JSON 完整写入数据库webhook 密集调用时数据增长极快。解决在 .env 里设置执行数据保留策略EXECUTIONS_DATA_PROVIDERpostgresdb EXECUTIONS_DATA_MAX_SIZE100mb EXECUTIONS_DATA_PRUNEtrue EXECUTIONS_DATA_MAX_AGE168EXECUTIONS_DATA_PRUNEtrue开启自动清理MAX_AGE168表示保留 7 天单位小时。设完重启后观察几天内存曲线通常能降下来 30% 以上。6. 进阶用环境变量做多环境隔离一套源码包管住 dev 和 prod部署稳定之后下一个问题就是怎么让同一份源码包既能在本地开发机跑又能在线上服务器跑。我的做法是把所有环境差异收敛进三个文件.env.dev、.env.prod、.env.shared。共享部分放 N8N_ENCRYPTION_KEY 和基础端口差异部分放数据库地址、日志级别和 API 开关。实际执行时不再手动改环境变量而是写一个启动脚本按参数加载对应 env 文件#!/bin/bash ENV${1:-dev} COMPOSE_FILEdocker-compose.yml ENV_FILE.env.$ENV docker compose --env-file $ENV_FILE -f $COMPOSE_FILE up -d这里的--env-file是 Docker Compose 原生的变量注入机制优先级低于 compose yaml 里的 environment 字段。所以 compose 文件里凡是会变动的变量一律用${VAR}引用不要在 environment 里写死。比如前面的模板改成environment: - N8N_HOST${N8N_HOST} - DB_POSTGRESDB_PASSWORD${DB_POSTGRESDB_PASSWORD}这样切环境只需要改 env 文件不会出现“测试环境配置被带到生产”的翻车事故。另一个建议是把加密密钥单独放一个文件不纳入 git 版本管理因为密钥一旦进了提交历史散播出去就是泄露风险。验证多环境是否正确生效最直接的方法不是看页面而是调公共 API。在 dev 环境调/api/v1/workflows看到的是开发库里的工作流在 prod 环境看到的是另一个集合就说明数据库隔离生效了。从那以后我每次做部署都强制走一遍这套流程先检查 env 文件是否存在再 docker compose config 渲染出最终配置最后起来之后看健康检查接口确认无误再交接给业务方。这套习惯救了我好几次希望你部署这份源码包的时候也能用上希望帮到你。本文还有配套的精品资源点击获取