后端开发指南

后端代码位于 src-tauri/src/，使用 Rust 编写，是 NyaTerm 的运行时核心：会话管理、SSH/SFTP、录制、翻译、AI、隧道、认证、同步备份、导入导出与配置持久化都在这里落地。

命令入口与模块组织

后端命令注册集中在 src-tauri/src/lib.rs：

在这里创建共享 manager 状态
在这里挂载 Tauri plugin
在这里通过 tauri::generate_handler![] 注册所有 commands

当前命令模块位于：

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，通常需要：

在对应 cmd/*.rs 中定义 #[tauri::command]
复用 core/ 或 config/ 层已有逻辑
回到 src-tauri/src/lib.rs 注册它
在前端通过 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 流程是：

读取连接配置
解密密码 / 私钥 / 凭据
建立 TCP / 代理连接
做 host key policy 校验
完成认证（可能进入 OTP / interactive 流程）
打开 PTY 通道并进入异步 I/O 循环
在支持时注入 OSC/CWD 跟踪能力

SFTP 与传输队列

src-tauri/src/core/ssh/sftp.rs 负责：

列目录
下载 / 上传单文件与目录
删除 / 重命名 / 新建文件夹 / 符号链接 / 属性读取
传输队列控制（pause / resume / cancel）
向前端发出 transfer-event

前端传输面板与 TransferContext 就是基于这些事件构建的。

watcher 与自动上传

src-tauri/src/core/watcher.rs 负责本地文件监听。

典型流程：

前端从远程文件浏览器中“打开”远程文件
后端下载到本地临时目录并开始 watch
本地文件保存后，发出 file-modified 事件
前端决定弹出自动上传窗口，或按“始终上传”策略直接回传

这条链路涉及：

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 的加密 .dgfy 配置备份
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 响应、推理内容与执行状态

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

命令入口与模块组织​

共享运行时状态​

SessionManager​

会话实现​

SSH 模块​

SFTP 与传输队列​

watcher 与自动上传​

AI runtime​

Cloud sync / portable snapshot​

导入、导出与诊断​

配置与加密​

事件模型​