把 Tripo 配置写成明确的破坏性部署要求,并说明刻意不做开关
- docs 开发运维:Tripo 两项配置改成以「破坏性部署要求」表述,写明升级前必须配好、不做开关也没有缺配置先启动的逃生口,不需要 3D 的机器只跑不检查该配置的两个角色 - docs/adr 0006:补上同一条口径与理由(允许缺配置启动就会退回「起得来但悄悄坏掉」的形态),并写明被否决的逃生口
This commit is contained in:
@@ -12,4 +12,6 @@
|
||||
|
||||
代价与已知取舍:请求期 503 作为第二道防线保留,兜住「启动后配置被改」或「别的入口拼出非法 `AppConfig`」,行为仍是不可用、不扣费、不入队;所有本地与 CI 环境在启动 api-server / worker 前都必须提供这两项,之前 `.env` 里一份 `TRIPO_*` 都没有的开发者会先撞上一次启动失败;Tripo 密钥没有 `_FILE` 变体(bgfilter 的 `GENARRATIVE_BGFILTER_INTERNAL_TOKEN` 有),密钥交付方式仍按部署机约定走 env。
|
||||
|
||||
这是一条破坏性部署要求,不是可选项:升级到本版本后,凡部署 `api` / `external-generation-worker` / `all` 角色的机器必须先把 `TRIPO_BASE_URL` 与 `TRIPO_API_KEY` 配好再上线,否则新进程起不来,而旧进程一停 3D 入口就是整体不可用。刻意不提供开关,也不加「缺配置先启动」的逃生口——一旦允许缺配置启动,回到的就是本次要消灭的那种「起得来但悄悄坏掉」的形态;确实不需要 3D 的部署只跑 `bgfilter-worker` / `external-generation-controller`,这两个角色不做 Tripo 启动校验。
|
||||
|
||||
被否决的做法:**保留内置默认网关**(缺配置时请求会打到运维没预期的账号);**只做请求期 503**(本次要修的就是这种「起得来、检查全绿、提交后失败」的形态);**只在 worker 角色校验**(HTTP 角色照样能把 3D 单收进来并返回 202,失败点仍然远离排查入口);**继续在请求路径静默钳制超时与重试**;**把两个旋钮也改成必填**(它们有明确的内置值、缺省是合法部署形态,强制填写只会制造与默认值等价的噪声配置)。
|
||||
|
||||
@@ -242,7 +242,7 @@ spacetime sql <database> "SELECT * FROM runtime_setting LIMIT 1" --server http:/
|
||||
本地 `.env`、`.env.local` 或 `.env.secrets.local` 修改后必须重启 `api-server` 才会生效;若已经通过 `npm run dev` 启动完整联调,可在该终端输入 `rs api-server`。排查图片编辑器 Tiantoken 生成链路时,确认 `TIANTOKEN_BASE_URL`、`TIANTOKEN_API_KEY` 和 `TIANTOKEN_IMAGE_REQUEST_TIMEOUT_MS` 只在本地或服务器密钥文件中配置,不能写入 Git。VectorEngine 配置仅保留给 Suno 音乐任务。`TIANTOKEN_IMAGE_REQUEST_TIMEOUT_MS` 是单次 attempt 的配置上限,默认 `1000000`;配置加载层允许显式值低于该默认值,不再在读取环境变量时强制抬高。业务模型和 Tiantoken provider 首选请求都使用 `gpt-image-2`,符合条件时才回退到兜底模型 `gpt-image-2-c`;图片协议、URL / base64 响应解析、远端图片下载和 provider 侧结构化日志在 `server-rs/crates/platform-image`,`api-server` 只做编辑器请求编排、OSS / asset 持久化、计费和失败审计落库。`platform-image` 会在 JSON 生成和 multipart 编辑请求发送前按同一 GPT-image-2 family 规则归一显式像素尺寸;若请求发送失败,先按同一 `request_id` 查看 provider 日志与 `external_api_call_failure.metadata_json.errorSource`,当前 multipart `/v1/images/edits` 单独强制 HTTP/1.1。
|
||||
|
||||
编辑器 ElevenLabs 音效生成只从服务端读取 `ELEVENLABS_BASE_URL`、`ELEVENLABS_API_KEY` 和 `ELEVENLABS_REQUEST_TIMEOUT_MS`,timeout 默认 `180000ms`;base URL 或 Key 缺失时失败关闭,不回退 Vidu。生产 API 与 external-generation worker 通过共享 API env 取得同一配置,模板见 `deploy/env/api-server.env.example`;Key 不得进入 Web/Vite 环境、命令参数、日志、fixture 或仓库。普通测试只使用 loopback mock,禁止把真实付费请求作为 T3 自动验收。
|
||||
Tripo 3D 生成的 `TRIPO_BASE_URL` / `TRIPO_API_KEY` 是**启动期必填项**:网关没有内置默认值,`api` / `external-generation-worker` / `all` 角色缺任意一项就直接拒绝启动(请求期 503 只是第二道防线),见 [ADR 0006](../adr/【ADR】0006-Tripo配置启动期失败关闭-2026-09-24.md);本地在 `.env.local` / `.env.secrets.local` 补齐,生产在 `/etc/genarrative/api-server.env` 补齐后再部署或重启。`TRIPO_REQUEST_TIMEOUT_MS` / `TRIPO_RETRIES` 可缺省(沿用内置 `60000` / `2`),显式给出时零值或越界值同样让进程拒绝启动。
|
||||
Tripo 3D 生成的 `TRIPO_BASE_URL` / `TRIPO_API_KEY` 是**破坏性部署要求**::网关没有内置默认值,`api` / `external-generation-worker` / `all` 角色缺任意一项就直接拒绝启动(请求期 503 只是第二道防线),见 [ADR 0006](../adr/【ADR】0006-Tripo配置启动期失败关闭-2026-09-24.md);本地在 `.env.local` / `.env.secrets.local` 补齐,生产在 `/etc/genarrative/api-server.env` 补齐后再部署或重启。`TRIPO_REQUEST_TIMEOUT_MS` / `TRIPO_RETRIES` 可缺省(沿用内置 `60000` / `2`),显式给出时零值或越界值同样让进程拒绝启动。这条要求不做开关,也没有「先起来、缺配置再说」的逃生口:需要 3D 能力的部署必须在上线前配好这两项(生产改 `/etc/genarrative/api-server.env` 后重启,本地补 `.env.local` / `.env.secrets.local`),否则升级会卡在启动期——旧进程一停,3D 入口就是整体不可用;确认不需要 3D 的机器只跑 `bgfilter-worker` / `external-generation-controller` 这两个不检查 Tripo 配置的角色。
|
||||
|
||||
SFX V2 发布必须使用维护窗:先关闭 SFX 入队,再对显式目标执行只读 `spacetime sql <database> --server <server-url> --format json "SELECT job_id, status, request_payload_json FROM external_generation_job WHERE job_kind = 'editor_sound_effect_generation' AND (status = 'pending' OR status = 'running')"`;结果非零时保持旧 Worker drain,不得删除任务或让新 Worker 解析旧 Vidu payload。禁止依赖默认 server,禁止使用 `--root-dir`。清零后先部署共享 env 已对齐的 api-server / external-generation worker,检查 `/healthz` 和 Worker 启动,再部署 Web 并小流量开放 SFX。灰度对账 job 完成数、退款数、ElevenLabs POST 数、完成资源数和孤儿资源;翻译失败仍调用 provider、单 job provider POST 大于一次、成功退款或失败未退款均应立即停止放量。回滚先停止入队并收口 V2 pending / running job,不自动切回 Vidu,不执行 SpacetimeDB schema 或数据回滚。完整清单见 `docs/【实施记录】SFX生成优化V2.0T6测试与发布门禁-2026-08-07.md`。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user