Salt 执行模块加载机制探秘：从 `salt.modules.test_virtual` 看 `__virtual__()` 返回 False 的模块如何处理

• 运维
• 配置管理
• 后端

导读

本篇文章围绕 salt/modules/test_virtual.py 这个专用于测试的执行模块展开，深入剖析 Salt 加载器（Loader）在遇到__virtual__()函数返回False时的完整处理链路。读者将掌握 Salt 模块加载的 "虚拟函数" 机制、模块被拒载时的错误记录与报错文案生成逻辑，以及如何通过virtual_enable开关和单元测试验证这一行为，从而在自己的 Salt 模块开发中正确利用__virtual__()控制模块的加载条件。

一、test_virtual模块：一个"注定加载失败"的测试样例

在 Salt 的执行模块目录salt/modules/下，绝大多数模块（如test.py、pkg.py）都提供真实可用的功能。而 salt/modules/test_virtual.py 是一个特殊的存在——它的全部源码只有 12 行：

""" Module for testing that a __virtual__ function returning False will not be available via the Salt Loader. """ def __virtual__(): return (False, "The test_virtual execution module failed to load.") def ping(): return True

从模块 docstring 可以明确其定位：它专门用于测试 "当__virtual__函数返回False时，模块不会通过 Salt Loader 对外提供"这一行为。模块定义了一个看似正常的ping()函数（返回True），但__virtual__()却返回了二元组：

return (False, "The test_virtual execution module failed to load.")

这里值得注意两点：

1. 返回值形式：__virtual__()返回的是一个(bool, str)元组，其中第一个元素是布尔判定结果，第二个元素是失败原因字符串。这是 Salt 推荐的"带原因的拒绝加载"写法，比单纯返回False更能说明模块为何不可用。
2. ping()永不对外可见：尽管ping()函数本身逻辑上可以正常执行，但由于模块级__virtual__()判定失败，整个模块的所有函数都会被加载器拒之门外。

从命名习惯看，test_virtual.py与同目录下的 salt/modules/test.py（提供test.ping等常用调试函数）形成对照：前者模拟"加载失败"场景，后者提供常规的调试能力。

二、__virtual__()：Salt 模块加载的"守门员"

要理解test_virtual的作用，必须先理解 Salt 加载器的模块筛选机制。在 salt/loader/lazy.py 的_process_virtual方法（salt/loader/lazy.py#L1352-L1481）中，加载器会对每个被扫描到的模块执行如下判定逻辑：

# The __virtual__ function will return either a True or False value. # If it returns a True value it can also set a module level attribute # named __virtualname__ with the name that the module should be # referred to as.

__virtual__()的返回值语义在源码注释中有权威说明：

• 返回True：模块加载成功，若同时定义了模块级属性__virtualname__，则使用该名字对外引用；
• 返回字符串（新名字）：模块以新名字注册，实现重命名（例如augeas_cfg对外称为augeas）；
• 返回False或(False, reason)：模块不适用于当前平台或缺少依赖，加载器跳过该模块；
• 返回None：属于错误用法，加载器会发出警告日志："%s.__virtual__()is wrongly returningNone"。

在_process_virtual的实现中，元组形式的返回值会被拆解：

virtual = self.run(virtual_attr) if isinstance(virtual, tuple): error_reason = virtual[1] virtual = virtual[0]

即元组的第二个元素被提取为error_reason，第一个元素作为实际的布尔判定结果。这正是test_virtual.py中(False, "The test_virtual execution module failed to load.")这种写法能够生效的底层原因。

此外，_process_virtual还定义了加载器对__virtualname__与__virtual__()返回值一致性检查：当模块重命名自己时，若__virtualname__属性与__virtual__()返回的名字不一致，会记录错误日志提示开发者修正。

加载失败后的处理：missing_modules记录

当__virtual__()判定失败后，加载器并不只是简单地跳过模块。在 salt/loader/lazy.py#L1143-L1166 中可以看到，加载器会把失败原因写入self.missing_modules字典：

# if _process_virtual returned a non-True value then we are # supposed to not process this module if virtual_ret is not True: # Always record the per-file reason; `name` is unique. self.missing_modules[name] = virtual_err # The virtualname (module_name) can collide when multiple # files declare the same __virtualname__ (e.g. x509 and # x509_v2 both use "x509"). If we've already recorded a # reason for this virtualname, append the new one so the # user sees every failure, not just the first. if module_name not in self.missing_modules: self.missing_modules[module_name] = virtual_err elif virtual_err is not None: # ... 多条原因以 "; " 拼接 return False

这段代码有两个关键行为：

1. 以文件名（name）为键记录：每个模块文件都有一条独立的失败记录；
2. 以虚拟名（module_name）为键合并记录：当多个文件声明了相同的__virtualname__且都加载失败时（典型场景是x509与x509_v2都声称叫x509），失败原因会以分号拼接，确保用户能看到全部失败原因，而不是只看到第一条。

错误文案生成：missing_fun_string

当用户在命令行或代码中调用一个未能加载的函数时，加载器通过missing_fun_string方法（salt/loader/lazy.py#L568-L588）生成报错文案：

def missing_fun_string(self, function_name): mod_name = function_name.split(".")[0] if mod_name in self.loaded_modules: return f"'{function_name}' is not available." else: try: reason = self.missing_modules[mod_name] except KeyError: return f"'{function_name}' is not available." else: if reason is not None: return "'{}' __virtual__ returned False: {}".format( mod_name, reason ) else: return f"'{mod_name}' __virtual__ returned False"

对于test_virtual.ping来说，调用失败时的文案将是：

'test_virtual' __virtual__ returned False: The test_virtual execution module failed to load.

这条文案中的后半段，正是来自 salt/modules/test_virtual.py 中__virtual__()返回的元组第二元素。也就是说，test_virtual模块中的失败原因字符串并非摆设——它最终会成为终端用户看到的报错信息的一部分。

三、加载器入口：minion_mods与LazyLoader

模块加载的入口函数是 salt/loader/init.py 中的minion_mods（salt/loader/init.py#L390-L440），其 docstring 直接点明了与__virtual__的关系：

Load execution modules — Returns a dictionary of execution modules appropriate for the current system by evaluating the__virtual__()function in each module.

该函数接受opts（Salt 配置字典）、context、utils、whitelist、proxy等参数，内部构建一个pack字典（包含__context__、__utils__、__proxy__、__opts__、__file_client__），随后创建LazyLoader实例完成实际加载。docstring 中还给出了一个标准的编程式调用示例：

import salt.config import salt.loader __opts__ = salt.config.minion_config('/etc/salt/minion') __grains__ = salt.loader.grains(__opts__) __opts__['grains'] = __grains__ __utils__ = salt.loader.utils(__opts__) __salt__ = salt.loader.minion_mods(__opts__, utils=__utils__) __salt__['test.ping']()

在LazyLoader内部，salt/loader/lazy.py#L1127-L1130 展示了虚拟函数的触发条件：

# if virtual modules are enabled, we need to look for the # __virtual__() function inside that module and run it. if self.virtual_enable: virtual_funcs_to_process = ["__virtual__"] + self.virtual_funcs for virtual_func in virtual_funcs_to_process: (...)

关键点在于self.virtual_enable开关。LazyLoader.__init__的签名中（salt/loader/lazy.py#L272）定义了参数virtual_enable：

:param bool virtual_enable: Whether or not to respect the __virtual__ function when loading modules.

默认值为True。当其为True时，__virtual__()参与模块筛选；当其为False时，__virtual__()被完全跳过，所有模块（包括test_virtual）都会无条件加载。这一开关正是单元测试验证test_virtual行为的关键入口。

四、单元测试：如何验证"被拒载"的行为

4.1 默认行为：test_virtual.ping不存在

在 tests/unit/test_loader.py#L359-L361 中，LazyLoaderVirtualEnabledTest测试类验证了默认加载行为：

@pytest.mark.slow_test def test_virtual(self): self.assertNotIn("test_virtual.ping", self.loader)

该测试的意图非常明确：在默认配置（virtual_enable=True）下，由于test_virtual模块的__virtual__()返回False，加载器不会注册test_virtual.ping函数，因此断言test_virtual.ping不在加载结果中。

4.2 关闭虚拟函数后：test_virtual.ping可加载

LazyLoaderVirtualDisabledTest测试类（tests/unit/test_loader.py#L364-L404）则演示了另一种场景。其setUp中创建加载器时显式传入virtual_enable=False：

self.loader = salt.loader.LazyLoader( salt.loader._module_dirs(copy.deepcopy(self.opts), "modules", "module"), copy.deepcopy(self.opts), tag="module", pack={ "__utils__": self.utils, "__salt__": self.funcs, "__proxy__": self.proxy, }, virtual_enable=False, )

相应的测试断言反转：

@pytest.mark.slow_test def test_virtual(self): self.assertTrue( isinstance(self.loader["test_virtual.ping"], salt.loader.lazy.LoadedFunc) )

此时test_virtual.ping不仅存在，而且被包装为LoadedFunc对象（即加载器对已加载函数的封装类型）。两处测试恰好构成"同一模块、两种加载策略"的对照实验，直观证明了__virtual__()对模块可用性的决定性影响。

4.3 补充测试：虚拟名冲突时的原因合并

在 tests/pytests/unit/loader/test_lazy.py#L203-L251 中还有一个与本主题高度相关的回归测试test_virtualname_collision_surfaces_all_reasons。它构造了x509.py与x509_v2.py两个都声明__virtualname__ = "x509"且都返回(False, reason)的模块，验证：

1. 通过loader["x509.expires"]访问会抛出KeyError；
2. loader.missing_modules.get("x509")中同时包含两条失败原因；
3. loader.missing_fun_string("x509.expires")生成的文案同样包含两条原因。

该测试对应的是真实缺陷 #68625 的修复：此前 salt-ssh 用户在调用 x509 功能时只能看到 v1 模块的 "Superseded" 提示，而看不到底层 x509_v2 模块 "Could not load cryptography" 的真实原因。这也从侧面印证了missing_modules与missing_fun_string机制的实际价值。

五、虚拟模块的两种正确打开方式：__virtualname__与__virtual_aliases__

test_virtual展示了"拒绝加载"的用法，但__virtual__()机制还有更丰富的应用。结合 salt/loader/lazy.py#L1378 的源码可以看到，加载器还会读取模块的__virtual_aliases__属性：

virtual_aliases = getattr(mod, "__virtual_aliases__", tuple())

这引出了两种常见的正向用法，供读者在编写自己的模块时参考：

1. 虚拟重命名：__virtual__()返回新名字字符串，同时设置__virtualname__属性。最典型的案例是pkg模块——它在不同平台上由pkg、aptpkg、yumpkg等不同文件实现，但统一以pkg对外服务；再如augeas_cfg对外称为augeas，避免命名空间冲突。
2. 依赖/平台检查：__virtual__()返回(False, reason)来拒绝在不满足条件的平台上加载（如缺少 Python 依赖库、运行在不支持的操作系统上），并给出对人类友好的失败原因——这正是test_virtual模拟的场景。

对于代理（proxy）环境，还有额外的__proxyenabled__约束：在 salt/loader/lazy.py#L1175-L1184 中，如果opts中存在proxy配置且模块类型为grains或proxy，模块必须声明__proxyenabled__且包含对应的 proxytype，否则同样会被记录为 "not a proxy_minion enabled module" 并跳过。

六、实践验证：在本地复现test_virtual的行为

读者可以在本地运行该仓库的测试套件来验证上述行为。使用项目配置的测试运行方式执行：

# 运行 loader 相关的单元测试（包含 test_virtual 的两组用例） pytest tests/unit/test_loader.py -k "test_virtual"

预期结果：LazyLoaderVirtualEnabledTest::test_virtual通过（断言test_virtual.ping不在 loader 中），LazyLoaderVirtualDisabledTest::test_virtual通过（断言test_virtual.ping是LoadedFunc）。

若要手工体验模块被拒载的报错，也可以在 Python REPL 中模拟加载器行为：

import salt.config import salt.loader __opts__ = salt.config.minion_config(None) __grains__ = salt.loader.grains(__opts__) __opts__["grains"] = __grains__ __utils__ = salt.loader.utils(__opts__) __salt__ = salt.loader.minion_mods(__opts__, utils=__utils__) # test_virtual.ping 不会被加载 assert "test_virtual.ping" not in __salt__ # 通过 missing_fun_string 查看被拒载的原因 loader = salt.loader.LazyLoader( salt.loader._module_dirs(__opts__, "modules", "module"), __opts__, tag="module", pack={"__utils__": __utils__, "__salt__": __salt__}, ) print(loader.missing_fun_string("test_virtual.ping"))

输出将包含test_virtual模块__virtual__()中写明的失败原因，与 salt/modules/test_virtual.py 中的字符串一一对应。

七、小结

test_virtual模块虽然只有 12 行代码，却是理解 Salt 模块加载机制的一把钥匙。它验证了一个核心事实：__virtual__()返回False（或带原因的二元组）的模块，无论其内部函数多么正常，都不会暴露给 Salt 运行时。围绕它，本文串联起了完整的证据链：

对于 Salt 模块开发者而言，这一机制意味着：应当在__virtual__()中主动检查运行平台、依赖库和前置条件，并以(False, reason)的形式给出清晰原因，这样既能让加载器自动跳过不适用的模块，又能让最终用户在报错时第一时间看到问题所在——这正是 Salt 生态中数百个模块赖以保持跨平台兼容性的基石。

• 运维
• 配置管理
• 后端