为什么模型 API Key 不能放在前端

为了快速做出模型调用演示，有人会把 API Key 写进网页脚本、移动端配置或客户端环境变量。请求虽然可以成功，但凭据会随代码、网络请求或安装包交给用户，任何人都可能提取并在应用之外调用。限制来源 Header 或把字符串混淆，不能把公开客户端变成可信环境。正确架构是让前端只携带自身业务身份访问后端，由后端保存模型凭据、判断用户权限、控制输入和验证输出。本文说明后端代理需要承担的最小职责及上线检查。

公开客户端无法保存秘密

浏览器 JavaScript、静态资源、Source Map、移动安装包和桌面客户端都在用户控制的设备上运行。只要客户端能够读取密钥并发送请求，用户也能通过调试工具、反编译或网络观察获得它。

以下做法不能建立真正保密：

• 把 Key 拆成多个字符串再拼接；
• 使用前端构建变量隐藏；
• 仅删除 Source Map；
• 将 Key Base64 编码；
• 依靠请求来源 Header；
• 在移动端写入资源或配置文件。

这些措施最多增加提取步骤，无法阻止凭据被复制到应用之外。

后端代理的基本请求链

前端业务身份
  → 后端认证与授权
  → 输入结构和大小校验
  → 数据分类与字段过滤
  → 使用服务端凭据调用模型
  → 响应结构与内容校验
  → 返回业务需要的最小结果

模型 Key 只存在于服务端密钥管理或运行时注入环境。前端拿到的是业务会话或短期访问令牌，它只允许调用本应用定义的功能，不允许直接调用任意模型接口。

第一项职责：认证用户并授权功能

认证回答“是谁”，授权回答“这个身份能做什么”。后端不能只验证用户已经登录，还要检查其是否有权访问当前知识库、上传文件或使用某个高风险工具。

模型名称、系统提示和工具列表不应完全由前端透传。由后端按业务功能选择允许值，避免调用者绕过产品边界构造任意请求。

第二项职责：校验请求结构和资源预算

使用明确 Schema 验证字段、类型、长度和枚举值。限制单次文本、文件数量、输出上限和并发，拒绝未知字段。限制值应来自业务容量测试和风险评估，而不是通用文章中的固定数字。

当请求超出限制时返回稳定错误类别，客户端可以提示用户收窄输入；不能静默截断关键材料后继续生成确定答案。

第三项职责：过滤不应发送的数据

后端只组装任务必需字段，并在调用前应用数据分类和权限过滤。客户信息、内部文档、凭据和日志片段是否允许进入模型，需要按功能与处理者单独判断。

脱敏不是简单替换几个数字格式。自由文本中的身份、合同内容和商业机密需要业务语义评估。无法确认处理边界时，使用合成或脱敏测试数据，不直接开放生产资料。

第四项职责：安全使用服务端凭据

每个服务和环境使用可单独撤销的凭据。凭据不写入代码、镜像、日志、错误响应或工单截图。部署系统从受控秘密存储注入，应用只读取固定配置名。

后端日志使用非敏感 credential_id 关联调用，不输出真实 Key。轮换时允许新旧凭据短暂并存，验证新凭据后撤销旧值，并主动确认旧值已经失败。

第五项职责：处理超时、重试和取消

调用设置端到端超时与取消传播。客户端中止请求后，后端应停止不再需要的工作，避免后台继续消耗资源。

认证、权限和输入错误不应自动重试。临时服务错误可以有限重试，但每次记录 request_id 与错误类别。若模型请求会触发外部写入，重试前必须先确认写入状态并使用幂等标识。

第六项职责：验证模型输出

模型响应是不可信输入。后端需要：

• 对 JSON 或工具参数执行 Schema 校验；
• 检查引用标识是否来自允许资料；
• 拒绝未授权工具和参数；
• 对 HTML、Markdown 或代码输出按目标渲染环境安全处理；
• 高风险结论进入人工复核，不直接触发业务动作。

“模型通常遵守格式”不能替代解析失败分支。

返回最小业务结果

不要把上游完整响应、内部系统提示、路由信息或调试字段全部发回前端。定义稳定的业务响应，例如：

{
  "request_id": "req_test_001",
  "status": "completed",
  "answer": "...",
  "citations": []
}

示例只表达结构。错误响应返回安全类别和关联标识，不泄露上游凭据、内部地址或堆栈。

日志关联但不复制正文

后端可记录用户或服务标识、项目、请求标识、功能类型、实际模型标识、状态、耗时和接口用量。默认不记录完整输入、检索片段、输出或密钥。

需要调试正文时使用受控采样、脱敏、访问限制和明确删除期限。业务日志和上游调用日志通过 request_id 关联，不必在多套系统复制同一敏感内容。

最小上线检查

[ ] 前端资源、安装包和网络响应中没有模型凭据
[ ] 后端按业务身份授权模型功能和数据范围
[ ] 模型、工具与输出参数使用白名单
[ ] 请求有 Schema、大小、超时和并发限制
[ ] 输入在发送前完成权限和数据过滤
[ ] 服务端凭据可按环境和服务独立撤销
[ ] 输出和工具参数在后端重新校验
[ ] 重试不会重复外部副作用
[ ] 日志没有凭据和默认正文
[ ] 已演练凭据泄露后的撤销与恢复

结论与限制

模型 API Key 不能放在前端，因为运行在用户设备上的代码无法保守共享秘密。后端代理的价值不只是隐藏 Key，而是把业务认证、数据边界、资源限制、重试和输出校验放在可信控制点。

本文提供通用接入职责，不包含特定供应商 SDK、模型配置或价格。服务端仍需依据所用接口的当前文档实现认证和错误处理，并结合组织的数据政策、安全评审与容量测试确定具体限制。