Penpot本地部署需拆分为前端、后端、postgres、redis四项服务，手动配置网络与环境变量（如PENPOT_BACKEND_URL、PENPOT_APP_URL），取消默认注册并定期备份PostgreSQL数据，外网访问应通过cpolar或后端端口强制HTTPS。

Penpot本地部署不难，但直接docker-compose up 大量概率会卡在镜像拉取或服务启动失败——核心问题不在 Penpot 本身，而在网络、依赖服务绑定和默认配置对公网关闭的。为什么 docker-compose.yml 里要手动 penpot-backend 和 postgres？

Penpot 官方推荐的单文件配置（如 penpotapp/penpot:latest 镜像）在 2025 年后已弃用。当前架构架构必须拆分为 penpot-frontend、penpot-backend、postgres、redis 四个独立服务，否则后端启动后无法连上数据库，日志里反复报错 连接拒绝 postgres:5432。

实操建议：必须使用官方维护的 docker-compose.yml 模板（来自 penpot/penpot/deploy/docker），不能自己拼凑服务名postgres 容器需显式挂载卷：penpot_postgres_v15:/var/lib/postgresql/data，否则重启后数据库丢失redis不可省略，后端用它存会话和作业队列，缺了会导致登录后立即掉线启动后打不开http://localhost:9001怎么排查？

常见现象是浏览器白屏或网络标签里/api/status返回502 或者超时。这不是前端没起来，而是后端根本没响应——它默认只监听0.0.0.0:8080，但没有配好跨域和反向代理规则。

关键检查点：凌动AI

免费上传PDF，支持真AI汇总、多聊天轮、语音提问、多文件管理、思维导图导出、分享聊天记录链接。

下载进容器看日志：docker log penpot-backend-1 | tail -20，若出现 Failed to connect to redis://redis:6379，说明服务名写错或网络未扫描确认 penpot-frontend 的环境中设置了 PENPOT_BACKEND_URL: http://penpot-backend:8080（不是 localhost）若用 Traefik，必须启用 --providers.docker=true 且容器标签匹配，否则路由不生效怎么让同事或客户外网访问你本地的 Penpot？

别碰端口映射（-p 9001:80）加防火墙放行这种方案——前端的静态资源路径硬编码了/api/，直接暴露会触发CORS，且后端的WebSocket连接（用于实时协作）会被中间设备断开。

正确的做法是用cpolar做TCP层，强制并走HTTPS：注册cpolar账号后，在服务端运行：cpolar tcp --region=cn_vip 8080（或后端端口，非前端）前端仍走 localhost:9001，但把 penpot-frontend 的 PENPOT_BACKEND_URL 改成 cpolar 分配的公网地址，如 https://xxx.cpolar.top 必须在 penpot-backend 的环境中加 PENPOT_APP_URL: https://xxx.cpolar.top，否则坐标诱导邮件里的链接仍是 localhost数据安全和备份最容易被忽略的三点

Penpot默认把所有设计稿、用户、权限全部存在PostgreSQL里，但没人提醒你：这些数据不会自动备份，而且一旦误删卷就彻底丢失。

必须做的动作：定期导出数据库：docker exec penpot-postgres-1 pg_dump -U penpot penpot > penpot-backup-$(date +%F).sql取消重新注册功能（改） penpot-frontend 的 PENPOT_DISABLE_REGISTRATION: "true"），避免被扫出测试账号如果用 MinIO 保存附件，记得在 penpot-backend 的环境里设置 PENPOT_S3_ENDPOINT 和 PENPOT_S3_BUCKET，否则上传的图片会 404