SaltStack 常用命令与工具详解

目标：详解 SaltStack 常用命令与工具（salt、salt-key、salt-run、salt-call、salt-cp、salt-master/salt-minion、sys/state 模块），每个命令给出完整参数说明与真实输出。所有命令均在 Ubuntu 22.04 主从真实架构实测通过（Salt 3004.1）。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（x86_64，内核 6.8.0-138-generic）
Salt 版本：3004.1
主控端：salt-master（172.22.0.2），运行 salt-master，监听 4505/4506
被管端：salt-minion（172.22.0.3），运行 salt-minion，id 为 salt-minion
密钥状态：salt-minion 已接受（Accepted）
演示账号：root

二、工具概览

工具	主要用途	所在端
`salt`	Master 端远程执行模块命令（批量/目标匹配）	Master
`salt-key`	Master 端密钥管理（接受/拒绝/删除/指纹）	Master
`salt-run`	Master 端 Runner 管理命令（状态/任务/事件）	Master
`salt-call`	Minion 端本地执行模块命令（不经过 Master）	Minion
`salt-cp`	Master 向目标 Minion 分发文件	Master
`salt-master`	Master 服务进程（守护/配置/日志）	Master
`salt-minion`	Minion 服务进程（守护/配置/日志）	Minion

三、前置条件

已部署 SaltStack 主从架构并完成密钥认证（参考《Ubuntu 22.04 安装 SaltStack（Master - Minion）指南》）
Master 侧命令（salt/salt-key/salt-run/salt-cp）在 Master 上执行；Minion 侧命令（salt-call）在 Minion 上执行
使用 root 账号或具有 /etc/salt、/var/lib/salt 读写权限的账号

四、salt 命令详解

salt 是 Master 端最核心的远程执行工具，格式为 salt '<target>' <module.function> [args]。

4.1 常用参数

参数	说明
`<target>`	目标匹配表达式（见 4.2），默认通配符匹配
`-L`	用列表匹配（逗号分隔，如 `salt -L 'node1,node2' test.ping`）
`-E`	用正则匹配（如 `salt -E '^web.*' test.ping`）
`-G`	用 grains 匹配（如 `salt -G 'os:Ubuntu' test.ping`）
`-N`	用 nodegroup 匹配（需在 master 配置中定义）
`-I`	用 pillar 匹配（如 `salt -I 'web:port:80' test.ping'`）
`--out=json`	以 JSON 格式输出（另有 yaml、quiet 等）
`-t TIMEOUT`	命令超时（秒），默认 5 秒

4.2 目标匹配方式（实测）

salt '*' test.ping                    # 通配符：所有节点
salt 'salt-minion' test.ping          # 精确 id
salt -L 'salt-minion' test.ping       # 列表
salt -G 'os:Ubuntu' test.ping         # grains：Ubuntu 系
salt -E '^salt-.*' test.ping          # 正则

4.3 存活探测与版本（实测）

salt '*' test.ping
salt '*' test.version

执行结果：

salt-minion:
    True

salt-minion:
    3004.1

💡 说明：test.ping 用于确认 Minion 在线（非 ICMP ping）；test.version 返回各 Minion 的 Salt 版本，便于核对版本一致性。

4.4 查看节点属性（grains，实测）

salt '*' grains.item os osrelease os_family kernel kernelrelease id

执行结果：

salt-minion:
    ----------
    id:
        salt-minion
    kernel:
        Linux
    kernelrelease:
        6.8.0-138-generic
    os:
        Ubuntu
    os_family:
        Debian
    osrelease:
        22.04

4.5 远程执行命令（cmd.run，实测）

salt '*' cmd.run 'uptime'

执行结果：

salt-minion:
     15:49:52 up 11 min,  0 users,  load average: 4.34, 61.09, 47.05

salt '*' cmd.run 'nginx -v'

执行结果：

salt-minion:
    nginx version: nginx/1.18.0 (Ubuntu)

4.6 模块与文档（sys，实测）

salt '*' sys.list_modules

执行结果（节选）：

salt-minion:
    - aliases
    - alternatives
    - archive
    - artifactory
    - baredoc
    - beacons
    - bigip
    - btrfs
    - buildout
    - chroot
    - cloud

salt '*' sys.doc test.ping

执行结果：

test.ping:

    Used to make sure the minion is up and responding. Not an ICMP ping.

    Returns ``True``.

    CLI Example:

        salt '*' test.ping

💡 说明：sys.list_modules 列出 Minion 可用的全部模块；sys.doc <module.function> 查看指定函数的内置帮助与 CLI 示例，是排查「模块不存在/参数不对」的首选工具。

五、salt-key 详解

salt-key 是 Master 端密钥管理工具，管理 Minion 的认证密钥生命周期。

5.1 常用参数

参数	说明
`-L`	列出全部密钥（Accepted/Denied/Unaccepted/Rejected）
`-A`	接受全部待接受（Unaccepted）密钥
`-a <id>`	接受指定 id 的密钥
`-D`	拒绝全部待接受密钥
`-d <id>`	删除指定密钥（立即断开该 Minion）
`-f <id>`	显示指定 Minion 的密钥指纹
`-y`	免交互确认（配合 -A/-D 使用）

5.2 查看密钥列表（实测）

salt-key -L

执行结果：

Accepted Keys:
salt-minion
Denied Keys:
Unaccepted Keys:
Rejected Keys:

5.3 接受密钥（实测）

salt-key -A -y

执行结果（未接受时）：

The following keys are going to be accepted:
Unaccepted Keys:
salt-minion
Key for minion salt-minion accepted.

5.4 查看指纹（实测）

salt-key -f salt-minion

执行结果：

Accepted Keys:
salt-minion:  c7:0b:ce:e2:43:af:66:9b:01:b2:ba:68:61:8c:f4:00:d6:13:5d:76:31:63:f3:97:e6:ba:45:1b:d4:1c:f7:ac

💡 说明：多节点接入时建议逐个 salt-key -a <id> 接受，并用 -f 先比对指纹，防止伪造 Minion 混入。

5.5 删除密钥（实测）

salt-key -d salt-minion -y

执行结果：

The following keys are going to be deleted:
Accepted Keys:
salt-minion
Key for minion salt-minion deleted.

💡 说明：删除后该 Minion 会重新发起认证，需再次接受方可恢复；常用于节点下线或密钥轮换。

六、salt-run 详解

salt-run 在 Master 端执行 Runner 管理模块（不涉及 Minion 业务模块）。

6.1 常用参数

参数	说明
`manage.status`	查看所有 Minion 在线/离线状态
`manage.up`	列出在线 Minion（等价于 manage.status 的 up 列表）
`manage.down`	列出离线 Minion
`jobs.list_jobs`	列出历史任务（JID、函数、目标、时间）
`jobs.active`	查看正在执行的任务
`jobs.lookup_jid <jid>`	按任务 ID 查询结果
`config.values`	查看 Master 生效配置（调试用）

6.2 在线状态（实测）

salt-run manage.status

执行结果：

down:
up:
    - salt-minion

salt-run manage.up

执行结果：

- salt-minion

💡 说明：manage.status 中 down 为空、up 列出 salt-minion，即主从链路健康。

6.3 任务历史（实测）

salt-run jobs.list_jobs

执行结果（节选）：

20261009154951228859:
    ----------
    Arguments:
    Function:
        test.ping
    StartTime:
        2026, Oct 09 15:49:51.228859
    Target:
        *
    Target-type:
        glob
    User:
        root
20261009154951956052:
    ----------
    Arguments:
        - uptime
    Function:
        cmd.run
    StartTime:
        2026, Oct 09 15:49:19.560521

💡 说明：JID 为 17 位时间戳，可用 jobs.lookup_jid <jid> 追溯某次任务在全部 Minion 上的执行结果，用于审计与排障。

七、salt-call 详解

salt-call 在 Minion 本地执行模块函数（不经过 Master），用于本机自检与排障。

7.1 常用参数

参数	说明
`<function>`	模块函数，如 `test.ping`、`grains.items`
`--out=json`	JSON 输出
`-l debug`	开启 debug 日志（排障首选：看连接、认证、发布）
`-c CONFIG_DIR`	指定配置目录（默认 /etc/salt）

7.2 本地存活自检（实测）

salt-call test.ping

执行结果：

local:
    True

7.3 查看全部 grains（实测节选）

salt-call grains.items

执行结果（节选）：

local:
    ----------
    biosreleasedate:
        11/12/2020
    biosversion:
        6.00
    cpu_flags:
        - fpu
        - vme
        - de
        - pse
        - tsc
        - msr
        - pae
        - mce
        - cx8
        - apic
        - sep
        - mtrr
        - pge
        - mca
        - cmov
        - pat
        - pse36
        - clflush
        - mmx
        - fxsr
        - sse
        - sse2
        - ss
        - ht
        - syscall
        - nx
        - pdpe1gb
        - rdtscp
        - lm
        - constant_tsc
        - arch_perfmon
        - rep_good
        - nopl
        - xtopology
        - tsc_reliable
        - nonstop_tsc
        - cpuid
        - tsc_known_freq

7.4 查看配置项（实测）

salt-call config.get master

执行结果：

local:
    salt-master

💡 说明：salt-call -l debug test.ping 是 Minion 连不上 Master 时的标准排障姿势——debug 日志会打印认证、发布通道连接过程与具体报错。

八、salt-cp 详解

salt-cp 从 Master 向目标 Minion 分发文件，适合文本/配置文件（官方说明不建议广播大文件）。

8.1 基本用法

salt-cp '<target>' <本地源文件> <远端目标路径>

参数	说明
`<target>`	目标匹配，同 salt 命令
`SOURCE`	本地（Master 侧）源文件路径
`DEST`	Minion 侧目标路径
`--chunked`	分块传输（大文件场景）

8.2 分发与验证（实测）

salt-cp '*' /srv/salt/hello.txt /tmp/hello.txt

执行结果：

salt-minion:
    ----------
    /tmp/hello.txt:
        True

验证远端内容：

salt '*' cmd.run 'cat /tmp/hello.txt'

执行结果：

salt-minion:
    hello-saltcp

💡 说明：返回值 True 表示分发成功；salt-cp 不自动建目录，目标目录需已存在；批量分发配置前建议先 --chunked 或拆分小文件。

九、salt-master / salt-minion 服务命令

9.1 服务启停（systemd 环境）

# Master
systemctl enable --now salt-master
systemctl status salt-master
systemctl restart salt-master

# Minion
systemctl enable --now salt-minion
systemctl status salt-minion
systemctl restart salt-minion

⚠️ 注意：不带 systemd 的环境改用守护进程方式：salt-master -d / salt-minion -d，停服用 pkill salt-master / pkill salt-minion。

9.2 守护进程参数（实测 help 节选）

salt-master --help

执行结果：

Usage: salt-master [options]

The Salt Master, used to control the Salt Minions

Options:
  --version             show program's version number and exit
  -V, --versions-report
                        Show program's dependencies version number and exit.
  -h, --help            show this help message and exit
  -c CONFIG_DIR, --config-dir=CONFIG_DIR
                        Pass in an alternative configuration directory.
                        Default: '/etc/salt'.
  -u USER, --user=USER  Specify user to run salt-master.
  -d, --daemon          Run the salt-master as a daemon.
  --pid-file=PIDFILE    Specify the location of the pidfile. Default:
                        '/var/run/salt-master.pid'.

salt-minion --help

执行结果：

Usage: salt-minion [options]

The Salt Minion, receives commands from a remote Salt Master

Options:
  --version             show program's version number and exit
  -V, --versions-report
                        Show program's dependencies version number and exit.
  -h, --help            show this help message and exit
  -c CONFIG_DIR, --config-dir=CONFIG_DIR
                        Pass in an alternative configuration directory.
                        Default: '/etc/salt'.

💡 说明：-d 后台守护、-c 指定配置目录、-l 指定日志级别（debug 排障常用）、--pid-file 指定 pid 文件位置。

9.3 日志位置

日志文件	内容
`/var/log/salt/master`	Master 运行日志
`/var/log/salt/minion`	Minion 运行日志
`/var/log/salt/key`	密钥认证相关日志

十、sys / state 模块测试

10.1 sys 模块（运行时自省）

salt '*' sys.list_modules                    # 列出全部可用模块
salt '*' sys.list_functions test             # 列出 test 模块下全部函数
salt '*' sys.doc cmd.run                     # 查看 cmd.run 文档

执行结果（sys.list_functions test 节选）：

salt-minion:
    - test.arg
    - test.arg_repr
    - test.arg_type
    - test.echo
    - test.exception
    - test.fib
    - test.get_opts
    - test.kwarg
    - test.mod_random
    - test.not_loaded
    - test.ping
    - test.rand_sleep
    - test.rand_str
    - test.sleep
    - test.version

10.2 state 模块（状态管理）

salt '*' state.apply <sls名>        # 应用指定 SLS
salt '*' state.show_sls <sls名>     # 预览渲染后的 SLS 结构（不执行）
salt '*' state.sls <sls名>          # 等同 state.apply（旧写法）
salt '*' state.highstate            # 应用 top.sls 定义的全局状态

实测 state.show_sls webserver（预览渲染结果，不执行）：

salt-minion:
    ----------
    install-nginx:
        ----------
        __env__:
            base
        __sls__:
            webserver
        pkg:
            |_
              ----------
              name:
                  nginx

实测 state.apply webserver（执行摘要）：

Summary for salt-minion
------------
Succeeded: 2
Failed:    0
------------
Total states run:     2
Total run time:  44.394 ms

💡 说明：排障顺序建议为 state.show_sls（看渲染结构）→ state.apply（看执行结果）；show_sls 不产生变更，适合验证 Jinja 渲染是否正确。

十一、注意事项

命令端别搞混：salt/salt-key/salt-run/salt-cp 只在 Master 执行；salt-call 只在 Minion 执行；在 Minion 上跑 salt 会报命令不存在。
目标匹配默认是通配符：salt '*' 匹配全部；生产批量操作前建议先用 --out=json 或 -L 精确限定目标，避免误操作。
密钥安全：salt-key -A 会接受所有待接受密钥，多节点环境建议逐个 -a 并比对 -f 指纹。
敏感值不落明文：涉及密码的演示一律用 Pillar 或环境变量注入，禁止把明文密码写进 SLS 与命令。
端口依赖：test.ping 超时先查 4505/4506 连通，再查 salt-key 状态，最后看 /var/log/salt/minion 日志。
版本一致性：Master/Minion 大版本保持一致，跨大版本先查官方升级说明，必要时重新认证。

十二、常见问题（FAQ）

Q1：salt '*' test.ping 超时（Minion did not return）？

按顺序排查：salt-key -L 确认密钥已接受 → Minion 侧 salt-call -l debug test.ping 看连接日志 → 两机互 ping 并确认 4505/4506 放行 → systemctl restart salt-minion。

Q2：salt '*' cmd.run 'some-cmd' 返回 Minion 无输出或命令不存在？

cmd.run 默认用 /bin/sh 执行；需确认命令存在于 Minion 的 PATH；查看 stderr 用 salt '*' cmd.run 'some-cmd 2>&1'。

Q3：salt-key -L 看到的 Unaccepted 密钥太多，如何快速清理？

先 salt-key -f <id> 核对指纹，确认是本人的再 salt-key -a <id>；不确定的 salt-key -D -y 全部拒绝。

Q4：salt-run jobs.list_jobs 结果为空？

任务历史默认保留 keep_jobs（默认 24 小时），超过保留期自动清理；刚执行的任务可通过 jobs.active 查看是否仍在执行。

Q5：如何批量查看多台机器的内存/磁盘？

salt '*' cmd.run 'free -m | head -3'
salt '*' cmd.run 'df -h /'

或使用模块：salt '*' disk.usage、salt '*' status.meminfo。

Q6：salt-cp 目标目录不存在导致失败？

先执行 salt '*' cmd.run 'mkdir -p /目标目录'，再 salt-cp；或将目录创建写入 SLS 用 state.apply 统一处理。

十三、参考链接

salt 命令手册：https://docs.saltproject.io/salt/ref/cli/salt.html
salt-key 命令手册：https://docs.saltproject.io/salt/ref/cli/salt-key.html
salt-run 命令手册：https://docs.saltproject.io/salt/ref/cli/salt-run.html
salt-call 命令手册：https://docs.saltproject.io/salt/ref/cli/salt-call.html
salt-cp 命令手册：https://docs.saltproject.io/salt/ref/cli/salt-cp.html
模块列表（模块索引）：https://docs.saltproject.io/salt/ref/modules/