kadupul-git

检澜.桥梁安全训练检测系统

检澜（DockScope）

检澜 DockScope 是面向桥梁安全隐患智能检测的一体化工作台：围绕「媒体 / 模型 / 模型训练 / 检测任务 / 结果与指标 / 台账与报告」闭环，提供 Web 端界面与 REST API。本仓库为检澜前后端源码——前端 Vue 3 + Element Plus + ECharts（bridge-disease-frontend-main）；后端 Flask + SQLAlchemy + MySQL（BridgeDiseaseBackend-main），检测推理基于 Ultralytics YOLO，对影像中的结构隐患区域进行识别、标注与量化评估。

---

检澜核心功能

账号与权限

• 注册 / 登录 / 忘记密码：表单提交至后端，成功后下发 JWT（Access + Refresh），前端持久化于 localStorage 并在 Axios 拦截器中自动携带 Authorization: Bearer …。
• 个人中心：查看与维护当前用户资料、头像等。
• 角色模型：ADMIN（管理员）、DEVELOPER（开发人员）、USER（普通用户）。部分菜单与列表接口按角色区分（见下节「角色与界面」）。

数据看板（/home）

• 登录后的默认工作台：侧栏导航、面包屑、数据洞察与社群快捷入口等壳层组件，以及基于 ECharts 的历史统计图表（StatisticsCharts）。

模型训练（/model-training）

• ADMIN / DEVELOPER 可见（侧栏紧跟在「数据看板」之后）：上传 Ultralytics YOLO 格式数据集（ZIP，内含 data.yaml），选择 YOLOv8n/s/m-seg 基线权重启动分割训练。
• 训练在 Flask 进程内以后台线程执行（无需单独起训练服务）；任务列表展示排队 / 训练中 / 已完成 / 失败，支持刷新与自动恢复排队任务。
• 完成后可将 best.pt 自动注册到模型库（含 mAP 等指标）；任务元数据持久化于 data/training_meta/jobs.json。
• 数据与产物目录：BridgeDiseaseBackend-main/data/datasets、data/training_runs、app/static/models。
• 文档与模板：docs/TRAINING_DATASET.md、training_templates/data.yaml.example。
• 试跑演示 ZIP：cd BridgeDiseaseBackend-main && python scripts/create_demo_dataset.py → training_templates/bridge_hazard_demo.zip（CPU 建议 yolov8n-seg、epochs=5、batch=2）。

桥梁安全隐患检测（/disease-detection）

• 三步向导：选择 检测模型（.pt）→ 选择 媒体（图像或视频）→ 发起 安全隐患检测。
• 后端调用 YOLO 推理，生成标注结果图并计算隐患指标（数量、周长、面积、形状复杂度、纹理粗糙度、裂缝宽度、平均色调等），综合得到严重度得分与隐患等级（轻 / 中 / 重 / 严重）。
• 支持任务状态（待处理、检测中、已完成、失败）与实时进度展示。

安全隐患检测记录（/detection-records）

• 分页列表：模型名、媒体名、任务状态、严重度、隐患等级、检测标注结果、检测时间、所属用户等。
• 支持筛选、导出 Excel、详情对话框查看指标明细与耗时。
• 管理员 / 开发人员可查看全量记录；普通用户通常仅能看到本人记录。

批量安全隐患检测（/batch-detection）

• 一次选择模型与多条媒体，以队列方式模拟批量检测任务（开发演示）。
• 支持自动 / 手动推进进度，完成后可将结果写入安全隐患台账。
• 数据持久化于浏览器 localStorage（dockscope_professional_v1），非后端 API。

安全隐患台账（/defect-ledger）

• 汇聚 AI 检测与批量任务发现的隐患，支持复核、确认、处置与销项。
• 可从检测记录导入、按状态 / 等级筛选。
• 数据同样为前端 localStorage 演示，便于产品演示与流程验证。

报告中心（/report-center）

• 巡检周报、专项检测报告、监测预警汇总等模板，生成记录并导出 Excel。
• 报告数据基于上述前端专业模块 store 汇总，非后端持久化。

媒体库（/media-library）

• 上传与管理巡检图片（png/jpg/jpeg）与视频（mp4），写入服务器静态目录并在数据库登记元数据。
• 列表预览通过 /file/... 访问（需后端可访问对应文件）。
• 可使用 scripts/seed_medias.py 导入真实桥梁照片种子（见「数据种子脚本」）。

模型库（/model-library）

• 上传与管理 YOLO 权重（.pt），供检测页选用。
• 侧栏仅对 DEVELOPER 可见；ADMIN 与普通用户不展示该入口。

物联网监测（前端演示）

以下四个模块共用 localStorage（dockscope_iot_monitoring_v1），用于展示监测业务界面，未接后端：

路由	功能
/sensor-management	传感器登记、阈值与在线状态
/data-collection	采集任务与原始数据浏览
/data-processing	清洗、聚合与特征处理
/alert-management	预警规则、分级与处置

用户管理（/user-management）

• 面向 管理员或开发人员：用户列表、状态与角色维护。

系统操作日志（/operation-logs）

• 面向 管理员或开发人员：登录、检测执行、失败原因等审计记录（Operation 实体）。

开发辅助：列表 Mock

• 当前端设置 VITE_USE_LIST_MOCK=true 时，安全隐患检测记录与媒体库列表可走本地 src/mocks/detectionAndMediaMockData.js，无需后端即可调试表格布局。

---

角色与界面

侧栏菜单顺序（SidebarMenu.vue）

1. 数据看板
   
2. 模型训练（仅 ADMIN / DEVELOPER）
   
3. 桥梁安全隐患检测
   
4. 安全隐患检测记录
   
5. 批量安全隐患检测
   
6. 安全隐患台账
   
7. 报告中心
   
8. 媒体库
   
9. 传感器管理 → 数据采集 → 数据处理 → 预警管理（物联网演示）
   
10. 模型库（仅 DEVELOPER）
    
11. 用户管理、系统操作日志（ADMIN / DEVELOPER）

角色可见入口

角色	典型可见菜单
USER	数据看板、桥梁安全隐患检测、安全隐患检测记录、批量检测、安全隐患台账、报告中心、媒体库、物联网监测四模块
DEVELOPER	上述 + 模型训练（第 2 项）+ 模型库 + 用户管理 + 系统操作日志
ADMIN	与 USER 相同业务菜单 + 模型训练（第 2 项）+ 用户管理 + 系统操作日志（无模型库）

路由见 bridge-disease-frontend-main/src/router/index.js；菜单见 src/components/SidebarMenu.vue。产品对外文案常量见 src/shellConstants.js（副标题：桥梁安全隐患智能检测工作台）。

---

检澜技术架构

总体部署视图

flowchart LR
  subgraph Browser[浏览器]
    SPA[检澜前端 Vue 3 / Element Plus]
  end
  subgraph Host[宿主机或服务器]
    NG[Nginx 托管检澜静态前端]
    API[检澜 API Flask :5000]
  end
  subgraph Data[数据层]
    MySQL[(MySQL 8 utf8mb4)]
    FS[本地静态目录\nmedias / models / results / avatars]
  end
  SPA -->|页面与 REST JSON| NG
  SPA -->|开发模式直连 API| API
  NG -.->|生产镜像中浏览器直连| API
  API --> MySQL
  API --> FS

逻辑分层

层级	前端	后端
表现层	views/*.vue、components/**	Flask 路由（各 *_route.py）
应用状态	stores/*（用户、资源列表、IoT、专业模块等）	JWT、Operation、限流
领域与数据	Axios src/utils/request.js	SQLAlchemy Models（User、Media、Model、Detection、Operation）
推理	—	detection_route 中 Ultralytics YOLO、OpenCV / Pillow 等

后端 API 蓝图前缀

URL 前缀	职责概要
/user	注册、登录、令牌刷新、用户资料
/media	媒体上传与分页列表
/model	模型上传与分页列表
/detection	发起安全隐患检测、检测记录分页查询等
/training	数据集上传、YOLOv8 训练任务、进度/日志、恢复排队任务（ADMIN / DEVELOPER）
/operation	操作日志分页（高权限）
/file	静态文件访问（头像、媒体、结果图等）

检测任务数据流

sequenceDiagram
  participant U as 用户浏览器
  participant F as 检澜 API Flask
  participant DB as MySQL
  participant Y as YOLO 推理
  participant S as 静态目录

  U->>F: POST /detection/detection_segmentation（model_id, media_id）
  F->>DB: 读 Model / Media，写/更新 Detection
  F->>S: 读权重与源媒体
  F->>Y: 推理与后处理
  Y-->>F: 掩码/可视化结果
  F->>S: 写 result 文件
  F->>DB: 更新指标、等级、状态、耗时
  F-->>U: JSON（含 operation 记录等）
  U->>F: GET 列表/详情、GET /file/... 预览

---

目录结构

路径	说明
bridge-disease-frontend-main/	检澜 Web 前端（Vite + Vue 3）
BridgeDiseaseBackend-main/	检澜 API 与推理服务
BridgeDiseaseBackend-main/scripts/	媒体/检测/训练数据集种子、编码修复等运维脚本
BridgeDiseaseBackend-main/docs/TRAINING_DATASET.md	模型训练数据集格式说明
BridgeDiseaseBackend-main/training_templates/	data.yaml 模板与演示 ZIP
scripts/start-backend.ps1	释放 5000 端口并启动检澜后端（Windows）
BridgeDiseaseBackend-main/seed_assets/	真实照片源文件（媒体种子）
BridgeDiseaseBackend-main/sql/	init_db.sql（最小种子）、seed_snapshot.sql（完整演示库）
BridgeDiseaseBackend-main/seed_assets/snapshot/	可提交的演示静态资源与训练元数据快照
docker/	镜像构建、Nginx、后端 bootstrap
docker-compose.yml	MySQL、后端、前端编排
images/	README 界面截图
package.json	根目录 npm run up / npm run down

---

技术栈概览

• 前端：Vue 3、Vue Router、Axios、Element Plus、ECharts、Vite 6
• 后端：Flask、Flask-JWT-Extended、Flask-CORS、SQLAlchemy、PyMySQL
• 推理与影像：OpenCV、Ultralytics、PyTorch、Pillow、scikit-image、moviepy 等（见 BridgeDiseaseBackend-main/requirements.txt）
• 数据库：MySQL 8（建议 utf8mb4）

---

检澜界面截图

---

启动检澜

方式 A：本地开发（推荐，启动快）

完整 Docker 堆栈需构建 PyTorch/CUDA 镜像，在 Windows 上可能极慢。日常开发建议 仅 Docker 跑 MySQL，本机启动前后端。

1. MySQL（Docker）

# 项目根目录
docker compose -p bridge-disease up -d db

• 端口：3307 → 容器 3306
• 密码：bridgedisease_root
• 库名：bridge_disease

2. 后端

cd BridgeDiseaseBackend-main
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

$env:SQLALCHEMY_DATABASE_URI="mysql+pymysql://root:bridgedisease_root@127.0.0.1:3307/bridge_disease?charset=utf8mb4"
python run.py

• API：http://127.0.0.1:5000
• Windows 下若登录报 ZoneInfoNotFoundError: Asia/Shanghai，需已安装 tzdata（已写入 requirements.txt）。

3. 前端

cd bridge-disease-frontend-main
npm install

创建 bridge-disease-frontend-main/.env.local：

VITE_API_BASE_URL=http://127.0.0.1:5000

npm run serve

• Web：http://localhost:5173

4. 初始化演示数据（首次或空库）

方式 A — 一键快照（推荐，与维护者演示效果一致）

仓库已包含导出的 sql/seed_snapshot.sql 与 seed_assets/snapshot/（媒体、模型、检测结果、训练任务元数据）：

cd BridgeDiseaseBackend-main
$env:SQLALCHEMY_DATABASE_URI="mysql+pymysql://root:bridgedisease_root@127.0.0.1:3307/bridge_disease?charset=utf8mb4"
python scripts/import_db_snapshot.py
python run.py

维护者更新快照：python scripts/export_db_snapshot.py 后提交 sql/seed_snapshot.sql 与 seed_assets/snapshot/。说明见 seed_assets/snapshot/README.md。

方式 B — 分步种子（体积极小，需联网下载照片）

cd BridgeDiseaseBackend-main
$env:SQLALCHEMY_DATABASE_URI="mysql+pymysql://root:bridgedisease_root@127.0.0.1:3307/bridge_disease?charset=utf8mb4"

python run.py   # 首次会 db.create_all()，空库可再导入 sql/init_db.sql

python scripts/download_real_medias.py   # 可选
python scripts/seed_medias.py
python scripts/seed_models.py
python scripts/seed_detections.py

若中文姓名、隐患类别显示为 ??，说明历史写入时连接未带 UTF-8，可执行修复脚本：

python scripts/fix_user_names.py
python scripts/fix_model_texts.py

注意：连接字符串务必包含 ?charset=utf8mb4；后端 config.py 会在未指定时自动补全。

---

方式 B：Docker 一键堆栈

在项目根目录（需 Docker + Node.js）：

npm install
npm run up

此流程会：

1. 以 DOCKER_BUILDKIT=0 构建镜像（降低中文路径下 Compose Bake 错误概率）。
2. 启动 MySQL、后端（:5000）、前端 Nginx（:8080）。
3. 数据库为空时由 bootstrap 执行 db.create_all() 并导入 sql/init_db.sql。

服务	地址
检澜 Web	http://localhost:8080
检澜 API	http://127.0.0.1:5000

停止：

npm run down

根目录环境变量（.env）

变量	说明
MYSQL_ROOT_PASSWORD	MySQL root 密码（默认 bridgedisease_root）
MYSQL_DATABASE	数据库名（默认 bridge_disease）
MYSQL_HOST_PORT	主机映射端口（默认 3307）
VITE_API_BASE_URL	构建前端镜像时的 API 基地址

---

数据种子脚本

脚本	作用
scripts/download_real_medias.py	从 Wikimedia / Pexels 下载真实照片到 seed_assets/medias/
scripts/seed_medias.py	导入媒体文件并同步 media 表
scripts/seed_detections.py	插入 20 条安全隐患检测演示记录（需已有 user/model/media）
scripts/fix_user_names.py	修复用户姓名 ?? 乱码
scripts/fix_model_texts.py	修复模型隐患类别、检测描述乱码
scripts/seed_models.py	下载 YOLOv8n-seg 并复制为演示用 .pt 权重
scripts/create_demo_dataset.py	生成试跑用 bridge_hazard_demo.zip 与 YOLO 分割演示数据集
scripts/export_db_snapshot.py	将当前 MySQL + 静态资源导出到 sql/seed_snapshot.sql 与 seed_assets/snapshot/
scripts/import_db_snapshot.py	导入上述快照（新同事一键还原演示环境）

照片版权说明见 BridgeDiseaseBackend-main/seed_assets/medias/ATTRIBUTION.md。

---

首次登录与种子账号

数据库由 sql/init_db.sql 初始化后，可使用下列账号（用户名或邮箱均可登录；登录成功后状态变为已启用）：

角色	用户名	邮箱	密码
管理员	admin	admin@example.com	Admin123456
开发人员	developer	dev@example.com	developer-WZY
普通用户	demo	user@example.com	user-WZY

若提示「用户尚未注册」：说明种子未成功导入。可清空库后重新导入 init_db.sql，或 Docker 删卷后 npm run up。上线前务必修改全部默认密码与密钥（JWT_SECRET_KEY、SECRET_KEY、数据库密码等）。

---

常用命令

场景	命令
仅启动 MySQL	docker compose -p bridge-disease up -d db
Docker 全栈	根目录 npm run up
Docker 停止	根目录 npm run down
前端开发	cd bridge-disease-frontend-main && npm run serve
前端构建	cd bridge-disease-frontend-main && npm run build
后端开发	cd BridgeDiseaseBackend-main && python run.py
后端开发（Windows）	项目根目录 .\scripts\start-backend.ps1

---

疑难排解

现象	处理
中文显示 ??（姓名、隐患类别等）	连接串加 charset=utf8mb4，运行 fix_user_names.py / fix_model_texts.py
登录报 Asia/Shanghai 时区错误	Windows 安装 tzdata：pip install tzdata
Docker 在中文路径构建失败	使用 npm run up，或项目移到 ASCII 路径
列表无数据	确认后端已启动、VITE_API_BASE_URL 正确；或运行 seed_medias.py / seed_detections.py
媒体库无图	运行 seed_medias.py；static/ 已在 .gitignore，需本地生成
推理慢或内存不足	PyTorch/YOLO 需足够 RAM；可选 GPU 环境
批量检测 / 台账 / 报告 / IoT 数据丢失	上述模块数据在浏览器 localStorage，清缓存会重置
Mermaid 图不渲染	使用支持 Mermaid 的 Markdown 预览（GitHub、VS Code 插件等）
模型训练一直「排队」、列表变空	确认 5000 为本项目后端；刷新训练页或重启后端（会恢复 pending）；jobs.json 损坏时可从 jobs.json.bak 恢复
训练完成但任务列表无数据	多为 jobs.json 写入异常，已修复 datetime 序列化；修复后刷新页面

---

授权与声明

各子目录包含第三方依赖，版权归原作者所有。若检澜或本仓库需对外发布，请补充适当的开源授权文件与数据使用声明。