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

💡 关于安装路径与源码的说明： pip install 会将可执行库安装在当前 Python 环境的 site-packages 目录中，并在系统 PATH 中注入 mock-proxy 可执行命令（它不会在您当前打开的终端目录中下载 Git 仓库）。

• 想在当前目录下快速开始？执行 mock-proxy init，会自动为您创建 ./rules/ 目录及全注释示例文件！
• 想查看 package 在系统中的实际安装路径？执行 mock-proxy info 即可打印全部路径。
• 查看随安装包提供的完整 YAML 语法手册：执行 mock-proxy docs yaml。
• 在源码仓库中阅读手册：Mock 规则编写完全指南 (YAML Specification)。

Python 模块源码也会安装到虚拟环境的 site-packages/server/ 和 site-packages/client/ 下。查看路径可运行 mock-proxy info；查看文件清单可运行 python -m pip show -f mock-proxy。如需在当前目录获得整个可修改的 Git 工程，请克隆源码仓库，而不是运行 pip install。

安装完成后，系统将自带 mock-proxy 统一命令行工具（同时保留 mock-proxy-server 与 mock-proxy-agent 别名）：

1. 快速初始化与环境诊断

# 在当前目录下生成 rules/ 目录与全注释 sample_rule.yaml 模板
mock-proxy init

# 查看当前环境、解释器与 package 源码实际安装路径
mock-proxy info

2. 本地 YAML 规则管理 (文件优先 File-First & 面向 AI Agent)

# 查看详细参数说明与 AI 实战调用示例
mock-proxy rule create -h

# 一键创建 Mock 500 规则 (支持自动转换为纯净 YAML 字典，免转义)
mock-proxy rule create --host 192.168.1.1:88 --path /v1/trade --status 500 --body '{"code": -1, "msg": "扣款失败"}'

# 创建带 Cookie 和自定义响应头的 200 规则
mock-proxy rule create --host 192.168.1.1:88 --path /v1/auth/login --status 200 --cookie "session_id=sess_123; Path=/; HttpOnly" --body '{"token": "jwt_xxx"}'

# 查看与删除本地规则 (毫秒级自动热重载，无需重启服务)
mock-proxy rule list
mock-proxy rule delete <规则名或文件名>

3. 业务机器免装客户端接入 (Agentless SSH / 纯 Shell 脚本)

针对业务机器无需安装任何 Python 进程，通过原生标准方式劫持与还原：

# 方式 A (SSH 远程一键装卸):
mock-proxy remote attach --ssh root@业务机器IP --target 192.168.1.1:88
mock-proxy remote detach --ssh root@业务机器IP

# 方式 B (生成原生 5 行 Bash 脚本直接复制执行):
mock-proxy script generate --target 192.168.1.1:88

4. 一键启动服务端 (单进程同时开启 HTTP 8000 + HTTPS 8443 + iptables 8888 双栈)

mock-proxy server
# 或 mock-proxy-server

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

1. 启动 Mock Proxy 服务端

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

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

# 使用 uv 一键启动双栈服务端 (同时监听 HTTP 8000 和 HTTPS 8443)
uv run python -m server.cli

• Web UI 管理后台：浏览器访问 http://<服务器IP>:8000 或 https://<服务器IP>:8443
• 代理端口（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

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

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