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

docs: 更新 README.md，优化内容格式和结构

Browse Source
This commit is contained in:
cita
2026-02-28 00:40:13 +08:00
parent 2ecc23730d
commit 20eec09211
1 changed files with 102 additions and 107 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+102 -107
View File
@@ -1,10 +1,5 @@
<div align="center">
<img src="docs/logos/logo-icon-512.png" alt="Metapi Logo" width="120" height="120">
# Metapi
<img src="docs/logos/logo-banner.png" alt="Metapi" width="280">
<img src="docs/logos/logo-full.png" alt="Metapi" width="280">
🔮 **中转站的中转站 — 将分散的 AI 中转站聚合为一个统一网关**
@@ -60,14 +55,14 @@ Metapi 作为这些中转站之上的聚合层，把多个站点统一到 **一
- [AnyRouter](https://anyrouter.top) — 通用路由平台
- [Sub2API](https://github.com/Wei-Shaw/sub2api) — 订阅制中转
| 痛点 | Metapi 怎么解决 |
|------|-----------------|
| 痛点 | Metapi 怎么解决 |
| ------------------------------------- | --------------------------------------------------------------- |
| 🔑 每个站点一个 Key，下游工具配置一堆 | **一个 Key 统一代理**，所有站点的模型自动聚合到 `/v1/*` |
| 💸 不知道哪个站点用某个模型最便宜 | **智能路由** 自动按成本、余额、使用率选最优通道 |
| 🔄 某个站点挂了，手动切换好麻烦 | **自动故障转移**，一个通道失败自动冷却并切到下一个 |
| 📊 余额分散在各处，不知道还剩多少 | **集中看板** 一目了然，余额不足自动告警 |
| ✅ 每天得去各站签到领额度 | **自动签到** 定时执行，奖励自动追踪 |
| 🤷 不知道哪个站有什么模型 | **自动模型发现**，上游新增模型零配置出现在你的模型列表里 |
| 💸 不知道哪个站点用某个模型最便宜 | **智能路由** 自动按成本、余额、使用率选最优通道 |
| 🔄 某个站点挂了，手动切换好麻烦 | **自动故障转移**，一个通道失败自动冷却并切到下一个 |
| 📊 余额分散在各处，不知道还剩多少 | **集中看板** 一目了然，余额不足自动告警 |
| ✅ 每天得去各站签到领额度 | **自动签到** 定时执行，奖励自动追踪 |
| 🤷 不知道哪个站有什么模型 | **自动模型发现**，上游新增模型零配置出现在你的模型列表里 |
---
@@ -90,15 +85,15 @@ Metapi 作为这些中转站之上的聚合层，把多个站点统一到 **一
### 📡 多平台聚合管理
| 平台 | 适配器 | 说明 |
|------|--------|------|
| **New API** | `new-api` | 新一代大模型网关 |
| **One API** | `one-api` | 经典 OpenAI 接口聚合 |
| **OneHub** | `onehub` | One API 增强分支 |
| **DoneHub** | `donehub` | OneHub 增强分支 |
| **Veloera** | `veloera` | API 网关平台 |
| **AnyRouter** | `anyrouter` | 通用路由平台 |
| **Sub2API** | `sub2api` | 订阅制中转平台 |
| 平台 | 适配器 | 说明 |
| ------------------- | ------------- | -------------------- |
| **New API** | `new-api` | 新一代大模型网关 |
| **One API** | `one-api` | 经典 OpenAI 接口聚合 |
| **OneHub** | `onehub` | One API 增强分支 |
| **DoneHub** | `donehub` | OneHub 增强分支 |
| **Veloera** | `veloera` | API 网关平台 |
| **AnyRouter** | `anyrouter` | 通用路由平台 |
| **Sub2API** | `sub2api` | 订阅制中转平台 |
每种平台适配器均支持：账号登录、余额查询、模型枚举、Token 同步、每日签到、用户信息获取等完整生命周期管理。
@@ -136,12 +131,12 @@ Metapi 作为这些中转站之上的聚合层，把多个站点统一到 **一
支持四种通知渠道：
| 渠道 | 说明 |
|------|------|
| **Webhook** | 自定义 HTTP 推送 |
| **Bark** | iOS 推送通知 |
| **Server酱** | 微信 / Telegram 通知 |
| **SMTP 邮件** | 标准邮件通知 |
| 渠道 | 说明 |
| ------------------- | -------------------- |
| **Webhook** | 自定义 HTTP 推送 |
| **Bark** | iOS 推送通知 |
| **Server酱** | 微信 / Telegram 通知 |
| **SMTP 邮件** | 标准邮件通知 |
告警场景覆盖：余额不足预警、站点/账号异常、签到失败、代理请求失败、Token 过期提醒、每日摘要报告。支持告警冷却机制（默认 300 秒），防止相同事件重复通知。
@@ -255,15 +250,15 @@ docker compose pull && docker compose up -d && docker image prune -f
## 📚 文档中心
| 分类 | 链接 | 说明 |
|------|------|------|
| 📖 文档总览 | [docs/README.md](docs/README.md) | 文档导航与索引 |
| 🚀 快速上手 | [docs/getting-started.md](docs/getting-started.md) | 10 分钟启动 |
| 🚢 部署指南 | [docs/deployment.md](docs/deployment.md) | Docker Compose、反向代理、升级回滚 |
| ⚙️ 配置说明 | [docs/configuration.md](docs/configuration.md) | 全部环境变量与路由参数 |
| 分类 | 链接 | 说明 |
| ------------- | ----------------------------------------------------- | -------------------------------------- |
| 📖 文档总览 | [docs/README.md](docs/README.md) | 文档导航与索引 |
| 🚀 快速上手 | [docs/getting-started.md](docs/getting-started.md) | 10 分钟启动 |
| 🚢 部署指南 | [docs/deployment.md](docs/deployment.md) | Docker Compose、反向代理、升级回滚 |
| ⚙️ 配置说明 | [docs/configuration.md](docs/configuration.md) | 全部环境变量与路由参数 |
| 🔌 客户端接入 | [docs/client-integration.md](docs/client-integration.md) | Open WebUI / Cherry Studio / Cursor 等 |
| 🔧 运维手册 | [docs/operations.md](docs/operations.md) | 备份恢复、日志排查、健康检查 |
| ❓ 常见问题 | [docs/faq.md](docs/faq.md) | 常见报错与修复路径 |
| 🔧 运维手册 | [docs/operations.md](docs/operations.md) | 备份恢复、日志排查、健康检查 |
| ❓ 常见问题 | [docs/faq.md](docs/faq.md) | 常见报错与修复路径 |
---
@@ -271,62 +266,62 @@ docker compose pull && docker compose up -d && docker image prune -f
### 基础配置
| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `AUTH_TOKEN` | 管理后台登录令牌（**必须修改**） | `change-me` |
| `PROXY_TOKEN` | 代理 API Bearer Token（**必须修改**） | `change-me-proxy` |
| `PORT` | 服务监听端口 | `4000` |
| `DATA_DIR` | 数据目录（SQLite 数据库） | `./data` |
| `TZ` | 时区 | `Asia/Shanghai` |
| `ACCOUNT_CREDENTIAL_SECRET` | 账号凭证加密密钥 | 默认使用 `AUTH_TOKEN` |
| 变量名 | 说明 | 默认值 |
| ----------------------------- | ------------------------------------------- | ----------------------- |
| `AUTH_TOKEN` | 管理后台登录令牌（**必须修改**） | `change-me` |
| `PROXY_TOKEN` | 代理 API Bearer Token（**必须修改**） | `change-me-proxy` |
| `PORT` | 服务监听端口 | `4000` |
| `DATA_DIR` | 数据目录（SQLite 数据库） | `./data` |
| `TZ` | 时区 | `Asia/Shanghai` |
| `ACCOUNT_CREDENTIAL_SECRET` | 账号凭证加密密钥 | 默认使用 `AUTH_TOKEN` |
### 定时任务
| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `CHECKIN_CRON` | 自动签到 Cron 表达式 | `0 8 * * *` |
| 变量名 | 说明 | 默认值 |
| ------------------------ | -------------------- | ------------- |
| `CHECKIN_CRON` | 自动签到 Cron 表达式 | `0 8 * * *` |
| `BALANCE_REFRESH_CRON` | 余额刷新 Cron 表达式 | `0 * * * *` |
<details>
<summary><strong>智能路由参数</strong></summary>
| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `ROUTING_FALLBACK_UNIT_COST` | 无成本信号时的默认单价 | `1` |
| `BASE_WEIGHT_FACTOR` | 基础权重因子 | `0.5` |
| `VALUE_SCORE_FACTOR` | 性价比评分因子 | `0.5` |
| `COST_WEIGHT` | 路由选择中成本权重 | `0.4` |
| `BALANCE_WEIGHT` | 路由选择中余额权重 | `0.3` |
| `USAGE_WEIGHT` | 路由选择中使用率权重 | `0.3` |
| 变量名 | 说明 | 默认值 |
| ------------------------------ | ---------------------- | ------- |
| `ROUTING_FALLBACK_UNIT_COST` | 无成本信号时的默认单价 | `1` |
| `BASE_WEIGHT_FACTOR` | 基础权重因子 | `0.5` |
| `VALUE_SCORE_FACTOR` | 性价比评分因子 | `0.5` |
| `COST_WEIGHT` | 路由选择中成本权重 | `0.4` |
| `BALANCE_WEIGHT` | 路由选择中余额权重 | `0.3` |
| `USAGE_WEIGHT` | 路由选择中使用率权重 | `0.3` |
</details>
<details>
<summary><strong>通知渠道配置</strong></summary>
| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `WEBHOOK_ENABLED` | 启用 Webhook 通知 | `true` |
| `WEBHOOK_URL` | Webhook 推送地址 | 空 |
| `BARK_ENABLED` | 启用 Bark 推送 | `true` |
| `BARK_URL` | Bark 推送地址 | 空 |
| `SERVERCHAN_ENABLED` | 启用 Server酱 通知 | `true` |
| `SERVERCHAN_KEY` | Server酱 SendKey | 空 |
| `SMTP_ENABLED` | 启用邮件通知 | `false` |
| `SMTP_HOST` | SMTP 服务器地址 | 空 |
| `SMTP_PORT` | SMTP 端口 | `587` |
| `SMTP_SECURE` | 使用 SSL/TLS | `false` |
| `SMTP_USER` / `SMTP_PASS` | SMTP 认证 | 空 |
| `SMTP_FROM` / `SMTP_TO` | 发件/收件人 | 空 |
| `NOTIFY_COOLDOWN_SEC` | 相同告警冷却时间（秒） | `300` |
| 变量名 | 说明 | 默认值 |
| ----------------------------- | ---------------------- | --------- |
| `WEBHOOK_ENABLED` | 启用 Webhook 通知 | `true` |
| `WEBHOOK_URL` | Webhook 推送地址 | 空 |
| `BARK_ENABLED` | 启用 Bark 推送 | `true` |
| `BARK_URL` | Bark 推送地址 | 空 |
| `SERVERCHAN_ENABLED` | 启用 Server酱 通知 | `true` |
| `SERVERCHAN_KEY` | Server酱 SendKey | 空 |
| `SMTP_ENABLED` | 启用邮件通知 | `false` |
| `SMTP_HOST` | SMTP 服务器地址 | 空 |
| `SMTP_PORT` | SMTP 端口 | `587` |
| `SMTP_SECURE` | 使用 SSL/TLS | `false` |
| `SMTP_USER` / `SMTP_PASS` | SMTP 认证 | 空 |
| `SMTP_FROM` / `SMTP_TO` | 发件/收件人 | 空 |
| `NOTIFY_COOLDOWN_SEC` | 相同告警冷却时间（秒） | `300` |
</details>
<details>
<summary><strong>安全配置</strong></summary>
| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| 变量名 | 说明 | 默认值 |
| ---------------------- | ---------------------------- | ------------ |
| `ADMIN_IP_ALLOWLIST` | 管理端 IP 白名单（逗号分隔） | 空（不限制） |
</details>
@@ -339,14 +334,14 @@ docker compose pull && docker compose up -d && docker image prune -f
Metapi 对下游暴露标准 OpenAI / Claude 兼容接口：
| 接口 | 方法 | 说明 |
|------|------|------|
| `/v1/chat/completions` | POST | OpenAI Chat Completions |
| `/v1/messages` | POST | Claude Messages |
| `/v1/completions` | POST | OpenAI Completions（Legacy） |
| `/v1/embeddings` | POST | 向量嵌入 |
| `/v1/images/generations` | POST | 图像生成 |
| `/v1/models` | GET | 获取所有可用模型列表 |
| 接口 | 方法 | 说明 |
| -------------------------- | ---- | ---------------------------- |
| `/v1/chat/completions` | POST | OpenAI Chat Completions |
| `/v1/messages` | POST | Claude Messages |
| `/v1/completions` | POST | OpenAI Completions（Legacy） |
| `/v1/embeddings` | POST | 向量嵌入 |
| `/v1/images/generations` | POST | 图像生成 |
| `/v1/models` | GET | 获取所有可用模型列表 |
请求头携带 `Authorization: Bearer <PROXY_TOKEN>` 即可访问。
@@ -356,11 +351,11 @@ Metapi 对下游暴露标准 OpenAI / Claude 兼容接口：
适用于所有兼容 OpenAI API 的客户端：
| 配置项 | 值 |
|--------|-----|
| 配置项 | 值 |
| ------------------ | ----------------------------------------------------------- |
| **Base URL** | `https://your-domain.com`（客户端一般会自动拼接 `/v1`） |
| **API Key** | 你设置的 `PROXY_TOKEN` 值 |
| **模型列表** | 自动从 `GET /v1/models` 获取 |
| **API Key** | 你设置的 `PROXY_TOKEN` 值 |
| **模型列表** | 自动从 `GET /v1/models` 获取 |
### 已验证兼容的客户端
@@ -403,17 +398,17 @@ location / {
## 🏗️ 技术栈
| 层 | 技术 |
|----|------|
| **后端框架** | [Fastify](https://fastify.dev) — 高性能 Node.js 后端框架 |
| **前端框架** | [React 18](https://react.dev) + [Vite](https://vitejs.dev) |
| **语言** | [TypeScript](https://www.typescriptlang.org) — 端到端类型安全 |
| **样式** | [Tailwind CSS v4](https://tailwindcss.com) — 原子化样式框架 |
| **数据库** | SQLite ([better-sqlite3](https://github.com/WiseLibs/better-sqlite3)) + [Drizzle ORM](https://orm.drizzle.team) |
| **数据可视化** | [VChart](https://visactor.io/vchart) (@visactor/react-vchart) |
| **定时任务** | [node-cron](https://github.com/node-cron/node-cron) |
| **容器化** | Docker (Alpine) + Docker Compose |
| **测试** | [Vitest](https://vitest.dev) |
| 层 | 技术 |
| -------------------- | --------------------------------------------------------------------------------------------------------- |
| **后端框架** | [Fastify](https://fastify.dev) — 高性能 Node.js 后端框架 |
| **前端框架** | [React 18](https://react.dev) + [Vite](https://vitejs.dev) |
| **语言** | [TypeScript](https://www.typescriptlang.org) — 端到端类型安全 |
| **样式** | [Tailwind CSS v4](https://tailwindcss.com) — 原子化样式框架 |
| **数据库** | SQLite ([better-sqlite3](https://github.com/WiseLibs/better-sqlite3)) + [Drizzle ORM](https://orm.drizzle.team) |
| **数据可视化** | [VChart](https://visactor.io/vchart) (@visactor/react-vchart) |
| **定时任务** | [node-cron](https://github.com/node-cron/node-cron) |
| **容器化** | Docker (Alpine) + Docker Compose |
| **测试** | [Vitest](https://vitest.dev) |
---
@@ -445,21 +440,21 @@ npm run db:generate # 生成 Drizzle 迁移文件
### 上游兼容平台
| 项目 | 说明 |
|------|------|
| [New API](https://github.com/QuantumNous/new-api) | 新一代大模型网关，Metapi 的主要上游之一 |
| [One API](https://github.com/songquanpeng/one-api) | 经典 OpenAI 接口聚合管理 |
| [OneHub](https://github.com/MartialBE/one-hub) | One API 增强分支 |
| [DoneHub](https://github.com/deanxv/done-hub) | OneHub 增强分支 |
| [Veloera](https://github.com/Veloera/Veloera) | API 网关平台 |
| 项目 | 说明 |
| ----------------------------------------------- | --------------------------------------- |
| [New API](https://github.com/QuantumNous/new-api) | 新一代大模型网关，Metapi 的主要上游之一 |
| [One API](https://github.com/songquanpeng/one-api) | 经典 OpenAI 接口聚合管理 |
| [OneHub](https://github.com/MartialBE/one-hub) | One API 增强分支 |
| [DoneHub](https://github.com/deanxv/done-hub) | OneHub 增强分支 |
| [Veloera](https://github.com/Veloera/Veloera) | API 网关平台 |
### 参考和使用的项目
| 项目 | 说明 |
|------|------|
| 项目 | 说明 |
| ---------------------------------------------------- | --------------------------------------------------------- |
| [All API Hub](https://github.com/qixing-jk/all-api-hub) | 浏览器扩展版 — 一站式管理中转站账号，Metapi 最初灵感来源 |
| [LLM Metadata](https://github.com/nicepkg/llm-metadata) | LLM 模型元数据库，用于模型描述参考 |
| [New API](https://github.com/QuantumNous/new-api) | 平台适配器参考实现 |
| [LLM Metadata](https://github.com/nicepkg/llm-metadata) | LLM 模型元数据库，用于模型描述参考 |
| [New API](https://github.com/QuantumNous/new-api) | 平台适配器参考实现 |
---
@@ -497,6 +492,6 @@ Metapi 完全自托管，所有数据（账号、令牌、路由、日志）均
**⭐ 如果 Metapi 对你有帮助，给个 Star 就是最大的支持！**
<sub>Built with ❤️ by the AI community</sub>
`<sub>`Built with ❤️ by the AI community`</sub>`
</div>