# laravel-redis-token

**Repository Path**: yssk/laravel-redis-token

## Basic Information

- **Project Name**: laravel-redis-token
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-04
- **Last Updated**: 2026-01-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

当然可以！以下是根据你提供的详细内容，**优化结构、增强可读性、突出亮点**后的 `README.md` 更新版本。保留了所有技术细节和内部版权信息，同时让文档更专业、清晰、易于使用：

---

# Laravel Redis Token

> 一个基于 Redis 的高性能、安全、可扩展的 Laravel 令牌认证系统，支持访问令牌（Access Token）与刷新令牌（Refresh Token）管理，适用于 API 认证、无状态登录、多设备会话等场景。

[![Production Ready](https://img.shields.io/badge/status-Production%20Ready-brightgreen)](https://github.com/your-org/laravel-redis-token)
[![Test Coverage](https://img.shields.io/badge/tests-37%20tests%20%7C%20249%20assertions-success)](https://github.com/your-org/laravel-redis-token/tree/main/tests)

---

## ✨ 核心优势

- **军工级安全**
    - Refresh Token **一次性使用**（原子化 Lua 脚本保障）
    - **IP 绑定**防止令牌盗用
    - 防载荷注入、速率限制、审计日志
- **极致性能**
    - 毫秒级响应（26k+ TPS 验证吞吐）
    - Redis Pipeline + 请求级内存缓存
    - 内存零泄漏，长期运行稳定
- **Laravel 原生体验**
    - 完美兼容 `Auth::user()`、`auth()->check()`
    - 提供自定义 Guard 驱动 `redis-token`
    - 中间件自动注入用户上下文
- **企业级运维支持**
    - 批量撤销、按用户登出、过期阈值检测
    - 完整测试覆盖（含令牌泄露模拟）
    - 可配置前缀、长度、TTL、速率策略

---

## 📦 安装

### 1. 添加包到项目

```bash
mkdir -p packages
cp -r /path/to/laravel-redis-token packages/
```

### 2. 配置 Composer 自动加载

在项目根目录 `composer.json` 中添加：

```json
{
    "repositories": [
        {
            "type": "path",
            "url": "./packages/laravel-redis-token"
        }
    ],
    "require": {
        "sysc/laravel-redis-token": "*"
    },
    "autoload": {
        "psr-4": {
            "Sysc\\LaravelRedisToken\\": "packages/laravel-redis-token/src/"
        }
    }
}
```

### 3. 安装依赖

```bash
composer install
composer dump-autoload
```

### 4. 注册服务提供者

#### Laravel 8 及以下（`config/app.php`）：
```php
'providers' => [
    // ...
    Sysc\LaravelRedisToken\RedisTokenServiceProvider::class,
],
```

#### Laravel 9+（`bootstrap/providers.php`）：
```php
return [
    // ...
    Sysc\LaravelRedisToken\RedisTokenServiceProvider::class,
];
```

---

## ⚙️ 配置

### 发布配置文件
```bash
php artisan vendor:publish --tag=token-config
```
生成：`config/token.php`

### 关键配置项说明
```php
return [
    'ip_binding' => true,                           // 启用 IP 绑定（推荐开启）
    'access_expires' => 3600,                       // Access Token 有效期（1小时）
    'refresh_expires' => 604800,                    // Refresh Token 有效期（7天）
    'access_length' => 64,                          // Token 长度（建议 ≥64）
    'refresh_length' => 128,

    'rate_limit_max_attempts' => 5,                 // 速率限制：5次/15分钟
    'expiring_threshold' => 300,                    // “即将过期”判断阈值（5分钟）

    'user_model' => App\Models\User::class,         // 用户模型
    'audit_log_enabled' => true,                    // 是否记录审计日志
];
```

> ⚠️ **生产环境提示**：若使用反向代理（Nginx/CDN），请确保正确配置 `TrustProxies` 中间件以传递真实 IP。

---

## 🧩 快速使用

### 1. 在 User 模型中引入 Trait
```php
// app/Models/User.php
use Sysc\LaravelRedisToken\Traits\TokenAuthUser;

class User extends Authenticatable
{
    use TokenAuthUser;
}
```

### 2. 生成令牌（登录）
```php
$tokens = auth()->guard('api')->login($user, $request->ip());
// 返回 ['access_token' => '...', 'refresh_token' => '...']
```

### 3. 刷新令牌
```php
$newTokens = auth()->guard('api')->refresh($refreshToken, $request->ip());
// 旧 refresh token 自动失效
```

### 4. 用户登出
```php
auth()->guard('api')->logout(); // 撤销当前会话
// 或
auth()->guard('api')->logoutAll(); // 撤销该用户所有设备会话
```

---

## 🔒 路由保护

### 注册中间件（`bootstrap/app.php`）
```php
->withMiddleware(function (Middleware $middleware) {
    $middleware->alias([
        'auth.token' => \Sysc\LaravelRedisToken\Http\Middleware\AuthenticateWithToken::class,
    ]);
})
```

### 应用中间件
```php
Route::middleware('auth.token')->group(function () {
    Route::get('/profile', fn () => Auth::user());
    Route::post('/logout', fn () => auth()->guard('api')->logout());
});
```

> ✅ 自动从 `Authorization: Bearer <token>` 头提取并验证令牌。

---

## 🔌 推荐：使用 Laravel Guard 集成

### 配置 Guard（`config/auth.php`）
```php
'guards' => [
    'api' => [
        'driver' => 'redis-token',  // ← 关键
        'provider' => 'users',
    ],
],
```

### 使用标准 Auth 方法
```php
// 控制器中
if (auth('api')->check()) {
    $user = auth('api')->user();
}

// 或 Facade
Auth::guard('api')->id();
```

> 💡 完全兼容 Laravel 授权策略、中间件、队列等生态。

---

## 🗃️ Redis 数据结构

| 键模式 | 类型 | 说明 |
|--------|------|------|
| `access_token:{token}` | Hash | `{ user_id, ip, payload, created_at }` |
| `refresh_token:{token}` | Hash | 同上 |
| `user_access_tokens:{user_id}` | Set | 用户所有 Access Token |
| `user_refresh_tokens:{user_id}` | Set | 用户所有 Refresh Token |
| `rate_limit:{key}` | String | 速率计数器（带 TTL） |
| `audit:token:{YYYY-MM-DD}` | List | 审计日志（可选） |

> 所有键自动设置 TTL，无需手动清理。

---

## 🧪 测试验证

运行全部测试：
```bash
php artisan test packages/laravel-redis-token/
```

✅ **已通过以下关键场景验证**：
- Refresh Token 一次性使用（高并发）
- 令牌泄露模拟（IP 绑定、登出失效、无效令牌拦截）
- 6万+ 操作稳定性测试（0 异常）
- ULID/UUID/整数 ID 兼容性
- 内存效率与批量操作性能

---

## ⚠️ 注意事项

1. **Redis 依赖**：确保 `.env` 中 Redis 配置正确。
2. **IP 绑定**：生产环境务必配置 `TrustProxies`。
3. **前端配合**：刷新令牌后需立即更新本地存储。
4. **审计日志**：高并发下建议定期归档或关闭。
5. **TLS 强制**：**必须在 HTTPS 下使用**，避免令牌明文传输。

---

## 📜 许可证

> 本项目为 **PetroChina 内部使用组件**，版权归 PetroChina 所有。
> 未经系统架构组（SysC Team）书面许可，禁止对外分发或用于非授权项目。

---

## 📞 支持

如有问题，请联系：**系统架构组（SysC Team）**

---

> ✅ **你已拥有一个经过工业级压力与安全验证的 Laravel Token 认证解决方案。**
> 开箱即用，生产就绪！🚀