使用端口转发

端口转发（Port Forwarding）通过 SSH 隧道将本地或远端端口映射到对端主机，用于在不暴露公网端口的前提下，安全访问数据库、内网 Web 服务等。OrcaTerm 桌面客户端内置 SSH 端口转发能力，支持本地、远程、动态三种模式，并可在本机直接建立隧道。

OrcaTerm 端口转发

Note

端口转发仅桌面客户端可用，Web 端因浏览器沙箱限制无法建立本机 SSH 隧道。

三种转发模式

模式对应 SSH 选项方向适用场景
本地转发ssh -L本地监听 → SSH 服务端 → 远端目标访问服务器内网中的数据库、Web 服务
远程转发ssh -RSSH 服务端监听 → 本地目标将本地服务暴露给远端服务器访问
动态转发ssh -D本地 SOCKS5 代理浏览器 / 应用通过代理访问整个内网

Important

所有模式均要求显式指定本地监听端口，不支持 0（自动分配端口）。Rust 端会强制校验端口合法性。

本地转发（Local，-L）

在本地开启监听端口，所有发往该端口的连接经 SSH 隧道转发到远端服务器可达的目标主机:端口。

本地主机              SSH 服务端          远端目标
[本地监听 :localPort]  ──隧道──▶  [解析]  ──▶  [remoteHost:remotePort]
  • 本地监听地址：默认 127.0.0.1，仅本机可访问；改为 0.0.0.0 可让同网段其他设备访问（注意安全）。
  • 本地监听端口：本机要监听的端口，如 3306。
  • 远端目标主机：由 SSH 服务端解析，可以是服务端能访问的任意主机（含内网地址）。
  • 远端目标端口：目标服务的端口，如 3306（MySQL）。

示例：把远程服务器内网 10.0.0.5:3306 的 MySQL 映射到本机 3306，然后用本地客户端连接 127.0.0.1:3306 即可。

远程转发（Remote，-R）

请求 SSH 服务端在远端开启监听端口，所有发往该端口的连接经隧道反向转发到本地主机。

远端服务端监听            本地目标
[remoteHost:remotePort]  ──隧道──▶  [localHost:localPort]
  • 远端监听地址：可选，受服务器 GatewayPorts 配置约束。默认仅服务端本机访问，需外部访问需服务端开启 GatewayPorts yes。
  • 远端监听端口：服务端要监听的端口。
  • 本地目标主机：本机或本机能访问的主机。
  • 本地目标端口：本地服务的端口。

示例：把本地 3000 端口开发的 Web 服务通过远端服务器 8080 暴露，供远端服务器内网其他机器访问。

动态转发（Dynamic，-D）

在本地开启 SOCKS5 代理端口，浏览器或应用通过该代理发起的每条连接都会经 SSH 隧道转发到对端。

本地 SOCKS5 监听          SSH 服务端          任意目标
[localHost:localPort]  ──隧道──▶  [direct-tcpip]  ──▶  [每条连接的目标]
  • 本地监听地址：默认 127.0.0.1。
  • 本地监听端口：本地 SOCKS5 端口，如 1080。
  • 无目标端：动态转发在每次连接时由应用协商目标，无需预先指定 remoteHost / remotePort。

示例：本地开启 127.0.0.1:1080 SOCKS5 代理，浏览器设置使用该代理后即可通过远端服务器访问整个内网。

前置要求

  • 已安装 OrcaTerm 桌面客户端。
  • 已创建 SSH 协议的连接配置（不支持 TAT / RDP）。
  • 连接配置需使用 密码 / 密钥 / 凭据托管 三种验证方式之一。

Note

交互式验证（Keyboard-Interactive）登录的连接配置也可用于端口转发，启动转发时会弹出鉴权交互窗口，需在窗口中输入响应。

自启动（应用启动时自动拉起）仅支持密码、密钥、凭据托管三种凭据化验证方式，不支持交互式验证——因为自启动时无人值守，无法响应键盘交互弹窗。

进入端口转发页面

在桌面客户端左侧边栏选择 端口转发，进入转发任务列表页面。列表按表格展示所有已创建的转发任务：

列说明
名称用户自定义的转发名称，用于识别该任务。
连接关联的 SSH 连接配置（含用户名@主机:端口）。
模式Local / Remote / Dynamic。
监听本地或远端监听地址与端口。
目标转发目标地址与端口（Dynamic 模式为空）。
状态运行中 / 已停止 / 启动中 / 错误（含错误信息）。
自启动是否在应用启动时自动拉起。
操作启动 / 停止 / 编辑 / 复制 / 删除。

新建转发任务

  1. 在端口转发页面点击 新建转发。

  2. 选择转发模式（Local / Remote / Dynamic）。

  3. 选择关联的 SSH 连接配置。

  4. 填写监听端与目标端字段（Dynamic 模式无目标端）：

    字段说明
    转发名称自定义标识，便于在列表中识别。
    本地监听地址默认 127.0.0.1，可改为 0.0.0.0。
    本地监听端口1-65535，不可为 0，不可与本机占用端口冲突。
    远端目标主机Local 模式必填，由 SSH 服务端解析。
    远端目标端口Local 模式必填。
    自启动应用启动时是否自动拉起该转发（仅凭据登录支持）。
    保存后立即启动默认开启，保存后立即建立 SSH 隧道。

  5. 点击 保存，任务即创建到列表；若勾选了立即启动，会自动建立隧道。

Important

单用户最多创建 50 条转发任务，超出会提示「端口转发数量已达上限（50 个），请先删除不再使用的转发」。创建时本地端口若被本机其他进程占用，启动会失败并提示「Address already in use」。

启动与停止

  • 启动：点击列表中的 启动 按钮，OrcaTerm 会通过本机 Tauri SSH 建立 ssh_connect → ssh_forward 隧道，状态变为「启动中」再「运行中」。
  • 停止：点击 停止 按钮，调用 ssh_forward_close 关闭隧道并释放本地端口。
  • 状态实时同步：列表状态由运行时状态层订阅推送，启动中 / 运行中 / 已停止 / 错误会实时刷新，无需手动刷新页面。

Note

同一任务在启动中（connecting）时无法重复启动，按钮会临时禁用并提示「该端口转发正在启动中，请稍候」，避免本地端口 bind 冲突。但不同任务可并发启动，互不影响。

编辑与复制

  • 编辑：点击 编辑 修改转发名称、模式、监听 / 目标字段、自启动开关。修改保存后立即生效，但运行中的隧道不会自动重连，需手动停止后重新启动以应用新配置。
  • 复制：点击 复制 将现有任务配置填入新建表单，便于基于一条转发快速创建另一条相似转发。复制不会改动原任务。

自启动

开启 自启动 后，桌面客户端启动时会自动拉起该转发任务：

  • 仅支持密码 / 密钥 / 凭据托管三种凭据化验证方式的连接，不支持交互式验证（无人值守无法响应弹窗）。
  • 应用启动时按列表顺序串行拉起，每条转发单独建立 SSH 连接。
  • 启动过程中状态显示为「启动中」，成功后变为「运行中」。
  • 启动失败的转发状态会标记为「错误」，不影响其他转发的启动。

Tip

关闭窗口（最小化到托盘）不会停止转发；仅当 退出 应用时才会清理所有活跃隧道并同步状态为「已停止」。下次启动时自启动会重新拉起。

主机密钥与鉴权交互

启动转发时建立 SSH 连接，可能触发以下交互：

主机密钥确认

  • 首次连接：弹出确认框显示服务器 Host Key 类型和指纹，确认后可永久信任（写入 known_hosts）或仅本次信任。
  • 指纹变更：提示「检测到服务器主机密钥变更」，请通过可信渠道核对后再决定是否继续，避免中间人攻击风险。

键盘交互鉴权

  • 连接配置使用交互式验证时，启动转发会弹出键盘交互窗口。
  • 按提示填写响应（密码字段默认不回显），提交后由服务端校验。
  • 可点击 取消 终止鉴权，转发任务标记为已停止。

Note

服务端发送 0 个 prompt 的 InfoRequest 时，客户端会自动回空响应继续，不会弹窗。

应用退出时的清理

退出桌面客户端时，OrcaTerm 会：

  1. 串行关闭所有活跃隧道（手动启动 + 自启动）。
  2. 调用 ssh_forward_close 释放本地端口。
  3. 同步数据库状态为「已停止」。
  4. 完成清理后退出进程。

下次启动时，标记为自启动的转发会重新拉起；非自启动的转发保持「已停止」状态，需手动启动。

Important

仅 退出 应用时清理隧道；最小化 / 隐藏窗口 不会停止转发，隧道持续保持连接。若端口转发页面未打开（hook 未挂载），退出时的清理 hook 不会注册，此时依赖进程退出释放端口 + Rust 端 SO_REUSEADDR 兜底。

常见问题

启动失败提示「Address already in use」

本地监听端口已被本机其他进程（或上一个未正常关闭的转发）占用。解决方法：

  • 检查本机是否有其他程序占用该端口（如本地 MySQL 占用 3306）。
  • 换一个未被占用的本地端口。
  • 重启桌面客户端，残留的监听会在启动时被清理。

启动后立即变为「错误」状态

可能原因：

  • 服务器地址 / 端口不通，或 SSH 服务未运行。
  • 凭据错误或已失效（密码改过、密钥被撤销）。
  • 远端目标主机在 SSH 服务端不可达（Local 模式）。
  • 远端监听端口被服务器其他进程占用，或服务端未开启 GatewayPorts（Remote 模式）。

鼠标悬停错误状态可查看具体错误信息。

自启动的转发没有自动拉起

  • 确认连接配置使用的是密码 / 密钥 / 凭据托管验证方式（交互式验证不支持自启动）。
  • 检查网络是否正常，自启动时网络异常会标记为错误，网络恢复后可手动启动。
  • 查看是否已达到 50 条上限。

关闭窗口后转发是否断开

不会。关闭窗口默认最小化到系统托盘，隧道保持连接。仅 退出 应用时才会断开所有隧道。

上一篇使用随手记下一篇会话协作