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。

• 高级多维规则引擎与多服务分派：

  • 支持 Host 通配符（如 *.partner.com）、Path 精确/前缀/正则表达式（如 ^/api/v1/.*$）、HTTP Method、Query 参数与 Body 匹配。
  • 支持按服务/代理分派生效：每条规则可指定生效的一个或多个具体服务（如 order-service-dev、payment-uat 或全局通用 *），避免多服务/多环境测试相互干扰。
  • 支持静态响应（自定义状态码如 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/                      # 自动化测试套件 (全量覆盖)

🚀 快速启动指南

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、匹配的规则名称及返回结果。

🤖 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

所有 21 项测试（包含配置、代理转发、多维规则引擎、脚本沙箱、服务分派隔离、iptables 链构建、REST API 及端到端闭环）均全量通过。

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