STACIO WIKI · 用户指南

Stacio 远程连接指南

1. 连接方式概览

Stacio 提供三条主要连接路径：

无论通过哪种路径连接，远端账号的授权、主机网络策略和协议安全边界都由目标环境决定。

实际使用中，大多数会话会直接连接 IPv4 地址，例如 192.168.1.20，SSH 不使用默认端口时写成 192.168.1.20:2222。有稳定 DNS 的环境也可以使用 server.example.com 或 server.example.com:2222。本文后续示例优先使用 IP，再补充等价的域名形式。

2. 快速连接

2.1 IP、端口与域名约定

快速连接只有一个“SSH 目标”输入框，可直接接收以下常见形式：

本文中的 IP:端口表示一个完整网络端点，IP 示例以常见 IPv4 为主。它不表示所有界面都把二者写在同一个输入框中：

• 快速连接的单行目标支持 [用户名@]IP[:端口]和[用户名@]域名[:端口]；
• 新建会话、编辑会话和手动 ProxyJump 使用独立的主机与端口字段；
• 独立主机字段只填 192.168.1.20 或 server.example.com，不要填 ssh://、root@ 或 :2222；
• 独立端口字段只填 22、2222 等数字。

2.2 支持的快速连接输入

快速连接当前用于 SSH，支持：

192.168.1.20
192.168.1.20:2222
root@192.168.1.20
deploy@192.168.1.20:2222
host.example.com
user@host.example.com
user@host.example.com:2222
ssh://deploy@192.168.1.20:2222

规则如下：

• 未写端口时使用 22；
• 未写用户名时使用当前 macOS 用户名；
• IP 地址与域名使用相同的用户名和端口规则；
• 用户名、主机或端口为空时会拒绝输入；
• 不要把密码或私钥口令写进目标字符串；应在认证控件中临时输入，或引用已保存凭据；
• 勾选连接成功后保存为会话后，只有连接成功才创建会话。

未勾选保存会话时，快速连接为临时 secret 创建的本地凭据引用会在连接完成或失败后清理；勾选保存时，该引用随会话保留。

2.3 建议用途

• 验证 IP 或域名、端口和账号是否可用；
• 首次确认主机密钥；
• 临时进入主机处理一次性任务；
• 连接成功后再补充标签、环境、AI 策略和跳板机配置。

3. 创建保存会话

选择文件 > 新建会话，然后选择协议。当前新建会话界面可保存：

• SSH；
• Telnet；
• VNC；
• SFTP；
• FTP；
• SCP；
• 串口；
• 本地终端。

RSH、XDMCP、Mosh、S3 和 WSL 会显示为当前版本不可保存或不支持；不要把这些规划项当作已可用连接。

3.1 通用字段

常见保存会话可按以下方式填写：

不要在主机字段中填写 192.168.1.20:2222；在保存会话表单中，这会把端口混入主机字符串。即使协议使用默认端口，也建议保留界面自动填写的明确端口值，便于后续核对和审计。

直接 IP 适合地址稳定、无需 DNS 的局域网、VPN 或固定公网入口；域名适合由 DNS 管理、地址可能切换或需要统一命名的目标。域名连接发生故障时，应同时记录配置域名、解析到的 IP 和端口，但不要未经确认就把保存会话改成解析结果。

3.2 推荐命名与标签

建议会话名能独立表达目标，例如：

prod-api-01
staging-postgres-bastion
lab-switch-console

标签可用于补充 project-a、linux、database、favorite 等信息。生产会话必须把“环境”设为生产，不要只依赖名称中的 prod。

4. SSH 认证

4.1 密码

1. 认证方式选择密码。
2. 填写密码并保存。
3. Stacio 在会话数据库中保存凭据引用，secret 写入 Stacio 本地加密凭据库。
4. 如果凭据文件缺失或无法解密，连接时会要求重新输入并保存。

不要把密码写入会话名称、标签、启动命令、环境变量、连接脚本或导入文件。

4.2 私钥

1. 认证方式选择私钥。
2. 选择本地私钥路径，例如 ~/.ssh/id_ed25519。
3. 私钥有口令时，把口令保存到本地凭据库。
4. 确认当前 macOS 用户仍能读取该私钥文件。

Stacio 保存私钥路径，不会把私钥正文放入普通会话导出。移动或删除私钥后，需要编辑会话并重新选择。

4.3 SSH 代理

选择SSH 代理时，Stacio 不要求保存密码或私钥口令。连接能否成功取决于当前环境中的 SSH agent 是否可用、是否加载了正确密钥，以及远端是否接受相应公钥。

5. 主机密钥确认

5.1 首次连接

Stacio 在发送认证凭据前探测主机密钥。首次连接会显示：

• 主机和端口；
• 密钥算法；
• SHA-256 指纹；
• 未知主机原因。

主机密钥信任以“配置中的主机字符串 + 端口”为连接身份。以下三项会分别确认和保存，不能因为最终可能到达同一台服务器就互相代替：

192.168.1.20:22
192.168.1.20:2222
server.example.com:22

因此，从 IP 改成域名、从域名改成 IP 或修改端口时，出现新的首次信任确认是正常现象；仍须通过可信渠道核对指纹。

核对来源包括云控制台、主机管理员、资产系统或已建立的可信通道。确认后，Stacio 把信任结果保存到本地数据库。

5.2 指纹变化

指纹与已保存值不一致时，Stacio 默认阻断连接。常见合法原因包括主机重装、SSH host key 轮换、IP/DNS 重新分配或跳板目标变化；也可能是中间人攻击。

处理顺序：

1. 停止连接，不要反复尝试或直接接受新指纹。
2. 核对实际目标、DNS、端口、VPN 和跳板机。
3. 通过独立可信渠道取得新指纹。
4. 确认变更经过授权后，再更新本地信任记录。
5. 在诊断或变更记录中保留时间、旧/新指纹摘要和确认人。

5.3 跳板机

ProxyJump 会分别验证跳板机和目标主机的指纹，任何一端不可信都会阻断连接。

6. 跳板机与 ProxyJump

SSH 会话的跳板机区域提供：

• 不使用；
• 已有会话：引用一个已保存的 SSH/SFTP/SCP 会话 ID；
• 手动填写：填写跳板主机、端口、用户、凭据 ID和私钥路径。

推荐使用“已有会话”，便于统一维护主机、账号、凭据和指纹。手动模式适合临时或尚未保存的堡垒入口。

手动模式同样使用独立字段。例如跳板端点 10.0.0.5:2222 应填写主机 = 10.0.0.5、端口 = 2222；使用域名时填写主机 = bastion.example.com、端口 = 22。不要把完整端点粘贴进跳板主机字段。

连接流程为：

Stacio -> 跳板机 SSH -> 目标主机 SSH

注意：

• ProxyJump 是受 License 控制的功能；
• 跳板机会话必须是 SSH、SFTP 或 SCP 类型；
• 目标主机和跳板机均使用独立认证与主机密钥校验；
• 跳板机可达不代表目标主机可达；排障时要分开检查两段链路；
• 不要在连接脚本中手工嵌套 ssh 来绕过 Stacio 的跳板配置和审计边界。

7. 连接后动作与超时

保存 SSH 会话可配置：

因此，需要自动执行的命令只能放在“连接脚本”，并应保持幂等、可审计、低风险。生产环境不建议配置自动变更脚本。

8. 其他协议

8.1 SFTP 与 SCP

• SFTP 会话直接打开内置 SFTP 文件工作区；
• SCP 会话使用 SSH 认证和文件传输上下文；
• 两者默认端口为 22，并使用 SSH 主机密钥流程；
• 常见端点为 192.168.1.20:22；自定义端口可为 192.168.1.20:2222，保存时主机和端口分开填写；
• 文件操作、传输队列和编辑行为见文件指南。

8.2 FTP

• FTP 默认端口为 21；
• 常见 IP 端点可表示为 192.168.1.30:21，域名形式可表示为 files.example.com:21；
• Stacio 会在打开前显示明文协议风险提示；
• 只应在受信任或额外加密的网络中使用；
• FTP 服务器是否支持续传、目录列表和特定文件操作取决于服务端能力。

8.3 Telnet

• Telnet 默认端口为 23；
• 常见网络设备端点可表示为 192.168.1.40:23，非默认端口仍在独立端口字段填写；
• 用户名、密码和终端内容不会被协议加密；
• 应用会显示明文协议警告；
• 仅建议用于隔离网络内无法升级的遗留设备。

8.4 VNC

• VNC 默认端口为 5900；
• 常见端点可表示为 192.168.1.50:5900 或 desktop.example.com:5900；
• 当前安装包必须包含可用的图形适配器；
• 适配器缺失或协议不受支持时，工作区会显示诊断而不是建立图形连接；
• VNC 的认证和传输安全还取决于服务端配置，必要时应通过 SSH 隧道保护。

8.5 串口

串口会话需要选择设备路径，并配置波特率、数据位、停止位、校验、流控和退格键。内置预设覆盖常见网络设备的 9600 8N1 和高速 Console 的 115200 8N1。

设备无法打开时检查：

• 设备是否仍出现在 macOS；
• 是否被其他程序占用；
• USB/蓝牙驱动和权限；
• 交换机或设备的实际串口参数；
• 线缆、转接器和硬件流控要求。

8.6 本地终端

本地终端在 Mac 上运行，不经过远程 SSH 会话。使用本地 Agent 时，必须区分本地 Shell 与通过 stacio-remote 操作的远端终端。

9. 导入会话

9.1 支持的来源

文件 > 导入会话当前列出：

堡垒机导入属于受 License 控制的连接编排功能。

9.2 安全导入流程

1. 选择明确的来源类型和原始导出文件。
2. 检查预览中的名称、分组、协议、目标和冲突状态。
3. 确认端口和用户名没有被错误解析。
4. 对重名会话选择跳过、覆盖或重命名策略。
5. 导入后重新配置密码、Token 或私钥口令。
6. 首次连接时重新核对主机密钥。

导入不会把外部文件中的明文密码当作可信凭据。Stacio 格式导入也会过滤凭据引用和自动执行字段；例如导入文件中的连接脚本或启动命令不会被静默继承。

9.3 导入失败

在视图 > 诊断查看“导入报告”，重点检查：

• 文件格式与所选来源是否一致；
• 厂商版本是否受支持；
• 压缩包结构是否完整；
• 端口、主机或协议字段是否无效；
• 重名会话的冲突策略；
• 当前 License 是否允许对应导入模块。

10. 会话维护

10.1 临时更换用户

右键会话选择连接为...，输入用户名后可临时打开连接，保存的会话不会被修改。适合使用同一主机的不同低权限账号进行验证。

10.2 Ping 主机

右键选择Ping 主机会显示持续输出并允许停止。Ping 只接收 IP 或域名，不检查 IP:端口；Ping 不通也不一定代表 SSH 不通，原因可能包括 ICMP 被禁、路由策略或本机权限。验证 192.168.1.20:2222 这类端点时，仍应在诊断 > 端口检查中分别填写主机 192.168.1.20 和端口 2222。

10.3 复制、移动和导出

• 复制会话会创建独立配置；复制后应检查名称、环境和凭据引用；
• 移动只改变侧栏分组；
• 导出适合迁移非敏感配置，不能替代凭据备份；
• 创建桌面快捷方式后，仍由 Stacio 执行实际连接和主机密钥校验。

11. 断线与重连

SSH 终端会区分连接中、运行中、断开、重连中和已关闭。网络中断后可能自动重连，延迟会逐步增加；手动关闭或取消后不会继续自动重连。

重连前检查：

1. 当前标签仍指向预期会话。
2. VPN、Wi-Fi、有线网络或代理已恢复。
3. 主机和端口没有变化。
4. 凭据仍有效，SSH agent 仍加载正确密钥。
5. 主机密钥没有出现未经确认的变化。

自动重连只恢复连接，不保证远端前台程序、事务、文件写入或未完成命令能从中断点继续。

12. 错误定位

需要提交问题时，提供 Stacio 版本、macOS 版本、协议、目标端口、错误发生时间、是否经过跳板机、认证类型和已脱敏诊断；不要提交 secret 或私钥正文。