TÀI LIỆU KỸ THUẬT: SYSTEM ARCHITECTURE - SEARCH TOOL API

Hệ thống Search Tool API được thiết kế theo kiến trúc hướng dịch vụ (Service-Oriented Architecture), đóng vai trò là hệ thống trung tâm điều phối (Orchestrator). Ứng dụng mô hình Master-Worker bất đồng bộ thông qua các bộ đệm trung gian (Buffer) và giao tiếp hai chiều qua cơ chế Webhook.

I. SƠ ĐỒ KIẾN TRÚC TỔNG THỂ (HIGH-LEVEL ARCHITECTURE)

Sơ đồ mô tả luồng giao tiếp giữa các nhóm Máy khách (Clients), Cổng giao tiếp API (API Gateway) và Hệ thống Cơ sở dữ liệu.

+------------------------------------------------------------------+
|                        CLIENTS / CONSUMERS                       |
|  Admin Frontend (Vue 3)  |  Tool Search Server (Node.js/Bun)     |
+-------------+------------+--------------+------------------------+
              |  JWT Auth                 |  API Key / Webhook Key
              v                           v
+------------------------------------------------------------------+
|                  SEARCH TOOL API (Go + Fiber)                    |
|                        Port: 33003                               |
|                                                                  |
|  Middleware Layer: CORS | Helmet | Logger | JWT | API Key | WH   |
|                                                                  |
|  Route Groups & Security Protocols:                              |
|  /api/* (JWT Auth)   - Quản trị User, Proxy, Server      |
|  /search/* (API Key)    - Quản lý KeywordPoolTask           |
|  /anchor-text/* (API Key)    - Quản lý AnchorText                |
|  /webhook/* (WH Key)     - Xử lý Callback Proxy & Kết quả    |
|  /ws            (Socket.IO)  - Phát luồng dữ liệu thời gian thực |
|                                                                  |
|  Background Scheduler (gocron):                                  |
|  - Thiết lập lại trạng thái Proxy lỗi.                           |
|  - Lịch trình phân phối tác vụ tìm kiếm (Send Tasks).            |
|  - Lịch trình gom nhóm từ khóa (Search Keyword Cron).            |
+---+------------------+------+-----+-----------------------------+
    |                  |            |
+---v---+      +-------v------+  +--v----------+
| MySQL |      |   MongoDB    |  |    Redis    |
| GORM  |      | Mongo Driver |  |   (Cache)   |
|       |      |              |  |             |
|users  |      |keywords      |  |task cache   |
|servers|      |results       |  |locks        |
|logs   |      |proxies       |  |             |
|       |      |anchor_texts  |  +-------------+
|       |      |pool_tasks    |
+-------+      +--------------+

II. PHÂN TÍCH LUỒNG HOẠT ĐỘNG CỐT LÕI (CORE WORKFLOWS)

Hệ thống vận hành thông qua 3 luồng tác vụ ngầm chính nhằm đảm bảo khả năng mở rộng và chịu tải cao.

1. Luồng Phân phối Tác vụ Từ khóa (Keyword Search Flow)

Cơ chế sử dụng bảng đệm trung gian keyword_pool_tasks để kiểm soát tốc độ (Throttling) và cân bằng tải.

Khởi tạo dữ liệu (Cronjob SCHEDULE_SEARCH_KEYWORD):

Tiến trình SearchKeyword() truy xuất toàn bộ từ khóa có trạng thái Kích hoạt từ MongoDB.

Tạo các yêu cầu tách biệt dựa trên tổ hợp Nền tảng thiết bị (Device) và Công cụ tìm kiếm (Engine).

Lưu các yêu cầu này vào bộ đệm keyword_pool_tasks.

Xử lý Bộ đệm (Cronjob keyword_pool_task):

Chạy lặp mỗi 60 giây, trích xuất dữ liệu từ keyword_pool_tasks.

Kiểm tra Cache Redis: Nếu tổ hợp dữ liệu đã tồn tại trong Cache, hệ thống lập tức gọi Webhook trả về kết quả cũ và hủy tác vụ.

Nếu chưa tồn tại, tác vụ được chuyển trạng thái sang PROCESSING.

Phân bổ theo Trọng số (Weighted Distribution): Hệ thống phân phát tác vụ đến các Tool Servers (truy xuất từ MySQL). Server có cờ IsPriority=true nhận trọng số 5, server thường nhận trọng số 2.

API gọi lệnh HTTP POST trực tiếp đến Tool Server, sau đó xóa tác vụ khỏi bộ đệm khi nhận được phản hồi tiếp nhận. Trạng thái tác vụ sẽ được thiết lập lại (Reset) nếu xảy ra lỗi mạng.

Cập nhật Kết quả (Webhook Callback):

Tool Server hoàn tất phân tích và đẩy dữ liệu về hệ thống qua POST /webhook/update-search-result/:id.

API xử lý và ghi bản ghi hoàn chỉnh vào Collection keyword_results.

2. Luồng Phân tích Văn bản Neo (Anchor Text Flow)

Hoạt động tương tự cơ chế phân phối từ khóa nhưng phục vụ cho nghiệp vụ thu thập dữ liệu liên kết ngược (Backlinks).

Hệ thống ngoại vi gọi POST /anchor-text/search để đẩy dữ liệu vào bộ đệm anchor_texts.

Tiến trình Cron anchor_text chạy lặp mỗi 60 giây để trích xuất tác vụ, đối chiếu Cache Redis.

Phân bổ tác vụ đến Tool Server. Tool Server sau khi duyệt liên kết hoàn tất sẽ phản hồi dữ liệu thông qua định tuyến POST /webhook/update-search-anchor-text/:id.

3. Luồng Quản trị Chu kỳ Proxy (Proxy Rotation Flow)

Đảm bảo Tool Server luôn có địa chỉ IP khả dụng, tránh bị chặn bởi tường lửa đối phương.

Cấp phát IP:

Tool Server trước khi chạy tác vụ gọi POST /webhook/proxy/get-proxy.

API truy vấn MongoDB để tìm Proxy thỏa mãn điều kiện: Đang kích hoạt, chưa đạt giới hạn max_use, và không trong trạng thái lỗi.

Tăng biến đếm in_use và ghi nhận định danh tác vụ vào lịch sử Proxy.

Cập nhật Vòng lặp:

Sau khi Tool Server kích hoạt API đổi IP của nhà mạng thành công, nó gửi lệnh POST /webhook/proxy-rotation-result/:id.

API trung tâm cập nhật tham số ip_public, vị trí địa lý (region), và gỡ bỏ cờ đang xoay vòng (is_rotating=false).

System Architecture

TÀI LIỆU KỸ THUẬT: SYSTEM ARCHITECTURE - SEARCH TOOL API#

I. SƠ ĐỒ KIẾN TRÚC TỔNG THỂ (HIGH-LEVEL ARCHITECTURE)#

II. PHÂN TÍCH LUỒNG HOẠT ĐỘNG CỐT LÕI (CORE WORKFLOWS)#

1. Luồng Phân phối Tác vụ Từ khóa (Keyword Search Flow)#