n8n Docker Compose 安裝踩坑紀錄：新手最常卡的 5 個問題

Q: 我改了 docker-compose.yml，為什麼沒生效？

改完設定要重新建立容器才會吃到新設定：docker compose up -d --force-recreate。只 restart 有時不會重新讀環境變數。

n8n docker-compose 自架的失敗，九成集中在五個地方：資料庫連線、webhook 對外網址、登入 cookie、volume 權限、資料持久化。這篇把這 5 個坑的「錯誤訊息、真正原因、可複製的解法」一次列清楚，照著對就能把卡住的流程救回來。

本文是「n8n 安裝完全教學：Docker 與雲端哪個適合你」系列的深入文章。如果你還沒準備好 docker-compose 設定檔，建議先回去看主指南，再帶著這篇來排雷。設定欄位的權威來源是 n8n 官方自架文件，compose 語法則可對照 Docker Compose 官方文件。

下面每一個坑，都會給你「症狀 → 原因 → 解法」三段，遇到哪個跳到哪個。

坑 1：n8n 啟動就報「連不到資料庫」

症狀

docker compose up 之後，n8n 容器一直重啟，log 出現：

Error: getaddrinfo ENOTFOUND postgres
# 或
ECONNREFUSED 127.0.0.1:5432

原因

有兩種常見情況：

n8n 比 PostgreSQL 早啟動。 容器啟動有先後，n8n 在資料庫還沒準備好時就嘗試連線，直接陣亡。
連線資訊寫錯。 最典型的是把 DB_POSTGRESDB_HOST 寫成 localhost 或 127.0.0.1。在 compose 網路裡，服務之間要用「服務名稱」互相找，不是 localhost。

解法

第一，DB_POSTGRESDB_HOST 要填 PostgreSQL 那個 service 的名稱（範例裡是 postgres）：

environment:
  - DB_TYPE=postgresdb
  - DB_POSTGRESDB_HOST=postgres   # 不是 localhost！
  - DB_POSTGRESDB_DATABASE=n8n
  - DB_POSTGRESDB_USER=n8n
  - DB_POSTGRESDB_PASSWORD=你的密碼

第二，用 healthcheck + depends_on 強制 n8n 等資料庫就緒再啟動：

  postgres:
    image: postgres:16
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U n8n"]
      interval: 5s
      timeout: 5s
      retries: 10

  n8n:
    depends_on:
      postgres:
        condition: service_healthy

關鍵是 condition: service_healthy。只寫 depends_on: [postgres] 只保證「postgres 容器有啟動」，不保證「資料庫可以連」，這兩件事差很多。

坑 2：webhook 收不到外部觸發

症狀

LINE、Slack、Stripe 這些服務要打你的 Webhook，但 n8n 的觸發節點完全沒反應。你複製出來的 Webhook 網址長這樣：

http://localhost:5678/webhook/xxxx

原因

自架 n8n 預設不知道「它對外的真實網址是什麼」，所以產出的 webhook 連結是 localhost。外部服務當然連不到你電腦裡的 localhost。

解法

在 n8n 的環境變數明確告訴它對外網址：

environment:
  - N8N_HOST=n8n.你的網域.com
  - N8N_PROTOCOL=https
  - WEBHOOK_URL=https://n8n.你的網域.com/
  - N8N_PORT=5678

設好之後，重新建立容器（docker compose up -d --force-recreate），再去複製一次 webhook 網址，它就會變成你的正式網域。

⚠️ 注意：很多 Webhook 來源（LINE、Slack）強制要 HTTPS，純 HTTP 的回呼網址會被拒絕。如果你還沒套 SSL，先看「n8n HTTPS / Nginx / SSL 設定教學」把憑證裝起來。

坑 3：登入頁一直跳掉 / 顯示空白

症狀

從別台電腦或手機連你自架的 n8n，畫面一片空白，或登入後一直被踢回登入頁。打開瀏覽器 console 看到跟 cookie、secure 有關的警告。

原因

n8n 從某版本開始預設啟用 secure cookie，要求必須走 HTTPS。如果你用純 HTTP（例如還在測試、用 IP 直連），瀏覽器會因為「secure cookie 卻沒有 HTTPS」而拒絕寫入 cookie，於是你永遠登不進去。

解法

正式環境的正解是套上 HTTPS（坑 2 的延伸）。但如果你只是在內網測試、暫時用 HTTP，可以先關掉 secure cookie：

environment:
  - N8N_SECURE_COOKIE=false

這只是測試期的權宜之計。對外正式服務一定要走 HTTPS，不要長期把 N8N_SECURE_COOKIE 關著，那等於把後台暴露在不安全的連線上。

如果你連的是 localhost 還是空白，多半是容器還沒完全起來，等 20 秒重整；或埠號 5678 被別的程式占用，換個對應埠（例如 -p 5679:5678）再試。

坑 4：volume 權限錯誤（EACCES / Permission denied）

症狀

容器 log 出現：

EACCES: permission denied, open '/home/node/.n8n/config'
# 或
Error: EACCES: permission denied, mkdir '/home/node/.n8n'

原因

n8n 容器內是用 node 這個非 root 使用者（UID 1000）在跑。如果你把一個「主機上 root 才能寫」的目錄掛進去當 volume，容器內的 node 使用者沒有寫入權限，就會報 EACCES。這在用「綁定目錄」（bind mount，例如 ./n8n-data:/home/node/.n8n）時特別常見。

解法

優先用 named volume（讓 Docker 自己管權限），這也是主指南範例的做法：

    volumes:
      - n8n_data:/home/node/.n8n

volumes:
  n8n_data:

如果你一定要用主機上的實體目錄（bind mount），就要先把目錄的擁有者改成 UID 1000：

mkdir -p ./n8n-data
sudo chown -R 1000:1000 ./n8n-data

改完權限再 docker compose up -d，EACCES 就會消失。

坑 5：升版或重建後，工作流和憑證全不見了

症狀

你跑了 docker compose down 再 up，或升級了 n8n 版本，結果：所有工作流消失、或工作流還在但憑證全部解不開、要重新輸入。

原因

這是最痛、也最常見的坑，分兩種狀況：

沒掛 volume，或用了預設 SQLite 又沒持久化。 資料寫在容器內部，容器一刪就跟著沒了。
加密金鑰 N8N_ENCRYPTION_KEY 換了。 n8n 用這把金鑰加密所有憑證。如果你第一次沒設、讓它自動產生存在 volume 裡，後來重建時又沒帶上同一把，所有加密過的憑證就全部解不開。

解法

第一，資料一定要掛 volume，資料庫也要持久化：

    volumes:
      - n8n_data:/home/node/.n8n
      - postgres_data:/var/lib/postgresql/data   # PostgreSQL 也要掛

第二，自己固定一把加密金鑰，寫死在 compose 裡（並另外安全備份）：

environment:
  - N8N_ENCRYPTION_KEY=一組你自己產生的固定隨機字串

產生金鑰可以用：

openssl rand -hex 16

把產出的字串貼進 N8N_ENCRYPTION_KEY，以後不管怎麼重建、升版，只要這把金鑰不變，憑證就解得開。

升版前的完整備份與驗證步驟，整理在「n8n 備份與升版標準流程」，正式環境升版前務必先讀。

排查順序：遇到問題先看 log

不管碰到哪個坑，第一步永遠是看容器的 log：

docker compose logs -f n8n
docker compose logs -f postgres

九成的錯誤訊息會直接告訴你問題在哪一層。看到 ECONNREFUSED 想資料庫（坑 1）、看到 EACCES 想權限（坑 4）、看到 cookie / secure 想 HTTPS（坑 3）。把錯誤訊息對到上面的症狀，比盲目改設定快得多。

更多非安裝期、而是日常使用會遇到的錯誤，整理在「n8n 常見錯誤 Top 10：原因分析與解法」。

常見問題（FAQ）

docker-compose 跟 docker run 哪個適合正式環境？

正式環境用 docker-compose。它能一次管好 n8n + PostgreSQL + volume + 環境變數，重啟、升版、搬機都靠一個檔案搞定。docker run 適合 30 秒快速試跑，不適合長期上線。

我改了 docker-compose.yml，為什麼沒生效？

改完設定要重新建立容器才會吃到新設定：docker compose up -d --force-recreate。只 restart 有時不會重新讀環境變數。

PostgreSQL 是必須的嗎？用預設的不行嗎？

小量測試用預設的 SQLite 也能跑，但資料量一大、執行頻繁時 SQLite 容易變慢甚至鎖死。正式環境建議用 PostgreSQL，這也是官方推薦做法。

為什麼一定要自己設 N8N_ENCRYPTION_KEY？

因為它決定你的憑證（API key、密碼）能不能在重建容器後還解得開。沒自己固定，等於把資料的命交給一把隨機產生、你不知道在哪的金鑰，升版時很容易整批失效。

小結

docker-compose 自架 n8n 的坑其實就那幾個，而且都有固定解法：資料庫用服務名稱連、等 healthy 再啟動、對外網址要設、權限用 named volume、加密金鑰自己固定。把這五點檢查過一遍，你的自架就穩了。

裝好、排完雷之後，接著就是真正開始用它。跟著「第一個 n8n 工作流入門指南」搭一條會幫你省時間的流程，或回到「n8n 安裝完全教學主指南」確認你的部署設定都到位了。