Go API Backend — Tổng Quan

Go API Backend là trung tâm điều phối của toàn hệ thống Traffic Tools V2. Đây là thành phần duy nhất có quyền truy cập trực tiếp vào cơ sở dữ liệu. Mọi yêu cầu từ Admin Dashboard, mọi kết quả từ Worker đều đi qua đây.

Xây dựng bằng Go + Fiber v2, chạy trên cổng 33003. Giao tiếp với 3 đối tượng: Admin Dashboard (REST API có xác thực JWT), Tools V2 Worker (phân phối task và nhận kết quả qua webhook), và các cơ sở dữ liệu (MySQL, MongoDB, Redis).

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

Xác thực và phân quyền — JWT + Device Token 2 lớp, 2FA TOTP qua Google Authenticator, phân quyền Admin/User.

Phân phối tác vụ — Cron job mỗi phút giao task đến worker đang online. Worker polling API mỗi giây để nhận task mới.

Nhận kết quả qua webhook — Worker gửi kết quả về qua các endpoint /webhook/* (luôn public, không cần JWT).

15+ cron job tự động — Phân phối task, reset task bị kẹt, quét thứ hạng từ khóa, kiểm tra sức khỏe proxy, báo cáo định kỳ...

36 module nghiệp vụ — Mỗi module quản lý một domain: user, campaign, proxy, keyword, profile, report...

Background services — HealthCheckCron (ping worker định kỳ) và TaskMonitor (phát hiện và reset task bị kẹt).

Thông báo — Telegram (3 kênh: chung, báo cáo, lỗi nghiêm trọng) và Mattermost (báo cáo hàng ngày lúc 9:00).

Bussiness | Logic

Tài liệu nghiệp vụ mô tả các tính năng mà API Backend phục vụ — từ góc nhìn người vận hành, không có code.

1. Thống kê hàng ngày — API tổng hợp dữ liệu traffic theo giờ từ MySQL + MongoDB, trả về cấu trúc lồng nhau theo ngày → loại traffic → từ khóa → 24 giờ. Có cơ chế deduplication ở cả frontend và backend để tránh query nặng trùng lặp.

2. Thống kê hệ thống — API phân loại chiến dịch theo flag only_ads và is_kill. Ba endpoint riêng cho 3 tab: Click Ads, Negative SEO, Traffic Tự Nhiên. Dùng Go Map thay vì SQL JOIN để tránh row explosion.

3. Tìm kiếm tự động — API tạo task tìm kiếm cho mọi tổ hợp engine × device × deviceOS. Confirm Fire kết nối MongoDB (keyword) sang MySQL (project). Cron job quét lại mỗi 30 phút.

4. Trung tâm Báo cáo — API quản lý report_sites (cấu hình AI prompt, GPT config, form schema), report_domains (soft delete), report_tasks (PENDING → IN_PROGRESS → COMPLETED/FAILED). Webhook nhận callback từ Worker sau mỗi lần gửi báo cáo.

5. Quản lý tài khoản — CRUD user, bcrypt password, TOTP 2FA, Device Token per-login, session timeout qua Redis, activity log ghi lại mọi hành động.

6. Quản lý Hệ thống — API quản lý server worker (MySQL), proxy pool (MongoDB với array domain_used/domain_blocks), xoay IP tự động qua webhook, import song song từ nhiều nhà cung cấp, backup proxy health check.

7. Quản lý tài khoản Google — API quản lý Browser Profile (MongoDB), chọn profile ngẫu nhiên cho task với giới hạn 5 báo cáo/ngày/server, ghi nhận đăng nhập thất bại (3 lần → vô hiệu hóa), dọn dẹp session hết hạn.

Architecture

Tài liệu kỹ thuật cho developer làm việc với Go API Backend.

Database Schema — Schema đầy đủ của MySQL (users, campaigns, servers, proxies, keywords...), MongoDB collections (tasks, profiles, keyword_results, evidences...) và Redis key patterns.

System Architecture — Kiến trúc phân lớp (Handler → Service → Repository), middleware chain (Recover → CORS → Helmet → Timeout → Auth → JWT), dependency injection với go.uber.org/dig, background services (HealthCheckCron + TaskMonitor), luồng dữ liệu chi tiết.

Code Structure — Cây thư mục đầy đủ: cmd/, bootstrap/, internal/ (36 modules), pkg/ (shared packages). Pattern tổ chức module 4 lớp nhất quán. Channel-based logging theo từng module.

Environment & Configuration — Danh sách đầy đủ biến môi trường: database connections, JWT secret, webhook URLs, cron schedules, Telegram tokens, proxy provider credentials.

Logs and Monitoring — Hệ thống log theo channel (mỗi module một thư mục riêng), cách đọc log từ xa, Telegram alerts, Mattermost reports, HealthCheckCron và TaskMonitor.

Deployment

Local — Chạy API trên máy local với air -c .air.toml (hot-reload), database trong Docker. Cấu hình env với localhost + cổng ánh xạ ra ngoài (33022, 33021, 33023).

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.

Production — Mô hình 2 giai đoạn: build Go binary trên Bastion Server → push image lên AWS ECR → pull và deploy trên EC2. Rollback bằng cách đổi tag image, hoàn thành trong ~5 giây.

API Interface

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

🔑 Identity & Session — Đăng nhập, đăng ký, lấy profile, thiết lập 2FA, xác thực OTP, quản lý user (CRUD, đổi mật khẩu), cấu hình Telegram notification.

Đăng nhập hệ thống — Xác thực email và mật khẩu. Nếu tài khoản có bật 2FA, hệ thống trả về yêu cầu xác thực OTP bước 2.

Khởi tạo bảo mật 2FA — Sinh khóa bí mật dùng cho Google Authenticator.

Xác thực mã OTP — Kiểm tra mã 6 số để hoàn tất đăng nhập hoặc thiết lập 2FA.

📁 Campaign Management — CRUD chiến dịch, bật/tắt hàng loạt, lấy dữ liệu Negative SEO.

Danh sách Chiến dịch — Lấy danh sách chiến dịch, hỗ trợ tìm kiếm, phân trang và lọc theo trạng thái.

Tắt/Mở Chiến dịch hàng loạt — Cập nhật trạng thái nhiều chiến dịch cùng lúc.

Dữ liệu Negative SEO — Thống kê hiệu quả rớt hạng SEO của đối thủ.

⚙️ Project Mechanics — CRUD project, cập nhật kịch bản chạy (loại traffic, device, thời gian onsite), chỉnh sửa hàng loạt.

Khởi tạo Kịch bản Mô phỏng — Tạo cài đặt quy định cách Worker phải chạy (truy cập trực tiếp hay tìm kiếm, click quảng cáo hay bỏ qua).

Chỉnh sửa Hàng loạt (Bulk) — Thay đổi cùng lúc Device, OS, hoặc Loại Traffic cho hàng trăm Project.

👤 Profile Management — CRUD Browser Profile, bulk import, mở khóa captcha/blocked, tra cứu profile khả dụng, báo cáo sức khỏe kho tài khoản.

Nhập kho Tài khoản Email (Bulk Import) — Nhận danh sách account định dạng account|password|recovery_email để đăng nhập giả lập số lượng lớn.

Tra cứu Kho Profile Khả dụng — Trả về các profile đã xả xong cooldown và không bị khóa. Dùng cho Node tự động điều phối.

Báo cáo Sức khỏe Kho Tài Khoản — Tính toán Tỉ lệ sống (Survival Rate), số lượng Click đã tạo.

🦾 Worker Interface — Handshake đăng ký node, heartbeat ping định kỳ, nhận cấu hình bypass, kéo nhiệm vụ traffic SEO, báo cáo sự cố crash.

Đăng ký Khởi tạo Node (Handshake) — Worker gọi khi chạy lần đầu. Cung cấp API_KEY và thông số máy. Hệ thống cấp worker_id và JWT Access Token 24h.

Nhịp Tim Khảo Sát Tình Trạng (Heartbeat) — Worker ping định kỳ để báo cáo health. Mất ping quá 3 phút → Admin Dashboard cảnh báo Node chết.

Kéo (PULL) Nhiệm vụ Traffic SEO — Worker kéo danh sách tác vụ kèm Proxy, Profile để thực hiện thao tác SEO.

📊 Report: Execution — Worker kéo công việc báo cáo, giám sát nhiệm vụ, bắn lại báo cáo thất bại.

Kéo Công việc Báo cáo (Worker Pull) — API độc quyền cho Report Worker. Hệ thống nhả Prompt và Metadata của nền tảng đích.

Bắn Lại Báo Cáo Thất Bại — Admin kích hoạt chạy lại Report đã FAILED do Form Timeout hoặc Proxy chết.

📊 Report: Discovery — Quản lý domain pool chờ xử lý, nhập mục tiêu thủ công, kích hoạt scanner tự động, duyệt yêu cầu để chuyển sang Execution.

Danh sách Tên miền Chờ Xử Lý — Lấy danh sách domain đang bị nghi ngờ vi phạm, lọc theo Keyword, Status và Loại.

Kích hoạt Heuristic Scanner — Gửi chỉ thị cho Worker cào Google SERPs tìm URL lừa đảo tự động đẩy vào Discovery Pool.

Duyệt Yêu Cầu (Approve to Execution) — Chốt chặn xác thực cuối cùng. Domain chuyển từ pending sang ready để phân bổ cho luồng Execution.

📊 Report: Platforms Configuration — CRUD nền tảng báo cáo, bật/tắt theo loại, cập nhật AI prompt và GPT config, cấu hình schema biểu mẫu.

Truy vấn Danh sách Nền tảng Đối tác — Lấy cấu hình hoạt động cho hơn 30 vendors (Spamhaus, Microsoft...), bao gồm BROWSER_BASED và EMAIL_BASED.

📊 Report: Email Automation — Quản lý SMTP server, nhật ký gửi mail, phân tích tỉ lệ chuyển đổi.

Danh sách SMTP/Mailer Server — Lấy danh sách tài khoản SMTP đang hoạt động dùng để bắn Email-Based Report.

Nhật ký Nhiệm vụ Gửi Mail — Trace trạng thái từng Message: Pending, Delivered, Bounced, Spam_Detected.

🌐 Global Proxies — CRUD proxy pool, bulk import, cập nhật thông tin, xoay vòng IP cưỡng bức.

Danh sách Kho Proxy — Lấy danh sách IP hiện có, hỗ trợ tìm kiếm theo IP, khu vực và thống kê số lỗi kết nối.

Kích hoạt Xoay vòng (Rotate IP) Cưỡng bức — Ping API nhà cung cấp để ép reset IP mới thay vì chờ vòng lặp định kỳ. Hữu hiệu để vượt Cloudflare Block.

📈 System Intelligence — Báo cáo luồng bảo mật hợp nhất, bản đồ lưu lượng GeoIP heatmap.

Báo cáo Luồng Bảo mật Hợp nhất — Phân tích số liệu lớn: Total Dead Ads, Brand Tracking, Survival Profile Rates.

Bản Đồ Lưu Lượng GeoIP (Heatmap) — Dữ liệu Heatmap mật độ Click/View theo múi giờ và tỉnh thành. Dùng vẽ bản đồ ECharts.

🪝 Webhook Integrations — Callback hoàn tất gói lưu lượng SEO, callback hoàn tất bắn Report AI.

Callback Hoàn tất Gói Lưu lượng SEO — Hứng HTTP POST từ máy chủ Node sau khi đã Onsite đủ Time On Page.

Callback Thông báo Hoàn tất Bắn Report AI — Nhận kết quả cuối (Success/Fail) kèm Screenshot bằng chứng submit từ Worker.

Tổng quan

Go API Backend — Tổng Quan#

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

Bussiness | Logic#

Architecture#