# 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. 获取项目

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

```powershell
C:\Apps\win_monitor
```

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

```powershell
cd C:\Apps\win_monitor
```

## 3. 安装 Python 依赖

建议使用虚拟环境：

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

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

```powershell
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
```

## 4. 安装前端依赖并构建

```powershell
cd frontend
npm install
npm run build
cd ..
```

开发调试时可运行：

```powershell
cd frontend
npm run dev
```

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

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

## 5. 安装 smartmontools

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

```powershell
smartctl --version
smartctl --scan
```

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

```text
C:\Program Files\smartmontools\bin
```

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

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

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

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

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

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

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

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

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

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

```text
root\LibreHardwareMonitor
root\OpenHardwareMonitor
```

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

## 7. 启动后端

### 推荐：使用项目脚本同时启动前后端

项目根目录提供 Windows PowerShell 启动和关闭脚本。脚本会在后台启动服务，将 PID 保存到 `.runtime\processes.json`，并把日志写入 `.runtime\logs`：

```powershell
.\start.ps1
```

也可以双击 `start.cmd`，或在 CMD 中执行：

```cmd
start.cmd
```

默认启动地址：

- 后端：`http://127.0.0.1:8000`
- 前端：`http://127.0.0.1:5173`

默认监听 `0.0.0.0`，允许局域网访问。只启动后端或不自动打开浏览器时可使用：

```powershell
.\start.ps1 -SkipFrontend
.\start.ps1 -NoBrowser
```

如需修改端口：

```powershell
.\start.ps1 -BackendPort 8080 -FrontendPort 5180
```

本机访问时，自定义后端端口会自动同步给 Vite。如果需要从局域网访问自定义后端端口，请显式指定设备地址：

```powershell
.\start.ps1 -BackendPort 8080 -ApiBaseUrl "http://192.168.1.10:8080"
```

启动前请先创建 `.venv`、安装后端依赖，并在 `frontend` 目录执行过 `npm install`。

视觉自动化、鼠标键盘控制和屏幕截图必须运行在当前登录用户的交互式桌面会话中。客厅娱乐中心部署时，建议让 Windows 自动登录一个专用用户，并通过“任务计划程序”的“用户登录时”触发 `start.ps1 -SkipFrontend -NoBrowser`。不要把后端放到非交互式服务会话里，否则可能无法截取投影仪画面或控制鼠标键盘。

### 手动启动后端

开发或本机使用：

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

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

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

局域网访问：

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

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

## 8. 启动前端

开发模式：

```powershell
cd C:\Apps\win_monitor\frontend
npm run dev
```

访问：

```text
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` 端口，请在启动或构建前设置：

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

## 9. 数据和日志

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

## 10. 项目自身会增加的进程

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

### 后端常驻进程

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

```powershell
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 查询 |

### 前端开发模式进程

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

```powershell
npm run dev
```

通常会看到：

| 进程名 | 说明 |
| --- | --- |
| `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 服务 |
| `nginx.exe` / `w3wp.exe` / 其他静态服务进程 | 是，可选 | 仅当前端由独立静态 Web 服务承载时出现 |

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

## 11. 结束程序

### 推荐：使用项目关闭脚本

如果项目由 `start.ps1` 或 `start.cmd` 启动，在项目根目录执行：

```powershell
.\stop.ps1
```

或双击、调用：

```cmd
stop.cmd
```

关闭脚本优先读取 `.runtime\processes.json`，按进程树关闭本项目启动的后端和前端，避免按名称结束其他 `python.exe` 或 `node.exe`。状态文件丢失时，仅会对默认端口上命令行明确匹配本项目的进程执行兜底关闭。

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

### 命令行窗口中启动的后端

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

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

在该窗口按：

```text
Ctrl + C
```

即可停止后端。

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

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

### 前端开发服务器

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

```powershell
npm run dev
```

在该窗口按：

```text
Ctrl + C
```

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

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

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

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

如果前端由 Nginx 承载：

```powershell
nginx -s stop
```

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

```powershell
Stop-Website -Name "WinMonitor"
```

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

```powershell
iisreset /stop
```

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

### 临时查询进程

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

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

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

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

再查看后端进程 PID：

```powershell
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 查询卡住，可先停止后端；后端停止后仍残留且确认属于本项目的临时查询进程，再按需结束：

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

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

```powershell
Stop-Process -Id 进程ID
```

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

检查后端端口：

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

检查前端开发端口：

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

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

## 12. 常见问题

### 页面没有温度

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

### SMART 页面提示 smartctl 不存在

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

### JMB39x 槽位没有显示硬盘

先手动执行：

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

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