Дополнительная информация
Оглавление
Система поиска на стороне сервера состоит из двух основных компонентов:
-
Dr.Explain Search Backend Controller: обрабатывает HTTP-запросы от браузеров и других клиентов и взаимодействует с поисковым движком Apache Solr (см. далее).
-
Apache Solr: поисковый движок, к которому подключены специальные библиотеки и словари для поддержки лемматизации (приведения слов к словарной форме) и синонимов.
-
Сервер с 4 ГБ оперативной памяти и 3 ГБ дискового пространства.
-
Установленный Docker Compose.
-
Веб-сервер (например, nginx или Apache).
-
Каталог с экспортированными HTML-файлами.
Вы можете разместить HTML-файлы на одном сервере, а установить поисковый движок на другом. В этом случае необходимо:
-
Указать поисковому движку, как загружать HTML-файлы.
-
Настроить перенаправление HTTP-запросов, содержащих /drexsearch/, на поисковый движок.
Чтобы загружать HTML-файлы по URL, отредактируйте файл docker-compose.yaml: под drexplain-search-backend-controller отыщите и удалите раздел volumes, а в разделе environment укажите URL-адреса вместо путей.
environment:
- DREX_CONTENT_ROOT_URL_EN=https://ваш-сайт.com/docs-en/
- DREX_CONTENT_ROOT_URL_ES=https://ваш-сайт.com/docs-ru/
Для перенаправления HTTP-запросов на поиск у вас есть два варианта в зависимости от того, можете ли вы изменить конфигурацию веб-сервера, на котором размещены ваши HTML-файлы.
Вариант 1: Перенаправление HTTP-запросов, содержащих /drexsearch/, на поисковый движок самим веб-сервером, на котором размещены HTML-файлы
В разделе ports файла docker-compose.yaml укажите порты без части "127.0.0.1:":
ports:
# ВНИМАНИЕ: это сделает сервис доступным на всех сетевых интерфейсах.
# Убедитесь, что у вас настроены надлежащие правила файрвола.
- "8082:8082"
В конфигурации вашего веб-сервера замените "127.0.0.1:" на адрес сервера, на котором размещен поисковый движок. Примечание: связь между вашим веб-сервером и поисковым движком будет осуществляться по незашифрованному протоколу HTTP. Убедитесь, что оба сервера подключены к одной локальной или защищенной сети (например, через VPN).
Перезапустите поисковый движок:
docker compose down
docker compose up -d
Вариант 2: Перенаправление HTTP-запросов, содержащих /drexsearch/, на поисковый движок с помощью веб-сервера, на котором размещен поисковый движок
При использовании этого метода вам потребуется установить веб-сервер на том же сервере, что и поисковый движок, затем настроить его для перенаправления запросов, содержащих /drexsearch/, на поисковый движок, и указать URL этого веб-сервера в настройках HTML экспорта:
-
Установите флажок Поисковый движок и HTML-файлы размещены на разных серверах.
-
Укажите URL-адрес сервера поискового движка в поле URL-адрес сервера с поисковым движком.
-
Экспортируйте проект в HTML и опубликуйте экспортированные файлы на вашем веб-сервере.
Функциональность поиска легко настраивается с помощью параметров (см. ниже). Чтобы использовать настройки:
-
Создайте файл с именем .env и поместите его в ту же папку, где находится docker-compose.yaml.
-
Скопируйте и вставьте необходимые строки в этот файл .env.
-
Отредактируйте docker-compose.yaml, добавив раздел env_file под drexplain-search-backend-controller:
drexplain-search-backend-controller:
env_file: ".env"
image: ghcr.io/indigobyte/dsb-controller:latest
...
Как вариант, вместо создания файла .env, вы можете указать необходимые настройки в разделе environment файла docker-compose.yaml:
drexplain-search-backend-controller:
environment:
- DSBC_JAVA_MAX_HEAP_SIZE=150m
- SEARCH_OCCURRENCE_BOOST_TITLE=1
Полный список настроек (в формате, удобном для копирования и вставки):
# Это порт, на который необходимо перенаправлять все входящие HTTP-запросы вида /drexsearch/ЧТО-ЛИБО
# например: https://ваш-сайт.com/любое/количество/ваших/подпапок/drexsearch/что-либо на http://127.0.0.1:ЭТОТ_ПОРТ/ЧТО-ЛИБО
DSBC_PORT=8082
# Укажите здесь URL-адреса или смонтированные пути к HTML-файлам, экспортированным Dr.Explain. Например, если какой-то раздел доступен по адресу
# https://ваш-сайт.com/manual/некий-раздел.html, напишите DREX_CONTENT_ROOT_URL_1=https://ваш-сайт.com/manual/
# Убедитесь, что все URL-адреса правильно экранированы в соответствии со стандартом RFC 3986 и что для доменов с не-ASCII символами используется punycode-
# имена. Например, вы можете открыть консоль инструментов разработчика в браузере и выполнить внутри неё следующую команду
# (заменить своим URL):
# new URL("https://ваш-сайт.com/manual/некий путь с пробелами и другими специальными символами/").href
# Используйте полученный URL-адрес.
DREX_CONTENT_ROOT_URL_1=https://ваш-сайт.com/docs/
DREX_CONTENT_ROOT_URL_2=https://ваш-сайт.com/docs-en/
DREX_CONTENT_ROOT_URL_3=https://ваш-сайт.com/docs-ru/
# Путь к логам внутри контейнера Dr.Explain Search Backend Controller. Сюда внутри контейнера
# монтируется DSB_LOG_EXT_PATH.
DSB_LOG_INT_PATH=/var/logs/dsbc
# Поддерживаемые уровни (от низшего к высшему): TRACE, DEBUG, INFO, WARN, ERROR, FATAL. Установка уровня DEBUG или TRACE
# не рекомендуется и может привести к снижению производительности.
# Должен соответствовать (или быть выше) DSBC_LOG_LEVEL_ROOT.
DSBC_LOG_LEVEL_LOGIC=INFO
# Поддерживаемые уровни (от низшего к высшему): TRACE, DEBUG, INFO, WARN, ERROR, FATAL. Установка уровня DEBUG или TRACE
# не рекомендуется и может привести к снижению производительности.
DSBC_LOG_LEVEL_ROOT=INFO
# Максимальный размер одного файла логов, после которого выполняется его ротация, в байтах.
DSBC_LOG_MAX_SIZE=1048576
# Максимальное количество сохраняемых ротированных версий одного файла логов.
DSBC_LOG_MAX_HISTORY=100
# Максимальный размер Java heap для приложения Dr.Explain Search Backend Controller.
DSBC_JAVA_MAX_HEAP_SIZE=128m
DSBC_JAVA_MAX_METASPACE_SIZE=10m
DSBC_JAVA_MAX_DIRECT_MEMORY_SIZE=2m
DSBC_JAVA_RESERVED_CODE_CACHE_SIZE=8m
DSBC_JAVA_THREAD_STACK_SIZE=512k
# Порт обычного HTTP-прокси, который Dr.Explain Search Backend Controller использует для связи с поисковой системой и внешним миром,
# например, для загрузки файлов с веб-сайтов, содержащих HTML-файлы, экспортированные из Dr.Explain, при использовании переменных окружения
# DREX_CONTENT_ROOT_URL_XXX (см. ниже). Установка HTTP_PROXY_PORT в значение 0 отключает HTTP прокси и
# заставляет Dr.Explain Search Backend Controller игнорировать все остальные настройки HTTP_PROXY_XXX (то есть все HTTP-запросы будут
# отправляться напрямую, минуя прокси).
HTTP_PROXY_PORT=0
# Хост HTTP-прокси. Игнорируется, если HTTP_PROXY_PORT равен 0. Для работы host.docker.internal
# на Linux может потребоваться дополнительная настройка. Обратитесь к документации Docker.
HTTP_PROXY_HOST=host.docker.internal
# Установите значение true, чтобы отслеживать HTTPS-запросы через MitM-прокси.
HTTP_PROXY_ALLOW_SELF_SIGNED_CERTIFICATES=false
# Эти настройки заставляют Dr.Explain Search Backend Controller возвращать подробную информацию об ошибках,
# возникающих при обработке HTTP-запросов (когда это возможно).
DSBC_REST_PRINT_PROBLEM_DETAILS=false
DSBC_REST_SERVER_ERROR_INCLUDE_BINDING_ERRORS=never
DSBC_REST_SERVER_ERROR_INCLUDE_EXCEPTION=false
DSBC_REST_SERVER_ERROR_INCLUDE_MESSAGE=never
DSBC_REST_SERVER_ERROR_INCLUDE_STACKTRACE=never
# Настройки подключения к серверу поисковой системы.
DSBC_SEARCH_SERVER_SCHEME=http
DSBC_SEARCH_SERVER_HOST=solr
DSBC_SEARCH_SERVER_PORT=8983
# Учётные данные поисковой системы. Поисковая система недоступна за пределами стека Docker Compose,
# поэтому использовать учётные данные Solr по умолчанию безопасно. После обновления учётных данных необходимо удалить старые данные с помощью команды "docker compose down -v"
# и перезапустить Dr.Explain Search Backend.
DSBC_SEARCH_SERVER_USER=solr
DSBC_SEARCH_SERVER_PASSWORD=SolrRocks
# Это префикс, используемый для того, чтобы отличать поисковые индексы, созданные Dr.Explain Search Backend, от всех остальных индексов.
# Когда Dr.Explain Search Backend обновляет индексы, он удаляет все старые индексы, названия которых начинаются с этого префикса.
# Если вы используете одну и ту же поисковую систему для нескольких экземпляров Dr.Explain Search Backend, задайте уникальное значение для каждого экземпляра,
# чтобы они не мешали поисковым индексам друг друга.
DSBC_SEARCH_INDEX_PREFIX=drex-
# Максимальная длина подсвечиваемого фрагмента (сниппета поиска) в символах. Установка этого значения в 0 приведёт к тому,
# что в сниппетах будет отображаться текст всего раздела.
SEARCH_HIGHLIGHT_FRAGMENT_SIZE=100
# Если описание раздела не содержит поискового запроса (например, он есть только в заголовке),
# то сниппеты поиска будут содержать первые SEARCH_DESCRIPTION_PREVIEW_MAX_LENGTH символов описания раздела.
SEARCH_DESCRIPTION_PREVIEW_MAX_LENGTH=200
# Множитель, применяемый к весу (релевантности) совпадений поискового запроса в заголовке раздела.
SEARCH_OCCURRENCE_BOOST_TITLE=2
# Множитель, применяемый к весу (релевантности) совпадений поискового запроса в описании раздела.
SEARCH_OCCURRENCE_BOOST_DESCRIPTION=1
# Множитель, применяемый к весу (релевантности) частичных совпадений поискового запроса (т.е. когда слово из поискового запроса содержится внутри другого слова,
# например, при поиске "документ" слово "документация" является частичным совпадением).
SEARCH_OCCURRENCE_BOOST_PARTIAL=0.5
# Коэффициент, применяемый к точным совпадениям поискового запроса, т.е. когда текст раздела содержит точные слова из поискового запроса
# в любом порядке (без учёта регистра).
SEARCH_OCCURRENCE_BOOST_EXACT=5
# Коэффициент, применяемый к точным совпадениям поискового запроса, т.е. когда текст раздела содержит точные слова из поискового запроса
# в том же порядке, без других слов между ними (без учёта регистра).
SEARCH_OCCURRENCE_BOOST_EXACT_PHRASE=10
# Результаты поиска с релевантностью ниже минимального значения отображаться не будут.
SEARCH_MIN_SCORE=0.0
# Максимальное количество результатов поиска, возвращаемых за один раз. Значение больше 20 может привести к повышенному потреблению памяти
# и увеличению времени отклика.
SEARCH_MAX_PAGE_SIZE=20
# Определяет задержку в секундах между попытками опроса для проверки
# инициализации поискового индекса после отправки команды создания.
SEARCH_INDEX_CREATION_CHECK_DELAY_BETWEEN_ATTEMPTS_SECONDS=1
# Это количество попыток проверки инициализации поискового индекса.
SEARCH_INDEX_CREATION_CHECK_MAX_ATTEMPTS=10
# Установка этого значения в false заставляет поисковую систему возвращать ответы в формате XML вместо двоичного формата. Используется только для отладки.
SEARCH_SOLR_BINARY_REQUEST_WRITER=true
# При индексации разделов поисковая система время от времени будет фиксировать изменения (записывать на диск). Это интервал между фиксациями в миллисекундах.
# Установка слишком большого или слишком малого значения может привести к увеличению потребления памяти или ресурсов процессора.
SEARCH_SOLR_COMMIT_TIME_MILLIS=5000
# Используется для отладки. Если значение равно true, поисковая система будет возвращать подробную информацию о поисковом запросе и найденных совпадениях.
SEARCH_DEBUG_ENABLED=false
# Максимальное количество символов, копируемых из другого поля (например, из описания) для создания копии поля.
SEARCH_SOLR_COPY_FIELD_MAX_CHARS=200
# При создании сниппета поиска будут просматриваться только первые N символов документа.
SEARCH_HIGHLIGHT_MAX_DOCUMENT_SIZE_IN_CHARS_TO_HIGHLIGHT=200000
# Параметр "minimum should match" парсера поисковых запросов Solr DisMax.
# Определяет, сколько слов из запроса должно быть найдено в документе, чтобы такой документ попал в поисковую выдачу.
# Формат: "X<-Y%" означает: если в поисковом запросе X или менее слов, все должны присутствовать в документе; если более X слов, не менее Y% должны совпасть.
# Пример: "2<-25%" означает: если поисковый запрос состоит из двух слов, оба должны присутствовать в документе; если более 2 слов, то в документе должны присутствовать не менее 25% их них.
SEARCH_DIS_MAX_MM=2<-25%
# Время, которое Dr.Explain Search Backend Controller будет ожидать после запуска перед проверкой необходимости обновления поискового индекса.
# Рекомендуется устанавливать этот параметр в значение не менее 5 секунд, чтобы позволить поисковой системе
# полностью инициализироваться и подготовиться к обработке входящих запросов.
SCHEDULED_SEARCH_CHECK_CONTENT_UPDATE_INITIAL_DELAY_SECONDS=10
# Dr.Explain Search Backend Controller будет периодически проверять, требуется ли обновление поискового индекса.
# Это время в секундах между окончанием предыдущей проверки и началом следующей.
SCHEDULED_SEARCH_CHECK_CONTENT_UPDATE_FIXED_DELAY_SECONDS=300
# Установите значение в false, чтобы отключить проверку необходимости обновления поискового индекса контроллером Dr.Explain Search Backend.
SCHEDULED_SEARCH_CHECK_CONTENT_UPDATE_ENABLED=true
|
|
Токен поискового запроса
|
Пример
|
Пояснение
|
|
+
|
Иван любит +яблоки
|
Следующее за знаком + слово должно присутствовать в разделе. Поиск по запросу Иван любит +яблоки будет игнорировать разделы, в которых нет слова "яблоки".
|
|
-
|
Иван любит -яблоки
|
Следующее за знаком - слово должно отсутствовать в разделе. Поиск по запросу Иван любит -яблоки будет игнорировать разделы, содержащие слово "яблоки".
|
|
( и )
|
Иван любит & (яблоки | груши)
|
Используется для вложения логических операторов, например (a | b) & c. Поиск по запросу Иван любит & (яблоки | груши) эквивалентен выполнению двух поисковых запросов: Иван любит & яблоки и Иван любит & груши с последующим объединением их результатов.
|
|
"
|
Иван "любит яблоки"
|
Ищет разделы, содержащие слова, написанные точно так, как указано в поисковом запросе. Поиск по запросу Иван "любит яблоки" будет включать разделы, содержащие слова "любит" и "яблоки".
|
|
& и |
|
Иван любит & (яблоки | груши)
|
Логические операторы "and" (&) и "or" (|). Поиск по запросу Иван любит & (яблоки | груши) эквивалентен выполнению двух поисковых запросов: "Иван любит & яблоки " и "Иван любит & груши" с последующим объединением их результатов.
|
Для обновления поискового движка до последней версии выполните следующие действия:
-
Подключитесь к серверу, на котором установлен поисковый движок, по SSH.
-
Перейдите в каталог, содержащий файл docker-compose.yaml (обычно /opt/drexplain-search):cd /opt/drexplain-search
-
Остановите поисковый движок и удалите все связанные с ним ресурсы:docker compose down -v --rmi all
-
Изучите актуальную документацию по установке. Проверьте наличие изменений, которые могут потребовать обновления файла docker-compose.yaml, и внесите соответствующие правки.