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
参考文档：应用发布指南

补充端点

本节补充 plans/need-update-api.md 中尚未覆盖到 docs-site 的接口。端点标题保持严格的 METHOD /path 格式，便于后台文档覆盖率服务识别。

GET /projects/:projectId/releases/:releaseId/debug-logs

获取端点调试日志

认证：JWT Bearer Token 或 API Key（combinedAuth）。 路径参数

参数	说明
`projectId`	项目 ID
`releaseId`	Release ID

请求：无请求体。Query 参数用于分页、过滤、搜索或状态筛选；未传时按后端默认排序与分页返回。

响应：成功时返回目标资源详情、状态或配置对象。

常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。

DELETE /projects/:projectId/releases/:releaseId/debug-logs

清空端点调试日志

认证：JWT Bearer Token 或 API Key（combinedAuth）。 路径参数

参数	说明
`projectId`	项目 ID
`releaseId`	Release ID

请求：通常无请求体；删除类接口通过路径参数定位资源，部分接口会执行软删除、释放绑定或撤回流程。

响应：成功时返回 { "success": true } 或等价删除结果；资源不存在、无权限或存在依赖时返回 4xx。

常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。

PATCH /projects/:projectId/releases/:releaseId/endpoints/:endpointKey/debug

切换端点调试模式

认证：JWT Bearer Token 或 API Key（combinedAuth）。 路径参数

参数	说明
`projectId`	项目 ID
`releaseId`	Release ID
`endpointKey`	Release 端点 key

请求：请求体为 JSON，传入需要变更的字段；未传字段保持不变。

响应：成功时返回创建或更新后的资源对象，或 { "success": true }。

常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。

GET /projects/:projectId/releases/documents

可发布文档列表

认证：JWT Bearer Token 或 API Key（combinedAuth）。 路径参数

参数	说明
`projectId`	项目 ID

请求：无请求体。Query 参数用于分页、过滤、搜索或状态筛选；未传时按后端默认排序与分页返回。

响应：成功时返回列表数据，通常包含 items / data / rows 与分页或统计字段。

常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。

GET /projects/:projectId/releases/documents/:documentId

获取文档发布状态

认证：JWT Bearer Token 或 API Key（combinedAuth）。 路径参数

参数	说明
`projectId`	项目 ID
`documentId`	文档 ID

请求：无请求体。Query 参数用于分页、过滤、搜索或状态筛选；未传时按后端默认排序与分页返回。

响应：成功时返回目标资源详情、状态或配置对象。

常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。

Release 管理 API ​

基础路径 ​

认证方式 ​

权限说明 ​

术语说明 ​

一、Release 管理 ​

1. 获取项目的 Release ​

2. 创建 Release ​

3. 更新 Release 内容 ​

4. 删除 Release ​

二、别名管理 ​

5. 检查别名可用性 ​

6. 设置别名 ​

7. 删除别名 ​

三、Deployment 列表 ​

8. 获取 Deployment 列表 ​

四、版本管理 ​

9. 创建版本 ​

10. 列出版本 ​

11. 发布版本 ​

12. 废弃版本 ​

13. 下线版本 ​

源码 ​

补充端点 ​

GET /projects/:projectId/releases/:releaseId/debug-logs ​

DELETE /projects/:projectId/releases/:releaseId/debug-logs ​

PATCH /projects/:projectId/releases/:releaseId/endpoints/:endpointKey/debug ​

GET /projects/:projectId/releases/documents ​

GET /projects/:projectId/releases/documents/:documentId ​

Release 管理 API

基础路径

认证方式

权限说明

术语说明

一、Release 管理

1. 获取项目的 Release

2. 创建 Release

3. 更新 Release 内容

4. 删除 Release

二、别名管理

5. 检查别名可用性

6. 设置别名

7. 删除别名

三、Deployment 列表

8. 获取 Deployment 列表

四、版本管理

9. 创建版本

10. 列出版本

11. 发布版本

12. 废弃版本

13. 下线版本

源码

补充端点

GET /projects/:projectId/releases/:releaseId/debug-logs

DELETE /projects/:projectId/releases/:releaseId/debug-logs

PATCH /projects/:projectId/releases/:releaseId/endpoints/:endpointKey/debug

GET /projects/:projectId/releases/documents

GET /projects/:projectId/releases/documents/:documentId