stock_cursor_v0/backend/ENV_CONFIG.md

环境变量配置说明

新增配置项（三大核心功能）

Redis 缓存配置

# Redis 连接配置
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0
REDIS_PASSWORD=  # 如果 Redis 设置了密码则填写

认证系统配置

# JWT 密钥（生产环境务必修改）
SECRET_KEY=your-secret-key-change-in-production

# Token 过期时间（分钟）
ACCESS_TOKEN_EXPIRE_MINUTES=10080  # 默认7天

# API Key 模式（可选，用于外部调用，逗号分隔多个）
API_KEYS=your-api-key-1,your-api-key-2

# 默认管理员账号（首次启动时创建）
DEFAULT_ADMIN_USERNAME=admin
DEFAULT_ADMIN_PASSWORD=admin123  # 首次启动后务必修改密码

安装 Redis（WSL 环境）

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

# 启动 Redis
sudo service redis-server start

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

# 设置 Redis 开机自启（可选）
sudo systemctl enable redis-server

安全建议

1. SECRET_KEY: 生产环境必须使用强随机字符串，可用以下命令生成：

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

2. 默认密码: 首次登录后立即修改 admin 密码

3. API_KEYS: 仅在需要外部调用时配置，妥善保管

4. Redis 密码: 生产环境建议为 Redis 设置密码：

   # 编辑 Redis 配置
   sudo nano /etc/redis/redis.conf
   # 找到 requirepass 行，取消注释并设置密码
   requirepass your-strong-password
   # 重启 Redis
   sudo service redis-server restart
   

功能说明

1. Redis 缓存

• 替代内存缓存，支持持久化和跨进程共享
• 自动降级：Redis 不可用时使用内存缓存
• 默认过期时间根据数据类型自动设置（行情数据1分钟，基本面数据1天）

2. 统一鉴权

• JWT Token 模式: 用户登录获取 Token，适合前端应用
• API Key 模式: 用于外部系统调用，配置在 HTTP Header X-API-Key
• 管理接口（/api/admin/*）需要管理员权限

3. 统一异常处理

• 业务异常返回友好错误信息
• 数据源异常自动降级
• 数据库异常统一处理
• 所有异常记录日志便于排查

API 使用示例

登录

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

使用 Token 访问受保护接口

curl -X GET http://localhost:8000/api/admin/status \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

使用 API Key 访问

curl -X GET http://localhost:8000/api/admin/status \
  -H "X-API-Key: your-api-key-1"

注意事项

1. WSL 环境下，每次重启后需要手动启动服务：

   sudo service postgresql start
   sudo service redis-server start
   

2. Redis 连接失败不会影响系统运行，会自动降级到内存缓存

3. 未配置鉴权时，所有接口默认不需要认证（开发模式）