diff --git a/README.md b/README.md index f688d28..9b3953c 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ Pear Admin Layui Version - Python Version + Python Version Mysql Version @@ -59,7 +59,7 @@ Pear Admin Flask 基于 Flask 的后台管理系统，拥抱应用广泛的pytho # 版本支持情况 -经过测试，此项目的（master分支）运行要求是 `>= Python 3.8` ，推荐使用 `Python 3.9`。 +经过测试，此项目的（master分支）运行要求是 `>= Python 3.8` ，推荐使用 `Python 3.11`。 > **💡提示** 由于 Flask 中使用的 Werkzeug 模块更新，Flask 官方并未进行更新，所以可能会出现 ImportError 。 > 此类情况的出现可以通过正确安装 `requirements.txt` 中的模块（以及其对应版本）解决。 @@ -69,19 +69,19 @@ Pear Admin Flask 基于 Flask 的后台管理系统，拥抱应用广泛的pytho ## 应用结构 ```应用结构 -Pear Admin Flask -├─applications # 应用 -│ ├─extensions # 注册插件 -│ ├─models # 数据模型 -│ ├─static # 静态资源文件 -│ ├─templates # 静态模板文件 -│ └─views # 视图部分 -│ ├─admin # 后台管理视图模块 -│ └─index # 前台视图模块 +Pear Admin Flask (master) +├─applications # 项目核心模块 +│ ├─common # 公共模块（初始化数据库、公用函数） +│ ├─extensions # 注册项目插件 +│ ├─schemas # 序列化模型 +│ ├─models # 数据库模型 +│ ├─views # 视图部分 +│ ├─config.py # 项目配置 +│ └─__init__.py # 项目初始化入口 ├─docs # 文档说明 -├─migrations # 迁移文件记录 -├─requirement # 依赖文件 -└─.env # 项目的配置文件 +├─static # 静态资源文件 +├─templates # 静态模板文件 +└─app.py # 程序入口 ``` ## 资源结构 @@ -159,7 +159,7 @@ python -m venv venv # 进入虚拟环境下 venv\Scripts\activate.bat # Windows 提示命令符 venv\Scripts\Activate.ps1 # Windows Powershell -. venv/bin/activate # Linux +source venv/bin/activate # Linux # 使用 pip 安装 pip install -r requirements.txt diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..92dd33a --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/detail.md b/docs/detail.md deleted file mode 100644 index 7d60398..0000000 --- a/docs/detail.md +++ /dev/null @@ -1,44 +0,0 @@ -## 项目介绍 :id=start - -欢迎阅读 Pear Admin Flask 的开发文档！Pear Admin Flask 是一个基于 Flask 的后台管理系统，拥抱应用广泛的 Python 语言，通过使用本系统，即可快速构建你的功能业务。 - -项目旨在为 Python 开发者提供一个后台管理系统的模板，成为您构建信息管理系统、物联网后台等应用时灵活、简单的工具。 - -同时，Pear Admin Flask 项目也是一个对于 Python 初学者友好的项目。此项目处于开发初期，欢迎各位 Python 爱好者加入到 Pear Admin Flask 项目建设中来。如果您在使用此项目的过程中，发现项目代码存在问题，请在 Gitee 上提交 PR ，一起开源共建！ - -接下来，我们将会为您详细介绍该项目搭建方法与开发架构。 - -> 如果对项目有不理解的地方欢迎加入我们的讨论群。 - -![QQ群](assets/qqgroup.jpg) - -> 微信群不定期在qq群更新二维码。 - -![开始使用](assets/界面演示.jpeg) - -**[master分支版本](https://gitee.com/pear-admin/pear-admin-flask/tree/master/)** - -flask 2.0.1 + flask-sqlalchemy + 权限验证 + Flask-APScheduler 定时任务 + marshmallow 序列化与数据验证 - -master 分支为主分支，是功能最全、页面最多的分支。 - -![开始使用](assets/界面演示.jpeg) - -## 下载使用 :id=download - - -#### 1. 官网地址 - -官网提供稳定版本的 Release 发行版本 [前往](http://www.pearadmin.com) - -![官方网址](assets/官网地址.jpg) - -#### 2. 源码仓库 - -如果你需要最新代码，请前往 Gitee 仓库 [前往](https://gitee.com/pear-admin/pear-admin-flask) - -![源码仓库](assets/源码仓库.jpg) - - -如果您完成了这一步，请参阅[下载安装](install.md)章节。 - diff --git a/docs/install.md b/docs/install.md deleted file mode 100644 index c4b2002..0000000 --- a/docs/install.md +++ /dev/null @@ -1,114 +0,0 @@ -### 环境要求 :id=install -- Python >= 3.6 -- Mysql >= 5.7.0 - -### 安装配置 - -#### 克隆远程仓库 - -您可以使用 git 来克隆远程仓库： - -```shell -# 进入项目主目录 -cd Pear Admin Flask - -# 使用 git 克隆远程仓库 -git clone https://gitee.com/pear-admin/pear-admin-flask.git - -# 切换分支 -git checkout master # master, main or mini -``` - -或者直接前往 Pear Admin Flask 项目的[Gitee 主页](https://gitee.com/pear-admin/pear-admin-flask)下载项目仓库。 - -#### 搭建开发环境 - -我们推荐使用 Python 的虚拟环境来开发该项目，这样便于项目的迁移与二次开发。当然，您也可以选择使用原 Python 环境。 - -如果你想创建 Python 虚拟环境，你可以使用下面的命令行： - -```shell -# 在当前目录的venv文件夹创建虚拟环境 -python -m venv venv - -# Windows 激活虚拟环境 -.\test_env\Scripts\Activate.ps1 - -# Linux 和 Mac 激活虚拟环境 -source ./test_env/bin/activate -``` - -**如果在创建虚拟环境时报错 “ModuleNotFoundError” ，这说明您的 Python 版本小于 3.3 。** - -#### 安装项目依赖 - -```shell -# 使用 pip 安装必要模块（对于 master 分支） -pip install -r requirements.txt - -# 使用 pip 安装必要模块（对于 mini 分支） -pip install -r requirement.txt -``` - -或者您可以尝试： - -```shell -# 使用 pip 安装必要模块 -python -m pip install -r requirement.txt -``` - -#### 配置数据库 - -在 `applications/config.py` 中配置好数据库。 - -> 由于结构与目录调整，我们简化了项目结构，废弃了文件 ```.flaskenv``` ，请使用 config.py 配置程序。 - -并使用以下命令生成数据库文件： - -```shell -# 初始化数据库 -flask db init -flask db migrate -flask db upgrade -flask admin init -``` - -#### 运行项目 - -```shell -# windows -run.bat - -# linux -./run.sh -``` - -#### 使用docker-compose运行项目 - -```shell -# 安装docker-compose -curl -L https://github.com/docker/compose/releases/download/1.26.2/docker-compose-`uname -s`-`uname -m` > /usr/local/bin/docker-compose -chmod +x /usr/local/bin/docker-compose -ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose - -docker-compose --version -docker-compose up -d # -d后台运行 -docker-compose stop # 停止启动 -docker-compose down # 清除容器 - -dockerdata/config.py # 配置文件 -dockerdata/mysql/initdb/ # MySQL初始化数据在 -rm -rf dockerdata/mysql/{log,data}/* # down掉容器后启动需要清除删除log,dat -``` - -### 二次开发 - -恭喜！现在您已经成功搭建并运行了 Pear Admin Flask ，是时候参与开发了： - -请阅读： - -+ Pear Admin Flask [目录结构](list.md) 章节 -+ Pear Admin Flask [开发函数](function.md) 章节 -+ Pear Admin Flask [插件开发](plugin.md) 章节 - -其它章节等待更新。 diff --git a/docs/list.md b/docs/list.md deleted file mode 100644 index 891fa73..0000000 --- a/docs/list.md +++ /dev/null @@ -1,43 +0,0 @@ -## 应用结构 :id=config -```应用结构 -Pear Admin Flask -├─applications # 应用 -│ ├─configs # 配置文件 -│ │ ├─ common.py # 普通配置 -│ │ └─ config.py # 配置文件对象 -│ ├─extensions # 注册插件 -│ ├─models # 数据模型 -│ ├─static # 静态资源文件 -│ ├─templates # 静态模板文件 -│ └─views # 视图部分 -│ ├─admin # 后台管理视图模块 -│ └─index # 前台视图模块 -├─docs # 文档说明 -├─migrations # 迁移文件记录 -├─requirement # 依赖文件 -└─.env # 项目的配置文件 -``` - -## 资源结构 :id=static -```资源结构 -Pear Admin Flask -├─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 # 主页模板 -``` \ No newline at end of file diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..b01af03 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,2 @@ +del _build /s /q +sphinx-build .\source .\_build \ No newline at end of file diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..27eabc6 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,3 @@ +sphinx>=5 +docutils<=0.21 +sphinx-rtd-theme \ No newline at end of file diff --git a/docs/source/_static/login.png b/docs/source/_static/login.png new file mode 100644 index 0000000..430271b Binary files /dev/null and b/docs/source/_static/login.png differ diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..b9732fc --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,28 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'Pear Admin Flask master 分支' +copyright = '2025, Yishang' +author = 'Yishang' +release = 'master' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = ["sphinx.ext.intersphinx"] + +templates_path = ['_templates'] +exclude_patterns = [] + +language = 'zh_CN' + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'sphinx_rtd_theme' +html_static_path = ['_static'] diff --git a/docs/source/function/index.rst b/docs/source/function/index.rst new file mode 100644 index 0000000..2031ba7 --- /dev/null +++ b/docs/source/function/index.rst @@ -0,0 +1,9 @@ +.. title:: 公有函数 + +目录索引 + +.. toctree:: + :maxdepth: 1 + + utils/index.rst + diff --git a/docs/source/function/utils/cache.rst b/docs/source/function/utils/cache.rst new file mode 100644 index 0000000..839f6bf --- /dev/null +++ b/docs/source/function/utils/cache.rst @@ -0,0 +1,2 @@ +程序缓存模块 +===================== \ No newline at end of file diff --git a/docs/source/function/utils/index.rst b/docs/source/function/utils/index.rst new file mode 100644 index 0000000..50c0807 --- /dev/null +++ b/docs/source/function/utils/index.rst @@ -0,0 +1,8 @@ +.. title:: 辅助函数 + +目录索引 + +.. toctree:: + :maxdepth: 1 + + cache diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..1a19ccb --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,23 @@ +目录索引 +================== + +.. note:: + 您好！欢迎查看 Pear Admin Flask **master 分支** 开发文档！你可以查看 :ref:`welcome` 章节来查看更多信息。 + Pear Admin Flask 项目经过长时间的发展现已是一个比较成熟的 Python 后台框架，非常适合新手学习入门 Python Flask ~ + +.. warning:: + 项目经过几次大型修改之后，为了同步项目 Pear Admin Layui ，部分（特别是前端页面的）代码改动较大，若要从旧版本进行迁移， + 请根据文档的 :ref:`migration` 章节进行迁移与改变。 + +.. toctree:: + :maxdepth: 1 + :caption: 介绍、配置与使用 + + welcome/index + +.. toctree:: + :maxdepth: 1 + :caption: 公有函数 + + function/index + diff --git a/docs/source/welcome/index.rst b/docs/source/welcome/index.rst new file mode 100644 index 0000000..1cf9565 --- /dev/null +++ b/docs/source/welcome/index.rst @@ -0,0 +1,11 @@ +.. title:: 介绍、配置与使用 + +目录索引 + +.. toctree:: + :maxdepth: 1 + + instruction + update + quickstart + migration diff --git a/docs/source/welcome/instruction.rst b/docs/source/welcome/instruction.rst new file mode 100644 index 0000000..e7d307a --- /dev/null +++ b/docs/source/welcome/instruction.rst @@ -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 + +
+
+
+

+ Pear Admin Flask +

+

+ 开 箱 即 用 的 Flask 快 速 开 发 平 台 +

+ +

+ + Pear Admin Layui Version + + + Python Version + + + Mysql Version + +

+
+ +
+ +
+ +项目简介 +--------------- + +Pear Admin Flask 基于 Flask 的后台管理系统，拥抱应用广泛的python语言，通过使用本系统，即可快速构建你的功能业务 +项目旨在为 python 开发者提供一个后台管理系统的模板，可以快速构建信息管理系统。 + +项目使用 flask-sqlalchemy + 权限验证 + marshmallow 序列化与数据验证，以此方式集成了若干不同的功能。 + +内置功能 +---------- + +- **用户管理**：用户是系统操作者，该功能主要完成系统用户配置。 +- **权限管理**：配置系统菜单，操作权限，按钮权限标识等。 +- **角色管理**：角色菜单权限分配。 +- **操作日志**：系统正常操作日志记录和查询；系统异常信息日志记录和查询。 +- **登录日志**：系统登录日志记录查询包含登录异常。 +- **服务监控**：监视当前系统 CPU、内存、磁盘、Python 版本、运行时长等相关信息。 +- **文件上传**：图片上传示例。 + +项目分支说明 +--------------- + +.. warning:: + Pear Admin Flask 不仅仅只提供一种对于 Pear Admin 后端的实现方式，所以提供了不同的分支版本，不同分支版本各有其优劣，并且由不同的开发者维护 + +.. list-table:: + :header-rows: 1 + + * - 分支名称 + - 特点 + * - `master `_ + - 功能齐全，处于开发阶段，代码量较大。 + * - `main `_ + - 功能精简，代码量小，处于开发阶段，易于维护。 + * - `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 组件库 `_ 。 +* 后端 Flask 学习可以参考官方的 `Flask 开发文档 `_ 。 +* Pear Admin 框架的源码可以查看 `Pear Admin 开源仓库 `_ 。 +* 开发时可以选择 `PyCharm `_ 作为集成开发环境 。 \ No newline at end of file diff --git a/docs/source/welcome/migration.rst b/docs/source/welcome/migration.rst new file mode 100644 index 0000000..0d9f0c2 --- /dev/null +++ b/docs/source/welcome/migration.rst @@ -0,0 +1,98 @@ +.. _migration: + +从旧项目迁移 +================= + +由于 `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 + + + +更正为： + +.. code-block:: html + + + + +公用模板修改 +~~~~~~~~~~~~~~~~~~~~~~~~ + +移除了 ``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 + + + + +改为： + +.. code-block:: html + + + + +.. tip:: + + 你会注意到修改之后的 layui-btn-primary 属性添加在了 “重置” 按钮上，而不是 “查询” 按钮上， + 这是因为 layui-btn-primary 是默认白色的，而不加 layui-btn-primary 属性是跟随主题色的。这里需要特别注意一下。 + + + diff --git a/docs/source/welcome/quickstart.rst b/docs/source/welcome/quickstart.rst new file mode 100644 index 0000000..0be2f7d --- /dev/null +++ b/docs/source/welcome/quickstart.rst @@ -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` 。 + diff --git a/docs/source/welcome/update.rst b/docs/source/welcome/update.rst new file mode 100644 index 0000000..7ab5799 --- /dev/null +++ b/docs/source/welcome/update.rst @@ -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，等待主项目合并。 \ No newline at end of file