APISIX proxy-mirror 流量镜像实践：灰度验证、监控分析与注意事项
APISIX 的 proxy-mirror 插件可以将真实请求复制一份发送到镜像服务，用于灰度验证、旁路分析、兼容性测试和流量观测。镜像请求不会影响原请求的正常响应，镜像服务返回的响应会被忽略。
这篇文章整理 proxy-mirror 的使用方式、配置参数、验证流程和生产注意事项。
相关系列文章：
适用场景
流量镜像适合：
- 新版本服务上线前，用真实流量进行旁路验证。
- 将部分请求复制到分析系统，做 API 监控和行为分析。
- 验证重构服务与旧服务的兼容性。
- 对接口请求进行离线审计或压测评估。
- 灰度前观察新系统处理真实请求的能力。
不适合：
- 需要把镜像服务响应返回给客户端的场景。
- 会产生副作用的写接口直接镜像到真实环境。
- 未做脱敏的数据流向不受控分析系统。
工作原理
请求流程可以理解为：
Client
│
▼
APISIX Route
│
├── 正常请求 -> 原上游服务 -> 响应客户端
│
└── 镜像请求 -> 镜像服务 -> 响应被忽略
关键点：
- 原请求仍按正常路由转发。
- 镜像请求是额外复制出来的请求。
- 镜像服务响应不会返回给客户端。
- 可以通过采样率控制镜像流量比例。
原验证目标示意图：
环境准备
示例：
- 默认上游地址：
10.249.0.121:31370 - 镜像上游地址：
10.249.0.121:31379
验证前建议：
- 确认 APISIX 能访问镜像服务。
- 镜像服务最好与生产写库隔离。
- 对写请求做好幂等或禁写处理。
- 镜像服务日志要能区分镜像流量。
Dashboard 配置方式
在 APISIX Dashboard 中进入目标 Route 的插件配置，找到 proxy-mirror 插件并启用。
常见参数：
| 参数 | 说明 |
|---|---|
host |
镜像服务地址，需要包含 http 或 https scheme |
path |
镜像请求路径；不指定时通常使用当前请求路径 |
sample_ratio |
镜像采样率，范围以官方文档为准 |
示例配置：
{
"host": "http://10.249.0.121:31379",
"sample_ratio": 1
}
sample_ratio=1 表示全部镜像。生产环境建议从较小比例开始，例如 0.01 或 0.05，观察镜像服务压力后再逐步调整。
提交后可以观察镜像服务日志：
Admin API 配置方式
通过 Admin API 为路由配置 proxy-mirror：
curl -i "http://127.0.0.1:9180/apisix/admin/routes/mirror-demo" \
-H "X-API-KEY: your-admin-key" \
-X PUT \
-d '{
"uri": "/store/v1/*",
"plugins": {
"proxy-mirror": {
"host": "http://10.249.0.121:31379",
"sample_ratio": 0.1
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"10.249.0.121:31370": 1
}
}
}'
验证：
curl -i "http://127.0.0.1:9080/store/v1/orders"
然后分别观察：
- 原上游是否正常返回。
- 镜像上游是否收到请求。
- 客户端响应是否仍来自原上游。
关闭流量镜像
Dashboard 中可以直接关闭插件启用状态。
Admin API 中可以删除或更新路由插件配置。
建议在生产环境中记录：
- 启用时间。
- 启用接口。
- 镜像目标。
- 采样比例。
- 关闭时间。
- 观察结论。
生产注意事项
1. 镜像请求可能产生副作用
如果镜像的是 POST、PUT、DELETE 请求，而镜像服务连接真实数据库，就可能造成重复写入、重复扣减、重复通知等严重问题。
建议：
- 镜像服务使用隔离数据库。
- 对写操作做禁写或 dry-run。
- 对外部通知、支付、库存等副作用操作做屏蔽。
2. 控制采样率
不要一开始就全量镜像。建议：
1% -> 5% -> 10% -> 50% -> 100%
每一步观察：
- 镜像服务 CPU / 内存。
- 请求耗时。
- 错误率。
- 日志写入压力。
- 下游依赖压力。
3. 注意数据安全
镜像流量可能包含：
- Token。
- Cookie。
- 手机号。
- 身份证。
- 地址。
- 订单和支付信息。
如果镜像到分析系统或测试环境，需要做脱敏、权限控制和数据留存治理。
4. 镜像响应被忽略
proxy-mirror 的核心特性是镜像响应不会影响客户端。这既是优点，也是限制：
- 适合旁路验证。
- 不适合动态选择响应。
- 不适合直接做蓝绿切流。
如果需要按比例把真实响应返回给用户，应评估 traffic-split 等流量切分方案。
常见问题
1. 镜像服务没有收到请求
检查：
- 插件是否启用。
- 当前请求是否命中目标 Route。
host是否包含http://或https://。- APISIX 到镜像服务网络是否连通。
sample_ratio是否过低导致暂时未命中。
2. 客户端响应变慢
理论上镜像请求不应该显著影响主链路，但如果插件处理、网络或资源出现瓶颈，仍可能间接影响网关。
检查：
- APISIX 节点资源。
- 镜像服务是否响应很慢。
- 是否全量镜像大流量接口。
- 网关日志是否有异常。
3. 镜像服务数据异常
检查：
- 是否镜像了写接口。
- 是否连接了真实数据库。
- 是否重复消费消息或调用第三方接口。
- 是否缺少 dry-run 控制。
总结
APISIX proxy-mirror 插件非常适合做旁路验证和流量分析，但生产使用时要特别关注副作用、采样率、数据安全和隔离。简单来说：
- 读接口更适合镜像。
- 写接口必须谨慎处理副作用。
- 从小流量采样开始。
- 镜像服务响应不会返回客户端。
- 如需真实切流，应考虑 traffic-split 等方案。