Python敏感信息管理实践指南：使用环境变量与配置文件实现代码分离

先想象这样一个场景：周五晚上，大家正准备冲去吃火锅，结果运维在群里艾特你：“谁把生产库密码写代码里的？已经被某同事截图发到需求群了。” 那一瞬间，这个周末大概率就泡汤了。

事实上，在许多 Python 项目中，最容易踩的坑往往不是高并发或复杂的协程，而是将代码与敏感信息混杂在一起编写。数据库密码、API Token、Access Key 等直接硬编码在 .py 文件中，不仅修改困难，一旦泄露也难以追溯。

那么，如何用 Python 既优雅又不太复杂地实现代码与敏感信息的彻底分离呢？我们先明确一下，到底哪些算“敏感信息”。

明确敏感信息的范围

在考虑引入 Vault、KMS 等高级方案前，先划定清晰的范围是关键。通常，以下信息不应直接写入 Python 源码：

• 数据库连接字符串、账号密码。
• Redis、消息队列等中间件的认证信息。
• 第三方平台（如支付、地图、OpenAPI）的 Key 和 Secret。
• JWT 签名密钥、对称加密密钥。
• 内部系统的管理账号或默认密码。

可以记住一个简单的原则：只要切换环境（开发、测试、生产）时需要随之更改的配置，就不应该写死在代码里。

最常见的反面教材

许多项目起步时都写过类似的代码（看起来非常眼熟）：

# config.py

DB_URL = "mysql://root:root123@127.0.0.1:3306/demo"
REDIS_URL = "redis://:redis123@127.0.0.1:6379/0"
PAYMENT_SECRET = "very-secret-key"

这样做的好处是简单直观，本地运行通畅。但问题同样明显：

1. 一旦提交到 Git，即使后续删除，历史记录中依然存在。
2. 新成员克隆仓库后，能直接看到生产环境密码，带来安全和合规风险。
3. 切换测试或预发布环境时，需要修改代码并重新提交，极易出错或混淆环境。

简而言之：初期省事，后期持续偿还技术债。

核心原则：代码只引用环境变量

如果你只能记住一个原则，那就是：Python 代码中只应出现变量名，而非真实的密码字符串。

改进后的写法如下：

# config.py
import os

DB_URL = os.getenv("APP_DB_URL")
REDIS_URL = os.getenv("APP_REDIS_URL")
PAYMENT_SECRET = os.getenv("APP_PAYMENT_SECRET")

然后在不同环境中，通过设置环境变量来注入这些值即可。

本地开发时，可以这样操作：

export APP_DB_URL="mysql://root:devpwd@127.0.0.1:3306/demo"
export APP_REDIS_URL="redis://:devredis@127.0.0.1:6379/0"
export APP_PAYMENT_SECRET="dev-secret"
python main.py

这种方式有几个优势：

• 代码仓库可以相对安全地分享给更多人。
• 环境切换只需改动环境变量，无需触碰代码。
• 与 Docker、Kubernetes 及 CI/CD 流程天然契合。

然而，直接使用 os.getenv 存在两个小缺陷：

1. 如果忘记配置环境变量，代码可能静默地使用 None，导致程序在运行时意外崩溃。
2. 配置分散，类型转换和默认值管理不便。

这便引出了下一个更优雅的方案。

进阶实践：使用配置对象统一管理

在 Python 中，创建一个 settings 对象来集中管理所有配置是更佳实践。代码只需依赖此对象，无需关心配置来源。

首先是一个不依赖第三方库的极简实现：

# settings.py
import os
from dataclasses import dataclass

class ConfigError(RuntimeError):
    pass

def _get_env(name: str, default=None, required: bool = False) -> str:
    value = os.getenv(name, default)
    if required and value is None:
        raise ConfigError(f"环境变量 {name} 必须配置")
    return value

@dataclass(frozen=True)
class Settings:
    db_url: str
    redis_url: str
    payment_secret: str
    env: str = "dev"  # dev / test / prod

def load_settings() -> Settings:
    return Settings(
        db_url=_get_env("APP_DB_URL", required=True),
        redis_url=_get_env("APP_REDIS_URL", required=True),
        payment_secret=_get_env("APP_PAYMENT_SECRET", required=True),
        env=_get_env("APP_ENV", default="dev"),
    )

settings = load_settings()

在业务代码中这样使用：

# main.py
from settings import settings

def connect_db():
    print("连接数据库：", settings.db_url)
    # 这里再去创建 engine / pool

if __name__ == "__main__":
    print("当前环境：", settings.env)
    connect_db()

这种模式的优点在于：

• 统一入口：所有敏感信息都通过 Settings 对象获取。
• 强制校验：必要的配置（如 APP_PAYMENT_SECRET）缺失时，程序会在启动阶段立即报错，而非在运行时才暴露问题。
• 类型明确：便于在 load_settings 函数中进行类型转换（如转为 int、bool）。

请牢记：敏感信息应集中在一两处管理，避免散落在代码各处，否则在排查问题时将异常困难。

开发便利：结合 .env 文件

每次在终端手动输入一堆 export 命令显然不现实。此时，.env 文件是本地开发的利器。

在项目根目录创建 .env 文件（切记不要提交到 Git）：

# .env
APP_DB_URL="mysql://root:devpwd@127.0.0.1:3306/demo"
APP_REDIS_URL="redis://:devredis@127.0.0.1:6379/0"
APP_PAYMENT_SECRET="dev-secret"
APP_ENV="dev"

并确保在 .gitignore 中添加：

.env

在 Python 中，可以使用 python-dotenv 库轻松加载：

pip install python-dotenv

代码调整如下：

# settings.py
import os
from dataclasses import dataclass
from dotenv import load_dotenv

# 优先加载 .env 文件中的变量
load_dotenv()

# ... 其余部分与之前相同，_get_env 仍使用 os.getenv

这样，在本地开发时使用 .env 文件方便管理；在测试或生产环境，则由运维直接设置环境变量，无需 .env 文件。

重要提示：.env 文件仅是开发便利工具，并非安全方案本身。安全的本质仍在于通过环境变量注入密钥，而非将其硬编码在代码中。

环境配置策略：避免多个配置文件

有些项目会为不同环境创建多个配置文件，如 settings_dev.py、settings_prod.py，并在主程序中通过注释切换导入语句。这种方式极易因人为疏忽导致环境错配（例如线上环境连到了测试数据库）。

更好的做法是：通过一个环境变量（如 APP_ENV）来控制当前环境，所有具体配置（如数据库地址）依然从环境变量中读取。

你可以在 Settings 类中添加一些便于区分的属性：

@dataclass(frozen=True)
class Settings:
    db_url: str
    redis_url: str
    payment_secret: str
    env: str = "dev"

    @property
    def debug(self) -> bool:
        return self.env != "prod"

业务代码只需判断 settings.debug：

from settings import settings

if settings.debug:
    print("Debug 模式，打开一些调试开关")

至于各个环境具体使用哪个数据库地址，完全由运维在对应环境里配置 APP_DB_URL 等变量，开发者无需关心。

混合方案：配置文件与环境变量结合

对于一些复杂的非敏感配置（如业务开关、白名单），你可能更倾向于使用 yaml 或 toml 文件。此时可以采用混合方案：配置文件存放非敏感信息，敏感信息依然通过环境变量注入。

例如，可提交至 Git 的 config.yaml：

# config.yaml
app:
  name: "demo-service"
  log_level: "INFO"

feature_flags:
  enable_new_login: true

敏感信息仍在环境变量中，settings.py 可这样编写：

# settings.py
import os
import yaml
from dataclasses import dataclass
from pathlib import Path

@dataclass(frozen=True)
class Settings:
    app_name: str
    log_level: str
    db_url: str
    payment_secret: str

def load_yaml_config(path: str = "config.yaml") -> dict:
    text = Path(path).read_text("utf-8")
    return yaml.safe_load(text)

def load_settings() -> Settings:
    cfg = load_yaml_config()
    return Settings(
        app_name=cfg["app"]["name"],
        log_level=cfg["app"]["log_level"],
        db_url=os.environ["APP_DB_URL"],
        payment_secret=os.environ["APP_PAYMENT_SECRET"],
    )

settings = load_settings()

这种分离方式在安全性和可维护性之间取得了良好平衡。

对接专业的秘密管理服务

当项目部署在云平台或 Kubernetes 中时，可以利用现有的秘密管理服务，如云厂商的 Secret Manager、Kubernetes Secrets 或自建的 HashiCorp Vault。

对于 Python 代码而言，核心思路不变：业务代码依然只从统一的 Settings 对象获取配置，只是 Settings 的底层加载方式从环境变量变为调用秘密管理服务的 API。

以下是一个高度简化的示例，展示思路：

# secret_loader.py (示例)
import os
import json
from typing import Any

def load_secret(name: str) -> Any:
    """
    一个简化的 Secret 加载器示例。
    实际项目中，这里会替换为请求 Vault 或云 Secret Manager 的客户端调用。
    此处假设秘密以JSON字符串形式存入环境变量。
    """
    raw = os.getenv(name)
    if raw is None:
        raise RuntimeError(f"找不到密钥：{name}")
    try:
        return json.loads(raw)
    except json.JSONDecodeError:
        return raw

在 settings.py 中使用：

# settings.py
from dataclasses import dataclass
from secret_loader import load_secret

@dataclass(frozen=True)
class Settings:
    db_url: str
    payment_secret: str

def load_settings() -> Settings:
    return Settings(
        db_url=load_secret("APP_DB_URL"),
        payment_secret=load_secret("APP_PAYMENT_SECRET"),
    )

settings = load_settings()

这样，当部署方式升级时，只需修改底层的 load_secret 实现，业务代码无需任何改动。

两个易忽略的要点：日志与错误处理

即使实现了代码与配置的分离，仍有两点可能导致信息泄露：

1. 日志中避免输出敏感信息
调试时，可能会顺手写下这样的日志：

import logging
from settings import settings

logging.info("当前配置：%s", settings) # 危险！

如果 Settings 类的 __repr__ 方法未做处理，完整的连接字符串和密钥将被记录到日志中，而日志系统往往有多人访问权限。

一个简单的解决方案是为配置对象实现一个安全的展示方法：

# settings.py
from dataclasses import dataclass, asdict

@dataclass(frozen=True)
class Settings:
    db_url: str
    redis_url: str
    payment_secret: str
    env: str = "dev"

    def safe_dict(self):
        data = asdict(self)
        # 对敏感字段进行脱敏
        data["db_url"] = "***hidden***"
        data["redis_url"] = "***hidden***"
        data["payment_secret"] = "***hidden***"
        return data

使用时：

logging.info("当前配置(脱敏)：%s", settings.safe_dict())

2. 错误信息中也应脱敏
当数据库连接失败时，切勿将完整的连接字符串（包含密码）直接抛出或打印。通常，日志只需记录“连接失败”、“超时”等概要信息，具体的账号密码问题应由运维人员通过配置管理后台核查。

总结：清晰的架构分层

我们可以将整个方案抽象为一个清晰的三层结构：

• 底层：环境变量 / 秘密管理服务 / .env 文件（仅用于开发）。这是所有敏感信息的来源。
• 中间层：一个统一的 Settings 对象（或配置模块）。它负责从底层读取所有配置，进行校验、类型转换和脱敏处理。
• 上层：业务代码。它只通过 settings.xxx 的方式获取所需配置，对密码等敏感信息的具体形态一无所知。

只要遵循这一核心模式，就实现了代码与敏感信息的优雅分离。未来无论是集成 Docker、Kubernetes，还是接入 Vault，都只需在底层进行调整，业务逻辑可以保持不变。

当你在深夜排查问题时，看到代码中没有散落各处的密码，只有一个清晰、统一的 settings 对象，你会感谢当初在配置管理上投入的这部分精力。良好的实践是稳定与安全的基石。