Penpot 完整教學 2026：開源 Figma 替代品 Docker 自架，Design Tokens、CSS Grid 到 MCP 讓 AI Agent 動手（安裝、備份、HTTPS 一次學會）

一句話結論

Penpot 是 6 萬顆星的開源設計平台（MPL-2.0，Clojure 寫成），原生以 CSS／SVG／HTML 表達設計、內建 Design Tokens 與 CSS Grid／Flex 版面，官方提供一組 docker-compose 就能自架；而且從 2.18 版開始，官方 compose 已經內含 MCP 服務，能讓 Claude Code、Cursor 這類 AI Agent 直接讀寫你的設計檔。

Penpot 是什麼？

Penpot 是一套以瀏覽器為介面的開源設計與原型工具，定位是「設計與程式碼之間的橋」。它最大的差異點不是「免費」，而是設計檔本身就是開放標準：畫面上的元件、樣式、版面，都能直接對應到 CSS、SVG、HTML 與 JSON，工程師看設計稿時看到的是可用的程式碼，而不是只有圖層名稱的圖片。

為什麼要自架設計工具？

三個很現實的理由：

1. 資料主權：設計檔裡常有未發表的產品介面、客戶 Logo、內部流程圖。放在第三方 SaaS 就是放在別人的雲上；自架則所有檔案與縮圖都存在自己的 Postgres 與 volume 裡。
2. 合規與稽核：金融、醫療、政府類的團隊常被要求「設計資產不得離開特定網路邊界」，可自架是少數能直接滿足的選項。
3. 成本與鎖定：設計工具是按席位訂閱的 SaaS，人數一多，費用就跟著線性成長；開源自架沒有席位費，只有主機成本。

Penpot vs Figma：該怎麼選？

先說清楚：兩者都能做出好設計，差別在控制權與工作流的取向。價格與方案內容各家隨時調整，實際數字請以官方頁面為準，下表整理的是結構性差異。

如果你的需求是「設計稿能直接被前端與 AI 讀懂，而且我要握有自己的檔案」，Penpot 的定位就很清楚；如果團隊已經重度依賴 Figma 的外掛與社群資源，硬換會付出不小的遷移成本。

架構：7 個容器各做什麼

官方 docker-compose.yaml 會拉起一整組服務，這是自架時最容易搞混的地方，先看懂就不會怕：

資料只存在兩個地方：**Postgres volume（你的專案）**與 assets volume（上傳的圖片與 SVG）。備份只要顧好這兩個，講白一點，「弄丟 Postgres volume 等於弄丟全部專案」。

安裝步驟（Docker Compose）

Step 1：確認 Docker 與 Compose v2

docker --version
docker compose version   # 需要 v2（指令是 docker compose，不是 docker-compose）

Step 2：下載官方 compose 檔

mkdir -p ~/penpot && cd ~/penpot
curl -o docker-compose.yaml \
  https://raw.githubusercontent.com/penpot/penpot/main/docker/images/docker-compose.yaml

Step 3：先改三個關鍵設定

打開 docker-compose.yaml，至少改這幾項：

# 1) 對外網址（要給別人連就必須改）
PENPOT_PUBLIC_URI: https://penpot.example.com

# 2) 主金鑰：務必換掉預設值
#    產生方式：python3 -c "import secrets; print(secrets.token_urlsafe(64))"
PENPOT_SECRET_KEY: <隨機產生的 512-bit base64 字串>

# 3) 版本鎖定（生產環境不要用 latest）
#    在啟動指令用環境變數帶入 PENPOT_VERSION，例如 2.18.3

Step 4：啟動

PENPOT_VERSION=2.18.3 docker compose -p penpot -f docker-compose.yaml up -d

啟動後瀏覽器打開 http://localhost:9001 就會看到登入頁。預設 compose 帶了 disable-email-verification 與 disable-secure-session-cookies 這類方便本機測試、但不該直接上線的 flag，正式環境請照下一節調整。

Step 5：建立第一個帳號（需要時）

若你關掉了公開註冊，可以用官方 CLI 直接建帳號（此指令需要 enable-prepl-server flag，預設 compose 已開啟）：

docker exec -ti penpot-penpot-backend-1 python3 manage.py create-profile

# 服務帳號可以跳過導覽
docker exec -ti penpot-penpot-backend-1 \
  python3 manage.py create-profile --skip-tutorial --skip-walkthrough

容器名稱依平台可能是 penpot-penpot-backend-1 或 penpot_penpot-backend-1，用 docker compose ps 確認即可。

設定方式：flags 與環境變數

Penpot 的設定只有兩種形式，理解這個規則就看得懂所有文件：

• Flags：enable-<功能>／disable-<功能>，全部寫在 PENPOT_FLAGS 這個清單裡。
• 環境變數：以 PENPOT_ 開頭，依服務（backend／frontend／exporter）分開設定。

# 常見組合範例
PENPOT_FLAGS: disable-email-verification enable-smtp enable-prepl-server enable-mcp enable-admin-console

# 寄信（密碼重設、邀請）
PENPOT_SMTP_HOST: smtp.example.com
PENPOT_SMTP_PORT: 587
PENPOT_SMTP_USERNAME: <user>
PENPOT_SMTP_PASSWORD: <password>
PENPOT_SMTP_TLS: true

# 限制註冊網域
PENPOT_REGISTRATION_DOMAIN_WHITELIST: mycompany.com,partner.com

登入方式除了預設的 email／密碼，還支援 Google、GitHub、GitLab、OIDC（可接 Azure AD 等 SSO）與 LDAP，各自用對應的 flag 與變數開啟：

PENPOT_FLAGS: enable-login-with-oidc
PENPOT_OIDC_CLIENT_ID: <client-id>
PENPOT_OIDC_BASE_URI: https://login.microsoftonline.com/<tenant-id>/v2.0/
PENPOT_OIDC_CLIENT_SECRET: <client-secret>

上線一定要做：反向代理與 HTTPS

不要讓 Penpot 直接裸奔在 HTTP 上。 除了安全性，瀏覽器在非 HTTPS 環境會停用部分 API——最常見的就是「複製貼上失效」。代理要轉發兩個東西：一般流量與 /ws/notifications 的 WebSocket。

server {
    listen 80;
    server_name penpot.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name penpot.example.com;

    # 要與 PENPOT_HTTP_SERVER_MAX_BODY_SIZE 一致（預設 367001600）
    client_max_body_size 367001600;

    ssl_certificate     /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    location /ws/notifications {
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_pass http://localhost:9001/ws/notifications;
    }

    location / {
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_pass http://localhost:9001/;
    }
}

sudo ln -s /etc/nginx/sites-available/penpot /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

Caddy 與 Traefik 官方文件都有範例；若你的環境已經在用 Caddy，把 penpot.example.com 反向代理到 localhost:9001 並放行 WebSocket 即可。

備份與還原

# 資料庫備份（在 compose 目錄下執行）
docker compose exec penpot-postgres \
  pg_dump -U penpot -d penpot > penpot-$(date +%F).sql

# assets volume：用臨時容器掛載後打包（不能直接 cp volume 目錄）
docker run --rm -v penpot_penpot_assets:/data -v "$PWD":/backup alpine \
  tar czf /backup/penpot-assets-$(date +%F).tar.gz -C /data .

還原順序是：docker compose down → 匯入 SQL（psql -U penpot penpot < penpot.sql）→ 解開 assets → up -d。備份建議交給 cron 或專用備份容器固定執行，並實際演練過一次還原，否則等於沒有備份。

版本升級：小幅度前進

cd ~/penpot
docker compose -f docker-compose.yaml pull      # 抓新映像
PENPOT_VERSION=2.18.3 docker compose -p penpot -f docker-compose.yaml up -d

兩個原則：

1. 一次只前進一個穩定版，不要從 2.4 直接跳 2.18。跨版本可能夾帶資料庫遷移，小步走才能照著 release notes 逐步處理，出錯也好回滾。
2. 2.18 的 compose 多了 penpot-admin-console 服務與 enable-admin-console flag。如果你是自己維護 compose 檔（不是直接下載官方版），升級到 2.18 要手動補上這個服務，否則管理主控台不會出現。

用 MCP 讓 AI Agent 直接動你的設計檔

這是 Penpot 近一年最有趣的變化，也是它跟多數設計工具拉開距離的地方。Penpot 官方提供 MCP server，把設計檔的結構（頁面、圖層、元件、樣式、Design Tokens）暴露給支援 MCP 的 AI 客戶端（Claude Code、Cursor、Copilot 類工具）。

運作方式由三塊組成：

• MCP server：對 AI 客戶端提供工具，並把請求轉發給 Penpot。
• Penpot 內的 MCP 外掛：在你開啟的檔案裡執行，讓 server 能存取「當前焦點頁面」。
• MCP 客戶端：你下 prompt 的地方，用 server URL＋MCP key 連線。

MCP 的設計任務與開發任務大致長這樣：

幾個實務上一定要知道的限制：

• MCP 只作用在「當前焦點頁面」，你切換頁面（即使是在另一個瀏覽器分頁），Agent 的上下文就跟著換。
• 同一時間只能有一個分頁持有 MCP，多個分頁開著時要自己指定。
• Agent 有寫入權限：連上 MCP 後，AI 客戶端可以建立、改名、移動、刪除、改樣式。務必在可回復的檔案或副本上操作。
• Local 與 Remote 模式能力不同：remote 模式無法存取本機檔案系統，所以「從本機路徑匯入圖片」不可用，匯出也會受限。
• MCP key 每人只有一把、且不可回復，設定位置在「Your account → Integrations → MCP Server」。

自架環境的好處是：官方 compose 已經有 penpot-mcp 服務，搭配 enable-mcp flag 就能啟用，設計檔與 Agent 的對話都在自己的基礎設施內完成。

常見陷阱速查

誰適合用 Penpot？

• 想擺脫席位訂閱的團隊：自架後成本變成主機費用，人多特別有感。
• 設計與前端想共用一套語言：CSS Grid／Flex 與 Design Tokens 讓設計決策直接對應程式碼。
• 要把 AI Agent 接進設計流程：MCP 讓「設計系統稽核」、「依設計產出 CSS」這類重複工作可以交給 Agent。
• 不能把設計資產放上第三方雲的組織：金融、醫療、政府與有內部資安政策的企業。

反過來說，如果你的團隊重度依賴 Figma 的外掛生態、跨組織協作與社群檔案，Penpot 目前還不是一比一的替代品——它是「控制權」路線的選項，不是「功能覆蓋率」路線的選項。

站內延伸閱讀

• Docker 完整教學 2026：什麼是容器？從安裝、Dockerfile、Compose 多階段構建到安全部署一次學會
• Caddy 完整教學 2026：75K 星自動 HTTPS 網頁伺服器，從 Caddyfile、反向代理到 Docker 部署一次學會
• Coolify 完整教學 2026：62K 星開源自架版 Vercel／Heroku，Git Push 自動部署
• svgl 完整教學 2026：669 個品牌 SVG Logo 免費圖庫，內建 API、13 種擴充套件

資料來源

• Penpot GitHub：penpot/penpot（stars／授權／最新版本 2.18.3）
• Penpot 官方：官方 docker-compose.yaml
• Penpot Help Center：Install with Docker
• Penpot Help Center：Penpot Configuration（flags 與環境變數）
• Penpot Blog：How to deploy Penpot with Docker: A Technical, Step-by-Step Guide
• Penpot Help Center：Penpot MCP server