escalator

给它一个 URL，就能得到干净的 Markdown。它会爬升到可行的最低一级阶梯——先尝试普通 HTTP 抓取，再通过住宅代理走同样的抓取，最后才用隐身浏览器——并在第一个返回真实内容的层级停下。

$ escalator scrape https://en.wikipedia.org/wiki/Web_scraping | head -3
# Web scraping

**Web scraping**, **web harvesting**, or **web data extraction** is [data scraping](...)

快速开始

# 1. install uv (https://docs.astral.sh/uv/getting-started/installation/)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. configure this machine -- finds your browser, or fetches one
uvx escalator init

# 3. use it
uvx escalator scrape https://en.wikipedia.org/wiki/Web_scraping

这就是全部的上手流程。init 会写入一个配置文件，首次运行前无需手动编辑任何内容。如果有什么看起来不对：运行 escalator doctor。

在最小化 Linux 上（裸容器、全新 VPS），Chrome 需要桌面系统已自带的系统库。escalator 不会替你安装它们——它会打印出确切的 apt-get 命令，escalator doctor 会重复显示该命令。只需一条命令，一次即可：

sudo apt-get update && sudo apt-get install -y \
  libnss3 libnspr4 libatk1.0-0t64 libatk-bridge2.0-0t64 libcups2t64 libdrm2 \
  libxkbcommon0 libxcomposite1 libxdamage1 libxext6 libxfixes3 libxrandr2 \
  libgbm1 libglib2.0-0t64 libpango-1.0-0 libcairo2 libasound2t64 \
  libatspi2.0-0t64 libxcb1 libdbus-1-3 libexpat1

默认不附带任何东西，这是设计使然。 escalator 以未配置状态发布——不捆绑浏览器、不捆绑代理、没有遥测，也不会在其自身目录之外写入任何内容。init 的存在是为了让配置变成两分钟的对话，而不是一场 README 寻宝游戏。

Related MCP server: Safer Fetch MCP Server

安装

核心流程所需的一切都包含在默认安装中，包括浏览器阶梯——它本身不携带浏览器，这正是 escalator browser install 的用途。还有一个额外选项：escalator[mcp] 会添加 MCP 界面，Docker 镜像已包含该功能。

Docker

docker run --rm \
  -e ESCALATOR_SERVER_API_KEYS=your-key \
  -p 8000:8000 -v ./data:/data \
  ghcr.io/ruslanstarikov/escalator serve

该镜像携带固定版本的浏览器，完全通过环境变量配置——参见 docker-compose.example.yml 了解代理配置。它以 uid 1000 运行，因此 bind-mount 的 ./data 目录需要对该用户可写。

命令

escalator init [--yes]     configure this machine; --yes for scripts
escalator doctor [--json]  check everything, one fix per failure
escalator browser list     every browser found, and which one wins
escalator browser install  download Chrome for Testing into the data dir
escalator scrape URL       one page to stdout, so it pipes
escalator serve            the HTTP API and the MCP face
escalator --version        tool, python, platform

阶梯

policy      robots.txt (cached) + rate limit  → may short-circuit (skip/deny/wait)
http        curl_cffi, impersonate=chrome     → ~100ms; clears undefended sites
http_proxy  same, routed via residential IP   → beats datacenter-IP bans
browser     nodriver, headless Chrome         → JS/SPA + Cloudflare-class defenses
                    │
                    └─ walled on the last rung? → status="challenged". Surrender.

有两件事让这不仅仅是一个 for 循环：

200 OK 并不代表成功。 返回 HTTP 200 但携带 Cloudflare 验证页的阶梯并没有成功。core/detect.py 在提取之后对每个响应进行分类——content、thin 或 blocked——只有 content 算数。没有这一点，阶梯就永远不会升级，缓存也会为一个永远返回垃圾内容的域名学到"http 可用"。

缓存会遗忘。 学到的起始阶梯如果只升不降，最终会把每个域名都推向浏览器+代理，悄悄推高你的代理账单。条目带有 learned_at 时间戳；超过 ladder.tier_cache_ttl_hours 后，域名会回退一级更便宜的阶梯重试。

关于为什么这样设计——以及它刻意拒绝做什么——请参阅 DESIGN.md。

配置

一个由 init 写入的配置文件，位于平台配置目录（Linux 上为 ~/.config/escalator/config.toml，macOS 上为 ~/Library/Application Support/escalator/config.toml）。使用 --config 覆盖位置。

所有场景下的优先级：

CLI flag  >  environment  >  config.toml  >  default

每个键都有对应的环境变量，Docker 镜像正是通过这种方式在没有任何配置文件的情况下完成配置的：

数据——SQLite 数据库和任何下载的浏览器——存放在平台数据目录中，可通过 ESCALATOR_STORAGE_DATA_DIR 覆盖。该目录之外不会写入任何内容。

浏览器从哪来

escalator browser list 按顺序显示查找过程：

1. 显式路径——先是 --browser-path，然后是 ESCALATOR_BROWSER_PATH，最后是 browser.path。如果设置了但错误，会报错并指明路径，绝不会静默跳过。

2. 本机安装的浏览器：先是真正的 Google Chrome，然后是 Chromium，再是 Edge 和 Brave。

3. 之前通过 escalator browser install 下载的浏览器。

如果以上都找不到，你会收到一条错误信息，其中包含修复它的两条命令。解析过程绝不会自行下载——服务器请求或 cron 作业不应有安装软件的副作用。

使用服务器

escalator serve   # 127.0.0.1:8000 by default

POST /scrape   {url, markdown?, min_tier?, max_tier?, timeout_ms?}  -> FetchResult
GET  /healthz                                                       -> {status, version}

使用 Authorization: Bearer <key> 进行身份验证，其中 key 是 server.api_keys 之一。该列表就是事实：移除一个 key，下次启动时即被撤销。没有用于生成 key 的端点。

验证墙返回 200 OK 并带有 {"status": "challenged"}，而不是 HTTP 错误。这是有意为之：另一端的代理可以对此做出反应。循环重试没有用——escalator 不解决验证码问题，这是设计使然。

使用 [mcp] 额外选项时，同一个阶梯会以工具的形式暴露在 /mcp 下：scrape_url(url, force_browser=False)。

故障排除

从这里开始：

escalator doctor

它会检查 Python、配置文件、数据目录、浏览器解析、实际的无头启动，以及——如果配置了代理——通过它发起一次真实请求，报告出口 IP 和国家（密码会被打码）。每个 ❌ 都会附带一条修复命令，如果任何检查失败，退出码为非零，因此脚本也可以使用它。escalator doctor --json 用于机器读取。

如果仍然无法解决，请将完整的 escalator doctor 输出粘贴到 issue 中——这正是它最后一行所要求的，也是获得答案的最快途径。

开发

参见 CONTRIBUTING.md。简而言之：uv sync、uv run pytest。

许可证

发布到公共领域——参见 UNLICENSE。无担保，无需署名，随意使用。