开发工具

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 能交付样式、导入导出成功，并且数据库和素材都完成过恢复演练。缺少其中任一项，都不应直接迁入团队唯一的正式设计文件。