核心要点
- 企业级 API 网关升级是一项运维变更，而不只是替换镜像标签。容量、代理信任、身份、会话行为、密钥和组件升级顺序，都会影响发布是否安全。
- API7 网关 3.10.3 的默认数据面共享内存比 3.10.2 约高 365 MiB，为 Kubernetes 运维人员提供了升级前必须完成的具体容量检查项。
- 只有来自
apisix.trusted_addresses显式信任地址的X-Forwarded-Proto、X-Forwarded-Host、X-Forwarded-Port和 RFC 7239Forwarded请求头才会被接受；其他值会被覆盖或清除。 - 内置控制台用户新增 TOTP 双因素认证和登录失败限制；新密码或升级后修改的密码必须至少包含 12 个字符。
- 更多 AI Cache 凭证会进行存储时加密，因此在混合版本窗口内，控制面和数据面的升级顺序格外重要。
- 更安全的配置验证、密钥解析、兼容性报告和配置重新同步，降低无效或陈旧状态悄然进入生产流量的风险。
API 网关是平台中连接最广泛的组件之一。它位于客户端与服务之间，从负载均衡器接收身份和网络上下文，执行安全策略，并导出运维人员理解生产流量所需的信号。因此，即使应用代码没有变化，一次网关升级也可能同时改变关键组件的容量、身份认证、请求元数据和故障响应行为。
这意味着，仅仅询问“新容器能不能启动”远远不够。稳健的升级流程还应检查：容器是否有足够内存、转发请求头是否仍能反映真实客户端、管理员访问方式是否变化、混合版本组件能否正确处理加密配置，以及每个网关实例是否都收到了有效状态。
API7 网关 3.10.3 正面处理了这一更广泛的升级难题。新版本强化了信任边界和身份控制，同时明确说明多项运维影响。它还改进了配置验证与同步路径，帮助分布式网关集群收敛到预期配置。
这为企业 API 管理提供了一个实用模型：升级安全应被视为整个流量平台的属性，而不是部署完成后才勾选的最后一项检查。
1flowchart LR
2 release[3.10.3 版本] --> capacity[容量边界]
3 release --> network[网络信任边界]
4 release --> identity[身份边界]
5 release --> secrets[密钥边界]
6
7 capacity --> memory[共享内存与 Kubernetes 限制]
8 network --> headers[可信转发请求头]
9 identity --> admin[2FA、锁定与访问令牌]
10 secrets --> versions[控制面与数据面升级顺序]
11
12 memory --> rollout[更安全的企业升级]
13 headers --> rollout
14 admin --> rollout
15 versions --> rollout升级风险分散在整个网关平台中
企业网关很少只以单进程、单主机的形式运行。典型部署通常包含一个控制面、多个数据面实例、外部数据库、负载均衡器或反向代理、身份提供商、监控系统，以及持续更新配置的自动化工具。Kubernetes 还会引入资源请求、资源限制、节点压力、驱逐行为和滚动替换。
任何边界上的变化都可能在其他位置产生症状。Pod 因内存不足被终止时，客户端看到的是可用性问题；代理未被识别为可信来源时，上游应用可能看到不同的协议或主机；登录策略收紧时，使用基本认证的自动化可能失效；控制面加密了旧数据面无法解密的值时，即使两个组件在稳定状态下都能独立运行，相关插件仍可能在升级期间失败。
API7 网关 3.10.3 在升级说明中明确展示了这些依赖关系。这一点很重要，因为它把隐藏假设转化为部署检查项。平台团队可以测试组件之间的真实契约，而不只是分别验证每个组件。
容量规划应在第一个新 Pod 启动前完成
3.10.3 最直接的基础设施变化，是更高的默认数据面共享内存。根据发布说明，默认 lua_shared_dict 分配在启动时总共比 3.10.2 多预留约 365 MiB 内存。
这些增长用于支持高级 Prometheus 指标、Kubernetes 及其他服务发现集成、SkyWalking 链路追踪，以及开发者门户 API 调用统计。即使相应能力未被实际使用，这些共享字典也会在网关启动时完成分配。因此，额外内存预留会影响所有采用默认配置的数据面，而不只是启用了全部功能的实例。
对 Kubernetes 团队而言，这是发布依赖。Pod 可能通过配置验证，却因为内存限制没有为新增预留和正常运行留出空间而被终止。当多个网关副本同时被替换时，节点内存压力也可能改变调度和驱逐行为。
升级前，团队应把 3.10.3 默认值与当前 Pod 的 requests、limits、实测负载余量、副本数量和节点容量进行对比。发布说明还指出，未使用某项功能的部署可以通过网关或 Helm 配置，把对应共享字典调回接近旧版的大小。但这应是有依据的容量决策：确认功能确实没有使用后再合理缩容，而不是为了让 Pod 启动而盲目降低内存。
这也是为什么金丝雀实例必须承载具有代表性的流量。成功启动只能证明共享内存可以完成分配；只有持续处理请求、指标、服务发现更新和链路追踪，才能证明 Pod 拥有足够的运行余量。
代理信任应该显式配置，而不是从请求中继承
转发请求头看起来只是普通元数据，但上游应用经常依据它们做出安全敏感决策。X-Forwarded-Proto 可能决定是否签发安全 Cookie，X-Forwarded-Host 可能影响重定向或生成的链接，标准 Forwarded 请求头则可以携带客户端与代理上下文。如果任意客户端都能提供这些值，应用就可能依据一条虚构的请求路径做出判断。
API7 网关 3.10.3 引入 apisix.trusted_addresses，用于决定是否信任客户端提供的 X-Forwarded-Proto、X-Forwarded-Host、X-Forwarded-Port 和 RFC 7239 Forwarded 请求头。如果没有配置该选项，或请求并非来自可信地址，网关会用自己观察到的协议、主机和端口覆盖转发值，并在转发到上游前清除 Forwarded。
如果已知负载均衡器或反向代理会提供权威信息，运维人员可以把它的 IP 地址或 CIDR 加入 trusted_addresses。信任模型由此从“请求头存在，所以信任”转变为“请求头来自获批中间层，所以信任”。
1flowchart TD
2 request[携带转发请求头的入站请求] --> source{来源地址是否可信？}
3 source -- 是 --> preserve[接受代理提供的转发上下文]
4 source -- 否 --> replace[覆盖 X-Forwarded 协议、主机和端口]
5 replace --> clear[清除 RFC 7239 Forwarded 请求头]
6 preserve --> upstream[代理到上游]
7 clear --> upstream更安全的默认行为仍然需要升级准备。团队应盘点网关前方的每个组件，确认网关实际看到的地址，并考虑网络地址转换。随后，从可信和不可信路径分别测试重定向 URL、安全 Cookie 行为、基于主机的应用逻辑和请求日志。目标不只是维持旧行为，而是只保留由明确可信关系支撑的行为。
管理员身份需要区分人工与机器访问路径
网关管理员与自动化工具不会以相同方式完成认证。人工用户适合使用第二因素和登录限速等交互式安全控制；自动化则需要可撤销、无需浏览器流程的非交互式凭证。
API7 网关 3.10.3 同时强化了两条路径。内置控制台用户可以注册 TOTP 双因素认证、保存恢复码，并在登录时完成 OTP 验证。必要时，管理员可以重置用户的 2FA 状态。新版本还增加了登录失败限制：默认情况下，连续失败 5 次后会临时封禁内置用户和来源 IP 15 分钟，并生成审计事件。新密码以及升级后修改的密码必须至少包含 12 个字符；现有密码在登录时不会重新校验是否满足新的长度要求。
机器访问路径则被明确分开。内置用户启用 2FA 后，该用户的 HTTP 基本认证会被拒绝，因为基本认证无法携带第二个认证因素。程序化集成应改用通过 X-API-KEY 发送的访问令牌。控制台访问令牌指南建议为日常访问创建独立、可撤销的访问令牌，而不是依赖初始管理员账号。
面向开发者的身份控制也更容易强制执行。开发者门户可以要求开发者先完成双因素认证注册，再访问受保护页面；这项要求会同时在登录和代理层执行。仅仅在界面中提示用户并不能构成完整访问边界，服务端强制执行可以防止客户端绕过注册要求。
使用 OpenID Connect 插件的团队还应检查会话行为。插件不再默认启用 900 秒的 refresh_session_interval。只有显式配置该值时，系统才会定期进行静默重新认证。如果环境依赖旧行为，可以设置 refresh_session_interval: 900 保持不变；否则，新默认值可以避免引入未经请求的会话刷新策略。
这些变化共同推动更清晰的身份架构：人员使用交互式控制，自动化使用有范围的访问令牌，会话刷新则通过显式配置决定。
混合版本密钥处理让升级顺序成为安全的一部分
存储时加密可以保护网关配置中的凭证，但引入加密也会产生兼容性边界。写入加密值的组件与读取它的组件必须理解相同格式。
在 3.10.3 中，控制面会加密语义 AI Cache 使用的 OpenAI 和 Azure OpenAI 嵌入模型 API 密钥。API7 网关的升级顺序是先控制面、后数据面。因此在这段窗口内，3.10.3 控制面可以加密这些字段，而 3.10.2 数据面无法解密。受到影响的 ai-cache 配置可能会在数据面完成升级前失效。
缓解方式简单却重要：控制面升级后应尽快升级数据面，并避免在双方都运行 3.10.3 前编辑受影响的 AI Cache 配置。这样可以缩短配置写入跨越兼容性边界的时间。
除加密外，本次发布也修复了密钥解析行为。消费者身份认证在无法解析引用密钥时，现在会采用失败关闭，而不会把未解析的字面量建立索引并当作可用凭证。更新或删除 /secrets 下的配置时，密钥缓存会失效，从而重新解析新值，避免旧值一直保留到无关的过期时间或进程重启。
这些修复强调了同一个原则：无法解析或已经变化的密钥，应产生明确且安全的结果，而不是悄然保留含糊的认证行为。
更安全的发布依赖有效且一致的配置
只有当配置被一致接受并到达每个网关实例时，它才真正有用。3.10.3 同时改善了这两个方面。
控制面现在会拒绝多类此前可能被数据面静默丢弃的无效核心资源和运行时服务插件配置。批量 SSL 验证改用正确的模式，IPv6 上游主机现在可以正常使用，兼容性报告也会保留完整且经过排序的结果，而不是只保留 200 个无序项目。对大型部署而言，这能更可靠地展示目标配置是否真正兼容。
当配置历史向后回退时，数据面也会采取更安全的响应。如果恢复后的控制面数据库报告的配置版本低于网关已知版本，网关现在会强制执行完整配置重新同步，而不是继续提供陈旧配置直到工作进程重启。与此同时，新增宽限期可以防止配置版本正常变化后的短暂窗口内，把最近仍在发送心跳的健康实例标记为不同步。
SQL Server 部署还有一项首次启动注意事项。控制面会启用 READ_COMMITTED_SNAPSHOT，避免配置读取被写入操作阻塞。如果现有数据库尚未启用该设置，首次启动 3.10.3 时会通过 ROLLBACK IMMEDIATE 应用数据库级变更。这可能会一次性断开进行中的事务和会话，之后连接池会重新连接。使用 SQL Server 的团队应把这一事件纳入控制面升级计划并进行观察。
升级到 3.10.3 前需要检查什么
请结合版本发布说明使用滚动升级指南。一套实用的检查顺序如下：
- 容量： 根据新的共享字典默认值计算内存余量，在替换 Pod 前调整 Kubernetes
requests、limits和节点容量。 - 代理拓扑： 列出可信负载均衡器和反向代理地址，配置
apisix.trusted_addresses，并测试转发主机、协议、端口和重定向行为。 - 管理员访问： 识别内置用户、使用基本认证的自动化、访问令牌所有者、锁定监控、密码策略、2FA 恢复和紧急访问流程。
- 会话策略： 决定是否继续启用 OIDC 静默重新认证；如有需要，显式配置刷新间隔。
- 密钥兼容性： 找出语义 AI Cache 的嵌入模型凭证，尽量缩短混合版本窗口，并在数据面全部升级前暂停相关编辑。
- 数据库行为： 如果使用 SQL Server，应为一次性的快照隔离变更和可能的连接中断做好准备。
- 配置可信度： 检查完整兼容性报告，测试无效配置，并确认配置版本变化后每个网关实例都会收敛到同一状态。
- 金丝雀发布与观察： 先升级一个具有代表性的网关组，发送真实测试流量，检查代理和资源指标，确认新节点持续稳定后再继续。
1flowchart TD
2 review[阅读 3.10.3 升级说明] --> size[规划内存与节点容量]
3 size --> trust[梳理可信代理地址]
4 trust --> access[区分人工与自动化访问]
5 access --> cp[升级控制面]
6 cp --> db{是否涉及 SQL Server 快照变更？}
7 db -- 是 --> observe[观察连接恢复]
8 db -- 否 --> freeze[暂停编辑受影响的 AI Cache]
9 observe --> freeze
10 freeze --> canary[升级金丝雀数据面]
11 canary --> verify[验证流量、指标、请求头、认证与配置同步]
12 verify --> fleet[继续滚动升级整个集群]让安全状态同时具备可运维性
最有价值的安全默认配置，是运维人员能够理解并持续维护的配置。API7 网关 3.10.3 推动多项边界向这个方向演进：转发上下文来自可信中间层，管理员登录获得更强控制，自动化拥有基于访问令牌的路径，无法解析的消费者凭证密钥会失败关闭，无效配置也会更早被拒绝。
新版本还把运维成本明确展示出来。更多共享内存意味着必须进行容量规划；存储时加密要求组件版本保持协调；更强的认证态势需要配套恢复方案；可靠的兼容性报告则必须覆盖完整配置范围。
这才是更安全的企业升级：它并不意味着没有变化，而是每项变化都有明确负责人、验证方法和故障边界。
阅读完整的 API7 网关 3.10.3 发布说明，遵循滚动升级流程，并在更新整个集群前，先在具有代表性的网关组中验证容量、信任、身份、密钥和配置收敛情况。