安装

Maigret 可以通过 pip 或 Docker 安装,也可以直接从克隆下来的仓库运行。此外,还可以在线使用社区 Telegram 机器人,其源码已在 GitHub 上开源。

Windows 独立 EXE 二进制文件

用于 Windows 的独立程序 maigret_standalone.exe 发布在 GitHub 仓库的Releases 页面。每次合并到 main 与 dev 分支后,都会自动构建一个新版本。

启动该 EXE 的方式有两种:

在资源管理器中双击运行。 Maigret 会让你输入一个用户名,执行一次默认搜索,并在结束时暂停,这样屏幕上打印的报告链接会保留到你按下 Enter 为止。

从终端启动,以便完整控制各项参数:

按 Win+R,输入 cmd 后回车(或使用 PowerShell)。
切换到你保存 EXE 文件的目录,例如 cd %USERPROFILE%\Downloads。

至少传入一个用户名后再运行:

maigret_standalone.exe USERNAME
maigret_standalone.exe USERNAME --html       :: also save an HTML report
maigret_standalone.exe USERNAME --pdf        :: also save a PDF report
maigret_standalone.exe --help                :: list all options

报告会写入 EXE 同级的 reports\ 子目录。

如何运行的视频指引:https://youtu.be/qIgwTZOmMmM。

云端 Shell 与 Jupyter Notebook

如果你不想在本地安装 Maigret,可以使用云端 Shell 或 Jupyter Notebook。点击下方任一按钮,按提示在浏览器中启动即可。

通过 PyPI 本地安装

Maigret 自带一份站点数据库。无论通过 PyPI 还是其它方式安装完毕后,在每次运行时,它都可以自动从 GitHub 拉取兼容的更新版数据库 —— 详见配置中的数据库自动更新。

备注

需要 Python 3.10 或更高版本以及 pip,推荐使用 Python 3.11。

# install from pypi
pip3 install maigret

# usage
maigret username

PDF 报告支持作为可选扩展单独提供,因为它依赖一些 pip 无法替你安装的系统级图形库。如果你打算使用 --pdf,请带上 pdf extra 进行安装:

pip3 install 'maigret[pdf]'

关于 PDF 为何是可选项,以及最常见构建错误的修复方法,请见下文可选项:PDF 报告(maigret[pdf])。

开发版本(GitHub)

git clone https://github.com/soxoj/maigret && cd maigret
pip3 install .

# OR
pip3 install git+https://github.com/soxoj/maigret.git

# usage
maigret username

# OR use poetry in case you plan to develop Maigret
pip3 install poetry
poetry run maigret

Docker

# official image of the development version, updated from the github repo
docker pull soxoj/maigret

# usage
docker run -v /mydir:/app/reports soxoj/maigret:latest username --html

# manual build
docker build -t maigret .

故障排查

如果你在安装过程中遇到 cannot find ft2build.h,或与 reportlab / _renderPM 相关的构建错误,那就需要先安装编译原生扩展所需的系统级依赖。

Debian / Ubuntu / Kali:

sudo apt install -y libfreetype6-dev libjpeg-dev libffi-dev

Fedora / RHEL / CentOS:

sudo dnf install -y freetype-devel libjpeg-devel libffi-devel

Arch Linux:

sudo pacman -S freetype2 libjpeg-turbo libffi

macOS(Homebrew):

brew install freetype

安装好上述系统依赖后,再重新安装 maigret。

如果仍有问题,可以考虑改用 Docker —— 其镜像中已包含所有必需的依赖。

可选项:PDF 报告(`maigret[pdf]`)

--pdf 报告格式作为可选 extra 提供,启用方式如下:

pip3 install 'maigret[pdf]'

如果未安装 PDF 支持但传入了 --pdf,Maigret 会打印一条警告并继续运行,而不会崩溃 —— 其它输出格式(--html、--json、--csv、--txt、--xmind、--graph)依然正常可用。

为什么 PDF 是可选的?

Maigret 通过转换 HTML 模板来渲染 PDF,而这条转换流水线最终通过一连串 Python 包依赖 cairo 图形库,大致的依赖链如下:

maigret[pdf] → xhtml2pdf → svglib → rlPyCairo → pycairo → libcairo2 (system)

这条依赖链最底层是一个 C 库 —— libcairo2 —— 必须在 pip 构建 Python 绑定*之前*就已存在于主机上。其 Python 绑定包(pycairo)目前在 PyPI 上只发布了 Windows wheel;在 Linux 和 macOS 上,pip 会回退为从源码构建,只要 pkg-config 找不到 cairo,构建就会失败,报错形如:

../cairo/meson.build:31:12: ERROR: Dependency "cairo" not found (tried pkg-config)
note: This error originates from a subprocess, and is likely not a problem with pip.
error: metadata-generation-failed

为了让一小部分确实需要 PDF 的用户能用上,而对每一次 Maigret 安装都强行拉入这一整条依赖链,显然不划算 —— 因此 xhtml2pdf 被收进了 pdf extra 中。

另有两个包 —— arabic-reshaper 和 python-bidi —— 也被一并收入了同一个 extra。Maigret 核心从不导入它们;它们仅被 xhtml2pdf 用于在 PDF 中塑造阿拉伯字符并排版从右到左的文字。python-bidi 0.5 及以上版本是 Rust 绑定,在某些没有预编译 wheel 的小众平台上,如果不这样隔离,就会让从未要求 PDF 支持的用户也被迫触发一次 Cargo 构建。

安装系统前置依赖

在执行 pip install 'maigret[pdf]' 之前,先安装 cairo 头文件、pkg-config 以及一套可用的 C 工具链。

Debian / Ubuntu / Linux Mint / Kali:

sudo apt update
sudo apt install -y libcairo2-dev pkg-config python3-dev build-essential
pip3 install --upgrade pip setuptools wheel
pip3 install 'maigret[pdf]'

Fedora / RHEL / CentOS:

sudo dnf install -y cairo-devel pkgconfig python3-devel gcc
pip3 install 'maigret[pdf]'

Arch Linux:

sudo pacman -S cairo pkgconf base-devel
pip3 install 'maigret[pdf]'

Alpine Linux:

sudo apk add cairo-dev pkgconf python3-dev build-base
pip3 install 'maigret[pdf]'

macOS(Homebrew):

brew install cairo pkg-config
pip3 install --upgrade pip setuptools wheel
pip3 install 'maigret[pdf]'

Windows:

不需要安装任何系统包 —— pycairo 在 Windows 上提供了预编译 wheel。直接执行:

pip install 'maigret[pdf]'

Google Cloud Shell / Colab / Replit / 通用 CI:

这些环境的表现与 Debian/Ubuntu 类似 —— 在 pip install 'maigret[pdf]' 之前,安装相同的 libcairo2-dev pkg-config python3-dev build-essential 组合即可。如果你无法控制基础镜像、也不能执行 apt install,那就跳过这个 extra,改用 --html 报告;HTML 报告承载的数据完全一致,任何浏览器都能打开。

安装后出现 `maigret: command not found`

如果 pip 打印出类似下面的警告:

WARNING: The scripts maigret and update_sitesmd are installed in
'/home/<user>/.local/bin' which is not on PATH.

…而 maigret --version 又报 command not found,这说明你用 --user 安装时,入口脚本被放进了一个不在 shell 搜索路径里的目录。把它加入 PATH:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

或者改在虚拟环境中安装 —— 入口脚本会自动出现在该 venv 的 bin/ 下:

python3 -m venv ~/.venvs/maigret
source ~/.venvs/maigret/bin/activate
pip install 'maigret[pdf]'   # or just `pip install maigret`

可选项:Cloudflare 绕过求解器

警告

实验特性。 Cloudflare webgate 仍在积极开发中;配置项和 CLI 行为都可能发生变化,不保证向后兼容。

打上 cf_js_challenge / cf_firewall 标签的站点需要真实浏览器才能通过 JavaScript 挑战。要检查这些站点,你可以在本地运行一个 FlareSolverr 实例 —— 在传入 --cloudflare-bypass 后,Maigret 会把受保护站点的检查请求转交给它:

docker run -d -p 8191:8191 --name flaresolverr ghcr.io/flaresolverr/flaresolverr:latest

该求解器是可选项 —— 没有它 Maigret 一样能跑;只有那些 protection 字段与 settings.cloudflare_bypass.trigger_protection 有交集的站点,才会实际依赖求解器。详情参见 Cloudflare webgate 绕过。

安装