远程 SSH 接入

Mantra v0.10.0 引入了远程 SSH 项目接入功能，让你可以连接到远程服务器，像管理本地项目一样导入、浏览和实时监听远程服务器上的 AI 编程会话——无需在远程服务器上安装任何额外软件。

什么是远程 SSH 接入？

当你在远程服务器（如云主机、开发机、团队共享服务器）上运行 AI 工具时，以前只能登录到服务器才能查看会话记录。现在，Mantra 可以通过 SSH 连接直接从你的本地机器上访问这些会话：

远程导入 AI 会话，无需下载日志文件到本地
浏览远程项目的文件树和源码
实时监听远程正在进行的 AI 编程会话

核心功能

零配置 SSH 连接

Mantra 自动读取你现有的 ~/.ssh/config 文件来发现可用的远程主机：

无需额外配置：如果你已经能用 SSH 命令连接到某台服务器，Mantra 也能连接
认证方式：支持密钥文件、SSH Agent 转发、密码认证，自动尝试可用的认证方式
已保存连接：成功连接过的服务器会被保存，下次一键重连，按最近使用时间排序

远程源自动检测

连接到远程服务器后，Mantra 会自动扫描可用的 AI 工具会话：

AI 工具	检测路径
Claude Code	`~/.claude/projects/`
Codex	`~/.codex/`
Cursor	`~/.config/Cursor/` (Linux)
Gemini CLI	`~/.gemini/`

检测结果会显示每个工具的预估会话数量，让你快速了解远程服务器上有什么可以导入。

远程会话导入

通过两种方式从远程服务器读取会话，无文件落地：

SFTP 流式传输：对于 Claude Code、Codex、Gemini CLI 的 JSONL/JSON 格式，通过 SFTP 流式读取，不完整下载文件到本地
远程命令执行：对于 Cursor 的 SQLite 数据库，通过 SSH 在远程执行查询命令获取数据

导入页面重设计

v0.10.0 对导入页面进行了重新设计，采用位置分组的平铺布局：

本地来源：显示在最上方（Claude Code、Cursor、Gemini CLI、Codex 本地路径）
远程服务器：每台服务器作为独立分组，显示其检测到的会话
添加新服务器：从 SSH 主机列表选择，或手动输入地址

远程文件浏览

在会话详情中，可以直接浏览远程项目的文件结构和源码：

通过 SFTP 列举远程目录结构
点击文件直接查看内容，常用文件有内存缓存加速
与本地项目完全相同的文件树操作体验

SSH 连接池与心跳保活

多个操作（文件浏览、实时监听、导入扫描）共享同一条 SSH 连接：

自动通道复用：同一连接上同时建立多个操作通道，节省连接资源
心跳保活：定期发送心跳消息，防止因空闲超时被服务器断开
优雅恢复：断开的连接在下次使用时自动重新建立，60 秒宽限期内无需用户干预

如何使用

第一步：添加远程服务器

打开 Mantra 导入页面
在「远程服务器」区域点击「添加服务器」
从你的 SSH 主机列表中选择（来自 ~/.ssh/config），或手动输入主机地址
选择认证方式：密钥文件、SSH Agent 或密码
点击「连接」，Mantra 自动检测远程可用的 AI 会话

SSH Config 推荐

如果你在 ~/.ssh/config 中配置了主机别名，Mantra 会直接识别，无需重复输入 IP 地址和端口。

Host my-dev-server
    HostName 192.168.1.100
    User ubuntu
    IdentityFile ~/.ssh/id_ed25519

第二步：导入远程会话

在导入页面找到目标远程服务器分组
选择要导入的 AI 工具和项目
点击「导入」，Mantra 通过 SFTP/SSH 读取会话数据
导入完成后，项目出现在 Mantra 的项目列表中

无文件下载

远程会话数据直接解析到 Mantra 的本地数据库，原始日志文件不会下载到你的本地机器。

第三步：浏览和监听

导入完成后，远程项目与本地项目操作完全一致：

时光旅行：回溯远程会话的历史
文件浏览：在右侧面板实时查看远程项目的源码
实时监听：如果远程会话仍在进行，自动开启实时更新（详见会话实时更新）

远程项目同步

对于已导入的远程项目，点击「同步」按钮可以：

扫描远程服务器上的新会话和消息更新
无需重新完整导入
SSH 断线时自动重连后继续同步

认证方式说明

密钥文件认证（推荐）

bash

# 确保私钥文件权限正确
chmod 600 ~/.ssh/id_ed25519

# 测试连接
ssh user@hostname

Mantra 会自动查找 ~/.ssh/ 下的常见密钥文件（id_rsa、id_ed25519、id_ecdsa）。

SSH Agent 认证

如果你使用 SSH Agent 管理密钥（推荐用于需要 passphrase 的密钥）：

bash

# 启动 SSH Agent 并添加密钥
eval $(ssh-agent)
ssh-add ~/.ssh/id_ed25519

Mantra 会自动检测并使用已加载的 SSH Agent。

密码认证

不推荐，但在必要时可以使用。输入密码时，Mantra 会提示你在安全输入框中输入，不会明文存储。

安全说明

重要提示

Mantra 不会存储你的 SSH 密码
私钥文件路径被记录，但私钥内容不被读取（通过系统 SSH 库加载）
通过 SFTP 读取远程文件时，仅读取必要的数据，不扫描无关目录
所有读取操作均为只读，不向远程服务器写入任何内容

常见问题

连接失败怎么办？

常见原因和解决方法：

SSH 服务未启动：确认远程服务器的 SSH 服务正在运行（systemctl status ssh）
端口不对：默认使用 22 端口，如使用其他端口，在 ~/.ssh/config 中配置 Port
认证失败：确认使用了正确的私钥或密码；如使用 SSH Agent，确认 Agent 已加载密钥
防火墙：确认远程服务器的防火墙允许来自本机的 SSH 连接
已知主机验证：首次连接时，Mantra 会提示你确认服务器的指纹信息

调试建议：先用终端手动 ssh user@hostname 确认连接正常，再在 Mantra 中添加。

支持 SSH 跳板机（Jump Host）吗？

通过 ~/.ssh/config 的 ProxyJump 配置可以支持：

Host target-server
    HostName 10.0.0.1
    User ubuntu
    ProxyJump jump-host

Host jump-host
    HostName public-ip
    User admin
    IdentityFile ~/.ssh/id_ed25519

配置后，在 Mantra 中直接选择 target-server 即可，跳板机路由自动处理。

远程会话的实时监听如何工作？

远程实时监听通过以下机制实现，不同 AI 工具有所不同：

Claude Code / Codex：通过 SSH 流式读取远程 JSONL 文件的尾部，等效于 tail -f，从上次读取位置继续
Cursor：通过 SSH 定期在远程执行 SQLite 查询
Gemini CLI：通过 SSH 定期检测远程 JSON 文件是否变化

断开 SSH 连接后重连，Mantra 会从上次记录的偏移量继续读取，不会遗漏期间产生的消息。

可以同时连接多台服务器吗？

可以。Mantra 支持同时导入来自多台远程服务器的项目。每台服务器维护独立的连接池，互不影响。你可以在项目列表中同时看到来自不同服务器的项目，操作体验完全相同。

下一步

会话实时更新 - 了解实时监听的详细工作原理
导入向导 - 了解完整的导入流程
项目管理 - 管理本地和远程项目

远程 SSH 接入 ​

什么是远程 SSH 接入？ ​

核心功能 ​

零配置 SSH 连接 ​

远程源自动检测 ​

远程会话导入 ​

导入页面重设计 ​

远程文件浏览 ​

SSH 连接池与心跳保活 ​

如何使用 ​

第一步：添加远程服务器 ​

第二步：导入远程会话 ​

第三步：浏览和监听 ​

远程项目同步 ​

认证方式说明 ​

密钥文件认证（推荐） ​

SSH Agent 认证 ​

密码认证 ​

安全说明 ​

常见问题 ​

下一步 ​