diff --git a/docs-site/docs/development/architecture.md b/docs-site/docs/development/architecture.md index 3839b24a..ded59214 100644 --- a/docs-site/docs/development/architecture.md +++ b/docs-site/docs/development/architecture.md @@ -4,155 +4,172 @@ sidebar_position: 1 # 架构说明 -Dragonfly 采用 Tauri 2 架构，前后端分离，通过 IPC 通信。 +Dragonfly 是一个基于 **Tauri 2** 的桌面应用：前端在 `src/`，后端在 `src-tauri/src/`，两者通过 Tauri command 与事件通信。 ## 整体架构 -``` -┌─────────────────────────────────────┐ -│ Frontend (React) │ -│ ┌──────┐ ┌──────┐ ┌─────────────┐ │ -│ │ 终端 │ │ 文件 │ │ 连接管理 │ │ -│ │ 面板 │ │ 浏览器│ │ │ │ -│ └──┬───┘ └──┬───┘ └──────┬──────┘ │ -│ │ │ │ │ -│ └────────┴────────────┘ │ -│ │ Tauri invoke │ -├──────────────┼──────────────────────┤ -│ │ IPC Bridge │ -├──────────────┼──────────────────────┤ -│ Backend (Rust) │ -│ ┌──────────┐ ┌──────┐ ┌────────┐ │ -│ │ Session │ │ SSH │ │ Config │ │ -│ │ Manager │ │ SFTP │ │ Store │ │ -│ └──────────┘ └──────┘ └────────┘ │ -└─────────────────────────────────────┘ +```text +┌─────────────────────────────────────────────────────────┐ +│ Frontend (React / TypeScript) │ +│ ├─ Main window: AppProvider + App.tsx │ +│ ├─ Child windows: ChildAppProvider + ChildWindowRouter│ +│ ├─ Terminal workspace, side panels, dialogs │ +│ └─ invoke wrapper + Tauri event listeners │ +├─────────────────────────────────────────────────────────┤ +│ Tauri IPC bridge │ +├─────────────────────────────────────────────────────────┤ +│ Backend (Rust) │ +│ ├─ SessionManager / TunnelManager / RecordingManager │ +│ ├─ PendingAuthManager │ +│ ├─ SSH / SFTP / watcher / importer / stats │ +│ └─ JSON config + encrypted credential storage │ +└─────────────────────────────────────────────────────────┘ ``` -## 前端架构 +## 前端窗口模型 -### 技术栈 +前端入口由 `src/main.tsx` 决定： -- **React 19** — UI 框架 -- **TypeScript** — 类型安全 -- **Vite** — 构建工具 -- **TailwindCSS 4** — 样式框架 -- **xterm.js** — 终端模拟器 +- **主窗口**：加载 `AppProvider` 与 `App.tsx` +- **子窗口**：加载 `ChildAppProvider` 与 `ChildWindowRouter` -### 目录结构 +当前子窗口流程包括： -``` -src/ -├── components/ # UI 组件 -│ ├── dialogs/ # 对话框组件 -│ ├── panels/ # 面板组件（侧边栏、文件浏览器等） -│ ├── layout/ # 布局组件 -│ └── ui/ # 基础 UI 组件（shadcn/ui） -├── context/ # React Context -│ ├── AppContext.tsx # 应用全局状态 -│ ├── ThemeContext.tsx # 主题管理 -│ └── TransferContext.tsx # 文件传输状态 -├── hooks/ # 自定义 Hooks -├── i18n/ # 国际化 -│ └── locales/ # 语言包（en.json, zh-CN.json） -├── lib/ # 工具库 -├── pages/ # 子窗口页面 -├── types/ # TypeScript 类型定义 -├── App.tsx # 主应用组件 -└── main.tsx # 入口文件 -``` +- 设置 +- 新建连接 +- 快捷命令编辑 +- 自动上传提示 -### 状态管理 +相关实现位置： -使用 React Context 管理全局状态： +- `src/main.tsx` +- `src/ChildWindowRouter.tsx` +- `src/lib/windowManager.ts` -- **AppContext** — 会话列表、连接配置、活动标签等 -- **ThemeContext** — 主题配置和切换 -- **TransferContext** — 文件传输队列和进度 +其中 `windowManager.ts` 还负责 modal child 与主窗口之间的焦点 / 可交互状态协调。 -## 后端架构 +## 前端状态模型 -### 模块组织 +### AppContext -``` -src-tauri/src/ -├── commands/ # Tauri 命令处理器 -│ ├── session_cmds.rs # 会话管理命令 -│ ├── sftp_cmds.rs # SFTP 文件操作命令 -│ ├── config_cmds.rs # 配置读写命令 -│ ├── settings_cmds.rs # 设置管理命令 -│ └── stats.rs # 系统信息命令 -├── config/ # 配置管理 -├── translate/ # 翻译服务 -├── lib.rs # 应用入口，Tauri 设置 -├── session.rs # SessionManager 会话管理器 -├── ssh.rs # SSH 客户端实现 -├── sftp.rs # SFTP 文件传输 -├── pty.rs # 本地 PTY 管理 -├── crypto.rs # AES-256-GCM 加密 -├── fuzzy.rs # 命令模糊搜索 -├── error.rs # 错误类型 -├── watcher.rs # 文件监听 -└── import.rs # 会话导入 -``` +`src/context/AppContext.tsx` 是主窗口的核心状态容器，负责： -### 核心组件 +- 工作区标签与窗格树 +- 应用设置与 UI 设置 +- 已保存连接 / 分组刷新 +- 启动时恢复 `ui.open_tabs` -#### SessionManager +### ChildAppProvider -管理所有活动会话（SSH 和本地终端）： +`src/context/ChildAppProvider.tsx` 是子窗口专用的轻量 Provider： -```rust -pub struct SessionManager { - sessions: Arc>>, - command_history: Arc>>>, - history_store: Arc>, -} -``` +- 只加载 / 保存设置 +- 通过事件与主窗口同步 +- 不管理完整的工作区标签与会话状态 -- 维护会话生命周期 -- 通过 MPSC channel 向会话发送命令（写入、调整大小、关闭） -- 缓冲终端输出直到前端连接 +### TransferContext -#### SSH 客户端 +`src/context/TransferContext.tsx` 单独管理文件传输队列，消费后端 `transfer-event` 事件，并驱动暂停、继续、取消、重试等前端行为。 -基于 `russh` 库的异步 SSH 客户端： +## 工作区模型 -- TOFU 主机密钥验证 -- 支持密码和密钥认证 -- 代理支持（SOCKS5） -- OSC 7 集成获取远程 CWD +Dragonfly 的终端工作区有两个容易混淆、但职责不同的层次： -#### SFTP 实现 +### 逻辑标签 / 窗格树 -高性能文件传输： +`src/lib/workspaceTabs.ts` 负责： -- 在现有 SSH 连接上复用通道 -- 管道化并发下载（16 并发，128 KiB 块） -- 实时传输进度事件 +- 创建标签页与会话 pane +- 标签页内横向 / 纵向分屏 +- 持久化 `ui.open_tabs` +- 启动时恢复可序列化的工作区结构 -### 事件通信 +### 运行时窗口布局 -后端通过 Tauri 事件系统向前端发送通知： +`src/lib/tabWindows.ts` 负责： + +- 不同标签当前分布在哪个 window leaf 中 +- 每个 leaf 的活动标签 +- 运行时窗口 split ratio + +可以简单理解为： + +- `workspaceTabs.ts` = “会保存下来的逻辑工作区” +- `tabWindows.ts` = “当前运行时终端区域怎么摆” + +## 终端集成 + +`src/components/terminal/XTerminal.tsx` 是 xterm.js 集成中心，负责： + +- Fit/Search/WebLinks 等 addon +- 命令历史建议与 shell integration +- 行号 / 时间戳 gutter +- 动作链接与关键词高亮 +- 大输出保护与恢复提示 +- 与 session 事件的绑定和重连处理 + +## 后端运行时模型 + +`src-tauri/src/lib.rs` 是后端入口，负责构建并注入共享状态： + +- `SessionManager` +- `TunnelManager` +- `RecordingManager` +- `PendingAuthManager` + +同时也在这里集中注册所有 Tauri commands，例如： + +- session 创建 / 关闭 / 写入 / 录制 / OTP +- SFTP 文件与传输操作 +- 连接 / 密钥 / 密码 / OTP / 设置读写 +- watcher、翻译、导入、stats、tunnel、proxy + +## SessionManager 与事件流 + +`src-tauri/src/core/session.rs` 中的 `SessionManager` 是活动会话注册中心，负责： + +- 管理所有活动会话 +- 向具体 session I/O loop 路由命令 +- 维护命令历史与模糊搜索存储 +- 发出 `sessions-changed`、`command-history-changed` 等事件 + +后端还会向前端发送这些典型事件： | 事件 | 说明 | |------|------| -| `terminal-output-{id}` | 终端输出数据 | +| `terminal-output-{id}` | 终端输出 | | `cwd-changed-{id}` | 工作目录变化 | | `session-closed-{id}` | 会话关闭 | -| `transfer-event` | SFTP 传输进度 | -| `sessions-changed` | 会话列表更新 | -| `connections-changed` | 连接配置变化 | +| `sessions-changed` | 会话列表变化 | +| `connections-changed` | 已保存连接变化 | +| `transfer-event` | 传输队列进度变化 | +| `otp-request` | 触发 OTP / keyboard-interactive 认证 | -### 配置文件 +## SSH / SFTP / watcher / 导入 -所有配置存储在 `~/.dragonfly/` 目录下： +核心后端能力主要分布在这些模块： -| 文件 | 内容 | -|------|------| -| `sessions.json` | SSH 连接和分组 | -| `keys.json` | SSH 私钥（加密存储） | -| `settings.json` | 应用设置 | -| `quick-command.json` | 快捷命令 | -| `history.json` | 命令历史 | -| `known_hosts` | SSH 主机密钥 | +- `src-tauri/src/core/ssh/` — SSH 连接、认证、OSC/CWD、SFTP、隧道 +- `src-tauri/src/core/pty.rs` — 本地终端 +- `src-tauri/src/core/telnet.rs` — Telnet +- `src-tauri/src/core/serial.rs` — 串口 +- `src-tauri/src/core/watcher.rs` — 本地文件监听与自动上传流程 +- `src-tauri/src/core/importer.rs` — Xshell / MobaXterm / WindTerm 导入 +- `src-tauri/src/core/recording.rs` — 会话录制 + +## 配置与持久化 + +应用配置保存在 `~/.dragonfly/` 下，典型文件包括： + +- `settings.json` +- `sessions.json` +- `keys.json` +- `passwords.json` +- `otp.json` +- `quick-command.json` +- `tunnels.json` +- `proxies.json` +- `history.json` +- `known_hosts` + +其中敏感值会先加密再写盘，因此前端管理的是可复用凭据条目，而不是明文配置。 diff --git a/docs-site/docs/development/backend.md b/docs-site/docs/development/backend.md index 60bbaba3..4de8b1aa 100644 --- a/docs-site/docs/development/backend.md +++ b/docs-site/docs/development/backend.md @@ -4,135 +4,162 @@ sidebar_position: 4 # 后端开发指南 -## 项目结构 +后端代码位于 `src-tauri/src/`，使用 Rust 编写，是 Dragonfly 的运行时核心：会话管理、SSH/SFTP、录制、翻译、隧道、认证、配置持久化都在这里落地。 -后端代码位于 `src-tauri/src/`，使用 Rust 编写。 +## 命令入口与模块组织 -## 添加 Tauri 命令 +后端命令注册集中在 `src-tauri/src/lib.rs`： -### 1. 定义命令函数 +- 在这里创建共享 manager 状态 +- 在这里挂载 Tauri plugin +- 在这里通过 `tauri::generate_handler![]` 注册所有 commands -在 `src-tauri/src/commands/` 中添加命令： +命令模块位于： -```rust -use tauri::State; -use crate::session::SessionManager; - -#[tauri::command] -pub async fn my_command( - session_manager: State<'_, SessionManager>, - param: String, -) -> Result { - // 实现逻辑 - Ok("result".to_string()) -} +```text +src-tauri/src/cmd/ +├── session.rs +├── sftp.rs +├── connection.rs +├── settings.rs +├── watcher.rs +├── translate.rs +├── stats.rs +├── tunnel.rs +├── proxy.rs +├── otp.rs +├── importer.rs +├── clipboard.rs +└── log.rs ``` -### 2. 注册命令 +如果你要新增一个 command，通常需要： -在 `src-tauri/src/lib.rs` 的 `invoke_handler` 中注册： +1. 在对应 `cmd/*.rs` 中定义 `#[tauri::command]` +2. 复用 `core/` 或 `config/` 层已有逻辑 +3. 回到 `src-tauri/src/lib.rs` 注册它 +4. 在前端通过 `src/lib/invoke.ts` 调用 -```rust -.invoke_handler(tauri::generate_handler![ - // ...existing commands - commands::my_command, -]) -``` +## 共享运行时状态 -### 3. 前端调用 +`src-tauri/src/lib.rs` 会把这些共享对象注入 Tauri state： -```typescript -const result = await invoke('my_command', { param: 'value' }); -``` +- `SessionManager` +- `TunnelManager` +- `RecordingManager` +- `PendingAuthManager` + +它们分别负责： + +- 活动会话生命周期与命令历史 +- SSH 隧道状态 +- 录制状态 +- keyboard-interactive / OTP 等待中的认证请求 + +## SessionManager + +`src-tauri/src/core/session.rs` 中的 `SessionManager` 是会话中心： + +- 注册 / 移除活动会话 +- 向具体 session 的 I/O loop 发送 `Write` / `Resize` / `Close` / `Attach` 命令 +- 管理命令历史与模糊搜索存储 +- 发出 `sessions-changed`、`command-history-changed` 等事件 + +它暴露给前端的会话元信息中，还包含 `injection_active`，用于标识当前会话是否支持终端路径跟踪等增强能力。 + +## 会话实现 + +具体会话类型分布在 `src-tauri/src/core/`： + +- `ssh/` — SSH 连接、认证、OSC/CWD、SFTP、隧道 +- `pty.rs` — 本地终端 +- `telnet.rs` — Telnet +- `serial.rs` — 串口 +- `recording.rs` — 会话录制 +- `watcher.rs` — 本地文件监听与自动上传 +- `importer.rs` — 外部客户端会话导入 ## SSH 模块 -### 连接流程 +`src-tauri/src/core/ssh/` 是最核心的一组模块： -1. 从配置加载连接信息 -2. 解密密码/私钥 -3. 建立 TCP 连接（可选代理） -4. TOFU 主机密钥验证 -5. 认证（密码/密钥） -6. 打开 PTY 通道 -7. 注入 OSC 7 脚本（CWD 追踪） -8. 启动异步 I/O 循环 +- `client.rs` — russh client、known_hosts 校验、代理感知连接 +- `auth.rs` — 保存认证信息加载、keyboard-interactive / OTP 流程 +- `io.rs` — 终端 I/O 与 cwd 更新事件 +- `sftp.rs` — 远程文件操作与传输队列 +- `tunnel.rs` — 本地 / 远程 / 动态隧道 +- `session.rs` — SSH session 生命周期协作 -### I/O 循环 +典型 SSH 流程是： -每个会话维护一个异步任务： +1. 读取连接配置 +2. 解密密码 / 私钥 / 凭据 +3. 建立 TCP / 代理连接 +4. 做 host key policy 校验 +5. 完成认证（可能进入 OTP / interactive 流程） +6. 打开 PTY 通道并进入异步 I/O 循环 +7. 在支持时注入 OSC/CWD 跟踪能力 -```rust -tokio::spawn(async move { - loop { - tokio::select! { - cmd = cmd_rx.recv() => { - // 处理前端命令：Write, Resize, Close, Attach - } - msg = channel.wait() => { - // 处理 SSH 数据：Data, ExtendedData, Eof - } - } - } -}); -``` +## SFTP 与传输队列 -## SFTP 模块 +`src-tauri/src/core/ssh/sftp.rs` 负责： -### 传输优化 +- 列目录 +- 下载 / 上传单文件与目录 +- 删除 / 重命名 / 新建文件夹 / 符号链接 / 属性读取 +- 传输队列控制（pause / resume / cancel） +- 向前端发出 `transfer-event` -下载使用管道化并发读取： +前端传输面板与 `TransferContext` 就是基于这些事件构建的。 -- 16 个并发文件句柄 -- 每块 128 KiB -- ~1 MiB 飞行中缓冲区 -- 已知大小文件使用滑动窗口 -- 未知大小文件（如 `/proc`）使用顺序读取 +## watcher 与自动上传 -### 目录操作 +`src-tauri/src/core/watcher.rs` 负责本地文件监听。 -递归删除时采用容错策略，部分失败不影响其他文件的删除。 +典型流程： -## 加密模块 +1. 前端从远程文件浏览器中“打开”远程文件 +2. 后端下载到本地临时目录并开始 watch +3. 本地文件保存后，发出 `file-modified` 事件 +4. 前端决定弹出自动上传窗口，或按“始终上传”策略直接回传 -使用 AES-256-GCM 加密敏感数据： +这条链路涉及： -```rust -// 加密 -let encrypted = encrypt_string("plaintext", &key)?; +- `cmd/watcher.rs` +- `core/watcher.rs` +- 前端 `FileUploadPage.tsx` -// 解密 -let decrypted = decrypt_string(&encrypted, &key)?; -``` +## 配置与加密 -密钥来源： -- 使用系统密钥链时，从 OS Keyring 获取 -- 使用主密码时，从密码派生 +配置文件保存在 `~/.dragonfly/`，主要由 `src-tauri/src/config/` 管理。 -## 配置管理 +常见文件包括： -配置文件使用 JSON 格式，位于 `~/.dragonfly/`： +- `settings.json` +- `sessions.json` +- `keys.json` +- `passwords.json` +- `otp.json` +- `quick-command.json` +- `tunnels.json` +- `proxies.json` +- `history.json` +- `known_hosts` -```rust -// 读取配置 -let config = SessionConfig::load()?; +敏感字段会在写盘前加密，因此新增配置时要确认是否属于敏感数据边界。 -// 保存配置 -config.save()?; -``` +## 事件模型 -配置文件变更会触发 `connections-changed` 事件通知前端。 +后端大量依赖 Tauri 事件通知前端，典型事件包括： -## 日志 +| 事件 | 说明 | +|------|------| +| `terminal-output-{id}` | 终端输出 | +| `cwd-changed-{id}` | 工作目录变化 | +| `session-closed-{id}` | 会话关闭 | +| `sessions-changed` | 会话列表变化 | +| `connections-changed` | 已保存连接变化 | +| `transfer-event` | 传输进度 | +| `otp-request` | 触发 OTP / keyboard-interactive 认证 | -使用 `tracing` 库记录日志： - -```rust -use tracing::{info, warn, error, debug}; - -info!("Session created: {}", session_id); -warn!("Connection timeout for: {}", host); -error!("SSH error: {:?}", err); -``` - -日志文件位于应用日志目录，每日轮转，保留 7 天。 +设计新后端能力时，优先考虑是否应该通过已有事件流对前端暴露，而不是额外引入新的轮询接口。 diff --git a/docs-site/docs/development/frontend.md b/docs-site/docs/development/frontend.md index 94793a4a..bc4aaf50 100644 --- a/docs-site/docs/development/frontend.md +++ b/docs-site/docs/development/frontend.md @@ -4,138 +4,151 @@ sidebar_position: 3 # 前端开发指南 -## 项目结构 +前端代码位于 `src/`，使用 React 19 + TypeScript。 -前端代码位于 `src/` 目录，使用 React 19 + TypeScript。 +## 入口与窗口模型 -## 组件开发 +前端入口在 `src/main.tsx`，它会根据 URL 中的 `?window=` 参数决定加载哪套应用： -### UI 组件库 +- **主窗口**：`AppProvider` + `App.tsx` +- **子窗口**：`ChildAppProvider` + `ChildWindowRouter` -项目使用 [shadcn/ui](https://ui.shadcn.com/) 作为基础组件库： +当前子窗口包括： -- 组件位于 `src/components/ui/` -- 基于 Radix UI 原语构建 -- 使用 TailwindCSS 样式 +- settings +- new-session +- quick-command +- auto-upload -### 添加新组件 +如果你要修改这些流程，优先查看： -使用 shadcn CLI 添加组件： +- `src/main.tsx` +- `src/ChildWindowRouter.tsx` +- `src/lib/windowManager.ts` -```bash -npx shadcn@latest add button -``` +## 组件与目录结构 -### 图标 - -使用 [Lucide React](https://lucide.dev/) 图标库： - -```tsx -import { Terminal } from 'lucide-react'; - - +```text +src/ +├── components/ # UI 组件 +│ ├── dialog/ # 对话框与子窗口相关组件 +│ ├── panel/ # 左右侧栏 / 底部区域面板 +│ ├── terminal/ # xterm 工作区与终端相关组件 +│ ├── layout/ # 外层布局、标题栏、活动栏 +│ └── ui/ # 基础 UI 组件（shadcn/ui） +├── context/ # React Context providers +├── hooks/ # 自定义 hooks +├── i18n/ # 国际化 +├── lib/ # invoke、window 管理、工作区模型等工具 +├── pages/ # 子窗口页面 +├── types/ # 类型定义 +├── App.tsx # 主应用壳层 +└── main.tsx # 前端入口 ``` ## 状态管理 ### AppContext -应用核心状态，包括： +`src/context/AppContext.tsx` 是主窗口核心状态容器，管理： -- 活动会话列表 -- 已保存的连接 -- 当前活动标签 -- 设置配置 +- 标签页与 pane 树 +- 活动 tab / pane +- 已保存连接 / 分组刷新 +- 应用设置与 UI 设置 +- 启动恢复工作区 -### ThemeContext +### ChildAppProvider -主题相关状态： +`src/context/ChildAppProvider.tsx` 是子窗口用的轻量 Provider： -- 当前主题（深色/浅色） -- 终端主题配色方案 -- 字体配置 +- 只加载 / 保存设置 +- 不持有完整工作区状态 +- 通过事件向主窗口同步设置变化 ### TransferContext -文件传输状态： +`src/context/TransferContext.tsx` 监听 `transfer-event`，集中维护： -- 传输队列 -- 传输进度 -- 完成/错误状态 +- 传输队列列表 +- 进度 / 暂停 / 取消 / 错误状态 +- pause / resume / cancel / retry 操作 ## 调用 Tauri 命令 -通过 `@tauri-apps/api` 调用后端命令： +前端应优先通过 `src/lib/invoke.ts` 中的统一包装调用后端，而不是直接到处散写 `@tauri-apps/api/core` 的 `invoke()`。 -```typescript -import { invoke } from '@tauri-apps/api/core'; +```ts +import { invoke } from '@/lib/invoke'; -// 创建 SSH 会话 const sessionId = await invoke('create_ssh_session', { - connectionId: 'uuid-here' -}); - -// 列出远程目录 -const files = await invoke('list_remote_dir', { - sessionId: 'session-id', - path: '/home/user' + connectionId: 'uuid-here', }); ``` -## 监听事件 +这个包装会统一做错误日志记录，也便于以后集中调整调用行为。 -监听后端发送的事件： +## 监听后端事件 -```typescript -import { listen } from '@tauri-apps/api/event'; +前端大量能力依赖 Tauri 事件系统，例如： -// 监听终端输出 -const unlisten = await listen(`terminal-output-${sessionId}`, (event) => { - terminal.write(event.payload); -}); +- `terminal-output-{id}` +- `cwd-changed-{id}` +- `session-closed-{id}` +- `transfer-event` +- `sessions-changed` +- `connections-changed` +- `otp-request` -// 清理监听 -unlisten(); -``` +终端、文件浏览器、资源监控、传输队列等功能都建立在这些事件之上。 -## 国际化 +## 工作区模型 -### 添加翻译 +工作区有两层模型： -在 `src/i18n/locales/` 下的 JSON 文件中添加键值对。 +### `workspaceTabs.ts` -### 使用翻译 +负责“会保存下来的逻辑工作区”： -```tsx -import { useTranslation } from 'react-i18next'; +- 标签页 +- pane 树 +- 标签页内分屏 +- `ui.open_tabs` 序列化 / 恢复 -function MyComponent() { - const { t } = useTranslation(); - return {t('menu.file')}; -} -``` +### `tabWindows.ts` + +负责“运行时终端布局”： + +- 哪些标签当前挂在哪个 leaf +- 每个 leaf 当前的 active tab +- 运行时 split ratio + +修改标签 / 分屏 / 多区域终端布局时，先判断你碰的是哪一层。 ## 终端集成 -终端使用 xterm.js，关键配置： +`src/components/terminal/XTerminal.tsx` 是 xterm.js 集成核心，负责： -- **WebGL 插件** — GPU 加速渲染 -- **Fit 插件** — 自适应容器大小 -- **Search 插件** — 文本搜索 -- **Web Links 插件** — URL 点击 +- Search / Fit / WebLinks addon +- shell integration 与命令建议 +- gutter（行号 / 时间戳） +- 动作链接与关键词高亮 +- 大输出保护 +- 会话重连相关行为 -```typescript -import { Terminal } from '@xterm/xterm'; -import { FitAddon } from '@xterm/addon-fit'; -import { WebglAddon } from '@xterm/addon-webgl'; +如果你改的是终端表现层，这通常是第一落点。 -const terminal = new Terminal({ - fontFamily: 'JetBrains Mono, monospace', - fontSize: 16, - cursorBlink: true, -}); +## 国际化 -const fitAddon = new FitAddon(); -terminal.loadAddon(fitAddon); -terminal.loadAddon(new WebglAddon()); -``` +界面文案使用 `react-i18next`，语言包位于： + +- `src/i18n/locales/zh-CN.json` +- `src/i18n/locales/en.json` + +新增或修改用户可见文本时，应同时更新两个 locale 文件。 + +## UI 组件约定 + +项目使用 shadcn/ui 作为基础组件层，共享组件位于 `src/components/ui/`。 + +如果需要新增通用 UI，优先复用现有组件与项目里的样式模式，而不是单独造一套新的基础组件。 diff --git a/docs-site/docs/getting-started/installation.md b/docs-site/docs/getting-started/installation.md index 51f022c3..1b4d2c5c 100644 --- a/docs-site/docs/getting-started/installation.md +++ b/docs-site/docs/getting-started/installation.md @@ -10,7 +10,7 @@ Dragonfly 支持以下操作系统： - **Windows** 10/11 (64-bit) - **macOS** 12+ (Intel & Apple Silicon) -- **Linux** (Ubuntu 20.04+, Fedora 36+, Arch Linux 等) +- **Linux**（Ubuntu 20.04+、Fedora 36+、Arch Linux 等） ## 下载安装 @@ -28,12 +28,29 @@ Dragonfly 支持以下操作系统： 如果你想从源码构建，请参考 [开发环境搭建](../development/setup) 章节。 -## 首次启动 +## 首次启动后会看到什么 -安装完成后启动 Dragonfly，你会看到一个干净的界面，包含： +安装完成后启动 Dragonfly，主窗口通常会由这些区域组成： -- **左侧边栏** — 已保存的连接列表 -- **中央区域** — 终端标签页 -- **右侧边栏** — 文件浏览器和快捷命令 +- **顶部菜单与窗口栏** — File / View / Help、窗口控制与应用级入口 +- **中央工作区** — 终端标签页，以及标签内横向 / 纵向分屏 +- **左侧活动栏与面板** — 文件浏览器、网络、Security/Auth 等能力入口 +- **右侧活动栏与面板** — 已保存连接、活动会话、命令历史、资源监控等运行态信息 +- **底部辅助区** — 快捷命令、串口发送、录制、锁屏等辅助操作 -接下来，请查看 [快速开始](./quick-start) 了解如何创建你的第一个 SSH 连接。 +某些流程会打开独立子窗口，而不是打断主工作区，例如： + +- 设置 +- 新建连接 +- 快捷命令编辑 +- 自动上传提示 + +## 第一次体验建议 + +如果你是第一次使用，建议按这个顺序体验： + +1. 打开 [快速开始](./quick-start) +2. 创建一个 **SSH** 连接 +3. 再创建一个 **本地终端**，体验混合工作区 +4. 在 SSH 会话里打开文件浏览器和传输面板 +5. 试试命令历史、快捷命令和终端搜索 diff --git a/docs-site/docs/getting-started/quick-start.md b/docs-site/docs/getting-started/quick-start.md index 582ee2be..5549bdaa 100644 --- a/docs-site/docs/getting-started/quick-start.md +++ b/docs-site/docs/getting-started/quick-start.md @@ -41,7 +41,7 @@ sidebar_position: 2 连接建立后，你会看到： -- **中央区域** — 当前终端标签页 +- **中央区域** — 当前终端标签页与分屏窗格 - **左侧活动栏** — 文件浏览器、网络、Security/Auth 等面板入口 - **右侧活动栏** — 已保存连接、活动会话、命令历史、资源监控等入口 - **底部区域** — 快捷命令、串口发送、录制、锁屏等辅助区域 @@ -61,16 +61,26 @@ sidebar_position: 2 这适合同时观察日志、执行命令和对照不同主机输出。 -### 3. 打开远程文件浏览器 +### 3. 打开远程文件浏览器和传输队列 SSH 会话激活后，文件浏览器面板可直接浏览远程目录，并支持上传、下载、删除、移动、属性查看等操作。 +如果你发起上传或下载，传输面板会显示队列进度，并支持暂停、继续、取消和失败重试。 + ### 4. 打开命令历史和快捷命令 - **命令历史** 适合回溯与模糊检索 -- **快捷命令** 适合保存固定操作，并支持变量输入 +- **快捷命令** 适合保存固定操作，并支持变量输入、分类和执行模式 -### 5. 启用终端增强项 +### 5. 试一次终端搜索 / 在线搜索 / 翻译 + +在终端中选中文本后，可以通过右键菜单： + +- **查找** 当前输出 +- 用自定义搜索引擎做**在线搜索** +- 按已启用的翻译 provider 做**翻译** + +### 6. 启用终端增强项 可在 **设置 → 终端** 中按需打开： diff --git a/docs-site/docs/guide/file-transfer.md b/docs-site/docs/guide/file-transfer.md index ed3cecab..98f0b5b0 100644 --- a/docs-site/docs/guide/file-transfer.md +++ b/docs-site/docs/guide/file-transfer.md @@ -60,16 +60,36 @@ Dragonfly 的远程文件能力建立在 SSH 会话之上。也就是说，**文 Dragonfly 会把上传 / 下载任务统一放进传输队列中，便于你查看： - 当前进度 -- 成功与失败状态 +- 成功、暂停、取消与失败状态 - 同时进行中的任务 +- 当前下载目录 -在设置中还可以按需调整传输相关策略，例如： +单个传输项支持： + +- **暂停** +- **继续** +- **取消** +- **失败后重试** +- **完成后从列表移除** + +面板顶部还提供批量操作： + +- **全部暂停** +- **全部继续** +- **全部取消** +- **清理已完成项** + +在 **设置 → 传输** 中还可以按需调整： - 上传 / 下载线程数 - 冲突时的处理策略 +- 最大重试次数 +- 传输缓冲区大小 - 是否保留时间戳 - 是否继续断点传输 +- 默认文件权限 - 默认下载路径 +- 是否每次询问保存位置 - 默认打开远程文件所使用的本地编辑器 ## 与终端路径同步 @@ -83,7 +103,7 @@ Dragonfly 会把上传 / 下载任务统一放进传输队列中，便于你查 ## 本地编辑后自动回传 -这是 Dragonfly 很适合文档截图和真实运维场景的一项能力。 +这是 Dragonfly 很适合真实运维场景的一项能力。 ### 工作方式 diff --git a/docs-site/docs/guide/keyboard-shortcuts.md b/docs-site/docs/guide/keyboard-shortcuts.md index 5a1179f0..c6bce75f 100644 --- a/docs-site/docs/guide/keyboard-shortcuts.md +++ b/docs-site/docs/guide/keyboard-shortcuts.md @@ -36,7 +36,8 @@ Dragonfly 的快捷键分成两类理解最不容易混淆： | `Ctrl / Cmd + Shift + W` | 关闭当前标签 | | `Ctrl + Tab` | 切换到下一个标签 | | `Ctrl + Shift + Tab` | 切换到上一个标签 | -| `Ctrl / Cmd + 1-9` | 跳转到指定标签 | +| `Ctrl / Cmd + 1-8` | 跳转到指定标签 | +| `Ctrl / Cmd + 9` | 跳转到最后一个标签 | ## 视图与面板 @@ -44,8 +45,8 @@ Dragonfly 的快捷键分成两类理解最不容易混淆： |--------|------| | `Ctrl / Cmd + Shift + E` | 切换左侧活动栏 / 面板 | | `Ctrl / Cmd + Shift + B` | 切换右侧活动栏 / 面板 | -| `Ctrl / Cmd + =` | 放大界面 | -| `Ctrl / Cmd + -` | 缩小界面 | +| `Ctrl / Cmd + =` | 放大 | +| `Ctrl / Cmd + -` | 缩小 | | `Ctrl / Cmd + 0` | 重置缩放 | ## 特殊功能 diff --git a/docs-site/docs/guide/quick-commands.md b/docs-site/docs/guide/quick-commands.md index f9afd70e..21d407ae 100644 --- a/docs-site/docs/guide/quick-commands.md +++ b/docs-site/docs/guide/quick-commands.md @@ -4,50 +4,91 @@ sidebar_position: 4 # 快捷命令 -快捷命令功能让你可以保存和一键执行常用命令，大幅提升运维效率。 +快捷命令功能让你可以把常用命令保存成可复用动作，在工作区里快速发送到当前终端。 + +## 适合哪些场景 + +- 高频执行固定运维命令 +- 保存带参数模板的部署 / 排障脚本 +- 把常见命令按产品、环境或团队分类 +- 把危险命令先放到输入行检查，再决定是否执行 ## 创建快捷命令 -1. 在右侧边栏的 **快捷命令** 面板中点击 **添加** -2. 填写以下信息： +1. 打开底部或侧边的 **快捷命令** 区域 +2. 点击 **添加** +3. 在独立子窗口中填写命令信息 + +可配置字段包括： | 字段 | 说明 | |------|------| | 标签名称 | 命令的显示名称 | -| 分类 | 命令所属分类（如 K8s、Docker 等） | -| 描述 | 命令的说明（可选） | +| 分类 | 命令所属分类 | +| 描述 | 命令说明（可选） | | 颜色标签 | 自定义显示颜色 | | 图标 | 自定义图标 | -| 置顶显示 | 是否在列表顶部显示 | +| 置顶显示 | 是否优先显示在列表顶部 | | 执行模式 | 立即执行或追加到输入行 | -| 命令脚本 | 要执行的命令内容 | +| 命令脚本 | 要发送到终端的命令内容 | + +保存后，命令会出现在快捷命令列表中，可继续编辑或删除。 ## 执行模式 ### 立即执行 -点击命令后自动在终端中回车执行，适合确认无误的常用命令。 +点击命令后会直接发送到当前终端并执行，适合： + +- 确认无误的常用命令 +- 日常巡检 +- 固定格式的只读查询 ### 追加到输入行 -点击后将命令放置到终端输入行供检查，不会立即执行。适合需要确认或修改参数的命令。 +点击后只把命令放到当前输入行，不会自动回车，适合： -## 变量替换 +- 还要再检查参数的命令 +- 可能需要二次修改的脚本片段 +- 有一定风险、希望人工确认的操作 -命令脚本支持 `{{变量名}}` 语法注入动态参数： +## 变量提示 + +命令脚本支持 `{{变量名}}` 语法注入动态参数，例如： ```bash docker exec -it {{容器名}} bash ``` -执行时会弹出对话框让你填写变量值。 +执行时会弹出变量填写对话框，让你把模板命令补全后再发送。 -## 分类管理 +## 分类、搜索与置顶 -- 创建分类对命令进行归类 -- 在搜索栏旁可按分类筛选 -- 支持搜索或创建新分类 +快捷命令面板支持这些管理方式： -## 搜索命令 +- 通过搜索框按标签、命令内容或描述过滤 +- 通过分类下拉框只看某一类命令 +- 置顶命令优先显示在列表顶部 +- 已保存分类会被复用，新命令也可以继续补充分类 -在搜索框中输入关键词，可以快速筛选命令列表。 +这让它很适合管理诸如： + +- K8s +- Docker +- 数据库 +- 发布脚本 +- 环境巡检 + +## 与工作区配合的使用方式 + +快捷命令并不绑定某一类会话。只要当前终端可接收输入，你就可以把命令发送到： + +- SSH 会话 +- 本地终端 +- 某些需要批量发指令的串口场景 + +常见搭配方式： + +- 左边看日志，右边通过快捷命令触发诊断脚本 +- 远程 SSH 执行部署命令，本地终端同时做构建或 Git 操作 +- 把变量化命令做成团队共享模板，减少人工拼写错误 diff --git a/docs-site/docs/guide/security.md b/docs-site/docs/guide/security.md index 5dbfa8c5..ec77748c 100644 --- a/docs-site/docs/guide/security.md +++ b/docs-site/docs/guide/security.md @@ -18,6 +18,7 @@ Dragonfly 会在本地保存连接相关配置，并对敏感内容做加密处 - SSH 私钥与私钥口令 - OTP 密钥 - 主密码本身的持久化表示 +- 代理或其他需要保护的认证材料 因此，平时使用时你看到的是“可以复用的密码 / 私钥 / OTP 条目”，而不是明文直接散落在普通文本配置里。 diff --git a/docs-site/docs/guide/terminal.md b/docs-site/docs/guide/terminal.md index b5046676..4fa07af4 100644 --- a/docs-site/docs/guide/terminal.md +++ b/docs-site/docs/guide/terminal.md @@ -16,7 +16,7 @@ Dragonfly 的终端体验围绕“在同一个工作区里高频处理远程与 - 粘贴选中的文本 - 查找文本 - 在线搜索选中文本 -- 翻译选中文本 +- 按 provider 翻译选中文本 - 清屏 / 全部清除 - 全选 @@ -29,7 +29,7 @@ Dragonfly 的终端体验围绕“在同一个工作区里高频处理远程与 ### 回滚缓冲区与字体 -- 回滚缓冲区默认保留 **10000 行**输出 +- 回滚缓冲区默认保留 **10000 行** 输出 - 可自定义字体族、字号、连字、光标样式与闪烁 - **硬件加速**为可选项，默认并未开启；如果你希望对比渲染效果，可在 **设置 → 终端** 中手动切换 @@ -72,7 +72,7 @@ Dragonfly 会为会话工作流提供两类辅助： - 需要先在 **设置 → 终端** 中开启 **动作链接** - 打开链接时需要使用 **Ctrl / Cmd + 点击**，避免和普通选中操作冲突 -- 具体匹配器可以单独启用或关闭 +- 三类 matcher 可以分别启用或关闭 ### 关键词高亮 @@ -92,6 +92,12 @@ Dragonfly 会为会话工作流提供两类辅助： - 每行填写一个匹配模式 - 可选择是否跨折行继续匹配 +### 大输出保护 + +当某个会话输出量过大时，Dragonfly 会临时进入保护模式，优先保证终端可交互性。 + +在这个阶段，应用会暂时抑制部分高开销装饰能力，并提示已经跳过的排队字符数；待输出压力回落后再恢复正常显示。这个机制主要用于日志洪峰或持续刷屏的场景。 + ## SSH 相关辅助能力 ### Keep-Alive @@ -119,6 +125,18 @@ Dragonfly 会为会话工作流提供两类辅助： - 内存使用情况 - 网络吞吐速率 +## 翻译与在线搜索 + +在终端中选中文本后，你可以直接通过右键菜单： + +- 使用自定义搜索引擎做在线搜索 +- 使用已启用的翻译 provider 打开翻译对话框 + +翻译 provider 的可见性取决于设置： + +- **Google**、**Microsoft** 无需额外配置 +- **DeepL / 百度 / 阿里 / 有道** 需要先在 **设置 → 翻译** 中填写凭据 + ## 录制与工作流配合 Dragonfly 支持会话录制，适合： diff --git a/docs-site/docs/guide/themes.md b/docs-site/docs/guide/themes.md index 92d1996b..a1c1ec4e 100644 --- a/docs-site/docs/guide/themes.md +++ b/docs-site/docs/guide/themes.md @@ -4,47 +4,71 @@ sidebar_position: 5 # 主题与外观 -Dragonfly 支持高度可定制的界面外观。 +Dragonfly 支持对工作区外观做细粒度调整，包括 UI 主题、终端主题、字体和光标样式。 -## 主题切换 +## UI 主题与终端主题 -在 **设置 → 外观 → 主题** 中选择颜色主题。支持深色和浅色模式。 +在 **设置 → 外观** 中，你可以分别配置： -也可以通过菜单 **视图 → 主题** 快速切换。 +- **界面主题** — 控制应用整体配色 +- **终端主题** — 控制终端区域配色；也可以选择跟随 UI 主题 -## 界面缩放 +如果你只是想快速切换主题，也可以使用顶部菜单中的 **View → Theme**。 -- **放大** — `Ctrl++` 或菜单 **视图 → 放大** -- **缩小** — `Ctrl+-` 或菜单 **视图 → 缩小** -- **重置** — `Ctrl+0` 或菜单 **视图 → 重置缩放** +## 字体与字号 -## 面板布局 +在 **设置 → 外观** 中可以调整： -界面采用三栏布局，每个面板都可以调整大小： +- **字体族** — 支持主字体 + 多级回退字体 +- **终端字体大小** +- **界面字体大小** -- **左侧边栏** — 已保存的连接、活动会话、命令历史 -- **中央区域** — 终端标签页 -- **右侧边栏** — 文件浏览器、文件传输、快捷命令 +Dragonfly 内置了这些常用字体： -可通过菜单 **视图 → 重置面板布局** 恢复默认布局。 +- `JetBrains Mono` +- `Noto Sans SC Variable` +- `Inter` -## 全屏模式 +同时也会读取系统已安装字体，供你加入字体回退链路。 -按 `F11` 或通过菜单 **视图 → 全屏** 进入全屏模式。 +## 光标与连字 -## 语言设置 +外观设置还支持这些终端细节： -在 **设置 → 外观 → 语言** 中切换界面语言，目前支持： +- **光标样式**：Block / Underline / Bar +- **光标闪烁** +- **字体连字** + +如果你经常在深浅主题之间切换，建议把终端主题和 UI 主题一起调整后再观察关键字高亮、动作链接等终端装饰效果。 + +## 语言切换 + +Dragonfly 当前提供： - 简体中文 - English -## 字体配置 +你可以通过两种方式切换： -在 **设置 → 外观** 中配置字体： +- **设置 → 通用 → 语言** +- 顶部菜单 **View → Language** -- **字体系列** — 选择终端和 UI 字体，支持多级回退 -- **终端字体大小** — 终端文字大小（像素） -- **界面字体大小** — UI 文字大小（像素） +## 面板与工作区外观 -内置字体包括 JetBrains Mono 和 Noto Sans SC，也会列出系统上已安装的字体供选择。 +除了配色与字体，工作区本身也支持按使用习惯调整： + +- 左右侧面板宽度可拖动调整 +- 标签内分屏比例可拖动调整 +- 左右活动栏可通过快捷键快速显示 / 隐藏 + +这些布局状态会跟随应用设置一起保存，适合按你自己的终端工作流长期固定下来。 + +## 缩放与快捷操作 + +应用提供这些常见快捷键： + +- **放大** — `Ctrl / Cmd + =` +- **缩小** — `Ctrl / Cmd + -` +- **重置** — `Ctrl / Cmd + 0` + +这些入口适合在演示、投屏或高分屏环境下快速调整可读性。 diff --git a/docs-site/docs/guide/translation.md b/docs-site/docs/guide/translation.md index 11272df8..38d5fe01 100644 --- a/docs-site/docs/guide/translation.md +++ b/docs-site/docs/guide/translation.md @@ -4,31 +4,54 @@ sidebar_position: 6 # 翻译功能 -Dragonfly 内置了多引擎文本翻译功能，方便在终端中快速翻译不熟悉的文本。 +Dragonfly 内置了多引擎文本翻译功能，适合在终端里快速翻译日志、报错、命令说明或临时看到的外语文本。 ## 使用方式 1. 在终端中选中要翻译的文本 -2. 右键选择 **翻译** -3. 翻译结果会在弹出窗口中显示 +2. 右键打开上下文菜单 +3. 在 **翻译** 子菜单中选择一个可用 provider +4. 翻译结果会在弹出对话框中显示 -## 支持的翻译引擎 +对话框中会展示： -| 引擎 | 是否需要配置 | -|------|-------------| -| Google 翻译 | 无需配置 | -| Microsoft 翻译 | 无需配置 | -| DeepL | 需要 API Key | -| 百度翻译 | 需要 App ID + App Key | -| 阿里翻译 | 需要 App ID + App Key | -| 有道翻译 | 需要 App ID + App Key | +- 原文 +- 翻译结果 +- 检测到的源语言（如果 provider 返回） +- 一键复制翻译结果 -## 配置翻译服务 +## Provider 显示规则 -在 **设置 → 翻译** 中配置： +终端右键菜单里并不是所有 provider 都会一直显示。 -- **翻译提供商** — 选择默认使用的翻译引擎 -- **目标语言** — 设置翻译的目标语言 -- **API 凭据** — 为需要密钥的引擎填写 API 凭据 +### 开箱即用 -Google 和 Microsoft 翻译开箱即用，无需额外配置。 +以下 provider 无需额外配置： + +- **Google** +- **Microsoft** + +### 需要凭据后才显示 + +以下 provider 只有在 **设置 → 翻译** 中填写了凭据后，才会出现在右键菜单里： + +- **DeepL** +- **百度翻译** +- **阿里翻译** +- **有道翻译** + +## 翻译设置 + +在 **设置 → 翻译** 中，你可以配置： + +- **目标语言** +- 各 provider 对应的 **API 凭据** + +需要注意的是：当前设置页主要负责目标语言和凭据管理，而不是指定“唯一默认 provider”。真正发起翻译时，仍然是你在终端右键菜单中选择具体 provider。 + +## 适合的使用场景 + +- 快速理解英文报错或第三方日志 +- 查阅混合语言输出中的重点信息 +- 对照翻译运维脚本说明或配置注释 +- 在排障时把某段输出直接翻译后转发给同事 diff --git a/docs-site/docs/intro.md b/docs-site/docs/intro.md index 4af3e515..7b342529 100644 --- a/docs-site/docs/intro.md +++ b/docs-site/docs/intro.md @@ -31,29 +31,31 @@ Dragonfly 不只支持 SSH，还支持： - 多标签页管理多个会话 - 标签页内支持**横向/纵向分屏** - 左右活动栏可放置文件浏览器、网络、Security/Auth、会话列表、命令历史、资源监控等面板 +- 底部辅助区可承载快捷命令、串口发送、录制与锁屏入口 - 设置、新建连接、快捷命令、自动上传提示均使用独立子窗口，减少主工作区干扰 ### 面向终端操作的增强 - 命令历史与模糊建议 - 终端搜索、复制/粘贴、上下文菜单 +- 选中文本后可直接做**在线搜索**或按 provider **翻译** - 可选的**行号 / 时间戳 gutter** - 可选的**动作链接**（如 IPv4、`host:port`、压缩包文件名） - 可选的**关键词高亮**与自定义规则 -- 会话录制与 SSH Keep-Alive +- 大输出场景下的保护机制、会话录制与 SSH Keep-Alive -### 远程文件与自动回传 +### 远程文件与传输队列 - SSH 会话下内置 SFTP 文件浏览器 -- 上传、下载、重命名、移动、删除、属性查看 -- 传输队列、失败重试、断点续传、时间戳保留 +- 上传、下载、重命名、移动、删除、属性查看、新建符号链接 +- 传输队列支持暂停、继续、取消、失败重试、断点续传、时间戳保留 - 在本地编辑下载的远程文件后，可通过 watcher 流程快速上传回远端 ### 安全与网络能力 - 私钥、密码、主机密钥策略、本地加密存储 - OTP 管理（TOTP / HOTP）、二维码导入、SSH 自动填充 -- 代理配置、跳板机、端口隧道 +- 代理配置、跳板机、本地 / 远程 / 动态隧道 - 锁屏与主密码能力 ## 文档导航建议 diff --git a/docs-site/i18n/en/docusaurus-plugin-content-docs/current/development/architecture.md b/docs-site/i18n/en/docusaurus-plugin-content-docs/current/development/architecture.md index 68741370..128a6097 100644 --- a/docs-site/i18n/en/docusaurus-plugin-content-docs/current/development/architecture.md +++ b/docs-site/i18n/en/docusaurus-plugin-content-docs/current/development/architecture.md @@ -4,139 +4,172 @@ sidebar_position: 1 # Architecture -Dragonfly uses a Tauri 2 architecture with separated frontend and backend communicating via IPC. +Dragonfly is a **Tauri 2** desktop application. The frontend lives in `src/`, the backend lives in `src-tauri/src/`, and they communicate through Tauri commands and events. -## Overall Architecture +## Overall architecture -``` -┌─────────────────────────────────────┐ -│ Frontend (React) │ -│ ┌──────┐ ┌──────┐ ┌─────────────┐ │ -│ │ Term │ │ File │ │ Connection │ │ -│ │ Panel│ │ Expl │ │ Manager │ │ -│ └──┬───┘ └──┬───┘ └──────┬──────┘ │ -│ └────────┴────────────┘ │ -│ │ Tauri invoke │ -├──────────────┼──────────────────────┤ -│ │ IPC Bridge │ -├──────────────┼──────────────────────┤ -│ Backend (Rust) │ -│ ┌──────────┐ ┌──────┐ ┌────────┐ │ -│ │ Session │ │ SSH │ │ Config │ │ -│ │ Manager │ │ SFTP │ │ Store │ │ -│ └──────────┘ └──────┘ └────────┘ │ -└─────────────────────────────────────┘ +```text +┌─────────────────────────────────────────────────────────┐ +│ Frontend (React / TypeScript) │ +│ ├─ Main window: AppProvider + App.tsx │ +│ ├─ Child windows: ChildAppProvider + ChildWindowRouter│ +│ ├─ Terminal workspace, side panels, dialogs │ +│ └─ invoke wrapper + Tauri event listeners │ +├─────────────────────────────────────────────────────────┤ +│ Tauri IPC bridge │ +├─────────────────────────────────────────────────────────┤ +│ Backend (Rust) │ +│ ├─ SessionManager / TunnelManager / RecordingManager │ +│ ├─ PendingAuthManager │ +│ ├─ SSH / SFTP / watcher / importer / stats │ +│ └─ JSON config + encrypted credential storage │ +└─────────────────────────────────────────────────────────┘ ``` -## Frontend Architecture +## Frontend window model -### Tech Stack +The frontend entry path is selected in `src/main.tsx`: -- **React 19** — UI framework -- **TypeScript** — Type safety -- **Vite** — Build tool -- **TailwindCSS 4** — Styling -- **xterm.js** — Terminal emulator +- **Main window** — loads `AppProvider` and `App.tsx` +- **Child windows** — load `ChildAppProvider` and `ChildWindowRouter` -### Directory Structure +Current child-window flows include: -``` -src/ -├── components/ # UI components -│ ├── dialogs/ # Dialog components -│ ├── panels/ # Panel components (sidebars, file explorer) -│ ├── layout/ # Layout components -│ └── ui/ # Base UI components (shadcn/ui) -├── context/ # React Context providers -│ ├── AppContext.tsx # Global application state -│ ├── ThemeContext.tsx # Theme management -│ └── TransferContext.tsx # File transfer state -├── hooks/ # Custom Hooks -├── i18n/ # Internationalization -├── lib/ # Utilities -├── pages/ # Child window pages -├── types/ # TypeScript type definitions -├── App.tsx # Main application component -└── main.tsx # Entry point -``` +- Settings +- New session +- Quick command editing +- Auto-upload prompts -### State Management +Relevant files: -React Context for global state: +- `src/main.tsx` +- `src/ChildWindowRouter.tsx` +- `src/lib/windowManager.ts` -- **AppContext** — Session list, connection configs, active tab -- **ThemeContext** — Theme configuration and switching -- **TransferContext** — File transfer queue and progress +`windowManager.ts` also coordinates focus and interactivity between modal child windows and the main window. -## Backend Architecture +## Frontend state model -### Module Organization +### AppContext -``` -src-tauri/src/ -├── commands/ # Tauri command handlers -│ ├── session_cmds.rs # Session management -│ ├── sftp_cmds.rs # SFTP file operations -│ ├── config_cmds.rs # Configuration read/write -│ ├── settings_cmds.rs # Settings management -│ └── stats.rs # System info -├── config/ # Configuration management -├── translate/ # Translation services -├── lib.rs # App entry, Tauri setup -├── session.rs # SessionManager -├── ssh.rs # SSH client -├── sftp.rs # SFTP file transfer -├── pty.rs # Local PTY management -├── crypto.rs # AES-256-GCM encryption -├── fuzzy.rs # Command fuzzy search -├── error.rs # Error types -├── watcher.rs # File watching -└── import.rs # Session import -``` +`src/context/AppContext.tsx` is the main state container for the primary window. It owns: -### Core Components +- Workspace tabs and pane trees +- Application settings and UI settings +- Saved connections and group refreshes +- Startup restoration for `ui.open_tabs` -#### SessionManager +### ChildAppProvider -Manages all active sessions (SSH and local terminals) with a shared HashMap, MPSC channels for commands, and buffered output for late-joining frontends. +`src/context/ChildAppProvider.tsx` is a lightweight provider used by child windows: -#### SSH Client +- Loads and saves settings only +- Syncs with the main window through events +- Does not manage the full workspace or active session state -Async SSH client based on `russh`: -- TOFU host key verification -- Password and key authentication -- Proxy support (SOCKS5) -- OSC 7 integration for remote CWD tracking +### TransferContext -#### SFTP Implementation +`src/context/TransferContext.tsx` manages the file transfer queue separately. It consumes backend `transfer-event` notifications and drives pause, resume, cancel, and retry behavior in the UI. -High-performance file transfers: -- Channel multiplexing on existing SSH connections -- Pipelined concurrent downloads (16 concurrent, 128 KiB chunks) -- Real-time transfer progress events +## Workspace model -### Event Communication +Dragonfly's terminal workspace has two layers that are easy to confuse but serve different purposes. -Backend emits events to frontend via Tauri: +### Logical tabs and pane trees + +`src/lib/workspaceTabs.ts` is responsible for: + +- Creating tabs and session panes +- Horizontal and vertical splits inside a tab +- Persisting `ui.open_tabs` +- Restoring the serializable workspace structure on startup + +### Runtime window layout + +`src/lib/tabWindows.ts` is responsible for: + +- Which tabs are currently attached to which window leaf +- The active tab inside each leaf +- Runtime window split ratios + +A practical shorthand is: + +- `workspaceTabs.ts` = the logical workspace that gets persisted +- `tabWindows.ts` = the live runtime arrangement of terminal areas + +## Terminal integration + +`src/components/terminal/XTerminal.tsx` is the xterm.js integration center. It is responsible for: + +- Fit / Search / WebLinks and related addons +- Shell integration and command-history suggestions +- Line-number / timestamp gutter +- Action links and keyword highlighting +- Large-output protection and recovery messaging +- Session event subscriptions and reconnect behavior + +## Backend runtime model + +`src-tauri/src/lib.rs` is the backend entry point. It constructs and stores shared runtime state such as: + +- `SessionManager` +- `TunnelManager` +- `RecordingManager` +- `PendingAuthManager` + +It also registers Tauri commands centrally, including commands for: + +- Session creation / close / write / recording / OTP flows +- SFTP file and transfer operations +- Connections, keys, passwords, OTP, and settings persistence +- Watcher, translation, importer, stats, tunnel, and proxy flows + +## SessionManager and event flow + +`src-tauri/src/core/session.rs` contains `SessionManager`, the central registry for active sessions. It is responsible for: + +- Tracking all active sessions +- Routing commands into per-session I/O loops +- Maintaining command history and fuzzy search storage +- Emitting `sessions-changed`, `command-history-changed`, and related events + +The backend also emits these common events to the frontend: | Event | Description | -|-------|-------------| -| `terminal-output-{id}` | Terminal output data | -| `cwd-changed-{id}` | Working directory changed | +|------|------| +| `terminal-output-{id}` | Terminal output | +| `cwd-changed-{id}` | Working directory updates | | `session-closed-{id}` | Session closed | -| `transfer-event` | SFTP transfer progress | -| `sessions-changed` | Session list updated | -| `connections-changed` | Connection config changed | +| `sessions-changed` | Session list changed | +| `connections-changed` | Saved connections changed | +| `transfer-event` | Transfer queue progress changed | +| `otp-request` | OTP / keyboard-interactive authentication requested | -### Configuration Files +## SSH, SFTP, watcher, and import flows -All configs stored in `~/.dragonfly/`: +Core backend capabilities are mainly organized under these modules: -| File | Content | -|------|---------| -| `sessions.json` | SSH connections and groups | -| `keys.json` | SSH private keys (encrypted) | -| `settings.json` | Application settings | -| `quick-command.json` | Quick commands | -| `history.json` | Command history | -| `known_hosts` | SSH host keys | +- `src-tauri/src/core/ssh/` — SSH connection setup, authentication, OSC/CWD tracking, SFTP, tunnels +- `src-tauri/src/core/pty.rs` — local terminal sessions +- `src-tauri/src/core/telnet.rs` — Telnet sessions +- `src-tauri/src/core/serial.rs` — serial sessions +- `src-tauri/src/core/watcher.rs` — local file watching and auto-upload workflows +- `src-tauri/src/core/importer.rs` — Xshell / MobaXterm / WindTerm session import +- `src-tauri/src/core/recording.rs` — session recording + +## Configuration and persistence + +Application data is stored under `~/.dragonfly/`. Typical files include: + +- `settings.json` +- `sessions.json` +- `keys.json` +- `passwords.json` +- `otp.json` +- `quick-command.json` +- `tunnels.json` +- `proxies.json` +- `history.json` +- `known_hosts` + +Sensitive values are encrypted before being written, so the app manages reusable credential records rather than plain-text secrets. diff --git a/docs-site/i18n/en/docusaurus-plugin-content-docs/current/development/backend.md b/docs-site/i18n/en/docusaurus-plugin-content-docs/current/development/backend.md index 34bf5c4f..4ddd8c9a 100644 --- a/docs-site/i18n/en/docusaurus-plugin-content-docs/current/development/backend.md +++ b/docs-site/i18n/en/docusaurus-plugin-content-docs/current/development/backend.md @@ -4,125 +4,162 @@ sidebar_position: 4 # Backend Development -## Project Structure +Backend code lives in `src-tauri/src/` and is written in Rust. It is the runtime core of Dragonfly: session management, SSH/SFTP, recording, translation, tunnels, authentication, and config persistence all land here. -Backend code is in `src-tauri/src/`, written in Rust. +## Command entry points and module organization -## Adding Tauri Commands +Backend command registration is centralized in `src-tauri/src/lib.rs`: -### 1. Define the Command +- Shared manager state is created there +- Tauri plugins are mounted there +- Commands are registered there through `tauri::generate_handler![]` -Add commands in `src-tauri/src/commands/`: +Command modules live in: -```rust -use tauri::State; -use crate::session::SessionManager; - -#[tauri::command] -pub async fn my_command( - session_manager: State<'_, SessionManager>, - param: String, -) -> Result { - Ok("result".to_string()) -} +```text +src-tauri/src/cmd/ +├── session.rs +├── sftp.rs +├── connection.rs +├── settings.rs +├── watcher.rs +├── translate.rs +├── stats.rs +├── tunnel.rs +├── proxy.rs +├── otp.rs +├── importer.rs +├── clipboard.rs +└── log.rs ``` -### 2. Register the Command +When adding a new command, the usual flow is: -In `src-tauri/src/lib.rs`, add to `invoke_handler`: +1. Define a `#[tauri::command]` in the appropriate `cmd/*.rs` file +2. Reuse existing logic in `core/` or `config/` where possible +3. Register the command in `src-tauri/src/lib.rs` +4. Call it from the frontend through `src/lib/invoke.ts` -```rust -.invoke_handler(tauri::generate_handler![ - // ...existing commands - commands::my_command, -]) -``` +## Shared runtime state -### 3. Call from Frontend +`src-tauri/src/lib.rs` injects these shared objects into Tauri state: -```typescript -const result = await invoke('my_command', { param: 'value' }); -``` +- `SessionManager` +- `TunnelManager` +- `RecordingManager` +- `PendingAuthManager` -## SSH Module +Their roles are: -### Connection Flow +- Active session lifecycle and command history +- SSH tunnel state +- Recording state +- Pending keyboard-interactive / OTP authentication requests -1. Load connection info from config -2. Decrypt password/private key -3. Establish TCP connection (optional proxy) -4. TOFU host key verification -5. Authenticate (password/key) -6. Open PTY channel -7. Inject OSC 7 script (CWD tracking) -8. Start async I/O loop +## SessionManager -### I/O Loop +`src-tauri/src/core/session.rs` contains `SessionManager`, the center of session runtime behavior. It is responsible for: -Each session maintains an async task: +- Registering and removing active sessions +- Sending `Write`, `Resize`, `Close`, and `Attach` commands into session I/O loops +- Managing command history and fuzzy search storage +- Emitting events such as `sessions-changed` and `command-history-changed` -```rust -tokio::spawn(async move { - loop { - tokio::select! { - cmd = cmd_rx.recv() => { - // Handle: Write, Resize, Close, Attach - } - msg = channel.wait() => { - // Handle: Data, ExtendedData, Eof - } - } - } -}); -``` +The session metadata exposed to the frontend also includes `injection_active`, which indicates whether the current session supports shell-integration features such as terminal path tracking. -## SFTP Module +## Session implementations -### Transfer Optimization +Concrete session types are implemented under `src-tauri/src/core/`: -Downloads use pipelined concurrent reads: -- 16 concurrent file handles -- 128 KiB per chunk -- ~1 MiB in-flight buffer -- Sliding window for known-size files -- Sequential reads for unknown-size files (e.g., `/proc`) +- `ssh/` — SSH connections, authentication, OSC/CWD tracking, SFTP, tunnels +- `pty.rs` — local terminal sessions +- `telnet.rs` — Telnet sessions +- `serial.rs` — serial sessions +- `recording.rs` — session recording +- `watcher.rs` — local file watching and auto-upload flows +- `importer.rs` — external client session import -### Directory Operations +## SSH modules -Recursive deletion uses a fault-tolerant strategy — partial failures don't affect other deletions. +`src-tauri/src/core/ssh/` is the most central backend area: -## Encryption Module +- `client.rs` — russh client setup, known-host verification, proxy-aware connection setup +- `auth.rs` — loading saved authentication data and handling keyboard-interactive / OTP flows +- `io.rs` — terminal I/O and cwd update events +- `sftp.rs` — remote file operations and transfer queue handling +- `tunnel.rs` — local / remote / dynamic tunnels +- `session.rs` — SSH session lifecycle coordination -AES-256-GCM for sensitive data: +A typical SSH flow is: -```rust -let encrypted = encrypt_string("plaintext", &key)?; -let decrypted = decrypt_string(&encrypted, &key)?; -``` +1. Read the connection configuration +2. Decrypt passwords, private keys, or other credentials +3. Establish the TCP or proxy connection +4. Apply host-key policy verification +5. Complete authentication, possibly entering OTP / interactive flow +6. Open the PTY channel and enter the async I/O loop +7. Inject OSC/CWD tracking when supported -Key sources: OS Keyring or master password derivation. +## SFTP and the transfer queue -## Configuration Management +`src-tauri/src/core/ssh/sftp.rs` is responsible for: -JSON-based configs in `~/.dragonfly/`: +- Listing directories +- Uploading / downloading files and directories +- Delete / rename / mkdir / symlink / stat operations +- Transfer queue control such as pause / resume / cancel +- Emitting `transfer-event` for the frontend -```rust -let config = SessionConfig::load()?; -config.save()?; -``` +The frontend transfer panel and `TransferContext` are built on top of these events. -Config changes emit `connections-changed` events to notify the frontend. +## Watcher and auto-upload -## Logging +`src-tauri/src/core/watcher.rs` handles local file watching. -Uses the `tracing` crate: +A typical flow is: -```rust -use tracing::{info, warn, error, debug}; +1. The frontend chooses **Open** on a remote file from the file explorer +2. The backend downloads it into a local temp directory and starts watching it +3. After the local file is saved, a `file-modified` event is emitted +4. The frontend decides whether to open the auto-upload window or upload immediately when the user previously chose an always-upload behavior -info!("Session created: {}", session_id); -warn!("Connection timeout for: {}", host); -error!("SSH error: {:?}", err); -``` +This flow involves: -Log files are in the app log directory with daily rotation and 7-day retention. +- `cmd/watcher.rs` +- `core/watcher.rs` +- Frontend `FileUploadPage.tsx` + +## Configuration and encryption + +Configuration files are stored under `~/.dragonfly/` and are mainly managed by `src-tauri/src/config/`. + +Common files include: + +- `settings.json` +- `sessions.json` +- `keys.json` +- `passwords.json` +- `otp.json` +- `quick-command.json` +- `tunnels.json` +- `proxies.json` +- `history.json` +- `known_hosts` + +Sensitive fields are encrypted before being written, so when adding new configuration you should verify whether it crosses a sensitive-data boundary. + +## Event model + +The backend relies heavily on Tauri events to notify the frontend. Typical events include: + +| Event | Description | +|------|------| +| `terminal-output-{id}` | Terminal output | +| `cwd-changed-{id}` | Working directory changed | +| `session-closed-{id}` | Session closed | +| `sessions-changed` | Session list changed | +| `connections-changed` | Saved connections changed | +| `transfer-event` | Transfer progress | +| `otp-request` | OTP / keyboard-interactive authentication requested | + +When designing new backend features, prefer exposing them through the existing event flow where appropriate rather than introducing extra polling APIs. diff --git a/docs-site/i18n/en/docusaurus-plugin-content-docs/current/development/frontend.md b/docs-site/i18n/en/docusaurus-plugin-content-docs/current/development/frontend.md index 5232cec4..1e536f32 100644 --- a/docs-site/i18n/en/docusaurus-plugin-content-docs/current/development/frontend.md +++ b/docs-site/i18n/en/docusaurus-plugin-content-docs/current/development/frontend.md @@ -4,114 +4,151 @@ sidebar_position: 3 # Frontend Development -## Project Structure +Frontend code lives in `src/` and uses React 19 + TypeScript. -Frontend code is in `src/`, using React 19 + TypeScript. +## Entry points and window model -## Component Development +The frontend entry point is `src/main.tsx`. It decides which app tree to load based on the `?window=` query parameter in the URL: -### UI Component Library +- **Main window** — `AppProvider` + `App.tsx` +- **Child windows** — `ChildAppProvider` + `ChildWindowRouter` -The project uses [shadcn/ui](https://ui.shadcn.com/): +Current child-window flows include: -- Components in `src/components/ui/` -- Built on Radix UI primitives -- Styled with TailwindCSS +- settings +- new-session +- quick-command +- auto-upload -### Adding Components +If you are changing these flows, start with: -```bash -npx shadcn@latest add button +- `src/main.tsx` +- `src/ChildWindowRouter.tsx` +- `src/lib/windowManager.ts` + +## Component and directory structure + +```text +src/ +├── components/ # UI components +│ ├── dialog/ # Dialog and child-window related components +│ ├── panel/ # Left/right sidebar and bottom helper panels +│ ├── terminal/ # xterm workspace and terminal-related components +│ ├── layout/ # Outer layout, title bar, activity bars +│ └── ui/ # Shared base UI components (shadcn/ui) +├── context/ # React Context providers +├── hooks/ # Custom hooks +├── i18n/ # Internationalization +├── lib/ # invoke wrapper, window manager, workspace helpers +├── pages/ # Child-window pages +├── types/ # Shared type definitions +├── App.tsx # Main application shell +└── main.tsx # Frontend entry point ``` -### Icons - -Uses [Lucide React](https://lucide.dev/): - -```tsx -import { Terminal } from 'lucide-react'; - - -``` - -## State Management +## State management ### AppContext -Core application state: active sessions, saved connections, active tab, settings. -### ThemeContext -Theme state: current theme, terminal color scheme, font configuration. +`src/context/AppContext.tsx` is the main state container for the primary window. It manages: + +- Tabs and pane trees +- Active tab and active pane +- Saved connections and group refreshes +- App settings and UI settings +- Startup restoration of the workspace + +### ChildAppProvider + +`src/context/ChildAppProvider.tsx` is the lightweight provider for child windows: + +- Loads and saves settings only +- Does not hold the full workspace state +- Syncs settings changes back to the main window through events ### TransferContext -File transfer state: transfer queue, progress, completion/error status. -## Calling Tauri Commands +`src/context/TransferContext.tsx` listens to `transfer-event` and centrally manages: -Use `@tauri-apps/api` to invoke backend commands: +- Transfer queue items +- Progress, paused, canceled, and error state +- Pause / resume / cancel / retry actions -```typescript -import { invoke } from '@tauri-apps/api/core'; +## Calling Tauri commands + +Frontend code should prefer the shared wrapper in `src/lib/invoke.ts` rather than scattering raw `@tauri-apps/api/core` `invoke()` calls everywhere. + +```ts +import { invoke } from '@/lib/invoke'; const sessionId = await invoke('create_ssh_session', { - connectionId: 'uuid-here' -}); - -const files = await invoke('list_remote_dir', { - sessionId: 'session-id', - path: '/home/user' + connectionId: 'uuid-here', }); ``` -## Listening to Events +This wrapper centralizes error logging and makes future call behavior easier to change. -```typescript -import { listen } from '@tauri-apps/api/event'; +## Listening to backend events -const unlisten = await listen(`terminal-output-${sessionId}`, (event) => { - terminal.write(event.payload); -}); +Many frontend features rely on Tauri events, for example: -unlisten(); // Cleanup -``` +- `terminal-output-{id}` +- `cwd-changed-{id}` +- `session-closed-{id}` +- `transfer-event` +- `sessions-changed` +- `connections-changed` +- `otp-request` + +Terminal rendering, file browsing, resource monitoring, transfer queues, and OTP flows all sit on top of these events. + +## Workspace model + +The workspace has two layers. + +### `workspaceTabs.ts` + +This file manages the persisted logical workspace: + +- Tabs +- Pane trees +- In-tab splits +- Serialization / restoration of `ui.open_tabs` + +### `tabWindows.ts` + +This file manages the live runtime terminal layout: + +- Which tabs are attached to which leaf +- The active tab for each leaf +- Runtime split ratios + +When editing tabs, splits, or multi-area terminal layout behavior, first decide which layer you are actually changing. + +## Terminal integration + +`src/components/terminal/XTerminal.tsx` is the main xterm.js integration point. It handles: + +- Search / Fit / WebLinks addons +- Shell integration and command suggestions +- Gutter rendering for line numbers and timestamps +- Action links and keyword highlighting +- Large-output protection +- Reconnect-related behavior + +If you are changing terminal presentation, this is usually the first file to inspect. ## Internationalization -### Adding Translations +User-facing UI text uses `react-i18next`. Locale files are in: -Add key-value pairs to JSON files in `src/i18n/locales/`. +- `src/i18n/locales/zh-CN.json` +- `src/i18n/locales/en.json` -### Using Translations +Whenever you add or change visible UI text, update both locale files. -```tsx -import { useTranslation } from 'react-i18next'; +## UI component conventions -function MyComponent() { - const { t } = useTranslation(); - return {t('menu.file')}; -} -``` +The project uses shadcn/ui as its base component layer. Shared UI components live in `src/components/ui/`. -## Terminal Integration - -Terminal uses xterm.js with key addons: - -- **WebGL Addon** — GPU-accelerated rendering -- **Fit Addon** — Auto-resize to container -- **Search Addon** — Text search -- **Web Links Addon** — Clickable URLs - -```typescript -import { Terminal } from '@xterm/xterm'; -import { FitAddon } from '@xterm/addon-fit'; -import { WebglAddon } from '@xterm/addon-webgl'; - -const terminal = new Terminal({ - fontFamily: 'JetBrains Mono, monospace', - fontSize: 16, - cursorBlink: true, -}); - -const fitAddon = new FitAddon(); -terminal.loadAddon(fitAddon); -terminal.loadAddon(new WebglAddon()); -``` +If you need a new reusable UI piece, prefer existing components and project style patterns over building a parallel base component system. diff --git a/docs-site/i18n/en/docusaurus-plugin-content-docs/current/faq.md b/docs-site/i18n/en/docusaurus-plugin-content-docs/current/faq.md index 35e9bf28..2f6e7734 100644 --- a/docs-site/i18n/en/docusaurus-plugin-content-docs/current/faq.md +++ b/docs-site/i18n/en/docusaurus-plugin-content-docs/current/faq.md @@ -4,84 +4,125 @@ sidebar_position: 100 # FAQ -## Connection Issues +## Sessions and connections -### SSH connection times out? +### SSH works, so why do Local Terminal, Telnet, and Serial behave differently? -1. Verify the server address and port -2. Confirm the SSH service is running on the server -3. Check firewall rules for the SSH port -4. If using a proxy, verify proxy configuration -5. Try increasing Keep-Alive interval (**Settings → Terminal → Keep-Alive Interval**) +Because Dragonfly supports multiple session types, and their capabilities are not identical: -### Terminal unresponsive after connecting? +- **SSH** — the most complete workflow, including SFTP, OTP, resource monitoring, proxy, jump host, and tunnels +- **Local Terminal** — local shell workflow only +- **Telnet** — lightweight remote terminal without SSH-specific features +- **Serial** — serial debugging, not an SSH network path -- Try pressing `Enter` -- Check if authentication succeeded -- View application logs (**Help → View Logs**) +If you need the file explorer, remote resource monitoring, or OTP, make sure the current tab is an **SSH session**. -### How to use private key authentication? +### Why is the file explorer missing for some sessions? -1. Go to **Settings → Security → Key Management** -2. Click **Add Key** and import your private key file -3. When creating a connection, select **Private Key** authentication and choose the key +The file explorer depends on SFTP, so it is only available for **SSH sessions**. -## File Transfer +These session types do not provide the remote file explorer: -### Slow upload/download speeds? +- Local Terminal +- Telnet +- Serial -Dragonfly uses pipelined transfers for optimized large file speeds. Slow speeds may indicate network bandwidth limitations. +### Why can’t I see remote resource monitoring? -### Cannot delete a file? +Check both of these: -Check if the current user has delete permissions. View permissions in file properties. +1. The current tab is an **SSH session** +2. **Show Remote Resource Stats** is enabled in **Settings → Terminal** -## Interface Issues +Resource monitoring is off by default. -### Fonts display incorrectly? +### What should I do if the serial port list is empty? -1. Go to **Settings → Appearance → Font Family** -2. Confirm the primary font is installed -3. Add fallback fonts +Check that: -### Terminal rendering is laggy? +- The device is physically connected +- The operating system recognizes the serial port +- Another tool is not already holding the port open -In **Settings → Terminal**: -- Toggle **Hardware Acceleration** (requires app restart) -- Reduce **Scrollback Buffer** line count +When you reopen the port dropdown on the Serial tab, Dragonfly reloads the available ports. -### How to reset the interface layout? +## Terminal experience -Use **View → Reset Panel Layout**. +### Why can’t I click action links? -## Security +Usually one of these is true: -### Forgot the master password? +1. **Action Links** is not enabled in **Settings → Terminal** +2. You are not using **Ctrl / Cmd + click** -The master password encrypts session data. If forgotten, delete the config files in `~/.dragonfly/` and reconfigure. +Action links are disabled by default, and opening them requires a modifier key to avoid accidental activation. -:::warning -Deleting config files will lose all saved connections and keys. -::: +### Why can’t I see keyword highlighting? -### Forgot the screen lock password? +Keyword highlighting is disabled by default. Enable it first in **Settings → Terminal**, then confirm the current output actually matches one of the configured rules. -Manually edit `~/.dragonfly/settings.json` and reset the lock-related settings. +### Why are line numbers and timestamps not visible? -## Other +These are also optional enhancements. Enable them separately in **Settings → Terminal**. -### How to import sessions from other SSH clients? +## File transfer -Currently supports WindTerm: +### Why didn’t the auto-upload prompt appear after I opened a remote file? -1. Right-click the sidebar and select **Import Sessions** -2. Choose WindTerm -3. Select the WindTerm session config file +The auto-upload prompt only appears in this workflow: -### Where are config files stored? +1. You choose **Open** on a remote file from the SSH file explorer +2. Dragonfly downloads it into a local temporary directory and starts watching it +3. You save that watched file in your local editor -All configs are in `~/.dragonfly/`, including connections, keys, and settings. +If you copied the file elsewhere and edited that copy manually, Dragonfly no longer knows it maps back to the remote file. -### How to view application logs? +### Why didn’t the file explorer follow my `cd` command automatically? -Via **Help → View Logs**. Logs rotate daily with 7-day retention. +Auto-follow depends on terminal path tracking support for the session. If the current session does not support it, automatic sync is disabled and you need to trigger sync manually. + +### Where do uploads and downloads go? + +That depends on your transfer settings: + +- If **ask every time** is enabled, Dragonfly prompts for a destination on each download +- Otherwise it uses the default download directory + +You can also change the default download path and the default editor in settings. + +## Security and authentication + +### Why can I unlock the screen without entering a password? + +Because screen lock is enabled, but **no master password is set yet**. + +In the current behavior: + +- With a master password: unlocking requires the master password +- Without a master password: unlocking can be done directly + +### What if I forget the master password? + +There is currently no built-in recovery flow for the master password. If your local data is protected by it and you can no longer provide the correct password, those protected sensitive settings cannot continue to be used in the original way. + +Before making manual changes, back up `~/.dragonfly/` first, then decide how to rebuild local configuration. + +### Where should OTP entries be managed? + +Manage them centrally in the **OTP** tab of the **Security/Auth** panel, then bind them to individual SSH connections in the connection form. + +## Import and migration + +### Which clients can Dragonfly import sessions from? + +Current supported imports are: + +- Xshell (`.xts`) +- MobaXterm (`.mxtsessions`) +- WindTerm (`.sessions`) + +After import, it is a good idea to review the username, port, authentication method, and whether proxy / jump host / OTP still needs to be configured. + +### Where are Dragonfly’s config files stored? + +Application configuration is stored under `~/.dragonfly/`, including settings, connections, keys, OTP data, tunnels, proxies, and history. diff --git a/docs-site/i18n/en/docusaurus-plugin-content-docs/current/getting-started/installation.md b/docs-site/i18n/en/docusaurus-plugin-content-docs/current/getting-started/installation.md index f54fc8ed..a0ecb7ce 100644 --- a/docs-site/i18n/en/docusaurus-plugin-content-docs/current/getting-started/installation.md +++ b/docs-site/i18n/en/docusaurus-plugin-content-docs/current/getting-started/installation.md @@ -10,11 +10,11 @@ Dragonfly supports the following operating systems: - **Windows** 10/11 (64-bit) - **macOS** 12+ (Intel & Apple Silicon) -- **Linux** (Ubuntu 20.04+, Fedora 36+, Arch Linux, etc.) +- **Linux** (Ubuntu 20.04+, Fedora 36+, Arch Linux, and similar distributions) -## Download & Install +## Download and install -### From Releases +### From releases Visit the [Releases](https://git.coderkang.top/Tauri/dragonfly/releases) page and download the installer for your OS: @@ -24,16 +24,33 @@ Visit the [Releases](https://git.coderkang.top/Tauri/dragonfly/releases) page an | macOS | `.dmg` | | Linux | `.deb` / `.AppImage` | -### Build from Source +### Build from source -To build from source, see the [Development Setup](../development/setup) section. +If you prefer to build Dragonfly yourself, see [Development Setup](../development/setup). -## First Launch +## What you see on first launch -After installation, launch Dragonfly and you'll see a clean interface with: +After installation, the main window is typically organized into these areas: -- **Left Sidebar** — Saved connections list -- **Center Area** — Terminal tabs -- **Right Sidebar** — File explorer and quick commands +- **Top menu and window bar** — File / View / Help and window controls +- **Central workspace** — terminal tabs and split panes inside the active tab +- **Left activity bar and panels** — file explorer, network, Security/Auth, and related capability entry points +- **Right activity bar and panels** — saved connections, active sessions, command history, and resource monitor +- **Bottom helper area** — quick commands, serial send, recording, and lock actions -Next, check out [Quick Start](./quick-start) to create your first SSH connection. +Some workflows open dedicated child windows instead of interrupting the main workspace, such as: + +- Settings +- New session / connection creation +- Quick command editing +- Auto-upload prompts + +## Suggested first run + +For a first pass through the app, try this order: + +1. Open [Quick Start](./quick-start) +2. Create one **SSH** connection +3. Create one **Local Terminal** to experience the mixed workspace model +4. Open the file explorer and transfer queue in the SSH session +5. Try command history, quick commands, and terminal search diff --git a/docs-site/i18n/en/docusaurus-plugin-content-docs/current/getting-started/quick-start.md b/docs-site/i18n/en/docusaurus-plugin-content-docs/current/getting-started/quick-start.md index f35f677d..9357322a 100644 --- a/docs-site/i18n/en/docusaurus-plugin-content-docs/current/getting-started/quick-start.md +++ b/docs-site/i18n/en/docusaurus-plugin-content-docs/current/getting-started/quick-start.md @@ -4,51 +4,98 @@ sidebar_position: 2 # Quick Start -This guide will walk you through creating and using your first SSH connection. +This chapter helps you experience Dragonfly's core workflow as quickly as possible: create a connection, open sessions, split the workspace, browse files, and turn on terminal enhancements when you need them. -## Create an SSH Connection +## Step 1: Pick a session type -1. Click **New Connection** in the left sidebar, or use **File → New SSH Connection** -2. Fill in the dialog: - - **Connection Name** — A friendly display name - - **Host** — Server IP address or domain name - - **Port** — SSH port (default 22) - - **Username** — Login username - - **Authentication** — Password or private key -3. Click **Save** +When you click **New Connection**, Dragonfly offers four session types: -## Connect to a Server +- **SSH** — the most complete remote-operations workflow +- **Local Terminal** — open a local shell inside Dragonfly +- **Telnet** — useful for legacy systems or lab environments +- **Serial** — useful for serial debugging devices -Double-click a connection in the sidebar, or right-click and select **Connect** to start an SSH session. +If this is your first time using Dragonfly, start with one **SSH** session and then add one **Local Terminal** to compare the mixed-workspace experience. -A new terminal tab will appear in the center area upon successful connection. +## Step 2: Create your first SSH connection -## Basic Operations +In the new-session window, fill in: -### Multi-Tab Management +- **Connection Name** — a friendly display name +- **Host** and **Port** +- **Username** +- **Authentication** — password or private key -- Open multiple SSH connections simultaneously, each in its own tab -- Use `Ctrl+Tab` to switch between tabs -- Use `Ctrl+W` to close the current tab +If needed, expand the advanced section to configure: -### File Browsing +- Proxy +- Jump host +- OTP binding and auto-fill +- Icon, group, description, and other metadata -After connecting, the right-side file explorer automatically shows the remote filesystem: +After saving, the connection appears in the saved-connections list. -- Browse directory structure -- Upload/download files -- Right-click for file operations (rename, delete, move, etc.) +## Step 3: Understand the workspace -### Command History +Double-click a saved connection, or use the connection context menu, to launch the session. -Dragonfly automatically records your commands, searchable via fuzzy matching. +After the connection is established, you will see: -## Create a Local Terminal +- **Center area** — the current terminal tab and any split panes inside it +- **Left activity bar** — entry points for file explorer, network, Security/Auth, and related panels +- **Right activity bar** — saved connections, active sessions, command history, and resource monitor +- **Bottom area** — quick commands, serial send, recording, and lock actions -You can also create local shell sessions via **Terminal → New Local Terminal**. +## Step 4: Try the highest-frequency workflows -## Next Steps +### 1. Open a local terminal too -- Learn more about [SSH Connection Management](../guide/ssh-connection) -- Explore [SFTP File Transfer](../guide/file-transfer) -- Set up [Quick Commands](../guide/quick-commands) for productivity +Use the ``Ctrl/Cmd + ` `` shortcut or the menu entry to create a local terminal so you can compare local and remote work in one app. + +### 2. Try split panes + +Right-click a tab and choose: + +- **Horizontal Split** +- **Vertical Split** + +This is useful when you want to watch logs, run commands, and compare output from different hosts at the same time. + +### 3. Open the remote file explorer and transfer queue + +Once an SSH session is active, the file explorer lets you browse remote directories and perform upload, download, delete, move, rename, and properties actions. + +When you start uploads or downloads, the transfer panel shows queue progress and supports pause, resume, cancel, and retry. + +### 4. Open command history and quick commands + +- **Command History** is useful for recall and fuzzy lookup +- **Quick Commands** is useful for reusable actions with categories, execution modes, and variable prompts + +### 5. Try search / online search / translation + +When text is selected in the terminal, the context menu can: + +- **Find** inside the current output +- Send text to an **online search** engine +- Open a **translation** dialog with a configured provider + +### 6. Turn on optional terminal enhancements + +In **Settings → Terminal**, you can enable: + +- Line numbers +- Timestamps +- Action links +- Keyword highlighting +- Remote resource stats + +These features are intentionally conservative by default, so you can enable them only where they help your workflow. + +## Step 5: Keep exploring by use case + +- Want to understand the differences between sessions? See [Session Types](../guide/session-types) +- Want to configure auth, proxy, or jump hosts? See [SSH Connection Management](../guide/ssh-connection) +- Want to manage files and auto-upload? See [SFTP File Transfer](../guide/file-transfer) +- Want to learn terminal enhancements and recording? See [Terminal Features](../guide/terminal) +- Want to configure OTP? See [OTP and Authentication](../guide/otp-and-auth) diff --git a/docs-site/i18n/en/docusaurus-plugin-content-docs/current/guide/file-transfer.md b/docs-site/i18n/en/docusaurus-plugin-content-docs/current/guide/file-transfer.md index f7213202..86f7aefa 100644 --- a/docs-site/i18n/en/docusaurus-plugin-content-docs/current/guide/file-transfer.md +++ b/docs-site/i18n/en/docusaurus-plugin-content-docs/current/guide/file-transfer.md @@ -4,72 +4,146 @@ sidebar_position: 2 # SFTP File Transfer -Dragonfly includes a full-featured SFTP file manager built right into the interface. +Dragonfly's remote file workflow is built on top of SSH sessions. That means the **file explorer, SFTP transfers, and local-edit-then-upload-back workflow** are only available in SSH sessions. Local Terminal, Telnet, and Serial do not expose this set of features. -## File Explorer +## File explorer -After connecting to an SSH session, the right sidebar displays the remote file explorer: +After connecting an SSH session, the file explorer panel lets you browse remote directories directly. -- Automatically navigates to the user's home directory -- Click folders to enter, click **Go Up** to navigate back -- Click the path bar to type a path directly -- Supports auto-sync with terminal working directory +Core capabilities include: -### File Operations +- Automatically entering the remote user's home directory +- Entering folders, going up, and jumping by typing a path +- Refreshing the current directory +- Syncing with the terminal's working directory +- Disabling auto-sync when the session does not support path tracking -Right-click files or folders for these operations: +## Common file operations + +From the file list or the context menu, you can perform: | Operation | Description | -|-----------|-------------| -| Open | Open file in default editor | -| Download | Download file to local machine | -| Rename | Rename file or folder | -| Move | Move file to specified path | -| Delete | Delete file or folder (recursive) | -| Properties | View detailed file information | -| Copy Path | Copy the full file path | +|------|------| +| Open | Download to a local temp directory, then open with the default editor | +| Upload File | Upload a local file to the current remote directory | +| Upload Folder | Upload a full local directory tree | +| Download | Download a file or an entire directory | +| Rename | Change the remote name | +| Move | Move a file or directory to another path | +| Delete | Remove a file or directory | +| Properties | View size, timestamps, UID/GID, permissions, and more | +| New File / Folder / Symlink | Create entries directly in the current directory | -### Create Files and Folders +The **Open** action is not just a preview. It prepares the round-trip editing flow. -From the toolbar: +## Uploads and downloads -- New File -- New Folder -- New Symlink +### Upload -## File Upload +Use the toolbar or context menu to upload local files into the current remote directory. -Click the **Upload** button in the toolbar to upload local files to the current directory. +- Multiple files are queued one by one +- Folder uploads preserve directory structure +- Good for syncing scripts, config files, or release packages -## File Download +### Download -Select a file and click **Download** in the toolbar, or right-click and select **Download**. +Downloads usually follow one of two workflows: -Dragonfly uses pipelined transfer technology with multiple concurrent data chunk reads for significantly faster large file transfers. +- Save directly into a default download directory +- Ask for a destination every time for ad hoc troubleshooting or task-based organization -## Transfer Progress +Both file downloads and directory downloads are supported. -In the **File Transfer** panel on the right sidebar, view real-time progress of all transfer tasks: +## Transfer panel and transfer settings -- Transferring files with progress -- Completed transfers -- Transfer errors +Dragonfly puts uploads and downloads into a shared transfer queue so you can inspect: -Clear completed transfers with one click. +- Current progress +- Success, paused, canceled, and failed states +- Concurrent transfers +- The current download target -## Path Sync +Each transfer item supports: -The file explorer supports syncing with the terminal path: +- **Pause** +- **Resume** +- **Cancel** +- **Retry after failure** +- **Remove after completion** -- **Manual Sync** — Click the sync button to navigate to the terminal's current directory -- **Auto Sync** — When enabled, the file explorer automatically follows the terminal's working directory +The panel also provides bulk actions: -## File Properties +- **Pause All** +- **Resume All** +- **Cancel All** +- **Clear Completed** -Right-click a file and select **Properties** to view: +In **Settings → Transfer**, you can adjust: + +- Upload / download thread count +- Conflict handling strategy +- Maximum retry count +- Transfer buffer size +- Whether to preserve timestamps +- Whether to continue resumable transfers +- Default file permissions +- Default download path +- Whether to ask for the save location every time +- The local editor used when opening remote files + +## Sync with terminal paths + +The file explorer can work together with the current SSH terminal path: + +- **Manual Sync** — jump the explorer to the terminal's current directory +- **Auto Sync** — automatically follow when the terminal changes directories + +This is useful when you are moving around in a deploy or log directory and want the file panel to stay aligned. + +## Edit locally and upload back automatically + +This is one of Dragonfly's most practical workflows for real operations work. + +### How it works + +1. In the SSH file explorer, choose **Open** on a remote file +2. Dragonfly downloads it into a local temp directory +3. A file watcher is started +4. After you save in your local editor, Dragonfly opens an upload prompt + +### Upload prompt window + +After the file changes, you can choose: + +- **Upload once** +- **Always upload** +- **Cancel** + +If you choose **Always upload** for a file, later saves in the **current session** are sent back automatically without prompting again. + +### Good fits + +- Editing remote config files +- Tweaking deploy scripts +- Pulling a file locally for inspection, then sending changes back +- Preparing screenshots that demonstrate the round-trip editing flow + +## File properties and permissions + +The **Properties** view shows: - File size -- Modified and access times +- Modified time and access time - Owner and group -- Permissions (user/group/other, octal notation) -- UID and GID +- UID / GID +- Octal permission values + +If your workflow requires checking permissions before replacing a file, this is often clearer than relying only on `ls -l`. + +:::tip Screenshot suggestion +- Suggested image path: `/img/docs/file-transfer/remote-file-browser.png` +- Show an SSH session with the file browser, toolbar, and context menu visible +- Another good image path: `/img/docs/file-transfer/auto-upload-dialog.png` +- Open a remote text file, save it in a local editor, and capture the auto-upload prompt +::: diff --git a/docs-site/i18n/en/docusaurus-plugin-content-docs/current/guide/keyboard-shortcuts.md b/docs-site/i18n/en/docusaurus-plugin-content-docs/current/guide/keyboard-shortcuts.md index b39e6b5c..43887dcf 100644 --- a/docs-site/i18n/en/docusaurus-plugin-content-docs/current/guide/keyboard-shortcuts.md +++ b/docs-site/i18n/en/docusaurus-plugin-content-docs/current/guide/keyboard-shortcuts.md @@ -4,44 +4,64 @@ sidebar_position: 8 # Keyboard Shortcuts -Dragonfly provides comprehensive keyboard shortcut support. +The easiest way to understand Dragonfly shortcuts is to split them into two groups: -## Terminal Operations +1. **App-level shortcuts** — toggle panels, create sessions, copy terminal content, and so on +2. **Shell-level keys** — keys that are sent to the remote or local shell, such as `Ctrl+C` + +If you want to copy text from the terminal, use Dragonfly's app-level shortcuts rather than assuming shell shortcuts become copy actions. + +## Conventions + +- **Ctrl / Cmd** means `Ctrl` on Windows/Linux and `Cmd` on macOS +- `Ctrl+Tab` and `Ctrl+Shift+Tab` are kept as-is because that matches the current implementation + +## Terminal operations | Shortcut | Action | -|----------|--------| -| `Ctrl+C` | Copy selected text / Send interrupt | -| `Ctrl+V` | Paste | +|--------|------| +| `Ctrl / Cmd + Shift + C` | Copy | +| `Ctrl / Cmd + Shift + V` | Paste | +| `Ctrl / Cmd + Shift + X` | Paste selected text | +| `Ctrl / Cmd + Shift + F` | Find | +| `Ctrl / Cmd + Shift + K` | Clear screen | +| `Ctrl / Cmd + Shift + A` | Select all | -## Tabs & Sessions +## Tabs and workspace | Shortcut | Action | -|----------|--------| -| `Ctrl+Shift+N` | New SSH Session | -| `Ctrl+Shift+T` | New Local Terminal | -| `Ctrl+W` | Close Active Tab | -| `Ctrl+Tab` | Next Tab | -| `Ctrl+Shift+Tab` | Previous Tab | -| `Ctrl+1~9` | Switch to Tab 1-9 | +|--------|------| +| `Ctrl / Cmd + Shift + N` | New session | +| ``Ctrl / Cmd + ` `` | New local terminal | +| `Ctrl / Cmd + Shift + W` | Close current tab | +| `Ctrl + Tab` | Next tab | +| `Ctrl + Shift + Tab` | Previous tab | +| `Ctrl / Cmd + 1-8` | Jump to a specific tab | +| `Ctrl / Cmd + 9` | Jump to the last tab | -## View & Layout +## View and panels | Shortcut | Action | -|----------|--------| -| `Ctrl+B` | Toggle Left Sidebar | -| `Ctrl+Shift+B` | Toggle Right Sidebar | -| `Ctrl++` | Zoom In | -| `Ctrl+-` | Zoom Out | -| `Ctrl+0` | Reset Zoom | -| `F11` | Toggle Fullscreen | +|--------|------| +| `Ctrl / Cmd + Shift + E` | Toggle left activity bar / panel | +| `Ctrl / Cmd + Shift + B` | Toggle right activity bar / panel | +| `Ctrl / Cmd + =` | Zoom in | +| `Ctrl / Cmd + -` | Zoom out | +| `Ctrl / Cmd + 0` | Reset zoom | -## Special Features +## Special actions | Shortcut | Action | -|----------|--------| -| `Ctrl+,` | Open Settings | -| `Ctrl+L` | Lock Screen | +|--------|------| +| `Ctrl / Cmd + Shift + L` | Lock screen | +| `Ctrl / Cmd + ,` | Open settings | + +## Usage tips + +- If you often copy logs from the terminal, memorize `Ctrl / Cmd + Shift + C` +- If you frequently switch between remote and local sessions, `Ctrl / Cmd + Shift + N` and the new-local-terminal shortcut will be your fastest entry points +- If you rely on screen lock, remember `Ctrl / Cmd + Shift + L` :::tip -Shortcuts may vary by operating system. On macOS, `Ctrl` corresponds to `Cmd`. +Use the current app settings and UI as the source of truth for shortcuts. If a future version adds configurable shortcuts, prefer the in-app interaction settings over this page. ::: diff --git a/docs-site/i18n/en/docusaurus-plugin-content-docs/current/guide/layout-and-workspace.md b/docs-site/i18n/en/docusaurus-plugin-content-docs/current/guide/layout-and-workspace.md new file mode 100644 index 00000000..f9ce17d7 --- /dev/null +++ b/docs-site/i18n/en/docusaurus-plugin-content-docs/current/guide/layout-and-workspace.md @@ -0,0 +1,140 @@ +--- +sidebar_position: 2 +--- + +# Layout & Workspace + +Dragonfly is built around a composable workspace rather than a single terminal tab. You can open multiple sessions, split panes inside a tab, and keep common tools docked around the sides of the app. + +## Workspace areas + +A typical workspace is made up of these areas: + +- **Center area** — tabs and terminal panes +- **Left activity bar / panels** — file explorer, network, Security/Auth +- **Right activity bar / panels** — saved connections, active sessions, command history, resource monitor +- **Bottom helper area** — quick commands, serial send, recording, lock actions + +These areas are not isolated pages. They cooperate around the currently active session. + +## Tabs + +Each tab can hold a session, and each tab can also be split into multiple panes. + +Common tab actions include: + +- Creating a new session +- Closing the current tab +- Switching between tabs +- Renaming a tab +- Setting a tab color +- Duplicating the current session +- Reconnecting a session +- Viewing session details + +This makes Dragonfly a good fit for separating: + +- Different environments +- Different projects +- Different task phases + +## Split panes + +Right-click a tab to split the current session into: + +- **Horizontal Split** +- **Vertical Split** + +The panes still belong to the same tab, but each pane can hold its own independent session content. This is useful for: + +- Watching logs in one pane and running commands in another +- Comparing two hosts side by side +- Keeping a local terminal next to a remote SSH session +- Watching serial output while running SSH troubleshooting commands + +## Sessions and workspace structure + +There are two concepts that are easy to mix up: + +1. **Logical tabs / pane tree** — how a tab is split internally +2. **Runtime window layout** — where tabs are currently attached in the live workspace + +For day-to-day usage, the simple mental model is: + +- Tabs organize tasks +- Splits let you observe things side by side +- The active pane decides where input goes + +## Left and right panels + +### Left side + +The left side is mainly for capability entry points: + +- File explorer +- Network +- Security/Auth + +### Right side + +The right side is mainly for live state and navigation: + +- Saved connections +- Active sessions +- Command history +- Resource monitor + +If your workflow is "pick a connection, then inspect live state," this split feels natural. + +## Bottom helper area + +The bottom area is used for features that do not need to permanently occupy a sidebar, such as: + +- **Quick Commands** — reusable commands with variable prompts +- **Serial Send** — useful when repeatedly sending fixed text to a serial device +- **Recording** — start or stop session recording +- **Lock** — quickly lock the app + +This is one of the differences between Dragonfly and a basic multi-tab terminal: it organizes the actions around sessions, not just the terminal surface itself. + +## Child windows + +Some flows open dedicated child windows instead of replacing the main workspace, such as: + +- Settings +- New session / connection creation +- Quick command editing +- Auto-upload prompts + +This helps because it: + +- Avoids interrupting the main workspace +- Gives complex configuration its own focused space +- Makes screenshots and demos easier to structure + +## Recommended workflow combinations + +### Local + remote + +- Tab 1: SSH session to the target host +- Tab 2: Local Terminal for builds or Git commands +- Right panel: Command History + +### Dual-pane troubleshooting + +- Left pane: live logs +- Right pane: diagnostic commands +- Resource Monitor open to watch CPU / memory changes + +### File + terminal workflow + +- SSH terminal enters the target directory +- File explorer syncs to the same path +- Open a remote file, edit it locally, then upload it back + +:::tip Screenshot suggestion +- Suggested image path: `/img/docs/layout/quick-start-split-workspace.png` +- Show a split workspace with one SSH session and one Local Terminal +- Another good image path: `/img/docs/readme/main-workspace.png` +- Include the activity bars, center terminal area, and bottom helper area together +::: diff --git a/docs-site/i18n/en/docusaurus-plugin-content-docs/current/guide/otp-and-auth.md b/docs-site/i18n/en/docusaurus-plugin-content-docs/current/guide/otp-and-auth.md new file mode 100644 index 00000000..f31bea52 --- /dev/null +++ b/docs-site/i18n/en/docusaurus-plugin-content-docs/current/guide/otp-and-auth.md @@ -0,0 +1,109 @@ +--- +sidebar_position: 6 +--- + +# OTP & Authentication + +Dragonfly ties OTP management into the SSH authentication flow. You can manage OTP entries as reusable credentials, then bind them directly to SSH connections to reduce repeated input. + +## Supported OTP types + +Dragonfly currently supports: + +- **TOTP** +- **HOTP** + +When creating or editing an OTP entry, you can configure: + +- Issuer +- Username +- Secret +- Algorithm (`SHA-1`, `SHA-256`, `SHA-512`) +- Digits +- Period for TOTP +- Counter for HOTP + +## Where to manage OTP + +Open the **OTP** tab inside the **Security/Auth** panel. + +There you can: + +- Create OTP entries +- Edit existing entries +- Delete entries +- View current verification codes +- Import from a QR code image + +## Import from QR code + +If you already have an MFA / 2FA QR code, you can import the image directly. + +Typical flow: + +1. Click the QR import action in the OTP panel +2. Choose a local image file +3. Dragonfly parses and fills fields such as issuer, username, and secret +4. Confirm and save the OTP entry + +This is usually more convenient than manually retyping the secret. + +## Bind OTP to an SSH connection + +In the advanced section of the SSH connection form, you can select a saved OTP entry for that connection. + +After binding, you can: + +- Quickly inspect the current code during login +- Enable **auto-fill OTP** in compatible interactive authentication flows + +This is especially useful for environments that require password or private key plus a second factor. + +## OTP interaction during authentication + +When the SSH server enters a keyboard-interactive or OTP flow, Dragonfly shows an OTP dialog. + +The dialog includes: + +- The current connection name +- The prompts requested by the server +- A code panel if the connection is bound to an OTP entry + +You can then: + +- Enter the verification code manually +- Send the current OTP code into the prompt +- Submit or cancel the authentication attempt + +## Auto-fill OTP + +If an SSH connection is already bound to an OTP entry, you can enable **auto-fill OTP**. + +Good fits include: + +- Stable infrastructure environments +- Bastion hosts that always require OTP +- High-frequency operational logins + +It is best enabled only on connections whose authentication prompts you understand well, so you avoid filling the wrong value into an unexpected interactive prompt. + +## OTP with passwords and keys + +OTP does not replace passwords or private keys. It is used alongside them: + +- **Password + OTP** +- **Private key + OTP** + +A clean workflow is: + +1. Organize passwords, keys, and OTP entries in **Security/Auth** +2. Bind them to specific SSH connections afterward + +This keeps connection records cleaner and makes it easier to update credentials later. + +:::tip Screenshot suggestion +- Suggested image path: `/img/docs/security/otp-management.png` +- Show the OTP management page with TOTP / HOTP switching, QR import, and the code panel +- Another good image path: `/img/docs/security/otp-dialog.png` +- Show the OTP dialog during an SSH login flow +::: diff --git a/docs-site/i18n/en/docusaurus-plugin-content-docs/current/guide/quick-commands.md b/docs-site/i18n/en/docusaurus-plugin-content-docs/current/guide/quick-commands.md index 07df3713..9c94c834 100644 --- a/docs-site/i18n/en/docusaurus-plugin-content-docs/current/guide/quick-commands.md +++ b/docs-site/i18n/en/docusaurus-plugin-content-docs/current/guide/quick-commands.md @@ -4,50 +4,91 @@ sidebar_position: 4 # Quick Commands -Quick Commands let you save and execute frequent commands with a single click. +Quick Commands let you save common commands as reusable actions, then send them to the current terminal from inside the workspace. -## Create a Quick Command +## Good use cases -1. In the **Quick Commands** panel on the right sidebar, click **Add** -2. Fill in: +- Frequently repeated operational commands +- Deployment or troubleshooting scripts with parameters +- Organizing commands by product, environment, or team +- Placing risky commands into the prompt first so you can review them before execution + +## Create a quick command + +1. Open the **Quick Commands** area in the bottom helper section or side panel +2. Click **Add** +3. Fill in the command details in the dedicated child window + +Available fields include: | Field | Description | -|-------|-------------| +|------|------| | Label | Display name for the command | -| Category | Command category (e.g., K8s, Docker) | -| Description | Optional description | +| Category | Command grouping | +| Description | Optional note | | Color Tag | Custom display color | | Icon | Custom icon | -| Pin to Top | Show at the top of the list | -| Execution Mode | Execute immediately or append to prompt | -| Command Script | The command content | +| Pin to Top | Whether it stays near the top of the list | +| Execution Mode | Execute immediately or append to the input line | +| Command Script | The command text to send | -## Execution Modes +After saving, the command appears in the list and can still be edited or deleted later. -### Execute Immediately +## Execution modes -The command runs automatically in the terminal when clicked. Best for well-known, safe commands. +### Execute immediately -### Append to Prompt +Clicking the command sends it to the current terminal and runs it at once. Good for: -The command is placed at the terminal prompt for review before execution. Best for commands that need parameter verification. +- Well-understood routine commands +- Daily inspection tasks +- Fixed-format read-only queries -## Variable Substitution +### Append to prompt -Command scripts support `{{variableName}}` syntax for dynamic parameters: +Clicking the command only inserts it into the current input line without pressing Enter. Good for: + +- Commands whose parameters still need checking +- Script fragments that usually need a small edit +- Higher-risk operations that should be reviewed manually first + +## Variable prompts + +Command scripts support `{{variableName}}` placeholders for dynamic parameters, for example: ```bash docker exec -it {{container_name}} bash ``` -A dialog will prompt you to fill in variable values when executing. +When you run the command, Dragonfly opens a variable input dialog so the template can be completed before sending it. -## Category Management +## Categories, search, and pinned items -- Create categories to organize commands -- Filter by category using the dropdown next to the search bar -- Search or create new categories inline +The Quick Commands panel supports these management patterns: -## Search Commands +- Search by label, command content, or description +- Filter by category from the dropdown +- Keep pinned commands at the top +- Reuse existing categories when creating new commands -Type keywords in the search box to quickly filter the command list. +That makes it useful for organizing sets like: + +- Kubernetes +- Docker +- Database +- Release scripts +- Environment inspection + +## How it fits the workspace + +Quick Commands are not tied to one specific session type. As long as the current terminal can accept input, you can send commands to: + +- SSH sessions +- Local Terminal sessions +- Some serial workflows that need repeated fixed input + +Common combinations include: + +- Watching logs on one side while triggering diagnostics from Quick Commands on the other +- Running deploy commands remotely while building or using Git locally +- Turning variable-based commands into team-friendly templates diff --git a/docs-site/i18n/en/docusaurus-plugin-content-docs/current/guide/security.md b/docs-site/i18n/en/docusaurus-plugin-content-docs/current/guide/security.md index 7f01e534..58bf328c 100644 --- a/docs-site/i18n/en/docusaurus-plugin-content-docs/current/guide/security.md +++ b/docs-site/i18n/en/docusaurus-plugin-content-docs/current/guide/security.md @@ -4,63 +4,122 @@ sidebar_position: 7 # Security -Dragonfly provides multiple layers of security protection. +Dragonfly's security features mainly focus on three areas: -## Credential Storage +1. Safely storing local credentials and authentication materials +2. Managing host verification and second-factor flows during SSH login +3. Providing master-password and screen-lock protection in the desktop workspace -### System Keychain +## How sensitive local data is stored -Enable **Use OS Keyring** to securely store credentials in the OS native keychain: +Dragonfly stores connection-related configuration locally, but sensitive values are encrypted before being written to disk. Typical sensitive data includes: -- **macOS** — Keychain -- **Windows** — Credential Manager -- **Linux** — Secret Service (GNOME Keyring / KWallet) +- Saved passwords +- SSH private keys and key passphrases +- OTP secrets +- The persisted representation of the master password +- Proxy or other authentication materials that need protection -### Encrypted Storage +So in day-to-day use, you work with reusable password, key, and OTP entries rather than scattering plaintext secrets through config files. -All sensitive data (passwords, private keys, passphrases) is encrypted with **AES-256-GCM** before being stored locally. +## The Security/Auth panel -## Master Password +The **Security/Auth** panel in the left activity bar centralizes authentication-related records into three groups: -Enable **Require Master Password** to encrypt session data with a master password that must be entered on each application startup. +- **Keys** +- **Passwords** +- **OTP** -Configure in **Settings → Security → Authentication**. +This means you do not need to re-enter every secret in every connection. You save reusable entries first, then reference them from the connection form. -## Screen Lock +### SSH key management -### Manual Lock +Good for storing: -Click the **Lock** button in the status bar, or use the keyboard shortcut. +- Common login keys +- Keys protected by passphrases +- Multiple identities separated by environment -### Auto Lock +When you switch an SSH connection to **Private Key** authentication, you can pick from these saved keys directly. -When **Screen Lock Protection** is enabled, the app locks automatically: +### Password management -- On application startup -- After a configurable idle period (set to 0 to disable) +Good for storing: -### Unlock Password +- SSH passwords +- Proxy passwords +- Other credentials you need to reuse -An optional unlock password can be set. Without a password, a simple click unlocks. +In the SSH connection form, password authentication can reference these saved password entries directly. -## SSH Key Management +### OTP management -Manage SSH private keys in **Settings → Security → Key Management**: +OTP management supports: -- Import private key files -- Set key names and passphrases -- Delete unused keys +- **TOTP** +- **HOTP** +- Import from QR code images +- Viewing and generating current codes +- Binding OTP entries to SSH connections -Imported keys are encrypted before storage. +For details, see [OTP & Authentication](./otp-and-auth). -## Host Key Policy +## Master password -Control how unknown SSH host keys are handled: +The master password is Dragonfly's most important local desktop protection feature. + +You can configure it in **Settings → Security**. After it is set: + +- The app uses it for unlock verification +- Sensitive local configuration protection is built around it +- The lock screen requires it before unlocking + +If you have not set a master password, the lock screen is only a visual lock layer, not full password-based protection. + +## Screen lock + +### Manual lock + +You can trigger lock from the UI or by keyboard shortcut at any time. + +### Auto lock + +In **Settings → Security**, once screen lock is enabled, you can also configure the idle timeout: + +- `0` means no idle auto-lock +- Values greater than `0` trigger automatic lock after that many idle minutes + +### Unlock behavior + +- **With a master password** — entering the correct master password is required +- **Without a master password** — unlocking can happen directly + +If you plan to use Dragonfly on a shared machine or during demos, enabling both **master password** and **screen lock** is the safer setup. + +## SSH host key policies + +When SSH first connects to an unknown host, Dragonfly supports three policies: | Policy | Behavior | -|--------|----------| -| Prompt | Ask on first connection (default) | -| Accept | Automatically accept and record new keys | +|------|------| +| Prompt | Ask whether to trust the host key on first connect (default) | +| Accept | Automatically accept new host keys | | Strict | Reject all unknown host keys | -Known host keys are stored in `~/.dragonfly/known_hosts`. +Known host records are stored in `~/.dragonfly/known_hosts`. + +If host identity validation matters in your environment, prefer **Prompt** or **Strict** over unconditional acceptance. + +## Practical security advice + +- Prefer **private key + OTP** in production environments instead of relying on one password +- Enable both **master password** and **screen lock** on shared computers or demo machines +- Save **jump host** and **proxy** definitions explicitly for environments that depend on them +- Verify the source of a new host key before trusting it + +:::tip Screenshot suggestion +- Suggested image path: `/img/docs/security/security-settings.png` +- Show master password, screen lock, idle lock time, and host key policy +- Another good image path: `/img/docs/security/security-auth-panel.png` +- Show the Keys, Passwords, and OTP tabs in the Security/Auth panel +::: diff --git a/docs-site/i18n/en/docusaurus-plugin-content-docs/current/guide/session-types.md b/docs-site/i18n/en/docusaurus-plugin-content-docs/current/guide/session-types.md new file mode 100644 index 00000000..e6c4966f --- /dev/null +++ b/docs-site/i18n/en/docusaurus-plugin-content-docs/current/guide/session-types.md @@ -0,0 +1,121 @@ +--- +sidebar_position: 0 +--- + +# Session Types + +Dragonfly is not just an SSH client. It is a desktop app that puts multiple terminal workflows into one workspace. It currently supports four session types: + +- **SSH** +- **Local Terminal** +- **Telnet** +- **Serial** + +Understanding the differences helps explain why some panels or enhancements only appear for certain tabs. + +## At a glance + +| Session Type | Typical scenario | Key capabilities | +|--------------|------------------|------------------| +| SSH | Remote Linux / Unix administration | SFTP, OTP, resource monitoring, proxy, jump host, tunnels | +| Local Terminal | Local shell work, scripts, builds | Shared terminal UI, command history, split panes | +| Telnet | Legacy devices, lab environments, compatibility troubleshooting | Terminal workspace features, but not SSH-only features | +| Serial | Routers, switches, boards, embedded debug ports | Serial port settings plus terminal workspace features | + +## SSH + +SSH is the most capable session type in Dragonfly. It is the best fit when you need to: + +- Log in to remote Linux / Unix hosts +- Browse and transfer remote files +- Use OTP, jump hosts, or proxies +- Watch remote resource statistics +- Configure port tunnels + +If you need any of these, use **SSH** first: + +- File explorer +- Auto-upload / round-trip editing +- Remote resource monitoring +- SSH tunnels in the Network panel + +## Local Terminal + +Local Terminal is useful when you want your local shell workflow inside the same Dragonfly workspace, for example: + +- Running frontend or Rust builds locally +- Running scripts, reading logs, or using Git +- Comparing local and remote output side by side + +Its value is not remote access. Its value is that it shares the same workspace model as SSH sessions: + +- Tabs +- Split panes +- Terminal search +- Command history and suggestions +- Optional line numbers, timestamps, and highlighting + +When creating a local terminal, you can also choose: + +- The shell path, such as `powershell.exe`, `cmd.exe`, `bash`, or `wsl.exe` +- The working directory + +## Telnet + +Telnet is useful for: + +- Maintaining older equipment +- Lab environments +- Compatibility scenarios where SSH is not available + +You still get Dragonfly's terminal workspace model, but not SSH-specific security or file features. In practice, that usually means no: + +- SFTP file explorer +- OTP binding +- SSH jump host +- SSH resource monitoring + +If your goal is simply to open a traditional remote terminal quickly, Telnet can be the more direct choice. + +## Serial + +Serial sessions are useful for connecting to: + +- Network device console ports +- Routers and switches +- Development boards, embedded devices, and debug ports + +When creating a serial session, you can configure: + +- Port +- Baud rate +- Data bits +- Parity +- Stop bits + +Serial sessions still live inside Dragonfly's tabbed and split workspace, so you can watch serial output in one pane while running commands in an SSH or local terminal pane. + +## How to choose + +A simple rule of thumb: + +- Need the full remote workflow? Use **SSH** +- Need a local shell? Use **Local Terminal** +- Need a traditional remote terminal? Use **Telnet** +- Need a device console or debug port? Use **Serial** + +## Mix them in one workspace + +One of Dragonfly's strengths is that you can mix these session types in the same workspace, for example: + +- SSH on the left to watch remote logs +- Local Terminal on the right to run packaging or Git commands +- A Serial tab open to watch device boot output + +That is why some features are documented as session-specific. The workspace is shared, but the capability boundary still depends on the underlying session type. + +:::tip Screenshot suggestion +- Suggested image path: `/img/docs/session-types/new-session-tabs.png` +- Show the SSH / Local Terminal / Telnet / Serial tabs in the new-session window +- Keeping the default field areas visible helps readers understand the differences +::: diff --git a/docs-site/i18n/en/docusaurus-plugin-content-docs/current/guide/ssh-connection.md b/docs-site/i18n/en/docusaurus-plugin-content-docs/current/guide/ssh-connection.md index d431933e..7d30dc39 100644 --- a/docs-site/i18n/en/docusaurus-plugin-content-docs/current/guide/ssh-connection.md +++ b/docs-site/i18n/en/docusaurus-plugin-content-docs/current/guide/ssh-connection.md @@ -4,73 +4,159 @@ sidebar_position: 1 # SSH Connection Management -## Connection Configuration +SSH is still Dragonfly's most complete session type. Beyond a basic login, an SSH connection can also be tied to: -### Basic Information +- SFTP file explorer +- Remote resource monitoring +- Proxy +- Jump host +- OTP binding and auto-fill +- Port tunnels -| Field | Description | Required | -|-------|-------------|----------| -| Connection Name | Display name for identification | No | -| Icon | Custom icon | No | -| Group | Connection group | No | -| Host | Server IP or domain | Yes | -| Port | SSH port (default 22) | No | -| Username | Login username | Yes | -| Authentication | Password or private key | Yes | -| Description | Notes about the connection | No | +If you are new to Dragonfly, it usually makes sense to configure SSH first, then expand into file workflows, terminal enhancements, and network features. -### Authentication Methods +## Create an SSH connection -#### Password Authentication +In the **New Session** window, switch to the **SSH** tab and fill in these fields. -Enter the server password directly. Passwords are encrypted with AES-256-GCM before storage. +### Basic information -#### Key Authentication +| Field | Description | +|------|------| +| Connection Name | Display name in the saved-connections list | +| Host | Server IP or domain | +| Port | Defaults to `22` | +| Username | Login user | +| Icon | Helps distinguish services or environments | +| Group | Organizes connections into folders | +| Description | Notes about the environment or purpose | -Select an imported SSH private key. Supports RSA, Ed25519, and other common key formats. +### Authentication methods -Manage keys in **Settings → Security → Key Management**. +Dragonfly supports two common SSH authentication methods: -## Connection Groups +- **Password** +- **Private key** -Organize connections with folders: +You can select saved passwords or saved keys instead of re-entering them every time. -- Right-click the sidebar and select **New Folder** -- Support nested folders -- Drag connections into folders -- Right-click folders to rename or delete +#### Password authentication -## Sorting +Useful for: -Three sorting modes: +- Temporary test hosts +- Environments that have not issued private keys yet +- Accounts that are combined with OTP -- **Custom Order** — Manual drag-and-drop -- **Name A → Z** — Ascending alphabetical -- **Name Z → A** — Descending alphabetical +#### Private key authentication -## Import Sessions +Useful for: -Import sessions from other SSH clients: +- Daily operations work +- Reusing one identity across many hosts +- Workflows that involve jump hosts or automation -1. Right-click the sidebar and select **Import Sessions** -2. Select the source application (currently supports WindTerm) -3. Choose the session configuration file -4. Confirm import +Both passwords and keys can be managed centrally in **Security/Auth**. -## Host Key Verification +## Advanced configuration -Dragonfly uses TOFU (Trust On First Use) for host key management: +The advanced section is where an SSH connection goes from "can connect" to "fits a real daily workflow." -- **Prompt** — Ask on first connection (default) -- **Accept** — Automatically accept new host keys -- **Strict** — Reject all unknown host keys +### Proxy -Configure in **Settings → Security → Connection Security**. +If the connection must go through a proxy, you can select a saved proxy profile. -## Proxy Support +Supported proxy types: -Configure proxy in **Settings → Proxy**: +- **SOCKS5** +- **HTTP** -- SOCKS5 protocol support -- Configure proxy host and port -- Enable/disable proxy +A proxy record can store: + +- Name +- Protocol +- Host +- Port +- Username / password + +### Jump host + +If the target host is not directly reachable, you can pick another saved SSH connection as the **jump host**. + +Typical cases include: + +- Connecting through a bastion host +- Reaching internal production hosts +- Multi-hop SSH login chains + +### OTP binding + +If the environment requires a second-factor code, you can bind an OTP entry to the SSH connection. + +After binding, you can either: + +- Quickly inspect the code during login +- Enable **auto-fill OTP** for compatible interactive prompts + +This works well together with [OTP & Authentication](./otp-and-auth). + +## Manage saved connections + +After saving, the connection appears in the **Saved Connections** panel on the right. + +Common operations include: + +- Double-click to connect +- Organize by group +- Edit an existing connection +- Duplicate a connection as a template +- Reconnect from an existing saved source + +If you manage many hosts, using groups, icons, and descriptions helps separate environments, projects, and roles. + +## Import sessions from other clients + +Dragonfly can import session definitions from other terminal clients. Current supported imports are: + +- **Xshell** (`.xts`) +- **MobaXterm** (`.mxtsessions`) +- **WindTerm** (`.sessions`) + +After importing, it is a good idea to verify: + +- Host and port +- Username +- Whether proxy / jump host / OTP binding still needs to be added +- Whether saved passwords or keys are already matched correctly + +## Host key policy + +Dragonfly maintains known-host records and offers three SSH host key policies: + +| Policy | Behavior | +|------|------| +| Prompt | Ask whether to trust an unknown host key on first connect (default) | +| Accept | Automatically accept and record new host keys | +| Strict | Reject all unknown host keys | + +Known host records are stored in `~/.dragonfly/known_hosts`. + +If you operate in a stricter environment, verify the host key source before accepting it. + +## When should you choose SSH? + +SSH is the right first choice when: + +- You need the file explorer or SFTP +- You need OTP, jump hosts, proxies, or tunnels +- You need remote resource monitoring +- You want a saved connection you can reuse long term + +If you only want a local shell inside Dragonfly, use **Local Terminal** from [Session Types](./session-types) instead. + +:::tip Screenshot suggestion +- Suggested image path: `/img/docs/session-types/ssh-advanced-form.png` +- Show the SSH form with host, authentication, and the advanced area for proxy / jump host / OTP binding +- Another good image path: `/img/docs/network/ssh-import-and-groups.png` +- Show saved-connection groups and the import entry +::: diff --git a/docs-site/i18n/en/docusaurus-plugin-content-docs/current/guide/terminal.md b/docs-site/i18n/en/docusaurus-plugin-content-docs/current/guide/terminal.md index b5ed75b2..96c807a7 100644 --- a/docs-site/i18n/en/docusaurus-plugin-content-docs/current/guide/terminal.md +++ b/docs-site/i18n/en/docusaurus-plugin-content-docs/current/guide/terminal.md @@ -4,96 +4,160 @@ sidebar_position: 3 # Terminal Features -Dragonfly provides a feature-rich terminal emulator powered by xterm.js. +Dragonfly's terminal experience is designed around high-frequency local and remote work inside one workspace. It is built on xterm.js, but the practical experience goes beyond a terminal canvas: search, command history, suggestions, optional enhancements, recording, and SSH-aware helpers are all part of it. -## Rendering +## Core operations -### Hardware Acceleration +### Search, copy, and the context menu -WebGL rendering is enabled by default, leveraging the GPU for smooth scrolling and output. - -Toggle in **Settings → Terminal → Hardware Acceleration**. - -### Font Configuration - -- **Font Family** — Multiple fallback fonts, primary font has highest priority -- **Font Size** — Terminal and UI font sizes are independently adjustable -- **Font Ligatures** — Enable programming font ligature support - -Built-in fonts include JetBrains Mono and Noto Sans SC. System fonts are also available. - -### Cursor Styles - -Three cursor styles: -- Block -- Underline -- Bar - -Cursor blink can be toggled on/off. - -## Terminal Operations - -### Context Menu - -Right-click in the terminal for: +The terminal context menu exposes these frequent actions directly: - Copy / Paste - Paste selected text - Find text - Search selected text online -- Translate selected text +- Translate selected text with a provider - Clear screen / Clear all - Select all -### Scrollback Buffer +In **Settings → Interaction**, you can also adjust: -The terminal retains a configurable number of history lines (default 1000). Scroll up with the mouse wheel. +- **Copy on select** +- **Right-click paste** +- Word separators +- Default character encoding -Adjust in **Settings → Terminal → Scrollback Buffer**. +### Scrollback and fonts -### Clipboard +- The default scrollback buffer keeps **10000 lines** +- You can customize font family, font size, ligatures, cursor style, and cursor blink +- **Hardware acceleration** is optional and is **not enabled by default**; you can toggle it manually in **Settings → Terminal** if you want to compare rendering behavior -- **Copy on Select** — Automatically copy selected text to clipboard -- **Right-click Paste** — Paste clipboard content on right-click +## Command history and suggestions -Configure in **Settings → Interaction**. +Dragonfly provides two related helpers for session workflows. -## Keyword Highlighting +### Command history -### Built-in Rules +- Commands entered in the terminal are recorded automatically +- Fuzzy search is supported +- You can review history from the **Command History** panel on the right -Automatically highlights common patterns including: -- Date/time formats -- Numbers -- Error/warning keywords +### Input suggestions -Built-in rules adapt to the current theme automatically. +While typing, Dragonfly can suggest commands based on history. This is useful for repeated operational commands, build commands, and troubleshooting scripts. -### Custom Rules +## Optional terminal enhancements -Add custom rules in **Settings → Terminal → Keyword Highlighting**: +These features are intentionally opt-in rather than enabled all at once. -1. Set a rule name -2. Choose a highlight color -3. Add matching patterns (regex supported), one per line +### Line numbers and timestamp gutter -Custom rules take priority over built-in rules. +In **Settings → Terminal**, you can enable: -## Command History +- **Show line numbers** +- **Show timestamps** -Commands are automatically recorded per session, searchable via fuzzy matching in the **Command History** panel. +When enabled, a gutter appears on the left side of terminal output. It is especially useful for long logs, command output, and recorded sessions. -## Auto-Complete Suggestions +### Action links -The terminal shows command suggestions based on history while typing. +Action links are off by default. When enabled, Dragonfly can detect and open patterns such as: -## Keep-Alive +- IPv4 addresses like `192.168.1.10` +- `host:port` pairs like `db.internal:5432` +- Archive names like `backup.tar.gz` -Configure SSH Keep-Alive interval to prevent idle disconnections: +Notes: -- Set in **Settings → Terminal → Keep-Alive Interval** -- Set to 0 to disable +- First enable **Action Links** in **Settings → Terminal** +- Opening a link requires **Ctrl / Cmd + click** to avoid conflicts with normal text selection +- The three matcher groups can be enabled or disabled separately -## Remote Resource Monitoring +### Keyword highlighting -Enable **Show Remote Resource Stats** in **Settings → Terminal** to display CPU and memory usage of the active SSH host in the status bar, updated every 10 seconds. +Keyword highlighting is also off by default. After enabling it, Dragonfly applies built-in rules and then overlays your custom rules. + +The built-in rules cover more than error keywords. They also include: + +- Common state words such as error / warn / success / info / debug +- Dates and times +- Numbers, sizes, and durations +- Structured text such as addresses, URLs, UUIDs, and versions + +You can define your own rules with: + +- A custom rule name +- Separate colors for dark and light themes +- One matching pattern per line +- An option to continue matching across wrapped lines + +### Large-output protection + +When a session produces too much output too quickly, Dragonfly can enter a temporary protection mode so the terminal remains responsive. + +During that period, the app temporarily suppresses some expensive decorations and reports how many queued characters were skipped. Once pressure drops, normal rendering resumes. This is mainly intended for log storms or constantly streaming output. + +## SSH-specific helpers + +### Keep-Alive + +For SSH sessions, you can configure a Keep-Alive interval in **Settings → Terminal**: + +- Default is **60 seconds** +- Set it to `0` to disable it +- Useful for reducing idle disconnects on long-lived sessions + +### Remote resource monitoring + +Remote resource monitoring is not shown globally by default. To use it, both of these must be true: + +1. The current tab is an **SSH session** +2. **Show Remote Resource Stats** is enabled in **Settings → Terminal** + +When enabled, the **Resource Monitor** panel polls the host on the configured interval. The default interval is **3 seconds**, and you can change it manually. + +The panel displays: + +- Hostname, OS, architecture, uptime +- Load average +- CPU usage +- Memory usage +- Network throughput + +## Translation and online search + +After selecting text in the terminal, you can use the context menu to: + +- Send the selection to an online search engine +- Open a translation dialog with an enabled translation provider + +Provider visibility depends on settings: + +- **Google** and **Microsoft** work without extra credentials +- **DeepL / Baidu / Alibaba / Youdao** appear after you enter credentials in **Settings → Translation** + +## Recording and workflow combinations + +Dragonfly supports session recording, which is useful for: + +- Preserving troubleshooting steps +- Sharing a reproducible path with teammates +- Capturing terminal examples with visible timing + +If you are preparing screenshots or demos, a good combination is: + +- Line numbers / timestamp gutter +- Keyword highlighting +- Action links +- Command history +- Resource monitor + +That usually gives a more realistic screenshot than showing one toggle in isolation. + +:::tip Screenshot suggestion +- Suggested image path: `/img/docs/terminal/gutter-line-numbers-timestamps.png` +- Enable line numbers and timestamps in **Settings → Terminal**, then run `scripts/demo-terminal-gutter.sh` +- Another good image path: `/img/docs/terminal/action-links-and-highlights.png` +- Enable action links and keyword highlighting, then run `scripts/demo-terminal-output.sh` and `scripts/demo-action-links.sh` +::: diff --git a/docs-site/i18n/en/docusaurus-plugin-content-docs/current/guide/themes.md b/docs-site/i18n/en/docusaurus-plugin-content-docs/current/guide/themes.md index 1ff40db1..99992097 100644 --- a/docs-site/i18n/en/docusaurus-plugin-content-docs/current/guide/themes.md +++ b/docs-site/i18n/en/docusaurus-plugin-content-docs/current/guide/themes.md @@ -4,47 +4,71 @@ sidebar_position: 5 # Themes & Appearance -Dragonfly supports highly customizable interface appearance. +Dragonfly lets you tune the workspace appearance in fairly fine detail, including UI theme, terminal theme, fonts, and cursor behavior. -## Theme Switching +## UI theme and terminal theme -Select a color theme in **Settings → Appearance → Theme**. Supports dark and light modes. +In **Settings → Appearance**, you can configure these separately: -Also accessible via **View → Theme** menu. +- **UI Theme** — controls the app-wide color scheme +- **Terminal Theme** — controls terminal colors, or can follow the UI theme -## Zoom +If you just want a quick theme switch, you can also use **View → Theme** from the top menu. -- **Zoom In** — `Ctrl++` or **View → Zoom In** -- **Zoom Out** — `Ctrl+-` or **View → Zoom Out** -- **Reset** — `Ctrl+0` or **View → Reset Zoom** +## Fonts and font size -## Panel Layout +In **Settings → Appearance**, you can adjust: -The interface uses a three-column layout with resizable panels: +- **Font family** — primary font plus multi-level fallback fonts +- **Terminal font size** +- **UI font size** -- **Left Sidebar** — Saved connections, active sessions, command history -- **Center Area** — Terminal tabs -- **Right Sidebar** — File explorer, file transfer, quick commands +Dragonfly includes these built-in fonts: -Reset to default via **View → Reset Panel Layout**. +- `JetBrains Mono` +- `Noto Sans SC Variable` +- `Inter` -## Fullscreen +System-installed fonts are also listed so you can extend the fallback chain. -Press `F11` or use **View → Fullscreen**. +## Cursor and ligatures -## Language +Appearance settings also expose terminal details such as: -Switch interface language in **Settings → Appearance → Language**: +- **Cursor style** — Block / Underline / Bar +- **Cursor blink** +- **Font ligatures** + +If you switch between dark and light themes often, it is worth checking the terminal theme together with keyword highlighting and action links so the overall result stays readable. + +## Language switching + +Dragonfly currently provides: - Simplified Chinese - English -## Font Configuration +You can switch language in either of these places: -Configure fonts in **Settings → Appearance**: +- **Settings → General → Language** +- **View → Language** in the top menu -- **Font Family** — Terminal and UI fonts with multi-level fallback -- **Terminal Font Size** — Terminal text size in pixels -- **UI Font Size** — Interface text size in pixels +## Panels and workspace appearance -Built-in fonts include JetBrains Mono and Noto Sans SC. System-installed fonts are also listed. +Besides colors and fonts, the workspace itself can be tuned to match your habits: + +- Left and right panel widths are resizable +- Split ratios inside a tab are resizable +- Left and right activity bars can be shown or hidden quickly with shortcuts + +These layout states are saved with app settings, which makes it practical to keep a preferred long-term workspace arrangement. + +## Zoom and quick adjustments + +Dragonfly provides these common shortcuts: + +- **Zoom In** — `Ctrl / Cmd + =` +- **Zoom Out** — `Ctrl / Cmd + -` +- **Reset Zoom** — `Ctrl / Cmd + 0` + +These are especially useful for demos, screen sharing, or high-DPI displays. diff --git a/docs-site/i18n/en/docusaurus-plugin-content-docs/current/guide/translation.md b/docs-site/i18n/en/docusaurus-plugin-content-docs/current/guide/translation.md index b5358785..e66e6150 100644 --- a/docs-site/i18n/en/docusaurus-plugin-content-docs/current/guide/translation.md +++ b/docs-site/i18n/en/docusaurus-plugin-content-docs/current/guide/translation.md @@ -4,31 +4,55 @@ sidebar_position: 6 # Translation -Dragonfly includes a multi-engine text translation feature for quickly translating unfamiliar text in the terminal. +Dragonfly includes multi-provider text translation, which is useful for quickly translating logs, errors, command descriptions, or any unfamiliar text you see in the terminal. -## Usage +## How to use it 1. Select text in the terminal -2. Right-click and choose **Translate** -3. The translation result appears in a popup window +2. Right-click to open the context menu +3. Open the **Translate** submenu +4. Choose one of the available providers +5. Read the result in the popup dialog -## Supported Engines +The dialog shows: -| Engine | Configuration Required | -|--------|----------------------| -| Google Translate | No configuration needed | -| Microsoft Translate | No configuration needed | -| DeepL | API Key required | -| Baidu Translate | App ID + App Key required | -| Alibaba Translate | App ID + App Key required | -| Youdao Translate | App ID + App Key required | +- The original text +- The translated result +- The detected source language, when provided +- A one-click copy action for the translated text -## Configuration +## Which providers appear -Configure in **Settings → Translation**: +Not every provider is always shown in the terminal context menu. -- **Provider** — Select the default translation engine -- **Target Language** — Set the translation target language -- **API Credentials** — Enter API credentials for engines that require them +### Available out of the box -Google and Microsoft Translate work out of the box with no configuration needed. +These providers do not require extra setup: + +- **Google** +- **Microsoft** + +### Shown after credentials are configured + +These providers appear only after credentials are entered in **Settings → Translation**: + +- **DeepL** +- **Baidu** +- **Alibaba** +- **Youdao** + +## Translation settings + +In **Settings → Translation**, you can configure: + +- **Target language** +- **API credentials** for each provider + +One important detail: the settings page mainly manages target language and credentials. It does **not** define one permanent default provider for all translation actions. The actual provider is still chosen from the terminal context menu when you translate. + +## Good use cases + +- Quickly understanding English errors or third-party logs +- Reading mixed-language output more efficiently +- Comparing translated operational notes or config comments +- Translating selected output before forwarding it to a teammate diff --git a/docs-site/i18n/en/docusaurus-plugin-content-docs/current/guide/tunnels-and-proxy.md b/docs-site/i18n/en/docusaurus-plugin-content-docs/current/guide/tunnels-and-proxy.md new file mode 100644 index 00000000..0fa31cd7 --- /dev/null +++ b/docs-site/i18n/en/docusaurus-plugin-content-docs/current/guide/tunnels-and-proxy.md @@ -0,0 +1,134 @@ +--- +sidebar_position: 5 +--- + +# Tunnels, Proxy, and Jump Hosts + +Dragonfly separates network-related features into three layers: + +1. **Proxy** — how the app reaches the network +2. **Jump host** — which SSH host acts as the intermediate hop +3. **Tunnel** — where port traffic is mapped + +These features often appear together in real environments, but they solve different problems. + +## Proxy + +A proxy helps Dragonfly establish outbound connectivity to the remote side. + +Currently supported: + +- **SOCKS5** +- **HTTP** + +Each proxy configuration can store: + +- Name +- Protocol +- Host +- Port +- Username / password + +Proxies are managed centrally in the Network panel, then selected from the advanced section of an SSH connection. + +Typical use cases: + +- Corporate networks that require outbound proxy access +- Regions where direct access is restricted +- Teams that want a reusable set of outbound network profiles + +## Jump hosts + +A jump host is SSH-specific. It does not replace a proxy. Instead, it uses another saved SSH connection as the intermediate entry point. + +Typical use cases: + +- Bastion hosts +- Internal hosts that are not directly reachable +- Multi-layer SSH network isolation + +In the SSH connection advanced section, you can pick an existing saved SSH connection as the jump host. + +## Tunnels + +Dragonfly provides a dedicated tunnel management area in the Network panel, so port mappings can be saved and reused instead of retyped as one-off commands. + +### Tunnel types + +- **Local tunnel** +- **Remote tunnel** +- **Dynamic tunnel (SOCKS5)** + +### Local tunnel + +A local tunnel binds a local listening port and forwards traffic to a remote target. It is useful for: + +- Accessing internal databases +- Opening web consoles that are only reachable from the remote host +- Securely forwarding service ports through SSH + +### Remote tunnel + +A remote tunnel binds a port on the remote side and forwards it back to a local service. It is useful for: + +- Temporarily exposing a local service to the remote environment +- Reverse debugging or temporary integration work + +### Dynamic tunnel + +A dynamic tunnel creates a local SOCKS5 proxy port. It is useful for: + +- Pointing a browser or tool at an SSH-backed proxy temporarily +- Quickly building an outbound path through SSH + +## Tunnel configuration + +When creating a tunnel, you typically configure: + +- Tunnel name +- Tunnel type +- Associated SSH connection +- Listen port +- Target host / target port for local and remote tunnels +- Whether to bind only to `127.0.0.1` +- Whether to auto-open the tunnel + +If the port only needs to be used locally, keeping it bound to `127.0.0.1` is usually safer than listening on `0.0.0.0`. + +## Daily operations in the Network panel + +In the Network panel, you can: + +- Create / edit / delete proxies +- Create / edit / delete tunnels +- Open or close a tunnel directly +- See whether a tunnel is currently active + +This turns network setup into something reusable and visible instead of a collection of one-off shell commands. + +## Common combinations + +### Example 1: Proxy + SSH + +- Save a SOCKS5 proxy in the Network panel +- Select that proxy in an SSH connection's advanced section +- Useful in corporate or cross-region network environments + +### Example 2: Jump host + target host + +- Save the bastion connection first +- Set that bastion as the jump host on the target host connection +- Useful for layered internal network access + +### Example 3: SSH + local tunnel + +- Create the SSH connection +- Save a local tunnel such as `localhost:15432 -> db.internal:5432` +- Then access the database locally via `127.0.0.1:15432` + +:::tip Screenshot suggestion +- Suggested image path: `/img/docs/network/network-panel.png` +- Show the proxy and tunnel tabs in the Network panel +- Another good image path: `/img/docs/network/tunnel-dialog.png` +- Show tunnel type, local listening port, target host, and auto-open options +::: diff --git a/docs-site/i18n/en/docusaurus-plugin-content-docs/current/intro.md b/docs-site/i18n/en/docusaurus-plugin-content-docs/current/intro.md index 3ab2773e..47bb335a 100644 --- a/docs-site/i18n/en/docusaurus-plugin-content-docs/current/intro.md +++ b/docs-site/i18n/en/docusaurus-plugin-content-docs/current/intro.md @@ -5,33 +5,68 @@ slug: / # Introduction -**Dragonfly** is a modern, high-performance SSH client built with [Tauri](https://tauri.app/) and [React](https://react.dev/). It combines a polished user interface with a powerful Rust backend, providing developers and system administrators with an excellent remote server management experience. +**Dragonfly** is a desktop client built around remote terminal workflows. It pairs a Tauri + React interface with a Rust backend that handles SSH, SFTP, session lifecycle, tunnels, authentication, and config persistence, so you can work with remote servers, local shells, serial devices, and network helpers inside one workspace. -## Key Features +## Where Dragonfly fits best -- **Secure & Fast SSH** — Powered by Rust's `russh` library for native-level performance -- **Multi-Tab Interface** — Manage multiple SSH and local terminal sessions simultaneously -- **Session Management** — Save, organize, and quickly connect to frequently used servers -- **Integrated File Explorer** — Browse and manage remote files via SFTP directly from the sidebar -- **Command History** — Automatically recorded with fuzzy search support -- **Quick Commands** — One-click execution of frequent commands with variable substitution -- **Customizable UI** — Resizable panels with dark/light theme support -- **Cross-Platform** — Windows, macOS, and Linux +- Managing multiple SSH hosts at the same time +- Switching between local terminals, Telnet sessions, and serial devices during troubleshooting +- Working with remote files while watching terminal output +- Standardizing common operations with reusable commands, jump-host chains, and saved connection metadata +- Using OTP, recording, resource monitoring, and auto-upload in the same desktop app -## Tech Stack +## Core capabilities -| Layer | Technology | -|-------|-----------| -| Frontend | React 19, TypeScript, Vite, TailwindCSS 4 | -| Backend | Tauri 2, Rust | -| Terminal | xterm.js (WebGL accelerated) | -| SSH | russh (pure Rust SSH implementation) | -| File Transfer | russh-sftp (pipelined transfers) | +### Multiple session types -## Why Dragonfly? +Dragonfly supports more than SSH: -1. **Native Performance** — Rust backend ensures high-performance SSH and file transfers -2. **Security First** — AES-256-GCM encrypted credential storage with system keychain support -3. **Modern UI** — Polished interface built with React and TailwindCSS -4. **Lightweight** — Tauri-based, much smaller than Electron apps -5. **Open Source** — MIT licensed, fully open source +- **SSH** — remote login, file transfer, resource monitoring, tunnels, OTP, and related workflows +- **Local Terminal** — open a local shell inside the same workspace +- **Telnet** — support for legacy systems and lab environments +- **Serial** — useful for network gear, embedded boards, and debug ports + +### Composable workspace + +- Multi-tab workflow for different tasks and environments +- **Horizontal and vertical splits** inside a tab +- Left and right activity bars for file explorer, network, Security/Auth, saved connections, active sessions, command history, and resource monitor panels +- Bottom helper areas for quick commands, serial send, recording, and lock controls +- Separate child windows for settings, new-session, quick-command editing, and auto-upload prompts + +### Terminal-focused enhancements + +- Command history and fuzzy suggestions +- Terminal search, copy/paste, and context actions +- **Online search** and **translation** from selected terminal text +- Optional **line-number / timestamp gutter** +- Optional **action links** for IPv4 addresses, `host:port`, and archive names +- Optional **keyword highlighting** with built-in presets and custom rules +- Large-output protection, session recording, and SSH keep-alive + +### Remote file and transfer workflows + +- Built-in SFTP file explorer for SSH sessions +- Upload, download, rename, move, delete, properties, and symlink actions +- Transfer queue with pause, resume, cancel, retry, timestamp preservation, and configurable concurrency +- Open a remote file in a local editor, then send changes back through the watcher-driven auto-upload flow + +### Security and networking + +- Passwords, private keys, host-key policies, and encrypted local storage +- OTP management with TOTP/HOTP, QR import, and SSH auto-fill support +- Proxy configs, jump hosts, and local / remote / dynamic tunnels +- Screen lock and master-password support + +## Suggested reading order + +If you are new to Dragonfly, this order works well: + +1. [Quick Start](./getting-started/quick-start) +2. [Session Types](./guide/session-types) +3. [SSH Connection Management](./guide/ssh-connection) +4. [Layout and Workspace](./guide/layout-and-workspace) +5. [Terminal Features](./guide/terminal) +6. [SFTP File Transfer](./guide/file-transfer) +7. [Tunnels and Proxy](./guide/tunnels-and-proxy) +8. [OTP and Authentication](./guide/otp-and-auth)