前言: Algolia 是什么？#

Algolia 是一个搜索、推荐服务平台，可以通过简单的配置来为站点添加全文检索功能

基本原理：

通过爬虫对目标网站的内容创建 Records (记录), 在用户搜索时调用接口返回相关内容

一. 需求描述#

为网站添加实时搜索, 采用 Docusaurus2 官方支持的 Algolia DocSearch

Docsearch 每周一次爬取网站 (可在网页界面上配置具体时间), 并将所有内容汇总到一个 Algolia 索引中

随后，前端页面会调用 Algolia API 来直接查询这些内容

Docusaurus 搜索功能文档

二. 准备工作#

Docsearch 官网申请前置条件:

准备项目域名地址 - 本案例: https://wiki.chn.gg/

备注如没有服务器和域名也可用 GitHub Pages

前置条件准备完成后, 就可到 Docsearch 注册

提交后大约 2 天内会收到反馈邮件, 通知注册成功

获取 Application ID & API Keys 前往 Algolia 官网, 登录账户创建 Application

设置 Application 名称, 选择免费计划

最后选择响应速度快的服务后, 创建成功 ✅

控制台打开设置页面，点击 API keys

找到接下来本地配置需要的数据

三. 本地 Algolia Docsearch 配置#

.env (键值不带双引号)

1
APPLICATION_ID=Application ID
2
API_KEY=Admin API Key # 务必确认, 这是坑点 不要用 'Write API Key' 或者 'Search API Key'

docusaurus.config.js

1
module.exports = {
2
  // ...
3
  presets: [
4
    [
5
      // ...
6
      'classic',
7
      /** @type {import('@docusaurus/preset-classic').Options} */
8
      ({
9
        // 这个插件会为你的站点创建一个站点地图
10
        // 以便搜索引擎的爬虫能够更准确地爬取你的网站
11
        sitemap: {
12
          changefreq: 'weekly',
13
          priority: 0.5,
14
          ignorePatterns: ['/tags/**'],
15
          filename: 'sitemap.xml',
16
        },
17
      }),
18
    ],
19
  ],
20
  // ...
21
  themeConfig: {
22
    // ...
23
    algolia: {
24
      appId: 'YOUR_APP_ID', // Application ID
25
      //  公开 API密钥：提交它没有危险
26
      apiKey: 'YOUR_SEARCH_API_KEY', //  Search-Only API Key
27
      indexName: 'YOUR_INDEX_NAME',
28
    },
29
  },
30
};

Algolia DocSearch 插件文档

sitemap 插件文档

docsearch-config.json (爬虫配置文件)

需修改 3 处:

index_name
start_urls
sitemap_urls

1
{
2
  "index_name": "wiki",
3
  "start_urls": ["https://wiki.chn.gg/"],
4
  "sitemap_urls": ["https://wiki.chn.gg/sitemap.xml"],
5
  "sitemap_alternate_links": true,
6
  "stop_urls": ["/tests"],
7
  "selectors": {
8
    "lvl0": {
9
      "selector": "(//ul[contains(@class,'menu__list')]//a[contains(@class, 'menu__link menu__link--sublist menu__link--active')]/text() | //nav[contains(@class, 'navbar')]//a[contains(@class, 'navbar__link--active')]/text())[last()]",
10
      "type": "xpath",
11
      "global": true,
12
      "default_value": "Documentation"
13
    },
14
    "lvl1": "header h1",
15
    "lvl2": "article h2",
16
    "lvl3": "article h3",
17
    "lvl4": "article h4",
18
    "lvl5": "article h5, article td:first-child",
19
    "lvl6": "article h6",
20
    "text": "article p, article li, article td:last-child"
21
  },
22
  "strip_chars": " .,;:#",
23
  "custom_settings": {
24
    "separatorsToIndex": "_",
25
    "attributesForFaceting": ["language", "version", "type", "docusaurus_tag"],
26
    "attributesToRetrieve": ["hierarchy", "content", "anchor", "url", "url_without_anchor", "type"]
27
  },
28
  "js_render": true,
29
  "conversation_id": ["833762294"],
30
  "nb_hits": 46250
31
}

Algolia 官方用例

四. 执行爬虫程序 - docsearch-scraper#

以下两种爬虫方式任选其一即可 (推荐使用 GitHub Actions)

1. 本地执行爬虫#

前置条件:

Docker
jq - 轻量级命令行 JSON 处理器

使用 brew 安装最新版的 jq

jq 安装完成后, 在命令行执行爬虫脚本

1
docker run -it --env-file=.env -e "CONFIG=$(cat docsearch-config.json | jq -r tostring)" algolia/docsearch-scraper

等待容器运行完成, 如下即可

1
...
2
Getting https://wiki.chn.gg/docs/react/hooks/custom-hooks from selenium
3
Getting https://wiki.chn.gg/docs/react/hooks/useMemo from selenium
4
Getting https://wiki.chn.gg/docs/react/hooks/useCallback from selenium
5
Getting https://wiki.chn.gg/docs/javascript/versions/es-2016 from selenium
6
Getting https://wiki.chn.gg/docs/javascript/versions/es-2015 from selenium
7
> DocSearch: https://wiki.chn.gg/docs/plugins-and-libraries/big-screen/ 17 records)
8
> DocSearch: https://wiki.chn.gg/docs/server/nginx/nginx-forward-proxy-vs-reverse-proxy/ 8 records)
9
> DocSearch: https://wiki.chn.gg/docs/category/caddy/ 3 records)
10
> DocSearch: https://wiki.chn.gg/docs/category/nginx/ 5 records)
11

12
Nb hits: 1369

2. GitHub Actions 执行爬虫#

在 .github/workflows/ 文件夹下创建 docsearch-scraper.yml, 用来定义 GitHub Actions 工作流 docsearch-scraper.yml(使用 vercel 发布)

1
name: 索引爬虫 docsearch-scraper
2

3
on:
4
    deployment_status:
5
#   push:
6
#     branches: [main]
7
#   pull_request:
8
#     branches: [main]
9

10
jobs:
11
    scan:
12
        if: github.event_name == 'deployment_status' && github.event.deployment_status.state == 'success'
13
        runs-on: ubuntu-latest
14

15
        steps:
16
            - name: Sleep for 10 seconds
17
              run: sleep 10s
18
              shell: bash
19

20
            - name: Checkout repo
21
              uses: actions/checkout@v3
22

23
            - name: Run scraper
24
              env:
25
                  APPLICATION_ID: ${{ secrets.APPLICATION_ID }}
26
                  API_KEY: ${{ secrets.API_KEY }}
27
              run: |
28
                  CONFIG="$(cat docsearch-config.json)"
29
                  docker run -i --rm \
30
                          -e APPLICATION_ID=$APPLICATION_ID \
31
                          -e API_KEY=$API_KEY \
32
                          -e CONFIG="${CONFIG}" \
33
                          algolia/docsearch-scraper

docsearch-scraper.yml(使用 github pages 发布)

1
name: 索引爬虫 docsearch-scraper
2

3
on:
4
    push:
5
        branches: [main]
6
    pull_request:
7
        branches: [main]
8

9
jobs:
10
    scan:
11
        runs-on: ubuntu-latest
12

13
        steps:
14
            - name: Sleep for 10 seconds
15
              run: sleep 10s
16
              shell: bash
17

18
            - name: Checkout repo
19
              uses: actions/checkout@v3
20

21
            - name: Run scraper
22
              env:
23
                  APPLICATION_ID: ${{ secrets.APPLICATION_ID }}
24
                  API_KEY: ${{ secrets.API_KEY }}
25
              run: |
26
                  CONFIG="$(cat docsearch-config.json)"
27
                  docker run -i --rm \
28
                          -e APPLICATION_ID=$APPLICATION_ID \
29
                          -e API_KEY=$API_KEY \
30
                          -e CONFIG="${CONFIG}" \
31
                          algolia/docsearch-scraper

然后在 GitHub 的 Secrets 创建

APPLICATION_ID
API_KEY — Admin API Key

当使用 Git 推送项目到 GitHub 时, Actions 就会自动执行爬虫任务

坑点

官网邮件通知创建好的项目是没有管理员权限的

需要在个人主页, 重新创建项目, 注意起名字不要冲突
index_name 需要三处对齐 docsearch-config.json - index_name docusaurus.config.js - indexName Algolia 官网的项目名称 - Application 如: wiki

示例代码#

GitHub Repository

实际效果 - 点击右上角 “搜索”

常见问题#

algoliasearch.exceptions.RequestException: Method not allowed with this API key

提示这个错误通常表示您在使用 Algolia Search API 时使用了无效的 API 密钥或 API 密钥权限不允许使用该请求方法

分析使用的 key 不对 - 当前使用的也许是 Search-Only API Key
解决方法改为使用 Admin API Key

2.Error: Process completed with exit code 3.

提示由于尝试使用 Algolia Search API 更新对象时所使用的 API 密钥缺少必要的权限

确认您正在使用具有正确权限的 Algolia Search API 密钥来更新对象

分析使用的 key 权限不对 - 当前使用的也许是 Write API Key
解决方法改为使用 Admin API Key

本地执行爬虫脚本, 报错: Error: Cannot find module ‘winston’

使用 yarn 重新安装 winston

1
yarn global remove winston
2

3
yarn global add winston

本地执行爬虫脚本, 报错: Error: { cli } was removed in winston@3.0.0.

1
# 查看本地的 全局依赖是否存在 jq (yarn)
2
yarn global list --depth=0
3

4
# 删除 jq依赖
5
yarn global remove jq

本地执行爬虫脚本, 报错: zsh: command not found: jq 确保本地 npm, yarn, pnpm 的全局依赖中没有 jq, 使用 brew 安装

1
# 安装最新版 jq
2
brew install --HEAD jq
3
# 链接 最新版 jq
4
brew link jq

参考链接