核心要点
- 自定义网关代码不仅需要代码审查，也需要环境边界。否则一次上传就可能改变共享同一插件对象的所有网关组。
- API7 网关 3.10.6 发布于 2026 年 8 月 25 日，将自定义插件从控制面级资源调整为网关组级资源。
- 预发布与生产环境现在可以使用相同插件名称运行不同版本，团队可先在一个网关组内验证变更，再发布到另一个网关组。
- 资源模型、Admin API、插件目录和权限策略现在都以网关组作为权限范围。
- 升级程序会迁移已经部署的插件并改写相关策略，但仍需明确检查未部署插件、失效的路由引用和回滚行为。
- 更安全的发布流程应把插件源码、依赖、元数据、权限、配置和回滚制品视为一个经过版本化的发布单元。
自定义插件可以让 API 网关对接专有身份系统、执行组织特定策略、转换特殊协议，或补充内置插件尚未提供的逻辑。它的价值恰恰来自代码能够在网关请求生命周期内运行，也正因如此，插件更新可能影响生产流量的身份认证、路由、请求体、延迟和日志。
风险不仅取决于 Lua 代码是否正确，还取决于发布操作会影响多大范围。
在 API7 网关 3.10.6 之前，自定义插件是控制面范围内的单一对象。同一份代码会绑定一个或多个网关组，上传新版本就会替换所有已绑定网关组共享的对象。团队首次把新插件发布到生产前，可以先在预发布环境测试；但当预发布和生产开始共享同一个对象后，更新预发布也会同步更新生产。
这种模型让运维约定承担了过多责任。审查人员可以要求团队先在预发布环境完成验证，但产品的资源边界并不能保证验证期间生产副本保持不变。
API7 网关 3.10.6 改变了所有权单元：自定义插件现在属于单个网关组。扩展发布的影响范围因此更小——上传到测试组的版本只留在该组，生产环境继续运行现有副本，直到团队有意将变更发布到生产网关组。
自定义插件风险也是发布范围问题
网关扩展包含两个不同问题：代码允许执行什么操作，以及代码被部署到哪里。安全代码审查处理第一个问题，发布边界处理第二个问题。
假设一个平台包含开发、预发布和生产三个网关组，三者都使用名为 tenant-policy 的自定义插件。团队准备修改插件读取声明并添加请求头的方式。
在控制面级共享对象模型下，这个名称只对应一份代码制品。更新该制品可能改变其部署到的所有网关组。团队可以临时使用另一个插件名称测试，但这也改变了受测的路由配置，最终生产发布仍需更新共享对象。
在网关组级资源模型下，每个环境都拥有自己的副本。开发和预发布环境可以运行候选版本，生产环境则继续以相同的 tenant-policy 名称运行上一个获批版本。路由、服务与插件元数据无需仅为建立隔离边界而改用临时名称。
这并不意味着自定义代码从此没有风险。插件仍可能在所在网关组内阻断流量、暴露数据或消耗过多资源。团队仍需执行代码审查、schema 校验、性能测试、安全测试和可观测性验证。此次调整的价值在于让这些控制措施真正有效：测试环境的发布不会同时替换生产制品。
3.10.6 将网关组变成发布边界
自定义 Lua 插件指南现已采用网关组级发布流程：先把插件上传到测试网关组，在代表性流量上启用并验证其行为，再把获批版本上传到生产组。
同一插件名称可以在不同网关组中对应不同代码，因此网关组可以成为实际的发布边界：
- 开发环境可以快速迭代，并对接模拟或本地依赖。
- 预发布环境可以使用接近生产的路由、身份流程和上游行为运行候选版本。
- 生产环境会继续使用已获批版本，直到发布操作明确指向其网关组。
1flowchart LR
2 source[已版本化插件包] --> review[代码与安全审查]
3 review --> test[上传到测试网关组]
4 test --> validate[验证流量、日志与失败路径]
5 validate --> decision{是否批准发布？}
6 decision -- 否 --> revise[修改插件]
7 revise --> review
8 decision -- 是 --> prod[上传到生产网关组]
9 prod --> observe[观察生产并保留回滚制品]该图展示的是发布流程，而不是自动同步制品。API7 网关不会推断预发布副本已经获准进入生产；生产上传仍是一次独立且有意的操作。
这种隔离也能改善所有权管理。负责某个网关组的团队可以管理自己的插件副本，而不会替换其他网关组使用的代码。资源范围、发布操作和权限现在可以共同描述同一条环境边界。
API 与权限变更与新范围保持一致
只有所有管理入口都使用同一范围，较小的发布边界才能真正生效。因此，API7 网关 3.10.6 在调整插件存储方式的同时，也修改了 API 和权限模型。
自定义插件端点从：
1/api/custom_plugins迁移到：
1/api/gateway_groups/{gateway_group_id}/custom_plugins调用旧路径会返回 HTTP 410，并指出替代路径。PUT 现在按插件名称执行创建或替换，发布流水线可通过一次操作把一个版本上传到一个网关组。请求与响应中不再包含原有的 gateway_groups 列表，因为网关组已经是资源路径的一部分。GET /api/plugins 也要求提供 gateway_group_id 查询参数，以便返回特定网关组的插件目录。
自动化流程不应把 HTTP 410 当作临时故障，而应将其视为明确的迁移信号。流水线需要选择目标网关组、调用新端点，并确认后续路由或服务变更查询的是同一网关组中的插件目录。
权限也随资源一同迁移。自定义插件操作过去作用于 arn:api7:gateway:gatewaysetting/*，现在作用于对应的 arn:api7:gateway:gatewaygroup/{gateway_group_id} 资源。由于 PUT 通过 gateway:UpdateCustomPlugin 执行创建或替换，gateway:CreateCustomPlugin 已被移除；读取插件源码现在需要 gateway:GetCustomPlugin。
读取权限的变化尤其重要。在 3.10.6 之前，任何已登录用户都能读取任意自定义插件的源码。升级后，没有新增读取操作权限的角色无法列出或读取这些源码。团队应依据当前的权限策略操作与资源参考，仅向确实需要的角色和网关组授予访问权限。
对于发布自动化，权限问题不再是“该身份能否在控制面的某个位置管理自定义插件”，而是“该身份能否读取或替换这个网关组中的自定义插件”。这是一条更容易审查的最小权限边界。
迁移会保留运行行为，也会暴露配置漂移
3.10.6 升级程序会自动处理常见情况。每个现有自定义插件都会按照此前部署到的网关组展开成多条记录，使这些网关组能够在资源模型调整后继续运行插件。
相关权限策略也会被改写。自定义插件操作会从旧网关设置资源迁移到网关组语句，并保持相同的效果与条件；gateway:CreateCustomPlugin 会被替换，同时新增 gateway:GetCustomPlugin。被替换的策略文档会保留在 permission_policy_backup 中，供后续检查。
自动迁移无法凭空推断旧数据中从未记录的意图，因此以下两种情况需要运维人员处理：
- 插件未部署到任何网关组。 升级程序无法判断它属于哪个组，因此只会记录日志而不会迁移。请把它上传到实际需要的每个网关组。
- 路由引用了从未部署到自身网关组的插件。 旧控制面会接受该引用，但插件实际不会在该组运行。升级后，该网关组仍不存在此插件，下一次写入该路由时会报告未知插件。请把预期插件上传到该组，或删除失效配置。
第二种情况提供了有价值的运维反馈：原本静默存在的配置漂移会变成写入时错误。不过，如果团队默认每个已保存的插件引用都在生效，这一变化也可能带来意外。升级前应盘点引用关系，区分“已经配置”与“确实存在于这个网关组”。
权限策略迁移也需要同等重视。请把生成的网关组语句与开发、预发布和生产环境的责任角色进行对照。自动保留的宽泛授权或许兼容旧行为，但未必符合新模型所支持的更严格隔离。
回滚也要考虑代码版本
新的资源模型也改变了回滚含义。控制面运行 3.10.6 时上传的插件代码会存储在新的网关组表中。如果控制面回滚到更早版本，旧版本会读取升级前的表，并提供当时仍保留在其中的插件代码。
换言之，回滚产品版本不会自动把升级后上传的插件变更复制到旧存储模型。团队可能恢复了旧控制面，却发现插件代码也回到了升级前的制品，即使 3.10.6 升级后已经发布过更新版本。
应把应用版本和插件版本视为两个相互关联的回滚输入。发布前请保留：
- 每个网关组升级前的插件源码或插件包；
- 带校验和的候选制品与已发布制品；
- 插件名称、网关组与获批版本之间的映射；
- 相关路由、服务、消费者、全局规则和插件元数据配置；
- 升级前的策略文档和迁移后的网关组策略。
回滚演练应同时验证控制面恢复和流量行为。请确认旧控制面实际提供哪个插件版本、哪些路由引用了它，以及数据面依赖是否仍然兼容。不要默认容器成功回滚就代表扩展状态已经恢复到预期版本。
为自定义网关代码建立更安全的发布模型
网关组级资源模型支持一套清晰的发布规范。具体流程可以使用控制台、Admin API 或内部自动化，但发布单元应始终保持一致。
- 对完整制品进行版本化。 将插件源码、依赖和元数据一并存储。即使对外插件名称保持不变，也要记录制品摘要。
- 审查特权行为。 除了 Lua 语法，还要检查请求和响应访问、网络调用、密钥处理、日志、失败模式与执行成本。
- 只上传到一个非生产网关组。 明确指定目标网关组，并验证任何生产组都未发生变化。
- 测试真实配置形态。 在代表性路由或服务上启用插件，使用与生产一致的 schema 和相邻插件顺序。
- 覆盖失败路径。 测试无效配置、依赖故障、上游超时、异常输入，以及插件在重新加载或重启期间的行为。
- 发布同一份已审查制品。 将完全相同的摘要上传到生产网关组，不要在环境之间重新构建。
- 先观察，再扩大范围。 关注错误、延迟、状态码、上游行为和业务信号，然后再发布到更多网关组。
- 按网关组保留回滚版本。 为每个生产组保存上一个获批版本，不要假设所有网关组运行同一版本。
该模型将“插件名称相同”与“所有环境运行同一版本”区分开来。这有利于分阶段发布，也带来新的制品盘点责任：运维人员应能随时回答每个网关组正在运行哪个插件版本。
升级前应验证什么
请结合 API7 网关升级指南与 3.10.6 更新日志，验证适用于当前部署的自定义插件生命周期：
- 导出自定义插件、已部署网关组，以及引用它们的所有路由、服务、消费者、全局规则与插件元数据清单。
- 找出未部署到任何网关组的插件，决定升级后将其上传到目标网关组，还是直接停用。
- 找出引用了当前网关组中不存在插件的资源；应在升级后的常规编辑暴露错误前修复这些漂移。
- 将自动化流程从
/api/custom_plugins迁移到网关组端点，按创建或替换语义处理PUT，并在读取插件目录时传入gateway_group_id。 - 检查目标网关组资源上
gateway:UpdateCustomPlugin和gateway:GetCustomPlugin的角色映射。 - 审查迁移后的策略，并保留
permission_policy_backup，直到访问行为得到确认。 - 验证现有插件在此前部署的每个网关组中仍正常运行，同时确认修改测试组副本不会改变生产环境。
- 记录升级前与已发布插件制品，并完成足够深入的回滚演练，确认旧控制面实际提供的代码版本。
- 在整个发布期间监控插件错误、路由兼容性报告、流量结果和审计事件。
只有当代码范围、发布范围和授权范围保持一致时，API 网关扩展能力才更安全。API7 网关 3.10.6 让网关组成为三者共同的边界。它没有替代严谨的插件工程实践，而是为环境隔离提供了能够落实这些实践的资源模型。
请阅读完整的 API7 网关 3.10.6 更新日志，了解插件执行顺序与作用范围，并在生产发布前，把适用于当前部署的每项迁移与回滚条件都转化为预发布验证项。