n8n 1.x 升級到 2.x 完整指南：那些官方沒說清楚的

前言

n8n 是一套熱門的開源自動化工作流平台，許多人選擇用 Docker 自架部署。2024 年底 n8n 發布了 2.0 大版本，帶來了不少改進，但同時也引入了多項破壞性變更。如果你正在考慮從 1.x 升級到 2.x，這篇文章整理了官方文件中的重點，以及一些實際升級時容易踩到的坑，希望能幫你省下不少除錯時間。

升級前必讀：官方 Breaking Changes

根據 n8n v2.0 官方文件，以下是最關鍵的破壞性變更：

1. MySQL / MariaDB 不再支援

這是影響最大的改動。n8n 2.0 完全移除了 MySQL 和 MariaDB 的支援，僅保留 PostgreSQL 和 SQLite 兩種資料庫選項。

如果你目前使用 MySQL，升級前必須先將資料遷移到 PostgreSQL，否則 n8n 2.x 會直接以 SQLite 啟動一個全新實例，看起來就像資料全部消失了。

2. Docker 映像架構調整

n8n 2.x 的 Docker 映像為了安全性做了精簡（類似 distroless），移除了 apk 套件管理器。如果你有自建 Dockerfile 來擴充 n8n（例如安裝 Chromium、Python、ffmpeg 等），這會直接導致建置失敗。

3. 其他變更

移除了舊版 SQLite driver，改用 pooling driver
部分 API 和環境變數有調整
儲存目錄預計在 v3 從 .n8n/binaryData 改名為 .n8n/storage

完整清單請參考官方文件。

常見問題與解決方案

問題一：`apk: not found`

升級到 2.x 後，自建的 Dockerfile 在安裝套件時報錯：

/bin/sh: apk: not found

你可能會直覺以為官方換成了 Debian 映像，改用 apt-get，但實際上 n8n 2.x 仍然是 Alpine-based，只是移除了套件管理器。

解決方式： 先用 apk-tools-static 恢復套件管理器：

FROM n8nio/n8n:2.x.x

USER root

# 恢復 apk 套件管理器
RUN ARCH=$(uname -m) && \\
    wget -qO- "<http://dl-cdn.alpinelinux.org/alpine/latest-stable/main/${ARCH}/>" | \\
    grep -o 'href="apk-tools-static-[^"]*\\.apk"' | head -1 | cut -d'"' -f2 | \\
    xargs -I {} wget -q "<http://dl-cdn.alpinelinux.org/alpine/latest-stable/main/${ARCH}/{}>" && \\
    tar -xzf apk-tools-static-*.apk && \\
    ./sbin/apk.static add apk-tools && \\
    rm -f apk-tools-static-*.apk

# 之後就能正常使用 apk
RUN apk update && apk add --no-cache chromium python3 ffmpeg ...

參考： n8n Issue #23246、n8n Issue #23603

問題二：升級後資料全部消失

打開 n8n 發現出現「Set up owner account」畫面，所有 workflow 和 credential 都不見了。

原因： 你的 docker-compose.yml 中仍然設定 DB_TYPE=mysqldb，但 n8n 2.x 已不支援 MySQL，於是自動 fallback 到 SQLite 並建立全新實例。你的資料還在 MySQL 裡，只是 n8n 讀不到了。

解決方式： 需要進行資料庫遷移，詳見下方完整遷移步驟。

MySQL 遷移到 PostgreSQL 完整步驟

步驟一：在 n8n 1.x 環境匯出資料

升級前，先用 n8n 1.x 匯出所有資料。如果你已經升級到 2.x，可以用臨時容器來匯出：

docker run --rm \\
  -v /path/to/n8n-data:/home/node/.n8n \\
  -v /path/to/backup:/home/node/backup \\
  -e DB_TYPE=mysqldb \\
  -e DB_MYSQLDB_HOST=your_mysql_host \\
  -e DB_MYSQLDB_PORT=3306 \\
  -e DB_MYSQLDB_DATABASE=n8n \\
  -e DB_MYSQLDB_USER=your_user \\
  -e DB_MYSQLDB_PASSWORD=your_password \\
  -e N8N_ENCRYPTION_KEY=your_encryption_key \\
  n8nio/n8n:1.70.3 \\
  export:workflow --all --separate --output=/home/node/backup/workflows/

docker run --rm \\
  -v /path/to/n8n-data:/home/node/.n8n \\
  -v /path/to/backup:/home/node/backup \\
  -e DB_TYPE=mysqldb \\
  -e DB_MYSQLDB_HOST=your_mysql_host \\
  -e DB_MYSQLDB_PORT=3306 \\
  -e DB_MYSQLDB_DATABASE=n8n \\
  -e DB_MYSQLDB_USER=your_user \\
  -e DB_MYSQLDB_PASSWORD=your_password \\
  -e N8N_ENCRYPTION_KEY=your_encryption_key \\
  n8nio/n8n:1.70.3 \\
  export:credentials --all --separate --decrypted --output=/home/node/backup/credentials/

注意事項：

步驟二：準備 PostgreSQL 資料庫

在你的 PostgreSQL 伺服器上建立新資料庫：

CREATE DATABASE n8n;

步驟三：更新 docker-compose.yml

將資料庫設定改為 PostgreSQL：

# 移除舊的 MySQL 設定
# - DB_TYPE=mysqldb
# - DB_MYSQLDB_HOST=...

# 新增 PostgreSQL 設定
- DB_TYPE=postgresdb
- DB_POSTGRESDB_HOST=your_postgres_host
- DB_POSTGRESDB_PORT=5432
- DB_POSTGRESDB_DATABASE=n8n
- DB_POSTGRESDB_USER=your_user
- DB_POSTGRESDB_PASSWORD=your_password

同時記得移除 depends_on 中對 MySQL 容器的依賴（如果有的話）。

步驟四：啟動 n8n 2.x 並匯入資料

部署 n8n 2.x 後，它會自動初始化 PostgreSQL schema，然後匯入資料：

# 匯入 workflows
docker exec -u node n8n n8n import:workflow --all --separate --input=/path/to/backup/workflows/

# 匯入 credentials
docker exec -u node n8n n8n import:credentials --all --separate --input=/path/to/backup/credentials/

步驟五：設定 Owner 帳號

n8n 的匯出/匯入不包含使用者帳號，第一次登入會出現設定畫面，這是正常的。建立 owner 帳號後，匯入的 workflows 和 credentials 會自動歸屬到該帳號。

快速除錯對照表

注意事項

執行歷史紀錄（Execution History）無法遷移，升級後會遺失
N8N_ENCRYPTION_KEY 在整個遷移過程中必須保持一致，否則 credentials 無法正確解密
建議先在測試環境完成遷移驗證，再操作正式環境
升級前務必備份 MySQL 資料庫，以便遇到問題時能退回 1.x

前言