Audit Bot
401564f9f2
- 添加 JWT_SECRET_KEY_OLD 配置项支持双密钥平滑迁移 - 添加 SECRET_ROTATION_DAYS 配置项(默认90天)提示轮换周期 - 创建 docs/KEY-ROTATION.md 密钥轮换操作指南文档 - 包含完整的轮换流程和注意事项
2.4 KiB
Executable File
2.4 KiB
Executable File
安全密钥轮换指南
本文档说明如何手动轮换小虾 SaaS 的安全密钥。
概述
为了保障系统安全，建议定期轮换以下密钥：
JWT_SECRET_KEY- JWT 签名密钥
配置项
在 apps/api/app/config.py 中定义：
# JWT secret key - MUST be set via environment variable, no default allowed
JWT_SECRET_KEY: Optional[str] = None
轮换流程
1. 准备新密钥
生成一个新的强随机密钥（至少 32 字符）：
# 使用 Python 生成
python3 -c "import secrets; print(secrets.token_urlsafe(48))"
# 或使用 openssl
openssl rand -base64 48
2. 更新环境变量
在生产/预发布环境中更新环境变量文件：
.env.production / .env.staging：
# 旧密钥（保留用于平滑迁移期间验证旧 token）
JWT_SECRET_KEY_OLD=your-old-secret-key
# 新密钥
JWT_SECRET_KEY=your-new-secret-key
3. 通知用户（可选）
如果需要用户重新登录，可以提前发布公告。
4. 部署新版本
# 使用 docker-compose 重启服务
docker-compose down && docker-compose up -d
# 或使用 K8s
kubectl rollout restart deployment/xiaoxia-api
5. 验证
- 检查服务是否正常启动
- 验证新用户可以正常登录
- 确认 API 请求正常工作
6. 清理旧密钥
在确认所有功能正常后，可以移除旧密钥：
# 编辑 .env.production
# 删除 JWT_SECRET_KEY_OLD 行
自动轮换支持
当前版本支持在环境变量中同时配置新旧密钥：
JWT_SECRET_KEY: str = os.getenv("JWT_SECRET_KEY")
JWT_SECRET_KEY_OLD: Optional[str] = os.getenv("JWT_SECRET_KEY_OLD")
这允许：
- 先部署新密钥（旧 token 仍可用旧密钥验证）
- 等待旧 token 自然过期
- 清理旧密钥
推荐的轮换周期
| 环境 | 建议轮换周期 |
|---|---|
| 生产环境 | 每 90 天 |
| 预发布环境 | 每 90 天 |
| 开发环境 | 按需 |
注意事项
- 不要在代码中硬编码密钥 - 始终使用环境变量
- 密钥强度 - 使用至少 32 字符的随机字符串
- 备份 - 在轮换前确保旧密钥有备份
- 监控 - 轮换后监控异常登录行为
- 零停机 - 推荐使用双密钥机制实现平滑迁移