3DCellForge 后端原理解读Node.js 多提供商 3D 生成任务队列与本地缓存设计【免费下载链接】3DCellForgeAI-powered interactive 3D model generation, inspection, and presentation studio.项目地址: https://gitcode.com/gh_mirrors/3d/3DCellForge3DCellForge 是一个 AI 驱动的交互式 3D 模型生成与演示工作台。它的 Node.js 后端用一套「多提供商 3D 生成任务队列 本地 GLB 缓存」设计把 Hyper3D Rodin、Tripo、Fal.ai、Hunyuan3D 等多家图生 3D 服务统一成同一个异步任务接口再用本地缓存目录避免临时链接失效与重复下载。本文不带大量代码用通俗方式带你完整看懂这套后端设计。一、整体架构前端只问一个后端后端统一对接多家 3D 服务3DCellForge 的前端是 React Three.js 工作台它不直接调用任何 3D 厂商的 API而是全部请求本地 Node.js 后端默认http://127.0.0.1:8787。整个后端只有一个入口文件 server.mjs用原生node:http搭建暴露的接口非常克制接口作用POST /api/3d/generate创建 3D 生成任务立刻返回taskIdGET /api/3d/status/:taskId轮询任务状态、进度与模型地址GET /api/3d/model?url...代理下载远端模型仅允许 HTTPS/本机地址POST /api/3d/local-model导入本地.glb/.gltf文件GET /api/3d/local-model/:id读取本地缓存的模型文件GET /api/3d/health查看各提供商是否已配置GET /api/3d/logs本地诊断日志仅限本机访问这种「创建任务 轮询状态」的异步任务队列模式是所有长耗时 AI 生成的通用解法生成一个 3D 模型动辄几十秒到几分钟后端不可能同步等待所以先给你一个taskId小票你再拿着小票来查进度。二、多提供商适配层4 个文件4 条生成通道 后端把每种生成服务封装成独立的 Provider 文件统一放在 server/providers/ 目录下每个文件对外只暴露三个函数健康检查、创建任务、查询任务。提供商源码调用链路Hyper3D Rodin默认rodin.mjsmultipart 提交/rodin任务 → 轮询/status→ 通过/download取回 GLBTripotripo.mjs先申请 STS 临时凭证上传对象存储 → 创建image_to_model任务 → 轮询任务Fal.aifal.mjs用官方 client 的 storage 上传 queue 队列提交可在设置里切换 5 种模型Hunyuan3D本地hunyuan.mjs对接本地 Hunyuan3D APIPOST /send→GET /status/:uid支持直接返回 base64 GLB几个值得新手学习的设计点统一调度入口 createGenerationTask 只按provider名字做一层简单分发路由层完全不知道具体厂商的细节统一任务形状无论哪家厂商返回都是{ provider, taskId, status, progress, modelUrl }结构各 Provider 内部负责把厂商五花八门的状态词done、succeeded、in_progress…归一化成queued / running / success / failed四态自动降级链前端 getProviderPlan 里auto模式会按rodin → tripo → fal → hunyuan → 浏览器端 JS Depth依次降级保证没有配置任何云端 Key 时依然有兜底方案。三、生成任务队列提交 → 轮询 → 完成 一次生成的完整生命周期是这样的提交前端把参考图转成 data URL随文件名、提示词一起发给POST /api/3d/generatemodelApi.js。后端解析图片、组装厂商参数例如 Tripo 的 STS 上传流程拿到任务 ID 后立即响应轮询前端 waitFor3dModel 按固定间隔循环调用GET /api/3d/status/:taskId把progress百分比实时渲染到左侧的「生成队列」面板GenerationTaskCenter.jsx直到成功、失败或超时完成成功时返回modelUrl前端把模型拉进中央 3D 舞台并写入 IndexedDB刷新页面后仍可从模型库恢复。一个巧妙细节Rodin / Fal 这类需要多段信息的任务会把taskUuid、requestId等元数据用 base64url 编码进taskId本身如rodin-xxxx见 encodeRodinTaskId后端因此可以保持无状态——不需要在内存里保存任务表重启也不丢任务。四、本地缓存设计.generated-models目录的四道防线 厂商返回的模型链接通常是临时签名 URL几小时后就会过期。3DCellForge 的解法是每次轮询到「成功」后端立刻把 GLB 下载到本地.generated-models/目录目录名在 config.mjs 配置并从此只给你本地地址。核心实现 cacheRemoteModelAs 有四个防御动作缓存优先每次查状态先问一句 hasLocalModel——本地已有就直接返回success连厂商 API 都不调用见 getRodinTask。这意味着重启后端、重开页面已完成的任务秒级复用临时文件落盘先写入xxx.tmp临时文件确认无误后才rename成正式文件避免半成品被当作有效模型魔数校验validateModelBuffer 会检查 GLB 文件头是否为glTF魔数、GLTF 是否为合法 JSON垃圾数据进不了缓存本地服务serveLocalModel 以正确的model/gltf-binary类型和Cache-Control: private, max-age3600响应浏览器还会再缓存一小时。本地导入的模型importLocalModel和生成模型共用同一套缓存目录所以「自己拖进来的 GLB」和「AI 生成的 GLB」在工作台里享受完全一致的加载路径。五、安全与可观测性新手容易忽略的细节 密钥只留在服务端所有 API Key 放在.env.local由 loadLocalEnv 在启动时加载前端构建产物里一个字符都看不到日志自动脱敏logger.mjs 定义了敏感字段名单API Key、imageDataUrl、modelBase64等写入.logs/的 JSON 日志前统一打码诊断接口/api/3d/logs也只允许本机访问请求可追踪每个请求生成短requestId并写入X-Request-Id响应头出问题时能对上日志体积护栏图片请求体上限 28MB、模型上传上限 180MBconfig.mjs超大文件在入口就被拦下代理友好所有出站请求支持HTTPS_PROXY代理config.mjs内网环境也能调通云端 3D 服务。六、小结这套后端设计好在哪里 ✅一份接口多家服务路由层只认「任务」抽象新增提供商只需加一个 Provider 文件 两行分发异步任务队列创建即返回 轮询查状态天然适合长耗时的图生 3D 流程本地缓存兜底临时链接过期不怕模型永远在.generated-models/里刷新、重启、离线演示都可用无状态设计任务元数据编码进taskId后端不需要任务数据库轻量到只依赖node:http undici。想亲手体验克隆仓库后执行下面两步就能打开左侧任务队列把一张参考图变成可交互的 3D 模型npm run dev:api # 启动 3D 生成后端8787 端口 npm run dev # 启动前端工作台更多配置说明各提供商 Key、Auto 降级链、Hunyuan 本地模式可查阅 README.zh-CN.md。【免费下载链接】3DCellForgeAI-powered interactive 3D model generation, inspection, and presentation studio.项目地址: https://gitcode.com/gh_mirrors/3d/3DCellForge创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/3 17:05:32 · 阅读 1.2k 3DCellForge 后端原理解读：Node.js 多提供商 3D 生成任务队列与本地缓存设计
3DCellForge 后端原理解读Node.js 多提供商 3D 生成任务队列与本地缓存设计【免费下载链接】3DCellForgeAI-powered interactive 3D model generation, inspection, and presentation studio.项目地址: https://gitcode.com/gh_mirrors/3d/3DCellForge3DCellForge 是一个 AI 驱动的交互式 3D 模型生成与演示工作台。它的 Node.js 后端用一套「多提供商 3D 生成任务队列 本地 GLB 缓存」设计把 Hyper3D Rodin、Tripo、Fal.ai、Hunyuan3D 等多家图生 3D 服务统一成同一个异步任务接口再用本地缓存目录避免临时链接失效与重复下载。本文不带大量代码用通俗方式带你完整看懂这套后端设计。一、整体架构前端只问一个后端后端统一对接多家 3D 服务3DCellForge 的前端是 React Three.js 工作台它不直接调用任何 3D 厂商的 API而是全部请求本地 Node.js 后端默认http://127.0.0.1:8787。整个后端只有一个入口文件 server.mjs用原生node:http搭建暴露的接口非常克制接口作用POST /api/3d/generate创建 3D 生成任务立刻返回taskIdGET /api/3d/status/:taskId轮询任务状态、进度与模型地址GET /api/3d/model?url...代理下载远端模型仅允许 HTTPS/本机地址POST /api/3d/local-model导入本地.glb/.gltf文件GET /api/3d/local-model/:id读取本地缓存的模型文件GET /api/3d/health查看各提供商是否已配置GET /api/3d/logs本地诊断日志仅限本机访问这种「创建任务 轮询状态」的异步任务队列模式是所有长耗时 AI 生成的通用解法生成一个 3D 模型动辄几十秒到几分钟后端不可能同步等待所以先给你一个taskId小票你再拿着小票来查进度。二、多提供商适配层4 个文件4 条生成通道 后端把每种生成服务封装成独立的 Provider 文件统一放在 server/providers/ 目录下每个文件对外只暴露三个函数健康检查、创建任务、查询任务。提供商源码调用链路Hyper3D Rodin默认rodin.mjsmultipart 提交/rodin任务 → 轮询/status→ 通过/download取回 GLBTripotripo.mjs先申请 STS 临时凭证上传对象存储 → 创建image_to_model任务 → 轮询任务Fal.aifal.mjs用官方 client 的 storage 上传 queue 队列提交可在设置里切换 5 种模型Hunyuan3D本地hunyuan.mjs对接本地 Hunyuan3D APIPOST /send→GET /status/:uid支持直接返回 base64 GLB几个值得新手学习的设计点统一调度入口 createGenerationTask 只按provider名字做一层简单分发路由层完全不知道具体厂商的细节统一任务形状无论哪家厂商返回都是{ provider, taskId, status, progress, modelUrl }结构各 Provider 内部负责把厂商五花八门的状态词done、succeeded、in_progress…归一化成queued / running / success / failed四态自动降级链前端 getProviderPlan 里auto模式会按rodin → tripo → fal → hunyuan → 浏览器端 JS Depth依次降级保证没有配置任何云端 Key 时依然有兜底方案。三、生成任务队列提交 → 轮询 → 完成 一次生成的完整生命周期是这样的提交前端把参考图转成 data URL随文件名、提示词一起发给POST /api/3d/generatemodelApi.js。后端解析图片、组装厂商参数例如 Tripo 的 STS 上传流程拿到任务 ID 后立即响应轮询前端 waitFor3dModel 按固定间隔循环调用GET /api/3d/status/:taskId把progress百分比实时渲染到左侧的「生成队列」面板GenerationTaskCenter.jsx直到成功、失败或超时完成成功时返回modelUrl前端把模型拉进中央 3D 舞台并写入 IndexedDB刷新页面后仍可从模型库恢复。一个巧妙细节Rodin / Fal 这类需要多段信息的任务会把taskUuid、requestId等元数据用 base64url 编码进taskId本身如rodin-xxxx见 encodeRodinTaskId后端因此可以保持无状态——不需要在内存里保存任务表重启也不丢任务。四、本地缓存设计.generated-models目录的四道防线 厂商返回的模型链接通常是临时签名 URL几小时后就会过期。3DCellForge 的解法是每次轮询到「成功」后端立刻把 GLB 下载到本地.generated-models/目录目录名在 config.mjs 配置并从此只给你本地地址。核心实现 cacheRemoteModelAs 有四个防御动作缓存优先每次查状态先问一句 hasLocalModel——本地已有就直接返回success连厂商 API 都不调用见 getRodinTask。这意味着重启后端、重开页面已完成的任务秒级复用临时文件落盘先写入xxx.tmp临时文件确认无误后才rename成正式文件避免半成品被当作有效模型魔数校验validateModelBuffer 会检查 GLB 文件头是否为glTF魔数、GLTF 是否为合法 JSON垃圾数据进不了缓存本地服务serveLocalModel 以正确的model/gltf-binary类型和Cache-Control: private, max-age3600响应浏览器还会再缓存一小时。本地导入的模型importLocalModel和生成模型共用同一套缓存目录所以「自己拖进来的 GLB」和「AI 生成的 GLB」在工作台里享受完全一致的加载路径。五、安全与可观测性新手容易忽略的细节 密钥只留在服务端所有 API Key 放在.env.local由 loadLocalEnv 在启动时加载前端构建产物里一个字符都看不到日志自动脱敏logger.mjs 定义了敏感字段名单API Key、imageDataUrl、modelBase64等写入.logs/的 JSON 日志前统一打码诊断接口/api/3d/logs也只允许本机访问请求可追踪每个请求生成短requestId并写入X-Request-Id响应头出问题时能对上日志体积护栏图片请求体上限 28MB、模型上传上限 180MBconfig.mjs超大文件在入口就被拦下代理友好所有出站请求支持HTTPS_PROXY代理config.mjs内网环境也能调通云端 3D 服务。六、小结这套后端设计好在哪里 ✅一份接口多家服务路由层只认「任务」抽象新增提供商只需加一个 Provider 文件 两行分发异步任务队列创建即返回 轮询查状态天然适合长耗时的图生 3D 流程本地缓存兜底临时链接过期不怕模型永远在.generated-models/里刷新、重启、离线演示都可用无状态设计任务元数据编码进taskId后端不需要任务数据库轻量到只依赖node:http undici。想亲手体验克隆仓库后执行下面两步就能打开左侧任务队列把一张参考图变成可交互的 3D 模型npm run dev:api # 启动 3D 生成后端8787 端口 npm run dev # 启动前端工作台更多配置说明各提供商 Key、Auto 降级链、Hunyuan 本地模式可查阅 README.zh-CN.md。【免费下载链接】3DCellForgeAI-powered interactive 3D model generation, inspection, and presentation studio.项目地址: https://gitcode.com/gh_mirrors/3d/3DCellForge创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考