[課程成果]搬家：n8n 部署全攻略

官方來源核對

本週只採用官方文件作為事實基礎，避免把部落格、二手整理或平台行銷話術直接當成部署決策。讀這一節時，請把每一列當成後續章節的判斷前提。

一頁部署選項矩陣

第一週的核心判斷不是「哪個平台最好」，而是「哪個平台的責任剛好匹配目前需求」。n8n Cloud 把最多維運責任交給 n8n；local Docker 把學習成本降到最低；VPS + Compose 在控制、成本與理解度之間取得平衡；PaaS 用平台能力換取部分維運簡化；hyperscaler 與 Kubernetes 則用複雜度換取企業級控制。

需求判斷流程

使用這張流程時，不要從平台名稱開始選，而是從需求責任開始問。每一個答案都會把你推向更合適的部署路線。

流程圖使用規則

這張表把流程圖中的關鍵分岔整理成可操作的問題。每次評估一個 n8n 部署需求，都先逐列回答，再把答案對應回部署選項。

必備風險詞彙

這些詞不是背誦用，而是部署前的檢查語言。只要你開始談 production，就要能用這些詞拆解責任。

擴充風險詞彙

這些詞會在後續週次反覆出現。Week 01 先建立語言，後面再把它們落到 Docker、PostgreSQL、Tunnel、VPS、PaaS、backup 與 scaling 的具體操作。

官方來源核對

本週只採用官方文件作為事實基礎。尤其是 state 與 encryption key，不能靠印象處理。每一列都是後面「搬家清單」的依據。

單一 instance 的核心運作

n8n 的 browser/editor 與 webhook endpoint 都會回到同一個 application process；process 再讀寫 database、user folder、binary data storage，並呼叫 external APIs。credential records 在 database 裡，但解密依賴 encryption key。

Docker 單機學習模式

Docker learning mode 的重點是：container 可以刪掉重建，但 n8n_data volume 不可以被當成暫存物。若使用預設 SQLite，database file 與 encryption key 都會落在 .n8n 這個 state boundary 裡。

Production-shaped self-hosted 模式

Production-shaped 模式要把三層分清楚：public edge 負責接 internet traffic，n8n application process 負責執行 workflow，state layer 負責保存 workflow、credential、execution、binary data 與 encryption material。三層任何一層錯，都會讓同一個 workflow 呈現不同錯誤。

Queue mode 的概念位置

Queue mode 是 Week 16 才深入的擴展主題。本週只建立一個基本觀念：只要同一個 n8n deployment 有多個 main 或 worker process，所有 process 都必須共享能讀取 credentials 的同一組 encryption key，並共同指向一致的 database state。

核心 State Inventory 上半部

這張表是 Week 02 最重要的搬家清單。每一個 state 項目都要回答：用途是什麼、存在哪裡、能不能重建、遺失後會怎樣、誰要備份。

核心 State Inventory 下半部

n8n 的 state 不只在 database。user folder、community nodes、environment variables、public URL 與 proxy config 都會影響「搬家後能不能照常運作」。

優先保護順序

保護順序的重點是先保住不可等價重建的東西。workflow export 很有用，但它不能取代 database、encryption key 與 volume。

State Boundary 判斷表

這張表把常見遷移、重建與擴展情境拆成「要保存什麼」與「不保存會怎樣」。這就是 Week 03 備份責任表的前置資料。

風險卡 01-02

Credential loss 通常不是「credential 不見了」這麼單純，而是 database、key、volume、URL 或 storage 其中一層失配。

風險卡 03-04

風險卡 05：Community nodes 消失

實務檢查表

這張表可以直接拿來檢查任何一個 n8n deployment。只有全部通過，才可以說自己知道這個 instance 的 state 在哪裡。

官方來源核對：Database、CLI 與 Export

本週只採用官方文件作為事實基礎。資料保存與備份不能靠平台印象或「應該會在某處」來判斷。

官方來源核對：Execution、Binary Data 與 Source Control

這一頁補上資料成長、binary data mode、queue mode 與 source control 邊界。這些都是 Week 03 不能被簡化的資料安全細節。

一頁決策表

這張表的重點不是說 SQLite 不好，而是把它放在正確位置：學習、短期測試、低風險單 instance。只要進入長期 public automation，PostgreSQL 就應該成為 production-like baseline。

決策流程圖

不可犯錯的判斷

Production self-host n8n 最小備份內容：P0

production self-host n8n 的備份不是單一檔案，而是一組 recovery bundle。這一頁先列 P0：缺少任一項，就可能無法恢復可用服務。

Production self-host n8n 最小備份內容：P1-P2

P1 與 P2 不是不重要，而是它們通常依 workload 與維運成熟度決定深度。binary-heavy workflow 與 community nodes 一旦存在，就不能被視為可忽略。

Backup coverage matrix

這張矩陣的關鍵訊息很直白：任何單一 export 幾乎都不是完整備份。唯一能當 recovery baseline 的，是完整 recovery bundle。

最小備份流程圖

備份時機

Binary-heavy 的定義與 mode 判斷表

Binary-heavy workflow 是大量處理 file-type data 的 workflow，例如圖片、PDF、文件、壓縮檔、音訊、影片、附件、爬蟲下載檔案、AI 生成檔案、OCR 或報表輸出。它的風險不是 workflow 節點多，而是檔案 payload 會佔用 memory、disk、database 或 external storage。

Binary-heavy 風險卡

Binary-heavy checklist

實務檢查表

這張表可以直接用來檢查一個 n8n instance 是否已具備基本資料安全意識。若任一項不明確，就表示還不能進正式導入。

官方來源核對：n8n URL 與 Webhook

本週只採用官方文件作為事實基礎。公開 URL 問題不能靠「瀏覽器打得開」就判定成功。

官方來源核對：OAuth、DNS、TLS 與 Proxy

OAuth callback、DNS record、Caddy reverse proxy 與 TLS certificate 是同一條 public edge 路徑的不同層。任何一層錯，都會讓外部服務回不到 n8n。

一張總圖

排查 public URL 問題時，請照層級往內查。不要一看到 webhook 或 OAuth 失敗就先改 workflow node。

排查總結

排查順序：DNS 到 n8n public URL

排查順序：Webhook、OAuth 與 Workflow Layer

n8n URL 變數矩陣

正確公開 URL 心智模型

public URL 的正確性不是單點設定，而是 DNS、TLS、reverse proxy、forwarded headers、n8n env vars 和 provider callback 六層一起正確。

OAuth callback 正確性檢查表：Provider 與 Base URL

OAuth callback 正確性檢查表：Proxy、TLS 與 Scopes

OAuth callback 排查流程

Provider 設定範例

不可犯錯的 OAuth 判斷

DNS/TLS Glossary：DNS 與 TLS

DNS/TLS Glossary：Proxy、Webhook 與 OAuth

實務檢查表

這張表可以直接拿來驗收 public URL 是否真的 ready。全部通過前，不要把問題歸咎於 workflow node。

官方來源核對

本週只採用官方文件作為安裝與驗證依據。Docker Desktop 是本機 runtime；n8n 的 workflows、credentials、settings 與 encryption key 需要留在 persistent volume 才能跨 container 重建保存。

5.3.1 實測環境

這一頁保留本週實際環境值。後續若要重跑 Week 05，先比對 Docker 版本、image tag、container name、volume name 與 mount path。

5.3.4 匯入 persistence probe workflow

測試 workflow 檔案：artifacts/week-05-persistence-workflow.json。這個 probe 用來在重建 container 後確認 workflow 仍能由 n8n CLI 匯出。

docker run --rm --name n8n-week5-import \
  -e GENERIC_TIMEZONE=Asia/Taipei \
  -e TZ=Asia/Taipei \
  -e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true \
  -e N8N_RUNNERS_ENABLED=true \
  -v n8n_data:/home/node/.n8n \
  -v /Users/linshangche/Desktop/projects/nuva-report/artifacts/week-05-persistence-workflow.json:/tmp/week-05-persistence-workflow.json:ro \
  docker.n8n.io/n8nio/n8n \
  import:workflow --input=/tmp/week-05-persistence-workflow.json

Importing 1 workflows
Successfully imported 1 workflow.

5.3.5 啟動 n8n container

本週以官方 n8n image 啟動單一 container，將本機 5678 對到 container 5678，並將 n8n_data 掛到 /home/node/.n8n。

docker run -d --name n8n-week5-local \
  -p 5678:5678 \
  -e GENERIC_TIMEZONE=Asia/Taipei \
  -e TZ=Asia/Taipei \
  -e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true \
  -e N8N_RUNNERS_ENABLED=true \
  -v n8n_data:/home/node/.n8n \
  docker.n8n.io/n8nio/n8n

aa3a92326847edea6ff41de72f358a8fc70f59ad1923195f8cae4ec0615310c3

curl -s -o /dev/null -w '%{http_code}' http://localhost:5678

200

5.3.6 匯入 persistence probe credential

測試 credential 檔案：artifacts/week-05-persistence-credential.json。credential probe 只使用 dummy data，不包含真實 API key、OAuth token 或客戶資料。

docker cp /Users/linshangche/Desktop/projects/nuva-report/artifacts/week-05-persistence-credential.json n8n-week5-local:/tmp/week-05-persistence-credential.json
docker exec n8n-week5-local n8n import:credentials --input=/tmp/week-05-persistence-credential.json

Successfully imported 1 credential.

5.4.4 Container 與 Volume 的責任邊界

這張表是 Week 05 的核心心智模型：container 是執行層，volume 是狀態層。把兩者混在一起，就會誤以為 container 刪掉還能自動保留資料。

5.5.1 驗證流程

本週使用「刪除並重建 container」作為 persistence 驗證。這符合第 5 週驗收條件中的「重啟 Docker Desktop 或重建 container 後，workflow 與 credential 仍存在」。

5.5.2 重建 container 命令

停止舊 container、刪除舊 container，然後用同一個 n8n_data volume 重建。

docker stop n8n-week5-local
docker rm n8n-week5-local

docker run -d --name n8n-week5-local \
  -p 5678:5678 \
  -e GENERIC_TIMEZONE=Asia/Taipei \
  -e TZ=Asia/Taipei \
  -e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true \
  -e N8N_RUNNERS_ENABLED=true \
  -v n8n_data:/home/node/.n8n \
  docker.n8n.io/n8nio/n8n

重建後 container id：

4a1ae7f019d1e4669201c3d91a834bb8a604a2cbbc861ba656cd32a1421c3a84

重建後 HTTP readiness：

http_status=200
container=4a1ae7f019d1 name=n8n-week5-local status=Up 5 seconds ports=0.0.0.0:5678->5678/tcp, [::]:5678->5678/tcp

5.5.5 驗收結論

5.6.1 最少摩擦路線：啟動階段

5.6.1 最少摩擦路線：Persistence 驗證階段

5.6.2 正確與錯誤 mount 對照

5.6.3 第 5 週不可犯錯清單

15 秒版本

8.1-8.6 啟動、停止、查看狀態、logs、匯出

docker start n8n-week5-local

docker stop n8n-week5-local

docker ps --filter name='^/n8n-week5-local$'

docker logs --tail=120 n8n-week5-local

docker exec n8n-week5-local n8n export:workflow --all

docker exec n8n-week5-local n8n export:credentials --all

Week 05 完成檢查

npm route 官方來源

本週只採用官方文件作為事實基礎。npm 路線不是錯；它的價值是快。真正要分清楚的是：快啟動不等於長期可維運。

npx、Docker、Volume 與 State 官方來源

這一頁補上 npx 的快啟動機制，以及 Docker / volume / N8N_USER_FOLDER 在 state boundary 上的差異。

3.3 npm/npx 實測觀察

4.1 總表：啟動、污染、版本與依賴

4.1 總表：升級、rollback、資料與 key

4.1 總表：public URL、監督、port、團隊與場景

4.2 一句話判斷

5.1.3 用 npx 短暫啟動 n8n

本週沒有直接使用 default ~/.n8n，而是指定獨立 N8N_USER_FOLDER，避免污染使用者真正的 n8n state。因第 5 週 Docker container 已占用 5678，本週 npm/npx route 使用 5686。

N8N_USER_FOLDER=/Users/linshangche/Desktop/projects/nuva-report/artifacts/week-06-npm-user-folder \
N8N_PORT=5686 \
GENERIC_TIMEZONE=Asia/Taipei \
TZ=Asia/Taipei \
N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true \
N8N_RUNNERS_ENABLED=true \
npx --yes n8n start

No encryption key found - Auto-generating and saving to: /Users/linshangche/Desktop/projects/nuva-report/artifacts/week-06-npm-user-folder/.n8n/config
n8n ready on ::, port 5686
Version: 2.22.4
Editor is now accessible via:
http://localhost:5686

6.1 npm quick start 何時有價值

6.2 停止訊號：credentials、public URL、OAuth、uptime、team

6.2 停止訊號：upgrade、rollback、executions、nodes、monitoring

6.3 核心原因 1-5

6.3 核心原因 6-10

7.1 何時用哪條路線

7.2 npm 與 Docker 的 state map

7.3 升級與 rollback 心智模型

15 秒版本

Week 06 完成檢查

Compose、environment、volumes 與 depends_on

本週只採用官方文件作為事實基礎。Compose 的任務是讓 multi-container stack 變成可以閱讀、重建與交接的 YAML。

n8n PostgreSQL、encryption key 與 Postgres image

這一頁補上 n8n database environment variables、固定 encryption key，以及 Postgres 官方 image 的初始化變數。

3.3 PostgreSQL-backed 證據

database_name | database_user | public_table_count
n8n_week7     | n8n_week7     | 93

credentials_entity
execution_entity
migrations
workflow_entity

id                   | name                      | active
week07PostgresProbe  | Week 07 PostgreSQL Probe  | f

http_status_after_restart=200
workflow_count=1
migration_count=184

4.1 Compose 檔完整內容

name: n8n-week7

services:
  postgres:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB"]
      interval: 5s
      timeout: 5s
      retries: 20
    volumes:
      - postgres_data:/var/lib/postgresql/data

  n8n:
    image: docker.n8n.io/n8nio/n8n:2.22.4
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    ports:
      - "5687:5678"
    environment:
      DB_TYPE: postgresdb
      DB_POSTGRESDB_HOST: postgres
      DB_POSTGRESDB_PORT: 5432
      DB_POSTGRESDB_DATABASE: ${POSTGRES_DB}
      DB_POSTGRESDB_USER: ${POSTGRES_USER}
      DB_POSTGRESDB_PASSWORD: ${POSTGRES_PASSWORD}
      N8N_ENCRYPTION_KEY: ${N8N_ENCRYPTION_KEY}
      N8N_HOST: ${N8N_HOST}
      N8N_PORT: ${N8N_PORT}
      N8N_PROTOCOL: ${N8N_PROTOCOL}
      GENERIC_TIMEZONE: ${GENERIC_TIMEZONE}
      TZ: ${TZ}
      N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS: "true"
    volumes:
      - n8n_data:/home/node/.n8n

volumes:
  postgres_data:
  n8n_data:

4.2 project、services 與 postgres service

4.2 Postgres 初始化與 healthcheck

4.2 volumes、n8n service、depends_on 與 ports

4.2 n8n database variables

4.2 runtime variables 與 top-level volumes

4.3 架構圖

4.4 啟動順序圖

5.1 .env 檔內容

POSTGRES_DB=n8n_week7
POSTGRES_USER=n8n_week7
POSTGRES_PASSWORD=week7_local_postgres_password_do_not_reuse
N8N_ENCRYPTION_KEY=week7_fixed_local_encryption_key_2026_05_27_do_not_reuse
N8N_HOST=localhost
N8N_PORT=5678
N8N_PROTOCOL=http
GENERIC_TIMEZONE=Asia/Taipei
TZ=Asia/Taipei

5.4 n8n runtime 變數

6.5 PostgreSQL 查詢

database 與 table count：

select
  current_database() as database_name,
  current_user as database_user,
  count(*) filter (where schemaname = 'public') as public_table_count
from pg_tables;

database_name=n8n_week7
database_user=n8n_week7
public_table_count=93

必要 tables：

select tablename
from pg_tables
where schemaname='public'
  and tablename in ('workflow_entity','credentials_entity','execution_entity','migrations')
order by tablename;

credentials_entity
execution_entity
migrations
workflow_entity

6.6 workflow probe 寫入 PostgreSQL

匯入命令：

docker cp artifacts/week-07-compose/week-07-postgres-workflow.json n8n-week7-n8n-1:/tmp/week-07-postgres-workflow.json
docker compose --env-file artifacts/week-07-compose/.env -f artifacts/week-07-compose/compose.yaml exec -T n8n n8n import:workflow --input=/tmp/week-07-postgres-workflow.json

Importing 1 workflows
Successfully imported 1 workflow.

PostgreSQL 查詢：

select id, name, active
from workflow_entity
where id='week07PostgresProbe';

week07PostgresProbe | Week 07 PostgreSQL Probe | f

restart n8n 後：

workflow_count=1

7.1 比單一 container 更像 production 的原因

7.2 仍不是完整 production 的原因

15 秒版本

Week 07 完成檢查

Webhook、WEBHOOK_URL、deployment env 與 Quick Tunnel

Named tunnel、ngrok、Tailscale Funnel 與 DDNS

短時間公開、完成測試、立刻收回

learning-only 與 production-ready candidate

reserved/custom domain、Funnel、DDNS

決策圖

外部 POST production webhook 測試

實際回應摘要

{
  "ok": true,
  "week": 8,
  "probe": "public-webhook",
  "tunnel": "cloudflare-quick-tunnel",
  "receivedSource": "week08-external-post",
  "receivedWeek": 8,
  "publicHost": "gif-decent-pharmacies-eligibility.trycloudflare.com",
  "forwardedProto": "https",
  "checkedDate": "2026-05-27"
}

learning-only vs production-ready

Week 08 完成檢查

Pricing、execution quota、data 與 concurrency

更新、匯出與 Projects / RBAC

Cloud first 的典型情境

Cloud first 的邊界與例外

Cloud-first 判斷圖

低量與中量 schedule / webhook 估算

執行量估算的核心規則很簡單：production execution 是 workflow 自動被 trigger、schedule、polling 或 webhook 啟動的一次完整執行。manual testing 不計入 paid execution quota，但仍會吃 instance memory。

高峰 webhook、chatbot、AI 與 manual testing

估算公式

入口、資料、金鑰、更新與 quota

concurrency、retention、custom runtime 與事故責任

Cloud 方案快照

補充限制