usage

免费 API 的安全与密钥管理

📅 2026-08-19 00:00:00 +0000 UTC 👁 2941 浏览 📂 usage

⚠️ 待更新·2026-08-29核验 · 更新时间待核验 · 本文信息可能已过期，请以官方文档为准更新时间：2026-08-29 · 核验状态：待更新 · 官方溯源待补

简介

免费 API Key 看似不值钱,但一旦泄露同样会被脚本刷爆配额,甚至被用来钓鱼或刷黑产内容,导致账号被封。本篇给出从开发到上线全链路的密钥保护清单,包含硬编码防御、git 钩子、KMS 接入、泄露应急四部分。

架构图

flowchart TD A[API Key Security] --> B[.env file - local dev] A --> C[Secret manager - production] A --> D[Git hooks - prevent leak] A --> E[Quota watchdog - detect abuse] B --> F[Single source of truth] C --> F D --> F E --> F F --> G[No key in Git, no key leaked]

第一原则:绝不硬编码

# ❌ 危险:Key 直接写在源码里
client = OpenAI(api_key="sk-or-v1-abc123...", base_url="...")

# ✅ 正确:从环境变量读
import os
client = OpenAI(api_key=os.environ["OPENROUTER_API_KEY"], base_url="...")

硬编码的 Key 会被代码搜索工具(如 GitHub 全站搜索)在数秒内发现,危险等级最高。

用 .env 文件管理本地 Key

pip install python-dotenv

项目根目录创建 .env:

OPENROUTER_API_KEY=sk-or-v1-...
GROQ_API_KEY=gsk_...
DEEPSEEK_API_KEY=sk-...

代码加载:

from dotenv import load_dotenv
load_dotenv()  # 自动把 .env 注入 os.environ

关键:.env 必须加入 .gitignore:

# .gitignore
.env
.env.*
*.pem
secrets/

防误提交的 git 钩子

装 pre-commit 与 detect-secrets:

pip install pre-commit detect-secrets
pre-commit install

.pre-commit-config.yaml:

repos:
  - repo: https://github.com/Yelp/detect-secrets
    rev: v1.5.0
    hooks:
      - id: detect-secrets
        args: ['--baseline', '.secrets.baseline']

这样每次 commit 都会扫描是否含 Key,发现就阻断。还可以加 gitleaks,规则更全。

生产环境:用密钥管理服务

不要把 .env 直接带进生产环境,改用 KMS:

AWS:Secrets Manager 或 Parameter Store
GCP:Secret Manager
阿里云:KMS 凭据管家
自建:HashiCorp Vault

示例(AWS Secrets Manager):

import boto3, json

def get_secret(name):
    client = boto3.client("secretsmanager")
    resp = client.get_secret_value(SecretId=name)
    return json.loads(resp["SecretString"])["OPENROUTER_API_KEY"]

client = OpenAI(api_key=get_secret("prod/llm-keys"), base_url="...")

额外的运维清单

设置用量告警:在每家平台后台开启"日预算超限邮件告警",异常时第一时间发现。
按用途分 Key:测试、生产、CI 各用一把,出问题精准吊销。
定期轮换:每 90 天换一次,降低长期泄露风险。
限制 IP:部分平台支持白名单,可前置 Cloudflare Workers 加 IP 校验。
日志脱敏:打印请求体时把 Authorization 头替换成 ***。

万一泄露了怎么办

立即去平台后台 吊销 Key。
查看用量日志,确认是否被滥用。
生成新 Key,更新所有部署环境。
用 git filter-repo 清理历史中的泄露提交,并通知协作者重新 clone。

常见问题

.env 已被提交:立刻吊销 Key,用 git rm --cached .env 移除,再重新生成。
CI 里怎么注入:用 GitHub Actions 的 secrets.OPENROUTER_API_KEY,在 workflow 里映射成 env。
多人共享:用 1Password / Vault 共享,而不是群里发截图。
审计追溯:在 KMS 里开启访问日志,谁取过哪个 secret 一清二楚。

安全习惯一旦养成,免费 API 用得才安心。

最佳实践

.env 文件不入 Git：.gitignore 加 .env，CI 用 secret injection。
生产用 Vault/AWS Secrets Manager：密钥 rotate、audit log、IAM 权限三层齐备。
pre-commit hook 检测密钥：detect-secrets 或 gitleaks 自动扫描 staged 文件。
配额告警：每天 cron 查询 usage，剩余额度低于 30% 就发邮件/短信。
多 Key 隔离：dev/ci/prod 各一把 Key，单点泄露影响最小化。

⚠️ Pending Update · 2026-08-29 Verification · Content may be outdated, please refer to official docs Updated: 2026-08-29 · Status: Pending Verification

Introduction

A free API key may look worthless, but a leaked one can still drain your quota, be abused for phishing or spam, and get your account banned. This article provides an end-to-end key-protection checklist covering hardcoded-key defense, git hooks, KMS integration, and incident response.

架构图

Rule One: Never Hardcode

# ❌ Dangerous: key embedded in source
client = OpenAI(api_key="sk-or-v1-abc123...", base_url="...")

# ✅ Correct: read from env
import os
client = OpenAI(api_key=os.environ["OPENROUTER_API_KEY"], base_url="...")

Hardcoded keys are discoverable by code-search tools (like GitHub's full-site search) within seconds — the highest-risk mistake you can make.

Manage Local Keys with .env

pip install python-dotenv

Create .env in the project root:

OPENROUTER_API_KEY=sk-or-v1-...
GROQ_API_KEY=gsk_...
DEEPSEEK_API_KEY=sk-...

Load it in code:

from dotenv import load_dotenv
load_dotenv()  # injects .env into os.environ

Critical: add .env to .gitignore:

# .gitignore
.env
.env.*
*.pem
secrets/

Git Hook to Prevent Accidental Commits

Install pre-commit and detect-secrets:

pip install pre-commit detect-secrets
pre-commit install

.pre-commit-config.yaml:

repos:
  - repo: https://github.com/Yelp/detect-secrets
    rev: v1.5.0
    hooks:
      - id: detect-secrets
        args: ['--baseline', '.secrets.baseline']

Every commit is scanned for secrets and blocked if found. Add gitleaks for broader rules.

Production: Use a Secret Manager

Do not ship .env to production — use a KMS:

AWS: Secrets Manager or Parameter Store
GCP: Secret Manager
Alibaba Cloud: KMS Credential Manager
Self-hosted: HashiCorp Vault

Example (AWS Secrets Manager):

import boto3, json

def get_secret(name):
    client = boto3.client("secretsmanager")
    resp = client.get_secret_value(SecretId=name)
    return json.loads(resp["SecretString"])["OPENROUTER_API_KEY"]

client = OpenAI(api_key=get_secret("prod/llm-keys"), base_url="...")

Operational Checklist

Usage alerts: Turn on daily-budget email alerts on each provider dashboard.
Separate keys per purpose: dev, prod, CI each use distinct keys so you can revoke surgically.
Rotate regularly: Every 90 days to limit long-term exposure.
IP restrictions: Some providers support allowlists. For OpenRouter, put a Cloudflare Worker in front for IP checks.
Log redaction: Replace the Authorization header with *** when logging request bodies.

If a Key Leaks

Immediately revoke the key on the provider dashboard.
Review usage logs for abuse.
Generate a new key and update every environment.
Use git filter-repo to scrub history and ask collaborators to re-clone.

Troubleshooting

.env already committed: Revoke the key immediately, run git rm --cached .env, then regenerate.
CI injection: Use GitHub Actions secrets.OPENROUTER_API_KEY mapped to an env var in the workflow.
Team sharing: Share via 1Password or Vault — never paste screenshots in chat.
Audit trail: Enable access logs in your KMS so every secret fetch is attributable.

Build these habits and your free APIs stay safe.

Best Practices

.env file never enters Git: add .env to .gitignore; in CI use secret injection.
Use Vault/AWS Secrets Manager in production: key rotation, audit log, IAM permissions all in one.
Pre-commit hook for key detection: detect-secrets or gitleaks auto-scans staged files.
Quota alerts: daily cron checks usage; alert at 30% remaining via email/SMS.
Per-environment key isolation: dev/ci/prod each get their own key; single leak has minimal blast radius.