n8n 本地部署教學：Windows 用 Docker Desktop 安裝、更新與備份

n8n 是一個以節點連接服務、API 和資料處理步驟的工作流程自動化平台。本地部署的吸引力，是可以在自己的電腦控制運行環境、資料保存位置和更新時間；但「成功開到 localhost:5678」只代表容器開始運行，並不等於資料已持久化、服務已安全或可以公開給團隊使用。

這篇教學以 Windows 和 Docker Desktop 為主線，先跟着畫面理解安裝和啟動，再按現行 n8n 與 Docker 官方文件補回 named volume、香港時區、設定檔權限、task runners、本機連接埠、更新和備份。完成後，你會有一個可重建的本機學習環境，而不是一個只在今天可用的臨時容器。

一、本地部署值得做甚麼，也不會自動解決甚麼

資料控制：workflow、憑證和執行紀錄可以留在你管理的 Docker volume，而不是由託管平台保存。不過，workflow 連接 Gmail、CRM、LLM 或付款服務時，資料仍會傳給那些第三方；本地部署不等於資料永遠不離開電腦。

成本與彈性：你不按託管平台的執行次數付費，也可自行選版本和整合方式；代價是電腦必須保持運行，你要負責更新、備份、安全、磁碟容量和故障處理。筆記型電腦睡眠、Docker Desktop 關閉或 Windows 更新重啟，都會令排程暫停。

適合：個人學習、workflow 原型、開發測試和只在本機使用的流程。
不應直接照搬：公司多人協作、關鍵排程、公開 webhook、客戶資料或需要 24×7 可用性的正式服務。

二、安裝前檢查 Windows 和 Docker Desktop

1. 確認 Windows 版本符合 Docker Desktop 當時的系統要求，BIOS／UEFI 已啟用硬件虛擬化。
2. 按 Docker 官方 Windows 安裝指引啟用 WSL 2 或合適後端，完成安裝後重新登入或重啟。
3. 啟動 Docker Desktop，等候狀態顯示 engine running。
4. 開啟 Windows PowerShell，輸入 docker version；應同時看到 Client 和 Server，而不是只能看到 client。
5. 預留足夠磁碟空間，並確保公司代理、防火牆或 VPN 沒有阻止 Docker registry。

Docker Desktop 可在介面內查看 Containers、Images 和 Volumes。本文仍以 PowerShell 指令為準，因為指令較容易記錄、重複和審核。

三、下載時要選對平台版本

Windows 一般選 Docker Desktop for Windows。Mac 下載頁會另分 Apple Silicon 和 Intel；不要把 Mac 安裝程式或 Linux 套件套用到 Windows。安裝完成後，先用 docker run --rm hello-world 做最小測試；成功看到說明訊息，才進入 n8n。

若 hello-world 也不能運行，問題仍在 Docker Desktop、虛擬化、WSL、網絡或權限層，不應急着修改 n8n 指令。

四、先看懂啟動流程：終端、持久化、連接埠

一個可重建的 n8n 本機環境至少包含：

• 映像：docker.n8n.io/n8nio/n8n，提供應用程式。
• 容器：正在運行的 n8n process，可停止和重建。
• named volume：n8n_data，保存 /home/node/.n8n。
• 連接埠：主機 127.0.0.1:5678 對應容器 5678。
• 環境變數：時區、設定檔權限和 task runners。

重要更新：不要直接照抄畫面中的舊式簡短指令。現行 n8n 官方 Docker 指引會建立 n8n_data volume，設定 TZ 和 GENERIC_TIMEZONE，啟用 N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS 及 N8N_RUNNERS_ENABLED。本文另外把端口綁在 127.0.0.1，令這個學習環境只限本機。

五、Windows PowerShell：建立 volume 並啟動 n8n

步驟 1：建立 named volume

docker volume create n8n_data
docker volume inspect n8n_data

volume 的內容獨立於容器。停止或移除 n8n 容器，不會自動刪除這個 named volume；但執行 docker volume rm 或不加判斷地清理 volumes 仍會刪除資料。

步驟 2：貼上 PowerShell 多行指令

docker run -it --rm `
  --name n8n `
  -p 127.0.0.1:5678:5678 `
  -e GENERIC_TIMEZONE="Asia/Hong_Kong" `
  -e TZ="Asia/Hong_Kong" `
  -e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true `
  -e N8N_RUNNERS_ENABLED=true `
  -v n8n_data:/home/node/.n8n `
  docker.n8n.io/n8nio/n8n

PowerShell 的續行符號是行尾反引號 `。反引號後面不要加空格或註解；若複製後出現逐行執行或「缺少運算式」，請改用以下單行版本：

docker run -it --rm --name n8n -p 127.0.0.1:5678:5678 -e GENERIC_TIMEZONE="Asia/Hong_Kong" -e TZ="Asia/Hong_Kong" -e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true -e N8N_RUNNERS_ENABLED=true -v n8n_data:/home/node/.n8n docker.n8n.io/n8nio/n8n

六、逐個參數解釋：不要只把長指令當咒語

為甚麼同時需要兩個時區變數？ TZ 影響容器內的系統時間；GENERIC_TIMEZONE 影響 n8n 的排程節點。只設其中一個，可能出現介面、日誌和實際觸發時間不一致。

task runners 是否等於完整 sandbox？ 不是。啟用後，Code node 工作交由 runner 執行；這個單容器基線使用 internal mode。n8n 文件亦提供 external mode、認證 token、並行和 timeout 等設定，較高風險或多人正式環境要另行 harden，而不是把 N8N_RUNNERS_INSECURE_MODE 打開。

七、驗證容器真的運行，而不是只看瀏覽器

另開一個 PowerShell 視窗，依次檢查：

docker ps --filter "name=n8n"
docker port n8n
docker logs --tail 100 n8n

• docker ps 應有名為 n8n 的 running container。
• docker port n8n 應顯示主機的 127.0.0.1:5678 映射。
• logs 不應持續重啟、報 database locked、permission denied 或 migration failure。
• 第一次啟動要下載映像和建立資料，需時可能比重啟長。

Docker Desktop 的綠點很方便，但部署紀錄應同時保存實際指令、映像版本、volume 名稱和驗證結果。

八、開啟 localhost，安全建立擁有者帳戶

1. 在同一部 Windows 電腦開啟 http://localhost:5678。
2. 建立 instance owner 帳戶；使用獨立、長而隨機的密碼，不要重用公司電郵密碼。
3. 不要在教學錄影、截圖、工單或群組訊息展示真實電郵、姓名、密碼、自動填寫清單或 API key。
4. 登入後先建立一個 Manual Trigger → Edit Fields 的無敏感資料測試 workflow。
5. 執行一次、重新整理頁面、停止 n8n、再以同一指令啟動；確認帳戶和 workflow 仍存在，才算持久化測試通過。

如果停止後所有設定消失，先檢查新容器是否仍掛載 n8n_data:/home/node/.n8n；不要在未備份前反覆建立新的 volumes。

九、「只限本機」的真正意思：webhook 和排程限制

Docker 若只寫 -p 5678:5678，通常會把連接埠發布到主機所有網絡介面。Docker 官方明確提醒，公開 port 預設可能讓外部網絡存取；本文使用 127.0.0.1:5678:5678，只讓 Docker 主機打開。

• 手動 workflow：可以在本機正常建立和執行。
• Schedule Trigger：只要電腦、Docker Desktop 和 n8n 一直運行便可；睡眠或關機期間不會神奇補回所有觸發。
• Polling：視乎節點，可由 n8n 主動連外。
• 外部 webhook：第三方通常不能連入 localhost。
• OAuth callback：部分供應商不接受 localhost，亦可能需要正式 HTTPS callback URL。

需要讓互聯網或同事存取時，不要只把 IP 改成 0.0.0.0。應建立正式網域、反向代理、TLS、正確的 base URL／webhook URL、防火牆、登入與權限、秘密管理、更新、監控和備份。n8n 官方建議以反向代理處理 TLS。

十、停止、重啟和改成背景運行

使用本文的 -it --rm 基線時，在原 PowerShell 按 Ctrl+C 會停止 n8n，容器物件隨後移除；重新貼上同一條 docker run 指令，就會用同一個 volume 啟動。

如果只為本機長時間測試，可把指令開頭的 -it --rm 改成 -d --restart unless-stopped。這是操作模式調整，不是把環境變成 production：

docker stop n8n
docker start n8n
docker logs -f n8n

改參數或更新映像時，舊容器不能原地修改完整啟動設定；做法是先備份、停止、移除容器，再以相同 volume 和新參數重建。移除容器時不要把 n8n_data 一併刪除。

十一、更新 n8n：先知道版本、再備份、最後重建

1. 在 n8n release notes 和 Docker 安裝文件確認目標版本、breaking changes 和相容要求。
2. 記錄目前映像：docker inspect n8n --format "{{.Config.Image}}"。
3. 完整備份 n8n_data，並測試可以還原到另一個 volume。
4. 停止並移除舊容器；named volume 保留。
5. 拉取穩定版或指定版本：docker pull docker.n8n.io/n8nio/n8n。
6. 以原本的時區、權限、runner、port 和 volume 參數重建。
7. 檢查 logs、登入、憑證、手動 workflow、排程和 webhook。

正式環境宜使用明確版本 tag 並經過 staging 測試；「永遠拉最新」會把更新時間和風險交給未知變化。資料庫完成 migration 後，單純改回舊 image 不一定安全，真正 rollback 通常需要可驗證的更新前備份。

十二、備份 named volume，並做一次還原演習

只匯出 workflow JSON 不足以還原完整 instance。/home/node/.n8n 可能包含 SQLite 資料庫、credentials 相關資料、encryption key 和其他設定。以下 PowerShell 範例先停止寫入，再把 volume 打包到目前資料夾：

docker stop n8n
docker run --rm `
  -v n8n_data:/data:ro `
  -v "${PWD}:/backup" `
  alpine `
  sh -c "tar czf /backup/n8n-data-backup.tar.gz -C /data ."

若你使用前景 --rm 模式，先在原終端按 Ctrl+C。備份檔應移到另一個受保護位置，設定保留期和存取權限；只留在同一部電腦、同一顆磁碟不算災難復原。

還原到新 volume 測試，不要直接覆蓋原本資料

docker volume create n8n_restore_test
docker run --rm `
  -v n8n_restore_test:/data `
  -v "${PWD}:/backup:ro" `
  alpine `
  sh -c "tar xzf /backup/n8n-data-backup.tar.gz -C /data"

然後以另一個容器名稱、另一個主機 port 和 n8n_restore_test:/home/node/.n8n 啟動，確認可以登入、打開 workflow 和解密憑證。測試完成後才決定保留或刪除測試 volume。每次更新前備份但從不還原測試，風險仍然很高。

十三、正式使用前的安全清單

• 本機學習保持 127.0.0.1 綁定；公開服務使用 TLS 反向代理和防火牆。
• 擁有者帳戶使用獨立強密碼，按可用功能啟用 2FA，避免共用管理員帳戶。
• API key、OAuth secret 和資料庫密碼不要寫入 workflow 名稱、截圖、PowerShell history 或公開 compose 檔。
• 只安裝受信任、經審查的 community nodes；按需要封鎖 Execute Command、Read/Write Files 等高風險節點。
• 限制 workflow 會讀取、傳送和保留哪些個人或公司資料；設定 execution data 保留和刪除政策。
• 保留 N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true，不要為消除警告而關閉保護。
• 保留 task runners 的安全預設；多人或不受信任 code 要研究 external mode 和 runner hardening。
• 定期執行 n8n security audit，檢查未使用 credentials、危險 nodes、未受保護 webhooks 和過時版本。
• 備份 volume、部署指令、映像版本和外部秘密；加密備份並測試還原。

十四、常見問題快速排查

到這裏，你已不只是「把 n8n 跑起來」，而是建立了一個有持久化資料、正確香港時區、基本安全邊界、可更新和可還原的 Windows 學習環境。下一步可先做一個完全不含真實資料的 workflow，練習 Manual Trigger、Edit Fields、If 和 HTTP Request；等你能解釋每項資料會去哪裏，再接入正式帳戶和業務系統。