@qzsy/dsh-bridge 2.18.0 → 3.0.0

package/lib/saas/tunnel-client.mjs

@@ -1,33 +1,27 @@
-// DSH Bridge - SaaS 隧道客户端（控制通道协议 v2）
+// SaaS 隧道客户端（控制通道协议 v2）——独立实现，不继承任何第三方隧道类。
 //
-// 契约见 docs/architecture/saas-tunnel.md §6（消息名/字段名不可擅自改名）与
-// packages/tunnel-protocol/src/index.ts（共享类型）：
-//   C→S 首帧 hello → S→C hello-ack(ok=true|false) → 之后沿用 v1 转发消息
-//   （request / response / response-start|chunk|end / ws-open|accept|frame|close / ping|pong）
-//   v2 新增：heartbeat / heartbeat-ack、route-update、drain
-//
-// 设计：继承 lib/tunnel-client.mjs 的 CustomTunnelClient，HTTP/WS 转发语义（含 32MB
-// 上限、gzip、session 投影剥离、Ping 自动 Pong）完全复用父类，本类只替换连接建立、
-// 心跳、重连与 v2 控制消息处理，避免两套转发实现漂移。
-
+// 契约见 docs/architecture/saas-tunnel.md §6 与 packages/tunnel-protocol/src/index.ts：
+//   C→S hello → S→C hello-ack → 转发 request/response(-start|chunk|end) 与 ws-*；
+//   v2 新增 heartbeat/heartbeat-ack、route-update、drain；未知 type 静默忽略。
+//   close 4001/4003/4004 为终态；4000/4002 可重连。
 import { WebSocket } from 'ws';
-import { CustomTunnelClient } from '../tunnel-client.mjs';
+import { request as httpRequest } from 'node:http';
+import { connect as netConnect } from 'node:net';
+import { randomBytes } from 'node:crypto';
 
 export const SAAS_HEARTBEAT_INTERVAL_MS = 30_000;
 export const SAAS_HEARTBEAT_MAX_MISSED = 3;
 export const SAAS_HANDSHAKE_TIMEOUT_MS = 15_000;
 export const SAAS_RECONNECT_BASE_DELAY_MS = 1000;
 export const SAAS_RECONNECT_MAX_DELAY_MS = 60_000;
-export const SAAS_RECONNECT_MAX_ATTEMPTS = Number.POSITIVE_INFINITY;
 export const SAAS_DEFAULT_GATEWAY_PATH = '/_gw/connect';
+export const SAAS_MAX_RESPONSE_BYTES = 32 * 1024 * 1024;
+export const SAAS_TERMINAL_CLOSE_CODES = new Set([4001, 4003, 4004]);
+export const SAAS_TERMINAL_ERROR_CODES = new Set(['auth_failed', 'revoked', 'bad_request', 'unsupported_version', 'time_exhausted']);
 
-/** 控制通道关闭码：4001 认证失败 / 4003 已吊销 → 终态，不再重连（契约 §4.2）。 */
-export const SAAS_TERMINAL_CLOSE_CODES = new Set([4001, 4003]);
-
-/** hello-ack 失败码里的终态集合（quota 视为可重试）。 */
-export const SAAS_TERMINAL_ERROR_CODES = new Set(['auth_failed', 'revoked', 'bad_request', 'unsupported_version']);
+const HOP_BY_HOP = new Set(['connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization', 'te', 'trailer', 'transfer-encoding', 'upgrade']);
+const TUNNEL_HEADER = 'x-dsh-internal-tunnel';
 
-/** SaaS 隧道协议/连接错误。terminal=true 表示不应再自动重连。 */
 export class SaasTunnelError extends Error {
   constructor(code, message, { terminal = false, closeCode = 0, cause } = {}) {
     super(message, cause === undefined ? undefined : { cause });
@@ -38,199 +32,172 @@ export class SaasTunnelError extends Error {
   }
 }
 
-/**
- * 拼接控制通道连接地址：{gatewayUrl}{gatewayPath}?device_token=<JWT>。
- * 契约 §6 允许 query 或 Authorization 头传令牌，这里两者都带（兼容只认一种的网关）。
- *
- * @param {{gatewayUrl: string, gatewayPath?: string, deviceToken?: string}} options
- * @returns {string}
- * @throws {SaasTunnelError} 地址非法
- */
 export function buildSaasConnectUrl({ gatewayUrl, gatewayPath = SAAS_DEFAULT_GATEWAY_PATH, deviceToken } = {}) {
   let url;
   try {
     url = new URL(String(gatewayUrl ?? '').trim());
   } catch {
-    throw new SaasTunnelError('invalid_gateway_url', `SaaS 网关连接地址不是合法 URL: ${gatewayUrl}`);
+    throw new SaasTunnelError('invalid_gateway_url', `SaaS 网关地址不合法: ${gatewayUrl}`, { terminal: true });
   }
   if (url.protocol === 'http:') url.protocol = 'ws:';
   else if (url.protocol === 'https:') url.protocol = 'wss:';
   else if (url.protocol !== 'ws:' && url.protocol !== 'wss:') {
-    throw new SaasTunnelError('invalid_gateway_url', 'SaaS 网关连接地址只支持 ws/wss/http/https');
+    throw new SaasTunnelError('invalid_gateway_url', 'SaaS 网关地址只支持 ws/wss/http/https', { terminal: true });
   }
-  const path = String(gatewayPath ?? '') || SAAS_DEFAULT_GATEWAY_PATH;
-  const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+  let path = String(gatewayPath || SAAS_DEFAULT_GATEWAY_PATH);
+  if (!path.startsWith('/')) path = '/' + path;
   const basePath = url.pathname.replace(/\/+$/, '');
-  url.pathname = `${basePath}${normalizedPath}`.replace(/\/{2,}/g, '/');
+  url.pathname = (basePath && basePath !== '/' ? basePath : '') + path;
   url.search = '';
   url.hash = '';
-  if (deviceToken) url.searchParams.set('device_token', deviceToken);
+  if (deviceToken) url.searchParams.set('device_token', String(deviceToken));
   return url.toString();
 }
 
-/**
- * 从 routes 里挑公网地址：优先 host 形态，其次第一条带 url 的路由。
- * @param {Array<{kind?: string, url?: string}>|null|undefined} routes
- * @returns {string|null}
- */
 export function pickRoutePublicUrl(routes) {
-  if (!Array.isArray(routes)) return null;
-  const list = routes.filter((route) => route && typeof route === 'object');
+  const list = Array.isArray(routes) ? routes.filter((route) => route && typeof route === 'object') : [];
   const host = list.find((route) => route.kind === 'host' && typeof route.url === 'string' && route.url);
-  if (host) return host.url;
   const any = list.find((route) => typeof route.url === 'string' && route.url);
-  return any ? any.url : null;
+  return String((host ?? any)?.url ?? '');
 }
 
-function normalizeDevicePlatform(value) {
-  const text = String(value ?? '').trim();
-  return text || 'unknown';
+function sanitizeHeaders(headers) {
+  const out = {};
+  for (const [name, value] of Object.entries(headers ?? {})) {
+    if (HOP_BY_HOP.has(name.toLowerCase()) || value === undefined) continue;
+    out[name.toLowerCase()] = value;
+  }
+  return out;
 }
 
-export class SaasTunnelClient extends CustomTunnelClient {
-  /**
-   * @param {object} options
-   * @param {string} options.gatewayUrl 数据面网关地址（token 接口返回的 gateway.url，或由控制面地址推导）
-   * @param {string} [options.gatewayPath] 控制通道路径，默认 /_gw/connect
-   * @param {() => Promise<string|{token: string, gateway?: object, tunnel?: object}>} [options.tokenProvider]
-   *   每次（重）连前取新短期令牌；返回对象时可用 gateway/tunnel 覆盖缓存
-   * @param {string} [options.deviceToken] 初始令牌（无 tokenProvider 时使用）
-   * @param {object} [options.deviceInfo] hello.device（name/platform/hostname/arch/pluginVersion/dshVersion）
-   * @param {object} [options.caps] hello.caps 覆盖项
-   * @param {'auto'|'v2'} [options.protocol] auto：兼容旧网关先发 ready 的 v1 降级；v2：严格等 hello-ack
-   * @param {number} [options.heartbeatIntervalMs] 心跳间隔（默认 30s）
-   * @param {number} [options.heartbeatMaxMissed] 连续缺失 ack 多少次判定失效（默认 3）
-   * @param {number} [options.reconnectBaseDelayMs]
-   * @param {number} [options.reconnectMaxDelayMs]
-   * @param {number} [options.maxReconnectAttempts] 默认无限（终态除外）
-   * @param {() => number} [options.random] 测试注入抖动随机源
-   * @param {Function} [options.onHelloAck]
-   * @param {Function} [options.onRouteUpdate]
-   * @param {Function} [options.onDrain]
-   * @param {Function} [options.onDrainComplete]
-   */
-  constructor({
-    gatewayUrl,
-    gatewayPath = SAAS_DEFAULT_GATEWAY_PATH,
-    tokenProvider,
-    deviceToken,
-    deviceInfo = {},
-    caps = {},
-    protocol = 'auto',
-    heartbeatIntervalMs = SAAS_HEARTBEAT_INTERVAL_MS,
-    heartbeatMaxMissed = SAAS_HEARTBEAT_MAX_MISSED,
-    reconnectBaseDelayMs = SAAS_RECONNECT_BASE_DELAY_MS,
-    reconnectMaxDelayMs = SAAS_RECONNECT_MAX_DELAY_MS,
-    maxReconnectAttempts = SAAS_RECONNECT_MAX_ATTEMPTS,
-    random = Math.random,
-    localPort,
-    internalTunnelSecret,
-    signal,
-    onStateChange,
-    logger,
-    sseStreaming = false,
-    onHelloAck,
-    onRouteUpdate,
-    onDrain,
-    onDrainComplete,
-  } = {}) {
-    super({
-      serverUrl: gatewayUrl,
-      accessToken: deviceToken,
+export class SaasTunnelClient {
+  constructor(options = {}) {
+    const {
+      gatewayUrl = '',
+      gatewayPath = SAAS_DEFAULT_GATEWAY_PATH,
+      deviceToken = null,
+      tokenProvider = null,
       localPort,
-      internalTunnelSecret,
-      signal,
-      onStateChange,
-      logger,
-      sseStreaming,
-    });
-    this.gatewayUrl = gatewayUrl ?? '';
+      internalTunnelSecret = '',
+      protocol = 'v2',
+      heartbeatIntervalMs = SAAS_HEARTBEAT_INTERVAL_MS,
+      heartbeatMaxMissed = SAAS_HEARTBEAT_MAX_MISSED,
+      maxResponseBytes = SAAS_MAX_RESPONSE_BYTES,
+      reconnectBaseDelayMs = SAAS_RECONNECT_BASE_DELAY_MS,
+      reconnectMaxDelayMs = SAAS_RECONNECT_MAX_DELAY_MS,
+      maxReconnectAttempts = Number.POSITIVE_INFINITY,
+      random = Math.random,
+      deviceInfo = {},
+      sseStreaming = true,
+      onHelloAck = null,
+      onStateChange = null,
+      onRouteUpdate = null,
+      onDrain = null,
+      onDrainComplete = null,
+      logger = console,
+    } = options;
+
+    if (!localPort) throw new Error('localPort is required');
+    this.gatewayUrl = String(gatewayUrl);
     this.gatewayPath = gatewayPath || SAAS_DEFAULT_GATEWAY_PATH;
-    if (typeof tokenProvider === 'function') {
-      this.tokenProvider = tokenProvider;
-    } else if (deviceToken) {
-      this.tokenProvider = async () => String(deviceToken);
-    } else {
-      this.tokenProvider = null;
-    }
-    this.deviceToken = deviceToken ?? null;
-    this.deviceInfo = deviceInfo ?? {};
-    this.caps = caps ?? {};
-    this.protocol = protocol === 'v2' ? 'v2' : 'auto';
+    this.deviceToken = deviceToken;
+    this.tokenProvider = typeof tokenProvider === 'function'
+      ? tokenProvider
+      : (deviceToken ? async () => deviceToken : null);
+    this.localPort = Number(localPort);
+    this.internalTunnelSecret = String(internalTunnelSecret ?? '');
+    this.protocol = protocol === 'auto' ? 'auto' : 'v2';
     this.protocolVersion = 2;
-    // 下限取 10ms 只服务于单测注入；生产配置在 lib/index.js 收敛到 >= 5s
     this.heartbeatIntervalMs = Math.max(10, Number(heartbeatIntervalMs) || SAAS_HEARTBEAT_INTERVAL_MS);
     this.heartbeatMaxMissed = Math.max(1, Number(heartbeatMaxMissed) || SAAS_HEARTBEAT_MAX_MISSED);
+    this.maxResponseBytes = Math.max(1024, Number(maxResponseBytes) || SAAS_MAX_RESPONSE_BYTES);
     this.reconnectBaseDelayMs = Math.max(10, Number(reconnectBaseDelayMs) || SAAS_RECONNECT_BASE_DELAY_MS);
     this.reconnectMaxDelayMs = Math.max(this.reconnectBaseDelayMs, Number(reconnectMaxDelayMs) || SAAS_RECONNECT_MAX_DELAY_MS);
     this.maxReconnectAttempts = Number.isFinite(maxReconnectAttempts) ? Math.max(0, maxReconnectAttempts) : Number.POSITIVE_INFINITY;
-    this._random = typeof random === 'function' ? random : Math.random;
+    this.random = typeof random === 'function' ? random : Math.random;
+    this.deviceInfo = deviceInfo ?? {};
+    this.sseStreaming = sseStreaming !== false;
+    this.onHelloAck = onHelloAck;
+    this.onStateChange = onStateChange;
+    this.onRouteUpdate = onRouteUpdate;
+    this.onDrain = onDrain;
+    this.onDrainComplete = onDrainComplete;
+    this.logger = logger ?? console;
 
+    this._connected = false;
+    this._state = 'idle';
+    this._stateDetail = '';
+    this._terminal = false;
+    this._draining = false;
+    this._manuallyClosed = false;
+    this._connecting = false;
+    this._ws = null;
+    this._awaitingHandshake = false;
+    this._handshakeResolve = null;
+    this._handshakeReject = null;
+    this._handshakeTimer = null;
+    this._heartbeatTimer = null;
+    this._heartbeatAckPending = false;
+    this._missedHeartbeatAcks = 0;
+    this._reconnectTimer = null;
+    this._reconnectAttempts = 0;
+    this._routes = [];
+    this._routeRev = 0;
     this.tunnel = null;
-    this.routes = [];
-    this.routeRev = 0;
+    this.publicUrl = '';
+    this.lastError = null;
+    this.lastAckAt = null;
     this.limits = null;
     this.features = null;
-    this.sessionId = null;
     this.serverTime = null;
-    this.lastAckAt = null;
-    this.lastError = null;
-    this._missedHeartbeatAcks = 0;
-    this._awaitingHeartbeatAck = false;
-    this._requestsInFlight = new Set();
+    this._inFlight = new Set();
+    this._localWs = new Map();
     this._bytesIn = 0;
     this._bytesOut = 0;
-    this._terminal = false;
-    this._draining = false;
-    this._drainFinished = false;
     this._drainTimer = null;
-    this._drainDeadlineTimer = null;
-    this._connecting = false;
-    this._publicUrlLockedByRoutes = false;
-
-    this.onHelloAck = onHelloAck;
-    this.onRouteUpdate = onRouteUpdate;
-    this.onDrain = onDrain;
-    this.onDrainComplete = onDrainComplete;
-  }
-
-  /** 是否已进入终态（认证失败/吊销/协议拒绝）：终态后不再自动重连。 */
-  get terminal() {
-    return this._terminal;
+    this._suppressReconnect = false;
   }
 
-  /** 是否正在 drain 优雅退出。 */
-  get draining() {
-    return this._draining;
+  get connected() { return this._connected; }
+  get state() { return this._state; }
+  get stateDetail() { return this._stateDetail; }
+  get draining() { return this._draining; }
+  get terminal() { return this._terminal; }
+  get routes() { return this._routes; }
+  get routeRev() { return this._routeRev; }
+  get reconnectAttempts() { return this._reconnectAttempts; }
+
+  _setState(state, detail = '') {
+    this._state = state;
+    this._stateDetail = detail;
+    try { this.onStateChange?.({ state, detail, connected: this._connected, publicUrl: this.publicUrl }); } catch {}
   }
 
   async connect() {
-    if (this.connected || this._connecting) return;
-    if (this.disconnecting || this._terminal) return;
+    if (this._connected || this._connecting || this._manuallyClosed) return;
     this._connecting = true;
     this._setState('connecting', '正在连接 SaaS 网关…');
     try {
-      const tokenInfo = await this._acquireToken();
-      this.deviceToken = tokenInfo.token;
-      this.serverUrl = tokenInfo.gateway?.url || this.gatewayUrl;
-      await this._connectWebSocket();
-      this._startHeartbeat();
-      this.reconnectAttempts = 0;
+      const token = await this._acquireToken();
+      await this._openSocket(token);
+      this._connected = true;
+      this._terminal = false;
+      this._manuallyClosed = false;
+      this._reconnectAttempts = 0;
       this.lastError = null;
-      this.protocolVersion = this.protocolVersion || 2;
+      this.lastAckAt = Date.now();
+      this._startHeartbeat();
       this._setState('ready', this.publicUrl ? `SaaS 隧道已建立 (${this.publicUrl})` : 'SaaS 隧道已建立');
     } catch (err) {
-      this.connected = false;
+      this._connected = false;
       this._stopHeartbeat();
-      const terminal = this._isTerminalError(err) || this._terminal;
       const detail = err?.message ?? String(err);
       this.lastError = detail;
+      const terminal = err?.terminal === true || this._terminal;
       if (terminal) {
         this._terminal = true;
         this._setState('error', detail);
-      } else if (this.disconnecting || this.signal?.aborted) {
-        this._setState('idle', '连接已取消');
-      } else {
+      } else if (!this._manuallyClosed && !this._draining) {
         this._scheduleReconnect(detail);
       }
       throw err;
@@ -239,261 +206,143 @@ export class SaasTunnelClient extends CustomTunnelClient {
     }
   }
 
-  _isTerminalError(err) {
-    if (!err) return false;
-    if (err.terminal === true) return true;
-    return SAAS_TERMINAL_ERROR_CODES.has(String(err.code ?? ''));
-  }
-
   async _acquireToken() {
     if (!this.tokenProvider) {
-      throw new SaasTunnelError('missing_device_credentials', 'SaaS 设备凭证缺失，请重新绑定设备', { terminal: true });
+      throw new SaasTunnelError('missing_device_credentials', '尚未绑定设备，请先在面板获取设备码并绑定', { terminal: true });
     }
     const result = await this.tokenProvider();
     const token = typeof result === 'string' ? result : result?.token;
-    if (!token) {
-      throw new SaasTunnelError('missing_device_token', 'SaaS 设备令牌获取失败，请重新绑定设备', { terminal: true });
-    }
+    if (!token) throw new SaasTunnelError('missing_device_token', '设备令牌获取失败，请重新绑定', { terminal: true });
     if (result && typeof result === 'object') {
-      if (result.gateway?.url) {
-        this.gatewayUrl = result.gateway.url;
-        this.serverUrl = result.gateway.url;
-      }
+      if (result.gateway?.url) this.gatewayUrl = result.gateway.url;
       if (result.gateway?.path) this.gatewayPath = result.gateway.path;
       if (result.tunnel) this.tunnel = result.tunnel;
     }
-    return { token: String(token), gateway: { url: this.gatewayUrl, path: this.gatewayPath } };
+    this.deviceToken = String(token);
+    return this.deviceToken;
   }
 
-  _connectWebSocket() {
+  _openSocket(deviceToken) {
     return new Promise((resolve, reject) => {
-      if (this.signal?.aborted) {
-        reject(new Error('Aborted'));
-        return;
-      }
-
       let ws;
       try {
         ws = new WebSocket(buildSaasConnectUrl({
           gatewayUrl: this.gatewayUrl,
           gatewayPath: this.gatewayPath,
-          deviceToken: this.deviceToken,
+          deviceToken,
         }), {
           handshakeTimeout: 10_000,
-          headers: this.deviceToken ? { authorization: `Bearer ${this.deviceToken}` } : undefined,
-          perMessageDeflate: {
-            clientNoContextTakeover: true,
-            serverNoContextTakeover: true,
-            clientMaxWindowBits: 15,
-            serverMaxWindowBits: 15,
-          },
+          headers: { authorization: `Bearer ${deviceToken}` },
+          perMessageDeflate: false,
         });
       } catch (err) {
         reject(new SaasTunnelError('invalid_gateway_url', err?.message ?? String(err), { terminal: true, cause: err }));
         return;
       }
-      this.ws = ws;
-
-      let settled = false;
-      let handshakeTimer = null;
-      let handshakeHandler = null;
-      const cleanupHandshake = () => {
-        if (handshakeTimer) {
-          clearTimeout(handshakeTimer);
-          handshakeTimer = null;
-        }
-        if (handshakeHandler) {
-          ws.off('message', handshakeHandler);
-          handshakeHandler = null;
-        }
-        this.signal?.removeEventListener?.('abort', onAbort);
-      };
-      const settle = (err) => {
-        if (settled) return;
-        settled = true;
-        cleanupHandshake();
-        if (err) reject(err);
-        else resolve();
-      };
-      const onAbort = () => {
+      this._ws = ws;
+      this._awaitingHandshake = true;
+      this._handshakeResolve = resolve;
+      this._handshakeReject = reject;
+      this._handshakeTimer = setTimeout(() => {
+        if (!this._awaitingHandshake) return;
         try { ws.terminate(); } catch {}
-        settle(new Error('Aborted'));
-      };
-      this.signal?.addEventListener?.('abort', onAbort, { once: true });
+        this._settleHandshake(new SaasTunnelError('handshake_timeout', 'SaaS 网关握手超时（15s 内未收到 hello-ack）'));
+      }, SAAS_HANDSHAKE_TIMEOUT_MS);
 
       ws.on('open', () => {
-        this.logger?.info?.('SaaS tunnel WebSocket connected');
+        this.logger?.info?.('SaaS tunnel WebSocket open');
         this._sendHello();
       });
-
-      ws.on('message', (data) => this._handleMessage(data));
-
-      handshakeHandler = (data) => {
-        let msg;
-        try {
-          msg = JSON.parse(typeof data === 'string' ? data : data.toString());
-        } catch {
-          return;
-        }
-        if (msg?.type === 'hello-ack') {
-          if (msg.ok === false) {
-            const code = String(msg.error?.code ?? 'bad_request');
-            const message = String(msg.error?.message ?? '');
-            const detail = `SaaS 网关拒绝握手: ${message || code} (${code})`;
-            if (SAAS_TERMINAL_ERROR_CODES.has(code)) {
-              this._terminal = true;
-              this.lastError = detail;
-              this._setState('error', detail);
-              try { ws.terminate(); } catch {}
-              settle(new SaasTunnelError(code, detail, { terminal: true }));
-              return;
-            }
-            try { ws.terminate(); } catch {}
-            settle(new SaasTunnelError(code, detail));
-            return;
-          }
-          this._handleHelloAck(msg);
-          settle();
-          return;
-        }
-        if (msg?.type === 'ready' && !settled) {
-          if (this.protocol === 'v2') return;
-          // auto 兼容：老网关只发 ready（v1 行为）→ 按 v1 继续，不改写状态机
-          this.protocolVersion = 1;
-          this.publicUrl = String(msg.publicUrl ?? '') || this.publicUrl;
-          this.connected = true;
-          this.logger?.warn?.('SaaS tunnel ready without hello-ack, falling back to protocol v1');
-          settle();
-        }
-      };
-      ws.on('message', handshakeHandler);
-
-      ws.on('close', (code, reason) => {
-        this.connected = false;
-        this._stopHeartbeat();
-        this._cleanupLocalWs();
-        const reasonText = reason?.toString?.() ?? '';
-        if (SAAS_TERMINAL_CLOSE_CODES.has(code)) {
-          this._terminal = true;
-          const detail = `SaaS 网关关闭连接 (${code}${reasonText ? `: ${reasonText}` : ''})，请重新绑定设备`;
-          this.lastError = detail;
-          this._setState('error', detail);
-          settle(new SaasTunnelError('connection_closed', detail, { terminal: true, closeCode: code }));
-          return;
-        }
-        if (!settled) {
-          settle(new SaasTunnelError('connection_closed', `SaaS 网关在握手完成前断开 (code=${code})`, { closeCode: code }));
-          return;
-        }
-        if (this.signal?.aborted || this.disconnecting || this._draining) return;
-        this.logger?.warn?.('SaaS tunnel disconnected: code=%d, reason=%s', code, reasonText);
-        this.lastError = `SaaS 网关连接已断开 (code=${code})`;
-        this._scheduleReconnect(this.lastError);
-      });
-
+      ws.on('message', (data) => this._onMessage(data));
+      ws.on('close', (code, reason) => this._onClose(code, reason));
       ws.on('error', (err) => {
-        this.logger?.error?.('SaaS tunnel WebSocket error: %s', err?.message ?? err);
-        if (!settled) settle(err);
+        this.logger?.error?.(`SaaS tunnel WebSocket error: ${err?.message ?? err}`);
+        if (this._awaitingHandshake) this._settleHandshake(err instanceof Error ? err : new Error(String(err)));
       });
-
-      handshakeTimer = setTimeout(() => {
-        if (settled) return;
-        try { ws.terminate(); } catch {}
-        settle(new SaasTunnelError('handshake_timeout', 'SaaS 网关握手超时（15s 内未收到 hello-ack）'));
-      }, SAAS_HANDSHAKE_TIMEOUT_MS);
     });
   }
 
+  _settleHandshake(error) {
+    if (!this._awaitingHandshake) return;
+    this._awaitingHandshake = false;
+    if (this._handshakeTimer) {
+      clearTimeout(this._handshakeTimer);
+      this._handshakeTimer = null;
+    }
+    const resolve = this._handshakeResolve;
+    const reject = this._handshakeReject;
+    this._handshakeResolve = null;
+    this._handshakeReject = null;
+    if (error) reject?.(error);
+    else resolve?.();
+  }
+
   _sendHello() {
     const device = {};
     for (const key of ['name', 'platform', 'hostname', 'pluginVersion', 'dshVersion']) {
       const value = this.deviceInfo?.[key];
       if (value !== undefined && value !== null && String(value).trim()) device[key] = String(value).trim();
     }
-    if (!device.name) device.name = device.hostname || 'DSH Bridge';
-    if (!device.platform) device.platform = normalizeDevicePlatform(undefined);
-    const hello = {
+    if (!device.name) device.name = device.hostname || 'DSH Remote Tunnel';
+    if (!device.platform) device.platform = process.platform ?? 'unknown';
+    this._send({
       type: 'hello',
       v: 2,
       device,
-      caps: {
-        sseStreaming: Boolean(this.sseStreaming),
-        wsFrames: true,
-        maxResponseBytes: 32 * 1024 * 1024,
-        ...(this.caps ?? {}),
-      },
+      caps: { sseStreaming: this.sseStreaming, wsFrames: true, maxResponseBytes: this.maxResponseBytes },
       ts: Math.floor(Date.now() / 1000),
-    };
-    this.logger?.info?.('SaaS tunnel hello sent (device=%s)', device.name);
-    this._sendMessage(hello);
-  }
-
-  _handleHelloAck(msg) {
-    this.protocolVersion = Number(msg?.v) || 2;
-    this.sessionId = msg?.sessionId ?? null;
-    if (msg?.tunnel) {
-      this.tunnel = {
-        publicId: String(msg.tunnel.publicId ?? ''),
-        name: String(msg.tunnel.name ?? ''),
-      };
-    }
-    this.limits = msg?.limits ?? null;
-    this.features = msg?.features ?? null;
-    this.serverTime = msg?.serverTime ?? null;
-    if (this.limits?.heartbeatMs) {
-      this.heartbeatIntervalMs = Math.max(10, Number(this.limits.heartbeatMs) || this.heartbeatIntervalMs);
-    }
-    this._applyRoutes(msg?.routes);
-    this.connected = true;
-    this.reconnectAttempts = 0;
-    this.lastAckAt = Date.now();
-    this.onHelloAck?.(msg);
-    this.logger?.info?.('SaaS tunnel hello-ack ok (publicId=%s, routes=%d)', this.tunnel?.publicId ?? '', this.routes.length);
-  }
-
-  _applyRoutes(routes) {
-    const list = Array.isArray(routes) ? routes.filter((route) => route && typeof route === 'object') : [];
-    this.routes = list;
-    const hostRoute = list.find((route) => route.kind === 'host' && typeof route.url === 'string' && route.url);
-    const picked = hostRoute ?? list.find((route) => typeof route.url === 'string' && route.url);
-    if (picked) {
-      this.publicUrl = String(picked.url);
-      this._publicUrlLockedByRoutes = Boolean(hostRoute);
-    }
-    return list;
+    });
   }
 
-  _handleMessage(data) {
+  _onMessage(data) {
     let msg;
     try {
       msg = JSON.parse(typeof data === 'string' ? data : data.toString());
-    } catch (err) {
-      this.logger?.error?.('Failed to parse SaaS tunnel message: %s', err?.message ?? err);
+    } catch {
+      return;
+    }
+    if (!msg || typeof msg !== 'object') return;
+
+    if (msg.type === 'hello-ack') {
+      if (this._awaitingHandshake) this._handleHelloAck(msg);
+      else if (msg.ok === false) this.logger?.warn?.('ignoring duplicate hello-ack');
+      return;
+    }
+    if (msg.type === 'ready' && this._awaitingHandshake && this.protocol === 'auto') {
+      this.protocolVersion = 1;
+      this.publicUrl = String(msg.publicUrl ?? '');
+      this._connected = true;
+      this._settleHandshake();
       return;
     }
-    switch (msg?.type) {
+    switch (msg.type) {
       case 'heartbeat-ack':
-        this._handleHeartbeatAck(msg);
+        this._heartbeatAckPending = false;
+        this._missedHeartbeatAcks = 0;
+        this.lastAckAt = Date.now();
+        if (msg.serverTime) this.serverTime = msg.serverTime;
+        if (Array.isArray(msg.actions) && msg.actions.includes('drain') && !this._draining) {
+          this._startDrain({ deadline: Date.now() + this.heartbeatIntervalMs * 3 });
+        }
         return;
       case 'route-update':
-        this._handleRouteUpdate(msg);
+        this._routeRev = Number(msg.rev) || this._routeRev;
+        this._applyRoutes(msg.routes);
+        try { this.onRouteUpdate?.({ routes: this._routes, rev: this._routeRev, publicUrl: this.publicUrl }); } catch {}
         return;
       case 'drain':
         this._handleDrain(msg);
         return;
-      case 'ping':
-        this._sendMessage({ type: 'pong', ts: Date.now() });
-        return;
-      case 'hello-ack':
       case 'ready':
-      case 'pong':
-        // 握手由一次性 handler 负责；运行期重复的 hello-ack/ready 不改变已建立状态
-        if (msg.type === 'ready' && this.connected && !this._publicUrlLockedByRoutes) {
+        if (this._connected && !this._routes.some((route) => route.kind === 'host')) {
           if (msg.publicUrl) this.publicUrl = String(msg.publicUrl);
         }
         return;
+      case 'ping':
+        this._send({ type: 'pong', ts: Date.now() });
+        return;
       case 'request':
-        this._handleHttpRequest(msg);
+        this._handleRequest(msg);
         return;
       case 'ws-open':
         this._handleWsOpen(msg);
@@ -504,192 +353,405 @@ export class SaasTunnelClient extends CustomTunnelClient {
       case 'ws-close':
         this._handleWsClose(msg);
         return;
+      case 'pong':
+        return;
       default:
         // 未知 type 必须静默忽略（v1 前后兼容）
         return;
     }
   }
 
-  _handleHeartbeatAck(msg) {
-    this._awaitingHeartbeatAck = false;
-    this._missedHeartbeatAcks = 0;
-    this.lastAckAt = Date.now();
-    if (msg?.serverTime) this.serverTime = msg.serverTime;
-    const actions = Array.isArray(msg?.actions) ? msg.actions : [];
-    if (actions.includes('drain') && !this._draining) {
-      this._startDrain({ deadline: Date.now() + this.heartbeatIntervalMs * 3 });
+  _handleHelloAck(msg) {
+    if (msg.ok === false) {
+      const code = String(msg.error?.code ?? 'bad_request');
+      const message = String(msg.error?.message ?? '');
+      const detail = `SaaS 网关拒绝握手: ${message || code} (${code})`;
+      const terminal = SAAS_TERMINAL_ERROR_CODES.has(code);
+      this.lastError = detail;
+      if (terminal) this._terminal = true;
+      this._setState(terminal ? 'error' : 'connecting', detail);
+      try { this._ws?.terminate(); } catch {}
+      this._settleHandshake(new SaasTunnelError(code, detail, { terminal }));
+      return;
     }
+    this.protocolVersion = Number(msg.v) || 2;
+    if (msg.tunnel) this.tunnel = { publicId: String(msg.tunnel.publicId ?? ''), name: String(msg.tunnel.name ?? '') };
+    this.limits = msg.limits ?? null;
+    this.features = msg.features ?? null;
+    this.serverTime = msg.serverTime ?? null;
+    if (this.limits?.heartbeatMs) this.heartbeatIntervalMs = Math.max(10, Number(this.limits.heartbeatMs) || this.heartbeatIntervalMs);
+    if (this.limits?.maxResponseBytes) this.maxResponseBytes = Math.max(1024, Number(this.limits.maxResponseBytes) || this.maxResponseBytes);
+    this._applyRoutes(msg.routes);
+    this._connected = true;
+    this._reconnectAttempts = 0;
+    this.lastAckAt = Date.now();
+    try { this.onHelloAck?.(msg); } catch {}
+    this._settleHandshake();
   }
 
-  _handleRouteUpdate(msg) {
-    this.routeRev = Number(msg?.rev) || this.routeRev;
-    this._applyRoutes(msg?.routes);
-    this.logger?.info?.('SaaS tunnel route updated (rev=%s, publicUrl=%s)', this.routeRev, this.publicUrl ?? '');
-    this.onRouteUpdate?.({ routes: this.routes, rev: this.routeRev, publicUrl: this.publicUrl });
+  _applyRoutes(routes) {
+    const list = Array.isArray(routes) ? routes.filter((route) => route && typeof route === 'object') : [];
+    this._routes = list;
+    const picked = pickRoutePublicUrl(list);
+    if (picked) this.publicUrl = picked;
   }
 
   _handleDrain(msg) {
     let deadline = Number(msg?.deadline);
     if (!Number.isFinite(deadline) || deadline <= 0) deadline = Date.now() + this.heartbeatIntervalMs * 3;
-    else if (deadline < 1e12) deadline *= 1000; // 秒级时间戳
+    else if (deadline < 1e12) deadline *= 1000;
     this._startDrain({ deadline });
   }
 
-  _startDrain({ deadline } = {}) {
+  _startDrain({ deadline }) {
     if (this._draining) return;
     this._draining = true;
-    const deadlineMs = Number.isFinite(deadline) && deadline > 0 ? deadline : Date.now() + this.heartbeatIntervalMs * 3;
-    this._setState('draining', 'SaaS 网关正在下线，等待在途请求结束后断开');
-    this.onDrain?.({ deadline: deadlineMs });
-    this.logger?.info?.('SaaS tunnel draining (deadline=%s, inFlight=%d)', deadlineMs, this._requestsInFlight.size);
-    const poll = () => {
-      if (this._drainFinished) return;
-      if (this._requestsInFlight.size === 0 || Date.now() >= deadlineMs) {
-        this._finishDrain();
-        return;
-      }
-      const waitMs = Math.min(250, Math.max(20, deadlineMs - Date.now()));
-      this._drainTimer = setTimeout(poll, waitMs);
-    };
-    this._drainTimer = setTimeout(poll, 20);
-    this._drainDeadlineTimer = setTimeout(() => this._finishDrain(), Math.max(0, deadlineMs - Date.now()) + 1000);
+    this._setState('draining', 'SaaS 网关下线中，等待在途请求结束');
+    try { this.onDrain?.({ deadline }); } catch {}
+    const finish = () => this._finishDrain();
+    if (this._inFlight.size === 0) {
+      this._drainTimer = setTimeout(finish, 20);
+    } else {
+      const poll = () => {
+        if (!this._draining) return;
+        if (this._inFlight.size === 0 || Date.now() >= deadline) return finish();
+        this._drainTimer = setTimeout(poll, Math.min(100, Math.max(10, deadline - Date.now())));
+      };
+      this._drainTimer = setTimeout(poll, 20);
+      setTimeout(() => { if (this._draining) finish(); }, Math.max(0, deadline - Date.now()) + 1000).unref?.();
+    }
   }
 
   _finishDrain() {
-    if (this._drainFinished) return;
-    this._drainFinished = true;
-    this._clearDrainTimers();
-    this.connected = false;
+    if (!this._draining) return;
+    this._draining = false;
+    this._suppressReconnect = true;
+    if (this._drainTimer) { clearTimeout(this._drainTimer); this._drainTimer = null; }
+    this._connected = false;
     this._stopHeartbeat();
     this._cleanupLocalWs();
-    this._requestsInFlight.clear();
-    const detail = 'SaaS 网关已下线（drain），隧道已优雅断开';
-    this.lastError = detail;
-    this._setState('closed', detail);
-    this.onDrainComplete?.({ detail });
-    try { this.ws?.close(1000, 'drain'); } catch { try { this.ws?.terminate(); } catch {} }
-  }
-
-  _clearDrainTimers() {
-    if (this._drainTimer) {
-      clearTimeout(this._drainTimer);
-      this._drainTimer = null;
-    }
-    if (this._drainDeadlineTimer) {
-      clearTimeout(this._drainDeadlineTimer);
-      this._drainDeadlineTimer = null;
-    }
+    this._inFlight.clear();
+    this.lastError = 'SaaS 网关已下线（drain），隧道已优雅断开';
+    this._setState('closed', this.lastError);
+    try { this.onDrainComplete?.({ detail: this.lastError }); } catch {}
+    this._closeSocket(1000, 'drain');
   }
 
-  // ── 转发语义复用父类，仅补计数/在途/drain 拒绝 ─────────────────────────
-  _handleHttpRequest(msg) {
+  _handleRequest(msg) {
+    const requestId = String(msg?.requestId ?? '');
+    if (!requestId) return;
     if (this._draining) {
-      this._sendMessage({
-        type: 'response',
-        requestId: msg?.requestId,
-        statusCode: 503,
-        headers: { 'content-type': 'text/plain; charset=utf-8' },
-        body: Buffer.from('tunnel is draining').toString('base64'),
-      });
+      this._send({ type: 'response', requestId, statusCode: 503, headers: { 'content-type': 'text/plain; charset=utf-8' }, body: Buffer.from('tunnel is draining').toString('base64') });
       return;
     }
-    if (msg?.requestId) this._requestsInFlight.add(msg.requestId);
-    if (typeof msg?.body === 'string' && msg.body) {
-      this._bytesIn += Math.floor((msg.body.length * 3) / 4);
-    }
-    super._handleHttpRequest(msg);
+    this._inFlight.add(requestId);
+    if (typeof msg.body === 'string') this._bytesIn += Math.floor((msg.body.length * 3) / 4);
+    const headers = sanitizeHeaders(msg.headers);
+    headers.host = `127.0.0.1:${this.localPort}`;
+    if (this.internalTunnelSecret) headers[TUNNEL_HEADER] = this.internalTunnelSecret;
+
+    const upstream = httpRequest({
+      host: '127.0.0.1',
+      port: this.localPort,
+      method: String(msg.method ?? 'GET'),
+      path: String(msg.path ?? '/'),
+      headers,
+    }, (res) => {
+      const responseHeaders = sanitizeHeaders(res.headers);
+      const isSse = String(res.headers['content-type'] ?? '').toLowerCase().includes('text/event-stream');
+      if (isSse && this.sseStreaming) {
+        this._send({ type: 'response-start', requestId, statusCode: res.statusCode ?? 200, headers: responseHeaders });
+        res.on('data', (chunk) => {
+          this._bytesOut += chunk.length;
+          this._send({ type: 'response-chunk', requestId, body: Buffer.from(chunk).toString('base64') });
+        });
+        res.on('end', () => {
+          this._send({ type: 'response-end', requestId });
+          this._inFlight.delete(requestId);
+        });
+        res.on('error', () => {
+          this._send({ type: 'response-end', requestId });
+          this._inFlight.delete(requestId);
+        });
+        return;
+      }
+      const chunks = [];
+      let total = 0;
+      let finished = false;
+      const fail = (code, text) => {
+        if (finished) return;
+        finished = true;
+        this._inFlight.delete(requestId);
+        this._send({ type: 'response', requestId, statusCode: code, headers: { 'content-type': 'text/plain; charset=utf-8' }, body: Buffer.from(text).toString('base64') });
+      };
+      res.on('data', (chunk) => {
+        total += chunk.length;
+        if (total > this.maxResponseBytes) {
+          fail(502, `Response too large for tunnel (>${Math.round(this.maxResponseBytes / 1024 / 1024)}MB cap)`);
+          res.destroy();
+          return;
+        }
+        chunks.push(chunk);
+      });
+      res.on('end', () => {
+        if (finished) return;
+        finished = true;
+        this._inFlight.delete(requestId);
+        const body = Buffer.concat(chunks).toString('base64');
+        this._bytesOut += Buffer.concat(chunks).length;
+        this._send({ type: 'response', requestId, statusCode: res.statusCode ?? 200, headers: responseHeaders, body });
+      });
+      res.on('error', () => fail(502, 'Response Error'));
+    });
+    upstream.on('error', (err) => {
+      this._inFlight.delete(requestId);
+      this._send({ type: 'response', requestId, statusCode: 502, headers: { 'content-type': 'text/plain; charset=utf-8' }, body: Buffer.from(`Bad Gateway: ${err?.message ?? err}`).toString('base64') });
+    });
+    if (typeof msg.body === 'string' && msg.body) upstream.write(Buffer.from(msg.body, 'base64'));
+    upstream.end();
   }
 
+  // ── WebSocket 原始帧转发 ────────────────────────────────────────────────
+  // 网关契约（apps/gateway/src/proxy-ws.ts）：ws-frame 的 data 是**原始 WebSocket 帧字节**
+  // （含 opcode/mask/分片），不是消息 payload。因此这里用裸 TCP 完成 Upgrade 握手后
+  // 原样透传字节，绝不能再经 ws 库二次成帧。
   _handleWsOpen(msg) {
+    const wsId = String(msg?.wsId ?? '');
+    if (!wsId) return;
     if (this._draining) {
-      this._sendMessage({
-        type: 'ws-accept',
-        wsId: msg?.wsId,
-        statusCode: 503,
-        statusMessage: 'Service Unavailable',
-        replyHeaders: { 'content-type': 'text/plain' },
-      });
+      this._send({ type: 'ws-accept', wsId, statusCode: 503, statusMessage: 'Service Unavailable', replyHeaders: { 'content-type': 'text/plain' } });
       return;
     }
-    super._handleWsOpen(msg);
-  }
+    // Upgrade 请求必须原样保留 connection/upgrade/sec-websocket-*（不能套用普通
+    // HTTP 请求的逐跳过滤），只重写 Host 并补本地隧道标记。
+    const requestHeaders = {};
+    for (const [name, value] of Object.entries(msg.headers ?? {})) {
+      const lower = name.toLowerCase();
+      if (lower === 'host' || lower === TUNNEL_HEADER || value === undefined) continue;
+      requestHeaders[lower] = value;
+    }
+    requestHeaders.host = `127.0.0.1:${this.localPort}`;
+    // 网关按 hop-by-hop 规则剥掉了 Upgrade/Connection，这里必须补回，否则本机
+    // WebSocket 升级请求不合法（表现为浏览器收到非 101）。
+    requestHeaders.connection = requestHeaders.connection ?? 'Upgrade';
+    requestHeaders.upgrade = requestHeaders.upgrade ?? 'websocket';
+    if (this.internalTunnelSecret) requestHeaders[TUNNEL_HEADER] = this.internalTunnelSecret;
+
+    const socket = netConnect({ host: '127.0.0.1', port: this.localPort });
+    const state = { socket, buffer: Buffer.alloc(0), upgraded: false, closed: false, headerSent: false };
+    this._localWs.set(wsId, state);
+
+    const fail = (code, message) => {
+      if (state.closed) return;
+      state.closed = true;
+      this._send({ type: 'ws-accept', wsId, statusCode: code, statusMessage: message, replyHeaders: { 'content-type': 'text/plain' } });
+      try { socket.destroy(); } catch {}
+      this._localWs.delete(wsId);
+    };
 
-  _sendMessage(msg) {
-    if (msg && typeof msg === 'object') {
-      if ((msg.type === 'response' || msg.type === 'response-end') && msg.requestId) {
-        this._requestsInFlight.delete(msg.requestId);
-      }
-      if (typeof msg.body === 'string' && msg.body) {
-        this._bytesOut += Math.floor((msg.body.length * 3) / 4);
+    socket.on('connect', () => {
+      const path = String(msg.path ?? '/');
+      const lines = [`GET ${path.startsWith('/') ? path : '/' + path} HTTP/1.1`];
+      for (const [name, value] of Object.entries(requestHeaders)) {
+        if (Array.isArray(value)) for (const item of value) lines.push(`${name}: ${item}`);
+        else if (value !== undefined) lines.push(`${name}: ${value}`);
       }
-      if (typeof msg.data === 'string' && msg.data) {
-        this._bytesOut += Math.floor((msg.data.length * 3) / 4);
+      lines.push('', '');
+      state.headerSent = true;
+      socket.write(lines.join('\r\n'));
+    });
+
+    socket.on('data', (chunk) => {
+      if (state.closed) return;
+      if (!state.upgraded) {
+        state.buffer = Buffer.concat([state.buffer, chunk]);
+        const separator = state.buffer.indexOf('\r\n\r\n');
+        if (separator === -1) {
+          if (state.buffer.length > 64 * 1024) fail(502, 'Bad Gateway');
+          return;
+        }
+        const head = state.buffer.subarray(0, separator).toString('latin1');
+        const rest = state.buffer.subarray(separator + 4);
+        state.buffer = Buffer.alloc(0);
+        state.upgraded = true;
+        const [statusLine, ...headerLines] = head.split('\r\n');
+        const match = /^HTTP\/1\.[01]\s+(\d{3})\s*(.*)$/.exec(statusLine ?? '');
+        const statusCode = match ? Number(match[1]) : 101;
+        const statusMessage = match ? match[2] : '';
+        const replyHeaders = {};
+        for (const line of headerLines) {
+          const index = line.indexOf(':');
+          if (index <= 0) continue;
+          replyHeaders[line.slice(0, index).trim().toLowerCase()] = line.slice(index + 1).trim();
+        }
+        if (statusCode !== 101) {
+          state.closed = true;
+          this.logger?.warn?.('local WS upgrade rejected: %s %s', statusCode, statusMessage);
+          this._send({ type: 'ws-accept', wsId, statusCode, statusMessage, replyHeaders });
+          try { socket.destroy(); } catch {}
+          this._localWs.delete(wsId);
+          return;
+        }
+        this._send({ type: 'ws-accept', wsId, statusCode: 101, replyHeaders });
+        if (rest.length > 0) this._send({ type: 'ws-frame', wsId, data: rest.toString('base64') });
+        return;
       }
+      this._send({ type: 'ws-frame', wsId, data: chunk.toString('base64') });
+    });
+
+    const finish = () => {
+      if (state.closed) return;
+      state.closed = true;
+      this._localWs.delete(wsId);
+      this._send({ type: 'ws-close', wsId });
+    };
+    socket.on('close', finish);
+    socket.on('error', finish);
+  }
+
+  /** 网关下发的 ws-frame 是原始帧字节：直接写入本地 TCP，不能经 ws 库重编码。 */
+  _handleWsFrame(msg) {
+    const state = this._localWs.get(String(msg?.wsId ?? ''));
+    if (!state || state.closed || !state.upgraded) return;
+    const data = Buffer.from(String(msg?.data ?? ''), 'base64');
+    this._bytesIn += data.length;
+    try { state.socket.write(data); } catch { /* 忽略单帧写入失败，close 会收敛 */ }
+  }
+
+  _handleWsClose(msg) {
+    const wsId = String(msg?.wsId ?? '');
+    const state = this._localWs.get(wsId);
+    if (!state) return;
+    state.closed = true;
+    this._localWs.delete(wsId);
+    try { state.socket.destroy(); } catch {}
+  }
+
+  _cleanupLocalWs() {
+    for (const state of this._localWs.values()) {
+      state.closed = true;
+      try { state.socket.destroy(); } catch {}
     }
-    super._sendMessage(msg);
+    this._localWs.clear();
   }
 
-  _heartbeatState() {
-    return {
-      requestsInFlight: this._requestsInFlight.size,
-      wsOpen: this.localWsSockets.size,
-      bytesIn: this._bytesIn,
-      bytesOut: this._bytesOut,
-      ...(this.lastError ? { lastError: String(this.lastError).slice(0, 500) } : {}),
-    };
+  _send(message) {
+    if (!this._ws || this._ws.readyState !== WebSocket.OPEN) return;
+    try { this._ws.send(JSON.stringify(message)); } catch (err) {
+      this.logger?.warn?.(`SaaS tunnel send failed: ${err?.message ?? err}`);
+    }
   }
 
   _heartbeatTick() {
-    if (!this.connected || this._draining) return;
-    if (this._awaitingHeartbeatAck) {
+    if (!this._connected || this._draining) return;
+    if (this._heartbeatAckPending) {
       this._missedHeartbeatAcks += 1;
       if (this._missedHeartbeatAcks >= this.heartbeatMaxMissed) {
         const detail = `SaaS 网关心跳连续 ${this._missedHeartbeatAcks} 次未确认，主动重连`;
         this.lastError = detail;
         this._setState('reconnecting', detail);
         this._stopHeartbeat();
-        try { this.ws?.terminate(); } catch {}
+        try { this._ws?.terminate(); } catch {}
         return;
       }
     }
-    this._awaitingHeartbeatAck = true;
-    this._sendMessage({ type: 'heartbeat', ts: Date.now(), state: this._heartbeatState() });
+    this._heartbeatAckPending = true;
+    this._send({
+      type: 'heartbeat',
+      ts: Date.now(),
+      state: {
+        requestsInFlight: this._inFlight.size,
+        wsOpen: this._localWs.size,
+        bytesIn: this._bytesIn,
+        bytesOut: this._bytesOut,
+        ...(this.lastError ? { lastError: String(this.lastError).slice(0, 500) } : {}),
+      },
+    });
   }
 
   _startHeartbeat() {
     this._stopHeartbeat();
+    this._heartbeatAckPending = false;
     this._missedHeartbeatAcks = 0;
-    this._awaitingHeartbeatAck = false;
-    this.heartbeatTimer = setInterval(() => this._heartbeatTick(), this.heartbeatIntervalMs);
+    this._heartbeatTimer = setInterval(() => this._heartbeatTick(), this.heartbeatIntervalMs);
+    this._heartbeatTimer.unref?.();
     this._heartbeatTick();
   }
 
-  _scheduleReconnect(reason) {
-    if (this.signal?.aborted || this.disconnecting || this._terminal || this._draining) return;
-    if (this.reconnectTimer) return;
-    if (Number.isFinite(this.maxReconnectAttempts) && this.reconnectAttempts >= this.maxReconnectAttempts) {
-      const detail = `SaaS 隧道重连已达上限 (${this.maxReconnectAttempts} 次)`;
+  _stopHeartbeat() {
+    if (this._heartbeatTimer) {
+      clearInterval(this._heartbeatTimer);
+      this._heartbeatTimer = null;
+    }
+  }
+
+  _onClose(code, reason) {
+    this._connected = false;
+    this._stopHeartbeat();
+    this._cleanupLocalWs();
+    this._inFlight.clear();
+    const reasonText = reason?.toString?.() ?? '';
+    if (SAAS_TERMINAL_CLOSE_CODES.has(code)) {
+      this._terminal = true;
+      const detail = `SaaS 网关关闭连接 (${code}${reasonText ? `: ${reasonText}` : ''})，请重新绑定设备`;
       this.lastError = detail;
       this._setState('error', detail);
+      if (this._awaitingHandshake) {
+        this._settleHandshake(new SaasTunnelError('connection_closed', detail, { terminal: true, closeCode: code }));
+      }
+      return;
+    }
+    if (this._awaitingHandshake) {
+      this._settleHandshake(new SaasTunnelError('connection_closed', `SaaS 网关在握手完成前断开 (code=${code})`, { closeCode: code }));
+      return;
+    }
+    if (this._manuallyClosed || this._draining || this._suppressReconnect) return;
+    const detail = `SaaS 网关连接已断开 (code=${code})`;
+    this.lastError = detail;
+    this._scheduleReconnect(detail);
+  }
+
+  _scheduleReconnect(reason) {
+    if (this._manuallyClosed || this._draining || this._terminal) return;
+    if (this._reconnectTimer) return;
+    if (Number.isFinite(this.maxReconnectAttempts) && this._reconnectAttempts >= this.maxReconnectAttempts) {
+      this.lastError = `SaaS 隧道重连已达上限 (${this.maxReconnectAttempts} 次)`;
+      this._setState('error', this.lastError);
       return;
     }
-    this.reconnectAttempts += 1;
-    const attempt = this.reconnectAttempts;
-    const baseDelay = Math.min(this.reconnectBaseDelayMs * 2 ** (attempt - 1), this.reconnectMaxDelayMs);
-    const jitter = 0.75 + this._random() * 0.5;
-    const delay = Math.max(50, Math.round(baseDelay * jitter));
-    const seconds = Math.round((delay / 1000) * 10) / 10;
-    this._setState('reconnecting', `SaaS 隧道断开${reason ? `：${reason}` : ''}，${seconds}s 后重连（第 ${attempt} 次）`);
-    this.reconnectTimer = setTimeout(() => {
-      this.reconnectTimer = null;
-      this.connect().catch(() => {});
+    this._reconnectAttempts += 1;
+    const attempt = this._reconnectAttempts;
+    const base = Math.min(this.reconnectBaseDelayMs * 2 ** (attempt - 1), this.reconnectMaxDelayMs);
+    const delay = Math.max(20, Math.round(base * (0.75 + this.random() * 0.5)));
+    this._setState('reconnecting', `SaaS 隧道断开${reason ? `：${reason}` : ''}，${Math.round(delay / 100) / 10}s 后重连（第 ${attempt} 次）`);
+    this._reconnectTimer = setTimeout(() => {
+      this._reconnectTimer = null;
+      this.connect().catch((err) => {
+        if (err?.terminal === true) this._setState('error', err.message);
+      });
     }, delay);
+    this._reconnectTimer.unref?.();
   }
 
-  disconnect() {
-    this._clearDrainTimers();
-    this._drainFinished = true;
-    this._requestsInFlight.clear();
-    super.disconnect();
+  _closeSocket(code = 1000, reason = '') {
+    const ws = this._ws;
+    this._ws = null;
+    if (!ws) return;
+    try { ws.close(code, reason); } catch {}
+    setTimeout(() => { try { ws.terminate(); } catch {} }, 1000).unref?.();
+  }
+
+  async disconnect() {
+    this._manuallyClosed = true;
+    this._draining = false;
+    this._connected = false;
+    if (this._reconnectTimer) { clearTimeout(this._reconnectTimer); this._reconnectTimer = null; }
+    if (this._drainTimer) { clearTimeout(this._drainTimer); this._drainTimer = null; }
+    this._stopHeartbeat();
+    if (this._awaitingHandshake) this._settleHandshake(new SaasTunnelError('disconnected', '连接已取消'));
+    this._cleanupLocalWs();
+    this._inFlight.clear();
+    this._closeSocket(1000, 'client disconnect');
+    this._setState('idle', '已断开');
   }
 }