STACIO WIKI · 网络指南

Stacio 隧道指南

1. 隧道是什么

Stacio 的隧道功能通过现有 SSH 认证链路转发 TCP 流量。它支持三种类型：

隧道不会创建新的远端账号权限，也不会绕过防火墙、SSH 服务端转发策略或组织审批。功能入口受 SSH 隧道 License 控制。

2. 使用前准备

启动隧道前确认：

1. 已保存并验证一个 SSH、SFTP 或 SCP 会话，或当前已打开可用的 SSH/SCP 连接；
2. SSH 账号和认证方式有效；
3. 首次连接的主机密钥已通过可信渠道核对；
4. 目标服务确实监听在预期地址和端口；
5. Local/Dynamic 使用的本地端口未被其他进程占用；
6. SSH 服务端允许所需的 TCP forwarding；
7. 生产环境的访问、反向暴露和代理行为已获批准。

建议先建立普通 SSH 终端并完成最小只读验证，再创建隧道。这样可以先区分认证问题、SSH 问题和目标服务问题。

多数情况下，SSH 入口是 192.168.1.20:22 或 192.168.1.20:2222 这样的 IP 端点；有稳定 DNS 时也可以是 gateway.example.com:22。隧道目标则可能是 SSH 主机可访问的另一个内网 IP 或域名，两者不要混为同一地址。

3. 打开隧道面板

1. 选择视图 > 隧道，或点击工具栏隧道。
2. 检查器中会显示已保存的隧道配置。
3. 表格包含类型、本地端点、远端端点、状态、详情和流量。
4. 使用顶部的新增、编辑、删除按钮管理配置；每行的启动或停止按钮管理运行态。

若入口灰色并提示“该功能模块无有效授权，请升级授权”，请在帮助 > License检查授权。不要通过直接修改本地数据库绕过授权或审批。

4. 创建隧道

4.1 快速新增

点击新建隧道后可快速填写：

• 类型：本地、远端或动态；
• 本地端口；
• 目标 host:port，例如 10.0.0.25:5432 或 db.internal:5432，Dynamic 不需要；
• 备注，用于生成易识别的配置标识。

快速新增默认把本地监听地址设为 127.0.0.1，保存后会立即尝试启动。Local 和 Remote 的目标支持 host:port，IPv6 可写为 [address]:port。

Remote 隧道的两端语义与 Local 相反，第一次配置 Remote 时建议保存后再进入完整编辑器核对全部字段。

4.2 完整编辑器

选中一条配置并点击编辑隧道，可设置：

选择“SSH 会话端点”会把远端主机和端口填为该会话端点。随后手动修改远端主机或端口时，配置不再与所选端点匹配。若 SSH 传输端点与实际转发目标不同，先打开正确的 SSH 会话，让隧道使用当前连接上下文，再填写真实转发目标。

4.3 区分四类地址

配置隧道时至少要区分以下地址角色：

快速新增的目标是一个合并的 host:port 输入；完整编辑器中的本地主机、本地端口、远端主机和远端端口必须分栏填写。不要把 SSH 登录入口误填成数据库目标，也不要把 10.0.0.25:5432 整体填入完整编辑器的主机字段。

5. Local 本地转发

5.1 数据流

Mac 应用 -> 本地监听地址:端口 -> SSH 连接 -> 内网目标:端口

例如，通过 SSH 入口 ops@192.168.1.20:22 访问只能从该 SSH 主机到达的 PostgreSQL 10.0.0.25:5432：

启动后，本机数据库客户端连接 127.0.0.1:15432。如果内网通过 DNS 管理数据库，也可把远端主机改为 db.internal，端口仍单独填写 5432。数据库看到的连接来源通常是 SSH 主机侧，而不是当前 Mac 的公网地址。

5.2 验证

在 Mac 本地终端进行只读检查：

lsof -nP -iTCP:15432 -sTCP:LISTEN
nc -vz 127.0.0.1 15432

端口可连接只证明 TCP 链路建立，不证明数据库账号、TLS 或业务查询正常。应再使用目标协议执行最小健康检查。

6. Remote 远端转发

6.1 数据流

远端客户端 -> SSH 服务器监听地址:端口 -> SSH 连接 -> Mac 侧目标:端口

例如，把 Mac 上 127.0.0.1:3000 的开发服务提供给 SSH 服务器本机的 127.0.0.1:19000：

在 SSH 服务器上可使用只读命令核对：

ss -lnt | grep ':19000'
curl --fail --max-time 5 http://127.0.0.1:19000/health

不要默认把 Remote 监听设为 0.0.0.0 或 ::。是否允许非回环监听还取决于 SSH 服务端的 GatewayPorts 等策略；对外暴露前必须确认认证、TLS、防火墙、访问范围和关闭时间。

7. Dynamic 动态转发

7.1 数据流

SOCKS5 客户端 -> Mac SOCKS5 监听地址:端口 -> SSH 连接 -> 客户端指定目标

推荐配置：

在支持 SOCKS5 的客户端中配置 127.0.0.1:1080。验证 HTTP 目标时可使用：

curl --socks5-hostname 127.0.0.1:1080 --fail --max-time 10 http://service.internal/health

--socks5-hostname让域名通过 SOCKS 侧解析，适合只有内网 DNS 能解析的主机；直接访问 IP 时不需要域名解析。代理不等于内容加密：从 SSH 出口到目标服务的链路仍取决于目标协议是否使用 TLS。

8. SSH 会话上下文

隧道启动时按以下顺序取得 SSH 上下文：

1. 当前工作区中可用的 SSH 连接上下文；
2. 隧道记录绑定的已保存 SSH/SFTP/SCP 会话；
3. 若两者都不可用，返回“需要先打开一个 SSH 或 SCP 会话”。

绑定会话被删除、改为不支持的协议、端口无效或凭据缺失时，编辑隧道并重新选择会话。经 ProxyJump 打开的 SSH 上下文可把相同跳板配置用于隧道运行时，但目标和跳板主机仍分别执行主机密钥与认证流程。

9. 启动、监控与停止

9.1 启动

1. 选中配置并再次核对类型和两端地址。
2. 点击该行的启动按钮。
3. 等待状态从“启动中”变为“运行中”。
4. 使用本地或远端客户端完成专项验证。

Local 和 Dynamic 启动时会检查本地端口是否可用。Remote 的监听发生在 SSH 服务器上，本地端口检查规则不同。

9.2 运行状态

面板以不同状态颜色和文本显示：

• 运行中；
• 连接中或重连中；
• 已停止；
• 失败。

运行中的隧道每秒轮询一次状态，并显示累计流量：

↑ 上传字节  ↓ 下载字节

流量只说明有字节经过，不代表请求成功、响应正确或业务事务完成。

9.3 复制等价 SSH 命令

右键隧道可选择复制SSH 隧道命令，得到对应的 ssh -L、ssh -R 或 ssh -D 形式。该操作只复制文本，不会执行命令；未绑定会话时目标可能显示为占位的 user@host，使用前必须补全并检查。

9.4 停止与退出

• 点击行内停止按钮会关闭隧道并取消后续自动重连；
• 删除运行中的配置前，Stacio 会先尝试停止运行时；
• 退出 Stacio 会停止所有运行中隧道，并在退出前显示确认；
• 保存配置不会让隧道在应用下次启动时自动运行。

10. 自动重连

隧道运行时发现链路断开后，会按递增延迟尝试重新建立，当前最多自动重连 10 次。界面显示“重连中…（第 N 次）”。

• 手动停止会取消待执行的重连；
• 超过次数后状态变为失败；
• 重新认证、主机密钥变化、配置错误或服务端拒绝转发不会因为重试而自动修复；
• 反复重连时应主动停止，避免持续请求和模糊故障时间线。

重连恢复的是隧道连接，不保证经过隧道的数据库事务、HTTP 请求、文件传输或长连接可以从断点继续。

11. 监听安全

11.1 默认使用回环地址

Local 和 Dynamic 推荐使用：

127.0.0.1

这只允许当前 Mac 本机连接。使用 0.0.0.0、:: 或局域网网卡地址会把服务或 SOCKS5 代理暴露给其他设备。动态隧道编辑器会对非 127.0.0.1 监听显示风险提示。

11.2 最小暴露原则

• 只开放完成任务所需的端口；
• 优先使用回环监听和短生命周期；
• 不通过无认证的 Remote 隧道公开管理后台；
• 在客户端和目标服务上继续使用认证和 TLS；
• 完成工作后停止隧道并验证监听已消失；
• 记录负责人、用途、目标和计划关闭时间。

11.3 凭据与日志

隧道使用 Stacio 当前或保存会话的认证信息。复制的 SSH 命令、诊断和截图不应包含密码、Token、私钥内容或私钥口令。主机密钥变化必须停止并独立核验。

12. 排障 Runbook

12.1 无法启动

按顺序检查：

1. License 是否有效；
2. 类型和端口是否正确，端口范围是否为 1...65535；
3. 是否有当前 SSH 上下文或有效的绑定会话；
4. SSH 认证和主机密钥是否正常；
5. Local/Dynamic 本地端口是否被占用；
6. SSH 服务端是否允许 TCP forwarding；
7. 目标服务是否监听且路由可达。

12.2 本地端口被占用

lsof -nP -iTCP:<端口> -sTCP:LISTEN

确认进程责任人后再决定停止进程或改用其他端口。不要为了启动隧道直接终止未知进程。

12.3 Local 已运行但目标不可用

• 先检查本地监听；
• 再从 SSH 终端检查目标名称解析和端口；
• 区分 TCP 可达、TLS 握手、应用认证和业务错误；
• 检查目标是否只监听错误的网卡地址。

12.4 Remote 无监听

• 检查 SSH 服务端是否允许 Remote forwarding；
• 检查远端端口是否冲突；
• 使用 ss -lnt 核对监听；
• 非回环监听还需检查 GatewayPorts 和防火墙；
• 检查 Mac 侧目标服务是否仍在运行。

12.5 Dynamic 客户端失败

• 确认客户端使用 SOCKS5 而不是 HTTP 代理；
• 内网域名使用代理侧 DNS 解析；
• 检查客户端是否错误绕过代理；
• 分别测试 IP 目标和域名目标；
• 检查目标协议本身的 TLS 和认证错误。

12.6 反复自动重连

1. 手动停止隧道。
2. 记录首次断开时间和错误详情。
3. 检查网络、VPN、SSH 会话、凭据和主机密钥。
4. 验证两端服务仍在监听。
5. 修复根因后手动启动一次并持续观察。

13. 完成与关闭清单

• 客户端通过隧道完成了专项健康检查；
• 目标不是错误的主机、端口或环境；
• 未暴露不必要的监听地址；
• 流量和应用日志与测试时间一致；
• 使用结束后已停止隧道；
• 本地或远端监听已消失；
• 必要的审计、变更记录和残余风险已保存。

涉及生产访问时，同时遵循安全与治理和远程运维。