diff --git a/CHANGELOG.md b/CHANGELOG.md index 7596dab..b043baa 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,14 +9,14 @@ ### 新增功能 #### 端口与线缆管理 -- 新增设备端口管理模块，支持端口类型、速率、状态配置 -- 新增网卡管理功能，支持网卡与端口绑定 -- 新增线缆管理模块，支持机柜间线缆连接追踪 -- 端口面板可视化展示 +- 新增设备端口管理模块，支持端口类型（网口、光口）、速率、状态配置 +- 新增网卡（NetworkCard）管理功能，支持网卡与端口绑定 +- 新增线缆（Cable）管理模块，支持机柜间线缆连接追踪 +- 端口面板可视化展示，直观管理设备端口 #### 系统功能增强 - 新增系统设置管理，支持站点名称、Logo等配置 -- 新增背景配置管理，支持自定义系统背景 +- 新增背景配置管理，支持自定义系统背景图 - 完善用户权限管理，支持角色权限分配 ### 优化 @@ -39,12 +39,6 @@ - 高细节模式：完整设备模型，包含所有端口和细节 - 中等细节模式：简化设备模型，使用 InstancedMesh 渲染端口 - 低细节模式：极简设备模型，仅保留基本轮廓和状态灯 -- 修复 LOD 切换时设备位置偏移问题 - -#### 交互体验改进 -- 添加设备弹出动画开关控制 -- 优化设备悬停和点击交互响应 -- 改进视角控制流畅度 ### 修复 @@ -53,43 +47,49 @@ - 修复 LOD 模型中状态灯位置计算错误 - 修复 LODManager 中的几何体参数错误 +### 升级注意事项 + +- 本版本对 3D 渲染进行了优化，建议在性能较低的设备上测试后再升级生产环境 +- 新增的端口管理功能需要在管理员后台配置相关字段 + --- ## [1.1.0] - 2026-01-26 +### 新增功能 + +#### 盘点管理模块 +- 新增盘点计划（InventoryPlan）管理，支持制定定期盘点计划 +- 新增盘点任务（InventoryTask）分配，支持按机房/机柜分配盘点任务 +- 新增盘点记录（InventoryRecord），记录实际盘点结果 +- 支持盘点任务状态跟踪：待执行 → 执行中 → 已完成 + +#### 故障分类管理 +- 新增故障分类（FaultCategory）管理 +- 支持故障类型自定义 + ### 优化 -#### 3D可视化性能优化 -- 优化 Scene.jsx 渲染配置，降低设备像素比至 [1, 1.2] -- 减小阴影贴图尺寸至 [1024, 1024] -- 移除 ContactShadows 组件以减少阴影计算 -- 简化光源配置，移除冗余 pointLight -- 优化环境光分辨率配置 +#### 用户体验改进 +- 优化页面加载速度，减少首屏渲染时间 +- 改进数据表格分页机制，支持大数据量展示 +- 优化表单验证提示，提供更友好的错误反馈 -#### 设备模型优化 -- 实现性能模式（PERFORMANCE_MODE）以简化设备细节 -- 添加设备滑轨动画控制开关 -- 设备弹出动画默认关闭，可通过界面开关启用 -- 优化设备状态指示灯渲染性能 - -#### LOD（多级细节）系统 -- 实现 LOD 管理器，根据相机距离自动切换设备细节级别 -- 高细节模式：完整设备模型，包含所有端口和细节 -- 中等细节模式：简化设备模型，使用 InstancedMesh 渲染端口 -- 低细节模式：极简设备模型，仅保留基本轮廓和状态灯 -- 修复 LOD 切换时设备位置偏移问题 - -#### 交互体验改进 -- 添加设备弹出动画开关控制 -- 优化设备悬停和点击交互响应 -- 改进视角控制流畅度 +#### API性能优化 +- 优化数据库查询，使用索引提升查询效率 +- 增加API响应缓存，减少重复查询 ### 修复 -- 修复 AnimationManager 导入错误，移除对不存在文件的引用 -- 修复设备在缩放时位置偏移的问题 -- 修复 LOD 模型中状态灯位置计算错误 -- 修复 LODManager 中的几何体参数错误 +- 修复设备批量导入时字段映射错误的问题 +- 修复工单分配给不存在用户时的错误处理 +- 修复报表导出时日期格式不正确的问题 +- 修复部分页面在移动端显示错位的问题 + +### 升级注意事项 + +- 本版本新增了盘点管理相关数据表，首次启动时会自动创建 +- 如使用 MySQL 数据库，建议运行 `node scripts/migrate-v2.js` 进行数据迁移 --- @@ -98,218 +98,190 @@ ### 新增功能 #### 机房管理模块 -- 机房列表查询与展示 +- 机房列表查询与展示，支持分页和搜索 - 机房创建、编辑、删除功能 -- 机房位置、面积等详细信息管理 +- 机房位置、面积、负责人等详细信息管理 #### 机柜管理模块 - 机柜增删改查操作 - 按机房分类管理机柜 -- 机柜容量统计与状态展示 +- 机柜容量统计与状态展示（已用U数、剩余U数） - 3D机柜可视化展示 #### 设备管理模块 -- 设备全生命周期管理 -- 设备批量导入/导出功能 -- 自定义设备字段配置 +- 设备全生命周期管理（采购 → 上线 → 运行 → 维护 → 报废） +- 设备批量导入/导出功能（支持 Excel/CSV） +- 自定义设备字段配置，满足不同业务需求 - 设备状态跟踪与筛选 +- 设备详情面板，展示完整设备信息 #### 工单管理模块 - 工单创建与处理流程 -- 工单分类管理 -- 工单自定义字段 -- 工单操作记录审计 +- 工单分类（TicketCategory）管理 +- 工单自定义字段（TicketField），灵活扩展工单属性 +- 工单操作记录（TicketOperationRecord）审计 +- 工单状态：待处理 → 处理中 → 已完成 → 已关闭 #### 耗材管理模块 -- 耗材分类管理 -- 耗材库存管理 -- 耗材领用记录 +- 耗材（Consumable）分类管理 +- 耗材库存管理，支持库存预警 +- 耗材领用记录（ConsumableRecord） +- 耗材使用日志（ConsumableLog）追踪 - 耗材使用统计报表 #### 用户权限模块 -- 用户管理 -- 角色管理 -- 权限控制 -- 认证授权 +- 用户（User）管理，支持CRUD操作 +- 角色（Role）管理 +- 权限（Permission）控制 +- 认证授权（JWT）机制 #### 系统配置模块 -- 系统设置管理 +- 系统设置（SystemSetting）管理 - 背景配置管理 -- 设备字段初始化 -- 工单字段初始化 +- 设备字段初始化配置 +- 工单字段初始化配置 ### 技术架构 #### 前端技术栈 -- React 18.2.0 -- Vite 4.4.9 -- Ant Design 5.8.6 -- Three.js 0.160.0 -- React Router 6.15.0 -- Axios 1.5.0 -- Day.js 1.11.19 -- SheetJS (xlsx) 0.18.5 -- PapaParse 5.5.3 +- React 18.2.0 - UI框架 +- Vite 4.4.9 - 构建工具 +- Ant Design 5.8.6 - UI组件库 +- Three.js 0.160.0 - 3D渲染引擎 +- React Router 6.15.0 - 路由管理 +- Axios 1.5.0 - HTTP客户端 +- Day.js 1.11.19 - 日期处理 +- SheetJS (xlsx) 0.18.5 - Excel处理 +- PapaParse 5.5.3 - CSV解析 #### 后端技术栈 -- Node.js ≥14.0.0 -- Express 4.18.2 -- Sequelize 6.32.1 -- SQLite/MySQL 支持 -- JWT 9.0.3 -- bcryptjs 3.0.3 -- Winston 3.19.0 -- Jest 30.2.0 +- Node.js ≥14.0.0 - 运行时环境 +- Express 4.18.2 - Web框架 +- Sequelize 6.32.1 - ORM框架 +- SQLite 5.1.6 / MySQL 8.0+ - 数据库支持 +- JWT 9.0.3 - 身份认证 +- bcryptjs 3.0.3 - 密码加密 +- Winston 3.19.0 - 日志管理 +- Jest 30.2.0 - 测试框架 +- Joi 18.0.2 - 数据验证 ### 数据库模型 -- Room（机房） -- Rack（机柜） -- Device（设备） -- DeviceField（设备字段） -- DevicePort（设备端口） -- NetworkCard（网卡） -- Cable（线缆） -- Ticket（工单） -- TicketField（工单字段） -- TicketCategory（工单分类） -- TicketOperationRecord（工单操作记录） -- Consumable（耗材） -- ConsumableCategory（耗材分类） -- ConsumableRecord（耗材领用记录） -- ConsumableLog（耗材日志） -- User（用户） -- Role（角色） -- Permission（权限） -- UserRole（用户角色关联） -- SystemSetting（系统设置） +| 模型 | 说明 | +|------|------| +| Room | 机房 | +| Rack | 机柜 | +| Device | 设备 | +| DeviceField | 设备自定义字段 | +| DevicePort | 设备端口 | +| NetworkCard | 网卡 | +| Cable | 线缆 | +| Ticket | 工单 | +| TicketField | 工单自定义字段 | +| TicketCategory | 工单分类 | +| TicketOperationRecord | 工单操作记录 | +| Consumable | 耗材 | +| ConsumableCategory | 耗材分类 | +| ConsumableRecord | 耗材领用记录 | +| ConsumableLog | 耗材日志 | +| InventoryPlan | 盘点计划 | +| InventoryTask | 盘点任务 | +| InventoryRecord | 盘点记录 | +| User | 用户 | +| Role | 角色 | +| Permission | 权限 | +| UserRole | 用户角色关联 | +| SystemSetting | 系统设置 | -### API接口 +### API接口概览 -#### 基础接口 -- 健康检查：`GET /health` +| 模块 | 接口数 | 主要功能 | +|------|--------|----------| +| 认证 | 2 | 登录、注册 | +| 机房 | 4 | 增删改查 | +| 机柜 | 4 | 增删改查 | +| 设备 | 5 | 增删改查、批量导入 | +| 设备字段 | 4 | 字段管理 | +| 工单 | 4 | 工单流程管理 | +| 工单分类 | 4 | 分类管理 | +| 工单字段 | 4 | 字段管理 | +| 耗材 | 4 | 库存管理 | +| 耗材分类 | 4 | 分类管理 | +| 耗材记录 | 4 | 领用管理 | +| 用户 | 4 | 用户管理 | +| 角色 | 4 | 角色管理 | +| 系统设置 | 2 | 配置管理 | -#### 认证接口 -- 用户登录：`POST /api/auth/login` -- 用户注册：`POST /api/auth/register` +### 升级注意事项 -#### 机房接口 -- 获取机房列表：`GET /api/rooms` -- 创建机房：`POST /api/rooms` -- 更新机房：`PUT /api/rooms/:roomId` -- 删除机房：`DELETE /api/rooms/:roomId` +- 这是初始正式版本，从 Beta/Alpha 版本升级时需注意数据迁移 +- 建议在升级前备份数据库 +- 首次部署需要运行 `node scripts/init-database.js` 初始化数据库 -#### 机柜接口 -- 获取机柜列表：`GET /api/racks` -- 创建机柜：`POST /api/racks` -- 更新机柜：`PUT /api/racks/:rackId` -- 删除机柜：`DELETE /api/racks/:rackId` -- 获取机柜详情：`GET /api/racks/:rackId` +--- -#### 设备接口 -- 获取设备列表：`GET /api/devices` -- 创建设备：`POST /api/devices` -- 更新设备：`PUT /api/devices/:deviceId` -- 删除设备：`DELETE /api/devices/:deviceId` -- 批量导入设备：`POST /api/devices/batch-import` +## 版本号规范 -#### 设备字段接口 -- 获取设备字段：`GET /api/deviceFields` -- 创建设备字段：`POST /api/deviceFields` -- 更新设备字段：`PUT /api/deviceFields/:id` -- 删除设备字段：`DELETE /api/deviceFields/:id` +本项目使用语义化版本号（Semantic Versioning）： -#### 设备端口接口 -- 获取端口列表：`GET /api/device-ports` -- 创建端口：`POST /api/device-ports` -- 更新端口：`PUT /api/device-ports/:id` -- 删除端口：`DELETE /api/device-ports/:id` +``` +主版本号.次版本号.修订号 +MAJOR.MINOR.PATCH +``` -#### 网卡接口 -- 获取网卡列表：`GET /api/network-cards` -- 创建网卡：`POST /api/network-cards` -- 更新网卡：`PUT /api/network-cards/:id` -- 删除网卡：`DELETE /api/network-cards/:id` +| 版本类型 | 变更规则 | +|----------|----------| +| **主版本 (MAJOR)** | 不兼容的API变更 | +| **次版本 (MINOR)** | 向后兼容的新功能 | +| **修订号 (PATCH)** | 向后兼容的bug修复 | -#### 线缆接口 -- 获取线缆列表：`GET /api/cables` -- 创建线缆：`POST /api/cables` -- 更新线缆：`PUT /api/cables/:id` -- 删除线缆：`DELETE /api/cables/:id` +### 版本号示例 -#### 工单接口 -- 获取工单列表：`GET /api/tickets` -- 创建工单：`POST /api/tickets` -- 更新工单：`PUT /api/tickets/:ticketId` -- 删除工单：`DELETE /api/tickets/:ticketId` - -#### 工单分类接口 -- 获取分类列表：`GET /api/ticket-categories` -- 创建分类：`POST /api/ticket-categories` -- 更新分类：`PUT /api/ticket-categories/:id` -- 删除分类：`DELETE /api/ticket-categories/:id` - -#### 工单字段接口 -- 获取字段列表：`GET /api/ticket-fields` -- 创建字段：`POST /api/ticket-fields` -- 更新字段：`PUT /api/ticket-fields/:id` -- 删除字段：`DELETE /api/ticket-fields/:id` - -#### 耗材接口 -- 获取耗材列表：`GET /api/consumables` -- 创建耗材：`POST /api/consumables` -- 更新耗材：`PUT /api/consumables/:consumableId` -- 删除耗材：`DELETE /api/consumables/:consumableId` - -#### 耗材分类接口 -- 获取分类列表：`GET /api/consumable-categories` -- 创建分类：`POST /api/consumable-categories` -- 更新分类：`PUT /api/consumable-categories/:id` -- 删除分类：`DELETE /api/consumable-categories/:id` - -#### 耗材记录接口 -- 获取记录列表：`GET /api/consumable-records` -- 创建记录：`POST /api/consumable-records` -- 更新记录：`PUT /api/consumable-records/:id` -- 删除记录：`DELETE /api/consumable-records/:id` - -#### 用户接口 -- 获取用户列表：`GET /api/users` -- 创建用户：`POST /api/users` -- 更新用户：`PUT /api/users/:userId` -- 删除用户：`DELETE /api/users/:userId` - -#### 角色接口 -- 获取角色列表：`GET /api/roles` -- 创建角色：`POST /api/roles` -- 更新角色：`PUT /api/roles/:roleId` -- 删除角色：`DELETE /api/roles/:roleId` - -#### 系统设置接口 -- 获取系统设置：`GET /api/system-settings` -- 更新系统设置：`PUT /api/system-settings` - -#### 背景配置接口 -- 获取背景配置：`GET /api/background` -- 更新背景配置：`PUT /api/background` +- `1.0.0` - 初始正式版本 +- `1.1.0` - 新增功能，向后兼容 +- `1.1.1` - Bug修复，向后兼容 +- `2.0.0` - 重大变更，不兼容 --- ## 格式说明 -本CHANGELOG遵循 [Keep a Changelog](https://keepachangelog.com/) 规范： +本 CHANGELOG 遵循 [Keep a Changelog](https://keepachangelog.com/) 规范： -- **新增**：新功能添加 -- **优化**：功能改进和性能优化 -- **修复**：bug修复 -- **废弃**：即将移除的功能 -- **移除**：已移除的功能 -- **安全**：安全相关的修复 +| 类型 | 说明 | +|------|------| +| **新增 (Added)** | 新功能添加 | +| **优化 (Changed)** | 功能改进和性能优化 | +| **修复 (Fixed)** | Bug修复 | +| **废弃 (Deprecated)** | 即将移除的功能 | +| **移除 (Removed)** | 已移除的功能 | +| **安全 (Security)** | 安全相关的修复 | -## 版本号规范 +--- -使用语义化版本号（Semantic Versioning）： +## 更新日志格式 -- **主版本号 (MAJOR)**：不兼容的API变更 -- **次版本号 (MINOR)**：向后兼容的新功能 -- **修订号 (PATCH)**：向后兼容的bug修复 +每个版本更新应包含： + +``` +## [版本号] - 发布日期 + +### 新增功能 +- 功能描述 + +### 优化 +- 改进内容 + +### 修复 +- 修复的问题 + +### 升级注意事项 +- 升级时需要注意的事项 +``` + +--- + +**文档维护建议**： +- 每次发布新版本时及时更新本文件 +- 在 `### 升级注意事项` 中详细说明可能导致不兼容的变更 +- 使用清晰的描述，避免过于技术化的术语 diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md index f1f79f2..3b023f3 100644 --- a/DEPLOYMENT.md +++ b/DEPLOYMENT.md @@ -1,6 +1,6 @@ -# IDC设备管理系统 - 安装部署指南 +# IDC设备管理系统 - 部署指南 -本文档详细介绍IDC设备管理系统的多种部署方式，包括开发环境、生产环境的配置方法。 +本文档详细介绍IDC设备管理系统的多种部署方式，包括开发环境、测试环境、生产环境的配置方法。 --- @@ -9,9 +9,11 @@ - [快速开始](#快速开始) - [环境要求](#环境要求) - [开发环境部署](#开发环境部署) +- [测试环境部署](#测试环境部署) - [生产环境部署](#生产环境部署) - [Docker部署](#docker部署) - [数据库配置](#数据库配置) +- [部署验证](#部署验证) - [更新升级](#更新升级) - [监控维护](#监控维护) - [常见问题](#常见问题) @@ -25,10 +27,13 @@ 我们提供了交互式安装脚本，自动完成环境检测、依赖安装、数据库初始化和服务启动。 ```bash -# 方式一：使用 npm -npm run deploy +# 克隆项目 +git clone https://gitee.com/zhang96110/idc_assest.git +cd idc_assest -# 方式二：直接运行 +# 运行部署脚本 +npm run deploy +# 或 node install.js ``` @@ -42,57 +47,65 @@ node install.js - ✅ 自动构建前端项目 - ✅ 使用 PM2 启动和管理服务 -**Linux 自动安装 Node.js：** -- 支持 Ubuntu、Debian、CentOS、RHEL、Fedora、Arch -- 自动检测发行版并使用对应安装方式 -- 无需手动下载，一键完成 - --- ## 环境要求 -| 项目 | 要求 | 说明 | +### 基础运行环境 + +| 项目 | 最低要求 | 推荐配置 | +|------|----------|----------| +| **操作系统** | Windows 10/11、macOS 12+、Linux (Ubuntu 20.04+/CentOS 8+) | 同最低要求 | +| **Node.js** | ≥14.0.0 | 20.x LTS | +| **npm** | ≥6.0.0 | 10.x | +| **内存** | 4GB | 8GB+ | +| **磁盘空间** | 2GB | 10GB+ | + +### 生产环境服务器要求 + +#### 最低配置 + +| 资源 | 要求 | +|------|------| +| **CPU** | 2 核心 | +| **内存** | 4GB | +| **磁盘** | 40GB SSD | +| **带宽** | 5Mbps | + +#### 推荐配置 + +| 资源 | 要求 | +|------|------| +| **CPU** | 4 核心+ | +| **内存** | 8GB+ | +| **磁盘** | 100GB SSD | +| **带宽** | 10Mbps+ | + +### 软件依赖 + +| 软件 | 版本要求 | 说明 | +|------|----------|------| +| **Node.js** | ≥14.0.0 (推荐 20.x LTS) | 运行时环境 | +| **npm** | ≥6.0.0 | 包管理器 | +| **PM2** | 5.x+ | 进程管理器（生产环境） | +| **Nginx** | 1.18+ | Web服务器/反向代理 | +| **MySQL** | 8.0+ | 数据库（生产环境，推荐） | +| **SQLite** | -（开发/小型 | 数据库部署） | + +### 端口要求 + +| 端口 | 用途 | 协议 | |------|------|------| -| Node.js | ≥14.0.0（推荐 20.x LTS） | 运行环境 | -| npm | ≥6.0.0 | 包管理器（随 Node.js 安装） | -| 操作系统 | Windows 10/11、macOS、Linux | 支持主流操作系统 | -| 内存 | 开发：4GB+ / 生产：8GB+ | 根据数据量调整 | -| 磁盘空间 | ≥2GB | 包含依赖和日志 | +| 8000 | 后端API服务 | HTTP | +| 3000 | 前端开发服务 | HTTP | +| 80 | Nginx HTTP | HTTP | +| 443 | Nginx HTTPS | HTTPS | -### Node.js 安装 +--- -#### Linux（自动安装） +## 开发环境部署 -运行 `node install.js`，选择自动安装即可。 - -#### Linux（手动安装） - -**Ubuntu/Debian:** -```bash -curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - -sudo apt-get install -y nodejs -``` - -**CentOS/RHEL/Fedora:** -```bash -curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash - -sudo yum install -y nodejs -``` - -**Arch Linux:** -```bash -sudo pacman -S nodejs npm -``` - -**使用 nvm（推荐开发者）:** -```bash -# 安装 nvm -curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash - -# 安装 Node.js 20 -nvm install 20 -nvm use 20 -``` +### 1. 环境准备 #### Windows @@ -118,11 +131,7 @@ winget install OpenJS.NodeJS.LTS brew install node@20 ``` -**方式二：官方安装包** -1. 访问: https://nodejs.org/ -2. 下载 macOS 安装包并安装 - -**方式三：nvm（推荐开发者）** +**方式二：nvm（推荐开发者）** ```bash # 安装 nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash @@ -132,35 +141,52 @@ nvm install 20 nvm use 20 ``` ---- +#### Linux -## 开发环境部署 - -### 1. 克隆项目 - -**方式一：从GitHub克隆（推荐）** +**Ubuntu/Debian:** ```bash -git clone https://github.com/gituib/idc_assest.git -cd idc_assest +curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - +sudo apt-get install -y nodejs ``` -**方式二：从Gitee克隆（国内访问更快）** +**CentOS/RHEL/Fedora:** ```bash +curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash - +sudo yum install -y nodejs +``` + +**使用 nvm（推荐开发者）:** +```bash +curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash +nvm install 20 +nvm use 20 +``` + +### 2. 克隆项目 + +```bash +# 从Gitee克隆（国内访问更快） git clone https://gitee.com/zhang96110/idc_assest.git + +# 或从GitHub克隆 +git clone https://github.com/gituib/idc_assest.git + cd idc_assest ``` -### 2. 安装依赖 +### 3. 安装依赖 ```bash # 安装后端依赖 -cd backend && npm install +cd backend +npm install -# 安装前端依赖 -cd ../frontend && npm install +# 安装前端依赖（新终端） +cd ../frontend +npm install ``` -### 3. 配置环境变量 +### 4. 配置环境变量 ```bash cd ../backend @@ -168,67 +194,113 @@ cp .env.example .env ``` 编辑 `.env` 文件（开发环境使用默认SQLite配置即可）： + ```env +# 开发环境配置 NODE_ENV=development PORT=8000 DB_TYPE=sqlite +DB_PATH=./idc_management.db + +# JWT配置（开发环境可使用简单密钥） +JWT_SECRET=dev_secret_key_change_in_production +JWT_EXPIRES_IN=7d ``` -### 4. 启动服务 +### 5. 初始化数据库 -**启动后端（端口8000）：** ```bash +node scripts/init-database.js +``` + +### 6. 启动服务 + +**同时启动前后端（推荐）：** +```bash +# 项目根目录 +npm start +``` + +**分别启动：** +```bash +# 终端1 - 启动后端（端口8000） cd backend npm run dev -``` -**启动前端（端口3000）- 新终端：** -```bash +# 终端2 - 启动前端（端口3000） cd frontend npm run dev ``` -**访问地址：** -- 前端应用：http://localhost:3000 -- 后端API：http://localhost:8000/api -- 健康检查：http://localhost:8000/health +### 7. 访问开发环境 -### 5. 开发脚本 +| 服务 | 地址 | +|------|------| +| 前端应用 | http://localhost:3000 | +| 后端API | http://localhost:8000/api | +| 健康检查 | http://localhost:8000/health | + +### 8. 开发命令 ```bash -# 同时启动前后端（项目根目录） -npm start +# 项目根目录命令 +npm start # 同时启动前后端 +npm run start:backend # 仅启动后端 +npm run start:frontend # 仅启动前端 +npm run install:all # 安装所有依赖 -# 仅启动后端 -npm run start:backend +# 后端命令 +cd backend +npm run dev # 开发模式启动（热重载） +npm start # 生产模式启动 -# 仅启动前端 -npm run start:frontend - -# 安装所有依赖 -npm run install:all +# 前端命令 +cd frontend +npm run dev # 开发模式启动 +npm run build # 构建生产版本 +npm run preview # 预览生产版本 ``` --- -## 生产环境部署 +## 测试环境部署 -### 方式一：一键部署脚本（推荐） +### 1. 服务器准备 + +测试环境配置要求： + +| 项目 | 配置 | +|------|------| +| **操作系统** | Ubuntu 20.04 LTS / CentOS 8 | +| **Node.js** | 20.x LTS | +| **内存** | 4GB | +| **磁盘** | 20GB SSD | +| **数据库** | MySQL 8.0（与生产一致） | + +### 2. 配置数据库 ```bash -npm run deploy +# 安装MySQL +sudo apt update +sudo apt install -y mysql-server + +# 启动MySQL +sudo systemctl start mysql +sudo systemctl enable mysql + +# 创建数据库和用户 +sudo mysql ``` -按提示选择： -- 数据库类型：SQLite 或 MySQL -- 前端部署方式：Nginx（推荐）或 PM2 serve -- 是否自动安装 Nginx（Windows） +```sql +CREATE DATABASE idc_management CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; +CREATE USER 'idc_test'@'localhost' IDENTIFIED BY 'test_password'; +GRANT ALL PRIVILEGES ON idc_management.* TO 'idc_test'@'localhost'; +FLUSH PRIVILEGES; +EXIT; +``` -### 方式二：手动部署 - -#### 后端部署 - -##### 1. 配置环境变量 +### 3. 配置环境变量 ```bash cd backend @@ -236,187 +308,364 @@ cp .env.example .env ``` 编辑 `.env` 文件： + ```env +NODE_ENV=test +PORT=8000 +DB_TYPE=mysql +MYSQL_HOST=localhost +MYSQL_PORT=3306 +MYSQL_USERNAME=idc_test +MYSQL_PASSWORD=test_password +MYSQL_DATABASE=idc_management +JWT_SECRET=test_jwt_secret_key +JWT_EXPIRES_IN=24h +``` + +### 4. 安装依赖并初始化 + +```bash +# 安装后端依赖 +cd backend +npm install + +# 初始化数据库 +node scripts/init-database.js + +# 安装前端依赖并构建 +cd ../frontend +npm install +npm run build +``` + +### 5. 使用PM2启动服务 + +```bash +# 安装PM2 +npm install -g pm2 + +# 启动后端服务 +cd ../backend +pm2 start server.js --name "idc-test-backend" --env test + +# 启动前端静态服务 +cd ../frontend +pm2 serve --name "idc-test-frontend" -s dist -l 3000 + +# 保存PM2配置 +pm2 save + +# 配置开机自启 +pm2 startup +``` + +### 6. 测试验证 + +```bash +# 测试后端API +curl http://localhost:8000/health + +# 测试前端 +curl http://localhost:3000 +``` + +--- + +## 生产环境部署 + +### 1. 服务器要求 + +#### 硬件要求 + +| 规模 | CPU | 内存 | 磁盘 | +|------|-----|------|------| +| 小型（<100设备） | 2核心 | 4GB | 40GB | +| 中型（100-500设备） | 4核心 | 8GB | 80GB | +| 大型（>500设备） | 8核心+ | 16GB+ | 100GB+ | + +#### 软件要求 + +| 软件 | 版本 | 说明 | +|------|------|------| +| 操作系统 | Ubuntu 20.04+ / CentOS 8+ | 推荐 Ubuntu 22.04 LTS | +| Node.js | 20.x LTS | 运行时环境 | +| MySQL | 8.0+ | 数据库 | +| Nginx | 1.18+ | 反向代理/静态文件 | +| PM2 | 5.x+ | 进程管理 | + +### 2. 系统配置 + +#### 创建部署用户（非root） + +```bash +# 创建用户 +sudo adduser idcadmin + +# 赋予sudo权限 +sudo usermod -aG sudo idcadmin + +# 切换到部署用户 +sudo su - idcadmin +``` + +#### 配置防火墙 + +```bash +# Ubuntu +sudo ufw allow 22 # SSH +sudo ufw allow 80 # HTTP +sudo ufw allow 443 # HTTPS +sudo ufw enable + +# CentOS +sudo firewall-cmd --permanent --add-port=22/tcp +sudo firewall-cmd --permanent --add-port=80/tcp +sudo firewall-cmd --permanent --add-port=443/tcp +sudo firewall-cmd --reload +``` + +### 3. 安装软件 + +#### 安装Node.js + +```bash +# Ubuntu/Debian +curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - +sudo apt-get install -y nodejs + +# 安装PM2 +sudo npm install -g pm2 +``` + +#### 安装MySQL + +```bash +# Ubuntu +sudo apt install -y mysql-server + +sudo apt update +# 启动并配置 +sudo systemctl start mysql +sudo systemctl enable mysql +``` + +#### 安装Nginx + +```bash +# Ubuntu +sudo apt install -y nginx +sudo systemctl start nginx +sudo systemctl enable nginx +``` + +### 4. 配置数据库 + +```bash +sudo mysql +``` + +```sql +-- 创建数据库 +CREATE DATABASE idc_management CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; + +-- 创建用户（生产环境使用强密码） +CREATE USER 'idc_prod'@'localhost' IDENTIFIED BY 'YOUR_STRONG_PASSWORD_HERE'; +GRANT ALL PRIVILEGES ON idc_management.* TO 'idc_prod'@'localhost'; +FLUSH PRIVILEGES; + +EXIT; +``` + +### 5. 部署项目 + +#### 克隆项目 + +```bash +cd /var/www +sudo git clone https://gitee.com/zhang96110/idc_assest.git +sudo chown -R idcadmin:idcadmin idc_assest +``` + +#### 配置环境变量 + +```bash +cd /var/www/idc_assest/backend +cp .env.example .env +nano .env +``` + +编辑 `.env` 文件： + +```env +# 生产环境配置 NODE_ENV=production PORT=8000 DB_TYPE=mysql MYSQL_HOST=localhost MYSQL_PORT=3306 -MYSQL_USERNAME=idc_user -MYSQL_PASSWORD=secure_password +MYSQL_USERNAME=idc_prod +MYSQL_PASSWORD=YOUR_STRONG_PASSWORD_HERE MYSQL_DATABASE=idc_management -JWT_SECRET=your_jwt_secret_key_here + +# JWT配置（使用强随机密钥） +JWT_SECRET=$(openssl rand -base64 32) +JWT_EXPIRES_IN=24h + +# 日志配置 +LOG_LEVEL=info ``` -##### 2. 安装生产依赖 +### 6. 安装依赖 ```bash +# 安装后端依赖 +cd /var/www/idc_assest/backend npm install --production -``` -##### 3. 配置数据库 - -**创建数据库：** -```sql -CREATE DATABASE idc_management CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; -CREATE USER 'idc_user'@'localhost' IDENTIFIED BY 'secure_password'; -GRANT ALL PRIVILEGES ON idc_management.* TO 'idc_user'@'localhost'; -FLUSH PRIVILEGES; -``` - -##### 4. 初始化数据库 - -```bash -node scripts/init-database.js -``` - -##### 5. 使用PM2管理进程 - -```bash -# 安装 PM2 -npm install -g pm2 - -# 启动服务 -pm2 start server.js --name "idc-backend" --cwd ./backend --env production - -# 配置开机自启 -pm2 startup -pm2 save -``` - -#### 前端部署 - -##### 1. 构建生产版本 - -```bash -cd frontend +# 安装前端依赖并构建 +cd ../frontend npm install npm run build ``` -构建输出目录：`frontend/dist/` +### 7. 初始化数据库 -##### 2. 部署静态文件 - -**Nginx 方式（推荐）：** ```bash -# 复制构建文件到Nginx目录 -sudo cp -r frontend/dist/* /var/www/idc-frontend/ -sudo chown -R www-data:www-data /var/www/idc-frontend -sudo chmod -R 755 /var/www/idc-frontend +cd ../backend +node scripts/init-database.js ``` -**PM2 serve 方式：** +### 8. 配置PM2 + ```bash -npm install -g serve -pm2 start serve --name "idc-frontend" -- -s frontend/dist -l 3000 +# 创建PM2配置文件 +nano /var/www/idc_assest/ecosystem.config.js ``` -### Nginx配置 - -#### 1. 创建配置文件 - -**Linux:** -```bash -sudo nano /etc/nginx/sites-available/idc_assest +```javascript +module.exports = { + apps: [ + { + name: 'idc-backend', + script: './server.js', + cwd: '/var/www/idc_assest/backend', + instances: 1, + exec_mode: 'fork', + env: { + NODE_ENV: 'production', + PORT: 8000 + }, + max_memory_restart: '1G', + log_file: '/var/log/idc/combined.log', + out_file: '/var/log/idc/out.log', + error_file: '/var/log/idc/error.log', + log_date_format: 'YYYY-MM-DD HH:mm:ss Z', + merge_logs: true, + autorestart: true, + watch: false + } + ] +}; ``` -**Windows:** -编辑 `C:\nginx\conf\nginx.conf` 或在 `conf.d` 目录创建新配置 +```bash +# 创建日志目录 +sudo mkdir -p /var/log/idc +sudo chown -R idcadmin:idcadmin /var/log/idc -#### 2. 配置内容 +# 启动服务 +cd /var/www/idc_assest +pm2 start ecosystem.config.js +pm2 save +pm2 startup +``` + +### 9. 配置Nginx + +```bash +sudo nano /etc/nginx/sites-available/idc +``` ```nginx +upstream idc_backend { + server 127.0.0.1:8000; +} + server { listen 80; - server_name your-domain.com; - - root /var/www/idc-frontend; + server_name your-domain.com; # 替换为实际域名 + + # 前端静态文件 + root /var/www/idc_assest/frontend/dist; index index.html; - + # Gzip压缩 gzip on; gzip_vary on; gzip_min_length 1024; gzip_types text/plain text/css text/xml text/javascript application/javascript application/xml+rss application/json; - + # 静态资源缓存 location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ { expires 1y; add_header Cache-Control "public, immutable"; } - - # 前端路由支持 + + # 前端路由支持（SPA） location / { try_files $uri $uri/ /index.html; } - + # API代理 location /api { - proxy_pass http://127.0.0.1:8000; + proxy_pass http://idc_backend; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; proxy_connect_timeout 60s; proxy_send_timeout 60s; proxy_read_timeout 60s; } - + # 文件上传代理 location /uploads { - proxy_pass http://127.0.0.1:8000; + proxy_pass http://idc_backend; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; client_max_body_size 50M; } + + # 健康检查 + location /health { + proxy_pass http://idc_backend/health; + } } ``` -#### 3. 启用配置 - -**Linux:** ```bash -sudo ln -s /etc/nginx/sites-available/idc_assest /etc/nginx/sites-enabled/ +# 启用配置 +sudo ln -s /etc/nginx/sites-available/idc /etc/nginx/sites-enabled/ +sudo rm -f /etc/nginx/sites-enabled/default sudo nginx -t -sudo systemctl restart nginx +sudo systemctl reload nginx ``` -**Windows:** -```cmd -nginx -t -nginx -s reload -``` +### 10. 配置SSL证书（可选） -### SSL证书配置（可选） +使用 Let's Encrypt 免费证书： -**使用 Let's Encrypt（Linux）：** ```bash -sudo apt install certbot python3-certbot-nginx +# 安装Certbot +sudo apt install -y certbot python3-certbot-nginx + +# 获取证书 sudo certbot --nginx -d your-domain.com -``` -**手动配置SSL：** -```nginx -server { - listen 443 ssl http2; - server_name your-domain.com; - - ssl_certificate /path/to/cert.pem; - ssl_certificate_key /path/to/key.pem; - ssl_protocols TLSv1.2 TLSv1.3; - ssl_ciphers HIGH:!aNULL:!MD5; - - # ... 其他配置 -} - -# HTTP重定向到HTTPS -server { - listen 80; - server_name your-domain.com; - return 301 https://$server_name$request_uri; -} +# 自动续期测试 +sudo certbot renew --dry-run ``` --- @@ -447,6 +696,7 @@ services: - MYSQL_DATABASE=idc_management volumes: - ./backend/uploads:/app/uploads + - ./backend/logs:/app/logs depends_on: - mysql restart: unless-stopped @@ -476,7 +726,8 @@ volumes: mysql_data: ``` -启动服务： +### 启动服务 + ```bash docker-compose up -d ``` @@ -500,14 +751,6 @@ docker-compose up -d CREATE DATABASE idc_management CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; ``` -#### 创建用户 - -```sql -CREATE USER 'idc_user'@'localhost' IDENTIFIED BY 'secure_password'; -GRANT ALL PRIVILEGES ON idc_management.* TO 'idc_user'@'localhost'; -FLUSH PRIVILEGES; -``` - #### 配置优化 ```ini @@ -526,32 +769,20 @@ innodb_buffer_pool_size=1G ```bash # 手动备份 cp backend/idc_management.db backup/database_$(date +%Y%m%d).db - -# 自动备份脚本 -#!/bin/bash -BACKUP_DIR="/var/backups/idc_assest" -DATE=$(date +%Y%m%d_%H%M%S) -mkdir -p $BACKUP_DIR -cp backend/idc_management.db "$BACKUP_DIR/database_$DATE.db" -gzip "$BACKUP_DIR/database_$DATE.db" - -# 清理30天前的备份 -find $BACKUP_DIR -name "database_*.gz" -mtime +30 -delete ``` #### MySQL备份 ```bash # 手动备份 -mysqldump -u idc_user -p idc_management > backup/database_$(date +%Y%m%d).sql +mysqldump -u idc_prod -p idc_management > backup/database_$(date +%Y%m%d).sql # 自动备份脚本 #!/bin/bash -BACKUP_DIR="/var/backups/idc_assest" +BACKUP_DIR="/var/backups/idc" DATE=$(date +%Y%m%d_%H%M%S) mkdir -p $BACKUP_DIR - -mysqldump -u idc_user -pYourPassword idc_management > "$BACKUP_DIR/database_$DATE.sql" +mysqldump -u idc_prod -pYourPassword idc_management > "$BACKUP_DIR/database_$DATE.sql" gzip "$BACKUP_DIR/database_$DATE.sql" # 清理30天前的备份 @@ -567,6 +798,58 @@ crontab -e --- +## 部署验证 + +### 1. 服务状态检查 + +```bash +# PM2服务状态 +pm2 status + +# Nginx状态 +sudo systemctl status nginx + +# MySQL状态 +sudo systemctl status mysql +``` + +### 2. 接口验证 + +```bash +# 健康检查 +curl http://localhost:8000/health + +# API测试 +curl http://localhost:8000/api/rooms + +# 上传接口测试 +curl -X POST http://localhost:8000/api/auth/login \ + -H "Content-Type: application/json" \ + -d '{"username":"admin","password":"admin123"}' +``` + +### 3. 日志检查 + +```bash +# PM2日志 +pm2 logs idc-backend + +# 错误日志 +pm2 logs idc-backend --err + +# Nginx错误日志 +sudo tail -f /var/log/nginx/error.log +``` + +### 4. 性能测试 + +```bash +# 使用curl测试响应时间 +time curl -o /dev/null -s -w "%{http_code}\n" http://localhost:8000/health +``` + +--- + ## 更新升级 ### 方式一：一键更新脚本（推荐） @@ -582,65 +865,75 @@ npm run update #### 1. 备份数据 ```bash -# MySQL -mysqldump -u idc_user -p idc_management > backup.sql +# 备份数据库 +mysqldump -u idc_prod -p idc_management > /var/backups/idc/database_backup_$(date +%Y%m%d).sql -# SQLite -cp backend/idc_management.db backup.db +# 或备份SQLite +cp backend/idc_management.db /var/backups/idc/ ``` #### 2. 拉取最新代码 ```bash -git pull origin master +cd /var/www/idc_assest +git pull origin main ``` #### 3. 更新依赖 ```bash -cd backend && npm install -cd ../frontend && npm install && npm run build +# 更新后端依赖 +cd backend +npm install + +# 更新前端依赖并构建 +cd ../frontend +npm install +npm run build ``` -#### 4. 重启服务 +#### 4. 运行数据库迁移（如有） + +```bash +cd ../backend +node scripts/migrate-all.js +``` + +#### 5. 重启服务 ```bash pm2 restart idc-backend -sudo systemctl restart nginx +sudo nginx -t && sudo nginx -s reload ``` --- ## 监控维护 -### 查看日志 +### 服务管理命令 ```bash -# PM2 日志 -pm2 logs idc-backend -pm2 logs idc-frontend +# PM2 管理 +pm2 status # 查看服务状态 +pm2 logs idc-backend # 查看后端日志 +pm2 logs idc-backend --err # 查看错误日志 +pm2 restart idc-backend # 重启后端服务 +pm2 stop idc-backend # 停止后端服务 +pm2 delete idc-backend # 删除后端服务 +pm2 save # 保存当前进程列表 +pm2 startup # 配置开机自启 +pm2 monit # 实时监控 -# Nginx 日志（Linux） -tail -f /var/log/nginx/idc_assest-error.log -tail -f /var/log/nginx/idc_assest-access.log - -# 系统日志（Linux） -journalctl -u idc-backend -f -``` - -### 健康检查 - -```bash -# 服务状态 -curl http://localhost:8000/health - -# 数据库连接检查 -curl http://localhost:8000/api/health/db +# Nginx 管理 +sudo nginx -t # 测试配置 +sudo systemctl restart nginx # 重启服务 +sudo systemctl status nginx # 查看状态 ``` ### 性能监控 -**PM2配置**（`ecosystem.config.js`）： +#### PM2配置（`ecosystem.config.js`） + ```javascript module.exports = { apps: [{ @@ -662,31 +955,6 @@ module.exports = { }; ``` -### 服务管理命令 - -```bash -# PM2 管理 -pm2 status # 查看服务状态 -pm2 logs idc-backend # 查看后端日志 -pm2 logs idc-frontend # 查看前端日志（PM2方式） -pm2 restart idc-backend # 重启后端服务 -pm2 stop idc-backend # 停止后端服务 -pm2 delete idc-backend # 删除后端服务 -pm2 save # 保存当前进程列表 -pm2 startup # 配置开机自启 -pm2 monit # 实时监控 - -# Nginx 管理（Linux） -sudo nginx -t # 测试配置 -sudo systemctl restart nginx # 重启服务 -sudo systemctl status nginx # 查看状态 - -# Nginx 管理（Windows） -nginx -t # 测试配置 -nginx -s reload # 重载配置 -nginx -s stop # 停止Nginx -``` - --- ## 常见问题 @@ -697,11 +965,13 @@ nginx -s stop # 停止Nginx # 检查端口占用 # Linux netstat -tulpn | grep :8000 + # Windows netstat -ano | findstr :8000 # 修改端口 -PORT=8001 npm run dev +# 编辑 backend/.env 文件 +PORT=8001 ``` ### 依赖安装失败 @@ -710,37 +980,19 @@ PORT=8001 npm run dev # 清理缓存 npm cache clean --force -# 删除 node_modules +# 删除 node_modules 重新安装 rm -rf node_modules package-lock.json - -# 重新安装 npm install ``` ### 数据库连接失败 -**SQLite：** -- 检查文件权限 -- 确保磁盘空间充足 -- 检查文件是否被其他进程占用 - **MySQL：** -- 检查服务状态：`systemctl status mysql`（Linux） +- 检查服务状态：`sudo systemctl status mysql` - 验证连接参数（主机、端口、用户名、密码） - 确认数据库已创建 - 检查防火墙设置 -- 确认用户权限：`SHOW GRANTS FOR 'idc_user'@'localhost'` - -### 部署脚本问题 - -**Linux 自动安装 Node.js 失败：** -- 检查 sudo 权限 -- 检查网络连接 -- 尝试手动安装后重新运行脚本 - -**Nginx 未安装（选择 Nginx 部署时）：** -- Windows：脚本会询问是否自动下载安装 -- Linux/macOS：脚本会显示安装命令，需手动安装 +- 确认用户权限：`SHOW GRANTS FOR 'idc_prod'@'localhost'` ### 前端构建失败 @@ -757,11 +1009,9 @@ npm run build ### 权限问题 -**Linux:** ```bash # 修复文件权限 -sudo chown -R $(whoami):$(whoami) /path/to/project -sudo chmod -R 755 /path/to/project +sudo chown -R $(whoami):$(whoami) /var/www/idc_assest # 上传目录权限 sudo chmod -R 777 backend/uploads @@ -777,6 +1027,26 @@ node --max-old-space-size=4096 server.js pm2 start server.js --name "idc-backend" --node-args="--max-old-space-size=4096" ``` +### Nginx 502 Bad Gateway + +1. 检查后端服务是否运行：`pm2 status` +2. 检查后端端口是否监听：`netstat -tulpn | grep 8000` +3. 检查Nginx配置：`nginx -t` +4. 查看错误日志：`tail -f /var/log/nginx/error.log` + +### SSL证书问题 + +```bash +# 检查证书是否过期 +sudo certbot certificates + +# 手动续期 +sudo certbot renew + +# 查看证书详情 +sudo certbot certificates +``` + --- ## 项目结构 @@ -785,33 +1055,33 @@ pm2 start server.js --name "idc-backend" --node-args="--max-old-space-size=4096" idc_assest/ ├── backend/ # 后端服务 │ ├── middleware/ # 中间件（认证、验证） -│ ├── models/ # 数据模型（Sequelize） -│ ├── routes/ # API路由 -│ ├── scripts/ # 数据库脚本 -│ ├── uploads/ # 文件上传目录 -│ ├── validation/ # 数据验证Schema -│ ├── server.js # 服务入口 +│ ├── models/ # 数据模型（Sequelize） +│ ├── routes/ # API路由 +│ ├── scripts/ # 数据库脚本 +│ ├── uploads/ # 文件上传目录 +│ ├── validation/ # 数据验证Schema +│ ├── server.js # 服务入口 │ └── package.json -├── frontend/ # 前端应用 +├── frontend/ # 前端应用 │ ├── src/ -│ │ ├── api/ # API接口 -│ │ ├── components/ # 组件 -│ │ ├── pages/ # 页面 -│ │ └── utils/ # 工具函数 -│ ├── dist/ # 构建输出 +│ │ ├── api/ # API接口 +│ │ ├── components/ # 组件 +│ │ ├── pages/ # 页面 +│ │ └── utils/ # 工具函数 +│ ├── dist/ # 构建输出 │ └── package.json -├── docs/ # 项目文档 -│ ├── api/ # 接口文档 -│ └── images/ # 文档图片 -├── install.js # 交互式安装脚本 ⭐ -├── update.js # 一键更新脚本 ⭐ -├── uninstall.js # 卸载脚本 -├── check.js # 环境检查脚本 -├── modify.js # 配置修改脚本 +├── docs/ # 项目文档 +│ ├── api/ # 接口文档 +│ └── images/ # 文档图片 +├── install.js # 交互式安装脚本 ⭐ +├── update.js # 一键更新脚本 ⭐ +├── uninstall.js # 卸载脚本 +├── check.js # 环境检查脚本 +├── modify.js # 配置修改脚本 ├── package.json -├── README.md # 项目说明 -├── CHANGELOG.md # 版本记录 -└── DEPLOYMENT.md # 本文件 +├── README.md # 项目说明 +├── CHANGELOG.md # 版本记录 +└── DEPLOYMENT.md # 本文件 ``` --- diff --git a/README.md b/README.md index 4f7859c..64d0702 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,33 @@ # IDC设备管理系统 +[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) +[![Node.js](https://img.shields.io/badge/Node.js-20.x-green.svg)](https://nodejs.org/) +[![React](https://img.shields.io/badge/React-18.2.0-blue.svg)](https://react.dev/) +[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey.svg)]() + 一个现代化的数据中心（IDC）设备管理系统，提供机房、机柜、设备的全生命周期管理，具备3D可视化展示功能。 ## 代码仓库 +- **GitHub**: https://github.com/gituib/idc_assest - **Gitee**: https://gitee.com/zhang96110/idc_assest +--- + ## 系统概述 ### 核心功能 | 功能模块 | 描述 | |---------|------| -| **机房管理** | 多机房管理，支持位置、面积等详细信息 | +| **机房管理** | 多机房管理，支持位置、面积、负责人等详细信息 | | **机柜管理** | 机柜增删改查，容量统计，3D可视化展示 | | **设备管理** | 服务器、网络设备、存储设备全生命周期管理，支持批量导入/导出 | | **端口管理** | 设备端口配置与管理，支持网卡绑定 | | **线缆管理** | 机柜间线缆连接管理，可视化追踪 | | **工单管理** | 故障报修、维护工单全流程管理，支持自定义字段 | | **耗材管理** | 耗材库存、领用记录、统计报表管理 | +| **盘点管理** | 盘点计划制定与执行，盘点任务分配与结果记录 | | **数据看板** | 实时监控数据中心整体运行状态 | | **3D可视化** | 三维机柜可视化展示，支持设备悬停详情、LOD优化 | | **系统配置** | 设备字段、工单字段自定义管理，背景配置 | @@ -38,9 +47,11 @@ ![机房管理](docs/images/room-management.png) *机房管理 - 多机房分类管理* -### 技术栈 +--- -#### 前端技术栈 +## 技术栈 + +### 前端技术栈 | 技术 | 版本 | 用途 | |------|------|------| @@ -48,67 +59,64 @@ | Vite | 4.4.9 | 构建工具（前端项目打包工具） | | Ant Design | 5.8.6 | UI组件库（企业级设计系统） | | Three.js | 0.160.0 | 3D渲染引擎 | +| @react-three/fiber | 8.18.0 | React Three.js 集成 | +| @react-three/drei | 9.122.0 | Three.js 辅助组件库 | | React Router | 6.15.0 | 路由管理 | | Axios | 1.5.0 | HTTP客户端 | | Day.js | 1.11.19 | 日期处理库 | | SheetJS (xlsx) | 0.18.5 | Excel文件处理 | | PapaParse | 5.5.3 | CSV文件解析 | +| Framer Motion | 12.34.0 | 动画库 | +| Styled Components | 6.3.9 | CSS-in-JS 样式方案 | +| SWR | 2.4.0 | 数据请求与缓存 | -#### 后端技术栈 +### 后端技术栈 | 技术 | 版本 | 用途 | |------|------|------| -| Node.js | ≥14.0.0 | 运行环境 | +| Node.js | ≥14.0.0（推荐 20.x LTS） | 运行环境 | | Express | 4.18.2 | Web框架（后端服务框架） | | Sequelize | 6.32.1 | ORM框架（数据库对象关系映射） | -| SQLite/MySQL | 5.1.6/8.0+ | 数据库 | +| SQLite | 5.1.6 | 嵌入式数据库（开发/小规模） | +| MySQL | 8.0+ | 关系型数据库（生产环境） | | JWT | 9.0.3 | 身份认证 | | bcryptjs | 3.0.3 | 密码加密 | | Winston | 3.19.0 | 日志管理 | +| Joi | 18.0.2 | 数据验证 | | Jest | 30.2.0 | 测试框架 | -## 项目结构 +--- -``` -jigui/ -├── frontend/ # 前端项目 -│ ├── src/ -│ │ ├── api/ # API接口封装 -│ │ ├── assets/ # 静态资源（字体、3D环境贴图） -│ │ ├── components/ # 通用组件 -│ │ │ ├── 3d/ # 3D可视化组件 -│ │ │ │ ├── materials/ # 3D材质组件 -│ │ │ │ ├── DeviceModel.jsx # 设备模型 -│ │ │ │ ├── RackModel.jsx # 机柜模型 -│ │ │ │ ├── Scene.jsx # 3D场景 -│ │ │ │ └── LODManager.jsx # LOD管理器 -│ │ │ └── *.jsx # 业务组件 -│ │ ├── context/ # React Context状态管理 -│ │ ├── hooks/ # 自定义Hooks -│ │ ├── pages/ # 页面模块 -│ │ └── utils/ # 工具函数 -│ ├── public/ # 公共资源 -│ └── vite.config.js # Vite配置 -├── backend/ # 后端项目 -│ ├── middleware/ # 中间件（认证、验证） -│ ├── models/ # 数据模型（Sequelize） -│ ├── routes/ # API路由 -│ ├── scripts/ # 数据库脚本 -│ ├── uploads/ # 文件上传目录 -│ ├── validation/ # 数据验证Schema -│ └── server.js # 服务入口 -├── docs/ # 项目文档 -│ ├── api/ # 接口文档 -│ └── images/ # 文档图片 -├── install.js # 交互式安装脚本 ⭐ -├── update.js # 一键更新脚本 ⭐ -├── uninstall.js # 卸载脚本 -├── check.js # 环境检查脚本 -├── modify.js # 配置修改脚本 -├── README.md # 项目说明 -├── CHANGELOG.md # 版本记录 -└── DEPLOYMENT.md # 部署指南 -``` +## 环境要求 + +### 运行环境 + +| 项目 | 最低要求 | 推荐配置 | +|------|----------|----------| +| **操作系统** | Windows 10/11、macOS 12+、Linux (Ubuntu 20.04+/CentOS 8+) | 同最低要求 | +| **Node.js** | ≥14.0.0 | 20.x LTS | +| **npm** | ≥6.0.0 | 10.x | +| **内存** | 4GB | 8GB+ | +| **磁盘空间** | 2GB | 10GB+ | + +### 生产环境额外要求 + +| 项目 | 要求 | +|------|------| +| **数据库** | MySQL 8.0+ (推荐) 或 SQLite (小型部署) | +| **Web服务器** | Nginx 1.18+ (反向代理/静态文件服务) | +| **进程管理** | PM2 5.x+ | +| **SSL证书** | Let's Encrypt (可选) | + +### 开发环境要求 + +| 项目 | 要求 | +|------|------| +| **代码编辑器** | VS Code (推荐) | +| **浏览器** | Chrome 90+、Firefox 90+、Safari 14+、Edge 90+ | +| **Git** | 2.30+ | + +--- ## 快速开始 @@ -138,75 +146,53 @@ node install.js - ✅ 自动构建前端项目 - ✅ 使用 PM2 启动和管理服务 -**交互配置示例：** -``` -▶ 环境检测 -✓ Node.js v20.11.0 -✓ npm 10.2.4 -✓ PM2 已安装 - -▶ 数据库配置 -选择数据库类型： - 1. SQLite（零配置，适合开发/小规模） - 2. MySQL（生产环境推荐） -请选择 (1): 1 - -▶ 服务配置 -后端服务端口 (8000): -选择运行环境： - 1. production（生产模式，性能优化，推荐正式部署） - 2. development（开发模式，详细日志，便于调试） -请选择 (1): 1 -前端部署方式： - 1. Nginx（性能最优，推荐生产环境） - 2. PM2 serve（简单快捷，无需额外安装） -请选择 (1): 1 - -▶ 配置确认 -部署配置摘要： - 数据库类型: sqlite - 后端端口: 8000 - 运行环境: production - 前端部署: nginx - 前端端口: 80 -确认以上配置并开始部署? (Y/n): Y - -✓ 后端环境变量文件已生成 (.env) -✓ PM2 配置文件已生成 (ecosystem.config.js) -✓ Nginx 配置文件已生成 (nginx-idc.conf) -✓ 安装部署完成！ -``` - ### 方式二：手动安装 -#### 环境要求 - -| 项目 | 要求 | -|------|------| -| Node.js | ≥14.0.0（推荐 20.x LTS） | -| npm | ≥6.0.0 | -| 操作系统 | Windows 10/11、macOS、Linux | - -#### 安装步骤 +#### 1. 克隆项目 ```bash -# 1. 克隆项目 git clone https://gitee.com/zhang96110/idc_assest.git cd idc_assest +``` -# 2. 安装后端依赖 +#### 2. 安装依赖 + +```bash +# 安装后端依赖 cd backend npm install -# 3. 安装前端依赖 +# 安装前端依赖 cd ../frontend npm install +``` -# 4. 配置环境变量 +#### 3. 配置环境变量 + +```bash cd ../backend cp .env.example .env +``` -# 5. 启动服务 +根据需要编辑 `.env` 文件（开发环境使用默认 SQLite 配置即可）： + +```env +# 开发环境配置示例 +NODE_ENV=development +PORT=8000 +DB_TYPE=sqlite +DB_PATH=./idc_management.db +``` + +#### 4. 初始化数据库 + +```bash +node scripts/init-database.js +``` + +#### 5. 启动服务 + +```bash # 启动后端（端口8000） npm run dev @@ -215,11 +201,182 @@ cd ../frontend npm run dev ``` -**访问地址**： +**访问地址：** - 前端应用：http://localhost:3000 - 后端API：http://localhost:8000/api - 健康检查：http://localhost:8000/health +--- + +## 基本使用方法 + +### 首次登录 + +系统采用**首次注册自动成为管理员**的机制： + +- 第一个注册的用户会自动获得「管理员」角色 +- 后续注册的用户默认为「访客」角色，需要管理员审核后才能激活 +- 首次访问系统时，请通过注册功能创建管理员账号 + +**注册方式：** +1. 打开系统登录页面 +2. 点击「注册账号」链接 +3. 填写用户名、密码、邮箱等信息 +4. 提交后自动登录，成为系统管理员 + +> ⚠️ **安全建议**：首次登录后请立即修改默认密码！ + +### 常用操作指南 + +#### 1. 机房管理 + +- 进入「机房管理」页面，点击「新增机房」按钮 +- 填写机房名称、位置、面积、负责人等信息 +- 支持机房图片上传 + +#### 2. 机柜管理 + +- 在机房详情页或「机柜管理」页面管理机柜 +- 设置机柜高度（U数）、位置坐标 +- 查看机柜容量使用情况 + +#### 3. 设备管理 + +- 「设备管理」页面进行设备增删改查 +- 支持 Excel/CSV 批量导入设备 +- 设备状态：采购中 → 待安装 → 运行中 → 维护中 → 已报废 + +#### 4. 3D可视化 + +- 进入「3D可视化」页面查看机房3D模型 +- 支持鼠标拖拽旋转、滚轮缩放 +- 悬停设备查看详情，点击设备弹出操作面板 + +#### 5. 工单管理 + +- 创建故障报修或维护工单 +- 分配负责人，设置优先级 +- 记录处理过程，更新工单状态 + +#### 6. 耗材管理 + +- 管理耗材库存，设置库存预警阈值 +- 记录耗材领用，追踪使用去向 +- 查看耗材统计报表 + +--- + +## 项目结构 + +``` +jigui/ +├── frontend/ # 前端项目 +│ ├── src/ +│ │ ├── api/ # API接口封装 +│ │ ├── assets/ # 静态资源（字体、3D环境贴图） +│ │ ├── components/ # 通用组件 +│ │ │ ├── 3d/ # 3D可视化组件 +│ │ │ │ ├── materials/ # 3D材质组件 +│ │ │ │ ├── DeviceModel.jsx # 设备模型 +│ │ │ │ ├── RackModel.jsx # 机柜模型 +│ │ │ │ ├── Scene.jsx # 3D场景 +│ │ │ │ ├── LODManager.jsx # LOD管理器 +│ │ │ │ └── utils.jsx # 3D工具函数 +│ │ │ ├── DeviceDetailDrawer.jsx # 设备详情抽屉 +│ │ │ ├── PortManagementPanel.jsx # 端口管理面板 +│ │ │ └── ... +│ │ ├── context/ # React Context状态管理 +│ │ │ ├── AuthContext.jsx # 认证上下文 +│ │ │ ├── ConfigContext.jsx # 配置上下文 +│ │ │ └── Scene3DContext.jsx # 3D场景上下文 +│ │ ├── hooks/ # 自定义Hooks +│ │ │ ├── useDebounce.js # 防抖Hook +│ │ │ ├── useDesignTokens.js # 设计令牌Hook +│ │ │ └── useIdleTimeout.js # 空闲超时Hook +│ │ ├── pages/ # 页面模块 +│ │ │ ├── Dashboard.jsx # 数据看板 +│ │ │ ├── RoomManagement.jsx # 机房管理 +│ │ │ ├── RackManagement.jsx # 机柜管理 +│ │ │ ├── DeviceManagement.jsx # 设备管理 +│ │ │ ├── PortManagement.jsx # 端口管理 +│ │ │ ├── CableManagement.jsx # 线缆管理 +│ │ │ ├── TicketManagement.jsx # 工单管理 +│ │ │ ├── ConsumableManagement.jsx # 耗材管理 +│ │ │ ├── InventoryManagement.jsx # 盘点管理 +│ │ │ ├── UserManagement.jsx # 用户管理 +│ │ │ ├── SystemSettings.jsx # 系统设置 +│ │ │ └── Rack3DVisualization.jsx # 3D可视化 +│ │ ├── styles/ # 样式文件 +│ │ ├── utils/ # 工具函数 +│ │ ├── config/ # 配置文件 +│ │ ├── constants/ # 常量定义 +│ │ ├── App.jsx # 应用入口 +│ │ ├── main.jsx # 渲染入口 +│ │ └── index.css # 全局样式 +│ ├── public/ # 公共资源 +│ ├── vite.config.mjs # Vite配置 +│ └── package.json # 前端依赖 +├── backend/ # 后端项目 +│ ├── middleware/ # 中间件 +│ │ ├── auth.js # 认证中间件 +│ │ └── validation.js # 验证中间件 +│ ├── models/ # 数据模型（Sequelize） +│ │ ├── Room.js # 机房模型 +│ │ ├── Rack.js # 机柜模型 +│ │ ├── Device.js # 设备模型 +│ │ ├── DeviceField.js # 设备字段模型 +│ │ ├── DevicePort.js # 设备端口模型 +│ │ ├── NetworkCard.js # 网卡模型 +│ │ ├── Cable.js # 线缆模型 +│ │ ├── Ticket.js # 工单模型 +│ │ ├── TicketField.js # 工单字段模型 +│ │ ├── TicketCategory.js # 工单分类模型 +│ │ ├── Consumable.js # 耗材模型 +│ │ ├── ConsumableCategory.js # 耗材分类模型 +│ │ ├── InventoryPlan.js # 盘点计划模型 +│ │ ├── InventoryTask.js # 盘点任务模型 +│ │ ├── InventoryRecord.js # 盘点记录模型 +│ │ ├── User.js # 用户模型 +│ │ ├── Role.js # 角色模型 +│ │ ├── Permission.js # 权限模型 +│ │ └── SystemSetting.js # 系统设置模型 +│ ├── routes/ # API路由 +│ │ ├── auth.js # 认证路由 +│ │ ├── rooms.js # 机房路由 +│ │ ├── racks.js # 机柜路由 +│ │ ├── devices.js # 设备路由 +│ │ ├── tickets.js # 工单路由 +│ │ ├── consumables.js # 耗材路由 +│ │ ├── users.js # 用户路由 +│ │ └── ... +│ ├── scripts/ # 数据库脚本 +│ │ ├── init-database.js # 数据库初始化 +│ │ ├── migrate-*.js # 数据迁移脚本 +│ │ └── archive/ # 归档脚本 +│ ├── uploads/ # 文件上传目录 +│ ├── validation/ # 数据验证Schema +│ ├── server.js # 服务入口 +│ ├── db.js # 数据库连接 +│ └── package.json # 后端依赖 +├── docs/ # 项目文档 +│ ├── api/ # 接口文档 +│ └── images/ # 文档图片 +├── scripts/ # 项目脚本 +│ └── frontend-manager.js # 前端管理脚本 +├── install.js # 交互式安装脚本 ⭐ +├── update.js # 一键更新脚本 ⭐ +├── uninstall.js # 卸载脚本 +├── check.js # 环境检查脚本 +├── modify.js # 配置修改脚本 +├── package.json # 项目根依赖 +├── README.md # 项目说明 +├── CHANGELOG.md # 版本记录 +├── DEPLOYMENT.md # 部署指南 +└── LICENSE # 许可证 +``` + +--- + ## 更新升级 ### 一键更新（推荐）⭐ @@ -233,75 +390,20 @@ npm run update ### 手动更新 ```bash -# 拉取最新代码 +# 1. 拉取最新代码 git pull -# 更新后端 +# 2. 更新后端依赖 cd backend && npm install -# 更新前端并构建 +# 3. 更新前端依赖并构建 cd ../frontend && npm install && npm run build -# 重启服务 +# 4. 重启服务 pm2 restart idc-backend ``` -## 主要功能详解 - -### 机房管理 - -- 多机房支持，机房详细信息记录 -- 按机房分类管理机柜 -- 机房容量统计与状态展示 - -### 机柜管理 - -- 机柜增删改查，支持自定义高度（U数） -- 机柜容量统计，功率管理 -- 3D可视化展示，支持视角控制 - -### 设备管理 - -- 设备全生命周期管理（采购→上线→维护→报废） -- 批量导入/导出（支持Excel/CSV） -- 设备状态跟踪与筛选 -- 自定义设备字段，灵活扩展 -- 网卡管理与端口配置 - -### 端口与线缆管理 - -- 设备端口配置（类型、速率、状态） -- 网卡管理与绑定 -- 线缆连接管理，可视化追踪 -- 支持批量配置 - -### 工单管理 - -- 故障报修流程，支持附件上传 -- 维护工单创建与处理 -- 工单状态追踪，操作记录审计 -- 自定义工单字段和分类 - -### 耗材管理 - -- 耗材分类管理，规格定义 -- 库存监控，预警提醒 -- 领用记录，使用追踪 -- 耗材使用统计报表 - -### 数据看板 - -- 实时统计图表（设备状态、容量使用） -- 关键指标监控 -- 趋势分析 - -### 3D可视化 - -- 三维机柜展示，真实比例渲染 -- 设备悬停详情查看 -- LOD（多级细节）优化，流畅渲染 -- 设备弹出动画（可开关） -- 视角控制（旋转、缩放、平移） +--- ## API接口 @@ -335,6 +437,8 @@ pm2 restart idc-backend } ``` +--- + ## 部署 详细部署指南请参考 [DEPLOYMENT.md](DEPLOYMENT.md)。 @@ -347,7 +451,7 @@ pm2 restart idc-backend - 推荐使用MySQL数据库 - 使用Nginx作为反向代理 -- 配置SSL证书 +- 配置SSL证书（可选） - 建议使用PM2管理进程 ### 服务管理命令 @@ -358,32 +462,151 @@ pm2 status # 查看日志 pm2 logs idc-backend +pm2 logs idc-frontend # 重启服务 pm2 restart idc-backend +pm2 restart idc-frontend # 停止服务 pm2 stop idc-backend + +# 删除服务 +pm2 delete idc-backend ``` -## 版本历史 - -完整版本记录请参考 [CHANGELOG.md](CHANGELOG.md)。 - -## 许可证 - -本项目采用 MIT 许可证，详见 [LICENSE](LICENSE)。 - -## 贡献指南 - -欢迎提交Issue或Pull Request。 - -1. Fork本项目 -2. 创建功能分支 (`git checkout -b feature/AmazingFeature`) -3. 提交更改 (`git commit -m 'Add some AmazingFeature'`) -4. 推送到分支 (`git push origin feature/AmazingFeature`) -5. 开启Pull Request - --- -**⭐ 如果这个项目对您有帮助，请给我们一个Star！** +## 贡献指南 + +欢迎提交 Issue 或 Pull Request 为项目贡献力量。 + +### 贡献流程 + +1. **Fork 本项目** + +2. **克隆 Fork 的仓库** + + ```bash + git clone https://github.com/YOUR_USERNAME/idc_assest.git + cd idc_assest + ``` + +3. **创建功能分支** + + ```bash + # 功能开发 + git checkout -b feature/your-feature-name + + # Bug 修复 + git checkout -b fix/your-fix-name + ``` + +4. **进行开发** + + - 保持代码风格一致，遵循 ESLint + Prettier 规范 + - 编写有意义的提交信息 + - 确保代码通过 lint 检查 + +5. **提交更改** + + ```bash + git add . + git commit -m 'feat: 添加新功能描述' + # 或 + git commit -m 'fix: 修复问题描述' + ``` + + **提交信息规范**： + + | 类型 | 说明 | + |------|------| + | feat | 新功能 | + | fix | Bug 修复 | + | docs | 文档更新 | + | style | 代码格式调整 | + | refactor | 代码重构 | + | perf | 性能优化 | + | test | 测试相关 | + | chore | 构建/工具链变动 | + +6. **推送到远程** + + ```bash + git push origin feature/your-feature-name + ``` + +7. **创建 Pull Request** + + - 描述您的改动内容和目的 + - 关联相关 Issue（如果有） + - 等待代码审查 + +### 开发规范 + +- 使用 ES6+ 语法 +- 前端遵循 React Hooks 规范 +- 后端使用 async/await 处理异步 +- 保持函数简洁，单一职责 +- 适当添加注释说明复杂逻辑 + +### 代码审查标准 + +- ✅ 代码功能正确性 +- ✅ 符合项目编码规范 +- ✅ 必要的测试覆盖 +- ✅ 文档更新（如有必要） +- ✅ 性能影响评估 + +--- + +## 许可证 + +本项目基于 **MIT 许可证** 开源。 + +``` +MIT License + +Copyright (c) 2024 IDC Device Management System + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. +``` + +--- + +## 致谢 + +感谢以下开源项目： + +- [React](https://react.dev/) - 前端框架 +- [Ant Design](https://ant.design/) - UI 组件库 +- [Three.js](https://threejs.org/) - 3D 渲染引擎 +- [Express](https://expressjs.com/) - Node.js Web 框架 +- [Sequelize](https://sequelize.org/) - Node.js ORM + +--- + +## 联系与支持 + +- 问题反馈：https://gitee.com/zhang96110/idc_assest/issues +- 功能建议：提交 Issue 并标注 `feature-request` + +--- + +**⭐ 如果这个项目对您有帮助，请给我们一个 Star！**