@xgent-ai/skills 0.3.0 → 0.5.0

package/skills/portal-dev-setup/scripts/onebox.sh

@@ -10,6 +10,8 @@
 #   onebox.sh up               ★ 按顺序把整套铺起来（迁移→种子→各库→注册→起栈），幂等可重跑。
 #                              顺序本身是契约（种子会 truncate、反代启动时才读 /svc map），
 #                              这条命令就是为了不让人自己记它。
+#   onebox.sh upgrade [--image <ref>] [--proxy-image <ref>]
+#                              换部署资产并追加版本信息；保留现有配置、端口、密钥与数据，再跑 up。
 #   onebox.sh doctor           ★ 体检：把排查表里能自动判的都判一遍，每条给一行可直接粘的修法。
 #                              跑不通先跑它，别翻文档。
 #   onebox.sh add <key>        ★ 把一个平台侧 App 拉进来陪调（如 omni-parser 多模态解析）：
@@ -74,6 +76,8 @@ load_registry_config() {
   done < "$f"
   # base64 不是加密，同组可读就等于把口令摊在那儿
   if [ -n "${PULLER_AUTH:-}" ]; then
+    # Only the permission field is read; the filename is never parsed.
+    # shellcheck disable=SC2012
     case "$(ls -l "$f" | cut -c1-10)" in ??????---*) ;; *) warn "$f 含 PULLER_AUTH 且同组/其他人可读 —— chmod 600 $f";; esac
   fi
 }
@@ -123,12 +127,13 @@ registry_login() {
     || die "docker login $REGISTRY 失败。口令可能已被轮换 —— 先 docker logout $REGISTRY 再让开发团队补一份新的 PULLER_AUTH。（陈旧凭证不会提示你去登录，只会一直 401。）"
 }
 
-# do_pull REF HINT —— docker pull 的 "What's Next" 提示走 stderr，>/dev/null 挡不住；
+# do_pull REF HINT [PLATFORM] —— docker pull 的 "What's Next" 提示走 stderr，>/dev/null 挡不住；
 # 但 2>&1 会把真错误一起吞掉，所以收进临时文件、只在失败时回显。
 do_pull() {
   local ref="$1" hint="$2" errf; errf="$(mktemp)"
-  info "拉 ${ref} …"
-  if ! docker pull "$ref" >/dev/null 2>"$errf"; then
+  local -a pf=(); [ -n "${3:-}" ] && pf=(--platform "$3")
+  info "拉 ${ref}${3:+（${3}）} …"
+  if ! docker pull ${pf[@]+"${pf[@]}"} "$ref" >/dev/null 2>"$errf"; then
     local msg; msg="$(tail -3 "$errf")"; rm -f "$errf"
     die "docker pull $ref 失败。${hint:+$hint
 }$msg"
@@ -254,6 +259,85 @@ port_free() { ! (exec 3<>"/dev/tcp/127.0.0.1/$1") >/dev/null 2>&1; }
 pick_port() { local p; for p in "$@"; do port_free "$p" && { printf '%s' "$p"; return; }; done; printf '%s' "$1"; }
 rand_hex() { openssl rand -hex 32 2>/dev/null || head -c32 /dev/urandom | od -An -tx1 | tr -d ' \n'; }
 
+_image_version() {
+  local image="$1" id created
+  id="$(docker image inspect "$image" --format '{{.Id}}' 2>/dev/null | cut -c8-14 || true)"
+  created="$(docker image inspect "$image" --format '{{.Created}}' 2>/dev/null | cut -c1-10 || true)"
+  [ -z "$id" ] || printf 'onebox %s %s%s' "${image##*:}" "$id" "${created:+ built ${created}}"
+}
+
+# Shared by init and upgrade. Machine-owned state must never come from an image.
+_extract_assets() {
+  local image="$1" home="$2" postgres_volume="${3:-}" tmp cid
+  info "从 ${image} 取出 compose 资产…"
+  tmp="$(mktemp -d)"
+  cid="$(docker create "$image")" || { rm -rf "$tmp"; die "docker create 失败，请确认镜像已就位。"; }
+  if ! docker cp "$cid:/app/deploy" "$tmp/deploy" >/dev/null; then
+    docker rm -f "$cid" >/dev/null; rm -rf "$tmp"
+    die "镜像里没有 /app/deploy，请使用门户一盒镜像。"
+  fi
+  docker rm -f "$cid" >/dev/null
+  if ! grep -qE '^  rustfs:' "$tmp/deploy/docker-compose.yml" \
+    || [ ! -f "$tmp/deploy/scripts/objectstore-cutover.sh" ] \
+    || [ ! -f "$tmp/deploy/scripts/objectstore-manifest.ts" ]; then
+    rm -rf "$tmp"; die "镜像里的对象存储资产还是旧版，请 upgrade --image <新版一盒镜像>。"
+  fi
+  ( cd "$tmp/deploy" && rm -rf .DS_Store k8s oauth pm2 caddy knowledge-devkit onebox/Dockerfile \
+      compose.env generated backup scripts/tests \
+      app-devkit/manifests/pagebuilder.manifest.json app-devkit/manifests/task-gateway.manifest.json )
+  # Persist volume identity in staging before replacing assets. If a later version
+  # check refuses an unknown layout, the next run must still find the same data.
+  if [ -n "$postgres_volume" ]; then
+    if ! awk -v volume="$postgres_volume" '
+      /^volumes:/{volumes=1}
+      volumes && /^  pg-data:/{print "  pg-data:"; print "    name: " volume; pg=1; count++; next}
+      volumes && /^  [A-Za-z0-9_-]+:/{pg=0}
+      pg && /^    name:/{next}
+      {print}
+      END{if(count!=1)exit 1}
+    ' "$tmp/deploy/docker-compose.yml" > "$tmp/compose-pinned.yml"; then
+      rm -rf "$tmp"; die "新版资产缺少唯一 pg-data 卷定义，未替换现有资产。"
+    fi
+    mv "$tmp/compose-pinned.yml" "$tmp/deploy/docker-compose.yml" \
+      || { rm -rf "$tmp"; die "无法保留 PostgreSQL 卷名，未替换现有资产。"; }
+  fi
+  # This retired overlay otherwise survives extraction and duplicates logging mounts.
+  [ -f "$tmp/deploy/onebox/docker-compose.portal-logs.yml" ] \
+    || rm -f "$home/onebox/docker-compose.portal-logs.yml"
+  ( cd "$tmp/deploy" && tar -cf - . ) | ( cd "$home" && tar -xf - )
+  rm -rf "$tmp"
+}
+
+cmd_upgrade() {
+  local image="" proxy=""
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --image) image="${2:?}"; shift 2 ;;
+      --proxy-image) proxy="${2:?}"; shift 2 ;;
+      *) die "upgrade: 不认识的参数 '$1'" ;;
+    esac
+  done
+  if [ -z "$image" ]; then
+    image="$(_eff XGENT_IMAGE)"
+    [ -n "$proxy" ] || proxy="$(_eff XGENT_PROXY_IMAGE)"
+  fi
+  [ -n "$image" ] || die "compose.env 缺 XGENT_IMAGE，请 upgrade --image <新版一盒镜像>。"
+  [ -n "$proxy" ] || proxy="${image%/*}/proxy:${image##*:}"
+  pull_images "$image" "$proxy"
+  # Retain the old volume identity even after down and with a custom volume name.
+  local postgres_volume; postgres_volume="$(_postgres_volume)" || die "无法确认升级前的 PostgreSQL 数据卷。"
+  _extract_assets "$image" "$HOME_DIR" "$postgres_volume"
+  _env_set XGENT_IMAGE "$image"
+  _env_set XGENT_PROXY_IMAGE "$proxy"
+  local version; version="$(_image_version "$image")"
+  [ -z "$version" ] || _env_set APP_VERSION "$version"
+  _objectstore_image
+  _pin_postgres "$postgres_volume"
+  _kafka_defaults
+  info "部署资产已升级；现有配置、generated/、backup/、端口与数据卷保留。"
+  info "下一步：$0 up（仍会重种门户库；App 自己的库不重置）。"
+}
+
 cmd_init() {
   local image="${XGENT_IMAGE:-}" proxy="" key="" home="./portal-onebox" force=0
   while [ $# -gt 0 ]; do
@@ -288,11 +372,11 @@ cmd_init() {
     --format '{{.Label "com.docker.compose.project"}}\t{{.Label "com.docker.compose.project.config_files"}}' 2>/dev/null \
     | awk -F'\t' -v h="$home/" '($1=="xgent-onebox" || $1 ~ /^onebox-/) && index($2, h)!=1 { print $1; exit }' || true)"
   if [ -n "$other" ]; then
-    [ "$force" = 1 ] || die "本机已有一套一盒（compose 项目 $other）—— 一台机器只共用一套，别再铺第二套。
+    [ "$force" = 1 ] || die "本机已有一套一盒（compose 项目 ${other}）—— 一台机器只共用一套，别再铺第二套。
 要调你的 App：XGENT_ONEBOX_HOME=<那套 portal-onebox/ 的路径> 复用它的栈跑 register-app / dc；
 宿主上的 dev 后端直连它的 pg/redis/minio（SKILL.md §5）。那套的路径查看：docker compose ls。
 确需整份重来（--force 会连 compose.env 一起重建）：$0 init --force …"
-    warn "本机已有另一套一盒（$other）—— --force 放行，但请确认那套已 down 掉，别长期并存。"
+    warn "本机已有另一套一盒（${other}）—— --force 放行，但请确认那套已 down 掉，别长期并存。"
   fi
 
   # 1) 备齐镜像 —— 没有 puller 凭证就在这里停下，而不是让人跑到一半才发现
@@ -304,29 +388,19 @@ cmd_init() {
   # （CR-4：自动授予租户那段代码比某一版镜像新一天，症状是市场里没有卡片且零报错）。
   # 这里把 tag + 镜像 ID + 构建日期钉进 compose.env，`/health` 与 `status` 立刻能回答
   # 「我跑的是哪一版」。取不到就留空，不编。
-  local img_id img_created ver=""
-  img_id="$(docker image inspect "$image" --format '{{.Id}}' 2>/dev/null | cut -c8-14 || true)"
-  img_created="$(docker image inspect "$image" --format '{{.Created}}' 2>/dev/null | cut -c1-10 || true)"
-  # 取不到镜像元信息（离线 load 的、docker 不认的）就留空 —— 宁可不自报，也不编一个版本号。
-  if [ -n "$img_id" ]; then ver="onebox ${image##*:} ${img_id}${img_created:+ built ${img_created}}"; fi
+  local ver; ver="$(_image_version "$image")"
 
   # 2) 从镜像里取 compose 资产 —— 版本天然与镜像对齐，不需要门户仓
-  info "从 $image 取出 compose 资产…"
-  local tmp cid; tmp="$(mktemp -d)"
-  cid="$(docker create "$image")" || die "docker create 失败。先 docker login 到镜像仓库，并确认 tag 写对了。"
-  docker cp "$cid:/app/deploy" "$tmp/deploy" >/dev/null || { docker rm -f "$cid" >/dev/null; die "镜像里没有 /app/deploy —— 这多半不是门户一盒镜像。"; }
-  docker rm -f "$cid" >/dev/null
-  # 只留联调用得上的：compose + 一盒增量 + devkit + postgres 建库脚本 + 两个 manifest 样例
-  ( cd "$tmp/deploy" && rm -rf .DS_Store k8s oauth pm2 caddy knowledge-devkit onebox/Dockerfile \
-      app-devkit/manifests/pagebuilder.manifest.json app-devkit/manifests/task-gateway.manifest.json 2>/dev/null || true )
-  ( cd "$tmp/deploy" && tar -cf - . ) | ( cd "$home" && tar -xf - )
-  rm -rf "$tmp"
+  _extract_assets "$image" "$home"
 
   # 3) 挑空闲端口 —— 首次用最常见的翻车就是 80/5432/6379/9000 已被别的东西占着
-  local hp hsp pgp rdp mnp mncp base
+  local hp hsp pgp rdp mnp mncp kfp base kafka_cluster_id kafka_password
   hp="$(pick_port 80 8080 8090 18080)"; hsp="$(pick_port 443 8443 18443)"
   pgp="$(pick_port 5432 15432 25432)"; rdp="$(pick_port 6379 16379 26379)"
   mnp="$(pick_port 9000 19000 29000)"; mncp="$(pick_port 9001 19001 29001)"
+  kfp="$(pick_port 9092 19092 29092)"
+  kafka_cluster_id="$(_kafka_cluster_id)" || die "无法生成 Kafka 集群 ID，初始化中止。"
+  kafka_password="$(_kafka_admin_password)" || die "无法生成 Kafka 管理密码，初始化中止。"
   base="http://localhost"; [ "$hp" = "80" ] || base="http://localhost:$hp"
 
   # 4) 三段模板 + 本机覆盖块（覆盖块必须在最末尾）
@@ -355,6 +429,9 @@ POSTGRES_PORT=$pgp
 REDIS_PORT=$rdp
 MINIO_PORT=$mnp
 MINIO_CONSOLE_PORT=$mncp
+KAFKA_PORT=$kfp
+KAFKA_CLUSTER_ID=$kafka_cluster_id
+KAFKA_ADMIN_PASSWORD=$kafka_password
 PORTAL_BASE_URL=$base
 FILES_APP_URL=$base
 
@@ -379,6 +456,7 @@ APP_IMAGE=
 # micro（有前端、iframe 嵌入）才要，且必须是【绝对路径】、目录里有 index.html：
 #APP_FRONTEND_DIST=/abs/path/to/your/frontend/dist
 EOF
+  chmod 600 "$envf" || die "无法保护 compose.env 权限，初始化中止。"
 
   # 5) 别让它进版本库：里面是密钥，且随时能从镜像重新生成
   local root; root="$(git rev-parse --show-toplevel 2>/dev/null || true)"
@@ -390,18 +468,15 @@ EOF
   echo
   printf '%s一盒资产就位：%s%s\n' "$c_grn" "$home" "$c_off"
   printf '  门户地址   %s\n' "$base"
-  printf '  端口       http=%s pg=%s redis=%s minio=%s/%s\n' "$hp" "$pgp" "$rdp" "$mnp" "$mncp"
+  printf '  端口       http=%s pg=%s redis=%s minio=%s/%s kafka=%s\n' "$hp" "$pgp" "$rdp" "$mnp" "$mncp" "$kfp"
   printf '  项目名     xgent-onebox（全机一套共用，别改名）\n'
   echo
   echo "下一步（顺序本身是契约，见 SKILL.md §3）。先记一个短名："
   echo "  S=$0"
   echo
   echo "  1. 编辑 $envf 末尾：填 APP_IMAGE（micro 再加 APP_FRONTEND_DIST）"
-  echo "  2. \$S dc up -d postgres redis minio"
-  echo "  3. \$S dc run --rm portal-api bun run db:migrate"
-  echo "  4. \$S dc run --rm portal-api bun run db:seed:onebox"
-  echo "  5. \$S dc run --rm -v \"\$PWD/<放 manifest 的目录>:/devkit:ro\" portal-api bun run register-app /devkit/app.manifest.json"
-  echo "  6. \$S dc up -d   然后  \$S smoke"
+  echo "  2. \$S up"
+  echo "  3. \$S doctor"
 }
 
 cmd_pull() {
@@ -424,7 +499,7 @@ cmd_pull() {
   do_pull "$image" "tag 写错了？一盒只有两种：:latest（可变指针，跟着最新一版走）和 :v<版本>-<7位sha>（钉住某一版）。"
   do_pull "$proxy" "代理镜像名是从 runtime 镜像推出来的，有的部署不叫 proxy —— 用 --proxy-image 指定。"
   printf '%s两个镜像就位%s\n' "$c_grn" "$c_off"
-  echo "换版本的话，记得同步 compose.env 末尾的 XGENT_IMAGE / XGENT_PROXY_IMAGE，再 dc up -d"
+  echo "镜像就位后跑 $0 upgrade --image ${image} --proxy-image ${proxy}，再跑 $0 up。"
 }
 
 # --- 其余子命令 ---------------------------------------------------------------
@@ -434,7 +509,7 @@ cmd_env() {
   echo
   local k v n
   for k in COMPOSE_PROJECT_NAME XGENT_IMAGE XGENT_PROXY_IMAGE XGENT_APP_CATALOG NODE_ENV DEV_MOCK_OAUTH \
-           HTTP_PORT HTTPS_PORT POSTGRES_PORT REDIS_PORT MINIO_PORT MINIO_CONSOLE_PORT PORTAL_BASE_URL \
+           HTTP_PORT HTTPS_PORT POSTGRES_PORT REDIS_PORT MINIO_PORT MINIO_CONSOLE_PORT KAFKA_PORT PORTAL_BASE_URL \
            APP_KEY APP_IMAGE APP_FRONTEND_DIST PREVIEW_MEDIA_CONVERTER_URL; do
     v="$(_eff "$k")"
     n="$(_assignments | awk -F'\t' -v k="$k" '$2==k{seen[$3]=1} END{print length(seen)}')"
@@ -511,14 +586,14 @@ cmd_status() {
   for cid in $(dc ps -q 2>/dev/null || true); do
     tst="$(docker inspect "$cid" --format '{{json .Config.Healthcheck.Test}}' 2>/dev/null || true)"
     case "$tst" in
-      *"curl -fsS http"*|*"wget -q -O /dev/null http://127.0.0.1:80/"*)
+      *"curl -fsS http://127.0.0.1:8080/health"*|*"wget -q -O /dev/null http://127.0.0.1:80/"*)
         nm="$(docker inspect "$cid" --format '{{.Name}}' 2>/dev/null | sed 's#^/##')"
         stale="$stale ${nm:-$cid}" ;;
     esac
   done
   if [ -n "$stale" ]; then
     warn "这些容器的 healthcheck 还是旧镜像里那条永远失败的探针，它们的 unhealthy 是假红（判活只看下面的探测）：$stale"
-    _note "新镜像已换成 bun / 不跟随重定向的 curl。$0 pull 换新镜像 + $0 init --force 重铺 compose 之后，unhealthy 就是真红。"
+    _note "新镜像已换成 bun / 不跟随重定向的 curl。$0 pull 后跑 $0 upgrade，再跑 $0 up；upgrade 保留配置与数据。"
   else
     _note "healthcheck 都是新探针 —— 这里的 unhealthy 就是真红，别当假红放过去（先看 $0 dc logs <服务>）。"
   fi
@@ -530,19 +605,305 @@ cmd_status() {
 _env_set() { # _env_set KEY VALUE —— 追加到 compose.env 末尾（后定义者胜），已是同值则跳过
   local k="$1" v="$2"
   [ "$(_eff "$k")" = "$v" ] && return 0
-  printf '%s=%s\n' "$k" "$v" >> "$ENV_FILE"
+  printf '%s=%s\n' "$k" "$v" >> "$ENV_FILE" || die "无法写入 compose.env，操作中止。"
   info "compose.env += ${k}=${v}"
 }
+_env_append_secret() {
+  printf '%s=%s\n' "$1" "$2" >> "$ENV_FILE" || die "无法写入 compose.env，操作中止。"
+  info "compose.env += ${1}=***"
+}
+_kafka_cluster_id() {
+  local value
+  value="$(openssl rand -base64 16 | tr '+/' '-_' | tr -d '=')" || return 1
+  [ "${#value}" = 22 ] || return 1
+  printf '%s' "$value"
+}
+_kafka_admin_password() {
+  local value
+  value="$(openssl rand -hex 24)" || return 1
+  [ "${#value}" = 48 ] || return 1
+  printf '%s' "$value"
+}
+_kafka_defaults() {
+  # Only absent keys are filled. An existing cluster ID/password must never rotate.
+  local value
+  if ! grep -q '^KAFKA_CLUSTER_ID=' "$ENV_FILE"; then
+    value="$(_kafka_cluster_id)" || die "无法生成 Kafka 集群 ID，升级中止。"
+    _env_set KAFKA_CLUSTER_ID "$value"
+  fi
+  if ! grep -q '^KAFKA_ADMIN_PASSWORD=' "$ENV_FILE"; then
+    value="$(_kafka_admin_password)" || die "无法生成 Kafka 管理密码，升级中止。"
+    _env_append_secret KAFKA_ADMIN_PASSWORD "$value"
+  fi
+  if ! grep -q '^KAFKA_PORT=' "$ENV_FILE"; then _env_set KAFKA_PORT "$(pick_port 9092 19092 29092)"; fi
+  chmod 600 "$ENV_FILE" || die "无法保护 compose.env 权限，升级中止。"
+}
+_kafka_assets_current() {
+  grep -qE '^  kafka:' "$HOME_DIR/docker-compose.yml" \
+    && grep -q '^KAFKA_CLUSTER_ID=' "$ENV_FILE" \
+    && grep -q '^KAFKA_ADMIN_PASSWORD=' "$ENV_FILE" \
+    && grep -q '^KAFKA_PORT=' "$ENV_FILE"
+}
+_require_kafka_assets() {
+  _kafka_assets_current || die "一盒 Kafka 资产或配置是旧版，先跑 $0 upgrade --image <新版一盒镜像>，再跑 $0 up。"
+}
+_kafka_up() {
+  local deadline cid state
+  if ! dc up -d kafka </dev/null; then
+    warn "Kafka 启动失败，门户继续；查看下方日志。"
+    dc logs --tail 50 kafka </dev/null || true
+    return 0
+  fi
+  deadline=$((SECONDS+60))
+  while [ "$SECONDS" -lt "$deadline" ]; do
+    cid="$(dc ps -q kafka </dev/null 2>/dev/null || true)"; state=''
+    [ -z "$cid" ] || state="$(docker inspect --format '{{if .State.Health}}{{.State.Health.Status}}{{end}}' "$cid" </dev/null 2>/dev/null || true)"
+    if [ "$state" = healthy ]; then info "Kafka: healthy"; return 0; fi
+    [ "$SECONDS" -ge "$deadline" ] || sleep 1
+  done
+  warn "Kafka 60s 内未健康，门户继续；依赖 Kafka 的应用需等服务恢复。"
+  dc logs --tail 50 kafka </dev/null || true
+  return 0
+}
+_ensure_kafka() { # _ensure_kafka LISTING_KEY ENV_PREFIX
+  local key="$1" prefix="$2" username password admin deadline
+  [[ "$key" =~ ^[a-z0-9][a-z0-9-]*$ ]] || return 1
+  _kafka_assets_current || return 1
+  dc up -d kafka </dev/null >/dev/null 2>&1 || return 1
+  deadline=$((SECONDS+60))
+  until dc exec -T kafka nc -z 127.0.0.1 9092 </dev/null >/dev/null 2>&1; do
+    [ "$SECONDS" -lt "$deadline" ] || return 1
+    sleep 1
+  done
+  username="app_${key//-/_}"
+  password="$(_eff "${prefix}_KAFKA_PASSWORD")"
+  if [ -z "$password" ]; then
+    password="$(_kafka_admin_password)" || return 1
+    # Persist before contacting the broker: a partial ACL failure must reuse this password.
+    _env_append_secret "${prefix}_KAFKA_PASSWORD" "$password"
+  fi
+  admin="$(_eff KAFKA_ADMIN_PASSWORD)"
+  [ -n "$admin" ] || return 1
+  case "$admin" in *$'\n'*|*$'\r'*) return 1 ;; esac
+  # Generated passwords are hex; preserve existing safe base64/url-safe passwords too.
+  [[ "$password" =~ ^[A-Za-z0-9_+/=-]+$ ]] || return 1
+  chmod 600 "$ENV_FILE" || return 1
+  # Secrets enter through stdin, never command arguments or raw CLI output. The temporary
+  # properties live only inside the broker and are removed on success, failure or signal.
+  # shellcheck disable=SC2016
+  if ! printf '%s\n%s\n' "$admin" "$password" | dc exec -T kafka bash -ec '
+    umask 077
+    IFS= read -r admin
+    IFS= read -r password
+    dir=$(mktemp -d /tmp/xgent-kafka-admin.XXXXXX)
+    trap '\''rm -rf "$dir"'\'' EXIT
+    trap '\''exit 1'\'' HUP INT TERM
+    escaped=${admin//\\/\\\\}; escaped=${escaped//\"/\\\"}
+    jaas="org.apache.kafka.common.security.plain.PlainLoginModule required username=\"admin\" password=\"$escaped\";"
+    printf "security.protocol=SASL_PLAINTEXT\nsasl.mechanism=PLAIN\nsasl.jaas.config=%s\nrequest.timeout.ms=10000\ndefault.api.timeout.ms=15000\n" "${jaas//\\/\\\\}" > "$dir/admin.properties"
+    printf "SCRAM-SHA-512=iterations=8192,password=%s\n" "$password" > "$dir/scram.properties"
+    /opt/kafka/bin/kafka-configs.sh --bootstrap-server kafka:9092 --command-config "$dir/admin.properties" --alter --add-config-file "$dir/scram.properties" --entity-type users --entity-name "$1"
+    acl=(--bootstrap-server kafka:9092 --command-config "$dir/admin.properties" --add --allow-principal "User:$1" --allow-host "*" --resource-pattern-type prefixed)
+    /opt/kafka/bin/kafka-acls.sh "${acl[@]}" --topic "$2" --operation Create --operation Delete --operation Describe --operation DescribeConfigs --operation Read --operation Write
+    /opt/kafka/bin/kafka-acls.sh "${acl[@]}" --group "$2" --operation Read --operation Describe --operation Delete
+    /opt/kafka/bin/kafka-acls.sh "${acl[@]}" --transactional-id "$2" --operation Write --operation Describe
+  ' bash "$username" "app.${key}." >/dev/null 2>&1; then return 1; fi
+  _env_set "${prefix}_KAFKA_BROKERS" kafka:9092
+  _env_set "${prefix}_KAFKA_USERNAME" "$username"
+  _env_set "${prefix}_KAFKA_SASL_MECHANISM" SCRAM-SHA-512
+  _env_set "${prefix}_KAFKA_TOPIC_PREFIX" "app.${key}."
+  info "Kafka 用户 ${username} 与前缀 app.${key}. 就绪"
+}
+_kafka_add_warning() {
+  warn "Kafka 供给失败；门户与应用初始化继续。已保存的密码保持不变，检查 Kafka 日志后重试："
+  printf '  XGENT_ONEBOX_HOME=%q bash %q add %q' "$HOME_DIR" "$0" "$1"
+  [ -z "${ADD_MANIFEST:-}" ] || printf ' --manifest %q' "$ADD_MANIFEST"
+  [ -z "${ADD_FROM:-}" ] || printf ' --from %q' "$ADD_FROM"
+  printf '\n'
+  _note "手工修复命令见《平台 Kafka 接入指引》的一盒故障恢复；不要把管理员密码填进 App requiredEnv。"
+}
+_portal_services_up() {
+  # Kafka has its own non-blocking startup; do not retry it in the hard-fail group.
+  local enabled svc services=()
+  enabled="$(dc config --services)" || die "无法读取一盒服务清单。"
+  while IFS= read -r svc; do
+    [ -z "$svc" ] || [ "$svc" = kafka ] || services+=("$svc")
+  done <<< "$enabled"
+  [ "${#services[@]}" -gt 0 ] || die "一盒服务清单为空。"
+  dc up -d "${services[@]}"
+}
 _svc_running() { [ -n "$(dc ps -q "$1" 2>/dev/null || true)" ]; }
+# v1 的放行表只在 Caddy load 时读取；v2 由唯一发布器生成、验证并应用整代配置。
+# 必须先询问镜像的受管 selector；模式损坏时不能按旧镜像降级，更不能重读兼容模板。
+_reload_proxy() {
+  _svc_running reverse-proxy || return 0
+  local selected out
+  if ! selected="$(dc exec -T reverse-proxy sh -c '
+    selector=/usr/local/libexec/xgent-gateway-config
+    if [ -e "$selector" ] || [ -L "$selector" ]; then
+      [ -f "$selector" ] && [ -x "$selector" ] || exit 1
+      exec "$selector"
+    fi
+    # 旧镜像只有完全没有受管状态时才允许兼容 reload。
+    for path in /etc/caddy/sites/gateway-v2.enabled /etc/caddy/sites/current /etc/caddy/gateway-operation.conf; do
+      if [ -e "$path" ] || [ -L "$path" ]; then exit 1; fi
+    done
+    printf "/etc/caddy/Caddyfile\n"
+  ' 2>/dev/null)"; then
+    die "无法确认反代模式；已停止 reload。请检查受管模式与 current 快照，再按网关维护文档恢复。"
+  fi
+  case "$selected" in
+    /etc/caddy/Caddyfile) ;;
+    /*/current/Caddyfile)
+      info "   反代为 v2，路由变更由唯一发布器应用；请查看发布状态确认结果"
+      return 0 ;;
+    *) die "反代模式返回无效；已停止 reload，不会回退到兼容模板。" ;;
+  esac
+  if out="$(dc exec -T reverse-proxy caddy reload --config /etc/caddy/Caddyfile --adapter caddyfile 2>&1)"; then
+    info "   反代已重读 /svc 放行表"
+  else
+    warn "反代重读失败，/svc 仍是改动前那份：$(printf '%s' "$out" | tail -2 | tr '\n' ' ')"
+  fi
+}
 _ok()   { printf '  %s✓%s %s\n' "$c_grn" "$c_off" "$*"; }
 _bad()  { printf '  %s✗%s %s\n' "$c_red" "$c_off" "$1"; shift; [ $# -gt 0 ] && printf '      %s↳ %s%s\n' "$c_dim" "$*" "$c_off"; DOCTOR_BAD=$((DOCTOR_BAD+1)); return 0; }
 _note() { printf '      %s↳ %s%s\n' "$c_dim" "$*" "$c_off"; }
 
 # --- up：按顺序铺一遍（幂等）---------------------------------------------------
+_objectstore_assets_current() {
+  grep -qE '^  rustfs:' "$HOME_DIR/docker-compose.yml" \
+    && [ -f "$HOME_DIR/scripts/objectstore-cutover.sh" ] \
+    && [ -f "$HOME_DIR/scripts/objectstore-manifest.ts" ]
+}
+_require_objectstore_assets() {
+  _objectstore_assets_current || die "一盒资产是旧版，先跑 $0 upgrade --image <新版一盒镜像>，再跑 $0 up。"
+}
+_objectstore_image() {
+  local image
+  image="$(dc config --images rustfs)" || die "无法读取 RustFS 镜像配置；旧对象存储未切换。"
+  [ -n "$image" ] || die "Compose 配置里没有 RustFS 镜像；旧对象存储未切换。"
+  docker image inspect "$image" >/dev/null 2>&1 && return 0
+  dc pull rustfs </dev/null || die "RustFS 镜像尚未就位；拉取失败，旧对象存储未切换。修复镜像拉取后重跑。"
+}
+
+# An asset upgrade must not upgrade/downgrade an existing PostgreSQL data directory.
+# Inspect only this project's real mount, then read it through a read-only container.
+_postgres_volume() {
+  local project ids cid volume volumes configured
+  project="$(_eff COMPOSE_PROJECT_NAME xgent-onebox)"
+  ids="$(docker ps -aq --filter "label=com.docker.compose.project=$project" --filter label=com.docker.compose.service=postgres)" \
+    || die "无法检查本项目 PostgreSQL 容器；未启动服务。"
+  if [ -n "$ids" ]; then
+    [ "$(printf '%s\n' "$ids" | wc -l | tr -d ' ')" = 1 ] || die "本项目有多个 PostgreSQL 容器，无法确定权威数据卷；请人工确认，勿删卷。"
+    cid="$ids"
+    volume="$(docker inspect "$cid" --format '{{range .Mounts}}{{if eq .Type "volume"}}{{if or (eq .Destination "/var/lib/postgresql") (eq .Destination "/var/lib/postgresql/data")}}{{println .Name}}{{end}}{{end}}{{end}}')" \
+      || die "无法读取 PostgreSQL 挂载，勿删卷。"
+    [ -n "$volume" ] && [ "$(printf '%s\n' "$volume" | wc -l | tr -d ' ')" = 1 ] \
+      || die "PostgreSQL 挂载不是唯一命名卷；请人工确认，勿删卷。"
+  else
+    volume="$(docker volume ls --filter "label=com.docker.compose.project=$project" --filter label=com.docker.compose.volume=pg-data --format '{{.Name}}')" \
+      || die "无法查询 PostgreSQL 数据卷；未启动服务。"
+    if [ -n "$volume" ]; then
+      [ "$(printf '%s\n' "$volume" | wc -l | tr -d ' ')" = 1 ] || die "本项目有多个 pg-data 卷，拒绝自动选择。"
+    else
+      configured="$(awk '
+        /^volumes:/{volumes=1; next}
+        volumes && /^  pg-data:/{pg=1; next}
+        volumes && /^  [A-Za-z0-9_-]+:/{pg=0}
+        pg && /^    name:/{sub(/^    name:[[:space:]]*/, ""); print}
+      ' "$HOME_DIR/docker-compose.yml" | sed "s/^[\"']//; s/[\"']$//")"
+      volume="${configured:-${project}_pg-data}"
+      [[ "$volume" =~ ^[A-Za-z0-9][A-Za-z0-9_.-]*$ ]] || die "pg-data 自定义卷名无法确定；请人工确认，勿删卷。"
+      volumes="$(docker volume ls --format '{{.Name}}')" || die "无法查询 Docker 数据卷；未启动服务。"
+      printf '%s\n' "$volumes" | grep -qxF "$volume" || return 0
+    fi
+  fi
+  printf '%s' "$volume"
+}
+_pin_postgres() {
+  local volume state major layout file next
+  if [ $# -gt 0 ]; then volume="$1"
+  else volume="$(_postgres_volume)" || die "无法确认 PostgreSQL 数据卷；未启动服务。"; fi
+  [ -n "$volume" ] || return 0
+  state="$(docker run --rm --network none -u 0 --entrypoint sh -v "$volume:/probe:ro" rustfs/rustfs:1.0.0 -c '
+    set -eu
+    count=0
+    for f in /probe/PG_VERSION /probe/[0-9]*/docker/PG_VERSION; do
+      [ -f "$f" ] || continue
+      count=$((count+1)); major=$(cat "$f")
+      if [ "$f" = /probe/PG_VERSION ]; then layout=legacy
+      elif [ "$f" = "/probe/$major/docker/PG_VERSION" ]; then layout=parent
+      else echo unknown; exit 1; fi
+      printf "%s %s\n" "$major" "$layout"
+    done
+    if [ "$count" = 0 ]; then
+      if [ -z "$(ls -A /probe)" ]; then echo empty; else echo unknown; fi
+    fi
+  ' </dev/null)" || die "PostgreSQL 只读卷检查失败；未启动服务，勿删卷。"
+  [ "$state" = empty ] && return 0
+  [ "$(printf '%s\n' "$state" | wc -l | tr -d ' ')" = 1 ] \
+    || die "PostgreSQL 卷内有多个版本目录，拒绝自动选择；勿删卷。"
+  major="${state%% *}"; layout="${state#* }"
+  [[ "$major" =~ ^[1-9][0-9]$ ]] || die "PostgreSQL 卷布局或版本未知；拒绝启动，勿删卷。"
+  if [ "$layout" = legacy ] && [ "$major" -lt 18 ]; then
+    layout=/var/lib/postgresql/data
+  elif [ "$layout" = parent ] && [ "$major" -ge 18 ]; then
+    layout=/var/lib/postgresql
+  else
+    die "PostgreSQL 版本与目录布局不一致；拒绝启动，勿删卷。"
+  fi
+  file="$HOME_DIR/docker-compose.yml"; next="$(mktemp "$HOME_DIR/.postgres-compose.XXXXXX")"
+  if ! awk -v major="$major" -v mount="$layout" -v volume="$volume" '
+    /^  postgres:/{svc=1; print; next}
+    svc && /^  [A-Za-z0-9_-]+:/{svc=0}
+    /^volumes:/{svc=0; volumes=1}
+    svc && /^    image:/{print "    image: postgres:" major "-alpine"; images++; next}
+    svc && /^[[:space:]]*- pg-data:\/var\/lib\/postgresql(\/data)?[[:space:]]*$/{print "      - pg-data:" mount; mounts++; next}
+    volumes && /^  pg-data:/{print "  pg-data:"; print "    name: " volume; named=1; names++; next}
+    volumes && /^  [A-Za-z0-9_-]+:/{named=0}
+    named && /^    name:/{next}
+    {print}
+    END{if(images!=1 || mounts!=1 || names!=1)exit 1}
+  ' "$file" > "$next"; then
+    rm -f "$next"; die "PostgreSQL compose 布局不符合预期，未覆盖文件；请人工确认，勿删卷。"
+  fi
+  # 运行中的 portal-api / controller 按 inode 单文件挂载它；内容没变就不换文件，免得它们读到已删除的旧文件。
+  if cmp -s "$next" "$file"; then rm -f "$next"
+  else mv "$next" "$file" || { rm -f "$next"; die "无法保存 PostgreSQL 版本保护；未启动服务。"; }; fi
+  info "PostgreSQL 存量卷保持 PG${major} 与 ${layout} 挂载；大版本迁移需另行安排。"
+}
+
+_objectstore_up() {
+  _require_objectstore_assets
+  _objectstore_image
+  local code deadline
+  if "$HOME_DIR/scripts/objectstore-cutover.sh" \
+    --project "$(_eff COMPOSE_PROJECT_NAME xgent-onebox)" --env-file "$ENV_FILE" \
+    --backup-dir "$HOME_DIR/backup" </dev/null; then
+    :
+  else
+    code=$?
+    die "对象存储切换中止（退出 ${code}）；按上方提示处理，未启动正式 RustFS。"
+  fi
+  dc up -d rustfs </dev/null || die "RustFS 启动失败；已过提交点，rustfs-data 是权威，勿删。看 $0 dc logs rustfs；回退只执行 $HOME_DIR/backup/rollback-minio.sh。"
+  deadline=$((SECONDS+60))
+  while [ "$SECONDS" -lt "$deadline" ]; do
+    if dc exec -T rustfs curl -fsS --max-time 1 http://127.0.0.1:9000/health </dev/null >/dev/null 2>&1; then return 0; fi
+    [ "$SECONDS" -ge "$deadline" ] || sleep 1
+  done
+  die "RustFS 60s 未就绪；已过提交点，rustfs-data 是权威，勿删。看 $0 dc logs rustfs；回退只执行 $HOME_DIR/backup/rollback-minio.sh。"
+}
+
 cmd_up() {
+  _require_objectstore_assets
+  _require_kafka_assets
   [ -n "$APP_KEY" ] || die "compose.env 里还没有 APP_KEY —— 先跑 $0 init --key <你的listingKey>。"
-  info "① 基础设施（postgres / redis / minio）"
-  dc up -d postgres redis minio
+  info "① 基础设施（postgres / redis / RustFS / Kafka）"
+  _objectstore_image
+  _pin_postgres
+  _objectstore_up
+  dc up -d postgres redis
+  _kafka_up
   info "   等 postgres 就绪…"
   # 首次初始化时 initdb 会先起一个临时实例再重启，单次 pg_isready 会在那个窗口里误判就绪，
   # 紧接着的 db:migrate 就撞 ECONNREFUSED（实测）。要求连续 3 秒都就绪才算。
@@ -557,8 +918,7 @@ cmd_up() {
   #    逐租户基线（org 的预置档案字段就是这么来的），表还没建就只能眼看着它失败。
   local k
   for k in ${CATALOG//,/ }; do
-    # qbank/lms 是 QBANK-WORKFLOW-ACTIONS §5.9 的变体成员；基础集不含它们时这段零执行。
-    case "$k" in files|llm-gateway|git|org|qbank|lms) dc run --rm portal-api bun run "db:$k:migrate" || warn "db:$k:migrate 失败，继续";; esac
+    case "$k" in files|llm-gateway|git|org) dc run --rm portal-api bun run "db:$k:migrate" || warn "db:$k:migrate 失败，继续";; esac
   done
   info "②b 你自己的库 xgent-${APP_KEY}"
   _ensure_db "xgent-${APP_KEY}"
@@ -580,7 +940,8 @@ cmd_up() {
     info "④b 目录里的清单型 App：${mk}"
     ADD_QUIET=1 cmd_add "$mk" || warn "add ${mk} 失败 —— 看上面的报错；修完重跑 $0 up（幂等）"
   done
-  info "⑤ 起门户三件套 + 基础服务" ; dc up -d
+  info "⑤ 起门户三件套 + 基础服务" ; _portal_services_up
+  _reload_proxy
   _has_catalog observability && _portal_logs_up
   echo; info "跑一次体检："; cmd_doctor
 }
@@ -597,7 +958,7 @@ _portal_logs_up() {
     # 容器的 workdir 是 /app（monorepo 根），脚本在 apps/api 下；不走 package script 是因为它带 --env-file=../../.env，镜像里没有那份文件。
     sec="$(dc run --rm --no-deps -T -w /app/apps/api portal-api bun run scripts/portal-logs-key.ts 2>"$err")" || rc=$?
     if [ "$rc" -eq 0 ] && [ -n "$sec" ]; then
-      _env_set OBS_ACCESS_KEY "$sec"
+      _env_append_secret OBS_ACCESS_KEY "$sec"
     else
       warn "采集密钥没签成（rc=${rc}）：$(grep -v xsak_ "$err" | tail -3 | tr '\n' ' ')"; rm -f "$err"; return 0
     fi
@@ -607,13 +968,18 @@ _portal_logs_up() {
   _ok "portal-logs 已起；portal-api 的 stdout/stderr 经 fluentd 驱动进 app_portal_console（观测：$0 dc logs portal-logs）"
 }
 
-# 在一盒 minio 上建桶（幂等）。minio 镜像自带 mc；凭证就是 compose.env 里的 MINIO_ROOT_USER/PASSWORD。
+# 使用 RustFS 自带 curl 与容器内凭据建桶；不依赖已停止分发的 mc。
 _ensure_bucket() { # _ensure_bucket <bucket>
-  local u p; u="$(_eff MINIO_ROOT_USER minioadmin)"; p="$(_eff MINIO_ROOT_PASSWORD minioadmin)"
-  dc up -d minio >/dev/null 2>&1 || true
-  local i=0; until dc exec -T minio mc ready local >/dev/null 2>&1; do i=$((i+1)); [ "$i" -gt 30 ] && { warn "minio 30s 没就绪，桶 $1 没建"; return 0; }; sleep 1; done
-  dc exec -T minio sh -c "mc alias set local http://127.0.0.1:9000 '$u' '$p' >/dev/null 2>&1 && mc mb --ignore-existing local/$1" >/dev/null 2>&1 \
-    && info "桶 $1 就绪" || warn "桶 $1 没建成（$0 dc exec minio mc mb local/$1 手工补）"
+  local bucket="$1"
+  [[ "$bucket" =~ ^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$ ]] || die "对象存储桶名不合法。"
+  _objectstore_up
+  # Credentials and bucket positional argument expand in the container shell.
+  # shellcheck disable=SC2016
+  if dc exec -T rustfs sh -c 'exec curl -fsS --max-time 10 --retry 10 --retry-delay 1 --retry-all-errors \
+    --aws-sigv4 "aws:amz:us-east-1:s3" --user "$RUSTFS_ACCESS_KEY:$RUSTFS_SECRET_KEY" \
+    -X PUT "http://127.0.0.1:9000/$1"' sh "$bucket" </dev/null >/dev/null; then
+    info "桶 ${bucket} 就绪"
+  else die "桶 ${bucket} 没建成；检查 $0 dc logs rustfs，修复后重跑原命令。"; fi
 }
 _ensure_db() { # _ensure_db <dbname>
   if dc exec -T postgres psql -U postgres -lqt 2>/dev/null | cut -d'|' -f1 | grep -qw "$1"; then
@@ -679,6 +1045,9 @@ _manifest_json() { # _manifest_json KEY  → 把 manifest JSON 打到 stdout
 }
 
 cmd_add() {
+  _require_objectstore_assets
+  _objectstore_image
+  _pin_postgres
   local key="" want_image=""
   ADD_MANIFEST=""; ADD_FROM=""
   while [ $# -gt 0 ]; do
@@ -702,6 +1071,8 @@ cmd_add() {
 
   # 用 portal-api 里的 bun 解析（不对宿主机的 python/jq 做任何假设）
   local fields
+  # JavaScript template expressions must reach Bun without shell expansion.
+  # shellcheck disable=SC2016
   fields="$(printf '%s' "$mj" | dc run --rm --no-deps -T portal-api bun -e '
     let raw=""; for await (const c of Bun.stdin.stream()) raw += new TextDecoder().decode(c);
     const m = JSON.parse(raw); const d = m.deployDescriptor ?? {};
@@ -713,20 +1084,43 @@ cmd_add() {
     console.log(`M_HEALTH=${q(d.healthPath ?? "/health")}`);
     console.log(`M_SA=${q((m.serviceAccount ?? {}).clientId)}`);
     console.log(`M_ENV=${(m.requiredEnv ?? []).map((e) => (typeof e === "string" ? e : e.key)).join(" ")}`);
+    console.log(`M_KAFKA=${(m.requiredServices ?? []).some((s) => s.kind === "kafka") ? "1" : "0"}`);
     // 非空 ⇒ 它是跨应用交换的【发起方】，需要一把 App Secret（下面与 SA 密钥同源生成注入）。
     console.log(`M_XTARGETS=${(m.exchangeTargets ?? []).join(" ")}`);
     console.log(`M_MIGRATE=${(d.migrateArgs ?? []).join(" ")}`);
+    console.log(`M_DEPS=${(m.dependencies ?? []).join(" ")}`);
   ' 2>/dev/null)" || die "解析清单失败 —— 它可能不是一份合法的 app.manifest.json。"
-  local M_KEY="" M_TYPE="" M_IMAGE="" M_PORT="" M_HEALTH="" M_SA="" M_ENV="" M_XTARGETS="" M_MIGRATE=""
+  local M_KEY="" M_TYPE="" M_IMAGE="" M_PORT="" M_HEALTH="" M_SA="" M_ENV="" M_KAFKA="" M_XTARGETS="" M_MIGRATE="" M_DEPS=""
   eval "$(printf '%s' "$fields" | sed 's/^\([A-Z_]*\)=\(.*\)$/\1="\2"/')"
   [ "$M_KEY" = "$key" ] || die "清单里的 listingKey 是「${M_KEY}」，与你要加的「${key}」对不上。"
   info "   ${M_KEY}  type=${M_TYPE}  port=${M_PORT}  sa=${M_SA}"
 
+  # 依赖预检：register-app 要求 dependencies 里每个 key 在【这台门户】已有清单，否则
+  # DEPENDENCY_UNAVAILABLE —— 而且只报第一个、带一屏堆栈。拉镜像之前一次点名全部缺的。
+  # 只卡「有没有清单」：装不装由「应用管理 → 应用市场」安装时按依赖一并装上，不归这里。
+  if [ -n "$M_DEPS" ]; then
+    dc up -d postgres >/dev/null 2>&1 || true
+    local rows dep dmiss=""
+    if rows="$(dc exec -T postgres psql -U postgres -d "$(_eff POSTGRES_DB xgent-portal)" -tAc 'select listing_key from marketplace_listings' 2>/dev/null)"; then
+      rows=" $(printf '%s' "$rows" | tr -d '\r' | tr '\n' ' ') "
+      for dep in $M_DEPS; do
+        _is_portal_hosted "$dep" && continue
+        case "$rows" in *" $dep "*) ;; *) dmiss="${dmiss:+$dmiss }$dep" ;; esac
+      done
+    else
+      warn "读不到本地门户的清单表（postgres 还没就绪或还没 migrate），跳过依赖预检，交给 register-app 判。"
+    fi
+    [ -z "$dmiss" ] || die "「${key}」依赖 ${dmiss}，这台一盒里还没有它们的清单 —— 直接注册会被拒（DEPENDENCY_UNAVAILABLE）。
+先逐个 ${0} add <依赖>（配了 MANIFEST_STORE 就从目录取清单；镜像在 <REGISTRY>/<ONEBOX_PROJECT>/ 下，清单没写 deployDescriptor.image 时加 --image <全引用>），再重跑 ${0} add ${key}。
+之后在「应用管理 → 应用市场」里安装 ${key}，依赖会被一并装上、自动授予。"
+  fi
+
   # ② 镜像：清单里的相对名按 <REGISTRY>/<ONEBOX_PROJECT>/ 补全（版本由清单钉住，可复现）
   local ivar ref; ivar="$(printf '%s' "$key" | tr 'a-z-' 'A-Z_')_IMAGE"
   ref="${want_image:-$(_eff "$ivar")}"
   if [ -z "$ref" ]; then
-    [ -n "$M_IMAGE" ] || die "清单里没有 deployDescriptor.image，也没给 --image。"
+    [ -n "$M_IMAGE" ] || die "清单里没有 deployDescriptor.image，也没给 --image。
+陪调用的平台侧 App 镜像在 ${REGISTRY:-<REGISTRY>}/${ONEBOX_PROJECT:-${PROJECT:-<ONEBOX_PROJECT>}}/${key}:<tag> 下 —— 用 --image 给全引用（tag 找门户团队确认），并请该 App 在清单里补上 deployDescriptor.image。"
     case "$M_IMAGE" in
       */*) ref="$M_IMAGE" ;;                       # 已经带项目/域名，原样用
       *) load_registry_config || true
@@ -738,20 +1132,32 @@ cmd_add() {
   if docker image inspect "$ref" >/dev/null 2>&1; then info "   本地已有，跳过拉取"
   else
     require_puller; registry_login
-    do_pull "$ref" "配合调试用的 App 都发在一盒同一个项目（ONEBOX_PROJECT=${ONEBOX_PROJECT:-未配}）下；确实不在就用 --image 给全引用。"
+    # 只发了 amd64 的镜像（buildx 默认带 attestation，推上去是个 index）在 Apple Silicon 上裸 pull
+    # 报 no matching manifest。本机没指定平台、裸 pull 又失败时，看它有没有 amd64 那一份：有就按
+    # amd64 拉（走仿真），并把 <PREFIX>_PLATFORM 记进 compose.env —— 生成片段的 platform: 读它。
+    # 其它失败原因（项目 / tag 不对、没权限）由 do_pull 原样报。
+    local pvar plat; pvar="${ivar%_IMAGE}_PLATFORM"; plat="$(_eff "$pvar" "$(_eff APP_PLATFORM)")"
+    [ -n "$plat" ] || info "拉 ${ref} …"
+    if [ -n "$plat" ] || ! docker pull "$ref" >/dev/null 2>&1; then
+      if [ -z "$plat" ] && docker manifest inspect "$ref" 2>/dev/null | grep -Eq '"architecture": *"amd64"'; then
+        plat="linux/amd64"; warn "${ref} 没有本机架构的版本，改按 ${plat} 拉（仿真运行，冷启动慢）"
+        _env_set "$pvar" "$plat"
+      fi
+      do_pull "$ref" "配合调试用的 App 都发在一盒同一个项目（ONEBOX_PROJECT=${ONEBOX_PROJECT:-未配}）下；确实不在就用 --image 给全引用。" "$plat"
+    fi
   fi
   _env_set "$ivar" "$ref"
 
   # ③ 密钥：一盒现生成，两侧同源（清单里有没有明文都不影响）
   local svar sec; svar="$(printf '%s' "$key" | tr 'a-z-' 'A-Z_')_SA_SECRET"
-  sec="$(_eff "$svar")"; [ -n "$sec" ] || { sec="$(rand_hex | cut -c1-32)"; _env_set "$svar" "$sec"; }
+  sec="$(_eff "$svar")"; [ -n "$sec" ] || { sec="$(rand_hex | cut -c1-32)"; _env_append_secret "$svar" "$sec"; }
   # 声明了 exchangeTargets 的 App 是跨应用交换的【发起方】，它在 /oauth/token 上用
   # `sk_<key>` + App Secret 换对方的令牌。目录里的清单按红线剥掉了 exchangeInitiatorSecret，
   # 而 register-app 的 dev 模式只在【清单里有这个字段】时才 wireInitiatorSecret ——
   # 不补这一把，该 App 的跨应用交换会稳定 401，且症状出现在「发起方」而不是这里。
   local avar asec=""; avar="$(printf '%s' "$key" | tr 'a-z-' 'A-Z_')_APP_SECRET"
   if [ -n "$M_XTARGETS" ]; then
-    asec="$(_eff "$avar")"; [ -n "$asec" ] || { asec="$(rand_hex | cut -c1-32)"; _env_set "$avar" "$asec"; }
+    asec="$(_eff "$avar")"; [ -n "$asec" ] || { asec="$(rand_hex | cut -c1-32)"; _env_append_secret "$avar" "$asec"; }
   fi
 
   info "④ 注册清单（非破坏性、幂等）"
@@ -774,6 +1180,7 @@ cmd_add() {
   dc run --rm --no-deps -v "$HOME_DIR:/devkit:ro" portal-api bun run register-app "/devkit/.add-$key.manifest.json" \
     || { rm -f "$HOME_DIR/.add-$key.manifest.json"; die "注册失败 —— 看上面的报错。"; }
   rm -f "$HOME_DIR/.add-$key.manifest.json"
+  _reload_proxy
 
   info "⑤ 建库 xgent-${key}"
   dc up -d postgres >/dev/null 2>&1 || true
@@ -782,6 +1189,10 @@ cmd_add() {
   # ⑥ 从 manifest 生成 compose 片段
   local gen="$HOME_DIR/generated"; mkdir -p "$gen"
   local out="$gen/${key}.yml" PREFIX; PREFIX="$(printf '%s' "$key" | tr 'a-z-' 'A-Z_')"
+  case " $M_ENV " in *" ${PREFIX}_KAFKA_USERNAME "*) M_KAFKA=1 ;; esac
+  if [ "$M_KAFKA" = 1 ]; then
+    if ! _ensure_kafka "$key" "$PREFIX"; then _kafka_add_warning "$key"; fi
+  fi
   {
     echo "# 由 onebox.sh add ${key} 从 manifest 生成 —— 不要手改，重跑 add 会覆盖。"
     echo "services:"
@@ -803,20 +1214,42 @@ cmd_add() {
     # 发起方才有：门户库里那把（register-app 从清单读）与容器里这把必须同源，否则
     # 跨应用交换在【发起方】上 401，而错看起来像是被调方的问题。
     [ -n "$M_XTARGETS" ] && echo "      ${PREFIX}_APP_SECRET: \${${avar}}"
+    # 库连接串：<PREFIX>_DATABASE_URL 是生产的约定名（批准时按它建库并注入，发版 preflight 也要求它）；
+    # 后两个是旧名，留给还没改名的镜像。三个都指向同一个库。
+    echo "      ${PREFIX}_DATABASE_URL: postgres://postgres:postgres@postgres:5432/xgent-${key}"
     echo "      ${PREFIX}_PG_DSN: postgres://postgres:postgres@postgres:5432/xgent-${key}"
     echo "      DATABASE_URL: postgres://postgres:postgres@postgres:5432/xgent-${key}"
     echo "    expose: [\"\${${PREFIX}_PORT:-${M_PORT}}\"]"
     echo "    networks: { default: { aliases: [${key}-server] } }"
   } > "$out"
-  info "⑥ 生成 ${out#$HOME_DIR/}"
-  [ -n "$M_ENV" ] && _note "清单声明了 requiredEnv：${M_ENV} —— 值归平台，按需补进 compose.env 末尾。"
+  info "⑥ 生成 ${out#"$HOME_DIR"/}"
+  # requiredEnv 里【既不在上面生成的片段、也不在 compose.env】的键 —— 一盒版的 REQUIRED_ENV_MISSING
+  # （生产还会把平台代为供给的键算作已提供，一盒只有这两处来源）。在这里点名，而不是等容器缺变量退出。
+  if [ -n "$M_ENV" ]; then
+    local gen_keys="PORT PORTAL_INTROSPECT_URL ${PREFIX}_SA_CLIENT_ID ${PREFIX}_SA_CLIENT_SECRET ${PREFIX}_DATABASE_URL ${PREFIX}_PG_DSN DATABASE_URL"
+    [ -n "$M_XTARGETS" ] && gen_keys="$gen_keys ${PREFIX}_APP_SECRET"
+    local ek missing=""
+    for ek in $M_ENV; do
+      case " $gen_keys " in *" $ek "*) continue ;; esac
+      [ -n "$(_eff "$ek")" ] && continue
+      missing="${missing:+$missing }$ek"
+    done
+    if [ -n "$missing" ]; then
+      warn "requiredEnv 里这些键既不在生成的片段里、也不在 compose.env 里：${missing}"
+      _note "值归平台（生产由审批屏填），这里补进 compose.env 末尾，再重跑 ${0} add ${key}。"
+    else
+      _note "requiredEnv 的键都已到位（生成的片段 + compose.env）。"
+    fi
+  fi
 
   # 例外：manifest 描述不了的自带 infra（如 knowledge 的 Chroma）
   local extra_args=() extra="$SKILL_DIR/services/${key}.extra.yml"
   [ -f "$extra" ] && { extra_args=(-f "$extra"); info "   叠加自带依赖 services/${key}.extra.yml"; }
 
-  # 对象存储桶：清单 requiredEnv 里带 *_S3_BUCKET_NAME / ZO_S3_BUCKET_NAME 的，按 compose.env 里的值在一盒 minio 上建桶
+  # 对象存储桶：清单 requiredEnv 里带 *_S3_BUCKET_NAME / ZO_S3_BUCKET_NAME 的，按 compose.env 在 RustFS 建桶
   local bvar bname
+  # M_ENV is a validated whitespace-delimited list of environment key names.
+  # shellcheck disable=SC2086
   for bvar in $(printf '%s\n' $M_ENV | grep -E '_S3_BUCKET(_NAME)?$' || true); do
     bname="$(_eff "$bvar")"; [ -n "$bname" ] && _ensure_bucket "$bname"
   done
@@ -824,7 +1257,8 @@ cmd_add() {
   # 清单声明了 deployDescriptor.migrateArgs（生产由 deploy-controller 在换容器前跑）：起容器前先跑一次
   if [ -n "$M_MIGRATE" ]; then
     info "⑥b 迁移：${key}-server ${M_MIGRATE}"
-    dc up -d postgres minio >/dev/null 2>&1 || true
+    _objectstore_up
+    dc up -d postgres >/dev/null
     # shellcheck disable=SC2086
     XGENT_ONEBOX_HOME="$HOME_DIR" dc -f "$out" ${extra_args[@]+"${extra_args[@]}"} run --rm --no-deps "${key}-server" $M_MIGRATE \
       || warn "${key}-server ${M_MIGRATE} 失败 —— 看上面的报错（多半是 env 值没到位）"
@@ -862,6 +1296,24 @@ cmd_doctor() {
   echo "一盒体检（${BASE_URL}）"
   echo
 
+  echo "对象存储"
+  if ! _objectstore_assets_current; then
+    _bad "对象存储部署资产是旧版" "$0 upgrade --image <新版一盒镜像> && $0 up"
+  elif dc exec -T rustfs curl -fsS --max-time 5 http://127.0.0.1:9000/health </dev/null >/dev/null 2>&1; then
+    _ok "RustFS /health 正常"
+  else
+    _bad "RustFS 未就绪" "$0 up；失败时保留 rustfs-data，查看 $0 dc logs rustfs。"
+  fi
+
+  echo "Kafka"
+  if ! _kafka_assets_current; then
+    _bad "Kafka 部署资产或配置是旧版" "$0 upgrade --image <新版一盒镜像> && $0 up"
+  elif dc exec -T kafka nc -z 127.0.0.1 9092 </dev/null >/dev/null 2>&1; then
+    _ok "Kafka INTERNAL 监听正常（SASL 认证由服务探测验证）"
+  else
+    _bad "Kafka 未就绪；门户与现有应用可继续运行" "$0 dc logs --tail 50 kafka；修复后重跑 $0 up。"
+  fi
+
   echo "① 镜像版本"
   local iv; iv="$(_eff XGENT_IMAGE)"
   if docker image inspect "$iv" >/dev/null 2>&1; then
@@ -930,13 +1382,14 @@ cmd_doctor() {
   local keys="$CATALOG"; [ -n "$APP_KEY" ] && keys="$CATALOG,$APP_KEY"
   local code
   code="$(curl -s -m 8 -o /dev/null -w '%{http_code}' "$BASE_URL/health" || true)"
-  [ "$code" = "200" ] && _ok "门户 /health 200" || _bad "门户 /health HTTP ${code:-000}" "000=反代没起或端口不对（$0 dc ps）；其它看 $0 dc logs portal-api"
+  if [ "$code" = "200" ]; then _ok "门户 /health 200"
+  else _bad "门户 /health HTTP ${code:-000}" "000=反代没起或端口不对（$0 dc ps）；其它看 $0 dc logs portal-api"; fi
   for k in ${keys//,/ }; do
     _is_portal_hosted "$k" && continue
     code="$(curl -s -m 8 -o /dev/null -w '%{http_code}' "$BASE_URL/svc/$k/health" || true)"
     case "$code" in
       200) _ok "/svc/$k 200";;
-      404) _bad "/svc/$k 404" "放行没写成或反代在写之前就起了：$0 dc exec reverse-proxy caddy reload";;
+      404) _bad "/svc/$k 404" "放行尚未应用：检查发布状态及 $0 dc logs portal-api，勿手工 reload 兼容模板";;
       502) _bad "/svc/$k 502" "后端不在/没听 8080/别名没命中：$0 dc logs ${k}-server";;
       *)   _bad "/svc/$k HTTP ${code:-000}" "$0 dc ps";;
     esac
@@ -951,6 +1404,7 @@ cmd_doctor() {
 
 case "${1-status}" in
   init)   shift; cmd_init "$@" ;;
+  upgrade) require_home; load_env; shift; cmd_upgrade "$@" ;;
   pull)   shift; cmd_pull "$@" ;;
   env)    require_home; load_env; cmd_env ;;
   smoke)  require_home; load_env; cmd_smoke ;;
@@ -962,5 +1416,5 @@ case "${1-status}" in
   dc)     require_home; load_env; shift; dc "$@" ;;
   # 打印开头那段注释直到第一条非注释行 —— 别写死行号，加一条子命令就会截断（踩过）。
   -h|--help|help) awk 'NR>1 && /^#/ {sub(/^# ?/,""); print; next} NR>1 {exit}' "${BASH_SOURCE[0]}" ;;
-  *)      die "未知子命令 '$1'。用 init | up | doctor | add <key> | pull | env | status | smoke | chain | dc <args...>" ;;
+  *)      die "未知子命令 '$1'。用 init | upgrade | up | doctor | add <key> | pull | env | status | smoke | chain | dc <args...>" ;;
 esac