create-ssnode-cli 0.2.4 → 0.2.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-ssnode-cli",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "SSNodeFullStack 脚手架 — 生成全栈 / 仅前端 / 仅后端项目(Vite+React+AntD / NestJS+SQLite)",
   "type": "module",
   "bin": {

package/templates/backend/config/config.develop.yaml

@@ -47,6 +47,25 @@ upload:
     - .mp4
   maxSize: 10485760  # 10MB
 
+# 慢SQL探针:挂 TypeORM Logger 层,记录落 data/slowsql/slowsql-YYYY-MM-DD.jsonl
+# (sql 慢查询样本按指纹每日限 5 条/error/lag 事件循环漂移/host 宿主基线/stats 每小时汇总)
+# 分析:node scripts/slowsql-report.mjs
+slowSql:
+  thresholdMs: 50     # 慢查询阈值 ms
+  lagMs: 200          # 事件循环漂移记录阈值
+  hostSampleSec: 60   # 宿主基线落盘周期(内存环形采样固定 10s 不外配)
+  retainDays: 14      # 日志保留天数
+  maxFileMb: 10       # 单日文件上限 MB(超限滚动瘦身留新去旧,丢条计数随 stats 留痕)
+
+# 运维调试日志:只记 ≥400 失败与 >slowMs 慢请求,2xx 成功不记。
+# 失败含 query/body(脱敏截断:password/token/sign 等→***)与失败结果(5xx 带异常 detail);
+# 慢请求只记 method/url/耗时/用户,query/body 同口径脱敏。
+# 落 data/apilog/apilog-YYYY-MM-DD.jsonl,traceId 经 X-Trace-Id 响应头回传,报 traceId 即可全链路 grep。
+apiLog:
+  slowMs: 1000       # 慢请求阈值 ms
+  retainDays: 14     # 保留天数
+  maxFileMb: 10      # 单日文件上限(超限丢条,每 500 条 warn 留痕)
+
 # 超管账号:yaml 为权威,启动时 user.service 把 DB reconcile 到此值
 # (改这里 + 重启 即完成轮换)。dev/prod 真值均入库 yaml 直读;ADMIN_PASSWORD env 为可选覆盖。
 admin:

package/templates/backend/config/config.prod.yaml

@@ -46,6 +46,25 @@ upload:
     - .mp4
   maxSize: 10485760
 
+# 慢SQL探针:挂 TypeORM Logger 层,记录落 data/slowsql/slowsql-YYYY-MM-DD.jsonl
+# (sql 慢查询样本按指纹每日限 5 条/error/lag 事件循环漂移/host 宿主基线/stats 每小时汇总)
+# 分析:node scripts/slowsql-report.mjs
+slowSql:
+  thresholdMs: 50     # 慢查询阈值 ms
+  lagMs: 200          # 事件循环漂移记录阈值
+  hostSampleSec: 60   # 宿主基线落盘周期(内存环形采样固定 10s 不外配)
+  retainDays: 14      # 日志保留天数
+  maxFileMb: 10       # 单日文件上限 MB(超限滚动瘦身留新去旧,丢条计数随 stats 留痕)
+
+# 运维调试日志:只记 ≥400 失败与 >slowMs 慢请求,2xx 成功不记。
+# 失败含 query/body(脱敏截断:password/token/sign 等→***)与失败结果(5xx 带异常 detail);
+# 慢请求只记 method/url/耗时/用户,query/body 同口径脱敏。
+# 落 data/apilog/apilog-YYYY-MM-DD.jsonl,traceId 经 X-Trace-Id 响应头回传,报 traceId 即可全链路 grep。
+apiLog:
+  slowMs: 1000       # 慢请求阈值 ms
+  retainDays: 14     # 保留天数
+  maxFileMb: 10      # 单日文件上限(超限丢条,每 500 条 warn 留痕)
+
 # 超管账号:yaml 为权威,启动时 user.service 把 DB reconcile 到此值
 # (改 current/config/config.prod.yaml 或 ADMIN_PASSWORD env + 重启 即完成轮换,如三月一换)。
 # prod 真值已入库本 yaml(systemd/pm2 直读);ADMIN_PASSWORD env 为可选覆盖(docker 经 .env、

package/templates/backend/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backend",
-  "version": "1.0.17",
+  "version": "1.0.21",
   "description": "全栈模板 - 后台服务(NestJS + SQLite + TypeORM)",
   "private": true,
   "engines": {

package/templates/backend/scripts/slowsql-report.mjs

@@ -0,0 +1,281 @@
+#!/usr/bin/env node
+/**
+ * 慢SQL探针分析报告(《慢SQL探针与SQL优化路径方案》§3.2/§5.2)
+ *
+ * 用法:
+ *   node scripts/slowsql-report.mjs [目录或文件...] [选项]
+ *     --top N          慢 SQL 指纹 top-N(默认 20)
+ *     --explain <db> 对 top-N 指纹输出可执行的 EXPLAIN 语句,不连库(sqlite 侧用
+ *                    EXPLAIN QUERY PLAN,MySQL 侧 EXPLAIN 后人工看 type=ALL;
+ *                    <db> 为占位值,仅作开关用,不会被当目标路径读取)
+ *     --out <file>     输出 markdown 到文件(默认 stdout)
+ *
+ * 读 data/slowsql/slowsql-YYYY-MM-DD.jsonl,聚合输出:
+ *   1. 总览(时间范围/查询量/慢查询/lag/错误)
+ *   2. 慢 SQL 指纹 top 表(含「宿主紧张占比」标注)
+ *   3. lag / 宿主基线摘要
+ *   4. §5.2 归因判别矩阵的自动结论
+ *
+ * 这是「证据 → 优化」闭环的一环:报告直接就是下一份优化方案的立项依据。
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const args = process.argv.slice(2);
+const flag = (name) => {
+  const i = args.indexOf(`--${name}`);
+  return i >= 0 ? args[i + 1] : undefined;
+};
+const TOP_N = Number(flag('top') || 20);
+const EXPLAIN_DB = flag('explain');
+const DIALECT = flag('dialect') || 'mysql';
+const OUT = flag('out');
+// flag 及其取值从位置参数里剔除(否则 --explain 的 db 路径会被当目标再读一遍)
+const flagValues = new Set([flag('top'), flag('explain'), flag('dialect'), flag('out')]);
+const targets = args.filter((a) => !a.startsWith('--') && !flagValues.has(a));
+
+const DEFAULT_DIR = path.join(process.cwd(), 'data', 'slowsql');
+const files = targets.length
+  ? targets.flatMap((t) => (fs.statSync(t).isDirectory() ? fs.readdirSync(t).map((f) => path.join(t, f)) : [t]))
+  : fs.existsSync(DEFAULT_DIR)
+    ? fs.readdirSync(DEFAULT_DIR).map((f) => path.join(DEFAULT_DIR, f))
+    : [];
+
+const jsonlFiles = files.filter((f) => f.endsWith('.jsonl')).sort();
+if (!jsonlFiles.length) {
+  console.error(`未找到 JSONL 文件(${DEFAULT_DIR});可用参数指定目录/文件`);
+  process.exit(1);
+}
+
+// ── 读取与聚合 ────────────────────────────────────────────────────────
+
+/** SQL 指纹:legacy 记录兜底(新记录由探针侧带 fp 字段,两处实现语义一致;
+ *  权威实现在 backend/src/database/sql-fingerprint.ts,采样与计数共用) */
+function fingerprint(sql) {
+  return sql
+    .replace(/\s+/g, ' ')
+    .replace(/'[^']*'/g, "'?'")
+    .replace(/\b\d+(\.\d+)?\b/g, '?')
+    .trim();
+}
+
+/** 宿主紧张判定:iowait/steal 超阈 或 PSI io/cpu 超阈(§5.2 第二行) */
+function hostTension(h) {
+  if (!h) return false;
+  if ((h.iowaitPct ?? 0) > 5 || (h.stealPct ?? 0) > 5) return true;
+  if ((h.psiIo ?? 0) > 10 || (h.psiCpu ?? 0) > 20) return true;
+  return false;
+}
+
+const lags = [];
+const hosts = [];
+const stats = [];
+const errors = [];
+const sqls = [];
+let firstTs = null;
+let lastTs = null;
+
+for (const file of jsonlFiles) {
+  const lines = fs.readFileSync(file, 'utf8').split('\n');
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    let r;
+    try {
+      r = JSON.parse(line);
+    } catch {
+      continue; // 坏行跳过(手工查看/截断等)
+    }
+    if (r.ts) {
+      if (!firstTs) firstTs = r.ts;
+      lastTs = r.ts;
+    }
+    if (r.type === 'sql') {
+      sqls.push(r);
+    } else if (r.type === 'lag') {
+      lags.push(r);
+    } else if (r.type === 'host') {
+      hosts.push(r);
+    } else if (r.type === 'stats') {
+      stats.push(r);
+    } else if (r.type === 'error') {
+      errors.push(r);
+    }
+  }
+}
+
+// ── 指纹聚合(《后端日志体系整改方案》§4.2 口径:计数优先、样本供下钻)──
+// stats.top 计数是全量(探针侧每条慢查询都计,采样与否无关);sql 记录只是
+// 每指纹每日前 5 条细节样本。合并规则:计数取 stats.top;legacy 记录(无 top)
+// 退回逐条累计。样本贡献 sql 文本/params(供 EXPLAIN 下钻)。
+const fpMap = new Map(); // 指纹 → { count, totalMs, maxMs, tension, sql, params, counted }
+for (const s of stats) {
+  for (const t of s.top || []) {
+    if (!t.fp) continue;
+    const e =
+      fpMap.get(t.fp) || { count: 0, totalMs: 0, maxMs: 0, tension: 0, sql: '', params: null, counted: true };
+    e.count += t.count || 0;
+    e.totalMs += t.totalMs || 0;
+    e.maxMs = Math.max(e.maxMs, t.maxMs || 0);
+    e.tension += t.tension || 0;
+    e.counted = true; // 有计数器背书的条目不再吃样本计数
+    fpMap.set(t.fp, e);
+  }
+}
+for (const r of sqls) {
+  const key = r.fp || fingerprint(r.sql || '');
+  const e =
+    fpMap.get(key) || { count: 0, totalMs: 0, maxMs: 0, tension: 0, sql: '', params: null, counted: false };
+  if (!e.counted) {
+    // legacy(无 stats.top):每条样本即一次发生
+    e.count += 1;
+    e.totalMs += r.ms || 0;
+    e.maxMs = Math.max(e.maxMs, r.ms || 0);
+    if (hostTension(r.host)) e.tension += 1;
+  }
+  if (!e.sql) {
+    e.sql = r.sql;
+    e.params = r.params;
+  }
+  fpMap.set(key, e);
+}
+
+const fps = [...fpMap.values()].sort((a, b) => b.totalMs - a.totalMs);
+const top = fps.slice(0, TOP_N);
+const slowCount = fps.reduce((s, e) => s + e.count, 0);
+const slowTotalMs = fps.reduce((s, e) => s + e.totalMs, 0);
+const totalQueries = stats.reduce((s, r) => s + (r.queries || 0), 0);
+const dropped = stats.reduce((s, r) => s + (r.dropped || 0), 0);
+
+// lag 与慢 SQL 的分钟级对齐(§5.2 判别矩阵)
+// 采样口径:分子分母都用样本(计数器无分钟粒度),样本虽是每指纹前 5 条,分钟分布不失真
+const lagMinutes = new Set(lags.map((r) => (r.ts || '').slice(0, 16)));
+const slowInLagMinute = lagMinutes.size
+  ? sqls.filter((r) => lagMinutes.has((r.ts || '').slice(0, 16))).length
+  : 0;
+
+// 宿主基线摘要
+const avg = (xs) => (xs.length ? xs.reduce((s, v) => s + v, 0) / xs.length : null);
+const hostAvg = {
+  cpuPct: avg(hosts.map((h) => h.cpuPct).filter((v) => v != null)),
+  iowaitPct: avg(hosts.map((h) => h.iowaitPct).filter((v) => v != null)),
+  stealPct: avg(hosts.map((h) => h.stealPct).filter((v) => v != null)),
+  procCpuPct: avg(hosts.map((h) => h.procCpuPct).filter((v) => v != null)),
+  psiIo: avg(hosts.map((h) => h.psiIo).filter((v) => v != null))
+};
+
+// ── EXPLAIN(只输出可执行语句,不连库;MySQL 侧执行后人工看 type=ALL,sqlite 用 EXPLAIN QUERY PLAN) ──
+
+let explainLines = [];
+if (EXPLAIN_DB) {
+  explainLines = top.slice(0, 10).map((e) => ({
+    fp: e,
+    lines: [`- 请在数据库侧执行(sqlite 可用 EXPLAIN QUERY PLAN): EXPLAIN ${e.sql.replace(/\?/g, 'NULL').slice(0, 500)};`]
+  }));
+}
+
+// ── §5.2 判别矩阵自动结论 ─────────────────────────────────────────────
+
+function verdict() {
+  const v = [];
+  if (!slowCount && !lags.length) return ['证据不足(无慢查询、无 lag)——探针刚上线或期间无阻塞。'];
+  const tensionRatio = slowCount
+    ? top.reduce((s, e) => s + e.tension, 0) / Math.max(1, top.reduce((s, e) => s + e.count, 0))
+    : 0;
+  const iowaitHigh = (hostAvg.iowaitPct ?? 0) > 5 || (hostAvg.psiIo ?? 0) > 10;
+  const stealHigh = (hostAvg.stealPct ?? 0) > 5;
+  if (tensionRatio > 0.5 || iowaitHigh || stealHigh) {
+    v.push(
+      `**宿主资源紧张嫌疑大**(慢事件内联宿主紧张占比 ${(tensionRatio * 100).toFixed(0)}%` +
+        `${iowaitHigh ? ',基线 iowait/PSI-io 偏高' : ''}${stealHigh ? ',steal 偏高' : ''})` +
+        `——先查 §5.4(vmstat/PSI/docker stats),SQL 优化可能是白做。`
+    );
+  }
+  const sampleBase = Math.max(1, sqls.length); // 样本基(计数无分钟粒度,§4.2)
+  if (lags.length && slowInLagMinute / sampleBase > 0.5 && !iowaitHigh && !stealHigh) {
+    v.push(
+      '慢 SQL 与 lag 高度同分钟且宿主空闲——**SQL 本身慢**(索引/扫描问题),走 SQL 侧优化;配合 --explain 看 SCAN。'
+    );
+  }
+  if (lags.length && sqls.length && slowInLagMinute / sampleBase < 0.2) {
+    v.push(
+      'lag 多但慢 SQL 稀疏——**JS 侧重活嫌疑**(大结果集聚合/序列化,SQL 不慢),对应审计方案批次二类问题。'
+    );
+  }
+  if (!lags.length && slowCount) {
+    v.push('慢 SQL 未伴随事件循环 lag(异步/低频)——单条慢但未阻塞,优先级看 totalMs 排序即可。');
+  }
+  return v;
+}
+
+// ── 输出 ──────────────────────────────────────────────────────────────
+
+const fmt = (v, unit = '') => (v == null ? '-' : `${Number(v.toFixed(1))}${unit}`);
+const md = [];
+md.push(`# 慢SQL探针分析报告`);
+md.push('');
+md.push(`- 数据源:${jsonlFiles.map((f) => path.basename(f)).join(', ')}`);
+md.push(`- 时间范围:${firstTs || '-'} ~ ${lastTs || '-'}`);
+md.push(`- 查询量(仅 stats 窗口统计):${totalQueries};慢查询:${slowCount} 次 / ${fps.length} 指纹 / 累计 ${fmt(slowTotalMs)}ms;lag:${lags.length} 次;查询错误:${errors.length} 次${dropped ? `;⚠️ 丢条:${dropped}` : ''}`);
+md.push('');
+
+md.push(`## 慢 SQL 指纹 Top${top.length}(按 totalMs)`);
+md.push('');
+if (top.length) {
+  md.push(`| # | 累计ms | 次数 | 最大ms | 宿主紧张 | 指纹 |`);
+  md.push(`|---|---|---|---|---|---|`);
+  top.forEach((e, i) => {
+    const fp = fingerprint(e.sql).slice(0, 120).replace(/\|/g, '\\|');
+    const t = e.tension ? `${e.tension}/${e.count}` : '0';
+    md.push(`| ${i + 1} | ${Math.round(e.totalMs)} | ${e.count} | ${Math.round(e.maxMs)} | ${t} | \`${fp}\` |`);
+  });
+} else {
+  md.push('无慢查询记录。');
+}
+md.push('');
+
+if (explainLines.length) {
+  md.push(`## EXPLAIN(占位符已回填样本/NULL,只看计划不看值)`);
+  md.push('');
+  for (const { fp, lines } of explainLines) {
+    md.push(`**${fingerprint(fp.sql).slice(0, 100)}**`);
+    md.push(...lines);
+    md.push('');
+  }
+}
+
+md.push(`## 事件循环 lag`);
+md.push('');
+if (lags.length) {
+  const maxLag = Math.max(...lags.map((r) => r.ms));
+  md.push(`- 共 ${lags.length} 次,最大 ${maxLag}ms;慢 SQL 样本落在 lag 同分钟的占比 ${((slowInLagMinute / Math.max(1, sqls.length)) * 100).toFixed(0)}%`);
+  const byHour = new Map();
+  for (const r of lags) {
+    const h = (r.ts || '').slice(0, 13);
+    byHour.set(h, (byHour.get(h) || 0) + 1);
+  }
+  md.push(`- 按小时分布:${[...byHour.entries()].map(([h, c]) => `${h}时=${c}`).join(', ')}`);
+} else {
+  md.push('- 无 lag 记录(事件循环未被阻塞)。');
+}
+md.push('');
+
+md.push(`## 宿主基线(${hosts.length} 条采样)`);
+md.push('');
+md.push(`- CPU 均值 ${fmt(hostAvg.cpuPct, '%')} / iowait 均值 ${fmt(hostAvg.iowaitPct, '%')} / steal 均值 ${fmt(hostAvg.stealPct, '%')}`);
+md.push(`- 自进程 CPU 均值 ${fmt(hostAvg.procCpuPct, '%')}(单核口径)`);
+md.push(`- PSI io 均值 ${fmt(hostAvg.psiIo)}`);
+md.push('');
+
+md.push(`## 归因判别(§5.2 矩阵)`);
+md.push('');
+for (const v of verdict()) md.push(`- ${v}`);
+md.push('');
+
+const out = md.join('\n');
+if (OUT) {
+  fs.writeFileSync(OUT, out);
+  console.log(`已写入 ${OUT}`);
+} else {
+  console.log(out);
+}

package/templates/backend/src/app.module.ts

@@ -15,6 +15,9 @@ import { AllExceptionsFilter } from './common/all-exceptions.filter';
 import { TransformInterceptor } from './common/transform.interceptor';
 import { AppThrottlerGuard } from './common/throttle.guard';
 import { AppSignModule } from './common/app-sign.module';
+// 运维调试日志(《后端日志体系整改方案》):失败登记(过滤器)+ 慢请求登记(拦截器)
+import { ApiLogModule } from './common/api-log/api-log.module';
+import { ApiLogInterceptor } from './common/api-log/api-log.interceptor';
 
 import { AuthModule } from './modules/auth/auth.module';
 import { UserModule } from './modules/user/user.module';
@@ -32,6 +35,8 @@ import { OpsModule } from './modules/ops/ops.module';
       isGlobal: true,
       load: [configuration]
     }),
+    // @Global:AllExceptionsFilter 与 ApiLogInterceptor 共用一个写盘器
+    ApiLogModule,
     ThrottlerModule.forRootAsync({
       inject: [ConfigService],
       useFactory: (config: ConfigService<AppConfig, true>) => {
@@ -69,10 +74,12 @@ import { OpsModule } from './modules/ops/ops.module';
     AppSignModule
   ],
   providers: [
-    // 统一异常过滤器
+    // 统一异常过滤器(内联失败登记:≥400 落 apilog)
     { provide: APP_FILTER, useClass: AllExceptionsFilter },
     // 统一响应拦截器
     { provide: APP_INTERCEPTOR, useClass: TransformInterceptor },
+    // 慢请求登记(失败登记在过滤器;SSE @SkipTransform 跳过)
+    { provide: APP_INTERCEPTOR, useClass: ApiLogInterceptor },
     // 限流守卫
     { provide: APP_GUARD, useClass: AppThrottlerGuard }
   ]

package/templates/backend/src/common/all-exceptions.filter.ts

@@ -6,26 +6,35 @@ import {
   HttpStatus,
   Logger
 } from '@nestjs/common';
+import { performance } from 'perf_hooks';
 import { Request, Response } from 'express';
 import { ResponseResult } from './response';
+import { ApiLogService } from './api-log/api-log.service';
 
 /**
  * 全局异常过滤器
  * 把所有异常统一包成 { code, message, data } 响应体
  * - HttpException: 用其 status 作 code,message 用其 message
  * - 其他错误: 500
+ *
+ * 失败登记(《后端日志体系整改方案》§2):过滤器是所有异常(含 guard 阶段的 401/429、
+ * 路由 404、校验 400、服务层 500)的唯一必经出口,在此落 apilog——带参数、带失败结果,
+ * 供联调事后追溯。之前只有 500 留痕,4xx 全静默。
  */
 @Catch()
 export class AllExceptionsFilter implements ExceptionFilter {
   private readonly logger = new Logger('Exception');
 
+  constructor(private readonly apiLog: ApiLogService) {}
+
   catch(exception: unknown, host: ArgumentsHost) {
     const ctx = host.switchToHttp();
     const response = ctx.getResponse<Response>();
-    const request = ctx.getRequest<Request>();
+    const request = ctx.getRequest<Request & { traceId?: string; traceStart?: number }>();
 
     let code = HttpStatus.INTERNAL_SERVER_ERROR;
     let message = '服务器内部错误';
+    let detail: string | undefined;
 
     if (exception instanceof HttpException) {
       code = exception.getStatus();
@@ -38,11 +47,18 @@ export class AllExceptionsFilter implements ExceptionFilter {
       if (Array.isArray(message)) {
         message = message[0];
       }
+      // 路由未命中(NotFoundException 默认 message 是 "Cannot GET /xxx")会原样回显请求
+      // URL,注入 payload 即被漏扫器判为反射 XSS;统一收敛为笼统文案,业务自定义 404 文案不受影响。
+      if (code === 404 && typeof message === 'string' && /^Cannot \w+ \//.test(message)) {
+        message = '接口不存在';
+      }
     } else if (exception instanceof Error) {
       // 非 HttpException(数据库/文件系统等)的 message 可能含 SQL 片段、绝对路径,
       // 只入日志,不回传客户端
       message = '服务器内部错误';
       this.logger.error(`${request.method} ${request.url} -> ${exception.message}`, exception.stack);
+      // apilog 的 5xx detail:异常 message + stack 首行(客户端看不到的真相只落盘)
+      detail = `${exception.message} @ ${(exception.stack || '').split('\n')[1]?.trim() || ''}`;
     }
 
     // 限流(429)使用更友好的文案
@@ -50,6 +66,27 @@ export class AllExceptionsFilter implements ExceptionFilter {
       message = '请求过于频繁,请稍后再试(每分钟 60 次)';
     }
 
+    // 失败登记:参数脱敏在 ApiLogService.record 内统一处理
+    try {
+      this.apiLog.record(
+        {
+          type: 'fail',
+          traceId: request?.traceId,
+          method: request?.method || '',
+          url: request?.originalUrl || request?.url || '',
+          ip: ApiLogService.ipOf(request),
+          user: (request as any)?.user?.username || '',
+          ms: request?.traceStart ? Math.round(performance.now() - request.traceStart) : -1,
+          code,
+          message: String(message),
+          detail
+        },
+        request
+      );
+    } catch {
+      // 登记失败不吞业务响应
+    }
+
     const status = code >= 100 && code < 600 ? code : 200;
     response
       .status(status)

package/templates/backend/src/common/api-log/api-log.interceptor.ts

@@ -0,0 +1,52 @@
+import { CallHandler, ExecutionContext, Injectable, NestInterceptor } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { performance } from 'perf_hooks';
+import { Observable, tap } from 'rxjs';
+import { SKIP_TRANSFORM_KEY } from '../decorators/skip-transform.decorator';
+import { ApiLogService } from './api-log.service';
+
+/**
+ * 慢请求登记拦截器(《后端日志体系整改方案》§2.2)
+ *
+ * 只管 slow(耗时 > apiLog.slowMs);fail(≥400)由 AllExceptionsFilter 统一落——
+ * 拦截器看不到 guard 阶段抛的 401/429(守卫先于拦截器),过滤器是所有异常的必经出口。
+ *
+ * SSE/文件下载(@SkipTransform)跳过:SSE 长连接的「总时长」无性能语义,只会刷噪音。
+ * 耗时起点 traceStart 由 main.ts 的 traceId 中间件挂 req(比拦截器更早,含 guard 耗时)。
+ */
+@Injectable()
+export class ApiLogInterceptor implements NestInterceptor {
+  constructor(
+    private readonly reflector: Reflector,
+    private readonly apiLog: ApiLogService
+  ) {}
+
+  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
+    if (this.reflector.get<boolean>(SKIP_TRANSFORM_KEY, context.getHandler())) {
+      return next.handle();
+    }
+    const req = context.switchToHttp().getRequest<any>();
+    const start = req?.traceStart ?? performance.now();
+
+    return next.handle().pipe(
+      tap(() => {
+        // 异常不进 tap(错误走过滤器登记),这里只记「成功但慢」
+        const ms = Math.round(performance.now() - start);
+        if (ms >= this.apiLog.slowThresholdMs && req) {
+          this.apiLog.record(
+            {
+              type: 'slow',
+              traceId: req.traceId,
+              method: req.method,
+              url: req.originalUrl || req.url,
+              ip: ApiLogService.ipOf(req),
+              user: req.user?.username || '',
+              ms
+            },
+            req
+          );
+        }
+      })
+    );
+  }
+}

package/templates/backend/src/common/api-log/api-log.module.ts

@@ -0,0 +1,13 @@
+import { Global, Module } from '@nestjs/common';
+import { ApiLogService } from './api-log.service';
+
+/**
+ * 运维调试日志(《后端日志体系整改方案》§2):@Global 横切——
+ * AllExceptionsFilter(失败登记)与 ApiLogInterceptor(慢请求登记)共用一个写盘器。
+ */
+@Global()
+@Module({
+  providers: [ApiLogService],
+  exports: [ApiLogService]
+})
+export class ApiLogModule {}

package/templates/backend/src/common/api-log/api-log.service.ts

@@ -0,0 +1,148 @@
+import { Injectable, Logger, type OnModuleDestroy } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import * as path from 'path';
+import { JsonlDailyWriter, localTs } from '../jsonl-daily-writer';
+import type { AppConfig } from '../../config/config.interface';
+
+/**
+ * 运维调试日志(《后端日志体系整改方案》§2)
+ *
+ * API 失败登记(≥400)与慢请求登记(>slowMs)落 data/apilog/apilog-YYYY-MM-DD.jsonl,
+ * 2xx 成功请求不记(内网单体下全量访问日志是纯噪音)。traceId 由 main.ts 中间件
+ * 挂到 req 并回传 X-Trace-Id 响应头——联调时用户报一个 traceId,grep 一次定位全链路。
+ *
+ * 落盘而非 DB:故障场景下 DB 本身可能就是挂的原因(自指死锁),文件零依赖。
+ * 参数口径(已拍板「不过度存储」):query 全量 + body 脱敏截断(敏感 key→***,
+ * 每字段 200 字符/最多 10 个),multipart 只记字段不记文件内容,不记成功响应体。
+ */
+
+/** 敏感 key(小写匹配,含嵌套层):值一律打码,安全整改成果不倒退 */
+const MASK_KEYS = new Set([
+  'password',
+  'oldpassword',
+  'newpassword',
+  'verifycode',
+  'captcha',
+  'token',
+  'accesstoken',
+  'refreshtoken',
+  'authorization',
+  'cookie',
+  'secret',
+  'appsecret',
+  'signkey',
+  'apikey',
+  'sign'
+]);
+
+/** 单条记录公共字段 */
+export interface ApiLogEntry {
+  type: 'fail' | 'slow';
+  traceId?: string;
+  method: string;
+  url: string;
+  ip: string;
+  user?: string;
+  ms: number;
+  /** fail 专用:响应 code + message(5xx 追加 detail 异常真相) */
+  code?: number;
+  message?: string;
+  detail?: string;
+}
+
+@Injectable()
+export class ApiLogService implements OnModuleDestroy {
+  private readonly logger = new Logger('ApiLog');
+  private readonly writer: JsonlDailyWriter;
+  private readonly slowMs: number;
+  private lastDropWarned = 0;
+
+  constructor(cfg: ConfigService<AppConfig, true>) {
+    const c = cfg.get<AppConfig['apiLog']>('apiLog');
+    this.slowMs = c.slowMs;
+    this.writer = new JsonlDailyWriter({
+      dir: path.resolve(process.cwd(), c.dir),
+      prefix: 'apilog',
+      retainDays: c.retainDays,
+      maxFileMb: c.maxFileMb
+    });
+    this.writer.cleanupExpired();
+    this.writer.startDailyCleanup();
+  }
+
+  /** 优雅停机关流冲刷(SIGTERM→app.close() 链路;进程 exit 另有同步兜底双保险) */
+  onModuleDestroy(): void {
+    this.writer.stop();
+  }
+
+  /** 慢请求阈值 ms(拦截器判定用) */
+  get slowThresholdMs(): number {
+    return this.slowMs;
+  }
+
+  /** 登记一条(失败或慢);请求参数统一在此脱敏截断 */
+  record(entry: ApiLogEntry, req: { query?: any; body?: any; rawBody?: any }): void {
+    const written = this.writer.write({
+      ts: localTs(),
+      ...entry,
+      query: this.sanitize(req.query),
+      body: this.extractBody(req)
+    });
+    if (!written) {
+      // 滚动淘汰/背压丢条:每 500 条 warn 一次留痕(不静默)
+      const dropped = this.writer.droppedCount;
+      if (dropped - this.lastDropWarned >= 500) {
+        this.lastDropWarned = dropped;
+        this.logger.warn(`apilog 滚动淘汰旧日志累计 ${dropped} 条(单文件容量滚动兜底生效,详见方案 §2.4)`);
+      }
+    }
+  }
+
+  /** 提取客户端 IP(与限流/登录审计同口径:trust proxy 时 req.ip 已按 XFF 解析) */
+  static ipOf(req: any): string {
+    try {
+      return req?.ip || req?.socket?.remoteAddress || req?.connection?.remoteAddress || '';
+    } catch {
+      return '';
+    }
+  }
+
+  /** body 提取:json 走 rawBody 保真解析(失败降级截断原文),multipart 取 multer 字段 */
+  private extractBody(req: { rawBody?: any; body?: any }): unknown {
+    const raw = req?.rawBody;
+    if (Buffer.isBuffer(raw)) {
+      try {
+        return this.sanitize(JSON.parse(raw.toString('utf8')));
+      } catch {
+        // 非 JSON(已消费/损坏):截断原文,只求留痕
+        return raw.toString('utf8').slice(0, 200);
+      }
+    }
+    // multipart(上传)/urlencoded:body 为字段对象(文件内容不记)
+    return this.sanitize(req?.body);
+  }
+
+  /** 脱敏 + 截断:敏感 key 值→***;字符串 200 字符;对象最多 10 键;递归深度 3 */
+  private sanitize(value: unknown, depth = 0): unknown {
+    if (value === null || value === undefined) return value;
+    if (typeof value === 'string') {
+      return value.length > 200 ? `${value.slice(0, 200)}…` : value;
+    }
+    if (typeof value !== 'object') return value;
+    if (depth >= 3) return '[深对象截断]';
+    if (Array.isArray(value)) {
+      return value.slice(0, 10).map((v) => this.sanitize(v, depth + 1));
+    }
+    const out: Record<string, unknown> = {};
+    let count = 0;
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      if (count >= 10) {
+        out['[字段截断]'] = true;
+        break;
+      }
+      out[k] = MASK_KEYS.has(k.toLowerCase()) ? '***' : this.sanitize(v, depth + 1);
+      count += 1;
+    }
+    return out;
+  }
+}