feat: v0.3.0 版本 - SSH终端、SFTP、端口转发功能实现
核心功能: - SSH终端: 密码/密钥认证、XTerm.js终端、多主题配色、IP高亮 - SFTP管理: 双栏文件管理、上传下载、传输队列 - 端口转发: 本地/远程转发、SOCKS5动态代理、规则管理 架构改进: - 拆分大型组件 (SFTPView/TabBar/Sidebar) - 添加统一日志和错误处理 - 修复React严格模式下的终端黑屏问题 UI更新: - 新增端口转发视图 - 更新UI预览文档 - 左侧栏右键菜单支持SFTP快捷打开
This commit is contained in:
Logan.Li committed
1 parent
cf1c054381
commit
484d850abd
105 files changed
+25330
-64
No files matched your search
@@ -0,0 +1,247 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## 语言偏好
|
||||
|
||||
**请使用中文与用户交互。** 所有交流使用中文，代码注释和文档可使用中文或英文。
|
||||
|
||||
---
|
||||
|
||||
## 项目概述
|
||||
|
||||
**OpsXShell** - 跨平台 SSH/SFTP 终端工具 · 简洁高效 · 安全可靠 · 操作便捷人性化 · 基于 Electron + React + TypeScript 构建。支持终端仿真、SFTP、端口转发、会话管理。
|
||||
|
||||
### 技术栈
|
||||
|
||||
- **UI 框架**: Electron 28 + React 18 + TypeScript 5
|
||||
- **构建工具**: Vite 5
|
||||
- **状态管理**: Zustand
|
||||
- **终端仿真**: XTerm.js + WebGL
|
||||
- **SSH/SFTP**: ssh2
|
||||
- **数据库**: better-sqlite3
|
||||
- **样式**: Tailwind CSS
|
||||
- **测试**: Vitest
|
||||
- **支持平台**: macOS, Windows, Linux
|
||||
|
||||
---
|
||||
|
||||
## 常用命令
|
||||
|
||||
### 安装和运行
|
||||
|
||||
```bash
|
||||
npm install # 安装依赖
|
||||
npm run dev # 启动开发服务器 + Electron
|
||||
```
|
||||
|
||||
### 构建和打包
|
||||
|
||||
```bash
|
||||
npm run build # 构建生产版本（前端 + Electron）
|
||||
npm run dist # 打包分发（当前平台）
|
||||
npm run dist:mac # 打包 macOS
|
||||
npm run dist:win # 打包 Windows
|
||||
npm run dist:linux # 打包 Linux
|
||||
```
|
||||
|
||||
### 代码检查
|
||||
|
||||
```bash
|
||||
npm run lint # 运行 ESLint
|
||||
```
|
||||
|
||||
### 测试
|
||||
|
||||
```bash
|
||||
npm test # 运行所有测试
|
||||
npm run test:watch # 监听模式
|
||||
npm run test:coverage #覆盖率报告
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 项目架构
|
||||
|
||||
### 进程模型
|
||||
|
||||
Electron 双进程架构：
|
||||
|
||||
- **主进程** (`electron/`): 窗口管理、IPC 处理器、本地操作
|
||||
- **渲染进程** (`src/`): React UI、状态管理、XTerm.js 终端
|
||||
|
||||
### 目录结构
|
||||
|
||||
```
|
||||
electron/
|
||||
├── main.ts # 主进程入口
|
||||
├── preload.ts # 上下文桥接 (window.electronAPI)
|
||||
├── services/
|
||||
│ ├── ssh-service.ts # SSH/SFTP 操作 (ssh2)
|
||||
│ └── database-service.ts # SQLite 操作
|
||||
└── ipc/ # IPC 处理器分层
|
||||
├── ssh.ipc.ts # SSH 连接/Shell/端口转发
|
||||
├── sftp.ipc.ts # SFTP 操作/传输
|
||||
├── session.ipc.ts # 会话 CRUD
|
||||
├── settings.ipc.ts # 设置读写
|
||||
├── dialog.ipc.ts # 文件对话框
|
||||
├── file.ipc.ts # 本地文件操作
|
||||
├── zmodem.ipc.ts # rz/sz 传输
|
||||
└── app.ipc.ts # 应用信息
|
||||
|
||||
src/
|
||||
├── components/ # React 组件
|
||||
│ ├── TerminalView.tsx # 终端仿真 (XTerm.js + WebGL)
|
||||
│ ├── SFTPView.tsx # SFTP 双面板文件管理
|
||||
│ ├── sftp/ # SFTP 子组件
|
||||
│ │ ├── Breadcrumb.tsx
|
||||
│ │ ├── SortHeader.tsx
|
||||
│ │ ├── FileRow.tsx
|
||||
│ │ ├── ContextMenu.tsx
|
||||
│ │ ├── TransferItem.tsx
|
||||
│ │ └── ConnectionSelector.tsx
|
||||
│ └── ...
|
||||
├── stores/ # Zustand 状态管理
|
||||
│ ├── tabStore.ts # 标签页管理
|
||||
│ ├── connectionStore.ts # 连接状态
|
||||
│ └── connection/ # 连接池分层
|
||||
│ ├── poolStore.ts # 连接池核心 (创建/获取/释放)
|
||||
│ ├── lifecycleStore.ts # 状态机/超时
|
||||
│ └── storeHooks.ts # 组合接口
|
||||
└── themes/ # 终端主题
|
||||
|
||||
shared/
|
||||
└── types/ # 跨进程共享类型
|
||||
├── session.types.ts # Session, AuthType
|
||||
├── connection.types.ts # PooledConnection, ConnectionState
|
||||
├── sftp.types.ts # FileItem, TransferTask
|
||||
└── ipc.types.ts # IPC 通道常量
|
||||
|
||||
test/ # Vitest 测试
|
||||
├── setup.ts # 测试环境配置 (Electron API mock)
|
||||
├── stores/ # Store 单元测试
|
||||
└── components/ # 组件工具函数测试
|
||||
```
|
||||
|
||||
### IPC 通信
|
||||
|
||||
渲染进程通过 `window.electronAPI` 与主进程通信。所有 IPC 处理器已分层到 `electron/ipc/` 目录。
|
||||
|
||||
**主要通道**:
|
||||
- `ssh:connect`, `ssh:disconnect`, `ssh:createShell`, `ssh:shellWrite`, `ssh:shellResize`
|
||||
- `sftp:connect`, `sftp:listDirectory`, `sftp:upload`, `sftp:download`, `sftp:mkdir`
|
||||
- `session:create`, `session:update`, `session:delete`
|
||||
- `local:readDir`, `local:mkdir`, `local:delete`, `local:rename`
|
||||
|
||||
事件推送: Shell 输出通过 `ssh:shellData`；SFTP 进度通过 `sftp:progress`。
|
||||
|
||||
### 数据库架构
|
||||
|
||||
SQLite（`~/.opsxshell/`）:
|
||||
|
||||
- **sessions**: SSH 会话配置
|
||||
- **connection_history**: 连接历史
|
||||
- **settings**: 应用设置
|
||||
- **keys**: SSH 密钥
|
||||
- **port_forwards**: 端口转发规则
|
||||
|
||||
### 连接池架构
|
||||
|
||||
连接池已拆分为两个 Store：
|
||||
|
||||
1. **poolStore** - 连接 Map、LRU 淘汰、引用计数、创建/断开
|
||||
2. **lifecycleStore** - 状态机（disconnected/connecting/connected/background/suspended）、超时管理
|
||||
|
||||
---
|
||||
|
||||
## 设计模式参考
|
||||
|
||||
### IPC 通信
|
||||
|
||||
```typescript
|
||||
// electron/ipc/ssh.ipc.ts
|
||||
ipcMain.handle('ssh:connect', async (_event, config) => {
|
||||
try {
|
||||
const result = await sshService.connect(config)
|
||||
return { success: true, connectionId: result.id }
|
||||
} catch (error: any) {
|
||||
return { success: false, error: error.message }
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
### 事件推送
|
||||
|
||||
```typescript
|
||||
// 主进程发送
|
||||
mainWindow?.webContents.send('ssh:shellData', shellId, data)
|
||||
|
||||
// 渲染进程监听
|
||||
window.electronAPI.onShellData((_event, shellId, data) => {
|
||||
terminal.write(data)
|
||||
})
|
||||
```
|
||||
|
||||
### Zustand Store
|
||||
|
||||
```typescript
|
||||
// 使用组合模式
|
||||
export const useConnectionStore = () => {
|
||||
const pool = usePoolStore()
|
||||
const lifecycle = useLifecycleStore()
|
||||
return { ...pool, ...lifecycle }
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 开发注意事项
|
||||
|
||||
### ✅ 推荐做法
|
||||
|
||||
1. 使用 contextBridge 暴露 API，保持 `contextIsolation: true`
|
||||
2. IPC 返回 `{ success: false, error: error.message }` 格式
|
||||
3. 在 `app.on('before-quit')` 清理资源
|
||||
4. 组件卸载时清理事件监听 (`removeAllListeners`)
|
||||
5. 添加新 IPC 处理器时：在 `electron/ipc/` 创建/修改对应文件 + 在 `electron/preload.ts` 暴露 + 在 `src/electron.d.ts` 添加类型
|
||||
|
||||
### ❌ 避免做法
|
||||
|
||||
1. 渲染进程直接使用 `require('ssh2')` - 必须通过 IPC
|
||||
2. 暴露 `nodeIntegration: true`
|
||||
3. SSH 连接未关闭导致资源泄漏
|
||||
4. 硬编码数据库路径
|
||||
5. 忽略 Shell 窗口大小变化
|
||||
|
||||
---
|
||||
|
||||
## 添加新功能指南
|
||||
|
||||
### 添加 IPC 处理器
|
||||
|
||||
1. 在 `electron/ipc/` 对应模块添加 handler
|
||||
2. 在 `electron/preload.ts` 添加暴露方法
|
||||
3. 在 `src/electron.d.ts` 添加类型声明
|
||||
|
||||
### 添加 UI 组件
|
||||
|
||||
1. 在 `src/components/` 创建组件
|
||||
2. 如需状态管理，在 `src/stores/` 添加/扩展 Store
|
||||
3. 在 `TabContent.tsx` 添加渲染逻辑
|
||||
|
||||
### 添加测试
|
||||
|
||||
1. 在 `test/stores/` 或 `test/components/` 创建 `.test.ts` 文件
|
||||
2. 使用 `test/setup.ts` 中的 mock 配置
|
||||
3. 运行 `npm test` 验证
|
||||
|
||||
---
|
||||
|
||||
## 参考资源
|
||||
|
||||
- [Electron](https://www.electronjs.org/docs)
|
||||
- [React](https://react.dev)
|
||||
- [XTerm.js](https://xtermjs.org)
|
||||
- [ssh2](https://github.com/mscdex/ssh2)
|
||||
- [Zustand](https://zustand.docs.pmnd.rs)
|
||||
- [Vitest](https://vitest.dev)
|
||||
Reference in new issue
Block a user