拆解Cheburcheck架构:Rust + SvelteKit + MQTT如何实现分布式封锁扫描
拆解Cheburcheck架构:Rust + SvelteKit + MQTT如何实现分布式封锁扫描
Cheburcheck 是一个开源的分布式封锁扫描平台,用于检查域名与 IP 地址是否被俄罗斯监管机构(RKN)或已封锁的 CDN 网段拦截。整个系统采用 Rust + SvelteKit + MQTT 技术栈:Rust 编写的 Rocket API 作为"大脑",MQTT 消息总线向部署在各地网络中的探测节点(Probe)下发扫描任务,SvelteKit 前端以流式方式实时展示多国多网络视角的检测结果。本文带你完整拆解它的架构设计与数据流转。
一、项目定位:为什么需要"分布式"封锁扫描 🌐
一次封锁检测,单靠服务器自己发请求是远远不够的:
- 封锁往往具有地域性(某个 ISP、某个地区被拦,其他区域正常);
- SNI 深度包检测(DPI)取决于流量经过哪一跳路由器;
- 不同网络环境看到的 DNS 解析结果可能不同(污染/劫持)。
因此 Cheburcheck 的思路是:把扫描能力下沉到分布在不同地区、不同运营商的真实设备上,由中心服务器统一调度、汇总证据。项目按职责拆分为 5 个核心模块:
| 模块 | 语言 | 职责 |
|---|---|---|
| website/ | Rust (Rocket) | API 网关、检查引擎、MQTT 调度、管理与分析 |
| frontend/ | SvelteKit (TS) | SSR 页面,流式展示扫描结果 |
| probe/ | Rust | 部署在用户机器上的动态网络扫描器 |
| querying/ | Rust | 封锁名单检查库(DNS 解析、RKN 黑名单、CDN 网段、GeoIP) |
| reporter/ | Rust | 大规模批量扫描器(默认扫 Tranco Top 10万域名) |
辅助模块 reports/ 定义了 Probe 与中心之间的 JSON 消息协议,rmqtt/ 是 MQTT 代理的配置。
二、Rust 检查引擎:先做"名单判定"
用户在网站输入域名或 IP 后,请求先打到 Rocket 构建的后端(website/src/main.rs):
/api/v1/check?target=example.com
判定逻辑集中在 querying/src/lib.rs 的 Checker 中,流程是:
- DoH 解析——通过 Quad9 的 DNS-over-HTTPS 解析目标,绕过本地 DNS 限制拿到真实 IP(querying/src/resolver.rs);
- RKN 黑名单匹配——域名是否在监管机构的封锁名单中(querying/src/lists.rs);
- CDN 网段匹配——IP 是否落在已知被封锁的 CDN 提供商网段内;
- GeoIP / ASN 补充——输出归属地与自治系统信息(querying/src/geoip.rs、querying/src/asn.rs)。
这三份数据库(GeoIP、RKN 黑名单、CDN 列表)由后台任务定期下载并原子热更新(ArcSwap 换指针),检查请求无需重启服务。API 同时做了限流、查询落库(PostgreSQL + ClickHouse 分析库),并返回一个签名后的查询上下文 ID——这个 ID 是下一步触发探针扫描的"凭证",防止伪造任务。
三、MQTT 总线:连接"大脑"与"四肢"的消息中枢 📡
这是整个系统最巧妙的部分。Cheburcheck 没有给每个探针开 HTTP 长轮询或 WebSocket 网关,而是选用了 MQTT over WebSocket(WSS)——一种为低功耗设备设计的轻量发布/订阅协议。
- 代理选用 rmqtt,同时开三个监听:外网 TCP(1883)、WebSocket(8080,经 nginx 暴露为
/mqtt)、内网 TCP(11883,供同机器的 website 服务使用); - 认证走 HTTP 回环:rmqtt 通过 rmqtt-auth-http 插件 把每次连接与每次主题访问转发给 website 的
/mqtt/auth与/mqtt/acl接口动态裁决(website/src/mqtt_auth.rs); - 探针只需一条出向的 443 加密连接即可"被找到",穿透 NAT 零成本,这正是它能部署在无数家庭路由器和 VPS 上的关键。
核心主题设计(website/src/mqtt.rs):
| 主题 | 方向 | 作用 |
|---|---|---|
probe/config/v1 |
中心 → 探针(retained) | 下发扫描主机、超时、DPI 配置 |
probe/status/v1/{id} |
探针 → 中心(retained + Last Will) | 上线/下线状态;断线自动置 offline |
probe/tasks/v1/{query_id} |
中心 → 探针 | 广播一个扫描任务(指定探针可定向) |
probe/results/v1/{query_id}/{probe_id} |
探针 → 中心 | 回传扫描证据 |
probe/commands/v1/{probe_id}/{cmd_id} |
中心 → 探针 | 指令式命令(traceroute、SNI 探测、重测 DPI) |
probe/update/v1 |
中心 → 探针 | 触发远程自动更新 |
值得注意的两个工程细节:
- Last Will 遗嘱消息:探针进程异常退出时,代理自动发布 offline 状态,中心永远知道谁还在线(probe/src/main.rs 中
set_last_will); - retained 消息:探针重连后立即收到最新配置与状态,无需中心重推。
四、Probe 探针:跑在每台机器上的"分布式眼睛" 👁️
Cheburprobe(probe/)是一个 Rust 编写的常驻守护进程,支持 Debian、OpenWrt(含 LuCI 界面)、Docker、Windows 实验性包,一行 install-probe.sh 即可安装并自动更新。
收到任务后,每个探针并行执行三类探测(tokio::join! 并发,并发度由 MAX_CONCURRENT_TASKS 控制,默认 8):
- SNI 探测(probe/src/sni.rs)——对配置文件中列出的境外/境内测试主机(website/probe-hosts.toml,含 Hetzner、OVH、Akamai 与俄罗斯本地 Selectel)建立 TCP 连接、发出携带目标域名 SNI 的 TLS ClientHello 再发 HTTP GET。如果境外主机连不上而本地白名单主机正常,即可判定"网络被封锁"。TLS 校验被刻意关闭——测的是连通性,不是证书信任;
- TCP Traceroute(probe/src/traceroute.rs)——定位流量路由中的封锁发生跳(DPI hop),判断拦截发生在哪一级设备;
- DNS 采样(probe/src/dns.rs)——多次解析比对,检测 DNS 污染/劫持(
dns_spoofing_provider_threshold控制判定阈值)。
探针还会校准本地 DPI 跳(probe/src/dpi_hop.rs):通过对比正常 SNI 与被拦 SNI 在每一跳的 RST/丢包差异,精确定位执行深度包检测的路由器 TTL,并把结果写回状态消息供中心参考。所有探针与中心共享的消息结构定义在 reports/src/probe.rs,这是两端能无缝对接的"契约"。
五、一次完整扫描请求的旅程 🔍
把前面所有环节串起来,用户在浏览器输入域名后:
① SvelteKit 页面 → GET /api/v1/check(Rust 名单判定,返回签名 ID)
② 前端 → GET /api/v1/probe/{id}(SSE 流式接口)
③ Rocket 挑选在线探针 → 发布任务到 probe/tasks/v1/{id}
④ Rocket 订阅 probe/results/v1/{id}/+ 等待回传
⑤ 各探针并行探测 → 结果经 MQTT 回流
⑥ Rocket 逐条转成 SSE 事件推给浏览器,同时落 ClickHouse 并缓存 3 小时
- 前端无需轮询:接口基于 Rocket 的
EventStream持续推送started/result/done事件(website/src/api/probe.rs); - 同一目标 3 小时内的探针结果走内存缓存,重复查询秒级返回;
- 探针超时未回传则流自动结束,页面展示已到达的部分结果——部分证据也比没有强。
结果页会汇总展示:判定结论、各区域探测点状态(frontend/src/lib/components/result/ 下的 ProbeRegionMap.svelte、ComplaintTrend.svelte 等组件)、DPI 跳 traceroute 明细与历史投诉趋势。
六、Reporter 与白名单:第二条"分布式"流水线 📊
Probe 负责"按需点检",reporter/ 负责"地毯式普查":
- 默认扫描 Tranco 排行榜 Top 100,000 域名,
-p参数可调至 1000 并发(reporter/src/main.rs); - 通过 SNI 方式判定哪些域名实际上未被封锁,结果提交到 Cheburcheck Agency(
/agency/report,API Key 鉴权); - 平台据此自动积累白名单,在检查接口中直接展示"该域名虽在名单上但实际可访问",大幅降低误报。
它还内置 systemd 定时器:每 6 小时跑一次 10 万域名、每天凌晨跑一次 100 万域名(reporter/debian/ 下的 cheburchecker.100k.timer 与 cheburchecker.1kk.timer),形成持续更新的封锁态势数据。
七、部署拓扑:四个容器 + 一套 nginx 路由
整个平台用 docker-compose.yaml 一键拉起,docker compose up --build 后由 nginx(nginx.conf)作为唯一入口分发:
| 路由 | 目标服务 | 说明 |
|---|---|---|
/api/v1/*、/agency/*、/whitelist/* |
website (Rocket:8000) | REST API |
/mqtt |
rmqtt (WS:8080) | 探针 WebSocket 入口,1 小时超时 |
/install-probe.sh |
website | 探针自动安装脚本 |
| 其余路径 | frontend (SvelteKit:3000) | SSR 页面 |
外部探针经公网 443 接入 /mqtt,内部 website 服务走 Docker 内网的 11883 TCP 端口连 rmqtt——内外网监听分离是配置里一个清晰的隔离思路。
八、为什么选这三样技术?💡
- Rust:探针要跑在路由器等弱资源设备上,Rust 的高性能 + 零成本并发 + 强类型协议(
reports库)让两端消息契约不易漂移; - SvelteKit (SSR):检查结果是 SEO 友好的静态可渲染页面,SSE 流式更新让"等待分布式结果"变成即时体验;
- MQTT:发布/订阅 + retained + Last Will 三个原生特性,恰好覆盖了"任务下发、断线感知、状态同步"三类需求,避免了自研长连接协议的数百行代码。
总结
Cheburcheck 用一套教科书式的分层架构回答了"如何低成本获得全网视角":Rust 引擎做静态判定,MQTT 总线做动态调度,Probe 探针做边缘执行,Reporter 做批量普查。模块边界清晰(querying、reports 均可独立复用)、消息契约集中定义、部署仅需一条 compose 命令——对想学习"中心-边缘"分布式系统设计的人来说,是一个非常值得细读的小型开源范例。
