Konfiguracja i użycie silnika wyszukiwania Typesense w ServBay

Typesense to otwartoźródłowy, lekki i niezwykle szybki silnik wyszukiwania in-memory, zaprojektowany z myślą o niskim opóźnieniu i doświadczeniu „search-as-you-type” (wyszukiwanie podczas wpisywania). Często postrzegany jest jako lżejsza alternatywa dla rozwiązań takich jak Algolia czy Elasticsearch. Dzięki ServBay możesz w prosty sposób uruchomić i zarządzać w pełni funkcjonalną instancją Typesense na lokalnym środowisku macOS, wzbogacając swoją aplikację o zaawansowane możliwości wyszukiwania.

Przegląd

ServBay znacząco upraszcza proces instalacji i konfiguracji Typesense. Programiści mogą wykonać całą konfigurację za pomocą interfejsu graficznego ServBay, bez potrzeby skomplikowanych działań w terminalu, uzyskując gotową do pracy lokalną usługę wyszukiwania.

Aby zapewnić maksymalną wygodę podczas developmentu, ServBay automatycznie konfiguruje dla Twojej instancji Typesense bezpieczny i łatwo dostępny punkt końcowy HTTPS API: https://typesense.servbay.host/. Oznacza to, że nie musisz zaprzątać sobie głowy mapowaniem portów czy obsługą certyfikatów SSL – możesz od razu korzystać z tego adresu w swojej aplikacji.

Wymagania wstępne

• System macOS z zainstalowanym i uruchomionym ServBay.
• Pracujesz nad projektem, który wymaga integracji funkcji wyszukiwania.
• Masz podstawową wiedzę na temat silników wyszukiwania (np. kolekcja/indeks — Collection, dokument — Document, klucz API).

Kroki operacyjne

1. Instalacja pakietu Typesense

Na początek zainstaluj pakiet Typesense w ServBay:

1. Otwórz aplikację ServBay.
2. W lewym pasku nawigacyjnym kliknij Pakiety (Packages).
3. Wyszukaj na liście sekcję Wyszukiwanie - Typesense.
4. Kliknij przycisk instalacji obok Typesense i poczekaj na ukończenie procesu.
5. Włącz usługę Typesense, klikając przełącznik po prawej stronie.

2. Konfiguracja usługi Typesense

Po instalacji wykonaj podstawową konfigurację Typesense:

1. W lewym menu ServBay kliknij Wyszukiwanie (Search).

2. Z rozwijanego menu wybierz Typesense, aby przejść do panelu konfiguracji.

   

3. Zobaczysz następujące opcje konfiguracyjne. Możesz je zmienić według potrzeb lub pozostawić domyślne:

   • Bind IP (adres IP związania): Adres IP, na którym nasłuchuje usługa Typesense. Domyślna wartość 127.0.0.1 zapewnia, że usługa jest dostępna tylko lokalnie — to najbezpieczniejsze rozwiązanie w środowisku developerskim.
   • Port: Port komunikacyjny API Typesense. Domyślnie 8108. Mimo że usługa działa na tym porcie, zalecamy korzystać z domeny https://typesense.servbay.host udostępnianej przez ServBay.
   • API Key (klucz API): Klucz uwierzytelniający wszystkie żądania API. To kluczowy element bezpieczeństwa Twoich danych wyszukiwania. Ustaw silne, unikalne hasło i przechowuj je w bezpiecznym miejscu.
   • Data Path (ścieżka danych): Lokalizacja, w której Typesense przechowuje indeksy i konfigurację. Domyślna wartość to /Applications/ServBay/data/typesense. Kliknij ikonę folderu po prawej, aby szybko otworzyć ten katalog w Finderze.

3. Zapisz konfigurację i uruchom usługę

1. Po zakończeniu konfiguracji kliknij przycisk Zapisz (Save) w prawym dolnym rogu.
2. Następnie przejdź ponownie do listy Pakietów (Packages), znajdź Typesense i włącz przełącznik, aby uruchomić usługę.
3. Jeśli wszystko jest poprawnie skonfigurowane, status usługi zmieni się na zielony — oznacza to, że Typesense działa prawidłowo.

4. Integracja Typesense w aplikacji

Twoja aplikacja (np. JavaScript, PHP, Python, Go) może łączyć się z instancją Typesense w ServBay przy użyciu oficjalnych lub społecznościowych bibliotek klienckich.

Do połączenia używaj poniższych, specjalnie przygotowanych przez ServBay danych:

• Host/Węzeł: typesense.servbay.host
• Port: 443 (standardowy port HTTPS)
• Protokół: https
• API Key: klucz ustawiony w kroku 2 (API Key)

Przykład kodu JavaScript (klient typesense-js)

Najpierw zainstaluj klienta Typesense JavaScript w swoim projekcie:

npm install typesense
# lub
yarn add typesense

Następnie zainicjuj klienta i rozpocznij interakcje w kodzie:

import Typesense from 'typesense'

// Inicjalizacja klienta Typesense
// Używamy dedykowanej domeny i protokołu HTTPS ServBay
const client = new Typesense.Client({
  nodes: [{
    host: 'typesense.servbay.host',
    port: 443,
    protocol: 'https'
  }],
  apiKey: 'YOUR-SUPER-STRONG-API-KEY', // Zamień na API Key ustawiony w ServBay
  connectionTimeoutSeconds: 2
})

// Przykład: utworzenie kolekcji '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 {
    // Utworzenie kolekcji
    await client.collections().create(bookSchema);
    console.log("Kolekcja 'books' została utworzona.");

    // Dodanie dokumentu książki
    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("Dokument został dodany pomyślnie.");

    // Przeprowadzenie wyszukiwania
    const searchParameters = {
      'q': 'hitchhiker',
      'query_by': 'title',
      'sort_by': 'publication_year:desc'
    };
    const searchResults = await client.collections('books').documents().search(searchParameters);
    console.log('Wyniki wyszukiwania:', searchResults);

  } catch (error) {
    console.error('Błąd Typesense:', error);
  }
}

setupTypesense();

Najczęściej zadawane pytania (FAQ)

• Q: Zapomniałem klucza API. Jak zresetować?
  • A: Resetowanie klucza w ServBay jest bardzo proste. W panelu konfiguracji Typesense (Wyszukiwanie -> Typesense) wpisz nowy klucz w polu API Key, kliknij Zapisz (Save), a następnie uruchom ponownie usługę Typesense.
• Q: Usługa Typesense nie uruchamia się. Co zrobić?
  • A: Sprawdź:
    1. Kliknij ikonę dziennika/logów w prawym górnym rogu panelu konfiguracji Typesense i przejrzyj szczegółowe komunikaty o błędach — najczęściej dostarczą konkretnej wskazówki.
    2. Upewnij się, że port 8108 nie jest zajęty przez inny program.
    3. Sprawdź, czy wskazany katalog Data Path istnieje i czy ServBay ma do niego dostęp do zapisu i odczytu.
• Q: Czy mogę korzystać z API bezpośrednio przez http://127.0.0.1:8108?
  • A: Tak, na lokalnym komputerze port ten jest dostępny, ale zdecydowanie zalecamy korzystanie z https://typesense.servbay.host/, które zapewnia automatyczny HTTPS i wyższy poziom bezpieczeństwa — rozwiązanie bliższe produkcyjnemu.

Podsumowanie

ServBay umożliwia pełną integrację zaawansowanego silnika wyszukiwania Typesense w lokalnym środowisku deweloperskim macOS. Dzięki uproszczonej konfiguracji graficznej i prekonfigurowanemu bezpiecznemu punktowi końcowemu HTTPS, możesz skupić się na tworzeniu wyjątkowych funkcji wyszukiwania, bez konieczności żmudnego przygotowywania i zarządzania infrastrukturą.