安装

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。

Code signing

Windows binaries are built on GitHub Actions from this repository. The project has applied to the SignPath Foundation for a free code signing certificate; once issued, released Windows binaries will be signed as part of the same automated build.

云端 Shell 与 Jupyter Notebook

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

Snap (Linux)

Maigret is on the Snap Store for amd64 and arm64. It needs neither Python nor pip:

sudo snap install maigret

# usage
maigret username

The snap is strictly confined: it can read and write your home directory and very little else. Run it from a directory under $HOME and reports land in ./reports as usual. Running it from somewhere it cannot see, /tmp for instance, fails before the search starts.

Access to USB drives and other removable media is not connected by default:

sudo snap connect maigret:removable-media

Updates arrive on their own through snapd, so the bundled site database and the code both stay current without any action.

通过 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])。

Isolated installation with pipx

pip3 install maigret drops Maigret and its dependencies into whichever Python environment happens to be active. If that is the system Python, the install can collide with packages your distribution manages, and on recent Debian, Ubuntu and Fedora pip refuses outright with error: externally-managed-environment.

pipx avoids all of that. It gives Maigret its own virtual environment, puts only the maigret command on your PATH, and keeps the dependencies away from everything else on the machine:

pipx install maigret

# usage
maigret username

The pdf extra works the same way:

pipx install 'maigret[pdf]'

Upgrading and removing are one command each:

pipx upgrade maigret
pipx uninstall maigret

备注

If you already use uv, uv tool install maigret does the same job.

开发版本(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 script maigret is 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 绕过。

安装