opsxshell/homepage/dist/docs/quickstart/index.html

<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>快速上手 · OpsXShell 文档</title>
<meta name="description" content="OpsXShell 运维终端用户文档 — SSH、SFTP、端口转发、RDP/VNC、串口与终端 AI。">
<link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3E%3Crect width='32' height='32' rx='7' fill='%232563eb'/%3E%3Ctext x='16' y='22' font-size='18' font-weight='bold' fill='%23fff' text-anchor='middle' font-family='sans-serif'%3EO%3C/text%3E%3C/svg%3E">
<link rel="icon" type="image/svg+xml" href="data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2064%2064%22%3E%3Cdefs%3E%3ClinearGradient%20id%3D%22g%22%20x1%3D%220%22%20y1%3D%220%22%20x2%3D%2264%22%20y2%3D%2264%22%20gradientUnits%3D%22userSpaceOnUse%22%3E%3Cstop%20offset%3D%220%22%20stop-color%3D%22%232563EB%22%2F%3E%3Cstop%20offset%3D%221%22%20stop-color%3D%22%2306B6D4%22%2F%3E%3C%2FlinearGradient%3E%3C%2Fdefs%3E%3Crect%20width%3D%2264%22%20height%3D%2264%22%20rx%3D%2214%22%20fill%3D%22url%28%23g%29%22%2F%3E%3Cg%20stroke%3D%22%23fff%22%20stroke-width%3D%225%22%20stroke-linecap%3D%22round%22%20stroke-linejoin%3D%22round%22%20fill%3D%22none%22%3E%3Cpath%20d%3D%22M17%2025h26%22%2F%3E%3Cpath%20d%3D%22M37%2019l6%206-6%206%22%2F%3E%3Cpath%20d%3D%22M47%2039H21%22%2F%3E%3Cpath%20d%3D%22M27%2033l-6%206%206%206%22%2F%3E%3C%2Fg%3E%3C%2Fsvg%3E">
<link rel="stylesheet" href="/docs/assets/docs.css">
</head>
<body>
<svg xmlns="http://www.w3.org/2000/svg" style="display:none" aria-hidden="true">
<symbol id="i-menu" viewBox="0 0 24 24"><path d="M4 5h16" /> <path d="M4 12h16" /> <path d="M4 19h16" /></symbol>
<symbol id="i-printer" viewBox="0 0 24 24"><path d="M6 18H4a2 2 0 0 1-2-2v-5a2 2 0 0 1 2-2h16a2 2 0 0 1 2 2v5a2 2 0 0 1-2 2h-2" /> <path d="M6 9V3a1 1 0 0 1 1-1h10a1 1 0 0 1 1 1v6" /> <rect x="6" y="14" width="12" height="8" rx="1" /></symbol>
<symbol id="i-thumbs-up" viewBox="0 0 24 24"><path d="M15 5.88 14 10h5.83a2 2 0 0 1 1.92 2.56l-2.33 8A2 2 0 0 1 17.5 22H4a2 2 0 0 1-2-2v-8a2 2 0 0 1 2-2h2.76a2 2 0 0 0 1.79-1.11L12 2a3.13 3.13 0 0 1 3 3.88Z" /> <path d="M7 10v12" /></symbol>
<symbol id="i-thumbs-down" viewBox="0 0 24 24"><path d="M9 18.12 10 14H4.17a2 2 0 0 1-1.92-2.56l2.33-8A2 2 0 0 1 6.5 2H20a2 2 0 0 1 2 2v8a2 2 0 0 1-2 2h-2.76a2 2 0 0 0-1.79 1.11L12 22a3.13 3.13 0 0 1-3-3.88Z" /> <path d="M17 14V2" /></symbol>
<symbol id="i-rocket" viewBox="0 0 24 24"><path d="M12 15v5s3.03-.55 4-2c1.08-1.62 0-5 0-5" /> <path d="M4.5 16.5c-1.5 1.26-2 5-2 5s3.74-.5 5-2c.71-.84.7-2.13-.09-2.91a2.18 2.18 0 0 0-2.91-.09" /> <path d="M9 12a22 22 0 0 1 2-3.95A12.88 12.88 0 0 1 22 2c0 2.72-.78 7.5-6 11a22.4 22.4 0 0 1-4 2z" /> <path d="M9 12H4s.55-3.03 2-4c1.62-1.08 5 .05 5 .05" /></symbol>
<symbol id="i-shield-check" viewBox="0 0 24 24"><path d="M20 13c0 5-3.5 7.5-7.66 8.95a1 1 0 0 1-.67-.01C7.5 20.5 4 18 4 13V6a1 1 0 0 1 1-1c2 0 4.5-1.2 6.24-2.72a1.17 1.17 0 0 1 1.52 0C14.51 3.81 17 5 19 5a1 1 0 0 1 1 1z" /> <path d="m9 12 2 2 4-4" /></symbol>
<symbol id="i-arrow-left-right" viewBox="0 0 24 24"><path d="M8 3 4 7l4 4" /> <path d="M4 7h16" /> <path d="m16 21 4-4-4-4" /> <path d="M20 17H4" /></symbol>
<symbol id="i-plug-zap" viewBox="0 0 24 24"><path d="M6.3 20.3a2.4 2.4 0 0 0 3.4 0L12 18l-6-6-2.3 2.3a2.4 2.4 0 0 0 0 3.4Z" /> <path d="m2 22 3-3" /> <path d="M7.5 13.5 10 11" /> <path d="M10.5 16.5 13 14" /> <path d="m18 3-4 4h6l-4 4" /></symbol>
<symbol id="i-package" viewBox="0 0 24 24"><path d="M11 21.73a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16V8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73z" /> <path d="M12 22V12" /> <polyline points="3.29 7 12 12 20.71 7" /> <path d="m7.5 4.27 9 5.15" /></symbol>
<symbol id="i-folder-tree" viewBox="0 0 24 24"><path d="M20 10a1 1 0 0 0 1-1V6a1 1 0 0 0-1-1h-2.5a1 1 0 0 1-.8-.4l-.9-1.2A1 1 0 0 0 15 3h-2a1 1 0 0 0-1 1v5a1 1 0 0 0 1 1Z" /> <path d="M20 21a1 1 0 0 0 1-1v-3a1 1 0 0 0-1-1h-2.9a1 1 0 0 1-.88-.55l-.42-.85a1 1 0 0 0-.92-.6H13a1 1 0 0 0-1 1v5a1 1 0 0 0 1 1Z" /> <path d="M3 5a2 2 0 0 0 2 2h3" /> <path d="M3 3v13a2 2 0 0 0 2 2h3" /></symbol>
<symbol id="i-globe" viewBox="0 0 24 24"><circle cx="12" cy="12" r="10" /> <path d="M12 2a14.5 14.5 0 0 0 0 20 14.5 14.5 0 0 0 0-20" /> <path d="M2 12h20" /></symbol>
<symbol id="i-hexagon" viewBox="0 0 24 24"><path d="M21 16V8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73l7 4a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16z" /></symbol>
<symbol id="i-zap" viewBox="0 0 24 24"><path d="M15.914 4a1.5 1.5 0 00-2.474-1.561l-9 9A1.5 1.5 0 005.5 14h4.002a.5.5 0 01.471.666L8.086 20a1.5 1.5 0 002.475 1.56l9-9A1.5 1.5 0 0018.5 10h-3.997a.5.5 0 01-.472-.667z" /></symbol>
<symbol id="i-radio" viewBox="0 0 24 24"><path d="M16.247 7.761a6 6 0 0 1 0 8.478" /> <path d="M19.075 4.933a10 10 0 0 1 0 14.134" /> <path d="M4.925 19.067a10 10 0 0 1 0-14.134" /> <path d="M7.753 16.239a6 6 0 0 1 0-8.478" /> <circle cx="12" cy="12" r="2" /></symbol>
<symbol id="i-mailbox" viewBox="0 0 24 24"><path d="M22 17a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2V9.5C2 7 4 5 6.5 5H18c2.2 0 4 1.8 4 4v8Z" /> <polyline points="15,9 18,9 18,11" /> <path d="M6.5 5C9 5 11 7 11 9.5V17a2 2 0 0 1-2 2" /> <line x1="6" x2="7" y1="10" y2="10" /></symbol>
<symbol id="i-code" viewBox="0 0 24 24"><path d="m16 18 6-6-6-6" /> <path d="m8 6-6 6 6 6" /></symbol>
<symbol id="i-book-open" viewBox="0 0 24 24"><path d="M12 5v16" /> <path d="M20.001 19A2 2 0 0022 17V5a2 2 0 00-1.999-2L16 3.002A5 5 0 0012 5a5 5 0 00-4-2H4a2 2 0 00-2 2v12a2 2 0 001.999 2H8a5 5 0 014 2 5 5 0 014-2z" /></symbol>
<symbol id="i-sprout" viewBox="0 0 24 24"><path d="M14 9.536V7a4 4 0 0 1 4-4h1.5a.5.5 0 0 1 .5.5V5a4 4 0 0 1-4 4 4 4 0 0 0-4 4c0 2 1 3 1 5a5 5 0 0 1-1 3" /> <path d="M4 9a5 5 0 0 1 8 4 5 5 0 0 1-8-4" /> <path d="M5 21h14" /></symbol>
<symbol id="i-graduation-cap" viewBox="0 0 24 24"><path d="M21.42 10.922a1 1 0 0 0-.019-1.838L12.83 5.18a2 2 0 0 0-1.66 0L2.6 9.08a1 1 0 0 0 0 1.832l8.57 3.908a2 2 0 0 0 1.66 0z" /> <path d="M22 10v6" /> <path d="M6 12.5V16a6 3 0 0 0 12 0v-3.5" /></symbol>
<symbol id="i-credit-card" viewBox="0 0 24 24"><rect width="20" height="14" x="2" y="5" rx="2" /> <line x1="2" x2="22" y1="10" y2="10" /> <path d="M6 14h2" /></symbol>
<symbol id="i-megaphone" viewBox="0 0 24 24"><path d="M11 6a13 13 0 0 0 8.4-2.8A1 1 0 0 1 21 4v12a1 1 0 0 1-1.6.8A13 13 0 0 0 11 14H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2z" /> <path d="M6 14a12 12 0 0 0 2.4 7.2 2 2 0 0 0 3.2-2.4A8 8 0 0 1 10 14" /> <path d="M8 6v8" /></symbol>
<symbol id="i-download" viewBox="0 0 24 24"><path d="M12 15V3" /> <path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4" /> <path d="m7 10 5 5 5-5" /></symbol>
<symbol id="i-upload" viewBox="0 0 24 24"><path d="M12 3v12" /> <path d="m17 8-5-5-5 5" /> <path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4" /></symbol>
<symbol id="i-library" viewBox="0 0 24 24"><path d="m16 6 4 14" /> <path d="M12 6v14" /> <path d="M8 8v12" /> <path d="M4 4v16" /></symbol>
<symbol id="i-settings" viewBox="0 0 24 24"><path d="M9.671 4.136a2.34 2.34 0 0 1 4.659 0 2.34 2.34 0 0 0 3.319 1.915 2.34 2.34 0 0 1 2.33 4.033 2.34 2.34 0 0 0 0 3.831 2.34 2.34 0 0 1-2.33 4.033 2.34 2.34 0 0 0-3.319 1.915 2.34 2.34 0 0 1-4.659 0 2.34 2.34 0 0 0-3.32-1.915 2.34 2.34 0 0 1-2.33-4.033 2.34 2.34 0 0 0 0-3.831A2.34 2.34 0 0 1 6.35 6.051a2.34 2.34 0 0 0 3.319-1.915" /> <circle cx="12" cy="12" r="3" /></symbol>
<symbol id="i-search" viewBox="0 0 24 24"><path d="m21 21-4.34-4.34" /> <circle cx="11" cy="11" r="8" /></symbol>
</svg>
<header class="topbar">
  <div class="topbar-inner">
    <button class="menu-btn" id="menu-btn" aria-label="打开导航"><svg class="i"><use href="#i-menu"/></svg></button>
    <a class="brand" href="/docs">
      <span class="brand-logo"><svg width="28" height="28" viewBox="0 0 64 64" aria-label="OpsXShell"><defs><linearGradient id="lg-docs" x1="0" y1="0" x2="64" y2="64" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#2563EB"/><stop offset="1" stop-color="#06B6D4"/></linearGradient></defs><rect width="64" height="64" rx="14" fill="url(#lg-docs)"/><g stroke="#fff" stroke-width="5" stroke-linecap="round" stroke-linejoin="round" fill="none"><path d="M17 25h26"/><path d="M37 19l6 6-6 6"/><path d="M47 39H21"/><path d="M27 33l-6 6 6 6"/></g></svg></span>
      <span class="brand-name">OpsXShell <em>文档</em></span>
    </a>
    <span class="ver-badge">v2.1.1</span>
    <div class="search">
      <input id="search-input" type="search" placeholder="搜索文档…" autocomplete="off" spellcheck="false">
      <div class="search-panel" id="search-panel" hidden></div>
    </div>
    <nav class="top-links">
      <a href="/">官网</a>
      <a href="/#download">下载</a>
    </nav>
  </div>
</header>

<div class="layout" id="layout">
  <aside class="sidebar" id="sidebar">
    
    <div class="nav-group">
      <div class="nav-group-title">开始使用</div>
      
      <a class="nav-link" href="/docs/overview">概述</a>
      
      <a class="nav-link active" href="/docs/quickstart">快速上手</a>
      
    </div>
    
    <div class="nav-group">
      <div class="nav-group-title">进阶</div>
      
      <a class="nav-link" href="/docs/ai">终端 AI</a>
      
    </div>
    
    <div class="sidebar-foot">© 2026 OpsXShell · 本地优先的运维终端</div>
  </aside>

  <main class="content">
    <div class="breadcrumb">文档 <span>/</span> 开始使用 <span>/</span> 快速上手</div>
    <h1 class="page-title">快速上手</h1>
    
    <article class="md">
<h1>使用指南</h1>
<p>OpsXShell 主打简单好用：常用远程操作走短路径，高级选项默认收起。不做堡垒审计。</p>
<h2 id="sec-1">安装（macOS）</h2>
<p>从 <code>release/v*/macos-arm64/</code> 打开 <code>.dmg</code>，把 OpsXShell 拖到「应用程序」。Finder 里应是 Tauri 那套大图标布局（应用在左、Applications 在右）。<strong>已经 staple 的正式包</strong>一般可直接打开。</p>
<p>自己改代码后重新打包：先 <code>./scripts/build.sh mac-arm64 --quick</code>（本机有签名配置就会签 Developer ID），再 <code>./scripts/macos-notarize.sh</code>（会要 App 专用密码）。新打的 DMG 在公证完成前仍会被 Gatekeeper 拦截。你现在要做的步骤见 <a href="./release.md#macos-next-steps">发布指南</a>。</p>
<h2 id="sec-2">快速连接</h2>
<p>按 <code>Cmd/Ctrl + K</code>，输入 <code>user@host</code> 或 <code>user@host:port</code> 后连接。默认端口为 <code>22</code>。快速连接适合临时使用，不会自动保存会话。</p>
<p>需要长期使用时新建保存会话，选择密码或私钥认证，并按需设置分组、标签和启动命令。未填写密码或私钥的导入会话会尝试本机 SSH Agent 和常见默认密钥。</p>
<p>侧边栏分组内可上下拖拽主机调整顺序。拖到另一分组的标题上会放到该组末尾；分组展开后也可以直接拖到组内某一主机的上方或下方插入。在分组标题右键可选择「按名称排序」一次性重排。顺序会保存，新建的主机排在组末尾；搜索过滤和批量多选模式下暂不可拖拽。</p>
<p>安装版支持系统链接，例如：</p>
<pre><code class="language-text">ssh://root@opsbase.cn:55555
</code></pre>
<p>点击后会唤起 OpsXShell，并打开已填好目标的快速连接窗口。为了避免网页静默连接陌生服务器，仍需用户确认连接；链接中禁止携带密码、远程路径、查询参数或片段。</p>
<h2 id="sec-3">代理与跳板</h2>
<p>会话的高级选项支持：</p>
<ul>
<li>HTTP CONNECT 代理</li>
<li>SOCKS5 代理</li>
<li>可选代理用户名和密码</li>
<li>选择一个已保存会话作为跳板机</li>
</ul>
<p>代理和跳板互斥，选择其中一个会清除另一个，避免连接路径含糊。界面保持单跳操作；Rust 连接层可处理已有配置中的最多 8 跳链。</p>
<h2 id="sec-4">端口转发与 SOCKS5</h2>
<p>SSH 连接后，可在状态栏点击「转发」打开右侧抽屉，管理本地转发、远程转发和动态 SOCKS5。动态转发使本机成为 SOCKS5 代理，流量经当前 SSH 服务器出口 IP 访问外网。默认地址：</p>
<pre><code class="language-text">socks5://127.0.0.1:1080
</code></pre>
<ul>
<li>动态转发每台 SSH 主机仅一条，端口固定 <code>1080</code>；在抽屉中直接启停。</li>
<li>状态栏「转发」右键可复制 <code>socks5://127.0.0.1:1080</code>。需要远程 DNS 解析的命令行工具应使用 <code>socks5h</code>，例如 <code>curl --proxy socks5h://127.0.0.1:1080 https://example.com</code>。</li>
<li>本地转发：本机监听默认只需填端口（绑定 <code>127.0.0.1</code> / localhost，等同 <code>ssh -L 8080:…</code>）；需要局域网访问时再展开高级项改为内网 IP 或 <code>0.0.0.0</code>。目标主机相对当前 SSH 服务器（常用 <code>127.0.0.1</code> 或内网 IP），不是会话页主机名，且不能填 <code>0.0.0.0</code>。</li>
<li>本地 / 远程规则在抽屉列表中添加、启停和删除；“停止”会关闭 Rust Listener，不是只改界面图标。</li>
<li>远程转发（<code>-R</code>）：远端监听填 <code>127.0.0.1:端口</code>（仅 SSH 服务器本机可访问）或 <code>0.0.0.0:端口</code>（远端内网其它主机也可访问，需 sshd <code>GatewayPorts yes</code> 或 <code>clientspecified</code>）。目标为本机或内网 <code>host:port</code>（不能填 <code>0.0.0.0</code>）。服务器还需 <code>AllowTcpForwarding yes</code> 或 <code>remote</code>；监听端口不能已被占用；<code>&lt;1024</code> 通常需要 root。可用 <code>ssh -R [bind:]port:host:port user@host</code> 对照。</li>
<li>“复制规则”会创建独立的新规则，便于只修改端口或目标；不会复制原规则的运行状态。</li>
<li>运行中的规则选择“编辑”时，会先提示停止真实监听，再允许保存新配置。</li>
<li>保存的是规则，不是“运行中”状态；应用重启后需要用户再次启动。同一窗口内只要没点「停止」，SSH 断线、保活失败、空闲挂起或重连都会继续监听（本地 / SOCKS 端口不拆，远程转发会自动重听）。点停止、关闭标签、连接面板手动断开，或退出应用，才会关闭真实 Listener。关闭标签后再开同一会话不会自动拉起转发。</li>
<li>SOCKS5 默认仅监听本机，当前不提供局域网开放和客户端密码认证。</li>
</ul>
<h2 id="sec-5">连接保活与重连</h2>
<p>默认对齐常见 SSH / RDP 客户端，分三层，不要把「窗口还开着」理解成无视服务器超时：</p>
<ul>
<li><strong>链路心跳</strong>：空闲时发 SSH 协议 keep-alive（不写入 Shell）。挡的是 NAT/防火墙丢掉空闲 TCP，挡不住 Bash <code>TMOUT</code> 或 Windows 空闲 GPO。</li>
<li><strong>意外断线</strong>：终端、SFTP 或远程桌面标签还开着时，有限次自动重连。SSH 重连后是新 Shell（长任务请在服务器上用 <code>tmux</code>/<code>screen</code>）；SFTP 会回到断线前的远程目录；RDP/VNC 重连是新会话，不会发假鼠标。</li>
<li><strong>会话策略</strong>：远端 <code>TMOUT</code> / <code>logout</code> 只关掉那一格 Shell，点「重新打开 Shell」即可。关标签、空闲挂起不会硬续连接。</li>
</ul>
<p>设置里的「保持心跳」和「自动重连」对应前两层；第三层尊重服务器，客户端不伪造按键。</p>
<h2 id="sec-6">远程桌面（RDP / VNC）</h2>
<p>欢迎页或会话入口可打开 RDP / VNC 连接对话框（仅原生桌面应用）：</p>
<ul>
<li>RDP：填写主机、端口、用户名、密码与可选域名；原生 IronRDP 引擎，支持剪贴板同步与共享盘（本机下载目录对应远端共享盘）。画面铺满当前窗口（任务栏贴底），连接时按窗口客户区请求分辨率；窗口缩放后再走 Display Control。</li>
<li>VNC：填写主机、端口与可选密码；原生 RFB 引擎，剪贴板按 UTF-8 发送。</li>
<li>连接后在独立标签中显示画面；工具栏可粘贴本机剪贴板、放入共享盘文件（RDP）或重新连接。标签还开着时网络闪断会有限次自动重连（新会话，不对抗服务器空闲注销）。</li>
<li>桌面会话不参与批量命令与终端广播。</li>
</ul>
<h2 id="sec-7">导入 OpenSSH 配置</h2>
<p>从应用菜单选择“文件 &gt; 导入会话”，打开 <code>~/.ssh/config</code>。当前解析以下常用字段：</p>
<ul>
<li><code>Host</code></li>
<li><code>HostName</code></li>
<li><code>User</code></li>
<li><code>Port</code></li>
<li><code>IdentityFile</code></li>
<li>单个 <code>ProxyJump</code> 别名</li>
</ul>
<p>包含 <code>*</code>、<code>?</code> 或 <code>!</code> 的 Host 模式不会生成会话。导入后请检查目标、用户名、密钥路径和跳板关系再连接。</p>
<p>会话导出默认保存为 <code>opsxshell-hosts.oxs</code>（密码加密的主机清单，格式类似 KeePass <code>.kdbx</code>、MobaXterm <code>.mxtsessions</code>）。旧版 <code>.bak</code> 与 OpenSSH <code>config</code> 仍可导入。导出包含主机分组、密钥和密码，务必保管备份密码。</p>
<h2 id="sec-8">SFTP</h2>
<p>SFTP 使用双栏文件管理器。中间箭头可上传/下载；上传和下载先写入 <code>.opsx-part</code> 临时文件，中断后再次传输同一路径会从已有字节继续。传输完成并通过大小校验后才替换正式文件，因此失败传输不会伪装成完整文件。</p>
<ul>
<li>上传：在左侧本地栏选中文件后点中间「上传」箭头；未选择文件时会打开系统原生文件选择器。</li>
<li>下载：在右侧远程栏选中文件后点中间「下载」箭头；未选择远程文件时下载保持禁用。</li>
<li>文件右键菜单也提供对应的「上传」或「下载」操作。</li>
<li>可把左侧本地文件拖到右侧远程栏上传，也可把右侧远程文件拖到左侧本地栏下载；拖到目录行时以该目录为目标，并显示落点高亮。系统未提供拖拽路径时，请改用中间箭头或文件选择器。</li>
<li>当前拖拽只支持单个文件，不递归传输目录；同侧拖拽不会执行移动或重命名。</li>
<li>远程文本编辑直接读写远程文件，不会在本地创建同名文件，也不等同于上传或下载。可编辑类型按扩展名排除归档/二进制等；单文件约 <strong>2MB</strong> 上限，超限、二进制或非 UTF-8 会提示并拒绝打开，请下载后用本地编辑器处理。</li>
<li>上传/下载若目标已存在同名项，会询问「覆盖」或「跳过」；失败或取消的任务可在传输队列里一键重试。</li>
<li>SSH 断线后，SFTP 会按与终端相同的有限次自动重连，并优先回到断线前的远程目录；进行中的传输会标为失败，可重试。也可一键手动重连。</li>
<li>刷新时状态栏显示「正在刷新…」，传输忙时浏览类操作会立即返回忙提示而不是卡住界面。</li>
<li>传输失败会在传输队列和界面通知中显示经多语言映射后的原因。</li>
</ul>
<p>当前目标文件采用覆盖语义。内容哈希校验和显式冲突选择仍在路线图中。</p>
<h2 id="sec-9">终端与批量命令</h2>
<ul>
<li><code>Cmd/Ctrl + B</code>：折叠/展开会话侧栏，便于专心操作终端</li>
<li><code>Cmd/Ctrl + D</code>：分屏当前终端</li>
<li><code>Cmd/Ctrl + W</code>：关闭当前标签</li>
<li>终端右键菜单提供复制、粘贴、全选、清屏、向右/向下分屏、最大化/恢复和关闭当前分屏；没有选区时“复制”保持禁用，不会一次右键就直接粘贴。</li>
<li>“广播”作用于所有已打开且已连接的 SSH 终端标签和分屏，按钮显示实时目标数；本地 Shell 不加入远程广播。目标不足两个时广播自动关闭。</li>
<li>会话侧栏进入批量模式后，可同时打开终端、SFTP，或在多个主机执行同一条命令</li>
<li>如果远端 Bash 因 <code>TMOUT</code> 显示 <code>timed out waiting for input: auto-logout</code>，OpsXShell 会标记只有该 Shell/分屏退出。SSH 连接、其他分屏、SFTP 和隧道仍可用，点击“重新打开 Shell”即可继续。</li>
</ul>
<p>批量命令弹框可以再次搜索、全选或调整主机，执行区逐主机显示连接/运行状态、输出、耗时与总进度。结果只保留在当前弹窗；OpsXShell 不持久化终端命令历史。</p>
<h2 id="sec-10">本地终端与串口</h2>
<p>快速启动入口可打开系统默认 Shell。串口入口会列出系统设备，可设置波特率、数据位、停止位和校验方式后连接终端设备。</p>
<h2 id="sec-11">大模型设置与终端助手</h2>
<p>在“设置 → 大模型”中添加 Provider。内置预设包含 DeepSeek、Z.AI/GLM、MiniMax、Kimi、Qwen、OpenAI、Anthropic、OpenRouter、Ollama 和 new-api；也可以从空白配置开始。</p>
<ol>
<li>选择供应商预设或“自定义”。新配置只在当前表单中暂存。</li>
<li>选择模型，核对 Endpoint，输入 API Key。协议和 HTTP 开关位于默认收起的“高级设置”。</li>
<li>点击“测试连接”。Rust 使用当前表单实际向目标模型发送“你是什么模型？请简短回答。”，但不会保存 Provider 或 API Key。只有服务返回成功状态且回答非空时界面才显示 <code>HTTP 200</code>。</li>
<li>测试成功后“保存”按钮才会启用。Endpoint、模型、协议或凭据变化后，测试结果立即失效，必须重新测试。</li>
<li>保存时 API Key 进入 Rust 加密存储，普通设置 JSON 不包含明文，界面重新打开后也不会回显。</li>
</ol>
<p>预设模型参考 models.dev 与各供应商兼容接口维护。new-api、One API、OpenRouter 等网关使用“自定义”或相应预设，填写自己的 <code>/v1</code> Endpoint 和实际模型 ID。</p>
<p>终端工具栏点击“AI 助手”打开 Agent CLI：</p>
<ul>
<li>直接输入任务，例如“排查 nginx 为什么启动失败并修复”。回车发送，<code>Shift+回车</code> 换行；不需要先选“解释 / 生成命令 / 排障 / 执行”。</li>
<li>有终端选区时会作为初始上下文；没有选区时不抓取整屏，Agent 通过真实 <code>ssh-exec</code> 自主取证。</li>
<li>Agent 最多执行 12 步。每步只能准备一条单行命令，界面会显示当前主机、命令和五级风险。默认「宽松」仅高风险命令确认；「严格」从中风险开始确认。critical（格式化磁盘、删除根目录等）始终硬拒绝，后端也会再拦一次。</li>
<li>格式化磁盘、删除根目录等 critical 命令会被硬拒绝，不提供确认放行。相同命令第 3 次会在执行前拦截。</li>
<li>执行后的真实输出和退出码会回给 AI，用于判断下一步或收敛结论。连续失败时 Agent 会被要求换方法。</li>
<li>长输出由本地 <code>analyze_output</code> 提取错误行并保留首尾；Rust 在发给云模型前做常见敏感信息脱敏。</li>
<li>关闭面板后任务、命令、工具输出和回答全部清空，不写入历史。</li>
<li>不提供独立 podexec。远程服务器已有的 <code>kubectl</code>、<code>helm</code>、<code>docker</code> 等工具都通过同一 SSH 执行链使用，避免额外管理本机 kubeconfig 和执行目标。</li>
</ul>
<p>云模型会把所选上下文发给相应供应商；有严格数据边界时使用本机 Ollama，并仅在可信本机上开启 HTTP。OpsXShell 不保存 AI 对话、终端上下文或长期记忆。</p>
<h2 id="sec-12">界面语言</h2>
<p>设置中可切换：简体中文（zh-CN）、繁体中文（zh-TW）、English、日本語、한국어、Tiếng Việt、Русский。首次启动按系统语言自动选择；新增可见文案须同步全部语种，并由 <code>test/i18n/localeKeys.test.ts</code> 校验 key 对齐。验收与单元测试默认中文文案。</p>
<h2 id="sec-13">本地数据</h2>
<p>设置“关于”页会显示当前系统的实际数据路径。会话密码、私钥口令、代理密码和大模型 API Key 使用 AES-256-GCM 加密。主密钥位于：</p>
<pre><code class="language-text">~/.opsxshell/master.key
</code></pre>
<p>Unix 系统中目录权限为 <code>0700</code>，密钥文件权限为 <code>0600</code>。主机信任记录使用 <code>~/.ssh/known_hosts</code>。</p>

    </article>

    <div class="pn-nav">
      
      <a class="pn prev" href="/docs/overview"><span class="pn-label">← 上一页</span><span class="pn-title">概述</span></a>
      
      
      <a class="pn next" href="/docs/ai"><span class="pn-label">下一页 →</span><span class="pn-title">终端 AI</span></a>
      
    </div>

    <div class="feedback" id="feedback">
      <span class="feedback-q">本页内容是否对您有帮助？</span>
      <button class="fb-btn" data-v="yes"><svg class="i"><use href="#i-thumbs-up"/></svg> 有帮助</button>
      <button class="fb-btn" data-v="no"><svg class="i"><use href="#i-thumbs-down"/></svg> 没有帮助</button>
      <span class="fb-thanks" id="fb-thanks" hidden>感谢您的反馈！</span>
    </div>
  </main>

  <aside class="toc">
    <div class="toc-title">本页目录</div>
    <nav class="toc-nav">
      <a class="toc-l2" href="#sec-1">安装（macOS）</a>
      <a class="toc-l2" href="#sec-2">快速连接</a>
      <a class="toc-l2" href="#sec-3">代理与跳板</a>
      <a class="toc-l2" href="#sec-4">端口转发与 SOCKS5</a>
      <a class="toc-l2" href="#sec-5">连接保活与重连</a>
      <a class="toc-l2" href="#sec-6">远程桌面（RDP / VNC）</a>
      <a class="toc-l2" href="#sec-7">导入 OpenSSH 配置</a>
      <a class="toc-l2" href="#sec-8">SFTP</a>
      <a class="toc-l2" href="#sec-9">终端与批量命令</a>
      <a class="toc-l2" href="#sec-10">本地终端与串口</a>
      <a class="toc-l2" href="#sec-11">大模型设置与终端助手</a>
      <a class="toc-l2" href="#sec-12">界面语言</a>
      <a class="toc-l2" href="#sec-13">本地数据</a>
      
    </nav>
    <button class="print-btn" id="print-btn"><svg class="i"><use href="#i-printer"/></svg> 打印 / 导出 PDF</button>
  </aside>
</div>

<script src="/docs/assets/docs.js" defer></script>
</body>
</html>