核心要点
- API7 网关 3.10.2 将 AI 效率、安全、可观测性、流量控制和开发者访问纳入同一个版本，不再把它们视为彼此割裂的平台问题。
- 新增的 AI Cache 插件可以让相同的大语言模型（LLM）请求直接从 Redis 缓存返回响应；新增的 AI Lakera Guard 插件则能检查提示词和响应中的提示词注入及其他不安全内容。
- 更丰富的
llm_summary字段、叠加式日志格式，以及嵌入调试会话链路的请求日志，为模型行为分析和故障响应提供了更完整的上下文。 - 限流修复弥补了变量校验和并发控制上的缺口，让配置的配额在跨路由和 Redis 高并发场景下仍能真正生效。
- 开发者门户的改进强化了邮箱验证、组织管理、文档交付和服务端 SSO 策略执行。
- 升级时需要协调控制面与数据面的版本，并明确检查 HMAC 请求体限制和开发者门户注册同意配置的迁移情况。
AI 应用很少会永远停留在一次模型调用上。进入生产环境后，请求链路会不断延长：验证用户身份、执行配额、检查提示词、选择模型、处理流式响应、记录 Token 和工具调用、排查故障，最后再把相关能力开放给开发者。
如果每一个环节都由不同的应用库或服务负责，平台很快就会变得难以治理。不同团队采用不同的缓存策略，提示词防护不一致，提供商错误被适配器吞掉，配额在并发场景下表现不一。运维团队能看到 HTTP 状态码和延迟，却缺少解释 LLM 行为所需的上下文。开发者随后又要通过另一套拥有独立身份和文档生命周期的门户来使用这些 API。
2026 年 6 月 29 日发布的 API7 网关 3.10.2，把这些问题视为同一条端到端流量链路来处理。该版本加入网关层的 AI 缓存与提示词防护，扩展请求级可观测性，提高限流可靠性，强化密钥与身份控制，并为平台团队提供更多运营开发者门户的手段。
这不只是一次 AI 功能更新。它让平台能够治理从提示词到模型提供商、从故障到链路追踪，以及从 API 产品到开发者的完整路径。
1flowchart LR
2 developers[开发者与 AI 应用] --> portal[开发者门户]
3 portal --> gateway[API7 网关 3.10.2]
4 gateway --> identity[身份与会话策略]
5 gateway --> limits[配额与限流]
6 gateway --> guard[提示词与响应防护]
7 gateway --> cache[AI Cache]
8 gateway --> models[LLM 提供商]
9 gateway --> telemetry[日志、指标与调试会话]
10 telemetry --> operations[平台运维]生产 AI 流量是一条完整链路，而不只是一次代理调用
AI 网关可以在多个模型提供商前提供稳定的访问端点，但仅仅实现连接，并不意味着 AI 流量已经具备生产就绪能力。平台团队还需要回答贯穿请求生命周期的一系列问题：
- 这个应用或开发者是否有权使用该模型？
- 同一个消费者跨多条路由时，应该应用哪一组配额？
- 提示词能否安全发送？响应返回前是否也需要检查？
- 完全相同的请求能否直接复用结果，而不再支付一次模型调用成本？
- 请求是否采用流式传输、调用了工具、使用了推理 Token，或消耗了提供商缓存中的 Token？
- 如果提供商返回
HTTP 429或5xx，客户端能否获得足够的信息并采取正确措施？ - 运维人员能否直接从故障定位到相关请求日志，而不必搜索多个彼此割裂的系统？
网关是一个合适的控制点，因为它能够看到通过验证的身份、请求体、策略决策、选中的上游、响应和最终状态。在这里实施控制，可以让多个应用共享同一套规则，而不必由每项服务重复建设。
API7 网关 3.10.2 从三个相互关联的方向强化了这个控制点：在调用模型前增加预防性控制，在调用期间和之后补充诊断上下文，并围绕使用 API 的开发者和应用实施治理。真正的价值，在于把这些能力作为同一套运行模式来管理。
在请求进入上游前控制 AI 成本与风险
重复的 LLM 请求会带来明显的效率问题。客服助手、分类服务、摘要流水线和内部工具，都可能多次发送完全相同的规范化请求。如果每次都调用上游模型，答案并不会发生变化，延迟和 Token 成本却会不断累积。
API7 网关 3.10.2 引入了 AI Cache 插件。它根据规范化请求体和所选 AI 实例的配置生成精确匹配缓存键，并将成功响应存入 Redis。命中缓存时，网关不再调用模型，而是直接返回缓存响应，并携带 X-AI-Cache-Status: HIT 和 X-AI-Cache-Age。未命中时，请求会继续发往上游，并可写入缓存。在 3.10.2 中，流式请求会绕过缓存并返回 X-AI-Cache-Status: BYPASS。
将这一能力集中在网关中，平台团队就能清楚掌握缓存策略。运维人员可以选择适合精确复用的路由，设置存活时间，限制缓存响应体大小，明确决定缓存键是否隔离或共享，并通过响应头区分命中、未命中和绕过。
缓存并不天然适合所有提示词。用户特定上下文、租户数据、模型版本变更和新鲜度要求，都会影响两个请求是否应该共享响应。网关不会替平台做出这个决定，但它提供了一个统一制定和审计策略的位置。
成本控制之外，还需要安全边界。API7 网关 3.10.2 新增 AI Lakera Guard 插件，通过 Lakera Guard 检查 AI 流量。运维人员可以选择检查输入、输出或双向内容。对于被标记的流量，可以直接阻断，也可以先以告警模式记录，从观察逐步过渡到强制执行。
AI Aliyun Content Moderation 插件也新增了 request_check_mode。团队可以根据应用的风险和成本特征，只检查多轮对话中最后一条用户消息，或检查全部用户消息。长文本会以线性时间切分，并保证 UTF-8 多字节字符安全。
1flowchart LR
2 request[AI 请求] --> gateway[API7 网关 3.10.2]
3 gateway --> cache[AI 缓存控制]
4 gateway --> safety[输入与输出安全控制]
5 gateway --> upstream[LLM 上游]
6 cache --> cacheOutcome[命中、未命中或绕过]
7 safety --> safetyOutcome[放行、告警或阻断]
8 upstream --> modelOutcome[模型响应或错误]
9 cacheOutcome --> governed[受治理的 AI 流量]
10 safetyOutcome --> governed
11 modelOutcome --> governed上图展示的是网关承担的控制职责，不代表组合使用多个插件时的实际执行顺序。团队应在预发布环境中验证所选插件和策略的最终行为。
缓存和安全控制分别回答了两个问题：“是否还需要调用一次上游？”以及“这段内容是否应该跨越边界？”把这两个判断放在流量路径附近，可以减少重复的应用逻辑，并形成更一致的 AI 治理模式。
让模型行为在故障期间可解释
传统 API 监控通常从请求量、错误率和延迟开始。这些信号对 AI 流量依然重要，但无法解释 Token 用量、流式体验、工具活动或提供商特定故障。
启用摘要日志后，API7 网关 3.10.2 会扩展日志插件输出的结构化 llm_summary。新增字段包括请求是否流式传输、可用工具数量、是否发生工具调用、终端用户标识、从提供商缓存读取或写入的 Token，以及推理 Token。这些字段可以帮助团队区分在 HTTP 层看起来相似、但成本和执行路径截然不同的请求。
例如，两个请求可能都在 8 秒内返回 HTTP 200。其中一个可能是简短的非流式响应；另一个则可能很快开始流式输出，调用了工具，并消耗大量推理 Token。排查成本或延迟时，运维人员需要在遥测数据中看到这些差异。
数据面现在支持 log_format_extra，它会在默认的丰富日志格式上增加字段，而不是要求团队完全替换默认格式。这一点很重要，因为自定义 log_format 可能意外删除有用的默认上下文。新增的 $upstream_unresolved_host 变量还会记录 DNS 解析前配置的上游主机名，帮助团队把解析后的后端地址与原本计划调用的模型或服务关联起来。
调试会话也变得更加自包含。每个请求的日志可以作为 OpenTelemetry Span 事件记录到根 Span 上。因此，运维人员检查调试会话时，可以直接在链路中查看单请求日志，而不必为了这次排查额外依赖外部日志采集器。
多项可靠性修复让这些遥测信息更便于实际排障。当上游模型返回 HTTP 429 或 5xx 等错误时，AI Proxy 现在会保留响应体和内容类型，包括触发 AI Proxy Multi 故障切换的情况。如果上游遗漏最终完成数据块，Anthropic 流式请求不再一直等待到超时。格式错误的工具调用也不会导致其余响应内容丢失；构建 AI Proxy Multi 工作实例池失败时，也不会再破坏性地清空实例池状态。
1flowchart TD
2 request[LLM 请求] --> summary[llm_summary 上下文]
3 request --> trace[调试会话根 Span]
4 request --> upstream[LLM 上游]
5 upstream --> outcome[响应或提供商错误]
6 summary --> logs[包含附加字段的网关日志]
7 trace --> events[单请求日志事件]
8 outcome --> details[保留错误响应体和内容类型]
9 logs --> triage[故障排查]
10 events --> triage
11 details --> triage这缩短了从症状到解释的距离。过去，运维人员需要手工关联告警、通用网关日志、提供商响应和应用侧 LLM 元数据；现在，更多上下文可以直接在做出路由决策的网关中收集。
让配额和身份在真实流量下保持正确
AI 流量成本高且容易突增。因此，即使请求并发执行，或同一消费者使用多条路由，配置的限制也必须保持正确。
API7 网关 3.10.2 修复了三项重要的限流行为。首先，Limit Count 现在会校验由变量解析得到的 count 和 time_window。无效、非正数或超出安全范围的值会被拒绝，而不是被忽略。此前忽略这些值可能导致预期的限流失效。
其次，基于 Redis 的滑动窗口计数改为使用原子脚本。如果检查和递增不是原子操作，并发请求可能同时读到相同的旧计数，最终共同突破配额。修复后，高并发下的实际结果才能与配置策略一致。
第三，Limit Request 现在会按父级资源确定共享资源限制的键。绑定在消费者上的限制会跨该消费者的全部路由统一执行，而不会为每条路由分别创建独立计数桶。
这些看似是实现细节，却会直接影响治理效果。平台团队依靠限流保护模型容量、分配租户预算并减少“吵闹邻居”问题。如果计数范围或并发行为与策略定义不一致，配额就只是名义上的限制。
身份边界也得到了类似强化。即使匹配的消费者没有标签值，Attach Consumer Label 插件也会从客户端请求中移除已配置的身份请求头，避免客户端伪造一个看似由网关注入的值。开发者门户基于邮箱域名的 SSO 策略也不再只在界面中执行，而是由服务端强制实施。因此，要求使用 SSO 的域名无法通过直接调用密码登录、邮件链接登录或密码重置端点来绕过策略。
OpenID Connect 现在可以把会话存储在 Redis 中，而不是把会话状态放入 Cookie。对于分布式部署，团队因此获得了一种服务端会话方案，同时 Cookie 仍是默认存储方式。该版本还支持 Elasticsearch Logger 通过自定义请求头向 Elasticsearch 进行认证，为可观测性流水线提供基本认证（Basic Auth）之外的选择。
随着凭证字段增加，3.10.2 也扩大了存储时加密的覆盖范围，包括限流插件和 AI Cache 使用的 Redis 密码、AI Lakera Guard API 密钥、OpenID Connect Redis 会话密码，以及 Elasticsearch 自定义认证请求头。这项安全改进伴随着一项重要的升级顺序要求，后文会详细说明。
将运行时治理延伸到开发者门户
流量路径只是 API 体系的一半。开发者还需要一个受控的入口，用于查找文档、完成认证、加入组织和使用 API 产品。
API7 网关 3.10.2 从多个方面扩展了开发者门户：
- 如果部署不应公开 API 目录，运维人员可以完全关闭 API Hub。导航入口、页面和站点地图条目会一起移除。
- 注册或登录完成前，可以强制要求邮箱验证。
- 平台管理员可以接管组织所有权或删除组织，便于在原所有者无法继续管理时完成恢复和生命周期管理。
- 门户可以使用自定义 PostgreSQL 模式，而不是固定使用
public，帮助组织在已有数据库服务中隔离门户数据。 - 文档可以通过 Markdown 和面向 LLM 的文本端点提供给 AI 工具，同时也能排除指定页面，而不影响这些页面在人类可读的文档站点中展示。
该版本还修复了开发者身份相关的安全和可用性问题。现在，启用或关闭双因素认证（2FA）时会真正校验账户密码；备用恢复码可以正常显示；登录时输入错误的 TOTP 验证码会显示错误，而不是跳转到主页。
这些变化把 API 治理与开发者体验连接起来。平台团队可以决定 API 目录是否公开、是否要求验证身份、如何维持组织边界，以及哪些文档可以被 AI 工具读取。开发者仍然可以获得自助式体验，但相关策略由平台强制执行，而不是依赖界面上的默认假设。
提高应用层之下的可靠性
API7 网关 3.10.2 的多项数据面变更，解决了不应由应用自行处理的基础设施问题。
域名上游在遭遇短暂 DNS 或服务发现故障后，会在解析恢复时重新正常工作，而不会持续返回 HTTP 503。当节点变为不健康时，一致性哈希环会保持稳定，只重新映射属于故障节点的键，而不会移动健康节点上的流量。Prometheus 库升级也移除了可能导致整个抓取请求被拒绝的重复指标序列。
新增的 max_post_args_readable_size 会限制网关在匹配 post_arg.* 路由条件时读取的 JSON 或 multipart 请求内容大小。默认值为 64 MiB，也可以设置为 0 以关闭限制。这让运维人员可以直接控制大请求体参与路由匹配时的内存风险。
部署方式也得到扩展。API7 网关 3.10.2 新增了数据面的 RPM 安装方式，其中包含离线脚本，可自动配置网关组客户端证书、写入配置，并把实例加入控制面。这适合无法联网，或没有统一采用 Docker 和 Kubernetes 的主机环境。
这些更新与 AI 和门户能力的改进目标一致：让基础设施行为保持可预测，使应用团队能够信赖网关提供的契约。
升级到 3.10.2 前需要检查什么
API7 网关 3.10.2 增加了多项重要控制能力，但有三项升级说明需要提前准备。
协调控制面与数据面的密钥处理
3.10.2 控制面会对更多插件字段执行存储时加密。旧版 3.10.1 数据面无法解密由 3.10.2 控制面新加密的字段。在控制面与数据面版本不一致的窗口期，受影响的限流插件、AI Cache、AI Lakera Guard、Elasticsearch Logger 或 OpenID Connect 配置可能失效。
因此，应在控制面升级后尽快升级数据面，并在两侧都升级到 3.10.2 之前避免编辑受影响的插件。提前盘点这些字段，可以降低兼容窗口内意外变更配置的风险。
重新检查 HMAC 请求体限制
当 hmac-auth 启用请求体校验时，3.10.2 中 max_req_body_size 的默认值为 64 MiB，高于 3.10.1 的 512 KiB，并与 Apache APISIX 保持一致。超过限制的请求现在会返回准确的 HTTP 413，而不是容易误导的 HTTP 401。
如果现有环境把较低限制作为安全边界，应显式配置该值。如果合法签名请求可能接近 64 MiB，则应测试网关和上游的内存表现，而不能把更高的默认值视为容量建议。
迁移开发者门户注册同意配置
注册同意现在统一使用 signUpConsentLabel，其内容是一段显示在同意复选框旁的 HTML。原有的 tosURL 和 beforeSignUpButtonHtml 已被移除。升级前应迁移现有同意内容，否则相关文字将不再显示；同时，只有配置了标签时才会强制执行同意检查。
除了上述必查项，还应使用有代表性的生产行为进行测试：
- 缓存命中、未命中、绕过、租户边界和 Redis 故障行为。
- 输入与输出防护策略在告警和阻断模式下的表现。
- 流式补全、格式错误的工具调用、故障切换、提供商
429响应和5xx错误。 - 并发流量下的动态限流和消费者级限流。
- 包含嵌入式日志的调试会话链路，以及
end_user_id等 LLM 上下文所需的隐私控制。 - 开发者门户邮箱验证、SSO 域名策略、2FA 恢复和注册同意。
- DNS 恢复、一致性哈希行为、Prometheus 抓取，以及包含大型
post_arg.*请求的路由匹配。
治理完整路径，而不是孤立功能
API7 网关 3.10.2 的意义在于，生产级 AI 与 API 管理正在走向融合。同一个平台必须同时控制模型成本、提示词安全、身份、配额、遥测、故障响应、开发者访问和基础设施可靠性。
该版本让这些职责更加紧密地结合在一起。AI Cache 可以在适合精确复用的场景中减少重复模型调用；AI Lakera Guard 和内容审查在提示词与响应周围建立策略边界；更丰富的 LLM 日志和调试会话事件让故障更容易解释；原子且范围正确的限流让配额真正生效；开发者门户控制则把治理延伸到使用 API 的人员和工具。
更重要的是，这些能力不必分别变成独立的应用项目。平台可以在网关层把它们作为一套端到端流量系统统一运营。
阅读完整的 API7 网关 3.10.2 更新日志，查看 API7 AI 网关文档，并在升级前结合控制面、数据面、Redis、身份系统和开发者门户配置，逐项验证升级说明。