mitmproxy 安装与初始化实战

目标：在 Ubuntu 22.04 服务器上完成 mitmproxy 12.3.1 的安装与初始化——覆盖官方二进制包、Python venv、发行版 apt 三条安装路线的实测对比，并完成 CA 证书生成、系统信任、首次代理请求闭环与 systemd 托管。全文命令与回显均在真实服务器环境逐条实测照抄，未实测内容不写入。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（PRETTY_NAME="Ubuntu 22.04.5 LTS"，内核 7.0.0-38-generic，x86_64）
系统自带 Python：3.10.12（python3 --version）
目标软件：mitmproxy 12.3.1（官方最新稳定版，2026-10-27 查询 GitHub Releases 确认）
安装位置（主线方案）：/usr/local/bin/mitmproxy、/usr/local/bin/mitmweb、/usr/local/bin/mitmdump
证书目录：/root/.mitmproxy/（首次运行自动生成）
代理监听端口：8080（默认值，下文实测沿用；如需改端口见《mitmproxy 配置参数详解》）
网络情况：官方下载源 downloads.mitmproxy.org 服务器直连可用（102MB 包约 29 秒完成），未启用代理；下载缓慢时可走 HTTP 代理，见常见问题
同篇实测的其他组件：python3.10-venv（apt 安装）、systemd（系统自带）

二、前置条件

安装前确认服务器满足以下条件（均在实测机验证过）：

系统依赖：curl、wget、ca-certificates、procps 用于下载与验证，主线二进制包本身零依赖（自带运行时）：

apt-get update && apt-get install -y curl wget ca-certificates procps   # 基础工具

架构确认：官方二进制按 glibc 发行，确认机器是 x86_64：

uname -m

实测回显：

x86_64

时间同步：mitmproxy 动态签发的 TLS 证书带有效期，系统时间错乱会导致客户端证书校验失败，先用 date 确认时间正常：

date

实测回显：

Mon Oct 27 07:10:02 UTC 2026

💡 技术拓展：Linux 上安装"自带运行时的 Go/Rust 二进制"与"Python 生态工具"是两条不同的依赖哲学。mitmproxy 官方二进制包用 PyInstaller 打包了独立 Python 解释器与全部依赖，装完即用、不碰系统 Python——这是服务器上最干净的方式；而 pip install mitmproxy 会把 mitmproxy 及其几十个依赖（cryptography、h2、kaitaistruct 等）装进 Python 环境，版本受限于系统 Python。生产服务器优先前者，开发机需要嵌入 Python 项目时选后者。

三、版本选型说明

2026-10-27 查询 GitHub Releases（https://github.com/mitmproxy/mitmproxy/releases），mitmproxy 12.x 系列最近的发布序列为：12.0.1 → 12.1.0 → 12.1.1 → 12.1.2 → 12.2.0 → 12.2.1 → 12.2.2 → 12.2.3 → 12.3.0 → 12.3.1（最新）。本文以 12.3.1 为主线实测。

三条安装路线可装的版本差异很大（后文逐条实测）：

路线	实测可装版本	说明
官方二进制包（downloads.mitmproxy.org）	12.3.1	与 Releases 同步，主线推荐
Python venv/pip（系统 Python 3.10）	11.0.2	12.x 不再支持 Python 3.10，pip 自动回退
Ubuntu 22.04 apt 仓库（universe）	6.0.2-1	2021 年版本，仅供无外网内网源兜底

四、方案 A：官方二进制包安装（主线）

4.1 方案说明

从官方下载站 downloads.mitmproxy.org 获取与 Releases 同版本的 tar.gz，内含 mitmproxy、mitmweb、mitmdump 三个静态可执行文件，解压即用。优点：版本最新、自带 Python 运行时与 OpenSSL、不污染系统环境；这是官方下载页首推的 Linux 安装方式（官网下载按钮 "Download Linux Binaries" 直指该站）。

4.2 下载与校验

cd /opt
curl -sS -o mitmproxy-12.3.1-linux-x86_64.tar.gz https://downloads.mitmproxy.org/12.3.1/mitmproxy-12.3.1-linux-x86_64.tar.gz

下载耗时与产物实测：

real    0m28.860s
-rw-r--r-- 1 root root 107431939 Oct 27 07:13 mitmproxy-12.3.1-linux-x86_64.tar.gz

记下 sha256 供留档比对：

sha256sum mitmproxy-12.3.1-linux-x86_64.tar.gz

实测回显：

f7b4237f5702f6cd21357fe6e4680a7e905f8f9b816b872230d018ea696c34d5  mitmproxy-12.3.1-linux-x86_64.tar.gz

4.3 解压与安装

tar xzf mitmproxy-12.3.1-linux-x86_64.tar.gz
mv mitmproxy mitmweb mitmdump /usr/local/bin/

包内仅三个可执行文件，无目录结构，直接移入 PATH 即完成安装。

4.4 版本验证

mitmproxy --version
which mitmproxy mitmweb mitmdump

实测回显：

Mitmproxy: 12.3.1 binary
Python:    3.15.1
OpenSSL:   OpenSSL 4.0.3 29 Sep 2026
Platform:  Linux-7.0.0-38-generic-x86_64-with-glibc2.35
/usr/local/bin/mitmproxy
/usr/local/bin/mitmweb
/usr/local/bin/mitmdump

Python: 3.15.1 是二进制包内嵌的运行时版本，与系统 Python 3.10 无关——这正是方案 A 的核心优势。

五、方案 B：Python venv 安装（pip 路线实测）

5.1 方案说明

通过 pip 把 mitmproxy 装进独立虚拟环境，适合需要在 Python 项目中调用 mitmproxy 库（from mitmproxy import http 写插件调试）或无法下载官方二进制的场景。生产服务器上做纯代理用途时，此方案不如方案 A。

5.2 安装 venv 支持

apt-get install -y python3-pip python3-venv

5.3 创建环境并安装

python3 -m venv /opt/mp-venv
/opt/mp-venv/bin/pip install mitmproxy

pip 解析依赖时只给出 11.0.2——先用 pip index versions 看清这一约束：

python3 -m pip index versions mitmproxy

实测回显（节选）：

mitmproxy (11.0.2)
Available versions: 11.0.2, 11.0.1, 11.0.0, 10.4.2, 10.4.1, 10.4.0, 10.3.1, 10.3.0, 10.2.4, 10.2.3, 10.2.2, 10.2.1, 10.2.0, 10.1.6, 10.1.5, 10.1.4, 10.1.3, 10.1.2, 10.1.1, 10.1.0, 10.1.0, 10.0.0, 9.0.1, 9.0.0, 8.1.1, 8.1.0, 8.0.0, 7.0.4, 7.0.3, 7.0.2, 7.0.1, 7.0.0, 6.0.2, 6.0.1, 6.0.0, ...

即：在系统 Python 3.10.12 下，PyPI 能解析到的最高版本是 11.0.2（12.x 系列已不支持 Python 3.10）。安装后验证：

/opt/mp-venv/bin/mitmdump --version

实测回显：

Mitmproxy: 11.0.2
Python:    3.10.12
OpenSSL:   OpenSSL 3.4.1 11 Feb 2025
Platform:  Linux-7.0.0-38-generic-x86_64-with-glibc2.35

⚠️ 注意：若坚持 pip 路线拿 12.x，需要先升级到 Python 3.11+（如 deadsnakes PPA 安装 python3.11 后再建 venv）。无需 Python 库集成时直接用方案 A 更省事。

六、方案 C：发行版 apt 仓库安装

6.1 方案说明与版本实测

Ubuntu 22.04 的 universe 仓库收录了 mitmproxy，但版本极旧。先查候选版本：

apt-cache policy mitmproxy

实测回显：

mitmproxy:
  Installed: (none)
  Candidate: 6.0.2-1
  Version table:

apt-get install mitmproxy 会装上 6.0.2（2021 年发布），与当前 12.3.1 相差六个大版本，大量参数与插件 API 已不兼容。此方案仅在完全无外网、且本地源缓存了该包时作为兜底，生产环境不建议采用。

七、方案对比与选择建议

维度	A 官方二进制（实装主线）	B pip/venv	C apt 发行版包
实测版本	12.3.1	11.0.2（Python 3.10 上限）	6.0.2-1
是否需联网	需（官方下载站）	需（PyPI）	需（Ubuntu 镜像源）
系统侵入	无（3 个静态文件）	占用 venv 空间	系统包管理器托管
自带运行时	是（Python 3.15.1 + OpenSSL 4.0.3）	依赖系统 Python	依赖系统 Python
版本时效	与 Releases 同步	滞后一个支持周期	严重滞后
适用场景	生产服务器代理/抓包	需 Python 库集成或写插件调试	离线兜底

选择建议：可联网服务器一律方案 A；要在自己的 Python 项目里 import mitmproxy 或开发插件时用方案 B 的 venv（并用 Python 3.11+ 拿新特性）；方案 C 仅当机器被防火墙隔离且内网源恰好有缓存时使用。

八、初始化与首次运行

8.1 首次启动 mitmdump

安装完成后直接前台启动，观察初始化输出：

mitmdump

实测回显（前台启动首行）：

[07:17:35.719] HTTP(S) proxy listening at *:8080.

首次启动 mitmproxy 自动完成两件事：在 /root/.mitmproxy/ 生成 CA 证书体系；在 8080 端口开启常规 HTTP 代理监听。Ctrl+C 退出。

8.2 证书文件清点

ls ~/.mitmproxy/

实测回显：

mitmproxy-ca-cert.cer
mitmproxy-ca-cert.p12
mitmproxy-ca-cert.pem
mitmproxy-ca.p12
mitmproxy-ca.pem
mitmproxy-dhparam.pem

各文件用途：mitmproxy-ca-cert.pem 是 PEM 格式 CA 证书（发给 curl/Python/nginx 等信任），.cer/.p12 供 Windows/Java 等场景，mitmproxy-ca.pem 含私钥（代理签发用，妥善保管），mitmproxy-dhparam.pem 是 DH 参数。

8.3 未信任 CA 时的 HTTPS 告警（实测）

初始化后先复现一次"证书不信任"的经典报错——curl 经代理访问 HTTPS 站点：

curl -x http://127.0.0.1:8080 https://example.com/

实测回显：

curl: (60) SSL certificate problem: unable to get local issuer certificate
More details here: https://curl.se/docs/sslcerts.html

curl failed to verify the legitimacy of the server and therefore could not
establish a secure connection to it. To learn more about this situation and

这就是中间人代理的预期行为：mitmproxy 用自己的 CA 签发了 example.com 的"仿冒证书"，而系统信任库里没有这个 CA，curl 拒绝继续。此时用 -k 跳过校验可以临时打通链路：

curl -sk -x http://127.0.0.1:8080 https://example.com/ -o /dev/null -w "HTTP %{http_code}\n"

实测回显：

HTTP 200

8.4 信任 CA 证书（Debian/Ubuntu 路径）

把 PEM 证书复制进系统 CA 目录（文件后缀必须是 .crt），再刷新信任库：

cp ~/.mitmproxy/mitmproxy-ca-cert.pem /usr/local/share/ca-certificates/mitmproxy-ca.crt
update-ca-certificates

实测回显：

Running hooks in /etc/ca-certificates/update.d...
done.

8.5 信任后闭环验证

再次走代理请求 HTTPS，无需 -k：

curl -sS -x http://127.0.0.1:8080 https://example.com/ -o /dev/null -w "HTTP %{http_code}\n"

实测回显：

HTTP 200

至此初始化闭环完成：代理可用、HTTPS 明文可见且客户端信任链完整。下一步把 mitmdump 交给 systemd 常驻。

九、systemd 托管

9.1 服务单元

创建 /etc/systemd/system/mitmdump.service：

[Unit]
Description=mitmproxy mitmdump HTTP(S) proxy
After=network-online.target

[Service]
ExecStart=/usr/local/bin/mitmdump --listen-host 0.0.0.0 --listen-port 8080
Restart=on-failure
RestartSec=3

[Install]
WantedBy=multi-user.target

9.2 启用与状态验证

systemctl daemon-reload
systemctl enable --now mitmdump
systemctl status mitmdump --no-pager

实测回显：

Created symlink /etc/systemd/system/multi-user.target.wants/mitmdump.service → /etc/systemd/system/mitmdump.service.
● mitmdump.service - mitmproxy mitmdump HTTP(S) proxy
     Loaded: loaded (/etc/systemd/system/mitmdump.service; enabled; vendor preset: enabled)
     Active: active (running) since Tue 2026-10-27 07:24:01 UTC; 3s ago
   Main PID: 3768 (mitmdump)
      Tasks: 2 (limit: 21153)
     Memory: 140.8M
        CPU: 645ms
     CGroup: /system.slice/mitmdump.service

常驻内存约 140MB（空载），Restart=on-failure 保证异常退出后 3 秒拉起。经 systemd 实例发一条请求确认端口可用：

curl -sS -x http://127.0.0.1:8080 http://127.0.0.1:8000/ -o /dev/null -w "port 8080: HTTP %{http_code}\n"

实测回显：

port 8080: HTTP 200

💡 说明：mitmdump 没有 ExecReload 语义的优雅重载，改配置后用 systemctl restart mitmdump。需要加载脚本插件时把 -s /path/addon.py 追加进 ExecStart，插件机制详见《mitmproxy 常用 CLI 命令详解》。

十、配置说明

安装与初始化阶段只涉及两个落盘位置：

/usr/local/bin/：三个可执行文件（方案 A）；venv 方案在 /opt/mp-venv/bin/；
/root/.mitmproxy/：CA 证书 + 用户级配置。mitmproxy 启动时会读取 ~/.mitmproxy/config.yaml，把常用参数（监听地址/端口、anticache 等）持久化，命令行参数优先级高于配置文件——实测在 config.yaml 写 listen_port: 8090 后，mitmdump 无参数启动监听 8090，而 mitmdump --listen-port 8080 则命令行覆盖生效。完整的 options 体系、参数分组与生产配置模板见《mitmproxy 配置参数详解》。

十一、常见问题（FAQ）

Q1：下载官方二进制特别慢或超时怎么办？ 实测环境直连 downloads.mitmproxy.org 约 29 秒完成 102MB；若网络受限，可给 curl 显式挂代理：curl -x http://<代理IP>:<端口> -o mitmproxy-12.3.1-linux-x86_64.tar.gz https://downloads.mitmproxy.org/12.3.1/mitmproxy-12.3.1-linux-x86_64.tar.gz。国内网络亦可改用方案 B 的 PyPI（清华/阿里镜像均可加速 pip），代价是版本上限受 Python 版本约束。

Q2：pip install mitmproxy 装出来的不是最新版？ 实测系统 Python 3.10.12 下 pip 最高解析到 11.0.2（12.x 已要求更新的 Python 版本）。用 pip index versions mitmproxy 查看当前解释器能拿到的版本列表；确需 12.x 则升级 Python 或改用方案 A 官方二进制。

Q3：apt 装的 mitmproxy 版本太旧、参数对不上？ Ubuntu 22.04 universe 源候选版本为 6.0.2-1（2021 年）。老版本的 options 与插件 API 与 12.x 有大量差异，文档排障时务必先 mitmproxy --version 对版本，建议卸载后改走方案 A。

Q4：curl 报 (60) SSL certificate problem: unable to get local issuer certificate？ 客户端不信任 mitmproxy CA。按 8.4 节把 ~/.mitmproxy/mitmproxy-ca-cert.pem 装入 /usr/local/share/ca-certificates/ 并 update-ca-certificates；其他运行时（Java/Python requests/Node）各有独立信任库，需按各自机制单独导入，参考官方文档 "How to trust mitmproxy certificates" 一节。

Q5：~/.mitmproxy 目录能随便复制到另一台服务器吗？ 可以，CA 体系是纯文件。把整个目录拷过去新机器即复用同一 CA，客户端无需重新信任——前提是妥善保管含私钥的 mitmproxy-ca.pem，泄露意味着任何拿到它的人都能伪造你信任的站点证书。

Q6：systemd 服务启动后立即退出？ 先手动前台运行 mitmdump 看是否端口被占（Address already in use）；确认 8080 未被其他进程占用后再 systemctl start。多实例并存时给每个实例显式 --listen-port 并拆成独立 service 单元。

十二、卸载与清理

按安装方案逆向清理（实测机执行的命令清单）：

# 方案 A
rm -f /usr/local/bin/mitmproxy /usr/local/bin/mitmweb /usr/local/bin/mitmdump
rm -f /opt/mitmproxy-12.3.1-linux-x86_64.tar.gz

# 方案 B
rm -rf /opt/mp-venv

# 方案 C
apt-get remove --purge -y mitmproxy && apt-get autoremove -y

# 公共部分：CA 信任与用户数据
rm -f /usr/local/share/ca-certificates/mitmproxy-ca.crt && update-ca-certificates
rm -rf /root/.mitmproxy

# systemd
systemctl disable --now mitmdump 2>/dev/null
rm -f /etc/systemd/system/mitmdump.service && systemctl daemon-reload

十三、参考链接

mitmproxy 介绍与选型：《mitmproxy 介绍与选型指南》
配置参数详解：《mitmproxy 配置参数详解》
CLI 命令详解：《mitmproxy 常用 CLI 命令详解》
官方下载站：https://downloads.mitmproxy.org/ （2026-10-27 查询）
GitHub Releases（12.3.1 版本依据）：https://github.com/mitmproxy/mitmproxy/releases （2026-10-27 查询）
官方文档·证书信任指引：https://docs.mitmproxy.org/stable/overview-features/ （2026-10-27 查询）