jurislm Coolify MCP Server 使用指南
Coolify 是一個開源的自託管 PaaS（Platform as a Service），類似於 Heroku 或 Vercel。此 skill 提供透過 MCP 工具管理 Coolify 基礎設施的完整指南。
MCP 工具概覽
@jurislm/coolify-mcp 提供以下類別的基礎設施管理工具：
| 類別 | 功能 |
|---|---|
| 基礎設施 | 版本檢查、基礎設施概覽 |
| 診斷 | 應用/伺服器診斷、問題掃描 |
| 伺服器 | 列表、詳情、建立/更新/刪除、資源、域名、驗證 |
| 專案與環境 | 專案 CRUD、環境管理 |
| 應用程式 | CRUD（5 種建立方式）、日誌、環境變數、控制 |
| 資料庫 | 8 種類型、備份排程管理、環境變數 |
| 服務 | 建立、更新、刪除、控制 |
| 部署 | 列表、部署、取消、狀態 |
| 私鑰 | SSH 金鑰 CRUD |
| GitHub Apps | 整合管理、儲存庫/分支列表 |
| 儲存空間 | 持久化磁碟區與檔案儲存管理 |
| 排程任務 | Cron 任務 CRUD、執行記錄 |
| 雲端 Token | Hetzner/DigitalOcean Token 管理 |
| 團隊 | 團隊與成員查詢 |
| 批量操作 | 重啟專案、環境變數更新、全面停止、重新部署 |
核心概念：Application vs Service
理解 Application 和 Service 的差異對於正確使用 Coolify 至關重要：
| 類型 | 說明 | FQDN 更新方式 |
|---|---|---|
| Application | 單一應用程式（Git/Dockerfile/Docker Image） | fqdn 或 domains 欄位 |
| Application (docker-compose build pack) | Application 類型但使用 docker-compose 部署 | docker_compose_domains 欄位 |
| Service | Coolify Service 類型的 Docker Compose 組合 | 修改 docker_compose_raw 的 Traefik labels |
Application (docker-compose) 的 FQDN 更新
使用 docker_compose_domains 參數，格式為 [{name, domain}] 的陣列：
coolify_application update uuid="<uuid>" docker_compose_domains=[{"name": "service-name", "domain": "https://example.com"}]
傳 fqdn 或 domains 給這類 app 會得到：
The domains field cannot be used for dockercompose applications.
Coolify Service 的 FQDN 更新
- Service FQDN 由
docker_compose_raw中的 Traefik labels 控制 - 更新方法：修改
docker_compose_raw中的 Traefik labels →coolify_service update→ 重啟
常見誤區
❌ 對 docker-compose Application 傳 fqdn 或 domains
✅ 正確：傳 docker_compose_domains: [{name, domain}]
❌ 嘗試用 coolify_application update 更新 Coolify Service 內的 App FQDN
✅ 正確：更新整個 Service 的 docker_compose_raw
智能查詢功能
除了 UUID，MCP 支援人類易讀識別符：
- 應用域名：
my-app.example.com而非 UUID - 伺服器 IP：
192.168.1.100而非 UUID
常見工作流程
部署新應用程式
- 使用
coolify_infrastructure_overview查看可用伺服器和專案 - 使用
coolify_create_application建立應用程式 - 使用
coolify_update_env_vars設定環境變數 - 使用
coolify_deploy觸發部署 - 使用
coolify_deployment_status監控部署進度
診斷問題
- 使用
coolify_scan_for_issues掃描基礎設施問題 - 使用
coolify_diagnose_application診斷特定應用程式 - 使用
coolify_get_application_logs查看應用程式日誌 - 使用
coolify_server_resources檢查伺服器資源
管理資料庫
- 使用
coolify_list_databases列出所有資料庫 - 使用
coolify_create_database建立新資料庫（支援 PostgreSQL、MySQL、MongoDB、Redis 等） - 使用
coolify_manage_backup_schedule設定備份排程
批量操作
coolify_restart_project_apps- 重啟專案中所有應用程式coolify_batch_env_update- 批量更新環境變數coolify_stop_all- 停止所有服務（維護用）
環境變數設定
使用前需設定以下環境變數：
# ~/.zshenv
export COOLIFY_ACCESS_TOKEN="your-api-token"
export COOLIFY_BASE_URL="https://your-coolify-instance.com"
取得 API Token：Coolify Dashboard → Settings → API Tokens → Generate
最佳實踐
部署策略
- 藍綠部署：使用兩個環境輪流部署，透過域名切換
- 滾動更新：設定
health_check_path確保平滑更新 - 回滾：保留前一版本的部署設定
資源管理
- 定期使用
coolify_server_resources監控資源使用 - 設定資源限制（CPU、記憶體）避免單一應用影響整體
- 使用
coolify_scan_for_issues定期檢查問題
安全考量
- 使用環境變數儲存敏感資料，不要硬編碼
- 定期輪換 API Token
- 啟用 SSL/TLS（Let's Encrypt 自動管理）
故障排除
部署失敗
- 檢查應用程式日誌：
coolify_get_application_logs - 驗證建置設定（Dockerfile、Nixpacks）
- 確認資源足夠：
coolify_server_resources - 檢查網路連接和防火牆
應用程式無法存取
- 診斷應用程式：
coolify_diagnose_application - 檢查域名設定和 SSL 狀態
- 驗證健康檢查路徑
- 檢查容器狀態
資料庫連接問題
- 確認資料庫正在運行
- 檢查連接字串格式
- 驗證網路政策（內部/外部存取）
- 檢查認證資訊
部署前檢查清單
每次部署新應用前，逐項確認：
環境變數
-
DATABASE_URI已設定且特殊字元已 URL-encode（!→%21） - 內部連線使用 DB UUID 作為 hostname（非 server IP + public port）
- Build-time 變數已標記為 build variable（如
DATABASE_URIfor Payload CMS） - 敏感資料不硬編碼在程式碼中
域名與網路
- FQDN 已設定（Application 直接設定，Service 需改 docker_compose_raw）
- DNS 已解析（Cloudflare wildcard 或獨立 A/CNAME 記錄）
- SSL 證書已簽發（通常自動，等待 1-5 分鐘）
資源
- 伺服器磁碟空間充足：
coolify_server_resources - 記憶體足夠（Next.js build 建議 512MB+）
驗證
- 部署完成後檢查應用程式日誌：
coolify_get_application_logs - 驗證域名可存取
- 確認健康檢查通過
附加資源
參考文件
詳細資訊請參閱：
references/api-reference.md- 完整 API 端點文件references/deployment-patterns.md- 部署模式與最佳實踐references/troubleshooting.md- 詳細故障排除指南