coolify

Coolify

概述

Coolify 是一个可自托管的 PaaS（Vercel/Netlify 的替代方案），可在你自己的基础设施上部署应用、数据库和服务。它提供 REST API 以便以编程方式进行控制，支持多种构建包，并使用 Traefik 进行反向代理和 SSL。

适用场景： 将应用部署到自托管基础设施，通过 API 管理数据库和服务，通过 CI/CD 自动化部署，以及在不受供应商锁定的情况下进行自托管。

不适用场景： 初次安装 Coolify 服务端（请通过浏览器使用官方安装脚本）、管理 Coolify 自身的基础设施（Postgres、Redis，由内部管理），或者托管平台（Vercel、Railway）已能满足需求且无需自托管的情况。

快速参考

模式	方案	关键点
API 身份验证	Authorization: Bearer <token> header	在控制面板中创建令牌，并配置权限范围
列出应用	GET /api/v1/applications	返回所有应用及其状态和配置
触发部署	GET /api/v1/deploy?uuid=<app>&force=true	或使用每个应用的 webhook URL
创建应用	POST /api/v1/applications/public	需要 project_uuid、server_uuid、env_name
更新应用	PATCH /api/v1/applications/<uuid>	接受构建、健康检查、域名和限制字段
自动部署	在 Advanced > General 中启用	每次向已配置的分支推送时部署
Webhook 部署	curl GET <webhook_url> -H "Authorization: Bearer ..."	通过 CI 流水线控制部署
GitHub Actions 部署	构建镜像、推送到镜像仓库、触发 webhook	在部署前全面控制构建和测试
Nixpacks 构建	从源代码自动检测	对受支持的语言无需配置
Dockerfile 构建	将构建包设为 dockerfile	全面控制构建流程
Compose 构建	以 docker-compose.yaml 作为事实来源	使用 Coolify 标签构建多服务堆栈
环境变量	通过 API 或控制面板按环境配置	在 Compose 中通过 ${VAR} 语法进行插值
域名路由	使用 fqdn 字段或 Compose 中的 Traefik 标签	通过 Let's Encrypt 自动配置 SSL
健康检查	通过 API 配置路径、间隔和重试次数	running:healthy 状态的必要条件

常见错误

错误	正确做法
API 返回“Unauthenticated”	除 Bearer 令牌外，还要添加 Accept: application/json 标头
无法读取敏感字段（自动部署等）	令牌需要 view:sensitive 或 * 权限范围
未触发自动部署	确认 GitHub App 已连接，并已在 Advanced 中启用自动部署
使用没有部署权限的 API 令牌	令牌需要明确的 deploy 权限才能触发部署
Compose 服务的健康检查失败	为非 HTTP 服务添加 exclude_from_hc: true 标签
Webhook 部署未添加身份验证标头	调用 webhook 时始终添加 Authorization: Bearer <token>
构建时无法使用环境变量	在 Advanced 菜单中使用构建参数，而非运行时环境变量
Compose 服务之间无法通信	在同一堆栈网络中使用服务名称作为主机名

委派

• API 探索：使用 Explore Agent 发现现有的 Coolify 资源
• Dockerfile 优化：使用 Task Agent 检查用于 Coolify 部署的 Dockerfile
• CI/CD 流水线设计：使用 Plan Agent 制定部署工作流策略

如果有 docker 技能，请将 Dockerfile 编写、多阶段构建和镜像优化委派给它。 如果有 github-actions 技能，请将工作流语法和 CI 流水线模式委派给它。 如果有 ci-cd-architecture 技能，请将部署策略和环境晋级委派给它。

参考资料

• API：身份验证、端点、常见操作和权限范围
• 部署：自动部署、webhook、GitHub Actions 和 CI/CD 流水线
• 构建包：Nixpacks、Dockerfile、Compose 约定和配置