From 36f6f6081f0cfdfd8a4a395a27eaef0a6cd88cda Mon Sep 17 00:00:00 2001 From: ila <2+ila@noreply.git.ilapage.cn> Date: Mon, 7 Sep 2026 17:27:17 +0800 Subject: [PATCH] docs: accept default HTTP and HTTPS client access (#237) --- Android-Agent-API-Contract.-.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Android-Agent-API-Contract.-.md b/Android-Agent-API-Contract.-.md index ec906d0..c28da71 100644 --- a/Android-Agent-API-Contract.-.md +++ b/Android-Agent-API-Contract.-.md @@ -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 安全提示。