📑 本页目录(点开跳转)
13 · 配置与密钥
⏱ 46 分钟 | 🔑 摘要服务的启动校验、凭证权限与环境边界
🎯 一句话
同一份服务可以换配置部署。凭证要能独立授权、替换和撤销。
摘要服务已经有了调用层和预算护栏。本章看同一份代码怎样在本地、预发和生产拿到各自的配置,为什么服务要在第一条请求之前查清这些配置。
🧩 一、配置为什么必须离开代码
三个常见现象:换模型要改代码再发版;同事的数据库端口和你不同;一个只该在服务器使用的值被提交到了代码库。它们都暴露了环境信息和共享代码之间缺少边界。
⭐ 分界线:换一台机器、换一个环境会变的是配置,不会变的是代码。 模型名、超时秒数、数据库地址、密钥、调试开关 → 配置;「重试几次、退避公式怎么算」→ 代码。
本章用环境变量作为常见交付方式。它是启动时提供给进程的一组名字和值。部署平台也可以通过受限文件或密钥服务提供凭证。无论从哪里取值,都交给同一个配置入口,明确来源、优先级和失败时的处理。
🔑 二、形状:一个类,启动时就炸
大多数人第一版是散着写 os.getenv("OPENAI_API_KEY")。这版有四个问题,每个都会在半夜咬你一口:
| 问题 | 后果 |
|---|---|
| 拼错的键静默返回 None | 半小时后第一个真实请求才炸 ⚠️ |
| 环境变量永远是字符串 | timeout > 30 直接报错;而 "0" 是 True 💀 |
| 没有一处列全所有配置项 | 新同事只能靠 grep 猜要设哪些变量 |
| 缺配置在运行时才发现 | 服务已经在接流量了 |
加载配置应发生在服务登记就绪之前。缺少值或值不符合规则时立刻报错,叫快速失败(Fail Fast)。因为缺少密钥和连错库都会改变服务的安全边界,所以还要拒绝带着错误配置接流量(Fail Closed),避免悄悄回退到另一套凭证或数据库。
跟一次摘要服务启动,看看哪一步该停
同一份摘要服务,本地练习需要开发库,线上实例需要生产库和自己的模型凭证。假设生产发布漏填了模型凭证。如果进程先收请求,第一位用户才会发现问题。如果启动时先检查,发布系统就能把实例挡在流量入口外。第 14 章会继续讲部署和就绪检查。
把代码保存为 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 那类 | 需要短时动态凭证、租约到期和独立撤销,且现有平台无法满足 |
⭐ 升级信号(出现任意一条就该动):
流程图
先比较现有平台的授权、审计和动态凭证能力。引入新组件也要有人负责维护与故障恢复。生产摘要服务只需要读取自己的凭证并调用获授权的模型。发布或运维身份单独持有创建与撤销权限,开发、预发、生产各用独立身份。记录密钥版本、操作人、操作时间和结果,审计记录中省略密钥值。
💀 四、AI 应用特有的:泄露 = 别人拿你的钱调模型
摘要服务需要在后端持有模型 API 密钥。用户访问的是本应用的接口,由后端验证用户和预算。供应商在自己的接口验证后端凭证。如果凭证泄露,影响取决于它能执行的动作、可访问的资源和失效时间。费用之外,还要核对数据和账户操作的范围。
日志和错误上报也有自己的信任边界。记录字段名、固定错误类别、请求 ID 或允许公开的密钥版本标识。避免采集原始请求头、连接串、局部变量、完整异常和配置对象。验证日志和采集端时用合成值。掩码或正则只能当补充,因为字段格式会变。第 15 章的诊断日志和审计记录也采用明确的字段范围。
什么时候先切换,什么时候先撤销
如果供应商允许新旧短暂并存,就创建同等必要权限的新版本,由一小部分实例先用新版本。验证实际调用成功,再切换其余实例。确认都已迁移后撤销旧版本,并核对供应商已标记失效。
启动事件处置,尽快撤销或限制受影响凭证,并隔离异常调用。必要时先降级摘要服务。再使用受限的新凭证恢复服务,核对使用记录和影响范围。恢复旧应用版本时也要绑定可信的新凭证。
如果新版本只分发了一半,先确认失败的是新凭证权限、配置来源,还是部分实例尚未刷新。计划轮换时可在旧凭证仍可信、有效的前提下暂停切换。泄露处置时不应为了恢复流量重新启用旧凭证。删除仓库中的字符串也无法让已经外泄的凭证失效。处置还包括清理可访问的副本,以及根据策略保留审计证据。OWASP 密钥生命周期。
供应商允许时,再限制项目、模型或用量范围,区分告警和真正阻止消费的硬上限。第 12 章的应用预算控制服务内请求,供应商的凭证权限和配额则限制该凭证能做的事。
🌍 五、多环境:dev / staging / prod
优先用同一个经过验证的构建产物逐级发布。让每个环境分别配置数据库、模型凭证、额度和日志权限。
这样可以把构建差异与运行配置差异分开排查。下一章介绍怎样打包并发布同一份镜像。
典型故障是开发实例意外拿到生产库配置。启动校验、网络和账号权限可以分别在不同层拦住它。
三道环境检查
- 启动时对照独立的部署身份与预期数据库目标,只输出允许公开的状态。
- 开发和预发网络及应用身份不具备生产数据库权限。
- 生产日常排查使用单独的受限只读角色,写权限按任务授权。
便宜模型适合本地试流程。需要验证生产模型的输出合同、上下文上限或延迟时,预发使用生产将部署的模型版本,并通过独立配额限制样本量。预发的样本和流量结构仍会影响外推范围。
⭐ 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 · 隐私脱敏与留存 | 本章脱敏只针对密钥;用户数据的脱敏和留存期是另一套要求,别混着做 |
✅ 检查点
- 同一份摘要镜像在 dev 和 prod 运行,哪些配置可以变化?哪些凭证需要分开?
- 本地文件写了 90 秒,进程注入 45 秒。结果是多少?如果注入值是空字符串呢?
- 生产实例的
APP_ENV填成了dev,本地文件能救回来吗? - 为什么要校验数值范围,即使
float()已经解析成功? repr=False有什么作用?启动日志和错误上报该记录哪些字段?- 谁应拥有读凭证权限?谁需要创建或撤销权限?
- 切了一半实例后发现旧凭证可能已泄露。计划轮换的重叠期还能继续用吗?
- 什么检查能发现开发服务误连生产库?哪层能直接阻止连接?
- 预发该在什么时候使用生产将部署的模型版本?如何限制试验费用?
👀 答案
- 模型、超时、数据库、额度和日志设置可以分别提供。各环境使用自己的受限凭证。
- 用 45 秒。注入空字符串也会覆盖本地值,随后因无法解析为有效秒数而拒绝启动。
- 不会。部署入口预期是 prod,声明为 dev 会失败。生产实例也不加载本地文件。
nan可以解析成浮点数,但不满足大于 0 且小于等于 120 秒的范围。- 它只隐藏默认对象表示里的字段。日志选择公开状态、字段名、固定失败类别、请求 ID 或允许公开的版本标识。
- 应用身份读取本服务的凭证。创建和撤销交给独立的发布或运维身份,并记录审计事件。
- 尽快撤销或限制旧凭证,隔离受影响调用。必要时降级,再使用可信新凭证恢复。
- 启动时用独立部署身份核对数据库目标。网络和数据库权限能阻止开发实例连接生产库。
- 验证与模型版本有关的输出合同、上下文限制或延迟时使用计划部署的版本,再通过独立配额限制样本量。
本节回顾
⚡ 走神救援
先由可信部署入口确定环境,再选配置来源、合并、校验和决定是否接流量。
缺值、错类型和错环境都要在启动时发现。错误只报字段和原因,诊断日志只选必要字段。
应用只读自己需要的凭证。计划轮换可短时并存;疑似泄露时优先阻断并换用可信凭证。
下一节 👉 14-容器化与部署.md