From 557c99686542da4f45cb42be29bd8026e933fc8e Mon Sep 17 00:00:00 2001 From: chengma Date: Fri, 14 Aug 2026 11:16:25 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=BD=92=E6=A1=A3=E4=BB=BB=E5=8A=A1=20?= =?UTF-8?q?#223?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../task/223-Admin-AI服务商BaseURL兼容HTTP.md | 64 +++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 docs/task/223-Admin-AI服务商BaseURL兼容HTTP.md diff --git a/docs/task/223-Admin-AI服务商BaseURL兼容HTTP.md b/docs/task/223-Admin-AI服务商BaseURL兼容HTTP.md new file mode 100644 index 0000000..182e81e --- /dev/null +++ b/docs/task/223-Admin-AI服务商BaseURL兼容HTTP.md @@ -0,0 +1,64 @@ +# 223 Admin：AI 服务商 Base URL 兼容 HTTP + +- 类型：需求 +- 父级大工单：#14 +- 所属 MVP / 版本：#199 / AI规格批量匹配 +- 状态：已完成，待用户验收 +- 日期：2026-08-14 +- Gitea 工单：http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/223 + +## 背景与目标 + +AI 服务商 Base URL 原来只接受 HTTPS，无法接入仅提供 HTTP 的 OpenAI 兼容服务。 +本任务按用户确认的范围同时支持 HTTP 和 HTTPS，不增加协议开关、允许列表字段或其他配置项， +并保留现有外部地址安全校验。 + +## 最终方案 + +`AIEndpointPolicy.ValidateSyntax` 现在明确只接受 `http` 和 `https` 两种协议，并把协议名规范 +为小写。两种协议共用原有的 URL 凭据、查询参数、片段、私网、回环、链路本地、元数据、 +DNS 解析、实际拨号和重定向校验。现有部署级 `allowed_hosts` 仍是私有模型端点的唯一例外， +没有新增 HTTP 专用配置。 + +自动化测试除语法规则外，还启动本机临时 HTTP 服务，通过现有测试级允许列表完成一次最小 +OpenAI 兼容连接请求，验证安全 HTTP 客户端能够实际使用 HTTP。HTTPS 原有行为继续保留。 + +配置页保持现有表单结构和可见标签，只把新增示例改为 HTTP，并增加持续可见的说明：HTTP 会 +明文传输 API Key 和匹配请求，只应在可信网络使用。该提示遵循 `ui-ux-pro-max` 的表单帮助 +文字建议，没有增加额外确认步骤。 + +## 改了哪些 + +- `admin/service/ai_config.go`：允许 HTTP/HTTPS 并拒绝其他协议。 +- `admin/service/ai_config_test.go`：增加双协议、危险地址、现有允许列表和真实临时 HTTP 服务测试。 +- `admin/templates/ai/list.html`：更新 Base URL 示例并显示 HTTP 明文传输说明。 +- `admin/config.example.yaml`：更新现有 AI 端点配置注释，不增加字段。 +- `docs/admin/02-architecture.md`：同步双协议和安全边界。 +- `docs/admin/03-data-model.md`：把 Base URL 口径更新为 HTTP/HTTPS。 +- `docs/admin/06-quality-security.md`：记录 HTTP 明文传输风险。 + +## 验收结果 + +| 验收标准 | 结果 | +|---|---| +| 合法 HTTP 地址可以保存并由安全客户端调用 | 通过 | +| 现有 HTTPS 行为保持不变 | 通过 | +| HTTP/HTTPS 都拒绝 URL 凭据、查询参数和片段 | 通过 | +| HTTP 不绕过私网、回环、元数据和现有网络校验 | 通过 | +| 不增加配置项，不修改 schema 和密钥存储 | 通过 | +| 固定 Go 1.23.0 的 build、test、vet | 通过 | + +## 测试 + +- 执行的命令： + - `$env:GOTOOLCHAIN='go1.23.0'; go test ./service -run 'TestAIEndpointPolicy|TestSafeAIHTTPClient|TestCallAIHealthCheck' -count=1` + - `$env:GOTOOLCHAIN='go1.23.0'; go build ./...; go test ./... -count=1; go vet ./...` + - `$env:GOTOOLCHAIN='go1.23.0'; go test ./handler/web ./service -count=1` + - `git diff --check` +- 结果：定向回归、固定 Go 1.23.0 全量构建、测试、vet 和模板相关测试全部通过。 +- **没验证到的部分**：未连接真实 HTTP AI 服务商，未使用真实 API Key；未部署生产 Admin， + 未在 1366×768 浏览器中人工检查提示文字。 + +## 相关提交 + +- `1e0b7ad` feat: AI 服务商接口兼容 HTTP (#223)