@xgent-ai/skills 0.3.0 → 0.5.0

package/skills/portal-dev-setup/SKILL.md

@@ -40,8 +40,8 @@ S="$SKILL_DIR/scripts/onebox.sh"
 
 - 要拉平台侧的别的 App 进来陪调：`onebox.sh add <key>`（§2.1），它进的就是这套。
 - 要调你自己的**另一个** App（在另一个 repo）：`XGENT_ONEBOX_HOME=<已有 portal-onebox/ 的路径>`
-  复用那套栈跑 `register-app` / `dc`；宿主上的 dev 后端则直连一盒的 pg/redis/minio（§5）。
-- 不用担心端口打架：init 挑宿主端口时逐个探测退让，一盒的 pg/redis/minio 落位永远避开
+  复用那套栈跑 `register-app` / `dc`；宿主上的 dev 后端则直连一盒的 pg/redis/RustFS（§5）。
+- 不用担心端口打架：init 挑宿主端口时逐个探测退让，一盒的 pg/redis/RustFS 落位永远避开
   你本地 dev 栈的 5432/6379/9000-9001（见 §5 的直连表）。
 
 ## 0. 先备齐三样
@@ -80,8 +80,8 @@ chmod 600 ./.xgent-registry.env
 
 ### 装 `@xgent/*` 私有包？不需要云账号
 
-前端要 `@xgent/portal-sdk` / `@xgent/portal-ui` 时，**别去申请云账号、也别装云厂商 CLI**：
-拿你已有的**发布令牌**向门户换一枚 ≤12 h 的只读令牌就行（门户持云凭据）：
+要装 `@xgent/shared` / `@xgent/portal-sdk` / `@xgent/portal-server-sdk` / `@xgent/portal-ui` 时，
+**别去申请云账号、也别装云厂商 CLI**：拿你的**发布令牌**向门户换一枚 ≤12 h 的只读令牌就行（门户持云凭据）：
 
 ```bash
 RELEASE_SKILL_DIR="<xgent-app-release 的 SKILL.md 所在目录>"
@@ -89,7 +89,12 @@ eval "$(node "$RELEASE_SKILL_DIR/scripts/npm-token.mjs")"
 npm install
 ```
 
-报 `NPM_REGISTRY_NOT_CONFIGURED` 是**平台侧**还没配，贴给管理员，你这边不用改任何配置。
+- **还没有发布令牌就停下。** 仓里没有 `.xgent-registry.env`（或里面没有 `XGENT_RELEASE_TOKEN`）⇒ 请开发者
+  先去门户「开发者应用」› 你的应用 › 凭证 › **生成配置文件**；应用还没建 ⇒ 先在开发者应用里
+  「申请建立应用」，平台管理员批准后才能生成。拿到之前**不许 vendor**：不把 `@xgent/*` 拷进仓、
+  不用 `file:` / `link:` / tar 依赖。
+- 报 `NPM_REGISTRY_NOT_CONFIGURED` 是**平台侧**还没配，贴给管理员，你这边不用改任何配置。
+
 细节见 `xgent-app-release` skill 的「第 0 步」。
 
 ## 1. 首次用：一条命令铺好
@@ -100,7 +105,7 @@ npm install
 
 不给 `--image` 就取 `<REGISTRY>/<ONEBOX_PROJECT>/one-box:latest`（反代同仓同 tag）——**开新项目不用先去问 tag**。
 `latest` 是**可变指针**：它跟着最新一版走，本地已经有同名镜像时 compose 不会回仓库看一眼，
-所以开工前先 `onebox.sh pull` 一次。要钉住某一版（复现一个 bug、或团队统一版本）就显式
+所以沿用 `latest` 升级先 `onebox.sh pull`，再 `upgrade` → `up`（§6），同时更新镜像与部署资产。要钉住某一版（复现一个 bug、或团队统一版本）就显式
 `--image <registry>/<项目>/one-box:v<版本>-<sha>`，那种 tag 是不可变的。
 
 它做五件事，都在**你的 repo 根**落到 `portal-onebox/`：
@@ -111,14 +116,16 @@ npm install
    不会让人跑到一半才发现，也不会留下半个空目录。
 1. **从镜像里取出 compose 资产**（`docker create` + `docker cp /app/deploy`）——所以版本天然与镜像对齐，
    不需要门户仓，也不会有「文档里的 compose 和镜像对不上」这种漂移。
-2. **挑空闲端口**。一盒只发布 6 个宿主端口（80/443 · 5432 · 6379 · 9000/9001），
-   开发机上这些十有八九被占——它逐个探测并退让，把结果写进 `compose.env` 并回显。
-   挑出来的 pg/redis/minio 端口同时就是你宿主进程直连一盒基建的口（见 §5 的直连表）。
+2. **挑空闲端口**。HTTP/HTTPS、pg、redis、RustFS 的 6 个宿主端口逐个探测并退让；
+   Kafka HOST 另按 9092/19092/29092 挑选，结果写进 `KAFKA_PORT`。Kafka EXTERNAL 独立默认
+   发布回环 9095，若已占用，在 `compose.env` 末尾另设 `KAFKA_EXTERNAL_PORT`；它不参与自动挑选。
+   挑出来的 pg/redis/RustFS 端口同时就是你宿主进程直连一盒基建的口（见 §5 的直连表）。
 3. **生成 `compose.env`**：三段模板拼装 + 一段本机覆盖块（随机密钥、端口、项目名、镜像 tag）。
+   Kafka 的 `KAFKA_CLUSTER_ID` 与 `KAFKA_ADMIN_PASSWORD` 每个新盒随机生成，密码不回显；文件权限为 600。
    覆盖块**放在文件最末尾**，因为 docker compose 读 env-file 是**后定义者胜**——以后要改配置也往那下面加，别回上面改。
 4. 把 `portal-onebox/` 加进 `.gitignore`（里面是密钥，且随时能重新生成）。
 
-它**不会**覆盖已存在的 `compose.env`（那是这台机器唯一的一份密钥）。要整份重来加 `--force`。
+它**不会**覆盖已存在的 `compose.env`（那是这台机器唯一的一份密钥）。已有一盒走 §6 的 `upgrade`；只有重置才用 `init --force`。
 
 跑完编辑 `portal-onebox/compose.env` 末尾，填你的 App：`APP_IMAGE`（后端镜像 tag），
 micro 型再加 `APP_FRONTEND_DIST`（前端 dist 的**绝对路径**，目录里要有 `index.html`）。
@@ -149,7 +156,8 @@ micro 型再加 `APP_FRONTEND_DIST`（前端 dist 的**绝对路径**，目录
 | `onebox.sh smoke` | 只跑健康探测 |
 | `onebox.sh dc <args>` | `docker compose <拼好的参数> <args>` |
 | `onebox.sh chain` | 打印那串参数（想自己敲 compose 时抄它） |
-| `onebox.sh pull` | 只（重）拉门户镜像。不带参数时从 `compose.env` 读当前版本 |
+| `onebox.sh pull` | 只（重）拉门户镜像，不更新部署资产。不带参数时从 `compose.env` 读当前版本 |
+| `onebox.sh upgrade [--image <ref>]` | 更新镜像与部署资产，保留配置和数据；完成后运行 `up`（§6） |
 
 ## 2. 起栈：顺序本身是契约
 
@@ -162,8 +170,9 @@ S="$SKILL_DIR/scripts/onebox.sh"
 它幂等，改完 manifest 或 compose.env 重跑即可。下面这几步是它替你做的事——想手动控某一步时照着敲：
 
 ```bash
-# 1) 基础设施
-"$S" dc up -d postgres redis minio
+# 1) 基础设施由 "$S" up 先做资产检查、存量对象存储切换，再起 postgres/redis/rustfs/kafka。
+#    不手工 dc up rustfs；旧资产会在启动前拒绝并提示先 upgrade。
+#    以下是 up 成功后单独重跑某一步的示例。
 
 # 2) 门户库 + 四个基础服务各自的库（它们的 xgent-* 库由 postgres 首次初始化时建好）
 "$S" dc run --rm portal-api bun run db:migrate
@@ -200,7 +209,7 @@ for k in files llm-gateway git org; do "$S" dc run --rm portal-api bun run db:$k
   反代已经在跑就补一句 `"$S" dc exec reverse-proxy caddy reload`，否则 `/svc/<key>` 一直 404。
 - **`register-app` 跑完先去市场里确认卡片在。** dev 模式下它会顺手把这条 listing 授予现有租户（生产是平台管理员显式勾选），
   但**旧一点的一盒镜像里没有这段代码**——症状是控制台显示已上架、租户市场里连卡片都不出现，且**没有任何报错**。
-  看不到就先 `"$S" pull` 换新镜像重来，或按 troubleshooting §6 手工授予，别接着往下排查前端。
+  看不到就按 §6 更新镜像缓存后 `"$S" upgrade` → `"$S" up` 同步资产，或按 troubleshooting §6 手工授予，别接着往下排查前端。
 - **要做跨应用交换的，`register-app` 得跑两次。** 发起方 App Secret 绑在**已安装实例**上，所以是
   `register-app` → 在应用市场里装上你的 App → **再跑一次 `register-app`**（幂等）。漏了的症状是交换在发起方 401。
 
@@ -209,20 +218,53 @@ for k in files llm-gateway git org; do "$S" dc run --rm portal-api bun run db:$k
 你的 App 要用前四个的数据，就在 manifest 里声明 `exchangeTargets` 走令牌交换；
 组织架构另有一条**服务态**只读面（`org.read`，不走用户态交换、也不需要 consent）：
 `/svc/org/api/v1/query/superiors`（批量查直属上级，上限 200）与 `/svc/org/api/v1/query/capabilities`
-（`{ superior: boolean }` —— 本租户有没有汇报数据）。⚠️ 一盒装上的是**空组织**，要数据先在
-App 里走「员工 → 导入」（CSV），否则上级一律回 `null` / `reason: "no-employee"`。
+（`{ superior: boolean }` —— 本租户有没有汇报数据）；`/svc/org/api/v1/query/users/{userId}/assignments`
+按**门户 userId** 查当前生效任职的平面集合（`{userId, employeeId, reason, items, total, page, pageSize}`，
+`items[] = {assignmentId, departmentId, departmentName, departmentArchived, isPrimary, startDate}`，
+缺省一次拿全；`reason` ∈ `ok`/`no-employee`/`employee-left`/`no-open-assignment`，空集合是 200 不是 404）。
+它**不给树语义**：要「本部门及下级」就用 `/svc/org/api/v1/query/departments?includeArchived=true` 分页取完、
+按 `parentId` 自己建树（**必须传 `includeArchived=true`**，否则归档的那一代会在链上留洞）。
+注意既有 `/query/employees/{employeeId}/assignments` 入参是 org 员工 id、容器键是 `assignments`、返回全部历史，
+两个任职端点的键名与排序都不同，别混拼。
+⚠️ **只有 HTTP 200 ∧ `ok:true` 是成功**：401/403/429/5xx/超时，以及门户回滚后的 **404 必须当查询失败**，
+不能缓存成「无任职」。**持续 403 `INSUFFICIENT_SCOPE` 先查 manifest**：铸服务令牌看响应 `scope` 有没有 `org.read`，
+没有就在 `serviceScopes` 加它（且 `org` 在 `dependencies` 或 `exchangeTargets` 里）走发布提案。
+限频 600 次/分钟，按 (令牌 `aud`, 租户) 计数、org 全部端点共享：服务态令牌 `aud` 是你的 SA clientId（独占一个桶），用户态令牌 `aud` 恒为 `org`（同租户所有 App 共用一个桶）；结果建议 ≤60s 进程内缓存、不得落表。
+⚠️ 一盒装上的是**空组织**，要数据先在 App 里走「员工 → 导入」（CSV），否则上级一律回 `null` /
+`reason: "no-employee"`，任职一律回空集合。
 
 日志与监控不用声明——种子把它登记成平台基础服务应用，你的 App 的服务账号
 **默认就持有 `observability.ingest`**，拿服务态令牌直接写 `/svc/observability/v1/ingest/<stream>`（落 `app_<你的key>_<stream>`）。
 
+### Kafka 的启动边界
+
+Kafka 随基础设施常驻，`up` 单独启动并最多等健康 60 秒；失败只告警并显示日志，继续门户与现有 App 初始化。
+`doctor` 检查 Kafka 的 TCP 监听；探针只证明监听已打开，不能替代客户端的认证、授权与收发验证。
+`add` 识别 `requiredServices: [{"kind":"kafka","name":"main"}]`，也兼容 `requiredEnv` 中的
+`<PREFIX>_KAFKA_USERNAME`。它为 App 创建 SCRAM-SHA-512 用户与前缀 ACL，并写入五键：
+`<PREFIX>_KAFKA_BROKERS`、`_KAFKA_USERNAME`、`_KAFKA_PASSWORD`、`_KAFKA_SASL_MECHANISM`、
+`_KAFKA_TOPIC_PREFIX`（后四项同样带 `<PREFIX>`）。`<PREFIX>` 是 listingKey 大写、连字符改成下划线。
+密码第一次生成后写入 `compose.env` 并显示 `***`，重复 `add` 及失败重试沿用原值。
+不要为联调把 `KAFKA_ADMIN_PASSWORD` 加进 App 的 `requiredEnv`。
+
+例如 `order-worker` 的用户名是 `app_order_worker`，主题、消费组、事务 ID 都必须以
+`app.order-worker.` 开头。机制固定 `SCRAM-SHA-512`。App 必须显式建主题（副本数 1），不能修改
+保留期或增加分区；前缀外访问被 broker 拒绝。Kafka 供给失败只告警，保留已保存的密码，按提示
+修复后重跑原 `add`。一盒仍向容器注入整份 `compose.env`，不承诺 App 容器之间的密钥隔离。
+声明范例、客户端配置、最小 ACL 与可粘的手工修复命令见 [Kafka 接入指引](references/kafka.md)。
+
+宿主地址为 `127.0.0.1:<KAFKA_PORT>`，容器网络为 `kafka:9092`，均使用 SASL_PLAINTEXT。
+一盒 EXTERNAL 默认 `127.0.0.1:9095`，保持回环，不开放公网。生产跨 VM 的外部口配置由运维处理：
+监听地址、非回环广告地址和安全组需同时匹配，且 SASL_PLAINTEXT 不加密消息。
+
 ### 2.0a 日志与监控是怎么进来的（`up` 替你做的 ④b / ⑥）
 
 - **④b** `observability` 不是门户内置 workspace，是清单型 App（`app-devkit/manifests/observability.manifest.json`）。
   `up` 对目录里每个清单型 App 自动走一遍 `add`：拉镜像（`<REGISTRY>/<ONEBOX_PROJECT>/observability:v0.5.4-…`；
   多架构清单会自动挑本机架构，只有单 amd64 的版本才要在 compose.env 钉 `OBSERVABILITY_PLATFORM=linux/amd64`
-  走仿真）→ 注册 → 建库 `xgent-observability` + 在一盒 minio
+  走仿真）→ 注册 → 建库 `xgent-observability` + 在一盒 RustFS
   建桶 `xgent-observability` → `init-db`（清单 `deployDescriptor.migrateArgs`）→ 生成 `generated/observability.yml` 起容器。
-  它要的那批 `ZO_*` 值（元数据库/对象存储）已经在 `onebox/compose.env.onebox.example` 里指向一盒的 postgres/minio；
+  它要的那批 `ZO_*` 值（元数据库/对象存储）已经在 `onebox/compose.env.onebox.example` 里指向一盒的 postgres/RustFS；
   `OBSERVABILITY_PORT=8080` 让它在 8080 上听（一盒反代只反代 `<key>-server:8080`）。
 - **⑥** 门户自身的控制台日志：`up` 用 `portal-self` 签一把只带 `observability.ingest` 的 `xsak_` 写进 compose.env
   的 `OBS_ACCESS_KEY`，再起 `portal-logs`（fluent-bit）；portal-api 的 stdout/stderr 走 docker 的 fluentd 日志驱动
@@ -276,6 +318,11 @@ release-cli 在一盒里是**通的**（`/api/market/release/*` 就在 portal-ap
 它按 manifest 把这个 App 装起来：拉镜像 → 注册清单+服务账号（**非破坏性、幂等**，不是那个会
 truncate 的 `db:seed:onebox`）→ 建 `xgent-<key>` 库 → **生成** compose 片段 → 起容器 → 冒烟。
 
+**清单声明了 `dependencies` 的**（比如 workflow 依赖 files 和 task-gateway）：注册时门户要求每个依赖在**这台一盒里**
+已经有清单，否则拒绝（`DEPENDENCY_UNAVAILABLE`），跟依赖装没装无关。`add` 会在拉镜像之前先查一遍，把缺的依赖一次列全，然后停下。
+这时先逐个 `"$S" add <依赖>`，再重跑原来那条 `add`。之后在「应用管理 → 应用市场」里安装这个 App，依赖会一起装上、自动授予，不用一个个去装。
+依赖的清单要是没写 `deployDescriptor.image`，`add` 它时带上 `--image <REGISTRY>/<ONEBOX_PROJECT>/<key>:<tag>`。
+
 **compose 片段是从 manifest 生成的，不是每个 App 在 skill 里预置一份 YAML。** 那样每接一个新
 App 都要改一次 skill，等于把问题换了个地方。manifest 里已经有全部所需：
 
@@ -284,8 +331,9 @@ App 都要改一次 skill，等于把问题换了个地方。manifest 里已经
 | 镜像（**版本由清单钉住，可复现**；相对名按 `<REGISTRY>/<ONEBOX_PROJECT>/` 补全） | `deployDescriptor.image` |
 | 容器内端口 / 健康路径 | `deployDescriptor.port` / `.healthPath` |
 | 网络别名 `<key>-server`、库名 `xgent-<key>` | `listingKey`（约定） |
+| 库连接串 `<PREFIX>_DATABASE_URL`（与生产同一个约定名），另带旧名 `<PREFIX>_PG_DSN` / `DATABASE_URL`，都指向 `xgent-<key>` | `listingKey`（约定） |
 | 自省身份 | `serviceAccount.clientId` |
-| 还要补哪些 env（值归平台） | `requiredEnv` |
+| 还要补哪些 env（值归平台；`add` 会点名片段与 `compose.env` 里都没有的那几个） | `requiredEnv` |
 
 **密钥不从清单来**：一盒现生成，**同时**写进本地门户 DB 与容器 env —— `add` 会在注册前把
 密钥注进临时清单（用完即删）。所以清单里有没有明文密钥都无所谓，这也正是 release-cli
@@ -328,7 +376,9 @@ MANIFEST_STORE_READ_TOKEN=xcat_…      # 只读令牌：只能读公开清单
   `data:null` = 目录里还没有这个 key（那个 App 还没发过版？）· 连不上 = 检查地址与网络。
 
 **镜像不用你操心**：配合调试用的平台侧 App 一律以**稳定版**发到与一盒**同一个项目**下，同一把
-puller key 就能拉。要换版才加 `--image <ref>`。
+puller key 就能拉。要换版才加 `--image <ref>`。有些镜像只发了 amd64，在 Apple Silicon 上直接 pull 会报
+`no matching manifest`。这种情况 `add` 会自动改拉 amd64 那一份（仿真运行，冷启动慢），并把
+`<PREFIX>_PLATFORM=linux/amd64` 写进 `compose.env`。
 
 > **你要花时间排查的只有你自己那个 App。** 别人的 App 在这里是稳定件——起不来先 `"$S" doctor`，
 > 还不行报给门户团队，别自己去调它。
@@ -350,8 +400,8 @@ puller key 就能拉。要换版才加 `--image <ref>`。
 
 首次跨应用调用浏览器会多弹一次交换授权页，是正常的。
 
-> **为什么建库/迁移在一盒要 `add` 代劳，生产不用。** 生产上这两件各有其主：**建库**归运维
-> （不在部署链里），**迁移**归部署链——`deployDescriptor.migrateArgs` 让 deploy-controller 在换
+> **为什么建库/迁移在一盒要 `add` 代劳，生产不用。** 生产上这两件各有其主：**建库**归批准时的
+> 平台供给（按约定名 `<PREFIX>_DATABASE_URL` 建库并注入，不在部署链里），**迁移**归部署链——`deployDescriptor.migrateArgs` 让 deploy-controller 在换
 > 容器**之前**跑一个一次性容器（同镜像、同 env、只换 argv），失败就让这次部署失败而**旧容器
 > 继续服务**，不会变成换完之后的崩溃循环。一盒**两样都没有**（没有 controller，`migrateArgs`
 > 一次也不会跑），所以 `add` 替你建库，迁移靠镜像自己启动时迁——**这也意味着一盒里验不出
@@ -371,7 +421,7 @@ puller key 就能拉。要换版才加 `--image <ref>`。
    `XGENT_ONEBOX_HOME=portal-onebox "$S" dc -f portal-onebox/<你的>.yml up -d <服务名>`。
    `-f` 出现在子命令前就仍是全局选项，位置没问题。
 3. **别改 `portal-onebox/` 里 init 铺出来的那几个 yml** —— 它们是从镜像里取出来的，
-   `init --force` 会原样覆盖，而且换一版镜像就该跟着换。你的东西永远是**新文件**。
+   `upgrade` 会同步这些平台资产，`init --force` 也会覆盖；不要在平台原文件里维护自己的改动。你的东西永远是**新文件**。
 
 **合并规则（实测 `docker compose config`，三条都不直觉）：**
 
@@ -406,7 +456,7 @@ amd64 镜像要 `linux/amd64`）· 网络别名 `<key>-server`（反代靠它找
 **dev 登录的入口**：登录页密码表单下方的「本地开发账号」按钮（`DEV_MOCK_OAUTH=true` 才出现），
 或直接打开 `/auth/dev/start` 进 mock IdP 选账号 → 选 `rockie@xgent.ai`（演示租户 admin + 平台管理员）。
 **按钮没出现**：先 `curl <地址>/auth/providers` 看 `dev` 字段在不在——在就走 `/auth/dev/start`，
-那说明这版镜像的前端与 API 对不齐，`"$S" pull` 换新的。
+那说明这版镜像的前端与 API 对不齐，按 §6 更新缓存后运行 `upgrade` → `up`。
 
 种子只种两个账号，另一个是 `liming@xgent.ai`（普通成员）——**ACL 成员基线没到位的问题只在非管理员身上现形**，
 验收要用它再走一遍，管理员那边永远是绿的。
@@ -434,7 +484,7 @@ amd64 镜像要 `linux/amd64`）· 网络别名 `<key>-server`（反代靠它找
 > **「照文档做，行为却不符」先看版本。** `status` / `smoke` 里 `/health` 那行会回一个 `version`：
 > `init` 把镜像的 tag + ID + 构建日期写进了 `compose.env` 的 `APP_VERSION`。报 `dev` 说明这份 compose.env
 > 是老 `init` 铺的（或你自己改过）。一盒镜像比文档旧一天，就足以让「注册后自动授予租户」这类行为整个不存在，
-> 而现场没有任何报错 —— 真实案例（CR-4）。`"$S" pull` 换新的再判。
+> 而现场没有任何报错 —— 真实案例（CR-4）。按 §6 更新缓存并运行 `upgrade` → `up`，同步新镜像与资产再判。
 那张表按「你看到什么」编排。最容易白白浪费半天的两条先放这儿：
 
 > **看到 `unhealthy` 先读那条探针，再决定要不要查。**
@@ -445,7 +495,7 @@ amd64 镜像要 `linux/amd64`）· 网络别名 `<key>-server`（反代靠它找
 > 假红：Caddy 把它 308 到 `https://127.0.0.1/`，对一个 IP 建 TLS 没有 SNI，回 `SSL alert number 80`。
 > · 探针已是 `bun -e fetch(...)` / `curl -fsS -o /dev/null http://127.0.0.1:80/`（新镜像的两条）
 > 却仍 `unhealthy` ⇒ **真红**，去看 `"$S" dc logs <服务>`。
-> 判活一律以 `"$S" smoke` 的宿主侧探测为准；pg/redis/minio 的 healthy 一直是真的。
+> 判活以 `"$S" smoke` 的宿主侧探测为准；pg/redis/RustFS 的 healthy 检查对应服务。Kafka 看 `doctor`，其 TCP healthy 不代表 App 凭据与 ACL 已可用。
 
 > **`COMPOSE_PROJECT_NAME` 固定是 `xgent-onebox`，别靠改名来「并存」两套。** 同机两套 compose
 > 项目名相同，compose 会认为它们是同一项目——容器互相接管、命名卷共享，症状是「我起了一盒，
@@ -469,7 +519,7 @@ services:
 然后 `XGENT_ONEBOX_HOME=portal-onebox "$S" dc -f portal-onebox/host-backend.yml up -d app-backend`。
 此时 `APP_IMAGE` 不再被用到（compose 仍要求它有值，随便填一个）；`APP_KEY` 照旧——别名还是靠它。
 
-**宿主进程的 DB / 缓存 / 对象存储也用一盒的，别再单起。** postgres / redis / minio 都发布了
+**宿主进程的 DB / 缓存 / 对象存储也用一盒的，别再单起。** postgres / redis / RustFS 都发布了
 宿主端口，而 init 挑端口时避开了本机已占用的口——所以它们和你本地 dev 栈的
 5432 / 6379 / 9000-9001 不冲突（典型落位 15432 / 16379 / 19000-19001；以 `compose.env` 末尾的
 `POSTGRES_PORT` / `REDIS_PORT` / `MINIO_PORT` / `MINIO_CONSOLE_PORT` 为准，`"$S" env` 也回显）。
@@ -479,33 +529,69 @@ services:
 | --- | --- | --- |
 | Postgres | `postgres://postgres:postgres@localhost:<POSTGRES_PORT>/xgent-<你的key>` | 库不存在先建（§2 3b 那条 CREATE DATABASE） |
 | Redis | `localhost:<REDIS_PORT>` | 无密码 |
-| MinIO (S3) | `http://localhost:<MINIO_PORT>` | `minioadmin` / `minioadmin`；控制台在 `<MINIO_CONSOLE_PORT>`，桶自己建（建议 `xgent-<你的key>`） |
+| RustFS (S3) | `http://localhost:<MINIO_PORT>` | `minioadmin` / `minioadmin`；控制台在 `http://localhost:<MINIO_CONSOLE_PORT>/rustfs/console/`，桶自己建（建议 `xgent-<你的key>`） |
 
 这样宿主进程和容器里的 App 看到的是同一份库、同一个桶。注意上面是**宿主侧**地址——
-容器网里那套服务名与端口不变（`postgres:5432` / `redis:6379` / `minio:9000`）。
+容器网里地址不变（`postgres:5432` / `redis:6379` / `minio:9000`）；`minio` 是 RustFS 的兼容别名，`MINIO_*` 配置继续使用。
 
-## 6. 重置与拆栈
+## 6. 初始化、升级与重置
+
+三条路径各有用途：
+
+| 目的 | 命令 | 配置与数据 |
+| --- | --- | --- |
+| 首次初始化 | `"$S" init --key <listingKey>` → 编辑 App 配置 → `"$S" up` | 新建资产、密钥与端口配置 |
+| 已有一盒升级 | `"$S" upgrade [--image <ref>]` → `"$S" up` | 保留 compose.env、generated/、backup/、端口与数据卷 |
+| 主动清空联调数据重置 | `"$S" dc down -v` → `"$S" init --force --key <listingKey>` → `"$S" up` | 删除当前 compose 的命名卷并重新生成配置；不可当升级使用 |
+
+### 升级：换资产，保留本机配置与对象
 
 ```bash
 S="$SKILL_DIR/scripts/onebox.sh"
-"$S" dc down          # 停容器，留命名卷（数据还在，下次 up 接着用）
-"$S" dc down -v       # ★ 连命名卷一起删：pg/minio/apps/caddy 的数据全没
+"$S" upgrade --image <registry>/<项目>/one-box:v<版本>-<sha>
+"$S" up
 ```
 
-只想重置门户数据：重跑 `db:seed:onebox`（同样破坏性），然后**重跑 `register-app`**（你的 listing 被种子清掉了），
-最后 `caddy reload`。种子会重新生成 UUID，浏览器会话随之失效——重登一次 dev 登录，不是坏了。
-
-换门户镜像版本：改 `compose.env` 末尾的 `XGENT_IMAGE` / `XGENT_PROXY_IMAGE` 两行，
-`"$S" pull` 把新版本拉下来，再 `"$S" dc up -d`。compose 资产要不要跟着更新，
-重跑 `init --force --home <另一个空目录>` 对比着看。
-
-⚠️ **换镜像要修的毛病，多半还得配一次 `down -v`，而且顺序是「先换镜像、再删卷」。**
-命名卷的属主与初始内容由**第一次挂它的那个容器**定，之后既不会因为换镜像而变，也不会被
-`up -d` 纠正。所以：只 `pull` 不删卷 = 老卷带着老属主继续用；只 `down -v` 不 `pull` = 用老镜像
-又建出一个一样坏的卷。EACCES 那一族（`/svc` 放行写不成 → `/svc/<key>` 404、发布前端产物报
-`/srv/www/apps` 不可写）就是这个形状，修法见排查表 [§7](references/troubleshooting.md#7-命名卷属主不对eacces-一族)。
-一盒是本地联调环境、数据不值钱，**首选就是 `"$S" pull` → `"$S" dc down -v` → 按 §2 重铺**，
-别为了保住一个演示库去绕。
+不指定 `--image` 时使用当前 `XGENT_IMAGE`；显式换 runtime 后会按同仓同 tag 推导 proxy，
+需要不同反代镜像可加 `--proxy-image <ref>`。`upgrade` 要求已有 `compose.env`，
+重新从镜像取出部署资产，**不重建配置、不重挑端口、不删卷**。只有镜像或版本变化时，
+才在文件末尾追加 `XGENT_IMAGE` / `XGENT_PROXY_IMAGE` / `APP_VERSION`；原有密钥、自定义行和 `add` 写入的键保留。
+Kafka 另按需补缺 `KAFKA_CLUSTER_ID` / `KAFKA_ADMIN_PASSWORD` / `KAFKA_PORT`：新 ID 与密码随机生成，
+新端口按 9092/19092/29092 挑选，已有的三键一个不改。密码写入不回显，`compose.env` 保持 600。
+`generated/` 和 `backup/` 原样保留。两个目标镜像本地都在时跳过拉取，支持本地构建或离线 `docker load`。
+沿用可变 `latest` 要先更新缓存：`"$S" pull` → `"$S" upgrade` → `"$S" up`；显式指定新的不可变 tag
+或已载入的本地新 tag，可直接 `upgrade --image <ref>`。单独 `pull` 不更新资产，不能代替 `upgrade`。
+
+升级也保留 PostgreSQL 的**现有数据大版本与挂载布局**。脚本在启动数据库前只读检查卷内
+`PG_VERSION`，已有 18 的一盒不会因新模板默认 16 而被降级；旧布局挂 `/var/lib/postgresql/data`，
+18 起的版本目录布局挂其父目录 `/var/lib/postgresql`。未知、冲突或非空但无法识别的布局会中止，
+不冒险初始化另一份空库。此时保留卷与原镜像，按提示核对；**不要删卷解决版本错误**。
+真正升级 PostgreSQL 大版本需要另行备份并安排 pg_upgrade 或导出/恢复，不随门户换版自动执行。
+
+`up` 先检查资产，再通过共用切换脚本把存量 MinIO 复制到全新的 RustFS 卷；旧卷保留，
+桶列表、对象清单和正文摘要一致才提交。正式 RustFS 只在脚本成功后启动，并等待 `/health`。
+`add` 与建桶入口同样经过这道切换门。**`up` 仍会重种门户库**（租户、用户、清单、安装与 UUID），
+这是一盒原有契约；App 自己的数据库不被重种，对象存储数据由切换校验保留。
+
+备份在一盒目录的 `backup/`，包含旧镜像归档、每次切换清单及 `rollback-minio.sh`。
+失败时先读退出提示：提交前失败恢复旧服务；已提交但新服务不健康时保留 `rustfs-data`，
+按日志排错后重跑 `up`。**不要删除权威新卷。** 回退入口会先停掉正式 RustFS，重新核对当前数据：
+有切换后写入则拒绝回退并保留新卷；此时需在副本上验证 MinIO 兼容与全部对象，再由人工安排恢复，
+不能直接把服务指回旧卷。运行回退入口时通过 `--env-file <一盒目录>/compose.env` 提供原凭据，勿写入命令行。
+
+Kafka 数据也随升级保留。`KAFKA_CLUSTER_ID` 与 `kafka-data` 绑定，备份需同时保留配置与卷；
+已有数据时不能重生成 ID、换空卷或改 `KAFKA_DATA_DIR` 来消除拒启。改变目录不会迁移消息。
+单节点没有高可用，重启期间不可用；需要回退平台代码时保留 Kafka 卷与原配置。
+
+### 停栈与重置
+
+`"$S" dc down` 只停容器、保留卷；下次 `up` 仍会重种门户库。只想重置门户数据也可重跑
+`db:seed:onebox`，随后重跑 `register-app`、重载 Caddy；浏览器需要重新登录。
+
+`down -v` 是主动删除当前 compose 命名卷的操作，pg、RustFS、Kafka、apps、caddy 数据会丢失。
+先备份要保留的 App 数据与对象，再按上表重置；退役 MinIO 卷和 `backup/` 不在新 compose 删除范围内，
+保留供核对，不因升级自动删除。命名卷属主故障按 [排查表 §7](references/troubleshooting.md#7-命名卷属主不对eacces-一族)
+处理，升级本身不要求清空所有数据。
 
 ## 7. 一盒不是门户，别拿它当门户
 
@@ -514,6 +600,11 @@ S="$SKILL_DIR/scripts/onebox.sh"
 - `bootstrap:prod` 与部署控制器**启动即拒**并打印原因；完整的 `db:seed`（十几个 App 的种子链）也必失败，
   一盒只能用 `db:seed:onebox`。
 - 它是 dev 联调套件：mock OAuth 常开、服务账号密钥是已知明文。**不要用于生产，也不要暴露到公网。**
+- `compose.env` 权限 600 只保护宿主文件；一盒仍把整份配置注入容器，是可信 App 之间的本地联调模型，
+  不构成对恶意 App 的凭据隔离。不要把 Kafka 管理密码当作 App 的连接凭据。
 - 不装 ffmpeg：`PREVIEW_MEDIA_CONVERTER_URL` 必须留空，视频海报/网格缩略图退化成图标。
 - 文件管理界面**不渲染预览**（镜像构建时关掉了前端的格式渲染器），打开任何文件都是下载卡；
   服务端的预览描述符 API 不变，你的 App 自带 `@xgent/file-preview` 时照常渲染。
+- **套件（bundle）的共享后端去重在一盒里不发生**：一盒不跑部署控制器（上面那条），
+  套件成员各自仍是「视作 ready」；两个成员共用一个容器这件事要验，去预发或一台 VM 栈，
+  别拿一盒当证据。套件的建/删/成员管理与发版（单发与批次）在一盒里照常可用。

package/skills/portal-dev-setup/puller.env.example

@@ -41,8 +41,9 @@ PROJECT=
 # 目录部署的地址（带协议，无尾斜杠）。同时是 release-cli 投递清单的第二站。
 MANIFEST_STORE=
 
-# 目录【只读】令牌（xcat_…）。它是跨 App 的读凭证 —— 一把泄露 = 全部 App 的公开清单
-# 可读（公开字段而已，里面没有任何密钥），但仍要按凭证对待：chmod 600 + 别提交。
+# 目录【只读】令牌（xcat_…）。它是跨 App 的读凭证 —— 一把泄露 = 全部已上架外部 App 的公开
+# 清单与前端产物可读（公开字段与静态文件而已，里面没有任何密钥），但仍要按凭证对待：
+# chmod 600 + 别提交。
 MANIFEST_STORE_READ_TOKEN=
 
 # ── 发布（xgent-app-release 用的三项，两个 skill 共用本文件）────────────

package/skills/portal-dev-setup/references/kafka.md

@@ -0,0 +1,140 @@
+# 平台 Kafka 接入指引
+
+平台为每个 App 供给一个 Kafka 用户及限定前缀的权限。App 只使用自己的五个环境变量；不要申请或读取 `KAFKA_ADMIN_PASSWORD`。
+
+## 清单与环境变量
+
+以 `listingKey: "order-worker"` 为例，清单声明：
+
+```json
+{
+  "requiredServices": [{ "kind": "kafka", "name": "main" }],
+  "requiredEnv": [
+    "ORDER_WORKER_KAFKA_BROKERS",
+    "ORDER_WORKER_KAFKA_USERNAME",
+    "ORDER_WORKER_KAFKA_PASSWORD",
+    "ORDER_WORKER_KAFKA_SASL_MECHANISM",
+    "ORDER_WORKER_KAFKA_TOPIC_PREFIX"
+  ]
+}
+```
+
+`requiredServices` 的每项只写 `kind`、`name`、可选 `note`，不写地址、密码或 `envKey`。生产由平台管理员登记 Kafka 服务与自动供给档案，批准应用时选择档案、建用户及授权。也兼容只在 `requiredEnv` 声明约定键名的应用；完整列出五键便于交付检查。
+
+| 键后缀 | 用途 / 例子 |
+| --- | --- |
+| `_KAFKA_BROKERS` | 逗号分隔的 `host:port`；容器一盒为 `kafka:9092` |
+| `_KAFKA_USERNAME` | `app_order_worker`；连字符转换成下划线 |
+| `_KAFKA_PASSWORD` | 平台供给的密码，不写进清单、源码或日志 |
+| `_KAFKA_SASL_MECHANISM` | 固定 `SCRAM-SHA-512` |
+| `_KAFKA_TOPIC_PREFIX` | `app.order-worker.`；保留原始 listingKey 的连字符与末尾点 |
+
+环境变量前缀是 listingKey 大写、连字符改成下划线。**主题、消费组、事务 ID 都必须使用 `_KAFKA_TOPIC_PREFIX`**，不能从用户名反推。例如主题 `app.order-worker.events`，消费组 `app.order-worker.readers`，事务 ID `app.order-worker.tx-01`。
+
+## 客户端配置与主题创建
+
+协议为 `SASL_PLAINTEXT`，认证为 `SCRAM-SHA-512`，不是管理员使用的 PLAIN。客户端必须支持 SCRAM-SHA-512，并在重连时继续使用收到的 broker 广告地址。地址不含 `http://`。
+
+以下是 Bun / `@platformatic/kafka` 的配置示例；初始化主题和生产消息使用的是 **App 用户**：
+
+```ts
+import { Admin, Producer, stringSerializers } from "@platformatic/kafka";
+
+function required(key: string): string {
+  const value = process.env[key];
+  if (!value) throw new Error(`缺少 ${key}`);
+  return value;
+}
+const prefix = required("ORDER_WORKER_KAFKA_TOPIC_PREFIX");
+if (required("ORDER_WORKER_KAFKA_SASL_MECHANISM") !== "SCRAM-SHA-512") {
+  throw new Error("Kafka 认证机制不匹配");
+}
+const connection = {
+  clientId: "order-worker",
+  bootstrapBrokers: required("ORDER_WORKER_KAFKA_BROKERS").split(",").map(s => s.trim()),
+  sasl: {
+    mechanism: "SCRAM-SHA-512" as const,
+    username: required("ORDER_WORKER_KAFKA_USERNAME"),
+    password: required("ORDER_WORKER_KAFKA_PASSWORD"),
+  },
+};
+const topic = `${prefix}events`;
+const admin = new Admin(connection);
+try {
+  // 首次部署显式创建；重跑只把“主题已存在”当成功，其它错误必须保留。
+  await admin.createTopics({ topics: [topic], partitions: 1, replicas: 1 });
+} finally {
+  await admin.close();
+}
+const producer = new Producer({ ...connection, serializers: stringSerializers });
+try {
+  await producer.send({ messages: [{ topic, key: "order-42", value: JSON.stringify({ eventId: "unique-event-id" }) }] });
+} finally {
+  await producer.close();
+}
+// 消费者 groupId 使用 `${prefix}readers`；业务处理成功后才提交 offset。
+```
+
+平台关闭自动建主题。App 必须在首次部署或迁移阶段显式创建主题，副本数为 1；不能靠第一次发送消息触发创建。保留期由平台决定，创建时不传 `retention.ms` 等保留配置，需要调整时联系平台管理员。
+
+| 资源（均为 App 前缀） | 授权操作 |
+| --- | --- |
+| 主题 | CREATE、DELETE、DESCRIBE、DESCRIBE_CONFIGS、READ、WRITE |
+| 消费组 | READ、DESCRIBE、DELETE |
+| 事务 ID | WRITE、DESCRIBE |
+
+不授权 ALTER、ALTER_CONFIGS、ALL：App 不能修改主题保留期或增加分区，也不能创建或读写他人主题、加入他人消费组、使用他人事务 ID。幂等生产可用；业务仍需处理重复投递。
+
+## 一盒联调
+
+使用新版 `portal-dev-setup` 的公开脚本：
+
+```bash
+S=/path/to/portal-dev-setup/scripts/onebox.sh
+"$S" add order-worker --manifest ./app.manifest.json --image <已交付的App镜像>
+```
+
+`add` 在清单包含 `<PREFIX>_KAFKA_USERNAME` 或 `requiredServices.kind=kafka` 时启动 Kafka，等待监听，创建 SCRAM-SHA-512 用户（8192 次迭代）和三组前缀 ACL，再把五键写入 `compose.env`。随机密码在第一次写 broker 之前保存；重复 `add` 和部分失败后的重试都沿用它，不会更换已连接客户端的密码。写密钥只显示 `***`。不要手工删掉已保存的密码行后重跑。
+
+容器内连接 `kafka:9092`。宿主热重载进程使用同一用户和密码，但将 BROKERS 改为 `127.0.0.1:<compose.env 的 KAFKA_PORT>`；不要把这一宿主地址写回容器用的五键。`doctor` 只检查 TCP 监听，绿灯不代替认证与收发验证。
+
+一盒将整份 `compose.env` 注入容器，**不提供 App 容器之间的密钥隔离**；仅用于可信团队的本地联调。App 自律只读自己的五键，权限验证也只用该用户，不能把管理员凭据交给 App 客户端。
+
+### 一盒故障恢复
+
+供给失败只告警，门户与应用初始化继续；依赖 Kafka 的 App 可能暂时不可用。先看 `"$S" dc logs --tail 50 kafka`，检查资产版本、磁盘与管理密码是否匹配，再粘贴告警中的 `add` 命令重试。旧资产先 `"$S" upgrade --image <新版一盒镜像>`；保留原 `compose.env` 与 Kafka 卷，不能改 `KAFKA_CLUSTER_ID`。
+
+需要手工确认或修复时，下面的命令只从本地配置读取密码，命令行不含密码字面量。把 `BOX`、`KEY` 改为自己的目录和 listingKey；脚本只接受自动生成的十六进制 / base64 / URL-safe App 密码，不自动覆盖不受支持的自定义密码。
+
+```bash
+BOX=./portal-onebox
+KEY=order-worker
+P=$(printf '%s' "$KEY" | tr 'a-z-' 'A-Z_')
+PASSWORD=$(awk -v key="${P}_KAFKA_PASSWORD" 'index($0,key"=")==1 {v=substr($0,length(key)+2)} END {print v}' "$BOX/compose.env")
+test -n "$PASSWORD" || { echo '先重跑 add，保留它生成的密码'; exit 1; }
+printf '%s\n' "$PASSWORD" | XGENT_ONEBOX_HOME="$BOX" "$S" dc exec -T kafka bash -ec '
+  umask 077; IFS= read -r password
+  dir=$(mktemp -d /tmp/xgent-kafka-admin.XXXXXX)
+  trap '\''rm -rf "$dir"'\'' EXIT
+  trap '\''exit 1'\'' HUP INT TERM
+  jaas=$KAFKA_LISTENER_NAME_INTERNAL_PLAIN_SASL_JAAS_CONFIG
+  printf "security.protocol=SASL_PLAINTEXT\nsasl.mechanism=PLAIN\nsasl.jaas.config=%s\n" "${jaas//\\/\\\\}" > "$dir/admin.properties"
+  printf "SCRAM-SHA-512=iterations=8192,password=%s\n" "$password" > "$dir/user.properties"
+  /opt/kafka/bin/kafka-configs.sh --bootstrap-server kafka:9092 --command-config "$dir/admin.properties" --alter --add-config-file "$dir/user.properties" --entity-type users --entity-name "app_${1//-/_}"
+  acl=(--bootstrap-server kafka:9092 --command-config "$dir/admin.properties" --add --allow-principal "User:app_${1//-/_}" --allow-host "*" --resource-pattern-type prefixed)
+  /opt/kafka/bin/kafka-acls.sh "${acl[@]}" --topic "app.$1." --operation Create --operation Delete --operation Describe --operation DescribeConfigs --operation Read --operation Write
+  /opt/kafka/bin/kafka-acls.sh "${acl[@]}" --group "app.$1." --operation Read --operation Describe --operation Delete
+  /opt/kafka/bin/kafka-acls.sh "${acl[@]}" --transactional-id "app.$1." --operation Write --operation Describe
+' bash "$KEY"
+unset PASSWORD
+# 用原 manifest / image 参数重跑，让 add 补齐五键并重建 App 容器。
+XGENT_ONEBOX_HOME="$BOX" "$S" add "$KEY" --manifest ./app.manifest.json
+```
+
+## 可靠性与网络边界
+
+当前平台 Kafka 是单节点，重启会短暂不可用；没有高可用承诺。按 at-least-once 设计，消费方用业务事件 ID 去重、成功处理后提交 offset，并实现重连与重试。Kafka 不是业务记录系统，权威数据仍在业务数据库 / 对象存储；消息过期后的补偿由 App 自己实现。
+
+隔离粒度是 **App，不是租户**。一个 App 内不同租户的消息，租户字段、消费授权及数据隔离由 App 负责。
+
+SASL_PLAINTEXT 只认证，不加密消息。HOST 和一盒 EXTERNAL 默认回环；跨 VM 接入由运维同时配置外部监听、客户端可达的广告地址与限来源安全组，不能只改 bootstrap 地址。不要自行开放公网端口。备份 / 恢复必须同时保留 Kafka 卷、`KAFKA_CLUSTER_ID` 和配置，不能把同一个卷搭配新集群 ID。

package/skills/portal-dev-setup/references/troubleshooting.md

@@ -22,8 +22,13 @@
 
 | 你看到 | 真相 |
 | --- | --- |
-| `portal-api` / `files-server` / `git-server` … 长期 `(unhealthy)`，但功能一切正常 | **先读探针再判**：`docker inspect <容器> --format '{{json .Config.Healthcheck.Test}}'`。是 `curl -fsS …/health` ⇒ **假红**，且说明这盒的 compose 是旧镜像那份（精简镜像没装 `curl`，`.State.Health` 里清一色 `curl: not found`）；已经是 `bun -e fetch(...)` ⇒ **真红**，去看 `"$S" dc logs <服务>`。判活一律以 `"$S" smoke` 为准；pg/redis/minio 的 healthy 一直是真的 |
+| `portal-api` / `files-server` / `git-server` … 长期 `(unhealthy)`，但功能一切正常 | **先读探针再判**：`docker inspect <容器> --format '{{json .Config.Healthcheck.Test}}'`。是 `curl -fsS …/health` ⇒ **假红**，且说明这盒的 compose 是旧镜像那份（精简镜像没装 `curl`，`.State.Health` 里清一色 `curl: not found`）；已经是 `bun -e fetch(...)` ⇒ **真红**，去看 `"$S" dc logs <服务>`。判活一律以 `"$S" smoke` 为准；pg/redis/RustFS 的 healthy 一直是真的 |
 | `reverse-proxy` 长期 `(unhealthy)`，而 `https://localhost/` 一切正常 | **旧镜像上必然的假红**（与站点地址有关，不是 Caddy 坏了）：那条探针是 `wget -q -O /dev/null http://127.0.0.1:80/`，`XGENT_SITE_ADDRESS` 一旦是主机名，Caddy 就把它 308 到 `https://127.0.0.1/` —— 对一个 **IP** 建 TLS 没有 SNI，`on_demand_tls` 选不出证书，回 `SSL alert number 80`（`docker inspect <容器> --format '{{range .State.Health.Log}}{{.Output}}{{end}}'` 能看到）。新镜像换成了不跟随重定向的 `curl -fsS -o /dev/null http://127.0.0.1:80/`，308 本身即判活 |
+| `up` 提示「资产是旧版」/ 没有 rustfs 服务或切换脚本 | 指定新版 tag 跑 `"$S" upgrade --image <ref>` 后 `up`；沿用 latest 先 pull，再 upgrade → up。init --force 是重置，不用于升级 |
+| RustFS 控制台端口根路径返回 403 | 打开 `http://localhost:<MINIO_CONSOLE_PORT>/rustfs/console/`；存活探测走 API 口 `/health` |
+| PostgreSQL 报版本不兼容，或升级前检查提示未知/冲突数据布局 | 保留现有卷和原镜像，勿 down -v。脚本按卷内 PG_VERSION 保留已有大版本与挂载点；不能识别时先核对布局，不初始化空库。真正的大版本迁移另行备份并用 pg_upgrade/导出恢复 |
+| 对象存储切换未提交、退出 10/20 | 按脚本提示处理并保留备份；原服务会在安全条件满足时恢复。已检测到正式 RustFS 时不要删除新卷 |
+| 已提交但 RustFS 不健康 / 回退提示数据有变化 | `rustfs-data` 是权威，勿删。回退先隔离正式服务，变化时拒绝回旧卷，需复制新卷做人工核验；细节见 SKILL.md §6 |
 | `curl http://localhost/api/health` → 404 `路由不存在` | **探错路径了。** 门户健康端点是 `/health`，不带 `/api`；各服务是 `/svc/<key>/health` |
 | 改了 `compose.env` 却「没生效」 | 这份文件是**拼装**出来的（基础模板 + 一盒增量 + devkit 增量 + 本机覆盖块），同一个键出现三四次很常见。**docker compose 后定义者胜**，你多半改在了中间那处。`"$S" env` 会把「同键多个不同值」标出来，并显示实际生效的那个。改配置一律往**文件最末尾**加 |
 | 一盒里 `bun --filter @xgent/<某个>-server …` 报 `no packages matched the filter` | **刻意的。** 精简镜像只保留 `files` / `llm-gateway` / `git` / `org` 四个基础服务的代码，其余在构建时就删掉了（`ingest` 已移出基础集） |
@@ -47,7 +52,7 @@
 | 「镜像域名与配置里的 REGISTRY 对不上」 | `--image` 的域名段和 `REGISTRY` 不是同一个 —— 登录 A 却去 B 拉，必然 401。对齐这两个再来 |
 | 想确认账号到底能不能用 | **判据只有 `docker pull` 本身。** 别拿 `curl` 去探仓库的管理 API（`/v2/_catalog` 之类）——只读账号在那里的 401/403 跟能不能拉是两回事 |
 | `manifest unknown` / `not found` | 按顺序查两条。① **项目名不对**——一盒镜像与**你自己 App 的镜像不在同一个项目**下，而 `.xgent-registry.env` 里的 `PROJECT` 是后者（`xgent-image-push` 用的那个）。填 `ONEBOX_PROJECT=<一盒的项目名>`（找开发团队要），或 `--image` 给全。脚本回退用 `PROJECT` 时会打一行黄色告警，**那行就是答案**。② **tag 写错**——一盒只有 `:latest`（可变指针）和 `:v<版本>-<7位sha>`（不可变）两种，别自己编版本号 |
-| 拉过了却还是旧的一版（修好的 bug 又出现） | 用的是 `:latest` 而本地已经有一份同名的 —— `docker run` / compose **默认不回仓库查**。`onebox.sh pull` 一次再 `dc up -d`；要钉住某一版就把 `compose.env` 里那两行改成 `:v<版本>-<sha>` |
+| 拉过了却还是旧的一版（修好的 bug 又出现） | 用的是 `:latest` 而本地已经有一份同名的 —— `docker run` / compose **默认不回仓库查**。先 `onebox.sh pull` 更新 latest 缓存，再 `upgrade` → `up` 同步资产；要钉住某一版用 `upgrade --image <ref>` |
 | `no matching manifest for linux/amd64` | 一盒只发 arm64（它是给开发机用的调试底座）。`--platform linux/arm64` 硬拉下来容器也起不来（`exec format error`）。要 amd64 找开发团队 |
 | **你自己的** `app-backend` 起来就 `exec format error`（或 `no matching manifest`） | 架构反了：生产镜像按规矩是 **amd64**，而开发机多半是 arm64，devkit 跟随本机架构、不会替你转译。叠一层 override 指定平台（SKILL.md §1 有现成的 `app-platform.yml`），Apple Silicon 上走 Rosetta，慢但能跑。⚠️ 别为了本地方便去发一个 arm64 的生产 tag |
 | 卡在 `Retrying in N seconds` 直到超时 | 链路或代理。把 `HTTP_PROXY`/`HTTPS_PROXY` 与 Docker Desktop 的代理设置对齐，或临时关掉代理重试 |
@@ -62,7 +67,13 @@
 
 | 症状 | 成因与修法 |
 | --- | --- |
-| `port is already allocated` | 一盒只发布 6 个宿主端口：80/443（`HTTP_PORT`/`HTTPS_PORT`）· 5432（`POSTGRES_PORT`）· 6379（`REDIS_PORT`）· 9000/9001（`MINIO_PORT`/`MINIO_CONSOLE_PORT`）。`init` 会自动避开当时被占的，但你**之后**又起了别的东西就会撞——改 `compose.env` 末尾那几行。⚠️ 改了 `HTTP_PORT` 要同步 `PORTAL_BASE_URL` 与 `FILES_APP_URL`，否则浏览器侧的绝对链接指错端口（`"$S" env` 会告警） |
+| `port is already allocated` | HTTP/HTTPS、PG、Redis、RustFS 加上 Kafka HOST/EXTERNAL 共 8 个宿主口。`init` 为原有 6 口与 Kafka HOST（`KAFKA_PORT`，9092/19092/29092）自动避让；Kafka EXTERNAL 默认回环 9095，占用时另设 `KAFKA_EXTERNAL_PORT`。自动挑选只避开当时被占的，但你**之后**又起了别的东西就会撞——改 `compose.env` 末尾那几行。⚠️ 改了 `HTTP_PORT` 要同步 `PORTAL_BASE_URL` 与 `FILES_APP_URL`，否则浏览器侧的绝对链接指错端口（`"$S" env` 会告警） |
+| Kafka 未健康，但 `up` 继续运行 | Kafka 最多软等 60 秒，失败不阻塞门户。先 `"$S" doctor`、`"$S" dc logs --tail 50 kafka`；TCP healthy 也不代表某个 App 的账号/ACL 可用。基础设施起停不会自动供给 App 身份，勿拿管理员密码替代 |
+| Kafka 日志报 `InconsistentClusterIdException` / cluster ID 不匹配 | 配置与已有卷不配对。保留卷，恢复与该卷对应的原 `KAFKA_CLUSTER_ID`；从备份核对，不运行 `init --force` 重生成，不删卷、不换空目录 |
+| Kafka `Permission denied`，使用了 `KAFKA_DATA_DIR` | 确认使用原来的绝对路径、目录属主为 `1000:1000`，再重试。默认命名卷不需要另找宿主目录；不要用换目录绕过权限问题 |
+| Kafka 外部 bootstrap 能连，但读取 metadata 后超时 | broker 返回的 EXTERNAL 广告地址对客户端不可达；生产运维需同时核对 `KAFKA_EXTERNAL_BIND`、非回环的 `KAFKA_EXTERNAL_HOST`、端口与安全组。一盒保持回环；宿主用 HOST，同 compose 网络用 `kafka:9092` |
+| 升级后缺 Kafka 三键 / 仍是开发默认 | `"$S" upgrade` 使用新版资产，只补缺 `KAFKA_CLUSTER_ID` / `KAFKA_ADMIN_PASSWORD` / `KAFKA_PORT`，已有值保留；不要手动填空赋值阻止生成。需修复已有空值时先核对卷和原配置，不要给已有卷随机新 ID |
+| Kafka 主题不存在且没有自动创建 | `auto.create.topics.enable=false` 是配置约定，不能靠发送消息隐式创建；App 身份与主题授权由后续供给流程处理，不使用管理账号接业务 |
 | 起了一盒，**别的** compose 栈的容器被停/被接管 | 两套栈同名。`COMPOSE_PROJECT_NAME` 相同 ⇒ compose 认为是同一项目，容器名冲突、命名卷共享。一盒项目名固定 `xgent-onebox`，同机只该有一套——已有在跑的一盒时别再 init 第二套，把你的 App 接进现有那套（SKILL.md 文首「一套就够」） |
 | 报缺 `APP_IMAGE` / `APP_KEY` | `docker-compose.app-dev.yml` 里的 `${APP_IMAGE:?}` 是**解析期**求值的，跟 profile 无关。`$S` 会按 `compose.env` 里这两行有没有值自动决定带不带那层——手敲 compose 时才会撞上 |
 | 报缺 `APP_FRONTEND_DIST` | 你给 `service` 型 App 叠了前端 override。service 无前端，不要那层 |
@@ -78,7 +89,7 @@
 
 | 症状 | 成因与修法 |
 | --- | --- |
-| `/svc/<key>/...` → **404** | `/svc` 放行 map 没写成，或**反代在写 map 之前就起了**（Caddy 启动时才读那个目录，不会热重载）。跑 `register-app`，然后 `"$S" dc exec reverse-proxy caddy reload` |
+| `/svc/<key>/...` → **404** | `/svc` 放行 map 没写成，或**反代在写 map 之前就起了**（Caddy 启动时才读那个目录，不会热重载）。跑 `register-app`，然后 `"$S" dc exec reverse-proxy caddy reload`（`add` / `up` 注册完会自动重读；只有自己手工跑 `register-app` 时才要这一步） |
 | `register-app` 输出里有 `/svc 放行未写成 … EACCES: permission denied`，随后 `/svc/<key>` 404 | 命名卷属主不对，见 **[§7](#7-命名卷属主不对eacces-一族)**（那一节的修法一次修好全部三个卷）。注册本身是成功的，缺的只是那一行放行 |
 | `/svc/<key>/...` → **502** | 后端不在。① 容器没起/崩了：`"$S" dc logs app-backend`；② 没监听容器内 **8080**（反代的通用规则是 `/svc/<key>/* → <key>-server:8080`，多数镜像认 `PORT`，你的若要别的变量名就在 `compose.env` 里补）；③ `APP_KEY` 与 manifest 的 `listingKey` 不一致，网络别名 `<key>-server` 没命中 |
 | 探测全是 **000** | 反代根本没起，或你探的端口不是 `HTTP_PORT`。`"$S" dc ps` / `"$S" dc logs reverse-proxy` |
@@ -104,8 +115,9 @@
 
 | 症状 | 成因与修法 |
 | --- | --- |
-| `register-app` 成功、控制台「清单管理」也看得到，但**演示租户的应用市场里没有卡片** | 授予行没写成。市场对租户是 **fail-closed** 的：没有 `tenant_listing_grants` 行就连卡片都不出现，且**不报错**。dev 模式的 `register-app` 本该顺手授予现有租户——**旧一点的一盒镜像里没有这段代码**，所以先 `"$S" pull` 换新镜像重跑一遍；换了还没有，就用平台管理员账号在控制台「租户 → 可用应用」里把它勾上（或 `PUT /api/console/tenants/<id>/apps`），再回市场安装 |
+| `register-app` 成功、控制台「清单管理」也看得到，但**演示租户的应用市场里没有卡片** | 授予行没写成。市场对租户是 **fail-closed** 的：没有 `tenant_listing_grants` 行就连卡片都不出现，且**不报错**。dev 模式的 `register-app` 本该顺手授予现有租户——**旧一点的一盒镜像里没有这段代码**，所以按 SKILL.md §6 更新缓存后 `upgrade` → `up` 换新镜像与资产重跑一遍；换了还没有，就用平台管理员账号在控制台「租户 → 可用应用」里把它勾上（或 `PUT /api/console/tenants/<id>/apps`），再回市场安装 |
 | `register-app` 报 `VALIDATION_FAILED`（scope） | manifest 声明了**别的 App 的 scope**，却没把那个 App 列进 `exchangeTargets`。规则：一个 listing 能声明的 scope = 平台基础 scope ∪ 本 namespace（`<listingKey>` 及其下划线变体，如 `omni-parser` → `omni_parser`）∪ 已声明 `exchangeTargets` 的 namespace |
+| `register-app` 报 `DEPENDENCY_UNAVAILABLE`（依赖的应用清单不存在：`<dep>`） | 清单 `dependencies` 里的 App 在这台一盒里还没有**注册**（跟装没装无关）。先 `"$S" add <dep>`（`add` 会在拉镜像之前预检，把缺的一次列全）。如果你自己的 App 是靠 `up` 注册的，补完依赖后**单独**重跑注册那一条：`"$S" dc run --rm -v "$PWD:/devkit:ro" portal-api bun run register-app /devkit/app.manifest.json`。**别重跑 `up`**：它的种子会 truncate 清单表，刚加的依赖又没了。之后在「应用管理 → 应用市场」里安装你的 App，依赖会一起装上 |
 | `register-app` 拒跑，提到 production | dev 模式的 `register-app` 拒绝 `NODE_ENV=production`。`compose.env` 末尾必须有 `NODE_ENV=development` |
 | 跑完 `db:seed:onebox` 后市场里找不到你的 App | **顺序反了。** 种子第一步是 `truncate … marketplace_listings … cascade`，先注册后种子 = 注册被清掉。必须 seed 在前、register-app 在后 |
 | `seed:onebox` 报 `unknown listing key` | 那个 key 既不是内置基础服务，`app-devkit/manifests/<key>.manifest.json` 也不存在。要么放一份 manifest 进去，要么把它从 `XGENT_APP_CATALOG` 里去掉 |
@@ -124,29 +136,13 @@
 旧镜像里这三个目录压根不存在，于是谁先起谁定调，卷落到 root 手里，portal-api 就写不进去了。
 `one-box` / `proxy` 的 **v1.2.0 起**已在 runtime 层预建这三个目录并 chown 给 `bun`（`latest` 已指向它）。
 
-> ⚠️ **光 `docker pull` 不解决**。镜像里的内容与属主只在卷**为空**时用来初始化它；已经建坏的卷
-> 不会因为换镜像而改属主。反过来也一样：**只 `down -v` 不换镜像**，用老镜像重建出来的还是 root 的卷。
-> 两件事要一起做，顺序是 **先换镜像、再删卷**。
+镜像升级不会自动改变已有卷的属主。先按 SKILL.md §6 更新镜像缓存，再用 `"$S" upgrade` 同步部署资产，再按下面的定点修法纠正
+这三个目录的属主；不需要删除 PostgreSQL 或对象存储卷。随后 `"$S" up` 会按一盒既有规则重种门户库。
 
-### 修法：换镜像 + 重铺（首选）
+若主动选择丢弃所有当前联调数据，可按 SKILL.md §6 的重置路径执行 `dc down -v` → `init --force` → `up`。
+重置会丢失 App 数据与对象；它不是升级的必经步骤。
 
-一盒是**本地联调环境，数据不值钱**，别为了保住一个演示库去绕。
-
-```bash
-S="$SKILL_DIR/scripts/onebox.sh"
-# 1) 换到 v1.2.0+（compose.env 末尾若把 XGENT_IMAGE / XGENT_PROXY_IMAGE 钉了 tag，先改成 latest 或 v1.2.0-*）
-"$S" pull
-# 2) 连卷一起删 —— pg / minio / apps / caddy 全没，这一步就是目的
-"$S" dc down -v
-# 3) 按 SKILL.md §2 的固定顺序重铺：migrate → seed:onebox → 各库 migrate → register-app → up
-```
-
-重铺完记得**重跑 `register-app`**（listing 被种子清掉了），浏览器要重登一次 dev 登录（种子换了 UUID）。
-
-**自查在哪一版**：`docker images --digests | grep -E 'one-box|/proxy'`。旧版 `one-box` 是
-`sha256:76b99254…`、`proxy` 是 `sha256:1e44e014…`；新版分别是 `sha256:7011de3b…` / `sha256:a0c9f304…`。
-
-### 备选：就地 chown（只在你确实不想重跑种子时）
+### 定点修复属主
 
 反代是 root 且挂着同样这三个卷，所以补属主不必进 portal-api：