d8dfun/new-api
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add API relay outsourcing requirements document

Browse Source 
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
zyh
2026-05-25 19:47:07 +08:00
parent 583da45296
commit 5421e5661c
1 changed files with 992 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

992
api-relay-outsourcing-requirements-mvp.html Normal file
View File

@@ -0,0 +1,992 @@
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>企业级 API 中转站 MVP 外包需求与验收标准</title>
<style>
:root {
--bg: #0b1020;
--panel: #11182b;
--panel-2: #151f36;
--panel-3: #0f1628;
--text: #eef4ff;
--muted: #9fb0ca;
--dim: #74839a;
--line: #25334d;
--line-soft: #1b2740;
--brand: #41d1b4;
--brand-2: #58a6ff;
--brand-3: #9b8cff;
--warn: #ffb454;
--danger: #ff6b6b;
--ok: #58d68d;
--paper: #f8fafc;
--ink: #101828;
--shadow: 0 24px 70px rgba(0, 0, 0, .32);
}
* { box-sizing: border-box; }
html { scroll-behavior: smooth; }
body {
margin: 0;
color: var(--text);
background:
radial-gradient(circle at 8% -4%, rgba(65, 209, 180, .18), transparent 28%),
radial-gradient(circle at 88% 8%, rgba(88, 166, 255, .16), transparent 28%),
linear-gradient(180deg, #090d18 0%, var(--bg) 46%, #080b13 100%);
font-family: -apple-system, BlinkMacSystemFont, "PingFang SC", "Microsoft YaHei", "Segoe UI", sans-serif;
line-height: 1.72;
font-size: 15px;
}
.page {
width: min(1180px, calc(100vw - 32px));
margin: 0 auto;
padding: 28px 0 56px;
}
.hero {
position: relative;
overflow: hidden;
min-height: 420px;
border: 1px solid rgba(255, 255, 255, .09);
border-radius: 18px;
background:
linear-gradient(135deg, rgba(65, 209, 180, .12), rgba(88, 166, 255, .10) 42%, rgba(155, 140, 255, .12)),
linear-gradient(180deg, rgba(17, 24, 43, .98), rgba(11, 16, 32, .96));
box-shadow: var(--shadow);
padding: 36px;
}
.hero::after {
content: "";
position: absolute;
inset: auto -12% -48% 45%;
height: 320px;
background: linear-gradient(90deg, transparent, rgba(65, 209, 180, .16), transparent);
transform: rotate(-12deg);
pointer-events: none;
}
.eyebrow {
display: inline-flex;
align-items: center;
gap: 8px;
padding: 7px 11px;
border: 1px solid rgba(65, 209, 180, .25);
border-radius: 999px;
background: rgba(65, 209, 180, .08);
color: #bff8ed;
font-size: 12px;
font-weight: 700;
letter-spacing: .08em;
text-transform: uppercase;
}
h1 {
max-width: 860px;
margin: 22px 0 12px;
font-size: 44px;
line-height: 1.12;
letter-spacing: 0;
}
.hero-copy {
max-width: 820px;
margin: 0;
color: #c6d5ec;
font-size: 17px;
}
.meta-grid {
display: grid;
grid-template-columns: repeat(4, minmax(0, 1fr));
gap: 12px;
margin-top: 28px;
}
.meta-card, .metric-card {
min-height: 96px;
border: 1px solid rgba(255, 255, 255, .09);
border-radius: 10px;
background: rgba(7, 11, 22, .54);
padding: 15px;
}
.meta-label {
color: var(--dim);
font-size: 12px;
font-weight: 700;
letter-spacing: .04em;
text-transform: uppercase;
}
.meta-value {
margin-top: 7px;
color: var(--text);
font-size: 18px;
font-weight: 800;
line-height: 1.25;
}
.layout {
display: grid;
grid-template-columns: 264px minmax(0, 1fr);
gap: 22px;
align-items: start;
margin-top: 22px;
}
.toc {
position: sticky;
top: 16px;
border: 1px solid var(--line);
border-radius: 14px;
background: rgba(17, 24, 43, .84);
backdrop-filter: blur(16px);
padding: 14px;
box-shadow: 0 16px 44px rgba(0, 0, 0, .22);
}
.toc-title {
padding: 5px 7px 10px;
color: #dbe8fb;
font-size: 13px;
font-weight: 800;
letter-spacing: .04em;
}
.toc a {
display: block;
padding: 8px 9px;
border-radius: 8px;
color: var(--muted);
text-decoration: none;
font-size: 13px;
line-height: 1.35;
}
.toc a:hover {
background: rgba(88, 166, 255, .10);
color: var(--text);
}
.content {
display: grid;
gap: 18px;
}
section {
border: 1px solid var(--line);
border-radius: 16px;
background:
linear-gradient(180deg, rgba(21, 31, 54, .88), rgba(17, 24, 43, .96));
box-shadow: 0 16px 44px rgba(0, 0, 0, .22);
overflow: hidden;
}
.section-head {
display: flex;
gap: 14px;
align-items: flex-start;
padding: 24px 26px 16px;
border-bottom: 1px solid var(--line-soft);
background: rgba(255, 255, 255, .02);
}
.num {
flex: 0 0 auto;
display: inline-grid;
place-items: center;
min-width: 38px;
height: 38px;
padding: 0 10px;
border-radius: 10px;
color: #071119;
background: linear-gradient(135deg, var(--brand), #8ff2df);
font-weight: 900;
}
.section-head h2 {
margin: 1px 0 5px;
font-size: 22px;
line-height: 1.25;
letter-spacing: 0;
}
.section-head p {
margin: 0;
color: var(--muted);
font-size: 13px;
}
.section-body {
padding: 22px 26px 26px;
}
h3 {
display: flex;
align-items: center;
gap: 9px;
margin: 24px 0 10px;
color: #f4f8ff;
font-size: 17px;
letter-spacing: 0;
}
h3:first-child { margin-top: 0; }
h3::before {
content: "";
width: 5px;
height: 18px;
border-radius: 8px;
background: var(--brand-2);
}
p { margin: 9px 0; color: #d7e1f1; }
ul, ol { margin: 10px 0; padding-left: 22px; }
li { margin: 6px 0; color: #d7e1f1; }
strong { color: #fff; }
code {
padding: 2px 6px;
border: 1px solid rgba(88, 166, 255, .18);
border-radius: 6px;
color: #b9dcff;
background: rgba(88, 166, 255, .10);
font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
font-size: .92em;
}
.callout {
margin: 14px 0;
padding: 14px 16px;
border: 1px solid rgba(65, 209, 180, .24);
border-left: 4px solid var(--brand);
border-radius: 10px;
background: rgba(65, 209, 180, .07);
color: #d9fff7;
}
.callout.warn {
border-color: rgba(255, 180, 84, .25);
border-left-color: var(--warn);
background: rgba(255, 180, 84, .08);
color: #ffe8c4;
}
.callout.danger {
border-color: rgba(255, 107, 107, .28);
border-left-color: var(--danger);
background: rgba(255, 107, 107, .08);
color: #ffd2d2;
}
.cards {
display: grid;
grid-template-columns: repeat(3, minmax(0, 1fr));
gap: 12px;
margin: 16px 0;
}
.metric-card {
min-height: 118px;
background: linear-gradient(180deg, rgba(15, 22, 40, .92), rgba(9, 13, 24, .82));
}
.metric-number {
color: var(--brand);
font-size: 30px;
font-weight: 900;
line-height: 1;
}
.metric-text {
margin-top: 9px;
color: var(--muted);
font-size: 13px;
line-height: 1.5;
}
.table-wrap {
margin: 14px 0 18px;
overflow-x: auto;
border: 1px solid var(--line);
border-radius: 12px;
background: rgba(5, 8, 16, .28);
}
table {
width: 100%;
min-width: 720px;
border-collapse: collapse;
font-size: 13px;
}
th, td {
padding: 11px 13px;
border-bottom: 1px solid var(--line-soft);
border-right: 1px solid var(--line-soft);
vertical-align: top;
text-align: left;
}
th:last-child, td:last-child { border-right: 0; }
tr:last-child td { border-bottom: 0; }
th {
position: sticky;
top: 0;
z-index: 1;
color: #dcecff;
background: #17233b;
font-weight: 800;
white-space: nowrap;
}
td { color: #d3dfef; }
.badge {
display: inline-flex;
align-items: center;
height: 22px;
padding: 0 8px;
border-radius: 999px;
font-size: 11px;
font-weight: 800;
letter-spacing: .03em;
white-space: nowrap;
}
.p0 { color: #ffe3e3; background: rgba(255, 107, 107, .18); border: 1px solid rgba(255, 107, 107, .26); }
.p1 { color: #fff0cf; background: rgba(255, 180, 84, .16); border: 1px solid rgba(255, 180, 84, .25); }
.ok { color: #d9fff0; background: rgba(88, 214, 141, .14); border: 1px solid rgba(88, 214, 141, .25); }
.cfg { color: #d9e8ff; background: rgba(88, 166, 255, .14); border: 1px solid rgba(88, 166, 255, .25); }
.timeline {
display: grid;
grid-template-columns: repeat(5, minmax(0, 1fr));
gap: 10px;
margin-top: 14px;
}
.step {
border: 1px solid var(--line);
border-radius: 12px;
background: rgba(7, 11, 22, .42);
padding: 13px;
}
.step b {
display: block;
color: var(--brand);
font-size: 12px;
letter-spacing: .04em;
text-transform: uppercase;
margin-bottom: 5px;
}
.step strong {
display: block;
margin-bottom: 6px;
font-size: 14px;
}
.step span {
color: var(--muted);
font-size: 12px;
line-height: 1.45;
}
.sign-grid {
display: grid;
grid-template-columns: repeat(4, minmax(0, 1fr));
gap: 12px;
margin-top: 14px;
}
.sign-box {
min-height: 116px;
border: 1px dashed rgba(238, 244, 255, .30);
border-radius: 12px;
padding: 13px;
background: rgba(255, 255, 255, .03);
color: var(--muted);
}
.sign-box strong {
display: block;
color: var(--text);
margin-bottom: 30px;
}
.print-note {
margin-top: 16px;
color: var(--dim);
font-size: 12px;
text-align: right;
}
@media (max-width: 980px) {
.page { width: min(100vw - 22px, 920px); padding-top: 14px; }
.hero { padding: 24px; min-height: auto; }
h1 { font-size: 34px; }
.meta-grid { grid-template-columns: repeat(2, minmax(0, 1fr)); }
.layout { grid-template-columns: 1fr; }
.toc { position: static; }
.toc a { display: inline-block; margin: 2px; }
.cards { grid-template-columns: 1fr; }
.timeline { grid-template-columns: 1fr; }
.sign-grid { grid-template-columns: repeat(2, minmax(0, 1fr)); }
}
@media (max-width: 620px) {
body { font-size: 14px; }
.hero { padding: 20px; border-radius: 14px; }
h1 { font-size: 29px; }
.meta-grid, .sign-grid { grid-template-columns: 1fr; }
.section-head { padding: 20px 18px 14px; }
.section-body { padding: 18px; }
table { min-width: 660px; }
}
@media print {
body {
background: #fff;
color: var(--ink);
font-size: 11px;
}
.page { width: 100%; padding: 0; }
.hero, section {
box-shadow: none;
border-color: #cbd5e1;
background: #fff;
color: var(--ink);
page-break-inside: avoid;
}
.hero { min-height: 0; padding: 22px; }
.hero::after, .toc { display: none; }
h1, .section-head h2, h3, p, li, td, .hero-copy { color: var(--ink); }
.layout { display: block; }
.section-head { background: #f1f5f9; border-color: #cbd5e1; }
.section-body { padding: 16px 18px; }
.num { color: #fff; background: #0f766e; }
.callout, .metric-card, .step, .sign-box {
background: #f8fafc;
border-color: #cbd5e1;
color: var(--ink);
}
th { background: #e2e8f0; color: var(--ink); }
td { color: var(--ink); }
th, td { border-color: #cbd5e1; }
code { color: #0f172a; background: #e2e8f0; border-color: #cbd5e1; }
}
</style>
</head>
<body>
<main class="page">
<header class="hero">
<span class="eyebrow">MVP Outsourcing Standard · v1.1</span>
<h1>企业级 API 中转站 MVP 外包需求与验收标准</h1>
<p class="hero-copy">基于 <code>QuantumNous/new-api</code> 的 B2B API 中转站交付标准。核心目标是接通可用、稳定运行、可故障切换、可监控、可交接验收，而不是从零开发完整 SaaS 平台。</p>
<div class="meta-grid">
<div class="meta-card"><div class="meta-label">上游渠道商</div><div class="meta-value">3 家</div></div>
<div class="meta-card"><div class="meta-label">预期用户规模</div><div class="meta-value">约 500 人</div></div>
<div class="meta-card"><div class="meta-label">交付模式</div><div class="meta-value">配置 + 部署 + 验收</div></div>
<div class="meta-card"><div class="meta-label">MVP 原则</div><div class="meta-value">先稳定可用</div></div>
</div>
</header>
<div class="layout">
<aside class="toc">
<div class="toc-title">文档目录</div>
<a href="#overview">1. 项目概述</a>
<a href="#boundary">2. New API 能力边界</a>
<a href="#flow">3. 角色与流程</a>
<a href="#features">4. 功能需求</a>
<a href="#quality">5. 非功能需求</a>
<a href="#ops">6. 部署与运维</a>
<a href="#acceptance">7. 验收维度</a>
<a href="#milestones">8. 交付节点</a>
<a href="#defects">9. 不通过处理</a>
<a href="#legal">10. 法务与交接</a>
</aside>
<div class="content">
<section id="overview">
<div class="section-head">
<span class="num">1</span>
<div>
<h2>项目概述</h2>
<p>先对齐“做什么 / 不做什么 / 以什么方式交付”，避免外包范围膨胀。</p>
</div>
</div>
<div class="section-body">
<h3>1.1 项目背景</h3>
<p>本项目拟基于开源项目 <strong>New API</strong> 部署一个面向企业 B2B 客户的 API 中转站。甲方上游不直接对接原始模型厂商，而是对接已经完成模型解析和接口封装的渠道商。当前计划接入 3 家上游渠道商，由上游渠道商向甲方提供可调用 API。</p>
<p>本次外包目标不是从零开发一个完整 SaaS 平台，而是交付一个 MVP：接通可用、运行稳定、可监控、可故障切换、可支撑约 500 人规模的企业客户使用。</p>
<div class="cards">
<div class="metric-card"><div class="metric-number">3</div><div class="metric-text">上游渠道商接入，均需可独立测试、启停、记录命中日志。</div></div>
<div class="metric-card"><div class="metric-number">500</div><div class="metric-text">按约 500 人规模配置，不因用户或日志规模导致明显卡顿。</div></div>
<div class="metric-card"><div class="metric-number">99.5%</div><div class="metric-text">试运行期核心 API 可用性目标，不包含客户参数错误和上游自身故障。</div></div>
</div>
<h3>1.2 本次交付范围</h3>
<ol>
<li>部署并配置一个可生产使用的 API 中转站，优先基于 New API 等成熟开源方案。</li>
<li>接入 3 家上游渠道商 API，并支持统一的下游调用入口。</li>
<li>提供企业 B2B 客户使用所需的账号、API Key、额度、调用统计、基础权限能力。</li>
<li>基于 New API 已有能力配置上游故障识别、失败重试、手动切换、权重分流、自动禁用与恢复验证机制。</li>
<li>完成日志、监控、告警、备份、部署文档、运维交接文档。</li>
<li>支撑约 500 名用户规模的稳定运行，满足本文定义的性能和稳定性验收标准。</li>
</ol>
<h3>1.3 明确不做范围</h3>
<div class="callout warn"><strong>MVP 不做复杂平台化。</strong> 本次交付不开发完整自研 API 网关内核，不开发复杂 CRM、分销、账单、企业组织、动态调度算法、故障演练平台和原生 App。</div>
<ol>
<li>不开发完整自研 API 网关内核。</li>
<li>不开发复杂 CRM、销售管理、工单系统。</li>
<li>不开发复杂分销、代理、佣金结算体系。</li>
<li>不开发多租户集团组织架构的复杂审批流。</li>
<li>不开发原生 App。</li>
<li>不承诺上游渠道商自身的可用性，只要求中转站具备故障发现、切换和记录能力。</li>
<li>不承诺特定模型输出质量，只验收 API 调用链路、稳定性、分流策略和计费统计准确性。</li>
<li>不开发企业级复杂组织架构；MVP 可采用“一个企业 = 一个用户 / 一个分组 + 多个 Token”的方式交付。</li>
<li>不开发动态智能调度算法；MVP 只要求权重、优先级、模型匹配和可用性过滤。</li>
<li>不开发完整 B2B 账单系统、月度对账单、发票、在线支付、充值和合同管理。</li>
<li>不开发独立事故管理系统；MVP 只要求监控告警可触达、故障日志可追溯。</li>
</ol>
<h3>1.4 技术基线</h3>
<div class="table-wrap">
<table>
<thead><tr><th>项目</th><th>要求</th></tr></thead>
<tbody>
<tr><td>基础系统</td><td>New API，乙方需在开工前提交选型说明</td></tr>
<tr><td>部署方式</td><td>Docker Compose 或等效可复现部署方式</td></tr>
<tr><td>数据库</td><td>使用开源项目推荐的稳定数据库方案，生产环境不得使用仅适合本地测试的临时存储</td></tr>
<tr><td>反向代理</td><td>Nginx / Caddy / Traefik 任一成熟方案</td></tr>
<tr><td>HTTPS</td><td>必须启用，证书自动续期或提供明确续期方案</td></tr>
<tr><td>日志</td><td>调用日志、错误日志、上游切换日志、管理员操作日志必须保留</td></tr>
<tr><td>监控</td><td>Prometheus + Grafana、Uptime Kuma、Sentry 或同等方案</td></tr>
<tr><td>告警</td><td>支持 Telegram / 飞书 / 企业微信 / 邮件任一可用告警通道</td></tr>
<tr><td>权限</td><td>管理员账号、企业客户账号、API Key 权限隔离</td></tr>
</tbody>
</table>
</div>
</div>
</section>
<section id="boundary">
<div class="section-head">
<span class="num">2</span>
<div>
<h2>New API 能力边界与外包工作拆分</h2>
<p>明确哪些是开源项目自带，哪些只是配置验收，哪些留到未来二开。</p>
</div>
</div>
<div class="section-body">
<div class="callout"><strong>报价约束：</strong>乙方报价和排期时必须区分“开源项目自带能力”“配置与部署验收工作”“未来二开选项”，不得把 New API 已有能力包装成从零开发。</div>
<h3>2.1 New API 开源项目自带能力</h3>
<div class="table-wrap">
<table>
<thead><tr><th>能力</th><th>New API 自带情况</th><th>MVP 处理方式</th></tr></thead>
<tbody>
<tr><td>统一 API 入口</td><td>自带统一 LLM API 网关能力，可对外提供统一 Base URL</td><td><span class="badge cfg">配置并验收</span></td></tr>
<tr><td>OpenAI 兼容接口</td><td>自带 OpenAI 兼容 API，并支持多模型服务格式兼容</td><td><span class="badge cfg">配置并验收</span></td></tr>
<tr><td>多上游渠道</td><td>自带 Channel 管理，可配置 Base URL、API Key、模型列表</td><td>配置 3 家渠道商</td></tr>
<tr><td>上游启停与测试</td><td>自带渠道测试、启用、禁用能力</td><td>配置并演示</td></tr>
<tr><td>模型映射</td><td>自带 Model Mapping</td><td>配置主要模型映射</td></tr>
<tr><td>权重分流</td><td>自带 Priority / Weight 等渠道选择能力</td><td>配置权重并压测验证</td></tr>
<tr><td>失败重试</td><td>自带失败自动重试能力</td><td>配置阈值并模拟故障</td></tr>
<tr><td>自动禁用异常渠道</td><td>自带 Auto Disable 等渠道保护能力</td><td>配置并模拟验证</td></tr>
<tr><td>用户管理</td><td>自带用户、角色、状态、额度等管理能力</td><td>配置企业客户账号</td></tr>
<tr><td>Token / API Key</td><td>自带 Token 创建、禁用、额度、模型限制、IP 白名单等能力</td><td>配置客户 Token</td></tr>
<tr><td>分组隔离</td><td>自带 Group，可限制用户或 Token 可访问的渠道和模型</td><td>用于企业/客户隔离</td></tr>
<tr><td>调用日志</td><td>自带请求日志、Token 消耗、额度扣减和统计</td><td>验证字段完整性</td></tr>
<tr><td>模型价格与倍率</td><td>自带模型倍率、分组倍率、计费配置</td><td>配置内部计量口径</td></tr>
<tr><td>Docker 部署</td><td>自带 Docker / Docker Compose 部署方式</td><td>生产化部署</td></tr>
<tr><td>数据库 / Redis</td><td>支持 MySQL、PostgreSQL、Redis 等生产组件</td><td>生产环境必须启用</td></tr>
<tr><td>集群部署</td><td>官方支持共享数据库、Redis、反向代理的集群部署思路</td><td>作为稳定性增强项</td></tr>
</tbody>
</table>
</div>
<h3>2.2 自带但必须认真配置和验收</h3>
<div class="table-wrap">
<table>
<thead><tr><th>能力</th><th>外包必须完成的配置</th><th>验收重点</th></tr></thead>
<tbody>
<tr><td>3 家渠道商接入</td><td>配置 Base URL、API Key、模型列表、模型映射、启停状态</td><td>每家渠道商可单独连通测试；日志能看到命中的上游</td></tr>
<tr><td>上游接口兼容性</td><td>核查渠道商是否 OpenAI 兼容；轻微差异先通过配置解决</td><td>不接受只配置一家可用，另外两家“待后续接入”</td></tr>
<tr><td>故障切换</td><td>配置失败重试、自动禁用、优先级、权重、超时参数</td><td>模拟 5xx、超时、网络失败后请求能转移到备用上游</td></tr>
<tr><td>权重分流</td><td>配置 3 家上游权重，例如 A/B/C = 50/30/20</td><td>压测后实际流量分布与配置大体一致</td></tr>
<tr><td>模型匹配</td><td>配置不同模型在不同上游的可用范围</td><td>不支持某模型的上游不得收到该模型请求</td></tr>
<tr><td>分组隔离</td><td>以 Group 或用户/Token 配置实现客户隔离</td><td>企业客户不能使用未授权模型或渠道</td></tr>
<tr><td>Token 额度</td><td>配置额度、过期时间、模型限制、IP 白名单或基础限制</td><td>超额、过期、禁用后必须立即拒绝调用</td></tr>
<tr><td>用量统计</td><td>确认请求量、Token、额度、模型、上游、错误等字段可查</td><td>可按客户、Token、模型、上游维度抽查</td></tr>
<tr><td>生产数据库</td><td>使用 MySQL 或 PostgreSQL，不得用 SQLite 作为生产交付</td><td>重启、升级、备份后数据不丢失</td></tr>
<tr><td>Redis / 缓存</td><td>按 New API 生产建议配置 Redis 或等效缓存组件</td><td>高并发下服务稳定，不因缓存缺失导致明显异常</td></tr>
<tr><td>HTTPS 与反代</td><td>配置 Nginx / Caddy / Traefik、HTTPS、请求体大小、超时、流式响应</td><td>长响应和 stream 不被代理层截断</td></tr>
<tr><td>监控告警</td><td>接入 Uptime Kuma、Prometheus/Grafana、Sentry 或同等工具</td><td>服务宕机、上游异常、错误率升高能触发告警</td></tr>
<tr><td>备份恢复</td><td>配置数据库自动备份和恢复脚本</td><td>完成一次恢复演示</td></tr>
</tbody>
</table>
</div>
<h3>2.3 MVP 暂不做，列为未来开发选项</h3>
<div class="table-wrap">
<table>
<thead><tr><th>未来选项</th><th>说明</th></tr></thead>
<tbody>
<tr><td>企业级组织体系</td><td>企业、部门、企业管理员、开发者、审批流、成员邀请等完整租户功能</td></tr>
<tr><td>企业管理员自助后台</td><td>企业管理员自行创建成员、分配 Key、查看本企业所有成员用量</td></tr>
<tr><td>B2B 账单与月报</td><td>月度对账单、发票、合同、在线支付、充值、欠费停用</td></tr>
<tr><td>动态智能调度</td><td>按实时成本、实时延迟、实时错误率、渠道余额自动选择最优上游</td></tr>
<tr><td>429 自动降权策略</td><td>收到 429 后临时降低某上游权重、冷却后自动恢复的精细策略</td></tr>
<tr><td>故障演练平台</td><td>一键模拟上游异常、生成演练报告、事故复盘时间线</td></tr>
<tr><td>管理员操作审计</td><td>记录谁修改了渠道、额度、Token、模型、价格，并可追责导出</td></tr>
<tr><td>品牌化客户门户</td><td>完整企业品牌、定制 UI、隐藏开源项目默认充值/公告等不相关入口</td></tr>
<tr><td>独立数据仓库报表</td><td>将调用日志同步到 BI / ClickHouse / 数据仓库进行长期分析</td></tr>
</tbody>
</table>
</div>
</div>
</section>
<section id="flow">
<div class="section-head">
<span class="num">3</span>
<div>
<h2>角色与核心业务流程</h2>
<p>MVP 用 New API 的用户、分组、Token 组合承载 B2B 客户。</p>
</div>
</div>
<div class="section-body">
<h3>3.1 用户角色</h3>
<div class="table-wrap">
<table>
<thead><tr><th>角色</th><th>说明</th><th>MVP 权限</th></tr></thead>
<tbody>
<tr><td>超级管理员</td><td>甲方内部技术或运营负责人</td><td>管理上游渠道、客户、额度、模型、分流策略、日志与告警</td></tr>
<tr><td>企业客户账号</td><td>B2B 客户侧负责人或技术对接人</td><td>查看本账号 API Key、额度、用量、调用记录</td></tr>
<tr><td>企业开发者</td><td>B2B 客户实际调用人员</td><td>使用分配到的 API Key 调用接口，查看必要的调用说明</td></tr>
<tr><td>运维人员</td><td>甲方或乙方交接人员</td><td>查看系统状态、告警、日志、备份与恢复流程</td></tr>
</tbody>
</table>
</div>
<h3>3.2 核心业务流程</h3>
<div class="table-wrap">
<table>
<thead><tr><th>流程</th><th>MVP 要求</th><th>验收标准</th></tr></thead>
<tbody>
<tr><td>企业开户</td><td>管理员创建企业客户账号或客户分组，配置额度和 API Key</td><td>新建客户后可立即生成可用 API Key</td></tr>
<tr><td>API 调用</td><td>企业客户通过统一接口调用模型</td><td>OpenAI 兼容格式或双方约定格式可正常请求和返回</td></tr>
<tr><td>上游路由</td><td>系统按模型、权重、可用性选择上游渠道商</td><td>日志中可看到每次请求命中的上游</td></tr>
<tr><td>故障切换</td><td>某上游异常时自动切换到可用上游</td><td>模拟上游 5xx、超时、网络失败后，请求可转移到备用上游</td></tr>
<tr><td>基础智能分流</td><td>按权重、优先级、模型匹配、可用性分配流量</td><td>管理后台可调整权重，实际调用分布与配置基本一致</td></tr>
<tr><td>额度控制</td><td>按客户或 API Key 限制额度</td><td>超出额度后拒绝调用并返回明确错误</td></tr>
<tr><td>用量统计</td><td>记录调用次数、Token、费用或等效消耗</td><td>客户维度、Key 维度、上游维度均可查看统计</td></tr>
<tr><td>监控告警</td><td>异常率、延迟、上游不可用触发告警</td><td>人工制造异常后 3 分钟内收到告警</td></tr>
</tbody>
</table>
</div>
</div>
</section>
<section id="features">
<div class="section-head">
<span class="num">4</span>
<div>
<h2>功能需求</h2>
<p>围绕统一入口、多上游、故障切换、分流和客户 Token 管理验收。</p>
</div>
</div>
<div class="section-body">
<h3>4.1 API 中转核心能力 <span class="badge p0">P0</span></h3>
<div class="table-wrap"><table><thead><tr><th>验收项</th><th>判定标准</th></tr></thead><tbody>
<tr><td>统一 API 入口</td><td>对外提供统一 Base URL，客户无需感知 3 家上游差异</td></tr>
<tr><td>OpenAI 兼容接口</td><td>至少支持 Chat Completions 或双方确认的主要调用接口</td></tr>
<tr><td>上游密钥管理</td><td>3 家渠道商密钥可在后台或安全配置中管理，不得写死在代码中</td></tr>
<tr><td>模型映射</td><td>支持将下游模型名映射到不同上游模型名</td></tr>
<tr><td>请求转发</td><td>请求头、请求体、流式响应、错误响应处理稳定</td></tr>
<tr><td>流式输出</td><td>如上游支持 stream，中转站需正确透传流式响应</td></tr>
<tr><td>错误标准化</td><td>上游错误需转换为客户可理解的统一错误格式，并保留内部错误详情日志</td></tr>
</tbody></table></div>
<h3>4.2 上游渠道商管理 <span class="badge p0">P0</span></h3>
<div class="table-wrap"><table><thead><tr><th>验收项</th><th>判定标准</th></tr></thead><tbody>
<tr><td>接入 3 家上游</td><td>3 家渠道商均可独立配置、启停、测试连通性</td></tr>
<tr><td>健康检查</td><td>系统可定时检测上游连通性、延迟、错误率</td></tr>
<tr><td>手动启停</td><td>管理员可手动禁用某个上游，禁用后不再分配新请求</td></tr>
<tr><td>优先级配置</td><td>可设置主用、备用或权重</td></tr>
<tr><td>模型支持差异</td><td>不同上游支持模型不同，系统不得把请求路由到不支持该模型的上游</td></tr>
<tr><td>上游凭据保护</td><td>上游 API Key 不得在前端、日志、错误信息中明文泄露</td></tr>
</tbody></table></div>
<h3>4.3 故障切换与熔断 <span class="badge p0">P0</span></h3>
<div class="table-wrap"><table><thead><tr><th>场景</th><th>MVP 要求</th><th>验收方式</th></tr></thead><tbody>
<tr><td>上游网络超时</td><td>超过配置阈值后自动切换备用上游</td><td>人工配置超时或断网模拟</td></tr>
<tr><td>上游 5xx</td><td>连续失败达到阈值后熔断该上游</td><td>使用 mock 或测试上游返回 500</td></tr>
<tr><td>上游限流</td><td>收到 429 或等效限流错误后触发失败重试、自动禁用或转备用上游</td><td>模拟 429</td></tr>
<tr><td>上游恢复</td><td>被自动禁用或异常的上游可通过健康检查或人工测试恢复使用</td><td>恢复上游后观察重新进入候选池</td></tr>
<tr><td>无可用上游</td><td>返回明确错误，不得卡死或无限重试</td><td>禁用全部上游后测试</td></tr>
<tr><td>手动兜底</td><td>管理员可强制指定上游或关闭某上游</td><td>后台操作后立即生效</td></tr>
</tbody></table></div>
<h3>4.4 基础智能分流 <span class="badge p0">P0</span></h3>
<p>MVP 分流不开发复杂算法，使用 New API 自带的优先级、权重、模型匹配、分组隔离和可用性过滤完成。分流策略必须可解释、可配置、可回滚。</p>
<div class="table-wrap"><table><thead><tr><th>分流策略</th><th>MVP 要求</th></tr></thead><tbody>
<tr><td>权重分流</td><td>例如渠道 A 50%、渠道 B 30%、渠道 C 20%</td></tr>
<tr><td>可用性优先</td><td>已熔断或健康检查失败的上游不得继续分配流量</td></tr>
<tr><td>模型匹配</td><td>按模型支持情况选择可用上游</td></tr>
<tr><td>优先级</td><td>支持配置某上游为优先使用，备用上游只在故障时启用</td></tr>
<tr><td>客户隔离</td><td>通过 Group、用户或 Token 限制不同客户可用模型和渠道</td></tr>
<tr><td>实际分布统计</td><td>管理后台或报表可看到各上游承接的请求量和占比</td></tr>
</tbody></table></div>
<h3>4.5 企业客户与 API Key 管理 <span class="badge p0">P0</span></h3>
<div class="table-wrap"><table><thead><tr><th>验收项</th><th>判定标准</th></tr></thead><tbody>
<tr><td>企业客户创建</td><td>管理员可通过 New API 用户、分组或等效配置创建、禁用、编辑企业客户</td></tr>
<tr><td>API Key 生成</td><td>每个企业客户可生成一个或多个 Token / API Key</td></tr>
<tr><td>Key 禁用</td><td>禁用 Key 后立即无法调用</td></tr>
<tr><td>额度设置</td><td>支持按企业或 Key 设置额度、过期时间或调用限制</td></tr>
<tr><td>速率限制</td><td>支持基础 QPS / RPM 限制，避免单客户打爆系统</td></tr>
<tr><td>调用记录</td><td>可按企业、Key、时间、模型、上游查询调用记录</td></tr>
<tr><td>数据隔离</td><td>企业客户只能看到自己的用量和 Key；如默认界面无法完整满足，MVP 可由管理员代查</td></tr>
</tbody></table></div>
<h3>4.6 管理后台与客户侧最小页面</h3>
<div class="table-wrap"><table><thead><tr><th>模块</th><th>必须能力</th></tr></thead><tbody>
<tr><td>仪表盘</td><td>今日请求量、成功率、平均延迟、错误率、上游状态</td></tr>
<tr><td>上游管理</td><td>3 家渠道商配置、启停、权重、健康状态</td></tr>
<tr><td>客户管理</td><td>用户/分组列表、额度、API Key、状态</td></tr>
<tr><td>调用日志</td><td>请求时间、客户、模型、上游、状态码、耗时、错误原因</td></tr>
<tr><td>告警记录</td><td>可通过外部监控系统查看告警触发时间、类型、恢复时间</td></tr>
<tr><td>客户侧页面</td><td>登录页、API Key 页、用量页、接入说明页</td></tr>
</tbody></table></div>
</div>
</section>
<section id="quality">
<div class="section-head">
<span class="num">5</span>
<div>
<h2>非功能需求</h2>
<p>稳定性、性能、安全和可观测性是 MVP 可运营的硬门槛。</p>
</div>
</div>
<div class="section-body">
<h3>5.1 稳定性与性能 <span class="badge p0">P0</span></h3>
<div class="table-wrap"><table><thead><tr><th>指标</th><th>验收标准</th></tr></thead><tbody>
<tr><td>系统可用性</td><td>试运行期核心 API 可用性不低于 99.5%</td></tr>
<tr><td>API 成功率</td><td>排除客户参数错误后，成功率不低于 99%</td></tr>
<tr><td>故障切换</td><td>单一上游故障时，中转站应在 1 分钟内停止向其分配新请求</td></tr>
<tr><td>500 用户规模</td><td>按 500 个企业用户或开发者账号规模配置，不因用户表规模导致明显卡顿</td></tr>
<tr><td>并发请求</td><td>至少通过 100 并发请求压测，系统自身不崩溃</td></tr>
<tr><td>中转额外延迟</td><td>上游正常情况下，中转站额外增加的中位延迟应小于 300ms</td></tr>
<tr><td>后台查询</td><td>近 7 天调用日志查询 3 秒内返回</td></tr>
<tr><td>长响应</td><td>对流式或长文本响应不得被代理层提前截断</td></tr>
</tbody></table></div>
<h3>5.2 安全与可观测性</h3>
<div class="table-wrap"><table><thead><tr><th>模块</th><th>必须要求</th></tr></thead><tbody>
<tr><td>HTTPS</td><td>生产域名必须启用 HTTPS</td></tr>
<tr><td>密钥保护</td><td>上游 Key、数据库密码、JWT Secret 等必须通过环境变量或密钥文件管理</td></tr>
<tr><td>日志脱敏</td><td>不记录完整 API Key、上游密钥、用户敏感请求内容；如必须记录，需可配置关闭</td></tr>
<tr><td>权限隔离</td><td>管理员、企业客户、普通用户权限隔离</td></tr>
<tr><td>API 请求监控</td><td>请求量、成功率、错误率、平均延迟、P95 延迟</td></tr>
<tr><td>上游状态监控</td><td>每个上游的健康状态、错误率、延迟、熔断次数</td></tr>
<tr><td>系统资源监控</td><td>CPU、内存、磁盘、网络、数据库连接数</td></tr>
<tr><td>告警</td><td>上游不可用、错误率过高、延迟过高、磁盘不足、服务宕机</td></tr>
</tbody></table></div>
</div>
</section>
<section id="ops">
<div class="section-head">
<span class="num">6</span>
<div>
<h2>部署与运维交付</h2>
<p>必须交付可复现部署、备份恢复、监控告警和完整运维文档。</p>
</div>
</div>
<div class="section-body">
<h3>6.1 环境要求</h3>
<div class="table-wrap"><table><thead><tr><th>环境</th><th>用途</th><th>要求</th></tr></thead><tbody>
<tr><td>测试环境</td><td>功能验收和模拟故障</td><td>可随时重置，不影响生产数据</td></tr>
<tr><td>生产环境</td><td>真实客户使用</td><td>HTTPS、监控、备份、告警全部启用</td></tr>
</tbody></table></div>
<h3>6.2 必交文档</h3>
<ol>
<li>服务器配置建议。</li>
<li>域名和 DNS 配置。</li>
<li>Docker Compose 或部署命令。</li>
<li>环境变量清单。</li>
<li>数据库初始化和迁移步骤。</li>
<li>上游渠道商配置步骤。</li>
<li>监控和告警配置步骤。</li>
<li>备份与恢复步骤。</li>
<li>常见故障排查手册。</li>
<li>如何新增第 4 家上游渠道商。</li>
</ol>
<h3>6.3 备份与恢复</h3>
<div class="table-wrap"><table><thead><tr><th>验收项</th><th>判定标准</th></tr></thead><tbody>
<tr><td>自动备份</td><td>数据库至少每日自动备份一次</td></tr>
<tr><td>保留周期</td><td>至少保留最近 7 天备份</td></tr>
<tr><td>恢复演练</td><td>乙方需演示一次从备份恢复到测试环境</td></tr>
<tr><td>配置备份</td><td>关键配置、环境变量模板、部署文件纳入交付物</td></tr>
</tbody></table></div>
</div>
</section>
<section id="acceptance">
<div class="section-head">
<span class="num">7</span>
<div>
<h2>验收维度</h2>
<p>P0 一票否决 + 功能清单 + New API 配置专项验收。</p>
</div>
</div>
<div class="section-body">
<h3>7.1 P0 一票否决项</h3>
<div class="callout danger">以下任一项未通过，则整批不验收。</div>
<ol>
<li>统一 API 入口无法稳定调用。</li>
<li>3 家上游渠道商未全部接通，且无明确原因和替代方案。</li>
<li>单一上游故障时不能自动或手动切换到其他上游。</li>
<li>API Key、上游密钥或客户数据存在明显泄露风险。</li>
<li>调用日志、用量统计、额度扣减核心数据明显不准确。</li>
<li>管理后台无法完成上游管理、客户管理、Key 管理、用量查看。</li>
<li>监控告警未接入，或模拟故障无法触发告警。</li>
<li>无部署文档、无运维交接文档、无备份恢复方案。</li>
<li>存在恶意代码、后门、未知数据外传逻辑。</li>
<li>乙方将 New API 已有能力改写成不可维护的私有实现，且未获得甲方书面确认。</li>
</ol>
<h3>7.2 功能验收清单</h3>
<div class="table-wrap"><table><thead><tr><th>勾选</th><th>验收项</th><th>判定标准</th><th>验收方</th></tr></thead><tbody>
<tr><td>[ ]</td><td>统一 Base URL</td><td>客户可通过统一地址调用</td><td>甲方技术</td></tr>
<tr><td>[ ]</td><td>3 家上游接入</td><td>每家上游可单独测试通过</td><td>甲方技术</td></tr>
<tr><td>[ ]</td><td>模型映射</td><td>至少 3 个主要模型完成映射</td><td>甲方技术</td></tr>
<tr><td>[ ]</td><td>流式响应</td><td>stream 调用可正常透传</td><td>甲方技术</td></tr>
<tr><td>[ ]</td><td>故障切换</td><td>模拟上游异常后自动切换成功</td><td>甲方技术</td></tr>
<tr><td>[ ]</td><td>手动切换</td><td>后台禁用某上游后立即生效</td><td>甲方技术</td></tr>
<tr><td>[ ]</td><td>权重分流</td><td>权重调整后流量分布变化可观察</td><td>甲方技术</td></tr>
<tr><td>[ ]</td><td>企业客户</td><td>可创建、禁用、编辑企业客户</td><td>甲方产品</td></tr>
<tr><td>[ ]</td><td>API Key</td><td>可生成、禁用、复制、调用</td><td>甲方产品</td></tr>
<tr><td>[ ]</td><td>额度限制</td><td>超额后调用被拒绝</td><td>甲方产品</td></tr>
<tr><td>[ ]</td><td>调用日志</td><td>可按客户、Key、模型、上游查询</td><td>甲方运营</td></tr>
<tr><td>[ ]</td><td>监控告警</td><td>故障 3 分钟内触达告警渠道</td><td>甲方运维</td></tr>
</tbody></table></div>
<h3>7.3 New API 配置专项验收清单</h3>
<div class="table-wrap"><table><thead><tr><th>勾选</th><th>验收项</th><th>判定标准</th><th>验收方</th></tr></thead><tbody>
<tr><td>[ ]</td><td>使用生产数据库</td><td>MySQL 或 PostgreSQL 已启用，未使用 SQLite 交付生产</td><td>甲方技术</td></tr>
<tr><td>[ ]</td><td>Redis 或等效缓存</td><td>按生产配置启用 Redis 或说明替代方案</td><td>甲方技术</td></tr>
<tr><td>[ ]</td><td>3 家渠道商配置表</td><td>交付每家渠道商的 Base URL、模型、权重、优先级、启停状态说明</td><td>甲方技术</td></tr>
<tr><td>[ ]</td><td>模型映射表</td><td>交付下游模型名到上游模型名的映射表</td><td>甲方技术</td></tr>
<tr><td>[ ]</td><td>分组与客户映射</td><td>交付企业客户与 New API 用户/分组/Token 的映射规则</td><td>甲方产品</td></tr>
<tr><td>[ ]</td><td>故障演示记录</td><td>提交 5xx、超时、禁用上游、恢复上游的演示记录</td><td>甲方技术</td></tr>
<tr><td>[ ]</td><td>权重压测记录</td><td>提交权重分流压测结果和日志截图</td><td>甲方技术</td></tr>
<tr><td>[ ]</td><td>日志字段核查</td><td>日志中可查客户、Token、模型、上游、状态、耗时、错误</td><td>甲方运营</td></tr>
<tr><td>[ ]</td><td>反代流式配置</td><td>stream / 长响应不被 Nginx、Caddy 或负载均衡截断</td><td>甲方技术</td></tr>
</tbody></table></div>
</div>
</section>
<section id="milestones">
<div class="section-head">
<span class="num">8</span>
<div>
<h2>交付节点与付款建议</h2>
<p>按验收节点释放款项，避免“部署能打开但不可运营”。</p>
</div>
</div>
<div class="section-body">
<div class="timeline">
<div class="step"><b>CP 1 · 20%</b><strong>方案确认</strong><span>选型说明、架构图、部署计划、风险清单、New API 配置清单。</span></div>
<div class="step"><b>CP 2 · 20%</b><strong>基础部署</strong><span>测试环境、统一 API 入口、管理员后台、1 家上游接通。</span></div>
<div class="step"><b>CP 3 · 25%</b><strong>多上游与切换</strong><span>3 家上游接通、故障切换、权重分流、日志、模型映射表。</span></div>
<div class="step"><b>CP 4 · 25%</b><strong>生产就绪</strong><span>生产部署、HTTPS、监控告警、备份恢复、压测报告。</span></div>
<div class="step"><b>尾款 · 10%</b><strong>保修期结束</strong><span>试运行问题闭环、文档交接完成，无遗留 P0/P1 问题。</span></div>
</div>
</div>
</section>
<section id="defects">
<div class="section-head">
<span class="num">9</span>
<div>
<h2>不通过处理</h2>
<p>缺陷等级、修复时限与返工规则。</p>
</div>
</div>
<div class="section-body">
<h3>9.1 缺陷等级</h3>
<div class="table-wrap"><table><thead><tr><th>等级</th><th>定义</th><th>修复时限</th></tr></thead><tbody>
<tr><td><span class="badge p0">P0</span></td><td>API 主链路不可用、密钥泄露、故障无法切换、数据严重错误</td><td>24 小时内修复或给出可执行临时方案</td></tr>
<tr><td><span class="badge p1">P1</span></td><td>部分客户受影响、部分上游异常、统计局部错误、后台核心功能异常</td><td>72 小时内修复</td></tr>
<tr><td><span class="badge cfg">P2</span></td><td>非核心页面问题、体验问题、文档小错误</td><td>7 个工作日内修复</td></tr>
</tbody></table></div>
<h3>9.2 返工规则</h3>
<ol>
<li>P0 缺陷未关闭，不进入下一付款节点。</li>
<li>同一 P0 问题重复出现 2 次以上，甲方有权要求乙方提交根因分析报告。</li>
<li>返工超过 10 个工作日仍无法通过核心验收，甲方有权暂停项目或更换供应商。</li>
<li>乙方提交修复后，甲方有权要求重测相关完整链路，而非只测单点。</li>
</ol>
</div>
</section>
<section id="legal">
<div class="section-head">
<span class="num">10</span>
<div>
<h2>法务与交接条款</h2>
<p>保修、保密、知识产权、开源合规与最终交接清单。</p>
</div>
</div>
<div class="section-body">
<h3>10.1 保修期与保密</h3>
<ol>
<li>生产验收通过后进入 4 周保修期。</li>
<li>保修期内，由乙方交付代码、配置、部署方式导致的 P0 / P1 缺陷，乙方需免费修复。</li>
<li>上游渠道商自身不可用不属于乙方责任，但乙方需保证中转站能按设计完成故障识别、切换、告警和日志记录。</li>
<li>乙方对上游渠道商信息、API Key、客户信息、价格策略、调用数据、系统架构、部署凭据负保密义务。</li>
</ol>
<h3>10.2 知识产权与开源合规</h3>
<ol>
<li>基于开源项目的部分遵守原开源许可证。</li>
<li>乙方为本项目新增的部署脚本、配置、二次开发代码、文档、监控面板配置，验收并结清款项后归甲方使用。</li>
<li>乙方不得在交付后保留生产环境访问权限、数据库权限、服务器权限或上游密钥。</li>
<li>若采用 <code>QuantumNous/new-api</code>，乙方必须在方案确认阶段提示其开源许可证约束，并说明二次开发、部署、对外服务场景下的合规处理方式。</li>
</ol>
<h3>10.3 最终交接清单</h3>
<ol>
<li>源码仓库或二次开发补丁。</li>
<li>部署文件。</li>
<li>环境变量模板。</li>
<li>管理员账号交接清单。</li>
<li>上游渠道商配置说明。</li>
<li>监控面板地址和告警配置。</li>
<li>数据库备份和恢复说明。</li>
<li>压测报告。</li>
<li>故障切换演示记录。</li>
<li>运维手册。</li>
<li>New API 配置清单，包括渠道、模型映射、分组、Token、价格倍率、环境变量。</li>
<li>未来二开建议清单，必须与本次 MVP 交付范围分开列示。</li>
</ol>
<h3>双方确认</h3>
<div class="sign-grid">
<div class="sign-box"><strong>甲方业务负责人</strong>签字 / 日期</div>
<div class="sign-box"><strong>甲方技术负责人</strong>签字 / 日期</div>
<div class="sign-box"><strong>乙方项目负责人</strong>签字 / 日期</div>
<div class="sign-box"><strong>乙方技术负责人</strong>签字 / 日期</div>
</div>
<div class="print-note">企业级 API 中转站 MVP 外包需求与验收标准 · v1.1 · 2026-05-25</div>
</div>
</section>
</div>
</div>
</main>
</body>
</html>