# PyTemplate

**Repository Path**: zhaofu233/py-template

## Basic Information

- **Project Name**: PyTemplate
- **Description**: python项目模板
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-11
- **Last Updated**: 2026-01-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PyTemplate Backend

基于 FastAPI 的现代化 Web 应用程序框架

## 项目特性

- **现代技术栈**: FastAPI + SQLAlchemy 2.0 + Pydantic 2.x
- **异步架构**: 支持高并发异步数据库操作
- **权限管理**: 完整的 RBAC 权限控制体系
- **任务调度**: 基于 APScheduler 的定时任务系统
- **日志监控**: 完整的操作日志和系统监控
- **安全机制**: JWT Token 认证、数据权限控制、密码加密存储
- **性能优化**: 异步数据库操作、Redis 缓存支持、GZip 压缩
- **服务分离**: 支持 Admin 管理端和 App 用户端独立部署
- **环境隔离**: 支持 dev/prod 环境配置分离
- **静态文件优化**: 修复Swagger UI静态资源路径问题

## 系统架构

### 技术栈

| 技术 | 说明 |
|------|------|
| FastAPI | 现代 Web 框架 |
| SQLAlchemy | 2.0 ORM 框架 |
| Alembic | 数据库迁移工具 |
| Pydantic | 数据验证与序列化 |
| APScheduler | 定时任务调度 |
| Redis | 缓存与会话存储 |
| Uvicorn | ASGI 服务器 |
| Python | 3.10+ 运行环境 |

### 架构设计

```txt
分层架构 (MVC)
├── Controller   # 控制器层 - 处理HTTP请求
├── Service      # 业务层 - 核心业务逻辑
├── CRUD         # 数据访问层 - 数据库操作
└── Model        # 模型层 - 数据模型定义
```

## 项目结构

```txt
PyTemplate backend/
├── application/               # 项目核心代码
│   ├── admin/                 # 后台管理模块
│   │   ├── module_common/     # 通用功能模块
│   │   │   ├── file/          # 文件上传模块
│   │   │   └── __init__.py    # 模块初始化
│   │   ├── module_monitor/    # 系统监控模块
│   │   │   ├── cache/         # 缓存管理
│   │   │   ├── online/        # 在线用户
│   │   │   ├── resource/      # 资源监控
│   │   │   ├── server/        # 服务器信息
│   │   │   └── __init__.py    # 模块初始化
│   │   ├── module_system/     # 系统管理模块
│   │   │   ├── account/       # 账户管理
│   │   │   ├── auth/          # 认证授权
│   │   │   ├── dept/          # 部门管理
│   │   │   ├── dict/          # 数据字典
│   │   │   ├── log/           # 日志管理
│   │   │   ├── menu/          # 菜单管理
│   │   │   ├── notice/        # 通知公告
│   │   │   ├── params/        # 参数配置
│   │   │   ├── position/      # 岗位管理
│   │   │   ├── role/          # 角色管理
│   │   │   └── __init__.py    # 模块初始化
│   │   └── __init__.py        # 后台管理模块初始化
│   ├── app/                   # 用户端模块
│   │   └── module_user/       # 用户功能模块
│   │       ├── auth/          # 用户认证
│   │       ├── user/          # 用户管理
│   │       └── __init__.py    # 模块初始化
│   ├── common/                # 公共组件
│   │   ├── crud/              # 通用数据访问层
│   │   ├── entity/            # 通用实体模型
│   │   ├── param/             # 通用参数模型
│   │   ├── schema/            # 通用数据模型
│   │   ├── __init__.py        # 公共组件初始化
│   │   ├── constant.py        # 常量定义
│   │   ├── enums.py           # 枚举定义
│   │   ├── request.py         # 请求工具
│   │   └── response.py        # 响应工具
│   ├── core/                  # 核心模块
│   │   ├── __init__.py        # 核心模块初始化
│   │   ├── ap_scheduler.py    # 定时任务调度
│   │   ├── base_crud.py       # 基础数据访问
│   │   ├── base_model.py      # 基础模型
│   │   ├── base_params.py     # 基础参数
│   │   ├── base_schema.py     # 基础数据模型
│   │   ├── database.py        # 数据库配置
│   │   ├── dependencies.py    # 依赖注入
│   │   ├── exceptions.py      # 异常处理
│   │   ├── logger.py          # 日志配置
│   │   ├── middlewares.py     # 中间件
│   │   ├── mongo_crud.py      # MongoDB操作
│   │   ├── redis_crud.py      # Redis操作
│   │   ├── router_class.py    # 路由类
│   │   ├── security_admin.py  # 管理端安全
│   │   ├── security_app.py    # 用户端安全
│   │   ├── serialize.py       # 序列化工具
│   │   └── validator.py       # 验证器
│   ├── scripts/               # 初始化脚本
│   │   ├── data/              # 初始化数据
│   │   ├── __init__.py        # 脚本初始化
│   │   └── initialize.py      # 数据库初始化
│   └── utils/                 # 工具类
│       ├── __init__.py        # 工具类初始化
│       ├── captcha_util.py    # 验证码工具
│       ├── common_util.py     # 通用工具
│       ├── console.py         # 控制台输出
│       ├── cron_util.py       # 定时任务工具
│       ├── excel_util.py      # Excel工具
│       ├── hash_bcrpy_util.py # 密码加密工具
│       ├── ip_local_util.py   # IP地理位置工具
│       ├── java_util.py       # Java兼容工具
│       ├── re_util.py         # 正则表达式工具
│       ├── sign_util.py       # 签名工具
│       ├── string_util.py     # 字符串工具
│       ├── time_util.py       # 时间工具
│       ├── upload_util.py     # 上传工具
│       └── wechat_util.py     # 微信工具
├── static/                    # 静态资源文件
├── alembic/                   # 数据库迁移
├── main.py                    # 项目启动入口
├── alembic.ini                # Alembic 迁移配置
├── requirements.txt           # Python 依赖包
├── run.sh                     # Linux启动脚本
└── README.md                  # 项目说明文档
```

### 模块设计

每个业务模块采用统一的分层结构：

```txt
module_*/
├── __init__.py     # 模块初始化，注册路由
├── controller.py   # 控制器 - HTTP 请求处理
├── service.py      # 服务层 - 业务逻辑处理
├── crud.py         # 数据层 - 数据库操作
├── model.py        # ORM 模型 - 数据库表定义
├── schema.py       # Pydantic 模型 - 数据验证
└── param.py        # 参数模型 - 请求参数
```

## 快速开始

### 环境要求

- **Python**: 3.10+
- **数据库**: MySQL 8.0+/PostgreSQL/SQLite
- **Redis**: 6.0+

### 安装与运行

#### 1. 项目初始化

```bash
# 克隆项目
git clone <repository-url>

# 进入项目目录
cd PyTemplate

# 创建conda环境(首次)
conda create -n PyTemplate python=3.10

# 激活conda环境
conda activate PyTemplate

# 安装依赖
pip install uv  -i https://pypi.tuna.tsinghua.edu.cn/simple 
uv pip install -r requirements.txt  -i https://pypi.tuna.tsinghua.edu.cn/simple 
```

#### 2. 环境配置

复制并编辑环境配置文件：

```bash
cp env/.env.prod env/.env.dev
# 编辑 env/.env.dev 文件，配置数据库连接和其他参数
```

主要配置项：

- `DATABASE_HOST`, `DATABASE_PORT`, `DATABASE_USER`, `DATABASE_PASSWORD`, `DATABASE_NAME`: 数据库连接配置
- `SECRET_KEY`: JWT 加密密钥
- `REDIS_HOST`, `REDIS_PORT`, `REDIS_PASSWORD`: Redis 连接配置
- `WECHAT_APPID`: 微信小程序AppID（微信小程序登录功能需要）
- `WECHAT_APPSECRET`: 微信小程序AppSecret（微信小程序登录功能需要）
- `ADMIN_SERVER_PORT`, `APP_SERVER_PORT`: 管理端和用户端服务端口配置

#### 3. 数据库初始化

```bash
# 生成迁移文件（仅首次或模型变更时）
python main.py revision "初始化迁移" --env=dev

# 应用数据库迁移
python main.py upgrade --env=dev

```

#### 4. 启动服务

```bash
# Admin 管理端服务 - 开发环境（默认启动）
python main.py admin --env=dev

# App 用户端服务 - 开发环境
python main.py app --env=dev

# Admin 管理端服务 - 生产环境
python main.py admin --env=prod

# App 用户端服务 - 生产环境
python main.py app --env=prod

# 完整服务启动（兼容旧方式）- 开发环境
python main.py run --env=dev

# 完整服务启动（兼容旧方式）- 生产环境
python main.py run --env=prod

# 或使用 uvicorn 直接启动
uvicorn main:application --host 127.0.0.1 --port 9990 --reload
```

**注意**：
- `admin` 命令仅启动管理端服务并只注册管理端路由
- `app` 命令仅启动用户端服务并只注册用户端路由
- `run` 命令启动完整服务并注册所有路由
- 生产环境使用多进程模式（默认4个工作进程）
- 静态文件路径问题已在最新版本中修复

服务成功启动后，可以访问：

- **Admin API 文档**: http://localhost:9991/docs (Swagger UI) - 管理端
- **App API 文档**: http://localhost:9990/docs (Swagger UI) - 用户端

## API 文档

### 主要接口模块

| 模块 | 路径 | 说明 |
|------|------|
| 用户管理 | `/admin/v1/system/user`     | 用户增删改查、角色分配 |
| 角色管理 | `/admin/v1/system/role`     | 角色管理、权限分配 |
| 菜单管理 | `/admin/v1/system/menu`     | 系统菜单、权限节点 |
| 部门管理 | `/admin/v1/system/dept`     | 组织架构管理 |
| 岗位管理 | `/admin/v1/system/position` | 岗位信息管理 |
| 系统监控 | `/admin/v1/monitor/*`       | 系统性能、日志监控 |
| 任务调度 | `/admin/v1/monitor/job`     | 定时任务管理 |
| 文件管理 | `/admin/v1/common/file`     | 文件上传下载 |
| 用户接口 | `/app/v1/user/*`            | 用户相关接口 |
| 用户认证 | `/app/v1/auth/*`            | 用户认证接口 |

### 认证授权

系统使用 JWT Bearer Token 进行身份验证：

```bash
# Admin 管理端登录获取 Token
curl -X POST "http://localhost:9991/admin/v1/auth/login" \
     -H "Content-Type: application/json" \
     -d '{"username": "admin", "password": "123456"}'

# App 用户端登录获取 Token
curl -X POST "http://localhost:9990/app/v1/auth/login" \
     -H "Content-Type: application/json" \
     -d '{"username": "user", "password": "123456"}'

# 使用 Token 访问受保护的资源
curl -X GET "http://localhost:9991/admin/v1/system/user/list" \
     -H "Authorization: Bearer YOUR_TOKEN_HERE"
```

## 开发指南

### 项目配置

主要配置文件位于 `application/setting.py`，支持通过环境变量进行覆盖。

### 数据库迁移

```bash
# 查看当前迁移状态
python main.py current --env=dev

# 查看迁移历史
python main.py history --env=dev

# 回滚到上一个版本
python main.py downgrade -1 --env=dev
```

## 监控与日志

### 日志级别

- **DEBUG**: 详细的调试信息
- **INFO**: 一般信息（默认级别）
- **WARNING**: 警告信息
- **ERROR**: 错误信息
- **CRITICAL**: 严重错误

### 性能监控

系统内置了完整的性能监控功能：

- API 响应时间监控
- 数据库连接池监控
- 内存与 CPU 使用率监控
- 自定义业务指标监控

## 部署指南

### Docker 部署

```bash
# 构建镜像
docker build -t PyTemplate .

# 运行容器
docker run -d \
  --name PyTemplate \
  -p 9990:9990 -p 9991:9991 \
  -e DATABASE_URL="postgresql://user:pass@host:5432/db" \
  PyTemplate
```

### 传统部署

```bash
# 使用 Gunicorn 启动管理端服务
ENVIRONMENT=prod nohup gunicorn main:create_admin_app \
  --workers 4 \
  --worker-class uvicorn.workers.UvicornWorker \
  --bind 0.0.0.0:9991 \
  --access-logfile - \
  --error-logfile - &

# 使用 Gunicorn 启动用户端服务
ENVIRONMENT=prod nohup gunicorn main:create_app_app \
  --workers 4 \
  --worker-class uvicorn.workers.UvicornWorker \
  --bind 0.0.0.0:9990 \
  --access-logfile - \
  --error-logfile - &
```

### Nginx 配置

```nginx
# Admin 管理端代理
server {
    listen 80;
    server_name admin.your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:9991;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

# App 用户端代理
server {
    listen 80;
    server_name app.your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:9990;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

## 开发指南

### 开发流程

1. Fork 项目
2. 创建特性分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add some amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 发起 Pull Request

### 代码规范

- 遵循 PEP 8 Python 编码规范
- 使用类型注解 (Type Hints)
- 编写单元测试
- 添加必要的注释和文档

## 相关链接

- **FastAPI 官方文档**: [https://fastapi.tiangolo.com/](https://fastapi.tiangolo.com/)
- **SQLAlchemy 文档**: [https://docs.sqlalchemy.org/](https://docs.sqlalchemy.org/)
- **Pydantic 文档**: [https://pydantic-docs.helpmanual.io/](https://pydantic-docs.helpmanual.io/)