pham/tokens-reef
2
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
main
tokens-reef/review_tmp/sub2api-launch-readiness-review-2026-05-08.md
pham 0e057904e6
Some checks failed
CI / test (push) Has been cancelled
Details
CI / golangci-lint (push) Has been cancelled
Details
Security Scan / backend-security (push) Has been cancelled
Details
Security Scan / frontend-security (push) Has been cancelled
Details
refactor: 彻底移除 Sora 视频生成模块（全栈清理） 
## 后端变更
- 删除 21 个 sora_*.go 服务文件（service/handler/repository/routes）
- 删除 Sora 相关 migration 文件（046/047/063/090）
- 清理 config 中的 sora_* 配置项和平台常量
- 清理 wire 依赖注入中的 Sora 组件
- 修复 wire_gen.go 语法错误（缺少逗号和闭合括号）
- 移除 go.mod 中的 go-sora2api 依赖
- 更新 ent schema usage_log.go 注释

## 前端变更
- 删除 SoraView、SoraAdminView 及 8 个 Sora 子组件
- 删除 sora API 层和路由配置
- 清理 UserEditModal 中的 Sora 存储配额 UI
- 清理 types/index.ts 中 Sora 相关类型定义
- 清理 stores/app.ts 默认配置
- 清理 i18n 翻译文件 en.ts/zh.ts (~110 行)
- 更新相关测试文件

## 文档更新
- README.md / README_CN.md / README_JA.md: 移除 Sora 状态说明和配置段落
- PROJECT_DIFF.md: 移除 Sora 相关差异描述

## 验证结果
- ✅ Go 编译通过 (go build ./...)
- ✅ TypeScript 类型检查通过 (vue-tsc --noEmit)
- ✅ 后端测试全通过 (0 failures)
- ✅ 前端测试全通过 (59 files, 329 tests, 0 failures)
- ✅ 前端生产构建成功 (23.81s)
2026-05-10 14:15:45 +08:00

250 lines
11 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Sub2API 全面上线评审报告
> **评审日期**: 2026-05-08
> **评审范围**: sub2api-merge 项目（Go + Vue3 + PostgreSQL + Redis）
> **评审目标**: 判定项目是否具备上线条件，核心 AI 模型是否正常支持
---
## 执行摘要
| 维度 | 评分 | 状态 |
|------|------|------|
| 核心模型支持 | ★★★★★ | 全部主流模型链路完整 |
| 构建稳定性 | ★★★★★ | 前后端构建均成功 |
| 测试质量 | ★★★★★ | 后端单元+集成全通过，前端 364 测试全通过 |
| 代码质量 | ★★★★☆ | 架构清晰，有少量残留代码 |
| 文档一致性 | ★★★☆☆ | 版本号不一致，Sora 状态说明已到位 |
**综合判定: CONDITIONAL GO（有条件通过）**
项目在核心功能（AI 模型转发网关）上完全具备上线能力。唯一需要在上线前处理的是 **Sora 模块残留代码与已删除数据库表的不一致问题**。
---
## 一、模型支持矩阵（核心关切验证）
以下对每种 AI 模型的端到端转发链路进行了深度代码审查和架构验证：
| # | 模型/平台 | 网关端点 | 路由文件 | 账号类型 | 模型映射 | 计费支持 | 状态 |
|---|-----------|---------|---------|---------|---------|---------|------|
| 1 | **Claude (Anthropic)** | `/v1/messages` | `gateway.go:44` | OAuth / API Key / Setup Token / Bedrock | 默认+自定义映射 | ✅ 完整 | **🟢 正常** |
| 2 | **Claude (OpenAI group)** | `/v1/messages` | `gateway.go:44-50` | OpenAI OAuth | 自动路由到 OpenAIGateway | ✅ 完整 | **🟢 正常** |
| 3 | **OpenAI Chat Completions** | `/v1/chat/completions`, `/chat/completions` | `gateway.go:84-90`, `gateway.go:120-126` | OAuth / API Key | 透传+映射 | ✅ 完整 | **🟢 正常** |
| 4 | **OpenAI Responses** | `/v1/responses`, `/responses` | `gateway.go:68-81`, `gateway.go:109-118` | OAuth / API Key | 透传+映射 | ✅ 完整 | **🟢 正常** |
| 5 | **Gemini** | `/v1beta/models/*` | `gateway.go:94-106` | OAuth | 完整（2.5/3/3.1 系列） | ✅ 完整 | **🟢 正常** |
| 6 | **Antigravity Claude** | `/antigravity/v1/messages` | `gateway.go:141-145` | OAuth | `DefaultAntigravityModelMapping` | ✅ 完整 | **🟢 正常** |
| 7 | **Antigravity Gemini** | `/antigravity/v1beta/*` | `gateway.go:147-159` | OAuth | `DefaultAntigravityModelMapping` | ✅ 完整 | **🟢 正常** |
| 8 | **Codex** | `gpt-5.1-codex`, `gpt-5.3-codex` | `billing_service.go:252-272` | OpenAI OAuth | `codex_cli_only` 模式 | ✅ 专用探测+计费 | **🟢 正常** |
| 9 | **Bedrock** | `/v1/messages` | `account.go:827` | SigV4 / API Key | `DefaultBedrockModelMapping`（区域自适应） | ✅ 完整 | **🟢 正常** |
| 10 | **Sora** | — | — | — | — | — | **🔴 不可用** |
### 关键发现
1. **自动路由逻辑完善**：`gateway.go` 中 `/v1/messages`、`/v1/responses`、`/v1/chat/completions` 均实现了根据 `getGroupPlatform()` 自动路由到对应 handler（Anthropic vs OpenAI）的逻辑，确保同一 API Key 在不同 group 下正确转发。
2. **Antigravity 隔离正确**：`/antigravity/*` 路由使用 `ForcePlatform(PlatformAntigravity)` 中间件强制锁定账号平台，不会与其他平台混合调度。
3. **Codex 支持完善**：`billing_service.go` 中已为 `gpt-5.1-codex`、`gpt-5.3-codex`、`gpt-5.1-codex-max`、`gpt-5.1-codex-mini`、`codex-mini-latest` 等模型配置计费；`account_usage_service.go` 实现了 Codex 专用用量探测和 rate limit 监控。
4. **模型映射覆盖全面**：`domain/constants.go` 中的 `DefaultAntigravityModelMapping` 和 `DefaultBedrockModelMapping` 覆盖了当前主流模型版本（Claude Opus/Sonnet/Haiku 4-5/4-6 系列，Gemini 2.5/3/3.1 系列）。
---
## 二、构建与测试验证（实际执行）
### 2.1 后端
| 验证项 | 命令 | 结果 | 耗时 |
|--------|------|------|------|
| 编译构建 | `go build -tags embed -o sub2api ./cmd/server` | ✅ 成功 | ~30s |
| 单元测试 | `go test -tags=unit ./...` | ✅ 全部通过 | ~86s |
| 集成测试 | `go test -tags=integration ./...` | ✅ 全部通过 | ~36s |
| golangci-lint | `golangci-lint run ./...` | ⚠️ 未安装（环境限制） | — |
**测试通过详情**：
- `internal/handler` ✅（含 admin handler）
- `internal/handler/admin` ✅（含 Sora handler 测试）
- `internal/prommetrics` ✅（12 个测试用例全部通过）
- `internal/service` ✅（含 ops 16 个测试文件全部通过）
- `internal/server/routes` ✅（含健康检查端点测试）
- `internal/pkg/*` ✅（antigravity、gemini、openai 等）
### 2.2 前端
| 验证项 | 命令 | 结果 | 说明 |
|--------|------|------|------|
| 依赖安装 | `pnpm install --frozen-lockfile` | ⚠️ 部分失败 | npmmirror 网络问题（环境限制） |
| 构建 | `pnpm run build` | ✅ 成功 | ~29s，产出在 `backend/internal/web/dist/` |
| vitest 测试 | `pnpm test --run` | ✅ 全部通过 | 62 文件 / 364 测试 / 0 失败 |
**构建产物确认**：新增模块均正常编译：
- `OpsDashboard-BPDgd74J.js` (235KB gzip: 51KB) ✅
- `SoraView-DYa5Tfy5.js` (33KB gzip: 11KB) ✅
- `DataManagementView` ✅
---
## 三、新增模块代码质量评估
| 模块 | 文件数 | 测试文件数 | 测试通过率 | 质量评分 | 备注 |
|------|--------|-----------|-----------|---------|------|
| `prommetrics/` | 2 | 1 | 12/12 ✅ | ★★★★★ | 独立包，无循环依赖 |
| `service/ops_*.go` | 52 | 16 | 全部通过 ✅ | ★★★★☆ | 功能完善，告警/聚合/清理全覆盖 |
| `service/sora_*.go` | 21 | 0（sora 表已删除） | — | 🔴 风险 | 见下方阻塞问题 #1 |
| `handler/admin/ops_*.go` | 8 | 部分 | — | ★★★★☆ | 路由注册完整 |
| `handler/admin/sora_*.go` | 1 | 1 | 通过 ✅ | — | 依赖已删除的表 |
| `repository/ops_repo*.go` | 9 | 0 | — | ★★★☆☆ | 建议补充单元测试 |
| `frontend/views/admin/ops/` | 19 | 3 | — | ★★★★☆ | 组件化良好 |
---
## 四、阻塞问题清单
### 🔴 阻塞级 #1：Sora 模块代码残留与数据库状态不一致
**问题描述**：
- 数据库迁移 `090_drop_sora.sql` 已删除所有 Sora 表（sora_tasks、sora_generations、sora_accounts）及相关字段
- 但后端仍保留 21 个 `sora_*.go` service 文件、Sora admin handler、前端 SoraView 页面
- Admin 路由 `/admin/sora` 仍在 `admin.go:97-101` 注册
- 访问该路由将导致数据库查询失败（表不存在）
**影响**：管理员访问 Sora 管理页面时会遇到 500 错误
**修复方案**（二选一）：
1. **方案 A（推荐）**：在 `admin.go` 中注释掉 Sora 路由注册，待 Sora 功能恢复后重新启用
2. **方案 B**：回滚 `090_drop_sora.sql` 迁移，恢复 Sora 数据库表
### 🟡 中风险 #2：文档 Go 版本不一致
**问题描述**：
- `README.md`、`DEV_GUIDE.md` 写需要 Go 1.25.7
- 实际 `go.mod` 为 `go 1.26.2`
- CI 配置 `backend-ci.yml` 也校验 `go1.26.2`
**影响**：误导新开发者，可能导致本地环境配置错误
**修复方案**：将 README/DEV_GUIDE 中的 Go 版本统一更新为 1.26.2
### 🟡 中风险 #3：前端 Chunk 体积过大
**问题描述**：
- `AccountsView-kd8fcLKO.js` 544KB（超过 500KB 警告线）
- `vendor-ui-BHFCCYkz.js` 430KB
**影响**：首次加载 Admin 面板时可能出现明显延迟
**修复方案**：使用动态 import 拆分 AccountsView 等超大 chunk
### 🟢 低风险 #4：README 中 Sora 状态声明
**问题描述**：README.md 第 434 行已声明 "Sora-related features are temporarily unavailable"，但项目中 Sora 代码仍大量存在。
**影响**：认知不一致，开发者可能误以为 Sora 可用
---
## 五、安全审计
| 检查项 | 状态 | 说明 |
|--------|------|------|
| SQL 注入（ORDER BY） | ✅ 安全 | 白名单校验模式 |
| SQL 注入（CREATE DATABASE） | ⚠️ 需注意 | 有前置校验，建议加引号包裹 |
| JWT Secret 管理 | ✅ 已完善 | 有轮换告警机制 |
| URL Allowlist | ✅ 配置完善 | 支持 CORS、私网地址控制 |
| 密码复杂度 | ⚠️ 不一致 | 各模块要求不统一 |
| 响应头过滤 | ✅ 可配置 | `security.response_headers.enabled` |
---
## 六、CI/CD 评估
| Workflow | 存在 | 配置 | 评价 |
|----------|------|------|------|
| `backend-ci.yml` | ✅ | 单元测试 + 集成测试 + golangci-lint v2.9 | 完善 |
| `security-scan.yml` | ✅ | govulncheck + gosec + pnpm audit | 完善 |
| `release.yml` | ✅ | tag `v*` 触发构建 | 完善 |
---
## 七、数据库迁移评估
- 总迁移文件数：122 个 SQL 文件
- 最新迁移：`102_add_out_trade_no_to_payment_orders.sql`
- Ops 相关迁移：完整（026、033、034、036、037、038、039、042b、054、079）
- Sora 迁移：`046_add_sora_accounts.sql`、`047_add_sora_pricing_and_media_type.sql`、`063_add_sora_client_tables.sql` → **已被 090_drop_sora.sql 删除**
**风险**：Sora 相关代码依赖的表已被删除，但代码未清理。
---
## 八、上线建议
### 立即执行（上线前必做）
1. **禁用 Sora Admin 路由**（`backend/internal/server/routes/admin.go:97-101`）
```go
// 暂时注释掉 Sora 路由，避免访问已删除的表
// sora := admin.Group("/sora")
// sora.GET("/stats", h.Admin.Sora.GetSystemStats)
// ...
```
2. **同步文档版本号**
- 更新 `README.md` 中的 Go 版本徽章
- 更新 `DEV_GUIDE.md` 中的 Go 版本说明
### 近期执行（上线后 1-2 周）
3. **清理 Sora 残留代码**
- 决定：彻底移除 Sora 代码，还是恢复数据库表支持
- 如果移除：删除 `service/sora_*.go`、`handler/admin/sora_*.go`、`frontend/src/views/admin/SoraAdminView.vue`
4. **前端代码分割优化**
- 对 AccountsView、OpsDashboard 等大 chunk 使用 `defineAsyncComponent` 懒加载
5. **统一密码复杂度要求**
- 检查各 handler 中的密码验证逻辑，统一最小长度和字符要求
### 持续监控
6. **部署后验证各模型连通性**
- Claude `/v1/messages`
- Gemini `/v1beta/models`
- OpenAI `/v1/chat/completions`
- Codex 用量探测是否正常
7. **观察新增 Ops 监控性能**
- 数据聚合任务对数据库负载的影响
- Prometheus 指标端点 `/metrics` 的响应时间
---
## 九、最终判定
| 检查项 | 结果 |
|--------|------|
| 核心模型支持 | ✅ 完整（除 Sora） |
| 构建成功 | ✅ 前后端均通过 |
| 测试通过 | ✅ 单元+集成全部通过 |
| 新增模块质量 | ✅ 代码结构良好，有配套测试 |
| 数据库迁移 | ⚠️ Sora 表已删但代码残留 |
| 安全审计 | ✅ 无高风险漏洞 |
| CI/CD 配置 | ✅ 完整 |
**最终结论：CONDITIONAL GO（有条件通过）**
项目在核心 AI 模型网关功能上完全具备上线能力。唯一阻碍上线的因素是 Sora 模块的残留代码可能触发数据库错误。建议在上线前执行以下最小改动：
> **最小改动清单**：
> 1. 注释掉 `backend/internal/server/routes/admin.go` 中的 Sora 路由组（4 行代码）
> 2. 更新 README/DEV_GUIDE 中的 Go 版本说明
> 3. 重新构建验证
> 4. 即可上线
---
*报告生成时间: 2026-05-08 15:30*
*评审执行人: 齐活林 (Qi) - 交付总监*
*协作团队: 高见远 (架构师), 严过关 (QA 工程师)*
Reference in New Issue View Git Blame Copy Permalink