HƯỚNG DẪN SỬ DỤNG VÀ THIẾT LẬP: SEARCH TOOL API

Tài liệu này cung cấp các hướng dẫn chi tiết để thiết lập môi trường phát triển cục bộ (Local Development), cấu hình hệ thống và cách thức tương tác với các tính năng cốt lõi của Search Tool API. Hệ thống được phát triển trên nền tảng Go (Fiber v2), kết hợp cơ sở dữ liệu MySQL, MongoDB và bộ nhớ đệm Redis.

I. HƯỚNG DẪN CÀI ĐẶT MÔI TRƯỜNG (LOCAL SETUP)

1. Yêu cầu hệ thống

Hệ thống yêu cầu các công cụ nền tảng sau để khởi chạy:

Go: Phiên bản 1.22 trở lên.

Docker & Docker Compose: Phiên bản mới nhất (dành cho việc khởi tạo Database và Cache).

Make: Tùy chọn (dùng để chạy các script tự động nếu có).

2. Các bước khởi chạy dự án

Bước 1: Khởi tạo biến môi trường
Di chuyển vào thư mục gốc của dự án API và nhân bản tệp môi trường mẫu:

Vui lòng mở tệp .env và tùy chỉnh các thông số (Database, Token, Webhook) theo cấu hình tại thiết bị của bạn.

Bước 2: Khởi động các dịch vụ nền (Background Services)
Sử dụng Docker để khởi chạy đồng thời MySQL, MongoDB và Redis:

Bước 3: Tải thư viện và Khởi chạy ứng dụng
Cài đặt các gói phụ thuộc và chạy HTTP Server (mặc định tại Port 33003):

Bước 4: Kiểm tra trạng thái hệ thống
Thực hiện một truy vấn HTTP GET cơ bản để xác nhận server đang hoạt động:

II. HƯỚNG DẪN TƯƠNG TÁC API (API INTERACTION GUIDE)

Hệ thống cung cấp một tập hợp các API RESTful để quản trị. Việc giao tiếp với API được phân tách thành 3 cơ chế xác thực bảo mật khác nhau tùy thuộc vào đối tượng gọi (User hoặc Tool).

1. Cơ chế xác thực (Authentication)

JWT Bearer Token (/api/*): Dành cho Quản trị viên thao tác trên giao diện Admin (Quản lý User, Proxy, Keyword). Client cần gọi API Login để lấy Token và truyền vào Header: Authorization: Bearer <token>.

API Key (/search/*, /anchor-text/*): Dành cho các hệ thống nội bộ giao tiếp với nhau. Yêu cầu truyền Header: x-api-key: <API_SEARCH_TOKEN>.

Webhook Key (/webhook/*): Dành cho các Tool Server trả kết quả về. Yêu cầu truyền Header: x-webhook-key: <WEBHOOK_KEY>.

2. Quy trình làm việc cốt lõi (Core Workflows)

A. Quản lý Từ khóa & Cấu hình Quét (Keyword Management)

Người dùng sử dụng các API nhóm Keyword để thiết lập mục tiêu SEO cần theo dõi:

Tạo Keyword: Gọi POST /api/keyword với payload chứa mảng các từ khóa, xác định thiết bị (0: Desktop, 1: Mobile) và công cụ tìm kiếm (0: GoogleVN, 1: Google, 2: CocCoc).

Luồng xử lý ngầm: Hệ thống Cronjob (SCHEDULE_SEARCH_KEYWORD) sẽ tự động quét danh sách các từ khóa có trạng thái Enable (1), khởi tạo các yêu cầu quét và đẩy vào bảng trung gian keyword_pool_tasks trên MongoDB.

B. Phân phối Tác vụ Tìm kiếm (Search Task Distribution)

Các Tool Server (được quản lý trong bảng servers của MySQL) sẽ được phân bổ tác vụ để thực hiện tìm kiếm thực tế:

Hệ thống kiểm tra bộ nhớ đệm Redis. Nếu kết quả từ khóa đã tồn tại trong ngày, hệ thống bỏ qua bước quét và gọi Webhook trả kết quả trực tiếp.

Nếu chưa có Cache, hệ thống phân phối tác vụ đến các Tool Server có trạng thái Active, dựa trên trọng số ưu tiên (is_priority).

Tool Server tiếp nhận, kích hoạt trình duyệt ẩn danh (Chrome), thực hiện tìm kiếm và thu thập dữ liệu (Top Ads, Top Search).

C. Cập nhật Kết quả thông qua Webhook (Result Webhook)

Khi Tool Server hoàn tất việc quét một từ khóa, hệ thống không chờ phản hồi đồng bộ mà sử dụng Webhook để nhận kết quả:

Tool gọi POST /webhook/update-search-result/{id} với payload chứa dữ liệu URL, Rank, thiết bị và thông tin Proxy đã dùng.

Search Tool API nhận dữ liệu, cập nhật bản ghi vào MongoDB (keyword_results) và phản hồi trạng thái hoàn tất.

D. Quản lý Mạng lưới Proxy (Proxy Rotation & Management)

Hệ thống tích hợp module Proxy để đảm bảo các Tool Server không bị chặn IP:

Import Proxy: Quản trị viên có thể sử dụng POST /api/proxy/import để tải lên danh sách hàng loạt proxy qua tệp Excel (.xlsx).

Cấp phát Proxy: Khi Tool chuẩn bị quét, nó gọi POST /webhook/proxy/get-proxy (kèm task_id). Hệ thống sẽ tìm proxy khả dụng (chưa vượt quá số luồng truy cập tối đa) và cấp phát.

Đảo IP (Rotation): Đối với các Proxy động, sau khi Tool trigger URL đảo IP thành công, Tool sẽ gọi POST /webhook/proxy-rotation-result/{id} để hệ thống API cập nhật IP Public mới và khu vực địa lý.

III. CẤU HÌNH THAM SỐ MÔI TRƯỜNG QUAN TRỌNG

Dưới đây là các nhóm biến môi trường trong tệp .env cần đặc biệt chú ý khi vận hành hệ thống:

Tích hợp Webhook (Webhook Integration):

WEBHOOK_HOST: Domain gốc của API Server (VD: http://127.0.0.1:33003) để Tool Server biết đường dẫn gọi ngược lại.

WEBHOOK_KEY: Chuỗi mã hóa bí mật để xác thực các request gửi vào route /webhook/*.

Điều phối Proxy (Proxy Throttling):

PROXY_USE_MAX: Giới hạn số lượng tác vụ (concurrent) được phép dùng chung một Proxy.

PROXY_ROTATE_MAX_CONCURRENT: Số luồng tối đa cho phép thực hiện việc đảo IP cùng lúc.

Lên lịch tự động (Cron Schedule):

SCHEDULE_SEARCH_KEYWORD: Biểu thức Cron quy định tần suất gom nhóm và phân phối tác vụ tìm kiếm từ khóa.

SCHEDULE_REPORT_TRAFFIC: Biểu thức Cron quy định thời điểm trích xuất báo cáo dữ liệu traffic.

Cảnh báo Telegram (Telegram Alerting):

Yêu cầu khai báo TELEGRAM_BOT_TOKEN và các CHAT_ID tương ứng (ERROR_ID, REPORT_ID) để hệ thống gửi các lỗi liên quan đến Proxy chết hoặc Timeout đến đội ngũ vận hành.

User Guide

HƯỚNG DẪN SỬ DỤNG VÀ THIẾT LẬP: SEARCH TOOL API#

I. HƯỚNG DẪN CÀI ĐẶT MÔI TRƯỜNG (LOCAL SETUP)#

1. Yêu cầu hệ thống#

2. Các bước khởi chạy dự án#

II. HƯỚNG DẪN TƯƠNG TÁC API (API INTERACTION GUIDE)#

1. Cơ chế xác thực (Authentication)#

2. Quy trình làm việc cốt lõi (Core Workflows)#

A. Quản lý Từ khóa & Cấu hình Quét (Keyword Management)#

B. Phân phối Tác vụ Tìm kiếm (Search Task Distribution)#

C. Cập nhật Kết quả thông qua Webhook (Result Webhook)#

D. Quản lý Mạng lưới Proxy (Proxy Rotation & Management)#

III. CẤU HÌNH THAM SỐ MÔI TRƯỜNG QUAN TRỌNG#