create-ssnode-cli 0.2.5 → 0.2.7

package/templates/backend/docker-compose.yml

@@ -1,49 +1,57 @@
 # fullstack-template backend — docker compose 部署
 # 本文件与 Dockerfile 同级:开发机在 backend/ 根,buildops 拷入产物 releases/<version>-<ts>/(→ 服务器 current/),
 # compose 与 Dockerfile 同处 current/ 根。
-# 镜像: image:<TAG>(TAG 来自 .env,由 docker/install.sh 以 current/ 为 context 现场构建)
-# 配置: 环境变量注入(见 .env.example / configuration.ts env override)
+# 镜像: image:<TAG>(TAG 来自 .prod.docker.env,由 docker/install.sh 以 current/ 为 context 现场构建)
+# 配置: 部署位 CONFIG_DIR 只读挂载 /app/config(config.base.yaml + config.yaml 环境 overlay;
+#       业务配置一律在那,见 configuration.ts);env 文件只剩部署拓扑项(buildops 自动生成)
 # 数据: bind mount DATA_DIR → /app/data(跨版本共享,轮转/回滚不动)
+# 日志: bind mount LOGS_DIR → /app/logs(slowsql/apilog 落此,缺省随 DATA_DIR/logs 相邻)
 # 运维: 直接用 docker compose 命令(up/down/logs/ps),无需额外 shell
 
 services:
   backend:
-    # 镜像名与 docker/install.sh 的 config.sh IMAGE 默认对齐(fullstack-template-backend),
-    # tag = <version>-<14位ts>(install.sh 现场 build 时已对齐 .env 的 TAG)。
+    # 镜像名缺省(fullstack-template-backend)与 ops/docker 部署同口径:运行时 IMAGE 由
+    # ops/docker/config.sh 从包 name 派生、deploy 时覆写 env 文件对齐,此处缺省仅本地无 env 用。
+    # tag = <version>(install.sh 现场 build 时已对齐 env 文件的 TAG)。
     image: ${IMAGE:-fullstack-template-backend}:${TAG}
     # build context = current/(compose 文件所在目录);docker compose up --build 现场 build。
     # 迁移机若已 docker load 同 tag 镜像,docker compose up(不带 --build)直接用已加载镜像。
-    build: .
+    # APP_LABEL 注入与 ops/docker/install.sh 同源(IMAGE):镜像 label 恒 = IMAGE,prune 定向不错位。
+    build:
+      context: .
+      args:
+        APP_LABEL: ${IMAGE:-fullstack-template-backend}
     container_name: ${CONTAINER_NAME:-fullstack-template-backend}
     restart: unless-stopped
-    # 端口权威 = .env 的 PORT(env 注入,app 读 PORT 监听);宿主映射 = 容器监听 = PORT。
-    # 迁移换端口只改 .env 的 PORT,镜像不动。
+    # 端口权威 = .prod.docker.env 的 PORT(env 注入,app 读 PORT 监听);宿主映射 = 容器监听 = PORT。
+    # 迁移换端口只改 env 文件的 PORT,镜像不动。
     ports:
       - "${PORT:-3001}:${PORT:-3001}"
     environment:
       NODE_ENV: ${NODE_ENV:-prod}
-      # PORT 权威在此(app 读 PORT 监听;未注入则回退镜像内 config/config.prod.yaml app.port)。
+      # PORT 权威在此(app 读 PORT 监听;未注入则回退配置 yaml 的 app.port)。
       PORT: ${PORT:-3001}
-      # 容器内持久化路径写死(随 /app/data mount 目标锁定,非部署期变量):
+      # 容器内持久化路径写死(随 /app/data、/app/logs mount 目标锁定,非部署期变量):
       #   DB_DIR              → sqlite 主库所在目录(文件名由程序定死为 template.prod.sqlite)
       #   UPLOAD_STORAGE_PATH → 上传文件子目录
-      # 部署期只调宿主 DATA_DIR(mount 源),容器内布局固定、不可错位。
+      #   SLOW_SQL_DIR        → 慢SQL探针 JSONL 落盘子目录(logs 卷)
+      #   API_LOG_DIR         → 运维调试日志 JSONL 落盘子目录(logs 卷)
+      # 业务配置(密钥/密码/限流阈值等)不经 env 注入 —— 一律走下方 config 挂载的部署位 yaml。
       DB_DIR: /app/data
       UPLOAD_STORAGE_PATH: /app/data/uploads
-      CORS_ORIGINS: ${CORS_ORIGINS:-}
-      TRUST_PROXY: ${TRUST_PROXY:-false}
-      JWT_SECRET: ${JWT_SECRET:-}
-      JWT_EXPIRES: ${JWT_EXPIRES:-}
-      LOG_LEVEL: ${LOG_LEVEL:-}
-      ADMIN_PASSWORD: ${ADMIN_PASSWORD:-}
-      APP_SIGN_KEY: ${APP_SIGN_KEY:-}
-      APP_SIGN_TS_WINDOW: ${APP_SIGN_TS_WINDOW:-}
+      SLOW_SQL_DIR: /app/logs/slowsql
+      API_LOG_DIR: /app/logs/apilog
     volumes:
-      # 单一宿主持久化根 → /app/data(容器内固定)。db/backup/logs/uploads 全落此 volume 子目录,
-      # 后续追加新子目录无需再加 mount。DATA_DIR 必填,不设默认值以免误落到错误宿主路径。
-      - ${DATA_DIR:?DATA_DIR must be set in .env}:/app/data
+      # 部署位配置(业务配置单一真相源):CONFIG_DIR 指向 APP_ROOT/config(含 config.base.yaml +
+      # config.yaml 环境 overlay 真值),只读挂载;缺省回落 compose 同级 config/(镜像兜底同款)。
+      - ${CONFIG_DIR:-./config}:/app/config:ro
+      # 宿主持久化双卷:数据 → /app/data(db/backup/uploads 全落此 volume 子目录);
+      # 进程日志 → /app/logs(slowsql/apilog JSONL)。DATA_DIR 必填,不设默认值
+      # 以免误落到错误宿主路径;LOGS_DIR 缺省随 DATA_DIR/logs 相邻(勿与数据混放需显式指定)。
+      - ${DATA_DIR:?DATA_DIR must be set in .prod.docker.env}:/app/data
+      - ${LOGS_DIR:-${DATA_DIR}/logs}:/app/logs
     healthcheck:
-      # 无独立 /health 接口,改用 TCP 端口探测(容器内自连,端口须与 .env PORT 一致)
+      # 无独立 /health 接口,改用 TCP 端口探测(容器内自连,端口须与 env 文件 PORT 一致)
       test: ["CMD", "node", "-e", "require('net').connect(${PORT:-3001},'127.0.0.1').on('connect',()=>process.exit(0)).on('error',()=>process.exit(1))"]
       interval: 30s
       timeout: 5s

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

@@ -1,8 +1,9 @@
 #!/usr/bin/env bash
 # docker 部署共用配置 —— 运维按环境改这一处即可,各脚本都 source 它。
+# 容器创建命令(docker run 参数)收敛在同目录 run-container.sh,修改挂载/env 参数去那里。
 #
 # 与 systemd/pm2 的 config.sh 对位。APP_ROOT 由顶层 install.sh / start.sh / stop.sh
-# 经环境变量传入(顶层脚本已 baked 字面量);此处只补 docker 专属变量。
+# 经环境变量传入(顶层脚本运行时自定位);此处只补 docker 专属变量。
 
 # 后端根目录(current/releases/data/logs 所在)—— 顶层脚本导出
 APP_ROOT="${APP_ROOT:-}"
@@ -11,15 +12,31 @@ APP_ROOT="${APP_ROOT:-}"
 CURRENT_DIR="$APP_ROOT/current"
 DATA_DIR="$APP_ROOT/data"
 LOG_DIR="$APP_ROOT/logs"
-ENV_FILE="$APP_ROOT/.env"
+# 部署位配置目录(跨版本共享:config.base.yaml + config.yaml 环境 overlay 真值)——
+# run-container.sh 只读挂载进容器 /app/config,configuration.ts 经 cwd/config 命中挂载副本
+# (镜像内 base+prod 仅为无挂载时的兜底)。改 $APP_ROOT/config/config.yaml + ./start.sh 即生效。
+CONFIG_DIR_HOST="$APP_ROOT/config"
+# 容器内挂载目标(随 /app/config 布局锁定,非部署期变量)
+CONTAINER_CONFIG_DIR="/app/config"
+# 容器 env 文件(docker 模式专用,纯部署件:IMAGE/TAG/CONTAINER_NAME/PORT/DATA_DIR/LOGS_DIR/
+# NODE_ENV,buildops 自动生成、install.sh 部署时随包拷入 APP_ROOT 根并对齐;业务配置不在此,
+# 在 $CONFIG_DIR_HOST/config.yaml):路径可外配 —— 运维想把 env 文件挪到独立目录时
+# export ENV_FILE 覆盖(需提前自行拷贝到位)。
+ENV_FILE="${ENV_FILE:-$APP_ROOT/.prod.docker.env}"
+# 配置密文根密钥(与 systemd/pm2 同口径):首部署选「开启配置加密」时由 ops/lib-encrypt.sh
+# 在本机生成(600)。run-container.sh 读取后以 docker run -e 注入(--env-file 的
+# .prod.docker.env 不放根密钥);缺文件 = 明文模式(不注入)。
+SECRETS_FILE="$APP_ROOT/.prod.secrets"
 
-# 镜像名(不含 tag;tag = <version>-<14位ts>,见 read_tag)
-IMAGE="${IMAGE:-fullstack-template-backend}"
-# 容器名
-CONTAINER_NAME="${CONTAINER_NAME:-fullstack-template-backend}"
-# 运行端口权威 = .env 的 PORT(docker 模式 env 注入,app 读 PORT 监听;迁移换端口只改 .env)。
+# 共享函数库(服务身份运行时从 current/package.json 派生;source 零动作)
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/lib.sh"
+# 镜像名(不含 tag;tag = <version>,见 read_tag)—— 包 name 派生,export IMAGE 可覆盖
+IMAGE="${IMAGE:-$(pkg_name)}"
+# 容器名 —— 同上派生,export CONTAINER_NAME 可覆盖(身份与包名分叉的项目用)
+CONTAINER_NAME="${CONTAINER_NAME:-$(pkg_name)}"
+# 运行端口权威 = .prod.docker.env 的 PORT(docker 模式 env 注入,app 读 PORT 监听;迁移换端口只改它)。
 # 宿主映射 = 容器内监听 = 此端口(PORT:PORT,nginx 反代到此),与 healthcheck 一致。
-# .env 无 PORT 回退 3001(防御,不阻断)。systemd/pm2 模式端口权威在 config.prod.yaml,与此无关。
+# env 文件无 PORT 回退 3001(防御,不阻断)。systemd/pm2 模式端口权威在部署位 config.yaml,与此无关。
 read_env_port() {
   [[ -f "$ENV_FILE" ]] || { printf '%s' "3001"; return; }
   local p
@@ -36,14 +53,12 @@ RESTART_POLICY="${RESTART_POLICY:-unless-stopped}"
 # 版本轮转保留数(docker = 本镜像仓库历史 tag 数,即回滚窗口;顶层 install.sh 轮转时读)
 KEEP_VERSIONS="${KEEP_VERSIONS:-3}"
 
-# 读 current 的 version + .build-ts 作镜像 tag(<version>-<14位ts>,与 systemd/pm2 releases/<ver>-<ts> 同口径)。
-# .build-ts 由 buildops 写入;缺则回退纯 version(兼容旧 release,但同 version 重发会覆盖,留意回滚)。
+# 读 current 的 version 作镜像 tag(纯 version,不带时间戳)。
+# 注意:同 version 重发 = 同名 tag 覆盖重建,回滚窗口 = 轮转保留的不同 version 数。
+# (.build-ts 由 buildops 写入包内,仅作构建时间溯源,docker tag 不消费)
 read_tag() {
-  local v ts
+  local v
   v="$(grep -m1 '"version"' "$CURRENT_DIR/package.json" 2>/dev/null \
     | sed -E 's/.*"version"[[:space:]]*:[[:space:]]*"([^"]+)".*/\1/' || true)"
-  ts="$(cat "$CURRENT_DIR/.build-ts" 2>/dev/null || true)"
-  if [[ -n "$v" && -n "$ts" ]]; then printf '%s-%s' "$v" "$ts"
-  else printf '%s' "$v"
-  fi
+  printf '%s' "$v"
 }

package/templates/backend/ops/docker/install.sh

@@ -3,8 +3,9 @@
  # Description  docker 部署 apply:从 current/ context build 镜像 → 停删旧容器 → run 新容器
 ###
 # 由顶层 install.sh / versionswitch.sh 派发(APP_ROOT/MODE 已导出)。
-# env 从 APP_ROOT/.env 注入(持久权威);data 走 volume 挂载 /app/data。
-# 镜像 tag = <version>-<14位ts>(read_tag 读 current/package.json + .build-ts);每次部署一个新 tag,旧 tag 留作回滚。
+# env(纯部署件)从 APP_ROOT/.prod.docker.env 注入(install.sh 部署时随包拷入);业务配置经
+# 部署位 APP_ROOT/config 只读挂载 /app/config(run-container.sh);data 走 volume 挂载 /app/data。
+# 镜像 tag = <version>(read_tag 读 current/package.json);同 version 重发覆盖同名 tag,旧 version tag 留作回滚。
 set -euo pipefail
 DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$DIR/config.sh"
@@ -26,56 +27,47 @@ echo "▶ docker build $IMAGE_TAG (context=$CURRENT_DIR) ..."
 # 直接以 current/ 为 build context:Dockerfile 与 .dockerignore 都在 current/ 根,
 # .dockerignore 排除 ops/ 等非镜像文件,context 仅含 package.json/dist/config/Dockerfile。
 # Dockerfile 的 COPY package.json/dist/config 即从 current/ 根取,与目录布局对齐。
-if [[ ! -f "$CURRENT_DIR/config/config.prod.yaml" ]]; then
-  echo "⚠ current/config/config.prod.yaml 不存在,镜像将无默认配置(全靠 -e env)"
+if [[ ! -f "$CURRENT_DIR/config/config.base.yaml" ]]; then
+  echo "⚠ current/config/config.base.yaml 不存在,镜像将无兜底配置(全靠部署位挂载)"
 fi
 
-docker build -t "$IMAGE_TAG" "$CURRENT_DIR"
+# --build-arg APP_LABEL=IMAGE:镜像 label 与运行时 IMAGE 同源烙入(Dockerfile 各阶段 ARG 接),
+# rotate_images 的 prune 过滤(label=app=$IMAGE)恒命中本应用,不随身份派生错位。
+docker build --build-arg APP_LABEL="$IMAGE" -t "$IMAGE_TAG" "$CURRENT_DIR"
 echo "✓ 镜像构建: $IMAGE_TAG"
 
-# env:APP_ROOT/.env 为权威(顶层 install.sh 已保证存在且空值已阻断)
-ENV_FLAG=""
+# 配置加密维护(每次部署,镜像构建后进行:docker 宿主常无 node,加密经一次性容器执行):
+# 首部署选「开启加密」时在本机生成根密钥;有根密钥则把部署位 config.yaml 新明文就地加密
+# (改明文 + 重跑 ./install.sh = 轮换闭环,见 docs/config-encryption.md)。
+source "$DIR/../lib-encrypt.sh"
+ensure_config_encryption "$IMAGE_TAG"
+
+# env:APP_ROOT/.prod.docker.env 为权威(顶层 install.sh 部署时已随包拷入并前置对齐)。
+# 现场对齐本次构建的 IMAGE/TAG/DATA_DIR/CONTAINER_NAME(PORT 在 env 文件由运维权威,不覆盖)。
+# (IMAGE/TAG 与 config.sh 的构建一致;--env-file 把 env 文件全量灌进容器,含 PORT)
 if [[ -f "$ENV_FILE" ]]; then
-  # 对齐本次部署的 IMAGE/TAG/DATA_DIR/CONTAINER_NAME(PORT 在 .env 由运维权威,不覆盖)
-  # (IMAGE/TAG 与 config.sh 的构建一致;--env-file 把 .env 全量灌进容器,含 PORT/密钥)
   _sed_i "$ENV_FILE" \
     -e "s|^IMAGE=.*|IMAGE=$IMAGE|" \
     -e "s|^TAG=.*|TAG=$TAG|" \
     -e "s|^DATA_DIR=.*|DATA_DIR=$DATA_DIR|" \
     -e "s|^CONTAINER_NAME=.*|CONTAINER_NAME=$CONTAINER_NAME|"
-  ENV_FLAG="--env-file $ENV_FILE"
-else
-  echo "⚠ 缺 $ENV_FILE,用空 env 起容器(仅限调试,密钥将为空)"
 fi
 
-echo "▶ 重建容器 $CONTAINER_NAME ..."
-docker stop "$CONTAINER_NAME" 2>/dev/null || true
-docker rm "$CONTAINER_NAME" 2>/dev/null || true
-
-# 端口权威 = .env 的 PORT(config.sh::read_env_port 读);-e PORT 注入 app 监听,-p 映射同值。
-# DB_DIR/UPLOAD_STORAGE_PATH 随 /app/data mount 目标锁定,容器内布局固定。
-docker run -d \
-  --name "$CONTAINER_NAME" \
-  --restart "$RESTART_POLICY" \
-  -p "$HOST_PORT:$CONTAINER_PORT" \
-  $ENV_FLAG \
-  -e NODE_ENV=prod \
-  -e PORT="$PORT" \
-  -e DB_DIR="$CONTAINER_DATA_DIR" \
-  -e UPLOAD_STORAGE_PATH="$CONTAINER_DATA_DIR/uploads" \
-  -v "$DATA_DIR:$CONTAINER_DATA_DIR" \
-  "$IMAGE_TAG"
+# 容器创建命令收敛于 run-container.sh(与 start.sh/versionswitch.sh 共用,参数勿在调用方手拷)
+source "$DIR/run-container.sh"
+run_container "$IMAGE_TAG"
 
 echo "✓ 容器已起: $CONTAINER_NAME (宿主 $HOST_PORT → $CONTAINER_PORT, tag $TAG)"
 
 # ── 镜像轮转:对齐 systemd/pm2 的 rotate_releases 口径 ──
 # docker 模式版本靠镜像 tag、不进 releases/,故轮转对象 = 本镜像仓库的历史 tag:
-# 按末段 14 位时间戳降序保留 KEEP_VERSIONS 个(缺省见 config.sh),其余 rmi(回滚窗口=保留数)。
+# 按版本号降序保留 KEEP_VERSIONS 个(缺省见 config.sh),其余 rmi(回滚窗口=保留数)。
 # KEEP_VERSIONS 优先级:顶层 --keep/env 显式 export > config.sh 持久值(运维改这处)。
 # 不删运行中容器在用的 tag(防御);versionswitch.sh 切版本不经过本脚本,不受影响。
 rotate_images() {
   # 半成品兜底:经典 builder 多阶段构建的 deps 阶段成品(711MB 级 <none>)无 tag、无子层,轮转清不到;
-  # 按 Dockerfile 烙进各层的 app label 定向 prune(仅本应用,不碰宿主其他镜像)。
+  # 按镜像 app label 定向 prune(仅本应用,不碰宿主其他镜像)—— label 由本脚本 --build-arg
+  # 以 IMAGE 注入,与过滤值同源恒命中(规矩:改 IMAGE 只改 config.sh/外配,label 随 build 自动跟)。
   # 但该 <none> 同时是经典 builder 的构建缓存(删掉 = 下次全量重跑 apt+npm ci),故加 until=72h:
   # 只清 72h 前的陈年残留,当天/周末内刚生成的缓存保住(发版即刷新存活期);放在 tag 轮转前,
   # 不受 ≤KEEP_VERSIONS 提前 return 影响。
@@ -83,12 +75,11 @@ rotate_images() {
   local running_ref
   running_ref="$(docker inspect "$CONTAINER_NAME" --format '{{.Config.Image}}' 2>/dev/null || true)"
   local list=() t
-  # tag 形如 <version>-<14位ts>;awk 提取末段时间戳做 sort 键降序(与顶层 sort_releases 同构)
+  # tag = 纯 version;按版本号降序(sort -rV,与 versionswitch.sh switch_docker 列 tag 同口径)
   while IFS= read -r t; do
     [[ -n "$t" ]] || continue
     list+=("$t")
-  done < <(docker images "$IMAGE" --format '{{.Tag}}' | grep -E -- '-[0-9]{14}$' \
-    | awk '{ts=$0; sub(/.*-/,"",ts); print ts" "$0}' | sort -r | awk '{print $2}')
+  done < <(docker images "$IMAGE" --format '{{.Tag}}' | grep -v '<none>' | sort -rV || true)
   [[ ${#list[@]} -le $KEEP_VERSIONS ]] && return 0
   local del=("${list[@]:$KEEP_VERSIONS}")
   for t in "${del[@]}"; do

package/templates/backend/ops/docker/run-container.sh

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+###
+ # Description: docker 容器创建命令单一真相源(start/install/versionswitch 三处共用)
+###
+# 本文件是被 source 的函数库(source 时零动作),调用方须先 source 同目录 config.sh
+# (依赖其中 CONTAINER_NAME/RESTART_POLICY/HOST_PORT/CONTAINER_PORT/CONTAINER_DATA_DIR/
+#  DATA_DIR/LOG_DIR/CONFIG_DIR_HOST/CONTAINER_CONFIG_DIR/ENV_FILE/PORT)。
+#
+# 设计动机:env 文件只在容器"创建"那一刻经 docker run --env-file 灌入容器元数据,
+# 之后 docker stop/start 是恢复旧容器、不重读 env —— 改 .prod.docker.env 后必须重建容器才生效。
+# 故"启容器"统一收敛为重建:env 文件是纯部署件(buildops 自动生成,只有 IMAGE/TAG/PORT 等拓扑项);
+# 业务配置走部署位 $CONFIG_DIR_HOST(只读挂载 /app/config,configuration.ts 命中挂载副本,
+# 改 config.yaml + ./start.sh 即生效);根密钥经 .prod.secrets → run -e 单独注入(不落 env 文件;
+# 首部署选「开启加密」时生成,缺文件 = 明文模式不注入);
+# stdout 走 json-file 轮转 50MB×3(治日志撑盘)。
+#   start.sh      = 用现有镜像 + 当前 env 文件/配置挂载重建(不 build;改 .prod.docker.env 或
+#                   $APP_ROOT/config/config.yaml → ./start.sh 即生效)
+#   install.sh    = build 新镜像后重建(随发布)
+#   versionswitch = 换 tag 重建(随版本切换)
+# 三处的 docker run 参数必须逐字一致(端口/-p/env/volume/重启策略),历史三份手拷已收敛到本函数,
+# 改挂载/env 参数只改这里。
+
+# ── 兼容旧部署保留的 config.sh(存量升级)──
+# config.sh 是运维文件,顶层 install.sh::lay_out_ops 跨版本保留不覆盖;本文件却随发布刷新。
+# 分层改造(base+overlay,CONFIG_DIR_HOST 挂载)之前完成首部署的服务器,其保留的 config.sh
+# 缺下面两个新变量 → set -u 下刷新后的本文件引用即炸 unbound variable。缺省回填部署位
+# 标准值(运维在 config.sh 的显式定义/export 覆盖仍优先);新变量今后再进 config.sh 时,
+# 若旧部署会缺,同样在此补一行兜底。
+CONFIG_DIR_HOST="${CONFIG_DIR_HOST:-$APP_ROOT/config}"
+CONTAINER_CONFIG_DIR="${CONTAINER_CONFIG_DIR:-/app/config}"
+
+# run_container <镜像完整引用,如 <pkg-name>:1.0.0-20261014120000>(镜像名 = 包 name 派生)
+#   幂等:先 stop/rm 同名旧容器再 run。数据/日志不受影响 —— 分别落 $DATA_DIR/$LOG_DIR
+#   宿主目录(bind mount /app/data、/app/logs 双卷),容器重建不动卷。
+#   同名容器被占用/端口被抢由 docker run 自行报错退出。
+run_container() {
+  local image_ref="$1"
+  [[ -n "$image_ref" ]] || { echo "✗ run_container: 缺镜像引用参数" >&2; return 1; }
+
+  # env:APP_ROOT/.prod.docker.env 为权威(install.sh 部署时随包拷入;此处兜底告警不阻断)
+  local env_flag=""
+  if [[ -f "$ENV_FILE" ]]; then
+    env_flag="--env-file $ENV_FILE"
+  else
+    echo "⚠ 缺 $ENV_FILE,用空 env 起容器(仅限调试,密钥将为空)" >&2
+  fi
+
+  echo "▶ 重建容器 $CONTAINER_NAME ..."
+  docker stop "$CONTAINER_NAME" 2>/dev/null || true
+  docker rm "$CONTAINER_NAME" 2>/dev/null || true
+
+  # 端口权威 = env 文件的 PORT(config.sh::read_env_port 读,config.sh source 时已赋 PORT/
+  # HOST_PORT/CONTAINER_PORT);-e PORT 注入 app 监听,-p 映射同值。
+  # DB_DIR/UPLOAD_STORAGE_PATH 随 /app/data、SLOW_SQL_DIR/API_LOG_DIR 随 /app/logs
+  # mount 目标锁定,容器内布局固定。
+  # 业务配置 = 部署位 $CONFIG_DIR_HOST(只读挂载 /app/config;缺目录 = 部署不完整,
+  # 告警并回落镜像内兜底 config,仅限调试)。
+  local cfg_flag=""
+  if [[ -d "$CONFIG_DIR_HOST" && -f "$CONFIG_DIR_HOST/config.yaml" ]]; then
+    cfg_flag="-v $CONFIG_DIR_HOST:$CONTAINER_CONFIG_DIR:ro"
+  else
+    echo "⚠ 缺 $CONFIG_DIR_HOST/config.yaml,容器用镜像内兜底 config(仅限调试;重跑 ./install.sh 播种部署位配置)" >&2
+  fi
+  # 根密钥(CONFIG_SECRET_KEY)从 $SECRETS_FILE(= APP_ROOT/.prod.secrets;首部署选「开启加密」
+  # 时由 lib-encrypt.sh 在本机生成、600)读取后以 run -e 注入容器。缺文件 = 明文模式
+  # (容器不注,应用按 security.encrypt=false 接受明文,仅限明文部署/调试);但部署位
+  # config.yaml 带 ENC(...) 而无密钥属部署完整性缺失,直接失败让运维回 install.sh 重新部署。
+  local enc_flags=()
+  if [[ -f "$SECRETS_FILE" ]]; then
+    local secrets_key
+    secrets_key="$(sed -nE 's/^CONFIG_SECRET_KEY=//p' "$SECRETS_FILE" | head -1 | sed -E "s/^['\"]?//; s/['\"]?$//")"
+    [[ -n "$secrets_key" ]] || { echo "✗ $SECRETS_FILE 无 CONFIG_SECRET_KEY(补齐后重跑)" >&2; return 1; }
+    enc_flags=(-e CONFIG_SECRET_KEY="$secrets_key")
+  elif grep -q 'ENC(' "$CONFIG_DIR_HOST/config.yaml" 2>/dev/null; then
+    echo "✗ 缺 $SECRETS_FILE 但部署位 config.yaml 含 ENC(...) 密文(重跑 ./install.sh <release 包> 重新部署)" >&2
+    return 1
+  else
+    echo "⚠ 明文模式:无 $SECRETS_FILE,容器不注 CONFIG_SECRET_KEY" >&2
+  fi
+
+  docker run -d \
+    --name "$CONTAINER_NAME" \
+    --restart "$RESTART_POLICY" \
+    --log-driver json-file \
+    --log-opt max-size=50m \
+    --log-opt max-file=3 \
+    -p "$HOST_PORT:$CONTAINER_PORT" \
+    $env_flag \
+    $cfg_flag \
+    -e NODE_ENV=prod \
+    -e PORT="$PORT" \
+    ${enc_flags[@]+"${enc_flags[@]}"} \
+    -e DB_DIR="$CONTAINER_DATA_DIR" \
+    -e UPLOAD_STORAGE_PATH="$CONTAINER_DATA_DIR/uploads" \
+    -e SLOW_SQL_DIR="/app/logs/slowsql" \
+    -e API_LOG_DIR="/app/logs/apilog" \
+    -v "$DATA_DIR:$CONTAINER_DATA_DIR" \
+    -v "$LOG_DIR:/app/logs" \
+    "$image_ref"
+}

package/templates/backend/ops/docker/start.sh

@@ -1,14 +1,43 @@
 #!/usr/bin/env bash
-# 启动 docker 容器(已存在则 start,不存在提示先 install)。
+# 启动 docker 容器 —— 重建而非 docker start:
+#   env 只在容器创建时经 --env-file 灌入容器元数据,docker start 旧容器不重读 env 文件(改了不生效)。
+#   故 start = 停删旧容器 + 按权威 tag 用现有镜像重 run(不 build,秒级)。
+#   运维改 APP_ROOT/.prod.docker.env 或 APP_ROOT/config/config.yaml 后 ./start.sh 即生效,
+#   与 systemd/pm2 改部署位 yaml + restart 同体验(业务配置单一真相源 = 部署位 config.yaml)。
+#   数据安全:$APP_ROOT/data 为宿主 bind mount,容器重建不动数据。
 set -euo pipefail
 DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$DIR/config.sh"
+source "$DIR/run-container.sh"
 
-echo "▶ 启动 $CONTAINER_NAME ..."
-if docker ps -a --format '{{.Names}}' | grep -qx "$CONTAINER_NAME"; then
-  docker start "$CONTAINER_NAME"
-  echo "✓ started."
-else
-  echo "✗ 容器不存在,先跑 install.sh(或顶层 install.sh/versionswitch.sh 派发)"
-  exit 1
+command -v docker >/dev/null 2>&1 || { echo "✗ docker 不存在(PATH 无 docker)" >&2; exit 1; }
+
+# 版本权威 = env 文件的 TAG(部署/install 与版本切换/versionswitch 时机都会对齐写入;
+# versionswitch 切换不改 current/,故不能以 current 包为权威,env TAG 才是运行版本真相)。
+# env 文件缺 TAG 回退 read_tag(读 current/package.json,兜底)。
+read_env_tag() {
+  [[ -f "$ENV_FILE" ]] || { printf ''; return; }
+  local t
+  t="$(sed -nE 's/^TAG=//p' "$ENV_FILE" | head -1 | sed -E "s/^['\"]?//; s/['\"]?$//; s/^[[:space:]]+//; s/[[:space:]]+$//")"
+  printf '%s' "$t"
+}
+TAG="$(read_env_tag)"
+[[ -n "$TAG" ]] || TAG="$(read_tag)"
+[[ -n "$TAG" ]] || { echo "✗ 无法定位版本 tag(env 文件无 TAG 且 current/package.json 不可读);先跑 install.sh(部署)或 versionswitch.sh(切换版本)" >&2; exit 1; }
+
+IMAGE_REF="$IMAGE:$TAG"
+if ! docker image inspect "$IMAGE_REF" >/dev/null 2>&1; then
+  # 回退链:当前运行容器所用镜像(docker rmi 不删被容器引用的 tag,故容器在 → 镜像必在)。
+  # 覆盖场景:env TAG 被改脏 / 旧 tag 被 KEEP_VERSIONS 轮转清掉。保启动优先,无容器可回退才 die。
+  RUNNING_REF="$(docker inspect --format '{{.Config.Image}}' "$CONTAINER_NAME" 2>/dev/null || true)"
+  if [[ -n "$RUNNING_REF" ]] && docker image inspect "$RUNNING_REF" >/dev/null 2>&1; then
+    echo "⚠ 镜像 $IMAGE_REF 不存在(TAG 失效),回退用当前运行容器镜像:$RUNNING_REF"
+    IMAGE_REF="$RUNNING_REF"
+  else
+    echo "✗ 镜像 $IMAGE_REF 不存在且无运行容器可回退;先跑 install.sh(部署)或 versionswitch.sh(切换到本机已有 tag)" >&2
+    exit 1
+  fi
 fi
+
+run_container "$IMAGE_REF"
+echo "✓ started: $CONTAINER_NAME (镜像 $IMAGE_REF,env 来自 $ENV_FILE)"

package/templates/backend/ops/docker/stop.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# 停止 docker 容器(进程保留容器,可再 start)。
+# 停止 docker 容器(保留容器;再 start 会按当前 env 文件(.prod.docker.env)、部署位 config.yaml 挂载与权威 tag 重建容器)。
 set -euo pipefail
 DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$DIR/config.sh"

package/templates/backend/ops/ensure-encrypt.cjs

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+/*
+ * ensure-encrypt —— 部署位配置加密维护器(服务器侧执行,零依赖,每次 install.sh 部署调用)
+ *
+ * 用法(根密钥经 CONFIG_SECRET_KEY env 传入,base64 的 32 字节):
+ *   CONFIG_SECRET_KEY=<key> node ensure-encrypt.cjs relock <configDir>
+ *   node ensure-encrypt.cjs genkey
+ *
+ * relock(加密维护,ops/lib-encrypt.sh 调用;处理 <configDir>/config.yaml,受控字段清单读
+ *   <configDir>/config.base.yaml 的 security.encryptedFields,缺省回落内置四项):
+ *   1. 校验文件内既有 ENC(...) 密文能用当前密钥解开(GCM 认证)—— 密钥错配/密文损坏
+ *      fail-fast,防「换密钥后旧密文静默解不开、服务起不来才发现」。
+ *   2. 把清单内【非空明文】值就地加密为 ENC(...) 密文(行级改写,注释与其余内容逐字节
+ *      保留;空占位('')与已是 ENC(...) 的值原样保留)—— 改明文 + 重跑 ./install.sh
+ *      即完成轮换闭环,服务器上不需要手工跑 config-crypt。
+ *   3. 把 config.yaml 的 security.encrypt 写为 true(深合并覆盖 base 的 false)。应用防呆
+ *      校验随之开启:此后手改明文直接重启会被拦下,提示回 ./install.sh 自动加密。
+ *
+ * genkey:生成新根密钥(base64 32 字节)打印到 stdout(lib-encrypt.sh init 流程用)。
+ *
+ * 密文格式 ENC(<b64(iv)>.<b64(authTag)>.<b64(cipher)>),AES-256-GCM,与
+ *   scripts/config-crypt.cjs 及运行时 src/common/config-crypto.ts 同源
+ *   (每次加密 IV 随机,同明文密文不同)。
+ */
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const KEY_BYTES = 32;
+// 与 configuration.ts 的 DEFAULT_ENCRYPTED_FIELDS 同步维护
+const DEFAULT_ENCRYPTED_FIELDS = ['jwt.secret', 'admin.password', 'sso.ticketKey', 'appSign.cryptKey'];
+
+function fail(msg) {
+  console.error(`✗ ${msg}`);
+  process.exit(1);
+}
+
+/** 零依赖读 config.base.yaml 的 security.encryptedFields(受控清单;清单形态由模板保证:
+ *  security: 段内缩进的 encryptedFields: + 更深缩进的 "- dot.path" 列表项)。缺文件/缺段/空
+ *  清单回落内置默认 —— 与 configuration.ts 的深合并结果同口径。 */
+function readFields(baseFile) {
+  try {
+    const lines = fs.readFileSync(baseFile, 'utf8').split('\n');
+    let inSecurity = false;
+    let inFields = false;
+    let fieldsIndent = -1;
+    const fields = [];
+    for (const line of lines) {
+      const top = /^([A-Za-z_][\w-]*):/.exec(line);
+      if (top) { inSecurity = top[1] === 'security'; inFields = false; continue; }
+      if (!inSecurity) continue;
+      const m = /^(\s+)([A-Za-z_][\w-]*):/.exec(line);
+      if (!m) continue;
+      if (m[2] === 'encryptedFields') { inFields = true; fieldsIndent = m[1].length; continue; }
+      if (inFields) {
+        const item = /^(\s*)-\s*(\S+)/.exec(line);
+        if (item && item[1].length > fieldsIndent) fields.push(item[2]);
+        else inFields = false;
+      }
+    }
+    return fields.length ? fields : DEFAULT_ENCRYPTED_FIELDS;
+  } catch {
+    return DEFAULT_ENCRYPTED_FIELDS;
+  }
+}
+
+/** 明文 → ENC(...) 密文(与 config-crypt.cjs encrypt 同格式) */
+function encryptValue(plain, key) {
+  const iv = crypto.randomBytes(12);
+  const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+  const enc = Buffer.concat([cipher.update(plain, 'utf8'), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return `ENC(${iv.toString('base64')}.${tag.toString('base64')}.${enc.toString('base64')})`;
+}
+
+/** ENC(...) → 明文(校验既有密文用;失败抛错) */
+function decryptValue(value, key) {
+  const inner = value.slice('ENC('.length, -1);
+  const parts = inner.split('.');
+  if (parts.length !== 3) throw new Error('密文格式非法');
+  const iv = Buffer.from(parts[0], 'base64');
+  const tag = Buffer.from(parts[1], 'base64');
+  const cipher = Buffer.from(parts[2], 'base64');
+  const decipher = crypto.createDecipheriv('aes-256-gcm', key, iv, { authTagLength: 16 });
+  decipher.setAuthTag(tag);
+  return Buffer.concat([decipher.update(cipher), decipher.final()]).toString('utf8');
+}
+
+/**
+ * yaml 行级改写:按缩进栈计算每行 key 的 dot-path,命中清单且为非空明文才替换值,
+ * 注释/空白/其余行逐字节保留(不走 load+dump,那会丢光注释)。
+ * 返回 [改写后文本, 已加密的 dot-path 列表]。
+ */
+function rewriteYaml(text, fields, key) {
+  const lines = text.split('\n');
+  const targets = new Set(fields);
+  const stack = []; // { indent, key }
+  const encryptedPaths = [];
+  for (let i = 0; i < lines.length; i++) {
+    // 仅捕获普通 key: 行;空行/注释/列表项(- )/flow 续行不动(受控字段均为此形态)
+    const m = /^(\s*)([A-Za-z_][\w-]*)\s*:(.*)$/.exec(lines[i]);
+    if (!m) continue;
+    const [, indentStr, key_, rest] = m;
+    const indent = indentStr.length;
+    while (stack.length && stack[stack.length - 1].indent >= indent) stack.pop();
+    const dotted = [...stack.map((s) => s.key), key_].join('.');
+    stack.push({ indent, key: key_ });
+    if (!targets.has(dotted)) continue;
+
+    // 取值段:引号包裹取内层(保留引号后尾注),裸值剥行尾注释(v # c 形态);
+    // 空占位 / 父节点(值空)/ 已是 ENC(...) 均原样保留
+    const v = rest.trim();
+    if (!v) continue;
+    let plain = '';
+    let tail = '';
+    const qm = /^'([^']*)'([\s\S]*)$/.exec(v) || /^"([^"]*)"([\s\S]*)$/.exec(v);
+    if (qm) {
+      plain = qm[1];
+      tail = qm[2].trim();
+    } else {
+      const hash = v.indexOf(' #');
+      if (hash >= 0) {
+        tail = v.slice(hash).trim();
+        plain = v.slice(0, hash).trim();
+      } else {
+        plain = v;
+      }
+    }
+    if (!plain || (plain.startsWith('ENC(') && plain.endsWith(')'))) continue;
+    lines[i] = `${indentStr}${key_}: ${encryptValue(plain, key)}${tail ? ` ${tail}` : ''}`;
+    encryptedPaths.push(dotted);
+  }
+  return [lines.join('\n'), encryptedPaths];
+}
+
+/**
+ * 把 config.yaml 的 security.encrypt 置 true(行级改写):
+ *   有 security: 段且带 encrypt: 键 → 原位改值;有段无键 → 段首插入;无段 → 文件末尾追加。
+ * 深合并语义:部署位 config.yaml 的 true 覆盖 base 的 false(encryptedFields 仍继承 base)。
+ */
+function setEncryptTrue(text) {
+  const lines = text.split('\n');
+  let secIdx = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (/^security:\s*(#.*)?$/.test(lines[i])) { secIdx = i; break; }
+  }
+  if (secIdx === -1) {
+    const block = ['security:', '  encrypt: true'];
+    // 文件尾部空行收敛:避免「末尾多空行 + 追加段」的松散形态
+    while (lines.length && lines[lines.length - 1] === '') lines.pop();
+    return [...lines, ...block, ''].join('\n');
+  }
+  for (let i = secIdx + 1; i < lines.length; i++) {
+    if (/^[^#\s]/.test(lines[i])) break; // 出段(下一个顶层 key)
+    const m = /^(\s*)encrypt\s*:\s*(\S+).*$/.exec(lines[i]);
+    if (m) {
+      lines[i] = `${m[1]}encrypt: true`;
+      return lines.join('\n');
+    }
+  }
+  // 段内无 encrypt 键:插到 security: 行之后(缩进与段内键对齐 = 2 空格)
+  lines.splice(secIdx + 1, 0, '  encrypt: true');
+  return lines.join('\n');
+}
+
+function main() {
+  const [, , cmd, dirArg] = process.argv;
+  if (cmd === 'genkey') {
+    console.log(crypto.randomBytes(KEY_BYTES).toString('base64'));
+    return;
+  }
+  if (cmd !== 'relock' || !dirArg) {
+    fail('用法: CONFIG_SECRET_KEY=<key> node ensure-encrypt.cjs relock <configDir> | node ensure-encrypt.cjs genkey');
+  }
+
+  const rawKey = process.env.CONFIG_SECRET_KEY;
+  if (!rawKey) fail('缺少 CONFIG_SECRET_KEY 环境变量(relock 必带根密钥;genkey 可生成)');
+  let keyBuf;
+  try {
+    keyBuf = Buffer.from(rawKey, 'base64');
+  } catch {
+    fail('密钥不是合法 base64');
+  }
+  if (keyBuf.length !== KEY_BYTES) {
+    fail(`密钥解码后为 ${keyBuf.length} 字节,期望 ${KEY_BYTES} 字节(AES-256)`);
+  }
+
+  const cfgFile = path.join(dirArg, 'config.yaml');
+  if (!fs.existsSync(cfgFile)) fail(`缺 ${cfgFile}(部署位配置未播种;先跑顶层 install.sh)`);
+  const fields = readFields(path.join(dirArg, 'config.base.yaml'));
+  const text = fs.readFileSync(cfgFile, 'utf8');
+
+  // 1) 既有 ENC(...) 密文全量校验(密钥错配在此暴露,而不是服务起不来才发现)
+  for (const enc of text.match(/ENC\([^)]*\)/g) || []) {
+    try {
+      decryptValue(enc, keyBuf);
+    } catch {
+      fail(`既有密文 ${enc} 用当前根密钥解不开(密钥错配或密文损坏)。` +
+        `核对 $APP_ROOT/.prod.secrets 的 CONFIG_SECRET_KEY 与加密该值的密钥是否同把(排障:scripts/config-crypt.cjs decrypt)`);
+    }
+  }
+
+  // 2) 清单内非空明文就地加密 → 3) security.encrypt 置 true
+  const [rewritten, encryptedPaths] = rewriteYaml(text, fields, keyBuf);
+  const finalText = setEncryptTrue(rewritten);
+  if (finalText !== text) fs.writeFileSync(cfgFile, finalText);
+
+  if (encryptedPaths.length) {
+    console.log(`✓ 已就地加密 ${encryptedPaths.length} 项:${encryptedPaths.join(', ')}(IV 随机,同明文每次密文不同)`);
+  } else {
+    console.log('✓ 无非空明文敏感值,密文无需更新');
+  }
+  console.log('✓ security.encrypt 已置 true(防呆校验开启:手改明文需重跑 ./install.sh 自动加密)');
+}
+
+main();