news 2026/9/12 13:41:56

Better Auth 1.7 升级时 OAuth Provider 客户端记录怎么从 oauthApplication 迁移到 oauthClient

作者头像

张小明

前端开发工程师

1.2k 24
文章封面图
Better Auth 1.7 升级时 OAuth Provider 客户端记录怎么从 oauthApplication 迁移到 oauthClient

Better Auth 1.7 升级时 OAuth Provider 客户端记录怎么从 oauthApplication 迁移到 oauthClient

【免费下载链接】better-authThe most comprehensive authentication framework项目地址: https://gitcode.com/GitHub_Trending/be/better-auth

把 Better Auth 从 1.6 升到 1.7 时，OAuth Provider 的客户端存储从oauthApplication表变成oauthClient表，同时会新增一组 token 表，而旧版oauthAccessToken表名会和 1.7 的 token 表冲突。这篇文章只解决一件事：客户端记录这一步数据迁移怎么做。它适用于三类 1.6 环境：使用核心内oidcProvider插件、使用 MCP 插件，或者已经在用@better-auth/oauth-provider。

为什么不能只靠升级命令

1.7 升级指南的 schema 变更表中明确列出：Provider client store 一项是「oauthApplicationbecomesoauthClient, plus new token tables」，手动准备要求是move client data（迁移客户端数据）。

指南同时警告：

  • 升级命令npx auth upgrade只处理包更新，数据库需要单独处理；
  • CLI 会添加表、列和索引，但不会复制 OAuth 客户端记录，也不会把oauthAccessToken.accessToken列改名为token；
  • 必须在应用生成的 1.7 schema之前准备好 OAuth 客户端数据，否则新 token 表建不出来或旧客户端直接丢失。

所以这条迁移路径是：先手动迁数据，再应用 1.7 schema，最后部署 1.7 包和配置。顺序不能反。

迁移前的准备

  • authCLI 要求 Node.js 22.12 或更新版本。
  • 用一条命令把better-auth和所有@better-auth/*包一起升到 1.7，保持 CLI 与库版本一致：
npx auth upgrade

1.7 的oauthClient表结构可以在 OAuth Provider 插件文档 的 Schema 一节查到，迁移时需要重点对齐的字段包括：clientId（唯一标识）、clientSecret、redirectUris（string[]，必填）、tokenEndpointAuthMethod（支持none、client_secret_basic、client_secret_post、private_key_jwt）、grantTypes（支持authorization_code、client_credentials、refresh_token）、responseTypes（支持code）、applicationType（支持web、native）、metadata（json）。

路径一：1.6 核心内 oidcProvider 或 MCP 插件（oauthApplication → oauthClient）

如果你用的是 1.6 的核心内oidcProvider插件或 MCP 插件，按 1.7 升级指南 的 "Migrate OAuth client records" 一节，对每一条oauthApplication记录执行复制或重新注册为oauthClient，并完成以下数据转换：

  1. 字段映射：把redirectUrls映射到redirectUris；把metadata转换为 JSON；为每个客户端设置 grant types 和 token-endpoint authentication method。
  2. 过期旧 access token：迁移客户端之后，让旧的 access token 失效。
  3. 处理旧 token 表：在创建 1.7 的 token 表之前，删除（drop）或重命名（rename）旧的oauthAccessToken表。文档特别指出 CLI 不会替你复制这些记录，也不会把oauthAccessToken.accessToken列改名为token，这一步必须手动完成。

代码配置上，1.7 移除了oidcProvider插件：把来自better-auth/plugins的oidcProvider换成来自@better-auth/oauth-provider的oauthProvider，并把原配置迁移过去。

如果 1.6 时运行的是 MCP 插件，它随 1.7 移到独立的@better-auth/mcp包，文档要求把已注册的客户端走上面这条 OAuth client records 迁移，OAuth 端点从/mcp/*迁到/oauth2/*，发现机制（discovery）的客户端会自动找到新端点。

另外两处与客户端记录直接相关的配置变更：

  • 客户端配置和注册负载里，裸 JWK 数组要换成 JWK Set 对象：jwks: [key]改为jwks: { keys: [key] }。
  • 移除oauthProvider.silenceWarnings选项。

路径二：已在使用 @better-auth/oauth-provider（回填现有 oauthClient 行）

如果你 1.6 时已经用@better-auth/oauth-provider，客户端数据已经在oauthClient表里，要做的不是换表，而是按顺序回填：

  1. 新增三个可空列：applicationType、clientDiscoveryId、clientCredentialsScopes。除非你有可信的 discovery 来源，否则保持clientDiscoveryId为 null。
  2. 把现有的web和native客户端类型映射到applicationType；user-agent-based客户端需要逐个单独审查。tokenEndpointAuthMethod只对公共客户端（public client）设为none，其余方法一律视为 confidential。
  3. 把clientCredentialsScopes设为空数组，再给每个使用client_credentialsgrant 的客户端指派已批准的机器 scope；同时从 provider 配置中移除clientCredentialGrantDefaultScopes。
  4. 在添加复合唯一索引之前，删除同一clientId和resourceId的重复oauthClientResource行。
  5. 回填完成后，删除已被移除的type和public列。

两条路径的公共收尾：JWK Set 格式调整（jwks: [key]→jwks: { keys: [key] }）和移除silenceWarnings选项同样适用。

应用 1.7 schema 并部署

客户端数据迁移完成后再动 schema：

  • 使用内置 Kysely adapter：
npx auth migrate
  • 使用 Drizzle、Prisma 或自定义 schema 工作流：先运行下面命令，审查生成结果，再用你自己的迁移工具应用：
npx auth generate

schema 应用后，把 1.7 包和配置变更一起部署。1.7 发布文章（1.7 发布公告）也强调了同样的顺序：npx auth upgrade之后运行npx auth generate或npx auth migrate，但不要认为生成的迁移就是完整升级——OAuth 客户端这类数据步骤必须人工完成。

验证升级结果

部署 1.7 后，按升级指南的 "Verify the upgrade" 一节验证你的应用实际使用的路径：

  • 作为身份提供方运行时：走一遍 OAuth 授权（authorization）、刷新（refresh）、撤销（revocation）、discovery 和 protected-resource 检查；
  • 运行了 MCP 的场景：连接一个 MCP 客户端并完整走一次受保护请求。

客户端能通过已迁移的oauthClient记录完成授权换 token、刷新 token 且 introspection 正常，说明数据迁移成功。

限制与注意事项

  • 顺序是唯一硬性约束：数据迁移必须在应用 1.7 schema 之前完成，CLI 不会复制客户端记录，也不会把oauthAccessToken.accessToken列改名为token，表名冲突只能手动 drop 或 rename 解决。
  • 1.7 移除了oidcProvider插件，仍在使用它的代码必须在同一批变更里换成@better-auth/oauth-provider，否则部署后无法启动 OAuth 端点。
  • 本文只覆盖客户端记录迁移。1.7 的 account identity（issuer列）、SCIM 重新 provision、Device Authorization 唯一索引等其它手动步骤属于独立任务，参见 1.7 升级指南 的对应章节，按指南中的检查表判断你的项目是否适用。

【免费下载链接】better-authThe most comprehensive authentication framework项目地址: https://gitcode.com/GitHub_Trending/be/better-auth

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：809451989@qq.com进行投诉反馈，一经查实，立即删除！
网站建设 2026/9/12 13:41:03

CEF、Electron、Tauri桌面开发硬边界深度对比

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

作者头像 李华
网站建设 2026/9/12 13:39:48

物联网毕设选题全指南：100个可落地题目与技术选型避坑清单

每年到了做毕业设计的季节，后台和私信里就堆满了类似的提问："学长，物联网毕设题目怎么选啊""有没有那种看起来不水、但又不会把自己做崩的题目""我单片机基础很弱，敢选智能家居吗"。说实话&#xf…

作者头像 李华
网站建设 2026/9/12 13:38:34

SSM框架开发中医知源微信小程序实践

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

作者头像 李华
网站建设 2026/9/12 13:33:16

Koodo Reader 跨平台电子书阅读器快速上手指南

Koodo Reader 跨平台电子书阅读器快速上手指南 【免费下载链接】koodo-reader A modern ebook manager and reader with sync and backup capacities for Windows, macOS, Linux, Android, iOS and Web 项目地址: https://gitcode.com/GitHub_Trending/koo/koodo-reader …

作者头像 李华