配置进阶模式参考：多环境分层、特性开关与配置源全景

前置知识#

• 已读完 配置管理：会用环境变量、.env 与 pydantic-settings，理解优先级链；
• Docker 有概念即可（K8s 一节用到镜像与容器词汇）。

定位说明：主线篇管「单服务把配置管对」，本篇是参考层：什么时候需要升级方案、升级后各模式的核心用法与代价。每节独立成篇，按需跳读。

一、多环境分层：什么时候轮到 Dynaconf#

pydantic-settings 的「同一模型、不同注入」在环境到三四个、配置项过百后会露出疲态：每个环境的 .env 各自维护，字段一多就漂移。Dynaconf 的解法是配置文件内分层——一份文件，环境各自一段：

# settings.toml
[default]
log_level = "INFO"
[development]
model_endpoint = "http://192.168.1.8:8000/v1"
[production]
model_endpoint = "https://api.toy.example.com/v1"

from dynaconf import Dynaconf

settings = Dynaconf(
    environments=True,
    env_switcher="TOY_ENV",        # 用环境变量决定当前环境
    settings_files=["settings.toml"],
)
settings.MODEL_ENDPOINT             # 随 TOY_ENV 取对应段

部署时 TOY_ENV=production，代码零改动切环境；密钥仍从环境变量注入（Dynaconf 自动并入，且约定密钥放 .secrets.toml 并 gitignore）。与 pydantic-settings 的分界：类型校验强需求选 pydantic-settings，多环境文件分层强需求选 Dynaconf，两者也能组合（Dynaconf 管分层取值，Pydantic 管校验）。

二、特性开关与动态配置：让行为改动不发版#

主线篇立过规矩：配置启动定型、运行期只读。但有两类需求天然要运行期变：新功能想只对部分用户开（灰度）、出事故想立刻关掉某功能（止血）。这用特性开关实现——开关本身是数据，不是代码：

import os

class FeatureFlags:
    """最小可用实现：环境变量驱动，重启生效。"""

    def __init__(self, raw: dict[str, bool]) -> None:
        self._flags = dict(raw)

    def enabled(self, name: str) -> bool:
        return self._flags.get(name, False)

flags = FeatureFlags({
    "wake_word": os.getenv("FLAG_WAKE_WORD", "").lower() == "true",
    "new_billing": os.getenv("FLAG_NEW_BILLING", "").lower() == "true",
})

if flags.enabled("wake_word"):
    start_wake_word_service()

要把「重启生效」升级成「秒级生效」，把开关的存储从环境变量换成 Redis / 数据库，请求时查询（加本地短缓存）。这时必须直面配置热更新的复杂度账单：同一进程内两个请求可能看到不同配置，代码要能容忍「开关中途变化」；读配置与用配置之间可能不一致（查完开关、处理到一半被关闭）；缓存失效与并发读带来一整类新 bug。经验阈值：开关数量少、变更频率低，重启式开关最划算；只有灰度发布、高频实验这类真实需求，才值得引入远程配置中心（Nacos、Apollo、etcd 一类），并配套灰度策略与回滚预案。

三、K8s 环境：ConfigMap 与 Secret#

容器编排环境里，「环境变量从哪来」由平台接管。K8s 的两个注入原语：

• ConfigMap：非敏感配置（端点、日志级别），以键值或文件形式挂进 Pod；
• Secret：敏感配置，机制类似但独立存储，K8s 侧可控权限（base64 只是编码不是加密，集群的 RBAC 与加密静态存储才是安全层）。

# deployment 片段：把 ConfigMap 与 Secret 注入为环境变量
envFrom:
  - configMapRef:
      name: toy-backend-config
  - secretRef:
      name: toy-backend-secrets

对 Python 代码完全透明：它们最终就是普普通通的环境变量，pydantic-settings 原样接收。要点是分工：镜像里只有代码没有配置（Docker 的原则），配置全部走 ConfigMap/Secret 注入，同一镜像即可推遍所有环境。更大规模的组织会用外部密钥系统（HashiCorp Vault、云厂商 Secret Manager）做密钥的集中发放与轮换，K8s 通过 CSI 驱动挂接——知道这条链路存在即可。

四、配置的测试策略#

配置代码也要测试，三个固定套路：

def test_missing_key_fails_fast(monkeypatch):
    monkeypatch.delenv("TOY_API_KEY", raising=False)
    with pytest.raises(ValidationError):
        get_settings()                     # 缺密钥必须启动即炸

def test_bool_parsing(monkeypatch):
    monkeypatch.setenv("TOY_WAKE_WORD", "false")
    monkeypatch.setenv("TOY_API_KEY", "sk-test")
    assert get_settings().wake_word is False   # 字符串 "false" 必须是 False

def test_priority_env_over_dotenv(monkeypatch):
    monkeypatch.setenv("TOY_LOG_LEVEL", "WARNING")
    assert get_settings().log_level == "WARNING"

纪律三条：测试只用 monkeypatch 注入，绝不依赖开发者本机的 .env（CI 没有它）；测试结束 monkeypatch 自动还原，全局环境零残留；给配置模型建立「合法值清单」测试，字段一改测试先红。主线篇的挑战题就是这三条的完整落地。

五、密钥的威胁模型：五问自检#

配置安全说到底是一张短清单，逐问自检你的项目：

1. 密钥有没有可能出现在 Git 历史？（.gitignore 起步，敏感仓库上 gitleaks 这类扫描器进 CI）
2. 密钥会不会进日志与异常栈？（SecretStr / 脱敏中间件；日志侧再拦一层）
3. 每个密钥的权限是不是最小？（只读桶密钥干不了删库的事）
4. 泄漏后多久能轮换？（密钥按「必然泄漏」设计：可作废、可轮换、有台账）
5. 本地 .env 与云上 Secret 的分发链路是否都过了人手？（能自动化就不经手）

六、三张全景表：选型速查#

配置库：

配置格式：

配置源（按运维成本升序）：

判断链：需求从「能跑」到「启动校验」到「多环境」到「运行期可变」逐步升级，方案跟着需求升级，不要为单脚本引入集群级方案。

自我检查#

• 能说出从 pydantic-settings 升级 Dynaconf 的触发信号；
• 能实现环境变量驱动的最小特性开关，并说出热更新的三重代价；
• 能区分 ConfigMap 与 Secret 的用途，并说出 base64 不是加密；
• 能默写配置测试三套路（缺项即炸、布尔解析、优先级）；
• 能逐条回答密钥五问。

练习#

预测题：TOY_ENV 未设置时，Dynaconf 取 settings.toml 的哪一段？（default。）TOY_ENV=staging 但文件里没有 [staging] 段，会发生什么？动手验证。

修改题：把主线篇的玩具服务改造成双开关灰度：wake_word 与 new_billing 走 FeatureFlags，写 pytest 验证「未设置的开关必须为 False」（fail-closed 原则）。

排错题：团队反映 K8s 里改了 ConfigMap，Pod 里的服务十分钟后才看到新值。解释这条链路（挂载卷约 60 秒同步 + 应用层缓存），并给出两个加快生效的方案（重启 Pod / 应用侧主动监听）。

挑战题：为 FeatureFlags 加「百分比灰度」：rollout("new_billing", user_id) 按 user_id 哈希稳定地放行 N% 用户（同一用户多次查询结果必须一致）。写 hypothesis 测试验证稳定性与比例近似。

下一步#

• 配置注入的容器形态：Python 与 Docker；
• 特性开关与灰度的工程化版本（实验平台、指标回收）超出了单机 Python 的范围，但决策思想与 可观测性日志 相通：先能看见，再谈变更；
• Dynaconf 官方文档：https://www.dynaconf.com/