Penpot自托管设计协作：Docker部署、MCP接入与Codex生成UI实操记录

前言

Penpot 是一套开源 UI/UX 设计协作平台，现有材料同时展示了两条比较有辨识度的能力：一条是通过 Docker 自托管，把设计稿和协作环境放到自己的服务器或本地电脑；另一条是通过 Penpot MCP Server，让 Codex 等支持 MCP 的 AI Agent 直接读取并操作画布。

本文先用一个实际例子验证 MCP 能力：开启 Penpot MCP，把带 Token 的 MCP 地址交给 Codex，并要求它在当前文件中创建 5 个 390 × 844 的移动端页面。完成后再回到部署部分，使用 PowerShell 一键脚本在 Windows Docker 环境里启动 Penpot。

本地服务跑通后，通过 9001 端口进入登录页并创建账号；随后再配置公网访问，先使用随机地址验证，再用脚本菜单中的【9】把公网域名写回 Penpot 配置并重建容器。

长期使用时，再把随机地址换成固定二级子域名，并再次执行脚本更新访问域名。这样整个过程从"AI 设计效果"一直走到"本地自托管和远程访问"都能形成闭环。

整篇重点放在"设计协作---MCP---Codex生成UI---Docker部署---公网地址重建"这一条实际链路上。

对于第一次接触 Penpot 的人来说，把 MCP 演示和本地部署放在同一篇里也更容易看清它的定位：前者说明 AI 能参与到什么程度，后者则解决这套设计环境到底运行在哪里、怎么长期使用的问题。

1 Penpot为什么值得单独看

很多人第一次接触 Penpot，会直接把它理解成"开源版 Figma"。

这个说法很容易理解，但也会把它真正有意思的地方说窄。

Penpot 本身可以做：

• UI 设计；
• 交互原型；
• 团队协作；
• 设计系统；
• Design Tokens；
• 自托管部署；
• 基于 SVG、CSS、HTML 等开放标准的设计交付。

现有材料里还特别提到了一个方向：MCP / AI 工作流。

也就是说，Penpot 不只是让人自己画，还开始允许 Codex、Cursor、Claude Code、VS Code 等支持 MCP 的 AI 工具进入设计流程。

对开发者来说，这一点比"界面像不像 Figma"更值得观察。

2 先看效果：让Codex通过MCP直接做UI

在正式部署之前，先看一遍最终效果会更容易理解 Penpot MCP 到底在做什么。

当前示例的任务是：

让 Codex 在 Penpot 当前文件和当前页面里，设计一套移动端 H5 学生信息管理系统。

首先在 Penpot 里开启 MCP：

然后复制带 Token 的 MCP 地址。

当前提示词完整保留如下：

我有一个本地 Penpot 实例，已经启用了 MCP。

MCP 地址如下，请把它当作敏感 token，不要在回答中复述，也不要在日志、代码注释、最终回复中打印：

【把你的 Penpot MCP 地址粘贴到这里】

请连接这个 Penpot MCP，并在我当前打开的 Penpot 文件和当前页面里，设计一套"移动端 H5 学生信息管理系统"原型。

要求：
1. 先调用 MCP 工具确认连接状态，读取 Penpot high_level_overview 和必要的 API 信息。
2. 使用 Penpot MCP 的 execute_code 直接在画布中创建设计稿，不要只给文字方案。
3. 设计 5 个移动端页面，尺寸 390 × 844：
   - 首页 / 数据概览
   - 学生列表
   - 学生详情
   - 新增或编辑学生
   - 成绩统计
4. 所有页面内容必须使用中文，不要用英文替代。
5. 页面风格：清爽、现代、适合学校教务/班主任使用，不要做成营销落地页。
6. 每个页面都要包含真实业务信息，例如学生姓名、学号、班级、手机号、考勤状态、综合分、成绩趋势等。
7. 元素需要可编辑，尽量用 Penpot 原生形状和文本创建。
8. 注意中文字体渲染：先创建一个小的中文文本测试并导出/检查。如果中文不可见，不要改成英文，请改用 Penpot 当前环境可显示的中文字体或其他稳定方案，让中文在画布中真实可见。
9. 完成后请告诉我创建了哪些画板，并导出首页预览检查一次。

把这段内容发送给 Codex 或其他支持 MCP 的 AI Agent：

此时 Penpot 画布还是空白：

接着等待 Codex 连接 MCP。

可以看到它已经开始测试连接：

回到 Penpot 页面，也出现了测试页面：

继续等待。

现有材料记录的时间大约是 20 分钟，Codex 最后提示任务完成：

回到浏览器：

可以看到当前示例最终生成了 5 个移动端页面。

这一步实际验证的是：

AI Agent 不只是读取设计稿，而是通过 MCP 在 Penpot 画布里创建了真实、可编辑的页面元素。

这比单纯让 AI"给一份 UI 文字方案"更接近真实设计工作流。

3 Penpot和AI工作流怎么理解

现有材料里提到，Figma 也已经支持 MCP，并且会受到套餐、席位和调用额度等条件限制。

这一部分我按当前材料保留，不扩展成"Penpot 一定比 Figma 更好"这样的结论。

更值得关注的是两种工作流的差别。

Penpot MCP 可以把设计文件里的：

• 页面；
• 图层；
• 组件；
• 样式；
• Design Tokens；

暴露给支持 MCP 的 AI Agent。

于是 AI 可以不只看截图，而是进一步参与：

• 建页面；
• 整理图层；
• 创建组件；
• 调整样式；
• 根据已有设计系统继续生成页面。

这类能力真正改变的是"AI 和设计文件之间怎么交互"。

4 Windows下用Docker部署Penpot

前面的效果演示看完以后，再回头部署。

当前环境要求先安装并启动 Docker。

现有材料采用一个 PowerShell 一键脚本简化 Penpot Docker Compose 部署。

以管理员身份打开 PowerShell，执行：

irm https://gitee.com/jun-wan/script/raw/master/penpot_deploy/deploy-penpot.ps1 | iex

进入脚本菜单：

选择数字【1】：

然后按照提示完成自定义配置，等待镜像拉取和服务启动。

部署完成：

5 确认Penpot本地服务能打开

脚本部署完成以后，通过 9001 端口访问：

看到 Penpot 登录页面：

随后创建账号并进入工作台。

这一层先确认的是：

Docker 容器和 Penpot Web 服务已经正常运行。

至于 MCP、远程访问和公网域名，都应该在这个本地链路稳定以后再继续处理。

6 本地部署和公网访问是两件事

当前 Penpot 可以通过：

localhost:9001

打开。

这说明本机服务正常，但外部设备还不能直接访问。

cpolar 在这里负责的是：

把本地运行的 9001 Web 服务增加一个公网访问入口。

Penpot 仍然运行在本地 Docker 中，设计稿和服务本身不会因为公网映射而自动迁移到别处。

7 安装cpolar

7.1 下载Windows客户端

打开下载页面：

安装完成后验证：

cpolar version

7.2 注册并登录Web UI

注册账号：

注册页面：

注册完成后,在浏览器中输入如下地址访问 web ui管理界面:

然后访问：

http://127.0.0.1:9200

登录：

8 先用随机域名验证公网访问

进入隧道列表：

当前流程可以编辑 website 隧道，也可以新建一条。

参数为：

• 协议：http
• 本地地址：9001
• 地区：China VIP

更新以后查看在线隧道：

这里会看到 Penpot 对应的 HTTP 和 HTTPS 公网地址。

不过这篇和很多普通 Web 服务有一点不同：

生成公网地址以后，还要把这个地址写回 Penpot 的部署配置。

9 把公网域名写回Penpot

回到 PowerShell，再次执行同一条部署管理脚本：

irm https://gitee.com/jun-wan/script/raw/master/penpot_deploy/deploy-penpot.ps1 | iex

进入菜单后选择数字【9】：

然后把在线隧道列表中的公网地址复制进去。

当前示例使用 HTTPS 地址：

脚本会重新构建容器，并应用新的公网地址。

完成以后，在浏览器打开：

可以看到 Penpot 登录页面。

这一步很关键。

它说明 Penpot 不是简单做了端口转发，而是还需要根据最终访问地址重新应用相关配置。

10 随机域名适合测试，长期使用再换固定地址

随机公网地址更适合短期验证。

如果 Penpot 准备长期使用，或者需要把地址持续分享给团队成员，再继续配置固定二级子域名。

进入预留页面：

https://dashboard.cpolar.com/reserved

保留子域名：

这里需要注意：

当前示例参数：

• 地区：China VIP
• 二级域名：例如 penpot
• 描述：可用于后续识别

然后回到隧道列表：

把域名类型改成二级子域名：

当前配置仍然保持：

• 协议：http
• 本地地址：9001
• 域名类型：二级子域名
• Sub Domain：填写前面保留的名称
• 地区：China VIP

更新以后：

固定公网地址就已经生成。

11 固定域名同样要重新写回Penpot

这一步和随机地址时一样。

固定域名变化以后，还要重新运行 Penpot 部署脚本：

irm https://gitee.com/jun-wan/script/raw/master/penpot_deploy/deploy-penpot.ps1 | iex

进入菜单后再次选择数字【9】：

把新的固定公网域名写入配置。

脚本会重新构建 Penpot 容器并应用新地址。

最终访问：

页面可以正常打开以后，固定公网访问才算真正完成。

12 为什么这篇不能只写成"Penpot部署教程"

因为 Penpot 本身的价值不只在部署。

这篇实际展示了三层东西：

第一层，是 设计工具本身：

UI、原型、组件、设计系统和团队协作。

第二层，是 自托管：

通过 Docker 把数据和服务放到自己的环境里。

第三层，是 AI Agent 工作流：

通过 MCP，让 Codex 直接操作当前 Penpot 文件和页面。

如果只写"如何把容器跑起来"，反而会把这篇最有辨识度的部分丢掉。

13 这类工具真正适合什么人

我觉得 Penpot 更适合几类用户：

• 希望设计稿和项目数据放在自己环境里；
• 个人开发者或小团队；
• 设计和开发协作比较紧密；
• 想尝试 Design Tokens 和开放 Web 标准；
• 已经在用 Codex、Cursor、Claude Code 等 AI 工具；
• 想让 AI 不只生成代码，还进一步进入设计文件。

如果只是偶尔做一张界面图，工具本身是不是自托管，可能并不重要。

但如果设计稿、组件库、内部项目和 AI 工作流开始长期积累，数据放在哪里、工具能不能扩展，就会越来越值得考虑。

总结

整套流程可以拆成三层：Penpot 负责 UI 设计、原型和协作；Docker 负责本地自托管；MCP 则负责让 Codex 等 AI Agent 读取并操作设计文件。

实际部署时，先用一键脚本把本地 9001 服务跑通，再处理公网入口；公网域名生成以后，还需要通过脚本菜单【9】重新写回 Penpot 配置并重建容器，这一步不能只做端口映射就结束。

长期使用时，再把随机地址切换成固定二级子域名，并重复一次公网域名写回流程。

对于希望自己掌握设计数据、又想继续尝试 AI Agent 参与设计流程的用户来说，Penpot 提供的并不只是一个自托管界面工具，而是一套可以继续往设计与代码协作方向扩展的工作环境。