考试刷题系统 - 启动运行指南

环境要求

项目架构说明

本项目是前后端完全分离的架构：

• 后端（Flask）只提供 RESTful JSON API，不渲染任何页面
• 管理后台（Vue3）是独立的 SPA 单页应用，通过 HTTP 请求调用后端 API
• 用户端（UniApp）是独立的跨平台客户端，同样通过 HTTP 请求调用后端 API
• 三个项目可以独立部署、独立运行，通过 API 接口通信
• 认证方式为 JWT Token，前端每次请求在 Header 中携带 Authorization: Bearer <token>

这意味着：后端部署一套，前端可以对接任意数量的客户端（网页、App、小程序、甚至第三方系统），互不影响。

鉴权机制详解

本项目使用 JWT（JSON Web Token） 进行身份认证，流程如下：

鉴权流程

1. 用户登录 → 后端验证密码 → 生成 JWT Token → 返回给前端2. 前端保存 Token（localStorage / uni.setStorageSync）3. 后续每次请求 → 前端在请求头中带上 Token → 后端验证 Token → 确认身份4. Token 过期或无效 → 后端返回 401 → 前端跳转登录页

完整示例（以管理员登录并查看用户列表为例）

第1步：登录获取 Token

请求：

POST /api/auth/loginContent-Type: application/json{"username": "admin", "password": "admin123"}

响应：

{"code": 200,"message": "登录成功","data": {"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxIiwiZXhwIjoxNzE4...","user": {"id": 1, "username": "admin", "role": "admin"}  }}

第2步：携带 Token 访问受保护接口

请求：

GET /api/admin/users?page=1&per_page=20Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxIiwiZXhwIjoxNzE4...

响应：

{"code": 200,"message": "success","data": {"items": [...], "total": 5, "page": 1}}

第3步：Token 缺失或过期时

请求（没带 Token）：

GET /api/admin/users

响应：

HTTP 401 Unauthorized

三种权限级别

前端实现方式

管理后台（Vue3 axios 拦截器）：

// 每次请求自动带上 Tokenrequest.interceptors.request.use(config => {const token = localStorage.getItem('token')if (token) {    config.headers.Authorization = `Bearer ${token}`  }return config})

UniApp 用户端：

// uni.request 中设置 headerheader: {'Authorization': token ? `Bearer ${token}` : ''}

Token 有效期

• 默认 24 小时过期（配置在 backend/config.py 的 JWT_ACCESS_TOKEN_EXPIRES）
• 过期后需重新登录获取新 Token

一、数据库初始化

1. 创建数据库并导入表结构

mysql -u root -p < database/01_create_tables.sql

2. 导入测试数据

mysql -u root -p < database/02_test_data.sql

3. 测试账号

二、后端启动（Flask）

1. 进入后端目录

cd backend

2. 创建虚拟环境（推荐）

python -m venv venv# Windowsvenv\Scripts\activate# Mac/Linuxsource venv/bin/activate

3. 安装依赖

pip install -r requirements.txt

4. 修改数据库配置

编辑 backend/config.py，修改以下字段为你的 MySQL 信息：

MYSQL_HOST = "127.0.0.1"MYSQL_PORT = 3306MYSQL_USER = "root"MYSQL_PASSWORD = "你的密码"MYSQL_DB = "exam_system"

5. 启动后端服务

python run.py

启动成功后显示：

 * Running on http://0.0.0.0:5000

6. 验证后端

浏览器访问 http://localhost:5000/api/categories ，能看到 JSON 数据即成功。

三、管理后台启动（Vue3 + Element Plus）

1. 进入管理后台目录

cd admin-web

2. 安装依赖

npm install

3. 启动开发服务器

npm run dev

启动后访问 http://localhost:3000

4. 登录

使用管理员账号 admin / admin123 登录。

5. 注意事项

• 管理后台已配置代理，/api 请求会转发到 http://localhost:5000
• 确保后端服务已启动
• 如需修改后端地址，编辑 vite.config.js 中的 proxy.target

四、UniApp 用户端（HBuilderX）

1. 安装 HBuilderX

下载地址：https://www.dcloud.io/hbuilderx.html

选择「App开发版」下载安装。

2. 导入项目到 HBuilderX

1. 打开 HBuilderX
2. 菜单栏 → 文件 → 导入 → 从本地目录导入
3. 选择项目中的 uni-app 文件夹（完整路径，如 D:\你的项目\uni-app）
4. 点击「导入」
5. 导入后左侧项目管理器中应看到 uni-app 项目，展开可见 pages.json、App.vue、main.js 等文件

重要确认项：

• manifest.json 中必须包含 "vueVersion": "3"（本项目已配置）
• uni.scss 文件必须存在于项目根目录
• index.html 文件必须存在于项目根目录
• static/tab/ 目录下的 tabBar 图标文件必须存在（home.png、home-active.png、exam.png、exam-active.png、mine.png、mine-active.png）

3. 修改后端接口地址

编辑 uni-app/utils/request.js，修改 BASE_URL：

// 本地开发（模拟器/电脑浏览器）const BASE_URL = 'http://localhost:5000/api'// 手机真机调试（改为电脑局域网IP）// const BASE_URL = 'http://192.168.x.x:5000/api'// 线上部署// const BASE_URL = 'https://你的域名/api'

4. 添加 TabBar 图标

在 uni-app/static/tab/ 目录下放置以下图标文件（81x81px PNG）：

• home.png / home-active.png
• exam.png / exam-active.png
• mine.png / mine-active.png

可以从 https://www.iconfont.cn 下载，或临时使用任意 PNG 图片命名即可。

5. 运行到不同平台

H5（浏览器）

1. 在左侧项目管理器中单击选中 uni-app 项目根目录（确保项目高亮激活）
2. 菜单栏 → 运行 → 运行到浏览器 → Chrome
3. 自动打开浏览器，访问 http://localhost:8080/#/
4. 如果显示白屏，检查 HBuilderX 控制台是否有编译错误，并确认 manifest.json 中有 "vueVersion": "3"
5. 修改配置后必须停止运行再重新运行（HBuilderX 需要重新编译）

微信小程序

1. 先安装微信开发者工具
2. 菜单栏 → 运行 → 运行到小程序模拟器 → 微信开发者工具
3. 首次运行需在 HBuilderX 设置中配置微信开发者工具路径：
• 工具 → 设置 → 运行配置 → 微信开发者工具路径
4. 在 manifest.json 中填写微信小程序 appid（可到微信公众平台申请测试号）

Android 模拟器/真机

1. 手机开启 USB 调试，连接电脑
2. 菜单栏 → 运行 → 运行到手机或模拟器
3. 选择设备后点击运行
4. 注意：真机调试时 BASE_URL 需改为电脑局域网 IP

iOS

1. 需要 Mac + Xcode
2. 菜单栏 → 运行 → 运行到手机或模拟器 → iOS 模拟器

6. 打包发布

Android APK

1. 菜单栏 → 发行 → 原生App-云打包
2. 选择 Android，配置证书（可用公共测试证书）
3. 点击打包，等待完成后下载 APK

微信小程序

1. 菜单栏 → 发行 → 小程序-微信
2. 在微信开发者工具中上传代码
3. 到微信公众平台提交审核

五、完整启动顺序

1. 启动 MySQL 服务2. 导入数据库（仅首次）3. 启动后端：cd backend && python run.py4. 启动管理后台：cd admin-web && npm run dev5. HBuilderX 运行 UniApp

六、打包部署

1. 后端打包部署（Flask）

Flask 生产环境不建议用 python run.py 直接运行，应使用 WSGI 服务器：

方式一：Gunicorn（Linux）

cd backendpip install gunicorn# 启动（4个worker进程）gunicorn -w 4 -b 0.0.0.0:5000 run:app

方式二：Waitress（Windows/Linux 通用）

cd backendpip install waitress# 启动python -c "from waitress import serve; from run import app; serve(app, host='0.0.0.0', port=5000)"

生产配置要点

1. 修改 config.py 中的 SECRET_KEY 和 JWT_SECRET_KEY 为随机强密码
2. 关闭 debug 模式（run.py 中 debug=False）
3. 配置 Nginx 反向代理到 5000 端口
4. 使用 systemd 或 supervisor 做进程管理

Nginx 参考配置

server {    listen 80;    server_name api.yourdomain.com;    location / {        proxy_pass http://127.0.0.1:5000;        proxy_set_header Host $host;        proxy_set_header X-Real-IP $remote_addr;    }}

2. 管理后台打包（Vue3）

cd admin-web# 构建生产包npm run build

构建完成后生成 dist/ 目录，内容为纯静态文件（HTML/CSS/JS）。

部署方式

将 dist/ 目录下所有文件部署到 Web 服务器（Nginx / Apache / 云存储 CDN）即可。

Nginx 配置（注意 history 模式路由）

server {    listen 80;    server_name admin.yourdomain.com;    root /path/to/admin-web/dist;    index index.html;    # Vue Router history 模式    location / {        try_files $uri $uri/ /index.html;    }    # API 代理到后端    location /api {        proxy_pass http://127.0.0.1:5000;    }}

注意事项

• 打包前修改 vite.config.js 中的 proxy 配置为生产环境 API 地址
• 或者在 src/utils/request.js 中将 baseURL 改为完整的后端地址（如 https://api.yourdomain.com/api）

3. UniApp 打包

3.1 打包为 H5（Web网页）

1. HBuilderX 中选中 uni-app 项目
2. 菜单栏 → 发行 → 网站-H5手机版
3. 打包完成后输出到 uni-app/unpackage/dist/build/h5/
4. 将该目录部署到 Web 服务器即可

注意： 打包前修改 utils/request.js 中的 BASE_URL 为生产环境地址

3.2 打包为 Android APK

方式一：云打包（推荐，无需本地环境）

1. HBuilderX 中选中 uni-app 项目
2. 菜单栏 → 发行 → 原生App-云打包
3. 选择 Android 平台
4. 证书配置：
• 开发测试：勾选「使用公共测试证书」
• 正式发布：需要自己生成 keystore 签名证书
5. 点击「打包」，等待云端编译（通常3-10分钟）
6. 完成后点击下载 APK 文件

方式二：离线打包（需要 Android Studio）

1. 菜单栏 → 发行 → 原生App-本地打包 → 生成本地打包App资源
2. 下载 DCloud 离线 SDK
3. 在 Android Studio 中集成 SDK 并导入资源
4. 使用 Android Studio 进行签名打包

3.3 打包为 iOS App

1. 需要 Mac 电脑 + Apple 开发者账号（$99/年）
2. HBuilderX 中选中 uni-app 项目
3. 菜单栏 → 发行 → 原生App-云打包
4. 选择 iOS 平台
5. 配置证书（.p12）和描述文件（.mobileprovision）
6. 点击打包，完成后下载 .ipa 文件
7. 通过 Transporter 或 Xcode 上传到 App Store Connect 提交审核

3.4 打包为微信小程序

1. HBuilderX 中选中 uni-app 项目
2. 菜单栏 → 发行 → 小程序-微信
3. 填写微信小程序 AppID（需在微信公众平台注册）
4. 编译完成后自动打开微信开发者工具
5. 在微信开发者工具中点击「上传」
6. 登录微信公众平台 → 版本管理 → 提交审核 → 发布

3.5 打包前检查清单

七、常见问题

Q: 后端启动报 ModuleNotFoundError

A: 确认已激活虚拟环境并安装了依赖：pip install -r requirements.txt

Q: 管理后台登录后页面报错

A: 确认后端已启动，且使用的是新登录获取的 token（修改代码后需重新登录）

Q: UniApp 请求接口报网络错误

A: 检查 BASE_URL 是否正确。模拟器用 localhost，真机用局域网 IP。确认后端 Flask 监听的是 0.0.0.0。

Q: MySQL 连接失败

A: 检查 backend/config.py 中的数据库用户名、密码、端口是否正确

Q: 小程序真机预览请求失败

A: 微信小程序要求后端必须是 HTTPS 域名。本地开发时在微信开发者工具中勾选「不校验合法域名」

Q: UniApp H5 运行后浏览器白屏

A: 检查以下几点：

1. manifest.json 中必须有 "vueVersion": "3"，否则 HBuilderX 会按 Vue2 编译导致白屏
2. 项目根目录必须有 uni.scss 文件（即使为空也要有）
3. 项目根目录必须有 index.html 模板文件
4. static/tab/ 下的 tabBar 图标文件必须存在（可以用任意 png 占位）
5. 修改 manifest.json 后需要停止运行再重新运行，HBuilderX 需要重新编译

Q: npm install 报错

A: 尝试清除缓存：npm cache clean --force，或使用淘宝镜像：npm install --registry=https://registry.npmmirror.com