create-ssnode-cli 0.2.4 → 0.2.5

package/templates/backend/src/common/decorators/skip-transform.decorator.ts

@@ -0,0 +1,9 @@
+import { SetMetadata } from '@nestjs/common';
+
+/**
+ * 跳过统一响应包装({ code, message, data })装饰器
+ * 用于 SSE 等事件流路由:响应体是 event-stream 事件序列,不能包 JSON。
+ * TransformInterceptor 检测此元数据直接放行。
+ */
+export const SKIP_TRANSFORM_KEY = 'skipTransform';
+export const SkipTransform = () => SetMetadata(SKIP_TRANSFORM_KEY, true);

package/templates/backend/src/common/jsonl-daily-writer.ts

@@ -0,0 +1,282 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+/**
+ * 按日切 JSONL 写盘器(《后端日志体系整改方案》§2.5,自 slow-sql.logger 抽公共)
+ *
+ * slowsql(性能证据)与 apilog(运维调试)共用的写盘纪律:
+ *   - 按日切文件 <prefix>-YYYY-MM-DD.jsonl,换日/首写 statSync 继承既有长度
+ *   - 单文件上限 MB,超限滚动瘦身(2026-09-24 由丢新条改留新去旧):从文件头砍
+ *     ~50%(行边界对齐,临时文件+原子 rename),排障时刻的日志价值最高,宁可丢旧。
+ *     droppedCount 语义=滚动淘汰的旧行数(不静默:调用方随 stats 留痕)
+ *   - 每日清理超保留期文件(按文件名日期判定,失败静默——日志器绝不拖死业务)
+ *   - 长驻 append 流(2026-09-24 由同步 append 改造):每日只开一次 fd,write 全程
+ *     零同步 I/O、零 syscall 放大——故障风暴时(DB 挂掉每请求都触发登记)日志器
+ *     不再给事件循环加码。write() 签名保持同步 boolean,调用方零改动。
+ *
+ * 三个善后机制:
+ *   - 进程 exit 兜底:未 ack(未到内核)的行同步 appendFileSync 补写;极端时序下
+ *     可能与已在途的写重复一条,崩溃路径的排障日志容忍重复
+ *   - 错误自愈:流挂 'error'(磁盘满/只读 fs)→ 销毁置空,下次 write 重开并重新
+ *     statSync 继承长度
+ *   - 内存背压:已入队未 ack 行超 4MB 硬顶丢条计数(防磁盘卡死时内存无限涨),
+ *     与单日上限共用 droppedCount 口径
+ */
+
+/** 本地时区偏移时间戳(2026-09-21T14:03:05.120+08:00;E2E 时区回传踩过坑,统一带偏移) */
+export function localTs(d = new Date()): string {
+  const pad = (n: number, len = 2) => String(Math.abs(n)).padStart(len, '0');
+  const off = -d.getTimezoneOffset();
+  const sign = off >= 0 ? '+' : '-';
+  return (
+    `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}` +
+    `T${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}.${pad(d.getMilliseconds(), 3)}` +
+    `${sign}${pad(Math.floor(Math.abs(off) / 60))}:${pad(Math.abs(off) % 60)}`
+  );
+}
+
+export interface JsonlDailyWriterOptions {
+  /** 落盘目录 */
+  dir: string;
+  /** 文件名前缀(slowsql / apilog) */
+  prefix: string;
+  /** 保留天数 */
+  retainDays: number;
+  /** 单文件上限 MB(超限滚动瘦身,留新去旧) */
+  maxFileMb: number;
+}
+
+/** 未 ack 行的内存背压硬顶(防磁盘卡死时缓冲无限涨;超限丢条计数) */
+const MAX_PENDING_BYTES = 4 * 1024 * 1024;
+
+/** 滚动瘦身的淘汰比例(砍头部 50%,留同等余量摊薄重写频率:约每半容量新日志才再触发) */
+const TRIM_KEEP_RATIO = 0.5;
+
+/** 本地时区日期键(与文件名 <prefix>-YYYY-MM-DD.jsonl 对齐) */
+function dayKeyOf(d: Date): string {
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+}
+
+export class JsonlDailyWriter {
+  private readonly opts: JsonlDailyWriterOptions;
+  private dayKey = '';
+  private writtenBytes = 0;
+  private stream: fs.WriteStream | null = null;
+  /** 已入队未 ack 的行(write 回调=已到内核;exit 兜底同步补写的依据) */
+  private pending: Array<{ line: string; bytes: number }> = [];
+  private pendingBytes = 0;
+  /** flush() 等待者:pending 清空时唤醒 */
+  private flushWaiters: Array<() => void> = [];
+  private cleanupTimer: NodeJS.Timeout | null = null;
+  /** exit 兜底(process.on 须持引用,stop 时移除防泄漏) */
+  private readonly exitHandler = (): void => this.emergencyFlush();
+
+  /** 滚动淘汰的旧行数(不静默丢弃:调用方随 stats/console 留痕) */
+  public droppedCount = 0;
+
+  constructor(opts: JsonlDailyWriterOptions) {
+    this.opts = opts;
+    try {
+      fs.mkdirSync(this.opts.dir, { recursive: true });
+    } catch {
+      // 目录建不了(只读 fs 等)后续每次写盘都会静默失败——写盘器不拖死业务
+    }
+    process.on('exit', this.exitHandler);
+  }
+
+  /** 写一条(超单文件上限滚动瘦身/内存背压丢条);返回是否接受落盘 */
+  write(record: Record<string, unknown>): boolean {
+    try {
+      const dayKey = dayKeyOf(new Date());
+      if (dayKey !== this.dayKey || !this.stream) {
+        this.rotate(dayKey);
+        if (!this.stream) return false;
+      }
+      const line = `${JSON.stringify(record)}\n`;
+      // 字节计量用 UTF-8 实长(中文一条 3 字节;原 line.length 按 UTF-16 单位少算)
+      const bytes = Buffer.byteLength(line);
+      const cap = this.opts.maxFileMb * 1024 * 1024;
+      if (this.writtenBytes + bytes > cap) {
+        // 留新去旧:砍文件头腾地方;trim 内部会关流,成功后 rotate 重开(继承瘦身后长度)
+        if (!this.trim() || !this.rotate(dayKey) || !this.stream || this.writtenBytes + bytes > cap) {
+          this.droppedCount += 1;
+          return false;
+        }
+      }
+      if (this.pendingBytes + bytes > MAX_PENDING_BYTES) {
+        this.droppedCount += 1;
+        return false;
+      }
+      // 回调=该行已到内核(后续同步读可见):ack 出队并唤醒 flush 等待者。
+      // 带错回调不 ack(行仍留 pending,由 'error' 处理器同步补写),防写失败被误标落盘
+      this.stream.write(line, (err?: Error | null) => {
+        if (!err) this.ack();
+      });
+      this.pending.push({ line, bytes });
+      this.pendingBytes += bytes;
+      this.writtenBytes += bytes;
+      return true;
+    } catch {
+      // 写盘失败(磁盘满/只读 fs):静默——写盘器绝不拖死业务
+      return false;
+    }
+  }
+
+  /** 等所有已入队行到内核(E2E/脚本断言文件内容前用;kill -9 仍拦不住,那是流的固有代价) */
+  flush(): Promise<void> {
+    if (this.pending.length === 0) return Promise.resolve();
+    return new Promise<void>((resolve) => this.flushWaiters.push(resolve));
+  }
+
+  /** 删除超过保留期的 <prefix>-YYYY-MM-DD.jsonl(按文件名日期判定;失败静默);返回删除数 */
+  cleanupExpired(): number {
+    let removed = 0;
+    try {
+      const cutoff = Date.now() - this.opts.retainDays * 24 * 3_600_000;
+      const pattern = new RegExp(`^${this.opts.prefix}-(\\d{4})-(\\d{2})-(\\d{2})\\.jsonl$`);
+      for (const name of fs.readdirSync(this.opts.dir)) {
+        const m = name.match(pattern);
+        if (!m) continue;
+        const fileDate = new Date(Number(m[1]), Number(m[2]) - 1, Number(m[3])).getTime();
+        if (fileDate < cutoff) {
+          try {
+            fs.unlinkSync(path.join(this.opts.dir, name));
+            removed += 1;
+          } catch {
+            // 单文件删除失败不中断其余清理
+          }
+        }
+      }
+    } catch {
+      // 目录不可读等:静默,下次再试
+    }
+    return removed;
+  }
+
+  /** 启动每日自动清理(unref,不阻退出) */
+  startDailyCleanup(): void {
+    if (this.cleanupTimer) return;
+    this.cleanupTimer = setInterval(() => this.cleanupExpired(), 24 * 3_600_000);
+    this.cleanupTimer.unref();
+  }
+
+  /** 关流冲刷并停掉定时器(测试与脚本场景防悬挂);返回后文件内容确定性可见 */
+  stop(): void {
+    if (this.cleanupTimer) clearInterval(this.cleanupTimer);
+    this.cleanupTimer = null;
+    process.removeListener('exit', this.exitHandler);
+    this.emergencyFlush();
+  }
+
+  // ── 内部 ────────────────────────────────────────────────────────────
+
+  /** 换日/首写/错误重开:旧流冲干净 → 继承新文件长度 → 开新 append 流;返回流是否可用 */
+  private rotate(dayKey: string): boolean {
+    // 先冲干净旧流:pending 全清零后,后续 emergencyFlush 只会写当前日的行
+    // (换日本就每日一次,这一次同步补写无性能意义可言)
+    this.emergencyFlush();
+    this.dayKey = dayKey;
+    // 换日/首写:继承既有文件长度计数
+    try {
+      const st = fs.statSync(path.join(this.opts.dir, `${this.opts.prefix}-${dayKey}.jsonl`));
+      this.writtenBytes = st.size;
+    } catch {
+      this.writtenBytes = 0;
+    }
+    try {
+      this.stream = fs.createWriteStream(path.join(this.opts.dir, `${this.opts.prefix}-${dayKey}.jsonl`), {
+        flags: 'a'
+      });
+      // 磁盘满/只读 fs 等:销毁置空,本次已入队行同步补写,下次 write 重开(重新 statSync 继承长度)
+      this.stream.on('error', () => this.emergencyFlush());
+    } catch {
+      this.stream = null;
+    }
+    return this.stream !== null;
+  }
+
+  /**
+   * 滚动瘦身(留新去旧):从文件头砍 ~50%,切点对齐行边界('\n' 之后),
+   * 临时文件+原子 rename 覆盖(中途崩溃原文件完好,不会出现半截行)。
+   * 淘汰行数计入 droppedCount。失败返回 false(调用方退回丢新条,绝不拖死业务)。
+   */
+  private trim(): boolean {
+    if (!this.dayKey) return false;
+    const file = path.join(this.opts.dir, `${this.opts.prefix}-${this.dayKey}.jsonl`);
+    try {
+      // 先把未 ack 行落盘,文件才是完整现场;顺带关流(rename 期间不再有并发写入)
+      this.emergencyFlush();
+      let content: Buffer;
+      try {
+        content = fs.readFileSync(file);
+      } catch {
+        return false;
+      }
+      if (content.length === 0) {
+        this.writtenBytes = 0;
+        return false;
+      }
+      // 切点:target 之后的第一个换行;找不到(单行巨行占满后半)退到首个换行——
+      // 保证至少前进一行,否则瘦身无意义。整文件无换行则放弃(返回 false 丢新条)
+      const target = Math.floor(content.length * TRIM_KEEP_RATIO);
+      let cut = target > 0 ? content.indexOf(0x0a, target) : -1;
+      if (cut === -1) cut = content.indexOf(0x0a);
+      if (cut === -1) return false;
+      const tail = content.subarray(cut + 1);
+      // 淘汰行数计数(不静默:droppedCount 语义=滚动淘汰的旧行)
+      let trimmedLines = 0;
+      for (let i = 0; i <= cut; i++) {
+        if (content[i] === 0x0a) trimmedLines += 1;
+      }
+      const tmp = `${file}.trim-${process.pid}.tmp`;
+      fs.writeFileSync(tmp, tail);
+      fs.renameSync(tmp, file);
+      this.writtenBytes = tail.length;
+      this.droppedCount += trimmedLines;
+      return true;
+    } catch {
+      // 瘦身失败(磁盘满/只读 fs/读不了):退回丢新条
+      return false;
+    }
+  }
+
+  /** 兜底冲刷:销毁流(丢弃其内部缓冲)→ 未 ack 行同步 appendFileSync → 唤醒等待者 */
+  private emergencyFlush(): void {
+    const stream = this.stream;
+    this.stream = null;
+    if (stream) {
+      try {
+        stream.destroy();
+      } catch {
+        // 已关/已销毁
+      }
+    }
+    const pending = this.pending;
+    this.pending = [];
+    this.pendingBytes = 0;
+    if (pending.length > 0) {
+      try {
+        fs.appendFileSync(
+          path.join(this.opts.dir, `${this.opts.prefix}-${this.dayKey}.jsonl`),
+          pending.map((p) => p.line).join('')
+        );
+      } catch {
+        // 磁盘满/只读 fs:与运行期同口径静默
+      }
+    }
+    const waiters = this.flushWaiters;
+    this.flushWaiters = [];
+    for (const w of waiters) w();
+  }
+
+  /** 单行 ack:write 回调已确认到内核;pending 清空时唤醒 flush 等待者 */
+  private ack(): void {
+    const head = this.pending.shift();
+    if (head) this.pendingBytes -= head.bytes;
+    if (this.pending.length === 0 && this.flushWaiters.length > 0) {
+      const waiters = this.flushWaiters;
+      this.flushWaiters = [];
+      for (const w of waiters) w();
+    }
+  }
+}

package/templates/backend/src/common/transform.interceptor.ts

@@ -4,19 +4,28 @@ import {
   Injectable,
   NestInterceptor
 } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
 import { Observable, map } from 'rxjs';
+import { SKIP_TRANSFORM_KEY } from './decorators/skip-transform.decorator';
 
 /**
  * 统一响应拦截器
  * 控制器/服务返回任意对象 -> 包成 { code:200, message:'success', data }
  * 二进制流(Stream) -> 原样输出(文件下载)
  * null/undefined -> { code:200, message:'success', data:null }
+ * @SkipTransform() 标记的路由(SSE 事件流)-> 原样输出
  *
  * 服务层统一返回纯数据(含 string,如 token),由这里统一包装。
  */
 @Injectable()
 export class TransformInterceptor implements NestInterceptor {
+  constructor(private readonly reflector: Reflector) {}
+
   intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
+    // SSE 等事件流路由:跳过包装,事件对象原样透传
+    if (this.reflector.get<boolean>(SKIP_TRANSFORM_KEY, context.getHandler())) {
+      return next.handle();
+    }
     return next.handle().pipe(
       map((data) => {
         if (data === undefined || data === null) {

package/templates/backend/src/config/config.interface.ts

@@ -69,4 +69,33 @@ export interface AppConfig {
     /** 时间戳允许偏差(秒),默认 300(±5min) */
     tsWindow: number;
   };
+  /**
+   * 慢SQL探针(《慢SQL探针与SQL优化路径方案》):挂 TypeORM Logger 层,驱动无关
+   * (better-sqlite3/mysql 同钩子 maxQueryExecutionTime → logQuerySlow)
+   */
+  slowSql: {
+    /** 落盘目录(cwd 相对;docker 下随 /app/data volume,默认 data/slowsql) */
+    dir: string;
+    /** 慢查询阈值 ms,同时作为 TypeORM maxQueryExecutionTime */
+    thresholdMs: number;
+    /** 事件循环漂移记录阈值 ms */
+    lagMs: number;
+    /** 宿主基线落盘周期 s(内存环形采样固定 10s 不外配) */
+    hostSampleSec: number;
+    /** 日志保留天数 */
+    retainDays: number;
+    /** 单日文件上限 MB(超限滚动瘦身留新去旧,丢条计数随 stats 留痕) */
+    maxFileMb: number;
+  };
+  /** 运维调试日志(《后端日志体系整改方案》§2):API 失败(≥400)/慢请求登记,JSONL 落盘 */
+  apiLog: {
+    /** 落盘目录(cwd 相对;docker 下随 /app/data volume,默认 data/apilog) */
+    dir: string;
+    /** 慢请求阈值 ms(超时记 slow;2xx 成功不记) */
+    slowMs: number;
+    /** 日志保留天数 */
+    retainDays: number;
+    /** 单日文件上限 MB(超限滚动瘦身留新去旧,每 500 条 warn 留痕) */
+    maxFileMb: number;
+  };
 }

package/templates/backend/src/config/configuration.ts

@@ -114,6 +114,24 @@ export default (): AppConfig => {
       enabled: envBool('SSO_ENABLED', config.sso.enabled) as boolean,
       ticketKey: envStr('SSO_TICKET_KEY', config.sso.ticketKey) as string,
       tsWindow: envInt('SSO_TS_WINDOW', config.sso.tsWindow) as number
+    },
+    // 慢SQL探针 + 运维调试日志:与全局「env > yaml > 内置默认」语义一致,
+    // 老配置文件不带 slowSql/apiLog 段也能起。
+    slowSql: {
+      // 落盘目录默认 cwd/data/slowsql(docker=volume /app/data/slowsql,随数据卷持久化)
+      dir: envStr('SLOW_SQL_DIR', config.slowSql?.dir ?? 'data/slowsql') as string,
+      thresholdMs: envInt('SLOW_SQL_THRESHOLD_MS', config.slowSql?.thresholdMs ?? 50) as number,
+      lagMs: envInt('SLOW_SQL_LAG_MS', config.slowSql?.lagMs ?? 200) as number,
+      hostSampleSec: envInt('SLOW_SQL_HOST_SAMPLE_SEC', config.slowSql?.hostSampleSec ?? 60) as number,
+      retainDays: envInt('SLOW_SQL_RETAIN_DAYS', config.slowSql?.retainDays ?? 14) as number,
+      maxFileMb: envInt('SLOW_SQL_MAX_FILE_MB', config.slowSql?.maxFileMb ?? 10) as number
+    },
+    // 运维调试日志:只记 ≥400 失败与 >slowMs 慢请求,2xx 成功不记
+    apiLog: {
+      dir: envStr('API_LOG_DIR', config.apiLog?.dir ?? 'data/apilog') as string,
+      slowMs: envInt('API_LOG_SLOW_MS', config.apiLog?.slowMs ?? 1000) as number,
+      retainDays: envInt('API_LOG_RETAIN_DAYS', config.apiLog?.retainDays ?? 14) as number,
+      maxFileMb: envInt('API_LOG_MAX_FILE_MB', config.apiLog?.maxFileMb ?? 10) as number
     }
   };
 };

package/templates/backend/src/database/host-metrics.sampler.ts

@@ -0,0 +1,275 @@
+import * as fs from 'fs';
+import * as os from 'os';
+
+/**
+ * 宿主资源采样器(《慢SQL探针与SQL优化路径方案》§5)
+ *
+ * 场景:同库同 SQL 本机飞快、线上偶发慢,且服务器混部多个服务——慢的可能不是 SQL,
+ * 是宿主 CPU/磁盘被别的服务抢走。本采样器提供「宿主视角」,与慢 SQL / lag 记录
+ * 时刻对齐后才构成归因证据(§5.2 判别矩阵)。
+ *
+ * 容器视角口径(刻意为之):
+ *   - 容器内读 /proc/stat、/proc/meminfo、os.loadavg() 拿到的是宿主整机值——
+ *     混部场景要的正是这个视角(邻居服务在抢什么);
+ *   - cgroup memory.current/max 补「容器自身被限额挤压」的判断;
+ *   - 自进程 CPU(process.cpuUsage 差值)是关键对照:自进程 CPU 低 + 宿主
+ *     iowait/steal 高 = 被邻居抢;反之 = 自己的锅。
+ *
+ * 平台降级:macOS(本机 dev)无 /proc,iowait/steal/PSI/cgroup 缺省(null),
+ * 退到 os.loadavg/freemem;目标是线上 Linux,dev 不报错即可。
+ */
+
+/** 单次采样快照(嵌入慢 SQL / lag 记录的 host 字段,或独立落 host 基线记录) */
+export interface HostSnapshot {
+  /** 宿主 CPU 总占用 %(/proc/stat 差值;首轮 null) */
+  cpuPct: number | null;
+  /** 宿主 iowait %——磁盘被抢的直接指标 */
+  iowaitPct: number | null;
+  /** 宿主 steal %(虚拟机被宿主/邻居抢走的时间片) */
+  stealPct: number | null;
+  /** 宿主 load 1/5/15 */
+  load: [number, number, number] | null;
+  /** 宿主可用内存 MB */
+  memAvailMb: number | null;
+  /** 宿主 swap 已用 MB */
+  swapUsedMb: number | null;
+  /** 容器内存用量 MB(cgroup) */
+  cgMemMb: number | null;
+  /** 容器内存限额 MB("max"/ Unlimited 时 null) */
+  cgMemMaxMb: number | null;
+  /** 自进程 CPU %(单核口径,>100 即多核) */
+  procCpuPct: number | null;
+  /** 自进程 RSS MB */
+  rssMb: number | null;
+  /** PSI(内核 ≥4.20):cpu/io/memory 的 some avg10 */
+  psiCpu: number | null;
+  psiIo: number | null;
+  psiMem: number | null;
+  /** 数据卷磁盘用量 %(《后端日志体系整改方案》§6:日志/时序表/uploads/DB 的容量风险
+   *  最终都指向磁盘,却是此前唯一无日志证据的指标;statfs 双平台可得,读不到则 null) */
+  diskUsedPct: number | null;
+  /** 数据卷磁盘剩余 MB */
+  diskAvailMb: number | null;
+}
+
+const isLinux = process.platform === 'linux';
+const MB = 1024 * 1024;
+
+/** 读小文件文本,失败返回 null(路径不存在/权限等一律降级) */
+function readText(file: string): string | null {
+  try {
+    return fs.readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/** /proc/stat 首行 cpu 聚合 tick(顺序固定:user nice system idle iowait irq softirq steal) */
+function parseProcStat(text: string): number[] | null {
+  const line = text.split('\n', 1)[0]?.trim();
+  if (!line?.startsWith('cpu ')) return null;
+  const cols = line.slice(4).trim().split(/\s+/).map(Number);
+  return cols.length >= 8 && cols.every((n) => Number.isFinite(n)) ? cols : null;
+}
+
+/** /proc/pressure/xxx → "some avg10=.. avg60=.. avg300=.. full ..." 取 some avg10 */
+function parsePsi(text: string | null): number | null {
+  if (!text) return null;
+  const m = text.match(/some\s+avg10=([\d.]+)/);
+  return m ? Number(m[1]) : null;
+}
+
+/** cgroup 内存用量/限额(v2 优先,v1 fallback;均读不到则 null) */
+function readCgroupMem(): { usedMb: number | null; maxMb: number | null } {
+  // v2
+  let cur = readText('/sys/fs/cgroup/memory.current');
+  let max = readText('/sys/fs/cgroup/memory.max');
+  // v1
+  if (cur === null || max === null) {
+    cur = readText('/sys/fs/cgroup/memory/memory.usage_in_bytes');
+    max = readText('/sys/fs/cgroup/memory/memory.limit_in_bytes');
+  }
+  const usedMb = cur !== null ? Math.round(Number(cur) / MB) : null;
+  // v2 无限额时值为字面量 "max"
+  const maxMb = max !== null && /^\d+$/.test(max.trim()) ? Math.round(Number(max) / MB) : null;
+  return { usedMb: Number.isFinite(usedMb) ? usedMb : null, maxMb };
+}
+
+/** /proc/meminfo 取 MemAvailable / SwapFree / SwapTotal(kB → MB) */
+function readMeminfo(): { memAvailMb: number | null; swapUsedMb: number | null } {
+  const text = readText('/proc/meminfo');
+  if (!text) return { memAvailMb: null, swapUsedMb: null };
+  const map = new Map<string, number>();
+  for (const line of text.split('\n')) {
+    const m = line.match(/^(\w+):\s+(\d+)\s*kB/);
+    if (m) map.set(m[1], Number(m[2]));
+  }
+  const avail = map.has('MemAvailable') ? map.get('MemAvailable') : map.get('MemFree');
+  const swapTotal = map.get('SwapTotal') ?? 0;
+  const swapFree = map.get('SwapFree') ?? 0;
+  return {
+    memAvailMb: avail !== undefined ? Math.round(avail / 1024) : null,
+    swapUsedMb: Math.round((swapTotal - swapFree) / 1024)
+  };
+}
+
+/** statfs 磁盘用量(watchPath 所在文件系统;读不到/不支持则 null 降级) */
+function readDisk(watchPath: string): { usedPct: number | null; availMb: number | null } {
+  try {
+    const st = (fs as any).statfsSync(watchPath) as {
+      blocks: number;
+      bsize: number;
+      bavail: number;
+    } | null;
+    if (!st || !st.blocks || !st.bsize) return { usedPct: null, availMb: null };
+    const totalBytes = st.blocks * st.bsize;
+    const availBytes = st.bavail * st.bsize;
+    return {
+      usedPct: Number((((totalBytes - availBytes) / totalBytes) * 100).toFixed(1)),
+      availMb: Math.round(availBytes / MB)
+    };
+  } catch {
+    return { usedPct: null, availMb: null };
+  }
+}
+
+export class HostMetricsSampler {
+  /** 环形缓冲(最近 ringSize 条),慢事件内联取 latest */
+  private ring: HostSnapshot[] = [];
+  private timer: NodeJS.Timeout | null = null;
+  /** 上一次 /proc/stat 原始 tick(差值计算用;首轮采样得 null 占位) */
+  private lastStat: number[] | null = null;
+  private lastStatAt = 0;
+  /** 上一次 process.cpuUsage 快照 */
+  private lastProc: { user: number; system: number } | null = null;
+  private lastProcAt = 0;
+
+  /**
+   * @param ringSize     环形缓冲条数
+   * @param diskWatchPath 磁盘水位观测路径(数据卷;默认 cwd,随 data volume 持久化语义)
+   */
+  constructor(
+    private readonly ringSize = 6,
+    private readonly diskWatchPath: string = process.cwd()
+  ) {}
+
+  /** 启动周期采样(默认 10s;定时器 unref,不阻止进程退出) */
+  start(intervalMs = 10_000): this {
+    if (this.timer) return this;
+    this.sample();
+    this.timer = setInterval(() => this.sample(), intervalMs);
+    this.timer.unref();
+    return this;
+  }
+
+  stop(): void {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = null;
+  }
+
+  /** 最近一次快照(未启动/首轮前返回全 null 结构,字段缺省原则) */
+  latest(): HostSnapshot {
+    return this.ring[this.ring.length - 1] || HostMetricsSampler.emptySnapshot();
+  }
+
+  private static emptySnapshot(): HostSnapshot {
+    return {
+      cpuPct: null,
+      iowaitPct: null,
+      stealPct: null,
+      load: null,
+      memAvailMb: null,
+      swapUsedMb: null,
+      cgMemMb: null,
+      cgMemMaxMb: null,
+      procCpuPct: null,
+      rssMb: null,
+      psiCpu: null,
+      psiIo: null,
+      psiMem: null,
+      diskUsedPct: null,
+      diskAvailMb: null
+    };
+  }
+
+  private sample(): void {
+    let snap: HostSnapshot;
+    try {
+      snap = this.buildSnapshot();
+    } catch {
+      // 采样自身永不抛错(它在探针写盘路径上),降级为空快照
+      snap = HostMetricsSampler.emptySnapshot();
+    }
+    this.ring.push(snap);
+    if (this.ring.length > this.ringSize) this.ring.shift();
+  }
+
+  private buildSnapshot(): HostSnapshot {
+    const snap = HostMetricsSampler.emptySnapshot();
+    const now = Date.now();
+
+    // 宿主 load(双平台可得)
+    const load = os.loadavg() as number[];
+    snap.load = [Number(load[0].toFixed(2)), Number(load[1].toFixed(2)), Number(load[2].toFixed(2))];
+
+    if (isLinux) {
+      // CPU/iowait/steal:/proc/stat 相邻两次差值
+      const statText = readText('/proc/stat');
+      const cols = statText ? parseProcStat(statText) : null;
+      if (cols) {
+        const prev = this.lastStat;
+        const elapsed = now - this.lastStatAt;
+        if (prev && elapsed > 0) {
+          const total = (a: number[], b: number[]) =>
+            a.reduce((s, v, i) => s + Math.max(0, v - b[i]), 0);
+          const dTotal = total(cols, prev);
+          if (dTotal > 0) {
+            const pct = (i: number) => Number(((Math.max(0, cols[i] - prev[i]) / dTotal) * 100).toFixed(1));
+            snap.cpuPct = Number((100 - pct(3) - pct(4)).toFixed(1)); // 非idle非iowait
+            snap.iowaitPct = pct(4);
+            snap.stealPct = pct(7);
+          }
+        }
+        this.lastStat = cols;
+        this.lastStatAt = now;
+      }
+
+      // 内存/swap(宿主整机)
+      const mem = readMeminfo();
+      snap.memAvailMb = mem.memAvailMb;
+      snap.swapUsedMb = mem.swapUsedMb;
+
+      // 容器限额视角
+      const cg = readCgroupMem();
+      snap.cgMemMb = cg.usedMb;
+      snap.cgMemMaxMb = cg.maxMb;
+
+      // PSI(有则直接量化宿主压力)
+      snap.psiCpu = parsePsi(readText('/proc/pressure/cpu'));
+      snap.psiIo = parsePsi(readText('/proc/pressure/io'));
+      snap.psiMem = parsePsi(readText('/proc/pressure/memory'));
+    } else {
+      // macOS/dev 降级
+      snap.memAvailMb = Math.round(os.freemem() / MB);
+    }
+
+    // 自进程 CPU(单核口径)与 RSS——「自己算得多」vs「被别人抢」的对照
+    const proc = process.cpuUsage();
+    const pPrev = this.lastProc;
+    const pElapsed = now - this.lastProcAt;
+    if (pPrev && pElapsed > 0) {
+      const usedUs = proc.user - pPrev.user + (proc.system - pPrev.system);
+      snap.procCpuPct = Number(((usedUs / 1000 / pElapsed) * 100).toFixed(1));
+    }
+    this.lastProc = proc;
+    this.lastProcAt = now;
+    snap.rssMb = Math.round(process.memoryUsage().rss / MB);
+
+    // 数据卷磁盘水位(双平台 statfs;读不到则 null)
+    const disk = readDisk(this.diskWatchPath);
+    snap.diskUsedPct = disk.usedPct;
+    snap.diskAvailMb = disk.availMb;
+
+    return snap;
+  }
+}