Cấu hình và sử dụng công cụ tìm kiếm Typesense trên ServBay

Typesense là một công cụ tìm kiếm mã nguồn mở, nhẹ, tốc độ cực cao, được thiết kế tối ưu để mang đến trải nghiệm tìm kiếm “gõ là tìm” với độ trễ rất thấp. Typesense thường được xem là một giải pháp thay thế nhẹ cho Algolia hoặc Elasticsearch. Nhờ ServBay, bạn dễ dàng triển khai và quản lý một instance Typesense hoàn chỉnh ngay trên môi trường macOS của mình, bổ sung khả năng tìm kiếm mạnh mẽ cho ứng dụng.

Tổng quan

ServBay tối giản hóa đáng kể quá trình cài đặt và cấu hình Typesense. Bạn sẽ không cần thao tác dòng lệnh phức tạp mà mọi thiết lập đều thực hiện qua giao diện đồ họa, giúp sở hữu dịch vụ tìm kiếm nội bộ sẵn sàng chỉ với vài cú click.

Để nâng cao trải nghiệm phát triển, ServBay tự động cấu hình một endpoint API HTTPS bảo mật, dễ truy cập: https://typesense.servbay.host/. Điều này nghĩa là bạn không phải bận tâm về ánh xạ cổng hay cấu hình chứng chỉ SSL — chỉ việc sử dụng tên miền này để gọi API cho ứng dụng.

Điều kiện tiên quyết

• Đã cài đặt và ServBay đang chạy trên macOS của bạn.
• Bạn đang phát triển một dự án cần tích hợp chức năng tìm kiếm.
• Có hiểu biết căn bản về các khái niệm công cụ tìm kiếm như bộ sưu tập (Collection), tài liệu (Document), khóa API (API Key).

Các bước thao tác

1. Cài đặt gói Typesense

Trước tiên, hãy cài đặt gói Typesense trên ServBay:

1. Mở ứng dụng ServBay.
2. Trong thanh điều hướng bên trái, chọn Phần mềm (Packages).
3. Tìm mục Tìm kiếm - Typesense trong danh sách phần mềm.
4. Nhấn nút cài đặt bên phải Typesense, đợi quá trình hoàn thành.
5. Nhấn nút kích hoạt dịch vụ Typesense ở bên phải.

2. Cấu hình dịch vụ Typesense

Sau khi cài đặt, bạn cần tiến hành cấu hình cơ bản cho Typesense:

1. Trên thanh điều hướng bên trái của ServBay, chọn Search.

2. Trong menu xổ xuống, chọn Typesense để vào giao diện cấu hình.

   

3. Bạn sẽ thấy các tùy chọn cấu hình sau, hãy chỉnh sửa theo nhu cầu hoặc giữ mặc định:

   • Bind IP (IP lắng nghe): Địa chỉ IP mà dịch vụ Typesense lắng nghe. Mặc định là 127.0.0.1, dịch vụ chỉ chấp nhận truy cập từ máy nội bộ — an toàn nhất cho phát triển cục bộ.
   • Port (Cổng): Cổng giao tiếp gốc của API Typesense. Giá trị mặc định là 8108. Dù dịch vụ chạy trên cổng này, bạn nên sử dụng tên miền https://typesense.servbay.host mà ServBay cấp.
   • API Key (Khóa API): Khóa xác thực cho mọi truy vấn API. Đây là yếu tố bảo mật dữ liệu tìm kiếm của bạn — hãy chọn khóa mạnh và duy nhất, đồng thời lưu giữ cẩn thận.
   • Data Path (Đường dẫn dữ liệu): Nơi lưu trữ toàn bộ dữ liệu và cấu hình của Typesense trên máy. Mặc định là /Applications/ServBay/data/typesense. Có thể nhấn biểu tượng thư mục bên phải để mở nhanh trong Finder.

3. Lưu cấu hình & khởi động dịch vụ

1. Sau khi hoàn tất cấu hình, nhấn nút Lưu (Save) ở góc phải bên dưới.
2. Chuyển sang danh sách Phần mềm (Packages), tìm Typesense và bật công tắc bên phải để khởi động dịch vụ.
3. Nếu mọi thứ đúng, đèn trạng thái dịch vụ sẽ chuyển màu xanh lá — đồng nghĩa Typesense đã sẵn sàng.

4. Tích hợp Typesense vào ứng dụng

Ứng dụng của bạn (ví dụ: JavaScript, PHP, Python, Go...) có thể kết nối đến Typesense trên ServBay thông qua bất kỳ thư viện khách chính thức hoặc cộng đồng nào của Typesense.

Khi kết nối, sử dụng thông tin endpoint chuyên dụng mà ServBay cung cấp:

• Host/Node (Máy chủ/Nút): typesense.servbay.host
• Port (Cổng): 443 (cổng chuẩn cho HTTPS)
• Protocol (Giao thức): https
• API Key (Khóa API): Khóa bạn đã thiết lập ở bước 2

Ví dụ mã JavaScript (sử dụng thư viện typesense-js)

Trước tiên, cài đặt thư viện Typesense cho JavaScript vào dự án:

npm install typesense
# Hoặc
yarn add typesense

Khởi tạo client và tương tác trong mã của bạn:

import Typesense from 'typesense'

// Khởi tạo client Typesense
// Lưu ý: sử dụng domain chuyên dụng và giao thức bảo mật từ ServBay
const client = new Typesense.Client({
  nodes: [{
    host: 'typesense.servbay.host',
    port: 443,
    protocol: 'https'
  }],
  apiKey: 'YOUR-SUPER-STRONG-API-KEY', // Thay bằng API Key bạn cấu hình trên ServBay
  connectionTimeoutSeconds: 2
})

// Ví dụ: Tạo một bộ sưu tập '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 {
    // Tạo collection
    await client.collections().create(bookSchema);
    console.log("Tạo collection 'books' thành công.");

    // Thêm một tài liệu sách mới
    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("Thêm tài liệu thành công.");

    // Thực hiện truy vấn tìm kiếm
    const searchParameters = {
      'q': 'hitchhiker',
      'query_by': 'title',
      'sort_by': 'publication_year:desc'
    };
    const searchResults = await client.collections('books').documents().search(searchParameters);
    console.log('Kết quả tìm kiếm:', searchResults);

  } catch (error) {
    console.error('Lỗi Typesense:', error);
  }
}

setupTypesense();

Câu hỏi thường gặp (FAQ)

• Hỏi: Tôi quên API Key thì đặt lại như thế nào?
  • Đáp: Đặt lại trên ServBay rất đơn giản. Chỉ cần nhập khóa mới vào trường API Key tại giao diện cấu hình Typesense (Search -> Typesense), nhấn Lưu (Save) và khởi động lại dịch vụ Typesense.
• Hỏi: Dịch vụ Typesense không khởi chạy, phải làm sao?
  • Đáp: Vui lòng kiểm tra các mục sau:
    1. Nhấn biểu tượng nhật ký góc trên phải giao diện cấu hình Typesense để xem chi tiết lỗi, đây thường là nguồn thông tin chính xác nhất.
    2. Đảm bảo cổng 8108 trên máy không bị ứng dụng khác chiếm dụng.
    3. Kiểm tra thư mục Data Path có tồn tại không, và ServBay có quyền đọc/ghi thư mục này không.
• Hỏi: Tôi có thể truy cập API qua http://127.0.0.1:8108 trực tiếp không?
  • Đáp: Có, cổng này cho phép truy cập cục bộ. Tuy nhiên, hãy luôn ưu tiên dùng https://typesense.servbay.host/ để nhận được kết nối HTTPS bảo mật mà không cần tự cấu hình — tương tự môi trường sản xuất và an toàn hơn hẳn.

Tổng kết

ServBay tích hợp liền mạch công cụ tìm kiếm mạnh mẽ Typesense vào quy trình phát triển macOS của bạn. Nhờ cấu hình đồ họa tối giản và endpoint HTTPS bảo mật được định sẵn, bạn có thể tập trung phát triển trải nghiệm tìm kiếm xuất sắc mà không còn phải bận tâm tới các thao tác thiết lập hay duy trì phức tạp cho môi trường.