SuperAPI AI 工具集

clerk-reference-architecture

安全与审计

查看项目

更新于 10-15 22:42

技能介绍

用途:为采用 Clerk 认证的应用提供架构级参考模式,适合设计应用架构、规划认证流程或落地企业级认证时参考。先决条件包括了解 Web 应用架构、熟悉 JWT/会话/OAuth 等认证模式,并了解自身技术栈与扩展需求。

主要覆盖四种架构:

  1. Next.js 全栈:通过 clerkMiddleware 在中间件校验会话令牌,服务端组件用 auth()、currentUser() 直接取用户数据,客户端组件用 useUser()、useAuth(),API 路由用 auth() 与 getToken(),并通过 /api/webhooks/clerk 同步用户到数据库。入口用 ClerkProvider 包裹,中间件用 createRouteMatcher 划出公开路由并对其余路由执行 auth.protect()。
  2. 微服务共享认证:由 API Gateway/BFF 生成带服务特定声明的 JWT(getToken({ template: service })),下游 Node.js、Python、Go 服务各自校验 JWT;Express 服务端使用 @clerk/express 的 clerkMiddleware 与 requireAuth(),通过 req.auth.userId 获取身份。
  3. 多租户 SaaS:以 Clerk 组织(orgId)隔离数据,封装 getTenantData 按 orgId 过滤查询;中间件对租户路由强制组织上下文,未选组织时重定向到组织选择页,使用 OrganizationSwitcher 并设置 hidePersonal。
  4. 移动端 + Web 共用后端:Web 用 @clerk/nextjs,移动端用 @clerk/clerk-expo,后端用 @clerk/express,受保护端点通过 requireAuth() 与 getAuth(req) 兼容两端。

文档还给出常见问题处理,如全栈中间件重定向循环需把登录路由加入公开路由、微服务需在 Dashboard 为每个服务创建 JWT 模板、多租户无组织时先重定向到选择器、移动端请求需携带 Authorization: Bearer <token>。并附 Prisma 模型示例,User 含唯一 clerkId 与 email,OrgMembership 以 userId+orgId 唯一约束关联 Clerk 组织 ID 与角色。

限制与缺失:资料未提供收费、价格、平台支持范围、性能指标或完整部署步骤;具体实现细节以 Clerk 官方文档为准。