secrets-env-manager

密钥与环境变量管理器

在 CI/CD 中安全地处理密钥并验证环境变量。

环境变量验证

validate-env:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4

    - name: Validate required environment variables
      run: |
        REQUIRED_VARS=(
          "DATABASE_URL"
          "API_KEY"
          "AWS_REGION"
          "STRIPE_SECRET_KEY"
        )

        MISSING=()
        for var in "${REQUIRED_VARS[@]}"; do
          if [ -z "${!var}" ]; then
            MISSING+=("$var")
          fi
        done

        if [ ${#MISSING[@]} -ne 0 ]; then
          echo "❌ Missing required environment variables:"
          printf '%s\n' "${MISSING[@]}"
          exit 1
        fi

        echo "✅ All required environment variables are set"
      env:
        DATABASE_URL: ${{ secrets.DATABASE_URL }}
        API_KEY: ${{ secrets.API_KEY }}
        AWS_REGION: ${{ secrets.AWS_REGION }}
        STRIPE_SECRET_KEY: ${{ secrets.STRIPE_SECRET_KEY }}

密钥屏蔽

- name: Mask sensitive values
  run: |
    # Automatically masked in GitHub Actions
    echo "::add-mask::${{ secrets.API_KEY }}"
    echo "::add-mask::${{ secrets.DATABASE_PASSWORD }}"

    # Safe to use in commands
    curl -H "Authorization: Bearer ${{ secrets.API_KEY }}" https://api.example.com

防止泄漏

- name: Check for leaked secrets
  uses: trufflesecurity/trufflehog@main
  with:
    path: ./
    base: ${{ github.event.repository.default_branch }}
    head: HEAD

- name: Detect hardcoded secrets
  uses: reviewdog/action-detect-secrets@master
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    reporter: github-pr-review

特定环境的密钥

deploy:
  runs-on: ubuntu-latest
  environment:
    name: ${{ github.event.inputs.environment }}
  steps:
    - name: Deploy
      run: |
        # Environment-specific secrets are automatically scoped
        echo "Deploying to ${{ github.event.inputs.environment }}"
      env:
        DATABASE_URL: ${{ secrets.DATABASE_URL }}
        API_KEY: ${{ secrets.API_KEY }}

密钥验证脚本

// scripts/validate-env.ts
import * as fs from "fs";

interface EnvConfig {
  required: string[];
  optional: string[];
}

const config: EnvConfig = {
  required: ["DATABASE_URL", "JWT_SECRET", "STRIPE_SECRET_KEY"],
  optional: ["SENTRY_DSN", "LOG_LEVEL"],
};

function validateEnv(): boolean {
  const missing: string[] = [];

  config.required.forEach((key) => {
    if (!process.env[key]) {
      missing.push(key);
    }
  });

  if (missing.length > 0) {
    console.error("❌ Missing required environment variables:");
    missing.forEach((key) => console.error(`  - ${key}`));
    return false;
  }

  console.log("✅ All required environment variables are set");
  return true;
}

if (!validateEnv()) {
  process.exit(1);
}

.env.example 模板

# .env.example - Check into git
# Copy to .env and fill in values

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/mydb

# Authentication
JWT_SECRET=your-secret-here
JWT_EXPIRY=24h

# External APIs
STRIPE_SECRET_KEY=sk_test_...
SENDGRID_API_KEY=SG....

# AWS
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...
AWS_REGION=us-east-1

# Optional
SENTRY_DSN=https://...
LOG_LEVEL=info

文档模板

# Environment Variables

## Required Variables

### DATABASE_URL

**Description:** PostgreSQL connection string
**Format:** `postgresql://user:password@host:5432/database`
**Example:** `postgresql://app:secret@localhost:5432/myapp`
**Where to get:** Create database on Heroku/RDS

### STRIPE_SECRET_KEY

**Description:** Stripe API secret key
**Format:** `sk_test_...` or `sk_live_...`
**Example:** `sk_test_51abc123...`
**Where to get:** Stripe Dashboard → Developers → API Keys
**⚠️ Never commit to git**

## Optional Variables

### LOG_LEVEL

**Description:** Logging verbosity
**Format:** `error | warn | info | debug`
**Default:** `info`

快速失败验证

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate secrets exist
        run: |
          if [ -z "${{ secrets.DATABASE_URL }}" ]; then
            echo "::error::DATABASE_URL secret not set"
            exit 1
          fi

          if [ -z "${{ secrets.API_KEY }}" ]; then
            echo "::error::API_KEY secret not set"
            exit 1
          fi

  deploy:
    needs: validate
    runs-on: ubuntu-latest
    steps:
      - name: Deploy
        run: echo "Deploying..."

最佳实践

1. 绝不记录密钥：始终屏蔽敏感值
2. 尽早验证：在部署前检查密钥
3. 使用 GitHub Secrets：绝不在工作流中硬编码
4. 环境隔离：使用开发、预发布和生产环境的密钥
5. 定期轮换：定期更新密钥
6. 最小权限原则：仅授予最低限度的权限
7. 清晰记录：说明如何获取每个密钥
8. 扫描泄漏：自动检测

输出清单

• 已验证必需的环境变量
• 已配置密钥屏蔽
• 已启用泄漏检测
• .env.example 模板
• 已记录环境变量
• 快速失败验证
• 特定环境的密钥
• 已记录轮换策略