FlashPanel

Appearance

Typesense Server ​

Typesense là công cụ tìm kiếm toàn văn mã nguồn mở, trả kết quả gần như tức thì và chịu được lỗi gõ sai chính tả. Hướng dẫn này cài Typesense trên máy chủ FlashPanel và dùng nó thay cho tính năng tìm kiếm mặc định của WordPress, đặc biệt hữu ích với website có hàng chục nghìn bài viết trở lên.

Yêu cầu ​

  • Máy chủ đã kết nối với FlashPanel để cài Typesense
  • Website WordPress (trên cùng máy chủ hoặc máy chủ khác)

INFO

Nên dùng một máy chủ riêng cho Typesense (chỉ cần thêm Nginx nếu kết nối qua tên miền). Bạn vẫn có thể cài chung máy chủ với website, nhưng tách riêng giúp giảm tải cho máy chủ website và khi một bên gặp sự cố thì bên còn lại không bị ảnh hưởng.

Bước 1: Cài đặt Typesense ​

  1. Vào trang quản lý máy chủ, bấm menu Ứng dụng và chọn tab Chưa cài đặt
  2. Tìm ứng dụng Typesense và bấm Cài đặt (biểu tượng tải xuống)
  3. Trong hộp thoại, kiểm tra Port (mặc định 8108) và Master Key (được tạo ngẫu nhiên sẵn, bạn có thể thay bằng giá trị của mình)
  4. Lưu lại Port và Master Key, sau đó bấm Cài đặt

TIP

Nếu quên Master Key, vào tab Đã cài đặt của trang Ứng dụng, bấm Cấu hình của Typesense và xem giá trị api-key. Các phần bên dưới dùng cổng mặc định 8108; nếu đã đổi cổng, hãy thay bằng cổng của bạn.

Bước 2: Cho phép website kết nối tới Typesense ​

Chọn cách phù hợp với vị trí của website:

  • Website và Typesense cùng máy chủ: không cần làm gì thêm, website kết nối qua 127.0.0.1:8108.
  • Khác máy chủ, kết nối qua IP và cổng: trên máy chủ Typesense, thêm quy tắc tường lửa Cho phép cổng 8108, điền IP của máy chủ website vào Địa chỉ IP Từ để chỉ máy chủ đó kết nối được. Lưu ý kết nối theo cách này không được mã hóa.
  • Khác máy chủ, kết nối qua tên miền (khuyến nghị): trên máy chủ Typesense, tạo website mới với Tên miền (ví dụ search.domain.com, đã trỏ DNS về máy chủ) và Proxy Port là 8108, sau đó cài SSL cho website này. Kết nối được mã hóa qua HTTPS và không cần mở cổng 8108.

Bước 3: Tạo API key ​

Website cần API key để kết nối tới Typesense. Bạn có thể dùng Master Key, nhưng không nên vì key này có toàn quyền. Thay vào đó, hãy tạo hai key con:

  • Admin API Key: dùng để đánh chỉ mục (index) dữ liệu
  • Search Only API Key: chỉ dùng để tìm kiếm, an toàn khi lộ ra trình duyệt của người xem

Mở Terminal trên trang tổng quan của máy chủ Typesense và chạy các lệnh dưới đây. Thay abcxyz bằng Master Key của bạn:

bash
# Master Key
TYPESENSE_API_KEY=abcxyz

# Tạo Admin API Key
curl 'http://localhost:8108/keys' \
    -X POST \
    -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{"description":"Admin Key","actions": ["*"], "collections": ["*"]}'

# Tạo Search Only API Key
curl 'http://localhost:8108/keys' \
    -X POST \
    -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{"description":"Search-only key","actions": ["documents:search"], "collections": ["*"]}'

Mỗi lệnh trả về một đoạn JSON, giá trị của trường value là API key. Hãy lưu lại ngay vì Typesense chỉ hiển thị giá trị này một lần.

Bước 4: Kết nối từ WordPress ​

  1. Trong trang quản trị WordPress, cài và kích hoạt plugin Search with Typesense (miễn phí; nếu dùng WooCommerce cần mua thêm add-on)
  2. Mở trang cài đặt của plugin và chọn tab General
  3. Điền thông tin theo trường hợp đã chọn ở bước 2:
TrườngCùng máy chủKhác máy chủ, qua IPKhác máy chủ, qua tên miền
PROTOCOLhttphttphttps
ENTER NODE URI127.0.0.1IP máy chủ Typesensesearch.domain.com
ENTER PORT81088108443
  1. Nhập Admin API Key vào ADMIN API KEY và Search Only API Key vào SEARCH API KEY (xem bước 3)
  2. Bấm Save. Nếu kết nối thành công, plugin hiển thị thông báo thành công ở góc màn hình

Bước 5: Index dữ liệu và thay thế ô tìm kiếm ​

  1. Mở tab Search Configuration của plugin
  2. Ở ô Select Posts Types to Enable, chọn các loại nội dung cần tìm kiếm (ví dụ Posts, Category)
  3. Bấm Index ở từng loại nội dung và đợi hoàn tất. Không rời trang trong lúc index. Với lượng dữ liệu lớn, nên index bằng WP-CLI theo hướng dẫn của plugin
  4. Bật Replace WordPress Search để thay ô tìm kiếm mặc định của WordPress, rồi chọn kiểu hiển thị Replace with Instant Search (trang kết quả có bộ lọc) hoặc Replace with Autocomplete (gợi ý khi gõ)

Nếu muốn có trang tìm kiếm riêng, tạo một trang trống trong WordPress và chèn shortcode của plugin (xem tài liệu shortcode).

Kiểm tra kết quả ​

  1. Trong Terminal của máy chủ Typesense, chạy curl http://localhost:8108/health. Kết quả {"ok":true} cho biết Typesense đang chạy
  2. Mở website WordPress, gõ từ khóa vào ô tìm kiếm và kiểm tra kết quả hiển thị từ Typesense

Xử lý sự cố ​

  • Plugin báo không kết nối được: kiểm tra lại PROTOCOL, ENTER NODE URI, ENTER PORT. Nếu kết nối qua IP, đảm bảo đã mở cổng 8108 cho đúng IP máy chủ website; nếu qua tên miền, đảm bảo website đã có SSL
  • Lỗi Forbidden - a valid x-typesense-api-key header must be sent: API key sai hoặc đã bị xóa. Tạo lại key theo bước 3
  • Typesense không chạy: vào tab Đã cài đặt của trang Ứng dụng, bấm Nhật ký của Typesense để xem lỗi, sau đó bấm Khởi động lại