NEVO 项目技术架构文档

1. 项目概述

NEVO 是一款低延迟加密 VoIP 通讯系统，采用 C++20 构建跨平台客户端/服务端架构。项目支持桌面端（Windows / Linux / macOS）、移动端（Android / iOS）以及 Web 管理面板，提供高质量实时语音通讯能力，具备端到端加密、NAT 穿透和可扩展频道系统。

核心特性

项目目录结构

NEVO/
├── cmake/                  # CMake 辅助模块
├── proto/                  # Protobuf 协议定义
│   └── generated/          # 手写 C++ protobuf 替换头文件
├── 3rdparty/               # 嵌入式依赖 (miniaudio, spdlog stub)
├── src/
│   ├── core/               # 共享核心库 (音频/协议/权限/通用)
│   ├── network/            # 网络库 (TCP/UDP/加密/NAT/SSL)
│   ├── client/             # 客户端应用
│   ├── server/             # 服务端应用
│   └── ui/                 # 客户端 UI (Qt 6)
├── mobile/
│   ├── android/            # Android 客户端
│   └── ios/                # iOS 客户端
├── web/                    # Web 管理面板
├── website/                # Cloudflare Pages 网站
├── tests/                  # 单元测试 & 集成测试 (GTest)
├── docs/                   # 项目文档
├── scripts/                # 辅助脚本
├── installer/              # 安装包 (NSIS)
├── bgm/                    # 背景音乐文件
├── Dockerfile              # Docker 多阶段构建
├── docker-compose.yml      # Docker 编排配置
└── CMakeLists.txt          # 顶层构建配置

2. 技术架构

2.1 整体架构图

2.2 技术栈总览

2.3 构建系统

项目使用 CMake 3.21+ 统一管理所有 C++ 模块的构建。整体采用模块化设计，每个模块可独立编译并自动检测依赖，依赖缺失时优雅降级为 stub 实现。

条件编译标志

构建命令

cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel

cmake -B build -DBUILD_TESTING=ON
cmake --build build --parallel
ctest --test-dir build --output-on-failure

cmake -B build -DBUILD_TESTING=ON -DENABLE_COVERAGE=ON

2.4 通信协议

协议层基于 Protocol Buffers proto3 语法定义，包含控制协议和语音协议两大类别。

关键协议结构

enum ResultCode {
    OK = 0;  ERROR_AUTH_FAILED = 2;  ERROR_PERMISSION_DENIED = 3;
    ERROR_CHANNEL_NOT_FOUND = 4;  ERROR_TIMEOUT = 8;  ERROR_CRYPTO_ERROR = 10;
}
message VoicePacketHeader {
    uint32 sequence_number = 1;   uint64 sender_id = 2;
    uint64 channel_id = 3;        uint32 timestamp = 4;
    bool   last_frame = 5;        uint32 fec_payload_size = 6;
    bytes  nonce = 7;             bytes  auth_tag = 8;
    bool   tcp_tunnel = 9;
}

3. 功能模块说明

3.1 核心模块 (nevo_core)

核心模块是所有上层模块的公共依赖，提供音频处理、协议编解码、权限系统和通用工具。

音频处理流水线

3.2 网络模块 (nevo_network)

网络库提供异步网络通信基础设施，核心设计基于 Boost.Asio 协程实现高性能 I/O。

3.3 客户端模块 (nevo_client)

桌面客户端采用 Python (PyQt5) + C++ 核心库 的混合架构。

src/client/
├── include/nevo/client/
│   ├── ClientCore.h          # 客户端核心接口
│   └── NetworkManager.h      # 网络管理器接口
├── src/
│   ├── ClientCore.cpp        # 客户端状态机实现
│   ├── NetworkManager.cpp    # 网络管理器实现
│   └── AudioInput/Output     # 音频 I/O
├── gui_python/
│   └── main.py               # Python 桌面 GUI 入口
└── CMakeLists.txt

3.4 服务端模块 (nevo_server)

服务端是系统的核心中枢，负责用户认证、频道管理、音频路由和状态持久化。

启动配置

# CLI 方式
./nevo_server --tcp-port 24430 --udp-port 24431 --db server.db --threads 4 --log-level info

# JSON 配置文件 (server_config.json)
{
    "tcp_port": 24430, "udp_port": 24431, "db_path": "server.db",
    "threads": 4, "log_level": "info", "server_name": "NEVO Server",
    "max_users": 100, "welcome_message": "Welcome to the NEVO server!"
}

# Docker Compose 部署
docker compose up -d

3.5 UI 模块 (nevo_ui)

桌面客户端 UI 基于 Qt 6 Widgets 实现。

3.6 移动端

移动端为原生实现，分别对应 Android (Kotlin) 和 iOS (Swift)，通过 JNI 和 C Interop 桥接 C++ 核心逻辑。

mobile/android/app/src/main/java/com/nevo/voip/
├── core/
│   ├── protocol/
│   │   ├── MessageType.kt         # 消息类型枚举
│   │   └── ProtocolSerializer.kt  # 二进制序列化器
│   └── update/
│       └── UpdateManager.kt       # 应用更新管理器

mobile/ios/NevoClient/
├── Protocol/
│   └── WireFormat.swift           # 网络数据包格式定义
└── Package.swift                  # Swift Package Manager 配置

3.7 Web 管理面板

Web 管理面板用于远程服务器监控和管理，采用轻量级前后端分离架构。

4. 页面结构设计

Web 管理面板采用 侧边栏 + 主内容区 的经典管理后台布局。

Web 管理面板导航结构

NEVO 管理面板
├── 📊 仪表盘 (Dashboard)
│   ├── 服务器运行状态概览
│   ├── 在线用户数 / 活跃频道数
│   └── 实时带宽/延迟图表
├── 👥 会话管理 (Sessions)
│   ├── 当前连接用户列表
│   ├── 用户踢出/静音/封禁操作
│   └── 会话详情查看
├── 📡 频道 (Channels)
│   ├── 层次化频道树
│   ├── 频道创建/编辑/删除
│   └── 权限设置
├── 📈 性能监控 (Metrics)
│   ├── CPU/内存/网络占用图表
│   ├── 音频包延迟分布
│   └── 丢包率统计
├── ⚙️ 系统配置 (Config)
│   ├── 服务器参数配置
│   ├── 日志级别调整
│   └── 配置导入/导出
└── 🖥️ 服务器控制 (Server)
    ├── 启动/停止/重启
    ├── 运行日志查看
    └── 健康检查状态

桌面客户端界面结构

NEVO 桌面客户端 (Qt 6)
├── MainWindow
│   ├── QDockWidget: 频道面板 (ChannelTreeModel)
│   ├── QDockWidget: 用户面板 (UserListModel)
│   ├── ConnectionBar: 连接状态 + 设置
│   └── 中央内容区

5. 交互流程

客户端连接 → 语音通讯完整流程

连接生命周期状态机

DISCONNECTED
    │ TCP 连接成功
    ▼
CONNECTING
    │ TLS 握手完成
    ▼
AUTHENTICATING
    │ 凭证验证通过
    ▼
ONLINE ←──────────────── 空闲/活跃状态
    ││
    │├─ 加入频道 → IN_CHANNEL (开始语音数据流)
    ││
    │└─ NAT 穿透 → UDP 直连 / TCP 隧道 → 语音收发
    │
    └── 断线/超时 → DISCONNECTED (释放资源)

关键场景流程

6. 响应式设计规范

Web 管理面板 — 断点策略

响应式设计要点

• CSS Flexbox + Grid：主布局使用 Flexbox 实现弹性布局
• 移动端菜单：通过 #menu-open / #menu-close 按钮切换侧边栏显示
• 数据表格：小屏幕下使用 overflow-x: auto 水平滚动
• 图表组件：SVG 自适应容器宽度，viewBox 保持比例
• 触碰目标：移动端按钮最小 44×44px，满足 WCAG 2.1 AA
• 辅助功能：提供 .skip-link 键盘跳过导航、aria-* 属性标注

桌面客户端 — 跨平台适配

7. 性能优化策略

音频流水线优化

网络层优化

服务端优化

8. 浏览器兼容性要求

Web 管理面板 — 目标浏览器

依赖的 Web 平台特性

• CSS Grid + Flexbox — 所有目标浏览器原生支持
• CSS Custom Properties (var()) — 主题变量
• SVG inline — 导航图标内嵌 SVG
• Fetch API — 与服务端 API 通信
• Google Fonts — Inter + JetBrains Mono 字体 (有回退字体栈)
• 无外部 JS 框架依赖 — 纯 Vanilla JS，降低兼容性风险

桌面客户端 — 操作系统兼容性

移动端兼容性

9. 已知问题与解决方案

常见问题排查

10. 开发规范与指南

代码规范

• C++ 命名：类名 PascalCase (AudioEngine)，文件名 PascalCase (AudioEngine.h)，命名空间 snake_case (nevo::audio)
• 当前测试框架为 Google Test (GTest v1.14.0)，测试目录 tests/ 包含：
  • Result<T> 错误处理单元测试
  • Channel 频道管理单元测试
  • Permission 权限系统单元测试
  • Opus 编解码器集成测试
  • JitterBuffer 去抖缓冲测试
  • AudioMixer 多路混音测试
  • AudioMemoryPool 内存池测试
  • TcpConnection 帧协议测试
  • VoiceCrypto 加解密测试
  • NatTraversal STUN 协议测试
  • Server 服务端集成测试

  CMake 依赖管理策略

  项目遵循 FindPackage → vcpkg CONFIG → stub 降级 的三级依赖查找策略：

  1. FindPackage：优先使用系统已安装的库
  2. vcpkg / pkg-config：使用包管理器提供的版本
  3. FetchContent：自动下载 (仅限 GTest 等测试依赖)
  4. Stub 降级：全部缺失时，编译不含该功能的精简版本

  ---

  📌 文档维护说明

  本文档应与项目代码同步更新。每当以下内容发生变化时，需更新本文档中对应章节：
  1. 新增/删除功能模块 → 更新第3章
  2. 技术栈升级 (库版本变更) → 更新第2.2节
  3. Web 页面重构 → 更新第4章
  4. 新增已知问题或问题修复 → 更新第9章
  5. 构建/部署流程变更 → 更新第2.3节和第10章