mitmproxy 部署指南：开源 HTTPS 抓包与中间人代理工具详解
一、项目介绍
mitmproxy 是一款开源的交互式中间人代理（Man-in-the-Middle Proxy）工具，支持 HTTP/1、HTTP/2 与 WebSocket 协议，并且原生具备 SSL/TLS 解密能力。它由三个核心组件组成：mitmproxy 本身提供基于终端的交互式控制台界面，mitmdump 是命令行版本，类似于"HTTP 世界的 tcpdump"，而 mitmweb 则是基于浏览器的 Web 图形界面。项目以 Python 编写，在 GitHub 上拥有超过三万八千颗 Star，是安全测试、移动 App 抓包、爬虫开发与后端接口联调领域事实上的标准工具之一。
与传统的 Charles、Fiddler 等商业抓包工具相比，mitmproxy 完全免费、开源、跨平台，并且支持通过 Python 脚本对流量进行可编程式拦截、修改与重放。无论是调试手机 App 与后端的通信协议、分析 Web 应用的 API 调用，还是对爬虫请求进行伪装与签名调试，mitmproxy 都能提供统一而强大的工作台。它的设计哲学是"把代理本身做成一个可编程的事件总线"：每一个 HTTP 会话在经过 mitmproxy 时都会被抽象成一个 flow 对象，插件可以在请求发出前、响应到达后等任意节点介入，从而实现 Mock、重写、录制、回放等高级能力。官方文档位于 docs.mitmproxy.org，源码仓库托管在 github.com/mitmproxy/mitmproxy。
除了基本的抓包功能，mitmproxy 还内置了反向代理模式、上游代理转发、流量录制回放、URL 替换、证书生成等常用能力。它被广泛应用于安全研究人员分析恶意软件通信、移动开发者调试前后端接口、运维人员排查线上网关问题，以及爬虫工程师模拟真实浏览器指纹等场景。对于希望摆脱付费软件限制、又需要可扩展抓包能力的团队来说，mitmproxy 是首选方案。
在实际工作流中，mitmproxy 通常承担三类角色：第一是调试辅助角色，开发人员通过它观察前后端真实报文，定位字段缺失、签名错误、缓存策略等问题；第二是测试替身角色，测试人员把录制好的接口流量作为 Mock 数据喂给前端，实现脱离后端的独立测试；第三是安全审计角色，红队与应急响应人员用它复盘可疑请求，发现隐藏的 C2 通道或数据外传行为。这三类场景共用同一套安装包，差别仅在启动参数与插件脚本。
二、项目结构与核心组件
mitmproxy 仓库的核心目录结构清晰，便于二次开发与扩展。mitmproxy 包本身实现了代理核心逻辑，包括流量捕获、TLS 握手、上游连接管理；mitmdump 负责命令行输出与脚本加载；mitmweb 是基于 Flask + Vue 的 Web 前端；addons 目录则内置了大量官方插件，例如文件保存、代理反转、流量重放、脚本注入、导出 HAR、过滤规则等；examples 目录提供了数十个可直接运行的插件示例，覆盖请求修改、响应 Mock、证书劫持、流式处理等典型场景。
从运行时角度看，mitmproxy 由四层构成：最底层是异步事件循环（基于 asyncio），负责管理成千上万的并发连接，单机可轻松承载数万长连接；其上是协议解析层，依次处理 HTTP/1、HTTP/2、WebSocket、TLS、QUIC 预览等协议；再往上是拦截与钩子层，允许插件在请求/响应的任意节点介入，钩子函数命名清晰，例如 request、response、error、websocket_start、tls_start；最上层是用户界面，包括 TUI、CLI 与 WebUI 三种形态。安装后系统会同时注册 mitmproxy、mitmdump、mitmweb 三个可执行命令，它们共享同一套核心库，只是入口界面不同，配置文件统一存放在 ~/.mitmproxy/ 目录下，包括自动生成的根证书 ca.crt、ca.key 以及配置文件。
插件系统是 mitmproxy 区别于其他抓包工具的灵魂。任何一个带有请求或响应方法的 Python 类都可以作为插件加载，通过 mitmdump -s myaddon.py 启用。社区围绕这套 API 构建了丰富的第三方插件生态，例如自动注入 Cookie、批量替换接口返回值、录制流量用于单元测试、把抓包结果推送到 ELK 等。
值得一提的是，mitmproxy 支持同时加载多个插件，它们按照加载顺序组成责任链，后一个插件看到的 flow 可能已经被前一个插件修改过。这种设计让复杂场景可以拆分成多个小脚本，例如一个插件负责统一添加鉴权头，另一个插件负责记录耗时，第三个插件负责错误重试，互不干扰又协同工作。
三、版本与环境要求
当前主线版本为 mitmproxy 11.x，要求 Python 3.10 及以上版本。官方提供的预编译二进制已经内嵌了 Python 运行时，因此在 Windows、macOS、Linux 上下载后即可直接运行，无需额外安装 Python。如果选择通过 pip 安装，则需要本地自行准备 3.10+ 的 Python 解释器，并建议使用虚拟环境隔离依赖，避免污染系统 Python。
操作系统层面，Windows 10/11、macOS 12 及以上、主流 Linux 发行版（Ubuntu 20.04+、Debian 11+、Fedora 38+、CentOS Stream 9）均可运行。端口方面，mitmproxy 默认监听 8080（HTTP 代理），mitmweb 默认监听 8081（Web 界面），使用前请确保防火墙与本地安全软件放行对应端口。若要抓 HTTPS 流量，必须在被抓包设备上手动信任 mitmproxy 自动生成的根证书，否则会出现证书错误或连接被重置。
硬件要求极低，普通笔记本即可流畅运行；但如果需要同时抓上千路并发连接，建议预留至少 2GB 内存，并把日志输出重定向到文件以避免终端卡顿。磁盘方面，长时间抓包会产生大量 flow 文件，建议提前规划存储目录，使用 --save-stream-file 做流式落盘。
四、本地部署
方式一：官方预编译二进制（推荐新手）
前往 mitmproxy.org/downloads 下载对应平台的压缩包。Linux 与 macOS 用户下载 mitmproxy-XX.X.x-linux.tar.gz 或 .macos.tar.gz，解压后直接执行：
tar xzf mitmproxy-*-linux.tar.gz
./mitmproxy --version
./mitmproxy -p 8080Windows 用户下载 mitmproxy-XX.X.x-windows-x86_64.zip，解压后在 PowerShell 中运行 .\mitmproxy.exe。建议将解压目录加入系统 PATH，以便在任意目录调用。首次启动会自动在 ~/.mitmproxy/ 下生成根证书，该过程只需数秒。
方式二：pip 安装（适合开发者）
在已安装 Python 3.10+ 的环境中执行：
python -m venv ~/mitmenv
source ~/mitmenv/bin/activate # Windows 下为 ~~\mitmenv\Scripts\activate
pip install --upgrade pip
pip install mitmproxy安装完成后即可使用 mitmproxy、mitmdump、mitmweb 三条命令。macOS 用户若提示 ncurses 相关错误，可通过 brew install ncurses 解决；Ubuntu 用户若报 Python 头文件错误，请先 sudo apt install python3-dev。
方式三：系统包管理器
macOS 用户可直接使用 Homebrew：brew install mitmproxy，版本跟随官方更新。Debian/Ubuntu 用户可使用 apt install mitmproxy，但仓库版本可能略旧。Arch Linux 用户通过 pacman -S mitmproxy 安装，滚动更新及时。Windows 用户也可以通过 Scoop：scoop install mitmproxy，自动处理 PATH。
方式四：Docker 部署（适合服务器端长期运行）
官方提供 Docker 镜像，一行命令即可启动：
docker run --rm -it -p 8080:8080 -p 8081:8081 \
mitmproxy/mitmproxy:latest mitmweb --web-host 0.0.0.0如需持久化保存抓包文件与证书，可挂载数据卷：-v $PWD/mitm-data:/home/mitmproxy/.mitmproxy。生产环境建议用 systemd 或 docker-compose 托管，并把日志重定向到 stdout 以便采集。
方式五：源码编译（适合贡献者）
git clone https://github.com/mitmproxy/mitmproxy.git
cd mitmproxy
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e .
mitmproxy --version源码模式下可以直接修改核心代码并立即生效，便于调试协议解析或开发自定义插件。运行测试使用 pytest test/。
五、浏览器端部署与可视化管理
mitmproxy 的 Web 界面 mitmweb 是最适合日常调试的形态。启动方式为：mitmweb --listen-port 8080 --web-port 8081 --web-host 0.0.0.0。启动后控制台会输出一行类似 Web server listening at http://127.0.0.1:8081 的提示，在浏览器打开该地址即可看到完整的流量列表。界面左侧是会话树，按域名分组；中间是请求/响应详情，支持 Headers、Hex、JSON、Cookies 多视图切换；右侧是命令与插件面板，可实时启用或停用插件、设置过滤表达式。
将手机或浏览器代理指向运行 mitmproxy 的机器 IP 与 8080 端口后，所有流量都会实时出现在 WebUI 中。首次抓 HTTPS 时，在被抓包设备浏览器访问 http://mitm.it，页面会自动识别操作系统并提供根证书下载。macOS 双击证书后需要在"钥匙串访问"中将其信任级别改为"始终信任"；Windows 选择"安装证书→本地计算机→受信任的根证书颁发机构"；Android 7+ 由于安全策略默认不信任用户证书，需要在 App 中配置 network_security_config 或将 mitmproxy 证书安装为系统证书（需要 Root 权限）；iOS 则在描述文件安装后，还需进入"设置→通用→关于本机→证书信任设置"中手动开启信任开关。
除了 WebUI，mitmproxy 的 TUI（终端界面）同样强大：上下方向键切换会话，回车查看详情，q 返回，z 清空列表，f 设置过滤表达式（例如 ~d api.example.com 只看该域名），m 拦截请求后可手动修改再放行。熟练使用 TUI 后，调试速度往往比鼠标操作 WebUI 更快。
六、API 用法
mitmproxy 本身既是代理也是可编程的流量处理框架。最常见的用法是通过 mitmdump 加载 Python 插件脚本，对流量进行自动化处理。下面这段脚本会拦截所有发往 api.example.com 的请求，并打印方法与用户代理：
# save_user_agent.py
from mitmproxy import http
def request(flow: http.HTTPFlow) -> None:
if "api.example.com" in flow.request.pretty_host:
print(flow.request.method, flow.request.pretty_url)
print("UA:", flow.request.headers.get("user-agent"))
flow.request.headers["X-Debug"] = "mitmproxy"
# 启动
mitmdump -s save_user_agent.py -p 8080插件中可直接读写 flow.request 与 flow.response，实现请求重写、响应 Mock、断点调试等功能。例如要把某个接口的返回值改成固定 JSON，只需在 response 钩子里替换 flow.response.text。若希望以 HTTP 接口方式远程控制 mitmproxy，可使用内置的 Web 接口，或基于 事件 API 自行封装 RPC。
下面是一段用 curl 让请求经过 mitmproxy 代理后访问示例接口的命令：
curl -x http://127.0.0.1:8080 https://httpbin.org/get -k此时该请求会出现在 mitmproxy 会话列表中，可在 WebUI 中右键选择"Replay"重放，或使用 mitmdump -nr flow.mitm 加载录制好的 flow 文件进行回放。批量压测时可以结合 --rerun 参数把录制的流量按时间间隔反复发送，用于接口回归测试。
七、常见问题 FAQ
Q1：抓 HTTPS 时浏览器提示 ERR_CERT_AUTH 或 NET::ERR_CERT_AUTHORITY_INVALID，怎么办？
A：说明根证书未被系统信任。请确认已从 http://mitm.it 下载对应平台证书，并正确导入到"受信任的根证书颁发机构"。macOS 还需在钥匙串中手动展开证书条目，将"信任"改为"始终信任"；iOS 必须额外到证书信任设置中打开开关。
Q2：手机配置代理后无法联网？
A：检查三点：手机与电脑是否在同一局域网；电脑防火墙是否放行 8080 端口；mitmproxy 启动时是否绑定了 0.0.0.0 而不是 127.0.0.1。可在电脑上用 ipconfig（Windows）或 ifconfig（macOS/Linux）查看局域网 IP，手机 Wi-Fi 高级设置里代理主机名填该 IP，端口填 8080。
Q3：Android 7+ 抓不到 App 流量？
A：Android 7 起 App 默认只信任系统证书。解决方案有三种：将 mitmproxy 证书通过 Root 或 Magisk 模块安装为系统证书；在 App 源码中配置 network_security_config 信任用户证书；或使用 Frida/Xposed 插件绕过 SSL Pinning。对第三方 App 抓包还需先脱壳，否则加固后的流量无法解析。
Q4：启动时提示 "Address already in use" 或端口被占用？
A：说明 8080 端口被其他程序占用。使用 lsof -i:8080（macOS/Linux）或 netstat -ano | findstr :8080（Windows）找到占用进程并结束，或改用 mitmproxy -p 8888 指定其他空闲端口，同时记得同步修改客户端代理配置。
Q5：mitmweb 启动后浏览器打不开界面？
A：默认 mitmweb 只监听 127.0.0.1，远程访问必须加 --web-host 0.0.0.0，并确认服务器安全组放行 8081 端口。建议在公网环境加上 --web-auth user:pass 做基本认证，避免管理面板被任意访问。
Q6：抓 WebSocket 或 HTTP/2 时数据乱码？
A：mitmproxy 默认已支持 HTTP/2 与 WebSocket。若看到二进制乱码，多半是 gzip 或 br 压缩未自动解压，可在插件中调用 flow.response.decode()，或在 WebUI 中勾选"Decode body"。某些 App 使用了自定义 TLS 扩展，需要在插件中关闭对应的 ALPN 协商。
Q7：如何把 mitmproxy 当作正向代理长期跑在服务器上？
A：推荐使用 Docker 启动并配合 systemd 守护，启动参数加上 --set block_global=false 避免误拦截本地回环，再通过 --allow-hosts 与 --ignore-hosts 白名单过滤流量。同时配置 ~/.mitmproxy/config.yaml 固化常用选项，例如默认上游代理、上游认证、日志级别等，避免每次手动敲参数。
Q8：抓包文件体积太大，如何瘦身？
A：使用 --read-flows 配合过滤表达式只保留需要的会话，例如 ~d api.example.com。也可以在插件中通过 flow.kill() 主动丢弃不需要的请求，或使用 --set save_stream_file=output.mitm 做流式落盘后再用 mitmdump -nr output.mitm -w cleaned.mitm '~d api' 二次裁剪。
相关链接： mitmproxy 官网 · 官方文档 · GitHub 仓库 · PyPI 页面 · Docker 镜像