MCP Gateway for Agents 镜像文档

1. 镜像概述

MCP Gateway for Agents 是 MCP（管理控制平面，Management and Control Plane）的核心组件，作为代理节点（Agents）与控制平面之间的通信枢纽，负责桥接代理节点与后端控制平面的数据流、协议转换及安全管控。其核心定位是解决大规模分布式环境下代理节点的统一接入、数据路由与通信安全问题。

2. 核心功能与特性

2.1 连接管理

• 支持高并发代理节点接入，单实例可承载数千至数万级代理连接
• 自动维护代理连接状态，支持断线重连与连接心跳检测
• 基于连接元数据（如代理ID、区域标签）的连接分组管理

2.2 数据转发与路由

• 低延迟双向数据转发，支持代理节点与控制平面的实时消息交互
• 基于规则的动态路由（如按代理类型、数据优先级路由至不同后端服务）
• 内置流量控制机制，防止突发流量冲击后端控制平面

2.3 协议适配与转换

• 原生支持 MQTT、gRPC、HTTP/HTTPS 等主流通信协议
• 支持自定义协议扩展，通过插件适配私有代理通信协议
• 协议间无缝转换（如将 MQTT 消息转换为 gRPC 格式转发至控制平面）

2.4 安全与认证

• 支持 TLS 1.2+ 传输加密，确保数据传输机密性
• 内置多种认证机制：JWT 令牌认证、API Key 认证、证书双向认证
• 基于 RBAC（角色访问控制）的代理操作权限粒度控制

2.5 高可用与可扩展性

• 无状态设计，支持多实例集群部署，通过负载均衡实现水平扩展
• 支持主备模式部署，自动故障转移，保障服务连续性
• 与主流服务发现机制（如 Kubernetes Service、Consul）集成

2.6 监控与可观测性

• 暴露 Prometheus 指标接口（如连接数、转发延迟、错误率）
• 支持结构化日志输出（JSON 格式），兼容 ELK、Grafana Loki 等日志系统
• 内置健康检查接口，支持容器编排平台的存活/就绪探针

3. 使用场景与适用范围

3.1 大规模代理部署环境

• 物联网（IoT）设备管理：对接海量物联网传感器、终端设备代理，实现设备状态上报与控制指令下发
• 边缘计算节点：边缘代理与云端控制平面的通信桥接，解决边缘-云端数据交互延迟问题

3.2 分布式系统管理

• 跨区域/数据中心代理协调：统一管理分布在多区域的代理节点，实现跨地域数据同步与任务调度
• 微服务代理接入：作为微服务网格（Service Mesh）的边缘网关，对接服务代理（Sidecar）与控制平面

3.3 高安全要求场景

• 金融交易系统：代理节点与风控控制平面的加密通信，满足金融级数据安全合规要求
• 工业控制系统（ICS）：工业设备代理与监控控制平面的隔离通信，防止未授权访问

3.4 多协议混合接入场景

• 异构代理统一管理：同时接入使用 MQTT（物联网）、gRPC（微服务）、HTTP（通用设备）的代理节点，简化控制平面协议适配复杂度

4. 使用方法与配置说明

4.1 基础 Docker 运行命令

docker run -d \
  --name mcp-gateway \
  --restart always \
  -p 8080:8080/tcp \    # HTTP/gRPC 协议端口
  -p 1883:1883/tcp \    # MQTT 协议端口（可选）
  -e LISTEN_HTTP_PORT=8080 \
  -e LISTEN_MQTT_PORT=1883 \
  -e AUTH_MODE=jwt \
  -e JWT_SECRET=your_jwt_secret_key \
  -e CONTROL_PLANE_ENDPOINTS="[***]" \
  -e LOG_LEVEL=info \
  -v /host/path/logs:/app/logs \    # 挂载日志目录
  mcp-gateway:latest

4.2 Docker Compose 配置示例

version: '3.8'

services:
  mcp-gateway:
    image: mcp-gateway:latest
    container_name: mcp-gateway
    restart: always
    ports:
      - "8080:8080"   # HTTP/gRPC 端口
      - "1883:1883"   # MQTT 端口
      - "9090:9090"   # 监控指标端口
    environment:
      - LISTEN_HTTP_PORT=8080
      - LISTEN_MQTT_PORT=1883
      - LISTEN_METRICS_PORT=9090
      - AUTH_MODE=cert
      - CERT_PATH=/etc/gateway/certs
      - CONTROL_PLANE_ENDPOINTS="[***]"
      - LOG_LEVEL=info
      - MAX_CONCURRENT_CONNECTIONS=10000
      - CONNECTION_IDLE_TIMEOUT=300s
    volumes:
      - ./certs:/etc/gateway/certs:ro   # 挂载认证证书（只读）
      - ./logs:/app/logs                # 挂载日志目录
      - ./config.yaml:/app/config.yaml:ro  # 挂载自定义配置文件（可选）
    networks:
      - mcp-network

networks:
  mcp-network:
    driver: bridge

4.3 环境变量说明

4.4 配置文件说明（可选）

若需更复杂配置（如路由规则、高级认证策略），可通过挂载配置文件（默认路径 /app/config.yaml）实现。示例配置：

# /app/config.yaml 示例
listen:
  http:
    port: 8080
    read_timeout: 30s
    write_timeout: 30s
  mqtt:
    port: 1883
    max_packet_size: 1MB
    keepalive_interval: 60s

auth:
  mode: cert
  cert:
    ca_cert: /etc/gateway/certs/ca.crt
    server_cert: /etc/gateway/certs/server.crt
    server_key: /etc/gateway/certs/server.key
    client_auth: required  # 强制客户端证书认证

routes:
  - protocol: grpc
    match:
      service: "agent.ControlPlane"
      method: "ReportStatus"
    backend:
      endpoints: ["[***]", "[***]"]
      load_balance: round_robin  # 轮询负载均衡

logging:
  level: info
  format: json
  output: /app/logs/gateway.log
  max_size: 100MB  # 单日志文件大小
  max_backup: 10   # 日志文件保留数量

metrics:
  path: /metrics
  scrape_interval: 10s

4.5 集群部署说明

对于大规模部署，建议通过 Docker Compose 或 Kubernetes 实现集群化部署，示例 Kubernetes Deployment 片段：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mcp-gateway
spec:
  replicas: 3  # 3实例集群
  selector:
    matchLabels:
      app: mcp-gateway
  template:
    metadata:
      labels:
        app: mcp-gateway
    spec:
      containers:
      - name: mcp-gateway
        image: mcp-gateway:latest
        ports:
        - containerPort: 8080
        env:
        - name: AUTH_MODE
          value: "jwt"
        - name: JWT_SECRET
          valueFrom:
            secretKeyRef:
              name: mcp-gateway-secrets
              key: jwt-secret
        - name: CONTROL_PLANE_ENDPOINTS
          value: "[***]"
        livenessProbe:
          httpGet:
            path: /health/live
            port: 8080
          initialDelaySeconds: 10
          periodSeconds: 5
        readinessProbe:
          httpGet:
            path: /health/ready
            port: 8080
          initialDelaySeconds: 5
          periodSeconds: 3

4.6 健康检查与监控

• 存活探针（Liveness Probe）：访问 http://<gateway-ip>:8080/health/live，返回 200 OK 表示服务存活
• 就绪探针（Readiness Probe）：访问 http://<gateway-ip>:8080/health/ready，返回 200 OK 表示服务可接收请求
• 监控指标：访问 http://<gateway-ip>:9090/metrics 获取 Prometheus 格式指标，关键指标包括：
  • mcp_gateway_connections_total：总连接数
  • mcp_gateway_data_throughput_bytes：数据吞吐量（字节）
  • mcp_gateway_request_latency_ms：请求处理延迟（毫秒）
  • mcp_gateway_errors_total：错误总数（按类型统计）

注：具体功能与配置参数可能因镜像版本不同存在差异，建议结合官方镜像标签（如 mcp-gateway:v1.2.0）的版本说明文档使用。