# 三大核心功能升级指南

本次升级新增了三个核心功能：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 分支

---

升级完成后，系统将具备更强的性能、安全性和稳定性！