Skip to main content
WorldMonitor 使用 Clerk 进行身份验证。认证系统将高级面板置于登录与层级检查之后,并通过本地 JWT 验证在服务端 API 端点上强制执行基于会话的访问控制。

认证技术栈

关键文件


面板门控

高级面板在用户满足访问要求之前,会显示 CTA 遮罩层而非内容。

门控原因

如何配置哪些面板为高级面板

三个文件控制门控。添加或移除高级面板时,三者必须保持同步。

1. 面板配置 — src/config/panels.ts

在相关变体的面板条目中添加 premium: 'locked'

2. 客户端门控集合 — src/app/panel-layout.ts

将面板键添加到 WEB_PREMIUM_PANELS
此集合驱动响应式 UI 门控 — 当认证状态变化时,该集合中的面板会被检查,并相应地显示/隐藏 CTA。

3. 服务端 API 强制执行(如果面板调用高级 API)

客户端 Token 注入src/services/runtime.tsWEB_PREMIUM_API_PATHS):
当 fetch 请求匹配此集合中的路径且用户拥有 Clerk 会话时,客户端会自动注入 Authorization: Bearer <token> 服务端网关server/gateway.tsPREMIUM_RPC_PATHS):
网关通过本地 JWKS 验证(jose)校验 Bearer Token,并检查 session.role === 'pro'。如果用户不是 pro,则返回 403。

当前受门控的面板

桌面端行为

在 Tauri 钥匙串中拥有有效 WORLDMONITOR_API_KEY 的桌面端用户可绕过所有面板门控。现有的 API 密钥流程不受影响 — Bearer Token 是第二条认证路径,而非替代方案。

服务端会话强制执行

Vercel API 网关为高级端点接受两种形式的身份验证:
  1. 静态 API 密钥X-WorldMonitor-Key 头(现有流程,未变更)
  2. Bearer TokenAuthorization: Bearer <clerk_jwt>(用于 Web 用户)
网关首先尝试 API 密钥。如果在高级端点上失败,则回退到使用 server/auth-session.ts 进行本地 JWKS 验证的 Bearer Token 校验。JWT 验证依据:
  • 签发方CLERK_JWT_ISSUER_DOMAIN
  • 受众convex(与 Clerk JWT 模板匹配)
  • 签名:通过 Clerk 发布的 JWKS 使用 RSA256
非高级端点不需要来自 Web 来源的任何身份验证。

环境变量


用户角色

用户角色(pro / free)存储为 Clerk JWT 中的 plan 声明。服务端从已验证的 Token 负载中提取此值。未知或缺失的 plan 值默认为 free(安全失败 — 绝不会默认为 pro)。 在客户端,getAuthState().user?.role 暴露该角色。isProUser()hasPremiumAccess() 都会检查此值以及旧版 API 密钥门控。