@sema-agent/server 7.147.0 → 7.148.0

package/deploy/sema-up/README.md

@@ -154,11 +154,18 @@ data-center:2c/2G/20G)以下 BLOCK——确实无法稳定部署,提前警告不
 - **MinIO**:钉死的 tag(`minio/minio:RELEASE.…`,chart / cluster 静态清单 / compose 三份同值;k8s `imagePullPolicy: IfNotPresent`,不再 `:latest` + `Always`)。换源 = 换整条引用:
   compose 与 kube-up 读环境变量 `MINIO_IMAGE`(kube-up 给了才递给 chart),chart 直接 `--set minio.image=<源>/minio/minio:<tag>`(预灌镜像的节点 `--set minio.pullPolicy=Never`)。
 
-## 停驻钥匙的持久卷(helm 图表的 `sealedKey` 块)
+## 停驻钥匙的持久卷(三条交付路径同形;helm 图表的 `sealedKey` 块)
 
-server 的 `<数据根>/sealed-key/` 存着停驻任务续跑上下文里请求凭据的封签钥匙(子目录 `checkpoint-ctx-keys/`)和模型钥匙 —— 私钥只在这个目录里、不进库。
-图表(`kube-up.sh` 的 `--kube=existing|k3s`、`cluster-up.sh` 的 `STACK_ENGINE=helm`)缺省把整个目录挂成一只 PVC(`sealedKey.persistence.enabled: true`),
-容器内路径 `/root/.ai-agent/sealed-key`,主 worker 与启用的 `serverV4pro` 共用:重启与换副本都不丢钥匙,停驻的任务照常续跑。
+server 的钥匙保管目录存着停驻任务续跑上下文里请求凭据的封签钥匙(子目录 `checkpoint-ctx-keys/`)和模型钥匙 —— 私钥只在这个目录里、不进库。
+三条交付路径都照随包部署事实 `deploy/facts/sealed-key.json` 装:给 server 设绝对路径的 `SEALED_KEY_DIR=/root/.ai-agent/sealed-key`,那个目录整个是一只持久卷 ——
+
+- **图表**(`kube-up.sh` 的 `--kube=existing|k3s`、`cluster-up.sh` 的 `STACK_ENGINE=helm`):缺省挂一只 PVC `sema-server-sealed-key`(`sealedKey.persistence.enabled: true`),
+  主 worker 与启用的 `serverV4pro` 共用;`kube-up.sh` 的 `STORAGE_CLASS` 同样用于新建的这只卷(已在的卷沿用它建好时的类,PVC 的存储类建好后不可改)。下面几条是图表的旋钮。
+- **cluster 静态清单**(`cluster-up.sh` 的缺省 `STACK_ENGINE=render`):同名 PVC,`ReadWriteMany`(本清单副本数恒 > 1)、存储类 `longhorn` —— **每个节点要装 NFS 客户端**
+  (Debian / Ubuntu `nfs-common`,RHEL 系 `nfs-utils`;机器预检缺它会告警,缺了 server Pod 挂不上卷、第 7 步等不到就绪而失败)。要单副本 / RWO / 关持久,改走图表路径。
+- **单机 compose**(`full-single` / `local-plus`):具名卷 `<项目>_sealedkey`(`--data-root` 时落 `<数据根>/sealedkey`);`--teardown-volumes` 删卷对象 —— docker 管的卷连钥匙一起没,`--data-root` 的 bind 目录留在盘上。
+
+重启与换副本都不丢钥匙,停驻的任务照常续跑。两条 helm 路径都把 helm 输出里的安装说明(NOTES 段)打进日志 —— 只这一段:开着 helm 调试时 stdout 里还有 values 与渲出的 Secret,那些不打。
 
 - **访问模式缺省随共享这只卷的 pod 数**:`server.replicas`(加上启用的 `serverV4pro.replicas`)为 1 ⇒ `ReadWriteOnce`,多于 1 ⇒ `ReadWriteMany`,**要集群的存储类支持 RWX**
   (Longhorn 走 NFS 共享管理器、每个节点要装 NFS 客户端;`local-path` 与多数云盘类不支持 ⇒ PVC 一直 Pending、server Pod 起不来)。点名存储类:`--set sealedKey.persistence.storageClass=<支持 RWX 的类>`。
@@ -166,7 +173,7 @@ server 的 `<数据根>/sealed-key/` 存着停驻任务续跑上下文里请求
   有效访问模式是 `ReadWriteOnce` 时 Deployment 用 `Recreate`(RWO 卷同时只能被一个节点挂,滚动更新的新 Pod 落在别的节点就永远等不到卷;代价是升级窗口内短暂没有副本)。
 - **没有 RWX 的集群**:`--set server.replicas=1`,或单节点多副本盖 RWO(上一条),或关持久 `--set sealedKey.persistence.enabled=false` —— 关掉时图表**显式**给每只 worker 设 `DURABLE_APPROVAL=false`
   (耐久审批整条关,不产生续不了的停驻行;`helm install` 打印的安装说明里也有这一句),且同时配 `server.durableApproval=true` 渲染即拒。
-- **首装是空卷**:多个 pod 并发首启可能各建一把钥匙、各持自己那一把(钥匙创建没有互斥,只有两个副本在同一个目录上同时首启、都没读到可用的钥匙文件时才发生,不是每次都分叉);装好后不论有没有分叉都执行 `kubectl -n <ns> rollout restart deploy/sema-server`(启用 `serverV4pro` 时再加 `deploy/sema-server-v4pro`)一次,之后每个 pod 读到全部钥匙。
+- **首装是空卷**:多个 pod 并发首启也只出一把钥匙(7.148.0 起,首把钥匙只有一个创建口:空目录里以 `wx` 独占创建互斥文件 `.keygen.lock` 分先后,其余 pod 等它发布后读到同一把),不必重启;要求存储类的 `O_EXCL` 独占创建是原子的(本地盘与 NFSv3 及以上按协议满足,别的存储请向存储方确认)。7.147.x 及更早版本首装出多把钥匙的卷(各 pod 各持自己那一把、互相答 `key_not_held`):执行 `kubectl -n <ns> rollout restart deploy/sema-server`(启用 `serverV4pro` 时再加 `deploy/sema-server-v4pro`)一次,之后每个 pod 读到全部钥匙。
 - PVC 的 `accessModes` 建好后不可改:副本数跨过 1 的边界时 `helm upgrade` 会撞「spec is immutable」;卷里是私钥,换卷前先结掉停驻行或备份钥匙文件。
   PVC 带 `helm.sh/resource-policy: keep`:`helm uninstall` 与把 `enabled` 改成 `false` 的 upgrade 都不删它(确认不要了再 `kubectl -n <ns> delete pvc sema-server-sealed-key`)。
 
@@ -249,4 +256,8 @@ machines.example.yaml 多机清单模板
 lib/parse-machines.py machines.yaml mini-parser(标准库零依赖,fail-loud)
 lib/dataroot.sh       数据根归属规则(自动根按项目分 / 项目标记 / 拒 / 卸载提示;sema-up 与 preflight 同读)
 lib/shell-access.sh   汇总里「壳接入」一段的唯一渲染(sema-up / kube-up / cluster-up 同读;只给位置不给值)
+lib/shell-text.sh     把一段文本按行 / 按词 / 按分隔字符读进变量(sema-up / kube-up / preflight 同读;不用 here-document / here-string,因为正文长过管道缓冲时在管道配额吃紧的机器上会永远写不完)
+lib/remote/*.sh       cluster-up 送去目标机 `bash -s` 跑的脚本(经 stdin 重定向喂入,不内嵌在入口脚本里;要传值的以位置参数递给远端)
+lib/*.py              渲染 helm values / 栈清单、生成镜像拉取凭据的 python 正文(经 stdin 重定向喂入)
+lib/usage-*.txt       `sema-up.sh --help` 里不随词表变的静态文本段
 ```

package/deploy/sema-up/chart/templates/NOTES.txt

@@ -8,7 +8,7 @@
 多个 pod 共用这只卷,存储类必须支持 ReadWriteMany(PVC 一直 Pending 就是它不支持:出路 server.replicas=1,或 sealedKey.persistence.enabled=false 并接受耐久审批随之关)。
 {{- end }}
 {{- if gt (int (include "sema.sealedKey.podCount" .)) 1 }}
-首装是空卷:多个副本并发首启可能各建一把钥匙、各持自己那一把(只有两个副本在同一个目录上同时首启、都没读到可用的钥匙文件时才发生,不是每次都分叉)—— 装好后不论有没有分叉都执行一次 kubectl -n {{ .Release.Namespace }} rollout restart deploy/sema-server{{ if .Values.serverV4pro.enabled }} deploy/sema-server-v4pro{{ end }},此后每个副本读到目录里的全部钥匙。
+首装是空卷:多个副本并发首启也只出一把钥匙(7.148.0 起首把钥匙只有一个创建口,不必重启);7.147.x 及更早版本首装出多把钥匙的卷(各副本各持自己那一把、互相答 key_not_held)执行一次 kubectl -n {{ .Release.Namespace }} rollout restart deploy/sema-server{{ if .Values.serverV4pro.enabled }} deploy/sema-server-v4pro{{ end }},此后每个副本读到目录里的全部钥匙。
 {{- end }}
 {{- else }}
 停驻封签钥匙:sealedKey.persistence.enabled=false —— 不建卷,图表已给每只 worker 显式设上 DURABLE_APPROVAL=false(耐久审批整条关,不产生续不了的停驻行;代价见 values.yaml 的 sealedKey 块;要重新打开,把它改回 true)。关持久 + 提交体没声明 settings.approvalFrameFamilies 的客户端 ⇒ 受门工具当场拒(没有耐久店,无处停驻;7.134.0 起审批卡只发给声明认得这一族的客户端)。

package/deploy/sema-up/chart/templates/_helpers.tpl

@@ -14,8 +14,16 @@
 {{- /* 卷 / PVC 的名字。 */ -}}
 {{- define "sema.sealedKey.claimName" -}}sema-server-sealed-key{{- end -}}
 
-{{- /* 容器内挂载点 = <数据根>/sealed-key(整个目录:模型钥匙 + checkpoint-ctx-keys/ 同一卷)。 */ -}}
-{{- define "sema.sealedKey.mountPath" -}}/root/.ai-agent/sealed-key{{- end -}}
+{{- /*
+  容器内挂载点 = 引擎的钥匙保管目录(整个目录:模型钥匙 + checkpoint-ctx-keys/ 同一卷),也是给引擎设的 SEALED_KEY_DIR 的值(随包部署事实 sealed-key.json:
+  安装器显式设绝对路径,不靠引擎的数据根回落)。值只有一处定义:sema-up 三条交付路径(本图表 · cluster 静态清单 · 单机 compose)的挂载位由
+  scripts/gen-deploy-lanes.ts 的 SEMA_UP_SEALED_KEY_DIR 渲出,下面圈起来的一行不要手改。
+*/ -}}
+{{- define "sema.sealedKey.mountPath" -}}
+{{/* @generated-begin sealed-key-dir */}}
+{{- "/root/.ai-agent/sealed-key" -}}
+{{/* @generated-end sealed-key-dir */}}
+{{- end -}}
 
 {{- /*
   持久开关,且**只收布尔**:`--set-string ...enabled=false` / values 里带引号的 "false" 是字符串,模板里字符串恒为真 ⇒ 会静默保持持久开,
@@ -126,11 +134,19 @@ false
 {{- ternary "false" "true" (eq $rp "true") -}}
 {{- end -}}
 
-{{- /* worker 容器 env 里的耐久审批一条(`nindent 12` 之后接在 env 列表里);值为空 ⇒ 什么都不出。 */ -}}
+{{- /*
+  worker 容器 env 里与钥匙卷同源的两条(`indent 12` 之后接在 env 列表里):持久开 ⇒ SEALED_KEY_DIR = 挂载点(安装契约:显式绝对路径);
+  耐久审批的显式表态(值为空 ⇒ 不出这一条)。持久关 ⇒ 不设 SEALED_KEY_DIR(没有卷可指),只出 DURABLE_APPROVAL=false。
+*/ -}}
 {{- define "sema.sealedKey.env" -}}
+{{- $lines := list -}}
+{{- if eq (include "sema.sealedKey.enabled" .) "true" -}}
+{{- $lines = append $lines (printf "- { name: SEALED_KEY_DIR, value: %s }" (include "sema.sealedKey.mountPath" . | quote)) -}}
+{{- end -}}
 {{- with (include "sema.durableApproval" .) -}}
-- { name: DURABLE_APPROVAL, value: {{ . | quote }} }
+{{- $lines = append $lines (printf "- { name: DURABLE_APPROVAL, value: %s }" (. | quote)) -}}
 {{- end -}}
+{{- join "\n" $lines -}}
 {{- end -}}
 
 {{- /* worker 容器的 volumeMounts 块(`nindent 10`);持久关 ⇒ 什么都不出。 */ -}}

package/deploy/sema-up/chart/values.yaml

@@ -86,8 +86,9 @@ server:
 #   这只卷里是私钥,不要为了过这个错直接删 PVC:先把停驻行结掉(随包排空检查脚本数一数)或备份钥匙文件,再换卷。
 #   PVC 带 helm.sh/resource-policy: keep:`helm uninstall` 与把 enabled 改成 false 的 upgrade 都不删它(钥匙留着;确认不要了再 `kubectl -n <ns> delete pvc sema-server-sealed-key`);
 #   同名 release 重装会接管这只留下的 PVC。
-#   ⚠ 空卷上多副本并发首启:钥匙创建没有互斥,两个副本在同一个目录上同时首启、都没读到可用的钥匙文件时,各副本可能各建一把钥匙、只持有自己那一把,直到下次重启(不是每次都分叉)—— 首装后不论有没有分叉都执行 `kubectl -n <ns> rollout restart deploy/sema-server`
-#   一次(启用 serverV4pro 时再加 deploy/sema-server-v4pro;NOTES 也说这句),重启之后每个副本读到目录里的全部钥匙,从此一致。
+#   空卷上多副本并发首启也只出一把钥匙(7.148.0 起:首把钥匙只有一个创建口,空目录里以独占创建的互斥文件分先后,其余副本等它发布后读到同一把;要求存储类的 O_EXCL 独占创建是原子的),不必重启。
+#   7.147.x 及更早版本首装出多把钥匙的卷(各副本各持自己那一把、互相答 key_not_held):执行一次 `kubectl -n <ns> rollout restart deploy/sema-server`
+#   (启用 serverV4pro 时再加 deploy/sema-server-v4pro;NOTES 也说这句),重启之后每个副本读到目录里的全部钥匙,从此一致。
 sealedKey:
   persistence:
     # true(缺省)= 建 PVC 并挂到上面的路径。

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"
@@ -400,77 +339,36 @@ RENDERED="$WORK/sema-stack-cluster.rendered.yaml"
   R_PG_INSTANCES="$PG_INSTANCES" R_PG_AA="$PG_AA" R_REPLICAS="$SERVER_REPLICAS" \
   R_REQ_PRINCIPAL="$(principal_of_users "$USERS")" \
   R_OPERATOR_SINGLE_USER="$(operator_single_user_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", "__OPERATOR_SINGLE_USER__":"R_OPERATOR_SINGLE_USER"}
-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
+  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 真踩)
@@ -479,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)。