ACI部署IPFS节点跨节点无法连通、数据不可访问问题咨询

跨节点无法检索CID的核心原因是默认IPFS配置与ACI网络特性不匹配，集中在三点：

• ACI默认不会为容器实例配置公网端口映射，IPFS节点间P2P通信用的4001端口如果没有显式暴露，其他节点根本无法寻址到你的节点，对等连接无法建立
• 默认启动的IPFS节点只会连接内置公共引导节点，不会主动和你自有部署的跨区域节点建立直连
• pubsub能力默认处于关闭状态，新写入的CID不会主动向对等节点广播，单靠全网DHT检索内容，在节点连接数不足的场景下要么超时要么完全查不到目标内容

1. 修正ACI部署的网络与端口配置 #

部署IPFS容器时必须为实例分配公网IP，同时显式暴露以下端口：

• 5001/tcp：API端口，供ipfs-http-client脚本调用，不要将这个端口对公网放行，仅开放给同VPC内的可信服务访问，该端口拥有节点全部操作权限，公网暴露会有严重安全风险
• 8080/tcp：HTTP网关端口，供普通HTTP客户端直接访问IPFS内容，可以对公网放行
• 4001/tcp、4001/udp：Swarm P2P通信端口，是节点间建连的核心端口，必须同时映射TCP和UDP协议，否则QUIC传输无法生效，跨区域连接延迟会升高数倍

注意：ACI配置端口映射时要给4001端口配置固定的端口号，不要用随机端口，否则其他节点无法通过固定地址找到你的节点。

2. 调整IPFS节点启动配置 #

两个区域的节点启动时都追加以下参数，覆盖默认配置：

ipfs daemon \
  --enable-pubsub-experiment \
  --enable-namesys-pubsub \
  --routing=dhtclient

参数说明：

• --enable-pubsub-experiment：开启pubsub核心能力
• --enable-namesys-pubsub：开启基于pubsub的内容路由广播，新写入的CID会主动向已连接的对等节点推送
• --routing=dhtclient：作为DHT客户端参与全网路由，避免作为DHT服务端占用过多ACI计算资源

启动前还需要执行两条配置命令，解决ACI的NAT网络适配问题，同时配置静态对等节点：

# 配置节点对外公告的公网地址，替换为当前节点的公网IP
ipfs config Addresses.Announce '["/ip4/<当前节点公网IP>/tcp/4001", "/ip4/<当前节点公网IP>/udp/4001/quic"]'
# 将对端区域节点的地址加入引导列表，替换为对端节点的公网IP和PeerID
ipfs bootstrap add /ip4/<对端节点公网IP>/tcp/4001/p2p/<对端节点PeerID>

两个节点互相将对方的地址加入引导列表后，启动后会第一时间建立跨区域直连，不需要等待公共节点的路由发现。

3. 验证对等连接状态 #

节点启动后，调用API检查连接是否正常：

# 调用EU节点API查看已连接的对等节点
curl http://<EU节点内网IP>:5001/api/v0/swarm/peers

如果返回的节点列表中能看到US节点的PeerID，说明跨节点直连已经建立完成。

4. 适配业务需求的代码调整 #

要实现指定对等节点列表随机选点、优先走pubsub实现数据共享的逻辑，对原有脚本做小幅修改即可：

• 客户端侧预先维护所有自有节点的API地址列表，初始化时随机选一个可用节点作为接入点
• 写入数据时主动通过pubsub广播新生成的CID，让所有订阅节点提前拉取内容，修改后的write.js示例：

// write.js
import * as IPFS from 'ipfs-http-client';

const main = async () => {
  // 节点列表，随机选一个写入
  const nodes = [
    { host: '<eu host>', port: '5001', protocol: 'http' },
    { host: '<us host>', port: '5001', protocol: 'http' }
  ]
  const randomNode = nodes[Math.floor(Math.random() * nodes.length)]
  const ipfs = IPFS.create(randomNode);

  const { cid } = await ipfs.add(
    `Hello at ${new Date().toISOString()}`,
    { pin: true } // 强制pin住内容，避免被垃圾回收清理
  );
  // 向固定topic广播CID
  await ipfs.pubsub.publish(
    'custom-ipfs-sync-topic',
    new TextEncoder().encode(cid.toString())
  )
  console.log(cid.toString());
};

main();

• 读取侧可以预先订阅同一个pubsub topic，收到CID公告后提前拉取内容到本地缓存，后续读取时直接从本地返回，延迟可以降到最低。基础版read.js不需要修改即可正常读取跨节点内容。

如果配置后仍然无法跨节点检索内容，按顺序排查：

1. 用nc -zv <对端节点公网IP> 4001命令测试两个节点的4001端口是否能跨公网连通，优先排查ACI的网络安全组规则是否放行了对应端口
2. 检查节点的Announce地址配置是否正确，NAT环境下如果不手动配置公告地址，节点会向内网其他节点广播自己的内网IP，导致对端无法连接
3. 写入内容时确认开启了pin: true选项，避免内容被节点的自动垃圾回收机制删除
4. 如果直连正常但检索慢，可以手动触发内容提供操作：写入CID后调用ipfs.dht.provide(cid)，加速全网路由记录同步

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