配置

警告

配置系统仍在开发中,后续可能发生变化。

各项选项也可以通过配置文件进行设置。当前支持的完整选项列表请参见 settings JSON 文件。

启动后,Maigret 会按以下顺序依次尝试从这些位置加载配置:

# relative path, based on installed package path
resources/settings.json

# absolute path, system-wide policy set by an administrator
/etc/maigret/settings.json

# absolute path, configuration file in home directory
~/.maigret/settings.json

# relative path, based on current working directory
settings.json

Missing any of these files is not an error. If the next settings file contains already known option, this option will be rewritten. So it is possible to make custom configuration for different users and directories.

数据库自动更新

Maigret 自带一份站点数据库,但它会随着新版本发布而逐渐过时。为了保持数据库是最新的,Maigret 在启动时会自动检查更新。

工作机制:

  1. 启动时,Maigret 会检查距离上次更新检查是否已超过 24 小时。

  2. 如果超过了,就从 GitHub 拉取一份轻量元数据文件(约 200 字节),查看是否有更新版本的数据库。

  3. 如果存在更新且兼容的数据库,Maigret 会把它下载到 ~/.maigret/data.json,并用它替代内置的版本。

  4. 如果下载失败,或新数据库与你的 Maigret 版本不兼容,就回退到内置数据库。

下载下来的数据库优先级高于内置数据库 —— 它是替换关系,而不是叠加。

状态消息仅在实际发生某种动作时才会打印:

[*] DB auto-update: checking for updates...
[+] DB auto-update: database updated successfully (<N> sites)
[*] DB auto-update: database is up to date (<N> sites)
[!] DB auto-update: latest database requires maigret >= 0.6.0, you have 0.5.0

强制更新:

使用 --force-update 参数会忽略检查间隔,立刻检查更新:

maigret username --force-update

更新只在启动时进行,完成后即用新下载的数据库继续执行正常搜索。

禁用自动更新:

使用 --no-autoupdate 参数可以完全跳过更新检查:

maigret username --no-autoupdate

或者在 ~/.maigret/settings.json 中永久设置:

{
    "no_autoupdate": true
}

该选项推荐用于 Docker 容器、CI 流水线以及离线隔离环境。

配置项(位于 settings.json):

选项

默认值

说明

no_autoupdate

false

完全禁用自动更新

autoupdate_check_interval_hours

24

检查更新的间隔(单位:小时)

db_update_meta_url

GitHub raw URL

元数据文件的 URL(用于自建镜像)

使用 --db 指定自定义数据库时,总是会跳过自动更新 —— 因为你已经明确选择了数据源。

激活令牌缓存

少数站点会拒绝匿名请求,必须先获取一个短期令牌:Twitter 需要 guest token,Vimeo 需要 JWT,Weibo 和 Wikimapia 需要会话 cookie,OnlyFans 需要一对签名请求头,ProtonMail 需要 bearer token。当这类站点返回的是验证页面而非个人主页时,Maigret 会在本次运行中即时获取这些令牌。

获取到的值会缓存在:

~/.maigret/activation.json

这样下次运行即可直接使用仍然有效的令牌,省去一次额外的往返请求。该文件以 0600 权限创建,因为这些令牌属于会话凭据——请按凭据对待,不要将其附在问题报告中。

缓存的内容: 仅保存与站点数据库自带值不同的请求头。若把整组请求头都存下来,就会把自带值固定住,以后的数据库更新将再也无法修改它们。

可以安全删除: 可以。下次运行会重新获取所需的令牌,代价仅仅是每个相关站点多一次请求。

为什么不存放在站点数据库中: 数据库属于软件包自带数据,它有版本、会做校验和验证,并且会被 数据库自动更新 整体替换;而在系统级安装(发行版软件包、snap、/nix/store)下,它所在的目录根本不可写。令牌是每个用户各自的状态,生命周期也不同,因此单独存放。

Cloudflare webgate

警告

实验特性。 cloudflare_bypass 这一节仍在积极开发中;字段名、默认值以及 trigger-protection 的路由规则都可能发生变化,不保证向后兼容。

settings.json 中的 cloudflare_bypass 配置块用于配置 Cloudflare webgate 绕过 所述的可选绕过机制。CLI、Python API 以及 Web 界面(python -m maigret.web.app)都会读取同一份配置:只需将 enabled 设为 true,所有入口都会把受 cf 保护的站点转发给求解器。

FlareSolverr 最小化配置。 先用 Docker 启动求解器,然后把下面这段配置写入 ~/.maigret/settings.json(或 配置 中列出的任意路径):

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

{
    "cloudflare_bypass": {
        "enabled": true,
        "modules": [
            {
                "name": "flaresolverr",
                "method": "json_api",
                "url": "http://localhost:8191/v1",
                "max_timeout_ms": 60000
            }
        ]
    }
}

这样就够了 —— session_prefix 和 trigger_protection 会回退到合理的默认值(分别为 "maigret" 和 ["cf_js_challenge", "cf_firewall", "webgate"])。下次运行时,Maigret 会输出 Cloudflare webgate active: ... 日志,并把命中的站点路由到求解器。

默认值(包含全部受支持字段的完整结构):

{
    "cloudflare_bypass": {
        "enabled": false,
        "session_prefix": "maigret",
        "trigger_protection": ["cf_js_challenge", "cf_firewall", "webgate"],
        "modules": [
            {
                "name": "flaresolverr",
                "method": "json_api",
                "url": "http://localhost:8191/v1",
                "max_timeout_ms": 60000
            },
            {
                "name": "chrome_webgate",
                "method": "url_rewrite",
                "url": "http://localhost:8000/html?url={url}&retries=1"
            }
        ]
    }
}

字段说明。

字段

说明

enabled

为 true 时,每次运行都会启用绕过;为 false(默认)时,仅在传入 --cloudflare-bypass 时才启用。

trigger_protection

一个 site.protection 值的列表;命中其中任何一个时,检查请求都会经由webgate 转发。protection 为空、或与本列表无交集的站点,仍使用默认的检查器(aiohttp / curl_cffi)。

session_prefix

FlareSolverr session 字段的前缀。Maigret 会在其后追加进程 PID,避免并发运行相互冲突。复用同一个 session 会在对同一域名的多次检查之间缓存 cf_clearance。

modules

后端模块的有序列表。第一个能连通的模块负责处理该检查,后续模块作为兜底链。

模块方法。

  • json_api —— 在 url 上提供的 FlareSolverr 兼容 POST 接口。会保留上游真实的 HTTP 状态码、响应头和最终 URL。可选字段 max_timeout_ms(默认 60000)是允许求解器在 JS 挑战上花费的单次请求时间预算。

  • url_rewrite —— 旧版 CloudflareBypassForScraping 接口。url 中必须包含 {url} 占位符;原始探测 URL 会被 URL 编码后代入。该方式仅返回渲染后的 HTML —— 因此在此方法下,checkType: status_code 和 response_url 两类检查会失准(成功时会被当作一个虚构的 HTTP 200)。

可选的 ``proxy`` 字段(仅 ``json_api`` 支持)。

每个模块都可以带一个 proxy 字段 —— 求解器会通过该代理转发上游请求。在站点启用了会封锁求解器主机的 ip_reputation 规则时,这会非常有用。接受两种写法:

{ "proxy": "socks5://localhost:1080" }

{ "proxy": { "url": "http://gw.example:3128",
             "username": "u",
             "password": "p" } }

仅 url/username/password 会被转发;其它字段会被丢弃。Cloudflare Error 1015 / 1020 响应表示该 IP 被限速或被封 —— 此时请更换代理,而不是反复重试。 .. _ai-analysis-settings:

AI 分析

--ai 参数(参见 AI 分析(内置))会调用一个 OpenAI 兼容的 chat completion 接口。以下三个配置项决定该请求的具体行为:

选项

默认值

说明

openai_api_key

""(空)

API key。为空时,Maigret 会回退到 OPENAI_API_KEY 环境变量。

openai_model

gpt-4o

默认模型名。可在单次运行中通过 --ai-model 覆盖。

openai_api_base_url

https://api.openai.com/v1

chat completion 接口的基础 URL。把它指向任何 OpenAI 兼容的服务(Azure OpenAI、OpenRouter、本地推理服务等),即可用其代替 OpenAI 官方服务。

下面是一个使用非 OpenAI 接口的 ~/.maigret/settings.json 片段示例:

{
    "openai_api_key": "sk-...",
    "openai_model": "gpt-4o-mini",
    "openai_api_base_url": "https://openrouter.ai/api/v1"
}

API key 的取值顺序为:settings.openai_api_key → OPENAI_API_KEY 环境变量;以第一个非空值为准。

备注

--ai 会把完整的内部 Markdown 报告(其中包含收集到的所有个人主页数据)发送至所配置的接口。请仅在你信任的服务商和账号上使用该功能。