From a2ee879fc87757d807fca85b188cd044732cb83a Mon Sep 17 00:00:00 2001 From: Linghong Date: Thu, 23 Jul 2026 18:06:29 +0800 Subject: [PATCH] =?UTF-8?q?=E6=B7=BB=E5=8A=A0gfilter=E4=B8=93=E7=94=A8work?= =?UTF-8?q?er=20(#103)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: kdletters Reviewed-on: http://genarrative-station/git/GenarrativeAI/Genarrative/pulls/103 Co-authored-by: Linghong Co-committed-by: Linghong --- .env.example | 13 + .gitea/workflows/project-ci.yml | 12 + .../SKILL.md | 45 +- README.md | 6 +- deploy/container/README.md | 4 +- deploy/container/api-server.env.example | 5 +- deploy/env/api-server.env.example | 13 +- deploy/env/bgfilter-worker.env.example | 18 + deploy/env/health-patrol.env.example | 3 + .../genarrative-bgfilter-worker.service | 30 + docs/README.md | 1 + .../shared-memory/decision-log.md | 60 +- .../shared-memory/development-workflow.md | 21 +- docs/project-memory/shared-memory/pitfalls.md | 16 + ...架构】图片画布编辑器MVP接入方案-2026-06-11.md | 12 +- ...架构】BgFilter受限资源调度方案-2026-07-21.md | 542 +++ ...端架构】外部生成Worker化方案-2026-06-03.md | 6 +- ...】server-rs与SpacetimeDB数据契约-2026-05-15.md | 6 +- ...发运维】本地开发验证与生产运维-2026-05-15.md | 69 +- ...辑器】画板UI设计图生成入口设计-2026-06-17.md | 4 +- ...辑器】画板图标素材生成入口设计-2026-06-15.md | 4 +- ...辑器】画板角色形象生成入口设计-2026-06-15.md | 12 +- jenkins/Jenkinsfile.production-api-deploy | 6 +- ...nkinsfile.production-full-build-and-deploy | 4 + package.json | 4 + scripts/bgfilter-worker-load-smoke.mjs | 1362 ++++++ scripts/bgfilter-worker-load-smoke.test.mjs | 190 + scripts/check-production-api-deploy.mjs | 877 +++- scripts/check-production-api-release.mjs | 36 + scripts/check-production-health-patrol.mjs | 15 + scripts/check-production-ops-guardrails.mjs | 111 + scripts/deploy/production-api-deploy.sh | 546 ++- scripts/dev-stack-port-utils.mjs | 6 +- scripts/dev-stack-port-utils.test.ts | 9 +- scripts/dev.mjs | 362 +- scripts/dev.test.ts | 174 +- scripts/jenkins-server-provision.sh | 413 +- scripts/ops/production-health-patrol.mjs | 16 + .../crates/api-server/src/bgfilter_worker.rs | 3816 +++++++++++++++++ .../src/character_animation_assets.rs | 82 +- server-rs/crates/api-server/src/config.rs | 199 +- .../crates/api-server/src/editor_project.rs | 1241 ++---- .../src/editor_screen_background_decision.rs | 1 + .../api-server/src/external_api_audit.rs | 116 + server-rs/crates/api-server/src/main.rs | 248 +- server-rs/crates/api-server/src/state.rs | 98 +- server-rs/crates/api-server/src/telemetry.rs | 17 + .../examples/bgfilter_worker_live_smoke.rs | 882 ++++ .../ImageCanvasEditorView.test-utils.ts | 1 + 49 files changed, 10627 insertions(+), 1107 deletions(-) create mode 100644 deploy/env/bgfilter-worker.env.example create mode 100644 deploy/systemd/genarrative-bgfilter-worker.service create mode 100644 docs/technical/【后端架构】BgFilter受限资源调度方案-2026-07-21.md create mode 100644 scripts/bgfilter-worker-load-smoke.mjs create mode 100644 scripts/bgfilter-worker-load-smoke.test.mjs create mode 100644 server-rs/crates/api-server/src/bgfilter_worker.rs create mode 100644 server-rs/crates/platform-oss/examples/bgfilter_worker_live_smoke.rs diff --git a/.env.example b/.env.example index 4b5ed9164..58b202e3d 100644 --- a/.env.example +++ b/.env.example @@ -143,6 +143,19 @@ ALIYUN_OSS_POST_EXPIRE_SECONDS="600" ALIYUN_OSS_POST_MAX_SIZE_BYTES="20971520" ALIYUN_OSS_SUCCESS_ACTION_STATUS="200" +# BgFilter 受限资源 worker。父 api-server / external-generation-worker 与唯一的 +# `GENARRATIVE_PROCESS_ROLE=bgfilter-worker` 进程必须使用同一个内部 Token。 +# `npm run dev` 与 `npm run dev:api-server` 都会自动带起并验活唯一 worker，不要再开第二个终端重复启动。 +# 只有需要脱离父 API 单独验证 worker 时才运行 `npm run dev:bgfilter-worker`；不要让 `all` 角色兼任它。 +GENARRATIVE_BGFILTER_WORKER_HOST="127.0.0.1" +GENARRATIVE_BGFILTER_WORKER_PORT="8083" +GENARRATIVE_BGFILTER_WORKER_BASE_URL="http://127.0.0.1:8083" +GENARRATIVE_BGFILTER_INTERNAL_TOKEN="CHANGE_ME_FOR_LOCAL" +GENARRATIVE_BGFILTER_WORKER_CONCURRENCY="16" +GENARRATIVE_EDITOR_BGFILTER_SINGLE_IMAGE_ESTIMATE_MS="5000" +GENARRATIVE_BGFILTER_WORKER_MAX_REQUESTS="2048" +GENARRATIVE_BGFILTER_WORKER_CONNECT_TIMEOUT_MS="2000" + # SpacetimeDB 数据目录备份到 OSS。备份 bucket 可与资源 bucket 分离；未设置时脚本回退使用 ALIYUN_OSS_BUCKET。 GENARRATIVE_DATABASE_BACKUP_DATA_DIR="" GENARRATIVE_DATABASE_BACKUP_WORK_DIR="" diff --git a/.gitea/workflows/project-ci.yml b/.gitea/workflows/project-ci.yml index b728bda03..29c8a4bcf 100644 --- a/.gitea/workflows/project-ci.yml +++ b/.gitea/workflows/project-ci.yml @@ -106,6 +106,18 @@ jobs: - name: Run frontend and script tests run: npm run test + - name: Run BgFilter worker smoke harness tests + run: npm run bgfilter-worker:smoke-test + + - name: Validate production health patrol behavior + run: npm run check:production-health-patrol + + - name: Validate production API release behavior + run: npm run check:production-api-release + + - name: Validate production API deploy behavior + run: npm run check:production-api-deploy + backend-tests: name: Backend tests runs-on: genarrative-ci diff --git a/.hermes/skills/genarrative-dev-stack-port-routing/SKILL.md b/.hermes/skills/genarrative-dev-stack-port-routing/SKILL.md index 18c2ebe05..2562ed0f6 100644 --- a/.hermes/skills/genarrative-dev-stack-port-routing/SKILL.md +++ b/.hermes/skills/genarrative-dev-stack-port-routing/SKILL.md @@ -1,8 +1,8 @@ --- name: genarrative-dev-stack-port-routing short_description: 修改 Genarrative 本地 dev 启动端口、代理目标、端口冲突处理时使用。 -description: 在 Genarrative 中修改 npm run dev / dev:spacetime / dev:api-server / dev:web / dev:admin-web 的本地启动端口、端口可用性探测、端口漂移、SpacetimeDB publish server、api-server 环境变量、Vite 代理目标和后台 admin-web 启动串联时使用。 -version: 1.0.0 +description: 在 Genarrative 中修改 npm run dev / dev:spacetime / dev:api-server / dev:bgfilter-worker / dev:web / dev:admin-web 的本地启动端口、端口可用性探测、端口漂移、SpacetimeDB publish server、Rust 进程环境变量、Vite 代理目标和后台 admin-web 启动串联时使用。 +version: 1.1.0 author: Hermes Agent license: MIT metadata: @@ -13,7 +13,7 @@ metadata: # Genarrative 本地 dev 启动端口与代理目标串联流程 -用于维护 Genarrative 本地开发栈启动脚本，重点覆盖 `npm run dev` 与四个 `dev:*` 单模块命令的端口检查、端口漂移和后续流程目标传递。 +用于维护 Genarrative 本地开发栈启动脚本，重点覆盖 `npm run dev` 与五个 `dev:*` 单模块命令的端口检查、端口漂移和后续流程目标传递。 ## 适用场景 @@ -31,40 +31,44 @@ metadata: 2. Rust `api-server`：`8082`，健康检查为 `http://127.0.0.1:/healthz`。 3. SpacetimeDB standalone：`3101`，健康检查为 `http://127.0.0.1:/v1/ping`。 4. 后台 Vite：`3102`，后台地址为 `http://127.0.0.1:/admin/`。 +5. 独立 BgFilter worker：`8083`，就绪检查为 `http://127.0.0.1:/readyz`。 端口不可用时，脚本会从优先端口开始向后寻找可用端口。后续流程必须以解析后的实际端口为准，不能继续使用默认端口。 -Linux 多用户并发开发时，`GENARRATIVE_DEV_PORT_RANGE` 或 `--port-range` 会先向系统级注册表 `/var/tmp/genarrative-dev-port-ranges/registry.json` 申请一个端口段，再把该段映射为 `web = start`、`api = start + 1`、`spacetime = start + 2`、`adminWeb = start + 3`。注册表锁文件是 `/var/tmp/genarrative-dev-port-ranges/registry.lock`，可通过 `GENARRATIVE_DEV_PORT_RANGE_REGISTRY_DIR` 覆盖目录。自动分配从 `10000-10099` 起，每次占用 100 个端口块，后续块按 `10100-10199`、`10200-10299` 递增；当前口径是“一个用户固定占用一个段，后续启动继续复用这段并在段内漂移”；该注册表只在 Linux 上生效；Windows 继续沿用原有端口探测、漂移和复用逻辑，不读系统级注册表。 +Linux 多用户并发开发时，`GENARRATIVE_DEV_PORT_RANGE` 或 `--port-range` 会先向系统级注册表 `/var/tmp/genarrative-dev-port-ranges/registry.json` 申请一个端口段，再把该段映射为 `web = start`、`api = start + 1`、`spacetime = start + 2`、`adminWeb = start + 3`、`bgfilterWorker = start + 4`。注册表锁文件是 `/var/tmp/genarrative-dev-port-ranges/registry.lock`，可通过 `GENARRATIVE_DEV_PORT_RANGE_REGISTRY_DIR` 覆盖目录。自动分配从 `10000-10099` 起，每次占用 100 个端口块，后续块按 `10100-10199`、`10200-10299` 递增；当前口径是“一个用户固定占用一个段，后续启动继续复用这段并在段内漂移”；该注册表只在 Linux 上生效；Windows 继续沿用原有统一端口探测和漂移逻辑，不读系统级注册表。 ## 实现入口 - `package.json` - - `dev`：执行 `node scripts/dev.mjs`，启动完整四模块。 - - `dev:spacetime` / `dev:api-server` / `dev:web` / `dev:admin-web`：执行 `node scripts/dev.mjs `。 + - `dev`：执行 `node scripts/dev.mjs`，启动完整五服务。 + - `dev:spacetime` / `dev:api-server` / `dev:bgfilter-worker` / `dev:web` / `dev:admin-web`：执行 `node scripts/dev.mjs `；`dev:api-server` 会安全带起其依赖的 BgFilter worker。 - `scripts/dev-stack-port-utils.mjs` - `isPortAvailable(...)`：探测端口是否可监听。 - `findAvailablePort(...)`：从优先端口向后寻找可用端口，`0` 表示申请临时端口。 - - `resolveDevStackPorts(...)`：一次性解析 SpacetimeDB、api-server、主站 Vite、后台 Vite 端口，并避免本次解析结果互相冲突。 + - `resolveDevStackPorts(...)`：一次性解析 SpacetimeDB、api-server、主站 Vite、后台 Vite、BgFilter worker 端口，并避免本次解析结果互相冲突。 - Linux 注册表分配：`reserveLinuxDevPortRange(...)` / `releaseLinuxDevPortRange(...)`，仅在 Linux 上启用系统级端口段登记与用户段复用，自动分配从 `10000-10099` 起。 - - CLI 模式：`node scripts/dev-stack-port-utils.mjs resolve-dev-stack spacetime:127.0.0.1:3101 api:127.0.0.1:8082 web:0.0.0.0:3000 adminWeb:127.0.0.1:3102`。 + - CLI 模式：`node scripts/dev-stack-port-utils.mjs resolve-dev-stack spacetime:127.0.0.1:3101 api:127.0.0.1:8082 web:0.0.0.0:3000 adminWeb:127.0.0.1:3102 bgfilterWorker:127.0.0.1:8083`。 - `scripts/dev.mjs` - 解析 CLI 参数后统一计算 client host、端口、`SPACETIME_SERVER`、`RUST_SERVER_TARGET`。 - - 完整栈按 SpacetimeDB、publish、api-server、主站 Vite、后台 Vite 顺序启动。 - - Linux 下会先申请系统级端口段并把它映射成四个 dev 端口；自动分配从 `10000-10099` 起，Windows 则直接沿用原有参数解析与端口漂移逻辑。 + - 完整栈按 SpacetimeDB、publish、BgFilter worker readiness、api-server readiness、主站 Vite、后台 Vite 顺序启动。 + - Linux 下会先申请系统级端口段并把它映射成五个 dev 端口；自动分配从 `10000-10099` 起，Windows 则把第五个服务纳入原有统一参数解析与端口漂移逻辑。 + - 完整栈和 `dev:api-server` 把两个 Rust 进程作为同一重启单元，先全部停止，再先启动 BgFilter worker、后启动 api-server；不要为同一份 Rust 源码创建两个并发 `cargo` watcher。 - 单模块命令复用同一套参数和 env 解析。 ## 必须保持的传递链路 -`npm run dev` 和四个 `dev:*` 单模块命令中端口解析后，必须同步到以下位置： +`npm run dev` 和五个 `dev:*` 单模块命令中端口解析后，必须同步到以下位置： 1. SpacetimeDB 启动：`spacetime start --listen-addr "${SPACETIME_HOST}:${SPACETIME_PORT}"`。 2. SpacetimeDB 发布：`spacetime publish ... --server "${SPACETIME_SERVER}"`。 3. Rust api-server：`GENARRATIVE_API_HOST`、`GENARRATIVE_API_PORT`、`GENARRATIVE_SPACETIME_SERVER_URL`、`GENARRATIVE_SPACETIME_DATABASE`。 4. api-server 健康检查：`wait_for_api_server "${RUST_SERVER_TARGET}/healthz" ...`。 -5. 主站 Vite：`RUST_SERVER_TARGET`、`GENARRATIVE_RUNTIME_SERVER_TARGET`、`ADMIN_WEB_TARGET`、`ADMIN_WEB_PORT`、`--port=${WEB_PORT}`、`--host=${WEB_HOST}`。 -6. 后台 Vite：`ADMIN_API_TARGET`、`GENARRATIVE_API_TARGET`、`GENARRATIVE_API_PORT`、`--port=${ADMIN_WEB_PORT}`。 -7. 控制台日志：`[dev:ports]` 和 `[dev] web/admin web/api-server/spacetime` 必须显示最终实际地址。 -8. Linux 端口段注册：`[dev] port-range:` 与 `[dev] port-range-registry:` 只在 Linux 输出，Windows 不应依赖系统级注册表。 +5. BgFilter worker：`GENARRATIVE_PROCESS_ROLE=bgfilter-worker`、解析后的 `HOST / PORT`、与父 API 相同的 `GENARRATIVE_BGFILTER_WORKER_BASE_URL` / `GENARRATIVE_BGFILTER_INTERNAL_TOKEN`，以及显式有效的 `N / Q`。 +6. BgFilter worker readiness：父 API 启动前检查解析后地址的 `/readyz`。 +7. 主站 Vite：`RUST_SERVER_TARGET`、`GENARRATIVE_RUNTIME_SERVER_TARGET`、`ADMIN_WEB_TARGET`、`ADMIN_WEB_PORT`、`--port=${WEB_PORT}`、`--host=${WEB_HOST}`。 +8. 后台 Vite：`ADMIN_API_TARGET`、`GENARRATIVE_API_TARGET`、`GENARRATIVE_API_PORT`、`--port=${ADMIN_WEB_PORT}`。 +9. 控制台日志：`[dev:ports]` 和 `[dev] web/admin web/api-server/bgfilter-worker/spacetime` 必须显示最终实际地址。 +10. Linux 端口段注册：`[dev] port-range:` 与 `[dev] port-range-registry:` 只在 Linux 输出，Windows 不应依赖系统级注册表。 如果只改了其中一段，通常会出现：浏览器打开的前端可用，但 `/api/*` 代理到旧端口；后台页面可用但后台 API 失败；SpacetimeDB 启动在新端口但 publish 仍发往旧端口。 @@ -74,7 +78,7 @@ Linux 多用户并发开发时，`GENARRATIVE_DEV_PORT_RANGE` 或 `--port-range` - `scripts/dev-stack-port-utils.mjs` - `scripts/dev.mjs` - `scripts/dev-utils.mjs` - - `docs/technical/RUST_LOCAL_AND_REMOTE_DEPLOYMENT_SCRIPTS_2026-04-22.md` + - `docs/【开发运维】本地开发验证与生产运维-2026-05-15.md` - `docs/project-memory/shared-memory/pitfalls.md` 2. 优先改公共端口工具，不要把端口探测逻辑复制到多个脚本。 3. 修改 `scripts/dev.mjs` 时确认变量顺序：先解析参数和端口，再构造 `SPACETIME_SERVER` / `RUST_SERVER_TARGET`，最后启动对应 service。 @@ -91,21 +95,21 @@ Linux 多用户并发开发时，`GENARRATIVE_DEV_PORT_RANGE` 或 `--port-range` node --check scripts/dev.mjs npm run test -- scripts/dev-stack-port-utils.test.ts npm run check:encoding -node scripts/dev-stack-port-utils.mjs resolve-dev-stack spacetime:127.0.0.1:0 api:127.0.0.1:0 web:0.0.0.0:0 adminWeb:127.0.0.1:0 +node scripts/dev-stack-port-utils.mjs resolve-dev-stack spacetime:127.0.0.1:0 api:127.0.0.1:0 web:0.0.0.0:0 adminWeb:127.0.0.1:0 bgfilterWorker:127.0.0.1:0 ``` 端口冲突回归测试建议： 1. 用测试或临时 Node server 占用某个优先端口。 2. 调用 `findAvailablePort`，断言结果大于被占用端口。 -3. 调用 `resolveDevStackPorts`，断言四个结果互不相同。 +3. 调用 `resolveDevStackPorts`，断言五个结果互不相同。 4. 如果实际启动完整栈，观察控制台： - `[dev:ports] ... 不可用，改用 ...` - `[dev] api-server: http://...:` - `[dev] spacetime: http://...:` - 主站和后台 Vite 启动端口与日志一致。 -完整启动属于长驻进程。需要 smoke 时用 background 方式启动，并另开命令检查 `/healthz`、`/v1/ping` 和页面端口；不要等待 `npm run dev` 自然退出。 +完整启动属于长驻进程。需要 smoke 时用 background 方式启动，并另开命令检查 api-server `/healthz`、BgFilter worker `/readyz`、SpacetimeDB `/v1/ping` 和两个页面端口；不要等待 `npm run dev` 自然退出。检查地址必须取 `.app/dev-stack.json` 或启动日志中的实际端口，不能假定 worker 一定停在 `8083`。 ## 常见坑 @@ -122,7 +126,8 @@ node scripts/dev-stack-port-utils.mjs resolve-dev-stack spacetime:127.0.0.1:0 ap - [ ] Linux 注册表分配、同用户复用固定段并继续漂移、自动分配从 `10000-10099` 起、Windows bypass 都有测试覆盖。 - [ ] `scripts/dev.mjs` 通过 `node --check`。 - [ ] `npm run dev` 的 SpacetimeDB、publish、api-server、主站 Vite、后台 Vite 都使用实际端口。 +- [ ] BgFilter worker 在 api-server 前 ready，父子共享实际 base URL / Token，Rust watch 只触发一次组合重启。 - [ ] `npm run dev:web` 在主站端口不可用时能切换到可用端口。 -- [ ] 文档同步更新 `docs/technical/RUST_LOCAL_AND_REMOTE_DEPLOYMENT_SCRIPTS_2026-04-22.md`。 +- [ ] 文档同步更新 `docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。 - [ ] 长期踩坑同步更新 `docs/project-memory/shared-memory/pitfalls.md`。 - [ ] 修改中文文件后运行 `npm run check:encoding`。 diff --git a/README.md b/README.md index 71aa2ac89..d5ee527a1 100644 --- a/README.md +++ b/README.md @@ -44,10 +44,10 @@ npm run dev 补充说明： -- `npm run dev` 会启动 SpacetimeDB standalone、Rust `api-server`、主站 Vite 与后台 Vite，适合完整联调。 +- `npm run dev` 会启动 SpacetimeDB standalone、独立 `bgfilter-worker`、Rust `api-server`、主站 Vite 与后台 Vite，适合完整联调；内部 worker ready 后才启动 API。 - 主站默认地址是 `http://127.0.0.1:3000`，后台可从 `http://127.0.0.1:3000/admin/` 进入，也可直连 `http://127.0.0.1:3102`。 -- 四个模块可独立启动：`npm run dev:spacetime`、`npm run dev:api-server`、`npm run dev:web`、`npm run dev:admin-web`。 -- 如需自动刷新后端模块，使用 `npm run dev -- --watch`；其中 `spacetime-module` 改动后只会重新发布模块，不会重启 standalone，`api-server` 改动后会重启 Rust 进程。主站和后台前端源码变化交给 Vite 自身 HMR，不由外层 watcher 重启。非 watch 模式下可在 `npm run dev` 终端输入 `rs api-server`、`rs web`、`rs admin-web`、`rs spacetime` 或 `rs all`，其中 `rs spacetime` 也是只重新发布模块。 +- 五个模块可独立启动：`npm run dev:spacetime`、`npm run dev:api-server`、`npm run dev:bgfilter-worker`、`npm run dev:web`、`npm run dev:admin-web`；其中 `dev:api-server` 会安全带起同 runner 的 BgFilter worker 依赖。 +- 如需自动刷新后端模块，使用 `npm run dev -- --watch`；其中 `spacetime-module` 改动后只会重新发布模块，不会重启 standalone，Rust 源码改动会把 `api-server` 与 `bgfilter-worker` 作为一个组合单元重启。主站和后台前端源码变化交给 Vite 自身 HMR，不由外层 watcher 重启。非 watch 模式下可在 `npm run dev` 终端输入 `rs api-server`、`rs bgfilter-worker`、`rs web`、`rs admin-web`、`rs spacetime` 或 `rs all`，其中 `rs spacetime` 也是只重新发布模块。 构建生产包： diff --git a/deploy/container/README.md b/deploy/container/README.md index 67c4dded3..10ae56971 100644 --- a/deploy/container/README.md +++ b/deploy/container/README.md @@ -1,6 +1,6 @@ # Genarrative 容器化压测、隔离部署与 CI Job 镜像 -本目录同时保存两类互不替代的容器资产：本机或预发的容器化模拟压测，以及 Gitea Actions 使用的预构建 CI job 镜像。它们都不替换当前生产 `systemd + Nginx + Jenkins` 发布路径；生产服务器仍以 `deploy/systemd/`、`deploy/nginx/`、`scripts/jenkins-*.sh` 和 `scripts/deploy/production-api-deploy.sh` 为准。 +本目录同时保存两类互不替代的容器资产：本机或预发的容器化模拟压测，以及 Gitea Actions 使用的预构建 CI job 镜像。它们都不替换当前生产 `systemd + Nginx + Jenkins` 发布路径；生产服务器仍以 `deploy/systemd/`、`deploy/nginx/`、`scripts/jenkins-*.sh` 和 `scripts/deploy/production-api-deploy.sh` 为准。当前 compose 不包含独立 `bgfilter-worker`，因此不是完整 BgFilter 预发拓扑，也不覆盖会触发 BgFilter 的现役任务；这里只验证非 BgFilter 路径，或使用 unsupported job 检查队列 claim / fail 回写和 API / worker 进程隔离。 ## 拓扑 @@ -15,7 +15,7 @@ Docker Compose 当前容器模拟参数按 `genarrative-release` 服务器采样值收口为 2 vCPU / 2 GiB RAM / 4096 soft nofile / 768 worker_connections，并已在 compose 里落实到 `spacetimedb cpus=1.0 mem_limit=896m`、`api-server cpus=2.0 mem_limit=1g`、`external-generation-worker cpus=2.0 mem_limit=1g`、`nginx cpus=0.5 mem_limit=128m`、`otelcol cpus=0.25 mem_limit=128m`。SpacetimeDB 同时设置 `--page_pool_max_size=402653184`，给 reducer、订阅与运行时保留更多非 page pool 内存。 容器 `api-server` 默认 `GENARRATIVE_API_WORKER_THREADS=4`，用于让 Tokio 在 2 vCPU 配额内有更多 I/O 调度 worker；该值不会突破 compose 里的 `cpus=2.0` CPU 上限。 -容器默认 `GENARRATIVE_EXTERNAL_GENERATION_MODE=queue`，用于验证 `api-server -> external_generation_job -> external-generation-worker` 链路；如只想本地同步排查 provider/OSS/SpacetimeDB 写回，可在本机 env 临时改为 `inline`，但该模式不会覆盖 worker 动态扩缩容验证。 +容器默认 `GENARRATIVE_EXTERNAL_GENERATION_MODE=queue`，用于验证不经过 BgFilter 的 `api-server -> external_generation_job -> external-generation-worker` 链路；会触发 BgFilter 的任务不属于当前 compose 验收范围。如只想本地同步排查非 BgFilter provider / OSS / SpacetimeDB 写回，可在本机 env 临时改为 `inline`，但该模式不会覆盖 worker 动态扩缩容验证。 Collector 镜像使用 `otel/opentelemetry-collector-contrib:0.151.0`。 生产服务器若启用 Collector，则由 `deploy/systemd/otelcol-contrib.service` 和 `deploy/otelcol/genarrative-debug.yaml` 托管，不走容器镜像。 diff --git a/deploy/container/api-server.env.example b/deploy/container/api-server.env.example index e70045834..6dddc3e82 100644 --- a/deploy/container/api-server.env.example +++ b/deploy/container/api-server.env.example @@ -30,9 +30,10 @@ GENARRATIVE_WALLET_REFUND_OUTBOX_DIR=/var/lib/genarrative/wallet-refund-outbox GENARRATIVE_WALLET_REFUND_OUTBOX_BATCH_SIZE=100 GENARRATIVE_WALLET_REFUND_OUTBOX_FLUSH_INTERVAL_MS=1000 GENARRATIVE_WALLET_REFUND_OUTBOX_MAX_BYTES=67108864 -GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS=180000 +GENARRATIVE_BGFILTER_WORKER_CONCURRENCY=16 +GENARRATIVE_EDITOR_BGFILTER_SINGLE_IMAGE_ESTIMATE_MS=5000 GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD=3 -GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS=300 +GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS=120 # BgFilter 失败后的中间兜底：阿里云通用抠图（SegmentCommonImage）。AccessKey 留空则跳过该层， # BgFilter 失败直接本地 editor_green_screen 去背；填入后恢复 BgFilter→阿里云→本地三级兜底。 # AccessKey 也可复用标准 SDK 命名 ALIBABA_CLOUD_ACCESS_KEY_ID / ALIBABA_CLOUD_ACCESS_KEY_SECRET。 diff --git a/deploy/env/api-server.env.example b/deploy/env/api-server.env.example index c254b1868..0bcee9522 100644 --- a/deploy/env/api-server.env.example +++ b/deploy/env/api-server.env.example @@ -17,6 +17,10 @@ GENARRATIVE_EXTERNAL_GENERATION_WORKER_POLL_INTERVAL_MS=2000 GENARRATIVE_EXTERNAL_GENERATION_WORKER_LEASE_SECONDS=600 GENARRATIVE_EXTERNAL_GENERATION_WORKER_JOB_TIMEOUT_SECONDS=900 GENARRATIVE_EXTERNAL_GENERATION_WORKER_LONG_JOB_TIMEOUT_SECONDS=1800 +# 父流程只访问同机 BgFilter worker；内部 Token 只通过受保护文件共享，不写明文 env。 +GENARRATIVE_BGFILTER_WORKER_BASE_URL=http://127.0.0.1:8083 +GENARRATIVE_BGFILTER_INTERNAL_TOKEN_FILE=/etc/genarrative/secrets/bgfilter-worker.token +GENARRATIVE_BGFILTER_WORKER_CONNECT_TIMEOUT_MS=2000 GENARRATIVE_API_MAX_CONCURRENT_REQUESTS=512 GENARRATIVE_API_ADMIN_MAX_CONCURRENT_REQUESTS=16 GENARRATIVE_API_SHUTDOWN_OUTBOX_FLUSH_TIMEOUT_MS=5000 @@ -30,9 +34,12 @@ GENARRATIVE_WALLET_REFUND_OUTBOX_DIR=/var/lib/genarrative/wallet-refund-outbox GENARRATIVE_WALLET_REFUND_OUTBOX_BATCH_SIZE=100 GENARRATIVE_WALLET_REFUND_OUTBOX_FLUSH_INTERVAL_MS=1000 GENARRATIVE_WALLET_REFUND_OUTBOX_MAX_BYTES=67108864 -GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS=180000 -GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD=3 -GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS=300 +# N 与单图估时：父子共同派生 attempt = N×est×2、callBudget = 2×attempt+1s 的公式输入； +# 单一来源放共享 env，专属 worker env 不重复定义。旧固定 REQUEST_TIMEOUT_MS 已删除。 +GENARRATIVE_BGFILTER_WORKER_CONCURRENCY=16 +GENARRATIVE_EDITOR_BGFILTER_SINGLE_IMAGE_ESTIMATE_MS=5000 +GENARRATIVE_EDITOR_BGFILTER_BASE_URL=http://58.87.105.82/bgfilter +GENARRATIVE_EDITOR_BGFILTER_TOKEN= # BgFilter 失败后的中间兜底：阿里云通用抠图（SegmentCommonImage）。AccessKey 留空则跳过该层， # BgFilter 失败直接本地 editor_green_screen 去背；填入后恢复 BgFilter→阿里云→本地三级兜底。 # AccessKey 也可复用标准 SDK 命名 ALIBABA_CLOUD_ACCESS_KEY_ID / ALIBABA_CLOUD_ACCESS_KEY_SECRET。 diff --git a/deploy/env/bgfilter-worker.env.example b/deploy/env/bgfilter-worker.env.example new file mode 100644 index 000000000..376fc922d --- /dev/null +++ b/deploy/env/bgfilter-worker.env.example @@ -0,0 +1,18 @@ +# 复制到 /etc/genarrative/bgfilter-worker.env；只放专用进程独占参数和可选日志覆盖。 +# provider、OSS、内部 Token 文件、N（CONCURRENCY）与单图估时统一来自先加载的 api-server.env，禁止在此重复定义。 +# systemd unit 会强制设置 GENARRATIVE_PROCESS_ROLE=bgfilter-worker。 + +GENARRATIVE_ENV=production +GENARRATIVE_BGFILTER_WORKER_HOST=127.0.0.1 +GENARRATIVE_BGFILTER_WORKER_PORT=8083 +# Q：admission 保险丝，只防连接风暴；正常业务不应触达，显式配置时必须 >= N。 +GENARRATIVE_BGFILTER_WORKER_MAX_REQUESTS=2048 +# flat / complex 熔断只由本进程维护；两种模式共享参数，但状态互相独立。 +GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD=3 +GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS=120 + +GENARRATIVE_API_LOG=info,tower_http=info +GENARRATIVE_OTEL_ENABLED=true +OTEL_SERVICE_NAME=genarrative-bgfilter-worker +OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318 +OTEL_RESOURCE_ATTRIBUTES=deployment.environment=production,service.namespace=genarrative diff --git a/deploy/env/health-patrol.env.example b/deploy/env/health-patrol.env.example index b1b9799e5..1528b17ae 100644 --- a/deploy/env/health-patrol.env.example +++ b/deploy/env/health-patrol.env.example @@ -2,6 +2,9 @@ # 默认不启用 Pingora shadow 巡检；只有同时配置 base URL 与 probe token 才会检查。 GENARRATIVE_HEALTH_PATROL_API_BASE_URL=http://127.0.0.1:8082 +# 巡检是独立进程，不读取 bgfilter-worker.env；若自定义了 GENARRATIVE_BGFILTER_WORKER_PORT， +# 必须在此同步改为相同端口，否则巡检会持续误报 worker 不健康。 +GENARRATIVE_HEALTH_PATROL_BGFILTER_BASE_URL=http://127.0.0.1:8083 GENARRATIVE_HEALTH_PATROL_SPACETIME_BASE_URL=http://127.0.0.1:3101 GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL=http://127.0.0.1 # 默认公网入口仍按 Nginx 巡检；Pingora 直连切换后改为 pingora-direct。 diff --git a/deploy/systemd/genarrative-bgfilter-worker.service b/deploy/systemd/genarrative-bgfilter-worker.service new file mode 100644 index 000000000..99b7d3f38 --- /dev/null +++ b/deploy/systemd/genarrative-bgfilter-worker.service @@ -0,0 +1,30 @@ +[Unit] +Description=Genarrative BgFilter Worker +After=network-online.target +Wants=network-online.target + +[Service] +Type=simple +User=genarrative +Group=genarrative +WorkingDirectory=/opt/genarrative/current +EnvironmentFile=/etc/genarrative/api-server.env +EnvironmentFile=/etc/genarrative/bgfilter-worker.env +Environment="LD_LIBRARY_PATH=/opt/genarrative/openssl-3.2.0/lib64:/opt/genarrative/openssl-3.2.0/lib" +ExecStart=/usr/bin/env GENARRATIVE_PROCESS_ROLE=bgfilter-worker OTEL_SERVICE_NAME=genarrative-bgfilter-worker /opt/genarrative/current/api-server +Restart=always +RestartSec=5 +KillSignal=SIGINT +# shutdown 会立即拒绝仍在排队的请求，只排空已取得 provider permit 的调用；默认 N=16、est=5000ms 时 callBudgetMs=321s，额外窗口用于响应发送和进程收口。 +TimeoutStopSec=900 +LimitNOFILE=65535 +TasksMax=2048 + +# 固定 loopback 地址与非模板 unit 共同保证首版同机只运行一个 BgFilter worker。 +NoNewPrivileges=true +PrivateTmp=true +ProtectSystem=full +ReadWritePaths=/opt/genarrative /var/lib/genarrative + +[Install] +WantedBy=multi-user.target diff --git a/docs/README.md b/docs/README.md index d8911947e..5b8222abc 100644 --- a/docs/README.md +++ b/docs/README.md @@ -27,6 +27,7 @@ ### 后端与公开数据 - [外部生成 Worker 化方案](./technical/【后端架构】外部生成Worker化方案-2026-06-03.md) +- [BgFilter 受限资源调度方案（同步内部 HTTP 原地等待版）](./technical/【后端架构】BgFilter受限资源调度方案-2026-07-21.md) - [统一公开作品 Read Model 设计](./technical/【后端架构】统一公开作品ReadModel设计-2026-05-26.md) - [外部 OpenAPI 与 API Key 接入方案](./【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md) - [SpacetimeDB 连接池取消安全](./【后端架构】SpacetimeDB连接池租约Drop兜底与取消安全-2026-06-11.md) diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index c15f60da9..8604b6bdc 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -16,6 +16,38 @@ --- +## 2026-07-23 BgFilter 失败审计使用硬上限与独立 tracking outbox + +- 背景：BgFilter worker 每个已发出的失败 provider attempt 都会启动 detached 审计任务；专用 worker 又关闭了 tracking outbox，使任务逐条等待 SpacetimeDB。`Q` 只约束内部 HTTP 请求生命周期，响应结束后无法限制仍在等待数据库的审计任务，部分失败、预算截短 timeout、重试恢复和熔断重置场景下可能持续堆积。 +- 决策：BgFilter worker 的失败审计在 `tokio::spawn` 前统一获取进程级 `1024` 个硬上限 permit，满载时直接丢弃并记录低基数指标，不创建等待任务。获准任务优先写入 worker 独立 tracking outbox，目录固定派生为共享 `GENARRATIVE_TRACKING_OUTBOX_DIR` 下的 `bgfilter-worker/` 子目录；worker 启动 outbox flush worker，退出时先排空已获准审计 enqueue，再封存并尽力 flush。BgFilter 专用策略在 outbox 缺失、容量拒绝或写盘失败时丢弃并观测，不回退同步直写 SpacetimeDB；其它外部 API 审计保持原有 fallback 语义。 +- 影响范围：`api-server` BgFilter worker、外部 API 失败审计策略、tracking outbox 进程接线、指标与测试、BgFilter 架构和开发运维文档；不修改 SpacetimeDB schema、procedure、bindings、前端或公开 DTO。 +- 验证方式：覆盖 spawn 前容量拒绝、flat / complex 共享总上限、permit 生命周期、独立 outbox 目录、outbox 满载 / 写盘失败不直写、SpacetimeDB 不可用时任务与磁盘保持有界，以及退出时 tracker drain 后再 flush；运行 api-server 定向测试、BgFilter fault smoke、Rust check、编码和 diff 检查。 +- 关联文档：`docs/technical/【后端架构】BgFilter受限资源调度方案-2026-07-21.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。 + +--- + +## 2026-07-22 BgFilter flat 与 complex 使用独立熔断状态 + +- 背景：complex 请求在 provider 持续快速失败时仍会不断发起真实 provider attempt，并为每次已发出的失败生成异步审计；现有 flat 熔断不能约束 complex，且五分钟冷却会让短暂故障恢复后的等待过长。 +- 决策：把现有 flat 熔断行为按原语义复用到 complex。flat / complex 共享 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD=3` 与 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS=120`，但在唯一 `bgfilter-worker` 内分别维护独立的连续失败数和打开截止时间；真实 provider attempt 的失败或成功只更新当前模式。两种模式都在排队前及取得 provider permit 后、第一次真实 HTTP 前检查自身熔断；已经通过第二次检查的逻辑调用仍可完成自己的第二次顺序 attempt。complex 熔断仍直接使父流程失败，不获得 flat 的阿里云 / 本地 fallback；本次不修改失败审计的异步处理流程。 +- 部署边界：deploy / Provision 将 worker env 中历史模板默认 cooldown `300` 定向迁移到 `120`，其它显式自定义值保持不变；`bgfilter_circuit_state` 分别上报 `mode=flat` 与 `mode=complex`。 +- 影响范围：`api-server` BgFilter worker、熔断指标与测试、worker 环境模板、生产部署迁移门禁、BgFilter 架构和运维文档；不修改 SpacetimeDB schema、父业务 fallback、计费或失败审计流程。 +- 验证方式：覆盖两种模式状态隔离、阈值、成功重置、cooldown 到期、permit 前二次检查和部署默认值迁移；运行 api-server BgFilter 定向测试、生产部署脚本门禁、编码检查与 diff 检查。 +- 关联文档：`docs/technical/【后端架构】BgFilter受限资源调度方案-2026-07-21.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。 + +## 2026-07-21 BgFilter 首版采用单实例同步内部 HTTP 与父流程原地等待 + +- 背景：角色动画在单个 `external_generation_job` 内通过 `buffer_unordered(frame_count)` 可并发发射最多 `48` 次 BgFilter 请求；限制父 worker 并发不能限制单个父 job 内的实际 BgFilter 并发。父 job checkpoint / continuation 和 SpacetimeDB 持久子任务都会扩大父状态机、attempt、计费、恢复和清理改动，而当前 BgFilter 成功结果本来就是 HTTP 图片二进制。 +- 决策：父 future 保持原调用栈、lease 和 attempt，等待期间继续占用通用 worker 槽并由现有 heartbeat 续租；所有调用统一同步请求唯一 `bgfilter-worker` 的内部 loopback HTTP。输入只传 OSS object key、参数、`maxQueueWaitMs / callBudgetMs` 和有界审计关联，成功直接返回经过校验的图片二进制。子 worker 使用有界 admission `Q` 和进程内 `Semaphore(N)`，负责最多两次顺序 provider attempt、flat 进程级熔断和失败审计；父流程继续负责 flat 降级、complex 失败、Alpha / 尺寸恢复、动画 finalizer、最终 OSS、业务写回、计费和父终态。 +- 超时边界：父 job 总预算仍为普通 `900s` / 长任务 `1800s`，并保留现有 `60s` 终态写回窗口。内部协议拆成互不挪用的 `maxQueueWaitMs` 与 `callBudgetMs`：前者由父剩余绝对预算扣除调用预算和父侧预留后派生，只限制等待 provider permit；flat 的 `39s` 父侧预留由 `37s` fallback（阿里云 `30s` + 本地 `7s`）与 `2s` 传输窗组成，complex 只留 `2s` 传输窗。后者从取得 permit 后起算，覆盖签名、最多两次 attempt、结果校验和响应构造。provider attempt 上限按 `N × est × 2` 派生，调用预算按 `2 × attempt + 1s` 派生；额外 `1s` 吸收 attempt 间开销，只要剩余时间仍能容纳完整 attempt 就不得先扣响应预留。父内部 client timeout 精确取 `maxQueueWaitMs + callBudgetMs + 2s`，不在发送阶段重新裁剪两笔相对预算。冻结 `N=16`、`est=5000ms` 时 attempt / callBudget 分别为 `160s / 321s`。动画删除旧的按帧数 timeout 增量，父侧不得在内部 timeout / 断连后重试整次 RPC。 +- 故障边界：首版不新增 `bgfilter_task_group`、`bgfilter_request_task`、raw OSS、checkpoint、continuation、数据库 capacity slot、共享熔断或 QPS token bucket。父或子进程崩溃、RPC 丢失时不查询、不恢复结果；父 job 沿用现有 lease / `max_attempts=1` 失败退款语义。动画首版保持所有已提交帧 collect / drain，不增加跨帧取消组。 +- 部署边界：专用进程首版仍复用完整 `AppState`，因此 systemd unit 先加载共享 `/etc/genarrative/api-server.env`，再加载 `/etc/genarrative/bgfilter-worker.env` 覆盖 worker 独占参数；父子共同依赖的 `N=16` 与 `est=5000ms` 必须来自共享基础环境，worker 专属环境只管理 flat 熔断参数和默认 `Q=2048` 保险丝。发布切换前校验父子使用同一个非空、非符号链接、`root:genarrative 0440` 的内部 Token 文件，并拒绝父子内部 URL、Token、连接参数、`N / est`、OSS bucket 或 endpoint 漂移（同 bucket 的独立 AK 允许）。worker 停机时立即拒绝仍在排队的请求，只排空已取得 provider permit 的调用；unit 使用 `TimeoutStopSec=900` 覆盖默认 `321s` 调用预算及响应收口。运行期巡检同时检查唯一 worker unit active 与 loopback readiness；本地 `npm run dev` 同样启动独立子进程并解析第五个 dev 端口，`ProcessRole::All` 不内嵌 listener。 +- 影响范围：已实施范围包括 `api-server` 内部 HTTP client、专用 `bgfilter-worker` listener / process role、并发与超时配置、部署和运维观测；未修改 SpacetimeDB schema、父 job schema、用户任务 DTO、任务列表或收费归属，当前待生产压测后启用。 +- 验证方式：`48` 帧并发进入父 future 时，健康唯一子 worker 进程持有的 BgFilter HTTP future 峰值不得超过生产显式配置的 `N`，且 `queued + running + egress` 不超过 `Q`（admission permit 持有到 response body 发送完成或 drop）；覆盖 flat / complex 降级矩阵、内部 deadline、断连后已启动请求排空、动画全帧 drain、External v1 / inline 旁路扫描、二进制大小 / MIME / 尺寸门禁、单实例部署、DDD、编码和 diff 门禁。 +- 关联文档：`docs/technical/【后端架构】BgFilter受限资源调度方案-2026-07-21.md`、`docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。 + +--- + ## 2026-07-20 角色动作抠图前禁止透明 padding - 背景：图片画布角色动作此前在 BgFilter 前复用最终帧 finalizer，把 FFmpeg 抽帧先转成目标尺寸 RGBA 画布并用透明黑像素补边；透明区域进入 BgFilter、阿里云和本地键色共同读取的 OSS 源帧后，会干扰主体边缘判断并降低抠图质量。 @@ -112,6 +144,8 @@ ## 2026-07-15 BgFilter 输入改用私有 OSS 短期签名 URL +> 后续更正（2026-07-21）：复用 object key、通过 `image_url` 提交且不传 `file` 的协议语义保留，但 600 秒 OSS GET URL 的签发和 BgFilter provider multipart 调用已迁入唯一 `bgfilter-worker`。父流程只向内部 worker 发送一次 object key、参数和剩余预算，不签发 BgFilter URL，也不重试已被 worker 接收的内部 RPC（2026-07-23 起：连接从未建立的失败按调度方案 §5.1 有界重连，见当日决策条目）。下文保留作历史记录。 + - 背景：角色形象、图标图集、UI 素材图集、角色动作抽取帧和手动去背景在调用 BgFilter 前都已有私有 OSS object key；继续由 api-server 下载或保留图片并作为 multipart `file` 再上传，会重复传输图片字节并占用 API 进程网络与内存。 - 决策：上述抠图链路统一复用 object key，签发 600 秒 OSS GET URL，并通过 BgFilter multipart 的 `image_url` 字段提交；请求中不再携带 `file`。签名 URL 只交给 BgFilter，不写日志或持久化。2026-07-17 起，生成原图和动作帧上传后不再保留图片字节；进入“阿里云通用抠图 → 本地键色”兜底链时按阶段从私有 OSS 重新下载。 - 影响范围：`server-rs/crates/api-server/src/editor_project.rs`、`server-rs/crates/api-server/src/character_animation_assets.rs`、相关测试与文档；不改变 BgFilter endpoint、鉴权、`screen_color`、`seg_model`、输出校验、熔断规则、阿里云上传协议或降级顺序。 @@ -127,6 +161,8 @@ ## 2026-07-15 角色动作 BgFilter 请求超时按帧数扩展 +> 后续更正（2026-07-21）：本条按帧数增加 timeout 的决策已被 2026-07-21「BgFilter 首版采用单实例同步内部 HTTP 与父流程原地等待」的公式化双预算取代。当前每帧分别携带 `maxQueueWaitMs` 与 `callBudgetMs`：排队预算只约束等待 provider permit，取得 permit 后才启动调用预算；provider attempt 按 `N × est × 2`、调用预算按 `2 × attempt + 1s` 运行时派生，冻结 `N=16`、`est=5000ms` 时为 `160s / 321s`，不再按 `32 / 40 / 48` 帧扩展。下文保留作历史记录。 + - 背景：角色动作全部序列帧会并发进入 BgFilter，而服务端可能在自身进程内排队；固定 `180000ms` 会把排队时间和单帧推理共用同一预算，靠后的请求可能在服务仍正常处理时被 api-server 提前取消。 - 决策：保留 `GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS` 作为统一基准值。只有角色动作逐帧 BgFilter 在共享 Client 的 RequestBuilder 上把每一次 HTTP attempt 覆盖为“基准值 + `2000ms × 本次实际帧数`”，默认 `32 / 40 / 48` 帧为 `244000 / 260000 / 276000ms`；角色形象单图、图标、UI 和手动去背景不增加帧预算。该 timeout 覆盖请求发起到响应体读取完成；首次失败后的重试重新获得同样的 request deadline，整批并发策略、失败排空语义和 worker long-job 总预算不变。 - 影响范围：`server-rs/crates/api-server/src/editor_project.rs`、`server-rs/crates/api-server/src/character_animation_assets.rs`、后端架构、开发运维和图片画布专题文档。 @@ -135,6 +171,8 @@ ## 2026-07-15 手动复杂去背景复用 BgFilter 单次重试 +> 后续更正（2026-07-21）：首次失败后再尝试一次、即同一次 complex 逻辑调用最多两次顺序 provider attempt 的语义保留，但重试所有权已迁入唯一 `bgfilter-worker`。父 `external-generation-worker` 至多让 worker 接收一次内部 HTTP RPC，不重试已被接收的 RPC（2026-07-23 起：连接从未建立的失败按调度方案 §5.1 有界重连，见当日决策条目）；两次 provider attempt 都失败时，子 worker 把最终类型化错误返回父流程，complex 仍不接入 flat 的阿里云 / 本地 fallback。下文所称“worker 重试”按此边界理解。 + - 背景：图片画布手动去背景已经改用 BgFilter `background_mode=complex`，但 worker 仍只发送一次上游请求，短暂网络抖动会直接让任务失败。 - 决策：手动去背景的 complex 请求复用现有 `EDITOR_BGFILTER_RETRY_COUNT=1`，首次请求失败后立即重试一次，两次都失败仍返回最终错误；本次不把手动 complex 接入标准纯色背景链路的阿里云 / 本地兜底，也不改变 flat 路径的熔断状态。 - 影响范围：图片画布手动去背景 worker、BgFilter complex 请求日志和 api-server 定向测试。 @@ -169,6 +207,8 @@ ## 2026-07-13 角色动作 BgFilter 全帧流水线与单次重试 +> 后续更正（2026-07-23）：本条「每次 BgFilter 调用失败后立即重试 1 次」与「不新增供应商进程锁或全局 Semaphore」已被 2026-07-21 起的唯一 `bgfilter-worker` 架构取代。重试所有权迁入子 worker：对一次逻辑调用最多两次顺序 provider attempt，provider 并发由 worker 进程内 `Semaphore(N)`（生产 `N=16`）约束；父侧不重试已被 worker 接收的内部 RPC，仅 TCP 连接从未建立的失败按调度方案 §5.1 有界重连（见 2026-07-23「BgFilter 父侧连接失败有界重连与冷启动宽限」条目）。全帧独立流水化、失败排空与整任务失败退款的语义保留。下文保留作历史记录。 + - 背景：角色动作抽帧后原先固定 `buffered(3)`，并在整批绿幕源帧串行落 OSS 后才开始抠图；每帧还单独创建 HTTP Client。公网 BgFilter 的网络等待会让服务端推理队列出现空档，且首个最终错误会通过 `try_collect` 提前取消 api-server 中其余已发 Future。 - 决策：BgFilter HTTP Client 在 `AppState` 中统一创建并复用 keep-alive 连接池；每次 BgFilter 调用失败后立即重试 `1` 次，两次都失败才进入既有“阿里云通用抠图 → 本地键色”降级链，每次已发失败调用都保留审计。角色动作全部 `32 / 40 / 48` 帧按“单帧绿幕源图落 OSS → BgFilter/降级 → 透明帧落 OSS”独立流水化，使用覆盖本次全部帧的 `buffer_unordered` 连续发射并携带原始帧序，完成后排序；不在 api-server 新增供应商进程锁或全局 Semaphore。任一帧最终失败时先排空全部已启动 Future，再让整个动作任务失败退款，不发布缺帧动画。 - 影响范围：`server-rs/crates/api-server/src/state.rs`、`server-rs/crates/api-server/src/editor_project.rs`、`server-rs/crates/api-server/src/character_animation_assets.rs`、后端架构文档和图片画布技术文档。 @@ -355,7 +395,7 @@ ## 2026-07-03 图片画布生成纯色背景资产接入 BgFilter -> 后续更正：本条关于 multipart `file`、手动去背景独立 BiRefNet 配置以及 BgFilter 失败后直接本地兜底的描述，已分别由 2026-07-14、2026-07-15 OSS 签名 URL 决策和 2026-07-17 内存生命周期决策取代。下文保留作历史记录。 +> 后续更正：本条关于 multipart `file`、手动去背景独立 BiRefNet 配置以及 BgFilter 失败后直接本地兜底的描述，已分别由 2026-07-14、2026-07-15 OSS 签名 URL 决策和 2026-07-17 内存生命周期决策取代；其中固定 provider timeout 配置也已被 2026-07-21 的公式化双预算取代，当前请求分别携带 `maxQueueWaitMs / callBudgetMs`，attempt 按 `N × est × 2` 派生，冻结 `N=16 / est=5000ms` 时为 `160s`，调用预算为 `321s`。下文保留作历史记录。 - 背景：独立 BgFilter 服务已部署在 image host，并提供 `POST /bgfilter/remove-background`，支持显式 `screen_color` 和 `seg_model`。手动去背景已有独立 BiRefNet BFF，不能把两个服务的配置或语义混在一起。 - 决策：角色形象生成、图标 spritesheet 生成和 UI 设计图素材提取在保存带纯色背景源图后，统一调用 BgFilter 生成透明 PNG；请求 multipart 字段为 `file`、`screen_color=` 和内部固定的 `seg_model=birefnet`。`segModel` 虽是后端可识别的内部兼容字段（另保留 `anime-seg`），但不向用户或外部 OpenAPI 暴露：当前 BgFilter 的内存与并发容量不适合由调用方自由切换模型。BgFilter 使用独立配置 `GENARRATIVE_EDITOR_BGFILTER_BASE_URL`、`GENARRATIVE_EDITOR_BGFILTER_TOKEN`、`GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS`，默认 base URL 为 `http://58.87.105.82/bgfilter`，默认请求超时 `180000ms`，token 未配置时复用 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN`。手动 `POST /api/editor/images/background-removals` 继续使用独立 BiRefNet 配置 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_BASE_URL`，不受 BgFilter 影响。BgFilter 参数里的 `seg_model=birefnet` 只表示 BgFilter 内部分割后端，不等于手动去背景的独立 BiRefNet 服务。若 BgFilter 失败，api-server 对这些标准纯色背景生成图使用本地 `editor_green_screen` 兜底；连续失败达到 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD`（默认 `3`）后，`GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS`（默认 `300`）内直接本地兜底。角色动作背景色和抠帧口径已由 2026-07-09 决策取代：角色动作同样使用多色自动决策，抽帧后优先阿里云通用抠图，失败再按选定背景色本地兜底。更正（截至 2026-07-10 实现）：BgFilter 失败与熔断期本条描述的「直接本地兜底」已过时——角色形象/图标/UI 三条静态生图链路同样先走阿里云通用抠图，仅阿里云也失败才本地 `editor_green_screen` 兜底。 @@ -1726,7 +1766,7 @@ ## 2026-05-30 Linux 本地 dev 端口段按系统级注册表分配 - 背景：同一台 Linux 开发机上有多个用户同时跑 `npm run dev` 时，单纯靠各自 `GENARRATIVE_DEV_PORT_RANGE` 容易撞段，且同一用户并发起两个 dev 会话时也会把相同端口段重复拿走。 -- 决策：Linux 上的本地 dev 端口段分配统一收口到系统级注册表 `/var/tmp/genarrative-dev-port-ranges/registry.json`，锁文件为 `/var/tmp/genarrative-dev-port-ranges/registry.lock`，可通过 `GENARRATIVE_DEV_PORT_RANGE_REGISTRY_DIR` 覆盖目录。未手动指定时自动从 `10000-10099` 开始按 100 端口块分配，后续块按 `10100-10199`、`10200-10299` 递增；端口段映射固定为 `web = start`、`api = start + 1`、`spacetime = start + 2`、`admin-web = start + 3`；注册表会拒绝不同用户的相同或重叠段，并让同一用户后续启动继续复用自己已占用的固定段。`GENARRATIVE_DEV_PORT_RANGE` 与 `--port-range` 仍可手动指定端口段，但只在 Linux 生效，Windows 继续沿用原有端口探测与漂移逻辑，不读注册表。 +- 决策：Linux 上的本地 dev 端口段分配统一收口到系统级注册表 `/var/tmp/genarrative-dev-port-ranges/registry.json`，锁文件为 `/var/tmp/genarrative-dev-port-ranges/registry.lock`，可通过 `GENARRATIVE_DEV_PORT_RANGE_REGISTRY_DIR` 覆盖目录。未手动指定时自动从 `10000-10099` 开始按 100 端口块分配，后续块按 `10100-10199`、`10200-10299` 递增；端口段最初映射为 `web = start`、`api = start + 1`、`spacetime = start + 2`、`admin-web = start + 3`，2026-07-21 按顶部 BgFilter 决策扩展 `bgfilter-worker = start + 4`；注册表会拒绝不同用户的相同或重叠段，并让同一用户后续启动继续复用自己已占用的固定段。`GENARRATIVE_DEV_PORT_RANGE` 与 `--port-range` 仍可手动指定端口段，但只在 Linux 生效，Windows 继续沿用统一端口探测与漂移逻辑，不读注册表。 - 影响范围：`scripts/dev-stack-port-utils.mjs`、`scripts/dev.mjs`、`scripts/dev-stack-port-utils.test.ts`、`scripts/dev.test.ts`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、本条决策记录、`development-workflow.md`。 - 验证方式：`node --check scripts/dev-stack-port-utils.mjs`、`node --check scripts/dev.mjs`、`node node_modules/vitest/vitest.mjs run scripts/dev-stack-port-utils.test.ts scripts/dev.test.ts` 通过；Linux 下能看到 `[dev] port-range:` 与 `registry.json` 路径日志，自动分配从 `10000-10099` 起步，Windows 不出现注册表分配日志。 - 关联文档：`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。 @@ -4398,6 +4438,22 @@ - 影响范围：`.gitea/workflows/project-ci.yml`、`deploy/container/gitea-ci-job.Dockerfile`、`scripts/gitea-ci-job-image.sh`、`scripts/check-gitea-ci-job-image.sh`、`scripts/check-gitea-ci-job-runtime.sh`、runner label/config 和 Gitea CI 运维文档。 - 验证方式：构建脚本校验宿主与 runner 内层 Image ID 一致；环境脚本校验 Node、Rust、`rustfmt`、Chrome、bwrap、原生命令与 pkg-config 依赖；runtime 脚本执行完整 bwrap 和 Chrome headless canary；真实 PR 的四个 job 全部通过，同时复核 `Privileged=false`、`Binds=[]`、`MaskedPaths=[]`、`ReadonlyPaths=[]` 和独立网络。 +## 2026-07-23 BgFilter 父侧连接失败有界重连与冷启动宽限 + +- 背景：主机重启或 worker 崩溃拉起期间，父侧对 loopback BgFilter worker 的 TCP 连接失败此前直接映射 `internal_error`：complex（队列 `max_attempts=1`）终态失败不可自愈，flat 被迫降级。systemd 层修复被否决——`After=` 在 `Type=simple` 下只提供进程启动排序，不构成「已监听」的 readiness 保证；而任何显式 readiness 交接（`Type=notify`、阻塞式 `ExecStartPost` 探活、socket activation 等）一旦成为 API / external worker 的启动硬依赖，都会把 BgFilter 故障扩大为整套服务不可启动。 +- 决策：仅对「TCP 连接从未建立」的失败（连接拒绝 / 不可达 / connect 阶段超时）做有界退避重连——这类请求从未进入 worker admission，无副作用、天然幂等；连接已建立后的任何失败（结果未知）与收到任何 HTTP 响应（含 5xx）维持原「不重试」禁令。每轮重连前按现有公式重算 `maxQueueWaitMs`，不突破「预算不足不发送」不变量。计量单位澄清：一次逻辑调用至多被 worker 接收一次 RPC，重连增加的只是连接尝试次数。 +- 冷启动宽限：重连配额按「本进程是否已连通过 worker」（收到任意 HTTP 响应即算，`AppState` 级标记）分档——冷启动档 flat 22.5s / complex 约 62.5s（覆盖开机竞态与慢开机），常规档 flat ≤1.5s（不侵蚀 39s fallback 预留）/ complex 22.5s（覆盖 `RestartSec=5s`+ 启动窗）；档位单次调用内锁定。新增 `bgfilter_internal_connect_retry_total{mode}` 指标。 +- 平台差异（Windows 开发环境）：连接已关闭的 loopback 端口不回 RST 而是挂到 connect timeout，错误呈现为 `deadline_exceeded` 且 `is_connect` 为真；重连判定只看 connect 分类，不看错误码。生产 Linux 即时拒绝，呈现 `internal_error`。 +- 安全不变量测试：除配额 / 跨窗 / deadline 地板路径外，专项覆盖「TCP 已 accept、未回任何 HTTP 字节即断开 → 不得发起第二次连接」，以 mock listener 的 accept 计数证明父侧未重连。 +- 影响范围：`server-rs/crates/api-server/src/bgfilter_worker.rs`、`state.rs`、`editor_project.rs`、调度方案 §5.1/§7/§9.3/§11、数据契约「BgFilter 连接复用、超时与动作帧流水线」条目、运维文档及各编辑器专题文档的旧禁令措辞统一改为「不重试已被 worker 接收的内部 RPC」。 + +## 2026-07-23 生产 API 发布按实际路径渲染 worker systemd unit + +- 背景：Server-Provision 支持自定义 current link、API env 和角色 env，并在首次安装时渲染三个 worker unit；API deploy 为下发随 release 更新的 unit 又原样覆盖目标机配置，导致自定义路径在下一次发布时退回模板默认值。 +- 决策：`production-api-deploy.sh` 继续随 release 安装默认命名的 BgFilter、external-generation worker 和 controller unit，但安装前必须用本次部署参数渲染临时文件；新增 `--controller-env-file` 补齐 controller 专属 env 输入。release 内模板保持默认路径，供 provision 和 deploy 共同作为单一模板来源；自定义服务名仍由目标机自行管理，不强制覆盖。 +- 影响范围：`scripts/deploy/production-api-deploy.sh`、`scripts/check-production-api-deploy.mjs`、`jenkins/Jenkinsfile.production-api-deploy`、`jenkins/Jenkinsfile.production-full-build-and-deploy`、`scripts/check-production-ops-guardrails.mjs`、生产运维文档和 worker systemd 发布契约。 +- 验证方式：`bash -n scripts/deploy/production-api-deploy.sh`、`node --check scripts/check-production-api-deploy.mjs`、`npm run check:production-api-deploy`、`npm run check:production-ops`、`npm run check:encoding`、`git diff --check`。 + ## 2026-07-23 Gitea CI 镜像刷新到 SpacetimeDB 2.7.0 锁 - 背景：`server-rs/Cargo.lock` 已从镜像预热时的 SpacetimeDB 2.6.1 前移到 2.7.0，runtime 校验因此报告 `server_rust_cache_lock=partial`。受控 Cargo egress proxy 连续返回 CONNECT tunnel 502 时，Backend job 在 `check:module-runtime-artifact` 依赖解析阶段失败，尚未进入 workspace tests。 diff --git a/docs/project-memory/shared-memory/development-workflow.md b/docs/project-memory/shared-memory/development-workflow.md index 30e2cadd6..13cc3dfc5 100644 --- a/docs/project-memory/shared-memory/development-workflow.md +++ b/docs/project-memory/shared-memory/development-workflow.md @@ -51,18 +51,19 @@ npm install npm run dev ``` -Linux 多用户共享同一台机器开发时，本地 dev 脚本会为当前 Linux 用户分配一个固定端口段并写入系统级注册表 `/var/tmp/genarrative-dev-port-ranges/registry.json`，自动分配从 `10000-10099` 开始，每段 100 个端口，四个 dev 服务依次使用 `start` 到 `start + 3`。可用 `GENARRATIVE_DEV_PORT_RANGE` 或 `npm run dev -- --port-range` 手动指定端口段用于特殊场景；注册表会阻止不同用户使用相同或重叠段，并让同一用户后续启动继续复用自己已占用的固定段。该机制只在 Linux 生效，Windows 仍沿用原有端口探测与漂移逻辑。 +Linux 多用户共享同一台机器开发时，本地 dev 脚本会为当前 Linux 用户分配一个固定端口段并写入系统级注册表 `/var/tmp/genarrative-dev-port-ranges/registry.json`，自动分配从 `10000-10099` 开始，每段 100 个端口，五个 dev 服务依次使用 `start` 到 `start + 4`，其中 BgFilter worker 固定为 `start + 4`。可用 `GENARRATIVE_DEV_PORT_RANGE` 或 `npm run dev -- --port-range` 手动指定端口段用于特殊场景；注册表会阻止不同用户使用相同或重叠段，并让同一用户后续启动继续复用自己已占用的固定段。该机制只在 Linux 生效，Windows 把第五个服务纳入原有统一端口探测与漂移逻辑。 -本地 `npm run dev`、`npm run dev:spacetime` 和 `npm run dev:api-server` 会在 Rust 子进程环境中绕过项目默认 `sccache` wrapper，避免损坏的本机 cache daemon 阻断 `spacetime publish` 或 `api-server` 启动；显式设置的非 sccache 自定义 wrapper 会被保留。生产 / Jenkins 构建仍按流水线自身的 sccache 策略执行。 +本地 `npm run dev`、`npm run dev:spacetime`、`npm run dev:api-server` 和 `npm run dev:bgfilter-worker` 会在 Rust 子进程环境中绕过项目默认 `sccache` wrapper，避免损坏的本机 cache daemon 阻断 `spacetime publish` 或 Rust 服务启动；显式设置的非 sccache 自定义 wrapper 会被保留。生产 / Jenkins 构建仍按流水线自身的 sccache 策略执行。 该命令会启动： - SpacetimeDB standalone +- 独立 `bgfilter-worker` - Rust `api-server` - 主站 Vite - 后台 Vite -`npm run dev` 和单模块 `dev:*` 命令会更新根目录 `.app/dev-stack.json`，记录四个本地服务的 pid、端口、URL、启动状态和当前命令。该目录只作本机运行态观测，不提交 Git。 +`npm run dev` 和单模块 `dev:*` 命令会更新根目录 `.app/dev-stack.json`，记录五个本地服务的 pid、端口、URL、启动状态和当前命令。该目录只作本机运行态观测，不提交 Git。 开启自动刷新： @@ -70,9 +71,9 @@ Linux 多用户共享同一台机器开发时，本地 dev 脚本会为当前 Li npm run dev -- --watch ``` -watch 模式只由外层调度器自动处理后端侧刷新：`spacetime-module` 改动后重新发布模块但不重启 standalone 宿主，`api-server` 改动后重启 Rust 进程。主站 Vite 与后台 Vite 的源码变化交给 Vite 自身 HMR，避免外层 watcher 监听到依赖缓存或临时文件后循环重启。 +watch 模式只由外层调度器自动处理后端侧刷新：`spacetime-module` 改动后重新发布模块但不重启 standalone 宿主；完整栈和 `dev:api-server` 只创建一套 Rust watcher，改动后先停止 API 与 BgFilter worker，再先启动并验活 worker、最后启动并验活 API。主站 Vite 与后台 Vite 的源码变化交给 Vite 自身 HMR，避免外层 watcher 监听到依赖缓存或临时文件后循环重启。 -非 watch 模式下，`npm run dev` 终端支持输入 `rs spacetime`、`rs api-server`、`rs web`、`rs admin-web` 或 `rs all`。其中 `rs spacetime` 只会重新发布 `spacetime-module`，不会重启 standalone 宿主；其他模块仍按进程重启。 +非 watch 模式下，`npm run dev` 终端支持输入 `rs spacetime`、`rs api-server`、`rs bgfilter-worker`、`rs web`、`rs admin-web` 或 `rs all`。其中 `rs spacetime` 只会重新发布 `spacetime-module`，不会重启 standalone 宿主；重启任一 Rust 角色都会走 API / BgFilter worker 组合重启。 单独启动 SpacetimeDB： @@ -86,6 +87,12 @@ npm run dev:spacetime npm run dev:api-server ``` +该命令会由同一 runner 自动带起独立 BgFilter worker，确保共享实际内部 base URL 和 Token。只单独启动内部 worker 时使用： + +```bash +npm run dev:bgfilter-worker +``` + 单独启动前端： ```bash @@ -107,7 +114,7 @@ npm run server-manager:panel 该命令启动 `server-rs/crates/server-manager-panel` 的 egui 桌面工具，从本机 `~/.ssh/config` 读取可用 `Host` alias，支持多服务器健康巡检、可折叠侧边栏和受控 systemd 服务启停。服务操作通过远端 `sudo -n systemctl start|stop|restart ` 执行，目标服务器需要提前配置对应 unit 的免交互 sudo 权限。 面板启动时会自动注入本机中文字体；如开发机中文仍显示为方块，可设置 `GENARRATIVE_SERVER_PANEL_CJK_FONT=/path/to/font.ttc|index` 指向本机 CJK 字体。 -`npm run dev:api-server` 会保留终端实时输出，并把同一份输出持久化到 `logs/api-server/api-server-.log`。完整联调入口 `npm run dev` 启动的 Rust `api-server` 使用同一套日志规则。如需改写路径，可设置 `GENARRATIVE_API_SERVER_LOG_FILE`；如只改目录，可设置 `GENARRATIVE_API_SERVER_LOG_DIR`。 +`npm run dev:api-server` 会保留终端实时输出，并把 API 输出持久化到 `logs/api-server/api-server-.log`、BgFilter worker 输出持久化到 `logs/bgfilter-worker/bgfilter-worker-.log`。完整联调入口 `npm run dev` 使用同一套日志规则。API 日志可通过 `GENARRATIVE_API_SERVER_LOG_FILE` / `GENARRATIVE_API_SERVER_LOG_DIR` 改写，worker 日志可通过 `GENARRATIVE_BGFILTER_WORKER_LOG_FILE` / `GENARRATIVE_BGFILTER_WORKER_LOG_DIR` 改写。 开发态 `npm run dev` / `npm run dev:api-server` 默认打开 `GENARRATIVE_DEV_PASSWORD_ENTRY_AUTO_REGISTER_ENABLED=true`，密码入口可以直接注册未知手机号账号；生产默认仍关闭该开关。 @@ -266,7 +273,7 @@ npm run check:server-rs-ddd - 仓库 CI 入口是 `.gitea/workflows/project-ci.yml`，向 `master`、`codex/ai-game-creator-app` 推送和所有 PR 创建、更新时必须运行，也允许手工触发。 - CI 固定拆分为 `Repository checks`、`Frontend tests`、`Backend tests`、`Native shell tests` 四个 required job；对应 PR context 完整名称是 `Project CI / Repository checks (pull_request)`、`Project CI / Frontend tests (pull_request)`、`Project CI / Backend tests (pull_request)`、`Project CI / Native shell tests (pull_request)`，首次运行后仍须从 Gitea 最近一周 context 表复核。测试使用独立 job，不能只藏在综合检查 step 中；原生壳验收单独运行以便定位重型构建失败。 -- 四个 job 共同覆盖 `npm run check`，并追加 `npm run check:server-rs-ddd`、`cargo test --locked --workspace --no-fail-fast --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --all-targets --manifest-path server-rs/Cargo.toml` 和 `cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml`。`ffmpeg` 由预构建 job 镜像提供，避免视频抽帧测试因工具缺失提前返回。`codex/ai-game-creator-app` 分支的原生壳入口还必须覆盖 `npm run ai-game-creator-shell:check` 和 release build smoke。 +- 四个 job 共同覆盖 `npm run check`，并追加 `npm run bgfilter-worker:smoke-test`、`npm run check:production-health-patrol`、`npm run check:production-api-release`、`npm run check:production-api-deploy`、`npm run check:server-rs-ddd`、`cargo test --locked --workspace --no-fail-fast --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --all-targets --manifest-path server-rs/Cargo.toml` 和 `cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml`。BgFilter 的 `.test.mjs` 使用 Node test runner，必须由 workflow 显式调用；生产巡检 / 发布 / 部署行为检查只运行无密钥临时 fixture，不连接现场环境。`ffmpeg` 由预构建 job 镜像提供，避免视频抽帧测试因工具缺失提前返回。`codex/ai-game-creator-app` 分支的原生壳入口还必须覆盖 `npm run ai-game-creator-shell:check` 和 release build smoke。 - checkout 必须使用完整历史。PR 将 base SHA 写入 `SPACETIME_SCHEMA_BASE_REF`，直接推送 `master` 使用 before SHA；事件基线不可解析时直接失败。Gitea 检查的是 PR head 而非预合并 commit，workflow 必须拒绝不包含最新 base commit 的过期 PR，分支保护同时保持“PR 过期禁止合并”。 - 普通 PR job 不读取业务 secret，不运行真实 API/SpacetimeDB/OSS/支付/生成/live smoke，也不执行会修改外部状态的维护、迁移、发布或备份命令。 - Gitea 至少升级到 `1.26.4` 后才能注册执行 PR job 的 runner。runner 保留 `ubuntu-latest` 固定 digest 映射，并把 workflow 使用的 `genarrative-ci` 映射到 runner 内层 Docker 已装入的完整 Image ID；不映射 host，不向 job 暴露 Docker socket、业务 secret 或不必要内网。当前 CI 镜像约 `1.788 GB`，Image ID 为 `sha256:c04b114b1f145072c9df7842c4c974e1bb2eaaf391d95d84c9212a460546b7d5`，标签映射为 `genarrative-ci:docker://sha256:c04b114b1f145072c9df7842c4c974e1bb2eaaf391d95d84c9212a460546b7d5`。内层 Docker 数据持久化且 `force_pull: false`，该 ID 缺失时失败关闭，不现场拉取或回退浮动 tag。Runner 2.0.0 支持 job 级 `timeout-minutes`，但 runner 全局 `3h` 仍是硬上限；首次运行成功后，`master` 分支保护必须要求上述四个 job 全部成功。 diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md index e69a0ac3a..94fe87ed5 100644 --- a/docs/project-memory/shared-memory/pitfalls.md +++ b/docs/project-memory/shared-memory/pitfalls.md @@ -3296,6 +3296,14 @@ - 原因：单 attempt timeout、重试退避、图片下载与 worker / lease 分别使用独立的相对计时，没有共享同一绝对 deadline；只抬高 worker timeout 或单独压低 provider timeout 都无法保证留出终态写回窗口。 - 处理：实际调用 VectorEngine 的四类图片 job 使用 `1800s` long 预算；从 job 开始的同一起点派生 provider deadline，常规提前 `60s`、短预算提前一半。每次 attempt、退避、下一次 attempt 和图片下载都必须在该 deadline 内；普通 HTTP / `inline` 不伪造 worker deadline。修复时不改动 lease fencing、迟到写回仲裁和原子退款语义。 +## 同一 Rust 二进制的本地双进程不能各自并发 watch 重启（2026-07-21） + +- 现象：本地把 `api-server` 与独立 `bgfilter-worker` 都用 `cargo run -p api-server` 启动后，一次 Rust 源码变更触发两套 watcher 并发停止、编译和链接；Windows 常因另一个实例仍占用 `api-server.exe` 而链接失败，或出现 API 已恢复但内部 worker 尚未 ready 的半更新状态。 +- 原因：两个进程角色共享同一 crate、target 和可执行文件，却被错误地当成两个互不相关的 dev service。更危险的是先启动 `GENARRATIVE_PROCESS_ROLE=all` 的 API：它会立即消费外部生成队列，可能在内部 BgFilter worker 尚未 ready 时领取任务。 +- 处理：`npm run dev` 与 `npm run dev:api-server` 只创建一套 Rust watcher，并把两个进程作为组合重启单元：先停止 API 与 BgFilter worker，再只让 worker 的 `cargo run` 完成必要构建，等待 worker `/readyz`，最后启动并验活 API。交互 `rs api-server`、`rs bgfilter-worker` 在完整栈内也必须走同一组合重启。`ProcessRole::All` 永远不内嵌 BgFilter listener；父子进程共享解析后的内部 base URL / Token，Linux 第五端口固定为端口段 `start + 4`，Windows 把第五端口纳入统一探测和漂移。 +- 验证：定向测试断言组合重启顺序为“stop API → stop worker → start/ready worker → start/ready API”，`dev:api-server` 自动带起同 runner worker，端口解析得到五个互不冲突的端口；再运行 `node --check scripts/dev.mjs`、dev-stack 定向测试和编码检查。 +- 关联：`scripts/dev.mjs`、`scripts/dev-stack-port-utils.mjs`、`.hermes/skills/genarrative-dev-stack-port-routing/SKILL.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。 + ## Gitea PR runner 不能把宿主 Docker socket 当普通 volume - 现象：`act_runner` 的 `container.docker_host` 留空时，job inspect 会出现 `/var/run/docker.sock:/var/run/docker.sock`；PR 脚本即使 `valid_volumes: []`，仍可直接调用 Docker API 读取其它容器、挂宿主目录或取得 runner 配置。另一类迁移故障是 rootless daemon 可以启动，但 bwrap 在 job 内报 `No permissions to create new namespace`、`Failed to make / slave` 或 `Mount too revealing`。 @@ -3332,6 +3340,14 @@ - 重启边界：`docker restart --timeout 660` 只设置容器停止宽限，不能替代 Runner drain。rootless DinD supervisor 可能与 runner 同时停止内层 dockerd，使仍在收尾的 job 因连接关闭被标记失败；切换前必须同时确认 Gitea 没有 `in_progress` run 且内层 `docker ps` 为空。误触发时只重跑受影响的失败 job，不重跑已成功项。 - 关联：`deploy/container/README.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、`docs/project-memory/shared-memory/development-workflow.md`。 +## 生产 API 发布重装 worker unit 不能丢失自定义路径（2026-07-23） + +- 现象：Server-Provision 已按自定义 current link 和 env 路径安装 worker systemd unit，但下一次 API 发布后，worker 可能重新读取 `/opt/genarrative/current` 与 `/etc/genarrative/*.env`；默认路径仍有旧 release 时，服务 active 和部署成功都不能证明新二进制已运行。 +- 原因：发布包中的 BgFilter、external-generation worker 和 controller unit 是带默认路径的模板；deploy 若直接 `install` 原文件，会覆盖 provision 已渲染的目标机 unit。external-generation 专属 env 还是可选加载，错误路径可能不会阻止服务进入 active。 +- 处理：API deploy 安装三个 unit 前必须按本次 current、API env 和各角色 env 参数渲染临时文件，安装后保留 release 内原始模板不变；controller 自定义 env 由 `--controller-env-file` 显式传入。API Deploy 与 Full Job 必须同步暴露并透传 controller/BgFilter env，不能让流水线回退默认路径。自定义服务名表示沿用目标机自管 unit，不进入默认 unit 安装分支。 +- 验证：部署 guard 使用临时自定义绝对路径，直接读取实际安装目录中的三个 unit，核对 `WorkingDirectory`、`ExecStart`、共享 API env 与角色 env，不能只用 fake `systemctl is-active` 判绿。 +- 关联：`scripts/deploy/production-api-deploy.sh`、`scripts/check-production-api-deploy.mjs`、`scripts/jenkins-server-provision.sh`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。 + ## 通用灰度后台页不能依赖已退役业务配置 - 现象：通用 `feature_gate_config`、`/admin/api/feature-gates` 和现役功能 gate 仍在，但后台“灰度发布”Tab 随旧创作模板入口一起消失；Rust 权限仍可授予 `gray-release`，前端却没有对应路由。 diff --git a/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md b/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md index cca6665d0..50ab585e2 100644 --- a/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md +++ b/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md @@ -21,9 +21,9 @@ - 生成资源右上角显示元数据按钮，点击打开独立元数据窗口。图片信息页不展示后端组装后的生图 Prompt，也不提供复制 Prompt；只展示该图片生成时用户在面板里提交的输入快照，包括普通生成提示词、规范表单字段、角色设定、图标素材描述、快速编辑提示词、重绘提示词，以及角色规范 / 常规参考图 / 图标规范 / 编辑参考图等参考图卡片，并提供“复制信息”复制当前可见字段。参考图输入快照只保存 `refType/refId` 行引用，其中 `refType="project-resource"` 指向 `editor_project_resource.resourceId`，`refType="asset"` 指向 `editor_asset.assetId`；不得把图片 Data URL、普通 URL 或 `objectKey` 写入 `generationInputs.references`。旧数据或上传图片没有输入快照时显示 `-`，禁止回退展示内部 Prompt。 - 对生成资源执行重绘时，在右侧创建新的生成结果图层，并自动调整视图显示原图和新图；重绘面板不因提交成功自动关闭，便于连续改提示词。重绘 / 改造输入框只允许从 `generationInputs.fields` 中恢复用户可见输入快照，例如普通生成提示词、视频描述、音效 `prompt`、背景音乐 `gpt_description_prompt`、角色设定、UI 用户输入、图标素材描述、规范表单和宣发素材字段；禁止回退展示资源 `prompt` / `actualPrompt` 中的后端拼接 Prompt、固定生成模板或模型默认提示词。没有用户输入快照的旧图层打开改造时保持空输入，等待用户重新填写。 - 图片生成 / 修改统一经 api-server BFF 接入 VectorEngine。普通生成、生成规范和重绘保留既有 `gpt-image-2` 路径；图片快速编辑统一打开框选区域 + 单提示词 + 模型选择面板，默认沿用原图模型，不展示参考图或比例 / 尺寸控件；其中生成规范类图片固定 `16:9`、`2K`、`gpt-image-2`，面板底部用与可编辑面板一致的比例 / 尺寸 / 模型胶囊按钮展示固定参数，但按钮为禁用态，不允许在该面板改比例、尺寸或模型。`生成角色形象` 与 `生成图标素材` 支持 `nanobanana2`（`gemini-3.1-flash-image-preview`）和 `gpt-image-2`，默认 `nanobanana2`，并在两类面板之间沿用用户上次选择的模型；两类面板不展示抠图背景色或抠图模型选择；前端用户路径固定提交 `screenColor=auto` 和 `segModel=birefnet`，由后端自动决策具体抠图背景色，`anime-seg` 作为内部保留能力不在用户界面暴露。`nanobanana2` 走 `/v1beta/models/{model}:generateContent`，请求体写入 `generationConfig.imageConfig.aspectRatio/imageSize`；`gpt-image-2` 走 `/v1/images/generations` 或 `/v1/images/edits`，请求体按 VectorEngine 文档映射 `size`。宣发素材三个工作流（游戏首图、详情五图、运营海报）固定使用 `gpt-image-2`，面板模型胶囊为禁用态，不提供 `nanobanana2` 入口；前端按 workflow 同时提交 `outputSize`、`aspectRatio` 和 `imageSize`，其中游戏首图为 `720x540 / 4:3`、详情单图为 `720x1280 / 9:16`、运营海报为 `1280x720 / 16:9`；后端收到 `kind: "publication-material"` 时也强制归一为 `gpt-image-2` 生成和计费，生成回填图层优先使用生成占位的 `originalWidth/originalHeight`，即使上游回包尺寸漂移也不得把宣发素材卡片变成随机 `1:1` 或 `4:3`。纯文本生成走 `/api/editor/images/generations`，重绘在前端优先复用当前图层 objectKey；尚未登记的本地图片先上传 OSS，再把 objectKey 交给同一图片生成 BFF，并在原图右侧生成一张新图；普通图层重绘作为 `quick-edit` 参考图提交，角色图层重绘必须按 `kind: "character"` 提交，继续套用角色生成器提示词限定、透明 PNG 后处理和角色资产持久化。`生成视频` 走 `/api/editor/videos/generations`，前端模型入口仅展示 Seedance 2.0 Fast / Seedance 2.0 / Kling 3.0 / Kling 3.0 Omni，不展示 Veo 入口，默认 Seedance 2.0 Fast；视频参数按当前正式面板支持的比例、时长、清晰度和声音开关提交，且 Seedance Fast 与 Seedance 标准版必须按各自真实模型 ID 独立映射，不得混用。生成结果以视频图层加入画布。纯文本生成入口采用 Lovart 式画布内占位图 + 锚定生成输入框：点击生成图片后以当前视口世界中心为目标，经统一 placement 避让后创建选中的灰色占位框，输入框跟随占位框显示；普通图片、角色、图标图集、UI 设计图及其重绘 / 改造入口必须在比例或清晰度恢复、切换时同步把占位框 `width/height/originalWidth/originalHeight` 更新为目标像素尺寸，生成中不得继续显示默认 1K 框；UI 素材提取的 1K / 2K 图集占位和旧图片修改入口也分别使用本次目标尺寸与源图真实尺寸。待生成、生成中和失败后保留的占位图都必须继续支持拖动，生成完成时真实生成图或视频落在最新占位框位置，输入框继续跟随新生成图层；占位图失焦时隐藏高亮边框、左上角生成器名称和右上角原始尺寸，重新聚焦时再显示，且名称 / 尺寸在画布缩小时按 viewport 反向缩放保持屏幕尺寸稳定；点击所有图片 / 视频生成入口并确认请求开始后，必须隐藏对应设置面板，只保留画布内占位图或原图预览，并在预览上显示 Lovart 式生成中遮罩，避免“面板仍占屏”或“预览一起消失”。图片快速编辑和重绘在调用图片 BFF 前必须把当前图层图片解析为已上传的 objectKey 或资源 ID；浏览器临时图片需先上传 OSS；视频素材快速编辑走视频生成 BFF，不允许走图片模型；角色动作的 `生成动画` 仍固定使用 `seedance2.0-fast` 动作 / 视频模型，角色动作素材的 `快速编辑` 按当前帧图片走图片编辑。前端不持有 provider 密钥；上游失败或配置缺失时恢复当前生成设置面板展示失败，不创建 mock 成功图。 -- 图片画布抠图统一使用 BgFilter 服务 `GENARRATIVE_EDITOR_BGFILTER_BASE_URL/remove-background`，默认 `http://58.87.105.82/bgfilter/remove-background`，默认请求超时 `180000ms`（BgFilter CPU 推理）。手动去除背景面向用户任意图片，仍走登录态同源 BFF `POST /api/editor/images/background-removals` 和外部生成队列；API 在入队前拒绝 `data:` / `blob:` 内联媒体，worker 将稳定引用解析为当前账号已登记的 OSS object key 并校验归属后签发 600 秒 URL，固定提交 `image_url`、`background_mode=complex`、`seg_model=birefnet`、`cross_check=off`，不下载原图，也不提交 `file` 或 `screen_color`。首次请求失败后立即重试 `1` 次，两次都失败则返回最终错误；manual complex 不接入依赖纯色键值的阿里云 / 本地键色降级链，也不改变 flat 链路的熔断状态。手动与标准纯色背景两类模式共用 `GENARRATIVE_EDITOR_BGFILTER_BASE_URL`、`GENARRATIVE_EDITOR_BGFILTER_TOKEN`、`GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS` 和共享 HTTP client；BgFilter token 未配置时只兼容回退读取旧 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN`。所有令牌都只在服务端注入，前端不持有令牌。worker 对上游结果做响应字节和图片尺寸上限保护，并先落 OSS / asset object；接口只返回 `queueState`，有项目上下文时前端同时创建去背景生成占位并把 `canvasCompletion` 交给后端，完成后由后端写入结果图层和最新项目快照。 -- 编辑器自己生成的标准纯色背景抠图资产在保存源图后统一调用 BgFilter `background_mode=flat`。角色形象生成、图标 spritesheet 生成、UI 设计图素材提取和角色动作的前端用户路径都固定把 `screenColor=auto` 注入请求体，但用户可见 `generationInputs.fields` 不再记录 `抠图背景色` 或 `抠图模型`；api-server 在组装 prompt 前调用背景决策模块，从 12 个候选色中选择具体 hex，最多重试 3 次，失败后兜底 `#CFEFFF`。后端仍保留手动 hex 解析能力供内部兼容。最终生图 prompt、动作视频实色背景和 BgFilter `screen_color` multipart 字段只接收解析后的具体 hex，不透传 `auto`。四条 flat 路径同时把默认 `segModel=birefnet` 传为 `seg_model`，并显式传 `cross_check`：角色形象生成和角色动作逐帧去背传 `on`，图标 spritesheet 和 UI 设计图素材提取传 `off`，不依赖 BgFilter 服务端默认值；后端仍保留识别 `anime-seg` 的内部兼容能力，但前端用户入口不展示也不提交 `seg_model`、`background_mode` 或 `cross_check`。flat 请求首次失败后立即重试 `1` 次；第二次仍失败、返回非成功状态、空图片或非法图片时，以及连续失败达到 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD=3` 后的 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS=300` 秒熔断期，api-server 都先调用阿里云通用抠图，只有阿里云失败才用本地 `editor_green_screen` 按同一 `screenColor` 兜底去背。角色动作生成的序列帧背景色已与生图统一：后端把源角色图合成到视觉决策出的具体 hex 后再图生视频；抽帧后逐帧进入同一条 `BgFilter（background_mode=flat，cross_check=on）→ 阿里云 → 本地键色` 链路。 -- 角色动作逐帧抠图在 api-server 内复用共享 BgFilter HTTP Client；每一次 HTTP attempt 使用“`GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS` 基准值 + `2000ms × 本次实际帧数`”，默认 `32 / 40 / 48` 帧分别为 `244000 / 260000 / 276000ms`，角色形象单图、图标、UI 和手动去背景仍使用基准值。该值是单个请求从发起到响应体读取完成的 timeout，不是整批帧或整项角色动作任务超时；单帧首次失败立即重试 `1` 次并重新签发 OSS URL、重新计时，第二次仍失败才按 object key 进入阿里云/本地降级链，整项任务另受 worker long-job 预算约束。全部 `32 / 40 / 48` 帧按“对应绿幕源图上传 OSS 并释放原帧字节 → 以签名 URL 调 BgFilter/按 object key 降级 → 透明帧落 OSS”连续加入无序在途流水线，允许响应乱序完成并在最终返回前按 `frameIndex` 恢复顺序；任一帧最终失败时仍排空全部已启动请求，整个动作任务失败退款，不发布缺帧动画。 +- 图片画布抠图统一通过唯一、只监听 loopback 的 `bgfilter-worker` 调用 BgFilter provider。手动去除背景面向用户任意图片，仍走登录态同源 BFF `POST /api/editor/images/background-removals` 和外部生成队列；API 在入队前拒绝 `data:` / `blob:` 内联媒体，父流程将稳定引用解析为当前账号已登记且归属已校验的私有 OSS object key，只通过一次内部 HTTP RPC 传递 object key、排队预算 `maxQueueWaitMs`、调用预算 `callBudgetMs` 和固定的 `background_mode=complex`、`seg_model=birefnet`、`cross_check=off`，不传源图字节、签名 URL、`file` 或 `screen_color`。子 worker 在每次真实 provider attempt 前签发 600 秒 URL，承担默认 `Q=2048` admission 保险丝、provider 并发 `N=16`、严格最多两次顺序 attempt、响应字节与图片尺寸校验，并把成功图片作为内部 HTTP 二进制 body 直接返回；父流程同步等待该响应且不重试已被 worker 接收的内部 RPC（连接从未建立时按调度方案 §5.1 有界重连）。排队只消耗 `maxQueueWaitMs`，取得 provider permit 后才启动 `callBudgetMs`；attempt 按 `N × est × 2`、调用预算按 `2 × attempt + 1s` 派生，冻结 `est=5000ms` 时分别为 `160s / 321s`。complex 的真实 provider 失败会累计并打开自身熔断，但与 flat 状态隔离；complex 任意失败或熔断仍直接返回父流程失败，不接入阿里云 / 本地键色降级。provider 配置继续统一使用 `GENARRATIVE_EDITOR_BGFILTER_BASE_URL` 和 `GENARRATIVE_EDITOR_BGFILTER_TOKEN`，父子共同使用 `GENARRATIVE_BGFILTER_WORKER_CONCURRENCY` 与 `GENARRATIVE_EDITOR_BGFILTER_SINGLE_IMAGE_ESTIMATE_MS` 派生预算；旧 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN` 只作为 provider token 兼容别名；内部调用另使用 `GENARRATIVE_BGFILTER_WORKER_BASE_URL` 和独立内部 Token。所有令牌只在服务端注入，前端不持有令牌。成功字节返回父流程后，仍由父流程完成最终处理、OSS / asset object 持久化、结果图层与最新项目快照写回；接口只向前端返回 `queueState`，有项目上下文时前端同时创建去背景生成占位并把 `canvasCompletion` 交给后端。 +- 编辑器自己生成的标准纯色背景抠图资产在保存源图后统一以 `background_mode=flat` 调用内部 `bgfilter-worker`。角色形象生成、图标 spritesheet 生成、UI 设计图素材提取和角色动作的前端用户路径都固定把 `screenColor=auto` 注入请求体，但用户可见 `generationInputs.fields` 不再记录 `抠图背景色` 或 `抠图模型`；api-server 在组装 prompt 前调用背景决策模块，从 12 个候选色中选择具体 hex，最多重试 3 次，失败后兜底 `#CFEFFF`。后端仍保留手动 hex 解析能力供内部兼容。最终生图 prompt、动作视频实色背景和子 worker 发往 provider 的 `screen_color` multipart 字段只接收解析后的具体 hex，不透传 `auto`。四条 flat 路径同时把默认 `segModel=birefnet` 传为 `seg_model`，并显式传 `cross_check`：角色形象生成和角色动作逐帧去背传 `on`，图标 spritesheet 和 UI 设计图素材提取传 `off`，不依赖 BgFilter 服务端默认值；后端仍保留识别 `anime-seg` 的内部兼容能力，但前端用户入口不展示也不提交 `seg_model`、`background_mode` 或 `cross_check`。子 worker 为 flat / complex 分别维护独立进程级熔断，并对一次逻辑调用严格最多执行两次顺序 provider attempt；两种模式共享 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD=3` 和 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS=120` 默认值，但失败和成功只更新当前模式；父侧至多让 worker 接收一次内部 RPC（连接从未建立时按调度方案 §5.1 有界重连）。flat 两次失败、熔断、overload、内部 deadline 或断连后，只要父业务预算仍有效，父流程才按同一 object key 进入“阿里云通用抠图 → 本地 `editor_green_screen` 键色”降级；阿里云 fallback 不属于 `bgfilter-worker`。角色动作生成的序列帧背景色已与生图统一：后端把源角色图合成到视觉决策出的具体 hex 后再图生视频；抽帧后逐帧进入同一条 `内部 bgfilter-worker（background_mode=flat，cross_check=on）→ 父侧阿里云 → 父侧本地键色` 链路。 +- BgFilter 单次真实 provider attempt 不再使用独立固定 timeout，而由父子共同按 `attempt = N × est × 2` 运行时派生；一次逻辑调用的 `callBudgetMs = 2 × attempt + 1s`，从子 worker 取得 provider permit 后才开始计时。当前冻结 `N=16 / est=5000ms` 时为 `160s / 321s`。父侧继续管理父 job / request 总预算，为每个内部 RPC 单独派生 `maxQueueWaitMs`；排队只消耗该字段，不侵蚀 `callBudgetMs`，flat 还需预留阿里云和本地键色 fallback 时间。角色动作不再按本次实际帧数增加 attempt，`32 / 40 / 48` 帧使用同一公式。角色动画继续用 `buffer_unordered(frame_count.max(1))` 同时提交单帧逻辑调用，由唯一子 worker 保证健康进程内实际在飞的 provider 请求不超过 `N`、admission 不超过默认保险丝 `Q=2048`；父流程仍按“对应绿幕源图上传 OSS 并释放原帧字节 → 以 object key 调内部 worker / 按 object key 降级 → 父侧完成透明帧处理并落 OSS”连续组成无序在途流水线，允许响应乱序，并在收口时 collect / drain 全部已提交 frame future、按 `frameIndex` 恢复顺序。任一帧最终失败时仍先排空全部已启动请求，再使整个动作任务失败退款，不发布缺帧动画；最终图片处理、OSS、画布写回和计费始终属于父流程。 - 多产物生成以后端项目快照为唯一画布真相：同一任务实际产生的原始产物、抠图 / 透明化结果和拆分结果都要先登记为 `editor_project_resource`，再通过一次 `canvasCompletion` 原子写入画布。角色形象、图标 spritesheet 和 UI 素材提取的纯色背景原图不能只留在 OSS。透明后处理成功时，处理结果保持主图层和 `generatedLayerId` 锚点，三类任务同时把 provider 原图作为第二个图层放在透明主结果右侧，图标和 UI 的实际拆分素材从 provider 原图右侧开始放置。透明背景处理最终失败时，只把已保存的原图作为唯一主图完成占位，不放透明处理图，图标和 UI 不继续拆分。source-only fallback 的前端只消费后端返回的 `project` / `resource` 快照，不按缺失字段自行构造透明图、切片或图层；任务以 `completed + warning` 收口。该收口只捕获透明背景处理本身的最终失败；phase 上报、provider 原图持久化、透明处理图持久化和 `canvasCompletion` 写回错误仍正常传播，不能被原图降级吞掉。通用 `warning.reason` 是可直接展示的完整原因，并优先于 `sliceWarning`；既有 `sliceWarning.reason` 只表示透明图成功后的自动拆分失败，保留后端原始诊断，inline 前端仅在展示时补充“图集已生成，但自动拆分未完成：”提示，queue worker 则把它归一为 BFF `warning` 字符串后由前端直接展示。无项目上下文时不创建项目资源或画布图层。 - 图片快速编辑面板只保留一个提示词输入框和模型选择，不展示额外参考图或比例 / 尺寸控件；原图 / 原素材作为 `/api/editor/images/edits` 的 `sourceImageSrc` 直接提交，不作为 `referenceImageSrcs`。完整图标图集 `icon-spritesheet` 支持快速编辑，拆分后的单个 `icon` 不提供该入口，前后端必须使用同一素材类型规则。打开快速编辑时画布必须自动平移缩放，让原素材完整落在可视区上半部分，底部面板固定出现在素材下方且不遮挡内容，竖屏 UI 素材也必须完整展示。快速编辑右侧显示矩形、椭圆、画笔框选工具，但进入时不默认启用；点击工具后显示选中态，再点同一工具取消启用。完成框选后，画布红色细框显示连续序号，提示词可按这些编号填写每个区域怎么改。点击 `修改` 后仍停留在当前快速编辑面板显示修改中，不创建独立 `Quick Edit Generator` 画布占位；生成成功后直接用结果覆盖原图图层，失败时保留当前面板并在错误红框中显示具体错误文案。 - 底部生成类按钮每次点击都必须创建独立的画布生成对象；新建规范、角色形象或图标素材时，只切换当前编辑面板，不得销毁此前尚未生成或已生成后的其它生成对象状态。归档为非当前编辑对象的生成占位仍可拖动、删除和等待异步完成，完成 / 失败回写必须按生成对象 ID 读取最新占位状态，不能使用提交瞬间的旧快照。 @@ -92,8 +92,8 @@ - `POST /api/editor/assets`：批量或单个创建账号级素材，登录态上传必须写入 OSS / asset object 引用和 `/` 轻量路径，不允许把 Data URL / signed URL 写入素材库。 - `PATCH /api/editor/assets/{assetId}`：重命名素材或移动素材到文件夹。 - `DELETE /api/editor/assets/{assetId}`：删除素材。已放入画布的 project resource 不被级联删除，避免旧画布丢图。 -- `POST /api/editor/images/generations`：按提示词调用 VectorEngine 生成图片。带 `model / aspectRatio / imageSize` 的用户生成必须把当前 K 档对应的真实像素直接传给 provider，前端占位与该请求尺寸使用同一映射；不得先请求固定 1K 再放大为 2K。普通图片的 provider 回图先留在内存，尺寸变换成功后只上传变换结果，变换失败则只上传 provider 原图，主结果只写一次 OSS 且不额外创建“原始输出”。角色生成可携带 `model`、`screenColor`、`segModel`、`aspectRatio`、`imageSize` 和 `referenceImageSrcs`；api-server 先保存带纯色背景源图，再调用 BgFilter 并传入 `screen_color=`、`seg_model=`，透明处理成功时生成透明 PNG，最终失败时按前述多产物降级规则以原图主结果和通用 `warning` 收口。角色、图标图集和 UI 图集的透明处理正常成功但返回尺寸与 provider 原图不同时，只重采样透明图的 alpha 蒙版并应用回 provider 原图的原始分辨率 RGB，不放大低分辨率后处理成品。宣发素材携带 `kind: "publication-material"` 时固定归一为 `gpt-image-2`，不支持 `nanobanana2`，并继续按固定交付像素处理。`nanobanana2` 参考图作为 `inline_data` 进入 `generateContent`，`gpt-image-2` 参考图进入 edits；`nanobanana2` 的 `512 / 1024 / 2K` 是标量清晰度档位，后端保留 provider 输出几何尺寸，不按 `宽x高` 解析。从既有图层重新打开生成器且没有仍存活的对话框快照时，前端按该图层真实 `originalWidth / originalHeight` 恢复比例和清晰度，不得回落到新建面板的 1K 默认值。普通重绘继续走该接口并把当前图层图片作为参考图；图片快速编辑不走该接口。请求可携带 `projectId`、`assetFolderId`、`assetKind`、`generationInputs` 和 `sourceResourceId`，后端生成完成后在响应中返回实际产物的 project / resource / asset 快照。 -- `POST /api/editor/images/background-removals`：接收当前图片的 `objectKey`、`resourceId` 或 `assetId` 候选引用，登录态和稳定引用入口校验通过后创建外部生成任务，响应只返回 `queueState`。worker 才负责引用解析和归属校验，不下载原图；调用共享 BgFilter HTTP client 前签发 600 秒 OSS URL，multipart 固定为 `image_url + background_mode=complex + seg_model=birefnet + cross_check=off`，不包含 `file` 或 `screen_color`，首次失败立即重试 `1` 次，两次都失败返回最终错误。请求可携带 `projectId`、`targetLayerId`、`assetFolderId`、`assetLabel`、`sourceResourceId` 和 `canvasCompletion`，有 `canvasCompletion` 时完成后按生成占位写入结果图层，否则沿用旧的目标图层替换路径。令牌只在服务端通过 `GENARRATIVE_EDITOR_BGFILTER_TOKEN` 注入，未配置时兼容回退旧 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN`。 +- `POST /api/editor/images/generations`：按提示词调用 VectorEngine 生成图片。带 `model / aspectRatio / imageSize` 的用户生成必须把当前 K 档对应的真实像素直接传给 provider，前端占位与该请求尺寸使用同一映射；不得先请求固定 1K 再放大为 2K。普通图片的 provider 回图先留在内存，尺寸变换成功后只上传变换结果，变换失败则只上传 provider 原图，主结果只写一次 OSS 且不额外创建“原始输出”。角色生成可携带 `model`、`screenColor`、`segModel`、`aspectRatio`、`imageSize` 和 `referenceImageSrcs`；父流程先保存带纯色背景源图，随后只以 object key 向唯一 loopback `bgfilter-worker` 发起一次内部 HTTP RPC；子 worker 在每次真实 provider attempt 前签发短期 OSS URL，并向 BgFilter 传入 `screen_color=`、`seg_model=`。父流程不直连 BgFilter、不签发该 URL，也不重试已被 worker 接收的内部 RPC（连接从未建立时按调度方案 §5.1 有界重连）；透明处理成功时生成透明 PNG，最终失败时按前述多产物降级规则以原图主结果和通用 `warning` 收口。角色、图标图集和 UI 图集的透明处理正常成功但返回尺寸与 provider 原图不同时，只重采样透明图的 alpha 蒙版并应用回 provider 原图的原始分辨率 RGB，不放大低分辨率后处理成品。宣发素材携带 `kind: "publication-material"` 时固定归一为 `gpt-image-2`，不支持 `nanobanana2`，并继续按固定交付像素处理。`nanobanana2` 参考图作为 `inline_data` 进入 `generateContent`，`gpt-image-2` 参考图进入 edits；`nanobanana2` 的 `512 / 1024 / 2K` 是标量清晰度档位，后端保留 provider 输出几何尺寸，不按 `宽x高` 解析。从既有图层重新打开生成器且没有仍存活的对话框快照时，前端按该图层真实 `originalWidth / originalHeight` 恢复比例和清晰度，不得回落到新建面板的 1K 默认值。普通重绘继续走该接口并把当前图层图片作为参考图；图片快速编辑不走该接口。请求可携带 `projectId`、`assetFolderId`、`assetKind`、`generationInputs` 和 `sourceResourceId`，后端生成完成后在响应中返回实际产物的 project / resource / asset 快照。 +- `POST /api/editor/images/background-removals`：接收当前图片的 `objectKey`、`resourceId` 或 `assetId` 候选引用，登录态和稳定引用入口校验通过后创建外部生成任务，响应只返回 `queueState`。父 `external-generation-worker` 负责把候选引用解析为已登记、已校验当前账号归属的私有 OSS object key，只向唯一 `bgfilter-worker` 发起一次内部 HTTP RPC，传递 object key、`maxQueueWaitMs`、公式化 `callBudgetMs` 以及固定的 `background_mode=complex + seg_model=birefnet + cross_check=off`；父侧不下载原图、不签发 URL，也不发送 `file` 或 `screen_color`。子 worker 在每次真实 provider attempt 前签发 600 秒 OSS URL，以默认 `Q=2048` admission 保险丝和 provider 并发 `N=16` 限流，取得 provider permit 后才启动 `callBudgetMs`，并对同一次逻辑调用最多执行两次顺序 provider attempt；成功图片以内部 HTTP 二进制 body 返回父流程，父侧不重试已被 worker 接收的内部 RPC（连接从未建立时按调度方案 §5.1 有界重连）。complex 任意最终失败都直接使父任务失败，不进入阿里云或本地键色 fallback。请求可携带 `projectId`、`targetLayerId`、`assetFolderId`、`assetLabel`、`sourceResourceId` 和 `canvasCompletion`；成功后仍由父流程完成最终 OSS / project resource 持久化，有 `canvasCompletion` 时按生成占位写入结果图层，否则沿用旧的目标图层替换路径。provider 令牌只在子 worker 服务端通过 `GENARRATIVE_EDITOR_BGFILTER_TOKEN` 注入，未配置时兼容回退旧 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN`；父子内部调用另使用独立内部 Token。 - `POST /api/editor/icon-spritesheets/generations`：按图标规范图和素材描述数组生成 spritesheet；api-server 先保存带纯色背景 spritesheet 源图，透明处理成功后再保存透明 spritesheet 并尝试拆分。请求支持 `model`、`screenColor`、`segModel`、`aspectRatio`、`imageSize`、`priceMudPoints`、`projectId`、`assetFolderId` 和 `generationInputs`；`priceMudPoints` 必须来自编辑器生成计费配置中对应生图模型的尺寸档位（如 `nanobanana2` 的 `0.5K / 1K / 2K` 或 `gpt-image-2` 的 `1K / 2K`），后端用 `editor_generation_config` 校验后才调用上游；`nanobanana2` 走原生 `generateContent` 并写入 `generationConfig.imageConfig.aspectRatio/imageSize`，`0.5K` 传 `"512"`；`gpt-image-2` 走 `/v1/images/edits`。透明处理最终失败时只保存并返回原图主结果，不生成透明图或切片；透明图成功但拆分失败时保留整张透明图并返回 `sliceWarning`。响应只返回实际产物对应的 project / resource / asset 快照及可选通用 `warning`。 - `POST /api/editor/ui-designs/assets/extractions`：前端把红色框选轮廓绘入本地临时图后，先将该图上传 OSS 并确认 asset object，再以返回的 `objectKey` 作为参考图入队；Data URL / Blob URL 只允许停留在上传前的浏览器临时态。接口固定 `gpt-image-2` 和自动决策纯色背景素材提取提示词生成素材 spritesheet；api-server 先保存带纯色背景 spritesheet 源图，透明处理成功后再保存透明 spritesheet 并按连通域尝试拆分为 `素材 1..N`，返回结构复用图标 spritesheet 响应。请求必须携带 `screenColor`、`segModel`、`aspectRatio: "1:1"`、`imageSize: "1K" | "2K"` 和 `priceMudPoints`；框选数量不超过 6 个时前端按 `1:1·1K` 与 gpt-image-2 1K 价格提交，超过 6 个时按 `1:1·2K` 与 2K 价格提交。后端必须在调用上游前校验比例、尺寸和泥点价格，只允许 `1:1 / 1K / 2K`。透明处理最终失败时只保存并返回原图主结果，不生成透明图或切片；透明图成功但拆分失败时保留整张透明图并返回 `sliceWarning`。请求可携带 `projectId`、`assetFolderId`、`generationInputs` 和 `spritesheetLabel`，响应只返回实际产物对应的 project / resource / asset 快照及可选通用 `warning`；前端按后端快照落画布，不补造缺失产物。 - `POST /api/editor/images/edits`：按提示词和当前图片的已登记 `objectKey` / `resourceId` 修改图片，返回新的生成图片元数据；图片快速编辑当前只提交 `sourceImageSrc`，不提交隐藏的 `referenceImageSrcs`，并随用户当前选择提交 `model / aspectRatio / imageSize / size`。api-server 必须先归一模型再选择 VectorEngine 协议：`nanobanana2` 调用 `/v1beta/models/{model}:generateContent` 并把原图作为 `inline_data`、比例和清晰度写入 `generationConfig.imageConfig`；`gpt-image-2` 调用 `/v1/images/edits` multipart。gpt-image-2 路径在 provider 边界把目标尺寸和所有 multipart 参考图临时补齐到 16 的倍数，回图后在内存恢复业务目标尺寸；nanobanana2 路径保留 provider 按比例和清晰度返回的几何尺寸。成功时只上传最终结果，尺寸恢复失败时只上传 provider 原图；无论是否发生尺寸恢复都只创建一个 project resource / 账号素材，不显示重复“原始输出”。16 对齐尺寸不得泄漏到正常完成的最终响应、资源或图层 Resolution；变换失败降级时以实际 provider 原图尺寸为准。本地红框标记图必须先上传再提交 objectKey；请求携带 project / asset 上下文时由后端创建新 resource / asset，前端只消费响应快照。 @@ -137,7 +137,7 @@ - 发送消息后，面板先展示本地用户消息和请求等待态，再应用普通 JSON 响应中的 `deltaMessages`；客户端取消等待只终止本次 transport 等待，不把已经确认入队的外部生成任务改成停止态。 - Agent 工具任务完成并懒回填后，消息内缩略图只作纯预览，不显示名称也不点击聚焦图层；前端同时重新读取工程快照和素材库。对话入口触发生成时不创建“即将生成”画布占位，生成完成后由后端 `canvasCompletion` 落新图层。规划或工具失败时消息内必须保留可回读的失败状态和错误气泡，不能只弹一次性 toast 或返回瞬时 `errorMessage`。 - 画布 Agent 会话刷新后能从后端恢复会话标题、消息、附件和生成记录；前端不得根据本地临时状态伪造会话持久化结果。 -- 图片选中后的浮动工具栏按钮顺序固定为：快速编辑、分割线、裁扩按钮、去除背景按钮、UI设计图专属提取素材、角色图专属生成动画、分割线、重绘、下载按钮。裁扩通过画布边界拖拉完成，不再展示四边数值输入；默认自由比例，选择固定比例后拖拉边界保持对应比例，完成后在原素材旁边新增裁扩结果图层，扩展区域透明填充。去除背景调用同源 BFF `POST /api/editor/images/background-removals`，由 api-server 通过共享 BgFilter `background_mode=complex` 链路去背景并持久化结果；有项目上下文时先在画布创建关闭面板的去背景生成占位，完成后由后端通过 `canvasCompletion` 把新 project resource 写入该占位并返回快照，无占位上下文时才用新的 project resource 引用替换当前图层。画布任务侧栏按“排队/生成中”和“已完成”分页，生成中排在排队前，生成中耗时从任务开始时间戳实时计算，排队中不计时；进行中任务只显示阶段文本和已用时，不显示百分比；完成态生成任务副标题显示用户提示词并单行截断；点击任务只聚焦对应画布内容，不激活生成面板或改变任务顺序，聚焦时必须预留图片上方工具栏、底部工具栏和可见生成对话框空间。UI设计图的提取素材必须先进入红框素材框选状态，默认启用矩形框选，右侧框选工具与快速编辑统一且可再次点击取消启用态，当前启用工具按钮必须保持高亮。素材提取面板必须在素材下方，使用与生成新素材一致的面板宽度和底部模型 / 按钮样式，提示语显示 `使用框选工具框选你希望从画面中提取的素材`，并展示按原图坐标准确裁剪的框选区域截图预览、固定模型 `gpt-image-2`、左下角计划规格 `1:1·1K/2K` 和 `提取 · N泥点` 按钮，不显示额外取消按钮；点击素材和面板以外的画布区域即退出 UI 素材提取。至少框选一个区域后才可提交，前端把红色轮廓绘入原图后固定走 `gpt-image-2` 和自动决策纯色背景素材提取提示词。透明处理及拆分正常完成时，透明 spritesheet 和拆分素材都按后端快照保留为画布图层；透明处理失败时仅原图作为主结果，既不要求透明图也不要求切片；透明图成功但拆分失败时保留整张透明图并展示拆分告警。三种完成结果都以后端项目快照为准。 +- 图片选中后的浮动工具栏按钮顺序固定为：快速编辑、分割线、裁扩按钮、去除背景按钮、UI设计图专属提取素材、角色图专属生成动画、分割线、重绘、下载按钮。裁扩通过画布边界拖拉完成，不再展示四边数值输入；默认自由比例，选择固定比例后拖拉边界保持对应比例，完成后在原素材旁边新增裁扩结果图层，扩展区域透明填充。去除背景调用同源 BFF `POST /api/editor/images/background-removals`；父流程解析并校验私有 OSS object key 后只调用一次唯一内部 `bgfilter-worker` 的 complex 链路，子 worker 负责签发 600 秒 URL、`N / Q` 限流和最多两次顺序 provider attempt，complex 失败不接入 fallback，成功二进制返回后仍由父流程完成最终持久化。有项目上下文时先在画布创建关闭面板的去背景生成占位，完成后由后端通过 `canvasCompletion` 把新 project resource 写入该占位并返回快照，无占位上下文时才用新的 project resource 引用替换当前图层。画布任务侧栏按“排队/生成中”和“已完成”分页，生成中排在排队前，生成中耗时从任务开始时间戳实时计算，排队中不计时；进行中任务只显示阶段文本和已用时，不显示百分比；完成态生成任务副标题显示用户提示词并单行截断；点击任务只聚焦对应画布内容，不激活生成面板或改变任务顺序，聚焦时必须预留图片上方工具栏、底部工具栏和可见生成对话框空间。UI设计图的提取素材必须先进入红框素材框选状态，默认启用矩形框选，右侧框选工具与快速编辑统一且可再次点击取消启用态，当前启用工具按钮必须保持高亮。素材提取面板必须在素材下方，使用与生成新素材一致的面板宽度和底部模型 / 按钮样式，提示语显示 `使用框选工具框选你希望从画面中提取的素材`，并展示按原图坐标准确裁剪的框选区域截图预览、固定模型 `gpt-image-2`、左下角计划规格 `1:1·1K/2K` 和 `提取 · N泥点` 按钮，不显示额外取消按钮；点击素材和面板以外的画布区域即退出 UI 素材提取。至少框选一个区域后才可提交，前端把红色轮廓绘入原图后固定走 `gpt-image-2` 和自动决策纯色背景素材提取提示词。透明处理及拆分正常完成时，透明 spritesheet 和拆分素材都按后端快照保留为画布图层；透明处理失败时仅原图作为主结果，既不要求透明图也不要求切片；透明图成功但拆分失败时保留整张透明图并展示拆分告警。三种完成结果都以后端项目快照为准。 - 重绘生成资源后，右侧出现新生成结果图层，并自动 fit 原图 + 新图，且重绘面板保持打开。 - 快速编辑 / 重绘站内 public 示例图、历史 generated 图或 OSS generated 图时，优先复用当前图层已有 `objectKey` / `resourceId` / `sourceAssetId`；尚未登记且没有稳定引用的浏览器本地图片或普通 public 图片路径都必须先上传并取得 objectKey。前端不得再把正式对象下载成 `data:image/*;base64,...` 后提交，也不得把 Data URL / Blob URL 写入外部生成持久任务 JSON；后端收到引用后统一做 owner 归属校验并签名读取。 - 快速编辑不保留额外参考图入口；点击修改时只把原图或红框序号标注图作为 `/api/editor/images/edits` 的 `sourceImageSrc` 提交给后端。 diff --git a/docs/technical/【后端架构】BgFilter受限资源调度方案-2026-07-21.md b/docs/technical/【后端架构】BgFilter受限资源调度方案-2026-07-21.md new file mode 100644 index 000000000..948fdbdd5 --- /dev/null +++ b/docs/technical/【后端架构】BgFilter受限资源调度方案-2026-07-21.md @@ -0,0 +1,542 @@ +# BgFilter 受限资源调度方案（同步内部 HTTP 原地等待版） + +更新时间：`2026-07-22` + +状态：`已实施，待生产压测` + +> 本文替代此前讨论的“SpacetimeDB 持久子任务 + raw 结果 OSS”以及更早的“父 job checkpoint / continuation”方案。首版改为父流程在原调用栈内同步等待唯一 `bgfilter-worker` 的内部 HTTP 响应。代码与部署接线已经实施；完成本文生产压测和验收门禁前，不视为可上线实现。 + +## 1. 决策摘要 + +| 决策项 | 首版结论 | +| --- | --- | +| 调度单位 | 一次逻辑 BgFilter 调用；角色动画为单帧 | +| 父流程 | 保持原 future、调用栈、lease 和 `attempt`，同步等待内部 HTTP | +| 通用 worker 槽 | 等待期间继续占用；父 heartbeat 继续运行 | +| 请求输入（父 → 子） | 只传私有 OSS `objectKey`、BgFilter 参数、排队预算 `maxQueueWaitMs`、调用预算 `callBudgetMs` 和有界审计关联；不重复传源图字节，也不传签名 URL | +| 成功输出（子 → 父） | 内部 HTTP body 直接传回 BgFilter 结果图片的原始字节；不使用 Base64、不返回结果 object key、不先写 raw OSS | +| BgFilter worker | 首版只运行一个内部 HTTP worker 实例 | +| 并发 | 进程内 `Semaphore(N)`，并增加有界 admission 上限 `Q` | +| 重试 | 子 worker 对一次逻辑调用最多做两次顺序 provider attempt；父侧不重试已被 worker 接收的内部 RPC，仅连接从未建立时按预算有界重连（§5.1 / §7.1） | +| 超时 | 双预算：父侧派生排队预算 `maxQueueWaitMs` 与调用预算 `callBudgetMs`；attempt 上限由 `N × est × 2` 公式运行时派生（est 默认 `5s`），排队不侵蚀调用时间 | +| flat / complex 熔断 | 迁到唯一子 worker；两种模式共享阈值和 `120s` cooldown，但分别维护独立进程内状态 | +| 业务语义 | 父流程继续负责 Alpha / 尺寸恢复、flat fallback、最终 OSS、画布写回、计费和父终态 | +| 动画失败 | 首版保持当前“所有已提交帧都等待并排空”语义，不新增跨帧取消组 | +| 崩溃恢复 | 不查询、不恢复 BgFilter 结果；父 job 沿用现有 lease、失败和退款语义 | +| 数据模型 | 不新增 SpacetimeDB 表，不修改 `external_generation_job` schema | +| 配置加载 | 子 worker 先加载 API 基础环境，再加载 worker 专属环境覆盖；共享超时保持单一来源 | + +首版明确不实现： + +- `bgfilter_task_group`、`bgfilter_request_task` 或 `bgfilter_capacity_slot`； +- 持久队列、claim、lease、reaper、subscription 或 waiter registry； +- raw 中间结果 OSS、raw TTL 或 raw 持久化预留； +- 父流程 checkpoint、`waiting_bgfilter`、continuation、requeue 或恢复不计 attempt 状态机； +- 多实例 BgFilter worker、共享持久熔断或 QPS token bucket； +- 内部 RPC 失败后偷偷回退为父进程直连 BgFilter。 + +## 2. 背景与目标 + +### 2.1 当前问题 + +角色动画当前使用 `buffer_unordered(frame_count.max(1))`。单个父 job 会让 `32 / 40 / 48` 个帧 future 同时进入 BgFilter 调用，因此限制 `external-generation-worker` 的父 job 并发不能限制实际 BgFilter 请求并发。 + +编辑器 queue job 固定 `max_attempts = 1`。普通 requeue 会改变 attempt、失败和退款语义；checkpoint / continuation 又会扩大父状态机和计费恢复改动。父流程既然可以接受继续占用 worker 槽，首版无需为 BgFilter 建第二套持久任务系统。 + +checkpoint / continuation 不是当前已有能力，而是旧版方案需要新增的恢复状态机；同步原地等待版不新增它们。旧版 `bgfilter_task_group` 用于聚合动画帧，`bgfilter_request_task` 用于持久调度一次逻辑调用（动画时为单帧）；本版继续由父 future 聚合帧结果，由内部 HTTP handler、`Q` admission 和 `Semaphore(N)` 调度单次调用，因此两张表都不再需要。 + +当前 BgFilter 成功结果本来就是 HTTP 图片二进制，调用方读取后再由父流程做最终处理和 OSS 持久化。因此让专用 worker 通过内部 HTTP 直接返回二进制，最接近现有数据流。 + +### 2.2 目标 + +- 所有现役 flat / complex 调用统一经过唯一内部 `bgfilter-worker`。 +- `48` 帧可同时提交内部请求，但健康唯一 worker 持有的 BgFilter HTTP future 不超过 `N`。 +- 父流程不重建，不改变父 job schema、attempt、计费和用户可见任务。 +- 保留现有 flat 两次尝试后“阿里云通用抠图 → 本地键色”、complex 两次失败直接失败的语义。 +- External v1、inline 和 queue 路径复用同一个低层 client，不能绕过限流。 +- 不把源图片、签名 URL、Token 或图片 Base64 写入数据库、JSON、审计 payload 或日志。 + +### 2.3 非目标 + +- 不释放等待中的通用 worker 槽。 +- 不保证父进程、子 worker 或内部连接崩溃后的结果恢复。 +- 不绝对限制客户端 timeout 后仍可能在 BgFilter 服务端继续的远端计算。 +- 不做跨 job 公平调度；首版有界等待采用 FIFO。 +- 不限制阿里云抠图、本地键色、OSS 或其它 provider 的并发。 +- 不改变前端 DTO、External OpenAPI、任务列表或收费归属。 + +## 3. 总体架构 + +```mermaid +flowchart LR + P["父流程：queue job / inline / External v1"] + O["已持久化的私有 OSS 源对象"] + C["内部 HTTP client"] + W["唯一 bgfilter-worker\n有界 admission(Q) + Semaphore(N)"] + B["BgFilter provider\n最多两次顺序 attempt"] + F["父流程原有后处理\nfallback / finalizer / 最终 OSS / 业务写回"] + + P --> O + P --> C + C -->|"objectKey + 参数 + maxQueueWaitMs + callBudgetMs"| W + W --> B + B --> W + W -->|"图片二进制或类型化 JSON 错误"| C + C --> P + P --> F +``` + +职责边界： + +- 父流程负责源对象已持久化、owner 校验、请求预算、flat fallback、Alpha / 尺寸恢复、动画 finalizer、最终 OSS / `asset_object` / 画布写回、计费和父终态。 +- `bgfilter-worker` 负责内部协议校验、OSS 签名、并发与排队上限、BgFilter 协议、两次顺序尝试、按模式隔离的熔断、provider 失败审计和结果图片校验；失败审计使用进程级 `1024` 个任务硬上限与 worker 独立 tracking outbox。 +- SpacetimeDB 不参与本次内部调度；不新增表、reducer、procedure、facade 或生成 bindings。 + +`bgfilter-worker` 从实现形态看是只监听内部地址的同步 worker service，不是队列 consumer。父 worker 调另一个 worker 在这里是允许的：父进程明确选择保留调用栈和槽位，因此同步内部 HTTP 正是首版的最小交接方式。 + +这里的“同步等待”是控制流上的 request / response `await`：不会阻塞 OS 执行线程或整个父进程，但父 job future 仍留在通用 worker 的并发集合中，占用一个父 worker 槽，并由现有 heartbeat 继续续租。 + +首版进程角色仍复用现有完整 `AppState` 构造路径，以获得 OSS、BgFilter provider、SpacetimeDB 审计、HTTP client 和可观测性依赖；进程角色只阻止它挂载公共路由、claim 外部生成 job 或启动其它后台循环，并不等于它只需要几个调度环境变量。因此生产 unit 必须先加载 `/etc/genarrative/api-server.env` 中父子共享的 `N / est` 与基础配置，再加载 `/etc/genarrative/bgfilter-worker.env` 覆盖监听地址、`Q`、flat / complex 统一熔断参数和 worker 独占参数。后续若拆出轻量专用 state，可再缩小共享配置依赖，首版不能假设该拆分已经存在。 + +### 3.1 图片数据流口径 + +请求和响应采用不同口径，不能把“请求不传源图字节”理解成“响应也不能传图片字节”： + +| 阶段 | 传递内容 | 是否新增持久化 | +| --- | --- | --- | +| 父流程 → `bgfilter-worker` | JSON：源图 `objectKey`、参数和预算 | 否 | +| `bgfilter-worker` → BgFilter provider | 子 worker 现场签发的源图短期 URL | 否 | +| BgFilter provider → `bgfilter-worker` | 结果图片字节 | 否，只在子 worker 有界内存中读取和校验 | +| `bgfilter-worker` → 父流程 | `2xx` HTTP body 中的原始结果图片字节 | 否，父侧直接读入有界字节缓冲 | +| 父流程 → OSS / 业务写回 | 现有后处理后的最终图片 | 是，仍只走父流程现有最终持久化路径 | + +因此，本方案所说的“直接返回二进制”就是直接传图片字节：父侧内部 client 的成功结果是 `Bytes` / `Vec` 一类有界内存缓冲及可信的图片类型，而不是 Base64 字符串、临时 object key 或子任务结果记录。这里不是把 provider 响应边读边透明转发；子 worker 要先完整读取并校验结果，确认本次 attempt 成功后，再把同一份图片内容作为内部 HTTP body 返回，以保留第二次顺序尝试和无效图片拦截能力。 + +输入与输出采用非对称传输是有意设计：源图在调用前已经持久化到私有 OSS，传 `objectKey` 可避免重复上传和跨进程复制大块输入；输出则是父流程马上消费的短生命周期结果，直接用内部 HTTP 二进制 body 返回最小，不需要先制造一份 raw OSS 资产。 + +## 4. 内部 HTTP 契约 + +### 4.1 请求 + +首版新增内部接口： + +```http +POST /internal/bgfilter/v1/remove-background +Content-Type: application/json +Authorization: Bearer +``` + +示例： + +```json +{ + "requestId": "bgfilter-call-uuid", + "sourceObjectKey": "generated-character-drafts/editor/source.png", + "backgroundMode": "flat", + "screenColor": "#00ff00", + "segModel": "birefnet", + "crossCheck": true, + "maxQueueWaitMs": 540000, + "callBudgetMs": 321000, + "auditContext": { + "userId": "bounded-internal-id", + "profileId": null, + "requestId": "parent-request-id" + } +} +``` + +约束： + +- 当前部署只有一个配置内私有 OSS bucket，因此请求只传 `sourceObjectKey`，子 worker 从自身 OSS 配置取 bucket 并生成短期签名 URL。 +- 如果未来确实支持多个 bucket，新增字段也必须由服务端 allowlist 校验；不能接受调用方提供任意下载 URL。 +- `backgroundMode` 只允许 `flat / complex`；`segModel` 继续沿用当前 `birefnet / anime-seg` allowlist；complex 固定使用当前参数组合。 +- `screenColor` 只对 flat 必填；complex 不得误接 flat 参数，两种模式的熔断状态必须隔离。 +- `maxQueueWaitMs` 与 `callBudgetMs` 都是相对预算，不是跨机器绝对时间。前者从 admission 起约束排队阶段（worker 还会用 §5.2 的动态估计对其取 min）；后者从取得 provider permit 起计时，覆盖签名、两次 attempt、结果校验和响应构造。`callBudgetMs` 是父侧按 `N / est` 公式算出的“配置指纹”，仅作核对：worker 始终以自己按同一公式派生的值执行，不一致时不拒绝请求，而是记录 warn 日志并递增漂移指标。发布调优 N / est 时新旧进程共存的瞬态漂移因此不会误伤在途任务；持久性漂移的硬拦截由部署脚本的共享 env 对齐校验承担。 +- JSON body 设置很小的固定上限；源图字节不进入该 JSON。 + +签名 URL 必须在取得 provider permit 后、每次 attempt 前生成，避免排队期间过期。签名 URL 只存在于子 worker 内存和发往 BgFilter 的请求中。 + +### 4.2 成功响应 + +成功直接返回经过大小、MIME 和像素尺寸校验的图片字节： + +```http +HTTP/1.1 200 OK +Content-Type: image/png + + +``` + +`image/png` 是常见响应示例。为保持当前行为，首版可以返回实际受支持的 `image/png`、`image/webp` 或 `image/jpeg`，但必须保证响应头与实际解码类型一致；不使用 JSON、Data URL 或 Base64 包装，也不为传输先落 raw OSS。 + +子 worker 必须完整读取并校验 provider body 后才向父侧返回成功，这样 provider body 中途断开时仍可在预算内执行第二次 attempt。父侧内部 client 对 `2xx` 响应读取有界二进制 body，并把字节直接交回现有 Alpha / 尺寸恢复与 finalizer；父侧仍执行一次独立校验，不能只信任内部响应头。任何一侧都不得把成功 body 转成 Base64、JSON 数组或临时 OSS 引用。 + +### 4.3 错误响应 + +失败返回有界 JSON，稳定错误码只保留： + +- `provider_exhausted`：两次真实 provider attempt 都失败； +- `circuit_open`：当前请求模式的熔断已打开，未发送 provider 请求； +- `deadline_exceeded`：排队、provider 或响应阶段预算耗尽，使用 `phase = queue | provider | response`；`phase = queue` 时附带触发边界 `bound = estimate | parent`，区分动态过载探测与父上限； +- `overloaded`：admission 保险丝 `Q` 触达（默认 `2048`，正常业务不应出现）； +- `cancelled`：保留错误码，首版子 worker 不产生。首版没有显式取消信号通道，单纯 TCP 断连后 handler future 被 drop、也无法再返回响应；该码为第二阶段 group cancellation 预留，父侧已按“不启动 fallback”实现映射； +- `invalid_request`：内部契约不合法； +- `unauthorized`：内部 Token 缺失或不匹配； +- `invalid_result`：provider 回图超限、MIME / 魔数不匹配或无法安全解码； +- `internal_error`：内部配置、OSS 签名或其它非 provider 故障。 + +示例： + +```json +{ + "error": { + "code": "deadline_exceeded", + "phase": "queue", + "bound": "parent", + "attemptsStarted": 0, + "message": "BgFilter 内部请求预算已耗尽" + } +} +``` + +HTTP status 只作粗粒度传输分类，父侧以稳定 `error.code` 映射业务语义。错误中不得包含签名 URL、Token、图片字节、完整 provider body 或无界错误文本。 + +## 5. 超时所有权 + +### 5.1 双预算分工 + +本版把一次内部 RPC 的时间拆成两笔互不挪用的预算，排队不再侵蚀调用时间： + +1. 父 worker 继续管理父 job 总预算：普通 `900s`、长任务 `1800s`。 +2. 排队预算 `maxQueueWaitMs`：父侧按自己的剩余绝对预算派生，只约束“在 worker 内等待 provider permit”的阶段。 +3. 调用预算 `callBudgetMs`：从取得 provider permit 时起算，覆盖签名、最多两次 provider attempt、结果校验和响应构造；排队时长不消耗它，每个真正开跑的请求都保证有完整的两次 attempt 窗口。 + +所有派生值都在运行时由 `N` 与单图估时 `est` 两个配置计算，代码不得硬编码计算结果： + +```text +est = GENARRATIVE_EDITOR_BGFILTER_SINGLE_IMAGE_ESTIMATE_MS（默认 5000ms） +attempt = N × est × 2 +callBudgetMs = 2 × attempt + 1s worker 响应构造窗 +maxQueueWaitMs = 父剩余绝对预算 − callBudgetMs − 父侧预留 + flat：39s = 37s fallback（阿里云 30s + 本地 7s）+ 2s 传输窗 + complex：2s 传输窗 +queue timeout = min((进入 provider 等待队列时的队长 + 5) × est × 2, maxQueueWaitMs) ← worker 侧计算 +parent client timeout = maxQueueWaitMs + callBudgetMs + 2s 传输窗 +``` + +`maxQueueWaitMs <= 0` 时父侧不得发送请求：flat 直接进入既有“阿里云 → 本地”fallback，complex 直接失败；不允许把注定超时的请求塞进队列。flat 扣除的 `39s` 父侧预留由 `37s` fallback 窗口和 `2s` 内部响应传输窗组成；complex 没有 fallback，只保留 `2s` 传输窗。 + +父侧对「TCP 连接从未建立」的失败（worker 重启、主机开机排序窗口内的连接拒绝 / 不可达 / connect 阶段超时）做有界自动重试：这类请求从未进入 worker admission，无副作用、天然幂等。每轮重试前按上式重算 `maxQueueWaitMs`，重试消耗的是父预算的自然余量，不突破「预算不足不发送」的不变量；退避序列本身有界，父无绝对 deadline 时也不会无限等待。配额按「本进程是否已连通过 worker」（收到任意 HTTP 响应即算）分两档： + +- **冷启动档**（首连前，覆盖主机开机竞态与 worker 首次拉起）：flat 用完整基础序列（总额约 `22.5s`），complex 在基础序列后追加 `8 × 5s` 平台退避（总额约 `62.5s`，覆盖慢开机）。 +- **常规档**（首连后，运行中途故障要快速收口）：flat 只取前 2 项（额外延迟 `≤1.5s`，不侵蚀 `39s` fallback 预留），complex 用完整基础序列（约 `22.5s`，覆盖 systemd `RestartSec=5s` + 进程启动窗口，更长的停机应快速失败而非挂住父 job）。 + +档位在单次调用开始时锁定，中途不切换。收到任何 HTTP 响应(含 5xx)或其它错误类别一律不重试，边界见 §7.1。 + +queue job 的总预算从父 job 开始执行时起算，不从开始申请 BgFilter 时重新计时。现有父 worker 还会把 provider deadline 设在 job deadline 前 `60s`，为最终写回和终态保留时间。同步 RPC 实现必须显式读取父侧剩余 provider budget 派生 `maxQueueWaitMs`，不能忽略 `RequestContext` deadline。 + +本版没有 BgFilter 子任务等待 claim 的阶段。几个起算点必须区分：父 job 在数据库中尚未被 claim 的等待不消耗 job 执行预算；父 job 开始实际执行后，生图及 BgFilter 之前的耗时都会消耗父总预算；父内部 HTTP client timeout 从开始发送请求起覆盖 loopback 传输、worker admission、排队、provider 和回包；`callBudgetMs` 计时只在子 worker 取得 provider permit 后启动，attempt timer 只在真正开始一次 provider HTTP 时启动。父侧不是放弃超时，而是不再直接执行 provider 单次 attempt 的计时器。 + +父总 deadline 到达时，现有 worker 会停止续租、释放 JoinSet 槽并把 work 交给 lease fencing 仲裁，不是立刻杀死所有内部工作。正常情况下内部 RPC 自身应在更早的 provider deadline 内结束，避免进入这条脱管路径。 + +### 5.2 排队预算与自适应过载探测 + +worker 通过鉴权与 `Q` admission 后，在请求完成 JSON 校验并进入 provider permit 等待队列时取得队长快照；排队 deadline 仍从 `Q` admission 时刻起算。双重上界为： + +```text +queue timeout = min((进入 provider 等待队列时的队长 + 5) × est × 2, maxQueueWaitMs) +``` + +- 动态项 `(队长 + 5) × est × 2`：按进入 provider permit 等待队列时的当前队列深度估计合理等待时间。`+5` 覆盖已在 provider 执行中、尚未释放 permit 的在途请求；`×2` 是安全系数。队列短但等待仍超出该值，说明 provider 实际速度远低于估计，趁父预算仍够时尽早返回 `deadline_exceeded (phase = queue)` 让 flat 走 fallback——动态项因此充当自适应过载探测器，替代旧 `Q` 容量拒绝的快速降级职责。tokio semaphore 按进入 provider 等待队列的顺序提供 FIFO；快照之后的后来者不影响本请求的动态上界。 +- 父上限 `maxQueueWaitMs`：父侧愿意等多久由父剩余预算决定，队列再长也不能超过它。 + +排队超时的错误响应必须标注触发边界（动态估计或父上限），便于区分“provider 变慢”与“父预算太紧”。 + +### 5.3 子 worker attempt timeout + +子 worker 取得 provider permit 后，以本机单调时钟起算 `callBudgetMs` 的 RPC deadline。每次 attempt 的 timeout 为： + +```text +attempt = N × est × 2 +attemptTimeout = attempt （RPC 剩余时间 > attempt） + = RPC 剩余时间 - 1s 响应构造窗口 （已无法容纳完整 attempt 的防御分支） +``` + +`callBudgetMs = 2 × attempt + 1s` 的额外 `1s` 用于吸收两次 attempt 之间的签名与调度开销；只要 RPC 剩余时间仍大于一次完整 `attempt`，第二次就必须取得完整窗口，不能先机械扣掉 `1s`，否则满窗 timeout 会被误判为预算截短并漏计熔断。已无法容纳完整 attempt 时才进入截短防御分支；被截短的 timeout 返回 `deadline_exceeded` 且不计入熔断。 + +attempt 公式的依据：BgFilter 服务端高并发时单图处理约 `1-3s`、网络约 `3-5s`；`N` 个在途请求在服务端排队的最坏等待按 `N × est` 估计，`×2` 为安全系数。`N = 16`、`est = 5s` 时 attempt 为 `160s`，与旧固定 `180s` 接近，单请求行为基本持平。 + +flat 调用还要由父侧从可分配预算中扣除 `39s`：阿里云 request timeout（默认 `30s`）与本地处理余量 `7s` 构成 `37s` fallback 窗口，另有 `2s` 内部响应传输窗，避免排队吃完全部预算后名义上有 fallback、实际上已无时间执行。 + +`N` 与 `est` 必须由父子进程使用同一份有效值：父侧要用它们算 `callBudgetMs` 与 client timeout，worker 要用它们算 attempt 与队列估时。两者都放在共享 API 基础环境中作为单一来源，worker 专属环境不得悄悄覆盖。worker 侧把请求携带的 `callBudgetMs` 与本进程公式值比对，不一致只告警并计指标、仍以本进程值执行——运行时校验必须容忍发布重启窗口内的瞬态漂移，持久漂移由部署脚本对齐校验在启动前拦截。 + +inline / External v1 当前没有显式 `RequestContext` deadline 时，内部 RPC 仍必须有界：`callBudgetMs` 同公式，`maxQueueWaitMs` 默认取与 `callBudgetMs` 等长的额度，因此默认父 client timeout 为 `2 × callBudgetMs + 2s`；后续若同步请求显式注入 deadline，再按同一 `maxQueueWaitMs` 公式从剩余预算派生。 + +### 5.4 动画旧增量 + +旧实现曾把动画单次 BgFilter timeout 设为： + +```text +180s + 2000ms × frame_count +``` + +该增量原本用于容纳 32 / 40 / 48 个请求直接进入 BgFilter 后的服务端排队。当前实现已把排队前移到内部 worker 并删除该增量；所有真实 provider attempt 统一使用 `N × est × 2` 公式上限，动画尾部请求能等待多久由各自的排队预算决定。 + +## 6. 并发、排队与熔断 + +### 6.1 `N` 与 `Q` + +唯一子 worker 使用一个真并发上限和一个保险丝： + +- `N`：BgFilter provider 并发 permit（生产 `16`）；handler 取得 permit 后才允许开始第一次 provider HTTP。 +- `Q`：admission 保险丝（默认 `2048`），只防调用方 bug 造成的连接风暴耗尽 fd / 连接资源，正常业务永远打不到；触达时立即返回 `overloaded`。部署与 Provision 会把历史模板默认 `128` 定向迁移为 `2048`，其它显式定制值保留。`Q` 不再承担容量策略职责——排队请求的真正上界是各自的 queue timeout（见 §5.2），队列因 deadline 自排水，长度上界约为到达率 × 父预算时长，而到达率被父侧扇出锁死。 + +同一次逻辑调用的 `N` permit 从第一次 provider attempt 前一直持有到两次尝试结束、provider body 读完、完成结果校验，并随内部成功 response body 一直持有到发送完成或 body drop。第二次 attempt 不重新排队。保守延长 permit 生命周期可以防止父侧慢读时积累多份完整结果；loopback 传输很短，接受这点吞吐代价。 + +内部 listener 仍在解析 JSON body 前完成鉴权与 `Q` admission，设置固定 listen backlog 和小型 body limit；`Q` 不替代内核 listen backlog。请求完成 JSON 校验后才进入 provider semaphore 等待队列，该队列采用 tokio semaphore 的 FIFO 语义；不增加持久优先级队列或公平调度状态机。 + +当前父 worker 可能提交的最大帧请求数并不只有 `96`： + +| 场景 | 潜在同时提交的动画帧调用 | +| --- | ---: | +| 一个动画父 job | `48` | +| 一个默认 external-generation-worker，父并发 `2` | `96` | +| controller 最多 `8` 个父 worker、每个并发 `2` | `768` | + +理论最大 `768` 远低于保险丝 `2048`，正常业务不会触发 `overloaded`；过载时的降级路径改由 §5.2 的动态排队探测承担——排队超出合理预期的 flat 请求提早进入 fallback，complex 失败。 + +容量评估：`N = 16`、单图真实耗时约 `5-8s` 时，`48` 帧的排队时间约为 `ceil(48 / 16) × 单图耗时`，远低于父 job 预算。上线值仍必须用真实 BgFilter P95、动画帧数和主机内存压测冻结；`est` 估计过小时动态探测会提早降级、attempt 超时会误伤慢图并触发熔断，因此 `est` 校准是压测的首要目标。 + +### 6.2 并发承诺边界 + +首版只能承诺： + +```text +部署中只有一个健康 bgfilter-worker 时， +该进程当前持有的 BgFilter HTTP future <= N。 +``` + +它不能绝对保证 BgFilter 服务端实际计算始终 `<= N`：客户端 timeout、进程退出或网络断开后，远端可能继续计算，而本地 permit 已被释放。若必须严格限制服务端计算，只能把全局 semaphore 放到 BgFilter 服务本身，或让 BgFilter 支持 request id、取消和状态查询。 + +两个子 worker 实例会得到 `2N`，因此首版使用固定内部监听地址和非模板化 systemd unit；同机第二实例应因固定端口 bind 失败。发布必须 `stop old -> 等待排空/退出 -> start new`，不能让新旧进程重叠。生产 `N` 或 `est` 缺失、为 `0` 时 fail-closed；`Q` 可缺省（默认 `2048`），显式配置时必须 `>= N`。 + +### 6.3 熔断 + +熔断是故障保护：flat 或 complex 的真实 provider attempt 连续失败达到阈值后，当前模式在 cooldown 内暂时不再请求 BgFilter，而是快速返回 `circuit_open`，避免故障 provider 持续占满并发和超时。flat 由父流程继续进入“阿里云 → 本地”fallback；complex 仍直接失败，不获得 flat fallback。 + +保持当前语义： + +- flat / complex 共享同一阈值与 cooldown 配置，但分别维护独立的 `consecutive_failures / open_until`；任一模式的失败或成功只更新自身状态，不影响另一模式。 +- 两种模式都在取得 permit、即将发送第一次 provider HTTP 前重新检查自身熔断，避免排队请求在熔断打开前全部通过旧检查。 +- 已经获准执行的逻辑调用，即使第一次失败使熔断打开，也仍允许在预算内完成自己的第二次顺序 attempt；后续请求快速返回 `circuit_open`。 +- 每个真实失败 attempt 计一次失败，保持当前计数口径；任一真实 attempt 成功后只重置当前模式。 +- 只有拿到完整公式 attempt 上限（`N × est × 2`）后发生的 provider timeout，以及真实传输失败、非 2xx 和无效 / 超限图片计入。因 `callBudgetMs` 剩余不足而被截短的 timeout 返回 `deadline_exceeded`，不更新熔断；保险丝拒绝、排队超时、客户端取消、鉴权和本地配置错误同样不计入。 +- 进程重启后熔断状态清零是首版接受行为。 + +flat / complex 统一使用的 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD=3` 与 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS=120` 属于 `bgfilter-worker` 运行参数；父 API / external-generation worker 不再读取或更新熔断。生产示例必须把这两个值放进 worker 专属环境；deploy / Provision 只把历史模板默认 cooldown `300` 定向迁移为 `120`，保留其它显式自定义值。 + +首版不增加 QPS 限制。若 provider 以后要求 QPS，需要另加 token bucket；不能把并发 semaphore 当作 QPS。 + +## 7. 断连、崩溃与动画语义 + +### 7.1 内部 RPC 断连 + +- 连接已建立后的断连不得自动重试整次内部 HTTP：此时结果未知，重试可能让一次逻辑调用从最多两次 provider attempt 扩大为四次，并可能突破瞬时并发预期。唯一例外是 TCP 连接从未建立的失败（连接拒绝 / 不可达 / connect 阶段超时）：请求从未进入 worker admission，结果确定为「未发生」，父侧按 §5.1 的预算约束有界退避重试，用于跨过 worker 重启与主机开机排序窗口；收到任何 HTTP 响应后即回到本条禁令。 +- 尚在等待 permit 的请求到达自身 deadline 后必须取消，不再发送 provider 请求；运行时若能可靠观察客户端断连，也可提前取消，但正确性不能只依赖断连事件。 +- 已经开始的 provider attempt 必须继续读取到完成或本次 attempt timeout，并持有 permit；可观察到的 handler / client drop 只丢弃最终结果，不能让已启动请求变成无人管理的本地 future。 +- deadline 已被子 worker 观察到后，不再开始第二次 attempt。首版没有显式 cancellation signal 通道；单纯 TCP 断连只能 best-effort 阻止二试（handler future 被 drop 后自然不再开始新 attempt），Axum / Hyper 不保证立刻通知 handler，因此不能承诺所有断连都阻止二试，排队阶段的 queue timeout 与 permit 后的 `callBudgetMs` deadline 是最终可靠的停止条件。 + +实现时，已启动 provider attempt 应由持有 permit 的独立 task 管理；request handler 可观察到的 Drop / cancellation signal 只影响“是否继续重试和是否返回结果”，不直接丢弃已经开始的 provider future。`callBudgetMs` deadline 是最终可靠的停止条件。 + +### 7.2 进程崩溃 + +- 父进程崩溃：内部连接最终断开，父 job 按现有 heartbeat、lease、`max_attempts = 1`、失败和退款语义收口。 +- 子 worker 崩溃或重启：已在途的内部 RPC 失败；父侧不查询、不恢复、不重发同一次 RPC。重启窗口内连接从未建立的新调用按 §7.1 的例外有界重试。 +- 子 worker 成功但响应在网络中丢失：结果视为未知；flat 进入原 fallback，complex 失败。 +- 子 worker 不得反向 complete / fail 父 job，也不得写画布、业务资源或账单。 + +### 7.3 动画首版范围 + +动画继续让最多 `48` 个 frame future 提交内部 HTTP，并保持当前 collect / drain 行为：所有已提交的帧调用都等待自己的成功、失败或 deadline 后，父流程再按稳定帧序号选择根因并失败。首版不增加 `groupId`、跨请求 registry 或 cancel endpoint，也不宣称“某一帧失败后立即取消仍在 worker 排队的兄弟帧”。 + +这是为了把改动限制在低层 BgFilter 调用和调度服务。若真实观测证明排队兄弟帧浪费严重，可在第二阶段增加纯内存 `groupId + CancellationToken`：取消尚未取得 permit 的请求，已经开始的 provider attempt 仍排空。该升级仍不需要数据库表，但需要同时修改父侧动画收集逻辑，因此不并入首版。 + +## 8. 业务语义保持 + +| 场景 | 内部响应 | 父流程行为 | +| --- | --- | --- | +| flat 单图 / 动画帧 | 图片二进制 | 继续现有 Alpha / 尺寸恢复、finalizer 和最终持久化 | +| flat，父业务预算仍有效 | `provider_exhausted / circuit_open / deadline_exceeded / overloaded / invalid_result / internal_error` 或内部断连 | 记录对应故障后进入现有“阿里云通用抠图 → 本地键色”；这些内部错误本身不都计入熔断 | +| flat | `cancelled`（保留码，首版子 worker 不产生），或父 job cancellation / 绝对 deadline 已生效 | 立即向上退出，不再启动阿里云或本地 fallback | +| flat | `invalid_request / unauthorized` | 作为内部契约或部署配置错误失败，不 fallback、不计入 BgFilter 熔断 | +| complex 手动去背景 | 图片二进制 | 父流程继续最终 OSS、资源和画布写回 | +| complex 手动去背景 | 任意非成功或断连 | 父流程直接失败；provider 失败只累计 complex 熔断，不得接 flat fallback 或修改 flat 熔断 | +| 角色 / 图标 / UI 后处理最终失败 | BgFilter 与 fallback 都未得到可用结果 | 保留已持久化 provider 原图，以现有 `completed + warning` 收口 | +| 动画任一帧最终失败 | 该帧完整 fallback / finalizer / PUT 仍失败 | 排空其它已提交帧后，整项动画按现有语义失败退款 | + +父侧移除现有 flat / complex BgFilter retry loop 和本地 flat 熔断，避免父侧两次 × 子 worker 两次变成四次。所有入口只替换共同的低层 BgFilter helper；这样 External v1 直接调用 `_for_owner` 的路径也会自然经过内部 worker。 + +BgFilter 成功二进制不是一份新的业务资产： + +- 不创建 raw object key，也没有 raw 结果 TTL。 +- 父侧按现有路径消费字节并写最终 OSS；手动 complex 只写最终结果一次。 +- 角色、图标、UI 的 provider 原图和动画源帧继续沿用现有对象生命周期，不归子 worker 清理。 + +## 9. 安全、内存与可观测性 + +### 9.1 内部安全 + +- 首版限定父 worker 与子 worker 同机部署，内部 listener 只绑定 loopback 固定端口，不挂公共 Axum router、Nginx、BFF 或 OpenAPI。 +- 使用独立内部 Token；缺失时生产 fail-closed。Token 不复用 BgFilter provider Token。 +- 父、子进程只从同一个 `GENARRATIVE_BGFILTER_INTERNAL_TOKEN_FILE` 读取内部 Token。首尾空白按配置读取规则规范化，规范化后的正文必须是非空且不含任何空白字符的单段值；相关进程启动和发布 preflight 都必须拒绝含内部空格、Tab 或多个非空行的 Token。发布脚本还必须在切换 `current` 链接前确认该路径是非符号链接的普通非空文件，owner / group / mode 符合 `root:genarrative 0440`；不能先切换版本、再等 readiness 暴露首次未 provision、格式或权限错误。 +- 只接受配置 bucket 下的规范化 object key；禁止 `http://`、`https://`、`data:`、`blob:` 和路径逃逸。 +- 不在日志、trace、metrics、错误 JSON 或 SpacetimeDB 审计中写签名 URL、Token、图片字节或 Base64。 + +### 9.2 图片与内存边界 + +父、子两侧都复用当前保护： + +- 响应体最大 `32 MiB`，有 `Content-Length` 和 chunked 两种路径都累计限长； +- 解码宽高最大 `8192 × 8192`，限制解码分配； +- MIME、魔数和实际解码结果必须一致； +- 空 body、截断 body 和超限图片按 `invalid_result` 处理。 + +二进制跨进程传输期间，子 worker 和父 worker 可能同时持有同一张图片。子侧 provider permit、成功 body guard 和图片校验槽均与 `N` 对齐；guard 持有到内部响应发送完成或 body drop，完整成功 body 不会积累到排队规模。父侧另有固定 `P = 8` 个成功图片读取 / 解码槽，必须在开始读取 `2xx` body 前取得，并覆盖有界 body 读取与 `spawn_blocking` 校验；`P` 低于 `N` 时会在出口串行化压低吞吐，`N = 16` 配 `P = 8` 是内存与吞吐的折中。极端完整 body 内存按 `(N + P) × 32 MiB` 评估——`N = 16`、`P = 8` 时约 `768 MiB`——再加父子解码缓冲、provider 读取缓冲和运行时开销；生产 `N` 必须结合主机内存压测，而不是只看 BgFilter 吞吐。 + +图片解码运行在不可强制取消的 blocking task 中。父子两侧等待校验结果都必须受各自 deadline 约束；deadline 到达后请求可按类型化超时收口。子 worker 已启动但尚未结束的校验 task 继续持有图片字节和校验槽，并由 shutdown tracker 等待真实结束；provider `N` 只覆盖真实 provider 调用及内部响应发送，不因后台 CPU 校验延长而虚假占用。父侧超时后的 blocking task 继续持有父侧校验槽直到真实结束，防止后续大图无界叠加，但它没有外部副作用，不纳入子 worker 的 shutdown tracker。`TimeoutStopSec=900` 覆盖的是子 worker 的排空边界。 + +### 9.3 指标与日志 + +最小指标： + +- `bgfilter_internal_waiting_requests`（即 admission 后等待 `N` permit 的队长） +- `bgfilter_internal_queue_timeout_total{bound}`（排队超时按触发边界 `estimate | parent` 分维度） +- `bgfilter_internal_call_budget_drift_total{mode}`（请求 `callBudgetMs` 与本进程公式值不一致；发布窗口内短暂非零正常，持续增长说明父子 N / est 真漂移） +- `bgfilter_internal_connect_retry_total{mode}`（父侧连接失败重试次数；worker 重启窗口内短暂非零正常，持续增长说明 worker 长期不可达） +- `bgfilter_internal_in_flight` +- `bgfilter_internal_request_seconds{mode,outcome}` +- `bgfilter_provider_http_seconds{mode,attempt,outcome}` +- `bgfilter_internal_request_total{mode,outcome}` +- `bgfilter_internal_response_bytes` +- `bgfilter_circuit_state{mode=flat|complex}` + +日志只写 `requestId`、父 job / request correlation、mode、attempt、排队耗时、provider 耗时、结果码和安全 object key；不得记录请求/响应图片 body。 + +flat / complex 的每次 provider 失败审计都必须留在子 worker，保留“第一次失败、第二次成功”也可观察的事实。审计口径以“该次 attempt 是否已发出 provider HTTP”为界：已发出的失败尝试写入 `external_api_call_failure`，包括被剩余预算截短后发生的 timeout 与 response 阶段超时（它们不计入熔断但仍属于审计候选）；未发出的失败（预算不足未启动、签名失败）以及内部 admission、鉴权和本地配置错误不伪装成 BgFilter provider 失败。worker 在 `tokio::spawn` 前获取 flat / complex 共用的进程级 `1024` 个审计 permit，满载时直接丢弃并递增指标，不创建 semaphore waiter 或 detached task。获准任务写入共享 tracking outbox 根目录下独立的 `bgfilter-worker/` 子目录，由 worker 自己批量 flush；outbox 缺失、达到 `MAX_BYTES` 或写盘失败时只丢弃并观测，不同步直写 SpacetimeDB。审计任务纳入 shutdown tracker，优雅退出先排空 enqueue，再封存并尽力 flush；进程被强杀时，已写入 outbox 的记录可在下次启动重放，尚未 enqueue 的任务可能丢失。 + +## 10. 实施与部署计划 + +### 10.1 实施顺序 + +1. 在现有 Rust 后端增加 `bgfilter-worker` 进程角色和独立 loopback Axum listener；它不启动用户 HTTP router，也不 claim `external_generation_job`。 +2. 增加内部 request / binary response / typed error 契约、Token 校验、JSON body 上限、object key allowlist 和健康检查；listener 在 body 解析前接入连接 / request concurrency limit、固定 backlog 和 load shedding。 +3. 增加 admission `Q`、`Semaphore(N)`、两次顺序 attempt、预算检查、结果限长 / 解码校验、response-body permit guard 和 flat / complex 独立进程级熔断。 +4. 增加父侧共享内部 HTTP client。该 client 不重试已被 worker 接收的请求，仅连接从未建立时按 §5.1 有界重连；对 `2xx` 读取并返回受限图片字节，对非 `2xx` 只解析有界类型化 JSON 错误；把父剩余预算显式转换为 `maxQueueWaitMs` 与公式 `callBudgetMs`，client timeout 固定取两者之和加 `2s`。父绝对预算只在派生 `maxQueueWaitMs` 时扣除 callBudget 与父侧预留，不在发送阶段重新裁剪或挪用两笔相对预算。 +5. 用内部 client 替换两个集中调用边界： + - flat：`remove_editor_generated_screen_background_with_bgfilter`； + - complex：`request_editor_background_removal_image_with_bgfilter_worker`。 +6. 从父侧移除 BgFilter provider retry 和 flat 熔断实现；保留 flat fallback、complex 失败、Alpha / 尺寸恢复和所有最终持久化。 +7. 删除动画 `2000ms × frame_count` 单 attempt timeout 增量；保留现有所有帧 collect / drain。 +8. 扫描 queue、inline、External v1 的角色、图标、UI、动画和手动 complex 路径，确认没有 direct BgFilter HTTP 旁路。 +9. 增加单实例 systemd unit、内部地址 / Token、`N / Q` 配置、readiness 和指标；unit 按“API 基础环境 → worker 专属环境”加载，部署 preflight 校验共享超时和 Token；真实压测 `32 / 40 / 48` 帧后启用。 +10. 把独立子进程纳入本地 dev 调度器；`ProcessRole::All` 保持不内嵌 BgFilter listener，避免本地与生产形成两套调用实现。 + +本计划不产生 SpacetimeDB schema、migration、bindings 或表目录改动。 + +### 10.2 部署与回滚 + +1. 在切换发布目录前完成 preflight：共享 API env 与两类 worker env 均存在；`external-generation-worker.env` 和 `bgfilter-worker.env` 不得把共享 BgFilter 配置覆盖为不同有效值；父 base URL、子 `HOST / PORT` 与 readiness URL 指向同一 loopback endpoint；内部 Token 文件存在、非空、非符号链接，规范化后是无空白的单段值且权限正确；`N / Q` 为正整数且 `Q >= N`。 +2. 安装非模板单实例 unit；它先加载 `/etc/genarrative/api-server.env`，再加载 `/etc/genarrative/bgfilter-worker.env`。 +3. 执行 `stop old -> 等待排空/退出 -> start new`，确认唯一 `bgfilter-worker` 的 loopback readiness、鉴权和 provider smoke，不得滚动重叠。 +4. 再重启使用内部 client 的 API / external-generation-worker / controller。 +5. 确认所有父进程只访问内部 endpoint，BgFilter provider 日志中不再出现父进程直连。 + +第 3-4 步之间存在“新 worker + 旧父进程”共存窗口，恰好覆盖旧 external-generation-worker 的优雅排空阶段。调优 N / est 的发布会让窗口内请求携带旧公式的 `callBudgetMs`：worker 按 §4.1 只告警不拒绝、以自身公式值执行，在途任务照常完成或走既有 fallback。发布期间 `bgfilter_internal_call_budget_drift_total` 短暂增长属预期，窗口结束后应停止增长；持续增长才需要排查 env 漂移。 + +内部 worker 不可用时禁止自动 direct fallback。flat 仍可走业务已有阿里云 / 本地 fallback；complex 明确失败。需要整体回滚时回滚父、子进程版本和配置，不在运行中混用两种 BgFilter 调度方式。 + +`bgfilter-worker` 收到停止信号后先停止接收新请求，并让仍在排队等待 `N` permit 的请求立即以类型化错误收口（父侧 flat 走 fallback），只等待已取得 permit 的调用和已启动 provider attempt 排空。排空上界由 `callBudgetMs`（`N = 16`、`est = 5s` 时约 `321s`）决定，因此 systemd unit 固定使用 `TimeoutStopSec=900` 仍有充分余量；部署脚本的同步 `systemctl stop` 必须允许该窗口完成，不能沿用 systemd 常见的约 `90s` 默认值强杀在途调用。排队请求不参与排空等待——它们尚未发出任何外部请求，快速失败是安全的。 + +### 10.3 本地开发 + +`npm run dev` 必须自动启动独立 `bgfilter-worker` 子进程，并在启动父 API / external-generation 路径前完成 loopback readiness。开发端口解析新增第五个 `bgfilter` 职责：Linux 多用户端口段使用 `start + 4`，Windows 沿用现有端口探测与漂移；解析后的实际 host / port 注入子进程，实际 base URL 注入父进程，不能继续硬编码 `8083`。父、子使用同一个仅存在于本地进程环境的内部 Token。 + +`GENARRATIVE_PROCESS_ROLE=all` 仍不直接运行 BgFilter listener。单模块联调需要提供明确的独立 worker 启动入口，并在 `dev:api-server` 没有可用 worker 时自动带起或 fail-fast 给出该入口，不能让开发者等到一次图片生成才看到连接拒绝。dev 状态文件、watch 重启、端口日志和退出清理都要把第五个子进程纳入，防止遗留进程占端口。 + +## 11. 验收门禁 + +必须覆盖： + +- `48` 帧同时进入时，唯一子 worker 观测到的客户端 BgFilter HTTP future 峰值不超过 `N`。 +- listener 在 body 解析前执行鉴权与 admission；保险丝 `Q`（默认 `2048`）触达后新请求立即返回 `overloaded`，内核 socket backlog 按独立固定值验证。 +- 排队时间只消耗 `min((队长+5)×est×2, maxQueueWaitMs)`，不侵蚀 `callBudgetMs`；排队超时返回 `deadline_exceeded (phase=queue)` 且带触发边界；`callBudgetMs` 自取得 `N` permit 起算，deadline 到达后不开始新的 provider attempt。 +- `maxQueueWaitMs <= 0` 时父侧不发送请求：flat 直接 fallback，complex 直接失败。 +- `callBudgetMs` 与 worker 本进程公式值不一致时不拒绝：worker 以自身公式值执行，记 warn 并递增漂移指标；发布调优 N / est 的新旧进程共存窗口内，在途 flat 任务仍能正常执行或走既有 fallback，不得因瞬态漂移触发 `invalid_request`（该码禁止 fallback）。attempt、callBudget、client timeout 全部由 `N / est` 运行时派生，代码不存在硬编码结果值。 +- parent client timeout 精确取 `maxQueueWaitMs + callBudgetMs + 2s`，helper 保持 infallible；父绝对预算通过 `maxQueueWaitMs` 的派生公式预先约束，结果校验等待也必须 deadline-aware，不能只在校验完成后事后判超时。 +- 第一次失败后预算不足时不开始第二次；父侧从不重试已建立连接的内部 RPC。连接从未建立的失败按 §5.1 有界退避重试：仅 connect 类失败重入、收到任何 HTTP 响应立即停止、每轮重算 `maxQueueWaitMs`、配额按冷启动 / 常规两档封顶且单次调用内锁定（Rust 集成测试覆盖「重试跨过监听空窗后停在首个 HTTP 响应」「常规档配额耗尽返回 connect 失败」「deadline 放不下下一轮时不空睡」「冷启动档 flat 跨过超出常规配额的监听空窗」，以及安全不变量「TCP 已 accept、未回任何 HTTP 字节即断开 → 不得发起第二次连接」——以 accept 计数证明）。 +- 父业务预算仍有效时，flat 两次失败、熔断、overload、内部 RPC deadline 或断连仍走“阿里云 → 本地”；complex 任意失败或自身熔断都直接失败，不接 flat fallback。 +- flat / complex 分别按自身真实失败 attempt 计数且状态互不影响；由剩余业务预算截短的 timeout 不计入。两种模式都在 permit 前二次检查；已获准调用可完成第二次，后续同模式排队请求快速 `circuit_open`。 +- `cancelled`（仅验证父侧映射，保留码首版不产生）、父 cancellation / 绝对 deadline、`invalid_request` 和 `unauthorized` 不启动 flat fallback；其它 flat 错误只在父业务预算仍有效时进入 fallback。 +- 已发出的 provider attempt 失败（含预算截短 timeout 与 response 阶段超时）都是 `external_api_call_failure` 审计候选；未发出与纯内部失败不落。审计 task 在 spawn 前受全局 `1024` 硬上限约束，满载或独立 outbox 不可写时允许丢弃并上报指标；已获准任务由 shutdown tracker 排空并完成 enqueue 后，进程才封存和尽力 flush outbox。 +- 客户端断连时，等待 permit 的请求最终由 deadline 收口；已开始 provider attempt 持有 permit 并排空。明确 cancellation 已被观察到后不再开始第二次，单纯 TCP 断连只作 best-effort 测试，不作为硬保证。 +- 动画全部已提交帧继续 collect / drain，根因按现有稳定帧序号收口；首版不存在未实现的 group cancellation 承诺。 +- 成功 body 为原始图片字节而非 Base64、JSON 或结果 object key；父侧 client 把该有界字节缓冲直接交给现有后处理，子 worker 不执行 raw OSS PUT。父、子两侧都拒绝空 body、MIME / 魔数不一致、chunked 超 `32 MiB` 和超过 `8192 × 8192` 的图片。 +- `N / Q` response-body guard 在发送完成或 body drop 前不释放，慢读 / 断连时完整成功 body 不积累到 `Q` 级。 +- 子侧图片校验槽与 `N` 对齐；校验等待受 child deadline 约束，超时后的 blocking 校验 task 继续持有图片字节与校验槽，并被 shutdown tracker 排空；真实 provider 调用已经结束后不继续占用 `N`。 +- 父侧固定最多 `8` 个成功图片读取 / 解码槽，permit 在读取 `2xx` body 前取得并覆盖 `spawn_blocking` 校验；内部响应并发再高也不能无界累积父侧完整 body 或解码任务。 +- worker 重启 / RPC 丢失不查询、不恢复结果；父 job 的 heartbeat、lease、失败退款和 fencing 保持现状。 +- External v1 / inline 不再直连 BgFilter；公共 router、BFF、账单和任务列表中没有内部 endpoint 或内部调用记录。 +- 生产不存在两个同时运行的 `bgfilter-worker`，`N` 或 `est` 缺失、为 `0` 时 fail-closed；`Q` 显式配置时必须 `>= N`。 +- worker unit 先加载共享 API env、再加载 worker 专属 env；父子有效 `N` 与 `est` 完全一致（两者都在共享 API env），flat / complex 统一熔断参数只由子 worker 配置和执行，cooldown 默认 `120s`。 +- `external-generation-worker.env` 后加载时不得把内部 base URL、Token / Token 文件、connect timeout、`N`、`est`、OSS bucket 或 endpoint 覆盖为与共享 API env 不同的有效值；父侧必须把源对象写到子 worker 将要签名读取的同一 OSS 位置。外部生成 worker 可使用同 bucket 下权限等价或更小的独立 AK，不要求凭据文本相同。 +- 父进程 `GENARRATIVE_BGFILTER_WORKER_BASE_URL`、子 worker `HOST / PORT` 和部署 readiness URL 必须指向同一个 `127.0.0.1:` endpoint；旧非空配置不能因为“无需补默认值”而绕过一致性检查。 +- deploy 安装的三个 worker systemd unit（bgfilter / worker@ / controller）必须先按 `--current-link` 与各 env 参数渲染再安装（与 provision 的 `render_*_service` 同语义），安装后的 unit 不得残留模板默认的 current 链接或 env 路径字面量；controller env 路径由 `--controller-env-file` 表达。默认参数下渲染输出与模板逐字节一致。 +- `genarrative-bgfilter-worker.service` 必须保持 `TimeoutStopSec=900`，覆盖 `callBudgetMs` 排空上界（约 `321s`）与停止收口余量；停止时排队请求立即类型化失败，不参与排空。 +- 发布目录切换前拒绝缺失、空、含内部空白、包含多个非空行、符号链接或权限错误的内部 Token 文件；允许文件末尾正常换行，父、子有效 Token 文件路径必须相同。 +- 生产运行期巡检同时检查 `genarrative-bgfilter-worker.service` 为 active 且 worker `readyz` 成功（默认 `127.0.0.1:8083`），不能只依赖 systemd 自动重启。provision / deploy 的发布验活 URL 必须从已验证的 env `HOST/PORT` 派生，不得硬编码默认端口；若运维自定义 `GENARRATIVE_BGFILTER_WORKER_PORT`，必须同步覆盖巡检的 `GENARRATIVE_HEALTH_PATROL_BGFILTER_BASE_URL`（巡检是独立进程，不读取 worker env，默认值不会自动跟随）。 +- `npm run dev` 启动独立 BgFilter 子进程并使用解析后的第五个端口；`all` 角色不内嵌 listener，单模块入口、watch、状态文件和退出清理没有遗留进程或硬编码端口。 + +本地全进程调度门禁使用已构建的 `api-server` binary 和 loopback mock provider，不读取真实 OSS / BgFilter 密钥，也不访问真实外部服务。`load-smoke` 固定验证 `R = 32 / 40 / 48、N = 16`（`Q` 用小值场景单独验证保险丝行为）；`fault-smoke` 用独立 worker / mock 生命周期验证保险丝触达快速拒绝、queue timeout 双边界、`503 → 200` 顺序重试、两次 `503` 后 provider exhausted，以及 provider 成功响应 body 中途 reset 后第二次 attempt 串行成功。默认读取 `server-rs/target/debug/api-server(.exe)`；在 WSL 或自定义 target 目录运行时，通过 `GENARRATIVE_BGFILTER_SMOKE_BINARY` 指定 binary： + +```bash +cargo build -p api-server --manifest-path server-rs/Cargo.toml +npm run bgfilter-worker:smoke-test +npm run bgfilter-worker:load-smoke +npm run bgfilter-worker:fault-smoke +``` + +真实 OSS + BgFilter 契约冒烟不属于默认门禁，会访问真实服务并产生调用成本。执行前必须在当前进程环境中以不回显方式注入与 loopback worker 相同的一次性 `GENARRATIVE_BGFILTER_INTERNAL_TOKEN`，不得把 token 写进命令行、仓库 env 文件或日志；OSS / BgFilter 配置只放本地私密环境。分别设置 `GENARRATIVE_BGFILTER_SMOKE_MODE=flat` 与 `complex` 后，标准 `8083` worker 使用以下命令： + +```bash +cargo run -p platform-oss --example bgfilter_worker_live_smoke --manifest-path server-rs/Cargo.toml -- --worker-url http://127.0.0.1:8083 +``` + +示例程序省略 `--worker-url` 时默认访问 `http://127.0.0.1:18083`，只适用于把 worker 显式启动在该隔离端口的场景，不是标准 dev / 生产端口。该 harness 固定使用 `generated-character-drafts/bgfilter-smoke//source.png`：PUT 前必须先确认 HEAD=404，随后验证私有上传、无鉴权 401 精确错误契约、真实 `200 image/png`，最后要求 DELETE 2xx 且 HEAD=404。正常失败也会尝试清理；若进程崩溃或被强杀，必须按输出的 object key 人工复核。它验证真实 OSS / BgFilter 边界，不替代完整父流程验收；父 flat 的 fallback 本地证据仍由真实阿里云 `segment_smoke` 与父路由单测组合提供，`mock worker 失败 → 父 flat → 真实阿里云`、完整动画写回及计费 / lease / 退款链留在 staging 验收。 + +当前实现按范围运行： + +```bash +cargo test -p api-server bgfilter --manifest-path server-rs/Cargo.toml +cargo test -p api-server character_animation --manifest-path server-rs/Cargo.toml +cargo check -p api-server --manifest-path server-rs/Cargo.toml +npm run check:server-rs-ddd +npm run check:encoding +git diff --check +``` + +不需要运行 `npm run spacetime:generate` 或 `npm run check:spacetime-schema`，因为本计划明确不修改 SpacetimeDB。 + +## 12. 生产启用前需冻结的参数 + +架构边界已固定：首版单实例、无 QPS、无数据库任务表、无 checkpoint / continuation、输出直接走内部二进制响应。 + +当前冻结值与校准要求： + +- 生产 `GENARRATIVE_BGFILTER_WORKER_CONCURRENCY = N = 16`。 +- 生产 `GENARRATIVE_EDITOR_BGFILTER_SINGLE_IMAGE_ESTIMATE_MS = est = 5000`。依据：BgFilter 服务端高并发单图处理约 `1-3s`、网络约 `3-5s`。est 是 attempt、callBudget 与队列估时三个公式的共同地基，估计过小会导致排队提早降级、attempt 误伤慢图并触发熔断；生产压测的首要目标是校准该值。 +- `GENARRATIVE_BGFILTER_WORKER_MAX_REQUESTS = Q` 为可选保险丝，默认 `2048`，仅防连接风暴；显式配置时必须 `>= N`。 + +其余固定边界：内部响应最大 `32 MiB / 8192 × 8192`，父侧解码槽 `P = 8`，内部 listener 只绑定 loopback 且必须鉴权。旧的独立 provider attempt timeout 配置已删除，attempt 上限不再独立配置。若要多实例、严格服务端全局并发、QPS 或动画 peer cancellation，应先升级本文，不在编码中临时扩 scope。 + +配置归属同时冻结：`N` 与 `est` 来自父子共同加载的 API 基础环境（父侧算 callBudget / client timeout、worker 算 attempt / 队列估时都依赖它们）；`GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD`、`GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS` 与可选的 `Q` 由 worker 专属环境管理。若部署脚本发现共享值被 worker 环境重复定义且不同，必须在启动前失败。 diff --git a/docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md b/docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md index 4eb3b79dc..7937809cb 100644 --- a/docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md +++ b/docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md @@ -2,7 +2,9 @@ > 2026-07-18 退役覆盖：旧创作模板 job 类型、玩法写回和玩法恢复链路均已退出现役 worker。当前 worker 只领取 `source_module = editor-canvas` 的任务；本文涉及拼图、跳一跳、拼消消、敲木鱼等玩法的内容仅作为历史设计记录，历史队列行不得被领取或改写。 -更新时间：`2026-07-15` +> 2026-07-21 已实施、待生产压测专题：BgFilter 作为受限内部资源，仍遵守“单用户动作一个外部生成 job”；用户可见层与调度层都只有父 `external_generation_job`。父 future 保持原 lease 和 attempt，在当前调用栈内同步请求唯一 `bgfilter-worker` 的内部 HTTP，成功图片字节直接返回父流程。首版不新增 SpacetimeDB 子任务表、父 checkpoint / continuation 或 raw 中间结果 OSS。完整边界见 [`BgFilter 受限资源调度方案（同步内部 HTTP 原地等待版）`](./【后端架构】BgFilter受限资源调度方案-2026-07-21.md)。 + +更新时间：`2026-07-21` ## 背景 @@ -192,7 +194,7 @@ controller 配置： - `editor_image_generation`：普通图片、生成规范、角色形象、UI 设计图、宣发素材和图片快速编辑。 - `editor_image_edit`：图片编辑 / 修改结果。 -- `editor_background_removal`：手动去除任意图片背景，worker 使用 BgFilter complex 模式、首次失败后重试 `1` 次，并把执行阶段标记为 `processing`。 +- `editor_background_removal`：手动去除任意图片背景，父 `external-generation-worker` 至多让 worker 接收一次内部 HTTP RPC（连接从未建立时按调度方案 §5.1 有界重连）并把执行阶段标记为 `processing`；唯一 `bgfilter-worker` 使用 BgFilter complex 模式，对同一次逻辑调用最多执行两次顺序 provider attempt，两次都失败时把类型化错误返回父流程。 - `editor_icon_spritesheet_generation`：图标素材 spritesheet 生成和拆分。 - `editor_ui_design_asset_extraction`：UI 设计图红框素材提取。 - `editor_character_animation_generation`：角色动作视频和帧素材生成。 diff --git a/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md b/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md index 80a9ade1f..bcf00d2e3 100644 --- a/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md +++ b/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md @@ -247,8 +247,8 @@ npm run check:server-rs-ddd - 抠图输入以私有 OSS 作为内存生命周期边界：生成原图和角色动作抽取帧上传时消费图片字节所有权，上传完成后不保留原图缓冲；手动去背景直接解析并校验已有 OSS object key，不下载原图。BgFilter 必须为 object key 签发 600 秒 GET URL 并通过 multipart `image_url` 提交，不用 `file` 重传；flat 链路进入阿里云 fallback 时由 `platform-matting` URL 接口单独下载并上传 `AuthorizeFileUpload` 临时对象，在推理前释放下载缓冲，继续 fallback 到本地键色时再单独下载一次原图，本地产出后释放本次原图下载缓冲。签名 URL 不得写入日志、审计或持久化。 - 角色动作抠图输入像素边界：仅图片画布角色动作链路在 FFmpeg 抽帧后、源帧上传 OSS 前，把帧解码为 RGB8，并按最终 `frameWidth × frameHeight` 的 contain 比例使用 `Triangle` 只缩放到内容尺寸；该阶段不得创建最终目标尺寸画布、不得引入 Alpha 通道，也不得插入任何 padding。BgFilter、阿里云通用抠图和本地键色降级共享这个无补边源帧 object key。抠图返回后才统一转为 RGBA8，按相同比例居中放入最终目标尺寸画布，并用 `RGBA(0,0,0,0)` 补齐透明 padding。以 `560×752 → 323×480` 为例，抠图输入固定为无 Alpha、无补边的 `323×434 RGB8 PNG`，最终输出为上下各 `23px` 透明补边的 `323×480 RGBA8 PNG`。旧 `/api/assets/character-animation/*` 动作发布链路继续保留原有帧 finalizer，不适用该输入规则。抽帧解码后若携带 Alpha 通道，必须先把像素按白底合成为不透明再转 RGB8，禁止直接丢弃 Alpha——全透明像素下未定义的 RGB 值会以杂色进入抠图输入，重新引入杂色边缘；共享 FFmpeg 抽帧命令保持不固定 `-pix_fmt`，白底合成只属于该链路的 BgFilter 输入准备阶段。 - 阿里云通用抠图的非上海地域输入不得使用 `viapiutils/GetOssStsToken`、固定 `viapi-customer-temp` 或 OSS V1 PUT。`platform-matting` 必须按官方新版 SDK Advance 协议调用 `AuthorizeFileUpload`，使用动态返回的单对象 Policy 执行 multipart POST，再把临时上海 OSS URL 交给 `SegmentCommonImage`；输入归一化、结果下载与原尺寸 Alpha 回贴继续留在同一适配器内。该协议仍上传图片字节，不等同于阿里云服务端直接抓取任意公网 URL，也不改变上层 BgFilter → 阿里云 → 本地降级顺序。 -- 编辑器抠图服务：手动 `POST /api/editor/images/background-removals` 与角色形象生成、图标 spritesheet 生成、UI 设计图素材提取、角色动作抽帧后的透明化统一走 BgFilter，配置为 `GENARRATIVE_EDITOR_BGFILTER_BASE_URL`、`GENARRATIVE_EDITOR_BGFILTER_TOKEN` 和 `GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS`，默认 base URL 为 `http://58.87.105.82/bgfilter`，默认请求超时为 `180000ms`（BgFilter 当前为 CPU 推理，单次抠图较慢，必须留足超时）；旧 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN` 只作为 BgFilter token 的兼容回退别名，原手动去背景专用 base URL / timeout 配置已经删除。手动去背景固定传 `image_url`、`background_mode=complex`、`seg_model=birefnet`、`cross_check=off`，不传 `file` 或 `screen_color`；该 API 接收 `objectKey`、`resourceId` 或 `assetId` 候选引用；BFF 入队前统一拒绝 `data:` / `blob:`；worker 不重复入口校验，只调用 `resolve_editor_reference_object_key_for_owner`，底层 resolver 在解析引用前拒绝内联媒体，并在签名前完成登记状态和 owner 校验；直接签发 OSS URL，不下载原图。标准纯色背景四条链路固定传 `background_mode=flat`，并显式传 `image_url`、`screen_color=`、`seg_model=` 和 `cross_check=`，其中角色形象生成和角色动作逐帧去背传 `cross_check=on`，图标 spritesheet 生成和 UI 设计图素材提取传 `cross_check=off`。前端用户路径不展示抠图模型、模式或 cross-check，固定提交默认 `birefnet`，后端仍识别内部保留的 `anime-seg`；这些参数只属于后端内部供应商策略，不进入前端或外部 OpenAPI。标准纯色背景 BgFilter 调用失败，或连续失败达到 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD`（默认 `3`）并在 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS`（默认 `300`）内打开熔断时，继续复用“阿里云通用抠图 → 本地 `editor_green_screen` 键色扣除”兜底链，熔断期不得直接退化到本地兜底。角色动作视频生成的背景色已与生图链路统一：`screenColor=auto` 时由视觉 LLM（`gpt-5-mini`，Responses 协议、low 推理档）读源角色图自动决策，并经硬过滤器剔除与前景 / 皮肤撞色的候选，手动 hex 则尊重用户选择；透明源角色图在提交 Ark 图生视频前先合成到选定背景色实色，使视频背景等于抠图键色；抽帧后每帧先上传私有 OSS 并释放原帧缓冲，再以该 object key 的签名 URL 固定使用 `seg_model=birefnet`、`cross_check=on` 进入上述三段式链路。阿里云通用抠图配置为 `GENARRATIVE_ALIYUN_MATTING_ENABLED`、`GENARRATIVE_ALIYUN_MATTING_ENDPOINT`、`GENARRATIVE_ALIYUN_MATTING_ACCESS_KEY_ID`、`GENARRATIVE_ALIYUN_MATTING_ACCESS_KEY_SECRET` 和 `GENARRATIVE_ALIYUN_MATTING_REQUEST_TIMEOUT_MS`；未配置专用 AK/SK 时可复用 `ALIBABA_CLOUD_ACCESS_KEY_ID` / `ALIBABA_CLOUD_ACCESS_KEY_SECRET`，默认 endpoint 为 `imageseg.cn-shanghai.aliyuncs.com`。标准纯色背景链路中，BgFilter 调用失败和阿里云抠图链路已开始后的失败（包括源 OSS GET 成功后的解码、尺寸校验和归一化失败）都写入 `external_api_call_failure` 审计；真正开始外部调用前的本地预检不写该审计，并在 `failureStage` 中保留 `source_decode`、`source_validate` 等阶段。 -- BgFilter 连接复用、重试与动作帧流水线：api-server 必须在 `AppState` 复用同一个 BgFilter HTTP Client 及 keep-alive 连接池。`GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS` 是所有路径的基准请求超时；角色动作逐帧 BgFilter 的每一次 HTTP attempt 使用“基准超时 + `2000ms × 本次实际帧数`”，默认 `32 / 40 / 48` 帧分别为 `244000 / 260000 / 276000ms`，角色形象单图、图标、UI 和手动去背景仍使用基准值。api-server 只在共享 Client 的单次 RequestBuilder 上覆盖该值；它覆盖从请求发起到响应体读取完成，是单次 attempt 的总 deadline，不是整批帧或 worker job 超时，重试会重新签发 600 秒 OSS URL 并获得同样的 request deadline，整项任务仍受 worker long-job 预算约束。flat 与 complex 请求首次失败后都立即重试 `1` 次；标准纯色背景 flat 请求第二次仍失败才进入“阿里云通用抠图 → 本地键色”降级链，手动 complex 请求第二次仍失败则返回最终错误，不接入依赖纯色键值的降级链，也不改变 flat 路径的熔断状态。角色动作全部 `32 / 40 / 48` 帧按“单帧绿幕源图 owned 上传 OSS 并释放原帧 → 以签名 URL 调 BgFilter/按 object key 降级 → 透明帧落 OSS”独立流水化，使用覆盖本次全部帧的无序在途集合连续发射；不限制 BgFilter、阿里云或本地处理，但角色动画源帧 PUT、透明帧 PUT 和最终帧 HEAD 统一复用 `AppState` 内初始化一次的 OSS HTTP Client（连接池参数为 connect 30 秒、request 60 秒、idle 300 秒、每 host 8 个 idle 连接、TCP keepalive 60 秒），并受进程级 8 路 OSS semaphore 限制。每个 OSS 网络 attempt 单独获取 permit，退避期间释放；PUT/HEAD 动画帧请求最多 3 次（250ms、500ms 退避），只重试无 HTTP 响应的传输错误、timeout、OSS PutObject 的 `400 + RequestTimeout`、PUT `400` 错误体读取失败（未解析出 `Code`，按 timeout/transport 归类）、408、429 和 5xx。动作帧 PUT 只在 400 响应中有界读取最多 16 KiB OSS 错误 XML，并保留 `Code` 与响应头优先的 `x-oss-request-id`；错误体读取超时/断流时保留已读字节，已解析出的 `Code` 优先生效，未解析出 `Code` 则按 timeout/transport 归类重试；除 `RequestTimeout` 与该错误体读取失败情形外的其他 400、401/403/404、配置、URL/签名和空请求体错误不重试。返回结果携带原始帧序并在收口时排序。任一帧最终失败时必须先排空全部已启动 Future，再让整个动作任务失败退款，不能发布缺帧动画。 +- 编辑器抠图服务：手动 `POST /api/editor/images/background-removals` 与角色形象生成、图标 spritesheet 生成、UI 设计图素材提取、角色动作抽帧后的透明化统一通过唯一 loopback `bgfilter-worker` 调用 BgFilter provider。provider 配置继续使用 `GENARRATIVE_EDITOR_BGFILTER_BASE_URL` 与 `GENARRATIVE_EDITOR_BGFILTER_TOKEN`，默认 base URL 为 `http://58.87.105.82/bgfilter`；单次 provider attempt 上限不再独立配置，由公式 `N × est × 2` 运行时派生，其中 `est = GENARRATIVE_EDITOR_BGFILTER_SINGLE_IMAGE_ESTIMATE_MS`（默认 `5000`，依据为服务端高并发单图处理约 1-3s、网络约 3-5s），旧 `GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS` 已删除；旧 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN` 只作为 provider token 的兼容回退别名，原手动去背景专用 base URL / timeout 配置已经删除。父流程先把候选 `objectKey`、`resourceId` 或 `assetId` 解析为当前 owner 已登记的私有 OSS object key；BFF 入队前统一拒绝 `data:` / `blob:`，底层 resolver 在解析引用前再次拒绝内联媒体并完成登记状态与 owner 校验。父流程只通过一次内部 HTTP RPC 传递 object key、排队预算 `maxQueueWaitMs`、调用预算 `callBudgetMs` 与模式参数，不传图片字节或签名 URL，并同步等待子 worker 返回的受限图片二进制 body。子 worker 在每次真实 provider attempt 前签发短期 OSS URL，承担 admission 保险丝 `Q`（默认 `2048`，仅防连接风暴）、provider 并发 `N`（生产 `16`）；排队 deadline 从 `Q` admission 时刻起算，完成 JSON 校验并进入 provider permit 等待队列时再取得队长快照，按 `min((队长+5)×est×2, maxQueueWaitMs)` 约束排队等待。子 worker 还负责严格最多两次顺序 attempt、结果校验和按 flat / complex 隔离的进程级熔断；两种模式共享 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD=3` 和 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS=120` 默认值，但失败和成功只更新当前模式，且只由子 worker 读写。手动去背景固定使用 `background_mode=complex`、`seg_model=birefnet`、`cross_check=off`，不传 `file` 或 `screen_color`；complex provider 失败累计自身熔断，任意失败或自身熔断都直接返回父流程失败，不接 flat fallback，也不影响 flat 熔断。标准纯色背景四条链路固定使用 `background_mode=flat`、`screen_color=`、`seg_model=` 和 `cross_check=`，其中角色形象生成和角色动作逐帧去背传 `cross_check=on`，图标 spritesheet 生成和 UI 设计图素材提取传 `cross_check=off`。前端用户路径不展示抠图模型、模式或 cross-check，固定提交默认 `birefnet`，后端仍识别内部保留的 `anime-seg`；这些参数只属于后端内部供应商策略，不进入前端或外部 OpenAPI。父侧不重试已建立连接的内部 RPC，仅对 TCP 连接从未建立的失败按父预算有界退避重试（跨过 worker 重启与开机排序窗口，收到任何 HTTP 响应即停止）；flat 两次 provider attempt 失败、熔断、overload、内部 deadline 或断连后，只要父业务预算仍有效，父流程才继续“阿里云通用抠图 → 本地 `editor_green_screen` 键色扣除”，熔断期不得直接退化到本地兜底。角色动作视频生成的背景色已与生图链路统一：`screenColor=auto` 时由视觉 LLM（`gpt-5-mini`，Responses 协议、low 推理档）读源角色图自动决策，并经硬过滤器剔除与前景 / 皮肤撞色的候选，手动 hex 则尊重用户选择；透明源角色图在提交 Ark 图生视频前先合成到选定背景色实色，使视频背景等于抠图键色；抽帧后每帧先上传私有 OSS 并释放原帧缓冲，再以 object key 固定使用 `seg_model=birefnet`、`cross_check=on` 进入上述三段式链路。阿里云通用抠图配置为 `GENARRATIVE_ALIYUN_MATTING_ENABLED`、`GENARRATIVE_ALIYUN_MATTING_ENDPOINT`、`GENARRATIVE_ALIYUN_MATTING_ACCESS_KEY_ID`、`GENARRATIVE_ALIYUN_MATTING_ACCESS_KEY_SECRET` 和 `GENARRATIVE_ALIYUN_MATTING_REQUEST_TIMEOUT_MS`；未配置专用 AK/SK 时可复用 `ALIBABA_CLOUD_ACCESS_KEY_ID` / `ALIBABA_CLOUD_ACCESS_KEY_SECRET`，默认 endpoint 为 `imageseg.cn-shanghai.aliyuncs.com`。标准纯色背景链路中，子 worker 已发出的 BgFilter provider 失败（含被剩余预算截短后发生的 timeout 与 response 阶段超时，这类失败不计入熔断但仍是审计候选）由进程级 `1024` 个审计任务硬上限保护，获准任务写入共享 tracking outbox 根目录下独立的 `bgfilter-worker/` 子目录并批量落库；满载、outbox 缺失、达到磁盘保护阈值或写盘失败时允许丢弃并记录指标，不回退逐条同步直写 SpacetimeDB。父侧阿里云抠图链路已开始后的失败（包括源 OSS GET 成功后的解码、尺寸校验和归一化失败）继续按通用外部 API 审计策略处理。真正开始外部调用前的本地预检不写该审计，并在 `failureStage` 中保留 `source_decode`、`source_validate` 等阶段。成功图片字节返回后，最终 Alpha / 尺寸恢复、OSS / asset object、画布写回、计费和父任务终态仍全部由父流程负责。 +- BgFilter 连接复用、超时与动作帧流水线：`AppState` 分别复用父侧内部 worker HTTP Client 和子 worker 专用 BgFilter provider HTTP Client；父侧对一次逻辑调用至多让 worker 接收一次内部 RPC，不重试已建立连接后的失败；仅 TCP 连接从未建立时（worker 重启 / 开机排序窗口）按每轮重算 `maxQueueWaitMs` 的有界退避序列重连——增加的只是连接尝试次数，不产生第二次被接收的 RPC。重连配额按本进程是否已连通过 worker 分档：首连前（冷启动）flat 22.5s / complex 约 62.5s，首连后 flat ≤1.5s / complex 22.5s；每次重连计 `bgfilter_internal_connect_retry_total` 指标。子 worker 在同一个 `N` permit 内严格最多执行两次顺序 provider attempt。唯一子 worker 使用 `GENARRATIVE_BGFILTER_WORKER_CONCURRENCY=N`（生产 `16`）限制真实 provider 在途数；`GENARRATIVE_BGFILTER_WORKER_MAX_REQUESTS=Q` 降级为可选 admission 保险丝（默认 `2048`，仅防连接风暴，显式配置时必须 `>= N`）。超时全部由 `N` 与 `est` 运行时派生：单 attempt 上限 `N × est × 2`、调用预算 `callBudgetMs = 2 × attempt + 1s`（自取得 `N` permit 起算）、排队等待受 `min((provider 等待队列队长+5)×est×2, maxQueueWaitMs)` 双重上界（动态项充当自适应过载探测，超时带 `bound = estimate | parent` 标记），排队不侵蚀调用预算；`N` 与 `est` 必须同放共享 API 基础环境；请求携带的 `callBudgetMs` 只是父侧配置指纹，worker 比对后不一致只告警并计 `bgfilter_internal_call_budget_drift_total` 指标、始终以本进程公式值执行——发布调优 N / est 的新旧进程共存窗口不得误伤在途任务，持久漂移由部署脚本共享 env 对齐校验在启动前拦截。角色动作不再增加 `2000ms × 本次实际帧数`，`32 / 40 / 48` 帧使用相同公式。父侧按剩余绝对预算派生 `maxQueueWaitMs`（flat 扣除 `39s` 父侧预留（`37s` fallback + `2s` 传输窗），complex 只留 `2s` 传输窗；`<= 0` 时不发请求直接降级 / 失败），client timeout 取 `maxQueueWaitMs + callBudgetMs + 2s`；每次 attempt 前重新签发短期 OSS URL，剩余时间不足时不开始新的 attempt。父侧成功响应解码槽 `P = 8`。角色动作继续以 `buffer_unordered(frame_count.max(1))` 将全部单帧逻辑调用加入无序在途集合；返回结果携带原始帧序并在最终 collect / drain 全部已提交 Future 后排序，任一帧最终失败时必须先排空全部已启动 Future，再让整个动作任务失败退款，不能发布缺帧动画。单帧按“绿幕源图 owned 上传 OSS 并释放原帧 → 以 object key 调内部 worker / 按 object key 由父侧降级 → 父侧处理透明帧并落 OSS”流水化。角色动画源帧 PUT、透明帧 PUT 和最终帧 HEAD 仍统一复用 `AppState` 内初始化一次的 OSS HTTP Client（连接池参数为 connect 30 秒、request 60 秒、idle 300 秒、每 host 8 个 idle 连接、TCP keepalive 60 秒），并受进程级 8 路 OSS semaphore 限制；BgFilter provider 的 `N` 不占该 OSS permit，阿里云和本地处理既不占 OSS permit，也不受 `N / Q` 限制。每个 OSS 网络 attempt 单独获取 permit，退避期间释放；PUT/HEAD 动画帧请求最多 3 次（250ms、500ms 退避），只重试无 HTTP 响应的传输错误、timeout、OSS PutObject 的 `400 + RequestTimeout`、PUT `400` 错误体读取失败（未解析出 `Code`，按 timeout/transport 归类）、408、429 和 5xx。动作帧 PUT 只在 400 响应中有界读取最多 16 KiB OSS 错误 XML，并保留 `Code` 与响应头优先的 `x-oss-request-id`；错误体读取超时/断流时保留已读字节，已解析出的 `Code` 优先生效，未解析出 `Code` 则按 timeout/transport 归类重试；除 `RequestTimeout` 与该错误体读取失败情形外的其他 400、401/403/404、配置、URL/签名和空请求体错误不重试。最终帧 HEAD 失败只重试 HEAD，不重复 PUT。 - Match3D 物品 sheet：关卡整图完成后走 VectorEngine `/v1/images/edits` multipart `image`，模型为 `gpt-image-2`，`2K 1:1` 输出 `10*10` spritesheet；物品 sheet prompt 固定要求单一纯绿色 `#00FF00 / RGB(0,255,0)` 绿幕背景，后端上传 OSS 前必须把绿幕扣成透明 PNG，并把透明整图写入 `itemSpritesheetImageSrc/itemSpritesheetImageObjectKey`。后端优先按透明 alpha 连通域从该 sheet 识别真实素材矩形并持久化 20 个物品、每个 5 个形态；识别数量不足时才回退 `10*10` 固定网格。通用系列素材图集的行列索引按每行 2 个物品计算，必须落在 `1..=10`，难度只决定运行态加载 3 / 9 / 15 / 20 种。 - Match3D UI spritesheet 和背景派生图：关卡整图作为参考图并发生成 `1K 1:1` UI spritesheet 与 `1K 9:16` 背景图，模型均为 `gpt-image-2`。UI spritesheet prompt 固定要求单一纯绿色 `#00FF00 / RGB(0,255,0)` 绿幕背景，后端上传 OSS 前必须把绿幕扣成透明 PNG；背景图必须合成为全画幅不透明 PNG。 - Match3D 1:1 容器 UI：VectorEngine `/v1/images/edits` multipart 参考图。该容器参考图是后端生图协议输入，必须通过 `include_bytes!` 随 `api-server` 编译进二进制，避免 API 单独发布或运行目录缺少 `public/` 时生成失败。 @@ -256,7 +256,7 @@ npm run check:server-rs-ddd - Hyper3D / Rodin：只保留后端安全代理和旧数据兼容；Rodin 提交、状态、下载和响应解析归属 `platform-hyper3d`，`api-server/src/hyper3d_generation.rs` 只做路由、配置和错误 envelope 映射；新 Match3D 草稿和批量新增不再生成 GLB。 - 音频：视觉小说专用音频路由保留；VectorEngine Suno/Vidu provider 协议、任务提交/查询、音频 URL 提取、下载、MIME/extension 归一和 OSS put 请求准备归属 `platform-audio`。`api-server/src/vector_engine_audio_generation.rs` 只做路由、配置、计费、asset object confirm、entity binding 和错误 envelope 映射；拼图、抓大鹅和敲木鱼提示词生成音效入口暂时关闭，通用 `/api/creation/audio/*` 对这些目标返回 `410 Gone`。敲木鱼创作只接收上传 / 录音音频资产；前端选择或录音阶段只在浏览器本地处理待提交音频，统一限制裁切后最长 1 秒、裁掉前后声音过小片段，并用浏览器端近似响度算法平衡到 `-15 LKFS` 后做峰值保护。点击生成时才直传 OSS 并确认 `asset_object`，创作 JSON 只提交轻量 `WoodenFishAudioAsset`，不得继续上传 Data URL 音频；未提供时由 `api-server` 写回内置默认木鱼音 `/wooden-fish/default-hit-sound.mp3`。 - OSS：私有 generated path 进入浏览器前必须通过 `/api/assets/read-url` 换签；不要裸请求 `/generated-*`。请求参数的安全语义不能混用：`legacyPublicPath` 是历史公开作品兼容口，只允许 `platform_oss::LEGACY_PUBLIC_PREFIXES` 中的 curated 前缀匿名换签；`objectKey` 是正式对象引用，绝不能复用该前缀旁路，必须查询 `asset_object` 并校验配置 bucket、精确 key、`PublicRead` 或当前 owner。External OpenAPI 的 `/api/external/v1/assets/read-url` 还必须有 `editor:asset` scope，并始终以 API Key 绑定的 `owner_user_id` 执行同一 owner 校验；后台跨账号预览只能走管理员鉴权后的 `/admin/api/assets/read-url`。`/api/assets/read-bytes` 与主站 read-url 共用完全相同的授权，默认仍应由浏览器使用 signed URL 直读，bytes 只作跨域字节读取 fallback。前端如果收到同一 OSS bucket 的完整 `https://*.oss-*.aliyuncs.com/generated-*` 地址，也必须先归一为 legacy path 后走同一换签链路，避免裸连私有 bucket 403 或绕过签名缓存。OSS 签名、读签名、HEAD 和 PUT 的结构化日志由 `platform-oss` 输出，排查资产写入 / 确认失败时优先按 `operation`、`object_key` / `key_prefix`、`status_class`、`error_kind` 和 `elapsed_ms` 下钻。新上传 generated 私有对象默认写入 `Cache-Control: public, max-age=31536000, immutable`；旧对象若缺该头，只能依赖 `ETag` / `Last-Modified` 协商缓存，应通过 OSS 元数据刷新或 CDN 配置补齐，不要恢复 api-server 静态代理。`editor-agent/` 前缀只用于服务端内部读写画布 Agent 会话消息文档，不属于浏览器直传 legacy public prefix；`/api/assets/direct-upload-tickets` 必须拒绝 `legacyPrefix=editor-agent`，内部读取只允许 `editor-agent/{conversationId}.json` 形态。 -- 外部 API 失败审计：外部供应商调用未成功时，`api-server` 必须发送 OTLP 失败事件并写入 `tracking_event`。VectorEngine 图片 provider 在 `platform-image` 内输出结构化日志和 `PlatformImageFailureAudit`，覆盖 `request_send`、`response_body`、`upstream_status`、`response_parse`、`missing_image` 和 `image_download` 阶段；编辑器 `screenColor=auto` 的 gpt-5-mini 背景色决策同样必须审计每次已发出的 LLM 调用失败，包括传输 / 超时、上游拒绝、响应体解析、空响应和返回候选外颜色；即使随后降级默认背景色并继续主流程也不得只记 warning。`api-server` 将这些失败映射成 `external_api_call_failure`，`scope_kind = module`、`scope_id = provider`、`module_key = external-api`。metadata 固定包含 provider、endpoint、operation、failureStage、statusCode、statusClass、timeout、retryable、errorMessage、latencyMs、promptChars、referenceImageCount、imageModel、rawExcerpt，以及在调用方可获得上下文时补充的 `userId`（触发者）和 `profileId`（草稿 / 作品 / 场景作用域）。图片生成入口应优先把 owner user id 和 profile id 透传到失败审计，不要只保留 provider 级聚合，否则很难按“谁触发、哪个作品触发”定位问题。入库优先复用 tracking outbox，outbox 不可写或保护阈值拒绝时回退同步写 SpacetimeDB；不得新增前端兜底或在 SpacetimeDB reducer 内做外部 I/O。 +- 外部 API 失败审计：外部供应商调用未成功时，`api-server` 必须发送 OTLP 失败事件并写入 `tracking_event`。VectorEngine 图片 provider 在 `platform-image` 内输出结构化日志和 `PlatformImageFailureAudit`，覆盖 `request_send`、`response_body`、`upstream_status`、`response_parse`、`missing_image` 和 `image_download` 阶段；编辑器 `screenColor=auto` 的 gpt-5-mini 背景色决策同样必须审计每次已发出的 LLM 调用失败，包括传输 / 超时、上游拒绝、响应体解析、空响应和返回候选外颜色；即使随后降级默认背景色并继续主流程也不得只记 warning。`api-server` 将这些失败映射成 `external_api_call_failure`，`scope_kind = module`、`scope_id = provider`、`module_key = external-api`。metadata 固定包含 provider、endpoint、operation、failureStage、statusCode、statusClass、timeout、retryable、errorMessage、latencyMs、promptChars、referenceImageCount、imageModel、rawExcerpt，以及在调用方可获得上下文时补充的 `userId`（触发者）和 `profileId`（草稿 / 作品 / 场景作用域）。图片生成入口应优先把 owner user id 和 profile id 透传到失败审计，不要只保留 provider 级聚合，否则很难按“谁触发、哪个作品触发”定位问题。普通调用入库优先复用 tracking outbox，outbox 不可写或保护阈值拒绝时回退同步写 SpacetimeDB；不得新增前端兜底或在 SpacetimeDB reducer 内做外部 I/O。`bgfilter-worker` 是受限资源例外：它使用共享 tracking outbox 基础目录下独立的 `bgfilter-worker/` 子目录，provider 失败审计在 spawn 前受进程级 `1024` 硬上限保护并由 shutdown tracker 跟踪；满载、outbox 缺失、保护阈值拒绝或写盘失败时直接丢弃并观测，不回退同步直写 SpacetimeDB。优雅退出先排空已获准任务的 enqueue，再封存并尽力 flush；进程被强杀时只有已 enqueue 记录可在下次启动重放。 - 外部生成运行记录：所有外部生成编排的完成态统一写入 `tracking_event`，`event_key = external_generation_run`，`scope_kind = module`，`scope_id = provider`，`module_key = external-generation`。metadata 固定包含 `runId`、`provider`、`operation`、`requestLabel`、`requestPayload`、`status`、`success`、`failureReason`、`providerRequestId`、`resultPayload`、`startedAtMicros`、`completedAtMicros` 和 `durationMs`。这类记录只用于运行审计和排障，不再走 `ai_task` 旧表。 ## SpacetimeDB 表目录 diff --git a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md index 43b7caa38..96f99c19b 100644 --- a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md +++ b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md @@ -27,13 +27,14 @@ npm run dev 该命令启动： - SpacetimeDB standalone。 +- 独立 `bgfilter-worker`。 - Rust `api-server`。 - 主站 Vite。 - 后台 Vite。 -`npm run dev` 和单模块 `npm run dev:web`、`npm run dev:api-server`、`npm run dev:spacetime`、`npm run dev:admin-web` 启动后都会更新根目录 `.app/dev-stack.json`。该文件记录本次命令、数据库、更新时间，以及 `spacetime`、`api-server`、`web`、`admin-web` 的 `pid`、监听 host / port、可访问 URL、启动状态和当前命令。`.app/` 是本地运行态目录，不提交 Git；端口漂移、服务重启或子进程退出后以该文件里的实际状态为准。 +`npm run dev` 和单模块 `npm run dev:web`、`npm run dev:api-server`、`npm run dev:bgfilter-worker`、`npm run dev:spacetime`、`npm run dev:admin-web` 启动后都会更新根目录 `.app/dev-stack.json`。该文件记录本次命令、数据库、更新时间，以及 `spacetime`、`api-server`、`bgfilter-worker`、`web`、`admin-web` 的 `pid`、监听 host / port、可访问 URL、启动状态和当前命令。`.app/` 是本地运行态目录，不提交 Git；端口漂移、服务重启或子进程退出后以该文件里的实际状态为准。 -通过 `nohup` 在仓库根目录启动 dev 栈且未显式重定向 stdout / stderr 时，默认 `nohup.out` 会持续收集 SpacetimeDB、api-server、主站 Vite 和后台 Vite 的整套 dev 栈输出；该文件已被主站 Vite watcher 和 Git 忽略，避免日志追加触发页面刷新循环，重启主站 Vite 后生效。若把输出显式重定向到其它仓库内文件（例如 `> dev.out`），该自定义文件不会自动获得同样的 watcher 保护，应改为写到 Vite root 之外，或同步配置精确的忽略规则。 +通过 `nohup` 在仓库根目录启动 dev 栈且未显式重定向 stdout / stderr 时，默认 `nohup.out` 会持续收集 SpacetimeDB、api-server、bgfilter-worker、主站 Vite 和后台 Vite 的整套 dev 栈输出；该文件已被主站 Vite watcher 和 Git 忽略，避免日志追加触发页面刷新循环，重启主站 Vite 后生效。若把输出显式重定向到其它仓库内文件（例如 `> dev.out`），该自定义文件不会自动获得同样的 watcher 保护，应改为写到 Vite root 之外，或同步配置精确的忽略规则。 单独启动主站前端： @@ -47,32 +48,41 @@ npm run dev:web npm run dev:api-server ``` -Linux 本机多用户并发开发时，`npm run dev` 和 `npm run dev:*` 单模块命令会先在系统级端口段注册表里给当前用户分配一个端口段，再把该段映射为 `web = start`、`api = start + 1`、`spacetime = start + 2`、`admin-web = start + 3`。默认注册表目录是 `/var/tmp/genarrative-dev-port-ranges/`，其中 `registry.json` 记录各用户的活跃段，`registry.lock` 负责串行化分配；可以用 `GENARRATIVE_DEV_PORT_RANGE_REGISTRY_DIR` 覆盖目录。系统自动分配时从 `10000-10099` 开始，每次占用 100 个端口块，后续块按 `10100-10199`、`10200-10299` 递增；`GENARRATIVE_DEV_PORT_RANGE` 或 `--port-range` 只在 Linux 上生效，Windows 仍按原来的 3000 / 8082 / 3101 / 3102 端口探测与漂移逻辑运行，不读这个系统级注册表。 +`npm run dev:api-server` 会由同一个启动器安全带起它依赖的独立 BgFilter worker，两者共享本次运行生成或显式配置的内部 Token；不要另外启动第二份 worker。只需单独运行内部 worker 时使用： -后端日志默认写入 `logs/api-server/`。后端 API smoke 使用 `npm run dev:api-server` 并检查 `/healthz`；需要确认实例可接生产流量时检查 `/readyz`。不要使用旧 `api-server:maincloud` 或任何 `GENARRATIVE_SPACETIME_MAINCLOUD_*` 口径。 +```bash +npm run dev:bgfilter-worker +``` -Windows 本地 `npm run dev` / `npm run dev:api-server` 会用空的 `RUSTC_WRAPPER` / `CARGO_BUILD_RUSTC_WRAPPER` 覆盖 `server-rs/.cargo/config.toml` 里的 `sccache`，从而直连真实 `rustc`。不要把 wrapper 绕过值写成 `rustc`；Cargo 会按 wrapper 协议调用 `rustc <真实rustc路径> - ...`，最终报 `multiple input filenames provided` 并导致 api-server 无法启动。排查本地启动失败时，先看 dev 日志是否出现该错误，再确认脚本注入的 wrapper 为空。 +Linux 本机多用户并发开发时，`npm run dev` 和 `npm run dev:*` 单模块命令会先在系统级端口段注册表里给当前用户分配一个端口段，再把该段映射为 `web = start`、`api = start + 1`、`spacetime = start + 2`、`admin-web = start + 3`、`bgfilter-worker = start + 4`。默认注册表目录是 `/var/tmp/genarrative-dev-port-ranges/`，其中 `registry.json` 记录各用户的活跃段，`registry.lock` 负责串行化分配；可以用 `GENARRATIVE_DEV_PORT_RANGE_REGISTRY_DIR` 覆盖目录。系统自动分配时从 `10000-10099` 开始，每次占用 100 个端口块，后续块按 `10100-10199`、`10200-10299` 递增；`GENARRATIVE_DEV_PORT_RANGE` 或 `--port-range` 只在 Linux 上生效，Windows 仍按原来的 3000 / 8082 / 3101 / 3102 / 8083 优先端口统一探测并漂移，不读这个系统级注册表。父 API 与 worker 始终使用解析后的实际 `GENARRATIVE_BGFILTER_WORKER_BASE_URL`，不能写死 `8083`。 + +后端日志默认写入 `logs/api-server/`，独立 BgFilter worker 日志默认写入 `logs/bgfilter-worker/`。后端 API smoke 使用 `npm run dev:api-server`，先检查 BgFilter worker `/readyz`，再检查 API `/healthz`；需要确认 API 实例可接生产流量时检查 API `/readyz`。不要使用旧 `api-server:maincloud` 或任何 `GENARRATIVE_SPACETIME_MAINCLOUD_*` 口径。 + +Windows 本地 `npm run dev` / `npm run dev:api-server` / `npm run dev:bgfilter-worker` 会用空的 `RUSTC_WRAPPER` / `CARGO_BUILD_RUSTC_WRAPPER` 覆盖 `server-rs/.cargo/config.toml` 里的 `sccache`，从而直连真实 `rustc`。完整栈和 `dev:api-server` 把 API 与 BgFilter worker 作为一个 Rust 重启单元：源码变化时先停两个进程，再先启动并验活 worker、最后启动并验活 API，避免两个 `cargo run` 并发链接同一个 Windows 可执行文件。不要把 wrapper 绕过值写成 `rustc`；Cargo 会按 wrapper 协议调用 `rustc <真实rustc路径> - ...`，最终报 `multiple input filenames provided` 并导致 api-server 无法启动。排查本地启动失败时，先看 dev 日志是否出现该错误，再确认脚本注入的 wrapper 为空。 Windows 本地如果已在 `%LOCALAPPDATA%\Genarrative\ffmpeg\bin` 安装 FFmpeg，`npm run dev` / `npm run dev:api-server` 会自动把该目录加入本次 `api-server` 子进程 `Path`，并注入 `CHARACTER_ANIMATION_FFMPEG_PATH` / `CHARACTER_ANIMATION_FFPROBE_PATH` 的绝对路径。这样即使外层终端或长期运行的 dev 进程是在安装 FFmpeg 之前启动，角色动画抽帧也不会继续因为 `ffmpeg: program not found` 失败；若手动配置了上述环境变量或 `GENARRATIVE_CHARACTER_ANIMATION_*` 前缀变量，显式配置优先。 -开发态 `npm run dev` 与 `npm run dev:api-server` 会默认注入 `GENARRATIVE_DEV_PASSWORD_ENTRY_AUTO_REGISTER_ENABLED=true` 和 `GENARRATIVE_PROCESS_ROLE=all`，因此密码登录在本地开发环境可直接注册未知手机号账号，且本地 `api-server` 会同时监听 HTTP 并消费外部生成队列；显式设置 `GENARRATIVE_PROCESS_ROLE` 时保留显式值。Linux 本地默认 `all` 角色启动前，dev 脚本会停止当前仓库、同一个 SpacetimeDB server / database 下遗留的 `GENARRATIVE_PROCESS_ROLE=external-generation-worker` 进程，避免旧 worker 二进制继续抢同一条队列并在业务写回时制造 procedure 超时；显式拆分 `api` / `external-generation-worker` 做生产式验证时不会触发这项清理。生产环境仍按 `api-server` 配置默认关闭密码自动注册，并由独立 worker 进程消费队列。 +开发态 `npm run dev` 与 `npm run dev:api-server` 都会注入 `GENARRATIVE_DEV_PASSWORD_ENTRY_AUTO_REGISTER_ENABLED=true`，因此密码登录在本地开发环境可直接注册未知手机号账号。完整 `npm run dev` 会强制父 API 使用 `GENARRATIVE_PROCESS_ROLE=all`，忽略外层显式角色，确保本地 `api-server` 同时监听 HTTP 并消费外部生成队列；只有单模块 `npm run dev:api-server` 会保留显式 `GENARRATIVE_PROCESS_ROLE`，未设置时默认为 `all`。`all` 不内嵌 BgFilter worker；启动器总是先启动并验活独立 `GENARRATIVE_PROCESS_ROLE=bgfilter-worker` 进程，再启动父 API，并向两者注入同一个内部 base URL / Token。Linux 本地默认 `all` 角色启动前，dev 脚本会停止当前仓库、同一个 SpacetimeDB server / database 下遗留的 `GENARRATIVE_PROCESS_ROLE=external-generation-worker` 进程，避免旧 worker 二进制继续抢同一条队列并在业务写回时制造 procedure 超时；显式拆分 `api` / `external-generation-worker` 做生产式验证时不会触发这项清理。生产环境仍按 `api-server` 配置默认关闭密码自动注册，并由独立 worker 进程消费队列。 本地排查外部内容生成 worker 队列时，默认同一 Rust 进程同时监听 HTTP 并消费 `external_generation_job` 队列；更接近生产的验证应分别启动 `api`、`external-generation-worker` 和 `external-generation-controller`。生产默认 `GENARRATIVE_PROCESS_ROLE=api`，外部生成任务由独立 `GENARRATIVE_PROCESS_ROLE=external-generation-worker` 进程消费；生产与容器扩缩容验证保持 `queue`。当前 worker 只领取 `source_module = editor-canvas` 的图片画布任务，包括 `editor_image_generation`、`editor_image_edit`、`editor_background_removal`、`editor_icon_spritesheet_generation`、`editor_ui_design_asset_extraction`、`editor_character_animation_generation`、`editor_video_generation`、`editor_sound_effect_generation` 和 `editor_background_music_generation`。旧玩法历史任务即使仍为 pending / running 也不领取、不改状态；显式把本地进程角色设为 `api` 且没有 worker 时，现役编辑器生成请求只返回 queued/running，不会兜底执行外部 provider。 HTTP 角色的 `GENARRATIVE_SPACETIME_POOL_SIZE` 只表示 procedure / reducer 调用池大小；池连接不订阅 read model。HTTP 角色会额外创建 1 条共享缓存读连接，当前只保留可选的 `user_account` 读取；配置为 `8` 时基础连接拓扑是 8 条调用连接加 1 条缓存读连接。`/readyz` 同时检查调用池与缓存读连接，缓存连接未准备好时不能放量。 -生产拆分角色时，`external-generation-worker` 和 `external-generation-controller` 的专属 env 示例会把 `GENARRATIVE_SPACETIME_POOL_SIZE` 覆盖为 `1`；非 HTTP 角色不创建 API 缓存读连接，只保留 `external_generation_job` 队列窄订阅作为响应式唤醒信号，实际抢占和扩缩容判断仍走 SpacetimeDB procedure。worker / controller 不执行模型定价 seed，启动时先调用受 runtime writer 鉴权的 queue-stats procedure 做只读预检，身份不匹配时 fail-fast；当前正式 systemd unit 通过共同加载 `/etc/genarrative/api-server.env` 继承同一 `GENARRATIVE_SPACETIME_TOKEN`，专属角色 env 示例不重复配置该 token。`GENARRATIVE_EXTERNAL_GENERATION_WORKER_POLL_INTERVAL_MS` 与 controller poll interval 只作为订阅失效、漏事件和 lease 过期这类时间条件的兜底，不作为正常领取任务的主路径。 +生产拆分角色时，`external-generation-worker` 和 `external-generation-controller` 的专属 env 示例会把 `GENARRATIVE_SPACETIME_POOL_SIZE` 覆盖为 `1`；非 HTTP 角色不创建 API 缓存读连接，只保留 `external_generation_job` 队列窄订阅作为响应式唤醒信号，实际抢占和扩缩容判断仍走 SpacetimeDB procedure。worker / controller 不执行模型定价 seed，启动时先调用受 runtime writer 鉴权的 queue-stats procedure 做只读预检，身份不匹配时 fail-fast；当前正式 systemd unit 通过共同加载 API env 继承同一 `GENARRATIVE_SPACETIME_TOKEN`，默认路径为 `/etc/genarrative/api-server.env`，自定义部署由 provision 和 API deploy 按实际参数渲染，专属角色 env 示例不重复配置该 token。`GENARRATIVE_EXTERNAL_GENERATION_WORKER_POLL_INTERVAL_MS` 与 controller poll interval 只作为订阅失效、漏事件和 lease 过期这类时间条件的兜底，不作为正常领取任务的主路径。 生产 worker 默认 `GENARRATIVE_EXTERNAL_GENERATION_WORKER_LEASE_SECONDS=600`，只覆盖 worker 心跳抖动和短暂断连窗口，不再把 lease 当成完整任务时长；默认 `GENARRATIVE_EXTERNAL_GENERATION_WORKER_JOB_TIMEOUT_SECONDS=900`。`editor_image_generation`、`editor_image_edit`、`editor_icon_spritesheet_generation`、`editor_ui_design_asset_extraction` 四类 VectorEngine 图片任务与角色动画 / 视频类长任务使用 `GENARRATIVE_EXTERNAL_GENERATION_WORKER_LONG_JOB_TIMEOUT_SECONDS=1800`，手动去背景、音效和背景音乐继续使用普通预算。worker 在单次尝试超过执行预算后会停止续租并释放 worker 槽位，但不会取消已启动的业务 future 或主动写入失败 / 重试状态；在途执行由 lease fencing 仲裁，有效租约内写回仍可完成，租约过期后任务才可重新领取，attempt 耗尽时由认领事务标记失败并结算退款。生产部署和 provision 脚本会给 `/etc/genarrative/api-server.env` 与 `/etc/genarrative/external-generation-worker.env` 补齐这些变量；已有自定义值不覆盖，只会把历史旧默认 `3600` 迁移为 `600`。 lease 过期后不代表任务一定再次执行：claim transaction 只有在 `attempt < max_attempts` 时才会递增 attempt 并返回 worker；如果过期的是最终 attempt，则直接把 job 收口为 `failed`、清理 lease，并按入队冻结价格为当前 attempt 原子退款或写 cancellation intent。该终态任务不会再次进入 provider executor，迟到 consume 会被 settlement intent 拒绝。 -图片画布角色图、图标素材、UI 素材提取和角色动作逐帧去背景时优先调用 BgFilter；当前全部调用都显式传 `background_mode=flat`，保持单一纯色背景抠图语义。默认 `GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS=180000`，该值是所有路径的基准请求超时；角色动作逐帧请求的每一次 HTTP attempt 额外增加 `2000ms × 本次实际帧数`，默认 `32 / 40 / 48` 帧对应 `244000 / 260000 / 276000ms`，角色形象单图、图标、UI 和手动去背景继续使用基准值。该 request timeout 不是整批帧或整项任务超时，首次失败后的重试会重新计时；角色动作整项任务仍受默认 `GENARRATIVE_EXTERNAL_GENERATION_WORKER_LONG_JOB_TIMEOUT_SECONDS=1800` 预算约束，排查时以 `editor_bgfilter_request_start.timeout_ms` 确认实际值。连续失败达到 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD=3` 后熔断 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS=300` 秒。BgFilter 调用失败和熔断期均先走阿里云通用抠图，只有阿里云失败才走本地幕布色去背景兜底。阿里云这层默认 `GENARRATIVE_ALIYUN_MATTING_ENABLED=true`，但必须在 `api-server.env` 填入 `GENARRATIVE_ALIYUN_MATTING_ACCESS_KEY_ID` / `GENARRATIVE_ALIYUN_MATTING_ACCESS_KEY_SECRET`（或标准 SDK 命名 `ALIBABA_CLOUD_ACCESS_KEY_ID` / `ALIBABA_CLOUD_ACCESS_KEY_SECRET`）才会真正启用；AccessKey 缺失时启动日志会打印「阿里云抠图 AccessKey 未配置，跳过抠图客户端初始化」，抠图直接塌成 BgFilter→本地两级，`npm run check:api-server-env` 也会给出对应告警。修改这些变量后需要重启对应 `api-server` / worker 进程；排查时先从 worker 启动日志确认 lease 和 job timeout，再看带 `background_mode=flat` 的 `editor_bgfilter_request_start`、`editor_bgfilter_fallback_to_aliyun_matting`、`editor_bgfilter_circuit_open_fallback_to_aliyun_matting`，以及阿里云失败后的 `editor_aliyun_matting_fallback_to_local_screen_background_removal` 日志。 -手动 `POST /api/editor/images/background-removals` 同样调用 BgFilter，但 worker 只解析并校验已有 OSS object key，直接签发 600 秒 URL，不下载原图；multipart 固定传 `image_url`、`background_mode=complex`、`seg_model=birefnet`、`cross_check=off`，不传 `file` 或背景色。首次失败后立即重试 `1` 次，两次都失败则返回最终错误。它不进入只适用于已知纯色背景的阿里云 / 本地键色兜底链，也不改变 flat 路径的熔断状态。标准纯色背景四条链路仍固定传 `background_mode=flat`。两种模式统一使用 `GENARRATIVE_EDITOR_BGFILTER_BASE_URL`、`GENARRATIVE_EDITOR_BGFILTER_TOKEN`、`GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS` 和共享 HTTP client；旧 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN` 只保留为 token 兼容别名。 +图片画布角色图、图标素材、UI 素材提取和角色动作逐帧去背景使用 `background_mode=flat`；手动 `POST /api/editor/images/background-removals` 使用 `background_mode=complex`、`seg_model=birefnet`、`cross_check=off`。父流程不再直连 BgFilter，而是把已持久化的私有 OSS object key、模式参数、排队预算 `maxQueueWaitMs` 和调用预算 `callBudgetMs` 交给唯一的 loopback `bgfilter-worker`。子 worker 负责签发短期源 URL、全局 admission `Q`、provider 并发 `N`、最多两次顺序 attempt、结果校验和按 flat / complex 隔离的进程级熔断；成功时直接用内部 HTTP 二进制 body 把原始结果图片字节返回父流程，不写 raw OSS。当前冻结 `N=16`、单图估时 `est=5000ms`，`Q` 默认 `2048` 且仅作为连接风暴保险丝；角色动画仍可同时提交最多 `48` 个单帧逻辑调用，但健康 worker 中实际在飞的 BgFilter provider 请求不超过 `N`。 + +BgFilter 不再配置独立的固定 attempt timeout。父子共同按 `attempt = N × est × 2` 派生单次真实 provider attempt 上限，并按 `callBudgetMs = 2 × attempt + 1s` 派生调用预算；当前 `N=16 / est=5000ms` 时分别为 `160s / 321s`。父侧仍管理父 job 总预算，按剩余绝对预算派生 `maxQueueWaitMs`；子 worker 从 admission 开始只用该字段等待 provider permit，取得 permit 后才启动 `callBudgetMs`，排队不侵蚀两次完整 attempt 窗口。flat 还由父侧预留阿里云 request timeout 和本地处理余量。flat 两次失败、熔断、overload 或内部 RPC 故障且父业务预算仍有效时，父流程才继续“阿里云通用抠图 → 本地键色”；阿里云 fallback 不属于 BgFilter worker。complex 的真实 provider 失败只累计自身熔断，任意失败或熔断仍直接使父流程失败，不接 flat fallback，也不影响 flat 状态。父侧不会重试已被 worker 接收的内部 HTTP（连接从未建立的失败按调度方案 §5.1 有界重连），避免子侧两次乘成四次 provider attempt。 + +阿里云通用抠图默认 `GENARRATIVE_ALIYUN_MATTING_ENABLED=true`，但必须在 `api-server.env` 填入 `GENARRATIVE_ALIYUN_MATTING_ACCESS_KEY_ID` / `GENARRATIVE_ALIYUN_MATTING_ACCESS_KEY_SECRET`（或标准 SDK 命名 `ALIBABA_CLOUD_ACCESS_KEY_ID` / `ALIBABA_CLOUD_ACCESS_KEY_SECRET`）才会真正启用；AccessKey 缺失时启动日志会打印「阿里云抠图 AccessKey 未配置，跳过抠图客户端初始化」，flat 失败后直接进入本地键色。两种模式的 provider 配置统一使用 `GENARRATIVE_EDITOR_BGFILTER_BASE_URL`、`GENARRATIVE_EDITOR_BGFILTER_TOKEN`，父子共同使用 `GENARRATIVE_BGFILTER_WORKER_CONCURRENCY` 与 `GENARRATIVE_EDITOR_BGFILTER_SINGLE_IMAGE_ESTIMATE_MS` 派生预算；旧 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN` 只保留为 token 兼容别名。修改 provider、内部 worker 或 fallback 配置后，需要按角色重启对应进程。 阿里云通用抠图的非上海地域输入使用 `AuthorizeFileUpload → Policy POST → SegmentCommonImage` 正式链路，上传 Bucket / Endpoint / ObjectKey 由阿里云动态返回；不得恢复 `GetOssStsToken`、固定 `viapi-customer-temp`、临时 AK/SK 或 OSS V1 PUT。该切换不新增环境变量；真实链路冒烟可运行 `cargo run -p platform-matting --example segment_smoke --manifest-path server-rs/Cargo.toml -- <图片路径>`，预期日志中的输入 host 为授权响应返回的上海 OSS host，并完成结果下载。图片字节仍经过执行任务的 api-server / worker，排障时不要把 Advance 路径误判为阿里云直接抓取任意公网 URL。 -BgFilter 对已经落入私有 OSS 的生成原图、动作抽取帧和手动去背景源图直接使用 600 秒签名 URL：`api-server` 的 multipart 提交 `image_url` 及对应模式参数，不再提交 `file`，也不会在 BgFilter 调用前重新下载 OSS 对象。生成原图和动作帧上传完成后应已消费并释放字节所有权；手动路径从始至终不读取原图字节。flat 路径的 BgFilter 失败或熔断打开后，阿里云 fallback 才单独下载源对象并上传动态临时桶，临时上传完成即释放本次下载缓冲；阿里云继续失败时本地 fallback 再独立下载，并在本地处理产出后释放本次原图缓冲。排障日志只应出现 object key 与签名有效期，不得记录带 `x-oss-*` 查询参数的完整 URL。这里的释放是 Rust 缓冲析构，不以操作系统 RSS 立即下降作为判据。 +BgFilter 对已经落入私有 OSS 的生成原图、动作抽取帧和手动去背景源图继续使用短期签名 URL，但签名只在 `bgfilter-worker` 内生成并传给 provider；父进程到子进程只传 object key 和参数，不传源图字节或签名 URL。子 worker 完整读取并校验 provider 成功 body 后，把同一图片内容作为受限原始字节响应返回；父流程继续负责 Alpha / 尺寸恢复、动画 finalizer、最终 OSS、画布写回、计费和终态。flat fallback 才由父流程按原路径下载源对象供阿里云或本地键色使用。排障日志只应出现 object key 与签名有效期，不得记录带 `x-oss-*` 查询参数的完整 URL、内部 Token 或图片字节。 图片编辑器任务侧栏与生成提交工作流只读取 BFF 队列接口：`GET /api/runtime/external-generation/jobs` 列出当前用户任务，`GET /api/runtime/external-generation/jobs/{jobId}` 查看单 job 状态，概览场景可使用 `GET /api/runtime/external-generation/queue-overview`。前端不直接查询 `external_generation_job` private table，也不展示 worker 内部 payload；完成态以编辑器项目和资源接口返回的正式数据为准。 @@ -203,11 +213,11 @@ npm run check 仓库级 Gitea Actions 工作流固定为 `.gitea/workflows/project-ci.yml`，在向 `master` 或 `codex/ai-game-creator-app` 推送、创建或更新 PR，以及手工触发时运行。工作流拆成四个必须通过的 job： - `Repository checks`：执行 `npm run lint`、主站与后台生产构建、内容数据检查和提交差异空白检查。 -- `Frontend tests`：独立执行根 `npm run test`，让 Vitest 文件数和测试数在 Gitea job 列表中明确可见。 +- `Frontend tests`：独立执行根 `npm run test`、`npm run bgfilter-worker:smoke-test`、`npm run check:production-health-patrol`、`npm run check:production-api-release` 和 `npm run check:production-api-deploy`，让 Vitest、Node test smoke harness 及不依赖真实服务的生产巡检 / 发布 / 部署行为 fixture 在 Gitea job 中持续执行；其中 `.test.mjs` 使用 Node test runner，不依赖 Vitest 的 `scripts/**/*.test.ts` 收集规则。 - `Backend tests`：执行 `npm run check:server-rs-ddd`、`cargo test --locked --workspace --no-fail-fast`、`api-server --all-targets` 编译和 `spacetime-module` 编译；runner 安装 `ffmpeg`，避免视频抽帧测试因工具缺失提前返回。依赖真实服务或密钥的测试必须显式 `ignored`，不能让普通 PR job访问现场环境。 - `Native shell tests`：独立执行 `npm run check:native-shells`，覆盖微信壳、Expo 和 Tauri 的完整验收，并确认 Tauri `Cargo.lock` 没有被构建过程改写，避免把重型原生壳或依赖锁漂移隐藏在基础检查末尾。`codex/ai-game-creator-app` 分支的同名脚本还会执行 `npm run ai-game-creator-shell:check` 和 AI 游戏创作壳 release build smoke。 -四个 job 合起来覆盖根 `npm run check`，并补齐根检查没有包含的 server-rs DDD、正式 workspace Rust 测试与现役后端编译门禁。普通 PR CI 不注入业务密钥，不启动真实 API、SpacetimeDB、OSS、支付、图片生成或生产 live smoke；需要现场环境、可变外部状态、Docker 编排或发布凭据的 `check:*` 继续按对应专题和 Jenkins 发布流程执行，不能遍历所有同名前缀脚本冒充 PR 门禁。 +四个 job 合起来覆盖根 `npm run check`，并补齐根检查没有包含的 BgFilter worker smoke harness、无密钥生产巡检 / 发布 / 部署行为 fixture、server-rs DDD、正式 workspace Rust 测试与现役后端编译门禁。普通 PR CI 不注入业务密钥，不启动真实 API、SpacetimeDB、OSS、支付、图片生成或生产 live smoke；需要现场环境、可变外部状态、Docker 编排或发布凭据的 `check:*` 继续按对应专题和 Jenkins 发布流程执行，不能遍历所有同名前缀脚本冒充 PR 门禁。 PR checkout 必须保留完整 Git 历史，并把 PR base SHA 传给 `SPACETIME_SCHEMA_BASE_REF`。`check:spacetime-schema` 依赖该基线识别已有表字段删除、改名、重排和改类型；事件给出的基线缺失或本地不可解析时必须直接失败，不能退化为空差异检查。Gitea 的 PR checkout 是 PR head，不是与目标分支的预合并 commit，因此 workflow 还会验证 PR head 包含事件中的最新 base commit；分支保护必须继续开启“PR 过期禁止合并”，过期分支先更新再重跑。向 `master` 直接推送时使用 push before SHA，手工触发时回退到 `origin/master`。 @@ -461,13 +471,14 @@ 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_HEALTH_PATROL_GATEWAY_MODE=nginx`，检查 `genarrative-api.service`、`genarrative-external-generation-controller.service`、`spacetimedb.service`、`nginx.service` 是否 active；Pingora 直连切换后改为 `pingora-direct`，检查 `genarrative-api.service`、`genarrative-external-generation-controller.service`、`spacetimedb.service`、`genarrative-pingora-gateway.service`，不再要求 `nginx.service` active。 +- 默认 `GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE=nginx`，检查 `genarrative-api.service`、唯一的 `genarrative-bgfilter-worker.service`、`genarrative-external-generation-controller.service`、`spacetimedb.service`、`nginx.service` 是否 active；Pingora 直连切换后改为 `pingora-direct`，仍要求 BgFilter worker active，只把网关检查从 `nginx.service` 切到 `genarrative-pingora-gateway.service`。 - 至少一个 `genarrative-external-generation-worker@*.service` 实例是否 active；如果 controller 存活但 worker 全部退出，巡检直接返回 `CRITICAL`，避免外部生成队列长期无人消费。 - API 直连 `/healthz`、`/readyz`。 +- BgFilter worker 直连 `http://127.0.0.1:8083/readyz`；可通过 `GENARRATIVE_HEALTH_PATROL_BGFILTER_BASE_URL` 覆盖探测地址。 - SpacetimeDB 直连 `/v1/ping`。 - 默认通过本机公网网关入口检查 `/`；需要增加现役公开 API 时，用可重复的 `--public-path` 或对应环境配置显式追加 `/api/editor/showcase/resources`。如需走正式域名，在 `/etc/genarrative/health-patrol.env` 配置 `GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL=https://<域名>`。若在目标机本机打 `https://127.0.0.1` 或 `http://127.0.0.1`，同时配置 `GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST=<域名>`，确保 public probe 命中正确 vhost / Host 语义；不得把已退役模板 API 重新加入健康探针。 - Pingora 影子网关只在同时配置 `GENARRATIVE_HEALTH_PATROL_PINGORA_BASE_URL` 与 `GENARRATIVE_HEALTH_PATROL_PINGORA_PROBE_TOKEN` 时纳入巡检；脚本会访问 `GET /__genarrative_pingora/healthz` 并校验返回 `gateway=pingora-shadow`，未配置时不影响现有生产巡检。 -- 最近 15 分钟对应 gateway mode 下 `genarrative-api.service`、`genarrative-external-generation-controller.service`、`genarrative-external-generation-worker@*.service`、`spacetimedb.service` 和 `nginx.service` 或 `genarrative-pingora-gateway.service` 的 `err..alert` 日志。 +- 最近 15 分钟对应 gateway mode 下 `genarrative-api.service`、`genarrative-bgfilter-worker.service`、`genarrative-external-generation-controller.service`、`genarrative-external-generation-worker@*.service`、`spacetimedb.service` 和 `nginx.service` 或 `genarrative-pingora-gateway.service` 的 `err..alert` 日志。 巡检脚本的显式 `--timeout-ms`、`--slow-ms`、`GENARRATIVE_HEALTH_PATROL_TIMEOUT_MS` 和 `GENARRATIVE_HEALTH_PATROL_SLOW_MS` 必须是正整数，非法值会直接失败，不静默回退默认 `5000ms` / `3000ms`；生产巡检、health patrol env 复核和 env 切换脚本读取的布尔 env 也必须是明确布尔值，非法值会直接失败。health patrol env 复核脚本的 `--env-file`，以及 env 切换脚本的 `--env-file` / `--check-script` 都必须是绝对路径且不能是文件系统根目录，也不能包含换行或 NUL；env 切换脚本写入的 public base URL / Host 同样不能包含换行或 NUL。env 切换 `--apply` 还必须直接指向真实普通 env 文件，不能传符号链接。切换窗口调整超时、慢请求阈值、巡检模式开关或 env 路径时，先确认 env 与命令行参数格式正确，再把失败当作配置错误处理。 @@ -594,7 +605,11 @@ Nginx 与 Pingora 在维护 marker 存在时对内网来源绕过整站维护闸 生产环境变量模板：`deploy/env/api-server.env.example`。真实密钥只放服务器，不提交 Git，不写入文档示例。 -`api-server` 进程角色由 `GENARRATIVE_PROCESS_ROLE` 控制：`api` 只监听 HTTP，`external-generation-worker` 只消费外部生成队列，`external-generation-controller` 只管理 worker systemd 实例，`all` 仅用于本地或临时 smoke，不隐式启动 controller。外部生成策略由 `GENARRATIVE_EXTERNAL_GENERATION_MODE` 控制；生产和容器压测默认保持 `queue`，本地 `npm run dev` / `npm run dev:api-server` 默认由 dev 脚本注入 `GENARRATIVE_PROCESS_ROLE=all`，如果外部生成策略为 `queue` 会由同一进程消费队列。`inline` 只用于本地或低并发同步排查，HTTP handler 会直接复用 worker executor，完成后返回 `completed`，但不会落 `external_generation_job`，也不能通过增加 worker 进程扩吞吐。外部生成 worker 使用同一发布包和同一套 SpacetimeDB 配置，按实例数和 `GENARRATIVE_EXTERNAL_GENERATION_WORKER_CONCURRENCY` 动态扩缩；生产默认由 `genarrative-external-generation-controller.service` 读取 `get_external_generation_queue_stats_and_return`，按 `claimable_pending + running_active + expired_running` 计算目标 worker 数，并对 `genarrative-external-generation-worker@N.service` 精确执行 `systemctl start/stop`。controller 参数模板是 `deploy/env/external-generation-controller.env.example`：默认保底 `MIN_WORKERS=1`、上限 `MAX_WORKERS=8`、每 worker 目标 `TARGET_JOBS_PER_WORKER=2`、`POLL_INTERVAL_MS=10000`、连续 `SCALE_DOWN_IDLE_ROUNDS=6` 轮完全空闲才缩容；缩容每轮只停止最高编号的一个实例，且不主动停止 `@1`。worker 收到 SIGINT/SIGTERM 后会停止 claim 新任务并等待当前任务完成；若进程被硬杀、机器断电或超过 systemd `TimeoutStopSec`，未完成任务才会在 lease 过期后由其它 worker 重领。每个 worker 实例应设置唯一 `GENARRATIVE_EXTERNAL_GENERATION_WORKER_ID`，默认会用主机名和 pid 兜底；systemd 生产模板 `deploy/systemd/genarrative-external-generation-worker@.service` 会用 `%H-%i` 生成实例 ID，并把 tracking outbox 隔离到 `/var/lib/genarrative/tracking-outbox/%H-%i`。`Genarrative-Server-Provision` 会安装 worker 模板、controller unit 和两份专属 env 模板，默认 enable 首个 `genarrative-external-generation-worker@1.service` 与 `genarrative-external-generation-controller.service`；首次 API deploy 会在默认 worker pattern 下自动 `enable --now genarrative-external-generation-worker@1.service` 并等待 worker active，同时重启并验活 controller。手动兜底扩容仍可用 `systemctl start genarrative-external-generation-worker@2.service` / `@3.service`，缩容用 `systemctl stop genarrative-external-generation-worker@N.service`；controller 下轮会按队列压力修正到目标实例数。worker 专属参数模板是 `deploy/env/external-generation-worker.env.example`，密钥与 SpacetimeDB 连接仍复用 `/etc/genarrative/api-server.env`。API 发布脚本默认会重启并验活 `genarrative-external-generation-worker@*.service` 和 `genarrative-external-generation-controller.service`；若本次只发 HTTP 且不希望滚动 worker，可传 `--no-worker-services`，若不希望重启 controller 可传 `--no-worker-controller`。`GENARRATIVE_EXTERNAL_GENERATION_WORKER_POLL_INTERVAL_MS` 控制空队列轮询间隔，`GENARRATIVE_EXTERNAL_GENERATION_WORKER_LEASE_SECONDS` 控制单次 lease，worker 会约每三分之一 lease、最长 30 秒续租；该值应覆盖一次心跳网络抖动窗口，不需要大于完整外部生成链路耗时。SpacetimeDB 使用自身事务时间计算 claim/renew/complete/fail，完成和失败回写还会校验 `lease_token` 与未过期 lease，避免同一 job 被过期 worker 覆盖。首版 worker 粒度是单动作单 job，不拆阶段 job；当前外部生成动作覆盖拼图、跳一跳、拼消消、敲木鱼和图片画布编辑器生成 / 抠图入口，纯元信息保存、发布、试玩启动、运行态动作和公开读取继续 inline。图片画布 worker 成功后由后端保存 `editor_project_resource` / `editor_asset` / `editor_canvas.layers_json`，前端只轮询 job 并重新读取项目快照。当前生成业务失败只做用户重新触发，不做自动业务重试，避免 worker 退款和重试成功之间产生钱包账本漂移。 +BgFilter 受限资源调度使用非模板单实例 `genarrative-bgfilter-worker.service`，固定以 `GENARRATIVE_PROCESS_ROLE=bgfilter-worker` 监听 `127.0.0.1:8083`，不挂 Nginx 或公共路由。`api-server.env` 是父侧与子 worker 的共享基础，集中保存 provider、OSS、冻结的 `GENARRATIVE_BGFILTER_WORKER_CONCURRENCY=16`、`GENARRATIVE_EDITOR_BGFILTER_SINGLE_IMAGE_ESTIMATE_MS=5000`、内部 worker 地址、Token 文件和连接超时；BgFilter unit 先加载它，再加载只含 `HOST / PORT / MAX_REQUESTS`、flat / complex 统一熔断阈值 / cooldown 和可选日志覆盖的 `/etc/genarrative/bgfilter-worker.env`，其中两种模式共享参数但状态独立，阈值默认 `3`、cooldown 默认 `120s`，`MAX_REQUESTS` 默认 `2048` 且只作 admission 保险丝。`N / est` 是父侧派生 `callBudgetMs`、子侧派生 attempt 与队列估时的共同输入，专属 env 不得重复覆盖；同一 provider、OSS、Token 或预算基础配置也只保留一份。外部生成 worker unit 会在共享 API env 后加载 `/etc/genarrative/external-generation-worker.env`；该文件如重复定义内部 base URL、Token / Token 文件、connect timeout、`N / est`、OSS bucket 或 endpoint，最终有效值必须与共享 API env 完全一致，否则发布失败，避免父子预算或对象存储视图漂移。外部生成 worker 可以使用同一 bucket 下权限等价或更小的独立 AK，不要求凭据文本一致。Token 文件由 Provision 以 `root:genarrative 0440` 创建或保留，env 只引用路径，不保存内部 Token 明文；env 示例和仓库不得出现真实 provider / OSS secret。 + +生产发布必须按 `共享配置 / endpoint / Token / N / est / Q 预检 → stop 旧 BgFilter worker → 等待 systemd 排空 → start 唯一实例 → 检查 worker readyz → 重启 API → 重启 external-generation worker / controller` 的顺序执行。readyz URL 由部署脚本从已校验 env 的 `HOST/PORT` 派生（默认 `http://127.0.0.1:8083/readyz`）：`--bgfilter-worker-health-url` 缺省即派生，Jenkins 流水线不传该参数；显式传入时必须与父进程 base URL 和子 worker listener 三方一致，否则预检失败。Token 预检要求 API env 指向非空、非符号链接的普通文件，权限固定为 `root:genarrative 0440`；endpoint 预检要求父进程 `GENARRATIVE_BGFILTER_WORKER_BASE_URL`、子 worker `HOST / PORT` 和 readiness URL 指向同一个 `127.0.0.1:`；预算预检要求共享 `N / est` 均为正整数、父子有效值一致，当前模板默认和压测前冻结值为 `N=16 / est=5000ms`，后续允许按真实压测校准 `est`，不由 deploy 脚本写死；`Q` 缺省为 `2048`，显式值不得小于 `N`，历史模板默认 `128` 会在 deploy / Provision 时定向迁移为 `2048`；熔断 cooldown 的历史模板默认 `300s` 同样会定向迁移为 `120s`；其它显式定制值均保留。任何预检失败都发生在 `current` 切换和停止现役 worker 之前。非模板 unit、固定 loopback 端口和显式 stop/start 共同避免新旧 BgFilter worker 重叠；第二实例会因固定端口绑定失败。内部请求分别携带 `maxQueueWaitMs` 与公式化 `callBudgetMs`；worker 停机时立即让尚未取得 provider permit 的排队请求失败，只排空已经取得 permit 的调用。默认 `callBudgetMs=321s`，unit 使用 `TimeoutStopSec=900` 给最多两次 attempt、响应发送和进程收口留足余量，禁止沿用约 `90s` 的默认停止窗口。默认 API deploy 会安装、enable、启动并验活该 unit；只有明确回滚或应急排障时才使用 `--no-bgfilter-worker` 跳过，且不得让父进程偷偷恢复为直连 BgFilter。 + +`api-server` 进程角色由 `GENARRATIVE_PROCESS_ROLE` 控制：`api` 只监听 HTTP，`external-generation-worker` 只消费外部生成队列，`external-generation-controller` 只管理 worker systemd 实例，`all` 仅用于本地或临时 smoke，不隐式启动 controller。外部生成策略由 `GENARRATIVE_EXTERNAL_GENERATION_MODE` 控制；生产和容器压测默认保持 `queue`，本地 `npm run dev` / `npm run dev:api-server` 默认由 dev 脚本注入 `GENARRATIVE_PROCESS_ROLE=all`，如果外部生成策略为 `queue` 会由同一进程消费队列。`inline` 只用于本地或低并发同步排查，HTTP handler 会直接复用 worker executor，完成后返回 `completed`，但不会落 `external_generation_job`，也不能通过增加 worker 进程扩吞吐。外部生成 worker 使用同一发布包和同一套 SpacetimeDB 配置，按实例数和 `GENARRATIVE_EXTERNAL_GENERATION_WORKER_CONCURRENCY` 动态扩缩；生产默认由 `genarrative-external-generation-controller.service` 读取 `get_external_generation_queue_stats_and_return`，按 `claimable_pending + running_active + expired_running` 计算目标 worker 数，并对 `genarrative-external-generation-worker@N.service` 精确执行 `systemctl start/stop`。controller 参数模板是 `deploy/env/external-generation-controller.env.example`：默认保底 `MIN_WORKERS=1`、上限 `MAX_WORKERS=8`、每 worker 目标 `TARGET_JOBS_PER_WORKER=2`、`POLL_INTERVAL_MS=10000`、连续 `SCALE_DOWN_IDLE_ROUNDS=6` 轮完全空闲才缩容；缩容每轮只停止最高编号的一个实例，且不主动停止 `@1`。worker 收到 SIGINT/SIGTERM 后会停止 claim 新任务并等待当前任务完成；若进程被硬杀、机器断电或超过 systemd `TimeoutStopSec`，未完成任务才会在 lease 过期后由其它 worker 重领。每个 worker 实例应设置唯一 `GENARRATIVE_EXTERNAL_GENERATION_WORKER_ID`，默认会用主机名和 pid 兜底；systemd 生产模板 `deploy/systemd/genarrative-external-generation-worker@.service` 会用 `%H-%i` 生成实例 ID，并把 tracking outbox 隔离到 `/var/lib/genarrative/tracking-outbox/%H-%i`。`Genarrative-Server-Provision` 会安装 worker 模板、controller unit 和两份专属 env 模板，默认 enable 首个 `genarrative-external-generation-worker@1.service` 与 `genarrative-external-generation-controller.service`；首次 API deploy 会在默认 worker pattern 下自动 `enable --now genarrative-external-generation-worker@1.service` 并等待 worker active，同时重启并验活 controller。手动兜底扩容仍可用 `systemctl start genarrative-external-generation-worker@2.service` / `@3.service`，缩容用 `systemctl stop genarrative-external-generation-worker@N.service`；controller 下轮会按队列压力修正到目标实例数。worker 专属参数模板是 `deploy/env/external-generation-worker.env.example`，密钥与 SpacetimeDB 连接默认复用 `/etc/genarrative/api-server.env`。API 发布脚本默认会重启并验活 `genarrative-external-generation-worker@*.service` 和 `genarrative-external-generation-controller.service`；安装随包 BgFilter、external-generation worker 和 controller unit 前，必须按本次 `--current-link`、`--api-env-file`、`--worker-env-file`、`--controller-env-file` 与 `--bgfilter-worker-env-file` 渲染路径，不能用原始模板覆盖 Server-Provision 已安装的自定义路径。`Genarrative-Api-Deploy` 和 `Genarrative-Full-Build-And-Deploy` 必须同时暴露并透传这三类角色 env 参数，避免独立发布脚本修复后又被流水线默认值截断。若本次只发 HTTP 且不希望滚动 worker，可传 `--no-worker-services`，若不希望重启 controller 可传 `--no-worker-controller`。`GENARRATIVE_EXTERNAL_GENERATION_WORKER_POLL_INTERVAL_MS` 控制空队列轮询间隔，`GENARRATIVE_EXTERNAL_GENERATION_WORKER_LEASE_SECONDS` 控制单次 lease，worker 会约每三分之一 lease、最长 30 秒续租；该值应覆盖一次心跳网络抖动窗口，不需要大于完整外部生成链路耗时。SpacetimeDB 使用自身事务时间计算 claim/renew/complete/fail，完成和失败回写还会校验 `lease_token` 与未过期 lease，避免同一 job 被过期 worker 覆盖。首版 worker 粒度是单动作单 job，不拆阶段 job；当前外部生成动作覆盖拼图、跳一跳、拼消消、敲木鱼和图片画布编辑器生成 / 抠图入口，纯元信息保存、发布、试玩启动、运行态动作和公开读取继续 inline。图片画布 worker 成功后由后端保存 `editor_project_resource` / `editor_asset` / `editor_canvas.layers_json`，前端只轮询 job 并重新读取项目快照。当前生成业务失败只做用户重新触发，不做自动业务重试，避免 worker 退款和重试成功之间产生钱包账本漂移。 worker 被硬杀或断电后，lease 过期任务只有尚未耗尽 `max_attempts` 才由其它 worker 重领；最终 attempt 的过期任务由 claim transaction 直接失败并结算，不会继续执行外部 provider。当前业务入队点默认 `max_attempts=1`，因此一次已领取任务若以 lease 过期结束，后续 poll 负责终态与退款收口，而不是发起第二次 provider 请求。 @@ -615,7 +630,7 @@ worker 被硬杀或断电后，lease 过期任务只有尚未耗尽 `max_attempt - Nginx `/api/` 与 `/admin/api/` 通过 `genarrative_api` upstream 代理到 `127.0.0.1:8082`，upstream keepalive 为 64；通用 API 使用 `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 中同时生效。 - 旧作品列表 K6 脚本、gallery 专属限流分组和对应容量结论已经退役；源码只作历史记录，不得作为当前发布门禁。新的容量验收必须针对现役编辑器、项目和素材 API 单独建立数据、负载与指标口径。 -容器化隔离部署方案单独放在 `deploy/container/`，用于本机或预发模拟 Linux release + Nginx + OTLP Collector 拓扑，不替换当前生产 `systemd + Nginx + Jenkins` 发布路径。当前容器模拟参数按 `genarrative-release` 采样值收口为 2 vCPU / 2 GiB RAM / `nofile=4096` / `worker_connections=768`，并在 compose 里落实到 `spacetimedb cpus=1.0 mem_limit=896m`、`api-server cpus=2.0 mem_limit=1g`、`external-generation-worker cpus=2.0 mem_limit=1g`、`nginx cpus=0.5 mem_limit=128m`、`otelcol cpus=0.25 mem_limit=128m`。容器 `api-server` 默认 `GENARRATIVE_API_WORKER_THREADS=4`，只增加 Tokio worker 调度并发，不突破 `api-server cpus=2.0` 的 CPU 配额；容器默认 `GENARRATIVE_EXTERNAL_GENERATION_MODE=queue`，可用 `npm run container:up -- --scale external-generation-worker=N external-generation-worker` 验证现役外部生成 worker 动态扩缩容，`inline` 模式不参与该验证： +容器化隔离部署方案单独放在 `deploy/container/`，用于本机或预发模拟现有的 Linux release + Nginx + OTLP Collector 非 BgFilter 拓扑，不替换当前生产 `systemd + Nginx + Jenkins` 发布路径。当前 compose 没有 `bgfilter-worker`，不构成完整 BgFilter 预发拓扑，也不覆盖任何会触发 BgFilter 的现役任务；它只用于非 BgFilter 路径，或通过下述 unsupported job smoke 验证外部生成队列的 claim / fail 回写和 API-only 更新。当前容器模拟参数按 `genarrative-release` 采样值收口为 2 vCPU / 2 GiB RAM / `nofile=4096` / `worker_connections=768`，并在 compose 里落实到 `spacetimedb cpus=1.0 mem_limit=896m`、`api-server cpus=2.0 mem_limit=1g`、`external-generation-worker cpus=2.0 mem_limit=1g`、`nginx cpus=0.5 mem_limit=128m`、`otelcol cpus=0.25 mem_limit=128m`。容器 `api-server` 默认 `GENARRATIVE_API_WORKER_THREADS=4`，只增加 Tokio worker 调度并发，不突破 `api-server cpus=2.0` 的 CPU 配额；容器默认 `GENARRATIVE_EXTERNAL_GENERATION_MODE=queue`，可用 `npm run container:up -- --scale external-generation-worker=N external-generation-worker` 验证不经过 BgFilter 的外部生成 worker 动态扩缩容，`inline` 模式不参与该验证： ```bash npm run container:init @@ -625,17 +640,27 @@ npm run container:up npm run container:down ``` -容器方案默认暴露 `http://127.0.0.1:18080`，`api-server` 在容器内监听 `0.0.0.0:8082`，Nginx 通过 `api-server:8082` upstream 反代 `/api/` 和 `/admin/api/`。SpacetimeDB 也纳入 compose，容器内由 `spacetimedb:3101` 提供服务，宿主机通过 `http://127.0.0.1:13101` 进行模块发布；Collector 镜像使用 `otel/opentelemetry-collector-contrib:0.151.0`。生产 provision 侧现在由目标 dev / release agent 自己准备 `provision-tools/otelcol-contrib`，并安装本机 `otelcol-contrib.service`，真实库名、token 和外部服务密钥只写本地 `deploy/container/api-server.env`，不提交 Git。旧 gallery K6 profile 已退役；完整现役拓扑、端口和 OTLP debug exporter 使用方法见 `deploy/container/README.md`。 +容器方案默认暴露 `http://127.0.0.1:18080`，`api-server` 在容器内监听 `0.0.0.0:8082`，Nginx 通过 `api-server:8082` upstream 反代 `/api/` 和 `/admin/api/`。SpacetimeDB 也纳入 compose，容器内由 `spacetimedb:3101` 提供服务，宿主机通过 `http://127.0.0.1:13101` 进行模块发布；Collector 镜像使用 `otel/opentelemetry-collector-contrib:0.151.0`。生产 provision 侧现在由目标 dev / release agent 自己准备 `provision-tools/otelcol-contrib`，并安装本机 `otelcol-contrib.service`，真实库名、token 和外部服务密钥只写本地 `deploy/container/api-server.env`，不提交 Git。旧 gallery K6 profile 已退役；当前容器拓扑（明确不含 BgFilter worker）、端口和 OTLP debug exporter 使用方法见 `deploy/container/README.md`。 `npm run container:config` 默认只做 quiet 校验，避免把本地 env 中的 token 展开到终端；确需排查完整 compose 时再传 `-- --print`。 -隔离验证 worker 队列和 API-only 更新时使用 `npm run container:worker-smoke -- smoke`。该命令不复用 `deploy/container/api-server.env`，会在 `deploy/container/worker-smoke/` 生成本机专用 env 与端口 state，并使用 unsupported job 验证 worker claim / fail 回写，不需要真实外部生成密钥；本机 crates.io 网络不稳时使用 `--local-binary`，由容器内 Cargo 复用本机 Cargo 缓存构建，并把产物放进 Debian bookworm smoke runtime。 +隔离验证 worker 队列和 API-only 更新时使用 `npm run container:worker-smoke -- smoke`。该命令不复用 `deploy/container/api-server.env`，会在 `deploy/container/worker-smoke/` 生成本机专用 env 与端口 state，并且只使用 unsupported job 验证 worker claim / fail 回写，不覆盖 BgFilter 成功、失败或 fallback 链路，也不需要真实外部生成密钥；本机 crates.io 网络不稳时使用 `--local-binary`，由容器内 Cargo 复用本机 Cargo 缓存构建，并把产物放进 Debian bookworm smoke runtime。 + +独立 BgFilter worker 的本机全进程验证先运行 `cargo build -p api-server --manifest-path server-rs/Cargo.toml`，再依次运行 `npm run bgfilter-worker:smoke-test`、`npm run bgfilter-worker:load-smoke` 和 `npm run bgfilter-worker:fault-smoke`。三条命令只使用动态 loopback 端口、假 OSS 签名配置和本地 mock provider；不会读取仓库 `.env*` 或请求真实 BgFilter / OSS。自定义或 WSL binary 通过 `GENARRATIVE_BGFILTER_SMOKE_BINARY` 指定。当前 fault 范围包含 overload、queue deadline、两类 HTTP 状态顺序重试结果，以及 provider 成功响应 body 中途 reset 后第二次 attempt 串行成功；慢读、大响应、父侧客户端断连与 SIGTERM 排空另行验证。 + +需要复核真实 OSS + BgFilter 契约时，先启动只监听 loopback 的 worker，并在 worker 与 smoke 的当前进程环境中以不回显方式注入同一个一次性 `GENARRATIVE_BGFILTER_INTERNAL_TOKEN`；token 不得写入命令参数、仓库 env 文件或日志。OSS / BgFilter 凭据继续只放本地私密环境。使用标准 worker 端口 `8083` 时，确认 `http://127.0.0.1:8083/readyz` 成功，再分别设置 `GENARRATIVE_BGFILTER_SMOKE_MODE=flat` 和 `complex`，并显式传入 worker 地址： + +```bash +cargo run -p platform-oss --example bgfilter_worker_live_smoke --manifest-path server-rs/Cargo.toml -- --worker-url http://127.0.0.1:8083 +``` + +示例程序省略 `--worker-url` 时默认访问 `http://127.0.0.1:18083`；该默认值只适合把 worker 显式启动在自定义隔离端口的场景，不是标准 dev / 生产端口。该命令会访问真实服务并产生调用成本；成功标准是 PUT 前 HEAD=404、私有上传成功、无鉴权请求返回精确 401 JSON、带鉴权请求返回 `200 image/png`、DELETE 2xx 且最终 HEAD=404。对象只写入 `generated-character-drafts/bgfilter-smoke//source.png`；正常失败会继续清理，进程崩溃或被强杀时需按输出 object key 人工复核。此 smoke 不经过用户 job、计费或父 flat fallback；完整 `mock worker 失败 → 父 flat → 真实阿里云` 和动画写回链在 staging 验收。 OpenTelemetry 现阶段默认开启 OTLP traces / metrics / logs，但本地日志与 Nginx 文件日志仍保留： - 生产与容器 `api-server` env 模板默认 `GENARRATIVE_OTEL_ENABLED=true`；压测、排障或短期要关闭 OTLP 时，必须显式设置 `GENARRATIVE_OTEL_ENABLED=false`。 - Collector 使用官方 `otelcol-contrib`，安装与启用仍由 `ENABLE_OTELCOL` / provision 控制，只监听 `127.0.0.1:4317/4318`；本地用 `npm run otel:debug` 启动 debug exporter，用 `npm run otel:rider` 转发到 Rider，再接 Jaeger、Tempo、Prometheus、Grafana 或托管平台。 -- api-server 发送 OTLP HTTP 时，生产模板使用 `OTEL_SERVICE_NAME=genarrative-api`、`OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318`，容器模板使用 `OTEL_EXPORTER_OTLP_ENDPOINT=http://otelcol:4318`。 +- api-server 发送 OTLP HTTP 时，生产模板使用 `OTEL_SERVICE_NAME=genarrative-api`、`OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318`，容器模板使用 `OTEL_EXPORTER_OTLP_ENDPOINT=http://otelcol:4318`。生产 `genarrative-bgfilter-worker.service` 强制使用独立的 `OTEL_SERVICE_NAME=genarrative-bgfilter-worker`，并从 worker env 读取同一 Collector 的 endpoint，避免父 API 与受限资源 worker 的遥测混在同一 service identity 下。 - `OTEL_EXPORTER_OTLP_ENDPOINT` 必须指向 Collector 的 HTTP base endpoint；不要填 gRPC `4317`，也不要直接填 Rider 端口，Rider 由 Collector 通过 `RIDER_OTLP_GRPC_ENDPOINT` 转发。 -- 应用日志仍通过 `journalctl -u genarrative-api.service` 查看，Nginx 日志仍写文件；日志等级继续用 `GENARRATIVE_API_LOG` / `RUST_LOG` 控制，例如 `info,tower_http=info,spacetime_client=info`。 +- 应用日志按进程查看：父 API 使用 `journalctl -u genarrative-api.service`，独立 BgFilter worker 使用 `journalctl -u genarrative-bgfilter-worker.service`；Nginx 日志仍写文件。日志等级继续用 `GENARRATIVE_API_LOG` / `RUST_LOG` 控制，例如 `info,tower_http=info,spacetime_client=info`。 - debug exporter / Rider 转发都会同时接收 traces、metrics 和 logs。 - api-server 会随 metrics 发送进程级指标：`process.memory.usage`、`process.memory.virtual`、`process.cpu.time`、`genarrative.process.cpu.usage_percent`、`process.thread.count`、`genarrative.process.memory.private`；Windows 额外发送 `process.windows.handle.count`，Linux 额外发送 `process.unix.file_descriptor.count`。这些指标只描述当前进程，不携带请求、用户或作品 label。 - HTTP 运行态补充发送 `genarrative.http.server.response_bodies.in_flight` 与 `genarrative.http.server.request_permits.available`，后者带低基数 `pool=default|gallery|detail|admin` label，用于区分业务 handler / 背压 permit 是否仍被占用；拼图广场热点缓存补充发送 `genarrative.puzzle_gallery.cache.*` 指标，记录 fresh hit、stale hit、未命中、后台刷新开始 / 失败、重建耗时和预序列化 data JSON 字节数。 @@ -709,7 +734,7 @@ cargo test -p platform-auth --manifest-path server-rs/Cargo.toml aliyun_send_sms 个人任务首版 scope 仅支持 `user`。每日登录任务按北京时间自然日 0 点重置；用户已登录并停留在“我的”页跨日时，前端需要先非阻断调用 refresh session 以写入新业务日 `daily_login`，再请求 `/api/profile/tasks` 刷新任务中心。认证成功后的 `daily_login` 必须通过 `SpacetimeClient::record_daily_login_tracking_event(...)` 调用 SpacetimeDB 专用 `record_daily_login_tracking_event_and_return` procedure，由数据库事务时间生成当日幂等事件并推进任务进度；不要改回普通 `record_tracking_event_after_success`、tracking outbox 或旧 `profile.login.daily` 事件键。后台、RPG、大鱼吃小鱼、Visual Novel、Story、Combat 等特定链路按 tracking 中间件排除规则处理；作品游玩统一使用 `work_play_start`。 -外部 API 失败审计复用 `tracking_event`，不新增表。失败事件优先写入本机 tracking outbox，再由后台 worker 批量落库；如果 outbox 因权限、磁盘或保护阈值不可写，会回退同步直写 SpacetimeDB。`metadata_json` 包含 endpoint、operation、failureStage、statusCode、statusClass、timeout、retryable、errorMessage、errorSource、latencyMs、promptChars、referenceImageCount、imageModel、rawExcerpt、userId、profileId 和 requestId；其中 `userId` 是触发生成的用户，`profileId` 是调用方传入的草稿 / 作品 / 场景作用域，`requestId` 用于回查同一次 HTTP 请求日志，入口拿不到上下文时允许为空。常用查询： +外部 API 失败审计复用 `tracking_event`，不新增表。普通 API / external-generation 调用的失败事件优先写入本机 tracking outbox，再由后台 worker 批量落库；如果 outbox 因权限、磁盘或保护阈值不可写，仍回退同步直写 SpacetimeDB。BgFilter worker 是受限资源例外：provider 失败审计在 spawn 前受进程级 `1024` 硬上限保护，获准任务写入 `GENARRATIVE_TRACKING_OUTBOX_DIR/bgfilter-worker/` 独立目录；任务满载、outbox 缺失、达到保护阈值或写盘失败时直接丢弃并记录指标，不同步直写。`metadata_json` 包含 endpoint、operation、failureStage、statusCode、statusClass、timeout、retryable、errorMessage、errorSource、latencyMs、promptChars、referenceImageCount、imageModel、rawExcerpt、userId、profileId 和 requestId；其中 `userId` 是触发生成的用户，`profileId` 是调用方传入的草稿 / 作品 / 场景作用域，`requestId` 用于回查同一次 HTTP 请求日志，入口拿不到上下文时允许为空。常用查询： ```sql SELECT event_id, scope_id AS provider, metadata_json, occurred_at @@ -749,7 +774,7 @@ GENARRATIVE_TRACKING_OUTBOX_MAX_BYTES=268435456 GENARRATIVE_API_SHUTDOWN_OUTBOX_FLUSH_TIMEOUT_MS=5000 ``` -outbox 采用 NDJSON 文件保存原始事件。达到 `BATCH_SIZE` 时会立刻把当前 active 文件原子封存为 sealed 文件，并马上切到新的 active 继续写入；后台 worker 异步 flush sealed 文件，HTTP 请求线程不等待 SpacetimeDB。`FLUSH_INTERVAL_MS` 只负责兜底封存长时间未满批的 active 文件。SpacetimeDB 批量 procedure 返回成功后删除 sealed 文件，失败则保留文件并重试。`MAX_BYTES` 是磁盘保护阈值，不是 flush 阈值；超过后低价值 route tracking 可以被丢弃并记录日志 / 指标，关键同步事件不进入该丢弃路径。sealed 文件若出现无法解析的坏行，会重命名为 `corrupt-*` 隔离并记录 `genarrative.tracking_outbox.files.corrupt` 指标，避免一个坏文件阻塞后续批量入库。api-server 收到退出信号后会在 `GENARRATIVE_API_SHUTDOWN_OUTBOX_FLUSH_TIMEOUT_MS` 窗口内封存 active 文件并尽力 flush sealed 文件，超时或 SpacetimeDB 暂不可用时保留本地文件给下次启动继续投递。该机制提供至少一次投递语义，依赖 `tracking_event.event_id` 幂等跳过重复事件。 +outbox 采用 NDJSON 文件保存原始事件。达到 `BATCH_SIZE` 时会立刻把当前 active 文件原子封存为 sealed 文件，并马上切到新的 active 继续写入；后台 worker 异步 flush sealed 文件，HTTP 请求线程不等待 SpacetimeDB。`FLUSH_INTERVAL_MS` 只负责兜底封存长时间未满批的 active 文件。SpacetimeDB 批量 procedure 返回成功后删除 sealed 文件，失败则保留文件并重试。`MAX_BYTES` 是每个 outbox 实例的磁盘保护阈值，不是 flush 阈值；超过后低价值 route tracking 和 BgFilter provider 失败审计可以被丢弃并记录日志 / 指标，关键同步事件不进入该丢弃路径。api-server 使用配置目录本身，BgFilter worker 固定使用其 `bgfilter-worker/` 子目录，两个进程不得操作同一个 active 文件。sealed 文件若出现无法解析的坏行，会重命名为 `corrupt-*` 隔离并记录 `genarrative.tracking_outbox.files.corrupt` 指标，避免一个坏文件阻塞后续批量入库。进程收到退出信号后会在 `GENARRATIVE_API_SHUTDOWN_OUTBOX_FLUSH_TIMEOUT_MS` 窗口内封存各自 active 文件并尽力 flush sealed 文件，超时或 SpacetimeDB 暂不可用时保留本地文件给下次同角色启动继续投递。该机制对已 enqueue 记录提供至少一次投递语义，依赖 `tracking_event.event_id` 幂等跳过重复事件；BgFilter 尚未 enqueue 或因硬上限 / 保护阈值被丢弃的审计不在该保证内。 release 机器如果日志每秒刷 `tracking outbox ... Permission denied (os error 13)`，先检查 `/etc/genarrative/api-server.env` 是否缺少 `GENARRATIVE_TRACKING_OUTBOX_DIR`。缺少时 `api-server` 会回退到本地开发默认相对路径 `server-rs/.data/tracking-outbox`，而 systemd 的工作目录是只读发布目录 `/opt/genarrative/releases/`，`genarrative` 用户无法在其中创建 `server-rs`。修复顺序： diff --git a/docs/【编辑器】画板UI设计图生成入口设计-2026-06-17.md b/docs/【编辑器】画板UI设计图生成入口设计-2026-06-17.md index 31a91bead..b5625276c 100644 --- a/docs/【编辑器】画板UI设计图生成入口设计-2026-06-17.md +++ b/docs/【编辑器】画板UI设计图生成入口设计-2026-06-17.md @@ -28,7 +28,7 @@ - 支持自定义画面比例和大小尺寸。 - 模型固定为 `gpt-image-2`，模型展示对齐角色规范面板底部固定模型样式，不响应点击、不弹出模型切换菜单；历史草稿如果残留其他模型，提交时也必须强制改为 `gpt-image-2`。 - 默认画面比例为 `16:9`，默认大小为 `1K`。 -- UI 素材提取面板不展示抠图背景色或抠图模型选择；前端用户路径固定提交 `screenColor=auto` 和 `segModel=birefnet`。后端先在 12 个候选色中自动决策具体 hex，最多重试 3 次，失败兜底 `#CFEFFF`；后端调用 BgFilter 时只把解析后的具体 hex 作为 `screen_color` 传入。后端仍识别内部保留的 `anime-seg`，但该选项不对用户可见。 +- UI 素材提取面板不展示抠图背景色或抠图模型选择；前端用户路径固定提交 `screenColor=auto` 和 `segModel=birefnet`。后端先在 12 个候选色中自动决策具体 hex，最多重试 3 次，失败兜底 `#CFEFFF`；父流程请求唯一 loopback `bgfilter-worker` 时只把解析后的具体 hex 作为 `screenColor` 参数传入。后端仍识别内部保留的 `anime-seg`，但该选项不对用户可见。 ## 提示词契约 @@ -61,7 +61,7 @@ 仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用后端自动决策出的抠图背景色。纯色背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便后续扣除背景；素材自身不要出现与背景色相同或相近的描边、底板、投影或反光。 ``` -- 后端收到 spritesheet 后先把带解析后纯色背景的源图 owned 上传私有 OSS（消费图片字节所有权，上传完成后释放原图缓冲，不克隆保留），写入项目资源和账号素材库；随后只持 object key。每次 BgFilter attempt 重新签发 600 秒 GET URL，multipart 固定传 `image_url`、`screen_color=`、`seg_model=`、`background_mode=flat` 和 `cross_check=off`，不包含 `file`，默认 `segModel=birefnet`。BgFilter 主路径不重新下载原图；首次失败后立即重试 `1` 次（重试同样重新换签），第二次仍失败进入“阿里云通用抠图（按签名 URL 单独下载）→ 本地键色（再按 object key 独立下载一次原图并在产出后释放）”降级链。透明背景处理正常成功时，透明 spritesheet 同样先进入 OSS、项目资源和账号素材库，再复用图标素材的连通域拆分能力；调用方未指定素材文件夹时落默认“项目”文件夹。透明背景处理最终失败、但 provider 原图已经持久化时，任务以 `completed + warning` 收口，只把 provider 原图作为唯一主图放入画布，`generatedLayerId` 指向原图，不创建透明图集，也不继续拆分。该收口只捕获透明背景处理本身的最终失败；phase 上报、provider 原图持久化、透明处理图持久化和 `canvasCompletion` 写回错误仍正常传播，不能被原图降级吞掉。 +- 父流程收到 spritesheet 后先把带解析后纯色背景的源图 owned 上传私有 OSS（消费图片字节所有权，上传完成后释放原图缓冲，不克隆保留），写入项目资源和账号素材库；随后只持 object key，并仅向同机唯一 loopback `bgfilter-worker` 发起一次内部 HTTP RPC，请求中的源图只以 object key 传递，并附带 BgFilter 参数、排队预算 `maxQueueWaitMs`、调用预算 `callBudgetMs` 和有界审计关联，父流程不签发 BgFilter URL、不直连 provider，也不重试已被 worker 接收的内部 RPC（连接从未建立时按调度方案 §5.1 有界重连）。子 worker 在 `Q` admission 和 `Semaphore(N)` 约束下执行这次逻辑调用；排队只消耗 `maxQueueWaitMs`，取得 provider permit 后才启动 `callBudgetMs`。每次 provider attempt 前重新签发 600 秒 GET URL，multipart 固定传 `image_url`、`screen_color=`、`seg_model=`、`background_mode=flat` 和 `cross_check=off`，不包含 `file`，并在调用预算内最多执行两次顺序 attempt，默认 `segModel=birefnet`。成功时，子 worker 通过内部 HTTP 二进制 body 把经过校验的图片字节直接返回父流程，不持久化中间结果；BgFilter 最终失败且父业务预算仍有效时，由父流程进入“阿里云通用抠图（按签名 URL 单独下载）→ 本地键色（再按 object key 独立下载一次原图并在产出后释放）”降级链。透明背景处理正常成功时，父流程把透明 spritesheet 写入 OSS、项目资源和账号素材库，再复用图标素材的连通域拆分能力；调用方未指定素材文件夹时落默认“项目”文件夹。BgFilter 与父侧 fallback 最终均失败、但 provider 原图已经持久化时，任务以 `completed + warning` 收口，只把 provider 原图作为唯一主图放入画布，`generatedLayerId` 指向原图，不创建透明图集，也不继续拆分。该收口只捕获透明背景处理本身的最终失败；phase 上报、provider 原图持久化、透明处理图持久化和 `canvasCompletion` 写回错误仍正常传播，不能被原图降级吞掉。最终透明结果及拆分切片的 OSS / 资源 / 画布持久化仍全部由父流程负责。 - UI 素材自动拆分只在透明图集成功后执行，与图标图集一致，属于 best-effort 附加动作。未知素材数量时按从上到下、从左到右自动命名为 `素材 1`、`素材 2`；识别或切片持久化失败仍返回整张透明图集和 `sliceWarning`，前端显示非阻断 warning toast，用户可手动重试。`sliceWarning` 与透明背景最终失败使用的通用 `warning` 互斥，前者只表示透明图集成功但自动拆分失败，`sliceWarning.reason` 原始契约保持不变。 - 正常透明化成功时，前端先把透明 spritesheet 作为 `assetKind: "icon-spritesheet"` 图集图层放在 UI 设计图右侧，再把拆分成功的独立素材作为 `assetKind: "icon"` 图标图层继续放到画布；透明背景处理最终失败时只消费后端快照中的 provider 原图。透明图集图层提供 `拆分图集` 工具栏按钮，可使用相同连通域规则重新拆分。 diff --git a/docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md b/docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md index 9e1fc8946..cf6fe7712 100644 --- a/docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md +++ b/docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md @@ -59,8 +59,8 @@ ## 去背与保存 -- 后端收到 spritesheet 后先把带解析后纯色背景的源图写入私有 OSS，并在上传完成后释放原图缓冲，再签发 600 秒 GET URL 调用 BgFilter 透明化；BgFilter multipart 固定传 `image_url`、`screen_color=`、`seg_model=`、`background_mode=flat` 和 `cross_check=off`，不包含 `file`。前端用户路径固定提交 `screenColor=auto` 与默认 `segModel=birefnet`，后端仍识别内部保留的 `anime-seg`，但这些内部参数不对用户可见。 -- 透明背景处理正常成功时，带背景原图和去背后的透明 spritesheet 都先写入 OSS、项目资源和账号素材库，再按 alpha 连通域和素材描述顺序执行附加拆分；若 BgFilter 返回较小图集，只把 alpha 蒙版重采样到 provider 原图尺寸并应用回原始高分辨率 RGB，不放大低分辨率后处理成品。画布完成快照同时写入透明主图与右侧 provider 原图（二者均已登记为 project resource / 账号素材），`generatedLayerId` 仍锚定透明主图；成功拆出的切片从 provider 原图右侧继续排列。调用方未指定素材文件夹时统一落默认“项目”文件夹。每个成功切片单独写入 OSS、项目资源和账号素材库，`sourceResourceId` 指向透明图集资源。透明背景处理最终失败、但 provider 原图已经持久化时，任务以 `completed + warning` 收口，只把 provider 原图作为唯一主图放入画布，`generatedLayerId` 指向原图，不创建透明图集，也不继续拆分，`iconImageSrcs=[]`。该收口只捕获透明背景处理本身的最终失败；phase 上报、provider 原图持久化、透明处理图持久化和 `canvasCompletion` 写回错误仍正常传播，不能被原图降级吞掉。 +- 父流程收到 spritesheet 后先把带解析后纯色背景的源图写入私有 OSS，并在上传完成后释放原图缓冲；随后只持 object key，并仅向同机唯一 loopback `bgfilter-worker` 发起一次内部 HTTP RPC，请求中的源图只以 object key 传递，并附带 BgFilter 参数、排队预算 `maxQueueWaitMs`、调用预算 `callBudgetMs` 和有界审计关联，父流程不签发 BgFilter URL、不直连 provider，也不重试已被 worker 接收的内部 RPC（连接从未建立时按调度方案 §5.1 有界重连）。子 worker 在 `Q` admission 和 `Semaphore(N)` 约束下执行这次逻辑调用；排队只消耗 `maxQueueWaitMs`，取得 provider permit 后才启动 `callBudgetMs`。每次 provider attempt 前重新签发 600 秒 GET URL，multipart 固定传 `image_url`、`screen_color=`、`seg_model=`、`background_mode=flat` 和 `cross_check=off`，不包含 `file`，并在调用预算内最多执行两次顺序 attempt。前端用户路径固定提交 `screenColor=auto` 与默认 `segModel=birefnet`，后端仍识别内部保留的 `anime-seg`，但这些内部参数不对用户可见。成功时，子 worker 通过内部 HTTP 二进制 body 把经过校验的图片字节直接返回父流程，不持久化中间结果；BgFilter 最终失败且父业务预算仍有效时，由父流程进入“阿里云通用抠图（按签名 URL 单独下载）→ 本地键色（再按 object key 独立下载一次原图并在产出后释放）”降级链。 +- 透明背景处理正常成功时，父流程把带背景原图和去背后的透明 spritesheet 写入 OSS、项目资源和账号素材库，再按 alpha 连通域和素材描述顺序执行附加拆分；若 BgFilter 返回较小图集，只把 alpha 蒙版重采样到 provider 原图尺寸并应用回原始高分辨率 RGB，不放大低分辨率后处理成品。画布完成快照同时写入透明主图与右侧 provider 原图（二者均已登记为 project resource / 账号素材），`generatedLayerId` 仍锚定透明主图；成功拆出的切片从 provider 原图右侧继续排列。调用方未指定素材文件夹时统一落默认“项目”文件夹。每个成功切片单独写入 OSS、项目资源和账号素材库，`sourceResourceId` 指向透明图集资源。BgFilter 与父侧 fallback 最终均失败、但 provider 原图已经持久化时，任务以 `completed + warning` 收口，只把 provider 原图作为唯一主图放入画布，`generatedLayerId` 指向原图，不创建透明图集，也不继续拆分，`iconImageSrcs=[]`。该收口只捕获透明背景处理本身的最终失败；phase 上报、provider 原图持久化、透明处理图持久化和 `canvasCompletion` 写回错误仍正常传播，不能被原图降级吞掉。最终透明结果及切片的 OSS / 资源 / 画布持久化仍全部由父流程负责。 - 自动拆分只在透明图集成功后执行，属于 best-effort 附加动作，不参与图集生成的成功判定。连通域识别或切片持久化失败时，接口仍返回并回填整张透明图集，`iconImageSrcs=[]`，并通过 `sliceWarning.code/reason` 暴露非阻断原因；`sliceWarning` 与透明背景最终失败使用的通用 `warning` 互斥，前者只表示透明图集成功但自动拆分失败，`sliceWarning.reason` 原始契约保持不变。前端在 inline、worker 队列完成和刷新恢复三条路径统一显示对应 warning toast，用户可在图集工具栏手动重试。 - 响应通过 `iconImageSrcs` 返回成功切片素材；自动生成使用用户输入的素材描述命名，UI 设计提取和手动拆分按从上到下、从左到右自动命名为 `素材 N`。 - 手动拆分调用 `POST /api/editor/icon-spritesheets/slices`，只允许读取当前用户项目中的 `icon-spritesheet` 资源，不调用图片生成 provider，不扣除泥点。输入限制为单边最多 `4096` 像素、总像素最多 `2048×2048`，单次最多持久化 `64` 个切片；超限在任何切片写入前拒绝。 diff --git a/docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md b/docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md index edd32af5b..f53c3d617 100644 --- a/docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md +++ b/docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md @@ -54,7 +54,7 @@ - 请求同时提交 `model`、`screenColor`、`segModel`、`aspectRatio` 和 `imageSize`： - `model` 支持 `gemini-3.1-flash-image-preview`（UI 显示 `nanobanana2`）和 `gpt-image-2`，默认 `nanobanana2`。 - 用户在角色或图标素材面板中切换过模型后，下一次打开这两类面板继续使用上次模型。 - - 前端用户路径固定提交 `screenColor=auto` 和 `segModel=birefnet`，不从生成器快照或输入快照恢复旧手动背景色 / 抠图模型。后端在组装 prompt 前把 `auto` 自动决策为具体 hex，最多重试 3 次，失败后兜底 `#CFEFFF`；调用 BgFilter 时只把解析后的具体 hex 作为 `screen_color` 传入。后端仍识别内部保留的 `anime-seg`，但该选项不对用户可见。 + - 前端用户路径固定提交 `screenColor=auto` 和 `segModel=birefnet`，不从生成器快照或输入快照恢复旧手动背景色 / 抠图模型。后端在组装 prompt 前把 `auto` 自动决策为具体 hex，最多重试 3 次，失败后兜底 `#CFEFFF`；父流程请求唯一 loopback `bgfilter-worker` 时只把解析后的具体 hex 作为 `screenColor` 参数传入。后端仍识别内部保留的 `anime-seg`，但该选项不对用户可见。 - 比例按 `x:y` 展示；大小按 `0.5K / 1K / 2K` 展示。 - 尺寸选项来源以 VectorEngine 接入文档为准： - `nanobanana2`：比例 `1:1 / 4:3 / 3:2 / 2:3 / 9:16 / 16:9`；大小 `0.5K / 1K / 2K`。后端走 `/v1beta/models/{model}:generateContent`，把比例写入 `generationConfig.imageConfig.aspectRatio`，把大小写入 `generationConfig.imageConfig.imageSize`；其中 `0.5K` 按文档传 `"512"`。 @@ -67,7 +67,7 @@ 角色设定：<用户输入的角色设定> ``` -- 角色图生成完成后，编辑器后端必须先把带自动决策纯色背景的源图 owned 上传私有 OSS（消费图片字节所有权，上传完成后释放原图缓冲），再对 object key 签发 600 秒 GET URL 调用共享 BgFilter 服务透明化。BgFilter 主路径不重新下载原图；每次 HTTP attempt 重新换签，multipart 字段包含 `image_url`、`screen_color=`、`seg_model=`、`background_mode=flat` 和 `cross_check=on`，不包含 `file`，用户路径默认并只提交 `seg_model=birefnet`；`flat` 明确表示单一纯色背景抠图模式，`birefnet` 是 BgFilter 管线内部后端。首次请求失败后立即重试 `1` 次，第二次仍失败进入“阿里云通用抠图（按签名 URL 单独下载）→ 本地键色（再按 object key 独立下载一次原图并在产出后释放）”降级链。角色图 prompt 按 `screenColor` 写入颜色名称、hex 和 RGB。该流程不再调用 RPG / 资产工坊的角色主图专用 `character_visual_assets` 后处理，也不复用手动去背景的 `background_mode=complex` 路径。透明背景处理正常成功时，输出透明背景 PNG，随后写入 OSS 私有对象并确认 `asset_object`；接口回包返回 `imageSrc: "/"`、`objectKey`、`assetObjectId` 及资源快照，画布同时写入透明主结果和 provider 原图，生成器 `generatedLayerId` 锚定透明主结果，provider 原图作为第二个图层放在其右侧。三段透明背景处理最终仍失败、但 provider 原图已经持久化时，任务以 `completed + warning` 收口，只把 provider 原图作为唯一主图放入画布，`generatedLayerId` 指向原图，不创建不存在的透明处理图；通用 `warning.code/reason` 携带完整降级原因。该收口只捕获透明背景处理本身的最终失败；phase 上报、provider 原图持久化、透明处理图持久化和 `canvasCompletion` 写回错误仍正常传播，不能被原图降级吞掉。前端创建图层和画板资源记录时必须保存最终回包对应的媒体引用。 +- 角色图生成完成后，编辑器父流程必须先把带自动决策纯色背景的源图 owned 上传私有 OSS（消费图片字节所有权，上传完成后释放原图缓冲），随后只持 object key，并仅向同机唯一 loopback `bgfilter-worker` 发起一次内部 HTTP RPC；请求中的源图只以 object key 传递，并附带 BgFilter 参数、排队预算 `maxQueueWaitMs`、调用预算 `callBudgetMs` 和有界审计关联，父流程不签发 BgFilter URL、不直连 provider，也不重试已被 worker 接收的内部 RPC（连接从未建立时按调度方案 §5.1 有界重连）。子 worker 在默认 `Q=2048` admission 保险丝和 `Semaphore(N=16)` 约束下执行这次逻辑调用，每次 provider attempt 前重新签发 600 秒 GET URL，multipart 字段包含 `image_url`、`screen_color=`、`seg_model=`、`background_mode=flat` 和 `cross_check=on`，不包含 `file`。排队只消耗 `maxQueueWaitMs`；取得 provider permit 后才启动 `callBudgetMs`，attempt 按 `N × est × 2`、调用预算按 `2 × attempt + 1s` 派生，冻结 `est=5000ms` 时分别为 `160s / 321s`，同一次逻辑调用最多执行两次顺序 attempt。用户路径默认并只提交 `seg_model=birefnet`，`flat` 明确表示单一纯色背景抠图模式，`birefnet` 是 BgFilter 管线内部后端。成功时，子 worker 通过内部 HTTP 二进制 body 把经过校验的图片字节直接返回父流程，不持久化中间结果；BgFilter 最终失败且父业务预算仍有效时，由父流程进入“阿里云通用抠图（按签名 URL 单独下载）→ 本地键色（再按 object key 独立下载一次原图并在产出后释放）”降级链。角色图 prompt 按 `screenColor` 写入颜色名称、hex 和 RGB。该流程不再调用 RPG / 资产工坊的角色主图专用 `character_visual_assets` 后处理，也不复用手动去背景的 `background_mode=complex` 路径。透明背景处理正常成功时，父流程输出透明背景 PNG，随后写入 OSS 私有对象并确认 `asset_object`；接口回包返回 `imageSrc: "/"`、`objectKey`、`assetObjectId` 及资源快照，画布同时写入透明主结果和 provider 原图，生成器 `generatedLayerId` 锚定透明主结果，provider 原图作为第二个图层放在其右侧。BgFilter、阿里云与本地键色最终均失败、但 provider 原图已经持久化时，任务以 `completed + warning` 收口，只把 provider 原图作为唯一主图放入画布，`generatedLayerId` 指向原图，不创建不存在的透明处理图；通用 `warning.code/reason` 携带完整降级原因。该收口只捕获透明背景处理本身的最终失败；phase 上报、provider 原图持久化、透明处理图持久化和 `canvasCompletion` 写回错误仍正常传播，不能被原图降级吞掉。最终透明结果的 OSS / 资源 / 画布持久化仍全部由父流程负责；前端创建图层和画板资源记录时必须保存最终回包对应的媒体引用。 - 对 `assetKind: "character"` 的角色图层执行 `重绘` 时，前端仍使用原图作为参考图，但请求 `kind` 必须传 `character`，让后端继续套用上述角色提示词限定、角色图后处理和角色资产持久化；透明背景正常成功与最终失败保留 provider 原图的收口规则和角色新生成一致。普通图片图层重绘仍保持 `kind: "quick-edit"`。 ## 生成规范参考图 @@ -116,7 +116,7 @@ - 角色生成提交统一走 `/api/editor/images/generations`，按 `角色规范 -> 常规参考图` 顺序传 `referenceImageSrcs`，并写入 `assetKind: "character"`。 - 角色图层重绘同样走 `/api/editor/images/generations` 的 `kind: "character"` 分支，原图作为参考图提交，生成结果继续保留 `assetKind: "character"`。 - 角色和图标素材生成已接入 `nanobanana2` / `gpt-image-2` 模型切换、上次模型记忆，以及按模型归一的比例 / 大小尺寸；`nanobanana2` 使用原生 `generateContent` 的 `imageConfig.aspectRatio/imageSize`，`gpt-image-2` 使用文档列出的 `size` 字符串。 -- 角色生成后端已按固定 prompt 骨架补入 `角色设定` 和自动决策纯色抠图背景，并在生成成功后先保存纯色背景源图，再通过 BgFilter 按用户路径默认 `segModel=birefnet` 执行透明化；透明化成功时把处理图写入 `generated-character-drafts/editor/character-images//image.png` 路径下的 OSS 私有对象，并把透明主结果与其右侧 provider 原图一起写入画布，`generatedLayerId` 仍锚定透明主结果；最终失败时则只保留并返回已经持久化的 provider 原图和通用 warning。若 BgFilter 返回较小图片，只允许把其 alpha 蒙版重采样到 provider 原图尺寸并应用回原始高分辨率 RGB，不得放大低分辨率透明成品。最终回包的 `objectKey` / `assetObjectId` 会随画板资源记录保存。 +- 角色生成后端已按固定 prompt 骨架补入 `角色设定` 和自动决策纯色抠图背景，并在生成成功后先保存纯色背景源图，再由父流程通过唯一 loopback `bgfilter-worker` 的 flat 内部 HTTP 调用执行透明化；子 worker 返回成功二进制后，父流程把处理图写入 `generated-character-drafts/editor/character-images//image.png` 路径下的 OSS 私有对象，并把透明主结果与其右侧 provider 原图一起写入画布，`generatedLayerId` 仍锚定透明主结果；BgFilter 与父侧 fallback 最终均失败时则只保留并返回已经持久化的 provider 原图和通用 warning。若 BgFilter 返回较小图片，只允许把其 alpha 蒙版重采样到 provider 原图尺寸并应用回原始高分辨率 RGB，不得放大低分辨率透明成品。最终回包的 `objectKey` / `assetObjectId` 会随画板资源记录保存。 - `Esc` 只退出角色规范画布点选状态，不关闭角色生成面板。 - 已补充回归测试覆盖角色形象生成、点选退出、角色动画入口隔离和快速编辑入口。 - 本次验证命令： @@ -166,9 +166,9 @@ - 抽帧采样必须按目标帧数预留视频尾部安全步长，例如 `32帧·4秒` 最后一帧采 `3.875s`，避免 FFmpeg 在尾点附近返回成功但输出 `0` 帧。 - 图片画布角色动作的 FFmpeg 原始帧在上传 OSS 前必须转为 RGB8，并按最终帧宽高的 contain 比例使用 `Triangle` 只缩放到内容尺寸；不得提前创建最终目标尺寸 RGBA 画布，不得引入 Alpha 通道或透明 padding。以 `560×752` 原始帧、`323×480` 最终目标为例，上传给抠图链路的源帧必须是 `323×434 RGB8 PNG`，没有上下补边。抽帧解码后若携带 Alpha 通道，必须先把像素按白底合成为不透明再转 RGB8，禁止直接丢弃 Alpha——全透明像素下未定义的 RGB 值会以杂色进入抠图输入，重新引入杂色边缘；共享 FFmpeg 抽帧命令保持不固定 `-pix_fmt`，白底合成只属于该链路的 BgFilter 输入准备阶段。 - 后端先计算整批精确采样时刻，再用单个 FFmpeg filter graph 统一解码预览视频并输出 `32 / 40 / 48` 张源帧；不得为每帧重新启动 FFmpeg、重复解码同一视频，也不得用会改变现有尾帧安全时刻的粗粒度 `fps` 抽帧替代。批量命令成功后必须逐一确认全部目标帧文件存在，缺少任一帧都按整批失败处理并保留缺帧编号、目标时刻和输出路径诊断。 -- 每帧绿幕源图字节由上传 owned 消费（`frame.bytes` 移入 put，上传完成后释放原帧缓冲，不克隆保留）；后续只持 object key。每次 BgFilter attempt 重新签发 600 秒 GET URL，multipart 仅传 `image_url`（加 `background_mode=flat`、`seg_model=birefnet`、`cross_check=on` 与同一次生成已选定的 `screenColor`），不传 `file`。BgFilter 主路径不重新下载原帧；失败后走 `阿里云通用抠图（按签名 URL 单独下载）→ 本地 editor_green_screen（再按 object key 独立下载一次并在产出后释放）`。BgFilter 每一次 HTTP attempt 的 timeout 使用“`GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS` 基准值 + `2000ms × 本次实际帧数`”，默认 `32 / 40 / 48` 帧分别为 `244000 / 260000 / 276000ms`；首次失败后重试 `1` 次。 -- BgFilter、阿里云或本地键色返回透明结果后，后端继续通过现有最终帧 finalizer 转为 RGBA8，按宽高比居中放入最终目标尺寸，并使用 `RGBA(0,0,0,0)` 补边。上述样例最终输出必须为 `323×480 RGBA8 PNG`，顶部和底部各 `23px` 透明 padding，内容区域完整保留抠图结果。 -- 全部 `32 / 40 / 48` 帧以覆盖本次所有帧的无序在途集合连续发射，允许乱序完成并最终按 `frameIndex` 排序；任一帧最终失败时先排空全部已启动 Future，再让整项任务失败退款，不发布缺帧动画。 +- 每帧绿幕源图字节由上传 owned 消费（`frame.bytes` 移入 put，上传完成后释放原帧缓冲，不克隆保留）；后续父流程只持 object key，并为每帧向唯一 loopback `bgfilter-worker` 发起一次内部 HTTP RPC，不直接签发 BgFilter URL、不直连 provider，也不重试已被 worker 接收的内部 RPC（连接从未建立时按调度方案 §5.1 有界重连）。每帧请求分别携带按父剩余绝对预算派生的 `maxQueueWaitMs` 和公式化 `callBudgetMs`；子 worker 在默认 `Q=2048` admission 保险丝和 `Semaphore(N=16)` 约束下排队，取得 provider permit 后才启动调用预算，每次 provider attempt 前重新签发 600 秒 GET URL，multipart 仅传 `image_url`（加 `background_mode=flat`、`seg_model=birefnet`、`cross_check=on` 与同一次生成已选定的 `screenColor`），不传 `file`。真实 provider attempt 按 `N × est × 2` 派生，调用预算按 `2 × attempt + 1s` 派生；冻结 `est=5000ms` 时分别为 `160s / 321s`，排队不侵蚀最多两次顺序 attempt 的完整窗口，`32 / 40 / 48` 帧也不再增加单帧 attempt。成功图片由子 worker 以内部 HTTP 二进制 body 返回父流程，不在子侧落 OSS；BgFilter 最终失败且父业务预算仍有效时，由父流程进入 `阿里云通用抠图（按签名 URL 单独下载）→ 本地 editor_green_screen（再按 object key 独立下载一次并在产出后释放）`。 +- BgFilter、阿里云或本地键色返回透明结果后，父流程继续通过现有最终帧 finalizer 转为 RGBA8，按宽高比居中放入最终目标尺寸，并使用 `RGBA(0,0,0,0)` 补边；最终帧 OSS 与业务写回仍由父流程完成。上述样例最终输出必须为 `323×480 RGBA8 PNG`，顶部和底部各 `23px` 透明 padding，内容区域完整保留抠图结果。 +- 全部 `32 / 40 / 48` 帧以覆盖本次所有帧的无序在途集合向内部 worker 提交，允许乱序完成并最终按 `frameIndex` 排序；BgFilter provider 的实际在途请求受唯一 worker 的 `N / Q` 限制。任一帧最终失败时先排空全部已启动 Future，再让整项任务失败退款，不发布缺帧动画。 - 抽帧结果写入 OSS，并返回帧路径、帧尺寸、帧数、fps、预览视频路径、模型、价格和实际 prompt。 - 画板前端回填角色动作结果时，必须以 `frames[0].imageSrc` 创建 `mediaType: "image-sequence"`、`assetKind: "character-animation"` 图层，并把完整 `frames` 保存为图层 `imageSequenceFrames`；`previewVideoPath` 只保留为上游预览视频来源，不作为画布主媒体。 - 角色动作图层在画布中使用序列帧播放器循环展示透明 PNG 帧；刷新恢复时必须继续读取 `imageSequenceFrames`，不能回退到 `