@@ -1,6 +1,6 @@
# 本地开发验证与生产运维
更新时间：`2026-07-21 `
更新时间：`2026-07-23 `
## 标准开发流程
@@ -151,7 +151,7 @@ spacetime sql <database> "SELECT * FROM runtime_setting LIMIT 1" --server http:/
本地 `npm run dev:spacetime` 发布模块时必须显式忽略仓库根目录的 `spacetime.json` ，由脚本固定追加 `--no-config` 并使用命令参数里传入的数据库名和 `--server http://127.0.0.1:3101` 。否则 CLI 可能把发布目标改写到配置文件里的其他数据库，导致 `dev:spacetime` 启动后又因发布失败自动退出，浏览器随后会在 `ws://127.0.0.1:3101/v1/database/.../subscribe` 看到连接拒绝。
本地 `spacetime` CLI / standalone 版本必须和 `server-rs/Cargo.toml` 里锁定的 `spacetimedb` 版本一致；当前统一版本为 `2.6.1` 。若版本错配，procedure 返回值可能在宿主侧触发 `Failed to BSATN deserialize procedure return value` ， `spacetime --version` ，再对照 `server-rs/Cargo.toml` 的 `spacetimedb = "..."` ； 遇到版本不匹配时直接 执行 `spacetime version install <version> && spacetime version use <version>` ， 或在目标就是最新版本时执行 `spacetime version upgrade` ， `npm run dev:spacetime` 再重试。当前 `scripts/dev.mjs` 会在启动和复用本地 SpacetimeDB 前写入并校验 `dev-spacetime-tool-version` 。2.6.1 修复了 procedure context 中调用者 `Identity` / `ConnectionId` 始终为空的回归，依赖 `ctx.sender` 鉴权时必须同时确认宿主已升级。
本地 `spacetime` CLI / standalone 版本必须和 `server-rs/Cargo.toml` 里锁定的 `spacetimedb` 版本一致；当前统一版本为 `2.7.0` 。官方发行包位于 `v2.7.0-hotfix3` 资产标签，二进制仍报告 `2.7.0` ；运行态和 provision 必须使用该 hotfix 构建，不得只按裸 `v2.7.0` tag 下载。当前 updater 元数据可能让 `spacetime version install 2.7.0` 装到裸 tag commit `a08663c7...` ，所以 2.7.0 安装后必须核对 `spacetime --version` 的 commit 为 hotfix3 `d220349a...` ；不一致时改用官方 hotfix3 archive 或仓库 provision 流程 。若版本错配，procedure 返回值可能在宿主侧触发 `Failed to BSATN deserialize procedure return value` ， `spacetime --version` ，再对照 `server-rs/Cargo.toml` 的 `spacetimedb = "..."` ； 其它版本可 执行 `spacetime version install <version> && spacetime version use <version>` ，升级后重启 `npm run dev:spacetime` 再重试。当前 `scripts/dev.mjs` 会把 tool version 和 commit 一起写入 `dev-spacetime-tool-version` ，启动新 standalone 与复用已有本地进程时都要求 `2.7.0 + d220349a...` 同时匹配；旧单行版本记录会拒绝复用并要求重启 。2.6.1 修复了 procedure context 中调用者 `Identity` / `ConnectionId` 始终为空的回归，依赖 `ctx.sender` 鉴权时必须同时确认宿主已升级。
本地 `.env` 、`.env.local` 或 `.env.secrets.local` 修改后必须重启 `api-server` 才会生效；若已经通过 `npm run dev` 启动完整联调，可在该终端输入 `rs api-server` 。排查图片编辑器 VectorEngine 生成链路时，确认 `VECTOR_ENGINE_BASE_URL` 、`VECTOR_ENGINE_API_KEY` 和 `VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS` 只在本地或服务器密钥文件中配置，不能写入 Git。`VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS` 是单次 attempt 的配置上限，默认 `1000000` ；配置加载层允许显式值低于该默认值，不再在读取环境变量时强制抬高。业务模型和 VectorEngine provider 首选请求都使用 `gpt-image-2` ，符合条件时才回退到兜底模型 `gpt-image-2-c` ；图片协议、URL / base64 响应解析、远端图片下载和 provider 侧结构化日志在 `server-rs/crates/platform-image` ， `api-server` 只做编辑器请求编排、OSS / asset 持久化、计费和失败审计落库。`platform-image` 会在 JSON 生成和 multipart 编辑请求发送前按同一 GPT-image-2 family 规则归一显式像素尺寸；若请求发送失败，先按同一 `request_id` 查看 provider 日志与 `external_api_call_failure.metadata_json.errorSource` ，当前 multipart `/v1/images/edits` 单独强制 HTTP/1.1。
@@ -247,7 +247,7 @@ SpacetimeDB bindings：
npm run spacetime:generate
```
后台账号 procedure 的 identity、唯一索引和版本事务使用隔离 smoke 验证；脚本会在随机本机端口启动临时 SpacetimeDB 2.6 、发布当前 module，结束后自动关闭并清理临时数据：
后台账号 procedure 的 identity、唯一索引和版本事务使用隔离 smoke 验证；脚本会在随机本机端口启动仓库锁定版本的 临时 SpacetimeDB、发布当前 module，结束后自动关闭并清理临时数据：
``` bash
npm run check:admin-account-procedures
@@ -609,7 +609,7 @@ worker 被硬杀或断电后，lease 过期任务只有尚未耗尽 `max_attempt
- `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 节点中转 SpacetimeDB / otelcol 工具包；Linux build 节点只负责从内网 Git 源准备 provision 脚本和配置并上传给目标 agent。`Prepare Provision Tools` 在目标 dev / release agent 工作区内先检查 `/usr/local/bin/otelcol-contrib` 与 `${SPACETIME_ROOT}/bin/current` ： 版本已满足时直接复用目标机现有文件生成 `provision-tools/` ，只有缺失或版本 不匹配时才使用 `PROVISION_DOWNLOADS_DIR` 里的本地包或从配置的下载源准备 SpacetimeDB `2.6.1` / ` otelcol-contrib 0.151.0``PROVISION_DOWNLOAD_PROXY` 配置目标机可访问的 HTTP 代理。
- Server provision 不再通过 Windows helper 下载，也不再通过 Linux build 节点中转 SpacetimeDB / otelcol 工具包；Linux build 节点只负责从内网 Git 源准备 provision 脚本和配置并上传给目标 agent。`Prepare Provision Tools` 在目标 dev / release agent 工作区内先检查 `/usr/local/bin/otelcol-contrib` 与 `${SPACETIME_ROOT}/bin/current` ： SpacetimeDB 必须同时匹配运行版本 `2.7.0` 和 hotfix3 commit `d220349a...` 才能复用，裸 tag `a08663c7...` 即使版本号相同也必须拒绝；只有缺失或版本 / commit 不匹配时才使用 `PROVISION_DOWNLOADS_DIR` 里的本地包或从配置的下载源准备官方 `v 2.7.0-hotfix3` 资产。 `SPACETIME_EXPECTED_COMMIT` 与下载根必须成对调整，安装结果也执行同一 commit 门禁。 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 源，目标部署 agent 也不再需要访问源码 Git remote。
- `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` 。该服务必须存在系统用户 / 组 `otelcol` ，并且 `/etc/otelcol/genarrative-debug.yaml` 已安装到目标机；若看到 `status=217/USER` 或 `Failed to determine user credentials` ，优先检查 `getent passwd otelcol` ，再补齐 `/etc/otelcol` 配置目录并重启服务。
- Nginx `/api/` 与 `/admin/api/` 通过 `genarrative_api` upstream 代理到 `127.0.0.1:8082` ， `genarrative_api_rps` ，后台 API 使用 `genarrative_admin_rps` 。通用 `/api` location 保留 `client_max_body_size 64m` 作为编辑器图片、视频和文档请求的反代兜底，真实大小仍由路由与业务校验负责。若线上出现 `413 Request Entity Too Large` 且 access log 中 `request_time=0.000` 、`upstream_status=-` ，说明请求在 Nginx 层被拦截，先核对 release 模板与实际媒体大小。`limit_conn_status 429` 和 `limit_req_status 429` 必须在 HTTP 与 HTTPS server 中同时生效。
