集群部署

GPT-Load 高可用集群部署方案，支持主从架构和水平扩展

集群架构概览

分布式主从架构

采用一主多从的分布式架构，主节点负责管理功能，从节点专注代理服务，实现高可用和负载分散

主节点 (Master)

Web 管理界面、配置管理、统计分析

从节点 (Slave)

专注 API 代理服务，支持水平扩展

共享存储

统一的 MySQL 和 Redis 集群

部署要求

重要提示

集群部署时 数据库 和 Redis 是必需的，用于分布式协调和状态同步

基础设施要求

数据库集群

  • • MySQL 8.2+ 高可用集群
  • • 支持主从复制或 Galera 集群
  • • 建议配置读写分离
  • • 定期备份和故障恢复机制

缓存集群

  • • Redis 集群或哨兵模式
  • • 用于分布式锁和状态同步
  • • 配置持久化和故障转移
  • • 监控内存使用和性能

部署步骤

1

准备共享基础设施

部署 MySQL 集群

建议使用云数据库集群服务，或自行部署独立的 MySQL 集群。

部署 Redis 集群

建议使用 Redis Sentinel 或集群模式，确保高可用性和数据一致性。

2

节点docker-compose.yml内容参考（主从节点一致）

services:
  gpt-load:
    image: ghcr.io/tbphp/gpt-load:latest
    container_name: gpt-load
    ports:
      - "${PORT:-3001}:${PORT:-3001}"
    env_file:
      - .env
    restart: always
    stop_grace_period: ${SERVER_GRACEFUL_SHUTDOWN_TIMEOUT:-10}s
    healthcheck:
      test: wget -q --spider -T 10 -O /dev/null http://localhost:${PORT:-3001}/health
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

使用配置区分主从节点

IS_SLAVE=true

主节点不配置，或者配置为IS_SLAVE=false。从节点配置为IS_SLAVE=true。

保证整个集群只有一个主节点。

3

配置负载均衡

使用 Nginx 或其他负载均衡器分发请求到不同的从节点

Nginx 配置示例

# nginx.conf
upstream gpt_load_cluster {
    server master-node-ip:3001 weight=3;
    server slave-node1-ip:3001 weight=5;
    server slave-node2-ip:3001 weight=5;
    # 可添加更多从节点
}

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://gpt_load_cluster;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # 如果使用CF或其他代理服务，需要设置真实IP
        set_real_ip_from 0.0.0.0/0;
        real_ip_header X-Forwarded-For;
    }
}

配置管理

统一配置要求

AUTH_KEY必须相同
DATABASE_DSN必须相同
REDIS_DSN必须相同
IS_SLAVE从节点为 true

动态配置同步

  • • 系统设置存储在 MySQL 中自动同步
  • • 分组配置实时推送到所有节点
  • • 密钥状态通过 Redis 实时共享
  • • 配置变更无需重启服务

监控与运维

健康检查

节点健康状态

# 检查节点状态
curl http://node:3001/health

# 响应示例
{
  "status": "healthy",
  "timestamp": "2025-07-15T12:56:00Z",
  "uptime": "11.822967ms"
}

集群状态监控

  • • 监控各节点请求量和响应时间
  • • 检查数据库和 Redis 连接状态

扩容与缩容

水平扩容

  • • 按需增加从节点数量
  • • 更新负载均衡器配置
  • • 新节点自动同步配置
  • • 无缝接入现有服务

优雅下线

  • • 从负载均衡器移除节点
  • • 等待现有请求处理完成
  • • 发送停止信号给容器
  • • 清理相关资源和日志

最佳实践

✅ 推荐做法

  • • 使用容器编排工具 (Docker Swarm/K8s)
  • • 配置数据库和 Redis 的高可用
  • • 设置完整的监控和告警系统
  • • 定期备份配置和数据
  • • 使用配置管理工具统一部署
  • • 实施蓝绿部署或滚动更新

❌ 避免做法

  • • 单点故障的数据库或缓存
  • • 节点间配置不一致
  • • 忽略网络延迟和分区问题
  • • 缺乏监控和日志收集
  • • 手动管理大量节点配置
  • • 直接修改生产环境配置