SaltStack 配置参数详解

目标：系统梳理 SaltStack Master 与 Minion 的核心配置参数、SLS State 文件、Jinja 模板与 Pillar 用法，并给出生产配置模板。所有默认值均来自 Salt 3004.1 真实环境实测。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（x86_64，内核 6.8.0-138-generic）
Salt 版本：3004.1（salt-master / salt-minion / salt-common）
主控端主机名：salt-master（172.22.0.2）
被管端主机名：salt-minion（172.22.0.3）
主配置文件：/etc/salt/master（Master）、/etc/salt/minion（Minion）
自定义配置目录：/etc/salt/master.d/、/etc/salt/minion.d/
密钥目录：/var/lib/salt/pki/master/、/var/lib/salt/pki/minion/
默认 State 根目录：/srv/salt；默认 Pillar 根目录：/srv/pillar
业务数据目录：/opt/data/salt

💡 说明：本文「默认值（实测）」来自 Salt 3004.1 全新安装、未做任何自定义时的生效配置（通过读取配置对象逐项核对），与配置文件注释中的说明一致。

二、前置条件

已按《Ubuntu 22.04 安装 SaltStack（Master - Minion）指南》完成主从部署并接受密钥
具备 Master 上的 root 权限（修改 /etc/salt/master）与 Minion 上的 root 权限（修改 /etc/salt/minion）
修改配置后需要重启对应服务：systemctl restart salt-master（或 salt-master -d 守护进程方式的环境执行 pkill salt-master 后重启）

三、参数查看与修改方式

3.1 查看生效配置

Minion 侧用 config.get 模块实时查看生效值（实测）：

salt-call config.get master

执行结果：

local:
    salt-master

Master 侧参数可在 Master 上读取配置对象核对（本文各参数默认值即来自该方式），或查看配置文件注释（/etc/salt/master 中每个参数均有说明与默认值）。

3.2 修改方式与生效

角色	修改位置	生效方式
Master	`/etc/salt/master` 或 `/etc/salt/master.d/*.conf`	`systemctl restart salt-master`
Minion	`/etc/salt/minion` 或 `/etc/salt/minion.d/*.conf`	`systemctl restart salt-minion`

💡 说明：master.d/ / minion.d/ 目录下所有 *.conf 会被自动加载并与主配置合并（目录配置优先），推荐用它做环境拆分，避免改动主文件。

四、Master 配置参数详解

4.1 interface（绑定网卡）

默认值（实测）：0.0.0.0
作用：Master 监听命令发布与结果回传的网络接口。0.0.0.0 表示绑定全部网卡；多网卡或多主控场景可指定具体 IP。
修改示例（/etc/salt/master.d/10-network.conf）：

interface: 0.0.0.0

4.2 publish_port（命令发布端口）

默认值（实测）：4505
作用：Master 向 Minion 广播命令的 TCP 端口。Minion 的 master_port 需与之一致（见 5.3）。
修改示例：

publish_port: 4505

⚠️ 注意：4505 端口变更后，所有 Minion 的 master_port 必须同步修改并重启，否则 Minion 收不到命令。

4.3 ret_port（结果回传端口）

默认值（实测）：4506
作用：Minion 向 Master 回传执行结果的 TCP 端口（ZeroMQ 消息队列）。
修改示例：

ret_port: 4506

4.4 salt_path（salt 可执行文件路径）

默认值（实测）：不显式设置（依赖系统 PATH 解析）
作用：Master 内部调用 salt 可执行文件（如 salt-call）时使用的路径。Ubuntu 包安装时二进制位于 /usr/bin；从源码/自定义前缀安装时需显式指定。
修改示例：

salt_path: /usr/bin

4.5 pki_dir（密钥目录）

默认值（实测）：/var/lib/salt/pki/master（Ubuntu 包默认；官方默认注释为 /etc/salt/pki）
作用：存放 Master 自身密钥（master.pem / master.pub）与已接受 Minion 的公钥。该目录包含全部信任关系，生产环境务必持久化与备份。
修改示例：

pki_dir: /var/lib/salt/pki/master

4.6 file_roots（State 根目录）

默认值（实测）：base: ['/srv/salt', '/srv/spm/salt']
作用：定义各环境（base/dev/prod）下 SLS State 文件的查找根目录，按顺序搜索。Minion 执行 state.apply 时按此路径拉取 SLS。
修改示例（追加业务目录 /opt/data/salt）：

file_roots:
  base:
    - /srv/salt
    - /opt/data/salt

4.7 state_roots（State 根目录，已废弃）

默认值（实测）：未设置（None）
作用：早期版本用于指定 SLS 根目录，3004 起已由 file_roots 取代，配置文件中仅保留兼容性说明，不建议使用。

4.8 pillar_roots（Pillar 根目录）

默认值（实测）：base: ['/srv/pillar', '/srv/spm/pillar']
作用：定义 Pillar 数据的查找根目录。Pillar 是 Master 下发给指定 Minion 的加密敏感数据（见七、Pillar 详解）。
修改示例：

pillar_roots:
  base:
    - /srv/pillar

五、Minion 配置参数详解

5.1 id（Minion 唯一标识）

默认值（实测）：主机名（本文环境为 salt-minion）
作用：Minion 在 Master 上的唯一标识，salt-key 列表与命令目标（salt 'salt-minion' test.ping）均使用该值。变更后需要重新认证。
修改示例：

id: salt-minion

5.2 master（主控端地址）

默认值：salt（即主机名 salt 或未配置）
作用：Minion 连接的 Master 地址，可写主机名或 IP。支持列表（故障切换）：master: [master1, master2]。
修改示例：

master: salt-master

5.3 master_port（主控端发布端口）

默认值（实测）：4506
作用：连接 Master 的端口。注意该端口对应 Master 的 publish_port（4505）还是 ret_port（4506）需按版本确认——3004 系列实测 Minion 通过 4505 接收广播、通过 4506 回传，配置项名为 master_port 时保持默认 4506 即可，若 Master 修改了对应端口需同步调整。
修改示例：

master_port: 4506

5.4 grains（自定义静态数据）

默认值（实测）：{}（空）
作用：Minion 上报给 Master 的自定义静态属性（如机柜、环境、角色），供目标匹配与 Jinja 渲染使用。两种定义方式：
1. /etc/salt/grains 文件（YAML 格式，随 minion 启动加载）；
2. grains 键值对直接写入 minion 配置（如下示例）。
修改示例：

grains:
  role: web
  env: prod

验证（Minion 侧）：

salt-call grains.get role

执行结果：

local:
    web

💡 说明：grains 是静态数据（每次启动加载）；运行时动态数据用 Pillar（见七），两者用途不同：grains 描述「机器是什么」，pillar 描述「机器要什么」。

六、SLS State 文件与 Jinja 模板

6.1 SLS 文件结构

SLS（Salt State file）是 Salt 声明式配置的语言，默认存放于 file_roots（/srv/salt）。每个 ID 对应一个状态：

# /srv/salt/webserver.sls
install-nginx:                    # 状态 ID（同文件内唯一）
  pkg.installed:                  # 模块.函数
    - name: nginx                 # 参数列表
  service.running:
    - name: nginx
    - enable: True

执行：salt '*' state.apply webserver。State 具有幂等性——再次执行时已满足的条件不再变更（实测见 6.3）。

6.2 Jinja 模板

SLS 文件支持 Jinja 渲染，可用变量、条件、循环与 Pillar/grains 数据，实现「同一 SLS 适配多环境」：

{# /srv/salt/webver.sls：从 Pillar 取包名，默认 nginx #}
{% set pkg = pillar.get('web', {}).get('package', 'nginx') %}
show-web-package:
  cmd.run:
    - name: echo "pillar package={{ pkg }}"

💡 说明：pillar.get('web', {}).get('package', 'nginx') 表示从 Pillar 取 web.package，取不到则回退默认值 nginx——这是模板「防抖」的常用写法，避免 Pillar 缺失导致渲染失败。

6.3 依赖与顺序

默认按文件内书写顺序执行；跨状态用 require / watch 声明依赖：

# /srv/salt/web.sls
install-nginx:
  pkg.installed:
    - name: nginx

start-nginx:
  service.running:
    - name: nginx
    - enable: True
    - require:
        - pkg: install-nginx     # 先装包，再启服务

实测执行（salt '*' state.apply webserver，来自真实环境）：

salt-minion:
----------
          ID: install-nginx
    Function: pkg.installed
        Name: nginx
      Result: True
     Comment: All specified packages are already installed
     Started: 15:50:46.076484
    Duration: 17.645 ms
     Changes:
----------
          ID: start-nginx
    Function: service.running
        Name: nginx
      Result: True
     Comment: The service nginx is already running
     Started: 15:50:46.095163
    Duration: 26.749 ms
     Changes:

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

💡 说明：require 使两个状态形成依赖链；执行摘要 Succeeded: 2 / Failed: 0 为幂等结果——包与服务已就绪，未产生重复变更。

七、Pillar 详解

Pillar 是 Master 按 Minion 定向下发的数据，天然支持敏感值（不落盘于 Minion 配置），常用于「每台机器要什么」的差异化配置。

7.1 Pillar 目录与 top 文件

Pillar 数据存放于 pillar_roots（/srv/pillar），通过 top.sls 定义目标匹配：

# /srv/pillar/top.sls
base:
  '*':                 # 全部 Minion
    - web

# /srv/pillar/web/init.sls（实际数据）
web:
  package: nginx
  port: 80

7.2 刷新与查看 Pillar

salt '*' saltutil.refresh_pillar    # 刷新全部 Minion 的 Pillar 缓存
salt '*' pillar.get web             # 查看 web 数据

执行结果：

salt-minion:
    True

salt-minion:
    ----------
    package:
        nginx
    port:
        80

7.3 Jinja 中消费 Pillar

结合 6.2 的模板，Pillar 数据在渲染时注入 SLS（实测 state.apply webver 输出）：

salt-minion:
----------
          ID: show-web-package
    Function: cmd.run
        Name: echo "pillar package=nginx"
      Result: True
     Comment: Command "echo "pillar package=nginx"" run
     Started: 15:57:03.545345
    Duration: 5.213 ms
     Changes:
              ----------
              pid:
                  5344
              retcode:
                  0
              stderr:
              stdout:
                  pillar package=nginx

Summary for salt-minion
------------
Succeeded: 1 (changed=1)
Failed:    0
------------
Total states run:     1
Total run time:   5.213 ms

7.4 敏感数据建议

Pillar 内容默认只在 Master 与对应 Minion 间传输，比写入 SLS 更安全；
生产环境敏感值（密码/令牌）建议配合外部 Secret 系统（如 Vault 的 pillar 外部 pillar）或本地 gpg 加密文件使用，禁止明文提交到代码库。

八、生产配置模板

适用场景：8GB 内存、SSD 磁盘、50 台以内的常规生产集群（OLTP 型业务服务器管理）。

/etc/salt/master.d/10-production.conf：

# ---- 网络 ----
interface: 0.0.0.0
publish_port: 4505
ret_port: 4506

# ---- 密钥 ----
pki_dir: /var/lib/salt/pki/master

# ---- State / Pillar 根目录 ----
file_roots:
  base:
    - /srv/salt
    - /opt/data/salt
pillar_roots:
  base:
    - /srv/pillar

# ---- 安全 ----
# 只接受已知指纹（可选加固，需先收集各 Minion 指纹）
# auto_accept: False
# 禁用未认证 Minion 的自动接受
# 事件/日志保留周期
keep_jobs: 24

/etc/salt/minion.d/10-production.conf（被管端）：

master: salt-master
id: salt-minion
master_port: 4506

# 自定义 grains：标记角色与环境
grains:
  role: web
  env: prod

# 超时与重连
auth_safemode: False
recon_default: 1000
recon_max: 59000

⚠️ 注意：以上参数中 keep_jobs 控制任务历史保留小时数；recon_default/recon_max 控制 Minion 断线重连退避（毫秒）。生产环境请按自身内存与规模调整，修改后 systemctl restart salt-master / salt-minion 生效。

九、常见问题（FAQ）

Q1：修改 publish_port / ret_port 后 minion 失联？

Master 改端口后，所有 Minion 的 master_port 与对应端口需同步修改并重启 minion；同时确认防火墙放行新端口。常见错误是只改了一侧。

Q2：state.apply 提示 SLS 找不到？

确认 SLS 文件位于 file_roots 配置的目录（默认 /srv/salt）且扩展名为 .sls；top.sls 未定义时可用 state.apply <sls名> 直接指定；检查 salt '*' cp.get_file salt://web.sls /tmp/web.sls 是否能拉到文件。

Q3：Pillar 更新后 Minion 上取到的还是旧值？

Pillar 有缓存，修改 pillar_roots 下的数据后先 salt '*' saltutil.refresh_pillar 再查询；top 文件目标匹配写错（如大小写、通配符）也会导致取不到。

Q4：grains 与 pillar 都能存自定义数据，怎么选？

grains：静态、描述机器本身（角色、机房、内核），随 minion 启动加载，Master 可全局查看；
pillar：动态、描述机器要什么（版本、端口、密码），按需下发且可含敏感值。简单记：grains 是「我是谁」，pillar 是「我要什么」。

Q5：多环境（dev/prod）如何隔离配置？

用 file_roots/pillar_roots 的环境维度（base、dev、prod 等），再通过 salt -E 'prod.*' 或 grains 目标匹配只对目标机器执行，模板中用 grains['env'] 分支渲染。

十、参考链接

Salt 官方 Master 配置参考：https://docs.saltproject.io/salt/ref/configuration/master.html
Salt 官方 Minion 配置参考：https://docs.saltproject.io/salt/ref/configuration/minion.html
Salt State 系统：https://docs.saltproject.io/salt/ref/states/
Salt Jinja 模板：https://docs.saltproject.io/salt/ref/renderers/all/salt.renderers.jinja.html
Salt Pillar：https://docs.saltproject.io/salt/ref/pillar/
Salt Grains：https://docs.saltproject.io/salt/ref/grains/