「n8n 2.x + Task Runners + 原生 Python」自托管完整部署示例
下面给你一套可直接照抄、可跑通的「n8n 2.x + Task Runners + 原生 Python」自托管完整部署示例。
这是目前唯一官方认可的、真正“在 Code 节点里直接写 Python”的方式。
我会按 原理 → 部署 → 验证 → 常见坑 的顺序来，避免你踩雷。
一、先明确一件事（非常关键）
在 n8n 2.x 中：
Python Code Node ≠ 主 n8n 容器执行
Python Code Node = Task Runner 容器执行
也就是说：
- n8n 主服务：不跑 Python
- Python：只在 Task Runner 里跑
- 两者通过 内部 RPC 通信
二、整体架构（你部署后会是这样）
┌──────────────┐ │ n8n main │ (UI / Workflow / Orchestration) │ │ │ Code Node │ └──────┬───────┘ │ Task execution ┌──────▼──────────────────┐ │ n8n Task Runner │ │ (Python / JS sandbox) │ │ │ │ ✔ Python 3.x │ │ ✔ 执行 Code Node(Python)│ └──────────────────────────┘ 三、完整 Docker Compose（可直接用）
1️⃣ 目录结构建议
n8n/ ├─ docker-compose.yml ├─ .env 2️⃣ .env 文件
N8N_BASIC_AUTH_ACTIVE=true N8N_BASIC_AUTH_USER=admin N8N_BASIC_AUTH_PASSWORD=admin123 N8N_ENCRYPTION_KEY=change_this_to_random_string DB_TYPE=sqlite （你可以后面再换 Postgres）
3️⃣ docker-compose.yml（重点）
version: "3.9" services: n8n: image: n8nio/n8n:2 container_name: n8n restart: always ports: - "5678:5678" env_file: - .env environment: # 开启 task runners - N8N_RUNNERS_ENABLED=true # 使用 external 模式（必须） - N8N_RUNNERS_MODE=external # runner 通信 - N8N_RUNNERS_AUTH_TOKEN=super-secret-token - N8N_RUNNERS_TIMEOUT=300 # 基本设置 - GENERIC_TIMEZONE=Asia/Shanghai volumes: - n8n_data:/home/node/.n8n depends_on: - n8n-runner n8n-runner: image: n8nio/runners:latest container_name: n8n-runner restart: always environment: - N8N_RUNNERS_AUTH_TOKEN=super-secret-token - N8N_RUNNERS_GRACEFUL_SHUTDOWN_TIMEOUT=30 volumes: - runner_data:/data volumes: n8n_data: runner_data: ⚠️ token 必须一致，否则 Code Node 无法执行
4️⃣ 启动
docker compose up -d 浏览器访问：
http://localhost:5678 四、在 Code Node 中使用 Python（验证）
1️⃣ 新建 Workflow → 添加 Code 节点
2️⃣ Language 选择：
👉 Python (Native)
（如果你看不到 Python，说明 Runner 没连上）
3️⃣ 示例 Python 代码（100% 可跑）
items = [] for item in _items: value = item["json"].get("value", 0) items.append({ "json": { "original": value, "result": value * 2 } }) return items 4️⃣ 输入示例（Set Node）
{ "value": 10 } 5️⃣ 输出结果
{ "original": 10, "result": 20 } ✔️ 这是原生 Python，不是 Pyodide，不是 CLI
五、Python Code Node 的重要规则（必须知道）
1️⃣ 可用变量
| 名称 | 含义 |
|---|---|
_items | 输入 items |
item["json"] | JSON 数据 |
return items | 输出 |
❌ 不支持 $json.xxx
❌ 不支持 JS 写法
2️⃣ Python 标准库
- 支持大多数 标准库
- ❌ 默认 不带第三方库（pandas / numpy）
六、如何支持第三方 Python 库（进阶）
方式：自定义 Runner 镜像（官方推荐）
1️⃣ Dockerfile
FROM n8nio/runners:latest RUN pip install pandas numpy 2️⃣ 构建
docker build -t n8n-runner-python:latest . 3️⃣ compose 中替换
n8n-runner: image: n8n-runner-python:latest 七、常见问题（90% 卡在这里）
❌ 看不到 Python 选项
- Runner 没启动
- Token 不一致
N8N_RUNNERS_MODE不是external
❌ 报 No runner available
- runner 容器未连上
- 防火墙 / 网络问题
❌ pandas / numpy import error
- runner 镜像没装库
- 不支持运行时 pip install
八、你现在到底“能做到什么程度”
你现在已经可以：
- ✅ 在 Code Node 直接写 Python
- ✅ 不用 HTTP
- ✅ 不用 Execute Command
- ✅ 不污染 n8n 主容器
- ✅ 官方支持、可升级
但仍要注意：
- ❌ 不适合长时间任务
- ❌ 不适合重 ML / GPU
- ❌ Runner 是“受控执行环境”
九、给你的真实建议（结合你的使用深度）
- 轻数据处理 / Schema / 逻辑判断 → Python Code Node ✅
- pandas / AI / 批处理 → Python Service + HTTP
- 大规模 AI / 向量 / GPU → 完全独立服务
