Nomad 常用 CLI 命令详解

目标：系统梳理 Nomad 2.0.7 的全部常用命令与参数，逐条给出真实执行命令与回显，覆盖全局选项、agent、server、client、job、alloc、node、volume、config、operator 等命令族。所有命令、参数与回显均以 Ubuntu 22.04 + Nomad 2.0.7 与真实集群（3 server + 2 client）的 --help 输出和实测为准。

一、环境信息

操作系统：Ubuntu 22.04 LTS（x86_64）
Nomad 版本：2.0.7（Client 与 Server 同版本）
集群：3 台 Server（server1/2/3.example.com）+ 2 台 Client
服务地址：默认 http://127.0.0.1:4646（可用 -address 或 NOMAD_ADDR 覆盖）
默认 namespace：default；区域 global；数据中心 dc1

二、工具概览

nomad 是单一二进制 CLI，命令按用途分层：

顶层通用：agent、run、stop、status、alloc、job、node、server、volume、eval、deployment、operator
job 编排：nomad job run/plan/stop/status/allocs/validate/inspect/history/revert/scale/dispatch
分配与日志：nomad alloc status/logs/exec/fs/restart/stop/signal
节点运维：nomad node status/drain/eligibility/meta/pool
集群与配置：nomad server members/join/force-leave、nomad config validate、nomad operator raft
辅助：nomad version、nomad agent-info、nomad monitor、nomad var、nomad fmt

💡 命令规范：所有子命令共享一组 General Options（地址、区域、命名空间、TLS、token），并各自带专属 Options。

三、前置条件

已安装并有正在运行的 Nomad agent（Server 或 Client），见《Nomad 安装指南》
CLI 可通过 4646 端口访问 server；多集群用 -address 指定远程 server

四、nomad 顶层命令与全局选项

4.1 `nomad --help`（命令全景）

nomad --help

执行结果（完整）：

Usage: nomad [-version] [-help] [-autocomplete-(un)install] <command> [args]

Common commands:
    run         Run a new job or update an existing job
    stop        Stop a running job
    status      Display the status output for a resource
    alloc       Interact with allocations
    job         Interact with jobs
    node        Interact with nodes
    agent       Runs a Nomad agent

Other commands:
    acl                 Interact with ACL policies and tokens
    action              Run a pre-defined command from a given context
    agent-info          Display status information about the local agent
    config              Interact with configurations
    deployment          Interact with deployments
    eval                Interact with evaluations
    exec                Execute commands in task
    fmt                 Rewrites Nomad config and job files to canonical format
    license             Interact with Nomad Enterprise License
    login               Login to Nomad using an auth method
    monitor             Stream logs from a Nomad agent
    namespace           Interact with namespaces
    operator            Provides cluster-level tools for Nomad operators
    plugin              Inspect plugins
    quota               Interact with quotas
    recommendation      Interact with the Nomad recommendation endpoint
    scaling             Interact with the Nomad scaling endpoint
    sentinel            Interact with Sentinel policies
    server              Interact with servers
    service             Interact with registered services
    setup               Interact with setup helpers
    start               Start a stopped job
    system              Interact with the system API
    tls                 Generate Self Signed TLS Certificates for Nomad
    ui                  Open the Nomad Web UI
    var                 Interact with variables
    version             Prints the Nomad version
    volume              Interact with volumes

4.2 版本命令

nomad version

执行结果：

Nomad v2.0.7
BuildDate 2026-09-17T17:24:03Z
Revision 9dcbdc5e64ecc4ec63e42b225af729c87c87cf83

4.3 全局/通用选项（所有子命令共享）

每个子命令都自带以下 General Options（实测 nomad job run --help 等输出一致）：

选项	默认值	说明
`-address=<addr>`	`http://127.0.0.1:4646`	Nomad server 地址，覆盖 `NOMAD_ADDR`
`-region=<region>`	Agent 本地区域	区域，覆盖 `NOMAD_REGION`
`-namespace=<ns>`	`default`	命名空间，覆盖 `NOMAD_NAMESPACE`
`-no-color`	false	禁用彩色输出
`-force-color`	false	强制彩色输出
`-ca-cert=<path>`	系统信任	服务端 TLS 校验 CA 证书，覆盖 `NOMAD_CACERT`
`-ca-path=<path>`	—	CA 证书目录，覆盖 `NOMAD_CAPATH`
`-client-cert=<path>`	—	TLS 客户端证书（需配合 `-client-key`）
`-client-key=<path>`	—	TLS 客户端私钥
`-tls-server-name=<val>`	—	TLS SNI 名称，覆盖 `NOMAD_TLS_SERVER_NAME`
`-tls-skip-verify`	false	跳过 TLS 校验（高危，不推荐）
`-token`	—	ACL token，覆盖 `NOMAD_TOKEN`

五、nomad agent——启动与配置

5.1 `nomad agent --help`（关键选项）

nomad agent --help

执行结果（关键段）：

General Options (clients and servers):
  -bind=<addr>            The address the agent will bind to … Defaults to the loopback 127.0.0.1.
  -config=<path>          The path to either a single config file or a directory … merged together.
  -data-dir=<path>        The data directory used to store state and other persistent data.
  -plugin-dir=<path>      The plugin directory … defaults to <data-dir>/plugins/.
  -dc=<datacenter>        The name of the datacenter … default "dc1".
  -log-level=<level>      DEBUG, INFO, WARN … default is INFO.
  -log-json               Output logs in a JSON format. default false.
  -node=<name>            The name of the local agent … default is the hostname.
  -region=<region>        … default "global".
  -dev                    Start the agent in development mode (pre-configured client+server).

Server Options:
  -server                 Enable server mode.
  -bootstrap-expect=<num> Expected number of server nodes before bootstrapping.
  -encrypt=<key>          Provides the gossip encryption key.
  -join=<address>         Address of an agent to join at start time.
  -retry-join=<address>   Address of an agent to join with retries. Can be specified multiple times.
  -retry-max=<num>        Maximum join attempts. Defaults to 0 (retry indefinitely).
  -retry-interval=<dur>   Time to wait between join attempts.
  -rejoin                 Ignore a previous leave and rejoin the cluster.

Client Options:
  -client                 Enable client mode.
  -servers                A list of known server addresses given as "host:port" delimited by commas.
  -node-class             Mark this node as a member of a node-class.
  -node-pool              Register this node in this node pool.
  -meta                   User specified metadata KEY=VALUE per instance.
  -network-interface      Forces the network fingerprinter to use the specified interface.
  -preferred-address-family   Which IP family to prefer (ipv4|ipv6).

选项	默认值	说明
`-bind`	`127.0.0.1`	所有网络服务绑定的地址（生产 0.0.0.0）
`-data-dir`	`<数据路径>`	状态与持久化数据目录
`-dc`	`dc1`	数据中心
`-region`	`global`	区域
`-log-level`	`INFO`	日志级别 DEBUG/INFO/WARN
`-bootstrap-expect`	0	server 期望数量
`-retry-max`	0	重试加入次数，0 表示无限重试
`-servers`	空	client 连接的 server 列表

启动示例：

nomad agent -config /etc/nomad.d -log-level INFO
nomad agent -server -bootstrap-expect 3 -data-dir /opt/data/nomad -bind 0.0.0.0
nomad agent -client -servers server1.example.com:4647 -data-dir /opt/data/nomad

5.2 `nomad agent-info`——本地 agent 状态

nomad agent-info | head -18

执行结果：

nomad
  bootstrap = true
  known_regions = 1
  leader = true
  leader_addr = 172.16.0.10:4647
  server = true
raft
  applied_index = 9
  commit_index = 9
  fsm_pending = 0
  last_contact = 0
  last_log_index = 9
  last_log_term = 3
  last_snapshot_index = 0
  last_snapshot_term = 0

💡 leader/leader_addr 判断本 server 是否 leader；raft 段反映 Raft 复制水位（applied/commit/last_log_index 一致即追平）。

六、nomad server——集群成员管理

6.1 `nomad server members`（列出成员）

nomad server members

执行结果：

Name                        Address     Port  Status  Leader  Raft Version  Build  Datacenter  Region
server1.example.com.global  172.30.0.2  4648  alive   false   3             2.0.7  dc1         global
server2.example.com.global  172.30.0.3  4648  alive   false   3             2.0.7  dc1         global
server3.example.com.global  172.30.0.4  4648  alive   true    3             2.0.7  dc1         global

server members 独有选项：

选项	说明
`-verbose`	显示每个成员的原始 tag（expect/role/raft 版本/rpc_addr 等）
`-ui`	在浏览器打开 server 页面
`-json`	JSON 输出成员信息
`-t`	Go 模板格式化输出

nomad server members -verbose

执行结果（标签段节选）：

server1.example.com.global  172.30.0.2  4648  alive  false  …  dc=dc1,expect=3,port=4647,role=nomad,region=global,raft_vsn=3,build=2.0.7,rpc_addr=172.30.0.2

6.2 `nomad server join` / `force-leave`

nomad server join server2.example.com:4647     # 把本节点 join 到指定 server
nomad server force-leave server2.example.com.global   # 强制某成员进入 left 状态

七、nomad node——节点状态与运维

7.1 `nomad node status`（节点列表/详情）

nomad node status

执行结果：

ID        Node Pool  DC   Name                 Class         Drain  Eligibility  Status
0c531868  default    dc1  client1.example.com  linux-docker  false  eligible     ready
b9b8a77e  default    dc1  client2.example.com  linux-docker  false  eligible     ready

node status 独有选项：

选项	说明
`-self`	查询本机节点
`-stats`	显示详细资源使用统计
`-allocs`	显示每个节点的运行分配数
`-short`	精简输出
`-verbose`	完整信息（含完整 node id / address / version）
`-os`	显示操作系统名
`-filter`	表达式过滤结果
`-json` / `-t`	JSON / 模板输出
`-quiet`	只输出节点 ID

nomad node status -self -verbose
nomad node status -stats b9b8a77e

7.2 `nomad node drain`（排空节点）

nomad node drain -enable -deadline 10m -yes 0c531868

执行结果：

2026-10-09T09:20:19Z: Node "0c531868…" drain strategy set
2026-10-09T09:20:20Z: Alloc "32bc310a…" marked for migration
2026-10-09T09:20:22Z: Alloc "32bc310a…" status running -> complete
2026-10-09T09:20:22Z: Drain complete for node 0c531868-…

drain 独有选项：

选项	说明
`-enable` / `-disable`	启用/取消排空（二选一必选）
`-deadline <duration>`	排空宽限，默认 1 小时，超时强制移除
`-force`	立即强制移除全部分配
`-no-deadline`	无截止时间，不强制停止
`-ignore-system`	排空时不停 system 类 job 分配
`-keep-ineligible`	取消排空后仍保持不可调度
`-self`	对本节点操作
`-detach` / `-monitor`	立即返回 / 直接进入监控
`-m` / `-meta`	排空消息 / 自定义元数据
`-yes`	自动确认

nomad node drain -disable -yes 0c531868

执行结果：

Node "0c531868-…" drain strategy unset

7.3 `nomad node eligibility`（调度开关）

nomad node eligibility -disable b9b8a77e   # 本节点不再放置新任务（存量保留）
nomad node eligibility -enable  b9b8a77e   # 恢复可调度

💡 -disable 只停新分配调度，不迁移存量；要连存量一起迁走需 node drain。

八、nomad job——任务生命周期

8.1 命令族总览

nomad job --help

执行结果（子命令清单）：

Subcommands:
    action            Run a pre-defined action from a Nomad task
    allocs            List allocations for a job
    deployments       List deployments for a job
    dispatch          Dispatch an instance of a parameterized job
    eval              Force an evaluation for the job
    history           Display all tracked versions of a job
    init              Create an example job file
    inspect           Inspect a submitted job
    periodic          Interact with periodic jobs
    plan              Dry-run a job update to determine its effects
    promote           Promote a job's canaries
    restart           Restart or reschedule allocations for a job
    revert            Revert to a prior version of the job
    run               Run a new job or update an existing job
    scale             Change the count of a Nomad job group
    scaling-events    Display the most recent scaling events for a job
    start             Start a stopped job
    status            Display status information about a job
    stop              Stop a running job
    tag               Manage job version tags
    validate          Checks if a given job specification is valid

8.2 `nomad job run`（运行/更新 job）

nomad job run /etc/nomad/web-demo.nomad

执行结果：

==> 2026-10-09T09:17:58Z: Monitoring evaluation "fe23c021"
    2026-10-09T09:17:58Z: Evaluation triggered by job "web-demo"
    2026-10-09T09:17:59Z: Allocation "24e22a20" created: node "b9b8a77e", group "web"
    2026-10-09T09:17:59Z: Evaluation status changed: "pending" -> "complete"
==> 2026-10-09T09:17:59Z: Evaluation "fe23c021" finished with status "complete"
==> 2026-10-09T09:17:59Z: Monitoring deployment "6c9e15a3"

job run 独有选项：

选项	说明
`-check-index`	校验 job modify index 一致才提交（并发安全），0 表示仅当不存在时注册
`-detach`	立即返回（不进入监控），打印 eval id
`-eval-priority`	覆盖本次 eval 优先级
`-json`	按 JSON 解析 job 文件
`-output`	只输出提交给 API 的 JSON 不实际提交
`-var 'k=v'` / `-var-file=path`	HCL2 模板变量
`-preserve-counts`	更新时保留现有 task group 数量
`-preserve-resources`	更新时保留现有资源

别名：nomad run（顶层别名）。退出码：0 成功；1 连接/内部错误；2 放置失败。

8.3 `nomad job plan`（干跑预演）

nomad job plan /etc/nomad/web-demo.nomad

执行结果：

+ Job: "web-demo"
+ Task Group: "web" (2 create)
  + Task: "echo" (forces create)

Scheduler dry-run:
- All tasks successfully allocated.

Job Modify Index: 0
To submit the job with version verification run:

nomad job run -check-index 0 /etc/nomad/web-demo.nomad

💡 退出码：0 无分配新增/销毁；1 有分配变化；255 无法预演。

8.4 `nomad job status`（状态）

nomad job status web-demo

执行结果：

ID            = web-demo
Status        = running
Summary
Task Group  Queued  Starting  Running  Failed  Complete  Lost  Unknown
web         0       0         2        0       0         0     0
Allocations
ID        Node ID   Task Group  Version  Desired  Status   Created  Modified
24e22a20  b9b8a77e  web         0        run      running  44s ago  7s ago

job status 独有选项： -all-allocs、-evals、-short、-verbose、-json、-t、-ui。

nomad job status 不带 job 名时列出全部 job 摘要。

8.5 `nomad job stop` / `nomad job validate` / `nomad job allocs`

nomad job stop web-demo
nomad job validate /etc/nomad/web-demo.nomad

执行结果：

Job validation successful

nomad job allocs web-demo

执行结果：

ID        Node ID   Task Group  Version  Desired  Status   Created  Modified
24e22a20  b9b8a77e  web         0        run      running  57s ago  20s ago

九、nomad alloc——分配与日志

9.1 命令族总览

nomad alloc --help

执行结果（子命令清单）：

Subcommands:
    checks     Outputs service health check status information.
    exec       Execute commands in task
    fs         Inspect the contents of an allocation directory
    logs       Streams the logs of a task.
    pause      Pause a running task
    restart    Restart a running allocation
    signal     Signal a running allocation
    status     Display allocation status information and metadata
    stop       Stop and reschedule a running allocation

9.2 `nomad alloc status`（分配详情）

nomad alloc status 24e22a20

执行结果：

ID                  = 24e22a20-9c7e-3b0e-42cf-408f0c54a3f5
Client Status       = running
Node Name           = client2.example.com
Deployment Health   = healthy
Task "echo" is "running"
Task Resources:
CPU      Memory  Disk     Addresses
100 MHz  64 MiB  300 MiB

alloc status 选项： -short、-stats、-verbose、-json、-t、-ui。

9.3 `nomad alloc logs`（任务日志）

nomad alloc logs -tail 24e22a20 echo

执行结果（片段）：

hello-nomad Fri Oct 9 09:18:25 UTC 2026
hello-nomad Fri Oct 9 09:18:27 UTC 2026

alloc logs 独有选项：

选项	说明
`-stdout` / `-stderr`	只显示 stdout / stderr
`-task <name>`	指定任务名
`-group <name>`	指定任务组
`-job <id>`	用某 job 的随机一个 alloc
`-f`	跟随输出（tail -f，默认同时跟随 stdout+stderr）
`-tail`	相对末尾输出（不指定 offset 时 `-n` 默认 10）
`-n`	相对末尾的行数
`-c`	相对末尾的字节数

别名：nomad logs。

9.4 `nomad alloc exec`/`fs`/`restart`

nomad alloc exec 24e22a20 echo "in-alloc"     # 在任务执行命令
nomad alloc fs 24e22a20 /alloc                # 浏览分配目录
nomad alloc restart 24e22a20                  # 重启分配
nomad alloc stop 24e22a20                     # 停止并重新放置该分配

十、nomad eval / deployment / operator

10.1 `nomad eval status`（评估状态）

nomad eval status fe23c021

nomad eval status <eval> 查看一次评估的详细信息与未放置原因；nomad eval list 列全部评估。

10.2 `nomad deployment status`（部署状态）

nomad deployment status
nomad deployment status 6c9e15a3

子命令：fail、list、pause、promote、resume、status、unblock。

10.3 `nomad operator`（集群底层工具，慎用）

nomad operator --help

执行结果（子命令清单）：

Subcommands:
    api             Query Nomad's HTTP API
    autopilot       Provides tools for modifying Autopilot configuration
    client-state    Dump the nomad client state
    debug           Build a debug archive
    gossip          Provides access to the Gossip protocol
    metrics         Retrieve Nomad metrics
    raft            Provides access to the Raft subsystem
    root            Provides access to root encryption keys
    scheduler       Provides access to the scheduler configuration
    snapshot        Saves and inspects snapshots of Nomad server state
    utilization     Generate a utilization reporting bundle

nomad operator raft list-peers    # 查看 Raft peers
nomad operator snapshot save /tmp/nomad.snap   # 保存集群快照

⚠️ operator 直连 Raft 底层，不正当使用可能导致 Nomad 宕机或丢数据，务必谨慎。

十一、nomad config / volume / var

11.1 `nomad config validate`（校验配置）

nomad config validate /etc/nomad.d/server.hcl

执行结果：

Configuration is valid!
WARNING: mTLS is not configured - Nomad is not secure without mTLS!

入参可为单个文件或目录，多实例合并校验。合法返回 0，问题返回 1。不需要 agent 运行，也不用 ACL token。

11.2 `nomad volume`（卷管理）

nomad volume --help

执行结果（子命令清单）：

Subcommands:
    claim         Interact with volume claims
    create        Create an external volume
    delete        Delete a volume
    deregister    Remove a volume
    detach        Detach a volume
    init          Create an example volume specification file
    register      Create or update a volume
    snapshot      Interact with volume snapshots
    status        Display status information about a volume

nomad volume status     # 无 id 时列出全部卷
nomad volume status <volume-id>

volume status 选项： -type <host|csi>（只列某类卷）、-short、-json、-t。

卷类型：host（静态 host volume）与 csi（CSI 外接存储卷）。

11.3 `nomad var`（变量管理）与 `nomad fmt`

nomad var list
nomad var get <path> <key>
nomad fmt -check /etc/nomad.d/*.hcl    # 格式化并检查 Nomad 配置/job 文件

十二、命令速查表

目的	命令
启动 agent	`nomad agent -config /etc/nomad.d`
本地状态	`nomad agent-info`
列 server	`nomad server members`
列节点	`nomad node status`
运行/更新 job	`nomad job run job.nomad`
干跑预演	`nomad job plan job.nomad`
job 状态	`nomad job status <job>`
停止 job	`nomad job stop <job>`
校验 job	`nomad job validate job.nomad`
列 job 分配	`nomad job allocs <job>`
分配详情	`nomad alloc status <alloc>`
任务日志	`nomad alloc logs <alloc> <task>`
节点排空	`nomad node drain -enable -deadline 10m -yes <node>`
取消排空	`nomad node drain -disable -yes <node>`
禁止/允许调度	`nomad node eligibility -disable\|-enable <node>`
校验配置	`nomad config validate <path>`
保存快照	`nomad operator snapshot save out.snap`

十三、注意事项

-address/-region/-namespace/-token 是全局选项，几乎所有子命令可用；生产建议用环境变量 NOMAD_ADDR/NOMAD_TOKEN 而非每次传参。
nomad node drain -enable/disable 与 -monitor 不能同用；-deadline 默认 1 小时。
job plan 退出码 0/1/255 语义不同，自动化脚本应据此判断。
operator raft/snapshot/gossip 为底层运维命令，使用时先做快照。
未开 ACL 时输出会提示 mTLS is not configured 安全警告；生产开启 mTLS/ACL。

十四、常见问题

Q1：命令报 connection refused agent 未启动或 4646 未监听目标地址。systemctl status nomad 确认，核对 -address/NOMAD_ADDR。

Q2：job run 退出码 2（放置失败） 约束/资源不满足，用 nomad job plan 看 Scheduler dry-run 的失败原因与 exclude 的节点类。

Q3：alloc logs 报 "Alloc ID must contain at least two characters" alloc id 缺失或太短。先 nomad alloc status <alloc> 确认合法 id，再接 <alloc> <task>。

Q4：node drain 报 -monitor 与 -enable 冲突 两者不同时使用；排空直接 -enable 默认进入监控，或用单独 -monitor。

十五、参考链接

Nomad 命令全集：https://developer.hashicorp.com/nomad/docs/commands
Job 命令：https://developer.hashicorp.com/nomad/docs/commands/job
Alloc 命令：https://developer.hashicorp.com/nomad/docs/commands/alloc
Node 操作命令：https://developer.hashicorp.com/nomad/docs/commands/node

Nomad 常用 CLI 命令详解

Nomad 常用 CLI 命令详解

一、环境信息

二、工具概览

三、前置条件

四、nomad 顶层命令与全局选项

4.1 nomad --help（命令全景）

4.2 版本命令

4.3 全局/通用选项（所有子命令共享）

五、nomad agent——启动与配置

5.1 nomad agent --help（关键选项）

5.2 nomad agent-info——本地 agent 状态

六、nomad server——集群成员管理

6.1 nomad server members（列出成员）

6.2 nomad server join / force-leave

七、nomad node——节点状态与运维

7.1 nomad node status（节点列表/详情）

7.2 nomad node drain（排空节点）

7.3 nomad node eligibility（调度开关）

八、nomad job——任务生命周期

8.1 命令族总览

8.2 nomad job run（运行/更新 job）

8.3 nomad job plan（干跑预演）

8.4 nomad job status（状态）

8.5 nomad job stop / nomad job validate / nomad job allocs

九、nomad alloc——分配与日志

9.1 命令族总览

9.2 nomad alloc status（分配详情）

9.3 nomad alloc logs（任务日志）

9.4 nomad alloc exec/fs/restart

十、nomad eval / deployment / operator

10.1 nomad eval status（评估状态）

10.2 nomad deployment status（部署状态）

10.3 nomad operator（集群底层工具，慎用）

十一、nomad config / volume / var

11.1 nomad config validate（校验配置）

11.2 nomad volume（卷管理）

11.3 nomad var（变量管理）与 nomad fmt

十二、命令速查表

十三、注意事项

十四、常见问题

十五、参考链接

4.1 `nomad --help`（命令全景）

5.1 `nomad agent --help`（关键选项）

5.2 `nomad agent-info`——本地 agent 状态

6.1 `nomad server members`（列出成员）

6.2 `nomad server join` / `force-leave`

7.1 `nomad node status`（节点列表/详情）

7.2 `nomad node drain`（排空节点）

7.3 `nomad node eligibility`（调度开关）

8.2 `nomad job run`（运行/更新 job）

8.3 `nomad job plan`（干跑预演）

8.4 `nomad job status`（状态）

8.5 `nomad job stop` / `nomad job validate` / `nomad job allocs`

9.2 `nomad alloc status`（分配详情）

9.3 `nomad alloc logs`（任务日志）

9.4 `nomad alloc exec`/`fs`/`restart`

10.1 `nomad eval status`（评估状态）

10.2 `nomad deployment status`（部署状态）

10.3 `nomad operator`（集群底层工具，慎用）

11.1 `nomad config validate`（校验配置）

11.2 `nomad volume`（卷管理）

11.3 `nomad var`（变量管理）与 `nomad fmt`