Meilisearch

docs-scraper

Meilisearch | Meilisearch Cloud | 文档 | Discord | 路线图 | 网站 | 常见问题

🚨 重要通知：维护和支持减少 🚨

亲爱的社区，

我们想分享一些关于这个仓库未来维护的更新：

我们的团队规模很小，在接下来的一段时间内可用性会降低。因此，响应时间可能会变慢，我们也不会接受这个仓库的任何增强功能。

如果你正在寻找可靠的替代方案，可以考虑使用云服务。它为那些寻找这个仓库替代方案的人提供了一个强大的解决方案，包括一个方便的爬虫工具。

需要即时支持？请加入我们的Discord频道。

docs-scraper是一个用于你的文档网站的爬虫，它可以将爬取的内容索引到Meilisearch实例中。

Meilisearch是一个开源搜索引擎。了解Meilisearch是什么！

这个爬虫在生产环境中使用，每次部署时都会在Meilisearch文档上运行。

💡 如果你已经有了自己的爬虫，但仍然想使用Meilisearch和我们的前端工具，请查看这个讨论。

⚡ 提升你的Meilisearch体验

告别服务器部署和手动更新，使用Meilisearch Cloud。无需信用卡。

⚙️ 使用方法

使用docs-scraper需要以下3个步骤：

运行Meilisearch实例
设置配置文件
运行爬虫

运行你的Meilisearch实例

你的文档内容需要被爬取并推送到Meilisearch实例中。

你可以使用curl在你的机器上安装和运行Meilisearch。

curl -L https://install.meilisearch.com | sh
./meilisearch --master-key=myMasterKey

还有其他安装Meilisearch的方式。

在接下来的步骤中，你将提供的主机URL和API密钥对应于这个Meilisearch实例的凭据。在上面的例子中，主机URL是http://localhost:7700，API密钥是myMasterKey。

Meilisearch是开源的，可以在你的服务器上或任何云提供商上运行。这里有一个在生产环境中运行Meilisearch的教程。

设置你的配置文件

爬虫工具需要一个配置文件来知道你想爬取哪些内容。这是通过提供选择器（例如HTML标签/id/类）来实现的。配置文件作为参数传递。它不遵循任何命名约定，你可以随意命名。

这是一个基本配置文件的例子：

{
  "index_uid": "docs",
  "start_urls": ["https://www.example.com/doc/"],
  "sitemap_urls": ["https://www.example.com/sitemap.xml"],
  "stop_urls": [],
  "selectors": {
    "lvl0": {
      "selector": ".docs-lvl0",
      "global": true,
      "default_value": "文档"
    },
    "lvl1": {
      "selector": ".docs-lvl1", 
      "global": true,
      "default_value": "章节"
    },
    "lvl2": ".docs-content .docs-lvl2",
    "lvl3": ".docs-content .docs-lvl3", 
    "lvl4": ".docs-content .docs-lvl4",
    "lvl5": ".docs-content .docs-lvl5",
    "lvl6": ".docs-content .docs-lvl6",
    "text": ".docs-content p, .docs-content li"
  }
}

index_uid字段是您的Meilisearch实例中存储网站内容的索引标识符。如果该索引不存在,爬虫工具会创建一个新的索引。

docs-content类(.表示这是一个类)在本例中是文本内容的主要容器。大多数情况下,这个标签是一个<main>或<article> HTML元素。

lvlX选择器应该使用标准的标题标签,如h1、h2、h3等。您也可以使用静态类。为这些元素设置唯一的id或name属性。

在主文档容器之外的每个可搜索的lvl元素(例如,在侧边栏中)必须是global选择器。它们将被全局选取并注入到从您的页面构建的每个文档中。

您还可以查看我们在生产环境中用于自己的文档网站的配置文件。

💡 要更好地理解选择器,请转到本节。

🔨 配置文件中还有许多其他字段可以设置,允许您根据需要调整爬虫。查看本节了解更多信息。

运行爬虫

从源代码运行

该项目支持Python 3.8及以上版本。

必须安装pipenv命令。

设置环境变量MEILISEARCH_HOST_URL和MEILISEARCH_API_KEY。
按照第一步中的示例,它们分别是http://localhost:7700和myMasterKey。

然后,运行:

pipenv install
pipenv run ./docs_scraper <path-to-your-config-file>

<path-to-your-config-file>应该是您在上一步中定义的配置文件的路径。

使用Docker

docker run -t --rm \
    -e MEILISEARCH_HOST_URL=<your-meilisearch-host-url> \
    -e MEILISEARCH_API_KEY=<your-meilisearch-api-key> \
    -v <absolute-path-to-your-config-file>:/docs-scraper/<path-to-your-config-file> \
    getmeili/docs-scraper:latest pipenv run ./docs_scraper <path-to-your-config-file>

<absolute-path-to-your-config-file>应该是您在上一步中定义的配置文件的绝对路径。

⚠️ 如果您在本地运行Meilisearch,必须在此Docker命令中添加--network=host选项。

在GitHub Action中运行

在部署作业之后运行:

run-scraper:
    needs: <your-deployment-job>
    runs-on: ubuntu-18.04
    steps:
    - uses: actions/checkout@master
    - name: Run scraper
      env:
        HOST_URL: ${{ secrets.MEILISEARCH_HOST_URL }}
        API_KEY: ${{ secrets.MEILISEARCH_API_KEY }}
        CONFIG_FILE_PATH: <path-to-your-config-file>
      run: |
        docker run -t --rm \
          -e MEILISEARCH_HOST_URL=$HOST_URL \
          -e MEILISEARCH_API_KEY=$API_KEY \
          -v $CONFIG_FILE_PATH:/docs-scraper/<path-to-your-config-file> \
          getmeili/docs-scraper:latest pipenv run ./docs_scraper <path-to-your-config-file>

⚠️ 我们不建议在生产环境中使用latest镜像。请使用发布标签。

这是我们在生产环境中用于Meilisearch文档的GitHub Action文件。

关于API密钥

您必须提供的API密钥应具有向Meilisearch实例添加文档的权限。
在生产环境中,我们建议提供私钥而不是主密钥,因为它更安全,并且具有足够的权限执行此类请求。

更多关于Meilisearch身份验证的信息。

🖌 前端搜索栏呢?

爬取文档后,您可能需要一个搜索栏来改善用户体验!

关于前端部分:

如果您的网站是VuePress应用程序,请查看vuepress-plugin-meilisearch仓库。
对于所有类型的文档,请查看docs-searchbar.js库。

这两个库都提供了一个完美适合文档的前端搜索栏。

docs-searchbar-demo

🛠 更多配置

关于选择器的更多信息

基础

简单来说,选择器用于告诉爬虫"我想获取这个HTML标签中的内容"。
这个HTML标签就是一个选择器。

选择器可以是:

一个类(例如.main-content)
一个id(例如#main-article)
一个HTML标签(例如h1)

一个更具体的例子:

"lvl0": {
    "selector": ".navbar-nav .active",
    "global": true,
    "default_value": "文档"
},

.navbar-nav .active表示"获取类navbar-nav中类active的内容"。

global: true表示您希望所有从同一页面提取的内容都使用相同的lvl0(也就是相同的主标题)。

如果在.navbar-nav .active中没有找到内容,将显示"default_value": "文档"。

注意:您可以为每个选择器级别(lvlX)设置global和default_value属性,而不仅仅是lvl0。

级别

您可以注意到配置文件中有不同级别的选择器(0到最多6级)。它们对应于不同级别的标题,并将以这种方式显示: 选择器显示

您的数据将以主标题（lvl0）、副标题（lvl1）、次级副标题（lvl2）等方式显示...

所有配置文件设置

`index_uid`

index_uid字段是您的Meilisearch实例中存储网站内容的索引标识符。如果该索引不存在，抓取工具将创建一个新索引。

{
  "index_uid": "example"
}

`start_urls`

这个数组包含用于开始抓取您网站的URL列表。抓取器将从这些页面递归地跟随任何链接（<a>标签）。它不会跟随其他域名上的链接。

{
  "start_urls": ["https://www.example.com/docs"]
}

使用页面排名

此参数为某些页面赋予更多权重，有助于提升从该页面构建的记录。具有最高page_rank的页面将在具有较低page_rank的页面之前返回。

{
  "start_urls": [
    {
      "url": "http://www.example.com/docs/concepts/",
      "page_rank": 5
    },
    {
      "url": "http://www.example.com/docs/contributors/",
      "page_rank": 1
    }
  ]
}

在这个例子中，从概念页面构建的记录将比从贡献者页面提取的结果排名更高。

`stop_urls`（可选）

抓取器不会跟随与stop_urls匹配的链接。

{
  "start_urls": ["https://www.example.com/docs"],
  "stop_urls": ["https://www.example.com/about-us"]
}

`selectors_key`（可选）

这允许您为每个页面使用自定义选择器。

如果您的网站标记在不同页面之间差异很大，以至于无法使用通用选择器，您可以为选择器添加命名空间，并指定应将哪组选择器应用于特定页面。

{
  "start_urls": [
    "http://www.example.com/docs/",
    {
      "url": "http://www.example.com/docs/concepts/",
      "selectors_key": "concepts"
    },
    {
      "url": "http://www.example.com/docs/contributors/",
      "selectors_key": "contributors"
    }
  ],
  "selectors": {
    "default": {
      "lvl0": ".main h1",
      "lvl1": ".main h2",
      "lvl2": ".main h3",
      "lvl3": ".main h4",
      "lvl4": ".main h5",
      "text": ".main p"
    },
    "concepts": {
      "lvl0": ".header h2",
      "lvl1": ".main h1.title",
      "lvl2": ".main h2.title",
      "lvl3": ".main h3.title",
      "lvl4": ".main h5.title",
      "text": ".main p"
    },
    "contributors": {
      "lvl0": ".main h1",
      "lvl1": ".contributors .name",
      "lvl2": ".contributors .title",
      "text": ".contributors .description"
    }
  }
}

在这里，所有文档页面将使用selectors.default中定义的选择器，而./concepts下的页面将使用selectors.concepts，./contributors下的页面将使用selectors.contributors。

`scrape_start_urls`（可选）

默认情况下，抓取器将从start_urls中定义的页面提取内容。如果您的起始URL没有任何有价值的内容，或者它是另一个页面的重复，您应该将此设置为false。

{
  "scrape_start_urls": false
}

`sitemap_urls`（可选）

您可以传递一个指向您的网站地图文件的URL数组。如果设置了此值，抓取器将尝试从您的网站地图读取URL。

{
  "sitemap_urls": ["http://www.example.com/docs/sitemap.xml"]
}

`sitemap_alternate_links`（可选）

网站地图可以包含URL的替代链接。这些是同一页面的其他版本，可能是不同的语言或不同的URL。默认情况下，docs-scraper将忽略这些URL。

如果您希望这些其他版本也被抓取，请将此设置为true。

{
  "sitemap_urls": ["http://www.example.com/docs/sitemap.xml"],
  "sitemap_alternate_links": true
}

使用上述配置和下面的sitemap.xml，http://www.example.com/docs/和http://www.example.com/docs/de/都将被抓取。

<url>
  <loc>http://www.example.com/docs/</loc>
  <xhtml:link rel="alternate" hreflang="de" href="http://www.example.com/de/"/>
</url>

`selectors_exclude`（可选）

这需要一个CSS选择器数组。任何匹配这些选择器之一的元素将在提取任何数据之前从页面中移除。

这可用于移除目录、侧边栏或页脚，以使其他选择器更容易编写。

{
  "selectors_exclude": [".footer", "ul.deprecated"]
}

`custom_settings`（可选）

此字段可用于添加Meilisearch设置。

示例：

"custom_settings": {
    "synonyms": {
      "static site generator": [
        "ssg"
      ],
      "ssg": [
        "static site generator"
      ]
    },
    "stopWords": ["of", "the"],
    "filterableAttributes": ["genres", "type"]
  }

在Meilisearch文档中了解更多关于filterableAttributes、synonyms、stop-words和所有可用设置的信息。

`min_indexed_level`（可选）

默认值为0。通过增加它，如果记录没有足够的lvlX匹配，您可以选择不索引某些记录。例如，使用min_indexed_level: 2，抓取器只会索引至少设置了lvl0、lvl1和lvl2的临时记录。

当您的文档中有页面共享相同的lvl0和lvl1时，这很有用。在这种情况下，您不希望索引所有共享的记录，而是希望保持跨页面的内容差异。

{
  "min_indexed_level": 2
}

`only_content_level`（可选）

当only_content_level设置为true时，抓取器不会为lvlX选择器创建记录。如果使用此选项，将忽略min_indexed_level。

{
  "only_content_level": true
}

`js_render`（可选）

当js_render设置为true时，抓取器将使用ChromeDriver。这对于使用JavaScript渲染的页面是必需的，例如使用React、Vue生成的页面，或在开发模式下运行的应用程序：autoreload watch。

安装ChromeDriver后，使用以下环境变量CHROMEDRIVER_PATH提供bin的路径（默认值为/usr/bin/chromedriver）。

js_render的默认值为false。

{
  "js_render": true
}

`js_wait`（可选）

当 js_render 设置为 true 且页面需要时间完全加载时，可以使用此设置。js_wait 接受一个整数，指定爬虫应等待页面加载的秒数。

{
  "js_render": true,
  "js_wait": 1
}

`allowed_domains`（可选）

此设置指定爬虫允许访问的域名。在大多数情况下，allowed_domains 将使用 start_urls 和 stop_urls 自动设置。当爬取包含端口的域名时，例如 http://localhost:8080，需要手动将域名添加到配置中。

{
  "allowed_domains": ["localhost"]
}

身份验证

警告： 请注意，爬虫将向每个被爬取的站点发送身份验证头，因此请使用 allowed_domains 相应地调整范围！

基本 HTTP 身份验证

通过设置以下环境变量支持基本 HTTP 身份验证：

DOCS_SCRAPER_BASICAUTH_USERNAME
DOCS_SCRAPER_BASICAUTH_PASSWORD

Cloudflare Access：身份和访问管理

如果您需要爬取受 Cloudflare Access 保护的网站，您必须设置适当的 HTTP 头。

这些头的值来自环境变量 CF_ACCESS_CLIENT_ID 和 CF_ACCESS_CLIENT_SECRET。

对于 Google Cloud Identity-Aware Proxy，请指定以下环境变量：

IAP_AUTH_CLIENT_ID - # 选择您要连接的应用程序的客户端 ID
IAP_AUTH_SERVICE_ACCOUNT_JSON - # 在操作中生成 -> 创建密钥 -> JSON

Keycloak Access：身份和访问管理

如果您需要爬取受 Keycloak（Gatekeeper）保护的网站，您必须提供有效的访问令牌。

如果设置环境变量 KC_URL、KC_REALM、KC_CLIENT_ID 和 KC_CLIENT_SECRET，爬虫将使用客户端凭证授权方式向 Keycloak 进行身份验证，并将生成的访问令牌作为 Authorization HTTP 头添加到每个爬取请求中。

安装 Chrome Headless

需要 JavaScript 渲染的网站通过 ChromeDriver 处理。下载适合您操作系统的版本，然后设置环境变量 CHROMEDRIVER_PATH。

🤖 与 Meilisearch 的兼容性

本包保证与 Meilisearch v1.x 版本兼容，但某些功能可能不存在。请查看问题了解更多信息。

⚙️ 开发工作流程和贡献

我们非常欢迎在这个项目中提出任何新的贡献！

如果您想了解更多关于开发工作流程的信息或想要贡献，请访问我们的贡献指南以获取详细说明！

致谢

基于 Algolia 的 docsearch 爬虫仓库的此提交。由于本仓库相比原始仓库将有许多未来变更，我们不将其维护为官方分支。

Meilisearch 提供并维护许多 SDK 和集成工具，如本工具。我们希望为各种项目提供卓越的搜索体验。如果您想贡献、提出建议或了解当前进展，请访问我们的 integration-guides 仓库。

docs-scraper

docs-scraper

Meilisearch | Meilisearch Cloud | 文档 | Discord | 路线图 | 网站 | 常见问题

目录

⚡ 提升你的Meilisearch体验

⚙️ 使用方法

运行你的Meilisearch实例

设置你的配置文件

运行爬虫

从源代码运行

使用Docker

在GitHub Action中运行

关于API密钥

🖌 前端搜索栏呢?

🛠 更多配置

关于选择器的更多信息

基础

级别

所有配置文件设置

index_uid

start_urls

使用页面排名

stop_urls（可选）

selectors_key（可选）

scrape_start_urls（可选）

sitemap_urls（可选）

sitemap_alternate_links（可选）

selectors_exclude（可选）

custom_settings（可选）

示例：

min_indexed_level（可选）

only_content_level（可选）

js_render（可选）

js_wait（可选）

allowed_domains（可选）

身份验证

基本 HTTP 身份验证

Cloudflare Access：身份和访问管理

Keycloak Access：身份和访问管理

安装 Chrome Headless

🤖 与 Meilisearch 的兼容性

⚙️ 开发工作流程和贡献

致谢

`index_uid`

`start_urls`

`stop_urls`（可选）

`selectors_key`（可选）

`scrape_start_urls`（可选）

`sitemap_urls`（可选）

`sitemap_alternate_links`（可选）

`selectors_exclude`（可选）

`custom_settings`（可选）

`min_indexed_level`（可选）

`only_content_level`（可选）

`js_render`（可选）

`js_wait`（可选）

`allowed_domains`（可选）