模型网关 minhaozhang/ModelGate

ModelGate

ModelGate 是基于 FastAPI 的 LLM 网关，支持多服务商路由、API key 管理、请求日志记录和仪表盘监控。面向团队和组织，用来集中管理并分发各部门的 AI 模型访问权限。

亮点

- 多服务商路由：Zhipu、DeepSeek、Ollama、Minimax，以及任何兼容 OpenAI 的 API
- 兼容 OpenAI 的代理端点：/v1/chat/completions、/v1/embeddings、/v1/models
- 兼容 Anthropic 的代理端点：/anthropic/v1/messages，支持完整协议转换（流式、工具调用、thinking、cache_control）
- 无需指定服务商的模型访问：API key 直接绑定标准模型；按模型名、别名或 provider/model 调用即可显式路由
- auto 虚拟模型：上下文感知池（每项带 min_ctx/max_ctx），自动挑选服务商，遇到 5xx/网络错误自动回退，并提供路由预览和排除原因
- 每模型上下文硬上限：超限请求直接拒绝，返回原生 context_length_exceeded 错误，让智能体（OpenCode、Claude Code）自动压缩上下文并重试
- 意图分类：根据消息内容自动把请求归类为 coding/writing/testing/design/chat，用于智能路由和日志分析
- 服务商 key 健康评分：滑动窗口（5 分钟）健康分（0–100），路由时优先使用健康的 key
- 服务商 key 优先级：每个 key 可手动设置优先级，用于有序回退，按（priority DESC, health DESC）排序
- 分层并发控制与排队：并发请求最多排队 10s 等一个槽位，而不是直接失败；只有等待队列饱和时才熔断为 429（带 retry-after）
- 服务商多 key 支持，带粘性路由，可按 key 禁用/重新启用
- 服务商 key 回退：遇到 401/403/429 错误时自动尝试下一个 API key
- 用量超限时自动禁用服务商/key；按 reset_at + 60s 定时自动重新启用，避免配额窗口边界竞争
- API key 管理：按 key 控制模型访问权限、设置过期时间、重新生成，以及 bypass_busyness 选项
- RBAC：用户、角色、菜单和细粒度权限，支持双认证（JWT + 旧版 session）
- 审计日志：记录所有管理端写操作
- 定价管理：按服务商-模型设置定价，支持筛选、批量编辑、复制、同步和 CSV 导出
- 请求内容日志：单独的 request_contents 表存放 messages、response、thinking、tool_calls —— 点 Content 按钮懒加载
- 流式请求生命周期跟踪：pending -> success / error / timeout
- 记录上游和下游状态码
- 模型标签：给模型打标签（如 coding、reasoning、vision），用于筛选和基于意图的路由
- MCP 代理：代理远程 MCP 服务器，支持 API key 绑定、管理界面、工具同步、日志和统计
- AI 驱动的模型推荐和耗时建议，供用户参考
- AI 驱动的用量报告生成（导出 DOCX，包含统计、趋势和趣味奖项）
- API key 基于时间的访问规则（时间窗、日期范围、星期限制）
- 管理后台和用户门户的文档分享
- 用户门户：个人统计、请求历史、健康评分、建议、服务商可用性横幅、OpenCode 配置导出
- OpenCode 集成：一行式安装脚本（irm <url> | iex / curl <url> | bash）、按 key 限定模型配置、按模型设置上下文/输出上限、推理强度变体
- 通过 MCP 集成微信 iLink Bot（扫码登录、自动回复、消息持久化）
- 集成 MinIO 做文件存储
- 用 Babel 实现英文 / 中文国际化
- 桌面端和移动端管理界面，支持深色/浅色/黑金主题
- 本地化静态资源（不依赖 CDN）
- 通过可配置的 base path 支持反向代理
- Docker Compose 搭配 Nginx 反向代理和静态文件服务
- 每日统计聚合和 30 天日志归档

截图

管理后台仪表盘

管理后台仪表盘

管理后台监控

管理后台监控

用户仪表盘

用户仪表盘

用户报告

用户报告

移动端仪表盘

移动端仪表盘

快速开始

pip install -r requirements.txt
python -m app.main

默认本地地址：

- 服务器：http://localhost:8765
- 管理后台：http://localhost:8765/admin/home
- 用户门户：http://localhost:8765/user/login

Windows 辅助脚本：start.bat 会提示输入日志级别，并在端口 8765 上重启服务。

Docker

Docker Run

docker build -t your-registry:5002/modelgate:latest .
docker push your-registry:5002/modelgate:latest

docker run -d --name modelgate \
-p 8765:8765 \
-e DATABASE_URL="postgresql+asyncpg://modelgate:password@host:5432/modelgate" \
-e PORT=8765 \
-e ADMIN_USERS="admin:YourPassword" \
-v /opt/modelgate/logs:/app/logs \
-v /opt/modelgate/reports:/app/reports \
-v /opt/modelgate/uploads:/app/uploads/documents \
--restart unless-stopped \
your-registry:5002/modelgate:latest

Docker Compose

仓库里包含 docker-compose.yml，内含 ModelGate + Nginx 服务。Nginx 负责静态文件服务和反向代理，并支持 WebSocket。

docker compose up -d

完整部署说明见 DEPLOY.md。

环境变量

| 变量 | 必填 | 说明 |
| DATABASE_URL | 是 | PostgreSQL 连接字符串 |
| PORT | 否 | 服务端口，默认 8765 |
| ADMIN_USERS | 建议填写 | 管理员账号，格式：user:pass,user:pass |
| ADMIN_USERNAME | 否 | 备用管理员用户名 |
| ADMIN_PASSWORD | 否 | 备用管理员密码 |
| LOG_LEVEL | 否 | DEBUG、INFO、WARNING、ERROR |
| MINIO_ENDPOINT | 否 | MinIO 端点，默认 localhost:9000 |
| MINIO_ACCESS_KEY | 否 | MinIO access key |
| MINIO_SECRET_KEY | 否 | MinIO secret key |
| MINIO_BUCKET | 否 | MinIO bucket 名称，默认 modelgate |
| MINIO_SECURE | 否 | MinIO 是否使用 HTTPS，默认 false |
| ICP_NUMBER | 否 | 落地页展示的 ICP 备案号 |

数据库

CREATE USER "modelgate" WITH PASSWORD 'your_password';
CREATE DATABASE "modelgate" OWNER "modelgate";

Schema：db/schema.sql

应用启动时会执行运行时兼容迁移（例如给 request_logs 添加新列）。

API

兼容 OpenAI 的端点

- POST /v1/chat/completions - 对话补全（流式与非流式）
- POST /v1/embeddings - 文本嵌入
- GET /v1/models - 列出可用模型

兼容 Anthropic 的端点

- POST /anthropic/v1/messages - Anthropic Messages API（流式与非流式）

ModelGate 把 Anthropic 协议请求转成 OpenAI 格式发给上游服务商，再把响应转回来。支持的功能：

- 流式与非流式响应
- 工具调用（function calling），可控制并行工具调用
- 扩展思考，透传 signature
- 缓存控制（在 system、user、assistant、tool_result 块上打 cache_control 标记）
- 系统提示词以结构化内容块形式传入
- 请求日志中记录 inbound_protocol，用于协议层面的分析

模型命名

model-name # standard model or alias (auto-select provider)
provider/model # explicit provider routing
auto # context-aware virtual model pool

示例：glm-5.2、zhipu/glm-4、deepseek/chat、auto

仪表盘

管理端

- /admin/home - 总览、实时统计、服务商可用性横幅、服务商/key 用量明细、趋势
- /admin/config - 服务商、key、模型、绑定、路由、定价、OpenCode 配置
- /admin/api-keys - API key 管理、按 key 控制模型访问、过期时间、重新生成
- /admin/request-logs - 高密度请求日志表，带意图标记、内容查看器、token 缓存明细
- /admin/monitor - 组成分析、热点、响应时间分析
- /admin/reports - AI 生成用量报告并下载 DOCX
- /admin/system-config - 出站 User-Agent 管理、GLM 健康检查模型、系统设置
- /admin/users、/admin/roles - RBAC 用户/角色/菜单管理
- /admin/audit - 所有管理端写操作的审计日志
- /admin/mcp-servers - MCP 服务器管理
- /admin/scheduler-tasks - 定时任务管理，可按任务覆盖 cron
- /admin/m - 移动端管理仪表盘

用户门户

持有 API key 的用户在 /user/login 登录后可访问：

- 个人请求与 token 统计（日/周/月）
- 我的请求历史，支持筛选、分页，以及每条请求的 token/费用明细
- 20 分钟粒度的系统健康分（错误率、延迟、负载、活跃用户）
- AI 模型推荐，附评分理由
- AI 根据每小时用量规律生成的时机建议
- 活跃会话跟踪
- 模型目录，包含上下文/输出上限、定价和多模态信息
- 服务商可用性横幅，显示预计恢复时间
- OpenCode 一行命令安装与配置导出

OpenCode 集成

一行命令安装会把 ModelGate 服务商合并进现有的 ~/.config/opencode/opencode.jsonc（先备份，去掉 JSONC 注释，绝不碰其他服务商）：

Windows (PowerShell)
irm '/opencode/setup.ps1?key=sk-...' | iex

macOS / Linux
curl -fsSL '/opencode/setup.sh?key=sk-...' | bash

生成的配置按 API key 的模型权限划定范围，包含每个模型的上下文/输出上限、可选的上下文硬上限，以及思考模型的 reasoning-effort 变体。GET /v1/models 同样按 key 划定范围。模型可见性跟随 key 权限——服务商被临时禁用（自动熔断）不会把它的模型从客户端配置里移除。

API Key 基于时间的访问规则

API key 可以按一天中的时段、日期范围、星期几来限制。每条规则在每个请求上都会校验：

- 时间窗口 —— start_time / end_time（例如只允许 09:00–18:00）
- 日期范围 —— start_date / end_date
- 星期过滤 —— 限制到一周中的特定几天
- 允许/拒绝语义 —— 每条规则带显式 allowed 标志

微信 iLink Bot（MCP）

ModelGate 内置一个 MCP（Model Context Protocol）服务器，用于微信 iLink Bot 集成，路径为 /weixin：

- 扫码登录流程
- 消息轮询、发送，以及通过内部 LLM 代理自动回复
- 消息持久化到数据库
- 按用户维护会话上下文线程
- 安装说明见 docs/guides/weixin-mcp.md

请求日志

request_logs 存储：API key、服务商、模型、token、延迟、状态、上游/下游 HTTP 状态码、客户端 IP、user agent、intent、requested_model、actual_model、provider_key_label，以及错误详情。

流式请求先以 pending 插入，随后更新为 success、error、timeout 或 cancelled。

超过 30 天的日志会自动归档到 request_logs_history。视图 request_logs_all 联合两张表，查询时对上层透明。

请求内容（单独存储）

请求消息、响应文本、thinking/reasoning 和工具调用存在单独的 request_contents 表里，让 request_logs 保持精简，列表查询更快。

- 懒加载：在日志查看器里点「Content」按钮，通过 GET /admin/api/logs/{id}/content 拉取
- 级联删除：父日志被归档或删除时，内容行自动移除

并发控制

基于分层信号量的速率控制。请求不会快速失败，而是在队列里等一个名额（默认最多 10s，由 MODELGATE_SEMAPHORE_ACQUIRE_TIMEOUT 控制）；等待队列饱和时（>= 限制的 2 倍），请求立即被拒绝，返回 429 + retry-after，以此在高负载下限制队列深度。
1. API key 全局上限 —— 非 bypass_busyness 的 API key，在所有服务商和模型上加起来最多 2 个并发请求
2. API key 服务商-模型上限 —— 按 (api_key, provider_key, model) 限制并发，可随繁忙程度调整；bypass_busyness 的 API key 不受用户侧繁忙并发限制
3. 服务商 key 上限 —— 每个服务商 key 可配置 max_concurrent
4. 系统级上限 —— 全局并发，超出时以 local_rate_limited 拒绝

服务商 key 支持粘性路由（同一个 API key 的请求路由到同一个服务商 key）。

Key 健康评分

每个服务商 key 都有实时健康分（0–100），基于 5 分钟滑动窗口：

| 事件 | 分数影响 |
| Key 被禁用（无效 / 配额超限） | 置为 0 |
| 429/529 限流 | 每次 -15（分数下限为 20，让 key 有机会恢复） |
| 5xx 服务端错误 | 每次 -10 |
| 4xx 客户端错误（非 429） | 每次 -5 |
| 请求成功 | 每 10 次成功 +5 |

健康等级：Excellent（90–100，绿色）/ Good（60–89，蓝色）/ Warning（30–59，黄色）/ Critical（1–29，橙色）/ Unavailable（0，红色）。

pick_api_keys 按健康分排序，所以更健康的 key 优先使用。

Key 优先级

服务商 key 支持手动优先级（priority 字段，默认 0）。pick_api_keys 按 (priority DESC, health DESC) 排序，实现有序的 key 回退（比如总是先试 Key A，再试 Key B）。

模型路由

模型有三种寻址方式：

Standard model name: auto-select provider by priority + health
glm-5.2

Alias: maps to a model, same auto-selection
gpt-4o

Explicit: route to a specific provider
zhipu/glm-4

Auto virtual model: context-aware pool with fallback
auto

当某个名称匹配多个服务商时，路由按 (tag_match DESC, health DESC, priority DESC) 对候选排序：

1. tag_match：模型的 tags 包含请求的 intent → 1，否则 → 0
2. health：服务商 key 的健康分
3. priority：服务商-模型绑定上的手动优先级

如果某个服务商出现 5xx 或网络错误，ModelGate 会自动回退到下一个候选服务商；所有服务商都失败时，返回统一的「no available provider」错误。

auto 虚拟模型在可配置的候选池上路由，支持逐项 min_ctx/max_ctx 过滤（上下文窗口装不下请求的候选会被排除；路由预览会显示排除原因）。

意图分类

请求按消息内容自动归入五种意图之一：

| 意图 | 说明 | 徽章颜色 |
| coding | 编程、调试、代码审查 | 蓝色 |
| writing | 文档、翻译、编辑 | 琥珀色 |
| testing | 单元测试、QA、验证 | 玫瑰色 |
| design | UI/UX、线框图、设计系统 | 紫色 |
| chat | 一般对话（默认） | 灰色 |
分类靠关键词和代码标识符匹配（不调用 LLM），针对 25k 条生产日志做了重写和验证。意图存在 request_logs.intent 里，在日志查看器中显示为彩色徽章。

模型标签

模型可以打标签（逗号分隔），用于过滤和基于意图的路由：

- coding、reasoning、vision、flash 这类标签表示模型擅长的方向
- 标签会和请求意图匹配，用于智能别名路由
- 在管理配置和用户门户中显示为徽章

服务商密钥回退

服务商配置了多个 API 密钥时，当前密钥失败，ModelGate 会自动回退到下一个：

- 可重试错误：HTTP 401（认证）、403（禁止）、429（限流）、529（过载）
- 每次请求都会打乱密钥顺序，保证分布均匀
- 粘性路由优先——有可用的粘性密钥时，只用那个密钥
- 并发受限的密钥会跳过并给出警告，接着试下一个可用密钥
- 回退尝试会带 [KEY FALLBACK] 前缀记录日志

服务商自动禁用与重新启用

- 检测到用量限制或认证错误（配额超限、密钥无效、计费停用）时，自动禁用服务商或服务商密钥，并给出原因
- 禁用状态显示在管理面板和用户门户中（可用性横幅，带预计恢复时间）
- 认证失败（401/403）的服务商密钥立即自动禁用
- 定时任务在 reset_at + 60s 重新启用每个被禁用的服务商/密钥——60s 缓冲避免和上游配额窗口边缘抢跑
- 管理配置页可手动重置

定时任务

Cron 表达式可在 /admin/scheduler-tasks 按任务编辑。

| 任务 | 默认计划 | 说明 |
| 每日聚合 | 00:05 | 把请求数聚合进每日/每小时统计表 |
| MCP 统计聚合 | 00:10 | 聚合 MCP 工具使用统计 |
| 日志归档 | 00:20 | 归档超过 30 天的请求日志 |
| 请求内容备份 | 00:30 | 把昨天的 request_contents 导出为 gzip 并清理数据库 |
| GLM 健康检查 | 05:30 | 每日上游健康探测；失败时通知管理员 |
| 推荐分析 | 08:00 | 每日模型推荐分析 |
| 超时清理 | 每 10 分钟 | 把陈旧的待处理请求（>10 分钟）标记为 timeout |
| 繁忙度计算 | 每 10 分钟 | 计算系统繁忙度等级（1-6） |
| 自动重新启用 | 每 30 分钟 | 重新启用待重置的已禁用服务商密钥和服务商 |

项目结构

modelgate/
├── app/ # Python application package
│ ├── main.py # FastAPI app entrypoint
│ ├── core/ # Config, database models, i18n, path helpers
│ ├── routes/ # FastAPI routers
│ └── services/ # Business logic and proxy runtime
├── web/ # Runtime web assets
│ ├── templates/ # Jinja2 HTML (admin/, user/, public/, components/)
│ ├── static/ # CSS, JS, favicon and static frontend assets
│ ├── assets/ # App image/icon assets
│ └── locales/ # i18n: en, zh
├── deploy/
│ └── nginx/ # nginx.conf for Docker reverse proxy
├── db/
│ ├── schema.sql
│ └── migrations/ # Database maintenance scripts
├── Dockerfile
└── DEPLOY.md

开发

- Python 3.10+ | FastAPI | SQLAlchemy async | PostgreSQL
- 代码检查与格式化：ruff check . && ruff format .
- 类型检查：mypy app --ignore-missing-imports
- i18n 编译：pybabel compile -d web/locales
- 日志：logs/proxy.log、logs/admin.log、logs/error.log

更新日志

发布历史见 CHANGELOG.md；优化与缺陷修复的详细剖析（2026 年 5 月至 8 月）见 docs/CHANGELOG_2026-05_2026-08.md。

商业支持

如需生产级集群部署、定制集成或专项功能开发，请联系：

minhaozhang@henngtiansoft.com

许可证

Apache 2.0