IPFS Cluster节点无法互相发现的原因排查咨询

1. 校验Cluster核心配置一致性 #

• 检查两个节点的~/.ipfs-cluster/service.json文件：
  • 确认cluster_secret完全匹配，注意是base64编码值，手动复制时避免漏字符或多余空格
  • 确保ipfs_peer_id与对应IPFS节点的peer id一致（用ipfs id命令查看）
  • 验证listen_multiaddresses包含可被对方访问的地址，比如/ip4/节点公网/内网IP/tcp/9096、/ip4/节点公网/内网IP/udp/9096/quic-v1，禁止仅绑定127.0.0.1

2. 确认引导节点配置与状态 #

• 在bootstrap集群节点执行ipfs-cluster-ctl peers ls，确认自身状态正常，记录完整的集群节点multiaddress，格式为/ip4/xxx.xxx.xxx.xxx/tcp/9096/p2p/<bootstrap-cluster-peer-id>
• 在client集群节点的service.json中，确保bootstrap字段填入上述完整multiaddress，而非仅主机名或IP

3. 测试集群端口连通性 #

• 在client节点测试TCP端口连通：

  nc -zv <bootstrap节点IP> 9096
  

• 测试UDP端口连通：

  nc -zvu <bootstrap节点IP> 9096
  

  若不通，需确认防火墙/安全组规则是否真正开放端口，包括云服务器安全组、本地iptables/nftables规则

4. 验证Cluster与本地IPFS节点的关联 #

• 执行ipfs-cluster-ctl id，确认Cluster能正常连接本地IPFS节点
• 若报错，检查service.json中ipfs_http_api地址是否正确（默认http://127.0.0.1:5001），以及IPFS节点API是否允许本地访问

5. 通过Debug日志定位问题 #

• 启动Cluster服务时添加--debug参数获取详细日志：

  ipfs-cluster-service daemon --debug
  

  重点排查包含peer discovery、bootstrap、connection failed的日志条目，比如是否存在"invalid cluster secret"或"could not connect to bootstrap peer"等明确错误

6. 重置Cluster节点状态（谨慎操作） #

若以上步骤无效，可尝试重置client节点：

• 停止服务：ipfs-cluster-service stop
• 删除Cluster数据目录：rm -rf ~/.ipfs-cluster
• 重新初始化并指定bootstrap节点：

  ipfs-cluster-service init --bootstrap /ip4/<bootstrap节点IP>/tcp/9096/p2p/<bootstrap-cluster-peer-id>
  

• 启动服务后再次测试节点发现

内容的提问来源于stack exchange，提问作者Test