crawlrs 0.2.0

crawlrs - Enterprise-grade web scraping and crawling platform built with Rust
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
<div align="center">

<img src="docs/image/crawlrs.png" alt="Crawlrs Logo" width="240">

[![Rust 2021](https://img.shields.io/badge/Rust-2021-edded?logo=rust&style=for-the-badge)](https://www.rust-lang.org/) [![Rustc 1.97.1+](https://img.shields.io/badge/Rustc-1.97.1+-orange.svg?style=for-the-badge)](https://www.rust-lang.org/) [![release](https://img.shields.io/github/v/release/Kirky-X/crawlrs?style=for-the-badge)](https://github.com/Kirky-X/crawlrs/releases) [![CI](https://img.shields.io/github/actions/workflow/status/Kirky-X/crawlrs/ci.yml?branch=main&label=CI&style=for-the-badge)](https://github.com/Kirky-X/crawlrs/actions/workflows/ci.yml) [![license](https://img.shields.io/github/license/Kirky-X/crawlrs?style=for-the-badge)](https://github.com/Kirky-X/crawlrs/blob/main/LICENSE)

**中文** | [English](README_EN.md)

**使用 Rust 构建的企业级网页数据采集平台**

[✨ 功能特性](#-功能特性) • [🚀 快速开始](#-快速开始) • [📚 文档](#-文档) • [💻 示例](#-示例) • [🤝 参与贡献](#-参与贡献)

</div>

---

<div align="center">

### 🎯 一句话下发任务,五引擎接力执行

通过统一 REST API 派发任务,引擎调度、反爬与限流由 crawlrs 自动接管:

<table style="width:100%; border-collapse: collapse">
<tr>
<td align="center" width="25%">📮<br><b>任务接入</b><br><span style="color:#64748B">同步 · 异步 · 批量</span></td>
<td align="center" width="25%">🚂<br><b>自动选路</b><br><span style="color:#64748B">混合调度 · 竞速 · 降级</span></td>
<td align="center" width="25%">🛡️<br><b>反爬升级</b><br><span style="color:#64748B">探测 · 伪装 · 重试 · 代理</span></td>
<td align="center" width="25%">🧠<br><b>AI 增强</b><br><span style="color:#64748B">RAG · 图谱 · DRL</span></td>
</tr>
</table>

</div>

---

## 📋 目录

<details open>
<summary>📑 目录</summary>

- [✨ 功能特性](#-功能特性)
- [🚀 快速开始](#-快速开始)
- [🎨 特性标志](#-特性标志)
- [🔌 作为库依赖](#-作为库依赖)
- [📚 文档](#-文档)
- [💻 示例](#-示例)
- [🚢 部署](#-部署)
- [🏗️ 架构](#️-架构)
- [🧪 测试](#-测试)
- [📊 性能](#-性能)
- [🔒 安全](#-安全)
- [🗺️ 开发路线图](#️-开发路线图)
- [🤝 参与贡献](#-参与贡献)
- [📋 更新日志](#-更新日志)
- [📄 许可证](#-许可证)
- [🙏 致谢](#-致谢)
- [📞 联系与支持](#-联系与支持)
- [⭐ Star 历史](#-star-历史)

</details>

---

## ✨ 功能特性

<table style="width:100%; border-collapse: collapse">
<tr>
<td width="50%" style="vertical-align:top; padding: 12px">🔍 <b>统一搜索</b><br><span style="color:#64748B">Bing、百度、搜狗多引擎聚合,RRF 融合排序 + SimHash 跨引擎去重,Exa / Tavily 按凭据自动注册,SearXNG 公共实例池按配置启用(opt-in),结果统一格式</span></td>
<td width="50%" style="vertical-align:top; padding: 12px">🎯 <b>单页抓取</b><br><span style="color:#64748B">静态 HTML 与 JS 渲染页面统一抓取,支持截图、表单交互、自定义请求头与同步等待;Playwright 引擎可捕获页面 XHR/Fetch 后台响应</span></td>
</tr>
<tr>
<td width="50%" style="vertical-align:top; padding: 12px">🕷️ <b>深度爬取</b><br><span style="color:#64748B">URL 过滤链 + 复合评分器 + 优先级队列 + 自适应停止条件,robots.txt 合规(Crawl-delay 双时钟);sitemap 流式请求源、软 404 指纹剔除、断点续爬 seen 预热</span></td>
<td width="50%" style="vertical-align:top; padding: 12px">📊 <b>数据提取</b><br><span style="color:#64748B">CSS 规则、正文提取器(Trafilatura / DomSmoothie)、LLM 与 RAG 增强多种提取模式;降级阶梯质量门、LLM 长文分块并行、提取结果字符级溯源</span></td>
</tr>
<tr>
<td width="50%" style="vertical-align:top; padding: 12px">🚂 <b>五引擎智能路由</b><br><span style="color:#64748B">Reqwest / Playwright / FlareSolverr / Wreq(TLS 指纹)/ MLLM(视觉 LLM 导航 + 混合 AX 树快照)/ Moli(可选,内存水位调度下低配机的 JS 渲染回退位),SmartHybrid、竞速与顺序降级三种路由策略</span></td>
<td width="50%" style="vertical-align:top; padding: 12px">🛡️ <b>反爬对抗</b><br><span style="color:#64748B">三层反爬检测、SPA 空壳探测升级、UA 池一致性伪装、智能重试、代理轮换、请求合并;Session 身份三件套记分退休、AutoThrottle 自适应限速、429 指数退避</span></td>
</tr>
<tr>
<td width="50%" style="vertical-align:top; padding: 12px">🏢 <b>企业平台能力</b><br><span style="color:#64748B">多租户隔离、garrison 认证(RBAC + JWT + 防暴力破解)、limiteron 限流熔断、Webhook 事件通知</span></td>
<td width="50%" style="vertical-align:top; padding: 12px">📈 <b>可观测性</b><br><span style="color:#64748B">Prometheus 指标导出(队列深度、引擎成功率、缓存命中等)、inklog 结构化日志、审计日志、失败现场快照(错误签名去重存档)</span></td>
</tr>
<tr>
<td width="50%" style="vertical-align:top; padding: 12px">🧠 <b>智能增强</b><br><span style="color:#64748B">RAG 增强提取、知识图谱覆盖感知爬取、DRL 自适应策略(ONNX 推理 + 启发式退化)</span></td>
<td width="50%" style="vertical-align:top; padding: 12px">🧩 <b>特性门控裁剪</b><br><span style="color:#64748B">20+ Cargo features 按需组合,<code>agent-lib</code> 提供嵌入式最小库面,全部业务能力可关闭并注入 Noop 实现</span></td>
</tr>
</table>

除上述核心能力外,crawlrs 还提供站点映射、异步任务队列(Worker 模式)、多层缓存与代理支持等能力;引擎级增强模块(反爬对抗、智能增强等)的设计与代码位置详见 [🏗️ 架构文档](docs/ARCHITECTURE.md)。

---

## 🚀 快速开始

### 📦 安装

<details>
<summary>📄 代码 · bash</summary>

```bash
git clone https://github.com/Kirky-X/crawlrs.git
cd crawlrs

# 默认特性构建(platform 全套业务能力 + db-postgres)
cargo build --release

# 生产推荐:默认 + Playwright 引擎 + 指标 + 内容处理
cargo build --release --features standard

# 全功能组合(standard + FlareSolverr + 正文提取 + LLM 边界;不含 vision/MLLM)
cargo build --release --features full
```

</details>

要求 Rust 1.97.1 及以上(`Cargo.toml` 的 `rust-version`,最新稳定版即可);默认数据库后端为 PostgreSQL 16+(`db-postgres`);Docker 20+ 用于集成测试(testcontainers)与容器化部署。

### 💡 最小示例

以下示例改编自 [`config/default.toml`](config/default.toml) 配置模板与 [📖 用户指南](docs/USER_GUIDE.md) 的启动流程:

<details>
<summary>📄 代码 · bash</summary>

```bash
# 1. 准备配置(完整模板见 config/default.toml,环境变量见 .env.example)
cat > config/default.toml <<'EOF'
[database]
url = "postgresql://user:password@localhost/crawlrs"

[server]
host = "0.0.0.0"
port = 8899
EOF

# 2. 初始化数据库(服务启动不自动迁移;migrate 按数据库特性选择 migrations/<dialect>/ 并有序应用)
cargo run --bin crawlrs migrate
# 迁移根目录缺省 ./migrations,可用 CRAWLRS_MIGRATIONS_DIR 覆盖;
# 也可手工应用 PostgreSQL 套:for f in migrations/postgres/*.sql; do psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -q -f "$f"; done

# 3. 启动服务(API 模式;worker 模式:cargo run --bin crawlrs worker)
cargo run --bin crawlrs
```

</details>

<details>
<summary>📄 代码 · bash</summary>

```bash
# 4. 验证安装
curl http://localhost:8899/health
# {"status":"healthy","version":"0.2.0"}
```

</details>

调用抓取接口(认证与全部端点详见 [📘 API 参考](docs/API_REFERENCE.md)):

<details>
<summary>📄 代码 · bash</summary>

```bash
curl -X POST http://localhost:8899/v1/scrape \
  -H "Authorization: Bearer <garrison_key_id>.<garrison_secret>" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'
```

</details>

### 🧭 核心概念

- **引擎与路由**:`EngineClient` 是抓取操作唯一公开入口,内部 `EngineRouter` 持有 `Vec<Arc<dyn ScraperEngine>>`,按 `SmartHybrid`(默认)/ `RaceMode` / `SequentialFallback` 策略选择引擎。
- **四种运行形态**:同一二进制按子命令分派(`src/main.rs`)——`crawlrs` 或 `crawlrs api`(默认)启动 API 服务,`crawlrs worker` 以 Worker 模式消费任务队列,`crawlrs bootstrap` 初始化默认团队与 admin API Key,`crawlrs migrate` 按编译启用的数据库特性选择 `migrations/postgres|sqlite|mysql/` 并有序应用。
- **DDD 四层**:`presentation → application → domain → infrastructure`,DI 由 trait-kit 的各 capability Module(`SettingsModule`/`CacheModule`/`EngineModule` 等)装配。
- **配置管理**:基于 confers,TOML 文件 + `CRAWLRS__` 前缀环境变量(`__` 分隔嵌套,如 `CRAWLRS__DATABASE__URL`)。
- **SearXNG 元搜索(opt-in)**:默认 `search.searxng.enabled = false`;启用后从 searx.space 采集公共实例写入 `searxng_instances` 登记簿,周期探活维护进程内热池(目标 3 个可用实例),请求失败自动熔断换实例;同一搜索请求最多换 `max_failover_attempts` 个实例。

<details>
<summary>📄 代码 · toml</summary>

  ```toml
  [search.searxng]
  enabled = true                                # 启用后拉起采集/探活两个周期 worker
  pool_target = 3
  seed_urls = ["https://searx.example.org"]     # 数据源不可达时的兜底实例
  ```

</details>

  **隐私披露**:启用后用户查询明文会发送给第三方公共 SearXNG 实例(非本部署控制)。默认关闭即为缓解;实例治理视图见 `GET /v1/searxng/instances` 与 `GET /v1/searxng/pool`。
- **特性门控**:业务能力(teams/auth/rate-limit/webhook)关闭时自动注入 Noop 实现,单租户/无认证部署零业务逻辑改动。

---

## 🎨 特性标志

### 📦 功能预设

<details>
<summary>📋 表格</summary>

| 预设 | 构建命令 | 包含内容 | 适用场景 |
|------|----------|----------|----------|
| 默认 | `cargo build --release` | `platform`(teams + auth + rate-limit + webhook + metrics + content + sitemap)+ `db-postgres` | 开箱即用的完整平台 |
| `standard` | `cargo build --release --features standard` | 默认 + `engine-playwright` + `sitemap` | 生产推荐(JS 渲染 + 指标 + 内容处理 + 站点地图) |
| `full` | `cargo build --release --features full` | `standard` + `engine-flaresolverr` + `extractors` + `llm` | 全功能组合(不含 vision/MLLM,需另加 `engine-mllm`) |
| `no-default` | `cargo build --release --no-default-features` | 纯核心抓取栈 | 单租户/无认证部署、嵌入集成 |
| `agent-lib` | `cargo build --release --no-default-features --features agent-lib` | `content` + `trafilatura` + `dom-smoothie` | agent/嵌入式最小库面 |

</details>

### 📋 功能矩阵

下表为 `Cargo.toml` `[features]` 的主要特性子集(完整清单见 `Cargo.toml`),`default = ["platform", "db-postgres"]`;核心抓取栈(oxcache / dbnexus / confers / sdforge / inklog / trait-kit + scraper / reqwest / robotstxt)始终编译。

<details>
<summary>📋 表格</summary>

| 特性 | 说明 | 默认 |
|------|------|------|
| `teams` | 多租户隔离(隐含 `auth`);关闭时归属 `DEFAULT_TEAM_ID` 单租户 | ✅ |
| `auth` | garrison v0.9 认证(RBAC + JWT + 防暴力破解);关闭时注入固定身份 | ✅ |
| `rate-limit` | limiteron 限流熔断;关闭时注入 `NoopRateLimitingService` | ✅ |
| `webhook` | Webhook 投递;关闭时移除 `/v1/webhooks` 路由并注入 Noop | ✅ |
| `metrics` | Prometheus 指标导出(含 sysinfo 内存感知) | ✅(platform) |
| `content` | 反爬检测(aho-corasick)+ HTML→Markdown 转换(alchemize html 引擎为默认;htmd 直通诊断臂) | ✅(platform) |
| `db-postgres` / `db-sqlite` / `db-mysql` | 数据库驱动三选一(dbnexus 编译期互斥强制) | ✅ postgres |
| `engine-playwright` | chromiumoxide 浏览器自动化引擎 | ❌ |
| `engine-flaresolverr` | FlareSolverr 反爬引擎(Full/Cdp/Tls 三模式) | ❌ |
| `engine-tls-fingerprint` | WreqEngine TLS 指纹伪装(BoringSSL JA3/JA4) | ❌ |
| `engine-mllm` | MLLM 视觉 LLM 自主导航引擎(隐含 `engine-playwright` + `llm`;视觉面经 fluxweir chat) | ❌ |
| `engine-moli` | MoliEngine(CDP 控制外部 `moli serve` 的纯 Rust 无头内核)+ 内存水位调度器(sysinfo 三档:Abundant/Tight/Critical 驱动引擎优先级与 Playwright 池门控) | ❌ |
| `trafilatura` / `dom-smoothie` / `extractors` | 正文提取主路径 / 性能回退 / 全启用 | ❌ |
| `llm` | LLM 提取边界(trait + 编排;供应商访问由宿主 carrier 注入) | ❌ |
| `sitemap` | 站点地图生成(`/v1/map` 端点) | ✅(platform/standard) |
| `rag-local` | 本地 RAG 嵌入与重排(vecboost) | ❌ |
| `rag` | RAG 组合包(`rag-local` + `gateway`) | ❌ |
| `openapi` | OpenAPI 3.1 规范生成(`GET /openapi.json`) | ❌ |
| `test-mocks` | 测试专用 mock 门控(集成测试需显式启用) | ❌ |

</details>

> 特性组合的编译矩阵(22 组合)与验证方式见 [🧪 测试场景矩阵](docs/TEST_SCENARIOS.md);特性门控的实现模式见 [🏗️ 架构文档 · Feature Gate Architecture](docs/ARCHITECTURE.md)。

---

## 🔌 作为库依赖

crawlrs 可作为库被下游项目(如网关类应用)以 **path 依赖**嵌入,获得抓取引擎 / 正文提取 / RAG 能力。受支持的嵌入方式如下。

### 嵌入 feature 组合

以 path 依赖引入 crawlrs 时,按下表声明 feature 组合(引擎默认集随 `default-features` 自动带入 `platform` + `db-postgres`):

<details>
<summary>📄 代码 · toml</summary>

```toml
[dependencies]
crawlrs = { path = "../crawlrs", features = ["db-postgres", "extractors", "llm"] }
```

</details>

<details>
<summary>📋 表格</summary>

| feature | 说明 | 是否 default |
|---------|------|:-----------:|
| `db-postgres` | PostgreSQL 后端(嵌入主存储路径) | ✅ default 已含 |
| `extractors` | 正文提取(`trafilatura` + `dom-smoothie`) | 显式声明 |
| `llm` | LLM 结构化提取边界(trait + 编排,不含供应商访问;carrier 由宿主注入) | 显式声明 |

</details>

> RAG(`vecboost`,走 `rag-local`+`gateway`)与 TLS 指纹引擎(`wreq`,走 `engine-tls-fingerprint`)**不在**受支持的默认嵌入组合内——它们会引入额外的重构建链(tokenizers 或 BoringSSL),需按各自 feature 单独验证。

### LLM 承载注入模型

crawlrs 不再内置任何 LLM 供应商访问(原 `LLMService` / `provider_adapter` / `llm_provider_strategy` 已删除),`LLMServiceTrait` 是唯一 LLM 边界。宿主经以下任一 pub 装配路径注入自有实现(如 fluxgate 的 `FluxgateLLMCarrier`):

1. `Services.llm_service` pub 字段直接赋值;
2. 以自有工厂替换 `init_llm_service`;
3. 经 `CrawlRsState::from_kit` 的装配面注入。

未注入时默认装配 `ExplicitErrorCarrier`:任何 LLM 调用返回 i18n 双语结构化错误(`domain-error-llm-carrier-not-injected`),不 panic、不静默降级。`prompt_builder` / `chunker`(F8)/ `provenance`(F9)编排模块保留,注入 carrier 可复用。

### 依赖版本统一基线

嵌入方与 crawlrs 共享同一组 nexus 家族依赖,全部为稳定版 minor 精度 requirement(`"0.6"` 形式,patch 由解析面取最新)。crawlrs 的 manifest 最低版本已抬升至下表基线,使「单仓 CI 基线 = 嵌入编译目标」,避免「单仓绿、嵌入红」在上游升级时复发:

<details>
<summary>📋 表格</summary>

| 依赖 | 统一基线 | 嵌入角色 |
|------|---------|---------|
| `dbnexus` | `0.6.1` | 数据库抽象(sea-orm 之上) |
| `inklog` | `0.3` | 日志(`log::` facade 后端) |
| `limiteron` | `0.3` | 限流 / 熔断 / 退避 |
| `confers` | `0.6` | 配置加载 |
| `trait-kit` | `0.5` | 异步 DI(AsyncKit) |
| `oxcache` | `0.5` | 多级缓存 |
| `garrison` | `0.9` | 认证引擎(经 default 的 `auth` 引入) |

</details>

> 嵌入方不得依赖 `[patch.crates-io]` 强制对齐版本——patch 属本地开发态机制,发布面禁用(path 版与 registry 版并存会触发 trait 身份分裂)。抬版本只保证「同一版本下编译与测试等价通过」,不改变运行行为。

### 嵌入探针门禁

`scripts/embed-probe.sh` 在临时目录以 path 依赖复现嵌入编译路径(`cargo new` 探针 crate → `cargo add --path <仓库根> --features "db-postgres,extractors,llm"` → `cargo check`),嵌入破坏在仓内即可发现;CI 的 `embed-probe` job 会串行执行该脚本并阻塞合并。

<details>
<summary>📄 代码 · bash</summary>

```bash
scripts/embed-probe.sh              # 自动定位仓库根(由脚本自身位置推导)
scripts/embed-probe.sh <repo-root>  # 显式指定仓库根(跨机器 / CI)
```

</details>

退出码 `0` 表示嵌入编译面完好;非零时 stderr 打印失败步骤名(`root` / `new` / `add` / `check`)。探针构建产物落在 `mktemp` 临时目录,不污染仓库工作区,可重复执行。

---

## 📚 文档

<details>
<summary>📋 表格</summary>

| 文档 | 说明 |
|------|------|
| [📖 用户指南](docs/USER_GUIDE.md) | 认证、抓取、爬取、搜索、提取、Webhook、团队等全部功能的完整教程 |
| [📘 API 参考](docs/API_REFERENCE.md) | 全部 REST 端点、请求/响应格式、错误码与 SDK |
| [🏗️ 架构文档](docs/ARCHITECTURE.md) | DDD 分层、引擎路由、增强模块、安全模型与部署拓扑 |
| [⚡ 性能指南](docs/PERFORMANCE.md) | 基准套件、性能观测与调优建议 |
| [🔒 安全文档](docs/SECURITY.md) | 安全设计、供应链门禁、漏洞报告流程与生产加固清单 |
| [❓ FAQ](docs/FAQ.md) | 常见问题解答 |
| [🧪 测试场景矩阵](docs/TEST_SCENARIOS.md) | 测试套件穷举、特性组合矩阵与运行手册 |
| [🤝 贡献指南](docs/CONTRIBUTING.md) | 环境搭建、开发工作流与提交规范 |
| [📋 更新日志](docs/CHANGELOG.md) | 每个版本的变更记录 |
| [📦 Releases](https://github.com/Kirky-X/crawlrs/releases) | 版本发布页面 |

</details>

---

## 💻 示例

全部 66 个可运行示例位于 [`examples/`](examples/)(根 workspace 成员 crate,主 `Cargo.toml` 的 `members = ["examples"]`),按功能域分为 search、scrape、crawl、extract、auth、teams、webhooks、cache、config、database、proxy、rate-limiting、sdk、tasks、browser、advanced 等类别(每个示例是 `[[bin]]` 目标,如 `basic_scrape`)。分类清单与说明见 [examples/README.md](examples/README.md) 与 [examples/QUICKSTART.md](examples/QUICKSTART.md)。

<details>
<summary>📄 代码 · bash</summary>

```bash
cd examples
cargo run --bin basic_scrape          # 基础抓取
cargo run --bin api_key_auth          # garrison API Key 认证
cargo run --bin async_batch           # 异步批量抓取
cargo build                           # 编译全部示例
```

</details>

---

## 🚢 部署

<details>
<summary>📄 代码 · bash</summary>

```bash
# 构建镜像(主 Dockerfile 位于 docker/ 目录)
docker build -t crawlrs:latest -f docker/Dockerfile .

# Docker Compose 一键启动(crawlrs + PostgreSQL 16 + FlareSolverr + Chrome + Prometheus)
docker compose -f docker/docker-compose.yml up -d
```

</details>

服务默认监听 `8899`(`CRAWLRS__SERVER__PORT` 可调);单实例与 Kubernetes 多实例拓扑、Worker 池与外部依赖关系详见 [🏗️ 架构文档 · 部署架构](docs/ARCHITECTURE.md),生产环境安全加固清单见 [🔒 安全文档 · 生产部署加固](docs/SECURITY.md)。

---

## 🏗️ 架构

crawlrs 遵循领域驱动设计(DDD),采用 `presentation → application → domain → infrastructure` 四层架构:Axum 处理 HTTP 与中间件,Use Case 编排业务逻辑,领域层以 `ScraperEngine` 等 trait 定义能力契约,基础设施层经 dbnexus(Sea-ORM)对接 PostgreSQL、经 oxcache 提供多层缓存。抓取数据通路为:请求经 SSRF 前置校验 → `EngineRouter` 按策略选路(反爬检测可动态改派浏览器引擎)→ Worker 池执行 → 结果落库并触发 Webhook。

自研库矩阵的消费面(同作者共享 rc 链):garrison 承载认证与健康探针(`auth` 门控)、limiteron 承载限流与引擎熔断状态机(`ManualCircuitBreaker` 薄封装 + `AtomicU8` 同步镜像)、oxcache 承载缓存本体(memory + `serialization` + `metrics`)与 URL 去重布隆过滤器(`bloom` feature,替代自研 MmapBloom)、sdforge 承载 DTO 校验与 HTTP 错误状态码映射(`unified::http_status_for`)。自研库缺口登记见 [🏗️ 架构文档 · 自研库反向需求](docs/ARCHITECTURE.md)。

分层职责、引擎路由细节、全部增强模块、队列/缓存/限流设计与部署拓扑详见 [🏗️ 架构文档](docs/ARCHITECTURE.md)。

---

## 🧪 测试

### 🎯 测试策略

测试体系覆盖七层:`src/` 内联单元测试、`tests/unit/` 按模块组织的单元测试、`tests/main.rs` 表驱动机(mock 注入)、SDK API 测试(`sdk_api_test`)、真实 PostgreSQL 集成测试(`integration_tests`,含 garrison 认证端到端)、Python API/性能测试与 E2E 质量保障套件(`tests/e2e/e2e-suite.sh`:22 组特性编译矩阵 → 静态检查 → 单元/集成测试 → 基准 → 报告)。各层场景穷举与文件映射见 [🧪 测试场景矩阵](docs/TEST_SCENARIOS.md)。

### ▶️ 运行命令

**与 CI 一致**(见 `.github/workflows/ci.yml`):

<details>
<summary>📄 代码 · bash</summary>

```bash
# 单元测试(CI test job:standard / full 各跑一轮;需 PostgreSQL 16,本地由 testcontainers 自动拉起)
cargo test --features "standard" --lib
cargo test --features "full" --lib

# 集成 + 全部测试目标(CI integration-test job)
cargo test --features "full,test-mocks" --tests --no-fail-fast

# Lint、格式与文档门禁(fmt / clippy / doc job)
cargo fmt -p crawlrs -p crawlrs-examples -- --check
cargo clippy --features "standard" -- -D warnings
cargo clippy --features "full" -- -D warnings
cargo doc --features "full" --no-deps          # CI doc job(RUSTDOCFLAGS=-D warnings)

# 覆盖率门禁:行覆盖率不低于 80%(CI coverage job,结果上传 Codecov)
cargo llvm-cov --features "full" --lib --fail-under-lines 80

# 供应链检查(advisories / licenses / bans / sources)
cargo deny check
```

</details>

**本地附加**(CI 不执行):

<details>
<summary>📄 代码 · bash</summary>

```bash
# 基准测试(Criterion,9 组)
cargo bench

# E2E 质量保障套件(特性矩阵 + 静态 + 测试 + 集成 + 基准 + 报告)
./tests/e2e/e2e-suite.sh

# Python API / 性能测试(local 模式跑 3 个套件:api_endpoints / performance / error_handling)
./scripts/run-tests.sh local

# 提交前完整检查(fmt → clippy → check → build → 私钥扫描)
scripts/pre-commit-check.sh all
```

</details>

### 📊 测试规模

截至 0.2.0:`src/` 内联测试 6,548 处(476 个源文件、229,992 行),`tests/` 目录 994 个测试(124 个 `.rs` 文件,含 `tests/unit/` 71 个单元测试文件与真实 PostgreSQL 集成套件),Criterion 基准 9 组,Python 测试 `tests/python/` 共 5 个套件(`scripts/run-tests.sh local` 模式跑其中 3 个:api_endpoints / performance / error_handling);覆盖率门禁为行覆盖率不低于 80%,由 CI 执行。逐项统计见 [🧪 测试场景矩阵 · 统计汇总](docs/TEST_SCENARIOS.md)。

---

## 📊 性能

性能工程内建于架构:AIMD 自适应并发、内存感知调度、TabPool 复用、请求合并(singleflight)、WaitFor 条件等待与 Hedge 副本控制器;可复现的基准为 `benches/benchmark.rs` 的 9 组 Criterion 基准(任务创建/状态迁移、JSON 序列化、URL 解析与校验、SSRF 检测、RegexCache、引擎路由等),E2E 套件 Stage 5 以 `e2e-baseline` 做回归对比。旧版宣传的 Node.js 对比数字未附测量口径,待复测后更新。基准说明与调优建议见 [⚡ 性能指南](docs/PERFORMANCE.md)。

---

## 🔒 安全

### 🛡️ 安全设计

安全设计覆盖请求全链路:SSRF 在 handler 前置与引擎路由双重校验;认证由 garrison 接管(HS256 JWT、RBAC、IP 级防暴力破解、审计落库);Webhook 经 Standard Webhooks 签名验证(subtle 恒时比较);JWT secret 以 zeroize 防内存残留;安全响应头与可信代理中间件默认加固。逐项机制详见 [🔒 安全文档](docs/SECURITY.md) 与 [🏗️ 架构文档 · 安全模型](docs/ARCHITECTURE.md)。

### ⛓️ 供应链与门禁

CI 固定执行 `cargo deny check`(advisories / licenses / bans / sources)、CodeQL 静态分析、clippy `-D warnings` 与 RSA 代码路径前提校验;本地 pre-commit 脚本含私钥扫描。完整门禁清单见 [🔒 安全文档 · 供应链与门禁](docs/SECURITY.md)。

### 🚨 报告安全漏洞

请勿通过公开 issue 报告安全漏洞。请优先使用 GitHub [Security Advisories](https://github.com/Kirky-X/crawlrs/security/policy) 私密披露通道提交报告(不可用时再发送邮件至 [Kirky-X@outlook.com](mailto:Kirky-X@outlook.com),受理人 Kirky.X)。完整漏洞处理流程见 [SECURITY.md](docs/SECURITY.md)。

---

## 🗺️ 开发路线图

<details>
<summary>📋 表格</summary>

<table style="width:100%; border-collapse: collapse">
<tr><th style="text-align:center">状态</th><th style="text-align:left">方向</th><th style="text-align:left">条目</th></tr>
<tr><td align="center">✅</td><td>核心平台(0.1.0)</td><td>搜索/抓取/爬取/提取/映射五大能力 API、DDD 四层、多租户与限流、Webhook 通知</td></tr>
<tr><td align="center">✅</td><td>稳定版发布(0.2.0)</td><td>自研依赖归一稳定版、alchemize 切 crates.io registry、i18n 宿主注册重写、crates.io + GitHub Release 双通道发布</td></tr>
<tr><td align="center">✅</td><td>流水线全量补跑(0.2.0-rc.4)</td><td>CI 五组合/engine-moli/BDD 复绿、CodeQL 归零、doctest 与示例修复、覆盖率 90.13%、E2E 六阶段 PASS(report 按设计 SKIPPED)</td></tr>
<tr><td align="center">✅</td><td>发布前收口(0.2.0-rc.3)</td><td>crawl 终态对账与崩溃恢复、团队域名黑名单全链路执行、SDK 建爬与搜索派生上限、Host 头丢弃等安全加固、web-axum 三驱动矩阵</td></tr>
<tr><td align="center">✅</td><td>平台加固与智能引擎(0.2.0-rc.2)</td><td>garrison 认证、反爬检测、TLS 指纹与 MLLM 引擎、RAG/KG/DRL 智能增强、Prometheus 可观测性、E2E 质量套件</td></tr>
<tr><td align="center">✅</td><td>数据库多驱动</td><td><code>db-sqlite</code> / <code>db-mysql</code> 覆盖到运行时 schema 供给:<code>migrations/{postgres,sqlite,mysql}/</code> 三方言建表目录按编译 feature 选择,<code>[database] auto_migrate</code>(缺省 false)接线,三方一致性由测试看护</td></tr>
<tr><td align="center">✅</td><td>架构演进</td><td>事件驱动内部总线(已交付 <code>tokio::sync::broadcast</code>)、WebSocket 实时任务状态(<code>GET /v1/tasks/{id}/ws</code>)、Redis 共享缓存层(<code>[cache] backend=redis</code>,多实例部署)</td></tr>
<tr><td align="center">🚧</td><td>forge_api 注册面迁移</td><td><code>forge-full</code>(sdforge inventory 单一注册面)为在途迁移停机坪,与手写 protected/v2 路由互斥;整体切换需三族中间件统一排序裁决</td></tr>
<tr><td align="center">🚧</td><td>性能看护</td><td>Criterion 基线(e2e-baseline / ci-baseline)回归对比门禁已落地(<code>.github/workflows/bench.yml</code>,手动派发);权威性能口径复测待进行</td></tr>
</table>

</details>

---

## 🤝 参与贡献

详细的贡献流程与代码规范请参阅 [🤝 贡献指南](docs/CONTRIBUTING.md)。

### 🛠️ 开发环境

工具链要求见 `Cargo.toml` 的 `rust-version`(1.97.1),构建 sdforge 需要 protoc;提交前运行 `scripts/pre-commit-check.sh all`(fmt → clippy → check → build → 私钥扫描),提交信息遵循 Conventional Commits(`type(scope): subject`)。开发工作流(TDD)、分支与测试要求见 [🤝 贡献指南 · 开发工作流](docs/CONTRIBUTING.md)。

### 💖 贡献方式

<table style="width:100%; border-collapse: collapse">
<tr>
<td width="33%" align="center" style="padding: 16px">

### 🐛 报告 Bug

发现问题?<br>
<a href="https://github.com/Kirky-X/crawlrs/issues/new">创建 Issue</a>

</td>
<td width="33%" align="center" style="padding: 16px">

### 💡 功能建议

有好想法?<br>
<a href="https://github.com/Kirky-X/crawlrs/issues/new">发起讨论</a>

</td>
<td width="33%" align="center" style="padding: 16px">

### 🔧 提交 PR

想贡献代码?<br>
<a href="https://github.com/Kirky-X/crawlrs/pulls">Fork 并提交 PR</a>

</td>
</tr>
</table>

---

## 📋 更新日志

完整版本历史见 [📋 更新日志](docs/CHANGELOG.md)(遵循 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) 格式,语义化版本)。

<details>
<summary>📋 表格</summary>

| 版本 | 日期 | 要点 |
|------|------|------|
| 0.2.0 | 2026-11-15 | **首个 crates.io 稳定版**:自研依赖全部归一稳定版(minor 精度)、alchemize 切 registry(无 path/git 依赖,publish 通道打通)、i18n 体系重写(sdforge 宿主注册,fluent-bundle 退役)、markdown 默认转换器 alchemize、release.yml 迁移 OIDC + token 兜底 |
| 0.2.0-rc.4 | 2026-11-10 | 发布流水线全量补跑:CI 三族修复复绿、CodeQL 18 条裁决归零、doctest/示例/文档修复、覆盖率 90.13%、E2E 六阶段 PASS(report 按设计 SKIPPED)、依赖补丁升级 |
| 0.2.0-rc.3 | 2026-11-10 | 终态对账/崩溃恢复重算、团队域名黑名单全链路(归一化+上限+fail-closed+sitemap/proxy 同口径)、SDK 建爬与搜索派生 200 上限/深度 ≤5、Host 头丢弃、web-axum 三驱动矩阵;三维审查三轮 PASS |
| 0.2.0-rc.2 | 2026-09-21 | TLS 指纹引擎(WreqEngine)、MLLM 视觉导航引擎、RAG 增强提取、知识图谱覆盖感知、DRL 自适应策略、5 个新 Prometheus 指标;功能吸收 F1–F12(AutoThrottle、Session 身份、失败快照、sitemap 请求源、XHR 捕获、提取质量门、LLM 分块与溯源、AIMD 内存联动、软 404、AX 树快照) |
| 0.2.0-legacy | 2026-07-29 | 历史段(tag 已于 2026-11-15 重制):garrison RBAC 认证集成、bootstrap admin key、`DELETE /v1/crawl/{id}`、暴力破解防护加固 |
| 0.1.0 | 2026-07-22 | 首个公开版本:五大能力 API、DDD 四层架构、多租户与限流、统一搜索 |

</details>

---

## 📄 许可证

本项目采用 [Apache License 2.0](LICENSE) 许可证。Copyright © 2025-2026 Kirky.X🌠。

---

## 🙏 致谢

### 🌟 核心依赖

crawlrs 站在以下优秀开源项目的肩膀上:

<details>
<summary>📋 表格</summary>

| 依赖 | 用途 |
|------|------|
| [tokio](https://crates.io/crates/tokio) | 异步运行时 |
| [axum](https://crates.io/crates/axum) | Web 框架 |
| [reqwest](https://crates.io/crates/reqwest) | HTTP 客户端 |
| [chromiumoxide](https://crates.io/crates/chromiumoxide) | Chrome CDP 浏览器自动化 |
| [wreq](https://crates.io/crates/wreq) | BoringSSL TLS 指纹伪装 |
| [scraper](https://crates.io/crates/scraper) | HTML 解析 |
| [fluxweir](https://crates.io/crates/fluxweir) | LLM/嵌入/重排统一出口(`gateway`;`engine-mllm` 视觉面经 chat 承载) |
| [htmd](https://crates.io/crates/htmd) | HTML→Markdown 转换(诊断臂直通) |
| [alchemize](https://github.com/Kirky-X/alchemize) | HTML→Markdown 默认转换器(自研 html 引擎:htmd 基础链 + 自研深链;path 依赖) |
| [rs-trafilatura](https://crates.io/crates/rs-trafilatura) / [dom_smoothie](https://crates.io/crates/dom_smoothie) | 正文提取 |
| [criterion](https://crates.io/crates/criterion) | 基准测试 |
| [testcontainers](https://crates.io/crates/testcontainers) | 集成测试基础设施 |

</details>

同作者自研基座组件:dbnexus(数据库抽象)、confers(配置管理)、garrison(认证框架)、limiteron(限流熔断)、oxcache(缓存)、inklog(结构化日志)、sdforge(SDK 生成)、trait-kit(依赖注入)。

### 💝 特别感谢

感谢 Rust 社区与所有[贡献者](https://github.com/Kirky-X/crawlrs/graphs/contributors)。

---

## 📞 联系与支持

<table style="width:100%; max-width: 600px">
<tr>
<td align="center" width="33%">
<a href="https://github.com/Kirky-X/crawlrs/issues"><b style="color:#991B1B">Issues</b></a><br>
<span style="color:#64748B">报告问题和 Bug</span>
</td>
<td align="center" width="33%">
<a href="mailto:Kirky-X@outlook.com"><b style="color:#1E40AF">邮箱</b></a><br>
<span style="color:#64748B">Kirky-X@outlook.com</span>
</td>
<td align="center" width="33%">
<a href="https://github.com/Kirky-X/crawlrs"><b style="color:#1E293B">GitHub</b></a><br>
<span style="color:#64748B">查看源代码</span>
</td>
</tr>
</table>

---

## ⭐ Star 历史

[![Star History Chart](https://api.star-history.com/svg?repos=Kirky-X/crawlrs&type=Date)](https://star-history.com/#Kirky-X/crawlrs&Date)

如果这个项目对您有帮助,请考虑给它一个 ⭐️!

**由 Kirky.X 构建**

---

<sub>© 2025 Kirky.X. 保留所有权利。</sub>