n8n 學習地圖

n8n 2.0 升級與維護教學

這章整理自高見龍的 n8n 2.0 升級文章，並對照 n8n 官方文件後改寫成教材。
判斷結果：這不適合只塞進部署章的一小節，因為它牽涉大版本升級、Task Runner、安全預設、資料庫、舊節點與維護流程，應該獨立成一章。

想一想

升級 n8n 不是「把版本號改新」而已。對初學者來說，升級看起來像技術維護，但其實它會直接影響 workflow 能不能繼續穩定執行。你原本能跑的 Code node，升級後可能因為 Python runner、環境變數權限或安全預設改變而出錯；你原本習慣按 Save 就上線，到了新版本可能變成 Save 和 Publish 分離；你原本用 SQLite、binary data 或舊節點，也可能遇到行為改變。

所以升級的核心心法是：不要把 production 當測試場。先知道新版本改了什麼，再檢查自己的 workflow 有沒有踩到 breaking changes，備份資料，跑 migration report，找一條低風險 workflow 試跑，最後才升正式環境。n8n 2.0 的價值是更安全、更可維護、更適合正式使用；但前提是你要用維運思維升級，而不是用「按一下更新」的心態升級。

1. 為什麼這篇要獨立成一章

11 n8n 雲端與地端部署教學 已經教你 n8n 要放在哪裡跑。
但升級是另一種能力。

部署關心：

  • n8n 跑在哪裡
  • 資料怎麼保存
  • Webhook 怎麼公開
  • HTTPS、Postgres、備份怎麼設

升級關心：

  • 新版本改了什麼
  • 哪些 workflow 會受影響
  • 哪些環境變數預設改了
  • 哪些舊節點不能用了
  • 升級前怎麼檢查
  • 升級後怎麼驗收

一句話： 部署是把 n8n 放上去；升級是讓 n8n 長期不壞地往前走。

2. n8n 2.0 的兩個大重點

高見龍文章中抓出的兩個核心重點很值得放進教材：

  1. Save / Publish 分離
  2. Task Runner 成為更重要的執行機制

2.1 Save / Publish 分離

以前的直覺是：

Save = 存檔並影響線上流程

新版本更接近：

Save = 儲存草稿
Publish = 正式上線

這對正式 workflow 很重要。
因為你可以先修改、測試、保存進度，不會因為手滑 Save 就把半成品推到 production。

2.2 Task Runner

Task Runner 是 n8n 用來執行 Code node 中使用者程式碼的機制。
官方文件說明 Task Runner 讓 JavaScript / Python code 能以更安全、效能更好的方式執行。

你可以先這樣理解：

以前：Code node 比較靠近 n8n 主程式跑
現在：Code node 可以交給 runner 隔離執行

對正式環境來說，隔離很重要。
因為一段寫壞的 Code node 不應該拖垮整個 n8n。

3. Save / Publish 對 workflow 維護的影響

Save / Publish 分離讓 workflow 維護更像軟體發布。

舊思維：

改 workflow -> Save -> 線上立即改變

新思維：

改 workflow -> Save 草稿 -> 測試 -> Publish 上線

升級後，你應該建立一個小流程：

修改 -> Save -> Manual test -> Test webhook -> Check output -> Publish -> Production test

不要把 Save 當成完成。
要把 Publish 當成真正上線。

4. Workflow History 與回復觀念

n8n 官方文件說明，workflow history 可以查看與還原過去版本。
它和 execution history 不一樣。

Workflow history = workflow 設計稿版本
Execution history = workflow 執行紀錄

升級前後都要能回答：

  • 如果 workflow 改壞，能不能回復上一版？
  • 如果某次執行失敗，能不能看出是哪筆資料造成？
  • 如果升級後出錯，能不能先回到原本版本？

5. Task Runner：先懂 Internal 與 External

官方文件把 Task Runner 分成兩種模式：

模式適合特點
Internal mode開發、測試n8n 主程式啟動 child process，隔離較低
External mode正式環境獨立 sidecar container，隔離較完整

Internal mode

好處：

  • 設定簡單
  • 適合本機測試
  • 不需要額外 container

限制：

  • 官方不建議 production 使用
  • 權限隔離較弱
  • Python Code node 支援會受限制

External mode

好處：

  • runner 與 n8n 主程式分開
  • 比較符合正式環境安全需求
  • 可以支援 Python runner
  • 可以獨立限制 runner 資源

限制：

  • Docker Compose 設定較複雜
  • runner image 版本要和 n8n image 一致
  • 需要設定 shared auth token

一句話： 學習環境可以先 internal；正式環境應該理解 external。

6. External Task Runner 的概念配置

概念架構：

n8n container
  -> task broker
  -> runners sidecar container
  -> execute JS / Python code

Docker Compose 概念：

services:
  n8n:
    image: n8nio/n8n:2.x.x
    environment:
      - N8N_RUNNERS_ENABLED=true
      - N8N_RUNNERS_MODE=external
      - N8N_RUNNERS_BROKER_LISTEN_ADDRESS=0.0.0.0
      - N8N_RUNNERS_AUTH_TOKEN=replace_with_random_secret
 
  task-runners:
    image: n8nio/runners:2.x.x
    environment:
      - N8N_RUNNERS_TASK_BROKER_URI=http://n8n:5679
      - N8N_RUNNERS_AUTH_TOKEN=replace_with_random_secret
    depends_on:
      - n8n

注意：

  • n8nio/n8n 和 n8nio/runners 版本要一致
  • N8N_RUNNERS_AUTH_TOKEN 兩邊要一致
  • token 不要寫進公開 repo
  • production 不要使用隨便的短字串

7. Python Code node 的升級重點

n8n 2.0 對 Python Code node 的影響很大。
高見龍文章指出，2.0 移除 Pyodide-based Python，若沒有設定 Task Runner，Python 可能無法正常執行。

如果你沒有用 Python Code node

升級風險較低，但仍要測 JavaScript Code node。

如果你有用 Python Code node

升級前一定要檢查：

  • 是否啟用 Task Runner
  • 是否使用 External mode
  • runner image 版本是否一致
  • Python 套件是否可用
  • 是否需要自訂 runner image

如果你只是做一般資料整理

能不用 Python 就先不用。
很多資料轉換可以用：

  • Edit Fields
  • IF / Switch
  • Code JavaScript
  • Item Lists / Aggregate
  • AI structured extraction

8. 安全預設改變

n8n 2.0 的方向是更安全的預設值。
這是好事，但也會讓舊 workflow 升級後遇到行為差異。

常見影響：

改變可能影響
Code node 預設不能讀環境變數舊程式若讀 process.env 可能失敗
Execute Command 預設停用依賴 shell command 的 workflow 會壞
Local File Trigger 預設停用本機檔案觸發流程可能失效
OAuth callback 預設要求認證特定嵌入或 callback 情境需檢查
settings file 權限檢查權限不對可能啟動警告或失敗
檔案存取限制讀寫非允許目錄可能失敗

不要看到錯誤就立刻把安全設定全部關掉。
先問：這個 workflow 為什麼需要這個權限？能不能改成更安全的方式？

9. 被移除或改變的東西

升級前要特別檢查：

Start Node

舊 Start node 要改：

舊做法新做法
手動開始Manual Trigger
被其他 workflow 呼叫Execute Workflow Trigger

MySQL / MariaDB 作為 n8n 自身資料庫

n8n 2.0 不再支援 MySQL / MariaDB 作為 n8n 自身的 database backend。
注意：這不是說 MySQL node 不能用，而是指 n8n instance 自己儲存 workflow / execution / credentials 的資料庫。

n8n --tunnel

2.0 移除 --tunnel。
本機測 webhook 可以改用：

  • ngrok
  • localtunnel
  • Cloudflare Tunnel

10. SQLite、binary data 與檔案處理

高見龍文章提到 n8n 2.0 對 SQLite 與 binary data handling 有改善。
官方 breaking changes 也列出移除 in-memory binary data mode。

Binary data 指：

  • PDF
  • 圖片
  • Excel
  • 音檔
  • 其他非純文字檔案

升級後要檢查：

  • workflow 是否處理大檔案
  • binary data 存在哪裡
  • queue mode 是否需要共享儲存
  • volume 是否有備份

如果 workflow 常處理檔案，升級後一定要做檔案流程測試。

11. 升級前檢查表

升級前請逐項確認：

  • 已備份 database
  • 已備份 /home/node/.n8n
  • 已保存 N8N_ENCRYPTION_KEY
  • 已匯出重要 workflow JSON
  • 已記錄目前 n8n 版本
  • 已記錄 Docker image tag
  • 已檢查是否有 Start node
  • 已檢查是否使用 MySQL / MariaDB 作為 n8n database
  • 已檢查是否使用 Python Code node
  • 已檢查是否使用 Execute Command
  • 已檢查是否使用 Local File Trigger
  • 已檢查是否依賴 process.env
  • 已檢查 webhook production URL
  • 已準備 rollback 方式

如果你答不出 rollback 怎麼做，不要升 production。

12. 建議升級流程

Step 1. 先升到支援 Migration Report 的 1.x 版本

高見龍文章提到，建議先到 1.121.0 以上，使用 migration report。

Step 2. 跑 Migration Report

在 n8n 管理介面中檢查升級風險。
Critical 一定要先處理。

Step 3. 修 workflow

處理：

  • Start node
  • retired nodes
  • 不支援資料庫
  • Python Code node
  • 安全預設會影響的節點

Step 4. 測 Task Runner

如果有 Code node，先測：

  • JavaScript Code node
  • Python Code node
  • runner 是否啟動
  • runner log 是否正常

Step 5. 備份

至少備份：

  • database
  • n8n volume
  • .env
  • encryption key
  • workflow JSON

Step 6. 升級到 2.x

Docker Compose 常見方式：

docker compose pull
docker compose down
docker compose up -d

正式環境建議 pin 版本，不要盲目使用 latest。

Step 7. 升級後驗收

至少測：

  • 登入
  • credentials
  • production webhook
  • schedule trigger
  • Google Sheets / API / OpenAI 等關鍵節點
  • Code node
  • Error workflow
  • 一條最重要的 production workflow

13. 升級後常見問題

Publish 按鈕不能按

可能原因：

  • workflow 沒有變更
  • workflow 有錯誤
  • 必填設定未完成

Python runner unavailable

代表 Python Code node 需要 Task Runner。
處理方式：

  • 檢查 N8N_RUNNERS_ENABLED
  • 檢查是否 external mode
  • 檢查 n8nio/runners container
  • 檢查 runner 版本是否與 n8n 一致

Execute Command 不能用

2.0 安全預設可能停用。
先確認是否真的需要 shell command。能改 API 或內建 node 就不要開。

workflow 跑到一半資料不同

檢查：

  • Save / Publish 是否弄混
  • 是否測到草稿而不是已發布版本
  • execution history 是哪個版本跑的

14. 新手如何吸收這篇升級文章

如果你現在還在學 workflow，不需要立刻全部會。
你只要先記住 5 件事：

  1. 2.0 是大版本，升級前要檢查
  2. Save 和 Publish 分離，正式上線前要 Publish
  3. Code node 尤其 Python 會牽涉 Task Runner
  4. 安全預設變嚴格，舊 workflow 可能需要調整
  5. 正式環境升級前一定要備份與測試

等你開始 self-host 或維護正式 workflow，再回來細讀這章。

15. 本章練習

練習 1：盤點自己的 workflow

workflow 名稱：
是否 production：
是否有 Webhook：
是否有 Code node：
是否有 Python：
是否有 Execute Command：
是否有 Local File Trigger：
是否處理檔案：
升級風險：

練習 2：寫一份升級計畫

目前版本：
目標版本：
備份方式：
測試 workflow：
rollback 方法：
預計停機時間：
驗收項目：

練習 3：設計發布流程

Edit -> Save -> Test -> Review -> Publish -> Production smoke test

16. 參考資料