⚡

环境配置技能Skill env-config

本技能是关于使用UV工具进行Python项目环境配置与密钥管理的完整指南。它详细介绍了如何通过.env文件、环境变量和加密手段来安全地管理API密钥、数据库连接等敏感信息，并支持开发、测试、生产等多环境配置。核心内容包括配置与代码分离原则、安全最佳实践、依赖管理、配置验证及测试方法，旨在帮助开发团队构建安全、可维护且符合12要素应用标准的项目配置体系。关键词：Python环境配置，UV包管理，.env文件管理，密钥加密，多环境设置，安全配置模式，12要素应用，Pydantic验证，DevOps配置。

DevOps 0 次安装 0 次浏览 更新于 3/2/2026

name: env-config description: 使用 UV 进行 Python 项目环境配置和密钥管理的技能。处理 .env 文件、环境变量、密钥加密、多环境设置和安全配置模式。在设置项目环境、管理 API 密钥或实施配置最佳实践时使用。

环境配置技能

概述

本技能提供了使用 UV（现代 Python 包和项目管理器）管理 Python 项目中环境配置、密钥和环境变量的全面指导。涵盖了安全配置模式、多环境设置、.env 文件管理以及支持加密的密钥处理。

环境配置对于将配置与代码分离（12要素应用原则）、跨环境安全地管理密钥、防止凭证泄露以及支持团队协作至关重要。

何时使用此技能

在以下情况下使用此技能：

  • 为新 Python 项目设置环境配置
  • 实施安全的密钥管理
  • 配置多环境设置（开发/预发布/生产）
  • 从硬编码配置迁移到环境变量
  • 审计现有配置是否存在安全问题
  • 跨团队项目标准化配置
  • 使用适当的配置管理设置基于 UV 的 Python 项目

核心原则

1. 绝不硬编码密钥

  • 所有 API 密钥、密码、令牌都应放入环境变量或加密的密钥中
  • 包含密钥的配置文件必须添加到 .gitignore
  • 使用模板来共享结构，而非实际密钥

2. 按环境分离

  • 为开发、预发布、生产环境提供不同的配置
  • 特定于环境的 .env 文件（.env.development, .env.production）
  • 清晰的环境变量命名约定

3. 安全地失败

  • 在启动时验证必需的环境变量
  • 为缺失的配置提供清晰的错误信息
  • 仅对非敏感值使用合理的默认值

4. 使用 UV 进行依赖管理

  • UV 提供快速、可靠的 Python 包管理
  • 替代 pip、pip-tools、virtualenv 等工具
  • 确保跨机器的可重现环境

5. 记录一切

  • 模板文件展示结构而不暴露密钥
  • README 解释所需变量及其设置方法
  • 注释描述变量的用途和格式

UV 设置

安装 UV

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# 或使用 pip
pip install uv

# 验证安装
uv --version

初始化 UV 项目

# 创建新项目
uv init my-project
cd my-project

# 创建虚拟环境
uv venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# 添加依赖
uv add python-dotenv cryptography pydantic

# 添加开发依赖
uv add --dev pytest pytest-env black ruff

环境配置工作流

阶段 1：项目设置

1. 创建项目结构

# 初始化 UV 项目
uv init your-project-name
cd your-project-name
uv venv
source .venv/bin/activate

2. 安装配置依赖

uv add python-dotenv      # 用于加载 .env 文件
uv add cryptography       # 用于密钥加密（可选）
uv add pydantic          # 用于配置验证（可选）
uv add --dev pytest pytest-env

3. 创建配置文件

需要创建的基本文件：

  • .env.template - 显示所需变量的模板（提交此文件）
  • .env - 实际密钥（添加到 .gitignore）
  • .env.development - 开发环境特定配置
  • .env.production - 生产环境特定配置
  • config.py - 配置加载模块

4. 更新 .gitignore

# 添加到 .gitignore
cat >> .gitignore << 'EOF'
# 环境文件
.env
.env.local
.env.*.local
secrets.json

# UV
.venv/
__pycache__/
*.pyc
.pytest_cache/
.ruff_cache/
EOF

阶段 2：创建配置模板

1. 创建 .env.template

# .env.template - 提交此文件
# 复制到 .env 并填写实际值

# 应用程序设置
APP_NAME=MyApp
APP_ENV=development
DEBUG=true
LOG_LEVEL=INFO

# 数据库配置
DATABASE_URL=postgresql://user:password@localhost:5432/dbname
DATABASE_POOL_SIZE=5

# API 密钥（替换为实际密钥）
ANTHROPIC_API_KEY=sk-ant-api03-xxx
OPENAI_API_KEY=sk-xxx
OPENROUTER_API_KEY=sk-or-v1-xxx

# 安全
SECRET_KEY=generate-random-secret-key-here
JWT_SECRET=another-random-secret

# 功能开关
ENABLE_ANALYTICS=false
ENABLE_CACHING=true

2. 创建配置加载模块

创建 config.py - 完整实现请参阅 references/api-reference.md：

import os
from pathlib import Path
from dotenv import load_dotenv


class ConfigError(Exception):
    """当缺少必需配置时引发。"""
    pass


class Config:
    """来自环境变量的应用程序配置。"""

    def __init__(self, env: str = None):
        self.env = env or os.getenv('APP_ENV', 'development')
        self._load_env_file()
        self._validate_required()

    def _load_env_file(self):
        """根据环境加载相应的 .env 文件。"""
        env_file = Path(f'.env.{self.env}')
        if env_file.exists():
            load_dotenv(env_file, override=True)
        if Path('.env').exists():
            load_dotenv('.env', override=False)

    @property
    def app_name(self) -> str:
        return os.getenv('APP_NAME', 'MyApp')

    @property
    def debug(self) -> bool:
        return os.getenv('DEBUG', 'false').lower() in ('true', '1', 'yes')

    # 根据需要添加更多属性...


# 全局配置实例
config = Config()

有关包含所有属性和验证的完整 Config 类，请参阅 references/api-reference.md。

3. 在应用程序中使用配置

from config import config

def main():
    print(f"在 {config.app_env} 模式下启动 {config.app_name}")

    if config.anthropic_api_key:
        # 使用 API 密钥
        print("✓ API 密钥已加载")

阶段 3：多环境设置

1. 创建环境特定文件

.env.development：

APP_ENV=development
DEBUG=true
LOG_LEVEL=DEBUG
DATABASE_URL=postgresql://localhost:5432/myapp_dev

.env.production：

APP_ENV=production
DEBUG=false
LOG_LEVEL=WARNING
DATABASE_URL=postgresql://prod-host:5432/myapp_prod
SECRET_KEY=super-secure-random-key

2. 在环境之间切换

# 开发环境（默认）
uv run python main.py

# 生产环境
export APP_ENV=production
uv run python main.py

阶段 4：密钥管理

1. 使用 JSON 密钥（替代模式）

创建 secrets_template.json：

{
  "anthropic_api_key": "sk-ant-api03-xxx",
  "openai_api_key": "sk-xxx",
  "database_password": "your-password-here",
  "comment": "复制到 secrets.json 并填写真实值"
}

2. 加载 JSON 密钥

完整实现请参阅 references/api-reference.md：

import json
from pathlib import Path

def load_secrets(secrets_file: str = 'secrets.json') -> dict:
    """从 JSON 加载密钥，回退到环境变量。"""
    if Path(secrets_file).exists():
        return json.load(open(secrets_file))
    # 回退到环境变量
    return {
        'anthropic_api_key': os.getenv('ANTHROPIC_API_KEY', '')
    }

3. 加密密钥

有关加密工具和高级密钥管理，请参阅：

  • references/advanced-topics.md - 加密、轮换、审计
  • scripts/env_helper.py - 加密/解密工具

配置验证

使用 Pydantic 进行类型安全配置

from pydantic import BaseSettings, Field, validator


class Settings(BaseSettings):
    app_name: str = Field(default='MyApp', env='APP_NAME')
    app_env: str = Field(default='development', env='APP_ENV')
    database_url: str = Field(..., env='DATABASE_URL')  # 必需

    @validator('app_env')
    def validate_env(cls, v):
        allowed = ['development', 'staging', 'production']
        if v not in allowed:
            raise ValueError(f'app_env 必须是 {allowed} 中的一个')
        return v

    class Config:
        env_file = '.env'


settings = Settings()

有关完整的 Pydantic 配置示例，请参阅 references/api-reference.md。

安全最佳实践

1. .gitignore 配置

始终添加到 .gitignore：

.env
.env.local
.env.*.local
secrets.json
.env.production
.venv/

2. 密钥轮换

实施定期的 API 密钥轮换：

def rotate_api_key(old_key: str, new_key: str):
    """使用备份优雅地轮换 API 密钥。"""
    # 实现位于 references/advanced-topics.md

3. 环境审计

定期进行安全审计：

def audit_environment():
    """检查环境变量中的安全问题。"""
    # 实现位于 references/advanced-topics.md

有关完整的安全实现，请参阅 references/advanced-topics.md。

测试配置

基本测试设置

# conftest.py
import pytest
import os


@pytest.fixture
def test_env():
    """设置测试环境变量。"""
    original = os.environ.copy()
    os.environ['APP_ENV'] = 'testing'
    os.environ['DEBUG'] = 'true'
    yield
    os.environ.clear()
    os.environ.update(original)


@pytest.fixture
def config(test_env):
    from config import Config
    return Config(env='testing')

示例测试

def test_config_loading(config):
    assert config.app_env == 'testing'
    assert config.debug is True


def test_missing_required_var():
    from config import ConfigError
    with pytest.raises(ConfigError):
        Config()  # 缺少必需变量

有关全面的测试指南，请参阅 references/testing-guide.md。

UV 命令参考

# 依赖管理
uv sync                    # 安装所有依赖
uv add requests           # 添加依赖
uv add --dev pytest       # 添加开发依赖
uv remove requests        # 移除依赖

# 环境管理
uv venv                   # 创建虚拟环境
uv lock --upgrade         # 更新依赖

# 运行脚本
uv run python main.py     # 使用 UV 环境运行
uv run pytest            # 运行测试

# 兼容性
uv pip compile pyproject.toml -o requirements.txt

辅助脚本

本技能在 scripts/ 中提供了实用脚本：

  • env_helper.py - 环境管理的核心工具
    • 解析和验证 .env 文件
    • 检查缺失的变量
    • 加密/解密密钥文件
    • 比较环境
    • 生成 .env 模板

用法：

# 验证 .env 文件
python scripts/env_helper.py validate .env

# 加密密钥
python scripts/env_helper.py encrypt secrets.json secrets.encrypted

# 比较环境
python scripts/env_helper.py compare .env.development .env.production

快速参考

设置清单

  • [ ] 安装 UV：curl -LsSf https://astral.sh/uv/install.sh | sh
  • [ ] 创建项目：uv init project-name
  • [ ] 创建虚拟环境：uv venv
  • [ ] 添加依赖：uv add python-dotenv
  • [ ] 根据示例创建 .env.template
  • [ ] 复制到 .env 并填写密钥
  • [ ] 将 .env 添加到 .gitignore
  • [ ] 创建 config.py 模块
  • [ ] 测试配置加载
  • [ ] 设置环境特定配置
  • [ ] 实施验证
  • [ ] 为配置添加测试

环境变量命名

使用一致的命名：

  • APP_* - 应用程序设置
  • DATABASE_* - 数据库配置
  • *_API_KEY - API 密钥和令牌
  • *_SECRET - 密钥
  • ENABLE_* - 功能开关
  • *_URL - 服务端点

安全检查清单

  • [ ] 版本控制中没有密钥
  • [ ] .env 在 .gitignore 中
  • [ ] 生产密钥与开发环境分离
  • [ ] 必需变量在启动时已验证
  • [ ] 密钥在静止时加密（如果需要）
  • [ ] 定期密钥轮换
  • [ ] 团队接受安全实践培训

其他资源

本技能中的文档

  • references/api-reference.md - 完整的 Config 类实现、Pydantic 验证、JSON 密钥加载
  • references/advanced-topics.md - 加密、密钥轮换、审计、多租户配置、云集成
  • references/testing-guide.md - pytest 设置、模拟、验证测试、CI/CD 示例
  • references/troubleshooting.md - 常见问题、环境特定问题、调试技术

示例目录

  • .env.example - 全面的 .env 模板
  • pyproject.toml - UV 项目配置
  • secrets_template.json - JSON 密钥模板

外部资源

故障排除

有关常见问题和解决方案，请参阅 references/troubleshooting.md：

  • 环境变量未加载
  • 加载了错误的环境
  • UV sync 失败
  • 导入错误
  • 密钥解密问题
  • 性能优化
  • 安全问题与修复
  • Docker 集成问题

快速调试：

from dotenv import load_dotenv
load_dotenv(verbose=True)  # 显示加载过程