288 lines
6.1 KiB
Markdown
288 lines
6.1 KiB
Markdown
# 三大核心功能升级指南
|
||
|
||
本次升级新增了三个核心功能：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 分支
|
||
|
||
---
|
||
|
||
升级完成后，系统将具备更强的性能、安全性和稳定性！
|