你提到的 **“n8ni”** 是一个**拼写错误**，正确名称是 **`n8n`**（读作 *“n-eight-n”*），由 [n8n.io](https://n8n.io) 开发的开源低代码工作流自动化平台。 而你真正想问的是： > ✅ **如何使用 `docker run` 命令启动 n8n，并同时加载自定义节点（Custom Nodes）？** > （即：让 `n8n` 容器识别并显示你开发的 JSONPath、HTTP Advanced、Database Connector 等自定义节点） 下面我将用 **最简、最可靠、生产可用的方式**，从零开始完整演示 👇 ✅ 包含：目录结构、挂载命令、权限修复、验证步骤、常见报错解决； ✅ 所有命令可直接复制粘贴执行； ✅ 适配 Linux（Ubuntu/CentOS/Debian）+ Docker 20.10+； ✅ 不依赖 docker-compose，纯 `docker run`。 --- ## ✅ 第一步：准备自定义节点目录（宿主机上） 假设你要加载一个名为 `n8n-node-jsonpath` 的自定义节点（你已开发好），结构如下： ```bash ~/n8n-custom-nodes/ ├── jsonpath-node/ │ ├── package.json # 必须含 "n8n": { "nodes": ["dist/JsonPathDescription.js"] } │ ├── dist/ │ │ └── JsonPathDescription.js # 编译后 CommonJS 文件（关键！） │ └── src/ │ └── JsonPathDescription.ts ``` > 🔑 关键要求（否则容器内加载失败）： > - `package.json` 中必须有 `"n8n": { "nodes": ["dist/JsonPathDescription.js"] }` 字段； > - `dist/JsonPathDescription.js` 必须是 **CommonJS 格式**（`module.exports = {...}`），不能含 `export default`； > - 文件路径大小写严格匹配（Linux 区分大小写）； > - `dist/` 目录需存在且非空（运行 `npx tsc` 编译生成）。 ✅ 验证命令（在宿主机执行）： ```bash ls -l ~/n8n-custom-nodes/jsonpath-node/package.json cat ~/n8n-custom-nodes/jsonpath-node/package.json | jq '.n8n' ls -l ~/n8n-custom-nodes/jsonpath-node/dist/JsonPathDescription.js ``` --- ## ✅ 第二步：使用 `docker run` 启动 n8n 并挂载自定义节点 ### ✅ 最小可行命令（带详细注释）： ```bash docker run -d \ --name n8n-with-custom \ --restart unless-stopped \ -p 5678:5678 \ -v ~/.n8n:/home/node/.n8n \ # 持久化数据（凭证、工作流、设置） -v ~/n8n-custom-nodes:/home/node/.n8n/custom \ # 🌟 核心！挂载自定义节点目录 -e N8N_BASIC_AUTH_ACTIVE=true \ -e N8N_BASIC_AUTH_USER=admin \ -e N8N_BASIC_AUTH_PASSWORD=123456 \ -e N8N_HOST=localhost \ -e N8N_PORT=5678 \ -e WEBHOOK_URL=http://localhost:5678 \ --user $(id -u):$(id -g) \ # 🌟 关键！避免权限问题（见下方解释） --log-opt max-size=10m --log-opt max-file=3 \ n8nio/n8n:1.45.0 ``` ### ✅ 命令逐项解释： | 参数 | 说明 | |------|------| | `-v ~/n8n-custom-nodes:/home/node/.n8n/custom` | ⚠️ **核心挂载**：将宿主机 `~/n8n-custom-nodes` 映射为容器内 `/home/node/.n8n/custom`，n8n 启动时自动扫描此目录下所有含 `n8n.nodes` 的 `package.json` | | `--user $(id -u):$(id -g)` | ✅ **必须添加**！官方镜像中 n8n 以 `node` 用户（UID 1001）运行，若挂载目录属主是 root（如 `sudo chown -R 1001:1001` 未做），会导致 `EACCES` 权限拒绝。用 `--user` 强制以当前用户 UID/GID 运行，彻底规避权限问题 | | `-v ~/.n8n:/home/node/.n8n` | 持久化数据库（SQLite）、凭据加密密钥、用户设置等 | | `n8nio/n8n:1.45.0` | **强烈建议指定精确版本号**（不要用 `latest`），避免意外升级导致兼容性问题 | > 💡 提示： > - `~/n8n-custom-nodes` 下可放多个节点文件夹（如 `jsonpath-node/`, `mysql-node/`），n8n 会全部加载； > - 若你只想挂载单个节点（不建子目录），可改为：`-v ~/n8n-custom-nodes/jsonpath-node:/home/node/.n8n/custom/jsonpath-node`； > - 挂载后，容器内路径必须是 `/home/node/.n8n/custom/xxx`，这是 n8n **硬编码的扫描路径**（源码中 `CUSTOM_EXTENSION_DIR = pathJoin(N8N_DEFAULT_DIR, 'custom')`）。 --- ## ✅ 第三步：验证自定义节点是否加载成功 ### ▶️ 1. 查看容器日志（最关键！） ```bash docker logs -f n8n-with-custom ``` ✅ 成功日志（必须看到）： ```log INFO: Loading custom node modules from: /home/node/.n8n/custom INFO: Loading custom node module: jsonpath-node INFO: Custom node "jsonPathExtractor" loaded successfully ``` ❌ 失败日志及修复： | 日志 | 原因 | 修复 | |------|------|------| | `Loading custom node modules from: /home/node/.n8n/custom`<br>但无后续 `Loading custom node module` | `~/n8n-custom-nodes/` 下没有合法 `package.json`（或 `n8n.nodes` 字段缺失） | `cat ~/n8n-custom-nodes/jsonpath-node/package.json \| jq '.n8n'` → 必须输出 `{ "nodes": ["dist/..."] }` | | `Error: EACCES: permission denied, access '/home/node/.n8n/custom'` | 权限问题（最常见！） | ✅ 加 `--user $(id -u):$(id -g)`；或 `chown -R $USER:$USER ~/n8n-custom-nodes` | | `Cannot find module 'n8n-workflow'` | `dist/JsonPathDescription.js` 中引用了 `n8n-workflow`（错误！它只应出现在 `devDependencies`） | 删除 `dist/`，重新 `npx tsc`，确保 `tsconfig.json` 中 `"module": "commonjs"` | ### ▶️ 2. 进入容器检查文件是否存在 ```bash docker exec -it n8n-with-custom ls -l /home/node/.n8n/custom/jsonpath-node/ # 应看到 package.json 和 dist/ 目录 docker exec -it n8n-with-custom cat /home/node/.n8n/custom/jsonpath-node/package.json | jq '.n8n' ``` ### ▶️ 3. 在 Web UI 中确认 - 访问 `http://localhost:5678` → 登录； - 点击左下角 `➕ Add Node` → 搜索 `jsonPath`； - ✅ 应出现你的节点（如 `JSON Path Extractor`）； - ❌ 若没出现 → 回头检查日志和 `package.json.n8n.nodes` 路径。 --- ## ✅ 第四步：进阶技巧（提升稳定性与可观测性） ### 🔹 技巧 1：启用调试日志（排查加载失败） ```bash docker run -d \ ... \ -e LOG_LEVEL=debug \ # 输出更详细日志（含 custom node 加载过程） n8nio/n8n:1.45.0 ``` ### 🔹 技巧 2：挂载日志目录便于审计 ```bash mkdir -p ~/n8n-logs docker run -d \ ... \ -v ~/n8n-logs:/home/node/.n8n/logs \ # n8n 会自动写日志到此 n8nio/n8n:1.45.0 ``` ### 🔹 技巧 3：强制重新加载（无需重启容器） > n8n 支持热重载 custom nodes（v1.39+），只需向容器发送 `SIGUSR2`： ```bash docker kill -s SIGUSR2 n8n-with-custom # 然后看日志：INFO: Reloading custom nodes... ``` --- ## 🚫 常见错误速查表 | 现象 | 原因 | 一行修复命令 | |------|------|----------------| | `docker logs` 显示 `Loading custom node modules from: ...` 但无后续 | `package.json` 缺 `n8n.nodes` 字段 | `echo '"n8n": {"nodes": ["dist/JsonPathDescription.js"]}' >> ~/n8n-custom-nodes/jsonpath-node/package.json` | | 节点在 UI 中显示但点击报错 `Cannot find module` | `dist/` 中 JS 是 ES Module（含 `export`） | `rm -rf dist/ && npx tsc`（确保 `tsconfig.json` 中 `"module": "commonjs"`） | | 容器启动失败，报 `permission denied` | 挂载目录属主不是容器内用户 | `sudo chown -R 1001:1001 ~/n8n-custom-nodes` 或 ✅ 用 `--user $(id -u):$(id -g)` | | 自定义节点名在 UI 中显示为 `undefined` | `description.name` 字段为空或含非法字符（空格/大写） | `cat dist/JsonPathDescription.js \| grep name` → 必须是 `name: "jsonPathExtractor"`（全小写+驼峰） | --- ## ✅ 最终验证清单（执行完这 4 步即成功） ```bash # 1. 启动容器（带 --user） docker run -d --name n8n-test --user $(id -u):$(id -g) -p 5678:5678 -v ~/n8n-custom-nodes:/home/node/.n8n/custom n8nio/n8n:1.45.0 # 2. 查日志确认加载 docker logs n8n-test | grep -i "custom\|jsonpath" # 3. 检查节点文件 docker exec n8n-test ls -l /home/node/.n8n/custom/jsonpath-node/dist/ # 4. 打开浏览器 http://localhost:5678 → 搜索节点名 ``` ✅ 全部通过 → 你的自定义节点已成功集成！ --- 如果你遇到具体报错（例如日志截图、`docker inspect` 输出、`package.json` 内容），欢迎贴出来，我可以 **逐行帮你定位哪一行配置错了**。 ---