Hướng dẫn cấu hình Meilisearch cho Init Live Search từ A đến Z

Yêu cầu trước khi bắt đầu

• Một VPS chạy Ubuntu 24.04, có quyền truy cập SSH (root hoặc sudo)
• Site WordPress đã cài Init Live Search phiên bản 1.9.3 trở lên
• WP-CLI đã cài trên server chạy WordPress (kiểm tra bằng lệnh wp --info)
• Một tên miền phụ trỏ về VPS Meilisearch, ví dụ search.example.com (nếu Meilisearch và WordPress không cùng một server)

Meilisearch không nặng — với một blog vài nghìn bài viết, VPS 1-2GB RAM là đủ dùng, kể cả khi chạy chung với WordPress trên cùng một máy.

Bước 1: Chuẩn bị hệ thống

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl ufw nginx

Bước 2: Tạo user riêng cho Meilisearch

Không nên chạy Meilisearch bằng quyền root. Tạo một user và thư mục riêng:

sudo useradd -r -s /bin/false meilisearch
sudo mkdir -p /var/lib/meilisearch/data /var/lib/meilisearch/dumps /etc/meilisearch
sudo chown -R meilisearch:meilisearch /var/lib/meilisearch

Bước 3: Tải và cài đặt Meilisearch

curl -L https://install.meilisearch.com | sh
sudo mv ./meilisearch /usr/local/bin/
sudo chmod +x /usr/local/bin/meilisearch
meilisearch --version

Bước 4: Tạo master key

Master key dùng để quản trị toàn quyền Meilisearch — chỉ dùng nó để tạo các API key con ở bước sau, không bao giờ đưa nó vào WordPress hay bất kỳ nơi nào ngoài VPS này.

openssl rand -base64 48

Lưu chuỗi này lại cẩn thận, bạn sẽ cần nó ở bước tiếp theo.

Bước 5: Tạo file cấu hình

sudo tee /etc/meilisearch/config.toml > /dev/null <<'EOF'
env = "production"
http_addr = "127.0.0.1:7700"
master_key = "DÁN_MASTER_KEY_VÀO_ĐÂY"
db_path = "/var/lib/meilisearch/data"
dump_dir = "/var/lib/meilisearch/dumps"
no_analytics = true
max_indexing_memory = "384 MiB"
max_indexing_threads = 1
EOF

sudo chown meilisearch:meilisearch /etc/meilisearch/config.toml
sudo chmod 600 /etc/meilisearch/config.toml

http_addr = 127.0.0.1:7700 nghĩa là Meilisearch chỉ lắng nghe nội bộ, không expose trực tiếp ra internet — an toàn hơn nhiều so với bind 0.0.0.0. Nếu VPS của bạn có ít RAM (dưới 4GB) hoặc chạy chung với WordPress, nên giữ nguyên hoặc giảm max_indexing_memory để tránh tranh chấp tài nguyên lúc reindex hàng loạt.

Bước 6: Tạo systemd service

sudo tee /etc/systemd/system/meilisearch.service > /dev/null <<'EOF'
[Unit]
Description=Meilisearch
After=network.target

[Service]
Type=simple
User=meilisearch
Group=meilisearch
ExecStart=/usr/local/bin/meilisearch --config-file-path /etc/meilisearch/config.toml
Restart=on-failure
RestartSec=5
LimitNOFILE=65536
MemoryMax=512M

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now meilisearch
sudo systemctl status meilisearch

MemoryMax=512M là lớp bảo vệ ở tầng hệ điều hành: nếu Meilisearch vượt mốc này, systemd sẽ tự kill và khởi động lại nó thay vì để hệ thống tự chọn tiến trình để kill, tránh ảnh hưởng đến MySQL hay PHP-FPM đang chạy chung server.

Bước 7: Kiểm tra Meilisearch đã chạy

curl -s http://127.0.0.1:7700/health

Kết quả mong đợi: {"status":"available"}

Bước 8: Cấu hình firewall

sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw deny 7700
sudo ufw enable

Bước 9: Expose ra internet qua Nginx (chỉ cần nếu WordPress ở server khác)

Trỏ DNS của tên miền phụ (ví dụ search.example.com) về IP của VPS này trước, sau đó:

sudo tee /etc/nginx/sites-available/search.example.com > /dev/null <<'EOF'
server {
    listen 80;
    server_name search.example.com;

    location / {
        proxy_pass http://127.0.0.1:7700;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
EOF

sudo ln -s /etc/nginx/sites-available/search.example.com /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d search.example.com

Nếu Meilisearch cài chung server với WordPress, bạn có thể dùng subdomain riêng theo cách tương tự, hoặc bỏ qua bước Nginx và để Init Live Search gọi thẳng http://127.0.0.1:7700 nội bộ.

Bước 10: Tạo index

curl -X POST 'http://127.0.0.1:7700/indexes' \
  -H 'Authorization: Bearer MASTER_KEY' \
  -H 'Content-Type: application/json' \
  --data '{ "uid": "my_site_posts", "primaryKey": "id" }'

Cấu hình các thuộc tính tìm kiếm cho index:

curl -X PATCH 'http://127.0.0.1:7700/indexes/my_site_posts/settings' \
  -H 'Authorization: Bearer MASTER_KEY' \
  -H 'Content-Type: application/json' \
  --data '{
    "searchableAttributes": ["title", "excerpt", "content"],
    "filterableAttributes": ["post_type", "categories"],
    "sortableAttributes": ["date_timestamp"],
    "displayedAttributes": ["id", "title", "excerpt", "url", "thumbnail", "date"],
    "rankingRules": ["words", "typo", "proximity", "attribute", "sort", "exactness"]
  }'

Bước 11: Tạo API key riêng cho search và indexing

Không bao giờ dùng master key trong WordPress. Tạo 2 key có quyền hạn giới hạn:

curl -X POST 'http://127.0.0.1:7700/keys' \
  -H 'Authorization: Bearer MASTER_KEY' \
  -H 'Content-Type: application/json' \
  --data '{
    "description": "Indexing key",
    "actions": ["documents.add", "documents.delete", "indexes.get"],
    "indexes": ["my_site_posts"],
    "expiresAt": null
  }'

curl -X POST 'http://127.0.0.1:7700/keys' \
  -H 'Authorization: Bearer MASTER_KEY' \
  -H 'Content-Type: application/json' \
  --data '{
    "description": "Search key",
    "actions": ["search"],
    "indexes": ["my_site_posts"],
    "expiresAt": null
  }'

Mỗi lệnh trả về một chuỗi key trong JSON — lưu lại 2 key này, đặt tên rõ ràng để không nhầm lẫn: Search Key (chỉ dùng để tìm kiếm, an toàn khi lộ ra frontend) và Admin/Indexing Key (có quyền ghi/xóa dữ liệu, cần giữ kín).

Bước 12: Cấu hình trong Init Live Search

Vào Settings → Init Live Search → Meilisearch trên trang quản trị WordPress, điền các thông tin sau:

• Enable Meilisearch: tick để bật
• Host URL: địa chỉ Meilisearch của bạn, ví dụ https://search.example.com (hoặc http://127.0.0.1:7700 nếu chạy chung server)
• Index Name: tên index đã tạo ở bước 10, ví dụ my_site_posts
• Search API Key: dán Search Key vừa tạo ở bước 11
• Admin / Indexing Key: dán Admin/Indexing Key — hoặc bỏ trống nếu bạn định nghĩa key này qua hằng số trong wp-config.php (khuyến nghị, an toàn hơn)
• Request Timeout: giữ mặc định 3000ms là hợp lý cho hầu hết trường hợp

Nếu muốn dùng cách bảo mật hơn cho Admin/Indexing Key, thêm dòng sau vào wp-config.php thay vì nhập trực tiếp vào ô Admin/Indexing Key trên giao diện:

define('INIT_LIVE_SEARCH_MEILI_ADMIN_KEY', 'admin-key-của-bạn');

Sau khi điền xong, nhấn Save Changes, rồi bấm nút Test Connection để xác nhận kết nối thành công.

Bước 13: Index nội dung hiện có

Chạy lệnh sau qua SSH để đưa toàn bộ bài viết đã publish vào Meilisearch:

wp init-live-search meili-reindex --path=/duong-dan-toi-wordpress

Nếu WordPress chạy dưới một user cụ thể (không phải root), chạy bằng đúng user đó, ví dụ:

sudo -u www-data -- wp init-live-search meili-reindex --path=/duong-dan-toi-wordpress

Lệnh xử lý theo từng batch 200 bài, in log tiến độ theo thời gian thực. Với site lớn, có thể điều chỉnh kích thước batch bằng tham số --batch-size.

Bước 14: Kiểm tra kết quả

Thử tìm kiếm trực tiếp trên site — kết quả giờ được trả lời bởi Meilisearch. Nếu muốn xác nhận trực tiếp qua API:

curl -X POST 'https://search.example.com/indexes/my_site_posts/search' \
  -H 'Authorization: Bearer SEARCH_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"q": "từ khóa test"}'

Thêm post type khác vào Meilisearch

Nếu muốn index thêm các post type ngoài danh sách hiện có trong phần “Post Types to Include” (ví dụ một custom post type không public), thêm đoạn sau vào functions.php của theme:

add_filter('init_plugin_suite_live_search_post_types', function ($post_types) {
    $post_types[] = 'ten_post_type_cua_ban';
    return array_unique($post_types);
});

Sau đó chạy lại lệnh reindex ở bước 13 để đưa nội dung cũ của post type mới vào index.

Một vài lưu ý khi vận hành

• Nếu Meilisearch tắt hoặc gặp sự cố, Init Live Search tự động fallback về tìm kiếm database — không cần can thiệp gì thêm.
• Bài viết mới, sửa, hoặc xóa sẽ tự động đồng bộ với Meilisearch sau khi tích hợp được bật — không cần chạy lại lệnh reindex thủ công, trừ khi cần rebuild toàn bộ index.
• Nếu nút Test Connection báo lỗi HTTP 403, kiểm tra lại Search Key có bị dán sai, thừa khoảng trắng, hoặc dùng nhầm key khác không.