Python项目中密钥和API密钥的管理指南（.env文件详解）-青云TOP-AI综合资源站平台|青云聚合API大模型调用平台|全网AI资源导航平台

📢 转载信息

原文链接：https://www.kdnuggets.com/managing-secrets-and-api-keys-in-python-projects-env-guide

原文作者：Kanwal Mehreen

Managing Secrets and API Keys in Python Projects (.env Guide)

Image by Author

# 安全密钥存储简介

将API密钥、数据库密码或令牌等敏感信息直接存储在Python代码中是十分危险的。如果这些密钥泄露，攻击者可能会入侵您的系统，您的组织将面临信任丧失、财务和法律后果。相反，您应该将密钥外部化，使其永远不出现在代码或版本控制中。一个常见的最佳实践是将密钥存储在环境变量中（代码外部）。这样，密钥就不会出现在代码库中。尽管手动设置环境变量可行，但对于本地开发而言，将所有密钥保存在单个.env文件中更为方便。

本文将解释七种在Python项目中管理密钥的实用技术，并提供代码示例和常见陷阱的说明。

# 技术 1：在本地使用.env文件（并安全加载）

.env 文件是由 KEY=value 对组成的文本文件，您将其保存在本地（不提交到版本控制）。它允许您为开发定义特定于环境的设置和密钥。例如，推荐的项目布局是：

my_project/
    app/
        main.py
        settings.py
    .env # 不提交 – 包含真实密钥
    .env.example # 提交 – 列出所需密钥但不包含真实值
    .gitignore
    pyproject.toml

您的真实密钥保存在本地的.env文件中，例如：

# .env (仅限本地，绝不提交)
OPENAI_API_KEY=your_real_key_here
DATABASE_URL=postgresql://user:pass@localhost:5432/mydb
DEBUG=true

相比之下，.env.example 是一个供其他开发人员查看所需密钥的模板文件，应该提交到代码库中：

# .env.example (提交此文件)
OPENAI_API_KEY=
DATABASE_URL=
DEBUG=false

在 Git 中添加模式以忽略这些文件：

.env
.env.*

这样可以确保您的秘密.env文件不会意外被检入。在 Python 中，惯用做法是使用 python-dotenv 库，它将在运行时加载.env文件。例如，在 app/main.py 中，您可以这样编写：

# app/main.py
import os
from dotenv import load_dotenv

load_dotenv() # 读取 .env 文件中的变量到 os.environ

api_key = os.getenv("OPENAI_API_KEY")

if not api_key:
    raise RuntimeError("Missing OPENAI_API_KEY. Set it in your environment or .env file.")

print("App started (key loaded).")

在这里，load_dotenv() 会自动在工作目录中查找.env文件，并将每个 key=value 对设置到 os.environ 中（除非该变量已经设置）。这种方法避免了提交 .env 或不安全共享的常见错误，同时为您提供了一个干净、可重现的开发环境。您可以在不同机器或开发设置之间切换而无需修改代码，并且本地密钥保持安全。

# 技术 2：从环境中读取密钥

一些开发人员会在代码中放置占位符，如 API_KEY="test"，或假设变量在开发环境中始终已设置。这在他们的机器上可能有效，但在生产环境中可能会失败。如果缺少密钥，占位符可能会被执行，从而造成安全风险。因此，务必在运行时从环境变量中获取密钥。在 Python 中，您可以使用 os.environ 或 os.getenv 安全地获取值。例如：

def require_env(name: str) -> str:
    value = os.getenv(name)
    if not value:
        raise RuntimeError(f"Missing required environment variable: {name}")
    return value

OPENAI_API_KEY = require_env("OPENAI_API_KEY")

这使得您的应用在启动时如果缺少密钥就会快速失败，这比使用缺失的或虚拟值继续运行要安全得多。

# 技术 3：使用设置模块验证配置

随着项目规模的扩大，许多分散的 os.getenv 调用会变得杂乱且容易出错。使用像 Pydantic 的 BaseSettings 这样的设置类，可以集中配置、验证类型，并从 .env 和环境中加载值。例如：

# app/settings.py
from pydantic_settings import BaseSettings, SettingsConfigDict
from pydantic import Field

class Settings(BaseSettings):
    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
    
    openai_api_key: str = Field(min_length=1)
    database_url: str = Field(min_length=1)
    debug: bool = False

settings = Settings()

然后在您的应用中：

# app/main.py
from app.settings import settings

if settings.debug:
    print("Debug mode on")

api_key = settings.openai_api_key

这可以防止因键输入错误、类型解析错误（如 "false" vs False）或重复的环境查找而导致的错误。使用设置类可以确保如果密钥丢失，您的应用会快速失败，并避免出现“在我机器上可以运行”的问题。

# 技术 4：使用平台/CI密钥进行部署

当您部署到生产环境时，不应复制本地的 .env 文件。相反，请使用托管/CI平台的密钥管理功能。例如，如果您在 CI 中使用 GitHub Actions，您可以将密钥加密存储在仓库设置中，然后将它们注入到工作流中。这样，您的 CI 或云平台就会在运行时注入真实值，而您永远不会在代码或日志中看到它们。

# 技术 5：Docker

在 Docker 中，应避免将密钥烘焙到镜像中或使用纯 ENV 变量。Docker 和 Kubernetes 提供了比环境变量更安全的密钥机制，因为环境变量可能会通过进程列表或日志泄露。对于本地开发，.env 配合 python-dotenv 方案有效，但在生产容器中，应挂载密钥或使用 docker secret。避免在 Dockerfiles 中使用 ENV API_KEY=... 或在 Compose 文件中提交包含密钥的配置。这样做可以降低密钥永久暴露在镜像中的风险，并简化密钥轮换。

# 技术 6：添加防护栏

人会犯错，所以要实现密钥保护的自动化。GitHub 的推送保护功能可以阻止包含密钥的提交，而像 TruffleHog 或 Gitleaks 这样的 CI/CD 密钥扫描工具可以在合并前检测到泄露的凭据。初学者通常依赖记忆或速度，这会导致意外提交。防护栏可以在泄露发生之前阻止它们进入仓库，使您在开发和部署过程中使用 .env 和环境变量时更加安全。

# 技术 7：使用真正的密钥管理器

对于大型应用，使用专业的密钥管理器（如 HashiCorp Vault、AWS Secrets Manager 或 Azure Key Vault）是很有意义的。这些工具控制谁可以访问密钥、记录每一次访问，并自动轮换密钥。如果没有此类工具，团队通常会重复使用密码或忘记轮换密钥，这很危险。密钥管理器可以使一切尽在掌控，简化轮换，并在开发人员的本地 .env 文件或计算机被泄露时保护您的生产系统。

# 总结

保护密钥安全不仅仅是遵守规则。它是要构建一个使您的项目安全、易于维护并可在不同环境中移植的工作流程。为了使这更容易，我为您在 Python 项目中可以使用的清单：

.env 文件在 .gitignore 中（切勿提交真实凭据）
存在 .env.example 且其中包含空值并已提交
代码仅通过环境变量读取密钥（os.getenv、设置类等）
如果缺少必需的密钥，应用会快速失败并给出清晰的错误提示
您为开发、分期和生产使用不同的密钥（切勿重复使用相同的密钥）
CI 和部署使用加密的密钥（GitHub Actions 密钥、AWS Parameter Store 等）
您的仓库启用了推送保护或密钥扫描功能
您有轮换策略（如果泄露，立即轮换密钥；否则定期轮换）

Kanwal Mehreen 是一位机器学习工程师和技术作家，对数据科学以及人工智能与医学的交叉领域怀有深厚的热情。她合著了电子书《Maximizing Productivity with ChatGPT》。作为 2022 年亚太地区谷歌一代学者，她倡导多样性和学术卓越。她还获得了 Teradata 技术多样性学者、Mitacs Globalink 研究学者和哈佛 WeCode 学者等荣誉。Kanwal 是一位热情的变革倡导者，她创立了 FEMCodes 来赋能 STEM 领域的女性。

🚀 想要体验更好更全面的AI调用？

欢迎使用青云聚合API，约为官网价格的十分之一，支持300+全球最新模型，以及全球各种生图生视频模型，无需翻墙高速稳定，文档丰富，小白也可以简单操作。

目录CONTENT

Python项目中密钥和API密钥的管理指南（.env文件详解）