forked from boos/BoosAPI
feat: enhance response serialization for compact mode
- 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
@@ -0,0 +1,96 @@
|
||||
import { existsSync, globSync } from 'node:fs';
|
||||
import { resolve } from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import config from './config';
|
||||
|
||||
const getAliasEntry = (aliasConfig: unknown, specifier: string) => {
|
||||
if (!aliasConfig) return undefined;
|
||||
|
||||
if (Array.isArray(aliasConfig)) {
|
||||
return aliasConfig.find(
|
||||
(entry) =>
|
||||
entry &&
|
||||
typeof entry === 'object' &&
|
||||
'find' in entry &&
|
||||
((typeof entry.find === 'string' && entry.find === specifier) ||
|
||||
(entry.find instanceof RegExp && entry.find.test(specifier))),
|
||||
);
|
||||
}
|
||||
|
||||
if (typeof aliasConfig === 'object' && aliasConfig !== null && specifier in aliasConfig) {
|
||||
return {
|
||||
find: specifier,
|
||||
replacement: String((aliasConfig as Record<string, unknown>)[specifier]),
|
||||
};
|
||||
}
|
||||
|
||||
return undefined;
|
||||
};
|
||||
|
||||
const getAlias = (aliasConfig: unknown, specifier: string): string | undefined => {
|
||||
const aliasEntry = getAliasEntry(aliasConfig, specifier);
|
||||
return aliasEntry && typeof aliasEntry === 'object' && 'replacement' in aliasEntry ? String(aliasEntry.replacement) : undefined;
|
||||
};
|
||||
|
||||
const repoRoot = fileURLToPath(new URL('../..', import.meta.url));
|
||||
|
||||
const getExpectedEntry = (hoistedRelativePath: string, pnpmPattern: string) => {
|
||||
const hoistedEntry = resolve(repoRoot, hoistedRelativePath);
|
||||
if (existsSync(hoistedEntry)) return hoistedEntry;
|
||||
|
||||
const [pnpmEntry] = globSync(resolve(repoRoot, pnpmPattern));
|
||||
return pnpmEntry;
|
||||
};
|
||||
|
||||
describe('docs vitepress config', () => {
|
||||
it('ships copied main-app favicon assets for docs', () => {
|
||||
expect(existsSync(resolve(repoRoot, 'docs/public/favicon.png'))).toBe(true);
|
||||
expect(existsSync(resolve(repoRoot, 'docs/public/favicon-64.png'))).toBe(true);
|
||||
expect(existsSync(resolve(repoRoot, 'docs/public/favicon.ico'))).toBe(true);
|
||||
});
|
||||
|
||||
it('ships a fallback favicon.ico for browsers that probe the default path', () => {
|
||||
expect(existsSync(resolve(repoRoot, 'docs/public/favicon.ico'))).toBe(true);
|
||||
});
|
||||
|
||||
it('declares the main-app favicon assets in docs head tags', () => {
|
||||
const iconLinks =
|
||||
config.head?.filter(
|
||||
(entry) =>
|
||||
entry[0] === 'link' &&
|
||||
typeof entry[1] === 'object' &&
|
||||
entry[1] !== null &&
|
||||
'rel' in entry[1] &&
|
||||
(entry[1].rel === 'icon' || entry[1].rel === 'shortcut icon'),
|
||||
) ?? [];
|
||||
|
||||
expect(iconLinks.some((entry) => typeof entry[1] === 'object' && entry[1] !== null && 'href' in entry[1] && entry[1].href === '/favicon.png')).toBe(true);
|
||||
expect(iconLinks.some((entry) => typeof entry[1] === 'object' && entry[1] !== null && 'href' in entry[1] && entry[1].href === '/favicon-64.png')).toBe(true);
|
||||
expect(iconLinks.some((entry) => typeof entry[1] === 'object' && entry[1] !== null && 'href' in entry[1] && entry[1].href === '/favicon.ico')).toBe(true);
|
||||
});
|
||||
|
||||
it('aliases dayjs to the ESM entry for mermaid browser compatibility', () => {
|
||||
const aliasConfig = config.vite?.resolve?.alias;
|
||||
const alias = getAlias(aliasConfig, 'dayjs');
|
||||
const aliasEntry = getAliasEntry(aliasConfig, 'dayjs');
|
||||
|
||||
expect(alias).toBe(getExpectedEntry('node_modules/dayjs/esm/index.js', 'node_modules/.pnpm/dayjs@*/node_modules/dayjs/esm/index.js'));
|
||||
expect(alias && existsSync(alias)).toBe(true);
|
||||
expect(Array.isArray(aliasConfig)).toBe(true);
|
||||
expect(aliasEntry && typeof aliasEntry === 'object' && 'find' in aliasEntry && aliasEntry.find instanceof RegExp).toBe(true);
|
||||
expect(aliasEntry && typeof aliasEntry === 'object' && 'find' in aliasEntry && aliasEntry.find instanceof RegExp && aliasEntry.find.test('dayjs/plugin/duration.js')).toBe(false);
|
||||
});
|
||||
|
||||
it('aliases sanitize-url to a browser-loadable source entry', () => {
|
||||
const alias = getAlias(config.vite?.resolve?.alias, '@braintree/sanitize-url');
|
||||
|
||||
expect(alias).toBe(
|
||||
getExpectedEntry(
|
||||
'node_modules/@braintree/sanitize-url/src/index.ts',
|
||||
'node_modules/.pnpm/@braintree+sanitize-url@*/node_modules/@braintree/sanitize-url/src/index.ts',
|
||||
),
|
||||
);
|
||||
expect(alias && existsSync(alias)).toBe(true);
|
||||
});
|
||||
});
|
||||
@@ -1,14 +1,56 @@
|
||||
import { existsSync, globSync } from 'node:fs';
|
||||
import { resolve } from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import { defineConfig } from 'vitepress';
|
||||
import { withMermaid } from 'vitepress-plugin-mermaid';
|
||||
|
||||
const repoRoot = fileURLToPath(new URL('../..', import.meta.url));
|
||||
const resolveDependencyEntry = (hoistedRelativePath: string, pnpmPattern: string) => {
|
||||
const hoistedEntry = resolve(repoRoot, hoistedRelativePath);
|
||||
if (existsSync(hoistedEntry)) return hoistedEntry;
|
||||
|
||||
const [pnpmEntry] = globSync(resolve(repoRoot, pnpmPattern));
|
||||
return pnpmEntry;
|
||||
};
|
||||
|
||||
const dayjsEsmEntry = resolveDependencyEntry(
|
||||
'node_modules/dayjs/esm/index.js',
|
||||
'node_modules/.pnpm/dayjs@*/node_modules/dayjs/esm/index.js',
|
||||
);
|
||||
const sanitizeUrlSourceEntry = resolveDependencyEntry(
|
||||
'node_modules/@braintree/sanitize-url/src/index.ts',
|
||||
'node_modules/.pnpm/@braintree+sanitize-url@*/node_modules/@braintree/sanitize-url/src/index.ts',
|
||||
);
|
||||
|
||||
if (!dayjsEsmEntry) {
|
||||
throw new Error('Unable to resolve the dayjs ESM entry required by vitepress-plugin-mermaid.');
|
||||
}
|
||||
|
||||
if (!sanitizeUrlSourceEntry) {
|
||||
throw new Error('Unable to resolve the sanitize-url source entry required by vitepress-plugin-mermaid.');
|
||||
}
|
||||
|
||||
export default withMermaid(
|
||||
defineConfig({
|
||||
lang: 'zh-CN',
|
||||
title: 'Metapi 文档',
|
||||
description: 'Metapi 使用文档、FAQ 与维护协作指南',
|
||||
head: [
|
||||
['link', { rel: 'icon', type: 'image/png', sizes: '32x32', href: '/favicon.png' }],
|
||||
['link', { rel: 'icon', type: 'image/png', sizes: '64x64', href: '/favicon-64.png' }],
|
||||
['link', { rel: 'shortcut icon', href: '/favicon.ico' }],
|
||||
],
|
||||
cleanUrls: true,
|
||||
lastUpdated: true,
|
||||
ignoreDeadLinks: true,
|
||||
vite: {
|
||||
resolve: {
|
||||
alias: [
|
||||
{ find: /^dayjs$/, replacement: dayjsEsmEntry },
|
||||
{ find: /^@braintree\/sanitize-url$/, replacement: sanitizeUrlSourceEntry },
|
||||
],
|
||||
},
|
||||
},
|
||||
themeConfig: {
|
||||
siteTitle: 'Metapi Docs',
|
||||
logo: '/logos/logo-icon-512.png',
|
||||
|
||||
@@ -13,10 +13,13 @@ Metapi 暴露标准 OpenAI / Claude 兼容接口，下游客户端通常只需
|
||||
| 配置项 | 值 |
|
||||
|--------|-----|
|
||||
| **Base URL** | 按客户端字段行为填写：会自动补 `/v1` 的字段填 `https://your-domain.com`；要求完整 API URL 的字段填 `https://your-domain.com/v1` |
|
||||
| **API Key** | 你设置的 `PROXY_TOKEN` 值，或创建的下游 API Key |
|
||||
| **API Key** | 你设置的 `PROXY_TOKEN` 值，或创建的[下游 API Key](./configuration.md#下游-api-key-策略) |
|
||||
|
||||
模型列表自动从 `GET /v1/models` 获取，无需手动配置。
|
||||
|
||||
> [!TIP]
|
||||
> 如果不确定客户端是否自动补 `/v1`，先试根域名，报 404 再改成带 `/v1` 的完整路径。
|
||||
|
||||
## 支持的接口
|
||||
|
||||
| 接口 | 方法 | 说明 |
|
||||
@@ -82,9 +85,19 @@ Metapi 暴露标准 OpenAI / Claude 兼容接口，下游客户端通常只需
|
||||
}
|
||||
```
|
||||
|
||||
> 说明：`ANTHROPIC_BASE_URL` 这里填根域名，不要手动拼接 `/v1`；不同版本客户端可能读取 `ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN`，建议同时设置。
|
||||
> 上述变量由 Claude Code 客户端读取，属于客户端行为开关；
|
||||
> `metapi` 服务端无法替代客户端自行设置这些变量，只能处理已经发来的请求。
|
||||
**环境变量说明：**
|
||||
|
||||
| 变量 | 作用 |
|
||||
|------|------|
|
||||
| `ANTHROPIC_BASE_URL` | 指向 Metapi 的根域名，Claude Code 会自动拼接 `/v1/messages` |
|
||||
| `ANTHROPIC_API_KEY` | 认证令牌，填 `PROXY_TOKEN` 值 |
|
||||
| `ANTHROPIC_AUTH_TOKEN` | 部分版本读取此变量而非 `ANTHROPIC_API_KEY`，建议两个都设 |
|
||||
| `CLAUDE_CODE_ATTRIBUTION_HEADER` | 设为 `0` 禁用 Attribution 头，避免部分上游不支持该头导致报错 |
|
||||
| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 设为 `1` 减少非必要请求（遥测等），降低 Token 消耗 |
|
||||
|
||||
> [!IMPORTANT]
|
||||
> `ANTHROPIC_BASE_URL` 填根域名即可，**不要**手动拼接 `/v1`。
|
||||
> 上述变量由 Claude Code 客户端读取，属于客户端行为开关；Metapi 服务端只能处理已经发来的请求。
|
||||
|
||||
### Codex CLI
|
||||
|
||||
@@ -115,7 +128,17 @@ base_url = "https://your-domain.com/v1"
|
||||
|
||||
### 其他客户端
|
||||
|
||||
所有支持 OpenAI API 格式的客户端均可接入，只需找到 Base URL 和 API Key 的配置位置即可：如果客户端会自动补 `/v1`，填根域名；如果字段要求完整 OpenAI API URL，就填 `https://your-domain.com/v1`。
|
||||
所有支持 OpenAI API 格式的客户端均可接入，只需找到 Base URL 和 API Key 的配置位置即可：
|
||||
|
||||
| 你的客户端... | 填法 |
|
||||
|--------------|------|
|
||||
| 有 "Base URL" 字段，会自动补 `/v1` | 填 `https://your-domain.com` |
|
||||
| 有 "OpenAI API URL" 字段，要求完整路径 | 填 `https://your-domain.com/v1` |
|
||||
| 有 "Anthropic" 选项 | 填 `https://your-domain.com`，Metapi 自动处理 `/v1/messages` |
|
||||
| 只能填 API Key | 填 `PROXY_TOKEN` 值即可 |
|
||||
|
||||
> [!TIP]
|
||||
> 不确定选哪种？先用 `/v1/models` 测试连通性，再配置模型。
|
||||
|
||||
## 下游 API Key 策略
|
||||
|
||||
@@ -188,5 +211,7 @@ curl -sS https://your-domain.com/v1/chat/completions \
|
||||
|
||||
## 下一步
|
||||
|
||||
- [配置说明](./configuration.md) — 环境变量详解
|
||||
- [配置说明](./configuration.md) — 环境变量详解与下游 API Key 策略
|
||||
- [上游接入](./upstream-integration.md) — 添加和管理上游平台
|
||||
- [运维手册](./operations.md) — 日志排查与健康检查
|
||||
- [常见问题](./faq.md) — 更多故障排查
|
||||
|
||||
+15
-6
@@ -87,12 +87,19 @@ Metapi 的路由引擎按多因子加权选择最优通道。
|
||||
|
||||
### 路由预设建议
|
||||
|
||||
| 场景 | COST_WEIGHT | BALANCE_WEIGHT | USAGE_WEIGHT |
|
||||
|------|:-----------:|:--------------:|:------------:|
|
||||
| **成本优先** | 0.7 | 0.2 | 0.1 |
|
||||
| **均衡（默认）** | 0.4 | 0.3 | 0.3 |
|
||||
| **稳定优先** | 0.2 | 0.5 | 0.3 |
|
||||
| **轮转均匀** | 0.1 | 0.1 | 0.8 |
|
||||
| 场景 | COST_WEIGHT | BALANCE_WEIGHT | USAGE_WEIGHT | 说明 |
|
||||
|------|:-----------:|:--------------:|:------------:|------|
|
||||
| **成本优先** | 0.7 | 0.2 | 0.1 | 适合预算敏感场景，总是选最便宜的通道 |
|
||||
| **均衡（默认）** | 0.4 | 0.3 | 0.3 | 兼顾成本、余额和负载均衡，推荐大多数用户 |
|
||||
| **稳定优先** | 0.2 | 0.5 | 0.3 | 适合生产环境，优先选余额充足的通道避免中断 |
|
||||
| **轮转均匀** | 0.1 | 0.1 | 0.8 | 适合测试场景，尽量让每个通道都被使用到 |
|
||||
|
||||
**调参建议：**
|
||||
|
||||
- 如果某个站点总是被选中导致余额很快耗尽 → 调高 `BALANCE_WEIGHT`
|
||||
- 如果你有几个很便宜的站点想优先用 → 调高 `COST_WEIGHT`
|
||||
- 如果你想让请求均匀分散到所有站点 → 调高 `USAGE_WEIGHT`
|
||||
- 如果你需要对特定项目偏好某个站点 → 使用[下游 API Key 的 `siteWeightMultipliers`](#下游-api-key-策略) 而非调全局权重
|
||||
|
||||
## 代理日志保留
|
||||
|
||||
@@ -209,3 +216,5 @@ Metapi 的路由引擎按多因子加权选择最优通道。
|
||||
|
||||
- [部署指南](./deployment.md) — Docker Compose 与反向代理
|
||||
- [客户端接入](./client-integration.md) — 对接下游应用
|
||||
- [上游接入](./upstream-integration.md) — 添加和管理上游平台
|
||||
- [运维手册](./operations.md) — 备份、日志与健康检查
|
||||
|
||||
+11
-8
@@ -87,6 +87,11 @@ docker compose up -d
|
||||
> - Windows 下常见路径是 `%APPDATA%\Metapi\data` 和 `%APPDATA%\Metapi\logs`。
|
||||
> - 如果你要把本机其他客户端接到桌面版内置后端，先到日志里查当前端口，不要写死 `4000`。
|
||||
|
||||
> [!WARNING]
|
||||
> **端口冲突排障：** 如果桌面版启动后报端口被占用，可能是 `4310..4399` 范围内的端口全被其他应用占用了。
|
||||
> - 设置环境变量 `METAPI_DESKTOP_SERVER_PORT=<指定端口>` 固定到一个空闲端口
|
||||
> - 或关闭占用这些端口的应用后重启 Metapi Desktop
|
||||
|
||||
> [!NOTE]
|
||||
> 服务器部署统一推荐 Docker / Docker Compose，不再提供裸 Node.js 的 Release 压缩包。
|
||||
|
||||
@@ -127,15 +132,9 @@ npm run dev
|
||||
|
||||
### 步骤 2：添加账号
|
||||
|
||||
首先前往你想添加的公益站，进入下图界面：
|
||||
|
||||
|
||||
|
||||
进入 **账号管理**，为每个站点添加已注册的账号：
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
- 填入用户名和访问凭证
|
||||
|
||||
@@ -143,7 +142,7 @@ npm run dev
|
||||
|
||||
- 系统会自动登录并获取余额信息
|
||||
|
||||
|
||||
|
||||
|
||||
- 启用自动签到（如站点支持）
|
||||
|
||||
@@ -163,6 +162,10 @@ npm run dev
|
||||
|
||||
- 系统会自动发现模型并生成路由规则
|
||||
- 可以手动调整通道的优先级和权重
|
||||
- 关于路由权重参数调优，参考 [配置说明 → 智能路由](./configuration.md#智能路由)
|
||||
|
||||
<!-- TODO: 补充路由管理截图 -->
|
||||
<!--  -->
|
||||
|
||||
### 步骤 5：验证代理
|
||||
|
||||
|
||||
+43
-8
@@ -30,12 +30,35 @@ cp -r data/ data-backup-$(date +%Y%m%d)/
|
||||
|
||||
### 方式二：数据库原生备份（MySQL / PostgreSQL）
|
||||
|
||||
如果当前运行库已经切到 MySQL / Postgres，请使用数据库自己的备份工具或云快照，例如 `mysqldump`、`pg_dump`、RDS 快照等。
|
||||
如果当前运行库已经切到 MySQL / Postgres，请使用数据库自己的备份工具或云快照。
|
||||
|
||||
**MySQL 备份示例：**
|
||||
|
||||
```bash
|
||||
# 全量导出（替换为你的实际连接信息）
|
||||
mysqldump -h <HOST> -u <USER> -p<PASSWORD> metapi > metapi-backup-$(date +%Y%m%d).sql
|
||||
|
||||
# 自动备份（crontab，每天凌晨 3 点）
|
||||
0 3 * * * mysqldump -h <HOST> -u <USER> -p<PASSWORD> metapi | gzip > /path/to/backups/metapi-$(date +\%Y\%m\%d).sql.gz
|
||||
```
|
||||
|
||||
**PostgreSQL 备份示例：**
|
||||
|
||||
```bash
|
||||
# 全量导出
|
||||
pg_dump -h <HOST> -U <USER> -d metapi -F c -f metapi-backup-$(date +%Y%m%d).dump
|
||||
|
||||
# 自动备份（crontab，每天凌晨 3 点，使用 .pgpass 免交互密码）
|
||||
0 3 * * * pg_dump -h <HOST> -U <USER> -d metapi -F c -f /path/to/backups/metapi-$(date +\%Y\%m\%d).dump
|
||||
```
|
||||
|
||||
**云托管数据库：** RDS、PlanetScale、Neon 等可直接使用平台的自动快照功能。
|
||||
|
||||
建议：
|
||||
- 升级、迁移、执行「重新初始化系统」前先做一次库级备份
|
||||
- 备份对象是当前 metapi 正在使用的运行库，而不只是本地 `data/`
|
||||
- 恢复后重启 Metapi 一次，确认它重新连接到了正确的运行库
|
||||
- 建议保留最近 7~30 天的备份，定期清理过期文件
|
||||
|
||||
### 方式三：应用内导出
|
||||
|
||||
@@ -104,11 +127,16 @@ npm run dev
|
||||
|
||||
| 关键词 | 含义 | 处理方式 |
|
||||
|--------|------|----------|
|
||||
| `auth failed` | 上游站点鉴权失败 | 检查账号凭证是否过期 |
|
||||
| `no available channel` | 路由无可用通道 | 检查 Token 是否同步、通道是否被冷却 |
|
||||
| `notify failed` | 通知发送失败 | 检查通知渠道配置 |
|
||||
| `auth failed` | 上游站点鉴权失败 | 检查账号凭证是否过期，系统会自动尝试重登录 |
|
||||
| `no available channel` | 路由无可用通道 | 检查 Token 是否同步、通道是否被冷却；可在路由页查看冷却状态 |
|
||||
| `channel cooling` | 通道进入冷却期 | 通道在请求失败后自动冷却 10 分钟，期间不会被路由选中；无需干预，会自动恢复 |
|
||||
| `upstream 429` | 上游限流 | 该上游站点触发了速率限制；路由引擎会自动切换其他通道，冷却期后重试 |
|
||||
| `upstream 5xx` | 上游服务器错误 | 上游站点临时不可用，路由引擎会自动故障转移到其他通道 |
|
||||
| `notify failed` | 通知发送失败 | 检查 [通知渠道配置](./configuration.md#通知渠道) |
|
||||
| `checkin failed` | 签到失败 | 检查账号状态和站点连通性 |
|
||||
| `balance refresh failed` | 余额刷新失败 | 检查账号凭证 |
|
||||
| `balance refresh failed` | 余额刷新失败 | 检查账号凭证，可能需要重新登录 |
|
||||
| `proxy timeout` | 代理请求超时 | 上游响应过慢；检查网络延迟或考虑切换其他通道 |
|
||||
| `token expired` | Token 过期 | 系统会自动尝试续签；若反复出现，手动刷新 Token |
|
||||
|
||||
## 健康检查
|
||||
|
||||
@@ -168,9 +196,14 @@ curl -sS http://localhost:4000/v1/chat/completions \
|
||||
|
||||
### 清理缓存并重建路由
|
||||
|
||||
- 「设置 → 清除缓存并重建路由」会清空模型发现缓存、自动路由和自动通道，再后台触发一次模型刷新与路由重建
|
||||
- 「TokenRoutes → 重建路由」适合在调整账号、Token、路由规则后手动重新生成自动路由
|
||||
- 如果 `GET /v1/models`、路由列表或选择概率明显滞后，优先执行这一操作
|
||||
当模型列表（`GET /v1/models`）、路由列表或选择概率明显滞后时，使用以下操作：
|
||||
|
||||
| 操作 | 位置 | 适用场景 |
|
||||
|------|------|----------|
|
||||
| **清除缓存并重建路由** | 设置 → 清除缓存并重建路由 | 全局刷新：清空模型发现缓存、自动路由和自动通道，后台触发模型刷新与路由重建 |
|
||||
| **重建路由** | TokenRoutes → 重建路由 | 局部刷新：调整账号、Token、路由规则后手动重新生成自动路由 |
|
||||
|
||||
优先使用「重建路由」做局部刷新，问题持续时再用全局清除。
|
||||
|
||||
### 批量操作
|
||||
|
||||
@@ -206,3 +239,5 @@ curl -sS http://localhost:4000/v1/chat/completions \
|
||||
|
||||
- [常见问题](./faq.md) — 常见报错与修复
|
||||
- [配置说明](./configuration.md) — 环境变量详解
|
||||
- [上游接入](./upstream-integration.md) — 平台特定的连接与排障
|
||||
- [客户端接入](./client-integration.md) — 下游客户端对接
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 4.3 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 4.3 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 1.4 KiB |
@@ -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 和路由配置，请谨慎操作
|
||||
|
||||
Reference in New Issue
Block a user