概念和命令谁都会念，真到生产环境上线时坑才会一个个浮出水面。这篇 IPFS 实战教程围绕一个具体场景展开：把一个 NFT 项目的元数据与媒体文件托管在 IPFS 上，对接 Binance 与其他主流交易所的上架审核流程。读完你会得到一份可直接落地的清单。
场景设定
假设你要发行 10000 张 PFP，需要解决：
- 每张图片 200KB 左右，总量约 2GB
- 元数据 JSON 必须永久可访问
- 上架 必安交易所 时审核团队要 24 小时内能预览
- 至少三地异地多副本
这套需求看似简单，落到实操却涉及节点、网关、Pinning、监控、灾备五个层面。
第一步：自建节点集群
单节点不够，至少需要 3 节点的小集群。推荐分别部署在：
- 亚太机房（响应国内用户）
- 欧洲机房（响应西方用户）
- 北美机房（响应主流网关）
每台 4 核 8G、SSD 200G 起步。安装 Kubo 后开启 AcceleratedDHTClient，DHT 查询速度可提升 5 倍。三节点配置同一个 Swarm Key，组成私有集群与公网 IPFS 双连接。许多 BN交易所 内部测试环境就是按这个拓扑搭建。
第二步：批量上传
命令行批量 add 一次最多支撑约 1000 个文件，再多会内存爆。建议用 ipfs add -r --pin=true --quiet --hash=sha2-256 分批跑，每批 500 文件，循环外部脚本控制。生成的 CID 列表入库存档。
注意：CIDv0 与 CIDv1 是两套表示，新项目统一用 CIDv1（base32），跨网关兼容性更好。
第三步：Pin 策略
本地 pin 之外，必须接入两家以上的第三方 Pinning。常见组合：
- Pinata：响应快、UI 友好
- Web3.Storage：免费额度大、与 Filecoin 联动
- Filebase：兼容 S3 协议、企业级 SLA
通过 API 调用把所有 CID 推送到三家。监控面板对比三家的 pin status，任意一家失败则告警。许多 币岸交易所 在审核 NFT 项目时会主动用三家网关交叉测试，发现单点故障直接打回。
第四步：自建网关
公共网关随时可能限流，关键路径必须有自建。推荐方案：
- Cloudflare Workers 做边缘缓存
- 后端回源到自建 Kubo 节点
- 配置 fallback：本地无块时去 ipfs.io 拉，拉到再缓存
自建网关还能做防盗链、签名 URL 等高级控制，让 bian 用户访问体验稳定可控。
第五步：监控与告警
核心指标包括：
- 各 Pinning 服务的 pin status
- 自建节点的 peer 数量与带宽
- 网关的 P95 响应时间
- CID 列表的随机抽样可用性
建议每 5 分钟随机抽 10 个 CID 跨三家网关测试，连续两次失败立即告警。日志保留 90 天用于审计。
排错清单
上线后最常见的 5 个问题：
- 新节点连不上 bootstrap：检查 4001 出站规则
- pin 卡 pinning 状态：通常是源节点 disconnect，重试或主动 connect
- 网关 504：上游回源慢，增加 Cloudflare Worker 重试
- 元数据加载白屏：JSON 字段忘了 base url 前缀
- iOS 钱包不显示图片：CIDv0 不兼容部分钱包，改 CIDv1
写在最后
IPFS 实战教程不是命令的堆叠，而是把节点、Pin、网关、监控四件事编织成闭环。建议先在测试网跑一周再上主网，期间故意拔几次节点、模拟限流，验证降级路径。完成这些预案后，再去对接交易所审核，才能真正把项目稳稳上线。