@jacksontian/kite-server 0.3.0 → 0.4.1

package/README.md

@@ -19,17 +19,19 @@
 npm i -g @jacksontian/kite-server
 
 # 一步生成配置文件（自动填好随机 apiSecret/workerSecret，打印在输出里请保存）
-kites init    # 默认生成在当前目录（server.yaml）；生产部署用 kites init /opt/kite/server.yaml
-# 手工方式：cp "$(npm root -g)/@jacksontian/kite-server/config.example.yaml" /opt/kite/server.yaml 后编辑，
+kites init    # 不带路径默认生成到 ~/.kites/conf/server.yaml（与 start/check 缺省读取的路径一致）；
+              # 生产部署落标准树：sudo -Hu www-data kites init（www-data 家目录即 /var/www/.kites）
+# 手工方式：cp "$(npm root -g)/@jacksontian/kite-server/config.example.yaml" ~/.kites/conf/server.yaml 后编辑，
 # 密钥用 kites keygen 或下面命令生成（永不在网络上传输）：
 node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
 
-kites check --config /opt/kite/server.yaml   # 干跑校验：只检查配置不启动服务，通过后退出
-kites start --config /opt/kite/server.yaml   # 前台启动服务；常驻托管交给 systemd（见下文 deploy）
+kites check   # 干跑校验：只检查配置不启动服务，通过后退出
+kites start   # 前台启动服务；常驻托管交给 systemd（见下文 deploy）
 ```
 
 启动后浏览器打开 `http://<vps>:8787`，粘贴密钥即可进入控制台。
-配置统一走 YAML 文件，以 `--config` 显式传入，不读取环境变量/.env。
+配置统一走 YAML 文件，不读取环境变量/.env；`--config` 可显式指定路径，
+不传时默认读 `~/.kites/conf/server.yaml`（init 缺省也生成到这里）。
 `kites` 是完全命令行化的工具：启动服务必须显式 `kites start`，裸 `kites`
 （不带子命令）只打印用法、不会启动服务。`kites --help` 查看完整用法，
 `kites --version` 查看版本号。
@@ -42,18 +44,52 @@ kites start --config /opt/kite/server.yaml   # 前台启动服务；常驻托管
 |---|---|
 | `apiSecret` | 必填，两端共享的 HMAC 签名密钥 |
 | `port` | 监听端口，默认 8787 |
-| `dataDir` | 持久化目录，建议绝对路径，支持 `~` 展开，默认 `~/.kite/data` |
+| `dataDir` | 持久化目录，建议绝对路径，支持 `~` 展开，默认 `~/.kites/data` |
+| `logFile` | 程序自写日志文件，默认 `~/.kites/logs/server.log`；超 10MB 轮转并逐代顺延（`.1` 最新），stdout 输出不受影响 |
+| `logLevel` | 日志落盘最低级别（`debug`\|`info`\|`warn`\|`error`），默认 `info`；只过滤落盘，前台输出不受影响 |
+| `logKeep` | 轮转保留代数（`server.log.1` … `.N`），默认 5，超出自动删除最旧一代 |
 | `maxTasks` | 终态任务最多保留条数 |
 | `staleRunningSec` | running 任务超时回收秒数（Worker 离线时判失败，pty 会话不受此限） |
 | `sigWindowSec` | 签名时间窗（秒），两端时钟漂移大时可调宽 |
 | `ptyIdleSec` | pty 会话空闲回收秒数 |
 | `imWebhook` / `imSecret` / `imNotifyEvents` | 钉钉群机器人通知，留空则完全静默 |
 
+## 标准工作目录结构
+
+kites 的所有可变状态收拢在家目录下的 `~/.kites/` 标准树（类比 nginx/mysql 的
+conf/data/logs 布局）；生产托管以 `www-data` 运行时即 `/var/www/.kites/`：
+
+```
+~/.kites/
+├── conf/
+│   └── server.yaml              # 配置（默认读这里，可用 --config 指定别处；模板见包内 config.example.yaml）
+├── data/                        # dataDir：持久化目录
+│   ├── tasks.json               # 任务队列 + 日志 + 结果（0600，含全部命令与输出，勿外传）
+│   ├── tasks.json.tmp           # 落盘中转文件（写完整后 rename 原子替换，正常情况不会残留）
+│   └── tasks.json.corrupt-<ts>  # tasks.json 解析失败时的自动备份（仅在损坏时出现）
+└── logs/
+    ├── server.log               # logFile：程序自写日志（每条一行：时间/级别/pid/内容）
+    └── server.log.1 … .N        # 轮转历史（超 10MB 顺延一代，保留 logKeep 代，默认 5）
+```
+
+约定：
+
+- 各路径支持 `~` 展开；相对路径相对**启动时的工作目录**解析（systemd 托管下即
+  unit 里的 `WorkingDirectory`），建议直接写绝对路径
+- 目录不存在时启动自动创建，并先做可写探测，不可写直接报错退出
+- 已显式配置路径的存量部署不受标准树影响（只改默认值，不迁移任何数据）
+- 备份/迁移时整个 `~/.kites/` 拷走即可；systemd 部署需给运行用户（www-data）
+  整棵树的读写权限
+- Web 控制台静态文件（`web/`）随 npm 包分发，不属于工作目录，不需要也不应该手工维护
+- 日志轮转只做「超 10MB 保留一代」，需要更长的保留策略请配系统工具（logrotate）
+
 ## 生产部署
 
+- 生产形态即上图标准树落 `www-data` 家目录：`sudo -Hu www-data kites init`
+  （缺省即生成到 `/var/www/.kites/conf/server.yaml`，conf/data/logs 同根，权限给 www-data 即可）
 - systemd unit：`kites deploy` 一步生成占位符已替换好的 unit（包内模板
-  `deploy/kiteserver.service`），再 `sudo install` 到 /etc/systemd/system/；
-  unit 以 `www-data` 运行，需给它 `dataDir` 写权限与配置文件读权限
+  `deploy/kiteserver.service`，缺省指向 `/var/www/.kites/conf/server.yaml`），
+  再 `sudo install` 到 /etc/systemd/system/
 - 建议 Nginx/Caddy 反代加 HTTPS（Caddy 有域名即自动签证书）；仅 HTTP 部署时
   按根 README「仅 HTTP 部署」一节做 IP 白名单与密钥轮换
 - `/health` 免签名探活端点，GET 返回 `{ ok: true }`，供 Caddy upstream health /

package/bin/server.js

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+/**
+ * kite 云端信箱 API
+ *
+ * 职责：签名鉴权、任务信箱（手机写入 / Worker 领取）、日志与结果收集、
+ *       Worker 心跳、托管手机端 Web 控制台。
+ *
+ * 模块划分（lib/）：持久化 store、签名鉴权 auth、API 路由 api、IM 通知 im、
+ * WS 推送 broadcast/websocket、pty 中继 pty、摘要视图 summary、静态文件 static、
+ * 工具 util；本文件只负责装配 ctx 与 HTTP/WS 入口。
+ *
+ * 依赖：ws（WebSocket）、dingbot（钉钉群机器人）、yaml、zod（配置校验，见 config.js）。
+ * 其余为 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 快速开始）
+ *   workerSecret       可选，Worker 专用密钥；配置后 Worker 侧 API 与 /worker/ws
+ *                      只认该密钥，控制台密钥泄露不再等于 Worker 执行权；
+ *                      留空则两端共用 apiSecret
+ *   workerSecrets      可选，workerId -> 密钥映射（多 Worker 各自专属密钥）；
+ *                      验签命中映射条目即绑定该 Worker 身份（自报 workerId 须一致），
+ *                      Worker 间无法互相冒充；与 workerSecret 可并存（命中共享
+ *                      密钥时身份自报，兼容旧部署）
+ *   port               可选，默认 8787
+ *   dataDir             可选，持久化目录，默认 ~/.kites/data；
+ *                      相对路径相对启动工作目录解析，建议写绝对路径；
+ *                      启动前校验可创建、可写，不满足直接报错退出
+ *   logFile             可选，程序自写日志文件，默认 ~/.kites/logs/server.log；
+ *                       超 10MB 轮转并逐代顺延（.1 最新）；stdout 输出不受影响
+ *   logLevel            可选，日志落盘最低级别（debug|info|warn|error），默认 info；
+ *                       只过滤落盘，前台输出不受影响
+ *   logKeep             可选，轮转保留代数（server.log.1 … .N），默认 5
+ *   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 path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadServerConfig } from '../lib/config.js';
+import { enableLogFile } from '../lib/logger.js';
+import { json } from '../lib/util.js';
+import { taskSummary } from '../lib/summary.js';
+import { createChannels } from '../lib/broadcast.js';
+import { createStore } from '../lib/store.js';
+import { createImNotifier } from '../lib/im.js';
+import { createPtyHub } from '../lib/pty.js';
+import { createAuth } from '../lib/auth.js';
+import { createApi } from '../lib/api.js';
+import { createStaticServer } from '../lib/static.js';
+import { createWebSockets } from '../lib/websocket.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const cfg = await loadServerConfig();
+// 日志落盘（logs/ 标准目录）：只包装 console 追加写文件，stdout/journal 捕获不受影响；
+// 落盘级别与轮转保留代数随配置走（行格式与轮转策略见 lib/logger.js）
+enableLogFile(cfg.logFile, { level: cfg.logLevel, keep: cfg.logKeep });
+const WEB_DIR = path.join(__dirname, '..', 'web');
+
+// ---------------------------------------------------------------------------
+// ctx 装配：各 lib 模块共享的运行时上下文。装配顺序即依赖顺序；
+// 跨模块调用（如 sweepStaleRunning -> broadcast/notifyIm）都发生在运行期，
+// 晚于装配完成，故经 ctx 间接引用无时序问题。
+// ---------------------------------------------------------------------------
+
+const ctx = { cfg };
+Object.assign(ctx, createChannels());
+ctx.taskSummary = taskSummary;
+Object.assign(ctx, createStore(ctx));
+ctx.notifyIm = createImNotifier(ctx);
+Object.assign(ctx, createPtyHub(ctx));
+ctx.auth = createAuth(ctx);
+ctx.handleApi = createApi(ctx);
+const serveStatic = createStaticServer(WEB_DIR);
+const { wss, workerWss } = createWebSockets(ctx);
+
+// dataDir 的存在性与可写性已由 config.js 启动校验保证
+await ctx.loadState();
+
+// ---------------------------------------------------------------------------
+// HTTP 入口
+// ---------------------------------------------------------------------------
+
+const server = http.createServer(async (req, res) => {
+  let pathname = '';
+  try {
+    const url = new URL(req.url, 'http://localhost');
+    pathname = url.pathname;
+
+    // 探活端点：反代/uptime 监控（Caddy health、Uptime Kuma 等）直接 GET 即可，
+    // 不参与签名鉴权，只回固定 { ok: true }，不暴露任何状态与数据
+    if (req.method === 'GET' && pathname === '/health') {
+      return json(res, 200, { ok: true });
+    }
+
+    if (pathname.startsWith('/api/')) {
+      // 验签失败限流：超阈值直接拒，不再读 body 做 HMAC，防止刷 401 耗资源
+      if (ctx.auth.authLimitExceeded(req.socket.remoteAddress)) {
+        return json(res, 429, { error: 'auth failures rate limited' });
+      }
+      // 先验签（读原始 body 计算摘要），通过后才进入业务路由；
+      // 密钥按路由角色选择（见 secretsForPath）
+      const auth = await ctx.auth.verifyRestSignature(req, ctx.auth.secretsForPath(pathname));
+      if (!auth.ok) {
+        ctx.auth.recordAuthFailure(req.socket.remoteAddress);
+        console.warn(
+          `[server] 拒绝请求 ${req.method} ${pathname}，来源 ${req.socket.remoteAddress}：${auth.reason}`,
+        );
+        return json(res, 401, { error: 'unauthorized' });
+      }
+      return await ctx.handleApi(req, res, pathname, auth.rawBody, auth.workerId);
+    }
+
+    if (req.method === 'GET') return serveStatic(req, res, pathname);
+
+    return json(res, 405, { error: 'method not allowed' });
+  } catch (err) {
+    const statusCode = err.statusCode || (err.message === 'invalid json' ? 400 : 500);
+    if (statusCode >= 500) {
+      // 内部异常只记服务端日志，响应不外泄细节（可能含路径等内部信息）
+      console.error(`[server] 请求处理异常 ${req.method} ${pathname}: ${err.stack || err.message}`);
+      return json(res, 500, { error: 'internal error' });
+    }
+    return json(res, statusCode, { error: err.message || 'bad request' });
+  }
+});
+
+// 两条通道共用同一 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();
+      ctx.wsClients.delete(ws);
+      ctx.wsWorkers.delete(ws);
+      continue;
+    }
+    ws.isAlive = false;
+    ws.ping();
+  }
+  ctx.sweepPtyIdle();
+}, 30 * 1000).unref();
+
+server.listen(cfg.port, () => {
+  console.log(`[server] kite API listening on :${cfg.port}`);
+  console.log(`[server] config file: ${cfg.configFile}`);
+  console.log(`[server] data dir: ${cfg.dataDir}`);
+  console.log(`[server] log file: ${cfg.logFile}`);
+  const boundEntries = cfg.workerAuth.filter((e) => e.workerId);
+  const sharedEntry = cfg.workerAuth.find((e) => !e.workerId);
+  let authMode;
+  if (boundEntries.length) {
+    authMode = `多 Worker 密钥（${boundEntries.map((e) => e.workerId).join(', ')}` +
+      `${sharedEntry ? '，另有共享 workerSecret' : ''}）`;
+  } else if (sharedEntry && sharedEntry.secret === cfg.apiSecret) {
+    authMode = '单密钥（控制台与 Worker 共用 apiSecret）';
+  } else {
+    authMode = '双密钥（控制台/Worker 已分离）';
+  }
+  console.log(`[server] auth mode: ${authMode}`);
+});

package/config.example.yaml

@@ -26,9 +26,19 @@ workerSecret: ""
 # 监听端口
 port: 8787
 
-# 持久化目录；建议写绝对路径；相对路径相对启动工作目录解析，
-# 支持 ~ 展开；留空/删掉该行则默认 ~/.kite/data
-dataDir: ./data
+# 持久化目录（~/.kites 标准树的 data/）；建议写绝对路径；相对路径相对启动
+# 工作目录解析，支持 ~ 展开；留空/删掉该行则默认 ~/.kites/data
+dataDir: ~/.kites/data
+
+# 程序自写日志文件（~/.kites 标准树的 logs/）；stdout 输出不受影响；
+# 超 10MB 轮转并逐代顺延（server.log.1 最新）；留空/删掉该行则默认 ~/.kites/logs/server.log
+logFile: ~/.kites/logs/server.log
+
+# 日志落盘最低级别（debug|info|warn|error）；只过滤落盘，前台输出不受影响
+logLevel: info
+
+# 轮转保留代数（server.log.1 … server.log.N），超出自动删除最旧一代
+logKeep: 5
 
 # 终态（done/failed/canceled）任务最多保留条数
 maxTasks: 200

package/deploy/kiteserver.service

@@ -11,8 +11,8 @@ After=network.target
 [Service]
 Type=simple
 User=www-data
-# 配置文件与 data 目录的家；server.yaml 里 dataDir: ./data 相对此目录解析
-WorkingDirectory=/opt/kite
+# ~/.kites 标准树（conf/data/logs）的家；unit 以 www-data 运行，家目录即 /var/www/.kites
+WorkingDirectory=/var/www/.kites
 # 配置只认 --config 传入的 YAML 文件（不再读环境变量），模板见包内 config.example.yaml；
 # 启动服务必须显式走 start 子命令（裸调用只打印用法不会启动）
 ExecStart=__KITES_BIN__ start --config __CONFIG_FILE__

package/lib/api.js

@@ -0,0 +1,209 @@
+/**
+ * API 路由：Worker 领取/心跳/上报，控制台建任务/查询/取消/关终端。
+ */
+
+import crypto from 'node:crypto';
+import { json, parseBody, publicTask } from './util.js';
+import { workersSnapshot } from './summary.js';
+
+const MAX_LOG_LINES = 2000;
+// pending 任务数上限：密钥泄露/控制台失守时防无限灌任务撑爆内存与 tasks.json
+// （pruneFinishedTasks 只清终态，堆积的 pending 没有任何自然出口）
+const MAX_PENDING_TASKS = 100;
+
+export function createApi(ctx) {
+  // 身份绑定：配置 workerSecrets 时验签密钥即决定 Worker 身份；
+  // 自报 workerId 与绑定身份不一致返回 null，调用方按 401 拒绝
+  function resolveWorkerId(authedWorkerId, bodyWorkerId) {
+    const claimed = String(bodyWorkerId || 'unknown').slice(0, 128);
+    if (authedWorkerId && claimed !== authedWorkerId) return null;
+    return authedWorkerId || claimed;
+  }
+
+  // 归属校验（仅身份绑定生效时启用）：只允许领取者上报日志/结果，
+  // 防止其他 Worker 伪造他人任务（含未领取任务）的日志与终态；
+  // 共享密钥模式（authedWorkerId 为 null）维持旧行为
+  function canReportTask(task, authedWorkerId) {
+    return !authedWorkerId || task.workerId === authedWorkerId;
+  }
+
+  async function handleApi(req, res, pathname, rawBody, authedWorkerId) {
+    ctx.sweepStaleRunning();
+    const body = parseBody(rawBody);
+
+    // --- Worker：领取最老的 pending 任务（原子置为 running）---
+    if (req.method === 'POST' && pathname === '/api/worker/claim') {
+      const workerId = resolveWorkerId(authedWorkerId, body.workerId);
+      if (!workerId) return json(res, 401, { error: 'workerId 与密钥绑定的身份不一致' });
+      // 显式指派模型：只领取指名给本 Worker 的任务，Worker 之间不存在竞争
+      const task = ctx.state.tasks.find(
+        (t) => t.status === 'pending' && t.targetWorker === workerId,
+      );
+      if (!task) return json(res, 200, { task: null });
+      task.status = 'running';
+      task.workerId = workerId;
+      task.startedAt = Date.now();
+      ctx.scheduleSave();
+      ctx.broadcast({ type: 'task.updated', task: ctx.taskSummary(task) });
+      return json(res, 200, { task });
+    }
+
+    // --- Worker：心跳 ---
+    if (req.method === 'POST' && pathname === '/api/worker/heartbeat') {
+      const workerId = resolveWorkerId(authedWorkerId, body.workerId);
+      if (!workerId) return json(res, 401, { error: 'workerId 与密钥绑定的身份不一致' });
+      ctx.state.heartbeats[workerId] = {
+        at: Date.now(),
+        hostname: String(body.hostname || '').slice(0, 128),
+        node: String(body.node || '').slice(0, 64),
+        // workspace 下的项目目录列表（控制台据此渲染终端起始目录下拉）
+        projects: Array.isArray(body.projects)
+          ? body.projects.map((p) => String(p).slice(0, 64)).slice(0, 64)
+          : [],
+      };
+      ctx.scheduleSave();
+      ctx.broadcast({ type: 'workers', workers: workersSnapshot(ctx.state.heartbeats) });
+      return json(res, 200, { ok: true });
+    }
+
+    // --- Worker / 控制台：查询 Worker 在线状态 ---
+    if (req.method === 'GET' && pathname === '/api/worker/status') {
+      return json(res, 200, { workers: workersSnapshot(ctx.state.heartbeats) });
+    }
+
+    // --- 创建任务（pending 超限拒绝，见 MAX_PENDING_TASKS）---
+    if (req.method === 'POST' && pathname === '/api/tasks') {
+      const type = String(body.type || '');
+      if (type !== 'pty') {
+        return json(res, 400, { error: 'type 必须是 pty' });
+      }
+      const pendingCount = ctx.state.tasks.filter((t) => t.status === 'pending').length;
+      if (pendingCount >= MAX_PENDING_TASKS) {
+        return json(res, 429, { error: `待执行任务已达上限（${MAX_PENDING_TASKS}），请先消化积压` });
+      }
+      // 显式指派模型：targetWorker 必填且必须是已注册（心跳过）的 Worker，
+      // 杜绝无人可领的孤儿任务永远 pending
+      const tw = String(body.targetWorker || '').trim().slice(0, 128);
+      if (!tw) {
+        return json(res, 400, { error: '必须指定目标 Worker（targetWorker）' });
+      }
+      if (!/^[\w.-]{1,128}$/.test(tw)) {
+        return json(res, 400, { error: 'targetWorker 只能含字母/数字/._-' });
+      }
+      if (!ctx.state.heartbeats[tw]) {
+        return json(res, 400, { error: `Worker "${tw}" 从未注册，无法指派` });
+      }
+      const targetWorker = tw;
+      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,
+        targetWorker,
+      };
+      ctx.state.tasks.push(task);
+      ctx.scheduleSave();
+      ctx.broadcast({ type: 'task.created', task: ctx.taskSummary(task) });
+      ctx.notifyWorkers(targetWorker); // 任务到达即推送，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 = [...ctx.state.tasks]
+        .sort((a, b) => b.createdAt - a.createdAt)
+        .slice(0, limit)
+        .map(ctx.taskSummary);
+      return json(res, 200, { tasks: list });
+    }
+
+    // --- 单个任务详情（含日志）---
+    const taskMatch = pathname.match(/^\/api\/tasks\/([0-9a-f-]{36})$/);
+    if (req.method === 'GET' && taskMatch) {
+      const task = ctx.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 = ctx.state.tasks.find((t) => t.id === logMatch[1]);
+      if (!task) return json(res, 404, { error: 'task not found' });
+      if (!canReportTask(task, authedWorkerId)) {
+        return json(res, 403, { error: '只能上报自己领取的任务' });
+      }
+      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);
+      }
+      ctx.scheduleSave();
+      ctx.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 = ctx.state.tasks.find((t) => t.id === finishMatch[1]);
+      if (!task) return json(res, 404, { error: 'task not found' });
+      if (!canReportTask(task, authedWorkerId)) {
+        return json(res, 403, { error: '只能上报自己领取的任务' });
+      }
+      // 状态守卫：已到终态（被 sweepStaleRunning 判失败回收、控制台取消等）的任务
+      // 拒绝迟到的 finish，防止短暂失联后"复活"的 Worker 把终态翻回
+      if (task.status !== 'running') {
+        return json(res, 409, { error: `任务已处于终态（${task.status}），拒绝 finish 上报` });
+      }
+      task.status = body.status === 'done' ? 'done' : 'failed';
+      task.result = body.result ?? null;
+      task.finishedAt = Date.now();
+      ctx.scheduleSave();
+      ctx.broadcast({ type: 'task.updated', task: ctx.taskSummary(task), result: task.result });
+      ctx.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 = ctx.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();
+      ctx.scheduleSave();
+      ctx.broadcast({ type: 'task.updated', task: ctx.taskSummary(task) });
+      ctx.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 = ctx.ptySessions.get(killMatch[1]);
+      if (!s) return json(res, 404, { error: '没有活跃的终端会话' });
+      ctx.wsSendJson(s.ws, { type: 'session.close', taskId: killMatch[1] });
+      return json(res, 200, { ok: true });
+    }
+
+    return json(res, 404, { error: 'not found' });
+  }
+
+  return handleApi;
+}

package/lib/auth.js

@@ -0,0 +1,130 @@
+/**
+ * 签名鉴权：HMAC-SHA256(密钥, METHOD\nPATH\nTS\nNONCE\nSHA256(BODY))
+ * 密钥永不上网；时间窗 + nonce 缓存联合防重放。
+ * 密钥按路由角色选择：控制台 API 用 apiSecret，Worker API 用 workerAuth
+ * 条目列表（workerSecrets 绑定密钥 / 共享 workerSecret / 回落 apiSecret）。
+ * 另含验签失败限流。
+ */
+
+import crypto from 'node:crypto';
+import { timingSafeEqualStr } from './util.js';
+
+export function createAuth(ctx) {
+  const { apiSecret: API_SECRET, workerAuth: WORKER_AUTH, sigWindowSec: SIG_WINDOW_SEC } = ctx.cfg;
+
+  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, secret) {
+    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', 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) {
+          const err = new Error('body too large');
+          err.statusCode = 413; // 明确为客户端错误，响应里可安全回显
+          reject(err);
+          req.destroy();
+          return;
+        }
+        chunks.push(chunk);
+      });
+      req.on('end', () => resolve(Buffer.concat(chunks)));
+      req.on('error', reject);
+    });
+  }
+
+  // REST 请求验签：签名覆盖方法、路径、时间戳、nonce 与请求体摘要。
+  // 注意：路径用含 query 的完整形式（与客户端签名方式一致，防止改写查询参数）。
+  // entries 为该路由可接受的密钥条目列表（{ secret, workerId }，按序尝试，
+  // 验过任一即通过）；workerId 非 null 表示该密钥绑定了 Worker 身份
+  // （workerSecrets 条目），null 表示身份自报（共享密钥兼容路径）。
+  // nonce 只在验过之后消费，失败尝试不留副作用。
+  async function verifyRestSignature(req, entries) {
+    const rawBody = await readRawBody(req);
+    const bodySha = crypto.createHash('sha256').update(rawBody).digest('hex');
+    const parts = [req.method, req.url, req.headers['x-rw-ts'], req.headers['x-rw-nonce'], bodySha];
+    let result = { ok: false, reason: '缺少签名头 X-RW-Ts/X-RW-Nonce/X-RW-Sig' };
+    let workerId = null;
+    for (const entry of entries) {
+      result = verifySignature(parts, req.headers['x-rw-ts'], req.headers['x-rw-nonce'], req.headers['x-rw-sig'], entry.secret);
+      if (result.ok) {
+        workerId = entry.workerId;
+        break;
+      }
+    }
+    return { ...result, rawBody, workerId };
+  }
+
+  // 路由 -> 可接受的密钥条目：Worker 侧 API 只认 WORKER_AUTH 条目，控制台只认
+  // API_SECRET；worker/status 两端都要读（控制台轮询兜底也用），两边密钥都放行
+  const WORKER_PATH = /^\/api\/(worker\/(claim|heartbeat)|tasks\/[0-9a-f-]{36}\/(logs|finish))$/;
+  function secretsForPath(pathname) {
+    if (pathname === '/api/worker/status') {
+      return [{ secret: API_SECRET, workerId: null }, ...WORKER_AUTH];
+    }
+    return WORKER_PATH.test(pathname) ? WORKER_AUTH : [{ secret: API_SECRET, workerId: null }];
+  }
+
+  // 验签失败限流：单 IP 滑动窗口（60s/30 次），防止恶意刷 401 灌日志耗 CPU；
+  // 只统计失败，成功请求不计（正常轮询频率不会触限）
+  const authFailures = new Map(); // ip -> { count, windowStart }
+  function authLimitExceeded(ip) {
+    const rec = authFailures.get(ip);
+    return Boolean(rec && Date.now() - rec.windowStart <= 60_000 && rec.count >= 30);
+  }
+  function recordAuthFailure(ip) {
+    const now = Date.now();
+    if (authFailures.size > 10_000) {
+      for (const [k, rec] of authFailures) if (now - rec.windowStart > 60_000) authFailures.delete(k);
+    }
+    let rec = authFailures.get(ip);
+    if (!rec || now - rec.windowStart > 60_000) {
+      rec = { count: 0, windowStart: now };
+      authFailures.set(ip, rec);
+    }
+    rec.count++;
+  }
+
+  return { verifySignature, verifyRestSignature, secretsForPath, authLimitExceeded, recordAuthFailure };
+}