所有项目
维护中 2025

CrossShellNext

鸿蒙原生多协议终端客户端,对标 PuTTY 从零设计

项目背景

HarmonyOS 生态缺乏功能完整的终端工具。PuTTY 因与 Win32 API 深度耦合无法移植,需从零设计一套支持多协议、多会话并发的终端客户端架构。

架构设计

采用三层分离架构:

  • C++ 协议层(平台无关):实现 SSH、Telnet、Serial 三种协议,通过抽象基类 Session 统一生命周期接口
  • NAPI 桥接层:封装异步语义,所有阻塞 I/O 下沉到后台线程池,数据通过 napi_threadsafe_function 安全回调 JS 线程
  • ArkTS UI 层:基于 XtermJS 的终端渲染,无需感知底层协议差异

核心设计模式

  • SessionFactory 工厂模式:按协议类型创建会话,新增协议只需实现子类
  • SessionManager 单例:map<int, shared_ptr<Session>> 管理多会话生命周期
  • 回调”先缓存后投递”策略:解决 NAPI 回调注册与 C++ 连接建立的时序竞争

技术难点

多会话并发状态机:用 atomic<SessionStatus> + mutex 实现连接/断开互斥,配合 KeepAlive 心跳线程,防止并发操作导致 libssh2 底层 socket 状态不一致。

SFTP 双通道隔离:每个 SSH 连接维护两个独立 SFTP 会话(交互式浏览 + 文件传输),互不阻塞且支持传输取消。

资源安全释放unique_ptr + 自定义 deleter 管理 libssh2 原生句柄(session/channel/knownhosts),确保异常路径下无泄漏。

功能覆盖

  • SSH / Telnet / Serial / SFTP 四协议
  • 密钥生成(RSA / ECDSA / Ed25519)
  • 端口转发(本地 / 远程 / 动态)
  • 多窗口多会话并发
  • OSC7 目录跟踪
  • 完整日志系统
  • 明暗主题 + 中英双语