1. Tổng Quan Kiến Trúc#
1.1. Mô Hình Tổng Thể#
Tools V2 được tổ chức theo mô hình phân tầng rõ ràng. Toàn bộ mã nguồn nằm trong thư mục src/ và chia thành bốn nhóm chính:src/api/ — Tầng giao tiếp: REST endpoints, cron jobs, và các module nghiệp vụ cấp cao.
src/services/ — Tầng dịch vụ: Business logic tái sử dụng, không phụ thuộc vào HTTP layer.
src/utils/ — Tầng tiện ích: Browser manager, logger, middleware, env config.
src/config/ — Cấu hình: Database, email, anti-captcha, security vendors.
src/index.ts. File này khởi tạo Elysia app, đăng ký tất cả middleware, routes, cron jobs, và kết nối database.1.2. Luồng Khởi Động#
Khi bun run src/index.ts được thực thi:Elysia app được khởi tạo với errorHandler và ipValidationMiddleware.
Swagger documentation được đăng ký tại /swagger.
Tất cả API routes được mount dưới prefix /api.
Tám cron jobs được đăng ký với protect: true.
onStart hook kết nối MongoDB, xóa tmp/user-data/, và log thông tin khởi động.
Server bắt đầu lắng nghe trên PORT (mặc định 3005).
1.3. Nguyên Tắc Thiết Kế#
Toàn bộ kiến trúc tuân theo các nguyên tắc:Mỗi module trong src/api/ có đủ bộ: controller, service, model, dto, cron.
Services trong src/services/ không import từ src/api/ — chỉ chiều ngược lại.
Tất cả biến môi trường được đọc qua src/utils/env.ts, không đọc trực tiếp process.env.
Tất cả cron jobs có protect: true để tránh overlap.
Tất cả lỗi được bắt và log với context đầy đủ.
2. Tầng API — src/api/#
2.1. Cấu Trúc Module#
Tầng API gồm tám module, mỗi module phục vụ một nhóm nghiệp vụ riêng biệt:src/api/
├── index.ts ← Tổng hợp tất cả routes dưới prefix /api
├── task-group/ ← Module trung tâm: traffic task execution
├── report-tasks/ ← Module báo cáo bảo mật tự động
├── proxy/ ← Module quản lý proxy pool
├── search/ ← Module quét thứ hạng từ khóa
├── task/ ← Module task cũ (legacy)
├── screenshot/ ← API chụp ảnh website
├── monitor/ ← API giám sát hiệu suất server
└── test/ ← Endpoints test (development only)
2.2. Module task-group — Trung Tâm Traffic#
Đây là module quan trọng nhất, chịu trách nhiệm toàn bộ nghiệp vụ tạo traffic.task-group/
├── task-group.controller.ts ← REST endpoints: POST /multiple, GET /, DELETE /:id
├── task-group.cron.ts ← CronTaskGroup class: điều phối thực thi
├── task-group.service.ts ← CRUD + business logic với MongoDB
├── task-group.model.ts ← TaskGroup schema (Typegoose)
├── task-group.dto.ts ← Request/response types
├── cron/
│ ├── resource-allocator.ts ← Phân bổ slots cho từng loại task
│ ├── link-tracker.ts ← Theo dõi links đang xử lý (tránh duplicate)
│ ├── cleanup-service.ts ← Xóa tasks cũ hàng ngày
│ ├── memory/ ← Kiểm tra memory trước khi spawn browser
│ ├── process/ ← ProcessOrchestrator: thực thi task group
│ ├── proxy/ ← Lấy proxy cho task
│ ├── session/ ← Tạo browser session
│ ├── screenshot/ ← Chụp và upload ảnh bằng chứng
│ └── domain/ ← Extract domain từ clicked ads
└── task-action/
├── task-action-executor.ts ← Điều phối flow execution
├── flows/ ← Ads, CocCoc, Home Traffic, Kill flows
├── search/ ← Search logic trong flows
└── captcha/ ← CAPTCHA handling trong flows
CronTaskGroup là class singleton được export từ task-group.cron.ts. Nó duy trì trạng thái:_processRunning: Tổng số tasks đang chạy.
_runningByType: Map theo dõi số tasks đang chạy cho từng loại (normalClick, killTask, homeTraffic, coccoc).
_isStarting: Flag tránh re-entrant execution.
task-group-cron-direct gọi cronTaskGroup.start(). Logic trong start():Kiểm tra và recover stuck tasks (PROCESSING quá 20 phút).
Dọn dẹp orphan browser sessions.
Tính availableSlots = maxProcess - totalProcessRunning.
Lấy danh sách tasks khả dụng từ MongoDB theo từng loại.
Gọi resourceAllocator.getAllocation() để tính số slots cho mỗi loại.
Khởi động tasks theo thứ tự ưu tiên: killTask > homeTraffic > normalClick > coccoc.
Mỗi browser được khởi động cách nhau 3 giây (staggered launch).
task-group-api-request-cron gọi cronTaskGroup.requestTasksFromAPI() mỗi giây. Logic:Đếm tổng pendingCount + processingCount trong MongoDB.
Nếu tổng thấp hơn max(maxProcess * 2, 20), request thêm tasks từ Go API.
Số tasks request mỗi lần: min(maxProcess * 10, 300).
2.3. Module report-tasks — Báo Cáo Bảo Mật#
Module này quản lý toàn bộ vòng đời của report tasks.report-tasks/
├── report-task.controller.ts ← REST endpoints
├── report-task.cron.ts ← ReportTaskCron class
├── report-task.model.ts ← ReportTask schema + ReportPlatform enum
└── cron/
├── report-task-request.service.ts ← Kiểm tra điều kiện request task
├── memory-manager.ts ← Kiểm tra memory
├── proxy/ ← Lấy proxy cho report task
├── session/ ← Tạo browser session
├── platform/ ← Thực thi report trên từng platform
├── task-executor/ ← Orchestrate toàn bộ task execution
├── callback/ ← Gửi callback về Go API
└── local/ ← Local cascade service
ReportTaskCron có logic phức tạp hơn traffic cron vì mỗi report task có thể là browser-based hoặc email-based:maxConcurrentTasks = 1: Chỉ chạy một report task tại một thời điểm.
MIN_INTERVAL_MS = 30 phút: Bắt buộc chờ 30 phút giữa các lần thực thi.
Email tasks có random timeout từ 30 đến 90 phút.
Xác định loại task: email-based hay browser-based dựa trên task.reportType.
Với email-based: Gọi _platformExecutor.executeEmailPlatformReport() trực tiếp, không cần browser.
Với browser-based: Tạo AI content trước, sau đó tạo browser session, rồi thực thi.
Cập nhật trạng thái task sau khi hoàn thành.
Gọi _localCascadeService.run() nếu thành công.
2.4. Module proxy — Quản Lý Proxy Pool#
Module proxy quản lý vòng đời của proxy records trong MongoDB nội bộ.proxy/
├── proxy.controller.ts ← REST endpoints: POST /create, GET /, PUT /:id
├── proxy.cron.ts ← CronProxy class
├── proxy.service.ts ← CRUD operations
├── proxy.model.ts ← Proxy schema với Status enum
└── proxy.dto.ts ← Request types
CronProxy chạy hai cron jobs song song:proxy-cron-direct gọi cronProxy.start() mỗi giây: Lấy proxy có status PENDING, thực hiện rotation (gọi rotate_url), kiểm tra IP public, cập nhật status thành COMPLETED.
proxy-cron-webhook-direct gọi cronProxy.runWebhook() mỗi giây: Lấy proxy có status COMPLETED, gọi webhook_url để thông báo proxy đã sẵn sàng, xóa proxy record sau khi webhook thành công.
rotateProxy() hỗ trợ nhiều format response từ rotate URL:httpProxy format: "ip:port:user:pass".
data format: { host, httpPort, location }.
ipv4 format: { ipv4, port, username, password }.
ip/port format: { ip, port, username, password }.
address format: { address: "ip:port" }.
proxy string format: { proxy: "ip:port" }.
Status/Data format: { Status, Data: [{ public_ip, http_port }] }.
Simple IP:port string: "1.2.3.4:8080".
PROXY_RETRY_LIMIT lần thất bại, proxy bị xóa.2.5. Module search — Quét Thứ Hạng Từ Khóa#
Module search thực hiện tìm kiếm từ khóa và ghi lại thứ hạng của domain trong SERP.search/
├── search.controller.ts ← REST endpoints
├── search.cron.ts ← SearchCron class
├── search.service.ts ← CRUD operations
├── search.model.ts ← Search schema
├── search.dto.ts ← Request types
├── cron/
│ ├── search-executor.ts ← Thực thi tìm kiếm
│ └── webhook-search.cron.ts ← Gửi kết quả về Go API
└── flows/
├── search-flow-executor.ts ← Điều phối flow
├── search-navigator.ts ← Điều hướng đến search engine
├── search-searcher.ts ← Gõ từ khóa và tìm kiếm
├── search-paginator.ts ← Phân trang kết quả
└── search-results-extractor.ts ← Extract ranking data
2.6. Module monitor — Giám Sát Server#
Module monitor cung cấp API để Go API Backend ping và kiểm tra trạng thái worker.monitor.controller.ts: Endpoint nhận ping từ Go API.
monitor.service.ts: Logic xử lý ping, cập nhật last-seen timestamp.
2.7. Module screenshot — Chụp Ảnh Website#
Module screenshot cung cấp API để chụp ảnh một URL bất kỳ theo yêu cầu.screenshot.controller.ts: Endpoint nhận URL, trả về screenshot URL.
Sử dụng screenshotmachine.service.ts hoặc Puppeteer tùy cấu hình.
3. Tầng Services — src/services/#
3.1. Tổng Quan#
Tầng services chứa toàn bộ business logic có thể tái sử dụng. Các services không biết về HTTP layer — chúng chỉ nhận input, xử lý, và trả về output. Điều này giúp dễ dàng test và tái sử dụng giữa các modules.src/services/
├── ai/ ← OpenAI integration, report content generation
├── api/ ← Giao tiếp với Go API Backend
├── behavior/ ← Human behavior simulation
├── browser/ ← Browser session management
├── captcha/ ← CAPTCHA detection và solving
├── check-proxy/ ← Kiểm tra IP và region của proxy
├── domain/ ← Domain lookup và content fetching
├── email/ ← SMTP email sending
├── evidence/ ← Thu thập bằng chứng domain
├── free-proxy/ ← Lấy proxy miễn phí từ nguồn công cộng
├── google-accounts/ ← Google account management và login
├── profiles/ ← Browser profile management
├── proxy/ ← Proxy rotation logic
├── report-tasks/ ← Report task execution per platform
├── screenshot/ ← Screenshot capture và upload
├── search/ ← Search callback domain service
├── webhook/ ← Webhook callback utilities
└── zing-proxy/ ← ZingProxy API integration
3.2. AI Services — src/services/ai/#
Đây là nhóm services phức tạp nhất, xử lý toàn bộ tích hợp với OpenAI.ai/
├── chatgpt.service.ts ← Singleton service, gọi OpenAI API
├── platform-prompt.service.ts ← Lấy prompt cho từng platform
├── platform-prompt-factory.service.ts ← Factory tạo prompt generators
├── indexer.service.ts ← Index các platform services
├── api/
│ └── openai-client.ts ← OpenAI client wrapper
├── cost/
│ └── cost-calculator.ts ← Tính chi phí API calls
├── generic/
│ └── generic-report-generator.ts ← Generator cho platforms không có generator riêng
├── parsers/
│ └── response-parser.ts ← Parse và validate AI responses
├── platform-prompt/
│ ├── fallback-generators/ ← Fallback khi API không khả dụng
│ ├── prompt-builders/ ← Xây dựng prompt cho từng platform
│ └── report-generators/ ← Tạo report content
├── unified-prompt/
│ ├── builders/ ← Unified prompt builders
│ ├── generators/ ← Unified generators
│ ├── mappers/ ← Map platform data
│ ├── storage/ ← Cache prompt configs
│ ├── templates/ ← Prompt templates
│ └── transformers/ ← Transform AI responses
└── utils/
├── json-fixer.ts ← Sửa malformed JSON từ AI
└── openai-debug-formatter.ts ← Format debug output
chatgpt.service.ts là singleton service trung tâm. Nó:Khởi tạo OpenAI client với CHATGPT_API_KEY.
Cung cấp method generateContent(prompt, config) cho tất cả AI calls.
Track chi phí mỗi call và hiển thị cost summary.
Xử lý rate limiting và retry.
platform-prompt-factory.service.ts là factory pattern để tạo prompt generator cho từng platform. Mỗi platform có generator riêng trong platform-prompt-factory/generators/. Factory nhận platform name và trả về generator phù hợp.AI đôi khi trả về JSON không hợp lệ (thiếu dấu ngoặc, trailing comma). json-fixer.ts cố gắng sửa các lỗi phổ biến trước khi parse.3.3. API Services — src/services/api/#
Ba services giao tiếp với Go API Backend:task-request.service.ts: Gọi Go API để lấy traffic tasks mới. Method requestAndCreateTaskGroups(count) gọi API và lưu tasks vào MongoDB nội bộ.
report-site-prompt.service.ts: Lấy cấu hình prompt cho từng report platform từ Go API. Cache 1 giờ.
report-sites.service.ts: Lấy danh sách report sites từ Go API.
3.4. Browser Services — src/services/browser/#
enhanced-browser-session.service.ts là service trung tâm quản lý browser sessions.browser/
├── enhanced-browser-session.service.ts ← Service chính
└── enhanced-session/
├── incognito-session-handler.ts ← Tạo incognito session
├── profile-session-handler.ts ← Tạo profile session
├── human-behavior-integration.ts ← Tích hợp human behavior
├── session-cleanup.ts ← Dọn dẹp session
├── session-data-capture.ts ← Lưu session data
├── session-statistics.ts ← Thống kê session
└── types.ts ← Type definitions
Incognito session: Không lưu cookies hay localStorage. Dùng cho anonymous tasks.
Profile session: Lưu session data để tái sử dụng. Dùng cho tasks cần đăng nhập Google.
3.5. Captcha Services — src/services/captcha/#
Đây là nhóm services phức tạp nhất về mặt kỹ thuật.captcha/
├── browser-captcha.service.ts ← Service chính, điều phối toàn bộ
├── anti-captcha.service.ts ← Giao tiếp với Anti-Captcha API
├── anticaptcha.service.ts ← Alternative Anti-Captcha client
├── anticaptcha-plugin.service.ts ← Plugin-based Anti-Captcha
├── audio-captcha.service.ts ← Giải audio CAPTCHA
├── captcha-rate-limiter.service.ts ← Rate limiting cho CAPTCHA solving
├── fingerprint-consistency.service.ts ← Đảm bảo fingerprint nhất quán
├── google-sorry-bypass.service.ts ← Bypass Google "Sorry" page
├── google-trust-builder.service.ts ← Xây dựng trust score với Google
├── detection/
│ ├── captcha-detector.ts ← Phát hiện CAPTCHA trên page
│ ├── confidence-detector.ts ← Tính confidence score
│ └── type-detector.ts ← Xác định loại CAPTCHA
├── solvers/
│ └── captcha-solver.ts ← Điều phối solving strategy
├── recaptcha/
│ └── recaptcha.service.ts ← reCAPTCHA specific logic
├── injection/
│ ├── token-injector.ts ← Inject token vào form
│ └── form-type-detector.ts ← Xác định loại form
└── stealth/
└── stealth-applier.ts ← Apply stealth trước khi giải
captcha-detector.ts scan page để tìm CAPTCHA elements.
confidence-detector.ts tính confidence score (0-100).
Nếu confidence >= ngưỡng, captcha-solver.ts được gọi.
captcha-solver.ts thử Anti-Captcha API trước.
Nếu thất bại và CAPTCHA_FALLBACK_TO_MANUAL = true, thử OpenAI Vision.
token-injector.ts inject token vào form sau khi giải xong.
3.6. Profile Services — src/services/profiles/#
profiles/
├── profile-manager.service.ts ← Service chính
├── profile.service.ts ← CRUD operations
├── session-capture.service.ts ← Lưu session data sau khi dùng
├── smart-session-restore.service.ts ← Khôi phục session thông minh
└── profile-manager/
├── browser-session-creator.ts ← Tạo browser session từ profile
├── profile-selector.ts ← Chọn profile phù hợp
├── session-cleanup.ts ← Dọn dẹp session files
├── session-manager.ts ← Quản lý active sessions
├── session-restorer.ts ← Restore session từ disk
├── session-validator.ts ← Validate session còn hợp lệ không
└── types.ts ← Type definitions
profile-selector.ts chọn profile theo các tiêu chí:Không trong cooldown period.
Phù hợp với geolocation requirement của task.
Sort theo last_used_at để ưu tiên profile ít dùng gần đây.
3.7. Report Task Services — src/services/report-tasks/#
report-tasks/
├── report-task.service.ts ← CRUD + status management
├── report-callback.service.ts ← Gửi callback về Go API
├── report-deduplication.service.ts ← Tránh submit duplicate reports
├── captcha-integration.service.ts ← CAPTCHA handling cho reports
├── proxy-snapshot.service.ts ← Snapshot proxy state
├── platforms/ ← Một file per platform
│ ├── base-report.service.ts ← Base class cho browser-based
│ ├── base-email-report.service.ts ← Base class cho email-based
│ ├── google-safe-browsing-report.service.ts
│ ├── microsoft-smartscreen-report.service.ts
│ ├── cloudflare-report.service.ts
│ ├── spamhaus-report.service.ts
│ ├── netcraft-report.service.ts
│ ├── ... (50+ platform services)
│ └── generic-email-report.service.ts ← Generic fallback
└── report-task-service/
├── task-creator.ts ← Tạo report tasks
├── task-queries.ts ← Query helpers
├── task-statistics.ts ← Thống kê
├── task-updater.ts ← Cập nhật trạng thái
├── platform-utils.ts ← Platform utilities
└── types.ts ← Type definitions
base-report.service.ts cung cấp template method pattern cho browser-based reports:navigateToReportPage(): Điều hướng đến trang báo cáo.
fillForm(content): Điền form với nội dung từ AI.
handleCaptcha(): Xử lý CAPTCHA nếu có.
submitForm(): Submit và chờ confirmation.
captureEvidence(): Chụp màn hình bằng chứng.
3.8. Google Accounts Services — src/services/google-accounts/#
google-accounts/
├── google-accounts.service.ts ← Service chính
├── account-manager.ts ← Quản lý account pool
├── account-selector.ts ← Chọn account phù hợp
├── account-availability.ts ← Kiểm tra account khả dụng
├── account-statistics.ts ← Thống kê account usage
├── session-creator.ts ← Tạo session từ account
├── session-lock.service.ts ← Lock account khi đang dùng
├── session-storage.service.ts ← Lưu/đọc session data
├── session-tracker.ts ← Theo dõi active sessions
└── google-login/
├── login-handler.ts ← Điều phối login flow
├── email-handler.ts ← Nhập email
├── password-handler.ts ← Nhập password
├── navigation-handler.ts ← Điều hướng trong login flow
└── verification-handler.ts ← Xử lý 2FA và verification
session-lock.service.ts đảm bảo không có hai tasks nào dùng cùng một Google account cùng lúc. Sử dụng Mutex pattern.3.9. Domain Services — src/services/domain/#
domain/
├── domain-lookup.service.ts ← DNS lookup, WHOIS
├── domain-identification.service.ts ← Xác định domain từ URL
├── domain-content-fetcher.service.ts ← Fetch nội dung domain
└── record-domain.service.ts ← Ghi lại domain đã xử lý
3.10. Storage Services — src/services/screenshot/#
screenshot/
├── screenshot.service.ts ← Service chính, upload ảnh
└── screenshotmachine.service.ts ← ScreenshotMachine API integration
screenshot.service.ts implement chiến lược multi-tier:Thử upload lên DigitalOcean Spaces trước.
Nếu thất bại, thử Cloudinary.
Nếu cả hai thất bại, lưu local.
Trả về URL của ảnh đã upload.
4. Tầng Utils — src/utils/#
4.1. Browser Manager — src/utils/browser_manager/#
Browser Manager là component kỹ thuật phức tạp nhất trong toàn bộ hệ thống. Nó bao bọc Puppeteer và cung cấp interface thống nhất cho tất cả browser operations.browser_manager/
├── index.ts ← Export browserManager singleton
├── browserSession.ts ← BrowserSession class
├── advanced-stealth.ts ← Advanced stealth techniques
├── captcha-detector.ts ← Phát hiện CAPTCHA trên page
├── crossSiteBehavior.ts ← Cross-site navigation behavior
├── device.ts ← Device configuration (UA, screen)
├── dom-stability.ts ← Chờ DOM ổn định
├── geolocation.ts ← Geolocation spoofing
├── geolocation-handler.ts ← Xử lý geolocation requests
├── ghost-cursor-wrapper.ts ← Wrapper cho ghost-cursor library
├── google-consent-detector.ts ← Phát hiện Google consent popup
├── keywords.ts ← Keyword utilities
├── mobile-pre-search.ts ← Mobile-specific pre-search behavior
├── navigation-retry.ts ← Retry navigation on failure
├── safe-executor.ts ← Safe execution wrapper
├── turnstile-detector.ts ← Cloudflare Turnstile detection
├── types.ts ← Type definitions
├── config/
│ ├── browser-flags.ts ← Chrome launch flags
│ ├── browser-launcher.ts ← Khởi động Chrome với config
│ └── resource-manager.ts ← Quản lý tài nguyên browser
├── page/
│ ├── click-handler.ts ← Click operations
│ ├── navigation-handler.ts ← Navigation operations
│ ├── page-controller.ts ← Page lifecycle management
│ └── search-handler.ts ← Search-specific operations
├── session/
│ └── session-manager.ts ← Quản lý active sessions
└── stealth/
├── stealth-applier.ts ← Apply tất cả stealth techniques
├── navigator-stealth.ts ← Patch navigator properties
├── webrtc-stealth.ts ← Disable WebRTC leak
├── webgl-audio-stealth.ts ← Spoof WebGL và Audio fingerprint
├── timezone-stealth.ts ← Set timezone theo geolocation
├── permissions-stealth.ts ← Override permissions API
├── device-stealth.ts ← Device-specific stealth
├── connection-stealth.ts ← Network connection stealth
├── fetch-stealth.ts ← Patch fetch API
├── mouse-event-stealth.ts ← Mouse event stealth
├── service-worker-stealth.ts ← Service worker stealth
└── light-stealth.ts ← Lightweight stealth cho simple tasks
4.2. Stealth Architecture#
Stealth được áp dụng theo nhiều lớp, mỗi lớp xử lý một khía cạnh khác nhau của browser fingerprinting:Navigator Stealth (navigator-stealth.ts):Xóa navigator.webdriver property.
Patch navigator.plugins để hiển thị danh sách plugins thực.
Override navigator.languages theo geolocation.
Patch navigator.platform theo device type.
webrtc-stealth.ts):Disable WebRTC để tránh IP leak qua STUN servers.
Override RTCPeerConnection để không expose real IP.
webgl-audio-stealth.ts):Spoof WebGL vendor và renderer string.
Add noise vào canvas fingerprint.
Add noise vào AudioContext fingerprint.
timezone-stealth.ts):Set Intl.DateTimeFormat timezone theo geolocation của proxy.
Override Date methods để trả về timezone-aware values.
device-stealth.ts):Set screen resolution theo device type.
Override window.devicePixelRatio.
Patch touch events cho mobile devices.
4.3. Browser Launcher — config/browser-launcher.ts#
browser-launcher.ts chịu trách nhiệm khởi động Chrome với đúng cấu hình:Đọc executablePath từ Puppeteer's installed Chromium.
Apply tất cả Chrome flags từ browser-flags.ts.
Khởi động với puppeteer-extra và stealth plugin.
Sử dụng rebrowser-puppeteer-core để tránh fingerprinting ở level thấp hơn.
--no-sandbox: Bắt buộc trong Docker.
--disable-setuid-sandbox: Bắt buộc trong Docker.
--disable-dev-shm-usage: Tránh lỗi shared memory.
--disable-gpu: Tắt GPU trên server.
--disable-blink-features=AutomationControlled: Ẩn automation flag.
--disable-extensions: Tắt extensions để giảm memory.
--no-first-run: Bỏ qua first-run setup.
4.4. Resource Manager — config/resource-manager.ts#
resource-manager.ts kiểm soát việc sử dụng tài nguyên:Block unnecessary resources (images, fonts, stylesheets) qua request interception.
Monitor memory usage của browser process.
Trigger cleanup khi memory vượt ngưỡng.
4.5. Logger — src/utils/logger/#
logger/
├── index.ts ← Export logger singleton
├── core-logger.ts ← Output streams (console + file)
├── error-categorizer.ts ← Phân loại lỗi tự động
├── formatter.ts ← Format log messages
├── structured-logger.ts ← Structured logging với metrics
└── types.ts ← Log level types
core-logger.ts quản lý output streams:Console stream: Colorized output với chalk.
File stream: JSON format, tự động tạo thư mục theo ngày.
Tự động rotate khi file vượt kích thước giới hạn.
error-categorizer.ts phân loại lỗi dựa trên error message và stack trace:NETWORK_TIMEOUT: Timeout, ETIMEDOUT.
PROXY_ERROR: ECONNREFUSED, proxy-related errors.
CAPTCHA_DETECTED: captcha, challenge keywords.
BOT_DETECTED: cloudflare, bot-detection keywords.
API_ERROR: API, HTTP error keywords.
BROWSER_CRASH: Chrome crash, process exit.
structured-logger.ts thêm metadata vào mỗi log entry:Service name (từ logger.child("service-name")).
4.6. Environment Config — src/utils/env.ts#
env.ts là single source of truth cho tất cả configuration:Đọc từ process.env và apply defaults.
Tính toán derived values (ví dụ: MONGODB_URI từ các DB_ variables).
Phân biệt isLocal (development) và production để apply different defaults.
Export env object được type-safe.
4.7. Middleware#
Error Handler (error.middleware.ts):Bắt tất cả unhandled errors trong Elysia.
Format error response nhất quán: { error, message, statusCode }.
Log error với full context.
Trả về HTTP 500 cho server errors, 400 cho client errors.
ip-validation.middleware.ts):Đọc IP nguồn từ request headers.
Kiểm tra IP có trong IP_ALLOWED list không.
Trả về HTTP 403 nếu IP không được phép.
Bỏ qua validation nếu IP_ALLOWED rỗng.
5. Tầng Config — src/config/#
5.1. Database Config — src/config/database/mongodb.config.ts#
mongodb.config.ts quản lý kết nối MongoDB:Xây dựng connection string từ env.MONGODB_URI.
Cấu hình Mongoose options: serverSelectionTimeoutMS, socketTimeoutMS.
Retry connection với exponential backoff khi thất bại.
Log connection events (connected, disconnected, error).
5.2. Anti-Captcha Config — src/config/anticaptcha.config.ts#
Cấu hình cho Anti-Captcha API:API key, base URL, timeout, retry attempts.
Cooldown periods giữa các lần giải.
Confidence thresholds cho từng loại CAPTCHA.
5.3. Email Config — src/config/email.config.ts#
Credentials từ env variables.
5.4. Security Vendor Emails — src/config/security-vendor-emails.config.ts#
File này chứa danh sách địa chỉ email của tất cả security vendors. Mỗi vendor có thể có nhiều địa chỉ email cho các loại báo cáo khác nhau (malware, phishing, spam, samples).
6. Luồng Dữ Liệu Chi Tiết#
6.1. Luồng Traffic Task — End to End#
Bước 1: Request từ Go APItask-group-api-request-cron (mỗi giây)
→ taskRequestService.requestAndCreateTaskGroups(count)
→ HTTP POST [API_HOST]/api/task/request
→ Nhận danh sách TaskGroup objects
→ taskGroupService.createMultiple(taskGroups)
→ Lưu vào MongoDB với status PENDING
task-group-cron-direct (mỗi giây)
→ cronTaskGroup.start()
→ resourceAllocator.getAllocation(availableTasks)
→ _runNextAvailableTaskByType(type)
→ taskGroupService.getPendingByType(type)
→ processOrchestrator.processTaskGroup(taskGroup)
→ Cập nhật status → PROCESSING
→ Lấy proxy từ proxy_webhook URL
→ Tạo browser session
→ task-action-executor.execute(task, session)
→ Chọn flow phù hợp (ads/search/kill/home)
→ Thực thi flow
→ Chụp screenshot
→ Upload lên DigitalOcean Spaces
→ Gửi webhook về Go API
→ Cập nhật status → COMPLETED
task-group-cleanup-cron (00:30 hàng ngày)
→ taskGroupCleanupService.cleanupPreviousDayTasks()
→ Xóa tasks cũ hơn 24 giờ
6.2. Luồng Report Task — End to End#
Bước 1: Request từ Go APIreport-task-api-request-cron (mỗi giây)
→ reportTaskRequestService.canRequestTasks()
→ Nếu có thể: reportTaskCron.requestTaskFromAPI()
→ HTTP GET [API_HOST]/api/report-tasks/pending
→ Nhận ReportTask object
→ Lưu vào MongoDB với status PENDING
→ reportTaskCron.run() được gọi ngay
reportTaskCron.run()
→ reportTaskService.getPendingTasks(1)
→ executeTask(task)
→ Xác định: isEmailFlow = true
→ _platformExecutor.executeEmailPlatformReport(task)
→ Lấy platform service (ví dụ: GoogleAdsAbuseEmailReportService)
→ platformPromptFactoryService.generateContent(task)
→ chatGPTService.generateContent(prompt, config)
→ Tạo email content từ AI response
→ emailService.send(to, subject, body)
→ Cập nhật status → COMPLETED
→ _callbackSender.sendPendingCallbacks()
reportTaskCron.run()
→ executeTask(task)
→ Xác định: isEmailFlow = false
→ _platformExecutor.generateAIContentForTask(task)
→ _proxyManager.getValidProxyForTask(task)
→ _sessionCreator.createBrowserSession(task, proxy)
→ _platformExecutor.executePlatformReport(session, task, aiData)
→ Lấy platform service (ví dụ: GoogleSafeBrowsingReportService)
→ navigateToReportPage()
→ fillForm(aiData)
→ handleCaptcha() nếu cần
→ submitForm()
→ captureEvidence()
→ Upload screenshot
→ Cập nhật status → COMPLETED
→ browserManager.endSession(session)
6.3. Luồng Proxy — End to End#
Bước 1: Nhận Proxy Requestproxy-cron-webhook-direct (mỗi giây)
→ proxyServices.getCompleted()
→ Nếu có proxy COMPLETED:
→ callbackWebhook(proxy.webhook_url, proxy)
→ Go API nhận proxy info
→ proxyServices.delete(proxy._id)
proxy-cron-direct (mỗi giây)
→ proxyServices.getPending()
→ Nếu có proxy PENDING:
→ rotateProxy(proxy) → gọi proxy.rotate_url
→ Parse response (nhiều format)
→ Cập nhật proxy.ip, proxy.port
→ _performIPCheck(proxy) → kiểm tra IP public
→ Cập nhật proxy.ip_public
→ proxyServices.update(proxy) với status COMPLETED
7. Database Schema#
7.1. Collection: task_groups#
7.2. Collection: tasks (embedded trong task_groups)#
7.3. Collection: report_tasks#
7.4. Collection: proxies#
8. Cron Job Architecture#
8.1. Tám Cron Jobs#
| Tên | Pattern | Class/Function | Mục đích |
|---|
task-group-cron-direct | EVERY_SECOND | cronTaskGroup.start() | Thực thi traffic tasks |
task-group-api-request-cron | EVERY_SECOND | cronTaskGroup.requestTasksFromAPI() | Lấy tasks từ Go API |
proxy-cron-direct | EVERY_SECOND | cronProxy.start() | Rotate và kiểm tra proxy |
proxy-cron-webhook-direct | EVERY_SECOND | cronProxy.runWebhook() | Callback proxy về Go API |
task-group-cleanup-cron | 30 0 * * * | taskGroupCleanupService.cleanupPreviousDayTasks() | Xóa tasks cũ |
report-task-api-request-cron | EVERY_SECOND | reportTaskCron.requestTaskFromAPI() | Lấy report tasks |
search-cron | Theo config | searchCron | Quét thứ hạng từ khóa |
webhook-search-cron | Theo config | webhookSearchCron | Gửi kết quả search về API |
8.2. Protect Flag#
Tất cả cron jobs đều có protect: true. Đây là tính năng của @elysiajs/cron:Khi một lần chạy của cron chưa hoàn thành, lần chạy tiếp theo sẽ bị skip.
Tránh tình trạng nhiều instances của cùng một cron chạy đồng thời.
Đặc biệt quan trọng với task-group-cron-direct vì mỗi lần chạy có thể mất vài phút.
8.3. Resource Allocator#
resource-allocator.ts tính toán số slots cho mỗi loại task dựa trên:Tổng availableSlots = maxProcess - totalProcessRunning.
Số tasks khả dụng cho từng loại.
Tỷ lệ cấu hình: KILL_TRAFFIC_RATIO, HOME_TRAFFIC_RATIO.
8.4. Link Tracker#
link-tracker.ts theo dõi các links đang được xử lý để tránh duplicate:Khi một home traffic task bắt đầu, link được đánh dấu là "processing".
HOME_TRAFFIC_PER_TARGET_LIMIT giới hạn số tasks đồng thời cho cùng một link.
Khi task hoàn thành, link được unmark.
Tránh tình trạng nhiều phiên Chrome cùng truy cập một URL cùng lúc.
9. Giao Tiếp Với Go API Backend#
| Endpoint | Method | Mục đích |
|---|
/api/task/request | POST | Lấy traffic tasks mới |
/api/report-tasks/pending | GET | Lấy report tasks mới |
/api/reports/sites/{platform}/config | GET | Lấy prompt config cho platform |
/webhook/task/update-status | POST | Gửi kết quả traffic task |
/webhook/report-task/callback | POST | Gửi kết quả report task |
Tất cả requests đều có header X-API-Key: {API_KEY}.| Endpoint | Method | Mục đích |
|---|
POST /api/task-traffics/multiple | POST | Tạo traffic tasks trực tiếp |
POST /api/report-tasks/create | POST | Tạo report tasks trực tiếp |
GET / | GET | Kiểm tra trạng thái worker |
GET /health | GET | Health check |
GET /logs | GET | Đọc log files |
Tất cả inbound requests được kiểm tra IP qua ipValidationMiddleware.9.3. Proxy Webhook Flow#
Đây là cơ chế đặc biệt để Go API cấp phát proxy cho từng task:Mỗi task group có proxy_webhook URL.
Khi task cần proxy, Tools V2 gọi URL này.
Go API nhận request, chọn proxy phù hợp, tạo proxy record trong MongoDB của Tools V2 qua POST /api/proxy/create.
Proxy record có status PENDING.
proxy-cron-direct rotate proxy và cập nhật status COMPLETED.
proxy-cron-webhook-direct gọi webhook_url để thông báo proxy sẵn sàng.
Go API nhận callback và biết proxy đã sẵn sàng để dùng.
10. Dependency Graph#
10.1. Module Dependencies#
src/index.ts
├── src/api/index.ts
│ ├── task-group.controller.ts
│ │ ├── task-group.service.ts → task-group.model.ts
│ │ └── task-group.cron.ts
│ │ ├── resource-allocator.ts
│ │ ├── link-tracker.ts
│ │ ├── process/process-orchestrator.ts
│ │ │ └── task-action/task-action-executor.ts
│ │ │ ├── flows/ads-flow/
│ │ │ ├── flows/coccoc-flow/
│ │ │ ├── flows/home-traffic-flow/
│ │ │ └── flows/kill-flow/
│ │ └── services/api/task-request.service.ts
│ ├── report-tasks.controller.ts
│ │ └── report-task.cron.ts
│ │ ├── cron/platform/platform-executor.ts
│ │ │ └── services/report-tasks/platforms/*
│ │ ├── cron/session/session-creator.ts
│ │ │ └── services/browser/enhanced-browser-session.service.ts
│ │ └── cron/proxy/proxy-manager.ts
│ └── proxy.controller.ts
│ └── proxy.cron.ts
│ └── services/check-proxy/
└── utils/browser_manager/index.ts
├── config/browser-launcher.ts
├── stealth/stealth-applier.ts
└── session/session-manager.ts
10.2. Service Dependencies#
services/ai/chatgpt.service.ts
└── services/ai/api/openai-client.ts
services/browser/enhanced-browser-session.service.ts
├── utils/browser_manager/
├── services/profiles/profile-manager.service.ts
└── services/captcha/browser-captcha.service.ts
services/report-tasks/platforms/*.service.ts
├── services/ai/platform-prompt-factory.service.ts
├── services/browser/enhanced-browser-session.service.ts
├── services/email/email.service.ts
└── services/screenshot/screenshot.service.ts
services/screenshot/screenshot.service.ts
← DigitalOcean Spaces SDK
← Cloudinary SDK
← Local filesystem (fallback)
11. Xử Lý Lỗi Và Resilience#
11.1. Error Boundaries#
Mỗi cron job được wrap trong try-catch:Lỗi trong một cron không làm crash toàn bộ application.11.2. Task Recovery#
Khi cronTaskGroup.start() chạy, nó luôn gọi _recoverStuckTasks() trước:Tìm tất cả tasks có status PROCESSING và updatedAt cũ hơn 20 phút.
Log số lượng tasks được recover.
11.3. Proxy Resilience#
Proxy cron có nhiều lớp resilience:Nếu rotation thất bại, proxy vẫn được đánh dấu COMPLETED để task có thể dùng IP hiện tại.
Sau PROXY_RETRY_LIMIT lần thất bại, proxy bị xóa.
Webhook được retry tối đa 3 lần trước khi proxy bị xóa.
11.4. Browser Session Cleanup#
Browser sessions được cleanup trong finally blocks:Đảm bảo counter luôn được decrement dù task thành công hay thất bại.11.5. Memory Management#
TaskGroupMemoryManager kiểm tra memory trước khi spawn browser mới:Nếu memory usage vượt ngưỡng, chờ cho đến khi memory giảm.
Tránh OOM killer kill Chrome processes.
browserManager.cleanupOldSessions(5 * 60 * 1000) được gọi định kỳ:Tìm browser sessions idle quá 5 phút.
Đóng và giải phóng tài nguyên.
12. Kiến Trúc Stealth Chi Tiết#
12.1. Tại Sao Cần Nhiều Lớp Stealth#
Các hệ thống phát hiện bot hiện đại như Google reCAPTCHA Enterprise, Cloudflare Bot Management, và DataDome sử dụng hàng chục tín hiệu để phân biệt bot với người dùng thật. Không có một kỹ thuật đơn lẻ nào đủ để vượt qua tất cả. Tools V2 áp dụng defense-in-depth: nhiều lớp stealth độc lập, mỗi lớp xử lý một nhóm tín hiệu khác nhau.Plugin puppeteer-extra-plugin-stealth là lớp đầu tiên và cơ bản nhất. Nó patch nhiều thuộc tính của browser ngay khi page được tạo:Xóa navigator.webdriver — đây là dấu hiệu rõ ràng nhất của automation.
Patch window.chrome để trông giống Chrome thật.
Override navigator.permissions để tránh permission prompts bất thường.
Patch navigator.plugins với danh sách plugins thực.
Override window.outerWidth và window.outerHeight.
12.3. Lớp 2 — Rebrowser Puppeteer Core#
rebrowser-puppeteer-core là fork của Puppeteer được patch ở level thấp hơn:Patch CDP (Chrome DevTools Protocol) messages để ẩn automation signatures.
Override các internal Chrome APIs mà Puppeteer dùng để control browser.
Tránh các fingerprinting techniques mới nhất của Google.
12.4. Lớp 3 — Custom Stealth Injections#
Các file trong stealth/ inject JavaScript vào mỗi page mới:navigator-stealth.ts: Patch navigator.webdriver, navigator.languages, navigator.platform.
webrtc-stealth.ts: Override RTCPeerConnection để không expose real IP.
webgl-audio-stealth.ts: Add noise vào canvas và WebGL fingerprint.
timezone-stealth.ts: Set timezone theo proxy geolocation.
permissions-stealth.ts: Override permissions API.
fetch-stealth.ts: Patch fetch để thêm realistic headers.
mouse-event-stealth.ts: Patch mouse events để trông tự nhiên hơn.
service-worker-stealth.ts: Kiểm soát service worker behavior.
12.5. Lớp 4 — Advanced Stealth#
advanced-stealth.ts xử lý các kỹ thuật phức tạp hơn:Screen randomization: Thêm noise nhỏ vào screen dimensions.
Hardware concurrency spoofing: Override navigator.hardwareConcurrency.
Memory spoofing: Override navigator.deviceMemory.
Battery API spoofing: Fake battery status.
Connection type spoofing: Override navigator.connection.
12.6. Lớp 5 — Behavioral Stealth#
Đây là lớp khó nhất để implement nhưng cũng quan trọng nhất:Ghost cursor tạo chuyển động chuột tự nhiên với đường cong Bezier.
Typing simulation với random delays và occasional typos.
Scroll behavior với easing functions và natural pauses.
Reading time calculation dựa trên word count.
Random micro-pauses giữa các actions.
13. Kiến Trúc AI Content Generation#
13.1. Luồng Tạo Nội Dung#
Khi cần tạo nội dung báo cáo cho một platform:ReportTaskCron.executeTask(task)
→ _platformExecutor.generateAIContentForTask(task)
→ platformPromptFactoryService.getGenerator(task.platform)
→ generator.generate(task)
→ reportSitePromptService.getConfig(platform)
→ HTTP GET [API_HOST]/api/reports/sites/{platform}/config
→ Cache 1 giờ
→ chatGPTService.generateContent(prompt, gptConfig)
→ openai-client.ts
→ OpenAI API call
→ response-parser.ts parse response
→ json-fixer.ts nếu JSON malformed
→ Validate response theo response_config
→ Return structured content
platform-prompt-factory.service.ts implement Factory pattern:Nhận platform name (ví dụ: GOOGLE_SAFE_BROWSING).
Tìm generator tương ứng trong platform-prompt-factory/generators/.
Nếu không có generator riêng, dùng generic-report-generator.ts.
Return generator instance.
Xây dựng prompt phù hợp với platform.
Map response fields vào form fields của platform.
13.3. Fallback Mechanism#
Khi Go API không khả dụng:reportSitePromptService trả về null.
Generator fallback về prompt trong platform-prompt/fallback-generators/.
Fallback prompts được hardcode trong code, không cần API.
Log cảnh báo khi dùng fallback.
13.4. Cost Tracking#
cost-calculator.ts theo dõi chi phí OpenAI:Đếm input tokens và output tokens cho mỗi call.
Tính chi phí dựa trên pricing của model.
chatGPTService.displayCostSummary() được gọi sau mỗi task để log tổng chi phí.
14. Kiến Trúc Email Reporting#
14.1. SMTP Configuration#
email.service.ts sử dụng Nodemailer với SMTP:Kết nối SMTP khi khởi động, reuse connection.
Hỗ trợ STARTTLS (port 587) và SSL (port 465).
Retry với exponential backoff khi gửi thất bại.
14.2. Email Content Generation#
Với email-based platforms, AI tạo:subject: Tiêu đề email phù hợp với platform.
body: Nội dung email với đầy đủ thông tin về domain vi phạm.
attachments: Danh sách file đính kèm (nếu có).
Google Ads Abuse: Email mô tả vi phạm chính sách quảng cáo.
Kaspersky: Email với malware sample information.
OpenPhish: Email với phishing URL và evidence.
14.3. Multi-Recipient Support#
Một số platforms có nhiều địa chỉ email (ví dụ: Kaspersky có email cho virus, spam, samples). security-vendor-emails.config.ts lưu tất cả địa chỉ này. Email service gửi đến tất cả địa chỉ liên quan.
15. Kiến Trúc Phân Tán#
15.1. Stateless Workers#
Mỗi Tools V2 instance là stateless về mặt business logic:Không có shared state giữa các instances.
Mỗi instance có MongoDB riêng để lưu local state.
Go API là single source of truth cho business data.
15.2. Worker Registration#
Mỗi worker tự đăng ký với Go API qua SERVER_ID:SERVER_ID là định danh duy nhất của worker (thường là IP của server).
Go API dùng SERVER_ID để tracking worker health.
Monitor cron định kỳ ping Go API để cập nhật last-seen.
15.3. Task Distribution#
Go API phân phối tasks dựa trên:Worker health (last-seen timestamp).
Worker capacity (số tasks đang chạy so với limit).
Worker location (geolocation matching với task requirements).
15.4. Failure Isolation#
Go API phát hiện qua health check timeout.
Tasks của worker đó không được phân phối thêm.
Tasks đang pending được giữ lại và phân phối cho workers khác.
Khi worker restart, nó tự đăng ký lại và nhận tasks mới.
16. Tóm Tắt Kiến Trúc#
16.1. Điểm Mạnh Của Kiến Trúc#
Phân tầng rõ ràng: API layer, Service layer, Utils layer không phụ thuộc chéo.
Modular: Mỗi module độc lập, có thể thay thế hoặc mở rộng mà không ảnh hưởng module khác.
Resilient: Nhiều lớp error handling, crash recovery, retry logic.
Observable: Logging chi tiết ở mọi tầng, endpoints giám sát.
Scalable: Horizontal scaling bằng cách thêm instances, không cần thay đổi code.
16.2. Trade-offs Đã Chấp Nhận#
Không có Zod validation cho env variables: Đổi lấy flexibility, nhưng lỗi cấu hình có thể xuất hiện muộn hơn.
MongoDB nội bộ thay vì shared state: Đổi lấy independence, nhưng cần sync với Go API.
Polling thay vì push: Đổi lấy simplicity, nhưng có latency 1 giây.
Single report task tại một thời điểm: Đổi lấy stability, nhưng throughput thấp hơn.
16.3. Các Quyết Định Thiết Kế Quan Trọng#
Dùng Bun thay vì Node.js: Hiệu năng cao hơn, TypeScript native, quan trọng cho workload nặng.
Dùng Elysia thay vì Express: Lightweight, TypeScript-first, cron tích hợp.
Dùng Typegoose thay vì raw Mongoose: Type safety cho MongoDB models.
Dùng protect: true cho tất cả crons: Tránh overlap, đảm bảo predictable behavior.
Staggered browser launch (3 giây): Tránh CPU spike, quan trọng cho server stability.
Proxy webhook pattern: Cho phép Go API kiểm soát proxy allocation mà không cần Tools V2 biết về proxy pool.
Modified at 2026-03-27 01:49:14
