cmautobuy/docs/task/223-Admin-AI服务商BaseURL兼容HTTP.md

223 Admin：AI 服务商 Base URL 兼容 HTTP

• 类型：需求
• 父级大工单：#14
• 所属 MVP / 版本：#199 / AI规格批量匹配
• 状态：已完成，待用户验收
• 日期：2026-08-14
• Gitea 工单：#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)