tsshd: 基于 UDP 支持漫游的 SSH 服务器

MIT License GitHub Release GitHub tsshd 中文文档

tsshd 是一个基于 UDP 的 SSH 服务器，专为不稳定网络环境设计，支持在网络切换或 IP 变化时无缝漫游，并能在高延迟链路（如蜂窝网络和不稳定的 Wi-Fi）上稳定工作。

tsshd 旨在与 OpenSSH 完全兼容，并提供额外能力：

功能对比

tsshd 的灵感来源于 mosh，tsshd 类似于 mosh-server，而 tssh --udp 类似于 mosh。

Feature mosh ( mosh-server ) tssh ( tsshd )
超低延迟 ?? ✅ KCP
保持连接 ✅ ✅
切换网络 ✅ ✅
本地回显 & 行编辑 ✅ 无支持计划
支持多平台 / Windows mosh#293 ✅
SSH X11 转发 mosh#41 ✅
SSH Agent 转发 mosh#120 ✅
SSH 端口转发 mosh#337 ✅
输出上下滚动 mosh#122 ✅
OSC52 复制粘贴 mosh#637 ✅
ProxyJump mosh#970 ✅
tmux -CC 集成 mosh#1078 ✅

tssh 和 tsshd 的工作方式与 ssh 完全相同，没有计划支持本地回显和行编辑，也不会出现 mosh 的问题：mosh#1041、mosh#1281、mosh#1295 等。

如何使用

  1. 在客户端（本地电脑）上安装 tssh。

  2. 在服务端（远程机器）上安装 tsshd。

  3. 使用 tssh --udp xxx 登录服务器，用法与标准 SSH 保持一致。

    • 对延迟敏感的用户可以指定 --kcp 选项。
    • 可在 ~/.ssh/config 中进行如下配置，以省略手动指定 --udp 或 --kcp 选项：
      Host xxx
    #!! UdpMode  ( Yes | QUIC | KCP )

原理简介

安装方法

支持终端

以下客户端或终端支持 tsshd 服务端：

重连架构

┌───────────────────────┐                ┌───────────────────────┐
│                       │                │                       │
│    tssh (process)     │                │    tsshd (process)    │
│                       │                │                       │
│ ┌───────────────────┐ │                │ ┌───────────────────┐ │
│ │                   │ │                │ │                   │ │
│ │  KCP/QUIC Client  │ │                │ │  KCP/QUIC Server  │ │
│ │                   │ │                │ │                   │ │
│ └───────┬───▲───────┘ │                │ └───────┬───▲───────┘ │
│         │   │         │                │         │   │         │
│         │   │         │                │         │   │         │
│ ┌───────▼───┴───────┐ │                │ ┌───────▼───┴───────┐ │
│ │                   ├─┼────────────────┼─►                   │ │
│ │   Client  Proxy   │ │                │ │   Server  Proxy   │ │
│ │                   ◄─┼────────────────┼─┤                   │ │
│ └───────────────────┘ │                │ └───────────────────┘ │
└───────────────────────┘                └───────────────────────┘

安全模型

配置说明

Server 配置 (tsshd)

Client 配置 (tssh)

Host xxx
    #!! UdpMode Yes
    #!! TsshdPort 61001-61999
    #!! TsshdPath ~/go/bin/tsshd
    #!! UdpAliveTimeout 86400
    #!! UdpHeartbeatTimeout 3
    #!! UdpReconnectTimeout 15
    #!! ShowNotificationOnTop yes
    #!! ShowFullNotifications yes
    #!! UdpProxyMode UDP
    #!! UdpMTU 1400

UDP 端口转发

使用 tssh 作为客户端时，支持 UDP 端口转发。

开发者指南：构建自定义 SSH 服务

tsshd 不仅仅是一个二进制程序，它还是一个强大的框架，允许你构建具有 无缝漫游 和 低延迟 能力的自定义 SSH 应用。

A. 快速开始：自定义业务逻辑

你可以通过 tsshd 提供的中间件机制，轻松地在 SSH 会话中注入自己的交互逻辑。

func main() {
    // 使用 tsshd.RunMain 作为入口，并注入自定义中间件
    code, err := tsshd.RunMain(
        tsshd.WithMiddleware(func(next tsshd.Handler) tsshd.Handler {
            return func(sess tsshd.Session) {
                term := term.NewTerminal(sess, "输入你的名字: ")
                name, _ := term.ReadLine()
                fmt.Fprintf(sess, "你好, %s！这是一个支持漫游的自定义 SSH 服务。\r\n", name)
            }
        }),
    )
    if err != nil {
        fmt.Fprintf(os.Stderr, "%v\n", err)
    }
    os.Exit(code)
}

运行原理：

  1. OpenSSH 引导：当客户端使用 tssh --udp 连接时，它首先通过标准 SSH 协议登录。
  2. 拉起进程：OpenSSH 会在服务端拉起你编写的这个二进制程序。
  3. 协议切换：该程序启动后监听随机 UDP 端口，并将密钥返回给客户端，随后客户端切换到 QUIC/KCP 协议与该程序直接通信。

注意：如果你的程序不在 PATH 中，请在客户端配置 TsshdPath 或使用 --tsshd-path 指定路径。

B. 高级进阶：使用 Wish 构建集成化服务器

如果你不想依赖系统自带的 OpenSSH 来拉起进程，或者想构建一个纯粹的、单文件的自定义 SSH 服务器，可以将 Wish（基于 gliderlabs/ssh）与 tsshd 结合。

这种模式下，你的程序可以同时扮演两个角色：

核心设计思路：适配器模式

为了让业务逻辑（如终端交互）在 Wish 和 tsshd 之间复用，你可以通过定义统一的 Session 接口来屏蔽底层差异：

// 统一 Session 接口，让业务逻辑在 Wish(TCP) 和 tsshd(UDP) 之间通用
type Session = tsshd.Session

func handleBusiness(sess Session) {
    fmt.Fprintf(sess, "当前会话类型: %T\r\n", sess)
    // 编写你的业务逻辑...
}

会话接管 (Process Handoff)

当 Wish 接收到客户端发出的启动 tsshd 指令时，你可以通过 exec.Command 重新执行当前的二进制文件（带上 tsshd 参数），实现从“标准 SSH 握手”到“UDP 低延迟传输”的无缝切换：

  1. 检测指令：在 Wish 中间件中捕获客户端执行 tsshd 的请求。
  2. 二次启动：在服务端本地启动一个子进程（当前程序的 tsshd 模式）。
  3. 环境继承：将当前的连接信息（如 SSH_CONNECTION）传递给子进程。

C. 为什么选择这种架构？

D. 示例代码 (Examples)

为了帮助您快速上手，我们在 examples/ 目录下提供了完整可运行的示例代码。您可以将这些示例作为构建自定义 SSH 服务的模板。

提示：您可以在本地运行这些示例，并使用 tssh 客户端进行测试，以亲身体验低延迟和漫游功能！

联系方式

有什么问题可以发邮件给作者 lonnywong@qq.com，也可以提 Issues 。欢迎加入 QQ 群：318578930。

赞助打赏

❤️ 赞助 trzsz ❤️，请作者喝杯咖啡 ☕ ? 谢谢您们的支持！