diff --git a/docs/technical/【技术方案】Tripo 3D生成API集成-2026-09-21.md b/docs/technical/【技术方案】Tripo 3D生成API集成-2026-09-21.md index 920039352..be02d46bb 100644 --- a/docs/technical/【技术方案】Tripo 3D生成API集成-2026-09-21.md +++ b/docs/technical/【技术方案】Tripo 3D生成API集成-2026-09-21.md @@ -164,7 +164,7 @@ width/height = 预览图像素尺寸 模型格式与体积由 `AssetObject` 承担(`content_type`、`content_length`、`content_hash`),因此不新增 `model_format`、`size_bytes`、`poly_count` 等列。两个槽位的 `content_type` 都在写入前按字节识别真实产物:模型按魔数认 GLB 的 `glTF` 头、FBX 的 `Kaydara FBX Binary` 头与 glTF 的 JSON 正文,预览按魔数认 PNG / JPEG / WebP;不直接采信 provider 返回或下载响应头声明的类型,对象键扩展名由该内容类型派生。只有字节判不出来时才采信声明值,且声明值必须落在该槽位的白名单内(模型:`model/gltf-binary`、`model/gltf+json`、`model/fbx`、`application/x-fbx`;预览:`image/png`、`image/jpeg`、`image/jpg`、`image/webp`);两边都对不上就直接按上游内容不合法失败并退款,不做任何兜底 —— 放行 `text/plain` 这类未知类型只会落成「错的 content type + 拼出来的扩展名」。客户端不复制这份格式清单:画布只按「`assetKind=model3d` 且 `objectKey` 非空」放行,能否交给 3D 查看器由 `packages/model3d-viewer` 判定,判据依次是读接口声明的 `Content-Type`、字节魔数、地址扩展名,全判不出来即按 `unsupported-format` 报错。这里的顺序是「信任后端检测结果」:`content_type` 在后端写入前已经按字节核过,所以客户端以声明为先;字节魔数只兜住声明缺失或认不出来(例如 `application/octet-stream`)的情况,不负责纠正一个「认得出来但不对」的声明。 -产物对象由 api-server 按固定前缀 PUT 写入、再 HEAD 复核后才登记;PUT 带退避重试(最多 3 次尝试,退避 250 / 500 ms),只对传输 / 超时 / 408 / 429 / 5xx 重试,确定性 4xx 直接失败。3D job 最多只尝试一次,一次瞬时网络失败就会废掉一笔已经计费的生成,所以这条链路上的每个网络动作都要能重试。 +产物对象由 api-server 按固定前缀 PUT 写入、再 HEAD 复核后才登记;PUT 带退避重试(最多 3 次尝试,退避 250 / 500 ms),只对传输 / 超时 / 408 / 429 / 5xx 重试,确定性 4xx 直接失败。3D job 最多只尝试一次,一次瞬时网络失败就会废掉一笔已经计费的生成,所以这条链路上的每个网络动作都要能重试。反过来,产物一旦上传成功、后续预览图上传或登记失败,就把已经传上去的对象删掉(删除失败只记警告,残留对象按日志人工清理):不接受“失败就烂在 bucket 里”。 `external_generation_job.phase` 的取值集合不变,仍只允许现有两种执行阶段;阶段文案由 api-server 映射,不扩展 schema 常量。 diff --git a/server-rs/crates/api-server/src/tripo3d/storage.rs b/server-rs/crates/api-server/src/tripo3d/storage.rs index 8040ae9d8..126143bb9 100644 --- a/server-rs/crates/api-server/src/tripo3d/storage.rs +++ b/server-rs/crates/api-server/src/tripo3d/storage.rs @@ -13,10 +13,14 @@ use axum::http::StatusCode; use module_assets::{ AssetObjectAccessPolicy, AssetObjectUpsertInput, build_asset_object_upsert_input, }; -use platform_oss::{LegacyAssetPrefix, OssHeadObjectRequest, OssObjectAccess, OssPutObjectRequest}; +use platform_oss::{ + LegacyAssetPrefix, OssDeleteObjectRequest, OssHeadObjectRequest, OssObjectAccess, + OssPutObjectRequest, +}; use serde_json::json; use sha2::{Digest, Sha256}; use shared_contracts::editor_generation::editor_generation_stable_asset_object_id; +use tracing::warn; use crate::{ editor_project::{ @@ -214,6 +218,37 @@ pub(crate) async fn store_model3d_artifact( }) } +/// 丢弃一个已经写进 OSS、但最终没能登记成正式资源的产物对象。 +/// +/// 上传成功、登记失败时如果不清理,bucket 里会一直堆着按 job 命名的私有残留对象。 +/// 删除失败只记警告:这时 job 已经注定失败,删除不成功不该改写对外错误,但残留对象 +/// 需要人工按日志清理。 +pub(crate) async fn discard_model3d_artifact(state: &AppState, artifact: &StoredModel3dArtifact) { + let object_key = artifact.object_key.clone(); + let Some(oss_client) = state.oss_client() else { + warn!( + object_key = %object_key, + "3D 产物登记失败后要删除对象,但 OSS 未配置,需要人工清理" + ); + return; + }; + if let Err(error) = oss_client + .delete_object( + state.editor_oss_http_client(), + OssDeleteObjectRequest { + object_key: object_key.clone(), + }, + ) + .await + { + warn!( + object_key = %object_key, + error = %error, + "3D 产物登记失败后删除对象也失败,需要人工清理" + ); + } +} + /// provider 声明的 content type 去参数、去空白、转小写后与槽位白名单比对; /// 不在表里(含空值、`application/octet-stream`)返回 `None`。 fn declared_artifact_content_type(raw: &str, slot: Model3dArtifactSlot) -> Option<&'static str> { diff --git a/server-rs/crates/api-server/src/tripo3d/worker.rs b/server-rs/crates/api-server/src/tripo3d/worker.rs index 081f5129b..f70e9d122 100644 --- a/server-rs/crates/api-server/src/tripo3d/worker.rs +++ b/server-rs/crates/api-server/src/tripo3d/worker.rs @@ -44,7 +44,8 @@ use super::{ provider::{TRIPO_PROVIDER, tripo_provider_client}, result::{build_result, job_result_payload}, storage::{ - MODEL3D_ASSET_KIND, Model3dArtifactSlot, StoredModel3dArtifact, store_model3d_artifact, + MODEL3D_ASSET_KIND, Model3dArtifactSlot, StoredModel3dArtifact, discard_model3d_artifact, + store_model3d_artifact, }, }; @@ -119,25 +120,40 @@ async fn run_model3d_job( model.content_type.as_str(), ) .await?; - let stored_preview = store_model3d_artifact( + let stored_preview = match store_model3d_artifact( state, caller, Model3dArtifactSlot::Preview, preview.bytes, preview.content_type.as_str(), ) - .await?; - persist_result( + .await + { + Ok(stored) => stored, + Err(error) => { + discard_model3d_artifact(state, &stored_model).await; + return Err(error); + } + }; + // 产物已经进了 OSS,但还没登记成正式资源:这一步失败就把刚传上去的对象删掉, + // 不让按 job 命名的私有残留对象一直堆在 bucket 里。 + if let Err(error) = persist_result( state, caller, job, &request, - stored_model, - stored_preview, + &stored_model, + &stored_preview, preview_width, preview_height, ) .await + { + discard_model3d_artifact(state, &stored_model).await; + discard_model3d_artifact(state, &stored_preview).await; + return Err(error); + } + Ok(()) } /// checkpoint 是 provider 侧任务的唯一凭据,也是 at-most-once 的开关:有值就只能查询, @@ -260,8 +276,9 @@ async fn persist_result( caller: &EditorGenerationCaller, job: &ExternalGenerationJobRecord, request: &Model3dJobRequest, - model: StoredModel3dArtifact, - preview: StoredModel3dArtifact, + // 取引用而不是拿走所有权:登记失败时调用方还要按对象键把刚传上去的产物删掉。 + model: &StoredModel3dArtifact, + preview: &StoredModel3dArtifact, preview_width: u32, preview_height: u32, ) -> Result<(), AppError> { @@ -382,22 +399,22 @@ async fn persist_result( has_resource.then(|| resource_id.clone()), has_asset.then_some(asset_id_for_result), ), - &model, - &preview, + model, + preview, ); // 预览图单独登记成 asset_object:它没有自己的资源行,但必须属于当前账号, // 否则后续按 objectKey 解析归属时会认为它未登记。 let items = vec![ EditorGenerationResultPersistItemRecordInput { slot: MODEL3D_MODEL_SLOT.to_string(), - asset_object: Some(model.asset_object), + asset_object: Some(model.asset_object.clone()), project_resource, asset, binding: None, }, EditorGenerationResultPersistItemRecordInput { slot: MODEL3D_PREVIEW_SLOT.to_string(), - asset_object: Some(preview.asset_object), + asset_object: Some(preview.asset_object.clone()), project_resource: None, asset: None, binding: None,