1. Hướng dẫn sử dụng
Traffic Tool
  • Traffic Tool Docs
    • Tổng Quan
    • project
      • admin
        • Hướng dẫn sử dung
          • Đăng Nhập & Xác Thực Hai Bước
          • Thống Kê Hệ Thống
          • Thống Kê Hàng Ngày
          • Tìm Kiếm Tự Động
          • Trung Tâm Báo Cáo
          • Quản Lý Tài Khoản
          • Quản Lý Server
          • Quản Lý Proxy
          • Quản Lý Gói Proxy
          • Quản Lý Nhà Cung Cấp Proxy
          • Quản Lý Backup Proxy
          • Quản Lý Tài Khoản Google
      • api + tool
        • Hướng dẫn sử dụng
          • User Guide
          • Setup Guide
        • Bussiness | Logic
          • 1. Thống kê hàng ngày (Daily Statistics)
          • 2. Thống kê hệ thống (System Statistics)
          • 3. Tìm kiếm tự động (Automated Discovery)
          • 4. Trung tâm Báo cáo (Report Center)
          • 5. Quản lý tài khoản (Account Management)
          • 6. Quản lý Hệ thống (System Management)
          • 7. Quản lý tài khoản Google (Google Account Management)
        • Architecture
          • Database Schema
          • System Architecture
          • Code Structure
          • Logs and Monitoring
          • Environment & Configuration
        • Deployment
          • Local
          • Staging
          • Product
  • Traffic Backend API
    • 🔑 Identity & Session
      • Đăng nhập hệ thống (Login)
      • Đăng ký tài khoản mới (Public)
      • Lấy danh sách người dùng (Phân trang)
      • Admin tạo người dùng mới
      • Lấy thông tin cá nhân hiện tại
      • Khởi tạo bảo mật 2FA
      • Xác thực mã OTP
      • Chi tiết người dùng theo ID
      • Cập nhật thông tin người dùng
      • Xóa tài khoản người dùng
      • Đổi mật khẩu
      • Kiểm tra Cấu hình Thông báo Telegram Toàn hệ thống
      • Bật/Tắt Thông báo Telegram Toàn cục
    • 📁 Campaign Management
      • Danh sách Chiến dịch Toàn cầu
      • Khởi tạo Chiến dịch Mới
      • Chi tiết Chiến dịch
      • Cập nhật Chiến dịch
      • Xóa Chiến dịch
      • Tắt/Mở Chiến dịch (Hàng loạt)
      • Dữ liệu Hình mẫu SEO (Negative SEO)
    • ⚙️ Project Mechanics
      • Danh sách Dự án (Projects List)
      • Khởi tạo Kịch bản Mô phỏng
      • Lấy chi tiết cấu hình Dự án
      • Cập nhật Kịch bản chạy
      • Xóa Dự án
      • Chỉnh sửa Hàng loạt (Bulk)
      • Bật/Tắt Dự án
    • 👤 Profile Management
      • Danh sách Vân tay số (Profiles Data)
      • Tạo Hồ sơ Đơn lẻ (Tạo Vân tay mới)
      • Nhập kho Tài khoản Email (Bulk Import)
      • Chi tiết Session/Cookies
      • Chỉnh sửa Hồ sơ/Ghi chú
      • Xóa Vân tay số và Dữ liệu Local
      • Mở khóa Captcha/Trạng thái Blocked
      • Tra cứu Kho Profile Khả dụng
      • Báo cáo Sức khỏe Kho Tài Khoản
    • 🦾 Worker Interface
      • Đăng ký Khởi tạo Node (Handshake)
      • Nhịp Tim Khảo Sát Tình Trạng (Heartbeat)
      • Nhận Cấu hình Bypass & Hệ thống
      • Kéo (PULL) Nhiệm vụ Traffic SEO
      • Báo cáo Sự cố Node (Crash Report)
    • 📊 Report: Execution
      • Kéo Công việc Báo cáo (Worker Pull)
      • Quản lý Giám sát Nhiệm vụ (Task Dashboard)
      • Bắn Lại Báo Cáo Thất Bại (Manual Retry)
    • 📊 Report: Discovery
      • Danh sách Tên miền Chờ Xử Lý (Discovery Pool)
      • Nhập Mục Tiêu Thủ Công (Manual Insert)
      • Kích hoạt Heuristic Scanner (Cào tự động)
      • Chi tiết Bằng Chứng (Evidence Data)
      • Dán nhãn Vi Phạm / Cập nhật Screenshot
      • Loại Bỏ Mục Tiêu
      • Duyệt Yêu Cầu (Approve to Execution)
    • 📊 Report: Platforms Configuration
      • Truy vấn Danh sách Nền tảng Đối tác (Vendor)
      • Tạo Nền tảng Vendor Báo cáo Mới
      • Bật/Tắt Trang báo cáo theo Loại
      • Cập nhật Metadata Trang
      • Xóa Trang Báo Cáo
      • Lấy Cài đặt LLM cho Vendor cụ thể
      • Cập nhật Cài đặt Tạo mẫu LLM
      • Lấy Cấu hình Schema Biểu mẫu cho Vendor
      • Cập nhật Yêu cầu Trường Biểu mẫu
    • 📊 Report: Email Automation
      • Danh sách SMTP/Mailer Server
      • Thêm kết nối SMTP Mới
      • Nhật ký Nhiệm vụ Gửi Mail (Email Log)
      • Phân tích Tỉ lệ Chuyển đổi (Email Delivery Analytics)
    • 🌐 Global Proxies
      • Danh sách Kho Proxy Phân trang (Proxy Pool)
      • Thêm mới Tuyến IP (Bulk Import)
      • Cập nhật Thông tin máy chủ Proxy
      • Xóa Proxy (Thu hồi tài nguyên)
      • Kích hoạt Xoay vòng (Rotate IP) Cưỡng bức
    • 📈 System Intelligence
      • Báo cáo Luồng Bảo mật Hợp nhất (Colossal Report)
      • Bản Đồ Lưu Lượng GeoIP (Heatmap)
    • 🪝 Webhook Integrations
      • Callback Hoàn tất Gói Lưu lượng SEO (Traffic Node)
      • Callback Thông báo Hoàn tất Bắn Report AI
    • Schemas
      • AppError
      • LoginRequest
      • UserResponseDto
      • UserModel
      • CreateUserRequest
      • UpdateUserRequest
      • PagingInfo
      • ProfileModel
      • CreateProfileRequest
      • BulkImportProfileReq
      • UpdateProfileRequest
      • CampaignModel
      • CampaignConfigs
      • CreateCampaignRequest
      • UpdateCampaignRequest
      • BulkUpdateCampaignStatusReq
      • NegativeSeoData
      • CreateProjectRequest
      • UpdateProjectRequest
      • ProjectModel
      • BulkUpdateProjectRequest
      • ProjectAttribute
      • WorkerHandshakeRequest
      • WorkerHandshakeResponse
      • WorkerHeartbeatPayload
      • WorkerGlobalSettings
      • TaskPullRequest
      • WorkerFatalLog
      • TaskModel
      • TaskTrafficType
      • TaskUpdateDto
      • ReportTaskModel
      • ReportTaskResult
      • PCReportResponse
      • SummaryStats
      • DailyStats
      • BrandStats
      • ProfileStats
      • ReportTaskItem
      • ReportSiteItem
      • CreateReportSiteRequest
      • GPTConfig
      • ResponseConfig
      • FieldConfig
      • ReportDomainsResponse
      • ReportDomainItem
      • AddReportDomainRequest
      • UpdateReportDomainRequest
      • BulkUpdateDashboardRequest
      • ProxyModel
      • CreateProxyRequest
      • UpdateProxyRequest
      • SMTPServerConfig
      • EmailTaskLog
      • GeoLocation
  • Traffic Tools V2 API
    • Tasks
      • Lọc và Truy vấn Nhật ký Phiên Duyệt lẻ
      • Get all tasks
      • Nạp Kết Quả Chạy của Puppeteer (Update Callback)
      • Xóa toàn bộ Tasks lẻ
      • Get all tasks
      • Xóa một Task (ID)
    • Group task
      • Đẩy nhóm công việc Traffic theo lô (Batch Pipeline Task Creation)
      • Lấy sơ đồ trạng thái hàng đợi Group Tasks
      • Endpoint /api/task-traffics/
      • Clear/Flush Hàng đợi Group Task (Kill Queue)
      • Endpoint /api/task-traffics/
      • Xóa 1 nhóm nhiệm vụ (Theo ObjectID Mongoose)
      • Parse chuỗi Proxy
    • Test
      • Kiểm tra Proxy hoạt động ngầm
      • Endpoint /api/test
      • Kho Fingerprint Thử Nghiệm
      • Endpoint /api/test/account-stats
      • Endpoint /api/test/session-recommendation
      • Endpoint /api/test/check-browser
      • Endpoint /api/test/clear-browser-sessions
    • Proxies
      • Lấy kho Proxy server
      • Khai báo Pool Tuyến Proxy mới
      • Get all proxies
      • Get all proxies
      • Xóa toàn bộ Proxy
      • Get all proxies
      • Xóa Proxy theo ID
      • Reset lại số đếm tiến trình (Cron Proxy Thread)
    • Report Platforms
      • Submit report to multiple platforms
      • Submit report to specific platform
      • Get available platforms
      • Get platform statistics
      • Health check
    • Reports
      • Create a new report
      • Create a new report
      • Get report by ID
      • Get report by ID
      • Get report statistics
      • Get report groups
      • Get report groups
      • Get report group
      • Add report to group
      • Bulk add reports to group
      • Get report group statistics
      • Get analytics data
      • Get platform success rates
      • Get reports by platform
      • Get reports by group
      • Create test reports in bulk
    • Test Report
      • Test Microsoft report submission
      • Test AdGuard report submission
      • Test Google Ads report submission
      • Test Spamhaus report submission
      • Test ESET report submission
      • Test multi-platform report submission
      • Get available platforms
    • ESET Test
      • Simple test
      • Minimal POST test
      • Generate ESET report content
      • Get sample test data
      • Test form filling
      • Test full form submission
    • Spamhaus Test
      • Simple test
      • Minimal POST test
      • Generate Spamhaus report content
      • Get sample test data
      • Test Spamhaus form filling
      • Test full Spamhaus form submission
    • Report Scheduler
      • Get report scheduler statistics
      • Process ad detection result
      • Submit a scheduled report
      • Start report scheduler
      • Stop report scheduler
      • Get scheduler status
      • Process scheduled reports
      • Test browser session (non-headless)
      • Test report submission (non-headless)
    • Comprehensive Analytics
      • Get comprehensive dashboard analytics
      • Get overview statistics
      • Get brand-wise statistics
      • Get daily statistics
      • Get platform success rates
      • Get account performance
      • Get summary report
    • Search
      • Ra lệnh Máy Lọc Dữ Liệu TOP SEO Hàng Loại (Scraper Engine)
      • Đếm tổng số dòng tìm kiếm (Length)
    • Report Tasks
      • Tạo chiến dịch Report (Auto Spawn 14 tasks)
      • Tạo chiến dịch Report Form hàng loạt (Bulk Abuse Report)
      • Create Direct Report (Từ API hệ thống thay vì Frontend)
      • Tạo Nhiệm Vụ Sinh Email Khiếu nại (Automated Bulk Mail Spam)
      • Worker Pull - Lấy task Báo cáo đang Pending
      • Worker Trả kết quả (Report Status)
      • Danh mục Platfoms & Providers
      • Dashboard Statistic Báo Cáo
      • Force Run Cronjob
    • Monitor
      • Xuất dữ liệu đo đếm Hardware (Telemetry OS Watchdog)
    • Schemas
      • CreateTask
      • UpdateTask
      • CreateTaskGroupRequest
      • CreateProxy
      • CreateSearch
      • ReportTaskCreation
      • CreateEmail
      • CreateMultipleSearchRequest
      • CreateMultipleReportRequest
      • UpdateReportStatusRequest
      • TestProxyRequest
  1. Hướng dẫn sử dụng

Setup Guide

Traffic Tools Ecosystem — Complete Setup Guide#


Mục lục#

1.
Kiến trúc tổng quan
2.
Yêu cầu cài đặt
3.
Phương án A: Chạy bằng Docker (Khuyến nghị)
4.
Phương án B: Chạy Local (Bare-Metal)
5.
Cấu hình biến môi trường chi tiết
6.
Xác minh hệ thống đang chạy
7.
Thứ tự khởi động đúng
8.
Troubleshooting & Lỗi phổ biến

1. Kiến trúc tổng quan#

Sơ đồ Luồng Dữ liệu#

┌─────────────────────────────────────────────────────────────────┐
│                        ADMIN DASHBOARD                          │
│                   Vue 3 + Vite + Naive-UI                       │
│                    http://localhost:5173                         │
└────────────────────────┬────────────────────────────────────────┘
                         │ REST API (HTTP)
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│                      API MASTER SERVER                          │
│              Golang 1.22 · GoFiber · GORM                       │
│                    http://localhost:33001                        │
│  ┌───────────┐   ┌───────────┐   ┌───────────┐                  │
│  │  MySQL    │   │  MongoDB  │   │  Redis    │                  │
│  │ :33022    │   │   :33021  │   │  :33023   │                  │
│  └───────────┘   └───────────┘   └───────────┘                  │
└─────────────┬────────────────────────┬───────────────────────────┘
              │ Webhook / Task Dispatch │ Task Result Callback
              ▼                        │
┌─────────────────────────────────┐    │
│         TOOLS V2 SERVER         │────┘
│    Bun >= 1.2.5 · ElysiaJS      │
│       http://localhost:3005      │
│  ┌──────────────────────────┐   │
│  │  MongoDB (dùng chung     │   │
│  │  hoặc DB riêng)          │   │
│  │      :33021              │   │
│  └──────────────────────────┘   │
│                                 │
│  Quản lý: Task Groups, Proxies  │
│  Profile, Search, Report Tasks  │
└─────────────────────────────────┘

Phân hệ & Công nghệ#

Phân hệCông nghệCổng mặc địnhDB sử dụng
apiGolang 1.22, GoFiber, GORM:33001MySQL + MongoDB + Redis
adminVue 3, Vite, Naive UI, Tailwind CSS:5173—(Gọi qua API)
tools_v2Bun ≥1.2.5, ElysiaJS, Puppeteer:3005MongoDB

2. Yêu cầu cài đặt#

Chạy Local#

Công cụPhiên bản tối thiểuLệnh kiểm tra
Go1.22.4go version
Node.js18.3.0node -v
Bun1.2.5bun -v
MongoDB6.0+mongod --version
MySQL8.0+mysql --version
Redis6.2+redis-cli --version

Chạy Docker#

Công cụPhiên bản tối thiểuLệnh kiểm tra
Docker24.0+docker --version
Docker Compose2.20+docker compose version

Cài đặt Bun (Windows)#

# Chạy trong PowerShell (Run as Administrator)
irm bun.sh/install | iex

# Kiểm tra sau khi cài
bun -v

3. Phương án A: Chạy bằng Docker#

[!TIP]
Đây là phương án khuyến nghị cho môi trường Production và CI/CD. Tất cả các Database sẽ được Docker quản lý, không cần cài tay.

Bước 3.1 — Khởi động Database bằng Docker Compose (Dùng chung cho cả 3 phân hệ)#

Mở file .env và sửa các thông số Database theo chuẩn của Docker:
# File: api/.env  (bắt buộc khi dùng Docker)
DB_MONGO_HOST=traffic_tool_mongodb
DB_MONGO_PORT=27017
DB_MONGO_USER=root
DB_MONGO_PASS=PwDev123
DB_MONGO_NAME=tool-traffic-api

DB_MYSQL_HOST=traffic_tool_mysql
DB_MYSQL_PORT=3306
DB_MYSQL_USER=root
DB_MYSQL_PASS=PwDev123
DB_MYSQL_NAME=tool_traffic_api

REDIS_HOST=traffic_tool_redis
REDIS_PORT=6379
REDIS_DB=0
Sau đó chạy Docker Compose để khởi động toàn bộ hạ tầng:
Các cổng được mở trên máy host:
ContainerImageHost Port → Container Port
traffic_tool_mongodbmongo:833021 → 27017
traffic_tool_mysqlmysql:8.433022 → 3306
traffic_tool_redisredis:6.233023 → 6379

Bước 3.2 — Chạy toàn bộ stack bằng Docker (Bao gồm API)#

[!NOTE]
API Docker sẽ chạy trên cổng :33001 (host), môi trường development. Log đầu tiên sẽ hiện "Server started on :33001".

4. Phương án B: Chạy Local (Bare-Metal)#

[!NOTE]
Phương án này dùng khi phát triển (Development), Debug trực tiếp source code hoặc không có Docker.

4.1 — Cài đặt & Chạy API (Golang Backend)#

Yêu cầu: Go 1.22.4+ · MongoDB + MySQL + Redis đang chạy (có thể dùng Docker chỉ cho DB)
Bước 1: Cấu hình môi trường
Mở .env và điền thông tin kết nối LOCAL (khác với Docker):
APP_MODE=development
SERVER_PORT=33001
AUTO_MIGRATE_DATABASE=true

# Kết nối Local MongoDB (nếu chạy MongoDB qua Docker với port 33021)
DB_MONGO_HOST=localhost
DB_MONGO_PORT=33021
DB_MONGO_USER=root
DB_MONGO_PASS=PwDev123
DB_MONGO_NAME=tool-traffic-api

# Kết nối Local MySQL (nếu chạy MySQL qua Docker với port 33022)
DB_MYSQL_HOST=localhost
DB_MYSQL_PORT=33022
DB_MYSQL_USER=root
DB_MYSQL_PASS=PwDev123
DB_MYSQL_NAME=tool_traffic_api

# Kết nối Redis (Docker port 33023)
REDIS_HOST=localhost
REDIS_PORT=33023
REDIS_DB=0

# JWT & Webhook
JWT_SECRET=your-secret-key-here
WEBHOOK_KEY=255d00cccdf39388d56b2edf4deb5ee85f95fa42f4e502176ae1db15fbbed26a
WEBHOOK_HOST=http://localhost:33001
WEBHOOK_TASK_UPDATE_STATUS_URL=http://localhost:33001/webhook/task/update-status
WEBHOOK_PROXY_GET_PROXY_URL=http://localhost:33001/webhook/proxy/get-proxy
WEBHOOK_SEARCH_KEYWORD_URL=http://localhost:33001/webhook/keyword-result
WEBHOOK_URL=http://localhost:33001/webhook/task/update-process

# Telegram (tuỳ chọn, để trống nếu không dùng)
TELEGRAM_BOT_TOKEN=
TELEGRAM_CHAT_ID=0
ENABLE_PUSH_MESSAGE_ERROR_TO_TELEGRAM=false

# IP trắng mà Tools V2 Worker được phép gọi vào
WHITE_LIST_IP_TOOL_TRAFFIC=127.0.0.1,localhost
IP_ALLOWED=127.0.0.1,localhost

# Giao tác vụ Traffic
LIMIT_SEND_TASK_PER_SERVER=30
CREATE_MULTIPLE_TASK_URL=/task-traffics/multiple
CREATE_SINGLE_TASK_URL=/task-traffics

# Schedule
SCHEDULE_RESET_TASK=*/10 * * * *
SCHEDULE_SEND_TASK=* * * * *
SCHEDULE_SEARCH_KEYWORD=*/30 * * * *
SCHEDULE_REPORT_TRAFFIC=0 2-22/2 * * *
Bước 2: Tải dependencies
Bước 3: Tạo dữ liệu mẫu ban đầu (chỉ cần chạy lần đầu)
Bước 4: Khởi động API
API chạy thành công sẽ log: "🚀 Server started on :33001"

4.2 — Cài đặt & Chạy Admin (Vue 3 / Vite)#

Yêu cầu: Node.js 18.3.0+ hoặc Bun 1.2.5+
Bước 1: Cài packages
Bước 2: Kiểm tra biến môi trường
File .env.development đã có sẵn với nội dung mặc định:
# File: admin/.env.development
NODE_MODE=development
VITE_API_SERVER=http://localhost:33001
[!WARNING]
Đảm bảo VITE_API_SERVER trỏ đúng về địa chỉ API đang chạy. Nếu API chạy trên cổng khác, hãy sửa tại đây.
Bước 3: Chạy Dev Server
Bước 4: Build Production (tuỳ chọn — khi deploy)
Admin chạy thành công sẽ log:
➜ Local: http://localhost:5173/

4.3 — Cài đặt & Chạy Tools V2 (Bun / ElysiaJS)#

Yêu cầu: Bun ≥ 1.2.5 · MongoDB đang chạy (dùng chung hoặc riêng)
[!IMPORTANT]
Tools V2 cần Puppeteer và Chromium để chạy browser automation. Chromium sẽ tự tải về lần đầu khi cài packages.
Bước 1: Cài packages
Lần đầu cài sẽ tự động tải Chromium (khoảng 100-200MB), cần kết nối internet.
Bước 2: Tạo file .env
Tools V2 không có file .env.example mặc định. Tạo mới file .env tại thư mục gốc tools_v2/:
# ====== FILE: tools_v2/.env ======

NODE_ENV=development

# Cổng lắng nghe của Tools V2
PORT=3005

# Server ID (dùng để phân biệt khi nhiều Worker)
SERVER_ID=tools_v2_server_1

# ---- MongoDB ----
# Nếu dùng chung MongoDB với API (port 33021 từ Docker):
DB_MONGO_HOST=localhost
DB_MONGO_PORT=33021
DB_MONGO_USERNAME=root
DB_MONGO_PASSWORD=PwDev123
DB_MONGO_DATABASE=traffic-tool

# ---- Kết nối về API Master ----
API_HOST=http://localhost:33001
WEBHOOK_HOST=http://localhost:33001
API_KEY=your-api-key-here
WEBHOOK_KEY=255d00cccdf39388d56b2edf4deb5ee85f95fa42f4e502176ae1db15fbbed26a

# ---- IP Whitelist (các IP được phép gọi vào) ----
# Để trống = cho phép tất cả (không khuyến nghị production)
IP_ALLOWED=

# ---- Search Configuration ----
# Chế độ Search Flow: "click" (click kết quả SERP) hoặc "report" (báo cáo)
SEARCH_FLOW=click

# ---- Traffic Limits (Giới hạn luồng chạy) ----
# Tắt giới hạn khi local (mặc định MAX_SAFE_INTEGER khi NODE_ENV=development)
SEARCH_TASK_LIMIT=1000
TASK_RETRY_LIMIT=8
PROXY_RETRY_LIMIT=15
MAX_RETRY_COUNT=3

# Browser automation
BROWSER_LIMIT_PER_PROCESS=1

# ---- AI / OpenAI (cho tính năng tạo nội dung báo cáo) ----
CHATGPT_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxx
CHATGPT_MODEL=gpt-4o-mini

# ---- SMTP (Email tự động báo cáo) ----
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password

# ---- Proxy Provider ----
ZING_PROXY_API_KEY=your-zing-proxy-jwt-token
ZING_PROXY_BASE_URL=https://api.zingproxy.com/proxy
PROXY_API_KEY=

# ---- Logging ----
LOG_LEVEL=info
LOG_WRITE_TO_FILE=false
LOG_WRITE_TO_CONSOLE=true
LOG_DIR=storage/log
ENABLE_SCREENSHOTS=true

# ---- Traffic Ratio Tuning ----
KILL_TRAFFIC_RATIO=0.8
HOME_TRAFFIC_RATIO=0.25
HOME_TRAFFIC_PER_TARGET_LIMIT=3
HOME_TRAFFIC_LIMIT=2
GEOLOCATION_RANDOM_RADIUS_KM=2.0
Bước 3: Khởi động server
Tools V2 chạy thành công sẽ log:
🦊 Elysia is running at http://localhost:3005

5. Cấu hình biến môi trường chi tiết#

API (Golang) — Biến quan trọng#

BiếnMô tảMặc định
SERVER_PORTCổng HTTP của API33001
AUTO_MIGRATE_DATABASETự động tạo bảng MySQL khi khởi độngfalse
JWT_SECRETKhoá bí mật ký JWT token(bắt buộc đặt)
WEBHOOK_KEYKhoá bí mật Webhook giữa API ↔ Tools V2(bắt buộc đặt)
LIMIT_SEND_TASK_PER_SERVERSố Task tối đa gửi xuống mỗi Worker/lần30
SCHEDULE_SEND_TASKCron gửi task (mặc định mỗi 1 phút)* * * * *
SCHEDULE_RESET_TASKCron reset task bị mắc kẹt*/10 * * * *
WHITE_LIST_IP_TOOL_TRAFFICDanh sách IP Worker được phép gọi API127.0.0.1
ENABLE_PUSH_MESSAGE_ERROR_TO_TELEGRAMGửi lỗi lên Telegramfalse

Tools V2 (Bun/ElysiaJS) — Biến quan trọng#

BiếnMô tảMặc định
PORTCổng HTTP của Tools V23005
DB_MONGO_HOSTHost MongoDBlocalhost
DB_MONGO_PORTPort MongoDB27017
DB_MONGO_USERNAMEUser MongoDB(rỗng = no auth)
DB_MONGO_PASSWORDMật khẩu MongoDB(rỗng = no auth)
DB_MONGO_DATABASETên Database MongoDBtraffic-tool
API_HOST / WEBHOOK_HOSTĐịa chỉ API Master (để gọi lại kết quả)localhost:33001
WEBHOOK_KEYKhoá bí mật Webhook (phải khớp với bên API)(bắt buộc)
CHATGPT_API_KEYOpenAI API key (dùng cho tính năng AI Report)(bắt buộc nếu dùng)
ZING_PROXY_API_KEYJWT Token đăng nhập dịch vụ Zing Proxy(bắt buộc nếu dùng)
IP_ALLOWEDIP được phép gọi vào Tools V2 (cách nhau bằng dấu ,)(rỗng = cho tất cả)
SEARCH_FLOWChế độ xử lý kết quả Searchclick
LOG_LEVELMức log: debug, info, warn, errorinfo

Admin (Vue 3) — Biến Vite#

BiếnFileMô tả
VITE_API_SERVER.env.developmentURL gốc của API Golang
NODE_MODE.env.developmentChế độ môi trường (development)

6. Xác minh hệ thống đang chạy#

Sau khi khởi động cả 3 dịch vụ, kiểm tra bằng các lệnh curl nhanh:

7. Thứ tự khởi động đúng#

[!IMPORTANT]
Phải khởi động theo đúng thứ tự để tránh lỗi kết nối.
1. Database (MongoDB, MySQL, Redis)  ← Phải chạy trước tiên
       ↓
2. API Golang (:33001)               ← Kết nối DB, migrate schema, cài Cron job
       ↓
3. Tools V2 (:3005)                  ← Kết nối MongoDB, sẵn sàng nhận Task
       ↓
4. Admin Dashboard (:5173)           ← Kết nối API, hiển thị dữ liệu

Script khởi động nhanh (Windows PowerShell)#

Lưu file này thành start-all.ps1 tại thư mục gốc:
# ============================================================
# start-all.ps1 — Khởi động toàn bộ Traffic Tools Ecosystem
# ============================================================

$root = "d:\WinAd Projects\Traffic Tools"

Write-Host "🐳 [1/4] Khởi động Database (Docker)..." -ForegroundColor Cyan
Set-Location "$root\api"
docker compose up -d traffic_tool_mongodb traffic_tool_mysql traffic_tool_redis

Write-Host "⏳ Chờ Database sẵn sàng (15 giây)..." -ForegroundColor Yellow
Start-Sleep -Seconds 15

Write-Host "🐹 [2/4] Khởi động API Golang..." -ForegroundColor Green
Start-Process powershell -ArgumentList "-NoExit", "-Command", "
  Set-Location '$root\api';
  Write-Host '--- API Server ---' -ForegroundColor Green;
  go run cmd/main.go
" 

Write-Host "⏳ Chờ API khởi động (5 giây)..." -ForegroundColor Yellow
Start-Sleep -Seconds 5

Write-Host "🐰 [3/4] Khởi động Tools V2 (Bun)..." -ForegroundColor Magenta
Start-Process powershell -ArgumentList "-NoExit", "-Command", "
  Set-Location '$root\tools_v2';
  Write-Host '--- Tools V2 Server ---' -ForegroundColor Magenta;
  bun run dev
"

Write-Host "⏳ Chờ Tools V2 khởi động (3 giây)..." -ForegroundColor Yellow
Start-Sleep -Seconds 3

Write-Host "🌐 [4/4] Khởi động Admin Dashboard..." -ForegroundColor Blue
Start-Process powershell -ArgumentList "-NoExit", "-Command", "
  Set-Location '$root\admin';
  Write-Host '--- Admin Dashboard ---' -ForegroundColor Blue;
  npm run dev
"

Write-Host ""
Write-Host "✅ Toàn bộ hệ thống đang khởi động!" -ForegroundColor Green
Write-Host "   API:     http://localhost:33001" -ForegroundColor White
Write-Host "   Tools V2: http://localhost:3005" -ForegroundColor White
Write-Host "   Admin:    http://localhost:5173" -ForegroundColor White
Chạy script:
powershell -ExecutionPolicy Bypass -File start-all.ps1

8. Troubleshooting & Lỗi phổ biến#

❌ Lỗi: dial mongodb: no reachable servers#

Nguyên nhân: Tools V2 hoặc API không kết nối được MongoDB.
Khắc phục:

❌ Lỗi: API khởi động báo Error: table not found trong MySQL#

Nguyên nhân: MySQL chạy nhưng chưa tạo schema.
Khắc phục:
Đảm bảo trong .env của API:
AUTO_MIGRATE_DATABASE=true
Sau đó restart API. GORM sẽ tự tạo bảng khi khởi động.

❌ Lỗi: npm install Admin báo conflict peer-dependency#

Khắc phục:

❌ Lỗi: Tools V2 báo Chromium executable not found#

Nguyên nhân: Puppeteer chưa tải xong Chromium
Khắc phục:

❌ Lỗi: Admin Dashboard báo Network Error hoặc data rỗng#

Nguyên nhân: API chưa chạy hoặc VITE_API_SERVER sai địa chỉ.
Khắc phục:
1.
Kiểm tra API đang chạy: curl http://localhost:33001/api/ping
2.
Kiểm tra file admin/.env.development:
VITE_API_SERVER=http://localhost:33001
3.
Restart Admin: Ctrl+C → npm run dev

❌ Lỗi: CORS khi Admin gọi API#

Nguyên nhân: API chưa cấu hình CORS cho localhost:5173.
Khắc phục:
Trong .env của API:
WHITE_LIST_IP_TOOL_TRAFFIC=127.0.0.1,localhost
Kiểm tra trong code API (GoFiber) xem CORS có đang allow http://localhost:5173 không.

❌ bun run dev của Tools V2 báo lỗi WEBHOOK_KEY mismatch#

Nguyên nhân: WEBHOOK_KEY trong tools_v2/.env không khớp với WEBHOOK_KEY trong api/.env.
Khắc phục: Đặt cùng WEBHOOK_KEY cho cả hai:
# Trong api/.env VÀ tools_v2/.env phải giống nhau:
WEBHOOK_KEY=255d00cccdf39388d56b2edf4deb5ee85f95fa42f4e502176ae1db15fbbed26a
Modified at 2026-03-24 06:50:03
Previous
User Guide
Next
1. Thống kê hàng ngày (Daily Statistics)
Built with