ghcr.io/gituib/idc-backend:latest
IDC设备资产管理系统
现代化数据中心(IDC)设备管理系统,提供机房、机柜、设备的全生命周期管理,具备 3D 可视化展示功能。
GitHub:
📖 查看完整文档教程 →
包含安装部署、配置说明、使用指南等全部教程
目录
- IDC设备资产管理系统
- 快速开始
- Linux 一键部署
- Windows 部署
- 环境要求
- 脚本命令参考
- install.js - 安装脚本
- update.js - 更新脚本
- uninstall.js - 卸载脚本
- 首次访问与管理员账号
- 生产环境安全配置
- 系统维护
- 服务管理
- 日志查看
- 数据备份
- 事故诊断
- 常见问题
- 项目结构
- API 文档
- 贡献指南
- 支持项目
- 许可证
快速开始
Docker 部署(推荐)
适用于新服务器上快速部署,无需安装 Node.js 等运行时环境,只需 Docker 即可。
📖 详细教程请查看文档站:https://gituib.github.io/idc_assest-docs/deploy/docker-deploy.html
Linux 一键部署
# 克隆项目(GitHub 主仓库)
git clone https://github.com/gituib/idc_assest.git
cd idc_assest
# 运行安装脚本(自动安装 Node.js)
chmod +x install.sh
./install.sh
install.sh需要与仓库内的install.js配合运行,必须先克隆仓库。请勿使用curl ... | bash管道方式——管道执行时脚本无法定位自身所在目录,会因找不到install.js而退出。
install.sh 自动完成:
- 自动检测 Linux 发行版并安装 Node.js 20.x
- Ubuntu / Debian
- CentOS / RHEL / Fedora / Rocky Linux / AlmaLinux
- Arch / Manjaro
- 其他发行版回退至 nvm
- 自动安装系统依赖(git、curl)
- 调用 install.js 完成后续安装
Windows 部署
# 克隆项目
git clone https://github.com/gituib/idc_assest.git
cd idc_assest
# 运行安装脚本(需要先安装 Node.js)
node install.js
# 或使用 npm
npm run deploy
环境要求
| 项目 | 最低要求 | 推荐配置 |
|---|---|---|
| Node.js | ≥16.0.0 | 20.x LTS |
| 内存 | 4GB | 8GB+ |
| 磁盘 | 2GB | 10GB+ |
| 数据库 | SQLite(内置,默认) | MySQL 8.0+ |
npm、Nginx、PM2 无需提前准备:
install.sh/install.js会自动检测并安装。Node.js 版本低于 16 时安装脚本会中止并提示升级。
操作系统:Linux 为完整支持(自动安装 Node.js、自动配置 Nginx)。Windows 可正常使用,但 Nginx 需手动放置配置文件。macOS 建议仅用于开发调试。
脚本命令参考
install.js - 安装脚本
# 交互式安装
node install.js
# 非交互式安装
node install.js -y
# 指定数据库类型
node install.js -y --db=mysql # 使用 MySQL
node install.js -y --db=sqlite # 使用 SQLite(默认)
# 指定端口
node install.js -y --port=8000 # 后端端口
# 跳过前端构建
node install.js -y --skip-build
# 跳过 Nginx 配置
node install.js -y --skip-nginx
# 仅重新生成并同步 Nginx 配置(端口跟随 backend/.env)
node install.js --regen-nginx
# 查看帮助
node install.js --help
update.js - 更新脚本
# 交互式更新
node update.js
# 模拟运行(不执行实际操作)
node update.js --dry-run
# 跳过某些步骤
node update.js --skip-git # 跳过 Git 拉取
node update.js --skip-backup # 跳过数据库备份
node update.js --skip-migrate # 跳过数据库迁移
node update.js --skip-build # 跳过前端构建
node update.js --skip-deps # 跳过依赖安装
node update.js --skip-restart # 跳过服务重启
# 强制执行(忽略锁文件)
node update.js --force
# 查看帮助
node update.js --help
智能检测功能:
- 依赖安装智能跳过(检测 package.json 变化)
- 前端构建智能跳过(检测源码变化)
- 数据库自动备份(支持回滚)
- 健康检查验证
- 日志持久化保存到
logs/update_*.log - 锁机制防止重复运行
uninstall.js - 卸载脚本
# 交互式卸载
node uninstall.js
# 强制卸载(无需确认)
node uninstall.js --force
# 卸载前自动备份数据库
node uninstall.js --backup
# 跳过某些步骤
node uninstall.js --skip-db # 跳过数据库删除
node uninstall.js --skip-deps # 跳过依赖删除
node uninstall.js --skip-uploads # 跳过上传文件删除
# 预览模式(不实际执行)
node uninstall.js --dry-run
# 查看帮助
node uninstall.js --help
首次访问与管理员账号
系统不内置默认管理员账号,管理员通过「首个注册用户」机制产生。首次部署完成后:
- 打开前端页面,进入注册页创建第一个账号。
- 该账号在满足下方规则时自动获得管理员权限。
首管理员分配规则
.env 中 BOOTSTRAP_ADMIN_USERNAME | 首个注册用户的行为 |
|---|---|
| 未配置(默认) | 首用户直接成为管理员,后端启动时输出风险警告日志 |
| 已配置 | 仅当注册用户名与该值完全一致时分配管理员;其他用户名注册后状态为 pending(待审核),无任何权限 |
[!WARNING] 生产环境强烈建议配置此项。从服务启动到管理员注册完成之间存在一个窗口期,若未配置且端口已对外可达,任何先访问到注册页的人都会直接拿到超级管理员权限。
配置方式(backend/.env):
# 预设首管理员用户名,仅该用户名的首次注册可获得管理员权限
BOOTSTRAP_ADMIN_USERNAME=your_admin_name
修改后需重启后端生效(pm2 restart idc-backend)。该配置只在数据库无任何用户时起作用,一旦已有用户则不再参与判定。
账号找回与补充创建
场景一:空库阶段离线创建初始管理员(不想通过注册页抢注,直接指定账号):
cd backend
# 推荐:口令通过环境变量传入,不进入 shell 历史
ADMIN_PASSWORD='YourStrongPassword' node scripts/create-admin.js --username admin
[!NOTE]
--password参数同样可用,但口令会留在 shell 历史中,不推荐。
行为说明:该脚本是幂等的——用户已存在且已是管理员时直接退出;用户存在但非管理员时补齐 admin 角色,但不修改已有口令。因此它适用于空库初始化与补授角色,不能用于重置已遗忘的密码。
场景二:管理员口令遗失——走系统内置的「忘记密码」流程(POST /api/auth/forgot-password/send-code),通过***验证码重置口令,重置成功后会自动激活被锁定的账户。
[!IMPORTANT] 该流程有两个前置条件,缺一不可:① 已在「系统设置」中配置可用的 SMTP 邮件服务;② 账号已绑定且完成验证(
emailVerified)。若条件不满足,忘记密码页会始终提示「验证码已发送」但实际收不到邮件——这是防止账户枚举的刻意设计,不代表功能异常。
因此建议在首次部署时即为管理员账号绑定并验证***,并优先确保 SMTP 可用。否则一旦口令遗失且无邮件通道,只能通过数据库层面人工介入恢复,风险较高。操作前请务必备份数据库。
生产环境安全配置
install.js 生成的 backend/.env 只包含端口、NODE_ENV、JWT_SECRET 与数据库连接。以下三项不在自动生成范围内,但对生产部署有实际安全影响,需人工补充。
配置位置统一为 backend/.env,修改后执行 pm2 restart idc-backend 生效。
1. BOOTSTRAP_ADMIN_USERNAME(强烈建议)
作用与风险见上一节。这是三项中优先级最高的一项,直接决定「谁能成为管理员」。
2. CORS_ORIGINS(建议)
跨域来源白名单,逗号分隔。用于限制哪些前端来源可以调用 /api。
# 单域名
CORS_ORIGINS=https://idc.example.com
# 多来源(如同时保留内网 IP 访问)
CORS_ORIGINS=https://idc.example.com,http://192.168.1.10
| 状态 | 实际行为 |
|---|---|
| 未配置 | 保持宽松策略,允许多源跨域,兼容开发环境与多入口访问 |
| 已配置 | 仅放行清单内的来源,其余来源的跨域请求会被拒绝 |
[!NOTE] 前后端同域部署(Nginx 同时提供静态页与
/api代理)时,浏览器请求不构成跨域,即使不配置也能正常工作。此项主要针对分离部署或需要显式收紧的场景。
3. REMOTE_BACKUP_KEY(按需)
用于加密远程备份目标(FTP/SFTP/SMB/WebDAV)中的口令、私钥等敏感字段,算法为 AES-256-GCM(带完整性认证)。
# 生成命令(Node.js)
# node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
REMOTE_BACKUP_KEY=
| 状态 | 实际行为 |
|---|---|
| 未配置 | 自动复用 JWT_SECRET 派生密钥,只需维护一个密钥 |
| 已配置 | 与 JWT_SECRET 职责分离,单项泄露的影响范围更小 |
[!WARNING] 轮换
JWT_SECRET前务必注意:若REMOTE_BACKUP_KEY未配置(即复用JWT_SECRET),直接更换JWT_SECRET会使所有已保存的远程备份凭据无法解密。轮换前须先用旧密钥执行node scripts/migrate-remote-backup-cipher.js完成重新加密,否则凭据将永久失效。
配置检查
补充完成后可用以下命令确认关键变量是否就位(值会脱敏显示,只判断是否存在):
cd backend
grep -E "^(JWT_SECRET|BOOTSTRAP_ADMIN_USERNAME|CORS_ORIGINS|REMOTE_BACKUP_KEY)=" .env | sed 's/=.*/= /'
[!NOTE] 上述四个变量中,
JWT_SECRET由install.js自动生成,其余三项需人工补充。未出现的行说明该项未配置——CORS_ORIGINS、REMOTE_BACKUP_KEY属可选项;BOOTSTRAP_ADMIN_USERNAME生产环境强烈建议配置。
系统维护
服务管理
# PM2 服务
pm2 status # 查看状态
pm2 logs idc-backend # 查看日志
pm2 restart idc-backend # 重启服务
pm2 stop idc-backend # 停止服务
pm2 delete idc-backend # 删除服务
pm2 save # 保存配置
pm2 startup # 开机自启
# Nginx
sudo nginx -t # 测试配置
sudo nginx -s reload # 重载配置
sudo systemctl restart nginx # 重启服务
日志查看
# PM2 日志
pm2 logs idc-backend
pm2 logs idc-backend --err # 仅错误日志
# Nginx 日志
sudo tail -f /var/log/nginx/error.log
# 应用日志
tail -f backend/logs/*.log
数据备份
# 内置备份
# 系统管理 → 备份管理 → 创建备份
# 命令行备份
cd backend && node scripts/backup.js
# 还原
cd backend && node scripts/restore.js
事故诊断
线上出现异常(5xx 突增、接口不可达、疑似发布引入故障)时,使用内置的只读诊断脚本快速定位,无需登录系统。
# 在项目根目录执行
npm run doctor
# 等价于
node scripts/incident-doctor.js
脚本特性:
- 纯只读:不重启服务、不修改配置、不写入业务文件,所有修复动作仅以命令文本形式输出,可在生产环境直接安全运行
- 无需安装依赖:仅
requireNode 内置模块(fs/path/os/net/http/child_process),不依赖项目node_modules,无需执行npm install即可运行 - 单文件可移植:将
scripts/incident-doctor.js单独通过scp传输到目标服务器即可执行,无需同步整个仓库 - 优雅降级:按需调用
ps/ss/netstat/docker/git采集运行时信息(通过execFile直接执行,不经过 shell 以规避注入风险);如果上述命令缺失,或是日志目录、.env、/proc不存在,脚本不会中断运行,对应采集项会标注为「不可用」
常用参数:
| 参数 | 说明 |
|---|---|
--json | 输出机器可读的 JSON 格式内容(默认输出中文事故卡) |
--out | 事故卡 Markdown 文件的落盘目录,默认值为 ./incidents |
--root | 项目根目录,默认自动探测包含 backend/server.js 或 backend/.env 的目录 |
--port | 后端期望监听端口,默认读取 backend/.env 中的 PORT 配置,未配置则回退为 8000 |
--container | 后端容器名称,默认自动探测名称为 idc-backend 或名称包含 backend 的容器 |
--window | 故障与最近部署的关联判定时间窗口,默认值为 10 分钟 |
--sample-minutes | HTTP 指标统计的时间窗口,默认值为 60 分钟 |
-h, --help | 显示帮助信息 |
输出内容:
- 终端:输出中文事故卡,包含判定结论 / 置信度 / HTTP 观测指标 / 故障开始时间 / 最近部署记录 / 核心证据 / 影响面 / 分级处置动作
- 文件:生成
incident-<时间戳>.md文件,两种输出模式下均会自动落盘
判定口径要点:
- 4xx(401/403/404)请求默认不计入故障统计,仅作为辅助证据;仅当 401/403 请求相对基线显著突增、且来源 IP 高度集中等条件满足时,才会升级为故障候选
- 故障候选仅包含以下场景:5xx 错误、请求超时或连接失败、进程/容器不可用、资源耗尽、伴随 5xx 错误的代码异常
- 当统计窗口内的响应样本少于 100 条时,脚本会标注「样本不足,不下结论」,不输出百分比形式的统计结论
- 若最近部署/配置变更的时间点与故障起始时间的差值 ≤
--window参数设定的分钟数,会优先判定为疑似发布引入故障,建议优先执行回滚操作
典型用法:
# 生产机应急排查(单文件拷贝即可,不依赖项目其余文件)
scp scripts/incident-doctor.js root@prod:/opt/idc/
ssh root@prod "cd /opt/idc && node incident-doctor.js"
# 将部署关联窗口放宽到 30 分钟,并输出 JSON 格式内容供后续程序处理
npm run doctor -- --window 30 --json
# 指定事故卡文件的落盘位置
npm run doctor -- --out /tmp/incidents
[!NOTE] 通过
npm run doctor传递参数时必须加--分隔符,否则传入的参数会被 npm 自身消费,无法传递给诊断脚本。
常见问题
- 端口冲突(常见端口:8000、3000、80)
# Linux 环境检查端口占用
netstat -tulpn | grep :8000
# Windows 环境检查端口占用
netstat -ano | findstr :8000
# 解决方案1:修改服务监听端口(编辑 backend/.env 文件)
PORT=8001
# 解决方案2:停止占用对应端口的进程
sudo kill $(lsof -t -i:8000)
-
502 Bad Gateway
-
检查后端服务运行状态:
pm2 status -
检查端口监听状态:
netstat -tulpn | grep 8000 -
校验 Nginx 配置合法性:
nginx -t -
查看 Nginx 错误日志:
tail /var/log/nginx/error.log
[!NOTE] 如果近期修改过
backend/.env中的PORT配置,Nginx 仍可能代理旧的端口。执行node install.js --regen-nginx重新生成并同步 Nginx 配置,再执行pm2 restart idc-backend重启后端服务即可。
- 前端构建失败
# 检查 Node.js 版本
node -v # 要求版本 ≥16.x,推荐使用 20.x LTS 版本
# 清理依赖后重试构建
cd frontend
rm -rf node_modules dist
npm install
npm run build
- 数据库连接失败
先确认 backend/.env 中的 DB_TYPE 配置与实际部署的数据库类型一致(可选值为 sqlite 或 mysql)。
MySQL 场景排查步骤:
- 检查 MySQL 服务运行状态:
sudo systemctl status mysql - 校验连接参数配置(
DB_HOST、DB_PORT、DB_USERNAME、DB_PASSWORD、DB_NAME) - 确认目标数据库已创建:执行 SQL 语句
SHOW DATABASES;验证 - 检查数据库用户权限(将下方占位符替换为
.env文件中配置的DB_USERNAME与对应主机地址):
SHOW GRANTS FOR '<DB_USERNAME>'@'<DB_HOST>';
SQLite 场景(默认配置)排查步骤:
- 确认
backend/.env中DB_STORAGE指向的数据库文件具备可写权限,且运行服务的用户对backend/目录拥有写入权限 - 查看后端日志
backend/logs/error-*.log中以SQLITE_开头的错误码定位具体问题
- 权限问题
# 修复项目目录所属用户权限
sudo chown -R $(whoami):$(whoami) /path/to/idc_assest
# 开放上传目录读写权限
sudo chmod -R 777 backend/uploads
- 内存不足
通过 PM2 为 Node 进程追加 V8 堆上限参数(其中 idc-backend 为安装脚本创建的服务名):
# 临时生效,服务重启后配置会恢复默认
pm2 restart idc-backend --node-args="--max-old-space-size=4096"
# 永久生效:先删除原有服务,再带参数重建
pm2 delete idc-backend
cd backend && pm2 start server.js --name idc-backend \
--node-args="--max-old-space-size=4096" --env production
pm2 save
[!WARNING]
--update-env参数仅会刷新环境变量,不会应用--node-args参数配置,请勿使用该命令调整内存上限。 另外请注意deploy/ecosystem.config.js中默认配置了max_memory_restart: '1G',当进程内存占用超过该阈值时 PM2 会自动重启服务——排查内存相关问题时需要同步确认该阈值是否设置过小。
- npm 安装失败
# 清理 npm 本地缓存
npm cache clean --force
# 删除旧依赖后重新安装
rm -rf node_modules package-lock.json
npm install
- PM2 服务消失
# 重新启动服务(与安装脚本的启动方式保持一致即可)
cd backend && pm2 start server.js --name idc-backend --env production
pm2 save
pm2 startup
[!NOTE] 如果你希望改用预定义的 PM2 配置文件启动服务(配置中包含日志路径、
max_memory_restart等完整参数),配置文件路径为deploy/ecosystem.config.js,不在项目根目录下:
> pm2 start deploy/ecosystem.config.js
>
注意安装脚本默认不使用该配置文件启动服务,两种启动方式二选一即可,请勿混用导致生成同名重复进程。
- 打不开注册页 / 注册后没有管理员权限
系统不会内置默认账号,管理员权限自动授予首个成功注册的用户。如果注册后未获得管理员权限,最常见原因是 backend/.env 中配置了 BOOTSTRAP_ADMIN_USERNAME,但你注册使用的用户名和该配置值不一致——此时你的账号状态为 pending(待审核),需要由管理员在用户管理页面完成审核,或是使用该预设的管理员用户名重新注册。
详细说明可参考 首次访问与管理员账号。
- 怀疑线上故障,需要快速定位
优先运行内置的只读诊断脚本,无需手动逐个翻阅日志:
npm run doctor # 在项目根目录下执行
npm run doctor -- --json # 输出机器可读的 JSON 格式结果
npm run doctor -- --window 30 # 将部署关联判定窗口放宽至 30 分钟
该脚本不会修改任何配置、不会重启任何服务,可在生产环境安全运行,详细说明可参考 事故诊断。
项目结构
idc_assest/
├── frontend/ # 前端项目目录
│ ├── src/
│ │ ├── api/ # API 接口定义
│ │ ├── components/ # 通用组件(3d/、dashboard/、device/、floorplan/ 子目录)
│ │ ├── pages/ # 页面组件
│ │ ├── hooks/ # 自定义 Hooks
│ │ ├── stores/ # 状态管理模块
│ │ └── utils/ # 通用工具函数
│ └── package.json
├── backend/ # 后端项目目录
│ ├── models/ # Sequelize 数据模型
│ ├── routes/ # API 路由定义
│ ├── middleware/ # 中间件
│ ├── scripts/ # 数据库脚本(init-database.js、migrate-all.js)
│ ├── utils/ # 后端工具函数
│ ├── uploads/ # 用户上传文件存储目录
│ ├── server.js # 后端服务入口文件
│ └── package.json
├── deploy/ # 部署相关配置
│ ├── nginx-troubleshooting.md # Nginx 404 问题排查教程
│ ├── ecosystem.config.js # PM2 配置文件(由 install.js 自动生成,不纳入代码仓库)
│ └── nginx-idc.conf # Nginx 站点配置(由 install.js 自动生成,不纳入代码仓库)
├── install/ # 安装脚本依赖模块
├── docs/ # 项目文档目录
├── install.sh # Linux 环境一键安装引导脚本
├── install.js # 安装脚本入口文件
├── update.js # 项目升级脚本
├── uninstall.js # 项目卸载脚本
└── README.md # 本文档
API 文档
仅在开发环境可用。以开发模式启动后端服务后,访问对应地址即可查看文档。 该文档基于 Swagger/OpenAPI 3.0 标准构建,支持在线身份认证测试和 API 接口调试。
[!IMPORTANT] 生产环境默认不提供该 API 文档页面。当环境变量
NODE_ENV=production时,后端不会挂载 Swagger UI 页面和完整的 OpenAPI 规格文件(该规格包含全部接口端点和参数定义,存在信息泄露风险),访问对应地址会返回 404。如果需要查阅接口规格,请切换到开发环境启动服务,或直接查看源码中的路由定义。
贡献指南
欢迎大家提交 Issue 或 Pull Request 参与项目贡献!
# 1. Fork 本项目到你的 GitHub 账号下
# 2. 克隆你账号下的 Fork 副本到本地
git clone https://github.com/YOUR_USERNAME/idc_assest.git
cd idc_assest
# 3. 创建独立的开发分支
git checkout -b feature/your-feature # 功能开发场景分支命名规则
git checkout -b fix/your-fix # Bug 修复场景分支命名规则
# 4. 本地完成开发后提交改动
git commit -m 'feat: 添加新功能'
git commit -m 'fix: 修复问题'
# 5. 推送本地分支到远程仓库,然后在 GitHub 页面提交 PR
git push origin feature/your-feature
提交信息规范:
| 类型标识 | 说明 |
|---|---|
| feat | 新增功能 |
| fix | 修复 Bug |
| docs | 文档内容更新 |
| style | 代码格式调整(不影响代码运行逻辑) |
| refactor | 代码重构(既不新增功能也不修复 Bug) |
| perf | 性能优化改动 |
| test | 测试用例相关改动 |
| chore | 构建流程、依赖工具等辅助工具的改动 |
开发规范:
- 代码使用 ES6+ 语法
- 遵循 React Hooks 官方开发规范
- 使用 async/await 语法处理异步逻辑
- 遵循 ESLint + Prettier 定义的代码风格规范
支持项目
如果这个项目对你有帮助,欢迎给仓库点 Star、分享项目,也可以通过以下方式支持作者的维护工作。
赞赏作者
如果你觉得这个项目对你有实用价值,可以请作者喝杯咖啡 ☕
微信赞赏
如需联系作者确认赞赏事宜,可加入官方 :。
许可证
本项目采用**双授权(Dual Licensing)**模式:
开源许可通道(GPL-3.0)
- 遵循 GNU GPL v3.0 许可协议:任何个人或组织都可以免费使用、修改、二次开发、分发本项目代码。
- 使用条件:所有基于本项目衍生的作品必须以 GPL-3.0 协议完全开源,并公开全部源代码。
商业许可通道(商业授权)
- 所有不符合 GPL-3.0 开源要求的商业使用场景,或是闭源二次开发场景,必须获得授权方 gituib 出具的商业授权。
- 适用商业授权的场景包括:闭源分发/销售软件、将本项目封装进闭源商业产品、对外提供商业化部署服务、企业内部闭源商业化运营等。
- 商业授权为非独占许可,付费后即可合法使用、修改、分发本软件,也可将其闭源集成到自有产品中,详细条款可查阅 LICENSE-COMMERCIAL.md。
版权 © 2026 gituib
如需申请商业授权,请通过*** *** 联系作者咨询详情。
⭐ 如果这个项目对您有帮助,请给我们点一个 Star!
- GitHub Issues 反馈入口:https://github.com/gituib/idc_assest/issues
- 官方 QQ 交流群:***
用户好评
来自真实用户的反馈,见证轩辕镜像的优质服务