Files
SimpleRemoter/docs/WebSocket_Transport_Design.md
T

26 KiB
Raw Blame History

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 号协议的情况。

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. 服务端实现

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 嗅探同一下限), 避免把「请求头还没到齐」误判掉;阈值内的字节攒在 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,在线列表、封禁与 白名单看到的就是设备本身。非回环对端的转发头一律忽略(防伪造)。
  • 既有客户端零影响:非 GET 首包在攒够 6 字节后原样进入 ParseReceivedData。

5. nginx 最小改动

前提:客户端地址填 ws.xxx.com、端口 443、协议选 WebSocket+TLS。 DNS 加一条 ws.xxx.com → 同一台机器即可(共用 443,靠 SNI + Host 分流,不动现有站点块)。

# 新增一个 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 那张证书):

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 块——把主控块设成默认块即可。

# 主控块:无 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 限流的「直连/反代两段」细分(沿用既有的按连接数计)。
  • MFC 侧的转发头信任范围是回环对端(与 Go 的默认 TrustedProxies 一致);反代与服务端 不同机部署时,要么让反代用 Proxy Protocol v2(既有的 ParseProxyProtocolV2 会先改 PeerName),要么把反代地址加进白名单逻辑——目前的 WS 层不会采信非回环对端的转发头。
  • 裸 PROTO_WS 是明文,只适合内网或回环(nginx 已在同一台机器上终止 TLS 的情形用 WSS 即可)。
  • macOS / Android 客户端没有 TLS 实现,只能选 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 也压不回去;登录成功后 ConfirmProtoSwitch 把 entry_try_at 清零撤销计时。
  • 自动回退:新入口 5 分钟内一直登不上,回到 prev_* 并把它改写成新的覆盖(不是清空,否则 下一轮会落进「还原」分支又跳回直连入口)。分享实例(m_bShared)忽略该命令——它的入口 由分享方控制。