GitHub 仓库：https://github.com/xuanlove/SSHTunnel
技术栈：Wails v2 + Go 1.25 + Vue 3 + Element Plus

SSHTunnel 是一款跨平台的 SSH 隧道管理工具，支持多跳跳板链、多协议代理（HTTP / HTTPS / SOCKS4 / SOCKS5）、本地端口转发、自动重连与实时日志推送，并提供桌面端与 WEB 面板双形态管理界面，一份代码产出两种二进制。

📑 文章目录

• 核心功能
• 隧道能力
• 代理协议细节
• 管理界面
• 双形态设计
• 安装方式
• 一键安装脚本（Linux）
• systemd 服务部署
• 从源码构建
• 预编译二进制下载
• 使用方法
• 运行模式
• 桌面模式
• WEB 模式
• 启用 HTTPS
• 混合模式
• 命令行参数
• 配置说明
• 配置文件位置
• 配置结构示例
• 跳板链简写格式
• WEB API 接口
• 技术栈
• 项目结构
• 版本更新记录
• 安全建议
• 总结

核心功能

隧道能力

• 多跳跳板链：支持任意层级的 SSH 跳板，逐跳串联建立 SSH 连接
• 本地端口转发：经典 SSH -L 本地转发，支持多个转发规则
• 多协议代理：单条隧道可同时监听 HTTP / HTTPS / SOCKS4 / SOCKS5 多端口
• 认证方式：密码认证 / 密钥认证（密钥以 PEM 文本形式存储，便于跨设备同步）
• 自动重连：SSH 断开后指数退避重连（初始 2s，上限 60s，可配置无限重试）
• 端口冲突检测：监听启动前自动检测端口占用

代理协议细节

协议	认证	说明
HTTP	Basic Auth（可选）	支持 CONNECT 方法代理 HTTPS 流量
HTTPS	Basic Auth（可选）	需提供 TLS 证书（可一键生成自签证书）
SOCKS4	UserID（可选）	兼容 SOCKS4a（域名直连）
SOCKS5	用户名/密码（可选）	实现 RFC 1928 / RFC 1929

管理界面

• 桌面端：Wails + WebView 原生应用（Windows / Linux / macOS）
• WEB 面板：内置 HTTP/HTTPS 服务器，浏览器即可管理（可选密码访问）
• 实时推送：日志与隧道状态变更通过 WebSocket 实时推送
• JWT 鉴权：WEB 模式下可选启用密码访问，Token 有效期 24 小时
• TLS 支持：WEB 面板与 HTTPS 代理均可使用 TLS

双形态设计

同一份代码，两种二进制：

变体	资产命名	说明
web（默认）	sshtunnel-{os}-{arch}[.exe]	纯 WEB 模式，CGO 禁用，可纯 Go 交叉编译，适合服务器
desktop	sshtunnel-{os}-{arch}-desktop[.exe]	含 Wails WebView，CGO 启用，原生 GUI 窗口

安装方式

一键安装脚本（Linux）

# 安装最新版
curl -fsSL https://raw.githubusercontent.com/xuanlove/SSHTunnel/main/scripts/install.sh | sudo bash

# 安装指定版本
sudo bash scripts/install.sh -v v1.1.0

# 升级模式（保留现有配置，仅替换二进制）
sudo bash scripts/install.sh -u

# 安装并注册为 systemd 服务（交互式配置端口/密码）
sudo bash scripts/install.sh -s

脚本选项：

选项	说明
-r, --repo owner/repo	GitHub 仓库（默认 xuanlove/SSHTunnel）
-v, --version VERSION	安装指定版本（如 v1.1.0）
-d, --dir PATH	安装目录（默认 /usr/local/bin）
-s, --service	安装为 systemd 服务（交互式配置端口/密码）
-u, --upgrade	升级模式：保留配置，仅替换二进制
-h, --help	显示帮助

systemd 服务部署

# 交互式菜单
sudo ./install.sh

# 直接安装并启动
sudo ./install.sh install

# 卸载
sudo ./install.sh uninstall

# 查看状态 / 重启 / 日志
sudo ./install.sh status | restart | logs

脚本特性：

• 创建专用系统用户 SSHTunnel（nologin，无家目录）
• 创建独立目录：/etc/SSHTunnel（配置）、/var/lib/SSHTunnel（数据）、/var/log/SSHTunnel（日志）
• systemd unit 含安全加固：ProtectSystem=strict、PrivateTmp=true、NoNewPrivileges=true、LimitNOFILE=65536
• 支持非交互模式：sudo -E LISTEN_PORT=8090 AUTH_USER=admin AUTH_PASS=xxx ./install.sh install
• 端口占用检测（ss → netstat → /proc/net/tcp 三级回退）

从源码构建

依赖要求：

• Go 1.25+
• Node.js 18+ 与 npm（构建前端）
• 桌面模式额外依赖：
• Windows：无
• Linux：libwebkit2gtk-4.1-dev、libgtk-3-dev
• macOS：Xcode Command Line Tools

# 克隆项目
git clone https://github.com/xuanlove/SSHTunnel.git
cd SSHTunnel

# 构建前端
cd frontend && npm install && npm run build && cd ..

# 构建当前平台桌面端（CGO 启用）
go build -o build/bin/sshtunnel .

# 仅构建 WEB 模式二进制（CGO 禁用，可交叉编译）
CGO_ENABLED=0 go build -o build/bin/sshtunnel-web .

预编译二进制下载

前往 Releases 页面 下载：

文件	平台	变体
sshtunnel-linux-amd64	Linux x86_64	web
sshtunnel-linux-arm64	Linux arm64	web
sshtunnel-darwin-amd64	macOS Intel	web
sshtunnel-darwin-arm64	macOS Apple Silicon	web
sshtunnel-windows-amd64.exe	Windows x86_64	web（控制台）
sshtunnel-windows-amd64-desktop.exe	Windows x86_64	desktop（GUI）

注意：macOS 桌面版需在 macOS 上原生构建或借助 osxcross 交叉编译，Release 暂不提供预编译包。

使用方法

运行模式

模式	说明
desktop	默认。仅启动桌面端应用（原生 GUI 窗口）
web	仅启动 WEB 面板（无 GUI 依赖，适合服务器部署）
both	同时启动桌面端与 WEB 面板

桌面模式

./sshtunnel
# 或显式指定
./sshtunnel --mode=desktop

启动后弹出原生窗口，左侧导航包含：仪表盘、配置编辑、日志、设置。

WEB 模式

# 无密码
./sshtunnel --mode=web --web-port=8090
# 监听所有网卡
./sshtunnel --mode=web --web-host=0.0.0.0 --web-port=8090

# 密码保护（JWT Token 24 小时有效）
./sshtunnel --mode=web --web-port=8090 --auth=admin:yourpassword

浏览器访问 http://127.0.0.1:8090 进入管理面板，密码模式下首次访问跳转至登录页。

启用 HTTPS

./sshtunnel --mode=web --web-port=8443 \
  --tls-cert=/path/to/cert.pem \
  --tls-key=/path/to/key.pem \
  --auth=admin:password

混合模式

./sshtunnel --mode=both --web-port=8090 --auth=admin:password

同时启动桌面端窗口与 WEB 面板，两端的日志与状态变更实时同步。

命令行参数

参数	默认值	说明
--mode	desktop	运行模式：desktop / web / both
--web-host	127.0.0.1	WEB 监听地址
--web-port	8080	WEB 监听端口
--auth	空	启用密码访问，格式 user:password，留空则无密码
--tls-cert	空	TLS 证书路径（启用 HTTPS）
--tls-key	空	TLS 私钥路径（启用 HTTPS）
--version	–	打印版本信息并退出
--check-update	–	检查 GitHub Release 是否有新版本并退出
--repo	xuanlove/SSHTunnel	GitHub 仓库（owner/repo），用于版本检查

版本检查退出码：0 已是最新版本；1 发现新版本；2 检查失败（网络/API 错误）。

配置说明

配置文件位置

• Windows：%APPDATA%\sshtunnel\configs.json
• Linux：~/.config/sshtunnel/configs.json
• macOS：~/Library/Application Support/sshtunnel/configs.json

配置结构示例

[
  {
    "id": "uuid-自动生成",
    "name": "我的隧道",
    "tunnel_type": "proxy",
    "hop_chain": [
      {
        "user": "root",
        "host": "bastion.example.com",
        "port": 22,
        "auth_type": "password",
        "password": "secret",
        "key_content": "-----BEGIN...",
        "passphrase": "key-passphrase"
      }
    ],
    "local_forwards": [
      {
        "local_port": 8080,
        "remote_host": "127.0.0.1",
        "remote_port": 80,
        "allow_external": false
      }
    ],
    "proxy_listeners": [
      {
        "protocol": "socks5",
        "listen_port": 1080,
        "allow_external": true,
        "auth": {
          "username": "proxyuser",
          "password": "proxypass"
        },
        "tls": {
          "cert_file": "/path/to/cert.pem",
          "key_file": "/path/to/key.pem"
        }
      }
    ],
    "auto_reconnect": true,
    "status": "stopped"
  }
]

字段说明：

字段	类型	说明
id	string	UUID，新建时自动生成
name	string	隧道名称
tunnel_type	string	local_forward（本地端口转发）或 proxy（代理服务）
hop_chain	array	SSH 跳板链，逐跳串联
local_forwards	array	本地转发规则（仅 local_forward 类型）
proxy_listeners	array	代理监听器（仅 proxy 类型）
auto_reconnect	bool	是否启用自动重连
status	string	运行时状态，不持久化（stopped / starting / running / error）

跳板链简写格式

支持使用 , 或 -> 分隔多跳：

user1@host1:22 -> user2@host2:2222 -> user3@host3

每跳格式：[user@]host[:port]，省略 port 时默认 22。

WEB API 接口

公开端点：

方法	路径	说明
GET	/api/auth/status	查询鉴权状态（是否启用密码、TLS）
POST	/api/login	登录（仅密码模式注册）

受保护端点（需 Authorization: Bearer ）：

方法	路径	说明
GET	/api/configs	列出所有配置
POST	/api/configs	新建配置
PUT	/api/configs/{id}	更新配置
DELETE	/api/configs/{id}	删除配置
POST	/api/configs/{id}/start	启动隧道
POST	/api/configs/{id}/stop	停止隧道
POST	/api/tunnels/start-all	批量启动
POST	/api/tunnels/stop-all	批量停止
GET	/api/tunnels/status	查询所有隧道状态
GET	/api/logs?limit=N	获取最近 N 条日志
POST	/api/port/check	检测端口可用性
POST	/api/cert/generate	生成 HTTPS 自签证书
POST	/api/hopchain/parse	解析跳板链简写
POST	/api/tunnel/test	测试隧道连通性（不启动监听）
GET	/api/version	查询当前版本信息
GET	/api/version/check	检查 GitHub Release 新版本

WebSocket 端点（密码模式下通过 ?token= 鉴权）：

路径	说明
/api/logs/stream	日志实时流（消息 type: "log"）
/api/tunnels/status/stream	隧道状态实时流（消息 type: "status"）

统一响应格式：

{
  "code": 0,
  "message": "success",
  "data": { }
}

code=0 表示成功，非 0 为业务错误码；HTTP 状态码与业务码类别对应（code >= 40000 → 4xx，code >= 50000 → 5xx）。

技术栈

层级	技术	版本
后端语言	Go	1.25+
SSH 协议	golang.org/x/crypto/ssh	v0.53.0
桌面框架	Wails	v2.12.0
前端框架	Vue 3	3.5
UI 组件库	Element Plus	2.14
状态管理	Pinia	2.3
路由	Vue Router	4.6
构建工具	Vite	6
类型检查	TypeScript + vue-tsc	5.7 / 2.2
实时通信	github.com/coder/websocket	v1.8.15
鉴权	github.com/golang-jwt/jwt/v5	v5.3.1
唯一标识	github.com/google/uuid	v1.6.0

项目结构

SSHTunnel/
├── main.go                      # 程序入口、CLI 参数解析、运行模式分发
├── app.go                       # Wails 桌面端绑定层（App 方法）
├── ssh_helper.go                # SSH 辅助函数
├── go.mod / go.sum              # Go 模块定义
├── wails.json                   # Wails 构建配置
├── install.sh                   # 根目录 systemd 服务安装脚本（生产部署）
├── README.md / LICENSE
├── build/                       # Wails 打包资源
├── internal/                    # 业务逻辑层（8 个包）
│   ├── config/                  # 配置管理（持久化、CRUD）
│   ├── logger/                  # 日志（环形缓冲 + 多订阅者 sink）
│   ├── port/                    # 端口检测
│   ├── proxy/                   # 代理协议实现（HTTP/HTTPS/SOCKS4/SOCKS5）
│   ├── sshclient/               # SSH 客户端与跳板链解析
│   ├── tunnel/                  # 隧道管理（启停、自动重连、状态回调）
│   ├── updater/                 # GitHub Release 版本检测
│   └── web/                     # WEB 服务器、API、WebSocket、JWT 鉴权
├── frontend/                    # Vue 3 + Element Plus 前端
│   ├── src/
│   │   ├── api/                 # 双模式 API 适配层（Wails Call / HTTP fetch）
│   │   ├── components/          # HopEditor、ProxyListenerEditor
│   │   ├── router/              # 路由守卫（WEB 模式登录拦截）
│   │   ├── stores/              # Pinia 状态管理
│   │   ├── views/               # Dashboard / ConfigEdit / Logs / Login / Settings
│   │   └── types.ts             # 与 Go 结构体一一对应的 TS 类型
│   ├── wailsjs/                 # Wails 自动生成的 JS 绑定
│   └── dist/                    # 构建产物（go:embed 嵌入到二进制）
├── scripts/
│   └── install.sh               # GitHub Release 下载安装脚本
└── releases/                    # 预编译二进制（提交到仓库）

版本更新记录

v1.1.0

• 项目重命名：统一命名为 SSHTunnel（Go 模块 sshsuidao → sshtunnel）
• 二进制资产、安装脚本、更新检测、User-Agent、Wails 标题、前端 TOKEN_KEY 全部统一
• 新增桌面版变体（buildVariant=desktop）
• /api/version 与 /api/version/check 返回 variant 字段
• 新增 CLI 参数：--version、--check-update、--repo

v1.0.0（初始发布）

• 多跳跳板链、多协议代理、本地端口转发
• 自动重连（指数退避）、端口冲突检测
• 桌面端与 WEB 面板双形态管理界面
• JWT 鉴权、TLS 支持、WebSocket 实时推送
• Linux systemd 安装脚本、GitHub Release 版本检测
• 全平台交叉编译（Linux/macOS/Windows × amd64/arm64）

安全建议

1. WEB 面板监听公网时务必启用 --auth：无密码模式监听 0.0.0.0 会让任何能访问本机端口的人控制隧道，启动时会在日志中输出安全警告
2. 生产环境推荐启用 HTTPS：使用 --tls-cert / --tls-key 防止 Token 被中间人窃取
3. SSH 密钥以 PEM 文本存储于配置文件：请妥善保护 configs.json，避免提交到版本控制系统
4. JWT 密钥每次启动随机生成：重启后所有已签发的 Token 失效，需重新登录
5. systemd 部署已内置安全加固：ProtectSystem=strict、PrivateTmp=true、NoNewPrivileges=true、专用 nologin 系统用户

总结

SSHTunnel 把「多跳跳板 + 多协议代理 + 本地转发」打包进一个单二进制：服务器上用纯 Go 的 WEB 模式跑无头服务，桌面端用 Wails 提供原生 GUI，前后端共享同一套 Vue 3 面板与 REST API。配合 systemd 安装脚本、自动重连与实时日志推送，非常适合作为个人或团队的内网穿透与代理基础设施。