项目密钥 API

管理项目级别的密钥（Secrets），用于 Block 执行时安全读取 API Key、Token 等敏感信息。

基础路径

/projects/:projectId/secrets

认证方式

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

权限说明

• 读取操作（GET）：需要项目 read 权限
• 写入操作（POST / PUT / DELETE）：需要项目 write 权限

---

端点列表

1. 列出项目密钥

GET /projects/:projectId/secrets

列出项目的所有密钥（仅返回掩码信息，不含密文）。

Path 参数

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

响应 200

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "key": "OPENAI_API_KEY",
      "description": "OpenAI 接口密钥",
      "masked_value": "sk-****xxxx",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z"
    }
  ]
}

错误码

状态码	说明
401	未认证
403	无项目读取权限
500	服务器内部错误

---

2. 创建项目密钥

POST /projects/:projectId/secrets

创建一个新的项目密钥。

Path 参数

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

Body 参数（JSON）

参数	类型	必填	说明
key	string	是	密钥名称。必须大写字母开头，仅允许大写字母、数字、下划线，最大 64 字符。匹配 /^[A-Z][A-Z0-9_]*$/
value	string	是	密钥值
description	string	否	密钥描述

响应 201

{
  "success": true,
  "data": {
    "id": "uuid",
    "key": "OPENAI_API_KEY",
    "description": "OpenAI 接口密钥",
    "masked_value": "sk-****xxxx",
    "created_at": "2026-01-01T00:00:00Z"
  }
}

错误码

状态码	说明
400	参数缺失或 key 格式不合法
401	未认证
403	无项目写入权限
409	key 名称已存在（唯一性约束冲突）
500	服务器内部错误

---

3. 更新项目密钥

PUT /projects/:projectId/secrets/:id

更新已有密钥的值或描述。

Path 参数

参数	类型	必填	说明
projectId	string	是	项目 ID
id	string	是	密钥记录 ID

Body 参数（JSON）

参数	类型	必填	说明
value	string	否	新的密钥值
description	string	否	新的描述

至少提供 value 或 description 之一。

响应 200

{
  "success": true,
  "data": {
    "id": "uuid",
    "key": "OPENAI_API_KEY",
    "description": "更新后的描述",
    "masked_value": "sk-****yyyy",
    "updated_at": "2026-01-02T00:00:00Z"
  }
}

错误码

状态码	说明
400	未提供任何更新字段
401	未认证
403	无项目写入权限
500	服务器内部错误

---

4. 删除项目密钥

DELETE /projects/:projectId/secrets/:id

删除指定的项目密钥。

Path 参数

参数	类型	必填	说明
projectId	string	是	项目 ID
id	string	是	密钥记录 ID

响应 200

{
  "success": true
}

错误码

状态码	说明
401	未认证
403	无项目写入权限
500	服务器内部错误

---

5. 列出密钥名称

GET /projects/:projectId/secret-keys

列出合并后的密钥名称列表（项目级 + 团队级），用于编辑器 mention 自动补全。

Path 参数

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

响应 200

{
  "success": true,
  "data": ["OPENAI_API_KEY", "GITHUB_TOKEN", "DATABASE_URL"]
}

错误码

状态码	说明
401	未认证
403	无项目读取权限
500	服务器内部错误

---

源码

• 路由：apps/backend/src/routes/project-secrets.ts
• 服务：apps/backend/src/services/project-secrets.ts
• 参考文档：密钥管理（内部文档 docs/CLAUDE/secrets.md）

补充端点

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

GET /projects/:projectId/secret-audit-logs

密钥审计日志

认证：JWT Bearer Token；读取明文值和写入系统密钥需要项目或团队管理员权限。 路径参数

参数	说明
projectId	项目 ID

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

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

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

---

GET /projects/:projectId/secrets/:id/value

读取密钥明文值，响应应只在受信任界面短暂展示。

认证：JWT Bearer Token；读取明文值和写入系统密钥需要项目或团队管理员权限。 路径参数

参数	说明
projectId	项目 ID
id	资源 ID

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

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

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

---

PUT /projects/:projectId/secrets/system/:key

更新系统密钥

认证：JWT Bearer Token；读取明文值和写入系统密钥需要项目或团队管理员权限。 路径参数

参数	说明
projectId	项目 ID
key	密钥 key

请求：请求体为 JSON，表示该资源的目标配置或完整更新内容。

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

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