通过命令行上传文件夹至IPFS返回哈希，但网络中不存在该文件夹

可能的原因 #

1. 节点连通性不足：你部署在Apache服务器上的IPFS节点可能缺少足够的对等节点，或者服务器的防火墙/安全组限制了IPFS默认端口（4001 TCP/UDP），导致其他节点（包括公共网关）无法主动连接到你的节点。小文件体积小，容易被网络中的节点临时缓存，所以偶尔能访问；但大文件夹包含多个分片，需要稳定的节点提供数据才能被网关获取。
2. 固定操作未完全生效：虽然执行了ipfs pin add --recursive，但如果节点磁盘空间不足、固定过程中断，可能导致部分文件分片未被成功固定。本地节点缺少完整分片的话，网关请求时自然无法获取到完整内容。
3. 公共网关缓存机制限制：ipfs.io这类公共网关不会永久缓存所有内容，只有当请求触发后，网关能从网络中获取到完整数据时才会临时缓存。如果你的节点离线或无法被网关访问，网关就无法拉取数据，导致加载失败。
4. 分片传播不充分：文件夹会被拆分为多个DAG节点，大视频文件本身也会被分片存储。如果这些分片没有充分传播到IPFS网络中，网关请求时找不到足够的分片来重组内容，就会一直处于加载状态。

解决方法 #

• 检查并优化节点连通性
  • 执行ipfs swarm peers查看当前连接的对等节点数，正常应保持在几十个以上。如果数量过少：
    • 确认服务器的4001端口（TCP/UDP）在防火墙、安全组中对外开放，允许外部节点主动连接。
    • 执行ipfs id查看节点地址，确保包含公网IP；如果只有内网地址，需配置NAT端口转发，或启用IPFS中继服务（执行ipfs config --json Swarm.EnableAutoRelay true并重启节点）。
• 验证固定操作的完整性
  • 执行ipfs pin ls --type=recursive {FOLDER HASH}，确认文件夹及其所有子资源都被标记为递归固定。若有缺失，重新执行ipfs pin add --recursive {FOLDER HASH}，等待命令完全执行（大文件夹可能耗时较久）。
  • 用df -h检查服务器磁盘空间，确保有足够容量存储固定的内容，避免因磁盘满导致固定失败。
• 保持节点持续在线
  • 确保IPFS节点始终运行且网络稳定。公共网关只有在请求时能找到提供数据的节点（你的节点或缓存了数据的其他节点），才能返回内容。如果你的节点频繁离线，网关无法获取数据，自然无法访问。
• 手动触发网关缓存
  • 上传并固定文件夹后，先在本地执行ipfs cat {FOLDER HASH}/video.mp4 > /dev/null，确保所有分片都已加载到本地节点。
  • 多次用浏览器或curl请求网关的文件地址（如ipfs.io/ipfs/{FOLDER HASH}/video.mp4），触发网关拉取并缓存完整数据。
• 确认上传内容完整性
  • 执行ipfs get {FOLDER HASH}，如果能成功下载并还原整个文件夹，说明本地节点的内容完整。若下载失败或文件损坏，重新执行ipfs add --recursive folder上传，确保过程无中断。

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