Files
SimpleRemoter/docs/WebSocket_Transport_Design.md
T

323 lines
20 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# WebSocket 传输设计(受限出站端口下经反代接入)
> 版本:v1.0(已实现并本地验证) · 日期:2026-10-30
> 目标:客户端的出站被限制在 80 / 443 / 8080 等少数端口,且这些端口都不归主控所有时,
> 仍能让客户端连上服务端;同时把 nginx 侧改动压到最小(只加一个 server 块或一个 location)。
>
> 需求原文:
> 1. 「我的客户端连接服务端时端口被限制……只能借助于已有端口分流,比如 nginx 的端口。
> 但是我的客户端目前是 TCP 流量。调研一下怎么解决」
> 2. 「我的客户端连接到 xxx.com:6543, 但是 6543 不允许出站」
> 3. 「6543 我可以修改,但是只能改为 80,443,8080,但是这些端口都已经在使用」
> 4. 「B 方案更适合目前场景。xxx.com 的 nginx 配置尽量少改,不要大改」
>
> 已核实前提:目标服务端是 **Go 版(`server/go`)**;客户端当前**都已启用 TLS**。
## 1. 方案选型
| 方案 | 做法 | 结论 |
|---|---|---|
| A. 占用 8080 | 把主控端口改到 8080 直连 | 否决:8080 已被别的应用占用 |
| **B. WebSocket over nginx 443** | 客户端把应用字节流套进 WS 帧,经 nginx `server_name` + `location /api/ws` 转发到 127.0.0.1:6543 | **采用** |
| C. 租新端口 | 换一台能出站的机器/端口 | 否决:出站白名单是客户端侧策略,换端口仍被拦 |
B 方案的关键点:WS 升级只是一次普通 HTTP 请求,nginx 现有的 443 已经能承载;
真正的应用协议完全不变,只是「字节流外面多了一层帧」。
## 2. 协议号与形态
`common/commands.h`:
| 值 | 枚举 | 形态 |
|---|---|---|
| 5 | `PROTO_WS` | 裸 WebSocket(明文;反代把明文 upgrade 转发到主控端口) |
| 6 | `PROTO_WSS` | WebSocket over TLS(**客户端经反代 443 接入,推荐**) |
| 7 | `PROTO_HTTPS` | 从未在生成界面出现过,故 5 让给 WS(原值 5,见下方风险) |
`WS_UPGRADE_PATH` = `/api/ws`:客户端请求的 Upgrade 路径,反代的 `location` 必须与之对齐;
服务端默认接受任意路径,`YAMA_WS_PATH` 只用于把路径收窄。
传输层位置(自下而上):TCP → TLS(可选)→ **WebSocket 帧** → 既有应用协议(Shine/HELL 头、
XOR、zstd、HTTP 伪装层)。WS 与 HTTP 伪装的 `MaskType` 互斥:选 WS 时用 `MaskTypeNone`。
> 兼容性:`PROTO_HTTPS` 从 5 移到 7。它在 `NewNetClient` 里本来就被直接拒绝、生成界面也从未
> 提供,因此不存在已发布客户端带 5 号协议的情况。
## 3. 客户端实现
新增 `client/WsChannel.h`(**头文件实现**,各平台工程文件不必改动):
- `Handshake(sock, host, port, path, &err)`:发 `GET <path> HTTP/1.1` + `Upgrade: websocket`,
期望 `HTTP/1.1 101`;`Sec-WebSocket-Key` 用固定值(它只用于让中间设备识别这是 WS 握手,
安全由隧道内登录与 TLS 承担)。
- `Send`:一次 `SendTo` 写一帧(FIN + binary,**客户端帧必须掩码**,RFC 6455 §5.3),
与 Go 端 `wsConn.Write` 的「一次 Write 一帧」对齐,包边界与发出时一致。
- `Recv`:在帧载荷上做流式读取(`m_remaining` 记录剩余、`m_maskPos` 记录掩码位置),
ping 自动回 pong,close 回 close 并按正常关闭返回 0,跨帧边界的应用层包不会丢。
- `HasPending()`:帧载荷只解析了一半、或 WSS 下 TLS 会话里还压着已解密明文时返回 true,
让接收线程在 `select` 之前优先消费(否则只能等 2 秒超时)。
- 并发写:`Recv` 里要为 ping/close 回写控制帧,与发送线程的数据帧是两条并发的写路径。
`WriteFrame` 用 `m_sendMtx` 串行化,并把整帧(帧头 + 掩码载荷)放进一个复用缓冲区、
一次 `SendAll` 写出——若头体分两次写,两帧会互相穿插,对端从此解帧错位。
接线(`IOCPClient.h` / `.cpp`):`ReceiveData` / `SendTo` / `HasPendingData` 三处在
`m_useTls` 之前判 `m_useWs`;`ConnectServer` 在 socket 选项之后、`m_bConnected = TRUE` 之前
完成 `TLS 握手 → WS 握手`,`Disconnect` 清 `m_useWs` 并 `m_ws.Reset()`。
### 3.1 信任模型:不换锚,靠 SNI 分流
客户端证书校验仍是**钉死信任锚**(Windows:`CertCreateCertificateChainEngine` + `hExclusiveRoot`
手动建链;Linux:`SSL_VERIFY_PEER` + 自定义 `X509_STORE`;均**不校主机名**)。因此
「经 nginx 接入」不能随便换成网站自己的证书——那会校验失败。
于是给 nginx 一个**独立 `server_name`**(如 `ws.xxx.com`)并挂主控自己的证书,客户端靠
**SNI** 让 nginx 选中这个 server 块:
- Windows Schannel:`InitializeSecurityContextA(..., pszTargetName = sni, ...)`(TlsChannel.cpp)
- Linux OpenSSL:`SSL_set_tlsext_host_name(ssl, sni)`(TlsChannelLinux.cpp)
- 只在 `PROTO_WSS` 且地址是域名时传;直连主控端口时保持原样(不发明 SNI),行为与改造前一致。
Host 头同理:用**配置里的地址(域名)**,而不是解析后的 IP——子连接只拿到 IP,必须回到
`CONNECT_ADDRESS::GetFirstServerIP()` 取。地址里填分号分隔的多个地址时取第一个,因此经反代
接入只应填一个域名。
### 3.2 回退与 fail-closed
传输方式只由信任锚决定(进程内缓存,服务端下发后可热重载,见 §3.3):
| 情形 | 行为 |
|---|---|
| 有锚 + `PROTO_WSS` / 直连主控端口 | TLS 握手;**握手或证书校验失败即断开**(fail-closed) |
| **无锚 + `PROTO_WSS`** | **回退为明文 WebSocket**:客户端还没被「颁发」证书,先打通隧道;服务端下发锚后自动升级(见下) |
| 有锚但加载失败(损坏/为空) | 拒绝连接(fail-closed)——管理员已「颁发」证书,不能静默回退明文 |
| 无锚 + `PROTO_WS` | 明文(本来如此) |
| 有锚 + `PROTO_WS` | **仍是明文**(显式选择的形态,见下) |
| 平台无 TLS(macOS / Android 未定义 `YAMA_TLS_CHANNEL`)+ `PROTO_WSS` | 直接断开并打日志:没有热切换路径,回退只会让人误以为在加密 |
| WS 握手失败 | 断开,`Mprintf` 里带上服务端返回的状态行 |
回退的判据是「本机**根本没有**信任锚」这一可观测状态,而不是握手中途失败——TLS 握手
失败、证书链校验失败、WS 握手失败一律断开。因此中间人最多能让「尚未下发锚」的客户端
留在明文(此时本来也没有可校验的锚),无法把已经持锚的客户端拉回明文。
升级路径(服务端菜单「TLS 传输 → 启用」,`COMMAND_TLS_ENABLE` + PEM 正文):客户端把锚
落盘(Windows 注册表 `settings\tls_cert`;Linux `~/.config/ghost/yama-ca.pem`),调用
`TlsReload()` 重建 TLS 上下文,**只在传输方式真正变化(明文 ↔ TLS)时**断开重连,之后
的新连接自动走 WSS;仅换一张证书(仍是 TLS)不打断现有会话。两平台都是立即生效,
不再需要重启进程。撤销(`COMMAND_TLS_DISABLE`)同理反向切换。
> 部署含义:「先明文、之后升级为 WSS」要求同一个 `地址:端口` 既能吃明文 WS 也能吃 TLS
> ——Go 服务端的设备端口正是这样(`wrapTLS` → `wrapWebSocket` 两级嗅探,见 §4)。由
> nginx 终止 TLS 的部署做不到:443 只收 TLS,明文回退会直接失败,这种拓扑必须先把证书
> 配到 nginx 上再出包。(对应的两个 nginx 监听端口也无法互替,地址是出包时写死的。)
`PROTO_WS` 的定位不变:它是**显式选择的明文形态**(§5.2 的 80 端口明文反代、内网直连),
即便客户端配了信任锚也不叠加 TLS,否则该路径永远不可达——选择 WS 是出包时的决定,
不存在远端可触发的降级。
### 3.3 信任锚热重载
`TlsEnabled()` / `TlsLoadError()` 首次调用时加载锚,之后读写的是受 `TlsReload` 保护的
进程级状态(Windows 原来用 `std::call_once` 缓存到进程结束,无法热切换;现改为互斥量,
与 Linux 版语义一致):
- 重建失败(锚存在但无效)→ **保持现有状态不变**,只记一行日志:一次坏下发不该打死正在
工作的客户端;下次启动仍会 fail-closed。
- 重建成功 → 互换 store / 链引擎并释放旧的。Windows 的证书校验(`VerifyServerCert`)
在整个校验过程中持同一把锁,因此旧句柄不会在别的线程手里被释放。
- 回环验证:Linux 由 `linux/main.cpp::ApplyTlsAnchorChange`、Windows 由
`client/KernelManager.cpp::ApplyTlsAnchorChange` 调用,两者都只在 `TlsEnabled()`
前后值发生变化时 `Disconnect()`,让重连循环用新传输方式重新登录。
## 4. 服务端实现(Go)
`server/go/server/ws.go`,在 `handleConnection` 里分层嗅探:
```
raw conn --wrapTLS(嗅 0x16 0x03)--> [TLS] --wrapWebSocket(嗅 "GET ")--> [WS 帧]
```
- 非 WS 连接:`bufferedConn` 原样返回,既有客户端零影响;嗅探用 `Peek`,不消耗字节。
- WS 连接:解析请求头、校验 `Upgrade`/`Connection`/`Sec-WebSocket-Key`,`YAMA_WS_PATH`
非空时再校验路径;通过后回 101 并返回 `wsConn`。
- `wsConn`:`Read` 在帧载荷上流式返回,`Write` 一次一帧(`net.Buffers` writev 拼头与体),
处理客户端掩码、控制帧(ping/pong/close),`Close` 发 close 帧并设 1 秒写超时。
- 反代信任:仅当对端 IP 落在 `TrustedProxies`(默认回环)内才采信 `X-Forwarded-For` /
`X-Real-IP`,取到的真实 IP 用于 `Context.GetPeerIP()`、`hub.Device.PeerIP` 与 ConnAuth
子连接的源 IP 绑定。
- 真实 IP 取 `X-Forwarded-For` 的**最后一段**(nginx 的 `$proxy_add_x_forwarded_for` 把
它实际看到的地址追加在末尾,客户端自己塞在开头的段一律无视;与 `web/ws.go` 的 `clientIP`
同一规则),没有 XFF 时才退回 `X-Real-IP`。
- 每 IP 限流分两段:**直连对端**在 `acceptLoop` 里、起 goroutine 和任何嗅探读之前就计数
(否则一个只建连接不发字节的对端能白占 goroutine 和缓冲直到 `ReadTimeout`);**反代后面
的设备**在 `handleConnection` 里按上报的真实 IP 计数(否则所有设备共用一个回环额度)。
环境变量:
| 变量 | 说明 |
|---|---|
| `YAMA_WS_PATH` | 只接受该路径的 upgrade(空 = 任意路径) |
| `YAMA_TRUSTED_PROXIES` | 允许上报真实 IP 的代理地址,逗号分隔的 IP/CIDR,默认 `127.0.0.0/8,::1/128` |
## 5. nginx 最小改动
前提:客户端地址填 `ws.xxx.com`、端口 **443**、协议选 **WebSocket+TLS**。
DNS 加一条 `ws.xxx.com` → 同一台机器即可(共用 443,靠 SNI + Host 分流,**不动**现有站点块)。
```nginx
# 新增一个 server 块;证书用主控自己的那份(就是客户端钉的锚,与 6543 的 YAMA_TLS_CERT 同一文件)
server {
listen 443 ssl; # nginx ≥1.25.1 可另加一行 http2 on;
server_name ws.xxx.com;
ssl_certificate /etc/nginx/certs/yama.crt;
ssl_certificate_key /etc/nginx/certs/yama.key;
location /api/ws {
proxy_pass http://127.0.0.1:6543; # 主控设备端口
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr; # 让服务端拿到设备真实 IP
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_buffering off; # 长连接必须关缓冲
proxy_read_timeout 86400s; # 空闲心跳间隔远小于此,防止被掐
proxy_send_timeout 86400s;
}
}
```
若该域名现有的 443 证书**正好就是客户端钉的那份**,可以连 server 块都不加,
只把上面 `location /api/ws { ... }` 贴进现有 443 块里。
### 5.1 站点与主控用两张不同证书时
实际部署里 `xxx.com` 的 443 证书(网站那张)和 6543 用的证书(客户端钉的锚)**是两张**。
同一端口放两张证书没问题,nginx 按 **SNI** 选 server 块:
| 客户端填的地址 | 客户端发的 SNI | nginx 选中 | 出示的证书 | 结果 |
|---|---|---|---|---|
| `xxx.com` | `xxx.com` | 网站块 | 网站的证书 | **握手失败**(不是钉的锚) |
| `ws.xxx.com` | `ws.xxx.com` | 主控块 | 6543 那张 | 通过 |
所以设备端必须用**另一个名字**(`ws.xxx.com`,或任何解析到同机、nginx 里能单独成块的名字):
- DNS:加一条 `ws.xxx.com` A 记录;若已有泛解析 `*.xxx.com` 则无需改动。
- `ssl_certificate` 指向**与 Go 服务端 `YAMA_TLS_CERT` 完全相同的那个文件**(Go 端若配的是
fullchain,这里也用 fullchain)。证书内容稍有不同(换过一张、少了中间证书)就会校验失败。
- 这张证书**不需要覆盖 `ws.xxx.com`**——客户端只验链到钉死的锚,不校主机名(见 §3.1)。
- 不要给主控块加 `default_server`,让网站块继续当默认块,其它访客行为不变。
自查(在服务器上执行,输出应是 6543 那张证书):
```bash
openssl s_client -connect 127.0.0.1:443 -servername ws.xxx.com </dev/null 2>/dev/null \
| openssl x509 -noout -subject -fingerprint -sha256
```
若看到的是网站的证书,说明 SNI 没落到主控块(名字拼错、块没 reload、或客户端地址填的是 `xxx.com`)。
### 5.2 拿不到 `ws.xxx.com` 这种名字时:地址填 IP,用 443 的默认块
结论:**DNS 不是必需的**。SNI 只是 ClientHello 里的一个字符串,nginx 拿它跟 `server_name`
比,不做解析;真正需要 DNS 的只有客户端解析地址这一步。所以换一条路走:
**客户端地址填 IP**(`1.2.3.4`,就是 `xxx.com` 解析出的那个),协议 `WebSocket+TLS`,端口 443。
地址是 IP 字面量时,客户端按 RFC 6066 **不发 SNI**(见 §3.1 的条件),nginx 于是落到 443 的
`default_server` 块——把主控块设成默认块即可。
```nginx
# 主控块:无 SNI(或 SNI 不匹配)时命中,出示客户端钉的那张证书
server {
listen 443 ssl default_server;
server_name _; # 兜底块,不占任何真实域名
ssl_certificate /root/cert/yama.crt; # 与 6543 的 YAMA_TLS_CERT 同一文件
ssl_certificate_key /root/cert/yama.key;
location /api/ws {
proxy_pass http://127.0.0.1:6543;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_buffering off;
proxy_read_timeout 86400s;
proxy_send_timeout 86400s;
}
}
```
现有网站块**一个字都不用改**:浏览器访问 `https://xxx.com` 时会发 SNI `xxx.com`,
按名字命中网站块,照旧拿网站的证书。
四个注意点:
- **同一 `地址:端口` 只能有一个 `default_server`**。若网站块原本写了
`listen 443 ssl default_server;`,把那里的 `default_server` 去掉(`nginx -t` 会直接报
duplicate default server)。
- 若默认块上设了 `ssl_reject_handshake on;`(有的加固模板会这么写),把它删掉,否则无 SNI 的连接被直接拒。
- IPv6 的默认块是独立的:若还有 `listen [::]:443`,默认块要么同样加 `[::]:443 default_server`,
要么保持 IPv4 即可(本客户端只连 AF_INET)。
- 代价是地址里写死 IP:换机器/换 IP 要重出客户端。站点域名不变、只是 `xxx.com` 的 A 记录
换 IP 时,旧客户端会连到旧机器。
> 还有两条退路,代价更大,一般不用:
> - 走 **80 端口明文**:把 `location /api/ws` 贴进现有 80 块,客户端选 `PROTO_WS`。没有证书问题,
> 但整条隧道是明文(只剩既有 XOR/Shine 混淆)。
> - 给客户端加一个「SNI/Host 单独覆盖」的配置项,让地址仍是域名、SNI 用一个不存在的名字。
> 需要改代码和重新出客户端,只有在必须保留域名地址时才值得做。
要点:
- `proxy_http_version 1.1` + 两条 `Upgrade` 头缺一不可,否则 nginx 会把升级请求当普通请求代理。
- 关 `proxy_buffering`,否则 nginx 攒包,画面与控制会明显延迟。
- `X-Real-IP` / `X-Forwarded-For` 只有在服务端的 `YAMA_TRUSTED_PROXIES` 覆盖 `127.0.0.1`
时才被采信(默认已覆盖)。
## 6. 部署清单
1. 服务端:Go 版加环境变量 `YAMA_WS_PATH=/api/ws`(可选)、`YAMA_TRUSTED_PROXIES`(默认够用)。
2. nginx:按 §5 加 server 块或 location,`nginx -t && nginx -s reload`。
3. DNS:`ws.xxx.com` 指向该机器。
4. 生成客户端:协议选 `WebSocket+TLS`,地址填 `ws.xxx.com`,端口 443。
5. 日志确认:
- 服务端 `WebSocket transport on device port enabled: path=/api/ws`、
`WebSocket device from <真实 IP>`;
- 客户端 `[WS] WebSocket 已就绪: ws.xxx.com:443/api/ws (TLS)`。
## 7. 验证方法(本次已做)
- `server/go`:`go test ./...` 全绿,`ws_test.go` 覆盖升级、隧道、ping/pong、1 MiB 大帧、
坏握手拒绝、转发 IP(含「XFF 末尾优先 / 开头伪造被无视」)、信任代理解析,以及
「无换行的超长请求行在 8 KiB 上限处被拒」;`server_test.go` 覆盖直连对端在嗅探前即计入
每 IP 上限、回环反代被豁免。
- 客户端:`client/WsChannel.h` 用一份**独立的 Python 最小 WS 服务端**(std lib 实现,非同一套
代码)交叉验证:1/5/125/126/130/4096/70000 字节全部往返一致、`Host: localhost:18080`
正确、客户端帧带掩码、服务端主动 ping 被回 pong。
- 并发写:另一份 Python 校验端一边每 5 帧发一次 ping、一边逐帧校验 3000×300 字节的载荷,
客户端同时从发送线程写数据帧、从接收线程回 pong。修复前在 ~40 帧处即出现解帧错位
(`BAD_PAYLOAD`/发送失败),修复后 3000 帧全部逐字节正确。
- 互操作:把该测试客户端直接指向真实 Go 服务端(`-port 16543`,`YAMA_WS_PATH=/api/ws`),
服务端日志出现 `WebSocket device from 127.0.0.1`,握手通过。
- 信任锚热重载(Windows):独立 harness(`tlsreload_test.cpp` + 真实 `TlsChannel.cpp`,锚
走 exe 同目录 `yama-ca.pem`)覆盖 6 个场景全部通过:无锚→明文、有效锚→TLS、坏锚首次
加载→fail-closed、无锚→下发锚后重载生效(明文→TLS)、坏锚重载→保持 TLS 不中断、撤销
锚→回到明文。Linux 侧的热重载此前已随 `TlsTrustAnchorSave/Remove` 实现。
- 构建:`ghost` x64/x86 Debug、`ServerDll.dll`、MFC 服务端 Debug x64、Linux
`IOCPClient.cpp` / `TlsChannelLinux.cpp` 语法检查均通过。
## 8. 限制与非目标
- **MFC 服务端(`server/2015Remote`)未实现设备端口的 WS 嗅探**:本功能目前只对接 Go 版服务端。
MFC 侧要支持需在它的连接建立处做同样的一层 sniff。生成界面照常提供这两个协议,但生成完成的
提示里已注明「服务端须为 Go 版本」,避免出包后才发现连不上。
- 裸 `PROTO_WS` 是明文,只适合内网或回环(nginx 已在同一台机器上终止 TLS 的情形用 WSS 即可)。
- macOS / Android 客户端没有 TLS 实现,只能选 `PROTO_WS`(明文),走不了 443。
- 经反代接入时地址只应填**一个域名**(多地址取第一个做 Host/SNI)。
- 不改应用协议、不改 MCP、不改 Web 控制台。