mitmproxy 配置参数详解

mitmproxy 12.3.1 配置体系实测详解：options 四种修改方式与优先级、60 余参数分组语义、modify_headers/anticache/anticomp 无插件改写实测、mitmweb 认证参数与 4GB 内存生产配置模板。

mitmproxymitmproxy抓包调试网络2026/10/27

mitmproxy 配置参数详解

目标：讲清 mitmproxy 12.3.1 的配置体系——options 机制的四种查看与修改方式、60 余个参数的分组语义、无需写插件的流量改写参数（modify_headers/modify_body/map_remote 等），并给出可落地的生产配置模板。所有参数行为与回显均在 Ubuntu 22.04 服务器实测验证。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS（内核 7.0.0-38-generic，x86_64）
  • mitmproxy：12.3.1 binary（官方二进制包安装，自带 Python 3.15.1 / OpenSSL 4.0.3；安装过程见《mitmproxy 安装与初始化实战》）
  • 配置目录：/root/.mitmproxy/（confdir 默认值）
  • 实测端口：8080（systemd 常驻）、8090（config.yaml 驱动）、8086（options 改写实验）
  • 验证目标：本机 python3 -m http.server 8000 测试站与外网 https://httpbin.org/get（响应 JSON 回显请求头，用于验证改写是否到达服务器）
  • options 清单取证：mitmdump --options 全量输出 442 行（2026-10-27 实测），下文分组均出自该输出

二、前置条件

按《mitmproxy 安装与初始化实战》完成安装、mitmproxy --version 确认为 12.3.1、CA 已被客户端信任。本篇还用到 systemd 常驻实例（mitmdump.service，8080 端口）与前台临时实例做对照实验，建议先通读安装篇第九节。

三、参数查看与修改方式

mitmproxy 的所有行为开关都叫 option（选项），统一存放于 options 存储，有四种等价的查看/修改途径：

3.1 查看全量参数：--options

mitmdump --options | head -12

实测回显（节选）：


# Add all certificates of the upstream server to the certificate chain
# that will be served to the proxy client, as extras. Type bool.
add_upstream_certs_to_client_chain: false

# Opposite of --ignore-hosts. Type sequence of str.
allow_hosts: []

# Strip out request headers that might cause the server to return
# 304-not-modified. Type bool.
anticache: false

输出格式是「注释（说明 + 类型）+ 参数名: 默认值」逐项排列，是离线查参数语义最快的手册——比官网文档更贴近当前二进制实际支持的选项。

3.2 命令行参数与 --set

短参数（-p、-s、-w 等交互常用）与长参数（--listen-port）是部分 option 的便捷别名；对没有专属命令行别名的 option，用 --set 通用写法：

mitmdump --listen-port 8080                      # 长参数形式
mitmdump --set listen_port=8080                  # 等价的 --set 形式
mitmdump --set anticache=true --set flow_detail=2

序列型 option（sequence of str）在 --set 里用 JSON 数组或按条重复传参，如 --set modify_headers='/~q/X-A/1'。

3.3 配置文件 ~/.mitmproxy/config.yaml

mitmproxy 启动时自动读取 ~/.mitmproxy/config.yaml（路径由 confdir option 决定），把常用参数持久化。实测：写入以下内容后无参数启动：

# /root/.mitmproxy/config.yaml
listen_host: 0.0.0.0
listen_port: 8090
anticache: true

mitmdump

实测回显：

[07:23:42.102] HTTP(S) proxy listening at *:8090.

监听端口 8090 生效，证明配置文件被读取。

3.4 优先级：命令行 > config.yaml

同一参数同时出现在配置文件与命令行时的裁决，实测说话——保留 3.3 的 listen_port: 8090，显式指定端口启动：

mitmdump --listen-port 8080

实测确认监听的是 8080（经该端口代理请求返回 port 8080: HTTP 200），即命令行参数覆盖配置文件。排障时若发现"参数改了没生效"，先检查 ~/.mitmproxy/config.yaml 里是否有同名项、再检查 systemd 单元里是否写死了参数。

3.5 运行时查看：TUI/Web 内置命令

mitmproxy TUI 中输入 :options 回车进入 options 交互面板，逐项可改；mitmweb 在 Web 界面 Options 页提供同等能力。这两个入口改的是当前进程内存中的 options，不自动写回 config.yaml（持久化需手动落盘）。

四、参数总览

以下为 12.3.1 实测 --options 输出的全部参数按用途分组（默认值照抄实测输出；web_* 组仅在 mitmweb --options 中出现）：

分组参数（默认值）一句话语义
监听与模式listen_host ('')、listen_port (8080)、server (true)、keepserving (false)、connection_strategy (eager)代理绑定的地址端口；server=false 进入纯回放模式；keepserving 让回放完成后继续监听
TLS 与证书certs ([])、key_size (2048)、ssl_insecure (false)、add_upstream_certs_to_client_chain (false)、tls_version_client_min (TLS1_2)、tls_version_client_max (UNBOUNDED)、tls_version_server_min (TLS1_2)、tls_version_server_max (UNBOUNDED)、request_client_cert (false)、strip_ech (true)动态签发与上游校验控制
流量放行与屏蔽ignore_hosts ([])、allow_hosts ([])、tcp_hosts ([])、udp_hosts ([])、block_global (true)、block_private (false)、block_list ([])、show_ignored_hosts (false)、showhost (false)、upstream_cert (true)哪些连接做中间人、哪些直通隧道、来源黑白名单
请求/响应改写modify_headers ([])、modify_body ([])、map_local ([])、map_remote ([])、keep_host_header (false)、normalize_outbound_headers (true)、validate_inbound_headers (true)、http_connect_send_host_header (true)、anticache (false)、anticomp (false)、keep_alt_svc_header (false)无需插件的就地改写矩阵
重放client_replay ([])、client_replay_concurrency (1)、server_replay ([]) 及 server_replay_* 九项、server_replay_extra (forward)客户端/服务器双向重放控制
脚本与扩展scripts ([])、command_history (true)插件加载与命令历史
输出与视图flow_detail (1)、content_view_lines_cutoff (512)、dumper_default_contentview (auto)、termlog_verbosity (info)、hardump ('')、export_preserve_original_ip (false)、proxy_debug (false)、onboarding (true)、onboarding_host (mitm.it)mitmdump 输出粒度与落盘格式
流式与大响应stream_large_bodies ('')、store_streamed_bodies (false)超大响应转流式以省内存
协议开关rawtcp (true)、websocket (true)、tcp_timeout (600)、dns_name_servers ([])、dns_use_hosts_file (true)、emudhra (false)非 HTTP 协议与扩展
Web UI（mitmweb 专属）web_host (127.0.0.1)、web_port (8081)、web_password ('')、web_debug (false)mitmweb 管理界面绑定与认证

💡 技术拓展："配置"在 mitmproxy 里有三层，别混用。第一层是 options（本篇主角，控制代理引擎行为）；第二层是插件自身的配置（插件用 configure() 回调读取 options 或自管文件）；第三层是模式定义（--mode regular|upstream|reverse|transparent|socks5，决定流量拓扑而非开关）。社区常见的 Nginx 式"一个配置文件管所有"的心智模型在这里不成立——mitmproxy 的 config.yaml 本质只是 options 的持久化载体。

五、核心参数分类详解

5.1 监听与模式参数

  • listen_host/listen_port：绑定地址与端口。默认 ''（全地址）、8080。3.3/3.4 节实测了 config.yaml 与命令行两条设定路径。
  • server: false：不启动代理监听，配合 -r 做离线 flow 处理（回读、过滤、改写、落盘），是 mitmdump -n 长参数背后的 option。
  • connection_strategy: eager：默认在看到 CONNECT/请求时就与目标建连（eager）；lazy 则推迟到确有数据转发时，可减少无效连接但对时序敏感场景有影响。
  • keepserving: false：重放/回读完成后默认退出；置 true 后继续服务，常用于 mitmdump -nC file --set keepserving=true 的"重放后继续抓"组合。

5.2 TLS 与证书参数

  • certs: []：自定义证书。序列项格式为 [主机匹配=]证书PEM路径，PEM 需完整链、叶子证书在前；指定主机走你提供的证书，其余主机仍用 CA 动态签发。实测机上默认值为空，即全部动态签发。
  • key_size: 2048：动态证书 RSA 密钥位长，安全要求高时可提至 3072/4096（代价是签发稍慢）。
  • ssl_insecure: false：置 true 后 mitmproxy 不校验上游服务器证书——抓自签名/内网 HTTPS 站点时常用，等价于插件里 --set ssl_insecure=true；官方注释明示该状态下 mitmproxy 自身可被 TLS 拦截，仅限调试环境。
  • tls_version_client_min/max、tls_version_server_min/max：四个独立旋钮分别约束"客户端↔mitmproxy"与"mitmproxy↔服务器"两段 TLS 的版本区间，默认下限 TLS1_2、上限不设限。老客户端只支持 TLS1.0 时下调 client_min（有合规风险需评估）。
  • add_upstream_certs_to_client_chain: false：把上游服务器证书链附加给客户端，便于客户端校验诊断。
  • strip_ech: true：剥离 Encrypted Client Hello 扩展——ECH 会把 SNI 加密导致 mitmproxy 无法按域名选证书，默认开启剥离以保证拦截成功率。

5.3 流量放行与屏蔽参数

  • ignore_hosts: []：匹配的连接不做中间人，直接 TCP 隧道透传（值按正则匹配 IP 或主机名）。对证书固定（SSL Pinning）的 App、或无需解密的大流量（如到数据库的 TLS），把目标加入 ignore 可避免客户端报错。
  • allow_hosts: []：ignore 的反向（官方注释 "Opposite of --ignore-hosts"）——仅对列表内主机拦截，其余全透传。
  • block_global: true：默认拒绝来自公网 IP 的连接，这是把代理暴露到公网时的防滥用护栏；实验机上显式 --set block_global=false 才接受非私网来源。生产若只监听内网网卡可保持默认。
  • block_private: false、block_list: []：分别控制私网段拒接与按正则名单拒接。
  • showhost: false：flow 列表显示原始 Host 头还是连接目标（官方注释提醒恶意 App 可伪造 Host 头，故默认关闭）。
  • upstream_cert: true：用 CONNECT 目标信息加速证书签发，减少与上游的额外往返。

5.4 请求/响应改写参数（无插件改写矩阵）

这组 option 能覆盖大部分轻量改写需求，不必写 Python 插件：

  • modify_headers: []：条目格式 /flow-filter/header-name/header-value（分隔符可任选字符），value 处用 @文件路径 可从文件读值，value 为空串则删除该头。实测：--set modify_headers="/~q/X-Injected/by-opts" 后经代理请求 https://httpbin.org/get，服务器回显的请求头里出现：
"X-Injected": "by-opts"

~q 过滤器限定只改请求侧（~a 为响应侧），不加过滤则请求与响应都改。

  • modify_body: []：同款语法作用于正文替换，如 /~u/example\.com/foo/bar 把 URL 匹配流量的 body 中 foo 换成 bar。
  • map_remote: []：把匹配流量重定向到另一上游（格式 |flow-filter|url-regex|replacement），适合把生产 API 映射到测试环境。
  • map_local: []：把匹配请求直接用本地文件应答，联调时可伪造静态资源。
  • anticache: false：实测开启后（--set anticache=true 与 modify_headers 同实例）curl 显式携带的 If-Modified-Since 头到达服务器时被剥除（httpbin 回显为 None），强制服务器返回完整 200 内容而非 304——调 API 时省去手动清缓存。
  • anticomp: false：剥离 Accept-Encoding，让服务器返回未压缩内容，mitmproxy 视图直接可读。
  • keep_host_header: false：反向代理模式下保留客户端原始 Host 头（默认改写为反向目标的主机名）。
  • normalize_outbound_headers / validate_inbound_headers：HTTP/2 伪头与大小写规范化校验，遇严格网关报头校验错误时可调。

5.5 重放参数族

  • client_replay: []：启动时即对指定 flow 文件做客户端重放（等价 -C）。
  • client_replay_concurrency: 1：重放并发度，压测场景调大。
  • server_replay: [] 与九个 server_replay_* 微调项（ignore_host/ignore_content/ignore_params/ignore_payload_params/ignore_port/kill_extra/nopop/refresh/reuse/use_headers、extra 策略 forward）：用录制的响应伺服客户端（等价 -S），微调项控制匹配口径——如 server_replay_refresh: true 默认刷新过期头。

5.6 输出与落盘参数

  • flow_detail: 1：mitmdump 输出粒度 0-3。实测同一段回读数据在 flow_detail=1 下每流一行（GET http://example.com/ << 200 OK 577b），flow_detail=3 则展开完整请求头、响应头与正文预览。
  • hardump: ''：进程退出（SIGTERM）时把会话导出为 HAR 1.2 文件。实测 --set hardump=/opt/flows/lab.har 正常退出后生成 7698 字节 HAR，creator.version 为 "12.3.1"。
  • termlog_verbosity: info：终端日志级别（debug/info/warn/error）。
  • content_view_lines_cutoff: 512：正文视图最大行数，超大 JSON/HTML 防爆屏。
  • dumper_default_contentview: auto：mitmdump 正文渲染器，auto 按内容类型探测，可显式指定 json/xml 等。
  • onboarding: true / onboarding_host: mitm.it：内置证书分发站点——客户端连上代理后浏览器访问 http://mitm.it 可直接下载各平台 CA，是给新设备装证书最省事的通道。

5.7 流式与大响应

  • stream_large_bodies: ''：超过阈值（如 3m）的响应转流式直通，避免整包进内存；理解 k/m/g 后缀。
  • store_streamed_bodies: false：官方注释说明其与 stream_large_bodies 配套——流式 body 默认不落内存/不可改，置 true 换内存换可查看性。

5.8 Web UI 参数（mitmweb 专属）

mitmweb --options 实测四个专属项：

  • web_host: 127.0.0.1：管理界面绑定地址。远程访问须改为 0.0.0.0 并自行加固（防火墙/反代认证），默认仅本机可开。
  • web_port: 8081：管理端口（注意与代理监听端口是两个独立端口）。
  • web_password: ''：为空时启动生成随机密码（打印在控制台）；实测显式设置后，访问管理界面有三种方式，回显如下（同一时刻对比）：
no-auth: HTTP 403        # 不带凭证
token-param: HTTP 200    # URL 追加 ?token=q1w2e3r4
bearer: HTTP 200         # 请求头 Authorization: Bearer q1w2e3r4

自动化调用（脚本读 /flows 等 JSON API）推荐 Bearer 头方式。

  • web_debug: false：前端调试日志开关。

六、生产配置模板

场景：2C/4GB 内存、NVMe 磁盘的调试网关服务器，长期常驻抓 API 流量、需要远程团队用 Web 界面查看、代理端口只对内网开放。

/root/.mitmproxy/config.yaml：

# 代理监听：绑定内网网卡地址，仅机房内网可达
listen_host: 0.0.0.0
listen_port: 8080

# 调 API 利器：剥缓存头与压缩头，流量在 mitmproxy 中始终可见明文
anticache: true
anticomp: true

# 上游为自签内网服务时按需打开（默认 false，公网调试不要开）
ssl_insecure: false

# 大响应转流式，避免 4GB 内存被单个大文件打爆
stream_large_bodies: 3m

# 拒绝公网来源连接（双保险，配合安全组）
block_global: true

# mitmdump 终端日志级别
termlog_verbosity: info

# 退出时落 HAR，便于事后导入浏览器 DevTools 复盘
hardump: /var/log/mitmproxy/session.har

配套 systemd 单元（ExecStart 不重复写 config.yaml 已有的参数）：

[Service]
ExecStart=/usr/local/bin/mitmdump
Restart=on-failure
RestartSec=3

参数依据：stream_large_bodies: 3m 控制单流内存上限（4GB 内存可承受数十个并发 3MB 流式响应）；ssl_insecure 保持默认关闭避免中间人风险放大；hardump 落盘路径需提前建目录并给运行账号写权限。若负载以长时大吞吐为主，把 mitmproxy/mitmweb（全量 flow 进内存）换成 mitmdump 常驻是内存面的第一优化。

七、常见问题（FAQ）

Q1：改了 config.yaml 不生效？ 按优先级排查：命令行参数 > config.yaml。先 ps -ef | grep mitmdump 看 systemd/ supervisord 是否在命令行写死了同名参数；再确认编辑的是 ~/.mitmproxy/config.yaml 且运行账号的家目录正确（systemd 服务默认 root，则为 /root/.mitmproxy/）。

Q2：--set 传序列型参数报格式错误？ 序列型 option 的单条格式内含分隔符（如 modify_headers 的 /filter/name/value），整条值要用引号包裹防止 shell 拆分：--set modify_headers='/~q/X-A/1'。多条时逗号分隔或重复 --set。

Q3：远程访问 mitmweb 界面 403？ 两个原因叠加：web_host 默认 127.0.0.1 根本没监听外网（表现为连接拒绝）；放开绑定后无密码会 403。正确做法是 --set web_host=0.0.0.0 --set web_password=<你的密码>，远程用 ?token=<密码> 或 Bearer 头访问，并务必用防火墙把 8081 限制到办公网段。

Q4：HTTPS 客户端一直报证书错误，是不是 certs 参数配错？ 先确认基础链路：~/.mitmproxy/mitmproxy-ca-cert.pem 是否已被客户端信任（安装篇 8.4 节）。certs 只影响"用哪张证书签发"，不影响信任链；除非你要对特定域名出示自备证书，否则无需动 certs。

Q5：block_global 拦了我的公网客户端，怎么放行？ 确认业务确需公网开放后 --set block_global=false，同时必须有防火墙/安全组兜底 + web_password（mitmweb）——裸公网开放代理会被扫描滥用为跳板。

Q6：哪里能看到当前进程实际生效的全部参数？ mitmproxy TUI 输入 :options；mitmweb 看界面 Options 页；无头环境用 mitmdump --options（看默认值）结合进程命令行 ps -ef（看覆盖值）比对。

八、参考链接