# ssh2重构计划

**决策日期**: 2026-06-10 01:35
**状态**: ⚠️ 开始重构

---

## 一、重构决策

### 背景

**混合架构失败原因**：
- ❌ russh Channel ≠ ssh2 Channel（类型不兼容）
- ❌ 无法共享TCP连接
- ❌ 无法传递Channel对象

**决策**：完全切换到ssh2库

---

## 二、重构范围

### 需要重写的模块

| 模块 | 当前状态 | 重写工作量 |
|------|----------|------------|
| **SSH server** | russh实现 | 高（约200行） |
| **SFTP handler** | 14操作完成 | 高（约300行） |
| **SCP sender** | scp_sender.rs（89行） | 中（约100行） |
| **SCP receiver** | placeholder | 中（约100行） |
| **rsync sender** | 40%实现 | 中（约150行） |
| **rsync receiver** | placeholder | 中（约150行） |
| **Auth系统** | bcrypt完成 | 低（可复用） |
| **Config系统** | 完成 | 低（可复用） |
| **总计** | | **约1000行** |

---

## 三、ssh2架构设计

### 新架构

```
MarkBase SSH System（ssh2版）
├── ssh2_server.rs（主服务器）
│   ├── TcpListener + ssh2::Session
│   ├── Auth handler（bcrypt复用）
│   ├── Session管理
│   └── Channel路由
│
├── sftp_handler.rs（SFTP）
│   ├── 14操作重写
│   ├── FileTree映射
│   └── SQLite集成
│
├── scp_handler.rs（SCP）
│   ├── scp -f（sender）✅
│   ├── scp -t（receiver）✅
│   └── scp -r（目录）✅
│
├── rsync_handler.rs（rsync）
│   ├── rsync sender ✅
│   ├── rsync receiver ✅
│   ├── checksum算法 ✅
│   └── delta算法 ✅
│
└── auth.rs（认证）
    ├── bcrypt验证 ✅复用
    └── SQLite查询 ✅复用
```

---

## 四、实施阶段

### Phase 1：SSH Server核心（Day 1）

**目标**：建立ssh2服务器基础

**任务**：
1. 创建ssh2_server.rs
2. 实现TcpListener + ssh2::Session
3. 实现Auth handler（bcrypt复用）
4. 实现Channel管理
5. 测试SSH连接和认证

**预期代码**：约200行

---

### Phase 2：SFTP Handler重写（Day 2）

**目标**：14个SFTP操作全部重写

**任务**：
1. 重写init操作
2. 重写open/read/write/close
3. 重写mkdir/rmdir/remove/rename
4. 重写opendir/readdir
5. 重写realpath/stat/lstat
6. 测试所有SFTP操作

**预期代码**：约300行

**关键改动**：
- russh-sftp → ssh2::Channel::exec("sftp")
- 或直接实现SFTP协议（ssh2-sftp crate？）

---

### Phase 3：SCP完整实现（Day 3）

**目标**：完整SCP sender + receiver

**任务**：
1. SCP sender（已有代码可移植）
2. SCP receiver（新增）
3. SCP目录递归（新增）
4. SCP权限保留（新增）
5. 测试SCP功能

**预期代码**：约200行

**优势**：
- ✅ ssh2完整read/write支持
- ✅ 可实现完整SCP协议

---

### Phase 4：rsync完整实现（Day 4）

**目标**：完整rsync sender + receiver

**任务**：
1. rsync sender（移植现有代码）
2. rsync receiver（新增）
3. checksum算法（已有）
4. delta算法（已有）
5. 测试rsync功能

**预期代码**：约300行

**优势**：
- ✅ ssh2完整双向通信
- ✅ 可实现完整rsync协议

---

### Phase 5：测试和优化（Day 5）

**目标**：全面测试和文档更新

**任务**：
1. 单元测试
2. 功能测试（SFTP + SCP + rsync）
3. 性能测试
4. 文档更新（AGENTS.md）
5. 清理旧russh代码

---

## 五、可复用代码

### 无需重写的模块

| 模块 | 说明 |
|------|------|
| **auth.rs** | bcrypt认证逻辑可复用 |
| **config.rs** | SftpConfig可复用 |
| **filetree.rs** | FileTree映射逻辑可复用 |
| **rsync算法** | checksum.rs, delta.rs可复用 |
| **SQLite数据库** | auth.sqlite可复用 |

---

## 六、技术挑战

### 挑战1：SFTP实现方式

**问题**：ssh2如何实现SFTP？

**方案A**：使用ssh2::Channel::exec("sftp-server")
- 依赖系统sftp-server程序
- 简单但不够灵活

**方案B**：实现SFTP协议
- 需理解SFTP packet格式
- 工作量大但灵活

**方案C**：使用ssh2-sftp crate（如果有）
- 查找是否有ssh2的SFTP crate
- 如果有则简化工作

---

### 挑战2：阻塞式API适配tokio

**问题**：ssh2是阻塞式，MarkBase是异步

**方案A**：使用tokio::task::spawn_blocking
```rust
tokio::task::spawn_blocking(|| {
    // ssh2阻塞操作
    channel.read(&mut buf)?;
}).await?;
```

**方案B**：使用tokio::io::AsyncReadExt适配
- 需要wrapper将ssh2::Channel转为AsyncRead

---

### 挑战3：性能影响

**问题**：阻塞式API可能影响并发性能

**解决方案**：
- 使用spawn_blocking隔离阻塞操作
- 多线程处理多个客户端
- 性能测试验证

---

## 七、预期结果

### 功能完整度

| 功能 | 重构后完整度 |
|------|--------------|
| **SFTP** | ✅ 100%（14操作） |
| **SCP sender** | ✅ 100% |
| **SCP receiver** | ✅ 100% ⭐新增 |
| **SCP目录** | ✅ 100% ⭐新增 |
| **rsync sender** | ✅ 100% |
| **rsync receiver** | ✅ 100% ⭐新增 |
| **整体完整度** | **100%** ⭐⭐⭐⭐⭐ |

---

### 性能预期

| 指标 | russh（异步） | ssh2（阻塞） |
|------|---------------|--------------|
| **SFTP吞吐量** | 150 MB/s | 120 MB/s（略降） |
| **SCP吞吐量** | N/A | 100 MB/s ⭐ |
| **rsync吞吐量** | Sender only | Sender + Receiver ⭐ |
| **并发性能** | 高 | 中（spawn_blocking） |

---

## 八、风险评估

| 风险 | 概率 | 影响 | 缓解措施 |
|------|------|------|----------|
| **SFTP重写复杂** | 高 | 高 | 查找ssh2-sftp crate |
| **阻塞API性能** | 中 | 中 | spawn_blocking隔离 |
| **调试困难** | 中 | 中 | 详细日志 |
| **功能缺失** | 低 | 高 | 完整测试 |

---

## 九、实施时间表

| 阶段 | 时间 | 任务 |
|------|------|------|
| **Phase 1** | Day 1 | SSH Server核心 |
| **Phase 2** | Day 2 | SFTP Handler重写 |
| **Phase 3** | Day 3 | SCP完整实现 |
| **Phase 4** | Day 4 | rsync完整实现 |
| **Phase 5** | Day 5 | 测试和优化 |
| **总计** | **5天** | |

---

## 十、决策确认

**重构决策**：✅确认
- 完全切换到ssh2库
- 重写SSH Server + SFTP Handler
- 实现完整SCP/rsync支持
- 时间：5天
- 工作量：约1000行代码

---

**计划完成时间**: 2026-06-10 01:40
**版本**: 1.0（ssh2重构版）