​

JWT 服务认证

​

概述

• 用户认证: Better Auth (Session-based) — 详见 Web 认证
• 服务认证: JWT + JWKS (Stateless)

​

认证架构

​

为什么需要双层认证

用户 → Web → ai-backend
              ↑
              任何人都可以直接调用！

用户 → Web (用户认证) → ai-backend (服务认证)
                         ↑
                         只接受来自 Web 的请求

​

JWT 工作原理

​

Token 获取流程

1. 用户登录 → Better Auth 创建 Session
2. 调用 /api/auth/token → Better Auth 签发 JWT
3. Web API 使用 JWT → 调用 ai-backend
4. ai-backend 验证 JWT → 通过 JWKS 验证签名

​

Token 结构

eyJhbGciOiJFZERTQSJ9.eyJ1c2VySWQiOiJ1c2VyX2FiYzEyMyJ9.signature
│                    │                                    │
│                    │                                    └─ 签名（EdDSA）
│                    └─ Payload（用户数据）
└─ Header（算法信息）

​

JWKS 验证流程

1. 提取 Token：从 Authorization: Bearer <token> 头部提取
2. 获取 JWKS：从 /api/auth/jwks 获取公钥（带缓存）
3. 查找密钥：根据 Token Header 中的 kid 查找对应公钥
4. 验证签名：使用公钥验证 Token 未被篡改
5. 检查过期：验证 Token 未过期
6. 返回用户信息：提取 userId, email, name

​

受保护的 API

​

需要 JWT 认证

​

不需要 JWT 认证

​

安全最佳实践

​

1. 非对称加密

• 后端无需共享密钥
• 私钥只在 Web 端
• 支持密钥轮换

​

2. 密钥轮换

• 轮换周期：30 天
• 旧密钥保留：30 天

​

3. Token 有效期 (双 Token 机制)

• accessToken 过期前 5 分钟自动刷新
• 刷新失败（refreshToken 过期）自动退出登录
• refreshToken 以 SHA-256 哈希存储在数据库中

​

Token 刷新流程

​

Refresh Token 安全

• 哈希存储：数据库只存储 SHA-256 哈希，即使泄漏也无法直接使用
• 级联删除：用户删除时自动清理所有 refreshToken 记录
• 单独作废：可按用户 ID 批量吊销所有 refreshToken

​

4. JWKS 缓存

• 缓存时间：1 小时
• 密钥轮换时自动刷新

​

5. 传输安全

• 生产环境必须使用 HTTPS
• Token 只在 HTTP Header 中传输
• 不要在 URL 中传递 Token