Fred Admin

基于 Flask 的后台管理框架，开箱即用的企业级脚手架。

特性

• 快速初始化：一条命令生成完整项目结构
• 模块化设计：支持多模块热加载，业务隔离
• 内置 Admin：完整的后台管理系统（前后端）
• 定时任务：APScheduler 持久化到数据库，重启自动恢复
• 多数据库：默认 SQLite，可切换 MySQL
• Swagger 文档：自动生成 API 文档
• 国际化：内置多语言支持

安装

pip install fred_admin

快速开始

# 1. 创建项目目录
mkdir myproject && cd myproject

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

# 3. 安装框架
pip install fred_admin

# 4. 初始化项目
fred-init

# 5. 启动应用
python app.py

访问 http://127.0.0.1:5000 即可看到管理后台。

目录结构

框架包结构（fred_admin）

fred_admin/
├── __init__.py           # create_app() 入口
├── install_hook.py       # fred-init 命令实现
├── create_module.py      # fred-create 命令实现
├── common/               # 框架核心组件
│   ├── AliyunSms.py      # 阿里云短信
│   ├── Blueprints.py     # 蓝图自动注册
│   ├── Email.py          # 邮件发送
│   ├── Extensions.py     # 扩展初始化（DB、JWT、Scheduler等）
│   ├── HandleExcetion.py # 全局异常处理
│   ├── ImageVerification.py # 图片验证码
│   ├── PageSchema.py     # 分页 Schema
│   ├── Response.py       # 统一响应格式
│   ├── Route.py          # SPA 路由与静态资源
│   ├── RuntimeHook.py    # 运行时模块加载钩子
│   ├── Sqlacodegen.py    # 数据库模型自动生成
│   ├── Swagger.py        # Swagger UI 配置
│   ├── SystemLog.py      # 系统日志
│   ├── Utils.py          # 工具函数
│   └── WechatLogin.py    # 微信登录
├── config/               # 框架默认配置
│   ├── Config.py         # 默认配置项
│   └── Logger.py         # 日志配置
├── fonts/                # 字体文件
└── _template/            # 项目模板（fred-init 复制源）
    ├── app.py            # 应用入口模板
    ├── common/           # 公共模块模板
    ├── data/             # 数据库文件（app.db、fred.sql）
    ├── docs/             # 文档模板
    ├── modules/          # 模块模板
    │   └── admin/        # 内置 Admin 模块
    │       ├── backend/  # 后端（controller/service/schema）
    │       ├── frontend/ # 前端源码（Vue 3 + TypeScript）
    │       └── templates/# 前端构建产物
    └── requirements.txt

初始化后的项目结构

myproject/
├── app.py                # 应用入口
├── common/               # 项目公共模块
│   ├── config/
│   │   ├── Config.py          # 项目配置（覆盖框架默认值）
│   │   └── Config.example.py  # 完整可覆盖项目录（可选参考）
│   └── model/
│       └── model.py      # 数据库模型（sqlacodegen 生成）
├── data/                 # 数据文件
│   ├── app.db            # SQLite 数据库
│   └── fred.sql          # SQL 初始化脚本
├── docs/                 # 项目文档
├── logs/                 # 日志目录
├── modules/              # 业务模块
│   └── admin/            # 内置 Admin
│       ├── backend/
│       │   ├── constant/ # 常量定义
│       │   ├── controller/ # 控制器（API 入口）
│       │   ├── schema/   # 请求/响应 Schema
│       │   └── service/  # 业务逻辑层
│       ├── frontend/     # 前端源码
│       └── templates/    # 前端构建产物
├── requirements.txt      # 项目依赖
└── .gitignore

配置说明

项目配置位于 common/config/Config.py，只需配置项目特有项，其余使用框架默认值。
完整可覆盖项目录见模板 common/config/Config.example.py（与 fred_admin.config.Config 键对齐）；框架源码注释见 src/fred_admin/config/Config.py。

必须配置

基础配置

模块加载

门户 qiankun CORS

子系统嵌入 gss-portal 时开启；最外层 WSGI，带 credentials，不被 after_request 信封冲掉。

数据库

# SQLite（默认，无需安装）
SQLALCHEMY_DATABASE_URI = 'sqlite:///data/app.db'

# MySQL
SQLALCHEMY_DATABASE_URI = 'mysql+pymysql://user:pwd@127.0.0.1:3306/db'

# 多数据库绑定
SQLALCHEMY_BINDS = {'other': 'mysql+pymysql://user:pwd@127.0.0.1:3306/other'}

Redis

REDIS_URL = 'redis://:password@127.0.0.1:6379/1'

JWT 配置

日志配置

Swagger 配置

定时任务

邮件配置

阿里云短信

路由映射

ROUTE_CONFIG = {
    'upload': 'upload',       # /upload/<path> -> upload/
    'download': 'download'    # /download/<path> -> download/
}

命令行工具

fred-init

初始化项目，将模板复制到当前目录：

fred-init

• 复制 app.py、common/、data/、modules/ 等
• demo_ 前缀文件自动重命名为隐藏文件（.gitignore 等）
• 自动构建前端（如 templates/ 不存在）

fred-create

创建业务模块：

fred-create user    # 创建 user 模块

• 生成 modules/user/backend/（controller/service/schema）
• 生成 modules/user/frontend/（Vue 前端）
• 文档写入 docs/modules/user.md

代码规范

后端规范（Python）

• 代码风格: 遵循 PEP 8，使用 Google 风格注释
• 目录分层: controller → service → model，职责清晰
• 蓝图注册: 控制器使用 MethodView，自动注册到蓝图
• Schema 验证: 使用 marshmallow 定义请求/响应 Schema
• 异常处理: 统一通过 HandleException 捕获，返回标准格式
• 日志: 使用 app.logger，格式统一

前端规范（Vue 3 + TypeScript）

JS/TS 规范

• 使用 Composition API (<script setup>)
• 优先 let/const，禁止 var
• 禁止未使用变量、空函数
• 类型明确，避免 any

CSS/SCSS 规范

• 组件样式 scoped，避免全局污染
• 使用 SCSS 变量与 CSS 变量保持主题一致性
• 属性顺序遵循 recess-order

Vue 组件规范

• 使用 <script setup> 语法
• 语义化标签，避免内联样式
• Props 单向数据流，命名连字符化

Git 提交规范

• type 限定: feat/fix/docs/style/refactor/perf/test/build/ci/chore/revert
• 分支命名: feature/xxx, fix/xxx, docs/xxx
• 提交前自动执行 ESLint + Prettier + Stylelint

前端构建

cd modules/admin/frontend

# 安装依赖
pnpm install

# 开发模式
pnpm dev

# 生产构建（输出到 ../templates/）
pnpm build:pro

模块开发

后端模块结构

modules/
└── your_module/
    └── backend/
        ├── constant/     # 常量（如 RedisKey.py）
        ├── controller/   # 控制器（API 入口）
        ├── schema/       # 请求/响应验证
        └── service/      # 业务逻辑

定时任务

在 modules/your_module/backend/service/SchedulerTasks.py 中定义任务函数：

def your_task():
    # 任务逻辑
    return {'success': True, 'message': 'done'}

通过管理后台或 API 添加定时任务，任务会持久化到数据库，重启后自动恢复。

License

MIT