create-ssnode-cli 0.2.5 → 0.2.7

package/templates/backend/scripts/pulldocker.cjs

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+/**
+ * backend 拉取(mirror 反向)—— 从服务器拉回 docker 镜像 + 部署配置,合并压缩下载到本地。
+ *
+ * 用途:迁移备份。发布是「本地 → 服务器」(publish.cjs 薄上传),本脚本是反向的
+ * 「服务器 → 本地」:把服务器上现场构建的镜像(docker save)与 APP_ROOT 部署配置
+ * 打成一个归档,scp 下载到本地 release/。迁移新机时:docker load 镜像 tar +
+ * 解包 app/ 即可起服务(compose 文件注释里的「迁移机 docker load 同 tag 镜像」伏笔)。
+ *
+ * 目标选择:--env <名> 选 server.config.cjs targets[名];未传且配了 targets 交互列选;
+ * 都没有则顶层单服务器形态(与 publish/rollback 同语义,统一走 lib/ssh.cjs pickTarget)。
+ * 镜像列表:current/package.json 的 name 派生镜像名(与 ops config.sh pkg_name 同口径:
+ * 剥 @scope 取 basename),docker images 按前缀过滤出全部历史 tag(即回滚窗口),单选一个
+ * (默认 current 的 version,--tag 可跳过交互)。
+ * 配置包:APP_ROOT 根部小文件(.mode/.prod.secrets[加密部署才有]/.prod.docker.env + 顶层 install/start/stop/
+ * status/versionswitch 脚本)+ APP_ROOT/config/(部署位配置:config.base.yaml + config.yaml
+ * 环境真值 —— 必须随迁,业务配置的单一真相源)+ APP_ROOT/ops/(mode 派发脚本,部署态权威含
+ * 运维护过的 config.sh)+ current/ 解引用内容(纯业务包:compose/Dockerfile/config);
+ * data/(sqlite+uploads)默认不带,交互询问,--data/--no-data 覆盖;logs/、releases/ 恒不带。
+ *
+ * 归档结构(下载到 release/pull-<name>-<时间戳>.tar.gz):
+ *   images/<repo>_<tag>.tar.gz   # 迁移机 docker load 用
+ *   app/                          # current 解引用(纯业务包:dist/package.json/Dockerfile/compose/config)
+ *   ops/                          # APP_ROOT/ops/(mode 派发:docker/pm2/systemd + run-container.sh)
+ *   root/                         # APP_ROOT 根部部署态文件(.mode/.prod.secrets[加密部署才有]/.prod.docker.env + 顶层 5 脚本)
+ *   root/config/                  # 部署位配置(config.base.yaml + config.yaml 环境真值)
+ *   data/                         # 可选(交互/--data 决定)
+ *
+ * 用法: pnpm pulldocker [--env <名>] [--tag <tag>] [--data|--no-data]
+ */
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+const { log, fatal, shq, connect, sshExec, pickTarget } = require('./lib/ssh.cjs');
+
+const BACKEND = path.resolve(__dirname, '..');
+const cfg = require('./server.config.cjs');
+
+// ── 本地交互(readline;非 TTY 下 ask 走默认值/警告,不挂起) ──
+function ask(question, { def = '' } = {}) {
+  return new Promise((resolve) => {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+      if (def !== '') log.warn(`非交互环境,${question.trim()} → 默认 ${def}`);
+      resolve(def);
+      return;
+    }
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    // 空输入(直接回车)回落 def:否则回车得 '' → Number('')=0 → 无效序号死循环
+    rl.question(question, (ans) => { rl.close(); resolve(ans.trim() || def); });
+  });
+}
+
+async function confirm(question, def = false) {
+  const hint = def ? '[Y/n]' : '[y/N]';
+  const ans = await ask(`${question} ${hint} `, { def: def ? 'y' : 'n' });
+  return /^(y|yes)/i.test(ans);
+}
+
+// 编号单选:items = [{ label, mark }](mark 为附加标记如「← current」)
+async function pickOne(title, items, { defIndex = 0 } = {}) {
+  console.log(`\n${title}`);
+  items.forEach((it, i) => console.log(`  ${C.gray}${String(i + 1).padStart(2)}.${C.reset} ${it.label}${it.mark ? ` ${C.cyan}${it.mark}${C.reset}` : ''}`));
+  const def = defIndex + 1;
+  while (true) {
+    const ans = await ask(`选择序号 [1-${items.length},回车=${def}]: `, { def: String(def) });
+    const n = Number(ans);
+    if (Number.isInteger(n) && n >= 1 && n <= items.length) return items[n - 1];
+    log.warn(`无效序号: ${ans}(1-${items.length} 或回车)`);
+  }
+}
+
+// ── 命令行参数 ──
+const C = { reset: '\x1b[0m', cyan: '\x1b[36m', gray: '\x1b[90m' };
+function takeFlag(name) {
+  const i = process.argv.indexOf(name);
+  return i === -1 ? null : process.argv.splice(i, 2)[1] ?? true;
+}
+const tagArg = takeFlag('--tag');
+if (tagArg !== null && typeof tagArg !== 'string') fatal('--tag 缺少值: --tag <tag>(镜像 tag,即 version)');
+const dataArg = takeFlag('--data') ? true : takeFlag('--no-data') ? false : null;
+
+// ── 目标选择:--env > targets 交互列选 > 顶层单服务器(共享 lib/ssh.cjs pickTarget,pickOne 留作镜像单选) ──
+
+// ── main ──
+async function main() {
+  const { target } = await pickTarget(cfg);
+  const appRoot = target.backendServiceDir;
+
+  const ssh = await connect(target);
+  let tmpDir = '';
+  let remoteTar = '';
+  try {
+    // 部署完整性:current 必须在位(name/version 都从服务器侧读,部署态权威,不信任本地包)
+    const installed = await sshExec(ssh, `test -f ${shq(`${appRoot}/current/package.json`)} && echo yes || echo no`);
+    if (installed !== 'yes') fatal(`远端 ${appRoot}/current/package.json 不存在(尚未部署,无可拉取)`);
+
+    const mode = await sshExec(ssh, `cat ${shq(`${appRoot}/.mode`)} 2>/dev/null || echo unknown`).catch(() => 'unknown');
+    if (mode !== 'docker') log.warn(`远端 .mode=${mode}(非 docker 模式):镜像拉取仅对 docker 部署有意义,配置包照拉`);
+
+    // 镜像名派生:pkg_name 同口径(剥 @scope 取 basename),服务端 current/package.json 权威
+    const pjRaw = await sshExec(ssh, `cat ${shq(`${appRoot}/current/package.json`)}`);
+    let pkgName = '', curVersion = '';
+    try {
+      const pj = JSON.parse(pjRaw);
+      pkgName = String(pj.name || '').split('/').pop();
+      curVersion = String(pj.version || '');
+    } catch (e) { fatal(`current/package.json 解析失败: ${e.message}`); }
+    if (!pkgName) fatal('current/package.json 缺 name');
+    log.ok(`镜像名(包名派生): ${pkgName}(current @ v${curVersion})`);
+
+    // 列出该服务全部镜像 tag(回滚窗口全部版本;<none> 悬空层跳过、ERE 元字符转义防误配)
+    const imgRe = pkgName.replace(/[.[\]*\\(){}?+|^$]/g, '\\$&');
+    const imgRaw = await sshExec(ssh,
+      `docker images --format '{{.Repository}}:{{.Tag}}\t{{.Size}}\t{{.CreatedSince}}' | grep -E '^${imgRe}([:/]|$)' | grep -v '<none>' || true`);
+    const images = imgRaw ? imgRaw.split('\n').filter(Boolean).map((l) => {
+      const [ref, size, since] = l.split('\t');
+      return { ref, size, since };
+    }) : [];
+    if (images.length === 0) fatal(`服务器无 ${pkgName} 前缀镜像(非 docker 部署或已清理)`);
+    log.info(`服务器现有镜像 tag:`);
+    images.forEach((im) => console.log(`  ${C.gray}-${C.reset} ${im.ref}  ${C.gray}(${im.size}, ${im.since})${C.reset}`));
+
+    // 单选一个(--tag 直选;默认 current 的 version)
+    let image = null;
+    if (tagArg) {
+      image = images.find((im) => im.ref === `${pkgName}:${tagArg}` || im.ref.endsWith(`:${tagArg}`));
+      if (!image) fatal(`--tag ${tagArg} 未命中镜像列表(可用: ${images.map((i) => i.ref).join(', ')})`);
+      log.ok(`--tag 直选: ${image.ref}`);
+    } else {
+      const defIndex = Math.max(0, images.findIndex((im) => im.ref === `${pkgName}:${curVersion}`));
+      const picked = await pickOne('拉取哪个镜像?(默认 current 版本)', images.map((im) => ({
+        label: `${im.ref}  ${C.gray}(${im.size}, ${im.since})${C.reset}`,
+        value: im,
+        mark: im.ref === `${pkgName}:${curVersion}` ? '← current' : '',
+      })), { defIndex });
+      image = picked.value;
+    }
+
+    // data/(sqlite+uploads)是否随包:--data/--no-data > 交互(默认不带)
+    const hasData = await sshExec(ssh, `test -d ${shq(`${appRoot}/data`)} && echo yes || echo no`);
+    let withData = false;
+    if (dataArg !== null) withData = dataArg;
+    else if (hasData === 'yes') withData = await confirm(`是否包含 data/(sqlite+uploads,可能很大)?`, false);
+    if (withData && hasData !== 'yes') { log.warn('data/ 不存在,跳过'); withData = false; }
+    log.ok(`镜像 ${image.ref} + 配置包${withData ? ' + data/' : ''}`);
+
+    // ── 远端组装归档(临时目录放 APP_ROOT 下:与部署同盘,避免 /tmp tmpfs 空间坑) ──
+    const ts = new Date().toISOString().replace(/[-:T]/g, '').slice(0, 14);
+    tmpDir = `${appRoot}/.pulldocker-tmp-${ts}-${process.pid}`;
+    remoteTar = `${appRoot}/pull-${pkgName}-${ts}.tar.gz`;
+    const imgFile = `images/${image.ref.replace(/[:/]/g, '_')}.tar.gz`;
+    const realCurrent = await sshExec(ssh, `readlink -f ${shq(`${appRoot}/current`)}`);
+
+    log.info('组装远端归档 ...');
+    await sshExec(ssh, `mkdir -p ${shq(`${tmpDir}/images`)} ${shq(`${tmpDir}/app`)} ${shq(`${tmpDir}/root`)}`);
+
+    // 1) docker save 镜像(gzip 单层压缩;这层是归档里的大头)
+    log.step(`docker save ${image.ref} ...(镜像大时耗时,耐心等待)`);
+    await sshExec(ssh, `docker save ${shq(image.ref)} | gzip > ${shq(`${tmpDir}/${imgFile}`)}`);
+
+    // 2) 配置包:current 解引用内容(纯业务包:compose/Dockerfile/config;顶层脚本与 ops/ 不在
+    //    current,分别由 3)/3b) 从 APP_ROOT 根与 APP_ROOT/ops/ 捕获)
+    await sshExec(ssh, `cp -a ${shq(`${realCurrent}/.`)} ${shq(`${tmpDir}/app/`)}`);
+    // 3) APP_ROOT 根部部署态文件(缺哪个跳哪个:systemd/pm2 模式没有 .prod.docker.env);
+    //    部署位 config/(config.base.yaml + config.yaml 环境真值)一整目录随迁 —— 业务配置
+    //    单一真相源,丢了它迁移机起不来(凭据/端口全在内)
+    for (const f of ['.mode', '.prod.secrets', '.prod.docker.env']) {
+      await sshExec(ssh, `if [ -f ${shq(`${appRoot}/${f}`)} ]; then cp -a ${shq(`${appRoot}/${f}`)} ${shq(`${tmpDir}/root/`)}; fi`);
+    }
+    await sshExec(ssh, `if [ -d ${shq(`${appRoot}/config`)} ]; then mkdir -p ${shq(`${tmpDir}/root/config`)} && cp -a ${shq(`${appRoot}/config/.`)} ${shq(`${tmpDir}/root/config/`)}; fi`);
+    // 3b) 顶层脚本(install.sh 首次部署拷到 APP_ROOT 根,start.sh 起容器全靠它)+ ops/(mode
+    //     派发脚本,部署态权威:含运维护过的 config.sh;current 是纯业务包,这两处都不在)
+    const topScripts = ['install.sh', 'start.sh', 'stop.sh', 'versionswitch.sh', 'status.sh'];
+    for (const f of topScripts) {
+      await sshExec(ssh, `if [ -f ${shq(`${appRoot}/${f}`)} ]; then cp -a ${shq(`${appRoot}/${f}`)} ${shq(`${tmpDir}/root/`)}; fi`);
+    }
+    await sshExec(ssh, `if [ -d ${shq(`${appRoot}/ops`)} ]; then cp -a ${shq(`${appRoot}/ops`)} ${shq(`${tmpDir}/ops`)}; fi`);
+    // 4) data/ 可选(数据库 + 上传,跨版本共享盘)
+    if (withData) {
+      log.info('拷贝 data/(数据库+上传,可能耗时)...');
+      await sshExec(ssh, `cp -a ${shq(`${appRoot}/data`)} ${shq(`${tmpDir}/data`)}`);
+    }
+
+    // 5) 合并压缩(外层 tar.gz:app/root 可压,text 层小;images/*.tar.gz 已压过,gzip 存近似零增益)
+    const sizeRaw = await sshExec(ssh, `du -sh ${shq(tmpDir)} | cut -f1`);
+    log.info(`归档体积约 ${sizeRaw},tar 打包 ...`);
+    await sshExec(ssh, `tar -C ${shq(tmpDir)} -czf ${shq(remoteTar)} .`);
+
+    // ── 下载(scp) ──
+    fs.mkdirSync(path.join(BACKEND, 'release'), { recursive: true });
+    const localTar = path.join(BACKEND, 'release', path.basename(remoteTar));
+    log.info(`下载 → ${path.relative(BACKEND, localTar)} ...`);
+    await ssh.getFile(localTar, remoteTar);
+    log.ok(`已下载: ${path.relative(BACKEND, localTar)}`);
+
+    console.log(`\n归档结构: images/(${image.ref}) + app/(current 纯业务包) + ops/(mode 派发) + root/(.mode/.prod.secrets/.prod.docker.env + 顶层 5 脚本 + config/ 部署位配置)${withData ? ' + data/' : ''}`);
+    log.info('迁移新机: pushdocker 一键推(镜像 load + current/ops/根部落位 + 起容器);手动则 tar 解包 → docker load → app/→current、ops/→ops、root/*→APP_ROOT 根 → bash start.sh');
+  } finally {
+    // 远端清理:临时目录 + 归档均不留(best-effort,不阻塞退出)
+    if (ssh) {
+      if (tmpDir) await sshExec(ssh, `rm -rf ${shq(tmpDir)}`).catch(() => {});
+      if (remoteTar) await sshExec(ssh, `rm -f ${shq(remoteTar)}`).catch(() => {});
+      ssh.dispose();
+    }
+  }
+}
+
+main().catch((e) => fatal(e.message));

package/templates/backend/scripts/pushdocker.cjs

@@ -0,0 +1,323 @@
+#!/usr/bin/env node
+/**
+ * backend 推送(pulldocker 对偶)—— 把拉取归档(镜像+配置)推到目标服务器,docker load 后起容器。
+ *
+ * 用途:迁移。pulldocker 把镜像(docker save)+ 部署配置拉到本地归档;本脚本做反向:上传归档 →
+ * 远端 docker load 镜像 → 按 install.sh 的 docker 部署力学落位(current=真实目录 + 顶层脚本 +
+ * ops/(mode 派发)+ 根部 .prod.secrets[加密部署才有]/.prod.docker.env + 部署位 config/(config.base.yaml +
+ * config.yaml 环境真值,业务配置单一真相源))→ 跑 APP_ROOT/start.sh 起容器
+ * (run-container.sh 停删旧容器重建,env/secrets/配置挂载力学复用单一真相源,本脚本零 docker run 参数)。
+ *
+ * 目标机两种状态:
+ *   裸机(无 .mode):引导落位 —— 建 releases/data/logs 骨架,直接铺内容
+ *   已部署(.mode 存在,须为 docker 模式):交互确认后覆盖 —— 旧 root 密钥文件/env 先备份
+ *     为 .bak.<ts>,包内 data/ 与远端 data/ 同在时再确认一次,然后按 install.sh 原语落位
+ *
+ * 端口确认(落位前做,取消零损伤):生效 PORT 的 env 源 = 包内 root/.prod.docker.env(包内赢)
+ *   > 目标机根部 env > 回退 3001(与 ops/docker/config.sh::read_env_port 同口径)。被非本应用
+ *   旧容器占用时交互三选一(换端口 sed 改写该 env 源 / 强推沿用 / 取消);--port <n> 非交互
+ *   直选,占用即拦(CI 逃生口)。
+ *
+ * 输入内容(--from <绝对路径>,未传交互输入;归档/目录两种形态):
+ *   pull-<name>-<ts>.tar.gz   # pulldocker 产出,直接上传远端解
+ *   已解包目录                 # 本地打 tar 再上传(目录里 images/ + app/ [+ ops/][+ root/][+ data/])
+ * 本地校验:images/ 必须非空(docker save 产物)、app/ 必须在(release 内容);
+ *   缺 root/:裸机直接拦(没有 .prod.docker.env 起不动),已部署机告警沿用目标机根文件;
+ *   缺 ops/(mode 派发脚本,起容器必需):裸机直接拦,已部署机告警沿用目标机 ops/。
+ *
+ * 用法: pnpm pushdocker [--env <名>] [--from <绝对路径>] [--port <1-65535>]
+ */
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+const { spawn } = require('child_process');
+const { log, fatal, shq, connect, sshExec, pickTarget } = require('./lib/ssh.cjs');
+
+const cfg = require('./server.config.cjs');
+
+// ── 本地交互(readline;非 TTY 下 ask 走默认值/警告,不挂起) ──
+function ask(question, { def = '' } = {}) {
+  return new Promise((resolve) => {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+      if (def === '') { console.error(`✗ 非交互环境无法回答: ${question.trim()}`); process.exit(1); }
+      log.warn(`非交互环境,${question.trim()} → 默认 ${def}`);
+      resolve(def);
+      return;
+    }
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    // 空输入(直接回车)回落 def:否则回车得 '' → Number('')=0 → 无效序号死循环
+    rl.question(question, (ans) => { rl.close(); resolve(ans.trim() || def); });
+  });
+}
+
+async function confirm(question, def = false) {
+  const hint = def ? '[Y/n]' : '[y/N]';
+  const ans = await ask(`${question} ${hint} `, { def: def ? 'y' : 'n' });
+  return /^(y|yes)/i.test(ans);
+}
+
+const isTTY = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+const isValidPort = (v) => /^\d{1,5}$/.test(v) && +v >= 1 && +v <= 65535;
+
+// ── 端口确认 ──
+// 读 env 文件 PORT(剥引号/空白,与 ops/docker/config.sh::read_env_port 同口径)
+async function readEnvPort(ssh, envFile) {
+  return sshExec(ssh,
+    `sed -nE 's/^PORT=//p' ${shq(envFile)} | head -1 ` +
+    `| sed -E "s/^['\\\"]?//; s/['\\\"]?$//; s/^[[:space:]]+//; s/[[:space:]]+$//"`);
+}
+
+// 远端占用探测 → { free, who[] }。本应用旧容器发布的宿主端口不算占用:run-container.sh 起
+// 容器前会停删同名旧容器,该端口马上腾出。监听判定:$4 末段按 ':' 切与端口比对(IPv4/IPv6
+// 通吃),ss 缺席回退 netstat。who 尽力给出占用者(docker 可见的容器;非容器进程仅见监听行,
+// -p 看进程需 root,不强求)。
+async function remotePortStat(ssh, port, ctName) {
+  const script = [
+    'p=$1; ct=$2',
+    'own=$(docker ps -a --filter "name=^/${ct}$" --format "{{.Ports}}" 2>/dev/null | tr "," "\\n" | grep -oE ":[0-9]+->" | tr -d ":>-" | tr "\\n" " ")',
+    'case " $own " in *" $p "*) echo FREE; exit 0;; esac',
+    'if (ss -ltn 2>/dev/null || netstat -ltn 2>/dev/null) | awk -v P="$p" \'{n=split($4,a,":"); if (a[n]==P) f=1} END{exit f?0:1}\'; then',
+    '  echo BUSY',
+    '  docker ps --format "{{.Names}}  {{.Ports}}" 2>/dev/null | grep ":${p}->" | sed "s/^/    /" || true',
+    '  (ss -ltnp 2>/dev/null || netstat -ltnp 2>/dev/null) | grep -E "[:.]${p}[[:space:]]" | grep -oE "users:\\(\\(.+\\)\\)" | head -3 | sed "s/^/    /" || true',
+    '  exit 0',
+    'fi',
+    'echo FREE',
+  ].join('\n');
+  const out = await sshExec(ssh, `bash -c ${shq(script)} probe ${shq(port)} ${shq(ctName)}`);
+  const [head, ...who] = out.split('\n');
+  if (head !== 'FREE' && head !== 'BUSY') throw new Error(`远端端口探测输出异常: ${out}`);
+  return { free: head === 'FREE', who: who.filter(Boolean).map((l) => l.trim()) };
+}
+
+// ── 命令行参数 ──
+const tagArgIdx = process.argv.indexOf('--from');
+const fromArg = tagArgIdx === -1 ? null : (() => {
+  const v = process.argv[tagArgIdx + 1];
+  if (!v || v.startsWith('--')) fatal('--from 缺少值: --from <绝对路径>(pull-*.tar.gz 或解包目录)');
+  process.argv.splice(tagArgIdx, 2);
+  return v;
+})();
+
+// --port <1-65535>:非交互端口直选(CI 逃生口;跳过询问,占用即拦)
+const portArgIdx = process.argv.indexOf('--port');
+const portArg = portArgIdx === -1 ? null : (() => {
+  const v = process.argv[portArgIdx + 1];
+  if (!v || v.startsWith('--')) fatal('--port 缺少值: --port <1-65535>');
+  if (!/^\d{1,5}$/.test(v) || +v < 1 || +v > 65535) fatal(`--port 非法: ${v}(须 1-65535)`);
+  process.argv.splice(portArgIdx, 2);
+  return String(+v);
+})();
+
+// ── 目标选择:--env > targets 交互列选 > 顶层单服务器(共享 lib/ssh.cjs pickTarget) ──
+
+// ── 输入内容定位与校验(归档或目录 → 统一为本地 tar 路径 + 结构信息) ──
+// 返回 { tarPath, localDir(目录形态时的临时 tar 需清理), hasRoot, hasData }。归档不解包校验,
+// 结构由远端解包后自检(远端为权威,本地解一遍只为省一次上传失败往返,不值得)。
+function resolvePayload(from) {
+  const abs = path.resolve(from);
+  if (!fs.existsSync(abs)) fatal(`路径不存在: ${abs}`);
+  if (fs.statSync(abs).isFile()) {
+    if (!/\.tar\.gz$/.test(abs)) fatal(`归档形态仅支持 pull-*.tar.gz(得到: ${path.basename(abs)})`);
+    return { tarPath: abs, localDir: '', hasRoot: true }; // 结构远端解包后判
+  }
+  // 目录形态:校验后本地打 tar(macOS 双治理同 publish: COPYFILE_DISABLE + --no-xattrs)
+  for (const d of ['images', 'app']) {
+    if (!fs.existsSync(path.join(abs, d))) fatal(`目录缺 ${d}/(结构 = images/ + app/ [+ ops/][+ root/][+ data/]): ${abs}`);
+  }
+  const imgs = fs.readdirSync(path.join(abs, 'images')).filter((f) => f.endsWith('.tar.gz'));
+  if (imgs.length === 0) fatal(`images/ 无 *.tar.gz(docker save 产物缺失): ${abs}/images`);
+  const ts = new Date().toISOString().replace(/[-:T]/g, '').slice(0, 14);
+  const tmpTar = path.join(abs, `../pushdocker-${path.basename(abs)}-${ts}.tar.gz`);
+  return { tarPath: tmpTar, localDir: abs, hasRoot: fs.existsSync(path.join(abs, 'root')) };
+}
+
+// 本地 tar 打包(目录 → 归档;同步 spawn,与 publish makeTar 同款双治理)
+function makeTar(dir, tarPath) {
+  return new Promise((resolve, reject) => {
+    const p = spawn('tar', ['--no-xattrs', '-czf', tarPath, '-C', dir, '.'], {
+      stdio: 'inherit', env: { ...process.env, COPYFILE_DISABLE: '1' },
+    });
+    p.on('error', reject);
+    p.on('close', (c) => (c === 0 ? resolve(tarPath) : reject(new Error(`tar exit ${c}`))));
+  });
+}
+
+async function main() {
+  // 0) 目标机 + 输入内容
+  const { target } = await pickTarget(cfg);
+  const appRoot = target.backendServiceDir;
+  const from = fromArg || await ask('输入上传内容绝对路径(pull-*.tar.gz 或解包目录): ');
+  const { tarPath, localDir, hasRoot } = resolvePayload(from);
+  if (localDir) {
+    log.info(`目录形态:本地打 tar(${path.basename(tarPath)})...`);
+    await makeTar(localDir, tarPath);
+  }
+  log.ok(`内容: ${tarPath}`);
+  if (!hasRoot) log.warn('包内无 root/(.mode/.prod.secrets[加密部署才有]/.prod.docker.env/config/):裸机部署会被拦,已部署机沿用目标机根文件');
+
+  const ssh = await connect(target);
+  const ts = new Date().toISOString().replace(/[-:T]/g, '').slice(0, 14);
+  const staging = `${appRoot}/.pushdocker-tmp-${ts}-${process.pid}`;
+  try {
+    // 1) 前置检查:docker 必在
+    const hasDocker = await sshExec(ssh, `command -v docker >/dev/null 2>&1 && echo yes || echo no`);
+    if (hasDocker !== 'yes') throw new Error('远端无 docker 命令:先安装 docker(pull 只迁了镜像和配置,runtime 不带)');
+
+    // 2) 目标机状态:裸机 / 已部署(须 docker 模式)
+    const mode = await sshExec(ssh, `cat ${shq(`${appRoot}/.mode`)} 2>/dev/null || echo none`).catch(() => 'none');
+    const deployed = mode !== 'none';
+    if (deployed) {
+      if (mode !== 'docker') throw new Error(`目标机 .mode=${mode}(非 docker):本脚本只推 docker 部署(mode 不同手动处理)`);
+      log.warn('目标机已部署(.mode=docker):覆盖将 rm 旧 current/、用包内文件盖根部 env/密钥');
+      const go = await confirm('确认继续推送到已部署的目标机吗?', false);
+      if (!go) throw new Error('已取消(目标机未做任何改动)');
+    }
+
+    // 3) 上传 + 解包(scp → APP_ROOT 下临时目录)
+    const remoteTar = `${staging}.tar.gz`;
+    await sshExec(ssh, `mkdir -p ${shq(appRoot)}`);
+    log.info(`上传 ${path.basename(tarPath)} → ${appRoot} ...`);
+    await ssh.putFile(tarPath, remoteTar);
+    await sshExec(ssh, `mkdir -p ${shq(staging)} && tar -xzf ${shq(remoteTar)} -C ${shq(staging)}`);
+
+    // 3.1) 远端结构自检(归档形态不解包看不到内容,校验收敛在此;与目录形态本地校验同口径)
+    // throw 而非 fatal:fatal 走 process.exit(1) 同步终止会跳过 finally,远端 staging 会残留。
+    const rHasApp = await sshExec(ssh, `test -f ${shq(`${staging}/app/package.json`)} && echo yes || echo no`);
+    if (rHasApp !== 'yes') throw new Error('包内 app/package.json 不存在(app/ 缺失或结构不对;只收 pulldocker 归档)');
+    const nImgs = Number(await sshExec(ssh,
+      `ls -1 ${shq(`${staging}/images`)}/*.tar.gz 2>/dev/null | wc -l | tr -d ' '`));
+    if (!Number.isInteger(nImgs) || nImgs < 1) throw new Error('包内 images/ 无 *.tar.gz(docker save 产物缺失)');
+    const rHasRoot = await sshExec(ssh, `test -d ${shq(`${staging}/root`)} && echo yes || echo no`);
+    const rHasOps = await sshExec(ssh, `test -d ${shq(`${staging}/ops`)} && echo yes || echo no`);
+    const rHasData = await sshExec(ssh, `test -d ${shq(`${staging}/data`)} && echo yes || echo no`);
+    if (rHasRoot !== 'yes' && !deployed) throw new Error('裸机部署但包内无 root/(缺 .prod.docker.env,起不动容器);重新 pulldocker 带齐');
+    if (rHasOps !== 'yes' && !deployed) throw new Error('裸机部署但包内无 ops/(缺 mode 派发脚本,起不动容器);重新 pulldocker 带齐');
+
+    // 3.2) 端口确认(此时未落位,取消零损伤):生效 PORT 的 env 源 = 包内 root/.prod.docker.env
+    //   (包内赢,落位时盖过去)> 目标机根部 env > 回退 3001(与 config.sh::read_env_port 同口径)。
+    //   换端口只 sed 该 env 源的 PORT 行,不另开旁路 —— 落位后 run-container.sh 自然读到新值。
+    const stagingEnv = `${staging}/root/.prod.docker.env`;
+    const rootEnv = `${appRoot}/.prod.docker.env`;
+    const hasStagingEnv = (await sshExec(ssh, `test -f ${shq(stagingEnv)} && echo yes || echo no`)) === 'yes';
+    const hasRootEnv = deployed && (await sshExec(ssh, `test -f ${shq(rootEnv)} && echo yes || echo no`)) === 'yes';
+    const envFile = hasStagingEnv ? stagingEnv : (hasRootEnv ? rootEnv : '');
+    // 容器名按 pkg_name 口径派生(剥 @scope 取 basename;与步骤 7 同款,current 即 app 拷贝)
+    const ctName = await sshExec(ssh,
+      `grep -m1 '"name"' ${shq(`${staging}/app/package.json`)} ` +
+      `| sed -E 's/.*"name"[[:space:]]*:[[:space:]]*"([^"]+)".*/\\1/' | sed -E 's|.*/||'`);
+    const port0 = envFile ? await readEnvPort(ssh, envFile) : '';
+    let port = port0 || '3001';
+    if (!port0) log.warn(`PORT 未定义(根部与包内 env 均无)→ 按回退端口 ${port} 探测(与 config.sh 口径一致)`);
+    let portChanged = portArg != null && portArg !== port;
+    if (portArg) port = portArg;
+    while (true) {
+      const st = await remotePortStat(ssh, port, ctName);
+      if (st.free) break;
+      const whoTxt = st.who.length ? `:${st.who.join('; ')}` : '(占用者不可见,多为非容器进程)';
+      if (portArg) throw new Error(`--port ${port} 已被占用${whoTxt}(非交互不询问;换 --port 或停掉占用者后重试)`);
+      if (!isTTY) throw new Error(`端口 ${port} 已被占用${whoTxt}(非交互环境无法询问;重跑加 --port <可用端口>)`);
+      log.warn(`端口 ${port} 已被占用${st.who.length ? ':' : ''}`);
+      st.who.forEach((l) => console.log(`    ${l}`));
+      const sel = await ask(`请选择: [1] 输入新端口  [2] 仍用 ${port} 继续  [3] 取消 `);
+      if (sel === '2') { log.warn(`沿用占用端口 ${port}(若占用者不释放,docker run 会因端口绑定失败)`); break; }
+      if (sel === '3') throw new Error(`已取消(端口 ${port} 被占,目标机未做任何改动)`);
+      if (sel !== '1') { log.warn(`无效选择: ${sel || '(空)'}(1/2/3)`); continue; }
+      const np = await ask(`新端口(1-65535): `);
+      if (!isValidPort(np)) { log.warn(`端口非法: ${np || '(空)'}(须 1-65535)`); continue; }
+      port = np; portChanged = true; // 先探测确认可用,再落盘(循环回来 free 才写 env)
+    }
+    if (portChanged && envFile) {
+      await sshExec(ssh, `sed -i -E "s/^PORT=.*/PORT=${port}/" ${shq(envFile)}`);
+      log.ok(`端口 ${port0 || '(未定义)'} → ${port},已写入 ${envFile === stagingEnv ? '包内 root' : '目标机根部'}/.prod.docker.env`);
+    } else if (portChanged) {
+      log.warn(`--port ${port} 但根部与包内均无 .prod.docker.env 可写;落位后请手动确认 env 的 PORT`);
+    } else if (!portArg) {
+      log.info(`端口 ${port} 可用`);
+    }
+
+    // 4) docker load(原生支持 gzip 包;逐个 load 齐活,保留回滚窗口内的全部历史 tag)
+    log.info(`docker load ${nImgs} 个镜像 tar ...`);
+    const loadOut = await sshExec(ssh,
+      `for f in ${shq(`${staging}/images`)}/*.tar.gz; do echo "== $f"; docker load -i "$f" || exit 1; done`);
+    console.log(loadOut.split('\n').map((l) => `  ${l}`).join('\n'));
+
+    // 5) 落位(对齐 install.sh docker 部署原语)
+    await sshExec(ssh, `mkdir -p ${shq(`${appRoot}/releases`)} ${shq(`${appRoot}/data`)} ${shq(`${appRoot}/logs`)}`);
+    // current:docker=真实目录,整体重建(与 install.sh lay_out_release 同款;data 在宿主 data/,不动)
+    log.info('落位 current/(app → current 整体重建)...');
+    await sshExec(ssh, `rm -rf ${shq(`${appRoot}/current`)} && mkdir -p ${shq(`${appRoot}/current`)} && cp -a ${shq(`${staging}/app/.`)} ${shq(`${appRoot}/current/`)}`);
+    // 顶层脚本 + root 文件:统一走 root/(pulldocker 从 APP_ROOT 根捕获;current 是纯业务包,
+    // 顶层脚本不在其中)。已部署机先备份再覆盖;仅拷包内实际有的。
+    if (rHasRoot === 'yes') {
+      const rootFiles = '.mode .prod.secrets .prod.docker.env install.sh start.sh stop.sh versionswitch.sh status.sh';
+      log.info(deployed ? '根部文件备份并覆盖(.bak.<ts>)...' : '根部文件落位(.mode/.prod.secrets/.prod.docker.env + 顶层脚本)...');
+      const backupCmd = deployed
+        ? `for f in ${rootFiles}; do [ -f ${shq(appRoot)}/$f ] && cp -a ${shq(appRoot)}/$f ${shq(appRoot)}/$f.bak.${ts}; done; true`
+        : '';
+      await sshExec(ssh,
+        `${backupCmd} for f in ${rootFiles}; do [ -f ${shq(`${staging}/root`)}/$f ] && cp -a ${shq(`${staging}/root`)}/$f ${shq(appRoot)}/$f; done; true`);
+      await sshExec(ssh, `if [ -f ${shq(`${appRoot}/.prod.secrets`)} ]; then chmod 600 ${shq(`${appRoot}/.prod.secrets`)}; fi`);
+      // 部署位 config/(config.base.yaml + config.yaml 环境真值):业务配置单一真相源,必随迁。
+      // 已部署机:旧 config 备份为 config.bak.<ts>(运维护过的环境真值,不静默丢)再覆盖。
+      const rHasRootCfg = (await sshExec(ssh, `test -d ${shq(`${staging}/root/config`)} && echo yes || echo no`)) === 'yes';
+      if (rHasRootCfg) {
+        log.info(deployed ? '部署位 config/ 备份并覆盖(config.bak.<ts>)...' : '部署位 config/ 落位(config.base.yaml + config.yaml)...');
+        const backupCfg = deployed
+          ? `rm -rf ${shq(`${appRoot}/config.bak.${ts}`)} && [ -d ${shq(`${appRoot}/config`)} ] && mv ${shq(`${appRoot}/config`)} ${shq(`${appRoot}/config.bak.${ts}`)}; true`
+          : '';
+        await sshExec(ssh, `${backupCfg} mkdir -p ${shq(`${appRoot}/config`)} && cp -a ${shq(`${staging}/root/config/.`)} ${shq(`${appRoot}/config/`)}`);
+      } else if (!deployed) {
+        log.warn('包内无 root/config/(部署位配置缺失):容器将用镜像内兜底 config;建议重新 pulldocker 带齐');
+      }
+    }
+    // ops/(mode 派发:start.sh → ops/docker/start.sh → run-container.sh):已部署机先备份再
+    // 整体覆盖,已部署且包内无则跳过(沿用目标机,告警)
+    if (rHasOps === 'yes') {
+      log.info(deployed ? 'ops/ 备份并整体覆盖(ops.bak.<ts>)...' : 'ops/ 落位(mode 派发脚本)...');
+      await sshExec(ssh, `rm -rf ${shq(`${appRoot}/ops.bak.${ts}`)} && [ -d ${shq(`${appRoot}/ops`)} ] && mv ${shq(`${appRoot}/ops`)} ${shq(`${appRoot}/ops.bak.${ts}`)}; true`);
+      await sshExec(ssh, `cp -a ${shq(`${staging}/ops`)} ${shq(`${appRoot}/ops`)}`);
+    } else if (deployed) {
+      log.warn('包内无 ops/:沿用目标机 ops/(旧格式归档;建议重新 pulldocker 带齐)');
+    }
+    // data/:包内有 → 裸机直接合入(空骨架);已部署机与远端 data 非空共存时需确认覆盖
+    if (rHasData === 'yes') {
+      const remoteDataN = Number(await sshExec(ssh, `ls -A ${shq(`${appRoot}/data`)} 2>/dev/null | wc -l | tr -d ' '`));
+      if (deployed && remoteDataN > 0) {
+        log.warn('目标机 data/ 非空且包内带 data/:覆盖会改变运行数据库');
+        const goData = await confirm(`备份目标机 data/ 为 data.bak.${ts} 后用包内数据覆盖?`, false);
+        if (!goData) log.warn('已跳过 data/(沿用目标机数据)');
+        else {
+          await sshExec(ssh, `mv ${shq(`${appRoot}/data`)} ${shq(`${appRoot}/data.bak.${ts}`)} && cp -a ${shq(`${staging}/data`)} ${shq(`${appRoot}/data`)}`);
+          log.ok(`data/ 已覆盖(旧数据 → data.bak.${ts})`);
+        }
+      } else {
+        log.info('落位 data/(sqlite+uploads)...');
+        await sshExec(ssh, `cp -a ${shq(`${staging}/data/.`)} ${shq(`${appRoot}/data/`)}`);
+      }
+    }
+
+    // 6) run:APP_ROOT/start.sh 自定位 .mode → ops/docker/start.sh → run-container.sh
+    //   (停删旧容器 + 用刚 load 的镜像重建;env/secrets 注入全部复用服务器侧脚本,零参数漂移)
+    log.info('起容器(bash APP_ROOT/start.sh)...');
+    const runOut = await sshExec(ssh, `bash ${shq(`${appRoot}/start.sh`)}`);
+    console.log(runOut.split('\n').map((l) => `  ${l}`).join('\n'));
+
+    // 7) 状态回显:容器名沿用 3.2 从 staging/app/package.json 派生的 ctName(current 即其拷贝)
+    const status = await sshExec(ssh,
+      `docker ps -a --filter "name=${ctName}" --format 'table {{.Names}}\\t{{.Image}}\\t{{.Status}}\\t{{.Ports}}'`);
+    console.log(status);
+    log.ok(`容器 ${ctName}(运行状态见上;看日志: APP_ROOT/ops/docker/logs.sh)`);
+    log.ok('推送完成(镜像 + current + 根部配置 + 容器)');
+  } finally {
+    // 远端清理:staging 目录 + 上传 tar 均 best-effort 不阻塞;本地目录形态的临时 tar 同步清
+    if (ssh) {
+      await sshExec(ssh, `rm -rf ${shq(staging)}`).catch(() => {});
+      await sshExec(ssh, `rm -f ${shq(`${staging}.tar.gz`)}`).catch(() => {});
+      ssh.dispose();
+    }
+    if (localDir && fs.existsSync(tarPath)) fs.rmSync(tarPath, { force: true });
+  }
+}
+
+main().catch((e) => fatal(e.message));

package/templates/backend/scripts/rollback.cjs

@@ -4,18 +4,21 @@
  *
  * 用法:
  *   pnpm rollback -- --only backend   # ssh 进服务器,跑 APP_ROOT/versionswitch.sh(交互列版本、选一个)
+ *   pnpm rollback -- --env <名>        # 多服务器:选 server.config.cjs targets[名];不传:配了 targets 交互列选,否则顶层默认目标
  *
  * 不外传版本片段:版本选择由服务器 versionswitch.sh 交互完成(systemd/pm2 列 releases 改链,
  * docker 列镜像 tag 重 run)。本脚本只负责 SSH 连接 + 透传交互 TTY。
  */
 const path = require('path');
-const { log, fatal, shq, connect, sshExec, sshInteractive } = require('./lib/ssh.cjs');
+const { log, fatal, shq, connect, sshExec, sshInteractive, pickTarget } = require('./lib/ssh.cjs');
 
 const cfg = require('./server.config.cjs');
 
 async function main() {
-  const appRoot = cfg.backendServiceDir;
-  const ssh = await connect(cfg);
+  // 多服务器目标:--env <名> > targets 交互列选 > 顶层默认(server.config.cjs)
+  const { target } = await pickTarget(cfg);
+  const appRoot = target.backendServiceDir;
+  const ssh = await connect(target);
   try {
     const installed = await sshExec(ssh, `test -f ${shq(`${appRoot}/install.sh`)} && echo yes || echo no`);
     if (installed !== 'yes') fatal(`远端 ${appRoot}/install.sh 不存在(尚未首次部署,无可回滚版本)`);

package/templates/backend/scripts/server.config.example.cjs

@@ -1,3 +1,10 @@
+/*
+ * Author  Murphy.xie
+ * Date  2026-10-23 15:15:32
+ * LastEditors  Murphy.xie
+ * LastEditTime  2026-11-04 14:19:13
+ * Description
+ */
 /*
  * Description
  */
@@ -8,22 +15,43 @@
  * ⚠ 含服务器登录密码,server.config.cjs 已 .gitignore 排除,不入库。
  *
  * 生产密钥(jwt/admin/appSign)不在本文件 —— systemd/pm2 直读 release 自带
- * config/config.prod.yaml(改 current/config/config.prod.yaml + 重启即轮换);
- * docker 用服务器侧 APP_ROOT/.env(首次从 .env.example 种子化,空值阻断,运维手填)。
+ * 部署位 APP_ROOT/config/config.yaml(install.sh 播种的环境 overlay 副本,改它 + 重启即轮换,
+ * 三模式一致;docker 另有 .prod.docker.env 纯部署件[buildops 自动生成],不含业务配置)。
  */
 module.exports = {
-  // ── 服务器连接(SSH,上传 tar + 触发 install.sh 用) ──
-  server: {
-    host: '<服务器IP>',
-    port: 22,
-    username: 'root',
-    authMode: 'password', // 'password' | 'privateKey'
-    password: '<服务器密码>',
-    // authMode=privateKey 时用(~ 自动展开到家目录)
-    // privateKey: { privateKeyPath: '~/.ssh/your-key', passphrase: '' }
-  },
+	// ── 多服务器(可选,各机独立实例,互不共享数据) ──
+	// 目标解析(publish/rollback/pushdocker/pulldocker 共用):`--env <名>` 显式选;不传时 TTY 下列出 targets 交互选择(非交互(CI)回落首个);未配 targets 则用顶层单服务器形态。
+	// 建议与 web/scripts/server.config.json 的 key 同名:根命令 `pnpm publish -- --env <名>` 即 web+backend 同发一台。
+	targets: {
+		deploy: {
+			// ── 服务器连接(SSH,上传 tar + 触发 install.sh 用) ──
+			server: {
+				host: "<服务器IP>",
+				port: 22,
+				username: "root",
+				authMode: "password", // 'password' | 'privateKey'
+				password: "<服务器密码>",
+				// authMode=privateKey 时用(~ 自动展开到家目录)
+				// privateKey: { privateKeyPath: '~/.ssh/your-key', passphrase: '' }
+			},
+
+			// ── 后端服务目录(服务端 APP_ROOT:current/releases/data/logs 所在) ──
+			// 首次部署由 install.sh 在此目录下建 current/releases/data/logs 结构。
+			backendServiceDir: "/data/server/fullstack-template",
+			keepVersions: 1,
+		},
 
-  // ── 后端服务目录(服务端 APP_ROOT:current/releases/data/logs 所在) ──
-  // 首次部署由 install.sh 在此目录下建 current/releases/data/logs 结构。
-  backendServiceDir: '/data/server/fullstack-template'
+		"machine-b": {
+			server: {
+				host: "<服务器IP>",
+				port: 22,
+				username: "root",
+				authMode: "password",
+				password: "<服务器密码>",
+			},
+			// authMode=privateKey 时:server.privateKey = { privateKeyPath: '~/.ssh/your-key', passphrase: '' }
+			backendServiceDir: "/data/server/fullstack-template",
+			keepVersions: 1,
+		},
+	},
 };

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

@@ -10,7 +10,7 @@
  *                    <db> 为占位值,仅作开关用,不会被当目标路径读取)
  *     --out <file>     输出 markdown 到文件(默认 stdout)
  *
- * 读 data/slowsql/slowsql-YYYY-MM-DD.jsonl,聚合输出:
+ * 读 logs/slowsql/slowsql-YYYY-MM-DD.jsonl,聚合输出:
  *   1. 总览(时间范围/查询量/慢查询/lag/错误)
  *   2. 慢 SQL 指纹 top 表(含「宿主紧张占比」标注)
  *   3. lag / 宿主基线摘要
@@ -35,7 +35,7 @@ const OUT = flag('out');
 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 DEFAULT_DIR = path.join(process.cwd(), 'logs', '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)