Audit Bot
401564f9f2
- 添加 JWT_SECRET_KEY_OLD 配置项支持双密钥平滑迁移 - 添加 SECRET_ROTATION_DAYS 配置项(默认90天)提示轮换周期 - 创建 docs/KEY-ROTATION.md 密钥轮换操作指南文档 - 包含完整的轮换流程和注意事项
110 lines
2.4 KiB
Markdown
Executable File
110 lines
2.4 KiB
Markdown
Executable File
# 安全密钥轮换指南
|
||
|
||
本文档说明如何手动轮换小虾 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)
|