Gateway Architecture 网关架构

核心设计理念

"单一长期存在的网关拥有所有消息表面。客户端/节点通过 WebSocket 连接。一个主机一个网关；它是唯一打开 WhatsApp 会话的地方。"

架构概览

单网关模式

┌─────────────┐    WebSocket    ┌──────────────┐
│   Client    ├─────────────────┤   Gateway    │
│   (Node)    │                 │   (Single)   │
└─────────────┘                 └──────────────┘
                                       │
                              ┌────────┴────────┐
                              │                 │
                         ┌────▼────┐      ┌────▼────┐
                         │Channel 1│      │Channel 2│
                         └─────────┘      └─────────┘

关键特性

单实例原则: 每个主机只运行一个网关实例
统一入口: 所有外部通信都通过网关
会话独占: 特定会话（如 WhatsApp）只能在一个网关上打开
WebSocket 连接: 客户端通过 WebSocket 与网关通信

组件架构

网关核心组件

gateway:
  message_router:         # 消息路由
  channel_managers:       # 频道管理器
  session_store:          # 会话存储
  authentication_layer:   # 认证层
  rate_limiter:           # 限流器
  load_balancer:          # 负载均衡（多实例时）

消息流向

External Channel → Gateway Router → Agent Runtime → Response → Channel

部署模式

单机部署

┌─────────────────────────────────────┐
│              Host Machine           │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│  │Gateway  │ │Agents   │ │Database │ │
│  │(Single) │ │(Multiple)│ │(SQLite) │ │
│  └─────────┘ └─────────┘ └─────────┘ │
└─────────────────────────────────────┘

分布式部署

┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   Gateway   │    │   Gateway   │    │   Gateway   │
│   (Host 1)  │    │   (Host 2)  │    │   (Host 3)  │
└─────────────┘    └─────────────┘    └─────────────┘
       │                  │                  │
       └──────────────────┼──────────────────┘
                          │
                ┌─────────▼─────────┐
                │ Shared Database   │
                │ (PostgreSQL/Redis)│
                └───────────────────┘

配置示例

基础配置

gateway:
  host: "0.0.0.0"
  port: 3000
  websocket_port: 3001
  
  # 连接配置
  max_connections: 1000
  connection_timeout: 30000
  
  # 安全配置
  tls_enabled: true
  certificate_file: "/path/to/cert.pem"
  private_key_file: "/path/to/key.pem"

负载均衡配置

load_balancing:
  strategy: "round_robin"
  health_check_interval: 30
  failover_timeout: 60
  
  nodes:
    - host: "gateway1.example.com"
      port: 3000
      weight: 1
      
    - host: "gateway2.example.com"
      port: 3000
      weight: 1

性能优化

连接管理

connection_pool:
  min_size: 10
  max_size: 100
  idle_timeout: 300
  max_lifetime: 3600

缓存策略

caching:
  message_cache:
    ttl: 300
    max_size: 10000
    
  session_cache:
    ttl: 3600
    max_size: 1000

监控和指标

关键指标

metrics:
  - name: "gateway_connections"
    type: "gauge"
    description: "当前连接数"
    
  - name: "messages_processed"
    type: "counter"
    description: "处理的消息总数"
    
  - name: "average_response_time"
    type: "histogram"
    description: "平均响应时间"

健康检查端点

GET /health          # 基础健康检查
GET /metrics         # Prometheus 指标
GET /status          # 详细状态信息

故障处理

自动恢复机制

failover:
  enabled: true
  retry_attempts: 3
  retry_delay: 5000
  circuit_breaker:
    threshold: 5
    timeout: 60000

日志配置

logging:
  level: "info"
  format: "json"
  outputs:
    - type: "file"
      path: "/var/log/openclaw/gateway.log"
    - type: "stdout"

安全考虑

访问控制

security:
  ip_whitelist:
    - "192.168.1.0/24"
    - "10.0.0.0/8"
    
  rate_limiting:
    requests_per_second: 100
    burst_size: 200

证书管理

# 自动生成自签名证书
openclaw gateway cert generate

# 使用现有证书
openclaw gateway cert install --cert /path/to/cert.pem --key /path/to/key.pem

最佳实践

高可用部署: 在生产环境中使用多个网关实例
监控告警: 设置关键指标的监控和告警
定期维护: 定期更新证书和清理日志
安全审计: 定期审查访问日志和安全配置

更多详情请参考官方文档: https://docs.openclaw.ai/concepts/architecture.md