1. 项目基础信息

1.1 项目名称

UCC Remote（可执行文件：UCCRemote.exe）

1.2 项目简介

UCC Remote 是一款面向工业/企业场景的 点对点（P2P）远程桌面 软件，采用 TeamViewer / ToDesk 风格的 统一客户端 设计：同一安装包既可作为被控端（Host），也可作为控制端（Viewer），运行时通过界面开关切换，无需分别安装两个程序。

项目基于 Qt 5.15.2 + MinGW 8.1 64-bit 构建，使用 qmake 工程管理，支持中文界面（uccremote_zh_CN.qm），具备屏幕共享、远程键鼠控制、剪贴板同步、断点续传文件传输等企业级远程协作能力。

1.3 核心功能

1.4 解决的核心问题

• 复杂 NAT 穿透：通过 STUN 打洞、KCP/UDT 双协议、自建 UDP/WebSocket 中继及可选 coturn TURN，覆盖 LAN/WAN 多种网络环境。
• 低延迟高画质：GPU 零拷贝 DXGI→NVENC 管线、脏矩形增量传输、双通道 KCP（控制/视频分离）、解码线程 offload。
• 部署简便：单文件夹部署，LAN 信标自动发现信令服务器，无需每台机器单独配置 IP。
• 工业稳定性：信令心跳重连、会话自动重连、DXGI 访问丢失恢复、传输层 rehome、单实例锁。
• 安全合规：端到端 AES 加密、ECDH 密钥交换、入站连接审批/无人值守模式、跨账户 CONNECT 拒绝。

2. 环境与安装

2.1 依赖环境要求

2.2 本地编译步骤

方式一：一键构建（推荐）

cd d:\UCC_QT\UCCRemote
scripts\build_and_deploy.bat [输出目录]

# 默认输出：C:\uccremote_out
# 自定义输出：scripts\build_and_deploy.bat C:\newout

该脚本自动完成：libyuv 静态编译 → FFmpeg 检测 → 翻译更新（lupdate/lrelease）→ UCCRemote Release 编译 → UCCSignaling/UCCRelay/UCCWsRelay 编译 → TLS 证书生成 → windeployqt 打包 → 部署脚本复制。

方式二：Qt Creator 手动构建

# 1. 打开 UCCRemote.pro
# 2. 配置 Kit：Desktop Qt 5.15.2 MinGW 64-bit
# 3. Release 模式构建
# 4. Release 构建会自动复制 exe 到 C:/newout（需先运行过一次 build_and_deploy.bat）

cd build
qmake ..\UCCRemote.pro -spec win32-g++ "CONFIG+=release" ^
  "FFMPEG_DIR=..\third_party\ffmpeg-static" ^
  "OPENSSL_DIR=..\third_party\openssl-mingw64"
mingw32-make -j4

可选：单独构建第三方库

scripts\build_libyuv_static.bat      # libyuv 静态库
scripts\build_ffmpeg_static.bat      # FFmpeg 静态库（H.264）
scripts\build_libudt_mingw.bat       # libudt（UDT 传输）
scripts\build_all.bat                # 全部构建
scripts\gen_certs.bat                # 生成 TLS 证书

2.3 部署/安装步骤

部署目录结构

C:\newout\
├── UCCRemote.exe              # 统一客户端
├── start_signaling.bat        # 信令+中继启动脚本
├── Qt5*.dll                   # Qt 运行时
├── libcrypto-3-x64.dll        # OpenSSL
├── libssl-3-x64.dll
├── libgcc_s_seh-1.dll         # MinGW 运行时
├── libstdc++-6.dll
├── libwinpthread-1.dll
├── certs\                     # TLS 证书
│   ├── ca.crt
│   ├── signaling.crt
│   └── signaling.key
├── translations\
│   └── uccremote_zh_CN.qm     # 中文界面
├── server\
│   ├── UCCSignaling.exe       # 信令服务器 (21080/TCP)
│   ├── UCCRelay.exe           # UDP 中继 (21081/UDP)
│   ├── UCCWsRelay.exe         # WebSocket 中继 (21082)
│   └── certs\
└── *.ps1                      # LAN 发现/信标脚本

同机测试

start_signaling.bat
UCCRemote.exe

2.4 TLS 证书配置

开发/测试环境由 scripts\gen_certs.bat 自动生成自签名证书到 certs/ 目录。生产环境应替换为正式 CA 签发的证书：

• certs/ca.crt — CA 根证书（客户端信任）
• certs/signaling.crt + signaling.key — 信令服务器证书

客户端启动时调用 TlsConfig::ensureDefaultCerts() 确保证书可用。

3. 使用指南

3.1 快速开始

1. 在一台 PC 运行 start_signaling.bat 启动信令与中继服务。
2. 被控 PC：启动 UCCRemote.exe → 勾选 「允许远程控制」 → 记录设备码和临时密码。
3. 控制 PC：启动 UCCRemote.exe → 输入对方设备码和密码 → 点击 「连接」。
4. 连接成功后自动打开远程桌面窗口，可进行键鼠操作、文件传输、剪贴板同步。

3.2 被控端（Host）操作

3.3 控制端（Viewer）操作

3.4 设置页面说明

配置存储于 INI 格式用户设置文件（AppRuntime::userSettings()），默认数据目录由 AppRuntime::defaultUnifiedDataDir() 决定，可通过 --datadir= 覆盖。

3.5 命令行参数

3.6 连接 URI 格式

uccremote://988008226?pwd=yhjm2mxx

解析器：ConnectionUriParser（src/core/connectionuri.cpp）。支持从剪贴板粘贴或 QR 码扫描导入。

4. 技术架构

4.1 整体架构图

┌─────────────────────────────────────────────────────────────────┐
│                        UCCRemote.exe (统一客户端)                  │
├──────────────┬──────────────────────────────────────────────────┤
│   UI 层       │ MainWindow / RemoteWindow / SystemTray / Dialogs │
├──────────────┼──────────────────────────────────────────────────┤
│   会话层      │ RemoteSession / SessionIoPump / VideoEncodeWorker │
│              │ VideoDecodeWorker / ClipboardSync / FileTransfer  │
├──────────────┼──────────────────────────────────────────────────┤
│   连接层      │ ConnectionManager / SignalingRegistrar / P2pConnector│
├──────────────┼──────────────────────────────────────────────────┤
│   传输层      │ SecureChannel → KCP / TCP / UDT / Relay / WS-Relay│
│              │ DualChannelTransport / TcpDualChannelTransport     │
├──────────────┼──────────────────────────────────────────────────┤
│   媒体层      │ DXGI/GDI Capture → FFmpeg Encoder/Decoder          │
│              │ D3D11 GPU Context / AdaptiveQoS / libyuv           │
├──────────────┼──────────────────────────────────────────────────┤
│   安全层      │ AES-256-HMAC / X25519 ECDH / SessionAuth / TLS     │
└──────────────┴──────────────────────────────────────────────────┘
                              │
                    TLS 信令 (21080) / UDP 中继 (21081)
                              │
┌─────────────────────────────┴───────────────────────────────────┐
│  UCCSignaling.exe  │  UCCRelay.exe  │  UCCWsRelay.exe  │ coturn │
└─────────────────────────────────────────────────────────────────┘

4.2 连接建立流程

4.3 代码目录结构

UCCRemote/
├── main.cpp                    # 程序入口（GUI + 测试模式分发）
├── mainwindow.cpp/h            # 主窗口（三页导航：首页/设备/设置）
├── UCCRemote.pro               # qmake 主工程文件
├── uccremote.qrc               # Qt 资源（图标等）
├── translations/
│   └── uccremote_zh_CN.ts/qm   # 中文翻译
├── certs/                      # TLS 证书
├── images/                     # 应用图标
├── docs/                       # 文档
├── scripts/                    # 构建/部署脚本
│   ├── build_and_deploy.bat
│   ├── gen_certs.bat
│   └── deploy/                 # 部署辅助脚本
├── server/                     # 服务端子工程
│   ├── UCCSignaling.pro        # 信令服务器
│   ├── UCCRelay.pro            # UDP 中继
│   ├── UCCWsRelay.pro          # WebSocket 中继
│   └── signaling_server.cpp
├── third_party/                # 第三方库
│   ├── kcp/                    # KCP 协议 (ikcp.c)
│   ├── qrcodegen/              # QR 码生成
│   ├── ffmpeg-static/          # FFmpeg 静态库
│   ├── libyuv-static/          # libyuv 静态库
│   ├── openssl-mingw64/        # OpenSSL
│   └── libudt/                 # UDT 库（可选）
└── src/                        # 核心源码
    ├── core/                   # 核心配置与协议
    ├── crypto/                 # 加密模块
    ├── net/                    # 网络基础（TLS, FEC）
    ├── p2p/                    # P2P 连接器
    ├── signaling/              # 信令客户端
    ├── transport/              # 传输层抽象
    ├── relay/                  # 中继协议
    ├── turn/                   # coturn 客户端
    ├── capture/                # 屏幕采集
    ├── codec/                  # 音视频编解码
    ├── session/                # 远程会话
    ├── input/                  # 输入注入
    ├── clipboard/              # 剪贴板同步
    ├── file/                   # 文件传输
    ├── ui/                     # UI 组件
    ├── util/                   # 工具类
    └── tools/                  # 测试/验证工具

4.4 核心模块说明

core/ — 核心基础设施

signaling/ — 信令子系统

transport/ — 传输层

p2p/ — P2P 连接

capture/ — 屏幕采集

codec/ — 编解码

session/ — 远程会话

ui/ — 用户界面

其他模块

4.5 通信协议

应用层协议（UCC1 帧格式）

所有会话消息使用 packMessage(MessageType, payload) 封装，前缀魔数 UCC1，支持 28 种消息类型：

信令协议（文本行）

格式：COMMAND arg1 arg2 ...\n，主要命令：

REGISTER <deviceId> <role> <deviceName>
LOGIN <username> <password>
CONNECT <peerDeviceId> <mode> [<sessionPassword>]
PEER_INFO <deviceId> <publicHost> <publicPort> <udpPort> <path> ...
PUNCH <peerHost> <peerPort>
RELAY_INFO <relayHost> <relayPort> <token>
PING / PONG

4.6 传输层级联策略

4.7 服务端组件

4.8 安全机制

• 信令 TLS：SignalingLink 使用 OpenSSL TLS 1.2+ 加密信令通道
• 媒体 AES-256-HMAC：SecureChannel 对所有会话数据 AES-256-CBC + HMAC-SHA256 认证
• ECDH 密钥交换：X25519 + HKDF 派生会话密钥，替代共享密码（SessionKeyExchange）
• 会话认证：HMAC-SHA256 sessionAuthTag 防止中间人（SessionAuth）
• 设备码 + 密码：9 位设备 ID + 临时会话密码双重验证
• 入站审批：密码不匹配时需人工确认，超时自动拒绝
• 跨账户保护：无会话密码时跨账户 CONNECT 被拒绝
• 单实例：SingleInstance 防止同一角色多开
• 防火墙：--ensure-firewall-rule 自动添加 Windows 防火墙入站规则

5. 附录

5.1 端口一览

5.2 第三方依赖

5.3 功能路线图（已实现）

5.4 生产部署检查清单

• 修改默认密码（AppConfig::defaultPassphrase()）
• 替换 certs/ 为正式 CA 证书
• 在 VPS 部署 UCCSignaling + UCCRelay
• 开放 TCP 21080、UDP 21081、UDP 3478（如用 coturn）
• 被控端安装 NVENC 版 FFmpeg 以启用硬件编码
• 运行 E2E 验证：verify_e2e_p2p.bat

5.5 线程模型

5.6 相关文档

• docs/INDUSTRIAL.md — 工业部署详细说明
• docs/REFERENCE_ANALYSIS.md — 参考项目分析
• docs/coturn.example.conf — coturn 配置示例
• scripts/deploy/README.txt — 部署快速指南
• README.md — 项目简要说明