企业官网建设流程全解析

• 可观测性
• 指标监控

本文基于仓库内的 docs/INSTALL.md 整理并深化，覆盖 nvidia_gpu_exporter 在 Linux、Docker、Kubernetes、Windows 与 macOS 上的全部官方安装方式，并结合源码（systemd 单元、Dockerfile、Windows 服务入口、CLI 参数定义、发布脚本）说明每种方式背后实际发生的事情。读完后你可以按自己的平台选择安装路径完成部署，并会用 cosign、gh attestation 等工具验证下载产物的真实来源与可复现性。

安装前的前提条件

导出器（exporter）的运行依赖两点：

• 被监控机器上安装了 NVIDIA 驱动，并且能成功运行nvidia-smi。只要nvidia-smi能打印出你的 GPU，导出器就能工作；
• 例外是-nvml版本（flavor）：它直接读取驱动库libnvidia-ml，不需要nvidia-smi。该版本目前仅存在于 Linux x86_64，以独立压缩包和-nvml镜像 tag 两种形式提供。其能力边界参见 CONFIGURE.md 的 “Experimental: native NVML backend” 一节。

安装完成后，导出器默认监听9835端口，并在/metrics路径提供指标。验证方式：

curl http://localhost:9835/metrics

从 internal/app/app.go 的命令行定义可以确认这些默认值：webflag.AddFlags(app, ":9835")给出--web.listen-address默认值:9835，--web.telemetry-path默认/metrics，采集后端由--collect.backend选择，枚举值为exec（默认，运行 nvidia-smi）、nvml（实验性，直接读驱动库）和demo（合成数据，无需 GPU）。

安装示例中会出现latest与X.Y.Z占位符。生产环境务必固定到具体的 release 版本号，让升级成为一个有意识的动作。

Linux 安装

官方提供 x86_64 与 arm64 两种构建，按场景三选一：

deb 与 rpm 包

从项目 releases 下载对应架构的包并安装：

# Debian、Ubuntu 及衍生发行版 sudo dpkg -i nvidia-gpu-exporter_X.Y.Z_linux_amd64.deb # Fedora、RHEL、Rocky、openSUSE 及衍生发行版 sudo rpm -i nvidia-gpu-exporter_X.Y.Z_linux_amd64.rpm

包会做四件事：把二进制放到/usr/bin、创建名为nvidia_gpu_exporter的系统用户、安装 systemd 单元、以开机自启方式启动服务。检查状态：

systemctl status nvidia_gpu_exporter

从仓库的打包脚本可以印证这些行为：

• install/scripts/pre-install.sh 用ps --no-headers -o comm 1检查 PID 1 是否为systemd，否则直接报错退出——这就是“包只支持 systemd”的硬性实现；
• install/scripts/post-install.sh 执行useradd -r nvidia_gpu_exporter -s /bin/false、systemctl daemon-reload，然后enable+restart服务。

如果你的发行版使用其他 init 系统，请改用纯二进制方式。

纯二进制

1. 从 releases 下载对应架构的压缩包；
2. 解压；
3. 把二进制移动到PATH中的位置。

以 x86_64 为例（arm64 压缩包名为nvidia_gpu_exporter_${VERSION}_linux_arm64.tar.gz）：

# 从 releases 页面挑选一个版本 VERSION=X.Y.Z wget https://github.com/utkuozdemir/nvidia_gpu_exporter/releases/download/v${VERSION}/nvidia_gpu_exporter_${VERSION}_linux_x86_64.tar.gz tar -xvzf nvidia_gpu_exporter_${VERSION}_linux_x86_64.tar.gz sudo mv nvidia_gpu_exporter /usr/bin nvidia_gpu_exporter --help

x86_64 的 release 还会附带nvidia_gpu_exporter-nvml_*压缩包：同一个导出器，但编译并默认启用了实验性 NVML 后端，因此无需nvidia-smi。该后端的细节与限制见 CONFIGURE.md。

常用命令行参数（默认值取自 internal/app/app.go 的 flag 定义）：

不使用包的 systemd 服务

以下步骤就是 deb/rpm 包替你做的事：

1. 按上一节把二进制放到/usr/bin；

2. 创建系统用户：

   sudo useradd --system --no-create-home --shell /usr/sbin/nologin nvidia_gpu_exporter

3. 把 install/systemd/nvidia_gpu_exporter.service 复制到/etc/systemd/system/；

4. 重载并开机自启：

   sudo systemctl daemon-reload sudo systemctl enable --now nvidia_gpu_exporter

单元文件本身很简洁（见 install/systemd/nvidia_gpu_exporter.service）：User=/Group=nvidia_gpu_exporter、ExecStart=/usr/bin/nvidia_gpu_exporter、Restart=always且RestartSec=1，安装在multi-user.target下，日志通过SyslogIdentifier=nvidia_gpu_exporter归入 syslog。

Docker 安装

镜像不捆绑任何 NVIDIA 组件。NVIDIA Container Toolkit 会在容器启动时注入与宿主机驱动匹配的 GPU 设备、驱动库和nvidia-smi二进制。这样同一个镜像可以适配任意驱动版本、任意数量 GPU、任意 CPU 架构。

前提：

• 宿主机安装 NVIDIA 驱动；
• 宿主机安装并配置好面向 Docker 的 NVIDIA Container Toolkit。

然后运行：

docker run -d \ --name nvidia_gpu_exporter \ --restart unless-stopped \ --gpus all \ -e NVIDIA_DRIVER_CAPABILITIES=utility \ -p 9835:9835 \ utkuozdemir/nvidia_gpu_exporter:latest

• 容器以 uid 65534（nobody）而非 root 运行。GPU 访问不需要 root。仓库 Dockerfile 中写的是数字USER 65534:65534而不是USER nobody，注释说明了原因：kubelet 无法基于名字校验runAsNonRoot，名字形式的用户会导致要求该检查的 Pod 拒绝启动；
• --gpus all打开 Docker 的 NVIDIA 集成并暴露全部 GPU；
• NVIDIA_DRIVER_CAPABILITIES=utility声明容器只需要nvidia-smi/NVML 层。新版 Toolkit 无论如何都会注入完整的驱动用户态组件，所以把它当作“意图声明”和对旧环境的兼容处理，而不是限制。

镜像发布在 Docker Hub（utkuozdemir/nvidia_gpu_exporter）和 GHCR（ghcr.io/utkuozdemir/nvidia_gpu_exporter），两边 tag 相同。想试用实验性 NVML 后端，用-nvmltag（如utkuozdemir/nvidia_gpu_exporter:latest-nvml）。

Docker Compose

services: nvidia_gpu_exporter: image: utkuozdemir/nvidia_gpu_exporter:latest restart: unless-stopped environment: - NVIDIA_DRIVER_CAPABILITIES=utility ports: - "9835:9835" deploy: resources: reservations: devices: - driver: nvidia count: all capabilities: [gpu]

如果你的环境不支持设备预留语法，改为在服务上设置runtime: nvidia，并在 environment 中追加NVIDIA_VISIBLE_DEVICES=all。

重要：NVIDIA_*环境变量只是配置NVIDIA runtime，并不会选择它。没有--gpus、设备预留或runtime: nvidia时，容器跑在默认 runtime 上，拿不到任何 GPU。此时导出器仍会启动，但只输出自身健康指标，且nvidia_smi_last_collect_success 0。

镜像里没有 shell

官方镜像基于 distroless（Dockerfile 使用gcr.io/distroless/base-nossl-debian13），只包含导出器二进制和最小运行时——没有 shell、没有包管理器。这让它体积很小、扫描结果接近零。

代价是没有 shell 可以docker exec进去，基于它派生的镜像也不能在RUN里执行 shell 命令。但运行镜像中已存在的二进制依然可行，例如docker exec <container> nvidia-smi可以验证驱动注入是否生效。

如果需要和导出器并排放置额外工具（例如为--nvidia-smi-command准备包装脚本），从一个更完整的基底镜像复制二进制：

FROM debian:stable-slim COPY --from=utkuozdemir/nvidia_gpu_exporter:latest /usr/bin/nvidia_gpu_exporter /usr/bin/ ENTRYPOINT ["/usr/bin/nvidia_gpu_exporter"]

这样构建的包装镜像会以基底镜像的默认用户（debian即 root）运行，不再保持 uid 65534，需要自行配置用户、home 与sudo/ssh。只有直接FROM官方镜像才保留 65534。若给包装镜像自定义非 rootUSER，请保持数字形式——Kubernetes 无法基于名字校验runAsNonRoot，会拒绝启动这样的容器。

以-nvml变体派生时，还要带过它的NVIDIA_VISIBLE_DEVICES=all和NVIDIA_DRIVER_CAPABILITIES=utility两个环境变量——正是它们让 NVIDIA runtime 在容器 spec 未设置任何NVIDIA_*变量时注入驱动库。缺失时导出器会在启动阶段以“找不到库”报错退出。

没有 NVIDIA Container Toolkit 的宿主机

Toolkit 装不上时，可以手动把必要部件挂载进容器：

• 每个/dev/nvidia*设备；
• nvidia-smi二进制；
• 宿主机库目录中的libnvidia-ml.so*库文件。

库要挂进容器的默认库目录（amd64 为/usr/lib/x86_64-linux-gnu，arm64 为/usr/lib/aarch64-linux-gnu），因为镜像里没有ldconfig去注册其他位置；或者把LD_LIBRARY_PATH指到你选的目录。

这种方式很脆弱：驱动升级会弄断库的符号链接链、设备清单随 GPU 数量变化、库路径因发行版和架构而异。可能时请优先用 Toolkit。

无论用哪种机制注入设备，容器里的 uid 65534 都必须能读取它们。驱动默认把/dev/nvidia*创建为全员可访问，所以直接可用；如果宿主机收紧了权限（NVreg_DeviceFileMode模块参数、udev 规则等），表现为nvidia_smi_last_collect_success 0。解决办法：放宽设备权限、用--group-add加入属组，或者以--user 0运行容器。

Kubernetes 安装

导出器以 DaemonSet 形式运行在 NVIDIA runtime 上，runtime 会在每个节点注入 GPU 访问，机制与上面 Docker 部分相同。

重要：不要给导出器申请nvidia.com/gpu资源。设备插件是按整卡独占分配的，监控 Pod 一旦申请，就会把那块 GPU 从真实工作负载手里拿走。下文的NVIDIA_*环境变量方式让导出器看到节点上所有 GPU，却不预留任何一块。

节点需要 NVIDIA 驱动和面向容器运行时配置的 NVIDIA Container Toolkit。托管 GPU 节点镜像（AKS、GKE、EKS）通常两者齐全。自管理 containerd 节点（含 k3s）需要自行安装 Toolkit，并把 NVIDIA runtime 设为默认，或创建一个名为nvidia的RuntimeClass如下引用。

Helm chart

仓库内的 charts/nvidia-gpu-exporter 实现了上文全部要点，以 OCI 方式发布：

helm install nvidia-gpu-exporter oci://ghcr.io/utkuozdemir/charts/nvidia-gpu-exporter \ --set runtimeClassName=nvidia

完整的 values 参考、可选的监控组件（ServiceMonitor、PodMonitor、告警规则、Grafana 仪表盘）与从旧 chart 仓库迁移的说明，见 chart README。几个核心 values（取自 charts/nvidia-gpu-exporter/values.yaml）：

chart 默认还配置了指向/-/healthy与/-/ready的存活/就绪探针——检查的是进程级 HTTP 可达性，刻意不依赖采集成功，这样 nvidia-smi 故障时 Pod 依然可被抓取，失败本身通过指标可见。

裸 DaemonSet

不想用 Helm 时，最小 DaemonSet 如下。在强制执行restrictedPod Security Standard 的命名空间中，请补齐 chart 默认设置的 security contexts（见 chart README 的 restricted namespaces 一节）：

apiVersion: apps/v1 kind: DaemonSet metadata: name: nvidia-gpu-exporter spec: selector: matchLabels: app: nvidia-gpu-exporter template: metadata: labels: app: nvidia-gpu-exporter spec: runtimeClassName: nvidia # 若 NVIDIA runtime 已是集群默认，可省略 containers: - name: exporter image: utkuozdemir/nvidia_gpu_exporter:latest # 生产请固定 release tag env: - name: NVIDIA_VISIBLE_DEVICES value: all - name: NVIDIA_DRIVER_CAPABILITIES value: utility ports: - containerPort: 9835 name: metrics

托管 Kubernetes（AKS 等）

托管 K8s 的 GPU 节点镜像随节点自带驱动与容器 Toolkit，上面的 DaemonSet 可直接工作。nvidia.com/gpu资源与 NVIDIA 设备插件是为调度 GPU 工作负载而存在的；导出器刻意游离于该机制之外，因为它只需要“观察”GPU。整数分配、一卡一工作负载这类配额约束适用于你的工作负载，但永远不适用于导出器。

Windows 安装

Windows 只有 x86_64 构建。还没有 Prometheus 和 Grafana 时，用下面的 all-in-one 脚本三件套一次装齐；已有监控栈时，用 winget 或 Scoop 单独装导出器并注册为服务。

All-in-one 脚本

install/windows-all-in-one.ps1 会在同一台机器上安装导出器、Prometheus 与 Grafana，并预置好数据源和仪表盘。脚本头部注释说明了分工：导出器自身实现 Windows 服务控制管理器协议无需包装；Grafana 的 MSI（经 winget 安装）自带服务；Prometheus 不自带服务支持，由 WinSW（脚本内固定为 v2.12.0 并做 sha256 校验）托管。

步骤：

1. 从仓库下载 install/windows-all-in-one.ps1，保存为.ps1；

2. 打开管理员 PowerShell（开始菜单搜索 PowerShell，右键“以管理员身份运行”）；

3. 由于默认策略会拦截下载来的脚本，本次运行旁路执行策略：

   powershell -NoProfile -ExecutionPolicy Bypass -File "C:\Users\<YOUR_USERNAME>\Downloads\windows-all-in-one.ps1"

4. 打开http://localhost:9090确认 Prometheus；

5. 打开http://localhost:3000确认 Grafana；

6. 用初始凭据admin/admin登录 Grafana，按需修改密码；

7. Prometheus 数据源与 “Nvidia GPU Metrics”“Nvidia GPU Overview” 两个仪表盘已就位，从仪表盘列表打开即可。

重复执行脚本是安全的：它把导出器更新到最新 release，并保留 Prometheus 数据与 Grafana 状态。

如果你是用早期版本脚本（基于 Scoop + NSSM）安装的，或想卸载脚本安装的全部内容，用同样方式运行 install/windows-all-in-one-uninstall.ps1。它移除服务和程序文件，但从不删除已采集的数据，并会打印被保留的位置。全新安装从空的 Prometheus 数据库开始，旧 Scoop 环境的数据不会迁移。

winget

winget install utkuozdemir.nvidia_gpu_exporter

装完即可在PATH中直接运行。若要注册为服务，请改用机器级安装（而非上面的用户级），保证服务账户能访问二进制且升级后路径稳定：

winget install --scope machine utkuozdemir.nvidia_gpu_exporter nvidia_gpu_exporter install

两种方式二选一，不要同时使用。

Scoop

没有 Scoop 的话先安装它（普通 PowerShell 即可）：

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser Invoke-Expression (New-Object System.Net.WebClient).DownloadString('https://get.scoop.sh')

然后从项目 bucket 安装。--global作用域保证路径在更新间稳定，这对以服务运行很重要：

scoop install git scoop bucket add nvidia_gpu_exporter https://github.com/utkuozdemir/scoop_nvidia_gpu_exporter.git scoop install nvidia_gpu_exporter/nvidia_gpu_exporter --global

二进制位于C:\ProgramData\scoop\apps\nvidia_gpu_exporter\current\nvidia_gpu_exporter.exe。

作为 Windows 服务运行

导出器自己实现了 Windows 服务控制管理器协议，用自己的install命令注册为普通 Windows 服务，无需 NSSM 之类的第三方包装。从 internal/app/app.go 和 Windows 入口 cmd/nvidia_gpu_exporter/service_windows.go 可以确认实现细节：dispatch()拦截install/uninstall子命令；被服务控制管理器启动时走runService()，通过svc.Run注册处理程序，把 Stop/Shutdown 请求翻译为 context 取消；日志通过一个slog.Handler（eventLogHandler）镜像到 Windows 事件日志的Application日志、source 为nvidia_gpu_exporter，且该镜像是尽力而为——事件日志 source 未注册时服务仍会启动而不是超时失败。

先通过 winget 或 Scoop 拿到二进制，或从 releases 下载 Windows 压缩包解压出nvidia_gpu_exporter.exe放到稳定位置（如C:\Program Files\nvidia_gpu_exporter\）。然后从管理员 PowerShell 执行：

# 注册服务：开机自启、失败自动重启。 # 若二进制不在 PATH，用完整路径，例如 Scoop 位置： # & 'C:\ProgramData\scoop\apps\nvidia_gpu_exporter\current\nvidia_gpu_exporter.exe' install nvidia_gpu_exporter install # 放行指标端口（限本地子网）。Prometheus 同机抓取时回环不受防火墙限制，可跳过； # Prometheus 在其他子网时去掉 -RemoteAddress 或放宽范围 New-NetFirewallRule -DisplayName "Nvidia GPU Exporter" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 9835 -Profile Private,Domain -RemoteAddress LocalSubnet # 启动 Start-Service nvidia_gpu_exporter

传给install的任何 flag 都会固化进服务命令行，因此配置服务与交互式运行完全一致。不带 flag 时监听:9835。例如换端口：

nvidia_gpu_exporter install --web.listen-address=:9836

重复执行install会就地重配置已有服务，改 flag 无需先卸载；改完后Restart-Service nvidia_gpu_exporter让新命令行生效。

管理与移除：

# 状态、停止、启动 Get-Service nvidia_gpu_exporter Stop-Service nvidia_gpu_exporter Start-Service nvidia_gpu_exporter # 卸载服务（先停止）。不在 PATH 时用完整路径，例如 .\nvidia_gpu_exporter.exe uninstall Stop-Service nvidia_gpu_exporter nvidia_gpu_exporter uninstall # 如添加过防火墙规则，一并移除 Remove-NetFirewallRule -DisplayName "Nvidia GPU Exporter"

之后用winget uninstall utkuozdemir.nvidia_gpu_exporter或scoop uninstall nvidia_gpu_exporter --global（与安装时相同的--global作用域）移除二进制。

早期文档使用 NSSM 运行服务。若当时这样装了，先在管理员 PowerShell 中删除旧服务再按上面步骤操作：

Stop-Service nvidia_gpu_exporter nssm remove nvidia_gpu_exporter confirm

NSSM 已不再需要，机器上若无其他用途可用scoop uninstall nssm一并移除。

macOS 安装

从 releases 下载darwin_x86_64压缩包，解压后把二进制放进PATH。只有 Intel 构建，Apple Silicon 通过 Rosetta 运行。

Mac 通常没有 NVIDIA GPU，所以 macOS 上的典型用法是远程抓取：导出器跑在 Mac 上，通过 SSH 在另一台机器上执行nvidia-smi。配置方法见 CONFIGURE.md 的 Remote scraping 一节（对应--nvidia-smi-command参数）。

验证你下载的内容

发布流水线产出的所有内容都经过签名，可以核实文件或镜像确实来自本项目的发布工作流。签名是无密钥（Sigstore）签名：它们绑定的是发布工作流的身份，即下面各命令实际校验的对象。例外是 Helm chart 的经典仓库，Helm 只能校验 GPG provenance。

Release 压缩包与安装包

每个 release 附带checksums.txt（所有二进制、压缩包、包的 sha256）和覆盖它的签名包checksums.txt.sigstore.json。先用 cosign v3+ 验签名，再核对下载物的校验和：

cosign verify-blob checksums.txt \ --bundle checksums.txt.sigstore.json \ --certificate-oidc-issuer=https://token.actions.githubusercontent.com \ --certificate-identity-regexp='^https://github\.com/utkuozdemir/nvidia_gpu_exporter/\.github/workflows/release\.yml@refs/tags/v.*$' && sha256sum --ignore-missing -c checksums.txt

&&保证签名校验失败时不会继续执行看似通过的校验和核对。macOS 上最后一行换成shasum -a 256 --ignore-missing -c checksums.txt。

较早的 release 没有checksums.txt.sigstore.json，而是附带用同一把（仍用于 chart provenance 签名的）密钥制作的分离式 GPG 签名checksums.txt.asc；导入密钥后核对两个文件即可。最早的 release 只有校验和文件：

curl -fsSL https://utkuozdemir.github.io/nvidia_gpu_exporter/pubkey.asc | gpg --import && gpg --verify checksums.txt.asc checksums.txt && sha256sum --ignore-missing -c checksums.txt

容器镜像

Docker Hub 与 GHCR 上的镜像用 cosign 做无密钥签名，替换VERSION为引入签名之后发布的 tag：

cosign verify \ --certificate-oidc-issuer=https://token.actions.githubusercontent.com \ --certificate-identity-regexp='^https://github\.com/utkuozdemir/nvidia_gpu_exporter/\.github/workflows/release\.yml@refs/tags/v.*$' \ utkuozdemir/nvidia_gpu_exporter:VERSION

Chart

chart 同样有签名：经典仓库是 GPG provenance，OCI 产物是 cosign。具体命令见 chart README。

构建溯源（build provenance）

checksums.txt列出的每个压缩包/包、每个镜像和 chart 还携带 GitHub 在发布工作流期间生成的构建溯源 attestation——一份签名声明，把产物的 digest 与本仓库、确切 commit、工作流和那次 run 绑定起来。它回答的问题与上面的签名不同：不只是“这是维护者的 release”，而是“这个产物是否由该工作流从那个 commit 构建而来”。

用 GitHub CLI 验证已下载的文件；两个附加 flag 把 attestation 钉死在发布工作流和 release tag 上，仓库里其他流程产生的 attestation 会被拒绝：

gh attestation verify nvidia_gpu_exporter_X.Y.Z_linux_x86_64.tar.gz \ --repo utkuozdemir/nvidia_gpu_exporter \ --signer-workflow github.com/utkuozdemir/nvidia_gpu_exporter/.github/workflows/release.yml \ --source-ref refs/tags/vX.Y.Z

镜像与 chart 按引用验证。注意chart 版本不等于应用版本：chart 主版本号是应用主版本号加一（charts/nvidia-gpu-exporter/Chart.yaml 的注释同样写明 “The chart major is the app major plus one”），例如应用1.14.0对应 chart2.14.0：

gh attestation verify oci://docker.io/utkuozdemir/nvidia_gpu_exporter:X.Y.Z \ --repo utkuozdemir/nvidia_gpu_exporter \ --signer-workflow github.com/utkuozdemir/nvidia_gpu_exporter/.github/workflows/release.yml \ --source-ref refs/tags/vX.Y.Z gh attestation verify oci://ghcr.io/utkuozdemir/charts/nvidia-gpu-exporter:CHART_VERSION \ --repo utkuozdemir/nvidia_gpu_exporter \ --signer-workflow github.com/utkuozdemir/nvidia_gpu_exporter/.github/workflows/release.yml \ --source-ref refs/tags/vX.Y.Z

输出会指明 commit 与工作流 run，可以回溯到源码和构建日志。checksums.txt本身没有 attestation，它由签名包覆盖。

复现一次发布

自 v1.15.1 起，release 文件是可复现构建：同一 commit 在任何机器上都能产出字节相同的二进制、压缩包和包。

一个例外：nvml 版本是 cgo 构建，二进制里带着构建机器的 C 编译器，只在匹配的工具链上可复现；发布 runner 是 Ubuntu 24.04 及其默认 GCC。

发布工作流会在第二台 runner 上从头重建每个 release，校验和不一致即失败。你也可以做同样的事：

1. 克隆仓库并检出 release tag；
2. 安装 go.mod 声明的 Go 版本（当前为go 1.27.2）和 hack/dev.Dockerfile 中固定的 goreleaser 版本（GORELEASER_VERSION行，当前v2.18.2）；
3. 构建但不发布，然后比对：

PRIVATE_ACCESS_TOKEN=placeholder goreleaser release --clean --skip=publish,sign,sbom,docker,announce diff dist/checksums.txt <(curl -fsSL https://github.com/utkuozdemir/nvidia_gpu_exporter/releases/download/vX.Y.Z/checksums.txt)

diff 为空即表示你构建的每个文件与发布的产物逐字节一致。使用其他 C 工具链的机器上，会有差异的恰好是 nvml 压缩包那一行。容器镜像同样可复现；比较镜像需要推送到一个 registry，方法见 AGENTS.md。

• 可观测性
• 指标监控