# ❓ Crawlrs FAQ
本页汇总 crawlrs 的常见问题与解答,按主题分组。答案均基于仓库实际代码与配置。没有找到答案?欢迎前往 [GitHub Issues](https://github.com/Kirky-X/crawlrs/issues) 提问。
## 📋 目录
- [🧭 通用问题](#-通用问题)
- [📦 安装与配置](#-安装与配置)
- [🔐 认证与多租户](#-认证与多租户)
- [🚂 引擎与抓取](#-引擎与抓取)
- [🧪 测试与部署](#-测试与部署)
---
## 🧭 通用问题
### ❓ crawlrs 是什么?
crawlrs 是一个使用 Rust 构建的自托管企业级网页数据采集平台,提供五大能力:统一搜索(Bing/百度/搜狗 + Smart 聚合,可选 Exa/Tavily)、单页抓取、多页爬取、数据提取与站点映射,并内置多租户、认证、限流、Webhook、指标等平台能力。架构与能力全景见 [🏗️ 架构文档](ARCHITECTURE.md)。
### ❓ 为什么选择 Rust 实现?
零成本抽象与 fearless concurrency 带来高吞吐与低尾延迟;强类型与 trait 契约(`ScraperEngine` 等)让引擎扩展安全可控;单个静态二进制便于部署。
### ❓ 可以用于生产环境吗?
可以。项目具备企业级配套:garrison 认证(RBAC + JWT + 防暴力破解)、limiteron 限流熔断、审计日志、Prometheus 指标、覆盖率门禁 ≥ 80% 的 CI、22 组合特性矩阵与 E2E 质量套件。上线前请过一遍 [🔒 安全文档 · 生产部署加固清单](SECURITY.md)。
### ❓ 项目采用什么许可证?
[Apache License 2.0](../LICENSE)。Copyright © 2025-2026 Kirky.X🌠。
### ❓ 在哪里可以获得帮助?
- 使用问题:[📖 用户指南](USER_GUIDE.md) 与本 FAQ;
- 接口细节:[📘 API 参考](API_REFERENCE.md);
- Bug 与建议:[GitHub Issues](https://github.com/Kirky-X/crawlrs/issues);
- 安全漏洞:优先走 GitHub [Security Advisories](https://github.com/Kirky-X/crawlrs/security/policy) 私密披露,备选邮件 [Kirky-X@outlook.com](mailto:Kirky-X@outlook.com)(受理人 Kirky.X;勿公开披露)。
---
## 📦 安装与配置
### ❓ 系统要求是什么?
Rust 1.97.1+(`Cargo.toml` `rust-version`,构建需 protoc)、PostgreSQL 16+(默认后端)、Docker 20+(集成测试与容器部署)。详见 README「快速开始」。
### ❓ 如何选择特性组合?
按场景选择预设:默认(完整平台)、`standard`(生产推荐)、`full`(全功能)、`--no-default-features`(单租户/嵌入)、`agent-lib`(agent 最小库面)。逐项矩阵见 README「🎨 特性标志」;组合的编译验证方式见 [🧪 测试场景矩阵](TEST_SCENARIOS.md)。
### ❓ 支持哪些数据库?
`db-postgres`(默认)/ `db-sqlite` / `db-mysql` 三组特性按构建三选一,互斥由 dbnexus 编译期强制。三套 DDL 均已随仓库提供(`migrations/postgres|sqlite|mysql/`);`crawlrs migrate` 按编译启用的特性选择对应子目录并有序应用,运行时不需要自行提供 schema。
### ❓ 环境变量如何命名?
统一 `CRAWLRS__` 前缀,`__` 分隔嵌套层级(confers 约定),如 `CRAWLRS__DATABASE__URL`、`CRAWLRS__SERVER__PORT`。完整参考见 [.env.example](../.env.example);配置段速查见用户指南。
### ❓ 服务监听哪个端口?如何确认启动成功?
默认 `8899`(`CRAWLRS__SERVER__PORT` 可调)。`curl http://localhost:8899/health` 返回 `{"status":"healthy","version":"0.2.0"}` 即成功。
---
## 🔐 认证与多租户
### ❓ API Key 是什么格式?
0.2.0 起认证由 garrison 接管,Bearer token 格式为 `garrison_key_id.garrison_secret`;明文 key 仅在签发响应中返回一次,请立即写入 secrets manager。
### ❓ 0.1.x 的旧 API Key 还能用吗?
不能。0.2.0 认证迁移后旧的 `api_keys.key_hash`(SHA-256)体系全部作废,`CRAWLRS__AUTH__KEYS` / `[auth] keys` 配置项已弃用,需向 garrison 重新领取。
### ❓ 如何签发新的 API Key?
两种方式:`POST /v1/admin/api-keys`(需 `crawlrs:admin` 权限);开发/测试环境用 `CRAWLRS__BOOTSTRAP_ADMIN_API_KEY` 环境变量自动引导 admin key(生产禁用)。
### ❓ 必须配置哪些认证相关项?
`CRAWLRS__AUTH__JWT_SECRET`(HS256,≥32 字节)——弱密钥会拒绝启动。
### ❓ 401 和 429 有什么区别?
401 表示 key 无效/过期/权限不足(auth-off 构建下则表示该路由未显式 `allow_unauthenticated_protected()` 放行);429 表示触发限流或 garrison 防暴力破解锁定(5 次失败 / 60 秒窗口 / 300 秒锁定)。
### ❓ 可以完全关闭认证吗?
可以,但**默认拒绝**。`cargo build --release --no-default-features` 构建单租户/无认证版本:`default_identity_middleware` 注入固定身份,全部请求归属默认团队;rate-limit / webhook 关闭时同样注入 Noop 实现,业务逻辑无感知。
> ⚠️ auth-off 不是"放行一切":`src/bootstrap/routes.rs:179-188` 注入的是 `ApiKeyScope::denied()`(read/write/admin 全 false、限额 0),因此未显式调用 `crawlrs::presentation::middleware::auth_middleware::allow_unauthenticated_protected()` 的受保护路由**一律返回 401**。要让某个路由在 auth-off 下可匿名访问,必须在代码里显式 opt-in;启动时会打一条 WARNING 提醒本实例运行在无鉴权降级模式,**切勿暴露到公网**。
---
## 🚂 引擎与抓取
### ❓ 五个引擎分别什么时候用?
| Reqwest | 静态 HTML、API 响应(默认最快路径) |
| Playwright(chromiumoxide) | JS 渲染的 SPA、页面交互 |
| FlareSolverr | 反爬保护站点(Full/Cdp/Tls 三模式,需外部服务) |
| WreqEngine | TLS 指纹伪装(BoringSSL JA3/JA4,`engine-tls-fingerprint`) |
| MllmEngine | 视觉 LLM 自主导航(截图→决策→执行,`engine-mllm`) |
`EngineRouter` 以 `SmartHybrid` 策略自动选路;反爬检测命中后可动态改派浏览器引擎。细节见 [🏗️ 架构文档 · Crawling Engines](ARCHITECTURE.md)。
### ❓ 构建 TLS 指纹引擎有什么额外要求?
`engine-tls-fingerprint` 引入 wreq(BoringSSL 后端),构建机器需要 cmake 与 C 编译器。许可证上刻意排除了 GPL 的 wreq-util,指纹模拟由项目自有枚举实现。
### ❓ 抓取结果支持哪些输出格式?
`ScrapeResponse` 支持原始 HTML、纯文本、结构化提取结果,启用 `content` 后附 `markdown` 字段(htmd 转换);正文提取可选用 Trafilatura(主路径)/ DomSmoothie(性能回退)/ LLM / RAG 策略。
### ❓ 遵守 robots.txt 吗?
遵守。`robotstxt` 为核心栈非可选依赖,爬取示例中有 `robots_compliance` 专项演示;深度爬取支持 URL 过滤链与自适应停止。
---
## 🧪 测试与部署
### ❓ 跑测试为什么需要 Docker?
集成测试用 testcontainers 自动拉起 PostgreSQL 16 容器(无 Docker 时相关用例自动 skip);也可用 `TEST_DATABASE_URL` 指向外部实例(`docker/docker-compose.test.yml` 提供 `test-db`)。完整命令见 [🧪 测试场景矩阵 · 运行手册](TEST_SCENARIOS.md)。
### ❓ 测试规模有多大?
截至 0.2.0(口径:`grep -rE '^\s*#\[(tokio::)?test\]'` 统计内联测试属性):
| `src/` | 476 个 `.rs` 文件、229,992 行、6,548 处内联测试属性 |
| `tests/` | 124 个 `.rs` 文件、994 个测试函数(其中 `tests/unit/` 71 个文件) |
| Criterion 基准组 | 9 组(`benches/benchmark.rs`) |
| Python 测试套件 | 5 个(`tests/python/`) |
| BDD 验收 | `tests/acceptance/` 61 个场景 / 10 个 feature 文件(其中 2 个 `@external` 不参与本地执行) |
| CI 行覆盖率门禁 | 80% |
详见 [🧪 测试场景矩阵 · 统计汇总](TEST_SCENARIOS.md#-统计汇总)。
### ❓ 如何部署?
`docker build -t crawlrs:latest -f docker/Dockerfile .` 构建镜像;`docker compose -f docker/docker-compose.yml up -d` 一键拉起 crawlrs + PostgreSQL + FlareSolverr + Chrome + Prometheus。Kubernetes 多实例拓扑见 [🏗️ 架构文档 · 部署架构](ARCHITECTURE.md)。
### ❓ `crawlrs worker` 是什么?
同一二进制的第二种运行形态:API 模式(默认)接收请求并入队,Worker 模式消费任务队列执行抓取。二者可分开部署、独立扩缩容。