---
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 响应、推理内容与执行状态 |

设计新后端能力时，优先考虑是否应该通过已有事件流对前端暴露，而不是额外引入新的轮询接口。