Mock Proxy Service (Mock 代理服务)

一个用于在开发测试过程中拦截第三方/外部 HTTP 接口并模拟返回定制数据的全功能 Mock 代理服务。

解决痛点：业务应用（如工程 A）调用了外部接口 http://xxx.com/test，代码中针对此接口报错编写了 catch 容错/降级逻辑，但在实际联调测试时外部接口极少报错。借助本服务，可以在完全不改动业务代码、不污染业务网络配置的前提下，通过客户端 Linux iptables 安全劫持与服务端规则引擎模拟 500、502、超时或异常响应，并提供现代化的 Web UI 监控看板与 AI Agent Skill 赋能。

🌟 核心特性

• 无侵入透明劫持：客户端 Agent 自动在 Linux 本机 iptables 中创建隔离的 MOCK_PROXY_OUTPUT 专有链，精准 DNAT 劫持目标域名/IP 到服务端。

• 全生命周期安全保障 (Safe Teardown)：

  • 客户端严格向下兼容 Python 3.6+，便于在各类旧版服务器（CentOS 7、Ubuntu 18.04 等）上直接运行。
  • 自动监听退出信号（Ctrl+C / SIGTERM / atexit），进程终止时100% 自动还原与清理 iptables 规则。
  • 提供独立急救清理命令：python -m client.agent clean。

• 高级多维规则引擎与精准 IP 绑定：

  • 支持 Host 通配符（如 *.partner.com）、Path 精确/前缀/正则表达式（如 ^/api/v1/.*$）、HTTP Method、Query 参数与 Body 匹配。
  • 基于来源 IP 精准绑定与隔离：约定单机单 IP 对应单个服务。规则支持绑定具体生效的机器 IP（在线 Agent 直接下拉勾选，未安装 Agent 的机器手动键入 IP 回车添加），支持 * 通配符代表所有 IP 全局生效。
  • 规则一键复制 (Clone Rule)：规则列表提供【复制】按钮，一键克隆已配置规则并微调，极大提升测试用例配置效率。
  • 支持静态响应（自定义状态码如 500/502/400、自定义响应头、响应延迟模拟、JSON/文本）。
  • 支持Python 沙箱动态脚本（可模拟概率性抛错、基于请求参数动态计算响应内容）。

• 未命中真实透传 (Passthrough)：未匹配任何 Mock 规则的请求原样转发至真实外部接口，返回真实响应。

• 现代化 Web UI 管理后台 (Vue 3 + Element Plus)：

  • Mock 规则管理：在线配置、规则开关、优先级调整、动态脚本语法高亮与测试。
  • 拦截目标配置：添加/移除需劫持的外部域名，变更实时推送给所有在线客户端 Agent。
  • 实时抓包控制台 (Live Traffic Inspector)：类似 Charles/Fiddler 的实时流量流，支持请求头/体对比，以及**“一键从流量生成 Mock 规则”**。
  • 客户端节点状态：实时观察在线 Agent 节点与心跳。

• AI Agent Skill 深度集成：内置 skills/mock-proxy/SKILL.md，可供 OpenCode、Claude 及其他 AI 辅助编程 Agent 直接调用，实现“自动配 Mock -> 触发测试 -> 审查抓包 -> 清理还原”的自动化闭环！

📂 项目目录结构

mock-proxy/
├── server/                     # 服务端核心
│   ├── app.py                  # FastAPI 主服务（集成 REST、WebSocket、静态托管）
│   ├── config.py               # 服务端配置 (端口、数据目录)
│   ├── proxy/                  # 代理引擎模块
│   │   ├── engine.py           # 代理处理与生命周期分发
│   │   ├── matcher.py          # 多维规则匹配引擎
│   │   ├── executor.py         # 动态 Python 脚本沙箱执行器
│   │   └── passthrough.py      # 真实上游透传客户端
│   ├── hub/                    # 管控中心模块
│   │   ├── database.py         # SQLite 异步存储
│   │   ├── ws_manager.py       # WebSocket 广播管理 (Agent & Web UI)
│   │   └── routers/            # REST API 路由 (rules, targets, traffic, agents, skills)
│   └── static/                 # Vue 3 前端生产构建产物
├── client/                     # 客户端 Agent (Python 3.6+ 严格向下兼容)
│   ├── agent.py                # Agent 守护进程命令行入口
│   ├── iptables.py             # Linux iptables 隔离链与安全清理
│   ├── dns_watcher.py          # 动态 DNS 解析监控
│   └── ws_client.py            # WebSocket 策略同步客户端
├── skills/                     # AI Agent Skill 技能定义
│   └── mock-proxy/
│       └── SKILL.md            # 提供给 OpenCode / AI Agent 调用的技能说明与脚本
├── web/                        # Vue 3 + Element Plus 前端工程源码
└── tests/                      # 自动化测试套件 (全量覆盖)

📦 安装方式 (PyPI)

pip install mock-proxy

安装完成后，系统将自带 mock-proxy-server 与 mock-proxy-agent 两个开箱即用的命令行工具：

• 启动服务端 (HTTP 模式)：mock-proxy-server --port 8000 --proxy-port 8888
• 启动服务端 (HTTPS 原生加密模式)：
  • 一键自签证书启动：mock-proxy-server --port 8443 --ssl-auto
  • 使用已有证书启动：mock-proxy-server --port 8443 --ssl-cert cert.pem --ssl-key key.pem
• 启动客户端：sudo mock-proxy-agent run --server <服务端IP> --service <服务名>
• 急救清理：sudo mock-proxy-agent clean

🚀 快速启动指南 (源码开发)

1. 启动 Mock Proxy 服务端

依赖环境：Python 3.10+、uv（或 pip）

# 进入项目目录
cd /home/coder/project/mock-proxy

# 使用 uv 同步安装依赖并启动服务
uv run uvicorn server.app:app --host 0.0.0.0 --port 8000

• Web UI 管理后台：打开浏览器访问 http://<服务器IP>:8000
• 代理端口（Proxy Engine）：监听 0.0.0.0:8888

2. 启动客户端 Agent（业务应用所在机器）

依赖环境：Linux 宿主机、Python 3.6+（需 sudo 权限配置 iptables）

# 启动常驻守护进程（连接服务端同步目标并管理 iptables，可通过 --service 标识所属业务服务/环境）
sudo python3 -m client.agent run --server <服务端IP> --hub-port 8000 --proxy-port 8888 --service order-service-dev

# 若在本地测试或无 root 权限环境演练，可附加 --dry-run 模式：
python3 -m client.agent run --server 127.0.0.1 --service order-service-dev --dry-run

急救清理与状态查看

如果 Agent 意外被强杀导致网络拦截未解除，可随时执行独立急救命令：

# 一键检测并安全清除所有 MOCK_PROXY_* iptables 规则链
sudo python3 -m client.agent clean

# 查看当前 iptables 生效规则
sudo python3 -m client.agent status

🧪 典型测试场景演示：模拟第三方接口 500 异常

假设工程 A 代码中有如下逻辑：

try:
    resp = requests.get("http://xxx.com/test", timeout=3)
    resp.raise_for_status()
    data = resp.json()
except requests.exceptions.RequestException as e:
    # 这是我们要重点验证的容错捕获逻辑
    logger.error("第三方接口异常，执行本地降级策略")
    return fallback_data()

验证步骤：

1. 添加拦截目标： 在 Web 界面【拦截目标配置】中，添加域名 xxx.com（端口 80）。此时客户端 Agent 会自动将发往 xxx.com:80 的流量劫持转发到 Mock 服务端。
2. 配置 Mock 规则： 在 Web 界面【Mock 规则管理】中新建规则：
   • 目标 Host：xxx.com
   • 请求路径：/test
   • 状态码：500
   • 响应体：{"code": "ERR_REMOTE", "message": "Third party unavailable"}
3. 触发业务请求： 运行工程 A，工程 A 发起请求 http://xxx.com/test，直接收到 Mock 返回的 500 错误。
4. 实时观测与验证：
   • 查看工程 A 控制台，确认 catch 异常处理逻辑被成功触发并执行降级！
   • 打开 Web 界面【实时流量监控】，可清晰看到该次调用的时间、Method、URL、匹配的规则名称及返回结果。

🌐 前缀代理网关模式（同时支持 HTTP 与 HTTPS，零 root 门槛与免根证书）

对于任何外部接口（无论是 HTTP 还是 HTTPS），如果业务运行在无 root 权限环境（如容器、开发机），或者不想配置系统根证书，可直接将接口 Base URL 加上前缀网关：

• 外部真实接口：https://api.partner.com/v1/pay/create?id=123 或 http://xxx.com/test
• 业务工程配置 (标准 HTTPS 访问)：https://<mock-proxy>:8443/proxy/api.partner.com/v1/pay/create?id=123
• 业务工程配置 (标准 HTTP 访问)：http://<mock-proxy>:8000/proxy/xxx.com/test

特性支持：

• 协议智能自适应推导：
  • 访问 http://.../proxy/xxx.com/...，透传时自动走上游 http://；
  • 访问 https://.../proxy/api.partner.com/...，透传时自动走上游 https://；
  • 带端口（如 :80 或 :443）自动推断，支持 X-Target-Scheme 标头显式指定。
• 原生支持纯正 HTTPS 访问：通过 mock-proxy-server --ssl-auto 开启 8443 端口原生 TLS 监听，业务端发出的就是真正的 HTTPS 请求，完美适配各类强制校验 https:// 的现代 SDK 与安全框架！
• 完整支持所有方法：支持 POST、GET、PUT、DELETE、PATCH。
• POST Body 完整透传：支持 JSON、表单数据及二进制流。
• 统一规则匹配：Web UI 中配置的目标 Host api.partner.com、Path /v1/pay/create 规则对前缀网关完全通用。
• 未命中真实上游透传：未命中 Mock 时，代理服务端使用对应协议与 TLS SNI 向上游发起真实请求，并原样返回结果。

🤖 AI Agent 调用说明 (OpenCode / LLM Skill)

本系统原生支持被 AI Agent 动态调用。AI 智能体可读取 skills/mock-proxy/SKILL.md，或者通过服务端接口获取调用定义：

# 获取技能说明文档
curl http://localhost:8000/api/agent-skills/SKILL.md

# 获取标准函数调用 Schema
curl http://localhost:8000/api/agent-skills/tools

AI 智能体在自动排查或编写降级逻辑时，可以直接发起 HTTP 请求配置 Mock 规则进行自闭环测试验证。

🧪 运行自动化测试

uv run pytest -v

所有 31 项测试（包含配置、HTTP/HTTPS 透传、TLS 证书自动生成、真实 TLS 握手、协议自适应、多维规则引擎、脚本沙箱、来源 IP 精准匹配、前缀网关、iptables 链构建、REST API 及端到端闭环）均全量通过。

完整的 Web UI 操作步骤与浏览器测试记录见：docs/manual/web-ui-usage.md。