RuView WiFi-DensePose 系统架构详解：从 CSI 数据采集到多协议服务的五层可扩展设计-平芜编程栈

RuView WiFi-DensePose 系统架构详解：从 CSI 数据采集到多协议服务的五层可扩展设计

【免费下载链接】RuViewπ RuView turns commodity WiFi signals into real-time spatial intelligence, vital sign monitoring, and presence detection — all without a single pixel of video.项目地址: https://gitcode.com/GitHub_Trending/wi/RuView

导读

本文以 plans/phase2-architecture/system-architecture.md 为核心骨架，系统拆解 RuView（WiFi-DensePose）项目如何将普通商用 WiFi 路由器采集的信道状态信息（CSI），经信号预处理、神经网络推理、多目标跟踪，最终通过 REST / WebSocket / MQTT / Webhook 多协议接口交付给上层应用。文中所有架构决策、组件职责、数据流参数与部署规格均完整继承自该设计文档，并结合仓库中v2/crates的 Rust 实现、docker/docker-compose.yml 部署文件与 monitoring/prometheus-config.yml 监控配置逐一印证。读完本文，你将掌握该系统的分层设计方法、端到端数据管线、容器/K8s 部署规格、性能与安全架构，以及如何在当前仓库中对照源码定位每一层的落地实现。

1. 系统全景：五层架构与关键特性

1.1 设计定位

WiFi-DensePose 是一套隐私保护的无线人体姿态估计系统：不依赖摄像头与光学传感器，仅通过普通 WiFi 基础设施上的 CSI 信号完成实时人体姿态估计。其核心思路是把"WiFi 信号"这一物理媒介转化为"空间智能"数据源，从而在医疗看护、零售分析、安防等场景提供无感、无摄像头的感知能力。

架构文档将整个系统划分为五个逻辑层，每一层职责单一、边界清晰：

1.2 关键系统特性

隐私保护：全链路无摄像头、无光学传感器，规避视频隐私风险；
实时处理：设计目标为端到端延迟低于 100ms；
穿墙检测：可穿透墙体与障碍物感知人体姿态；
多人跟踪：设计支持同时跟踪最多 5 人；
模块化可扩展：组件松耦合，可适配边缘设备到云端多种部署形态；
领域专属分析：面向医疗、零售、安防等垂直领域提供专门化分析能力。

需要说明的是，本文档（Version 1.0，Status: Draft）中的精度 87.2%、延迟 <100ms 等指标属于架构规划阶段设定的设计目标，而非仓库实测数据；仓库侧的真实能力请以各模块的测试与基准结果为准。

2. 组件分解与职责

2.1 硬件接口层

WiFi Router Interface：负责与路由器建立并维护通信，包括配置路由器进行 CSI 提取、管理连接生命周期、处理路由器故障与重连，并支持 Atheros、Intel、ASUS 等多种路由器类型。

CSI Data Collector：从路由器提取并收集 CSI 数据，具体职责包括接收来自路由器的 UDP 数据流、解析 CSI 数据包格式、缓冲输入数据、同步多路数据流，以及处理丢包与数据损坏。

在仓库中，该层已有成熟的 Rust 落地：v2/crates/wifi-densepose-hardware/src下包含esp32/（含 tdm.rs、quic_transport.rs、secure_tdm.rs 三个传输/加密模块）、ieee80211bf/、aggregator/等子模块；src/bin/下则提供了aggregator.rs、mediatek-csi-sim.rs、qualcomm-csi-sim.rs、rtl8720f-sim.rs、vendor-rf-sim.rs等多个厂商 CSI 仿真器，用于在没有真实硬件时验证采集与解析链路。更完整的硬件接入细节可参考姊妹文档 plans/phase2-architecture/hardware-integration.md（包含 Atheros / Intel 5300 的 CSI 格式解析、UDP 流式协议与硬件抽象层设计）。

2.2 核心处理层

Signal Preprocessor：清洗与归一化原始 CSI，涵盖相位解卷绕（phase unwrapping）、幅度归一化、时域滤波、背景减除、降噪与环境标定；
Neural Network Pipeline：完成模态翻译（CSI → 空间表征）、特征提取、DensePose 估计、置信度评分与批处理优化。模型侧设计详见 plans/phase2-architecture/neural-network-architecture.md（双分支编码器、空间上采样网络、DensePose-RCNN 集成、知识蒸馏与多阶段训练策略）；
Pose Estimation Engine：编排端到端处理管线，协调组件间数据流、管理处理队列、优化资源分配、处理错误恢复并维持处理性能；
Multi-Person Tracker：跨时间跟踪多个个体，负责人员检测与 ID 分配、轨迹跟踪与预测、遮挡处理、轨迹生命周期管理（创建/更新/终止）与时序一致性约束。

仓库侧的对应实现集中在v2/crates/wifi-densepose-sensing-server/src，例如 pose.rs 定义了PersonDetection、PoseKeypoint等数据结构，实现了基于置信度、SNR 因子与噪声因子的关键点置信度计算，以及apply_temporal_smoothing（基于上一帧关键点做指数平滑，正是文档中"时序一致性约束"的实现）；engine_bridge.rs 与v2/crates/wifi-densepose-engine/src（lib.rs、mesh_guard.rs）则承担引擎编排与网格防护职责。

2.3 服务层

API Gateway：统一访问入口，负责请求路由、负载均衡、认证授权、限流、请求/响应转换与 API 版本管理；
REST API Service：提供 HTTP 访问能力，包括姿态数据访问（当前/历史）、系统控制（启动/停止/状态）、配置管理、分析报表与领域专属端点；
WebSocket Server：支持实时数据流，负责连接管理、订阅处理、实时姿态流推送、系统状态更新与告警通知；
External Integration Services：对接外部系统，包括 MQTT 发布（IoT 集成）、Webhook 事件通知、Restream 直播对接与第三方 API 集成。

2.4 管理层

Configuration Management：配置存储与检索、模板管理、校验与验证、动态配置更新、多环境差异化配置；
Monitoring and Diagnostics：性能指标采集、资源利用率监控、错误检测与上报、日志与审计轨迹、告警与通知。

仓库中服务层的实际实现与文档高度对应：v2/crates/wifi-densepose-sensing-server/src下既有 mqtt/ 目录（MQTT 连接、HA Discovery、发布器，详见第 5 节），也有matter/（Matter 协议）、semantic/（语义层）、training_api.rs（训练接口）等模块；cli.rs 中定义了 REST 端口（默认 8080）、WebSocket 端口（默认 8765）、UDP 端口（默认 5005）等参数。

3. 数据流架构：从原始 CSI 到客户端姿态数据

3.1 主数据流

3.2 各处理阶段规格

阶段	输入	处理	输出	关键参数
CSI 数据采集	路由器天线原始 WiFi 信号	数据包解析、缓冲、同步	结构化 CSI（幅度 + 相位）	采样率 10–30 Hz；约 ~100 KB/s/路由器
信号预处理	结构化 CSI	相位解卷绕、滤波、归一化	干净归一化的 CSI 特征	降噪、背景移除；以信噪比提升为质量指标
神经网络推理	预处理后的 CSI 特征	深度学习推理	空间表征与姿态估计	GPU 推理 <50ms；最优条件下 AP@50 目标 87.2%
多人跟踪	原始姿态估计	ID 分配、轨迹预测	带 ID 的连续跟踪姿态	遮挡处理、轨迹连续；容量最多 5 人
API 分发	跟踪后的姿态数据	格式化、序列化、流式推送	REST 响应 / WebSocket 消息 / MQTT 发布	API 响应生成 <10ms；支持 100+ 并发客户端

3.3 数据存储流

存储流将姿态数据拆分为短期缓存与时序数据库（时间序列库、聚合分析、报表引擎）三条通道，配置数据与系统指标则分别进入配置库与指标库，实现"运行态 / 历史态 / 观测态"三类数据的隔离管理。

4. 服务边界与内部接口契约

4.1 组件接口边界

硬件接口层：外部接口为 UDP socket（CSI 数据接收）与路由器配置接口；内部接口为预处理器的 CSI 数据队列与监控用的路由器状态事件；
核心处理层：外部接口为参数调优的配置 API 与性能监控的指标 API；内部接口为神经网络预处理数据队列、跟踪器姿态估计队列，以及系统状态更新的事件总线；
服务层：外部接口为 REST 端点、WebSocket 实时流、MQTT 主题与 Webhook 端点；内部接口为姿态数据访问、认证授权、限流与节流服务。

4.2 内部 API 契约

架构文档为组件间通信定义了三个核心 TypeScript 契约，是理解数据形状的关键：

CSI Collector → Signal Preprocessor

interface CSIData { timestamp: number; routerId: string; amplitude: Float32Array[][]; phase: Float32Array[][]; rssi: number; metadata: Record<string, any>; }

Neural Network → Pose Estimator

interface SpatialRepresentation { features: Float32Array[][][]; confidence: number; timestamp: number; processingTime: number; }

Pose Estimator → Multi-Person Tracker

interface PoseEstimate { keypoints: Array<{x: number, y: number, confidence: number}>; boundingBox: {x: number, y: number, width: number, height: number}; confidence: number; timestamp: number; }

值得注意：姿态数据统一采用归一化坐标（0–1）与置信度（0–1）的表示，这与仓库实现一致——pose.rs 中PoseKeypoint的关键点坐标与置信度即为归一化数值，且置信度通过clamp(0.1, 1.0)保证输出区间稳定。外部 API 契约的完整定义（REST 端点、WebSocket 消息、MQTT 主题、版本化策略与鉴权流程）见 plans/phase2-architecture/api-architecture.md。

4.3 事件驱动通信

系统通过事件总线解耦各层，按硬件事件、处理事件、API 事件与告警事件四类分发：

5. 部署架构：Docker 与 Kubernetes 双轨方案

5.1 Docker 容器架构

5.2 容器规格（设计文档定义）

核心容器

容器	基础镜像	资源	卷 / 网络	备注
CSI Collector	Python 3.9-slim	1 CPU / 1GB	配置卷；host 网络（UDP 接收）	重启策略 Always
Neural Network	NVIDIA CUDA 11.6 + Python 3.9	2 CPU / 4GB / 1 GPU	模型卷 + 共享数据卷；内部网络	重启策略 Always
Pose Estimation	Python 3.9-slim	2 CPU / 2GB	共享数据卷；内部网络	重启策略 Always
API Services	Python 3.9-slim	2 CPU / 2GB	配置卷；内外双网络	端口 8000（REST）、8001（WebSocket）

支撑容器

容器	基础镜像	资源	端口	说明
Database	TimescaleDB（PostgreSQL 扩展）	2 CPU / 4GB	—	持久化数据卷；内部网络
MQTT Broker	Eclipse Mosquitto	1 CPU / 1GB	1883（MQTT）、8883（MQTT over TLS）	内外双网络
Redis Cache	Redis Alpine	1 CPU / 2GB	—	持久化数据卷；内部网络
Monitoring	Prometheus + Grafana	1 CPU / 2GB	9090（Prometheus）、3000（Grafana）	持久化数据卷；内部网络

5.3 仓库中的实际部署实现

设计文档中的容器化思路在仓库里已有对应落地。docker/docker-compose.yml 定义了sensing-server（Rust）与python-sensing两个服务：

sensing-server（镜像ruvnet/wifi-densepose:latest）：REST API 绑定127.0.0.1:3000、WebSocket 绑定127.0.0.1:3001，UDP 端口5005暴露给 ESP32 节点；通过CSI_SOURCE环境变量控制数据源，可选auto（默认，自动探测 ESP32 UDP → 主机 WiFi，两者都不可用时以退出码 78 硬失败）、esp32（从 UDP 5005 接收真实 CSI）、wifi（Windows netsh 主机 RSSI/扫描数据）、simulated（显式生成合成 CSI 用于演示）；MODELS_DIR指定.rvf模型扫描目录；并配置了no-new-privileges、cap_drop: ALL与 2 CPU / 1G 的资源上限、kill -0 1健康检查；
python-sensing（镜像ruvnet/wifi-densepose:python）：WebSocket8765、UI8080，1 CPU / 512M 资源上限，健康检查探测 8765 端口连通性。

CLI 层与之一一对应：见 cli.rs 中--source（默认auto）、--udp-port（默认 5005）、--tick-ms（默认 100，即处理节拍）、SENSING_BIND_ADDR（默认127.0.0.1）等参数。镜像构建说明见 docker/Dockerfile.rust 与 docker/Dockerfile.python，入口脚本 docker/docker-entrypoint.sh 依据CSI_SOURCE决定启动方式。

5.4 Kubernetes 部署架构

K8s 形态下，核心服务（采集/推理/姿态/网关）以 Deployment 部署，有状态的数据组件（数据库、Redis）采用 StatefulSet，MQTT 用 Deployment，前端与流媒体服务器独立 Deployment；基础设施侧由 Ingress Controller 统一暴露入口，Prometheus Operator 负责指标采集，Cert Manager 管理 TLS 证书。

5.5 四类部署环境配置

环境	部署方式	基础设施	扩展性	数据持久化	监控
开发环境	Docker Compose	本地开发机	每容器单实例	本地卷	基础日志与指标
测试环境	Kubernetes（minikube/kind）	专用测试服务器	单实例 + 真实数据	测试数据集（临时）	完整监控栈用于性能测试
生产环境	Kubernetes	云厂商或本地集群	多实例 + 自动扩缩容	托管数据库或持久卷	全面监控、告警、日志；多可用区冗余高可用
边缘部署	Docker 或 K3s	带 GPU 的边缘设备	资源受限单实例	本地存储 + 云备份	轻量监控 + 云端上报；支持离线运行与同步

6. 可扩展性与性能架构

6.1 水平扩展策略

无状态的处理管线（采集→推理→跟踪→网关）通过负载均衡横向扩展，有状态的数据库与缓存以共享集群形式作为后端，从而在容量扩展的同时保持数据一致性。

6.2 垂直扩展考量

神经网络容器：GPU 显存是首要瓶颈；
数据库容器：时序数据的 I/O 性能与内存；
API 服务容器：并发请求处理依赖 CPU 核数；
CSI 采集容器：多路由器数据流依赖网络 I/O。

6.3 性能优化要点

批处理推理（神经网络推理合并批量）、多级缓存（API 响应）、时序查询的数据库索引优化、数据库与服务连接池复用、全链路非阻塞异步 I/O，以及按负载合理设定容器资源规格。

7. 安全架构

7.1 认证与授权

请求统一经 API Gateway 完成认证（JWT / API Key）与授权（角色 / 权限）两道校验，未通过即拒绝，通过后进入处理链路。

7.2 数据保护

传输中：外部通信全部使用 TLS 1.3；
静态存储：敏感数据落库加密；
处理中：内存保护与安全编码实践；
隐私：数据最小化与匿名化设计。

7.3 网络安全

API Gateway 作为带安全控制的唯一入口，内部服务不直接对外暴露（网络分段），配合严格的防火墙出入规则与限流机制抵御滥用与 DoS。仓库侧同样体现了最小权限原则，例如 docker/docker-compose.yml 中cap_drop: ALL与no-new-privileges: true，REST/WebSocket 默认仅绑定回环地址127.0.0.1，仅 UDP 5005 对 ESP32 开放；鉴权实现可参考v2/crates/wifi-densepose-sensing-server/src/bearer_auth.rs与 ws_ticket.rs（WebSocket 票据认证）。

8. 监控与可观测性架构

8.1 指标采集

8.2 日志架构

集中式日志（ELK 或同类方案），日志级别覆盖 ERROR / WARN / INFO / DEBUG / TRACE，采用带一致字段的 JSON 结构化日志，通过 Correlation ID 跨组件追踪请求，并按年龄分级存储、分层保留。

8.3 健康检查与探针

Liveness Probe：检测并重启故障容器；
Readiness Probe：阻止流量进入初始化中的容器；
Startup Probe：允许较长的启动初始化时间；
深健康检查：在基础连通性之上验证组件真实功能。

仓库侧的观测实现与文档一一对应：监控配置 monitoring/prometheus-config.yml 定义了wifi-densepose-app抓取任务（scrape_interval: 10s，按app=wifi-densepose标签过滤，从/metrics采集）、Prometheus 自身 / K8s 节点 / Node Exporter / cAdvisor / kube-state-metrics / CoreDNS / ingress / blackbox 等全栈抓取任务，并配置了 Alertmanager、remote_write远程长期存储、TSDB 15 天 / 50GB 保留策略与 WAL 压缩；告警规则见 monitoring/alerting-rules.yml，可视化面板见 monitoring/grafana-dashboard.json；日志侧 logging/fluentd-config.yml 提供集中日志采集，docker/otel-compose.yml 与 docker/otel-collector.yaml 提供 OpenTelemetry 观测链路，更多细节可参考 docs/observability.md。

9. 灾备与高可用

9.1 备份策略

数据库备份：定期快照与事务日志；
配置备份：版本化的配置仓库；
模型备份：神经网络模型的版本化存储；
恢复演练：定期验证备份恢复流程。

9.2 高可用架构

全局负载均衡将流量分发到多可用区，数据库节点间环形复制，任一可用区故障时其余区继续提供服务。

9.3 故障恢复流程

常见故障场景自动自愈；复杂故障遵循文档化的手动干预流程；资源受限时优雅降级；恢复全程保证数据一致性。仓库中v2/crates/wifi-densepose-engine/src/mesh_guard.rs即承担了网格级防护与容错职责。

10. 未来扩展性

10.1 扩展点

插件架构：模块化设计支持自定义扩展；
API 版本化：向后兼容的版本演进（API 文档中定义了 v1 稳定、v2 beta 的版本协商中间件与Sunset/Deprecation响应头）；
特性开关：运行时启停实验性功能；
配置模板：面向领域的配置包。

10.2 集成能力

标准协议（REST、WebSocket、MQTT、Webhook）之外，还提供自定义适配器框架、标准化数据导出格式与实时事件分发。仓库中 MQTT 集成已经深度落地：v2/crates/wifi-densepose-sensing-server/src/mqtt/下 config.rs 定义MqttConfig与PublishRates（对应RUVIEW_MQTT_*系列环境变量，见 cli.rs），discovery.rs 按{prefix}/wifi_densepose_{node_id}/{entity}/availability的格式发布 Home Assistant Discovery 主题，并通过 LWT（遗嘱消息）上报实体可用性；publisher.rs 负责在连接成功与每 30 秒重发布 retained discovery 配置，并发布 presence（存在性）等二进制实体状态（对应文档中system/status、pose/zone/+/occupancy等主题设计，注释标注依据 ADR-115）。完整的 Home Assistant / Matter 接入方案可进一步参考 docs/integration/home-assistant.md 与 ui/components 下的前端组件。

11. 结论

WiFi-DensePose 系统架构为"基于 WiFi 信号的隐私保护人体姿态估计"提供了一套健壮、可扩展、安全的基础框架：

实时性优先：端到端延迟设计目标 <100ms；
隐私内生：通过无摄像头感知从源头消除视频隐私风险；
可扩展：支持多并发用户与多节点网格；
高可靠：容错与多可用区高可用设计；
安全设计：传输、存储、处理三态保护与最小权限网络模型；
可扩展：模块化组件 + 标准接口（REST / WebSocket / MQTT / Webhook / Matter）。

这一架构既是实现路线图的蓝图，也为后续增强预留了清晰入口。建议读者结合 plans/phase2-architecture/api-architecture.md、plans/phase2-architecture/hardware-integration.md 与 plans/phase2-architecture/neural-network-architecture.md 三份配套设计文档，以及v2/crates下的 Rust 源码与 docker/docker-compose.yml 实际部署文件，逐层验证本文所述的设计与实现映射关系。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考