Настройка и использование поискового движка Typesense в ServBay

Typesense — это открытый, легковесный и чрезвычайно быстрый поисковый движок в памяти, созданный для обеспечения низкой задержки и мгновенного поиска по мере ввода текста (search-as-you-type). Часто рассматривается как легковесная альтернатива Algolia или Elasticsearch. С помощью ServBay вы легко сможете развернуть и управлять полноценным экземпляром Typesense в вашей локальной среде macOS, добавив мощный поиск в свои приложения.

Обзор

ServBay значительно упрощает процесс установки и настройки Typesense. Разработчику не нужно разбираться с командной строкой — все операции доступны в графическом интерфейсе ServBay, а рабочий локальный поисковый сервис готов к использованию «из коробки».

Для повышения удобства разработки, ServBay автоматически настраивает для вашего экземпляра Typesense защищённую и легко доступную HTTPS API конечную точку: https://typesense.servbay.host/. Это значит, что вам больше не нужно заботиться о пробросе портов и настройке SSL-сертификатов — просто используйте этот домен для API-запросов прямо из вашего приложения.

Предварительные требования

• Установленный и запущенный ServBay на вашем macOS.
• Вы работаете над проектом, в который требуется интегрировать поиск.
• Знакомство с базовыми понятиями поисковых движков (коллекция/индекс Collection, документ Document, API ключ).

Пошаговая инструкция

1. Установка пакета Typesense

Сначала необходимо установить пакет Typesense в ServBay:

1. Откройте приложение ServBay.
2. В левой навигационной панели перейдите в раздел Пакеты (Packages).
3. В списке пакетов найдите категорию Поиск — Typesense.
4. Нажмите на кнопку установки рядом с Typesense и дождитесь завершения процесса.
5. Нажмите на кнопку справа для активации сервиса Typesense.

2. Настройка сервиса Typesense

После установки выполните базовую настройку Typesense:

1. В левой навигации ServBay выберите Search.

2. В выпадающем меню откройте Typesense для перехода к настройкам.

   

3. На странице будут представлены следующие параметры, которые можно редактировать или оставить по умолчанию:

   • Bind IP (привязка IP): IP-адрес, на котором слушает сервис Typesense. Значение по умолчанию 127.0.0.1 обеспечивает доступ только с локальной машины — это самый безопасный вариант для локальной разработки.
   • Port (порт): Базовый порт взаимодействия API Typesense. По умолчанию 8108. Несмотря на то, что сервис запущен на этом порту, рекомендуется использовать домен https://typesense.servbay.host, который предоставляет ServBay.
   • API Key (API-ключ): Ключ для аутентификации всех API-запросов. Это критически важный параметр для защиты ваших поисковых данных. Обязательно задайте сложный и уникальный ключ и храните его в безопасности.
   • Data Path (путь к данным): Локальный путь для хранения всех индексов и конфигураций Typesense. По умолчанию /Applications/ServBay/data/typesense. Для быстрого перехода в этот каталог нажмите значок папки справа.

3. Сохранение настроек и запуск сервиса

1. Закончив настройку, нажмите кнопку Save (Сохранить) в правом нижнем углу.
2. Далее переключитесь на список Пакеты (Packages), найдите Typesense и активируйте его с помощью переключателя справа.
3. Если настройки верны, индикатор состояния станет зелёным — это значит, что Typesense успешно работает.

4. Интеграция Typesense в приложение

Ваше приложение (например, на JavaScript, PHP, Python, Go и др.) может подключиться к Typesense в ServBay через любой официальный или сторонний клиент.

Для подключения используйте следующие параметры, предоставленные ServBay:

• Host/Node (хост/узел): typesense.servbay.host
• Port (порт): 443 (стандартный порт HTTPS)
• Protocol (протокол): https
• API Key (API-ключ): тот, который вы указали на шаге 2

Пример кода на JavaScript (клиент typesense-js)

Сначала установите JS-клиент Typesense в проект:

npm install typesense
# или
yarn add typesense

Затем инициализируйте клиент и выполните основные операции:

import Typesense from 'typesense'

// Инициализация клиента Typesense
// Обратите внимание: используем выделенный домен и протокол HTTPS от ServBay
const client = new Typesense.Client({
  nodes: [{
    host: 'typesense.servbay.host',
    port: 443,
    protocol: 'https'
  }],
  apiKey: 'YOUR-SUPER-STRONG-API-KEY', // Замените на ваш API Key из ServBay
  connectionTimeoutSeconds: 2
})

// Пример создания коллекции 'books'
const bookSchema = {
  name: 'books',
  fields: [
    { name: 'title', type: 'string' },
    { name: 'author', type: 'string', facet: true },
    { name: 'publication_year', type: 'int32', facet: true }
  ],
  default_sorting_field: 'publication_year'
}

async function setupTypesense() {
  try {
    // Создание коллекции
    await client.collections().create(bookSchema);
    console.log("Коллекция 'books' успешно создана.");

    // Добавление документа-книги
    const bookDocument = {
      'title': 'The Hitchhiker\'s Guide to the Galaxy',
      'author': 'Douglas Adams',
      'publication_year': 1979
    };
    await client.collections('books').documents().create(bookDocument);
    console.log("Документ успешно добавлен.");

    // Поиск данных
    const searchParameters = {
      'q': 'hitchhiker',
      'query_by': 'title',
      'sort_by': 'publication_year:desc'
    };
    const searchResults = await client.collections('books').documents().search(searchParameters);
    console.log('Результаты поиска:', searchResults);

  } catch (error) {
    console.error('Ошибка Typesense:', error);
  }
}

setupTypesense();

Часто задаваемые вопросы (FAQ)

• Вопрос: Я забыл API Key. Как его сбросить?
  • Ответ: В ServBay сбросить ключ очень просто: зайдите в настройки Typesense (Search -> Typesense), в поле API Key введите новый ключ, нажмите Save (Сохранить) и перезапустите сервис Typesense.
• Вопрос: Сервис Typesense не запускается. Что делать?
  • Ответ: Проверьте следующее:
    1. Откройте интерфейс настроек Typesense и кликните по иконке логов в правом верхнем углу — подробная ошибка обычно отображается там.
    2. Убедитесь, что порт 8108 на локальной машине не занят другими приложениями.
    3. Проверьте, существует ли заданная директория в Data Path и имеет ли ServBay разрешения на чтение/запись в этот каталог.
• Вопрос: Можно ли использовать API по адресу http://127.0.0.1:8108 напрямую?
  • Ответ: Да, этот порт доступен локально, и вы можете к нему обращаться. Тем не менее, крайне рекомендуется использовать https://typesense.servbay.host/, чтобы ваши соединения были зашифрованы (HTTPS), что ближе к условиям production-окружения и безопаснее.

Заключение

ServBay предоставляет бесшовную интеграцию мощного поискового движка Typesense в ваш локальный процесс разработки на macOS. Графическая настройка и готовая защищённая HTTPS-точка доступа позволяют вам сосредоточиться на создании отличного пользовательского поиска, а не на рутинной установке и поддержке среды.