Coolify logoCoolify

API 授权

Coolify 使用 Bearer 令牌来验证 API 请求的身份。

令牌的作用域限定为单个团队，并携带控制可用数据和操作的具体权限。

适用人群

本指南适合以下人群：

  • 希望通过 Coolify API 自动化基础设施管理。
  • 正在构建以编程方式与 Coolify 交互的集成。
  • 需要为 MCP 服务器或其他基于 API 的工具设置身份验证。

工作原理

每个 API 请求都必须在 Authorization 头中包含 Bearer 令牌。

Coolify 会验证令牌，识别用户和团队，然后检查令牌的权限是否允许执行所请求的操作。

API 返回的所有资源都限定于创建该令牌所在的团队。

如果您在多个团队之间工作，则需要为每个团队使用单独的令牌。

示例数据

以下数据在本指南中作为示例使用。请将其替换为您的实际实例 URL 和令牌。

  • Coolify URL： https://coolify.shadowarcanist.com
  • API 基础地址： https://coolify.shadowarcanist.com/api/v1
  • API 令牌： 67|abcthisisa123dummytoken

1. 启用 API

您可以从仪表板启用或禁用 API：

  1. 转到侧边栏中的设置 (Settings)。
  2. 点击高级 (Advanced)。
  3. 找到 API 设置部分并开启 API 访问 (API Access)。

提示

可选地，配置允许的 IP (Allowed IPs) 以将 API 访问限制为特定的 IP 地址。

留空或设置为 0.0.0.0 以允许所有 IP（不建议在生产环境中使用）

如果您已经拥有具有 root 权限的令牌，则可以通过编程方式启用或禁用 API：

# 启用 API
curl -X POST https://coolify.shadowarcanist.com/api/v1/enable \
  -H "Authorization: Bearer 67|abcthisisa123dummytoken"

# 禁用 API
curl -X POST https://coolify.shadowarcanist.com/api/v1/disable \
  -H "Authorization: Bearer 67|abcthisisa123dummytoken"

这些端点需要具有 root 权限的令牌。

2. 创建 API 令牌

  1. 转到侧边栏中的安全 (Security)。
  2. 点击 API 令牌 (API Tokens)。
  3. 为您的令牌输入名称。
  4. 选择过期期限 — 7、30、60、90 天、1 年或永不过期。
  5. 选择您需要的权限（见下方的权限）。
  6. 点击创建按钮。

复制您的令牌

令牌仅在创建后显示一次。

请立即复制并将其存储在安全的地方 — 您将无法再次看到它。

您的令牌将如下所示：

67|abcthisisa123dummytoken

| 前面的数字是令牌 ID。后面的所有内容都是密钥 — 两部分都是身份验证所必需的。

3. 发起 API 请求

在每个请求的 Authorization 头中包含您的令牌：

curl https://coolify.shadowarcanist.com/api/v1/teams \
  -H "Authorization: Bearer 67|abcthisisa123dummytoken"

基础 URL

所有 API 端点均可在以下地址访问：

https://coolify.shadowarcanist.com/api/v1

唯一的例外是 /api/health 和 /api/feedback，它们位于 /v1 前缀之外。

权限

每个令牌携带一个或多个权限，控制其可以访问的内容。

在创建令牌时选择正确的权限。

权限访问级别描述
read只读查看资源 — 服务器、项目、应用程序、数据库、服务
read:sensitive读取 + 密钥read 中的所有功能，以及访问密码、私钥、环境变量和日志
write修改创建、更新和删除资源
deploy部署触发部署和管理部署 Webhook
root完全访问绕过所有权限检查 — 对 API 拥有完全控制权

Root 权限

root 权限只能由具有管理员 (Admin) 或所有者 (Owner) 角色的用户分配。

它授予不受限制的 API 访问权限，包括启用/禁用 API 本身。

仅在绝对必要时才使用 root。

权限检查方式

  • 每个 API 端点都需要特定的权限 — read、write 或 deploy。
  • 如果您的令牌没有所需的权限，请求将返回 403 Forbidden 并列出缺失的权限。
  • 具有 root 的令牌完全绕过所有权限检查。
  • read:sensitive 权限控制敏感字段（密码、密钥、私钥、Compose 文件）在响应中是包含还是被屏蔽。

最小权限原则

仅授予您的集成实际需要的权限。

监控仪表板只需要 read。

CI/CD 管道可能需要 read 和 deploy。

将 root 保留给管理自动化。

团队作用域

每个 API 令牌都绑定到创建令牌时处于活动状态的那个团队。该令牌只能访问属于该团队的资源。

  • 服务器、项目、应用程序、数据库和服务都按令牌的团队进行过滤。
  • 如果您在 API 响应中看不到某个资源，它可能属于另一个团队。
  • 要访问多个团队之间的资源，请在每个团队处于活动状态时创建单独的令牌。

速率限制

默认情况下，API 请求的速率限制为每分钟 200 次请求。这适用于全局，并且可以通过 Coolify 的 API_RATE_LIMIT 环境变量进行配置。

当您超过速率限制时，API 将返回 429 Too Many Requests。

IP 白名单

您可以将 API 访问限制为特定的 IP 地址，以便只有受信任的网络可以访问您实例的 API。

配置允许的 IP

  1. 转到侧边栏中的设置 (Settings)。
  2. 点击高级 (Advanced)。
  3. 找到 API 访问允许的 IP (Allowed IPs for API Access) 字段。
  4. 输入您的允许 IP，以逗号分隔。
# 单个 IP
192.168.1.100,203.0.113.50

# CIDR 表示法
10.0.0.0/8,172.16.0.0/16

# 混合
192.168.1.100,10.0.0.0/8,203.0.113.0/24

支持 IPv4 和 IPv6 地址，包括 CIDR 范围。

行为

配置结果
空（默认）允许所有 IP
0.0.0.0允许所有 IP（显式通配符）
逗号分隔的 IP/CIDR仅列出的 IP 可以访问 API

锁出风险

如果您错误地设置了允许的 IP，您可能会被锁定在 API 之外。

在保存之前，请确保您的当前 IP 已包含在内。您始终可以从仪表板更改此设置。

Coolify 会自动去重条目 — 如果特定 IP 已经包含在您列表中的 CIDR 范围内，则冗余条目将被移除。

安全注意事项

  • 令牌存储 — 令牌以 SHA-256 哈希形式存储。Coolify 无法在创建后检索您的令牌 — 如果您丢失了它，请创建一个新的。
  • 令牌过期 — 为用于自动化系统的令牌设置过期期限。Coolify 会在令牌过期前发送电子邮件警告。
  • IP 白名单 — 仅将 API 访问限制为受信任的 IP。参见上面的 IP 白名单。
  • 团队隔离 — 令牌仅访问其团队内的资源。泄露的令牌无法访问其他团队的资源。
  • 吊销 — 从安全 > API 令牌中删除令牌以立即吊销访问权限。

故障排除

常见问题解答 (FAQ)

解答常见的 Coolify 问题，包括 SSH 权限、自定义端口、Cloudflare SSL、并发构建以及应用程序端口映射故障排除。

Create (Docker Compose) POST

Deprecated: Use POST /api/v1/services instead.

On this page

API 授权适用人群工作原理示例数据1. 启用 API2. 创建 API 令牌3. 发起 API 请求基础 URL权限权限检查方式团队作用域速率限制IP 白名单配置允许的 IP行为安全注意事项故障排除