@maiyunnet/kebab 9.21.0 → 9.21.2

package/lib/core.js

@@ -830,7 +830,7 @@ export async function sendNpm(path, hosts) {
             'time': time,
             'path': path
         }), globalConfig.rpcSecret), {
-            'timeout': 300,
+            'timeout': 330,
         });
         const content = await res.getContent();
         if (!content) {
@@ -938,7 +938,7 @@ export async function updateCode(sourcePath, path, hosts, config = true, strict
             'action': 'code',
             'time': lTime.stamp()
         }), globalConfig.rpcSecret), fd, {
-            'timeout': 60,
+            'timeout': 180,
         });
         const content = await res.getContent();
         if (!content) {
@@ -1182,6 +1182,87 @@ export async function getLog(opt) {
         'total': res.total,
     };
 }
+/**
+ * --- 通过 master RPC 读取已保存的监控数据，不依赖目标 HTTP 子进程 ---
+ * @param action 要读取的监控资源
+ * @param opt 读取参数，host 默认本机
+ * @returns 响应对象；配置或网络错误时返回 false
+ */
+async function requestMonitor(action, opt) {
+    if (!Number.isInteger(globalConfig.rpcPort) || typeof globalConfig.rpcSecret !== 'string') {
+        return false;
+    }
+    const command = lCrypto.aesEncrypt(lText.stringifyJson({
+        action, 'time': lTime.stamp(), 'path': opt.path, 'offset': opt.offset,
+        'limit': opt.limit, 'preview': opt.preview,
+    }), globalConfig.rpcSecret);
+    const res = await lUndici.get(`http://${opt.host ?? '127.0.0.1'}:${globalConfig.rpcPort}/${command}`, {
+        'timeout': action === 'monitor-file' ? 300 : 5,
+        'follow': 0,
+    });
+    if (res.error || !res.headers) {
+        await res.getRawStream()?.dump({ 'limit': 4096 });
+        return false;
+    }
+    return res;
+}
+/**
+ * --- 获取某天已保存的监控事件，按目录时间倒序分页 ---
+ * @param opt path 为 YYYY/MM/DD，默认目标服务器的当天；offset 默认 0，limit 默认 20、最多 100
+ * @returns 事件列表和总数；无事件时返回空列表，参数、配置或读取错误时返回 false
+ */
+export async function getMonitorEvents(opt = {}) {
+    const res = await requestMonitor('monitor-events', opt);
+    if (res === false) {
+        return false;
+    }
+    const text = await res.getText();
+    if (text === null) {
+        return false;
+    }
+    const result = lText.parseJson(text);
+    if (!result || result.result !== 1 || !Array.isArray(result.list) || !Number.isSafeInteger(result.total)) {
+        return false;
+    }
+    return { 'list': result.list, 'total': result.total };
+}
+/**
+ * --- 读取事件详情和文件清单；只解析事件记录，不解析 Profile 或堆快照 ---
+ * @param opt path 使用 getMonitorEvents 返回的事件路径；host 默认本机
+ * @returns 事件详情；不存在时返回 null，参数、配置或读取错误时返回 false
+ */
+export async function getMonitorEvent(opt) {
+    const res = await requestMonitor('monitor-event', opt);
+    if (res === false) {
+        return false;
+    }
+    const text = await res.getText();
+    if (text === null) {
+        return false;
+    }
+    const result = lText.parseJson(text);
+    if (!result || result.result !== 1 || result.data === undefined) {
+        return false;
+    }
+    return result.data;
+}
+/**
+ * --- 获取监控原始文件的响应，可使用 getStream() 下载；小文件可用 getText()/getJson() 预览 ---
+ * @param opt path 使用事件 files 中的文件路径；preview=true 只允许 1 MiB 内的 JSON/调用栈文本；host 默认本机
+ * @returns 文件响应；不存在时返回 null，参数、预览限制、配置或读取错误时返回 false；流消费或销毁由调用方负责
+ */
+export async function getMonitorFile(opt) {
+    const res = await requestMonitor('monitor-file', opt);
+    if (res === false) {
+        return false;
+    }
+    if (res.headers?.['http-code'] === 200 && res.headers['x-kebab-monitor-file'] === '1') {
+        return res;
+    }
+    // --- 有界丢弃错误响应；直接 destroy 未消费的 Undici 流会产生未处理的 AbortError ---
+    await res.getRawStream()?.dump({ 'limit': 4096 });
+    return res.headers?.['http-code'] === 404 ? null : false;
+}
 /**
  * --- 获取目录内文件/文件夹列表 ---
  * @param opt 参数

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maiyunnet/kebab",
-  "version": "9.21.0",
+  "version": "9.21.2",
   "description": "Simple, easy-to-use, and fully-featured Node.js framework that is ready-to-use out of the box.",
   "type": "module",
   "keywords": [

package/sys/master.js

@@ -8,9 +8,11 @@ import * as os from 'os';
 import * as fs from 'fs';
 import * as http from 'http';
 import * as path from 'path';
+import * as stream from 'stream/promises';
 // --- 库和定义 ---
 import * as kebab from '#kebab/index.js';
 import * as sRoute from '#kebab/sys/route.js';
+import * as sMonitorFiles from '#kebab/sys/monitor/files.js';
 import * as lCore from '#kebab/lib/core.js';
 import * as lFs from '#kebab/lib/fs.js';
 import * as lText from '#kebab/lib/text.js';
@@ -918,6 +920,58 @@ function createRpcListener() {
                     }));
                     return;
                 }
+                case 'monitor-events': {
+                    const result = await sMonitorFiles.getEvents(path.join(kebab.LOG_CWD, 'monitor'), msg.path ?? lTime.format(null, 'Y/m/d'), msg.offset ?? 0, msg.limit ?? 20);
+                    res.setHeader('cache-control', 'no-store');
+                    res.end(lText.stringifyJson(result === false ? { 'result': 0 } : { 'result': 1, ...result }));
+                    return;
+                }
+                case 'monitor-event': {
+                    const data = await sMonitorFiles.getEvent(path.join(kebab.LOG_CWD, 'monitor'), msg.path);
+                    res.setHeader('cache-control', 'no-store');
+                    res.end(lText.stringifyJson(data === false ? { 'result': 0 } : { 'result': 1, data }));
+                    return;
+                }
+                case 'monitor-file': {
+                    const file = await sMonitorFiles.getFile(path.join(kebab.LOG_CWD, 'monitor'), msg.path);
+                    res.setHeader('cache-control', 'no-store');
+                    if (file === false || msg.preview !== undefined && typeof msg.preview !== 'boolean') {
+                        res.writeHead(400);
+                        res.end();
+                        return;
+                    }
+                    if (file === null) {
+                        res.writeHead(404);
+                        res.end();
+                        return;
+                    }
+                    if (msg.preview && file.info.preview === null) {
+                        res.writeHead(file.stat.size > sMonitorFiles.PREVIEW_LIMIT ? 413 : 415);
+                        res.end();
+                        return;
+                    }
+                    let contentType = 'application/octet-stream';
+                    if (msg.preview) {
+                        contentType = file.info.preview === 'json' ? 'application/json; charset=utf-8' : 'text/plain; charset=utf-8';
+                    }
+                    res.setHeader('content-type', contentType);
+                    res.setHeader('x-content-type-options', 'nosniff');
+                    res.setHeader('x-kebab-monitor-file', '1');
+                    res.setHeader('content-disposition', `attachment; filename="${file.info.name}"`);
+                    res.setHeader('content-length', file.stat.size);
+                    if (file.stat.size === 0) {
+                        res.end();
+                        return;
+                    }
+                    // --- 原始字节直接传输；pipeline 在客户端断开时关闭文件流，不整文件读取或压缩 ---
+                    try {
+                        await stream.pipeline(fs.createReadStream(file.path, { 'start': 0, 'end': file.stat.size - 1 }), res);
+                    }
+                    catch {
+                        res.destroy();
+                    }
+                    return;
+                }
                 case 'ls': {
                     // --- 获取目录内文件/文件夹列表 ---
                     if (typeof msg.path !== 'string') {

package/sys/monitor/files.d.ts

@@ -0,0 +1,34 @@
+import type { Stats } from 'fs';
+import type { IMonitorEvent, IMonitorEventSummary, IMonitorFile } from '#kebab/lib/core.js';
+/** --- 小型 JSON/文本预览上限，Profile 和堆快照不预览 --- */
+export declare const PREVIEW_LIMIT: number;
+/**
+ * --- 获取一天的事件摘要，先分页目录再读取记录 ---
+ * @param root log/monitor 的绝对路径
+ * @param day YYYY/MM/DD
+ * @param offset 跳过目录数量
+ * @param limit 返回数量，1-100
+ * @returns 列表和总数；目录不存在返回空列表，输入或读取错误返回 false
+ */
+export declare function getEvents(root: string, day: unknown, offset?: unknown, limit?: unknown): Promise<{
+    'list': IMonitorEventSummary[];
+    'total': number;
+} | false>;
+/**
+ * --- 获取允许读取的诊断文件及其元数据，文件路径限制在日期/事件目录下 ---
+ * @param root log/monitor 的绝对路径
+ * @param relative files 中返回的文件相对路径
+ * @returns 真实路径、文件状态和元数据；不存在返回 null，非法路径或读取错误返回 false
+ */
+export declare function getFile(root: string, relative: unknown): Promise<{
+    'path': string;
+    'stat': Stats;
+    'info': IMonitorFile;
+} | null | false>;
+/**
+ * --- 获取事件原始数据及文件清单，包含 diagnostics 引用的看门狗取证文件 ---
+ * @param root log/monitor 的绝对路径
+ * @param relative 事件相对路径
+ * @returns 事件详情；不存在返回 null，非法路径或读取错误返回 false
+ */
+export declare function getEvent(root: string, relative: unknown): Promise<IMonitorEvent | null | false>;

package/sys/monitor/files.js

@@ -0,0 +1,260 @@
+/** --- master 读取落盘监控数据；只读取有界事件 JSON，Profile 和堆快照仅提供文件元数据 --- */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as lText from '#kebab/lib/text.js';
+/** --- 单个事件记录读取上限，避免损坏或异常大的文件占用 master 内存 --- */
+const RECORD_LIMIT = 4 * 1024 * 1024;
+/** --- 小型 JSON/文本预览上限，Profile 和堆快照不预览 --- */
+export const PREVIEW_LIMIT = 1024 * 1024;
+const DAY_PATTERN = /^\d{4}\/\d{2}\/\d{2}$/;
+const EVENT_NAME_PATTERN = /^\d{6}-pid-\d+(?:-\d+)?(?:-blocked)?$/;
+const FILE_NAME_PATTERNS = [
+    /^(?:event\.json|blocked-event\.json|(?:report|profile)-[\w.-]+\.json)$/,
+    /^(?:cpu|blocked-cpu)-[\w.-]+\.cpuprofile$/,
+    /^blocked-stack-[\w.-]+\.txt$/,
+    /^heap-[\w.-]+\.heapsnapshot$/,
+];
+/**
+ * --- 仅开放框架生成的监控取证文件名 ---
+ * @param name 文件名
+ * @returns 是否为诊断文件
+ */
+function isFileName(name) {
+    return FILE_NAME_PATTERNS.some(pattern => pattern.test(name));
+}
+/**
+ * --- 解析监控目录内已有路径，阻止目录穿越和符号链接逃逸 ---
+ * @param root log/monitor 的绝对路径
+ * @param relative 已校验格式的相对路径
+ * @returns 真实路径；不存在时返回 null，越界或读取错误时返回 false
+ */
+async function resolveInside(root, relative) {
+    try {
+        if ((await fs.lstat(root)).isSymbolicLink()) {
+            return false;
+        }
+        const rootReal = await fs.realpath(root);
+        const target = await fs.realpath(path.join(rootReal, relative));
+        const difference = path.relative(rootReal, target);
+        if (difference === '..' || difference.startsWith(`..${path.sep}`) || path.isAbsolute(difference)) {
+            return false;
+        }
+        return target;
+    }
+    catch (error) {
+        return error.code === 'ENOENT' ? null : false;
+    }
+}
+/**
+ * --- 校验事件相对路径，不接受绝对路径、反斜杠或多余层级 ---
+ * @param relative 事件路径
+ * @returns 是否为日期下的事件目录
+ */
+function isEventPath(relative) {
+    if (typeof relative !== 'string') {
+        return false;
+    }
+    const parts = relative.split('/');
+    return parts.length === 4 && DAY_PATTERN.test(parts.slice(0, 3).join('/')) && EVENT_NAME_PATTERN.test(parts[3]);
+}
+/**
+ * --- 有界读取原始事件；没有记录的旧诊断目录仍可列出文件 ---
+ * @param directory 事件真实目录
+ * @returns 原始数据及读取状态
+ */
+async function readRecord(directory) {
+    for (const name of ['event.json', 'blocked-event.json']) {
+        let handle = null;
+        try {
+            // --- 拒绝事件记录本身的符号链接；读取过程中即使文件增长也不会超过上限 ---
+            const stat = await fs.lstat(path.join(directory, name));
+            if (!stat.isFile() || stat.isSymbolicLink()) {
+                return { 'data': null, 'status': 'unreadable' };
+            }
+            if (stat.size > RECORD_LIMIT) {
+                return { 'data': null, 'status': 'too-large' };
+            }
+            handle = await fs.open(path.join(directory, name), fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+            const buffer = Buffer.alloc(stat.size + 1);
+            const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+            if (bytesRead > RECORD_LIMIT) {
+                return { 'data': null, 'status': 'too-large' };
+            }
+            const data = lText.parseJson(buffer.subarray(0, bytesRead).toString('utf8'));
+            if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+                return { 'data': null, 'status': 'invalid' };
+            }
+            return { 'data': data, 'status': 'loaded' };
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                return { 'data': null, 'status': 'unreadable' };
+            }
+        }
+        finally {
+            await handle?.close();
+        }
+    }
+    return { 'data': null, 'status': 'missing' };
+}
+/**
+ * --- 从目录名和事件记录生成简短摘要，不携带大段采样或调用栈 ---
+ * @param relative 事件相对路径
+ * @param record 原始事件读取结果
+ * @returns 事件摘要
+ */
+function summarize(relative, record) {
+    const [year, month, day, name] = relative.split('/');
+    const parts = name.split('-');
+    const time = Number(parts[3]) || new Date(`${year}-${month}-${day}T${parts[0].slice(0, 2)}:${parts[0].slice(2, 4)}:${parts[0].slice(4, 6)}`).getTime();
+    const data = record.data;
+    const source = name.endsWith('-blocked') ? 'watchdog' : 'main';
+    let status = record.status === 'loaded' ? 'active' : record.status;
+    if (typeof data?.endReason === 'string') {
+        status = data.endReason;
+    }
+    else if (typeof data?.status === 'string') {
+        status = data.status;
+    }
+    let eventTime = time;
+    if (typeof data?.confirmedAt === 'number') {
+        eventTime = data.confirmedAt;
+    }
+    else if (typeof data?.time === 'number') {
+        eventTime = data.time;
+    }
+    let reasons = [];
+    if (Array.isArray(data?.reasons)) {
+        reasons = data.reasons.filter((reason) => typeof reason === 'string');
+    }
+    else if (source === 'watchdog') {
+        reasons = ['ELOOP_BLOCKED'];
+    }
+    return {
+        'path': relative,
+        'pid': typeof data?.pid === 'number' ? data.pid : Number(parts[2]),
+        'time': eventTime,
+        source, status, reasons,
+    };
+}
+/**
+ * --- 获取一天的事件摘要，先分页目录再读取记录 ---
+ * @param root log/monitor 的绝对路径
+ * @param day YYYY/MM/DD
+ * @param offset 跳过目录数量
+ * @param limit 返回数量，1-100
+ * @returns 列表和总数；目录不存在返回空列表，输入或读取错误返回 false
+ */
+export async function getEvents(root, day, offset = 0, limit = 20) {
+    if (typeof day !== 'string' || !DAY_PATTERN.test(day) || !Number.isSafeInteger(offset) ||
+        typeof offset !== 'number' || offset < 0 || !Number.isSafeInteger(limit) || typeof limit !== 'number' || limit < 1 || limit > 100) {
+        return false;
+    }
+    const directory = await resolveInside(root, day);
+    if (directory === false) {
+        return false;
+    }
+    if (directory === null) {
+        return { 'list': [], 'total': 0 };
+    }
+    try {
+        const entries = await fs.readdir(directory, { 'withFileTypes': true });
+        const names = entries.filter(entry => entry.isDirectory() && EVENT_NAME_PATTERN.test(entry.name))
+            .map(entry => entry.name).sort().reverse();
+        const list = [];
+        for (const name of names.slice(offset, offset + limit)) {
+            const relative = `${day}/${name}`;
+            const record = await readRecord(path.join(directory, name));
+            list.push(summarize(relative, record));
+        }
+        return { list, 'total': names.length };
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * --- 获取允许读取的诊断文件及其元数据，文件路径限制在日期/事件目录下 ---
+ * @param root log/monitor 的绝对路径
+ * @param relative files 中返回的文件相对路径
+ * @returns 真实路径、文件状态和元数据；不存在返回 null，非法路径或读取错误返回 false
+ */
+export async function getFile(root, relative) {
+    if (typeof relative !== 'string' || !isEventPath(path.posix.dirname(relative)) || !isFileName(path.posix.basename(relative))) {
+        return false;
+    }
+    const file = await resolveInside(root, relative);
+    if (file === null || file === false) {
+        return file;
+    }
+    try {
+        const stat = await fs.stat(file);
+        if (!stat.isFile()) {
+            return false;
+        }
+        let preview = null;
+        if (stat.size <= PREVIEW_LIMIT) {
+            if (relative.endsWith('.json')) {
+                preview = 'json';
+            }
+            else if (relative.endsWith('.txt')) {
+                preview = 'text';
+            }
+        }
+        return { 'path': file, stat, 'info': {
+                'path': relative, 'name': path.basename(relative), 'size': stat.size, 'mtime': stat.mtimeMs, preview,
+            } };
+    }
+    catch (error) {
+        return error.code === 'ENOENT' ? null : false;
+    }
+}
+/**
+ * --- 获取事件原始数据及文件清单，包含 diagnostics 引用的看门狗取证文件 ---
+ * @param root log/monitor 的绝对路径
+ * @param relative 事件相对路径
+ * @returns 事件详情；不存在返回 null，非法路径或读取错误返回 false
+ */
+export async function getEvent(root, relative) {
+    if (!isEventPath(relative)) {
+        return false;
+    }
+    const directory = await resolveInside(root, relative);
+    if (directory === null || directory === false) {
+        return directory;
+    }
+    try {
+        const record = await readRecord(directory);
+        const entries = await fs.readdir(directory, { 'withFileTypes': true });
+        const candidates = new Set(entries.filter(entry => entry.isFile() && isFileName(entry.name))
+            .map(entry => `${relative}/${entry.name}`));
+        if (Array.isArray(record.data?.diagnostics)) {
+            // --- 主线程事件会引用另一个阻塞目录；只将监控根目录内的文件加入下载清单 ---
+            for (const diagnostic of record.data.diagnostics) {
+                if (diagnostic === null || typeof diagnostic !== 'object') {
+                    continue;
+                }
+                const files = diagnostic.files;
+                if (!Array.isArray(files)) {
+                    continue;
+                }
+                for (const file of files) {
+                    if (typeof file === 'string' && path.isAbsolute(file)) {
+                        candidates.add(path.relative(root, file).split(path.sep).join('/'));
+                    }
+                }
+            }
+        }
+        const files = [];
+        for (const candidate of [...candidates].sort()) {
+            const file = await getFile(root, candidate);
+            if (file !== false && file !== null) {
+                files.push(file.info);
+            }
+        }
+        return { 'summary': summarize(relative, record), 'data': record.data, 'recordStatus': record.status, files };
+    }
+    catch {
+        return false;
+    }
+}