feat(#31): 添加密钥轮换机制支持

- 添加 JWT_SECRET_KEY_OLD 配置项支持双密钥平滑迁移
- 添加 SECRET_ROTATION_DAYS 配置项(默认90天)提示轮换周期
- 创建 docs/KEY-ROTATION.md 密钥轮换操作指南文档
- 包含完整的轮换流程和注意事项

docs/KEY-ROTATION.md

@@ -0,0 +1,109 @@
+# 安全密钥轮换指南
+
+本文档说明如何手动轮换小虾 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)