1MCP Server

# 健康检查 API 参考 1MCP 代理提供全面的健康检查端点，用于监控系统状态、服务器连接和操作指标。 ## 概述 健康检查端点专为以下目的而设计： - **负载均衡器**：HAProxy、nginx、AWS ALB - **容器编排**：Kubernetes、Docker Swarm - **CI/CD 管道**：部署验证 - **手动调试**：系统状态检查 ## 安全配置 健康端点包括可配置的安全功能，以控制信息暴露： **详细级别**： - **`full`**：完整的系统信息，带有错误清理功能 - **`basic`**：有限的系统详细信息、经过清理的错误、服务器状态 - **`minimal`**（默认）：仅包含必要的状态信息，无敏感详细信息 **配置**： ```bash # CLI 选项（默认为 minimal） npx -y @1mcp/agent --config mcp.json --health-info-level basic # 环境变量 export ONE_MCP_HEALTH_INFO_LEVEL=basic npx -y @1mcp/agent --config mcp.json ``` **清理功能**： - 自动错误消息清理 - 删除凭据模式（user:password@、令牌、密钥） - URL 和文件路径编辑 - IP 地址匿名化 ## 端点 ### `GET /health` **描述**：完整的健康状态，包含详细的系统指标和服务器信息。 **身份验证**：无需 **响应代码**： - `200` - 健康或已降级但功能正常 - `503` - 不健康，存在严重问题 - `500` - 内部服务器错误 **响应标头**： ```http Content-Type: application/json Cache-Control: no-cache, no-store, must-revalidate X-Health-Status: healthy|degraded|unhealthy X-Service-Version: 0.15.0 X-Uptime-Seconds: 3600 ``` **响应模式**： ```json { "status": "healthy|degraded|unhealthy", "timestamp": "2025-01-30T12:00:00.000Z", "version": "0.15.0", "system": { "uptime": 3600, "memory": { "used": 50.5, "total": 100.0, "percentage": 50.5 }, "process": { "pid": 12345, "nodeVersion": "v20.0.0", "platform": "linux", "arch": "x64" } }, "servers": { "total": 3, "healthy": 2, "unhealthy": 1, "details": [ { "name": "filesystem-server", "status": "connected|error|disconnected|awaiting_oauth", "healthy": true, "lastConnected": "2025-01-30T11:30:00.000Z", "lastError": "Connection timeout", "tags": ["filesystem", "local"] } ] }, "configuration": { "loaded": true, "serverCount": 3, "enabledCount": 2, "disabledCount": 1, "authEnabled": true, "transport": "http" } } ``` **字段描述**： - **`status`**：整体健康状态 - `healthy` - 所有系统均可运行 - `degraded` - 存在一些问题，但仍可正常运行 - `unhealthy` - 存在影响功能的严重问题 - **`system.uptime`**：服务器正常运行时间（秒） - **`system.memory.used`**：已用堆内存（MB） - **`system.memory.total`**：总堆内存（MB） - **`system.memory.percentage`**：内存使用百分比 - **`servers.details[].status`**：单个服务器状态 - `connected` - 服务器已连接且可运行 - `error` - 服务器存在连接或运行时错误 - `disconnected` - 服务器未连接 - `awaiting_oauth` - 服务器需要 OAuth 身份验证 ### `GET /health/live` **描述**：用于基本可用性检查的简单活动性探针。 **身份验证**：无需 **响应代码**： - `200` - 服务器正在运行（如果可访问，则始终返回 200） **响应模式**： ```json { "status": "alive", "timestamp": "2025-01-30T12:00:00.000Z" } ``` **用例**： - Kubernetes 活动性探针 - 负载均衡器基本健康检查 - 服务发现健康检查 ### `GET /health/ready` **描述**：就绪性探针，用于确定服务是否已准备好接受请求。 **身份验证**：无需 **响应代码**： - `200` - 服务已就绪（配置已加载） - `503` - 服务未就绪 **响应模式**： ```json { "status": "ready|not_ready", "timestamp": "2025-01-30T12:00:00.000Z", "configuration": { "loaded": true, "serverCount": 3, "enabledCount": 2, "disabledCount": 1, "authEnabled": true, "transport": "http" } } ``` **用例**： - Kubernetes 就绪性探针 - 负载均衡器就绪性检查 - 部署验证 ## 健康状态逻辑 ### 整体状态确定 整体健康状态由以下因素确定： 1. **配置状态**：必须加载才能处于 `healthy` 或 `degraded` 状态 2. **服务器健康比率**： - 所有服务器都健康 → `healthy` - 未配置服务器 → `degraded` - > 50% 的服务器健康 → `degraded` - ≤50% 的服务器健康 → `unhealthy` ### 服务器健康分类 单个服务器在以下情况下被视为健康： - 状态为 `connected` - 最近没有严重错误 - 响应健康检查 ## 速率限制 健康端点的速率限制较为宽松： - **窗口**：5 分钟 - **限制**：每个 IP 200 个请求 - **标头**：包含标准速率限制标头 ## 监控集成示例 ### Kubernetes 健康探针 ```yaml apiVersion: apps/v1 kind: Deployment metadata: name: 1mcp-agent spec: template: spec: containers: - name: 1mcp image: ghcr.io/1mcp-app/agent:latest ports: - containerPort: 3050 livenessProbe: httpGet: path: /health/live port: 3050 initialDelaySeconds: 30 periodSeconds: 10 timeoutSeconds: 5 failureThreshold: 3 readinessProbe: httpGet: path: /health/ready port: 3050 initialDelaySeconds: 5 periodSeconds: 5 timeoutSeconds: 3 failureThreshold: 3 ``` ### Docker Compose 健康检查 ```yaml version: '3.8' services: 1mcp: image: ghcr.io/1mcp-app/agent:latest ports: - '3050:3050' healthcheck: test: ['CMD', 'curl', '-f', 'http://localhost:3050/health'] interval: 30s timeout: 10s retries: 3 start_period: 60s ``` ### HAProxy 后端健康检查 ``` backend 1mcp_servers balance roundrobin option httpchk GET /health/ready http-check expect status 200 server 1mcp-1 1mcp-1:3050 check inter 30s server 1mcp-2 1mcp-2:3050 check inter 30s ``` ### 基于脚本的监控 ```bash #!/bin/bash # 简单的健康检查脚本 HEALTH_URL="http://localhost:3050/health" RESPONSE=$(curl -s -w "%{http_code}" -o /tmp/health.json "$HEALTH_URL") HTTP_CODE="${RESPONSE: -3}" if [ "$HTTP_CODE" -eq 200 ]; then STATUS=$(jq -r '.status' /tmp/health.json) UNHEALTHY=$(jq -r '.servers.unhealthy' /tmp/health.json) echo "1MCP Health: $STATUS (Unhealthy servers: $UNHEALTHY)" if [ "$STATUS" = "unhealthy" ]; then exit 1 fi else echo "1MCP Health Check Failed: HTTP $HTTP_CODE" exit 1 fi ``` ## 错误响应 ### 服务不可用 (503) ```json { "status": "unhealthy", "timestamp": "2025-01-30T12:00:00.000Z", "version": "0.15.0", "system": { /* system info */ }, "servers": { "total": 3, "healthy": 0, "unhealthy": 3, "details": [ /* server details */ ] }, "configuration": { "loaded": false, "serverCount": 0, "enabledCount": 0, "disabledCount": 0, "authEnabled": false, "transport": "http" } } ``` ### 内部服务器错误 (500) ```json { "status": "unhealthy", "timestamp": "2025-01-30T12:00:00.000Z", "error": "Health check failed", "message": "Configuration service unavailable" } ``` ## 安全注意事项 ### 生产部署 **网络级保护**（推荐）： - 仅将健康端点限制为监控网络 - 使用防火墙规则限制对受信任 IP 的访问 - 考虑使用 VPN 或专用网络访问详细端点 **信息暴露控制**： - 对面向公众的部署使用 `basic` 或 `minimal` 详细级别 - `full` 详细级别仅建议用于专用网络 - 始终启用错误清理以防止凭据泄漏 **示例安全配置**： ```bash # 开发环境 npx -y @1mcp/agent --config mcp.json --health-info-level full # 暂存环境 npx -y @1mcp/agent --config mcp.json --health-info-level basic # 生产环境（默认的 minimal 级别是安全的） npx -y @1mcp/agent --config mcp.json ``` ### 详细级别影响 | 级别 | 系统信息 | 服务器详细信息 | 错误消息 | 用例 | | --------- | ---------- | -------------- | -------- | --------------- | | `full` | 完整 | 完整 + 已清理 | 已清理 | 内部监控 | | `basic` | 有限 | 状态 + 已清理 | 已清理 | 受限监控 | | `minimal` | 仅基本信息 | 仅计数 | 无 | 公共/负载均衡器 | ## 最佳实践 ### 监控设置 1. **使用多个端点**：结合使用 `/health`、`/health/live` 和 `/health/ready` 进行全面监控 2. **设置适当的超时**：健康检查应在 5-10 秒内完成 3. **配置重试逻辑**：允许 2-3 次重试，并采用指数退避策略 4. **监控趋势**：跟踪健康状态随时间的变化 5. **安全第一**：为您的网络暴露选择适当的详细级别 ### 开发测试 ```bash # 测试所有健康端点 curl -v http://localhost:3050/health curl -v http://localhost:3050/health/live curl -v http://localhost:3050/health/ready # 检查响应标头 curl -I http://localhost:3050/health # 监控健康状态 watch -n 5 'curl -s http://localhost:3050/health | jq ".status, .servers.healthy, .servers.unhealthy"' ```