🏠 总目录📚 本教程 13 · 配置与密钥 ← →

AI全栈 / 13

配置能读到,是否就足够安全可靠?

把配置移出代码只是开始;启动校验、密钥分级和环境隔离仍需逐项落实。

能在请求进入前发现缺失配置,并区分普通配置与秘密。

检查环境边界

📑 本页目录(点开跳转)

13 · 配置与密钥

⏱ 46 分钟 | 🔑 摘要服务的启动校验、凭证权限与环境边界


🎯 一句话

同一份服务可以换配置部署。凭证要能独立授权、替换和撤销。

摘要服务已经有了调用层和预算护栏。本章看同一份代码怎样在本地、预发和生产拿到各自的配置,为什么服务要在第一条请求之前查清这些配置。


🧩 一、配置为什么必须离开代码

三个常见现象:换模型要改代码再发版;同事的数据库端口和你不同;一个只该在服务器使用的值被提交到了代码库。它们都暴露了环境信息和共享代码之间缺少边界。

⭐ 分界线:换一台机器、换一个环境会变的是配置,不会变的是代码。 模型名、超时秒数、数据库地址、密钥、调试开关 → 配置;「重试几次、退避公式怎么算」→ 代码。

本章用环境变量作为常见交付方式。它是启动时提供给进程的一组名字和值。部署平台也可以通过受限文件或密钥服务提供凭证。无论从哪里取值,都交给同一个配置入口,明确来源、优先级和失败时的处理。


🔑 二、形状:一个类,启动时就炸

大多数人第一版是散着写 os.getenv("OPENAI_API_KEY")。这版有四个问题,每个都会在半夜咬你一口:

问题 后果
拼错的键静默返回 None 半小时后第一个真实请求才炸 ⚠️
环境变量永远是字符串 timeout > 30 直接报错;而 "0" 是 True 💀
没有一处列全所有配置项 新同事只能靠 grep 猜要设哪些变量
缺配置在运行时才发现 服务已经在接流量了

加载配置应发生在服务登记就绪之前。缺少值或值不符合规则时立刻报错,叫快速失败(Fail Fast)。因为缺少密钥和连错库都会改变服务的安全边界,所以还要拒绝带着错误配置接流量(Fail Closed),避免悄悄回退到另一套凭证或数据库。

跟一次摘要服务启动,看看哪一步该停

同一份摘要服务,本地练习需要开发库,线上实例需要生产库和自己的模型凭证。假设生产发布漏填了模型凭证。如果进程先收请求,第一位用户才会发现问题。如果启动时先检查,发布系统就能把实例挡在流量入口外。第 14 章会继续讲部署和就绪检查。

① 选来源从可信部署入口确定环境。只有 dev 可加载本地 .env。
② 合并配置同名字段使用优先级更高的值。显式空值也要交给校验。
③ 校验检查必填项、数值范围,以及声明环境和数据库目标。
④ 决定是否就绪通过后再初始化依赖。失败只报字段名和原因,拒绝接流量。

把代码保存为 config_demo.py,运行 python config_demo.py。expected_env 模拟由部署入口独立确认的环境。local 是已经读出的本地文件数据,injected 是已经注入的字符串。全部值都是合成夹具,示例不读取环境变量或文件,也不连接数据库和供应商。

from dataclasses import dataclass, field
from urllib.parse import urlsplit


DATABASE_HOST = {
    "dev": "dev-db.example.invalid",
    "staging": "staging-db.example.invalid",
    "prod": "prod-db.example.invalid",
}
TIMEOUT_ERROR = "LLM_TIMEOUT_S 必须是 0 到 120 之间的正数(秒)"
DATABASE_ERROR = "DATABASE_URL 不在当前环境的允许范围"


class ConfigError(Exception):
    pass


@dataclass(frozen=True)
class Settings:
    env: str
    timeout_s: float
    api_key: str = field(repr=False)
    database_url: str = field(repr=False)


def load_settings(expected_env, injected, local=None):
    if expected_env not in DATABASE_HOST:
        raise ConfigError("部署环境未获认可")
    if local is not None and expected_env != "dev":
        raise ConfigError("只有 dev 允许加载本地 .env")

    values = {"LLM_TIMEOUT_S": "60", **(local or {}), **injected}
    if values.get("APP_ENV") != expected_env:
        raise ConfigError("APP_ENV 与部署环境不符")
    key = values.get("LLM_API_KEY", "")
    if not key.strip():
        raise ConfigError("LLM_API_KEY 缺失或为空")

    try:
        timeout = float(values["LLM_TIMEOUT_S"])
    except ValueError:
        raise ConfigError(TIMEOUT_ERROR) from None
    if not 0 < timeout <= 120:
        raise ConfigError(TIMEOUT_ERROR)

    database_url = values.get("DATABASE_URL", "")
    try:
        target = urlsplit(database_url)
        allowed = (
            target.scheme == "postgresql"
            and target.hostname == DATABASE_HOST[expected_env]
            and target.port in (None, 5432)
            and target.path == "/summary"
            and not target.query
            and not target.fragment
        )
    except ValueError:
        raise ConfigError(DATABASE_ERROR) from None
    if not allowed:
        raise ConfigError(DATABASE_ERROR)
    return Settings(expected_env, timeout, key, database_url)


def startup(expected_env, injected, local=None):
    try:
        settings = load_settings(expected_env, injected, local)
    except ConfigError as error:
        # ConfigError 只携带本章写好的短句,不拼接输入值。
        return False, f"拒绝启动 {error}"
    return True, (
        f"启动通过 APP_ENV={settings.env} "
        f"LLM_TIMEOUT_S={settings.timeout_s:g}"
    )


if __name__ == "__main__":
    # 合成夹具,模拟已经读出的字符串,不读取 os.environ 或 .env。
    dev_url = "postgresql://demo:fake-password@dev-db.example.invalid/summary"
    prod_url = "postgresql://demo:fake-password@prod-db.example.invalid/summary"
    dev = {"APP_ENV": "dev", "DATABASE_URL": dev_url,
           "LLM_API_KEY": "SYNTHETIC_ONLY_DEV", "LLM_TIMEOUT_S": "90"}
    prod = {"APP_ENV": "prod", "DATABASE_URL": prod_url,
            "LLM_API_KEY": "SYNTHETIC_ONLY_PROD", "LLM_TIMEOUT_S": "30"}
    cases = [
        ("本地覆盖", "dev", {"LLM_TIMEOUT_S": "45"}, dev, True),
        ("生产配置", "prod", prod, None, True),
        ("缺少密钥", "prod", {**prod, "LLM_API_KEY": ""}, None, False),
        ("错误格式", "prod", {**prod, "LLM_TIMEOUT_S": "SYNTHETIC_ONLY"}, None, False),
        ("非有限数字", "prod", {**prod, "LLM_TIMEOUT_S": "nan"}, None, False),
        ("生产读本地配置", "prod", prod, dev, False),
        ("开发连接生产库", "dev", {"DATABASE_URL": prod_url}, dev, False),
        ("声明环境不符", "prod", {**prod, "APP_ENV": "dev"}, None, False),
    ]
    for label, expected_env, injected, local, should_start in cases:
        ready, summary = startup(expected_env, injected, local)
        assert ready == should_start, label
        assert "SYNTHETIC_ONLY" not in summary
        assert "fake-password" not in summary
        assert "example.invalid" not in summary
        print(f"{label} | {summary}")

本地文件给了 90 秒,注入值 45 秒覆盖它,所以第一行显示 APP_ENV=dev LLM_TIMEOUT_S=45。生产配置只有注入值,显示 APP_ENV=prod LLM_TIMEOUT_S=30。接下来六种失败都停在就绪之前,终端只显示字段名和固定原因。float("nan") 可以解析,仍然不满足 0 < timeout <= 120。

repr=False 只保护这个对象默认的文本表示。完整序列化、调试器或错误采集仍可能读到字段。启动日志在 startup() 里明确选择环境和超时两项,数据库连接串即使只是地址,也按可能含凭证的数据处理。Python 字段文档说明了 repr 的作用范围。

这套示例把可连接的 PostgreSQL 主机、端口和库名限制在预先定义的集合内,演示怎样发现误连。urlsplit() 只做拆分。生产仍要由数据库身份、网络和连接驱动落实隔离,并独立确认依赖可用。真实进程遇到失败应以非零状态退出或保持未就绪。这里返回布尔值,便于同一轮离线运行核对所有分支。

.env 只给本地用

.env 是本地配置文件。用 .gitignore 防止新文件被误加入版本库,并在构建时排除它。仓库里的 .env.example 可以列出变量名和安全示例值,密钥留空。已跟踪的文件和历史记录需要单独处理。

在本章的约定里,优先级由低到高是「普通代码默认值 → dev 本地文件 → 运行环境注入」。如果注入端显式给了空值,就让必填校验拒绝启动,不悄悄回退。测试把输入直接交给配置入口,避免依赖测试机器上的值。预发和生产只走部署平台提供的来源。


🔐 三、密钥管理三档,和升级信号

上一节解决了应用怎样读取值。接下来考虑谁能提供凭证、谁可以替换,以及应用怎样取得最小必要权限。环境变量是交付渠道,密钥服务负责访问授权、审计和生命周期,两者可以配合。

档 长什么样 够用到什么时候
① 环境变量 PaaS 面板 / 服务器上直接填 调用身份和权限简单,部署端已有独立访问控制与可执行的撤销流程
② 平台密钥管理 云厂商 Secrets Manager、K8s Secret、CI Secrets 多环境多服务,需要分别授权并追踪访问。具体审计能力以平台配置为准
③ 专用密钥服务 Vault 那类 需要短时动态凭证、租约到期和独立撤销,且现有平台无法满足

⭐ 升级信号(出现任意一条就该动):

流程图

① 给新同事发密钥,你是【复制粘贴到聊天窗口】的→升到 ②
② 轮换一次要改 6 个地方,而且你记不全是哪 6 个→升到 ②
③ 有人问「这个 key 现在有谁能看到」,你答不上来→升到 ②
④ 需要「这把凭证 1 小时后自动失效」→升到 ③
⑤ 每个租户一套凭证,且要能单独吊销→升到 ③

先比较现有平台的授权、审计和动态凭证能力。引入新组件也要有人负责维护与故障恢复。生产摘要服务只需要读取自己的凭证并调用获授权的模型。发布或运维身份单独持有创建与撤销权限,开发、预发、生产各用独立身份。记录密钥版本、操作人、操作时间和结果,审计记录中省略密钥值。


💀 四、AI 应用特有的:泄露 = 别人拿你的钱调模型

摘要服务需要在后端持有模型 API 密钥。用户访问的是本应用的接口,由后端验证用户和预算。供应商在自己的接口验证后端凭证。如果凭证泄露,影响取决于它能执行的动作、可访问的资源和失效时间。费用之外,还要核对数据和账户操作的范围。

浏览器只提交业务请求,凭证留在后端。
应用后端检查本应用授权与预算,再使用本服务的受限凭证。
模型供应商只接收业务调用所需的内容,并按凭证权限处理请求。

日志和错误上报也有自己的信任边界。记录字段名、固定错误类别、请求 ID 或允许公开的密钥版本标识。避免采集原始请求头、连接串、局部变量、完整异常和配置对象。验证日志和采集端时用合成值。掩码或正则只能当补充,因为字段格式会变。第 15 章的诊断日志和审计记录也采用明确的字段范围。

什么时候先切换,什么时候先撤销

计划轮换 · 旧凭证仍可信

如果供应商允许新旧短暂并存,就创建同等必要权限的新版本,由一小部分实例先用新版本。验证实际调用成功,再切换其余实例。确认都已迁移后撤销旧版本,并核对供应商已标记失效。

疑似泄露 · 先阻断

启动事件处置,尽快撤销或限制受影响凭证,并隔离异常调用。必要时先降级摘要服务。再使用受限的新凭证恢复服务,核对使用记录和影响范围。恢复旧应用版本时也要绑定可信的新凭证。

如果新版本只分发了一半,先确认失败的是新凭证权限、配置来源,还是部分实例尚未刷新。计划轮换时可在旧凭证仍可信、有效的前提下暂停切换。泄露处置时不应为了恢复流量重新启用旧凭证。删除仓库中的字符串也无法让已经外泄的凭证失效。处置还包括清理可访问的副本,以及根据策略保留审计证据。OWASP 密钥生命周期。

供应商允许时,再限制项目、模型或用量范围,区分告警和真正阻止消费的硬上限。第 12 章的应用预算控制服务内请求,供应商的凭证权限和配额则限制该凭证能做的事。


🌍 五、多环境:dev / staging / prod

优先用同一个经过验证的构建产物逐级发布。让每个环境分别配置数据库、模型凭证、额度和日志权限。

这样可以把构建差异与运行配置差异分开排查。下一章介绍怎样打包并发布同一份镜像。

典型故障是开发实例意外拿到生产库配置。启动校验、网络和账号权限可以分别在不同层拦住它。

三道环境检查

  1. 启动时对照独立的部署身份与预期数据库目标,只输出允许公开的状态。
  2. 开发和预发网络及应用身份不具备生产数据库权限。
  3. 生产日常排查使用单独的受限只读角色,写权限按任务授权。

便宜模型适合本地试流程。需要验证生产模型的输出合同、上下文上限或延迟时,预发使用生产将部署的模型版本,并通过独立配额限制样本量。预发的样本和流量结构仍会影响外推范围。

⭐ prompt 模板算配置还是代码? 建议当代码:跟版本库走、进 code review、能和某次发版对上 —— 改一句 prompt 就可能改变全部输出,这是发版级变更,不该在面板上被人随手改掉。 确实要不发版就改,就把它当带版本号的数据(日志里记录用的是哪个版本), 🔗 理由见模型上线之后 17:改不了的东西才可复现。


🔄 六、换个栈怎么对应

概念 Python(本板块) Node(Express/Hono) Go
读环境变量 os.environ process.env os.Getenv
加载 .env python-dotenv dotenv / 🗓️ 新版 Node 自带 --env-file godotenv
配置对象 + 校验 pydantic-settings zod / envalid envconfig / viper
缺配置时 抛异常,进程退出 throw → process.exit(1) log.Fatal
安全诊断日志 显式构造允许记录的字段 pino 的 redact 选项 slog 的 ReplaceAttr

⭐ 三个栈形状完全一样:一处声明全部配置 → 启动时校验 → 校验不过就别启动 → 打印时永远不吐密钥。会过期的是包名,不会过期的是这四步。


🔗 这一章连到哪里

去哪 为什么
密码学与信息安全 19 · 密钥管理 这一章讲密钥放在哪;密钥本身该怎么生成、派生、销毁,为什么不能随手 random() 一个,在那边
模型上线之后 17 · 版本回溯与可复现 当你想让 prompt「不发版就能改」时,先去看那边为什么改不了的东西才可复现
模型上线之后 18 · 成本与容量 供应商侧的消费上限只是最外层,容量规划和成本怎么摊回业务在那边
数据这一关 19 · 隐私脱敏与留存 本章脱敏只针对密钥;用户数据的脱敏和留存期是另一套要求,别混着做

✅ 检查点

  1. 同一份摘要镜像在 dev 和 prod 运行,哪些配置可以变化?哪些凭证需要分开?
  2. 本地文件写了 90 秒,进程注入 45 秒。结果是多少?如果注入值是空字符串呢?
  3. 生产实例的 APP_ENV 填成了 dev,本地文件能救回来吗?
  4. 为什么要校验数值范围,即使 float() 已经解析成功?
  5. repr=False 有什么作用?启动日志和错误上报该记录哪些字段?
  6. 谁应拥有读凭证权限?谁需要创建或撤销权限?
  7. 切了一半实例后发现旧凭证可能已泄露。计划轮换的重叠期还能继续用吗?
  8. 什么检查能发现开发服务误连生产库?哪层能直接阻止连接?
  9. 预发该在什么时候使用生产将部署的模型版本?如何限制试验费用?
👀 答案
  1. 模型、超时、数据库、额度和日志设置可以分别提供。各环境使用自己的受限凭证。
  2. 用 45 秒。注入空字符串也会覆盖本地值,随后因无法解析为有效秒数而拒绝启动。
  3. 不会。部署入口预期是 prod,声明为 dev 会失败。生产实例也不加载本地文件。
  4. nan 可以解析成浮点数,但不满足大于 0 且小于等于 120 秒的范围。
  5. 它只隐藏默认对象表示里的字段。日志选择公开状态、字段名、固定失败类别、请求 ID 或允许公开的版本标识。
  6. 应用身份读取本服务的凭证。创建和撤销交给独立的发布或运维身份,并记录审计事件。
  7. 尽快撤销或限制旧凭证,隔离受影响调用。必要时降级,再使用可信新凭证恢复。
  8. 启动时用独立部署身份核对数据库目标。网络和数据库权限能阻止开发实例连接生产库。
  9. 验证与模型版本有关的输出合同、上下文限制或延迟时使用计划部署的版本,再通过独立配额限制样本量。

本节回顾

⚡ 走神救援

先由可信部署入口确定环境,再选配置来源、合并、校验和决定是否接流量。

缺值、错类型和错环境都要在启动时发现。错误只报字段和原因,诊断日志只选必要字段。

应用只读自己需要的凭证。计划轮换可短时并存;疑似泄露时优先阻断并换用可信凭证。

下一节 👉 14-容器化与部署.md

打卡记录保存在你的浏览器里,首页能看到总进度