sub_filter 仅能替换响应体内容，无法单独实现动态下线模块；需结合 map/geo 开关、Lua 动态 upstream 或 proxy_next_upstream 熔断等机制，由 sub_filter 辅助前端平滑过渡。
sub_filter 本身不能动态下线模块，它只是 Nginx 的响应体内容替换指令，用于修改后端返回的 HTML、JSON 或文本内容。所谓“动态下线模块”，实际需结合其他机制协同实现——核心思路是：让网关在不重启、不重载配置的前提下，将特定请求路径或模块流量静默拦截、重写或降级，而 sub_filter 可用于辅助完成前端感知层的平滑过渡（例如自动改写页面中的模块链接、API 地址或状态提示）。
明确 sub_filter 的定位与局限
它工作在 Nginx 输出过滤阶段，仅作用于响应体（response body），且默认只处理第一个匹配项（需 sub_filter_once off 启用全局替换）。它不改变路由逻辑、不终止 upstream 请求、不控制服务发现，因此无法单独实现“模块下线”。但它可配合以下方式提升用户体验一致性：
- 将已下线模块的前端资源 URL 替换为占位页或降级接口
- 把 JSON 响应中指向该模块的字段（如
"module_url": "/api/v1/report"）替换为空字符串或备用地址 - 在 HTML 页面中自动移除或禁用对应模块的导航菜单、按钮或 iframe src
真正实现“动态下线”的关键组合策略
需在 Nginx 层构建可热更新的开关能力，sub_filter 作为渲染层配合项：
-
用 map + geo 指令实现运行时路由开关：通过外部文件（如 /etc/nginx/conf.d/module-status.conf）定义模块启用状态，用
include引入，并配合map将变量映射为 upstream 名称或返回码；Nginx 支持nginx -s reload热重载该 include 文件（体积小、无连接中断） -
用 lua-resty-balancer 或 OpenResty 实现动态 upstream 切换：通过共享字典（shared dict）存储模块开关状态，Lua 在
balancer_by_lua*阶段决定是否跳过某 upstream；状态可通过 HTTP 接口实时更新（如 POST /api/admin/module/report/disable） -
用 proxy_next_upstream + 自定义 error_page 实现静默熔断：对目标模块 upstream 设置超时/错误触发条件，配合
error_page 502 503 504 = @fallback跳转至降级响应，再由sub_filter渲染友好提示
sub_filter 的典型协同用法示例
假设要临时下线报表模块（/report/*），后端返回 HTML 页面含导航链接 <a href="/report/dashboard">报表中心</a>，你希望自动将其替换为灰色不可点状态：
location / {
proxy_pass http://backend;
sub_filter '<a href="/report/' '<a class="disabled" href="javascript:void(0)" title="该模块暂不可用"';
sub_filter_once off;
sub_filter_types text/html application/json;
proxy_set_header Accept-Encoding '';
}
注意：proxy_set_header Accept-Encoding '' 是必须的，防止后端返回 gzip 响应导致 sub_filter 失效；sub_filter_types 需显式声明 MIME 类型。
安全与维护提醒
直接依赖 sub_filter 做业务逻辑控制存在风险：
- 响应体未压缩或含非 UTF-8 字符时易出错，建议搭配
sub_filter_last_modified on和日志监控 - 避免在高并发 JSON API 中大量使用正则替换（性能开销），优先考虑后端统一降级字段
- 所有开关操作应记录审计日志（可用 log_by_lua 记录 module=report status=disabled operator=admin）
- 真正的模块生命周期管理仍应由服务注册中心（如 Nacos、Consul）或网关控制面（如 Kong Admin API、APISIX Discovery）承担，Nginx 定位为边缘执行层
