99 lines
3.3 KiB
Markdown
99 lines
3.3 KiB
Markdown
|
# API Key 认证流程
|
|||
|
|
|
|||
|
|
## 概述
|
|||
|
|
|
|||
|
|
API Key 认证是系统支持的两种认证方式之一（另一种是 JWT）。客户端通过 `X-API-Key` 请求头传递明文 key，中间件负责解析、校验并将认证用户注入到 request attribute 中，供下游中间件和控制器使用。
|
|||
|
|
|
|||
|
|
## API Key 格式
|
|||
|
|
|
|||
|
|
明文格式：`{user_id}#{token}`
|
|||
|
|
|
|||
|
|
- `user_id`：用户 ID（整数）
|
|||
|
|
- `#`：分隔符
|
|||
|
|
- `token`：64 字符十六进制随机串（`bin2hex(random_bytes(32))`）
|
|||
|
|
|
|||
|
|
示例：`42#a3b5c7d9e1f2...`（完整 token 为 64 字符）
|
|||
|
|
|
|||
|
|
数据库仅存储 token 的 SHA-256 哈希值（`key_hash`），不存储明文。明文仅在生成时返回给用户一次。
|
|||
|
|
|
|||
|
|
## 认证流程图
|
|||
|
|
|
|||
|
|
```mermaid
|
|||
|
|
flowchart TD
|
|||
|
|
A["请求进入 AuthMiddleware"] --> B{"有 Bearer Token?"}
|
|||
|
|
B -- 是 --> JWT["JWT 认证路径"]
|
|||
|
|
B -- 否 --> C{"有 X-API-Key 头?"}
|
|||
|
|
C -- 否 --> R401_NO["401 未授权，请先登录"]
|
|||
|
|
C -- 是 --> D["解析明文 key"]
|
|||
|
|
|
|||
|
|
D --> E{"包含 # 分隔符?"}
|
|||
|
|
E -- 否 --> R401_FMT["401 API Key 无效或已过期"]
|
|||
|
|
E -- 是 --> F["拆分 user_id 和 token sha256(token) → key_hash"]
|
|||
|
|
|
|||
|
|
F --> G["查询 api_keys 表WHERE (user_id, key_hash)AND 未过期"]
|
|||
|
|
G --> H{"记录存在?"}
|
|||
|
|
H -- 否 --> R401_KEY["401 API Key 无效或已过期"]
|
|||
|
|
H -- 是 --> I{"key.enabled?"}
|
|||
|
|
|
|||
|
|
I -- false --> R403_KEY["403 该 API Key 已被禁用"]
|
|||
|
|
I -- true --> J["加载关联 user"]
|
|||
|
|
J --> K{"user 存在且user.status = 1?"}
|
|||
|
|
|
|||
|
|
K -- 否 --> R403_USER["403 账号已被禁用"]
|
|||
|
|
K -- 是 --> L{"user.api_key_enabled?"}
|
|||
|
|
|
|||
|
|
L -- false --> R403_FEAT["403 API Key 功能未启用"]
|
|||
|
|
L -- 是 --> M["认证成功"]
|
|||
|
|
|
|||
|
|
M --> N["更新 last_used_at"]
|
|||
|
|
N --> O["注入 request attribute\nauth_user → User\nauth_type → 'api_key'"]
|
|||
|
|
O --> P["写入协程 Context"]
|
|||
|
|
P --> Q["放行到下游 handler"]
|
|||
|
|
|
|||
|
|
style R401_NO fill:#fdd,stroke:#c00
|
|||
|
|
style R401_FMT fill:#fdd,stroke:#c00
|
|||
|
|
style R401_KEY fill:#fdd,stroke:#c00
|
|||
|
|
style R403_KEY fill:#fdd,stroke:#c00
|
|||
|
|
style R403_USER fill:#fdd,stroke:#c00
|
|||
|
|
style R403_FEAT fill:#fdd,stroke:#c00
|
|||
|
|
style M fill:#dfd,stroke:#0a0
|
|||
|
|
style JWT fill:#def,stroke:#08c
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 关键 SQL
|
|||
|
|
|
|||
|
|
解析阶段的数据库查询走 `(user_id, key_hash)` 联合索引，单次精确命中：
|
|||
|
|
|
|||
|
|
```sql
|
|||
|
|
SELECT * FROM api_keys
|
|||
|
|
WHERE user_id = {user_id}
|
|||
|
|
AND key_hash = {hash}
|
|||
|
|
AND (expires_at IS NULL OR expires_at > NOW())
|
|||
|
|
LIMIT 1
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 数据查询汇总
|
|||
|
|
|
|||
|
|
整个认证流程涉及 2 次数据库查询 + 1 次写入：
|
|||
|
|
|
|||
|
|
| 操作 | SQL | 说明 |
|
|||
|
|
|------|-----|------|
|
|||
|
|
| 查找 API Key | `SELECT FROM api_keys WHERE (user_id, key_hash)` | 联合索引精确匹配 |
|
|||
|
|
| 加载关联用户 | `SELECT FROM users WHERE id = {user_id}` | `$api_key->user` 懒加载 |
|
|||
|
|
| 更新使用时间 | `UPDATE api_keys SET last_used_at = NOW()` | 记录最后使用时间 |
|
|||
|
|
|
|||
|
|
## 下游消费
|
|||
|
|
|
|||
|
|
认证完成后，下游代码通过以下方式获取认证用户：
|
|||
|
|
|
|||
|
|
- **中间件**：`$request->getAttribute('auth_user')` 或从 Context 读取
|
|||
|
|
- **控制器**：`$this->getAuthUser()`（AbstractController 提供，含 JWT guard 兜底）
|
|||
|
|
|
|||
|
|
## 相关文件
|
|||
|
|
|
|||
|
|
| 文件 | 职责 |
|
|||
|
|
|------|------|
|
|||
|
|
| `app/Middleware/AuthMiddleware.php` | 认证入口，执行校验链 |
|
|||
|
|
| `app/Model/ApiKey.php` | key 解析、DB 查询、格式定义 |
|
|||
|
|
| `app/Controller/AbstractController.php` | `getAuthUser()` 统一用户获取 |
|