# 安全密钥轮换指南

本文档说明如何手动轮换小虾 SaaS 的安全密钥。

## 概述

为了保障系统安全，建议定期轮换以下密钥：
- `JWT_SECRET_KEY` - JWT 签名密钥

## 配置项

在 `apps/api/app/config.py` 中定义：

```python
# JWT secret key - MUST be set via environment variable, no default allowed
JWT_SECRET_KEY: Optional[str] = None
```

## 轮换流程

### 1. 准备新密钥

生成一个新的强随机密钥（至少 32 字符）：

```bash
# 使用 Python 生成
python3 -c "import secrets; print(secrets.token_urlsafe(48))"

# 或使用 openssl
openssl rand -base64 48
```

### 2. 更新环境变量

在生产/预发布环境中更新环境变量文件：

**`.env.production` / `.env.staging`**：

```bash
# 旧密钥（保留用于平滑迁移期间验证旧 token）
JWT_SECRET_KEY_OLD=your-old-secret-key

# 新密钥
JWT_SECRET_KEY=your-new-secret-key
```

### 3. 通知用户（可选）

如果需要用户重新登录，可以提前发布公告。

### 4. 部署新版本

```bash
# 使用 docker-compose 重启服务
docker-compose down && docker-compose up -d

# 或使用 K8s
kubectl rollout restart deployment/xiaoxia-api
```

### 5. 验证

- 检查服务是否正常启动
- 验证新用户可以正常登录
- 确认 API 请求正常工作

### 6. 清理旧密钥

在确认所有功能正常后，可以移除旧密钥：

```bash
# 编辑 .env.production
# 删除 JWT_SECRET_KEY_OLD 行
```

## 自动轮换支持

当前版本支持在环境变量中同时配置新旧密钥：

```python
JWT_SECRET_KEY: str = os.getenv("JWT_SECRET_KEY")
JWT_SECRET_KEY_OLD: Optional[str] = os.getenv("JWT_SECRET_KEY_OLD")
```

这允许：
1. 先部署新密钥（旧 token 仍可用旧密钥验证）
2. 等待旧 token 自然过期
3. 清理旧密钥

## 推荐的轮换周期

| 环境 | 建议轮换周期 |
|------|-------------|
| 生产环境 | 每 90 天 |
| 预发布环境 | 每 90 天 |
| 开发环境 | 按需 |

## 注意事项

1. **不要在代码中硬编码密钥** - 始终使用环境变量
2. **密钥强度** - 使用至少 32 字符的随机字符串
3. **备份** - 在轮换前确保旧密钥有备份
4. **监控** - 轮换后监控异常登录行为
5. **零停机** - 推荐使用双密钥机制实现平滑迁移

## 相关文档

- [环境配置指南](./ENVIRONMENT-CONFIG.md)
- [生产部署清单](./PRODUCTION-CHECKLIST.md)