diff --git a/api-relay-outsourcing-requirements-mvp.html b/api-relay-outsourcing-requirements-mvp.html new file mode 100644 index 00000000..27de7dd6 --- /dev/null +++ b/api-relay-outsourcing-requirements-mvp.html @@ -0,0 +1,992 @@ + + + + + + 企业级 API 中转站 MVP 外包需求与验收标准 + + + +
+
+ MVP Outsourcing Standard · v1.1 +

企业级 API 中转站 MVP 外包需求与验收标准

+

基于 QuantumNous/new-api 的 B2B API 中转站交付标准。核心目标是接通可用、稳定运行、可故障切换、可监控、可交接验收，而不是从零开发完整 SaaS 平台。

+
+
上游渠道商
3 家
+
预期用户规模
约 500 人
+
交付模式
配置 + 部署 + 验收
+
MVP 原则
先稳定可用
+
+
+ +
+ + +
+
+
+ 1 +
+

项目概述

+

先对齐“做什么 / 不做什么 / 以什么方式交付”，避免外包范围膨胀。

+
+
+
+

1.1 项目背景

+

本项目拟基于开源项目 New API 部署一个面向企业 B2B 客户的 API 中转站。甲方上游不直接对接原始模型厂商，而是对接已经完成模型解析和接口封装的渠道商。当前计划接入 3 家上游渠道商，由上游渠道商向甲方提供可调用 API。

+

本次外包目标不是从零开发一个完整 SaaS 平台，而是交付一个 MVP：接通可用、运行稳定、可监控、可故障切换、可支撑约 500 人规模的企业客户使用。

+
+
3
上游渠道商接入，均需可独立测试、启停、记录命中日志。
+
500
按约 500 人规模配置，不因用户或日志规模导致明显卡顿。
+
99.5%
试运行期核心 API 可用性目标，不包含客户参数错误和上游自身故障。
+
+ +

1.2 本次交付范围

+
    +
  1. 部署并配置一个可生产使用的 API 中转站，优先基于 New API 等成熟开源方案。
    2. +
  2. 接入 3 家上游渠道商 API，并支持统一的下游调用入口。
    3. +
  3. 提供企业 B2B 客户使用所需的账号、API Key、额度、调用统计、基础权限能力。
    4. +
  4. 基于 New API 已有能力配置上游故障识别、失败重试、手动切换、权重分流、自动禁用与恢复验证机制。
    5. +
  5. 完成日志、监控、告警、备份、部署文档、运维交接文档。
    6. +
  6. 支撑约 500 名用户规模的稳定运行，满足本文定义的性能和稳定性验收标准。
    7. +
+ +

1.3 明确不做范围

+
MVP 不做复杂平台化。 本次交付不开发完整自研 API 网关内核，不开发复杂 CRM、分销、账单、企业组织、动态调度算法、故障演练平台和原生 App。
+
    +
  1. 不开发完整自研 API 网关内核。
    2. +
  2. 不开发复杂 CRM、销售管理、工单系统。
    3. +
  3. 不开发复杂分销、代理、佣金结算体系。
    4. +
  4. 不开发多租户集团组织架构的复杂审批流。
    5. +
  5. 不开发原生 App。
    6. +
  6. 不承诺上游渠道商自身的可用性，只要求中转站具备故障发现、切换和记录能力。
    7. +
  7. 不承诺特定模型输出质量，只验收 API 调用链路、稳定性、分流策略和计费统计准确性。
    8. +
  8. 不开发企业级复杂组织架构；MVP 可采用“一个企业 = 一个用户 / 一个分组 + 多个 Token”的方式交付。
    9. +
  9. 不开发动态智能调度算法；MVP 只要求权重、优先级、模型匹配和可用性过滤。
    10. +
  10. 不开发完整 B2B 账单系统、月度对账单、发票、在线支付、充值和合同管理。
    11. +
  11. 不开发独立事故管理系统；MVP 只要求监控告警可触达、故障日志可追溯。
    12. +
+ +

1.4 技术基线

+
+ + + + + + + + + + + + + +
项目要求
基础系统New API，乙方需在开工前提交选型说明
部署方式Docker Compose 或等效可复现部署方式
数据库使用开源项目推荐的稳定数据库方案，生产环境不得使用仅适合本地测试的临时存储
反向代理Nginx / Caddy / Traefik 任一成熟方案
HTTPS必须启用，证书自动续期或提供明确续期方案
日志调用日志、错误日志、上游切换日志、管理员操作日志必须保留
监控Prometheus + Grafana、Uptime Kuma、Sentry 或同等方案
告警支持 Telegram / 飞书 / 企业微信 / 邮件任一可用告警通道
权限管理员账号、企业客户账号、API Key 权限隔离
+
+
+
+ +
+
+ 2 +
+

New API 能力边界与外包工作拆分

+

明确哪些是开源项目自带，哪些只是配置验收，哪些留到未来二开。

+
+
+
+
报价约束：乙方报价和排期时必须区分“开源项目自带能力”“配置与部署验收工作”“未来二开选项”，不得把 New API 已有能力包装成从零开发。
+

2.1 New API 开源项目自带能力

+
+ + + + + + + + + + + + + + + + + + + + +
能力New API 自带情况MVP 处理方式
统一 API 入口自带统一 LLM API 网关能力，可对外提供统一 Base URL配置并验收
OpenAI 兼容接口自带 OpenAI 兼容 API，并支持多模型服务格式兼容配置并验收
多上游渠道自带 Channel 管理，可配置 Base URL、API Key、模型列表配置 3 家渠道商
上游启停与测试自带渠道测试、启用、禁用能力配置并演示
模型映射自带 Model Mapping配置主要模型映射
权重分流自带 Priority / Weight 等渠道选择能力配置权重并压测验证
失败重试自带失败自动重试能力配置阈值并模拟故障
自动禁用异常渠道自带 Auto Disable 等渠道保护能力配置并模拟验证
用户管理自带用户、角色、状态、额度等管理能力配置企业客户账号
Token / API Key自带 Token 创建、禁用、额度、模型限制、IP 白名单等能力配置客户 Token
分组隔离自带 Group，可限制用户或 Token 可访问的渠道和模型用于企业/客户隔离
调用日志自带请求日志、Token 消耗、额度扣减和统计验证字段完整性
模型价格与倍率自带模型倍率、分组倍率、计费配置配置内部计量口径
Docker 部署自带 Docker / Docker Compose 部署方式生产化部署
数据库 / Redis支持 MySQL、PostgreSQL、Redis 等生产组件生产环境必须启用
集群部署官方支持共享数据库、Redis、反向代理的集群部署思路作为稳定性增强项
+
+ +

2.2 自带但必须认真配置和验收

+
+ + + + + + + + + + + + + + + + + +
能力外包必须完成的配置验收重点
3 家渠道商接入配置 Base URL、API Key、模型列表、模型映射、启停状态每家渠道商可单独连通测试；日志能看到命中的上游
上游接口兼容性核查渠道商是否 OpenAI 兼容；轻微差异先通过配置解决不接受只配置一家可用，另外两家“待后续接入”
故障切换配置失败重试、自动禁用、优先级、权重、超时参数模拟 5xx、超时、网络失败后请求能转移到备用上游
权重分流配置 3 家上游权重，例如 A/B/C = 50/30/20压测后实际流量分布与配置大体一致
模型匹配配置不同模型在不同上游的可用范围不支持某模型的上游不得收到该模型请求
分组隔离以 Group 或用户/Token 配置实现客户隔离企业客户不能使用未授权模型或渠道
Token 额度配置额度、过期时间、模型限制、IP 白名单或基础限制超额、过期、禁用后必须立即拒绝调用
用量统计确认请求量、Token、额度、模型、上游、错误等字段可查可按客户、Token、模型、上游维度抽查
生产数据库使用 MySQL 或 PostgreSQL，不得用 SQLite 作为生产交付重启、升级、备份后数据不丢失
Redis / 缓存按 New API 生产建议配置 Redis 或等效缓存组件高并发下服务稳定，不因缓存缺失导致明显异常
HTTPS 与反代配置 Nginx / Caddy / Traefik、HTTPS、请求体大小、超时、流式响应长响应和 stream 不被代理层截断
监控告警接入 Uptime Kuma、Prometheus/Grafana、Sentry 或同等工具服务宕机、上游异常、错误率升高能触发告警
备份恢复配置数据库自动备份和恢复脚本完成一次恢复演示
+
+ +

2.3 MVP 暂不做，列为未来开发选项

+
+ + + + + + + + + + + + + +
未来选项说明
企业级组织体系企业、部门、企业管理员、开发者、审批流、成员邀请等完整租户功能
企业管理员自助后台企业管理员自行创建成员、分配 Key、查看本企业所有成员用量
B2B 账单与月报月度对账单、发票、合同、在线支付、充值、欠费停用
动态智能调度按实时成本、实时延迟、实时错误率、渠道余额自动选择最优上游
429 自动降权策略收到 429 后临时降低某上游权重、冷却后自动恢复的精细策略
故障演练平台一键模拟上游异常、生成演练报告、事故复盘时间线
管理员操作审计记录谁修改了渠道、额度、Token、模型、价格，并可追责导出
品牌化客户门户完整企业品牌、定制 UI、隐藏开源项目默认充值/公告等不相关入口
独立数据仓库报表将调用日志同步到 BI / ClickHouse / 数据仓库进行长期分析
+
+
+
+ +
+
+ 3 +
+

角色与核心业务流程

+

MVP 用 New API 的用户、分组、Token 组合承载 B2B 客户。

+
+
+
+

3.1 用户角色

+
+ + + + + + + + +
角色说明MVP 权限
超级管理员甲方内部技术或运营负责人管理上游渠道、客户、额度、模型、分流策略、日志与告警
企业客户账号B2B 客户侧负责人或技术对接人查看本账号 API Key、额度、用量、调用记录
企业开发者B2B 客户实际调用人员使用分配到的 API Key 调用接口，查看必要的调用说明
运维人员甲方或乙方交接人员查看系统状态、告警、日志、备份与恢复流程
+
+

3.2 核心业务流程

+
+ + + + + + + + + + + + +
流程MVP 要求验收标准
企业开户管理员创建企业客户账号或客户分组，配置额度和 API Key新建客户后可立即生成可用 API Key
API 调用企业客户通过统一接口调用模型OpenAI 兼容格式或双方约定格式可正常请求和返回
上游路由系统按模型、权重、可用性选择上游渠道商日志中可看到每次请求命中的上游
故障切换某上游异常时自动切换到可用上游模拟上游 5xx、超时、网络失败后，请求可转移到备用上游
基础智能分流按权重、优先级、模型匹配、可用性分配流量管理后台可调整权重，实际调用分布与配置基本一致
额度控制按客户或 API Key 限制额度超出额度后拒绝调用并返回明确错误
用量统计记录调用次数、Token、费用或等效消耗客户维度、Key 维度、上游维度均可查看统计
监控告警异常率、延迟、上游不可用触发告警人工制造异常后 3 分钟内收到告警
+
+
+
+ +
+
+ 4 +
+

功能需求

+

围绕统一入口、多上游、故障切换、分流和客户 Token 管理验收。

+
+
+
+

4.1 API 中转核心能力 P0

+
+ + + + + + + +
验收项判定标准
统一 API 入口对外提供统一 Base URL，客户无需感知 3 家上游差异
OpenAI 兼容接口至少支持 Chat Completions 或双方确认的主要调用接口
上游密钥管理3 家渠道商密钥可在后台或安全配置中管理，不得写死在代码中
模型映射支持将下游模型名映射到不同上游模型名
请求转发请求头、请求体、流式响应、错误响应处理稳定
流式输出如上游支持 stream，中转站需正确透传流式响应
错误标准化上游错误需转换为客户可理解的统一错误格式，并保留内部错误详情日志
+ +

4.2 上游渠道商管理 P0

+
+ + + + + + +
验收项判定标准
接入 3 家上游3 家渠道商均可独立配置、启停、测试连通性
健康检查系统可定时检测上游连通性、延迟、错误率
手动启停管理员可手动禁用某个上游，禁用后不再分配新请求
优先级配置可设置主用、备用或权重
模型支持差异不同上游支持模型不同，系统不得把请求路由到不支持该模型的上游
上游凭据保护上游 API Key 不得在前端、日志、错误信息中明文泄露
+ +

4.3 故障切换与熔断 P0

+
+ + + + + + +
场景MVP 要求验收方式
上游网络超时超过配置阈值后自动切换备用上游人工配置超时或断网模拟
上游 5xx连续失败达到阈值后熔断该上游使用 mock 或测试上游返回 500
上游限流收到 429 或等效限流错误后触发失败重试、自动禁用或转备用上游模拟 429
上游恢复被自动禁用或异常的上游可通过健康检查或人工测试恢复使用恢复上游后观察重新进入候选池
无可用上游返回明确错误，不得卡死或无限重试禁用全部上游后测试
手动兜底管理员可强制指定上游或关闭某上游后台操作后立即生效
+ +

4.4 基础智能分流 P0

+

MVP 分流不开发复杂算法，使用 New API 自带的优先级、权重、模型匹配、分组隔离和可用性过滤完成。分流策略必须可解释、可配置、可回滚。

+
+ + + + + + +
分流策略MVP 要求
权重分流例如渠道 A 50%、渠道 B 30%、渠道 C 20%
可用性优先已熔断或健康检查失败的上游不得继续分配流量
模型匹配按模型支持情况选择可用上游
优先级支持配置某上游为优先使用，备用上游只在故障时启用
客户隔离通过 Group、用户或 Token 限制不同客户可用模型和渠道
实际分布统计管理后台或报表可看到各上游承接的请求量和占比
+ +

4.5 企业客户与 API Key 管理 P0

+
+ + + + + + + +
验收项判定标准
企业客户创建管理员可通过 New API 用户、分组或等效配置创建、禁用、编辑企业客户
API Key 生成每个企业客户可生成一个或多个 Token / API Key
Key 禁用禁用 Key 后立即无法调用
额度设置支持按企业或 Key 设置额度、过期时间或调用限制
速率限制支持基础 QPS / RPM 限制，避免单客户打爆系统
调用记录可按企业、Key、时间、模型、上游查询调用记录
数据隔离企业客户只能看到自己的用量和 Key；如默认界面无法完整满足，MVP 可由管理员代查
+ +

4.6 管理后台与客户侧最小页面

+
+ + + + + + +
模块必须能力
仪表盘今日请求量、成功率、平均延迟、错误率、上游状态
上游管理3 家渠道商配置、启停、权重、健康状态
客户管理用户/分组列表、额度、API Key、状态
调用日志请求时间、客户、模型、上游、状态码、耗时、错误原因
告警记录可通过外部监控系统查看告警触发时间、类型、恢复时间
客户侧页面登录页、API Key 页、用量页、接入说明页
+
+
+ +
+
+ 5 +
+

非功能需求

+

稳定性、性能、安全和可观测性是 MVP 可运营的硬门槛。

+
+
+
+

5.1 稳定性与性能 P0

+
+ + + + + + + + +
指标验收标准
系统可用性试运行期核心 API 可用性不低于 99.5%
API 成功率排除客户参数错误后，成功率不低于 99%
故障切换单一上游故障时，中转站应在 1 分钟内停止向其分配新请求
500 用户规模按 500 个企业用户或开发者账号规模配置，不因用户表规模导致明显卡顿
并发请求至少通过 100 并发请求压测，系统自身不崩溃
中转额外延迟上游正常情况下，中转站额外增加的中位延迟应小于 300ms
后台查询近 7 天调用日志查询 3 秒内返回
长响应对流式或长文本响应不得被代理层提前截断
+

5.2 安全与可观测性

+
+ + + + + + + + +
模块必须要求
HTTPS生产域名必须启用 HTTPS
密钥保护上游 Key、数据库密码、JWT Secret 等必须通过环境变量或密钥文件管理
日志脱敏不记录完整 API Key、上游密钥、用户敏感请求内容；如必须记录，需可配置关闭
权限隔离管理员、企业客户、普通用户权限隔离
API 请求监控请求量、成功率、错误率、平均延迟、P95 延迟
上游状态监控每个上游的健康状态、错误率、延迟、熔断次数
系统资源监控CPU、内存、磁盘、网络、数据库连接数
告警上游不可用、错误率过高、延迟过高、磁盘不足、服务宕机
+
+
+ +
+
+ 6 +
+

部署与运维交付

+

必须交付可复现部署、备份恢复、监控告警和完整运维文档。

+
+
+
+

6.1 环境要求

+
+ + +
环境用途要求
测试环境功能验收和模拟故障可随时重置，不影响生产数据
生产环境真实客户使用HTTPS、监控、备份、告警全部启用
+

6.2 必交文档

+
    +
  1. 服务器配置建议。
    2. +
  2. 域名和 DNS 配置。
    3. +
  3. Docker Compose 或部署命令。
    4. +
  4. 环境变量清单。
    5. +
  5. 数据库初始化和迁移步骤。
    6. +
  6. 上游渠道商配置步骤。
    7. +
  7. 监控和告警配置步骤。
    8. +
  8. 备份与恢复步骤。
    9. +
  9. 常见故障排查手册。
    10. +
  10. 如何新增第 4 家上游渠道商。
    11. +
+

6.3 备份与恢复

+
+ + + + +
验收项判定标准
自动备份数据库至少每日自动备份一次
保留周期至少保留最近 7 天备份
恢复演练乙方需演示一次从备份恢复到测试环境
配置备份关键配置、环境变量模板、部署文件纳入交付物
+
+
+ +
+
+ 7 +
+

验收维度

+

P0 一票否决 + 功能清单 + New API 配置专项验收。

+
+
+
+

7.1 P0 一票否决项

+
以下任一项未通过，则整批不验收。
+
    +
  1. 统一 API 入口无法稳定调用。
    2. +
  2. 3 家上游渠道商未全部接通，且无明确原因和替代方案。
    3. +
  3. 单一上游故障时不能自动或手动切换到其他上游。
    4. +
  4. API Key、上游密钥或客户数据存在明显泄露风险。
    5. +
  5. 调用日志、用量统计、额度扣减核心数据明显不准确。
    6. +
  6. 管理后台无法完成上游管理、客户管理、Key 管理、用量查看。
    7. +
  7. 监控告警未接入，或模拟故障无法触发告警。
    8. +
  8. 无部署文档、无运维交接文档、无备份恢复方案。
    9. +
  9. 存在恶意代码、后门、未知数据外传逻辑。
    10. +
  10. 乙方将 New API 已有能力改写成不可维护的私有实现，且未获得甲方书面确认。
    11. +
+

7.2 功能验收清单

+
+ + + + + + + + + + + + +
勾选验收项判定标准验收方
[ ]统一 Base URL客户可通过统一地址调用甲方技术
[ ]3 家上游接入每家上游可单独测试通过甲方技术
[ ]模型映射至少 3 个主要模型完成映射甲方技术
[ ]流式响应stream 调用可正常透传甲方技术
[ ]故障切换模拟上游异常后自动切换成功甲方技术
[ ]手动切换后台禁用某上游后立即生效甲方技术
[ ]权重分流权重调整后流量分布变化可观察甲方技术
[ ]企业客户可创建、禁用、编辑企业客户甲方产品
[ ]API Key可生成、禁用、复制、调用甲方产品
[ ]额度限制超额后调用被拒绝甲方产品
[ ]调用日志可按客户、Key、模型、上游查询甲方运营
[ ]监控告警故障 3 分钟内触达告警渠道甲方运维
+

7.3 New API 配置专项验收清单

+
+ + + + + + + + + +
勾选验收项判定标准验收方
[ ]使用生产数据库MySQL 或 PostgreSQL 已启用，未使用 SQLite 交付生产甲方技术
[ ]Redis 或等效缓存按生产配置启用 Redis 或说明替代方案甲方技术
[ ]3 家渠道商配置表交付每家渠道商的 Base URL、模型、权重、优先级、启停状态说明甲方技术
[ ]模型映射表交付下游模型名到上游模型名的映射表甲方技术
[ ]分组与客户映射交付企业客户与 New API 用户/分组/Token 的映射规则甲方产品
[ ]故障演示记录提交 5xx、超时、禁用上游、恢复上游的演示记录甲方技术
[ ]权重压测记录提交权重分流压测结果和日志截图甲方技术
[ ]日志字段核查日志中可查客户、Token、模型、上游、状态、耗时、错误甲方运营
[ ]反代流式配置stream / 长响应不被 Nginx、Caddy 或负载均衡截断甲方技术
+
+
+ +
+
+ 8 +
+

交付节点与付款建议

+

按验收节点释放款项，避免“部署能打开但不可运营”。

+
+
+
+
+
CP 1 · 20%方案确认选型说明、架构图、部署计划、风险清单、New API 配置清单。
+
CP 2 · 20%基础部署测试环境、统一 API 入口、管理员后台、1 家上游接通。
+
CP 3 · 25%多上游与切换3 家上游接通、故障切换、权重分流、日志、模型映射表。
+
CP 4 · 25%生产就绪生产部署、HTTPS、监控告警、备份恢复、压测报告。
+
尾款 · 10%保修期结束试运行问题闭环、文档交接完成，无遗留 P0/P1 问题。
+
+
+
+ +
+
+ 9 +
+

不通过处理

+

缺陷等级、修复时限与返工规则。

+
+
+
+

9.1 缺陷等级

+
+ + + +
等级定义修复时限
P0API 主链路不可用、密钥泄露、故障无法切换、数据严重错误24 小时内修复或给出可执行临时方案
P1部分客户受影响、部分上游异常、统计局部错误、后台核心功能异常72 小时内修复
P2非核心页面问题、体验问题、文档小错误7 个工作日内修复
+

9.2 返工规则

+
    +
  1. P0 缺陷未关闭，不进入下一付款节点。
    2. +
  2. 同一 P0 问题重复出现 2 次以上，甲方有权要求乙方提交根因分析报告。
    3. +
  3. 返工超过 10 个工作日仍无法通过核心验收，甲方有权暂停项目或更换供应商。
    4. +
  4. 乙方提交修复后，甲方有权要求重测相关完整链路，而非只测单点。
    5. +
+
+
+ + +
+
+
+ +