Rust 构建 Nostr 中继：buzz 项目架构与工程实践

1. 从 buzz 这个名字说起它到底想解决什么问题第一次看到 buzz 这个项目名加上关键词里蹦出来的 Nostr、relay、Rust、workspace我大概能猜到这是个什么路数——一个用 Rust 写的 Nostr 中继relay实现。Nostr 这套协议这两年热度一直没降核心思路其实很朴素把身份和数据传输彻底解耦用户靠一对密钥证明我是我内容通过一堆互不隶属的 relay 来转发和存储。而 relay 就是这套体系里最脏最累的活——它要处理海量连接、验证签名、做事件去重、按订阅条件过滤推送还得扛住各种畸形输入。为什么有人愿意用 Rust 重写一个 relay我自己的判断是三个字扛得住。Nostr relay 本质上是个长连接 高并发的消息中间件每个客户端可能同时挂着几十条订阅每条订阅又对应一套过滤条件filter事件进来之后要跟所有活跃订阅做匹配。用动态语言写原型阶段很爽一旦连接数上到几千、事件吞吐上到每秒几万GC 停顿和内存抖动就会让你怀疑人生。Rust 没有 GC所有权模型逼着你在编译期就把并发安全问题想清楚配合 tokio 的异步运行时单机撑住相当可观的连接数是有可能的。buzz 这个词本身也挺有意思它暗示的是嗡嗡作响、消息不断的状态一个 relay 最理想的工作状态不就是这个么——事件像蜂群一样涌进来被有序地验证、存储、分发出去整个过程安静又高效。关键词里的 workspace 说明这个项目大概率用了 Cargo workspace 来组织多 crate 结构这在稍微正经一点的 Rust 项目里几乎是标配把协议解析、存储层、网络层、配置管理拆成独立 crate各自编译、各自测试主二进制只负责组装。这篇文章我不打算写成一份干巴巴的 API 文档而是想从一个真的动手搭过一个 relay的角度把 buzz 这类项目背后的设计取舍、Rust 工程化的坑、以及实际跑起来之后会遇到的问题讲透。不管你是刚学 Rust 想找个真实项目练手还是已经在维护自己的 relay应该都能捞到点东西。2. Nostr relay 的核心职责拆解buzz 必须处理的四件事在动手看代码之前得先把一个 relay 到底要干什么这件事想明白。很多人一上来就盯着 WebSocket 怎么建、数据库怎么选结果写到一半发现协议语义没吃透返工成本极高。我把 relay 的职责归纳成四块buzz 这类实现基本都绕不开。2.1 连接管理与订阅生命周期relay 和客户端之间是 WebSocket 长连接。客户端连上来之后会发两种核心消息REQ建立订阅带一串 filter和EVENT发布事件。relay 收到REQ之后要记住这个订阅之后每来一个新事件都要拿它去跟所有订阅匹配命中了就推给对应连接。客户端不想听了就发CLOSErelay 得把订阅清掉否则内存里会堆积一堆僵尸订阅。这里有个很容易被忽略的点订阅是有生命周期的而且和连接强绑定。连接断了这个连接上挂的所有订阅都得跟着销毁。我见过一些早期实现订阅存在一个全局 map 里连接断开时忘了清理跑几天内存就爆了。Rust 里这个问题相对好处理因为你可以把订阅的所有权挂在连接任务task上连接任务结束订阅自然 drop。但前提是你得设计对——如果用ArcMutexHashMap...全局共享就得手动清理反而更容易漏。2.2 事件验证签名、ID、时间戳Nostr 事件的结构大致是{id, pubkey, created_at, kind, tags, content, sig}。relay 收到事件后至少要验证三件事id 是否等于对事件序列化结果做 SHA-256 的哈希。这一步是防止有人篡改内容却复用旧 id。sig 是否是 pubkey 对 id 的有效 Schnorr 签名。Nostr 用的是 secp256k1 上的 Schnorr 签名Rust 生态里secp256k1这个 crate 支持得比较成熟。created_at 是否在合理范围内。太离谱的未来时间或远古时间很多 relay 会选择拒绝防止有人用时间戳刷屏。验证这块是 CPU 密集型操作Schnorr 验签虽然比 ECDSA 快但量大了照样吃 CPU。所以 buzz 这类项目通常会把验证放在独立的线程池或者用tokio::task::spawn_blocking处理避免阻塞异步运行时的工作线程。这一点如果做错表现就是连接数一多事件处理延迟飙升但 CPU 又没跑满——因为全卡在异步线程里做同步计算了。2.3 存储层事件怎么落、怎么查存储是 relay 的另一个大头。事件要持久化订阅匹配时要能快速按条件捞出来。常见的 filter 条件包括按作者authors、按事件类型kinds、按标签如#e、#p、按时间范围since/until、按 id 列表。这些条件组合起来对查询能力的要求其实不低。选型上大致两条路关系型数据库SQLite、Postgres和嵌入式 KV / 专用存储。SQLite 胜在零运维、单文件、事务可靠适合个人或小规模 relayPostgres 适合需要多实例、复杂查询的场景。buzz 作为 Rust 项目用 SQLite 配合sqlx或rusqlite是很自然的选择。但要注意SQLite 的写是串行的高并发写入场景下得做批量提交或者用 WAL 模式缓解。2.4 消息分发把事件推给对的人事件存下来只是第一步真正体现 relay 价值的是实时分发。一个新事件进来relay 要遍历所有活跃订阅判断哪些 filter 命中然后推给对应连接。这里的性能关键在于别每次都全量遍历。如果有一万个活跃订阅每个事件都扫一遍吞吐直接崩。优化思路通常是给订阅建索引按 kind 分桶、按 author 分桶事件进来先定位到可能命中的桶再做精确匹配。buzz 如果做得细应该会在订阅注册时就解析 filter提取出可以用于索引的维度。这块的设计好坏直接决定了 relay 能扛多少连接。3. 用 Cargo workspace 组织 buzz多 crate 拆分的实际收益关键词里出现 workspace基本可以确定 buzz 不是单 crate 项目。Cargo workspace 在 Rust 里就是一个仓库管多个 crate的机制根目录一个Cargo.toml声明成员各个子 crate 各管各的依赖和编译产物。很多人觉得这是大项目才需要的排场其实不然relay 这种职责边界清晰的项目拆 workspace 的收益非常直接。3.1 为什么 relay 特别适合拆 workspacerelay 的几块职责——协议类型定义、存储、网络服务、配置——耦合度天然就低。协议类型Event、Filter、ClientMessage、RelayMessage是纯数据结构不依赖任何 IO存储层只依赖协议类型和数据库驱动网络层依赖协议类型和存储层配置层谁都能用。这种依赖关系画出来是一棵树不是一张网拆起来毫无痛苦。拆开之后有几个实打实的好处。第一是编译增量你改网络层的代码协议 crate 不用重编如果协议 crate 本身又依赖了一堆 serde、secp256k1 这种重依赖省下的时间很可观。第二是测试隔离存储层的单元测试不需要起 WebSocket 服务跑得飞快。第三是依赖收敛网络层引入的 tokio、tungstenite 不会污染协议 crate协议 crate 可以保持极简依赖将来想复用到别的项目里也方便。我自己的经验是一个 relay 项目如果所有代码堆在一个src/里超过三四千行之后维护就开始难受了。workspace 拆分不是过度设计而是给未来的自己留条路。3.2 一个务实的 crate 划分方案结合 buzz 的场景我会这样拆crate 名称职责关键依赖buzz-core协议类型、序列化、签名验证serde, secp256k1, sha2buzz-store事件持久化、查询、索引sqlx 或 rusqlitebuzz-relayWebSocket 服务、连接管理、订阅分发tokio, tungstenite/axumbuzz-config配置解析、环境变量、默认值serde, configbuzz-bin主程序入口组装以上模块以上全部这个划分的关键在于依赖方向单一buzz-bin依赖所有buzz-relay依赖 core 和 storebuzz-store依赖 corebuzz-core谁也不依赖。只要守住这条线就不会出现循环依赖。Rust 的 crate 之间不允许循环依赖这其实是个好事它逼着你把架构想清楚。3.3 workspace 依赖统一管理的细节workspace 根Cargo.toml里可以用[workspace.dependencies]统一声明版本子 crate 里用workspace true引用。这样做的好处是tokio 的版本只在一个地方改所有 crate 同步升级不会出现 A crate 用 tokio 1.35、B crate 用 tokio 1.40 的尴尬。[workspace] members [buzz-core, buzz-store, buzz-relay, buzz-config, buzz-bin] resolver 2 [workspace.dependencies] tokio { version 1, features [full] } serde { version 1, features [derive] } serde_json 1 secp256k1 { version 0.29, features [rand, global-context] } sqlx { version 0.7, features [runtime-tokio, sqlite] }提示resolver 2在 edition 2021 之后是默认的但显式写出来更保险尤其是 workspace 里混着不同 edition 的 crate 时特性解析行为会更符合预期。有个坑我得提醒一下[workspace.dependencies]只统一版本声明不统一 feature。子 crate 引用时仍然要自己写 feature比如tokio { workspace true, features [net] }。如果你以为根里写了features [full]子 crate 就自动继承那会编译报错找不到符号。这个我踩过排查了半天。4. 事件验证与存储的 Rust 实现要点前面讲的是架构层面的东西这一节落到具体代码。relay 的性能瓶颈和正确性风险八成集中在验证和存储这两块。4.1 Schnorr 验签的正确姿势与性能考量Nostr 事件签名用的是 BIP-340 定义的 Schnorr 签名。Rust 里secp256k1crate 提供了verify_schnorr。验证流程大致是先把事件按规范序列化成[0, pubkey, created_at, kind, tags, content]的 JSON 数组做 SHA-256 得到 id再用 pubkey 对 id 验签。这里有个细节特别容易错序列化格式必须和客户端完全一致。JSON 里数组元素的顺序、字符串转义、数字格式任何一点差异都会导致算出来的 id 对不上验签直接失败。规范里对序列化有明确定义实现时最好直接照抄参考实现别自己发挥。我见过有人用serde_json::to_string直接序列化一个结构体结果字段顺序和规范不一致所有事件都验不过。性能上验签是纯 CPU 计算单次大概几十微秒量级。如果 relay 每秒要处理上万个事件那就是几百毫秒的 CPU 时间必须并行化。做法是用spawn_blocking把验签丢到阻塞线程池let event event.clone(); let valid tokio::task::spawn_blocking(move || verify_event(event)) .await .unwrap_or(false);spawn_blocking的线程池默认上限是 512对于验签这种短任务够用。但要注意别在里面做太重的活否则线程池会被占满反而拖慢其他阻塞操作。4.2 存储 schema 设计与索引策略用 SQLite 存事件最朴素的 schema 是一张events表把 id、pubkey、created_at、kind、content、sig 都存进去tags 单独一张表或者序列化成 JSON 存一列。查询时按条件拼 SQL。但朴素方案在订阅匹配时会很慢因为 filter 条件组合太多。我的做法是为高频查询维度建索引CREATE TABLE events ( id TEXT PRIMARY KEY, pubkey TEXT NOT NULL, created_at INTEGER NOT NULL, kind INTEGER NOT NULL, content TEXT NOT NULL, sig TEXT NOT NULL, tags TEXT NOT NULL ); CREATE INDEX idx_events_pubkey_created ON events(pubkey, created_at DESC); CREATE INDEX idx_events_kind_created ON events(kind, created_at DESC); CREATE INDEX idx_events_created ON events(created_at DESC);tags存成 JSON 字符串需要按标签查的时候用 SQLite 的 JSON 函数或者额外建一张event_tags关联表。关联表的查询更灵活但写入时多一次插入得权衡。如果 relay 主要面向的是按作者 时间范围这类查询那idx_events_pubkey_created就能覆盖大部分场景。写入方面SQLite 默认每条 INSERT 都是一个事务高并发下会非常慢。解决办法是批量提交把短时间内的多个事件攒成一个事务一次性写入。配合 WAL 模式PRAGMA journal_modeWAL读写可以并发吞吐能提升一个数量级。// 伪代码示意批量写入 let mut tx pool.begin().await?; for event in batch { sqlx::query(INSERT OR IGNORE INTO events (...) VALUES (...)) .bind(...) .execute(mut *tx) .await?; } tx.commit().await?;INSERT OR IGNORE是为了处理重复事件——Nostr 里同一个事件可能从多个来源到达 relay用主键冲突直接忽略是最省事的去重方式。4.3 订阅匹配的索引化思路前面提过事件进来要跟所有活跃订阅匹配。如果订阅数量大全量遍历是灾难。我的优化思路是两级索引第一级按 kind 分桶。绝大多数 filter 都会指定 kind比如只订阅 kind 1 的文本笔记所以可以维护一个HashMapu64, VecSubscriptionId事件进来先按 kind 找到候选订阅。第二级在候选订阅里做精确匹配检查 authors、tags、时间范围等条件。这一级订阅数量已经小很多遍历成本可接受。对于没指定 kind 的宽订阅单独放一个列表事件进来时也要过一遍。这类订阅通常不多但要小心有人恶意注册大量宽订阅来拖垮 relay所以一般会限制单连接的订阅数量。5. 把 relay 跑起来从编译到压测的完整链路代码写完了不代表能用relay 这种服务真正的考验在跑起来之后。这一节讲讲从编译到压测的实操链路以及我踩过的几个坑。5.1 编译与依赖问题的排查Rust 项目第一次cargo build往往是最折磨人的。buzz 这种依赖了 secp256k1、sqlx、tokio 的项目编译时间不会短。几个常见问题secp256k1 的 C 依赖。这个 crate 默认会编译一个 C 版本的 libsecp256k1需要系统有 C 编译器。如果你在精简的容器环境里编译可能会报找不到cc。解决办法是装build-essential或者启用纯 Rust 实现性能会差一些。sqlx 的编译期检查。sqlx 有个query!宏会在编译期连数据库校验 SQL如果数据库没起或者 schema 不对编译直接失败。开发阶段我建议先用query而不是query!避免编译依赖运行时环境。等 schema 稳定了再切回编译期检查。镜像源配置。国内环境拉 crates.io 经常慢得离谱配置镜像源是刚需。在~/.cargo/config.toml里加[source.crates-io] replace-with mirror [source.mirror] registry sparsehttps://mirrors.tuna.tsinghua.edu.cn/crates.io-index/配完之后cargo build的速度会有质的提升。注意用 sparse 协议老的 git 协议索引拉取特别慢。5.2 配置项与运行参数relay 跑起来之前得想清楚几个参数监听地址和端口、数据库路径、最大连接数、单连接最大订阅数、事件大小上限、允许的事件 kind 范围。这些最好都做成配置项别硬编码。一个务实的配置结构大概长这样[server] bind 0.0.0.0:8080 max_connections 10000 max_subscriptions_per_connection 20 [database] path ./buzz.db batch_size 100 batch_interval_ms 50 [limits] max_event_size 65536 max_content_length 8192batch_size和batch_interval_ms是写入批量的控制参数需要根据实际负载调。批量太大延迟高太小则失去批量的意义。我的经验是 50ms 的间隔配合 100 条的批量在中等负载下比较平衡。5.3 压测怎么知道 relay 到底能扛多少不压测就上线等于闭着眼睛开车。压测 relay 需要模拟大量 WebSocket 连接每个连接发 REQ 建订阅然后持续发 EVENT。工具上可以用websocat做简单测试但要做规模化的压测得自己写脚本。我用 Rust 写过一个简易压测器核心是起 N 个 tokio task每个 task 建一个 WebSocket 连接循环发事件。关键指标看三个连接建立成功率、事件处理延迟P50/P99、CPU 和内存占用。压测时最容易暴露的问题是文件描述符耗尽。每个 WebSocket 连接占一个 fdLinux 默认单进程上限是 1024压到一千连接就报Too many open files。解决办法是调ulimit -n或者用systemd的LimitNOFILE配置。这个坑我踩过不止一次每次都是压测到一半突然全挂。另一个常见问题是内存增长。如果订阅清理有 bug或者事件缓存没设上限内存会随着时间缓慢上涨。压测时跑个几小时观察 RSS 是否稳定是发现内存泄漏的好办法。6. 那些文档里不会写的坑前面讲的都是应该怎么做这一节讲讲实际做的时候会怎么翻车。这些经验基本都是从真实调试里攒出来的。6.1 时间戳的时区与精度陷阱Nostr 的created_at是 Unix 时间戳单位是秒。听起来简单但坑不少。第一别用毫秒。有些语言的SystemTime默认给毫秒直接塞进去会导致时间戳大了一千倍relay 一看是几万年后的未来时间直接拒收。第二客户端时钟可能不准。有些客户端的时间戳偏差几分钟甚至几小时如果 relay 严格校验时间范围会误伤正常用户。我的做法是给一个宽松的容忍窗口比如允许未来 15 分钟、过去几年既能挡住明显的异常又不至于误杀。6.2 订阅过滤器的边界情况filter 里的条件是可以组合的而且有些组合的语义容易理解错。比如authors和kinds同时存在时是作者在列表里且kind 在列表里不是或。再比如ids和authors同时存在也是且的关系。这些在规范里有定义但实现时如果逻辑写反表现就是订阅收不到该收的事件或者收到一堆不该收的。还有一个边界空 filter。有些客户端会发一个所有字段都空的 filter意思是我要所有事件。这种订阅如果放任不管一个连接就能把 relay 的所有事件流量吸干。所以必须限制要么拒绝空 filter要么限制这类订阅的推送速率。6.3 优雅关闭与数据一致性relay 重启时如果正在批量写入直接 kill 进程可能丢数据。正确做法是监听关闭信号SIGTERM停止接受新连接把待写入的批量刷盘再退出。Rust 里用tokio::signal配合CancellationToken可以做得比较干净。let ctrl_c tokio::signal::ctrl_c(); tokio::select! { _ ctrl_c { // 触发关闭流程 shutdown_token.cancel(); } }关闭流程里要确保数据库连接池正常关闭否则 SQLite 的 WAL 文件可能残留下次启动要做恢复。这些细节平时看不出来一旦出问题就是数据丢失值得多花点时间做扎实。7. 关于 buzz 这类项目我的一些真实体会搭 relay 这件事技术难度其实不算特别高难的是把每个细节都做对。协议本身不复杂但边界情况多如牛毛一个时间戳单位搞错、一个 filter 逻辑写反就可能让整个 relay 不可用。Rust 在这里帮了大忙——类型系统和所有权模型能在编译期挡掉一大批并发和内存问题让你把精力集中在业务逻辑上。workspace 的拆分我强烈建议一开始就做哪怕项目还小。等到代码堆到几千行再拆迁移成本会高很多。拆的时候守住依赖方向单一这条线基本不会出问题。最后说个心态上的事relay 是个长期运行的服务它的质量不是靠一次写完决定的而是靠持续观察和迭代。上线之后盯着日志、盯着内存曲线、盯着延迟指标发现问题就改。我自己的 relay 跑了几个月中间修过订阅泄漏、修过批量写入的边界、调过验签的线程池大小每一次都是真实负载暴露出来的。这些东西文档里不会写只有自己跑起来才会遇到。