create-ssnode-cli 0.2.5 → 0.2.7

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

@@ -7,7 +7,7 @@ import type { AppConfig } from '../../config/config.interface';
 /**
  * 运维调试日志(《后端日志体系整改方案》§2)
  *
- * API 失败登记(≥400)与慢请求登记(>slowMs)落 data/apilog/apilog-YYYY-MM-DD.jsonl,
+ * API 失败登记(≥400)与慢请求登记(>slowMs)落 logs/apilog/apilog-YYYY-MM-DD.jsonl,
  * 2xx 成功请求不记(内网单体下全量访问日志是纯噪音)。traceId 由 main.ts 中间件
  * 挂到 req 并回传 X-Trace-Id 响应头——联调时用户报一个 traceId,grep 一次定位全链路。
  *

package/templates/backend/src/common/config-crypto.ts

@@ -0,0 +1,133 @@
+import { aesGcmDecrypt } from './app-crypto';
+
+/**
+ * 配置密文(jasypt 式)加载期解密
+ *
+ * 设计/运维手册见 docs/config-encryption.md。yaml/env 中敏感值以 `ENC(...)` 包裹存储,
+ * 进程启动时由 configuration.ts 在「base+overlay 合并之后」对最终配置树统一调用 decryptConfigValues
+ * 解开为明文,下游 config.get(...) 拿到的就是明文,业务零改动。
+ *
+ * 密文格式(三段,以 `.` 分隔,各段 base64):
+ *   ENC(<b64(iv)>.<b64(authTag)>.<b64(ciphertext)>)
+ *   - iv      : 12 字节 GCM IV(每次加密随机)
+ *   - authTag : 16 字节 GCM 认证标签
+ *   - ciphertext : AES-256-GCM 密文
+ *
+ * 密钥:CONFIG_SECRET_KEY env(base64 的 32 字节)。根密钥在服务器首部署选「开启配置加密」
+ * 时生成(ops/lib-encrypt.sh),只存服务器 APP_ROOT/.prod.secrets(600,三模式统一注入:
+ * systemd EnvironmentFile / pm2 env / docker run -e),不入 git、开发机零密钥;
+ * dev 明文运行(security.encrypt=false),不涉及密钥。
+ *
+ * 安全边界(诚实声明):本机制防「仓库 / release 包 / 镜像 / 配置外发」泄露,
+ * 不防「已能登服务器读 env / 内存」的攻击者(root 可读 env 与解密后内存)。
+ */
+
+const ENC_PREFIX = 'ENC(';
+const ENC_SUFFIX = ')';
+/** base64 的 32 字节密钥长度(AES-256) */
+const KEY_BYTES = 32;
+
+/** 判断是否为 ENC(...) 包裹的密文 */
+export function isEncryptedValue(v: unknown): v is string {
+  return typeof v === 'string' && v.startsWith(ENC_PREFIX) && v.endsWith(ENC_SUFFIX);
+}
+
+/**
+ * 从 env 取 CONFIG_SECRET_KEY 并校验为 base64 的 32 字节密钥。
+ * 返回 base64 原串(app-crypto 的 aesGcmDecrypt 内部 Buffer.from(key,'base64'))。
+ * 缺失/非法 → 抛错(由调用方决定 fail-fast 还是 dev 回退)。
+ */
+export function loadConfigSecretKey(envKey = 'CONFIG_SECRET_KEY'): string {
+  const raw = process.env[envKey];
+  if (!raw) {
+    throw new Error(
+      `[config-crypto] 缺少 ${envKey} 环境变量,无法解密配置中的 ENC(...) 值。` +
+        `加密模式的根密钥在服务器 APP_ROOT/.prod.secrets(首部署生成),` +
+        `经部署通道注入:systemd EnvironmentFile / pm2 env / docker run -e。`
+    );
+  }
+  let buf: Buffer;
+  try {
+    buf = Buffer.from(raw, 'base64');
+  } catch {
+    throw new Error(`[config-crypto] ${envKey} 不是合法 base64`);
+  }
+  if (buf.length !== KEY_BYTES) {
+    throw new Error(
+      `[config-crypto] ${envKey} 解密后为 ${buf.length} 字节,期望 ${KEY_BYTES} 字节(AES-256)。请用 genkey 重新生成。`
+    );
+  }
+  return raw;
+}
+
+/**
+ * 解密单个 ENC(...) 值为明文。
+ * @param value  形如 ENC(b64(iv).b64(authTag).b64(cipher)) 的字符串
+ * @param secretKeyB64  base64 的 32 字节密钥
+ */
+export function decryptValue(value: string, secretKeyB64: string): string {
+  const inner = value.slice(ENC_PREFIX.length, -ENC_SUFFIX.length);
+  const parts = inner.split('.');
+  if (parts.length !== 3) {
+    throw new Error(
+      `[config-crypto] 密文格式非法:期望 ENC(iv.authTag.cipher) 三段,实得 ${parts.length} 段`
+    );
+  }
+  const [ivB64, tagB64, cipherB64] = parts;
+  let iv: Buffer;
+  let authTag: Buffer;
+  let ciphertext: Buffer;
+  try {
+    iv = Buffer.from(ivB64, 'base64');
+    authTag = Buffer.from(tagB64, 'base64');
+    ciphertext = Buffer.from(cipherB64, 'base64');
+  } catch {
+    throw new Error('[config-crypto] 密文各段不是合法 base64');
+  }
+  try {
+    return aesGcmDecrypt(ciphertext, secretKeyB64, iv, authTag).toString('utf8');
+  } catch {
+    // GCM 认证失败:密钥错 / 密文被篡改 / 三段错序,统一不泄露细节
+    throw new Error('[config-crypto] 解密失败(密钥不匹配或密文已损坏)');
+  }
+}
+
+/**
+ * 递归遍历配置对象,把所有 ENC(...) 字符串值就地替换为明文。
+ * 仅处理 string;number/boolean/数组/嵌套对象照常递归,数组内字符串一并解密。
+ * 遇非法密文 / 解密失败即抛错(fail-fast,由 configuration.ts 决定是否启动)。
+ */
+export function decryptConfigValues(node: unknown, secretKeyB64: string): void {
+  if (node === null || node === undefined) return;
+  if (Array.isArray(node)) {
+    for (let i = 0; i < node.length; i++) {
+      const item = node[i];
+      if (isEncryptedValue(item)) {
+        node[i] = decryptValue(item, secretKeyB64);
+      } else if (typeof item === 'object') {
+        decryptConfigValues(item, secretKeyB64);
+      }
+    }
+    return;
+  }
+  if (typeof node === 'object') {
+    for (const [k, v] of Object.entries(node as Record<string, unknown>)) {
+      if (isEncryptedValue(v)) {
+        (node as Record<string, unknown>)[k] = decryptValue(v, secretKeyB64);
+      } else if (typeof v === 'object') {
+        decryptConfigValues(v, secretKeyB64);
+      }
+    }
+  }
+}
+
+/** 检测配置树中是否含有 ENC(...) 值(用于决定是否要求密钥) */
+export function hasEncryptedValues(node: unknown): boolean {
+  if (node === null || node === undefined) return false;
+  if (isEncryptedValue(node)) return true;
+  if (Array.isArray(node)) return node.some(hasEncryptedValues);
+  if (typeof node === 'object') {
+    return Object.values(node as Record<string, unknown>).some(hasEncryptedValues);
+  }
+  return false;
+}

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

@@ -46,7 +46,7 @@ export interface AppConfig {
     /** 单文件最大字节 */
     maxSize: number;
   };
-  /** 超管账号(yaml 为权威,启动 reconcile 到 DB;prod 真值已入库 config.prod.yaml,env 为可选覆盖) */
+  /** 超管账号(yaml 为权威,启动 reconcile 到 DB;prod 真值在环境 overlay / 部署位 config.yaml) */
   admin: {
     username: string;
     password: string;
@@ -74,7 +74,7 @@ export interface AppConfig {
    * (better-sqlite3/mysql 同钩子 maxQueryExecutionTime → logQuerySlow)
    */
   slowSql: {
-    /** 落盘目录(cwd 相对;docker 下随 /app/data volume,默认 data/slowsql) */
+    /** 落盘目录(cwd 相对,默认 logs/slowsql;docker 下随 /app/logs volume 单独挂载) */
     dir: string;
     /** 慢查询阈值 ms,同时作为 TypeORM maxQueryExecutionTime */
     thresholdMs: number;
@@ -87,9 +87,28 @@ export interface AppConfig {
     /** 单日文件上限 MB(超限滚动瘦身留新去旧,丢条计数随 stats 留痕) */
     maxFileMb: number;
   };
+  /** 配置加密总开关 */
+  security: {
+    /**
+     * 是否强制配置加密。true:敏感字段(默认 jwt.secret / admin.password / sso.ticketKey /
+     * appSign.cryptKey,清单见 encryptedFields)非空必须是 ENC(...) 密文,启动校验、
+     * 漏填明文 fail-fast;false:全部接受明文(已存在的 ENC(...) 仍照常解密,向后兼容)。
+     * 模板 base 恒 false(仓库层明文维护);服务器首部署选「开启加密」时 install.sh
+     * (ops/ensure-encrypt.cjs)把部署位 config.yaml 的此键置 true 并就地加密敏感值。
+     * 老配置缺 security 段时按 true(强制)对齐历史口径。
+     */
+    encrypt: boolean;
+    /**
+     * 受控加密字段清单(dot-path,相对配置树根部)。security.encrypt=true 时清单内字段
+     * 非空且非 ENC(...) → 拒启(仅 string 值参与校验,数组/数字字段不适用)。
+     * 打包产物是混淆后的 dist,改清单只改 yaml 即可、无需重编译;
+     * 老配置缺该项回落内置默认四项(向后兼容)。
+     */
+    encryptedFields?: string[];
+  };
   /** 运维调试日志(《后端日志体系整改方案》§2):API 失败(≥400)/慢请求登记,JSONL 落盘 */
   apiLog: {
-    /** 落盘目录(cwd 相对;docker 下随 /app/data volume,默认 data/apilog) */
+    /** 落盘目录(cwd 相对,默认 logs/apilog;docker 下随 /app/logs volume 单独挂载) */
     dir: string;
     /** 慢请求阈值 ms(超时记 slow;2xx 成功不记) */
     slowMs: number;

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

@@ -2,19 +2,35 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'js-yaml';
 import type { AppConfig } from './config.interface';
+import {
+  decryptConfigValues,
+  hasEncryptedValues,
+  isEncryptedValue,
+  loadConfigSecretKey
+} from '../common/config-crypto';
 
 /**
- * 按 NODE_ENV 加载对应 yaml 配置,默认 develop
- * 文件位于 backend/config/config.{env}.yaml;buildops 产物保留 config/config.<env>.yaml 原名。
+ * 配置加载:config.base.yaml(全量默认)+ 环境 overlay 深合并,单一真相源。
  *
- * prod 真值(jwt 密钥/签名密钥/admin 凭证/端口等)已入库 config.prod.yaml——systemd/pm2
- * 以 cwd=current 经 resolveConfig 直读;环境变量为可选覆盖通道(docker 经 .env 注入、
- * 或免改 yaml 轮换时用),env 未设则回退 yaml 值。本地 dev 不设 env 仍用 yaml。
- * 超管账号 yaml 为权威(启动 reconcile 到 DB,支持改配置+重启轮换);占位值(change-me/空)
- * 时 user.service 跳过 reconcile、不写弱默认,作防御兜底。
+ * 文件形态(backend/config/,新发布环境只需增一份 overlay):
+ *   config.base.yaml        全量默认值 + 注释权威(所有环境共享)
+ *   config.develop.yaml     开发 overlay:只写与 base 不同的键 + 本环境凭证(明文)
+ *   config.prod.yaml        生产 overlay:同上,仓库/传输层明文维护 —— 服务器首部署选「开启
+ *                           配置加密」时,install.sh 把部署位副本的敏感值就地加密为 ENC(...)
+ *                           (新环境 = 复制一份改值,如 config.demo.yaml,加密同此路径)
+ *   config.yaml             部署位 overlay 固定名:install.sh 首部署从所选 overlay 播种到
+ *                           APP_ROOT/config/(此后发布不覆盖,运维/开发在其上维护该环境真值)
  *
- * 镜像自带 config.<env>.yaml 作默认,部署 docker run -e 注入各环境值,
- * 换 env 即换环境,无需每环境一个镜像。
+ * 目录定位(优先级):CONFIG_DIR env(systemd unit / pm2 ecosystem 注入 = APP_ROOT/config)
+ *   > cwd/config(dev 与 docker 容器:cwd=/app,挂载或镜像内 config)
+ *   > __dirname/../../config(tsc 多文件布局兜底)。
+ * overlay 选择(同目录内):config.yaml(部署位固定名)> config.<NODE_ENV>.yaml(dev 侧按环境名)。
+ *
+ * env 覆盖只剩部署拓扑项(容器内路径/端口,由部署脚本注入,与业务配置无关):
+ *   PORT / DB_DIR / UPLOAD_STORAGE_PATH / SLOW_SQL_DIR / API_LOG_DIR / CONFIG_SECRET_KEY(根密钥)
+ * 业务配置一律走 yaml:新增键 = base 加键 + config.interface.ts 加类型 + 消费处读取,
+ * 不再需要动任何 env 模板/部署文件(这是收敛「一处新增多处改」的根因修复)。
+ * 改部署位 APP_ROOT/config/config.yaml + 重启 即生效(改密轮换同路径,三模式行为一致)。
  */
 
 const envStr = (k: string, fallback?: string): string | undefined => {
@@ -27,111 +43,182 @@ const envInt = (k: string, fallback?: number): number | undefined => {
   const n = Number(v);
   return Number.isFinite(n) ? n : fallback;
 };
-const envBool = (k: string, fallback?: boolean): boolean | undefined => {
-  const v = process.env[k];
-  if (v === undefined || v === '') return fallback;
-  return v === 'true' || v === '1';
-};
-const envList = (k: string, fallback?: string[]): string[] | undefined => {
-  const v = process.env[k];
-  if (v === undefined || v === '') return fallback;
-  return v.split(',').map((s) => s.trim()).filter(Boolean);
-};
+
+/** 深合并:overlay 的键覆盖 base 同位键,对象递归、数组/标量整体替换 */
+function deepMerge<T>(base: T, overlay: T): T {
+  if (
+    Array.isArray(base) || Array.isArray(overlay) ||
+    typeof base !== 'object' || typeof overlay !== 'object' ||
+    base === null || overlay === null
+  ) {
+    return overlay;
+  }
+  const out: Record<string, unknown> = { ...(base as Record<string, unknown>) };
+  for (const k of Object.keys(overlay as Record<string, unknown>)) {
+    out[k] = deepMerge((base as Record<string, unknown>)[k], (overlay as Record<string, unknown>)[k]);
+  }
+  return out as T;
+}
 
 export default (): AppConfig => {
   const env = process.env.NODE_ENV || 'develop';
-  const file = `config.${env}.yaml`;
 
-  // 配置文件定位：cwd 优先（运维部署 cwd 即版本根，单文件 dist/main.js 也能找到 config/），
-  // __dirname 兜底（兼容 tsc 多文件布局 dist/config/configuration.js → ../../config）。
-  // 三种部署形态都命中,不依赖固定目录深度:
-  //   1) cwd 根 config.yaml   — buildops 运维包布局(整包根放 config.yaml,不分 env)
-  //   2) cwd/config/<name>    — dev/docker/多 env 布局(config.<env>.yaml)
-  //   3) __dirname/../../config/<name> — tsc 多文件布局(dist/config → ../../config)
-  const resolveConfig = (name: string) => {
-    const rootCfg = path.join(process.cwd(), 'config.yaml');
-    if (fs.existsSync(rootCfg)) return rootCfg;
-    const byCwd = path.join(process.cwd(), 'config', name);
-    if (fs.existsSync(byCwd)) return byCwd;
-    return path.join(__dirname, '../../config', name);
-  };
-  const filePath = resolveConfig(file);
+  // 配置目录定位:CONFIG_DIR(部署脚本注入,存在 config.base.yaml 才算数)
+  //   > cwd/config(dev 与 docker 容器) > __dirname/../../config(tsc 布局兜底)。
+  // 候选链保证:首选目录无 base 时回落下一候选(兼容无 base 的老布局 —— env
+  // overlay 单独成完整配置);全部无 base 时用首个存在目录。
+  const candidates: string[] = [];
+  if (process.env.CONFIG_DIR) candidates.push(process.env.CONFIG_DIR);
+  candidates.push(path.join(process.cwd(), 'config'));
+  candidates.push(path.join(__dirname, '../../config'));
+  let configDir = candidates[0];
+  for (const c of candidates) {
+    if (fs.existsSync(path.join(c, 'config.base.yaml'))) {
+      configDir = c;
+      break;
+    }
+  }
+  if (!fs.existsSync(path.join(configDir, 'config.base.yaml'))) {
+    for (const c of candidates) {
+      if (fs.existsSync(c)) { configDir = c; break; }
+    }
+  }
 
-  let config: AppConfig;
+  // base:全量默认(缺文件按空对象 —— 老布局无 base 时 overlay 单独成完整配置)
+  let base: Partial<AppConfig> = {};
   try {
-    const text = fs.readFileSync(filePath, 'utf8');
-    config = yaml.load(text) as AppConfig;
-  } catch (e) {
-    // 找不到对应环境文件时回退到 develop
-    config = yaml.load(fs.readFileSync(resolveConfig('config.develop.yaml'), 'utf8')) as AppConfig;
+    base = yaml.load(fs.readFileSync(path.join(configDir, 'config.base.yaml'), 'utf8')) as Partial<AppConfig>;
+  } catch {
+    // base 不存在或不可解析:按空对象继续
   }
 
-  return {
-    ...config,
+  // overlay:部署位固定名 config.yaml > 环境 overlay config.<env>.yaml(都不在则仅 base)
+  const overlayName = fs.existsSync(path.join(configDir, 'config.yaml'))
+    ? 'config.yaml'
+    : `config.${env}.yaml`;
+  let overlay: Partial<AppConfig> = {};
+  try {
+    overlay = yaml.load(fs.readFileSync(path.join(configDir, overlayName), 'utf8')) as Partial<AppConfig>;
+  } catch {
+    // overlay 不存在:纯 base 也能起(占位值直跑)
+  }
+
+  // 断言同旧实现(yaml.load as AppConfig):base 全量键由模板保证,类型层不重复推导
+  const merged = deepMerge(base, overlay) as AppConfig;
+
+  const config: AppConfig = {
+    ...merged,
+    // security 老配置缺段按 true(强制)对齐文档「密码类一律密文」口径
+    security: {
+      encrypt: merged.security?.encrypt ?? true,
+      encryptedFields: merged.security?.encryptedFields
+    },
     app: {
-      ...config.app,
-      port: envInt('PORT', config.app.port) as number,
-      corsOrigins: envList('CORS_ORIGINS', config.app.corsOrigins) as string[],
-      trustProxy: envBool('TRUST_PROXY', config.app.trustProxy) as boolean
+      ...merged.app,
+      // PORT = 部署拓扑项(docker 权威 = .prod.docker.env 的 PORT,run-container.sh -e 注入;
+      // 未注入则回退 yaml app.port)
+      port: envInt('PORT', merged.app?.port) as number,
+      corsOrigins: merged.app?.corsOrigins ?? [],
+      trustProxy: merged.app?.trustProxy ?? false
     },
     database: {
-      ...config.database,
-      // DB_DIR:仅目录(容器内如 /app/data、宿主绝对路径)。
-      // 文件名由程序按 NODE_ENV 定死为 template.<env>.sqlite(prod=template.prod.sqlite /
-      // dev=template.dev.sqlite),不外配;未设 DB_DIR 则用 yaml 的 dir(相对 data/ → WORKDIR /app)。
-      dir: envStr('DB_DIR', config.database.dir) as string
+      ...merged.database,
+      // DB_DIR:仅目录(容器内如 /app/data、宿主绝对路径),部署脚本注入
+      dir: envStr('DB_DIR', merged.database?.dir) as string
     },
     jwt: {
-      ...config.jwt,
-      secret: envStr('JWT_SECRET', config.jwt.secret) as string,
-      expiresIn: envStr('JWT_EXPIRES', config.jwt.expiresIn) as string
+      secret: merged.jwt?.secret ?? '',
+      expiresIn: merged.jwt?.expiresIn ?? '8h'
     },
     log: {
-      ...config.log,
-      level: envStr('LOG_LEVEL', config.log.level) as string
+      level: merged.log?.level ?? 'info'
     },
     upload: {
-      ...config.upload,
-      // 上传目录随 data volume 走(如 /app/data/uploads)
-      storagePath: envStr('UPLOAD_STORAGE_PATH', config.upload.storagePath) as string
+      ...merged.upload,
+      // 上传目录:部署脚本注入(容器内随 data volume,如 /app/data/uploads)
+      storagePath: envStr('UPLOAD_STORAGE_PATH', merged.upload?.storagePath) as string
     },
     // 超管账号:yaml 为权威,启动时 user.service 把 DB reconcile 到此值
-    // (支持「改配置 + 重启」轮换)。prod 真值已入库 config.prod.yaml;ADMIN_USERNAME/
-    // ADMIN_PASSWORD env 为可选覆盖(docker 经 .env、或免改 yaml 轮换时用)。
-    // 占位值(change-me/空)时 user.service 跳过、不写弱默认,作防御兜底。
+    // (支持「改部署位 config.yaml + 重启」轮换)。占位值(change-me/空)时
+    // user.service 跳过 reconcile、不写弱默认,作防御兜底。
     admin: {
-      ...config.admin,
-      username: envStr('ADMIN_USERNAME', config.admin.username) as string,
-      password: envStr('ADMIN_PASSWORD', config.admin.password) as string
+      username: merged.admin?.username ?? 'admin',
+      password: merged.admin?.password ?? ''
     },
     appSign: {
-      ...config.appSign,
-      signKey: envStr('APP_SIGN_KEY', config.appSign.signKey) as string,
-      tsWindow: envInt('APP_SIGN_TS_WINDOW', config.appSign.tsWindow) as number
+      signKey: merged.appSign?.signKey ?? '',
+      cryptKey: merged.appSign?.cryptKey ?? '',
+      tsWindow: merged.appSign?.tsWindow ?? 300
     },
     sso: {
-      ...config.sso,
-      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
+      enabled: merged.sso?.enabled ?? false,
+      ticketKey: merged.sso?.ticketKey ?? '',
+      tsWindow: merged.sso?.tsWindow ?? 300
     },
-    // 慢SQL探针 + 运维调试日志:与全局「env > yaml > 内置默认」语义一致,
-    // 老配置文件不带 slowSql/apiLog 段也能起。
+    // 慢SQL探针 + 运维调试日志:落盘目录为部署拓扑项(部署脚本指到 APP_ROOT/logs),
+    // 其余阈值走 yaml;base/overlay 不带段也能起(内置默认)
     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
+      dir: envStr('SLOW_SQL_DIR', merged.slowSql?.dir ?? 'logs/slowsql') as string,
+      thresholdMs: merged.slowSql?.thresholdMs ?? 50,
+      lagMs: merged.slowSql?.lagMs ?? 200,
+      hostSampleSec: merged.slowSql?.hostSampleSec ?? 60,
+      retainDays: merged.slowSql?.retainDays ?? 14,
+      maxFileMb: merged.slowSql?.maxFileMb ?? 10
     },
-    // 运维调试日志:只记 ≥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
+      dir: envStr('API_LOG_DIR', merged.apiLog?.dir ?? 'logs/apilog') as string,
+      slowMs: merged.apiLog?.slowMs ?? 1000,
+      retainDays: merged.apiLog?.retainDays ?? 14,
+      maxFileMb: merged.apiLog?.maxFileMb ?? 10
     }
   };
+
+  // 防呆校验(security.encrypt,缺 security 段按 true 对齐历史口径):敏感字段非空却不是
+  // ENC(...) 密文 → fail-fast,防「以为加密了实际裸奔」。模板 base 恒 false(仓库层明文),
+  // 服务器首部署选「开启加密」时由 ops/ensure-encrypt.cjs 把部署位 config.yaml 的此键置
+  // true —— 此后手改明文直接重启会被本校验拦下,提示回 ./install.sh 自动重新加密(轮换闭环)。
+  // 受控字段清单来自 security.encryptedFields(base 可配,缺省回落内置默认),打包产物 dist
+  // 是混淆源码,改清单只改 yaml、无需重编译。校验在解密之前(只看 ENC 前后缀)。
+  // 空占位不拦(与「占位可直跑」一致)。置 false 完全放开(不建议 prod)。
+  if (config.security.encrypt) {
+    const DEFAULT_ENCRYPTED_FIELDS = [
+      'jwt.secret',
+      'admin.password',
+      'sso.ticketKey',
+      'appSign.cryptKey'
+    ];
+    // dot-path 解析配置树(label 形如 'jwt.secret');解析不到 = 清单写错,报出而非静默跳过
+    const getByPath = (obj: unknown, dotted: string): unknown =>
+      dotted.split('.').reduce<unknown>((o, k) => {
+        return typeof o === 'object' && o !== null ? (o as Record<string, unknown>)[k] : undefined;
+      }, obj);
+    const fields = config.security.encryptedFields?.length
+      ? config.security.encryptedFields
+      : DEFAULT_ENCRYPTED_FIELDS;
+    const plainSensitive: string[] = [];
+    for (const label of fields) {
+      const value = getByPath(config, label);
+      if (typeof value === 'string' && value && !isEncryptedValue(value)) plainSensitive.push(label);
+    }
+    if (plainSensitive.length) {
+      throw new Error(
+        `[configuration] security.encrypt=true:以下敏感字段为明文,必须写 ENC(...) 密文` +
+          `(base 与环境 overlay 同强制):${plainSensitive.join(' / ')}。` +
+          `加密:重跑 ./install.sh(自动用服务器根密钥就地把明文加密);` +
+          `或手动 \`node scripts/config-crypt.cjs encrypt "<明文>" $CONFIG_SECRET_KEY\`;` +
+          `或把 config.yaml 的 security.encrypt 置 false 以明文运行(不建议 prod)。`
+      );
+    }
+  }
+
+  // jasypt 式解密:ENC(...) 密文值统一解开为明文,下游 config.get(...) 零改动。
+  // ENC 只存在于服务器侧(首部署「开启配置加密」后由 install.sh 就地加密部署位 config.yaml,
+  // 见 ops/ensure-encrypt.cjs);根密钥 CONFIG_SECRET_KEY 在服务器生成并只存服务器
+  // (APP_ROOT/.prod.secrets,600;systemd EnvironmentFile / pm2 env / docker run -e 注入),
+  // 开发机零密钥。密钥缺失/解密失败 → 抛错中断启动(fail-fast,不带病运行);
+  // 无 ENC 值时不要求密钥(明文/占位直跑)。
+  if (hasEncryptedValues(config)) {
+    decryptConfigValues(config, loadConfigSecretKey());
+  }
+  return config;
 };

package/templates/backend/src/database/migrations/0001-init.migration.ts

@@ -10,7 +10,7 @@ import { MigrationInterface, QueryRunner } from 'typeorm';
  *   string → TEXT,number → INTEGER,boolean → INTEGER(0/1),Date → TEXT/DATETIME
  *
  * 五张框架表:user / screen_config / page_data / audit_log / image。
- * 业务扩展:新增实体后 `pnpm --filter backend migration:generate src/database/migrations/xxxx`
+ * 业务扩展:新增实体后 `pnpm --filter ./backend migration:generate src/database/migrations/xxxx`
  * 生成新迁移文件,并在 sqlite.config.ts 的 migrations 数组显式 import 注册(必须,勿漏)。
  */
 export class Init1740000000000 implements MigrationInterface {

package/templates/backend/src/database/slow-sql.logger.ts

@@ -12,7 +12,7 @@ import { sqlFingerprint, hostTension } from './sql-fingerprint';
  * 切 MySQL 时本文件零改动,只在 MySQL options 侧严禁顺手开 enableQueryTimeout
  * (那会把 maxQueryExecutionTime 变成 server 端杀查询的超时)。
  *
- * 记录落独立 JSONL(data/slowsql/slowsql-YYYY-MM-DD.jsonl),非应用日志——是调试
+ * 记录落独立 JSONL(logs/slowsql/slowsql-YYYY-MM-DD.jsonl),非应用日志——是调试
  * 期间的证据链,供 slowsql-report.mjs 后期分析。三类记录:
  *   sql    慢查询样本(内联最近宿主快照 host 字段;《后端日志体系整改方案》§4.2 起
  *          同指纹每日仅前 5 条落全量,其余只进 stats 计数——影响大的就是那几条,

package/templates/backend/src/database/sqlite.config.ts

@@ -52,8 +52,8 @@ export const buildTypeOrmOptions = (
   const db = config.get<AppConfig['database']>('database');
   const env = process.env.NODE_ENV || 'develop';
   const isProd = env === 'prod';
-  // 文件名按环境定死(不外配):prod=template.prod.sqlite / dev=template.dev.sqlite,
-  // 与运维脚本 ops/sqlite/config.sh、ops 探针约定一致。仅目录(dir/DB_DIR)可外配。
+  // 文件名按环境定死(不外配):prod=template.prod.sqlite / dev=template.dev.sqlite。
+  // 仅目录(dir/DB_DIR)可外配。
   const dbFilename = isProd ? 'template.prod.sqlite' : 'template.dev.sqlite';
   // 慢SQL探针(《慢SQL探针与SQL优化路径方案》):挂 TypeORM Logger 层,驱动无关——
   // better-sqlite3 与 mysql 两驱动的 QueryRunner 都内置同一钩子(maxQueryExecutionTime

package/templates/backend/src/main.ts

@@ -27,7 +27,7 @@ async function bootstrap() {
     if (!jwtSecret || jwtSecret === DEV_DEFAULT_SECRET) {
       throw new Error(
         `[security] NODE_ENV=${nodeEnv} 但 jwt.secret 为空/开发默认值,拒绝启动。` +
-          '请在 config.prod.yaml 或 JWT_SECRET 环境变量注入强密钥(CLI 生成的项目已自动注入)。'
+          '请在环境 overlay yaml(config.prod.yaml / 部署位 config.yaml)注入强密钥(CLI 生成的项目已自动注入)。'
       );
     }
   } else if (!nodeEnv) {
@@ -101,7 +101,7 @@ async function bootstrap() {
   const origins = cfg.get<AppConfig['app']>('app').corsOrigins;
   if (!origins.length) {
     throw new Error(
-      '[security] app.corsOrigins 为空——请在 yaml 配置前端来源(或 CORS_ORIGINS env)后重启。'
+      '[security] app.corsOrigins 为空——请在 yaml 配置前端来源后重启。'
     );
   }
   app.enableCors({
@@ -111,7 +111,7 @@ async function bootstrap() {
 
   // 可信反代:默认关闭——直连部署(compose 直暴端口)下 x-forwarded-for 可伪造,
   // 限流/审计 IP 一律取 socket 对端。前置 nginx 时设 yaml app.trustProxy=true
-  // (或 env TRUST_PROXY),req.ip 即按 XFF 正确解析客户端 IP。
+  // (yaml 配置),req.ip 即按 XFF 正确解析客户端 IP。
   if (cfg.get<AppConfig['app']>('app').trustProxy) {
     app.set('trust proxy', 1);
   }

package/templates/backend/src/modules/ops/ops-probe.interface.ts

@@ -19,9 +19,9 @@
 export const OPS_PROBE = Symbol('OPS_PROBE');
 
 export interface OpsProbe {
-  /** 探针唯一标识，前端按此聚合，如 'sqlite-backup' */
+  /** 探针唯一标识，前端按此聚合，如 'backend-version' */
   readonly key: string;
-  /** 展示名，如「SQLite 备份」 */
+  /** 展示名，如「后台版本」 */
   readonly name: string;
   /** 卡片渲染形态 */
   readonly kind: OpsProbeKind;
@@ -38,7 +38,7 @@ export interface OpsProbeResult {
   kind: OpsProbeKind;
   /** healthy: true=正常 / false=异常 / unknown=探针自身无法判定（如目录不存在） */
   healthy: boolean | 'unknown';
-  /** 一句话摘要，状态卡用，如「最近备份 3 小时前」 */
+  /** 一句话摘要，状态卡用，如「v1.2.3」 */
   summary: string;
   /** 详情，结构随 kind 不同（见下方 *Detail）。前端按 kind 解析。 */
   detail: OpsStatusDetail | OpsTableDetail | OpsLogDetail;

package/templates/backend/src/modules/ops/ops.module.ts

@@ -3,9 +3,6 @@ import { OpsService } from './ops.service';
 import { OpsController } from './ops.controller';
 import { VersionController } from './version.controller';
 import { OPS_PROBE, type OpsProbe } from './ops-probe.interface';
-import { SqliteBackupProbe } from './sqlite-backup.probe';
-import { SqliteBackupListProbe } from './sqlite-backup-list.probe';
-import { SqliteBackupLogProbe } from './sqlite-backup-log.probe';
 import { BackendVersionProbe } from './backend-version.probe';
 
 /**
@@ -16,10 +13,7 @@ import { BackendVersionProbe } from './backend-version.probe';
  *   加到下方 providers 数组即可。OpsService 通过多 provider 注入自动发现，
  *   controller / 前端均无需改动。
  *
- * 当前探针（A 阶段，全只读 SQLite 备份相关）：
- *   - SqliteBackupProbe      status  状态卡（最近备份时间 / 健康灯 / 份数）
- *   - SqliteBackupListProbe  table   备份历史表
- *   - SqliteBackupLogProbe   log     备份日志尾
+ * 当前探针：
  *   - BackendVersionProbe    status  后台版本号（package.json version）
  *
  * 未来 B 阶段可挂（各自新文件 + 加到 providers）：
@@ -29,9 +23,6 @@ import { BackendVersionProbe } from './backend-version.probe';
   providers: [
     OpsService,
     // 各探针以自身类 token 注册（可被下方工厂注入）
-    SqliteBackupProbe,
-    SqliteBackupListProbe,
-    SqliteBackupLogProbe,
     BackendVersionProbe,
     // NestJS 不支持 Angular 的 multi:true，同 token 的 { provide, useClass } 会互相覆盖
     // （最后一个胜出）。故用工厂把所有探针实例聚合成数组，注入到 OPS_PROBE token，
@@ -41,7 +32,7 @@ import { BackendVersionProbe } from './backend-version.probe';
     {
       provide: OPS_PROBE,
       useFactory: (...probes: OpsProbe[]) => probes,
-      inject: [SqliteBackupProbe, SqliteBackupListProbe, SqliteBackupLogProbe, BackendVersionProbe]
+      inject: [BackendVersionProbe]
     }
   ],
   controllers: [OpsController, VersionController],

package/templates/backend/src/modules/user/user.service.ts

@@ -32,7 +32,7 @@ export class UserService implements OnModuleInit {
    * 超管(superadmin)仅此一个,随配置注入,后台 UI 不可创建/不可见/不可改。
    * admin/普通用户由后台 UI 管理。
    * 「改配置 + 重启」即完成轮换(如三月一换)。
-   * prod 真值已入库 config.prod.yaml(直读);ADMIN_PASSWORD env 为可选覆盖。占位值
+   * prod 真值在环境 overlay / 部署位 config.yaml(直读)。占位值
    * (change-me/空)时跳过 reconcile、不写弱默认,作防御兜底。
    */
   async onModuleInit() {
@@ -43,7 +43,7 @@ export class UserService implements OnModuleInit {
     // 占位/空:防御性跳过,不写库(yaml 已带真值时正常走 reconcile;此处仅兜底异常配置)。
     if (!password || /^change-?me$/i.test(password)) {
       this.logger.warn(
-        `admin.password 为占位值,跳过超管 reconcile(检查 ${isProd ? 'config/config.prod.yaml 或 ADMIN_PASSWORD env' : 'config.develop.yaml'})`
+        `admin.password 为占位值,跳过超管 reconcile(检查 ${isProd ? '环境 overlay / 部署位 config.yaml 的 admin.password' : 'config.develop.yaml'})`
       );
       return;
     }