LQAdminPlatform/项目

LQAdminPlatform - OAuth2 单点登录认证中心

项目简介

LQAdminPlatform 是一个基于 FastAPI 的 OAuth2 单点登录认证中心，提供统一的用户认证、授权管理和样本中心功能。

功能模块

1. 系统管理

• 用户管理
• 角色管理
• 菜单管理
• 权限管理
• 系统日志
• 仪表盘
• 应用管理

2. 授权管理

• SSO 验证凭证
• 授权码生成与管理
• Access Token 管理
• 用户信息获取
• JWT Token 管理
• 子系统登录认证

3. 样本中心

• 知识库管理
• 文档管理
• 知识片段管理
• 标签管理
• 检索引擎
• 图片管理

环境准备

创建虚拟环境

# 使用 conda
conda create --name lq_oauth2 python=3.12
conda activate lq_oauth2

# 或使用 venv
python -m venv venv
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows

安装依赖

pip install -r requirements/base.txt

# 开发环境额外依赖
pip install -r requirements/dev.txt

快速开始

1. 配置环境变量

复制 .env.example 到 .env 并配置：

# 数据库配置
DATABASE_URL=mysql://user:password@localhost:3306/sso_db

# Redis配置
REDIS_HOST=localhost
REDIS_PORT=6379

# 应用配置
APP_NAME=LQAdminPlatform
HOST=0.0.0.0
PORT=8000
DEBUG=True

# JWT配置
JWT_SECRET_KEY=your-secret-key
ACCESS_TOKEN_EXPIRE_MINUTES=30

2. 初始化数据库

python scripts/init_db.py

3. 启动服务

开发环境（推荐）

# 使用新的启动脚本（自动查找可用端口）
python run_server.py



#### 生产环境

bash

使用 uvicorn

uvicorn app.server.app:app --host 0.0.0.0 --port 8000

使用 gunicorn（推荐）

gunicorn app.server.app:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000

### 4. 访问服务

- **API 文档**: http://localhost:8000/docs
- **ReDoc 文档**: http://localhost:8000/redoc
- **健康检查**: http://localhost:8000/health

## 项目结构

LQAdminPlatform/ ├── src/ │ ├── app/ │ │ ├── server/ # 服务器启动模块 │ │ ├── logger/ # 日志配置 │ │ ├── base/ # 基础连接（MySQL、Redis、Milvus） │ │ ├── core/ # 核心模块（异常等） │ │ ├── models/ # 数据模型 │ │ ├── schemas/ # 数据结构 │ │ ├── utils/ # 工具类 │ │ ├── config/ # 配置文件 │ │ ├── system/ # 系统管理模块 │ │ ├── oauth/ # 授权管理模块 │ │ └── sample/ # 样本中心模块 │ └── views/ # 视图路由 ├── scripts/ # 脚本文件 ├── test/ # 测试文件 ├── requirements/ # 依赖文件 ├── run_server.py # 启动脚本（新） └── full_server.py # 启动脚本（旧，保留兼容）

详细的项目结构说明请查看 [REFACTOR_README.md](./REFACTOR_README.md)

## 授权中心

### 授权后台

bash cd LQAdminPlatform python run_server.py

访问: http://localhost:8000/docs

### 授权前台

bash cd LQAdminFront npm install npm run dev-local

访问: http://localhost:3000

默认账号: admin / Admin123456

## 授权子系统案例

### 子系统后台

bash cd subsystem-demo/backend python main.py

访问: http://localhost:8001/docs

### 子系统前台

bash cd subsystem-demo/frontend npm install npm run dev

访问: http://localhost:3001

### 子系统配置

在子系统中配置以下环境变量：

env CLIENT_ID=eqhoIdAyAWbA8MsYHsNqQqNLJbCayTjY CLIENT_SECRET=LKJm5XHJFhhgxSv9nQhoQNNI3wrKyWGZCaPQ4qc43Lf5qfXdLAHoGAHhCYqApEpr SSO_SERVER_URL=http://localhost:8000

## API 端点

### 系统管理
- `GET /api/v1/system/dashboard` - 仪表盘
- `GET /api/v1/system/users` - 用户列表
- `GET /api/v1/system/roles` - 角色列表
- `GET /api/v1/system/menus` - 菜单列表
- `GET /api/v1/system/logs` - 系统日志

### 授权管理
- `GET /api/v1/oauth/authorize` - OAuth2 授权
- `POST /api/v1/oauth/token` - 获取令牌
- `GET /api/v1/oauth/userinfo` - 用户信息
- `POST /api/v1/oauth/revoke` - 撤销令牌

### 样本中心
- `GET /api/v1/sample/knowledge-bases` - 知识库列表
- `GET /api/v1/sample/documents` - 文档列表
- `POST /api/v1/sample/documents` - 上传文档
- `POST /api/v1/sample/search` - 检索文档

## 开发指南

### 添加新功能

1. 在对应模块下创建 model（如需要）
2. 在对应模块下创建 schema
3. 在 views 目录下创建或更新视图路由
4. 在 server/app.py 中注册路由

### 运行测试

bash

运行所有测试

pytest

运行特定测试

pytest test/test_auth.py

查看覆盖率

pytest --cov=app

### 代码规范

项目使用以下工具保证代码质量：

- **Black**: 代码格式化
- **isort**: 导入排序
- **flake8**: 代码检查
- **mypy**: 类型检查

bash

格式化代码

black src/

排序导入

isort src/

检查代码

flake8 src/

## 部署

### Docker 部署

bash

构建镜像

docker build -t lqadmin:latest .

运行容器

docker run -d -p 8000:8000 --env-file .env lqadmin:latest

### Docker Compose 部署

bash docker-compose up -d

## 常见问题

### 1. 端口被占用

启动脚本会自动查找可用端口（8000-8010），或手动指定：

bash PORT=8001 python run_server.py ```

2. 数据库连接失败

检查 .env 文件中的 DATABASE_URL 配置是否正确。

3. Redis 连接失败

Redis 为可选组件，连接失败不会影响核心功能，但会影响缓存和会话管理。

更新日志

v1.0.0 (2024-01-15)

• ✅ 完成项目结构重构
• ✅ 按功能模块划分（system、oauth、sample）
• ✅ 统一日志配置
• ✅ 统一数据库连接管理
• ✅ 新增模块化视图路由

详细更新日志请查看 REFACTOR_README.md

贡献指南

欢迎提交 Issue 和 Pull Request！

许可证

MIT License

联系方式

如有问题，请联系开发团队。