Cluster 概览
One API Pro 的「多节点去中心化部署」是什么、什么时候用、跟普通多副本有什么区别。
Cluster 是什么
Cluster 模式 = 多个 One API Pro 实例，每个实例自带 MySQL + Redis，节点间通过 HTTP 主动推送同步数据。
没有中心节点、没有共享数据库。每个节点都是平等的：你访问哪个节点，就由那个节点服务。
跟「多实例 + 共享 DB」的区别
| 维度 | Cluster 模式 | 多实例 + 共享 DB（传统） |
|---|---|---|
| 数据库 | 每个节点独立 MySQL | 所有实例共享一个 MySQL |
| Redis | 每个节点独立 | 共享 |
| 数据一致性 | 最终一致（基于时间戳） | 强一致 |
| 跨地域部署 | ✅ 友好（本地节点就近服务） | 跨地域延迟高 |
| 节点离线容忍 | 离线期间变更不补传 | 节点随时可下线 |
| 适合场景 | 多机房 / 跨地域 / 边缘节点 | 单机房多副本 |
简而言之：Cluster = 高可用 + 跨地域；多副本 = 单机房内负载分担。
什么时候该用 Cluster
✅ 建议用：
- 多机房 / 多区域 / 跨地域容灾
- 业务对延迟敏感，希望就近接入
- 不想让所有流量都回中心机房
❌ 不需要用：
- 单机房、中小流量：单实例 + docker-compose 就够了
- 已经有 K8s 多副本 + 共享 DB：那是另一个方案，不要混用
- 强一致 / 分布式事务：One API Pro 不实现跨节点事务
它能做什么
- 去中心化：节点对等，无中心协调器
- 自动同步：任一节点改一条记录，自动推到所有其他节点
- 冲突可收敛：基于
updated_at的最后写入胜出，最终一致 - 限流聚合：渠道的并发 / RPM 计数按节点同步，全局状态可跨节点聚合
- 零侵入：通过数据库触发器自动捕获变更，业务代码不用改
它不能做什么 / 已知限制
- 节点离线期间产生的变更不会回填：节点恢复后需要从存活节点手工
mysqldump同步一次 - 新节点只能看到加入之后的变更历史：加入前的数据需要手工导入
- 日志表很大时建议关掉同步：在节点环境变量设
CLUSTER_SYNC_LOGS=false
同步哪些数据
账号、Token、渠道、套餐、订阅、兑换码、系统设置、调用日志（可选）等。
不同步：节点注册表本身（由发现机制维护）。
架构示意
┌─────────────┐
│ Nginx/LB │ ← 入口，ip_hash 负载均衡
└──────┬──────┘
│
┌───────────────┼───────────────┐
│ │ │
┌────┴────┐ ┌────┴────┐ ┌────┴────┐
│ Node A │ │ Node B │ │ Node C │
│ one-api │ │ one-api │ │ one-api │
│ MySQL │ │ MySQL │ │ MySQL │
│ Redis │ │ Redis │ │ Redis │
└────┬────┘ └────┬────┘ └────┬────┘
│ │ │
└──────── HTTP push 同步 ────────┘任一节点的数据变更都会主动推送到所有存活节点。