iroh 版本演进全解析：从 v0.3.0 到 v1.1.0 的 QUIC + NAT 穿透库开发路线图

iroh 版本演进全解析从 v0.3.0 到 v1.1.0 的 QUIC NAT 穿透库开发路线图【免费下载链接】irohIP addresses break, dial keys instead. A library that adds QUIC NAT Traversal to your apps.项目地址: https://gitcode.com/GitHub_Trending/ir/iroh本指南以仓库根目录 CHANGELOG.md 为骨架梳理 iroh 从 2023 年初的文件传输工具一路演进为“以公钥拨号、自带 QUIC 与 NAT 穿透”的 1.0 稳定库的完整过程。通过阅读本文你将掌握 iroh 各主要版本的核心特性、破坏性变更breaking changes、架构重构方向、测试策略演进以及如何对照当前仓库源码如 iroh/Cargo.toml、iroh/src/lib.rs理解这些变更背后的实现。为什么一份 Changelog 值得深度阅读CHANGELOG.md 不是流水账。对于 iroh 这样一个快速迭代的 Rust 网络库变更记录就是架构设计决策的历史档案它记录了协议层的每次替换QUIC 栈从 quinn 到 noq、relay 协议从/derp升级到 iroh-relay-v2、公共 API 的每次收敛Peer→Node→Endpoint 的命名演变、以及稳定化过程中每一次被标记[**breaking**]的取舍。当前仓库中 iroh/Cargo.toml 的版本号1.1.0、rust-version 1.91、edition 2024以及noq、iroh-relay、iroh-base、iroh-dns等依赖组合都可以在 CHANGELOG 中找到它们被引入的对应版本节点。第一阶段前 1.0 时代v0.3.0 ~ v0.35.0v0.3.0 ~ v0.5.12023 年从文件传输工具到网络栈雏形这个阶段 iroh 还是一个基于 QUIC 的内容传输工具但已经埋下了日后网络栈的种子传输层替换v0.3.0 从s2n-quic切换到quinncommit3eff210并引入自己的 ALPN 与SSLKEYLOGFILE支持、bao 切片解码器、Provider/ProviderBuilder、基于 PeerId 的连接、认证 token 握手命名起源v0.3.0 正式“Rename to iroh”v0.5.1 将核心网络模块拆分为独立 crateiroh-net引入MagicEndpoint、derpDERP数据包中继、DerpMap/DerpNode、netcheck/STUN/ICMP 探测、UPnP/PCP 端口映射、iRTT 测量与iroh doctor诊断工具端口约定默认绑定端口定为11204“iroh leet port”commit2901b97基础设施引入 netsim 网络模拟 CI、metrics 采集、cargo-deny、git-cliff 生成 changelog。从源码结构看这一阶段确立的magicsockUDP 收发核心、derp/relay、netcheck/net_report、portmapper四大模块至今仍是 iroh 的骨架可在 iroh/src/socket、iroh/src/net_report、iroh/src/portmapper.rs 中看到它们的现代形态。v0.6.0 ~ v0.14.02023-2024 年功能扩张与分裂v0.6.0 引入 Downloader、网络监控、持久化 peer 信息v0.6.0-alpha.0 引入iroh-sync文档同步引擎与iroh-gossip并把 CLI 重构为 REPL consolev0.9.0 引入NodeTicket可分享的连接票据与doctor ticket-inspectv0.10.0 支持“仅凭 node id 连接”Peer→Node 全局重命名PeerAddr更名为NodeAddr引入NodeId别名v0.12.0 移除 derp regions、改用直接的 relay URLv0.13.0 DNS 解析器从 trust-dns 迁移到 hickory并拆分出iroh-clicratev0.14.0 实现Node discovery via DNS通过 DNS 做节点发现。v0.15.0 ~ v0.23.02024 年年中架构持续收敛v0.15.0 引入“改进的地址分享选项”derper 更名iroh-relayv0.16.0 将核心Conn重命名为MagicSock公开 QUIC API 归 iroh 所有改进初始连接延迟v0.17.0MagicEndpoint更名EndpointMSRV 提升到 1.76支持 FreeBSD/NetBSD/OpenBSDv0.20.0 引入PkarrResolver、本地 swarm discovery、relay 的 websocket 协议升级支持relay 配置拆分 production/stagingv0.21.0 添加 holepunching 事件移除基于文件系统的 peers 存储relay 路径从/derp切换到/relayv0.22.0~v0.23.0 全面移除flume改用async_channel升级 quinn 0.11 rustls 0.23blobs/docs/gossip 协议陆续拆分到独立仓库。v0.24.0 ~ v0.35.02024 下半年 ~ 2025 年中模块重组与协议升级v0.24.0 引入iroh doctor的plot与relay-urlsbench 支持--with-relay与--metricsv0.28.0 引入iroh-routercratev0.29.0 正式引入iroh-relaycratenet-report 拆分为独立 craterelay 支持 rate-limit 客户端连接与 QUIC 地址发现QAD服务v0.30.0Endpoint::connect_by_node_id被移除MSRV 提升至 1.81v0.31.0 实现 relay 认证authentication、relay 侧定时 pingEndpoint::close变为 infalliblev0.32.0 引入QUIC Address Discovery (QAD)移除本地/远端 IP 地址的公开访问iroh 可编译到 wasm32-unknown-unknownv0.33.0 支持应用建立0-RTT连接、discovery 订阅流与用户自定义数据发布v0.34.0 TLS 认证切换为raw public keys不再使用 x509/libp2p 认证relay 默认证书格式从 der 改为 pemv0.35.0 引入 fallback ALPN、Endpoint::net_report返回WatchableReport、websockets 代理与 test-utils 支持。第二阶段1.0 稳定化v1.0.0-rc.0 ~ v1.1.0从 v1.0.0-rc.0 开始CHANGELOG 进入了稳定化冲刺所有改动都围绕 API 收敛、默认值合理化、1.0 依赖对齐与可观测性展开并大量标注[**breaking**]。v1.0.0-rc.02026-05-07Incoming::local_ip替换为Incoming::local_addr支持为 relay 设置auth tokensiroh与iroh-relay双侧ConnectionInfo替换为WeakConnectionHandleSource类型收为私有QNTQlog/QUIC 网络跟踪相关配置默认值更新更新到 1.0.0-rc.0 依赖族移除 noqWrittenre-export添加后量子post-quantum密钥交换示例对应今天的 iroh/examples/pq-only-key-exchange.rs 与 prefer-pq-key-exchange.rsunstable-custom-transportsfeature 门控改进net_report API 移到unstable-net-reportfeature 之后。v1.0.0-rc.12026-05-27可配置路径选择Configurable path selection新增endpoint::Builder的路径选择配置对应 iroh/src/endpoint/bind.rs 中BiasedRttPathSelector等实现noq patch 支持服务器处于硬 NAT 之后的打洞relay 暴露Bucket限流原语升级到noq1.0.0-rc.1RemoteStateActor结构拆分、用FourTuple表示选中路径与发送路径relay 的AccessConfig枚举替换为AccessControltrait支持追踪连接。v1.0.02026-06-15endpoint presets 正式化Endpoint::bind(presets::N0)成为推荐用法见 iroh/src/endpoint/presets.rs 与 iroh/src/lib.rs 中的示例relay URL 更新到 1.0 stablenet_report支持完整配置CustomAddr序列化修复与Vecu8序列化一致、mapped addrs 改用随机值替代计数器relay 支持Bearer token 访问控制无需外部服务、多 hostname Lets Encrypt TLS、自定义ServerCertVerifierCaRootsConfig更名为CaTlsConfigrelay 客户端 IPv4/IPv6happy eyeballs并发连接。v1.0.1 ~ v1.0.32026 年 6-7 月v1.0.1修复 keep-alive 文档、补全向后兼容条目、日志 span 级别不超过 info、16 接口下的打洞测试、iroh-dns在无 JNI 环境下回退到 fallback nameserversv1.0.2修复接收传输 lane 公平性计数器问题增加 Windows 瞬时 recv 错误的回归测试v1.0.3连接空 ALPN 时报错n0 preset 加入 pkarr resolver移除 build.rs 中的 vergen降低 warn 日志噪音。v1.1.02026-08-25当前版本relay 连接指标为 relay 连接增加 metrics对应 iroh/src/metrics.rs 与 iroh-relay/src/server/metrics.rs限流通知客户端被限流时被告知iroh 侧输出 warn 日志修复 relay 重连退避期间持续应答 priority messages、net_report的 HTTP 探测走已配置代理、relay 任务用join_next替代join_all排空iroh-dns-server启用 TCP keepalive 并同时绑定 IPv4/IPv6不再发送 SNI隐私改进refactor6d7f68cpatchbay 更新至 0.7.0并新增 relay 连通性 patchbay 测试见 iroh/tests/patchbay/relay.rs依赖升级noq、net-tools、n0-mainline、lru。贯穿全程的核心技术主线1. 命名演变Peer → Node → Endpoint从 CHANGELOG 中可以清晰看到 iroh 公共 API 的三次大改名版本变更含义v0.10.0PeerAddr→NodeAddrPeer→Node引入NodeId从“对等点”转向“节点”模型v0.19.0Endpoint::my_relay→home_relaylocal_endpoints→direct_addresses地址语义精确化v0.94.0Node→Endpoint全面更名与“按公钥拨号”的核心心智模型对齐现代 iroh/src/lib.rs 中Endpoint是中心结构Endpoint::bind(presets::N0)创建端点、ep.connect(addr, ALPN)拨号、ep.accept()接受连接。用户面对的 QUIC 能力则通过Connection暴露open_bi/accept_bi、uni 流、datagram 等。2. QUIC 栈演进quinn → iroh-quinn → noqv0.3.0s2n-quic → quinnv0.24.0quinn 0.11 rustls 0.23v0.91.1改用 quinn multipathv0.97.0切换 noq[**breaking**] Switch noqcommitb32c9271.0 系列对齐 noq 1.0/1.2 依赖当前 iroh/Cargo.toml 中noq 1.2.0、noq-proto、noq-udp。noq 是 n0 团队维护的 QUIC 实现提供了多路径与打洞所需的底层控制这也是 iroh 1.0 之后能够实现“可配置路径选择”“硬 NAT 之后打洞”等能力的基础。3. 中继/relay 协议derp → iroh-relay → iroh-relay-v2v0.8.0 之前derp 区域regions模型v0.12.0移除 regions改为直接 relay URLv0.15.0derper 更名为iroh-relayv0.21.0HTTP 路径/derp→/relayv0.98.0relay 协议升级为 iroh-relay-v2新增 Health frame 并测试协议升级机制1.0 系列relay 认证auth tokens Bearer token、AccessControl trait、限流与限流通知、happy eyeballs、健康检查。当前 iroh-relay/src/lib.rs 同时包含客户端client模块与服务端server模块即文档所称“生产环境运行的代码你也可以跑”。4. 地址发现Address Lookup / DiscoveryCHANGELOG 中的 discovery 演进同样醒目mDNS本地网络发现v0.20.0 的 local swarm discovery→ pkarr/DHTv0.20.0 引入 PkarrResolverv0.98.0 vendor pkarr 实现→ DNSv0.14.0 的 Node discovery via DNSv0.23.0 的 PkarrNodeDiscovery→ v0.96.0 全面更名Discovery→AddressLookup。现代实现见 iroh/src/address_lookupdns/memory/pkarr 三个后端并且 n0 preset 默认带 pkarr resolverv1.0.3。5. 打洞Hole Punching与路径管理v0.21.0holepunching 事件v0.96.0ping paths 并在网络变化时触发打洞holepunch 基础指标v1.0.0-rc.1noq patch 支持服务器硬 NAT 之后的打洞可配置路径选择v1.0.0正确放弃更差 RTT 的新路径、全局地址验证 token 存储测试v1.0.1 用16 个网络接口测试打洞patchbay 持续补充 NAT 矩阵与 uplink 切换测试见 iroh/tests/patchbay。6. 可观测性metrics、tracing、qlogv0.5.1引入 metrics 采集与iroh doctorv0.96.0qlog 支持、连接延迟追踪v0.98.0relay 暴露更多指标v1.1.0relay 连接指标 限流通知日志纪律贯穿始终多次提交都在“降低 warn 级别”“不要逐包 debug 日志”“tracing span 级别不超过 info”上做文章如 v1.0.1、v0.97.0。破坏性变更速查表升级前必读以下是从 CHANGELOG 中摘录的、影响面较大的 breaking changes按时间倒序版本破坏性变更v1.0.0-rc.0Incoming::local_ip→local_addr移除 noqWrittenConnectionInfo→WeakConnectionHandleSource收为私有v1.0.0relayAccessConfig→AccessControltraitCaRootsConfig→CaTlsConfigFourTuple用于选中路径v0.98.0升级 noq0.18relay 协议 iroh-relay-v2v0.97.0切换到 noqrelay 不应在相同 endpoint id 重连时杀掉旧连接v0.96.0Endpoint::latency移除net-report 私有化quinn-proto 编码 trait 不再导出Builder::bind_addr端口不可用时不再回退随机端口Discovery更名AddressLookupv0.95.0snafu → n0-errorredb v3v0.94.0Node→Endpointadd_node_addr从公共 API 移除tickets 移到独立 cratetransport genericEndpointAddrv0.93.0Endpoint::add_node_addr移除online方法引入v0.91.0edition 2024stride 取代自定义 split 协议并发送 ECN 位relay 新握手协议v0.90.0默认 relay 改为 “canary” relaysconcrete errorsProtocolError→AcceptErrornet_report 重构v0.35.0Metrics 重构v0.34.0TLS 认证切换 raw public keysrelay 默认证书 der→pemv0.33.0pkarr v3v0.32.0移除本地/远端 IP 访问v0.30.0connect_by_node_id移除MSRV 1.81v0.29.0引入 iroh-relay cratev0.28.0引入 iroh-routergossip/docs/blobs 移出仓库注意以上均为 CHANGELOG 原文标注的事实。具体某个 API 在当前 1.1.0 源码中的最终形态请以 iroh/src/endpoint.rs 等源码为准。测试与 CI 策略的演进CHANGELOG 里反复出现两类测试基础设施值得单独说明netsimv0.3.0 起在 CI 中运行真实网络拓扑模拟uplink、NAT、丢包后来并入仓库v0.97.0 “Colocate sims into iroh repo”patchbayv0.98.0 起更高层的网络测试矩阵覆盖 relay 连通性、NAT 组合、uplink 切换、降级场景。1.0 之后 patchbay 升级到 0.5/0.7 并针对 relay 增加专门用例iroh/tests/patchbay/relay.rs。此外flaky 测试管理也是高频主题单独 flaky CI workflow、nextest groups、超时放宽、#[ignore]标记反映出网络库测试对时序的高敏感度。如何基于 CHANGELOG 做版本迁移与代码考古定位迁移目标升级前先在该文档搜索[**breaking**]对照上表确认影响面结合源码确认现状例如要了解 “可配置路径选择”可阅读 iroh/src/socket/biased_rtt_path_selector.rs 与 iroh/src/endpoint/bind.rs看示例验证 API1.0 之后新增的示例0rtt、custom-transport、pq 密钥交换、incoming-filter、screening-connection、monitor-connections、remote-info都对应 CHANGELOG 中的某项特性见 iroh/examples关注 feature 门控unstable-custom-transports、unstable-net-report、tls-ring/tls-aws-lc-rs、fast-apple-datapath、qlog等 feature 的引入与变更都能在文档中找到出处其当前定义见 iroh/Cargo.toml 的[features]段。小结从 v0.3.0 到 v1.1.0iroh 的 CHANGELOG 完整记录了四条演进主线API 从 Peer 收敛到 Endpoint、QUIC 栈从 quinn 替换为 noq、中继从 derp regions 演进为 iroh-relay-v2、发现机制从 DHT 扩展到 DNS/mDNS/pkarr 全家桶。1.0 之后项目进入以稳定性、可观测性和 relay 生态认证、限流、指标为核心的维护阶段。对于使用或二次开发 iroh 的工程师而言这份文档既是升级指南也是理解仓库源码组织方式的最佳入口。【免费下载链接】irohIP addresses break, dial keys instead. A library that adds QUIC NAT Traversal to your apps.项目地址: https://gitcode.com/GitHub_Trending/ir/iroh创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考