POST/api/v1/sites注册 git 源站点

Try it 面板需要启用 JavaScript。

从 git 仓库注册站点。服务器克隆仓库并执行静态构建，构建完成后同步返回站点信息；请求在构建完成前保持等待。

Request

Headers

Name	Data Type	Required	Description
Authorization	string	Yes	Bearer Token 认证，格式 `Bearer <token>`
Content-Type	string	Yes	请求体类型，JSON 请求体为 application/json（默认值 "application/json"）

type RequestHeaders = {
  /** Bearer Token 认证，格式 `Bearer <token>` */
  Authorization: string
  /** 请求体类型，JSON 请求体为 application/json，默认值 "application/json" */
  Content-Type: string
}

{
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
}

Body

Name	Data Type	Required	Description
name	string	Yes	站点名，`^[a-z][a-z0-9-]*$`，保留名 `api` 不可用
domain	string	No	绑定域名，全局唯一；缺省时站点仅可经路径前缀访问
sourceUrl	string	Yes	git 仓库地址
ref	string	No	git 分支或标签，缺省为仓库默认分支

type RequestBody = {
  /** 站点名，`^[a-z][a-z0-9-]*$`，保留名 `api` 不可用 */
  name: string
  /** 绑定域名，全局唯一；缺省时站点仅可经路径前缀访问 */
  domain?: string
  /** git 仓库地址 */
  sourceUrl: string
  /** git 分支或标签，缺省为仓库默认分支 */
  ref?: string
}

{
  "name": "my-docs",
  "domain": "docs.example.com",
  "sourceUrl": "https://github.com/acme/docs.git",
  "ref": "main"
}

Response

Body

SiteDTO

Name	Data Type	Required	Description
name	string	Yes	站点名，全局唯一
domain	string	No	绑定域名，缺省时站点仅可经路径前缀访问
sourceKind	string	Yes	来源类型
sourceUrl	string	No	git 仓库地址，sourceKind 为 `git` 时存在
ref	string	No	git 分支或标签，sourceKind 为 `git` 时存在
pages	number	Yes	站点页面总数
builtAt	string	Yes	最近一次构建完成时间，ISO 8601 格式

type SiteDTO = {
  /** 站点名，全局唯一 */
  name: string
  /** 绑定域名，缺省时站点仅可经路径前缀访问 */
  domain?: string
  /** 来源类型 */
  sourceKind: 'git' | 'artifact'
  /** git 仓库地址，sourceKind 为 `git` 时存在 */
  sourceUrl?: string
  /** git 分支或标签，sourceKind 为 `git` 时存在 */
  ref?: string
  /** 站点页面总数 */
  pages: number
  /** 最近一次构建完成时间，ISO 8601 格式 */
  builtAt: string
}

{
  "name": "my-docs",
  "domain": "docs.example.com",
  "sourceKind": "git",
  "sourceUrl": "https://github.com/acme/docs.git",
  "ref": "main",
  "pages": 42,
  "builtAt": "2026-01-12T08:30:00.000Z"
}

HTTP Code

HTTP Status	Meaning	Notes
200	成功	站点注册成功，返回 SiteDTO
409	站点名已存在	同名站点已注册
409	域名已被占用	domain 已绑定到其他站点
422	git 克隆失败	sourceUrl 不可达或不是有效 git 仓库
422	构建失败	渲染或产物生成阶段出错

Response Code

响应为统一响应包装（见响应格式），其中 code 字段：

code	Meaning	Notes
0	成功	站点注册成功，返回 SiteDTO
4101	站点名已存在	同名站点已注册

Examples

POST /api/v1/sites HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "my-docs",
  "domain": "docs.example.com",
  "sourceUrl": "https://github.com/acme/docs.git",
  "ref": "main"
}

{
  "id": "b0f2c1d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
  "code": 0,
  "messages": [],
  "result": {
    "name": "my-docs",
    "domain": "docs.example.com",
    "sourceKind": "git",
    "sourceUrl": "https://github.com/acme/docs.git",
    "ref": "main",
    "pages": 42,
    "builtAt": "2026-01-12T08:30:00.000Z"
  }
}

Remarks