用途：验证私有 IPFS Cluster（Kubo）部署/基础设施本身是否正确，属部署 e2e runbook，而非 Agent 发布链路测试（后者见 kubo-publish-e2e）。
主要能力：起 3 节点集群加 Caddy 反代；生成机密后校验三 peer 成形；经 cluster 代理(:9095)上传 HTML 并断言三节点副本 PINNED；检查原生网关(:8080)/ipfs/<CID> 与 Caddy 友好路径(:8088)/artifact/<CID> 渲染；停一个 kubo 节点后仍可读；结束收摊。全程用真实 curl 与 ipfs-cluster-ctl 断言。镜像锁 kubo v0.42.0、ipfs-cluster v1.1.6、caddy:2-alpine。运行时数据在 runtime/，重启不丢，down -v 才清。
使用方式：约定 REPO=$(git rev-parse --show-toplevel)，COMPOSE="docker compose -f docker-compose.cluster.yml"，PROXY=http://localhost:9095，GW=http://localhost:8080，ART=http://localhost:8088，CTL="docker exec cl-cluster0 ipfs-cluster-ctl"。先 make secrets，再 $COMPOSE up -d，轮询代理就绪与 peers 数达 3。一键 e2e 用 make e2e（跑完自动 down）或 make e2e-keep（保留集群手测），退出码非 0 即失败并生成 runtime/e2e/<时间戳>/report.html。手动演示走 :9095 上传，用 $CTL status 看副本，停 cl-ipfs1 后复验网关返回 200。
适用场景：单宿主机三容器试验形态的部署校验、演示与排查。
限制与注意：.env 的 CLUSTER_SECRET 与 runtime/private/swarm.key 需存在且被 gitignore；起栈前须排查 8080/9094/9095/8088 端口占用；私有网须关 AutoConf，否则 daemon 崩溃重启；cluster 代理 502 多因 ipfsproxy 的 node_multiaddress 未配对；私有网下依赖种子节点加 bootstrap 互联，不可靠 mDNS；上传必须走 :9095 而非 :5001；多副本只防硬件故障，不防误删 pin，仍需备份。多主机等更广部署与运维说明见仓库内文档，此处暂未提供更细内容。