# 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 配置尽量少改,不要大改」 > > 已核实前提:客户端当前**都已启用 TLS**。服务端两套实现均可接入:Go 版(`server/go`) > 与 MFC 版(`server/2015Remote`,见 §4.2)。 ## 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 号协议的情况。 > > 但这是**协议号复用**:从此任何历史落盘 / 历史配置里的 `proto=5` 一律按 `PROTO_WS` 解释。 > 老客户端与老服务端之间若曾有 `5` 的任何含义,都会在这次升级后变成 WS。 ## 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()`。 - 握手超时:`connect()` 之后、TLS/WS 握手之前给 socket 设 **15 s** `SO_RCVTIMEO`/`SO_SNDTIMEO`, 握手结束(成功路径)立刻清零。`WsChannel::Handshake` 是同步逐字节读 101 响应的;没有这道 保护时,对端接受 TCP 却不回数据(反代上游黑洞)会让 `StartClient` 的重连循环永久停摆。 服务端两个握手线程用的是同一个 15 s。 - `m_useWs` / `m_useTls` / `WsChannel::m_ready` 均为 `std::atomic`:写的一方是连接线程, 读的一方是接收/发送线程(`Disconnect` 也可能从接收线程侧清)。 - 帧掩码由 `WsChannel` 私有的 xorshift64 在 `m_sendMtx` **内**生成:不能用全局 `rand()` ——`HttpMask` 的构造函数里有 `srand(time(nullptr))`,会在同进程内重置全局序列,而收、发两个 线程都会写帧。 - 不校验 `Sec-WebSocket-Accept`(设计上由 TLS + 隧道内登录承担)。明文 `PROTO_WS` 下这意味着 中间人可以伪造 101 接管字节流——这正是「裸 WS 只适合内网」的另一半理由。 - 没有 `conn` 的构造路径(Linux / macOS / Android 的 `main` 都是 `new IOCPClient(exit, false)`) 拿不到外壳注入的 `CONNECT_ADDRESS`,协议由 `IOCPClient::SetDefaultProto()` 显式给出; 三个平台的 `main` 都在进入重连循环前调一次。不调则保持 `-1`、按明文直连——那正是 「配置成 WS 却毫无反应」的来源,所以这里留了一行日志便于排查。 ### 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(未定义 `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. 服务端实现 ### 4.1 Go 服务端(`server/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` | ### 4.2 MFC 服务端(`server/2015Remote`) MFC 服务端此前就在设备端口上嗅探 TLS(首字节 `0x16 0x03` → `ServerTlsSession`), WS 叠在同一层状态机之上,**与 TLS 是分层而不是并列**(`wss` = TLS 里的 WebSocket): ``` 子套接字 -- TLS 嗅探 --+-- 明文 --+-- "GET " 嗅探 --+-- WS 帧 --+--> ParseReceivedData | | | +-- TLS ---+----------------+(WSS 时帧在解密的明文里判) ``` 新增两个文件,其余改动都在既有握手/收发路径上: | 文件 | 职责 | |---|---| | `ServerWsSession.h/.cpp` | 每连接 WS 会话:升级握手(逐行解析、8 KiB 上限、`Sec-WebSocket-Accept`)、流式解帧(不整帧缓冲,大帧按片交付)、控制帧(ping→pong、close 回显后断开)、转发真实 IP | | `IOCPServer.cpp` | `WsHandshakeThreadProc` / `StartWsHandshake`(专用阻塞线程,与 TLS 握手线程同一模式)、`DispatchPlain`(明文/WSS 共用入口)、`OnClientPreSending` 里的「先封帧、再 TLS 加密」 | - 状态机:`ServerWsState { WS_Undecided → WS_Handshaking → WS_Ready | WS_None }` 与既有的 `ServerTlsState` 并存;`CONTEXT_OBJECT` 复用(`InitMember`)时一并复位并释放会话。 - 判定点:**明文的第一段有 ≥6 字节**才开始分类(与 ClientHello 嗅探同一下限), 避免把「请求头还没到齐」误判掉;阈值内的字节攒在 `wsPreClassify` 里(与 TLS 嗅探的 `tlsPreClassify` 分开,两者服务不同状态机,串行使用但字段不共用)。 - 升级线程与 TLS 握手线程同构:`FIONBIO=0`(该套接字常是非阻塞的,`ioctlsocket` 会以 `WSAEINVAL` 失败),15 s 收发超时,遇 `WSAEWOULDBLOCK` 用 `select` 等可读/可写再试; 线程持有一枚 `IoRefCount`,结束后把 socket 交还 IOCP(`PostRecv`)。升级响应之后同批 字节里若已带客户端首帧(WSS 分批解密时常见),先在交还前喂给解帧路径。 - 发送方向:`OnClientPreSending` 里把本次新追加的尾部封成一帧(`TruncateBuffer` + `WriteBuffer`,与既有的「只加密新尾部」同一手法规避在途数据),然后才走 TLS 加密; 控制帧应答(pong / close 回显)走同一条发送路径(`SendWsReplies`,持 `SendLock`)。 - 反代真实 IP:**仅当直接对端是回环地址**时才采信 `X-Forwarded-For` 的**最后一段** (`X-Real-IP` 兜底),且必须是 IP 字面量;结果写回 `PeerName`,在线列表、封禁与 白名单看到的就是设备本身。非回环对端的转发头一律忽略(防伪造)。 - 两段式限流(与 Go 端 `limitDirectPeer` / `handleConnection` 同构):accept 阶段按 `getpeername` 计数——那一次对经反代的连接**没有意义**(反代同机时对端是回环地址, `IPWhitelist` 对回环恒为 true,黑名单/封禁/计数全部不生效)。升级完成后在 `WsHandshakeThreadProc` 里按**真实设备 IP** 重做一次黑名单 / 封禁检查与计数,超阈值 直接 fail-closed。直连连接(无转发头)只在 accept 阶段计一次,不重复计。 反代**异机**部署时转发头不被采信(见 §8),此时需把反代地址加进白名单,否则所有设备 共用反代 IP 那一个计数桶。 - fail-closed 的两处:握手期间(`wsState == WS_Handshaking`)收到 IORead 直接断开(判断 放在 `OnClientReceiving` 最开头,WSS 下 `tlsState` 已是 `TLS_Ready`,放在 TLS 分支之后 就不生效);`wsState == WS_Ready` 但会话已关时,应用字节**丢弃而不是裸发**,否则对端 解帧错位;同时对该 socket 做一次 `shutdown(SD_BOTH)`,让挂起的 recv 立刻返回 0 字节, 由接收路径走正常的 `-2` 收尾(不在这里直接 `RemoveStaleContext`——调用方往往本身就 持有 `IoRefCount`,自己等自己会超时,且可能把已回收复用的上下文交回给调用者)。 - 既有客户端零影响:非 `GET ` 首包在攒够 6 字节后原样进入 `ParseReceivedData`。 - 收尾一致:`dwTrans == 0`(对端 FIN)在 `TLS_Unclassified` / `TLS_Ready` / `TLS_Plain` 三条分支上都必须 `RemoveStaleContext`。WS 改造把 `TLS_Plain` 的 `ParseReceivedData` 换成 `DispatchPlain` 后,`DispatchPlain` 对空数据返回「已处理」,这个判断一度丢了, 连接会停在 CLOSE_WAIT 直到 keepalive(3 分钟),期间占着 IOCP 上下文、一枚挂起的 `WSARecv` 和限流槽。现已补回。 ## 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. 服务端:**无需改动**即可接受 WS 升级(两套实现都是同端口嗅探)。Go 版可选加环境变量 `YAMA_WS_PATH=/api/ws`(不设 = 任意路径)、`YAMA_TRUSTED_PROXIES`(默认够用);MFC 版 不校验路径,转发头只信回环对端(§4.2)。 2. nginx:按 §5 加 server 块或 location,`nginx -t && nginx -s reload`。 3. DNS:`ws.xxx.com` 指向该机器。 4. 生成客户端:协议选 `WebSocket+TLS`,地址填 `ws.xxx.com`,端口 443。 5. 日志确认: - Go 服务端 `WebSocket transport on device port enabled: path=/api/ws`、 `WebSocket device from <真实 IP>`;MFC 服务端 `[WS] ... upgraded via reverse proxy, real client <真实 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`,握手通过。 - MFC 服务端(Debug x64,设备端口 6543,同时开着 TLS): - 独立 Python 最小客户端对 6543 跑 9 项断言全通过:101 状态行、`Sec-WebSocket-Accept` 与 `base64(sha1(key+GUID))` 一致、`Upgrade`/`Connection` 回显、ping→pong(服务端帧不带 掩码)、数据帧后连接保持、close 回显、**升级请求跨两个 TCP 段**仍升级成功、**帧与升级 请求粘在同一段**里也能解出;同一套断言加 `ssl` 包一层(TLSv1.2 ECDHE-RSA-AES256-GCM) 再跑一遍全通过,即 WSS。 - 转发头:`X-Forwarded-For: 198.51.100.7, 203.0.113.9` 时日志记 `[WS] 127.0.0.1 upgraded via reverse proxy, real client 203.0.113.9`(取最后一段)。 - 端到端:让 Debug 服务端向真实客户端下发它自己的 payload(其中配置为 `PROTO_WS`), 客户端日志 `[WS] WebSocket 已就绪: 127.0.0.1:6543/api/ws` → 登录 → 收到主控配置 (1000 字节)→ 上线列表出现该设备并长时间保活(心跳往返即双向数据帧都在工作)。 - 信任锚热重载(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 服务端与 Go 服务端都已实现设备端口的 WS 嗅探**,生成界面里的协议选项两边通用; 差别只在细节:MFC 侧不校验 upgrade 路径(`/api/ws` 只是客户端习惯,反代转到哪个路径都行)。 每 IP 限流两边都是**两段式**(直连对端 / 反代后的真实设备),见 §4.1 与 §4.2。 - MFC 侧的转发头信任范围是**回环对端**(与 Go 的默认 `TrustedProxies` 一致);反代与服务端 不同机部署时,要么让反代用 Proxy Protocol v2(既有的 `ParseProxyProtocolV2` 会先改 `PeerName`),要么把反代地址加进白名单——WS 层不采信非回环对端的转发头。此时限流按 「反代 IP」那一个桶算,**务必把反代地址加进白名单**,否则阈值一响就是全体设备一起被封。 - 试用模式的 WAN 入站检测(`m_bTrialMode && !IsPrivateIPv4Str(clientIP)`)在 accept 时判定, 经反代接入时 `clientIP` 是反代地址(回环或内网),该合规检查会被绕过;转发真实 IP 要到 升级线程里才有。若这是硬性合规要求,需单独评估(本特性未改变这一点,只是让它的漏检更 容易发生)。 - 裸 `PROTO_WS` 是明文,只适合内网或回环(nginx 已在同一台机器上终止 TLS 的情形用 WSS 即可)。 - macOS 客户端自 2026-11-14 起也有 TLS(与 Linux/Android 同一 OpenSSL 实现,见 `TransportTLS_Design.md` §6.8),WSS 与 Linux 行为一致;更早的 macOS 构建仍只能选 `PROTO_WS`(明文),走不了 443。 - 经反代接入时地址只应填**一个域名**(多地址取第一个做 Host/SNI)。 - 不改应用协议、不改 MCP、不改 Web 控制台。 ## 9. 远程协议切换(在线列表右键 → 协议切换) 动机:客户端在线升级只换 DLL,外壳每次注入的连接配置仍是编译时的 TCP 直连入口,所以 「已经在跑」的机器没法被搬到反代入口上。协议切换就是补这一环:由主控下发一次命令,客户端 把新入口落盘并重连,此后(含再次在线升级)都按落盘的入口连。 - 菜单:与「实验功能」平级、紧跟在它下面,三个单选项 `直连 TCP / WS / WSS`。单选状态取 选中主机连接的真实传输(`context::GetProtocol()`:`TCP`/`WS`/`WSS`),不取客户端自报。 选中主机的客户端没有能力位 `CLIENT_CAP_PROTO_SWITCH(0x0020)` 时整组置灰(只有 Windows 客户端实现了该命令)。 - 命令:`COMMAND_SET_PROTO = 177`,载荷 `ProtoSwitchPacket`(113 字节:`proto` + 反代 `host[100]` + `port[8]` + `certLen`),WS/WSS 后面再跟反代信任锚 PEM 正文;`host`/`port` 全空表示「还原到安装时的直连入口」。 - 服务端:WS/WSS 先弹输入框问反代入口(`域名:端口`,记住上次填的 `[ws] Entry`);WSS 额外 要求 `ServerTlsIdentity::IsReady()` 并读取 `[tls] CertPath` 的 PEM 一并下发——没有锚的 客户端会把 WSS 降级成明文 WS,等于静默降级,所以直接拒绝。 - 客户端落盘(`settings` 下):`proto_override` / `entry_host` / `entry_port` / `entry_try_at` 为当前覆盖;`base_*` 是首次切换时记下的安装入口(「还原」用它);`prev_*` 是每次切换前的入口(自动回退用它)。重连循环在建连前 `ApplyProtoSwitch` 覆盖入口——位置 在「外壳注入完配置之后、建连之前」,因此换 DLL 也压不回去。(该函数返回 `void`:它既写 配置也改 `CONNECT_ADDRESS`,返回值无法表达「部分完成」,早期版本里的 `return false` 只是提前退出,调用方一直忽略它。) - 撤销自动回退的判据是**登录被接受**,不是「连接建立」。客户端在收到 `CMD_MASTERSETTING` 时把当前连接标记为已登录(服务端只有在把本机加入在线列表之后才下发 它),重连循环每轮心跳都检查一次,命中才 `ConfirmProtoSwitch` 把 `entry_try_at` 清零。 只看 `IsConnected()` 是不够的:那只是 TCP/TLS/WS 握手完成,新入口能建连但登录始终不被 接受(选错后端 / 反代指到别的 WS 服务 / 服务端登录阶段丢弃)时,提前撤销会让自动回退 永久失效,客户端卡在错误入口反复重连。 - 随包下发的信任锚先落盘再 `TlsReload`;**加载失败即放弃本次切换**——回滚 `tls_cert`、 不写 `proto_override`/`entry_*`、不断连,并把失败原因用 `ClientMsg` 回报操作端。否则客户端 会进入 `TlsLoadError()` 的 fail-closed 状态,切过去只是「新入口连不上,等 5 分钟回退」。 - 自动回退:新入口 5 分钟内一直登不上,回到 `prev_*` 并把它改写成新的覆盖(不是清空,否则 下一轮会落进「还原」分支又跳回直连入口)。分享实例(`m_bShared`)忽略该命令——它的入口 由分享方控制。 - `ProtoSwitchPacket::certLen` 不做字节序转换:当前服务端与 Windows 客户端同为小端,无影响; 将来若出现大端平台的客户端,需要补一次 `ntohl`/`htonl`。 ## 9.1 分享链路携带传输方式(2026-11-02 修复) §9 的「分享实例忽略 `COMMAND_SET_PROTO`」只保护了**入口**,却把**传输**一起挡住了: `COMMAND_SHARE` 的载荷一直只有 `host:port:shine`(Shine/HELL 是应用层),传输方式不在 契约内。于是分享实例只能沿用**出包时烘焙的** `protoType`。 实测后果(ASM-03,烘焙 TCP、主连接已切 WSS):分享到 Go 服务端的 `nginx:443` 后,分享 实例带着裸 TLS 上的 YAMA 字节去撞一个只收 HTTP/WebSocket 的前端,被回 `HTTP/1.1 400 Bad Request`,每 5 秒一轮重连,永远登不上。反过来(烘焙 WSS、分享给直连 设备端口的服务端)会以对称的方式坏掉——所以这是「契约不携带传输」的缺口,不是某个分支 的疏漏。 **不能简单去掉 `ClientDll.cpp` 里 `ApplyProtoSwitch` 的 `!app.m_bShared` 判断**:那个函数 同时写 `entry_host/entry_port` 和 `protoType`,放行后分享实例会被指到主控入口上。 新契约(分享追加第 4 段,转移追加第 5 段): ``` host:port:shine:transport # 分享(COMMAND_SHARE) host:port:days:shine:transport # 转移(COMMAND_ASSIGN_MASTER) # transport = PROTO_TCP(0) / PROTO_WS(5) / PROTO_WSS(6);缺省 = 沿用烘焙值 ``` - **双向兼容**:老客户端只读到第 3 段,第 4 段被忽略 → 退回烘焙值(行为与改造前一致); 老服务端不下发第 4 段时,新客户端同样按烘焙值走。只认这三个合法值——`atoi` 对非法串 返回 0(正是 `PROTO_TCP`),不校验就会把 WSS 静默降级成直连。 - **服务端取值**(`2015RemoteDlg.cpp::OnOnlineShare`):默认取选中主机**当前的真实传输** (`ctx->GetProtocol()` → TCP/WS/WSS),即「这台机器已切成 WSS,分享出去也该是 WSS」。 地址栏另支持 `tcp://` / `ws://` / `wss://` 前缀显式覆盖;前缀写了却认不出来时提示重填, 不静默按默认值分享。选中主机的传输不属于这三种(HTTP 伪装 / UDP / KCP)或根本没选中 主机时**不下发第 4 段**,分享实例沿用烘焙值——用 `PROTO_TCP` 兜底会把这些客户端强行 改成直连,是行为倒退。多选时取第一个**传输可识别**的主机(与协议切换菜单同规则)。 - **客户端落地**:`NewClientStartArg` 增加 `protoType` 参数(-1 = 沿用烘焙值),只改该实例 自己那份 `CONNECT_ADDRESS`(`ClientApp` 构造时已深拷贝,不影响主实例); `share_list` 持久化为 `host:port:shine:transport`,重启后照旧生效。`ApplyProtoSwitch` 对 `m_bShared` 的跳过保持不变。 - **分享链路的传输在分享那一刻定格**,不跟随主连接之后的 TCP ↔ WSS 切换(含新入口 5 分钟登不上触发的自动回退):分享实例读不到 `proto_override`,它的 `protoType` 来自 `share_list` 第 4 段。这是刻意的——分享目标是**另一台**服务端,它的前端形态与主控 无关;主控侧反代挂了退回 TCP,不该把另一条已经能用的链路一起改掉。要换分享链路的 传输只能重新分享一次。 - **重新分享按 `host:port` 去重**(不是按整条记录比):同一条目标换了传输时第 3/4 段 会变,整条比会判成新条目,结果同一 `clientID` 起两个分享实例、登录时互相踢。老记录 (3 段)也在这一步被新记录替换。已在跑的旧实例要等进程重启才消失——与 `COMMAND_SHARE_CANCEL` 的语义一致(都是「下次运行生效」)。 - **信任锚仍按目标地址选**(§3.6):服务端**不**随分享下发 PEM——分享方拿不到接收方的 证书,下发自己的那张只会把主连接校验搞坏。目标没有可校验的锚时按 §3.2 退化为明文 WS 并打日志;若对端是 TLS-only 的反代,那条链路依然不可达,需要先给客户端装上接收方的锚。 - **转移主机(`SHARE_TYPE_YAMA_FOREVER`)同样携带传输**:载荷是 `host:port:days:shine[:transport]`,传输排在第 5 段(客户端按 `pv[4]` 取,前 4 段被 天数/Shine 占着),落盘到 `settings\master_transport`,由 `StartClient` 的 assigned 分支应用。没带这一段时把 `master_transport` **清空**,否则会沿用上一次转移留下的值, 把一条本该直连的链路继续按 WSS 去连。转移与分享共用同一个地址对话框和历史记录 (`ShareAddress`),所以两边都支持 `tcp://` / `ws://` / `wss://` 前缀——只改分享不改 转移的话,在分享对话框里存下的带前缀历史会被转移对话框选中并当成主机名发下去。 ## 10. 审查遗留(已知边界,未改动) 以下条目来自 PR 审查,记录在此以免重复讨论。带「已处理」的是复查后**已经改掉**的, 留在这里说明当时的判断,其余评估后保留现状: - **`GetPeerName(SOCKET)` 只走 `sockaddr_in`(IPv4)**:`ServerWsSession.cpp::IsLoopbackPeer` 里的 `::1` / `::ffff:127.0.0.1` 分支目前是死代码。将来若监听 IPv6,转发头信任也需要跟着 改,否则会静默失效。 - **`tlsPreClassify` 名不副实**:已处理——WS 的 "GET " 前缀缓冲拆成独立的 `wsPreClassify`, `tlsPreClassify` 回归 ClientHello 嗅探单一职责(两条路径仍按先后串行,互不重叠)。 - **`WsChannel::Reset()` 与接收线程的帧状态**:已处理——`Disconnect()` 可能来自心跳/命令线程, 不只是接收线程,所以 `Reset()` 现在只翻转原子的 `m_ready`;`m_remaining` / `m_masked` / `m_maskPos` 改由 `ResetFrames()` 清,且只在 `Handshake()` 里(连接线程、接收线程尚未起来) 调用。这样这几个字段始终只有一个线程访问,不用加锁。 - **客户端单帧载荷上限 256 MB**(`WsChannel::kMaxFramePayload`,与 `ServerWsSession` 同值): 超过即按错误断开。没有上限时一个错误长度字段就能把 `m_remaining` 定在天文数字上, 连接「活着但永远收不到新包」。正常业务的最大单包远小于此值。 - **`DispatchPlain` 对明文首包引入「攒够 6 字节再解析」**:这是既有路径的行为变更。当前首包 是登录包(远大于 6 字节),实际无影响;极端情况下(<6 字节的合法首包)会多等一轮收包。 - **客户端不校验 `Sec-WebSocket-Accept`**:见 §3;明文 WS 下中间人可伪造 101,已在 §8 明确 裸 WS 只适合内网。 - **Go `wrapWebSocket` 的 `Peek`**:已改为即使 `ReadTimeout == 0` 也用 `wsHandshakeTimeout` (10 s,取与 `ReadTimeout` 的较小值)封顶,慢速对端不再能长期占住 goroutine 与限流槽。