ghcr.io/gituib/idc-backend

ghcr.io/gituib/idc-backend:00f558e

ghcr.iolinux/amd6400f558e大小: 116.22 MB更新于 2026年11月20日

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.020.x LTS
内存4GB8GB+
磁盘2GB10GB+
数据库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

首次访问与管理员账号

系统不内置默认管理员账号,管理员通过「首个注册用户」机制产生。首次部署完成后:

  1. 打开前端页面,进入注册页创建第一个账号。
  2. 该账号在满足下方规则时自动获得管理员权限。

首管理员分配规则

.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

脚本特性:

  • 纯只读:不重启服务、不修改配置、不写入业务文件,所有修复动作仅以命令文本形式输出,可在生产环境直接安全运行
  • 无需安装依赖:仅 require Node 内置模块(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 自身消费,无法传递给诊断脚本。


常见问题

  1. 端口冲突(常见端口: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)
  1. 502 Bad Gateway

  2. 检查后端服务运行状态:pm2 status

  3. 检查端口监听状态:netstat -tulpn | grep 8000

  4. 校验 Nginx 配置合法性:nginx -t

  5. 查看 Nginx 错误日志:tail /var/log/nginx/error.log

[!NOTE] 如果近期修改过 backend/.env 中的 PORT 配置,Nginx 仍可能代理旧的端口。执行 node install.js --regen-nginx 重新生成并同步 Nginx 配置,再执行 pm2 restart idc-backend 重启后端服务即可。

  1. 前端构建失败
# 检查 Node.js 版本
node -v # 要求版本 ≥16.x,推荐使用 20.x LTS 版本

# 清理依赖后重试构建
cd frontend
rm -rf node_modules dist
npm install
npm run build
  1. 数据库连接失败

先确认 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_ 开头的错误码定位具体问题
  1. 权限问题
# 修复项目目录所属用户权限
sudo chown -R $(whoami):$(whoami) /path/to/idc_assest

# 开放上传目录读写权限
sudo chmod -R 777 backend/uploads
  1. 内存不足

通过 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 会自动重启服务——排查内存相关问题时需要同步确认该阈值是否设置过小。

  1. npm 安装失败
# 清理 npm 本地缓存
npm cache clean --force

# 删除旧依赖后重新安装
rm -rf node_modules package-lock.json
npm install
  1. 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
>

注意安装脚本默认不使用该配置文件启动服务,两种启动方式二选一即可,请勿混用导致生成同名重复进程。

  1. 打不开注册页 / 注册后没有管理员权限

系统不会内置默认账号,管理员权限自动授予首个成功注册的用户。如果注册后未获得管理员权限,最常见原因是 backend/.env 中配置了 BOOTSTRAP_ADMIN_USERNAME,但你注册使用的用户名和该配置值不一致——此时你的账号状态为 pending(待审核),需要由管理员在用户管理页面完成审核,或是使用该预设的管理员用户名重新注册。 详细说明可参考 首次访问与管理员账号。

  1. 怀疑线上故障,需要快速定位

优先运行内置的只读诊断脚本,无需手动逐个翻阅日志:

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 交流群:***
专业版 · 高速稳定拉取镜像
50GB 仅 ¥8/年
高速镜像下载在线技术支持专业版保障服务可用付费会员免广告