gpu-hot：用一条 docker run 把 NVIDIA 显卡指标搬到浏览器
🔥 Real-time NVIDIA GPU dashboard
秒懂
- 它是什么？
- gpu-hot 是一个自托管的 NVIDIA GPU 实时仪表盘，通过 NVML 采集指标，用 WebSocket 推给前端。本文拆解它的采集链路、hub 聚合模式、配置项，以及它在多节点场景下暴露出的取舍。
- 适合谁用？
- 适合已经在用 NVIDIA Container Toolkit、需要一块不依赖外部监控栈的显卡面板的团队，尤其是单机多卡或几台 GPU 服务器的小集群。不适合想替代 Prometheus 长期指标存储、或需要告警与权限体系的场景，gpu-hot 的定位是实时看板而不是时序数据库。
- 能商用吗？
- 可以。MIT 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
- 还在维护吗？
- 在维护。仓库最近一次提交在 22 天前。
- 用什么语言写的？
- 主要是 JavaScript（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月15日）和我们的分析，不构成法律意见。
开源项目深度解析
它解决的是「现在这块卡在干什么」这个问题
训练和推理任务跑起来之后，最常被问的一句话是显卡现在什么状态。nvidia-smi 能回答，但它是逐次快照，看趋势要反复敲命令；把 nvidia-smi 输出重定向到文件再画图，又得自己写采集和前端。gpu-hot 把这一段补齐：容器一跑，浏览器打开 1312 端口就是仪表盘。README 列出的指标覆盖利用率、温度、显存、功耗、风扇转速、时钟频率、PCIe 信息、P-State、降频状态、编解码会话数，基本对应 nvidia-smi 能给出的字段集合。目标用户是手里有几张到几十张 NVIDIA 卡、又不想为此引入一整套 Prometheus 加 Grafana 的工程师。项目用 MIT 许可，前端是 Chart.js，后端 Python，目录结构里 app.py 是 FastAPI 服务入口，core/monitor.py 负责 NVML 采集。
采集链路：NVML 轮询、WebSocket 推送、前端批量渲染
从仓库目录能还原出数据流。core/monitor.py 走 NVML 取显卡指标，core/metrics/collector.py 做采集，core/handlers.py 处理 WebSocket 连接，数据经 socket.io 推到前端。前端侧 static/js/socket-handlers.js 的注释写的是 WebSocket 加批量渲染，也就是不逐条消息触发 DOM 更新，而是攒一批再画，这对多卡机器很关键：十几张卡每 0.5 秒推一次，逐条重绘会直接把浏览器拖死。图表配置和生命周期分别在 chart-config.js 与 chart-manager.js，另有 chart-drawer.js 负责关联性抽屉。README 提到轮询在没有客户端连接时会自动暂停，空闲 CPU 占用接近零。这个设计比「一直采集、前端只是不显示」要干净，代价是重新打开页面时历史曲线会有一段空档，因为采集本身停了。
跑起来只需要一条命令，但有几个参数会改变行为
单机场景 README 给的命令是 docker run -d --gpus all -p 1312:1312 ghcr.io/psalias2006/gpu-hot:latest，然后打开 http://localhost:1312。前置条件是 Docker 加 NVIDIA Container Toolkit。真正需要留意的是几个环境变量。NVIDIA_VISIBLE_DEVICES=0,1 用来只暴露指定显卡，默认全部。NVIDIA_SMI=true 强制走 nvidia-smi 回退路径，README 明确说老显卡指标不出现时加这个。UPDATE_INTERVAL 默认 0.5 秒，控制 NVML 轮询间隔；NVIDIA_SMI_INTERVAL 默认 2.0 秒，是回退模式的间隔，两者分开说明官方也承认 nvidia-smi 解析比 NVML 慢。想看进程名要加 --init --pid=host，README 自己标注了这会让容器访问宿主机进程信息，属于权限上的让步。从源码构建则是 git clone 之后 docker-compose up --build。端口在 core/config.py 里写死为 PORT = 1312，改端口要动代码而不是环境变量，这一点在需要复用 1312 的机器上会有点别扭。
hub 模式：多节点聚合的收益与它没做的事
多机部署的写法是每个 GPU 服务器跑一个带 NODE_NAME=$(hostname) 的容器，再在一台不需要显卡的机器上用 GPU_HOT_MODE=hub 加 NODE_URLS=http://server1:1312,http://server2:1312 启动聚合端。对应代码是 core/hub.py 和 core/hub_handlers.py。这里有个结构性事实值得说清楚：hub 是通过 HTTP 去拉各节点的 /api/gpu-data，而不是节点主动上报。这意味着 hub 机器必须能直连每个节点的 1312 端口，README 的排查步骤也正是 curl http://node-ip:1312/api/gpu-data 加 sudo ufw allow 1312/tcp。节点数量上去之后，hub 的轮询压力是线性叠加的，而 NODE_URLS 是启动时读入的环境变量，节点列表变更要重建容器。对固定几台机器的场景够用，对弹性伸缩的集群就不合适了。
接口很薄，这是优点也是边界
HTTP 只有三个端点：GET / 返回仪表盘页面，GET /api/gpu-data 返回 JSON 指标快照，GET /api/version 返回版本与更新信息。WebSocket 走 /socket.io/，消息体里分三块：data.gpus 是每卡指标，data.processes 是活跃 GPU 进程，data.system 是宿主机的 CPU、内存、swap、磁盘、网络。这个接口面足够让 hub 模式成立，也足够让人写个脚本把数据转存到别处。但要注意 /api/gpu-data 是快照而不是历史查询接口，README 没有描述任何按时间范围取历史数据的端点，历史曲线只存在于浏览器内存里。想拿 gpu-hot 做容量分析或者事后复盘，得自己在外面接一层采集。
什么时候它不合适：几个具体的失败场景
第一个是长期留存。项目没有暴露时序存储，重启容器或者关掉页面，曲线就断了，而 README 里没有任何数据库或导出配置项。需要按周按月看显卡利用率趋势的团队，gpu-hot 只能当实时窗口用。第二个是多租户与权限。整个服务没有提到认证机制，任何人访问 1312 端口就能看到全部显卡指标和进程名，配合 --pid=host 还能看到宿主机进程信息，放在公网或者共享内网里要自己加反向代理做访问控制。第三个是告警。README 的功能列表里没有阈值告警、通知渠道这类内容，它不会在显卡温度异常时告诉你。第四个是超大规模。README 的功能项写的是 scale from 1 to 100+ GPUs，但 hub 的拉取式聚合在节点数量大、网络抖动时会明显吃力，而且没有提到任何重试或缓存策略。如果需求是这几项中的任意一项，应该去找 Prometheus 加 DCGM Exporter 那条路线，它把指标暴露成 /metrics 端点由 Prometheus 主动抓取，存储、告警、查询语言都是现成的，代价是要维护整套监控栈和对应的配置。gpu-hot 与它的差别不在功能多少，而在数据是推送给人看还是被抓取供系统消费。
维护成本与许可
MIT 许可，商用和修改都没有额外约束，README 指向 LICENSE 文件，具体条款以仓库内文件为准，这里不做法律解读。维护节奏上，仓库最近三个版本是 v1.9.0、v1.9.1、v1.9.2，其中后两个发布于同一天，属于小步修修补补的形态，不是大版本重构。升级成本主要看容器镜像，默认用 ghcr.io/psalias2006/gpu-hot:latest 意味着拉取即更新，想控制版本就固定到具体 tag。真正会咬人的是前后端耦合：前端 JS 与后端 WebSocket 消息结构是一起演进的，如果你 fork 之后改了 data.gpus 的字段，得同步改 static/js 下的渲染逻辑，否则页面会静默地少显示东西。另外 core/config.py 里的 PORT 是代码级配置，多实例部署时要么改代码要么自己做端口映射。
编辑结论
适合已经在用 NVIDIA Container Toolkit、需要一块不依赖外部监控栈的显卡面板的团队，尤其是单机多卡或几台 GPU 服务器的小集群。不适合想替代 Prometheus 长期指标存储、或需要告警与权限体系的场景，gpu-hot 的定位是实时看板而不是时序数据库。落地前先确认三件事：目标机器上 nvidia-smi 能正常输出、容器内 --gpus all 能拿到设备、hub 机器到各节点的 1312 端口可通（README 给的排查命令是 curl http://node-ip:1312/api/gpu-data）。如果显卡较老导致指标为空，再加 NVIDIA_SMI=true 走 nvidia-smi 回退路径。
社区笔记