完善快速开始文档
This commit is contained in:
wojiaoyishang
@@ -0,0 +1,11 @@
|
||||
.. title:: 介绍、配置与使用
|
||||
|
||||
目录索引
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
instruction
|
||||
update
|
||||
quickstart
|
||||
migration
|
||||
@@ -0,0 +1,150 @@
|
||||
.. _welcome:
|
||||
|
||||
项目介绍
|
||||
=================
|
||||
|
||||
.. note::
|
||||
该章节将会介绍 Pear Admin Flask 项目的一些基本信息，以及介绍在开发时需要使用到的工具链、文档。此项目是一个 Web 开发项目，前后端一体，
|
||||
在 layui 界面库的基础上进行二次封装以及开发。
|
||||
|
||||
.. important::
|
||||
项目经过几次大型修改之后，为了同步项目 Pear Admin Layui ，部分（特别是前端页面的）代码改动较大，若要从旧版本进行迁移，
|
||||
请根据文档的 :ref:`migration` 章节进行迁移与改变。如存在问题请在仓库中提交 issue 并标明分支，
|
||||
然后提供详尽的复现方法，感谢各位！
|
||||
**另外，对于 Pear Admin Layui 中未实现但是在 Pear Admin Flask 中实现的内容或者存在的部分问题，请参阅** :ref:`update` **章节。**
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<div align="center">
|
||||
<br/>
|
||||
<br/>
|
||||
<h1 align="center">
|
||||
Pear Admin Flask
|
||||
</h1>
|
||||
<h4 align="center">
|
||||
开 箱 即 用 的 Flask 快 速 开 发 平 台
|
||||
</h4>
|
||||
|
||||
<p align="center">
|
||||
<a href="#">
|
||||
<img src="https://img.shields.io/badge/pear%20admin%20flask-1.0.0-green" alt="Pear Admin Layui Version">
|
||||
</a>
|
||||
<a href="#">
|
||||
<img src="https://img.shields.io/badge/Python-3.8+-green.svg" alt="Python Version">
|
||||
</a>
|
||||
<a href="#">
|
||||
<img src="https://img.shields.io/badge/Mysql-5.3.2+-green.svg" alt="Mysql Version">
|
||||
</a>
|
||||
</p>
|
||||
</div>
|
||||
|
||||
<div align="center">
|
||||
<img width="92%" style="border-radius:10px;margin-top:20px;margin-bottom:20px;box-shadow: 2px 0 6px gray;" src="https://images.gitee.com/uploads/images/2020/1019/104805_042b888c_4835367.png" />
|
||||
</div>
|
||||
|
||||
项目简介
|
||||
---------------
|
||||
|
||||
Pear Admin Flask 基于 Flask 的后台管理系统，拥抱应用广泛的python语言，通过使用本系统，即可快速构建你的功能业务
|
||||
项目旨在为 python 开发者提供一个后台管理系统的模板，可以快速构建信息管理系统。
|
||||
|
||||
项目使用 flask-sqlalchemy + 权限验证 + marshmallow 序列化与数据验证，以此方式集成了若干不同的功能。
|
||||
|
||||
内置功能
|
||||
----------
|
||||
|
||||
- **用户管理**：用户是系统操作者，该功能主要完成系统用户配置。
|
||||
- **权限管理**：配置系统菜单，操作权限，按钮权限标识等。
|
||||
- **角色管理**：角色菜单权限分配。
|
||||
- **操作日志**：系统正常操作日志记录和查询；系统异常信息日志记录和查询。
|
||||
- **登录日志**：系统登录日志记录查询包含登录异常。
|
||||
- **服务监控**：监视当前系统 CPU、内存、磁盘、Python 版本、运行时长等相关信息。
|
||||
- **文件上传**：图片上传示例。
|
||||
|
||||
项目分支说明
|
||||
---------------
|
||||
|
||||
.. warning::
|
||||
Pear Admin Flask 不仅仅只提供一种对于 Pear Admin 后端的实现方式，所以提供了不同的分支版本，不同分支版本各有其优劣，并且由不同的开发者维护
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
|
||||
* - 分支名称
|
||||
- 特点
|
||||
* - `master <https://gitee.com/pear-admin/pear-admin-flask/tree/master/>`_
|
||||
- 功能齐全，处于开发阶段，代码量较大。
|
||||
* - `main <https://gitee.com/pear-admin/pear-admin-flask/tree/main/>`_
|
||||
- 功能精简，代码量小，处于开发阶段，易于维护。
|
||||
* - `mini <https://gitee.com/pear-admin/pear-admin-flask/tree/mini/>`_
|
||||
- 不再更新，是最初版本的镜像
|
||||
|
||||
版本支持情况
|
||||
---------------
|
||||
|
||||
经过测试，此项目的（master分支）运行要求是 ``>= Python 3.8`` ，推荐使用 ``Python 3.11``。
|
||||
|
||||
.. tip::
|
||||
由于 Flask 中使用的 Werkzeug 模块更新，Flask 官方并未进行更新，所以可能会出现 ImportError 。
|
||||
截止至 2025 年 1 月 26 日，若使用项目中 **requirements.txt** 不会出现该错误。
|
||||
|
||||
此类情况的出现可以通过正确安装 **requirements.txt** 中的模块（以及其对应版本）解决。
|
||||
|
||||
|
||||
目录架构
|
||||
--------------
|
||||
|
||||
应用结构
|
||||
~~~~~~~~~~
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
Pear Admin Flask (master)
|
||||
├─applications # 项目核心模块
|
||||
│ ├─common # 公共模块（初始化数据库、公用函数）
|
||||
│ ├─extensions # 注册项目插件
|
||||
│ ├─schemas # 序列化模型
|
||||
│ ├─models # 数据库模型
|
||||
│ ├─views # 视图部分
|
||||
│ ├─config.py # 项目配置
|
||||
│ └─__init__.py # 项目初始化入口
|
||||
├─docs # 文档说明
|
||||
├─static # 静态资源文件
|
||||
├─templates # 静态模板文件
|
||||
└─app.py # 程序入口
|
||||
|
||||
资源结构
|
||||
~~~~~~~~~~
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
Pear Admin Flask (master)
|
||||
├─static # 项目设定的 Flask 资源文件夹
|
||||
│ ├─admin # pear admin flask 的后端资源文件（与 pear admin layui 同步）
|
||||
│ ├─index # pear admin flask 的前端资源文件
|
||||
│ └─upload # 用户上传保存目录
|
||||
└─templates # 项目设定的 Flask 模板文件夹
|
||||
├─admin # pear admin flask 的后端管理页面模板
|
||||
│ ├─admin_log # 日志页面
|
||||
│ ├─common # 基本模板页面（头部模板与页脚模板）
|
||||
│ ├─console # 系统监控页面模板
|
||||
│ ├─dept # 部门管理页面模板
|
||||
│ ├─dict # 数据自动页面模板
|
||||
│ ├─mail # 邮件管理页面模板
|
||||
│ ├─photo # 图片上传页面模板
|
||||
│ ├─power # 权限（菜单）管理页面模板
|
||||
│ ├─role # 角色管理页面模板
|
||||
│ ├─task # 任务设置页面模板
|
||||
│ └─user # 用户管理页面模板
|
||||
├─errors # 错误页面模板
|
||||
└─index # 主页模板
|
||||
|
||||
开发资源
|
||||
-------------
|
||||
|
||||
由于项目依赖多个开源项目，而此开发文档并不会全进行涉足，所以提供如下的链接共大家开发参考：
|
||||
|
||||
* 前端页面设计可以参考 `layui 原生态 · 开源 极简模块化 Web UI 组件库 <https://layui.dev/>`_ 。
|
||||
* 后端 Flask 学习可以参考官方的 `Flask 开发文档 <https://flask.palletsprojects.com/zh-cn/stable/>`_ 。
|
||||
* Pear Admin 框架的源码可以查看 `Pear Admin 开源仓库 <https://gitee.com/pear-admin/pear-admin-layui>`_ 。
|
||||
* 开发时可以选择 `PyCharm <https://www.jetbrains.com/pycharm/>`_ 作为集成开发环境 。
|
||||
@@ -0,0 +1,98 @@
|
||||
.. _migration:
|
||||
|
||||
从旧项目迁移
|
||||
=================
|
||||
|
||||
由于 `Pear Admin Layui <https://gitee.com/pear-admin/pear-admin-layui>`_ 框架（下面将会称其为 “主项目”）的更新获得了更好的性能与新的功能，
|
||||
此项目 Pear Admin Flask 作为主项目的附属项目将会在一定时间进行迁移与同步。由于主项目的更新，此项目的部分功能被弃用这大大增加了同步的难度，所以在一段时间
|
||||
内，此项目并未有同步的打算。为了获得性能更新，此项目于 2025 的新年前后开始逐步将项目代码进行同步与完善，迫不得已舍去了部分功能，这为以往基于此项目的作品更新
|
||||
加大了难度，所以便有了此迁移章节。各位开发者，如果您想要同步自己原先以项目为基础的作品，请阅读该章节。
|
||||
|
||||
.. _migration1:
|
||||
|
||||
迁移到 v2.0.0-4.0.5 版本
|
||||
----------------------------
|
||||
|
||||
更正验证码生成模块引用
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
由于 ``applications/common/utils/gen_captcha.py`` 更名为 ``applications/common/utils/captcha.py`` ，需要修改导入引用。
|
||||
|
||||
例如：
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from applications.common.utils.gen_captcha import vieCode
|
||||
|
||||
更正为：
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from applications.common.utils.captcha import vieCode
|
||||
|
||||
|
||||
后台首页路径修改
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
由于为了对齐主项目，``system/console/console.html`` 更名为 ``system/analysis/main.html``，前端页面需要进行修改。
|
||||
|
||||
例如：
|
||||
|
||||
.. code-block:: html
|
||||
|
||||
<a href="system/console/console.html"></a>
|
||||
|
||||
更正为：
|
||||
|
||||
.. code-block:: html
|
||||
|
||||
<a href="system/analysis/main.html"></a>
|
||||
|
||||
|
||||
公用模板修改
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
移除了 ``templates/system/common/memory.html`` ，该文件原先仅用于系统监控页面，现在换为 JavaScript 函数进行换算。
|
||||
详情参阅模板文件 ``templates/system/monitor.html``
|
||||
|
||||
|
||||
移除 Pear Button 模块
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
由于主项目不再使用 Pear Button 而直接使用 Layui Button。所以需要将所有的按钮 class 中的 “pear-btn” 变为 “layui-btn”。
|
||||
（附属的 pear-btn-* 也要修改，建议是直接搜索替换。）
|
||||
|
||||
|
||||
例如：
|
||||
|
||||
.. code-block:: html
|
||||
|
||||
<button class="pear-btn pear-btn-primary pear-btn-md" lay-submit lay-filter="dept-query">
|
||||
<i class="layui-icon layui-icon-search"></i>
|
||||
查询
|
||||
</button>
|
||||
<button type="reset" class="pear-btn pear-btn-md">
|
||||
<i class="layui-icon layui-icon-refresh"></i>
|
||||
重置
|
||||
</button>
|
||||
|
||||
改为：
|
||||
|
||||
.. code-block:: html
|
||||
|
||||
<button class="layui-btn layui-btn-md" lay-submit lay-filter="dept-query">
|
||||
<i class="layui-icon layui-icon-search"></i>
|
||||
查询
|
||||
</button>
|
||||
<button type="reset" class="layui-btn layui-btn-primary layui-btn-md">
|
||||
<i class="layui-icon layui-icon-refresh"></i>
|
||||
重置
|
||||
</button>
|
||||
|
||||
.. tip::
|
||||
|
||||
你会注意到修改之后的 layui-btn-primary 属性添加在了 “重置” 按钮上，而不是 “查询” 按钮上，
|
||||
这是因为 layui-btn-primary 是默认白色的，而不加 layui-btn-primary 属性是跟随主题色的。这里需要特别注意一下。
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,169 @@
|
||||
快速开始
|
||||
=========================
|
||||
|
||||
此章节将介绍 Pear Admin Flask 搭建的方法，将会 Python 搭建与 Docker 自动构建两种方法。
|
||||
|
||||
克隆仓库
|
||||
-----------------
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
git clone https://gitee.com/pear-admin/pear-admin-flask
|
||||
cd pear-admin-flask # 进入到项目目录
|
||||
|
||||
Python 部署
|
||||
-----------------
|
||||
|
||||
创建虚拟环境
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
推荐使用虚拟环境，如果您不想使用虚拟环境请跳过这一步。
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
python -m venv venv
|
||||
|
||||
venv\Scripts\activate.bat # Windows 提示命令符
|
||||
venv\Scripts\Activate.ps1 # Windows Powershell
|
||||
source venv/bin/activate # Linux
|
||||
|
||||
|
||||
安装必要模块
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# 使用 pip 安装
|
||||
pip install -r requirements.txt
|
||||
|
||||
# 另外，如果上述无效，你可以选择以模块的方式调用 pip
|
||||
python -m pip install -r requirements.txt
|
||||
|
||||
设置配置文件
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
打开文件 `applications/config.py` 进行编辑，在其中配置数据库等相关信息，默认采用的是 sqlite3 存储项目数据。
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# 数据库的配置信息
|
||||
SQLALCHEMY_DATABASE_URI = 'sqlite:///../pear.db'
|
||||
|
||||
.. important::
|
||||
|
||||
注意！在实际项目中一定要修改 SECRET_KEY 参数！否则存在 Cookie 中的 session 被破解的情况。
|
||||
|
||||
初始化数据库
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
随后需要初始化数据库。
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
flask db init
|
||||
flask db migrate
|
||||
flask db upgrade
|
||||
flask admin init
|
||||
|
||||
运行项目（调试模式）
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
可以使用 flask 对项目进行调试运行。此方式仅用于生产环境。
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
flask run
|
||||
|
||||
# 或者使用
|
||||
python app.py
|
||||
|
||||
|
||||
发布项目
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
推荐使用 `gunicorn` 对项目进行发布。
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pip install gunicorn # 安装 gunicorn
|
||||
|
||||
# 运行项目
|
||||
gunicorn -b 0.0.0.0:5000 app:app
|
||||
|
||||
|
||||
如果部分平台（如 Windows）不能使用 `gunicorn` 可以尝试使用 `pywsgi` 。
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pip install gevent # 安装 gevent
|
||||
|
||||
并修改 app.py 文件为：
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from applications import create_app
|
||||
|
||||
from gevent import pywsgi
|
||||
|
||||
app = create_app()
|
||||
|
||||
if __name__ == '__main__':
|
||||
# app.run()
|
||||
server = pywsgi.WSGIServer(('0.0.0.0', 7000), app)
|
||||
server.serve_forever()
|
||||
|
||||
随后在控制台中：
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# 运行项目
|
||||
python app.py
|
||||
|
||||
Docker 部署
|
||||
-------------------
|
||||
|
||||
设置配置文件
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
打开文件 `applications/config.py` 进行编辑，在其中配置数据库等相关信息，默认采用的是 sqlite3 存储项目数据。
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# 数据库的配置信息
|
||||
SQLALCHEMY_DATABASE_URI = 'sqlite:///../pear.db'
|
||||
|
||||
.. important::
|
||||
|
||||
注意！在实际项目中一定要修改 SECRET_KEY 参数！否则存在 Cookie 中的 session 被破解的情况。
|
||||
|
||||
部署
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
随后确保 docker 环境已经安装，并在控制台中输入（目录要切换到项目根目录）：
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
docker-compose -f dockerdata/docker-compose.yaml up
|
||||
|
||||
.. tip::
|
||||
|
||||
你可以在 `dockerdata/docker-compose.yaml` 和 `dockerdata/Dockerfile` 中调整映射的端口，和项目默认开发的端口与行为。
|
||||
容器每次重启会执行 `dockerdata/start.sh` ，故可以在其中配置 Docker 容器的系统。
|
||||
|
||||
|
||||
浏览项目
|
||||
------------------
|
||||
|
||||
|
|
||||
|
||||
.. image:: ../_static/login.png
|
||||
:align: center
|
||||
|
||||
|
|
||||
|
||||
打开 `http://127.0.0.1:5000` （在未调整端口配置的情况下），可以打开项目的登录页面，默认的用户名与密码分别为 ``admin`` 与 ``123456`` 。
|
||||
|
||||
.. tip::
|
||||
|
||||
旧版的登录页面保留在了 `templates/system/login_old.html` 。
|
||||
|
||||
@@ -0,0 +1,55 @@
|
||||
.. _update:
|
||||
|
||||
更新日志
|
||||
================
|
||||
|
||||
此章节展示更新说明。
|
||||
|
||||
版本号说明
|
||||
----------------------
|
||||
|
||||
版本号由主版本号、次版本号、修订号和 Pear Admin Layui 版本号组成。
|
||||
|
||||
2025 年 1 月 26 日（v2.0.0-4.0.5）
|
||||
------------------------------------
|
||||
|
||||
.. important::
|
||||
|
||||
同步与迁移查看 :ref:`migration1` 章节。
|
||||
|
||||
* 权限管理（后台框架）增加 组件（_component） 打开方式，根据 Pear Admin Layui ，此方式将会将目标页面作为 div 嵌入框架内部。
|
||||
* 权限管理完善批量删除的功能（先前没有实现）。
|
||||
* 增加 权限管理、角色管理 等添加、更新路由的参数效验。（先前参数输错会导致程序崩溃）
|
||||
* 修改增加编辑页面中的 sort（排序） 参数的输入框为数字输入。
|
||||
* 修改编辑页面的默认留空文本。将默认的“请输入标题”改为更合理的内容。
|
||||
* 修改了权限名称中对于 “权限编辑” 权限的标注错误。
|
||||
* 修复没有子部门的公司无法删除的问题
|
||||
* 修复操作日志和登录日志接口查询相反和接口匹配错误的问题
|
||||
* 系统监控改为异步操作，并完善系统监控的功能
|
||||
* 删除字典时会一并删除字典值（特性更新）
|
||||
* 流程修改，超级管理员也会被记录日志
|
||||
* 修复邮件发送设置后台路由错误的问题
|
||||
* 后台首页文件修改，system/console/console.html --> system/analysis/main.html
|
||||
* 验证码生成模块重命名 gen_captcha --> captcha
|
||||
* 移除文件 system/common/memory.html（此原先仅作用于系统监控）
|
||||
* 移除前端框架模块 botton.js （pear-btn） ，故前端页面中的 pear-btn 需要替换为 layui-btn ( 直接搜索替换，其附属的 pear-btn- 都要替换* )
|
||||
* 保留了前端框架中未使用的模块（在 Pear Admin Layui 已经移除），但是默认不启用，需要自行在 static/system/component/pear/pear.js 和 static/system/component/pear/css/pear.css 添加
|
||||
* 加入了程序缓存模块，applications/common/utils/cache.py
|
||||
* 增加后台消息接口
|
||||
* 系统监控中对硬盘的获取，如果是在 docker 中就获取根目录的数据
|
||||
* 更正登录之后重定向由于路由更改从而设置错误的问题
|
||||
|
||||
已知问题以及解决方式
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
主项目 Pear Admin Layui 存在如下的问题：
|
||||
|
||||
* 对于组件式嵌入页面（_component），存在 JavaScript 无法解绑的问题，由于无法解除 JavaScript 注册，可能会因为不同页面的同标识的按钮绑定到同一个事件。
|
||||
* 主项目无法对子页面（iframe）同步更新主题色和修改夜间模式。
|
||||
* 主项目无法刷新以 iframe 嵌入的子页面。
|
||||
|
||||
对此给出的解决方法如下：
|
||||
|
||||
* 仅后台主页和个人资料页面使用组件方式嵌入，其余使用 iframe 嵌入。
|
||||
* 在框架中添加 JavaScript 脚本，用于通知所有子 iframe 改变颜色。
|
||||
* 修改 admin.js 并提交 PR，等待主项目合并。
|
||||
Reference in New Issue
Block a user