coolify-compose

Coolify Docker Compose

将标准 Docker Compose 文件转换为兼容 Coolify 的模板，支持自动生成凭据、动态 URL 和一键部署。

两种部署模式

Coolify 支持两种部署 Compose 文件的方式，功能各不相同：

1. 原始 Compose（粘贴内容）

直接将 Compose YAML 粘贴到 Coolify 的 UI 中。功能有限：

功能	是否支持
image:	✅ 是
build:	❌ 否 — 必须使用预构建镜像
外部配置文件	❌ 否 — 必须使用内联 content:
YAML 锚点（&、*）	✅ 是 — 由 YAML 解析器解析
Coolify 魔法变量	✅ 是
用于内联文件的 content:	✅ 是

适用场景： 快速部署、简单服务、无需自定义镜像。

2. 仓库模式（Git URL）

将 Coolify 指向一个包含 Compose 文件的 Git 仓库。支持完整的 Docker Compose 功能：

功能	是否支持
image:	✅ 是
build:	✅ 是 — 从仓库中的 Dockerfile 构建
外部配置文件	✅ 是 — 支持相对路径
Coolify 魔法变量	✅ 是
用于内联文件的 content:	✅ 是

适用场景： 需要自定义镜像、复杂的多文件配置、仓库中已有 docker-compose.yml。

仓库配置：

my-service/
├── compose.yml          # or docker-compose.yml
├── custom-image/
│   ├── Dockerfile
│   └── config.sql
└── other-files/

# compose.yml - can use build:
services:
  app:
    build:
      context: ./custom-image
      dockerfile: Dockerfile

应使用哪种模式？

原始 Compose 包含……	推荐模式
仅有 image: 引用	两种都可以
build: 指令	仓库模式
要挂载的外部配置文件	仓库模式（或在原始模式中使用 content:）
单个简单服务	原始模式更快

快速开始

每个 Coolify 模板都需要标头和魔法变量：

# documentation: https://example.com/docs
# slogan: Brief description of the service
# category: backend
# tags: api, database, docker
# logo: svgs/myservice.svg
# port: 3000

services:
  app:
    image: myapp:latest
    environment:
      - SERVICE_URL_APP_3000           # Generates URL, routes proxy to port 3000
      - DATABASE_URL=postgres://${SERVICE_USER_POSTGRES}:${SERVICE_PASSWORD_POSTGRES}@db:5432/mydb
    depends_on:
      db:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "http://localhost:3000/health"]
      interval: 5s
      timeout: 10s
      retries: 10

  db:
    image: postgres:16-alpine
    environment:
      - POSTGRES_USER=$SERVICE_USER_POSTGRES
      - POSTGRES_PASSWORD=$SERVICE_PASSWORD_POSTGRES
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER}"]
      interval: 5s
      timeout: 10s
      retries: 10

转换检查清单

转换标准 docker-compose.yml 时：

0. 检查 build: 指令

如果 Compose 中包含 build: 条目：

• 仓库模式： 保留它们。Coolify 将从 Dockerfile 构建。
• 原始模式： 替换为预构建的 image: 引用或查找等效镜像。

# Original with build:
services:
  custom-db:
    build: ./custom-postgres

# Raw mode: find or create pre-built image
  custom-db:
    image: your-registry.com/custom-postgres:latest

# Repository mode: keep build:, include Dockerfile in repo
  custom-db:
    build:
      context: ./custom-postgres
      dockerfile: Dockerfile

1. 添加标头元数据

# documentation: https://...    # Required: URL to official docs
# slogan: ...                   # Required: One-line description  
# category: ...                 # Required: backend, cms, monitoring, etc.
# tags: ...                     # Required: Comma-separated search terms
# logo: svgs/....svg            # Required: Path in Coolify's svgs/ folder
# port: ...                     # Recommended: Main service port

2. 替换硬编码凭据

# ❌ Before
POSTGRES_PASSWORD=mysecretpassword
POSTGRES_USER=admin

# ✅ After  
POSTGRES_PASSWORD=$SERVICE_PASSWORD_POSTGRES
POSTGRES_USER=$SERVICE_USER_POSTGRES

3. 使用魔法变量替换 URL

# ❌ Before
APP_URL=https://myapp.example.com

# ✅ After
- SERVICE_URL_APP_3000    # Declares URL + proxy routing
- APP_URL=$SERVICE_URL_APP  # References it

4. 移除代理服务的 ports:

Coolify 的 Traefik 代理会处理路由。仅在 SSH、UDP 或绕过代理时保留 ports:。

# ❌ Before
ports:
  - "3000:3000"

# ✅ After
environment:
  - SERVICE_URL_APP_3000  # Proxy routes to container port 3000
# No ports: needed

5. 添加健康检查

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
  interval: 5s
  timeout: 10s
  retries: 10

6. 使用带条件的 depends_on

depends_on:
  db:
    condition: service_healthy

魔法变量参考

Coolify 使用 SERVICE_<TYPE>_<IDENTIFIER> 生成值：

类型	示例	结果
PASSWORD	SERVICE_PASSWORD_DB	随机密码
PASSWORD_64	SERVICE_PASSWORD_64_KEY	64 位密码
USER	SERVICE_USER_ADMIN	随机 16 位字符串
BASE64_64	SERVICE_BASE64_64_SECRET	64 位随机字符串
REALBASE64_64	SERVICE_REALBASE64_64_JWT	实际的 Base64 编码字符串
HEX_32	SERVICE_HEX_32_KEY	64 位十六进制字符串
URL	SERVICE_URL_APP_3000	https://app-uuid.example.com + 代理
FQDN	SERVICE_FQDN_APP	app-uuid.example.com（无协议、无端口后缀）

声明与引用（至关重要）

对于 SERVICE_URL，端口后缀用于配置代理路由，但不是变量名的一部分：

# Declare WITH port suffix (configures proxy to route to port 3000)
- SERVICE_URL_MYAPP_3000

# Reference WITHOUT port suffix (gets the URL value)
- APP_URL=$SERVICE_URL_MYAPP
- WEBHOOK_URL=${SERVICE_URL_MYAPP}/webhooks

声明 SERVICE_URL 后，SERVICE_FQDN 会自动可用 — 无需单独声明：

# This single declaration...
- SERVICE_URL_MYAPP_3000

# ...makes BOTH of these available:
- FULL_URL=$SERVICE_URL_MYAPP           # https://myapp-uuid.example.com
- HOSTNAME=${SERVICE_FQDN_MYAPP}        # myapp-uuid.example.com

⚠️ 重要： 端口号前使用连字符，而不是下划线：

SERVICE_URL_MY_SERVICE_3000  # ❌ Breaks parsing
SERVICE_URL_MY-SERVICE_3000  # ✅ Works

完整列表请参阅 references/magic-variables.md。

Coolify 专属扩展

创建目录

volumes:
  - type: bind
    source: ./data
    target: /app/data
    is_directory: true  # Coolify creates this

创建包含内容的文件

在原始模式下无法引用外部文件时，此功能很有用。在仓库模式下，可以像往常一样挂载文件。

# Raw mode: embed file content inline
volumes:
  - type: bind
    source: ./config.json
    target: /app/config.json
    content: |
      {"key": "${SERVICE_PASSWORD_APP}"}

# Repository mode: reference actual file in repo
volumes:
  - ./config/settings.json:/app/config.json:ro

从健康检查中排除

用于运行后退出的迁移/初始化容器：

services:
  migrate:
    command: ["npm", "run", "migrate"]
    exclude_from_hc: true

常见模式

数据库连接

environment:
  - DATABASE_URL=postgres://${SERVICE_USER_POSTGRES}:${SERVICE_PASSWORD_POSTGRES}@db:5432/${POSTGRES_DB:-myapp}

共享凭据

相同的 SERVICE_PASSWORD_* 标识符 = 所有服务使用相同的值：

services:
  app:
    environment:
      - DB_PASS=$SERVICE_PASSWORD_POSTGRES
  db:
    environment:
      - POSTGRES_PASSWORD=$SERVICE_PASSWORD_POSTGRES  # Same value

多服务 URL

services:
  frontend:
    environment:
      - SERVICE_URL_FRONTEND_3000
      - API_URL=$SERVICE_URL_API
  api:
    environment:
      - SERVICE_URL_API_8080=/api  # Path suffix

健康检查模式

# HTTP
test: ["CMD", "wget", "--spider", "-q", "http://localhost:8080"]

# PostgreSQL
test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]

# MySQL/MariaDB  
test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]

# Redis
test: ["CMD", "redis-cli", "ping"]

# Always pass (use sparingly)
test: ["CMD", "echo", "ok"]

环境变量语法

environment:
  - NODE_ENV=production           # Hardcoded, hidden from UI
  - API_KEY=${API_KEY}            # Editable in UI (empty)
  - LOG_LEVEL=${LOG_LEVEL:-info}  # Editable with default
  - SECRET=${SECRET:?}            # Required - blocks deploy if empty

故障排除

问题	解决方案
出现 "No Available Server" 错误	检查 docker ps，查看是否有容器状态异常；确认健康检查通过
Coolify UI 中没有显示变量	使用 ${VAR} 语法；硬编码的 VAR=value 不会显示
未生成 Magic variables	检查拼写；确保使用 SERVICE_ 前缀；确认 Coolify 版本为 v4.0.0-beta.411+
端口路由异常	使用 SERVICE_URL_NAME_PORT；避免在端口前使用下划线；移除 ports:

示例

首先，检查是否有官方模板： 许多热门服务都有 Coolify 官方模板，位于 github.com/coollabsio/coolify/tree/main/templates/compose。如果有，请将其作为正确模式的参考。

将没有官方模板的 compose 文件转换时，请先分析文件并使用匹配的示例：

Compose 文件包含……	使用示例
1 个服务，没有数据库	examples/simple/
2 个服务：应用 + 数据库（postgres/mysql/mariadb）	examples/with-database/
3 个或更多服务，或挂载的配置文件，或多个数据库	examples/multi-service/

快速分析：

• 统计 services: 的数量——如果只有 1 个，使用 simple/
• 查找 postgres、mysql、mariadb、mongo 镜像——如果有 1 个数据库，使用 with-database/
• 查找挂载的 .xml、.json、.yml 配置文件——如果存在，使用 multi-service/
• 查找 clickhouse、redis 或多个数据库——使用 multi-service/

参考资料

• references/magic-variables.md — 完整的变量类型参考
• references/categories.md — 有效的类别值
• Official Coolify Compose Docs — 权威文档
• Official Service Templates — 正确模式的参考实现