Tools V2 Worker Engine — Tổng Quan

Tools V2 là Worker Engine tự động hóa hai nghiệp vụ chính: tạo traffic trình duyệt thực và gửi báo cáo bảo mật tự động đến hơn 100 nền tảng toàn cầu.

Không có giao diện người dùng. Hoạt động như một worker nền, liên tục nhận lệnh từ Go API Backend, thực thi tác vụ trên Chrome thực (Puppeteer + Bun), rồi gửi kết quả về. Toàn bộ quá trình diễn ra tự động sau khi cấu hình.

Xây dựng bằng Bun + TypeScript + Elysia + Puppeteer, chạy trên cổng 3005. Có thể deploy nhiều instance trên nhiều máy chủ — mỗi instance tự đăng ký với Go API qua SERVER_ID và nhận task tự động, không cần cấu hình thêm.

Các nhóm chức năng chính

Tạo traffic thực — Mở Chrome thật, tìm kiếm từ khóa, click quảng cáo hoặc kết quả tự nhiên, ở lại trang đủ lâu. Hỗ trợ 5 loại flow: Google Ads, CocCoc Ads, Organic Search (Google/CocCoc), Kill (Negative SEO), Home Traffic (Direct).

Gửi báo cáo bảo mật — Tự động điền form báo cáo vi phạm trên 100+ nền tảng (browser-based) hoặc gửi email đến địa chỉ abuse (email-based). Nội dung do GPT-4o-mini tạo ra theo prompt riêng của từng nền tảng.

Chống phát hiện bot — 11 lớp stealth kỹ thuật: xóa navigator.webdriver, patch navigator/plugins, spoof WebGL/Audio fingerprint, disable WebRTC, ghost cursor (Bezier), random timing, proxy rotation, browser profiles, geolocation matching, resource blocking, timezone spoofing.

Tự phục hồi — Khi server crash, tất cả task đang PROCESSING được reset về PENDING khi khởi động lại. Task bị kẹt quá 20 phút tự động được reset bởi cron job.

Giám sát từ xa — Endpoint GET / trả về snapshot trạng thái (số Chrome đang chạy, task đang xử lý, proxy đang dùng). Endpoint GET /logs cho phép đọc log từ xa mà không cần SSH.

Bussiness | Logic

Tài liệu nghiệp vụ mô tả các tính năng mà Tools V2 thực thi — từ góc nhìn người vận hành.

1. Thống kê hàng ngày — Tools V2 là nguồn tạo ra dữ liệu traffic. Mỗi lượt click thành công được ghi nhận theo giờ và hiển thị trên màn hình này.

2. Thống kê hệ thống — Tools V2 thực thi 3 loại chiến dịch: Click Ads (tiêu hao ngân sách đối thủ), Negative SEO (tăng bounce rate), Traffic Tự Nhiên (cải thiện SEO). Kết quả từng domain được cập nhật sau mỗi lượt thực thi.

3. Tìm kiếm tự động — Tools V2 thực hiện tìm kiếm thực tế trên Google/CocCoc, bóc tách toàn bộ kết quả SERP (URL, rank, loại ads/organic) và gửi về API qua webhook. Cron job quét lại mỗi 30 phút.

4. Trung tâm Báo cáo — Tools V2 nhận report task, lấy AI prompt từ API, gọi GPT-4o-mini tạo nội dung, điền form hoặc gửi email, giải CAPTCHA tự động, chụp ảnh bằng chứng và gửi kết quả về.

6. Quản lý Hệ thống — Tools V2 nhận proxy từ API qua webhook, thực hiện xoay IP khi được yêu cầu và báo cáo kết quả xoay về. Proxy được phân bổ sao cho không có hai task nào dùng cùng proxy cùng lúc.

7. Quản lý tài khoản Google — Tools V2 nhận profile từ API, dùng cookie/localStorage đã lưu để đăng nhập không cần nhập lại, lưu session data sau mỗi lần dùng, báo cáo đăng nhập thất bại về API.

Architecture

Tài liệu kỹ thuật cho developer làm việc với Tools V2 Worker Engine.

System Architecture — Kiến trúc phân tầng 4 lớp (api/ → services/ → utils/ → config/), CronTaskGroup singleton điều phối traffic (polling mỗi giây, staggered launch 3 giây/browser), ReportTaskCron singleton điều phối báo cáo (1 task đồng thời, 30 phút giữa các lần), luồng dữ liệu end-to-end từ nhận task đến gửi kết quả.

Code Structure — Cây thư mục đầy đủ: api/ (task-group, report-tasks, proxy, search, monitor, screenshot), services/ (ai, browser, captcha, profiles, report-tasks, email, evidence, screenshot, google-accounts, webhook, zing-proxy), utils/browser_manager/ (11 stealth files, ghost-cursor, geolocation, device, session-manager).

Environment & Configuration — Biến môi trường: API_HOST, API_KEY, WEBHOOK_API_KEY, SERVER_ID, giới hạn đồng thời (CRON_TASK_LIMIT, BROWSER_LIMIT_PER_PROCESS, CRON_REPORT_LIMIT), cấu hình Anti-Captcha, OpenAI (GPT-4o-mini), DigitalOcean Spaces, Cloudinary, SMTP.

Logs And Monitoring — Log tổ chức theo service và ngày (storage/log/{service}/{YYYY-MM-DD}/{level}.log). Endpoint GET /logs?filePath=... đọc log từ xa. Error categorizer tự động phân loại lỗi: NETWORK_TIMEOUT, PROXY_ERROR, CAPTCHA_DETECTED, BOT_DETECTED, BROWSER_CRASH.

Database Schema — Schema MongoDB nội bộ của Tools V2: task_groups (TaskGroupStatus: PENDING=0, PROCESSING=1, COMPLETED=2), proxies (Status: PENDING→COMPLETED, rotation logic, domain_blocks), search (keyword ranking tasks), report_tasks (ReportPlatform enum 100+ values, ReportType: EMAIL_BASED/BROWSER_BASED). Tách biệt hoàn toàn với MongoDB của Go API.

Deployment

Local — Chạy Tools V2 trên máy local với bun run dev. Cần khởi động MongoDB riêng qua Docker Compose (docker compose up -d). Cấu hình API_HOST trỏ đến Go API local, BROWSER_LIMIT_PER_PROCESS=1 để tiết kiệm RAM.

Staging — Pipeline GitLab tự động: SSH vào server, git pull, docker compose up --build -d. Build trực tiếp trên server, mất 5–10 phút (tải Bun, cài packages, tải Chrome).

Production — Deploy trên Linux server (Ubuntu 22.04 LTS). Cần cài thư viện hệ thống cho Chrome. Cấu hình BROWSER_LIMIT_PER_PROCESS dựa trên RAM server (mỗi Chrome ~300MB, server 16GB chạy được ~28-30 instance). Rollback bằng cách đổi tag image.

API Interface

Tài liệu chi tiết từng endpoint của Tools V2, được nhóm theo chức năng.

🖥️ System — Giám sát trạng thái worker, health check, đọc log từ xa.

Trạng thái tổng quan worker — GET / trả về snapshot: số Chrome đang chạy (browserSessionRunning), task đang xử lý (task.totalProcessRunning), giới hạn cấu hình (task.maxProcess), proxy processes đang chạy. Endpoint quan trọng nhất để giám sát worker.

Health check — GET /health trả về status: "ok", thời gian server, uptime. Go API Backend gọi mỗi 30 giây — không phản hồi 3 lần liên tiếp → worker bị đánh dấu offline.

Đọc file log từ xa — GET /logs?filePath=... đọc log mà không cần SSH. Format path: {service}/{YYYY-MM-DD}/{level}.log. Các service: task-group-cron, cron_proxy, report-task-cron, browser_manager.

📦 Group Task — Tạo và quản lý task groups (đơn vị công việc traffic).

Tạo nhiều task groups — POST /api/task-traffics/multiple — Go API đẩy traffic tasks xuống worker. Body là mảng 2 chiều, mỗi task group chứa nhiều tasks với cấu hình traffic_type (method, only_ads, is_kill, organic_engine, links), traffic_device, device_os, geolocation, page_view. Xác định flow: method=0 → Home Traffic, method=1+only_ads=true → Ads, method=1+is_kill=true → Kill, method=1+engine=2 → CocCoc.

Lấy danh sách task groups — GET /api/task-traffics — Xem toàn bộ hàng đợi. Mỗi task group có status (PENDING=0, PROCESSING=1, COMPLETED=2), proxy đang dùng, user_agent, geolocation.

Xóa tất cả task groups — DELETE /api/task-traffics — Reset hoàn toàn hàng đợi. Thao tác không thể hoàn tác, chỉ dùng khi worker bị kẹt vòng lặp lỗi.

✅ Tasks — Xem và cập nhật kết quả từng phiên Chrome.

Lấy tasks có phân trang và lọc — GET /api/tasks — Filter theo status, project_id, result_status (1=SUCCESS, -1=ERROR, -2=NOT_FOUND, -3=CAPTCHA). Xem rank (thứ hạng SERP), ip_public, execution_time, screenshot_url.

Cập nhật một task — PUT /api/tasks/:id — Worker gọi để lưu kết quả: result_status, rank, ip_public, execution_time, screenshot_url, user_agent.

🌐 Proxies — Quản lý proxy pool nội bộ của Tools V2.

Lấy tất cả proxy records — GET /api/proxies — Mỗi proxy có vòng đời: PENDING (cần rotate) → COMPLETED (sẵn sàng dùng). Xem rotate_url, ip_public, domain_blocks, retry_count.

Reset proxy process counter — POST /api/proxies/reset — Reset bộ đếm khi worker bị crash và counter bị stuck, ngăn proxy mới được xử lý.

📊 Report Tasks — Tạo và quản lý report tasks cho từng domain.

Tạo report tasks cho một domain — POST /api/report-tasks/create — Tạo tasks báo cáo domain đến các tổ chức bảo mật. Chỉ định domain, platforms (mảng ReportPlatform enum), proxyUrl, profileUrl, priority. Mặc định dùng 14 browser-based platforms.

Tạo email-based report tasks — POST /api/report-tasks/create-email — Tạo tasks gửi email trực tiếp đến Kaspersky, Bitdefender, OpenPhish, 80+ nền tảng khác. Cần profile có Gmail App Password.

Lấy report task PENDING tiếp theo — GET /api/report-tasks/next — Worker gọi để lấy task tiếp theo. Sau khi lấy, task chuyển sang IN_PROGRESS. Chỉ 1 task đồng thời, bắt buộc chờ 30 phút giữa các lần.

Cập nhật status của report task — PUT /api/report-tasks/:id — Worker báo cáo kết quả: COMPLETED hoặc FAILED kèm screenshot URL bằng chứng.

Kích hoạt thực thi thủ công — POST /api/report-tasks/trigger — Kích hoạt cron job ngay lập tức, không cần chờ lịch tự động. Dùng khi cần xử lý tasks khẩn cấp.

Lấy report tasks — GET /api/report-tasks — Lấy danh sách report tasks. Endpoint PUBLIC.

Thống kê reports — GET /api/report-tasks/stats — Thống kê tổng hợp: tổng tasks, tỷ lệ thành công/thất bại, phân loại theo platform. Endpoint PUBLIC.

📋 Report Sites — Quản lý cấu hình nền tảng báo cáo.

Lấy danh sách report sites — GET /api/report-sites — Lấy danh sách 100+ nền tảng được cấu hình. Endpoint PUBLIC.

Toggle tất cả sites — POST /api/report-sites/toggle-all — Bật/tắt tất cả sites cùng lúc.

Cập nhật hàng loạt AI prompts — PUT /api/report-sites/bulk-prompts — Cập nhật AI prompts cho nhiều sites cùng lúc.

PC report dashboard — GET /api/report-sites/pc-dashboard — Lấy dữ liệu PC report cho dashboard. Endpoint PUBLIC.

🔍 Search — Tạo và quản lý search tasks để quét thứ hạng từ khóa.

Tạo nhiều search tasks — POST /api/search/multiple — Tạo tasks quét thứ hạng từ khóa. Mỗi task mở Chrome, tìm kiếm và trả về danh sách kết quả kèm thứ hạng (ads[] và search[]). Hỗ trợ Google VN, Google quốc tế, CocCoc.

📸 Report Platforms — Gửi báo cáo đến các nền tảng bảo mật.

Submit report to multiple platforms — Gửi báo cáo đến nhiều nền tảng cùng lúc.

Get available platforms — Lấy danh sách nền tảng báo cáo đang được hỗ trợ (100+ platforms, chia browser-based và email-based).

Get platform statistics — Thống kê tỷ lệ thành công/thất bại theo từng nền tảng.

📡 Monitor — Giám sát tài nguyên hệ thống.

Thông tin tài nguyên hệ thống — GET /api/monitor — Snapshot CPU, RAM, Disk, số Chrome instances, giới hạn cấu hình. Nếu used_session gần bằng total_session, worker đang full capacity.

🪝 Webhooks — Các endpoint webhook luôn PUBLIC, không cần auth.

Lấy proxy cho task — Worker gọi để lấy proxy phù hợp cho task. LUÔN PUBLIC.

Báo cáo kết quả proxy rotation — Worker báo cáo kết quả sau khi rotate proxy. LUÔN PUBLIC.

Lấy profile ngẫu nhiên — Worker lấy profile ngẫu nhiên đang khả dụng để thực thi task. LUÔN PUBLIC.

Cập nhật kết quả thực thi task — Worker gọi sau khi hoàn thành task để báo cáo kết quả. LUÔN PUBLIC.

Gửi kết quả SERP keyword — Worker gửi kết quả SERP của keyword. LUÔN PUBLIC.

Cập nhật trạng thái report task — Cập nhật trạng thái report task. LUÔN PUBLIC.

Lock/Unlock CocCoc token — Lock token để sử dụng độc quyền, unlock để trả về pool. LUÔN PUBLIC.

Tổng quan

Tools V2 Worker Engine — Tổng Quan#

Các nhóm chức năng chính#

Bussiness | Logic#

Architecture#