Penpot Docker 部署实战：30 分钟搭建团队自己的开源设计协作平台
【免费下载链接】penpotPenpot: The open-source design platform for Product teams that need scalable collaboration.项目地址: https://gitcode.com/GitHub_Trending/pe/penpot
你有没有遇到过这种情况：产品需求评审时，设计师在云端工具里的稿子，开发截图、量标注、再手动抄 CSS，来回对三遍还是对不齐；更糟的是，设计稿散落在各家订阅服务里，一旦预算砍掉或团队解散，所有资产瞬间找不回来。把设计平台搬到自己服务器上的开源 Penpot，就是冲着这两个痛点去的。它基于纯 Web 技术，Docker 一条命令拉起前端、后端、PostgreSQL、Valkey 缓存和 MCP 服务，浏览器打开 localhost:9001 就能开始画。
能力速览：Penpot 到底帮你解决什么
| 能力 | 解决的问题 |
|---|---|
| 浏览器端实时协作 | 团队多人同时编辑一个文件，不用来回传 .fig 文件 |
| 设计稿直接查看 CSS/SVG 代码 | 开发不用量标注、手抄代码，设计交付即开发输入 |
| 数据全部落在自己的 PostgreSQL + 对象存储 | 设计资产不经过第三方服务器，安全审计可控 |
| 组件、变体与设计令牌 | 设计系统统一维护，全局一键替换 |
| Webhooks、API 令牌、插件 | 设计流程能接进 CI/CD 和内部系统，不是孤岛 |
| MCP 服务容器 | AI 工具可以直接读写你的设计文件 |
最快上手：5 条命令跑通 Penpot
先别纠结配置，把服务跑起来最重要。准备一台装有 Docker 20.10+ 和 Docker Compose 2.0+ 的机器（4GB 内存起步），然后依次执行：
# 1. 获取 Penpot 仓库（只需要其中的 docker-compose 文件） git clone https://gitcode.com/GitHub_Trending/pe/penpot cd penpot # 2. 复制生产用编排文件到工作目录 cp docker/images/docker-compose.yaml ./docker-compose.yaml # 3. 用指定版本启动（固定版本比 latest 更稳） PENPOT_VERSION=2.16 docker compose -p penpot -f docker-compose.yaml up -d # 4. 确认全部容器健康 docker compose -p penpot -f docker-compose.yaml ps打开浏览器访问http://localhost:9001，注册一个账号，Penpot 就跑起来了。默认编排里已经内置了 PostgreSQL 15、Valkey 缓存、文件存储卷和一个临时邮件服务（mailcatcher，在 1080 端口可以查看注册验证邮件），你什么都不用额外装。
停掉服务同样简单：docker compose -p penpot -f docker-compose.yaml down。
场景化配置：按你的团队规模来
所有配置都集中在docker-compose.yaml的环境变量里，改完执行docker compose up -d重新加载即可。下面按团队规模给出建议，而不是逐个变量讲。
个人 / 小团队（3 人以内）
保持默认编排即可，只改一处：把默认密钥换掉。
# 生成一个随机密钥 python3 -c "import secrets; print(secrets.token_urlsafe(64))"把生成结果填入 backend 服务的PENPOT_SECRET_KEY（默认值change-this-insecure-key绝对不能上生产）。内网使用的话，默认的文件系统存储（PENPOT_OBJECTS_STORAGE_BACKEND: fs，资产写入penpot_assets卷）已经够用。
中型团队（3~20 人，对外提供服务）
| 配置项 | 环境变量 / 操作 | 说明 |
|---|---|---|
| 对外地址 | PENPOT_PUBLIC_URI（frontend 和 backend 两处都要改） | 填你的真实域名，如https://design.example.com |
| 正式邮件 | PENPOT_SMTP_HOST/PENPOT_SMTP_PORT/PENPOT_SMTP_USERNAME/PENPOT_SMTP_PASSWORD/PENPOT_SMTP_TLS | 换成真实 SMTP 服务商，别用内置 mailcatch |
| 注册策略 | PENPOT_FLAGS中移除disable-email-verification，移除disable-secure-session-cookies | 开启邮箱验证和安全 Cookie |
| 功能开关 | PENPOT_FLAGS按需追加webhooks、enable-login-with-github等 | 完整列表见编排文件顶部注释 |
| 存储 | 可保持 fs，但确保卷有独立磁盘和备份 | 设计资产都在penpot_assets卷里 |
企业级（多人协作 + 高可用诉求）
| 配置项 | 环境变量 / 操作 | 说明 |
|---|---|---|
| S3 兼容存储 | PENPOT_OBJECTS_STORAGE_BACKEND: s3+PENPOT_OBJECTS_STORAGE_S3_ENDPOINT/PENPOT_OBJECTS_STORAGE_S3_BUCKET/AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY | 资产与计算解耦，可水平扩展 |
| 数据库加固 | 修改POSTGRES_PASSWORD、PENPOT_DATABASE_PASSWORD；确认POSTGRES_INITDB_ARGS=--data-checksums | 默认编排已开启数据校验和 |
| 缓存内存上限 | Valkey 的VALKEY_EXTRA_FLAGS=--maxmemory 128mb --maxmemory-policy volatile-lfu | 默认值对多数实例足够，用户多时调大但别超过 60% 可用内存 |
| 资源规格参考 | 4 核 CPU / 16GB 内存可支撑数千注册用户；数据库磁盘从 50~100GB 起步，每多 10 个活跃编辑器加约 5GB | 官方推荐配置基线 |
生产就绪：HTTPS、性能与监控一张表
生产环境的差别基本都在反向代理层，Penpot 容器本身改动很小。
| 检查项 | 配置方法 | 验收标准 |
|---|---|---|
| HTTPS | 用 Nginx/Caddy/Traefik 反代到9001端口；编排文件里注释掉的 Traefik + Let's Encrypt 片段可直接照抄 | 浏览器显示安全锁；PENPOT_PUBLIC_URI与证书域名一致 |
| WebSocket 支持 | 反代/ws/路径时加Upgrade/Connection头 | 两人同时编辑文件，改动实时同步不卡顿 |
| 上传上限 | 容器侧PENPOT_HTTP_SERVER_MAX_BODY_SIZE默认 367001600（350MB），反代侧client_max_body_size设一致 | 上传 200MB 字体/素材包不报 413 |
| 资源限制 | 给 backend 设 4G 内存上限、frontend 2G（compose 的deploy.resources段） | docker stats下容器不出现 OOM 重启 |
| 指标采集 | backend 暴露 Prometheus 格式的/metrics端点，Prometheus 抓取即可 | 能看到请求延迟与容器指标曲线 |
| 日志留存 | 给 compose 服务加json-file驱动限制max-size: 10m、max-file: 3 | 磁盘不因日志无限增长 |
踩坑急救：症状、定位、修复
| 症状 | 定位命令 | 修复 |
|---|---|---|
| 服务起不来，backend 反复重启 | docker compose -p penpot -f docker-compose.yaml logs penpot-backend | 多半是数据库连接失败；先ps确认penpot-postgres状态为 healthy，再检查PENPOT_DATABASE_URI与密码是否匹配 |
| 页面空白或一直转圈 | 浏览器 F12 看 Console 和 Network 报错；确认PENPOT_PUBLIC_URI与实际访问域名一致 | 域名不匹配会导致资源 404，改完两个服务的PENPOT_PUBLIC_URI重启即可 |
| 注册收不到验证邮件 | docker compose logs penpot-backend \| grep -i smtp | 生产必须配真实 SMTP；临时排障时可打开http://localhost:1080的 mailcatcher 看邮件到底发没发 |
| 大文件上传失败 | 对照反代层与容器层的 body size 限制 | 两边取较小值生效，把反代client_max_body_size调到 ≥350M |
| 崩溃后不知原因 | 崩溃界面直接点 Download report.txt 下载系统报告 | 报告里含版本、配置与错误摘要，排查和提 issue 都靠它 |
日常排障三件套记住就行：docker compose ps看状态、docker compose logs -f跟踪日志、F12 看浏览器控制台。
进阶集成：只讲三个最值得做的
1. CI/CD 自动导出。在团队的「访问令牌」里生成一个 API Token（界面上直接创建，见上文图片），CI 任务里用带Authorization头的请求调用 RPC 接口，定时把设计稿导出为 SVG 或切图，直接推给前端仓库。
2. Webhooks 打通内部系统。PENPOT_FLAGS追加webhooks，在团队设置里填回调地址。设计文件更新、成员变动都会推 JSON 到你的服务，很适合驱动审批流和发布流水线。
3. Prometheus 监控。backend 自带/metrics端点，写一条 scrape 配置指向它，再配个容器存活告警，监控就闭环了，不需要额外装 exporter。
开始你的自托管 Penpot
现在就照着「最快上手」那 4 条命令跑一遍，跑通后再按团队规模补配置。更完整的变量说明、Kubernetes 部署和代理细节，都在仓库里的 docs/technical-guide/getting-started/docker.md 和 docs/technical-guide/configuration.md 中，随查随用。
【免费下载链接】penpotPenpot: The open-source design platform for Product teams that need scalable collaboration.项目地址: https://gitcode.com/GitHub_Trending/pe/penpot
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
