Penpot 2.18 自托管：开源设计协作的部署、对比与局限

Penpot 是跑在浏览器里的开源设计与原型平台，MPL-2.0 协议，可以自托管。它把设计稿表达成 SVG、CSS、HTML 和 JSON，让前端不必靠标注和截图还原界面。这篇按 2.18 版本讲清四件事：它靠什么工作、怎么部署、和常见工具怎么分工、哪里会卡住人。

它解决的是设计稿与代码之间的翻译问题

传统协作里，设计稿存在私有格式中，前端拿到的是图片和标注，还原程度取决于双方沟通是否充分。Penpot 换了思路：画布上的对象直接对应 CSS 盒模型，Flex 与 Grid 布局在画的时候就是属性，Inspect 面板能复制出对应的 CSS、SVG 与 HTML 片段。

文件层面同样如此。设计文件以 SVG 为主干，文本、颜色、层级都是可读的节点，放进 Git 之后 diff 能看出改了哪个图层。这一点对需要审计设计资产、或者想把设计纳入代码评审流程的团队比较实用。

设计系统靠两组东西落地：组件与变体负责结构与状态，Design Tokens 负责颜色、字号、间距这些变量。Penpot 把令牌做成原生对象，设计侧改一处，导出的 JSON 跟着变，开发侧的变量表不必手工同步。源码在 GitHub 上的 penpot 仓库，目前约 6.2 万 Star，主体用 Clojure 与 ClojureScript 编写。

2.18 版本带来了哪些变化

2.18 于 2026 年 9 月 9 日发布，代号 Born this way；到 10 月 26 日，补丁版本已推进到 2.18.5。官方在发布说明里把它定位成把治理能力单独分层的一次更新。

• 描边转路径：右键带描边的图形选 Outline stroke，可以把描边变成独立的闭合路径，之后能做布尔运算、能导出真实矢量。前提是打开 WebGL 渲染器，旧渲染器下没有这个命令。
• Enterprise 付费层：新增 Admin Console，可按组织接入 OIDC、Azure AD、Google 登录，并统一设置谁能建团队、谁能邀请外部成员。画布本身仍然免费开源，付费买的是组织级管控。
• 绘图工具重新分组：形状与自由绘制收进两个浮出面板，并补上直线、箭头两个独立工具。
• 细节修补：字体选择器用字体本身预览名称；复制粘贴属性时保留 Token 引用，而不是解析成原始数值。

补丁节奏也值得看一眼。发布记录显示，2.18.2 到 2.18.4 连续修了多处与 SVG 清洗、binfile 导入相关的问题，其中一条涉及上传 SVG 时命名空间前缀的脚本标签未被清理。自托管实例如果长期停在旧版本，这类问题会一直留在内网。

用 Docker Compose 自托管部署

官方自托管指南给出三条路线：Docker Compose、Kubernetes（含 Helm Chart）、以及 Elestio 这类托管部署。单机团队走 Compose 就够。

官方仓库里的 compose 文件默认拉起八个服务，各自职责如下。

启动只有两步：下载配置文件，用项目名 penpot 拉起。

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 up -d

默认监听 9001 端口，邮件调试页面在 8025。要固定版本，用 PENPOT_VERSION 环境变量指定，例如 2.18.5；不指定就跟随 Docker Hub 的默认标签，升级时容易一步跨太大。官方文档明确建议小步升级，不要从很旧的版本直接跳到大版本。

上线前有几处必须改：

• 密钥：PENPOT_SECRET_KEY 的默认值是 change-this-insecure-key，必须换成随机串，官方给的做法是用 Python 的 secrets 模块生成 64 字节。
• 访问地址：PENPOT_PUBLIC_URI 要从 localhost:9001 改成真实域名，否则邀请邮件里的链接会指向本机。
• 两个不安全的默认开关：compose 默认带了 disable-email-verification 和 disable-secure-session-cookies。前者让注册邮箱验证形同虚设，后者让会话 Cookie 不走 HTTPS。官方注释写明，暴露到公网时应删掉这两项。
• 邮件通道：默认 SMTP 指向内置的 Mailpit，邮件只存在内存里，容器重建即丢。生产环境要换成真实 SMTP，否则用户收不到验证信和邀请。
• 遥测：PENPOT_TELEMETRY_ENABLED 默认为 true，会周期性上报匿名实例数据，介意的话把它关掉。

前置一层反向代理几乎是必需的。Nginx、Caddy、Traefik 三种配置官方都给了样例，其中两个细节容易漏：一是 /ws/notifications 与 /mcp/ws 两条 WebSocket 路径要单独转发，否则多人协作的实时状态会断；二是 Nginx 的 client_max_body_size 要和 compose 里的 PENPOT_HTTP_SERVER_MAX_BODY_SIZE 对齐，后者默认约 350MB，不同步会在传大图时返回 413。

备份不要直接拷 volumes 目录。官方文档的说法是容器数据放在 Docker 卷里，需要用临时容器挂载后再打包，默认只涉及两个卷：数据库卷和素材卷。用面板类工具部署时也一样，卷的备份策略要单独确认。

和 Figma、Excalidraw 的分工

把三者放在一起看，差别不在功能清单，而在数据放在哪、文件由谁定义。

从 Figma 迁过来需要做心理准备。术语先对一遍：Frame 对应 Board，Auto layout 对应 Flex layout，组件属性与变体的组织方式也有差异。官方为此专门写了一篇术语对照，迁移前值得先读，能省掉不少「这个功能在哪」的搜索。

生态是另一道坎。Figma 的插件市场和社区模板积累多年，Penpot 的插件体系还在补，遇到冷门需求时未必有现成方案。反过来说，它的开放 API、Webhook 和 MCP 服务让自动化更直接：可以让 AI 工具读到真实的图层与令牌结构，而不是对着一张截图猜。

如果只是讨论阶段的草图，用不着上设计工具。Excalidraw 那类手绘白板更轻，画完直接贴进文档；等界面要落地成组件和令牌，再进 Penpot。图标资源可以走 Iconify 这类聚合库，导出 SVG 后拖进画布，比在工具里一个个画省事。

局限与容易踩的坑

先把不适合的场景说清楚，省得部署完才发现方向错了。

• 自托管镜像晚于云端：官方 FAQ 说明，Docker 镜像在 SaaS 更新之后才发布。想吃新功能，云端比自建快一步。
• 治理能力在付费层：单点登录、集中权限、审计这类组织级功能属于 Enterprise。小团队不受影响，中大型组织要认真算这笔账。
• 技术栈偏窄：代码以 Clojure 与 ClojureScript 为主，渲染层是 Rust 编译的 WebAssembly。出问题时能改的人不多，多数团队只能等上游修。
• 运维成本真实存在：八个容器加一个 Postgres、一个 Valkey，空载也要占掉几百 MB 内存，导出任务还会额外吃 CPU。两核四 G 的机器跑得动，但同时在线人数上去后要留余量。
• 导入导出不是无损：从其他工具导入的文件，图层命名、效果、字体替换常需要手工收拾，别指望一键搬完。
• 新功能与渲染器绑定：描边转路径只在 WebGL 渲染器下可用，老机器或远程桌面环境可能要先解决显卡加速问题。

还有一类坑来自流程而不是软件：很多人部署完就把公网地址发给了同事，邮箱没配、HTTPS 没上、密钥没换。这三件事的顺序应该是先配好 SMTP 与证书，再开放注册。

谁适合用、怎么开始与常见问题

适合的团队

• 设计文件需要留在自己机房，或所在行业对数据出境有要求的团队。
• 设计与前端处在同一个仓库节奏里，希望设计改动也能进代码评审的团队。
• 想用设计令牌打通设计与代码，但不愿为每个席位持续付费的中小团队。

上手三步

1. 先用官方云端账号摸一遍画布：建一个文件、画两个 Board、试一次 Flex 布局和 Inspect 复制。半小时能判断习不习惯。
2. 再起本地实例：改密钥、改公网地址、配 SMTP、挂反向代理，跑通一次邀请流程。这一步跑通，后面的问题都会提前暴露。
3. 最后迁移真实项目：挑一个组件数在二十个以内的页面做试点，把令牌建起来，确认导出的 CSS 能被现有工程直接吃下，再扩大范围。

如果服务器上已经有一套自建服务在跑，用 Coolify 这类自托管部署面板管理 compose 项目会省掉一些手工操作，但反向代理规则和卷备份仍要自己确认一遍。

三个高频问题

问：Penpot 能直接打开 Figma 文件吗？

答：不能原生打开。官方给的是术语对照与迁移思路，实际导入依赖社区工具，或者导出 SVG 后重新组织图层，复杂组件需要重建。

问：免费版有人数限制吗？

答：官方把画布本身描述为免费且不限人数，付费的是 Enterprise 层的组织治理功能。自托管时真正的上限来自你的服务器配置。

问：必须用 HTTPS 吗？

答：官方建议生产环境走 HTTPS。纯 HTTP 下剪贴板等浏览器接口会失效，只能用 disable-secure-session-cookies 这类降级开关顶着，不适合长期使用。

一句话收尾：Penpot 适合把设计资产当成代码资产来管的团队，不适合只想快速画几张图、或者不愿意维护服务器的人。