create-ssnode-cli 0.2.5 → 0.2.7

package/README.md

@@ -85,7 +85,7 @@ $ npm create ssnode-cli my-app
 
 生成过程自动完成,不需要手工改任何模板占位:
 
-- **身份替换**:包名(子包派生 `<name>-web`/`<name>-backend`)、后台顶栏标题、Swagger 标题、SQLite 文件名、docker 镜像/容器名、systemd/pm2 服务名、服务器部署根目录、编排脚本 `--filter` 名——生成物零模板残留(CI 守卫每次发布前扫描断言)
+- **身份替换**:包名(子包派生 `<name>-web`/`<name>-backend`)、后台顶栏标题、Swagger 标题、SQLite 文件名、docker 镜像/容器名、systemd/pm2 服务名、服务器部署根目录、编排脚本 `--filter`(路径形态 `./web`/`./backend`,包名改名免疫)——生成物零模板残留(CI 守卫每次发布前扫描断言)
 - **密钥生成注入**:dev/prod 两套独立密钥(JWT secret、大屏签名 signKey、超管密码、AES cryptKey),前后端成对同值写入并回读校验;超管账号打印在控制台
 - **git init + 首次 commit**、**pnpm install**(交互可选)
 

package/index.js

@@ -272,7 +272,8 @@ async function main() {
     pkg.name = name;
     pkg.description = `${displayName}(create-ssnode-cli 生成)`;
     writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
-    // web/backend 子包名:<name>-web / <name>-backend(与 --filter 派生名一致)
+    // web/backend 子包名:<name>-web / <name>-backend(编排 filter 已用 ./web 路径形态,
+    // 包名改名免疫;保留派生名是为 yarn1 workspace——它只认包名,不认路径)
     for (const [dir, suffix] of [['web', '-web'], ['backend', '-backend']]) {
       const p2 = join(targetDir, dir, 'package.json');
       const sub = JSON.parse(readFileSync(p2, 'utf-8'));
@@ -299,22 +300,13 @@ async function main() {
       const envPath = stack === 'fullstack' ? join(targetDir, 'web', envFile) : join(targetDir, envFile);
       writeFileSync(envPath, injectWebEnv(readFileSync(envPath, 'utf-8'), mode, secrets[mode].signKey));
     }
-    // backend yaml(仅 fullstack)
+    // backend yaml(仅 fullstack):凭证明文注入环境 overlay —— dev 开箱即跑,prod 明文维护,
+    // 加密交由服务器首部署按需开启(install.sh 询问,见 docs/config-encryption.md)
     if (stack === 'fullstack') {
       for (const [mode, yamlFile] of [['develop', 'config.develop.yaml'], ['prod', 'config.prod.yaml']]) {
         const yamlPath = join(targetDir, 'backend', 'config', yamlFile);
         writeFileSync(yamlPath, injectBackendYaml(readFileSync(yamlPath, 'utf-8'), secrets[mode]));
       }
-      // docker .env.example 一并种子化(README 必改清单第 2 条的 docker 面)
-      const envExamplePath = join(targetDir, 'backend', 'ops', 'docker', '.env.example');
-      let envExample = readFileSync(envExamplePath, 'utf-8');
-      envExample = envExample
-        .replace('JWT_SECRET=', `JWT_SECRET=${secrets.prod.jwtSecret}`)
-        .replace('ADMIN_PASSWORD=', `ADMIN_PASSWORD=${secrets.prod.adminPassword}`)
-        .replace('APP_SIGN_KEY=', `APP_SIGN_KEY=${secrets.prod.signKey}`)
-        .replace('SSO_TICKET_KEY=', `SSO_TICKET_KEY=${secrets.prod.ssoTicketKey}`)
-        .replace('# ⚠️ 模板占位:新项目务必换成自己的强密钥(与 config.prod.yaml / web/.env.production 同款)。', '# 已由脚手架生成(与 config.prod.yaml / web/.env.production 同款)。');
-      writeFileSync(envExamplePath, envExample);
     }
     // 回读校验:fullstack 做前后端成对一致(硬约束);web-only 只需确认注入成功
     const files = {};
@@ -334,14 +326,14 @@ async function main() {
     secretsPrintout = secrets;
     s.message('密钥已生成并注入(前后端成对一致)');
   } else {
-    // backend-only:只注 yaml(无前端 env)
+    // backend-only:只注环境 overlay yaml(无前端 env);凭证明文,加密由服务器首部署按需开启
     const secrets = generateSecrets();
     for (const [mode, yamlFile] of [['develop', 'config.develop.yaml'], ['prod', 'config.prod.yaml']]) {
       const yamlPath = join(targetDir, 'config', yamlFile);
       writeFileSync(yamlPath, injectBackendYaml(readFileSync(yamlPath, 'utf-8'), secrets[mode]));
     }
     secretsPrintout = secrets;
-    s.message('密钥已生成并注入 yaml');
+    s.message('密钥已生成并明文注入 yaml(dev 开箱即跑;prod 加密由服务器首部署按需开启)');
   }
 
   // ── ⑦ git init + 首次 commit ──
@@ -365,19 +357,20 @@ async function main() {
   }
   p.log.success(`项目已生成:${targetDir}`);
 
-  // ── ⑧ 密钥打印(仅控制台,不落盘;密钥本体已在文件里) ──
+  // ── ⑧ 密钥打印(明文凭证只进控制台 + 生成项目文件;服务器侧加密按需开启) ──
   if (secretsPrintout) {
     if (stack !== 'web') {
       // 超管账号只对含 backend 的变体有意义(web-only 无后端可 reconcile)
       const cfgPath = (f) => (stack === 'fullstack' ? `backend/config/${f}` : `config/${f}`);
       p.log.info('超管账号(启动时 reconcile 入库,牢记):');
-      console.log(`    dev : admin / ${secretsPrintout.develop.adminPassword}   ← 改密:${cfgPath('config.develop.yaml')} 的 admin.password + 重启`);
-      console.log(`    prod: admin / ${secretsPrintout.prod.adminPassword}   ← 改密:${cfgPath('config.prod.yaml')} 的 admin.password + 重启(docker 用 .env 的 ADMIN_PASSWORD)`);
+      console.log(`    dev : admin / ${secretsPrintout.develop.adminPassword}   ← 改密:换入 ${cfgPath('config.develop.yaml')} 明文 + 重启`);
+      console.log(`    prod: admin / ${secretsPrintout.prod.adminPassword}   ← 改密:换部署位 config.yaml 明文 + 重跑 ./install.sh(加密模式自动重新加密)`);
+      p.log.info('凭证均为明文注入 yaml(dev 开箱即跑,prod 明文维护);服务器首部署时 install.sh 会询问是否开启配置加密(开启后服务器生成根密钥并就地加密,见 docs/config-encryption.md)');
     }
     if (stack === 'fullstack') {
-      p.log.info('签名/JWT 密钥已写入 web/.env.* 与 backend/config/*.yaml(前后端已同值,无需手抄)');
+      p.log.info('签名密钥已写入 web/.env.* 与 backend yaml 的 signKey(前后端同值)');
     } else if (stack === 'backend') {
-      p.log.info('签名/JWT 密钥已写入 config/*.yaml;将来接前端时,把 appSign.signKey 同值填入前端 .env');
+      p.log.info('签名密钥已写入 config/*.yaml 的 signKey;将来接前端时,把同值填入前端 .env');
     } else {
       p.log.info('签名密钥已写入 .env.development / .env.production;将来接后端时,把同值填入后端 yaml 的 appSign.signKey');
     }
@@ -406,12 +399,14 @@ function nextSteps(stack, targetDir, installed, pm) {
   if (stack === 'fullstack') {
     lines.push(`${pm} ${pm === 'npm' ? 'run ' : ''}dev          # web(6177)+ backend(3001)${pm === 'npm' ? '(workspace 顺序执行)' : ''}`);
     lines.push('→ 部署前:配 SSH 凭证 web/scripts/server.config.json + backend/scripts/server.config.cjs(从 example 拷)');
+    lines.push('→ 首部署时 install.sh 会询问是否开启配置加密(服务器生成根密钥并就地加密 config.yaml,无需手抄)');
   } else if (stack === 'web') {
     lines.push(`${pm} ${pm === 'npm' ? 'run ' : ''}dev          # 端口 6177;checkToken=false 免登录`);
     lines.push('→ 接后端时:public/env.config.js 的 checkToken 改回 true,并填 .env.* 签名密钥');
   } else {
     lines.push(`${pm} ${pm === 'npm' ? 'run ' : ''}dev          # 端口 3001;管理走 /api/docs Swagger`);
     lines.push('→ 部署前:配 SSH 凭证 scripts/server.config.cjs(从 example 拷)');
+    lines.push('→ 首部署时 install.sh 会询问是否开启配置加密(服务器生成根密钥并就地加密 config.yaml,无需手抄)');
   }
   return lines.join('\n');
 }
@@ -442,10 +437,11 @@ ${common}
 ${common}
 ## 本变体要点(backend-only)
 
-- **管理走 Swagger**:dev 起动后 /docs(Swagger 挂根路径,不带 /api 前缀);超管账号见 config.*.yaml 的 admin(password 已由脚手架生成,启动 reconcile 入库)。
+- **管理走 Swagger**:dev 起动后 /docs(Swagger 挂根路径,不带 /api 前缀);超管账号见 config.develop.yaml 的 admin(password 已由脚手架生成,启动 reconcile 入库)。
+- **prod 配置加密**:首部署时 install.sh 询问是否开启(服务器生成根密钥并就地加密部署位 config.yaml);日常轮换 = 改明文 + 重跑 ./install.sh,详见 docs/config-encryption.md。
 - **迁移显式注册**:新增迁移必须手动加进 src/database/sqlite.config.ts 的 migrations 数组(既定约定,漏注册 prod 不建表)。
 - **构建** = nest build(tsc)+ terser 混淆;better-sqlite3 v13 需 python3/make/g++ 源码编译。
-- **DB 文件名程序定死**:<name>.prod.sqlite / <name>.dev.sqlite(已随生成物改名,四处同步见 sqlite.config.ts)。
+- **DB 文件名程序定死**:<name>.prod.sqlite / <name>.dev.sqlite(已随生成物改名,同步点见 sqlite.config.ts)。
 - \`${cmd('dev')}\` 端口 3001;\`${cmd('build')}\` = nest build(tsc)+ terser 混淆。
 `;
 }

package/package.json

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

package/secrets.js

@@ -1,21 +1,28 @@
 /**
  * secrets.js — 密钥生成与注入(纯函数 + 注入器)
  *
- * 生成 dev/prod 两套独立密钥,注入前后端共 8 个点:
+ * 生成 dev/prod 两套独立密钥,注入前后端共 6 个点:
  *   web/.env.development        VITE_APP_SIGN_KEY     ← dev signKey
  *   web/.env.production         VITE_APP_SIGN_KEY     ← prod signKey
- *   backend/config/config.develop.yaml  jwt.secret / admin.password / appSign.signKey
- *   backend/config/config.prod.yaml     jwt.secret / admin.password / appSign.signKey
+ *   backend/config/config.develop.yaml  环境 overlay:jwt.secret / admin.password / appSign.signKey 等
+ *   backend/config/config.prod.yaml     环境 overlay:同上(密码只入 yaml,不再有 env 通道)
  *
  * 硬约束(README「必改清单」第 2 条):大屏签名密钥前后端必须逐字同值 ——
  * 本模块从同一个生成值写到两端,从根上消灭「改了一端忘另一端」。
  *
+ * ⚠️ 凭证形态(2026-10 收口,运维手册 docs/config-encryption.md):
+ *   仓库/开发机层一律【明文】注入环境 overlay yaml —— 开发零密钥零加密操作(dev 开箱即跑,
+ *   prod 明文维护)。ENC(...) 加密只在服务器侧发生:首部署 install.sh 会询问是否开启配置
+ *   加密,选开启则服务器生成根密钥(APP_ROOT/.prod.secrets)并把部署位 config.yaml 的
+ *   敏感值就地加密,此后每次部署自动加密新增明文(改明文 + 重跑 ./install.sh = 轮换闭环)。
+ *   signKey 前后端 bundle 均可见,恒明文、前后端同值注入。
+ *
  * 密钥形态:
- *   signKey    32 字节 hex(64 字符)  — HMAC-SHA256
- *   jwtSecret  48 字节 hex(96 字符)  — 签发/校验 JWT
- *   password   16 字节 urlSafe       — 超管密码(打印给用户,启动 reconcile 到 DB)
- *   cryptKey   32 字节 base64        — AES-256-GCM 预留(本期未启用,一并生成免得后期补)
- *   ssoTicket  32 字节 hex(64 字符)  — SSO 票据校验(默认关闭,接入时启用)
+ *   signKey     32 字节 hex(64 字符)  — HMAC-SHA256(明文,前后端同值)
+ *   jwtSecret   48 字节 hex(96 字符)  — 签发/校验 JWT(明文入 overlay yaml,服务器侧可选加密)
+ *   password    16 字节 urlSafe        — 超管密码(打印给用户;入 overlay yaml,启动 reconcile 到 DB)
+ *   cryptKey    32 字节 base64         — AES-256-GCM 预留(入 overlay yaml)
+ *   ssoTicket   32 字节 hex(64 字符)  — SSO 票据校验(入 overlay yaml;默认关闭)
  */
 import { randomBytes } from 'node:crypto';
 
@@ -58,37 +65,28 @@ export function injectWebEnv(content, mode, signKey) {
 }
 
 /**
- * 注入 backend/config/config.<env>.yaml:
- *   jwt.secret / admin.password / appSign.signKey / appSign.cryptKey / sso.ticketKey
- *   五个空值字段。锚点 = `字段名: ''`(模板统一空字符串占位);只替换 yaml 值层,不碰注释。
+ * 注入 backend/config/config.<env>.yaml(环境 overlay,只含差异值 + 凭证锚点;全量默认在
+ * config.base.yaml,由 configuration.ts 深合并不需要注入):
+ *   signKey / jwt.secret / admin.password / appSign.cryptKey / sso.ticketKey 五个字段,全部明文
+ *   (加密交由服务器首部署按需进行,见文件头)。
+ * 锚点 = `<field>: '<任意单引号串>'`(模板统一单引号占位);只替换 yaml 值层,不碰注释。
+ * 若锚点缺失则报错,绝不静默跳过。
  */
 export function injectBackendYaml(content, secrets) {
-  const pairs = [
-    ['jwt', 'secret', secrets.jwtSecret],
-    ['admin', 'password', secrets.adminPassword],
-    ['appSign', 'signKey', secrets.signKey],
-    ['appSign', 'cryptKey', secrets.cryptKey],
-    ['sso', 'ticketKey', secrets.ssoTicketKey],
-  ];
-  // 源仓 develop yaml 的 jwt.secret / admin.password 为 dev 固定值(npm run dev 可直启),
-  // 注入时同样替换——生成项目的 develop 也用随机密钥。
-  const DEV_DEFAULTS = {
-    secret: `secret: dev-only-jwt-secret-not-for-prod`,
-    password: `password: admin123`
+  const fields = {
+    secret: secrets.jwtSecret,
+    password: secrets.adminPassword,
+    cryptKey: secrets.cryptKey,
+    ticketKey: secrets.ssoTicketKey,
+    signKey: secrets.signKey,
   };
   let out = content;
-  for (const [, field, value] of pairs) {
-    // 同一 yaml 内字段名唯一(secret/password/signKey/cryptKey/ticketKey 不重复出现),
-    // 直接按 `field: ''` 定位;若锚点缺失则报错,绝不静默跳过。
-    const anchor = `${field}: ''`;
-    const devAnchor = DEV_DEFAULTS[field];
-    const useDev = !out.includes(anchor) && devAnchor && out.includes(devAnchor);
-    if (!out.includes(anchor) && !useDev) {
-      throw new Error(`yaml 注入失败:未找到锚点「${anchor}」`);
+  for (const [field, value] of Object.entries(fields)) {
+    const re = new RegExp(`${field}: '[^']*'`);
+    if (!re.test(out)) {
+      throw new Error(`yaml 注入失败:未找到锚点「${field}: '<值>'」`);
     }
-    out = useDev
-      ? out.replace(devAnchor, `${field}: '${value}'`)
-      : out.replace(anchor, `${field}: '${value}'`);
+    out = out.replace(re, `${field}: '${value}'`);
   }
   return out;
 }

package/templates/backend/Dockerfile

@@ -4,18 +4,24 @@
 #     每次 version bump 打断,better-sqlite3 编译只在依赖树真变时重跑;稳态 build 仅 COPY dist,秒级。
 #   - host 的 current/package.json(真 version)由 config.sh::read_tag 读拼 <version>-<ts> tag,不受镜像内归一影响。
 #   - 两阶段同 node:22-slim(debian glibc)→ better-sqlite3 .node ABI 一致,可直接拷。
-#   - 配置注入:镜像带 config.<env>.yaml 作默认值,环境敏感值由 docker run -e 覆盖(configuration.ts 支持 env
-#     override):PORT/CORS_ORIGINS/DB_DIR/JWT_SECRET/APP_SIGN_KEY/ADMIN_PASSWORD/UPLOAD_STORAGE_PATH/LOG_LEVEL 等。
+#   - 配置注入:业务配置走部署位 APP_ROOT/config(只读挂载 /app/config,含 config.base.yaml +
+#     config.yaml 环境 overlay 真值,见 configuration.ts);镜像自带 config/(base+prod)仅作
+#     无挂载时的兜底。env 只剩部署拓扑项(PORT/DB_DIR/UPLOAD_STORAGE_PATH/SLOW_SQL_DIR/API_LOG_DIR)。
 #   - data(sqlite+uploads)持久化走 volume 挂载 /app/data,不进镜像。
 # 改代码:重 build(runtime 的 dist 层变,deps 层 cache 命中,秒级);改依赖:deps 层 cache miss,重装+编译。
 #
 # base:docker.1ms.run/library/node:22-slim(Docker Hub 国内直连不稳,1ms 可用),首次 build 联网。
 
+# app label:构建期由 --build-arg APP_LABEL 注入(ops/docker/install.sh 传运行时 IMAGE,
+# compose build 读 env IMAGE)—— label 与 IMAGE 恒同源,rotate_images 据此定向 prune
+# 本应用悬空镜像,改名无需手动同步。缺省值仅无注入时兜底(与 docker-compose.yml image 对齐)。
+ARG APP_LABEL=fullstack-template-backend
+
 # ── deps 阶段:构建工具 + npm ci + 编译 better-sqlite3 ──
 FROM docker.1ms.run/library/node:22-slim AS deps
-# app label 烙进每一层中间镜像(经典 builder 下 build 失败/中断留下的 <none> 半成品也带标):
-# ops/docker/install.sh::rotate_images 据此定向 prune 本应用悬空镜像。改名须与 ops/docker/config.sh 的 IMAGE 同步。
-LABEL app=fullstack-template-backend
+# 全局 ARG 须在阶段内重声明才可用;label 烙进每一层中间镜像(build 失败/中断的 <none> 半成品也带标)
+ARG APP_LABEL
+LABEL app=$APP_LABEL
 WORKDIR /app
 # better-sqlite3 v13 无预编译二进制(GitHub release 0 asset、npmmirror 仅镜像源码包),prebuild-install
 # 取不到必回退 node-gyp 源码编译,需 python3/make/g++。node:22-slim 无,装之。
@@ -32,20 +38,24 @@ RUN npm config set registry https://registry.npmmirror.com \
 
 # ── runtime 阶段:精简,只带运行所需(无构建工具)──
 FROM docker.1ms.run/library/node:22-slim AS runtime
-LABEL app=fullstack-template-backend
+ARG APP_LABEL
+LABEL app=$APP_LABEL
 WORKDIR /app
 # 编译好的 node_modules(含 better-sqlite3 .node;两阶段同 node:22-slim → ABI 一致)
 COPY --from=deps /app/node_modules ./node_modules
 # 代码层:每次改代码这层变(deps 层仍 cache 命中)
 COPY dist ./dist
-# 默认配置(非敏感值兜底;敏感值由 env 覆盖)
+# 兜底配置(base + prod overlay;正常部署被部署位挂载 /app/config 覆盖,仅无挂载时生效)
 COPY config ./config
 # 真 package.json(带 version;运行时/镜像内一致;read_tag 读的是 host current/package.json)
 COPY package.json ./package.json
 
 ENV NODE_ENV=prod
+# 时区:镜像默认 UTC,不设则日志按天轮转(jsonl-daily-writer)/时间戳比北京时间差 8 小时。
+# 镜像级注入对 ops/docker 与 compose 两条部署路径同时生效;运维临时换区可 run -e TZ=... 覆盖。
+ENV TZ=Asia/Shanghai
 # 运行端口权威 = PORT env(install.sh/compose 从 .env 注入,app 读 PORT 监听;迁移换端口只改 .env)。
-# 镜像内 config/config.prod.yaml 的 app.port 仅作未注入 PORT 时的兜底默认值。
+# 镜像内 config/(base+prod)的 app.port 仅作未注入 PORT 且无挂载时的兜底默认值。
 # EXPOSE 仅为元数据(默认 3001),实际端口由运行期 PORT env 决定。
 EXPOSE 3001
 CMD ["node", "dist/main.js"]

package/templates/backend/config/config.base.yaml

@@ -0,0 +1,130 @@
+# ═══════════════════════════════════════════════════════════════════
+# 基础配置(全量默认值 + 注释权威)—— 所有环境共享,单一真相源
+#
+# 配置形态(见 configuration.ts):
+#   config.base.yaml     ← 本文件:全量键 + 注释(配置说明只写这一份)
+#   config.<env>.yaml    ← 环境 overlay:只写与 base 不同的键 + 本环境凭证(明文维护;
+#                          服务器侧可选加密,见下 security 段);开发 = config.develop.yaml、
+#                          生产 = config.prod.yaml,新发布环境 = 复制一份 overlay 改值
+#                          (如 config.demo.yaml)。
+# 合并语义 = 深合并(overlay 的键覆盖 base 同位键,其余继承 base)。
+#
+# 新增配置:只在 base 加键 + config.interface.ts 加类型 + 消费处读取 ——
+# 无需再动任何 env 模板/部署文件(部署位 config.yaml 只是 overlay 的副本)。
+#
+# 部署模型:buildops 包随行 base + 全部 overlay;首部署 install.sh 选 overlay 播种为
+# APP_ROOT/config/config.yaml(此后发布不覆盖,运维/开发在其上维护该环境真值);
+# 改部署位 config.yaml + 重启 即生效(改密轮换同路径,三模式行为一致)。
+# ═══════════════════════════════════════════════════════════════════
+
+# 配置加密总开关(见 docs/config-encryption.md §0):true 时 encryptedFields 清单内的敏感值
+# 非空必须写 ENC(...) 密文(base 与环境 overlay 同强制),启动校验、明文即拒启;
+# false 时全部接受明文(已存在的 ENC(...) 仍照常解密)。
+# 模板恒 false(仓库层明文维护,dev 零密钥);服务器首部署选「开启加密」时由
+# install.sh(ops/ensure-encrypt.cjs)把部署位 config.yaml 的此键置 true 并就地加密敏感值。
+# 受控字段清单为 dot-path:新增敏感字段加进清单即可,无需改源码(dist 混淆产物同理)。
+security:
+  encrypt: false
+  encryptedFields:
+    - jwt.secret
+    - admin.password
+    - sso.ticketKey
+    - appSign.cryptKey
+
+app:
+  port: 3001
+  globalPrefix: api
+  corsOrigins:
+    - 'http://localhost:6177'
+  # 是否信任前置反代(nginx)。默认 false:直连部署下 x-forwarded-for 可伪造;
+  # 前置 nginx 时置 true,限流/审计 IP 才会按 XFF 解析
+  trustProxy: false
+
+database:
+  type: better-sqlite3
+  # 仅目录:文件名由程序定死为 template.<env>.sqlite(prod=template.prod.sqlite),不外配
+  # 部署时由 publish-common 注入 backendDataDir(绝对路径),或 DB_DIR env 覆盖
+  dir: data
+  synchronize: false
+  logging:
+    - error
+
+jwt:
+  # 明文维护(环境 overlay 填真实值);服务器侧可选加密(首部署开启后,部署位 config.yaml
+  # 存 ENC(...) 密文,由 APP_ROOT/.prod.secrets 的根密钥在启动时解密;空占位跳过校验)。
+  secret: ''
+  expiresIn: 8h
+
+log:
+  level: info
+
+# 限流:每分钟 60 次(精确路径匹配,忽略 query)
+# login/ssologin 不进白名单——在 auth.controller 单独紧限流(每 IP 10/min)防爆破;
+# captcha 也不豁免——SVG 生成 CPU 密集,免限流会被打挂(登录页每分钟最多取 60 次足够)
+throttle:
+  limit: 60
+  ttl: 60
+  whitelist:
+    - /api/user/islogin
+
+# 文件上传:nginx 静态资源目录
+upload:
+  urlPrefix: /static/uploads
+  # nginx 静态目录路径:dev 相对(随 cwd),prod 由 overlay 覆盖为服务器绝对路径
+  storagePath: ./data/uploads
+  allowedExt:
+    - .jpg
+    - .jpeg
+    - .png
+    - .webp
+    - .gif
+    - .mp4
+  maxSize: 10485760
+
+# 慢SQL探针:挂 TypeORM Logger 层,记录落 logs/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 同口径脱敏。
+# 落 logs/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 到此值
+# (改部署位 config.yaml 的 admin.password + 重启 即完成轮换,如三月一换;加密模式下重跑
+# ./install.sh 自动把新明文加密,服务器上不需要 config-crypt)。
+# 占位值(change-me/空)启动跳过 reconcile(不写弱默认),作防御兜底。
+admin:
+  username: admin
+  # 环境 overlay 填真实明文(CLI 生成项目时自动随机生成);服务器侧可选加密为 ENC(...)
+  password: ''
+
+# 单点登录 /api/ssologin(演示接入范式,默认关闭;未开启时接口返回 404)
+# 开启后接入方(门户/统一认证)持 ticketKey 生成跳转 URL:
+#   GET /api/ssologin?username=xxx&ts=<unix秒>&sign=HMAC-SHA256('username\nts', ticketKey) hex
+# role 固定 'web'(最小权限),勿给该角色挂敏感路由。
+sso:
+  enabled: false
+  # 票据密钥为纯后端秘密:接入时环境 overlay 填真实值(服务器侧可选加密为 ENC(...))
+  ticketKey: ''
+  # 时间戳允许偏差(秒),±5min
+  tsWindow: 300
+
+# 大屏 API 签名加密(无 token、无过期)
+# signKey 与前端 VITE_APP_SIGN_KEY 须逐字一致(前端 bundle 可见,聚类恒明文,不走 ENC);
+# 轮换改环境 overlay(或部署位 config.yaml)+ 重启。
+# cryptKey 是纯后端秘密:环境 overlay 填真实值(服务器侧可选加密为 ENC(...))。
+appSign:
+  signKey: ''
+  cryptKey: ''
+  tsWindow: 300

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

@@ -1,95 +1,28 @@
-# 开发环境配置
+# 开发环境 overlay —— 深合并到 config.base.yaml 之上,只写与 base 不同的键。
+# dev 一律明文(security.encrypt=false,无根密钥/无 .develop.secrets):
+# 下方占位值即开箱即跑的 dev 假值,锚点行('<field>: '<任意单引号串>'')留给 CLI 生成项目时
+# 注入真实明文凭证。prod 加密(ENC 密文)只在服务器侧发生,见 docs/config-encryption.md。
 app:
   port: 4001
-  globalPrefix: api
-  corsOrigins:
-    - 'http://localhost:6177'
-  # 是否信任前置反代(nginx)。默认 false:直连部署下 x-forwarded-for 可伪造;
-  # 前置 nginx 时置 true,限流/审计 IP 才会按 XFF 解析(env: TRUST_PROXY)
-  trustProxy: false
 
 database:
-  type: better-sqlite3
-  # 仅目录:文件名由程序定死为 template.<env>.sqlite(dev=template.dev.sqlite),不外配
-  dir: data
   synchronize: true
   logging: true
 
 jwt:
-  # dev 专用固定密钥:让源仓 npm run dev 可直接启动(CLI 生成项目时会被随机密钥覆盖,勿用于 prod)
-  secret: dev-only-jwt-secret-not-for-prod
-  expiresIn: 8h
+  # dev 假密钥(dev-only,不用于 prod)
+  secret: 'dev-only-jwt-secret-not-for-prod'
 
 log:
   level: debug
 
-# 限流:每分钟 60 次(精确路径匹配,忽略 query)
-# login/ssologin 不进白名单——在 auth.controller 单独紧限流(每 IP 10/min)防爆破;
-# captcha 也不豁免——SVG 生成 CPU 密集,免限流会被打挂(登录页每分钟最多取 60 次足够)
-throttle:
-  limit: 60
-  ttl: 60
-  whitelist:
-    - /api/user/islogin
-
-# 文件上传:nginx 静态资源目录
-upload:
-  # 可访问 URL 前缀(nginx location 映射)
-  urlPrefix: /static/uploads
-  # nginx 静态目录绝对路径,后端把文件写到此处
-  storagePath: ./data/uploads
-  allowedExt:
-    - .jpg
-    - .jpeg
-    - .png
-    - .webp
-    - .gif
-    - .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:
-  username: admin
-  # dev 专用弱密码:让源仓 npm run dev 能直接登录(CLI 生成项目时会被随机强密钥覆盖,勿用于 prod)
-  password: admin123
-
+  # dev 口令 admin123(启动 reconcile 入库;CLI 生成项目时随机覆盖)
+  password: 'admin123'
 
-# 单点登录 /api/ssologin(演示接入范式,默认关闭;未开启时接口返回 404)
-# 开启后接入方(门户/统一认证)持 ticketKey 生成跳转 URL:
-#   GET /api/ssologin?username=xxx&ts=<unix秒>&sign=HMAC-SHA256('username\nts', ticketKey) hex
-# role 固定 'web'(最小权限),勿给该角色挂敏感路由。
 sso:
-  enabled: false
   ticketKey: ''
-  # 时间戳允许偏差(秒),±5min
-  tsWindow: 300
 
-# 大屏 API 签名加密(无 token、无过期)
-# 签名密钥前端构建期注入 bundle,本期只启用请求侧签名;cryptKey 后期响应/body 加密用
 appSign:
-  # HMAC-SHA256 签名密钥,32+ 字符随机串,永不过期。须与 web/.env.development 逐字一致。
   signKey: ''
-  # AES-256-GCM 内容加密密钥,base64(32 字节)。本期保留不校验
   cryptKey: ''
-  # 时间戳允许偏差(秒),±5min
-  tsWindow: 300

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

@@ -1,93 +1,38 @@
-# 生产环境配置
+# 生产环境 overlay —— 深合并到 config.base.yaml 之上,只写与 base 不同的键。
+# 部署模型:本文件随 buildops 包走;首部署 install.sh 把它播种为 APP_ROOT/config/config.yaml
+# (此后发布不覆盖,运维/开发在部署位副本上维护本环境真值;新发布环境 = 复制本文件改值)。
+# 凭证锚点行(空占位 '')留给 CLI 生成项目时注入真实值。
+# 加密模型(见 docs/config-encryption.md):本文件【明文】维护(开发机零密钥零加密操作),
+# 敏感值明文随包传输;首部署 install.sh 会询问是否开启配置加密 —— 选开启则服务器生成
+# 根密钥(.prod.secrets)并把部署位 config.yaml 的非空明文敏感值就地加密为 ENC(...) 密文,
+# 此后每次部署自动加密新增明文(改明文 + 重跑 ./install.sh = 轮换闭环)。
 app:
   port: 3001
-  globalPrefix: api
-  corsOrigins:
-    - 'http://localhost:6177'
-  # 是否信任前置反代(nginx)。默认 false:直连部署下 x-forwarded-for 可伪造;
-  # 前置 nginx 时置 true,限流/审计 IP 才会按 XFF 解析(env: TRUST_PROXY)
-  trustProxy: false
 
 database:
-  type: better-sqlite3
-  # 仅目录:文件名由程序定死为 template.<env>.sqlite(prod=template.prod.sqlite),不外配
-  # 部署时由 publish-common 注入 backendDataDir(绝对路径),或 DB_DIR env 覆盖
-  dir: data
   synchronize: false
   logging:
     - error
 
 jwt:
+  # prod 明文维护,服务器侧(可选)加密为 ENC(...)
   secret: ''
-  expiresIn: 8h
 
 log:
   level: warn
 
-# 限流:每分钟 60 次(精确路径匹配,忽略 query)
-# login/ssologin 不进白名单——在 auth.controller 单独紧限流(每 IP 10/min)防爆破;
-# captcha 也不豁免——SVG 生成 CPU 密集,免限流会被打挂(登录页每分钟最多取 60 次足够)
-throttle:
-  limit: 60
-  ttl: 60
-  whitelist:
-    - /api/user/islogin
-
-# 文件上传:nginx 静态资源目录
 upload:
-  urlPrefix: /static/uploads
+  # 服务器 nginx 静态目录绝对路径(docker 部署由 run-container.sh 的
+  # UPLOAD_STORAGE_PATH env 覆盖为 /app/data/uploads,此值兜底 systemd/pm2)
   storagePath: /data/uploads
-  allowedExt:
-    - .jpg
-    - .jpeg
-    - .png
-    - .webp
-    - .gif
-    - .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、
-# 或免改 yaml 轮换时用)。占位值(change-me/空)启动跳过 reconcile(不写弱默认),作防御兜底。
 admin:
-  username: admin
-  # ⚠️ 模板占位:新项目务必改成强密码(启动 reconcile 到 DB)
+  # prod 明文维护;改部署位 config.yaml 此值 + 重跑 ./install.sh(加密模式自动重新加密)= 轮换
   password: ''
 
-# 单点登录 /api/ssologin(演示接入范式,默认关闭;未开启时接口返回 404)
-# 开启后接入方(门户/统一认证)持 ticketKey 生成跳转 URL:
-#   GET /api/ssologin?username=xxx&ts=<unix秒>&sign=HMAC-SHA256('username\nts', ticketKey) hex
-# role 固定 'web'(最小权限),勿给该角色挂敏感路由。
 sso:
-  enabled: false
   ticketKey: ''
-  # 时间戳允许偏差(秒),±5min
-  tsWindow: 300
 
-# 大屏 API 签名加密(无 token、无过期)
-# signKey 与前端 VITE_APP_SIGN_KEY 须逐字一致;轮换改本 yaml + 重启或 APP_SIGN_KEY env 覆盖。
-# cryptKey 后期响应/body 加密用(本期未启用,占位不可移除——aes-js 解密侧待二期端到端做)。
 appSign:
   signKey: ''
   cryptKey: ''
-  tsWindow: 300