mgmt/docs/CONSUL_ARCHITECTURE.md

Consul 集群架构设计

当前架构

Consul Servers (3个)

• master (100.117.106.136) - 韩国，当前 Leader
• warden (100.122.197.112) - 北京，Voter
• ash3c (100.116.80.94) - 美国，Voter

Consul Clients (1个+)

• hcp1 (100.97.62.111) - 北京，系统级 Client

架构优势

✅ 当前设计的优点：

1. 高可用 - 3个 Server 可容忍 1个故障
2. 地理分布 - 跨三个地区，容灾能力强
3. 性能优化 - 每个地区有本地 Server
4. 扩展性 - Client 可按需添加

✅ 为什么 hcp1 作为 Client 是正确的：

1. 服务就近注册 - Traefik 运行在 hcp1，本地 Client 效率最高
2. 减少网络延迟 - 避免跨网络的服务注册
3. 健康检查优化 - 本地 Client 可以更准确地检查服务状态
4. 故障隔离 - hcp1 Client 故障不影响集群共识

扩展建议

🎯 理想的 Client 部署：

每个运行业务服务的节点都应该有 Consul Client：

┌─────────────┬─────────────┬─────────────┐
│   Server    │   Client    │   业务服务   │
├─────────────┼─────────────┼─────────────┤
│ master      │ ✓ (内置)    │ Consul      │
│ warden      │ ✓ (内置)    │ Consul      │
│ ash3c       │ ✓ (内置)    │ Consul      │
│ hcp1        │ ✓ (独立)    │ Traefik     │
│ 其他节点... │ 建议添加     │ 其他服务... │
└─────────────┴─────────────┴─────────────┘

🔧 Client 配置标准：

# hcp1 的 Consul Client 配置 (/etc/consul.d/consul.hcl)
datacenter = "dc1"
data_dir = "/opt/consul"
log_level = "INFO"
node_name = "hcp1"
bind_addr = "100.97.62.111"

# 连接到所有 Server
retry_join = [
  "100.117.106.136",  # master
  "100.122.197.112",  # warden  
  "100.116.80.94"     # ash3c
]

# Client 模式
server = false
ui_config {
  enabled = false  # Client 不需要 UI
}

# 服务发现和健康检查
ports {
  grpc = 8502
  http = 8500
}

connect {
  enabled = true
}

服务注册策略

🎯 推荐方案：

1. Nomad 自动注册 (首选)

   • 通过 Nomad 的 consul 配置
   • 自动处理服务生命周期
   • 与部署流程集成

2. 本地 Client 注册 (当前方案)

   • 通过本地 Consul Client
   • 手动管理，但更灵活
   • 适合复杂的注册逻辑

3. Catalog API 注册 (应急方案)

   • 直接通过 Consul API
   • 绕过同步问题
   • 用于故障恢复

🔄 迁移到 Nomad 注册：

# 在 Nomad Client 配置中
consul {
  address = "127.0.0.1:8500"  # 本地 Consul Client
  server_service_name = "nomad"
  client_service_name = "nomad-client"
  auto_advertise = true
  server_auto_join = false
  client_auto_join = true
}

监控和维护

📊 关键指标：

• Raft Index 同步 - 确保所有 Server 数据一致
• Client 连接状态 - 监控 Client 与 Server 的连接
• 服务注册延迟 - 跟踪注册到可发现的时间
• 健康检查状态 - 监控服务健康状态

🛠️ 维护脚本：

# 集群健康检查
./scripts/consul-cluster-health.sh

# 服务同步验证  
./scripts/verify-service-sync.sh

# 故障恢复
./scripts/consul-recovery.sh

故障处理

🚨 常见问题：

1. Server 故障 - 自动 failover，无需干预
2. Client 断连 - 重启 Client，自动重连
3. 服务同步问题 - 使用 Catalog API 强制同步
4. 网络分区 - Raft 算法自动处理

🔧 恢复步骤：

1. 检查集群状态
2. 验证网络连通性
3. 重启有问题的组件
4. 强制重新注册服务

---

结论: 当前架构设计合理，hcp1 作为 Client 是正确的选择。建议保持现有架构，并考虑为其他业务节点添加 Consul Client。