多网关部署架构教程

为什么需要多网关

单个 Gateway 实例存在以下局限：

单点故障风险
处理能力有限
无法跨地域优化延迟

多网关部署可以解决这些问题，提供高可用性和水平扩展能力。

架构模式

主备模式（Active-Standby）

一个主实例处理所有请求，备用实例待命。主实例故障时自动切换。

用户请求 → 负载均衡器 → 主 Gateway (active)
                      → 备 Gateway (standby)

主主模式（Active-Active）

多个实例同时处理请求，负载均衡器分发流量。

用户请求 → 负载均衡器 → Gateway A
                      → Gateway B
                      → Gateway C

Nginx 负载均衡配置

upstream openclaw_backend {
    least_conn;
    server 10.0.0.1:3000 weight=5;
    server 10.0.0.2:3000 weight=5;
    server 10.0.0.3:3000 backup;

    keepalive 32;
}

server {
    listen 443 ssl;
    server_name gateway.example.com;

    ssl_certificate /etc/ssl/cert.pem;
    ssl_certificate_key /etc/ssl/key.pem;

    location / {
        proxy_pass http://openclaw_backend;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_connect_timeout 10s;
        proxy_read_timeout 120s;
    }

    location /health {
        proxy_pass http://openclaw_backend;
        proxy_connect_timeout 5s;
        proxy_read_timeout 5s;
    }
}

共享状态存储

多网关部署需要共享会话状态，使用 Redis 作为共享存储：

{
  "gateway": {
    "session": {
      "store": "redis",
      "redis": {
        "host": "redis.example.com",
        "port": 6379,
        "password": "{{REDIS_PASSWORD}}",
        "db": 0,
        "keyPrefix": "openclaw:"
      }
    }
  }
}

Docker Compose 多实例

version: "3"
services:
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    command: redis-server --requirepass your-redis-password

  gateway-1:
    image: openclaw/openclaw:latest
    environment:
      - OPENCLAW_NODE_ID=gateway-1
      - REDIS_URL=redis://:your-redis-password@redis:6379/0
    ports:
      - "3001:3000"
    depends_on:
      - redis

  gateway-2:
    image: openclaw/openclaw:latest
    environment:
      - OPENCLAW_NODE_ID=gateway-2
      - REDIS_URL=redis://:your-redis-password@redis:6379/0
    ports:
      - "3002:3000"
    depends_on:
      - redis

  nginx:
    image: nginx:alpine
    ports:
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf
      - ./ssl:/etc/ssl
    depends_on:
      - gateway-1
      - gateway-2

会话亲和性

某些场景需要同一用户的请求始终路由到同一个 Gateway（如 WebSocket 连接）：

upstream openclaw_backend {
    ip_hash;
    server 10.0.0.1:3000;
    server 10.0.0.2:3000;
}

健康检查配置

负载均衡器需要定期检查后端健康状态：

upstream openclaw_backend {
    server 10.0.0.1:3000 max_fails=3 fail_timeout=30s;
    server 10.0.0.2:3000 max_fails=3 fail_timeout=30s;
}

在 OpenClaw 中确保健康检查端点可用：

{
  "gateway": {
    "healthCheck": {
      "enabled": true,
      "path": "/health",
      "includeDetails": false
    }
  }
}

Webhook 处理

多网关部署时，Webhook 请求只应被一个实例处理。使用 Redis 锁防止重复处理：

{
  "gateway": {
    "webhook": {
      "deduplication": true,
      "deduplicationStore": "redis",
      "deduplicationTTL": 60
    }
  }
}

监控多实例

通过统一的监控面板查看所有实例状态：

# 查看集群状态
openclaw gateway cluster-status

输出：

Cluster Status:
  gateway-1  ✓ healthy  requests: 1520  cpu: 35%  mem: 256MB
  gateway-2  ✓ healthy  requests: 1480  cpu: 32%  mem: 248MB
  Total: 2 nodes, 3000 requests/hour

滚动更新

使用多网关架构可以实现零停机更新：

# 1. 从负载均衡器移除 gateway-1
# 2. 更新 gateway-1
docker compose up -d --no-deps gateway-1
# 3. 等待 gateway-1 健康
# 4. 重复对 gateway-2
docker compose up -d --no-deps gateway-2

总结

多网关部署是 OpenClaw 生产环境的最佳实践。通过 Nginx 负载均衡 + Redis 共享状态，可以实现高可用、可扩展的 Gateway 集群，满足高并发和高可靠性需求。