buffer_platform/AUTH_GUIDE.md

用户权限系统使用指南

📋 系统概述

期货智析系统现已集成完整的用户权限管理系统，所有页面需要进行登录才能访问。系统支持两种用户角色：

• 管理员 (admin): 可以访问品种分析界面和系统管理界面
• 普通用户 (user): 只能访问品种分析界面

🔐 默认账户

系统首次启动时会自动创建默认管理员账户：

字段	值
用户名	lxy_root
密码	admin123
角色	管理员 (admin)
邮箱	admin@system.local

⚠️ 重要: 首次登录后请立即修改默认密码！

🚀 使用流程

1. 访问系统

打开浏览器访问：http://localhost:9600

系统会自动重定向到登录页面。

2. 登录

1. 输入用户名和密码
2. 点击"登录"按钮
3. 系统验证成功后会根据用户角色进行跳转

3. 角色跳转逻辑

普通用户

• 登录后直接进入 品种分析 界面
• 访问地址：http://localhost:9600/futures-analysis

管理员用户

• 登录后进入 角色选择 页面
• 可选择进入：
  • 品种分析 - 智能期货分析工具
  • 系统管理 - 后台管理配置界面

4. 退出登录

在任意页面点击"退出登录"按钮，或在角色选择页面点击退出。

📁 文件结构

app/
├── user_models.py          # 用户数据库模型
├── auth_service.py         # 认证服务（密码加密、会话管理）
├── api/
│   └── auth.py            # 认证API路由
├── static/
│   ├── login.html         # 登录页面
│   └── role_select.html   # 角色选择页面
└── main.py                # 主入口（已集成认证）

🔧 API接口

1. 用户登录

POST /api/v1/auth/login

请求体:

{
  "username": "lxy_root",
  "password": "admin123"
}

响应:

{
  "success": true,
  "token": "jr1xNX4egsLRStvVYLnkJj8uruB902VwCG4z3Wuy6dc",
  "user": {
    "id": 1,
    "username": "lxy_root",
    "role": "admin",
    "email": "admin@system.local"
  },
  "message": "登录成功"
}

2. 验证令牌

GET /api/v1/auth/verify

请求头:

Authorization: Bearer <token>

响应:

{
  "success": true,
  "user": {
    "id": 1,
    "username": "lxy_root",
    "role": "admin",
    "email": "admin@system.local",
    "last_login": "2026-05-24T15:30:00"
  }
}

3. 获取当前用户信息

GET /api/v1/auth/me

请求头:

Authorization: Bearer <token>

4. 用户登出

POST /api/v1/auth/logout

请求头:

Authorization: Bearer <token>

🗄️ 数据库表

系统创建了两个新表：

1. users 表 - 用户信息

字段	类型	说明
id	INTEGER	主键
username	VARCHAR(50)	用户名（唯一）
password_hash	VARCHAR(255)	密码哈希
email	VARCHAR(100)	邮箱
role	VARCHAR(20)	角色 (admin/user)
is_active	BOOLEAN	是否启用
created_at	DATETIME	创建时间
last_login	DATETIME	最后登录时间

2. sessions 表 - 会话管理

字段	类型	说明
id	INTEGER	主键
user_id	INTEGER	用户ID
token	VARCHAR(255)	会话令牌（唯一）
created_at	DATETIME	创建时间
expires_at	DATETIME	过期时间
is_valid	BOOLEAN	是否有效

🔒 安全特性

1. 密码加密: 使用 SHA-256 + 随机盐值加密存储
2. 会话管理: 使用安全令牌，24小时自动过期
3. 权限控制: 基于角色的访问控制 (RBAC)
4. 自动清理: 过期会话自动标记为无效

👥 用户管理

创建新用户

可以通过Python脚本或直接操作数据库创建用户：

from app.database import SessionLocal
from app import auth_service

db = SessionLocal()
try:
    auth_service.create_user(
        db=db,
        username='new_user',
        password='secure_password',
        email='user@example.com',
        role='user'  # 或 'admin'
    )
finally:
    db.close()

修改用户角色

from app.database import SessionLocal
from app.user_models import User

db = SessionLocal()
try:
    user = db.query(User).filter(User.username == 'username').first()
    user.role = 'admin'  # 或 'user'
    db.commit()
finally:
    db.close()

禁用用户

user.is_active = False
db.commit()

🎯 页面访问控制

页面	需要登录	需要角色
/login	❌	❌
/futures-analysis	✅	任意
/role-select	✅	admin
/ui	✅	admin
/ai-config	✅	任意
/api/v1/*	部分接口	视接口而定

🐛 故障排查

1. 登录后无法访问页面

• 检查浏览器控制台是否有错误
• 确认localStorage中保存了auth_token
• 尝试清除浏览器缓存后重新登录

2. 令牌过期

• 会话令牌24小时过期
• 过期后需要重新登录
• 可在代码中修改 expires_hours 参数

3. 忘记管理员密码

可以通过数据库重置：

from app.database import SessionLocal
from app import auth_service

db = SessionLocal()
try:
    from app.user_models import User
    admin = db.query(User).filter(User.username == 'lxy_root').first()
    admin.password_hash = auth_service.hash_password('new_password')
    db.commit()
    print("密码已重置")
finally:
    db.close()

📝 最佳实践

1. ✅ 首次登录后修改默认密码
2. ✅ 定期清理过期会话
3. ✅ 为不同用户分配最小权限原则
4. ✅ 定期检查用户登录日志
5. ✅ 备份用户数据库表

🔗 相关文档

• 部署指南
• 系统架构
• API文档