@sema-agent/server 7.146.0 → 7.148.0

package/deploy/sema-up/cluster-up.sh

@@ -12,7 +12,7 @@
 #   MODEL_GATEWAY_BASEURL MODEL_ID MODEL_API_KEY
 #   ALLOW_SMALL_CLUSTER=true 放行 <3 机(dev/CI 单节点验流程;生产必须 >=3 奇数)
 set -euo pipefail
-# >>> 自身目录(五个入口逐字同一段)
+# [[[ 自身目录(五个入口逐字同一段)
 # HERE = 本脚本**真实文件**所在目录。经 npm bin 软链(node_modules/.bin/sema-up)调用时 $0 是软链路径,
 # 按它的目录找 lib/ 会落进 .bin/ ⇒ 逐跳解软链。只用不带参数的 readlink(macOS 自带 bash 3.2 / BSD readlink 没有 -f)。
 # 库要在知道 HERE 之后才找得到,所以这段不能收进库里:五个入口各持同一段,逐字一致由测试判。
@@ -24,7 +24,7 @@ while [ -L "$_self" ]; do
 done
 HERE="$(cd "$(dirname "$_self")" && pwd)"
 unset _self _hops _dir
-# <<< 自身目录
+# ]]] 自身目录
 # `.env` 的文法与全部读写原语只在 lib/envf.sh 定义:本脚本不再有自己的 setk / `. "$ENVF"`。
 . "$HERE/lib/envf.sh"
 # 「壳怎么接这台引擎」的渲染(sema-up.sh / kube-up.sh 同一只)。
@@ -35,6 +35,8 @@ unset _self _hops _dir
 . "$HERE/lib/health.sh"
 # 对象存储桶的唯一表(sema-up.sh / kube-up.sh / smoke.sh 同读这一张)。
 . "$HERE/lib/buckets.sh"
+# 跑图表的共用读法:只打 helm 输出里的 NOTES 段(kube-up.sh 同一只)。
+. "$HERE/lib/chart-run.sh"
 log() { printf '[cluster-up] %s\n' "$*" >&2; }
 die() { log "⛔ $*"; exit 1; }
 
@@ -87,24 +89,25 @@ mscp() { # mscp <i> <local> <remote>
 rsudo() { local i="$1"; shift; if [ "$(mvar "$i" USER)" = "root" ]; then mssh "$i" bash -s -- "$@"; else mssh "$i" sudo bash -s -- "$@"; fi; }
 # 远端单命令(stdin 归命令用,如 kubectl apply -f -)
 rrun() { local i="$1"; shift; if [ "$(mvar "$i" USER)" = "root" ]; then mssh "$i" "$@"; else mssh "$i" sudo "$@"; fi; }
+# 远端要跑的脚本有两种来路,都不用 here-document / here-string(正文超过管道缓冲时,先写后 fork 的写法会在管道配额吃紧的机器上永远写不完):
+#   · 全静态的正文 ⇒ 仓内文件 lib/remote/*.sh,`rsudo N < "$HERE/lib/remote/….sh"`(stdin 直接是文件,没有管道);要传给远端 $1… 的值放在 N 后面;
+#   · 要展开本地变量的正文 ⇒ `rsudo_text N "<双引号串>"`:文本(第 2 个参数)与改前展开后的字节相同,经 stdin 喂 `bash -s`。
+#     文本是 shell 函数的参数、printf 是内建,所以口令(如 k3s token)既不落盘也不进任何进程的命令行;用进程替换而不是管道,rc 只取 rsudo 的。
+rsudo_text() { local i="$1" t="$2"; shift 2; rsudo "$i" "$@" < <(printf '%s' "$t"); }
 
 # ── 0. 互达 + sudo + 硬件预检(在目标机上,§3d-2:错误带原因+建议)+ hostname 告警 ──
 log "0/8 机器预检($MACHINE_COUNT 台)"
 declare -a SYS_HOSTNAMES=()
 for ((i=0; i<MACHINE_COUNT; i++)); do
-  out=$(rsudo "$i" <<'EOF'
-set -e
-command -v curl >/dev/null || { echo "FAIL curl 缺失——建议:apt-get install -y curl"; exit 1; }
-[ "$(uname -m)" = "x86_64" ] || [ "$(uname -m)" = "aarch64" ] || { echo "FAIL 架构 $(uname -m) 不支持——建议:x86_64/aarch64 机器"; exit 1; }
-ram=$(awk '/MemTotal/{printf "%d", $2/1024}' /proc/meminfo)
-[ "$ram" -ge 8192 ] || { echo "FAIL 内存 ${ram}MB < 8G——建议:full-cluster 节点至少 8G(数据面+沙箱同机)"; exit 1; }
-disk=$(df -m / | awk 'NR==2{print $4}')
-[ "$disk" -ge 40960 ] || { echo "FAIL 根盘可用 ${disk}MB < 40G——建议:Longhorn/镜像要空间,清盘或换机"; exit 1; }
-[ -e /dev/kvm ] || echo "WARN 无 /dev/kvm——kata VM 沙箱在本节点不可用(建议:开嵌套虚拟化/裸机;或全集群改 e2b lane)"
-hostname
-EOF
-  ) || die "机器 $i($(mvar "$i" HOST))预检失败:${out:-ssh/sudo 不通——需要 key 互信 + passwordless sudo}"
-  case "$out" in *WARN*) log "  ⚠ $(mvar "$i" HOST):${out%%$'\n'*}" ;; esac
+  out=$(rsudo "$i" < "$HERE/lib/remote/machine-precheck.sh") || die "机器 $i($(mvar "$i" HOST))预检失败:${out:-ssh/sudo 不通——需要 key 互信 + passwordless sudo}"
+  # 每条 WARN 行都打(预检可能告不止一件:无 /dev/kvm、无 NFS 客户端……);末行是 hostname
+  _rest="$out"
+  while [ -n "$_rest" ]; do
+    _line="${_rest%%$'\n'*}"
+    case "$_line" in WARN*) log "  ⚠ $(mvar "$i" HOST):$_line" ;; esac
+    [ "$_rest" = "$_line" ] && break
+    _rest="${_rest#*$'\n'}"
+  done
   SYS_HOSTNAMES+=("$(printf '%s\n' "$out" | tail -1)")
 done
 if [ "$(printf '%s\n' "${SYS_HOSTNAMES[@]}" | sort -u | wc -l)" -lt "$MACHINE_COUNT" ]; then
@@ -113,12 +116,7 @@ fi
 
 # region=auto:从目标机(不是操作员机)探测网络亲和
 if [ "$REGION" = "auto" ]; then
-  REGION=$(rsudo 0 <<'EOF'
-a=$(curl -m3 -so /dev/null -w '%{time_total}' https://mirrors.aliyun.com 2>/dev/null || echo 99)
-b=$(curl -m3 -so /dev/null -w '%{time_total}' https://registry.npmjs.org 2>/dev/null || echo 99)
-awk -v a="$a" -v b="$b" 'BEGIN{print (a<b)?"cn":"global"}'
-EOF
-  )
+  REGION=$(rsudo 0 < "$HERE/lib/remote/region-probe.sh")
   log "region=auto → $REGION(目标机探测)"
 fi
 
@@ -139,81 +137,58 @@ node_flags() { # node_flags <i> → 该机的 k3s server 通用 flag(字段已
 }
 K3S0_IP="$(mvar 0 PRIVATE_IP)"; [ -z "$K3S0_IP" ] && K3S0_IP="$(mvar 0 HOST)"
 
-if rsudo 0 <<<'test -f /usr/local/bin/k3s && systemctl is-active --quiet k3s' 2>/dev/null; then
+if rsudo_text 0 'test -f /usr/local/bin/k3s && systemctl is-active --quiet k3s'$'\n' 2>/dev/null; then
   log "1/8 k3s 首节点已在跑,跳过安装"
 else
   log "1/8 k3s 首节点($(mvar 0 NAME) @ $(mvar 0 HOST))"
-  rsudo 0 <<EOF
-set -e
+  rsudo_text 0 "set -e
 curl -sfL https://get.k3s.io | $(k3s_install_env)INSTALL_K3S_CHANNEL=$K3S_CHANNEL \
-  INSTALL_K3S_EXEC="server --cluster-init $(node_flags 0)" sh -
-EOF
+  INSTALL_K3S_EXEC=\"server --cluster-init $(node_flags 0)\" sh -
+"
 fi
-TOKEN="$(rsudo 0 <<<'cat /var/lib/rancher/k3s/server/node-token')" || die "读不到 k3s node-token"
+TOKEN="$(rsudo_text 0 'cat /var/lib/rancher/k3s/server/node-token'$'\n')" || die "读不到 k3s node-token"
 for ((i=1; i<MACHINE_COUNT; i++)); do
-  if rsudo "$i" <<<'test -f /usr/local/bin/k3s && systemctl is-active --quiet k3s' 2>/dev/null; then
+  if rsudo_text "$i" 'test -f /usr/local/bin/k3s && systemctl is-active --quiet k3s'$'\n' 2>/dev/null; then
     # 活着 ≠ 属于本集群:被复用的机器可能挂在别的集群上,静默跳过=幽灵成员
-    if rsudo 0 <<<"k3s kubectl get node $(mvar "$i" NAME) --no-headers >/dev/null 2>&1"; then
+    if rsudo_text 0 "k3s kubectl get node $(mvar "$i" NAME) --no-headers >/dev/null 2>&1"$'\n'; then
       log "1/8 节点 $(mvar "$i" NAME) 已是本集群成员,跳过"
       continue
     fi
     die "机器 $(mvar "$i" HOST) 上 k3s 在跑但不是本集群成员($(mvar "$i" NAME) 不在)——先在该机跑 k3s-uninstall.sh 再重来"
   fi
   log "1/8 加入节点 $(mvar "$i" NAME) @ $(mvar "$i" HOST)"
-  rsudo "$i" <<EOF
-set -e
+  rsudo_text "$i" "set -e
 curl -sfL https://get.k3s.io | $(k3s_install_env)INSTALL_K3S_CHANNEL=$K3S_CHANNEL \
-  K3S_TOKEN='$TOKEN' INSTALL_K3S_EXEC="server --server https://$K3S0_IP:6443 $(node_flags "$i")" sh -
-EOF
+  K3S_TOKEN='$TOKEN' INSTALL_K3S_EXEC=\"server --server https://$K3S0_IP:6443 $(node_flags "$i")\" sh -
+"
 done
 # Ready 等待(embedded etcd 首次选主可能要 ~1min)
-rsudo 0 <<EOF || die "k3s 节点未全 Ready"
-set -e
+rsudo_text 0 "set -e
 for t in \$(seq 1 60); do
   n=\$(k3s kubectl get nodes --no-headers 2>/dev/null | grep -cw Ready || true)
-  [ "\$n" -ge "$MACHINE_COUNT" ] && { k3s kubectl get nodes -o wide; exit 0; }
+  [ \"\$n\" -ge \"$MACHINE_COUNT\" ] && { k3s kubectl get nodes -o wide; exit 0; }
   sleep 5
 done
 k3s kubectl get nodes -o wide; exit 1
-EOF
+" || die "k3s 节点未全 Ready"
 
 # ── 2. VXLAN 守卫(有公网口的机器:flannel 8472 只许私网,公网口 DROP;systemd 常驻,
 #      k3s 重装会重置 iptables——unit 常驻保证 reboot/重装后规则还在)────────────────
 log "2/8 VXLAN 公网口守卫"
 for ((i=0; i<MACHINE_COUNT; i++)); do
   iface="$(mvar "$i" PUBLIC_IFACE)"; [ -z "$iface" ] && continue
-  rsudo "$i" <<EOF
-set -e
-cat > /etc/systemd/system/sema-vxlan-guard.service <<'UNIT'
-[Unit]
-Description=Drop flannel VXLAN on public iface (sema isolation invariant)
-After=network-online.target k3s.service
-[Service]
-Type=oneshot
-RemainAfterExit=yes
-ExecStart=/bin/sh -c 'iptables -C INPUT -i $iface -p udp --dport 8472 -j DROP 2>/dev/null || iptables -I INPUT -i $iface -p udp --dport 8472 -j DROP'
-[Install]
-WantedBy=multi-user.target
-UNIT
-systemctl daemon-reload && systemctl enable --now sema-vxlan-guard.service
-iptables -C INPUT -i $iface -p udp --dport 8472 -j DROP
-EOF
+  rsudo "$i" "$iface" < "$HERE/lib/remote/vxlan-guard.sh"
   log "  $(mvar "$i" NAME):8472/udp DROP on $iface ✓"
 done
 
 # ── 3. helm(装配工具,仅首节点)────────────────────────────────────────────────
 log "3/8 helm + 基础组件"
-rsudo 0 <<'EOF'
-set -e
-command -v helm >/dev/null && exit 0
-curl -fsSL https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash >/dev/null
-EOF
+rsudo 0 < "$HERE/lib/remote/helm-install.sh"
 KC="--kubeconfig /etc/rancher/k3s/k3s.yaml"
 
 # Longhorn(分布式存储;replica 数=min(机器数,2)——RAID1 之上跨机冗余)
 LH_REPLICAS=$(( MACHINE_COUNT < 2 ? 1 : 2 ))
-rsudo 0 <<EOF
-set -e
+rsudo_text 0 "set -e
 if ! k3s kubectl get storageclass longhorn >/dev/null 2>&1; then
   helm $KC repo add longhorn https://charts.longhorn.io >/dev/null
   helm $KC repo update >/dev/null
@@ -224,40 +199,38 @@ if ! k3s kubectl get storageclass longhorn >/dev/null 2>&1; then
     --set persistence.defaultClassReplicaCount=$LH_REPLICAS --wait --timeout 10m >/dev/null
 fi
 # longhorn=默认 SC,local-path 摘掉 default 标(两个 default 会让 PVC 行为不定)
-k3s kubectl patch storageclass local-path -p '{"metadata":{"annotations":{"storageclass.kubernetes.io/is-default-class":"false"}}}' >/dev/null 2>&1 || true
-k3s kubectl patch storageclass longhorn -p '{"metadata":{"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}' >/dev/null
+k3s kubectl patch storageclass local-path -p '{\"metadata\":{\"annotations\":{\"storageclass.kubernetes.io/is-default-class\":\"false\"}}}' >/dev/null 2>&1 || true
+k3s kubectl patch storageclass longhorn -p '{\"metadata\":{\"annotations\":{\"storageclass.kubernetes.io/is-default-class\":\"true\"}}}' >/dev/null
 echo LONGHORN_OK
-EOF
+"
 
 # kata-deploy(官方 helm chart;kustomize remote base 老路径已失效——真踩)
 log "4/8 kata-deploy(VM 沙箱运行时)"
-rsudo 0 <<EOF
-set -e
+rsudo_text 0 "set -e
 k3s kubectl get runtimeclass kata-qemu >/dev/null 2>&1 && { echo KATA_ALREADY; exit 0; }
 helm $KC upgrade --install kata-deploy oci://ghcr.io/kata-containers/kata-deploy-charts/kata-deploy \
   --version $KATA_VERSION --namespace kube-system --set k8sDistribution=k3s --wait --timeout 10m >/dev/null
 for t in \$(seq 1 36); do k3s kubectl get runtimeclass kata-qemu >/dev/null 2>&1 && break; sleep 5; done
 k3s kubectl get runtimeclass kata-qemu >/dev/null
 echo KATA_OK
-EOF
+"
 
 # CNPG operator(钉 $CNPG_VERSION)
 log "5/8 CNPG operator $CNPG_VERSION"
-rsudo 0 <<EOF
-set -e
+rsudo_text 0 "set -e
 if ! k3s kubectl get deployment -n cnpg-system cnpg-controller-manager >/dev/null 2>&1; then
-  # 组件刚装完 apiserver 聚合 openapi 可能未就绪(瞬时 "unable to handle the request")——重试非降级
+  # 组件刚装完 apiserver 聚合 openapi 可能未就绪(瞬时 \"unable to handle the request\")——重试非降级
   ok=0
   for t in 1 2 3 4 5; do
     k3s kubectl apply --server-side -f \
-      "https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/release-${CNPG_VERSION%.*}/releases/cnpg-$CNPG_VERSION.yaml" >/dev/null && { ok=1; break; }
+      \"https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/release-${CNPG_VERSION%.*}/releases/cnpg-$CNPG_VERSION.yaml\" >/dev/null && { ok=1; break; }
     sleep 15
   done
-  [ "\$ok" = 1 ] || { echo "CNPG manifest apply 重试耗尽" >&2; exit 1; }
+  [ \"\$ok\" = 1 ] || { echo \"CNPG manifest apply 重试耗尽\" >&2; exit 1; }
 fi
 k3s kubectl rollout status deployment/cnpg-controller-manager -n cnpg-system --timeout=300s >/dev/null
 echo CNPG_OK
-EOF
+"
 
 # ── 6. server 镜像:registry 引用 or tar 预灌 ─────────────────────────────────────
 log "6/8 server 镜像"
@@ -272,14 +245,7 @@ elif [ -n "${SEMA_SERVER_IMAGE_TAR:-}" ]; then
     # ⚠ 每台都灌,包括"看起来已有"的——k3s-uninstall 重装过的节点镜像会被清(复审真抓)
     log "  预灌 $(mvar "$i" NAME) …"
     mscp "$i" "$SEMA_SERVER_IMAGE_TAR" /tmp/sema-server-image.tar.upload
-    rsudo "$i" <<'EOF'
-set -e
-trap 'rm -f /tmp/sema-server-image.tar.upload /tmp/sema-server-image.tar' EXIT
-f=/tmp/sema-server-image.tar.upload
-case "$(head -c2 "$f" | od -An -tx1 | tr -d ' ')" in 1f8b) gunzip -c "$f" > /tmp/sema-server-image.tar && f=/tmp/sema-server-image.tar ;; esac
-k3s ctr images import "$f" >/dev/null
-k3s ctr images ls | grep -q sema-server
-EOF
+    rsudo "$i" < "$HERE/lib/remote/image-import.sh"
   done
 else
   die "需要 SEMA_SERVER_IMAGE(registry 引用)或 SEMA_SERVER_IMAGE_TAR(docker save 包)之一"
@@ -305,22 +271,12 @@ if [ -n "${IMAGE_PULL_USER:-}" ] && [ -n "${IMAGE_PULL_TOKEN:-}" ]; then
       rrun 0 k3s kubectl annotate ns "$ns" meta.helm.sh/release-name=sema-stack meta.helm.sh/release-namespace=sema --overwrite >/dev/null
     fi
     IPS_NS="$ns" IPS_REG="${IMAGE_PULL_REGISTRY:-https://index.docker.io/v1/}" \
-    IPS_USER="$IMAGE_PULL_USER" IPS_TOKEN="$IMAGE_PULL_TOKEN" python3 - <<'PY' | rrun 0 k3s kubectl apply -f - >/dev/null
-import base64, json, os
-u, p = os.environ["IPS_USER"], os.environ["IPS_TOKEN"]
-cfg = {"auths": {os.environ["IPS_REG"]: {"username": u, "password": p,
-       "auth": base64.b64encode(f"{u}:{p}".encode()).decode()}}}
-b64 = base64.b64encode(json.dumps(cfg).encode()).decode()
-print(json.dumps({"apiVersion": "v1", "kind": "Secret", "type": "kubernetes.io/dockerconfigjson",
-      "metadata": {"name": "sema-regcred", "namespace": os.environ["IPS_NS"]},
-      "data": {".dockerconfigjson": b64}}))
-PY
+    IPS_USER="$IMAGE_PULL_USER" IPS_TOKEN="$IMAGE_PULL_TOKEN" python3 - < "$HERE/lib/regcred.py" | rrun 0 k3s kubectl apply -f - >/dev/null
     # default SA 由 ns 控制器异步建——等它出现再 patch(幂等)
-    rsudo 0 <<EOF
-set -e
+    rsudo_text 0 "set -e
 for t in \$(seq 1 12); do k3s kubectl get sa default -n $ns >/dev/null 2>&1 && break; sleep 5; done
-k3s kubectl patch sa default -n $ns -p '{"imagePullSecrets":[{"name":"sema-regcred"}]}' >/dev/null
-EOF
+k3s kubectl patch sa default -n $ns -p '{\"imagePullSecrets\":[{\"name\":\"sema-regcred\"}]}' >/dev/null
+"
   done
 elif [ -n "${IMAGE_PULL_USER:-}${IMAGE_PULL_TOKEN:-}" ]; then
   die "IMAGE_PULL_USER/IMAGE_PULL_TOKEN 只给了一个——两个都要(或都不给=公共镜像)"
@@ -360,33 +316,16 @@ if [ "$STACK_ENGINE" = "helm" ]; then
     V_PKG_SOURCE="$([ "$REGION" = "global" ] && echo global || echo '')" \
     V_PG_INSTANCES="$PG_INSTANCES" V_PG_AA="$PG_AA" V_REPLICAS="$SERVER_REPLICAS" \
     V_REQ_PRINCIPAL="$(principal_of_users "$USERS")" \
-    python3 - > "$VALSF" <<'PY'
-import json, os
-e = os.environ
-# json 是合法 yaml;json.dumps 对任意凭据字符安全(引号/反斜杠/换行都正确转义)
-print(json.dumps({
-  "pg": {"instances": int(e["V_PG_INSTANCES"]), "antiAffinity": e["V_PG_AA"]},
-  "minio": {"rootPassword": e["V_MINIO_PW"]},
-  "server": {
-    "image": e["V_SERVER_IMAGE"], "pullPolicy": e["V_PULL_POLICY"],
-    "replicas": int(e["V_REPLICAS"]), "serviceAuthToken": e["V_SVC_TOKEN"],
-    "modelGatewayBaseurl": e["V_MODEL_GATEWAY"], "modelId": e["V_MODEL_ID"],
-    "modelApiKey": e["V_MODEL_KEY"], "sandboxPkgSource": e["V_PKG_SOURCE"],
-    "requirePrincipal": e["V_REQ_PRINCIPAL"],
-  },
-  # chart 0.3.0 起 registry.enabled 默认 true(单机档语义)——machines 多机路径的 registry/git
-  # 面还没接线,必须显式关,不然 helm 撞 registry.image required(2026-07-12 自查)
-  "registry": {"enabled": False},
-  "gitea": {"enabled": False},
-}))
-PY
+    python3 - > "$VALSF" < "$HERE/lib/helm-values-cluster.py"
   )
   [ -s "$VALSF" ] || die "helm values 生成失败"
-  # 失败也删 values 文件(die 在 rm 之前退出会把含 MODEL_API_KEY 的 0600 文件留在 WORK)
-  rrun 0 helm --kubeconfig /etc/rancher/k3s/k3s.yaml upgrade --install sema-stack \
-    /tmp/sema-stack-chart/chart -n sema --create-namespace -f - < "$VALSF" >/dev/null \
+  # 失败也删 values 文件(die 在 rm 之前退出会把含 MODEL_API_KEY 的 0600 文件留在 WORK)。
+  # helm 的 stdout 收进变量,只把图表 NOTES 段打进日志(lib/chart-run.sh helm_notes:开着调试时 stdout 还有 values / 渲出的 Secret,那些不打)。
+  _helm_out=$(rrun 0 helm --kubeconfig /etc/rancher/k3s/k3s.yaml upgrade --install sema-stack \
+    /tmp/sema-stack-chart/chart -n sema --create-namespace -f - < "$VALSF") \
     || { rm -f "$VALSF"; die "helm upgrade --install sema-stack 失败"; }
   rm -f "$VALSF"
+  helm_notes "$_helm_out" >&2
   rrun 0 rm -rf /tmp/sema-stack-chart
 else
 RENDERED="$WORK/sema-stack-cluster.rendered.yaml"
@@ -399,77 +338,37 @@ RENDERED="$WORK/sema-stack-cluster.rendered.yaml"
   R_PKG_SOURCE="$([ "$REGION" = "global" ] && echo global || echo '')" \
   R_PG_INSTANCES="$PG_INSTANCES" R_PG_AA="$PG_AA" R_REPLICAS="$SERVER_REPLICAS" \
   R_REQ_PRINCIPAL="$(principal_of_users "$USERS")" \
-  python3 - "$HERE/stack/sema-stack-cluster.yaml" > "$RENDERED" <<'PY'
-import os, sys
-MAP = {"__MINIO_PW__":"R_MINIO_PW", "__SVC_TOKEN__":"R_SVC_TOKEN", "__MODEL_KEY__":"R_MODEL_KEY",
-       "__MODEL_GATEWAY__":"R_MODEL_GATEWAY", "__MODEL_ID__":"R_MODEL_ID",
-       "__SERVER_IMAGE__":"R_SERVER_IMAGE", "__SERVER_PULL_POLICY__":"R_PULL_POLICY",
-       "__PKG_SOURCE__":"R_PKG_SOURCE", "__PG_INSTANCES__":"R_PG_INSTANCES",
-       "__PG_ANTI_AFFINITY__":"R_PG_AA", "__SERVER_REPLICAS__":"R_REPLICAS",
-       "__REQUIRE_PRINCIPAL__":"R_REQ_PRINCIPAL"}
-t = open(sys.argv[1], encoding="utf-8").read()
-for ph, env in MAP.items():
-    v = os.environ.get(env)
-    if v is None: raise SystemExit(f"渲染缺 {env}({ph})")
-    if any(c in v for c in "\n\"\\"): raise SystemExit(f"{env} 含 YAML 危险字符(换行/引号/反斜杠)")
-    t = t.replace(ph, v)
-import re
-left = sorted(set(re.findall(r"__[A-Z_]+__", t)))
-if left: raise SystemExit(f"未渲染占位符残留: {left}")
-sys.stdout.write(t)
-PY
+  R_OPERATOR_SINGLE_USER="$(operator_single_user_of_users "$USERS")" \
+  python3 - "$HERE/stack/sema-stack-cluster.yaml" > "$RENDERED" < "$HERE/lib/render-stack.py"
 )
 [ -s "$RENDERED" ] || die "sema-stack 渲染失败"
 # 凭据清单经 stdin 直接 apply,不落远端盘(落 /tmp 失败时会残留)
 rrun 0 k3s kubectl apply -f - < "$RENDERED" >/dev/null
+# 与 helm 路径的图表 NOTES 同一组事实(本清单不经 helm,NOTES 由这里说):钥匙卷是 ReadWriteMany(本清单副本数恒 > 1),Longhorn 的 RWX 要节点上的 NFS 客户端。
+log "  停驻封签钥匙:引擎的钥匙保管目录在持久卷 sema-server-sealed-key(ReadWriteMany,longhorn;每个节点要装 NFS 客户端,server Pod 挂不上卷就是缺它),重启与换副本都不丢钥匙"
 fi
-rsudo 0 $(buckets_prefixed local/ $(buckets_k8s)) <<'EOF'
-set -e
-BUCKETS=("$@")   # 要建的桶(local/<桶>):清单只在 lib/buckets.sh 一处,经位置参数递给远端
-# runner token 跨 ns 复制要赶在 server 起 pod 前(晚了=CreateContainerConfigError 干等——真踩);
-# SA token secret 由控制器异步填充,先等它有值
-TOK=""
-for t in $(seq 1 24); do
-  TOK=$(k3s kubectl get secret sema-runner-token -n sema-sandbox -o jsonpath='{.data.token}' 2>/dev/null || true)
-  [ -n "$TOK" ] && break; sleep 5
-done
-[ -n "$TOK" ] || { echo "sema-runner-token 未被控制器填充" >&2; exit 1; }
-k3s kubectl create secret generic sema-runner-token-copy -n sema --from-literal=token="$(printf '%s' "$TOK" | base64 -d)" \
-  --dry-run=client -o yaml | k3s kubectl apply -f - >/dev/null
-# MinIO 建桶(备份桶+引擎桶)—— 排在等 PG healthy 与等 server rollout **之前**:引擎起服会核快照桶在不在,桶缺时 server 不就绪、rollout 永远等不到,而建桶又排在它后面 ⇒ 互等;
-# MinIO 不依赖 PG,建桶也就不必陪着等 PG(冷启拉镜像 + init 可要几分钟,会把引擎的等桶窗耗掉)
-k3s kubectl rollout status deployment/sema-minio -n sema --timeout=300s >/dev/null
-PW=$(k3s kubectl get secret sema-minio -n sema -o jsonpath='{.data.rootPassword}' | base64 -d)
-k3s kubectl exec deploy/sema-minio -n sema -- sh -c \
-  "mc alias set local http://localhost:9000 sema '$PW' >/dev/null && mc mb --ignore-existing ${BUCKETS[*]}" >/dev/null
-# PG healthy(冷启拉镜像+init 可要几分钟)
-for t in $(seq 1 120); do
-  s=$(k3s kubectl get cluster sema-pg -n sema -o jsonpath='{.status.phase}' 2>/dev/null || true)
-  [ "$s" = "Cluster in healthy state" ] && break; sleep 5
-done
-[ "$s" = "Cluster in healthy state" ] || { k3s kubectl get cluster -n sema; echo "PG 未达 healthy" >&2; exit 1; }
-k3s kubectl rollout status deployment/sema-server -n sema --timeout=300s >/dev/null
-echo STACK_OK
-EOF
+rsudo 0 $(buckets_prefixed local/ $(buckets_k8s)) < "$HERE/lib/remote/stack-ready.sh"
 
 # ── 8. smoke(节点内经 NodePort;外网入口=LB 在云商侧配,打印指引)────────────────
 log "8/8 smoke"
 # NodePort 被 nodeport-addresses 钉在节点网段——loopback 不在其内,必须打 node-ip(真踩 curl exit 7)
 # 第一行 = 两个 HTTP 码,其后 = /health 体(后端位在里面:200 + 401 测不出「服务在内存里跑」,验收必须读那一位)
-SMOKE_OUT=$(rsudo 0 <<EOF
-HB=\$(curl -m5 -s -w '\n%{http_code}' "http://$K3S0_IP:$NODEPORT/health" || printf '\n000')
-H="\${HB##*\$'\n'}"
-A=\$(curl -m5 -s -o /dev/null -w '%{http_code}' "http://$K3S0_IP:$NODEPORT/v1/runs" || echo 000)
-echo "health=\$H auth=\$A"
-printf '%s' "\${HB%\$'\n'*}"
-EOF
-)
+# /health 带服务凭据读(配了服务凭据的引擎只对出示凭据的读者给后端位 / 持久性):凭据经 stdin 喂 curl 的 `-K -` 配置,不进远端任何进程的 argv。
+# 值是数据不是代码:curl 配置行由 lib/health.sh 的 health_curl_config 按配置文法转义,再整行过 `printf '%q'` 才进远端 shell 文本。
+_health_cfg="$(health_curl_config "$SERVICE_AUTH_TOKEN")" || die "SERVICE_AUTH_TOKEN 含控制字符 —— 那不是能放进 Authorization 头的凭据;检查 $ENVF"
+_health_cfg_q="$(printf '%q' "$_health_cfg")"
+SMOKE_OUT=$(rsudo_text 0 "CFG=$_health_cfg_q
+HB=\$(printf '%s\n' \"\$CFG\" | curl -K - -m5 -s -w '\n%{http_code}' \"http://$K3S0_IP:$NODEPORT/health\" || printf '\n000')
+H=\"\${HB##*\$'\n'}\"
+A=\$(curl -m5 -s -o /dev/null -w '%{http_code}' \"http://$K3S0_IP:$NODEPORT/v1/runs\" || echo 000)
+echo \"health=\$H auth=\$A\"
+printf '%s' \"\${HB%\$'\n'*}\"
+")
 SMOKE="${SMOKE_OUT%%$'\n'*}"
 case "$SMOKE" in *"health=200 auth=401"*) : ;; *) die "smoke 失败:$SMOKE(期望 health=200 auth=401)" ;; esac
 BK_WHY=$(health_backend_check "${SMOKE_OUT#*$'\n'}") || die "smoke 失败:$BK_WHY。下一步:kubectl -n sema logs deploy/sema-server(引擎在库没连上时不会再退内存起服 —— 它会拒启;读到 memory 多半是旧镜像)"
-log "smoke ✓ $SMOKE backend=$SEMA_UP_EXPECT_SESSION_BACKEND"
-cat >&2 <<EOF
-
+log "smoke ✓ $SMOKE backend=$SEMA_UP_EXPECT_SESSION_BACKEND durability=$(health_store_durability "${SMOKE_OUT#*$'\n'}")${BK_WHY:+ — $BK_WHY}"
+printf '%s' "
 ══════════ cluster-up 完成($MACHINE_COUNT 节点)══════════
  入口   NodePort $NODEPORT(限私网段)。公网入口在云商 LB 上配:
         listener TCP:8090 → pool(每节点 private_ip:$NODEPORT,member 必带 subnet_id——Gcore 真踩)
@@ -478,7 +377,7 @@ cat >&2 <<EOF
  沙箱   kata-qemu runtimeclass(ns sema-sandbox,SA sema-runner)
  凭据   $ENVF(0600;SERVICE_AUTH_TOKEN=API 门)
  管理   ssh 隧道 6443(kubeconfig 在首节点 /etc/rancher/k3s/k3s.yaml,server 改 127.0.0.1)
-EOF
+" >&2
 # 壳对 NodePort / LB 的明文 http 按设计拒连(非回环要 https)⇒ 经 ssh 隧道把首节点的 NodePort 带到本机回环再 connect
 # (NodePort 钉在节点网段、不在节点自己的回环上 —— **转发目标**写节点私网 IP,见上面 smoke 的同一条注;**ssh 目标**是本次部署
 # 连得上的那一台 = machines.yaml 的 HOST / USER / SSH_KEY,与 mssh 同一组,私网 IP 与 HOST 可以不同 —— 车内 codex r1-F4)。

package/deploy/sema-up/kube-up.sh

@@ -13,7 +13,7 @@
 #   MODEL_GATEWAY_BASEURL MODEL_ID MODEL_API_KEY
 #   [NAMESPACE=sema][STORAGE_CLASS=集群默认][CNPG_VERSION]
 set -euo pipefail
-# >>> 自身目录(五个入口逐字同一段)
+# [[[ 自身目录(五个入口逐字同一段)
 # HERE = 本脚本**真实文件**所在目录。经 npm bin 软链(node_modules/.bin/sema-up)调用时 $0 是软链路径,
 # 按它的目录找 lib/ 会落进 .bin/ ⇒ 逐跳解软链。只用不带参数的 readlink(macOS 自带 bash 3.2 / BSD readlink 没有 -f)。
 # 库要在知道 HERE 之后才找得到,所以这段不能收进库里:五个入口各持同一段,逐字一致由测试判。
@@ -25,7 +25,7 @@ while [ -L "$_self" ]; do
 done
 HERE="$(cd "$(dirname "$_self")" && pwd)"
 unset _self _hops _dir
-# <<< 自身目录
+# ]]] 自身目录
 # `.env` 的文法与全部读写原语(envf_get / envf_has / envf_load / envf_put / setk / setk_new / resetk)只在这一处
 # 定义,sema-up.sh / cluster-up.sh / smoke.sh 同源:本脚本不再有自己的 setk / has_env / `. "$ENVF"`。
 . "$HERE/lib/envf.sh"
@@ -39,6 +39,10 @@ unset _self _hops _dir
 . "$HERE/lib/buckets.sh"
 # 集群节点地址的唯一读法(NodePort 入口 + 沙箱出网策略要拒的全部节点地址;同读一份节点表)。
 . "$HERE/lib/node-addrs.sh"
+# 把一段文本按行 / 按词读进变量的三只函数(不用 here-document / here-string)。
+. "$HERE/lib/shell-text.sh"
+# 跑图表的共用读法:只打 helm 输出里的 NOTES 段、钥匙卷的存储类(cluster-up.sh 同一只)。
+. "$HERE/lib/chart-run.sh"
 log() { printf '[kube-up] %s\n' "$*" >&2; }
 die() { log "⛔ $*"; exit 1; }
 
@@ -106,7 +110,9 @@ NODES=$($KUBECTL get nodes --no-headers | grep -cw Ready || true)
 # ── 节点容量测量+建议(建议不强求;某台确实过小才拦)────────────────────────────────
 # allocatable 口径(比 capacity 更接近可用);盘容量 kubectl 不可见,PVC Pending 时按报错查 SC
 NODE_CAPS=$($KUBECTL get nodes -o jsonpath='{range .items[*]}{.metadata.name}{" "}{.status.allocatable.cpu}{" "}{.status.allocatable.memory}{"\n"}{end}' 2>/dev/null)
-while read -r n_name n_cpu n_mem; do
+caps_rest="$NODE_CAPS"$'\n'
+while text_pop_line caps_rest caps_line; do
+  text_words "$caps_line" n_name n_cpu n_mem
   [ -z "$n_name" ] && continue
   # cpu:"4"或"3900m"→ 毫核;memory:"8049856Ki"/"7Gi" → MB
   case "$n_cpu" in *m) n_mcpu="${n_cpu%m}" ;; *) n_mcpu=$(( ${n_cpu:-0} * 1000 )) ;; esac
@@ -121,9 +127,7 @@ while read -r n_name n_cpu n_mem; do
   elif [ "$n_mcpu" -lt 2000 ] || [ "$n_mb" -lt 4096 ]; then
     log "⚠ 节点 $n_name 偏小(${n_mcpu}m CPU / ${n_mb}MB,推荐 ≥2c/4G)——能跑,数据面/沙箱余量紧;建议升配或外接 S3/DB 减负"
   fi
-done <<EOF_NODES
-$NODE_CAPS
-EOF_NODES
+done
 [ "$NODES" -lt 3 ] && log "建议:准生产配置=3 节点(PG 反亲和 HA+副本打散);当前 $NODES 节点能跑,按单机形态缩放(不强求)"
 DEFAULT_SC=$($KUBECTL get storageclass -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.metadata.annotations.storageclass\.kubernetes\.io/is-default-class}{"\n"}{end}' 2>/dev/null | awk -F'\t' '$2=="true"{print $1; exit}')
 STORAGE_CLASS="${STORAGE_CLASS:-}"   # 空=用集群默认 SC;显式给了就用给的
@@ -217,7 +221,7 @@ helm_values() { # helm_values <giteaBaseUrl> <oauthId> <oauthSecret>
   V_MINIO_PW="$MINIO_PASSWORD" V_SVC_TOKEN="$SERVICE_AUTH_TOKEN" V_MODEL_KEY="$MODEL_API_KEY" \
   V_MODEL_GATEWAY="$MODEL_GATEWAY_BASEURL" V_MODEL_ID="$MODEL_ID" \
   V_SERVER_IMAGE="$SEMA_SERVER_IMAGE" V_REPLICAS="$SERVER_REPLICAS" \
-  V_PG_INSTANCES="$PG_INSTANCES" V_PG_AA="$PG_AA" V_SC="$STORAGE_CLASS" \
+  V_PG_INSTANCES="$PG_INSTANCES" V_PG_AA="$PG_AA" V_SC="$STORAGE_CLASS" V_SK_SC="$SEALED_KEY_SC" \
   V_RT_CLASS="$RUNTIME_CLASS" V_REQ_PRINCIPAL="$(principal_of_users "$USERS")" \
   V_PKG_SOURCE="$([ "$REGION" = "global" ] && echo global || echo '')" \
   V_REG_ENABLED="$REGISTRY_ENABLED" V_REG_IMAGE="${SEMA_REGISTRY_IMAGE:-}" \
@@ -225,47 +229,23 @@ helm_values() { # helm_values <giteaBaseUrl> <oauthId> <oauthSecret>
   V_GITEA_ENABLED="$([ "$GIT_MODE" = provision ] && echo true || echo false)" \
   V_GITEA_IMAGE="${GITEA_IMAGE:-gitea/gitea:1.24}" V_NODE_IP="$NODE_IP" V_NODE_CIDRS="$NODE_CIDRS" \
   V_MINIO_IMAGE="${MINIO_IMAGE:-}" \
-  python3 - <<'PY'
-import json, os
-e = os.environ
-# json 是合法 yaml;json.dumps 对任意凭据字符安全(引号/反斜杠/换行都正确转义)
-v = {
-  # helm 的 values 合并是深合并——只给部分 parameters 时 values.yaml 里 3 机 as-built 的
-  # shared_buffers=8GB/effective_cache_size=86GB 会留下来,小集群 PG 直接起不来(内存不够)。
-  # 必须整组显式覆盖成保守值;真按机器规格调优的入口是 STORAGE/PG 显式 values(后续档)。
-  "pg": {"instances": int(e["V_PG_INSTANCES"]), "antiAffinity": e["V_PG_AA"],
-         "storageClass": e["V_SC"], "storageSize": "20Gi",
-         "parameters": {"shared_buffers": "256MB", "effective_cache_size": "1GB",
-                        "maintenance_work_mem": "128MB", "random_page_cost": "1.1",
-                        "effective_io_concurrency": "200", "checkpoint_completion_target": "0.9",
-                        "max_parallel_workers": "2"}},
-  "minio": {"rootPassword": e["V_MINIO_PW"], "storageClass": e["V_SC"], "storageSize": "20Gi"},
-  "server": {
-    "image": e["V_SERVER_IMAGE"], "replicas": int(e["V_REPLICAS"]),
-    "serviceAuthToken": e["V_SVC_TOKEN"], "modelGatewayBaseurl": e["V_MODEL_GATEWAY"],
-    "modelId": e["V_MODEL_ID"], "modelApiKey": e["V_MODEL_KEY"],
-    "sandboxPkgSource": e["V_PKG_SOURCE"], "requirePrincipal": e["V_REQ_PRINCIPAL"],
-  },
-  "sandbox": {"runtimeClass": e["V_RT_CLASS"],
-              "networkPolicy": {"nodeCidrs": json.loads(e["V_NODE_CIDRS"])}},
-  "registry": {"enabled": e["V_REG_ENABLED"] == "true", "image": e["V_REG_IMAGE"],
-               "storageClass": e["V_SC"], "adminPassword": e["V_REG_PW"],
-               "sessionSecret": e["V_REG_SS"], "pullToken": e["V_REG_PT"],
-               "giteaBaseUrl": e["V_GITEA_URL"], "giteaOauthClientId": e["V_OA_ID"],
-               "giteaOauthClientSecret": e["V_OA_SECRET"]},
-  "gitea": {"enabled": e["V_GITEA_ENABLED"] == "true", "image": e["V_GITEA_IMAGE"],
-            "storageClass": e["V_SC"], "domain": e["V_NODE_IP"]},
-}
-# MinIO 镜像:给了才递(默认只在 chart values.yaml 写一处,不在脚本里再抄一份);国内源 = 整条引用
-if e["V_MINIO_IMAGE"]: v["minio"]["image"] = e["V_MINIO_IMAGE"]
-print(json.dumps(v))
-PY
+  python3 - < "$HERE/lib/helm-values-kube.py"
 }
 helm_apply() { # helm_apply <giteaBaseUrl> <oauthId> <oauthSecret>
-  helm_values "$1" "$2" "$3" | helm upgrade --install sema-stack "$HERE/chart" \
-    -n "$NAMESPACE" --create-namespace -f - >/dev/null \
+  # helm 的 stdout 收进变量,只把图表 NOTES 段打进日志(lib/chart-run.sh helm_notes:开着调试时 stdout 还有 values / 渲出的 Secret,那些不打)。
+  local out
+  out=$(helm_values "$1" "$2" "$3" | helm upgrade --install sema-stack "$HERE/chart" \
+    -n "$NAMESPACE" --create-namespace -f -) \
     || die "helm upgrade --install sema-stack 失败。下一步:helm -n $NAMESPACE status sema-stack;kubectl -n $NAMESPACE get events --sort-by=.lastTimestamp | tail"
+  helm_notes "$out" >&2
 }
+# 钥匙卷的存储类(lib/chart-run.sh sealed_key_class):卷已在 ⇒ 它建好时的类(不可改);新建 ⇒ STORAGE_CLASS。读不到(API 错)⇒ 停,不猜。
+_sk_reading=$($KUBECTL get pvc sema-server-sealed-key -n "$NAMESPACE" --ignore-not-found -o jsonpath='{.metadata.name}/{.spec.storageClassName}') \
+  || die "读不到钥匙卷 PVC sema-server-sealed-key 的现状(-n $NAMESPACE)。下一步:kubectl -n $NAMESPACE get pvc 手查权限 / 连通"
+SEALED_KEY_SC="$(sealed_key_class "$_sk_reading" "$STORAGE_CLASS")" || exit 1
+if [ -n "$_sk_reading" ] && [ -n "$STORAGE_CLASS" ] && [ "$SEALED_KEY_SC" != "$STORAGE_CLASS" ]; then
+  log "钥匙卷 sema-server-sealed-key 已在存储类「${SEALED_KEY_SC:-<无>}」(建好后不可改)—— STORAGE_CLASS=$STORAGE_CLASS 不用于它"
+fi
 log "2/6 helm 装配 sema-stack(-n $NAMESPACE,pg×$PG_INSTANCES server×$SERVER_REPLICAS registry=$REGISTRY_ENABLED gitea=$([ "$GIT_MODE" = provision ] && echo true || echo false))"
 # git 目标的解析 + OAuth 接线的锚校验,都排在读 OA_* 之前。
 # ① connect 的目标:**显式输入优先**;这次没给就沿用上次登记的连接(经严格读口;本脚本支持单独重跑,v7.97.0 靠
@@ -394,21 +374,21 @@ fi
 
 # ── smoke(port-forward 直验——kind/远程 kubeconfig 下 NodePort 对本机不可达,别靠它)──
 log "5/6 smoke"
-smoke_pf() { # smoke_pf <svc> <port> <path> → 第一行 http code,其后是响应体(调用方按需取)
+smoke_pf() { # smoke_pf <svc> <port> <path> [<服务凭据>] → 第一行 http code,其后是响应体(调用方按需取);第 4 参缺省 = 不带凭据
   local pf_pid out code body
   $KUBECTL port-forward "svc/$1" -n "$NAMESPACE" "1$2:$2" >/dev/null 2>&1 &
   pf_pid=$!
   sleep 2
-  out=$(curl -m5 -s -w '\n%{http_code}' "http://127.0.0.1:1$2$3" || printf '\n000')
+  out=$(health_curl "${4:-}" -m5 -s -w '\n%{http_code}' "http://127.0.0.1:1$2$3" || printf '\n000')
   kill $pf_pid 2>/dev/null; wait $pf_pid 2>/dev/null || true
   code="${out##*$'\n'}"; body="${out%$'\n'*}"
   [ "$out" = "$code" ] && body=""   # 没有换行 = 只有码(假 curl / 空体)
   printf '%s\n%s' "$code" "$body"
 }
-HR=$(smoke_pf sema-server 8090 /health)
+HR=$(smoke_pf sema-server 8090 /health "$SERVICE_AUTH_TOKEN")   # 配了服务凭据的引擎只对出示凭据的读者给后端位 / 持久性
 H="${HR%%$'\n'*}"
 [ "$H" = "200" ] || die "smoke 失败:server /health=$H(期望 200)。下一步:kubectl -n $NAMESPACE logs deploy/sema-server"
-# /health 200 ≠ 数据落了库:后端位必须是期望的持久后端(durable(pg));读到 memory = 服务在内存里跑、重启即丢,不许判绿
+# /health 200 ≠ 数据落了库:后端位必须是期望的后端(pg)且读得到 store.durability;读到 memory = 服务在内存里跑、重启即丢,不许判绿
 BK_WHY=$(health_backend_check "${HR#*$'\n'}") || die "smoke 失败:$BK_WHY。下一步:kubectl -n $NAMESPACE logs deploy/sema-server(引擎在库没连上时不会再退内存起服 —— 它会拒启;读到 memory 多半是旧镜像)"
 A=$(smoke_pf sema-server 8090 /v1/runs); A="${A%%$'\n'*}"
 [ "$A" = "401" ] || die "smoke 失败:无 token /v1/runs=$A(期望 401=auth 门在)。SERVICE_AUTH_TOKEN 未生效=裸奔,立刻查"
@@ -422,7 +402,7 @@ if [ "$GIT_MODE" = "provision" ]; then
   G=$(smoke_pf sema-gitea 3000 /api/healthz); G="${G%%$'\n'*}"
   [ "$G" = "200" ] || die "smoke 失败:gitea healthz=$G"
 fi
-log "smoke ✓ health=$H backend=$(health_session_backend "${HR#*$'\n'}") auth=$A registry=$R gitea=$G"
+log "smoke ✓ health=$H backend=$(health_session_backend "${HR#*$'\n'}") durability=$(health_store_durability "${HR#*$'\n'}") auth=$A registry=$R gitea=$G${BK_WHY:+ — $BK_WHY}"
 
 # ── summary(一屏;凭据一次性显示)────────────────────────────────────────────────
 log "6/6 完成"

package/deploy/sema-up/lib/chart-run.sh

@@ -0,0 +1,23 @@
+# lib/chart-run.sh —— 跑随包 helm 图表的两只共用读法(kube-up.sh / cluster-up.sh 被 source,不单独执行)。全程参数展开:不开管道、不用 here-string。
+#
+# helm_notes <helm upgrade 的 stdout> —— 只把图表 NOTES 那一段(最后一个 `NOTES:` 行之后的全部)打到 stdout,其余一字不打。
+#   helm 开着调试(HELM_DEBUG / --debug)时 stdout 里还有 USER-SUPPLIED / COMPUTED VALUES 与渲出的 MANIFEST —— 含凭据与 Secret 明文,那些不进日志;
+#   NOTES 恒是 helm 输出的最后一段(钥匙卷的挂载位 / 访问模式 / 关持久的后果在这里)。没有 NOTES 段 ⇒ 什么都不打。
+helm_notes() {
+  local out="$1" nl=$'\n'
+  case "$out" in
+    *"${nl}NOTES:${nl}"*) printf '%s\n' "${out##*"${nl}NOTES:${nl}"}" ;;
+  esac
+}
+
+# sealed_key_class <现有钥匙卷的读数> <STORAGE_CLASS> —— 钥匙卷 PVC 该用的存储类。
+#   读数 = `kubectl get pvc sema-server-sealed-key --ignore-not-found -o jsonpath='{.metadata.name}/{.spec.storageClassName}'` 的输出:
+#   空 = 卷还没建 ⇒ STORAGE_CLASS(空 = 集群缺省);`<名>/<类>` = 卷已在 ⇒ 它建好时的类(PVC 的 storageClassName 建好后不可改,
+#   换类会让 helm upgrade 撞「spec is immutable」;7.134.0–7.147.x 建的钥匙卷走的是集群缺省类,不随 STORAGE_CLASS)。
+sealed_key_class() {
+  case "$1" in
+    "") printf '%s' "$2" ;;
+    */*) printf '%s' "${1#*/}" ;;
+    *) echo "sealed_key_class: 读不懂钥匙卷读数「$1」(期望空或 <名>/<类>)" >&2; return 2 ;;
+  esac
+}

package/deploy/sema-up/lib/dataroot.sh

@@ -11,8 +11,8 @@
 # 调用方先定义:log(打到 stderr)、PROJECT、WORK、ENVF。拒 = 响亮一段 + exit 1(不静默另选一条根:替运维挑目录是替他做决定)。
 
 DATAROOT_MARKER=".sema-up-project"
-# sema-up 在数据根下建的四只卷目录(compose.dataroot.yaml 的 bind 源)= 存量数据根的指纹。
-DATAROOT_LAYOUT="pgdata miniodata registrydata gitdata"
+# sema-up 在数据根下建的卷目录(compose.dataroot.yaml 的 bind 源)= 存量数据根的指纹。
+DATAROOT_LAYOUT="pgdata miniodata registrydata gitdata sealedkey"
 
 # dataroot_for_disk <挂载点> <项目> —— 自动选盘的根。preflight 的建议句也用它(同一条规则,不另拼路径)。
 dataroot_for_disk() { printf '%s/sema-data/%s' "${1%/}" "$2"; }
@@ -109,7 +109,7 @@ dataroot_plan_line() {
   esac
 }
 
-# dataroot_settle <根> —— 落定(只在真跑、判定之后调):建根与四只卷目录,new / backfill 时写标记。
+# dataroot_settle <根> —— 落定(只在真跑、判定之后调):建根与各只卷目录,new / backfill 时写标记。
 # 写标记用 noclobber(O_EXCL):两次 sema-up 同时认领同一条新根时,后到的那次读到对方的标记 ⇒ 拒,不互相覆盖。
 dataroot_settle() {
   local root="${DATAROOT_PHYS:-$1}" v