Civitai 3D 模型模块Model3D 实体 Schema、生成-发布全链路与详情页读取路径解析【免费下载链接】civitaiA repository of models, textual inversions, and more项目地址: https://gitcode.com/GitHub_Trending/ci/civitai本文围绕 docs/3d-models-diagram.md 展开系统讲解 Civitai 平台新增的 3D 模型Model3D子域的完整数据模型7 张新表与既有User、Image、Thread、Post、Report、CollectionItem等实体的关系图、基于 orchestrator PolyGen 工作流的生成 → 入库 → 发布生命周期、详情页读取路径以及每张新表与既有Model/ModelFile等实体的设计取舍。读完本文你将能理解该模块为何选择复用ImageReaction、把下载事件落到 ClickHouse、以及schema 为唯一事实来源的迁移约定在代码库中如何落地。1. 文档定位与主计划文档配套、以 Mermaid 为载体的设计图3d-models-diagram.md 是 docs/3d-models-plan.mdrev 9开放问题已解决、可进入实施的配套视觉参考Companion专门刻画三件事新实体的形状、它们与既有 Civitai 数据表的关系、以及关键用户流程。文档中的图全部采用 Mermaid 编写可直接在 GitHub 或 VS Code配合Markdown Preview Mermaid Support扩展中内联渲染。文档同时声明了一条重要约定图与 schema 不一致时以 schema 为准If diagrams drift from the schema, the schema wins——因为 Prisma schema仓库中实际位于 packages/civitai-db-schema/prisma/schema.full.prisma才是可编辑的事实来源。这一点在后文演化差异部分会得到印证。2. 实体关系图ERD8 个新实体与既有表的连接图例约定蓝色 新表灰色 被触碰的既有表基数用 Mermaid 的||、|o、}o、}|记法表达。完整 ERD 如下原文档第 1 节2.1 有意不在图里的东西rev 5 的删减项文档专门列出了三个被刻意删除的实体它们的设计决定值得单独强调Model3DReaction—— 不存在独立的 3D 模型点赞表用户直接对缩略图Image一个既有的Image行做 reaction复用既有ImageReaction表Model3DDownloadHistory—— 下载事件不进 Postgres而是作为事件写入ClickHouse由聚合任务反规范化进Model3DMetric.downloadCountModel3DVersion—— v1 不做版本管理versioning。2.2 与当前 Prisma schema 的对照对照 schema.full.prisma 中的实际定义核心字段与图一致name为citextthumbnailImageId可空且unique、外键onDelete: SetNull缩略图被删不炸外键应用层再约束发布必须有缩略图workflowId可空且唯一注释明确NULL for future user-uploaded rows——v1 只走生成但 schema 预留了用户上传路径status默认Draft。从源码结构看当前 schema 已比图演化出若干新字段例如Model3D增加了meta、gallerySettings逐图/用户/标签的画廊隐藏设置与软删除四件套deletedAt/deletedByModel3DFile增加了variant判别列见第 7 节迁移演化。另外图中Model3DReview.rating (CHECK 1..5)与Model3DMetric.ratingAvg在现网 schema 中已不存在——迁移目录下的 20260605120000_model3d_drop_legacy_rating 移除了 rating 列schema.full.prisma 中的Model3DReview只剩recommended/details/metadata等字段。这正是文档schema wins约定的实例。3. 既有表触碰点Touch Points新表如何嵌入旧生态原文档第 2 节的 flowchart 刻画了Model3D与既有实体、外部系统Meilisearch、ClickHouse、S3、Orchestrator的连接方式文档给出的四个关键结论Reaction 复用ImageReaction挂在缩略图Image上没有 Model3D 专属 reaction 表对应 ERD 中reactionCount反规范化自 thumbnailImageMetric下载走 ClickHouse事件不落 Postgres 表Model3DMetric.downloadCount是反规范化聚合值v1 的内容来源只有 orchestrator 的 PolyGen 配方——没有上传路径但 schema 的 nullableworkflowId已为未来的上传流程预留Image有两条指向Model3D的 FK一条是缩略图PolyGen 产物一条是 sourceimage-to-3D 的输入图。迁移 SQL 印证了这些触碰点migration.sql 在既有枚举上追加Model3D值TagTarget、CosmeticEntity、CollectionType、EntityType——最后一个正是 BuzzTip 的entityType通道L361-L362 给CollectionItem加上model3dId外键并级联删除。4. 生成 发布生命周期从 Generate 面板到/3d-models/:id上线原文档第 3 节的完整生命周期图4.1 服务端结果处理器handlePolyGenWorkflowResult的源码印证生命周期中 A4→B5 的服务端段实现于 src/server/services/orchestrator/ecosystems/polyGen.handler.ts。要点常量S3 前缀固定为3d/POLYGEN_S3_PREFIX主格式为glbPRIMARY_FORMAT见 polyGen.handler.ts#L33-L35格式归一化对每个输出 blob 的format做小写并去掉前导点然后按格式建Model3DFile行GLB 标记isPrimary多变体共存一次完整的 rigged animated 生成最多可产出约 12 个文件base / rigged / animated / walking / running 各自的 glb fbx armature靠Model3DFile.variant判别列与(model3dId, format, variant)唯一索引共存——这是迁移 20260617120000_model3dfile_variant 追加的演化原文档图中尚未体现幂等以Model3D.workflowIdUNIQUE为键 upsert重放同一 workflow 只会返回已存在的草稿行缩略图通过标准图片入库流水线createImage建成真正的Image行走 NSFW / CSAM 扫描与图中 B2 步一一对应。4.2 发布门禁publishModel3D的服务端守卫生命周期 C1→D3 的发布动作在服务端有硬性守卫。src/server/services/model3d.service.ts 中的publishModel3D依次校验已删除的行不可发布、发布前必须有 name、发布前必须有缩略图随后才写入status Published与publishedAt。同文件 L710-L714 的注释还说明status的变更只能走专用publish/unpublish/ 审核端点普通 upsert 不能悄悄把草稿发布出去——这保证了图中Model3D stays Draft, no public surface的分支在数据层不可被绕过。此外src/server/routers/model3d.router.ts 的注释表明整组 model3d tRPC 过程都受model3dFeed特性标志门控详情页本身落在 src/pages/3d-models/[id]/与图中End节点的路径一致。5. 详情页读取路径Read Path一次请求扇出七路查询原文档第 4 节的读取路径图设计上的几个值得注意的点Q2 的顺序约束文件行按isPrimary优先排序保证 three.js 查看器V1 节点动态 importGLTFLoader加载 GLB 主文件总能拿到可播放的资产V2 的下载链路闭环文件下拉给出签名 URL下载事件写入 ClickHouse——呼应第 3 节下载不落 Postgres的架构决定downloadCount由Model3DMetricQ3反规范化提供展示Q6 的 Makes/Uses 语义Post.model3dId宽外键把创作者自己的 Post与社区用该 3D 模型生成内容的 Post统一成一条 Makes Uses 轨道V5前端组件对应评论区、审核面板、标签选择器、查看器变体等分别实现在 src/components/Model3D/ 下的Comments/、Reviews/、Tags/、Viewer/子目录与图中 V4–V6 的渲染节点一一对应。6. 交叉参照表每张新表对照既有实体的差异原文档第 5 节的 cross-reference 表完整保留如下——它解释了为什么新建一套表而不是复用Model/ModelFileEntity既有对照物差异Model3DModel无baseModel/ecosystem/ModelType/版本管理多了一个workflowIdModel3DFileModelFileformat是String不是 enum、有isPrimary、(model3dId, format)唯一现为三元组见下Model3DLicenseLicense新增allowPrintFarm、allowRedistribution、isCustomModel3DReviewResourceReview只限定到model3dId无modelVersionIdModel3DReportModelReport形状完全一致Model3DEngagementModelEngagement枚举中去掉了MuteModel3DMetricModelMetricdownloadCount来自 ClickHouse新增评分字段TagsOnModel3DTagsOnModels形状完全一致Model3D↔ThreadModel↔Thread加宽外键列model3dIdmodel3dReviewIdModel3D↔PostModelVersion↔Post加宽外键列Post.model3dIdModel3D↔CollectionItemModel↔CollectionItem新 FK 列 扩展唯一约束Model3DReactionImageReaction删除—— 改为对缩略图 Image 做 reactionModel3DDownloadHistoryDownloadHistory删除—— ClickHouse 事件 Model3DMetric聚合Model3DFileType枚举ModelFile.type删除—— 用format String换取灵活性关于format用自由文本而非枚举的理由迁移 SQL 里写得直白migration.sql#L46-L49Meshy/orchestrator 未来给出的新格式可以不经 schema 迁移直接入库。Model3DLicense独立于既有License表是因为物理打印/资产授权有 AI 模型授权不具备的维度print-farm、redistribution。迁移 SQL 用一条 CHECK 约束强制业务规则允许打印农场 ⇒ 必须允许商用migration.sql#L69-L72并预置了 6 个模板授权CC-BY 4.0 / CC-BY-NC 4.0 / Personal Use Only / No Commercial Print Farm / All Rights Reserved / CustomisCustomtrue时布尔列仅作参考、以licenseDetails自由文本为准见 migration.sql#L364-L376。polyGen.handler.ts 在未指定 license 时回退到最保守的 All Rights Reserved 模板。同段迁移还预置了 12 个 Model3D 起步标签character、creature、environment、prop、vehicle、architecture、furniture、low-poly、stylized、realistic、abstract、sci-fi、fantasy其中 7 个为 category通过Tag.target数组追加Model3D实现与既有标签体系的共用。7. 事实来源与迁移约定为什么这张图够用且会漂移文档结尾给出了完整的source of truth声明这里结合仓库实际路径补全可编辑 schemaprisma/schema.full.prisma本仓库 monorepo 结构下实际位于 packages/civitai-db-schema/prisma/schema.full.prismaschema.prisma是由 scripts/generate-slim-schema.js 自动生成的瘦身版不应直接编辑迁移 SQL 手写位于 packages/civitai-db-schema/prisma/migrations/20260526120000_add_3d_models/migration.sql按 CLAUDE.md 的约定手动应用不走prisma migrate deploy双事务结构的工程细节该迁移文件显式用COMMIT; BEGIN;拆成两个事务migration.sql#L11-L26。原因是 Postgres 要求ALTER TYPE ... ADD VALUE先提交后才能被使用——第 18 节的 Tag 种子要插入Model3D::TagTarget若与第 1 节的ALTER TYPE同事务执行会报unsafe use of new value。文件头注释还说明了该结构对外层包裹事务的应用工具psql / Retool及 autocommit 模式均安全。从后续迁移目录20260605120000_model3d_drop_legacy_rating、20260612120000_model3d_gallery_settings、20260617120000_model3dfile_variant、20260618120000_model3d_category_system_tag等见 packages/civitai-db-schema/prisma/migrations/可以推断该模块在实施期经历了快速迭代rating 列被移除、gallerySettings与variant被加入。阅读本文档图时应把其当作rev 9 设计点的基线字段级细节以 Prisma schema 为准——文档自己也声明了这条规则。8. 小结与延伸阅读docs/3d-models-diagram.md用四张 Mermaid 图 一张交叉参照表完整回答了 3D 模型子域的三个核心问题数据模型8 个新实体Model3D、Model3DFile、Model3DLicense、Model3DReview、Model3DReport、Model3DReviewReport、Model3DEngagement、Model3DMetric、TagsOnModel3D三个刻意不做reaction 表、下载历史表、版本表集成策略最大化复用既有基础设施——Image缩略图/源图双 FK、ImageReaction、Thread/CommentV2、Report判别器、CollectionItem宽外键、Meilisearch 索引、ClickHouse 事件流生命周期PolyGen 生成 → S33d/前缀落盘 → 标准图片扫描 → Draft 入库workflowId幂等→ 用户显式 Post → 发布门禁name 缩略图→ 搜索索引与 Metric 初始化 →/3d-models/:id上线。延伸阅读均在仓库内docs/3d-models-plan.md主设计文档rev 9、docs/3d-models-summary.md、docs/3d-models-implementation-tracker.md实施跟踪、docs/3d-models-followups.md后续事项、docs/model3d-thumbnail-nsfw-propagation.md缩略图 NSFW 传播问题。【免费下载链接】civitaiA repository of models, textual inversions, and more项目地址: https://gitcode.com/GitHub_Trending/ci/civitai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考