事件概述 在 2025 年 10 月 1 日,我们的应用中一个用于生成提示文本的功能突然报错并返回 401 Unauthorized。令人困惑的是,应用的其它调用相同 LLM(Google Gemini)的功能并未受影响,且我们并未对代码或配置做任何新部署。经过 12 小时的逐步排查,一位团队成员发现当日 Netlify 推出了一个名为 AI Gateway 的新功能,并且默认对所有用户生效。进一步调查显示,Netlify 在构建或运行时为某些 LLM 提供商注入了 API key,并将流量路由到他们自己的网关,进而导致我们的请求因认证失败而被拒绝。 问题根源与表现 Netlify 官方说明不"覆盖已存在的环境变量",但并未完全考虑到环境变量在构建时与运行时的差异。我们的项目在构建过程中使用了由 CI 注入的 GEMINI_API_KEY。
如果变量仅在构建时存在,而在运行时不存在,Netlify 的 AI Gateway 会在运行时插入他们自己的 GEMINI_API_KEY,这就改变了运行环境下的凭证,从而导致部分 SDK 或集成在运行时读取到不同的值并发生认证失败。我们尝试在管理控制台关闭 AI Gateway 功能,但在我们的实例中该配置并未立即生效。最终的解决办法是在 Netlify 的环境变量配置中明确添加我们自己的 GEMINI_API_KEY,使 Netlify 认为变量"已存在",从而不再注入他们的默认值。 为何只有部分功能出错 并非所有依赖 Gemini 的功能都同时报错,这让排查更加棘手。出现差异的主要原因在于不同 SDK 与集成方式对环境变量的读取时机和策略不同。比如我们发现出问题的功能使用了 Google 的 genai SDK,该 SDK 在某些运行路径下会在运行时读取环境变量或以某种方式与运行时环境交互,而其它功能可能在构建时已将凭证固化或通过服务器端代理进行调用,因此没有暴露在运行时环境中。
换言之,环境变量在哪个阶段被读取以及 SDK 如何实现认证,会直接影响是否受到 Netlify 注入策略的影响。 如何排查类似问题 首先查看构建与运行日志。Netlify 的构建日志与函数调用日志通常会指示请求失败的时间点与错误码。401 错误提示通常意味着凭证不对或凭证被替换。其次,在受控的非生产环境中复现问题。可以在本地或一个干净的部署环境中先不设置任何 GEMINI_API_KEY,观察 Netlify 是否注入并返回何种值。
若要检查环境变量值,不要直接在日志中打印秘密凭证,而可以打印凭证的哈希或长度来对比是否一致。还可以通过 Netlify 控制台的"Site settings -> Build & deploy -> Environment"查看当前设置的环境变量,或使用 Netlify CLI 列出环境变量并确认其来源。 修复与缓解措施 第一步是确保在 Netlify 控制台或 netlify.toml 中明确设置所需的 GEMINI_API_KEY,这通常会阻止 Netlify 注入他们的默认密钥。对于必须在构建时使用的密钥,应当在构建环境(build.environment)中声明,而不是依赖外部在运行时填充的变量。第二步是尽快旋转受影响的 API key。既然存在第三方网关介入或注入的可能性,最好把原有密钥废弃并生成新的短生命周期或权限受限的密钥。
第三步是在系统架构层减少对客户端环境变量的依赖。把对 LLM 的调用放到后端或服务器端函数中,并由后端安全地管理密钥。使用 Netlify Functions、独立后端或代理服务来隔离凭证,避免将密钥暴露给浏览器或构建后公开的产物。第四步是将敏感操作与凭证访问做更严格的审计。记录谁何时变更了环境变量,并对控制台权限进行限制。 对开发者的长期建议 尽量避免在构建时将敏感凭证写入产物或代码库。
使用运行时凭证管理或秘密管理服务来发放临时凭证或按需签发。把对外部 LLM 服务的调用集中在受控的服务器侧,这样不仅能保护密钥,还能统一进行速率限制、缓存与成本控制。采取最小权限原则,为每个服务生成粒度更细的 API key,必要时使用只读或受限范围的凭证。为 CI/CD 配置加密的环境变量,并且限制显示这些变量的人员范围。定期轮换密钥并启用使用告警,当异常流量或认证失败激增时立即通知运维。 监测与检测策略 增加对 401/403 错误的监控阈值,并在短时间内出现突增时触发报警。
为不同调用路径(客户端直连、后端代理、定时任务)设置独立的指标与告警,这样可以更快定位是哪个路径受影响。在安全允许的前提下,对外包网关/中间件的使用情况做白名单审计,确保任何第三方注入或代理流量都会被记录与批准。建立变更记录,任何默认开放或启用平台新功能的行为都应进入变更审查流程。 关于平台默认行为与沟通 平台在默认开启新功能时应当更谨慎,尤其当该功能可能改变环境变量或数据流向时。作为用户,及时关注托管平台的发布说明、变更日志与邮件通知非常重要。若发现平台提供的"禁用"选项在实际环境中不起作用,应当立即向平台提交支持工单并提供可重现步骤。
同时将该问题在社区或开发者论坛中公示可以促使更多受影响的团队快速发现并采取防护措施。 对于 Netlify 用户的具体操作建议 在 Netlify 控制台为站点显式配置所需的所有 LLM API key,确保在"Build & deploy"下的环境变量里能看到键名与来源。若使用 netlify.toml 来管理构建配置,可以在 [build.environment] 段落中声明构建时所需的变量。对于函数(Netlify Functions)调用,建议在函数执行环境中注入密钥而非直接在前端暴露。若发现关闭 AI Gateway 无效,记录操作时间并与 Netlify 支持同步,要求他们说明变更是否已经完全部署以及是否存在已知的覆盖逻辑。 兼顾隐私、成本与合规 将所有 LLM 请求通过第三方网关可能带来隐私与合规风险。
平台为用户扣费或用自有信用点系统结算时,必须清晰告知用户计费模型與数据使用条款。开发团队应当审视是否允许平台在未经明确授权的情况下代理或重路由 AI 请求,尤其当请求中包含用户隐私或受限数据时。对接合规团队或法律顾问,评估第三方网关是否满足你的行业要求,特别是在金融、医疗或受监管领域。 技术深究:环境变量的读取时机 许多问题源自环境变量的读取时机与生命周期。构建时读取意味着凭证被写入产物或被 SDK 在编译/打包时固化;运行时读取意味着在服务启动或函数执行时从环境中读取。Netlify 的 AI Gateway 注入行为主要影响运行时环境,因此对运行时读取的 SDK 和逻辑影响最大。
理解你所使用库在何时读取凭证至关重要。若无法确定,检查库文档或源码,或在安全环境下打印其对凭证的读取行为(采用不可逆哈希来避免泄露明文)。 应对未来风险的组织层面策略 把对第三方平台变更的监控纳入运维流程。建立一套平台变更评估清单,每次托管平台或基础设施提供商发布新功能或默认行为调整时先在预生产环境进行验证。将关键凭证的存在性与正确性作为 CI 验证流程的一部分,构建前后对比关键环境变量的哈希值从而检测潜在被注入或替换的情况。培训开发人员识别 SDK 与平台在凭证管理上的陷阱,鼓励通过代码审查与安全评估来发现隐藏风险。
结语与行动项 这起事件提醒我们,托管平台的默认行为可能会在不通知或不充分通知的前提下影响到生产系统。遇到类似 401 Unauthorized 的突发问题时,除了检查业务代码与第三方服务本身,还应把视角扩展到托管平台与构建/运行时环境的变化。立即的修复方向是显式设置所需环境变量并旋转受影响密钥,长期应对则在于把敏感调用迁移到受控后端、加强监控告警、采用秘密管理服务以及把平台变更纳入例行评估流程。如果你使用 Netlify 或类似托管平台,尽快在控制台核对所有 LLM 与第三方 API 的环境变量,确认没有被平台默认注入的凭证替换,并将此事作为团队的安全与运维学习点进行记录与分享。 。
