完整 API 参考
完整的 sh0 REST API：/api/v1 下超过 230 个路径、交互式浏览器，以及可下载用于代码生成的 OpenAPI 规范。
交互式 API 浏览器
探索 sh0 API 最简单的方式是通过交互式 API 浏览器，可在以下位置访问：
- 控制台：在 sh0 控制台中打开服务 → API 文档。
- 网站：访问 sh0 网站上的 /api。
显示端点列表及请求/响应预览的交互式 API 浏览器
浏览器允许您：
- 按类别浏览所有端点
- 查看请求参数、头和请求体 Schema
- 查看每个端点的示例响应
- 直接从浏览器尝试端点（连接到 sh0 实例时）
- 复制任意端点的 curl 命令
Tip
API 浏览器使用
utoipa 从 OpenAPI 规范自动生成。它始终与您 sh0 版本中的实际 API 端点保持同步。OpenAPI 规范
sh0 暴露了一个完整的 OpenAPI 3.1 规范，描述每个端点、参数、请求体和响应类型。规范使用 utoipa 从 Rust 源代码自动生成，确保始终准确和最新。
该规范以 JSON 格式提供，无需身份验证，地址为：
curl https://panel.example.com/api/v1/openapi.json 在文档查看器中渲染的 OpenAPI 规范
端点分组
API 按逻辑分组。以下是主要端点类别的概述：
应用
管理应用生命周期——创建、配置、启动、停止、重启和删除应用。
| 方法 | 端点 | 描述 |
|---|---|---|
| GET | /api/v1/apps | 列出所有应用 |
| POST | /api/v1/apps | 创建新应用 |
| POST | /api/v1/apps/upload | 通过上传的归档创建或更新应用 |
| GET | /api/v1/apps/:id | 获取应用详情 |
| PATCH | /api/v1/apps/:id | 更新应用配置 |
| DELETE | /api/v1/apps/:id | 删除应用 |
| POST | /api/v1/apps/:id/restart | 重启应用 |
部署
触发部署、查看构建日志、回滚和管理部署历史。
| 方法 | 端点 | 描述 |
|---|---|---|
| POST | /api/v1/apps/:id/deployments | 触发新的部署 |
| GET | /api/v1/apps/:id/deployments | 列出部署历史 |
| POST | /api/v1/deployments/:id/rollback | 回滚到之前的部署 |
域名与 SSL
列出域名、将其绑定到应用并管理其证书。
| 方法 | 端点 | 描述 |
|---|---|---|
| GET | /api/v1/domains | 列出所有域名 |
| POST | /api/v1/apps/:id/domains | 为应用添加域名 |
| DELETE | /api/v1/apps/:id/domains/:domain_id | 从应用移除域名 |
| GET | /api/v1/apps/:id/certificates | 列出应用的证书 |
数据库
创建数据库服务器，执行备份与恢复。
| 方法 | 端点 | 描述 |
|---|---|---|
| POST | /api/v1/database-servers | 创建数据库服务器 |
| GET | /api/v1/database-servers/:id | 获取数据库服务器详情 |
| POST | /api/v1/backups/trigger | 立即触发备份 |
| POST | /api/v1/backups/:id/restore | 恢复备份 |
其他端点
API 还涵盖以下资源类别：
| 类别 | 端点 | 描述 |
|---|---|---|
| 环境变量 | 8 个端点 | 环境变量 CRUD、批量导入、密钥管理 |
| 存储与挂载 | 6 个端点 | 卷管理、存储提供商 |
| 伸缩 | 4 个端点 | 手动伸缩、自动伸缩规则 |
| 监控 | 12 个端点 | 指标、告警、正常运行时间检查、健康状态 |
| 定时任务 | 5 个端点 | 调度、列出、更新、删除、运行定时任务 |
| 团队与认证 | 15 个端点 | 登录、双因素认证、会话、团队成员、API 密钥 |
| SSH 密钥 | 4 个端点 | 添加、列出、删除 SSH 密钥 |
| 节点 | 8 个端点 | 多服务器管理、节点健康 |
| 服务 | 8 个端点 | 子服务 URL、状态、重启、停止、启动、凭证 |
| 备份 | 11 个端点 | 触发、列出、恢复、下载备份，管理计划任务 |
| 证书 | 6 个端点 | SSL 证书管理、CSR 生成、SSL 模式 |
| 项目 | 11 个端点 | 项目增删改查、成员管理、审计日志 |
| 重定向 | 5 个端点 | URL 重定向规则的创建、更新、启停、删除 |
| 预览环境 | 4 个端点 | PR 预览部署、设置、清理 |
| 设置 | 6 个端点 | 服务器配置、域名、Cloudflare、ACME、DNS |
| 模板 | 5 个端点 | 浏览并从 171 个模板部署 |
| Webhook | 6 个端点 | Git Webhook、部署钩子、通知钩子 |
API 浏览器中的端点分组概览
下载 OpenAPI 规范
您可以下载 OpenAPI 规范，用于文档工具、测试框架或代码生成器。
curl -o sh0-openapi.json https://panel.example.com/api/v1/openapi.json规范文件可以导入以下工具：
- Postman：导入规范以创建预配置所有端点的集合。
- Insomnia：导入以创建交互式 API 工作区。
- Swagger UI：托管您自己的交互式 API 文档。
- Redocly：生成精美的 API 文档。
导入 Postman 的 OpenAPI 规范
配合代码生成器使用
OpenAPI 规范可以与代码生成器配合使用，以任何语言创建类型化的 API 客户端：
TypeScript 客户端（使用 openapi-typescript）：
npx openapi-typescript https://panel.example.com/api/v1/openapi.json \
-o ./src/lib/api/sh0-types.ts Tip
生成的客户端为您的 IDE 提供完整的类型安全和自动补全。它们在构建与 sh0 实例交互的 CI/CD 流水线或自定义自动化工具时特别有用。
VS Code 中生成的 API 类型的 TypeScript 自动补全