salt-proxy 代理 Minion 完全指南:命令选项、配置要点与启动原理
salt-proxy 代理 Minion 完全指南:命令选项、配置要点与启动原理
导读
salt-proxy 是 Salt 生态中用于管理无法运行完整 minion 的设备(如网络交换机、路由器、带外管理卡、APC 电源等)的代理守护进程:它接收 Salt master 下发的命令,翻译为设备可执行的指令,再把执行结果回传给 master。本文以官方 CLI 文档(doc/ref/cli/salt-proxy.rst)为主体,深入仓库源码(入口脚本、参数解析器、daemon 启动类与 ProxyMinion 类)和官方示例配置(conf/proxy),帮助你完整掌握 salt-proxy 的全部命令行选项、日志控制、配置文件组织方式,以及它从进程启动到连接 master 的底层实现原理。
salt-proxy 是什么:接收命令、代理执行、回传结果
salt-proxy(proxy minion)的工作方式是:从 Salt master 接收命令 → 向无法运行 minion 的设备发送适当的命令 → 将命令结果回复给 master。官方 CLI 文档的定义非常明确:
Receives commands from a Salt master and proxies these commands to devices that are unable to run a full minion. The Salt proxy minion receives commands from a Salt master, transmits appropriate commands to devices that are unable to run a minion, and replies with the results of said commands.
从源码看,ProxyMinion 是 Minion 的子类,位于 salt/minion.py#L6363-L6435:
This class instantiates a 'proxy' minion—a minion that does not manipulate the host it runs on, but instead manipulates a device that cannot run a minion.
关键差异在于:普通 minion 在本机执行模块函数,而 proxy minion 不操作自身宿主机,而是通过 proxymodule 与远端设备(通常是网络设备)通信。ProxyMinion 类中的所有核心方法(_post_master_init、tune_in、_target_load、_handle_payload、_thread_return 等)都经由 _metaproxy_call() 动态委托给配置指定的 metaproxy 实现(默认 proxy,见 salt/minion.py#L6346-L6360),这正是代理逻辑与标准 minion 解耦的架构设计。
命令语法与全部命令行选项
Synopsis(语法)
salt-proxy [ options ]
核心选项详解
salt-proxy 的命令行选项由 ProxyMinionOptionParser 解析,它组合了 ProxyIdMixIn、ConfigDirMixIn、MergeConfigMixIn、LogLevelMixIn、RunUserMixin、DaemonMixIn、SaltfileMixIn 等 mixin。以下是官方文档列出的全部选项:
| 选项 | 说明 |
|---|---|
--proxyid |
该代理将采用的 minion id(必填)。salt-proxy 会以此 id 在 master 上注册,并以此 id 作为 target 匹配对象 |
--version |
打印当前运行的 Salt 版本号 |
--versions-report |
打印程序的依赖与版本信息后退出 |
-h, --help |
显示帮助信息并退出 |
-c CONFIG_DIR, --config-dir=CONFIG_DIR |
Salt 配置目录的位置。该目录包含 Salt master 与 minion 的配置文件,多数系统默认为 /etc/salt |
-u USER, --user=USER |
指定运行 salt-proxy 的系统用户 |
-d, --daemon |
以守护进程(后台)方式运行 salt-proxy |
--pid-file PIDFILE |
指定 pidfile 路径,默认:/var/run/salt-proxy-<id>.pid |
--proxyid 为什么是必填的?
--proxyid 是唯一一个必须显式提供的参数。在 salt/cli/daemons.py#L452-L455 中,ProxyMinion.prepare() 会直接校验并报错退出:
# allow for native minion
if not is_junos():
if not self.values.proxyid:
self.error("salt-proxy requires --proxyid")
其解析定义在 salt/utils/parsers.py#L1324:
"--proxyid", default=None, dest="proxyid", help="Id for this proxy."
--proxyid 不仅用于标识代理,还会被注入到 minion 配置的 id 字段。在 ProxyMinionOptionParser.setup_config() 中(salt/utils/parsers.py#L1999-L2007):
def setup_config(self):
try:
minion_id = self.values.proxyid
except AttributeError:
minion_id = None
return config.proxy_config(
self.get_config_file_path(), cache_minion_id=False, minion_id=minion_id
)
注意 cache_minion_id=False:代理的 id 来自命令行而非自动探测,因此不会像普通 minion 那样把探测到的 id 写入缓存。这意味着每个受管设备都需要启动一个独立的 salt-proxy 进程,例如 salt-proxy --proxyid=device1、salt-proxy --proxyid=device2……每个进程各占一个 pidfile(/var/run/salt-proxy-<id>.pid)。
其他选项的默认值来源
选项默认值并非散落在代码里,而是集中在 salt/config 模块的 DEFAULT_PROXY_MINION_OPTS 中。ProxyMinionOptionParser 通过 _config_filename_ = "proxy" 和 _default_logging_logfile_ = config.DEFAULT_PROXY_MINION_OPTS<a href="https://link.gitcode.com/i/0db8c2094157690bda94c4c351ce6868" target="_blank">"log_file"] 关联配置([salt/utils/parsers.py#L1995-L1997)。也就是说,-c 指定的目录下会查找名为 proxy 的配置文件,配置目录默认为 /etc/salt。
日志选项(Logging Options)
日志选项会覆盖配置文件中的任何日志设置,来自 doc/ref/cli/_includes/logging-options.rst,salt-proxy 的日志默认值为:logfile 默认 /var/log/salt/minion,log level 默认 warning。
| 选项 | 说明 |
|---|---|
-l LOG_LEVEL, --log-level=LOG_LEVEL |
控制台日志级别,可选 all、garbage、trace、debug、info、warning、error、quiet,默认 warning |
--log-file=LOG_FILE |
日志文件路径,默认 /var/log/salt/minion |
--log-file-level=LOG_LEVEL_LOGFILE |
日志文件的日志级别,可选值与上面相同,默认 warning |
实际排查设备连接问题时,常用的启动方式是临时调高日志级别观察输出,例如:
salt-proxy --proxyid=my-router -l debug
配置文件组织:proxy 主配置与 proxy.d/*.conf
与 salt-minion 使用 minion 配置文件类似,salt-proxy 使用 proxy 配置文件(-c 指定的配置目录下,默认为 /etc/salt/proxy)。仓库根目录提供了完整的示例配置 conf/proxy,其头部说明写道:
This configuration file is used to manage the behavior of all Salt Proxy Minions on this host.
关键配置项
以下配置项全部来自 conf/proxy 示例(注释即官方说明),并适用于所有 proxy minion:
default_include: proxy.d/*.conf:默认情况下,proxy minion 会自动加载主配置文件同目录下proxy.d/目录中的全部*.conf文件。这是多代理场景下组织不同设备配置的推荐方式——每个设备一个proxy.d/<id>.conf。master: salt:Salt master 服务器地址。若 master 无法解析,minion 将启动失败。add_proxymodule_to_opts: True:兼容 2015.8.2 之前创建的 proxymodule 的选项。设为True会把 proxymodule 加入__opts__字典,但会破坏部分依赖序列化__opts__的功能,仅用于向后兼容。proxy_merge_grains_in_module: True:若 proxymodule 有名为grains的函数,则在常规 grains 加载期间调用它,并将结果合并进代理的 grains 字典;否则假定模块以自定义方式调用 grains 函数并在别处返回数据。proxy_keep_alive: True(2017.7.0 新增):若 proxymodule 实现了返回布尔值的alive函数,设为True后代理上的定时任务会尝试在连接断开时重启连接。proxy_keep_alive_interval: 1(2017.7.0 新增):检查与远端设备连接是否存活的轮询间隔(分钟)。要求proxy_keep_alive为True且 proxymodule 实现alive函数。proxy_always_alive: True(2017.7.0 新增):默认情况下代理初始化时即打开与远端设备的连接;部分 proxymodule 支持通过该选项改为每条命令独立开关会话(按命令建连/断连),是否可用取决于具体代理类型是否支持。random_master: False:当master配置了多个 master 时,默认总是按列表顺序连接;设为True则随机化顺序。master_type:设为str表示多 master 同时热连接;设为failover表示故障切换模式,此时务必设置master_alive_interval。master_alive_interval: 30:仅在master_type: failover时生效,轮询 master 是否存活的间隔(秒)。ipv6: False:是否通过 IPv6 连接 master。retry_dns: 30:master 主机名解析失败后的重试等待秒数;设为 0 则直接关闭。
其余配置(如 pki_dir、cachedir、sock_dir、verify_env、user 等)与普通 minion 保持一致,不再赘述。
从命令行到守护进程:启动链路源码解析
入口脚本 scripts/salt-proxy
命令行 salt-proxy 实际对应仓库中的 scripts/salt-proxy 脚本:
#!/usr/bin/env python3
from multiprocessing import freeze_support
import salt.utils.platform
from salt.scripts import salt_proxy
if __name__ == "__main__":
if salt.utils.platform.is_windows():
# Windows 下为无 .py 扩展名的脚本生成 .pyc,使子进程可加载该模块
...
freeze_support()
salt_proxy()
Windows 平台会先把入口脚本编译为 .pyc,以解决无扩展名脚本在 spawn 新进程时无法作为模块加载的问题;freeze_support() 则兼容 PyInstaller 等冻结打包场景。
主函数 salt.scripts.salt_proxy() 与 keepalive 监督进程
真正的启动逻辑在 salt/scripts.py#L392-L439 的 salt_proxy() 中。除了 Windows 平台和 --disable-keepalive 参数会直接启动外,Linux 上默认进入一个 监督循环(supervisor loop):
while True:
queue = multiprocessing.Queue()
process = multiprocessing.Process(
target=proxy_minion_process, args=(queue,), name="ProxyMinion"
)
process.start()
# 仅在第一次 fork 后降权,见 #68115
if not supervisor_privileges_dropped:
import salt.config
_supervisor_drop_privileges(salt.config.proxy_config, "proxy")
supervisor_privileges_dropped = True
process.join()
也就是说,实际代理工作在一个名为 ProxyMinion 的子进程中执行;若子进程因异常退出,监督进程会捕获异常并依据 random_reauth_delay(默认 60 秒,见 salt/scripts.py#L377-L386)随机延时后自动重启。这与普通 salt-minion 的 keepalive 机制一致,保证了网络设备的长时间托管稳定性。
daemon 类 salt.cli.daemons.ProxyMinion
子进程内会实例化 salt/cli/daemons.py#L428-L430 的 ProxyMinion(继承 ProxyMinionOptionParser 与 DaemonsMixin),其 prepare() 完成:校验 --proxyid → 执行 verify_env 创建必要的目录(pki_dir、cachedir、sock_dir、extension_modules,以及 proxy.d 目录)→ 检查运行用户(salt/cli/daemons.py#L441-L499)。随后由 salt.minion.ProxyMinion 真正进入 minion 主事件循环,与 master 建立连接、加载模块与 pillar、订阅任务并回传结果。
与 metaproxy 的关系
salt.minion.ProxyMinion 自身不做代理实现,而是把 tune_in、target_load、handle_payload、thread_return 等生命周期方法全部转交给 opts<a href="https://link.gitcode.com/i/34c0a09dec441197e3495834033e784a" target="_blank">"metaproxy"] 指定的模块(默认 proxy,可配置为 deltaproxy 以支持 subproxy,见 [salt/minion.py#L6387-L6394 的 subproxy_post_master_init)。这解释了为何 salt-proxy 能同时支撑标准 proxy 与 multi-proxy(deltaproxy)两种模式。
实战:启动与管理代理 minion
单设备前台调试
# 以 debug 级别前台运行,便于观察与设备的握手过程
sudo salt-proxy --proxyid=my-router -l debug
多设备后台运行
为每台设备分别启动一个守护进程:
sudo salt-proxy --proxyid=my-router -d --pid-file=/var/run/salt-proxy-my-router.pid
sudo salt-proxy --proxyid=my-switch -d --pid-file=/var/run/salt-proxy-my-switch.pid
并在 master 上验证代理已注册:
salt-key -L # 确认 my-router、my-switch 的公钥已接受
salt my-router test.ping
使用 systemd 托管
仓库自带 systemd 模板单元 pkg/common/salt-proxy@.service,可直接按设备 id 拉起多个代理:
sudo systemctl enable --now salt-proxy@my-router
sudo systemctl status salt-proxy@my-router
代理 id 与 master 端目标匹配
master 端把代理视为普通 minion 目标即可,例如 salt 'my-router' <module>.<function>。请确保各代理的 --proxyid 在 master 的 key 管理中唯一,且对应设备的 proxymodule 已在 salt/proxy 目录或自定义模块路径中注册。
更多参考
- 本命令的权威参考:doc/ref/cli/salt-proxy.rst
- 同族 CLI:salt(1)、salt-master(1)、salt-minion(1)、salt(7)
- 官方示例配置:conf/proxy
- 入口脚本:scripts/salt-proxy,主逻辑 salt/scripts.py
- 参数解析器:salt/utils/parsers.py#L1977-L2007
- 代理 daemon 启动:salt/cli/daemons.py#L428,代理 minion 核心类 salt/minion.py#L6363
- 代理模块(proxymodule)实现目录:salt/proxy
- systemd 单元模板:pkg/common/salt-proxy@.service