LaPaoPao/BoosAPI
1
0
Fork 0
forked from boos/BoosAPI
Code Pull Requests 1 Activity

feat: enhance response serialization for compact mode

Browse Source 
- Added support for preserving native response.compaction payloads when compact serialization is requested in `serializeResponsesFinalPayload`.
- Implemented serialization of compact mode as `response.compaction` instead of an ordinary response object.
- Introduced a new type `ResponsesFinalSerializationMode` to manage serialization modes.
- Refactored `serializeResponsesFinalPayload` to handle different serialization modes and usage payloads.
- Added tests to ensure correct behavior for compact serialization and preservation of upstream payloads.
- Updated favicon assets and documentation configuration for VitePress.
This commit is contained in:
cita
2026-03-10 01:28:34 +08:00
parent 74d2e559ec
commit cd031b732f
20 changed files with 1387 additions and 90 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/upstream-integration.md
+487
View File
@@ -0,0 +1,487 @@
# 🔌 上游接入指南
本文档详细说明如何将不同类型的 AI 中转站接入 Metapi。
[返回文档中心](./README.md)
---
## 概述
Metapi 支持两大类上游站点：
1. **中转聚合平台** — New API / One API / OneHub / DoneHub / Veloera / AnyRouter / Sub2API 等
2. **官方 API 端点** — OpenAI / Claude (Anthropic) / Gemini (Google) 直连
每种站点类型的接入方式略有不同，本文档按站点类型分别说明。
---
## 🎯 快速接入流程
### 通用步骤
1. **登录管理后台** — 访问 `http://your-metapi-host:4000`，使用 `AUTH_TOKEN` 登录
2. **进入站点管理** — 点击左侧菜单「站点管理」
3. **添加站点** — 点击「添加站点」按钮
4. **填写站点信息** — 根据站点类型填写对应字段（见下文详细说明）
5. **添加账号** — 站点创建后，在站点详情页添加账号凭证
6. **验证连接** — 系统自动验证账号可用性并获取模型列表
---
## 📦 中转聚合平台接入
### New API
**适用平台：** New API 及其衍生版本（Wong-Gongyi、VO-API、Super-API、RIX-API、Neo-API 等）
#### 站点配置
| 字段 | 说明 | 示例 |
|------|------|------|
| **站点名称** | 自定义名称，便于识别 | `我的 New API` |
| **站点 URL** | New API 部署地址（**不含** `/v1` 后缀） | `https://api.example.com` |
| **平台类型** | 选择 `new-api` | - |
| **代理 URL** | （可选）该站点专用代理地址 | `http://proxy.example.com:7890` |
| **使用系统代理** | 是否使用全局 `SYSTEM_PROXY_URL` | 默认关闭 |
#### 账号凭证类型
New API 支持三种凭证类型：
##### 1. 用户名密码登录
- **适用场景：** 有完整账号权限，需要自动签到、余额查询、Token 管理
- **填写方式：**
- 用户名：`your-username`
- 密码：`your-password`
- **自动获取：** 系统自动登录并获取 Access Token 和 API Token
##### 2. Access Token / Session Cookie
- **适用场景：** 已有登录凭证，无需密码
- **填写方式：**
- 在「Access Token」字段填入以下任一格式：
- JWT Token：`eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`
- Session Cookie：`session=MTczNjQxMjM0NXxEdi1CQUFFQ180SUFBUkFCRUFBQVB2LUNBQUVHYzNSeWFXNW5EQThBRFhObGMzTnBiMjVmZEdGaWJHVUdjM1J5YVc1bkRBSUFBQT09fGRlYWRiZWVmMTIzNDU2Nzg5MGFiY2RlZjEyMzQ1Njc4OTBhYmNkZWY=`
- Cookie 字符串：`session=xxx; token=yyy`
- **自动解析：** 系统自动识别凭证类型并提取用户信息
##### 3. API Token（仅代理）
- **适用场景：** 仅用于模型调用，不需要管理功能
- **填写方式：**
- 在「API Token」字段填入：`sk-xxxxxxxxxxxxxx`
- **限制：** 无法使用签到、余额刷新、Token 管理等功能
#### 特殊说明
**User ID 自动探测：** New API 的某些衍生版本（如 Wong-Gongyi、VO-API）需要在请求头中携带 `New-API-User` / `Veloera-User` / `voapi-user` 等字段。Metapi 会自动：
1. 从 JWT Token 中解码 User ID
2. 从 Session Cookie 中提取 User ID（支持 Gob 编码解析）
3. 通过探测常见 ID 范围验证可用性
**防护盾穿透：** 自动处理阿里云盾 / Cloudflare 等 JS 挑战（`acw_sc__v2` / `cdn_sec_tc`），无需手动配置。
---
### One API
**适用平台：** One API 原版及兼容分支
#### 站点配置
| 字段 | 说明 | 示例 |
|------|------|------|
| **站点名称** | 自定义名称 | `One API 主站` |
| **站点 URL** | One API 部署地址 | `https://oneapi.example.com` |
| **平台类型** | 选择 `one-api` | - |
#### 账号凭证
One API 支持与 New API 相同的三种凭证类型（用户名密码 / Access Token / API Token），配置方式相同。
---
### OneHub
**适用平台：** OneHub（One API 增强分支）
#### 站点配置
| 字段 | 说明 | 示例 |
|------|------|------|
| **站点名称** | 自定义名称 | `OneHub 站点` |
| **站点 URL** | OneHub 部署地址 | `https://onehub.example.com` |
| **平台类型** | 选择 `one-hub` | - |
#### 账号凭证
OneHub 继承 One API 的凭证体系，支持用户名密码、Access Token、API Token 三种方式。
**额外功能：** OneHub 支持 Token 分组（`token_group`），Metapi 会自动识别并保留分组信息。
---
### DoneHub
**适用平台：** DoneHub（OneHub 增强分支）
#### 站点配置
| 字段 | 说明 | 示例 |
|------|------|------|
| **站点名称** | 自定义名称 | `DoneHub 站点` |
| **站点 URL** | DoneHub 部署地址 | `https://donehub.example.com` |
| **平台类型** | 选择 `done-hub` | - |
#### 账号凭证
DoneHub 完全兼容 OneHub 的凭证体系，配置方式相同。
---
### Veloera
**适用平台：** Veloera API 网关
#### 站点配置
| 字段 | 说明 | 示例 |
|------|------|------|
| **站点名称** | 自定义名称 | `Veloera 网关` |
| **站点 URL** | Veloera 部署地址 | `https://veloera.example.com` |
| **平台类型** | 选择 `veloera` | - |
#### 账号凭证
Veloera 基于 New API 架构，支持相同的凭证类型。特别注意：
- Veloera 需要 `Veloera-User` 请求头，Metapi 会自动添加
- 支持 Session Cookie 和 JWT Token
---
### AnyRouter
**适用平台：** AnyRouter 通用路由平台
#### 站点配置
| 字段 | 说明 | 示例 |
|------|------|------|
| **站点名称** | 自定义名称 | `AnyRouter 平台` |
| **站点 URL** | AnyRouter 部署地址 | `https://anyrouter.example.com` |
| **平台类型** | 选择 `anyrouter` | - |
#### 账号凭证
AnyRouter 基于 New API 架构，凭证配置方式相同。
---
### Sub2API
**适用平台：** Sub2API 订阅制中转平台
#### 站点配置
| 字段 | 说明 | 示例 |
|------|------|------|
| **站点名称** | 自定义名称 | `Sub2API 订阅站` |
| **站点 URL** | Sub2API 部署地址 | `https://sub2api.example.com` |
| **平台类型** | 选择 `sub2api` | - |
#### 账号凭证
Sub2API 支持：
- **用户名密码登录**
- **Access Token**
- **API Token**（订阅密钥）
配置方式与 New API 相同。
---
## 🌐 官方 API 端点接入
### OpenAI
**适用场景：** 直连 OpenAI 官方 API 或 OpenAI 兼容端点
#### 站点配置
| 字段 | 说明 | 示例 |
|------|------|------|
| **站点名称** | 自定义名称 | `OpenAI 官方` |
| **站点 URL** | OpenAI API 端点（**不含** `/v1` 后缀） | `https://api.openai.com` |
| **平台类型** | 选择 `openai` | - |
| **代理 URL** | （推荐）配置代理以访问 OpenAI | `http://proxy.example.com:7890` |
#### 账号凭证
**仅支持 API Key：**
- 在「API Token」字段填入：`sk-proj-xxxxxxxxxxxxxx`
- 不支持用户名密码登录（OpenAI 无此接口）
#### 功能限制
| 功能 | 支持情况 |
|------|----------|
| 模型列表获取 | ✅ 支持（`/v1/models`） |
| 代理调用 | ✅ 支持 |
| 余额查询 | ❌ 不支持（OpenAI 无公开接口） |
| 自动签到 | ❌ 不适用 |
| Token 管理 | ❌ 不适用 |
---
### Claude (Anthropic)
**适用场景：** 直连 Anthropic Claude API
#### 站点配置
| 字段 | 说明 | 示例 |
|------|------|------|
| **站点名称** | 自定义名称 | `Claude 官方` |
| **站点 URL** | Anthropic API 端点 | `https://api.anthropic.com` |
| **平台类型** | 选择 `claude` | - |
#### 账号凭证
**仅支持 API Key：**
- 在「API Token」字段填入：`sk-ant-api03-xxxxxxxxxxxxxx`
#### 功能限制
| 功能 | 支持情况 |
|------|----------|
| 模型列表获取 | ✅ 支持（内置模型目录） |
| 代理调用 | ✅ 支持（自动转换 OpenAI ⇄ Claude 格式） |
| 余额查询 | ❌ 不支持 |
| 自动签到 | ❌ 不适用 |
| Token 管理 | ❌ 不适用 |
**协议转换：** Metapi 自动处理 OpenAI 格式与 Claude Messages API 格式的双向转换，下游客户端可使用 OpenAI SDK 调用 Claude 模型。
---
### Gemini (Google)
**适用场景：** 直连 Google Gemini API
#### 站点配置
| 字段 | 说明 | 示例 |
|------|------|------|
| **站点名称** | 自定义名称 | `Gemini 官方` |
| **站点 URL** | Gemini API 端点 | `https://generativelanguage.googleapis.com` |
| **平台类型** | 选择 `gemini` | - |
#### 账号凭证
**仅支持 API Key：**
- 在「API Token」字段填入：`AIzaSyxxxxxxxxxxxxxx`
#### 功能限制
| 功能 | 支持情况 |
|------|----------|
| 模型列表获取 | ✅ 支持（`/v1beta/models`） |
| 代理调用 | ✅ 支持（自动转换 OpenAI ⇄ Gemini 格式） |
| 余额查询 | ❌ 不支持 |
| 自动签到 | ❌ 不适用 |
| Token 管理 | ❌ 不适用 |
**协议转换：** Metapi 自动处理 OpenAI 格式与 Gemini `generateContent` API 格式的双向转换。
---
## 🔧 高级配置
### 站点级代理
每个站点可单独配置代理，优先级高于全局 `SYSTEM_PROXY_URL`：
```
站点专用代理 > 全局系统代理 > 直连
```
**配置方式：**
1. 在站点编辑页面填写「代理 URL」字段
2. 格式：`http://proxy-host:port` 或 `socks5://proxy-host:port`
3. 支持 HTTP / HTTPS / SOCKS5 代理
### 站点权重
**全局权重（`global_weight`）：** 影响该站点下所有通道的路由概率。
- 默认值：`1.0`
- 范围：`0.1` ~ `10.0`
- 示例：
- 设置为 `2.0` — 该站点通道被选中的概率翻倍
- 设置为 `0.5` — 该站点通道被选中的概率减半
**配置位置：** 站点编辑页面 → 高级设置 → 全局权重
### 外部签到 URL
**适用场景：** 某些站点的签到接口非标准路径，或需要通过外部服务触发签到。
**配置方式：**
1. 在站点编辑页面填写「外部签到 URL」
2. Metapi 会向该 URL 发送 POST 请求执行签到
3. 请求头自动携带账号凭证
---
## 🔍 站点自动检测
Metapi 支持自动识别站点类型，检测优先级如下：
### 1. URL 特征检测
根据 URL 中的关键字自动识别：
| URL 特征 | 识别为 |
|----------|--------|
| `api.openai.com` | OpenAI |
| `api.anthropic.com` | Claude |
| `generativelanguage.googleapis.com` | Gemini |
| `anyrouter` | AnyRouter |
| `donehub` / `done-hub` | DoneHub |
| `onehub` / `one-hub` | OneHub |
| `veloera` | Veloera |
| `sub2api` | Sub2API |
### 2. 页面标题检测
访问站点首页，解析 `<title>` 标签识别平台类型。
### 3. API 探测
依次尝试各平台的特征接口：
- New API：`/api/status` 返回 `system_name`
- One API：`/api/status` 返回特定结构
- OpenAI：`/v1/models` 返回模型列表
**手动指定：** 如果自动检测失败，可在添加站点时手动选择平台类型。
---
## 📊 账号健康状态
Metapi 自动追踪每个账号的健康状态：
| 状态 | 说明 | 触发条件 |
|------|------|----------|
| `healthy` | 健康 | 最近请求成功，余额充足 |
| `degraded` | 降级 | 部分模型不可用，或余额不足 |
| `unhealthy` | 不健康 | 连续失败，或凭证过期 |
| `disabled` | 已禁用 | 手动禁用或站点禁用 |
**自动恢复：** `unhealthy` 状态的账号会定期重试，成功后自动恢复为 `healthy`。
---
## 🛠️ 故障排查
### 问题：添加站点后无法获取模型列表
**可能原因：**
1. 站点 URL 填写错误（检查是否包含 `/v1` 后缀，应去除）
2. 网络不通（检查代理配置或防火墙）
3. 凭证无效（重新验证账号密码或 Token）
**解决方法：**
- 在站点详情页点击「测试连接」
- 查看「事件日志」中的错误信息
- 检查「代理日志」中的请求详情
### 问题：New API 账号提示「需要 New-API-User 头」
**原因：** 该站点是 New API 衍生版本，需要 User ID。
**解决方法：**
1. Metapi 会自动探测 User ID，通常无需手动配置
2. 如果自动探测失败，可在账号编辑页面的「额外配置」中手动填写：
```json
{
"platformUserId": 12345
}
```
### 问题：签到失败
**可能原因：**
1. 凭证过期（Access Token 有效期到期）
2. 站点签到接口变更
3. 已经签到过（部分站点限制每日一次）
**解决方法：**
- 查看「签到记录」中的失败原因
- 尝试重新登录获取新凭证
- 配置「外部签到 URL」使用备用签到方式
### 问题：余额显示不准确
**原因：** 不同平台的余额单位不同。
**说明：**
- New API 系列：余额单位为「美元」，内部存储为 `quota / 500000`
- OpenAI / Claude / Gemini：官方 API 无余额查询接口，显示为 `N/A`
---
## 📝 最佳实践
### 1. 凭证选择建议
| 场景 | 推荐凭证类型 | 原因 |
|------|-------------|------|
| 个人站点，需要完整功能 | 用户名密码 | 支持自动签到、Token 管理 |
| 共享账号，只读权限 | Access Token | 避免密码泄露 |
| 仅用于模型调用 | API Token | 最小权限原则 |
### 2. 站点命名规范
建议使用清晰的命名规则，便于管理：
```
[平台类型] - [站点特征] - [用途]
```
示例：
- `New API - 主站 - 生产环境`
- `OneHub - 备用 - 测试`
- `OpenAI - 官方 - 高优先级`
### 3. 代理配置策略
- **国内访问 OpenAI / Claude / Gemini：** 必须配置代理
- **国内中转站：** 通常不需要代理
- **海外中转站：** 根据网络情况选择
### 4. 定期维护
- **每周检查：** 账号健康状态、余额预警
- **每月清理：** 禁用长期不可用的站点和账号
- **凭证轮换：** 定期更新 Access Token 和 API Key
---
## 🔗 相关文档
- [配置说明](./configuration.md) — 环境变量与路由参数
- [客户端接入](./client-integration.md) — 下游应用配置
- [常见问题](./faq.md) — 故障排查与优化建议
---
## 💡 提示
- 添加站点后，系统会自动发现可用模型并生成路由表，无需手动配置
- 支持同时接入多个相同类型的站点（如多个 New API 实例）
- 站点禁用后，关联的所有账号和路由通道会自动禁用
- 删除站点会级联删除所有关联账号、Token 和路由配置，请谨慎操作