SSH-Tunnel 文档

简介

SSH-Tunnel 是一个基于SSH协议的隧道代理工具，可以在本地建立SOCKS5和HTTP代理，通过SSH隧道将流量安全地转发到远程服务器。这对于以下场景特别有用：

• 安全地浏览网络，防止本地网络监控
• 访问受地理位置限制的内容
• 绕过网络防火墙限制
• 保护网络通信安全

快速开始

最简单的使用方式是通过以下命令启动SSH隧道：

./ssh-tunnel -s xx.xx.xx.xx

其中 xx.xx.xx.xx 是您的SSH服务器地址。这将使用默认设置：

• 本地SOCKS5代理端口：1081
• SSH服务器端口：22
• 使用 ~/.ssh/id_rsa 作为私钥
• 用户名：root

命令选项

SSH-Tunnel 提供了丰富的命令行选项，以便根据您的需求进行自定义配置：

代理模式

SSH-Tunnel 支持多种代理模式，可以根据您的需求进行配置：

SOCKS5 代理

默认情况下，SSH-Tunnel 会在本地 1081 端口启动 SOCKS5 代理。可以通过以下参数进行配置：

./ssh-tunnel -s xx.xx.xx.xx -socks5.enable -l 0.0.0.0:1081

HTTP 代理

SSH-Tunnel 还支持 HTTP 代理模式，默认在本地 1082 端口，需要显式启用：

./ssh-tunnel -s xx.xx.xx.xx -http.enable -http.local.address 127.0.0.1:1082

HTTP Basic 认证

您可以为 HTTP 代理启用基本认证，提高安全性：

./ssh-tunnel -s xx.xx.xx.xx -http.enable -http.basic.enable -http.basic.username admin -http.basic.password password

HTTP Over SSH

启用 HTTP Over SSH 功能，可以将 HTTP 请求通过 SSH 隧道转发：

./ssh-tunnel -s xx.xx.xx.xx -http.enable -http.over.ssh.enable

管理界面

SSH-Tunnel 提供了一个内置的管理界面，方便您监控连接状态、查看日志和配置信息：

./ssh-tunnel -s xx.xx.xx.xx -admin.enable -admin.address 127.0.0.1:1083

启用后，浏览器访问 http://localhost:1083/view/index 打开管理界面。

主要功能

• SSH 状态：显示 SSH 连接状态、延迟、持久化总体/Profile/直连流量和历史图表
• 连接池管理：实时查看连接池成员（健康/可疑/探测中/已摘除），支持手动探测、手动摘除指定成员、一键清理已摘除历史
• 多 Profile 管理：维护多套 SSH 配置，支持动态切换与持久化写入 profiles.json
• 节点质量：展示最近 24 小时真实访问成功率、平均/P95 建连延迟、连续失败，并支持 SSH 握手与出口手测
• 独立路由：在 /view/routes 管理域名、IP 通配符和 CIDR 规则，支持固定或随机多 Profile 出口
• 日志查看：默认加载最近 1000 行历史并继续实时追踪；支持一键清空日志
• 域名列表：响应式域名过滤列表，支持增删改查
• 应用配置：在线修改配置参数，保存后即时生效
• 服务控制：支持重启服务以应用新配置
• 版本管理：检查 GitHub Release 新版本，支持一键更新（含 SHA256 校验）
• 进程信息：显示当前程序执行路径与工作目录

管理界面预览

多 Profile 管理 v1.4.18+

Multi-Profile 功能允许维护多套 SSH 服务器、账号、私钥和连接池配置。在管理界面 /view/index 的 Profile 卡片中可新增、编辑、复制、删除和切换 Profile。

从 v1.5.0 开始，路由不再作为 Profile 的内嵌字段编辑。被任何规则组默认出口或单规则独立出口引用的 Profile 不能删除，需先调整或删除引用。

Profile 节点质量 v1.7.0+

应用配置页的 Profile 表格会根据最近 24 小时真实代理访问，展示 testing、reachable、degraded、unreachable、unknown 五种状态，以及成功率、成功/失败数、连续失败、平均和近似 P95 建连延迟、最近目标与错误。

三种延迟不可混用

• 访问建连延迟：代理请求通过某个 Profile 建立目标 TCP 连接的耗时；平均和 P95 只统计成功访问。
• SSH 握手延迟：手动测试建立一次性 SSH 连接的耗时。
• 出口探测延迟：通过该一次性 SSH 连接访问 ssh.probe.urls、兼容地址或默认探测地址的耗时。

它们都不是纯网络 RTT。HTTP、HTTPS、SOCKS5 和随机路由故障转移会在同一真实建连边界记录，每个候选 Profile 分别统计；直连流量不计入。

排序与筛选 v1.7.1+

Profile 列表默认按综合质量从好到差排列：先比较可用、异常、未知、不通，再比较真实访问成功率、连续失败、P95、平均延迟和样本数；没有访问样本时使用最近手测的出口与 SSH 延迟。还可单独按状态、成功率、三类延迟、最近活动或 Profile ID 排序并切换方向。

• 状态可多选，访问样本和手测结果可分别筛选“有/无”。
• 搜索同时匹配 Profile ID、SSH 用户、服务器 IP 和端口。
• 视图设置保存在浏览器；鼠标或键盘焦点位于表格内时，健康刷新不会突然移动操作按钮。

按需测试与数据保留

• 每行“测试”测试单个 Profile，“测试全部”测试整个列表；批次内部最多并发 3 个节点，服务同时只运行一个批次。
• 测试不会切换活动 Profile，不会加入连接池或被动成功率，完成后立即关闭 SSH 连接。
• 健康分钟桶和最新状态保存在现有 traffic.db，有效窗口为 24 小时；无样本或样本过期显示未知。
• 服务器、端口、用户、私钥路径改变或 Profile 被删除时，会清除对应旧健康数据。

接口包括 GET /admin/profiles/health、POST /admin/profiles/test 和 GET /admin/profiles/test/status?testId=...。参见 配置 API 和 完整功能说明。

DNS 跟随分组路由

本地 DNS 按查询域名复用域名分组的优先级、启停、继承和覆盖，通过选中的 SSH 节点向上游查询。未命中时走当前默认 Profile；命中组失败返回 SERVFAIL，不回退其他出口或系统 DNS。本地支持 UDP/TCP，上游使用 SSH 内的 TCP DNS，返回真实 IP。

dns.enable=true
dns.local.address=127.0.0.1:1053
dns.upstreams=1.1.1.1:53,8.8.8.8:53

默认关闭，可单独开启而不启用 SOCKS5/HTTP。普通程序和服务程序均支持同名参数。全局设置在管理页“DNS配置”中修改，重启进程生效。Profile 的“DNS 上游覆盖”保存后对新查询生效，仅修改覆盖不会断开已有 TCP。

每个上游列表支持 1–2 个 IP:端口，IPv6 使用 [2001:db8::53]:53。Profile JSON 字段为 "dnsUpstreams":["10.0.0.53:53"]，留空继承全局；覆盖失败不会回退全局。随机组每次查询独立选择，不保证后续 TCP 选中同一个节点。首版不缓存应答，合法负响应直接返回；查询总超时 10 秒，单次上游最多 5 秒。

dig @127.0.0.1 -p 1053 example.com A
dig @127.0.0.1 -p 1053 example.com AAAA +tcp

程序不会修改系统 DNS；系统接入需使用 53 端口或本地转发到 1053，SSH 服务器域名需有独立的启动解析途径。只有接入此服务的查询生效。客户端若只把真实 IP 交给代理，TCP 无法还原域名；需要域名路由时应向代理提交域名。此功能不提供 Fake-IP、DoH/DoT 或通用 UDP 转发。DNS 日志记录实际出口与上游，不计入业务访问成功率。参见 配置 API。

路由规则组 v1.6.0+ v1.6.1 批量编辑

访问 http://localhost:1083/view/routes 可把同一服务的多个域名、IP 或 CIDR 放入带名称和说明的规则组。组提供默认出口，单规则可继承或独立覆盖；页面还支持跨组多选、搜索筛选、批量迁移到现有/新组、继承切换、统一独立出口和批量启停。配置保存在活动配置文件同目录的版本 2 routes.json；未显式指定配置文件时，使用 ~/.ssh-tunnel/routes.json。

规则类型与策略

• domain：域名后缀及 *.google.com 通配域名。
• ip：IPv4 精确值或通配符，如 192.168.*。
• cidr：IPv4/IPv6 CIDR，如 10.0.0.0/8。
• fixed：必须选择一个 Profile。
• random：至少选择两个 Profile，每个新 TCP 连接重新打乱并依次尝试。所有目标失败时不回退默认 Profile。

组和规则双层开关共同决定是否生效；关闭组不会改变组内规则各自的开关状态。命中时按所有组之间的更具体规则优先；未命中或规则未生效时，继续执行默认 Profile、域名过滤或直连逻辑。有效规则所需的后台 SSH 连接池会实时增删，无需重启服务。

旧配置迁移

版本 1 平铺规则和 Profile 中的旧 domainRoutes 会自动迁入确定 ID 的“未分组（自动迁移）”。每条旧规则保留原出口作为独立覆盖，升级行为不变。如存在相同的规范化模式，程序会拒绝启动并明确报冲突。

持久化流量统计 v1.5.0+

SSH 状态页 /view/ssh/state 展示所有代理流量的总体数据、各实际使用的 Profile 和直连明细，包含实时速度、累计值和 24 小时、7 天、30 天及按月历史。

• 数据保存于配置目录的 traffic.db，每 5 秒批量刷盘，正常停止时强制同步。
• 历史按运行机器的系统本地时区保存小时桶，保留最近 365 天。
• 支持整体或单 Profile 重置，重置不删除历史小时数据。
• 数据库打开失败或被其他进程锁定时，服务会中止启动，不会退化为易失统计。

SSH 连接池 v1.4.18+

SSH-Tunnel 内置多成员 SSH 连接池，每个代理请求从池中选取一条 SSH 链路，实现并发复用与自动故障摘除。

成员状态

• healthy 健康，正常承载请求
• suspect 可疑，已检测到异常信号，进入观察期
• probing 探测中，正在通过探测 URL 验证连通性
• reconnecting 重连中，SSH 链路断开后正在恢复
• evicted 已摘除，移出活跃池并记入历史

关键参数

ssh.pool.size=5
ssh.pool.replenish.interval.sec=1
ssh.pool.balance.strategy=least_active
ssh.probe.url=https://www.google.com
ssh.probe.timeout.sec=3
ssh.probe.failure.threshold=2
proxy.retry.max.attempts=1

管理界面操作

访问 SSH 状态页（/view/ssh/state）可进行以下操作：

• 实时查看所有成员状态及请求计数
• 点击「探测」按钮对指定成员发起主动健康检查
• 点击「🗑」按钮手动摘除指定活跃成员
• 点击「清理已摘除」按钮一键清空摘除历史记录

版本管理 v1.4+

SSH-Tunnel 内置版本管理页面，可定时检测 GitHub Release，并在人工确认后完成一键升级。

访问地址：http://localhost:1083/view/version

主要功能

• 定时从 GitHub Release API 检测新版本（可自定义检查间隔）
• 展示所有可用版本及发布说明，支持分页浏览
• 支持指定版本一键更新，含 SHA256 完整性校验
• Linux/macOS 升级后自动 chmod 0755 确保执行权限（v1.4.21+）
• Windows 平台通过临时脚本完成原子替换

域名过滤

SSH-Tunnel 支持 HTTP 请求的域名过滤功能，可以根据域名决定是否通过 SSH 隧道转发请求：

./ssh-tunnel -s xx.xx.xx.xx -http.enable -http.domain-filter.enable -http.domain-filter.file-path /path/to/domain.txt

域名过滤文件 domain.txt 的格式示例：

*.google.com
*.github.com
github.com
*.stackoverflow.com
stackoverflow.com

当启用域名过滤时，只有匹配这些域名的 HTTP 请求会通过 SSH 隧道转发。您可以通过管理界面动态管理这些域名。

服务配置

SSH-Tunnel 支持配置为系统服务，以实现开机自启动。

MacOS 开机自启动配置

在 MacOS 上，您可以将 SSH-Tunnel 配置为 LaunchAgent 以实现开机自启动：

1. 将 ssh-tunnel 可执行文件放到 /usr/local/bin 目录下
2. 创建 com.idefav.ssh-tunnel.plist 文件，内容类似如下：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>Label</key>
    <string>com.idefav.ssh-tunnel</string>
    <key>Disabled</key>
    <false/>
    <key>KeepAlive</key>
    <true/>
    <key>ProcessType</key>
    <string>Background</string>
    <key>ProgramArguments</key>
    <array>
      <string>/usr/local/bin/ssh-tunnel</string>
      <string>-s</string>
      <string>xx.xx.xx.xx</string>
      <string>-server.ssh.port</string>
      <string>10022</string>
      <string>-l</string>
      <string>0.0.0.0:1081</string>
      <string>-socks5.enable=false</string>
      <string>-http.enable</string>
      <string>-http.over.ssh.enable</string>
      <string>-http.domain-filter.enable</string>
    </array>
    <key>UserName</key>
    <string>root</string>
    <key>GroupName</key>
    <string>wheel</string>
  </dict>
</plist>

3. 将该文件放到 /Library/LaunchDaemons 目录下
4. 设置文件权限和加载服务：

sudo chown -R root /Library/LaunchDaemons/com.idefav.ssh-tunnel.plist
launchctl load -w /Library/LaunchDaemons/com.idefav.ssh-tunnel.plist

Windows 服务配置

在 Windows 上，SSH-Tunnel 提供了服务安装功能：

1. 在 C 盘根目录创建 ssh-tunnel 目录
2. 在该目录下创建 .ssh-tunnel 目录，并创建 config.properties 文件：

server.ip=xx.xx.xx.xx
server.ssh.port=22
ssh.private_key_path=C:\\Users\\username\\.ssh\\id_rsa
login.username=root
local.address=127.0.0.1:1081
http.local.address=127.0.0.1:1082
http.enable=false
socks5.enable=true
http.over-ssh.enable=false
http.domain-filter.enable=false
http.domain-filter.file-path=C:\\Users\\username\\Documents\\ssh-tunnel\\domain.txt
admin.enable=true
admin.address=127.0.0.1:1083

3. 安装 Windows 服务：

C:\ssh-tunnel\ssh-tunnel-svc.exe install --config=C:\ssh-tunnel\.ssh-tunnel\config.properties

然后可以在服务管理器中找到并启动 SSHTunnelService。