# YL-Connect

**Repository Path**: chayunyolong/YL-Connect

## Basic Information

- **Project Name**: YL-Connect
- **Description**: 游龙远程协作系统（YL-Connect）
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-01
- **Last Updated**: 2026-04-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 游龙远程协作系统（YL-Connect）
> 《游龙远程协作系统（YL-Connect）系统设计说明书》


## 目录

- [一、项目概述](#一项目概述)
  - [1.1 项目背景](#11-项目背景)
  - [1.2 建设目标](#12-建设目标)
  - [1.3 目标用户与使用场景](#13-目标用户与使用场景)
- [二、需求分析](#二需求分析)
  - [2.1 功能需求](#21-功能需求)
  - [2.2 非功能需求](#22-非功能需求)
- [三、总体架构设计](#三总体架构设计)
- [四、详细模块设计（Rust 维度）](#四详细模块设计rust-维度)
- [五、主要流程设计](#五主要流程设计)
- [六、数据与存储设计](#六数据与存储设计)
- [七、安全设计](#七安全设计)
- [八、性能与资源控制](#八性能与资源控制)
- [九、扩展与论文可写创新点](#九扩展与论文可写创新点)
- [十、里程碑与后续工作](#十里程碑与后续工作)
- [十一、实施路线与迭代计划](#十一实施路线与迭代计划)
- [十二、分发与开源配置说明](#十二分发与开源配置说明)

------

# 一、项目概述

> 轻量、自主可控的远程协作系统，聚焦 2 核 2GB 服务器和小团队内部使用场景。

## 1.1 项目背景

随着远程办公、小团队协作的普及，传统远程控制软件（如 Radmin、TeamViewer 等）往往存在如下问题：

- 数据经第三方服务器中转，存在隐私与合规风险；
- 商业授权费用高，不适合学生团队、小工作室；
- 无法根据自身需求进行功能定制与二次开发。

为此，本项目设计并实现一个**基于 Rust 的轻量级远程协作系统 YL-Connect**，目标是为小规模内部团队提供：

- 远程桌面控制
- 文件传输
- 文本聊天与链接共享
- 私有化部署、全链路自控

系统部署于一台**2 核 CPU、2GB 内存的阿里云服务器**上即可稳定运行，适合软著登记、学术论文撰写及后续产品化上架。

## 1.2 建设目标

- 自主可控：所有核心模块（信令、数据通道、屏幕采集、输入模拟、文件传输）自主实现，避免对大型现成远控开源项目的依赖，提升原创性。
- 轻量高效：针对 2C2G 服务器优化，控制 CPU 与内存占用。
- 易用扩展：模块化设计，便于后续增加用户体系、权限控制、记录审计等高级功能。
- 可论文化：协议设计、性能优化、架构设计均可提炼为论文中的技术亮点。

## 1.3 目标用户与使用场景

- 小型开发团队、实验室内部使用；
- 远程维护自己家中/机房的开发环境；
- 内部文件、链接、调试信息的低成本安全共享。

------

# 二、需求分析

## 2.1 功能需求

### 2.1.1 设备注册与管理

- 客户端首次启动时向服务器注册，获得唯一设备 ID（如 `YL-0001`）。
- 服务器维护在线设备列表：设备 ID、设备名、操作系统、在线状态、最后心跳时间等。
- 控制端可以查询在线设备并发起连接。

### 2.1.2 远程桌面控制

- 支持远程查看被控端屏幕。
- 支持鼠标移动、点击、滚轮及键盘输入的远程注入。
- 支持设置帧率（如 5–15 FPS）与画质（低/中/高）的参数，用于在 2C2G 配置下做性能与清晰度权衡。

### 2.1.3 文件传输

- 支持控制端向被控端发送单个文件。
- 支持被控端向控制端返回文件。
- 支持基本的传输进度显示与取消操作。
- 传输过程提供简单的完整性校验（如 SHA-256 摘要）。

### 2.1.4 文本消息与链接共享

- 支持会话内文本聊天（如说明操作步骤）。
- 支持发送 URL 链接，控制端一键打开浏览器访问。

### 2.1.5 会话管理

- 支持创建远程控制会话、关闭会话。
- 支持多会话并发（服务器限制最大并发数，防止资源耗尽）。
- 支持简单的访问密码或 PIN 验证。

## 2.2 非功能需求

- **性能**：
  - 在 2C2G 服务器上，支持至少 3–5 个同时在线控制会话（非高帧率）。
  - 在普通宽带环境下（上/下行 ≥ 10Mbps），远程控制具有可接受的延迟（<300ms）。
- **安全性**：
  - 整体通信使用 TLS 或基于 Noise/自定义密钥的加密通道。
  - 支持基于 Token 的客户端认证。
- **可移植性**：
  - 服务器端：Linux (x86_64)
  - 客户端：优先支持 Windows（后续可扩展 Linux / macOS）。
- **可维护性**：
  - Rust 语言 + 模块化设计 + 清晰的 crate 划分。
  - 使用异步运行时（Tokio）统一处理网络 IO。

------

# 三、总体架构设计

## 3.1 系统总体结构

系统由三类主要组件构成：

1. **服务器端（Core Server）**
   - 设备注册与管理模块
   - 信令服务器模块（WebSocket / TCP）
   - 会话协商模块
   - 中继转发模块（当 P2P 不可用时）
   - 文件中转/下载服务模块
2. **客户端被控端（Agent）**
   - 设备注册与心跳模块
   - 屏幕采集与编码模块
   - 输入事件执行模块（键鼠模拟）
   - 文件接收与发送模块
   - 本地配置管理模块
3. **客户端控制端（Controller）**
   - 设备列表与连接管理界面
   - 远程桌面显示模块
   - 输入事件采集模块
   - 文件传输界面与控制模块
   - 会话聊天界面

## 3.2 部署架构

- 服务器端为一个 Rust 可执行程序，运行在阿里云 ECS 上（如 Ubuntu 22.04）。
- 使用 systemd 管理服务启动与重启。
- 对外暴露一个控制端口（如 TCP 443 / 8443），客户端通过该端口建立长连接（WebSocket/TCP）。

------

# 四、详细模块设计（Rust 维度）

建议采用 **Rust Workspace** 管理多个 crate：

- `ylc-server`：服务器端二进制
- `ylc-agent`：被控端二进制
- `ylc-controller`：控制端二进制
- `ylc-proto`：公共协议与数据结构（message 定义）
- `ylc-core`：公共工具库（加密、日志、配置）

下面按逻辑模块描述。

## 4.1 公共协议模块（ylc-proto）

### 4.1.1 基础数据结构

使用 `serde` 进行序列化/反序列化，统一采用 JSON 或者轻量二进制（如 bincode）格式。

示例消息包：

```json
{
  "type": "register",
  "payload": {
    "device_id": "YL-0001",
    "device_name": "Ni-PC",
    "os": "Windows 11",
    "role": "agent"
  }
}
```

统一定义几类消息：

- `Register`：客户端注册
- `Heartbeat`：心跳
- `DeviceListRequest` / `DeviceListResponse`
- `ConnectRequest` / `ConnectResponse`
- `RemoteControlFrame`：屏幕帧数据
- `InputEvent`：键鼠事件
- `FileMeta`：文件元数据
- `FileChunk`：文件内容块
- `ChatMessage`：会话聊天消息
- `Error`：错误通告

### 4.1.2 传输信道

- 信令与控制：文本/小二进制消息，通过 WebSocket/TCP 长连接承载。
- 大数据（屏幕帧、文件块）：
  - 可复用同一连接，使用帧头标识类型与长度。
  - 或单独建立数据通道（简化起见，设计上预留，首版可复用）。

## 4.2 服务器端模块（ylc-server）

### 4.2.1 连接管理模块

- 使用 `tokio` 管理异步连接。
- 每个客户端连入时分配一个 `ClientHandle`，包括：
  - device_id
  - role（agent/controller）
  - send_channel（用于向客户端发送消息）
- 在内存中维护 `HashMap<device_id, ClientHandle>`，实现设备查找与消息路由。

### 4.2.2 设备注册与心跳模块

- 处理 `Register` 消息：记录或更新设备信息。
- 处理 `Heartbeat` 消息：更新最后在线时间。
- 定期清理长时间无心跳的设备（如超过 60 秒）。

### 4.2.3 会话协商模块

- 控制端发送 `ConnectRequest`（目标 device_id）。
- 服务器检查目标被控端是否在线：
  - 若在线：向 agent 发送会话请求，等待其确认（或自动允许）。
  - 若拒绝/离线：返回失败。
- 协商完成后，服务器在内部维护一个 `Session` 对象，将控制端与被控端的连接绑定。

### 4.2.4 数据转发模块（中继）

- 对于远程桌面数据和输入事件，服务器仅做中继转发：
  - 控制端 → 服务器 → 被控端
  - 被控端 → 服务器 → 控制端
- 通过逻辑上的 `SessionId` 将两端关联，转发时根据 `session_id` 查找目标连接。

> **说明**：文档中可以写上预留 P2P 打洞流程作为“后续扩展与创新点”，但此版以中继为主，简化实现，更适合 2C2G 环境。

### 4.2.5 文件传输模块

两种模式可选（设计上都写，实际先实现简单版）：

1. **直接透传模式**：
   - 文件数据块通过服务器在控制端与被控端之间透传。
   - 服务器不落盘，仅按顺序转发。
2. **中转存储模式（扩展）**：
   - 被控端将文件分块上传到服务器临时存储（如 `/var/ylc/tmp/`）。
   - 控制端再从服务器下载。
   - 适合网络不对称或需要断点续传时使用。

### 4.2.6 配置与日志模块

- 使用 `toml` 格式配置文件：
  - 监听端口
  - 最大会话数
  - 日志级别
- 日志使用 `tracing` 或 `log + env_logger`，输出到文件与终端，方便问题排查。

## 4.3 客户端被控端模块（ylc-agent）

### 4.3.1 设备信息与配置管理

- 首次启动生成一个 `device_id`（如 UUID + 前缀）。
- 将配置保存在本地文件（如 `config.toml`），包括：
  - device_id、device_name
  - 服务器地址
  - 自动启动选项等。

### 4.3.2 连接与心跳模块

- 使用 `tokio` + `tokio-tungstenite`（如使用 WebSocket）连接服务器。
- 定时发送心跳（如每隔 10 秒发送 `Heartbeat`）。

### 4.3.3 屏幕采集模块

- 使用平台相关库采集屏幕：
  - Windows 可使用相关截图 crate（如 `scrap` 等），设计书中可描述为“基于 Win32 GDI 或 DXGI 的屏幕捕获实现”。
- 将采集到的图像进行缩放与 JPEG 压缩，得到图像帧（`Vec<u8>`）。

### 4.3.4 屏幕编码与发送模块

- 将图像帧封装为 `RemoteControlFrame` 消息，包含：
  - session_id
  - 序号
  - 时间戳
  - 图像数据（可 Base64 后再传，或走二进制帧）
- 按设定的帧率（如 10 FPS）周期发送。

### 4.3.5 输入事件执行模块

- 接收 `InputEvent` 消息。
- 在本地调用系统 API 模拟：
  - 鼠标移动、点击、滚轮
  - 键盘按键（按下/抬起）
- Windows 下可通过 Win32 API 实现，论文中可以重点展开“输入注入模块设计”。

### 4.3.6 文件收发模块

- 接收控制端发送的文件（流式接收，落本地）。
- 支持从本地选择文件，分块上传给对端。

## 4.4 客户端控制端模块（ylc-controller）

### 4.4.1 设备列表与连接管理

- 从服务器请求 `DeviceList`。
- UI 显示设备在线状态。
- 支持点击某个设备发起连接请求。

### 4.4.2 远程桌面显示模块

- 接收 `RemoteControlFrame` 图像帧，按序解码为图像并显示。
- 负责简单的帧率控制和缓存丢弃策略（例如新帧覆盖旧帧，以降低延迟）。

### 4.4.3 输入事件采集模块

- 监听本地窗口的鼠标与键盘输入事件。
- 将坐标按远程屏幕分辨率缩放后封装为 `InputEvent` 消息发送。

### 4.4.4 文件传输界面模块

- 支持从本地选择文件，通过协议发送给被控端。
- 显示传输进度。
- 当对方上传文件时提供保存位置选择。

### 4.4.5 会话聊天模块

- 支持在控制窗口中输入文字，发送 `ChatMessage`。
- 接收来自对方的消息并显示。

------

# 五、主要流程设计

## 5.1 客户端注册与心跳流程（顺序简述）

1. Agent/Controller 启动 → 读取本地配置或生成新 device_id。
2. 与服务器建立 WebSocket/TCP 连接。
3. 发送 `Register` 消息（携带 device_id、device_name、role 等）。
4. 服务器记录设备信息，返回 `RegisterAck`。
5. 客户端定时发送 `Heartbeat`。
6. 服务器更新在线状态，定期清理失联设备。

## 5.2 会话建立流程（控制端连接被控端）

1. 控制端从服务器获取设备列表。
2. 用户选择目标设备，发送 `ConnectRequest(device_id)`。
3. 服务器检查目标被控端在线情况：
   - 若在线：向被控端发送 `IncomingSession` 通知。
   - 若不在线：返回错误。
4. 被控端根据策略（自动/手动确认）回复 `SessionAccept/Reject`。
5. 服务器创建 `Session` 实例，将双方连接与 session_id 绑定。
6. 客户端进入远程控制模式，开始屏幕帧与输入事件的交互。

## 5.3 远程控制数据流

- 被控端：
  - 循环采集屏幕 → 编码 → 发送 `RemoteControlFrame(session_id, frame)`。
- 控制端：
  - 接收 Frame → 解码 → 渲染。
  - 捕获鼠标键盘事件 → 封装 `InputEvent(session_id, ...)` 发送。
- 服务器：
  - 根据 session_id，将消息在两端转发。

## 5.4 文件传输流程（直接透传模式）

1. 控制端发起文件发送请求，发送 `FileMeta`（文件名、大小、摘要）。
2. 被控端确认接收并返回 `FileAccept`。
3. 控制端将文件分块读取（如每块 64KB），逐块封装 `FileChunk` 并发送。
4. 被控端按序写入本地文件，完成后校验摘要并返回 `FileComplete`。
5. 若传输中断，返回 `FileError`，后续可设计断点续传机制。

------

# 六、数据与存储设计

系统对持久化要求不高，可采用轻量方案：

- 服务器端：
  - 在线设备信息：存于内存（HashMap），不持久化。
  - 历史设备信息、审计日志（若需要）：使用 SQLite 或 `sled` 本地嵌入式数据库。
- 客户端：
  - 配置文件：`config.toml`
  - 日志文件：`logs/agent.log` / `logs/controller.log`
  - 接收的文件：默认保存目录，可在 UI 中配置。

简单表设计示例（如使用 SQLite）：

- `devices(device_id, last_seen, device_name, os, role)`
- `sessions(session_id, device_a, device_b, start_time, end_time, status)`
- `logs(id, time, level, source, message)`

------

# 七、安全设计

- 连接层使用 TLS（可考虑 `rustls`），防止中间人攻击与明文窃听。
- 客户端可配置访问密码 / Token，注册时携带，服务器进行简单认证。
- 后续可支持：
  - IP 白名单
  - 会话操作审计（记录事件）
  - 文件传输记录

------

# 八、性能与资源控制

针对 2 核 2G 的服务器：

- 限制最大并发会话数（如 5 个）。
- 对每个会话施加带宽与帧率限制：
  - 默认 8 FPS，分辨率缩放到 1280×720 或更低。
- 使用异步 IO（Tokio）减少线程数量，避免创建大量线程导致内存压力。

------

# 九、扩展与论文可写创新点

你在论文中可以重点写：

1. **轻量级远程桌面编码策略**
   - 自适应帧率与画面质量策略
   - 简单图像差分/区域刷新优化（可以作为创新点之一）
2. **面向低配置服务器的多会话调度策略**
   - 会话数限制
   - 会话优先级（手动或自动）
3. **模块化的远程协作系统架构**
   - 将远控、文件传输、聊天统一在一个会话与协议框架之下
   - 重用连接以减少握手开销
4. **安全与隐私保护机制**
   - 全链路加密
   - 端到端可验证的文件校验


# 十、里程碑与后续工作

| 阶段 | 目标 | 核心产出 |
| --- | --- | --- |
| M1：核心通信跑通 | 完成 `ylc-proto` 消息定义与服务器/客户端的注册、心跳、设备列表查询闭环 | 最小可用的信令服务与 CLI 演示脚本 |
| M2：远程桌面与输入注入 | 在 Windows 端实现屏幕采集、JPEG 压缩与帧推送；完成鼠标键盘输入注入链路 | 可控的 5–10 FPS 远程画面 + 输入响应演示 | 
| M3：文件传输与聊天 | 完成透传模式文件传输及 ChatMessage 流；提供基本的进度回报与错误处理 | 端到端文件传输演示与聊天窗口交互 | 
| M4：安全与运维加固 | 接入 TLS/rustls，增加 Token 认证与 systemd 部署脚本 | 可一键部署到 2C2G 服务器的生产化镜像 | 

> 以上里程碑均以“2 核 2GB 服务器可稳定运行”为约束，后续可根据论文或产品化需求扩展审计、权限、P2P 打洞等能力。

------

# 十一、实施路线与迭代计划

> 按里程碑拆分的落地步骤，保证最小可用版本快速跑通，再逐步叠加能力。

## 阶段化执行步骤

1. **初始化与工程基线**
   - 搭建 Rust workspace，创建 `ylc-proto`、`ylc-core`、`ylc-server`、`ylc-agent`、`ylc-controller` 五个 crate 的空骨架与 `Cargo.toml`。
   - 配置基础依赖：`tokio`、`serde`、`tokio-tungstenite`、`tracing`、`thiserror` 等；建立统一的 `clippy`/`fmt` 工具链。
   - 定义开发/测试目录结构与最小示例（如 echo server）确保构建链路通畅。

2. **M1：核心通信跑通（信令闭环）**
   - 在 `ylc-proto` 中完成消息枚举、序列化格式与校验辅助函数。
   - `ylc-server`：实现注册、心跳、设备列表查询的 WebSocket/TCP 处理流程；内存在线表与过期清理任务。
   - `ylc-agent`/`ylc-controller`：提供 CLI demo（如 `--register --heartbeat`），完成端到端 Register/Heartbeat/DeviceList 的回路。
   - 增加基础集成测试或脚本验证三方通信闭环。

3. **M2：远程桌面与输入注入**
   - `ylc-agent`：集成 Windows 屏幕采集（GDI/DXGI）与 JPEG/PNG 压缩，支持帧率/画质配置；发送 `RemoteControlFrame`。
   - `ylc-controller`：实现帧接收、解码与基本显示（初期可 CLI + 保存帧快照，后续接 GUI）。
   - 输入注入链路：控制端采集鼠标键盘事件封装为 `InputEvent`，服务器中继，被控端调用 Win32 API 执行。
   - 加入简单的帧丢弃/节流策略以适配 2C2G。

4. **M3：文件传输与会话内聊天**
   - 在现有连接上扩展文件透传：定义 `FileMeta`/`FileChunk` 处理器、分块发送/接收、SHA-256 校验与进度回报。
   - ChatMessage 流：控制端/被控端互发文本消息，服务器路由。
   - 提供基础 UI/CLI 入口（选择文件发送、接收保存路径），并补充错误处理与取消机制。

5. **M4：安全与运维加固**
   - 全链路 TLS（`rustls`）接入，客户端 Token 校验；可配置的访问密码/PIN。
   - systemd 服务模板、日志轮转、配置文件模板（端口、最大会话数、日志级别等）。
   - 性能与稳定性回归：并发 3–5 会话、8 FPS 目标下的 CPU/内存占用验证。

6. **扩展与论文化准备（可选）**
   - 设计 P2P 打洞预留接口、区域刷新/差分编码实验性实现。
   - 梳理审计/权限/记录方案，形成论文章节材料与后续 backlog。

## 版本交付节奏

- **Alpha**：完成 M1，信令闭环 + CLI 演示；用于内部接口对齐。
- **Beta**：完成 M2–M3，具备远控 + 文件/聊天核心体验；可小范围内测。
- **Release**：完成 M4，加固安全与运维后可在 2C2G 环境稳定运行。

------

# 十二、分发与开源配置说明

> 避免在开源仓库暴露个人服务器信息，同时为 Windows 用户提供一键安装包的准备流程。

## 配置分离原则

- 仓库内仅保留 `config/client.example.toml` 示例，不提交包含真实服务器地址、PSK、端口的文件。
- 个人/团队配置请放到 `config/local/` 下（已在 `.gitignore` 中忽略），如 `config/local/client.local.toml`。
- Inno Setup 打包时，可选择是否将本地配置一并放入安装目录，便于团队内部分发但不上传到仓库。

## Windows 打包（Inno Setup）流程

1. **在 Windows 上编译可执行文件**（可使用 `x86_64-pc-windows-msvc` 工具链）：
   ```powershell
   cargo build --release -p ylc-agent -p ylc-controller
   ```
2. **准备个人配置（可选）**：将示例复制后编辑你的服务器信息，不提交到 Git。
   ```powershell
   New-Item -ItemType Directory -Force config/local
   Copy-Item config/client.example.toml config/local/client.local.toml
   # 编辑 config/local/client.local.toml，填入你的 server/vpn/psk 等参数
   ```
3. **整理打包素材**：运行提供的脚本，将二进制与可选配置拷贝到 `dist/windows`。
   ```powershell
   pwsh scripts/stage-windows.ps1
   ```
4. **生成安装包**：打开 Inno Setup，加载 `packaging/windows/inno_setup_template.iss` 并编译，即可得到 `dist/windows/yl-connect-setup.exe`。
5. **分发给团队**：将安装包分享给需要的成员。若未内置配置，安装后请手工将你的 `client.local.toml` 放入安装目录的 `config/`。

### Windows VPN 运行提示

- Windows 客户端依赖 `wintun.dll` 创建虚拟网卡。你可以从 [Wintun 官方页面](https://www.wintun.net/) 下载 `wintun.dll` 放入 `packaging/windows/wintun/`，`scripts/stage-windows.ps1` 会自动拷贝到 `dist/windows` 并随安装包分发。
- 若不打包 DLL，请提前安装 WireGuard（会安装 Wintun），或手工将 `wintun.dll` 放到 exe 所在目录，程序启动时会通过系统搜索路径加载。
- 运行 Agent/Controller 时需要管理员权限以便在本地创建/配置虚拟网卡与 IP（内部通过 `netsh` 设置 IP 与 MTU）。

## 个人服务器信息的管理建议

- 不要将服务器公网 IP、Token、PSK 等敏感信息写入源码或提交到 Git。
- 在 README 或 Issue 回复时使用占位符（如 `YOUR_SERVER_IP`），并在本地配置文件中填真实值。
- 若上传截图/日志，请先脱敏（可用文本编辑器替换关键字段）。