# 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 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 \ | 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 控制台。