OpsXShell 文档 v2.1.1
文档 / 开始使用 / 快速上手

快速上手

使用指南

OpsXShell 主打简单好用：常用远程操作走短路径，高级选项默认收起。不做堡垒审计。

安装（macOS）

从官网下载，或打开本机构建产物 src-tauri/target/<triple>/release/bundle/dmg/ 里的 .dmg，把 OpsXShell 拖到「应用程序」。Finder 里应是 Tauri 那套大图标布局（应用在左、Applications 在右）。已经 staple 的正式包一般可直接打开。

自己改代码后重新打包：先 ./scripts/build.sh mac-arm64 --quick（本机有签名配置就会签 Developer ID），再 ./scripts/macos-notarize.sh（会要 App 专用密码）。新打的 DMG 在公证完成前仍会被 Gatekeeper 拦截。你现在要做的步骤见 发布指南。

快速连接

按 Cmd/Ctrl + K，输入 user@host 或 user@host:port 后连接。默认端口为 22。快速连接适合临时使用，不会自动保存会话。

需要长期使用时新建保存会话，选择密码或私钥认证，并按需设置分组、标签和启动命令。未填写密码或私钥的导入会话会尝试本机 SSH Agent 和常见默认密钥。

侧边栏分组内可上下拖拽主机调整顺序。拖到另一分组的标题上会放到该组末尾；分组展开后也可以直接拖到组内某一主机的上方或下方插入。在分组标题右键可选择「按名称排序」一次性重排。顺序会保存，新建的主机排在组末尾；搜索过滤和批量多选模式下暂不可拖拽。

安装版支持系统链接，例如：

ssh://root@opsbase.cn:55555

点击后会唤起 OpsXShell，并打开已填好目标的快速连接窗口。为了避免网页静默连接陌生服务器，仍需用户确认连接；链接中禁止携带密码、远程路径、查询参数或片段。

代理与跳板

会话的高级选项支持：

  • HTTP CONNECT 代理
  • SOCKS5 代理
  • 可选代理用户名和密码
  • 选择一个已保存会话作为跳板机

代理和跳板互斥，选择其中一个会清除另一个，避免连接路径含糊。界面保持单跳操作；Rust 连接层可处理已有配置中的最多 8 跳链。

端口转发与 SOCKS5

SSH 连接后，可在状态栏点击「转发」打开右侧抽屉，管理本地转发、远程转发和动态 SOCKS5。动态转发使本机成为 SOCKS5 代理，流量经当前 SSH 服务器出口 IP 访问外网。默认地址：

socks5://127.0.0.1:1080
  • 动态转发每台 SSH 主机仅一条，端口固定 1080；在抽屉中直接启停。
  • 状态栏「转发」右键可复制 socks5://127.0.0.1:1080。需要远程 DNS 解析的命令行工具应使用 socks5h，例如 curl --proxy socks5h://127.0.0.1:1080 https://example.com。
  • 本地转发：本机监听默认只需填端口（绑定 127.0.0.1 / localhost，等同 ssh -L 8080:…）；需要局域网访问时再展开高级项改为内网 IP 或 0.0.0.0。目标主机相对当前 SSH 服务器（常用 127.0.0.1 或内网 IP），不是会话页主机名，且不能填 0.0.0.0。
  • 本地 / 远程规则在抽屉列表中添加、启停和删除；“停止”会关闭 Rust Listener，不是只改界面图标。
  • 远程转发（-R）：远端监听填 127.0.0.1:端口（仅 SSH 服务器本机可访问）或 0.0.0.0:端口（远端内网其它主机也可访问，需 sshd GatewayPorts yes 或 clientspecified）。目标为本机或内网 host:port（不能填 0.0.0.0）。服务器还需 AllowTcpForwarding yes 或 remote；监听端口不能已被占用；<1024 通常需要 root。可用 ssh -R [bind:]port:host:port user@host 对照。
  • “复制规则”会创建独立的新规则，便于只修改端口或目标；不会复制原规则的运行状态。
  • 运行中的规则选择“编辑”时，会先提示停止真实监听，再允许保存新配置。
  • 保存的是规则，不是“运行中”状态；应用重启后需要用户再次启动。同一窗口内只要没点「停止」，SSH 断线、保活失败、空闲挂起或重连都会继续监听（本地 / SOCKS 端口不拆，远程转发会自动重听）。点停止、关闭标签、连接面板手动断开，或退出应用，才会关闭真实 Listener。关闭标签后再开同一会话不会自动拉起转发。
  • SOCKS5 默认仅监听本机，当前不提供局域网开放和客户端密码认证。

连接保活与重连

默认对齐常见 SSH / RDP 客户端，分三层，不要把「窗口还开着」理解成无视服务器超时：

  • 链路心跳：空闲时发 SSH 协议 keep-alive（不写入 Shell）。挡的是 NAT/防火墙丢掉空闲 TCP，挡不住 Bash TMOUT 或 Windows 空闲 GPO。
  • 意外断线：终端、SFTP 或远程桌面标签还开着时，有限次自动重连。SSH 重连后是新 Shell（长任务请在服务器上用 tmux/screen）；SFTP 会回到断线前的远程目录；RDP/VNC 重连是新会话，不会发假鼠标。
  • 会话策略：远端 TMOUT / logout 只关掉那一格 Shell，点「重新打开 Shell」即可。关标签、空闲挂起不会硬续连接。

设置里的「保持心跳」和「自动重连」对应前两层；第三层尊重服务器，客户端不伪造按键。

远程桌面（RDP / VNC）

欢迎页或会话入口可打开 RDP / VNC 连接对话框（仅原生桌面应用）：

  • RDP：填写主机、端口、用户名、密码与可选域名；原生 IronRDP 引擎，支持剪贴板同步与共享盘（本机下载目录对应远端共享盘）。画面铺满当前窗口（任务栏贴底），连接时按窗口客户区请求分辨率；窗口缩放后再走 Display Control。
  • VNC：填写主机、端口与可选密码；原生 RFB 引擎，剪贴板按 UTF-8 发送。
  • 连接后在独立标签中显示画面；工具栏可粘贴本机剪贴板、放入共享盘文件（RDP）或重新连接。标签还开着时网络闪断会有限次自动重连（新会话，不对抗服务器空闲注销）。
  • 桌面会话不参与批量命令与终端广播。

导入 OpenSSH 配置

从应用菜单选择“文件 > 导入会话”，打开 ~/.ssh/config。当前解析以下常用字段：

  • Host
  • HostName
  • User
  • Port
  • IdentityFile
  • 单个 ProxyJump 别名

包含 *、? 或 ! 的 Host 模式不会生成会话。导入后请检查目标、用户名、密钥路径和跳板关系再连接。

会话导出默认保存为 opsxshell-hosts.oxs（密码加密的主机清单，格式类似 KeePass .kdbx、MobaXterm .mxtsessions）。旧版 .bak 与 OpenSSH config 仍可导入。导出包含主机分组、密钥和密码，务必保管备份密码。

SFTP

SFTP 使用双栏文件管理器。中间箭头可上传/下载；上传和下载先写入 .opsx-part 临时文件，中断后再次传输同一路径会从已有字节继续。传输完成并通过大小校验后才替换正式文件，因此失败传输不会伪装成完整文件。

  • 上传：在左侧本地栏选中文件后点中间「上传」箭头；未选择文件时会打开系统原生文件选择器。
  • 下载：在右侧远程栏选中文件后点中间「下载」箭头；未选择远程文件时下载保持禁用。
  • 文件右键菜单也提供对应的「上传」或「下载」操作。
  • 可把左侧本地文件拖到右侧远程栏上传，也可把右侧远程文件拖到左侧本地栏下载；拖到目录行时以该目录为目标，并显示落点高亮。系统未提供拖拽路径时，请改用中间箭头或文件选择器。
  • 当前拖拽只支持单个文件，不递归传输目录；同侧拖拽不会执行移动或重命名。
  • 远程文本编辑直接读写远程文件，不会在本地创建同名文件，也不等同于上传或下载。可编辑类型按扩展名排除归档/二进制等；单文件约 2MB 上限，超限、二进制或非 UTF-8 会提示并拒绝打开，请下载后用本地编辑器处理。
  • 上传/下载若目标已存在同名项，会询问「覆盖」或「跳过」；失败或取消的任务可在传输队列里一键重试。
  • SSH 断线后，SFTP 会按与终端相同的有限次自动重连，并优先回到断线前的远程目录；进行中的传输会标为失败，可重试。也可一键手动重连。
  • 刷新时状态栏显示「正在刷新…」，传输忙时浏览类操作会立即返回忙提示而不是卡住界面。
  • 传输失败会在传输队列和界面通知中显示经多语言映射后的原因。

当前目标文件采用覆盖语义。内容哈希校验和显式冲突选择仍在路线图中。

终端与批量命令

  • Cmd/Ctrl + B：折叠/展开会话侧栏，便于专心操作终端
  • Cmd/Ctrl + D：分屏当前终端
  • Cmd/Ctrl + W：关闭当前标签
  • 终端右键菜单提供复制、粘贴、全选、清屏、向右/向下分屏、最大化/恢复和关闭当前分屏；没有选区时“复制”保持禁用，不会一次右键就直接粘贴。
  • “广播”作用于所有已打开且已连接的 SSH 终端标签和分屏，按钮显示实时目标数；本地 Shell 不加入远程广播。目标不足两个时广播自动关闭。
  • 会话侧栏进入批量模式后，可同时打开终端、SFTP，或在多个主机执行同一条命令
  • 如果远端 Bash 因 TMOUT 显示 timed out waiting for input: auto-logout，OpsXShell 会标记只有该 Shell/分屏退出。SSH 连接、其他分屏、SFTP 和隧道仍可用，点击“重新打开 Shell”即可继续。

批量命令弹框可以再次搜索、全选或调整主机，执行区逐主机显示连接/运行状态、输出、耗时与总进度。结果只保留在当前弹窗；OpsXShell 不持久化终端命令历史。

本地终端与串口

快速启动入口可打开系统默认 Shell。串口入口会列出系统设备，可设置波特率、数据位、停止位和校验方式后连接终端设备。

大模型设置与终端助手

在“设置 → 大模型”中添加 Provider。内置预设包含 DeepSeek、Z.AI/GLM、MiniMax、Kimi、Qwen、OpenAI、Anthropic、OpenRouter、Ollama 和 new-api；也可以从空白配置开始。

  1. 选择供应商预设或“自定义”。新配置只在当前表单中暂存。
  2. 选择模型，核对 Endpoint，输入 API Key。协议和 HTTP 开关位于默认收起的“高级设置”。
  3. 点击“测试连接”。Rust 使用当前表单实际向目标模型发送“你是什么模型？请简短回答。”，但不会保存 Provider 或 API Key。只有服务返回成功状态且回答非空时界面才显示 HTTP 200。
  4. 测试成功后“保存”按钮才会启用。Endpoint、模型、协议或凭据变化后，测试结果立即失效，必须重新测试。
  5. 保存时 API Key 进入 Rust 加密存储，普通设置 JSON 不包含明文，界面重新打开后也不会回显。

预设模型参考 models.dev 与各供应商兼容接口维护。new-api、One API、OpenRouter 等网关使用“自定义”或相应预设，填写自己的 /v1 Endpoint 和实际模型 ID。

终端工具栏点击“AI 助手”打开 Agent CLI：

  • 直接输入任务，例如“排查 nginx 为什么启动失败并修复”。回车发送，Shift+回车 换行；不需要先选“解释 / 生成命令 / 排障 / 执行”。
  • 有终端选区时会作为初始上下文；没有选区时不抓取整屏，Agent 通过真实 ssh-exec 自主取证。
  • Agent 最多执行 12 步。每步只能准备一条单行命令，界面会显示当前主机、命令和五级风险。默认「宽松」仅高风险命令确认；「严格」从中风险开始确认。critical（格式化磁盘、删除根目录等）始终硬拒绝，后端也会再拦一次。
  • 格式化磁盘、删除根目录等 critical 命令会被硬拒绝，不提供确认放行。相同命令第 3 次会在执行前拦截。
  • 执行后的真实输出和退出码会回给 AI，用于判断下一步或收敛结论。连续失败时 Agent 会被要求换方法。
  • 长输出由本地 analyze_output 提取错误行并保留首尾；Rust 在发给云模型前做常见敏感信息脱敏。
  • 关闭面板后任务、命令、工具输出和回答全部清空，不写入历史。
  • 不提供独立 podexec。远程服务器已有的 kubectl、helm、docker 等工具都通过同一 SSH 执行链使用，避免额外管理本机 kubeconfig 和执行目标。

云模型会把所选上下文发给相应供应商；有严格数据边界时使用本机 Ollama，并仅在可信本机上开启 HTTP。OpsXShell 不保存 AI 对话、终端上下文或长期记忆。

界面语言

设置中可切换：简体中文（zh-CN）、繁体中文（zh-TW）、English、日本語、한국어、Tiếng Việt、Русский。首次启动按系统语言自动选择；新增可见文案须同步全部语种，并由 test/i18n/localeKeys.test.ts 校验 key 对齐。验收与单元测试默认中文文案。

本地数据

设置“关于”页会显示当前系统的实际数据路径。会话密码、私钥口令、代理密码和大模型 API Key 使用 AES-256-GCM 加密。主密钥位于：

~/.opsxshell/master.key

Unix 系统中目录权限为 0700，密钥文件权限为 0600。主机信任记录使用 ~/.ssh/known_hosts。