概述

多环境配置的目标是避免把测试流量打到生产项目，也避免把生产 key 放进本地设备。

推荐把 base URL、API key、默认模型和项目预算按环境拆开。

本文适合本地开发、CI、staging 和 prod 同时存在的团队。

环境变量命名

推荐使用统一前缀：

UOUODUO_BASE_URL=https://api.example.com/v1
UOUODUO_API_KEY=sk-xxx...
UOUODUO_MODEL=gpt-4o-mini
UOUODUO_ENV=dev

不要混用多个 provider 的变量名。

如果第三方 SDK 只识别 `OPENAI_API_KEY`，可以在启动脚本里映射。

dev 环境

dev 环境用于本地测试。

建议：

• 使用个人或项目 dev key
• 设置较低预算
• 默认模型使用便宜模型
• 允许较详细日志
• 不处理真实用户数据

`.env.local` 示例：

UOUODUO_ENV=dev
UOUODUO_BASE_URL=https://api.example.com/v1
UOUODUO_API_KEY=sk-xxx...
UOUODUO_MODEL=gpt-4o-mini

staging 环境

staging 用于上线前验证。

建议：

• 使用团队 staging 项目
• 模型尽量接近生产
• 预算低于生产但高于 dev
• 开启和生产一致的日志字段
• 使用脱敏数据

staging 的主要目标是发现配置和路由问题，而不是压测全部容量。

prod 环境

prod 环境只使用生产 key。

建议：

• 密钥只存放在部署平台 secret 中
• 不允许开发机直接读取
• 每个服务单独 key
• 每个项目配置预算
• 定期轮换密钥

生产配置变更应走审查流程。

一键切换脚本

可以写一个本地脚本：

#!/usr/bin/env bash
set -euo pipefail

case "${1:-dev}" in
  dev)
    export UOUODUO_API_KEY="$UOUODUO_DEV_KEY"
    export UOUODUO_MODEL="gpt-4o-mini"
    ;;
  staging)
    export UOUODUO_API_KEY="$UOUODUO_STAGING_KEY"
    export UOUODUO_MODEL="claude-3-5-haiku"
    ;;
  prod)
    echo "prod key must be loaded by deployment secrets"
    exit 1
    ;;
esac

export UOUODUO_BASE_URL="https://api.example.com/v1"

本地脚本不要自动加载生产 key。

CI 配置

CI 建议使用 staging key。

只跑轻量 smoke：

• `/v1/models`
• 一次短 chat completions
• 一次 embeddings

不要在每次 PR 上跑长文本生成。

模型切换

把模型 ID 放进环境变量：

UOUODUO_MODEL=gpt-4o-mini

应用里读取：

const model = process.env.UOUODUO_MODEL ?? 'gpt-4o-mini';

这样切换模型不需要改代码。

日志标记

建议在请求 metadata 或业务日志里记录环境：

{
  "environment": "staging",
  "service": "worker",
  "feature": "summary"
}

不要把用户敏感信息放进 metadata。

成本隔离

按环境创建独立项目：

• `dev`
• `staging`
• `prod-web`
• `prod-worker`

每个项目绑定独立 API key 和预算。

这样可以快速定位是哪一类流量造成费用变化。

轮换策略

密钥轮换建议：

1. 创建新 key。
2. 部署新 key。
3. 确认 Logs 中新 key 有流量。
4. 等待旧请求自然结束。
5. 撤销旧 key。

不要先撤销旧 key 再部署新 key。

常见错误

• 本地 `.env` 被提交到 Git。
• staging 使用了生产 key。
• SDK 读取了 `OPENAI_API_KEY`，但没有映射到 UOUODUO key。
• base URL 缺少 `/v1`。
• CI 并发过高导致 429。

这些问题都可以通过独立项目、低预算和启动前自检降低风险。