# 200 Admin：增加管理员 AI 服务商与模型配置

- 类型：需求
- 父级大工单：#14
- 所属 MVP / 版本：#199 / AI规格批量匹配
- 状态：已完成
- 日期：2026-08-14
- Gitea 工单：http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/200

## 背景与目标

AI 规格匹配需要在不重新发布 Admin 的情况下切换 OpenAI 兼容服务商和模型，同时确保
API Key 不进入数据库、`data/`、日志、页面响应、工单或文档。配置入口及全部写操作仅
允许管理员使用。

## 最终方案

- 使用 MySQL v20 保存服务商普通配置和非敏感操作审计；生成列唯一索引保证最多一个
  服务商处于启用状态。
- 增加 `AISecretStore`，把 API Key 写入部署指定的绝对路径。写入使用同目录临时文件、
  `fsync`、原子替换和 `600` 权限；页面只展示是否配置及尾四位掩码。
- 增加仅管理员可访问的服务端渲染配置页，支持新增、编辑、替换/清除密钥、连接测试和
  启停。普通配置或密钥变化后会停用并要求重新测试。
- 外部端点只允许 HTTPS；拒绝 URL 凭据、环回、链路本地、元数据和未允许的私网地址，
  并在 DNS 解析、实际拨号和重定向阶段重复校验。私有端点只能通过部署静态允许列表开放。
- 连接测试发送不含订单、店铺、用户和 Client 信息的最小请求，不保存完整响应。

## 改了哪些

- `admin/config.example.yaml`、`admin/config/config.go`：增加密钥路径和私有端点允许列表。
- `admin/model/model.go`、`admin/repository/ai_config.go`、`admin/repository/mysql_db.go`：
  增加 AI 配置、审计模型和 MySQL v20 迁移、自检。
- `admin/service/ai_secret.go`、`admin/service/ai_config.go`：实现密钥隔离、配置业务规则、
  连接测试和 SSRF 防护。
- `admin/handler/web/ai_config.go`、`admin/handler/web/web.go`、`admin/templates/ai/list.html`：
  增加管理员配置页面及全部操作。
- `admin/*_test.go`、`admin/service/*_test.go`、`admin/repository/mysql_db_integration_test.go`：
  增加权限、模板、密钥、端点安全和迁移测试。
- `docs/admin/`：同步需求、架构、数据模型、界面和安全基线。

## 验收结果

| 验收标准 | 结果 |
|---|---|
| 管理员可管理、测试和启停服务商，且最多一个启用项 | 通过（代码和自动化测试） |
| 采购员页面和全部写接口被服务端拒绝 | 通过 |
| API Key 不回显，只显示掩码尾号 | 通过 |
| 密钥不进入数据库、`data/`、日志和页面 | 通过（代码及假密钥测试） |
| 密钥原子写入且失败不破坏旧值 | 通过（单元测试）；生产 Linux 路径待部署验证 |
| 测试失败不切换当前配置，成功后可热启用 | 通过 |
| 不安全 URL 和未允许私网地址被拒绝 | 通过 |
| 审计仅记录操作者、时间和非敏感内容 | 通过 |
| MySQL 8.4 `_test` 迁移和自检 | 未验证：本机未启用隔离测试库 |
| 固定 Go 1.23.0 build、test、vet | 通过 |

## 测试

- 执行的命令：
  - `go test ./config ./service ./repository`
  - `go test . -run "Test(AI|MainPages)" -count=1`
  - `$env:GOTOOLCHAIN="go1.23.0"; go build ./...; go test ./... -count=1; go vet ./...`
- 结果：固定 Go 1.23.0 的构建、全量测试和静态检查全部通过。
- **没验证到的部分**：未连接 MySQL 8.4 `_test` 实库；未在生产 Linux 上验证
  `/etc/cmautobuy/ai-secrets.yaml` 的最终属主、权限和服务进程读写权限；未调用真实模型。

## 相关提交

- `018da3f` feat: 增加管理员 AI 模型配置 (#200)