# 密码工具

<!-- Copyright (c) 2021-2026 小蚂蚁云团队 版权所有 -->

:::tip 说明
密码加密使用 Django 内置的 `make_password` 和 `check_password` 函数，基于 PBKDF2 算法（默认工作因子 320000 次迭代）。用户安全信息获取工具位于 `utils/security.py`。
:::

## 加密方案

Django 默认使用 PBKDF2 + SHA256 算法进行密码哈希，内置随机盐值管理：

```
用户密码 + 随机盐 → PBKDF2(SHA256, 320000轮) → 存储哈希值
```

### 加密密码

```python
from django.contrib.auth.hashers import make_password

# 生成密码哈希（自动管理盐值）
hashed = make_password("mypassword")
# 结果格式：pbkdf2_sha256$320000$随机盐$哈希值
```

### 验证密码

```python
from django.contrib.auth.hashers import check_password

# 验证密码是否正确
is_correct = check_password("mypassword", hashed)
# 返回 True 或 False
```

## 存储结构

Django 密码哈希格式：`algorithm$iterations$salt$hash`

```
pbkdf2_sha256$320000$abc123def456$longhashvalue...
```

| 部分 | 说明 |
|------|------|
| `pbkdf2_sha256` | 哈希算法 |
| `320000` | 迭代次数（工作因子） |
| `abc123def456` | 随机盐值 |
| `longhashvalue...` | 哈希结果 |

## 用户安全工具（utils/security.py）

### get_user_id(request)

快速获取当前登录用户的 ID：

```python
from utils.security import get_user_id

def some_view(request):
    user_id = get_user_id(request)
    if user_id:
        # 执行需要用户ID的操作
        create_log(user_id, "操作内容")
```

### get_username(request)

快速获取当前登录用户的真实姓名：

```python
from utils.security import get_username

def add_example(request):
    Example.objects.create(
        name="示例",
        create_user=get_username(request),
        update_user=get_username(request),
    )
```

## JWT Token 工具（utils/jwt.py）

### create_token(payload, timeout)

生成 JWT 访问令牌：

```python
from utils.jwt import create_token

payload = {'userId': 1001, 'username': 'admin', 'realname': '管理员'}
token = create_token(payload, timeout=20)  # 20分钟过期
```

### parse_token(request)

从请求头解析 JWT Token，获取用户信息：

```python
from utils.jwt import parse_token

result = parse_token(request)
if result['code'] == 0:
    user_id = result['data']['userId']
    username = result['data']['username']
    realname = result['data']['realname']
```

### refresh_token(token, extend_minutes)

刷新 JWT 令牌，延长有效期：

```python
from utils.jwt import refresh_token

result = refresh_token(old_token, extend_minutes=30)
if result['code'] == 0:
    new_token = result['data']['access_token']
```

### Token 黑名单

退出登录时将 Token 加入黑名单，使其立即失效：

```python
from utils.jwt import add_token_to_blacklist

# 退出登录时调用
add_token_to_blacklist(token)
```

黑名单使用 Redis 存储，TTL 与 Token 剩余有效期一致，Token 自然过期后黑名单条目自动清除。

## 使用示例

### 登录验证

```python
from django.contrib.auth.hashers import check_password
from utils.jwt import create_token

def login(request):
    data, error = parse_request_body(request)
    username = data.get('username')
    password = data.get('password')

    # 查询用户
    user = User.objects.filter(username=username, is_delete=False).first()
    if not user:
        return R.failed(msg="用户名或密码错误")

    # 验证密码
    if not check_password(password, user.password):
        return R.failed(msg="用户名或密码错误")

    # 生成 Token
    payload = {
        'userId': user.id,
        'username': user.username,
        'realname': user.realname,
    }
    token = create_token(payload)
    return R.ok(data={'access_token': token})
```

### 修改密码

```python
from django.contrib.auth.hashers import make_password, check_password

def reset_password(request):
    # 验证旧密码
    if not check_password(old_password, user.password):
        return R.failed("原密码错误")

    # 生成新密码哈希
    user.password = make_password(new_password)
    user.save()
```

## 安全特性

```
1. 随机盐值：Django 自动为每个密码生成随机盐值，即使两个用户使用相同密码，存储的哈希值也不同
2. 抗彩虹表：每个密码都有独立盐值，无法预计算彩虹表
3. 抗暴力破解：PBKDF2 320000 次迭代，大幅增加暴力破解成本
4. 自适应性：可通过修改迭代次数提升安全性
```

## 总结

密码工具使用 Django 内置的 `make_password`/`check_password`，基于 PBKDF2 + SHA256 算法，自动管理随机盐值。`utils/security.py` 提供 `get_user_id()` 和 `get_username()` 快速获取当前登录用户信息。JWT Token 通过 `utils/jwt.py` 管理，支持生成、解析、刷新和黑名单功能。