团队里越来越多的设计协作被锁在一家 SaaS 的账号体系里账号停用、席位涨价、文件格式不开放任何一条都可能让半年前的设计稿变成打不开的黑盒。对有数据合规要求的团队来说设计稿本身就是产品机密存在别人机房里始终不踏实。只靠“导出一份 SVG 备份”并不够用因为丢的是组件树、变量、交互原型和评审历史这些结构化信息而换一个同类云端工具不过是把同样的风险换个供应商再买一遍。本文分享一套可直接落地的私有方案Docker Compose 自托管 Penpot 本地大模型侧挂 AI 面板 REST API 批量自动化从起服务到排错全部给出可复制配置。一、设计文件锁在云端自托管是唯一解药当设计资产的存亡由别人的账号体系决定时格式不开放云端工具的专有格式一旦停服或停止导出历史稿件只能靠截图抢救。计费不可控席位按人头收费外包、实习生、评审同学都要买权限成本随人数线性膨胀。合规过不了金融、政企项目常要求“数据不出内网”云端协作直接卡在安全评审环节。核心结论自托管不是省钱手段而是把设计文件的所有权、格式权、审计权一次性拿回自己手里。二、Penpot 与 Figma 的能力边界对照先把替代范围说清楚避免抱着“完全一样”的预期去部署能力维度FigmaPenpot 自托管文件所有权云端账号完全落在自己的数据库组件与变量成熟组件、样式、变量均支持插件生态数千款插件 API 较新数量少AI 能力内置 AI 功能需自行接入模型服务协作评审实时多人实时协作 评论够用迁出成本导出受限.penpot包 SVG 随时导出适合迁移内部产品后台、B 端系统、组件规范沉淀这类不依赖重度插件的设计场景。暂缓迁移依赖海量第三方插件或强实时动效协作的 UI 体验设计团队。核心结论Penpot 能覆盖八成日常设计工作短板集中在插件数量与开箱即用的 AI后者正是本方案要补的。三、用 Docker Compose 起一套 Penpot起服务只需编排四个容器这份 compose 覆前后端、数据库与缓存可直接落地services:penpot-frontend:image:penpotapp/frontend:latestports:[8080:8080]environment:-PENPOT_FLAGSenable-registration enable-login-with-passwordpenpot-backend:image:penpotapp/backend:latestenvironment:-PENPOT_DATABASE_URIpostgresql://penpot:penpotpostgres/penpot-PENPOT_REDIS_URIredis://redis:6379/0-PENPOT_SECRET_KEY请替换为32字节随机串-PENPOT_PUBLIC_URIhttp://penpot.internal:8080depends_on:[postgres,redis]postgres:image:postgres:15-alpineenvironment:{POSTGRES_USER:penpot,POSTGRES_PASSWORD:penpot,POSTGRES_DB:penpot}volumes:[pgdata:/var/lib/postgresql/data]redis:image:redis:7-alpinevolumes:pgdata:启动与健康检查只需要两行命令dockercompose up-dcurl-sfhttp://localhost:8080/api/health||echo等待后端就绪强约束启动 → 库表初始化 → 健康检查通过再放流量核心结论****PENPOT_SECRET_KEY与数据库卷是两个绝对不能随手写的位置前者管会话签名后者管设计文件本体。四、反向代理与持久化配置要点服务起来之后真正决定长期可用性的是这三件事HTTPS 与域名用 Nginx/Caddy 反代 8080 端口PENPOT_PUBLIC_URI必须与浏览器访问地址一致否则 WebSocket 升级失败、实时协作静默断开。数据分层备份设计文件在Postgres上传的媒体在后端数据目录两者要一起备份只备数据库会丢图。升级策略先pg_dump再改镜像 tag 重启出现异常直接回滚镜像即可数据库结构基本可向前兼容。核心结论****公网入口、数据库、媒体目录三位一体地备份才能保证灾备后能真正打开文件。五、自托管字体与图标素材库私有部署的另一大收益是把团队资产统一沉淀到一处字体目录将商业字体、品牌字体放进挂载卷团队成员无需各自安装浏览器端自动加载同一份字源。图标库把 SVG 图标集中成一个共享项目设为团队只读库UI 与前端引用同一套命名。模板项目每类产品线建一个“页面模板 组件规范”项目新需求直接复制分支避免从零摆组件。**核心结论**素材一旦集中设计与前端拿到的是同一份真相还原度问题会大幅下降。六、给 Penpot 挂一个本地大模型面板Penpot 本身不内置 AI但插件 API 允许我们把模型能力挂上去先起一个本地侧车服务# sidecar.pyFastAPI 包一层本地模型供插件跨域调用fromfastapiimportFastAPIfromfastapi.middleware.corsimportCORSMiddlewareimporthttpx appFastAPI()app.add_middleware(CORSMiddleware,allow_origins[*],allow_methods[*])app.post(/design/tokens)asyncdeftokens(req:dict):promptf为{req[scene]}生成一套 UI 配色与圆角变量只返回 JSONasyncwithhttpx.AsyncClient(timeout60)asc:rawaitc.post(http://127.0.0.1:11434/api/generate,json{model:qwen2.5:7b,prompt:prompt,stream:False})return{result:r.json()[response]}插件侧在 iframe 里一次fetch就能拿到结果直接写进画布变量// 插件内调用生成配色并批量写入样式constresawaitfetch(http://127.0.0.1:8001/design/tokens,{method:POST,headers:{Content-Type:application/json},body:JSON.stringify({scene:后台管理表格})});constdataawaitres.json();// 解析 JSON 后写入 penpot.currentPage 的 fills / radius用户选画布 → 侧车调本地模型 → 插件回填样式 → 设计师微调定稿**核心结论**模型留在内网、提示词贴合团队规范AI 产出的才不是通用模板感的配色。七、用 REST API 批量生成与导出批量归档、给前端交付切图靠手动点菜单太慢用账号里的 API Token 即可脚本化# export.py拉取项目列表并导出设计包需在个人设置生成 Tokenimportrequests BASEhttps://penpot.internal/apiHEAD{X-Auth-Token:your-token,X-Auth-JWT:your-jwt}teamrequests.post(f{BASE}/rpc/command/get-profile-teams,headersHEAD).json()fortinteam[data]:projectsrequests.post(f{BASE}/rpc/command/get-projects,headersHEAD,json{team-id:t[id]}).json()forpinprojects[data][projects]:requests.post(f{BASE}/rpc/command/get-project-files,headersHEAD,json{project-id:p[id]})print(归档项目,p[name])两种用途CI 每晚定时导出设计包做备份或按文件 ID 导出 SVG 供前端直接引用。两个头部X-Auth-Token与X-Auth-JWT缺一不可这是新版接口最常见的失败点。核心结论设计资产一旦能被脚本读取就自然接进了备份、交付与巡检的工程链路。八、团队权限与版本协作机制自托管不等于放任权限模型要按最小授权配好三级作用域团队 → 项目 → 文件外部顾问只给到单项目的查看权限避免整库可见。角色分工Owner 管成员与导出权限Editor 改设计Viewer 只评论评审同学通常给 Viewer 即可。版本兜底每次大改前用“创建快照”留一个恢复点改崩了可以直接回滚到上一版。**核心结论**权限按项目收敛 关键节点留快照是团队规模变大后不出事故的底线。九、部署排错与常见故障对照把实际会踩的坑列成对照表出问题先查这张现象可能原因处理方式页面 502后端未就绪或依赖库没起docker compose ps查依赖看 backend 日志无法实时协作PENPOT_PUBLIC_URI与访问地址不一致改成浏览器实际域名并重启容器登录后立即掉线Secret Key 变更导致会话失效固定该值扩容节点必须用同一串数据库连不上凭据或网络别名错误核对PENPOT_DATABASE_URI与 compose 同网络图片全部丢失只备份了 DB 没备份媒体目录两处一起归档恢复时同时回填排查顺序先docker compose ps看容器状态再看后端日志最后核对外部入口配置。日志入口docker compose logs -f penpot-backend能覆盖九成启动期问题。核心结论故障八成出在环境变量与网络别名而不是 Penpot 本身。十、从插件到工作流的扩展路线跑稳之后往工程化方向再走三步插件沉淀把配色生成、文案填充、图标搜索封装成团队内部插件随项目复用。对接交付导出脚本挂进 CI设计包与 SVG 自动同步到前端仓库的设计资源目录。留好退路所有文件可导出为.penpot包与 SVG任何时候都不受制于单一平台。**核心结论**自托管拿下控制权AI 面板补上能力短板API 打通交付链路三步合起来才是一套完整设计工作台。结语这套方案的价值不在于复刻某个云端工具的全部功能而在于把设计资产的存放位置、格式出口、扩展入口一次性握在手里起服务只用一份 composeAI 能力靠一个本地侧车和插件接口挂上批量交付由 REST 脚本接进 CI。团队得到的是一条可以随时备份、随时迁移、随时加能力的设计工作流。把设计工作台建在自己的服务器上才是给产品留下的最稳的一条退路。
