配置

警告

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

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

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

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

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

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

上述文件中任何一个不存在都不算错误。如果后一个配置文件包含了已经出现过的选项,该选项就会被覆盖。因此你可以针对不同用户和不同目录设置不同的自定义配置。

数据库自动更新

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 (3180 sites)
[*] DB auto-update: database is up to date (3157 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 指定自定义数据库时,总是会跳过自动更新 —— 因为你已经明确选择了数据源。

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 报告(其中包含收集到的所有个人主页数据)发送至所配置的接口。请仅在你信任的服务商和账号上使用该功能。