mod_filter仅负责条件分发响应给实际处理的过滤器；需按声明（filterdeclare）、绑定（filterprovider）、启用（filterchain/setoutputfilter）三步顺序配置，且filterdeclare与filterprovider必须成对前置，filterchain与setoutputfilter须同作用域，provider须适配内容类型与编码，验证需分层检查响应头、日志及输入输出一致性。

mod_filter 本身不处理内容，只负责按条件把响应分发给真正干活的过滤器（比如 mod_substitute、mod_deflate 或 mod_ext_filter）。要让流水线动起来，关键不是写一堆指令，而是理清声明、绑定、启用三步之间的依赖和顺序。

FilterDeclare 和 FilterProvider 必须成对且前置

FilterDeclare 只是起个名字，比如 FilterDeclare json_prettify，它本身不触发任何行为。真正决定“什么时候用哪个过滤器”的是紧随其后的 FilterProvider，例如：

• FilterProvider json_prettify resp=Content-Type $application/json 表示：当响应头 Content-Type 以 application/json 开头 时，才调用名为 json_prettify 的过滤器
• 匹配表达式中的 $ 是正则含义的“开头”，不是字面美元符
• 如果要用环境变量控制（如调试开关），可写成 env=ENABLE_JSON_FORMAT，再配合 RewriteRule ... [E] 或 SetEnvIf 设置该变量
• 多个条件支持布尔运算：resp=Content-Type $text/html && env=DEBUG

FilterChain 和 SetOutputFilter 要在同一作用域内配对

FilterChain 是启用某组 provider 的“总开关”，SetOutputFilter 是把 filter 名称挂进输出链的动作。两者必须在同一个配置块里（如 <virtualhost></virtualhost>、<directory></directory> 或全局），否则会报错。

Apache Superset Dashboard and SQL Exploration Skill

Apache Superset 是一个广泛采用的开源 BI 平台，用于 SQL 探索、图表构建和仪表板交付。当代理需要查询仓库数据、组装仪表板或使用成熟的分析界面解释指标而不是临时笔记本代码时，此技能非常有用。

下载

• 常见错误：全局写了 FilterDeclare mysub 和 FilterProvider mysub ...，但在 <directory></directory> 里只写 SetOutputFilter mysub → 报错 Invalid filter name 'mysub'
• 正确做法：在同一个 <directory></directory> 块里，先写 FilterChain mysub，再写 SetOutputFilter mysub
• FilterChain 支持叠加：FilterChain mysub json_prettify 表示同时启用两个 provider，执行顺序按列出顺序

底层过滤器要适配内容类型和编码

mod_filter 只转发，不解析。真正读取响应体、做替换或加水印的是被调度的 provider，所以 provider 自身的限制必须满足：

• 用 mod_substitute 处理 JSON？默认它只认 text/*，得加 FilterProtocol substitute change= 并确保 FilterProvider 匹配 application/json
• 用 mod_ext_filter 加水印？静态图片默认走 sendfile，会绕过 filter —— 必须设 EnableSendfile Off 和 EnableMMAP Off
• 外部程序必须严格处理二进制流：从 stdin 完整读入，原样或修改后写到 stdout，不能残留输入、不能阻塞、不能额外输出（包括 stderr 中的调试信息）
• 建议脚本加超时：ExtFilterDefine myfilter timeout=5，防止单次处理拖垮整个 worker

验证是否生效的实用方法

别只看页面效果，要分层确认每一步是否真在运行：

• 用 curl -I http://your-site/api/data 检查响应头是否含预期的 Content-Type，这是 FilterProvider 匹配的前提
• 在 provider 调用的外部脚本里加一行 echo "X-Filter-Applied: yes" >&2，再配 ExtFilterOptions logStderr，看 error_log 是否出现该标记
• 对 mod_substitute 类过滤器，可在配置中加 FilterProtocol substitute debug 查看替换日志（需 LogLevel info）
• 独立测试外部程序：curl -s http://site/file.json | ./your-filter.sh > out.json，比对输入输出字节长度是否一致