# SA-CM

**Repository Path**: dromara/sa-cm

## Basic Information

- **Project Name**: SA-CM
- **Description**: 快把你家里吃灰的平板、手机拿来搞副屏吧 —— CPU、内存、GPU、磁盘、网络、进程、功耗风扇
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 11
- **Forks**: 1
- **Created**: 2026-08-07
- **Last Updated**: 2026-09-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SA-CM · 局域网 Windows 性能监控

在被监控的 Windows 电脑上跑一个轻量 Web 服务，局域网里的平板 / 手机浏览器打开就能看——**CPU、内存、GPU、磁盘、网络、进程、功耗风扇**，一屏搞定。**快把你家里吃灰的平板、手机拿来搞副屏吧**。

不想研究源码想直接使用的同学可以直接下载项目右侧发行版，**双击启动直接用**。

目前源码就是 vibe 出来的一坨 💩。如果关注的同学比较多，我就持续更新此项目 😂，要是没人吊我，那就算了 😓。

![SA-CM 仪表盘演示](show-img/show-img-1.png)

---

## 🤔 为啥搞这个项目？

两年前在淘宝花 **572** 买了个平板——这个价钱啥档次，我心里也有数。买的时候想着：「这要能看个视频就算值了。」

结果买回来后，它还真就**只能看个视频**；干别的事，直接卡成 PPT 📽️

吃灰都快两年了，每次看见都觉得有点来气。某天夜里垂死梦中惊坐起：**何不搞一个监控副屏？** 于是就有了这个项目。

---

## ✨ 特性

| | |
|---|---|
| 📊 **实时仪表盘** | 环形仪表 + 趋势折线，P0 指标首屏可见，专为横屏平板优化 |
| 🔄 **增量刷新** | 轮询更新数据，不整页刷新，适合常亮监控屏 |
| 🎮 **GPU / 显存** | 支持 NVIDIA 独显占用、温度、显存（NVML + hw-bridge） |
| 🌡️ **温度与传感器** | CPU / GPU 温度、功耗、风扇转速（LibreHardwareMonitorLib） |
| 📋 **进程 Top 5** | 按 CPU 占用排序，独立采样间隔，省资源 |
| 💡 **屏幕常亮** | Wake Lock + 隐藏视频兜底，平板挂墙不掉屏 |
| ✨ **扫描线动效** | 可选扫描线，直观感知刷新节奏 |
| 🖼️ **背景图** | 支持自定义背景，监控屏也能好看 |
| 🔔 **系统托盘** | 一键打开 / 复制局域网 URL，右键退出 |
| 🔌 **端口自愈** | 默认 `28473` 被占用时自动尝试后续端口 |
| 📦 **单文件 exe** | PyInstaller 打包，拷贝 `dist/` 目录即可运行 |

---

## 🚀 快速开始

### 环境要求

- Windows 10 / 11
- Python 3.11+
- .NET SDK 5+（编译硬件传感器桥，仅首次或更新时需要）

### 安装

```powershell
cd sa-cm
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"

# 编译 hw-bridge（内嵌 LibreHardwareMonitorLib，Windows 必做）
dotnet publish tools/hw-bridge/HwBridge.csproj -c Release -o tools/hw-bridge/publish

copy config.example.toml config.toml
```

### 启动

```powershell
python -m sacm.main
# 或
sacm
```

默认监听 `http://0.0.0.0:28473`。若配置了 `open_browser_on_start = true`，启动后会自动打开浏览器。

### 停止

- **命令行**：终端按 `Ctrl+C`
- **系统托盘**：右键托盘图标 → **退出**（`enable_tray = true` 时）

---

## 🌐 局域网访问

1. 在被监控机运行 `ipconfig`，记下 IPv4 地址（如 `192.168.1.100`）
2. 平板 / 手机浏览器打开：`http://192.168.1.100:28473/`
3. **Windows 防火墙**：入站规则放行 TCP **28473**（若端口被自动切换，以托盘 / 控制台实际端口为准）

> 💡 同一 URL 可被多台设备同时打开，只读并发，无会话锁。

---

## 🖥️ 系统托盘

启动后（`enable_tray = true`）任务栏托盘图标支持：

- 查看运行状态
- 打开仪表盘（局域网 URL）
- 复制局域网 URL 到剪贴板
- 退出服务

---

## ⚙️ 配置

编辑 `config.toml`（由 `config.example.toml` 复制）：

| 项 | 默认 | 说明 |
|----|------|------|
| `port` | `28473` | HTTP 端口（被占用时自动尝试后续端口） |
| `port_fallback_attempts` | `20` | 端口占用时最多向后尝试次数 |
| `sample_interval_ms` | `2000` | 后端采样间隔 |
| `process_sample_interval_ms` | `10000` | Top5 进程扫描间隔（越大越省资源） |
| `poll_default_ms` | `2000` | 前端默认轮询间隔 |
| `history_minutes` | `30` | 趋势缓冲保留时长 |
| `enable_tray` | `true` | 是否启用托盘 |
| `open_browser_on_start` | `true` | 启动后自动打开浏览器 |
| `dev_live_reload` | `false` | 开发模式：`static/` 变更后自动刷新 |
| `hw_bridge_enabled` | `true` | 启用内嵌 hw-bridge 传感器采集 |

### 🔧 前端热刷新（开发）

```toml
dev_live_reload = true
```

保存 `static/` 下任意前端文件后，已打开的页面约 1 秒内自动刷新。生产环境请保持 `false`。

---

## 🌡️ CPU / GPU 温度与传感器

SA-CM 通过 **`tools/hw-bridge`** 内嵌 [LibreHardwareMonitorLib](https://github.com/LibreHardwareMonitor/LibreHardwareMonitor)，**无需单独安装 LHM GUI**。

采集优先级：

1. **内嵌 hw-bridge**（LibreHardwareMonitorLib，推荐）
2. 外部 LHM HTTP（若用户自行开启 Remote Web Server）
3. 系统 WMI 热区（多数台式机不可用）

部分传感器需要 **以管理员身份运行**：

```powershell
# 开发模式
python -m sacm.main

# 打包后
# 右键 SA-CM.exe → 以管理员身份运行
```

`config.toml` 相关项：

```toml
hw_bridge_enabled = true
# hw_bridge_path = "tools/hw-bridge/publish/sacm-hw-bridge.exe"
lhm_http_url = "http://127.0.0.1:8085"
```

---

## 📦 打包为 exe

一键打包脚本（含 hw-bridge 编译、pytest、PyInstaller）：

```powershell
.\scripts\build.ps1
```

跳过测试加速：

```powershell
.\scripts\build.ps1 -SkipTests
```

### 产物目录

```
dist/
  SA-CM.exe                 # 双击启动（无控制台，托盘常驻）
  config.toml               # 从项目根刷新（不存在则用 config.example.toml）
  config.example.toml
  tools/hw-bridge/publish/  # 硬件传感器桥，需与 exe 同级
    sacm-hw-bridge.exe
    ...
```

将整个 `dist/` 目录拷贝到其他 Windows 电脑即可；`config.toml` 与 `tools/` 需与 `SA-CM.exe` 保持在同一目录。

> 📌 前端 `static/` 已内嵌进 exe，无需单独拷贝。

手动打包：`pip install pyinstaller` 后执行 `pyinstaller --clean sacm.spec`

---

## 🧪 测试

```powershell
pytest -v
```

---

## 📄 更多文档

- 需求与验收：[需求书.md](需求书.md)

---

## 💬 说明

- 趋势缓冲有上限（默认 30 分钟，按采样间隔动态计算点数），长时间运行内存应趋于稳定
- 若 24h 运行后内存持续线性增长，欢迎提 issue

---

<p align="center">Made with 💻 for 局域网监控屏</p>