n8n Runner 用法
在 2.0.0 以後，官方推薦使用 Runner 作為執行 Code 的執行的地方。
與 n8n 執行環境隔離，在執行效能，與安全上，有所提升。
有幾個地方要設定
n8n 主程式的環境變數
enviroment:
- N8N_RUNNERS_ENABLED=true
- N8N_RUNNERS_MODE=external # 使用 external 表示
- N8N_RUNNERS_BROKER_LISTEN_ADDRESS=0.0.0.0 # 允許 Runner 接入 n8n
- N8N_RUNNERS_AUTH_TOKEN=隨機的Token
- N8N_NATIVE_PYTHON_RUNNER=true # 啟用 Python Coderunner
n8n_runners:
image: n8nio/runners:2.0.0
environment:
- N8N_RUNNERS_TASK_BROKER_URI=http://n8n:5679 # 預設 runner 接入的 port
- N8N_RUNNERS_LAUNCHER_LOG_LEVEL=debug
- N8N_RUNNERS_AUTH_TOKEN=test # 與主程式相同的隨機 Token如此一來，在 2.0 版本中，執行 Code 就會透過 runner 去執行 JS 或 Python
其 runner docker 源碼是 https://github.com/n8n-io/task-runner-launcher
主程式完整可用環境變數如下：
1. N8N_RUNNERS_MODE
型別： internal | external
用途： 決定 Task Runner 以哪種模式執行。
- internal：由 n8n 主進程直接 spawn 子進程。
- external：Runner 以獨立程序方式存在（例如 Kubernetes sidecar），需自行啟動。
2. N8N_RUNNERS_PATH
型別： string
用途： Runner 用來連線至 n8n broker 的 endpoint 路徑（URL path 部分）。
預設： /runners
3. N8N_RUNNERS_AUTH_TOKEN
型別： string
用途： Runner 與 broker 之間的認證 token，用來確保只有允許的 runner 能連線。
預設： 空字串（非生產環境可接受，正式環境應設定）。
4. N8N_RUNNERS_BROKER_PORT
型別： number
用途： Broker（主進程）對 Runner 監聽的連接埠。
預設： 5679
5. N8N_RUNNERS_BROKER_LISTEN_ADDRESS
型別： string
用途： Broker 綁定的 IP。
127.0.0.1限本機0.0.0.0對外部網路可用（Docker / K8s 常用）
6. N8N_RUNNERS_MAX_PAYLOAD
型別： number（bytes）
用途： n8n 傳給 Runner 的最大 payload 大小。
預設： 1GB
用於限制大型任務避免耗盡記憶體。
7. N8N_RUNNERS_MAX_OLD_SPACE_SIZE
型別： string（MB）
用途： 提供給 Runner 的 Node.js --max-old-space-size 設定，控制記憶體上限。
預設： 空字串 → 由 Node.js 自行決定。
8. N8N_RUNNERS_MAX_CONCURRENCY
型別： number
用途： 單一 Runner 可同時執行的任務數量。
預設： 10（維持舊版相容性）
n8n v2 計畫調整至 5。
9. N8N_RUNNERS_TASK_TIMEOUT
型別： number（秒）
用途：
- 單 task 最大執行時間（timeout）。
- timeout 時，task 會被強制停止。
- internal 模式下，Runner 也會被完全重啟。
預設： 300 秒（5 分鐘）
10. N8N_RUNNERS_TASK_REQUEST_TIMEOUT
型別： number（秒）
用途： Task 排隊等候 Runner 可用的最長時間。若超過就直接報錯。
預設： 60 秒
11. N8N_RUNNERS_HEARTBEAT_INTERVAL
型別： number（秒）
用途： Runner 向 broker 送出 heartbeat 的頻率。
若超過間隔未收到 heartbeat，broker 會認為 runner 掛掉並終止任務。
預設： 30 秒
12. N8N_RUNNERS_INSECURE_MODE
型別： boolean（true / false）
用途：
在 Runner 中停用所有安全限制。除非必要，不建議在生產環境啟用。
用途多為：
- 舊 code 依賴不安全 JS 特性
- 需要繞過 sandbox 限制
預設： false
Runner 端環境變數解釋
1. N8N_RUNNERS_GRANT_TOKEN
用途：
啟動器（launcher）向 n8n 主系統進行一次性授權交換時所使用的「單次授權 token」。
流程簡述：
- Runner 啟動 → 派出 launcher
- 主系統回傳 single-use grant token
- 此 token 用於換取正式 auth token（或建立信任）
- 使用一次後即失效（防重放、提升安全性）
主要目的：
確保 Runner 啟動流程安全，不讓不存在的或未經允許的 Runner 冒充加入。
2. N8N_RUNNERS_TASK_BROKER_URI
用途：
Runner 要連線至 Task Broker（主進程或 sidecar broker）的完整 URI。
典型格式可能是：
ws://127.0.0.1:5679/runners
或在 K8s 中：
ws://n8n-broker.default.svc.cluster.local:5679/runners
它是 Runner 的 主要指令通道，用來接收：
- 任務指派
- heartbeats
- 控制訊息（停止、取消、重啟等）
3. N8N_RUNNERS_HEALTH_CHECK_SERVER_ENABLED
用途：
是否啟用 Runner 的本地「健康檢查 HTTP 伺服器」。
值通常為：
"true""false"
啟用後，Runner 會起一個短小的 HTTP server 提供：
- readiness / liveness check
- K8s 或 Docker healthcheck 可直接打這個端點
用途：
- 監控 Runner 是否正常運作
- 自動重啟掛掉或卡住的 Runner
4. N8N_RUNNERS_HEALTH_CHECK_SERVER_PORT
用途：
健康檢查伺服器要綁定的埠號。
搭配 N8N_RUNNERS_HEALTH_CHECK_SERVER_ENABLED 使用。
範例：
N8N_RUNNERS_HEALTH_CHECK_SERVER_PORT=8080
Kubernetes 會利用它進行 livenessProbe / readinessProbe。
5. N8N_RUNNERS_AUTO_SHUTDOWN_TIMEOUT
單位：秒
用途：
Runner 若在指定秒數內沒有接收到任何任務，就會自動關閉（退出進程）。
作用：
- 避免空閒 runner 長期佔用資源
- 雲端環境（K8s、serverless）可用於節省費用
典型例子：
N8N_RUNNERS_AUTO_SHUTDOWN_TIMEOUT=120 // 2 分鐘無任務就自動結束
6. N8N_RUNNERS_TASK_TIMEOUT
單位：秒
用途：
Runner 端對單一 task 的最大允許執行時間。
若超時：
- 該 task 強制中斷
- 若與主端設定同名，Runner 端會覆寫本地限制（或作為補充邏輯）
典型用途：
- 避免無窮迴圈或卡死的任務
- 多層保護，與主系統的
N8N_RUNNERS_TASK_TIMEOUT一起運行
範例：
N8N_RUNNERS_TASK_TIMEOUT=300
