「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 → 完全独立服务