427 lines
13 KiB
Markdown
427 lines
13 KiB
Markdown
# 博闻 Bowen · MCP Web Search
|
||
|
||
博闻是魂镜的 MCP 联网搜索服务，支持多搜索引擎、多 API 密钥智能轮询、两级缓存和双传输模式。
|
||
|
||
> 文化命名出自《礼记·中庸》「博闻强识而让」，与辰正、一炁等同属魂镜文化命名体系。工程路径保留 `mcp/web-search`。
|
||
|
||
---
|
||
|
||
## 架构概览
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
subgraph L1["① 传输层"]
|
||
ST["stdio<br/>stdin/stdout JSON-RPC"]
|
||
SSE["HTTP SSE<br/>/sse + /messages"]
|
||
HTTP["简化 HTTP<br/>/tools/list + /tools/call"]
|
||
end
|
||
|
||
subgraph L2["② 核心处理器"]
|
||
H["Handler<br/>传输层共享"]
|
||
C["Cache Manager<br/>L1 LRU → L2 Redis"]
|
||
end
|
||
|
||
subgraph L3["③ 负载均衡"]
|
||
LB["Load Balancer"]
|
||
KP["KeyPool<br/>EWMA 动态权重"]
|
||
CB["Circuit Breaker<br/>closed / open / half-open"]
|
||
end
|
||
|
||
subgraph L4["④ 搜索提供商"]
|
||
T[Tavily]
|
||
B[Bing]
|
||
V[Brave]
|
||
end
|
||
|
||
subgraph L5["⑤ 可观测性"]
|
||
M["Prometheus Metrics<br/>7 指标"]
|
||
S["/status + /health"]
|
||
A["管理 API<br/>enable / disable / clear"]
|
||
end
|
||
|
||
ST --> H
|
||
SSE --> H
|
||
HTTP --> H
|
||
H --> C
|
||
H --> LB
|
||
LB --> KP
|
||
KP --> CB
|
||
LB --> T
|
||
LB --> B
|
||
LB --> V
|
||
H --> M
|
||
H --> S
|
||
H --> A
|
||
```
|
||
|
||
### 核心特性
|
||
|
||
| 特性 | 说明 |
|
||
| ------ | ------ |
|
||
| **多 Provider** | Tavily、Bing、Brave 三家搜索，统一响应格式 |
|
||
| **多 Key 轮询** | 每 Provider 可配多个 API Key，按 EWMA 动态权重（延迟×成功率）自动排序 |
|
||
| **熔断器** | 每个 Key 独立熔断（closed → open → half-open），失败 key 自动隔离并恢复探测 |
|
||
| **故障转移** | 一个 Key 失败自动换 Key，一个 Provider 耗尽自动切其他 Provider |
|
||
| **双传输** | HTTP SSE（远程 Client 直连）+ stdio（子进程集成），由 `--port` / `--stdio` CLI 标志决定 |
|
||
| **两级缓存** | L1 内存 LRU（毫秒级）+ L2 Redis（可选，跨实例共享），L2 命中自动升温到 L1 |
|
||
| **配置热重载** | fsnotify 监听 YAML 变更，动态调整 provider 启用/禁用、缓存 TTL、重试次数，无需重启 |
|
||
| **管理 API** | 运行时启用/禁用 provider、清空缓存、查询密钥状态 |
|
||
| **SearchMode** | `first`（首个成功返回，默认低延迟）+ `merge`（并发搜所有引擎，URL 去重排序） |
|
||
| **可观测性** | 暗色风格 HTML 监控面板（`:9090`）、Prometheus 指标（`:9090/metrics`）、结构化彩色日志 |
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
### 前置条件
|
||
|
||
- Go 1.22+
|
||
- 至少一个搜索 API Key（Tavily / Bing / Brave）
|
||
- （可选）Redis 用于二级缓存
|
||
|
||
#### 环境变量快速配置
|
||
|
||
```bash
|
||
# 必填——搜索 API Key（逗号分隔支持多 key 轮询）
|
||
export TAVILY_API_KEYS="tvly-key1,tvly-key2"
|
||
export BRAVE_API_KEYS="brave-key1"
|
||
```
|
||
|
||
完整环境变量见项目根目录 `.env.example` 中的「博闻」段。
|
||
|
||
### 启动
|
||
|
||
```bash
|
||
# HTTP SSE 模式（供 MCP Client 远程连接，或供灵台注册为工具）
|
||
go run ./cmd/server --port 8080
|
||
|
||
# stdio 模式（供 Claude Desktop / Cursor 等 MCP Client 子进程集成）
|
||
go run ./cmd/server --stdio
|
||
|
||
# 指定 YAML 配置文件（可选，不传则自动探测 config/mcp/web-search.yaml）
|
||
go run ./cmd/server --config ../../config/mcp/web-search.yaml
|
||
```
|
||
|
||
### 验证
|
||
|
||
```bash
|
||
# 存活探针
|
||
curl http://localhost:8080/health
|
||
# → {"status":"ok"}
|
||
|
||
# 系统状态
|
||
curl http://localhost:8080/status
|
||
# → {"version":"2.0.0","uptime":"...","providers":[...],"cache":{...}}
|
||
|
||
# 工具列表（MCP tools/list）
|
||
curl -X POST http://localhost:8080/tools/list
|
||
# → {"tools":[{"name":"web_search",...}]}
|
||
|
||
# 搜索调用
|
||
curl -X POST http://localhost:8080/tools/call \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"tool":"web_search","input":{"query":"hello world"}}'
|
||
|
||
# 监控面板（浏览器打开）
|
||
open http://localhost:9090
|
||
```
|
||
|
||
---
|
||
|
||
## 端口规划
|
||
|
||
| 端口 | 用途 | 说明 |
|
||
| ------ | ------ | ------ |
|
||
| **8080** | MCP 服务端口 | tools/list、tools/call、SSE、管理 API、/health、/status |
|
||
| **9090** | 监控端口 | HTML 仪表盘（`/`）、Prometheus 指标（`/metrics`）、存活探针（`/health`） |
|
||
|
||
## MCP 服务端点（端口 8080）
|
||
|
||
### MCP 协议端点
|
||
|
||
| 路径 | 方法 | 说明 |
|
||
| ------ | ------ | ------ |
|
||
| `POST /tools/list` | POST | 列出可用工具（web_search），含 inputSchema |
|
||
| `POST /tools/call` | POST | 调用 web_search 工具执行搜索 |
|
||
| `GET /sse` | GET | SSE 事件流（MCP 标准握手） |
|
||
| `POST /messages` | POST | MCP JSON-RPC 消息（与 /sse 配对使用） |
|
||
| `GET /` | GET | 端点指引（纯文本） |
|
||
|
||
### web_search 工具
|
||
|
||
**inputSchema**：
|
||
|
||
| 参数 | 类型 | 默认 | 说明 |
|
||
| ------ | ------ | ------ | ------ |
|
||
| `query` | string | (必填) | 搜索关键词 |
|
||
| `max_results` | integer | 5 | 最大返回结果数（1–20） |
|
||
| `mode` | string | `"first"` | 搜索模式：`first`（首个成功返回） / `merge`（并发搜所有引擎后合并去重） |
|
||
| `providers` | string[] | 全部 | 优先使用的搜索引擎 |
|
||
|
||
**响应**（CallToolResult）：
|
||
|
||
```json
|
||
{
|
||
"content": [{
|
||
"type": "json",
|
||
"text": "{\"provider\":\"tavily\",\"query\":\"...\",\"results\":[...],\"total_count\":5,\"cached\":false}"
|
||
}]
|
||
}
|
||
```
|
||
|
||
### 管理端点
|
||
|
||
| 路径 | 方法 | 说明 |
|
||
| ------ | ------ | ------ |
|
||
| `GET /health` | GET | 存活探针 → `{"status":"ok"}` |
|
||
| `GET /status` | GET | 系统状态：provider 列表、活跃密钥数、缓存命中率、uptime |
|
||
| `GET /admin/keys` | GET | 各 provider 启用状态 |
|
||
| `PUT /admin/provider/{name}/enable` | PUT | 启用指定 provider |
|
||
| `PUT /admin/provider/{name}/disable` | PUT | 禁用指定 provider |
|
||
| `POST /admin/cache/clear` | POST | 清空缓存 |
|
||
|
||
## 监控面板（端口 9090）
|
||
|
||
### HTML 仪表盘 `GET /`
|
||
|
||
暗色风格的可视化面板，展示：
|
||
|
||
- **四张概览卡片**：Provider 数、活跃密钥数、缓存命中率（绿/黄/红三档）、缓存条目总数
|
||
- **Provider 状态表格**：🟢/🔴 状态指示灯、名称、启用/禁用开关、活跃密钥计数
|
||
- **缓存统计表格**：L1（内存 LRU）命中、L2（Redis）命中、未命中、综合命中率
|
||
- **自动刷新**：每 30 秒自动刷新
|
||
- **导航链接**：一键跳转 /status、/admin/keys、/health
|
||
|
||
### Prometheus 原始指标 `GET /metrics`
|
||
|
||
| 指标名 | 类型 | 标签 | 说明 |
|
||
| -------- | ------ | ------ | ------ |
|
||
| `bowen_search_total` | Counter | `provider` | 搜索请求总数 |
|
||
| `bowen_search_duration_seconds` | Histogram | — | 搜索耗时分布 |
|
||
| `bowen_search_errors_total` | Counter | `reason` | 搜索错误数 |
|
||
| `bowen_cache_hits_total` | Counter | — | 缓存命中总数 |
|
||
| `bowen_cache_hits_l2_total` | Counter | — | Redis 二级缓存命中数 |
|
||
| `bowen_cache_misses_total` | Counter | — | 缓存未命中数 |
|
||
| `bowen_active_keys` | Gauge | `provider` | 各 provider 活跃密钥数 |
|
||
|
||
所有监控端点也可在端口 9090 访问，与 MCP 服务端口独立。
|
||
|
||
---
|
||
|
||
## 配置文件
|
||
|
||
非敏感配置放在项目根目录 `config/mcp/web-search.yaml`（从 `config/mcp/web-search.example.yaml` 复制）。
|
||
不传 `--config` 时自动按项目惯例探测：开发模式探测 `../../config/mcp/web-search.yaml`，容器内探测 `/etc/bowen/config.yaml`。
|
||
|
||
```yaml
|
||
server:
|
||
port: 8080 # SSE 模式监听端口
|
||
read_timeout: 30s # HTTP 读取超时
|
||
write_timeout: 30s # HTTP 写入超时
|
||
|
||
providers:
|
||
tavily:
|
||
enabled: true # 是否启用（热重载：支持动态变更）
|
||
timeout: 10s
|
||
max_results: 10
|
||
health_check:
|
||
interval: 60s
|
||
failure_threshold: 3
|
||
bing:
|
||
enabled: true
|
||
timeout: 10s
|
||
max_results: 20
|
||
brave:
|
||
enabled: true
|
||
timeout: 10s
|
||
max_results: 10
|
||
|
||
balancer:
|
||
strategy: weighted_round_robin
|
||
retry_count: 2 # 热重载：支持动态变更
|
||
circuit_breaker:
|
||
enabled: true
|
||
failure_threshold: 5
|
||
cooldown: 30s
|
||
|
||
cache:
|
||
enabled: true
|
||
ttl: 5m # 热重载：支持动态变更
|
||
max_items: 1000
|
||
redis:
|
||
enabled: false # 需要自行部署 Redis
|
||
addr: 127.0.0.1:6379
|
||
password: ""
|
||
db: 0
|
||
|
||
metrics:
|
||
enabled: true
|
||
port: 9090
|
||
path: /metrics
|
||
```
|
||
|
||
**配置优先级**：环境变量 > YAML 文件 > 内置默认值
|
||
|
||
**热重载**：指定 `--config` 后，修改 YAML 文件自动生效（500ms 防抖），支持动态变更：
|
||
|
||
| 配置项 | 变更后自动生效 |
|
||
| -------- | --------------- |
|
||
| `providers.{name}.enabled` | 运行时启用/禁用搜索源 |
|
||
| `cache.ttl` | 更新新缓存条目的过期时间 |
|
||
| `balancer.retry_count` | 更新重试次数 |
|
||
|
||
---
|
||
|
||
## 传输模式
|
||
|
||
博闻支持两种 MCP 传输模式，**不在配置中写死**，由启动 CLI 参数决定：
|
||
|
||
| 模式 | 启动方式 | 适用场景 |
|
||
| ------ | --------- | --------- |
|
||
| **SSE** | `--port 8080` | 灵台后端注册（简化 HTTP 端点 `/tools/list` + `/tools/call`）、远程 MCP Client 直连（`/sse` + `/messages`） |
|
||
| **Stdio** | `--stdio` | Claude Desktop / Cursor 等 MCP Client 以子进程方式启动，通过 stdin/stdout 走 JSON-RPC 通信 |
|
||
|
||
两种模式下核心业务逻辑完全共享（`internal/mcp/handler.go`），只有传输层不同。
|
||
|
||
---
|
||
|
||
## 环境变量
|
||
|
||
所有敏感信息通过环境变量注入（参见 `.env.example` 博闻段）：
|
||
|
||
| 变量 | 必填 | 说明 |
|
||
| ------ | ------ | ------ |
|
||
| `TAVILY_API_KEYS` | 是 | Tavily 搜索 Key，多 key 逗号分隔 |
|
||
| `BRAVE_API_KEYS` | 是 | Brave Search Key |
|
||
| `MCP_WEB_SEARCH_REDIS_ENABLED` | 否 | Redis 二级缓存开关 |
|
||
| `MCP_WEB_SEARCH_REDIS_ADDR` | 否 | Redis 地址（默认 `127.0.0.1:6379`） |
|
||
| `MCP_WEB_SEARCH_REDIS_PASSWORD` | 否 | Redis 密码 |
|
||
| `MCP_WEB_SEARCH_REDIS_DB` | 否 | Redis 数据库编号（默认 0） |
|
||
|
||
---
|
||
|
||
## 开发
|
||
|
||
```bash
|
||
# 运行所有测试
|
||
make test
|
||
|
||
# 编译
|
||
make build # → bin/bowen-server
|
||
|
||
# 本地 SSE 模式
|
||
make run-sse
|
||
|
||
# 本地 stdio 模式
|
||
make run-stdio
|
||
|
||
# 代码检查
|
||
make lint
|
||
```
|
||
|
||
开发环境日志自动使用彩色输出（ANSI 颜色代码）：
|
||
|
||
- `INFO` → 绿色
|
||
- `WARN` → 黄色
|
||
- `ERROR` → 红色
|
||
- `DEBUG` → 灰色
|
||
|
||
生产环境（`ENV=production`）自动切换为 JSON 格式，便于日志采集系统采集。
|
||
|
||
### 项目结构
|
||
|
||
```text
|
||
mcp/web-search/
|
||
├── cmd/server/main.go # 入口（--port / --stdio）
|
||
├── internal/
|
||
│ ├── config/
|
||
│ │ ├── config.go # YAML + 环境变量配置加载
|
||
│ │ ├── yaml.go # YAML 解析
|
||
│ │ └── reloader.go # 配置热重载（fsnotify）
|
||
│ ├── logger/logger.go # slog 双模式（dev 彩色 / prod JSON）
|
||
│ ├── models/types.go # 核心数据类型
|
||
│ ├── providers/ # 搜索提供商适配
|
||
│ │ ├── provider.go # SearchProvider 接口
|
||
│ │ ├── tavily.go / bing.go / brave.go
|
||
│ │ └── registry.go # 注册中心
|
||
│ ├── balancer/ # 负载均衡
|
||
│ │ ├── keypool.go # 密钥池（EWMA）
|
||
│ │ ├── circuitbreaker.go # 熔断器
|
||
│ │ └── balancer.go # LoadBalancer
|
||
│ ├── cache/cache.go # 两级缓存
|
||
│ ├── mcp/ # MCP 协议实现
|
||
│ │ ├── handler.go # 核心处理逻辑
|
||
│ │ ├── stdio.go # stdin/stdout JSON-RPC
|
||
│ │ ├── sse.go # HTTP SSE 传输
|
||
│ │ ├── http.go # 简化 HTTP 端点
|
||
│ │ ├── status.go # /health + /status
|
||
│ │ ├── admin.go # 管理 API
|
||
│ │ └── monitor.go # HTML 监控面板
|
||
│ └── metrics/metrics.go # Prometheus 指标
|
||
├── Makefile
|
||
├── go.mod / go.sum
|
||
```
|
||
|
||
---
|
||
|
||
## Docker
|
||
|
||
```bash
|
||
# 构建镜像
|
||
docker build -t bowen-web-search -f ../../docker/Dockerfile.web-search .
|
||
|
||
# 运行
|
||
docker run \
|
||
-e TAVILY_API_KEYS=tvly-xxx \
|
||
-e BRAVE_API_KEYS=brave-xxx \
|
||
-p 8080:8080 -p 9090:9090 \
|
||
bowen-web-search
|
||
```
|
||
|
||
Docker 镜像可通过魂镜的 `docker/docker-compose.app.yml` 编排启动。
|
||
|
||
---
|
||
|
||
## 集成到灵台
|
||
|
||
后端通过 MCP 注册 API 自动接入博闻：
|
||
|
||
```bash
|
||
# 注册博闻为 MCP Server
|
||
curl -X POST http://localhost:8000/api/v1/tools/mcp-servers \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"name": "bowen-web-search",
|
||
"endpoint_url": "http://localhost:8080",
|
||
"status": "enabled"
|
||
}'
|
||
```
|
||
|
||
注册后灵台会拉取工具清单，Agent 即可在对话中直接调用 `web_search` 工具。
|
||
|
||
---
|
||
|
||
## 搜索模式对比
|
||
|
||
| 模式 | 延迟 | 召回 | 使用场景 |
|
||
| ------ | ------ | ------ | --------- |
|
||
| `first`（默认） | 低（首个成功即返回） | 单 provider | 快速查天气、新闻、百科等简单查询 |
|
||
| `merge` | 中（等最慢 provider） | 高（多源合并去重） | 研究、对比多个来源、需要全面 coverage |
|
||
|
||
---
|
||
|
||
## 技术栈
|
||
|
||
| 类别 | 选型 |
|
||
| ------ | ------ |
|
||
| 语言 | Go 1.22+ |
|
||
| Web | 标准库 `net/http` |
|
||
| 日志 | 标准库 `log/slog` + 自定义彩色 Handler |
|
||
| 配置 | `gopkg.in/yaml.v3` + 环境变量 |
|
||
| 内存缓存 | `hashicorp/golang-lru/v2` |
|
||
| Redis | `redis/go-redis/v9`（可选） |
|
||
| 监控 | `prometheus/client_golang` |
|
||
| 热重载 | `fsnotify` |
|
||
| 测试 | 标准库 `testing` |
|
||
| 容器化 | Docker 多阶段构建 |
|