MongoDB Docker副本集连接失败如何排查？

Question

在使用Docker部署MongoDB副本集时，常见问题为“节点间无法通信导致副本集初始化失败”。具体表现为：mongod实例启动正常，但执行rs.initiate()后提示“Failed to reach primary”或“connection refused”。此问题通常由Docker容器间网络配置不当引起，如未使用自定义桥接网络、host映射错误或容器hostname与replica set成员配置不一致。此外，防火墙限制、bindIp未包含容器内IP或Docker卷权限问题也可能导致连接失败。需结合日志（docker logs）排查网络连通性、端口暴露及副本集成员配置的准确性，确保各节点可通过服务名或IP相互访问。

Answer 1

使用Docker部署MongoDB副本集时节点间通信失败的深度排查与解决方案

1. 问题现象与初步诊断

在基于Docker部署MongoDB副本集时，常见的故障表现为：所有mongod容器均正常启动，日志中未出现致命错误，但执行rs.initiate()后返回“Failed to reach primary”或“connection refused”。该问题并非MongoDB本身崩溃，而是集群成员之间无法建立有效通信。

典型错误日志片段示例如下：

2025-04-05T10:12:33.789+0000 I NETWORK  [replication-2] Failed to connect to 172.20.0.3:27017 after 5000ms: Connection refused
2025-04-05T10:12:33.790+0000 E REPL     [replexec-0] Error in heartbeat (requestId: 3) to mongo2:27017; err: Timed out waiting for connection
    

此类日志表明，尽管服务进程运行中，但网络层面存在阻断。

2. 常见原因分类与层级分析

根据实际运维经验，可将导致通信失败的原因按层次划分为以下几类：

1. 网络隔离：容器处于默认bridge网络，无法通过服务名解析彼此。
2. DNS/Hostname不匹配：mongod配置中的replSet成员使用了hostname，但容器hostname未正确设置或DNS不可达。
3. bindIp配置不当：mongod仅绑定到127.0.0.1，拒绝来自容器网络的连接请求。
4. 防火墙或安全组限制：宿主机iptables规则或云平台安全策略阻止端口通信。
5. 卷权限问题：数据目录权限不足导致某些内部服务（如replication）无法写入状态文件。
6. Docker Compose服务依赖顺序错乱：初始化脚本在其他节点尚未就绪时提前执行rs.initiate()。
7. IP地址动态变化：使用自定义网络但未固定IP分配，导致配置失效。
8. 端口未正确暴露：Dockerfile或compose文件中缺少ports声明。
9. TLS/SSL配置冲突：启用了加密通信但证书未共享或验证失败。
10. 仲裁机制异常：两节点环境中无明确主节点选举能力，陷入僵局。

3. 网络架构设计建议

为确保容器间可靠通信，必须使用Docker自定义桥接网络。该网络支持内置DNS解析，允许通过服务名称进行访问。

网络类型	支持DNS解析	推荐用于副本集	说明
default bridge	❌	❌	仅支持IP通信，hostname无法解析
custom bridge	✅	✅	支持服务名互访，推荐方案
host network	✅（直接使用宿主机）	⚠️（有限场景）	牺牲隔离性换取性能，安全性较低
overlay network	✅	✅（多主机Swarm）	适用于跨节点集群部署

4. 典型Docker Compose配置示例

以下是一个经过验证的docker-compose.yml配置，确保网络、hostname、卷和环境变量协同工作：

version: '3.8'
services:
  mongo1:
    image: mongo:6.0
    hostname: mongo1
    container_name: mongo1
    command: [--replSet, "rs0", --bind_ip, "0.0.0.0", --port, "27017"]
    environment:
      MONGO_INITDB_ROOT_USERNAME: admin
      MONGO_INITDB_ROOT_PASSWORD: example
    volumes:
      - ./data/db1:/data/db
      - ./scripts/init-replica.js:/docker-entrypoint-initdb.d/init-replica.js:ro
    networks:
      mongo-net:
        ipv4_address: 172.20.0.10

  mongo2:
    image: mongo:6.0
    hostname: mongo2
    container_name: mongo2
    command: [--replSet, "rs0", --bind_ip, "0.0.0.0", --port, "27017"]
    volumes:
      - ./data/db2:/data/db
    networks:
      mongo-net:
        ipv4_address: 172.20.0.11

  mongo3:
    image: mongo:6.0
    hostname: mongo3
    container_name: mongo3
    command: [--replSet, "rs0", --bind_ip, "0.0.0.0", --port, "27017"]
    volumes:
      - ./data/db3:/data/db
    networks:
      mongo-net:
        ipv4_address: 172.20.0.12

networks:
  mongo-net:
    driver: bridge
    ipam:
      config:
        - subnet: 172.20.0.0/24
    

5. 排查流程图（Mermaid格式）

graph TD
            A[副本集初始化失败] --> B{检查docker logs}
            B --> C[是否存在connection refused?]
            C -->|Yes| D[检查目标容器是否运行]
            D --> E[确认端口是否暴露]
            E --> F[测试telnet IP PORT]
            F --> G[成功?]
            G -->|No| H[检查防火墙/Docker网络]
            G -->|Yes| I[进入Mongo Shell测试connect]
            I --> J[rs.status()查看成员状态]
            J --> K[检查replSet配置中host字段是否匹配容器hostname或IP]
            K --> L[确认bind_ip包含0.0.0.0或容器内IP]
            L --> M[修复并重启]
            M --> N[重新initiate]

6. 关键配置注意事项

• 务必设置--bind_ip 0.0.0.0：否则mongod只监听localhost，外部容器无法连接。
• hostname必须与replSet成员定义一致：例如rs.add("mongo2:27017")要求容器hostname为mongo2。
• 避免使用localhost或127.0.0.1作为成员地址：每个容器的loopback是独立的。
• 初始化脚本应延迟执行：可通过wait-for-it.sh等待其他节点端口开放后再运行rs.initiate()。
• 数据卷权限需为mongod用户可写：通常chown -R 999:999 /path/to/data。
• 启用日志记录以辅助调试：添加--logpath /var/log/mongodb/mongod.log便于追踪。