69 lines
3.6 KiB
Markdown
69 lines
3.6 KiB
Markdown
# 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)
|