@sema-agent/server 7.147.0 → 7.149.0

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

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

@@ -1,13 +1,40 @@
-# lib/health.sh — 「装好的引擎 /health 体说它真落在哪个后端」的唯一读法 + sema-up 部署的期望值。
+# lib/health.sh — 「装好的引擎 /health 体说它落在哪个后端、店活不活得过替换」的唯一读法 + sema-up 部署的期望值。
 # smoke.sh / kube-up.sh / cluster-up.sh 三处验收都调它,不各写一份(各写一份的下场:有一处还只看 HTTP 200,把退到内存的服务判绿)。
 #
 # 事实(出处是引擎,不是推测):
-#  · `/health` 体里的 `sessionBackend` 是**装配后**的有效店:`durable(<kind>)`(kind = pg | mysql | local)或 `memory`
-#    (引擎侧只有一只读法:src/store-posture.ts 的 `sessionStoreLabelOf`);
+#  · `/health` 体里的 `sessionBackend` = 会话店**装配后**落在哪种后端:`pg` | `mysql` | `local` | `memory`(只说种类;
+#    引擎侧只有一只读法:src/store-posture.ts 的 `sessionStoreLabelOf`);
+#  · `/health` 体里的 `store.durability` = 店活不活得过容器 / Pod 替换:`durable` | `ephemeral` | `unknown`(三根取最弱:数据根、
+#    封签钥匙目录、file 记忆根;与 GET /v1/capabilities 的 `store.durability` 同一只读数;逐根明细在 GET /v1/diagnostics/wiring 的 `storeDurability.roots`);
+#  · 这两位只给**出示了服务凭据**的读者:sema-up 部署的引擎一律配了 `SERVICE_AUTH_TOKEN`,而配了服务凭据的引擎对匿名 `/health` 只给存活位与自报位三键
+#    (src/http/health-reader.ts),不给 `sessionBackend` / `store`。三处验收读 `/health` 都带这枚凭据:本机两处(smoke.sh / kube-up.sh)走 `health_curl`,
+#    多机那一处(cluster-up.sh)是同一句话在远端节点上的写法(凭据经 stdin 配置喂 curl,不进远端 argv);
 #  · sema-up 三条路径(compose / kube / 多机)起的引擎一律 `DB_BACKEND=pg`(stack/compose.yaml、chart/templates/server.yaml、
-#    stack/sema-stack-cluster.yaml 逐份写死),所以装好的引擎必须读到 `durable(pg)`。读到 `memory` = 会话 / 停驻 / run 账本在进程内存里、
+#    stack/sema-stack-cluster.yaml 逐份写死),所以装好的引擎必须读到 `sessionBackend=pg`。读到 `memory` = 会话 / 停驻 / run 账本在进程内存里、
 #    重启即丢 —— /health 照样 200、401 门照样在,只有这一位说了实话,验收必须看它。
-SEMA_UP_EXPECT_SESSION_BACKEND="durable(pg)"
+#  · `store.durability` 必须读得到(三词之一;读不到 = 引擎早于这一读法,或体不是引擎的);它不是 `durable` 时验收**照过**、但把读数与指路说出来
+#    (与引擎自己的起服审计同一律:会话店在 pg 上恒持久,别的根判不出 / 易失只 warn)。三条路径都给封签钥匙目录挂了卷,读数随卷的形走:
+#    多机清单的 Longhorn RWX(NFS)读 `durable`;compose 的具名卷 / `--data-root` bind、图表路径上 hostPath 形的存储类(如 local-path)是绑定挂载一只子目录,
+#    判不出它跟着谁走,读 `unknown`。
+SEMA_UP_EXPECT_SESSION_BACKEND="pg"
+
+# health_curl <服务凭据|空串> <curl 实参…> —— 本机读 `/health`:有凭据就带 `Authorization: Bearer`(全键),空串 = 不带(没配服务凭据的引擎本来就给全键)。
+# 凭据只上本机 curl 的实参(与 smoke.sh 的 POST /v1/tasks 同一处境)。
+health_curl() {
+  local tok="$1"; shift
+  if [ -n "$tok" ]; then curl "$@" -H "Authorization: Bearer $tok"; else curl "$@"; fi
+}
+
+# health_curl_config <服务凭据> —— 多机验收在远端节点上读 `/health` 用的 curl 配置行(经 stdin 喂 `curl -K -`,凭据不进远端 argv):
+# 打印 `header = "Authorization: Bearer <凭据>"`,凭据里的反斜杠与双引号按 curl 配置文法转义(原样读回);凭据含控制字符(换行 / 回车 …)⇒ rc 1、不打印 ——
+# 那不是能放进 Authorization 头的值,更不能让它多出一行配置。调用方再过一道 `printf '%q'` 才把这一行放进远端 shell 文本(值是数据,不是代码)。
+health_curl_config() {
+  local t="$1"
+  case "$t" in *[[:cntrl:]]*) return 1 ;; esac
+  t="${t//\\/\\\\}"
+  t="${t//\"/\\\"}"
+  printf 'header = "Authorization: Bearer %s"' "$t"
+}
 
 # health_session_backend <health 体> → 打印 `sessionBackend` 的值;体读不成 JSON / 没有这一位 ⇒ 打印空串(调用方按「读不出」处置,不猜)。
 health_session_backend() {
@@ -19,15 +46,37 @@ except Exception:
   print("")' 2>/dev/null
 }
 
-# health_backend_check <health 体> → 0 = 落在期望的后端;1 = 不是(stdout 打一句人话,供调用方拼进失败行)。
+# health_store_durability <health 体> → 打印 `store.durability`(三词之一);体读不成 JSON / 没有这一位 / 不是三词之一 ⇒ 打印空串。
+health_store_durability() {
+  printf '%s' "$1" | python3 -c 'import json,sys
+try:
+  s = json.load(sys.stdin).get("store", {})
+  v = s.get("durability", "") if isinstance(s, dict) else ""
+  print(v if v in ("durable", "ephemeral", "unknown") else "")
+except Exception:
+  print("")' 2>/dev/null
+}
+
+# health_backend_check <health 体> → 0 = 落在期望的后端且读得到持久性(stdout:持久性不是 `durable` 时一句读数 + 指路,调用方拼进成功行);
+# 1 = 不是(stdout 打一句人话,供调用方拼进失败行)。
 health_backend_check() {
-  local got
+  local got dur
   got="$(health_session_backend "$1")"
-  if [ "$got" = "$SEMA_UP_EXPECT_SESSION_BACKEND" ]; then return 0; fi
-  if [ -z "$got" ]; then
-    printf '/health 体里读不出 sessionBackend(期望 %s)' "$SEMA_UP_EXPECT_SESSION_BACKEND"
-  else
-    printf '/health.sessionBackend=%s,期望 %s' "$got" "$SEMA_UP_EXPECT_SESSION_BACKEND"
+  dur="$(health_store_durability "$1")"
+  if [ "$got" != "$SEMA_UP_EXPECT_SESSION_BACKEND" ]; then
+    if [ -z "$got" ]; then
+      printf '/health 体里读不出 sessionBackend(期望 %s)' "$SEMA_UP_EXPECT_SESSION_BACKEND"
+    else
+      printf '/health.sessionBackend=%s,期望 %s' "$got" "$SEMA_UP_EXPECT_SESSION_BACKEND"
+    fi
+    return 1
+  fi
+  if [ -z "$dur" ]; then
+    printf '/health 体里读不出 store.durability(期望 durable / ephemeral / unknown 之一;读不到多半是旧镜像)'
+    return 1
+  fi
+  if [ "$dur" != "durable" ]; then
+    printf 'store.durability=%s(至少一根活不过容器替换或判不出;逐根看 GET /v1/diagnostics/wiring 的 storeDurability.roots,给那只目录挂持久卷)' "$dur"
   fi
-  return 1
+  return 0
 }

package/deploy/sema-up/lib/helm-values-cluster.py

@@ -0,0 +1,18 @@
+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},
+}))

package/deploy/sema-up/lib/helm-values-kube.py

@@ -0,0 +1,35 @@
+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"]},
+  # 钥匙卷的存储类:kube-up 按 lib/chart-run.sh sealed_key_class 定(新建 = STORAGE_CLASS;已在 = 它建好时的类,不可改)。其余 sealedKey 键照图表缺省。
+  "sealedKey": {"persistence": {"storageClass": e["V_SK_SC"]}},
+}
+# MinIO 镜像:给了才递(默认只在 chart values.yaml 写一处,不在脚本里再抄一份);国内源 = 整条引用
+if e["V_MINIO_IMAGE"]: v["minio"]["image"] = e["V_MINIO_IMAGE"]
+print(json.dumps(v))

package/deploy/sema-up/lib/regcred.py

@@ -0,0 +1,8 @@
+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}}))

package/deploy/sema-up/lib/remote/helm-install.sh

@@ -0,0 +1,3 @@
+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

package/deploy/sema-up/lib/remote/image-import.sh

@@ -0,0 +1,6 @@
+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

package/deploy/sema-up/lib/remote/machine-precheck.sh

@@ -0,0 +1,11 @@
+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)"
+# 钥匙卷是 ReadWriteMany(多副本共用一份钥匙);Longhorn 的 RWX 由节点上的 NFS 客户端挂载 —— 缺它 server Pod 挂不上卷、rollout 等不到就绪
+{ [ -x /sbin/mount.nfs ] || [ -x /usr/sbin/mount.nfs ]; } || echo "WARN 无 NFS 客户端(mount.nfs)——server 的钥匙卷(ReadWriteMany)在本节点挂不上(建议:apt-get install -y nfs-common / yum install -y nfs-utils)"
+hostname

package/deploy/sema-up/lib/remote/region-probe.sh

@@ -0,0 +1,3 @@
+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"}'

package/deploy/sema-up/lib/remote/stack-ready.sh

@@ -0,0 +1,26 @@
+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

package/deploy/sema-up/lib/remote/vxlan-guard.sh

@@ -0,0 +1,8 @@
+set -e
+iface="$1"
+printf '%s\n' '[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' > /etc/systemd/system/sema-vxlan-guard.service
+systemctl daemon-reload && systemctl enable --now sema-vxlan-guard.service
+iptables -C INPUT -i "$iface" -p udp --dport 8472 -j DROP

package/deploy/sema-up/lib/render-stack.py

@@ -0,0 +1,17 @@
+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)

package/deploy/sema-up/lib/shell-text.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+# shell-text.sh —— 把一段文本「按行 / 按词 / 按分隔字符」读进变量的三只函数(被 source,不单独执行)。
+#
+# ── 为什么有这只 lib ─────────────────────────────────────────────────────────────────────────────────────────────────
+# `read … ` 与 `while read …; done` 后面接 here-string(把一段文本直接当输入的那种写法)时,靠 bash 先把整段文本写进一根管道、读者随后才读。
+# 全机管道配额吃紧时,内核只给新管道很小的缓冲(事故里读到的形:512 B),文本一长就写不完,链路停在本机、日志里什么也没有。
+# registry 的一行读数里装着本包的全部版本号(几 KB),恰是这一类。这条死法与脚本逻辑无关,只与「脚本里有没有 here-document / here-string」有关,
+# 所以发车链的两个脚本目录与部署脚本目录(deploy/ 下全部 .sh)的每一行都不许有这两种写法(由仓内测试逐行钉住);
+# 要把一段文本读进变量,走这里:全程只用参数展开,不开管道、不开文件描述符、不起子进程,更不起子 shell(变量赋值与 `return` 留在调用方的 shell 里)。
+# 本文件有两份逐字节相同的拷贝:发车链用的一份在 scripts/lib/,随部署包落到运维机的一份在 deploy/sema-up/lib/(部署目录要能脱离 scripts/ 单独落机)。改一处必须同改另一处,仓内测试逐字节比。
+#
+# ── 三只函数 ────────────────────────────────────────────────────────────────────────────────────────────────────────
+#   text_words <文本> <变量名>…        = `read -r <变量名>…` 读 here-string 的文本:只读文本的第一行,按空格 / 制表切词;
+#                                       前 N-1 个词依次给前 N-1 个变量,第 N 个变量拿剩下的整段(去掉两头的空白);词不够 ⇒ 余下的变量写空串。
+#                                       分隔符取自 IFS 里的空格与制表(IFS 没设 ⇒ 默认,两者都是;`IFS=' ' text_words …` ⇒ 只认空格)。
+#                                       IFS 里有空格 / 制表 / 换行之外的字符,或一个空格与制表都没有 ⇒ rc 2、stderr 一句(不静默换一种切法)。
+#   text_split <分隔字符> <文本> <变量名>…   = `IFS=<分隔字符> read -r <变量名>…` 读 here-string 的文本:只读文本的第一行;分隔字符是单个字符(不是空格 / 制表 / 换行),
+#                                       每个分隔字符都切一刀、空段照留;前 N-1 段依次给前 N-1 个变量,第 N 个变量拿剩下的整段(其中还有分隔字符就原样留着),
+#                                       例外一处与 read 一致:剩下的整段里只有末尾恰一个分隔字符、别无他个 ⇒ 那一个算终结符、不算内容;段不够 ⇒ 余下的变量写空串。
+#   text_pop_line <存余变量名> <行变量名>   从名为 <存余变量名> 的变量里削下第一行放进 <行变量名>,<存余变量名> 留剩下的;存余为空 ⇒ rc 1(没有行了)。
+#                                       逐行遍历的写法(同 `while IFS= read -r l; do …; done` 读 here-string 的文本):
+#                                           rest="$文本"$'\n'            # here-string 在文本末尾补的那个换行;空文本 ⇒ 恰好读到一行空行
+#                                           while text_pop_line rest line; do …; done
+# 变量名只许是调用方的普通变量名(printf -v 写它);本文件的内部变量一律 _ts_ 起头,调用方别用这个前缀。
+# bash 3.2 兼容(发车机 /bin/bash 可能是它):不用关联数组 / mapfile / nameref。
+
+_TS_NL=$'\n'
+_TS_TAB=$'\t'
+
+text_words() { # <文本> <变量名>…
+  [ "$#" -ge 2 ] || { echo "text_words: 用法 text_words <文本> <变量名>…" >&2; return 2; }
+  local _ts_ifs _ts_ws="" _ts_rest _ts_lead _ts_word _ts_tail
+  if [ -z "${IFS+x}" ]; then _ts_ifs=" $_TS_TAB$_TS_NL"; else _ts_ifs="$IFS"; fi
+  [ -z "${_ts_ifs//[ $_TS_TAB$_TS_NL]/}" ] || { echo "text_words: IFS 里有空格 / 制表 / 换行以外的字符,不支持" >&2; return 2; }
+  case "$_ts_ifs" in *" "*) _ts_ws=" " ;; esac
+  case "$_ts_ifs" in *"$_TS_TAB"*) _ts_ws="$_ts_ws$_TS_TAB" ;; esac
+  [ -n "$_ts_ws" ] || { echo "text_words: IFS 里既没有空格也没有制表,没有可切的分隔符" >&2; return 2; }
+  _ts_rest="${1%%"$_TS_NL"*}"
+  shift
+  while [ "$#" -gt 1 ]; do
+    _ts_lead="${_ts_rest%%[!$_ts_ws]*}"
+    _ts_rest="${_ts_rest#"$_ts_lead"}"
+    _ts_word="${_ts_rest%%[$_ts_ws]*}"
+    _ts_rest="${_ts_rest#"$_ts_word"}"
+    printf -v "$1" '%s' "$_ts_word" || return 2
+    shift
+  done
+  _ts_lead="${_ts_rest%%[!$_ts_ws]*}"
+  _ts_rest="${_ts_rest#"$_ts_lead"}"
+  _ts_tail="${_ts_rest##*[!$_ts_ws]}"
+  _ts_rest="${_ts_rest%"$_ts_tail"}"
+  printf -v "$1" '%s' "$_ts_rest" || return 2
+}
+
+text_pop_line() { # <存余变量名> <行变量名>
+  [ "$#" -eq 2 ] || { echo "text_pop_line: 用法 text_pop_line <存余变量名> <行变量名>" >&2; return 2; }
+  local _ts_all="${!1}"
+  [ -n "$_ts_all" ] || return 1
+  printf -v "$2" '%s' "${_ts_all%%"$_TS_NL"*}" || return 2
+  case "$_ts_all" in
+    *"$_TS_NL"*) printf -v "$1" '%s' "${_ts_all#*"$_TS_NL"}" || return 2 ;;
+    *) printf -v "$1" '%s' "" || return 2 ;;
+  esac
+}
+
+text_split() { # <分隔字符> <文本> <变量名>…
+  [ "$#" -ge 3 ] || { echo "text_split: 用法 text_split <分隔字符> <文本> <变量名>…" >&2; return 2; }
+  local _ts_sep="$1" _ts_rest="${2%%"$_TS_NL"*}" _ts_field
+  case "$_ts_sep" in
+    " " | "$_TS_TAB" | "$_TS_NL") echo "text_split: 分隔字符不能是空格 / 制表 / 换行(要按空白切词用 text_words)" >&2; return 2 ;;
+  esac
+  [ "${#_ts_sep}" -eq 1 ] || { echo "text_split: 分隔符必须恰是一个字符" >&2; return 2; }
+  shift 2
+  while [ "$#" -gt 1 ]; do
+    _ts_field="${_ts_rest%%"$_ts_sep"*}"
+    case "$_ts_rest" in *"$_ts_sep"*) _ts_rest="${_ts_rest#*"$_ts_sep"}" ;; *) _ts_rest="" ;; esac
+    printf -v "$1" '%s' "$_ts_field" || return 2
+    shift
+  done
+  case "$_ts_rest" in
+    *"$_ts_sep")
+      _ts_field="${_ts_rest%"$_ts_sep"}"
+      case "$_ts_field" in *"$_ts_sep"*) ;; *) _ts_rest="$_ts_field" ;; esac
+      ;;
+  esac
+  printf -v "$1" '%s' "$_ts_rest" || return 2
+}

package/deploy/sema-up/lib/usage-flags.txt

@@ -0,0 +1,10 @@
+  --interactive=json     机器可读交互协议(sema cloud deploy 渲染用)
+  --yes                  全默认无人值守(与 -f 组合)
+  -f FILE                site 配置(env 形式;machines.yaml=固定形状 mini-parser)
+  --project=NAME         compose project 名(默认 sema;并行试验用)。也是工作目录 ~/.sema-up/<名> 与自动数据根
+                         <盘>/sema-data/<名> 的一段 ⇒ 只收小写字母 / 数字 / - / _,首字符是字母或数字
+  --data-root=DIR        数据卷 bind 到这条目录(缺省:多盘机自动选大盘 <盘>/sema-data/<project>);首装落定不漂移,
+                         一条数据根只归一个项目(根里的 .sema-up-project 标记,别的项目的根一律拒)
+  --dry-run              只打印将执行计划(不写 .env、不起任何容器)
+  --port=N               服务端口(默认 8090);--pg-port/--minio-port/--minio-console-port 同理(端口旗只收 1–65535 的整数)
+  --gateway=URL --model=ID --model-key=K   模型面(带 agent 的档必需)

package/deploy/sema-up/lib/usage-head.txt

@@ -0,0 +1 @@
+用法: sema-up.sh [选项]

package/deploy/sema-up/lib/usage-tail.txt

@@ -0,0 +1,13 @@
+  --registry=true|false  配置中心网站(默认 true;local-plus 默认 false;只收这两个词)
+  --registry-image=REF   sema-registry 镜像(registry=true 必需,可 -f 配置 SEMA_REGISTRY_IMAGE)
+  --git=MODE             none(默认)|provision(一键自建 Gitea)|connect(接已有 git)
+  --git-url=URL --git-token=T   git=connect 的已有服务(Gitea/GitHub/任意三方 git;自动识别,证书不校验)
+  --pg-url=URL           外接第三方 PG(postgres://user:pass@host:port/db;连不上会先检,不部署本地 PG)
+  --s3-endpoint=URL --s3-access-key=K --s3-secret-key=S   外接第三方 S3(兼容协议即可;不部署本地 MinIO)
+  --git-http-port=N --git-ssh-port=N   自建 Gitea 端口(默认 3300/2222)
+  --gitea-image=REF      自建 Gitea 镜像(默认 gitea/gitea:1.24)
+  --pg-host=H --pg-password=P --minio-endpoint=URL --minio-password=P   local-plus 远端数据面
+  --kube=MODE            full-cluster 单机两态:existing(已有 kubeconfig)|k3s(本机装 k3s)
+  --kubeconfig=PATH      --kube=existing 的 kubeconfig(缺省 $KUBECONFIG 或 ~/.kube/config)
+  --teardown             卸载本 project(数据卷保留;--teardown-volumes 连卷删)
+  --skip-preflight       跳过预检(不建议)