中转站的中转站 —— 把分散的 AI API 站点聚合为一个统一网关
将你在各处注册的 New API / One API / OneHub / Sub2API 等站点，
汇聚成一个 API Key、一个入口：自动发现模型、智能路由、成本最优。
特性 · 界面 · 快速开始 · 部署与配置 · 迁移 · 限制
AI 生态里基于 New API / One API 系列的聚合中转站越来越多，多站点的余额、模型列表和 API 密钥往往分散在各处。Metapi 是这些中转站之上的元聚合层（Meta-Aggregation Layer）：把多个站点统一到一个入口，下游所有工具（Cursor、Claude Code、Codex、Open WebUI 等）即可无感接入全部模型。
支持的上游：
- 聚合面板：New API、One API、OneHub、DoneHub、Veloera、AnyRouter、Sub2API
- 通用兼容接口：OpenAI / Claude / Gemini 兼容端点，以及
cliproxyapi/ CPA - OAuth 连接：Codex、Claude、Gemini CLI、Antigravity
| 能力 | 说明 |
|---|---|
| 16 个上游适配器 | New API / One API / OneHub / DoneHub / Veloera / AnyRouter / Sub2API / OpenAI / Claude / Gemini / Gemini CLI / Codex / Antigravity / Grok / CLIProxyAPI / SenseTime |
| 统一代理 | OpenAI 与 Claude 双协议：Chat / Responses / Messages / Embeddings / Images / Models / Files，SSE 流式；Messages→Chat 的文本与客户端工具回退支持 JSON/SSE 返回转换 |
| 路由与容错 | 模型自动发现；通道按账号模型可用性绑定；可在设置中开启自动创建缺失模型路由（默认关闭）；重建在后台执行并可追踪结果；按成本/余额/使用权重分配多通道；失败通道自动冷却并重试下一通道；运行时熔断 + half-open 探测 |
| 计费真值 | 四级成本信号（实测 → 账号配置 → models.dev 目录参考价 → 兜底）；使用日志逐请求记录 Token 与成本 |
| 管理 UI | 站点 / 账号 / 路由 / 模型 / 日志 / 告警一站管理，React SPA 预构建后嵌入二进制，无需额外前端服务 |
| 运营自动化 | 定时签到、定时余额刷新、九种告警渠道、模型批量验证、审计日志、实时 QPS 面板 |
| 轻量部署 | 单二进制即跑；SQLite 默认、PostgreSQL 可选；启动自动执行幂等 schema 升级 |
| TS 版无缝接管 | 同数据库 Schema、同环境变量名、同 API 契约；停旧服务、用同样环境变量启动即完成接管 |
仪表盘 — 余额分布、签到与定时任务健康
|
模型市场 — 跨站模型覆盖、品牌与实测指标
|
智能路由 — 多通道概率分配、成本优先选路
|
账号管理 — 多站点多账号、健康状态追踪
|
站点管理 — 上游站点配置与状态一览
|
使用日志 — 代理请求日志与成本明细
|
模型操练场 — 在线对比不同通道输出
|
系统设置 — 全局参数、主题与安全配置
|
三种等价方式，任选其一。启动只需要两个令牌：AUTH_TOKEN（管理后台登录）与 PROXY_TOKEN（下游调用 /v1/* 的 Key）。
发布页提供 Linux / macOS / Windows 预编译二进制，单文件即跑：
curl -fsSL https://github.com/DeliciousBuding/metapi-go/releases/latest/download/install.sh | bash
export AUTH_TOKEN=$(openssl rand -hex 16) # 管理后台登录令牌
export PROXY_TOKEN=sk-$(openssl rand -hex 24) # 下游客户端调用 /v1/* 的 Key
metapi脚本自动校验 SHA-256 并安装到 /usr/local/bin/metapi（默认安装最新发布，METAPI_VERSION 可钉住版本，METAPI_INSTALL_PREFIX 可换安装目录）。Windows 直接从 Releases 下载 metapi-windows-amd64.exe。
稳定使用请选择维护者已公开发布的非预发布 Release，并固定对应的完整版本镜像标签或 digest。latest 会随 master 构建移动，也会被版本 tag 构建更新，不代表稳定发布；合入开发分支也不等于已通过发布验收。
docker run -d --name metapi \
-p 4000:4000 \
-e AUTH_TOKEN=your-admin-token \
-e PROXY_TOKEN=your-proxy-sk-token \
-e ACCOUNT_CREDENTIAL_SECRET=$(openssl rand -hex 32) \
-e TZ=Asia/Shanghai \
-v metapi_data:/app/data \
--restart unless-stopped \
ghcr.io/deliciousbuding/metapi-go:0.21.3镜像版本 0.21.3 是本示例的稳定版本；部署前到 Releases 核对当前已公开发布的版本，并替换为对应的完整版本标签或 digest。
命名卷首次挂载自动继承镜像内属主，开箱即用；改用 bind mount（./data:/app/data）需先在宿主机 chown -R 1001:1001 ./data。Compose 方式（生产硬化配置）：
cp .env.example .env # 填入 AUTH_TOKEN / PROXY_TOKEN / ACCOUNT_CREDENTIAL_SECRET
docker compose -f docker-compose.prod.yml up -d需要 Go 1.26+ 与 Bun 1.x。前端必须先构建——产物经 go:embed 打包进二进制，跳过会报 pattern dist: no matching files found：
git clone https://github.com/DeliciousBuding/metapi-go.git
cd metapi-go
cd web && bun install --frozen-lockfile && bun run build:web && cd ..
go build -o metapi ./cmd/server
AUTH_TOKEN=your-admin-token PROXY_TOKEN=your-proxy-sk-token ./metapicurl http://localhost:4000/health
# {"status":"ok"}
curl http://localhost:4000/ready
# {"status":"ok","database":"ok"}打开 http://localhost:4000，用 AUTH_TOKEN 登录。数据默认存放在 ./data（SQLite）。端口被占用时用 PORT=<端口> 覆盖（默认 4000）。
在界面里添加至少一个上游站点与账号，再为要暴露的模型建一条路由，或在「设置 → 运维 → 任务调度」开启「自动创建模型路由」后重建（默认关闭；通道按账号模型可用性绑定），然后像调用 OpenAI 一样调用 Metapi：
curl http://localhost:4000/v1/chat/completions \
-H "Authorization: Bearer $PROXY_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "<任意已路由模型>",
"messages": [{ "role": "user", "content": "hello" }]
}'Metapi 自动在所有上游站点中选择成本最优、状态健康的通道；通道失败自动冷却并重试下一个。未配置任何路由时返回如实的 503：
{ "error": { "message": "No available channels", "type": "server_error", "request_id": "…" } }Claude 原生格式（/v1/messages）、Responses、Embeddings、Images、/v1/models 与 /v1/files 同样支持；完整端点清单见 HTTP API，客户端接入见 client-integration。
全部配置由环境变量驱动，启动只需两个必填项：
| 变量 | 说明 |
|---|---|
AUTH_TOKEN |
管理后台登录令牌 |
PROXY_TOKEN |
下游客户端调用 /v1/* 的 Key |
常用项：
| 变量 | 默认值 | 说明 |
|---|---|---|
ACCOUNT_CREDENTIAL_SECRET |
回退 AUTH_TOKEN |
上游凭据加密密钥，建议 32+ 字节随机串 |
PORT |
4000 |
监听端口 |
DATA_DIR |
./data |
数据目录（SQLite 库与上传文件） |
DATABASE_URL |
空 | PostgreSQL 连接串；留空使用 SQLite |
LOG_LEVEL |
info |
日志级别：debug / info / warn / error |
CHECKIN_CRON |
0 8 * * * |
签到时间 |
BALANCE_REFRESH_CRON |
0 * * * * |
余额刷新频率 |
完整清单（约 150 项）见 配置参考 与 .env.example。
健康检查：GET /health（liveness）、GET /ready（readiness，检查数据库）；Docker 镜像内置 metapi healthcheck 等价探测 /ready。
深入阅读：
| 文档 | 用途 |
|---|---|
| docs/getting-started.md | 快速上手：安装到第一个代理请求 |
| docs/deployment.md | 反向代理 / TLS / PostgreSQL / 备份 / 升级回滚 |
| docs/configuration.md | 环境变量完整参考 |
| docs/client-integration.md | 客户端接入（Cursor / Claude Code / Codex / Open WebUI） |
| docs/api.md | HTTP API 端点清单 |
| docs/migration.md | TS → Go 迁移（SQLite / PG / MySQL） |
| docs/faq.md | 常见问题 |
| docs/api/routes-inventory.md | 已注册 /api 路由全量清单（由 docs/api_inventory_parity_test.go 与代码对账） |
| docs/configuration.md | 每个环境变量的真实默认值与钳制规则（由 docs/env_parity_test.go 与 .env.example、config/config.go 对账） |
| docs/architecture.md | 分层与所有权边界、一次 /v1 请求经过哪些阶段（改代码或排查归属前读） |
| CHANGELOG.md | 版本变更 |
数据库 Schema 完全一致：停止旧服务，用同样的环境变量启动 Go 版即可，启动时自动执行幂等迁移。SQLite / PostgreSQL 直接接管，MySQL 需先经 TypeScript 版内置迁移转出。Go 镜像以 uid 1001 运行，旧版 root 写入的 bind mount 目录需先 chown -R 1001:1001 ./data（命名卷无需处理）。完整步骤、metapi-migrate 工具与回滚方案见 迁移指南。
- 少量管理端点当前如实返回
501（未实现），清单见 api.md 中的「501 残留」标注。 - 代理上游未配置时返回 503，不做合成成功响应。
- 单进程语义为主；多实例部署的共享语义（Redis 共享 RPM/TPM 准入、PostgreSQL advisory lock）见 FAQ。
make build # 构建
make test # 全部测试（含 -race）
make vet # go vet
make lint # golangci-lint
make vuln # govulncheck 漏洞扫描cd web
bun install
bun run dev # 本地开发（/api /v1 代理到后端 :4000）
bun run typecheck # tsgo 类型检查
bun run test # vitest 全量
bun run build # rsbuild 构建（产物经 go:embed 打包进 Go 二进制）贡献流程（分支模型、PR 门禁）见 CONTRIBUTING.md。
本项目的文档命令按以下口径核实，集中说明一次，正文不再重复：
| 路径 | 核实口径 |
|---|---|
| Release 二进制：安装脚本 → 空数据目录启动 → 健康检查 → 文档路径建站点/账号/路由 → 真实中继 | 端到端实测（v0.19.0） |
| 源码构建：前端构建 → go build → 启动 | 端到端实测 |
| Docker / Compose 命令 | 与仓库 Dockerfile / docker-compose.prod.yml 逐项核对 |
| 未配置路由返回 503、健康检查退出码 | 实测 |
- CONTRIBUTING.md — 分支模型、PR 流程、本地门禁
- SECURITY.md — 漏洞报告（Security Advisory）
- CODE_OF_CONDUCT.md — 社区行为准则
- Metapi (TypeScript) — 原版 Node.js 实现，本项目为其 Go 重写
- New API — 感谢项目及贡献者提供 RelayKit 协议转换库。本项目也参考了 New API 的渠道预设、前后端功能、管理界面和交互设计。
- AxonHub — 渠道类型、平台适配与导入模型的重要参考。
- One API — 经典 OpenAI 接口聚合
GNU AGPLv3（AGPL-3.0-only）。本版本起整体采用 AGPLv3；此前已按 MIT 发布的版本仍保留其原许可。第三方组件及既有版权声明见 第三方声明。
Metapi 完全自托管：所有数据存储在你自己的部署环境中，代理请求仅在你的服务器与上游站点之间直连传输。