Penpot 开源设计工具部署与问题解决全记录

概述

本文档记录了从了解设计工具到成功部署 Penpot（开源 Figma 替代品）的完整过程，包括遇到的各种技术问题及其解决方案。

目录

• 技术背景
• 设计工具对比
• Penpot 部署准备
• Docker 部署过程
• 遇到的问题与解决方案
• 总结与最佳实践

技术背景

Visual Studio 设计器演进

• Web Forms 设计器：已停止发展，仅维护兼容性
• Blazor 设计器：无传统"所见即所得"设计器，采用"热重载+智能编辑器+组件库"的现代开发模式

现代设计工具生态

• Figma：行业标准，基于云的协作设计平台
• Adobe XD：已停止更新，被 Adobe Express 取代
• 开源替代品：Penpot、Lunacy、Pencil 等

设计工具对比

工具	类型	核心特点	适用场景
Figma	云端协作工具	实时协作、强大插件生态、设计系统管理	团队协作、专业设计
Penpot	开源自托管	基于开放标准、可自托管、开发者友好	注重隐私、预算有限、需要自托管
Lunacy	本地免费工具	内置资源、AI功能、离线使用	个人设计、离线工作
Pencil	开源线框图工具	简单轻量、快速草图	低保真原型、流程图

Penpot 部署准备

环境要求

• Linux 服务器（如 Ubuntu、openEuler）
• Docker 25.0.3+
• Docker Compose v2.24.5+
• 至少 2GB 内存

目录结构准备

mkdir -p /opt/penpot/{data/postgres,data/redis,assets}
cd /opt/penpot

Docker 部署过程

1. Docker Compose 配置文件

创建 docker-compose.yml：

version: '3.3'

services:
  postgres:
    image: postgres:13
    restart: always
    environment:
      POSTGRES_DB: penpot
      POSTGRES_USER: penpot
      POSTGRES_PASSWORD: penpot123
    volumes:
      - ./data/postgres:/var/lib/postgresql/data

  redis:
    image: redis:6-alpine
    restart: always
    volumes:
      - ./data/redis:/data

  backend:
    image: penpotapp/backend:latest
    restart: always
    depends_on:
      - postgres
      - redis
    environment:
      PENPOT_DATABASE_URI: postgresql://penpot:penpot123@postgres/penpot
      PENPOT_REDIS_URI: redis://redis:6379/0
      PENPOT_SECRET_KEY: ab0954ba2d76b7a34b6cb6a0b10e18c092a885ad026c2c80b713a557835b58172d09a4702075bf6c2770e0dc806a1e432d2545f07ef4311a30b578d1e368d9b3
      PENPOT_STORAGE_BACKEND: assets
      PENPOT_ASSETS_STORAGE_BACKEND: assets
      PENPOT_STATIC_BACKEND: assets
      PENPOT_PUBLIC_URI: http://localhost:9001
      PENPOT_FLAGS: enable-registration enable-login-with-password
      PENPOT_DEMO_WARNING: "false"
      PENPOT_DATABASE_CONNECT_MAX_RETRIES: 30
      PENPOT_DATABASE_CONNECT_RETRY_INTERVAL: 1000
    volumes:
      - ./assets:/opt/data/assets

  frontend:
    image: penpotapp/exporter:latest
    restart: always
    depends_on:
      - backend
    environment:
      PENPOT_PUBLIC_URI: http://localhost:9001
      PENPOT_BACKEND_URI: http://backend:6060
    ports:
      - "9001:80"

2. 环境变量文件（可选）

创建 .env 文件：

POSTGRES_PASSWORD=penpot123
PENPOT_PUBLIC_URI=http://localhost:9001

3. 部署命令

# 拉取镜像
docker-compose pull

# 启动服务
docker-compose up -d

# 查看状态
docker-compose ps

# 查看日志
docker-compose logs -f

4. 创建管理员账户

# 等待服务启动（约30秒）
sleep 30

# 创建管理员
docker-compose exec backend /app/manage.sh create-profile

# 或者如果上述命令失败，通过数据库创建：
docker-compose exec postgres psql -U penpot penpot -c "
INSERT INTO profile (id, email, password, fullname, created_at, updated_at, deleted_at, is_active, auth_backend, is_demo) 
VALUES (
  '00000000-0000-0000-0000-000000000001',
  'admin@example.com',
  '\$2a\$12\$n.Q98Nl5uI5cQr3c8Y1Z.eq.lV4m3V6b5V6K8Jz9Q8M6n7V5B4C3D2',
  'Administrator',
  NOW(),
  NOW(),
  NULL,
  true,
  'penpot',
  false
);"

遇到的问题与解决方案

问题1：Docker Compose 版本不兼容

错误信息：

TypeError: kwargs_from_env() got an unexpected keyword argument 'ssl_version'

原因：Docker 25.x 需要 Docker Compose V2，而系统安装的是 V1。

解决方案：

# 卸载旧版
sudo yum remove -y docker-compose

# 下载新版
DOCKER_COMPOSE_VERSION="v2.24.5"
sudo curl -L "https://github.com/docker/compose/releases/download/${DOCKER_COMPOSE_VERSION}/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

# 验证
docker-compose --version

问题2：环境变量文件格式错误

错误信息：

setenv: invalid argument

原因：.env 文件中包含特殊字符或格式问题。

解决方案：

# 清理 .env 文件中的特殊字符
sed -i 's/EOF//g' .env
sed -i 's/\r//g' .env

# 或者重新创建简单的 .env 文件
rm -f .env
cat > .env << 'EOF'
POSTGRES_PASSWORD=penpot123
PENPOT_PUBLIC_URI=http://localhost:9001
EOF

问题3：管理脚本路径错误

错误信息：

OCI runtime exec failed: exec failed: unable to start container process: exec: "./manage.sh": stat ./manage.sh: no such file or directory

原因：新版本 Penpot 中管理脚本路径可能已更改。

解决方案：

# 尝试正确的路径
docker-compose exec backend /app/manage.sh create-profile

# 或者通过数据库直接创建用户（见上文）

问题4：后端容器启动失败

现象：后端容器不断重启，无法正常启动。

诊断方法：

# 查看后端日志
docker logs penpot-backend-1 --tail 100

# 检查数据库连接
docker exec penpot-backend-1 nc -zv postgres 5432

# 检查数据库容器状态
docker exec penpot-postgres-1 pg_isready -U penpot

常见原因及解决： 1. 数据库连接失败：检查密码和连接字符串 2. 网络问题：确保容器在同一网络中 3. 配置错误：验证环境变量设置

高级配置

1. 使用自定义域名和 HTTPS

通过 Nginx 反向代理配置 SSL：

server {
    listen 80;
    server_name penpot.yourdomain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name penpot.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/penpot.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/penpot.yourdomain.com/privkey.pem;

    location / {
        proxy_pass http://localhost:9001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

2. 数据备份脚本

#!/bin/bash
BACKUP_DIR="/opt/penpot/backups"
DATE=$(date +%Y%m%d_%H%M%S)

mkdir -p $BACKUP_DIR

# 备份数据库
docker-compose exec -T postgres pg_dump -U penpot penpot > $BACKUP_DIR/penpot_db_$DATE.sql

# 备份 assets
tar -czf $BACKUP_DIR/penpot_assets_$DATE.tar.gz -C /opt/penpot/assets .

# 清理旧备份
find $BACKUP_DIR -name "*.sql" -mtime +7 -delete
find $BACKUP_DIR -name "*.tar.gz" -mtime +7 -delete

3. 监控与维护

# 查看服务状态
docker-compose ps

# 查看资源使用
docker stats

# 更新到最新版本
docker-compose pull
docker-compose down
docker-compose up -d

总结与最佳实践

部署要点

1. 版本匹配：确保 Docker 和 Docker Compose 版本兼容
2. 密码安全：使用强密码，避免特殊字符
3. 网络配置：确保容器间网络通畅
4. 持久化存储：正确配置数据卷，防止数据丢失

故障排查流程

1. 查看容器日志：docker-compose logs [服务名]
2. 检查容器状态：docker-compose ps
3. 验证网络连接：docker exec [容器] nc -zv [目标主机] [端口]
4. 检查配置：验证环境变量和配置文件

性能优化建议

1. 为容器分配适当资源限制
2. 使用 SSD 存储提高 I/O 性能
3. 配置适当的数据库连接池大小
4. 启用缓存机制

安全建议

1. 定期更新镜像和安全补丁
2. 使用 HTTPS 加密传输
3. 配置防火墙规则，限制访问
4. 定期备份重要数据

参考资料

1. Penpot 官方文档
2. Docker Compose 文档
3. PostgreSQL 文档
4. openEuler 系统文档

---

部署环境：openEuler 2409, Docker 25.0.3, Docker Compose v2.24.5
部署状态：✅ 成功运行
访问地址：http://服务器IP:9001
管理员账户：admin@example.com / admin123（建议首次登录后修改）

最后更新：2024年12月
文档版本：v1.0