Windows 设备部署文档

1. 环境要求

Windows 10/11 或 Windows Server
Python 3.11 及以上
Node.js 20 及以上
smartmontools，且 smartctl.exe 已加入 PATH
可选：LibreHardwareMonitor 或 OpenHardwareMonitor，用于提供更完整的 CPU/GPU/主板温度传感器
可选：NVIDIA 驱动自带 nvidia-smi，用于 NVIDIA 显卡负载、温度、显存和功耗

2. 获取项目

将项目目录复制到目标设备，例如：

C:\Apps\win_monitor

以下命令默认在项目根目录执行：

cd C:\Apps\win_monitor

3. 安装 Python 依赖

建议使用虚拟环境：

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r backend\requirements.txt

如果 PowerShell 禁止执行激活脚本，可先执行：

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

4. 安装前端依赖并构建

cd frontend
npm install
npm run build
cd ..

开发调试时可运行：

cd frontend
npm run dev -- --port 5173

当前前端开发服务器默认监听 0.0.0.0:5173，同一局域网内其他设备可通过 http://目标设备IP:5173 访问。

生产部署建议使用前端构建产物 frontend\dist，可由 Nginx、IIS 或其他静态文件服务承载。

5. 安装 smartmontools

下载安装 smartmontools for Windows，并确认命令可用：

smartctl --version
smartctl --scan

如果提示找不到命令，请将 smartmontools 安装目录加入系统 PATH，常见路径类似：

C:\Program Files\smartmontools\bin

项目也会自动尝试以下常见路径：

C:\Program Files\smartmontools\bin\smartctl.exe
C:\Program Files (x86)\smartmontools\bin\smartctl.exe

如果安装在其他目录，可设置环境变量：

$env:SMARTCTL_PATH="D:\Tools\smartmontools\bin\smartctl.exe"

JMB39x USB 阵列硬盘柜中的硬盘可使用类似命令验证：

smartctl -a -d jmb39x,0 /dev/sdb
smartctl -a -d jmb39x,1 /dev/sdb

本项目的 SMART 页面会在启用“探测 JMB39x 阵列槽位”后自动按槽位读取。

6. 可选：启用更完整的温度传感器

Windows 原生接口经常无法直接提供 CPU、GPU 和主板真实温度。建议在目标设备上运行 LibreHardwareMonitor 或 OpenHardwareMonitor，并开启 WMI 暴露能力。

后端会尝试读取以下 WMI 命名空间：

root\LibreHardwareMonitor
root\OpenHardwareMonitor

如果没有这些组件，页面仍会展示 CPU/内存负载、NVIDIA 显卡信息、Windows GPU 性能计数器和可用的 ACPI 温度。

7. 启动后端

开发或本机使用：

cd C:\Apps\win_monitor\backend
..\.venv\Scripts\python.exe -m uvicorn app.main:app --host 127.0.0.1 --port 8000

如果上一条命令因路径复制产生问题，请使用绝对路径：

C:\Apps\win_monitor\.venv\Scripts\python.exe -m uvicorn app.main:app --host 127.0.0.1 --port 8000

局域网访问：

C:\Apps\win_monitor\.venv\Scripts\python.exe -m uvicorn app.main:app --host 0.0.0.0 --port 8000

如需局域网访问，请在 Windows 防火墙中放行 TCP 8000 端口，并按实际安全要求限制访问来源。

8. 启动前端

开发模式：

cd C:\Apps\win_monitor\frontend
npm run dev -- --host 0.0.0.0 --port 5173

访问：

http://目标设备IP:5173

前端默认会把 API 地址解析为当前访问主机的 8000 端口。例如从局域网访问 http://192.168.1.10:5173 时，前端会默认请求 http://192.168.1.10:8000。

如需局域网访问，请在 Windows 防火墙中放行 TCP 5173 端口。开发模式适合测试自动化操作；生产环境仍建议把 frontend\dist 交给 IIS、Nginx 或其他静态文件服务。

如果前端和后端不在同一台机器，或后端不是当前主机的 8000 端口，请在启动或构建前设置：

$env:VITE_API_BASE="http://目标设备IP:8000"
npm run build

9. 作为 Windows 服务运行后端

可使用 NSSM：

nssm install WinMonitorApi

推荐配置：

Application path：C:\Apps\win_monitor\.venv\Scripts\python.exe
Startup directory：C:\Apps\win_monitor\backend
Arguments：-m uvicorn app.main:app --host 127.0.0.1 --port 8000

如果需要让局域网设备访问后端，Arguments 改为：

-m uvicorn app.main:app --host 0.0.0.0 --port 8000

保存后启动：

nssm start WinMonitorApi

10. 数据和日志

SQLite 数据库位置：backend\data\win_monitor.db
服务、进程和扫描记录会写入数据库。
传感器信息和 SMART 信息是实时读取，不写入数据库。
如果需要备份，只需停止后端后复制 backend\data\win_monitor.db。

11. 项目自身会增加的进程

项目启动后，进程列表中会出现一些属于本项目自身或由本项目临时调用的进程。做服务/进程扫描结果确认时，可以将这些进程按实际部署方式标记为可信。

后端常驻进程

使用以下命令启动后端时：

C:\Apps\win_monitor\.venv\Scripts\python.exe -m uvicorn app.main:app --host 127.0.0.1 --port 8000

通常会看到：

进程名	说明
`python.exe`	FastAPI 后端主进程，运行 `uvicorn app.main:app`，负责 API、扫描、传感器和 SMART 查询

如果使用 NSSM 注册为 Windows 服务，还会看到：

进程名	说明
`nssm.exe`	NSSM 服务包装器，用于托管后端 Python 进程
`python.exe`	被 NSSM 启动的 FastAPI 后端主进程

前端开发模式进程

如果使用开发模式启动前端：

npm run dev -- --host 0.0.0.0 --port 5173

通常会看到：

进程名	说明
`node.exe`	Vite 前端开发服务器
`npm.cmd` / `cmd.exe`	启动脚本外壳，某些启动方式下会短暂或持续存在

实际部署时，如果前端使用 frontend\dist 静态文件，并由 IIS、Nginx 或其他 Web 服务承载，则不会再有 Vite 的 node.exe 进程。此时前端相关进程取决于你选择的静态文件服务，例如 nginx.exe 或 IIS 的 w3wp.exe。

实时查询产生的临时进程

访问传感器或 SMART 页面时，后端可能临时启动以下进程，执行完会退出：

进程名	触发场景	说明
`smartctl.exe`	打开或刷新硬盘 SMART 页面	读取硬盘 SMART 信息，包括 JMB39x 阵列槽位探测
`powershell.exe` / `pwsh.exe`	打开或刷新传感器页面	读取 WMI 传感器、ACPI 温度或 Windows GPU 性能计数器
`nvidia-smi.exe`	存在 NVIDIA 显卡并刷新传感器页面	读取 NVIDIA 显卡负载、温度、显存和功耗

这些临时进程一般只在接口请求期间出现，不属于常驻服务。如果扫描进程列表时刚好捕获到它们，可以结合命令行和父进程判断是否由本项目后端触发。

最小常驻进程总结

推荐生产部署方式下，项目自身最少只需要：

进程名	是否常驻	用途
`python.exe`	是	后端 API 服务
`nssm.exe`	是，可选	仅当使用 NSSM 托管后端服务时出现
`nginx.exe` / `w3wp.exe` / 其他静态服务进程	是，可选	仅当前端由独立静态 Web 服务承载时出现

不建议在生产环境长期使用 npm run dev，因为它会额外保留 node.exe 开发服务器进程，适合调试，不适合作为正式前端服务。

12. 结束程序

结束程序时，先确认你当前采用的是哪种启动方式。推荐优先使用启动方式对应的正常停止命令，避免直接结束无关的 python.exe、node.exe 或 Web 服务进程。

命令行窗口中启动的后端

如果后端是在 PowerShell 或 CMD 窗口中用以下方式启动的：

python -m uvicorn app.main:app --host 127.0.0.1 --port 8000

在该窗口按：

Ctrl + C

即可停止后端。

如果窗口已经关闭但进程仍在，可按端口查找并停止：

$pid = (Get-NetTCPConnection -LocalPort 8000 -State Listen).OwningProcess
Stop-Process -Id $pid

NSSM 服务方式启动的后端

如果后端注册成了 NSSM 服务，例如服务名是 WinMonitorApi：

nssm stop WinMonitorApi

或使用 Windows 服务命令：

Stop-Service WinMonitorApi

如需禁止开机自启：

Set-Service WinMonitorApi -StartupType Manual

如需彻底删除该服务：

nssm remove WinMonitorApi confirm

前端开发服务器

如果前端是开发模式启动的：

npm run dev -- --host 0.0.0.0 --port 5173

在该窗口按：

Ctrl + C

即可停止前端开发服务器。

如果窗口已经关闭但 node.exe 仍在监听 5173 端口，可执行：

$pid = (Get-NetTCPConnection -LocalPort 5173 -State Listen).OwningProcess
Stop-Process -Id $pid

静态 Web 服务方式部署的前端

如果前端由 Nginx 承载：

nginx -s stop

如果前端由 IIS 承载，可停止对应站点，或停止 IIS：

Stop-Website -Name "WinMonitor"

如果需要停止整个 IIS 服务：

iisreset /stop

注意：iisreset /stop 会影响该设备上的所有 IIS 站点，使用前请确认没有其他业务依赖 IIS。

临时查询进程

smartctl.exe、powershell.exe / pwsh.exe、nvidia-smi.exe 是由后端在刷新传感器或 SMART 页面时临时启动的查询进程，正常情况下会自动退出，不需要手动停止。

传感器接口已对外部命令设置超时，并会在超时后清理对应进程树。也就是说，由本项目后端启动的 PowerShell 查询进程不应该长期残留。

如果看到长期存在的 powershell.exe 或 pwsh.exe，请先查看它的父进程和命令行，确认是否属于本项目：

Get-CimInstance Win32_Process -Filter "name = 'powershell.exe' or name = 'pwsh.exe'" |
  Select-Object ProcessId, ParentProcessId, CreationDate, CommandLine |
  Format-List

再查看后端进程 PID：

Get-CimInstance Win32_Process -Filter "name = 'python.exe'" |
  Where-Object { $_.CommandLine -like '*uvicorn app.main:app*' } |
  Select-Object ProcessId, ParentProcessId, CommandLine |
  Format-List

如果 PowerShell 的 ParentProcessId 等于后端 python.exe 的 ProcessId，才说明它是本项目后端临时启动的查询进程。

如果某次硬盘或 WMI 查询卡住，可先停止后端；后端停止后仍残留且确认属于本项目的临时查询进程，再按需结束：

Get-Process smartctl,powershell,pwsh,nvidia-smi -ErrorAction SilentlyContinue

确认是本项目触发且不再需要后，可结束指定 PID：

Stop-Process -Id 进程ID

一次性检查项目是否仍在运行

检查后端端口：

Get-NetTCPConnection -LocalPort 8000 -State Listen -ErrorAction SilentlyContinue

检查前端开发端口：

Get-NetTCPConnection -LocalPort 5173 -State Listen -ErrorAction SilentlyContinue

如果没有输出，表示对应端口没有进程监听。

13. 常见问题

页面没有温度

优先确认 LibreHardwareMonitor/OpenHardwareMonitor 是否运行并开启 WMI。部分硬件或驱动不向 Windows 暴露温度，这是正常限制。

SMART 页面提示 smartctl 不存在

确认 smartmontools 已安装，并且 smartctl.exe 所在目录已加入系统 PATH。重新打开 PowerShell 后执行 smartctl --scan 验证。

JMB39x 槽位没有显示硬盘

先手动执行：

smartctl -a -d jmb39x,0 /dev/sdb

将 /dev/sdb 替换为 smartctl --scan 中对应的阵列设备。如果手动命令能输出硬盘信息，页面刷新后也应能展示。

deployment.md 12 KB Histórico Raw