Release 管理 API

管理项目的 Release（对外发布的 API 集合），包括 Release CRUD、别名管理和版本管理。

基础路径

/projects/:projectId/releases

认证方式

所有端点均需要 JWT Bearer Token 或 API Key 认证（combinedAuth 中间件）。

权限说明

请求者必须是项目所有者或项目所属团队的活跃成员。

术语说明

术语	说明
Release	对外发布的完整 API 集合
Alias	Release 的人类可读别名（如 `my-app`），用于构建访问 URL
Version	Release 的版本快照，支持发布/废弃/下线生命周期
Deployment	文档的部署版本，可绑定到 Release 端点

一、Release 管理

1. 获取项目的 Release

GET /projects/:projectId/releases

获取项目关联的 Release 信息。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID

响应 200

json

{
  "release": {
    "id": "uuid",
    "project_id": "uuid",
    "name": "My API",
    "alias": "my-api",
    "content": { ... },
    "created_at": "2026-01-01T00:00:00Z"
  }
}

如果项目没有 Release，返回 { "release": null }。

错误码

状态码	说明
401	未认证
404	项目不存在或无权访问
500	操作失败

2. 创建 Release

POST /projects/:projectId/releases

为项目创建一个新的 Release。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID

Body 参数（JSON）

参数	类型	必填	说明
`name`	string	是	Release 名称

响应 201

json

{
  "release": { ... }
}

错误码

状态码	说明
401	未认证
404	项目不存在或无权访问
409	别名冲突
500	操作失败

3. 更新 Release 内容

PUT /projects/:projectId/releases/:releaseId

更新 Release 的配置内容，包括端点配置、鉴权设置等。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID
`releaseId`	string	是	Release ID

Body 参数（JSON）

参数	类型	必填	说明
`content`	ReleaseDocumentContent	是	Release 配置内容

校验规则：

关闭鉴权（requireAuth === false）时，必须指定 apiKeyId
端点级跳过鉴权（skipAuth === true）时，必须有端点级或全局 apiKeyId

响应 200

json

{
  "release": { ... }
}

错误码

状态码	说明
400	content 缺失、鉴权配置不合法
401	未认证
404	项目不存在、无权访问或 Release 不存在
409	别名冲突
500	操作失败

4. 删除 Release

DELETE /projects/:projectId/releases/:releaseId

删除指定的 Release。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID
`releaseId`	string	是	Release ID

响应 200

json

{
  "success": true
}

错误码

状态码	说明
401	未认证
404	项目不存在、无权访问或 Release 不存在
500	操作失败

二、别名管理

5. 检查别名可用性

GET /projects/:projectId/releases/check-alias/:alias

检查指定别名是否可用。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID
`alias`	string	是	要检查的别名

响应 200

返回别名可用性检查结果。

错误码

状态码	说明
401	未认证
404	项目不存在或无权访问
409	别名已被占用
500	操作失败

6. 设置别名

POST /projects/:projectId/releases/:releaseId/alias

为 Release 设置别名。别名用于构建对外访问 URL。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID
`releaseId`	string	是	Release ID

Body 参数（JSON）

参数	类型	必填	说明
`alias`	string	是	别名。只允许小写字母、数字和连字符，格式匹配 `/^[a-z0-9][a-z0-9-]*[a-z0-9]$/` 或单字符 `/^[a-z0-9]$/`

响应 200

json

{
  "success": true,
  "alias": "my-api"
}

错误码

状态码	说明
400	alias 缺失或格式不合法
401	未认证
404	项目不存在、无权访问或 Release 不存在
409	别名已被其他 Release 占用
500	操作失败

7. 删除别名

DELETE /projects/:projectId/releases/:releaseId/alias

删除 Release 的别名。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID
`releaseId`	string	是	Release ID

响应 200

json

{
  "success": true
}

错误码

状态码	说明
401	未认证
404	项目不存在、无权访问或 Release 不存在
500	操作失败

三、Deployment 列表

8. 获取 Deployment 列表

GET /projects/:projectId/releases/deployments

获取项目下的 Deployment 列表，用于端点绑定选择。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID

响应 200

json

{
  "deployments": [
    {
      "id": "uuid",
      "title": "文档标题",
      "version": "1.2",
      "documentId": "uuid",
      "visibility": "public",
      "createdAt": "2026-01-01T00:00:00Z"
    }
  ]
}

错误码

状态码	说明
401	未认证
404	项目不存在或无权访问
500	查询失败

四、版本管理

9. 创建版本

POST /projects/:projectId/releases/:releaseId/versions

创建版本快照（快照当前 Release 内容）。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID
`releaseId`	string	是	Release ID

响应 201

json

{
  "version": {
    "id": "uuid",
    "version": "1.0",
    "status": "draft",
    "created_at": "2026-01-01T00:00:00Z"
  }
}

错误码

状态码	说明
401	未认证
404	项目不存在、无权访问、Release 不存在或 ID 不匹配
500	操作失败

10. 列出版本

GET /projects/:projectId/releases/:releaseId/versions

获取 Release 的所有版本列表。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID
`releaseId`	string	是	Release ID

响应 200

json

{
  "versions": [
    {
      "id": "uuid",
      "version": "1.0",
      "status": "published",
      "published_at": "2026-01-01T00:00:00Z"
    }
  ]
}

错误码

状态码	说明
401	未认证
404	项目不存在、无权访问、Release 不存在或 ID 不匹配
500	操作失败

11. 发布版本

POST /projects/:projectId/releases/:releaseId/versions/:versionId/publish

将版本状态设为已发布。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID
`releaseId`	string	是	Release ID
`versionId`	string	是	版本 ID

响应 200

json

{
  "success": true
}

错误码

状态码	说明
401	未认证
404	项目不存在、无权访问或版本不存在
500	操作失败

12. 废弃版本

POST /projects/:projectId/releases/:releaseId/versions/:versionId/deprecate

将版本标记为已废弃。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID
`releaseId`	string	是	Release ID
`versionId`	string	是	版本 ID

响应 200

json

{
  "success": true
}

错误码

状态码	说明
401	未认证
404	项目不存在、无权访问或版本不存在
500	操作失败

13. 下线版本

POST /projects/:projectId/releases/:releaseId/versions/:versionId/offline

将版本设为下线状态。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID
`releaseId`	string	是	Release ID
`versionId`	string	是	版本 ID

响应 200

json

{
  "success": true
}

错误码

状态码	说明
401	未认证
404	项目不存在、无权访问或版本不存在
500	操作失败

源码

路由：apps/backend/src/routes/releases.ts
服务：apps/backend/src/services/release.ts、apps/backend/src/services/release-version.ts
类型：apps/backend/src/types/release.ts
参考文档：应用发布指南

Release 管理 API ​

基础路径 ​

认证方式 ​

权限说明 ​

术语说明 ​

一、Release 管理 ​

1. 获取项目的 Release ​

2. 创建 Release ​

3. 更新 Release 内容 ​

4. 删除 Release ​

二、别名管理 ​

5. 检查别名可用性 ​

6. 设置别名 ​

7. 删除别名 ​

三、Deployment 列表 ​

8. 获取 Deployment 列表 ​

四、版本管理 ​

9. 创建版本 ​

10. 列出版本 ​

11. 发布版本 ​

12. 废弃版本 ​

13. 下线版本 ​

源码 ​

Release 管理 API

基础路径

认证方式

权限说明

术语说明

一、Release 管理

1. 获取项目的 Release

2. 创建 Release

3. 更新 Release 内容

4. 删除 Release

二、别名管理

5. 检查别名可用性

6. 设置别名

7. 删除别名

三、Deployment 列表

8. 获取 Deployment 列表

四、版本管理

9. 创建版本

10. 列出版本

11. 发布版本

12. 废弃版本

13. 下线版本

源码