Crawl4AI CHANGELOG 深度解读：从 v0.2 到 0.9.0 的功能演进与安全加固全景

Crawl4AI 的 CHANGELOG.md 是一份完整记录该项目从 v0.2.4（2024-06）到 0.9.0（2026-06）全部重要变更的发布日志，涵盖内容提取策略重构、深度爬取、Docker API 服务端、LLM 集成与安全加固六大主线。本篇基于该日志逐版本梳理其演进脉络，重点解析 0.8.7–0.9.0 的安全硬化历程与 breaking changes 迁移要求，并结合仓库源码与配套迁移文档（deploy/docker/MIGRATION.md、cliff.toml）给出可操作的升级检查清单，帮助你在升级前准确评估影响范围。

一、CHANGELOG 的编写规范与生成方式

CHANGELOG.md 文件头部声明了其格式约定：

• 格式基于 Keep a Changelog，并遵循 Semantic Versioning 语义化版本规范；
• 每个版本条目包含 Added / Changed / Fixed / Security / Breaking Changes 等分组。

从仓库配置看，该日志由 git-cliff 基于 Conventional Commits 自动分组生成。cliff.toml 中的提交类型映射可以印证这一机制：

[git]
conventional_commits = true
filter_unconventional = true
commit_parsers = [
    { message = "^feat", group = "Added"},
    { message = "^fix", group = "Fixed"},
    { message = "^doc", group = "Documentation"},
    { message = "^perf", group = "Performance"},
    { message = "^refactor", group = "Changed"},
    ...
]

当前稳定版本号由 crawl4ai/version.py 声明，为 0.9.0，与日志中最新条目 ## [0.9.0] - 2026-06-18 一致。夜构建版本通过 __nightly_version__ 在构建期单独赋值，因此日志中出现的 Unreleased 段落（如 preserve_https_for_internal_links 配置项）代表尚未随稳定版发布的功能。

二、版本时间线总览

将 1777 行日志按主线归纳，可以勾勒出 Crawl4AI 从"轻量抓取库"到"LLM 友好爬取平台"的完整演进路径：

版本	时间	核心主题
0.2.x（0.2.4–0.2.77）	2024-06 ~ 2024-08	Selenium 时代：五阶段钩子（on_driver_created、before_get_url 等）、Docker Hub 官方镜像、transformer 模型替代 spaCy 的文本分块标注
0.3.x（0.3.5–0.3.75）	2024-09 ~ 2024-12	Playwright 迁移：AsyncWebCrawler、ManagedBrowser、CacheMode 缓存枚举、raw: / file:// 协议、BM25ContentFilter、PruningContentFilter、Docker API 服务化
0.4.x（0.4.1–0.4.3b2）	2024-12 ~ 2025-01	robots.txt 合规（SQLite 缓存）、代理配置、LLM 驱动 Schema 生成、redirected_url、MemoryAdaptiveDispatcher、流式处理
0.5.0（含 post5）	2025-02 ~ 2025-03	BrowserProfiler 身份浏览、深度爬取 max_pages / score_threshold、表格提取评分系统、LXML 抓取模式（breaking）
0.6.x（0.6.0–0.6.2）	2025-04	浏览器池化（页面预热、地理位置/时区控制）、网络与控制台日志捕获 + MHTML 导出、MCP 协议端点（socket/SSE）、RegexExtractionStrategy、CrawlResult.tables 独立字段
0.7.x	2025-06 ~ 2025-08	虚拟滚动 VirtualScrollConfig、AsyncUrlSeeder（sitemap + Common Crawl + BM25 相关性评分）、Undetected 隐身浏览器适配器、多 URL 配置系统、result.tables 接口
0.8.0	2026-01	修复 RCE（移除 __import__ 内置白名单）、init_scripts、CDP 连接改进、深度爬取崩溃恢复（resume_state / on_state_change）、Prefetch 两阶段深爬、HTTP 策略代理支持
0.8.7 / 0.8.8 / 0.8.9	2026-06	连续三个安全补丁版本：预授权 RCE、硬编码 JWT 密钥、SSRF、任意文件写等（详见第三节）
0.9.0	2026-06-18	Docker API 服务端"secure-by-default"大版本：默认鉴权、环回绑定、请求信任边界、声明式 hooks

三、0.9.0：secure-by-default 的 Docker API 服务端

这是整份日志中信息密度最高的条目。0.9.0 被明确定位为仅针对自托管 HTTP 服务端的 breaking 发布，pip 安装的核心库（SDK / 进程内用法）保持不变。其核心转变可以概括为一句话：从"信任调用方"（open, trust-the-caller）转向"默认拒绝"（closed, secure-by-default）。

3.1 默认行为变化

• 鉴权默认开启，环回绑定：服务端不再在 0.0.0.0 上提供无鉴权 API。未配置 token 时仅绑定 127.0.0.1 并打印一次性本地 token；要对外暴露必须设置 CRAWL4AI_API_TOKEN，且除 GET /health 外每个请求都需携带 Authorization: Bearer <token>；
• 请求信任边界：爬取请求体仅接受声明式标量选项。过去允许调用方驱动浏览器内部机制或执行任意代码的字段，现在在网络边界直接拒绝；
• 声明式 hooks 取代 hook 代码：任意 Python 钩子字符串被固定动作集合替代，请求中不再有用户代码。

配套的操作步骤（与 deploy/docker/MIGRATION.md 的 "Everyone (2 steps)" 一致）：

export CRAWL4AI_API_TOKEN="$(openssl rand -hex 32)"

随后通过 POST /token 重新签发所有旧 token（JWT 实现已变更，旧版本签发的 token 全部失效）。

3.2 请求体中被告知的字段清单

日志完整列出了经网络发送即被拒绝（HTTP 400）的字段：

js_code, js_code_before_wait, c4a_script, proxy / proxy_config,
extra_args, user_data_dir, cdp_url, cookies, headers, init_scripts,
base_url, deep_crawl_strategy, simulate_user, magic,
process_in_browser, 以及嵌套的 LLM 配置对象

未知字段被静默丢弃，而超时、viewport、滚动次数会被钳制到安全上限。这些能力并非被移除，而是"移到服务端配置或改用进程内 SDK"——CRAWL4AI_API_TOKEN 之外的对应配置都应写在服务端环境或配置文件中。

3.3 声明式 hooks 与 artifact 化输出

旧的 hooks.code（Python 字符串）被五个固定动作替代：block_resources、add_cookies、set_headers、scroll_to_bottom、wait_for_timeout。deploy/docker/MIGRATION.md 给出了请求体示例：

{
  "hooks": {
    "hooks": [
      {"action": "block_resources", "params": {"resource_types": ["image", "font"]}},
      {"action": "scroll_to_bottom",  "params": {"max_steps": 10, "delay_ms": 500}}
    ]
  }
}

可用参数 schema 可通过 GET /hooks/info 查询。

同时，/screenshot 与 /pdf 端点的 output_path 参数被移除，改为返回 artifact_id + URL，经认证的 GET /artifacts/{artifact_id} 拉取文件（受 TTL 与配额约束）。LLM 端点 /md、/llm、/llm/job 则只能按名称选择 provider，端点与密钥一律服务端配置，并受 config.llm.allowed_providers 约束。

其余硬化项包括：CORS 默认拒绝（需列入 security.cors_allow_origins）、TLS 校验默认开启（内部测试逃生门为 CRAWL4AI_ALLOW_INSECURE_TLS=true / CRAWL4AI_ALLOW_INTERNAL_URLS=true）、webhook 头部校验（畸形或 hop-by-hop/敏感头返回 422）、容器内 Redis 改为环回 + 密码且不对外发布端口、后台作业队列有界化（请求体大小、单次爬取墙钟时间、队列深度、每主体并发均可配置，0 = 不限制）、5xx 响应统一为 {"error": "Internal server error", "correlation_id": "…"} 并可在日志中按 correlation id 追踪详情。

四、安全演进线：0.8.7 → 0.9.0 的漏洞与修复

日志的 0.8.7 至 0.9.0 四个版本构成一条清晰的安全加固链，且每条修复都标注了 CWE 编号、CVSS 分值与报告者（完整致谢见 SECURITY-CREDITS.md）。

4.1 0.8.7（2026-06-01）：批量修复既有披露漏洞

• CRITICAL 级（CVSS 9.8）：
  • 计算字段 eval() 路径上的 AST 沙箱逃逸（gi_frame.f_back 帧链逃逸，CWE-94/913）——修复方式是彻底移除计算字段中的 eval() 并删除 _safe_eval_expression；
  • Hook 沙箱逃逸 RCE：注入的模块对象（asyncio、json、re）携带完整 __builtins__，绕过 __import__ 拦截——修复为剥离注入内置、移除危险白名单项；
  • 硬编码 JWT 密钥（默认签名密钥 "mysecret" 可伪造 token，CWE-798）——移除默认值、拒绝弱密钥、未设密钥时自动生成临时密钥。
• HIGH 级：output_path 任意文件写（CVSS 9.1，CWE-22，限定写入 CRAWL4AI_OUTPUT_DIR 并拒绝 .. 穿越）；webhook URL SSRF（CVSS 8.6，增加拦截清单 + follow_redirects=False）；/crawl、/md、/llm 端点 SSRF（IPv6 映射 IPv4 绕过问题，归一化后再过拦截清单）；/execute_js 任意 JS 执行（CVSS 8.1，默认关闭，CRAWL4AI_EXECUTE_JS_ENABLED 控制）。
• MEDIUM 级：Monitor 端点鉴权绕过（补 token_dep）、Monitor 仪表盘存储型 XSS（服务端 html.escape() + 客户端 escapeHtml()）。

同版本还带来了 DomainMapper（域级 URL 发现，支持 include_subdomains 与分源超时，实现见 crawl4ai/domain_mapper.py）、Docker API 的 arun_many 按 URL 配置列表支持（#1837），以及一批抓取保真度修复：mermaid 图表从 SVG 中保留文本（#1043）、表格 rowspan/colspan 保留（#1920）、NlpSentenceChunking 语句顺序（#1909）、深爬流式 ContextVar bug（#1917）等。

4.2 0.8.8（2026-06-04）：SSRF 过滤缺口与凭据外泄

向后兼容的补丁版本，四组修复：

• SSRF 过滤缺口（CWE-918）：拦截清单此前只覆盖显式地址，NAT64（64:ff9b::/96）、6to4（2002::/16）、IPv4-mapped 与未指定地址 :: 等 IPv6 过渡形态可绕过；现改为拒绝任何"非全局可路由"的解析地址，且错误信息不再回显解析结果；
• output_path 符号链接/TOCTOU 绕过（CWE-59/22）：写前解析符号链接、复检包含关系并使用 O_NOFOLLOW；
• LLM 凭据外泄（CWE-522/200）：/md、/llm、/llm/job 忽略请求方传入的 base_url，配置好的 provider key 无法被重定向到攻击者端点；LLMConfig 同时拒绝通过 env: token 形式解析受保护环境变量；
• CRLF 安全日志（CWE-117）与 webhook 请求头校验（CWE-93）：日志记录剥离 CR/LF 与控制字符；webhook 头部校验名称模式、禁控制字符、拒绝 hop-by-hop/敏感头。

4.3 0.8.9（2026-06-04）：代理路径上的 SSRF

0.8.8 未覆盖的最后一类 SSRF：SSRF 目标校验只作用于爬取目标 URL，而代理地址不受校验。未认证的 /crawl、/crawl/stream、/crawl/job 可将 browser_config.proxy_config.server（或弃用的 browser_config.proxy、crawler_config.proxy_config、extra_args 中的 --proxy-server / --host-resolver-rules 标志）指向内网地址，让浏览器经代理触达内网服务与云元数据端点。修复后所有代理目标在建浏览器前经过同一"全局可路由"校验，且代理/DNS 重定向类标志从 extra_args 中剥离。注意：裸 --proxy-server、--host-resolver-rules、--proxy-bypass-list、--proxy-pac-url 标志从此被忽略，代理应通过受校验的 proxy_config 配置。

4.4 0.9.0：从缓解到架构

0.9.0 把剩余问题从"缓解"升级为"架构级消除"，日志中记录了三项带 CWE 编号的修复：

• 下载路径约束（CWE-22）：两个下载落点均改为 basename + realpath + O_NOFOLLOW，关闭"路径穿越到任意文件写"这一类；
• 流式爬取路径 SSRF（CWE-918）：/crawl/stream 与 stream=true 的 /crawl 现在也校验目标，非允许目标返回 HTTP 400，与非流式处理器对齐；
• 拒绝请求方 browser_config.extra_args（CWE-94）：Chromium 启动参数不能再经网络传入，关闭启动参数注入类风险。

这一演进路径本身即有参考价值：0.8.0 修复"沙箱内可执行代码"→ 0.8.7 修复"沙箱逃逸与凭据"→ 0.8.8/0.8.9 收口"网络可达性边界"→ 0.9.0 用默认鉴权 + 信任边界 + 声明式配置重建服务端架构。自托管 Docker 服务端的用户应依次阅读 deploy/docker/MIGRATION.md（分步迁移）与 deploy/docker/SECURITY-VERIFY.md（部署核查清单）。

五、SDK 核心功能演进线

安全线之外，日志记录的另一条主线是 SDK 能力的持续扩张。以下选取各版本中具有代表性的能力，均标注了日志出处。

5.1 内容提取与过滤策略的三次重构

1. v0.3.72：引入 ContentCleaningStrategy，基于文本密度与元素评分做智能内容抽取，同时新增 fit_markdown / fit_html 输出形态；

2. v0.3.74：RelevanceContentFilter（实现 BM25ContentFilter）取代 Fit Markdown 作为内容清理策略，fit_markdown 标志按标题、meta description、关键词过滤内容。日志给出的用法示例：

   from crawl4ai import AsyncWebCrawler
   from crawl4ai.content_filter_strategy import BM25ContentFilter
   
   async def filter_content(url, query):
       async with AsyncWebCrawler() as crawler:
           content_filter = BM25ContentFilter(user_query=query)
           result = await crawler.arun(url=url, extraction_strategy=content_filter, fit_markdown=True)
           print(result.extracted_content)
           print(result.fit_html)
   

3. v0.3.75：再增 PruningContentFilter，按文本与链接密度剪除低相关节点，配套测试见 tests/async/test_content_filter_prune.py 与 tests/async/test_content_filter_bm25.py；

4. 0.6.2：无 LLM 的 RegexExtractionStrategy（内置 email/URL/电话/日期模式，支持自定义正则，另有 generate_pattern 供一次性 LLM 辅助生成模式）；

5. Unreleased：preserve_https_for_internal_links 配置项（默认 False），防止深度爬取中内链被降级到 HTTP（修复 #1410）。

5.2 浏览器管理与深爬能力

• v0.3.73：ManagedBrowser 生命周期管理、CDP 端点连接、用户数据目录持久化、HTML 转 Markdown 的 preserve_tags、弹窗/遮罩自动移除（remove_overlay_elements）、screenshot_wait_for；

• v0.3.74：文件下载处理（accept_downloads、downloads_path，成功文件记录于 CrawlResult.downloaded_files）、raw: / file:// 协议支持、CacheMode 枚举（ENABLED / DISABLED / READ_ONLY / WRITE_ONLY / BYPASS）取代 bypass_cache、no_cache_read 等布尔标志。日志附迁移示例：

  # 旧写法
  crawler = AsyncWebCrawler(always_by_pass_cache=True)
  result = await crawler.arun(url="https://example.com", bypass_cache=True)
  
  # 新写法
  from crawl4ai import CacheMode
  crawler = AsyncWebCrawler(always_bypass_cache=True)
  result = await crawler.arun(url="https://example.com", cache_mode=CacheMode.BYPASS)
  

• v0.3.71：HTML 解析器从 html.parser 切换到 lxml（日志称带来约 4 倍性能提升）；

• 0.5.0：BrowserProfiler 专职浏览器 profile 管理（从 ManagedBrowser 拆分而来）、CLI 交互式 profile 管理、深度爬取 max_pages 与 score_threshold；同版本将 license 更新为 Apache 2.0 + 署名条款（任何公开使用或分发需明确署名，完整法律文本见 LICENSE）；

• 0.7.x：VirtualScrollConfig 处理"内容被替换式"虚拟滚动（Twitter/Instagram 风格），自动识别三种滚动场景（内容不变/内容追加/内容替换），基于归一化文本去重；AsyncUrlSeeder 支持从 sitemap 与 Common Crawl 索引发现 URL、BM25 查询相关性评分、many_urls() 多域并行发现，配套示例见 docs/examples/url_seeder/url_seeder_demo.py；

• 0.7.3：Undetected 隐身浏览器适配器（browser_adapter.py，支持无头隐身与类人行为模拟）、多 URL 配置系统（字符串通配、lambda 匹配器、AND/OR 混合匹配、fallback 配置）、memory_utils.py 内存监控；

• 0.8.0：init_scripts 页面加载前 JS 注入（面向反检测）、CDP WebSocket URL 支持与浏览器复用、深度爬取崩溃恢复（BFS/DFS/Best-First 策略的 resume_state 与 on_state_change）、Prefetch 两阶段深爬（快速链接提取）、HTTP 策略代理支持、process_in_browser 让 raw:/file:// 走浏览器管线、sitemap seeder 的 cache_ttl_hours 与 validate_sitemap_lastmod 智能 TTL 缓存。

5.3 服务端与基础设施演进

• v0.3.73：Docker 化 API 服务落地；v0.3.746 引入平台区分镜像命令（basic-amd64 / all-arm64 / gpu-amd64 等）；
• v0.3.74：API 服务端引入 CRAWL4AI_API_TOKEN 鉴权与 /crawl_sync、/crawl_direct 端点（这是鉴权概念的早期形态，0.9.0 将其变为默认强制）；
• 0.5.0：引入 MemoryAdaptiveDispatcher、SemaphoreDispatcher、RateLimiter 与 CrawlerMonitor，深度爬取模块化为独立包（deep_crawling/，现仓库中对应 crawl4ai/deep_crawling/）；
• 0.6.0：浏览器池化（页面预热 + 地理/时区/locale 细粒度控制）、网络与控制台日志捕获、MHTML 导出、MCP 协议端点（socket 与 SSE 双传输，测试见 tests/mcp/）、ProxyConfig 迁入 async_configs、旧 crawl4ai/browser/* 模块移除（升级到 0.6.0 需按日志 Upgrade notes 调整直接 import）；
• 0.8.7：AsyncLogger 默认输出到 stderr（#1968）、MCP 桥 ensure_ascii=False 保留 CJK（#1967）、arun() 返回类型修正为 CrawlResultContainer（#1898）；
• 0.4.3b2：robots.txt 合规（check_robots_txt 参数 + SQLite 缓存 + 403 状态码）、redirected_url 重定向跟踪、shared_data 钩子间传参、LLM 驱动的 CSS/XPath schema 自动生成（OpenAI/Ollama）。

六、升级实践：从日志到检查清单

结合整份 CHANGELOG 的 breaking changes 标注，可以提炼出四条实操原则：

1. 区分作用域：0.8.7 的 CRITICAL 修复（RCE、JWT 密钥）与 0.9.0 的 breaking changes 只影响自托管 Docker 服务端；pip 库用户升级时主要关注 API 层面变化（如 0.6.0 的 crawl4ai/browser/* import 移除、0.7.3 的 result.media → result.tables 迁移）；
2. 按"影响功能"定位迁移项：deploy/docker/MIGRATION.md 将迁移工作拆成"所有人都要做的 2 步"（设 CRAWL4AI_API_TOKEN、重签 token）与"仅当用过该功能才需处理"的分项——请求体字段被拒、hooks 声明化、artifact 化输出、LLM 按名选 provider、CORS 白名单、TLS 校验、Redis 密码、队列限额；
3. 在 staging 环境先行验证：0.9.0 日志明确要求"在 staging 先测再升级"，部署核查见 deploy/docker/SECURITY-VERIFY.md；
4. 关注 Unreleased 段落与测试回归：日志中的 issue 编号（#1837、#1043、#1917 等）与仓库内回归测试目录（如 tests/regression/、tests/docker/）可以互相印证，升级前用对应测试套件跑一遍是最可靠的验证方式。

七、如何维护与阅读这份 CHANGELOG

• 新增条目遵循 Keep a Changelog 分组；提交信息遵循 Conventional Commits（feat / fix / doc / perf / refactor 等前缀），cliff.toml 负责把提交映射到 Added / Fixed / Documentation 等分组，chore(release): prepare for 类提交被跳过；
• 安全类条目保持"漏洞描述 + CWE/CVSS + 修复方式 + 报告者署名"四要素，所有报告者的联系方式与报告日期汇总在 SECURITY-CREDITS.md；
• 版本号以 crawl4ai/version.py 为准，当前为 0.9.0；带具体日期的版本头（如 ## [0.9.0] - 2026-06-18）为正式发布，## [Unreleased] 为待发功能。

对 LLM 与 Agent 而言，这份日志也是极佳的项目语义索引：每个功能条目都保留了参数名（accept_downloads、cache_mode、init_scripts、resume_state）、类名（BM25ContentFilter、BrowserProfiler、AsyncUrlSeeder）与端点名（/crawl/stream、/hooks/info、/artifacts/{id}），可直接作为代码定位与升级决策的检索入口。