MiniMax M3.1 Flash 密钥走环境变量、模型参数走配置文件，改一处就能换环境

换环境要改好几处，通常不是配置本身复杂，而是把“不能见光的密钥”“随环境变的地址”“调行为用的超时重试”放在同一份文件或同一段代码里。可行的做法是把参数分三层：密钥只从环境变量读，模型名和接入地址放配置文件并按环境分节，超时、重试、温度这类行为参数放配置文件默认段。加载时按“环境变量 > 环境专属段 > 默认段”合并，缺失密钥在进程启动时直接抛错，再用一次启动自检和一次最小请求确认改动生效。

判断标准：泄露即可被冒用身份的值归为秘密，只走环境变量；同一份代码在不同环境取值不同的归为环境相关，放配置文件按环境分节；不随环境变、只影响调用行为的放默认段。加载顺序建议环境变量覆盖配置文件，配置文件不存密钥也不放占位符。合并结果靠启动自检打印来源路径和指纹来验证，改错时改回 APP_ENV 或回滚配置文件重启即可，不需要回退代码。

先给参数分成秘密、环境相关、行为相关三类

三类的判断标准可以按“会不会被冒用”“会不会随部署位置变”“会不会随业务场景调”来分，分完再决定放哪儿，换环境时的改动面就只剩一处。

秘密：拿到就能以你的身份调用，与具体账号绑定。典型是 MINIMAX_API_KEY，有些接入方式里 group_id、应用 ID 也算半秘密。判断标准是“能不能进代码仓库、镜像层、日志”。放错位置的风险最直接：配置文件一旦提交，密钥会随分支、构建产物、报错堆栈扩散，事后只能轮换，不是改个权限就能收回。
环境相关：同一份代码在测试和正式环境取不同值。典型是 base_url（接入域名）、环境标识、模型名（如果不同环境用不同模型别名）。判断标准是“换一套部署要不要跟着换”。写死在代码里的风险是测试流量打到正式地址，或者调用方以为切了环境、实际还在用旧域名。
行为相关：与部署位置无关，跟调用场景有关。典型是 timeout、retries、temperature、max_tokens、并发上限。判断标准是“换个环境这段值基本不变”。把它们塞进环境变量的风险是每个环境都要复制一份完整变量表，改一个超时要改三处，漏一处就是线上线下行为不一致。

环境变量读取与缺失时的显式报错

目标是缺密钥时进程起不来，而不是跑到第一次请求才在网络层报一个看不懂的错。下面以 Python 为例，其他语言照这个骨架改写即可：读取、去空白、为空就抛自定义异常，并在异常信息里写清变量名和注入方式提示。

import os

class ConfigError(RuntimeError):
    pass

def require_env(name):
    value = os.environ.get(name, "").strip()
    if not value:
        raise ConfigError(
            f"缺少必需的环境变量 {name}；请确认启动命令或部署平台已注入，"
            f"本地可先 export {name}=***"
        )
    return value

API_KEY = require_env("MINIMAX_API_KEY")

启动自检建议只打印能对齐配置、又不暴露原值的行，例如：

[config] env=test model=MiniMax-M3.1-Flash base_url=https://api-test.example.com/v1
[config] api_key_fp=3f9a1c2e len=48
[config] timeout=30 retries=2 temperature=0.3 max_tokens=1024
[config] source=config/minimax.yaml#default <- envs.test + env:APP_ENV

这几行分别回答：当前是哪套环境、用哪个模型和地址、密钥是不是换成了新的（指纹与长度变化即可判断）、行为参数取到什么值、合并来源是哪几层。缺变量时这里根本不会打印，进程会带着 ConfigError 退出，定位成本很低。

MiniMax M3.1 Flash 密钥走环境变量、模型参数走配置文件，改一处就能换环境

配置文件的结构与加载顺序

配置文件只放环境相关和行为相关参数，并按 default 与 envs 分节。不要在配置文件里写 ${MINIMAX_API_KEY} 这类占位符，否则容易让人误以为密钥从这里注入，也让“密钥只走环境变量”这条边界失效。

# config/minimax.yaml
default:
  model: MiniMax-M3.1-Flash
  base_url: https://api.example.com/v1
  timeout: 30
  retries: 2
  temperature: 0.3
  max_tokens: 1024
envs:
  test:
    base_url: https://api-test.example.com/v1
    timeout: 10
  staging:
    base_url: https://api-staging.example.com/v1

合并逻辑的关键是顺序：先深拷贝默认段，用当前环境段覆盖，最后才从环境变量取秘密和允许临时覆盖的少量字段。这样环境变量永远在配置文件之上，配置文件不可能把密钥写回去。

import os, copy, yaml

OVERRIDABLE = {
    "model": "MINIMAX_MODEL",
    "base_url": "MINIMAX_BASE_URL",
}

def load_config(path="config/minimax.yaml"):
    env_name = os.environ.get("APP_ENV", "default").strip() or "default"
    with open(path, encoding="utf-8") as f:
        raw = yaml.safe_load(f) or {}

    cfg = copy.deepcopy(raw.get("default", {}))
    cfg.update(raw.get("envs", {}).get(env_name, {}))
    cfg["env"] = env_name
    cfg["_source"] = f"{path}#default <- envs.{env_name}"

    for key, env_key in OVERRIDABLE.items():
        if os.environ.get(env_key, "").strip():
            cfg[key] = os.environ[env_key].strip()
            cfg["_source"] += f" + env:{env_key}"

    cfg["api_key"] = require_env("MINIMAX_API_KEY")
    return cfg

验证合并结果不必看全部字段，盯三处即可：启动自检里的 base_url 是否换成了目标环境地址、source 是否出现了 envs.test、api_key_fp 是否与上一环境不同。如果只有 base_url 变了但 source 没变，说明是代码里还写死了一处地址，需要回去删掉。

日志里只打参数指纹不打原值

排查时真正需要的不是密钥原文，而是“这次跑的是不是同一把密钥”。用哈希前缀加长度足以区分，也便于在轮换后确认新密钥已经生效。

import hashlib

def fingerprint(secret, n=8):
    if not secret:
        return "MISSING"
    return hashlib.sha256(secret.encode("utf-8")).hexdigest()[:n]

允许打印的字段清单：环境名、模型名、base_url（若域名本身敏感可只打主机名）、timeout、retries、temperature、max_tokens、密钥指纹与长度、配置文件路径、合并来源。不应打印的字段：api_key 原值、完整的 Authorization 请求头、包含密钥的完整请求体、SDK 的调试级请求转储。

如果框架自带的 HTTP 调试日志会打印请求头，建议把该 logger 级别调到 INFO 以上，或在拼装请求头时只保留脱敏副本给日志。改完用命令自查一次：

grep -nE "Bearer |Authorization|MINIMAX_API_KEY=" app.log \
  || echo "no secret pattern found"

python -c "from app.config import load_config, fingerprint; \
  c=load_config(); print(c['env'], c['base_url'], fingerprint(c['api_key']))"

第一条命令确认日志里没有秘密痕迹，第二条在本地或容器里单独跑一次加载逻辑，输出与启动自检对比，能快速判断是配置没读到还是日志没打到。

换环境时怎么验证改对了

把“应该生效了”换成三步可见的确认，按顺序做，任一步不符合预期就停下。

启动自检对齐：切换 APP_ENV 并重启后，确认输出里的 env、base_url、source 三项与目标环境一致，密钥指纹与上一环境不同。三项都对上再继续，不对就先查注入方式和配置文件路径。
发一次最小请求：用一句很短的输入跑通一次调用，观察日志里出现的是目标 base_url、返回状态码正常、返回体中模型标识与配置一致。这一步的目的是验证地址和模型名同时生效，而不是只看日志。
改错后的回滚：如果自检显示 base_url 或指纹不对，先把 APP_ENV 改回原值（或 git checkout -- config/minimax.yaml 回滚配置），重启，再跑一次自检对比 env、base_url、指纹三项是否回到改动前的值。回滚只动配置和环境变量，不需要回退代码，也不要把密钥临时写进配置文件来“先跑通”。

边界需要说清：这套分层解决的是“换环境时改动面和漏改”的问题，不改变调用本身的鉴权方式和限流规则。若接入方对密钥注入有额外要求（例如必须走某个密钥管理服务），环境变量这一层可以替换成读取该服务的封装函数，只要保持“配置文件不承载秘密、缺失即启动报错”这两条不变，其余结构可以继续用。