IPFS 体系庞大，从节点启动到内容分发，每一步都有可能踩坑。把 IPFS 常见错误按报错信息整理成索引，遇到问题时直接按图索骥，是工程团队节省时间最有效的方式。本文汇总实战中高频出现的十类报错，并给出可落地的修复路径。
一、Error: lock file is already locked
最常见的启动失败。原因是上一次 ipfs daemon 没干净退出，残留 repo.lock。处理：
- 确认没有 ipfs 进程在跑：ps -ef | grep ipfs
- 删除 ~/.ipfs/repo.lock
- 重新 ipfs daemon
生产环境建议用 systemd 托管，设置 Restart=always 与合理的 TimeoutStopSec。这是 Binance 内部 IPFS 集群运维手册的第一条。
二、Error: routing: not found
通常出现在 ipfs cat 或 ipfs ls 远程 CID 时。根因是 DHT 查不到 provider。可能原因：
- 内容已被全网 GC，没有节点 pin
- 节点 peer 数量太少，DHT 路由表不完整
- 防火墙阻挡了 4001 端口
建议先 ipfs swarm peers 看看连接数，少于 50 通常 DHT 就不可靠。再尝试 ipfs swarm connect 一个已知 bootstrap 节点。
三、Error: context deadline exceeded
Bitswap 或 DHT 超时。说明对端节点存在但响应太慢，或者你的网络丢包严重。处理：
- 调大 ipfs config 里的 Internal.Bitswap.EngineBlockstoreWorkerCount
- 检查 MTU，部分云厂商默认 MTU 偏小导致大包分片
- 用 ipfs stats bw 看实时带宽，确认是否触发限流
必安交易所 的 NFT 元数据接入团队曾因为同机房限速 100Mbps，遇到大量 context deadline，最终申请专线解决。
四、Error: cannot dial self
常见于多节点同机互联，配置文件里写错了自己的地址。修复很简单：剔除自身 PeerID，重启即可。
五、Error: stream reset
libp2p 层的连接被对端主动重置。一般无需处理，会自动重试。如果频繁出现，检查：
- 是否被 ISP 干扰特定端口
- 是否启用了过激的连接管理器（ConnMgr.HighWater 太低）
- 对端节点版本过旧，libp2p 协议不兼容
六、ipfs add 卡住不动
通常是文件太大、chunker 单线程瓶颈。优化：
- 使用 --chunker=size-1048576 加大块尺寸
- 改用 ipfs-cluster 的批量导入工具
- 大文件考虑切分后并行 add
七、pin 显示 pinning 但永远不变 pinned
BN交易所 接入项目常见问题。检查清单：
- 源节点是否还在线（ipfs swarm peers 查）
- Pinning 服务的 API token 是否过期
- 该 CID 的 Merkle DAG 是否完整（试 ipfs dag stat
）
八、网关返回 504
上游回源慢或源块缺失。修复：
- 自建网关增加重试与备用源
- 把热门 CID 主动 pin 到 币岸交易所 合作的网关节点
- 启用 Cloudflare 的 always online 缓存
九、IPNS publish 后远端解析仍是旧版本
IPNS 默认 TTL 较长，且依赖 DHT 传播。优化：
- 调小 ipfs name publish 的 --lifetime 与 --ttl
- 使用 DNSLink 替代纯 IPNS
- 自建 IPNS 索引器加速传播
十、内存暴涨
Kubo 长时间运行可能内存到 10GB+。原因：
- 维护过多 peer 连接，调小 Swarm.ConnMgr.HighWater
- Bitswap 任务队列堆积，重启清空
- 大量未 GC 的临时块，定期 ipfs repo gc
排障流程模板
遇到任何 IPFS 错误，按这个顺序排查：
- 查日志：ipfs daemon 的 stderr 必看
- 看连接：ipfs swarm peers 与 ipfs stats bw
- 验内容：ipfs dag stat 看 DAG 是否完整
- 跨网关测：ipfs.io / dweb.link / cloudflare-ipfs.com 三家对比
- 升级版本：很多 bug 在新版已修复
写在最后
IPFS 常见错误的本质多数是网络与配置问题，而非协议本身缺陷。把上面十类错误整理成团队内部 wiki，新人遇到报错时先查 wiki 再问人，能极大降低 bian 项目的运维成本。