# flaskicu
**Repository Path**: coding-change-world/flaskicu
## Basic Information
- **Project Name**: flaskicu
- **Description**: FlaskICU 是一个轻量级但功能完善的 Flask 企业级脚手架框架。它基于 Flask 3.1.0 构建，集成了企业级应用开发所需的核心功能，帮助开发者快速构建稳定、安全、可扩展的 Web 应用。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-14
- **Last Updated**: 2026-03-23
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
FlaskICU
企业级 Flask 脚手架框架
开箱即用的 Flask 企业级开发框架，内置权限管理、缓存、异步任务等核心功能
[核心特性](#-核心特性) • [快速开始](#-快速开始) • [项目结构](#-项目结构) • [开发指南](#-开发指南)
---
## 项目简介
FlaskICU 是一个轻量级但功能完善的 Flask 企业级脚手架框架。它基于 Flask 3.1.0 构建，集成了企业级应用开发所需的核心功能，帮助开发者快速构建稳定、安全、可扩展的 Web 应用。
### 设计理念
- **开箱即用**：内置权限管理、缓存、日志、异步任务等企业级功能
- **简单易用**：清晰的代码结构，完善的文档，降低学习成本
- **灵活扩展**：模块化设计，支持按需扩展和定制
- **生产就绪**：经过生产环境验证，可直接用于生产部署
---
## 核心特性
### 权限管理系统
#### 动态端点权限管理
- **自动检测路由**：启动时自动检测所有蓝图端点并写入数据库
- **细粒度权限控制**：支持端点级别的权限配置
- **继承机制**：支持端点权限继承，简化权限配置
- **YAML/数据库双模式**：支持 YAML 配置文件和数据库两种权限管理方式
#### RBAC 角色权限
- **多角色支持**：内置超级管理员、管理员、普通用户、游客等角色
- **角色-端点关联**：灵活配置角色可访问的端点
- **公共接口管理**：支持公共接口配置，无需登录即可访问
### 数据库与 ORM
#### SQLAlchemy 集成
- **模型基类**：提供统一的 `BaseModel`，内置软删除、审计字段、变更日志
- **智能查询**：集成搜索、排序、分页、过滤的统一查询方法
- **批量操作**：支持批量创建、批量更新，自动记录变更日志
- **数据库迁移**：基于 Flask-Migrate 的数据库版本管理
#### 软删除与审计
- **软删除**：避免唯一约束冲突，支持数据恢复
- **变更日志**：自动记录数据变更历史
- **审计字段**：自动记录创建者、更新者、创建时间、更新时间
### 缓存与会话管理
#### 多缓存后端
- **Redis 缓存**：高性能分布式缓存
- **SimpleCache**：轻量级内存缓存（开发环境）
- **统一接口**：缓存后端可无缝切换
#### 多 Session 存储
- **Redis Session**：分布式会话存储
- **Filesystem Session**：文件系统会话存储
- **灵活配置**：根据环境选择合适的存储方式
### 异步任务系统
#### Celery 多服务管理
- **YAML 配置**：通过 YAML 文件统一管理多个 Celery 服务
- **多队列支持**：每个服务可配置独立的任务队列
- **定时任务**：支持 Crontab 和秒数两种定时任务格式
- **并发控制**：可配置每个服务的 Worker 并发数
#### 分布式锁
- **Redis 锁**：基于 Redis 的分布式锁实现
- **防止重复**：避免并发任务重复执行
### 认证与安全
#### JWT 认证
- **Token 管理**：支持访问 Token 和刷新 Token
- **自动刷新**：Token 过期自动刷新机制
- **安全存储**：Token 存储在 Redis 中，支持过期控制
#### 权限验证
- **中间件拦截**：全局权限验证中间件
- **策略模式**：支持多种权限验证策略（认证、角色、管理员）
- **IP 记录**：自动记录客户端真实 IP
### 日志与监控
#### Loguru 日志
- **结构化日志**：支持请求日志、响应日志、错误日志
- **日志分级**：根据状态码自动选择日志级别
- **敏感信息过滤**：自动过滤密码等敏感信息
- **请求追踪**：记录请求耗时、IP、用户等信息
#### 请求日志
- **请求记录**：自动记录所有请求信息到数据库
- **错误追踪**：详细记录错误堆栈和位置
### 全文搜索
#### Whoosh 搜索
- **中文分词**：集成 Jieba 中文分词
- **多字段搜索**：支持多字段联合搜索
- **排名排序**：搜索结果按相关性排序
### 开发工具
#### CLI 命令
- **模块创建**：一键创建模块目录结构
- **角色初始化**：快速初始化系统角色
- **根用户创建**：创建超级管理员账户
- **数据导入**：支持 Excel 数据批量导入
- **Schema 生成**：自动从模型生成 Marshmallow Schema
#### Marshmallow 自动生成
- **模板驱动**：基于模板自动生成 Schema 代码
- **类型安全**：自动映射模型字段到 Schema 字段
### 其他功能
#### WebSocket 支持
- **实时通信**：支持 WebSocket 长连接
- **SocketIO 集成**：基于 Flask-SocketIO
#### gRPC 支持
- **高性能 RPC**：支持 gRPC 服务调用
- **Proto 管理**：支持 Proto 文件生成
#### 邮件服务
- **Flask-Mail**：内置邮件发送功能
- **模板支持**：支持 HTML 邮件模板
#### 分页支持
- **Flask-Paginate**：内置分页功能
- **自动计算**：自动计算页码和偏移量
#### 统一响应
- **Response 封装**：统一的 API 响应格式
- **错误码管理**：标准化的错误码定义
#### 环境配置
- **多环境支持**：支持 product、test 等多环境配置
- **环境变量**：基于 python-dotenv 的环境变量管理
#### Gunicorn 部署
- **生产配置**：内置 Gunicorn 配置
- **Eventlet 支持**：支持 Eventlet 协程
#### 事件总线
- **发布订阅**：基于事件的解耦机制
- **灵活扩展**：支持事件监听和触发
---
## 快速开始
### 环境要求
- **Python**: >= 3.12
- **MySQL**: >= 8.0.19
- **Redis**: >= 8.2.2
### 安装步骤
#### 1. 克隆项目
```bash
git clone
cd flaskicu
```
#### 2. 创建虚拟环境（推荐）
```bash
python -m venv venv
source venv/bin/activate # Linux/Mac
# 或
venv\Scripts\activate # Windows
```
#### 3. 安装依赖
```bash
pip install -r requirements.txt -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple
```
#### 4. 配置环境变量
复制环境变量模板文件：
```bash
cp .env.template .env.product # 生产环境
# 或
cp .env.template .env.test # 测试环境
```
编辑 `.env.product` 文件，配置以下关键项：
```env
# 环境标识
APP_ENV=product
# 数据库配置
DB_TYPE=mysql
DB_DRIVER=pymysql
DB_USERNAME=your_username
DB_PASSWORD=your_password
DB_NAME=your_database
DB_HOST=localhost
DB_PORT=3306
# Redis配置
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0
REDIS_PASSWORD=your_redis_password
# Flask配置
FLASK_HOST=0.0.0.0
FLASK_PORT=5000
FLASK_DEBUG=False
SECRET_KEY=your_secret_key
# 缓存配置
CACHE_TYPE=redis
# Session配置
SESSION_TYPE=redis
# 权限配置
IS_OPEN_AUTH_ROUTER=True
IS_DYNAMIC_ENDPOINT_MANAGE=True
IS_AUTO_CHECKOUT_ENDPOINT=True
# JWT配置
TOKEN_TIMEOUT_EXPIRE=3600
REFRESH_TOKEN_TIMEOUT_EXPIRE=2592000
# Gunicorn配置
GUNICORN_WORKERS=2
GUNICORN_WORKER_CLASS=eventlet
GUNICORN_WORKER_CONNECTIONS=1000
GUNICORN_TIMEOUT=60
```
#### 5. 初始化数据库
```bash
# 设置环境变量（Linux/Mac）
export APP_ENV=product
# 或（Windows）
set APP_ENV=product
# 创建数据库迁移
flask db init
flask db migrate -m "Initial migration"
flask db upgrade
# 初始化角色
flask init role
# 创建根用户(flask init root 参数1 参数2)
flask init root admin your_password
```
#### 6. 启动项目
**方式一：开发环境**
```bash
python app.py
```
**方式二：生产环境（Gunicorn）**
```bash
gunicorn -c gunicorn.py app:app
```
**方式三：使用启动脚本（Linux）**
```bash
# 编辑 start.sh，设置 APP_ENV=product
sh start.sh
```
#### 7. 启动 Celery（可选）
如果需要使用异步任务功能：
```bash
# 启动 Worker
celery -A celery_config.celery_manager:celery_manager.get_app('your_service_name') worker --loglevel=info -Q your_queue_name
# 启动 Beat（如果有定时任务）
celery -A celery_config.celery_manager:celery_manager.get_app('your_service_name') beat --loglevel=info
```
---
## 项目结构
```
flaskicu/
├── src/ # 源代码目录
│ ├── base/ # 基础模块
│ │ ├── base_model.py # 基础模型（软删除、审计、变更日志）
│ │ ├── blueprints.py # 蓝图注册
│ │ ├── endpoint_auth.py # 端点权限验证
│ │ ├── middleware.py # 中间件（请求日志、权限验证）
│ │ ├── exception.py # 全局异常处理
│ │ └── log/ # 日志模块
│ │ ├── change_log.py # 变更日志
│ │ └── request_log.py # 请求日志
│ │
│ ├── event_bus/ # 事件总线
│ │ └── core.py # 发布订阅核心
│ │
│ ├── handlers/ # 事件处理器
│ │ ├── user_handler.py # 用户事件处理器
│ │ ├── role_handler.py # 角色事件处理器
│ │ └── menu_button_handler.py # 菜单按钮事件处理器
│ │
│ ├── tasks/ # Celery 异步任务
│ │ └── common.py # 通用任务
│ │
│ ├── user/ # 用户模块
│ │ ├── models.py # 用户模型
│ │ ├── service.py # 用户服务
│ │ ├── views.py # 用户视图
│ │ └── public_views.py # 公共用户视图
│ │
│ ├── role/ # 角色模块
│ │ ├── models.py # 角色模型
│ │ ├── service.py # 角色服务
│ │ ├── views.py # 角色视图
│ │ └── secondary_models.py # 辅助模型
│ │
│ ├── endpoint/ # 端点模块
│ │ ├── models.py # 端点模型
│ │ ├── service.py # 端点服务
│ │ └── views.py # 端点视图
│ │
│ ├── menu/ # 菜单模块
│ ├── button/ # 按钮模块
│ ├── dictionary/ # 字典模块
│ ├── history/ # 历史记录模块
│ ├── mobile_information/ # 移动端信息模块
│ ├── mobile_version_user/ # 移动端用户模块
│ ├── mobile_download_qrcode/ # 移动端下载二维码模块
│ └── __init__.py # 模块初始化
│
├── celery_config/ # Celery 配置
│ ├── celery_manager.py # Celery 管理器
│ ├── celery_service.py # Celery 服务
│ ├── celery_settings.yml # Celery 配置文件
│ └── README.md # Celery 使用文档
│
├── rpc/ # gRPC 相关
│ ├── chat/ # 聊天服务
│ ├── generated/ # 生成的 Proto 文件
│ └── street_fight_rpc/ # 街霸 RPC 服务
│
├── utils/ # 工具函数
│ ├── enums.py # 枚举定义
│ ├── log.py # 日志配置
│ ├── response.py # 响应封装
│ ├── generate.py # 代码生成工具
│ ├── locks.py # 分布式锁
│ ├── faker/ # 测试数据生成
│ └── static/ # 静态资源
│
├── migrations/ # 数据库迁移文件
│ ├── alembic.ini # Alembic 配置
│ ├── env.py # 迁移环境
│ └── versions/ # 迁移版本
│
├── templates/ # 模板文件
│ ├── email_template.html # 邮件模板
│ └── ...
│
├── logs/ # 日志目录
├── configs.py # 配置管理
├── factory.py # Flask 应用工厂
├── app.py # 应用入口
├── cli.py # CLI 命令
├── gunicorn.py # Gunicorn 配置
├── marshmallow_auto_tool.py # Marshmallow 自动生成工具
├── requirements.txt # 依赖列表
├── .env.template # 环境变量模板
├── .env.product # 生产环境配置
├── endpoints_permissions.yaml # 端点权限配置
├── start.sh # 启动脚本
├── start_celery.sh # Celery 启动脚本
└── README.md # 项目文档
```
---
## 开发指南
### 创建新模块
使用 CLI 命令快速创建模块：
```bash
flask module create
```
这将在 `src/` 目录下创建包含以下文件的模块：
- `__init__.py` - 模块初始化
- `models.py` - 数据模型
- `service.py` - 业务逻辑
- `views.py` - 视图函数
### 注册蓝图
在 `src/base/blueprints.py` 中注册你的蓝图：
```python
from src.your_module.views import your_blueprint
def register_blueprints(app):
# 在对应的蓝图组中注册
blueprint_groups = {
'admin': {
'blueprint_params': {...},
'sub_blueprints': [
(your_blueprint, '/your-module'),
# ...
]
}
}
```
### 定义模型
继承 `BaseModel` 创建你的模型：
```python
from src.base.base_model import BaseModel
from src import db
class YourModel(BaseModel):
__tablename__ = 'your_table'
name = db.Column(db.String(100), nullable=False)
description = db.Column(db.Text)
# 定义可搜索字段
__searchable__ = ['name', 'description']
```
### 使用智能查询
```python
from src.your_module.models import YourModel
# 搜索、排序、分页
result = YourModel.search_order_paginate(
search='keyword',
order='desc',
sort_by='created_date',
page=1,
per_page=10,
fields=['name'],
ops=['=='],
values=['value']
)
```
### 配置端点权限
在 `endpoints_permissions.yaml` 中配置端点权限：
```yaml
endpoints:
admin.your_module.your_endpoint:
requires_auth: true
roles: ["admin", "root"]
```
### 创建 Celery 任务
1. 在 `celery_settings.yml` 中定义服务：
```yaml
services:
your_service:
name: "your_service"
include: ["src.tasks.your_tasks"]
queue: "your_queue"
concurrency: 2
```
2. 创建任务文件 `src/tasks/your_tasks.py`：
```python
from celery_config.celery_manager import celery_manager
app = celery_manager.get_app('your_service')
@app.task(name='your_task_name')
def your_task():
# 任务逻辑
pass
```
3. 启动 Worker：
```bash
celery -A celery_config.celery_manager:celery_manager.get_app('your_service') worker --loglevel=info -Q your_queue
```
### 使用事件总线
```python
from src import event_bus
# 订阅事件
def on_user_created(user):
print(f"User created: {user.username}")
event_bus.on('user.created', on_user_created)
# 触发事件
event_bus.emit('user.created', user)
```
### 生成 Marshmallow Schema
```bash
flask model auto src/your_module/models.py
```
### 数据导入
准备 Excel 文件，然后执行：
```bash
flask data import your_excel_file.xlsx
```
---
## 配置说明
### 环境变量
| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| APP_ENV | 环境标识（product/test） | product |
| DB_TYPE | 数据库类型 | mysql |
| DB_DRIVER | 数据库驱动 | pymysql |
| DB_USERNAME | 数据库用户名 | - |
| DB_PASSWORD | 数据库密码 | - |
| DB_NAME | 数据库名称 | - |
| DB_HOST | 数据库主机 | localhost |
| DB_PORT | 数据库端口 | 3306 |
| REDIS_HOST | Redis 主机 | localhost |
| REDIS_PORT | Redis 端口 | 6379 |
| REDIS_DB | Redis 数据库 | 0 |
| SECRET_KEY | Flask 密钥 | - |
| CACHE_TYPE | 缓存类型（redis/simple） | redis |
| SESSION_TYPE | Session 类型（redis/filesystem） | redis |
| IS_DYNAMIC_ENDPOINT_MANAGE | 是否启用动态端点管理 | True |
| IS_AUTO_CHECKOUT_ENDPOINT | 是否自动检测端点 | True |
| TOKEN_TIMEOUT_EXPIRE | Token 过期时间（秒） | 3600 |
### 权限配置
#### 启用动态端点管理
在 `.env.product` 中设置：
```env
IS_DYNAMIC_ENDPOINT_MANAGE=True
IS_AUTO_CHECKOUT_ENDPOINT=True
```
#### 配置端点权限
编辑 `endpoints_permissions.yaml`：
```yaml
default:
requires_auth: true
roles: ["*"]
endpoints:
public.auth.login:
requires_auth: false
roles: ["*"]
```
---
## 部署指南
### Gunicorn 部署
```bash
gunicorn -c gunicorn.py app:app
```
Gunicorn 配置参数（在 `gunicorn.py` 中）：
```python
workers = 2
worker_class = 'eventlet'
worker_connections = 1000
timeout = 60
keepalive = 2
```
### Nginx 反向代理
```nginx
server {
listen 80;
server_name your_domain.com;
location / {
proxy_pass http://127.0.0.1:5000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
```
### Supervisor 管理
创建 `/etc/supervisor/conf.d/flaskicu.conf`：
```ini
[program:flaskicu]
command=/path/to/venv/bin/gunicorn -c /path/to/gunicorn.py app:app
directory=/path/to/flaskicu
user=www-data
autostart=true
autorestart=true
stderr_logfile=/var/log/flaskicu.err.log
stdout_logfile=/var/log/flaskicu.out.log
```
---
## 常见问题
### 如何切换缓存后端？
修改 `.env.product` 中的 `CACHE_TYPE`：
```env
CACHE_TYPE=simple # 或 redis
```
### 如何重置数据库？
```bash
flask db downgrade base
flask db upgrade
```
### 如何查看日志？
日志文件位于 `logs/` 目录，文件名格式为 `log_YYYYMMDD_HHMMSS.log`。
---
## 技术栈
| 类别 | 技术 |
|------|------|
| Web 框架 | Flask 3.1.0 |
| ORM | SQLAlchemy |
| 数据库迁移 | Flask-Migrate |
| 数据验证 | Marshmallow |
| 缓存 | Redis / SimpleCache |
| 异步任务 | Celery |
| 日志 | Loguru |
| 全文搜索 | Whoosh + Jieba |
| 认证 | JWT |
| WebSocket | Flask-SocketIO |
| gRPC | gRPC + Protobuf |
| 部署 | Gunicorn |
| 协程 | Eventlet / Gevent |
---
## 贡献指南
欢迎贡献代码！请遵循以下步骤：
1. Fork 本项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request
---
## 开源协议
本项目基于 [MIT License](./LICENSE) 开源协议。
---
**如果这个项目对您有帮助，请给一个 ⭐️ Star！**
Made with ❤️ for Flask Developers