Search Engine

🔎 分布式搜索引擎爬虫

建立一个 生产风格，横向可扩展 crawler+索引管道与Python，Postgres，批处理作业，和一个FastAPI搜索API。

______________________________________________________________________

✨ 为什么是这个项目？

• ⚡ 快速无国籍工人 用于爬行吞吐量。
• 🧠 离线全局计算 （PageRank、链接分辨率、BM25统计数据）。
• 🗄️ 迁移优先模式管理 与Alembic。
• 🐳 Docker编写+Swarm友好 部署工作流程。

______________________________________________________________________

🧱 建筑概览

Crawler Workers (append-heavy writes)
        ↓
      Postgres
        ↓
Batch Jobs (duplicate detection, link graph, pagerank, bm25)
        ↓
     Search API

______________________________________________________________________

🚀 快速开始

1） 配置环境

此回购附带了基线 .env.根据需要更新值：

• POSTGRES_USER
• POSTGRES_PASSWORD
• POSTGRES_DB
• CRAWLER_USER_AGENT
• QUEUE_BATCH_SIZE
• CRAWLER_CONCURRENCY
• REQUEST_TIMEOUT_S
• BATCH_INTERVAL_S
• BATCH_TOTAL_NODES （可选，适用于分布式批处理工人）
• BATCH_NODE_INDEX （可选，适用于分布式批处理工人）
• BATCH_ROLE (auto, coordinator, worker)

2） 启动堆栈

docker compose up --build

3） 查询搜索API

curl 'http://localhost:8000/search?q=example'
curl 'http://localhost:8000/search/web?q=example'
curl 'http://localhost:8000/search/news?q=example'
curl 'http://localhost:8000/search?q=example&limit=10&offset=0'

4） 运行MCP搜索服务器

将搜索作为MCP工具公开(search_web, search_news)对于MCP兼容客户端：

python -m app.mcp.server

服务器名称： OpenGoogle.

将URL种子放入爬网队列

python scripts/seed_url.py 'https://example.com'

______________________________________________________________________

🔌 API

GET /search

别名 /search/web （仅限网络结果）。

查询参数：

• q （必填）：搜索查询文本
• limit （可选，默认20，最大100）
• offset （可选，默认为0）

GET /search/web

查询参数与 /search。仅返回web结果：

{
  "results": [
    {
      "title": "...",
      "description": "...",
      "url": "https://...",
      "score": 1.234
    }
  ],
  "count": 1
}

GET /search/news

查询参数与 /search。仅返回新闻结果。

______________________________________________________________________

🧩 组件

• app/crawler/queue_manager.py：队列转换+批出队列。
• app/crawler/worker.py：fetch→ 解析→ 验证→ 标记化→ 坚持。
• app/batch/*.py：离线全球工作，包括集成RSS/Atom新闻提取器。
• app/batch/runner.py：始终运行批处理调度程序循环。
• app/api/main.py：FastAPI /search, /search/web，以及 /search/news 端点。
• app/api/search_service.py：共享搜索执行+API和MCP层使用的排名逻辑。
• app/mcp/server.py：FastMCP服务器暴露 search_web 和 search_news 工具。
• alembic/：版本化迁移（单一模式真实源）。
• scripts/update_cluster.sh：带迁移窗口的群更新。

______________________________________________________________________

🐝 Swarm部署/更新

建筑来自 main 发布多拱形图像(linux/amd64 和 linux/arm64)to ghcr.io/youngermax/search-engine:latest 通过GitHub操作。 Swarm部署直接从任一架构上的GHCR中提取该图像。

docker swarm init
./scripts/update_cluster.sh

更新流程：

1. 部署堆栈定义。
2. 缩小迁移器+爬行器/API/批处理。
3. 等待Postgres运行。
4. 重试运行migrator（处理Postgres启动窗口）。
5. 缩放爬行器/API/批量备份。

______________________________________________________________________

⏱️ 批量节奏

batch-jobs 持续运行并执行完整的管道 BATCH_INTERVAL_S 秒。

📰 新闻整合

• 新闻提要和文章通过以下方式存储在Postgres中 Alembic迁徙 (news_feeds, news_articles)和统一 tokens 表（web和新闻的源代码感知行）。
• 爬虫工人自动发现RSS/Atom `

元数据与种子 news_feeds`.

• 批处理作业获取提要并索引新闻术语 /search/news 结果。
• Alembic是集成堆栈的规范迁移引擎。

⚙️ 分布式批处理模式

运行多个 batch-jobs 节点与 BATCH_TOTAL_NODES 独一无二 BATCH_NODE_INDEX 价值观。 碎片化作品(duplicate_detection, news_fetcher)在所有节点上运行；全球工作(link_graph, pagerank, bm25, spellcheck)仅在协调器上运行（默认情况下为节点0，或强制使用 BATCH_ROLE=coordinator).