合入最新 master

合并 origin/master 并保留平台入口运行态与推荐链路语义修正合并后基于 tab 语义变化的前端断言
2026-06-11 22:59:35 +08:00
parent 9d1dd493a6 b54cbafc54
commit cfc0c0eadf
120 changed files with 9591 additions and 1099 deletions
@@ -16,6 +16,30 @@

 ---

+## 2026-06-11 本地服务器管理入口采用 SSH alias + egui 桌面面板
+
+- 背景：release / dev 等服务器的日常巡检已有 systemd、健康巡检 timer 和 HTTP 探测口径，但开发者本地仍需要在多个 SSH alias 间手工切换命令并重复执行启停操作。
+- 决策：新增 `server-rs/crates/server-manager-panel` 作为本地 egui 桌面工具；服务器来源只读取本机 `~/.ssh/config` 的具体 `Host` alias，不保存服务器密钥或凭据；巡检通过 `ssh <alias> sh -s` 执行只读脚本，服务操作只允许 `start`、`stop`、`restart` 并限制 systemd unit 名字符集。
+- 影响范围：本地运维工具入口、`package.json` 的 `server-manager:panel`、开发运维文档和团队共享工作流。
+- 验证方式：`cargo check -p server-manager-panel --manifest-path server-rs/Cargo.toml`、`cargo test -p server-manager-panel --manifest-path server-rs/Cargo.toml`、`npm run check:encoding`。
+- 关联文档：`docs/technical/【开发运维】本地SSH服务器管理面板技术方案-2026-06-11.md`。
+
+## 2026-06-10 公开作品互动能力进入后台全局配置
+
+- 背景：作品详情页的点赞和改造能力原本由前端和各玩法 handler 的硬编码能力矩阵决定，后台无法临时关闭某类公开作品的互动入口，直接关闭创作入口又会误伤已有作品读取和游玩。
+- 决策：公开作品点赞 / 改造能力作为 `creation_entry_config.public_work_interactions_json` 的全局矩阵保存，不进入单个 `creation_entry_type_config`。`GET /api/creation-entry/config` 下发 `publicWorkInteractions`；后台通过 `/admin/api/creation-entry/config/interactions` 按 `sourceType` 保存点赞、改造开关和关闭提示；api-server 只对已经接入后端动作的 RPG / custom-world、大鱼吃小鱼和拼图 like / remix 路由做同源熔断，公开列表、详情读取、已发布作品启动和运行态请求不受影响。
+- 影响范围：`CreationEntryConfigResponse`、`AdminCreationEntryConfigResponse`、`module-runtime` 默认矩阵、`spacetime-module` 表字段和 procedure、`spacetime-client` 绑定、后台入口开关页、平台作品详情点赞 / 改造意图解析。
+- 验证方式：`npm run spacetime:generate`、`npm run check:spacetime-schema`、`cargo test -p module-runtime public_work_interaction_config_defaults_and_overrides --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server public_work_interactions --manifest-path server-rs/Cargo.toml`、后台和前台作品详情互动相关前端测试。
+- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
+## 2026-06-10 dev Gitea 提供内网 HTTP 入口
+
+- 背景：release / dev 目标 agent 需要从 dev 自托管 Gitea 拉取仓库；继续走 `https://git.genarrative.world/...` 会绕公网链路，`10.2.0.10:3000` 又受云侧端口策略影响不能作为稳定入口。
+- 决策：dev 上 Gitea 进程保持 `HTTP_ADDR = 127.0.0.1`、`HTTP_PORT = 3000`，公网 `ROOT_URL = https://git.genarrative.world/` 不变；新增 Nginx 内网 vhost `/etc/nginx/conf.d/gitea-internal.conf`，只允许 `10.2.0.0/16` 与本机访问，并把 `http://10.2.0.10/` 反代到本机 Gitea。内网 agent 统一使用 `http://10.2.0.10/GenarrativeAI/Genarrative.git` 作为可直连 Git 源。
+- 影响范围：dev Gitea / Nginx 运维配置、Jenkins `SOURCE_GIT_REMOTE_URL`、release / dev 目标 agent checkout 口径。
+- 验证方式：从 release 执行 `git ls-remote http://10.2.0.10/GenarrativeAI/Genarrative.git HEAD` 应返回 HEAD；公网来源伪造 `Host: 10.2.0.10` 访问 dev 公网 80 应返回 `403`；`https://git.genarrative.world/` 原入口应保持 `200`。
+- 关联文档：`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+
 ## 2026-06-08 微信能力按领域收口

 - 背景：微信登录、订阅消息、普通微信支付和小程序虚拟支付能力曾分散在 `api-server` 根模块、`platform-auth` 与 `platform-wechat`，支付协议细节和业务 handler 边界不够清晰。
@@ -511,6 +535,7 @@

 - 背景：`Genarrative-Server-Provision` 的 `DEPLOY_TARGET=development` 语义是部署到 dev 服务器，不是构建机 dry-run。旧流水线把 development 映射到 `linux && genarrative-build`，还先在 build 节点准备 `provision-tools/` 再 stash 给后续阶段，导致真实 dev 初始化可能跑到 Jenkins controller / build 节点；脚本还安装 clang / lld / pkg-config / OpenSSL headers / sccache 等构建链依赖，超出了服务器初始化职责。
 - 决策：Server-Provision 只做服务器初始化，全程运行在目标部署 agent：development 使用 `linux && genarrative-dev-deploy`，release 使用 `linux && genarrative-release-deploy`。`Prepare Provision Tools` 与 `Provision Server` 在同一个目标 agent workspace 顺序执行，不再切到 `linux && genarrative-build`，不再 `stash/unstash` 工具包。`scripts/jenkins-server-provision.sh` 不再安装 clang / lld / pkg-config / libssl-dev / sccache；非 dry-run 仍要求目标 dev / release agent 具备 root 权限，因为 provision 会写 systemd、Nginx、`/etc` 和系统用户。Job 的 `Pipeline script from SCM` 与 Jenkinsfile 参数 `SOURCE_GIT_REMOTE_URL` 都必须使用本机路径或目标 agent 可访问的内网 Git 源，不允许公网 Git fallback。
+- 追加决策（2026-06-10）：`Prepare Provision Tools` 必须先读取目标机现状，再准备需要的文件。目标机 `/usr/local/bin/otelcol-contrib` 版本匹配 `OTELCOL_VERSION` 时直接复用；`${SPACETIME_ROOT}/bin/current/spacetimedb-cli` 和 `spacetimedb-standalone` 存在且 CLI 版本匹配 `SPACETIME_EXPECTED_VERSION` 或 `SPACETIME_DOWNLOAD_ROOT` 中的版本时，直接复用当前安装生成 `provision-tools/`。只有目标机缺失、不可执行或版本不匹配时，才消费 `PROVISION_DOWNLOADS_DIR` 中的本地包或进入下载分支。
 - 影响范围：`jenkins/Jenkinsfile.production-server-provision`、`scripts/jenkins-server-provision.sh`、生产运维文档、Server-Provision 排障口径。
 - 验证方式：Jenkins 日志中 Server-Provision 的 `Prepare`、`Checkout Provision Files`、`Prepare Provision Tools` 和 `Provision Server` 都在目标 dev / release agent 上执行；日志不出现 `Running on Jenkins`、`linux && genarrative-build`、`stash 'server-provision-tools'`、`Git 主地址拉取失败...改用备用地址`、`https://git.genarrative.world/GenarrativeAI/Genarrative.git` 或构建依赖 / sccache 安装步骤；`bash -n scripts/jenkins-server-provision.sh` 和编码检查通过。
 - 关联文档：`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
@@ -672,7 +697,7 @@
 - 背景：Match3D、SquareHole、Puzzle、Jump Hop 等 runtime client 重复手写 path segment 编码、JSON header / body、runtime guest token、auth options 和 retry options，新增玩法容易遗漏同一请求骨架。
 - 决策：新增 `src/services/runtimeRequest.ts`，以 `buildRuntimeApiPath` 统一 runtime path 编码，以 `requestRuntimeJson` 统一 JSON 请求、runtime guest auth 和 retry 合并。Match3D 与 SquareHole runtime client 已先迁移，保留原导出函数名、错误文案、返回契约和重试常量。
 - 追加决策：Big Fish 与 Bark Battle runtime client 也迁入 `runtimeRequest.ts`；玩法专属 payload 归一化（如 Bark Battle start / finish 自动补 `workId`、`runId`）仍留在各玩法 client，通用 Module 只承接请求骨架。
- 追加决策：Puzzle 的 start / get / swap / drag / next-level / leaderboard 与 Jump Hop 的 start / jump / restart 也迁入 `runtimeRequest.ts`；Puzzle `pause` 与 `props` 仍保留原账号态 auth options，不直接接入 runtime guest auth。
+- 追加决策：Puzzle 的 start / get / swap / drag / next-level / leaderboard / pause / props 与 Jump Hop 的 start / jump / restart 也迁入 `runtimeRequest.ts`；只要调用方传入 Runtime Guest Token，所有正式 runtime 请求都统一带局部 Authorization、`skipAuth` 与 `skipRefresh`。
 - 追加决策：Wooden Fish 的 start / checkpoint / finish 与 Visual Novel 的 gallery / run / history / regenerate JSON 请求也迁入 `runtimeRequest.ts`；Wooden Fish 的 `clientEventId` 生成仍留在木鱼 client，Visual Novel start 因 `timeoutMs`、SSE 因流式 `fetchWithApiAuth` 仍暂留原实现。
 - 影响范围：`src/services/runtimeRequest.ts`、Match3D / SquareHole / Big Fish / Bark Battle / Puzzle / Jump Hop / Wooden Fish / Visual Novel runtime client。
 - 验证方式：`npm run test -- src/services/runtimeRequest.test.ts src/services/recommendedRuntimeGuestLaunch.test.ts src/services/match3d-runtime/match3dRuntimeAdapter.test.ts`、`npm run typecheck`、`npm run check:encoding`、相关文件 ESLint 通过。
@@ -821,7 +846,7 @@
 ## 2026-05-25 抓大鹅运行态 HUD 收敛为拼图同款低遮挡样式

 - 背景：抓大鹅游玩阶段 UI 需要继续对齐拼图运行态的观感，同时移除右上角设置入口、灰白半透底板和显眼锅壳，让棋盘区域更专注。
- 决策：抓大鹅运行态只保留左上透明返回按钮，右上不再显示设置入口；顶部关卡名和倒计时直接复用拼图同款的铭牌 + 下挂计时牌结构、同色板、同造型和 `media/logo.png` 产品 logo；底部备选栏和道具图标保持交互边界但不再显示灰白半透底；中央容器图层可以视觉隐藏，但棋盘命中边界和既有交互逻辑保留。
+- 决策：抓大鹅运行态只保留左上透明返回按钮，右上不再显示设置入口；顶部关卡名和倒计时直接复用拼图同款的铭牌 + 下挂计时牌结构、同色板、同造型和 `media/logo-runtime-hud.webp` 产品 logo 小图；底部备选栏和道具图标保持交互边界但不再显示灰白半透底；中央容器图层可以视觉隐藏，但棋盘命中边界和既有交互逻辑保留。
 - 影响范围：`src/components/match3d-runtime/Match3DRuntimeShell.tsx`、`src/components/match3d-runtime/Match3DRuntimeShell.test.tsx`、`src/index.css`、抓大鹅玩法链路文档。
 - 验证方式：运行态页面不再渲染“打开抓大鹅设置”，顶部仍显示关卡名和倒计时，底部槽位和道具按钮 class 中不含旧白底视觉；相关测试通过后保持该口径。
 - 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
@@ -2156,3 +2181,11 @@
 - 影响范围：`shared-contracts` 默认 spec、`module-runtime` 入口配置响应、`spacetime-module` 后台保存校验、后台入口开关页摘要和前端 fallback spec。
 - 验证方式：`GET /api/creation-entry/config` 中各玩法 `unifiedCreationSpec.title` 等于已保存契约内容；后台只修改入口名称时不应隐式改写已保存的统一创作页表头。
 - 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
+## 2026-06-11 资产计费边界改为 fail-closed 并补偿退款
+
+- 背景：图片 / 资产生成入口曾在钱包或 SpacetimeDB 预扣费连通性异常时允许继续生成，且失败后同步退款如果遇到 SpacetimeDB 短暂不可用缺少本地补偿；拼图首图后台任务还使用 api-server 进程内 HashSet 互斥，多实例下不能防重复。
+- 决策：暂不实现 token 限流。所有资产生成预扣费改为 fail-closed，预扣费失败直接返回错误；支持 retry 的计费 ledger id 统一包含 HTTP `request_id`，前端静默刷新重试复用同一个 `x-request-id`。生成失败后的退款先同步调用 SpacetimeDB，失败则写入 `wallet-refund-outbox` 本地文件并由后台 worker 重放。拼图首图后台生成互斥改为 SpacetimeDB `puzzle_background_compile_task` 表，使用 `task_id + request_id` 作为 claim id，释放时校验 claim id，避免旧任务误删新租约。
+- 影响范围：`api-server` 资产计费包裹、钱包退款补偿、拼图首图后台生成、`spacetime-module` 拼图 task 表、`spacetime-client` bindings/facade、前端 API request id 复用和后端架构文档。
+- 验证方式：`npm run spacetime:generate`、`npm run check:spacetime-schema`、`npm run check:spacetime-runtime-access`、`node scripts/check-server-rs-ddd-boundaries.mjs`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml wallet_refund_outbox`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml asset_operation`、`npm run test -- src/services/apiClient.test.ts`、`npm run check:encoding`。
+- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
@@ -95,6 +95,15 @@ npm run dev:web
 npm run dev:admin-web
 ```

+本地 SSH 服务器管理面板：
+
+```bash
+npm run server-manager:panel
+```
+
+该命令启动 `server-rs/crates/server-manager-panel` 的 egui 桌面工具，从本机 `~/.ssh/config` 读取可用 `Host` alias，支持多服务器健康巡检、可折叠侧边栏和受控 systemd 服务启停。服务操作通过远端 `sudo -n systemctl start|stop|restart <unit>` 执行，目标服务器需要提前配置对应 unit 的免交互 sudo 权限。
+面板启动时会自动注入本机中文字体；如开发机中文仍显示为方块，可设置 `GENARRATIVE_SERVER_PANEL_CJK_FONT=/path/to/font.ttc|index` 指向本机 CJK 字体。
+
 `npm run dev:api-server` 会保留终端实时输出，并把同一份输出持久化到 `logs/api-server/api-server-<timestamp>.log`。完整联调入口 `npm run dev` 启动的 Rust `api-server` 使用同一套日志规则。如需改写路径，可设置 `GENARRATIVE_API_SERVER_LOG_FILE`；如只改目录，可设置 `GENARRATIVE_API_SERVER_LOG_DIR`。

 开发态 `npm run dev` / `npm run dev:api-server` 默认打开 `GENARRATIVE_DEV_PASSWORD_ENTRY_AUTO_REGISTER_ENABLED=true`，密码入口可以直接注册未知手机号账号；生产默认仍关闭该开关。
@@ -15,6 +15,22 @@
 - 关联：相关文件、文档、提交或 Issue
 ```

+## 生产冷备份后 API 不能只依赖 SpacetimeDB 自恢复
+
+- 现象：release 机器 `03:20` 冷备份后，`spacetimedb.service` 已恢复，但作品列表、创作入口配置或公开 gallery 继续超时 / 502 / 504，`genarrative-api.service` 保持 stopped。
+- 原因：`genarrative-api.service` 配置了 `Requires=spacetimedb.service`，冷备份停止 `spacetimedb.service` 时 API 会被 systemd 依赖关系一并停止；如果 `genarrative-database-backup.service` 只传 `--stop-service spacetimedb.service` 而漏掉 `--restart-service-after genarrative-api.service`，备份脚本只会恢复数据库，不会再拉起 API。
+- 处理：生产冷备份 unit 和发布脚本必须带 `--restart-service-after genarrative-api.service`；仓库用 `npm run check:production-ops` 检查 systemd 模板、API build/deploy 归档和健康巡检链路。现场修复后执行 `systemctl daemon-reload`，但不要为了验证而手动触发冷备份。
+- 验证：`systemctl cat genarrative-database-backup.service` 应包含该参数；`systemctl is-active spacetimedb.service genarrative-api.service nginx.service` 全为 `active`；`curl -fsS http://127.0.0.1:3101/v1/ping`、`/healthz`、`/readyz` 和代表性 `/api/runtime/puzzle/gallery` 均成功。
+- 关联：`deploy/systemd/genarrative-database-backup.service`、`scripts/database-backup-to-oss.mjs`、`scripts/ops/production-health-patrol.mjs`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+
+## SpacetimeDB 45 秒超时要看 api-server 记录的阶段
+
+- 现象：release 上 Nginx 能立刻连到 `api-server`，但 `/api/runtime/*/gallery`、`/api/creation-entry/config` 等请求在约 `GENARRATIVE_SPACETIME_PROCEDURE_TIMEOUT_SECONDS` 后返回 `502` / `504`。
+- 原因：旧日志只能看到 HTTP 总耗时和最终状态，无法区分卡在连接池、SDK 建连、等待 `on_connect`、订阅 read model、等待 procedure / reducer 回调还是本地订阅 cache 读取。
+- 处理：`spacetime-client` 内置阶段化健康检查和失败日志；`/readyz` 用 `GENARRATIVE_SPACETIME_HEALTH_CHECK_TIMEOUT_SECONDS` 短窗口检查 SpacetimeDB 连接租约，业务失败日志包含 `operation_kind`、`operation_name`、`spacetime_stage`、`elapsed_ms`。
+- 验证：`/readyz` 失败时看 `details.spacetime.stage`；业务请求超时时查 `journalctl -u genarrative-api.service` 中同一时间窗口的 `SpacetimeDB client operation failed`，优先按 `pool_acquire`、`connect_build`、`connect_handshake`、`read_model_subscribe`、`procedure_result`、`reducer_result`、`read_cache` 分阶段处理。
+- 关联：`server-rs/crates/spacetime-client/src/lib.rs`、`server-rs/crates/api-server/src/health.rs`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+
 ## 新建草稿扣费不能和入口卡泥点配置分离

 - 现象：后台修改创作入口的 `mudPointCost` 后，入口卡和前置余额提示可能显示新数值，但用户真实钱包流水仍按代码常量扣除。
@@ -1119,6 +1135,8 @@
 - 现象：刷新网页后，用户明明有本地 access token，却回到未登录状态。
 - 原因：`AuthGate` hydrate 曾先强制调用 `refreshStoredAccessToken()`；当 refresh cookie 临时失效、代理错配或后端返回 `401` 时，该方法会先清空本地 access token，随后 `/api/auth/me` 只能恢复成未登录。
 - 处理：`refreshStoredAccessToken()` 增加 `clearOnFailure` 选项；`AuthGate` 在已有本地 access token 时先用 `/api/auth/me` 确认用户，确认成功后再后台 refresh 续期与写每日登录埋点，后台 refresh 失败不清 token。
+- 追加处理：`/api/auth/refresh` 只有明确返回 `401` / `403` 时才代表登录态权威失效，可以清本地 access token 并触发全局 auth 变化；服务器重启、Nginx 502/503/504、浏览器 `Failed to fetch` 或 refresh 响应契约异常都属于暂时不可用，不能把已有本地 token 清掉，否则重启窗口会把所有打开页面踢成未登录。
+- 契约：`/api/auth/refresh` 成功响应按共享契约 `RefreshSessionResponse { token }` 解析；测试 mock 不要额外塞 `{ ok: true, token }` 遮住真实恢复路径。
 - 验证：`npm run test -- src/services/apiClient.test.ts src/components/auth/AuthGate.test.tsx -t "explicit refresh opts out|auth gate keeps a valid local token login"`。
 - 关联：`src/services/apiClient.ts`、`src/components/auth/AuthGate.tsx`、`docs/technical/AUTH_RESTORE_AND_RECOMMEND_LOADING_FIX_2026-05-09.md`。

@@ -1131,6 +1149,7 @@
 - 追加处理：generated 私有图片换签 `/api/assets/read-url` 也属于展示层后台请求；推荐页拼图运行态挂载后会立即解析封面图，若换签 401 触发全局鉴权事件，也会表现成“进入拼图作品后瞬间未登录”。资源换签失败只应让当前图片为空，不应清 token、广播 auth 事件或主动 refresh。
 - 追加处理：从推荐页点进公开拼图作品并启动完整运行态后，`startPuzzleRun`、通关自动 `submitPuzzleLeaderboard`、下一关 `advancePuzzleNextLevel` 和重开同样属于当前玩法局部同步；这些请求失败时只应留在拼图错误态，不应清 token 或广播 auth 事件。
 - 追加处理：通关后 `refreshSaveArchives()`、首屏 bootstrap 的个人看板/作品架/浏览历史读写也只是平台投影刷新，失败应显示局部错误，不能充当全局登录态判定。
+- 追加处理：未登录推荐页启动任一公开正式玩法时，`/api/runtime/*` 局内路由必须使用 `RuntimePrincipal`，前端通过 `PlatformEntryFlowShellImpl` 的统一 request options helper 给 start / checkpoint / finish / input / drop / click / restart / time-up / leaderboard / next-level 等动作透传 runtime guest token；公开 runtime detail 读取如跳一跳、敲木鱼必须显式 `skipAuth/skipRefresh`，匿名推荐流不能补读受保护创作详情，否则会在真正开局前打出 `/api/auth/refresh 401`。
 - 验证：`npm run test -- src/services/apiClient.test.ts src/services/assetReadUrlService.test.ts`、`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "home recommendation starts embedded puzzle"`、`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "formal puzzle runtime uses frontend move merge logic and backend leaderboard"`、`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "formal puzzle similar work keeps current run level progression"`。
 - 关联：`src/services/apiClient.ts`、`src/services/assetReadUrlService.ts`、`src/services/puzzle-runtime/puzzleRuntimeClient.ts`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`docs/technical/RECOMMEND_RUNTIME_AUTH_FAILURE_ISOLATION_FIX_2026-05-09.md`。

@@ -1314,6 +1333,14 @@
 - 验证：Jenkins 日志中 `Provision Target` 下的 `Prepare`、`Checkout Provision Files`、`Prepare Provision Tools` 和 `Provision Server` 都应运行在目标 dev / release agent；日志不应出现 `stash 'server-provision-tools'`、目标阶段 `unstash`、`Git 主地址拉取失败...改用备用地址` 或 `https://git.genarrative.world/GenarrativeAI/Genarrative.git`。
 - 关联：`jenkins/Jenkinsfile.production-server-provision`、`scripts/prepare-server-provision-tools.sh`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。

+## Server-Provision 不要无条件下载工具包
+
+- 现象：目标 dev / release 机器已经安装正确版本的 SpacetimeDB 或 `otelcol-contrib`，但 `Prepare Provision Tools` 仍每次下载 release tarball，网络慢或 GitHub 不稳时会把服务器初始化卡在准备阶段。
+- 原因：工具准备阶段如果只按“生成交付包”理解，会忽略它已经运行在目标部署 agent 上这一事实；此时目标机本地的 `/usr/local/bin/otelcol-contrib` 与 `${SPACETIME_ROOT}/bin/current` 就是可信状态源。
+- 处理：`scripts/prepare-server-provision-tools.sh` 必须先检查目标机状态：`otelcol-contrib --version` 命中 `OTELCOL_VERSION` 时复制现有二进制；`spacetimedb-cli --version` 命中 `SPACETIME_EXPECTED_VERSION` 或 `SPACETIME_DOWNLOAD_ROOT` 推导出的版本且 standalone 同时存在时，复制 `${SPACETIME_ROOT}/bin` 并生成 wrapper。只有缺失、不可执行或版本不匹配时，才查 `PROVISION_DOWNLOADS_DIR` 或下载源。
+- 验证：运行 `bash scripts/check-server-provision-tools.sh`；Jenkins 日志应先出现“检查目标机 ...”，已有版本命中时出现“复用目标机已有 ...”，且不出现“下载 ...”。
+- 关联：`scripts/prepare-server-provision-tools.sh`、`jenkins/Jenkinsfile.production-server-provision`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+
 ## 个人任务 scope 不得扩成 work/site/module

 - 现象：个人任务配置为 `work` / `site` / `module` 后进度串桶或静默按 0 处理。
@@ -2163,3 +2190,11 @@
 - 待处理：将跳一跳生成改为后端任务化 / 可轮询真实阶段进度，按背景、返回按钮、图集、切片、持久化、写草稿分阶段落库；统一后端全局生成 deadline、VectorEngine 重试预算、前端等待窗口和失败态回写。超时后再次进入同一 session 应优先恢复正在运行或已完成的任务，不应重复生图。
 - 验证：模拟首张 image2 超长耗时或超时重试时，生成页应显示真实阶段和可恢复状态；前端请求超时不应把最终成功草稿标记为失败；刷新 `/creation/jump-hop/generating?sessionId=<id>` 后应能恢复到后端真实状态；同一 session 重试不得重复生成已完成阶段。
 - 关联：`src/services/jump-hop/jumpHopClient.ts`、`src/services/miniGameDraftGenerationProgress.ts`、`server-rs/crates/api-server/src/jump_hop.rs`、`server-rs/crates/platform-image/src/vector_engine/client.rs`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
+## SpacetimeDB 连接池租约必须有 Drop 兜底，acquire 不允许无界自旋
+
+- 现象：release 上 api-server 周期性出现全量 `spacetime_stage="pool_acquire" elapsed_ms=45000` 业务超时，`/readyz` 503（`reason=spacetime_unhealthy, stage=pool_acquire`），`/healthz` 仍 200，只有重启能恢复，过若干小时复发。
+- 原因：旧 `PooledConnectionLease` 只能显式 `release_connection` 归还；HTTP 请求方在等待 StDB 回包期间断开时 handler future 被取消，permit 自动归还但槽位 `in_use` 永不复位。后续 acquire 在拿到 permit 后进入无界 `loop + yield_now` 扫描空闲槽位，泄漏积累到 pool_size 后整池挂死。
+- 处理：租约持有 `Arc<SpacetimeConnectionPool>` 并实现 `Drop` 统一复位槽位/归还连接；槽位改 `AtomicBool` CAS 抢占，删除自旋循环（持有 permit 必然命中空闲槽位）。任何新的"显式归还"资源在 async 取消语义下都要先想 Drop 兜底。
+- 验证：`cargo test -p spacetime-client --manifest-path server-rs/Cargo.toml --lib`（`dropped_lease_releases_slot_and_permit`、`acquire_times_out_at_pool_acquire_when_pool_is_busy`）。
+- 关联：`server-rs/crates/spacetime-client/src/lib.rs`、`docs/【后端架构】SpacetimeDB连接池租约Drop兜底与取消安全-2026-06-11.md`。
@@ -20,6 +20,7 @@ import type {
  AdminUpsertProfileRechargeProductRequest,
  AdminUpsertProfileRedeemCodeRequest,
  AdminUpsertProfileTaskConfigRequest,
+  AdminUpsertPublicWorkInteractionConfigRequest,
  AdminWorkVisibilityListResponse,
  ApiErrorEnvelope,
  ApiMeta,
@@ -129,16 +130,16 @@ export async function request<T>(
 export function loginAdmin(username: string, password: string) {
  return request<AdminLoginResponse>('/admin/api/login', {
    method: 'POST',
-    body: {username, password},
+    body: { username, password },
  });
 }

 export function getAdminMe(token: string) {
-  return request<AdminMeResponse>('/admin/api/me', {token});
+  return request<AdminMeResponse>('/admin/api/me', { token });
 }

 export function getAdminOverview(token: string) {
-  return request<AdminOverviewResponse>('/admin/api/overview', {token});
+  return request<AdminOverviewResponse>('/admin/api/overview', { token });
 }

 export function getAdminDatabaseTables(token: string) {
@@ -154,7 +155,7 @@ export function getAdminDatabaseTableRows(
 ) {
  return request<AdminDatabaseTableRowsResponse>(
    `/admin/api/database/tables/${encodeURIComponent(tableName)}/rows${buildDatabaseTableRowsQuery(query)}`,
-    {token},
+    { token },
  );
 }

@@ -172,15 +173,14 @@ export function listAdminTrackingEvents(
 ) {
  return request<AdminTrackingEventListResponse>(
    `/admin/api/tracking/events${buildQueryString(query)}`,
-    {token},
+    { token },
  );
 }

-
 export function getAdminCreationEntryConfig(token: string) {
  return request<AdminCreationEntryConfigResponse>(
    '/admin/api/creation-entry/config',
-    {token},
+    { token },
  );
 }

@@ -213,10 +213,25 @@ export function upsertAdminCreationEntryBanners(
  );
 }

+/** 保存公开作品详情页点赞 / 改造能力配置。 */
+export function upsertAdminPublicWorkInteractions(
+  token: string,
+  payload: AdminUpsertPublicWorkInteractionConfigRequest,
+) {
+  return request<AdminCreationEntryConfigResponse>(
+    '/admin/api/creation-entry/config/interactions',
+    {
+      method: 'POST',
+      token,
+      body: payload,
+    },
+  );
+}
+
 export function listAdminWorkVisibility(token: string) {
  return request<AdminWorkVisibilityListResponse>(
    '/admin/api/works/visibility',
-    {token},
+    { token },
  );
 }

@@ -237,7 +252,7 @@ export function updateAdminWorkVisibility(
 export function listProfileRedeemCodes(token: string) {
  return request<ProfileRedeemCodeAdminListResponse>(
    '/admin/api/profile/redeem-codes',
-    {token},
+    { token },
  );
 }

@@ -258,7 +273,7 @@ export function upsertProfileRedeemCode(
 export function listProfileInviteCodes(token: string) {
  return request<ProfileInviteCodeAdminListResponse>(
    '/admin/api/profile/invite-codes',
-    {token},
+    { token },
  );
 }

@@ -293,7 +308,7 @@ export function disableProfileRedeemCode(
 export function listProfileTaskConfigs(token: string) {
  return request<ProfileTaskConfigAdminListResponse>(
    '/admin/api/profile/tasks',
-    {token},
+    { token },
  );
 }

@@ -325,7 +340,7 @@ export function disableProfileTaskConfig(
 export function listProfileRechargeProducts(token: string) {
  return request<ProfileRechargeProductConfigAdminListResponse>(
    '/admin/api/profile/recharge-products',
-    {token},
+    { token },
  );
 }

@@ -414,13 +429,13 @@ function buildAdminApiError(
 ) {
  const envelope = isRecord(payload) ? (payload as ApiErrorEnvelope) : null;
  const errorPayload = envelope?.error;
-  const details = isRecord(errorPayload?.details)
-    ? errorPayload.details
-    : null;
+  const details = isRecord(errorPayload?.details) ? errorPayload.details : null;
  const detailsMessage =
    typeof details?.message === 'string' ? details.message.trim() : '';
  const payloadMessage =
-    typeof errorPayload?.message === 'string' ? errorPayload.message.trim() : '';
+    typeof errorPayload?.message === 'string'
+      ? errorPayload.message.trim()
+      : '';
  const topLevelMessage =
    typeof envelope?.message === 'string' ? envelope.message.trim() : '';
  const message =
@@ -107,12 +107,7 @@ export interface AdminDebugHeaderInput {
  value: string;
 }

-export type AdminDebugHttpMethod =
-  | 'GET'
-  | 'POST'
-  | 'PUT'
-  | 'PATCH'
-  | 'DELETE';
+export type AdminDebugHttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';

 export interface AdminDebugHttpRequest {
  method: AdminDebugHttpMethod;
@@ -143,11 +138,11 @@ export interface AdminTrackingEventListQuery {
  limit?: number;
 }

-
 /** 后台创作入口配置响应，同时包含模板入口和独立公告配置。 */
 export interface AdminCreationEntryConfigResponse {
  entries: AdminCreationEntryTypeConfigPayload[];
  eventBanners: AdminCreationEntryEventBannerPayload[];
+  publicWorkInteractions: PublicWorkInteractionConfigPayload[];
 }

 /** 后台创作入口公告位配置项；旧结构化 banner 字段仅保留兼容。 */
@@ -201,6 +196,20 @@ export interface AdminUpsertCreationEntryEventBannersRequest {
  eventBannersJson: string;
 }

+/** 后台公开作品详情页互动能力配置项。 */
+export interface PublicWorkInteractionConfigPayload {
+  sourceType: string;
+  likeEnabled: boolean;
+  remixEnabled: boolean;
+  likeDisabledMessage: string;
+  remixDisabledMessage: string;
+}
+
+/** 后台保存公开作品点赞 / 改造能力配置请求体。 */
+export interface AdminUpsertPublicWorkInteractionConfigRequest {
+  publicWorkInteractions: PublicWorkInteractionConfigPayload[];
+}
+
 /** 后台统一创作工作台契约表单的传输结构。 */
 export interface UnifiedCreationSpecPayload {
  playId: string;
@@ -1,19 +1,26 @@
 /* @vitest-environment jsdom */

-import {fireEvent, render, screen, waitFor, within} from '@testing-library/react';
+import {
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+  within,
+} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
-import {beforeEach, expect, test, vi} from 'vitest';
+import { beforeEach, expect, test, vi } from 'vitest';

 import {
  getAdminCreationEntryConfig,
  upsertAdminCreationEntryBanners,
  upsertAdminCreationEntryConfig,
+  upsertAdminPublicWorkInteractions,
 } from '../api/adminApiClient';
 import type {
  AdminCreationEntryConfigResponse,
  UnifiedCreationSpecPayload,
 } from '../api/adminApiTypes';
-import {AdminCreationEntrySwitchPage} from './AdminCreationEntrySwitchPage';
+import { AdminCreationEntrySwitchPage } from './AdminCreationEntrySwitchPage';

 vi.mock('../api/adminApiClient', () => ({
  formatAdminApiError: vi.fn((error: unknown) =>
@@ -23,6 +30,7 @@ vi.mock('../api/adminApiClient', () => ({
  isAdminApiError: vi.fn(() => false),
  upsertAdminCreationEntryBanners: vi.fn(),
  upsertAdminCreationEntryConfig: vi.fn(),
+  upsertAdminPublicWorkInteractions: vi.fn(),
 }));

 const puzzleSpec: UnifiedCreationSpecPayload = {
@@ -55,6 +63,15 @@ const configResponse: AdminCreationEntryConfigResponse = {
      htmlCode: '<section>后台公告</section>',
    },
  ],
+  publicWorkInteractions: [
+    {
+      sourceType: 'puzzle',
+      likeEnabled: true,
+      remixEnabled: true,
+      likeDisabledMessage: '拼图点赞暂不可用。',
+      remixDisabledMessage: '拼图作品改造暂不可用。',
+    },
+  ],
  entries: [
    {
      id: 'puzzle',
@@ -79,16 +96,24 @@ beforeEach(() => {
  vi.mocked(getAdminCreationEntryConfig).mockResolvedValue(configResponse);
  vi.mocked(upsertAdminCreationEntryBanners).mockResolvedValue(configResponse);
  vi.mocked(upsertAdminCreationEntryConfig).mockResolvedValue(configResponse);
+  vi.mocked(upsertAdminPublicWorkInteractions).mockResolvedValue(
+    configResponse,
+  );
 });

 test('创作入口后台展示并保存统一创作契约', async () => {
  const user = userEvent.setup();
-  const {container} = render(
-    <AdminCreationEntrySwitchPage token="admin-token" onUnauthorized={vi.fn()} />,
+  const { container } = render(
+    <AdminCreationEntrySwitchPage
+      token="admin-token"
+      onUnauthorized={vi.fn()}
+    />,
  );

  await screen.findByText('pictureDescription');
-  expect(container.querySelector('.admin-subsection .admin-info-list')).not.toBeNull();
+  expect(
+    container.querySelector('.admin-subsection .admin-info-list'),
+  ).not.toBeNull();
  expect(
    container.querySelector('.admin-subsection .admin-info-list')?.textContent,
  ).toContain('拼图');
@@ -97,22 +122,22 @@ test('创作入口后台展示并保存统一创作契约', async () => {
  expect(screen.queryByLabelText('契约 JSON')).toBeNull();
  expect(screen.queryByText('puzzle-generating')).toBeNull();

-  await user.click(screen.getByRole('button', {name: '修改契约'}));
-  const dialog = screen.getByRole('dialog', {name: '统一创作契约'});
+  await user.click(screen.getByRole('button', { name: '修改契约' }));
+  const dialog = screen.getByRole('dialog', { name: '统一创作契约' });
  expect(within(dialog).queryByLabelText('玩法 ID')).toBeNull();
  expect(within(dialog).queryByLabelText('工作台阶段')).toBeNull();
  expect(within(dialog).queryByLabelText('生成阶段')).toBeNull();
  expect(within(dialog).queryByLabelText('结果阶段')).toBeNull();
  fireEvent.change(within(dialog).getByLabelText('泥点消耗'), {
-    target: {value: '12'},
+    target: { value: '12' },
  });
-  await user.click(within(dialog).getByRole('button', {name: '应用修改'}));
+  await user.click(within(dialog).getByRole('button', { name: '应用修改' }));

-  expect(screen.queryByRole('dialog', {name: '统一创作契约'})).toBeNull();
+  expect(screen.queryByRole('dialog', { name: '统一创作契约' })).toBeNull();
  expect(screen.getByText('12泥点数')).toBeTruthy();

-  await user.click(screen.getByRole('button', {name: '保存入库'}));
-  await user.click(screen.getByRole('button', {name: '确认'}));
+  await user.click(screen.getByRole('button', { name: '保存入库' }));
+  await user.click(screen.getByRole('button', { name: '确认' }));

  await waitFor(() => {
    expect(upsertAdminCreationEntryConfig).toHaveBeenCalledWith(
@@ -150,9 +175,11 @@ test('创作入口后台拒绝 playId 不一致的统一创作契约', async ()
  );

  await screen.findByText('pictureDescription');
-  await user.click(screen.getByRole('button', {name: '保存入库'}));
+  await user.click(screen.getByRole('button', { name: '保存入库' }));

-  expect(await screen.findByText('统一创作契约 playId 必须与入口 ID 一致')).toBeTruthy();
+  expect(
+    await screen.findByText('统一创作契约 playId 必须与入口 ID 一致'),
+  ).toBeTruthy();
  expect(upsertAdminCreationEntryConfig).not.toHaveBeenCalled();
 });

@@ -166,23 +193,25 @@ test('创作入口后台用表单保存公告配置', async () => {
    />,
  );

-  expect(await screen.findAllByRole('heading', {name: '创作入口公告'})).toHaveLength(2);
+  expect(
+    await screen.findAllByRole('heading', { name: '创作入口公告' }),
+  ).toHaveLength(2);
  expect(screen.queryByLabelText('公告代码 JSON')).toBeNull();
  fireEvent.change(await screen.findByLabelText('公告 1 标题'), {
-    target: {value: '周末创作赛'},
+    target: { value: '周末创作赛' },
  });
  fireEvent.change(screen.getByLabelText('公告 1 HTML'), {
-    target: {value: '<section>新的入口公告</section>'},
+    target: { value: '<section>新的入口公告</section>' },
  });
-  await user.click(screen.getByRole('button', {name: '新增公告'}));
+  await user.click(screen.getByRole('button', { name: '新增公告' }));
  fireEvent.change(screen.getByLabelText('公告 2 标题'), {
-    target: {value: '第二条公告'},
+    target: { value: '第二条公告' },
  });
  fireEvent.change(screen.getByLabelText('公告 2 HTML'), {
-    target: {value: '<section>轮播第二条</section>'},
+    target: { value: '<section>轮播第二条</section>' },
  });
-  await user.click(screen.getByRole('button', {name: '保存公告'}));
-  await user.click(screen.getByRole('button', {name: '确认'}));
+  await user.click(screen.getByRole('button', { name: '保存公告' }));
+  await user.click(screen.getByRole('button', { name: '确认' }));

  await waitFor(() => {
    expect(upsertAdminCreationEntryBanners).toHaveBeenCalled();
@@ -206,6 +235,42 @@ test('创作入口后台用表单保存公告配置', async () => {
  );
 });

+test('创作入口后台用表单保存作品互动配置', async () => {
+  const user = userEvent.setup();
+  render(
+    <AdminCreationEntrySwitchPage
+      token="admin-token"
+      onUnauthorized={vi.fn()}
+    />,
+  );
+
+  await screen.findByText('作品互动');
+  const likeToggle = screen.getAllByRole('checkbox')[0]!;
+  await user.click(likeToggle);
+  fireEvent.change(screen.getByLabelText('拼图 / puzzle 点赞关闭提示'), {
+    target: { value: '拼图点赞维护中。' },
+  });
+  await user.click(screen.getByRole('button', { name: '保存作品互动' }));
+  await user.click(screen.getByRole('button', { name: '确认' }));
+
+  await waitFor(() => {
+    expect(upsertAdminPublicWorkInteractions).toHaveBeenCalledWith(
+      'admin-token',
+      {
+        publicWorkInteractions: [
+          {
+            sourceType: 'puzzle',
+            likeEnabled: false,
+            remixEnabled: true,
+            likeDisabledMessage: '拼图点赞维护中。',
+            remixDisabledMessage: '拼图作品改造暂不可用。',
+          },
+        ],
+      },
+    );
+  });
+});
+
 test('创作入口后台把旧结构化公告回显成 HTML 表单', async () => {
  vi.mocked(getAdminCreationEntryConfig).mockResolvedValueOnce({
    ...configResponse,
@@ -251,12 +316,12 @@ test('创作入口后台拒绝空公告表单', async () => {
  );

  fireEvent.change(await screen.findByLabelText('公告 1 标题'), {
-    target: {value: ''},
+    target: { value: '' },
  });
  fireEvent.change(screen.getByLabelText('公告 1 HTML'), {
-    target: {value: ''},
+    target: { value: '' },
  });
-  await user.click(screen.getByRole('button', {name: '保存公告'}));
+  await user.click(screen.getByRole('button', { name: '保存公告' }));

  expect(await screen.findByText('公告 1 标题和 HTML 都不能为空')).toBeTruthy();
  expect(upsertAdminCreationEntryBanners).not.toHaveBeenCalled();
@@ -0,0 +1,20 @@
+[Unit]
+Description=Genarrative Production Health Patrol
+After=network-online.target genarrative-api.service spacetimedb.service nginx.service
+Wants=network-online.target
+ConditionPathExists=/opt/genarrative/current/scripts/ops/production-health-patrol.mjs
+
+[Service]
+Type=oneshot
+User=root
+Group=root
+WorkingDirectory=/opt/genarrative/current
+EnvironmentFile=-/etc/genarrative/health-patrol.env
+ExecStart=/usr/bin/node /opt/genarrative/current/scripts/ops/production-health-patrol.mjs --status-file /var/lib/genarrative/health-patrol/status.json
+TimeoutStartSec=30
+
+# 巡检只读 systemd、HTTP 和 journal；只允许写入自己的最近一次状态文件。
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=full
+ReadWritePaths=/var/lib/genarrative/health-patrol
@@ -0,0 +1,13 @@
+[Unit]
+Description=Run Genarrative Production Health Patrol
+
+[Timer]
+OnBootSec=2min
+OnCalendar=*-*-* *:0/5:00
+Persistent=true
+RandomizedDelaySec=30
+AccuracySec=30s
+Unit=genarrative-health-patrol.service
+
+[Install]
+WantedBy=timers.target
@@ -21,6 +21,8 @@

 微信小程序虚拟支付接入、`wechat_mp_virtual` 渠道、`wx.requestVirtualPayment` 承接页和后端签名配置见 [【技术方案】微信虚拟支付接入-2026-05-26.md](./%E3%80%90%E6%8A%80%E6%9C%AF%E6%96%B9%E6%A1%88%E3%80%91%E5%BE%AE%E4%BF%A1%E8%99%9A%E6%8B%9F%E6%94%AF%E4%BB%98%E6%8E%A5%E5%85%A5-2026-05-26.md)。

+本地通过 SSH alias 管理多台服务器、查看硬件 / systemd / HTTP 健康状态并执行受控服务启停的 egui 桌面工具见 [【开发运维】本地SSH服务器管理面板技术方案-2026-06-11.md](./technical/【开发运维】本地SSH服务器管理面板技术方案-2026-06-11.md)。
+
 生产部署切换到 systemd + Nginx + SpacetimeDB 自托管的总方案见 [PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md](./technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md)，该文档也是当前生产 Jenkinsfile 的唯一入口。SpacetimeDB 表结构变更、自动迁移边界和保留旧数据的分阶段迁移流程见 [SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md](./technical/SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md)；private 表迁移 JSON 导入导出、HTTP 413 分片导入和旧数据库迁移流水线经验见 [SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md](./technical/SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md) 与 [JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md](./technical/JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md)；后台管理独立前端工程技术方案见 [ADMIN_WEB_CONSOLE_TECHNICAL_SOLUTION_2026-04-30.md](./technical/ADMIN_WEB_CONSOLE_TECHNICAL_SOLUTION_2026-04-30.md)。

 SpacetimeDB 表结构变更、自动迁移边界和保留旧数据的分阶段迁移流程见 [SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md](./technical/SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md)。
@@ -0,0 +1,82 @@
+# 本地 SSH 服务器管理面板技术方案
+
+日期：`2026-06-11`
+
+## 背景
+
+release / dev 等服务器的日常巡检已经有 `genarrative-health-patrol.timer`、`/readyz`、`/healthz`、SpacetimeDB `/v1/ping` 和 systemd 状态文件，但开发者本地仍需要在多个 SSH alias 之间切换命令。服务器管理面板用于把这些只读巡检和少量 systemd 服务操作收敛到一个本地桌面入口。
+
+## 范围
+
+- 使用 Rust `egui` / `eframe` 实现本地桌面面板，不接入线上 Web 后台，不暴露公网端口。
+- 从本机 `~/.ssh/config` 的 `Host` alias 发现服务器；只展示不含通配符的 alias。
+- 支持多个服务器，左侧服务器侧边栏可收起。
+- 主面板展示硬件状态、服务状态、HTTP 健康探测和生产健康巡检状态。
+- 支持对允许的 systemd unit 执行启动、关闭、重启。
+
+## 命令入口
+
+```bash
+npm run server-manager:panel
+```
+
+等价于：
+
+```bash
+cargo run -p server-manager-panel --manifest-path server-rs/Cargo.toml
+```
+
+面板启动时会自动查找本机中文字体并注入 egui 字体集，优先使用 `Noto Sans CJK SC`，其次使用文泉驿 / Droid fallback。若某台开发机字体路径特殊，可用 `GENARRATIVE_SERVER_PANEL_CJK_FONT=/path/to/font.ttc|index` 指定；普通 `.ttf` 可省略 `|index`。
+
+## SSH 约定
+
+本地 `~/.ssh/config` 中需要存在类似：
+
+```sshconfig
+Host dev
+  HostName 10.2.0.10
+  User genarrative
+
+Host release
+  HostName genarrative.world
+  User genarrative
+```
+
+面板通过 `ssh <alias> sh -s` 执行远端只读巡检脚本。服务操作使用：
+
+```bash
+sudo -n systemctl <start|stop|restart> <unit>
+```
+
+若 SSH 用户是 root，则直接执行 `systemctl`。非 root 用户需要提前配置只允许目标 unit 的无密码 sudo；否则面板会显示 sudo 权限错误，不会弹出交互密码输入。
+
+## 健康检查内容
+
+只读巡检覆盖：
+
+- 主机名、内核、运行时长、CPU 核数 / 型号、load average。
+- 内存 / swap 使用情况。
+- `/`、`/var`、`/opt`、`/stdb`、`/data` 中存在路径的磁盘使用率。
+- `genarrative-api.service`、`spacetimedb.service`、`nginx.service`、`genarrative-health-patrol.timer`、`genarrative-database-backup.timer` 的 systemd 状态。
+- `http://127.0.0.1:8082/healthz`、`/readyz`、`http://127.0.0.1:3101/v1/ping` 和代表性公开接口。
+- `/var/lib/genarrative/health-patrol/status.json` 的最近巡检状态。
+- 若服务器安装了 `sensors`，附带温度 / 风扇等硬件传感器摘要。
+
+## 服务操作安全边界
+
+面板只允许 `start`、`stop`、`restart` 三种动作，并且 unit 名必须匹配安全字符集：
+
+```text
+A-Z a-z 0-9 . _ - @ :
+```
+
+服务操作会先出现确认弹窗，避免误点。第一版默认列出 Genarrative 生产相关 unit，并提供“其他 unit”输入框；该输入框仍只会执行 `systemctl` 的三种受控动作，不提供任意命令执行入口。
+
+## 状态判定
+
+- service / HTTP 探测失败：`CRITICAL`。
+- 磁盘使用率 `>= 95%`：`CRITICAL`，`>= 85%`：`WARNING`。
+- 内存使用率 `>= 95%`：`CRITICAL`，`>= 85%`：`WARNING`。
+- 生产健康巡检状态沿用 `OK / WARNING / CRITICAL`。
+
+面板状态只是本地巡检视图，最终运维事实仍以服务器上的 systemd、journal、Nginx 日志、`production-health-patrol.mjs` 输出和现有部署文档为准。
@@ -0,0 +1,40 @@
+# SpacetimeDB 连接池租约 Drop 兜底与取消安全
+
+- 日期：2026-06-11
+- 关联故障：release 环境 api-server 周期性全量 `spacetime_stage="pool_acquire" elapsed_ms=45000` 超时，`/readyz` 503（`reason=spacetime_unhealthy, stage=pool_acquire`），重启后临时恢复。
+- 涉及代码：`server-rs/crates/spacetime-client/src/lib.rs`
+
+## 故障根因
+
+修复前的连接池存在两个叠加缺陷：
+
+1. **租约没有 Drop 兜底**。`PooledConnectionLease` 只能通过显式 `release_connection` 归还。当 HTTP 请求方在等待 StDB 回包期间断开（前端超时、用户刷新、Nginx 截断），axum/hyper 会直接丢弃 handler future，租约被 Drop：permit 因 `OwnedSemaphorePermit` 自动归还，但槽位的 `in_use` 标记永远不会复位。
+2. **acquire 在槽位泄漏后永久空转**。后续请求拿到 permit 后进入 `loop { 扫描槽位; yield_now }`，找不到空闲槽位就无限自旋，且这段自旋不受 `procedure_timeout` 约束，自旋期间 permit 不归还。
+
+叠加效果：StDB 一旦变慢（请求占用连接接近 45 秒），客户端取消请求的概率大增，每次取消泄漏一个槽位并连带吞掉一个 permit；泄漏数量达到 `pool_size`（release 为 8）后，所有业务请求与健康检查全部在 `pool_acquire` 阶段 45 秒超时，服务表现为"连不上 StDB"，只有重启能恢复。
+
+## 本地复现
+
+不需要真实 SpacetimeDB，单元测试即可复现机制（位于 `spacetime-client` tests 模块）：
+
+- 修复前：将一个槽位置为 `in_use=true` 后调用 `acquire_connection_with_timeout(200ms)`，acquire 在 5 秒守护窗口内不返回（永久自旋），测试红。
+- `dropped_lease_releases_slot_and_permit`：模拟"请求被取消、租约未经 release 直接 Drop"，断言槽位与 permit 都被复位归还。
+- `acquire_times_out_at_pool_acquire_when_pool_is_busy`：池内 permit 全部被占用时，acquire 必须在超时窗口内返回 `PoolAcquire + Timeout`，不允许无限等待。
+
+## 修复方案
+
+1. `PooledConnectionSlot` 改为 `in_use: AtomicBool + connection: Mutex<Option<PooledConnection>>`，槽位占用标记不再依赖异步锁。
+2. `PooledConnectionLease` 持有 `Arc<SpacetimeConnectionPool>` 并实现 `Drop`：无论显式归还还是 future 被取消，统一在 Drop 中复位槽位、按 broken 状态决定连接是否回池，permit 随后自动归还。Drop 体先复位 `in_use` 再释放 permit（字段在 Drop 体之后析构），保证新请求拿到 permit 时必有空闲槽位。
+3. acquire 改为 CAS 抢占槽位：持有 permit 即保证并发持有者不超过 `pool_size`，扫描一轮必然命中空闲槽位，彻底删除自旋循环；建连失败直接返回错误，槽位由租约 Drop 复位。
+4. `release_connection` 退化为 `drop(lease)`，显式与隐式归还共用同一条兜底路径。
+
+## 验收
+
+- `cargo test -p spacetime-client --manifest-path server-rs/Cargo.toml --lib`（35 通过，含上述新测试）
+- `cargo test -p api-server --manifest-path server-rs/Cargo.toml readyz`（2 通过）
+- `cargo check -p api-server --manifest-path server-rs/Cargo.toml`
+
+## 运维提示
+
+- 此修复解决的是"取消导致的永久泄漏"。StDB 真慢时仍会出现成批 45 秒超时（连接被在途请求合法占用），那是容量/上游问题，应结合 `GENARRATIVE_SPACETIME_POOL_SIZE` 与 StDB 负载排查，不要再怀疑池泄漏。
+- 健康检查 `/readyz` 在池被在途请求占满时仍可能短暂 503（stage=pool_acquire），恢复后自动转好，无需重启。
@@ -1,6 +1,6 @@
 # server-rs 与 SpacetimeDB 数据契约

-更新时间：`2026-05-15`
+更新时间：`2026-06-10`

 ## 后端主线

@@ -54,13 +54,13 @@ npm run check:server-rs-ddd
 路由树由 `server-rs/crates/api-server/src/app.rs` 统一构造。当前主要分组：

 - 健康检查：`GET /healthz`。
- 后台管理：`/admin/api/*`，包括登录、概览、HTTP debug、埋点、表查询、创作入口开关、作品可见性、兑换码、邀请码、任务配置和充值商品配置。
+- 后台管理：`/admin/api/*`，包括登录、概览、HTTP debug、埋点、表查询、创作入口开关、作品互动配置、作品可见性、兑换码、邀请码、任务配置和充值商品配置。
 - 认证与账号：`/api/auth/*`、`/api/profile/me`，包括短信、密码、微信、refresh session、多端会话和登出。
 - 个人中心：`/api/profile/*`，包括钱包流水、任务、领奖、充值、反馈、邀请和兑换等账号侧能力。
 - 平台基础能力：`/api/llm/*`、`/api/speech/volcengine/*`，只保留通用 LLM 和语音代理。
 - 资产基础能力：`/api/assets/direct-upload-tickets`、`/api/assets/sts-upload-credentials`、`/api/assets/objects/*`、`/api/assets/read-*`，负责直传、确认、绑定和读取。
 - 创作 / 游玩支撑能力：`/api/creation-entry/config`、`/api/ai/tasks*`、`/api/runtime/chat/*`、`/api/runtime/settings`、`/api/runtime/save/snapshot`、`/api/profile/browse-history`、`/api/profile/save-archives*`、`/api/profile/play-stats`、`/api/assets/history`、`/api/assets/character-visual/*`、`/api/assets/character-animation/*`、`/api/assets/character-workflow-cache*`、`/api/assets/hyper3d/*`、`/api/runtime/custom-world/asset-studio/*`。
- 后台入口配置：`/admin/api/creation-entry/config` 和 `/admin/api/creation-entry/config/banners`。
+- 后台入口配置：`/admin/api/creation-entry/config`、`/admin/api/creation-entry/config/banners` 和 `/admin/api/creation-entry/config/interactions`。
 - 自定义世界 / RPG：`/api/runtime/custom-world*`、`/api/story/*`、`/api/runtime/chat/*`。
 - 拼图：`/api/runtime/puzzle/*`。
 - 抓大鹅 Match3D：`/api/creation/match3d/*`、`/api/runtime/match3d/*`。
@@ -125,11 +125,14 @@ npm run check:server-rs-ddd

 `/api/runtime/puzzle/runs*` 当前接受 `RuntimePrincipal`，可同时识别登录用户 Bearer 和 runtime guest token。推荐页嵌入运行态的正式开局、交换、拖拽、下一关、暂停、道具与排行榜请求，应由前端在登录态下继续携带账号 access token；匿名游客仅在确认为未登录时走 runtime guest token。不要再把拼图 runtime 当成只认普通 Bearer 的纯账号接口。

+公开正式 runtime 的启动与局内同步动作统一接受 `RuntimePrincipal`，包括拼图、拼消消、跳一跳、敲木鱼、抓大鹅 Match3D、方洞挑战、视觉小说、大鱼吃小鱼和汪汪声浪。登录用户仍使用账号 Bearer；未登录推荐页或公开运行态使用 Runtime Guest Token，后端以 `principal.subject()` 作为本局 owner / player subject，并用 `WorkPlayTrackingDraft::runtime_principal(...)` 记录游玩。创作、个人作品、删除、发布、Remix、点赞等账号或所有权动作不得改成 runtime guest 鉴权。
+
 抓大鹅 Match3D `api-server` 内部拆分：

 - `server-rs/crates/api-server/src/modules/match3d.rs` 继续负责路由装配和 body limit；对外 handler 名称保持不变。
 - `server-rs/crates/api-server/src/match3d.rs` 只作为聚合入口，保留共享 import / 常量 / 内部类型、模块声明和 handler re-export。
 - `server-rs/crates/api-server/src/match3d/handlers.rs` 承接 Axum handler，负责 extract、鉴权上下文、调用 SpacetimeDB facade / 编排 helper，并返回 HTTP 响应。
+- `/api/runtime/match3d/works/{profile_id}/runs`、`/api/runtime/match3d/runs/{run_id}`、`/click`、`/stop`、`/restart` 与 `/time-up` 属于正式运行态局部请求，必须接受 `RuntimePrincipal`；登录用户使用账号 Bearer，推荐页匿名游客使用 runtime guest token，后端以 principal subject 作为本局 owner，不得退回只认普通 Bearer 的路由。
 - `server-rs/crates/api-server/src/match3d/draft.rs` 承接 Agent session、草稿编译、题材 / 难度 / 物品计划和草稿持久化编排。
 - `server-rs/crates/api-server/src/match3d/works.rs` 承接作品 CRUD、封面 / 背景 / 容器资产生成入口、发布 / Remix / 点赞 / 游玩记录和作品级 helper。
 - `server-rs/crates/api-server/src/match3d/item_assets.rs` 承接物品生成批次编排、append / replace / delete / sort / merge、计费外层和草稿素材映射；sheet prompt、绿幕 / 近白底透明化、切图和切片持久化复用 `generated_asset_sheets` 通用模块。
@@ -187,6 +190,10 @@ npm run check:server-rs-ddd
 1. `creation_entry_type_config.unified_creation_spec_json` 内的 `mudPointCost` 是玩法新建草稿初始生成的泥点成本真相源，同时供入口卡展示和前端余额前置校验使用；旧契约缺失时允许按代码默认成本兜底。
 2. `api-server` 执行拼图首图生成、抓大鹅完整草稿生成和汪汪声浪初始三图生成时，必须通过 `GET /api/creation-entry/config` 同源配置解析对应玩法成本后再调用钱包扣费 procedure，不得继续使用前端或后端硬编码常量作为实际扣费真相。
 3. 结果页单图重生成、发布、道具使用和其它独立资产操作仍按各自业务操作成本执行；不要把初始草稿成本误套到这些单次操作上。
+4. 资产操作的预扣费必须 fail-closed：钱包或 SpacetimeDB 预扣费不可达、超时或返回业务错误时，`api-server` 直接返回错误，不允许继续调用图片、音频、GLB 等外部生成 provider。
+5. 需要支持 HTTP retry 的计费 ledger id 必须包含当前请求的 `request_id`；前端 `fetchWithApiAuth` 同一次业务请求的静默刷新重试复用同一个 `x-request-id`，后端不得再使用 prompt 指纹或随机 asset id 作为扣费幂等键。
+6. 外部生成已预扣费但后续失败时必须先同步调用钱包退款；若 SpacetimeDB 暂不可用，退款请求写入 `wallet-refund-outbox` 本地文件并由后台 worker 重放。默认启用，配置项为 `GENARRATIVE_WALLET_REFUND_OUTBOX_ENABLED`、`GENARRATIVE_WALLET_REFUND_OUTBOX_DIR`、`GENARRATIVE_WALLET_REFUND_OUTBOX_BATCH_SIZE`、`GENARRATIVE_WALLET_REFUND_OUTBOX_FLUSH_INTERVAL_MS` 和 `GENARRATIVE_WALLET_REFUND_OUTBOX_MAX_BYTES`。outbox 文件按 refund ledger id 幂等落盘；成功重放后删除，坏文件隔离为 `corrupt-*`。
+7. 拼图首图后台生成的跨实例互斥锁必须落在 SpacetimeDB `puzzle_background_compile_task` 表，claim id 由 `task_id + request_id` 构成，释放时必须校验 claim id，避免旧后台任务释放新请求抢到的租约。

 ## 外部服务与资产

@@ -356,8 +363,8 @@ npm run check:server-rs-ddd

 - Rust 结构体：`CreationEntryConfig`
 - 源码：`server-rs/crates/spacetime-module/src/runtime/creation_entry_config.rs`
- 字段：`config_id`、`start_title`、`start_description`、`start_idle_badge`、`start_busy_badge`、`modal_title`、`modal_description`、`updated_at`、`event_title`、`event_description`、`event_cover_image_src`、`event_prize_pool_mud_points`、`event_starts_at_text`、`event_ends_at_text`、`event_banners_json`。
- 迁移兼容：旧迁移包缺少活动横幅字段时，由 `migration.rs` 写入 `None` / `58000` 默认值；旧库缺少 `event_banners_json` 时写入 `None`，运行态读取层再按 `module-runtime` 默认公告数组归一，不覆盖后台已保存配置，也不把旧结构化 `eventBanner` 升格为前端优先数组。HTTP 响应同时返回 `eventBanners` 数组和旧 `eventBanner` 单条兼容字段，前端优先消费数组；后台新配置主格式为 HTML 公告字符串数组或 `{title, htmlCode}` 对象数组，旧结构化 banner 字段仅保留兼容。默认公告背景和旧结构化默认 `coverImageSrc` 必须引用 `public/` 下真实存在的静态资源，当前为 `/creation-type-references/puzzle.webp`。
+- 字段：`config_id`、`start_title`、`start_description`、`start_idle_badge`、`start_busy_badge`、`modal_title`、`modal_description`、`updated_at`、`event_title`、`event_description`、`event_cover_image_src`、`event_prize_pool_mud_points`、`event_starts_at_text`、`event_ends_at_text`、`event_banners_json`、`public_work_interactions_json`。
+- 迁移兼容：旧迁移包缺少活动横幅字段时，由 `migration.rs` 写入 `None` / `58000` 默认值；旧库缺少 `event_banners_json` 时写入 `None`，运行态读取层再按 `module-runtime` 默认公告数组归一，不覆盖后台已保存配置，也不把旧结构化 `eventBanner` 升格为前端优先数组。旧库缺少 `public_work_interactions_json` 时写入 `None`，读取层按 `module-runtime` 默认作品互动矩阵补齐 `publicWorkInteractions`，不覆盖后台已保存开关。HTTP 响应同时返回 `eventBanners` 数组、旧 `eventBanner` 单条兼容字段和 `publicWorkInteractions` 互动矩阵；前端优先消费数组与矩阵。后台新公告配置主格式为 HTML 公告字符串数组或 `{title, htmlCode}` 对象数组，旧结构化 banner 字段仅保留兼容。默认公告背景和旧结构化默认 `coverImageSrc` 必须引用 `public/` 下真实存在的静态资源，当前为 `/creation-type-references/puzzle.webp`。

 ### `creation_entry_type_config`

@@ -637,6 +644,12 @@ npm run check:server-rs-ddd
 - Rust 结构体：`PuzzleAgentSessionRow`
 - 源码：`server-rs/crates/spacetime-module/src/puzzle.rs`

+### `puzzle_background_compile_task`
+
+- Rust 结构体：`PuzzleBackgroundCompileTaskRow`
+- 源码：`server-rs/crates/spacetime-module/src/puzzle.rs`
+- 说明：拼图首图后台生成的跨 api-server 实例互斥 claim 表，只保存活动任务租约，不表达最终生成结果；`task_id` 为主键，`claim_id` 用于释放时防止误删新租约，租约超时时间为 30 分钟。
+
 ### `puzzle_event`

 - Rust 结构体：`PuzzleEvent`
@@ -749,8 +762,8 @@ npm run check:server-rs-ddd

 跨玩法公开作品列表 / 详情主读模型是 `public_work_gallery_entry` 与 `public_work_detail_entry`。拼图、自定义世界等旧玩法公开列表 HTTP 路由保留原响应 shape，由 BFF mapper 从统一 public cache 映射回当前 DTO；旧 `*_gallery_card_view` / `*_gallery_view` / `custom_world_gallery_entry` 继续作为 source view 和兼容缓存。各玩法的个人作品列表、详情、发布、点赞、游玩记录、Remix 和其它需要鉴权或写入副作用的路径继续走 procedure / reducer；不要为了公开列表性能把这些 owner-specific 或 mutation 语义混进 public view。

-`GET /api/creation-entry/config` 和入口熔断优先从订阅 cache 读取创作入口配置；cache 缺失时使用最近一次成功读取的内存快照，再兜底调用 `get_creation_entry_config` procedure 完成空库种子或旧库兼容。
-入口配置快照包含 start card、类型弹窗、公告位兼容字段和入口类型列表；入口类型列表新增 `category_id`、`category_label`、`category_sort_order` 后，后台 upsert、`shared-contracts`、`module-runtime` 和 `spacetime-client` binding 必须同步，旧迁移 JSON 通过 `migration.rs` 默认值兼容。
+`GET /api/creation-entry/config`、入口熔断和公开作品互动熔断优先从订阅 cache 读取创作入口配置；cache 缺失时使用最近一次成功读取的内存快照，再兜底调用 `get_creation_entry_config` procedure 完成空库种子或旧库兼容。
+入口配置快照包含 start card、类型弹窗、公告位兼容字段、入口类型列表和 `publicWorkInteractions` 作品互动矩阵；入口类型列表新增 `category_id`、`category_label`、`category_sort_order` 后，后台 upsert、`shared-contracts`、`module-runtime` 和 `spacetime-client` binding 必须同步，旧迁移 JSON 通过 `migration.rs` 默认值兼容。作品互动矩阵是全局公开作品详情能力配置，不属于单个 `creation_entry_type_config`；后台通过 `/admin/api/creation-entry/config/interactions` 保存，前端据此隐藏或拦截已接入的点赞 / Remix 入口，api-server 同时对已接入后端动作执行 `public_work_interaction_disabled` 熔断。

 RPG 创作入口的配置 ID 是 `rpg`，当前 `visible=true`、`open=true`；历史 `custom-world` 路由仍是 RPG 的工程域与运行态源类型。入口熔断把 `/api/runtime/custom-world*`、`/api/story/*` 和 `/api/runtime/chat/*` 统一映射到 `rpg`，不要新增平行 `airp` 路由或用 `airp` 接管当前文字冒险链路。

@@ -96,6 +96,7 @@ npm run admin-web:typecheck
 ```bash
 npm run check:encoding
 npm run check:spacetime-schema
+npm run check:production-ops
 npm run check:server-rs-ddd
 npm run lint:eslint
 npm run typecheck
@@ -217,7 +218,7 @@ UI 相关修改要重点验证：
 npm run database:backup:oss -- --data-dir /stdb --stop-service spacetimedb.service --restart-service-after genarrative-api.service
 ```

-脚本会将数据目录打包成 `tar.gz`，上传到 `oss://<bucket>/<prefix>/<database>/<database>-<UTC时间>.tar.gz`。生产建议做冷备份：传入 `--stop-service spacetimedb.service`，脚本会在打包前停止服务、打包后恢复服务，再上传 OSS；因 `genarrative-api.service` 依赖 `spacetimedb.service`，生产定时冷备份还必须传入 `--restart-service-after genarrative-api.service`，确保备份后 API 随数据库一起恢复。由于 OSS 上传可能受服务器带宽限制，`Genarrative-Stdb-Module-Publish` 默认使用 `DATABASE_BACKUP_MODE=async`：先在 publish 前用 `--defer-upload` 生成本地冷备份和 `.manifest.json`，随后继续执行 publish；发布脚本退出前会用后台 `node ... --upload-archive <tar.gz>` 上传同一份发布前备份，不等待上传完成。发布脚本在校验 wasm 后、执行 `spacetime publish` 前会等待显式 `SPACETIME_SERVER_URL` 的 `/v1/ping` 就绪，默认最多等待 `60` 秒；如生产机器冷备份恢复 `spacetimedb.service` 较慢，可临时设置 `GENARRATIVE_STDB_PUBLISH_READY_TIMEOUT_SECONDS` 调整等待时间。需要强一致发布闸门时改用 `DATABASE_BACKUP_MODE=sync`（等价脚本参数 `--backup-mode sync`），备份会在 publish 前同步打包并上传，失败会阻断 publish；确认已有其他备份窗口时才使用 `DATABASE_BACKUP_MODE=skip`（兼容脚本参数 `--skip-backup`）。若业务不能接受停机窗口，应先规划 SpacetimeDB 原生快照或主备策略，不要直接在写入中的数据目录上做热拷贝并当作强一致备份。
+脚本会将数据目录打包成 `tar.gz`，上传到 `oss://<bucket>/<prefix>/<database>/<database>-<UTC时间>.tar.gz`。生产建议做冷备份：传入 `--stop-service spacetimedb.service`，脚本会在打包前停止服务、打包后恢复服务，再上传 OSS；因 `genarrative-api.service` 依赖 `spacetimedb.service`，生产定时冷备份还必须传入 `--restart-service-after genarrative-api.service`，确保备份后 API 随数据库一起恢复。`2026-06-10` release 故障就是现场 unit 漏掉该参数，`03:20` 冷备份停止 SpacetimeDB 后 API 被依赖关系一并停止，备份脚本只恢复了 SpacetimeDB，API 直到人工重启前都不可用；后续现场变更、provision 模板和 Jenkins 归档都必须通过 `npm run check:production-ops` 防止回退。由于 OSS 上传可能受服务器带宽限制，`Genarrative-Stdb-Module-Publish` 默认使用 `DATABASE_BACKUP_MODE=async`：先在 publish 前用 `--defer-upload` 生成本地冷备份和 `.manifest.json`，随后继续执行 publish；发布脚本退出前会用后台 `node ... --upload-archive <tar.gz>` 上传同一份发布前备份，不等待上传完成。发布脚本在校验 wasm 后、执行 `spacetime publish` 前会等待显式 `SPACETIME_SERVER_URL` 的 `/v1/ping` 就绪，默认最多等待 `60` 秒；如生产机器冷备份恢复 `spacetimedb.service` 较慢，可临时设置 `GENARRATIVE_STDB_PUBLISH_READY_TIMEOUT_SECONDS` 调整等待时间。需要强一致发布闸门时改用 `DATABASE_BACKUP_MODE=sync`（等价脚本参数 `--backup-mode sync`），备份会在 publish 前同步打包并上传，失败会阻断 publish；确认已有其他备份窗口时才使用 `DATABASE_BACKUP_MODE=skip`（兼容脚本参数 `--skip-backup`）。若业务不能接受停机窗口，应先规划 SpacetimeDB 原生快照或主备策略，不要直接在写入中的数据目录上做热拷贝并当作强一致备份。

 生产环境变量模板在 `deploy/env/api-server.env.example`：

@@ -234,6 +235,17 @@ GENARRATIVE_DATABASE_BACKUP_OSS_ACCESS_KEY_SECRET=

 `GENARRATIVE_DATABASE_BACKUP_OSS_BUCKET` 为空时会回退 `ALIYUN_OSS_BUCKET`；AccessKey 默认复用 `ALIYUN_OSS_ACCESS_KEY_ID` / `ALIYUN_OSS_ACCESS_KEY_SECRET`，也可用 `GENARRATIVE_DATABASE_BACKUP_OSS_ACCESS_KEY_ID` / `GENARRATIVE_DATABASE_BACKUP_OSS_ACCESS_KEY_SECRET` 为备份 bucket 单独配置最小权限账号。`Genarrative-Server-Provision` 会创建 `/var/lib/genarrative/database-backups` 并归属 `genarrative:genarrative`，同时安装并启用 `genarrative-database-backup.timer`。手动检查定时器：`systemctl list-timers genarrative-database-backup.timer`；手动触发一次：`systemctl start genarrative-database-backup.service`。

+冷备份后必须做一次只读验收，不要只看 `genarrative-database-backup.service` 是否成功退出：
+
+```bash
+systemctl is-active spacetimedb.service genarrative-api.service nginx.service
+curl -fsS --max-time 5 http://127.0.0.1:3101/v1/ping
+curl -fsS --max-time 5 http://127.0.0.1:8082/healthz
+curl -fsS --max-time 5 http://127.0.0.1:8082/readyz
+curl -fsS --max-time 5 http://127.0.0.1/api/creation-entry/config >/dev/null
+curl -fsS --max-time 5 http://127.0.0.1/api/runtime/puzzle/gallery >/dev/null
+```
+
 ## 生产运维

 生产部署当前口径：
@@ -244,11 +256,32 @@ Nginx 负责站点和反向代理
 Jenkins 按 web / api / Spacetime module / build / deploy / publish 拆分
 ```

+### 生产健康巡检
+
+`Genarrative-Server-Provision` 会安装并启用 `genarrative-health-patrol.timer`，默认每 5 分钟运行一次 `genarrative-health-patrol.service`。巡检脚本随 API release 归档到 `/opt/genarrative/current/scripts/ops/production-health-patrol.mjs`，只读检查：
+
+- `genarrative-api.service`、`spacetimedb.service`、`nginx.service` 是否 active。
+- API 直连 `/healthz`、`/readyz`。
+- SpacetimeDB 直连 `/v1/ping`。
+- 默认直连 API 端口检查 `/api/creation-entry/config`、`/api/runtime/puzzle/gallery`、`/api/runtime/custom-world-gallery`；如需走 Nginx / 公网域名，在 `/etc/genarrative/health-patrol.env` 配置 `GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL=https://<域名>`。
+- 最近 15 分钟 `genarrative-api.service`、`spacetimedb.service`、`nginx.service` 的 `err..alert` 日志。
+
+巡检输出总状态 `OK / WARNING / CRITICAL`；只有 `CRITICAL` 默认让 systemd service 失败，`WARNING` 只写日志和状态文件，避免历史日志噪声把 timer 长期打成失败。最近一次结果写入 `/var/lib/genarrative/health-patrol/status.json`。手动执行：
+
+```bash
+systemctl start genarrative-health-patrol.service
+systemctl status genarrative-health-patrol.service --no-pager
+journalctl -u genarrative-health-patrol.service -n 80 --no-pager
+cat /var/lib/genarrative/health-patrol/status.json
+```
+
+如需接外部告警，可在 `/etc/genarrative/health-patrol.env` 配置 `GENARRATIVE_HEALTH_PATROL_WEBHOOK_URL`；脚本只会在 `WARNING` 或 `CRITICAL` 时向该 webhook 发送 JSON。未配置 webhook 时，告警来源是 systemd 失败状态、journal 和状态文件。
+
 `Genarrative-Web-Build` 的主站构建失败若出现 Rollup 报错 `"xxx" is not exported by "src/services/publicWorkCode.ts"`，优先按前端公开作品号工具缺失处理，而不是排查 Jenkins 节点环境。修复时要让 `publicWorkCode.ts` 的 `build<Play>PublicWorkCode` 与 `isSame<Play>PublicWorkCode` 成对导出，并补 `src/services/publicWorkCode.test.ts` 覆盖对应玩法前缀；随后用 `npm run build:production-release -- --component web --name <临时名>` 复现 Jenkins web 构建路径。

 `Genarrative-Web-Build` 会把 `build/<version>/web.tar.gz`、`web.tar.gz.sha256`、`release-manifest.json` 和 `scripts/deploy/production-web-deploy.sh` 直接归档为 Jenkins 构建产物；`Genarrative-Web-Deploy` 只通过 `copyArtifacts` 从指定上游构建复制这些产物和部署脚本，不再在目标机器 checkout Git，再执行随构建归档的 `scripts/deploy/production-web-deploy.sh`。Web 发布不再读取构建机本地缓存目录，也不再通过 release agent `rsync` 回构建机拉取大包；如果 deploy 找不到 `web.tar.gz`，应先检查上游 Web Build 是否按同一 `BUILD_VERSION` 成功归档产物。

-`Genarrative-Api-Build` 的 Jenkins 归档产物必须包含 `build/<version>/api-server`、`api-server.sha256`、`release-manifest.json`、`scripts/database-backup-to-oss.mjs`、`scripts/deploy/production-api-deploy.sh`、`scripts/deploy/maintenance-on.sh` 和 `scripts/deploy/maintenance-off.sh`。`deploy/systemd/genarrative-database-backup.service` 从 `/opt/genarrative/current/scripts/database-backup-to-oss.mjs` 执行冷备份，`Genarrative-Api-Deploy` 会从上游 API 构建产物复制部署脚本和备份脚本，不再在目标机器 checkout Git；如果 API 发布后 current release 中缺少该脚本，应先检查 `Genarrative-Api-Build` 的 `archiveArtifacts` 和 `Genarrative-Api-Deploy` 的 `copyArtifacts` 过滤器是否仍包含 `build/<version>/scripts/database-backup-to-oss.mjs`，不要只在部署机工作区手工补文件。
+`Genarrative-Api-Build` 的 Jenkins 归档产物必须包含 `build/<version>/api-server`、`api-server.sha256`、`release-manifest.json`、`scripts/database-backup-to-oss.mjs`、`scripts/ops/production-health-patrol.mjs`、`scripts/deploy/production-api-deploy.sh`、`scripts/deploy/maintenance-on.sh` 和 `scripts/deploy/maintenance-off.sh`。`deploy/systemd/genarrative-database-backup.service` 从 `/opt/genarrative/current/scripts/database-backup-to-oss.mjs` 执行冷备份，`deploy/systemd/genarrative-health-patrol.service` 从 `/opt/genarrative/current/scripts/ops/production-health-patrol.mjs` 执行巡检；`Genarrative-Api-Deploy` 会从上游 API 构建产物复制部署脚本、备份脚本和巡检脚本，不再在目标机器 checkout Git。如果 API 发布后 current release 中缺少这些脚本，应先检查 `Genarrative-Api-Build` 的 `archiveArtifacts` 和 `Genarrative-Api-Deploy` 的 `copyArtifacts` 过滤器是否仍包含 `build/<version>/scripts/database-backup-to-oss.mjs` 与 `build/<version>/scripts/ops/production-health-patrol.mjs`，不要只在部署机工作区手工补文件。

 `Genarrative-Stdb-Module-Build` 的 Jenkins 归档产物必须包含 `build/<version>/spacetime_module.wasm`、`spacetime_module.wasm.sha256`、`release-manifest.json`、`scripts/deploy/production-stdb-publish.sh`、`scripts/deploy/maintenance-on.sh`、`scripts/deploy/maintenance-off.sh` 和 `scripts/database-backup-to-oss.mjs`。`Genarrative-Stdb-Module-Publish` 只通过 `copyArtifacts` 复制这些产物和发布脚本，不再在目标机器 checkout Git；如果 publish 前备份脚本缺失，应先检查 Stdb Build 的归档列表和 Stdb Publish 的复制过滤器。

@@ -256,6 +289,8 @@ Jenkins 按 web / api / Spacetime module / build / deploy / publish 拆分

 生产 Jenkins 的 `Pipeline script from SCM` 由 Jenkins controller 读取 Jenkinsfile。`Genarrative-Server-Provision` 是服务器初始化流水线，Job 配置里的 SCM URL 必须使用 controller 本机可访问的仓库路径或内网 Gitea 地址，不能使用 `https://git.genarrative.world/...`；否则日志一开始的 `Checking out git ... to read jenkins/Jenkinsfile.production-server-provision` 就会先从公网拉 Jenkinsfile。构建类流水线仍按各自 Jenkinsfile 的 checkout 口径执行；所有 `GitSCM checkout` 都必须保留单分支 refspec、`shallow=true`、`depth=1`、`noTags=true` 与 `honorRefspec=true`。API / Web / Stdb 发布类流水线不在目标机器 checkout Git，统一执行上游构建归档里的部署脚本，避免产物 commit 与部署脚本 commit 漂移。

+dev 服务器上的 Gitea 内网入口固定为 `http://10.2.0.10/GenarrativeAI/Genarrative.git`，用于 release / dev 等内网 agent 直接拉取仓库，避免绕公网 `git.genarrative.world`。该入口由 dev Nginx `/etc/nginx/conf.d/gitea-internal.conf` 暴露，只允许 `10.2.0.0/16` 和本机访问；Gitea 进程自身仍只监听 `127.0.0.1:3000`，公网域名 `https://git.genarrative.world/` 继续走原有 TLS 反代。验证时从 release 执行 `git ls-remote http://10.2.0.10/GenarrativeAI/Genarrative.git HEAD`，应能直接返回 HEAD。
+
 `scripts/jenkins-checkout-source.sh` 是生产 Jenkinsfile 内部二次确认源码的统一入口。构建流水线和服务器初始化流水线传入 `COMMIT_HASH` 时，脚本必须先保持 `depth=1` 浅拉，若上游 commit 已在浅历史内则直接校验并 checkout；只有浅历史无法证明 commit 属于目标分支时，才按 `GENARRATIVE_JENKINS_CHECKOUT_DEEPEN_STEPS`（默认 `50 200 1000 5000`）逐步加深，最后才尝试展开完整历史。`Genarrative-Api-Deploy`、`Genarrative-Web-Deploy` 和 `Genarrative-Stdb-Module-Publish` 仍保留上游构建传入的 `COMMIT_HASH` 作为通知和追溯字段，但不再用它在目标机器重新 checkout 部署脚本。


@@ -273,9 +308,10 @@ Jenkins 按 web / api / Spacetime module / build / deploy / publish 拆分

 - `api-server` 生产模板默认 `GENARRATIVE_API_LISTEN_BACKLOG=1024`、`GENARRATIVE_API_WORKER_THREADS=4`；本地未设置 worker threads 时继续使用 Tokio 默认值。
 - `GENARRATIVE_API_MAX_CONCURRENT_REQUESTS=512` 开启应用内 HTTP 并发背压；`GENARRATIVE_API_GALLERY_MAX_CONCURRENT_REQUESTS=320`、`GENARRATIVE_API_DETAIL_MAX_CONCURRENT_REQUESTS=64`、`GENARRATIVE_API_ADMIN_MAX_CONCURRENT_REQUESTS=16` 分别限制公开列表、公开详情和后台 API 热路径。超过许可时直接返回 `429 Too Many Requests` 和 `Retry-After: 1`，`/healthz` 与 `/readyz` 不受该限制。这些值不是 RPS 限速；如果压测中 429 上升但内存和 p95 收敛，说明背压正在保护进程。直连 `api-server` 的极高 RPS 压测若出现 `connection refused`，通常已经打到 TCP 监听 / accept 层，应同时检查 backlog、Nginx upstream keepalive 和前置限流。
- `api-server` 正常运行时 `/healthz` 返回进程存活状态，`/readyz` 返回是否仍接收新流量；收到 `SIGINT` / `SIGTERM` 后会先把 readiness 标记为不可用，再让 Axum 停止接新连接并等待已有 HTTP 请求排空。systemd 仍以 `KillSignal=SIGINT` 停服务，`TimeoutStopSec=90` 作为长请求排空上限。
+- `api-server` 正常运行时 `/healthz` 只返回进程存活状态，`/readyz` 会同时检查进程是否仍接收新流量和 SpacetimeDB 连接租约是否健康；收到 `SIGINT` / `SIGTERM` 后会先把 readiness 标记为不可用，再让 Axum 停止接新连接并等待已有 HTTP 请求排空。systemd 仍以 `KillSignal=SIGINT` 停服务，`TimeoutStopSec=90` 作为长请求排空上限。
+- SpacetimeDB 健康检查默认使用 `GENARRATIVE_SPACETIME_HEALTH_CHECK_TIMEOUT_SECONDS=2` 的短等待窗口，和业务 procedure 的 `GENARRATIVE_SPACETIME_PROCEDURE_TIMEOUT_SECONDS` 分开。`/readyz` 失败时 `details.spacetime.stage` 会标出当前卡住阶段：`pool_acquire`、`connect_build`、`connect_handshake`、`read_model_subscribe`、`procedure_result`、`reducer_result` 或 `read_cache`；`elapsedMs` / `timeoutMs` 用于确认是否命中健康检查窗口。业务请求日志也会写入 `operation_kind`、`operation_name`、`spacetime_stage` 和 `elapsed_ms`，后续 45 秒超时不再只靠 Nginx `request_time=45s` 推断。
 - `genarrative-api.service` 设置 `LimitNOFILE=65535`、`TasksMax=2048`；上线后用 `systemctl show genarrative-api.service -p LimitNOFILE -p TasksMax -p TimeoutStopUSec` 和 `cat /proc/$(pidof api-server)/limits` 核对。
- Server provision 不再通过 Windows helper 下载，也不再通过 Linux build 节点中转工具包。`Prepare Provision Tools` 在目标 dev / release agent 工作区内准备 SpacetimeDB `2.4.1` 的 `spacetime-x86_64-unknown-linux-gnu.tar.gz` 和 `otelcol-contrib_0.151.0_linux_amd64.tar.gz` 并生成 `provision-tools/`；如果目标服务器下载需要代理，在 `PROVISION_DOWNLOAD_PROXY` 配置目标机可访问的 HTTP 代理。
+- Server provision 不再通过 Windows helper 下载，也不再通过 Linux build 节点中转工具包。`Prepare Provision Tools` 在目标 dev / release agent 工作区内先检查 `/usr/local/bin/otelcol-contrib` 与 `${SPACETIME_ROOT}/bin/current`：版本已满足时直接复用目标机现有文件生成 `provision-tools/`，只有缺失或版本不匹配时才使用 `PROVISION_DOWNLOADS_DIR` 里的本地包或从配置的下载源准备 SpacetimeDB `2.4.1` / `otelcol-contrib 0.151.0`；如果目标服务器下载需要代理，在 `PROVISION_DOWNLOAD_PROXY` 配置目标机可访问的 HTTP 代理。
 - 除 `Genarrative-Server-Provision` 外，`Genarrative-Stdb-Module-Build`、`Genarrative-Web-Build`、`Genarrative-Api-Build`、`Genarrative-*Deploy`、`Genarrative-Database-Import/Export`、`Genarrative-Full-Build-And-Deploy` 和 `Genarrative-Notify-Email` 的生产流水线现都以 Linux agent 为主，仍按各自 Jenkinsfile 的 checkout 口径执行。Server provision 不使用公网备用 Git 源。
 - `otelcol-contrib.service` 作为可选系统服务加入 provision，默认监听 `127.0.0.1:4317/4318` 并使用 `deploy/otelcol/genarrative-debug.yaml`。api-server 是否发送 OTLP 仍由 `GENARRATIVE_OTEL_ENABLED` 控制，服务 unit 见 `deploy/systemd/otelcol-contrib.service`。
 - Nginx `/api/` 与 `/admin/api/` 通过 `genarrative_api` upstream 代理到 `127.0.0.1:8082`，upstream keepalive 为 64；`limit_conn` 负责连接 / 并发保护，`limit_req` 负责入口 RPS 快拒绝。当前模板把公开 gallery list 单独放到 `genarrative_gallery_rps`，默认 `rate=5000r/s`、`burst=4096`、`limit_conn=320`；公开详情和普通 API 放到 `genarrative_api_rps`，后台 API 放到 `genarrative_admin_rps`。通用 `/api` location 设置 `client_max_body_size 64m` 是反代兜底，防止拼图入口页 / 新增关卡本地参考图 Data URL 或旧兼容请求在到达 `api-server` 前被默认 1 MiB 上限拦截；拼图本地参考图前后端统一限制 6MB，历史图片仍提交 `referenceImageAssetObjectId(s)`。若线上出现 `413 Request Entity Too Large` 且 access log 中 `request_time=0.000`、`upstream_status=-`，说明请求在 Nginx 层被拦截，先用 `nginx -T | grep client_max_body_size` 检查 release 模板是否已渲染并 reload，同时检查前端是否超出 6MB 或错误提交了未压缩大图。`limit_conn_status 429` 和 `limit_req_status 429` 必须在 HTTP 与 HTTPS server 中同时生效；若线上压测看到 `limiting connections by zone "genarrative_api_conn"` 却返回 503，优先检查 `nginx -T` 里 HTTPS server 是否缺少这些状态码，以及 `/api/runtime/puzzle/gallery` 是否误落到通用 `location ~ ^/api` 的 `limit_conn=64`。压测时看 `/var/log/nginx/genarrative.access.log` 中的 `request_time`、`upstream_connect_time`、`upstream_header_time`、`upstream_response_time`、`upstream_status`、`request_id`。
@@ -429,6 +465,8 @@ journalctl -u genarrative-api.service --since '30 seconds ago' --no-pager | grep

 `Genarrative-Server-Provision` 和 `Genarrative-Api-Deploy` 会在保留旧 `/etc/genarrative/api-server.env` 的前提下补齐缺失的 tracking outbox 运行态路径，并确保 `/var/lib/genarrative/tracking-outbox` 归属 `genarrative:genarrative`。用户认证真相源只允许在 SpacetimeDB 正式认证表（`user_account` / `auth_identity` / `refresh_session`）恢复；不要再配置或依赖 `GENARRATIVE_AUTH_STORE_PATH` / `auth-store.json`，`module-auth` 也不再维护本地文件持久化；`auth_store_snapshot` 只保留行级记录，不再保存为单行 `default` 聚合快照，且旧 `get_auth_store_snapshot` / `upsert_auth_store_snapshot` / `import_auth_store_snapshot` 入口已经删除。如果 `api-server` 启动时连不上 SpacetimeDB，会持续重试启动恢复，直到认证工作集从 SpacetimeDB 正式表恢复成功后才开始监听 HTTP，以避免用空本地状态或旧快照覆盖认证表。

+前端登录态恢复只把 `/api/auth/refresh` 的 `401` / `403` 当成权威失效信号；服务器重启窗口里的 `502` / `503` / `504`、浏览器 `Failed to fetch` 或 refresh 响应契约异常都必须保留已有本地 access token，不触发全局 auth 变化。refresh 成功响应以共享契约 `RefreshSessionResponse { token }` 为准，前端不要额外要求业务 `ok` 字段。排查“重启后用户都掉线”时，先区分前端是否被暂时不可用清掉本地 token，再检查 SpacetimeDB 正式认证表是否缺 `user_account` / `refresh_session` 数据。
+
 常用检查思路：

 ```sql
@@ -104,7 +104,7 @@ pipeline {

    stage('Archive') {
      steps {
-        archiveArtifacts artifacts: "build/${env.EFFECTIVE_BUILD_VERSION}/api-server,build/${env.EFFECTIVE_BUILD_VERSION}/api-server.sha256,build/${env.EFFECTIVE_BUILD_VERSION}/release-manifest.json,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/database-backup-to-oss.mjs,scripts/deploy/production-api-deploy.sh,scripts/deploy/maintenance-on.sh,scripts/deploy/maintenance-off.sh", fingerprint: true
+        archiveArtifacts artifacts: "build/${env.EFFECTIVE_BUILD_VERSION}/api-server,build/${env.EFFECTIVE_BUILD_VERSION}/api-server.sha256,build/${env.EFFECTIVE_BUILD_VERSION}/release-manifest.json,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/database-backup-to-oss.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/ops/production-health-patrol.mjs,scripts/deploy/production-api-deploy.sh,scripts/deploy/maintenance-on.sh,scripts/deploy/maintenance-off.sh", fingerprint: true
      }
    }

@@ -65,7 +65,7 @@ pipeline {
        copyArtifacts(
          projectName: params.BUILD_JOB_NAME,
          selector: specific(params.BUILD_NUMBER_TO_DEPLOY),
-          filter: "build/${params.BUILD_VERSION}/api-server,build/${params.BUILD_VERSION}/api-server.sha256,build/${params.BUILD_VERSION}/release-manifest.json,build/${params.BUILD_VERSION}/scripts/database-backup-to-oss.mjs,scripts/deploy/production-api-deploy.sh,scripts/deploy/maintenance-on.sh,scripts/deploy/maintenance-off.sh",
+          filter: "build/${params.BUILD_VERSION}/api-server,build/${params.BUILD_VERSION}/api-server.sha256,build/${params.BUILD_VERSION}/release-manifest.json,build/${params.BUILD_VERSION}/scripts/database-backup-to-oss.mjs,build/${params.BUILD_VERSION}/scripts/ops/production-health-patrol.mjs,scripts/deploy/production-api-deploy.sh,scripts/deploy/maintenance-on.sh,scripts/deploy/maintenance-off.sh",
          target: '.',
          fingerprintArtifacts: true
        )
@@ -164,6 +164,7 @@ BASH
                PROVISION_DOWNLOAD_PROXY="${PROVISION_DOWNLOAD_PROXY:-}" \
                SPACETIME_DOWNLOAD_ROOT="${SPACETIME_DOWNLOAD_ROOT:-https://github.com/clockworklabs/SpacetimeDB/releases/download/v2.4.1}" \
                SPACETIME_TARGET_HOST="${SPACETIME_TARGET_HOST:-x86_64-unknown-linux-gnu}" \
+                SPACETIME_ROOT="${SPACETIME_ROOT:-/stdb}" \
                scripts/prepare-server-provision-tools.sh
              '
            '''
@@ -9,6 +9,7 @@
    "dev:api-server": "node scripts/dev.mjs api-server",
    "dev:web": "node scripts/dev.mjs web",
    "dev:admin-web": "node scripts/dev.mjs admin-web",
+    "server-manager:panel": "cargo run -p server-manager-panel --manifest-path server-rs/Cargo.toml",
    "dev:spacetime:logs": "node scripts/run-bash-script.mjs scripts/spacetime-logs-local.sh",
    "otel:debug": "node scripts/run-otelcol.mjs debug",
    "otel:rider": "node scripts/run-otelcol.mjs rider",
@@ -27,6 +28,7 @@
    "clean": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\"",
    "check:encoding": "node scripts/check-encoding.mjs",
    "check:spacetime-schema": "node scripts/check-spacetime-schema-guard.mjs",
+    "check:production-ops": "node scripts/check-production-ops-guardrails.mjs",
    "assets:child-motion-demo": "node scripts/generate-child-motion-demo-assets.mjs",
    "assets:match3d-style-references": "node scripts/generate-match3d-style-references.mjs",
    "check:visual-novel-vn11": "node scripts/check-visual-novel-vn11-negative-scan.mjs",
@@ -37,7 +39,7 @@
    "lint:guardrails": "npm run lint:eslint",
    "typecheck": "tsc -p tsconfig.typecheck-guardrails.json --noEmit",
    "typecheck:guardrails": "npm run typecheck",
-    "lint": "npm run check:encoding && npm run check:spacetime-schema && npm run lint:eslint && npm run typecheck",
+    "lint": "npm run check:encoding && npm run check:spacetime-schema && npm run check:production-ops && npm run lint:eslint && npm run typecheck",
    "lint:fix": "eslint . --ext .ts,.tsx,.js,.mjs,.cjs --fix && prettier --write .",
    "format": "prettier --write .",
    "format:check": "prettier --check .",
@@ -156,8 +156,7 @@ export type AuthPhoneChangeResponse = {
 };

 export type AuthRefreshResponse = {
-  ok: true;
-  token?: string;
+  token: string;
 };

 export type AuthSessionSummary = {
@@ -445,7 +445,7 @@ if [[ "${BUILD_SPACETIME}" -eq 1 ]]; then
  write_migration_bootstrap_secret_file
 fi

-mkdir -p "${TARGET_DIR}/scripts" "${TARGET_DIR}/deploy"
+mkdir -p "${TARGET_DIR}/scripts" "${TARGET_DIR}/scripts/ops" "${TARGET_DIR}/deploy"
 cp "${SCRIPT_DIR}/deploy/maintenance-on.sh" "${TARGET_DIR}/scripts/maintenance-on.sh"
 cp "${SCRIPT_DIR}/deploy/maintenance-off.sh" "${TARGET_DIR}/scripts/maintenance-off.sh"
 cp "${SCRIPT_DIR}/deploy/maintenance-status.sh" "${TARGET_DIR}/scripts/maintenance-status.sh"
@@ -466,6 +466,7 @@ copy_required_file "${SCRIPT_DIR}/spacetime-migration-common.mjs" "${TARGET_DIR}
 copy_required_file "${SCRIPT_DIR}/spacetime-authorize-migration-operator.mjs" "${TARGET_DIR}/scripts/spacetime-authorize-migration-operator.mjs" "数据库迁移授权脚本"
 copy_required_file "${SCRIPT_DIR}/spacetime-revoke-migration-operator.mjs" "${TARGET_DIR}/scripts/spacetime-revoke-migration-operator.mjs" "数据库迁移撤权脚本"
 copy_required_file "${SCRIPT_DIR}/database-backup-to-oss.mjs" "${TARGET_DIR}/scripts/database-backup-to-oss.mjs" "数据库 OSS 备份脚本"
+copy_required_file "${SCRIPT_DIR}/ops/production-health-patrol.mjs" "${TARGET_DIR}/scripts/ops/production-health-patrol.mjs" "生产健康巡检脚本"

 copy_required_dir "${REPO_ROOT}/deploy/systemd" "${TARGET_DIR}/deploy/systemd" "systemd 配置"
 copy_required_dir "${REPO_ROOT}/deploy/nginx" "${TARGET_DIR}/deploy/nginx" "Nginx 配置"
@@ -485,7 +486,7 @@ cat >"${TARGET_DIR}/README.md" <<EOF
 - \`migration-bootstrap-secret.txt\`：构建 \`spacetime_module.wasm\` 时注入的迁移引导密钥，仅用于创建首个迁移操作员；请作为敏感文件保存到 Jenkins Secret Text，授权完成后不要长期留在公开归档中。
 - \`*.sha256\`：发布产物 checksum，用于部署前校验。
 - \`release-manifest.json\`：发布版本、源码 commit 与产物清单。
- \`scripts/\`：维护模式脚本、数据库导入导出脚本、数据库 OSS 备份脚本、迁移授权脚本和 Jenkins inbound agent systemd 安装脚本。
+- \`scripts/\`：维护模式脚本、数据库导入导出脚本、数据库 OSS 备份脚本、生产健康巡检脚本、迁移授权脚本和 Jenkins inbound agent systemd 安装脚本。
 - \`deploy/\`：systemd、Nginx 和生产环境变量示例；\`deploy/nginx/genarrative-dev-http.conf\` 仅供无域名开发服初始化使用。

 ## 生产部署口径
@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+
+import {readFileSync} from 'node:fs';
+
+const checks = [
+  {
+    file: 'deploy/systemd/genarrative-database-backup.service',
+    includes: '--restart-service-after genarrative-api.service',
+    reason: '生产冷备份恢复 SpacetimeDB 后必须显式拉起依赖它的 API 服务。',
+  },
+  {
+    file: 'deploy/systemd/genarrative-health-patrol.service',
+    includes: 'scripts/ops/production-health-patrol.mjs',
+    reason: '健康巡检 systemd service 必须调用随 API release 发布的巡检脚本。',
+  },
+  {
+    file: 'deploy/systemd/genarrative-health-patrol.timer',
+    includes: 'genarrative-health-patrol.service',
+    reason: '健康巡检 timer 必须绑定巡检 service。',
+  },
+  {
+    file: 'scripts/jenkins-server-provision.sh',
+    includes: 'genarrative-health-patrol.timer',
+    reason: 'Server-Provision 必须安装并启用健康巡检 timer。',
+  },
+  {
+    file: 'scripts/build-production-release.sh',
+    includes: 'production-health-patrol.mjs',
+    reason: '生产 API release 必须携带健康巡检脚本。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    includes: 'production-health-patrol.mjs',
+    reason: 'API deploy 必须把健康巡检脚本复制到 current release。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-build',
+    includes: 'scripts/ops/production-health-patrol.mjs',
+    reason: 'API Build 归档必须包含健康巡检脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-deploy',
+    includes: 'scripts/ops/production-health-patrol.mjs',
+    reason: 'API Deploy 复制上游产物时必须包含健康巡检脚本。',
+  },
+];
+
+let failed = false;
+
+for (const check of checks) {
+  const content = readFileSync(check.file, 'utf8');
+  if (!content.includes(check.includes)) {
+    failed = true;
+    console.error(
+      `[check:production-ops] ${check.file} 缺少 ${check.includes}。${check.reason}`,
+    );
+  }
+}
+
+if (failed) {
+  process.exit(1);
+}
+
+console.log('[check:production-ops] OK');
@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_ROOT="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd)"
+TMP_ROOT="$(mktemp -d)"
+trap 'rm -rf "${TMP_ROOT}"' EXIT
+
+WORK_DIR="${TMP_ROOT}/workspace"
+FAKE_BIN_DIR="${TMP_ROOT}/fake-bin"
+TARGET_BIN_DIR="${TMP_ROOT}/target-bin"
+SPACETIME_ROOT_DIR="${TMP_ROOT}/stdb"
+OUTPUT_LOG="${TMP_ROOT}/prepare.log"
+
+mkdir -p \
+  "${WORK_DIR}" \
+  "${FAKE_BIN_DIR}" \
+  "${TARGET_BIN_DIR}" \
+  "${SPACETIME_ROOT_DIR}/bin/current"
+
+cat >"${FAKE_BIN_DIR}/curl" <<'EOF'
+#!/usr/bin/env bash
+echo "curl should not be called when target tools are already ready" >&2
+exit 97
+EOF
+cat >"${FAKE_BIN_DIR}/wget" <<'EOF'
+#!/usr/bin/env bash
+echo "wget should not be called when target tools are already ready" >&2
+exit 97
+EOF
+chmod +x "${FAKE_BIN_DIR}/curl" "${FAKE_BIN_DIR}/wget"
+
+cat >"${TARGET_BIN_DIR}/otelcol-contrib" <<'EOF'
+#!/usr/bin/env bash
+echo "otelcol-contrib version 0.151.0"
+EOF
+chmod +x "${TARGET_BIN_DIR}/otelcol-contrib"
+
+cat >"${SPACETIME_ROOT_DIR}/bin/current/spacetimedb-cli" <<'EOF'
+#!/usr/bin/env bash
+echo "spacetimedb-cli 2.4.1"
+EOF
+cat >"${SPACETIME_ROOT_DIR}/bin/current/spacetimedb-standalone" <<'EOF'
+#!/usr/bin/env bash
+echo "spacetimedb-standalone 2.4.1"
+EOF
+chmod +x \
+  "${SPACETIME_ROOT_DIR}/bin/current/spacetimedb-cli" \
+  "${SPACETIME_ROOT_DIR}/bin/current/spacetimedb-standalone"
+
+if ! (
+  cd "${WORK_DIR}"
+  PATH="${FAKE_BIN_DIR}:${PATH}" \
+    WORKSPACE="${WORK_DIR}" \
+    PROVISION_TOOLS_DIR="provision-tools" \
+    PROVISION_DOWNLOADS_DIR="downloads" \
+    PROVISION_TOOLS_TMP_PARENT="${WORK_DIR}/.tmp/server-provision-tools" \
+    PROVISION_REQUIRE_LOCAL_DOWNLOADS="true" \
+    OTELCOL_TARGET_BIN="${TARGET_BIN_DIR}/otelcol-contrib" \
+    OTELCOL_VERSION="0.151.0" \
+    SPACETIME_ROOT="${SPACETIME_ROOT_DIR}" \
+    SPACETIME_EXPECTED_VERSION="2.4.1" \
+    "${REPO_ROOT}/scripts/prepare-server-provision-tools.sh" \
+    >"${OUTPUT_LOG}" 2>&1
+); then
+  echo "[check-server-provision-tools] prepare-server-provision-tools.sh 执行失败。" >&2
+  cat "${OUTPUT_LOG}" >&2
+  exit 1
+fi
+
+grep -q "复用目标机已有 otelcol-contrib" "${OUTPUT_LOG}"
+grep -q "复用目标机已有 SpacetimeDB 安装" "${OUTPUT_LOG}"
+grep -q "otelcol-contrib 0.151.0 target existing" "${WORK_DIR}/provision-tools/MANIFEST.txt"
+grep -q "spacetime target existing" "${WORK_DIR}/provision-tools/MANIFEST.txt"
+
+test -x "${WORK_DIR}/provision-tools/otelcol-contrib"
+test -x "${WORK_DIR}/provision-tools/spacetime/spacetime"
+test -x "${WORK_DIR}/provision-tools/spacetime/bin/current/spacetimedb-cli"
+test -x "${WORK_DIR}/provision-tools/spacetime/bin/current/spacetimedb-standalone"
+
+if grep -q "下载 " "${OUTPUT_LOG}"; then
+  echo "[check-server-provision-tools] 已有目标机工具时不应进入下载分支。" >&2
+  cat "${OUTPUT_LOG}" >&2
+  exit 1
+fi
+
+echo "[check-server-provision-tools] OK"
@@ -334,7 +334,9 @@ chmod +x "${RELEASE_DIR}/api-server"

 BACKUP_SCRIPT_SOURCE="${SOURCE_DIR}/scripts/database-backup-to-oss.mjs"
 WORKSPACE_BACKUP_SCRIPT_SOURCE="$(cd "${SCRIPT_DIR}/../.." && pwd)/scripts/database-backup-to-oss.mjs"
-mkdir -p "${RELEASE_DIR}/scripts"
+HEALTH_PATROL_SCRIPT_SOURCE="${SOURCE_DIR}/scripts/ops/production-health-patrol.mjs"
+WORKSPACE_HEALTH_PATROL_SCRIPT_SOURCE="$(cd "${SCRIPT_DIR}/../.." && pwd)/scripts/ops/production-health-patrol.mjs"
+mkdir -p "${RELEASE_DIR}/scripts" "${RELEASE_DIR}/scripts/ops"
 if [[ ! -f "${BACKUP_SCRIPT_SOURCE}" ]]; then
  if [[ -f "${WORKSPACE_BACKUP_SCRIPT_SOURCE}" ]]; then
    echo "[production-api-deploy] 发布产物缺少 scripts/database-backup-to-oss.mjs，回退使用部署工作区脚本；请重新触发包含该脚本的 API 构建。" >&2
@@ -346,6 +348,19 @@ if [[ ! -f "${BACKUP_SCRIPT_SOURCE}" ]]; then
 fi
 cp "${BACKUP_SCRIPT_SOURCE}" "${RELEASE_DIR}/scripts/database-backup-to-oss.mjs"
 chmod 0644 "${RELEASE_DIR}/scripts/database-backup-to-oss.mjs"
+if [[ ! -f "${HEALTH_PATROL_SCRIPT_SOURCE}" ]]; then
+  if [[ -f "${WORKSPACE_HEALTH_PATROL_SCRIPT_SOURCE}" ]]; then
+    echo "[production-api-deploy] 发布产物缺少 scripts/ops/production-health-patrol.mjs，回退使用部署工作区脚本；请重新触发包含该脚本的 API 构建。" >&2
+    HEALTH_PATROL_SCRIPT_SOURCE="${WORKSPACE_HEALTH_PATROL_SCRIPT_SOURCE}"
+  else
+    echo "[production-api-deploy] 未找到生产健康巡检脚本，跳过复制；genarrative-health-patrol.service 会因脚本缺失而跳过执行。" >&2
+    HEALTH_PATROL_SCRIPT_SOURCE=""
+  fi
+fi
+if [[ -n "${HEALTH_PATROL_SCRIPT_SOURCE}" ]]; then
+  cp "${HEALTH_PATROL_SCRIPT_SOURCE}" "${RELEASE_DIR}/scripts/ops/production-health-patrol.mjs"
+  chmod 0644 "${RELEASE_DIR}/scripts/ops/production-health-patrol.mjs"
+fi

 if [[ -f "${SOURCE_DIR}/release-manifest.json" ]]; then
  cp "${SOURCE_DIR}/release-manifest.json" "${RELEASE_DIR}/release-manifest.api-server.json"
--- a/Show More
+++ b/Show More