admin/stock_cursor_v0

Fork 0

Files

Lukas 964c17c200 功能细节优化

2026-06-15 01:26:39 +08:00

6.1 KiB

Raw Permalink Blame History

三大核心功能升级指南

本次升级新增了三个核心功能：Redis 缓存层、统一鉴权机制、统一异常处理中间件。

1. 安装新依赖

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）

# 安装 Redis
sudo apt update
sudo apt install -y redis-server

# 启动 Redis
sudo service redis-server start

# 验证 Redis 是否运行
redis-cli ping
# 应返回 PONG

3. 配置环境变量

编辑 backend/.env 文件，添加以下配置：

# ============ 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

python -c "import secrets; print(secrets.token_urlsafe(32))"

将输出的字符串替换 SECRET_KEY 的值。

4. 初始化数据库（创建用户表和默认管理员）

cd backend
source .venv/bin/activate
python cli.py init

你会看到类似输出：

✓ 创建默认管理员: admin
init done

5. 启动服务

# 确保 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 和鉴权状态）

curl http://localhost:8000/api/health

应返回：

{
  "ok": true,
  "akshare": true,
  "redis": true,
  "auth": true
}

测试登录

curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'

应返回 Token：

{
  "ok": true,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhb...",
  "token_type": "bearer",
  "username": "admin",
  "is_admin": true
}

测试受保护的接口

# 使用上一步获取的 Token
curl -X GET http://localhost:8000/api/admin/status \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

测试 Redis 缓存

# 第一次请求（缓存未命中，较慢）
time curl http://localhost:8000/api/indices

# 第二次请求（缓存命中，应该快很多）
time curl http://localhost:8000/api/indices

7. 修改默认密码（重要！）

首次登录后，立即修改默认密码：

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 连接失败，缓存已禁用: ...

解决方法：

# 检查 Redis 是否运行
sudo service redis-server status

# 如果未运行，启动它
sudo service redis-server start

注意：Redis 连接失败不会影响系统运行，会自动降级到内存缓存。

401 Unauthorized 错误

如果访问管理接口返回 401：

{"detail":"未认证，请先登录"}

原因：该接口需要认证

解决方法：

先调用 /api/auth/login 获取 Token
在请求头中加入 Authorization: Bearer YOUR_TOKEN

WSL 重启后服务启动失败

WSL 每次重启后需要手动启动服务：

# 一键启动所有服务
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 不可用时自动使用内存缓存

鉴权机制

支持两种认证方式：

JWT Token（推荐用于前端）
- 登录后获取 Token
- Token 有效期 7 天（可配置）
- 在 HTTP Header 中传递：Authorization: Bearer TOKEN
API Key（推荐用于外部系统）
- 在 .env 中配置 API_KEYS
- 在 HTTP Header 中传递：X-API-Key: YOUR_API_KEY

受保护的接口：

/api/admin/* - 需要管理员权限
其他接口暂不需要认证（可根据需要扩展）

异常处理

系统现在会返回友好的错误信息：

{
  "success": false,
  "error": "数据源异常，请稍后重试",
  "code": 503
}

错误类型：

400 - 业务逻辑错误
401 - 未认证
403 - 权限不足
422 - 请求参数错误
500 - 服务器内部错误
503 - 数据源不可用

10. 升级检查清单

安装新依赖包
安装并启动 Redis
配置 .env 文件（Redis + 鉴权配置）
生成安全的 SECRET_KEY
运行 python cli.py init 创建用户表
启动服务并验证功能
测试登录和受保护接口
修改默认管理员密码
检查 Redis 缓存是否生效

11. 回退方案

如果升级后遇到问题，可以临时禁用新功能：

禁用 Redis 缓存：停止 Redis 服务，系统会自动降级到内存缓存
```
sudo service redis-server stop
```
禁用鉴权：暂时注释掉 main.py 中受保护接口的 Depends(require_auth) 参数
完整回退：切换到升级前的 git 分支

6.1 KiB Raw Permalink Blame History Unescape Escape