192 lines
8.8 KiB
Markdown
192 lines
8.8 KiB
Markdown
# 🚀 Rtty 项目实现总结与目录导航
|
||
|
||
> **Rtty** 是一款基于 Rust + Flutter 构建的高性能、跨平台分布式虚拟终端系统。
|
||
> 服务端（Rust + Alacritty 引擎）在内存中维持"真相源"，通过 WebSocket 与各端解耦；
|
||
> 桌面端（Flutter + `flutter_alacritty`）共享同一 Alacritty 引擎做工业级 ANSI 渲染；
|
||
> 移动端（Flutter）消费语义化快照做卡片化重排。
|
||
|
||
---
|
||
|
||
## 一、总体架构
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
subgraph Server["rtty-server (Rust)"]
|
||
PTY["portable-pty<br/>伪终端 / Shell"]
|
||
ENGINE["alacritty_terminal<br/>真相源 · ANSI 解析 · 屏幕网格"]
|
||
WS["Axum WebSocket<br/>session 管理 / 广播"]
|
||
end
|
||
|
||
subgraph Desktop["rtty-desktop (Flutter Windows)"]
|
||
BACKEND["RttyPtyBackend<br/>WebSocket 桥接"]
|
||
DENGINE["flutter_alacritty<br/>Alacritty 引擎渲染"]
|
||
end
|
||
|
||
subgraph Mobile["rtty-mobile (Flutter)"]
|
||
MCLIENT["RttyMobileClient<br/>语义快照消费"]
|
||
MUI["卡片化 / 换行 / Keybar"]
|
||
end
|
||
|
||
PTY --> ENGINE --> WS
|
||
WS -->|"原始 ANSI 二进制帧<br/>client=desktop"| BACKEND --> DENGINE
|
||
WS -->|"语义化 JSON 快照<br/>client=mobile"| MCLIENT --> MUI
|
||
```
|
||
|
||
---
|
||
|
||
## 二、目录树状图与功能对应
|
||
|
||
### 1. 服务端内核 `src/`（Rust）
|
||
|
||
```
|
||
src/
|
||
├── main.rs # 程序入口：全局 AppState（会话表）、Axum 路由、配置加载
|
||
├── config.rs # ServerConfig：host/port/shell/尺寸/scrollback/并发限制/空闲超时（环境变量 RTTY_* 可覆盖）
|
||
├── terminal/ # 终端核心（PTY + Alacritty 引擎）
|
||
│ ├── mod.rs # terminal 模块声明
|
||
│ ├── pty.rs # PtySession：portable-pty 伪终端封装（拉起 Shell、读写、resize、kill）
|
||
│ └── engine.rs # TerminalEngine：alacritty_terminal 封装（ANSI 解析、网格维护、语义快照生成、PtyWrite 回写）
|
||
└── ws/ # WebSocket 通信层
|
||
├── mod.rs # ws 模块声明
|
||
├── protocol.rs # 协议：ClientMessage（input/resize/claim_control/ping）、ServerMessage（ready/snapshot/control/error/session_closed）、MobileSnapshot
|
||
└── handler.rs # 会话管理：多端解耦广播、并发限制、控制权强制、会话清理（EOF + 进程监控 + 空闲超时）
|
||
```
|
||
|
||
| 功能 | 对应文件 |
|
||
|------|---------|
|
||
| 伪终端创建 / Shell 拉起 / 读写 / resize | `src/terminal/pty.rs` |
|
||
| ANSI 解析 / 屏幕网格 / 滚动历史 / 语义快照 | `src/terminal/engine.rs` |
|
||
| 断线重连状态恢复（初始快照） | `src/ws/handler.rs` |
|
||
| 多端解耦（PC 收 ANSI、移动收快照） | `src/ws/handler.rs` |
|
||
| 控制权强制（非控制者输入被拒） | `src/ws/handler.rs` |
|
||
| 会话清理（泄漏防护） | `src/ws/handler.rs` |
|
||
| 配置加载（环境变量） | `src/config.rs` |
|
||
|
||
---
|
||
|
||
### 2. 桌面端 `desktop/`（Flutter Windows）
|
||
|
||
```
|
||
desktop/
|
||
├── lib/
|
||
│ ├── main.dart # 入口：初始化 RustLib（flutter_rust_bridge）后启动应用
|
||
│ └── src/
|
||
│ ├── rtty_pty_backend.dart # RttyPtyBackend：实现 flutter_alacritty 的 PtyBackend 接口，桥接 WebSocket
|
||
│ ├── terminal_config.dart # RttyTerminalConfig：把 Rtty 配色/字体映射为 Alacritty TerminalConfig
|
||
│ ├── terminal_screen.dart # 主页面：TerminalEngine + TerminalView、连接控制、resize 防抖、双向接线
|
||
│ ├── connection_bar.dart # 顶部连接控制条：状态灯、host/port/session 输入、会话徽章、连接按钮
|
||
│ └── theme.dart # 工业终端主题（深炭黑 + 磷光青绿）
|
||
├── test/ # 单元测试（服务端离线时集成测试自动跳过）
|
||
│ ├── e2e_ws_test.dart # RttyPtyBackend 连真实服务端接收原始 ANSI 输出
|
||
│ ├── regression_ws_test.dart# 多端解耦 + 控制权强制 + 会话清理回归
|
||
│ ├── support.dart # 测试共享工具（服务端探测）
|
||
│ └── widget_test.dart # Widget 渲染测试
|
||
├── integration_test/ # 真实 Windows 桌面集成测试
|
||
│ ├── e2e_test.dart # 连接 + 渲染 + 命令回显闭环
|
||
│ └── cd_resize_test.dart # cd 跨目录 + resize 内容完整性
|
||
├── windows/ # Windows 平台 CMake/runner（flutter 生成）
|
||
├── pubspec.yaml # 依赖：web_socket_channel、flutter_alacritty
|
||
└── README.md # 桌面端说明
|
||
```
|
||
|
||
| 功能 | 对应文件 |
|
||
|------|---------|
|
||
| Alacritty Rust 引擎初始化 | `lib/main.dart`（`await RustLib.init()`） |
|
||
| WebSocket ↔ PtyBackend 桥接（远程数据源） | `lib/src/rtty_pty_backend.dart` |
|
||
| 引擎接线（输出喂渲染、输入回传服务端） | `lib/src/terminal_screen.dart` |
|
||
| 100% 工业级 ANSI 渲染（vim/htop/tmux） | `lib/src/terminal_screen.dart` + `flutter_alacritty` |
|
||
| resize 防抖（TUI resize 稳定性） | `lib/src/terminal_screen.dart` |
|
||
| 连接控制条 / 会话管理 | `lib/src/connection_bar.dart` |
|
||
| 主题 / 配色 | `lib/src/theme.dart`、`lib/src/terminal_config.dart` |
|
||
|
||
---
|
||
|
||
### 3. 移动端 `mobile/`（Flutter）
|
||
|
||
```
|
||
mobile/
|
||
├── lib/
|
||
│ ├── main.dart # 入口
|
||
│ └── src/
|
||
│ ├── rtty_mobile_client.dart # RttyMobileClient：消费 mobile_snapshot 语义快照，发送 input/resize/claim_control
|
||
│ └── theme.dart # 移动端主题（卡片化美学）
|
||
├── android/ # Android 平台工程（flutter 生成）
|
||
├── ios/ # iOS 平台工程（flutter 生成）
|
||
└── pubspec.yaml # 依赖：web_socket_channel
|
||
```
|
||
|
||
> ⚠️ **当前状态**：移动端为脚手架骨架（客户端连接层与主题已就绪），卡片化重排、Keybar 等核心 UI 尚未实现，尚未提交 Git。这是规划中的下一个里程碑。
|
||
|
||
| 功能 | 对应文件 |
|
||
|------|---------|
|
||
| 语义快照 WebSocket 消费 | `mobile/lib/src/rtty_mobile_client.dart` |
|
||
| 智能换行 / 卡片化 / Keybar | ⏳ 待实现 |
|
||
|
||
---
|
||
|
||
### 4. 根目录其他文件
|
||
|
||
```
|
||
Rtty/
|
||
├── src/ # 服务端源码（见上）
|
||
├── desktop/ # 桌面端（见上）
|
||
├── mobile/ # 移动端（见上）
|
||
├── Cargo.toml # 服务端依赖与 release 优化配置
|
||
├── Cargo.lock # Rust 依赖锁
|
||
├── README.md # 项目设计总结与架构指南
|
||
├── LICENSE # 许可证
|
||
└── .gitignore # 忽略 target/.idea/Cargo.lock 等
|
||
```
|
||
|
||
---
|
||
|
||
## 三、核心功能清单（实现 vs 规划）
|
||
|
||
| 功能 | 服务端 | 桌面端 | 移动端 | 状态 |
|
||
|------|:---:|:---:|:---:|:---:|
|
||
| PTY / Shell 会话 | ✅ | — | — | 已实现 |
|
||
| Alacritty 引擎（ANSI 解析 / 网格） | ✅ | ✅ | — | 已实现 |
|
||
| 多端状态保持（断线重连恢复） | ✅ | ✅ | ⏳ | 已实现 |
|
||
| 多端解耦（PC ANSI / 移动快照） | ✅ | ✅ | ⏳ | 已实现 |
|
||
| 控制权强制 | ✅ | — | ⏳ | 已实现 |
|
||
| 会话清理（空闲超时） | ✅ | — | — | 已实现 |
|
||
| 100% 工业级 ANSI 渲染 | — | ✅ | — | 已实现 |
|
||
| 命令执行 / cd / TUI resize 稳定 | — | ✅ | — | 已实现 |
|
||
| 智能文本换行（Word Wrap） | — | — | ⏳ | 规划 |
|
||
| 卡片化命令交互 | — | — | ⏳ | 规划 |
|
||
| 移动端 Keybar | — | — | ⏳ | 规划 |
|
||
| 分布式横向扩展 | ⏳ | — | — | 规划 |
|
||
| 服务端鉴权 | ⏳ | — | — | 规划 |
|
||
|
||
---
|
||
|
||
## 四、运行与构建
|
||
|
||
```bash
|
||
# 1. 服务端（仓库根目录）
|
||
cargo run # 监听 ws://0.0.0.0:8080
|
||
|
||
# 2. 桌面端
|
||
cd desktop
|
||
flutter run -d windows # 运行
|
||
flutter build windows --release # 构建（含 Rust 引擎编译）
|
||
|
||
# 3. 测试
|
||
cargo test # 服务端
|
||
flutter test # 桌面端单元测试（服务端离线时集成测试跳过）
|
||
flutter test integration_test -d windows # 桌面端真实桌面集成测试
|
||
```
|
||
|
||
---
|
||
|
||
## 五、目录导航速查
|
||
|
||
- **要改终端解析/网格逻辑** → `src/terminal/engine.rs`
|
||
- **要改 PTY/进程管理** → `src/terminal/pty.rs`
|
||
- **要改协议/消息格式** → `src/ws/protocol.rs`
|
||
- **要改会话/多端/清理逻辑** → `src/ws/handler.rs`
|
||
- **要改桌面端连接桥接** → `desktop/lib/src/rtty_pty_backend.dart`
|
||
- **要改桌面端渲染/接线** → `desktop/lib/src/terminal_screen.dart`
|
||
- **要改桌面端 UI/主题** → `desktop/lib/src/connection_bar.dart`、`theme.dart`
|
||
- **要改移动端连接层** → `mobile/lib/src/rtty_mobile_client.dart`
|