内容
# 双子座 AI 网关 — 本地集群演示
一个完整的演示环境，用于在本地 kind 集群上运行 [双子座 AI 网关](https://github.com/maximhq/bifrost)，包括 Kubernetes MCP 工具集成、Prometheus MCP 可观察性、Ollama 本地模型支持和受控代理工作流。
## 目录
## 工具列表
```
bifrost-k8s-demo
├── 文档
│ ├── 额外的 MCP 服务器指南
│ │ ├── Argo CD MCP 服务器 — 部署指南.md
│ │ ├── AWS MCP 服务器 — 部署和演示指南.md
│ │ ├── Azure MCP 服务器 — 部署和演示指南.md
│ │ ├── Datadog MCP 服务器 — 部署指南.md
│ │ ├── Dynatrace MCP 服务器 — 部署指南.md
│ │ ├── GitHub MCP 服务器 — 部署指南.md
│ │ └── Grafana MCP 服务器 — 部署指南.md
│ ├── bifrost-analysis.md
│ ├── BIFROST_METRICS_QUERY_REFERENCE.md
│ ├── bifrost-mcp-quickref.md
│ ├── bifrost-mcp-rebuild-guide.md
│ ├── demo-guide.md
│ ├── gateway-comparison.md
│ ├── network-flow.svg
│ ├── ollama-bifrost-setup.md
│ ├── Prometheus MCP 服务器 — 部署和演示指南.md
│ ├── prometheus-grafana-bifrost.md
│ ├── README.md
│ ├── SERVICEMONITOR_DEBUG_QUICK_REF.md
│ ├── SESSION_RECAP_2026-05-12-prometheus-bifrost-fix.md
│ └── 截图
│ ├── access-denied-delete-pod.png
│ ├── bifrost-access-control.png
│ ├── bifrost-dashboard.png
│ ├── bifrost-latency-p99.png
│ ├── bifrost-llm-logs.png
│ ├── bifrost-logs.png
│ ├── bifrost-mcp-catalog.png
│ ├── bifrost-total-requests.png
│ ├── cpu-usage-by-pod.png
│ ├── instant-query-up-targets.png
│ ├── owui-basic-chat.png
│ ├── owui-gemma4-triage-response.png
│ ├── owui-model-comparison.png
│ ├── owui-model-selector.png
│ ├── pods-in-namespace-restricted.png
│ └── prometheus-mcp-running.png
├── grafana-dashboards
│ ├── advanced-bifrost-grafana-dashboard.json
│ └── bifrost-grafana-dashboard.json
├── 清单文件
│ ├── bifrost-alerts.yaml
│ ├── bifrost-config.json
│ ├── bifrost-servicemonitor.yaml
│ ├── bifrost-values-dev.yaml
│ ├── bifrost-values-prod.yaml
│ ├── mcp-kubernetes-host-svc.yaml
│ ├── mcp-kubernetes-proxy-kind.yaml
│ ├── namespace.yaml
│ ├── prometheus-mcp-deployment-fixed.yaml
│ └── prometheus-mcp.yaml
├── postman
│ └── bifrost-k8s-mcp_postman_collection.json
├── README.md
└── 脚本
├── bifrost-sim.sh
├── com.local.mcp-kubernetes-sse.plist
├── install.sh
├── start-mcp-server.sh
├── teardown.sh
├── test-prometheus-connectivity.sh
└── warmup-ollama.sh
```
## 前置条件
- kind 集群正在运行（`kind-devops-lab`）
- Helm 3.x
- kubectl 配置为集群
- Anthropic API 密钥
- Ollama 安装在 Mac 上（`brew install ollama`）并设置 `OLLAMA_HOST=0.0.0.0`
- Docker Desktop for Mac
## 快速开始
```bash
# 1. 克隆仓库
git clone https://github.com/simonjday/bifrost-k8s-demo.git
cd bifrost-k8s-demo
# 2. 运行安装脚本
./scripts/install.sh --apply --context kind-devops-lab
# 3. 安装 kubernetes MCP 服务器 LaunchAgent
cp scripts/com.local.mcp-kubernetes-sse.plist ~/Library/LaunchAgents/
launchctl load -w ~/Library/LaunchAgents/com.local.mcp-kubernetes-sse.plist
# 4. 启动端口转发
kubectl -n ai-gateway port-forward svc/bifrost 8080:8080 &
kubectl -n monitoring port-forward svc/kube-prometheus-stack-prometheus 9090:9090 &
kubectl -n monitoring port-forward svc/kube-prometheus-stack-grafana 3000:80 &
kubectl -n argocd port-forward svc/argocd-server 9080:80 &
# 5. 导出虚拟密钥（从 http://localhost:8080 → 密钥）
export KEY_ALL="<your-admin-key>"
export KEY_RESTRICTED="<your-restricted-key>"
# 6. 验证两个 MCP 服务器是否连接（应显示 48 个工具）
curl -s -X POST http://localhost:8080/mcp \
-H "Content-Type: application/json" \
-H "X-Api-Key: $KEY_ALL" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
| jq '[.result.tools[].name] | group_by(split("-")[0]) | map({prefix: .[0] | split("-")[0], count: length})'
# 预期：new_kubernetes_local: 20, prometheus: 28
```
运行安装脚本后，两个 MCP 服务器都已配置。验证它们是否连接：
```bash
curl -s http://localhost:8080/api/mcp/clients | jq '.clients[] | {name, state, tool_count: (.tools | length)}'
# 预期：2 个客户端，均“连接”，20 + 28 个工具
```
**MCP 服务器详情：**
| 服务器 | 类型 | URL | 工具 | 备注 |
|---|---|---|---|---|
| `kubernetes-local` | SSE | `http://mcp-kubernetes-sse.ai-gateway.svc.cluster.local:8811/sse` | 20 | 通过 socat 代理在集群内连接到 Mac（192.168.1.21:8811） |
| `prometheus` | HTTP（可流式传输） | `http://prometheus-mcp.monitoring.svc.cluster.local:8080/mcp` | 28 | 集群内服务，抓取 Prometheus API |
> **Kubernetes MCP 网络：** `mcp-kubernetes-proxy` Deployment（socat）将请求从集群内 DNS 转发到 Mac LaunchAgent。这允许 Bifrost 在不将 Mac MCP 服务器暴露到网络的情况下访问它。
> 设置完成后，前往 **Bifrost UI → 虚拟密钥** 并显式授予每个 MCP 服务器对需要它的每个密钥的访问权限。
---
## 架构
### MCP 服务器
两个 MCP 服务器已注册到 Bifrost，提供 48 个工具：
| 服务器 | 工具 | 连接 | 前缀 |
|---|---|---|---|
| `new_kubernetes_local` | 20 | SSE → `http://192.168.1.21:8811/sse` | `new_kubernetes_local-` |
| `prometheus` | 28 | HTTP（可流式传输）→ 集群内 `:8080/mcp` | `prometheus-` |
### 请求路由
```mermaid
flowchart LR
CU["curl / Postman"]
OW["打开 WebUI"]
BF["Bifrost :8080\n身份验证 · 允许列表 · 日志"]
AN["Anthropic API"]
OL["Ollama :11434"]
KM["kubernetes-mcp-server\n:8811"]
PM["prometheus-mcp\nmonitoring 命名空间"]
CU -->|"MCP 工具调用\nLLM 补全"| BF
OW -->|"仅补全"| BF
BF --> AN
BF --> OL
BF --> KM
BF --> PM
style CU fill:#F0997B,stroke:#993C1D,color:#4A1B0C
style OW fill:#EF9F27,stroke:#854F0B,color:#412402
style BF fill:#85B7EB,stroke:#185FA5,color:#042C53
style AN fill:#B4B2A9,stroke:#5F5E5A,color:#2C2C2A
style OL fill:#97C459,stroke:#3B6D11,color:#173404
style KM fill:#5DCAA5,stroke:#0F6E56,color:#04342C
style PM fill:#a78bfa,stroke:#6d28d9,color:#2e1065
```
### kind 集群网络
```
Mac 主机
├── Ollama (0.0.0.0:11434)
├── kubernetes-mcp-server LaunchAgent (:8811)
│
└── Docker Desktop / kind 集群
├── ai-gateway 命名空间
│ ├── bifrost-0 (:8080)
│ │ ├── → Ollama: 192.168.1.21:11434
│ │ ├── → Kubernetes MCP: http://mcp-kubernetes-sse.ai-gateway.svc.cluster.local:8811/sse
│ │ └── → Prometheus: http://prometheus-mcp.monitoring.svc.cluster.local:8080/mcp
│ └── mcp-kubernetes-proxy (socat)
│ └── 转发到 Mac: 192.168.1.21:8811
│
└── monitoring 命名空间
├── kube-prometheus-stack (Prometheus + Grafana)
└── prometheus-mcp (:8080)
└── 封装 prometheus-mcp-server，使 Prometheus API 可作为 MCP 工具使用
```
**关键网络详情：**
- Bifrost 在 kind 内 **无法** 使用 `localhost` — 必须使用 Mac 的局域网 IP (`192.168.1.21`) 访问 Ollama/MCP 服务器
- Ollama 可通过 Docker Desktop 网关 (`192.168.65.254:11434`) 访问，**而非** Mac 局域网 IP
- 集群内服务通过 DNS 解析（例如 `prometheus-mcp.monitoring.svc.cluster.local`)
---
## Postman 集合
Postman 集合 (`postman/bifrost-k8s-mcp_postman_collection.json`) 包含 **10 个 Bifrost 指标查询：**
### 🔮 双子座 - 网关指标（5 个查询 via MCP）
这些查询调用 Bifrost 的 MCP 接口。由于 Prometheus MCP 服务器二进制文件中的硬编码超时（v0.18.0），这些查询可能会在 pod 重启后超时（参见下面的 **已知问题**）。
- **所有 Bifrost 指标（即时）** — `bifrost_success_requests_total`
- **按提供者划分的请求率（5m）** — `rate(bifrost_success_requests_total[5m])`
- **按提供者划分的错误率（5m）** — `bifrost_error_requests_total`
- **按模型划分的 P95 延迟（5m）** — 模型延迟百分位
- **令牌吞吐量（5m）** — `bifrost_output_tokens_total`
### 🔧 直接 Prometheus 查询（5 个查询 - 推荐用于稳定性）
这些查询直接通过 HTTP API 调用 Prometheus，**完全绕过 MCP 接口**。这些查询始终稳定且不会超时。
- **所有 Bifrost 指标（即时）** — `bifrost_success_requests_total`
- **Bifrost 错误（即时）** — `bifrost_error_requests_total`
- **按提供者划分的成功率（5m 平均值）** — `rate(bifrost_success_requests_total[5m])`
- **令牌吞吐量（5m）** — `rate(bifrost_output_tokens_total[5m])`
- **范围查询：请求随时间变化（1小时）** — 时间序列与可视化
所有查询都包含 **有效可视化**，可解析响应数据并在表格中显示指标。
---
## 测试和指标
通过 Bifrost 生成合成流量以填充 Prometheus 指标：
```bash
bash scripts/bifrost-sim.sh # 40 请求（默认）
bash scripts/bifrost-sim.sh 100 # 自定义请求数
```
在完成前循环约 30 秒后，Prometheus 将抓取数据，然后运行 🔧 **直接 Prometheus 查询** 文件夹中的 Postman。
---
## 打开 WebUI
所有本地 Ollama 模型都可以通过真正的聊天界面通过 [Open WebUI](https://github.com/open-webui/open-webui) 访问。每个消息都通过 Bifrost 路由 - 没有任何内容离开机器。
```bash
docker run -d \
--name open-webui \
-p 3001:8080 \
-e OPENAI_API_BASE_URL=http://host.docker.internal:8080/v1 \
-e OPENAI_API_KEY=$KEY_ALL \
-v open-webui:/app/backend/data \
--restart always \
ghcr.io/open-webui/open-webui:main
```
打开 `http://localhost:3001`。端口 `3000` 保留给 Grafana 使用。
> 使用 `host.docker.internal`（而非 `localhost`）— 这在 Docker 内部分辨率主机，从而使流量通过 Bifrost 正确路由。
---
## 虚拟密钥模型
```mermaid
flowchart LR
subgraph 调用者 ["调用者"]
CU["curl / Postman\n（管理员密钥）"]
CR["curl / Postman\n（受限密钥）"]
end
subgraph Bifrost ["Bifrost :8080"]
subgraph 虚拟密钥 1 ["管理员密钥"]
VK1A["所有 48 个工具\n所有模型"]
end
subgraph 虚拟密钥 2 ["受限密钥"]
VK2A["7 个只读 kubernetes 工具\n仅 llama3.2:3b"]
end
end
subgraph 后端 ["后端"]
AN["Anthropic"]
OL["Ollama"]
KM["kubernetes-mcp"]
PM["prometheus-mcp"]
end
CU --> vk1
CR --> vk2
vk1 --> AN
vk1 --> OL
vk1 --> KM
vk1 --> PM
vk2 -->|"仅 llama3.2:3b"| OL
vk2 -->|"仅 7 个工具"| KM
vk2 -. "❌ qwen2.5-coder:7b 被阻止" .-> BK["403 模型不允许"]
vk2 -. "❌ pods_delete 被阻止" .-> BK2["工具未找到"]
style BK fill:#F09595,stroke:#A32D2D,color:#501313
style BK2 fill:#F09595,stroke:#A32D2D,color:#501313
style VK1A fill:#85B7EB,stroke:#185FA5,color:#042C53
style VK2A fill:#85B7EB,stroke:#185FA5,color:#042C53
```
---
## 集群重启后
每次集群重启时，kind API 服务器端口都会更改。请重新启动 LaunchAgent 以重新加载 kubeconfig：
```bash
# 1. 重新启动 LaunchAgent
launchctl stop com.local.mcp-kubernetes-sse
launchctl start com.local.mcp-kubernetes-sse
# 2. 重新应用端口转发
kubectl -n ai-gateway port-forward svc/bifrost 8080:8080 &
kubectl -n monitoring port-forward svc/kube-prometheus-stack-prometheus 9090:9090 &
kubectl -n monitoring port-forward svc/kube-prometheus-stack-grafana 3000:80 &
# 3. 验证
curl -s -X POST http://localhost:8080/mcp \
-H "Content-Type: application/json" \
-H "X-Api-Key: $KEY_ALL" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
| jq '[.result.tools[].name] | length'
# 预期：48
```
---
## 已知问题
| 问题 | 修复方法 |
|---|---|
| `install.sh` 失败： “command not found: kubectl --context kind-devops-lab” | 使用存储库中的固定版本 — `kubectl_cmd()` 函数替换字符串变量。正确处理条件语句中的单词拆分。 |
| Helm 版本卡住： “cannot reuse a name that is still in use” | `helm uninstall bifrost -n ai-gateway` 在运行安装脚本之前 |
| Prometheus MCP `listen tcp :8080: bind: address already in use` | 清单参数格式错误。必须使用 `command: ["node"]` 入口点和正确的参数数组（无 shell 字符串）。参见 `manifests/prometheus-mcp-deployment-fixed.yaml` |
| Prometheus MCP pod 卡在初始化中 | Supergateway 预期无状态 HTTP 传输。确保部署使用 `--outputTransport streamableHttp` 和 `--web.listen-address=:0`（Prometheus 二进制文件的随机端口）。删除健康检查。 |
| **Prometheus MCP 服务器在 ~5 秒后退出（已知限制）** | **Prometheus MCP 服务器二进制文件中的硬编码超时（v0.18.0）。** 解决方法：使用 **直接 Prometheus 查询** 文件夹中的 Postman（完全绕过 MCP 接口）。直接使用 `curl` 调用 Prometheus 也可以：`curl -s 'http://localhost:9090/api/v1/query?query=bifrost_success_requests_total'` |
| Prometheus 未抓取 Bifrost（ServiceMonitor “无活动目标”） | ServiceMonitor 选择器必须与 **服务标签** 匹配，而不是 pod 标签。修复：`selector: {matchLabels: {app.kubernetes.io/name: bifrost}}` 和标签 `release: kube-prometheus-stack`。参见 [ServiceMonitor 调试快速参考](docs/SERVICEMONITOR_DEBUG_QUICK_REF.md) |
| Prometheus 中未出现 Bifrost 指标 | 修复 ServiceMonitor 选择器后，重启 Prometheus：`kubectl -n monitoring delete pod prometheus-kube-prometheus-stack-prometheus-0`。等待 30 秒抓取。查询测试：`curl -s 'http://localhost:9090/api/v1/query?query=bifrost_success_requests_total'` |
| Prometheus 工具在 Bifrost 重启后返回 0 | 密钥权限缓存已过时。Bifrost UI → 虚拟密钥 → 切换 **此密钥是否激活？** 为 OFF，持续 3 秒，然后为 ON |
| Bifrost 无法在集群内访问 MCP 服务器 | 从 Bifrost pod 测试：`kubectl -n ai-gateway exec bifrost-0 -- wget -v http://mcp-kubernetes-sse.ai-gateway.svc.cluster.local:8811/healthz`。验证 socat 代理是否正在运行：`kubectl -n ai-gateway get pods -l app=mcp-kubernetes-proxy` |
| MCP 客户端在 Bifrost 中显示为 `null` 名称 | 它们仍然功能正常；名称字段用于 UI 标签。如需，可以在 Bifrost 配置 JSON 中显式设置服务器名称 |
| 工具未找到 | 使用正确的前缀：`new_kubernetes_local-`（而非 `kubernetes_local-`），`prometheus-`。运行 `tools/list` 以确认确切名称 |
| Ollama `403 模型不允许` | 允许的密钥中的空允许密钥 - 在 Bifrost UI 中为提供者密钥显式选择 |
| Ollama `404 页面未找到` | 错误的提供者类型（`ollama` 而非 `openai`）或 `/v1` 在基本 URL 中 - 删除它 |
| `qwen2.5-coder:1.5b-base` 返回 400 | 基本模型 - 无聊天补全支持。请改用 `qwen2.5-coder:7b` |
| Open WebUI 显示无模型 | `OPENAI_API_BASE_URL` 必须指向 Bifrost (`:8080`)，而非 Ollama (`:11434`) |
| Anthropic `429 rate_limit_error` | 工具模式消耗大量令牌预算 - 请使用 `claude-haiku-4-5-20251001` 进行 MCP 工具流程 |
| 代理模式未执行工具 | 在 Bifrost UI → MCP → `kubernetes-local` → 编辑中设置 **自动执行工具：`*`**
---
## 关键配置参考
| 项目 | 值 |
|---|---|
| Bifrost UI | `http://localhost:8080` |
| Bifrost 补全 | `POST http://localhost:8080/v1/chat/completions` |
| Bifrost MCP 端点 | `POST http://localhost:8080/mcp` |
| 授权头 | `X-Api-Key: $KEY_ALL` |
| Kubernetes MCP 工具前缀 | `new_kubernetes_local-<tool>` |
| Prometheus MCP 工具前缀 | `prometheus-<tool>` |
| Ollama 模型前缀 | `openai/<modelname>` 例如 `openai/qwen2.5:7b` |
| Ollama 提供者类型 | `openai`（而非 `ollama`） |
| Ollama 基本 URL（kind） | `http://192.168.1.21:11434`（无 `/v1` 后缀） |
| Kubernetes MCP SSE URL | `http://192.168.1.21:8811/sse` |
| Prometheus MCP URL | `http://prometheus-mcp.monitoring.svc.cluster.local:8080/mcp` |
| Prometheus UI | `http://localhost:9090` |
| Grafana | `http://localhost:3000` |
| ArgoCD | `http://localhost:9080` |
| Open WebUI | `http://localhost:3001` |
| x-bf-mcp-include-clients | `new_kubernetes_local`（代理模式头） |
---
## 验证环境
| 组件 | 版本 / 详情 |
|---|---|
| Bifrost | v1.5.0 |
| install.sh | kubectl_cmd() 函数，自动配置 MCP 服务器 |
| kubernetes-mcp-server | 最新（macOS LaunchAgent，端口 8811） |
| prometheus-mcp-server | v0.18.0（ghcr.io/tjhop/prometheus-mcp-server）与 HTTP 传输 |
| Kubernetes | v1.33.x（kind-devops-lab） |
| Docker Desktop | Mac（局域网 IP：192.168.1.21） |
| kube-prometheus-stack | 最新（Helm，Prometheus + Grafana） |
| 指标服务器 | 由 install.sh 安装，pods_top 需要 |
| ServiceMonitor | bifrost（15 秒间隔，抓取 :8080/metrics） |
| PrometheusRule | bifrost（5 个警报规则用于网关健康） |
| Ollama 模型 | qwen2.5:7b, qwen3-coder:30b, llama3.2:3b, qwen2.5-coder:7b, gemma4:latest |
| Anthropic 模型 | claude-haiku-4-5-20251001, claude-sonnet-4-5-20250929 |
| Open WebUI | 最新（ghcr.io/open-webui/open-webui:main） |
---
## 文档
| 文档 | 目的 |
|---|---|
| [docs/demo-guide.md](docs/demo-guide.md) | 主要演示手册 - 11 个演示 |
| [docs/bifrost-mcp-rebuild-guide.md](docs/bifrost-mcp-rebuild-guide.md) | 逐步指南，用于完全集群重建，Bifrost 安装，可观察性和 MCP 设置 |
| [docs/bifrost-mcp-quickref.md](docs/bifrost-mcp-quickref.md) | 快速参考，健康检查，故障排除和常见调试命令 |
| [docs/BIFROST_METRICS_QUERY_REFERENCE.md](docs/BIFROST_METRICS_QUERY_REFERENCE.md) | **全新** 所有 Bifrost 指标和示例 PromQL 查询 |
| [docs/SERVICEMONITOR_DEBUG_QUICK_REF.md](docs/SERVICEMONITOR_DEBUG_QUICK_REF.md) | **全新** ServiceMonitor 故障排除和调试检查清单 |
| [docs/SESSION_RECAP_2026-05-12-prometheus-bifrost-fix.md](docs/SESSION_RECAP_2026-05-12-prometheus-bifrost-fix.md) | **全新** 本次会议的 Prometheus 集成修复和根本原因分析 |
| [docs/Prometheus MCP 服务器 — 部署和演示指南.md](docs/Prometheus%20MCP%20Server%20—%20Deployment%20%26%20Demo%20Guide.md) | Prometheus MCP 设置，ServiceMonitor，Postman 集合 |
| [docs/prometheus-grafana-bifrost.md](docs/prometheus-grafana-bifrost.md) | Prometheus 和 Grafana 中的 Bifrost 指标 - ServiceMonitor，仪表板导入，PromQL 参考 |
| [docs/ollama-bifrost-setup.md](docs/ollama-bifrost-setup.md) | Ollama 配置，模型管理，Claude Desktop 集成 |
| [docs/bifrost-analysis.md](docs/bifrost-analysis.md) | Bifrost 供应商分析，测试场景 |
| [docs/gateway-comparison.md](docs/gateway-comparison.md) | Bifrost 与 LiteLLM 与 Portkey 与 Kong 与 Helicone 比较 |
| [docs/Additional-MCP-Server-Guides/](docs/Additional-MCP-Server-Guides/) | ArgoCD、AWS、Azure、Datadog、Dynatrace、GitHub、Grafana MCP 服务器设置指南 |
---
**最后更新：** 2026 年 5 月 12 日 - Prometheus 集成、稳定性说明和直接查询解决方法
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器