Civitai Creator Studio `/models` 页面设计与实现:模型版本化货币化管理全解析
Civitai Creator Studio /models 页面设计与实现:模型版本化货币化管理全解析
本文基于 Civitai 仓库 docs/creator-studio/models.md 展开,深入拆解 Creator Studio 中
/models(模型管理)页面的完整设计:它以「模型为行、版本嵌套其中」的分组表格为骨架,让创作者在每个版本上直接管理许可费(licensing fee)、早鸟/付费访问(early/paid access)与无限期售卖(sell indefinitely),并通过 SvelteKit 服务端加载、form action 与 monetization 模块完成权限内联写入。读完你将掌握:页面布局与组件选型、服务端数据读取模型、四种写操作的表单动作与鉴权边界、各状态机设计,以及 URL 驱动的表格状态与浅路由编辑抽屉等前端工程细节。
1. 页面定位:创作者版本货币化的唯一控制面
/models 是 Creator Studio(creator.civitai.com,SvelteKit spoke 应用)中 v1 优先级最高的页面。它的职责非常聚焦:管理创作者自己模型版本的全部货币化手段,而非通用的模型上传或内容管理。整体实现计划见 docs/creator-studio-plan.md,其中明确 /models 承担「Model management ⭐」:按模型分组(版本嵌套、包含草稿)、每个版本可配置完整早鸟/付费访问、许可费开关与金额(仅会员)、Creator Program 成员的「无限期售卖」,以及次优先级的发布/排期能力。
从 apps/creator-studio/src/routes/(app)/models/+page.server.ts/models/+page.server.ts) 的实现看,页面已经超出原始 v1 设想:除了 setFee(单个版本设置许可费)、bulkSetFee(批量设置)、bulkClearFee(批量清除)外,还实现了 setPaidAccess(单个版本付费访问)、bulkSetPaidAccess、bulkRemovePaidAccess、setUsageControl/bulkSetUsageControl(使用控制:Download vs Generation-only)等一整套写操作——即原始文档中的「早鸟/付费访问配置编辑」在源码中已经落地为完整的 action 集。
2. User story:创作者视角下的页面行为
原文档的用户故事可以还原为以下具体交互:
- 创作者打开
/models,看到自己的模型以行呈现,版本嵌套在模型之下(草稿版本也包含在内)。 - 每个版本上可以管理全部货币化配置:
- 设置/清除许可费(仅会员);
- 编辑早鸟/付费访问配置;
- 作为 Creator Program 成员,可将版本无限期售卖(超出早鸟访问的时间限制)。
- 次要能力:从本页发布版本或排期发布(管理便利性,优先级低于许可费)。
- 所有修改内联保存;创作者能立刻看到费用是 Active(生效)还是暂停状态。
页面的关键取舍在于:这不是分析页——每个模型的收益/用量数据在 docs/creator-studio/analytics.md,这里不接 ClickHouse。
3. Layout 与组件选型:复用 @civitai/ui 而非手写
页面 UI 全部基于 @civitai/ui(shadcn-svelte 原语),文档明确要求「不要手写」。从 apps/creator-studio/src/routes/(app)/models/+page.svelte/models/+page.svelte) 的导入可见实际用到的组件族:
| 文档中的原语 | 源码实际导入(@civitai/ui/components/ui/...) |
用途 |
|---|---|---|
table(data-table) |
card、badge、sheet、popover、select |
按模型分组的嵌套表格容器 |
input(numeric) |
input + 自研 NumberInput.svelte |
费用金额输入 |
checkbox/switch |
checkbox、radio-group |
开关与单选(如使用控制) |
badge |
badge |
费用状态(Active/Off)与访问状态徽标 |
tooltip/sonner |
@civitai/ui/.../sonner 的 toast |
暂停原因说明与保存成功/失败反馈 |
值得注意的实现细节(+page.svelte/models/+page.svelte#L90-L130)):
feeStatus()/feeChip():将fee数值渲染为徽标——null/0显示灰色「Fee off」,有值则通过feeToRatio(fee)还原为N ⚡ / M generations的人类可读比例并标绿;- 访问徽标
accessBadge():permanent为蓝色「Permanent · 价格」,非 permanent 为绿色「Early access · 价格」,两者用不同颜色区分「无限期售卖」与「限时早鸟」两种产品语义; - 状态徽标
statusBadgeCls():Published 绿色、Draft 灰色,让版本状态在扫描行中一眼可辨。
4. 数据读取(服务端):+page.server.ts 的 load 设计
4.1 读取范围
页面数据在服务端加载(kysely 经 @civitai/db),全部限定在 locals.user.id 作用域内。原始文档列出的读取项在源码中全部可找到对应:
- 创作者模型 + 版本(含草稿):
getModelsView()(apps/creator-studio/src/lib/server/models-view.ts)→getCreatorModels()(apps/creator-studio/src/lib/server/models.ts),返回发布状态、licensingFee、paidAccessConfig等;每页条数MODELS_PER_PAGE,分页大小可配置PAGE_SIZE_OPTIONS并持久化到 cookie。 - 会员
tier与 CP 成员资格:resolveMembership()(apps/creator-studio/src/lib/server/membership.ts),从共享会话缓存的SessionUser读取,而非重复查库。 - 额度类数据(实际实现中新增的读取):
resolveTotalScore/resolveCreatorScore(创作者分数)、countPricingSlotsThisMonth(本月已用定价额度)、countActiveEarlyAccessVersions(并发早鸟窗口数)、listPricingSlots(额度历史)。
4.2 会员资格解析的底层原理
membership.ts 是理解页面权限的钥匙:
isMember:tier !== null && tier !== 'free' && !user.memberInBadState——会员状态由 tier 字符串加「坏状态」标记共同决定;isCreatorProgramMember:通过位运算(user.onboarding ?? 0) & CREATOR_PROGRAM_ONBOARDING_FLAG(flag = 16,对应主应用OnboardingSteps.CreatorProgram)解析——这正是文档「Gating」一节中「从onboardingCP flag 解析」的源码实现;- 另有仅限版主使用的测试覆盖 cookie
cs-test-membership,用于在不具备真实 CP 账户时模拟该状态。
4.3 页面不是分析页
/models 的 load 不触碰 ClickHouse;每个模型的收益/用量归属 analytics.md 页面(经由 @civitai/clickhouse 读取日聚合)。这一边界在 creator-studio-plan.md §5.1 中有完整论述:所有收益/分析读 ClickHouse(buzz 服务太慢),而货币化写入则走应用内模块。
5. 写操作:form actions → monetization 模块
所有变更都经由 Creator Studio 的 monetization 模块(src/lib/server/monetization/)执行,直接以 kysely 写 ModelVersion——无 buzz 调用、无 ClickHouse。原文档的操作表与源码的对应关系如下:
| 文档中的 Action | 源码 form action | 底层模块函数 | 关键约束 |
|---|---|---|---|
| Set / adjust / clear licensing fee | setFee |
setLicensingFee(licensing-fee.ts) |
会员专属;分数比例输入;校验边界;暂停时保留数值 |
| 编辑早鸟/付费访问配置 | setPaidAccess |
setPaidAccessConfig(paid-access.ts) |
完整 paidAccessFormSchema;非会员也可编辑(早鸟不受会员门槛限制) |
| Sell access indefinitely | bulkSetPaidAccess(permanent) |
bulkSetPaidAccess |
仅 Creator Program 成员;有月度额度上限 |
| Publish / schedule publish | (原文档为次优先级,尚在开放问题中) | — | B13 仍标注 OPEN |
| 批量设置/清除许可费 | bulkSetFee / bulkClearFee |
bulkSetLicensingFee |
批量选择跨页;确认前预览 |
5.1 许可费写路径的源码级细节
licensing-fee.ts 是许可费的核心实现,几个关键点值得展开:
费用输入模型:licensingFeeRatioSchema 规定费用以「整数值 N ⚡ 每 M 张图」的比例输入(绝不直接输入小数),服务端转换为存储的每图费用(Math.round((buzz / images) * 100) / 100,0.01 精度)。buzz === 0 或空值表示清除费用。图片档位必须来自 FEE_IMAGE_OPTIONS 白名单。这与 creator-studio-plan.md §7.1 的「licensingFee 从 Int 迁移为 0.01 精度 decimal」决策一致。
四层守卫(在模块内部强制执行,与 UI 禁用无关):
- 非商用基础模型:
NON_COMMERCIAL_BASE_MODELS(如Ideogram 4.0)不能携带费用,与主应用nonCommercialBaseModels常量保持同步; - 肖像权(POI):
licensingFeeBlockedFor({ poi })——描绘真实人物的模型不可货币化; - 费用上限:
maxLicensingFeeCeiling(capMediaType(baseModel)),按媒体类型(image/video 等)决定每代费用上限,包内MAX_LICENSING_FEE = 100为每图基准; - 定价资格与月度额度:
assertPricingAllowed()——从未定价到定价消耗额度;已有费用或永久门槛的版本再次编辑/清除不消耗。
权利确认(rights affirmation):首次设置费用前必须勾选确认拥有货币化权利(RIGHTS_AFFIRMATION_REQUIRED_ERROR);确认记录通过 SQL COALESCE("meta", '{}'::jsonb) || {affirmation}::jsonb 合并写入 ModelVersion.meta,避免与主应用共享的 meta 键冲突。费用写入与确认记录、额度记录在同一事务中完成——「费用上线却没有确认记录」正是该功能要杜绝的产物。
所有权校验:每个写操作在 WHERE 子句中双重强制 Model.userId = userId 且 deletedAt is null(ownedVersions()),即「数据来自 owner 作用域读取,写入时再次校验」。
5.2 早鸟/付费访问写路径
setPaidAccess(+page.server.ts/models/+page.server.ts#L436-L519))展示了一条不同的架构路径:写操作转发到主应用的 REST 端点 POST /api/v1/model-versions/early-access(setPaidAccessConfig),Studio 仅转发共享的 .civitai.com 会话 cookie,所有权与所有守卫留在主应用服务中——这与 pre-implementation-decisions.md B12 记录的「全量 parity,已构建并合并」一致。
值得注意的是源码中的模拟分数护栏注释:非版主用户传入模拟 cookie 会被丢弃(!locals.user.isModerator 是让模拟器安全的前提),防止测试工具移动金钱门槛。
5.3 鉴权:禁用是 UX,服务端才是真正的关卡
原文档强调「授权在模块内部断言(禁用的控件只是 UX;服务器会重新检查)」。实现完全印证:
- 费用写入与无限期售卖门槛 = Creator Program 会员(单一门槛,见 pre-implementation-decisions.md B1);
- 访问配置编辑与发布 = 任何已认证的版本所有者;
- 所有权检查 = 每个 action 确认
locals.user.id拥有该版本。
关于「tier vs CP」的门槛演变:原始 models.md 中标注「fee gate 依据 tier、indefinite-sale 依据 CP membership」仍待确认,但 2026-07-09 已定案为统一 CP 门槛(见 creator-studio-plan.md §9「Member gate — DECIDED」),理由是「仅凭 tier 会让全新青铜账户也能给他人模型设置费用门槛,而 CP 需要创作者分数,维持质量门槛」。源码 membership.ts 的 resolveMembership 已按此实现。
6. 状态机设计
原文档定义了五种页面状态,可与源码互证:
| 状态 | 行为 |
|---|---|
| Loading | 骨架行(skeleton);源码中 live ?? data 的 $state 切换实现「filter-as-you-type 只替换查询相关切片,caps/scores 保持不动」的渐进增强 |
| Empty | 无模型 → 友好空态 + 跳转主应用上传的链接 |
| 非会员 / 非 CP | 页面正常加载;费用控件禁用(会员门槛)、sell-indefinitely 禁用(CP 门槛),均带 upsell(JoinUpsell.svelte、CapUpsell.svelte、TierCapsTable.svelte);访问配置编辑保持可用;草稿带 draft 徽标 |
| Fee paused | 会员曾设费用后会员资格失效 → 显示 Paused,数值保留、不收费;割接前的费用显示「not-yet-payable」状态(见 creator-studio-plan.md §7.1 的 active flag 方案) |
| Error | 行内错误 + toast;乐观更新失败回滚 |
关于「Fee paused」,决策记录(pre-implementation-decisions.md A3)明确:在用户层面(创作者活跃会员状态)解析,而非每个 ModelVersion 加标志,避免大规模行更新;读取时判定,无批处理任务。主应用 mini 端点 model-versions/mini/[id].ts 会在命中时检查 hasActiveMembership(userId) 决定费用是否适用。
乐观更新(optimistic money updates)在 pre-implementation-decisions.md 的「Resolved (Justin)」中确认可行,理由是「费用是存储值而非实时扣款」。
7. Gating:单一 CP 门槛
Gating 决策(2026-07-09 定案):所有会员专属操作——设置费用和无限期售卖——统一以 Creator Program 会员为门槛(单一标准,从 onboarding CP flag 解析),而非订阅 tier。其余一切(访问配置、发布)对任何已认证的所有者开放。UI 层(禁用 + tooltip)与服务端重检查双管齐下。详见 pre-implementation-decisions.md B1。
这套设计还有一层微妙的平衡,源码注释点得很透(membership.ts):货币化对达到资格线的每个创作者开放,会员资格只决定每月能设置多少个新价格(monthlyPricingAllowance);而使用控制(generation-only)并非如此开放——非 Download 控制需要主应用 generationOnlyModels 特性,可用性为 ['mod', 'granted', 'gold'],因此在 spoke 中直接重述该常量(GENERATION_ONLY_TIERS = ['gold'])。
8. 共享与交叉引用
- 主应用的内联费用编辑:
ModelVersionUpsertForm在主应用上仍保留,直到模型管理在主站被完全弃用(creator-studio-plan.md §6.2);合并时共用同一模块。 - 跨版本批量费用编辑:见 docs/creator-studio/licensing.md(
?mode=bulk,C2 决策:作为/models的一种模式,共享行组件)。 - 导航项会员感知:
memberOnly通过共享的 apps/creator-studio/src/lib/nav.ts 常量驱动侧边栏与移动端 header,两条导航不会漂移。 - 费用堆叠(stacking)不在此处理:后端已处理(creator-studio-plan.md §7.3)——一个衍生模型的费用堆叠在其基础模型费用之上是后端职责;创作者只需设置自己的许可费。决策 B14 进一步明确:涉及其模型的每个创作者都会得到自己的许可费,它们会堆叠(如 Anima 基础费用 + 微调创作者费用 + LoRA 创作者费用)。
9. 路由与 URL 状态
页面在 URL 状态管理上做得非常完整,这是 SvelteKit 深度链接能力的典型示范:
9.1 表格状态在 URL 中
- 搜索:
?q=; - 筛选:
?status=(all/published/draft)、?fee=set|off、?bm=(基础模型)、?mt=(模型类型)、?access=1(有付费访问)、?usage=download|generation; - 排序:
?sort=recent|name; - 分页:
?page=、?ps=(页大小,写回PAGE_SIZE_COOKIE,一年有效)。
这些参数在 models-view.ts 的 modelsQuerySchema(zod)中定义,由 +page.server.ts 的 load 解析,前端通过 goto('?...', { keepFocus, noScroll }) 更新——可深度链接、重新获取全新数据。特殊的 ?for=sale 参数:由 Sales 页「New sale」跳转而来,服务端据此将列表收窄为可被折扣的版本,并返回 saleOnly 视图状态(受 scheduled-model-sales Flipt 开关门控,且开关同时门控数据读取,避免未迁移环境抛错)。
9.2 分组行与编辑表面
- 分组行:哪些模型展开属于视图状态,保持临时性(或
?open=<modelId>实现可链接展开)。 - 编辑表面:更丰富的按版本编辑器(完整访问配置、发布排期)以 URL 可寻址抽屉 打开(
?version=<id>),通过浅路由(pushState/replaceState,源码导入自$app/navigation)实现——可链接、后退按钮关闭、无页面重载;行内的费用/开关保持内联。 - 乐观更新:货币更新乐观执行、失败回滚(已确认可行——费用是存储值而非实时扣款)。
9.3 分页
offset vs cursor 尚未定案(Justin:「not sure yet」);工程侧推荐 v1 用 offset(可通过 pagination 原语 URL 寻址),版本数过大再评估(pre-implementation-decisions.md C4)。源码目前按 offset 实现(page/ps 参数)。
10. 开放问题
截至原文档撰写时,仍有两个开放问题:
- 访问配置深度——「全部货币化进 studio」意味着在这里暴露完整
earlyAccessConfig(下载 vs 生成价格、试用限制、捐赠目标);需要确认 v1 按字段划分的范围与后续跟进。- 注:此问题已实质解决——pre-implementation-decisions.md B12 记录 2026-07-10 定案「全量 parity」,编辑器已构建并合并,写入经主应用 REST 端点。
- 分页——offset vs cursor(未定)。
已解决(2026-07-09):费用/无限期售卖门槛 = CP 会员(单一门槛);无限期售卖 = 无时间限制的早鸟访问(复用 EA/扩展 earlyAccessConfig,A4/B2);费用暂停在用户层面解析,而非按版本加标志(A3)。详见 pre-implementation-decisions.md。
已解决(Justin):表格按模型分组、版本嵌套 · 显示草稿 · 结算货币非创作者可选(仅 Civitai 在特殊情况下代创作者现金结算)· 乐观更新可行。
11. 从文档到代码:一次端到端验证
将文档与源码对照后,可以画出一条完整的「需求 → 实现」链路:
- 分组表格 + 草稿 → models-view.ts 的查询 +
+page.svelte的嵌套渲染与status筛选; - 许可费(会员) →
setFee/bulkSetFee/bulkClearFee+ licensing-fee.ts 的四层守卫与事务写入; - 早鸟/付费访问 →
setPaidAccess/bulkSetPaidAccess/bulkRemovePaidAccess+ 主应用 REST 端点转发; - 无限期售卖 →
bulkSetPaidAccess的permanent分支,受 CP 门槛与月度定价额度(assertPricingAllowed/recordPricingSlots)约束; - 权限 → membership.ts 的
isCreatorProgramMember位运算解析 + 每个写入的 WHERE 所有权断言; - URL 状态 →
modelsQuerySchema的 zod 校验 +?version=<id>浅路由抽屉。
这份设计文档的价值在于它把「创作者如何靠自己的模型赚钱」这一产品命题,拆解成了可测试、可审计、权限边界清晰的工程规范——而仓库源码证明这些规范不仅停留在纸面,/models 已经是 Creator Studio 中功能最完整的页面之一。