iroh 1.0.0-rc.0 深度解析：Rust 写就的模块化网络协议栈，四年磨一剑的 P2P 连接基础设施

背景：IP 地址为什么出了问题？

如果你做过端对端直连的应用，一定会踩过一个坑：IP 地址根本不可靠。

NAT 层层嵌套、防火墙锁死端口、IP 地址随时变化……传统的"知道 IP 就能连上"这个假设，在现实网络里根本不成立。HTTP 是怎么解决这个问题的？靠的是中心化服务器——你总能找到一个稳定的域名，通过代理绕过去。

但当你需要真正的 P2P 直连时，这个问题就变得非常棘手。你要么放弃直连走中继（延迟高、带宽贵），要么手动做 NAT 穿透（代码复杂、坑多）。很多团队的做法是：先假设能直连，失败了再退化到中继。但这个"先假设"的逻辑，在不同网络环境下的成功率差异极大，维护成本也很高。

iroh 解决的就是这个问题。它的核心哲学是：让"找对人"这件事变得可靠和透明，而不是让开发者去处理各种网络环境的细节。你只需要说"我要连接那台设备"，iroh 负责找到最快的路径，无论是直连、打洞还是中继。

这次发布的 1.0.0-rc.0，是 iroh 经过四年开发、50 多个版本迭代后的首个候选版本，也是它正式走向生产环境的信号。本文从架构设计、核心原理、API 演进和实战代码四个维度，全面解析这个项目。

一、iroh 是什么：从 QUIC 连接到模块化网络栈

1.1 项目定位

iroh 是一个用 Rust 编写的模块化网络协议栈，核心目标是在任意网络环境下建立设备之间的直接连接。

"直接连接"（Direct Connection）是关键词。iroh 的设计思路是：能直连就直连，直连做不到就打洞（NAT穿透），打洞失败就走中继。三种方式对上层 API 完全透明，开发者只需要调用同一个接口。

它的底层传输基于 QUIC 协议（通过一个叫 noq 的自研 QUIC 实现），所以天然具备：

• 端到端加密：QUIC 连接的握手过程已经完成了密钥协商
• 多路复用：一个连接上可以开多个独立流，不存在 TCP 的队头阻塞问题
• 流优先级：可以给不同流设置不同的优先级，关键数据优先传输
• 数据报传输：支持不可靠的数据报模式，适合实时性要求高的场景

1.2 四大子模块

iroh 的仓库是一个 workspace，包含多个独立发布的 crate：

iroh（核心库） — 处理 hole-punching（NAT穿透）和中继通信。
iroh-relay（Relay 服务器实现） — 你可以自己部署 relay 服务器，也可用官方维护的公共 relay。
iroh-base（公共类型） — Hash、密钥类型、RelayUrl 等跨模块共享的基础类型。
iroh-dns-server（DNS 服务器） — 为 EndpointId 提供域名解析，部署在 dns.iroh.link。

1.3 高层协议生态

iroh 不仅仅是连接基础设施，它还提供基于连接的上层协议：

• iroh-blobs：基于 BLAKE3 的内容寻址大文件传输，KB 到 TB 级别全覆盖
• iroh-gossip：基于共享密钥的发布-订阅网络，资源消耗极低，适合手机等受限设备
• iroh-docs：基于 iroh-blobs 的最终一致 KV 文档库，支持冲突无关复制（CRDT）
• iroh-willow： Willow 协议的实现（Willow 是新一代去中心化存储协议）

这意味着：当你用 iroh 构建应用时，可以直接用这些现成的协议，不用自己从零设计 P2P 数据传输逻辑。

二、连接建立的核心机制：Path 和多路径

2.1 路径观察 API 重设计

1.0 候选版中最重要的变化之一，是把 PathWatcher 拆成了两个独立的原语。这是四年来最大的 API 破坏性变更，需要详细讲解。

之前的 PathWatcher 一个原语试图同时服务两类使用者：

1. "我现在有哪些路径？"
2. "路径变化时通知我"

这两类需求的行为特性完全不同：前者需要状态快照，后者需要事件流。把它们混在一起导致了两个问题：

• 状态快照会持有已关闭路径的统计信息（为了给晚到的订阅者看），造成内存泄漏隐患
• 事件流的订阅时机和状态读取之间有竞态条件

1.0 候选版拆成了：

// 1. 获取当前路径快照（借用 Connection）
let paths = connection.paths();
// paths 是 PathList 类型的借用，生命周期绑定到 Connection
// 因为 Connection 活着，路径统计信息就有效，所以 Path::stats() 是 infallible 的

// 2. 订阅路径变化事件流（'static，Connection 死了也能收到关闭事件）
let mut stream = connection.path_events();
while let Some(event) = stream.next().await {
    match event {
        PathEvent::Opened(path) => { ... }
        PathEvent::Selected(path) => { ... }
        PathEvent::Closed { path, stats } => { 
            // 关闭路径的最终统计在 Closed 事件里内联传递
            // 不再保存在 Connection 上，消除了内存泄漏风险
        }
        PathEvent::Lagged => { ... }
        _ => {} // #[non_exhaustive]，编译器保证处理未来可能新增的变体
    }
}

关键设计决策：已关闭路径的统计信息不再保存在 Connection 上，而是在 PathEvent::Closed 事件里内联传递。消费者自己负责累积这些信息。这个设计让 Connection 的内存占用不再随时间增长。

2.2 多路径连接（Multipath）

iroh 从 0.96 版本开始支持 multipath，即一个逻辑连接可以同时使用多个物理路径。比如设备同时连着 WiFi 和 5G，iroh 可以同时利用两条路径，把流量动态分配到延迟更低的那条上。

这种设计对于移动设备特别有价值——WiFi 切到 5G 不需要重建连接，iroh 会自动检测新路径并纳入使用。

2.3 NAT 穿透：hole-punching 原理

iroh 建立直连的核心是 hole punching（打洞）：

[Client A] ---(发送UDP)---> [STUN Server]
              <--- 得到公网IP:Port ---

[Client B] ---(发送UDP)---> [STUN Server]
              <--- 得到公网IP:Port ---

A 和 B 互相向对方的公网IP:Port 发包
→ 在各自的 NAT 上"打洞"成功，双方就能直接通信了

iroh 封装了这个过程。开发者只需要调用 endpoint.connect(addr, alpn)，iroh 会：

1. 查询本地网络信息
2. 查询 STUN 服务器获取公网地址
3. 尝试 hole punching
4. 失败则自动 fallback 到 relay

你可以在 https://perf.iroh.computer 看到 n0-computer 团队持续测试的穿透率和延迟数据。

三、API 设计哲学：从 ConnectionInfo 到 WeakConnectionHandle

3.1 旧的 ConnectionInfo 问题在哪

1.0 之前，开发者通过 ConnectionInfo 获取连接信息：

// 旧 API（已废弃）
let info = connection.to_info();
let paths = info.paths();           // 这个 paths() 后来被移除了
let selected = info.selected_path(); // Option -> Option

问题在于：ConnectionInfo 是一个完整的信息快照，它持有的数据可能已经过时（路径选择随时在变化）。而且 to_info() 返回的信息在调用之后就与实际连接状态脱节了，容易导致开发者写出"看起来对但实际不对"的代码。

3.2 新的 WeakConnectionHandle

// 新 API
let handle = connection.weak_handle();
// handle 持有的信息更少，更"弱"，不容易被误用

// 如果需要真正操作连接，先 upgrade
if let Some(conn) = handle.upgrade() {
    // 现在可以安全地使用连接了
}

WeakConnectionHandle 暴露的方法比 ConnectionInfo 少得多，这其实是刻意为之的——减少了误用的空间，让 API 的行为更容易预测。

3.3 OnClosed 的新返回类型

// 旧
let closed = handle.closed(); // 返回某个 Future

// 新：返回 Closed 结构体，字段全部公开
let closed = handle.closed();
closed.await; // Closed { reason, conn_stats, path_stats }

关闭原因、连接统计、路径统计全部内联在一个结构体里，不再是分散的 API 调用。

四、实战：构建一个 Echo 服务

4.1 连接方（Sender）

use iroh::{Endpoint, ProtocolHandler};

const ALPN: &[u8] = b"iroh-example/echo/0";

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // 创建 Endpoint（底层创建 UDP socket，初始化 QUIC 堆栈）
    let endpoint = Endpoint::builder()
        .relay_url(Some("https://relay.iroh.computer/".parse()?))
        .secret_key(iroh::SecretKey::generate())
        .bind()
        .await?;
    
    // ticket 包含目标节点的所有连接信息（公钥、中继地址等）
    // 分享 ticket 比分享 IP 地址可靠得多
    let ticket = "..."; // 从接收方获取
    
    // 用 ticket 打开连接（iroh 会自动找到最快路径）
    let conn = endpoint.connect(&ticket.parse()?, ALPN).await?;
    
    // 打开一个双向 QUIC 流
    let (mut send, mut recv) = conn.open_bi().await?;
    
    // 发送数据
    send.write_all(b"Hello, world!").await?;
    send.finish()?; // 通知接收方数据已发完
    
    // 接收响应
    let response = recv.read_to_end(1024).await?;
    println!("收到响应: {:?}", response);
    
    // 关闭连接
    conn.close(0u32.into(), b"done");
    endpoint.close().await;
    
    Ok(())
}

4.2 接收方（Receiver）

use iroh::{Endpoint, Router, ProtocolHandler};
use std::sync::Arc;

const ALPN: &[u8] = b"iroh-example/echo/0";

#[derive(Debug, Clone)]
struct Echo;

#[iroh::ProtocolHandler]
impl ProtocolHandler for Echo {
    async fn accept(
        &self,
        connection: iroh::endpoint::Connection,
    ) -> anyhow::Result<()> {
        // 接受双向流
        let (mut send, mut recv) = connection.accept_bi().await?;
        
        // 读取所有数据然后原样发回
        let data = recv.read_to_end(1024 * 1024).await?;
        tokio::io::copy(&mut std::io::Cursor::new(data), &mut send).await?;
        send.finish()?;
        
        // 等待连接关闭（优雅关闭）
        connection.closed().await;
        Ok(())
    }
}

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let endpoint = Endpoint::builder()
        .relay_url(Some("https://relay.iroh.computer/".parse()?))
        .secret_key(iroh::SecretKey::generate())
        .bind()
        .await?;
    
    let router = Router::builder(endpoint)
        .accept(ALPN.to_vec(), Arc::new(Echo))
        .spawn()
        .await?;
    
    // 打印 ticket 用于分享
    let ticket = router.local_ticket(ALPN).await?;
    println!("接收方 ticket: {}", ticket);
    
    // 保持运行
    router.stopped().await;
    Ok(())
}

ticket 的意义：ticket 是一个自包含的连接凭证，包含了目标节点的公钥、中继地址等信息。只要双方都能访问互联网（或其中一方有公网 IP），通过 ticket 就能建立连接。相比 IP 地址，ticket 不依赖具体网络拓扑，更稳定。

五、对比主流方案：iroh vs libp2p vs Tailscale

iroh 的优势在于：开箱即用的上层协议 + 简洁的 API + 对直连的执着。如果你只需要 P2P 文件传输或文档同步，直接用 iroh-blobs 或 iroh-docs，不用自己设计协议。

六、1.0 候选版的关键变更总结

这次的 1.0.0-rc.0 不是一个普通的版本更新，而是对过去四年 API 设计经验的总结：

API 清理

• 移除了 pre-1.0 版本的几乎所有类型重导出，API 表面更干净
• 所有公开的 struct 和 enum 都标记了 #[non_exhaustive]，为未来扩展留空间
• 不再导出已废弃的 API（to_info, PathWatcher 等）

Path 观察重构

• PathWatcher → Connection::paths() + Connection::path_events()
• 关闭路径统计内联到 PathEvent::Closed，不在 Connection 上累积

功能模块拆分

• DhtAddressLookup → iroh-mainline-address-lookup（独立版本控制和发布）
• MdnsAddressLookup → iroh-mdns-address-lookup
• AccessLimit → iroh-util

noq 1.0 候选版

• iroh 的 QUIC 实现 noq 也同步发布 1.0 候选版，两者一起稳定

MSRV 提升到 1.91

七、实际应用场景

7.1 跨设备文件同步

用 iroh-blobs 可以轻松实现多设备间的文件同步。文件按内容 hash 寻址，自动去重，传输的是增量部分。设备只需要知道对方的公钥（而不是 IP），就能在任何网络环境下同步。

7.2 离线优先应用

iot & embedded 场景的文档里特别提到了 ESP32 和树莓派：iroh 让没有公网 IP 的设备也能互相发现和通信，特别适合物联网场景。

7.3 协作应用（类似 Figma 的多用户实时编辑）

iroh-docs 的 CRDT 文档模型天然支持多用户并发编辑，再配合 iroh-gossip 做状态广播，可以构建去中心化的协作应用。

八、性能与可靠性

iroh 团队在 https://perf.iroh.computer 持续测量穿透率和延迟数据。在北美和欧洲的测试节点上，hole-punching 成功率相当可观。

QUIC 的拥塞控制和多路复用特性也保证了即使走中继，性能也比传统 TCP relay 好很多——QUIC 的流控是独立于连接的，不会因为中继路径的队头阻塞而影响其他流。

九、展望：1.0 正式版之后

根据官方博客的说法，1.0 正式版之前至少还会再发一个候选版本，主要看社区反馈。如果你是 0.35 稳定版的用户，现在是测试候选版的最好时机——API 已经冻结，有问题可以提 issue。

长期来看，iroh 的目标是把"建立可靠的端到端连接"这件事做成基础设施中的基础设施——像 HTTP 让"获取资源"变得简单一样，iroh 让"连接设备"变得简单。

总结

iroh 1.0.0-rc.0 是一个工程化程度非常高的 Rust 网络库。它用四年时间回答了一个问题：在现实网络条件下，如何可靠地连接两台设备？

答案是一套分层策略：能直连就直连，打洞成功就走打洞路径，都不行就走中继。对开发者来说，只需要一个 ticket + 一个 connect 调用，iroh 在后台完成所有复杂的网络协商工作。

对于需要构建 P2P 应用的团队来说，iroh 值得认真考虑——它不仅提供了连接基础设施，还提供了 blobs/gossip/docs 等可直接使用的上层协议，用 Rust 的安全性和性能，构建真正可靠的去中心化应用。