create-ssnode-cli 0.2.5 → 0.2.7

package/templates/web/src/services/app-request.ts

@@ -1,6 +1,7 @@
 import Axios from 'axios';
 import { sha256 as hmacSha256 } from 'js-sha256';
 import ProjectConfig from '../../config/project.config';
+import { enterMaintenance, isApiUnavailable } from './maintenance';
 
 /**
  * 大屏 API 请求实例(无 token、无过期,HMAC 签名)
@@ -160,7 +161,13 @@ appRequest.interceptors.response.use(
     // 后期响应加密时,在此先解密 base64 密文 → { code, message, data }
     return res.data;
   },
-  (error) => Promise.reject(error)
+  (error) => {
+    // 后端不可用(502)→ 整页进入维护页;reject 照常透传给业务侧
+    if (isApiUnavailable(error)) {
+      enterMaintenance();
+    }
+    return Promise.reject(error);
+  }
 );
 
 export default appRequest;

package/templates/web/src/services/maintenance.ts

@@ -0,0 +1,67 @@
+import ProjectConfig from '../../config/project.config';
+
+/**
+ * 维护态检测内核(纯 JS 模块,不依赖 React)
+ *
+ * 触发契约:自家后端接口(/api/**)返回 HTTP 502 —— 通常意味着 nginx 反代
+ * 后面的 backend 挂了或正在发版重启 —— 由 axios 拦截器调用 enterMaintenance(),
+ * 整页跳转到 /maintenance 维护页,并记录来源路径供恢复后跳回。
+ *
+ * 用整页跳转而非 SPA 路由切换:502 风暴时应用内状态已不可信,整页刷新
+ * 顺带清掉所有在途请求与旧页面状态;维护页自带 /api/version 探活自动恢复。
+ */
+
+/** 来源路径在 sessionStorage 的键(隐私模式下存储可能抛错,一律 try/catch) */
+const FROM_KEY = 'maintenance:from';
+
+/** 维护页路由(挂在路由树顶层,含部署目录前缀) */
+const MAINTENANCE_PATH = `${ProjectConfig.directory || ''}/maintenance`;
+
+/** 跳转中标记:并发多个 502 只触发一次跳转 */
+let redirecting = false;
+
+/**
+ * 当前是否已处于维护页(防止维护页内的 502 再次触发跳转形成死循环)
+ */
+export function isMaintenancePage(): boolean {
+  return window.location.pathname === MAINTENANCE_PATH;
+}
+
+/**
+ * 判定一个 axios 错误是否为「后端不可用(502)」
+ * 只认自家 /api 接口,第三方接口 502 不视为系统维护。
+ */
+export function isApiUnavailable(error: any): boolean {
+  return (
+    error?.response?.status === 502 &&
+    typeof error?.config?.url === 'string' &&
+    error.config.url.includes('/api')
+  );
+}
+
+/**
+ * 进入维护页:记录来源路径 → 整页跳转
+ */
+export function enterMaintenance(): void {
+  if (redirecting || isMaintenancePage()) return;
+  redirecting = true;
+  try {
+    sessionStorage.setItem(FROM_KEY, window.location.pathname + window.location.search);
+  } catch (e) {
+    // sessionStorage 不可用(隐私模式等)时放弃记录,恢复后回首页
+  }
+  window.location.href = MAINTENANCE_PATH;
+}
+
+/**
+ * 取出并清除来源路径(维护页恢复时跳回用)
+ */
+export function consumeReturnPath(): string {
+  try {
+    const from = sessionStorage.getItem(FROM_KEY);
+    sessionStorage.removeItem(FROM_KEY);
+    return from && from !== MAINTENANCE_PATH ? from : '/';
+  } catch (e) {
+    return '/';
+  }
+}

package/templates/web/src/services/request.ts

@@ -1,5 +1,6 @@
 import Axios from 'axios';
 import ProjectConfig from '../../config/project.config';
+import { enterMaintenance, isApiUnavailable } from './maintenance';
 
 /**
  * 错误处理
@@ -42,6 +43,10 @@ axiosIntance.interceptors.response.use(
     return res.data;
   },
   (error) => {
+    // 后端不可用(502)→ 整页进入维护页;reject 照常透传给业务侧
+    if (isApiUnavailable(error)) {
+      enterMaintenance();
+    }
     errorHandle();
     return Promise.reject(error);
   }

package/transforms.js

@@ -15,31 +15,30 @@
 /**
  * 按包管理器生成的命令替换规则(模板命令按 pnpm 写,npm/yarn 生成时改写)。
  * 三家在「workspace 过滤」上的等价形态:
- *   pnpm:  pnpm --filter  <pkg> run <script>
- *   npm:   npm  --workspace <pkg> run <script>   (flag 可前置)
- *   yarn1: yarn workspace    <pkg> run <script>  (子命令,非 flag)
+ *   pnpm:  pnpm --filter ./web run <script>       (路径 filter,包名改名免疫)
+ *   npm:   npm  --workspace ./web run <script>    (flag 可前置;--workspace 同样认路径)
+ *   yarn1: yarn workspace <pkg> run <script>      (子命令,非 flag;只认包名 → 派生名)
  * 全 workspace 递归:
  *   pnpm:  pnpm -r [--parallel] run <script>
  *   npm:   npm run <script> --workspaces --if-present(顺序执行,无并行)
  *   yarn1: yarn workspaces run <script>
  * 裸命令:npm 必须 `npm run <script>`,yarn 可直接 `yarn <script>`,pnpm 可直接。
  * 顺序敏感:复合长串先替换,裸 `pnpm ` 兜底(yarn 用)。
+ * pnpm 的 `--filter` 无匹配时退出码为 0(静默跳过)—— 模板 root 编排脚本已用 fs 预检
+ * 子包存在与 script 声明,勿只依赖退出码判断成败。
  */
 export function buildPmRules(pm, name) {
   if (pm === 'pnpm') {
-    return [
-      { find: '--filter web', replace: `--filter ${name}-web` },
-      { find: '--filter backend', replace: `--filter ${name}-backend` },
-    ];
+    return []; // 模板命令原生 pnpm,零改写(filter 已是 ./web 路径形态)
   }
   if (pm === 'npm') {
     return [
       // root scripts(templates/root/package.json 与文档)
       { find: 'pnpm -r --parallel run ', replace: 'npm run --workspaces --if-present ' },
       { find: 'pnpm -r run ', replace: 'npm run --workspaces --if-present ' },
-      // 编排脚本(scripts/{publish,rollback}.cjs 的 spawn)与文档命令
-      { find: 'pnpm --filter web', replace: `npm --workspace ${name}-web` },
-      { find: 'pnpm --filter backend', replace: `npm --workspace ${name}-backend` },
+      // 编排脚本(scripts/{publish,rollback}.cjs 的 spawn)与文档命令(路径 filter 直译)
+      { find: 'pnpm --filter ./web', replace: 'npm --workspace ./web' },
+      { find: 'pnpm --filter ./backend', replace: 'npm --workspace ./backend' },
       // 裸命令(install 除外,npm 裸动词只有内建命令)
       { find: 'pnpm install', replace: 'npm install' },
       { find: 'pnpm dev', replace: 'npm run dev' },
@@ -52,12 +51,12 @@ export function buildPmRules(pm, name) {
       { find: 'pnpm monorepo', replace: 'npm monorepo' },
     ];
   }
-  // yarn1(经典):动词直通 + workspaces 子命令
+  // yarn1(经典):动词直通 + workspaces 子命令;workspace 子命令只认包名 → 用派生名
   return [
     { find: 'pnpm -r --parallel run ', replace: 'yarn workspaces run ' },
     { find: 'pnpm -r run ', replace: 'yarn workspaces run ' },
-    { find: 'pnpm --filter web', replace: `yarn workspace ${name}-web` },
-    { find: 'pnpm --filter backend', replace: `yarn workspace ${name}-backend` },
+    { find: 'pnpm --filter ./web', replace: `yarn workspace ${name}-web` },
+    { find: 'pnpm --filter ./backend', replace: `yarn workspace ${name}-backend` },
     // publish:yarn 裸动词是内建发包命令,必须 run;rollback 顺带统一
     { find: 'pnpm publish', replace: 'yarn run publish' },
     { find: 'pnpm rollback', replace: 'yarn run rollback' },
@@ -90,26 +89,20 @@ export function buildTransforms(id, pm = 'pnpm') {
   // ── 通用规则(所有文本文件全局应用,顺序敏感:长串先替换) ──
   const globalRules = [
     // DB 文件名:template.<env>.sqlite → <dbPrefix>.<env>.sqlite
-    // 出处:sqlite.config.ts:59 / configuration.ts:74-75 / data-source.ts:33 /
-    //      ops/sqlite/config.sh:39-40 / config.{develop,prod}.yaml:10 / docker-compose.yml:28
+    // 出处:sqlite.config.ts:57 / configuration.ts / scripts/data-source.ts:33 /
+    //      config.interface.ts(注释)/ config.base.yaml(注释)/ docker-compose.yml
     { find: 'template.prod.sqlite', replace: `${dbPrefix}.prod.sqlite` },
     { find: 'template.dev.sqlite', replace: `${dbPrefix}.dev.sqlite` },
-    // 模板字符串形态:ops 探针(sqlite-backup*.probe.ts)用 `template.${env}.` 前缀匹配
-    { find: 'template.${env}.', replace: `${dbPrefix}.\${env}.` },
+    // 注释里的形态占位(如 config.interface.ts:16「定死为 template.<env>.sqlite」)
     { find: 'template.<env>.sqlite', replace: `${dbPrefix}.<env>.sqlite` },
-    // 不带扩展名的 TAG/注释/示例形态:
-    //  - sqlite/config.sh:43 TAG 示例 template.prod;sqlite/README.md:25 同
-    //  - sqlite-backup-list.probe.ts:59 'template.prod'/'template.develop' 字面量
-    //  - sqlite-backup.probe.ts:139 dirName 示例 template.prod.<ts>
-    { find: 'template.develop', replace: `${dbPrefix}.develop` },
-    { find: 'template.prod', replace: `${dbPrefix}.prod` },
-    { find: 'template.dev', replace: `${dbPrefix}.dev` },
-    // 部署身份:容器名 / 服务名 / 镜像名 / APP_ROOT
-    // 出处:docker-compose.yml:13,17 / install.sh:392 / docker/config.sh:17,19 /
-    //      systemd/config.sh:7 / pm2/config.sh:7 / restore.sh:103-105 / .env.example:6,7,11
+    // 部署身份:容器名 / 镜像名 / APP_ROOT
+    // 出处:docker-compose.yml(image + build args)/ Dockerfile ARG APP_LABEL 缺省(实际值构建期
+    //      由 ops/docker/install.sh --build-arg 注入;运行时 env 的 IMAGE/TAG 由 ops 派生对齐,
+    //      .prod.docker.env 已是 buildops 自动生成物,不在模板内)
+    // (ops/ 脚本不再烙身份 —— 运行时由 ops/lib.sh::pkg_name 从 current/package.json 派生)
     { find: 'fullstack-template-backend', replace: containerName },
     // 服务器部署根目录
-    // 出处:server.config.example.cjs:28 / ops/sqlite/config.sh:16 / sqlite/README.md:34,37,40,53
+    // 出处:server.config.example.cjs:28,37(targets 注释示例同串,一并替换)
     { find: '/data/server/fullstack-template', replace: appRoot },
     // 模板身份字面量(兜底,放最后;上面的长串已先被替换,不会误伤)
     { find: 'fullstack-template', replace: name },

package/templates/backend/ops/docker/.env.example

@@ -1,40 +0,0 @@
-# docker compose 部署配置(复制为 .env 后改值)。
-# 镜像由 docker/install.sh 以 current/ 为 build context 现场构建 <IMAGE>:<TAG>,此处只引用 IMAGE/TAG。
-# 配置以环境变量注入(configuration.ts 读 env,缺省回退镜像内 yaml)。
-
-# 镜像名 & tag(tag = <version>-<14位ts>,每次部署一个新 tag,旧 tag 留作回滚)。
-# IMAGE 默认 fullstack-template-backend(与 docker/install.sh 的 config.sh 一致,通常不用改)。TAG 必填。
-IMAGE=fullstack-template-backend
-TAG=
-
-# 容器名。
-CONTAINER_NAME=fullstack-template-backend
-
-# 数据根目录(宿主路径,bind mount 进容器 /app/data,跨版本/镜像共享、轮转不动)。
-# db/backup/logs/uploads 全部落此根的子目录,后续追加新子目录无需再加 mount。必填。
-DATA_DIR=
-
-# 运行端口(docker 权威 = 此 PORT env;app 读 PORT 监听,宿主映射 = 容器监听 = PORT)。
-# 迁移新机只改此值即可换端口;systemd/pm2 模式端口权威在 config.prod.yaml,与此无关。
-PORT=3001
-
-# 业务配置(env override,空则用镜像内 config/prod.yaml 缺省)。
-# 注意:DB_DIR/UPLOAD_STORAGE_PATH 已在 docker run/compose 内置(随 /app/data mount 目标锁定),
-#       此处不再暴露,避免部署期改容器内路径致数据写飞(非持久化目录)。
-NODE_ENV=prod
-CORS_ORIGINS=
-# 前置 nginx 等可信反代时置 true(限流/审计 IP 按 x-forwarded-for 解析);直连暴露端口务必 false
-TRUST_PROXY=false
-# ⚠️ 模板占位:新项目务必换成自己的强密钥(与 config.prod.yaml / web/.env.production 同款)。
-# 种子化 .env 时一并带入,免部署期空值阻断。
-# 轮换:改本文件 + 重新部署,或直接改服务器 APP_ROOT/.env + 重启容器。
-JWT_SECRET=
-JWT_EXPIRES=8h
-LOG_LEVEL=warn
-ADMIN_PASSWORD=
-APP_SIGN_KEY=
-APP_SIGN_TS_WINDOW=300
-# 单点登录(默认关闭;接入时改 true 并配 ticketKey,见 README「单点登录」)
-SSO_ENABLED=false
-SSO_TICKET_KEY=
-SSO_TS_WINDOW=300

package/templates/backend/ops/sqlite/README.md

@@ -1,57 +0,0 @@
-# SQLite 运维工具(现场 shell 版)
-
-不依赖 node、不进容器,运维现场可直接跑。脚本随 `backend/ops/sqlite/` 整目录发布到
-宿主 `${backendServiceDir}/ops/sqlite/`(与 backend 发布版本解耦,跨版本共享)。
-首次部署由运维手动把整目录拷到宿主并装 crontab(详见下文「与发布脚本的关系」)。
-
-## 配置
-
-改 `config.sh` 一处即可(`DATA_DIR`/`ENV`/`DB_NAME`/`KEEP`),所有脚本都 source 它。也可由参数覆盖:
-
-| 参数 | 说明 |
-|---|---|
-| `--db <path>` | 主库路径(默认 `${DATA_DIR}/${DB_NAME}`) |
-| `--env <prod\|develop>` | 环境,未显式设 `DB_NAME` 时按此推导文件名(prod→`template.prod.sqlite` / dev→`template.dev.sqlite`,与 app 代码定死的一致) |
-| `--keep <n>` | 保留份数(默认 7) |
-| `--data-dir <dir>` | 数据目录,派生 backup/logs 子目录 |
-| `--backup <dir>` | restore 指定回退的备份目录(不指定则取最近一份) |
-| `--no-recover` | restore 跳过 `.recover`,直接回退备份 |
-
-### 主库文件名(由 app 定死,此处仅作运维定位)
-
-`DB_NAME` 默认按 `ENV` 推导为 `template.prod.sqlite`(prod)/ `template.dev.sqlite`(dev),
-与 app 代码(`sqlite.config.ts` / `data-source.ts`)定死的文件名一致——文件名不外配,
-仅目录(`DB_DIR`/`backendDataDir`)可配。备份目录名随之用 `<tag>.<ts>`
-(`<tag>` = `DB_NAME` 去扩展名:`template.prod.sqlite → template.prod`)。
-
-改 `config.sh` 的 `DB_NAME` 可显式覆盖(如排障指向特定文件),但默认值勿改——
-须与 app 代码定死的文件名一致,否则脚本找不到主库。
-
-## 三件套
-
-```bash
-# 定时在线备份(cron 与手动均用):sqlite3 .backup 产单文件自洽快照(WAL 已并入)
-./backup.sh --db /data/server/fullstack-template/data/template.prod.sqlite --env prod --keep 7
-
-# 损坏快速切换:留现场 → 优先 .recover 抢救 → 回退备份;不重启进程,打印重启命令
-./restore.sh --db /data/server/fullstack-template/data/template.prod.sqlite --env prod
-
-# 健康探针:文件头魔数判定,不依赖 sqlite3 CLI;exit 0 健康 / 1 异常
-./healthcheck.sh --db /data/server/fullstack-template/data/template.prod.sqlite
-```
-
-异常自动切换:`./healthcheck.sh --db <db> --env prod || ./restore.sh --db <db> --env prod`
-
-## 产物与日志(与 ops 页探针同源,勿改)
-
-- 备份目录:`${DATA_DIR}/backup/<tag>.<ts>/<basename>`(单文件自洽主库)
-- 日志文件:`${DATA_DIR}/logs/sqlite-backup.log`(ops 页 `SqliteBackupLogProbe` 读尾 50 行;`❌` 行被判异常,故脚本仅真失败打 `❌`)
-
-## 与发布脚本的关系
-
-- **定时备份(cron)**:本目录 `backup.sh`(在线 `.backup`),由宿主 crontab 调用。
-  首次部署运维手动装:`crontab -e` 加一行(如 `0 3 * * * /data/server/fullstack-template/ops/sqlite/backup.sh --env prod --keep 7 >/dev/null 2>&1`)。
-- **迁移前备份**:原 `scripts/lib/sqlite-backup.cjs`(node cp 三件套)随旧管线删除,不再自动跑。
-  需时手动触发:`./backup.sh --env prod`(在线 `.backup`,WAL 已并入,产物单文件自洽)。
-  restore 兼容历史 cp 三件套产物与 `.backup` 单文件产物(旁文件存在才拷)。
-- 根 `scripts/sqlite-ops.cjs` 早已废弃删除,运维现场统一用本目录 shell 版。

package/templates/backend/ops/sqlite/backup.sh

@@ -1,65 +0,0 @@
-#!/usr/bin/env bash
-# SQLite 在线备份 —— 宿主 sqlite3 .backup 产单文件自洽快照(WAL 已并入),不依赖 node。
-# cron 与手动均用此脚本;产物落 ${DATA_DIR}/backup/${TAG}.<ts>/<basename>,按 KEEP 轮转。
-# 日志 >> ${DATA_DIR}/logs/sqlite-backup.log(ops 页 SqliteBackupLogProbe 读此文件;❌ 行被判异常,故仅真失败打 ❌)。
-#
-# 为什么用 .backup 而非 cp 三件套:
-#   .backup 是 SQLite 在线一致性快照接口,拷贝期间即使 app 在写也产出自洽单文件副本,
-#   不存在 cp 三件套"拷到一半正好有写事务"的中间态风险。docker 下后台随时可能有人配置台写,
-#   无低峰保证,故定时备份必须走 .backup。产物单文件自洽(无 -wal/-shm),restore 已兼容。
-#   迁移前备份也改用本脚本(在线 .backup 单文件自洽),或停 app 后 cp 三件套;旧 deploy 的 node lib/sqlite-backup.cjs 随管线删除,不再自动跑。
-#
-# 用法:
-#   ./backup.sh                                    # 用 config.sh 默认值
-#   ./backup.sh --db <path> --env prod --keep 7 --data-dir <dir>
-#   cron: 0 3 * * * /.../ops/sqlite/backup.sh --db ... --env prod --keep 7 --data-dir ... >/dev/null 2>&1
-set -euo pipefail
-DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-source "$DIR/config.sh"
-
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --db)       DB="$2"; shift 2 ;;
-    --env)      ENV="$2"; shift 2 ;;
-    --keep)     KEEP="$2"; shift 2 ;;
-    --data-dir) DATA_DIR="$2"; shift 2 ;;
-    *) echo "未知参数: $1" >&2; exit 2 ;;
-  esac
-done
-sqlite_derive
-BASENAME="$(basename "$DB")"
-
-# ── 前置检查 ──
-if ! sqlite_has_cli; then
-  sqlite_log "❌ 宿主无 sqlite3,备份无法执行(DB=$DB)。请装 sqlite3 或改方案。"
-  exit 1
-fi
-if [[ ! -f "$DB" ]]; then
-  sqlite_log "⚠️  主库不存在($DB),首次部署跳过。"
-  exit 0
-fi
-
-DEST_DIR="${BACKUP_DIR}/${TAG}.$(_ts)"
-DEST_FILE="${DEST_DIR}/${BASENAME}"
-mkdir -p "$DEST_DIR"
-
-# ── 在线一致性备份 ──
-sqlite_log "▶ 备份开始:sqlite3 \"$DB\" .backup → $DEST_FILE"
-if sqlite3 "$DB" ".backup '$DEST_FILE'" 2>>"$LOG_FILE"; then
-  if sqlite_is_valid "$DEST_FILE"; then
-    SIZE=$(stat -c '%s' "$DEST_FILE" 2>/dev/null || stat -f '%z' "$DEST_FILE")
-    sqlite_log "✅ 备份完成:$DEST_FILE (${SIZE}B,单文件自洽,WAL 已并入)"
-  else
-    sqlite_log "❌ 备份产物非有效 SQLite(魔数不符),已清理:$DEST_FILE"
-    rm -f "$DEST_FILE"; rmdir "$DEST_DIR" 2>/dev/null || true
-    exit 1
-  fi
-else
-  sqlite_log "❌ sqlite3 .backup 失败(见日志上行 stderr),已清理半成品:$DEST_FILE"
-  rm -f "$DEST_FILE"; rmdir "$DEST_DIR" 2>/dev/null || true
-  exit 1
-fi
-
-# ── 轮转 ──
-sqlite_rotate "$BACKUP_DIR" "$TAG" "$KEEP"
-exit 0

package/templates/backend/ops/sqlite/config.sh

@@ -1,91 +0,0 @@
-#!/usr/bin/env bash
-# SQLite 运维共用配置 —— 运维按环境改这一处即可,backup/restore/healthcheck 都 source 它。
-# 与 backend/ops/{docker,systemd,pm2} 的 config.sh 同款:绝对路径、${VAR:-default} env override。
-#
-# 配置项(DATA_DIR/ENV/DB_NAME/KEEP)既可在此改,也可由 deploy cron 行或手动 --db/--env/--keep/--data-dir 覆盖。
-# 不重新打包服务:这些脚本只读 data 目录做文件操作,改值 + 重跑脚本即生效,与 backend 发布解耦。
-#
-# 约定(与 deploy 迁移前备份、ops 页探针保持一致,勿改):
-#   - 备份目录:${DATA_DIR}/backup/${TAG}.<ts>/   (单文件自洽主库,WAL 已并入)
-#   - 日志文件:${DATA_DIR}/logs/sqlite-backup.log      (ops 页 SqliteBackupLogProbe 读此文件尾;
-#     ❌ 行被探针判异常,故各脚本只在真失败时打 ❌,成功打 ✅)
-
-# 环境(develop|prod,决定 DB_NAME/备份目录名 <env>.sqlite / <env>.<ts>)
-ENV="prod"
-# 数据目录(sqlite + uploads + backup + logs 所在;docker 下即 data volume 源=宿主真实目录)
-DATA_DIR="/data/server/fullstack-template/data"
-# 主库文件名(留空则 sqlite_derive 按 ENV 推导,与 app 代码定死的文件名一致:
-# prod=template.prod.sqlite / dev=template.dev.sqlite;--db 显式覆盖)。
-# 文件名由 app 定死不外配,此处仅作运维定位/备份 tag 用,改值须与 app 代码同步。
-DB_NAME=""
-# 主库路径(留空则由 sqlite_derive 推导为 ${DATA_DIR}/${DB_NAME};--db 显式覆盖)
-DB=""
-# 备份保留份数
-KEEP=7
-
-# ── 派生路径(脚本解析完参数后调 sqlite_derive 一次性算定)──
-BACKUP_DIR=""
-LOG_DIR=""
-LOG_FILE=""
-TAG=""
-
-sqlite_derive() {
-  BACKUP_DIR="${DATA_DIR}/backup"
-  LOG_DIR="${DATA_DIR}/logs"
-  LOG_FILE="${LOG_DIR}/sqlite-backup.log"
-  # DB_NAME 未显式设定则按 ENV 推导,与 app 代码定死的文件名一致:
-  #   prod → template.prod.sqlite / dev → template.dev.sqlite(--env 覆盖 ENV 后此处同步生效)。
-  if [[ -z "$DB_NAME" ]]; then
-    if [[ "$ENV" == "prod" ]]; then DB_NAME="template.prod.sqlite";
-    else DB_NAME="template.dev.sqlite"; fi
-  fi
-  # TAG = DB 文件名去扩展名,用作备份目录名前缀(<tag>.<ts>)与轮转/回退 glob。
-  # DB_NAME=template.prod.sqlite → TAG=template.prod;DB_NAME=prod.sqlite → TAG=prod。
-  TAG="${DB_NAME%.*}"
-  # 注意:用 if/then 而非 [[ -z ]] && DB=... —— 后者在 DB 非空时整句返回 1,
-  # 在 set -e 下会让 sqlite_derive 返回 1 致脚本中途退出。
-  if [[ -z "$DB" ]]; then DB="${DATA_DIR}/${DB_NAME}"; fi
-}
-
-# 时间戳:目录名用 YYYYMMDD-HHMMSS(与 releases/<ts> 同款,字典序≈时间序)
-_ts()  { date '+%Y%m%d-%H%M%S'; }
-_now() { date '+%Y-%m-%d %H:%M:%S'; }
-
-# 日志:同时落 LOG_FILE + stdout。cron 行重定向 stdout→/dev/null,LOG_FILE 留记录;手动跑两边都见。
-# LOG_FILE 不可写(目录缺失/权限)时只打 stdout,不致脚本失败。
-sqlite_log() {
-  local msg="[$(_now)] $*"
-  echo "$msg"
-  if [[ -n "${LOG_FILE:-}" ]]; then
-    mkdir -p "$LOG_DIR" 2>/dev/null || true
-    printf '%s\n' "$msg" >> "$LOG_FILE" 2>/dev/null || true
-  fi
-}
-
-# 宿主是否有 sqlite3 CLI
-sqlite_has_cli() { command -v sqlite3 >/dev/null 2>&1; }
-
-# 文件头魔数判定(SQLite 文件头 15 字节 = "SQLite format 3",第 16 字节为 NUL)。
-# 只比首 15 字节的可打印串,避开 NUL —— 兼容 GNU/BSD grep 与 macOS/Linux/macOS sh。
-# (旧法 head -c 16 | grep -q $'...\x00' 在 BSD grep 下匹配 NUL 失败,故弃用。)
-sqlite_is_valid() {
-  local f="$1"
-  [[ -f "$f" ]] || return 1
-  [[ "$(head -c 15 "$f")" = "SQLite format 3" ]]
-}
-
-# 备份轮转:按目录名时间戳倒序,删超 keep 份。
-# while 在子 shell 里跑(管道),计数取不回主 shell,故另用 ls|wc 统计删除数。
-sqlite_rotate() {
-  local bdir="$1" tag="$2" keep="$3"
-  local i=0 total deleted
-  ls -1d "${bdir}"/${tag}.* 2>/dev/null | sort -r | while read -r d; do
-    i=$((i + 1))
-    # if/then 而非 [[ ]] && rm:i<=keep 时整句返回 1 会触发 set -e 退出子 shell 致轮转中断
-    if [[ "$i" -gt "$keep" ]]; then rm -rf "$d"; fi
-  done
-  total=$(ls -1d "${bdir}"/${tag}.* 2>/dev/null | wc -l | tr -d ' ')
-  deleted=$((total - keep))
-  # if/then 而非 [[ ]] && sqlite_log,避免 deleted<=0 时 set -e 中途退出
-  if [[ "$deleted" -gt 0 ]]; then sqlite_log "🧹 轮转:保留 $keep 份(当前共 $total 份),已删 $deleted 份旧备份"; fi
-}

package/templates/backend/ops/sqlite/healthcheck.sh

@@ -1,25 +0,0 @@
-#!/usr/bin/env bash
-# SQLite 健康探针 —— 文件头魔数("SQLite format 3\0")判定,不依赖 sqlite3 CLI。
-# 返回 0=健康,1=异常。供 cron/supervisor 主动检测;异常可串 restore 自动切换:
-#   ./healthcheck.sh --db <db> --env prod || ./restore.sh --db <db> --env prod
-set -euo pipefail
-DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-source "$DIR/config.sh"
-
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --db)        DB="$2"; shift 2 ;;
-    --env)       ENV="$2"; shift 2 ;;
-    --data-dir)  DATA_DIR="$2"; shift 2 ;;
-    *) echo "未知参数: $1" >&2; exit 2 ;;
-  esac
-done
-sqlite_derive
-
-if sqlite_is_valid "$DB"; then
-  echo "✓ 健康: $DB"
-  exit 0
-else
-  echo "✗ 异常: $DB(文件不存在或非 SQLite 格式)" >&2
-  exit 1
-fi

package/templates/backend/ops/sqlite/restore.sh

@@ -1,105 +0,0 @@
-#!/usr/bin/env bash
-# SQLite 损坏快速切换(restore)—— 留现场 + 优先 .recover 抢救 + 回退备份,RTO 秒级。
-# 不重启进程(进程重启由 supervisor 负责),结束时打印 pm2/systemd/docker 重启命令。
-#
-# 流程:
-#   1) 移走损坏主库(连 -wal/-shm 一起)为 <db>.corrupt.<ts>,留现场不删。
-#   2) 若有 sqlite3 CLI 且未 --no-recover:.recover 抢救残页 → .sql → 导入新库 → 魔数校验。
-#   3) .recover 失败/跳过/产物无效 → 回退到最近一份备份目录(或 --backup <dir> 指定):
-#      主库 + -wal/-shm(存在才拷)一起 cp 回原位。
-#   4) .recover 成功路径兜底清 -wal/-shm(重建库本无旁文件);备份还原路径旁文件已就位不动。
-#   5) 不重启进程,打印重启命令。
-#
-# 用法:
-#   ./restore.sh --db <损坏主库> [--env prod] [--backup <备份目录>] [--no-recover] [--data-dir <dir>]
-set -euo pipefail
-DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-source "$DIR/config.sh"
-
-NO_RECOVER=0
-BACKUP_ROOT=""
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --db)         DB="$2"; shift 2 ;;
-    --env)        ENV="$2"; shift 2 ;;
-    --backup)     BACKUP_ROOT="$2"; shift 2 ;;
-    --no-recover) NO_RECOVER=1; shift ;;
-    --data-dir)   DATA_DIR="$2"; shift 2 ;;
-    *) echo "未知参数: $1" >&2; exit 2 ;;
-  esac
-done
-sqlite_derive
-BASENAME="$(basename "$DB")"
-mkdir -p "$LOG_DIR" "$BACKUP_DIR"
-
-[[ -f "$DB" ]] || { echo "✗ 主库不存在: $DB" >&2; exit 1; }
-TS=$(_ts)
-CORRUPT="${DB}.corrupt.${TS}"
-
-# 1) 留现场:损坏主库 + 旁文件一起移走
-echo "▶ 移走损坏主库 → $CORRUPT"
-mv "$DB" "$CORRUPT"
-mv "${DB}-wal" "${CORRUPT}-wal" 2>/dev/null || true
-mv "${DB}-shm" "${CORRUPT}-shm" 2>/dev/null || true
-
-# 2) 优先 .recover 抢救(需 sqlite3 CLI)。注意:.recover 产物是 SQL 文本,
-#    不能 `sqlite3 corrupt ".recover" > db`(非有效库),须先落 .sql 再导入空库重建。
-RESTORED=0
-if sqlite_has_cli && [[ "$NO_RECOVER" -eq 0 ]]; then
-  SQL="${DB}.recovered.${TS}.sql"
-  echo "▶ .recover 抢救残页 → $SQL"
-  if sqlite3 "$CORRUPT" ".recover" > "$SQL" 2>>"$LOG_FILE"; then
-    echo "▶ 导入 $SQL → $DB"
-    if sqlite3 "$DB" < "$SQL" 2>>"$LOG_FILE" && sqlite_is_valid "$DB"; then
-      echo "✓ .recover 抢救成功 → $DB"
-      rm -f "$SQL"
-      RESTORED=1
-    else
-      echo "⚠ .recover 产物导入/校验失败,回退备份" >&2
-      rm -f "$SQL" "$DB"
-    fi
-  else
-    echo "⚠ .recover 失败,清理半成品后回退备份" >&2
-    rm -f "$SQL" "$DB"
-  fi
-elif ! sqlite_has_cli; then
-  echo "⚠ 无 sqlite3 CLI,跳过 .recover,直接回退备份" >&2
-fi
-
-# 3) 回退到最近三件套备份目录
-if [[ "$RESTORED" -eq 0 ]]; then
-  if [[ -z "$BACKUP_ROOT" ]]; then
-    BACKUP_ROOT=$(ls -1d "${BACKUP_DIR}"/${TAG}.* 2>/dev/null | sort -r | head -1)
-  fi
-  BACKUP_MAIN="${BACKUP_ROOT}/${BASENAME}"
-  if [[ -z "$BACKUP_ROOT" || ! -f "$BACKUP_MAIN" ]]; then
-    echo "✗ 无可用备份(${BACKUP_DIR}/${TAG}.* 目录)。损坏主库留于 $CORRUPT,需手动处理。" >&2
-    sqlite_log "❌ restore 失败:无可用备份,损坏主库留于 $CORRUPT"
-    exit 1
-  fi
-  echo "▶ 回退备份 $BACKUP_MAIN → $DB"
-  rm -f "$DB" && cp -a "$BACKUP_MAIN" "$DB"
-  for ext in -wal -shm; do
-    src="${BACKUP_ROOT}/${BASENAME}${ext}"
-    # if/then 而非 [[ -f ]] && { ... },旁文件不存在时整句返回 1 会触发 set -e 退出
-    if [[ -f "$src" ]]; then
-      rm -f "${DB}${ext}" && cp -a "$src" "${DB}${ext}"
-    fi
-  done
-  echo "✓ 已从备份还原: $DB"
-fi
-
-# 4) .recover 成功路径清残留 -wal/-shm;备份还原路径旁文件已就位不动
-if [[ "$RESTORED" -eq 1 ]]; then
-  rm -f "${DB}-wal" "${DB}-shm"
-  echo "✓ 清理 .recover 残留 -wal/-shm"
-fi
-
-sqlite_log "✅ restore 完成:$DB(recover=${RESTORED},现场=$CORRUPT)"
-echo
-echo "✓ 主库已就绪: $DB"
-echo "  损坏现场保留: $CORRUPT(事后可再 .recover 或取证后删除)"
-echo "  请重启进程使新库生效:"
-echo "    pm2:     pm2 restart fullstack-template-backend"
-echo "    systemd: systemctl restart fullstack-template-backend"
-echo "    docker:  docker restart fullstack-template-backend"