常见问题

针对用户在文档搜索中出现频率最高的问题给出简短回答。需要更深入的内容时,每个小节都会链接到对应的详细页面。

可以用邮箱地址进行搜索吗?

不可以。 Maigret 只接受用户名(或 受支持的标识符类型 之一)作为输入 —— 通过 email 或 mail 地址进行搜索不在其能力范围内。查询邮箱地址需要另一类技术(探测密码重置流程、注册端点),属于另一类工具的工作。

推荐用于邮箱查询的开源工具:

在线服务:

注意:如果 Maigret 已经通过用户名找到了账号,它往往会自动从资料页中提取出关联的邮箱地址 —— 参见 从账号页面抽取信息。

可以配置代理 / SOCKS / Tor / I2P 吗?

可以。 三个参数分别对应三种不同目标:

  • --proxy URL —— 让 所有 检查请求都通过指定的 HTTP 或 SOCKS 代理转发(如果想让整次运行都走 Tor,使用 socks5://127.0.0.1:9050;或者用于住宅代理、公司网关,也用这个参数)。

  • --tor-proxy URL —— 只 对数据库中 .onion 站点生效。明网站点仍走你的直连(或 --proxy,如果你设置了的话)。

  • --i2p-proxy URL —— 同样的思路,只对 .i2p 域名生效。

最常见的混淆是 --proxy 与 --tor-proxy 的区别:--proxy 是"所有流量走这个网关",而 --tor-proxy 是"只有 onion 站点走 Tor"。

完整说明(Tor Browser 与系统 tor 守护进程端口差异、Tails 系统、超时与重试调优):Tor、I2P 与代理。

如果你的目标实际上是"绕过 WAF 拦截 / 修复 403 错误",请参见下文 站点失败 / 超时 / 403 一节 —— 对此场景,住宅代理几乎总是优于 Tor 或 VPN。

可以配合 VPN 使用 Maigret 吗?

可以,但通常 --proxy 是更好的选择。VPN 在操作系统层透明工作 —— Maigret 不需要任何特殊配置就能用上 VPN。不过:

  • --proxy 是按进程生效的:不会影响其它应用,在切换时也不会泄露。

  • --proxy 会让出口 IP 出现在日志里,在排查为什么某批站点返回 UNKNOWN 时很有用。

  • --proxy 每次运行都可以传入不同的值,因此可以在住宅出口和数据中心出口之间轮换,而不必动系统的网络设置。

如果很多站点都返回 403,原因几乎可以肯定是 VPN 出口 IP 在某个 WAF 黑名单上(Cloudflare、DDoS-Guard、Akamai 都会对常见 VPN 网段做整体封锁)。通常的修复办法是通过 --proxy 使用住宅代理 —— 参见 TROUBLESHOOTING.md 中的 "Lots of sites fail / timeout / return 403" 章节。

Maigret 会通过 DNS 检查域名吗?

可以,处于实验阶段。 加上 --with-domains,Maigret 会在执行普通 HTTP 检查的同时,通过 DNS(A 记录)解析一小组 {username}.<tld> 模式。当前包含的后缀有 .ddns.net、.com、.pro、.me、.biz、.email、.guru —— 数据库中共有 7 条 protocol: dns 的记录。

maigret <username> --with-domains

该参数被标记为 实验性:仅靠 DNS 的检查可能会把停放域名和通配符记录也识别为"用户名已注册",所以命中应当视为线索,而不是确认结果。

如果你的任务是更广义的 DNS 侦察 —— 子域名枚举、WHOIS 历史、相似域名 —— 那么 Maigret 不是合适的工具。常用替代方案如下:

  • dnstwist —— 用于发现拼写错误抢注与相似域名。

  • amass / subfinder —— 子域名枚举。

  • theHarvester —— 按域名收集邮箱 / 主机 / 子域名信息。

有 Maigret 的 Telegram 机器人吗?

有。 社区维护的一个 Telegram 机器人让你无需在本地安装就能运行 Maigret:

关于*搜索 Telegram 本身*这个问题:Maigret 在常规扫描中会检查 t.me/<user> 页面是否存在,但不会解析频道、帖子、成员或消息内容。如需对 Telegram 内容进行OSINT 调查,需要使用专门的工具。

Web 界面在哪里?

maigret --web 5000

然后在浏览器中打开 http://127.0.0.1:5000。截图和完整说明见 Web 界面。

站点失败 / 超时 / 返回 403 —— 连接失败 (connection failure)

这是被反映得最多的问题,几乎总是由反机器人防护(Cloudflare、DDoS-Guard、Akamai)或缓慢的网络链路引起的,而不是 Maigret 的 bug。可按下面的顺序逐步调整:

  1. --timeout 60 —— 在慢速网络和 Tor 环境下,默认 30 秒往往太紧。

  2. --retries 2 —— 覆盖偶发性失败。

  3. -n 20 —— 降低并发可以减少 WAF 的速率限制。

  4. --proxy http://user:pass@residential-proxy:port —— 数据中心 IP(AWS、GCP、DigitalOcean)以及大多数 VPN 网段都被整体封锁;住宅 / 移动出口通常能解决大部分 403。

完整的故障排查矩阵(针对 403、超时、SSL、验证码、大量 UNKNOWN 等各类错误的处理办法)见 TROUBLESHOOTING.md。

如何生成 PDF 报告?

PDF 支持是一个可选附加项,因为它会引入较重的图形库依赖:

pip install 'maigret[pdf]'
maigret <username> --pdf

在 Linux / macOS 上还需要安装系统级图形库(Pango、Cairo、GDK-PixBuf)。各操作系统的安装步骤见 安装 中 Optional: PDF reports 一节。

其它报告格式(--html、--md、--json、--csv、--txt、--xmind)见 命令行选项。

maigret: command not found

The install succeeded but your shell can't find the maigret launcher (you may see -bash: maigret: command not found or a not recognized message on Windows). The package is installed — only the entry-point script is not on your PATH. Fixes, in order of laziness:

  • Run it as a module instead — this always works if the package imported:

    python3 -m maigret <username>

  • pip install --user puts the script in a per-user bin / Scripts directory that is often not on PATH. The cleanest fix is to install into an isolated environment that manages PATH for you:

    pipx install maigret

  • On Windows, reopen the terminal after installing (PATH is only read at startup), or use the standalone maigret_standalone.exe — see 安装.

error: metadata-generation-failed

This comes from pip, not Maigret: pip could not build one of the dependencies. Almost always the build toolchain is stale or a native dependency is missing its system libraries. Try, in order:

  • Upgrade the toolchain and retry:

    python -m pip install --upgrade pip setuptools wheel

  • Use a supported interpreter (Python 3.10–3.12). Bleeding-edge or end-of-life versions frequently have no prebuilt wheels, forcing a source build that then fails.

  • If the failing package is a native one (lxml, reportlab, _renderPM, or an error mentioning ft2build.h / cairo), you need system build dependencies — see the Troubleshooting section of 安装, or skip the compilers entirely and use Docker.

Too many errors of type "..."

This is Maigret's end-of-run summary, not a crash — the run finished. It means a large share of sites failed the same way, so the fix depends on the class printed in the quotes:

  • Connecting failure — check your internet connection; if only a subset of sites fails, lower parallelism with -n 10.

  • Connecting failure (DNS) — DNS resolution failed for most sites. Try --dns-resolver threaded (often fixes Windows / VPN / corporate networks); failing that, check your VPN / firewall and consider a public resolver (1.1.1.1 or 8.8.8.8).

  • Request timeout — raise --timeout or switch ISP / network.

  • Captcha — switch to another IP address, or supply service cookies.

  • Bot protection / Access denied — switch IP; a residential --proxy or --cloudflare-bypass is the usual fix.

  • Webgate unavailable — --cloudflare-bypass is on but no solver is reachable; start FlareSolverr, or drop the flag to skip protected sites.

If most of your run is one of the last three, see the Sites fail / timeout / return 403 section above and the full TROUBLESHOOTING.md.