From 20eec09211f26866655ad4a719399decd0f99ffb Mon Sep 17 00:00:00 2001 From: cita Date: Sat, 28 Feb 2026 00:40:13 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=20README.md=EF=BC=8C?= =?UTF-8?q?=E4=BC=98=E5=8C=96=E5=86=85=E5=AE=B9=E6=A0=BC=E5=BC=8F=E5=92=8C?= =?UTF-8?q?=E7=BB=93=E6=9E=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 209 ++++++++++++++++++++++++++---------------------------- 1 file changed, 102 insertions(+), 107 deletions(-) diff --git a/README.md b/README.md index 5d80c77..6da83fd 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,5 @@ -
-Metapi Logo - -# Metapi - -Metapi +Metapi 🔮 **中转站的中转站 — 将分散的 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 * * * *` |
智能路由参数 -| 变量名 | 说明 | 默认值 | -|--------|------|--------| -| `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` |
通知渠道配置 -| 变量名 | 说明 | 默认值 | -|--------|------|--------| -| `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` |
安全配置 -| 变量名 | 说明 | 默认值 | -|--------|------|--------| +| 变量名 | 说明 | 默认值 | +| ---------------------- | ---------------------------- | ------------ | | `ADMIN_IP_ALLOWLIST` | 管理端 IP 白名单（逗号分隔） | 空（不限制） |
@@ -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 ` 即可访问。 @@ -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 就是最大的支持！** -Built with ❤️ by the AI community +``Built with ❤️ by the AI community``