382 lines
9.6 KiB
Markdown
382 lines
9.6 KiB
Markdown
# Token认证缓存服务使用指南
|
||
|
||
## 概述
|
||
|
||
TokenAuthService是一个专为Laravel Sanctum设计的高性能认证缓存服务，通过智能缓存机制大大减少数据库查询次数，提升API响应速度。
|
||
|
||
## 核心特性
|
||
|
||
### 1. 智能缓存策略
|
||
- **动态缓存时间**：根据token剩余有效期自动调整缓存时间
|
||
- **健康检查**：自动检测缓存可用性，故障时自动回退到数据库
|
||
- **多缓存驱动支持**：支持Redis、文件缓存等多种缓存驱动
|
||
|
||
### 2. 性能优化
|
||
- **减少数据库查询**：相同token的重复验证直接从缓存获取
|
||
- **自动过期管理**：缓存时间不超过token剩余有效期
|
||
- **异常恢复**：缓存失败时自动降级到数据库验证
|
||
|
||
### 3. 安全设计
|
||
- **Token哈希存储**：使用SHA256对token进行哈希后作为缓存键
|
||
- **自动清理**：登出时自动清空相关缓存
|
||
- **状态验证**：验证用户状态（is_active, deleted等）
|
||
|
||
## 架构设计
|
||
|
||
```
|
||
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
|
||
│ HTTP请求 │───▶│ AdminApiAuth │───▶│ TokenAuthService│
|
||
│ │ │ Middleware │ │ │
|
||
└─────────────────┘ └──────────────────┘ └─────────────────┘
|
||
│
|
||
┌─────────────────────────┼─────────────────────────┐
|
||
│ │ │
|
||
▼ ▼ ▼
|
||
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
||
│ 缓存层检查 │ │ 数据库验证 │ │ 缓存管理 │
|
||
│ (Redis/File) │ │ (Sanctum) │ │ (清理/统计) │
|
||
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
||
```
|
||
|
||
## 主要组件
|
||
|
||
### 1. TokenAuthService 认证服务
|
||
|
||
**位置**: `app/Services/Auth/TokenAuthService.php`
|
||
|
||
**核心方法**:
|
||
|
||
#### validateTokenAndGetUser()
|
||
验证token并获取用户信息，支持缓存加速：
|
||
|
||
```php
|
||
public function validateTokenAndGetUser(string $token, string $guard = 'sanctum'): ?User
|
||
```
|
||
|
||
**工作流程**:
|
||
1. 检查缓存健康状态
|
||
2. 尝试从缓存获取用户信息
|
||
3. 缓存未命中时从数据库验证
|
||
4. 成功验证后将结果存入缓存
|
||
|
||
#### calculateCacheTime()
|
||
智能计算缓存时间：
|
||
|
||
```php
|
||
protected function calculateCacheTime(string $token): int
|
||
```
|
||
|
||
**缓存策略**:
|
||
- 基于token剩余有效期的1/4作为缓存时间
|
||
- 最小缓存时间：1分钟
|
||
- 最大缓存时间：30分钟
|
||
- 无过期时间token：默认5分钟
|
||
|
||
#### clearTokenCache()
|
||
清空指定token的缓存：
|
||
|
||
```php
|
||
public function clearTokenCache(string $token): bool
|
||
```
|
||
|
||
#### clearCacheOnLogout()
|
||
登出时清空缓存：
|
||
|
||
```php
|
||
public function clearCacheOnLogout(User $user, ?string $currentToken = null): int
|
||
```
|
||
|
||
### 2. AdminApiAuthenticate 中间件
|
||
|
||
**位置**: `app/Http/Middleware/AdminApiAuthenticate.php`
|
||
|
||
**功能**:
|
||
- 集成TokenAuthService进行认证
|
||
- 提取请求中的Bearer Token
|
||
- 认证失败时返回标准化401响应
|
||
|
||
### 3. AuthController 控制器扩展
|
||
|
||
**新增方法**:
|
||
- `clearAuthCache()` - 缓存清理管理
|
||
- `getCacheStats()` - 缓存统计信息
|
||
|
||
## 使用方法
|
||
|
||
### 1. 基本使用
|
||
|
||
在控制器中注入服务：
|
||
|
||
```php
|
||
<?php
|
||
|
||
namespace App\Http\Controllers;
|
||
|
||
use App\Services\Auth\TokenAuthService;
|
||
use Illuminate\Http\Request;
|
||
|
||
class UserController extends Controller
|
||
{
|
||
public function __construct(
|
||
protected TokenAuthService $tokenAuthService
|
||
) {}
|
||
|
||
public function someMethod(Request $request)
|
||
{
|
||
$token = $request->bearerToken();
|
||
$user = $this->tokenAuthService->validateTokenAndGetUser($token);
|
||
|
||
if (!$user) {
|
||
return response()->json(['error' => 'Invalid token'], 401);
|
||
}
|
||
|
||
// 继续业务逻辑...
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 中间件使用
|
||
|
||
在路由中使用自定义认证中间件：
|
||
|
||
```php
|
||
// routes/admin.php
|
||
Route::middleware('admin.auth')->group(function () {
|
||
Route::get('/users', [UserController::class, 'index']);
|
||
Route::post('/users', [UserController::class, 'store']);
|
||
});
|
||
```
|
||
|
||
### 3. 缓存管理
|
||
|
||
#### 清空当前token缓存
|
||
```bash
|
||
curl -X DELETE http://localhost:8000/admin/auth/cache \
|
||
-H "Authorization: Bearer YOUR_TOKEN" \
|
||
-d '{"type": "current"}'
|
||
```
|
||
|
||
#### 清空用户所有token缓存
|
||
```bash
|
||
curl -X DELETE http://localhost:8000/admin/auth/cache \
|
||
-H "Authorization: Bearer YOUR_TOKEN" \
|
||
-d '{"type": "user"}'
|
||
```
|
||
|
||
#### 清空所有认证缓存（管理员）
|
||
```bash
|
||
curl -X DELETE http://localhost:8000/admin/auth/cache \
|
||
-H "Authorization: Bearer YOUR_TOKEN" \
|
||
-d '{"type": "all"}'
|
||
```
|
||
|
||
#### 获取缓存统计
|
||
```bash
|
||
curl -X GET http://localhost:8000/admin/auth/cache/stats \
|
||
-H "Authorization: Bearer YOUR_TOKEN"
|
||
```
|
||
|
||
### 4. 登出时自动清理
|
||
|
||
在AuthController中，登出方法已自动集成缓存清理：
|
||
|
||
```php
|
||
public function logout(Request $request): JsonResponse
|
||
{
|
||
$user = $request->user();
|
||
$currentToken = $request->bearerToken();
|
||
|
||
// 清空当前token的缓存
|
||
if ($currentToken) {
|
||
$this->tokenAuthService->clearTokenCache($currentToken);
|
||
}
|
||
|
||
// 删除当前使用的token
|
||
$user->currentAccessToken()->delete();
|
||
|
||
return $this->Success(['message' => '登出成功']);
|
||
}
|
||
```
|
||
|
||
## 配置说明
|
||
|
||
### 1. 缓存配置
|
||
|
||
#### 使用Redis缓存（推荐）
|
||
```env
|
||
CACHE_STORE=redis
|
||
REDIS_CLIENT=predis
|
||
REDIS_HOST=127.0.0.1
|
||
REDIS_PORT=6379
|
||
REDIS_PASSWORD=
|
||
```
|
||
|
||
#### 使用文件缓存（开发环境）
|
||
```env
|
||
CACHE_STORE=file
|
||
```
|
||
|
||
### 2. 缓存参数调整
|
||
|
||
在TokenAuthService中可以调整缓存参数：
|
||
|
||
```php
|
||
class TokenAuthService
|
||
{
|
||
const DEFAULT_CACHE_MINUTES = 5; // 默认缓存时间
|
||
const MAX_CACHE_MINUTES = 30; // 最大缓存时间
|
||
const CACHE_PREFIX = 'auth_token:'; // 缓存键前缀
|
||
}
|
||
```
|
||
|
||
## 测试和验证
|
||
|
||
### 1. Web测试界面
|
||
|
||
访问测试页面查看系统状态：
|
||
```
|
||
http://localhost:8000/test-auth-cache
|
||
```
|
||
|
||
### 2. API测试
|
||
|
||
#### 缓存健康检查
|
||
```bash
|
||
curl -X GET http://localhost:8000/admin/auth/cache/test \
|
||
-H "Authorization: Bearer YOUR_TOKEN"
|
||
```
|
||
|
||
响应示例：
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "缓存测试结果",
|
||
"data": {
|
||
"cache_prefix": "auth_token:",
|
||
"default_cache_minutes": 5,
|
||
"max_cache_minutes": 30,
|
||
"cache_available": true,
|
||
"cache_health": true,
|
||
"cache_store": "file"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3. 性能对比
|
||
|
||
**无缓存**（每次数据库查询）:
|
||
- 单次认证: ~50-100ms
|
||
- 100次认证: ~5-10秒
|
||
|
||
**有缓存**（命中缓存）:
|
||
- 单次认证: ~1-5ms
|
||
- 100次认证: ~0.1-0.5秒
|
||
|
||
**性能提升**: 10-20倍
|
||
|
||
## 监控和日志
|
||
|
||
### 1. 日志记录
|
||
|
||
系统会自动记录以下日志：
|
||
|
||
- **缓存命中**: `Log::debug('Token认证使用缓存')`
|
||
- **缓存存储**: `Log::debug('Token认证结果已缓存')`
|
||
- **缓存失败**: `Log::warning('缓存读取失败')`
|
||
- **健康检查**: `Log::error('缓存健康检查失败')`
|
||
|
||
### 2. 监控指标
|
||
|
||
可以通过缓存统计API监控：
|
||
|
||
- 缓存驱动类型
|
||
- 缓存可用性状态
|
||
- 缓存健康状态
|
||
- 缓存配置参数
|
||
|
||
## 故障排查
|
||
|
||
### 1. Redis连接问题
|
||
|
||
**现象**: 系统报Redis连接错误
|
||
**解决方案**:
|
||
1. 确认Redis服务正在运行: `redis-cli ping`
|
||
2. 检查Redis配置: `.env`文件中的Redis参数
|
||
3. 验证网络连接: 防火墙设置
|
||
|
||
**临时方案**: 切换到文件缓存
|
||
```env
|
||
CACHE_STORE=file
|
||
```
|
||
|
||
### 2. 缓存不生效
|
||
|
||
**现象**: 每次都查询数据库
|
||
**排查步骤**:
|
||
1. 检查缓存健康状态: `/admin/auth/cache/stats`
|
||
2. 查看错误日志: `storage/logs/laravel.log`
|
||
3. 验证缓存目录权限: `storage/framework/cache`
|
||
|
||
### 3. 性能问题
|
||
|
||
**现象**: API响应慢
|
||
**优化建议**:
|
||
1. 使用Redis替代文件缓存
|
||
2. 调整缓存时间参数
|
||
3. 监控缓存命中率
|
||
|
||
## 最佳实践
|
||
|
||
### 1. 缓存策略
|
||
- 生产环境使用Redis
|
||
- 开发环境可使用文件缓存
|
||
- 定期清理过期缓存
|
||
|
||
### 2. 安全考虑
|
||
- Token使用SHA256哈希存储
|
||
- 用户状态变更时及时清理缓存
|
||
- 敏感操作不依赖缓存
|
||
|
||
### 3. 性能优化
|
||
- 合理设置缓存时间
|
||
- 监控缓存命中率
|
||
- 避免缓存雪崩
|
||
|
||
## 扩展功能
|
||
|
||
### 1. 自定义缓存键策略
|
||
|
||
```php
|
||
protected function getTokenCacheKey(string $token): string
|
||
{
|
||
// 可以添加用户ID等信息到缓存键
|
||
return self::CACHE_PREFIX . hash('sha256', $token);
|
||
}
|
||
```
|
||
|
||
### 2. 缓存预热
|
||
|
||
```php
|
||
public function warmupCache(User $user, string $token): void
|
||
{
|
||
$cacheKey = $this->getTokenCacheKey($token);
|
||
$cacheMinutes = $this->calculateCacheTime($token);
|
||
Cache::put($cacheKey, $user, now()->addMinutes($cacheMinutes));
|
||
}
|
||
```
|
||
|
||
### 3. 缓存统计增强
|
||
|
||
```php
|
||
public function getCacheHitRate(): float
|
||
{
|
||
// 实现缓存命中率统计
|
||
return $this->cacheHits / ($this->cacheHits + $this->cacheMisses);
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
**维护者**: 开发团队
|
||
**更新时间**: 2024-12
|
||
**版本**: v1.0 |