Coolify API 技能

通过 Coolify API 全面管理 Coolify 部署、应用程序、数据库、服务和基础设施。

何时使用此技能

当用户需要时使用此技能：

• 将应用程序部署到 Coolify
• 管理应用程序生命周期（启动、停止、重启）
• 查看应用程序日志
• 创建和管理数据库（PostgreSQL、MySQL、MongoDB、Redis 等）
• 部署 Docker Compose 服务
• 管理服务器和基础设施
• 配置环境变量
• 触发和监控部署
• 管理 GitHub App 集成
• 配置 SSH 私钥

先决条件

1. Coolify API 令牌—— 从 Coolify 仪表板生成：

   • 导航至密钥和令牌→API 令牌
   • 创建具有适当权限的令牌（读取，写入，部署）
   • 设置COOLIFY_TOKEN环境变量

2. bash，curl，jq— 运行bash脚本所需

3. API访问— Coolify云（app.coolify.io）或自托管实例

快速开始

基本命令

# List all applications
{baseDir}/scripts/coolify applications list

# Get application details
{baseDir}/scripts/coolify applications get --uuid abc-123

# Deploy an application
{baseDir}/scripts/coolify deploy --uuid abc-123 --force

# View application logs
{baseDir}/scripts/coolify applications logs --uuid abc-123

# Restart an application
{baseDir}/scripts/coolify applications restart --uuid abc-123

---

应用程序

列出应用程序

{baseDir}/scripts/coolify applications list

输出：

{
  "success": true,
  "data": [
    {
      "uuid": "abc-123",
      "name": "my-app",
      "status": "running",
      "fqdn": "https://app.example.com"
    }
  ],
  "count": 1
}

获取应用程序详情

{baseDir}/scripts/coolify applications get --uuid abc-123

应用程序生命周期

# Start
{baseDir}/scripts/coolify applications start --uuid abc-123

# Stop
{baseDir}/scripts/coolify applications stop --uuid abc-123

# Restart
{baseDir}/scripts/coolify applications restart --uuid abc-123

查看日志

{baseDir}/scripts/coolify applications logs --uuid abc-123

环境变量

# List environment variables
{baseDir}/scripts/coolify applications envs list --uuid abc-123

# Create environment variable
{baseDir}/scripts/coolify applications envs create \
  --uuid abc-123 \
  --key DATABASE_URL \
  --value "postgres://user:pass@host:5432/db" \
  --is-runtime true \
  --is-buildtime false

# Update environment variable
{baseDir}/scripts/coolify applications envs update \
  --uuid abc-123 \
  --env-uuid env-456 \
  --value "new-value"

# Bulk update environment variables
{baseDir}/scripts/coolify applications envs bulk-update \
  --uuid abc-123 \
  --json '{"DATABASE_URL":"postgres://...","API_KEY":"..."}'

# Delete environment variable
{baseDir}/scripts/coolify applications envs delete \
  --uuid abc-123 \
  --env-uuid env-456

创建应用

# Public Git repository
{baseDir}/scripts/coolify applications create-public \
  --project-uuid proj-123 \
  --server-uuid server-456 \
  --git-repository "https://github.com/user/repo" \
  --git-branch main \
  --name "My App"

# Private GitHub App
{baseDir}/scripts/coolify applications create-private-github-app \
  --project-uuid proj-123 \
  --server-uuid server-456 \
  --github-app-uuid gh-789 \
  --git-repository "user/repo" \
  --git-branch main

# Dockerfile
{baseDir}/scripts/coolify applications create-dockerfile \
  --project-uuid proj-123 \
  --server-uuid server-456 \
  --dockerfile-location "./Dockerfile" \
  --name "My Docker App"

# Docker Image
{baseDir}/scripts/coolify applications create-dockerimage \
  --project-uuid proj-123 \
  --server-uuid server-456 \
  --docker-image "nginx:latest" \
  --name "Nginx"

# Docker Compose
{baseDir}/scripts/coolify applications create-dockercompose \
  --project-uuid proj-123 \
  --server-uuid server-456 \
  --docker-compose-location "./docker-compose.yml"

---

数据库

列出数据库

{baseDir}/scripts/coolify databases list

获取数据库详情

{baseDir}/scripts/coolify databases get --uuid db-123

数据库生命周期

# Start
{baseDir}/scripts/coolify databases start --uuid db-123

# Stop
{baseDir}/scripts/coolify databases stop --uuid db-123

# Restart
{baseDir}/scripts/coolify databases restart --uuid db-123

# Delete
{baseDir}/scripts/coolify databases delete --uuid db-123

创建数据库

# PostgreSQL
{baseDir}/scripts/coolify databases create-postgresql \
  --project-uuid proj-123 \
  --server-uuid server-456 \
  --name "my-postgres" \
  --postgres-user admin \
  --postgres-password secret \
  --postgres-db myapp

# MySQL
{baseDir}/scripts/coolify databases create-mysql \
  --project-uuid proj-123 \
  --server-uuid server-456 \
  --name "my-mysql"

# MariaDB
{baseDir}/scripts/coolify databases create-mariadb \
  --project-uuid proj-123 \
  --server-uuid server-456 \
  --name "my-mariadb"

# MongoDB
{baseDir}/scripts/coolify databases create-mongodb \
  --project-uuid proj-123 \
  --server-uuid server-456 \
  --name "my-mongo"

# Redis
{baseDir}/scripts/coolify databases create-redis \
  --project-uuid proj-123 \
  --server-uuid server-456 \
  --name "my-redis"

# KeyDB
{baseDir}/scripts/coolify databases create-keydb \
  --project-uuid proj-123 \
  --server-uuid server-456 \
  --name "my-keydb"

# ClickHouse
{baseDir}/scripts/coolify databases create-clickhouse \
  --project-uuid proj-123 \
  --server-uuid server-456 \
  --name "my-clickhouse"

# Dragonfly
{baseDir}/scripts/coolify databases create-dragonfly \
  --project-uuid proj-123 \
  --server-uuid server-456 \
  --name "my-dragonfly"

备份

# List backup configurations
{baseDir}/scripts/coolify databases backups list --uuid db-123

# Create backup configuration
{baseDir}/scripts/coolify databases backups create \
  --uuid db-123 \
  --frequency "0 2 * * *" \
  --enabled true

# Get backup details
{baseDir}/scripts/coolify databases backups get \
  --uuid db-123 \
  --backup-uuid backup-456

# Update backup
{baseDir}/scripts/coolify databases backups update \
  --uuid db-123 \
  --backup-uuid backup-456 \
  --frequency "0 3 * * *"

# Trigger manual backup
{baseDir}/scripts/coolify databases backups trigger \
  --uuid db-123 \
  --backup-uuid backup-456

# List backup executions
{baseDir}/scripts/coolify databases backups executions \
  --uuid db-123 \
  --backup-uuid backup-456

# Delete backup configuration
{baseDir}/scripts/coolify databases backups delete \
  --uuid db-123 \
  --backup-uuid backup-456

---

服务 (Docker Compose)

列出服务

{baseDir}/scripts/coolify services list

获取服务详情

{baseDir}/scripts/coolify services get --uuid service-123

服务生命周期

# Start
{baseDir}/scripts/coolify services start --uuid service-123

# Stop
{baseDir}/scripts/coolify services stop --uuid service-123

# Restart
{baseDir}/scripts/coolify services restart --uuid service-123

# Delete
{baseDir}/scripts/coolify services delete --uuid service-123

创建服务

{baseDir}/scripts/coolify services create \
  --project-uuid proj-123 \
  --server-uuid server-456 \
  --name "My Service" \
  --docker-compose '{"version":"3.8","services":{"web":{"image":"nginx"}}}'

环境变量

# List
{baseDir}/scripts/coolify services envs list --uuid service-123

# Create
{baseDir}/scripts/coolify services envs create \
  --uuid service-123 \
  --key API_KEY \
  --value "secret"

# Update
{baseDir}/scripts/coolify services envs update \
  --uuid service-123 \
  --env-uuid env-456 \
  --value "new-secret"

# Bulk update
{baseDir}/scripts/coolify services envs bulk-update \
  --uuid service-123 \
  --json '{"API_KEY":"secret","DB_HOST":"localhost"}'

# Delete
{baseDir}/scripts/coolify services envs delete \
  --uuid service-123 \
  --env-uuid env-456

---

部署

部署应用

# Deploy by UUID
{baseDir}/scripts/coolify deploy --uuid abc-123

# Force rebuild
{baseDir}/scripts/coolify deploy --uuid abc-123 --force

# Deploy by tag
{baseDir}/scripts/coolify deploy --tag production

# Instant deploy (skip queue)
{baseDir}/scripts/coolify deploy --uuid abc-123 --instant-deploy

列出部署

# List all running deployments
{baseDir}/scripts/coolify deployments list

# List deployments for specific application
{baseDir}/scripts/coolify deployments list-for-app --uuid abc-123

获取部署详情

{baseDir}/scripts/coolify deployments get --uuid deploy-456

取消部署

{baseDir}/scripts/coolify deployments cancel --uuid deploy-456

---

服务器

列出服务器

{baseDir}/scripts/coolify servers list

获取服务器详情

{baseDir}/scripts/coolify servers get --uuid server-123

创建服务器

{baseDir}/scripts/coolify servers create \
  --name "Production Server" \
  --ip "192.168.1.100" \
  --port 22 \
  --user root \
  --private-key-uuid key-456

更新服务器

{baseDir}/scripts/coolify servers update \
  --uuid server-123 \
  --name "Updated Name" \
  --description "Production environment"

验证服务器

{baseDir}/scripts/coolify servers validate --uuid server-123

获取服务器资源

# List all resources on server
{baseDir}/scripts/coolify servers resources --uuid server-123

# Get domains configured on server
{baseDir}/scripts/coolify servers domains --uuid server-123

删除服务器

{baseDir}/scripts/coolify servers delete --uuid server-123

---

项目

列出项目

{baseDir}/scripts/coolify projects list

获取项目详情

{baseDir}/scripts/coolify projects get --uuid proj-123

创建项目

{baseDir}/scripts/coolify projects create \
  --name "My Project" \
  --description "Production project"

更新项目

{baseDir}/scripts/coolify projects update \
  --uuid proj-123 \
  --name "Updated Name"

删除项目

{baseDir}/scripts/coolify projects delete --uuid proj-123

环境

# List environments
{baseDir}/scripts/coolify projects environments list --uuid proj-123

# Create environment
{baseDir}/scripts/coolify projects environments create \
  --uuid proj-123 \
  --name "staging"

# Get environment details
{baseDir}/scripts/coolify projects environments get \
  --uuid proj-123 \
  --environment staging

# Delete environment
{baseDir}/scripts/coolify projects environments delete \
  --uuid proj-123 \
  --environment staging

---

团队

列出团队

{baseDir}/scripts/coolify teams list

获取当前团队

{baseDir}/scripts/coolify teams current

获取团队成员

{baseDir}/scripts/coolify teams members

通过ID获取团队

{baseDir}/scripts/coolify teams get --id 1

---

安全（私钥）

列出私钥

{baseDir}/scripts/coolify security keys list

获取私钥

{baseDir}/scripts/coolify security keys get --uuid key-123

创建私钥

{baseDir}/scripts/coolify security keys create \
  --name "Production Key" \
  --description "SSH key for production servers" \
  --private-key "$(cat ~/.ssh/id_rsa)"

更新私钥

{baseDir}/scripts/coolify security keys update \
  --uuid key-123 \
  --name "Updated Key Name"

删除私钥

{baseDir}/scripts/coolify security keys delete --uuid key-123

---

GitHub 应用

列出GitHub应用

{baseDir}/scripts/coolify github-apps list

获取GitHub应用

{baseDir}/scripts/coolify github-apps get --uuid gh-123

创建GitHub应用

{baseDir}/scripts/coolify github-apps create \
  --name "My GitHub App" \
  --app-id 123456 \
  --installation-id 789012 \
  --private-key "$(cat github-app-key.pem)"

更新GitHub应用

{baseDir}/scripts/coolify github-apps update \
  --uuid gh-123 \
  --name "Updated App Name"

删除GitHub应用

{baseDir}/scripts/coolify github-apps delete --uuid gh-123

列出仓库

{baseDir}/scripts/coolify github-apps repos --uuid gh-123

列出分支

{baseDir}/scripts/coolify github-apps branches \
  --uuid gh-123 \
  --owner myorg \
  --repo myrepo

---

常见用例

部署新应用

1. 列出可用服务器：

   {baseDir}/scripts/coolify servers list
   

2. 创建应用：

   {baseDir}/scripts/coolify applications create-public \
     --project-uuid proj-123 \
     --server-uuid server-456 \
     --git-repository "https://github.com/user/repo" \
     --git-branch main \
     --name "My App"
   

3. 配置环境变量：

   {baseDir}/scripts/coolify applications envs create \
     --uuid <new-app-uuid> \
     --key DATABASE_URL \
     --value "postgres://..." \
     --is-runtime true
   

4. 部署：

   {baseDir}/scripts/coolify deploy --uuid <new-app-uuid>
   

设置带备份的数据库

1. 创建数据库：

   {baseDir}/scripts/coolify databases create-postgresql \
     --project-uuid proj-123 \
     --server-uuid server-456 \
     --name "production-db"
   

2. 配置每日备份：

   {baseDir}/scripts/coolify databases backups create \
     --uuid <db-uuid> \
     --frequency "0 2 * * *" \
     --enabled true
   

3. 触发手动备份：

   {baseDir}/scripts/coolify databases backups trigger \
     --uuid <db-uuid> \
     --backup-uuid <backup-uuid>
   

监控应用健康状态

1. 检查应用状态：

   {baseDir}/scripts/coolify applications get --uuid abc-123
   

2. 查看近期日志：

   {baseDir}/scripts/coolify applications logs --uuid abc-123
   

3. 列出近期部署：

   {baseDir}/scripts/coolify deployments list-for-app --uuid abc-123
   

---

故障排除

"未配置 API 令牌"

原因： COOLIFY_TOKEN环境变量未设置。

解决方案：

export COOLIFY_TOKEN="your-token-here"

或在 OpenClaw 配置中配置于~/.openclaw/openclaw.json:

{
  "skills": {
    "entries": {
      "coolify": {
        "apiKey": "your-token-here"
      }
    }
  }
}

"请求频率超限"

原因:短时间内API请求过多。

解决方案:客户端会自动以指数退避方式重试。请等待重试或降低请求频率。

"应用程序未找到"

原因:UUID无效或不存在。

解决方案:

# List all applications to find correct UUID
{baseDir}/scripts/coolify applications list

"连接被拒绝 (ECONNREFUSED)"

原因:无法连接到 Coolify API。

自托管的解决方案:

# Set custom API URL
export COOLIFY_API_URL="https://your-coolify.example.com/api/v1"

云服务的解决方案:请验证网络连接并确保app.coolify.io可以访问。

"部署失败"

原因:构建或部署错误。

解决方案:

1. 检查部署日志：

   {baseDir}/scripts/coolify deployments get --uuid deploy-456
   

2. 检查应用程序日志：

   {baseDir}/scripts/coolify applications logs --uuid abc-123
   

3. 验证环境变量是否正确：

   {baseDir}/scripts/coolify applications envs list --uuid abc-123
   

Node.js 未找到

原因：Node.js 未安装或不在 PATH 中。

解决方案：

# macOS (via Homebrew)
brew install node

# Verify installation
node --version

---

输出格式

所有命令返回结构化的 JSON：

成功响应

{
  "success": true,
  "data": { ... },
  "count": 42
}

错误响应

{
  "success": false,
  "error": {
    "type": "APIError",
    "message": "Application not found",
    "hint": "Use 'applications list' to find valid UUIDs"
  }
}

---

配置

环境变量

变量	必需	默认值	描述
COOLIFY_TOKEN	是	—	来自 Coolify 仪表板的 API 令牌
COOLIFY_API_URL	否	https://app.coolify.io/api/v1	API 基础 URL（用于自托管）

自托管 Coolify

对于自托管实例，请设置 API URL：

export COOLIFY_API_URL="https://coolify.example.com/api/v1"
export COOLIFY_TOKEN="your-token-here"

---

其他资源

• Coolify 文档： https://coolify.io/docs/
• API 参考：请参阅{baseDir}/references/API.md
• GitHub： https://github.com/coollabsio/coolify
• Discord： https://coollabs.io/discord

---

特殊情况与最佳实践

UUID 与名称

大多数命令需要 UUID，而非名称。请始终先使用list命令查找 UUID：

# Bad: Using name (will fail)
{baseDir}/scripts/coolify applications get --uuid "my-app"

# Good: Using UUID
{baseDir}/scripts/coolify applications list  # Find UUID first
{baseDir}/scripts/coolify applications get --uuid abc-123

强制部署

请谨慎使用--force标志，因为它会从头开始重建：

# Normal deployment (uses cache)
{baseDir}/scripts/coolify deploy --uuid abc-123

# Force rebuild (slower, but ensures clean build)
{baseDir}/scripts/coolify deploy --uuid abc-123 --force

环境变量更新

更新环境变量后，重启应用程序：

# Update env var
{baseDir}/scripts/coolify applications envs update \
  --uuid abc-123 \
  --env-uuid env-456 \
  --value "new-value"

# Restart to apply changes
{baseDir}/scripts/coolify applications restart --uuid abc-123

备份频率

使用cron表达式设置备份计划：

表达式	描述
0 2 * * *	每天凌晨2点
0 */6 * * *	每6小时
0 0 * * 0	每周日午夜
0 0 1 * *	每月1号午夜

---

概述

此技能提供对Coolify API的完整访问，涵盖：

• 应用程序— 部署、生命周期、日志、环境变量
• 数据库— 8种数据库类型、备份、生命周期管理
• 服务— Docker Compose编排
• 部署— 触发、监控、取消
• 服务器——基础设施管理与验证
• 项目——组织与环境管理
• 团队——访问控制与协作
• 安全——SSH密钥管理
• GitHub应用——仓库集成

所有操作均返回结构化JSON，便于代理程序处理。

部分文章来自各大搜索引擎，如有侵权，请与我联系删除。