InspectHub - 设备巡检信息统计平台

一个基于 Vue 3 + Express + MySQL 的全栈巡检管理系统，支持模板管理、巡检记录、图片上传、Word 导出等功能。

功能特性

核心功能

🔐 用户认证 - JWT 身份验证，支持管理员和普通用户角色
📋 模板管理 - 创建、编辑、复制、删除巡检模板
📝 巡检记录 - 基于模板创建巡检记录，支持多图上传
📤 Word 导出 - 将巡检记录导出为格式化的 Word 文档
💾 备份恢复 - 支持数据库和图片的完整备份与恢复

模板管理特性

✅ 设备分组 - 按设备组织检查项
✅ 拖拽排序 - 支持拖拽调整设备顺序
✅ 设备复制 - 快速复制设备及其所有检查项
✅ 检查项管理 - 支持分组标题和必更项标记
✅ 实时预览 - 编辑时实时显示设备和检查项

巡检记录特性

✅ 模板同步 - 复制记录时自动同步最新模板结构
✅ 智能匹配 - 基于层级路径匹配，支持设备顺序调整
✅ 多图上传 - 支持粘贴、拖拽、选择文件上传
✅ 必更标识 - 动态项标记"必更"，提醒用户更新
✅ 状态管理 - 草稿和完成状态管理

技术栈

前端

框架: Vue 3 (Composition API)
构建工具: Vite 5
UI 组件: Element Plus 2.4
状态管理: Pinia 2.1
路由: Vue Router 4.2
HTTP 客户端: Axios 1.6
拖拽排序: SortableJS 1.15

后端

框架: Express 4.18
数据库: MySQL 8.0
ORM: Sequelize 6.35
身份验证: JWT (jsonwebtoken 9.0)
密码加密: bcryptjs 2.4
文件上传: Multer 1.4
Word 生成: docx 8.2
备份压缩: archiver 7.0

部署

容器化: Docker + Docker Compose
Web 服务器: Nginx (客户端)
数据库: MySQL 8.0 (官方镜像)

项目结构

InspectHub/
├── client/                 # 前端项目
│   ├── src/
│   │   ├── api/           # API 接口
│   │   ├── components/    # 公共组件
│   │   ├── router/        # 路由配置
│   │   ├── stores/        # Pinia 状态管理
│   │   ├── views/         # 页面组件
│   │   │   ├── Dashboard.vue
│   │   │   ├── Login.vue
│   │   │   ├── TemplateList.vue
│   │   │   ├── TemplateEditTwoColumn.vue
│   │   │   ├── InspectionList.vue
│   │   │   └── InspectionEdit.vue
│   │   ├── App.vue
│   │   └── main.js
│   ├── package.json
│   └── vite.config.js
│
├── server/                 # 后端项目
│   ├── config/            # 配置文件
│   │   └── database.js    # 数据库配置
│   ├── controllers/       # 控制器
│   │   ├── authController.js
│   │   ├── templateController.js
│   │   ├── inspectionController.js
│   │   └── backupController.js
│   ├── middleware/        # 中间件
│   │   └── auth.js        # JWT 认证中间件
│   ├── models/            # 数据模型
│   │   ├── index.js
│   │   ├── User.js
│   │   ├── Template.js
│   │   ├── TemplateItem.js
│   │   ├── Inspection.js
│   │   └── InspectionItem.js
│   ├── routes/            # 路由
│   │   ├── auth.js
│   │   ├── template.js
│   │   ├── inspection.js
│   │   ├── upload.js
│   │   └── backup.js
│   ├── uploads/           # 上传文件目录
│   ├── app.js             # 应用入口
│   └── package.json
│
├── docker-compose.yml      # Docker Compose 配置
├── README.md              # 项目文档
└── .gitignore             # Git 忽略文件

快速开始

前置要求

Node.js >= 16.0.0
MySQL >= 8.0
Docker & Docker Compose (可选)

方式一：本地开发

1. 克隆项目

git clone https://github.com/Xeubad/InspectHub.git
cd InspectHub

2. 安装依赖

后端：

cd server
npm install

前端：

cd client
npm install

3. 配置数据库

后端通过环境变量读取数据库配置（见下方「环境变量」），默认连接 localhost:3306 的 inspection_platform 库。也可以创建数据库后按需覆盖：

export DB_NAME=inspecthub_db DB_USER=root DB_PASS=your_password

4. 启动服务

后端（开发模式）：

cd server
npm run dev
# 服务运行在 http://localhost:3000

前端（开发模式）：

cd client
npm run dev
# 服务运行在 http://localhost:5173

5. 访问应用

打开浏览器访问 http://localhost:5173

初始管理员账号：

首次启动时如果系统中没有任何管理员，会自动创建初始管理员（用户名默认 admin）：

设置了 ADMIN_PASSWORD 环境变量时使用该密码
未设置时生成随机密码并打印在服务日志里，请立即登录修改

注册页面只能创建「工程师」账号，管理员账号只能通过初始 seed 或备份恢复产生。

方式二：Docker 部署

1. 配置环境变量

cp .env.example .env
# 编辑 .env，必须设置 DB_PASSWORD 和 JWT_SECRET（用强随机字符串）

2. 启动容器

docker-compose up -d

3. 访问应用

打开浏览器访问 http://localhost

4. 查看日志

# 查看所有服务日志
docker-compose logs -f

# 查看特定服务日志
docker-compose logs -f server
docker-compose logs -f client

5. 停止服务

docker-compose down

环境变量

后端环境变量

# 数据库配置
DB_HOST=localhost
DB_NAME=inspecthub_db
DB_USER=root
DB_PASS=your_password
DB_PORT=3306

# JWT 配置（生产环境必须设置强随机密钥，未设置时启动会打印警告）
JWT_SECRET=your_jwt_secret_key

# 初始管理员（仅当系统中无任何管理员时创建）
ADMIN_USERNAME=admin
ADMIN_PASSWORD=            # 留空则生成随机密码并打印在日志

# 服务器端口
PORT=3000

前端环境变量

# API 基础路径
VITE_API_BASE_URL=http://localhost:3000/api

数据库结构

主要数据表

users - 用户表

id, username, password, role, createdAt, updatedAt

templates - 模板表

id, name, description, createdBy, createdAt, updatedAt

template_items - 模板项表

id, templateId, name, description, level, code, isGroup, isDynamic, sortOrder

inspections - 巡检记录表

id, templateId, title, status, inspectionTime, inspectorId, createdBy, createdAt, updatedAt

inspection_items - 巡检项表

id, inspectionId, name, result, imagePath, level, code, isGroup, isDynamic, isUpdated, sortOrder

API 接口

认证接口

POST /api/auth/register - 用户注册
POST /api/auth/login - 用户登录
GET /api/auth/me - 获取当前用户信息

模板接口

GET /api/templates - 获取模板列表
GET /api/templates/:id - 获取模板详情
POST /api/templates - 创建模板（管理员）
PUT /api/templates/:id - 更新模板（管理员）
DELETE /api/templates/:id - 删除模板（管理员）

巡检接口

GET /api/inspections - 获取巡检记录列表
GET /api/inspections/:id - 获取巡检记录详情
POST /api/inspections - 创建巡检记录
PUT /api/inspections/:id - 更新巡检记录
DELETE /api/inspections/:id - 删除巡检记录
POST /api/inspections/:id/copy - 复制巡检记录
GET /api/inspections/:id/export - 导出 Word 文档

上传接口

POST /api/upload - 上传图片

备份接口（仅管理员）

GET /api/backup/export - 导出备份（含数据库 JSON 和图片，密码 hash 一并导出）
POST /api/backup/import - 恢复备份

核心功能说明

1. 模板编辑

左侧设备列表，支持拖拽排序
右侧检查项编辑，一行一项
设备编号：1.1, 2.1, 3.1...
检查项编号：1.1.1, 1.1.2, 2.1.1...
支持设备复制功能

2. 巡检记录复制

使用层级路径匹配（设备名称/检查项名称）
支持设备顺序调整后的复制
自动同步模板新增的设备和检查项
保留旧数据，不丢失任何信息

3. 图片上传

支持粘贴、拖拽、选择文件
自动转换为高质量 JPEG
支持多图上传（JSON 数组格式）
导出时按原图比例缩放，固定宽度 280px

4. Word 导出

格式化表格布局
支持多图显示
分组标题样式
16:9 图片比例

开发指南

代码规范

使用 ES6+ 语法
组件使用 Composition API
遵循 Vue 3 风格指南
使用 async/await 处理异步

提交规范

feat: 新功能
fix: 修复 bug
docs: 文档更新
style: 代码格式调整
refactor: 重构
test: 测试相关
chore: 构建/工具链相关

分支管理

main - 主分支，生产环境
develop - 开发分支
feature/* - 功能分支
hotfix/* - 紧急修复分支

常见问题

1. 数据库连接失败

检查 MySQL 服务是否启动
验证数据库配置是否正确
确认数据库用户权限

2. 图片上传失败

检查 server/uploads 目录权限
确认文件大小未超过限制（默认 10MB）
验证文件格式是否支持

3. Docker 容器启动失败

检查端口是否被占用
验证数据卷路径是否存在
查看容器日志排查错误

4. 前端无法连接后端

检查后端服务是否启动
验证 API 基础路径配置
检查 CORS 配置

性能优化

前端优化

路由懒加载
图片懒加载
组件按需引入
生产环境代码压缩

后端优化

数据库索引优化
查询结果缓存
图片压缩处理
接口响应压缩

数据库优化

合理使用索引
避免 N+1 查询
使用连接池
定期清理日志

安全建议

生产环境

✅ 修改默认管理员密码
✅ 使用强随机 JWT 密钥
✅ 启用 HTTPS
✅ 配置防火墙规则
✅ 定期备份数据
✅ 限制文件上传大小和类型
✅ 使用环境变量管理敏感信息

数据库安全

✅ 使用强密码
✅ 限制远程访问
✅ 定期更新补丁
✅ 启用审计日志

更新日志

v1.0.0 (2026-01-29)

✨ 初始版本发布
✨ 模板管理功能
✨ 巡检记录功能
✨ Word 导出功能
✨ 备份恢复功能
✨ 设备拖拽排序
✨ 智能复制匹配

贡献指南

欢迎提交 Issue 和 Pull Request！

提交 PR 流程

Fork 本仓库
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
开启 Pull Request

许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件

联系方式

项目地址: [GitHub Repository]
问题反馈: [GitHub Issues]

致谢

感谢以下开源项目：

⭐ 如果这个项目对你有帮助，请给一个 Star！

Name		Name	Last commit message	Last commit date
client		client
server		server
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml

Latest commit

History

Folders and files

Repository files navigation