项目架构

Netcatty 不仅仅是一个"SSH 封装器"。它是一项复杂的工程工作，将低级系统调用（通过 Node.js C++ 插件）与高性能渲染（通过 WebGL）连接起来。

本文档解释了 Netcatty 如何运作。它适用于开发者、安全审计师和好奇的高级用户。

Electron 进程模型

Netcatty 利用 Electron 多进程架构 来确保稳定性和安全性。

1. 主进程 (Main Process, Node.js)

• 角色： 协调者。
• 职责：
  • 生成原生 PTY（伪终端）进程 (node-pty)。
  • 管理系统菜单和窗口。
  • 处理全局快捷键（Cmd+K 等）。
  • 与操作系统级别的 Keytar 交互，用于安全的密码存储。
• 权限： 拥有对 Node.js API 的完全访问权限。

2. 渲染进程 (Renderer Process, React, Chrome)

• 角色： 用户界面。
• 职责：
  • 渲染 React 组件树。
  • 管理应用状态 (Zustand)。
  • 绘制 xterm.js WebGL 画布。
• 权限： 沙盒化。 渲染进程不能直接访问磁盘或生成进程。它必须通过 IPC（进程间通信）请求这些操作。

3. 上下文隔离 (Context Isolation) (安全)

我们强制使用 contextIsolation: true。这意味着渲染进程代码无法访问 Electron 内部或 Node.js 原语。

• 桥接： 一个 preload.js 脚本向渲染进程暴露一个严格的、类型化的 API (window.electron)。
• 为什么？ 如果恶意服务器试图利用终端输出中的 XSS 漏洞（例如，打印一个奇怪的转义序列触发 HTML 渲染），他们会发现自己被困在一个无法访问你文件系统的沙盒中。

终端管道

一次按键是如何变成一个像素的？

1. 输入： 你在键盘上按下 A。
2. 渲染进程： React 捕获 onKeyDown。它发送一个 IPC 消息 term.write('A') 到主进程。
3. 主进程： 将 A 写入 PTY 文件描述符（SSH 二进制文件的 stdin）。
4. SSH 二进制： 将数据包发送到远程服务器。
5. 远程服务器： 回显 A（stdout）。
6. 主进程： 从 PTY stdout 捕获数据。发送 IPC 消息 term.data('A') 到渲染进程。
7. 渲染进程 (xterm.js)： 解析 ANSI 序列。
8. 引擎 (WebGL/Canvas)： 使用当前平台最高效的引擎绘制字形（WebGL 提供原始速度，而 Canvas 在 macOS 上提供清晰的文本）。

这个往返过程通常在 16 毫秒内完成（60fps），给人以即时输入的错觉。

数据持久化策略

Netcatty 采用 本地优先 (Local-First) 理念。

本地数据 (保险库)

• 存储： 我们使用标准的基于浏览器的 localStorage（由 Electron 的原生持久存储支持）来存储本地机器的保险库。
• 安全性： 对于本地机器的安全性，我们建议使用操作系统级别的全盘加密（FileVault / BitLocker）。高级的应用级加密（零知识）在 云同步 期间启用。
• 验证： 我们在运行时使用 Zod 模式，以确保损坏的数据不会导致应用崩溃。它会优雅地降级或提示恢复。

状态管理 (Zustand)

我们放弃 Redux 而选择 Zustand。用例：

• 会话状态： 哪些标签页打开了？哪个窗格获得焦点？（临时的，仅存于内存）。
• 设置状态： 主题偏好、字体大小。（持久化到单独的 config.json）。

性能优化

虚拟化

当你在保险库中有 5,000 个主机时，渲染 5,000 个 DOM 节点会冻结 UI。

• 解决方案： 我们使用 react-window（虚拟滚动）。我们只渲染当前屏幕上可见的约 20 个项目。
• 搜索： 我们使用自定义的模糊搜索实现，在 Web Worker 中索引对象树，以避免在输入时阻塞主线程。

Keep-Alives

即使渲染进程重新加载（例如，在开发期间或崩溃后），SSH 连接也会在主进程中保持活动。这是通过"分离会话 (Detached Sessions)"完成的。

• 重建水合 (Rehydration)： 当 UI 重新加载时，它会查询主进程："你有任何活动会话吗？"。主进程会以现有的 PTY 句柄和重放缓冲区进行回复。

贡献指南

Netcatty 是开源的 (MIT)。我们欢迎贡献。

技术栈

• 语言： TypeScript（严格模式）。
• 运行时： Node.js 20+。
• 打包器： Vite（用于超快的 HMR）。
• UI 框架： React 18, Tailwind CSS, shadcn/ui。

快速开始

1. git clone https://github.com/binaricat/Netcatty
2. npm install
3. 在一个终端中运行 npm run dev（启动渲染进程）。
4. 在另一个终端中运行 npm run electron（启动主进程）。