SSD Nodes Learn Hosting plans →
指南 Matt Connor作者: Matt Connor

Planka 自架部署:Docker Compose 看板教學

使用 Docker Compose 在 VPS 自架 Planka,設定 Postgres、Traefik 與管理員 bootstrap 變數,並修正 BASE_URL 錯誤導致的登入問題。

自架 Planka 可獲得的功能

自架 Planka 可讓團隊在自行控管的 VPS 上使用 Kanban 看板,提供大家已熟悉的 Trello 卡片、清單與標籤模型。沒有席位上限,也沒有按使用者計費,因為唯一的成本就是伺服器。本指南會使用 Docker Compose,在 Traefik 後方部署 Planka,並使用 Postgres 儲存資料,以及為每個使用者上傳的檔案建立 named volume。

Planka 2 依據專案自有的 Fair Use License 發布。該專案將此授權描述為 source-available,而非 open source。將其用於自己組織的內部專案是允許的。若要以商業託管服務的形式提供給第三方,則需要 Pro 或 Enterprise license。

本指南的對象是由兩到五人組成、準備離開 Trello 免費方案的團隊。如果你仍在決定要使用哪個看板,請先閱讀 自架 Trello 替代方案比較。本指南假設你已經做出選擇,內容只涵蓋部署。

你需要一台執行 Docker Engine 並安裝 Compose plugin 的 VPS,以及一筆指向該 VPS 的 DNS A record。你也需要在該伺服器上已有 Traefik,並由它處理 TLS (transport layer security) termination。如果尚未安裝 Traefik,請先設定 位於多個 Compose 應用程式前方的 Traefik reverse proxy;如果不熟悉下方檔案,也請先閱讀 VPS 的 Docker Compose 基礎。

Planka 需要多少 VPS 資源?

該專案的技術 FAQ 建議小型團隊至少配置 2 GB RAM 與 10 GB 儲存空間,請將這些數值視為起點而非絕對標準。

實際運行的程序很輕量:一個負責 API 與前端服務的 Node.js 程序,以及一個儲存資料的 Postgres 伺服器(包含一個監控程序與每個連線對應的後端程序)。Planka 容器內還會運行一個小型代理程序來過濾對外請求。2 GB 的方案符合專案對小型團隊的記憶體建議。看板服務相對輕量,若同一台 VPS 還要存放團隊文件,請優先考量該應用程式的需求:執行 AFFiNE 作為 Notion 風格的工作區 本身就需要數 GB 的記憶體,這是在 Planka 佔用資源前必須預留的。

請先評估磁碟空間再決定記憶體大小,因為附件檔案會持續增長。請測量您自己的實例,不要僅依賴此處的建議:

docker stats --no-stream
docker system df -v

第一個指令會顯示每個容器即時的記憶體與 CPU 使用量。第二個指令顯示每個 volume 佔用的空間。請在正常工作一週後進行測量,而非安裝當天,因為閒置的看板無法反映團隊的實際負載。

編寫 Compose 檔案

建立目錄並取得擁有權,這樣您就不需要透過 sudo 來編輯這些檔案。

sudo mkdir -p /opt/planka
sudo chown "$USER":"$USER" /opt/planka
cd /opt/planka

將密鑰產生至 Compose 檔案旁的 .env 檔案中。Compose 會自動讀取該檔案並替換其中的數值。

umask 077
{
  printf 'SECRET_KEY=%s\n' "$(openssl rand -hex 64)"
  printf 'POSTGRES_PASSWORD=%s\n' "$(openssl rand -hex 24)"
  printf 'ADMIN_PASSWORD=%s\n' "$(openssl rand -hex 12)"
} > .env
chmod 600 .env

使用 openssl rand -hex 是經過深思熟慮的。十六進位字串僅包含數字與 a 到 f 的字母,因此不會破壞它所嵌入的 DATABASE_URL 連接字串。標準 Base64 可能包含斜線、加號與填充用的等號,但絕不會包含 @ 符號;在連接 URL 中具有特殊意義的字元需要進行百分比編碼。更廣泛的模式請參閱 將密鑰排除在 Compose 檔案之外。

現在執行 docker-compose.yml。請將兩處出現的 kanban.example.com 替換為您自己的主機名稱。

services:
  planka:
    image: ghcr.io/plankanban/planka:2.2.1
    restart: unless-stopped
    volumes:
      - planka-data:/app/data
    environment:
      - BASE_URL=https://kanban.example.com
      - DATABASE_URL=postgresql://planka:${POSTGRES_PASSWORD}@postgres/planka
      - SECRET_KEY=${SECRET_KEY}
      - TRUST_PROXY=true
      - DEFAULT_ADMIN_EMAIL=you@example.com
      - DEFAULT_ADMIN_PASSWORD=${ADMIN_PASSWORD}
      - DEFAULT_ADMIN_NAME=Your Name
      - DEFAULT_ADMIN_USERNAME=admin
    networks:
      - proxy
      - internal
    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=proxy"
      - "traefik.http.routers.planka.rule=Host(`kanban.example.com`)"
      - "traefik.http.routers.planka.entrypoints=websecure"
      - "traefik.http.routers.planka.tls.certresolver=default"
      - "traefik.http.services.planka.loadbalancer.server.port=1337"
    depends_on:
      postgres:
        condition: service_healthy

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

volumes:
  planka-data:
  db-data:

networks:
  proxy:
    external: true
  internal:

該檔案中的四項決策值得說明,因為這些通常是使用者修改後會後悔的部分。

  • Planka 服務中沒有 ports: 區塊。Traefik 透過 proxy 網路存取容器,因此 1337 埠永遠不會發佈到主機上。發佈該埠會讓任何人有機會繞過您的代理伺服器與憑證。
  • loadbalancer.server.port=1337 指定了容器內部的埠號。Planka 監聽 1337 埠,而上游範例僅能透過 3000 埠存取,是因為它將埠對應到了主機。此處沒有主機對應,因此必須告知 Traefik 容器的埠號。
  • condition: service_healthy 與 Postgres 的健康檢查(healthcheck)相配合。若沒有它,Planka 會在資料庫接受連線前啟動,導致首次查詢失敗並退出,這看起來會像是一個崩潰迴圈(crash loop)。其運作機制請參閱 Compose 健康檢查與啟動順序。
  • 資料庫服務特意命名為 postgres。Planka 2 會透過內部過濾器路由其自身的對外請求,該過濾器的預設封鎖清單為 localhost,postgres。若重新命名該服務,您將會悄悄地將您的資料庫從該清單中移除。

在啟動任何服務前,請檢查 Compose 是否能讀取您的密鑰:

docker compose config | grep -E 'image:|BASE_URL|POSTGRES_USER'

這會印出已替換 .env 數值的檔案內容。若數值為空,表示 Compose 未讀取 .env 檔案,這通常是因為您在不同的目錄下執行該指令。

管理員引導變數的實際作用

自 Planka 1.13 版本起,系統不再自動建立管理員帳號,因此全新的資料庫中沒有任何帳號可以登入。DEFAULT_ADMIN_* 群組是解決此問題的兩種方式之一。

Planka 在啟動時會搜尋符合 DEFAULT_ADMIN_EMAIL 的使用者。若不存在,系統會使用同時設定的密碼、顯示名稱與使用者名稱建立該帳號。在後續啟動時,若 DEFAULT_ADMIN_PASSWORD 仍保持設定,系統也會根據這些變數更新對應的帳號,包括重設其密碼。

DEFAULT_ADMIN_EMAIL 還有第二項容易讓人困惑的功能。只要該變數保持設定,介面上將無法修改該帳號的名稱、角色或電子郵件地址,也無法將其刪除。這是一種鎖定保護機制,也是為何您無法在 UI 中重新命名該帳號或更改其電子郵件地址的原因。移除該變數並重新啟動後,該帳號即會變為一般的管理員帳號,您可以像編輯其他帳號一樣對其進行編輯。

密碼設定行需要特別小心。任何位於 environment: 下方的內容,只要能對容器執行 docker inspect 的人皆可讀取,因此 DEFAULT_ADMIN_PASSWORD 不應永久存放在該處。請登入系統、刪除該行、再次執行 docker compose up -d,然後在介面中變更您的密碼。

更乾淨的做法是完全跳過這些變數。請註解掉整個 DEFAULT_ADMIN_* 群組,然後以互動方式建立帳號:

docker compose run --rm planka npm run db:create-admin-user

系統會提示您輸入電子郵件、密碼、顯示名稱以及選填的使用者名稱,並直接將使用者寫入資料庫。密碼完全不會接觸到 Compose 檔案或容器的設定環境。若有多人擁有該 VPS 的 shell 存取權,請使用此方式。由於 depends_on 的緣故,該指令會先啟動 Postgres,因此即使在從未啟動過的堆疊上也能運作。

無論採取哪種方式,您都必須手動管理 Planka 密碼。在 2.1.1 版本之前,社群版可將登入交由 OIDC 提供者處理,例如 以您自己的單一登入伺服器執行的 Authentik,但 2026 年 8 月發布的 2.2.0 版本已將 OIDC 與 SSO 功能移至 PLANKA Pro。社群版在同一次發布中新增了本機帳號的雙重驗證 (TOTP) 功能,因此請至少為管理員帳號啟用此功能。

為何當 BASE_URL 與主機名稱不符時會導致登入失敗

BASE_URL 是使用者在瀏覽器中輸入的確切位址,包含協定且結尾不含斜線。對於此堆疊而言,該值即為 https://kanban.example.com。Planka 會根據此值建立內部連結並列出允許的 WebSocket 來源,這意味著若 BASE_URL 設定錯誤,系統不會顯示明確的錯誤訊息,而是會出現一個載入後卻永遠無法完成的頁面。

常見的情況是:您複製了上游範例,保留了 BASE_URL=http://localhost:3000,並透過 HTTPS 以您的真實網域名稱存取網站。登入表單送出後,您的憑證雖被接受,但看板頁面卻始終無法顯示。開啟瀏覽器的開發者工具,您會發現對 /socket.io/ 的請求失敗,這是因為 Socket 連線至瀏覽器頁面的來源,但伺服器的來源限制卻僅允許由 BASE_URL 推導出的來源。

TRUST_PROXY=true 是同一問題的另一半。Planka 位於 Traefik 後方,因此每個請求皆透過 Docker 網路內部的純 HTTP 從代理伺服器傳入。若未設定 TRUST_PROXY,應用程式會忽略 Traefik 設定的 X-Forwarded-Proto 與 X-Forwarded-For 標頭,導致其誤判連線不安全,並將所有用戶端視為同一個共用 IP 位址。設定該參數後,應用程式便會讀取這些標頭,並與瀏覽器在協定認知上達成一致。

Traefik 無需額外設定即可代理 WebSocket,這也是在此處優先選用它的原因。若使用 nginx,代理伺服器必須轉發 upgrade 標頭、proxy_set_header Upgrade $http_upgrade 與 proxy_set_header Connection "upgrade",否則同樣會因不同原因導致載入圖示卡住。這些設定可放置於一般的 location / 區塊中;針對 /socket.io 使用獨立區塊亦可,但非必要。

若日後需將看板遷移至新的主機名稱,必須同時變更兩項設定:BASE_URL 的值與 Traefik 的 Host() 規則。若僅變更其中一項而遺漏另一項,載入圖示卡住的問題將會再次發生。自 2026 年 3 月發布的 2.1.0 版本起,Planka 支援以子路徑(例如 https://example.com/planka)進行部署。若使用舊版本標籤,請為其配置獨立的子網域。

Planka 存放附件與頭像的位置

Planka 2 將使用者上傳的所有內容儲存在容器內的單一路徑:/app/data。附件、使用者頭像與看板背景圖片皆存放於此。第 1 版使用三個獨立目錄,因此若從舊版教學複製 Compose 檔案,會掛載已不存在的路徑,導致預期的資料掛載遺失。

該單一掛載點決定了看板在升級後能否存續。Docker 映像檔將 /app/data 宣告為 volume,若在 Compose 中省略掛載,上傳內容將存入匿名 volume。Compose 在執行一般的 up 重建時會保留該 volume,但後續執行 down 再接 up 時,並不會自動重新連結。看板恢復後外觀看似正常,卡片也都在,但所有附件連結皆會失效,因為資料庫記錄仍指向舊 volume 中的檔案。

上述 Compose 檔案中的具名 volume 可避免此問題。Bind mount 亦可達成,且能透過一般工具更輕鬆地備份檔案,但需額外執行一個步驟。容器內的 Node 程序以 UID 1000 執行,因此若宿主機目錄由 root 擁有,首次上傳時會發生權限錯誤:

sudo chown -R 1000:1000 /opt/planka/data

兩者之間的取捨詳見 bind mounts 與具名 volume 的比較。

若附件大小超出方案的磁碟限制,Planka 可透過 S3_ENDPOINT、S3_BUCKET 及對應的 key 變數,將附件寫入 S3 相容儲存空間。該設定可指向託管的 bucket,或另一台機器上的 自架 MinIO 物件儲存。請在團隊填滿看板前決定,因為啟用 S3 會將檔案讀寫切換至該後端,且不會自動遷移現有的上傳檔案。

啟動堆疊並確認運作正常

docker compose pull
docker compose up -d
docker compose ps

docker compose ps 應顯示 postgres 為 healthy,且 planka 為 running。如果 Planka 持續重啟,第一個應檢查的是資料庫連線,而不是應用程式。

docker compose logs -f planka

正常的首次啟動會執行資料庫 migration,但正式環境設定會設定 noShip: true,並抑制回報埠 1337 的啟動訊息。請直接查詢 Postgres,確認 schema 確實已建立,不要只相信日誌:

docker compose exec postgres psql -U planka -d planka -c '\dt'

如果資料表清單包含 board 與 card,表示 migration 已執行。Did not find any relations 表示 Planka 從未連線,因此請將 DATABASE_URL 與 .env 中的 POSTGRES_USER 和 POSTGRES_PASSWORD 值進行比對。

接著從自己的電腦檢查路由,不要從 VPS 檢查:

curl -I https://kanban.example.com

HTTP/2 200 表示 Traefik 已取得憑證,並且能連到容器。由 Traefik 提供的 404 表示沒有 router 符合請求:Host() 規則不符合你請求的主機名稱,或 Traefik 從未讀取到這些 labels。502 表示 router 已符合,但 Traefik 無法連到容器,例如容器未連接至 proxy network。現在開啟網站,並使用管理員帳號登入。

在每次版本升級前執行 pg_dump

您的看板資料存放在兩個獨立的儲存區,因此備份必須涵蓋兩者:Postgres 資料庫與 planka-data 磁碟區。請在服務堆疊執行時進行資料庫傾印(dump)。

docker compose exec -T postgres pg_dump -U planka -d planka > "planka-db-$(date +%F).sql"

-T 參數會停用 Compose 預設的虛擬終端機配置,確保傾印內容以純文字串流輸出。

接著是上傳檔案。請先找出正確的磁碟區名稱,因為 Compose 會在名稱前加上專案目錄名稱作為前綴。

docker volume ls | grep planka
docker run --rm -v planka_planka-data:/data -v "$PWD":/backup alpine \
  tar czf /backup/planka-files-$(date +%F).tgz -C /data .

該專案的儲存庫中也提供了 docker-backup.sh 與 docker-restore.sh 指令碼,官方文件建議將其設定為每日排程任務(cron job)。這兩種方式皆可。但未經還原測試的備份是無效的,請務必在測試用的 VPS 上執行一次還原,並確認能成功登入且開啟附件。這類雙重儲存架構存在於所有支援檔案上傳的 Compose 應用程式中,因此若您日後將 Chatwoot 安裝在與支援服務台相同的伺服器上,您在此建立的備份流程只需修改磁碟區名稱即可直接套用。

請在每次版本變更前立即執行傾印。昨晚的備份不等同於您即將進行遷移前的備份。

固定 tag 並閱讀 release notes

該檔案中的兩個 image tag 都是刻意固定的。

ghcr.io/plankanban/planka:2.2.1 是特定版本,截至 2026 年 10 月仍為目前版本。Community 2.3.0 已於 2026 年 11 月 4 日發布,包含安全性修正,且上游建議更新。Community 2.3.1 隨後於 2026 年 11 月 5 日發布,修正了在包含無 username 成員的 board 上編輯 card 描述時發生當機的問題。latest 會在上游發布新版本時變動,因此例行的 docker compose pull 可能在你未選擇的時間執行 schema migration。修改該數值前,請先閱讀 release notes,因為重大變更與安全性修正都會記載在其中。2.0.3 版本以安全性版本形式發布,這正是應先閱讀、而不是意外套用的變更。2.2.1 也是如此;該版本於 2026 年 8 月發布,修正了 path traversal 缺陷。使用 local file storage 的 instance 上,已登入的使用者可利用此缺陷讀取任意檔案;本指南採用的正是這種設定,且該公告列出 2.1.1 及更早版本為受影響版本。如果你是從 2.1.x 升級,請先閱讀 2.2.0 的說明,因為該版本會停用只曾透過 SSO 登入的使用者,直到管理員為他們設定密碼並重新啟用帳號。這裡很容易固定版本,因為上游會發布 image;如果專案沒有發布 image,你仍應採用相同的紀律,只是多一個步驟,例如 在主機上從 checkout 的 git tag 建置 openGym。

postgres:16-alpine 固定在 major version,原因更為嚴格。Postgres 會以與 major version 綁定的格式寫入 data directory,而 server 會拒絕開啟由其他版本寫入的 directory。寫入 postgres:latest、讓 tag 滾動超過 16 後,容器將無法啟動。例如 17 image 會停止並顯示:

FATAL:  database files are incompatible with server
DETAIL:  The data directory was initialized by PostgreSQL version 16, which is not compatible with this version 17.

資料不會遺失,重新啟動也無法修正問題。移至新的 Postgres major version,必須從舊版本 dump,再還原至新版本的全新 data directory;也可以執行 pg_upgrade,直接轉換資料,但必須同時提供新舊 server binary;另一種方式是將 logical replication 複製到執行新版本的 server,然後進行切換。每種方式都是規劃好的 migration,不是拉取 image 的附帶結果;logical replication 可讓舊 server 持續執行,直到新 server 追上進度。

如果你要搬移既有的 Planka 1.x 安裝,而不是重新開始,該升級有自己的文件化程序,請參閱專案文件。若事前沒有備份,就無法返回 version 1。

失敗模式與常見錯誤訊息

Planka 陷入重啟迴圈,且日誌顯示資料庫相關錯誤。 DATABASE_URL 中的憑證與 Postgres 環境變數不符。請注意,POSTGRES_PASSWORD 僅在資料目錄首次初始化時生效,因此在首次啟動失敗後修改該變數無效。請使用 ALTER ROLE 修改資料庫角色的密碼,使其與設定的密碼一致;若為無須保留資料的測試安裝,則可選擇移除 db-data 儲存卷。

登入成功但看板無法載入。 BASE_URL 與瀏覽器網址列中的位址不符,導致伺服器拒絕該 socket 的來源請求。瀏覽器控制台會顯示對 /socket.io/ 的請求失敗。

其他功能正常但無法上傳檔案。 這是因為綁定掛載(bind mount)的擁有者為 root。請在宿主機目錄執行 sudo chown -R 1000:1000,然後重啟容器。

升級後附件消失。 /app/data 未正確掛載至原始的上傳儲存卷。請重新掛載該儲存卷或從備份還原檔案,並在再次更動映像檔標籤前,改用具名儲存卷(named volume)。

Traefik 回傳 404 錯誤。 沒有路由符合該請求:Host() 規則與您的 DNS 記錄不符,或是標籤未正確傳遞至 Traefik。docker compose config 可顯示替換變數後的標籤內容,此處可檢查是否有拼字錯誤。若回傳 502,則代表路由匹配成功但無法連線至容器,請檢查該容器是否已加入 proxy 網路。

通知或 Webhook 無法送達。 Planka 2 會透過內部過濾器發送對外 HTTP 請求,預設封鎖清單包含 localhost 與 postgres。指向 localhost 的 Webhook 會被預設機制封鎖;一旦設定 OUTGOING_ALLOWED_HOSTS,不在該清單中的所有主機也將被封鎖。請將 Webhook 指向其他容器的服務名稱,若使用允許清單(allow list),請將該名稱加入 OUTGOING_ALLOWED_HOSTS,而非直接移除過濾器。

系統運行後的負載極低。請留意發行說明(release notes),並在每次升級前備份資料庫。由於設定了 restart: unless-stopped,只要 Docker 服務本身已設定為開機啟動,重啟伺服器後堆疊(stack)會自動恢復。若無法自動恢復,請參閱 重啟後自動恢復的 Compose 堆疊。

FAQ

為什麼登入後 Planka 一直顯示載入中?

系統已接受憑證,但無法建立即時連線。瀏覽器會向頁面來源開啟 socket,而 Planka 是根據 BASE_URL 來判斷允許的 socket 來源,若該變數維持 http://localhost:3000,而您是透過 https://kanban.example.com 存取網站,伺服器將會拒絕連線。開發者主控台會顯示對 /socket.io/ 的請求失敗。請將 BASE_URL 設定為正確的公開網址(結尾不可包含斜線),並加入 TRUST_PROXY=true 以確保應用程式能識別來自反向代理的 X-Forwarded-Proto 標頭,最後執行 docker compose up -d。

如何建立第一個 Planka 管理員帳號?

自 1.13 版本起,系統不再自動建立管理員。您可以設定 DEFAULT_ADMIN_EMAIL 及其對應的密碼、姓名與使用者名稱變數並啟動 stack,或是執行 docker compose run --rm planka npm run db:create-admin-user 並依照提示操作。在共用伺服器上,互動式指令較為安全,因為密碼不會進入容器的設定環境中,避免被 docker inspect 讀取。設定完成後保留 DEFAULT_ADMIN_EMAIL,可防止該帳號的姓名、角色與電子郵件地址被變更,並禁止從介面刪除該帳號。設定完成後請移除 DEFAULT_ADMIN_PASSWORD,否則每次啟動時都會重設該帳號的密碼。

Planka 將附件與頭像儲存在哪裡?

在 Planka 2 中,所有上傳的檔案(包含附件、使用者頭像與看板背景)皆位於容器內的 /app/data。請將此路徑掛載至具名儲存卷(named volume)。若未明確掛載,Docker 映像檔會使用匿名儲存卷,導致執行 docker compose down 後,後續的 docker compose up 無法自動重新連結。綁定掛載(bind mount)亦可,但由於 Node 程序是以 UID 1000 執行,請務必在宿主機目錄執行 sudo chown -R 1000:1000,否則上傳會因權限錯誤而失敗。

自架 Planka 需要多少 RAM?

專案技術 FAQ 建議小型團隊至少配置 2 GB RAM 與 10 GB 儲存空間。預設的 Docker 部署包含一個 Node 程序、一個 Postgres 伺服器(每個開啟的連線對應一個後端程序),以及一個用於過濾外連請求的內部 Squid 代理。請在正常運作一週後執行 docker stats --no-stream,並根據實際數據調整規格。相較於記憶體,請更密切監控磁碟空間,因為附件會隨時間增長。

如何在不遺失資料的情況下升級 Planka?

請在升級前立即備份資料庫並封存上傳目錄的儲存卷,不要僅依賴昨晚的排程備份。請使用 docker compose exec -T postgres pg_dump -U planka -d planka > planka-db.sql,並保留 -T 以停用重新導向輸出時的虛擬終端分配。請閱讀所有跳過版本的發布說明,將映像檔標籤(tag)改為特定版本而非 latest,接著執行 docker compose pull 與 docker compose up -d,並監控日誌以確認遷移過程。請將 Postgres 標籤鎖定在主要版本(major version),因為伺服器會拒絕開啟由不同主要版本所寫入的資料目錄。

這篇文章對您有幫助嗎?