civitaisync-account跨域登录同步参数迁移指南从硬编码颜色到useSyncAccount统一封装【免费下载链接】civitaiA repository of models, textual inversions, and more项目地址: https://gitcode.com/GitHub_Trending/ci/civitai本文以 docs/sync-account-utility-migration.md 为骨架结合当前仓库源码完整讲解 civitai 多色彩域名green / blue / red架构下sync-account会话同步参数的迁移方案为何每个跨域链接都要携带该参数、三种硬编码颜色为何都是隐患、新的syncAccountFor/useSyncAccount如何自动推导来源颜色以及 12 个调用点的分桶迁移、验收标准与 2026-08 之后的现状修正。读完本文你将掌握一套可复用的“跨域登录引导参数”收敛方法并能直接对照仓库源码验证每一步行为。背景sync-account参数与多色彩域名架构civitai 的主站按“颜色域名”拆分部署当前ColorDomain只有三种合法取值见 src/shared/constants/domain.constants.tsexport const colorDomainNames [green, blue, red] as const; export type ColorDomain (typeof colorDomainNames)[number];用户会话token保存在某个颜色域名下。当用户从当前域名跳转到另一个颜色域名时目的地需要知道“我的会话在哪个域名上”才能把会话引导过来。这个信息通过 URL 查询参数sync-account传递——参数名本身在 packages/civitai-auth/src/constants.ts 中统一定义export const SYNC_PARAM sync-account;目的地页面加载时src/hooks/useDomainSync.tsx 会读取该参数并启动跨域登录引导const url new URL(window.location.href); const sync url.searchParams.get(SYNC_PARAM); if (!sync) return; isSyncing true; url.searchParams.delete(SYNC_PARAM); const returnUrl ${url.pathname}${url.search}${url.hash}; window.location.replace(/api/auth/authorize?returnUrl${encodeURIComponent(returnUrl)});从源码注释可以看出这条链路的当前形态是sync-account标记存在时页面跳转到/api/auth/authorize经由 auth hub 的 OAuth provider 走标准授权码流程auth-code flow回调后在当前域名换取civ-tokensync-account会被从returnUrl中剥离避免登录落地页再次触发同步造成循环。注意文档写作时提到的旧桥接端点/api/auth/sync从目的地拉 token已随 swap bridge 一起删除现在的引导完全走 OAuth authorize 流程。迁移前的三个硬编码问题在syncAccount工具出现之前每个跨域链接都手工拼接sync-account...颜色值存在三类隐患硬编码值问题green对 .com → .red 的流程是正确的但对 .red → .com 的流程是 no-op来源与目的地同色useDomainSync内host syncDomain会短路blue历史遗留——blue 曾是主域名槽位useDomainSync按serverDomains.blue解析但该 key 是否与serverDomains.red指向同一主机取决于环境配置yellow单个站点硬编码了yellow但它不是合法ColorDomain在useDomainSync内被静默忽略认证交换永远不会发生新工具 src/utils/sync-account.ts 同时解析当前主机与目标 URL 的主机对照配置好的serverDomains映射自动生成正确的来源颜色。新工具syncAccountFor纯函数与useSyncAccountHook文档原始设计中提供的是syncAccount(url, redirectUrl?)其中第二个参数附带sync-redirect参数让目的地完成认证交换后跳转到干净路径。该设计已被后续迭代取代详见文末“现状修正”一节当前推荐 API 是 src/hooks/useSyncAccount.ts 中的useSyncAccount()Hook以及纯函数形态syncAccountFor(url, currentColor, domains)。纯函数syncAccountFor的实现原理src/utils/sync-account.ts 的核心逻辑只有三步export function syncAccountFor( url: string, currentColor: ColorDomain | undefined, domains: ServerDomains | undefined ): string { if (!domains || !currentColor) return url; const urlHost extractHost(url); if (!urlHost) return url; const urlColor hostToColor(urlHost, domains); if (!urlColor || urlColor currentColor) return url; return QS.stringifyUrl({ url, query: { [SYNC_PARAM]: currentColor } }); }前置防御域名映射或当前颜色缺失时原样返回 URL绝不擅自加参数提取主机extractHost用正则^(?:https?:)?\/\/([^/?#])/i同时兼容https://、//协议相对两种写法并统一小写主机反查颜色hostToColor遍历serverDomains的每个颜色条目先比对cfg.primary主域名再比对cfg.aliases别名列表命中即返回该颜色同色短路目标颜色等于当前颜色、或目标主机不属于任何已知颜色域名外部站点、或 URL 是相对路径时URL 原样返回打标否则通过QS.stringifyUrl把{ sync-account: currentColor }合并进既有查询串——已有查询参数如?querycats会被完整保留这正是 src/utils/tests/sync-account.test.ts 中preserves an existing query string用例验证的行为。DomainConfig的结构见 src/shared/constants/domain.constants.ts决定了上述匹配方式export type DomainConfig { primary: string; // 规范主机名所有出站 URL 构造都使用它 aliases: string[]; // 入站请求中解析到同一颜色的其他主机 };为什么颜色必须是显式参数SSR 的教训syncAccount的旧实现从window.location.host推导当前颜色这在服务端渲染SSR下是致命的SSR 期间没有windowsyncAccount(url)只能原样返回 URL于是每个服务端渲染的跨色链接都没有携带标记——用户到达另一个颜色域名后若无本地会话就一直是未登录状态该问题已在生产环境确认只是被 30 天滚动会话 cookie 掩盖了。syncAccountFor把颜色作为显式参数传入从而可以在 SSR 阶段正常工作。而useSyncAccount()则从 React 上下文提供颜色export function useSyncAccount() { const { domain, serverDomains } useAppContext(); const currentColor (Object.keys(domain) as ColorDomain[]).find((color) domain[color]); return useCallback( (url: string) syncAccountFor(url, currentColor, serverDomains), [currentColor, serverDomains] ); }源码注释点明了另一个关键设计理由模块作用域缓存颜色也会出错——同一个 Next.js 进程同时服务所有颜色域名模块级变量会在并发请求间泄漏。所以颜色既不能来自window也不能来自模块作用域只能作为参数传入客户端由 context 供给。测试如何锁定“无浏览器可用”src/utils/tests/sync-account.test.ts 特意声明“测试绝不触碰window”——如果打标逻辑再次悄悄依赖浏览器环境所有用例都会失败。测试域配置与用例要点const domains: ServerDomains { green: { primary: civitai.com, aliases: [] }, red: { primary: civitai.red, aliases: [www.civitai.red] }, blue: { primary: civitai.blue, aliases: [] }, };跨色链接//civitai.red/models/1 来源green→ 追加?sync-accountgreen绝对 URL 与别名主机https://civitai.red/x、//www.civitai.red/x同样打标已有查询串?querycats被保留同色、相对路径、外部主机//example.com/x、颜色未解析、域名映射缺失五种情况均原样返回。迁移方案12 个调用点分四桶收敛文档规划将每个手工拼接sync-account...的调用点迁移到新工具并在一个 PR 内合并。迁移按行为差异分为四个 Bucket。Bucket 1同值迁移无行为变化用户位于 .com链接指向 .red硬编码?sync-accountgreen。新工具从 .com 推导出的正是green纯重构。文件行号改动MatureContentMigrationAlert.tsx63-64用syncAccount(...)包裹//${redDomain}与https://civitai.red兜底去掉硬编码?sync-accountgreenYellowBuzzMigrationNotice.tsx51-55用syncAccount(//${redDomain ?? civitai.red}/, /user/buzz-dashboard)替换syncParamsredUrl。原设计里它是唯一使用sync-redirect的站点把同步后路径作为第二参数传入SensitiveShield.tsx64用syncAccount(\//${redDomain}${router.asPath})替换手工分隔符 sync-accountgreen 拼接需要说明的是YellowBuzzMigrationNotice.tsx 在当前代码中已改用useSyncAccount()第 21 行const syncAccount useSyncAccount();第 45-46 行基于serverDomains.red构造redUrl印证了从文档方案到 Hook 方案的演进。Bucket 2Bug 修复当前值为 no-op硬编码sync-accountgreen却链接到 green 域名本身useDomainSync内部host syncDomain会短路参数今天完全无效。迁移后来源解析为用户真实域名red认证交换真正发生。文件行号改动QueueItem.tsx744pricingHref features.isGreen ? /pricing : syncAccount(\//${serverDomains.green}/pricing)NoCryptoUpsell.tsx33-34greenBuzzUrl syncAccount(\//${greenDomain}/purchase/buzz)greenPricingUrl syncAccount(//${greenDomain}/pricing)Bucket 3sync-accountblue→ 当前来源颜色硬编码blue是历史遗留。迁移后值变为用户当前颜色——从 .com 出发是green同主机短路后甚至会被省略从 .red 出发是red。意图不变“在目的地使用我当前的会话”。文件行号改动buzz.utils.ts27-36useBuyBuzz从查询对象中删除sync-account: blue用syncAccount(...)包裹传给window.open的最终 URLpricing/index.tsx50-61自动重定向 effect同模式——从查询对象删除参数用syncAccount(...)包裹最终 URLYellowMembershipUnavailable.tsx10-13greenPricingUrl syncAccount(\//${serverDomains.green}/pricing?${QS.stringify({ buzzType: green })})BuzzPurchaseImproved.tsx360-373从查询中删除sync-account: blue用syncAccount(...)包裹window.openURLGreenEnvironmentRedirect.tsx41-49handleManualRedirect从查询中删除sync-account: blue用syncAccount(...)包裹window.location.href值MembershipUpsell.tsx107Become a member用syncAccount(pricingUrl)替换?sync-accountblue拼接以当前代码中 buzz.utils.ts 的useBuyBuzz为例迁移后的形态是特性关闭时通过syncAccount(\//${serverDomains.green}/purchase/buzz?${QS.stringify(query)})生成带正确sync-account的购买 URL再window.open(..., _blank, noreferrer)。Bucket 4pages/user/membership.tsx的双重 Bug 修复pages/user/membership.tsx 中的handleRedirectToOtherEnvironment有两个潜伏缺陷从 .red → .com 时发出sync-accountyellow。yellow不是合法ColorDomainuseDomainSync静默放弃认证交换永不发生对 .red 目标使用serverDomains.blue这是“blue 即 red”的历史约定。与 .com→green / .red→red 的映射对齐后应使用serverDomains.red。文档给出的修复是第 132-141 行将函数体替换为const targetDomain otherBuzzType green ? serverDomains.green : serverDomains.red; window.open(syncAccount(//${targetDomain}/user/membership), _blank, noreferrer);当前代码中该页面已改为const syncAccount useSyncAccount();第 145 行并在页内构造跳转 URL与“所有服务端渲染场景用 Hook”的最终结论一致。验证注意点serverDomains.blue→serverDomains.red的替换假设生产环境中两个 key 指向同一主机。若环境配置里二者是不同主机此改动改变的是目标域名而非仅仅是同步参数。合并前务必核对环境变量。明确不迁移的站点文件行号原因LoginContent.tsx53?sync-accountgreen位于一个主机与当前主机相同的返回 URL 上——syncAccount会短路并丢掉参数。这里的意图是“在 green 认证后从 green 同步”即认证后的来源而非用户当前域名工具无法表达这种语义pages/purchase/buzz.tsx18服务端检查只读取参数不写入useDomainSync.tsx—参数的消费方验收标准Bucket 1-4 的全部 12 个站点均使用syncAccount(...)除LoginContent.tsx豁免外仓库中不再残留sync-accountgreen、sync-accountblue、sync-accountyellow字面量pnpm run typecheck通过手工冒烟从 .com 点击 .com → .red 链接仍追加?sync-accountgreen点击同域链接不再追加任何参数。现状修正2026-08 之后文档已被 SUPERSEDED文档头部标注SUPERSEDED (2026-08)12 站点迁移已经落地但代码又发生了几处变化阅读历史迁移记录时必须与现状对齐两个文件已不存在MatureContentMigrationAlert.tsx、SensitiveShield.tsx已从仓库删除没有redirectUrl第二参数 /sync-redirect参数syncAccountFor的签名只有(url, currentColor, domains)目的地不再从/api/auth/sync拉取 token该端点随 swap bridge 一起删除而是启动/api/auth/authorize的 OAuth 授权码流程见 useDomainSync.tsx 源码注释syncAccount(url)不再是推荐 API它从window.location.host推导当前颜色SSR 期间静默 no-op导致每个服务端渲染的跨色链接都不带标记。任何服务端渲染场景应使用 useSyncAccount.ts 的useSyncAccount()纯函数形态请用syncAccountFor(url, colour, domains)。因此这份迁移文档的持久价值在于Bucket 分桶原理与验收标准哪些是纯重构、哪些是修复 no-op、哪些是修 legacy 值而具体落地的 API 形态应以当前源码为准useSyncAccount()syncAccountFor()颜色必须显式传入打标逻辑必须可在无浏览器环境下运行并被测试锁定。【免费下载链接】civitaiA repository of models, textual inversions, and more项目地址: https://gitcode.com/GitHub_Trending/ci/civitai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考