docs: accept default HTTP and HTTPS client access (#237)

ila
2026-09-07 17:27:17 +08:00
parent 17e346d6e9
commit 36f6f6081f
+4 -4
@@ -862,11 +862,11 @@ Agent 携带既有 Token(可已失效)及恢复码重新调用注册接口
## 客户端 API 与管理员密钥管理(#237)
实现基线 `57b0f15`;以下接口已通过隔离测试,尚未完成真实迁移/部署联调。Android 接口不变。
实现基线 `71f7751`;以下接口已通过隔离测试,尚未完成真实迁移/部署联调。Android 接口不变。
### 管理接口
前缀 `/api/admin/v1/client-keys`,要求 Admin JWT、admin 角色及 HTTPS,响应 `Cache-Control: no-store`。
前缀 `/api/admin/v1/client-keys`,要求 Admin JWT 和 admin 角色,默认接受 HTTP/HTTPS,响应 `Cache-Control: no-store`。
| 方法与相对路径 | 输入 | 成功 data |
|---|---|---|
@@ -881,8 +881,8 @@ Agent 携带既有 Token(可已失效)及恢复码重新调用注册接口
### 客户端访问与错误语义
- 前缀 `/api/client/v1`,只接受 `Authorization: Bearer <客户端密钥>`,不接受 Cookie 或 URL 凭据,不与 JWT、Device Token 通用。
- 所有环境均要求 TLS;仅在 `GOAUTO_TRUST_FORWARDED_PROTO=true` 且实际 TCP 对端为 loopback 时接受反向代理设置的 `X-Forwarded-Proto: https`。Agent HTTP 例外不适用。
- HTTP 426 表示未使用 HTTPS;401 为缺失、无效或停用密钥;403 为模块/动作未授权;400 为查询参数携带凭据;503 为认证或审计暂不可用。业务错误沿用各既有接口。
- 根据用户 2026-09-07 的明确确认,管理与客户端接口在所有环境默认接受 HTTP/HTTPS,不设置协议开关,也不依赖 X-Forwarded-Proto 或 GOAUTO_TRUST_FORWARDED_PROTO。HTTP 明文传输密钥及业务数据,优先使用 HTTPS;不影响其他接口各自的协议要求。
- 不再因 HTTP 返回 426;401 为缺失、无效或停用密钥;403 为模块/动作未授权;400 为查询参数携带凭据;503 为认证或审计暂不可用。业务错误沿用各既有接口。
- 一般请求体最大 16 MiB;响应只支持有限 JSON(32 MiB),递归过滤凭据与原始载荷字段。不支持直接流式/二进制文件接口。响应不可序列化或超限时返回 502;业务可能已执行,必须先核对结果,不要自动重试。
- 通过密钥认证的请求由服务端生成 `X-Client-Request-Id` 关联审计;它不是业务幂等键,原业务接口要求的 requestId 等字段仍须提供。允许请求必须先落审计意图;完成状态更新失败可留下 status=0。无效密钥没有 key_id 关联审计;拒绝授权的 403 审计为尽力记录。
- GET `/ai-matching-settings` 只返回 `data.enabled`。POST `/ai-matching-settings/resolve` 接受 targetColor、targetSize、colors、sizes;每组最多 200 项,每个值最多 255 字符,总请求最大 64 KiB;确定性优先,必要时使用当前 Provider,返回 mappedColor、mappedSize、source;不保存映射、不创建任务,无法可靠匹配返回 422 安全提示。