功能细节优化

backend/UPGRADE_GUIDE.md

@@ -0,0 +1,287 @@
+# 三大核心功能升级指南
+
+本次升级新增了三个核心功能：Redis 缓存层、统一鉴权机制、统一异常处理中间件。
+
+## 1. 安装新依赖
+
+```bash
+cd backend
+source .venv/bin/activate  # 激活虚拟环境
+pip install -r requirements.txt
+```
+
+新增的依赖包：
+- `redis>=5.0.0` - Redis 客户端
+- `python-jose[cryptography]>=3.3.0` - JWT Token 生成和验证
+- `passlib[bcrypt]>=1.7.4` - 密码哈希
+- `python-multipart>=0.0.9` - 表单数据解析
+
+## 2. 安装和启动 Redis（WSL）
+
+```bash
+# 安装 Redis
+sudo apt update
+sudo apt install -y redis-server
+
+# 启动 Redis
+sudo service redis-server start
+
+# 验证 Redis 是否运行
+redis-cli ping
+# 应返回 PONG
+```
+
+## 3. 配置环境变量
+
+编辑 `backend/.env` 文件，添加以下配置：
+
+```bash
+# ============ Redis 缓存配置 ============
+REDIS_HOST=localhost
+REDIS_PORT=6379
+REDIS_DB=0
+REDIS_PASSWORD=  # 可选，如果设置了密码则填写
+
+# ============ 认证系统配置 ============
+# JWT 密钥（务必修改为强随机字符串）
+SECRET_KEY=your-secret-key-change-in-production
+
+# Token 过期时间（分钟，默认7天）
+ACCESS_TOKEN_EXPIRE_MINUTES=10080
+
+# API Key（可选，用于外部调用，逗号分隔）
+API_KEYS=
+
+# 默认管理员账号
+DEFAULT_ADMIN_USERNAME=admin
+DEFAULT_ADMIN_PASSWORD=admin123
+```
+
+### 生成安全的 SECRET_KEY
+
+```bash
+python -c "import secrets; print(secrets.token_urlsafe(32))"
+```
+
+将输出的字符串替换 `SECRET_KEY` 的值。
+
+## 4. 初始化数据库（创建用户表和默认管理员）
+
+```bash
+cd backend
+source .venv/bin/activate
+python cli.py init
+```
+
+你会看到类似输出：
+```
+✓ 创建默认管理员: admin
+init done
+```
+
+## 5. 启动服务
+
+```bash
+# 确保 PostgreSQL 和 Redis 都在运行
+sudo service postgresql start
+sudo service redis-server start
+
+# 启动 FastAPI 服务
+cd backend
+source .venv/bin/activate
+python main.py
+```
+
+启动日志应包含：
+```
+✓ Redis 已连接: localhost:6379
+✓ 管理员账号已存在: admin
+[startup] db + scheduler + auth ready
+```
+
+## 6. 测试功能
+
+### 测试健康检查（查看 Redis 和鉴权状态）
+
+```bash
+curl http://localhost:8000/api/health
+```
+
+应返回：
+```json
+{
+  "ok": true,
+  "akshare": true,
+  "redis": true,
+  "auth": true
+}
+```
+
+### 测试登录
+
+```bash
+curl -X POST http://localhost:8000/api/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"username":"admin","password":"admin123"}'
+```
+
+应返回 Token：
+```json
+{
+  "ok": true,
+  "access_token": "eyJ0eXAiOiJKV1QiLCJhb...",
+  "token_type": "bearer",
+  "username": "admin",
+  "is_admin": true
+}
+```
+
+### 测试受保护的接口
+
+```bash
+# 使用上一步获取的 Token
+curl -X GET http://localhost:8000/api/admin/status \
+  -H "Authorization: Bearer YOUR_TOKEN_HERE"
+```
+
+### 测试 Redis 缓存
+
+```bash
+# 第一次请求（缓存未命中，较慢）
+time curl http://localhost:8000/api/indices
+
+# 第二次请求（缓存命中，应该快很多）
+time curl http://localhost:8000/api/indices
+```
+
+## 7. 修改默认密码（重要！）
+
+首次登录后，立即修改默认密码：
+
+```bash
+curl -X POST http://localhost:8000/api/auth/change-password \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"old_password":"admin123","new_password":"your-new-strong-password"}'
+```
+
+## 8. 常见问题
+
+### Redis 连接失败
+
+如果看到以下日志：
+```
+✗ Redis 连接失败，缓存已禁用: ...
+```
+
+**解决方法**：
+```bash
+# 检查 Redis 是否运行
+sudo service redis-server status
+
+# 如果未运行，启动它
+sudo service redis-server start
+```
+
+**注意**：Redis 连接失败不会影响系统运行，会自动降级到内存缓存。
+
+### 401 Unauthorized 错误
+
+如果访问管理接口返回 401：
+```json
+{"detail":"未认证，请先登录"}
+```
+
+**原因**：该接口需要认证
+
+**解决方法**：
+1. 先调用 `/api/auth/login` 获取 Token
+2. 在请求头中加入 `Authorization: Bearer YOUR_TOKEN`
+
+### WSL 重启后服务启动失败
+
+WSL 每次重启后需要手动启动服务：
+
+```bash
+# 一键启动所有服务
+sudo service postgresql start && \
+sudo service redis-server start && \
+cd /mnt/e/project/stock_cs_v1/backend && \
+source .venv/bin/activate && \
+python main.py
+```
+
+## 9. 功能详细说明
+
+### Redis 缓存优势
+
+- **持久化**：服务重启后缓存不丢失
+- **跨进程**：多个进程可共享缓存
+- **性能提升**：大幅减少 AkShare API 调用，响应速度提升 10-100 倍
+- **自动降级**：Redis 不可用时自动使用内存缓存
+
+### 鉴权机制
+
+**支持两种认证方式**：
+
+1. **JWT Token**（推荐用于前端）
+   - 登录后获取 Token
+   - Token 有效期 7 天（可配置）
+   - 在 HTTP Header 中传递：`Authorization: Bearer TOKEN`
+
+2. **API Key**（推荐用于外部系统）
+   - 在 `.env` 中配置 `API_KEYS`
+   - 在 HTTP Header 中传递：`X-API-Key: YOUR_API_KEY`
+
+**受保护的接口**：
+- `/api/admin/*` - 需要管理员权限
+- 其他接口暂不需要认证（可根据需要扩展）
+
+### 异常处理
+
+系统现在会返回友好的错误信息：
+
+```json
+{
+  "success": false,
+  "error": "数据源异常，请稍后重试",
+  "code": 503
+}
+```
+
+错误类型：
+- **400** - 业务逻辑错误
+- **401** - 未认证
+- **403** - 权限不足
+- **422** - 请求参数错误
+- **500** - 服务器内部错误
+- **503** - 数据源不可用
+
+## 10. 升级检查清单
+
+- [ ] 安装新依赖包
+- [ ] 安装并启动 Redis
+- [ ] 配置 `.env` 文件（Redis + 鉴权配置）
+- [ ] 生成安全的 `SECRET_KEY`
+- [ ] 运行 `python cli.py init` 创建用户表
+- [ ] 启动服务并验证功能
+- [ ] 测试登录和受保护接口
+- [ ] 修改默认管理员密码
+- [ ] 检查 Redis 缓存是否生效
+
+## 11. 回退方案
+
+如果升级后遇到问题，可以临时禁用新功能：
+
+1. **禁用 Redis 缓存**：停止 Redis 服务，系统会自动降级到内存缓存
+   ```bash
+   sudo service redis-server stop
+   ```
+
+2. **禁用鉴权**：暂时注释掉 `main.py` 中受保护接口的 `Depends(require_auth)` 参数
+
+3. **完整回退**：切换到升级前的 git 分支
+
+---
+
+升级完成后，系统将具备更强的性能、安全性和稳定性！