iroh 项目深度调研：dial-by-key 的 P2P 传输栈与 libp2p 的另一条路

P2P 传输栈里，libp2p 长期是默认选项——但它的协议栈庞大、配置面广，每次新项目都要在 tcp/quic/webrtc/noise/yamux/identify/kad/relay/dcutr 一长串 feature 里挑组合。iroh 是 Rust 生态里走另一条路的库：只做 QUIC + dial-by-public-key + NAT 穿透，把传输层收敛到很小，再在它上面叠加 blobs/gossip/docs 三个可选模块。2026 年 6 月 15 日 n0 发布 iroh 1.0，slogan 是「Dial Keys, not IPs」，经过 4 年开发、65 个预发布版本后第一次稳定。

本篇调研 iroh 的完整技术图景，并和系列里已有的 libp2p 实战（《Rust P2P 开发实战》《libp2p 协议栈与 BitTorrent》《P2P 信令与中继服务器技术调研》）做对照，回答一个问题：在哪些场景下 iroh 比 libp2p 更合适，在哪些场景下不是。

核心概念速查

项目定位与发展脉络

iroh 由 n0（N0, Inc.） 公司维护，这家公司的核心团队来自 Radicle 项目（去中心化代码协作网络），所以 iroh 一开始就是为「让任意两台设备直接同步数据」这个场景设计的。项目代码托管在 GitHub n0-computer/iroh，许可证 Apache-2.0 OR MIT，纯 Rust 实现。

iroh 的版本史能看出它的演化方向：

当前（2026-07）的仓库结构：

• n0-computer/iroh — 核心，含 iroh（Endpoint/连接）、iroh-relay（中继协议与服务）、iroh-base（NodeId/Hash 等基础类型）、iroh-dns-server（pkarr 用的 DNS 服务）
• n0-computer/iroh-blobs — BLAKE3 内容寻址传输
• n0-computer/iroh-gossip — Plumtree 群组广播
• n0-computer/iroh-docs — CRDT 键值存储
• n0-computer/iroh-examples — 官方示例集

注意 iroh 在 0.x 阶段多次重命名和拆分 crate（iroh-p2p → iroh-net → iroh），看老博客或老代码时要注意版本。本篇所有 API 描述以 1.0 为准。

设计哲学：dial-by-key 与 QUIC-first

iroh 的核心理念可以浓缩成两点：

1. 拨公钥，不拨地址

libp2p 里连接一个节点要先有 Multiaddr（形如 /ip4/1.2.3.4/udp/4001/quic-v1），再从中提取 PeerId 验证身份。IP 和 PeerId 是两套独立信息，IP 会变（家庭宽带换 IP、移动网络切基站、笔记本换 Wi-Fi），PeerId 不变，但应用层每次都得处理「怎么拿到当前 IP」这个问题——通常靠 DHT、rendezvous、relay 消息中转。

iroh 把这个抽象反过来：你拨的是一个 NodeId（公钥），而不是一个地址。具体怎么连由 Endpoint 内部决定：

• 先尝试已知直连地址（direct addresses）；
• 直连失败走 relay 中转；
• 中转的同时尝试打洞，成功后升级为直连。

应用层永远只看到 endpoint.connect(node_addr, ALPN)，NodeAddr 里的 relay 和直连地址只是「提示」，缺失也能连（靠 relay 兜底），过期也能连（靠 pkarr DHT 重新发现）。这让上层代码不用关心「设备现在在哪个 IP」。

2. 只用 QUIC

iroh 不像 libp2p 提供 TCP/QUIC/WebRTC/WebSocket 多种可插拔传输。它只支持 QUIC（基于 quinn crate），在 QUIC 之上直接跑 TLS 1.3。这个决定有几个直接后果：

这个取舍很明确：iroh 服务的是「设备到设备」的应用层通信（同步、文件传输、私有协议），不是「浏览器到服务器」的 Web 应用。如果你的目标平台是浏览器，iroh 不是合适的选择。

架构分层

iroh 是一个分层但可独立使用的协议栈，上层依赖下层但不强制：

flowchart TD
    A["应用层<br/>自定义协议 / iroh-docs"] --> B["iroh-gossip<br/>Plumtree 群组广播"]
    A --> C["iroh-blobs<br/>BLAKE3 内容寻址"]
    B --> D["iroh 核心<br/>Endpoint / QUIC 连接"]
    C --> D
    D --> E["发现层<br/>pkarr DHT / DNS / 静态"]
    D --> F["中继层<br/>iroh-relay（无状态）"]

    classDef app fill:#E8F5E9,stroke:#4CAF50,color:#1B5E20
    classDef proto fill:#E3F2FD,stroke:#2196F3,color:#0D47A1
    classDef base fill:#FFF3E0,stroke:#FF9800,color:#BF360C
    classDef infra fill:#F3E5F5,stroke:#9C27B0,color:#4A148C
    class A app
    class B,C proto
    class D base
    class E,F infra

iroh 的分层是「按需引入」：只要直连两个节点跑自定义协议，只需要核心 iroh crate；要群组消息广播再加 iroh-gossip；要文件/内容传输再加 iroh-blobs；要做协作编辑、同步状态这种需要 CRDT 语义的场景，才需要 iroh-docs。每一层都有清晰的职责边界，不像 libp2p 那样把 Gossipsub/Kad/Identify 全部塞进一个 Swarm 里。

核心：Endpoint 与连接生命周期

iroh 核心 crate 提供的就是「建立端到端加密的 QUIC 连接」这一件事。一条 iroh 连接本质上就是一条 QUIC 连接，连接的 API 和 QUIC 一致——可以开单向流（unidirectional stream）、双向流（bidirectional stream），流上跑什么协议由 ALPN 标识。

Endpoint 是核心入口，等价于 libp2p 的 Swarm，但 API 收敛得更小：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

use iroh::{Endpoint, NodeAddr, node_addr::NodeMap};
use iroh_base::SecretKey;

const ALPN: &[u8] = b"myapp/1";

// 生成或加载身份
let secret = SecretKey::generate(rand::rngs::OsRng);
let node_id = secret.public();

// 创建 Endpoint
let endpoint = Endpoint::builder()
    .secret_key(secret)
    .alpns(vec![ALPN.to_vec()])
    .bind()
    .await?;

println!("my NodeId: {node_id}");
println!("my NodeAddr: {:?}", endpoint.node_addr());

// 拨号对方（NodeAddr 可以是对方分享给你的任意子集：
// 只有 NodeId 也能连，靠 relay + pkarr 发现）
let peer_addr: NodeAddr = todo!("从对方拿到");
let conn = endpoint.connect(peer_addr, ALPN).await?;

// 在连接上开双向流，跑自己的协议
let mut stream = conn.open_bi().await?;
stream.0.write_all(b"hello").await?;

接受端：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

while let Some(incoming) = endpoint.accept().await {
    let conn = incoming.await?;          // 自动校验 ALPN
    tokio::spawn(async move {
        loop {
            let (mut send, mut recv) = match conn.accept_bi().await {
                Ok(s) => s,
                Err(_) => break,
            };
            // 处理自定义协议的流
        }
    });
}

关键点：

• Endpoint::builder().bind() 完成所有底层工作：绑定 UDP socket、注册 ALPN、启动 relay 客户端、启动发现服务。
• connect() 接受 NodeAddr，而 NodeAddr = NodeId + relay_urls + direct_addresses，三部分任意缺失都能尝试连接——relay 兜底，pkarr 重新发现。
• 连接即 QUIC 连接，所有自定义协议通过 open_bi / accept_bi 在同一条连接上跑多个流，ALPN 决定初始握手协议。

这套 API 比起 libp2p 的 SwarmBuilder + NetworkBehaviour + From 实现一堆，心智负担小很多。

iroh-blobs：BLAKE3 内容寻址

iroh-blobs 是 iroh 上的内容寻址数据传输协议，类似简化版的 bitswap，但有几个关键差异：

iroh-blobs 的「verified streaming」基于 BLAKE3 的流式哈希树：每个 chunk 的哈希可以从根哈希推导，下载过程中任意位置的数据都能即时验证，不需要等整个 blob 下载完。这让 iroh-blobs 在大文件分块下载、断点续传上很自然。

最简用法（写一个 blob 到本地 store 并生成可分享 ticket）：

1
2
3
4
5
6
7
8
9

use iroh_blobs::{HashAndFormat, BlobFormat};
use iroh_blobs::api::Blobs;

let client: Blobs = todo!("从 iroh router 拿到");

let data = b"hello world";
let outcome = client.add_bytes(data).await?;
let hash: HashAndFormat = HashAndFormat::raw(outcome.hash);
// 把 hash + NodeAddr 打包成 Ticket 分享给其他节点

读取端拿到 Ticket 后用同样的 client 去对方节点请求并验证。

iroh-gossip：Plumtree 群组广播

iroh-gossip 用的是 Plumtree（Epidemic Broadcast Trees，2007 年 INFORUM 论文），而不是 libp2p Gossipsub 那类基于随机 mesh 的协议。

两者的差异在机制层面：

iroh-gossip 的 API 是 topic-based：节点 join(topic) 后，对该 topic 的 broadcast 会被沿着 Plumtree 树扩散到所有订阅者。和 libp2p 的 gossipsub.publish(topic, msg) 形态接近，但底层机制完全不同。

iroh-docs：CRDT 键值存储

iroh-docs 是最上层的「meta 协议」，本质是基于 CRDT（具体是 iroh-sync 的 automerge-like 实现）的多维键值存储——每个 document 是一个 Map<Author, Key, Value>，Author 是写入者签名身份，Value 序列化为 blob 存进 blobs 层。

它叠加在 blobs + gossip 之上：

• 写入：作者用 Author 私钥签一条 entry，entry 的 value 写入 blobs 层（拿到 BLAKE3 哈希）；
• 同步：gossip 把 entry 的新哈希广播给群组其他成员；
• 合并：所有节点收到 entry 后按 CRDT 规则合并，结果一致。

iroh-docs 的典型场景是协作编辑、共享配置、多设备同步——任何需要「多端最终一致」的应用。分享一个 document 用 DocTicket，对方 join 后自动同步整个文档历史。

与 libp2p 的设计哲学对比

iroh 和 libp2p 不是「新旧」关系，而是两种不同的设计哲学。把它和系列里 libp2p 的文章对照看会更清楚。

身份与寻址

iroh 这套设计的好处是上层不用管地址漂移，代价是你必须信任 iroh 的发现层（默认用 n0 公共 pkarr 节点和 n0 公共 relay，自建需要额外部署）。

传输层

iroh 用 ALPN 做协议复用是一条更「标准」的路（HTTP/2、HTTP/3 都用 ALPN）。libp2p 的 Protocol ID 字符串更灵活但要自己管版本。

NAT 穿透与中继

这是 iroh 和 libp2p 最大的工程差异：

iroh relay 之所以能做无状态，是因为它复用了 QUIC 连接——客户端到 relay 是一条 QUIC 连接，relay 只做转发不做解密，连接本身由两端的 QUIC 状态机维护。libp2p relay 建立在 StreamMuxer 之上，relay 必须维护 stream 到 peer 的映射。

n0 在 1.0 发布时公布的数据：他们的公共 relay 已经承载了 2 亿条连接，正是因为无状态才能扛住这个量级。

协议栈体积

从依赖角度看，iroh 的协议栈更收敛：

iroh 的设计假设是「你只想要一条加密直连」，libp2p 的设计假设是「你可能在搭一个完整的 P2P 系统，需要 Kad/Gossipsub/PubSub/Identify 全套」。两边各自合理。

最简节点代码对照

把同一个需求——「两个节点建立一条加密直连，互相发一条消息」——分别用 iroh 和 rust-libp2p 实现，能直观看出 API 差异。

iroh 版本

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

use iroh::{Endpoint, NodeAddr};
use iroh_base::SecretKey;
use tokio::io::{AsyncReadExt, AsyncWriteExt};

const ALPN: &[u8] = b"echo/1";

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let secret = SecretKey::generate(rand::rngs::OsRng);
    let endpoint = Endpoint::builder()
        .secret_key(secret)
        .alpns(vec![ALPN.to_vec()])
        .bind()
        .await?;

    println!("NodeId: {}", endpoint.node_id());

    // 简化演示：实际应用中 NodeAddr 通过带外通道交换
    // （控制台复制粘贴、二维码、邀请链接等）
    let args: Vec<String> = std::env::args().collect();
    if args.len() > 1 {
        // 拨号方
        let peer_addr: NodeAddr = args[1].parse()?;
        let conn = endpoint.connect(peer_addr, ALPN).await?;
        let (mut send, mut recv) = conn.open_bi().await?;
        send.write_all(b"ping").await?;
        send.finish()?;
        let mut buf = vec![0u8; 4];
        recv.read_exact(&mut buf).await?;
        println!("got: {}", String::from_utf8(buf)?);
    } else {
        // 接受方
        println!("NodeAddr to share: {}", endpoint.node_addr());
        while let Some(incoming) = endpoint.accept().await {
            let conn = incoming.await?;
            tokio::spawn(async move {
                let (mut send, mut recv) = conn.accept_bi().await?;
                let mut buf = vec![0u8; 4];
                recv.read_exact(&mut buf).await?;
                send.write_all(b"pong").await?;
                send.finish()?;
                Ok::<_, anyhow::Error>(())
            });
        }
    }
    Ok(())
}

Cargo.toml：

1
2
3
4
5
6

[dependencies]
iroh = "1.0"
iroh-base = "0.1"
tokio = { version = "1", features = ["full"] }
anyhow = "1"
rand = "0.8"

rust-libp2p 对照（同样需求）

对应的 libp2p 版本（参见系列《Rust P2P 开发实战》），同样的「建立加密连接 + 发一条消息」需要：

1. SwarmBuilder::with_new_identity() 生成身份
2. .with_tokio() .with_quic() 配置传输
3. .with_ping() 组合 NetworkBehaviour
4. 监听 + 拨号 + 事件循环匹配 SwarmEvent + ping::Event
5. 处理 From 实现把 behaviour event 转成 swarm out_event

代码量大约是 iroh 的 2–3 倍，而且要理解 Swarm / Behaviour / Event 三件套的关系。这不是说 libp2p 设计差——它把这些抽象做出来是为了支持复杂的协议组合（Kad + Gossipsub + Identify 同时跑）。但如果你只想要「一条加密直连跑自定义协议」，iroh 的抽象层级更贴近需求。

选型边界：什么时候用 iroh，什么时候不用

iroh 的优势集中在点对点直连 + 设备到设备同步这个象限。把它和系列里其他场景的对照放出来：

iroh 合适的场景

• 多设备同步：笔记、配置、相册等需要在用户自己的多台设备间同步。iroh-docs 的 CRDT 模型天然适合。
• 文件传输与分享：iroh-blobs 的 BLAKE3 verified streaming 适合大文件、断点续传、内容校验。
• 私有协议的端到端加密通道：嵌入式设备、IoT 网关、边缘节点之间跑自定义协议，iroh 核心 + ALPN 足够。
• 需要 NAT 穿透但不想自建 TURN：n0 公共 relay 起步免费，自建 relay 因为无状态比 TURN 便宜得多。

iroh 不合适的场景

• 浏览器端 P2P：iroh 只支持 QUIC，浏览器不能直接用，需要额外的 WebTransport 桥接或 gateway。如果你目标是 WebRTC 兼容的浏览器通信，libp2p 的 WebRTC transport 或原生 WebRTC 更合适（参见《NVR 远程访问 P2P 技术方案全面调研》）。
• 需要大规模去中心化路由：iroh 的 pkarr 发现依赖 BitTorrent mainline DHT，没有自己的大规模 Kad 路由层。如果你的应用是公链节点、文件共享公网（几百万人共享同一个 DHT），libp2p 的 Kad 实现更成熟（参见《Kademlia DHT 协议深度解析》《libp2p 协议栈与 BitTorrent》）。
• 多语言客户端：iroh 是 Rust-first 的，官方没有 Go/JS/Python 的完整对等实现。libp2p 有 Go、JS、Rust、Python 多语言实现，跨语言 P2P 系统首选 libp2p。
• 强制 TCP/HTTPS 网络环境：iroh 只走 QUIC（UDP），部分企业网封 UDP 时只能依赖 relay 中转。如果你的目标网络对 UDP 不友好，libp2p 的 TCP + Noise 路径更稳。
• 需要复杂的协议组合（Kad + Gossipsub + Identify + PubSub）：libp2p 的 Swarm/Behaviour 抽象就是为这个设计的，iroh 需要你自己组装。

决策树

flowchart TD
    A["需要 P2P 通信"] --> B{"浏览器是客户端？"}
    B -->|"是"| C["libp2p WebRTC<br/>或原生 WebRTC"]
    B -->|"否"| D{"需要跨语言客户端？"}
    D -->|"是"| E["libp2p（Go/JS/Rust）"]
    D -->|"否，全 Rust"| F{"需要大规模 DHT 路由？"}
    F -->|"是，公网规模"| G["libp2p Kad"]
    F -->|"否，设备到设备"| H{"主要场景？"}
    H -->|"文件/内容传输"| I["iroh-blobs"]
    H -->|"多设备状态同步"| J["iroh-docs"]
    H -->|"自定义协议直连"| K["iroh 核心"]
    H -->|"群组消息广播"| L["iroh-gossip<br/>或 libp2p Gossipsub"]

    classDef pick fill:#E8F5E9,stroke:#4CAF50,color:#1B5E20
    classDef alt fill:#E3F2FD,stroke:#2196F3,color:#0D47A1
    class C,E,G alt
    class I,J,K,L pick

这张图不是绝对——iroh-gossip 和 libp2p Gossipsub 在「群组广播」场景重合度很高，如果团队已经在用 libp2p，没必要为了一两个群组切到 iroh-gossip。

自建与生产部署考量

iroh 1.0 之后，n0 把公共 relay 服务商业化：免费档有连接数限制，商用档按容量计费。如果你的应用不依赖 n0 公共服务，自建需要考虑几个点。

自建 relay

iroh-relay 在 n0-computer/iroh 仓库里，包含 server 端实现，可独立部署。它无状态的特性意味着：

• 可以放在任意负载均衡后面（Cloudflare、nginx、HAProxy），不用 sticky session；
• 横向扩展直接加机器，节点间不需要共享状态；
• 单实例失败不影响已建立的直连（只影响中继流量），客户端会自动切其他 relay 或重试。

对比自建 TURN（参见《P2P 信令与中继服务器技术调研》的 TURN 部分），iroh relay 的运维成本明显低。

自建 pkarr 发现节点

iroh 默认通过 BitTorrent mainline DHT 做 pkarr 发现（节点把自己的 NodeId + 当前地址签名后发布到 DHT）。这个发现机制本身是去中心化的，理论上不需要自建。但在企业内网或受限网络里，mainline DHT 不可达时需要：

• 部署一个 mainline DHT bootstrap 节点；
• 或者用 iroh 的 DNS 发现（pkarr 记录编码为 DNS TXT 记录，走自建 DNS server）。

iroh 仓库里带了 iroh-dns-server 做这件事。

许可证与供应链

iroh 全栈 Apache-2.0 OR MIT，是商业友好的双许可证。但有几个供应链风险点要注意：

• iroh 1.0 之前 API 多次大改（crate 重命名、模块重组），老代码迁移成本不低。1.0 承诺 API 稳定，但生态里 iroh-blobs/iroh-docs 等周边 crate 还在快速迭代。
• n0 公司本身是商业公司，公共 relay 服务有 EOL 政策（0.x 版本对应的 relay 已经停止服务）。如果你的应用依赖 n0 公共 relay，要关注他们的服务条款变更。
• iroh 团队规模比 libp2p 协议生态小（libp2p 由 Protocol Labs 维护，背后是 IPFS/Filecoin 的整个生态）。iroh 的长期可持续性取决于 n0 公司的商业化能否跑通。

与系列其他文章的关系

本篇是「P2P 应用调研」章节里 iroh 这条线的入口。要深入相关主题，可以结合系列其他篇目：

• 传输与协议基础：《P2P 网络核心原理》《libp2p 协议栈与 BitTorrent》《Kademlia DHT 协议深度解析》《Gossip 协议核心原理》——理解 iroh 各层背后的经典算法。
• 代码实战：《Rust P2P 开发实战：从 Ping 到 Gossipsub》——libp2p 这条线的对照代码，本篇引用了它的对照示例。
• 工程实践：《P2P 信令与中继服务器技术调研》——STUN/TURN/ICE/DERP 的完整图谱，iroh 的 relay 设计可以放在这个谱系里理解。
• 应用场景：《NVR 远程访问 P2P 技术方案全面调研》——监控/IoT 场景的 P2P 实践，iroh-blobs/iroh-docs 的潜在落地领域。

参考来源

官方资料

• iroh GitHub（核心仓库）. https://github.com/n0-computer/iroh
• Iroh 1.0 — Dial Keys, not IPs（1.0 发布博客）. https://www.iroh.computer/blog/v1
• What is Iroh?（官方文档）. https://docs.iroh.computer/what-is-iroh
• Comparing Iroh & Libp2p: Simplifying P2P Connectivity（官方对比）. https://www.iroh.computer/blog/comparing-iroh-and-libp2p
• Documents Protocol. https://docs.iroh.computer/protocols/documents
• Tickets 概念. https://docs.iroh.computer/concepts/tickets
• iroh crate（docs.rs）. https://docs.rs/iroh
• iroh::endpoint::Builder. https://docs.rs/iroh/latest/iroh/endpoint/struct.Builder.html

周边仓库

• iroh-blobs. https://github.com/n0-computer/iroh-blobs
• iroh-gossip. https://github.com/n0-computer/iroh-gossip
• iroh-docs. https://github.com/n0-computer/iroh-docs
• iroh-examples. https://github.com/n0-computer/iroh-examples
• iroh-workshop（39c3 workshop）. https://github.com/n0-computer/iroh-workshop-39c3

深度分析

• Deep dive into iroh: A replacement for WireGuard or a P2P framework for your applications?（kerkour.com）. https://kerkour.com/iroh-v1-p2p
• The Wisdom of Iroh（LambdaClass）. https://blog.lambdaclass.com/the-wisdom-of-iroh/

协议论文与 RFC

• Leitão, J., Pereira, J., Rodrigues, L. Epidemic Broadcast Trees（Plumtree，iroh-gossip 的基础）. 2007 IEEE International Symposium on Reliable Distributed Systems.
• RFC 9000 — QUIC: A UDP-Based Multiplexed and Secure Transport. https://datatracker.ietf.org/doc/rfc9000/
• RFC 7301 — TLS Application-Layer Protocol Negotiation Extension（iroh ALPN 复用的基础）. https://datatracker.ietf.org/doc/rfc7301/
• pkarr（基于 mainline DHT 的签名记录）. https://pkarr.org

社区讨论

• Iroh: A library to establish direct connection between peers（HN 讨论）. https://news.ycombinator.com/item?id=44379173
• Iroh 1.0 HN 讨论. https://news.ycombinator.com/item?id=48542480
• libp2p-iroh: PeerId based Dialing（rust-libp2p 桥接 iroh 传输）. https://discuss.libp2p.io/t/libp2p-iroh-peerid-based-dialing-behind-any-nat/3672