From 5e1e592d87315606cfecb5b87605dc2fc2af8a0f Mon Sep 17 00:00:00 2001 From: Kang Date: Mon, 13 Apr 2026 15:05:48 +0800 Subject: [PATCH] docs: update README and user guides to enhance clarity on Dragonfly's features, session types, and terminal capabilities; add new sections for workspace layout, security, and network configurations --- README.md | 152 ++++++++++------ docs-site/docs/faq.md | 137 +++++++++----- docs-site/docs/getting-started/quick-start.md | 106 +++++++---- docs-site/docs/guide/file-transfer.md | 134 +++++++++----- docs-site/docs/guide/keyboard-shortcuts.md | 59 ++++-- docs-site/docs/guide/layout-and-workspace.md | 140 ++++++++++++++ docs-site/docs/guide/otp-and-auth.md | 109 +++++++++++ docs-site/docs/guide/security.md | 122 +++++++++---- docs-site/docs/guide/session-types.md | 123 +++++++++++++ docs-site/docs/guide/ssh-connection.md | 172 +++++++++++++----- docs-site/docs/guide/terminal.md | 168 ++++++++++------- docs-site/docs/guide/tunnels-and-proxy.md | 134 ++++++++++++++ docs-site/docs/intro.md | 87 ++++++--- 13 files changed, 1280 insertions(+), 363 deletions(-) create mode 100644 docs-site/docs/guide/layout-and-workspace.md create mode 100644 docs-site/docs/guide/otp-and-auth.md create mode 100644 docs-site/docs/guide/session-types.md create mode 100644 docs-site/docs/guide/tunnels-and-proxy.md diff --git a/README.md b/README.md index 49922390..6493e649 100644 --- a/README.md +++ b/README.md @@ -1,86 +1,124 @@
Dragonfly Logo -

Dragonfly is a modern, high-performance SSH client

+

Dragonfly is a modern remote terminal workspace built with Tauri and Rust

-## ✨ Features +## Overview -- **🚀 Robust SSH Client**: Secure and fast SSH connections powered by Rust's `russh`. -- **📑 Multi-Tab Interface**: Manage multiple active sessions simultaneously in a tabbed interface. -- **💾 Session Management**: Save, organize, and edit your frequently used server connections for quick access. -- **📂 Integrated File Explorer**: Browse, upload, and download files on your remote servers directly from the sidebar. -- **📜 Command History**: Automatically save and easily access your command history. -- **⚡ Quick Commands**: store and execute your most frequent commands with a single click. -- **🎨 Customizable UI**: Resizable panels for File Explorer, Saved Connections, and Command History to fit your workflow. -- **🌗 Theme Support**: Fully supported Dark and Light modes. -- **🖥️ Cross-Platform**: Optimized for Windows, macOS, and Linux. +Dragonfly is a desktop client for SSH-centric operations and mixed terminal workflows. It combines a React + Tauri interface with a Rust backend so you can manage remote hosts, local shells, file transfers, authentication, and network tooling from one workspace. -## 🛠️ Tech Stack +## Highlights -- **Frontend**: [React 19](https://react.dev/), [TypeScript](https://www.typescriptlang.org/), [Vite](https://vitejs.dev/), [TailwindCSS 4](https://tailwindcss.com/) -- **Backend**: [Tauri 2](https://tauri.app/), [Rust](https://www.rust-lang.org/) -- **Terminal**: [xterm.js](https://xtermjs.org/) -- **Icons**: [Material Icons](https://fonts.google.com/icons) +### Sessions and workspace -## 🚀 Getting Started +- SSH, Local Terminal, Telnet, and Serial session support +- Multi-tab workspace with horizontal and vertical pane splits +- Saved connections with folders, icons, duplication, reconnect, and import tools +- Child windows for settings, new-session, quick-command, and auto-upload flows + +### Terminal experience + +- Search bar, command history, fuzzy suggestions, and context actions +- Optional line numbers and timestamps gutter for dense terminal output +- Optional action links for IPv4 addresses, `host:port`, and archive filenames +- Optional keyword highlighting with built-in presets and custom rules +- Session recording, configurable scrollback, and SSH keep-alive +- Remote resource monitor for active SSH sessions + +### Remote operations + +- Built-in SFTP file explorer with upload, download, rename, move, delete, and properties +- Transfer queue with retry, resume, timestamp preservation, and configurable concurrency +- Open remote files in a local editor and upload changes back through the watcher flow +- Quick Commands with categories, colors, icons, and variable prompts + +### Security and networking + +- Password auth, private keys, host-key verification, and local credential encryption +- OTP management with TOTP/HOTP, QR import, and SSH auto-fill support +- Screen lock, master password support, and known-hosts management +- Proxy configs, SSH jump hosts, and local / remote / dynamic tunnels + +## Supported session types + +| Type | Typical use | Notes | +|------|-------------|-------| +| SSH | Linux / Unix remote servers | Supports SFTP, OTP, resource monitor, proxy, jump host, tunnels | +| Local Terminal | Local shell workflows | Uses your local shell path and working directory | +| Telnet | Legacy network devices / lab systems | Lightweight terminal session without SSH-only features | +| Serial | Routers, boards, embedded devices | Configurable port, baud rate, parity, stop bits | + +## Documentation map + +The detailed user docs live in `docs-site/`. + +- Product overview: [docs-site/docs/intro.md](docs-site/docs/intro.md) +- Quick start: [docs-site/docs/getting-started/quick-start.md](docs-site/docs/getting-started/quick-start.md) +- Guides: [docs-site/docs/guide/](docs-site/docs/guide) +- Development docs: [docs-site/docs/development/](docs-site/docs/development) + +## Screenshot placeholders + +If you want to add screenshots later, these are the recommended stable asset paths to use in the docs site: + +- `docs-site/static/img/docs/readme/main-workspace.png` — main workspace with split panes and both side panels +- `docs-site/static/img/docs/readme/session-types.png` — new-session window showing SSH / Local / Telnet / Serial tabs +- `docs-site/static/img/docs/readme/terminal-features.png` — gutter, action links, and highlight demo output +- `docs-site/static/img/docs/readme/network-and-security.png` — proxy / tunnel / OTP related UI + +## Tech stack + +| Layer | Technology | +|------|------------| +| Frontend | React 19, TypeScript, Vite, TailwindCSS 4 | +| Desktop runtime | Tauri 2 | +| Backend | Rust | +| Terminal | xterm.js | +| SSH | russh | +| File transfer | russh-sftp | + +## Getting started ### Prerequisites -Ensure you have the following installed on your machine: - -- **Node.js**: v18 or newer recommended. -- **Rust**: The latest stable version (via [rustup](https://rustup.rs/)). -- **Tauri CLI**: (Optional) `npm install -g @tauri-apps/cli`. +- Node.js 18+ +- Rust stable via [rustup](https://rustup.rs/) +- pnpm recommended ### Installation -1. **Clone the repository**: - ```bash - git clone https://github.com/yourusername/dragonfly.git - cd dragonfly - ``` +```bash +git clone https://git.coderkang.top/Tauri/dragonfly.git +cd dragonfly +pnpm install +``` -2. **Install dependencies**: - ```bash - npm install - # or - pnpm install - # or - yarn install - ``` - -### 💻 Development - -Start the development server with hot-module replacement (HMR): +### Run the app in development ```bash -npm run tauri dev -# or pnpm tauri dev -# or -yarn tauri dev ``` -This will start the Vite dev server and launch the Tauri application window. - -### 📦 Build - -Build the application for production: +### Run the docs site locally ```bash -npm run tauri build -# or -pnpm tauri build -# or -yarn tauri build +pnpm --dir docs-site start ``` -The build artifacts will be located in `src-tauri/target/release/bundle`. +### Build -## 🤝 Contributing +```bash +pnpm build +pnpm tauri build +pnpm --dir docs-site build +``` -Contributions are welcome! Please feel free to submit a Pull Request. +The desktop bundles are generated under `src-tauri/target/release/bundle`. -## 📄 License +## Contributing + +Please read the docs under [docs-site/docs/development/](docs-site/docs/development) before contributing. + +## License [MIT](LICENSE) diff --git a/docs-site/docs/faq.md b/docs-site/docs/faq.md index 83878e02..5984c5b4 100644 --- a/docs-site/docs/faq.md +++ b/docs-site/docs/faq.md @@ -4,84 +4,125 @@ sidebar_position: 100 # 常见问题 -## 连接问题 +## 会话与连接 -### SSH 连接超时怎么办？ +### SSH 能连，本地终端 / Telnet / 串口为什么行为不一样？ -1. 检查服务器地址和端口是否正确 -2. 确认服务器的 SSH 服务是否正在运行 -3. 检查防火墙是否允许 SSH 端口 -4. 如果使用代理，确认代理配置是否正确 -5. 尝试增加 Keep-Alive 间隔（**设置 → 终端 → Keep-Alive 间隔**） +因为 Dragonfly 支持多种会话类型，但能力并不完全相同： -### 连接后终端没有响应？ +- **SSH**：功能最完整，支持 SFTP、OTP、资源监控、代理、跳板机、隧道 +- **本地终端**：只负责本地 shell 工作流 +- **Telnet**：轻量远程终端，不包含 SSH 专属能力 +- **串口**：用于串口调试，不属于 SSH 网络链路 -- 尝试按 `Enter` 键 -- 检查用户认证是否成功 -- 查看应用日志（**帮助 → 查看日志**） +如果你希望使用文件浏览器、远程资源监控或 OTP，请确认当前打开的是 **SSH 会话**。 -### 如何使用私钥连接？ +### 为什么某些会话没有文件浏览器？ -1. 前往 **设置 → 安全 → 密钥管理** -2. 点击 **添加密钥**，导入私钥文件 -3. 创建连接时，认证方式选择 **私钥**，然后选择对应的密钥 +文件浏览器基于 SFTP，因此只会在 **SSH 会话** 下可用。 + +以下类型不会提供远程文件浏览器： + +- 本地终端 +- Telnet +- 串口 + +### 为什么没有看到远程资源监控？ + +请同时检查两件事： + +1. 当前标签是否为 **SSH 会话** +2. 是否已在 **设置 → 终端** 中开启 **显示远程资源信息** + +资源监控默认是关闭的。 + +### 串口列表为空怎么办？ + +先确认： + +- 设备已经连接到系统 +- 当前系统已经识别该串口 +- 串口未被其他工具独占 + +切换到串口标签并重新展开端口下拉时，Dragonfly 会重新加载可用串口列表。 + +## 终端体验 + +### 为什么动作链接不能点击？ + +通常有两种原因： + +1. 你还没有在 **设置 → 终端** 中启用 **动作链接** +2. 点击时没有使用 **Ctrl / Cmd + 点击** + +动作链接默认关闭，而且为了避免误触，打开链接时需要配合修饰键。 + +### 为什么看不到关键词高亮？ + +关键词高亮默认关闭。请先到 **设置 → 终端** 中启用它，再确认当前输出里确实包含可匹配的文本。 + +### 为什么行号和时间戳没有显示？ + +这两项也都是按需开启的可选增强项，需要在 **设置 → 终端** 中分别打开。 ## 文件传输 -### 上传/下载速度慢？ +### 打开远程文件后，为什么没有弹出自动上传提示？ -Dragonfly 使用管道化传输优化了大文件传输速度。如果速度仍然不理想，可能是网络带宽限制。 +自动上传提示只会在下面这种流程里出现： -### 无法删除文件？ +1. 你从 SSH 文件浏览器中对远程文件执行 **打开** +2. Dragonfly 下载该文件到本地临时目录并启动监听 +3. 你在本地编辑器里保存这个文件 -检查当前用户是否有该文件的删除权限。可在文件属性中查看权限信息。 +如果你是自己另外复制了一个文件再编辑，Dragonfly 不会知道它和远端文件之间的关系。 -## 界面问题 +### 文件浏览器为什么没有跟着 `cd` 自动切换目录？ -### 界面字体显示异常？ +自动跟随依赖会话的终端路径跟踪能力。如果当前会话不支持，自动同步会被关闭；这时你仍然可以手动执行同步。 -1. 前往 **设置 → 外观 → 字体系列** -2. 确认首选字体已正确安装 -3. 添加备选字体作为回退 +### 上传 / 下载保存到哪里？ -### 终端渲染卡顿？ +取决于你的传输设置： -尝试在 **设置 → 终端** 中： -- 开启或关闭 **硬件加速**（需要重启应用） -- 减少 **回滚缓冲区** 行数 +- 如果启用了“每次询问保存位置”，每次下载都会让你选择路径 +- 否则会使用默认下载目录 -### 如何重置界面布局？ +你也可以在设置里修改默认下载目录和默认编辑器。 -通过菜单 **视图 → 重置面板布局** 恢复默认布局。 +## 安全与认证 -## 安全相关 +### 锁屏后为什么不需要输入密码也能解锁？ -### 忘记了主密码怎么办？ +这是因为你启用了锁屏，但**还没有设置主密码**。 -主密码用于加密会话数据。如果忘记，需要删除 `~/.dragonfly/` 目录下的配置文件重新配置。 +当前实现中： -:::warning 注意 -删除配置文件将丢失所有已保存的连接和密钥。 -::: +- 有主密码：锁屏后必须输入主密码 +- 没有主密码：可以直接点击解锁 -### 忘记了锁屏密码怎么办？ +### 忘记主密码怎么办？ -可以手动编辑 `~/.dragonfly/settings.json` 文件，将锁屏相关配置项重置。 +当前没有内建的“找回主密码”流程。如果本地数据已经受主密码保护，而你又无法提供正确密码，那么相关敏感配置将无法按原方式继续使用。 -## 其他 +在手动处理前，建议先备份 `~/.dragonfly/` 目录，再决定如何重建本地配置。 -### 如何导入其他 SSH 客户端的会话？ +### OTP 应该在哪里管理？ -目前支持从 WindTerm 导入： +请到 **Security/Auth** 面板中的 **OTP** 标签页统一管理；创建或编辑 SSH 连接时，再把某个 OTP 条目绑定到具体连接。 -1. 右键点击侧边栏选择 **导入会话** -2. 选择 WindTerm -3. 选择 WindTerm 的会话配置文件 +## 导入与迁移 -### 配置文件在哪里？ +### 可以从哪些客户端导入会话？ -所有配置文件存储在 `~/.dragonfly/` 目录下，包括连接、密钥、设置等。 +目前支持： -### 如何查看应用日志？ +- Xshell（`.xts`） +- MobaXterm（`.mxtsessions`） +- WindTerm（`.sessions`） -通过菜单 **帮助 → 查看日志** 打开日志文件。日志按天轮转，保留最近 7 天的记录。 +导入后建议检查用户名、端口、认证方式，以及是否需要补充代理 / 跳板机 / OTP。 + +### Dragonfly 的配置文件存放在哪里？ + +应用配置位于 `~/.dragonfly/` 目录下，其中会保存设置、连接、密钥、OTP、隧道、代理、历史等本地数据。 diff --git a/docs-site/docs/getting-started/quick-start.md b/docs-site/docs/getting-started/quick-start.md index 4340e9c6..582ee2be 100644 --- a/docs-site/docs/getting-started/quick-start.md +++ b/docs-site/docs/getting-started/quick-start.md @@ -4,51 +4,95 @@ sidebar_position: 2 # 快速开始 -本章将引导你完成第一个 SSH 连接的创建和使用。 +本章帮助你在最短路径内体验 Dragonfly 的核心工作流：创建连接、打开会话、使用分屏、查看文件、启用终端增强功能。 -## 创建 SSH 连接 +## 第一步：选择会话类型 -1. 点击左侧边栏中的 **新建连接** 按钮，或使用菜单 **文件 → 新建 SSH 连接** -2. 在弹出的对话框中填写： - - **连接名称** — 给连接取一个便于识别的名称 - - **主机** — 服务器的 IP 地址或域名 - - **端口** — SSH 端口，默认 22 - - **用户名** — 登录用户名 - - **认证方式** — 选择密码或私钥 -3. 点击 **保存** 保存连接配置 +点击 **新建连接**，你会看到四类可选会话： -## 连接服务器 +- **SSH** — 最完整的远程运维场景 +- **本地终端** — 直接在 Dragonfly 中打开本地 shell +- **Telnet** — 适合旧系统或实验环境 +- **串口** — 适合串口调试设备 -在左侧边栏的已保存连接列表中，双击连接名称或右键选择 **连接** 即可开始 SSH 会话。 +如果你只是第一次体验，建议优先创建一个 **SSH** 会话，再额外创建一个 **本地终端** 对比工作区效果。 -连接成功后，你会在中央区域看到一个新的终端标签页。 +## 第二步：创建第一个 SSH 连接 -## 基本操作 +在新建连接窗口中填写： -### 多标签管理 +- **连接名称** — 便于识别的显示名称 +- **主机** 与 **端口** +- **用户名** +- **认证方式** — 密码或私钥 -- 你可以同时打开多个 SSH 连接，每个连接占一个标签页 -- 使用 `Ctrl+Tab` 切换标签页 -- 使用 `Ctrl+W` 关闭当前标签页 +如有需要，还可以展开高级区域配置： -### 文件浏览 +- 代理 +- 跳板机 +- OTP 绑定与自动填充 +- 图标、分组、描述等元数据 -连接成功后，右侧文件浏览器会自动显示远程文件系统： +保存后，连接会出现在已保存连接列表中。 -- 浏览目录结构 -- 上传/下载文件 -- 右键菜单进行文件操作（重命名、删除、移动等） +## 第三步：启动并理解工作区 -### 命令历史 +双击已保存连接，或者右键选择连接，即可启动会话。 -Dragonfly 会自动记录你输入的命令，你可以通过模糊搜索快速找到之前使用过的命令。 +连接建立后，你会看到： -## 创建本地终端 +- **中央区域** — 当前终端标签页 +- **左侧活动栏** — 文件浏览器、网络、Security/Auth 等面板入口 +- **右侧活动栏** — 已保存连接、活动会话、命令历史、资源监控等入口 +- **底部区域** — 快捷命令、串口发送、录制、锁屏等辅助区域 -除了 SSH 连接，你还可以通过菜单 **终端 → 新建本地终端** 创建本地 Shell 会话。 +## 第四步：试试这些高频能力 -## 下一步 +### 1. 再打开一个本地终端 -- 了解 [SSH 连接管理](../guide/ssh-connection) 的更多选项 -- 学习使用 [SFTP 文件传输](../guide/file-transfer) -- 配置 [快捷命令](../guide/quick-commands) 提升效率 +使用快捷键 ``Ctrl/Cmd + ` `` 或菜单入口创建本地终端，这样你可以在一个应用里同时看本地和远程环境。 + +### 2. 试一次终端分屏 + +在标签页上右键，选择： + +- **水平分屏** +- **垂直分屏** + +这适合同时观察日志、执行命令和对照不同主机输出。 + +### 3. 打开远程文件浏览器 + +SSH 会话激活后，文件浏览器面板可直接浏览远程目录，并支持上传、下载、删除、移动、属性查看等操作。 + +### 4. 打开命令历史和快捷命令 + +- **命令历史** 适合回溯与模糊检索 +- **快捷命令** 适合保存固定操作，并支持变量输入 + +### 5. 启用终端增强项 + +可在 **设置 → 终端** 中按需打开： + +- 行号 +- 时间戳 +- 动作链接 +- 关键词高亮 +- 远程资源监控 + +这些能力默认更偏保守，需要你按场景开启。 + +## 第五步：按你的场景继续深入 + +- 想了解不同会话差异：查看 [会话类型](../guide/session-types) +- 想配置认证、代理、跳板机：查看 [SSH 连接管理](../guide/ssh-connection) +- 想管理文件与自动回传：查看 [SFTP 文件传输](../guide/file-transfer) +- 想了解终端增强与录制：查看 [终端功能](../guide/terminal) +- 想配置 OTP：查看 [OTP 与认证](../guide/otp-and-auth) + +:::tip 截图建议 +- 推荐图片路径：`/img/docs/session-types/new-session-tabs.png` +- 建议展示内容：新建连接窗口中 SSH / 本地终端 / Telnet / 串口四个标签 +- 另一个推荐图片路径：`/img/docs/layout/quick-start-split-workspace.png` +- 建议先执行：连接一个 SSH 会话，再新建一个本地终端并对标签页做一次分屏 +::: diff --git a/docs-site/docs/guide/file-transfer.md b/docs-site/docs/guide/file-transfer.md index 5f9c55f0..ed3cecab 100644 --- a/docs-site/docs/guide/file-transfer.md +++ b/docs-site/docs/guide/file-transfer.md @@ -4,74 +4,126 @@ sidebar_position: 2 # SFTP 文件传输 -Dragonfly 内置了功能完善的 SFTP 文件管理器，让你无需额外工具即可管理远程文件。 +Dragonfly 的远程文件能力建立在 SSH 会话之上。也就是说，**文件浏览器、SFTP 传输、远程文件本地编辑后回传** 都只在 SSH 会话中可用；本地终端、Telnet、串口不会显示这一套能力。 ## 文件浏览器 -连接 SSH 会话后，右侧边栏会显示远程文件浏览器： +连接 SSH 会话后，文件浏览器面板可以直接浏览远程目录。 -- 自动定位到用户主目录 -- 点击文件夹进入，点击上方 **返回上级** 按钮返回 -- 点击路径栏可直接输入路径跳转 -- 支持自动同步终端当前路径 +你会得到这些基础能力： -### 文件操作 +- 自动进入远端用户主目录 +- 进入文件夹、返回上级、手动输入路径跳转 +- 刷新当前目录 +- 与终端当前工作目录同步 +- 在不支持路径跟踪的会话中关闭自动同步 -右键点击文件或文件夹，可执行以下操作： +## 常见文件操作 + +在文件列表或右键菜单中，你可以执行： | 操作 | 说明 | |------|------| -| 打开 | 在默认编辑器中打开文件 | -| 下载 | 下载文件到本地 | -| 重命名 | 重命名文件或文件夹 | -| 移动 | 将文件移动到指定路径 | -| 删除 | 删除文件或文件夹（递归） | -| 属性 | 查看文件详细信息 | -| 复制路径 | 复制文件的完整路径 | +| 打开 | 下载到本地临时目录后，用默认编辑器打开 | +| 上传文件 | 选择本地文件上传到当前目录 | +| 上传文件夹 | 整个目录上传到当前远端路径 | +| 下载 | 下载单个文件或整个目录 | +| 重命名 | 修改远端名称 | +| 移动 | 把文件或目录移动到新路径 | +| 删除 | 删除文件或目录 | +| 属性 | 查看大小、时间、UID/GID、权限等信息 | +| 新建文件 / 文件夹 / 符号链接 | 在当前目录中直接创建 | -### 新建文件和文件夹 +其中“打开”并不只是只读预览，而是为后续本地修改后回传做准备。 -在工具栏中可以： +## 上传与下载 -- 新建文件 -- 新建文件夹 -- 新建符号链接 +### 上传 -## 文件上传 +可通过工具栏或右键菜单把本地文件上传到当前目录。 -点击工具栏的 **上传** 按钮，选择本地文件上传到当前目录。 +- 多个文件会逐个加入传输流程 +- 上传目录时会保留目录结构 +- 对 SSH 场景适合拿来同步脚本、配置文件或发布包 -也可以通过右键菜单选择 **上传到当前文件夹**。 +### 下载 -## 文件下载 +下载时有两种常见工作方式： -选中文件后，点击工具栏的 **下载** 按钮，或右键选择 **下载**。 +- 使用默认下载目录，直接保存到固定位置 +- 每次都询问保存位置，适合临时排障或按任务分类归档 -Dragonfly 使用管道化传输技术，同时维持多个并发数据块读取，大幅提升大文件传输速度。 +目录下载与文件下载都支持，远端目录会落到你选择的本地目标目录中。 -## 传输进度 +## 传输面板与传输设置 -在右侧边栏的 **文件传输** 面板中，可以查看所有传输任务的实时进度： +Dragonfly 会把上传 / 下载任务统一放进传输队列中，便于你查看： -- 传输中的文件名和进度 -- 已完成的传输 -- 传输错误 +- 当前进度 +- 成功与失败状态 +- 同时进行中的任务 -可以一键清除已完成的传输记录。 +在设置中还可以按需调整传输相关策略，例如： -## 路径同步 +- 上传 / 下载线程数 +- 冲突时的处理策略 +- 是否保留时间戳 +- 是否继续断点传输 +- 默认下载路径 +- 默认打开远程文件所使用的本地编辑器 -文件浏览器支持与终端路径同步： +## 与终端路径同步 -- **手动同步** — 点击同步按钮，将文件浏览器定位到终端当前目录 -- **自动同步** — 开启后，文件浏览器会自动跟随终端的工作目录变化 +文件浏览器可以和当前 SSH 终端的工作目录配合使用： -## 文件属性 +- **手动同步**：把浏览器直接跳到终端当前路径 +- **自动同步**：终端 `cd` 到新目录后，文件浏览器自动跟随 -右键点击文件选择 **属性**，可查看： +这对边跑命令边查文件非常有用，例如你在终端里进入某个发布目录后，文件浏览器会更容易保持在同一位置。 + +## 本地编辑后自动回传 + +这是 Dragonfly 很适合文档截图和真实运维场景的一项能力。 + +### 工作方式 + +1. 在 SSH 文件浏览器中对远程文件执行 **打开** +2. Dragonfly 先把文件下载到本地临时目录 +3. 同时启动文件监听 +4. 你在本地编辑器里保存后，应用会弹出上传提示窗口 + +### 上传提示窗口 + +文件被修改后，你可以选择： + +- **上传一次** +- **始终上传** +- **取消** + +如果你对某个文件选择了“始终上传”，那么在**当前会话内**后续再次保存时会直接回传，不再重复询问。 + +### 适合的使用场景 + +- 修改远程配置文件 +- 调整部署脚本 +- 打开日志或状态文件做本地分析 +- 为文档准备“编辑后回传”的演示截图 + +## 文件属性与权限 + +在 **属性** 中可以查看： - 文件大小 -- 修改时间和访问时间 +- 修改时间、访问时间 - 所有者和组 -- 权限（用户/组/其他，八进制表示） -- UID 和 GID +- UID / GID +- 权限的八进制表示 + +如果你的流程需要先核对权限再替换文件，这里会比单纯依赖 `ls -l` 更直观。 + +:::tip 截图建议 +- 推荐图片路径：`/img/docs/file-transfer/remote-file-browser.png` +- 建议连接一个 SSH 会话后，在文件浏览器中展示目录树、工具栏与右键菜单 +- 另一个推荐图片路径：`/img/docs/file-transfer/auto-upload-dialog.png` +- 建议先打开一个远程文本文件，再在本地编辑器中保存一次以触发自动上传提示 +::: diff --git a/docs-site/docs/guide/keyboard-shortcuts.md b/docs-site/docs/guide/keyboard-shortcuts.md index 044c2f2b..5a1179f0 100644 --- a/docs-site/docs/guide/keyboard-shortcuts.md +++ b/docs-site/docs/guide/keyboard-shortcuts.md @@ -4,44 +4,63 @@ sidebar_position: 8 # 快捷键 -Dragonfly 提供丰富的快捷键支持，提升操作效率。 +Dragonfly 的快捷键分成两类理解最不容易混淆： + +1. **应用级快捷键**：切换面板、开新会话、复制终端内容等 +2. **Shell 级按键**：直接发送给远端或本地 shell，例如常见的 `Ctrl+C` + +如果你想复制终端里的文本，请优先使用 Dragonfly 的应用级快捷键，而不是假设 shell 里的快捷键会变成复制。 + +## 约定 + +- 下表中的 **Ctrl / Cmd** 表示：Windows / Linux 使用 `Ctrl`，macOS 使用 `Cmd` +- `Ctrl+Tab` 与 `Ctrl+Shift+Tab` 保持当前实现写法 ## 终端操作 | 快捷键 | 功能 | |--------|------| -| `Ctrl+C` | 复制选中文本 / 发送中断信号 | -| `Ctrl+V` | 粘贴 | +| `Ctrl / Cmd + Shift + C` | 复制 | +| `Ctrl / Cmd + Shift + V` | 粘贴 | +| `Ctrl / Cmd + Shift + X` | 粘贴选中的文本 | +| `Ctrl / Cmd + Shift + F` | 查找 | +| `Ctrl / Cmd + Shift + K` | 清屏 | +| `Ctrl / Cmd + Shift + A` | 全选 | -## 标签与会话 +## 标签与工作区 | 快捷键 | 功能 | |--------|------| -| `Ctrl+Shift+N` | 新建 SSH 会话 | -| `Ctrl+Shift+T` | 新建本地终端 | -| `Ctrl+W` | 关闭当前标签 | -| `Ctrl+Tab` | 下一个标签 | -| `Ctrl+Shift+Tab` | 上一个标签 | -| `Ctrl+1~9` | 切换到标签 1-9 | +| `Ctrl / Cmd + Shift + N` | 新建会话 | +| ``Ctrl / Cmd + ` `` | 新建本地终端 | +| `Ctrl / Cmd + Shift + W` | 关闭当前标签 | +| `Ctrl + Tab` | 切换到下一个标签 | +| `Ctrl + Shift + Tab` | 切换到上一个标签 | +| `Ctrl / Cmd + 1-9` | 跳转到指定标签 | -## 视图与布局 +## 视图与面板 | 快捷键 | 功能 | |--------|------| -| `Ctrl+B` | 切换左侧边栏 | -| `Ctrl+Shift+B` | 切换右侧边栏 | -| `Ctrl++` | 放大 | -| `Ctrl+-` | 缩小 | -| `Ctrl+0` | 重置缩放 | -| `F11` | 切换全屏 | +| `Ctrl / Cmd + Shift + E` | 切换左侧活动栏 / 面板 | +| `Ctrl / Cmd + Shift + B` | 切换右侧活动栏 / 面板 | +| `Ctrl / Cmd + =` | 放大界面 | +| `Ctrl / Cmd + -` | 缩小界面 | +| `Ctrl / Cmd + 0` | 重置缩放 | ## 特殊功能 | 快捷键 | 功能 | |--------|------| -| `Ctrl+,` | 打开设置 | -| `Ctrl+L` | 锁定屏幕 | +| `Ctrl / Cmd + Shift + L` | 锁定屏幕 | +| `Ctrl / Cmd + ,` | 打开设置 | + +## 使用建议 + +- 如果你经常在终端里复制日志，优先记住 `Ctrl / Cmd + Shift + C` +- 如果你会同时管理远程与本地会话，`Ctrl / Cmd + Shift + N` 与 ``Ctrl / Cmd + ` `` 会是最常用的两个入口 +- 如果你使用锁屏功能，建议同时记住 `Ctrl / Cmd + Shift + L` :::tip 提示 -快捷键可能因操作系统不同而有所差异。macOS 上 `Ctrl` 对应 `Cmd` 键。 +快捷键列表以当前设置页展示的实现为准。如果未来版本新增可配置快捷键，请以应用内设置中的“交互”页面为最新信息源。 ::: diff --git a/docs-site/docs/guide/layout-and-workspace.md b/docs-site/docs/guide/layout-and-workspace.md new file mode 100644 index 00000000..9ad6d105 --- /dev/null +++ b/docs-site/docs/guide/layout-and-workspace.md @@ -0,0 +1,140 @@ +--- +sidebar_position: 2 +--- + +# 工作区与布局 + +Dragonfly 的核心体验不是“单个终端标签页”，而是一个可组合的工作区：你可以同时打开多个会话、拆分多个窗格，并把常用面板固定在左右两侧。 + +## 工作区的组成 + +典型工作区由几部分组成： + +- **中央区域**：标签页与终端窗格 +- **左侧活动栏 / 面板**：文件浏览器、网络、Security/Auth +- **右侧活动栏 / 面板**：已保存连接、活动会话、命令历史、资源监控 +- **底部辅助区域**：快捷命令、串口发送、录制、锁定 + +这些区域不是固定死的单一页面，而是围绕当前活跃会话动态协作。 + +## 标签页 + +每个标签页都可以承载一个会话，也可以继续拆分成多个窗格。 + +你可以对标签页执行这些常见操作： + +- 新建会话 +- 关闭当前标签 +- 在标签之间切换 +- 自定义标签名 +- 给标签设置颜色 +- 复制当前会话 +- 重新连接会话 +- 查看会话信息 + +这让 Dragonfly 很适合用来区分： + +- 不同环境 +- 不同项目 +- 不同任务阶段 + +## 分屏能力 + +在标签页上右键，可以把当前会话拆成： + +- **水平分屏** +- **垂直分屏** + +分屏后的窗格仍然属于同一个标签页，但每个窗格都能承载自己独立的会话内容。适合的场景包括： + +- 一个窗格看日志，一个窗格执行命令 +- 并排比较两台主机状态 +- 左边本地终端，右边远程 SSH +- 串口输出和 SSH 排障命令同时观察 + +## 会话与工作区的关系 + +工作区里有两个容易混淆的概念： + +1. **逻辑标签页 / 窗格树**：决定一个标签内部如何分屏 +2. **运行时窗口布局**：决定不同标签当前挂在哪个工作区叶子位置 + +对普通使用者来说，可以简单理解成： + +- 标签页负责组织任务 +- 分屏负责并排观察 +- 活动窗格决定当前命令发往哪里 + +## 左右侧面板 + +### 左侧 + +左侧更偏“能力入口”，通常包括： + +- 文件浏览器 +- 网络 +- Security/Auth + +### 右侧 + +右侧更偏“运行态信息”，通常包括： + +- 已保存连接 +- 活动会话 +- 命令历史 +- 资源监控 + +如果你的工作流是“先选连接，再看运行状态”，这种左右分工会很自然。 + +## 底部辅助区域 + +工作区底部用于承载一些不适合一直占满侧栏的能力，例如： + +- **快捷命令**：保存可复用命令片段并支持变量输入 +- **串口发送**：适合频繁向串口设备发固定文本 +- **录制**：开始或停止当前会话录制 +- **锁定**：快速锁屏 + +这也是 Dragonfly 和“普通多标签终端”差异较大的地方：它不是只让你开终端，而是把会话周边动作也组织到工作区里。 + +## 子窗口 + +某些操作会打开独立子窗口，而不是把所有内容都塞进主界面，例如： + +- 设置 +- 新建连接 +- 快捷命令编辑 +- 自动上传提示 + +这样做的好处是： + +- 不打断主工作区当前会话 +- 复杂配置可以独立完成 +- 演示和截图时结构更清晰 + +## 推荐的工作流组合 + +### 组合一：本地 + 远程 + +- 标签 1：SSH 登录远程主机 +- 标签 2：本地终端执行构建或 Git 命令 +- 右侧打开命令历史 + +### 组合二：双窗格排障 + +- 左窗格：实时日志 +- 右窗格：执行诊断命令 +- 再打开资源监控观察 CPU / 内存变化 + +### 组合三：文件 + 终端联动 + +- SSH 终端进入目标目录 +- 文件浏览器同步到当前路径 +- 打开远程文件，本地编辑后自动回传 + +:::tip 截图建议 +- 推荐图片路径：`/img/docs/layout/quick-start-split-workspace.png` +- 建议展示一个 SSH 会话 + 一个本地终端的分屏工作区 +- 另一个推荐图片路径：`/img/docs/readme/main-workspace.png` +- 建议同时包含左侧活动栏、右侧面板、中心终端与底部辅助区 +::: diff --git a/docs-site/docs/guide/otp-and-auth.md b/docs-site/docs/guide/otp-and-auth.md new file mode 100644 index 00000000..fe67eb01 --- /dev/null +++ b/docs-site/docs/guide/otp-and-auth.md @@ -0,0 +1,109 @@ +--- +sidebar_position: 6 +--- + +# OTP 与认证 + +Dragonfly 把 OTP 管理和 SSH 认证流程结合在了一起：你既可以把 OTP 当作一个独立的验证码仓库来管理，也可以把它直接绑定到 SSH 连接中，减少重复输入。 + +## 支持的 OTP 类型 + +当前支持： + +- **TOTP** +- **HOTP** + +创建或编辑 OTP 条目时，可以配置： + +- issuer +- username +- secret +- 算法（SHA-1 / SHA-256 / SHA-512） +- 位数 +- 周期（TOTP） +- 计数器（HOTP） + +## 在哪里管理 OTP + +请打开 **Security/Auth** 面板中的 **OTP** 标签页。 + +你可以在这里： + +- 新建 OTP 条目 +- 编辑已有条目 +- 删除条目 +- 查看验证码 +- 从二维码图片导入 + +## 从二维码导入 + +如果你已经有 MFA / 2FA 的二维码，可以直接导入图片文件。 + +典型流程： + +1. 在 OTP 面板中点击二维码导入 +2. 选择本地图片文件 +3. Dragonfly 解析后自动填充 issuer、username、secret 等信息 +4. 确认后保存为一个 OTP 条目 + +这比手动抄写 secret 更适合日常管理，也更适合批量整理认证资料。 + +## 绑定到 SSH 连接 + +在 SSH 连接表单的高级区域中，可以为连接选择一个已保存的 OTP 条目。 + +绑定后你可以： + +- 在认证时快速查看当前验证码 +- 在支持的交互流程中启用 **自动填充 OTP** + +这非常适合需要“密码 / 私钥 + 二次验证码”组合认证的环境。 + +## 认证弹窗中的 OTP 交互 + +当 SSH 服务器进入 keyboard-interactive / OTP 流程时，Dragonfly 会弹出 OTP 对话框。 + +对话框中会显示： + +- 当前连接名称 +- 服务端要求输入的提示项 +- 如果该连接绑定了 OTP，还会显示验证码面板 + +你可以： + +- 手动输入验证码 +- 直接把当前 OTP 验证码发送到输入框 +- 提交或取消本次认证 + +## 自动填充 OTP + +如果某个 SSH 连接已经绑定了 OTP 条目，还可以启用 **自动填充 OTP**。 + +适合场景： + +- 固定资产环境 +- 跳板机 / 堡垒机需要验证码 +- 高频重复登录的运维场景 + +建议只对你明确掌握认证流程的连接开启，避免在不兼容的交互提示上产生误填。 + +## 与密码 / 私钥的关系 + +OTP 不是替代密码或私钥，而是和它们配合使用： + +- **密码 + OTP** +- **私钥 + OTP** + +因此更推荐的管理方式是： + +1. 在 Security/Auth 中先分别整理好密码、私钥、OTP +2. 再在具体 SSH 连接中绑定这些材料 + +这样连接配置会更干净，也更方便后续统一替换认证信息。 + +:::tip 截图建议 +- 推荐图片路径：`/img/docs/security/otp-management.png` +- 建议展示 OTP 管理页中的 TOTP / HOTP 切换、二维码导入入口和验证码面板 +- 另一个推荐图片路径：`/img/docs/security/otp-dialog.png` +- 建议展示 SSH 登录过程中弹出的 OTP 输入对话框 +::: diff --git a/docs-site/docs/guide/security.md b/docs-site/docs/guide/security.md index 6f30c83e..5dbfa8c5 100644 --- a/docs-site/docs/guide/security.md +++ b/docs-site/docs/guide/security.md @@ -4,63 +4,121 @@ sidebar_position: 7 # 安全功能 -Dragonfly 提供多层安全保护机制。 +Dragonfly 的安全能力主要围绕三件事展开： -## 凭据存储 +1. 安全保存本地凭据与认证材料 +2. 管理 SSH 连接过程中的主机校验与二次认证 +3. 在桌面端工作区中提供锁屏与主密码保护 -### 系统密钥链 +## 本地敏感数据的保存方式 -启用 **使用系统凭据管理器** 后，凭据将安全地存储在操作系统原生的密钥链中： +Dragonfly 会在本地保存连接相关配置，并对敏感内容做加密处理后再写入配置文件。常见的敏感数据包括： -- **macOS** — Keychain -- **Windows** — Credential Manager -- **Linux** — Secret Service (GNOME Keyring / KWallet) +- 已保存密码 +- SSH 私钥与私钥口令 +- OTP 密钥 +- 主密码本身的持久化表示 -### 加密存储 +因此，平时使用时你看到的是“可以复用的密码 / 私钥 / OTP 条目”，而不是明文直接散落在普通文本配置里。 -所有敏感数据（密码、私钥、密码短语）均使用 **AES-256-GCM** 加密后存储在本地配置文件中。 +## Security/Auth 面板 + +左侧活动栏中的 **Security/Auth** 面板集中管理认证相关内容，分为三类： + +- **密钥** +- **密码** +- **OTP** + +这意味着你不需要在每个连接里重复录入所有敏感信息，而是先把凭据存成可复用条目，再在连接表单中引用。 + +### SSH 密钥管理 + +适合保存： + +- 常用登录私钥 +- 需要密码短语的私钥 +- 按环境区分的多个身份 + +创建 SSH 连接时，认证方式切换到 **私钥** 后，就可以直接选择已保存的密钥。 + +### 密码管理 + +适合保存： + +- SSH 密码 +- 代理密码 +- 需要重复复用的口令条目 + +在 SSH 连接表单中，密码认证也会直接引用这里的已保存密码。 + +### OTP 管理 + +OTP 管理支持： + +- **TOTP** +- **HOTP** +- 从二维码图片导入 +- 查看并生成当前验证码 +- 绑定到具体 SSH 连接 + +详细使用方式见 [OTP 与认证](./otp-and-auth)。 ## 主密码 -启用 **需要主密码** 后，会话数据将使用主密码加密，每次启动应用时必须输入主密码才能解密。 +主密码是 Dragonfly 桌面端最重要的一项本地保护能力。 -在 **设置 → 安全 → 系统认证与加密** 中配置。 +你可以在 **设置 → 安全** 中设置主密码。设置后： + +- 应用会用它来校验解锁 +- 本地敏感配置的保护会围绕它展开 +- 锁屏界面会要求输入这个密码才能解锁 + +如果你没有设置主密码，后续锁屏就只是一层界面遮罩，而不是严格意义上的密码保护。 ## 屏幕锁定 ### 手动锁定 -点击状态栏的 **锁定** 按钮，或使用快捷键锁定屏幕。 +你可以随时从界面中的锁定入口或快捷键触发锁屏。 ### 自动锁定 -启用 **屏幕锁定保护** 后，应用会在以下情况自动锁定： +在 **设置 → 安全** 中开启屏幕锁定后，还可以配置空闲分钟数： -- 应用启动时 -- 空闲一段时间后（可配置分钟数，设为 0 禁用） +- `0` 表示不使用空闲自动锁定 +- 大于 `0` 时，空闲达到设定时间后自动进入锁屏界面 -### 解锁密码 +### 解锁行为 -可设置解锁密码。如果不设置密码，点击即可解锁。 +- **已设置主密码**：必须输入正确主密码才能解锁 +- **未设置主密码**：可以直接点击解锁 -## SSH 密钥管理 +如果你准备把 Dragonfly 用在共享办公环境或演示现场，建议把“主密码 + 屏幕锁定”一起开启。 -在 **设置 → 安全 → 密钥管理** 中管理 SSH 私钥： +## SSH 主机密钥策略 -- 导入私钥文件 -- 设置密钥名称和密码短语 -- 删除不需要的密钥 - -导入的私钥会加密存储在本地。 - -## 主机密钥策略 - -控制 SSH 连接时如何处理未知主机密钥： +SSH 首次连接未知主机时，Dragonfly 支持三种策略： | 策略 | 行为 | |------|------| -| 提示 | 首次连接时弹窗询问是否信任（默认） | -| 接受 | 自动接受并记录新主机密钥 | -| 严格 | 拒绝所有未知主机密钥 | +| 提示 | 首次连接时询问是否信任（默认） | +| 接受 | 自动接受新的主机密钥 | +| 严格 | 拒绝所有未知主机 | -已知主机密钥存储在 `~/.dragonfly/known_hosts` 文件中。 +已知主机记录保存在 `~/.dragonfly/known_hosts`。 + +如果你处在对主机身份校验要求更高的环境，建议使用“提示”或“严格”，而不是无条件接受。 + +## 安全使用建议 + +- 生产环境优先使用 **私钥 + OTP**，不要长期依赖单一密码 +- 对共享电脑或演示机，开启 **主密码** 与 **屏幕锁定** +- 对需要经常穿过堡垒机的环境，把 **跳板机** 和 **代理** 做成明确的已保存配置 +- 对首次连接的新主机，核对主机密钥来源后再信任 + +:::tip 截图建议 +- 推荐图片路径：`/img/docs/security/security-settings.png` +- 建议展示主密码、屏幕锁定、空闲锁定时间、主机密钥策略 +- 另一个推荐图片路径：`/img/docs/security/security-auth-panel.png` +- 建议展示 Security/Auth 面板中的密钥、密码、OTP 三个标签 +::: diff --git a/docs-site/docs/guide/session-types.md b/docs-site/docs/guide/session-types.md new file mode 100644 index 00000000..c437cad5 --- /dev/null +++ b/docs-site/docs/guide/session-types.md @@ -0,0 +1,123 @@ +--- +sidebar_position: 0 +--- + +# 会话类型 + +Dragonfly 不只是 SSH 客户端，而是一个把多类终端工作流放到同一工作区中的桌面应用。当前支持四类会话： + +- **SSH** +- **本地终端** +- **Telnet** +- **串口** + +理解它们之间的差异，有助于你判断某个功能为什么“只在某些标签页里出现”。 + +## 一览对比 + +| 会话类型 | 典型场景 | 支持的增强能力 | +|----------|----------|----------------| +| SSH | Linux / Unix 服务器远程运维 | SFTP、OTP、资源监控、代理、跳板机、隧道 | +| 本地终端 | 本地 shell、脚本调试、构建命令 | 共享同一套终端 UI、命令历史、分屏 | +| Telnet | 旧设备、实验环境、兼容性排障 | 终端工作区能力，但不包含 SSH 专属特性 | +| 串口 | 路由器、交换机、板卡、嵌入式调试口 | 串口参数配置、终端工作区能力 | + +## SSH + +SSH 是当前能力最完整的会话类型，适合： + +- 登录远程 Linux / Unix 主机 +- 浏览和传输远程文件 +- 使用 OTP、跳板机、代理 +- 查看远程资源监控 +- 配置端口隧道 + +如果你需要： + +- 文件浏览器 +- 自动上传 / 回传 +- 远程资源监控 +- 网络面板中的 SSH 隧道 + +那么应该优先使用 SSH。 + +## 本地终端 + +本地终端适合把本机 shell 工作流也放进 Dragonfly 工作区中，例如： + +- 本地构建前端 / Rust 项目 +- 跑脚本、日志查看、Git 命令 +- 和远程 SSH 会话并排对照 + +它支持的重点不在远程功能，而在“和 SSH 会话共享同一套工作区体验”： + +- 标签页 +- 分屏 +- 终端搜索 +- 命令历史与建议 +- 行号 / 时间戳 / 高亮等终端增强项 + +创建本地终端时，还可以指定： + +- shell 路径，例如 `powershell.exe`、`cmd.exe`、`bash`、`wsl.exe` +- 工作目录 + +## Telnet + +Telnet 会话适合： + +- 旧设备维护 +- 实验室环境 +- 需要兼容非 SSH 登录链路的场景 + +它保留的是 Dragonfly 的终端工作区能力，但不会附带 SSH 特有的安全和文件能力。因此通常不会有： + +- SFTP 文件浏览器 +- OTP 绑定 +- SSH 跳板机 +- SSH 资源监控 + +如果你的目标只是“快速打开一个传统远程终端”，Telnet 会更直接。 + +## 串口 + +串口会话适合连接： + +- 网络设备控制台口 +- 路由器 / 交换机 +- 开发板、嵌入式设备、调试口 + +创建串口会话时可以配置： + +- 串口号 +- 波特率 +- 数据位 +- 校验位 +- 停止位 + +串口会话同样可以放进 Dragonfly 的标签页与分屏工作区中，适合边看一个串口输出，边在另一个 SSH 或本地终端里执行命令。 + +## 如何选择？ + +可以按下面这个简单规则判断： + +- 要远程服务器完整能力：用 **SSH** +- 要本机 shell：用 **本地终端** +- 要兼容传统远程终端：用 **Telnet** +- 要接调试口 / 设备串口：用 **串口** + +## 在一个工作区里混用 + +Dragonfly 的优势之一，是允许你把这些类型混合放进同一工作区，例如： + +- 左边 SSH 看远端日志 +- 右边本地终端执行打包脚本 +- 再开一个串口标签观察设备启动信息 + +这也是为什么文档里很多功能会写成“某会话类型专属”或“某会话类型才显示”的原因——工作区统一，但能力边界仍然取决于底层会话类型。 + +:::tip 截图建议 +- 推荐图片路径：`/img/docs/session-types/new-session-tabs.png` +- 建议展示新建连接窗口中的 SSH / 本地终端 / Telnet / 串口四个标签 +- 可同时保留各标签的默认字段区域，便于用户理解差异 +::: diff --git a/docs-site/docs/guide/ssh-connection.md b/docs-site/docs/guide/ssh-connection.md index 89ba1c14..989cfa08 100644 --- a/docs-site/docs/guide/ssh-connection.md +++ b/docs-site/docs/guide/ssh-connection.md @@ -4,77 +4,157 @@ sidebar_position: 1 # SSH 连接管理 -## 连接配置 +SSH 仍然是 Dragonfly 最完整的一类会话。除了基础登录外，SSH 连接还可以进一步挂接： + +- SFTP 文件浏览器 +- 远程资源监控 +- 代理 +- 跳板机 +- OTP 绑定与自动填充 +- 端口隧道 + +如果你第一次接触 Dragonfly，通常建议先把 SSH 连接配置好，再去扩展文件、终端增强和网络能力。 + +## 创建 SSH 连接 + +在 **新建连接** 窗口切换到 **SSH** 标签后，可以填写这些信息： ### 基本信息 -创建 SSH 连接时，需要填写以下信息： - -| 字段 | 说明 | 必填 | -|------|------|------| -| 连接名称 | 用于识别的显示名称 | 否 | -| 图标 | 自定义图标 | 否 | -| 分组 | 连接所属分组 | 否 | -| 主机 | 服务器 IP 或域名 | 是 | -| 端口 | SSH 端口号（默认 22） | 否 | -| 用户名 | 登录用户名 | 是 | -| 认证方式 | 密码或私钥 | 是 | -| 描述 | 连接的备注说明 | 否 | +| 字段 | 说明 | +|------|------| +| 连接名称 | 在已保存连接列表中的显示名称 | +| 主机 | 服务器 IP 或域名 | +| 端口 | 默认 `22` | +| 用户名 | 登录用户名 | +| 图标 | 用于区分不同环境或服务 | +| 分组 | 把连接整理到文件夹中 | +| 描述 | 记录用途、环境或备注 | ### 认证方式 -Dragonfly 支持两种认证方式： +Dragonfly 支持两种常见 SSH 认证方式： + +- **密码** +- **私钥** + +你可以直接选择已经保存的密码或私钥，而不必每次重复填写。 #### 密码认证 -直接输入服务器密码。密码会使用 AES-256-GCM 加密存储在本地。 +适合： -#### 密钥认证 +- 临时测试机 +- 还未发放私钥的环境 +- 与 OTP 联合使用的账号 -选择已导入的 SSH 私钥进行认证。支持 RSA、Ed25519 等常见密钥格式。 +#### 私钥认证 -如需管理密钥，前往 **设置 → 安全 → 密钥管理**。 +适合： -## 连接分组 +- 日常远程运维 +- 多台主机复用同一身份 +- 需要配合跳板机或自动化流程的场景 -你可以创建文件夹来组织连接： +私钥和密码都可以在 **Security/Auth** 面板中统一管理。 -- 右键点击侧边栏空白区域选择 **新建文件夹** -- 支持多级嵌套文件夹 -- 拖拽连接到文件夹中进行分组 -- 右键文件夹可重命名或删除 +## 高级配置 -## 连接排序 +SSH 表单的高级区域可以把连接从“能连上”扩展成“适合日常使用”的工作流配置。 -侧边栏支持三种排序方式： +### 代理 -- **自定义顺序** — 手动拖拽调整 -- **名称 A → Z** — 按名称升序 -- **名称 Z → A** — 按名称降序 +如果需要通过代理建立 SSH 连接，可以直接为当前连接选择已保存的代理配置。 -## 导入会话 +当前代理支持： -Dragonfly 支持从其他 SSH 客户端导入会话： +- **SOCKS5** +- **HTTP** -1. 右键点击侧边栏选择 **导入会话** -2. 选择导入来源（目前支持 WindTerm） -3. 选择对应的会话配置文件 -4. 确认导入 +代理记录中可保存： -## 主机密钥验证 +- 名称 +- 协议 +- 主机 +- 端口 +- 用户名 / 密码 -Dragonfly 使用 TOFU（Trust On First Use）策略管理主机密钥： +### 跳板机 -- **提示** — 首次连接时询问是否信任（默认） -- **接受** — 自动接受所有新主机密钥 -- **严格** — 拒绝所有未知主机密钥 +如果目标主机不能直连，可以为当前 SSH 连接指定另一个已保存的 SSH 连接作为 **跳板机**。 -可在 **设置 → 安全 → 连接安全** 中修改策略。 +适合的场景： -## 代理支持 +- 先进入堡垒机，再访问内网服务器 +- 分环境隔离的生产网络 +- 多层 SSH 登录链路 -如需通过代理连接，前往 **设置 → 代理** 配置： +### OTP 绑定 -- 支持 SOCKS5 协议 -- 配置代理主机和端口 -- 启用/禁用代理 +如果目标环境要求二次验证码，可以把一个 OTP 条目绑定到当前 SSH 连接。 + +绑定后有两种常见工作方式： + +- 只是在认证时快速取码 +- 开启 **自动填充 OTP**，在支持的交互流程中直接带入验证码 + +这部分可以结合 [OTP 与认证](./otp-and-auth) 一起使用。 + +## 已保存连接的管理 + +保存后的连接会出现在右侧 **已保存连接** 面板中。常见操作包括： + +- 双击直接连接 +- 按分组组织连接 +- 编辑已有配置 +- 复制连接作为新模板 +- 重新连接已存在的会话来源 + +如果你维护大量主机，建议用分组、图标和描述把“环境 / 项目 / 角色”区分开。 + +## 导入其他客户端的会话 + +Dragonfly 支持导入其他客户端的会话配置，目前可导入： + +- **Xshell**（`.xts`） +- **MobaXterm**（`.mxtsessions`） +- **WindTerm**（`.sessions`） + +导入后建议逐条检查： + +- 主机与端口 +- 用户名 +- 是否需要补充代理 / 跳板机 / OTP 绑定 +- 本地保存的密码或私钥是否已经匹配 + +## 主机密钥策略 + +Dragonfly 会为 SSH 主机维护已知主机记录，并提供三种主机密钥策略： + +| 策略 | 行为 | +|------|------| +| 提示 | 首次连接未知主机时询问是否信任（默认） | +| 接受 | 自动接受并记录新的主机密钥 | +| 严格 | 拒绝所有未知主机 | + +已知主机记录保存在 `~/.dragonfly/known_hosts`。 + +如果你对安全要求较高，建议至少在生产环境中确认主机密钥来源，再决定是否接受。 + +## 什么时候该用 SSH，而不是其他会话类型？ + +优先使用 SSH 的典型场景是： + +- 你需要远程文件浏览器或 SFTP +- 你需要 OTP、跳板机、代理、隧道 +- 你需要远程资源监控 +- 你希望把连接长期保存下来复用 + +如果你只是想在 Dragonfly 里开一个本地 shell，请改用 [会话类型](./session-types) 里的 **本地终端**。 + +:::tip 截图建议 +- 推荐图片路径：`/img/docs/session-types/ssh-advanced-form.png` +- 建议展示 SSH 表单中的主机、认证方式，以及高级区域中的代理 / 跳板机 / OTP 绑定 +- 另一个推荐图片路径：`/img/docs/network/ssh-import-and-groups.png` +- 建议展示已保存连接分组与导入入口 +::: diff --git a/docs-site/docs/guide/terminal.md b/docs-site/docs/guide/terminal.md index 73364b74..b5046676 100644 --- a/docs-site/docs/guide/terminal.md +++ b/docs-site/docs/guide/terminal.md @@ -4,102 +4,142 @@ sidebar_position: 3 # 终端功能 -Dragonfly 基于 xterm.js 提供了功能丰富的终端模拟器。 +Dragonfly 的终端体验围绕“在同一个工作区里高频处理远程与本地会话”设计。它基于 xterm.js，但实际体验并不只是一块终端画布，还包括搜索、命令历史、建议、可选增强项、录制和 SSH 辅助能力。 -## 终端渲染 +## 基础操作 -### 硬件加速 +### 搜索、复制与右键菜单 -默认启用 WebGL 渲染，利用 GPU 加速终端绘制，确保流畅的滚动和输出体验。 - -可在 **设置 → 终端 → 硬件加速** 中开启或关闭。 - -### 字体配置 - -- **字体系列** — 支持多字体回退链，首选字体优先级最高 -- **字体大小** — 终端和界面字体大小分别可调 -- **字体连字** — 可启用编程字体连字特性 - -内置 JetBrains Mono 和 Noto Sans SC 字体，也可使用系统安装的任意字体。 - -### 光标样式 - -支持三种光标样式： -- 块（Block） -- 下划线（Underline） -- 竖线（Bar） - -可选择是否启用光标闪烁。 - -## 终端操作 - -### 右键菜单 - -在终端中右键可以： +终端右键菜单可直接执行这些高频操作： - 复制 / 粘贴 -- 粘贴选定的文本 +- 粘贴选中的文本 - 查找文本 - 在线搜索选中文本 - 翻译选中文本 - 清屏 / 全部清除 - 全选 -### 回滚缓冲区 +在 **设置 → 交互** 中，你还可以调整： -终端保留可配置行数的历史输出（默认 1000 行），可通过滚轮向上滚动查看历史内容。 +- **选中即复制** +- **右键粘贴** +- 单词分隔符 +- 默认字符编码 -在 **设置 → 终端 → 回滚缓冲区** 中调整行数。 +### 回滚缓冲区与字体 -### 剪贴板 +- 回滚缓冲区默认保留 **10000 行**输出 +- 可自定义字体族、字号、连字、光标样式与闪烁 +- **硬件加速**为可选项，默认并未开启；如果你希望对比渲染效果，可在 **设置 → 终端** 中手动切换 -- **选中即复制** — 选中文本自动复制到剪贴板 -- **右键粘贴** — 右键点击终端区域粘贴剪贴板内容 +## 命令历史与建议 -在 **设置 → 交互** 中配置。 +Dragonfly 会为会话工作流提供两类辅助： -## 关键词高亮 +### 命令历史 -Dragonfly 支持终端文本的关键词高亮： +- 自动记录终端输入过的命令 +- 支持模糊检索 +- 可从右侧的 **命令历史** 面板回看历史输入 -### 内置规则 +### 输入建议 -自动识别并高亮常见模式，包括： -- 日期时间格式 -- 数字 -- 错误/警告关键词 +输入时会基于历史命令给出建议，适合重复执行运维命令、构建命令或排障脚本。 -内置规则会根据当前主题自动调整配色。 +## 可选终端增强项 -### 自定义规则 +下面这些能力都需要你按需开启，而不是默认全部打开。 -在 **设置 → 终端 → 关键词高亮** 中添加自定义规则： +### 行号与时间戳 gutter -1. 设置规则名称 -2. 选择高亮颜色 -3. 添加匹配模式（支持正则表达式），每行一个 +在 **设置 → 终端** 中可分别开启： -自定义规则的优先级高于内置规则。 +- **显示行号** +- **显示时间戳** -## 命令历史 +开启后，终端左侧会出现 gutter，用于辅助阅读长日志、命令输出或回放录制内容。 -终端会自动记录输入的命令： +### 动作链接 -- 按会话分组存储 -- 支持模糊搜索 -- 在左侧边栏的 **命令历史** 面板中查看 +动作链接默认关闭，开启后可识别并点击常见文本模式，包括： -## 联想补全 +- IPv4 地址，例如 `192.168.1.10` +- `host:port`，例如 `db.internal:5432` +- 压缩包文件名，例如 `backup.tar.gz` -终端输入时会自动显示命令联想补全建议，基于历史命令进行匹配。 +注意： -## Keep-Alive +- 需要先在 **设置 → 终端** 中开启 **动作链接** +- 打开链接时需要使用 **Ctrl / Cmd + 点击**，避免和普通选中操作冲突 +- 具体匹配器可以单独启用或关闭 -可配置 SSH Keep-Alive 间隔，防止连接因空闲而断开： +### 关键词高亮 -- 在 **设置 → 终端 → Keep-Alive 间隔** 中设置 -- 设为 0 则禁用 +关键词高亮同样默认关闭。启用后，Dragonfly 会先应用内置规则，再叠加你的自定义规则。 -## 远程资源监控 +内置规则覆盖的内容不只限于错误关键字，还包括： -在 **设置 → 终端** 中启用 **显示远程资源信息** 后，状态栏会显示当前 SSH 主机的 CPU 和内存使用情况，每 10 秒更新一次。 +- error / warn / success / info / debug 等常见状态词 +- 日期时间 +- 数字、大小、持续时间 +- 地址、URL、UUID、版本号等结构化文本 + +你也可以自定义规则： + +- 自定义规则名称 +- 分别设置深色 / 浅色主题颜色 +- 每行填写一个匹配模式 +- 可选择是否跨折行继续匹配 + +## SSH 相关辅助能力 + +### Keep-Alive + +对 SSH 会话，可以在 **设置 → 终端** 中配置 Keep-Alive 间隔： + +- 默认值为 **60 秒** +- 设为 `0` 表示关闭 +- 适合降低长时间空闲连接被远端回收的概率 + +### 远程资源监控 + +远程资源监控不是全局默认显示项。要使用它，需要同时满足： + +1. 当前是一个 **SSH 会话** +2. 在 **设置 → 终端** 中开启 **显示远程资源信息** + +启用后，右侧 **资源监控** 面板会按设定间隔轮询主机信息；默认轮询间隔为 **3 秒**，可手动调整。 + +面板会显示的内容包括： + +- 主机名、系统、架构、运行时长 +- Load Average +- CPU 使用率 +- 内存使用情况 +- 网络吞吐速率 + +## 录制与工作流配合 + +Dragonfly 支持会话录制，适合： + +- 保留排障步骤 +- 给同事复现问题 +- 截取有时间顺序的终端示例 + +如果你准备录制文档素材，通常可以把这些能力组合起来： + +- 行号 / 时间戳 gutter +- 关键词高亮 +- 动作链接 +- 命令历史 +- 资源监控 + +这样更容易拍出“终端在真实工作流中使用”的截图，而不是单独展示某个开关。 + +:::tip 截图建议 +- 推荐图片路径：`/img/docs/terminal/gutter-line-numbers-timestamps.png` +- 建议先在 **设置 → 终端** 中开启行号与时间戳，再执行：`scripts/demo-terminal-gutter.sh` +- 另一个推荐图片路径：`/img/docs/terminal/action-links-and-highlights.png` +- 建议先开启动作链接与关键词高亮，再执行：`scripts/demo-terminal-output.sh` 与 `scripts/demo-action-links.sh` +::: diff --git a/docs-site/docs/guide/tunnels-and-proxy.md b/docs-site/docs/guide/tunnels-and-proxy.md new file mode 100644 index 00000000..a8ce1148 --- /dev/null +++ b/docs-site/docs/guide/tunnels-and-proxy.md @@ -0,0 +1,134 @@ +--- +sidebar_position: 5 +--- + +# 代理、跳板机与隧道 + +Dragonfly 把网络相关能力分成三层： + +1. **代理**：先解决“怎么连出去” +2. **跳板机**：再解决“通过哪台 SSH 主机中转” +3. **隧道**：最后解决“把端口流量映射到哪里” + +这三者经常会出现在同一个真实场景里，但职责不同，分开理解更清楚。 + +## 代理 + +代理用于帮助 Dragonfly 建立到远端的网络连接。 + +当前支持： + +- **SOCKS5** +- **HTTP** + +每个代理配置可保存： + +- 名称 +- 协议 +- 主机 +- 端口 +- 用户名 / 密码 + +代理在网络面板中统一管理，之后可以在 SSH 连接的高级区域中直接选择。 + +适合场景： + +- 办公网必须走代理 +- 某些区域网络不允许直连 +- 需要统一维护一组出站网络配置 + +## 跳板机 + +跳板机是 SSH 专属能力。它的作用不是代替代理，而是使用一个已保存的 SSH 连接作为中转入口。 + +适合场景： + +- 堡垒机 / bastion host +- 目标主机只允许内网访问 +- 多层 SSH 网络隔离 + +在 SSH 连接高级区域中，你可以直接从已有 SSH 连接里选一个作为跳板机。 + +## 隧道 + +Dragonfly 在网络面板中提供专门的隧道管理页，可把端口映射保存为可复用配置。 + +### 支持的隧道类型 + +- **本地隧道（local）** +- **远程隧道（remote）** +- **动态隧道（dynamic / SOCKS5）** + +### 本地隧道 + +把本机监听端口转发到远端目标地址，适合： + +- 访问内网数据库 +- 打开只能在远端访问的 Web 控制台 +- 通过 SSH 安全转发服务端口 + +### 远程隧道 + +把远端监听端口映射回本地服务，适合： + +- 临时把本地服务暴露给远端环境 +- 做反向调试或联调 + +### 动态隧道 + +创建一个本地 SOCKS5 代理端口，适合： + +- 浏览器或工具临时走 SSH 动态代理 +- 需要快速建立一条“经 SSH 出站”的代理链路 + +## 隧道配置项 + +创建隧道时，通常会配置： + +- 隧道名称 +- 隧道类型 +- 关联的 SSH 连接 +- 监听端口 +- 目标主机 / 目标端口（动态隧道除外） +- 是否仅绑定 `127.0.0.1` +- 是否自动打开 + +如果你只想本机自己访问，建议保持绑定到 `127.0.0.1`；这通常比监听 `0.0.0.0` 更安全。 + +## 网络面板中的日常操作 + +在网络面板中，你可以： + +- 新建 / 编辑 / 删除代理 +- 新建 / 编辑 / 删除隧道 +- 直接打开或关闭某条隧道 +- 查看某条隧道当前是否处于打开状态 + +这让网络配置不再是“一次性命令”，而是可以被保存、复用和可视化管理。 + +## 典型组合示例 + +### 示例 1：代理 + SSH + +- 先在网络面板中保存一个 SOCKS5 代理 +- 再在 SSH 连接高级区域里选择这个代理 +- 适合公司网络或跨区访问环境 + +### 示例 2：跳板机 + 目标主机 + +- 先保存堡垒机连接 +- 再在业务主机连接里把堡垒机设为跳板机 +- 适合内网分层登录场景 + +### 示例 3：SSH + 本地隧道 + +- 建立 SSH 连接 +- 保存一个本地隧道 `localhost:15432 -> db.internal:5432` +- 之后本地工具即可通过 `127.0.0.1:15432` 访问数据库 + +:::tip 截图建议 +- 推荐图片路径：`/img/docs/network/network-panel.png` +- 建议展示网络面板中的代理与隧道两个标签 +- 另一个推荐图片路径：`/img/docs/network/tunnel-dialog.png` +- 建议展示隧道类型、本地监听端口、目标主机与自动打开选项 +::: diff --git a/docs-site/docs/intro.md b/docs-site/docs/intro.md index fb359c79..4af3e515 100644 --- a/docs-site/docs/intro.md +++ b/docs-site/docs/intro.md @@ -5,33 +5,72 @@ slug: / # 项目介绍 -**Dragonfly** 是一个现代、高性能的 SSH 客户端，基于 [Tauri](https://tauri.app/) 和 [React](https://react.dev/) 构建。它将精致的用户界面与强大的 Rust 后端相结合，为开发者和运维人员提供卓越的远程服务器管理体验。 +**Dragonfly** 是一个围绕远程终端工作流设计的桌面客户端。它以 Tauri + React 构建前端界面，以 Rust 负责 SSH、SFTP、会话管理、隧道、认证与配置持久化，让你在同一个工作区中处理远程服务器、本地 shell、串口设备和网络辅助能力。 -## 核心特性 +## 适合哪些场景 -- **安全高效的 SSH 连接** — 基于 Rust `russh` 库，提供原生级性能 -- **多标签界面** — 同时管理多个 SSH 和本地终端会话 -- **会话管理** — 保存、组织和快速连接常用服务器 -- **集成文件浏览器** — 通过 SFTP 直接在侧边栏浏览和管理远程文件 -- **命令历史** — 自动记录并支持模糊搜索的命令历史 -- **快捷命令** — 一键执行常用命令，支持变量替换 -- **可定制界面** — 可调整面板大小，支持深色/浅色主题 -- **跨平台** — 支持 Windows、macOS 和 Linux +- 同时维护多台 SSH 主机 +- 在本地终端、Telnet、串口设备之间切换排障 +- 边看终端输出边操作远程文件 +- 为常用运维命令、登录流程和跳板机链路做标准化配置 +- 需要 OTP、录制、资源监控、自动上传等增强能力 -## 技术栈 +## 核心能力 -| 层级 | 技术 | -|------|------| -| 前端 | React 19, TypeScript, Vite, TailwindCSS 4 | -| 后端 | Tauri 2, Rust | -| 终端 | xterm.js (WebGL 加速) | -| SSH | russh (纯 Rust SSH 实现) | -| 文件传输 | russh-sftp (管道化传输) | +### 多种会话类型 -## 为什么选择 Dragonfly？ +Dragonfly 不只支持 SSH，还支持： -1. **原生性能** — Rust 后端确保 SSH 连接和文件传输的高性能 -2. **安全至上** — AES-256-GCM 加密存储凭据，支持系统密钥链 -3. **现代 UI** — 基于 React 和 TailwindCSS 的精致界面 -4. **轻量级** — 基于 Tauri，安装包体积远小于 Electron 应用 -5. **开源免费** — MIT 许可证，完全开源 +- **SSH** — 远程登录、文件传输、资源监控、隧道、OTP 等完整能力 +- **本地终端** — 在同一套 UI 中打开本地 shell +- **Telnet** — 兼容旧设备或实验环境 +- **串口** — 适合网络设备、嵌入式板卡、调试口场景 + +### 可组合的工作区 + +- 多标签页管理多个会话 +- 标签页内支持**横向/纵向分屏** +- 左右活动栏可放置文件浏览器、网络、Security/Auth、会话列表、命令历史、资源监控等面板 +- 设置、新建连接、快捷命令、自动上传提示均使用独立子窗口，减少主工作区干扰 + +### 面向终端操作的增强 + +- 命令历史与模糊建议 +- 终端搜索、复制/粘贴、上下文菜单 +- 可选的**行号 / 时间戳 gutter** +- 可选的**动作链接**（如 IPv4、`host:port`、压缩包文件名） +- 可选的**关键词高亮**与自定义规则 +- 会话录制与 SSH Keep-Alive + +### 远程文件与自动回传 + +- SSH 会话下内置 SFTP 文件浏览器 +- 上传、下载、重命名、移动、删除、属性查看 +- 传输队列、失败重试、断点续传、时间戳保留 +- 在本地编辑下载的远程文件后，可通过 watcher 流程快速上传回远端 + +### 安全与网络能力 + +- 私钥、密码、主机密钥策略、本地加密存储 +- OTP 管理（TOTP / HOTP）、二维码导入、SSH 自动填充 +- 代理配置、跳板机、端口隧道 +- 锁屏与主密码能力 + +## 文档导航建议 + +如果你是第一次使用，建议按下面顺序阅读： + +1. [快速开始](./getting-started/quick-start) +2. [会话类型](./guide/session-types) +3. [SSH 连接管理](./guide/ssh-connection) +4. [工作区与布局](./guide/layout-and-workspace) +5. [终端功能](./guide/terminal) +6. [SFTP 文件传输](./guide/file-transfer) +7. [代理、跳板机与隧道](./guide/tunnels-and-proxy) +8. [OTP 与认证](./guide/otp-and-auth) + +:::tip 截图建议 +- 推荐图片路径：`/img/docs/readme/main-workspace.png` +- 建议展示内容：左侧活动栏、右侧面板、中心多标签终端、底部快捷区 +- 适合先执行的脚本：`scripts/demo-terminal-output.sh` +:::