penpot容器启动失败主因是postgresql连接失败或环境变量缺失，需检查postgres服务状态、显式配置penpot_database_url、清理旧volume；前端8080端口不通需确认端口映射与代理配置；邮件不生效须启用enable-smtp flag并正确设置tls/ssl及用户名；公网登录异常多因penpot_public_uri协议与反代不一致导致cookie安全标志错误。
Penpot 容器启动失败：常见报错和修复点
直接执行 docker compose up -d 后容器反复重启或日志里出现 penpot-backend exited with code 1，基本是 PostgreSQL 连接失败或环境变量缺失。Penpot 的后端强依赖数据库初始化完成，而默认配置里没设等待逻辑。
- 检查
docker ps -a确认penpot-postgres-1是否在运行；如果它先挂了，penpot-backend必然失败 - 进入 PostgreSQL 容器手动验证：
docker exec -it penpot-postgres-1 psql -U penpot -d penpot，能进说明服务通，否则看docker logs penpot-postgres-1 -
PENPOT_DATABASE_URL必须显式配置，不能只靠默认值；推荐写成postgres://penpot:penpot@penpot-postgres:5432/penpot（注意 host 名要和docker-compose.yml中 service 名一致） - 首次启动前删掉旧 volume：
docker volume rm penpot_penpot_postgres_v15，避免残留 schema 冲突
前端打不开：8080 端口没响应的几种可能
浏览器访问 http://localhost:8080 显示连接被拒绝，不是 Penpot 自身问题，而是反向代理或端口映射没生效。
- 确认
docker-compose.yml中penpot-frontend的ports段写了- "8080:80"，且没被其他进程占用（ss -tuln | grep :8080） - 如果用了 Traefik 或 Nginx 做代理，
penpot-frontend的expose和labels必须匹配；缺一不可 - 检查容器内 Nginx 配置是否加载成功：
docker exec penpot-frontend-1 cat /etc/nginx/conf.d/default.conf，应包含proxy_pass http://backend - Ubuntu 上若启用了 ufw，需放行：
sudo ufw allow 8080
邮件注册不生效：SMTP 配置关键参数
用户注册后收不到验证邮件，大概率是 SMTP 参数传进去了但没真正启用，或者 TLS/SSL 协议选错。
linux-sysadmin
下载
Linux系统管理专家，覆盖12大模块：用户权限、SSH、存储、网络、systemd、防火墙、日志监控、备份恢复、TLS证书、Ansible、容器、IaC。提供配置、验证、加固、监控、备份、自动化、故障排查、回滚闭环。关键词：useradd、sudo、sshd_config、chmod、SEL...
-
PENPOT_FLAGS必须包含enable-smtp，只配 SMTP 地址不加这个 flag，Penpot 会静默忽略所有邮件配置 - Gmail 类服务必须用
PENPOT_SMTP_PORT: "587"+PENPOT_SMTP_TLS: "true"；用 465 端口则要改用PENPOT_SMTP_SSL: "true" -
PENPOT_SMTP_USERNAME必须是完整邮箱地址（如design@company.com），不是用户名部分 - 测试时用
docker logs penpot-backend-1 | grep -i mail查看是否有Sending verification email日志，没有就说明根本没触发发送流程
公网访问卡在登录页：HTTPS 和 cookie 安全标志冲突
用 cpolar 或 Nginx 反代后能打开首页，但点击登录跳转空白或无限重定向，本质是 Penpot 对 Secure cookie 标志的校验太严格。
-
PENPOT_PUBLIC_URI必须以https://开头，哪怕你用的是 HTTP 反代——否则前端生成的 session cookie 缺少Secure标志，后端拒绝接受 - 如果反代层（如 Nginx）没透传
X-Forwarded-Proto: https，Penpot 会误判为非 HTTPS 请求，导致重定向循环 - 临时调试可加
PENPOT_COOKIE_SECURE: "false"，但上线前务必关掉，否则存在中间人劫持风险 - cpolar 免费版域名每次重启会变，固定域名需升级或换用 frp + 自有域名解析
实际部署中，最易被忽略的是 PostgreSQL 初始化顺序和 PENPOT_PUBLIC_URI 与反代协议的一致性。前者导致服务起不来，后者让整个协作链路在登录环节就断掉。
