.. _wagtailsearch_backends:

========
底层平台
========

Wagtailsearch 支持搜索功能使用不同的底层平台。开发者可使用数据库，也可以使用外部的搜索引擎例如 Elasticsearch。缺省情况下使用数据库。

底层搜索平台通过配置文件中的 ``WAGTAILSEARCH_BACKENDS`` 选项定义：

.. code-block:: python

  WAGTAILSEARCH_BACKENDS = {
      'default': {
          'BACKEND': 'wagtail.search.backends.db',
      }
  }


.. _wagtailsearch_backends_auto_update:

``AUTO_UPDATE``
===============

缺省情况下，Wagtail 将自动更新索引为最新变更的内容。这将会影响编辑内容时的性能，特别是索引存贮在外部服务上面。

``AUTO_UPDATE`` 允许按每类索引禁用自动索引功能：

.. code-block:: python

  WAGTAILSEARCH_BACKENDS = {
      'default': {
          'BACKEND': ...,
          'AUTO_UPDATE': False,
      }
  }

禁用自动索引功能后，需要周期性执行 :ref:`update_index` 命令来保持外部索引与数据的内容同步。


.. _wagtailsearch_backends_atomic_rebuild:

``ATOMIC_REBUILD``
==================

.. warning::
    这个选项不同工作在 Elasticsearch 版本 5.4.x，原因参考 `a bug in the handling of aliases <https://github.com/elastic/elasticsearch/issues/24644>`_ - 需要 Elasticsearch 升级到 5.5 之上。

缺省情况下 (使用 Elasticsearch 平台), 运行 ``update_index`` 命令执行时，Wagtail 先删除索引内容并重新构建。这将会导致命令在执行期间，查询匹配不成功，并且在发生错误的情况下不能回滚。

为了防止这种情况，将 ``ATOMIC_REBUILD`` 选项设为 ``True``，Wagtail 会重构一个新索引，在重构完成前不会删除原来索引。在构建完成后切换到新索引并删除老索引。

``BACKEND``
===========

下面是 Wagtail 搭建完成后支持的底层平台。

.. _wagtailsearch_backends_database:

数据库平台 (缺省)
--------------------------

``wagtail.search.backends.db``

使用数据库做为搜索平台，主要用于开发或小型站点上。查询结果不能结合相关性排序，在大量页面情况下搜索结果可用性较低。

不支持以下功能：

 - 不能搜索 ``Page`` 子类中定义的字段， (除非直接查询)
 - :ref:`wagtailsearch_indexing_callable_fields`
 - Converting accented characters to ASCII

如果这几点功能对你很重要，推荐使用 Elasticsearch 搜索平台。

.. _wagtailsearch_backends_postgresql:

PostgreSQL 平台
------------------

``wagtail.contrib.postgres_search.backend``

如果使用 PostgreSQL 做为数据库，并且网站页面小于百万级别，可以使用这个搜索平台。

更多说明请参考 :ref:`postgres_search`。


.. _wagtailsearch_backends_elasticsearch:

Elasticsearch 平台
---------------------

支持 Elasticsearch versions 2, 5, 6 及 7 版本。请选择如下对应的后台接口版本：

``wagtail.search.backends.elasticsearch2`` (Elasticsearch 2.x)

``wagtail.search.backends.elasticsearch5`` (Elasticsearch 5.x)

``wagtail.search.backends.elasticsearch6`` (Elasticsearch 6.x)

``wagtail.search.backends.elasticsearch7`` (Elasticsearch 7.x)

使用 `Elasticsearch`_ 服务需要先安装相关服务，并且通过 pip 安装 `elasticsearch-py`_ 软件包。
软件包的版本应匹配 Elasticsearch 的版本：

.. _Elasticsearch: https://www.elastic.co/downloads/elasticsearch

.. code-block:: console

  $ pip install "elasticsearch>=2.0.0,<3.0.0"  # for Elasticsearch 2.x

.. code-block:: sh

  pip install "elasticsearch>=5.0.0,<6.0.0"  # for Elasticsearch 5.x

.. code-block:: sh

  pip install "elasticsearch>=6.4.0,<7.0.0"  # for Elasticsearch 6.x

.. code-block:: sh

  pip install "elasticsearch>=7.0.0,<8.0.0"  # for Elasticsearch 7.x

.. warning::

    | 注意  6.3.1 的 Elasticsearch 客户端版本不兼容 Wagtail。请使用 6.4.0 及以上版本。


配置文件中的后台设置为：

.. code-block:: python

  WAGTAILSEARCH_BACKENDS = {
      'default': {
          'BACKEND': 'wagtail.search.backends.elasticsearch2',
          'URLS': ['http://localhost:9200'],
          'INDEX': 'wagtail',
          'TIMEOUT': 5,
          'OPTIONS': {},
          'INDEX_SETTINGS': {},
      }
  }

除了 ``BACKEND``, 其它关键是可选的，缺省值是上述值。定义在 ``OPTIONS`` 的关键字直接传给 Elasticsearch，注意大小写的区分 (例如：``'max_retries': 1``)。

用户名和密码可以放在 ``URL`` 字段中以做认证字段传给 Elasticsearch 服务：

.. code-block:: python

  WAGTAILSEARCH_BACKENDS = {
      'default': {
          ...
          'URLS': ['http://username:password@localhost:9200'],
          ...
      }
  }

``INDEX_SETTINGS`` 描述创建索引时的缺省设置。 ``ElasticsearchSearchBackend`` 类中的
缺省设置定义在 ``wagtail/wagtail/wagtailsearch/backends/elasticsearch.py`` 文件中。
下面例子说明配置 shards 的数量，并将 Italian LanguageAnalyzer 设为缺省的分析器：

.. code-block:: python

  WAGTAILSEARCH_BACKENDS = {
      'default': {
          ...,
          'INDEX_SETTINGS': {
              'settings': {
                  'index': {
                      'number_of_shards': 1,
                  },
                  'analysis': {
                      'analyzer': {
                          'default': {
                              'type': 'italian'
                          }
                      }
                  }
              }
          }
      }

在开发或生产环境中如果自已不搭建 Elasticsearch 服务器，可以使用很多云服务器，包括 `Bonsai`_，提供的免费账号足够用来测试及开发。要使用 Bonsai 服务：

-  注册 `Bonsai`_ 账号
-  使用 Bonsai 管理员面板创建集群。
-  配置 ``WAGTAILSEARCH_BACKENDS`` 中的 Elasticsearch ``URLS`` 使用配置好的集群地址。
-  运行 ``./manage.py update_index``

.. _elasticsearch-py: https://elasticsearch-py.readthedocs.org
.. _Bonsai: https://bonsai.io/signup

Amazon AWS Elasticsearch
~~~~~~~~~~~~~~~~~~~~~~~~

Elasticsearch 后台接口兼容 `Amazon Elasticsearch Service`_, 但是需要增加一些处理 IAM 授权的配置项，这需要安装 `requests-aws4auth`_ 软件包，并使用如下配置：

.. code-block:: python

  from elasticsearch import RequestsHttpConnection
  from requests_aws4auth import AWS4Auth

  WAGTAILSEARCH_BACKENDS = {
      'default': {
          'BACKEND': 'wagtail.search.backends.elasticsearch2',
          'INDEX': 'wagtail',
          'TIMEOUT': 5,
          'HOSTS': [{
              'host': 'YOURCLUSTER.REGION.es.amazonaws.com',
              'port': 443,
              'use_ssl': True,
              'verify_certs': True,
              'http_auth': AWS4Auth('ACCESS_KEY', 'SECRET_KEY', 'REGION', 'es'),
          }],
          'OPTIONS': {
              'connection_class': RequestsHttpConnection,
          },
      }
  }

.. _Amazon Elasticsearch Service: https://aws.amazon.com/elasticsearch-service/
.. _requests-aws4auth: https://pypi.python.org/pypi/requests-aws4auth


使用自已的引擎
----------------

Wagtail 后台接口定义在 ``wagtail/wagtail/wagtailsearch/backends/base.py`` 中。最小实现是在后端的 ``search()`` 方法中返回搜索结果对象集合，
为空时返回 ``model.objects.none()``。 要实现一个全功能搜索引擎，参考 ``elasticsearch.py`` 的实现代码。