内容
# OpenCrawling
[](LICENSE)
[](https://jdk.java.net/25/)
[](https://spring.io/projects/spring-boot)
[](https://www.docker.com/)
[](https://kafka.apache.org/)
[](https://www.postgresql.org/)
[](https://redis.io/)
[](https://github.com/OpenPj/spring-manifold-next-gen/stargazers)
[](https://github.com/OpenPj/spring-manifold-next-gen/issues)
[](https://github.com/OpenPj/spring-manifold-next-gen/pulls)
**OpenCrawling** 是一款企业级数据集成和摄入平台，其灵感来自 Apache ManifoldCF。它利用现代 Java 25 功能（例如结构化并发和虚拟线程）、Spring Boot 和向量搜索基础设施来编排来自各种存储库连接器到向量搜索输出的数据流。
<p align="center">
<img src="https://github.com/opencrawling/.github/raw/main/profile/images/logo.png" alt="OpenCrawling Logo" width="200" />
</p>
---
## 架构图
下面的图表显示了 OpenCrawling 的高级架构：
```mermaid
graph TD
subgraph UI
UI_App[Admin React UI - oc-admin-ui]
end
subgraph Platform Runtime [OpenCrawling JVM Runtime]
Core[Core Ingestion Engine - oc-core]
Runtime[Bootstrap - oc-runtime]
FS_Conn[Filesystem Repository - oc-filesystem-repository-connector]
Ing_Cons[Ingestion Consumer - IngestionConsumer]
Tika[Apache Tika Text Extractor]
Chunker[Token Chunker]
Embed_Cons[Embedding Consumer - EmbeddingConsumer]
Writer_Cons[Vector Store Writer - VectorStoreWriterConsumer]
Precompute_Model[PrecomputedEmbeddingModel]
Vec_Conn[Vector Store Output - oc-vector-output-connector]
McpServer[Secure MCP Server - McpVectorServer]
Runtime --> Core
Core --> FS_Conn
Core -->|Publish IngestionMessage| Ingest_Topic[(Kafka Topic: opencrawling-ingestion)]
Ingest_Topic -->|Consume IngestionMessage| Ing_Cons
Ing_Cons -->|Extract Text| Tika
Tika --> Chunker
Chunker -->|Publish Chunks| Chunk_Topic[(Kafka Topic: opencrawling-chunks)]
Chunk_Topic -->|Consume ChunkMessage| Embed_Cons
Embed_Cons -->|Publish Embedded| Embed_Topic[(Kafka Topic: opencrawling-embedded)]
Embed_Topic -->|Consume EmbeddedMessage| Writer_Cons
Writer_Cons --> Precompute_Model
Precompute_Model --> Vec_Conn
McpServer -->|Queries - Enforces ACLs| Vec_Conn
end
subgraph Infrastructure [Docker Containers]
PG[(PostgreSQL + pgvector)]
Redis[(Redis Cache & Session)]
Ollama[Ollama AI Embeddings]
Kafka_Broker[Apache Kafka Broker]
end
subgraph External [AI Clients]
LLM[AI Client / LLM Agent]
end
UI_App -->|REST API| Runtime
Vec_Conn -->|Vectors| PG
Runtime -->|Job Cache| Redis
Embed_Cons -->|Generates Embeddings| Ollama
Ingest_Topic --> Kafka_Broker
Chunk_Topic --> Kafka_Broker
Embed_Topic --> Kafka_Broker
LLM -->|Model Context Protocol| McpServer
```
---
## 管理仪表盘（oc-admin-ui）
`oc-admin-ui` 提供了一个现代化的基于 Web 的管理控制台，用于监控和配置摄入作业。
### UI 截图
#### 📊 遥测仪表盘
* 实时图表监控作业成功率、Kafka 队列负载、活动爬取线程和索引摄入速度。
#### 📋 作业管道调度器
* 调度、监控、启动和暂停摄入爬取任务。查看文档索引状态报告。
#### 📁 连接器配置
* 管理存储库（SharePoint、S3、文件系统）和向量搜索目标的端点和凭证。
#### ⚙️ 摄入和嵌入映射
* 配置目标模型（例如 Ollama、OpenAI）并动态调整文本块大小和重叠边界。
#### 🪵 实时摄入日志
* 检查实时 Java 日志流和 Kafka 消费者偏移以排除连接器执行的故障。
---
## 核心技术
- **Java 25 预览功能**：结构化并发、虚拟线程和模式匹配。
- **Spring Boot 和 Spring AI**：高性能后端编排摄入作业。
- **Apache Kafka**：使用 **Claim Check Pattern** 的解耦、事件驱动的文档处理。
- **pgvector**：PostgreSQL 中的高维向量相似性搜索。
- **Redis Stack**：轻量级缓存和会话管理。
- **Ollama**：通过开源 LLM 模型进行本地 AI 嵌入生成。
- **Vite + React + TailwindCSS**：现代前端管理仪表盘。
---
## 入门指南
### 先决条件
确保您的机器上已安装以下内容：
- **JDK 25**（确保 `JAVA_HOME` 指向您的 JDK 25 目录）
- **Maven 3.9+**
- **Docker 和 Docker Compose**
- **Node.js 18+ 和 npm**（用于 UI）
---
### 步骤式设置
#### 1. 启动基础设施（Docker）
启动数据库、缓存、消息代理和 AI 引擎。从项目根目录运行：
```bash
docker compose up -d
```
**启动的服务：**
* **PostgreSQL（端口 5432）**：用于作业元数据、模式迁移和 pgvector 存储。
* **Redis（端口 6379 / Insight 端口 8001）**：用于缓存和会话管理。
* **Ollama（端口 11434）**：用于本地嵌入。
* **Apache Kafka（端口 9092）**：用于解耦、事件驱动的文档处理的 KRaft 模式代理（内部容器通信在端口 `9094`）。
#### 2. 拉取嵌入模型（Ollama）
OpenCrawling 支持在每个作业的基础上配置不同的嵌入模型，并自动将它们路由到相应的 PgVector 表中。要使用可用的选项，请确保拉取您计划使用的模型：
* **mxbai-embed-large（1024-dim，默认）**：
```bash
docker exec -it ollama ollama pull mxbai-embed-large
```
* **nomic-embed-text（768-dim）**：
```bash
docker exec -it ollama ollama pull nomic-embed-text
```
* **all-minilm（384-dim）**：
```bash
docker exec -it ollama ollama pull all-minilm
```
*（Ollama 将在后台下载请求的模型。一旦拉取，OpenCrawling 将自动将它们路由到 `vector_store_1024`、`vector_store_768` 或 `vector_store_384`。）
---
### 选项 A：以 Docker 容器运行 OpenCrawling（推荐）
要将 OpenCrawling 后端运行时和管理员 UI 作为容器化服务构建和运行，请执行：
1. **构建镜像**：
```bash
docker compose -f docker-compose-apps.yml build
```
2. **启动应用程序**：
```bash
docker compose -f docker-compose-apps.yml up -d
```
* **后端服务**：在 [http://localhost:8080](http://localhost:8080) 访问后端运行时和集成的静态资源。
* **前端服务**：在 [http://localhost:3000](http://localhost:3000) 访问独立的 React 管理控制台。
---
### 选项 A.2：解耦多服务部署（解耦微服务）
要将每个微服务组件（存储库爬虫、摄入消费者、嵌入消费者、向量存储写入器、安全 MCP 服务器和管理员 UI）作为单独的容器化进程运行，通过 Kafka 进行通信：
1. **构建解耦服务镜像**：
```bash
docker compose -f docker-compose-decoupled.yml build
```
2. **启动完整的解耦管道**：
```bash
docker compose -f docker-compose-decoupled.yml up -d
```
这将启动数据库/事件流依赖项以及五个解耦的 OpenCrawling 服务容器。您可以查看日志、缩放单个工作线程（例如 `docker compose -f docker-compose-decoupled.yml scale oc-embedding-consumer=3`）并监控解耦管道。
* **React 管理 UI 控制台**：在 [http://localhost:3000](http://localhost:3000) 访问管理仪表盘。
* **安全 MCP 服务器**：通过 SSE 直接将您的 AI 客户端/IDE 连接到 [http://localhost:8080](http://localhost:8080)。
#### 运行解耦集成测试
我们提供了一个完全自动化的端到端集成测试脚本，用于构建、启动、测试和清理整个解耦环境：
```bash
./scripts/test-docker-decoupled.sh
```
该脚本：
1. 从源代码构建所有解耦的微服务。
2. 启动 Kafka 代理、PostgreSQL + pgvector、Redis、Ollama 和消费者工作线程。
3. 自动在爬虫挂载中生成一个示例文档，触发扫描，并等待消费者摄入。
4. 直接查询 pgvector 以验证生成的嵌入是否正确存储。
5. 验证安全 MCP 服务器 SSE 端点，并在成功后关闭环境。
---
### 选项 B：在本地运行 OpenCrawling（开发模式）
如果您希望在主机机器上直接运行 JVM 运行时和 React 前端进行开发：
#### 1. 构建项目（Maven）
使用 Java 25 编译所有模块。由于我们使用高级功能，因此必须启用预览功能：
```bash
mvn clean install
```
#### 2. 运行运行时引导
启动 Spring Boot 运行时应用程序：
```bash
mvn spring-boot:run -pl oc-runtime -Dspring-boot.run.profiles=dev
```
##### 在启动时运行示例摄入作业（可选）
默认情况下，自动启动爬取功能被禁用，以防止不必要的扫描。要在启动时触发演示爬取作业，请传递配置属性：
```bash
mvn spring-boot:run -pl oc-runtime -Dspring-boot.run.profiles=dev \
-Dspring-boot.run.arguments="--spring.opencrawling.crawl-on-startup=true --spring.opencrawling.scan-path=/your/local/directory/to/scan"
```
#### 3. 运行管理员 UI
启动管理仪表盘：
```bash
cd oc-admin-ui
npm install
npm run dev
```
在浏览器中打开 [http://localhost:5173](http://localhost:5173)。
---
## 扩展和性能
OpenCrawling 设计用于高吞吐量、水平可扩展性。由于摄入管道使用 **Apache Kafka** 和 **Claim Check Pattern** 进行解耦，您可以独立扩展组件。
### 1. 扩展摄入/处理（输出连接器）
向量索引和嵌入生成通常是主要的性能瓶颈，因为深度学习模型推理（Ollama）和数据库索引（pgvector）。
* **Kafka 消费者组分区**：三个主要主题（`opencrawling-ingestion`、`opencrawling-chunks` 和 `opencrawling-embedded`）分别由 `IngestionConsumer`、`EmbeddingConsumer` 和 `VectorStoreWriterConsumer` 在 `oc-runtime` 服务中消费。通过将这些主题配置为多个分区，Kafka 在活动消费者节点之间动态分配负载。
* **运行时实例的水平扩展**：您可以运行多个 `oc-runtime` 应用程序实例，共享相同的 `spring.application.name` 和消费者组（`opencrawling-vector-group`）。Kafka 自动分配分区并平衡消息。
* **Ollama 负载均衡**：通过将 `spring.ai.ollama.base-url` 指向负载均衡器（例如 NGINX、HAProxy），并由一组 Ollama 实例运行在启用 GPU 的节点上来扩展嵌入生成。
### 2. 扩展存储库连接器（摄入源）
可以通过分割大型目标源来分布式扫描/爬取：
* **分区扫描**：运行单独的启动爬取作业，针对不同的子目录或存储库前缀。
* **分布式文件共享/共享存储**：在多节点设置中，确保 `IngestionConsumer` 实例可以访问与存储库爬虫相同的共享文件系统（例如 NFS、S3/MinIO 存储桶、SMB），以便 Claim Check 引用（路径/URI）可以成功地被消费者节点解析。
### 3. Claim Check Pattern
为了确保消息系统保持快速和响应：
1. **存储库连接器** 爬取数据，但不是将整个文档内容（可能是数兆字节的二进制数据）发布到 Kafka，而是将文件保存在共享存储介质上。
2. 发布一个轻量级 `IngestionMessage`（Claim Check 记录）到 Kafka 主题，包含元数据（URI、文件路径、版本）。
3. **消费者工作线程** 处理摄入：
* **`IngestionConsumer`** 拉取引用，读取文件直接从存储中，提取文本与 **Apache Tika**，将其分成语义块，并发布到块主题。
* **`EmbeddingConsumer`** 拉取块，请求 **Ollama** 的嵌入向量，并发布嵌入块到嵌入主题。
* **`VectorStoreWriterConsumer`** 消费嵌入块，并使用 `PrecomputedEmbeddingModel` 直接将它们保存到 pgvector。
---
## 验证和监控
- **数据库**：在 `localhost:5432` 访问 PostgreSQL（用户：`opencrawling`，数据库：`opencrawling`）。
- **Redis 仪表盘**：在 [http://localhost:8001](http://localhost:8001) 打开 Redis Stack Insight 仪表盘以查看 Redis Stack Insight 仪表盘。
- **日志**：监控控制台输出的虚拟线程执行器和结构化并发任务日志。
---
## 故障排除
- **Java 版本检查**：运行 `java -version` 以确认您正在使用 Java 25。
- **预览功能**：如果您的 IDE 无法编译结构化并发代码，请验证编译器和运行时设置是否配置了 `--enable-preview` JVM 参数。（它已经预配置在 `pom.xml` 中）。
---
## 商标
OpenCrawling® 是 OpenCrawling 组织的注册商标。有关使用该名称和徽标的指南，请参阅 [TRADEMARK.md](TRADEMARK.md) 文件。
