@muyichengshayu/promptx 0.1.10 → 0.1.12

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.1.12
+
+- Relay 新增按天聚合的租户使用统计，自动记录设备连接与真实转发请求，方便查看“今天有哪些同事实际用了 Relay”。
+- 新增 Relay 管理统计页 `/relay/admin/usage` 与对应接口，可直接查看今日活跃租户、连接次数、请求次数、最近设备与最近活跃时间。
+- 统计能力默认落在云端 Relay 侧，不依赖本地 PromptX client 升级；同时补充文档说明与服务端测试覆盖。
+
+## 0.1.11
+
+- 加固 Relay 自动重连恢复链路：固定间隔重连升级为指数退避，并在连接成功后重置重连计数，减少 Relay 重启或网络抖动时的无效重试。
+- 补齐 Relay client 健康检查与自愈能力：新增心跳超时巡检、假死连接主动重连，以及类似 Mac 休眠/唤醒后的时间跳变检测，避免远程页面断开后必须手动保存设置才能恢复。
+- 修复 Relay client 旧连接 `close` 回调误伤新连接的竞态问题，避免在 Windows 等时序下反复出现“旧设备连接被新连接替换”的重连循环。
+- 对 `invalid_token`、`invalid_device`、`invalid_tenant` 等不可恢复错误改为暂停自动重连，并在状态里明确暴露暂停原因，方便快速定位配置问题。
+- 设置页“远程”增加“立即重连”按钮，并补充等待重连 / 已暂停重连等状态反馈，便于手动触发恢复和远程排障。
+- 新增 Relay 重连相关服务端与接口测试，覆盖拒绝后暂停、重连成功清零、心跳超时自愈、休眠恢复近似场景和手动重连。
+- 调整左侧任务列表为固定创建顺序，不再因运行、保存、自动刷新或 `updatedAt` 变化跳动；同时修复慢网切换任务时旧草稿标题短暂显示到新任务上的问题。
+
 ## 0.1.10
 
 - 重构执行链路为 `server + runner` 双进程架构：`server` 专注 HTTP API、任务/项目存储与 SSE，`runner` 专注 agent 子进程生命周期、事件流、stop/kill/超时回收，显著降低长任务拖垮主服务的风险。

package/apps/server/src/relayClient.js

@@ -9,9 +9,17 @@ import {
   sanitizeProxyHeaders,
 } from './relayProtocol.js'
 
-const DEFAULT_RECONNECT_DELAY_MS = 3_000
+const DEFAULT_RECONNECT_DELAYS_MS = [1_000, 2_000, 5_000, 10_000, 30_000]
+const DEFAULT_HEALTH_CHECK_INTERVAL_MS = 10_000
+const DEFAULT_HEARTBEAT_TIMEOUT_MS = 65_000
+const DEFAULT_SLEEP_RESUME_THRESHOLD_MS = 45_000
 const MAX_RECENT_EVENTS = 200
 const REQUEST_CANCEL_REASON = 'relay_request_cancelled'
+const NON_RETRYABLE_CLOSE_REASONS = new Set([
+  'invalid_tenant',
+  'invalid_token',
+  'invalid_device',
+])
 
 function createDisabledStatus() {
   return {
@@ -27,6 +35,9 @@ function createDisabledStatus() {
     lastCloseReason: '',
     lastError: '',
     reconnectCount: 0,
+    reconnectPaused: false,
+    reconnectPausedReason: '',
+    nextReconnectDelayMs: 0,
     recentEvents: [],
   }
 }
@@ -51,6 +62,22 @@ function normalizeCloseReason(reason = '') {
   return reasonMap[normalized] || normalized
 }
 
+function parseCloseReason(reason = '') {
+  const rawReason = Buffer.isBuffer(reason)
+    ? reason.toString('utf8').trim()
+    : String(reason || '').trim()
+
+  return {
+    rawReason,
+    closeReason: normalizeCloseReason(rawReason),
+  }
+}
+
+function getReconnectDelayMs(reconnectCount = 0) {
+  const normalizedCount = Math.max(1, Number(reconnectCount) || 1)
+  return DEFAULT_RECONNECT_DELAYS_MS[Math.min(normalizedCount - 1, DEFAULT_RECONNECT_DELAYS_MS.length - 1)]
+}
+
 function readRelayClientConfig({
   relayUrl = process.env.PROMPTX_RELAY_URL,
   deviceId = process.env.PROMPTX_RELAY_DEVICE_ID,
@@ -85,6 +112,12 @@ function createRelayClient({
   localBaseUrl,
   logger = console,
   appVersion = '0.0.0',
+  createWebSocket = (url) => new WebSocket(url),
+  reconnectDelayStrategy = getReconnectDelayMs,
+  healthCheckIntervalMs = DEFAULT_HEALTH_CHECK_INTERVAL_MS,
+  heartbeatTimeoutMs = DEFAULT_HEARTBEAT_TIMEOUT_MS,
+  sleepResumeThresholdMs = DEFAULT_SLEEP_RESUME_THRESHOLD_MS,
+  getNow = () => Date.now(),
 } = {}) {
   let config = readRelayClientConfig({
     relayUrl,
@@ -104,8 +137,12 @@ function createRelayClient({
   let socket = null
   let stopped = false
   let reconnectTimer = null
+  let healthCheckTimer = null
   let requestMap = new Map()
   let authenticated = false
+  let pendingReconnectSource = ''
+  let lastHealthCheckTickAt = 0
+  let connectionSequence = 0
 
   function updateStatus(patch = {}) {
     Object.assign(status, patch)
@@ -113,7 +150,7 @@ function createRelayClient({
 
   function appendRecentEvent(type, extra = {}) {
     const nextEvent = {
-      at: new Date().toISOString(),
+      at: new Date(getNow()).toISOString(),
       type: String(type || '').trim() || 'unknown',
       ...extra,
     }
@@ -163,6 +200,60 @@ function createRelayClient({
     logger.error?.(message)
   }
 
+  function nowIso() {
+    return new Date(getNow()).toISOString()
+  }
+
+  function clearReconnectTimer() {
+    if (reconnectTimer) {
+      clearTimeout(reconnectTimer)
+      reconnectTimer = null
+    }
+  }
+
+  function clearHealthCheckTimer() {
+    if (healthCheckTimer) {
+      clearInterval(healthCheckTimer)
+      healthCheckTimer = null
+    }
+  }
+
+  function resetReconnectState() {
+    updateStatus({
+      reconnectCount: 0,
+      reconnectPaused: false,
+      reconnectPausedReason: '',
+      nextReconnectDelayMs: 0,
+    })
+  }
+
+  function getHeartbeatAgeMs(now = getNow()) {
+    const lastHeartbeatAt = Date.parse(status.lastHeartbeatAt || status.lastConnectedAt || '')
+    if (!Number.isFinite(lastHeartbeatAt)) {
+      return Number.POSITIVE_INFINITY
+    }
+    return Math.max(0, now - lastHeartbeatAt)
+  }
+
+  function shouldPauseReconnect(rawReason = '') {
+    return NON_RETRYABLE_CLOSE_REASONS.has(String(rawReason || '').trim())
+  }
+
+  function pauseReconnect(rawReason = '') {
+    const reason = normalizeCloseReason(rawReason)
+    updateStatus({
+      reconnectPaused: true,
+      reconnectPausedReason: reason || String(rawReason || '').trim(),
+      nextReconnectDelayMs: 0,
+    })
+    appendRecentEvent('reconnect_paused', {
+      reason: reason || String(rawReason || '').trim() || 'unknown',
+    })
+    logWarn('[relay] 检测到不可重试错误，已暂停自动重连', getLogContext({
+      reason: reason || String(rawReason || '').trim() || 'unknown',
+    }))
+  }
+
   syncStatusFromConfig()
 
   function sendFrame(payload = {}) {
@@ -313,43 +404,142 @@ function createRelayClient({
     }
   }
 
-  function scheduleReconnect() {
-    if (stopped || reconnectTimer || !config.enabled) {
+  function connectWithRetry(source = 'start') {
+    return connect().catch((error) => {
+      updateStatus({
+        lastError: error?.message || 'Relay 连接失败。',
+      })
+      appendRecentEvent('connect_failed', {
+        source,
+        reconnectCount: Number(status.reconnectCount || 0),
+        error: error?.message || String(error || ''),
+      })
+      logError('[relay] 连接失败', getLogContext({
+        source,
+        reconnectCount: Number(status.reconnectCount || 0),
+        error: error?.message || String(error || ''),
+      }))
+      scheduleReconnect({ source })
+    })
+  }
+
+  function scheduleReconnect({ source = 'close' } = {}) {
+    if (stopped || reconnectTimer || !config.enabled || status.reconnectPaused) {
       return
     }
 
     const nextReconnectCount = Number(status.reconnectCount || 0) + 1
+    const reconnectInMs = Math.max(100, Number(reconnectDelayStrategy(nextReconnectCount)) || getReconnectDelayMs(nextReconnectCount))
     updateStatus({
       reconnectCount: nextReconnectCount,
+      nextReconnectDelayMs: reconnectInMs,
     })
     appendRecentEvent('reconnect_scheduled', {
-      reconnectInMs: DEFAULT_RECONNECT_DELAY_MS,
+      reconnectInMs,
       reconnectCount: nextReconnectCount,
       authenticated,
+      source,
     })
     logWarn('[relay] 已计划重连', getLogContext({
-      reconnectInMs: DEFAULT_RECONNECT_DELAY_MS,
+      reconnectInMs,
       reconnectCount: nextReconnectCount,
       authenticated,
+      source,
     }))
 
     reconnectTimer = setTimeout(() => {
       reconnectTimer = null
-      connect().catch((error) => {
-        updateStatus({
-          lastError: error?.message || 'Relay 连接失败。',
+      connectWithRetry(`reconnect:${source}`)
+    }, reconnectInMs)
+    reconnectTimer.unref?.()
+  }
+
+  function triggerReconnect(source = 'manual') {
+    if (stopped || !config.enabled) {
+      return false
+    }
+
+    clearReconnectTimer()
+    updateStatus({
+      reconnectPaused: false,
+      reconnectPausedReason: '',
+      nextReconnectDelayMs: 0,
+      lastError: '',
+    })
+    pendingReconnectSource = source
+    appendRecentEvent('reconnect_requested', {
+      source,
+      socketReadyState: socket?.readyState ?? 3,
+    })
+    logInfo('[relay] 收到重连请求', getLogContext({
+      source,
+      socketReadyState: socket?.readyState ?? 3,
+    }))
+
+    if (!socket || socket.readyState === WebSocket.CLOSED) {
+      pendingReconnectSource = ''
+      connectWithRetry(source)
+      return true
+    }
+
+    try {
+      if (socket.readyState === WebSocket.CONNECTING || socket.readyState === WebSocket.OPEN) {
+        socket.terminate()
+      } else {
+        socket.close(1012, `${source}_reconnect`)
+      }
+    } catch {
+      socket = null
+      authenticated = false
+      pendingReconnectSource = ''
+      connectWithRetry(source)
+    }
+
+    return true
+  }
+
+  function runHealthCheck() {
+    if (stopped || !config.enabled) {
+      return
+    }
+
+    const now = getNow()
+    const previousTickAt = lastHealthCheckTickAt
+    lastHealthCheckTickAt = now
+
+    if (previousTickAt > 0) {
+      const elapsedSinceLastTick = now - previousTickAt
+      if (elapsedSinceLastTick > sleepResumeThresholdMs) {
+        appendRecentEvent('system_resume_detected', {
+          elapsedMs: elapsedSinceLastTick,
         })
-        appendRecentEvent('reconnect_failed', {
-          reconnectCount: Number(status.reconnectCount || 0),
-          error: error?.message || String(error || ''),
+        logInfo('[relay] 检测到系统挂起/恢复，开始检查连接健康状态', getLogContext({
+          elapsedMs: elapsedSinceLastTick,
+          socketReadyState: socket?.readyState ?? 3,
+          connected: status.connected,
+        }))
+      }
+    }
+
+    if (socket?.readyState === WebSocket.OPEN && authenticated) {
+      const heartbeatAgeMs = getHeartbeatAgeMs(now)
+      if (heartbeatAgeMs > heartbeatTimeoutMs) {
+        appendRecentEvent('heartbeat_stale', {
+          heartbeatAgeMs,
+          heartbeatTimeoutMs,
         })
-        logError('[relay] 重连失败', getLogContext({
-          reconnectCount: Number(status.reconnectCount || 0),
-          error: error?.message || String(error || ''),
+        logWarn('[relay] 心跳已过期，准备主动重连', getLogContext({
+          heartbeatAgeMs,
+          heartbeatTimeoutMs,
         }))
-        scheduleReconnect()
-      })
-    }, DEFAULT_RECONNECT_DELAY_MS)
+        triggerReconnect('heartbeat_timeout')
+        return
+      }
+    }
+
+    if (!socket && !reconnectTimer && !status.connected && !status.reconnectPaused) {
+      scheduleReconnect({ source: 'health_check_idle' })
+    }
   }
 
   async function connect() {
@@ -362,10 +552,15 @@ function createRelayClient({
 
     appendRecentEvent('connect_start')
     logInfo('[relay] 开始连接', getLogContext())
-    socket = new WebSocket(config.websocketUrl)
+    const currentSocket = createWebSocket(config.websocketUrl)
+    const connectionId = ++connectionSequence
+    socket = currentSocket
     authenticated = false
 
-    socket.on('open', () => {
+    currentSocket.on('open', () => {
+      if (socket !== currentSocket) {
+        return
+      }
       appendRecentEvent('ws_open')
       sendFrame({
         type: 'hello',
@@ -373,10 +568,15 @@ function createRelayClient({
         deviceToken: config.deviceToken,
         version: appVersion,
       })
-      logInfo('[relay] WebSocket 已建立，等待设备认证', getLogContext())
+      logInfo('[relay] WebSocket 已建立，等待设备认证', getLogContext({
+        connectionId,
+      }))
     })
 
-    socket.on('message', (payload, isBinary) => {
+    currentSocket.on('message', (payload, isBinary) => {
+      if (socket !== currentSocket) {
+        return
+      }
       if (isBinary) {
         return
       }
@@ -390,10 +590,11 @@ function createRelayClient({
 
       if (message?.type === 'hello.ack') {
         authenticated = true
+        resetReconnectState()
         updateStatus({
           connected: true,
-          lastConnectedAt: new Date().toISOString(),
-          lastHeartbeatAt: new Date().toISOString(),
+          lastConnectedAt: nowIso(),
+          lastHeartbeatAt: nowIso(),
           lastCloseCode: 0,
           lastCloseReason: '',
           lastError: '',
@@ -401,10 +602,12 @@ function createRelayClient({
         appendRecentEvent('auth_ok', {
           tenantKey: String(message?.tenantKey || '').trim(),
           reconnectCount: Number(status.reconnectCount || 0),
+          connectionId,
         })
         logInfo('[relay] 设备认证成功，连接已就绪', getLogContext({
           tenantKey: String(message?.tenantKey || '').trim(),
           reconnectCount: Number(status.reconnectCount || 0),
+          connectionId,
         }))
         return
       }
@@ -412,28 +615,49 @@ function createRelayClient({
       handleIncomingFrame(JSON.stringify(message))
     })
 
-    socket.on('ping', () => {
+    currentSocket.on('ping', () => {
+      if (socket !== currentSocket) {
+        return
+      }
       updateStatus({
-        lastHeartbeatAt: new Date().toISOString(),
+        lastHeartbeatAt: nowIso(),
       })
     })
 
-    socket.on('pong', () => {
+    currentSocket.on('pong', () => {
+      if (socket !== currentSocket) {
+        return
+      }
       updateStatus({
-        lastHeartbeatAt: new Date().toISOString(),
+        lastHeartbeatAt: nowIso(),
       })
     })
 
-    socket.on('close', (code, reason) => {
+    currentSocket.on('close', (code, reason) => {
+      if (socket !== currentSocket) {
+        appendRecentEvent('stale_close_ignored', {
+          code: Number(code || 0),
+          reason: parseCloseReason(reason).closeReason || '',
+          connectionId,
+        })
+        logInfo('[relay] 已忽略旧连接的 close 事件', getLogContext({
+          code: Number(code || 0),
+          connectionId,
+        }))
+        return
+      }
+
       const wasAuthenticated = authenticated
-      const closeReason = normalizeCloseReason(reason?.toString('utf8'))
+      const reconnectSource = pendingReconnectSource
+      pendingReconnectSource = ''
+      const { rawReason, closeReason } = parseCloseReason(reason)
       const nextError = closeReason && closeReason !== '配置已更新，正在重连'
         ? `${wasAuthenticated ? 'Relay 已断开' : 'Relay 连接被拒绝'}：${closeReason}`
         : (!wasAuthenticated && code && code !== 1000 ? `Relay 连接已关闭（code=${code}）` : '')
 
       updateStatus({
         connected: false,
-        lastDisconnectedAt: new Date().toISOString(),
+        lastDisconnectedAt: nowIso(),
         lastCloseCode: Number(code || 0),
         lastCloseReason: closeReason,
         ...(nextError ? { lastError: nextError } : {}),
@@ -441,7 +665,10 @@ function createRelayClient({
       appendRecentEvent('close', {
         code: Number(code || 0),
         reason: closeReason || '',
+        rawReason: rawReason || '',
         authenticated: wasAuthenticated,
+        reconnectSource: reconnectSource || '',
+        connectionId,
       })
       socket = null
       authenticated = false
@@ -449,19 +676,37 @@ function createRelayClient({
         code: Number(code || 0),
         reason: closeReason || 'none',
         authenticated: wasAuthenticated,
+        reconnectSource: reconnectSource || '',
+        connectionId,
       }))
-      scheduleReconnect()
+
+      if (reconnectSource) {
+        connectWithRetry(reconnectSource)
+        return
+      }
+
+      if (shouldPauseReconnect(rawReason)) {
+        pauseReconnect(rawReason)
+        return
+      }
+
+      scheduleReconnect({ source: rawReason || 'close' })
     })
 
-    socket.on('error', (error) => {
+    currentSocket.on('error', (error) => {
+      if (socket !== currentSocket) {
+        return
+      }
       updateStatus({
         lastError: error?.message || 'Relay 连接失败。',
       })
       appendRecentEvent('error', {
         error: error?.message || String(error || ''),
+        connectionId,
       })
       logWarn('[relay] 连接异常', getLogContext({
         error: error?.message || String(error || ''),
+        connectionId,
       }))
     })
   }
@@ -469,6 +714,8 @@ function createRelayClient({
   return {
     start() {
       stopped = false
+      clearReconnectTimer()
+      clearHealthCheckTimer()
       if (!config.enabled) {
         syncStatusFromConfig()
         appendRecentEvent('disabled')
@@ -476,34 +723,29 @@ function createRelayClient({
         return
       }
 
-      connect().catch((error) => {
-        updateStatus({
-          lastError: error?.message || 'Relay 连接失败。',
-        })
-        appendRecentEvent('connect_failed', {
-          error: error?.message || String(error || ''),
-        })
-        logError('[relay] 初次连接失败', getLogContext({
-          error: error?.message || String(error || ''),
-        }))
-        scheduleReconnect()
-      })
+      lastHealthCheckTickAt = getNow()
+      healthCheckTimer = setInterval(() => {
+        runHealthCheck()
+      }, Math.max(20, Number(healthCheckIntervalMs) || DEFAULT_HEALTH_CHECK_INTERVAL_MS))
+      healthCheckTimer.unref?.()
+
+      connectWithRetry('start')
     },
     stop() {
       stopped = true
-      if (reconnectTimer) {
-        clearTimeout(reconnectTimer)
-        reconnectTimer = null
-      }
+      clearReconnectTimer()
+      clearHealthCheckTimer()
       requestMap.forEach((record) => {
         record.controller?.abort()
       })
       requestMap = new Map()
+      pendingReconnectSource = ''
       socket?.close()
       socket = null
       authenticated = false
       updateStatus({
         connected: false,
+        nextReconnectDelayMs: 0,
       })
       appendRecentEvent('stopped')
       logInfo('[relay] 已停止', getLogContext())
@@ -517,6 +759,9 @@ function createRelayClient({
       syncStatusFromConfig()
       updateStatus({
         lastError: '',
+        reconnectPaused: false,
+        reconnectPausedReason: '',
+        nextReconnectDelayMs: 0,
       })
       appendRecentEvent('config_updated', {
         previousEnabled,
@@ -543,6 +788,9 @@ function createRelayClient({
         this.start()
       }
     },
+    reconnect() {
+      return triggerReconnect('manual')
+    },
     getStatus() {
       return {
         ...status,
@@ -557,5 +805,6 @@ function createRelayClient({
 export {
   createDisabledStatus,
   createRelayClient,
+  getReconnectDelayMs,
   readRelayClientConfig,
 }