coolify

Coolify

概述

通过终端管理 Coolify 部署、应用、数据库和服务。支持使用 Coolify CLI 执行日常操作，也支持使用 REST API 集成 CI/CD。Coolify 是一个开源、可自托管的 PaaS，可将资源作为 Docker 容器部署到你自己的服务器上。

说明

用户寻求 Coolify 相关帮助时，先确定他们需要执行哪项任务：

任务 A：设置 CLI 上下文

将 CLI 连接到 Coolify 实例：

# Add a context (name, URL, API token)
coolify context add production https://coolify.example.com <api-token>

# List configured contexts
coolify context list

# Switch active context
coolify context use production

# Verify connection
coolify context verify

在 Coolify 控制面板的 Keys & Tokens > API tokens 下创建 API 令牌。权限级别：

• read-only — 查看资源，不包含敏感数据
• read:sensitive — 查看资源，包括密钥
• * — 完全访问权限（部署和修改操作所需）

任务 B：部署应用

# Deploy by UUID
coolify deploy uuid <app-uuid>

# Deploy by name
coolify deploy name my-api

# Deploy multiple resources at once
coolify deploy batch app1-uuid,app2-uuid,db-uuid

# List recent deployments
coolify app deployments list <app-uuid>

# View deployment logs
coolify app deployments logs <deployment-uuid>

# Cancel a running deployment
coolify deploy cancel <deployment-uuid>

通过 API（用于 CI/CD 流水线）：

curl -X POST "https://coolify.example.com/api/v1/deploy" \
  -H "Authorization: Bearer $COOLIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"uuid": "app-uuid-here"}'

任务 C：管理环境变量

# List env vars for an application
coolify app env list <app-uuid>

# Create a single env var
coolify app env create <app-uuid> --key DATABASE_URL --value "postgres://user:pass@db:5432/myapp"

# Sync from a .env file (creates missing, updates existing, leaves others untouched)
coolify app env sync <app-uuid> --file .env.production

# Bulk update via API
curl -X PATCH "https://coolify.example.com/api/v1/applications/<uuid>/envs/bulk" \
  -H "Authorization: Bearer $COOLIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"key": "NODE_ENV", "value": "production"}, {"key": "PORT", "value": "3000"}]'

任务 D：管理数据库

# List all databases
coolify database list

# Create a PostgreSQL database
coolify database create postgresql --name my-postgres --server <server-uuid>

# Start/stop/restart a database
coolify database start <db-uuid>
coolify database stop <db-uuid>
coolify database restart <db-uuid>

# Create a backup configuration
coolify database backup create <db-uuid> --frequency "0 2 * * *" --s3 <s3-uuid>

# Trigger a backup immediately
coolify database backup trigger <backup-uuid>

支持的数据库类型：PostgreSQL、MySQL、MariaDB、MongoDB、Redis、ClickHouse、Dragonfly、KeyDB。

任务 E：管理应用和服务

# List all applications
coolify app list

# Get application details
coolify app get <app-uuid>

# Start/stop/restart an application
coolify app start <app-uuid>
coolify app stop <app-uuid>
coolify app restart <app-uuid>

# View application logs
coolify app logs <app-uuid>

# List one-click services
coolify service list

# Start/stop a service
coolify service start <service-uuid>
coolify service stop <service-uuid>

任务 F：服务器和资源管理

# List all servers
coolify server list

# Validate a server (checks SSH, Docker, prerequisites)
coolify server validate <server-uuid>

# List all resources across servers
coolify resources list

# Get server details (JSON output for scripting)
coolify server get <server-uuid> --format json

示例

示例 1：部署 Next.js 应用并同步环境变量

用户请求：“将我的 Next.js 应用部署到 Coolify，并同步生产环境变量”

执行步骤：

# First, sync env vars from local .env.production
$ coolify app env sync abc123-def456 --file .env.production
Synced 12 environment variables (3 created, 9 updated)

# Trigger deployment
$ coolify deploy uuid abc123-def456
Deployment queued: dep-789xyz

# Monitor deployment
$ coolify app deployments logs dep-789xyz
[2024-01-15 10:23:01] Building with Nixpacks...
[2024-01-15 10:23:45] Build completed successfully
[2024-01-15 10:23:50] Deploying container...
[2024-01-15 10:24:02] Health check passed
[2024-01-15 10:24:03] Deployment successful

示例 2：设置启用自动备份的 PostgreSQL 数据库

用户请求：“在 Coolify 上创建一个 PostgreSQL 数据库，并启用每晚备份”

执行步骤：

# Create the database
$ coolify database create postgresql --name analytics-db --server srv-abc123
Created database: db-xyz789 (PostgreSQL 16)

# Create backup schedule (daily at 2 AM)
$ coolify database backup create db-xyz789 --frequency "0 2 * * *" --s3 s3-backup-config
Backup schedule created: backup-111222

# Verify it's running
$ coolify database list
UUID          NAME           TYPE         STATUS
db-xyz789     analytics-db   postgresql   running

示例 3：通过 GitHub Actions 进行 CI/CD 部署

用户请求：“设置从 GitHub Actions 自动部署”

GitHub Actions 工作流：

# .github/workflows/deploy.yml
name: Deploy to Coolify
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Coolify deployment
        run: |
          curl -X POST "${{ secrets.COOLIFY_URL }}/api/v1/deploy" \
            -H "Authorization: Bearer ${{ secrets.COOLIFY_TOKEN }}" \
            -H "Content-Type: application/json" \
            -d '{"uuid": "${{ secrets.COOLIFY_APP_UUID }}"}'

指南

• 安全存储 Coolify API 令牌。切勿将其提交到版本控制系统。在 CI/CD 中将 COOLIFY_TOKEN 用作环境变量。
• 使用 coolify context 管理多个 Coolify 实例（生产、预发布）。避免硬编码 URL。
• coolify app env sync 命令不会造成破坏——不会删除文件中未列出的环境变量。可使用此命令安全地同步。
• 部署会排队，并在每台服务器上依次处理。如果部署似乎延迟，请检查队列。
• 排查部署失败问题时，务必先检查 coolify app deployments logs <deployment-uuid>。
• 数据库备份需要在 Coolify 中配置兼容 S3 的存储目标（AWS S3、MinIO、Backblaze B2 等）。
• 在任何 CLI 命令中使用 --format json，即可获取适用于脚本的机器可读输出。
• 如需详细的 API 端点参考，请参阅 references/api-reference.md。