Kubo HTTP Gateway 缓存控制测试夹具深度解析t0116-gateway-cache 数据集生成与验证【免费下载链接】kuboIPFS implementation in Go: a daemon that stores and serves content-addressed data, with a CLI, HTTP Gateway, and RPC API项目地址: https://gitcode.com/GitHub_Trending/ku/kubo本指南围绕 KuboIPFS 的 Go 实现仓库中test/sharness/t0116-gateway-cache/README.md所记录的测试数据集展开逐条讲解fixtures.car与配套 IPNS 记录是如何生成的、各路径层级 CID 的含义以及 sharness 测试套件 t0116-gateway-cache.sh 如何消费这些夹具来验证 HTTP Gateway 的缓存控制Etag、Cache-Control、X-Ipfs-Roots语义。读完本文你将能够复现该数据集的完整构建流程理解逻辑根logical root这一缓存设计核心并掌握如何基于同一夹具扩展出属于自己的 Gateway 缓存回归测试。从 fixtures.car 到缓存语义一个测试套件的定位Kubo 的 HTTP Gateway 在返回内容时会针对不同响应类型生成不同的Etag并配合If-None-Match、Cache-Control与X-Ipfs-Roots响应头让浏览器、CDN 与负载均衡器能够对 IPFS 内容做精确的缓存与失效判断。为了验证这套语义仓库在 test/sharness/t0116-gateway-cache.sh 中实现了一个独立的 sharness 测试套件其测试数据fixture则固化在 test/sharness/t0116-gateway-cache/ 目录下fixtures.car一个原始的 CARv1 归档内含一棵三级目录root2/root3/root4/index.html的全部区块k51qzi5uqu5dlxdsdu5fpuu7h69wu4ohp32iwm9pdt9nq3y5rpn3ln9j12zfhe.ipns-record与该目录 CID 绑定的 IPNS 记录有效期长达 100 年用于构造/ipns/路径的测试场景。README.md 完整记录了这套夹具的来源它由 ipfs 版本0.21.0-devcommit03a98280e3e642774776cd3d0435ab53e5dfa867通过一组可复现的 CLI 命令生成。数据集的规模被刻意设计得很小——只有一个index.html文件内容仅为hello——目的是让测试关注点完全集中在不同路径形态下的缓存响应头上而不是内容本身的传输。夹具清单CAR 文件与 IPNS 记录文件说明fixtures.car原始 CARv1 归档包含从 ROOT1 到index.html的整棵 DAG测试通过ipfs dag import导入${TEST_IPNS_ID}.ipns-record指向/ipfs/$ROOT1_CID的 IPNS 记录有效期为 100 年测试通过ipfs routing put写入本地路由表之所以同时准备 CAR 与 IPNS 记录是因为缓存控制语义需要覆盖两类内容路径/ipfs/cid/...直接按内容寻址/ipns/id/...先经 IPNS 解析到内容根再按路径展开。两份夹具共同保证了测试可以在完全不联网test_launch_ipfs_daemon_without_network的环境下运行这也是 sharness 测试一贯追求的可重复性。数据集生成全流程README 给出的生成脚本以逐级目录 逐层 CID 的方式组织核心目的是让每个路径段都对应一个可独立引用的 CID。下面按步骤拆解每条命令的实际作用。构建目录与内容mkdir -p root2/root3/root4 echo hello root2/root3/root4/index.html先创建一个三级嵌套目录并在最深层放入内容为hello的index.html。这里刻意使用最朴素的文件布局只有唯一的叶子文件因此整棵 DAG 的拓扑完全由目录节点决定后续所有 CID 都具有教科书式的确定性。逐层解析路径锁定各层级 CIDROOT1_CID$(ipfs add -Qrw --cid-version 1 root2) ROOT2_CID$(ipfs resolve -r /ipfs/$ROOT1_CID/root2 | cut -d / -f3) ROOT3_CID$(ipfs resolve -r /ipfs/$ROOT1_CID/root2/root3 | cut -d / -f3) ROOT4_CID$(ipfs resolve -r /ipfs/$ROOT1_CID/root2/root3/root4 | cut -d / -f3) FILE_CID$(ipfs resolve -r /ipfs/$ROOT1_CID/root2/root3/root4/index.html | cut -d / -f3)ipfs add -Qrw --cid-version 1 root2递归-r添加目录仅输出最终根 CID-Q/--quieter并强制使用 CIDv1--cid-version 1。得到的ROOT1_CID即整棵 DAG 的根ipfs resolve -r path把 IPFS 路径解析为完整的/ipfs/cid/剩余路径形式-r表示递归解析到最终结果cut -d / -f3从解析结果中取出第一个路径段即该层级节点自身的 CID。通过这种方式脚本为./、./root2、./root2/root3、./root2/root3/root4以及index.html各自锁定了一个独立 CID。这些常量随后被硬编码进测试脚本作为断言 Etag 时的比对基准。创建 ed25519 测试密钥TEST_IPNS_ID$(ipfs key gen --ipns-basebase36 --typeed25519 cache_test_key | head -n1 | tr -d \n)ipfs key gen生成一个名为cache_test_key的密钥对--typeed25519指定签名算法--ipns-basebase36让输出即 IPNS ID使用 base36 编码——这正是测试中那个以k51q...开头的 ID 的来历。head -n1只取 ID 行tr -d \n去除尾部换行确保后续拼接到路径中不会引入空白字符。发布 100 年有效期的 IPNS 记录ipfs name publish --key cache_test_key --allow-offline -Q --ttl876600h --lifetime876600h /ipfs/$ROOT1_CID ipfs routing get /ipns/${TEST_IPNS_ID} ${TEST_IPNS_ID}.ipns-record--key cache_test_key使用刚生成的密钥签名记录--allow-offline允许在未连接公网 DHT 的情况下完成发布离线环境下的关键参数-Q静默模式只输出结果--ttl876600h记录在远程对等节点缓存中的 TTL876600h即 100 年876600 ÷ 24 36525 天--lifetime876600h记录本身的签名有效期EOL同样设为 100 年。两个参数同时拉满保证这条记录在整个测试生命周期内永不过期避免缓存行为被 IPNS 过期时间干扰随后ipfs routing get /ipns/${TEST_IPNS_ID}把这条原始记录从路由表取出落盘为.ipns-record文件作为可静态导入的夹具。导出并固化 CARv1 夹具ipfs dag export ${ROOT1_CID} ./fixtures.caripfs dag export以 CAR 流形式导出以ROOT1_CID为根的整棵 DAG重定向写入fixtures.car。README 特别注明这是raw CARv1——即不经过任何封套wrapper处理的纯 CAR v1 格式这也与测试导入端ipfs dag import的预期一致。CID 与路径对照表README 末尾给出了生成脚本的实际运行结果这些常量同样被原样复制进了测试脚本变量CID路径ROOT1_CIDbafybeib3ffl2teiqdncv3mkz4r23b5ctrwkzrrhctdbne6iboayxuxk5ui./ROOT2_CIDbafybeih2w7hjocxjg6g2ku25hvmd53zj7og4txpby3vsusfefw5rrg5sii./root2ROOT3_CIDbafybeiawdvhmjcz65x5egzx4iukxc72hg4woks6v6fvgyupiyt3oczk5ja./root2/root3ROOT4_CIDbafybeifq2rzpqnqrsdupncmkmhs3ckxxjhuvdcbvydkgvch3ms24k5lo7q./root2/root3/root4FILE_CIDbafkreicysg23kiwv34eg2d7qweipxwosdo2py4ldv42nbauguluen5v6am./root2/root3/root4/index.htmlTEST_IPNS_IDk51qzi5uqu5dlxdsdu5fpuu7h69wu4ohp32iwm9pdt9nq3y5rpn3ln9j12zfhe/ipns/根注意FILE_CID是bafkrei...前缀说明index.html在 UnixFS 中被编码为 raw 叶子节点即裸文件块不额外包裹目录元数据而各级目录节点均为bafybei...DAG-PB。测试如何消费夹具t0116-gateway-cache.sh 在test_init_ipfs初始化仓库、test_launch_ipfs_daemon_without_network启动离线守护进程之后分两步把夹具装入节点ipfs dag import --pin-roots ../t0116-gateway-cache/fixtures.car ipfs routing put --allow-offline /ipns/${TEST_IPNS_ID} ../t0116-gateway-cache/${TEST_IPNS_ID}.ipns-recordipfs dag import --pin-roots从 CAR 导入全部区块并对归档中标记的根 CID 执行 pin保证内容不被 GC 回收ipfs routing put --allow-offline把静态的 IPNS 记录直接写入本地路由表从而让/ipns/id/...路径无需联网即可解析。断言 DirIndex 专用 Etag测试的核心断言围绕 Etag 展开。它首先发起两个 GET 请求通过curl -svX GET捕获响应头curl -svX GET http://127.0.0.1:$GWAY_PORT/ipfs/$ROOT1_CID/root2/root3/ /dev/null 2curl_ipfs_dir_listing_output curl -svX GET http://127.0.0.1:$GWAY_PORT/ipns/$TEST_IPNS_ID/root2/root3/ /dev/null 2curl_ipns_dir_listing_output然后分别断言两路响应都带有目录索引专用的 Etagtest_should_contain Etag: DirIndex curl_ipfs_dir_listing_output grep -E Etag: DirIndex-._CID-${ROOT3_CID} curl_ipfs_dir_listing_outputgrep的正则揭示出生成式目录列表 Etag 的形态DirIndex-hash_CID-ROOT3_CID。其中_CID-后缀直接内嵌该目录节点自身的 CID此处即ROOT3_CID。这意味着 Etag 同时编码了两层信息响应是生成的 HTML 目录索引前缀DirIndex该列表内容源自哪一个逻辑根_CID-cid后缀。浏览器或 CDN 据此可以精确判断目录内容是否变化只要ROOT3_CID不变Etag 就不会变If-None-Match即可命中并返回304 Not Modified从而省去整页目录列表的重复传输。覆盖的边界情况与逻辑根设计测试脚本注释明确给出了缓存控制支持的设计基础——逻辑根Cache control support is based on logical roots (each path segment one logical root).即 URL 路径中的每一段都构成一个独立的逻辑根缓存失效可以细化到任意一个子路径层级而非整个 IPNS 站点一变全失效。为了让测试覆盖面最大化夹具被设计为同时覆盖三种 UnixFS 场景这也是生成脚本保留四级目录的根本原因场景使用的 CID响应形态目录列表ROOT3_CID网关生成式 HTML 目录索引dir-index-html响应对应上面的DirIndexEtag 断言目录根下的index.htmlROOT4_CID请求/root4/时直接以index.html作为根响应而非生成目录索引裸文件FILE_CIDindex.html被直接作为文件返回第三种情形在测试脚本中虽未展开断言脚本在完成两路目录列表的 Etag 校验后即test_kill_ipfs_daemon收尾但它是后续扩展断言的天然落点。而 raw block、CAR、dag-json、dag-cbor 等非 UnixFS 响应类型的缓存语义注释明确说明在各自对应的测试套件中覆盖——例如 t0115-gateway-dir-listing.sh 负责更细粒度的目录列表行为文件系统相关路径则由 t0116-gateway-cache.sh 之外的其他套件验证体现了 sharness 测试按响应类型切分的组织原则。缓存机制在 Kubo 中的演进将这套测试放入 Kubo 的版本脉络中可以看到它对应的能力沉淀过程依据 docs/changelogs/v0.13.md 与 docs/changelogs/v0.14.mdv0.13 起每种响应类型拥有唯一的Etag。网关会评估客户端在If-None-Match中携带的 Etag命中强匹配或弱匹配时直接返回304 Not Modified对应 RFC 7232 §2.3这正是本套件断言DirIndexEtag 的协议基础v0.13 起每个 Gateway 响应都携带X-Ipfs-Roots。该响应头列出从X-Ipfs-Path解析路径所需的全部 CID配合前述逻辑根模型让 CDN/负载均衡器能做细粒度缓存失效当某个子目录分支变化时只失效该分支而不必清空整个 IPNS 站点的缓存v0.14 修复并新增缓存控制细节fix(gw): cache-control of index.html websites修正了以index.html为根响应时的Cache-Control头feat(gw): Cache-Control: only-if-cached则新增了仅命中缓存才返回的能力——前者恰好对应本夹具中ROOT4_CID场景印证了该数据集的工程价值同系列还包含按响应类型划分的网关指标如gw_unixfs_gen_dir_listing_get_duration_seconds等可在 RPC API 端口的/debug/metrics/prometheus查看便于观测生成式目录索引的实际耗时。需要说明的是Gateway.FastDirIndexThreshold控制大目录快速列表阈值默认 100 项在 docs/config.md 中标注为REMOVED自 Kubo 0.18 起该选项已不再必要并被忽略因此当前版本中目录索引的生成不再依赖该阈值。另外对仓库全文检索DirIndex只命中测试与文档可以推断 Etag 的实际生成逻辑位于 Kubo 所依赖的 boxo 库HTTP Gateway 底层实现中本仓库的 core/corehttp/gateway.go 负责将其挂载为 HTTP 服务。复现、运行与扩展如果你希望在自己的环境中重新生成这套夹具直接在仓库根目录按 README 的顺序执行上文各段命令即可唯一的外部要求是拥有一份 ipfs/kubo 二进制README 记录生成时版本为0.21.0-dev当前仓库 version.go 标注的版本为0.44.0-dev。更常见的做法是直接复用仓库中已固化的fixtures.car与.ipns-record在 test/sharness/t0116-gateway-cache/ 确认两份夹具就位运行测试套件sharness 套件由 test/sharness/GNUmakefile 与 test/sharness/Rules.mk 统一驱动test_init_ipfs、test_launch_ipfs_daemon_without_network等基础设施来自 test/sharness/lib/如需扩展可仿照现有结构新增针对ROOT4_CIDindex.html 根响应与FILE_CID裸文件的curl -svX GET与 Etag/Cache-Control 断言二者对应的 CID 常量已在上文对照表中给出。若需要生成内容更新场景的新夹具只需修改index.html内容后重新执行ipfs add、ipfs name publish与ipfs dag export即可得到一套 CID 全部变化的平行数据集——这正是验证 CDN 细粒度失效X-Ipfs-Roots语义的最佳实验材料。【免费下载链接】kuboIPFS implementation in Go: a daemon that stores and serves content-addressed data, with a CLI, HTTP Gateway, and RPC API项目地址: https://gitcode.com/GitHub_Trending/ku/kubo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Kubo HTTP Gateway 缓存控制测试夹具深度解析：t0116-gateway-cache 数据集生成与验证
Kubo HTTP Gateway 缓存控制测试夹具深度解析t0116-gateway-cache 数据集生成与验证【免费下载链接】kuboIPFS implementation in Go: a daemon that stores and serves content-addressed data, with a CLI, HTTP Gateway, and RPC API项目地址: https://gitcode.com/GitHub_Trending/ku/kubo本指南围绕 KuboIPFS 的 Go 实现仓库中test/sharness/t0116-gateway-cache/README.md所记录的测试数据集展开逐条讲解fixtures.car与配套 IPNS 记录是如何生成的、各路径层级 CID 的含义以及 sharness 测试套件 t0116-gateway-cache.sh 如何消费这些夹具来验证 HTTP Gateway 的缓存控制Etag、Cache-Control、X-Ipfs-Roots语义。读完本文你将能够复现该数据集的完整构建流程理解逻辑根logical root这一缓存设计核心并掌握如何基于同一夹具扩展出属于自己的 Gateway 缓存回归测试。从 fixtures.car 到缓存语义一个测试套件的定位Kubo 的 HTTP Gateway 在返回内容时会针对不同响应类型生成不同的Etag并配合If-None-Match、Cache-Control与X-Ipfs-Roots响应头让浏览器、CDN 与负载均衡器能够对 IPFS 内容做精确的缓存与失效判断。为了验证这套语义仓库在 test/sharness/t0116-gateway-cache.sh 中实现了一个独立的 sharness 测试套件其测试数据fixture则固化在 test/sharness/t0116-gateway-cache/ 目录下fixtures.car一个原始的 CARv1 归档内含一棵三级目录root2/root3/root4/index.html的全部区块k51qzi5uqu5dlxdsdu5fpuu7h69wu4ohp32iwm9pdt9nq3y5rpn3ln9j12zfhe.ipns-record与该目录 CID 绑定的 IPNS 记录有效期长达 100 年用于构造/ipns/路径的测试场景。README.md 完整记录了这套夹具的来源它由 ipfs 版本0.21.0-devcommit03a98280e3e642774776cd3d0435ab53e5dfa867通过一组可复现的 CLI 命令生成。数据集的规模被刻意设计得很小——只有一个index.html文件内容仅为hello——目的是让测试关注点完全集中在不同路径形态下的缓存响应头上而不是内容本身的传输。夹具清单CAR 文件与 IPNS 记录文件说明fixtures.car原始 CARv1 归档包含从 ROOT1 到index.html的整棵 DAG测试通过ipfs dag import导入${TEST_IPNS_ID}.ipns-record指向/ipfs/$ROOT1_CID的 IPNS 记录有效期为 100 年测试通过ipfs routing put写入本地路由表之所以同时准备 CAR 与 IPNS 记录是因为缓存控制语义需要覆盖两类内容路径/ipfs/cid/...直接按内容寻址/ipns/id/...先经 IPNS 解析到内容根再按路径展开。两份夹具共同保证了测试可以在完全不联网test_launch_ipfs_daemon_without_network的环境下运行这也是 sharness 测试一贯追求的可重复性。数据集生成全流程README 给出的生成脚本以逐级目录 逐层 CID 的方式组织核心目的是让每个路径段都对应一个可独立引用的 CID。下面按步骤拆解每条命令的实际作用。构建目录与内容mkdir -p root2/root3/root4 echo hello root2/root3/root4/index.html先创建一个三级嵌套目录并在最深层放入内容为hello的index.html。这里刻意使用最朴素的文件布局只有唯一的叶子文件因此整棵 DAG 的拓扑完全由目录节点决定后续所有 CID 都具有教科书式的确定性。逐层解析路径锁定各层级 CIDROOT1_CID$(ipfs add -Qrw --cid-version 1 root2) ROOT2_CID$(ipfs resolve -r /ipfs/$ROOT1_CID/root2 | cut -d / -f3) ROOT3_CID$(ipfs resolve -r /ipfs/$ROOT1_CID/root2/root3 | cut -d / -f3) ROOT4_CID$(ipfs resolve -r /ipfs/$ROOT1_CID/root2/root3/root4 | cut -d / -f3) FILE_CID$(ipfs resolve -r /ipfs/$ROOT1_CID/root2/root3/root4/index.html | cut -d / -f3)ipfs add -Qrw --cid-version 1 root2递归-r添加目录仅输出最终根 CID-Q/--quieter并强制使用 CIDv1--cid-version 1。得到的ROOT1_CID即整棵 DAG 的根ipfs resolve -r path把 IPFS 路径解析为完整的/ipfs/cid/剩余路径形式-r表示递归解析到最终结果cut -d / -f3从解析结果中取出第一个路径段即该层级节点自身的 CID。通过这种方式脚本为./、./root2、./root2/root3、./root2/root3/root4以及index.html各自锁定了一个独立 CID。这些常量随后被硬编码进测试脚本作为断言 Etag 时的比对基准。创建 ed25519 测试密钥TEST_IPNS_ID$(ipfs key gen --ipns-basebase36 --typeed25519 cache_test_key | head -n1 | tr -d \n)ipfs key gen生成一个名为cache_test_key的密钥对--typeed25519指定签名算法--ipns-basebase36让输出即 IPNS ID使用 base36 编码——这正是测试中那个以k51q...开头的 ID 的来历。head -n1只取 ID 行tr -d \n去除尾部换行确保后续拼接到路径中不会引入空白字符。发布 100 年有效期的 IPNS 记录ipfs name publish --key cache_test_key --allow-offline -Q --ttl876600h --lifetime876600h /ipfs/$ROOT1_CID ipfs routing get /ipns/${TEST_IPNS_ID} ${TEST_IPNS_ID}.ipns-record--key cache_test_key使用刚生成的密钥签名记录--allow-offline允许在未连接公网 DHT 的情况下完成发布离线环境下的关键参数-Q静默模式只输出结果--ttl876600h记录在远程对等节点缓存中的 TTL876600h即 100 年876600 ÷ 24 36525 天--lifetime876600h记录本身的签名有效期EOL同样设为 100 年。两个参数同时拉满保证这条记录在整个测试生命周期内永不过期避免缓存行为被 IPNS 过期时间干扰随后ipfs routing get /ipns/${TEST_IPNS_ID}把这条原始记录从路由表取出落盘为.ipns-record文件作为可静态导入的夹具。导出并固化 CARv1 夹具ipfs dag export ${ROOT1_CID} ./fixtures.caripfs dag export以 CAR 流形式导出以ROOT1_CID为根的整棵 DAG重定向写入fixtures.car。README 特别注明这是raw CARv1——即不经过任何封套wrapper处理的纯 CAR v1 格式这也与测试导入端ipfs dag import的预期一致。CID 与路径对照表README 末尾给出了生成脚本的实际运行结果这些常量同样被原样复制进了测试脚本变量CID路径ROOT1_CIDbafybeib3ffl2teiqdncv3mkz4r23b5ctrwkzrrhctdbne6iboayxuxk5ui./ROOT2_CIDbafybeih2w7hjocxjg6g2ku25hvmd53zj7og4txpby3vsusfefw5rrg5sii./root2ROOT3_CIDbafybeiawdvhmjcz65x5egzx4iukxc72hg4woks6v6fvgyupiyt3oczk5ja./root2/root3ROOT4_CIDbafybeifq2rzpqnqrsdupncmkmhs3ckxxjhuvdcbvydkgvch3ms24k5lo7q./root2/root3/root4FILE_CIDbafkreicysg23kiwv34eg2d7qweipxwosdo2py4ldv42nbauguluen5v6am./root2/root3/root4/index.htmlTEST_IPNS_IDk51qzi5uqu5dlxdsdu5fpuu7h69wu4ohp32iwm9pdt9nq3y5rpn3ln9j12zfhe/ipns/根注意FILE_CID是bafkrei...前缀说明index.html在 UnixFS 中被编码为 raw 叶子节点即裸文件块不额外包裹目录元数据而各级目录节点均为bafybei...DAG-PB。测试如何消费夹具t0116-gateway-cache.sh 在test_init_ipfs初始化仓库、test_launch_ipfs_daemon_without_network启动离线守护进程之后分两步把夹具装入节点ipfs dag import --pin-roots ../t0116-gateway-cache/fixtures.car ipfs routing put --allow-offline /ipns/${TEST_IPNS_ID} ../t0116-gateway-cache/${TEST_IPNS_ID}.ipns-recordipfs dag import --pin-roots从 CAR 导入全部区块并对归档中标记的根 CID 执行 pin保证内容不被 GC 回收ipfs routing put --allow-offline把静态的 IPNS 记录直接写入本地路由表从而让/ipns/id/...路径无需联网即可解析。断言 DirIndex 专用 Etag测试的核心断言围绕 Etag 展开。它首先发起两个 GET 请求通过curl -svX GET捕获响应头curl -svX GET http://127.0.0.1:$GWAY_PORT/ipfs/$ROOT1_CID/root2/root3/ /dev/null 2curl_ipfs_dir_listing_output curl -svX GET http://127.0.0.1:$GWAY_PORT/ipns/$TEST_IPNS_ID/root2/root3/ /dev/null 2curl_ipns_dir_listing_output然后分别断言两路响应都带有目录索引专用的 Etagtest_should_contain Etag: DirIndex curl_ipfs_dir_listing_output grep -E Etag: DirIndex-._CID-${ROOT3_CID} curl_ipfs_dir_listing_outputgrep的正则揭示出生成式目录列表 Etag 的形态DirIndex-hash_CID-ROOT3_CID。其中_CID-后缀直接内嵌该目录节点自身的 CID此处即ROOT3_CID。这意味着 Etag 同时编码了两层信息响应是生成的 HTML 目录索引前缀DirIndex该列表内容源自哪一个逻辑根_CID-cid后缀。浏览器或 CDN 据此可以精确判断目录内容是否变化只要ROOT3_CID不变Etag 就不会变If-None-Match即可命中并返回304 Not Modified从而省去整页目录列表的重复传输。覆盖的边界情况与逻辑根设计测试脚本注释明确给出了缓存控制支持的设计基础——逻辑根Cache control support is based on logical roots (each path segment one logical root).即 URL 路径中的每一段都构成一个独立的逻辑根缓存失效可以细化到任意一个子路径层级而非整个 IPNS 站点一变全失效。为了让测试覆盖面最大化夹具被设计为同时覆盖三种 UnixFS 场景这也是生成脚本保留四级目录的根本原因场景使用的 CID响应形态目录列表ROOT3_CID网关生成式 HTML 目录索引dir-index-html响应对应上面的DirIndexEtag 断言目录根下的index.htmlROOT4_CID请求/root4/时直接以index.html作为根响应而非生成目录索引裸文件FILE_CIDindex.html被直接作为文件返回第三种情形在测试脚本中虽未展开断言脚本在完成两路目录列表的 Etag 校验后即test_kill_ipfs_daemon收尾但它是后续扩展断言的天然落点。而 raw block、CAR、dag-json、dag-cbor 等非 UnixFS 响应类型的缓存语义注释明确说明在各自对应的测试套件中覆盖——例如 t0115-gateway-dir-listing.sh 负责更细粒度的目录列表行为文件系统相关路径则由 t0116-gateway-cache.sh 之外的其他套件验证体现了 sharness 测试按响应类型切分的组织原则。缓存机制在 Kubo 中的演进将这套测试放入 Kubo 的版本脉络中可以看到它对应的能力沉淀过程依据 docs/changelogs/v0.13.md 与 docs/changelogs/v0.14.mdv0.13 起每种响应类型拥有唯一的Etag。网关会评估客户端在If-None-Match中携带的 Etag命中强匹配或弱匹配时直接返回304 Not Modified对应 RFC 7232 §2.3这正是本套件断言DirIndexEtag 的协议基础v0.13 起每个 Gateway 响应都携带X-Ipfs-Roots。该响应头列出从X-Ipfs-Path解析路径所需的全部 CID配合前述逻辑根模型让 CDN/负载均衡器能做细粒度缓存失效当某个子目录分支变化时只失效该分支而不必清空整个 IPNS 站点的缓存v0.14 修复并新增缓存控制细节fix(gw): cache-control of index.html websites修正了以index.html为根响应时的Cache-Control头feat(gw): Cache-Control: only-if-cached则新增了仅命中缓存才返回的能力——前者恰好对应本夹具中ROOT4_CID场景印证了该数据集的工程价值同系列还包含按响应类型划分的网关指标如gw_unixfs_gen_dir_listing_get_duration_seconds等可在 RPC API 端口的/debug/metrics/prometheus查看便于观测生成式目录索引的实际耗时。需要说明的是Gateway.FastDirIndexThreshold控制大目录快速列表阈值默认 100 项在 docs/config.md 中标注为REMOVED自 Kubo 0.18 起该选项已不再必要并被忽略因此当前版本中目录索引的生成不再依赖该阈值。另外对仓库全文检索DirIndex只命中测试与文档可以推断 Etag 的实际生成逻辑位于 Kubo 所依赖的 boxo 库HTTP Gateway 底层实现中本仓库的 core/corehttp/gateway.go 负责将其挂载为 HTTP 服务。复现、运行与扩展如果你希望在自己的环境中重新生成这套夹具直接在仓库根目录按 README 的顺序执行上文各段命令即可唯一的外部要求是拥有一份 ipfs/kubo 二进制README 记录生成时版本为0.21.0-dev当前仓库 version.go 标注的版本为0.44.0-dev。更常见的做法是直接复用仓库中已固化的fixtures.car与.ipns-record在 test/sharness/t0116-gateway-cache/ 确认两份夹具就位运行测试套件sharness 套件由 test/sharness/GNUmakefile 与 test/sharness/Rules.mk 统一驱动test_init_ipfs、test_launch_ipfs_daemon_without_network等基础设施来自 test/sharness/lib/如需扩展可仿照现有结构新增针对ROOT4_CIDindex.html 根响应与FILE_CID裸文件的curl -svX GET与 Etag/Cache-Control 断言二者对应的 CID 常量已在上文对照表中给出。若需要生成内容更新场景的新夹具只需修改index.html内容后重新执行ipfs add、ipfs name publish与ipfs dag export即可得到一套 CID 全部变化的平行数据集——这正是验证 CDN 细粒度失效X-Ipfs-Roots语义的最佳实验材料。【免费下载链接】kuboIPFS implementation in Go: a daemon that stores and serves content-addressed data, with a CLI, HTTP Gateway, and RPC API项目地址: https://gitcode.com/GitHub_Trending/ku/kubo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考