Coolify项目部署Penpot服务常见问题分析与解决方案

前言

在自托管设计协作平台Penpot的部署过程中，许多用户在使用Coolify管理平台时遇到了"server not available"的服务不可用问题。本文将深入分析这一问题的根源，并提供完整的解决方案。

问题现象

用户在Coolify平台上部署Penpot服务时，前端容器持续显示"server not available"错误。检查容器状态发现，除前端容器外其他服务均显示健康状态，前端容器日志中频繁出现"host not found in upstream"的Nginx错误。

根本原因分析

经过技术排查，发现该问题主要由以下因素导致：

1. 端口变更问题：Penpot在2.4.0及后续版本中将前端服务默认端口从80变更为8080，而Coolify的默认配置仍使用80端口。

2. 健康检查机制：前端容器的健康检查配置未同步更新，导致无法正确检测服务状态。

3. 服务依赖关系：容器间的依赖关系(depends_on)设置过于严格，在服务初始化阶段可能造成死锁。

4. 初始化时间不足：后端服务首次启动时需执行数据库迁移，耗时较长，而健康检查超时时间设置不足。

完整解决方案

1. 端口配置调整

修改前端服务配置，将相关端口统一调整为8080：

frontend:
  image: penpotapp/frontend:latest
  environment:
    - SERVICE_FQDN_FRONTEND_8080
  healthcheck:
    test: ['CMD', 'curl', '-f', 'http://127.0.0.1:8080']

2. 健康检查优化

调整各服务的健康检查参数，特别是增加后端服务的检查间隔和重试次数：

penpot-backend:
  healthcheck:
    test: ['CMD', 'curl', '-f', 'http://127.0.0.1:6060/readyz']
    interval: 10s
    timeout: 30s
    retries: 15

3. 访问URL格式

用户访问服务时需在URL中明确指定8080端口，例如：http://your-domain.com:8080

4. 完整配置示例

以下是经过验证的稳定配置：

services:
  frontend:
    image: penpotapp/frontend:latest
    volumes:
      - penpot-assets:/opt/data/assets
    depends_on:
      penpot-backend:
        condition: service_healthy
      penpot-exporter:
        condition: service_healthy
    environment:
      - SERVICE_FQDN_FRONTEND_8080
      - PENPOT_FLAGS=${PENPOT_FRONTEND_FLAGS:-enable-login-with-password}
    healthcheck:
      test: ['CMD', 'curl', '-f', 'http://127.0.0.1:8080']
      interval: 2s
      timeout: 10s
      retries: 15

  penpot-backend:
    image: penpotapp/backend:latest
    # 其他配置保持不变...

实施建议

1. 全新部署：建议用户采用上述完整配置进行全新部署，避免残留配置冲突。

2. 监控日志：部署后应检查各容器日志，特别是后端服务的初始化过程。

3. 性能调优：根据服务器资源配置，可适当调整健康检查间隔和超时参数。

4. 版本兼容性：该解决方案适用于Penpot 2.4.x及以上版本。

总结

通过系统分析Penpot在Coolify平台上的部署问题，我们发现版本迭代带来的配置变更是最主要的挑战。本文提供的解决方案已在多个生产环境验证，能有效解决服务不可用问题。建议用户在部署前充分了解各组件版本特性，并保持配置同步更新，以确保服务稳定运行。