Penpot 私有化部署指南5 条命令上线附对象存储、SMTP 与故障排查【免费下载链接】penpotPenpot: The open-source design platform for Product teams that need scalable collaboration.项目地址: https://gitcode.com/GitHub_Trending/pe/penpotPenpot 是一款自托管的开源设计协作平台支持画板、组件库、原型和代码查看。适合需要在内网拥有设计数据主权、又希望团队在线协作的技术负责人。按本文操作你可以在 10 分钟内拉起一套完整实例并完成对象存储、邮件、HTTPS 的生产配置。一键启动的最小步骤前置条件Docker 20.10 以上、Docker Compose v2磁盘预留 10GB。生产配置模板就放在仓库的 docker/images/docker-compose.yaml 里直接复用即可# 1. 克隆仓库compose 文件在仓库内 git clone https://gitcode.com/GitHub_Trending/pe/penpot # 2. 进入目录把生产 compose 文件复制为当前项目的 compose 文件 cd penpot cp docker/images/docker-compose.yaml docker-compose.yaml # 3. 给 backend 生成一个主密钥见下文上线前加固 python3 -c import secrets; print(secrets.token_urlsafe(64)) # 4. 把上一步输出的值填入 docker-compose.yaml 的 PENPOT_SECRET_KEY # 5. 拉起全部服务 docker compose up -d完成后浏览器打开http://localhost:9001看到注册页即部署成功。镜像版本由 compose 文件中的PENPOT_VERSION决定不设置时按文件内默认值拉取具体可选版本以官方发布为准。跑起来的是什么6 个容器速览整套实例由 6 个容器组成职责如下排障时先对号入座服务镜像作用penpot-frontendpenpotapp/frontend前端入口宿主机端口 9001penpot-backendpenpotapp/backendAPI、数据库迁移、WebSocket内部端口 6060penpot-postgrespostgres:15业务数据卷penpot_postgres_v15penpot-valkeyvalkey/valkey:8.1WebSocket 通知协调等价于 Redispenpot-exporterpenpotapp/exporterPDF、图片导出penpot-mailcatchsj26/mailcatcher临时 SMTP网页在 1080 端口按需配置生产环境要动的几处compose 文件默认是可跑通配置生产要按场景改下面 4 处。全部变量说明见 docs/technical-guide/configuration.md。对象存储本地卷换 S3默认文件资产存在 Docker 卷penpot_assets里。多台 backend 或需要备份策略时切到 S3 兼容存储只需在 backend 的 environment 里改# S3 兼容存储MinIO、COS 等均可 PENPOT_OBJECTS_STORAGE_BACKEND: s3 PENPOT_OBJECTS_STORAGE_S3_ENDPOINT: https://s3.your-provider.com # 端点地址 PENPOT_OBJECTS_STORAGE_S3_BUCKET: penpot-assets # 桶名 AWS_ACCESS_KEY_ID: your-access-key AWS_SECRET_ACCESS_KEY: your-secret-key邮件注册验证与邀请Penpot 的注册验证和团队邀请都依赖邮件不配 SMTP 时邀请发不出去。compose 里已内置 mailcatch 用于本地验证生产替换为真实 SMTP# 启用 SMTP 功能 PENPOT_FLAGS: ... enable-smtp PENPOT_SMTP_HOST: smtp.your-provider.com # SMTP 服务器 PENPOT_SMTP_PORT: 587 PENPOT_SMTP_USERNAME: your-username PENPOT_SMTP_PASSWORD: your-password PENPOT_SMTP_TLS: true第三方登录一个 flag 加一对凭证默认只有邮箱密码登录。接入 Google 为例flag 控制开关、变量给凭证PENPOT_FLAGS: ... enable-login-with-google # 开启 Google 登录 PENPOT_GOOGLE_CLIENT_ID: your-client-id PENPOT_GOOGLE_CLIENT_SECRET: your-client-secretGitHub、GitLab、LDAP、OIDC 同理对应enable-login-with-github等 flagOAuth 回调地址格式为https://你的域名/api/auth/oidc/callback细节以官方配置文档为准。HTTPS必须走反向代理非 HTTPS 环境下剪贴板等浏览器 API 不可用生产必须上 TLS。compose 文件里内置了 Traefik 的注释示例含 Lets Encrypt 自动证书取消注释并填入域名即可也可以换成自己的 Nginx注意把请求转到 9001 端口并透传X-Forwarded-Proto。同时把文件顶部的PENPOT_PUBLIC_URI改成https://penpot.your-domain.com邮件里的链接依赖它。上线前必改的参数这一节集中处理安全项改完再对外暴露端口PENPOT_SECRET_KEY主密钥用于派生会话、邀请等子密钥。模板里是change-this-insecure-key必须换成python3 -c import secrets; print(secrets.token_urlsafe(64))的输出。数据库密码backend 里PENPOT_DATABASE_PASSWORD与 postgres 的POSTGRES_PASSWORD都是弱密码penpot两处同步改成强密码。收紧 flags模板默认带disable-email-verification和disable-secure-session-cookiescompose 文件头部明确警告——暴露到公网前应移除这两项同时建议加disable-registration防止陌生人注册。健康检查backend 提供http://容器:6060/health端点postgres 已有内置pg_isready检查建议给 frontend、backend 各加一条基于/health的 healthcheck并在编排层配置restart: always模板已默认开启。3 个高频故障的处理上传大文件报 413 或截断现象导入超过几十 MB 的设计文件失败。排查docker compose config | grep MAX_BODY。解法把PENPOT_HTTP_SERVER_MAX_BODY_SIZE调大到目标值模板默认 367001600约 350MB反向代理层的client_max_body_size要同步调大。页面空白或登录跳转异常现象9001 能打开但界面白屏、或登录后反复跳回。排查docker compose ps看 frontend/backend 是否都running再看浏览器控制台。解法90% 是PENPOT_PUBLIC_URI与浏览器实际访问地址不一致或 HTTP 访问了本应 HTTPS 的域名改 URI 后docker compose restart。邀请邮件发不出现象创建团队发邀请无反应。排查docker compose logs penpot-backend | grep -i smtp。解法确认enable-smtpflag 在、SMTP 变量指向真实服务器若还在用 mailcatch到http://localhost:1080收件箱确认邮件是否已生成区分没发和发不到。更多报错对照可查 docs/technical-guide/troubleshooting.md。还可以往哪走监控后端自带日志与指标输出可直接接入 Prometheus/日志平台。CI/CD 与自动化实例配好访问令牌后导出、批量操作都能脚本化。性能Postgres 定期 VACUUM、Valkey 内存上限、S3 分流静态资产。完整变量清单以官方文档 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），仅供参考
Penpot 私有化部署指南：5 条命令上线，附对象存储、SMTP 与故障排查
Penpot 私有化部署指南5 条命令上线附对象存储、SMTP 与故障排查【免费下载链接】penpotPenpot: The open-source design platform for Product teams that need scalable collaboration.项目地址: https://gitcode.com/GitHub_Trending/pe/penpotPenpot 是一款自托管的开源设计协作平台支持画板、组件库、原型和代码查看。适合需要在内网拥有设计数据主权、又希望团队在线协作的技术负责人。按本文操作你可以在 10 分钟内拉起一套完整实例并完成对象存储、邮件、HTTPS 的生产配置。一键启动的最小步骤前置条件Docker 20.10 以上、Docker Compose v2磁盘预留 10GB。生产配置模板就放在仓库的 docker/images/docker-compose.yaml 里直接复用即可# 1. 克隆仓库compose 文件在仓库内 git clone https://gitcode.com/GitHub_Trending/pe/penpot # 2. 进入目录把生产 compose 文件复制为当前项目的 compose 文件 cd penpot cp docker/images/docker-compose.yaml docker-compose.yaml # 3. 给 backend 生成一个主密钥见下文上线前加固 python3 -c import secrets; print(secrets.token_urlsafe(64)) # 4. 把上一步输出的值填入 docker-compose.yaml 的 PENPOT_SECRET_KEY # 5. 拉起全部服务 docker compose up -d完成后浏览器打开http://localhost:9001看到注册页即部署成功。镜像版本由 compose 文件中的PENPOT_VERSION决定不设置时按文件内默认值拉取具体可选版本以官方发布为准。跑起来的是什么6 个容器速览整套实例由 6 个容器组成职责如下排障时先对号入座服务镜像作用penpot-frontendpenpotapp/frontend前端入口宿主机端口 9001penpot-backendpenpotapp/backendAPI、数据库迁移、WebSocket内部端口 6060penpot-postgrespostgres:15业务数据卷penpot_postgres_v15penpot-valkeyvalkey/valkey:8.1WebSocket 通知协调等价于 Redispenpot-exporterpenpotapp/exporterPDF、图片导出penpot-mailcatchsj26/mailcatcher临时 SMTP网页在 1080 端口按需配置生产环境要动的几处compose 文件默认是可跑通配置生产要按场景改下面 4 处。全部变量说明见 docs/technical-guide/configuration.md。对象存储本地卷换 S3默认文件资产存在 Docker 卷penpot_assets里。多台 backend 或需要备份策略时切到 S3 兼容存储只需在 backend 的 environment 里改# S3 兼容存储MinIO、COS 等均可 PENPOT_OBJECTS_STORAGE_BACKEND: s3 PENPOT_OBJECTS_STORAGE_S3_ENDPOINT: https://s3.your-provider.com # 端点地址 PENPOT_OBJECTS_STORAGE_S3_BUCKET: penpot-assets # 桶名 AWS_ACCESS_KEY_ID: your-access-key AWS_SECRET_ACCESS_KEY: your-secret-key邮件注册验证与邀请Penpot 的注册验证和团队邀请都依赖邮件不配 SMTP 时邀请发不出去。compose 里已内置 mailcatch 用于本地验证生产替换为真实 SMTP# 启用 SMTP 功能 PENPOT_FLAGS: ... enable-smtp PENPOT_SMTP_HOST: smtp.your-provider.com # SMTP 服务器 PENPOT_SMTP_PORT: 587 PENPOT_SMTP_USERNAME: your-username PENPOT_SMTP_PASSWORD: your-password PENPOT_SMTP_TLS: true第三方登录一个 flag 加一对凭证默认只有邮箱密码登录。接入 Google 为例flag 控制开关、变量给凭证PENPOT_FLAGS: ... enable-login-with-google # 开启 Google 登录 PENPOT_GOOGLE_CLIENT_ID: your-client-id PENPOT_GOOGLE_CLIENT_SECRET: your-client-secretGitHub、GitLab、LDAP、OIDC 同理对应enable-login-with-github等 flagOAuth 回调地址格式为https://你的域名/api/auth/oidc/callback细节以官方配置文档为准。HTTPS必须走反向代理非 HTTPS 环境下剪贴板等浏览器 API 不可用生产必须上 TLS。compose 文件里内置了 Traefik 的注释示例含 Lets Encrypt 自动证书取消注释并填入域名即可也可以换成自己的 Nginx注意把请求转到 9001 端口并透传X-Forwarded-Proto。同时把文件顶部的PENPOT_PUBLIC_URI改成https://penpot.your-domain.com邮件里的链接依赖它。上线前必改的参数这一节集中处理安全项改完再对外暴露端口PENPOT_SECRET_KEY主密钥用于派生会话、邀请等子密钥。模板里是change-this-insecure-key必须换成python3 -c import secrets; print(secrets.token_urlsafe(64))的输出。数据库密码backend 里PENPOT_DATABASE_PASSWORD与 postgres 的POSTGRES_PASSWORD都是弱密码penpot两处同步改成强密码。收紧 flags模板默认带disable-email-verification和disable-secure-session-cookiescompose 文件头部明确警告——暴露到公网前应移除这两项同时建议加disable-registration防止陌生人注册。健康检查backend 提供http://容器:6060/health端点postgres 已有内置pg_isready检查建议给 frontend、backend 各加一条基于/health的 healthcheck并在编排层配置restart: always模板已默认开启。3 个高频故障的处理上传大文件报 413 或截断现象导入超过几十 MB 的设计文件失败。排查docker compose config | grep MAX_BODY。解法把PENPOT_HTTP_SERVER_MAX_BODY_SIZE调大到目标值模板默认 367001600约 350MB反向代理层的client_max_body_size要同步调大。页面空白或登录跳转异常现象9001 能打开但界面白屏、或登录后反复跳回。排查docker compose ps看 frontend/backend 是否都running再看浏览器控制台。解法90% 是PENPOT_PUBLIC_URI与浏览器实际访问地址不一致或 HTTP 访问了本应 HTTPS 的域名改 URI 后docker compose restart。邀请邮件发不出现象创建团队发邀请无反应。排查docker compose logs penpot-backend | grep -i smtp。解法确认enable-smtpflag 在、SMTP 变量指向真实服务器若还在用 mailcatch到http://localhost:1080收件箱确认邮件是否已生成区分没发和发不到。更多报错对照可查 docs/technical-guide/troubleshooting.md。还可以往哪走监控后端自带日志与指标输出可直接接入 Prometheus/日志平台。CI/CD 与自动化实例配好访问令牌后导出、批量操作都能脚本化。性能Postgres 定期 VACUUM、Valkey 内存上限、S3 分流静态资产。完整变量清单以官方文档 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），仅供参考
