docs: 归档任务 #223

2026-08-14 11:16:25 +08:00
parent 1e0b7ad6e1
commit 557c996865
1 changed files with 64 additions and 0 deletions
@@ -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)