Penpot 自托管部署实战：从 5 分钟跑通到生产可用的设计协作平台

Penpot 自托管部署实战从 5 分钟跑通到生产可用的设计协作平台【免费下载链接】penpotPenpot: The open-source design platform for Product teams that need scalable collaboration.项目地址: https://gitcode.com/GitHub_Trending/pe/penpot你的设计稿散落在三四个文件里开发拿到的版本和你在改的版本对不上间距和颜色各差一点。把设计平台搬回自己服务器上的思路和搬任何内部系统一样先跑通最小环境再按团队规模加配置。Penpot 是开源的在线设计协作平台画布、组件库、原型交互都在这边实现设计稿还能直接输出对应的 CSS / SVG 代码给开发。本文只讲 Docker 部署这条最主流的路径。 5 分钟跑通最小环境先别管其他先把这个跑通。前置条件一句话机器上装好 Docker 和 Docker Compose4GB 内存起步磁盘留足 10GB 余量。# 1. 克隆仓库拿到官方 compose 文件 git clone https://gitcode.com/GitHub_Trending/pe/penpot cd penpot/docker/images # 2. 启动-p penpot 指定项目名容器和卷都以它为前缀 docker compose -p penpot up -d # 3. 看容器状态等 postgres / valkey 的 healthy 标记出现 docker compose -p penpot ps然后打开http://localhost:9001注册一个账号新建一个文件开始画。想锁定版本的话加一个环境变量即可默认拉的是2.16系列镜像PENPOT_VERSION2.4.3 docker compose -p penpot up -d跑通了恭喜。但别急着开给全公司——先花两分钟搞清楚它到底起了哪些东西。️ 起服之后各容器在干什么你刚才启动的不只是一个前端页面而是一条完整的请求链路浏览器加载的画布应用ClojureScript React 编译出的单页应用跑在penpot-frontend容器里端口 9001页面里每一次操作——改属性、移动图层——都会通过 RPC 打到penpot-backendClojure/JVM 写的服务后端把结构化数据写进 PostgreSQL用户上传的图片、SVG 则落在文件系统卷penpot_assets里这个卷由前端和后端容器共同挂载所以静态资源和二进制素材其实都经过 frontend 这一层。另外两个容易被忽略的容器penpot-valkeyRedis 的开源分支负责 websocket 通知和缓存——多人协作时对方正在编辑这类实时消息就靠它做 pub/sub 广播penpot-exporter内置无头浏览器你点导出 PDF/PNG时它在背后渲染页面截图。penpot-mailcatch只是开发期的临时 SMTP 收件箱生产环境必须换成真实邮件服务。penpot-mcp则是给 AI/自动化工具用的 MCP 接口默认未开启。设计稿与代码同屏协作是 Penpot 区别于纯设计工具的关键能力。 按场景改配置而不是照抄参数所有配置都写在docker/images/docker-compose.yaml里分两类PENPOT_*环境变量调参数PENPOT_FLAGS里的开关项enable-*/disable-*调功能。官方文件已经填好默认值绝大多数项你不需要动。只给自己用默认值即可无需改动。唯一值得知道的compose 里默认带了disable-email-verification注册不用验证邮箱验证邮件由 mailcatch 容器接收打开http://localhost:1080这个网页收件箱就能看到。想开验证把PENPOT_FLAGS里的disable-email-verification删掉、配好 SMTP 就行。给 3~10 人小团队用要改的就三件事都写在PENPOT_FLAGS和PENPOT_SMTP_*上# penpot-backend 的 environment 中 PENPOT_FLAGS: enable-smtp # 去掉 disable-email-verification启用邮箱验证 # 换成真实 SMTP 服务商替换默认的 mailcatch PENPOT_SMTP_HOST: smtp.your-provider.com PENPOT_SMTP_PORT: 587 PENPOT_SMTP_TLS: true # 其余 PENPOT_SMTP_* 按服务商要求填写如果不想让任何人自助注册只走管理员邀请再加一个域名白名单2.1 起需配合enable-email-whitelist标记非空时会自动启用细节以官方文档为准PENPOT_REGISTRATION_DOMAIN_WHITELIST: yourcompany.com给多团队 / 多项目用在团队配置之上认证和协作自动化是重点。登录方式按需组合比如接 GooglePENPOT_FLAGS: enable-login-with-google # 也可用 github / gitlab / ldap / oidc # 只改 backend PENPOT_GOOGLE_CLIENT_ID: client-id PENPOT_GOOGLE_CLIENT_SECRET: client-secret回调地址固定格式填到 OAuth 应用配置里https://你的域名/api/auth/oidc/callback。人员稳定后建议加disable-registration关掉自助注册。自动化方面enable-webhooks打开后可以在团队设置里配置钩子文件更新时通知外部系统enable-mcp则对应penpot-mcp容器供 AI 工具读取和操作设计文件。团队管理、令牌、Webhook 这些界面都在 Web 端完成不需要改配置。 从开发到生产之间还差什么跑在localhost和开给团队之间差一张 checklist。HTTPS 反向代理必须做。非 HTTPS 环境下浏览器剪贴板等 API 直接不可用部分功能会悄悄失效反代要单独放行 WebSocket 升级/ws/notifications和/mcp/ws需要Upgrade头client_max_body_size要和 compose 里的 367001600约 350MB对齐否则大文件上传在代理层就被拒。PENPOT_SECRET_KEY必须改。它是派生会话、邀请令牌等所有密钥的主密钥默认值是change-this-insecure-key不改等于会话可被伪造。生成方式python3 -c import secrets; print(secrets.token_urlsafe(64))。数据库凭证PENPOT_DATABASE_USERNAME/PASSWORD和POSTGRES_PASSWORD默认都是penpot暴露公网前必须换成强密码并保持一致。PENPOT_PUBLIC_URI指向用户实际访问的域名。不改的后果很隐蔽——邀请邮件、验证链接里带的还是 localhost。存储后端默认fs文件系统PENPOT_OBJECTS_STORAGE_BACKEND: fs够用资产规模上来后切 S3 兼容存储compose 里已留好注释示例s3 endpoint bucket。关掉开发期开关公网部署必须去掉disable-secure-session-cookies官方 compose 文件头部注释也明确提示了这一点。 出问题了先定位再动手先建一个习惯任何异常第一反应是docker compose -p penpot ps加docker compose -p penpot logs -f 服务名按连接层→应用层→数据层的顺序排查。连接层端口和代理。9001 是否被反代正确转发WebSocket 路径有没有做Upgrade升级没配的话协作通知会时断时续页面看起来抽风上传 413 先查反代的 body 限制。应用层浏览器 F12。Console 能看到实际版本号和启用的 flagsNetwork 面板定位报错的请求。崩溃时前端会弹系统报告页把report.txt存下来里面带着诊断信息。数据层penpot-postgres起不来通常是卷权限或POSTGRES_*参数问题penpot-valkey不 healthy 时 backend 的depends_on会直接卡住看这两个容器的启动日志。三个高频故障速查# 页面 502 / 一直转圈backend 没起来frontend 在等它 docker compose -p penpot logs penpot-backend # 上传失败先确认反代与 compose 的上传上限一致 # compose 里为 PENPOT_HTTP_SERVER_MAX_BODY_SIZE: 367001600 # 页面空白但请求正常清缓存强刷仍不行再看 frontend 日志 docker compose -p penpot logs penpot-frontend 规模上来后做什么按触发条件→动作来不要提前优化编辑人数超过 10 个 → 数据库卷扩到 50~100GB 并预留弹性空间官方经验值是每多 10 个编辑器约加 5GB上传资产超过 100GB 或开始多台机器 → 切 S3 兼容存储文件系统卷就到头了需要高可用或多副本 → 换 Helm 部署到 Kuberneteshelm repo add penpot http://helm.penpot.app后helm install my-release penpot/penpot可用helm rollback回滚版本开始多人同时在线抱怨卡顿 → 参考官方推荐配置4 核 16GB 内存的服务器足够支撑上千用户瓶颈通常在前端机器性能而非服务器需要持续观测 →docker compose logs -f起步接你自己的日志采集和告警。 日常运维最小集做不做定期备份penpot_postgres_v15和penpot_assets两个卷数据库用pg_dump卷用 Docker 官方备份流程只备份数据库不备份 assets等于丢了一半数据升级先备份docker compose pull后up -d逐小版本升不跨大版本跳直接 1.x 跳到 2.x数据量大时 v2 迁移可能跑几分钟且需人工兜底docker compose ps每周扫一眼 healthy 状态和容器重启次数等用户报障才发现容器早挂了回到开头那个问题部署完这套流程你手里的不再是散落在几个文件里的稿子而是一个所有人共享版本、开发能直接对照 CSS 的线上工作区。下一步可以做两件具体的事用 webhook 把文件变更接到你们的 CI 或通知渠道或者接上 MCP 容器让自动化工具直接读取设计文件。更细的配置项、LDAP/OIDC 全量参数查仓库里的 docs/technical-guide/configuration.md 和 docs/technical-guide/getting-started/docker.md 即可。【免费下载链接】penpotPenpot: The open-source design platform for Product teams that need scalable collaboration.项目地址: https://gitcode.com/GitHub_Trending/pe/penpot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考