# Star-Web-APP

**Repository Path**: chenwm-star/star-web-app

## Basic Information

- **Project Name**: Star-Web-APP
- **Description**: StarWeb 是一个基于 FastAPI 的企业级认证框架，专为快速开发而设计，提供完整的用户认证、权限管理和模块化架构。
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 4
- **Forks**: 0
- **Created**: 2025-08-24
- **Last Updated**: 2025-09-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: FastAPI, Python, 认证

## README

# StarWeb 认证框架 （APP版）

StarWeb 是一个基于 FastAPI 的企业级认证框架，专为快速开发而设计，提供完整的用户认证、权限管理和模块化架构。

## 🌟 项目特色

- **🚀 快速开发**: 模块化设计，开箱即用的认证系统
- **🔐 完整认证**: JWT 认证 + RBAC 权限模型
- **📦 自动注册**: 应用和路由自动发现注册
- **🏗️ 分层架构**: Controller-Service-Repository-Model 四层架构
- **🛠️ 管理工具**: 类似 Django 的命令行管理工具
- **⚡ 高性能**: 基于 FastAPI 异步框架
- **🎯 团队友好**: 规范化的代码结构，适合团队协作

## 🔧 技术栈

- **Web框架**: FastAPI
- **数据库**: SQLite (可配置其他数据库)
- **ORM**: Tortoise ORM
- **认证**: JWT Token
- **权限**: RBAC 模型
- **日志**: loguru
- **命令行工具**: Click

## 🚀 快速开始

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

### 2. 数据库初始化

```bash
# 执行数据库迁移
python manage.py migrate

# 创建超级管理员
python manage.py createsuperuser
```

### 3. 启动服务

```bash
# 启动开发服务器
python manage.py runserver
```

### 4. 访问接口

- API 文档: http://127.0.0.1:8005/api/docs
- 健康检查: http://127.0.0.1:8005/health

## 📋 管理命令

```bash
# 数据库相关
python manage.py migrate              # 数据库迁移
python manage.py createsuperuser      # 创建超级管理员

# 应用管理
python manage.py startapp myapp       # 创建新应用
python manage.py listapps             # 列出所有应用

# 开发工具
python manage.py runserver            # 启动服务器
python manage.py showroutes           # 显示路由信息
python manage.py shell                # 交互式Shell
```

## 📁 项目结构

```
star-web-app/
├── apps/                    # 应用模块目录
│   ├── auth/               # 认证应用（用户、角色、权限管理）
│   └── apps.py             # 应用注册管理
├── pkg/                    # 核心功能包
│   ├── core/              # 核心模块（应用工厂、路由、数据库）
│   ├── common/            # 通用模块（常量、基础模型、工具）
│   ├── middlewares/       # 中间件（认证、权限）
│   ├── logger/            # 日志工具
│   └── settings/          # 配置管理
├── main.py                # 应用入口
├── manage.py              # 管理脚本
└── config.ini             # 配置文件
```

## 🔐 权限系统

支持完整的 RBAC 权限模型：

```python
from pkg.middlewares.auth_middleware import require_permissions, require_roles

# 权限检查
@router.get("/users")
async def get_users(user: User = Depends(require_permissions("user:read"))):
    pass

# 角色检查
@router.get("/admin")
async def admin_panel(user: User = Depends(require_roles("admin"))):
    pass
```

## 🆕 创建新应用

```bash
# 创建新应用
python manage.py startapp blog

# 启用路由（在 apps/blog/router.py 中）
from .controllers.blog_controller import router as blog_router
router.include_router(blog_router)
```

## ⚙️ 配置

主要配置文件 `config.ini`：

```ini
[APP]
APP_NAME = StarWeb认证框架
DEBUG = true

[SERVER]
HOST = 127.0.0.1
PORT = 8005

[DATABASE]
DATABASE_URL = sqlite:///./starweb.db
MIGRATE = true

[JWT]
SECRET_KEY = your-jwt-secret-key
ACCESS_TOKEN_EXPIRE_MINUTES = 30
EXCLUDE_ROUTES = ["/auth/login", "/auth/refresh"]

[LOG]
LEVEL = INFO
FILE_ENABLED = true
CONSOLE_OUTPUT = true
```

## 🎯 适用场景

- **企业后台管理系统**
- **API 服务开发**
- **微服务架构**
- **权限管理系统**
- **快速原型开发**

## 📚 文档

- **[技术文档](./docs/TECHNICAL_GUIDE.md)** - 架构设计、设计模式、代码示例
- **[使用文档](./docs/USER_GUIDE.md)** - 详细使用指南、日志工具、最佳实践

## 🤝 贡献

欢迎提交 Issue 和 Pull Request 来完善这个项目！

## 📄 许可证

本项目使用 MIT 许可证。

---

**StarWeb** - 让认证变得简单，让开发更加高效！