后端启动

本章节介绍如何将后端项目从官网下载到本地并成功启动运行。后端基于 Python + Flask 框架，采用分层架构设计（Router 层 → Service 层 → Repository 层 → Model 层）。

温馨提示

启动后端前，请确保已完成环境准备章节中的所有软件安装。

获取源码

前往官方网站购买授权后，按以下步骤获取源码：

1. 登录官方网站，进入「个人中心」→「我的订单」页面。
2. 在订单列表中找到已购买的授权订单，点击「下载」按钮。
3. 下载的压缩包包含完整的前后端源码、数据库脚本及部署配置文件。
4. 将压缩包解压到本地开发目录（如 E:\Projects\ 或 ~/Projects/）。

bash

# 进入项目根目录（以实际解压路径为准）
cd djangoadmin

温馨提示

源码包请务必从官方网站订单中心下载，确保获取的是正版授权的最新版本。
授权有效期内可无限次下载最新版本，版本更新后可重新下载获取最新源码。
解压后请先阅读根目录下的 README.md 和 CHANGELOG.md 了解版本更新内容。
如需使用 Git 管理代码，可在解压后自行初始化仓库：git init && git add . && git commit -m "init"。

项目目录结构如下：

├── src/               # 后端源码
│ ├── app.py           # 启动入口
│ ├── core/            # 核心模块（数据库、缓存、认证、响应等）
│ ├── routes/          # 路由层（HTTP 接口定义）
│ ├── modules/         # 业务模块（模型、仓库、服务）
│ ├── middleware/      # 中间件（认证、事务、日志、操作记录等）
│ └── common/          # 公共模块（基类、常量、工具函数等）
├── ui/                # 前端源码（独立仓库或子目录）
├── config/            # 配置文件（base / database / redis / auth）
├── docker/            # Docker 部署配置（Dockerfile / docker-compose.yml）
├── scripts/           # 脚本工具（数据库初始化、数据迁移等）
├── migrations/        # Flask-Migrate 数据库迁移文件
├── tests/             # 测试代码
├── .env.example       # 环境变量示例文件
├── requirements.txt   # Python 依赖清单
└── Makefile           # 常用命令集合

安装依赖

进入项目根目录，使用 pip 安装后端依赖包：

bash

# 安装运行时依赖
pip install -r requirements.txt

温馨提示

如果网络较慢，可先配置 pip 镜像源（参见环境准备），或使用国内镜像临时安装：

bash

pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/

验证依赖安装

bash

# 检查 Flask 是否安装成功
python -c "import flask; print(flask.__version__)"
3.1.3

# 检查 SQLAlchemy 是否安装成功
python -c "import sqlalchemy; print(sqlalchemy.__version__)"
2.0.51

温馨提示

依赖安装完成后，如果上述命令输出版本号，说明核心依赖已正确安装。

配置环境变量

项目通过 .env 文件管理所有配置参数。首次使用需要从示例文件复制并修改：

bash

# 复制环境变量示例文件
cp .env.example .env # Linux / macOS
copy .env.example .env # Windows CMD

编辑 .env 文件

使用文本编辑器打开 .env 文件，修改以下关键配置：

bash

# ============================================================
# 基础配置
# ============================================================
FLASK_NAME=DjangoAdmin Flask+EleVue旗舰版
FLASK_VERSION=v3.0.0
FLASK_HOST=0.0.0.0
FLASK_PORT=8021
FLASK_ENV=development
FLASK_DEBUG=True

# ============================================================
# 数据库配置（根据实际情况修改）
# ============================================================
DB_DRIVER=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=djangoadmin.flask.elevue
DB_USERNAME=root
DB_PASSWORD=your_mysql_password # 修改为真实密码
DB_PREFIX=flask_

# ============================================================
# Redis 缓存配置（根据实际情况修改）
# ============================================================
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=your_redis_password # 修改为真实密码
REDIS_AUTH=True

# ============================================================
# JWT 令牌配置（必填项）
# ============================================================
# 生成方式：python -c "import secrets; print(secrets.token_urlsafe(48))"
JWT_SALT=your_jwt_secret_key_at_least_16_chars
JWT_EXPIRE_MINUTES=20

重要提示

JWT_SALT 是 JWT 令牌的签名密钥，必须设置且至少 16 字符。留空会导致应用拒绝启动。可使用以下命令生成：

bash

python -c "import secrets; print(secrets.token_urlsafe(48))"

DB_PASSWORD 和 REDIS_PASSWORD 请填写真实的服务密码。
生产环境务必设置 FLASK_DEBUG=False，避免泄漏内部错误信息。

初始化数据库

首次启动前，需要初始化数据库结构和种子数据。

方式一：手动导入（推荐）

bash

# 1. 登录 MySQL，创建数据库
mysql -uroot -p
CREATE DATABASE `djangoadmin.flask.elevue` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

# 2. 导入数据库脚本（脚本位于 document/mysql/ 目录下）
mysql -uroot -p djangoadmin.flask.elevue < document/mysql/djangoadmin.flask.elevue.sql

温馨提示

项目支持 MySQL、PostgreSQL、SQL Server、SQLite、Oracle 等数据库，对应的 SQL 脚本分别存放在 document/ 目录下的对应文件夹中（mysql/、postgresql/、sqlserver/、sqlite/、oracle/）。请根据你使用的数据库类型选择对应的脚本导入。详细的多数据库初始化步骤请参考数据库初始化章节。

方式二：脚本初始化（备选）

bash

# 自动完成建库、建表、导入种子数据
python scripts/setup_db.py

温馨提示

脚本初始化会根据 .env 中的 DB_DRIVER 配置，自动查找 document/{driver}/ 目录下的 SQL 脚本并执行，同时完成建库、建表、导入种子数据和 Flask-Migrate 版本标记。

注意事项

执行初始化前，请确保数据库服务已启动，并且 .env 中的数据库连接信息正确。

启动后端服务

一切准备就绪后，执行以下命令启动后端服务：

bash

# 方式一：直接运行（推荐，适用于所有操作系统）
python app.py

# 方式二：使用 Flask 命令启动
flask run --host=0.0.0.0 --port=8021

启动入口说明

app.py 是应用入口，核心代码如下：

python

# app.py
from src.app import create_app

app = create_app()

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=8021, debug=True)

create_app() 是应用工厂函数（位于 src/app.py），负责组装中间件链、注册路由、配置全局异常处理器和扩展初始化（Redis 连接池 + 定时任务调度器）。

启动成功后，终端将输出类似以下信息：

 * Serving Flask app 'app'
 * Debug mode: on
 * Running on http://0.0.0.0:8021 (Press CTRL+C to quit)
 * Restarting with stat
 * Debugger is active!
 * Debugger PIN: 123-456-789

默认端口

后端服务默认监听端口为 8021，可通过 .env 文件中的 FLASK_PORT 参数修改。

验证后端服务

测试接口连通性

使用 curl 或浏览器访问健康检查接口：

bash

# 测试服务是否正常响应
curl http://127.0.0.1:8021/api/v1/captcha

返回类似以下 JSON 即表示服务正常运行：

json

{
    "code": 0,
    "data": {
        "captcha": "data:image/png;base64,...",
        "key": "sl1dhi-ejqV2PWH8tYDE1pVNaRiccsrQ"
    },
    "msg": "操作成功",
    "ok": true
}

查看日志输出

在终端中观察后端日志输出，确认无异常错误信息。如果出现连接数据库或 Redis 失败的错误，请检查 .env 配置和相关服务是否正常运行。

Makefile 常用命令

项目根目录的 Makefile 提供了常用命令的快捷方式。

Windows 用户注意

make 命令是 Linux / macOS 系统自带的构建工具，Windows 系统默认不包含。Windows 用户有以下选择：

直接执行对应命令：表格中"对应命令"列所示的原始命令，如 python app.py、python scripts/setup_db.py 等。
安装 make 工具：通过 scoop install make、choco install make 或 winget install GnuWin32.Make 安装。
使用 Git Bash：安装 Git for Windows 后，自带的 Git Bash 环境支持 make 命令。

命令	对应命令	说明
`make install`	`pip install -r requirements.txt`	安装生产依赖
`make install-dev`	`pip install -r requirements-dev.txt`	安装开发依赖（含测试/规范工具）
`make dev`	`python app.py`	启动开发服务
`make lint`	`flake8 + black --check + isort --check-only`	静态检查
`make format`	`black + isort`	自动格式化
`make type-check`	`mypy src`	类型检查
`make test`	`pytest`	运行全部测试
`make test-cov`	`pytest --cov=src`	带覆盖率运行测试
`make db-migrate`	`flask db migrate`	生成迁移脚本
`make db-upgrade`	`flask db upgrade`	应用迁移到最新
`make db-downgrade`	`flask db downgrade`	回滚一次迁移
`make docker-up`	`cd docker && docker-compose up -d`	启动 Docker 服务
`make docker-down`	`cd docker && docker-compose down`	停止 Docker 服务
`make clean`	清理 `__pycache__` / `.pyc` / `.pytest_cache`	清理缓存与临时文件

常见问题

端口被占用

如果启动时报错 Address already in use，说明端口 8021 已被其他程序占用：

bash

# Windows 查看端口占用
netstat -ano | findstr 8021

# Linux / macOS 查看端口占用
lsof -i :8021

解决方式：终止占用进程，或修改 .env 中的 FLASK_PORT 为其他端口。

JWT_SALT 未配置

如果启动时报错 JWT_SALT must be set，说明未配置 JWT 签名密钥。请在 .env 文件中设置：

bash

JWT_SALT=your_generated_secret_key_here

数据库连接失败

如果启动时报错 Can't connect to MySQL server，请检查：

1. MySQL 服务是否已启动
2. .env 中的 DB_HOST、DB_PORT、DB_USERNAME、DB_PASSWORD 是否正确
3. 防火墙是否放行了数据库端口

总结

本章节介绍了后端项目的完整启动流程：拉取代码 → 安装依赖 → 配置环境变量 → 初始化数据库 → 启动服务。通过以上步骤，你已经成功将后端服务运行在本地 8021 端口。下一步可以进入前端启动章节，启动前端项目并登录系统。

🔐 认证与安全

📊 数据与配置

📝 日志与监控

🛡️ 防护与治理

🔄 事务管理

📁 文件处理

🔧 核心工具

🧩 辅助工具

后端启动

获取源码

安装依赖

配置环境变量

初始化数据库

方式一：手动导入（推荐）

方式二：脚本初始化（备选）

启动后端服务

验证后端服务

Makefile 常用命令

常见问题

总结

Become a sponsor

企业级中台解决方案

企业级中台解决方案

后端启动 ​

获取源码 ​

安装依赖 ​

配置环境变量 ​

初始化数据库 ​

方式一：手动导入（推荐） ​

方式二：脚本初始化（备选） ​

启动后端服务 ​

验证后端服务 ​

Makefile 常用命令 ​

常见问题 ​

总结 ​

后端启动

获取源码

安装依赖

配置环境变量

初始化数据库

方式一：手动导入（推荐）

方式二：脚本初始化（备选）

启动后端服务

验证后端服务

Makefile 常用命令

常见问题

总结