# itgeeker_gpu_widgets

**Repository Path**: itgeeker/itgeeker_gpu_widgets

## Basic Information

- **Project Name**: itgeeker_gpu_widgets
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-20
- **Last Updated**: 2026-07-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Widget

## README

<div align="center">

# 🖥️ itgeeker-gpu-widgets

**一款把多块 GPU "塞进" Windows 桌面的开源浮窗监控插件**

[![License: MulanPSL-2.0](https://img.shields.io/badge/License-MulanPSL--2.0-blue.svg)](LICENSE)
[![Version](https://img.shields.io/badge/version-0.7.0-green.svg)](itgeeker-gpu-widgets_更新日志_2026-07-26.md)
[![Python](https://img.shields.io/badge/Python-3.12%2B-blue.svg)](https://www.python.org/)
[![Platform](https://img.shields.io/badge/Platform-Windows%2010%2F11-0078D6.svg)]()
[![Build: Pass](https://img.shields.io/badge/Build-Pass-brightgreen.svg)]()
[![Powered by PySide6](https://img.shields.io/badge/UI-PySide6-41CD52.svg)](https://doc.qt.io/qtforpython-6/)

> 把 GPU 状态，以最不打扰的方式，放在你最需要它的地方。

</div>

---

## 📖 项目简介

跑 LLM 微调、做大模型推理、玩 4K 光追游戏的时候，你有没有反复切窗口、敲 `nvidia-smi` 才能确认显存没爆？

**itgeeker-gpu-widgets** 是一个轻量级的 GPU 桌面浮窗监控插件。它安静地趴在屏幕角落，**默认置顶但不抢焦点**，用最不打扰的方式，把本机和远程 GPU 的关键指标实时呈现给你——看一眼，余光扫一下，就能掌握每一块显卡的状态。

它不是"看起来啥都有"的大而全平台，而是**把"盯着 GPU"这一件事做到极致**的小工具：深色科技风半透明浮窗、智能变色告警、Windows Toast 通知、SSH 免密远程监控、历史趋势曲线、Top 进程列表……该有的都有，不该有的绝不打扰你。

如果你既想要桌面上"看着就很专业"的科技感，又想真正掌握每一块 GPU 的状态，这个开源小浮窗就是为你准备的。

---

## ✨ 核心特性

- 🎯 **多源一屏监控** —— 同时支持**本机 NVIDIA**、**远程 NVIDIA Ubuntu（SSH + nvidia-smi）**、**远程 Intel Arc Ubuntu（SSH + intel_gpu_top）** 三类数据源并排显示。
- 🔐 **SSH 免密远程接入** —— 远程机器配一次 SSH 密钥，浮窗自动盯上；远程机重启后一键秒级重连。
- 🎨 **深色科技风浮窗** —— `#1a1a2e` 深邃底色 + `#00ff88` 荧光绿 + `#00d4ff` 荧光蓝，**置顶但不抢焦点**，写代码、看文档、刷浏览器它都在。
- 🚨 **智能变色告警** —— 温度 > 85°C、显存 > 90%、GPU 利用率打满？数字立刻变红，余光一扫就知道"不对劲"。
- 🔔 **Windows Toast 通知 + 60 秒防骚扰** —— 开会时不用盯屏幕，右下角弹窗告诉你哪台机器在冒烟；同类告警 60 秒内不重复。
- 🧊 **系统托盘 + 开机自启** —— 自绘 GPU 芯片小图标，右键菜单齐全；设置里勾一下，写入 `HKCU\...\Run`，开机后台默默启动。
- 📈 **1 小时历史趋势曲线** —— 720 个采样点的环形缓冲，pyqtgraph 绘制，丝滑滚动。
- 🏆 **Top 进程列表** —— 本地 NVIDIA 列出显存占用 Top 3 进程，远程 Intel Arc 列出最繁忙的客户端。
- 🖱️ **边缘自动吸附** —— 鼠标拖到屏幕边缘，自动靠边隐藏，不遮挡你的工作区。
- 📦 **PyInstaller 单文件 EXE** —— 不装 Python 也能跑，双击即用，企业内分发无门槛。
- 🧩 **模块边界清晰** —— `collectors / controller / models / services / ui` 五层结构，二次开发门槛极低。

---

## 🎬 效果演示

> _以下为占位图，建议替换为实际截图或 GIF_

<div align="center">

![Demo](assets/gpu_icon.png)

</div>

浮窗示意（ASCII 预览）：

```
┌─────────────────────────────────┐
│  NVIDIA RTX 4090 (本机)         │
│  GPU  :  78.3%                  │
│  VRAM : 18.2 / 24.0 GB          │
│  Temp :  71°C                   │
│  Fan  :  45%                    │
│  Power: 285 W                   │
│  ─────────────────────────────  │
│  DGX Server (远程 SSH)          │
│  GPU  :  92.1%                  │
│  VRAM : 76.0 / 80.0 GB          │
│  Temp :  84°C                   │
│  ...                            │
└─────────────────────────────────┘
```

---

## 🚀 快速上手

### 一、环境准备

| 项目       | 要求                                                              |
| ---------- | ----------------------------------------------------------------- |
| 操作系统   | **Windows 10 / Windows 11**（64 位）                              |
| Python     | **>= 3.12**（仅源码运行需要；下载 EXE 版本无需）                  |
| 显卡       | 本机监控需 NVIDIA GPU；远程监控通过 SSH 接入，**本机无需独显**    |
| 网络       | 远程节点需可 SSH 登录（推荐密钥免密）                              |
| 远程节点   | Ubuntu + NVIDIA（`nvidia-smi`）**或** Ubuntu + Intel Arc（`intel_gpu_top`） |

> 💡 **Windows only？** 浮窗本体依赖 PySide6 + Win10toast，**仅在 Windows 上运行**。但远程节点可以是任意 Linux 发行版。

### 二、安装步骤

#### 🟢 方式一：小白版（下载 EXE，5 秒上手）

前往 [Releases](../../releases) 页面，下载最新的 `itgeeker-gpu-widgets.exe`，**双击即用**——无需 Python 环境，无需任何依赖。

#### 🔧 方式二：开发者版（从源码运行）

```bash
# 1. 克隆仓库
git clone https://github.com/<your-org>/itgeeker-gpu-widgets.git
cd itgeeker-gpu-widgets

# 2. 创建并激活虚拟环境（推荐）
python -m venv .venv
# Windows PowerShell
.venv\Scripts\Activate.ps1
# Windows CMD
.venv\Scripts\activate.bat

# 3. 安装依赖（含开发依赖）
pip install -e ".[dev]"
```

> 如果使用 `uv`：`uv sync --extra dev` 亦可。

### 三、使用示例

#### ▶️ 启动应用

```bash
python main.py
```

启动后，浮窗会出现在屏幕右上角（上次保存的位置），同时系统托盘会出现 GPU 芯片图标。

#### ⌨️ 常用操作

| 操作                          | 效果                              |
| ----------------------------- | --------------------------------- |
| **双击托盘图标**              | 显示 / 隐藏浮窗                   |
| **右键托盘图标**              | 打开菜单：显示、设置、自启、退出  |
| **拖动浮窗到屏幕边缘**        | 自动吸附                          |
| **点击浮窗右上角 ↻**          | 一键重连所有远程节点              |
| **托盘菜单 → 打开设置**       | 编辑 SSH 主机、告警阈值、刷新频率 |

#### 🧪 运行测试

```bash
pytest                    # 跑全部测试
pytest --cov             # 生成覆盖率报告
ruff check .              # 代码风格检查
mypy .                    # 静态类型检查
```

项目使用 **pre-commit** 维护提交质量：

```bash
pre-commit install        # 安装 git hooks（仅需一次）
pre-commit run --all-files
```

---

## ⚙️ 配置说明

浮窗启动后，所有配置均通过 **设置窗口（托盘菜单 → 打开设置）** 完成，配置保存在用户目录下：

```
%USERPROFILE%\.itgeeker-gpu-widgets\config.json
```

### 主要配置项

| 配置项             | 说明                                                            | 默认值                     |
| ------------------ | --------------------------------------------------------------- | -------------------------- |
| `refresh_interval` | 数据刷新周期（秒）                                              | `2`                        |
| `ssh_hosts`        | 远程节点列表，每项含 `name / host / user / port / key_path`     | `[]`                       |
| `alert_thresholds` | 告警阈值：`temp_c / vram_pct / gpu_pct`                         | `85 / 90 / 95`             |
| `alert_cooldown_s` | 同一类告警的最小重复间隔（秒）                                  | `60`                       |
| `autostart`        | 是否开机自启（写入 `HKCU\Software\Microsoft\Windows\CurrentVersion\Run`） | `false`        |
| `window_geometry`  | 浮窗位置与大小                                                  | 屏幕右上角默认位置         |
| `always_on_top`    | 浮窗是否置顶                                                    | `true`                     |

### SSH 密钥免密（远程节点必做）

```powershell
# 1. 生成本机密钥（如已有可跳过）
ssh-keygen -t ed25519

# 2. 把公钥复制到远程 Ubuntu 节点
type $env:USERPROFILE\.ssh\id_ed25519.pub | ssh user@remote-host "mkdir -p ~/.ssh && chmod 700 ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys"

# 3. 在浮窗设置中添加远程节点：
#    name = "DGX Server"
#    host = 192.168.1.100
#    user = your_user
#    port = 22
#    key_path = C:\Users\you\.ssh\id_ed25519
```

### 环境变量（高级）

| 变量名                          | 说明                                       |
| ------------------------------- | ------------------------------------------ |
| `ITGEEKER_GPU_WIDGETS_CONFIG`   | 自定义配置文件路径（覆盖默认位置）         |
| `ITGEEKER_GPU_WIDGETS_LOG_LEVEL`| 日志级别：`DEBUG` / `INFO` / `WARNING`     |

---

## 🤝 贡献指南

欢迎任何形式的贡献——Bug 反馈、功能建议、文档改进、代码 PR 都值得感谢 🙌。

### 提 Issue

- **Bug**：请附带系统版本、Python 版本、复现步骤、相关日志；
- **新功能**：先描述使用场景，再讨论实现方案，避免方向不一致的无效 PR。

### 提 Pull Request

```bash
# 1. Fork 本仓库并克隆你的 Fork
git clone https://github.com/<your-name>/itgeeker-gpu-widgets.git
cd itgeeker-gpu-widgets

# 2. 创建特性分支（feat/、fix/、docs/ 前缀）
git checkout -b feat/support-amd-gpus

# 3. 安装开发依赖
pip install -e ".[dev]"
pre-commit install

# 4. 编写代码 + 测试（tests/ 目录下）
#    新功能请同步更新 docs 与 CHANGELOG

# 5. 本地验证
ruff check .
mypy .
pytest --cov

# 6. 提交（commit 信息遵循 Conventional Commits）
git commit -m "feat: add AMD GPU monitoring via rocm-smi"

# 7. 推送并创建 PR
git push origin feat/support-amd-gpus
```

### 代码风格

- 遵循 [`pyproject.toml`](pyproject.toml) 中的 **ruff** + **mypy** 配置；
- UI 代码集中在 `ui/`，业务逻辑收敛到 `services/`，数据采集放到 `collectors/`；
- 提交前请确保 `pre-commit run --all-files` 通过。

> 💡 **重大变更**（架构调整、新增数据源、协议变更）请先开 Issue 讨论，再写代码。

---

## 📜 开源协议

本项目采用 **[木兰宽松许可证，第 2 版 (MulanPSL-2.0)](LICENSE)** 开源。

> 您可以自由地复制、使用、修改、分发本软件，包括用于商业用途；只需保留版权声明和许可声明。
> 完整条款请参见 [LICENSE](LICENSE) 文件。

---

## 🙏 致谢

- [PySide6](https://doc.qt.io/qtforpython-6/) —— 现代化的 Qt for Python 绑定；
- [NVIDIA Management Library (NVML)](https://developer.nvidia.com/nvidia-management-library-nvml) —— 本机 GPU 数据源；
- [pyqtgraph](https://pyqtgraph.org/) —— 高性能实时绘图；
- [paramiko](https://www.paramiko.org/) —— 纯 Python SSH 实现；
- 所有 [Contributors](../../graphs/contributors) 与 Issue 反馈者。

---

<div align="center">

如果这个项目对你有帮助，欢迎 ⭐ **Star** 支持一下，也欢迎分享给身边需要的朋友！

**itgeeker-gpu-widgets** · Made with ❤️ for GPU enthusiasts

</div>