第2章：NVMe命令行工具：安装和基本使用（nvme-cli）
说白了，这一章就是大家上手的第一个实操课。我刚开始搞NVMe性能测试那会儿，没有图形工具可用，全是靠命令行敲出来的。nvme-cli就是这套工具里的瑞士军刀，免安装图形界面，纯命令操作，轻量且高效。安装它不复杂，但细节不少。我会把我在不同平台上遇到的坑一并讲清楚。你只要跟着我的步骤走，就能很快用上这套工具，顺便摸清设备的基本信息。
2.1 nvme-cli是什么
nvme-cli，全名NVMe Command Line Interface，是一个开源的工具集，专门用来管理NVMe存储设备。它能执行设备识别、错误日志查看、固件升级、性能监控等任务。性能测试里最常用的是它执行NVMe标准的管理命令，比如获取设备信息、检查健康状态、做格式化等等。
为什么要用这套工具？
- 直接操作设备：不依赖操作系统自带驱动的那种低效通信，直接通过NVMe驱动发命令。
- 全覆盖命令集：从最基础的identify到高级的directive，基本覆盖了NVMe规范里所有管理命令。
- 脚本友好：命令行输出是结构化文本，用awk、sed处理很方便，写自动化脚本时很顺手。
我记得刚开始做项目时，官方文档没有中文，全是英文字段，我一个个去对协议。现在大家学起来会轻松很多。
小提示：nvme-cli只是一个命令行工具，不负责做IO性能基准测试。做IO测试还得用fio、spdk等其他工具。但如果你不知道设备的具体参数，比如支持的队列数量和IO特性，那测试就没法精准设计。
2.2 安装nvme-cli
安装的方式取决于你的操作系统。我常用的几个环境，我会分开说。
2.2.1 在Linux上安装
Linux是nvme-cli的原生平台。我个人习惯用包管理器直接装，最省事。
# Ubuntu / Debian 系列
sudo apt-get update
sudo apt-get install nvme-cli
# CentOS / RHEL 系列
sudo yum install nvme-cli
# Fedora 系列
sudo dnf install nvme-cli
# openSUSE 系列
sudo zypper install nvme-cli如果你需要最新版本或定制功能，还可以从源码编译安装。我建议使用包管理器，省掉依赖问题。在项目现场时，也有Linux环境没有开启包管理器的，那你只能手动编译。
git clone https://github.com/linux-nvme/nvme-cli.git
cd nvme-cli
make
sudo make install注意：多数发行版的官方源版本落后于GitHub上的最新版。但除非你需要新增加的命令，否则稳定版也够用。我曾经在某个老版本上编译，结果因为内核头文件版本不匹配而失败。嗯，如果你遇到错误，检查下内核头文件和libuuid-dev是否齐全。
2.2.2 在Windows上安装
Windows上我不常用nvme-cli，但确实有移植版本。我记得是通过nvmewin项目做的封装，你可以在GitHub找到release版本。下载exe文件后直接执行，或者用PowerShell调用。
不过，如果你的测试目标是Windows平台的NVMe驱动和存储栈，我强烈建议你用Windows自带的工具或者WinDbg配合专用驱动。nvme-cli在Windows下更像一个备用方案，功能不如Linux下完整。
2.2.3 在macOS上安装
macOS可以直接用Homebrew安装，非常方便。我在笔记本上做过一次端到端验证，过程如下：
brew install nvme-cli但提醒一下，macOS对NVMe设备的用户态操作权限严格，你可能需要以root用户运行。我曾经试过一个系统更新后，某些命令因为SIP（系统完整性保护）而失败。实在不行，可以关掉SIP或签一个特权工具。
2.3 基本命令使用
工具装好了，我们就开始实战。首先得确认机器上有没有NVMe设备。拿Linux为例：
sudo nvme list它会列出所有可识别的NVMe设备。比如输出像这样：
Node SN Model Version Namespace Usage Format FW Rev
---------------- -------------------- ---------------------------------------- -------- ----------------------- ---------------------- -------------
/dev/nvme0n1 S5A7NG0N123456 Samsung SSD 970 EVO Plus 2TB 1.3 1 200.04 GB / 2.00 TB 4 KiB + 0 B 1B2QEXM7
/dev/nvme1n1 1946E3B6700C WDC WDS500G3X0C-00SJG0 1.3 1 500.11 GB / 500.11 GB 4 KiB + 0 B 102000WD拿到设备后，最核心的操作就是获取设备详细信息。用identify命令：
sudo nvme id-ctrl /dev/nvme0输出的内容很丰富：控制器版本号、支持的IO命令集、队列数量、最大数据传输大小等。拿队列数量来说：如果你测队列深度（QD）1的随机IO，后面就要参照这里的最大值来设计实验。我遇到好几次同事设计的队列深度超过了设备限制，导致测试结果不对，查了半天才发现是参数配错了。
除了identify，还有一个命令特别常用——获取设备健康信息：
sudo nvme smart-log /dev/nvme0输出包括：可用空间百分比、温度、写入量、读取量、坏块数、media error次数等。我原先在排查测试结果异常时，会先跑smart-log，看看设备的累计写入量和温度。有时候跑了一个小时的测试，发现设备温度飙到80度以上，嗯，那就要先解决散热，否则测出来的数据不准确。
实战注意点：
- 执行所有nvme命令行都需要root权限（在Linux上加上sudo，在Windows上以管理员身份运行）。
- 最好不要在生产环境设备上乱试format或sanitize命令，会丢掉所有数据。我个人只在专门的测试盘上做这些危险操作。
- 不同NVMe固件支持的命令可能有差异。如果某个命令返回不支持的错误码，你可以查下设备手册或更新固件。
2.4 常用命令速查
这里我整理了一个常用命令表，你可作为速查使用。
| 命令 | 功能说明 | 示例 |
|---|---|---|
nvme list |
列出所有NVMe设备 | sudo nvme list |
nvme id-ctrl |
获取控制器详细信息 | sudo nvme id-ctrl /dev/nvme0 |
nvme smart-log |
获取健康状态日志 | sudo nvme smart-log /dev/nvme0 |
nvme error-log |
获取设备错误日志 | sudo nvme error-log /dev/nvme0 |
nvme format |
对命名空间进行格式化（毁数据，务必谨慎！） | sudo nvme format /dev/nvme0n1 |
nvme sanitize |
安全擦除所有数据（更彻底） | sudo nvme sanitize /dev/nvme0n1 |
nvme fw-download + fw-activate |
固件下载和激活 | sudo nvme fw-download /path/to/fw.bin → sudo nvme fw-activate /dev/nvme0 --slot=1 --action=1 |
nvme get-feature |
读取指定特性寄存器（如电源管理、中断聚合等） | sudo nvme get-feature /dev/nvme0 -f 0x0a |
技巧：获取到控制器信息后，重点关注nn（命名空间数量）、sqes（提交队列大小）和cqes（完成队列大小）。这些参数直接影响你做IO测试时的性能上限。
2.5 本章知识体系
为了帮你更直观地理解本章的结构，我绘制了一张框架图。从安装到基本命令，再到实战验证，形成一个闭环。
这个框架已经涵盖了从零搭建nvme-cli环境的整个过程。你只要照着这个顺序走，基本不会有遗漏。
2.6 避坑指南
我在项目里遇到过一些典型的坑，这里列出来给大家提个醒：
- 设备未显示在list中：检查一下是不是内核驱动没正确加载，或者设备没插牢。我就在一次测试中发现NVMe盘没被识别，后来发现是PCIe槽接触不良。
- 命令返回错误码-1：一般是因为设备不支持该命令。比如老款NVMe硬盘不支持某些特性，或者命名空间个数超出。这时你先看看设备手册。
- 权限问题：千万别忘记sudo，否则得到的是“Permission denied”或空输出。我曾经犯了低级错误，折腾了好久。
- 千万别在系统盘上执行format：有一次同事在生产环境上误操作了format，结果数据全丢了，最后只能从头重建。所以，我建议你在测试前，仔细确认设备节点名。
警告：format和sanitize命令相当于白纸重画。如果你不确定当前操作的是哪块盘，先执行nvme list确认设备型号和序列号，核对后再操作。
到现在为止，nvme-cli的安装和基本使用应该已经清楚了。下一阶段我们就可以用这个工具跑简单的命令，逐步加深对NVMe设备的认识。