markbase/docs/SSH2_REFACTOR_PLAN.md

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

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重构版）