متغيرات البيئة للوكلاء

لماذا لا ينبغي تضمين مفاتيح API مباشرة في الشفرة؟

مشكلة سجل Git

import os

os.environ['OPENAI_API_KEY'] = 'sk-proj-abc123def456'  # simulate deployment env

OPENAI_API_KEY = os.environ['OPENAI_API_KEY']
print('Key loaded from environment — never hard-coded')

os.environ[] في مقابل os.getenv()

import os

os.environ['OPENAI_API_KEY'] = 'sk-proj-demo-key'

try:
    openai_key = os.environ['OPENAI_API_KEY']
except KeyError:
    print('ERROR: OPENAI_API_KEY environment variable is not set!')
    raise

model = os.getenv('AGENT_MODEL', 'gpt-4o-mini')
timeout = float(os.getenv('AGENT_TIMEOUT', '30'))
log_level = os.getenv('LOG_LEVEL', 'INFO')
max_steps = int(os.getenv('AGENT_MAX_STEPS', '20'))

print(f'Model: {model}, Timeout: {timeout}s, Log: {log_level}')

التحقق من متغيرات البيئة المطلوبة عند بدء التشغيل

import os
import sys

REQUIRED_VARS = [
    'OPENAI_API_KEY',
    'SEARCH_API_KEY',
    'DATABASE_URL'
]

def check_required_env_vars():
    missing = [var for var in REQUIRED_VARS if not os.getenv(var)]
    if missing:
        print('FATAL: Missing required environment variables:')
        for var in missing:
            print(f'  - {var}')
        print('\nSet these in your .env file or shell environment.')
        sys.exit(1)
    print(f'All {len(REQUIRED_VARS)} required environment variables are set.')

# Call this at the very start of your agent:
# check_required_env_vars()

if __name__ == '__main__':
    for var in REQUIRED_VARS:
        os.environ.setdefault(var, 'demo-value')
    check_required_env_vars()

مبدأ تطبيق 12-Factor

import os

os.environ['OPENAI_API_KEY'] = 'sk-proj-demo'
os.environ['SEARCH_API_KEY'] = 'tvly-demo'
os.environ['DATABASE_URL'] = 'postgresql://user:pass@localhost/agentdb'

config = {
    'openai_key': os.environ['OPENAI_API_KEY'],
    'search_key': os.environ['SEARCH_API_KEY'],
    'database_url': os.environ['DATABASE_URL'],
    'redis_url': os.getenv('REDIS_URL', 'redis://localhost:6379'),
    'enable_caching': os.getenv('ENABLE_CACHING', 'true') == 'true',
    'max_results': int(os.getenv('MAX_RESULTS', '10')),
    'log_level': os.getenv('LOG_LEVEL', 'INFO'),
    'env': os.getenv('ENV', 'development')
}

print('Config loaded from environment:', config['env'])

تعيين متغيرات البيئة في الصدفة

# Mac/Linux (bash/zsh):
# export OPENAI_API_KEY='sk-proj-your-key-here'
# export AGENT_MODEL='gpt-4o-mini'
# python agent.py

# Windows (Command Prompt):
# set OPENAI_API_KEY=sk-proj-your-key-here
# python agent.py

# Windows (PowerShell):
# $env:OPENAI_API_KEY = 'sk-proj-your-key-here'
# python agent.py

# One-liner (temporary, only for this command):
# OPENAI_API_KEY='sk-proj-...' python agent.py

print('Shell exports set env vars for the current session only')

إدراج المتغيرات المطلوبة في تعليقات الشفرة

# agent.py
#
# REQUIRED ENVIRONMENT VARIABLES:
#   OPENAI_API_KEY       OpenAI API key (get from platform.openai.com)
#   SEARCH_API_KEY       Tavily search API key (get from tavily.com)
#
# OPTIONAL ENVIRONMENT VARIABLES:
#   AGENT_MODEL          LLM model (default: gpt-4o-mini)
#   AGENT_MAX_STEPS      Max loop iterations (default: 20)
#   LOG_LEVEL            Logging verbosity: DEBUG|INFO|WARNING (default: INFO)
#   DATABASE_URL         PostgreSQL URL (default: none, disables memory storage)
#
# EXAMPLE SETUP:
#   cp .env.example .env
#   Edit .env with your keys
#   python agent.py --query 'Your question'

print('Document required variables at the top of each agent file')

الوصول الآمن إلى الإعدادات المتداخلة

import os

class AgentConfig:
    def __init__(self):
        self.openai_key = self._require('OPENAI_API_KEY')
        self.search_key = self._require('SEARCH_API_KEY')
        self.model = os.getenv('AGENT_MODEL', 'gpt-4o-mini')
        self.max_steps = int(os.getenv('AGENT_MAX_STEPS', '20'))
        self.log_level = os.getenv('LOG_LEVEL', 'INFO')
        self.env = os.getenv('ENV', 'development')

    def _require(self, key: str) -> str:
        value = os.getenv(key)
        if not value:
            raise EnvironmentError(
                f'Required environment variable {key} is not set. '
                f'See .env.example for setup instructions.'
            )
        return value

# config = AgentConfig()  # raises clear error if any key is missing
# client = openai.OpenAI(api_key=config.openai_key)

if __name__ == '__main__':
    os.environ.setdefault('OPENAI_API_KEY', 'sk-demo-1234')
    os.environ.setdefault('SEARCH_API_KEY', 'demo-search-key')
    config = AgentConfig()
    print(f'Model: {config.model}, max_steps: {config.max_steps}, env: {config.env}')

إخفاء المفاتيح في السجلات

import os

def mask_key(key: str) -> str:
    if not key or len(key) < 8:
        return '****'
    return '*' * (len(key) - 4) + key[-4:]

def log_config_summary(config: dict):
    print('Agent configuration:')
    for name, value in config.items():
        if 'key' in name.lower() or 'secret' in name.lower() or 'token' in name.lower():
            print(f'  {name}: {mask_key(value)}')
        else:
            print(f'  {name}: {value}')

config = {
    'openai_key': os.getenv('OPENAI_API_KEY', ''),
    'model': 'gpt-4o-mini',
    'max_steps': '20'
}
log_config_summary(config)
# openai_key: ****abcd
# model: gpt-4o-mini

متغيرات البيئة في Docker وCI

# Docker run with env vars:
# docker run -e OPENAI_API_KEY='sk-...' -e AGENT_MODEL='gpt-4o-mini' myagent:latest

# Docker with an env file:
# docker run --env-file .env myagent:latest

# GitHub Actions workflow (secrets stored in repo settings):
# env:
#   OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
#   SEARCH_API_KEY: ${{ secrets.SEARCH_API_KEY }}

# docker-compose.yml:
# services:
#   agent:
#     image: myagent:latest
#     env_file:
#       - .env

print('Never bake secrets into Docker images — always inject at runtime')

ما الذي ينبغي فعله عند كشف مفتاح؟

# Immediate response if a key is exposed:
# 1. REVOKE the key immediately (provider dashboard)
#    OpenAI: platform.openai.com/api-keys -> Delete key
#    Anthropic: console.anthropic.com -> API Keys
# 2. Generate a new key
# 3. Update your .env file with the new key
# 4. Rotate in all environments (staging, prod)

# Remove from git history (does NOT guarantee removal from forks/clones):
# git filter-branch or git-filter-repo to rewrite history
# Force push to all branches

# Note: Rewriting git history cannot undo exposure
# if others have already cloned or forked the repo
print('Revoke immediately. Do not just remove from code — rotate the key.')

اختبار المعرفة: متغيرات البيئة

مراجعة: متغيرات البيئة للوكلاء