Kubo v0.22 版本解析：IPIP-412 流式 CAR、IPNS V2-only 记录与 libp2p 智能拨号

Kubo v0.22（IPFS 的 Go 实现）是一次聚焦于 HTTP Gateway、IPNS 命名系统与底层网络栈的版本升级。本文以 docs/changelogs/v0.22.md 为核心脉络，逐一拆解本版本引入的 IPIP-412 有序 CAR 响应参数、ipfs name publish --v1compat=false 的 V2-only IPNS 记录能力、IPNS 名称解析回归修复，以及 go-libp2p v0.29.0 带来的智能拨号（smart dialing）与 ProtocolVersion 移除破坏性变更，并结合仓库源码与测试用例验证每一项声明的实际落地位置。

版本概览

v0.22.0 是 Kubo 在 0.21 基础上的增量发布，核心工作横跨三个层面：

• HTTP Gateway：基于更新后的 boxo/gateway 库实现 IPIP-412 规范，为 CAR 响应显式声明 order= 与 dups= 内容类型参数，并新增可选的带重复块（duplicate blocks）的 DFS 流式 CAR 能力。
• IPNS：ipfs name publish 新增 --v1compat=false 选项用于发布 V2-only 记录（对应 IPIP-428），同时修复了启用 IPNS over PubSub 时名称解析最长耗时 1 分钟的回归问题。
• 网络层：go-libp2p 从 v0.27.x 升级至 v0.29.0，默认启用智能拨号（smart dialing），并将硬编码的 ProtocolVersion（ipfs/0.1.0）从节点识别信息中移除，构成对 ipfs id 与部分 ipfs swarm 命令的破坏性变更。

从完整变更日志（见文档中的 Full Changelog 折叠块）看，本版本还顺带升级了 boxo v0.11.0、go-bitswap v0.11.0、go-merkledag v0.11.0、go-car/v2、go-yamux/v4 与 go-multiaddr 等关键依赖，并将 WebUI 更新至 4.0.2。

Gateway：支持 order= 与 dups= 参数（IPIP-412）

背景：从"隐含行为"到"显式规范"

在 Kubo 0.21 及更早版本中，网关返回的 CAR 流实际上已经按 DFS（深度优先搜索）顺序排列且不含重复块，但这一行为从未在内容类型层面被显式声明。v0.22 通过实现 IPIP-412，把"返回什么样的 CAR"从隐含约定提升为可由客户端通过 Accept 请求头协商的显式契约。

IPIP-412 为 CAR 内容类型引入了两个可选参数：

参数	取值范围	含义
order	dfs	块在 CAR 流中的遍历顺序，当前规范仅定义 DFS
dups	y / n	CAR 流中是否允许出现重复块

默认行为保持不变

如果客户端在 Accept 请求头中既不指定 dups 也不指定 order，则网关返回的默认 CAR 响应为：

Content-Type: application/vnd.ipld.car; version=1; order=dfs; dups=n

即：版本 v1、DFS 顺序、不含重复块——与 Kubo 0.21 返回的块集合完全一致，保证向后兼容。

新的可选能力：带重复块的 DFS CAR 流

v0.22 仍然只支持 DFS 这一种块排序方式（order=dfs），但新增了请求带重复块 CAR 流的能力。客户端通过如下 Accept 头显式声明：

Accept: application/vnd.ipld.car; order=dfs; dups=y

这个 opt-in 特性对内存受限的客户端与 IoT 设备尤其有价值：它允许在不需要把已遍历过的块全部保存在内存中的前提下，以流式方式下载大型 DAG——即使同一 DAG 中存在对同一块的多次引用，也可以直接透传，从而显著降低客户端侧的内存峰值。

仓库中的落地位置

在 docs/gateway.md 中，application/vnd.ipld.car 一节说明了 CAR 流的语义：返回 DAG（或其子集）的 CAR 流，dag-scope 参数控制包含哪些块（all 整个 DAG、entity 逻辑单元、block 单个块），对 UnixFS 文件还可配合 entity-bytes 实现字节范围请求（详见 IPIP-402 中的 GetCAR 方法接收 gateway.CarParams 结构，将 order、dups 等解析结果与路径信息一起传给底层 boxo/gateway 实现——这一方法签名正是 IPIP-412 参数从 HTTP 层流向 CAR 流生成器的通道。Kubo 的完整 CAR 响应实现位于 boxo/gateway 库中（本仓库通过 go.mod 以依赖形式引入），Kubo 本身通过 core/corehttp/gateway.go 进行装配与参数转发。

ipfs name publish 支持 V2-only IPNS 记录

为什么需要 V1/V2 双签名

IPNS 记录在演进过程中引入了两种签名机制：V1 签名兼容最早期的记录格式，V2 签名基于 IPIP-428 重新设计，具备更清晰的验证逻辑（见 IPNS Record Verification）。长期以来，Kubo 发布的记录同时携带 V1 与 V2 两种签名，以最大化与旧版本节点/客户端之间的互操作性。

新增的 --v1compat 选项

v0.22 在 ipfs name publish 中新增布尔选项 --v1compat：

# 默认行为：发布同时含 V1+V2 签名的记录（向后兼容优先）
ipfs name publish /ipfs/<CID>

# 新能力：发布仅含 V2 签名的记录
ipfs name publish --v1compat=false /ipfs/<CID>

• 默认值：true，即默认仍创建 V1+V2 双签名记录，确保与老客户端的最大兼容概率。
• 目标方向：项目计划在未来逐步过渡到纯 V2-only 记录。

源码与测试印证

--v1compat 选项的定义位于 core/commands/name/publish.go：

cmds.BoolOption(v1compatOptionName, "Produce a backward-compatible IPNS Record by including fields for both V1 and V2 signatures.").WithDefault(true),

其声明文本明确说明：该选项控制"是否生成包含 V1 与 V2 双签名字段的向后兼容 IPNS 记录"。取值在命令的 Run 函数中被读取（core/commands/name/publish.go），随后通过 options.Name.CompatibleWithV1(...)（core/commands/name/publish.go）传入 coreapi 层。

在 coreapi 中，该选项被转换为底层的 namesys 发布选项 core/coreapi/name.go：

namesys.PublishWithIPNSOption(ipns.WithV1Compatibility(options.CompatibleWithV1)),

端到端的验证在 test/cli/name_test.go 的 Publish V2-only record 测试子用例中：测试以 --ttl=30m --v1compat=false 发布记录，随后通过 ipfs name resolve 确认可正常解析，再经 ipfs routing get 取出原始记录并用 ipfs name inspect --verify= 验证，断言输出包含 Valid: true 与 Signature Type: V2，证明 V2-only 记录可被正确生成、传播并验证。

IPNS 名称解析回归修复

v0.22 修复了一个影响 IPNS 名称解析的回归：当启用 IPNS over PubSub（配置文件中的 Ipns.UsePubsub），但待解析的名称实际上并非通过 PubSub 发布时，若记录尚未被缓存，一次名称查找最长需要等待约 1 分钟才能完成。

修复之后，解析逻辑恢复到既有的"竞速取优"模型：DHT 子系统与 IPNS over PubSub 两条路径并行查找，谁先返回有效记录就采用谁（DoNotWaitForSearchValue 标记被应用到所有路由上，见变更日志中的 fix: mark all routers DoNotWaitForSearchValue (#10020) 条目）。这样既保留了 PubSub 的低延迟优势，又避免了在 PubSub 路径上无谓阻塞。

从源码结构看，这一修复涉及 routing/composer.go、routing/delegated.go 等路由组合/代理层对查询等待语义的控制——DoNotWaitForSearchValue 正是路由组合器（composer）在并行查询多个路由时决定"是否等待某个路由返回"的关键开关，相关行为可在 routing/composer.go 与 routing/delegated.go 中进一步追踪。

go-libp2p v0.29.0：智能拨号与破坏性变更

智能拨号（Smart Dialing）

Kubo v0.22 将 go-libp2p 从 v0.27.7 升级至 v0.29.0，其中最受关注的是智能拨号（smart dialing）机制。传统实现会尝试并行拨号一个 peer 的所有候选地址与协议；智能拨号则引入一个优先级排序算法，先对地址和协议进行排序，再按优先级依次尝试，而不是无差别地同时发起全部连接尝试。

从官方发布的经验数据看，Kubo 节点在采用该机制后，拨号次数约减少 30%，而延迟影响可忽略（"Anecdotally, we have observed Kubo nodes make 30% less dials with no to low latency impact"）。这在 NAT 穿透、公网地址池较大的场景下能有效降低节点在拨号上的资源消耗。

在变更日志的依赖明细中可以看到这条特性的完整演进轨迹：swarm: implement smart dialing logic → swarm: make smart-dialing opt in → swarm: enable smart dialing by default（go-libp2p#2420），以及配套的 Happy Eyeballs 排序、黑洞检测（blackhole detection）、地址去重（DedupAddrs）等 swarm 层改进，共同组成了这一代拨号体验优化。

破坏性变更：不再上报 ProtocolVersion

go-libp2p v0.29.0 同时带来一项对命令输出的破坏性变更：ipfs id 及部分 ipfs swarm 命令不再报告 ProtocolVersion 字段。此前该字段被硬编码为 ipfs/0.1.0 并随 identify 流程发送给对端 peer，但它并不携带任何有区分度的信息。

这一变更的直接影响是：依赖 ipfs id 输出中 ProtocolVersion 字段的自动化脚本与工具需要相应调整。仓库中的 docs/file-transfer.md 仍保留了旧版输出中 "ProtocolVersion": "ipfs/0.1.0" 的示例，读者在对比新旧版本输出时需要注意该字段在 v0.22 之后不再出现。

其它值得关注的变更

除上述四个重点外，v0.22 的完整变更日志还包含以下要点（均可在 docs/changelogs/v0.22.md 的 Full Changelog 中逐条核对）：

• ipfs dag import 行为调整：先以 feat!: dag import - don't pin roots by default（破坏性）不再默认 pin 根块，随后又通过 cmds/dag/import: pin roots by default 恢复默认 pin 行为，并改进导入失败时的错误信息（fix(cmd): useful errors in dag import）。核心实现位于 core/commands/dag/import.go。
• 依赖升级：boxo v0.10.3 → v0.11.0；go-bitswap 引入（split client and server、Don't add blocks to the datastore、基础 tracing 等）；go-merkledag v0.11.0（显式 decoder registry）；go-car/v2 更新（StorageCar index 暴露、减少 NewCarReader 分配等）；go-yamux/v4 v4.0.1（sendWindowUpdate 尊重 deadline）；go-multiaddr v0.10.1（Unique 函数与 NAT64 前缀检查）。
• 其它修复：网关子域重定向补上 CORS（fix(gateway): include CORS on subdomain redirects）；relay 用户自定义选项生效（fix(relay): apply user provider options）；配置迁移处理修正；Docker 镜像构建简化并新增镜像测试；WebUI 更新至 4.0.2；测试基建方面将部分 sharness 测试迁移至一致性测试（conformance testing），CI 从 js-ipfs 切换到 Helia。

升级与兼容性提示

结合上述变更，从 v0.21 升级到 v0.22 时建议关注以下三点：

1. 脚本兼容：如脚本解析 ipfs id / ipfs swarm 输出并依赖 ProtocolVersion 字段，v0.22 起该字段已移除，需要修改解析逻辑。
2. IPNS 发布策略：默认仍为 V1+V2 双签名记录；--v1compat=false 仅面向明确希望发布 V2-only 记录、且确认对端解析方已支持 V2 验证的场景。
3. CAR 消费端：默认 CAR 响应仍与 0.21 完全一致（order=dfs; dups=n）；如需带重复块的流式 CAR，请在 Accept 头中显式声明 dups=y，这对内存受限客户端下载大型 DAG 是直接的收益点。

如需继续深入，推荐阅读 docs/gateway.md（CAR 与网关响应语义）、core/commands/name/publish.go（ipfs name publish 全部选项）以及 test/cli/name_test.go（IPNS 发布/验证的端到端用例）。