数据库后端【免费下载链接】convex-backendThe open-source reactive database for app developers项目地址https://gitcode.com/gh_mirrors/co/convex-backend点击查看免费下载AuthKit 是 WorkOS 提供的托管式登录认证服务本文以开源仓库 convex-backend 中convex-setup-auth技能的 workos-authkit.md 参考文档为主线结合仓库内 CLI 源码与 waitlist 示例应用系统讲解在 Convex 应用中接入 WorkOS AuthKit 的完整流程包括 Convex-managed 与既有 WorkOS 团队两条接入路径、convex.json的authKit段配置、WorkOS 环境变量、convex/auth.config.ts的 JWT 校验、前端 Provider 与回调接线以及生产环境与常见坑位。读完本文你将具备从零到生产环境完整落地 Convex WorkOS AuthKit 登录体系的能力。一、为什么选择 WorkOS AuthKit以及两条接入路径1.1 适用场景workos-authkit.md明确指出当应用已经在使用 WorkOS或者用户明确希望使用 AuthKit 时才选择这条路。如果项目尚未选定认证方案convex-setup-auth技能SKILL.md给出的候选还包括 Convex Auth、Clerk、Auth0 和自定义 JWT Provider——WorkOS AuthKit 只是其中的一个分支不应默认选择。在动手之前技能要求先通过仓库信号判断是否已存在认证方案依赖中是否出现workos-inc/*、clerk/*、auth0/*等 Provider 包是否已存在convex/auth.config.ts、认证中间件、Provider 包装组件或登录组件环境变量中是否已有指向某个 Provider 的明显痕迹。若仓库已经存在 WorkOS 配置应当保留现有租户模型tenant model除非用户明确要求变更。1.2 两条接入路径Convex-managed 还是既有 WorkOS 团队这是整个接入流程的第一个分叉点文档要求先确认用户想要哪种路径适用场景关键动作Convex-managed WorkOS 团队用户没有现成 WorkOS 组织希望 Convex 代管运行npx convex dev走交互式引导流程由 Convex 自动完成 AuthKit 环境开通与本地环境变量生成既有 WorkOS 团队用户已有 WorkOS 账号与组织从 WorkOS Dashboard 获取WORKOS_CLIENT_ID与WORKOS_API_KEY用npx convex env set写入 Convex 环境从 CLI 源码看workos.ts 中正是通过backend.get(WORKOS_CLIENT_ID)与backend.get(WORKOS_API_KEY)从 Convex 后端读取凭据并在缺失时给出手动设置WORKOS_CLIENT_ID和WORKOS_API_KEY以及npx convex env set的明确提示——这与参考文档的既有团队路径完全对应。二、整体工作流先读文档、再确认、后动手参考文档给出的 Workflow 是一个强顺序流程核心原则是在写任何设置代码之前先阅读官方指南因为 Provider 的 CLI 与 Convex Auth 内部实现会随版本变化凭记忆编写设置代码极易使用过时模式。整体顺序如下确认用户确实要 WorkOS AuthKit确定要 Convex-managed 团队还是既有 WorkOS 团队询问本次是仅本地local-only还是需要生产就绪production-ready配置阅读官方 Convex 与 WorkOS AuthKit 指南为应用的框架与实际本地端口创建或更新convex.json根据上述选择走正确的设置分支配置 WorkOS 所需环境变量配置convex/auth.config.ts以校验 WorkOS 签发的 JWT接线客户端 Provider 与回调流程验证认证请求能到达 Convex若需要生产就绪覆盖生产 WorkOS 配置仅在应用确实需要一级用户记录时才添加storeUser或users表。其中第 12 条值得特别强调不是每个应用都需要users表。只有需要在 Convex 内部存储与用户身份绑定的业务数据如用户资料、偏好设置时才应引入storeUser或users表。文档多次重复这一原则可见这是最常见的过度设计点。三、convex.jsonAuthKit 配置的一等公民而非可选项参考文档反复强调convex.json不是可选配置。它驱动着重定向 URI、首页 URL、CORS 配置以及本地环境变量生成是托管式 AuthKit 流程的基石。3.1 authKit 段的结构与字段从 CLI 的配置解析源码 config.ts 可以看到authKit段的字段定义redirectUrisstring[]允许的回调重定向 URI 列表appHomepageUrlstring应用首页 URLcorsOriginsstring[]允许的 CORS 来源列表environmentType仅允许出现在prod段源码第 236 行附近的校验逻辑明确authKit.environmentType is only allowed in the prod sectionlocalEnvVars仅支持 dev 部署源码第 261 行附近说明 preview 与 prod 必须直接在部署平台上配置环境变量。配置解析逻辑getAuthKitConfig会优先读取显式的authKit配置若convex.json中缺少该段CLI 会提示从最新模板复制convex.json或添加authKit段config.ts。这从源码层面印证了文档convex.json不是可选项的论断。一个典型的convex.json大致形态如下字段名以仓库源码为准具体值需按你的框架与实际端口填写{ authKit: { dev: { redirectUris: [http://localhost:5173/auth/callback], appHomepageUrl: http://localhost:5173, corsOrigins: [http://localhost:5173] }, prod: { environmentType: production, redirectUris: [https://your-app.example.com/auth/callback], appHomepageUrl: https://your-app.example.com, corsOrigins: [https://your-app.example.com] } } }注意当前仓库中 waitlist 示例应用的 convex.json 仅包含$schema与aiFiles配置尚未启用 AuthKit——它正好可以作为一个接入前的基线状态参考。接入 AuthKit 时需按上述结构补充authKit段。3.2 端口不一致是最隐蔽的坑文档的 Gotchas 部分给出了两个关联性极强的提醒Vite 默认端口 5173 可能被占用如果其他应用正在运行Vite 会回退到其它端口。不能假设默认端口仍然匹配生成的 AuthKit 配置。前端实际端口与 convex.json 不一致的后果托管式 WorkOS 登录流程会指向错误的回调 URL。此时需要更新convex.json、更新本地重定向环境变量并重新运行npx convex dev。3.3 托管式团队convex dev 的交互式引导对于 Convex-managed 团队运行npx convex dev即可走交互式引导流程。CLI 会自动开通/配置 AuthKit 环境为 Vite 应用把VITE_WORKOS_CLIENT_ID、VITE_WORKOS_REDIRECT_URI等本地环境变量写入.env.local。关键提醒convex dev的首次运行是交互式的。如果在非交互式终端中执行应当停下来请用户亲自完成引导提示而不能跳过。这也是技能文档强调交互流程受阻时明确询问用户所需的人工步骤的原因。四、WorkOS 环境变量清单参考文档列出的 WorkOS 相关环境变量分为后端与前端两类环境变量归属说明WORKOS_CLIENT_IDConvex 后端WorkOS 客户端 IDConvex 端 JWT 校验与托管流程必需WORKOS_API_KEYConvex 后端WorkOS API 密钥用于服务端调用 WorkOS APIWORKOS_COOKIE_PASSWORD后端框架相关用于加密 AuthKit 会话 Cookie 的密码至少 32 字节VITE_WORKOS_CLIENT_IDVite 前端前端向 WorkOS 发起登录用的公开客户端 IDVITE_WORKOS_REDIRECT_URIVite 前端前端登录成功后的回调地址NEXT_PUBLIC_WORKOS_REDIRECT_URINext.js 前端Next.js 应用的公开回调地址在既有 WorkOS 团队路径下从 WorkOS Dashboard 获取WORKOS_CLIENT_ID与WORKOS_API_KEY后通过npx convex env set写入 Convex 部署环境。CLI 源码 workos.ts 中给出了明确的命令形态npx convex env set WORKOS_CLIENT_ID $YOUR_CLIENT_ID_HERE npx convex env set WORKOS_API_KEY $YOUR_API_KEY_HERE源码还展示了构建环境变量时的优先级逻辑读取部署环境变量其次回退到process.env.WORKOS_CLIENT_IDworkos.ts并会在凭据不一致时提示用npx convex env remove清理后重新设置workos.ts。核心纪律绝不混用 dev 与 prod 的 WorkOS 凭据或重定向 URI文档明确要求 dev 与 prod 需要不同的客户端 ID / API Key 时务必分开维护。五、convex/auth.config.ts让 Convex 信任 WorkOS 签发的 JWTconvex/auth.config.ts是 Convex 侧认证的信任锚点。它的作用是把 WorkOS 这个 OAuth/OIDC Provider 声明为 Convex 认可的 JWT 签发方之后 Convex 才能校验 WorkOS 签发的令牌并在后端函数中通过ctx.auth.getUserIdentity()暴露用户身份。接入 AuthKit 时该文件需要声明 WorkOS 作为 JWT Provider配置其 issuer签发方域与相关的客户端标识保证与convex.json中authKit段、以及 WorkOS Dashboard 中的客户端配置三者一致。修改convex/auth.config.ts之后必须运行常规的npx convex dev或部署流程让后端同步新配置——这一点在参考文档与技能文档SKILL.md 的 Gotchas 部分中都被反复强调。若 Convex 报no auth provider matched the token首先要核查的就是convex/auth.config.ts与 WorkOS 端的配置是否匹配。六、前端接线Provider、Callback 与 Token 流入6.1 客户端 Provider 与回调前端部分的核心工作有三块安装与框架匹配的 WorkOS SDKReact、Vite、Next.js 等框架包不同包装客户端 Provider在应用根部接入 WorkOS 的认证 Provider把登录状态与令牌管理交给它回调/重定向路由登录成功后 WorkOS 会重定向回应用回调路由需要正确落地Next.js 等需要显式路由的地方尤其如此并把拿到的令牌流转给 Convex。6.2 认证后的后端防护模式接入登录后后端函数必须服务端验证身份而不是信任客户端传入的 userId。技能文档 SKILL.md 给出了一个正反对比示例这个模式对 WorkOS AuthKit 同样适用// Bad: trusting a client-provided userId export const getMyProfile query({ args: { userId: v.id(users) }, handler: async (ctx, args) { return await ctx.db.get(args.userId); }, });// Good: verifying identity server-side export const getMyProfile query({ args: {}, handler: async (ctx) { const identity await ctx.auth.getUserIdentity(); if (!identity) throw new Error(Not authenticated); return await ctx.db .query(users) .withIndex(by_tokenIdentifier, (q) q.eq(tokenIdentifier, identity.tokenIdentifier), ) .unique(); }, });正确模式通过ctx.auth.getUserIdentity()从 Convex 侧验证令牌再基于identity.tokenIdentifier查询用户记录。错误信息应当清晰明确如Not authenticated、Unauthorized而不是含糊的通用异常。6.3 验证的终点是Convex 看到认证状态文档的 Validation 部分给出了明确的验证终点用户能完成登录流程并回到应用回调 URL 与实际前端端口一致本地开发登录成功后 Convex 能收到认证请求即前端不再停留在托管式 WorkOS 页面加载成功这一步——文档特别警告不要以托管式 WorkOS 页面打开了作为完成标志。七、逐步落地两条路径的 Concrete Steps参考文档的 Concrete Steps 可以归纳为如下可执行清单两条路径仅在环境变量来源上分叉选择 Convex-managed 或既有 WorkOS 团队为应用框架创建或更新convex.json的authKit段确保 dev 的redirectUris、appHomepageUrl、corsOrigins以及本地重定向环境变量与应用真实本地端口一致Convex-managed运行npx convex dev并走完交互式引导自动生成本地环境变量既有团队从 WorkOS Dashboard 获取WORKOS_CLIENT_ID与WORKOS_API_KEY用npx convex env set设置创建或更新convex/auth.config.ts配置 WorkOS JWT 校验运行常规npx convex dev或部署流程让后端配置同步生效在应用中接线 WorkOS 客户端 Provider配置回调与重定向处理验证用户能登录并回到应用验证 Convex 在登录后能看到已认证用户若需要生产就绪同步配置生产客户端 ID、API Key、重定向 URI 与部署设置。八、生产环境配置从 dev-only 到 production-ready文档将仅本地与生产就绪视为需要主动询问的分叉而不是默认行为。生产就绪意味着配置生产 WorkOS 客户端 ID、API Key、重定向 URI配置 Convex 生产部署preview/prod的convex.jsonauthKit段包括environmentType字段生产环境变量直接在部署平台上配置而不是依赖convex dev生成的本地.env.local这一点与源码中localEnvVars仅支持 dev的校验逻辑一致在宣布任务完成前逐项验证生产的重定向与回调设置。此外文档有一条流程纪律默认不要把笔记文件静默写入仓库。只有用户明确需要上线/交接文档时才显式创建。九、Gotchas 汇总最容易翻车的 8 个点综合参考文档与技能文档以下是 WorkOS AuthKit 接入中最常见的坑路径分叉不清官方文档将 Convex-managed 与既有团队分开描述不明显时应先问清用户走哪条路dev/prod 配置混淆不同客户端 ID 或 API Key 时保持隔离不混用凭据与重定向 URI过度建模只有应用真正需要一级用户行时才加storeUser或users表已有 WorkOS 配置被破坏仓库已有 WorkOS 设置时保留现有租户模型除非用户要求变更非交互终端的托管引导convex dev首次运行是交互式的非交互终端下应停下来请用户完成提示忽略 convex.json托管流程下它是必需配置驱动重定向、首页 URL、CORS 与本地环境变量生成端口漂移Vite 可能因端口被占而回退到非 5173 端口不能假设默认端口仍匹配生成的配置发现不对就更新convex.json、更新本地重定向环境变量并重新npx convex dev验证停在半路成功的 WorkOS 登录应重定向回本地回调路由并到达 Convex 认证状态而不是停在托管页面加载完成。十、接入完成 Checklist参考文档的最终 Checklist 可作为落地验收标准确认用户需要 WorkOS AuthKit询问是仅本地还是生产就绪选定 Convex-managed 或既有 WorkOS 团队创建或更新convex.json含authKit段配置 WorkOS 环境变量配置convex/auth.config.ts登录后验证认证请求能到达 Convexctx.auth.getUserIdentity()非空若需要配置生产部署延伸阅读技能主文档convex-setup-auth/SKILL.mdProvider 选择流程、后端防护代码模式与整体工作流同目录其他 Provider 参考clerk.md、auth0.md、convex-auth.md用于对比不同认证方案CLI 配置解析源码config.tsauthKit段的字段与校验规则WorkOS 集成实现workos.ts环境变量读写、npx convex env set流程与托管式引导实现示例应用waitlist接入 AuthKit 前的 Vite Convex 应用基线其convex.json、package.json与src/App.tsx可作为改造起点。赞分享数据库后端【免费下载链接】convex-backendThe open-source reactive database for app developers项目地址https://gitcode.com/gh_mirrors/co/convex-backend点击查看免费下载相关推荐Convex 集成 WorkOS AuthKit 完整实战指南从 convex.json 自动配置到 JWT 校验与生产部署Convex 集成 WorkOS AuthKit 完整实战指南从 convex.json 自动配置到 JWT 校验与生产部署 导读 本文基于 convex b数据库后端在 Convex 中集成 WorkOS AuthKit从 convex.json 自动配置到 JWT 校验的完整实战指南在 Convex 中集成 WorkOS AuthKit从 convex.json 自动配置到 JWT 校验的完整实战指南 WorkOS AuthKit 是 C数据库后端Convex Auth在 Convex 后端直接落地的完整认证接入指南convex-backend 仓库实战Convex Auth在 Convex 后端直接落地的完整认证接入指南convex backend 仓库实战 Convex Auth 是 Convex 官数据库后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
