@jacksontian/kite-server 0.1.0

package/server.js

@@ -0,0 +1,921 @@
+#!/usr/bin/env node
+/**
+ * kite 云端信箱 API
+ *
+ * 职责：签名鉴权、任务信箱（手机写入 / Worker 领取）、日志与结果收集、
+ *       Worker 心跳、托管手机端 Web 控制台。
+ *
+ * 依赖：ws（WebSocket）、dingbot（钉钉群机器人）、yaml。其余为 Node 内置模块。Node >= 24。
+ *
+ * 鉴权模型：HMAC-SHA256 请求签名。密钥（API_SECRET）只存在两端，
+ * 永不在网络上传输；HTTP 明文下抓到请求也无法重放（时间窗 + nonce）。
+ *   签名串：方法、路径、时间戳、nonce、请求体 SHA256，五行以换行符连接
+ *   请求头：X-RW-Ts（秒级时间戳）、X-RW-Nonce（随机串）、X-RW-Sig（hex）
+ *   WS 鉴权：首条消息 { type:'auth', ts, nonce, sig }，签名串 "WS\nTS\nNONCE"
+ *   WS 通道：/ws 控制台实时广播 + pty 终端输入上行；/worker/ws Worker 任务通知
+ *            与 pty 会话 IO 中继（session.output 下行广播、session.input 定向转发）。
+ *            有任务即推 task.available，领取仍走 HTTP claim，轮询兜底不丢任务
+ *
+ * 配置文件（--config 传入的 YAML 文件，唯一配置来源，不再读取环境变量；
+ * 字段说明与模板见包内 config.example.yaml）：
+ *   apiSecret          必填，两端共享的签名密钥（强随机 hex，见 README 快速开始）
+ *   port               可选，默认 8787
+ *   dataDir             可选，持久化目录，默认 ~/.kite/data；
+ *                      相对路径相对启动工作目录解析，建议写绝对路径；
+ *                      启动前校验可创建、可写，不满足直接报错退出
+ *   maxTasks           可选，终态任务保留条数，默认 200
+ *   staleRunningSec    可选，running 任务超过该时长且 Worker 离线则判失败，默认 600；
+ *                      pty 交互会话不受此限，由 ptyIdleSec 空闲回收
+ *   sigWindowSec       可选，签名时间窗（秒），默认 300；两端时钟漂移大时可调宽
+ *   ptyIdleSec         可选，pty 会话空闲（Worker 断开且无控制台输入）回收秒数，默认 90
+ *   imWebhook          可选，钉钉群机器人 webhook 地址；配置后任务终态事件以 markdown 推送到群
+ *   imSecret           可选，机器人“加签”安全设置的密钥（SEC 开头）；关键词/白名单模式留空
+ *   imNotifyEvents     可选，触发推送的事件集合（数组）：done|failed|canceled，默认 [failed]
+ */
+
+import http from 'node:http';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { WebSocketServer } from 'ws';
+import DingBot from 'dingbot';
+import { loadServerConfig } from './config.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const {
+  configFile: CONFIG_FILE,
+  apiSecret: API_SECRET,
+  port: PORT,
+  dataDir: DATA_DIR,
+  maxTasks: MAX_TASKS,
+  staleRunningMs: STALE_RUNNING_MS,
+  sigWindowSec: SIG_WINDOW_SEC,
+  ptyIdleMs: PTY_IDLE_MS,
+  imWebhook: IM_WEBHOOK,
+  imSecret: IM_SECRET,
+  imNotifyEvents: IM_NOTIFY_EVENTS,
+} = await loadServerConfig();
+const WEB_DIR = path.join(__dirname, 'web');
+const DB_FILE = path.join(DATA_DIR, 'tasks.json');
+const MAX_LOG_LINES = 2000;
+
+// ---------------------------------------------------------------------------
+// 持久化：单文件 JSON，异步落盘（脏标记 + 节流 + 串行化，全程无同步 IO）
+// ---------------------------------------------------------------------------
+
+const state = { tasks: [], heartbeats: {} };
+
+async function loadState() {
+  let raw;
+  try {
+    raw = await fs.promises.readFile(DB_FILE, 'utf8');
+  } catch {
+    return; // 首次启动，文件尚不存在，从空状态开始
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    state.tasks = Array.isArray(parsed.tasks) ? parsed.tasks : [];
+    state.heartbeats = parsed.heartbeats || {};
+  } catch {
+    // 文件损坏：先备份，避免被后续写盘静默覆盖丢失历史数据
+    console.warn('[server] tasks.json 已损坏，备份后从空状态启动');
+    await fs.promises.rename(DB_FILE, `${DB_FILE}.corrupt-${Date.now()}`).catch(() => {});
+  }
+}
+
+// 只保留最近 MAX_TASKS 个终态任务，进行中的不受影响，防止无限增长
+function pruneFinishedTasks() {
+  const finished = state.tasks.filter((t) => ['done', 'failed', 'canceled'].includes(t.status));
+  if (finished.length > MAX_TASKS) {
+    const cutoff = finished
+      .sort((a, b) => b.finishedAt - a.finishedAt)
+      [MAX_TASKS - 1].finishedAt;
+    state.tasks = state.tasks.filter(
+      (t) => !['done', 'failed', 'canceled'].includes(t.status) || t.finishedAt >= cutoff,
+    );
+  }
+}
+
+// 落盘策略：脏标记 + 300ms 节流合并高频写（心跳/日志上报），串行链防交叠，
+// tmp + rename 原子替换。崩溃最多丢约 300ms 的变更，
+// 卡住的 running 任务由心跳超时回收兜底，可接受。
+let savePending = false;
+let saveTimer = null;
+let savingChain = Promise.resolve();
+
+async function flushSave() {
+  if (!savePending) return;
+  savePending = false; // 先清脏标记再序列化快照；写失败会重新标脏重试
+  pruneFinishedTasks();
+  try {
+    const data = JSON.stringify(state, null, 2);
+    const tmp = DB_FILE + '.tmp';
+    await fs.promises.writeFile(tmp, data);
+    await fs.promises.rename(tmp, DB_FILE);
+  } catch (err) {
+    console.error(`[server] 落盘失败，下次变更时重试: ${err.message}`);
+    scheduleSave();
+  }
+}
+
+function scheduleSave() {
+  savePending = true;
+  if (saveTimer) return;
+  saveTimer = setTimeout(() => {
+    saveTimer = null;
+    savingChain = savingChain.then(flushSave);
+  }, 300).unref();
+}
+
+// 退出前把待写变更落盘（systemd 停服走 SIGTERM）
+for (const sig of ['SIGTERM', 'SIGINT']) {
+  process.on(sig, () => {
+    savingChain.then(flushSave).finally(() => process.exit(0));
+  });
+}
+
+// Worker 崩溃/掉线后，回收卡死在 running 的任务。
+// pty 交互会话例外：时长不可预期，由 PTY_IDLE_SEC 空闲回收（见 sweepPtyIdle）
+function sweepStaleRunning() {
+  const now = Date.now();
+  for (const t of state.tasks) {
+    if (t.status !== 'running' || t.type === 'pty') continue;
+    const hb = t.workerId ? state.heartbeats[t.workerId] : null;
+    const workerAlive = hb && now - hb.at < 90 * 1000;
+    if (!workerAlive && t.startedAt && now - t.startedAt > STALE_RUNNING_MS) {
+      t.status = 'failed';
+      t.finishedAt = now;
+      t.result = { error: 'Worker 离线超时，任务被服务端回收' };
+      t.logs.push('[server] Worker 心跳超时，任务被标记为失败');
+      broadcast({ type: 'task.updated', task: taskSummary(t), result: t.result });
+      notifyIm(t, 'failed');
+    }
+  }
+}
+
+// dataDir 的存在性与可写性已由 config.js 启动校验保证
+await loadState();
+
+// ---------------------------------------------------------------------------
+// 工具函数
+// ---------------------------------------------------------------------------
+
+function timingSafeEqualStr(a, b) {
+  const ha = crypto.createHash('sha256').update(String(a)).digest();
+  const hb = crypto.createHash('sha256').update(String(b)).digest();
+  return crypto.timingSafeEqual(ha, hb);
+}
+
+function json(res, code, body) {
+  const data = JSON.stringify(body);
+  res.writeHead(code, {
+    'Content-Type': 'application/json; charset=utf-8',
+    'Cache-Control': 'no-store',
+  });
+  res.end(data);
+}
+
+// ---------------------------------------------------------------------------
+// 签名鉴权：HMAC-SHA256(密钥, METHOD\nPATH\nTS\nNONCE\nSHA256(BODY))
+// 密钥永不上网；时间窗 + nonce 缓存联合防重放。
+// ---------------------------------------------------------------------------
+
+const seenNonces = new Map(); // nonce -> 过期时间戳(ms)
+
+function pruneNonces(now) {
+  if (seenNonces.size < 10000) return;
+  for (const [nonce, expiry] of seenNonces) {
+    if (expiry < now) seenNonces.delete(nonce);
+  }
+}
+
+// 校验 ts/nonce/签名三元组；通过即消费掉该 nonce。
+// signingParts 为参与签名的各行（不含密钥），body 为原始字节（可为空 Buffer）。
+function verifySignature(signingParts, tsRaw, nonce, sig) {
+  const now = Date.now();
+  if (!tsRaw || !nonce || !sig) {
+    return { ok: false, reason: '缺少签名头 X-RW-Ts/X-RW-Nonce/X-RW-Sig' };
+  }
+  const ts = Number(tsRaw);
+  if (!Number.isFinite(ts)) return { ok: false, reason: `时间戳非法: ${String(tsRaw).slice(0, 32)}` };
+  const skewSec = Math.abs(now / 1000 - ts);
+  if (skewSec > SIG_WINDOW_SEC) {
+    return {
+      ok: false,
+      reason: `时间戳超出 ±${SIG_WINDOW_SEC}s 窗口（偏差 ${Math.round(skewSec)}s；检查客户端时钟）`,
+    };
+  }
+  const nonceStr = String(nonce);
+  if (nonceStr.length < 8 || nonceStr.length > 64) {
+    return { ok: false, reason: 'nonce 长度非法' };
+  }
+  if (seenNonces.has(nonceStr)) {
+    return { ok: false, reason: 'nonce 重复（疑似重放）' };
+  }
+  const signingString = signingParts.join('\n');
+  const expected = crypto.createHmac('sha256', API_SECRET).update(signingString).digest('hex');
+  if (!timingSafeEqualStr(String(sig), expected)) {
+    return { ok: false, reason: '签名不匹配（密钥错误或请求被篡改）' };
+  }
+  seenNonces.set(nonceStr, now + SIG_WINDOW_SEC * 1000);
+  pruneNonces(now);
+  return { ok: true };
+}
+
+function readRawBody(req, limit = 1024 * 1024) {
+  return new Promise((resolve, reject) => {
+    let size = 0;
+    const chunks = [];
+    req.on('data', (chunk) => {
+      size += chunk.length;
+      if (size > limit) {
+        reject(new Error('body too large'));
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on('end', () => resolve(Buffer.concat(chunks)));
+    req.on('error', reject);
+  });
+}
+
+// REST 请求验签：签名覆盖方法、路径、时间戳、nonce 与请求体摘要。
+// 注意：路径用含 query 的完整形式（与客户端签名方式一致，防止改写查询参数）。
+async function verifyRestSignature(req, pathname) {
+  const rawBody = await readRawBody(req);
+  const bodySha = crypto.createHash('sha256').update(rawBody).digest('hex');
+  const result = verifySignature(
+    [req.method, req.url, req.headers['x-rw-ts'], req.headers['x-rw-nonce'], bodySha],
+    req.headers['x-rw-ts'],
+    req.headers['x-rw-nonce'],
+    req.headers['x-rw-sig'],
+  );
+  return { ...result, rawBody };
+}
+
+function parseBody(rawBody) {
+  if (!rawBody || !rawBody.length) return {};
+  try {
+    return JSON.parse(rawBody.toString('utf8'));
+  } catch {
+    const err = new Error('invalid json');
+    err.statusCode = 400;
+    throw err;
+  }
+}
+
+function publicTask(task) {
+  // 不外泄内部字段的浅拷贝
+  return { ...task };
+}
+
+// ---------------------------------------------------------------------------
+// WebSocket 实时推送：控制台通过 /ws 建立长连接，任务变更即时下发；
+// Worker 通过 /worker/ws 建立长连接，仅接收任务到达通知（见下方 workerWss）。
+// 鉴权走连接后的第一条消息（Token 不进 URL，不落日志）。
+// ---------------------------------------------------------------------------
+
+function taskSummary(t) {
+  return {
+    id: t.id,
+    type: t.type,
+    title: t.title,
+    status: t.status,
+    createdAt: t.createdAt,
+    startedAt: t.startedAt,
+    finishedAt: t.finishedAt,
+    workerId: t.workerId,
+    logCount: t.logs.length,
+    ...shellPreview(t),
+  };
+}
+
+// 控制台 shell 视图预览：命令回显行（$ xxx）+ 末尾最多 5 行 stdout。
+// [worker]/[server] 元信息行与空行不算 stdout；控制台默认只展示这些，
+// 其余（元信息、结果 JSON、更早输出）点击展开才可见。
+function shellPreview(t) {
+  let cmd = null;
+  let outLines = 0;
+  const tail = [];
+  for (const line of t.logs) {
+    if (line.startsWith('$ ')) { if (!cmd) cmd = line; continue; }
+    if (line.startsWith('[worker]') || line.startsWith('[server]') || line === '') continue;
+    outLines++;
+    tail.push(line);
+    if (tail.length > 5) tail.shift();
+  }
+  return { cmd, outLines, tail };
+}
+
+function workersSnapshot() {
+  const now = Date.now();
+  return Object.entries(state.heartbeats).map(([id, hb]) => ({
+    workerId: id,
+    hostname: hb.hostname,
+    lastSeenAt: hb.at,
+    online: now - hb.at < 90 * 1000,
+    agents: hb.agents || [],
+  }));
+}
+
+// 已鉴权连接集合（未通过鉴权的 socket 不会进入此集合）
+const wsClients = new Set();
+
+function broadcast(msg) {
+  if (!wsClients.size) return;
+  const data = JSON.stringify(msg);
+  for (const ws of wsClients) ws.send(data);
+}
+
+// 已鉴权的 Worker 通知连接（见下方 /worker/ws）。通知只是加速：
+// Worker 收到后仍走 HTTP claim 原子领取，断线期间由轮询兜底
+const wsWorkers = new Set();
+
+function notifyWorkers() {
+  if (!wsWorkers.size) return;
+  const data = JSON.stringify({ type: 'task.available' });
+  for (const ws of wsWorkers) ws.send(data);
+}
+
+// ---------------------------------------------------------------------------
+// IM 群通知：任务终态事件推送钉钉群机器人（markdown），走 dingbot SDK；
+// 机器人启用“加签”安全设置时由 IM_SECRET 自动完成 timestamp+sign 拼接。
+// 未配置 IM_WEBHOOK 完全静默；发送失败只记日志，绝不抛出影响主链路。
+// ---------------------------------------------------------------------------
+
+const IM_STATUS_META = {
+  done: { icon: '✅', label: '完成' },
+  failed: { icon: '❌', label: '失败' },
+  canceled: { icon: '🚫', label: '已取消' },
+};
+
+const IM_BOT = IM_WEBHOOK ? new DingBot(IM_WEBHOOK, { timeout: 10_000 }, IM_SECRET || undefined) : null;
+
+// 按任务类型提取推送摘要：命令/脚本/prompt/留言，pty 只有项目目录
+function imPayloadBrief(task) {
+  const p = task.payload || {};
+  switch (task.type) {
+    case 'shell':
+      return p.command ? `$ ${String(p.command).trim()}` : '';
+    case 'script': {
+      const args = Array.isArray(p.args) ? p.args.map(String) : [];
+      return p.script ? `${p.script}${args.length ? ` ${args.join(' ')}` : ''}` : '';
+    }
+    case 'agent':
+      return [p.agent ? `Agent: ${p.agent}` : '', p.project ? `项目: ${p.project}` : '', String(p.prompt || '').trim()]
+        .filter(Boolean)
+        .join(' | ');
+    case 'chat':
+      return String(p.message || '').trim();
+    case 'pty':
+      return p.project ? `交互终端（项目：${p.project}）` : '交互终端';
+    default:
+      return '';
+  }
+}
+
+function notifyIm(task, event) {
+  if (!IM_BOT || !IM_NOTIFY_EVENTS.has(event)) return;
+  const meta = IM_STATUS_META[event] || { icon: 'ℹ️', label: event };
+  const fmtTime = (ms) => new Date(ms).toLocaleString('zh-CN', { hour12: false });
+  const fmtDur = (ms) => (ms >= 60_000 ? `${Math.round(ms / 60_000)}分钟` : `${Math.round(ms / 1000)}s`);
+  // 超长内容中间截断，保留首尾
+  const truncate = (s, n) => (s.length > n ? `${s.slice(0, n - 8)} … ${s.slice(-4)}` : s);
+
+  const lines = [
+    `### ${meta.icon} 任务${meta.label}：${task.title || task.type}`,
+    `- 类型：${task.type}`,
+  ];
+  const hb = task.workerId ? state.heartbeats[task.workerId] : null;
+  if (task.workerId) {
+    lines.push(`- Worker：${hb?.hostname ? `${hb.hostname}（${task.workerId}）` : task.workerId}`);
+  }
+  const brief = imPayloadBrief(task);
+  if (brief) lines.push(`- 内容：${truncate(brief, 200)}`);
+  if (task.createdAt) lines.push(`- 创建：${fmtTime(task.createdAt)}`);
+  if (task.startedAt) lines.push(`- 开始：${fmtTime(task.startedAt)}`);
+  if (task.finishedAt) lines.push(`- 结束：${fmtTime(task.finishedAt)}`);
+  if (task.startedAt && task.finishedAt) {
+    lines.push(`- 耗时：${fmtDur(task.finishedAt - task.startedAt)}`);
+  }
+  if (task.result) {
+    const detail = String(task.result.error || JSON.stringify(task.result)).slice(0, 300);
+    if (detail !== '{}') lines.push(`- 结果：${detail}`);
+  }
+  // 日志末尾几行，失败时可直接看到报错上下文
+  const tail = (task.logs || [])
+    .filter((l) => !/^\[(server|worker)\]/.test(l) && l.trim())
+    .slice(-3)
+    .map((l) => truncate(String(l), 150));
+  if (tail.length) lines.push('**日志末尾：**', ...tail.map((l) => `> ${l}`));
+  lines.push(`任务 ID：\`${task.id}\``);
+  // SDK 内部校验钉钉返回的 errcode（关键词/加签拦截、限流等业务错误）并抛错
+  IM_BOT.markdown(`kite 任务${meta.label}`, lines.join('\n'))
+    .catch((err) => console.error(`[server] IM 推送失败（${task.id}）：${err.message}`));
+}
+
+// ---------------------------------------------------------------------------
+// pty 会话中继：taskId -> { ws, tail, lastActiveAt }
+// Worker 上行 session.output -> 追加回看缓冲并广播控制台；
+// 控制台下行 session.input/resize/close -> 定向转发给持有会话的 Worker。
+// 回看缓冲只留末尾 16KB，手机切后台重连终端不至于白屏。
+// ---------------------------------------------------------------------------
+
+const ptySessions = new Map();
+const PTY_TAIL_BYTES = 16 * 1024;
+
+function wsSendJson(ws, msg) {
+  if (ws && ws.readyState === ws.OPEN) ws.send(JSON.stringify(msg));
+}
+
+// 关闭会话并（可选）把 running 的 pty 任务落为终态；reason 为空表示 Worker
+// 正常上报退出，任务终态由 Worker 的 finish 上报负责，这里只清会话
+function closePtySession(taskId, { status, error, reason }) {
+  const s = ptySessions.get(taskId);
+  if (s) ptySessions.delete(taskId);
+  if (status) {
+    const task = state.tasks.find((t) => t.id === taskId);
+    if (task && task.status === 'running') {
+      task.status = status;
+      task.finishedAt = Date.now();
+      task.result = { error };
+      if (reason) task.logs.push(reason);
+      scheduleSave();
+      broadcast({ type: 'task.updated', task: taskSummary(task), result: task.result });
+    }
+  }
+  broadcast({ type: 'pty.exited', id: taskId, reason: error || 'closed' });
+}
+
+// Worker 通道断开或会话长时间无活动（Worker 掉线且无控制台输入）时回收，
+// 防止忘关的终端在 Worker 上常驻
+function sweepPtyIdle() {
+  const now = Date.now();
+  for (const [taskId, s] of ptySessions) {
+    const workerGone = !s.ws || s.ws.readyState !== s.ws.OPEN;
+    if (workerGone && now - s.lastActiveAt > PTY_IDLE_MS) {
+      closePtySession(taskId, {
+        status: 'failed',
+        error: '终端会话空闲超时，已被服务端回收',
+        reason: '[server] 终端会话空闲超时（Worker 断开），已回收',
+      });
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// API 路由
+// ---------------------------------------------------------------------------
+
+async function handleApi(req, res, pathname, rawBody) {
+  sweepStaleRunning();
+  const body = parseBody(rawBody);
+
+  // --- Worker：领取最老的 pending 任务（原子置为 running）---
+  if (req.method === 'POST' && pathname === '/api/worker/claim') {
+    const workerId = String(body.workerId || 'unknown').slice(0, 128);
+    const task = state.tasks.find((t) => t.status === 'pending');
+    if (!task) return json(res, 200, { task: null });
+    task.status = 'running';
+    task.workerId = workerId;
+    task.startedAt = Date.now();
+    scheduleSave();
+    broadcast({ type: 'task.updated', task: taskSummary(task) });
+    return json(res, 200, { task });
+  }
+
+  // --- Worker：心跳 ---
+  if (req.method === 'POST' && pathname === '/api/worker/heartbeat') {
+    const workerId = String(body.workerId || 'unknown').slice(0, 128);
+    state.heartbeats[workerId] = {
+      at: Date.now(),
+      hostname: String(body.hostname || '').slice(0, 128),
+      node: String(body.node || '').slice(0, 64),
+      // Worker 配置的可用 Agent 列表（控制台据此渲染下拉选择）
+      agents: Array.isArray(body.agents)
+        ? body.agents.map((a) => String(a).slice(0, 64)).slice(0, 32)
+        : [],
+    };
+    scheduleSave();
+    broadcast({ type: 'workers', workers: workersSnapshot() });
+    return json(res, 200, { ok: true });
+  }
+
+  // --- Worker / 控制台：查询 Worker 在线状态 ---
+  if (req.method === 'GET' && pathname === '/api/worker/status') {
+    return json(res, 200, { workers: workersSnapshot() });
+  }
+
+  // --- 创建任务 ---
+  if (req.method === 'POST' && pathname === '/api/tasks') {
+    const type = String(body.type || '');
+    if (!['script', 'shell', 'agent', 'chat', 'pty'].includes(type)) {
+      return json(res, 400, { error: 'type 必须是 script|shell|agent|chat|pty' });
+    }
+    const task = {
+      id: crypto.randomUUID(),
+      type,
+      title: String(body.title || '').slice(0, 200),
+      payload: body.payload || {},
+      status: 'pending',
+      logs: [],
+      result: null,
+      createdAt: Date.now(),
+      startedAt: null,
+      finishedAt: null,
+      workerId: null,
+    };
+    state.tasks.push(task);
+    scheduleSave();
+    broadcast({ type: 'task.created', task: taskSummary(task) });
+    notifyWorkers(); // 任务到达即推送，Worker 立即领取，不再等轮询周期
+    return json(res, 201, publicTask(task));
+  }
+
+  // --- 任务列表 ---
+  if (req.method === 'GET' && pathname === '/api/tasks') {
+    const url = new URL(req.url, 'http://localhost');
+    const limit = Math.max(1, Math.min(Number(url.searchParams.get('limit')) || 50, 200));
+    const list = [...state.tasks]
+      .sort((a, b) => b.createdAt - a.createdAt)
+      .slice(0, limit)
+      .map(taskSummary);
+    return json(res, 200, { tasks: list });
+  }
+
+  // --- 单个任务详情（含日志）---
+  const taskMatch = pathname.match(/^\/api\/tasks\/([0-9a-f-]{36})$/);
+  if (req.method === 'GET' && taskMatch) {
+    const task = state.tasks.find((t) => t.id === taskMatch[1]);
+    if (!task) return json(res, 404, { error: 'task not found' });
+    return json(res, 200, publicTask(task));
+  }
+
+  // --- 追加日志（Worker）---
+  const logMatch = pathname.match(/^\/api\/tasks\/([0-9a-f-]{36})\/logs$/);
+  if (req.method === 'POST' && logMatch) {
+    const task = state.tasks.find((t) => t.id === logMatch[1]);
+    if (!task) return json(res, 404, { error: 'task not found' });
+    const lines = Array.isArray(body.lines) ? body.lines : [];
+    for (const line of lines) {
+      task.logs.push(String(line).slice(0, 4000));
+    }
+    if (task.logs.length > MAX_LOG_LINES) {
+      task.logs.splice(0, task.logs.length - MAX_LOG_LINES);
+    }
+    scheduleSave();
+    broadcast({ type: 'task.logs', id: task.id, lines });
+    return json(res, 200, { ok: true, logCount: task.logs.length });
+  }
+
+  // --- 结束任务（Worker）---
+  const finishMatch = pathname.match(/^\/api\/tasks\/([0-9a-f-]{36})\/finish$/);
+  if (req.method === 'POST' && finishMatch) {
+    const task = state.tasks.find((t) => t.id === finishMatch[1]);
+    if (!task) return json(res, 404, { error: 'task not found' });
+    task.status = body.status === 'done' ? 'done' : 'failed';
+    task.result = body.result ?? null;
+    task.finishedAt = Date.now();
+    scheduleSave();
+    broadcast({ type: 'task.updated', task: taskSummary(task), result: task.result });
+    notifyIm(task, task.status);
+    return json(res, 200, publicTask(task));
+  }
+
+  // --- 取消任务（控制台；仅对 pending 生效）---
+  const cancelMatch = pathname.match(/^\/api\/tasks\/([0-9a-f-]{36})\/cancel$/);
+  if (req.method === 'POST' && cancelMatch) {
+    const task = state.tasks.find((t) => t.id === cancelMatch[1]);
+    if (!task) return json(res, 404, { error: 'task not found' });
+    if (task.status !== 'pending') {
+      return json(res, 409, { error: `只能取消 pending 任务，当前状态：${task.status}` });
+    }
+    task.status = 'canceled';
+    task.finishedAt = Date.now();
+    scheduleSave();
+    broadcast({ type: 'task.updated', task: taskSummary(task) });
+    notifyIm(task, 'canceled');
+    return json(res, 200, publicTask(task));
+  }
+
+  // --- 关闭交互终端（控制台）：通知持有会话的 Worker 杀掉 PTY，
+  // 任务终态仍由 Worker 的 finish 上报闭环 ---
+  const killMatch = pathname.match(/^\/api\/tasks\/([0-9a-f-]{36})\/kill$/);
+  if (req.method === 'POST' && killMatch) {
+    const s = ptySessions.get(killMatch[1]);
+    if (!s) return json(res, 404, { error: '没有活跃的终端会话' });
+    wsSendJson(s.ws, { type: 'session.close', taskId: killMatch[1] });
+    return json(res, 200, { ok: true });
+  }
+
+  return json(res, 404, { error: 'not found' });
+}
+
+// ---------------------------------------------------------------------------
+// 静态文件（手机端 Web 控制台）
+// ---------------------------------------------------------------------------
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+};
+
+function serveStatic(req, res, pathname) {
+  const rel = pathname === '/' ? 'index.html' : pathname.replace(/^\/+/, '');
+  const filePath = path.join(WEB_DIR, rel);
+  if (!filePath.startsWith(WEB_DIR)) {
+    res.writeHead(403);
+    return res.end('forbidden');
+  }
+  fs.readFile(filePath, (err, data) => {
+    if (err) {
+      res.writeHead(404);
+      return res.end('not found');
+    }
+    res.writeHead(200, {
+      'Content-Type': MIME[path.extname(filePath)] || 'application/octet-stream',
+      'Cache-Control': 'no-store',
+    });
+    res.end(data);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// HTTP 入口
+// ---------------------------------------------------------------------------
+
+const server = http.createServer(async (req, res) => {
+  try {
+    const url = new URL(req.url, 'http://localhost');
+    const pathname = url.pathname;
+
+    if (pathname.startsWith('/api/')) {
+      // 先验签（读原始 body 计算摘要），通过后才进入业务路由
+      const auth = await verifyRestSignature(req, pathname);
+      if (!auth.ok) {
+        console.warn(
+          `[server] 拒绝请求 ${req.method} ${pathname}，来源 ${req.socket.remoteAddress}：${auth.reason}`,
+        );
+        return json(res, 401, { error: 'unauthorized' });
+      }
+      return await handleApi(req, res, pathname, auth.rawBody);
+    }
+
+    if (req.method === 'GET') return serveStatic(req, res, pathname);
+
+    return json(res, 405, { error: 'method not allowed' });
+  } catch (err) {
+    return json(res, err.statusCode || (err.message === 'invalid json' ? 400 : 500), {
+      error: err.message || 'internal error',
+    });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// WebSocket 连接管理
+// ---------------------------------------------------------------------------
+
+const wss = new WebSocketServer({ noServer: true });
+
+wss.on('connection', (ws, req) => {
+  const remote = req.socket.remoteAddress;
+  ws.isAuthed = false;
+  ws.isAlive = true;
+
+  // 连接后 5 秒内必须完成鉴权，否则关闭，防止裸连接占资源
+  const authTimer = setTimeout(() => ws.close(4001, 'auth timeout'), 5000);
+
+  ws.on('message', (raw) => {
+    if (!ws.isAuthed) {
+      let msg = null;
+      try {
+        msg = JSON.parse(raw.toString());
+      } catch {
+        ws.close(4002, 'bad auth message');
+        return;
+      }
+      if (!msg || msg.type !== 'auth') {
+        ws.close(4002, 'bad auth message');
+        return;
+      }
+      // 签名鉴权：sig = HMAC(密钥, "WS\nTS\nNONCE")，同样走时间窗 + nonce 防重放
+      const result = verifySignature(
+        ['WS', String(msg.ts), String(msg.nonce)],
+        msg.ts,
+        msg.nonce,
+        msg.sig,
+      );
+      if (!result.ok) {
+        console.warn(`[server] 拒绝 WS 连接，来源 ${remote}：${result.reason}`);
+        ws.close(4003, 'auth failed');
+        return;
+      }
+      clearTimeout(authTimer);
+      ws.isAuthed = true;
+      wsClients.add(ws);
+      // 鉴权通过立即下发全量快照，之后的增量靠 broadcast
+      ws.send(
+        JSON.stringify({
+          type: 'hello',
+          tasks: [...state.tasks].sort((a, b) => b.createdAt - a.createdAt).slice(0, 50).map(taskSummary),
+          workers: workersSnapshot(),
+        }),
+      );
+      return;
+    }
+
+    // 鉴权后只受理 pty 终端交互消息，其余一律忽略
+    let msg = null;
+    try {
+      msg = JSON.parse(raw.toString());
+    } catch {
+      return;
+    }
+    if (!msg || typeof msg.taskId !== 'string') return;
+    const taskId = msg.taskId.slice(0, 64);
+
+    if (msg.type === 'pty.attach') {
+      // 打开终端：先补回看缓冲，再告知 Worker 侧会话是否仍活
+      const s = ptySessions.get(taskId);
+      wsSendJson(ws, {
+        type: 'pty.attach',
+        id: taskId,
+        tail: s ? s.tail : '',
+        live: Boolean(s && s.ws && s.ws.readyState === s.ws.OPEN),
+      });
+      return;
+    }
+    if (msg.type === 'session.input') {
+      const s = ptySessions.get(taskId);
+      if (!s) return wsSendJson(ws, { type: 'pty.exited', id: taskId, reason: '会话已结束' });
+      s.lastActiveAt = Date.now();
+      wsSendJson(s.ws, { type: 'session.input', taskId, data: String(msg.data || '').slice(0, 65536) });
+      return;
+    }
+    if (msg.type === 'session.resize') {
+      const s = ptySessions.get(taskId);
+      if (!s) return;
+      wsSendJson(s.ws, {
+        type: 'session.resize',
+        taskId,
+        cols: Number(msg.cols) || 80,
+        rows: Number(msg.rows) || 24,
+      });
+      return;
+    }
+    if (msg.type === 'session.close') {
+      const s = ptySessions.get(taskId);
+      if (s) wsSendJson(s.ws, { type: 'session.close', taskId });
+    }
+  });
+
+  ws.on('pong', () => {
+    ws.isAlive = true;
+  });
+  ws.on('close', () => {
+    clearTimeout(authTimer);
+    wsClients.delete(ws);
+  });
+  ws.on('error', () => {});
+});
+
+// --- Worker 通道 /worker/ws：鉴权方式同 /ws；鉴权后下发 task.available，
+// 并承载 pty 会话上行消息（session.started/output/exited）---
+const workerWss = new WebSocketServer({ noServer: true });
+
+workerWss.on('connection', (ws, req) => {
+  const remote = req.socket.remoteAddress;
+  ws.isAuthed = false;
+  ws.isAlive = true;
+
+  const authTimer = setTimeout(() => ws.close(4001, 'auth timeout'), 5000);
+
+  ws.on('message', (raw) => {
+    if (!ws.isAuthed) {
+      let msg = null;
+      try {
+        msg = JSON.parse(raw.toString());
+      } catch {
+        ws.close(4002, 'bad auth message');
+        return;
+      }
+      if (!msg || msg.type !== 'auth') {
+        ws.close(4002, 'bad auth message');
+        return;
+      }
+      const result = verifySignature(
+        ['WS', String(msg.ts), String(msg.nonce)],
+        msg.ts,
+        msg.nonce,
+        msg.sig,
+      );
+      if (!result.ok) {
+        console.warn(`[server] 拒绝 Worker WS 连接，来源 ${remote}：${result.reason}`);
+        ws.close(4003, 'auth failed');
+        return;
+      }
+      clearTimeout(authTimer);
+      ws.isAuthed = true;
+      ws.workerId = String(msg.workerId || 'unknown').slice(0, 128);
+      wsWorkers.add(ws);
+      console.log(`[server] Worker ${ws.workerId} 通道已连接（来源 ${remote}）`);
+      // 断线窗口内可能已有积压任务，连接建立即补一次通知
+      if (state.tasks.some((t) => t.status === 'pending')) {
+        ws.send(JSON.stringify({ type: 'task.available' }));
+      }
+      return;
+    }
+
+    // --- pty 会话上行消息 ---
+    let msg = null;
+    try {
+      msg = JSON.parse(raw.toString());
+    } catch {
+      return;
+    }
+    if (!msg || typeof msg.taskId !== 'string') return;
+    const taskId = msg.taskId.slice(0, 64);
+    const task = state.tasks.find((t) => t.id === taskId);
+
+    if (msg.type === 'session.started') {
+      // 会话注册（含 Worker 通道重连后的重新挂载）；只认该 Worker 自己领取的任务
+      if (!task || task.type !== 'pty' || task.workerId !== ws.workerId) return;
+      const prev = ptySessions.get(taskId);
+      ptySessions.set(taskId, {
+        ws,
+        tail: prev ? prev.tail : '',
+        lastActiveAt: Date.now(),
+      });
+      broadcast({ type: 'pty.started', id: taskId, pid: Number(msg.pid) || 0 });
+      return;
+    }
+    if (msg.type === 'session.output') {
+      const s = ptySessions.get(taskId);
+      if (!s) return;
+      const data = String(msg.data || '');
+      s.lastActiveAt = Date.now();
+      s.tail = (s.tail + data).slice(-PTY_TAIL_BYTES); // 回看缓冲，重连可重放
+      broadcast({ type: 'pty.data', id: taskId, data });
+      return;
+    }
+    if (msg.type === 'session.exited') {
+      // 只清会话映射；任务终态由 Worker 随后的 HTTP finish 上报负责
+      closePtySession(taskId, {});
+    }
+  });
+
+  ws.on('pong', () => {
+    ws.isAlive = true;
+  });
+  ws.on('close', () => {
+    clearTimeout(authTimer);
+    wsWorkers.delete(ws);
+    // 该连接持有的会话置为游离：PTY 在 Worker 上还活着，重连后会重新挂载；
+    // 超过 PTY_IDLE_SEC 未重连则由 sweepPtyIdle 判失败
+    for (const [, s] of ptySessions) {
+      if (s.ws === ws) s.ws = null;
+    }
+  });
+  ws.on('error', () => {});
+});
+
+// 两条通道共用同一 HTTP server，按路径分发 upgrade（path 模式的多个
+// WebSocketServer 实例会在 upgrade 事件上互相干扰，故用 noServer 手动路由）
+server.on('upgrade', (req, socket, head) => {
+  const pathname = new URL(req.url, 'http://localhost').pathname;
+  if (pathname === '/ws') {
+    wss.handleUpgrade(req, socket, head, (ws) => wss.emit('connection', ws, req));
+  } else if (pathname === '/worker/ws') {
+    workerWss.handleUpgrade(req, socket, head, (ws) => workerWss.emit('connection', ws, req));
+  } else {
+    socket.destroy();
+  }
+});
+
+// 心跳探活：揪出半开连接（手机锁屏/断网后 TCP 可能不触发 close）；
+// 顺带回收空闲的 pty 会话
+setInterval(() => {
+  for (const ws of [...wss.clients, ...workerWss.clients]) {
+    if (!ws.isAlive) {
+      ws.terminate();
+      wsClients.delete(ws);
+      wsWorkers.delete(ws);
+      continue;
+    }
+    ws.isAlive = false;
+    ws.ping();
+  }
+  sweepPtyIdle();
+}, 30 * 1000).unref();
+
+server.listen(PORT, () => {
+  console.log(`[server] kite API listening on :${PORT}`);
+  console.log(`[server] config file: ${CONFIG_FILE}`);
+  console.log(`[server] data dir: ${DATA_DIR}`);
+});