API 快速入门

几分钟内完成对 sh0 API 的第一次调用：创建 API 密钥、列出应用、重新部署一个应用，并了解响应格式。

Note

API 由您的 sh0 面板提供：设置域名后通过该域名访问，否则通过服务器的 9000 端口访问。所有路径都以 /api/v1 开头。示例使用 https://panel.example.com，请替换为您自己的地址。

创建 API 密钥

在控制台中打开设置 → API 密钥，按需选择访问级别创建密钥并复制：它只显示一次。访问级别说明见API 身份验证。然后将其保存在环境变量中：

Terminal

export SH0_TOKEN="sh0_..."

Warning

请像对待密码一样对待密钥：将其保存在密钥管理工具或环境变量中，切勿放入代码仓库。一旦可能泄露，请立即在设置 → API 密钥中撤销。

第 2 步：列出您的应用

列出您的应用。任何访问级别都可以执行此操作：

Terminal

curl https://panel.example.com/api/v1/apps \
  -H "Authorization: Bearer $SH0_TOKEN"

重新部署应用

使用列表中的应用 ID，为已有应用触发一次新的部署。需要“部署”或“管理”级别。请求体可以为空，但必须是合法的 JSON：

Terminal

curl -X POST https://panel.example.com/api/v1/apps/APP_ID/deployments \
  -H "Authorization: Bearer $SH0_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

要从您自己的代码创建应用，最短的路径是 CLI：sh0 push 会将项目目录作为归档上传并部署，有无 Dockerfile 均可。

响应格式

所有 sh0 API 响应遵循一致的格式：

成功响应：

Success Format

{
  "data": { ... }
}

带分页的列表响应：

List Format

{
  "data": [ ... ],
  "total": 42,
  "page": 1,
  "per_page": 20,
  "pages": 3
}

错误响应：

Error Format

{
  "error": {
    "code": "NOT_FOUND",
    "message": "App with id 'app_xyz' not found"
  }
}

分页

列表端点支持两个查询参数进行分页：

参数	默认值	描述
`page`	1	页码（从 1 开始）
`per_page`	20	每页条目数（最大 100）

Terminal

# Get page 2, 50 items per page
curl "https://panel.example.com/api/v1/apps/APP_ID/deployments?page=2&per_page=50" \
  -H "Authorization: Bearer $SH0_TOKEN"

错误处理

API 使用标准 HTTP 状态码。以下是最常见的：

状态码	含义
200	成功
201	资源已创建
400	错误请求（无效参数）
401	未认证（缺失或无效的令牌）
403	禁止（权限不足）
404	资源未找到
409	冲突（名称重复等）
422	验证错误
429	请求过于频繁
500	内部服务器错误

Tip

始终检查 error.code 字段进行编程错误处理，而非解析消息字符串，消息可能在版本间变化。

后续步骤

现在您可以认证并发起基本 API 调用，探索 sh0 API 的全部功能：

完整 API 参考 -- 包含所有 180+ 端点的交互式浏览器
Git 部署 -- 设置推送即部署工作流
伸缩 -- 通过 API 伸缩应用
监控 -- 获取指标和健康数据

显示可用端点类别的 sh0 API 浏览器

API 认证

完整参考