统一BgFilter与外部生成文档口径
收敛手动去背景到BgFilter complex并补齐单次重试边界 明确外部生成summary读取事实源、phase字段与正式procedure 补充nohup.out刷新循环的运维说明和共享踩坑记录 整理SpacetimeDB mapper导出列表格式
This commit is contained in:
@@ -1602,6 +1602,14 @@
|
||||
- 验证：`npm run dev -- --watch` 下修改 `apps/admin-web/src/**` 应由 Vite HMR 处理，不应出现连续 `[dev] 重启 admin-web`；`scripts/dev.test.ts` 覆盖 web/admin-web 不注册外层 watch。
|
||||
- 关联：`scripts/dev.mjs`、`docs/technical/RUST_LOCAL_AND_REMOTE_DEPLOYMENT_SCRIPTS_2026-04-22.md`。
|
||||
|
||||
## 根目录 `nohup.out` 持续写入会触发主站 Vite 刷新循环
|
||||
|
||||
- 现象：在仓库根目录用 `nohup npm run dev ... &` 启动完整 dev 栈后，即使没有修改前端源码，主站页面也会反复整页刷新；`nohup.out` 同时持续增长。
|
||||
- 原因：未显式重定向 stdout / stderr 时，`nohup.out` 会收集 SpacetimeDB、api-server 和两套 Vite 的整套 dev 栈输出。主站 Vite 的 root 是仓库根目录，若 watcher 未忽略这个持续写入的文件，每次追加日志都会被当成文件变化；后台 Vite root 是 `apps/admin-web`，仓库根日志不在其监听根内。
|
||||
- 处理：主站 `vite.config.ts` 的 `server.watch.ignored` 保持忽略 `**/nohup.out`，Git 同时忽略 `nohup.out`。修改配置后重启主站 Vite。若显式重定向到其它仓库内日志文件，该文件不会自动受保护，应写到 Vite root 之外或补充精确忽略规则。
|
||||
- 验证：在仓库根目录追加 `nohup.out` 时主站不再刷新，真实源码修改仍正常触发 HMR；`git check-ignore nohup.out` 能命中忽略规则，`git status` 不出现该日志。
|
||||
- 关联：`vite.config.ts`、`.gitignore`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
|
||||
|
||||
## 本地 SpacetimeDB publish 401 可清本地库重发
|
||||
|
||||
- 现象：本地 `spacetime publish` 显示 `401` 无权限，或重新发布仍像是在更新旧库。
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -1,6 +1,6 @@
|
||||
# 外部生成 Worker 化方案
|
||||
|
||||
更新时间：`2026-06-24`
|
||||
更新时间：`2026-07-15`
|
||||
|
||||
## 背景
|
||||
|
||||
@@ -13,7 +13,7 @@
|
||||
- 多个 worker 进程通过 SpacetimeDB 任务表抢占任务，依赖 lease 超时恢复，支持按进程数和单进程并发动态缩扩容。
|
||||
- 本地或小流量同步排查可显式启用 `inline` 模式，由 HTTP handler 复用同一 worker executor 同步执行并返回 `completed`；该模式不创建队列任务，也不具备 worker 横向扩容能力。
|
||||
- SpacetimeDB reducer / procedure 只做任务状态流转，不做网络、文件系统或外部 provider I/O。
|
||||
- 已接入拼图 `compile_puzzle_draft`、结果页 `generate_puzzle_images` 与结果页 `generate_puzzle_ui_background`，跳一跳、拼消消和敲木鱼的外部图片生成动作，以及图片画布编辑器的图片、改图、图标 spritesheet、UI 素材提取、角色动作、视频、音效和背景音乐生成。后续玩法和编辑器生成入口继续复用同一队列 Module，不再为每个入口发明独立队列。
|
||||
- 已接入拼图 `compile_puzzle_draft`、结果页 `generate_puzzle_images` 与结果页 `generate_puzzle_ui_background`，跳一跳、拼消消和敲木鱼的外部图片生成动作，以及图片画布编辑器的图片、改图、手动去背景、图标 spritesheet、UI 素材提取、角色动作、视频、音效和背景音乐生成。后续玩法和编辑器生成入口继续复用同一队列 Module，不再为每个入口发明独立队列。
|
||||
- 第一版外部生成队列粒度固定为“单个用户动作对应单个 job”。例如草稿编译、结果页单槽重生、图集重生都各自入一个 job；job 内部可以串行或并行调用 provider、OSS、SpacetimeDB 写回，但不再拆成“提示词 / 生图 / 切图 / 去背景 / 持久化 / 回写”等阶段 job。用户可见执行阶段通过现有任务行及摘要投影的轻量 `phase` 保存，不作为队列调度单位，也不写回大 payload。
|
||||
- 不调用外部图片 / 音频 / LLM provider 的动作继续 inline 执行，不为了统一排队而进入 `external_generation_job`。
|
||||
|
||||
@@ -27,10 +27,12 @@
|
||||
- `update_external_generation_job_phase_and_return`：worker 按 `job_id + worker_id + lease_token` 把当前执行阶段更新为 `generating` 或 `processing`，并同步现有摘要投影；不新增阶段任务或阶段表。
|
||||
- `complete_external_generation_job_and_return`：worker 成功后按 `worker_id + lease_token` 写入 `result_payload_json`，任务进入 `completed`。
|
||||
- `fail_external_generation_job_and_return`：worker 失败后按 `worker_id + lease_token` 回写错误，并按 `max_attempts` 决定回到 `pending` 重试或进入 `failed`。
|
||||
- `list_external_generation_jobs_and_return`：按当前账号读取正式生成任务列表，返回 pending / running / 未确认终态数量、任务价格和完成提示确认状态。
|
||||
- `acknowledge_external_generation_jobs_and_return`：按当前账号确认已终态任务的完成 / 失败提示，写入 `notification_acknowledged_at` 并追加审计事件。
|
||||
- `list_external_generation_job_summaries_and_return`：按当前账号从轻量摘要投影读取正式生成任务列表，返回 pending / running / 未确认终态数量、任务价格、执行阶段和完成提示确认状态。
|
||||
- `acknowledge_external_generation_job_summaries_and_return`：按当前账号确认已终态任务的完成 / 失败提示，写入摘要投影的 `notification_acknowledged_at` 并追加审计事件。
|
||||
- `get_external_generation_queue_stats_and_return`：controller 读取队列积压、运行中任务和过期 lease 数量，用于计算 worker 目标实例数；该 procedure 只读 `external_generation_job`，不直接操作 systemd。
|
||||
- `get_external_generation_job_and_return`：按 `job_id` 读取单个任务状态，给 BFF 和生成页展示使用；必须只返回调用者有权读取的任务，不能暴露其它用户的 payload、错误详情或 worker 内部字段。
|
||||
- `get_external_generation_job_summary_and_return`：按 `job_id` 从轻量摘要投影读取单个任务状态，给 BFF 和生成页展示使用；必须只返回调用者有权读取的任务，不能暴露其它用户的 payload、错误详情或 worker 内部字段。
|
||||
|
||||
不带 `summary / summaries` 的旧 `get / list / acknowledge_external_generation_job*` procedure 只保留给受控内部兼容，不是 BFF 正式读取入口。
|
||||
|
||||
这个 Module 的 **Seam** 在 SpacetimeDB procedure + `spacetime-client` facade；`api-server` HTTP role 和 worker role 都只依赖这个 Interface。外部 provider、OSS、计费补偿、玩法草稿回写仍留在 `api-server` worker implementation 内，不进入 SpacetimeDB reducer。
|
||||
|
||||
@@ -40,11 +42,11 @@
|
||||
|
||||
- `GET /api/runtime/external-generation/queue-overview`：当前账号队列概览，用于兼容旧展示和轻量状态读取。返回 pending、running、未确认终态数量和更新时间。
|
||||
- `GET /api/runtime/external-generation/jobs?limit=20&includeAcknowledgedTerminal=false`：当前账号正式生成任务列表，用于 `我的` 页签任务列表和完成 / 失败提示。返回每个任务的 job id、kind、source、可展示 label、状态、进度、错误、`priceMudPoints`、`refundLedgerId`、`notificationAcknowledgedAt` 和时间戳。默认不返回已确认的终态任务；需要拆分活跃和完成列表时可追加 `statuses=running,queued` 或 `statuses=completed,failed`，BFF 仍只返回当前账号任务。
|
||||
- 任务被 claim 后默认处于 `generating`，BFF 显示“正在生成”；真实进入 BgFilter、逐帧抠图或独立去背景时切换为 `processing`，BFF 显示“正在处理”。旧任务 `phase=None` 按 `generating` 兼容，前端不得按耗时或 job kind 推断阶段。
|
||||
- 任务被 claim 后默认处于 `generating`，BFF 显示“正在生成”；真实进入 BgFilter、逐帧抠图或手动去背景时切换为 `processing`，BFF 显示“正在处理”。旧任务 `phase=None` 按 `generating` 兼容，前端不得按耗时或 job kind 推断阶段。
|
||||
- `POST /api/runtime/external-generation/jobs/acknowledge`：生成完成 / 失败提示展示后由前端后台调用，BFF 只传当前账号 job ids，后端只确认属于当前账号且已终态的任务。
|
||||
- `GET /api/runtime/external-generation/jobs/{jobId}`：单 job 状态，用于生成页轮询某次动作。返回 `jobId`、`jobKind`、`sourceModule`、`sourceEntityId`、`status`、`attempt`、`maxAttempts`、`createdAt`、`startedAt`、`completedAt`、`updatedAt`、可展示的 `requestLabel`、可展示的 `lastErrorMessage`、以及业务侧下一次轮询所需的 source 标识。
|
||||
|
||||
BFF 只做鉴权、授权裁剪、字段脱敏和契约映射；队列事实仍以 `external_generation_job` 为准，业务结果仍以玩法 session / work profile 为准。生成页 / 进度页只展示当前玩法业务进度；用户可见任务列表放在 `我的` 页签，必要时再用单 job 状态补充排障信息，并继续按原玩法 session/detail 接口收敛到 ready 或 failed。队列接口不替代玩法恢复接口，也不把 private `request_payload_json` 原样传给前端。终态提示的弹出与否以后端 `notification_acknowledged_at` 为准；前端在提示展示后后台调用 acknowledge 接口，关闭按钮只负责收起本地弹窗，不能只靠本地 dismiss 永久吞掉任务。
|
||||
BFF 只做鉴权、授权裁剪、字段脱敏和契约映射；worker 调度、lease、执行和计费事实仍以 `external_generation_job` 为准，用户可见任务列表、单任务状态、执行阶段和通知确认的正式读取事实源为 `external_generation_job_summary`，业务结果仍以玩法 session / work profile 为准。生成页 / 进度页只展示当前玩法业务进度；用户可见任务列表放在 `我的` 页签，必要时再用单 job 状态补充排障信息，并继续按原玩法 session/detail 接口收敛到 ready 或 failed。队列接口不替代玩法恢复接口，也不把 private `request_payload_json` 原样传给前端。终态提示的弹出与否以后端 `notification_acknowledged_at` 为准；前端在提示展示后后台调用 acknowledge 接口，关闭按钮只负责收起本地弹窗，不能只靠本地 dismiss 永久吞掉任务。
|
||||
|
||||
## 任务表
|
||||
|
||||
@@ -54,7 +56,7 @@ BFF 只做鉴权、授权裁剪、字段脱敏和契约映射；队列事实仍
|
||||
| --- | --- |
|
||||
| `job_id` | 主键，`extgen-` 前缀 UUID |
|
||||
| `dedupe_key` | 唯一键，建议为 `play/action/session/scope` |
|
||||
| `job_kind` | 执行类型，当前覆盖 `puzzle_compile_draft`、`puzzle_generate_images`、`puzzle_generate_ui_background`、跳一跳 / 拼消消 / 敲木鱼生成动作，以及 `editor_image_generation`、`editor_image_edit`、`editor_icon_spritesheet_generation`、`editor_ui_design_asset_extraction`、`editor_character_animation_generation`、`editor_video_generation`、`editor_sound_effect_generation`、`editor_background_music_generation` |
|
||||
| `job_kind` | 执行类型，当前覆盖 `puzzle_compile_draft`、`puzzle_generate_images`、`puzzle_generate_ui_background`、跳一跳 / 拼消消 / 敲木鱼生成动作，以及 `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` |
|
||||
| `owner_user_id` | 触发用户 |
|
||||
| `source_module` | 玩法或能力名，例如 `puzzle` |
|
||||
| `source_entity_id` | session/profile/work 等作用域 |
|
||||
@@ -72,6 +74,9 @@ BFF 只做鉴权、授权裁剪、字段脱敏和契约映射；队列事实仍
|
||||
| `price_mud_points` | 后端计算的本任务价格，用于任务列表展示和排障 |
|
||||
| `refund_ledger_id` | 失败退款产生的钱包退款流水 ID，便于从任务追到退款记录 |
|
||||
| `notification_acknowledged_at` | 用户已确认完成 / 失败提示的时间，未确认终态任务下次登录继续集中弹出 |
|
||||
| `phase` | 尾部可选字段；`null / generating / processing`，claim 时写 `generating`，进入正式后处理时写 `processing` |
|
||||
|
||||
用户正式读取使用私有轻量投影 `external_generation_job_summary`。该表同步保存 owner、来源、状态、`phase`、价格、有限错误/告警摘要、通知确认和时间字段，不复制 request/result payload、worker lease 或 dedupe 内部字段；enqueue、claim、renew、phase update、complete、fail 与 acknowledge 都必须维护对应投影语义。
|
||||
|
||||
新增私有审计表 `external_generation_job_event`，记录 `enqueued/claimed/lease_renewed/completed/failed/acknowledged` 等事件。事件表只追加状态转换事实，不作为当前状态源；排障时先看 `external_generation_job` 当前状态，再按 `job_id` 追 `external_generation_job_event` 时间线。
|
||||
|
||||
@@ -180,6 +185,7 @@ controller 配置：
|
||||
|
||||
- `editor_image_generation`：普通图片、生成规范、角色形象、UI 设计图、宣发素材和图片快速编辑。
|
||||
- `editor_image_edit`：图片编辑 / 修改结果。
|
||||
- `editor_background_removal`：手动去除任意图片背景，worker 使用 BgFilter complex 模式、首次失败后重试 `1` 次，并把执行阶段标记为 `processing`。
|
||||
- `editor_icon_spritesheet_generation`：图标素材 spritesheet 生成和拆分。
|
||||
- `editor_ui_design_asset_extraction`：UI 设计图红框素材提取。
|
||||
- `editor_character_animation_generation`：角色动作视频和帧素材生成。
|
||||
|
||||
@@ -240,9 +240,8 @@ npm run check:server-rs-ddd
|
||||
|
||||
- LLM：通用 LLM 门面继续使用 `GENARRATIVE_LLM_*`；创意 Agent `gpt-5.4-mini` Chat Completions 文本链路已于 2026-06 从 APIMart 迁移到 VectorEngine，使用 `VECTOR_ENGINE_BASE_URL` / `VECTOR_ENGINE_API_KEY` 构造 OpenAI-compatible client，`api-server` 会把未带 `/v1` 的 VectorEngine base URL 规范化到 `/v1` 后请求 `/chat/completions`。通用 `/api/llm/chat/completions` 代理使用 `GENARRATIVE_LLM_PROVIDER=openai-compatible`、`GENARRATIVE_LLM_BASE_URL=https://api.vectorengine.cn/v1`、`GENARRATIVE_LLM_MODEL=gpt-5.4-mini`；未单独配置 `GENARRATIVE_LLM_API_KEY` 时可复用 `VECTOR_ENGINE_API_KEY`。`APIMART_BASE_URL` / `APIMART_API_KEY` 只作为历史残留，不再作为创意 Agent gpt-5.4-mini 客户端来源；后续排障时优先确认 VectorEngine `/v1/models`、`/v1/chat/completions` 和 `/v1/responses` 可用性。
|
||||
- 图片生成：VectorEngine `gpt-image-2` 图片 provider 归属 `platform-image`，密钥只在后端环境变量中；`api-server` 内的 `openai_image_generation.rs` 只是兼容调用面和外部失败审计桥接，不再承载 provider 协议实现。实际外部生成运行记录统一落 `tracking_event`，`event_key = external_generation_run`，metadata 记录开始 / 结束时间、耗时、状态、成功标记、失败原因、provider task id 和结果摘要，不再写回过时的 `ai_task`。DashScope 只按仍在使用的历史能力单独处理，不作为 GPT-image-2 兜底。VectorEngine `/v1/images/generations` 和 `/v1/images/edits` 上游 POST 使用 `libcurl` 发送；`reqwest` 只保留给参考图 URL 下载和响应中图片 URL 下载。`/v1/images/edits` 的 multipart 参考图必须作为 libcurl 文件上传 part 发送，字段名为 `image`，实现上使用 `Form::buffer(file_name, bytes)` 并设置 `Content-Type`；不能只用 `contents(...).filename(...)`，否则上游会把请求转码为缺少图片并返回 `image is required`。`request_send` 阶段的 curl timeout / connect error 按可重试传输错误处理，最多尝试 5 次，并使用指数退避加短抖动；排障时优先看 `attempt`、`max_attempts`、`retry_delay_ms`、`reference_image_bytes_total` 和 `request_params`，不要把 `SendRequest` 当成上游业务错误。
|
||||
- 编辑器抠图服务：手动 `POST /api/editor/images/background-removals` 继续代理独立 BiRefNet 服务，配置为 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_BASE_URL`、`GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN` 和 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_REQUEST_TIMEOUT_MS`。角色形象生成、图标 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 推理，单次抠图较慢，必须留足超时），token 未配置时复用 BiRefNet token。BgFilter 请求必须显式传 `screen_color=<screenColor>`、`seg_model=<segModel>` 和 `cross_check=<on|off>`；角色形象生成和角色动作逐帧去背固定传 `cross_check=on`，图标 spritesheet 生成和 UI 设计图素材提取固定传 `cross_check=off`，不依赖服务端默认值。前端用户路径不展示抠图模型选择并固定提交默认 `birefnet`，后端仍识别内部保留的 `anime-seg`，其中 `birefnet` 只表示 BgFilter 管线内部后端，不等同于手动去背景的独立 BiRefNet 服务；`cross_check` 同样只属于后端内部供应商策略，不进入前端或外部 OpenAPI。BgFilter 调用失败，或连续失败达到 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD`（默认 `3`）并在 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS`（默认 `300`）内打开熔断时，四条路线均跳过或结束 BgFilter 调用后复用同一兜底链：先调用阿里云通用抠图，阿里云失败才使用本地 `editor_green_screen` 键色扣除；熔断期不得直接退化到本地兜底。角色动作视频生成的背景色已与生图链路统一：`screenColor=auto` 时由视觉 LLM（`gpt-5-mini`，Responses 协议、low 推理档）读源角色图自动决策，并经硬过滤器剔除与前景 / 皮肤撞色的候选，手动 hex 则尊重用户选择；透明源角色图在提交 Ark 图生视频前先合成到选定背景色实色，使视频背景等于抠图键色；抽帧后逐帧固定使用 `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 与阿里云抠图失败都写入 `external_api_call_failure` 审计。
|
||||
- 2026-07-14 更新：上句关于“手动去背景继续代理独立 BiRefNet”的口径已废止。手动 `POST /api/editor/images/background-removals` 现与标准纯色背景链路共用 BgFilter 配置和 HTTP client，固定传 `background_mode=complex`、`seg_model=birefnet`、`cross_check=off`，不传 `screen_color`；标准纯色背景四条链路固定传 `background_mode=flat` 并继续沿用各自的 `screen_color`、`seg_model`、`cross_check` 策略。独立 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_BASE_URL` 与 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_REQUEST_TIMEOUT_MS` 已删除，旧 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN` 只作为 BgFilter token 的兼容回退别名。
|
||||
- BgFilter 连接复用、重试与动作帧流水线：api-server 必须在 `AppState` 复用同一个 BgFilter HTTP Client 及 keep-alive 连接池。单次 BgFilter 调用失败后立即重试 `1` 次，第二次仍失败才进入既有“阿里云通用抠图 → 本地键色”降级链，每次已发出的失败调用都单独写审计。角色动作全部 `32 / 40 / 48` 帧按“单帧绿幕源图先落 OSS → BgFilter/降级 → 透明帧落 OSS”独立流水化，使用覆盖本次全部帧的无序在途集合连续发射，不在 api-server 增加供应商进程锁或固定小并发窗口；返回结果携带原始帧序并在收口时排序。任一帧最终失败时必须先排空全部已启动 Future，再让整个动作任务失败退款，不能发布缺帧动画。
|
||||
- 编辑器抠图服务：手动 `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 配置已经删除。手动去背景固定传 `background_mode=complex`、`seg_model=birefnet`、`cross_check=off`，不传 `screen_color`；标准纯色背景四条链路固定传 `background_mode=flat`，并显式传 `screen_color=<screenColor>`、`seg_model=<segModel>` 和 `cross_check=<on|off>`，其中角色形象生成和角色动作逐帧去背传 `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 图生视频前先合成到选定背景色实色，使视频背景等于抠图键色；抽帧后逐帧固定使用 `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 与阿里云抠图失败都写入 `external_api_call_failure` 审计。
|
||||
- BgFilter 连接复用、重试与动作帧流水线：api-server 必须在 `AppState` 复用同一个 BgFilter HTTP Client 及 keep-alive 连接池。flat 与 complex 请求首次失败后都立即重试 `1` 次；标准纯色背景 flat 请求第二次仍失败才进入“阿里云通用抠图 → 本地键色”降级链，手动 complex 请求第二次仍失败则返回最终错误，不接入依赖纯色键值的降级链，也不改变 flat 路径的熔断状态。角色动作全部 `32 / 40 / 48` 帧按“单帧绿幕源图先落 OSS → BgFilter/降级 → 透明帧落 OSS”独立流水化，使用覆盖本次全部帧的无序在途集合连续发射，不在 api-server 增加供应商进程锁或固定小并发窗口；返回结果携带原始帧序并在收口时排序。任一帧最终失败时必须先排空全部已启动 Future，再让整个动作任务失败退款，不能发布缺帧动画。
|
||||
- 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/` 时生成失败。
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# 本地开发验证与生产运维
|
||||
|
||||
更新时间：`2026-06-12`
|
||||
更新时间：`2026-07-15`
|
||||
|
||||
## 标准开发流程
|
||||
|
||||
@@ -33,7 +33,7 @@ npm run dev
|
||||
|
||||
`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；端口漂移、服务重启或子进程退出后以该文件里的实际状态为准。
|
||||
|
||||
通过 `nohup` 在仓库根目录启动 dev 栈时，`nohup.out` 已被 Vite 和 Git 忽略，避免 API 日志持续追加后触发页面刷新循环；重启 Vite 后生效。
|
||||
通过 `nohup` 在仓库根目录启动 dev 栈且未显式重定向 stdout / stderr 时，默认 `nohup.out` 会持续收集 SpacetimeDB、api-server、主站 Vite 和后台 Vite 的整套 dev 栈输出；该文件已被主站 Vite watcher 和 Git 忽略，避免日志追加触发页面刷新循环，重启主站 Vite 后生效。若把输出显式重定向到其它仓库内文件（例如 `> dev.out`），该自定义文件不会自动获得同样的 watcher 保护，应改为写到 Vite root 之外，或同步配置精确的忽略规则。
|
||||
|
||||
单独启动主站前端：
|
||||
|
||||
@@ -66,7 +66,7 @@ Windows 本地如果已在 `%LOCALAPPDATA%\Genarrative\ffmpeg\bin` 安装 FFmpeg
|
||||
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`，连续失败达到 `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，但固定传 `background_mode=complex`、`seg_model=birefnet`、`cross_check=off`，不传背景色；它不进入只适用于已知纯色背景的阿里云 / 本地键色兜底链。标准纯色背景四条链路仍固定传 `background_mode=flat`。两种模式统一使用 `GENARRATIVE_EDITOR_BGFILTER_BASE_URL`、`GENARRATIVE_EDITOR_BGFILTER_TOKEN` 和 `GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS`；旧 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN` 只保留为 token 兼容别名。
|
||||
手动 `POST /api/editor/images/background-removals` 同样调用 BgFilter，但固定传 `background_mode=complex`、`seg_model=birefnet`、`cross_check=off`，不传背景色；首次失败后立即重试 `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 兼容别名。
|
||||
|
||||
`我的` 页签或排障面板展示队列等待时，只读取 BFF 队列接口：`GET /api/runtime/external-generation/queue-overview` 查看当前用户可见队列概览，`GET /api/runtime/external-generation/jobs/{jobId}` 查看单 job 状态。生成页 / 进度页不承接队列概览，只展示当前玩法业务进度；队列接口只提供等待 / 运行 / 失败 / 完成状态补充，最终草稿、作品和结果页仍要轮询对应玩法 session/detail 接口收敛到 ready 或 failed；不要直接查询 `external_generation_job` private table，也不要把 worker 内部 payload 暴露到前端。
|
||||
|
||||
|
||||
@@ -65,7 +65,7 @@
|
||||
角色设定：<用户输入的角色设定>
|
||||
```
|
||||
|
||||
- 角色图生成完成后，编辑器后端必须先把带自动决策纯色背景的源图写入 OSS，再调用独立 BgFilter 服务透明化：multipart 字段包含 `file`、`screen_color=<screenColor>`、`seg_model=<segModel>` 和 `background_mode=flat`，用户路径默认并只提交 `seg_model=birefnet`；`flat` 明确表示沿用单一纯色背景抠图模式。这里的 `seg_model=birefnet` 是 BgFilter 管线内部后端，不等同于手动去背景使用的独立 BiRefNet 服务。角色图 prompt 按 `screenColor` 写入颜色名称、hex 和 RGB。该流程不再调用 RPG / 资产工坊的角色主图专用 `character_visual_assets` 后处理，也不调用手动去背景的独立 BiRefNet；输出仍统一为透明背景 PNG，随后写入 OSS 私有对象并确认 `asset_object`。接口回包仍返回透明 PNG Data URL 供画板立即显示，同时返回 `objectKey` / `assetObjectId`，前端创建图层和画板资源记录时必须保存这些字段。
|
||||
- 角色图生成完成后，编辑器后端必须先把带自动决策纯色背景的源图写入 OSS，再调用共享 BgFilter 服务透明化：multipart 字段包含 `file`、`screen_color=<screenColor>`、`seg_model=<segModel>`、`background_mode=flat` 和 `cross_check=on`，用户路径默认并只提交 `seg_model=birefnet`；`flat` 明确表示单一纯色背景抠图模式，`birefnet` 是 BgFilter 管线内部后端。首次请求失败后立即重试 `1` 次，第二次仍失败进入“阿里云通用抠图 → 本地键色”降级链。角色图 prompt 按 `screenColor` 写入颜色名称、hex 和 RGB。该流程不再调用 RPG / 资产工坊的角色主图专用 `character_visual_assets` 后处理，也不复用手动去背景的 `background_mode=complex` 路径；输出仍统一为透明背景 PNG，随后写入 OSS 私有对象并确认 `asset_object`。接口回包仍返回透明 PNG Data URL 供画板立即显示，同时返回 `objectKey` / `assetObjectId`，前端创建图层和画板资源记录时必须保存这些字段。
|
||||
- 对 `assetKind: "character"` 的角色图层执行 `重绘` 时，前端仍使用原图作为参考图，但请求 `kind` 必须传 `character`，让后端继续套用上述角色提示词限定、角色图后处理和角色资产持久化；普通图片图层重绘仍保持 `kind: "quick-edit"`。
|
||||
|
||||
## 生成规范参考图
|
||||
|
||||
@@ -62,17 +62,16 @@ pub use mapper::{
|
||||
ExternalGenerationJobListRecordInput, ExternalGenerationJobPhaseUpdateRecordInput,
|
||||
ExternalGenerationJobRecord, ExternalGenerationJobRenewLeaseRecordInput,
|
||||
ExternalGenerationJobSummaryListRecord, ExternalGenerationJobSummaryRecord,
|
||||
ExternalGenerationQueueStatsRecord,
|
||||
FeatureGateConfigRecord, JumpHopActionRequest, JumpHopActionResponse, JumpHopActionType,
|
||||
JumpHopCharacterAsset, JumpHopDifficulty, JumpHopDraftResponse, JumpHopGalleryCardResponse,
|
||||
JumpHopGalleryDetailResponse, JumpHopGalleryResponse, JumpHopGenerationStatus,
|
||||
JumpHopJumpRequest, JumpHopJumpResponse, JumpHopJumpResult, JumpHopLastJump, JumpHopPath,
|
||||
JumpHopPlatform, JumpHopRestartRunRequest, JumpHopRunResponse, JumpHopRunStatus,
|
||||
JumpHopRuntimeRunSnapshotResponse, JumpHopScoring, JumpHopSessionResponse,
|
||||
JumpHopSessionSnapshotResponse, JumpHopStartRunRequest, JumpHopStylePreset, JumpHopTileAsset,
|
||||
JumpHopTileType, JumpHopWorkDetailResponse, JumpHopWorkMutationResponse,
|
||||
JumpHopWorkProfileResponse, JumpHopWorkSummaryResponse, JumpHopWorksResponse,
|
||||
JumpHopWorkspaceCreateRequest, Match3DAgentMessageFinalizeRecordInput,
|
||||
ExternalGenerationQueueStatsRecord, FeatureGateConfigRecord, JumpHopActionRequest,
|
||||
JumpHopActionResponse, JumpHopActionType, JumpHopCharacterAsset, JumpHopDifficulty,
|
||||
JumpHopDraftResponse, JumpHopGalleryCardResponse, JumpHopGalleryDetailResponse,
|
||||
JumpHopGalleryResponse, JumpHopGenerationStatus, JumpHopJumpRequest, JumpHopJumpResponse,
|
||||
JumpHopJumpResult, JumpHopLastJump, JumpHopPath, JumpHopPlatform, JumpHopRestartRunRequest,
|
||||
JumpHopRunResponse, JumpHopRunStatus, JumpHopRuntimeRunSnapshotResponse, JumpHopScoring,
|
||||
JumpHopSessionResponse, JumpHopSessionSnapshotResponse, JumpHopStartRunRequest,
|
||||
JumpHopStylePreset, JumpHopTileAsset, JumpHopTileType, JumpHopWorkDetailResponse,
|
||||
JumpHopWorkMutationResponse, JumpHopWorkProfileResponse, JumpHopWorkSummaryResponse,
|
||||
JumpHopWorksResponse, JumpHopWorkspaceCreateRequest, Match3DAgentMessageFinalizeRecordInput,
|
||||
Match3DAgentMessageRecord, Match3DAgentMessageSubmitRecordInput,
|
||||
Match3DAgentSessionCreateRecordInput, Match3DAgentSessionRecord, Match3DAnchorItemRecord,
|
||||
Match3DAnchorPackRecord, Match3DClickConfirmationRecord, Match3DCompileDraftRecordInput,
|
||||
|
||||
Reference in New Issue
Block a user