项目密钥 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）