720 lines
23 KiB
Markdown
720 lines
23 KiB
Markdown
# IDC 设备资产管理系统
|
||
|
||
**维护团队**：IDC 设备资产管理开源社区
|
||
**版本**：2.1.1 | **更新**：2026-06-22
|
||
|
||
面向数据中心（IDC）运维与资产管理场景，提供机房、机柜、设备全生命周期管理，支持 3D 可视化、工单流转、耗材库存、资产盘点与 RBAC 权限控制。
|
||
|
||
| 层级 | 技术选型 |
|
||
|------|----------|
|
||
| 后端 | Node.js 20 + Express + Sequelize |
|
||
| 前端 | React 18 + Vite + Ant Design + Three.js |
|
||
| 数据库 | SQLite（开发默认）/ MySQL 8.0（生产推荐） |
|
||
| 部署 | Docker Compose / PM2 + Nginx / 本地开发 |
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
- [快速开始](#快速开始)
|
||
- [操作手册](#操作手册)
|
||
- [1. 系统概述](#1-系统概述)
|
||
- [2. 环境要求](#2-环境要求)
|
||
- [3. 安装与启动](#3-安装与启动)
|
||
- [4. 登录与账号](#4-登录与账号)
|
||
- [5. 界面与模块导航](#5-界面与模块导航)
|
||
- [6. 业务模块操作指南](#6-业务模块操作指南)
|
||
- [7. 典型业务流程](#7-典型业务流程)
|
||
- [8. 系统管理](#8-系统管理)
|
||
- [9. 日常运维](#9-日常运维)
|
||
- [10. 常见问题与排查](#10-常见问题与排查)
|
||
- [11. 附录](#11-附录)
|
||
- [贡献指南](#贡献指南)
|
||
- [许可证](#许可证)
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
### 方式一：Docker 全栈部署（推荐）
|
||
|
||
适用于已安装 Docker 的服务器，一键启动前端、后端与 MySQL。
|
||
|
||
```bash
|
||
# 克隆项目
|
||
git clone https://github.com/gituib/idc_assest.git
|
||
cd idc_assest
|
||
|
||
# 配置 JWT 密钥（生产环境必填）
|
||
# PowerShell 生成示例：
|
||
# node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"
|
||
set JWT_SECRET=你的强随机密钥
|
||
|
||
# 启动全部服务（构建镜像）
|
||
docker compose -f docker-compose.full.yml up -d --build
|
||
|
||
# 写入示例数据（可选，含演示账号与机房/设备/工单）
|
||
docker exec idc_assest-backend node scripts/seed-example-data.js
|
||
```
|
||
|
||
| 服务 | 默认地址 | 说明 |
|
||
|------|----------|------|
|
||
| 前端 | http://localhost:12000 | Nginx 托管 SPA，代理 `/api` |
|
||
| 后端 API | http://localhost:12001 | 容器内端口 8000 |
|
||
| API 文档 | http://localhost:12000/api-docs | Swagger 交互文档 |
|
||
| 健康检查 | http://localhost:12001/health | 后端存活探测 |
|
||
| MySQL | localhost:12006 | 库名 `idc_management` |
|
||
|
||
| 角色 | 用户名 | 密码 | 获取方式 |
|
||
|------|--------|------|----------|
|
||
| 管理员（演示） | `admin` | `admin123` | 执行 `seed-example-data.js` 后可用 |
|
||
| 管理员（全新） | 自行注册 | 自行设定 | 首个注册账号自动成为管理员 |
|
||
|
||
> 生产环境请立即修改默认密码与 MySQL 根密码（`MYSQL_ROOT_PASSWORD`）。
|
||
|
||
**Docker 预构建镜像**（`docker-compose.prod.yml`，从仓库拉取，无需本地 build）：
|
||
|
||
```
|
||
ghcr.io/gituib/idc-backend:latest
|
||
ghcr.io/gituib/idc-frontend:latest
|
||
```
|
||
|
||
### 方式二：本地开发
|
||
|
||
```bash
|
||
git clone https://github.com/gituib/idc_assest.git
|
||
cd idc_assest
|
||
npm run install:all
|
||
cp backend/.env.example backend/.env
|
||
cd backend && node scripts/init-database.js && cd ..
|
||
npm start
|
||
```
|
||
|
||
| 服务 | 地址 |
|
||
|------|------|
|
||
| 前端 | http://localhost:3000 |
|
||
| 后端 API | http://localhost:8000 |
|
||
| API 文档 | http://localhost:8000/api-docs |
|
||
|
||
### 项目结构
|
||
|
||
```
|
||
idc_assest/
|
||
├── frontend/ # React 前端（Vite）
|
||
├── backend/ # Express 后端（models / routes / scripts）
|
||
├── deploy/ # PM2、Nginx 部署配置
|
||
├── docs/ # 补充文档与截图目录
|
||
├── docker-compose.full.yml # 全栈 Docker（推荐）
|
||
├── docker-compose.prod.yml # 预构建镜像生产部署
|
||
├── install.js # 一键安装脚本
|
||
└── README.md # 本操作手册（权威文档）
|
||
```
|
||
|
||
---
|
||
|
||
## 操作手册
|
||
|
||
### 1. 系统概述
|
||
|
||
#### 1.1 产品简介
|
||
|
||
IDC 设备资产管理系统（界面品牌名：**云睿资产**）用于统一管理多机房、多机柜下的服务器、网络、存储等设备，覆盖设备上架、端口接线、故障工单、耗材出入库、资产盘点、数据备份与操作审计等场景，并通过 3D 机柜视图与机房平面图辅助空间规划。
|
||
|
||
#### 1.2 核心能力
|
||
|
||
| 模块 | 能力说明 |
|
||
|------|----------|
|
||
| 数据看板 | 设备/机柜/功率统计与趋势图表 |
|
||
| 机房管理 | 多机房、平面图编辑、机柜网格布局 |
|
||
| 机柜管理 | 机柜 CRUD、批量导入导出、3D 可视化 |
|
||
| 设备管理 | 全生命周期、自定义字段、批量导入导出 |
|
||
| 端口与接线 | 设备端口、网卡绑定、线缆连接追踪 |
|
||
| 工单管理 | 故障报修、分类、统计、全流程状态 |
|
||
| 耗材管理 | 库存、SN 追踪、分类、操作日志归档 |
|
||
| 资产盘点 | 盘点计划、任务执行、盘盈设备审核 |
|
||
| 空闲设备 | 设备转入空闲、重新激活上架 |
|
||
| 系统管理 | 用户/角色 RBAC、系统设置、备份、操作日志 |
|
||
| API 文档 | Swagger 在线调试 |
|
||
|
||
#### 1.3 技术架构
|
||
|
||
```
|
||
┌─────────────┐ /api、/uploads ┌─────────────┐
|
||
│ 浏览器 │ ◄──────────────────────► │ Nginx/前端 │
|
||
│ React SPA │ │ (端口 80) │
|
||
└─────────────┘ └──────┬──────┘
|
||
│ 反向代理
|
||
┌──────▼──────┐
|
||
│ Express API │
|
||
│ (端口 8000) │
|
||
└──────┬──────┘
|
||
│
|
||
┌─────────────────┼─────────────────┐
|
||
│ │ │
|
||
┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐
|
||
│ MySQL 8 │ │ SQLite │ │ uploads/ │
|
||
│ (生产推荐) │ │ (开发默认) │ │ logs/ 备份 │
|
||
└─────────────┘ └─────────────┘ └─────────────┘
|
||
```
|
||
|
||
|
||
|
||
---
|
||
|
||
### 2. 环境要求
|
||
|
||
| 项 | 要求 |
|
||
|----|------|
|
||
| 操作系统 | Windows 10+、macOS 12+、Linux |
|
||
| Node.js | ≥ 20.10.0（见 `.nvmrc`） |
|
||
| npm | ≥ 6.0.0（推荐 10.x） |
|
||
| Docker | 20.10+（Docker 部署时） |
|
||
| Docker Compose | v2+ |
|
||
| 内存 | 最低 4 GB，推荐 8 GB+ |
|
||
| 磁盘 | 最低 2 GB，推荐 10 GB+ |
|
||
|
||
**生产环境额外要求**：
|
||
|
||
| 项 | 要求 |
|
||
|----|------|
|
||
| 数据库 | MySQL 8.0+ |
|
||
| Web 服务器 | Nginx 1.18+（非 Docker 部署时） |
|
||
| 进程管理 | PM2 5.x+（非 Docker 部署时） |
|
||
| JWT 密钥 | 生产环境必须在 `.env` 或环境变量中设置 `JWT_SECRET` |
|
||
|
||
---
|
||
|
||
### 3. 安装与启动
|
||
|
||
#### 3.1 Docker 全栈（`docker-compose.full.yml`）
|
||
|
||
三个容器：MySQL、Backend、Frontend（Nginx + 静态资源）。
|
||
|
||
```bash
|
||
# 启动
|
||
docker compose -f docker-compose.full.yml up -d --build
|
||
|
||
# 查看状态
|
||
docker compose -f docker-compose.full.yml ps
|
||
|
||
# 查看后端日志
|
||
docker logs -f idc_assest-backend
|
||
|
||
# 停止
|
||
docker compose -f docker-compose.full.yml down
|
||
```
|
||
|
||
**常用环境变量**（可在项目根目录 `.env` 或命令行覆盖）：
|
||
|
||
| 变量 | 默认值 | 说明 |
|
||
|------|--------|------|
|
||
| `FRONTEND_PORT` | `12000` | 前端映射端口 |
|
||
| `BACKEND_PORT` | `12001` | 后端映射端口 |
|
||
| `MYSQL_PORT` | `12006` | MySQL 映射端口 |
|
||
| `MYSQL_DATABASE` | `idc_management` | 数据库名 |
|
||
| `MYSQL_ROOT_PASSWORD` | `xinmi_password` | MySQL root 密码 |
|
||
| `JWT_SECRET` | （无默认） | **生产必填** |
|
||
|
||
数据持久化：MySQL 数据卷 `idc_assest-mysql-data`；上传文件映射 `backend/uploads`；日志映射 `backend/logs`；备份映射 `backend/backups`。
|
||
|
||
#### 3.2 Docker 预构建镜像（`docker-compose.prod.yml`）
|
||
|
||
适用于 CI 已构建好的镜像，无需本地编译：
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
# 编辑 .env 设置 BACKEND_IMAGE、FRONTEND_IMAGE、backend/.env 数据库等
|
||
docker compose -f docker-compose.prod.yml up -d
|
||
```
|
||
|
||
前端默认映射 **80** 端口；后端通过 Nginx 内部网络访问，不直接暴露。
|
||
|
||
#### 3.3 Linux 一键安装
|
||
|
||
```bash
|
||
git clone https://gitee.com/zhang96110/idc_assest.git
|
||
cd idc_assest
|
||
./install.sh
|
||
# 或远程一键：curl -fsSL https://gitee.com/zhang96110/idc_assest/raw/main/install.sh | bash
|
||
```
|
||
|
||
`install.sh` 自动检测发行版、安装 Node.js 20.x，并调用 `install.js` 完成依赖安装、数据库初始化与 Nginx/PM2 配置。
|
||
|
||
#### 3.4 Windows / 手动安装
|
||
|
||
```powershell
|
||
git clone https://gitee.com/zhang96110/idc_assest.git
|
||
cd idc_assest
|
||
node install.js
|
||
# 或：npm run deploy
|
||
```
|
||
|
||
手动步骤：
|
||
|
||
```bash
|
||
npm run install:all
|
||
cp backend/.env.example backend/.env
|
||
# 编辑 backend/.env：JWT_SECRET、DB_TYPE 等
|
||
cd backend && node scripts/init-database.js && cd ..
|
||
npm start
|
||
```
|
||
|
||
#### 3.5 安装脚本常用参数
|
||
|
||
```bash
|
||
# 非交互安装，使用 MySQL
|
||
node install.js -y --db=mysql
|
||
|
||
# 指定后端端口
|
||
node install.js -y --port=8000
|
||
|
||
# 跳过前端构建或 Nginx 配置
|
||
node install.js -y --skip-build --skip-nginx
|
||
```
|
||
|
||
更新与卸载：
|
||
|
||
```bash
|
||
node update.js # 拉取代码、备份、迁移、重启
|
||
node uninstall.js # 交互式卸载
|
||
```
|
||
|
||
---
|
||
|
||
### 4. 登录与账号
|
||
|
||
#### 4.1 登录方式
|
||
|
||
1. 浏览器访问前端地址（Docker 默认 `http://localhost:12000`，本地开发 `http://localhost:3000`）。
|
||
2. 使用账号密码登录；未登录时自动跳转 `/login`。
|
||
3. 登录后 JWT Token 保存在浏览器，空闲超时后自动退出（时长可在系统设置中配置）。
|
||
|
||
|
||
|
||
#### 4.2 账号与角色
|
||
|
||
| 场景 | 用户名 | 密码 | 说明 |
|
||
|------|--------|------|------|
|
||
| 示例数据 | `admin` | `admin123` | 执行种子脚本后可用 |
|
||
| 全新部署 | 自行注册 | 自行设定 | **第一个**注册账号自动获得管理员角色 |
|
||
| 后续用户 | 自行注册 | 自行设定 | 默认待管理员审核（`pending` 状态） |
|
||
|
||
**预置角色**（种子脚本或「用户管理」中初始化）：
|
||
|
||
| 角色编码 | 角色名 | 权限范围 |
|
||
|----------|--------|----------|
|
||
| `admin` | 管理员 | 全部权限（`*`） |
|
||
| `operator` | 运维人员 | 设备/机柜/机房/耗材读写 |
|
||
| `viewer` | 只读用户 | 设备/机柜/机房/耗材只读 |
|
||
|
||
> 生产环境部署后请立即修改 `admin123`，并为用户分配最小必要角色。
|
||
|
||
#### 4.3 写入示例数据
|
||
|
||
```bash
|
||
# Docker 环境
|
||
docker exec idc_assest-backend node scripts/seed-example-data.js
|
||
|
||
# 本地开发（backend 目录，需配置数据库连接）
|
||
cd backend && npm run seed
|
||
```
|
||
|
||
示例数据包含：2 个机房、4 个机柜、7 台设备、3 个业务、1 个库房、3 种耗材、3 条工单。脚本**幂等**，重复执行不会重复插入；强制重写可设 `SEED_FORCE=1`。
|
||
|
||
---
|
||
|
||
### 5. 界面与模块导航
|
||
|
||
登录后左侧为功能菜单，顶部右侧显示当前用户与退出按钮。
|
||
|
||
| 一级菜单 | 子页面 | 路由 |
|
||
|----------|--------|------|
|
||
| 仪表盘 | 数据看板 | `/` |
|
||
| 机房管理 | 机房管理 | `/rooms` |
|
||
| | 机柜管理 | `/racks` |
|
||
| | 3D 机柜可视化 | `/visualization-3d` |
|
||
| | 机房平面图 | `/floor-plan` |
|
||
| 资产管理 | 设备管理 | `/devices` |
|
||
| | 空闲设备 | `/idle-devices` |
|
||
| | 字段管理 | `/fields` |
|
||
| | 端口管理 | `/ports` |
|
||
| | 接线管理 | `/cables` |
|
||
| 耗材管理 | 耗材统计 | `/consumables-stats` |
|
||
| | 耗材列表 | `/consumables` |
|
||
| | 分类管理 | `/consumables-categories` |
|
||
| | 操作日志 | `/consumables-logs` |
|
||
| 工单管理 | 工单列表 | `/tickets` |
|
||
| | 故障分类 | `/ticket-categories` |
|
||
| | 统计报表 | `/ticket-statistics` |
|
||
| 资产盘点 | 盘点计划 | `/inventory` |
|
||
| | 盘盈设备 | `/pending-devices` |
|
||
| 系统管理 | 用户管理 | `/users` |
|
||
| | 系统设置 | `/settings` |
|
||
| | 数据备份 | `/backup` |
|
||
| | 操作日志 | `/operation-logs` |
|
||
| | 关于系统 | `/about` |
|
||
|
||
|
||
|
||
---
|
||
|
||
### 6. 业务模块操作指南
|
||
|
||
#### 6.1 数据看板
|
||
|
||
**路径**：`/`
|
||
|
||
**功能概述**：汇总机房、机柜、设备数量与状态分布，展示功率与趋势图表。
|
||
|
||
| 元素 | 说明 |
|
||
|------|------|
|
||
| 统计卡片 | 设备总数、在线/离线、机柜利用率等 |
|
||
| 图表 | 按类型、状态、机房的分布与趋势 |
|
||
| 刷新 | 进入页面自动加载，可手动刷新 |
|
||
|
||
|
||
|
||
#### 6.2 机房与机柜管理
|
||
|
||
**路径**：`/rooms`、`/racks`
|
||
|
||
**功能概述**：维护机房基础信息、机柜规格与在机房中的行列位置；支持批量导入导出。
|
||
|
||
| 元素 | 说明 |
|
||
|------|------|
|
||
| 机房 | 名称、位置、面积、容量、网格行列 |
|
||
| 机柜 | 名称、U 高、最大功率、所属机房、行列坐标 |
|
||
| 平面图 | `/floor-plan` 拖拽编辑机柜布局 |
|
||
|
||
|
||
|
||
#### 6.3 3D 机柜可视化
|
||
|
||
**路径**：`/visualization-3d`
|
||
|
||
**功能概述**：Three.js 三维展示机柜内设备 U 位占用，支持旋转、缩放与设备详情查看。需浏览器支持 WebGL。
|
||
|
||
|
||
|
||
#### 6.4 设备管理
|
||
|
||
**路径**：`/devices`
|
||
|
||
**功能概述**：设备全生命周期管理，支持上架到机柜或入库到库房，自定义扩展字段。
|
||
|
||
| 元素 | 说明 |
|
||
|------|------|
|
||
| 基本信息 | 名称、型号、序列号、类型、IP、功耗 |
|
||
| 位置 | 机柜 + U 位，或库房 |
|
||
| 状态 | online / offline / maintenance 等 |
|
||
| 导入导出 | Excel/CSV 批量操作 |
|
||
| 业务关联 | 可绑定一个或多个业务系统 |
|
||
|
||
|
||
|
||
#### 6.5 端口与接线管理
|
||
|
||
**路径**：`/ports`、`/cables`
|
||
|
||
**功能概述**：配置设备物理/逻辑端口，记录线缆两端连接关系，便于故障追踪与拓扑分析。
|
||
|
||
| 元素 | 说明 |
|
||
|------|------|
|
||
| 端口 | 端口号、类型、速率、绑定网卡 |
|
||
| 线缆 | 源/目标设备与端口、线缆类型与长度 |
|
||
|
||
#### 6.6 工单管理
|
||
|
||
**路径**：`/tickets`
|
||
|
||
**功能概述**：故障报修与维护工单从创建到关闭的全流程管理。
|
||
|
||
| 元素 | 说明 |
|
||
|------|------|
|
||
| 状态 | pending → in_progress → completed / closed |
|
||
| 优先级 | critical / high / medium / low |
|
||
| 故障分类 | 系统/硬件/网络等（可在故障分类页维护） |
|
||
| 关联设备 | 可选绑定具体设备 |
|
||
|
||
|
||
|
||
#### 6.7 耗材管理
|
||
|
||
**路径**：`/consumables`、`/consumables-stats`
|
||
|
||
**功能概述**：耗材分类、库存数量、SN 序列号追踪、出入库日志与归档。
|
||
|
||
| 元素 | 说明 |
|
||
|------|------|
|
||
| 库存预警 | 当前库存低于最小库存时提示 |
|
||
| 操作日志 | 记录每次入库/出库/调整 |
|
||
| 分类 | 线缆、光模块、硬盘等自定义分类 |
|
||
|
||
#### 6.8 资产盘点
|
||
|
||
**路径**：`/inventory`、`/pending-devices`
|
||
|
||
**功能概述**：创建全面/局部/抽样盘点计划，执行盘点任务，审核盘盈设备。
|
||
|
||
| 元素 | 说明 |
|
||
|------|------|
|
||
| 盘点计划 | 设定范围、负责人、截止时间 |
|
||
| 任务执行 | `/inventory/execution` 逐项核对 |
|
||
| 盘盈设备 | 待审核通过后纳入资产 |
|
||
|
||
#### 6.9 空闲设备
|
||
|
||
**路径**：`/idle-devices`
|
||
|
||
**功能概述**：将机柜中不再使用的设备标记为空闲并释放 U 位，或从空闲状态重新激活上架。
|
||
|
||
---
|
||
|
||
### 7. 典型业务流程
|
||
|
||
#### 7.1 新设备上架
|
||
|
||
```
|
||
采购入库（库房） → 设备管理创建/导入 → 分配到机柜 U 位 → 配置端口与线缆 → 绑定业务
|
||
```
|
||
|
||
1. 在「设备管理」中新增设备，`sourceType` 为库房或直接在机柜创建。
|
||
2. 选择目标机柜与起始 U 位，系统自动校验 U 位冲突。
|
||
3. 在「端口管理」「接线管理」中完善网络连接。
|
||
4. 在设备详情中关联业务系统。
|
||
|
||
#### 7.2 故障工单处理
|
||
|
||
```
|
||
发现故障 → 创建工单（选设备/分类/优先级） → 指派处理人 → 处理并填写方案 → 完成/关闭
|
||
```
|
||
|
||
1. 「工单列表」点击新建，填写标题、故障分类与描述。
|
||
2. 管理员或运维将状态改为「处理中」并指派处理人。
|
||
3. 处理完成后填写解决方案，状态改为「已完成」。
|
||
|
||
#### 7.3 资产盘点
|
||
|
||
```
|
||
创建盘点计划 → 生成盘点任务 → 现场逐项核对 → 提交结果 → 审核盘盈设备
|
||
```
|
||
|
||
1. 「盘点计划」新建计划，选择机房/机柜范围。
|
||
2. 执行人进入任务执行页，扫描或勾选设备实际状态。
|
||
3. 发现未登记设备时进入「盘盈设备」等待审核入库。
|
||
|
||
---
|
||
|
||
### 8. 系统管理
|
||
|
||
#### 8.1 用户与角色
|
||
|
||
**路径**：`/users`
|
||
|
||
- 审核 `pending` 状态的新注册用户。
|
||
- 为用户分配 `admin` / `operator` / `viewer` 角色。
|
||
- 支持锁定、重置密码等操作。
|
||
|
||
#### 8.2 系统设置
|
||
|
||
**路径**：`/settings`
|
||
|
||
| 分类 | 可配置项 |
|
||
|------|----------|
|
||
| 全局 | 站点名称、Logo、时区、会话超时、维护模式 |
|
||
| 外观 | 主题色、紧凑模式、侧边栏折叠 |
|
||
| 关于 | 版本号、公司信息、联系方式 |
|
||
|
||
维护模式开启后，仅管理员可登录。
|
||
|
||
#### 8.3 数据备份
|
||
|
||
**路径**：`/backup`
|
||
|
||
- 支持手动创建本地备份。
|
||
- 可配置自动定时备份（`/auto-backup-settings`）与远程备份（FTP/SFTP/WebDAV 等，`/remote-backup-settings`）。
|
||
- 备份文件存储在 `backend/backups/`（Docker 下已映射到宿主机）。
|
||
|
||
|
||
|
||
命令行备份：
|
||
|
||
```bash
|
||
cd backend && node scripts/backup.js
|
||
cd backend && node scripts/restore.js <backup-file>
|
||
```
|
||
|
||
#### 8.4 操作日志
|
||
|
||
**路径**：`/operation-logs`
|
||
|
||
记录用户关键操作（增删改、登录等），支持按模块、操作人、时间筛选，用于安全审计。
|
||
|
||
---
|
||
|
||
### 9. 日常运维
|
||
|
||
#### 9.1 健康检查
|
||
|
||
```bash
|
||
# 后端健康（Docker 映射端口示例）
|
||
curl http://localhost:12001/health
|
||
|
||
# 通过前端 Nginx 代理
|
||
curl http://localhost:12000/health
|
||
```
|
||
|
||
返回 `status: ok` 表示服务正常；`warning` / `error` 时查看 `backend/logs/`。
|
||
|
||
#### 9.2 日志查看
|
||
|
||
| 环境 | 命令 |
|
||
|------|------|
|
||
| Docker | `docker logs -f idc_assest-backend` |
|
||
| PM2 | `pm2 logs idc-backend` |
|
||
| 文件 | `tail -f backend/logs/*.log` |
|
||
|
||
日志级别通过 `backend/.env` 中 `LOG_LEVEL` 控制（`error` / `warn` / `info` / `debug`）。
|
||
|
||
#### 9.3 服务重启
|
||
|
||
```bash
|
||
# Docker
|
||
docker compose -f docker-compose.full.yml restart backend frontend
|
||
|
||
# PM2
|
||
pm2 restart idc-backend
|
||
sudo nginx -s reload
|
||
```
|
||
|
||
#### 9.4 版本更新
|
||
|
||
```bash
|
||
node update.js
|
||
# 支持 --skip-git --skip-backup --skip-build 等跳过选项
|
||
```
|
||
|
||
#### 9.5 数据库维护
|
||
|
||
```bash
|
||
# 初始化表结构（首次部署）
|
||
cd backend && node scripts/init-database.js
|
||
|
||
# 写入示例数据
|
||
cd backend && npm run seed
|
||
```
|
||
|
||
---
|
||
|
||
### 10. 常见问题与排查
|
||
|
||
#### 10.1 访问与登录
|
||
|
||
| 现象 | 可能原因 | 处理 |
|
||
|------|----------|------|
|
||
| 前端打不开 | 端口被占用或服务未启动 | `docker compose ps` 或检查 12000/3000 端口 |
|
||
| 登录 401 | 账号密码错误或 Token 过期 | 重新登录；检查 `JWT_SECRET` 是否变更 |
|
||
| 登录后立刻退出 | 空闲超时 | 系统设置中调整 `idle_timeout` |
|
||
| 维护模式无法登录 | 非管理员账号 | 使用管理员登录，或在数据库关闭 `maintenance_mode` |
|
||
|
||
#### 10.2 Docker 部署
|
||
|
||
| 现象 | 可能原因 | 处理 |
|
||
|------|----------|------|
|
||
| backend 启动失败 | MySQL 未就绪或 `JWT_SECRET` 未设 | 等待 MySQL；设置 `JWT_SECRET` 后重启 |
|
||
| 502 / API 无响应 | 后端容器异常 | `docker logs idc_assest-backend` |
|
||
| 中文乱码 | MySQL 字符集 | 确保库为 `utf8mb4` |
|
||
|
||
#### 10.3 本地开发
|
||
|
||
| 现象 | 可能原因 | 处理 |
|
||
|------|----------|------|
|
||
| 端口 8000/3000 冲突 | 其他进程占用 | 修改 `backend/.env` 的 `PORT` 或 `FRONTEND_PORT` |
|
||
| 前端 API 失败 | 代理未生效 | 确认 Vite 将 `/api` 代理到 `http://localhost:8000` |
|
||
| 数据库连接失败 | MySQL 未启动或密码错误 | 检查 `DB_TYPE` 与 MySQL 连接参数 |
|
||
|
||
#### 10.4 业务功能
|
||
|
||
| 现象 | 可能原因 | 处理 |
|
||
|------|----------|------|
|
||
| U 位冲突 | 同一机柜 U 位已被占用 | 调整设备起始 U 位或高度 |
|
||
| 3D 页面空白 | 浏览器不支持 WebGL | 更换浏览器或更新显卡驱动 |
|
||
| 上传失败 | 文件超过大小限制 | 默认最大 30 MB（`MAX_FILE_SIZE_MB`） |
|
||
| 无示例数据 | 未执行种子脚本 | `docker exec idc_assest-backend node scripts/seed-example-data.js` |
|
||
|
||
---
|
||
|
||
### 11. 附录
|
||
|
||
#### 11.1 环境变量速查（后端 `backend/.env`）
|
||
|
||
| 变量 | 默认值 | 说明 |
|
||
|------|--------|------|
|
||
| `PORT` | `8000` | 后端监听端口 |
|
||
| `NODE_ENV` | `development` | 运行环境 |
|
||
| `DB_TYPE` | `sqlite` | `sqlite` 或 `mysql` |
|
||
| `DB_PATH` | `./idc_management.db` | SQLite 文件路径 |
|
||
| `MYSQL_HOST` | `localhost` | MySQL 主机（Docker 内为 `mysql`） |
|
||
| `MYSQL_PORT` | `3306` | MySQL 端口 |
|
||
| `MYSQL_DATABASE` | `idc_management` | 数据库名 |
|
||
| `MYSQL_USERNAME` | `root` | 数据库用户 |
|
||
| `MYSQL_PASSWORD` | （空） | 数据库密码 |
|
||
| `JWT_SECRET` | 开发自动生成 | **生产必填** |
|
||
| `TOKEN_EXPIRY` | `24h` | Token 有效期 |
|
||
| `LOG_LEVEL` | `debug` | 日志级别 |
|
||
| `MAX_FILE_SIZE_MB` | `30` | 上传大小上限 |
|
||
| `FRONTEND_PORT` | `3000` | 本地前端端口提示 |
|
||
|
||
完整列表见 `backend/.env.example`。
|
||
|
||
#### 11.2 服务端口对照
|
||
|
||
| 场景 | 前端 | 后端 | MySQL |
|
||
|------|------|------|-------|
|
||
| Docker 全栈（`docker-compose.full.yml`） | 12000 | 12001 | 12006 |
|
||
| Docker 生产镜像（`docker-compose.prod.yml`） | 80 | 内部网络 | 可选 |
|
||
| 本地开发 | 3000 | 8000 | 3306 |
|
||
|
||
####
|
||
|
||
#### 11.3 相关链接
|
||
|
||
| 资源 | 地址 |
|
||
|------|------|
|
||
| API 详细文档 | [docs/api/README.md](docs/api/README.md) |
|
||
| Docker 部署补充 | [docs/docker-deployment-guide.md](docs/docker-deployment-guide.md) |
|
||
| 用户指南（历史） | [docs/USER_GUIDE.md](docs/USER_GUIDE.md) |
|
||
|
||
---
|
||
|
||
## 贡献指南
|
||
|
||
欢迎提交 Issue 或 Pull Request。
|
||
|
||
```bash
|
||
git checkout -b feature/your-feature
|
||
git commit -m 'feat: 添加新功能'
|
||
git push origin feature/your-feature
|
||
```
|
||
|
||
| 提交类型 | 说明 |
|
||
|----------|------|
|
||
| `feat` | 新功能 |
|
||
| `fix` | Bug 修复 |
|
||
| `docs` | 文档更新 |
|
||
| `refactor` | 重构 |
|
||
| `chore` | 构建/工具 |
|
||
|
||
开发规范：后端 CommonJS + Sequelize；前端 ESM + React Hooks；提交前运行 `npm run lint`（backend / frontend）。
|
||
|
||
---
|
||
|
||
## 许可证
|
||
|
||
本项目基于 [MIT 许可证](LICENSE) 开源。
|
||
|
||
---
|
||
|
||
**IDC 设备资产管理开源社区**
|
||
文档版本：2.1.1 | 2026-06-22
|