Apache Airflow 团队级（Team Scoped）敏感配置脱敏：实现原理与行为变更解析

Apache Airflow 团队级（Team Scoped）敏感配置脱敏：实现原理与行为变更解析

【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow

Apache Airflow 支持在配置文件中通过[<team>=<section>]小节，或在环境中通过AIRFLOW__<TEAM>___<SECTION>__<KEY>环境变量为不同团队提供独立的配置覆盖。在旧版本中，当某个配置项在基础小节（base section）下被注册为敏感项时，只有基础拼写形式会被脱敏为< hidden >，而团队级覆盖因无法被识别为同一配置项，会以明文形式完整返回，造成敏感信息（如密码、token、命令字符串、Secret 路径）泄露。本文以本仓库中 70755.significant.rst 记录的行为变更为主线，深入解析团队级敏感配置脱敏的实现原理、影响面与升级注意事项，帮助你准确理解AirflowConfigParser的敏感值处理机制，并正确配置团队级覆盖以规避泄露风险。

背景：Airflow 的配置体系与团队级覆盖

Apache Airflow 的配置体系围绕AirflowConfigParser构建，该解析器位于共享配置包 parser.py 中，同时服务于 Airflow 核心与其他共享组件。配置的来源按优先级依次为：Airflow 默认值、配置文件（airflow.cfg）、环境变量（AIRFLOW__SECTION__KEY）、*_cmd命令与*_secretSecret 后端。

团队级覆盖（team scoped override）是其中一种特殊机制：它允许以团队为单位隔离配置，而不是全局生效。具体有两种拼写形式：

• 配置文件小节：使用[<team>=<section>]语法，例如[team_a=celery]，其中team_a是团队名，celery是被覆盖的基础小节名；
• 环境变量：使用三重下划线___分隔团队名与基础小节，例如AIRFLOW__TEAM_A___CELERY__BROKER_URL，对应团队TEAM_A、基础小节celery、配置键broker_url。

从源码 parser.py 可以看到分隔符与命名函数：

ENV_VAR_PREFIX = "AIRFLOW__" # Separates the team name from the base section name in a team scoped config file section. TEAM_SECTION_SEPARATOR = "=" def team_section_name(team_name: str, section: str) -> str: """Build the config file section name that holds the team scoped overrides of ``section``.""" return f"{team_name}{TEAM_SECTION_SEPARATOR}{section}"

环境变量的构造逻辑在_env_var_name（parser.py）中：

def _env_var_name(self, section: str, key: str, team_name: str | None = None) -> str: """Generate environment variable name for a config option.""" team_component: str = f"{team_name.upper()}___" if team_name else "" return f"{ENV_VAR_PREFIX}{team_component}{section.replace('.', '_').upper()}__{key.upper()}"

即基础拼写为AIRFLOW__SECTION__KEY，团队级拼写为AIRFLOW__TEAM___SECTION__KEY（注意TEAM与SECTION之间是三个下划线）。单元测试 test_parser.py 中的test_team_env_var_format验证了这一格式：

def test_team_env_var_format(self): """Test the triple-underscore env var format: AIRFLOW__{TEAM}___{SECTION}__{KEY}.""" test_conf = AirflowConfigParser() with patch.dict( os.environ, {"AIRFLOW__MY_TEAM___MY_SECTION__MY_KEY": "team_value"}, ): assert test_conf.get("my_section", "my_key", team_name="my_team") == "team_value"

问题的本质：敏感项注册在基础小节，团队拼写无法被识别

Airflow 将配置项注册为敏感项时，统一使用基础小节名。例如sensitive_config_values集合中存放的是("test", "sensitive_key")这样的(section, key)二元组（见 parser.py）。当一个团队通过[team_a=test]小节或AIRFLOW__TEAM_A___TEST__SENSITIVE_KEY环境变量覆盖该配置时，敏感判定代码拿到的小节名是team_a=test（配置文件形式）或拆分后的team_a（环境变量形式），与注册时的基础小节名test不匹配。

因此在旧实现中：

• 脱敏逻辑只遍历sensitive_config_values中注册的(section, key)组合；
• 团队级拼写下同一配置项不在该集合内，判定为"非敏感"；
• 结果就是团队级覆盖的敏感值（包括_cmd命令字符串与_secretSecret 路径）会以明文形式被as_dict()、REST API 与airflow config list等出口完整暴露。

行为变更的核心：现在敏感判定在"把团队级拼写解析回基础配置项"之后执行。也就是说，is_sensitive_option("team_a=test", "sensitive_key")会先把team_a=test还原为基础小节test，再命中注册记录("test", "sensitive_key")，从而与基础拼写一样被脱敏。变更后的判定逻辑只可能识别出更多敏感项，永远不会比之前识别得更少。

新增的公共辅助函数：团队拼写与基础拼写的双向转换

本次变更在共享配置解析器上新增了三个公共辅助函数，均为纯增量（additive），未改动任何既有函数签名：

team_section_name(team_name, section)

构建团队级配置文件小节的名称。实现在 parser.py：

def team_section_name(team_name: str, section: str) -> str: """ Build the config file section name that holds the team scoped overrides of ``section``. :param team_name: name of the team the overrides belong to :param section: base section name that is being overridden :return: the team scoped section name, e.g. ``team_a=celery`` """ return f"{team_name}{TEAM_SECTION_SEPARATOR}{section}"

例如team_section_name("team_a", "celery")返回"team_a=celery"。

base_section_name(section)

从可能带团队前缀的小节名中恢复基础小节名。实现在 parser.py：

def base_section_name(section: str) -> str: """ Return the base section name of a possibly team scoped config file section. """ _, separator, base_section = section.rpartition(TEAM_SECTION_SEPARATOR) return base_section if separator else section

关键细节：这里使用rpartition从右侧分割，因此即使团队名本身包含分隔符=（例如团队名a=team对应小节a=team=celery），也能正确恢复出基础小节celery。参数化测试 test_parser.py 覆盖了四种情形：

@pytest.mark.parametrize( ("section", "expected"), [ pytest.param("celery", "celery", id="base_section"), pytest.param("team_a=celery", "celery", id="team_scoped_section"), pytest.param("team-a=celery", "celery", id="team_name_with_dash"), pytest.param("a=team=celery", "celery", id="separator_inside_team_name"), ], ) def test_base_section_name(self, section, expected): """The base section name is recovered from a team scoped section name.""" assert base_section_name(section) == expected

AirflowConfigParser.is_sensitive_option(section, key)

判断某配置项是否在任意拼写下被注册为敏感项。实现在 parser.py：

def is_sensitive_option(self, section: str, key: str) -> bool: """...""" section = section.lower() key = key.lower() if (section, key) in self.sensitive_config_values: return True base_section = base_section_name(section) if base_section != section: if (base_section, key) in self.sensitive_config_values: return True # A team scoped ``_cmd`` / ``_secret`` fallback is not resolved into its value, so it # stays in the output as configured and has to be recognised on its own. for fallback_suffix in ("_cmd", "_secret"): if not key.endswith(fallback_suffix): continue if (base_section, key.removesuffix(fallback_suffix)) in self.sensitive_config_values: return True # A team scoped environment variable is reported under the section and key its name splits # into, which is neither the base nor the team scoped section name. return self._names_sensitive_team_env_var(self._env_var_name(section, key))

它的判定路径依次覆盖三种情况：

1. 基础拼写：(section, key)直接命中注册集合；
2. 团队配置文件小节：通过base_section_name还原基础小节后命中注册集合；同时额外处理团队级_cmd/_secret回退键——由于团队级下它们不会被解析成真实值（见下文"行为变更"），必须针对sensitive_key_cmd/sensitive_key_secret这类键名本身单独识别；
3. 团队环境变量：环境变量名拆分出来的小节/键组合既不是基础小节名也不是团队小节名（例如AIRFLOW__TEAM_A___TEST__SENSITIVE_KEY拆出的小节是team_a、键是_test__sensitive_key），因此交由_names_sensitive_team_env_var根据变量名尾部模式匹配（parser.py），对_CMD、_SECRET后缀同样覆盖。

对应测试test_is_sensitive_option_resolves_team_scoped_names（test_parser.py）验证：team_a=test、team-a=test、a=team=test以及环境变量拆分形式("team_a", "_test__sensitive_key")均被判定为敏感；而未注册项key1在任何拼写下都不敏感，且"团队名恰好与某敏感配置键同名"（如sensitive_key=test）也不会误伤其他选项。

行为变更：哪些出口开始对团队值脱敏

本次变更后，以下四个出口在display_sensitive=False（或等价设置）下，对团队级敏感值统一返回< hidden >：

升级提醒：任何依赖上述出口读取团队真实值的部署，升级后将收到掩码< hidden >。若确需真实值（且有相应权限与必要性），请使用display_sensitive=True（CLI 侧对应--show-values等显式选项）。

as_dict的脱敏主循环位于 parser.py。值得注意的实现细节是：脱敏时遍历的是收集到的所有小节（包括团队小节），而非仅注册的敏感项，从而保证team_a=test这类以团队命名的小节也被覆盖：

if not display_sensitive: # This ensures the ones from config file is hidden too # if they are not provided through env, cmd and secret # The collected options are walked (rather than the registered sensitive ones) so that # team scoped sections are covered as well - they are named after the team, not after # the base section the option is registered under. hidden = "< hidden >" for section, options in config_sources.items(): for key, value in list(options.items()): if not value or not self.is_sensitive_option(section, key): continue if display_source: source = value[1] options[key] = (hidden, source) else: options[key] = hidden

display_source=True时，掩码值与来源信息组成元组("< hidden >", "airflow.cfg")，来源信息仍然保留。对应的单元测试test_team_scoped_sensitive_value_is_hidden_in_as_dict（test_parser.py）完整断言了这一行为：

as_dict = test_conf.as_dict(display_sensitive=False) assert as_dict["team_a=test"]["sensitive_key"] == "< hidden >" # The base option keeps being hidden, and an option that is not registered as sensitive # keeps being readable. assert as_dict["test"]["sensitive_key"] == "< hidden >" assert as_dict["team_a=test"]["key1"] == "team_a_key1_value" # display_source keeps reporting where the value came from as_dict_with_source = test_conf.as_dict(display_sensitive=False, display_source=True) assert as_dict_with_source["team_a=test"]["sensitive_key"] == ("< hidden >", "airflow.cfg") # display_sensitive=True still returns the real values as_dict_sensitive = test_conf.as_dict(display_sensitive=True) assert as_dict_sensitive["team_a=test"]["sensitive_key"] == "team_a_value"

行为变更：团队级_cmd与_secret的就地脱敏

在基础小节中，*_cmd与*_secret形式的敏感项在输出前会被解析成真实值（执行命令 / 从 Secret 后端取值），然后从输出中移除解析出的键；而团队级小节下不支持解析这两个回退项。变更前，由于团队拼写未被识别为敏感，命令字符串或 Secret 路径会原样展示；变更后，它们被就地替换为< hidden >（而不是被解析后移除），命令字符串或 Secret 路径不再显示。

测试 test_parser.py 验证：

def test_team_scoped_sensitive_cmd_and_secret_fallbacks_are_hidden_in_as_dict(self): """The _cmd / _secret fallbacks of a team scoped option are not resolved, so they are hidden.""" test_conf = AirflowConfigParser() test_conf.read_string( textwrap.dedent( """\ [team_a=test] sensitive_key_cmd = echo -n team_a_value sensitive_key_secret = team_a/secret/path """ ) ) test_conf.sensitive_config_values.add(("test", "sensitive_key")) as_dict = test_conf.as_dict(display_sensitive=False) assert as_dict["team_a=test"]["sensitive_key_cmd"] == "< hidden >" assert as_dict["team_a=test"]["sensitive_key_secret"] == "< hidden >"

环境中对应的AIRFLOW__TEAM_A___TEST__SENSITIVE_KEY_CMD与..._SECRET同理：test_team_scoped_sensitive_env_var_is_hidden_in_as_dict（test_parser.py）断言真实值team_a_value与命令字符串echo -n team_a_cmd_value在display_sensitive=False下均不出现，且display_sensitive=True时真实值仍可读。

不受影响的范围与回归保障

本次变更保持了两个重要边界：

• 非团队配置完全不受影响：基础小节（非团队）的敏感项行为与变更前一致——display_sensitive=False时掩码，display_sensitive=True时返回真实值；
• display_sensitive=True始终返回真实值：无论基础还是团队拼写，只要显式请求显示敏感值，出口仍返回明文，这为需要真实值的受控场景保留了通道（parser.py）。

此外，脱敏同样作用于把配置写回文件的路径：AirflowConfigParser.write(..., hide_sensitive=True)会在写出的 ini 内容中将团队级敏感值替换为sensitive_key = < hidden >（测试见 test_parser.py）。REST API 侧，config.py 的_check_expose_config强制display_sensitive = False，且[api] expose_config的旧取值non-sensitive-only已被标记为废弃——敏感配置项在 API 出口始终被掩码；config_command.py 中的airflow config list（即show_config）默认隐藏值，并提示需使用--show-values才可能展示敏感数据。对应路由实现见 routes/public/config.py。

升级检查清单

对于使用团队级配置覆盖的部署，升级后建议逐一核对：

1. 审计出口：排查是否依赖GET /config、GET /config/section/{section}/option/{option}、as_dict()或airflow config list读取团队真实值——这些出口现在统一返回< hidden >；
2. 修正读取方：确需真实值的自动化脚本改用display_sensitive=True（REST API 则需在权限允许的前提下评估展示策略），并确保日志与监控链路不落盘敏感明文；
3. 核对_cmd/_secret回退：团队级小节不再解析命令与 Secret 路径，输出中被就地替换为< hidden >，请确认相关消费方不会误解析该占位符；
4. 验证环境变量拼写：确认团队级环境变量严格使用三重下划线AIRFLOW__<TEAM>___<SECTION>__<KEY>（及_CMD/_SECRET后缀），这是团队环境变量被正确识别为敏感的前提；
5. 回归测试：可参考 test_parser.py 中新增的团队级敏感测试用例，在自有配置上验证基础小节、团队小节、团队环境变量三条路径的掩码行为一致。

小结

本次变更将团队级覆盖（[<team>=<section>]小节与AIRFLOW__<TEAM>___<SECTION>__<KEY>环境变量）纳入敏感配置的统一脱敏体系：新增team_section_name、base_section_name与is_sensitive_option三个公共辅助函数，将团队拼写解析回基础配置项后再做敏感判定，使as_dict()、GET /config、GET /config/section/{section}/option/{option}与airflow config list对团队敏感值统一返回< hidden >，团队级_cmd/_secret回退项则就地脱敏且不再解析。非团队配置与display_sensitive=True行为保持不变。对于需要真实值的受控场景，显式开启display_sensitive=True仍是官方支持的通道。

【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow