S3 兼容访问密钥（S3CredentialController）¶

提供 KMS 知识管理模块「S3 凭证域」的自助签发能力：已登录 KMS 的用户可创建 / 列出 / 吊销 S3 兼容访问密钥（AccessKey / SecretAccessKey），用于通过 s3-api.md 数据面（SigV4）访问网盘。所有端点均返回 JSON 资源。

接口类型：REST 资源（@RestController，类级与所有方法级 produces = MediaType.APPLICATION_JSON_VALUE）
基址：${myapps.context-path.kms:}/api/kms/s3-credentials（类级 @RequestMapping 仅声明单一前缀，无 /kms 备用前缀）
Tag：kms S3 凭证模块

公共说明¶

鉴权（据源码 KmsMvcConfig + KmsSecurityFilter）：KmsMvcConfig 注册全局 Servlet 过滤器 KmsSecurityFilter（URL 模式 /*，context-path 为 / 时为 /kms/*）。本控制器路径 /api/kms/s3-credentials、/api/kms/s3-credentials/{id} 不在 KmsSecurityFilter.isExcludeURI 的豁免名单内，亦不匹配 S3 数据面前缀（/s3、/kms/s3）。过滤器调用 Security.getUserIdFromToken(request)，取不到用户则返回 HTTP 401。因此所有端点均需 accessToken，可通过以下任一方式传递（据 Security.getUserIdFromToken）：query 参数 accessToken、query 参数 access_token（移动端）、请求头 accessToken、Cookie accessToken、请求头 Authorization: Bearer <token>。完整鉴权机制见 index.md「鉴权说明」。
执行用户：控制器内 getUser()（继承自 AbstractBaseController）调用 Security.getUserIdFromToken(request) 还原当前用户 id，再经 Feign（UserAPI.getUserById）装载 KmsUser。无 userCode 参数。
响应结构：统一 Resource（见 ../index.md「统一响应结构」），字段为 errcode/errmsg/data/errors。KMS 的 Resource 为 AbstractBaseController 内部类，其构造器对 data 执行 ESAPI.encode(data) 做 XSS 编码。
HTTP 状态码与错误码：成功默认 HTTP 200；UnauthorizedException → HTTP 403 / errcode=403；其他 Exception → HTTP 500 / errcode=500。
Secret 安全：create 端点返回的 secretAccessKey 仅在创建时返回一次（服务端以 S3SecretCrypto 加密入库），后续 list 不再返回；遗失需吊销后重新创建。
路径变量：id 为 S3 凭证主键（凭证 Id），非 AccessKey 字符串。

1. 创建 S3 兼容访问密钥¶

为当前用户签发一对新的 AccessKey / SecretAccessKey，并加密入库。SecretAccessKey 仅在此响应中返回一次。

接口类型：REST 资源
请求方式：POST
请求路径：/api/kms/s3-credentials（完整：{kms-context}/api/kms/s3-credentials）
鉴权：是（需 accessToken，据源码）
Tag：kms S3 凭证模块

请求参数¶

参数名	位置	类型	必填	说明
body	body	object	否	JSON 对象，可含 `remark`（备注）；整个 body 可省略

请求体¶

{ "remark": "rclone 挂载用" }

请求示例¶

POST /api/kms/s3-credentials?accessToken=__TOKEN__ HTTP/1.1
Content-Type: application/json

{ "remark": "rclone 挂载用" }

响应¶

结构：统一 Resource（见 ../index.md「统一响应结构」）。 data：Map，字段含 id（凭证 Id）、accessKey（AccessKey 字符串）、secretAccessKey（SecretAccessKey 明文，仅显示一次）、message（提示语）。

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": {
    "id": "__CREDID__",
    "accessKey": "AKxxxxxxxxxxxxxxxxxx",
    "secretAccessKey": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "message": "secretAccessKey 仅显示一次，请妥善保存"
  },
  "errors": null
}

2. 列出我的 S3 兼容访问密钥（不含 Secret）¶

返回当前用户名下的全部 S3 凭证（不含 SecretAccessKey，仅元数据）。

接口类型：REST 资源
请求方式：GET
请求路径：/api/kms/s3-credentials（完整：{kms-context}/api/kms/s3-credentials）
鉴权：是（需 accessToken，据源码）
Tag：kms S3 凭证模块

请求参数¶

无。

请求示例¶

GET /api/kms/s3-credentials?accessToken=__TOKEN__ HTTP/1.1

响应¶

结构：统一 Resource。 data：List<Map>，每项字段含 id、accessKey、active（是否启用）、remark（备注）、createDate（创建时间）。

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": [
    {
      "id": "__CREDID__",
      "accessKey": "AKxxxxxxxxxxxxxxxxxx",
      "active": true,
      "remark": "rclone 挂载用",
      "createDate": "2026-08-05 10:00:00"
    }
  ],
  "errors": null
}

3. 吊销 S3 兼容访问密钥¶

按凭证 Id 吊销（删除）当前用户名下的某个 S3 凭证。仅能吊销本人的凭证。

接口类型：REST 资源
请求方式：DELETE
请求路径：/api/kms/s3-credentials/{id}（完整：{kms-context}/api/kms/s3-credentials/{id}）
鉴权：是（需 accessToken，据源码）
Tag：kms S3 凭证模块

请求参数¶

参数名	位置	类型	必填	说明
id	path	string	是	凭证Id

请求示例¶

DELETE /api/kms/s3-credentials/__CREDID__?accessToken=__TOKEN__ HTTP/1.1

响应¶

结构：统一 Resource。 data：boolean，固定为 true（吊销由 credentialService.revoke(id, user.getId()) 完成，过程中抛出的异常由全局处理器映射）。