# pg4ml-studio

**Repository Path**: rain-scott/pg4ml-studio

## Basic Information

- **Project Name**: pg4ml-studio
- **Description**: pg4ml任务管理和可视化
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-17
- **Last Updated**: 2025-08-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# pg4ml-studio

<div align="center">

![Python](https://img.shields.io/badge/Python-3.11+-blue.svg)
![FastAPI](https://img.shields.io/badge/FastAPI-0.101.1+-green.svg)
![License](https://img.shields.io/badge/License-MIT-yellow.svg)
![Version](https://img.shields.io/badge/Version-1.0.0-orange.svg)

**一个基于 FastAPI 的机器学习任务管理和可视化平台**

[快速开始](#快速开始) • [文档](#文档) • [API 参考](#api-参考) • [贡献指南](CONTRIBUTING.md)

</div>

---

## 📖 项目介绍

pg4ml-studio 是一个现代化的机器学习任务管理和可视化平台，基于 FastAPI 框架构建。该平台提供了完整的用户管理系统、任务调度、数据存储和监控功能，支持分布式部署和容器化运行。

### ✨ 主要特性

- 🚀 **高性能**: 基于 FastAPI 和异步编程，提供高性能的 API 服务
- 🔐 **用户管理**: 完整的用户认证、授权和角色管理系统
- 📊 **任务管理**: 支持机器学习任务的创建、调度和监控
- 🗄️ **数据存储**: 集成 PostgreSQL 数据库和 Redis 缓存
- 📈 **监控系统**: 集成 Prometheus、Grafana 和 Node Exporter
- 🐳 **容器化**: 支持 Docker 和 Docker Compose 部署
- 📝 **API 文档**: 自动生成的 Swagger 和 ReDoc API 文档
- 🔧 **开发友好**: 完整的开发工具链和代码质量检查

## 🏗️ 技术架构

### 核心技术栈

| 组件 | 技术选型 | 版本 |
|------|----------|------|
| **后端框架** | FastAPI | 0.101.1 |
| **数据库** | PostgreSQL + Tortoise ORM | 0.19.3 |
| **缓存** | Redis + Redis Sentinel | 5.0.0b1 |
| **任务调度** | APScheduler | 3.10.4 |
| **文件存储** | MinIO | 7.1.16 |
| **监控** | Prometheus + Grafana + Node Exporter | - |
| **容器化** | Docker + Docker Compose | - |
| **Web服务器** | Nginx + Gunicorn | - |

### 系统架构图

```mermaid
graph TB
    subgraph "前端/客户端"
        A[Web UI]
        B[Mobile App]
        C[API Client]
    end
    
    subgraph "负载均衡"
        D[Nginx]
    end
    
    subgraph "应用层"
        E[FastAPI]
        F[Gunicorn]
    end
    
    subgraph "数据层"
        G[PostgreSQL]
        H[Redis]
        I[MinIO]
    end
    
    subgraph "监控层"
        J[Prometheus]
        K[Grafana]
        L[Node Exporter]
    end
    
    A --> D
    B --> D
    C --> D
    D --> E
    E --> F
    E --> G
    E --> H
    E --> I
    E --> J
    J --> K
    L --> J
```

## 🚀 快速开始

### 环境要求

- **Python**: 3.11+
- **Docker**: 20.10+
- **Docker Compose**: 2.0+
- **内存**: 至少 4GB
- **磁盘**: 至少 20GB

### 方式一：Docker 快速启动（推荐）

```bash
# 1. 克隆项目
git clone <repository-url>
cd pg4ml-studio

# 2. 使用启动脚本
./start.sh docker

# 3. 访问服务
# API 文档: http://localhost/apidocs
# ReDoc 文档: http://localhost/apiredoc
# Grafana 监控: http://localhost:3000
# Prometheus: http://localhost:9090
```

### 方式二：本地开发环境

```bash
# 1. 克隆项目
git clone <repository-url>
cd pg4ml-studio

# 2. 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate     # Windows

# 3. 安装依赖
pip install -r working/requirements.txt

# 4. 配置环境变量
cp config/env.example config/.env
# 编辑 config/.env 文件，配置数据库等信息

# 5. 启动开发服务器
./start.sh dev
```

### 方式三：生产环境部署

```bash
# 1. 安装依赖
./start.sh install

# 2. 检查环境
./start.sh check

# 3. 启动生产服务
./start.sh prod
```

## 📚 文档

### 核心文档

- [📖 用户指南](docs/user-guide.md) - 详细的使用说明
- [🔧 API 参考](docs/api-reference.md) - 完整的 API 文档
- [🏗️ 架构设计](docs/architecture.md) - 系统架构详解
- [🚀 部署指南](docs/deployment.md) - 部署和运维指南

### 开发文档

- [👥 贡献指南](CONTRIBUTING.md) - 如何参与项目开发
- [🧪 测试指南](docs/testing.md) - 测试用例编写和运行
- [🔍 代码规范](docs/coding-standards.md) - 代码风格和规范

## 🔌 API 参考

### 用户管理模块 (`/api/user`)

| 方法 | 路径 | 描述 | 状态 |
|------|------|------|------|
| `GET` | `/api/user/role/all` | 查询所有角色列表 | ✅ |
| `POST` | `/api/user/login` | 用户登录 | ✅ |
| `DELETE` | `/api/user/logout` | 退出登录 | ✅ |
| `GET` | `/api/user/info/list` | 获取用户信息列表 | ✅ |
| `GET` | `/api/user/info` | 获取个人用户信息 | ✅ |
| `POST` | `/api/user/info` | 新增用户 | ✅ |
| `PUT` | `/api/user/info` | 修改用户信息 | ✅ |
| `DELETE` | `/api/user/info` | 删除用户 | ✅ |

### 快速测试

```bash
# 使用 curl 测试 API
curl -X GET "http://localhost:8000/api/user/role/all" \
  -H "accept: application/json"

# 使用 httpie 测试 API
http GET localhost:8000/api/user/role/all
```

## 🏗️ 项目结构

```
pg4ml-studio/
├── 📁 app/                    # 应用主目录
│   ├── 📁 user_module/       # 用户管理模块
│   │   ├── __init__.py      # 模块初始化
│   │   ├── service.py       # 业务逻辑
│   │   ├── schemas.py       # 数据模型
│   │   └── operate_log.py   # 操作日志
│   ├── route.py             # 路由配置
│   ├── schemas.py           # 通用数据模型
│   └── utils.py             # 工具函数
├── 📁 config/               # 配置文件
│   ├── __init__.py         # 配置初始化
│   ├── settings.py         # 应用配置
│   ├── db.py              # 数据库配置
│   └── env.example        # 环境变量示例
├── 📁 model/               # 数据模型
│   ├── __init__.py        # 模型初始化
│   ├── base.py           # 基础模型
│   └── user.py           # 用户模型
├── 📁 working/            # 部署相关文件
│   ├── compose.yaml      # Docker Compose 配置
│   ├── Dockerfile        # Docker 镜像配置
│   ├── requirements.txt  # Python 依赖
│   └── gunicorn_conf.py  # Gunicorn 配置
├── 📁 swagger/           # API 文档静态文件
├── main.py              # 应用入口
├── start.sh             # 启动脚本
├── .gitignore           # Git 忽略文件
├── pyproject.toml       # 项目配置
├── README.md           # 项目说明
├── CONTRIBUTING.md     # 贡献指南
├── CHANGELOG.md        # 更新日志
└── LICENSE             # 许可证
```

## 🔧 配置说明

### 环境变量配置

主要配置文件位于 `config/.env`：

```ini
[development]
# 数据库配置
POSTGRESQL_HOST = localhost
POSTGRESQL_USER = postgres
POSTGRESQL_PASSWORD = postgresql_admin
POSTGRESQL_PORT = 5432
POSTGRESQL_DB = pg4ml_studio

# Redis 配置
REDIS_SENTINEL_HOST_LIST = localhost,localhost,localhost
REDIS_PASSWORD = redis_password
REDIS_SENTINEL_SERVICE_NAME = mymaster

# MinIO 配置
MINIO_HOST = localhost
MINIO_PORT = 9000
MINIO_ACCESS_KEY = minioadmin
MINIO_SECRET_KEY = minioadmin
MINIO_BUCKET = pg4ml-studio
```

### 启动脚本使用

```bash
# 查看帮助
./start.sh help

# 启动开发环境
./start.sh dev

# 启动生产环境
./start.sh prod

# 使用 Docker 启动
./start.sh docker

# 停止 Docker 服务
./start.sh stop

# 安装依赖
./start.sh install

# 检查环境
./start.sh check
```

## 🧪 测试

### 运行测试

```bash
# 运行所有测试
pytest

# 运行特定测试文件
pytest tests/test_user.py

# 运行带覆盖率报告的测试
pytest --cov=app tests/

# 运行性能测试
pytest tests/test_performance.py -m performance
```

### 测试覆盖率

```bash
# 生成覆盖率报告
pytest --cov=app --cov-report=html tests/

# 查看覆盖率报告
open htmlcov/index.html
```

## 📊 监控和日志

### 系统监控

- **Prometheus**: 收集系统指标和业务指标
- **Grafana**: 可视化监控数据和告警
- **Node Exporter**: 系统级指标收集

### 日志管理

- **应用日志**: 记录业务操作和错误信息
- **访问日志**: 记录 API 访问情况
- **性能日志**: 记录系统性能指标

### 告警配置

```yaml
# Grafana 告警规则示例
groups:
  - name: pg4ml-studio
    rules:
      - alert: HighCPUUsage
        expr: cpu_usage > 80
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "CPU 使用率过高"
```

## 🚀 性能优化

### 数据库优化

- 使用连接池管理数据库连接
- 实现查询缓存机制
- 优化数据库索引

### 缓存策略

- Redis 缓存热点数据
- 实现缓存预热机制
- 设置合理的缓存过期时间

### 异步处理

- 使用异步 I/O 处理请求
- 实现任务队列处理耗时操作
- 优化并发处理能力

## 🔒 安全特性

### 认证授权

- JWT Token 认证
- 基于角色的访问控制 (RBAC)
- API 访问频率限制

### 数据安全

- 敏感数据加密存储
- SQL 注入防护
- XSS 攻击防护

### 网络安全

- HTTPS 传输加密
- CORS 跨域配置
- 请求签名验证

## 🤝 参与贡献

我们欢迎所有形式的贡献！请查看 [贡献指南](CONTRIBUTING.md) 了解详细信息。

### 贡献方式

1. 🐛 **报告 Bug**: 在 [Issues](https://github.com/your-org/pg4ml-studio/issues) 中报告问题
2. 💡 **功能建议**: 提出新功能建议和改进意见
3. 📝 **文档改进**: 完善项目文档和示例
4. 🔧 **代码贡献**: 提交代码修复和新功能
5. 🧪 **测试用例**: 编写和优化测试用例

### 开发流程

```bash
# 1. Fork 项目
# 2. 克隆到本地
git clone <your-fork-url>
cd pg4ml-studio

# 3. 创建功能分支
git checkout -b feature/amazing-feature

# 4. 提交更改
git commit -m "feat: 添加新功能"

# 5. 推送到分支
git push origin feature/amazing-feature

# 6. 创建 Pull Request
```

## 📄 许可证

本项目采用 [MIT 许可证](LICENSE) - 查看 LICENSE 文件了解详情。

## 🙏 致谢

感谢所有为项目做出贡献的开发者！

### 主要贡献者

- [@your-username](https://github.com/your-username) - 项目维护者
- [@contributor1](https://github.com/contributor1) - 核心功能开发
- [@contributor2](https://github.com/contributor2) - 文档和测试

### 开源项目

感谢以下开源项目的支持：

- [FastAPI](https://fastapi.tiangolo.com/) - 现代、快速的 Web 框架
- [PostgreSQL](https://www.postgresql.org/) - 强大的开源数据库
- [Redis](https://redis.io/) - 高性能的缓存数据库
- [Docker](https://www.docker.com/) - 容器化平台

## 📞 联系我们

- 📧 **邮箱**: team@pg4ml-studio.com
- 🐛 **问题反馈**: [GitHub Issues](https://github.com/your-org/pg4ml-studio/issues)
- 💬 **讨论区**: [GitHub Discussions](https://github.com/your-org/pg4ml-studio/discussions)
- 📖 **文档**: [项目文档](https://pg4ml-studio.readthedocs.io/)

## ⭐ 支持项目

如果这个项目对您有帮助，请给我们一个 ⭐ Star！

---

<div align="center">

**pg4ml-studio** - 让机器学习任务管理更简单

[快速开始](#快速开始) • [文档](#文档) • [贡献](#参与贡献) • [许可证](LICENSE)

</div>