8.0 KiB
8.0 KiB
Relaykit 迁移方案执行摘要
文档版本：v1.0
生成日期：2026-07-28
完整方案：relaykit-migration-plan.md状态（2026-07-29 更新）：✅ 代码完成 + 切换已落地（阶段 0–7）。特性开关已移除、relaykit 常开、旧转换器作容错回退保留；DTO 去重完成。本文下方「建议批准执行 / 75 天计划」为立项时历史内容，实际执行状态以
relaykit-migration-plan.md阶段 7「最终执行状态」为准。
一、项目背景
当前问题
team-api 的 relay/ 模块（26,138 行代码）存在以下痛点：
- 转换逻辑分散：24 个供应商的协议转换代码散落在各自的
channel/目录，大量重复代码 - 难以测试：转换函数缺乏独立测试，依赖完整的 HTTP 链路
- 维护成本高：新增供应商需要 5 天开发时间，协议变更适配需要 2-3 天
- 无法复用：转换逻辑与 GoFrame/Gin 框架耦合，无法在其他项目中使用
解决方案
参考 new-api 项目的 relaykit 模块化架构，将协议转换逻辑提取为独立的 Go 模块：
- 零依赖：不依赖任何框架，纯粹的协议转换库
- 高可测试：Golden 测试保证字节级精确性
- 易扩展：注册表模式，新增供应商只需实现接口
- 可复用：可以开源或在其他项目中使用
二、核心架构
Relaykit 模块结构
relaykit/
├── types/ # 核心类型定义（RelayFormat、EndpointType）
├── relayconvert/ # 协议转换核心
│ ├── convmeta/ # Meta 接口（宿主信息契约）
│ ├── internal/ # 转换器实现
│ │ ├── oai_chat/ # OpenAI Chat Completions 转换器
│ │ ├── claude_messages/ # Claude Messages API 转换器
│ │ ├── gemini_chat/ # Gemini generateContent 转换器
│ │ └── oai_responses/ # OpenAI Responses API 转换器
│ ├── request_registry.go # 请求转换器注册表
│ ├── response_registry.go # 响应转换器注册表
│ └── text_converter_registry.go # 文本转换器注册表（统一接口）
└── dto/ # 数据传输对象（兼容层）
关键设计
- Meta 接口：宿主应用（team-api）实现该接口，转换器通过它访问渠道信息、模型名称等
- Options 快照：请求级配置快照，避免并发读取配置时的竞态条件
- 注册表模式：转换器通过注册表管理，支持运行时查找和多跳转换
- StreamState 接口：有状态的流式转换（如 Gemini → OpenAI 需要累积 tool_use）
- Golden 测试：每个转换器都有 testdata/ 目录存储预期输出，测试时逐字节对比
三、迁移策略
核心原则
- 零停机：双轨并行，功能开关控制，随时可回滚
- 降低风险：分 7 个阶段渐进式迁移，每个阶段独立验收
- 质量保证：测试覆盖率 ≥ 85%，Golden 测试通过率 100%
7 个阶段
| 阶段 | 工作内容 | 预计时间 | 交付物 |
|---|---|---|---|
| 0 | 准备工作 | 3 天 | 功能开关 + 监控配置 + 测试基线 |
| 1 | relaykit 模块骨架 | 5 天 | 类型定义 + Meta 接口 + 注册表 |
| 2 | DTO 迁移 | 5 天 | 类型别名（向后兼容） |
| 3 | 核心转换器实现 | 10 天 | OpenAI ↔ Claude ↔ Gemini + Golden 测试 |
| 4 | 集成到主项目 | 7 天 | RelayInfo 实现 Meta + Handler 调用 relaykit |
| 5 | 迁移其他供应商 | 24 天 | 24 个供应商全部迁移 |
| 6 | 测试与验证 | 14 天 | 单元测试 + 集成测试 + 压力测试 + 灰度验证 |
| 7 | 清理旧代码 | 7 天 | 删除旧转换函数 + 移除功能开关 + 文档更新 |
总计：75 天（11 周，约 2.5 个月）
四、关键里程碑
| 里程碑 | 日期 | 验收标准 |
|---|---|---|
| M1: relaykit 模块可用 | Day 13 | DTO + 核心转换器实现完成，测试通过 |
| M2: 首个供应商集成 | Day 30 | Anthropic 在生产环境使用 relaykit，成功率 ≥ 99.5% |
| M3: 核心供应商迁移完成 | Day 44 | Anthropic + OpenAI + Gemini + Qwen 迁移完成 |
| M4: 全部供应商迁移完成 | Day 54 | 24 个供应商全部使用 relaykit |
| M5: 测试验证完成 | Day 68 | 单元 + 集成 + 压力测试全部通过 |
| M6: 迁移完成 | Day 75 | 旧代码清理完毕，文档更新，项目交付 |
五、风险与回滚
高风险项
| 风险 | 缓解措施 |
|---|---|
| 转换逻辑错误导致请求失败 | Golden 测试 + 灰度验证 + 监控告警 + 自动回滚 |
| 性能回退导致服务不可用 | 基准测试 + 压力测试 + 流量控制 + P95 延迟阈值告警 |
| 边界情况未覆盖 | 多样化测试用例 + 生产流量回放 + 灰度分批放量 |
当前回滚方式\r\n\r\n阶段 7 已移除运行时功能开关。relaykit 在已覆盖方向上始终优先，转换器未匹配、解析失败或转换失败时由现有 bridge 回退到旧实现。若需要整体停用 relaykit，必须 revert 阶段 7 cutover 提交并重新构建部署，不能再通过修改配置并重启完成。
六、成功指标（KPI）
质量指标
- ✅ 单元测试覆盖率 ≥ 85%
- ✅ Golden 测试通过率 = 100%
- ✅ 转换成功率 ≥ 99.5%（生产环境 30 天滚动）
性能指标
- ✅ P50 转换延迟 < 0.5ms
- ✅ P95 转换延迟 < 1ms
- ✅ P99 端到端延迟增加 < 20ms
可维护性指标
- ✅ 代码行数减少 ≥ 20%（长期）
- ✅ 新增供应商开发时间 < 3 天（原 5 天）
- ✅ 协议变更适配时间 < 1 天（原 2-3 天）
七、资源需求
人力投入
| 角色 | 人数 | 投入时间 |
|---|---|---|
| 后端开发（Go） | 2 人 | 全职 11 周 |
| 测试工程师 | 1 人 | 全职 4 周 |
| 架构师/Tech Lead | 1 人 | 兼职 20%（Code Review + 架构审查） |
| 运维工程师 | 1 人 | 兼职 10%（监控 + 灰度发布） |
基础设施
- 测试环境：与现有环境共用
- 监控系统：扩展现有 Prometheus/Grafana
- CI/CD：扩展现有 Jenkins/GitLab CI
八、预期收益
短期收益（迁移完成后 3 个月内）
- 代码量减少 20%：从 26,138 行降至约 21,000 行
- 测试覆盖率提升：从 < 50% 提升至 85%+
- 转换逻辑集中：24 个供应商的转换代码统一管理
中期收益（6 个月内）
- 开发效率提升 60%：新增供应商从 5 天降至 2 天
- 维护成本降低 80%：协议变更适配从 2-3 天降至 < 1 天
- 质量稳定性提升：Golden 测试防止转换回归
长期收益（1 年内）
- 可复用性：relaykit 可开源或在其他项目中使用
- 社区贡献：接受社区贡献新的供应商适配器
- 技术影响力：作为 AI 协议转换标准库推广
九、决策建议
建议批准执行
理由：
- ✅ 风险可控：分阶段迁移 + 双轨并行 + 功能开关 + < 5 分钟回滚
- ✅ 收益显著：开发效率提升 60%，维护成本降低 80%
- ✅ 方案完善：7 个阶段 + 75 天时间线 + 详细回滚方案 + KPI 指标
- ✅ 长期价值：零依赖独立模块，可开源复用
关键成功因素
- 严格执行 Golden 测试：每个转换器必须有 3+ 个测试用例
- 监控先行：灰度验证前必须配置好成功率和延迟监控
- 及时回滚决策：成功率 < 99.5% 或 P95 延迟增加 > 50ms 立即回滚
- 充分的测试时间：阶段 6 预留 14 天进行全面测试，不压缩
十、附录
相关文档
- 完整迁移方案（2645 行，93 个主章节）
参考项目
- new-api/relaykit：D:\github\new-api\relaykit\（11,264 行，架构参考）
- team-api/relay：D:\github\team-api\relay\（26,138 行，迁移对象）