OpenAI
用于代理安全与请求流程验证的原始 API 契约。
安全代理架构指南
OpenAI API 代理
安全架构与部署
验证 OpenAI API 代理的凭据、路由、日志、流式响应和故障处理，明确生产接入条件。
On this page
摘要
直接答案：OpenAI API 代理是位于应用与 OpenAI API 之间的服务端中间层。它认证调用方、验证并限制请求、附加受保护的上游凭证、转发获准流量、保持流式传输，并在返回响应的同时，只记录运营方明确决定保留的证据。
保护密钥，不等于开放匿名调用
代理把供应商密钥移出客户端，但仍需实现自己的用户或工作负载认证、授权、滥用防护与配额。
把代理视为信任边界
代理能够看到提示词、文件、工具参数、输出、用量和上游凭证，因此运营人员、日志、插件与依赖都属于安全模型的一部分。
保持协议语义
流式事件、取消、原生请求 ID、错误、用量、工具调用与结构化输出不应被静默修改。
让行为可以验证
所有修改都要有版本，重试只能有一个责任方，数据保留必须明确，故障路径要经过测试，并保留紧急回滚或备用路径。
OpenAI API 代理是什么，又不是什么
最简单的 OpenAI API 代理会在服务端暴露一个与 OpenAI API 形状相近的端点，接收获准应用的请求，再使用保存在服务端的凭证转发到预先配置的 OpenAI 端点。它首先解决一个狭窄但重要的问题：不可信客户端不再持有或传输上游密钥。
代理并不会自动让集成变安全。如果它不认证用户、允许任意模型或上游地址、接受无限大小的请求正文、记录敏感内容，或者原样暴露上游详细错误，那么它只是移动了密钥，却扩大了滥用面。代理也不天然等同于 AI 网关；路由、预算、护栏、缓存、供应商协议转换与多租户治理都属于额外能力。
生产请求如何一步步通过代理
| 步骤 | 代理职责 | 证据 |
|---|---|---|
| 1 | 终止 TLS，并拒绝错误方法、路径、Content-Type 与超大正文 | 请求 ID、路由与拒绝类别 |
| 2 | 认证用户或工作负载，并授权本次操作 | 主体、租户、策略版本与决策 |
| 3 | 验证请求正文、模型别名、工具、限制与元数据 | Schema 版本、别名与命中限制 |
| 4 | 在服务端解析上游端点与凭证，绝不信任客户端提供的 URL 或密钥 | 路由 ID 与密钥引用，不记录密钥值 |
| 5 | 设置总截止时间，保持流式与取消语义，并执行单一、有限的重试策略 | 尝试次数、各阶段耗时与已传输字节/事件 |
| 6 | 返回稳定客户端错误，同时保留原生 ID、模型、用量与结束状态以便诊断 | 上游请求 ID、状态、用量与最终结果 |
代理、网关与兼容端点
透明代理可能几乎不修改地转发 OpenAI 契约；兼容代理可能把请求转换给其他上游；网关则增加更广泛的身份、策略、配额、路由、缓存与可观测。产品可组合这些角色，因此关键问题是哪些代码为何触碰请求。
代理成为高价值密钥与数据边界。需评估谁运营、凭证如何存储、请求数据流向哪里、记录什么日志、修改哪些字段，以及代理或上游失败时会发生什么。
代理职责与风险
| 控制 | 最适合 | 选择前验证 |
|---|---|---|
| 密钥隔离 | 让供应商密钥离开客户端，并约束代理身份。 | 密钥集中扩大爆炸半径；采用最小权限、轮换与审计。 |
| 验证与策略 | 在上游执行前拒绝异常、未授权或禁止请求。 | 定义 Fail-open 与 Fail-closed 行为，并保留错误证据。 |
| 日志与可观测 | 关联客户端、请求、上游 ID、延迟、用量与故障。 | 脱敏敏感内容、控制保留并限制运维访问。 |
| 重试与限制 | 保护上游容量并从批准的瞬态故障恢复。 | 嵌套重试会放大负载、成本与重复工具副作用。 |
| 请求转换 | 注入批准的默认值、元数据或兼容映射。 | 隐藏修改会改变安全、输出、成本与调试行为。 |
浏览器、移动端与服务端客户端的安全控制
不要把 OpenAI 供应商密钥放进浏览器 JavaScript、移动端安装包、桌面软件、公开代码仓库或用户可控配置文件。代理可以把密钥保留在受信基础设施中，但代理端点绝不能因此变成任何人都能消耗额度的匿名转发器。
先认证，再授权
验证用户会话或工作负载身份，再授权具体模型别名、操作、租户与产品功能。不要让所有客户端共用一把静态代理密钥。
限制输入范围
对白名单路径、方法、模型、工具与参数放行，并在访问上游前限制正文长度、文件大小、工具数量、最大输出、并发流与请求速率。
防止服务端请求伪造
上游主机必须由服务端配置。拒绝客户端提供的 URL、自动重定向、内部地址、异常协议与任意代理 Header。
保护错误与密钥
移除 Authorization 与 Hop-by-Hop Header，清理日志，返回稳定客户端错误，并确保密钥值不进入调用链、崩溃报告或支持包。
流式传输是一套协议契约，不只是响应正文
生产代理必须保持事件顺序、帧格式、连接保活、背压、客户端取消与最终结束状态。先缓冲完整响应再一次性返回，会失去首 Token 延迟优势，并可能显著增加内存占用。普通压缩或响应转换也可能延迟事件，甚至破坏客户端解析。
连接、首字节、流空闲与总时长应分别设置超时。客户端断开后，在上游支持的情况下应传递取消并停止消耗资源。如果已经输出部分内容后流被中断，要记录已传输的数据量，并明确标记结果不完整；不能静默重启请求，再把第二次模型响应拼接上去。
重试只能有一个责任方，并受总截止时间约束
客户端 SDK、应用服务、代理与上游平台都可能自带重试。如果多层各自重试，一次用户操作会被放大成多次付费请求，并在事故期间制造流量尖峰。应明确唯一重试层，传递尝试次数元数据，并让连接、排队、生成与重试等待共享一个总截止时间。
| 情况 | 更安全的处理 | 原因 |
|---|---|---|
| 建立连接前失败 | 在总时间允许时进行一次带抖动的有限重试 | 尚未交付输出，短暂故障可能恢复 |
| 上游限流 | 遵循重试提示，仅在严格时间内排队，否则返回稳定过载错误 | 立即重试会加重饱和与成本 |
| 已经交付部分流 | 不要自动重试，明确标记不完整 | 第二次响应可能重复或冲突 |
| 工具调用可能产生副作用 | 要求幂等或明确恢复流程 | 盲目重试会重复外部动作 |
日志要足以诊断，但不能多到造成泄露
有用的代理遥测应关联客户端请求 ID、已认证主体、租户、模型别名、上游原生请求 ID、原生模型、尝试次数、状态、各阶段耗时、Token 用量、结束原因与转换版本。这些字段通常足以回答可用性与成本问题，而无需保存完整提示词和响应正文。
如果质量或支持确实需要采集正文，应把它设计成独立、受权限控制的模式，明确采样、脱敏、保留、客户同意与删除规则。不要让调试日志演变成永久的影子数据库。第三方 APM、异常跟踪与支持系统也必须遵守同一数据政策。
把代理当作安全产品评估
运营者与部署
识别所有权、区域、网络路径、更新、依赖与支持边界。
数据处理
记录加密、日志、脱敏、保留、训练使用与删除。
修改契约
版本化每个 Header、字段、提示词、工具、流、错误与用量转换。
恢复路径
测试直连或备用访问、凭证轮换与代理不可用行为。
OpenAI API 代理生产检查表
身份与滥用防护
所有客户端都经过认证；操作按权限授权；凭证范围受限；具备用户或工作负载级配额；能发现异常流量与支出。
请求边界
路径、方法、模型、工具、MIME 类型、参数、正文大小、输出 Token、并发与上游端点均由服务端限制。
数据处理
正文暴露、脱敏、采样、日志目的地、保留、删除、运维访问、次级处理方与支持流程都有文档并经过测试。
协议一致性
对比直连与代理的流式事件、取消、工具调用、结构化输出、错误、原生 ID、用量与结束状态。
可靠性
分别设置连接、首字节、空闲与总超时；明确唯一重试方；限制过载；部分流与客户端断开均可见。
运营与恢复
演练密钥轮换、发布回滚、代理故障、上游故障、遥测故障、配置恢复、事故证据导出与紧急备用访问。
为代理做威胁建模与故障测试
- 映射信任边界、请求数据类别、凭证与每个存储位置。
- 对比代理与直连的请求、流、错误、用量与原生 ID。
- 注入代理超时、重启、部分流、上游 429 与凭证故障。
- 验证重试不能重复非幂等工具或外部动作。
- 演练紧急旁路、密钥轮换与事故证据导出。
显式表达检查点
客户端用受限身份向代理认证；代理授权工作负载、验证 OpenAI 形状请求、应用版本化且可观测的转换、执行预算，并用受保护的上游凭证转发。响应保留原生 ID 与转换证据；直连回滚被隔离并经过测试。
生产规则：只有接受代理新增的信任与故障模式后，才能用它简化客户端访问。
OpenAI API 代理常见失败模式
匿名转发器
供应商密钥虽然被隐藏，但代理没有实现调用方身份与授权，任何人都能通过公开端点消耗额度。
任意上游转发
客户端可控的 Base URL、重定向或 Header 把代理变成 SSRF 通道，能够访问内部服务或攻击者端点。
密钥或正文进入日志
Authorization Header、提示词、文件或响应进入普通应用日志、APM 调用链、异常报告或支持包。
缓冲完整流式响应
代理等待完整响应后再返回，导致首 Token 更慢、内存更高、超时风险更大，并放大长文本生成的影响。
重试放大
客户端、应用、代理与上游各自重试，在供应商最拥堵的时候把一次付费请求放大成多次。
隐藏的请求修改
默认提示词、工具、参数、模型别名或安全字段发生变化，却没有版本记录，导致质量和事故无法复现。
模型代理不是外部能力目录
代理治理 OpenAI 形状的推理流量；QVeris 补充外部 API、工具、服务与实时数据的发现和调用。让工具身份与副作用证据独立于模型代理，再通过父工作流调用链连接两者。
让代理 Policy 小于 API 本身
安全代理应认证调用方、解析 Allowlist 中的模型别名、限制请求、附加调用链上下文并转发到已配置 Upstream。它不应接受客户端提供的任意 Upstream URL、原始供应商密钥或无限请求 Body。
代理边界伪代码
POST /v1/chat/completions
authenticate(caller_token)
require(content_length <= 1_000_000)
alias = require_allowlisted(request.model)
policy = load_versioned_policy(caller, alias)
upstream = policy.endpoint # server-side configuration only
key = secret_store.get(policy.key_ref)
trace_id = new_trace_id()
response = forward(upstream, key, request, trace_id, timeout=30s)
log(trace_id, caller, alias, response.model, response.usage, response.status)
return redact_and_normalize(response)- 移除 逐跳请求头，绝不记录 Authorization 或完整敏感提示词。
- 明确唯一重试负责人，并防止非幂等工具 Effect 重复。
- 测试 SSRF、重定向、超大 Body、无效 JSON、超时与 Upstream Error。
实施参考已根据官方资料核验：OWASP API 安全。
常见问题
OpenAI API 代理就是 OpenAI 吗？
不是。它是由你或第三方运营的中间层，拥有自己的控制与风险。
为什么使用代理？
为了隔离密钥、集中策略、应用限制、增加证据或桥接兼容客户端契约。
哪些内容绝不能隐藏？
请求修改、重试行为、数据处理、上游身份、原生 ID 与最终错误原因。
更多 OpenAI API 代理问题
浏览器或移动应用使用代理安全吗？
只有在代理认证用户、授权操作、验证并限制输入、阻止任意上游 URL、控制滥用且永不返回供应商密钥时，才是安全方案。
代理会保存提示词吗？
代理不一定保存，但传输过程中能够看到提示词，因此必须明确日志、脱敏、保留、访问、删除与第三方遥测规则。
应该用代理还是 AI 网关？
代理主要负责转发边界；AI 网关通常还增加模型感知路由、协议统一、预算、护栏、缓存与治理。同一产品也可能同时承担两种角色。
官方资料与延伸阅读
OpenAI API、支持字段、数据控制与 SDK 行为会持续变化。上线前应核对最新一手文档，并测试代理实际转发的具体端点与功能。