discover · compare · collections · requirements · contribute · feed · watching · stats · help with your tokens
ZiChuanLan/meta-gateway · source

Snapshot 0 · 2026-11-04T12:47:28Z · Go · MIT
Content fingerprint
7c0f80675686009e203a44e3a124200c3f1840c1e8ab25a9e7fc2f5ea2f3a653
GitHub description at capture

OpenAI-compatible multi-channel LLM relay gateway with admin console
README at capture

<div align="center">

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/marketing/hero-dark.png">
  <source media="(prefers-color-scheme: light)" srcset="docs/marketing/hero-light.png">
  <img src="docs/marketing/hero-light.png" alt="Meta Gateway — 多通道 AI 中继网关" width="100%">
</picture>

<p>
  <a href="https://github.com/ZiChuanLan/meta-gateway/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/ZiChuanLan/meta-gateway/ci.yml?branch=master&style=flat-square&labelColor=2F3646"></a>
  <a href="https://zichuanlan.github.io/meta-gateway/"><img alt="Docs" src="https://img.shields.io/github/deployments/ZiChuanLan/meta-gateway/github-pages?style=flat-square&label=docs&labelColor=2F3646"></a>
  <a href="https://hub.docker.com/r/zichuanlan/meta-gateway"><img alt="Docker Pulls" src="https://img.shields.io/docker/pulls/zichuanlan/meta-gateway?style=flat-square&labelColor=2F3646&color=2496ED"></a>
  <a href="https://github.com/ZiChuanLan/meta-gateway/releases"><img alt="Stable release" src="https://img.shields.io/github/v/release/ZiChuanLan/meta-gateway?style=flat-square&label=stable&labelColor=2F3646&color=4F6BF0"></a>
  <a href="https://github.com/ZiChuanLan/meta-gateway/releases"><img alt="Beta release" src="https://img.shields.io/github/v/release/ZiChuanLan/meta-gateway?style=flat-square&label=beta&include_prereleases&labelColor=2F3646&color=E8B93E"></a>
  <a href="https://github.com/ZiChuanLan/meta-gateway/stargazers"><img alt="Stars" src="https://img.shields.io/github/stars/ZiChuanLan/meta-gateway?style=flat-square&labelColor=2F3646&color=E8B93E"></a>
  <a href="https://github.com/ZiChuanLan/meta-gateway/blob/master/LICENSE"><img alt="License" src="https://img.shields.io/github/license/ZiChuanLan/meta-gateway?style=flat-square&labelColor=2F3646&color=3DA639"></a>
  <a href="https://linux.do"><img alt="linux.do" src="https://img.shields.io/badge/linux.do-Community-F97316?style=flat-square&labelColor=2F3646"></a>
</p>

<p>
  <img alt="Go" src="https://img.shields.io/badge/Go-1.26%2B-4F6BF0?style=flat-square&logo=go&logoColor=white&labelColor=2F3646">
  <img alt="SQLite" src="https://img.shields.io/badge/SQLite-embedded-4F6BF0?style=flat-square&logo=sqlite&logoColor=white&labelColor=2F3646">
  <img alt="Platform" src="https://img.shields.io/badge/Platform-amd64%20%7C%20arm64-4F6BF0?style=flat-square&logo=linux&logoColor=white&labelColor=2F3646">
  <img alt="Protocol" src="https://img.shields.io/badge/Protocol-OpenAI%20%2F%20Anthropic%20%2F%20Gemini-4F6BF0?style=flat-square&labelColor=2F3646">
  <a href="https://github.com/ZiChuanLan/meta-gateway/issues"><img alt="Issues" src="https://img.shields.io/github/issues/ZiChuanLan/meta-gateway?style=flat-square&logo=github&logoColor=white&label=Issues&labelColor=2F3646&color=4F6BF0"></a>
</p>

<p>
  <a href="https://zichuanlan.github.io/meta-gateway/"><strong>📖 完整文档</strong></a> ·
  <a href="https://zichuanlan.github.io/meta-gateway/guide/quickstart-docker">快速开始</a> ·
  <a href="https://zichuanlan.github.io/meta-gateway/reference/env-vars">配置全表</a> ·
  <a href="https://zichuanlan.github.io/meta-gateway/reference/admin-api">API 全表</a>
</p>

</div>

> [!TIP]
> **在线体验** · <https://mg.015201314.xyz> — 用户名 `admin`，登录密码 `123456`
>
> 公开演示环境，请勿存放生产敏感密钥。控制台内置 **经典 / 现代** 双外观与明暗主题，登录后即可切换体验。

---

## 它是什么

下游工具越接越多（Cursor、Claude Code、Cherry Studio、Open WebUI），而上游分散在各类站点（New API、One API、官方接口与各路代理）。各站模型命名各异、额度分散、容易单点故障。

**Meta Gateway** 是自托管的多通道聚合中枢：所有上游统一挂载，下游只需配置**一个接口地址、一个访问令牌**。

架构上坚持**透明 pass-through** —— 不改写请求语义、不注入提示词、不伪造响应。

| 痛点 | 做法 |
| :--- | :--- |
| **密钥繁多易混乱** | 统一中继代理，单一下游令牌即可穿透访问全站上游模型 |
| **渠道故障易中断** | 失败自动进入冷却并秒级转移备用通道，恢复后无感回归 |
| **模型命名不统一** | 跨渠道识别与一键别名归一，对外屏蔽上游命名碎片化 |
| **协议不兼容** | OpenAI / Anthropic / Gemini 原生格式自动双向互译 |
| **上游不是标准 OpenAI 形态** | 渠道级端点覆盖与请求/响应字段映射，支持任意路径透传 |
| **额度浪费需打卡** | 内置定时签到引擎，原生支持 Session Cookie 与保活 |
| **上游只能靠猜** | 站点探针读站点自己的公开状态页（零 token），公告与价格变动同步到总览 |
| **业务隔离需求** | 模型路由分组，为不同客户端精准分配专属通道集 |

> 完整的功能说明、每条规则的边界与踩坑记录都在[文档站](https://zichuanlan.github.io/meta-gateway/)。本文件只做门面。

---

## 界面预览

<img src="docs/marketing/feature-appearance.png" alt="经典与现代两种外观同框" width="100%">

**经典 Classic** 紧凑信息密度，适合长时间盯盘运维 ｜ **现代 Modern** 卡片式工作台，层次更舒展

| 数据总览 | 上游连接 |
| :---: | :---: |
| [![数据总览：区间请求、成本、Token 用量与成功率](docs/screenshots/dashboard.png)](docs/screenshots/dashboard.png) | [![上游连接：渠道、模型数、延迟与健康度](docs/screenshots/channels.png)](docs/screenshots/channels.png) |
| <sub>区间请求 / 成本 / Token / 成功率一行读完；下面是渠道健康矩阵、上游站点消息与最近请求流</sub> | <sub>每个站点的渠道、模型数、延迟与健康度；右侧是这条连接的实时画像与探测结果</sub> |
| **模型路由** | **模型工作台** |
| [![模型路由：成员优先级、权重与别名归一](docs/screenshots/models.png)](docs/screenshots/models.png) | [![模型工作台：图像生成与编辑、文字流式对话](docs/screenshots/workbench.png)](docs/screenshots/workbench.png) |
| <sub>成员优先级与权重负载、别名归一；一键挂载能提供该模型的渠道，重命名后仍搜得到</sub> | <sub>图像生成与编辑、文字流式对话，都走真实转发链路（这张图就是网关自己生成的）</sub> |
| **令牌管理** | **日志观测** |
| [![令牌管理：额度、分组绑定与调用统计](docs/screenshots/keys.png)](docs/screenshots/keys.png) | [![日志观测：延迟分布、失败率与代理审计](docs/screenshots/logs.png)](docs/screenshots/logs.png) |
| <sub>独立额度（token / 金额）、路由分组绑定与调用统计</sub> | <sub>延迟分布、失败率与代理审计，可核到真实上游地址与上游凭据</sub> |
| **运行参数** | **资产交换** |
| [![运行参数：路由与转发、健康与自动化、数据与运维](docs/screenshots/settings.png)](docs/screenshots/settings.png) | [![资产交换：拓扑快照、加密导入导出与 WebDAV 备份](docs/screenshots/exchange.png)](docs/screenshots/exchange.png) |
| <sub>路由与转发、健康与自动化、数据与运维三段，改完即时生效</sub> | <sub>拓扑快照、加密导入导出与 WebDAV 备份，可作为站点间迁移的中间格式</sub> |

> 截图均为 1440×960 视口（2× 像素密度），来自一份演示数据（虚构站点、模型与流量），不是真实部署；点击任意图片可打开原始文件。

---

## 快速开始

```yaml
# docker-compose.yml
services:
  meta-gateway:
    image: zichuanlan/meta-gateway:${IMAGE_TAG:-latest}   # latest = 正式版；beta = 预发布
    container_name: meta-gateway
    restart: unless-stopped
    ports:
      - "4100:4100"
    volumes:
      - ./data:/data
    environment:
      ADMIN_TOKEN: ${ADMIN_TOKEN:?ADMIN_TOKEN required}
      MASTER_KEY: ${MASTER_KEY:?MASTER_KEY 32-char required}
      METRICS_TOKEN: ${METRICS_TOKEN:-mg-metrics-secret}
```

```bash
export ADMIN_TOKEN=$(openssl rand -hex 16)
export MASTER_KEY=$(openssl rand -hex 16)   # 32 字符加密主密钥
docker compose up -d
curl --fail http://127.0.0.1:4100/readyz
```

访问 `http://localhost:4100/console/`，输入 `ADMIN_TOKEN` 进入控制台。

<img src="docs/screenshots/login.png" alt="控制台登录页" width="100%">

管理员与团队成员共用同一个登录入口，按账号角色隔离权限；支持暗色 / 明亮双主题，另有独立的移动端布局。

> [!IMPORTANT]
> **`MASTER_KEY` 必须随数据库一起备份、一起迁移。** 换一个 `MASTER_KEY` 打开同一个库，所有已存凭据都解不开。

### AI 一键部署

在用 Cursor / Claude Code / Windsurf / ChatGPT 这类助手？把下面整段发给它，它自己检测宿主机环境、生成高强度密钥、写 compose 并拉起容器。

<details>
<summary>展开提示词，复制</summary>

```markdown
请帮我在当前服务器/本机部署 Meta Gateway（高性能 AI 统一中继网关）。
项目仓库：https://github.com/ZiChuanLan/meta-gateway

部署要求：
1. 采用 Docker Compose 方式部署，使用官方镜像 `zichuanlan/meta-gateway:latest`；
2. 宿主机服务端口映射为 4100（即 `4100:4100`）；
3. 数据持久化挂载至当前目录下的 `./data` 目录（映射容器内 `/data`）；
4. 环境变量要求：
   - 自动生成一个高强度的 `ADMIN_TOKEN` 作为后台控制台登录密码；
   - 自动生成一个 32 位的强随机字符串作为 AES 密钥 `MASTER_KEY`（必须 ≥ 32 字符）；
   - 开启自动重启策略 `restart: unless-stopped`；
5. 生成完整的 `docker-compose.yml` 文件后，自动执行 `docker compose up -d` 命令拉起容器；
6. 检查容器运行状态，并在控制台清晰输出：
   - 控制台 WebUI 访问地址（`http://<IP或localhost>:4100/console`）；
   - API 中继调用地址（`http://<IP或localhost>:4100/v1`）；
   - 随机生成的 ADMIN_TOKEN 密码与 MASTER_KEY 明文记录。
```

</details>

部署完成后自己核对三件事：`curl --fail http://127.0.0.1:4100/readyz` 成功、**`MASTER_KEY` 已单独记录**、`./data` 属主可写（容器以 UID/GID `10001` 运行）。详见[AI 一键部署](https://zichuanlan.github.io/meta-gateway/guide/ai-deploy-prompt)。

单行 `docker run`、源码构建、从 v3 升级到 V4 —— 见[文档站 / 入门](https://zichuanlan.github.io/meta-gateway/guide/)。

---

## 接入

把 API Base URL 指向网关，API Key 填管理后台颁发的**下游令牌**：

```bash
curl http://localhost:4100/v1/chat/completions \
  -H "Authorization: Bearer <你的下游令牌>" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-flash","messages":[{"role":"user","content":"Hello!"}]}'
```

| 客户端类别 | Base URL | 传输协议 |
| :--- | :--- | :--- |
| Cursor / VS Code / Cherry Studio | `http://<网关>:4100/v1` | OpenAI 兼容 |
| Claude Code 等原生客户端 | `http://<网关>:4100/v1` | Anthropic Messages |
| Open WebUI / LibreChat | `http://<网关>:4100/v1` | OpenAI 兼容 |

---

## 文档

| 章节 | 内容 |
| :--- | :--- |
| [入门](https://zichuanlan.github.io/meta-gateway/guide/) | 定位、**核心概念**（站点/渠道/路由/令牌四层）、部署与升级 |
| [接入](https://zichuanlan.github.io/meta-gateway/clients/) | 下游协议、作用域与配额、流式与 SSE 语义、图像接口 |
| [上游](https://zichuanlan.github.io/meta-gateway/upstream/) | 站点与渠道、基础 URL 与端点规则、协议映射、站点探针 |
| [路由](https://zichuanlan.github.io/meta-gateway/routing/) | 选型算法、会话粘性、故障转移、冷却熔断、模型归一 |
| [计费](https://zichuanlan.github.io/meta-gateway/billing/) | 两层单价链、阶梯价与时段价、配额与用量账单 |
| [团队](https://zichuanlan.github.io/meta-gateway/team/) | 个人／团队模式、成员、团队码、第三方登录 |
| [控制台](https://zichuanlan.github.io/meta-gateway/console/) | 信息架构、主题包、交互约定 |
| [运维](https://zichuanlan.github.io/meta-gateway/operations/) | 架构、部署与反代、备份恢复、保留策略、**故障排查** |
| [插件](https://zichuanlan.github.io/meta-gateway/plugins/) | sidecar 协议、安装、配置与拦截钩子 |
| [参考](https://zichuanlan.github.io/meta-gateway/reference/) | **由代码生成**的配置、接口、错误码与数据结构全表 |

参考层由 `tools/docsgen` 从代码生成，CI 会校验生成结果与代码一致 —— 代码改了而文档没跟上，构建就红。

---

## 常见问题

<details>
<summary><strong>Q: 它和普通的反向代理或 Nginx 有什么本质区别？</strong></summary>

Nginx 是纯传输层转发，无法理解 AI 模型的语义。Meta Gateway 运行在应用协议层：它能够**解析 OpenAI / Claude / Gemini 的请求与流式包**，完成多协议互译、识别每个 Token 的用量进行精确扣费、在流式发生中断时秒级触发备用通道故障转移，并具备跨站模型聚合与自动探活机制。
</details>

<details>
<summary><strong>Q: 节点出现网络抖动时，会不会直接把正常渠道误禁用？</strong></summary>

不会。网关设有渐进式弹性防护机制：偶尔超时会先进入**平滑冷却期**并在后台执行静默健康探活，只有当连续失败触发阈值且探活全军覆没时才会触发通道保护。
</details>

<details>
<summary><strong>Q: 数据与凭证安全如何保证？</strong></summary>

1. 所有上游 API Key 在入库前均由 `MASTER_KEY` 执行 AES-GCM 高强度加密，仅在出站转发前在内存中瞬时解密；
2. 控制台 `ADMIN_TOKEN` 仅保留在浏览器当前会话内存中，不存 Cookie、不入 URL；
3. 出站流量全局搭载 SSRF 防护墙，严格拦截环回私网与非法重定向。
</details>

<details>
<summary><strong>Q: 模型的价格、上下文窗口和模态是从哪来的？会覆盖我手工填的值吗？</strong></summary>

优先级是**人工校正 > 外部目录同步 > 内置推断**。同步写入遵循「只填空位」：已有的值不会被覆盖，把字段清空即代表「要求下次同步重填」。人工改过的模型能力会被标记为 `manual` 并**永久冻结**。
</details>

<details>
<summary><strong>Q: 经典控制台和现代工作空间有什么区别？我只想换个明暗呢？</strong></summary>

两套是完整界面包，切换后布局、过场与控件风格整体变化。**明暗与配色是彼此独立的两个维度**——可以只切明暗、只换配色，也可以整套换包，互不干扰。偏好存在浏览器本地。
</details>

---

## Star History

<div align="center">

<a href="https://star-history.com/#ZiChuanLan/meta-gateway&Date">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=ZiChuanLan/meta-gateway&type=Date&theme=dark" />
    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=ZiChuanLan/meta-gateway&type=Date" />
    <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=ZiChuanLan/meta-gateway&type=Date" width="100%">
  </picture>
</a>

</div>

---

## 贡献

欢迎提 Issue 与 Pull Request。报问题时附上**网关版本、相关配置片段与日志**会省很多来回。

```bash
# 后端：构建 → 静态检查 → 单测（gofmt -l 应无输出）
go build ./... && go vet ./... && go test ./...
gofmt -l .

# 前端（在 web/ 目录下）
npm run lint && npm run typecheck && npm test -- --run && npm run build

# 文档站（在 docs/ 目录下）
go run ./tools/docsgen && npm ci && npm run build
```

提交前请确认这几条（CI 会逐条卡住）：

- **`gofmt` 干净** —— 流水线里有 `test -z "$(gofmt -l .)"`，格式化不通过会直接失败；
- 后端 `go vet ./...` 与 `go test ./...` 全绿（CI 另跑一遍 `go test -race ./...`，本地跑需要 cgo 与 gcc）；
- 前端 `lint` / `typecheck` / `test` / `build` 四项全绿；
- 新增数据库迁移时，同步更新 `store_test.go` 里的迁移数量断言；
- 改了代码里任何被 `docs/reference` 覆盖的事实（环境变量、端点、错误码、迁移、连接类型、供应商 profile），跑一遍 `go run ./tools/docsgen` 并提交结果。

涉及界面改动的 PR，请顺手贴一张改前 / 改后截图（本项目同时维护**经典 / 现代**两套界面包，两边都要看一眼）。

更细的约定见 [CONTRIBUTING.md](CONTRIBUTING.md)。

---

## 许可

以 **MIT License** 发布 —— 可自由商用、修改与再分发，只需保留原始版权声明。详见 [LICENSE](LICENSE)。

仓库本身不附带任何上游密钥或用户数据；实例内的凭证均由 `MASTER_KEY` 加密后存放在本地 SQLite 中。

致谢：
[LinuxDo](https://linux.do)、Metapi、Axonhub、allapihub、cc-switch、CPA、newapi、sub2api

---

<div align="center">

<p>
  <a href="https://github.com/ZiChuanLan/meta-gateway/stargazers"><img alt="Stars" src="https://img.shields.io/github/stars/ZiChuanLan/meta-gateway?style=social"></a>
</p>

<sub><b>Meta Gateway</b> — 让分散的 AI 算力与模型，汇聚于极致优雅的统一入口 · <a href="#top">返回顶部</a></sub>

</div>