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

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

【免费下载链接】crawl4ai🚀🤖 Crawl4AI: Open-source LLM Friendly Web Crawler & Scraper. Don't be shy, join here: https://discord.gg/jP8KfhDhyN项目地址: https://gitcode.com/GitHub_Trending/craw/crawl4ai

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 内容提取与过滤策略的三次重构

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

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)

v0.3.75：再增PruningContentFilter，按文本与链接密度剪除低相关节点，配套测试见 tests/async/test_content_filter_prune.py 与 tests/async/test_content_filter_bm25.py；
0.6.2：无 LLM 的RegexExtractionStrategy（内置 email/URL/电话/日期模式，支持自定义正则，另有generate_pattern供一次性 LLM 辅助生成模式）；
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 标注，可以提炼出四条实操原则：

区分作用域：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迁移）；
按"影响功能"定位迁移项：deploy/docker/MIGRATION.md 将迁移工作拆成"所有人都要做的 2 步"（设CRAWL4AI_API_TOKEN、重签 token）与"仅当用过该功能才需处理"的分项——请求体字段被拒、hooks 声明化、artifact 化输出、LLM 按名选 provider、CORS 白名单、TLS 校验、Redis 密码、队列限额；
在 staging 环境先行验证：0.9.0 日志明确要求"在 staging 先测再升级"，部署核查见 deploy/docker/SECURITY-VERIFY.md；
关注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}），可直接作为代码定位与升级决策的检索入口。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

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