mgmt/docs/consul-cluster-troubleshooting.md

Consul 集群故障排除指南

问题诊断

发现的问题

1. DNS 解析失败：服务间无法通过服务名相互发现
2. 网络连通性问题：ash3c 节点网络配置异常（地址显示为 0.0.0.0）
3. 跨节点通信失败：no route to host 错误
4. 集群无法形成：持续的 "No cluster leader" 错误

根本原因

• Docker Swarm overlay 网络在跨节点环境中的服务发现机制存在问题
• ash3c 节点的网络配置可能有问题
• 防火墙或网络策略可能阻止了 Consul 集群通信端口

解决方案

方案 1：单节点 Consul（临时解决方案）

文件: swarm/stacks/consul-single-node.yml 优点: 简单、可靠、立即可用 缺点: 没有高可用性

docker stack deploy -c swarm/stacks/consul-single-node.yml consul

方案 2：使用主机网络的集群配置

文件: swarm/stacks/consul-cluster-host-network.yml 优点: 绕过 overlay 网络问题 缺点: 需要手动配置 IP 地址

方案 3：修复后的 overlay 网络配置

文件: swarm/stacks/consul-cluster-fixed.yml 优点: 使用 Docker 原生网络 缺点: 需要解决底层网络问题

方案 4：macvlan 网络配置

文件: swarm/stacks/consul-cluster-macvlan.yml 优点: 直接使用物理网络 缺点: 需要网络管理员权限和配置

网络诊断步骤

1. 检查节点状态

docker node ls
docker node inspect <node-name> --format '{{.Status.Addr}}'

2. 检查网络连通性

# 在 master 节点上测试到 ash3c 的连通性
ping <ash3c-ip>
telnet <ash3c-ip> 8301

3. 检查防火墙设置

# 确保以下端口开放
# 8300: Consul server RPC
# 8301: Consul Serf LAN
# 8302: Consul Serf WAN
# 8500: Consul HTTP API
# 8600: Consul DNS

4. 检查 Docker Swarm 网络

docker network ls
docker network inspect <network-name>

推荐的修复流程

立即解决方案（单节点）

1. 部署单节点 Consul 以恢复服务
2. 验证基本功能正常

长期解决方案（集群）

1. 修复 ash3c 节点的网络配置
2. 确保节点间网络连通性
3. 配置防火墙规则
4. 重新部署集群配置

验证步骤

单节点验证

# 检查服务状态
docker service ls | grep consul

# 检查日志
docker service logs consul_consul

# 访问 Web UI
curl http://localhost:8500/v1/status/leader

集群验证

# 检查集群成员
docker exec <consul-container> consul members

# 检查领导者
docker exec <consul-container> consul operator raft list-peers

常见问题

Q: 为什么服务发现不工作？

A: Docker Swarm 的 overlay 网络在某些配置下可能存在 DNS 解析问题，特别是跨节点通信时。

Q: 如何选择合适的网络方案？

A:

• 开发/测试环境：使用单节点或 overlay 网络
• 生产环境：推荐使用 macvlan 或主机网络以获得更好的性能和可靠性

Q: 集群恢复后数据会丢失吗？

A: 如果使用了持久化卷，数据不会丢失。但建议在修复前备份重要数据。

监控和维护

健康检查

# 定期检查集群状态
consul members
consul operator raft list-peers

日志监控

# 监控关键错误
docker service logs consul_consul | grep -E "(ERROR|WARN)"

性能监控

• 监控 Consul 的 HTTP API 响应时间
• 检查集群同步延迟
• 监控网络连接数

联系支持

如果问题持续存在，请提供以下信息：

1. Docker 版本和 Swarm 配置
2. 网络拓扑图
3. 完整的服务日志
4. 节点间网络测试结果