mirror of
https://github.com/nyakang/nyaterm.git
synced 2026-10-30 16:08:28 +00:00
235 lines
7.7 KiB
Markdown
235 lines
7.7 KiB
Markdown
---
|
||
sidebar_position: 4
|
||
---
|
||
|
||
# 后端开发指南
|
||
|
||
后端代码位于 `src-tauri/src/`，使用 Rust 编写，是 NyaTerm 的运行时核心：会话管理、SSH/SFTP、录制、翻译、AI、隧道、认证、同步备份、导入导出与配置持久化都在这里落地。
|
||
|
||
## 命令入口与模块组织
|
||
|
||
后端命令注册集中在 `src-tauri/src/lib.rs`：
|
||
|
||
- 在这里创建共享 manager 状态
|
||
- 在这里挂载 Tauri plugin
|
||
- 在这里通过 `tauri::generate_handler![]` 注册所有 commands
|
||
|
||
当前命令模块位于：
|
||
|
||
```text
|
||
src-tauri/src/cmd/
|
||
├── app.rs
|
||
├── backup.rs
|
||
├── clipboard.rs
|
||
├── cloud_sync.rs
|
||
├── connection.rs
|
||
├── importer.rs
|
||
├── log.rs
|
||
├── otp.rs
|
||
├── proxy.rs
|
||
├── session.rs
|
||
├── settings.rs
|
||
├── sftp.rs
|
||
├── stats.rs
|
||
├── translate.rs
|
||
├── tunnel.rs
|
||
├── watcher.rs
|
||
└── ai.rs
|
||
```
|
||
|
||
如果你要新增一个 command，通常需要：
|
||
|
||
1. 在对应 `cmd/*.rs` 中定义 `#[tauri::command]`
|
||
2. 复用 `core/` 或 `config/` 层已有逻辑
|
||
3. 回到 `src-tauri/src/lib.rs` 注册它
|
||
4. 在前端通过 `src/lib/invoke.ts` 调用
|
||
|
||
## 共享运行时状态
|
||
|
||
`src-tauri/src/lib.rs` 会把这些共享对象注入 Tauri state：
|
||
|
||
- `SessionManager`
|
||
- `TunnelManager`
|
||
- `RecordingManager`
|
||
- `PendingAuthManager`
|
||
- `QuickCommandsStore`
|
||
- `CloudSyncManager`
|
||
|
||
它们分别负责：
|
||
|
||
- 活动会话生命周期与命令历史
|
||
- 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` — 外部客户端会话导入
|
||
- `ai.rs` — AI provider 调用、流式输出和命令卡片生成
|
||
|
||
## SSH 模块
|
||
|
||
`src-tauri/src/core/ssh/` 是最核心的一组模块：
|
||
|
||
- `client.rs` — russh client、known_hosts 校验、代理感知连接
|
||
- `auth.rs` — 保存认证信息加载、keyboard-interactive / OTP 流程
|
||
- `io.rs` — 终端 I/O 与 cwd 更新事件
|
||
- `sftp.rs` — 远程文件操作与传输队列
|
||
- `tunnel.rs` — 本地 / 远程 / 动态隧道
|
||
- `session.rs` — SSH session 生命周期协作
|
||
|
||
典型 SSH 流程是：
|
||
|
||
1. 读取连接配置
|
||
2. 解密密码 / 私钥 / 凭据
|
||
3. 建立 TCP / 代理连接
|
||
4. 做 host key policy 校验
|
||
5. 完成认证（可能进入 OTP / interactive 流程）
|
||
6. 打开 PTY 通道并进入异步 I/O 循环
|
||
7. 在支持时注入 OSC/CWD 跟踪能力
|
||
|
||
## SFTP 与传输队列
|
||
|
||
`src-tauri/src/core/ssh/sftp.rs` 负责：
|
||
|
||
- 列目录
|
||
- 下载 / 上传单文件与目录
|
||
- 删除 / 重命名 / 新建文件夹 / 符号链接 / 属性读取
|
||
- 传输队列控制（pause / resume / cancel）
|
||
- 向前端发出 `transfer-event`
|
||
|
||
前端传输面板与 `TransferContext` 就是基于这些事件构建的。
|
||
|
||
## watcher 与自动上传
|
||
|
||
`src-tauri/src/core/watcher.rs` 负责本地文件监听。
|
||
|
||
典型流程：
|
||
|
||
1. 前端从远程文件浏览器中“打开”远程文件
|
||
2. 后端下载到本地临时目录并开始 watch
|
||
3. 本地文件保存后，发出 `file-modified` 事件
|
||
4. 前端决定弹出自动上传窗口，或按“始终上传”策略直接回传
|
||
|
||
这条链路涉及：
|
||
|
||
- `cmd/watcher.rs`
|
||
- `core/watcher.rs`
|
||
- 前端 `FileUploadPage.tsx`
|
||
|
||
## AI runtime
|
||
|
||
`src-tauri/src/core/ai.rs` 负责 AI 功能的后端核心逻辑，包括：
|
||
|
||
- provider 请求与模型能力适配
|
||
- 流式文本输出与推理内容捕获
|
||
- 结构化 JSON 输出解析
|
||
- 命令卡片生成、风险等级和执行审计
|
||
- AI 历史与审计记录持久化
|
||
|
||
如果你修改 AI provider 行为或响应解析，重点留意：
|
||
|
||
- 推理内容与主文本可能来自不同通道
|
||
- 某些模型会把主要答案放在 reasoning 中
|
||
- 前端依赖结构化命令卡片和风险字段做执行审批
|
||
|
||
## Cloud sync / portable snapshot
|
||
|
||
`src-tauri/src/core/cloud_sync.rs` 负责这条能力线的运行时行为，包括：
|
||
|
||
- 启动时同步检查
|
||
- 手动推送 / 拉取
|
||
- 自动推送防抖
|
||
- 定时备份
|
||
- 远程备份列表与恢复
|
||
- 冲突检测与事件广播
|
||
|
||
它通过 `src-tauri/src/cmd/cloud_sync.rs` 暴露给前端的 commands 包括：
|
||
|
||
- `test_cloud_sync_connection`
|
||
- `get_cloud_sync_status`
|
||
- `sync_push_now`
|
||
- `sync_pull_now`
|
||
- `run_cloud_backup_now`
|
||
- `list_cloud_sync_history`
|
||
- `list_remote_backups`
|
||
- `restore_remote_backup`
|
||
- `resolve_cloud_sync_conflict`
|
||
|
||
`src-tauri/src/core/portable_snapshot.rs` 则定义了“哪些数据应该进入可移植快照”。这层很重要，因为它决定了：
|
||
|
||
- 哪些设置适合跨设备同步
|
||
- 哪些数据只应该保留在本机
|
||
- 备份快照和同步快照的范围差异
|
||
|
||
当前实现里，portable snapshot 会覆盖连接、凭据配置、OTP、代理、隧道、快捷命令、大部分应用设置，以及必要的文本密钥材料；但设备本地的运行态 UI 状态不会被无差别漫游。
|
||
|
||
## 导入、导出与诊断
|
||
|
||
除了运行时会话能力，后端还负责几类数据管理命令：
|
||
|
||
- `cmd::importer` — 导入 Xshell / MobaXterm / WindTerm 会话
|
||
- `cmd::backup` — 导出 / 导入 NyaTerm 的加密 `.nya` 配置备份
|
||
- `cmd::log` — 收集前端日志并导出诊断包
|
||
- `cmd::app` — 应用级退出等控制命令
|
||
|
||
如果你修改的是迁移、备份恢复或故障排查工具链，这几组模块通常比 session / ssh 更关键。
|
||
|
||
## 配置与加密
|
||
|
||
配置和记录保存在 `~/.nyaterm/nyaterm.redb`，主要由 `src-tauri/src/storage.rs` 和 `src-tauri/src/config/` 管理。从 Dragonfly 升级时会复制 `~/.dragonfly/dragonfly.redb`；如果旧环境只有 `.dragonfly` JSON / 文本文件，也会复制后迁入 redb。旧目录不会被删除。
|
||
|
||
主要 redb 文档包括：
|
||
|
||
- JSON 文档：`settings`、`sessions`、`keys`、`passwords`、`otp`、`quick-command`、`tunnels`、`proxies`、`history`、`cloud-sync`、`cloud-sync-state`、`ai-history`、`ai-audit`
|
||
- 文本文档：`known_hosts`、`master.key`
|
||
|
||
敏感字段会在写盘前加密，因此新增配置时要确认是否属于敏感数据边界。
|
||
|
||
对于 cloud sync，还要额外关注：
|
||
|
||
- provider 配置中的凭据字段会经过加密 / mask / merge 处理
|
||
- 运行时状态单独落在 `cloud-sync-state` 文档
|
||
- 历史记录主要来自结构化日志，再被 `list_cloud_sync_history` 聚合读取
|
||
|
||
## 事件模型
|
||
|
||
后端大量依赖 Tauri 事件通知前端，典型事件包括：
|
||
|
||
| 事件 | 说明 |
|
||
|------|------|
|
||
| `terminal-output-{id}` | 终端输出 |
|
||
| `cwd-changed-{id}` | 工作目录变化 |
|
||
| `session-closed-{id}` | 会话关闭 |
|
||
| `sessions-changed` | 会话列表变化 |
|
||
| `connections-changed` | 已保存连接变化 |
|
||
| `transfer-event` | 传输进度 |
|
||
| `otp-request` | 触发 OTP / keyboard-interactive 认证 |
|
||
| `cloud-sync-status-changed` | 云同步 / 备份状态变化 |
|
||
| `cloud-sync-history-changed` | 同步 / 备份历史变化 |
|
||
| `cloud-sync-conflict` | 云同步冲突预览 |
|
||
| AI 流式事件 | AI 响应、推理内容与执行状态 |
|
||
|
||
设计新后端能力时，优先考虑是否应该通过已有事件流对前端暴露，而不是额外引入新的轮询接口。
|