POST/api/v1/sites/artifacts上传产物注册站点

Try it 面板需要启用 JavaScript。

客户端在本地完成构建后上传产物包注册站点，服务器校验产物包并落盘到站点目录。

Request

Headers

Name	Data Type	Required	Description
Authorization	string	Yes	Bearer Token 认证，格式 `Bearer <token>`
Content-Type	string	Yes	请求体类型，产物上传为 multipart/form-data；实际发送由浏览器生成带 boundary 的完整头（默认值 "multipart/form-data"）

type RequestHeaders = {
  /** Bearer Token 认证，格式 `Bearer <token>` */
  Authorization: string
  /** 请求体类型，产物上传为 multipart/form-data；实际发送由浏览器生成带 boundary 的完整头，默认值 "multipart/form-data" */
  Content-Type: string
}

{
  "Authorization": "Bearer <token>",
  "Content-Type": "multipart/form-data"
}

Body

Name	Data Type	Required	Description
name	string	Yes	站点名，`^[a-z][a-z0-9-]*$`，保留名 `api` 不可用
domain	string	No	绑定域名，全局唯一
artifact	file	Yes	本地构建产物包，`.tar.gz` 格式，必须包含入口 `index.html`

type RequestBody = {
  /** 站点名，`^[a-z][a-z0-9-]*$`，保留名 `api` 不可用 */
  name: string
  /** 绑定域名，全局唯一 */
  domain?: string
  /** 本地构建产物包，`.tar.gz` 格式，必须包含入口 `index.html` */
  artifact: File
}

{
  "name": "my-docs",
  "domain": "docs.example.com"
}

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	产物包无效	非合法 `.tar.gz`，或缺少入口 `index.html`

Response Code

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

code	Meaning	Notes
0	成功	站点注册成功，返回 SiteDTO
4101	站点名已存在	同名站点已注册
4102	域名已被占用	domain 已绑定到其他站点
4106	产物包无效	非合法 `.tar.gz`，或缺少入口 `index.html`

Examples

POST /api/v1/sites/artifacts HTTP/1.1
Authorization: Bearer <token>
Content-Type: multipart/form-data; boundary=----docdoc

------docdoc
Content-Disposition: form-data; name="name"

my-docs
------docdoc
Content-Disposition: form-data; name="artifact"; filename="site.tar.gz"
Content-Type: application/gzip

<二进制产物包内容>
------docdoc--

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

Remarks

产物包在请求体内完整上传，服务器校验通过并落盘后才返回结果；校验失败的请求不占用站点名，修正后可重发。