@jacksontian/kite-server 0.3.0 → 0.4.0

package/lib/config.js

@@ -0,0 +1,280 @@
+/**
+ * 云端 server 配置加载与校验。
+ *
+ * 纯 CLI 形态：任何动作都走子命令，裸 kites（无参数）只打印用法、绝不启动服务。
+ * 配置只认 YAML 文件（不再读取任何环境变量），--config 显式指定，
+ * 不传时回落默认路径 ~/.kites/conf/server.yaml：
+ *   kites start --config /path/to/server.yaml
+ * 结构与类型校验由 zod schema 完成（CONFIG_SCHEMA）：未知配置项、
+ * 类型错误、缺必填项一次性报全后 exit 1；dataDir 的可创建/可写校验
+ * 是运行时行为，仍在校验通过后单独执行。模板见包内 config.example.yaml。
+ *
+ * 各子命令实现拆分在 lib/cli/ 目录：
+ *   kites start         启动云端服务（--config 缺省回落 ~/.kites/conf/server.yaml）；裸 kites 不带子命令只打印用法，不启动
+ *   kites keygen        生成强随机密钥并打印配置片段（lib/cli/keygen.js）
+ *   kites init [路径]   在目标位置（默认 ~/.kites/conf/server.yaml）生成填好随机密钥的配置文件；
+ *                       终端（TTY）下进入交互问答（port/dataDir，回车用默认值），
+ *                       --yes 或非终端环境按默认值直接生成（lib/cli/init.js）
+ *   kites check         只校验配置文件（--config 指定或默认路径），通过打印摘要退出，不启动服务
+ *   kites deploy        基于包内 systemd 模板生成占位符已按本机替换好的 unit 文件（lib/cli/deploy.js）
+ *   kites --help        打印用法说明（-h 等效，lib/cli/meta.js）
+ *   kites --version     打印版本号（-V 等效，lib/cli/meta.js）
+ * apiSecret 若仍是配置模板的占位符文本，启动时直接拦截，避免裸奔。
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import YAML from 'yaml';
+import { z } from 'zod';
+import { maybeMeta } from './cli/meta.js';
+import { dispatch, isCheckMode, parseArgs, fail } from './cli/args.js';
+import { maybeKeygen } from './cli/keygen.js';
+import { maybeInit } from './cli/init.js';
+import { maybeDeploy } from './cli/deploy.js';
+import { isPlainObject, PLACEHOLDER_SECRET, optStr, formatIssues, expandHome, SECRET_HINT } from './cli/util.js';
+
+// 交互问答入口保持从 lib/config.js 导出（测试约定的导入路径）
+export { collectServerInitAnswers } from './cli/init.js';
+
+const CONFIG_SCHEMA = z.strictObject({
+  apiSecret: z
+    .string({
+      error: (iss) =>
+        iss.input === undefined || iss.input === null
+          ? `缺少 apiSecret${SECRET_HINT}`
+          : 'apiSecret 必须是字符串（建议加引号，避免被 YAML 解析为数字）',
+    })
+    .trim()
+    .min(1, `缺少 apiSecret${SECRET_HINT}`),
+  // Worker 专用密钥（可选）：配置后 Worker 侧 API（claim/heartbeat/logs/finish）
+  // 与 /worker/ws 只认该密钥，控制台密钥（apiSecret）泄露不再等于 Worker 执行权。
+  // 留空则两端共用 apiSecret（向后兼容）
+  workerSecret: optStr('workerSecret 必须是字符串'),
+  // 多 Worker 独立密钥（可选）：workerId -> 密钥映射，每台 Worker 一密钥。
+  // 配置后 Worker 侧验签命中该映射的密钥即绑定其 workerId 身份（请求自报的
+  // workerId 必须一致），Worker 之间无法互相冒充；与 workerSecret 可并存
+  // （命中共享密钥时身份仍自报，兼容旧部署）。均未配置时回落共用 apiSecret
+  workerSecrets: z
+    .record(z.string(), z.string({ error: 'workerSecrets 的密钥必须是字符串' }).trim(), {
+      error: 'workerSecrets 必须是「workerId: 密钥」的映射',
+    })
+    .optional(),
+  port: z.coerce
+    .number({ error: 'port 必须是数字' })
+    .int('port 必须是整数')
+    .min(1, 'port 超出范围 [1, 65535]')
+    .max(65535, 'port 超出范围 [1, 65535]')
+    .default(8787),
+  // 语义（~ 展开 / 相对启动工作目录 / 缺省 ~/.kites/data / 可写校验）
+  // 无法纯声明式表达，schema 只约束类型，解析后命令式处理
+  dataDir: optStr('dataDir 必须是字符串'),
+  // 程序自写日志文件（logs/ 标准目录）；落盘逻辑见 lib/logger.js，
+  // 只包装 console 追加写文件，前台输出与 journal 捕获不受影响
+  logFile: optStr('logFile 必须是字符串'),
+  // 落盘最低级别（只影响日志文件，前台输出不过滤）；大小写归一化后比枚举
+  logLevel: z.coerce
+    .string({ error: 'logLevel 必须是字符串' })
+    .trim()
+    .toLowerCase()
+    .pipe(
+      z.enum(['debug', 'info', 'warn', 'error'], {
+        error: (iss) => `logLevel 值 "${iss.input}" 非法（可用：debug|info|warn|error）`,
+      }),
+    )
+    .default('info'),
+  // 轮转保留代数（.1 最新，超出自动删除最旧一代）
+  logKeep: z.coerce
+    .number({ error: 'logKeep 必须是数字' })
+    .int('logKeep 必须是整数')
+    .min(1, 'logKeep 至少保留 1 代')
+    .max(100, 'logKeep 超出范围 [1, 100]')
+    .default(5),
+  maxTasks: z.coerce.number({ error: 'maxTasks 必须是数字' }).positive('maxTasks 必须是正数').default(200),
+  staleRunningSec: z.coerce
+    .number({ error: 'staleRunningSec 必须是数字' })
+    .positive('staleRunningSec 必须是正数')
+    .default(600),
+  sigWindowSec: z.coerce
+    .number({ error: 'sigWindowSec 必须是数字' })
+    .positive('sigWindowSec 必须是正数')
+    .default(300),
+  ptyIdleSec: z.coerce
+    .number({ error: 'ptyIdleSec 必须是数字' })
+    .positive('ptyIdleSec 必须是正数')
+    .default(90),
+  imWebhook: optStr('imWebhook 必须是字符串'),
+  imSecret: optStr('imSecret 必须是字符串'),
+  imNotifyEvents: z
+    .array(
+      // 与原实现一致：元素宽容转字符串后归一化小写再比枚举
+      z.coerce.string({ error: 'imNotifyEvents 元素必须是字符串' }).trim().toLowerCase().pipe(
+        z.enum(['done', 'failed', 'canceled'], {
+          error: (iss) => `imNotifyEvents 含非法事件 "${iss.input}"（可用：done|failed|canceled）`,
+        }),
+      ),
+      { error: 'imNotifyEvents 必须是数组（如 [failed, done]）' },
+    )
+    .default(['failed']),
+});
+
+/** 加载并校验配置，返回归一化后的常量对象 */
+export async function loadServerConfig() {
+  const tag = 'server';
+  await maybeMeta();
+  dispatch(); // 裸调用/旧写法/未知子命令在此拦截；能走到下面的必是五个子命令之一
+  maybeKeygen();
+  await maybeInit();
+  await maybeDeploy();
+  const configFile = parseArgs();
+
+  let raw;
+  try {
+    raw = await fs.promises.readFile(configFile, 'utf8');
+  } catch (err) {
+    console.error(`[${tag}] 无法读取配置文件 ${configFile}: ${err.message}`);
+    process.exit(1);
+  }
+
+  const doc = YAML.parseDocument(raw);
+  if (doc.errors.length) {
+    console.error(`[${tag}] 配置文件 YAML 语法错误（${configFile}）：`);
+    for (const e of doc.errors) console.error('  - ' + e.message);
+    process.exit(1);
+  }
+  const cfg = doc.toJS();
+  if (!isPlainObject(cfg)) {
+    console.error(`[${tag}] 配置文件内容必须是一个键值映射（${configFile}）`);
+    process.exit(1);
+  }
+
+  const parsed = CONFIG_SCHEMA.safeParse(cfg);
+  if (!parsed.success) {
+    fail(formatIssues(parsed.error.issues, { '': Object.keys(CONFIG_SCHEMA.shape) }), tag);
+  }
+  const v = parsed.data;
+  const errors = [];
+
+  // 模板占位符原样未改：此时启动等于用公开"密钥"裸奔，显式拦下并指路 keygen
+  if (v.apiSecret === PLACEHOLDER_SECRET) {
+    errors.push('apiSecret 仍是配置模板的占位符文本，请生成真实密钥后填入：kites keygen');
+  }
+  if (v.workerSecret === PLACEHOLDER_SECRET) {
+    errors.push('workerSecret 仍是配置模板的占位符文本，请生成真实密钥后填入（或留空共用 apiSecret）：kites keygen');
+  }
+
+  // workerSecrets：键即 workerId（与 worker.yaml 的 workerId 同规则）；
+  // 密钥非空/非占位符，且两两不同（同密钥会让服务端无法区分身份）
+  const workerSecrets = {};
+  if (v.workerSecrets) {
+    const seen = new Map(); // secret -> workerId
+    for (const [id, secret] of Object.entries(v.workerSecrets)) {
+      if (!/^[\w.-]{1,128}$/.test(id)) {
+        errors.push(`workerSecrets 的 Worker 标识 "${id}" 非法（只能含字母/数字/._-，不超过 128 字符）`);
+        continue;
+      }
+      if (!secret) {
+        errors.push(`workerSecrets.${id} 密钥不能为空（kites keygen 生成）`);
+        continue;
+      }
+      if (secret === PLACEHOLDER_SECRET) {
+        errors.push(`workerSecrets.${id} 仍是配置模板的占位符文本，请填入真实密钥：kites keygen`);
+        continue;
+      }
+      if (seen.has(secret)) {
+        errors.push(`workerSecrets 中 "${id}" 与 "${seen.get(secret)}" 配置了相同密钥，服务端无法区分两者身份`);
+        continue;
+      }
+      seen.set(secret, id);
+      workerSecrets[id] = secret;
+    }
+    if (v.workerSecret && seen.has(v.workerSecret)) {
+      errors.push(
+        `workerSecret 与 workerSecrets.${seen.get(v.workerSecret)} 的密钥相同，身份绑定会有歧义，请配置不同密钥`,
+      );
+    }
+  }
+
+  // 未配置时默认主目录下的固定位置（~/.kites 标准树），与配置文件位置、启动目录都解耦；
+  // 相对路径相对启动工作目录解析（path.resolve 默认行为），建议写绝对路径
+  const dataDir = path.resolve(
+    expandHome(v.dataDir || path.join(os.homedir(), '.kites', 'data')),
+  );
+  const logFile = path.resolve(
+    expandHome(v.logFile || path.join(os.homedir(), '.kites', 'logs', 'server.log')),
+  );
+  // 启动前校验可创建、可写：误配在这里一次性报清，
+  // 而不是运行中落盘失败才静默降级（只打日志、数据留在内存）
+  try {
+    await fs.promises.mkdir(dataDir, { recursive: true });
+    const probe = path.join(dataDir, '.rw-write-probe');
+    await fs.promises.writeFile(probe, '');
+    await fs.promises.rm(probe);
+  } catch (err) {
+    if (err.code === 'EEXIST' || err.code === 'ENOTDIR') {
+      errors.push(`dataDir 指向的路径已存在但不是目录：${dataDir}`);
+    } else {
+      errors.push(`dataDir 无法创建或不可写（${dataDir}）：${err.message}；请确认运行用户对该目录有读写权限`);
+    }
+  }
+  // logFile 探测父目录可创建、可写（文件本身由 logger 追加打开）：
+  // 与 dataDir 同等对待，误配在启动时一次性报清
+  try {
+    await fs.promises.mkdir(path.dirname(logFile), { recursive: true });
+    const probe = path.join(path.dirname(logFile), '.rw-write-probe');
+    await fs.promises.writeFile(probe, '');
+    await fs.promises.rm(probe);
+  } catch (err) {
+    if (err.code === 'EEXIST' || err.code === 'ENOTDIR') {
+      errors.push(`logFile 的父目录已存在但不是目录：${path.dirname(logFile)}`);
+    } else {
+      errors.push(`logFile 父目录无法创建或不可写（${path.dirname(logFile)}）：${err.message}；请确认运行用户对该目录有读写权限`);
+    }
+  }
+  if (errors.length) fail(errors, tag);
+
+  // 典型误配提示：配了加签密钥但没配 webhook，secret 会被静默忽略
+  if (v.imSecret && !v.imWebhook) {
+    console.warn(`[${tag}] 已配置 imSecret 但 imWebhook 为空，加签密钥将被忽略`);
+  }
+
+  // check 子命令（kites check --config x）：与启动完全相同的校验已通过，
+  // 打印归一化摘要后直接退出，改完配置不用真启动服务（占端口）就能验证。
+  // 密钥只报长度不回显内容
+  if (isCheckMode()) {
+    console.log(`[${tag}] 配置校验通过：${configFile}`);
+    console.log(`  port: ${v.port}`);
+    console.log(`  dataDir: ${dataDir}`);
+    console.log(`  logFile: ${logFile}（级别 ${v.logLevel}，轮转保留 ${v.logKeep} 代）`);
+    console.log(`  apiSecret: 已配置（${v.apiSecret.length} 字符）`);
+    console.log(`  workerSecret: ${v.workerSecret ? '已单独配置（Worker 专用密钥）' : '未配置，与 apiSecret 共用'}`);
+    console.log(`  IM 通知: ${v.imWebhook ? `已配置（事件：${v.imNotifyEvents.join(', ')}）` : '未配置'}`);
+    console.log(`[${tag}] 可以启动服务：kites start --config ${configFile}`);
+    process.exit(0);
+  }
+
+  // Worker 侧可接受的密钥及身份绑定：workerSecrets 条目验签命中即绑定 workerId；
+  // workerSecret 为共享兼容路径（workerId 为 null 表示身份自报）；
+  // 两者都未配置时回落共用 apiSecret（单密钥模式）
+  const workerAuth = Object.entries(workerSecrets).map(([workerId, secret]) => ({ secret, workerId }));
+  if (v.workerSecret) workerAuth.push({ secret: v.workerSecret, workerId: null });
+  if (!workerAuth.length) workerAuth.push({ secret: v.apiSecret, workerId: null });
+
+  return {
+    configFile,
+    apiSecret: v.apiSecret,
+    workerAuth,
+    port: v.port,
+    dataDir,
+    logFile,
+    logLevel: v.logLevel,
+    logKeep: v.logKeep,
+    maxTasks: v.maxTasks,
+    staleRunningMs: v.staleRunningSec * 1000,
+    sigWindowSec: v.sigWindowSec,
+    ptyIdleMs: v.ptyIdleSec * 1000,
+    imWebhook: v.imWebhook,
+    imSecret: v.imSecret,
+    imNotifyEvents: new Set(v.imNotifyEvents),
+  };
+}

package/lib/im.js

@@ -0,0 +1,70 @@
+/**
+ * IM 群通知：任务终态事件推送钉钉群机器人（markdown），走 dingbot SDK；
+ * 机器人启用“加签”安全设置时由 imSecret 自动完成 timestamp+sign 拼接。
+ * 未配置 imWebhook 完全静默；发送失败只记日志，绝不抛出影响主链路。
+ */
+
+import DingBot from 'dingbot';
+
+const IM_STATUS_META = {
+  done: { icon: '✅', label: '完成' },
+  failed: { icon: '❌', label: '失败' },
+  canceled: { icon: '🚫', label: '已取消' },
+};
+
+export function createImNotifier(ctx) {
+  const { imWebhook: IM_WEBHOOK, imSecret: IM_SECRET, imNotifyEvents: IM_NOTIFY_EVENTS } = ctx.cfg;
+
+  const IM_BOT = IM_WEBHOOK ? new DingBot(IM_WEBHOOK, { timeout: 10_000 }, IM_SECRET || undefined) : null;
+
+  // 推送摘要：pty 任务只有项目目录
+  function imPayloadBrief(task) {
+    const p = task.payload || {};
+    if (task.type === 'pty') {
+      return p.project ? `交互终端（项目：${p.project}）` : '交互终端';
+    }
+    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 ? ctx.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}`));
+  }
+
+  return notifyIm;
+}

package/lib/logger.js

@@ -0,0 +1,129 @@
+/**
+ * 日志落盘：start 启动时把 console.log/warn/error 同时追加写到 logFile
+ * （logs/ 标准目录），前台输出与托管层（systemd journal / launchd 捕获）不受影响。
+ * 只在 start 路径接线（bin 里配置加载完成后调用），check/init/keygen/deploy
+ * 这类一次性子命令不写日志文件。
+ *
+ * 格式与轮转：
+ *   - 每条一行：「[ISO 时间] [级别 ] [pid] 内容」；内容里的换行统一转义成 \n，
+ *     保证一条记录一行，grep/tail 友好，也防止换行字符伪造日志行
+ *   - 落盘最低级别由 logLevel 配置（debug|info|warn|error，默认 info）；
+ *     低于阈值的条目只走前台输出、不落盘（前台输出行为完全不受影响）
+ *   - 超过 maxBytes（默认 10MB）轮转：当前文件整体顺延一代（.1 最新），
+ *     超出 logKeep 代（默认 5）的最旧一代自动删除；
+ *     更复杂的保留策略可交给 logrotate 等系统工具
+ *
+ * 实现：所有落盘动作（打开/写入/轮转/关闭）排进一条异步串行队列依次执行，
+ * 全程不用同步 IO 阻塞事件循环，同时保持「本行写完才判轮转、轮转完才续写」
+ * 的严格顺序；写入失败即降级为不落盘并告警，不阻断服务
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const MAX_BYTES = 10 * 1024 * 1024;
+const KEEP_FILES = 5;
+const LEVEL_RANK = { debug: 0, info: 1, warn: 2, error: 3 };
+
+/** 把 console 参数序列转成单行文本（近似 console 的拼接语义）；
+ * 换行转义成字面 \n，保证一条记录一行 */
+function fmt(args) {
+  return args
+    .map((a) => (typeof a === 'string' ? a : a instanceof Error ? a.stack || a.message : JSON.stringify(a)))
+    .join(' ')
+    .replace(/\r?\n/g, '\\n');
+}
+
+/** 创建文件日志写入器（不触碰 console 全局，enableLogFile 拿它接线；
+ * 单测可直接用它验证格式/过滤/轮转）。返回 { append(level, args), close() }；
+ * append 入队即返回（fire-and-forget），不阻塞前台输出 */
+export function createFileLogger(logFile, { level = 'info', keep = KEEP_FILES, maxBytes = MAX_BYTES } = {}) {
+  const minRank = LEVEL_RANK[level] ?? LEVEL_RANK.info;
+  let stream = null;
+  let written = 0;
+  let disabled = false; // 写入失败后本次启动不再落盘（前台输出不受影响）
+
+  const open = async () => {
+    try {
+      await fs.promises.mkdir(path.dirname(logFile), { recursive: true });
+      const st = await fs.promises.stat(logFile).catch(() => null);
+      written = st ? st.size : 0;
+      stream = fs.createWriteStream(logFile, { flags: 'a' });
+      // 兜住 error 事件（如 ENOSPC）：未监听会让进程崩溃；
+      // 流置空后队列里的下一次写入会走降级路径
+      stream.on('error', () => { stream = null; });
+    } catch (err) {
+      stream = null;
+      console.warn(`[server] 日志文件无法打开，本次启动不落盘日志（${logFile}）：${err.message}`);
+    }
+  };
+
+  const rotate = async () => {
+    // end 会等缓冲冲刷完再关闭，轮转不丢行；
+    // 再删最旧一代、逐代后移，最后把当前文件改名为 .1
+    const cur = stream;
+    stream = null;
+    await new Promise((resolve) => cur.end(resolve));
+    try {
+      await fs.promises.unlink(`${logFile}.${keep}`).catch(() => {}); // 最旧一代不存在则跳过
+      for (let i = keep - 1; i >= 1; i--) {
+        await fs.promises.rename(`${logFile}.${i}`, `${logFile}.${i + 1}`).catch(() => {}); // 缺代跳过
+      }
+      await fs.promises.rename(logFile, `${logFile}.1`);
+    } catch { /* 轮转失败交给下方重开兜底，避免无限增长 */ }
+    await open();
+  };
+
+  const writeLine = async (line) => {
+    // 先写后查：本行落盘完成才判超限，触发行不丢；超限则整体轮转
+    await new Promise((resolve, reject) => {
+      stream.write(line, (err) => (err ? reject(err) : resolve()));
+    });
+    written += Buffer.byteLength(line);
+    if (written > maxBytes) await rotate();
+  };
+
+  // 异步串行队列：打开/写入/轮转/关闭按调用顺序逐个执行；
+  // 队列内部消化所有异常，永不 reject（否则后续任务会被跳过）
+  let queue = open();
+
+  const append = (lvl, args) => {
+    if (disabled || LEVEL_RANK[lvl] < minRank) return;
+    const line = `[${new Date().toISOString()}] [${lvl.toUpperCase().padEnd(5)}] [${process.pid}] ${fmt(args)}\n`;
+    queue = queue.then(async () => {
+      if (!stream) return;
+      try {
+        await writeLine(line);
+      } catch {
+        // 写失败（磁盘满/文件被外部移除等）：关流降级，不影响前台输出
+        const cur = stream;
+        stream = null;
+        if (cur) try { cur.end(); } catch { /* 流可能已失效 */ }
+        disabled = true;
+        console.warn(`[server] 日志文件写入失败，本次启动不再落盘日志（${logFile}）`);
+      }
+    });
+  };
+
+  /** 等队列里的写入全部落盘后关闭流（供单测等待异步写入完成） */
+  const close = () =>
+    queue.then(async () => {
+      disabled = true;
+      const cur = stream;
+      stream = null;
+      if (cur) await new Promise((resolve) => cur.end(resolve));
+    });
+
+  return { append, close };
+}
+
+/** 启用日志文件：包装 console.log/warn/error，原输出保留，另按
+ * 「[ISO 时间] [级别 ] [pid] 内容」追加写入 logFile（父目录自动创建）；
+ * 打开失败只降级告警，不阻断服务启动 */
+export function enableLogFile(logFile, opts) {
+  const fileLog = createFileLogger(logFile, opts);
+  const { log, warn, error } = console;
+  console.log = (...args) => { log(...args); fileLog.append('info', args); };
+  console.warn = (...args) => { warn(...args); fileLog.append('warn', args); };
+  console.error = (...args) => { error(...args); fileLog.append('error', args); };
+}

package/lib/pty.js

@@ -0,0 +1,55 @@
+/**
+ * pty 会话中继：taskId -> { ws, tail, lastActiveAt }
+ * Worker 上行 session.output -> 追加回看缓冲并广播控制台；
+ * 控制台下行 session.input/resize/close -> 定向转发给持有会话的 Worker。
+ * 回看缓冲只留末尾 16KB，手机切后台重连终端不至于白屏。
+ */
+
+export const PTY_TAIL_BYTES = 16 * 1024;
+
+export function createPtyHub(ctx) {
+  const PTY_IDLE_MS = ctx.cfg.ptyIdleMs;
+
+  const ptySessions = new Map();
+
+  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 = ctx.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);
+        ctx.scheduleSave();
+        ctx.broadcast({ type: 'task.updated', task: ctx.taskSummary(task), result: task.result });
+      }
+    }
+    ctx.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 断开），已回收',
+        });
+      }
+    }
+  }
+
+  return { ptySessions, wsSendJson, closePtySession, sweepPtyIdle };
+}

package/lib/static.js

@@ -0,0 +1,51 @@
+/**
+ * 静态文件（Web 控制台：移动端 index.html / PC 端 pc.html，按 UA 分发）
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+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',
+};
+
+// 移动端 UA 特征词；命中走手机版，其余（桌面浏览器）走 PC 版。
+// iPadOS 13+ 默认伪装 Mac UA，会落到 PC 版——需要时可显式访问 /index.html
+const MOBILE_UA = /android|iphone|ipod|ipad|mobile|harmonyos/i;
+
+export function createStaticServer(WEB_DIR) {
+  return function serveStatic(req, res, pathname) {
+    let rel = pathname.replace(/^\/+/, '');
+    if (!rel) {
+      rel = MOBILE_UA.test(req.headers['user-agent'] || '') ? 'index.html' : 'pc.html';
+    }
+    // resolve 归一化 ../ 后按「目录 + 分隔符」前缀判断，避免同级前缀目录（web-xxx）绕过
+    const filePath = path.resolve(WEB_DIR, rel);
+    if (filePath !== WEB_DIR && !filePath.startsWith(WEB_DIR + path.sep)) {
+      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',
+        // 纵深防御：页面资源一律限同源，阻断潜在注入脚本把密钥外传（connect-src
+        // 的 'self' 按 CSP3 含同源 ws/wss，实时通道不受影响）；页面含内联 <script>
+        // 与行内样式操作，script/style 需放行 'unsafe-inline'
+        'Content-Security-Policy':
+          "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; " +
+          "img-src 'self' data:; connect-src 'self'",
+        'X-Content-Type-Options': 'nosniff',
+      });
+      res.end(data);
+    });
+  };
+}