開發工具

Penpot 自託管怎麼選：開源設計工具的 Docker、協作和開發交付思路

整理 penpot/penpot 的定位、適用場景、自託管入口、設計系統、Inspect Mode 和團隊協作時需要注意的部署邊界。

Penpot 是一套面向產品設計與程式碼協作的開源平臺。自託管版不是單容器畫圖工具：官方 Compose 同時執行前端、後端、Exporter、MCP、Postgres、Valkey 等服務，並把資料庫與上傳素材放在持久卷中。因此，部署完成必須同時驗證容器健康、HTTP 訪問、註冊策略、持久卷和恢復流程。

專案地址：

https://github.com/penpot/penpot

官網：

https://penpot.app

快速結論

  • 個人試用可以直接訪問 Penpot SaaS；需要資料控制、內網部署或合規邊界時再自託管。
  • 官方 Docker 方式要求 Compose V2，預設監聽 http://localhost:9001。
  • 下載到的示例 Compose 面向本機試用，公網部署前必須更換 PENPOT_SECRET_KEY、公開 URI、郵件與安全 Cookie 設定。
  • 備份不能只儲存 docker-compose.yaml，還要覆蓋 Postgres 與 penpot_assets 持久卷。

下載官方 Compose 並先校驗 

1
2
3
4
5
6
7

docker --version
docker compose version
mkdir penpot-selfhost
cd penpot-selfhost
curl -o docker-compose.yaml https://raw.githubusercontent.com/penpot/penpot/main/docker/images/docker-compose.yaml
docker compose -p penpot -f docker-compose.yaml config --services
docker compose -p penpot -f docker-compose.yaml config --volumes

config 必須零退出。服務列表應包含前端、後端、資料庫等元件；卷列表至少應看到 Postgres 資料和素材卷。如果 YAML 解析失敗，不要繼續執行 up -d。

在修改前保留原檔案，便於恢復：

1

cp docker-compose.yaml docker-compose.yaml.original

上線前修改預設安全配置

官方示例明確提示：公網部署不應保留 disable-secure-session-cookies 和 disable-email-verification。還應把下面這些佔位配置改成真實值：

  1. PENPOT_PUBLIC_URI：改為最終 HTTPS 域名。
  2. PENPOT_SECRET_KEY：不要保留 change-this-insecure-key。
  3. PENPOT_FLAGS：決定是否允許註冊、是否驗證郵件以及是否啟用 MCP。
  4. SMTP：正式環境不要把 Mailcatch 當真實郵件服務。

可用 Python 生成隨機 Secret：

1

python3 -c "import secrets; print(secrets.token_urlsafe(64))"

再次執行 docker compose ... config，確認變數替換後仍能解析。不要把包含 Secret 的 Compose 檔案提交到公開倉庫。

啟動並驗證每個服務 

1
2
3
4

docker compose -p penpot -f docker-compose.yaml up -d
docker compose -p penpot -f docker-compose.yaml ps
docker compose -p penpot -f docker-compose.yaml logs --tail 100 penpot-backend
curl -I http://localhost:9001

驗收不能只看前端返回 200。docker compose ps 中不應有持續重啟或退出的服務，後端日誌也不應反覆出現資料庫連線、遷移或 Secret 錯誤。

如果頁面打不開，按順序檢查：

1
2
3
4

docker compose -p penpot -f docker-compose.yaml ps -a
docker compose -p penpot -f docker-compose.yaml logs --tail 200 penpot-frontend
docker compose -p penpot -f docker-compose.yaml logs --tail 200 penpot-backend
docker compose -p penpot -f docker-compose.yaml logs --tail 100 penpot-postgres

前端正常但登入或儲存失敗，通常應繼續查後端和 Postgres，而不是隻重啟瀏覽器。

建立第一個受控賬號

公網例項不建議長期開放匿名註冊。關閉註冊後，可以使用後端管理命令建立賬號。先找實際容器名：

1
2

docker compose -p penpot -f docker-compose.yaml ps
docker exec -ti penpot-penpot-backend-1 python3 manage.py create-profile

不同 Compose 版本可能使用連字元或下劃線組成容器名，不能盲抄第二條命令。若提示找不到容器，以 docker compose ps 輸出為準；管理命令還依賴後端啟用 prepl-server。

HTTPS 反向代理的驗收重點

Penpot 的公開 URI、瀏覽器實際訪問域名和反向代理 TLS 域名必須一致。部署代理後，從外部網路檢查：

1

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

出現重定向迴圈時，先檢查 PENPOT_PUBLIC_URI 與代理傳遞的協議頭；登入後立即掉線，則重點檢查安全 Cookie 和 HTTPS。不要為了臨時可用而重新開啟不安全 Cookie。

用一個最小專案驗證設計交付

完成基礎部署後，新建一個測試團隊和檔案，至少驗證：

  1. 兩個賬號能進入同一團隊並實時看到修改。
  2. 建立一個元件、一個 Variant 和至少一個 Design Token。
  3. 開發賬號能在 Inspect Mode 讀取 SVG、CSS 或佈局資訊。
  4. 匯出一個 .penpot 檔案，再匯入到測試空間。
  5. 上傳一張圖片後重新整理頁面，素材仍可訪問。

這些操作同時覆蓋協作、資料庫和素材卷。只建立空白檔案不足以證明自託管資料鏈路可用。

備份資料庫和素材卷

官方預設 Compose 使用兩個關鍵卷：Postgres 資料卷和 penpot_assets。先讀取實際卷名：

1
2

docker compose -p penpot -f docker-compose.yaml config --volumes
docker volume ls --filter label=com.docker.compose.project=penpot

備份前暫停寫入並記錄版本：

1
2

docker compose -p penpot -f docker-compose.yaml images
docker compose -p penpot -f docker-compose.yaml stop

隨後按 Docker 官方卷備份流程分別歸檔資料庫卷和素材卷，備份檔案必須存到宿主機或遠端儲存，而不是留在容器裡。完成後重新啟動並複查：

1
2
3

docker compose -p penpot -f docker-compose.yaml start
docker compose -p penpot -f docker-compose.yaml ps
curl -I http://localhost:9001

只有實際在隔離環境恢復過的歸檔才算可用備份。恢復驗收應開啟原測試檔案、檢查元件並確認上傳圖片仍存在。

更新前先準備回退點

不要直接覆蓋 Compose 後執行 pull。先保留當前配置、映象資訊和卷備份：

1
2
3
4
5

cp docker-compose.yaml docker-compose.yaml.before-upgrade
docker compose -p penpot -f docker-compose.yaml images
docker compose -p penpot -f docker-compose.yaml pull
docker compose -p penpot -f docker-compose.yaml up -d
docker compose -p penpot -f docker-compose.yaml logs --tail 200 penpot-backend

大版本遷移可能在啟動後繼續執行。此時頁面暫時不可用不等於應該反覆重啟；先看遷移日誌。若新版持續失敗，應停止服務，恢復舊 Compose 和相匹配的映象版本，再恢復升級前卷備份。資料庫已經遷移後，僅切回舊映象可能不安全。

設計與開發的長期協作方式

團隊可按以下方式落地：

  1. 設計師建立 Design System，元件命名儘量與前端元件庫一致。
  2. 顏色、字號和間距使用 Design Token，而不是散落的手填值。
  3. 開發透過 Inspect Mode 獲取 SVG、CSS 和佈局資訊。
  4. 用測試檔案驗證外掛、API 或 MCP，避免直接操作正式設計資產。
  5. 大版本升級前同時匯出關鍵檔案並備份服務端持久卷。

故障判斷表

現象 重點檢查 恢復動作
localhost:9001 無響應 前端埠、容器狀態、宿主機防火牆 恢復原 Compose 後重新建立容器
頁面可開但無法登入 後端日誌、Secret、Cookie、公開 URI 恢復一致的域名與安全 Cookie 配置
邀請郵件收不到 SMTP 與郵件驗證標誌 修正 SMTP，不要關閉驗證長期繞過
檔案能開但圖片丟失 penpot_assets 卷或物件儲存 恢復與資料庫同一時間點的素材備份
升級後後端反覆重啟 資料庫遷移與映象版本 停止寫入，使用升級前整套備份恢復

Penpot 自託管的完成標準是：HTTPS 域名可用、註冊邊界明確、兩名測試使用者能協作、Inspect Mode 能交付樣式、匯入匯出成功，並且資料庫和素材都完成過恢復演練。缺少其中任一項，都不應直接遷入團隊唯一的正式設計檔案。