Penpot项目Docker部署完全指南

前言：关于自托管Penpot的技术要求

Penpot作为一款开源的设计协作平台，支持通过Docker进行自托管部署。但需要明确的是，这种部署方式需要使用者具备以下技术基础：

• Docker和Docker Compose的基本操作能力
• 基础的DNS管理知识
• 反向代理配置经验

如果您对这些技术栈不太熟悉，建议考虑使用Penpot提供的SaaS服务，或者选择更简单的一键部署方案。

一、Docker环境准备

1.1 安装Docker和Docker Compose

部署Penpot前，需要确保系统中已安装以下工具：

docker --version
docker compose version

如果尚未安装，请参考Docker官方文档完成安装。不同操作系统（Linux/Windows/macOS）的安装方式略有差异，建议选择与您系统匹配的安装方式。

二、快速启动Penpot服务

2.1 获取Docker Compose文件

Penpot官方提供了标准的docker-compose.yaml文件，可通过以下任一方式获取：

wget -O docker-compose.yaml [官方文件地址]
# 或
curl -o docker-compose.yaml [官方文件地址]

2.2 启动服务

执行以下命令启动所有服务：

docker compose -p penpot -f docker-compose.yaml up -d

启动完成后，Penpot将在本地9001端口提供服务，可通过http://localhost:9001访问。

技术提示：默认情况下会使用最新的Docker镜像，生产环境建议指定具体版本。

2.3 指定版本启动

为保持环境稳定，建议明确指定Penpot版本：

PENPOT_VERSION=2.4.3 docker compose -p penpot -f docker-compose.yaml up -d

三、服务管理与维护

3.1 停止服务

docker compose -p penpot -f docker-compose.yaml down

3.2 配置调整

所有配置参数都集中在docker-compose.yaml文件中：

1. 环境变量：用于设置数据库连接、密钥等
2. 服务参数：调整资源限制、端口映射等
3. 功能开关：通过flags启用/禁用特定功能

建议首次部署时仔细阅读文件中的注释说明。

四、高级管理操作

4.1 使用管理脚本

Penpot提供了manage.py脚本用于执行管理任务，例如创建用户：

docker exec -ti penpot-penpot-backend-1 python3 manage.py create-profile

注意：容器名称可能因环境而异，可通过docker ps命令确认。

4.2 服务升级

升级到新版本的步骤：

docker compose -f docker-compose.yaml pull
docker compose -p penpot -f docker-compose.yaml up -d

重要升级提示：

• 建议按版本顺序逐步升级，避免大版本跳跃
• 从1.x升级到2.0时需特别注意数据迁移

4.3 数据备份

Penpot使用Docker卷存储数据，备份策略应包括：

1. 数据库卷：包含所有用户和项目数据
2. 资源卷：存储用户上传的图片等资源

推荐备份方法：

# 备份数据库
docker run --rm -v penpot_postgres_data:/volume -v $(pwd):/backup alpine tar cvf /backup/db-backup.tar /volume

# 备份资源
docker run --rm -v penpot_assets_data:/volume -v $(pwd):/backup alpine tar cvf /backup/assets-backup.tar /volume

五、生产环境配置建议

5.1 HTTPS配置

生产环境必须启用HTTPS，否则会影响部分功能（如剪贴板API）。配置要点：

1. 获取有效的SSL证书
2. 配置反向代理处理HTTPS
3. 确保WebSocket连接能正常建立

5.2 反向代理配置示例

NGINX配置要点

server {
  listen 443 ssl;
  server_name penpot.example.com;
  
  # 注意与docker-compose中的大小限制保持一致
  client_max_body_size 30M;
  
  # WebSocket支持
  location /ws/ {
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_pass http://localhost:9001;
  }
  
  # 常规请求
  location / {
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_pass http://localhost:9001;
  }
}

Caddy配置示例

penpot.example.com {
    reverse_proxy :9001
    tls /path/to/cert.pem /path/to/key.pem
}

六、故障排查建议

1. 查看日志：docker compose logs
2. 检查服务状态：docker compose ps
3. 数据库连接问题：检查Postgres容器日志
4. 前端加载问题：检查浏览器控制台错误

通过以上完整的Docker部署指南，您应该能够在各种环境中顺利部署和管理Penpot服务。建议首次部署后在测试环境验证所有功能，确认无误后再迁移到生产环境。