import { pollCourseware } from './courseware.js'; import { spawn } from 'node:child_process'; import os from 'node:os'; import fs from 'node:fs'; import path from 'node:path'; import { BrowserWindow, app } from 'electron'; import { CLIENT_COMMAND_LABELS, CLIENT_HEARTBEAT_INTERVAL_MS, isNewerVersion, type ClientCommandDto, type ApiResponse, type ClientCommandKind, type ClientHeartbeatRequest, type ClientHeartbeatResponse, type ClientUpdateInfoDto, } from '@classhelper/shared'; import { maybeInstallPendingUpdate, considerUpdate, syncUpdatePolicy } from './auto-update.js'; import { connectionEvents, type ConnectionEvent } from './config-events.js'; import { getConfig } from './config.js'; import { island } from './island.js'; import { logger } from './logger.js'; /** * 桌面客户端的服务端联动代理(心跳上报)。 * * **为什么是"客户端定时拉"而不是服务端推**:教室机的连接经常断(代理、休眠、重启), * 而「这台机器是什么版本、要不要更新、有没有待执行命令」必须下次上线就能补上 —— 所以统一用 * 「服务端记状态 + 客户端定时上报」的范式,不引入新的长连接握手。 * 每次上报的响应里同时带回「服务端指定的目标版本 + 待执行命令」。 * * 三条边界: * 1. **没有 token 就不上报**:未登录时静默跳过(登录后下一次自然就上报了), * 不能拿空令牌去打服务端,否则日志里会刷满 401; * 2. **401/403 退避到 5 分钟**:令牌可能已失效(班级密码被改 / 令牌过期), * 继续 30 秒一次只是白刷服务端与日志; * 3. **冒烟模式默认不上报**:每次冒烟都在服务端库里造一条设备记录没有意义, * 只有显式 `ELECTRON_SMOKE_CLIENT_AGENT=1` 时才照常跑(给需要验证这条链路的用例用)。 */ /** 启动后第一次上报的延迟:等窗口、登录流程与灵动岛都就绪,也不跟首屏抢带宽 */ const FIRST_BEAT_DELAY_MS = 3_000; /** 令牌失效(401/403)后的退避间隔:5 分钟一次,直到用户重新登录 */ const UNAUTHORIZED_BACKOFF_MS = 5 * 60_000; /** 单次上报的超时:教室机网络慢,但也不能挂着不放 */ const HEARTBEAT_TIMEOUT_MS = 10_000; /** * 「在线」判定窗口:与 shared 的 `CLIENT_ONLINE_WINDOW_MS`(90 秒)同口径 —— * 连续丢两次心跳(30 秒 × 3)才算离线。这里不复用那个常量是因为它属于**服务端**的判定口径, * 客户端展示的是"我这边的上报还新不新",单独留一个本地常量更容易看出两边的关系。 */ const ONLINE_WINDOW_MS = 90_000; /** 对外暴露的联动状态(设置页「服务端联动状态」与冒烟断言用) */ export interface ClientAgentStatus { /** 设备标识尾号(服务端设备列表里显示的那串用来对账,完整 UUID 不上界面) */ deviceKeyTail: string; /** 最近一次上报成功的时刻(ISO 字符串;从未上报过为 null) */ lastHeartbeatAt: string | null; /** 最近一次失败的原因(空串 = 最近一次是成功的) */ lastError: string; /** 已下载待安装的版本(空串 = 无) */ pendingUpdateVersion: string; /** 服务端最近一次要求升到的版本(空串 = 没要求) */ updateTargetVersion: string; /** 是否接受服务端统一下发的自动更新(配置值,供设置页回显) */ autoUpdate: boolean; /** 最近 90 秒内上报成功过(与服务端的在线口径一致) */ online: boolean; } interface AgentState { running: boolean; /** 当前心跳定时器(退避期间与正常节奏共用它) */ timer: ReturnType | null; /** 正在上报:避免手动「立即上报」与定时器撞在一起 */ beating: boolean; lastHeartbeatAt: string | null; lastError: string; updateTargetVersion: string; } const state: AgentState = { running: false, timer: null, beating: false, lastHeartbeatAt: null, lastError: '', updateTargetVersion: '', }; /** 设备标识尾号:取后 8 位(足够对账,又不至于把完整 UUID 贴到界面上) */ export function deviceKeyTail(deviceKey: string): string { const trimmed = deviceKey.trim(); if (!trimmed) return ''; return trimmed.length > 8 ? trimmed.slice(-8) : trimmed; } /** 冒烟模式且没有显式打开联动开关时,一律不上报(避免每次冒烟都在库里造设备记录) */ function isAgentSuppressed(): boolean { return process.env.ELECTRON_SMOKE_TEST === '1' && process.env.ELECTRON_SMOKE_CLIENT_AGENT !== '1'; } /** * 上报里的"这台机器现在在干什么"。 * * 取值就三种(服务端设备列表直接展示这段文字): * - `上课中` —— 灵动岛按渲染进程上报的课表状态判定正在上课(延后策略此时不安装更新); * - `使用中` —— 主窗口可见,人正在用; * - `待机` —— 窗口隐藏(最小化到托盘),机器空闲。 */ function currentStateNote(): string { if (island.getState().inClass) return '上课中'; const win = BrowserWindow.getAllWindows().find((item) => !item.isDestroyed()); return win?.isVisible() ? '使用中' : '待机'; } /** 已下载待安装的版本;没有则 null(服务端把它记进设备的 `pendingVersion`) */ function pendingVersionOrNull(): string | null { const pending = getConfig().pendingUpdateVersion.trim(); return pending ? pending : null; } /** 清掉待执行的心跳定时器(幂等) */ function clearTimer(): void { if (state.timer !== null) { clearTimeout(state.timer); state.timer = null; } } /** 排下一次上报;`delayMs` 不传时用正常节奏 */ function scheduleNext(delayMs: number = CLIENT_HEARTBEAT_INTERVAL_MS): void { if (!state.running) return; clearTimer(); state.timer = setTimeout(() => { state.timer = null; void beat(); }, delayMs); } /** * 一次上报(含响应处理)。 * * 失败一律**不抛**:网络抖动是教室机的常态,只记一行日志并按原节奏重试; * 只有 401/403 才退避(见文件头说明)。 */ async function beat(): Promise { if (state.beating) return; if (isAgentSuppressed()) { // 冒烟模式:照原节奏空转(不碰服务端,也不在库里造设备记录) state.lastError = ''; scheduleNext(); return; } const config = getConfig(); const token = config.token?.trim() ?? ''; if (!token) { // 未登录:不打服务端、不记错误,等下次心跳(登录后自然会带上令牌) logger.debug('客户端上报:尚未登录(没有令牌),本次跳过'); scheduleNext(); return; } const epoch = connectionEpoch; state.beating = true; let backoff = false; try { const body: ClientHeartbeatRequest = { agentProtocol: 2, deviceKey: config.deviceKey, name: os.hostname(), clientVersion: app.getVersion(), platform: `${process.platform}-${process.arch}`, autoUpdate: config.autoUpdate !== false, pendingVersion: pendingVersionOrNull(), stateNote: currentStateNote(), }; const response = await fetch(`${config.serverUrl}/api/clients/heartbeat`, { method: 'POST', headers: { 'content-type': 'application/json', authorization: `Bearer ${token}`, }, body: JSON.stringify(body), signal: AbortSignal.timeout(HEARTBEAT_TIMEOUT_MS), }); if (epoch !== connectionEpoch) return; if (response.status === 401 || response.status === 403) { // 令牌失效:退避到 5 分钟一次,直到用户重新登录 backoff = true; state.lastError = `上报被拒绝(HTTP ${response.status}),可能登录已过期,请重新登录`; logger.warn(`客户端上报:服务端返回 HTTP ${response.status},退避为 5 分钟一次`); return; } if (!response.ok) { state.lastError = `服务端返回 HTTP ${response.status}`; logger.warn(`客户端上报失败:HTTP ${response.status}(${HEARTBEAT_INTERVAL_TEXT})`); return; } const envelope = (await response.json()) as ApiResponse; if (!envelope.success || !envelope.data?.deviceId) throw new Error('心跳响应格式不正确'); if (epoch !== connectionEpoch) return; const payload = envelope.data; void pollCourseware(); state.lastHeartbeatAt = new Date().toISOString(); state.lastError = ''; state.updateTargetVersion = payload.updateTargetVersion?.trim() ?? ''; logger.debug( `客户端上报成功(设备尾号 ${deviceKeyTail(config.deviceKey)},状态 ${body.stateNote ?? '-'}` + `${state.updateTargetVersion ? `,服务端要求升到 ${state.updateTargetVersion}` : ''})`, ); void handleCommand(payload.command).catch((error) => logger.error(`远控处理失败:${String(error)}`)); // 下载不能阻塞心跳,否则慢速下载期间远控和在线状态都会失效。 syncUpdatePolicy(payload); void handleUpdate(payload.update, payload.updateTargetVersion).catch((error) => logger.error(`更新处理失败:${String(error)}`), ); } catch (error) { // 网络错误 / 超时 / JSON 解析失败:按原节奏重试 if (epoch !== connectionEpoch) return; state.lastError = error instanceof Error ? error.message : String(error); logger.warn(`客户端上报失败(将于 ${HEARTBEAT_INTERVAL_TEXT} 后重试):${state.lastError}`); } finally { state.beating = false; // 每次心跳后检查已下载的更新是否满足安装策略。 void maybeInstallPendingUpdate(); scheduleNext( epoch !== connectionEpoch ? 0 : backoff ? UNAUTHORIZED_BACKOFF_MS : CLIENT_HEARTBEAT_INTERVAL_MS, ); } } const HEARTBEAT_INTERVAL_TEXT = `${Math.round(CLIENT_HEARTBEAT_INTERVAL_MS / 1000)} 秒`; /** * 服务端下发的远控命令(关机 / 重启 / 注销 / 锁屏)。 * * 按产品要求收到即执行,保留十分钟有效期、持久去重与设备归属校验。 * 执行结果必须回执;网络失败只重试回执,不重复执行。 * 冒烟在执行器处强制返回假结果,永不调用系统命令。 */ const inFlightCommands = new Set(); type CommandOutcome = { ok: boolean; result: string }; const commandResults = new Map(); let resultsLoaded = false; function commandResultsPath(): string { return path.join(app.getPath('userData'), 'command-results.json'); } function readCommandResults(): void { if (resultsLoaded) return; try { const entries: unknown = JSON.parse(fs.readFileSync(commandResultsPath(), 'utf8')); if (Array.isArray(entries)) for (const entry of entries.slice(-200)) { if ( Array.isArray(entry) && typeof entry[0] === 'string' && typeof entry[1]?.ok === 'boolean' && typeof entry[1]?.result === 'string' ) commandResults.set(entry[0], entry[1]); } } catch { /* 首次运行尚无记录 */ } resultsLoaded = true; } function rememberCommand(commandId: string, outcome: CommandOutcome): void { readCommandResults(); commandResults.set(commandId, outcome); while (commandResults.size > 200) commandResults.delete(commandResults.keys().next().value!); fs.mkdirSync(app.getPath('userData'), { recursive: true }); fs.writeFileSync(commandResultsPath(), JSON.stringify([...commandResults]), 'utf8'); } async function handleCommand(command: ClientCommandDto | null): Promise { if (!command) return; const commandConfig = getConfig(); const label = CLIENT_COMMAND_LABELS[command.kind] ?? command.kind; const expired = command.expiresAt !== null && Number.isFinite(Date.parse(command.expiresAt)) ? Date.parse(command.expiresAt) < Date.now() : false; if (expired) { logger.warn(`收到已过期的远控命令(${label}),已忽略:${command.payload || '无备注'}`); return; } // 正在执行时不能用预存的中间结果抢先回执。 if (inFlightCommands.has(command.id)) return; // 处理过但回执没送达:只重试回执 readCommandResults(); const pending = commandResults.get(command.id); if (pending) { await ackCommand(command.id, pending.ok, pending.result, commandConfig); return; } inFlightCommands.add(command.id); try { // 注销可能立刻结束本进程,先落盘,重启后不能再次执行同一条指令。 rememberCommand(command.id, { ok: false, result: '已提交系统执行,最终结果未回传,请核对设备状态', }); if (getConfig().serverUrl !== commandConfig.serverUrl || getConfig().token !== commandConfig.token) return; const outcome = await executeCommand(command.kind); logger.warn(`远控命令「${label}」执行${outcome.ok ? '成功' : '失败'}:${outcome.result}`); await ackCommand(command.id, outcome.ok, outcome.result, commandConfig); } finally { inFlightCommands.delete(command.id); } } /** 执行系统命令:只支持 Windows(本项目客户端只发 Windows 版) */ async function executeCommand(kind: ClientCommandKind): Promise<{ ok: boolean; result: string }> { if (process.env.ELECTRON_SMOKE_TEST === '1') return { ok: true, result: '冒烟假执行器:已接收,未调用系统命令' }; if (!['shutdown', 'restart', 'logoff', 'lock'].includes(kind)) return { ok: false, result: '未知的远控动作' }; if (process.platform !== 'win32') return { ok: false, result: '仅支持 Windows' }; const commands: Record = { shutdown: { file: 'shutdown.exe', args: ['/s', '/t', '5'] }, restart: { file: 'shutdown.exe', args: ['/r', '/t', '5'] }, logoff: { file: 'shutdown.exe', args: ['/l'] }, lock: { file: 'rundll32.exe', args: ['user32.dll,LockWorkStation'] }, }; const plan = commands[kind]; try { // 关机/重启预留 5 秒用于回执;检查系统命令进程的真实退出码。 const child = spawn(plan.file, plan.args, { detached: true, stdio: 'ignore', windowsHide: true }); /** * **必须监听 `error` 事件**:`spawn` 找不到可执行文件(或没权限)时不是抛异常,而是在 * next tick 上发一个 `error` 事件 —— 只包 `try/catch` 的话,这种情况会一路走到 * `return { ok: true }`,回执写着"已下达系统命令",Web 端看起来一切正常,机器却纹丝不动。 * 同时检查非零退出码,系统拒绝指令时不能回报成功。 */ return await new Promise((resolve) => { child.once('error', (error) => resolve({ ok: false, result: error.message })); child.once('exit', (code) => resolve({ ok: code === 0, result: code === 0 ? '系统已接受指令' : `系统命令执行失败(退出码 ${code ?? '未知'})`, }), ); }); } catch (error) { return { ok: false, result: error instanceof Error ? error.message : String(error) }; } } /** 回执:服务端用 body 里的 deviceKey 校验"这条命令是发给这台机器的" */ async function ackCommand( commandId: string, ok: boolean, result: string, config: ReturnType, ): Promise { rememberCommand(commandId, { ok, result }); // 回执始终发给接收命令时的服务器,切换实例不能把旧命令带到新实例。 if (!config.token) return; try { const response = await fetch(`${config.serverUrl}/api/clients/commands/${commandId}/ack`, { method: 'POST', headers: { 'content-type': 'application/json', authorization: `Bearer ${config.token}` }, body: JSON.stringify({ deviceKey: config.deviceKey, ok, result }), signal: AbortSignal.timeout(HEARTBEAT_TIMEOUT_MS), }); if (!response.ok) { logger.warn(`远控命令回执失败(HTTP ${response.status}),将在下次心跳重试`); return; } logger.info(`远控命令回执已送达(${ok ? '成功' : '失败'}):${result}`); } catch (error) { logger.warn( `远控命令回执失败(${error instanceof Error ? error.message : String(error)}),将在下次心跳重试`, ); } } /** 响应里的更新信息:服务端指定了目标版本、且该版本确实比本机新,才交给 auto-update */ async function handleUpdate(info: ClientUpdateInfoDto | null, targetVersion: string | null): Promise { const target = targetVersion?.trim() ?? ''; if (!target) return; if (!info) { // 服务端指定了目标版本但还没有这份安装包:只记一行,客户端只能提示手动更新 logger.warn(`服务端要求升到 ${target},但服务端还没有这个版本的安装包(无法自动下载)`); return; } if (!isNewerVersion(app.getVersion(), target)) return; await considerUpdate(info, target); } let connectionEpoch = 0; /** 显式身份事件清除旧服务端退避;旧请求返回也不得覆盖新服务器状态。 */ export function resetClientAgent(reason: ConnectionEvent): void { connectionEpoch++; clearTimer(); state.lastHeartbeatAt = null; state.lastError = ''; state.updateTargetVersion = ''; logger.info(`客户端连接状态已重置:${reason}`); if (state.running && !state.beating) scheduleNext(0); } connectionEvents.on('changed', resetClientAgent); /** 启动心跳(重复调用无副作用) */ export function startClientAgent(): void { if (state.running) return; state.running = true; logger.info( isAgentSuppressed() ? '客户端上报代理:冒烟模式下不上报(需要时设 ELECTRON_SMOKE_CLIENT_AGENT=1)' : `客户端上报代理已启动:${FIRST_BEAT_DELAY_MS / 1000} 秒后首次上报,之后每 ${HEARTBEAT_INTERVAL_TEXT} 一次`, ); scheduleNext(FIRST_BEAT_DELAY_MS); } /** 停止心跳(退出清理调用;幂等) */ export function stopClientAgent(): void { if (!state.running) return; state.running = false; clearTimer(); logger.info('客户端上报代理已停止'); } /** * 手动触发一次上报并返回最新状态(设置页「立即上报」按钮)。 * 返回的是**报告之后**的状态,界面直接照它刷新即可。 */ export async function beatNow(): Promise { if (!state.running) startClientAgent(); if (isAgentSuppressed()) { logger.info('客户端上报:冒烟模式下跳过手动上报'); return getClientAgentStatus(); } clearTimer(); await beat(); return getClientAgentStatus(); } /** 当前联动状态(纯数据,可直接跨 contextBridge 传给渲染进程) */ export function getClientAgentStatus(): ClientAgentStatus { const config = getConfig(); const lastAt = state.lastHeartbeatAt ? Date.parse(state.lastHeartbeatAt) : Number.NaN; return { deviceKeyTail: deviceKeyTail(config.deviceKey), lastHeartbeatAt: state.lastHeartbeatAt, lastError: state.lastError, pendingUpdateVersion: config.pendingUpdateVersion ?? '', updateTargetVersion: state.updateTargetVersion, autoUpdate: config.autoUpdate !== false, online: Number.isFinite(lastAt) && Date.now() - lastAt < ONLINE_WINDOW_MS, }; }