在 ServBay 中設定與使用 Typesense 搜尋引擎

Typesense 是一套開源、輕量且極速的記憶體搜尋引擎，專為提供低延遲、「輸入即搜尋」（search-as-you-type）體驗而設計。它常被視為 Algolia 或 Elasticsearch 的輕量級替代方案。透過 ServBay，您能輕鬆於本機 macOS 環境布署並管理完整功能的 Typesense 實例，為您的應用新增強大的搜尋能力。

概述

ServBay 大幅簡化了 Typesense 的安裝及設定流程。開發者無須繁瑣指令操作，僅需透過 ServBay 圖形化介面就能完成所有設置，輕鬆獲得即插即用的本機搜尋服務。

為進一步提升開發體驗，ServBay 會自動為您的 Typesense 實例設定一個安全、便於存取的 HTTPS API 端點：https://typesense.servbay.host/。這代表您毋須擔心埠轉發和 SSL 憑證配置，直接在應用程式內使用該網域進行 API 呼叫即可。

前置條件

您的 macOS 系統已成功安裝並執行 ServBay。
您正在開發需整合搜尋功能的專案。
具備搜尋引擎基本概念（例如集合/索引 Collection、文件 Document、API 金鑰）基礎知識。

操作步驟

1. 安裝 Typesense 軟體包

首先，您需要在 ServBay 裡安裝 Typesense 軟體包：

開啟 ServBay 應用程式。
於左側導覽列點擊 軟體包 (Packages)。
在軟體包清單中尋找搜尋 - Typesense。
點選 Typesense 右側的安裝鈕，並等待安裝完成。
點擊右側按鈕啟用 Typesense 服務。

2. 設定 Typesense 服務

完成安裝後，需進行 Typesense 基本設定：

在 ServBay 左側導覽列中，點擊 Search。
於下拉選單選擇 Typesense，進入其設定畫面。
您會看到以下設定項目，可依需求變更或維持預設：
- Bind IP (綁定 IP): Typesense 服務監聽的 IP 位址。預設 127.0.0.1 只允許本機存取，對本機開發來說最為安全。
- Port (埠號): Typesense API 底層通訊埠，預設為 8108。雖然服務跑在這個埠號上，我們強烈建議優先用 ServBay 提供的 https://typesense.servbay.host 網域做連線。
- API Key (API 金鑰): 驗證所有 API 請求的金鑰。這是守護搜尋資料安全的關鍵，請一定要設定強且唯一的金鑰，並妥善保存。
- Data Path (資料路徑): Typesense 在本機儲存所有索引資料與設定的路徑，預設為 /Applications/ServBay/data/typesense。您可點擊右側資料夾圖示於 Finder 中快速定位該目錄。

3. 儲存設定並啟動服務

完成所有設定後，點擊右下的 Save (儲存) 鈕。
接著切換至 軟體包 (Packages) 清單，尋找 Typesense，並點擊其右側開關啟動服務。
若設定皆正確，服務狀態指示燈會轉為綠色，代表 Typesense 成功啟動。

4. 在應用程式中整合 Typesense

您的應用（如 JavaScript、PHP、Python、Go 等）可直接使用官方或社群提供的 Typesense 客戶端套件，連線至 ServBay 中的 Typesense 實例。

連線時，請優先使用 ServBay 為您提供的專屬端點資訊：

Host/Node (主機/節點): typesense.servbay.host
Port (埠號): 443（標準 HTTPS 埠號）
Protocol (協定): https
API Key (API 金鑰): 您於步驟 2 設定的 API Key

JavaScript 程式碼範例（以 `typesense-js` 客戶端為例）

首先，在您的專案中安裝 Typesense JavaScript 客戶端：

bash

npm install typesense
# 或
yarn add typesense

然後於程式碼初始化客戶端並互動：

javascript

import Typesense from 'typesense'

// 初始化 Typesense 客戶端
// 注意我們採用 ServBay 提供的專屬網域與加密協定
const client = new Typesense.Client({
  nodes: [{
    host: 'typesense.servbay.host',
    port: 443,
    protocol: 'https'
  }],
  apiKey: 'YOUR-SUPER-STRONG-API-KEY', // 請替換為您在 ServBay 設定的 API Key
  connectionTimeoutSeconds: 2
})

// 範例：建立名為 'books' 的集合 (collection)
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("Collection 'books' created successfully.");

    // 新增書籍文件
    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("Document added successfully.");

    // 進行搜尋
    const searchParameters = {
      'q': 'hitchhiker',
      'query_by': 'title',
      'sort_by': 'publication_year:desc'
    };
    const searchResults = await client.collections('books').documents().search(searchParameters);
    console.log('Search Results:', searchResults);

  } catch (error) {
    console.error('Typesense Error:', error);
  }
}

setupTypesense();

常見問題 (FAQ)

Q: 我忘記了 API Key，要怎麼重設？
- A: 在 ServBay 重設非常簡單，只需在 Typesense 的設定頁（Search -> Typesense）的 API Key 欄位重新輸入新金鑰，點擊 Save (儲存) 並重新啟動 Typesense 服務即可。
Q: Typesense 服務啟動失敗怎麼辦？
- A: 請檢查以下幾點：
  1. 點擊 Typesense 設定頁右上角的日誌圖示，查看具體錯誤資訊，這通常能提供最直接的線索。
  2. 確認本地 8108 埠號無被其他程式占用。
  3. 檢查 Data Path 指定目錄是否存在，以及 ServBay 是否有權限讀寫該資料夾。
Q: 我可以直接用 http://127.0.0.1:8108 存取 API 嗎？
- A: 可以，本地該埠可存取。但我們強烈推薦採用 https://typesense.servbay.host/ 連線，因為它不需額外設定即可享有 HTTPS 加密，更貼近實際上線環境，更加安全。

結語

ServBay 將強大的 Typesense 搜尋引擎無縫導入您的本機 macOS 開發流程。透過簡易圖形化設定與預設安全的 HTTPS 端點，您可將寶貴心力專注於打造優異的搜尋體驗，而非耗在繁瑣環境建置與維護工作上。

在 ServBay 中設定與使用 Typesense 搜尋引擎 ​

概述 ​

前置條件 ​

操作步驟 ​

1. 安裝 Typesense 軟體包 ​

2. 設定 Typesense 服務 ​

3. 儲存設定並啟動服務 ​

4. 在應用程式中整合 Typesense ​

JavaScript 程式碼範例（以 typesense-js 客戶端為例） ​

常見問題 (FAQ) ​

結語 ​