Hướng Dẫn Cài Đặt — Tools V2 Worker Engine

Thư mục: tools_v2/ | Cổng mặc định: 3005 | Công nghệ: Bun + TypeScript + Puppeteer

Yêu cầu

Bun >= 1.2.5

Docker >= 24.0 (để chạy MongoDB riêng cho Tools V2)

Go API Backend đang chạy tại http://localhost:33003

Trên Linux: cần cài thêm thư viện hệ thống cho Chrome

Cài Bun:

Cài thư viện hệ thống cho Chrome (chỉ Linux):

Cài đặt

Bước 1: Cài dependencies

Lần đầu chạy, Bun sẽ tự tải Chrome (~150MB) về máy. Quá trình này mất 2-5 phút.

Bước 2: Khởi động MongoDB riêng cho Tools V2

Tools V2 dùng MongoDB riêng, tách biệt với MongoDB của Go API.

Kiểm tra:

Bước 3: Tạo file cấu hình

Mở file .env và chỉnh sửa các giá trị sau:

# Địa chỉ Go API Backend
# Phải trỏ đúng đến API đang chạy
API_HOST=http://localhost:33003

# Phải khớp chính xác với API_KEY trong api/.env
API_KEY='#!6f1!0#aa77%@G$%8262x4AaD460c*3TExbqS9@0fPHF2F&$9m9$0Z!!^468J72W'

# Phải khớp chính xác với WEBHOOK_KEY trong api/.env
WEBHOOK_API_KEY='255d00cccdf39388d56b2edf4deb5ee85f95fa42f4e502176ae1db15fbbed26a'

# Kết nối MongoDB của Tools V2
# Dùng localhost vì Tools V2 chạy trực tiếp trên máy, không trong Docker
DB_MONGO_HOST=localhost
DB_MONGO_PORT=27017

# Giới hạn số tab Chrome mở đồng thời
# Để 1 khi phát triển để tránh tốn RAM
BROWSER_LIMIT_PER_PROCESS=1

Quan trọng: API_KEY và WEBHOOK_API_KEY phải khớp chính xác với API_KEY và WEBHOOK_KEY trong api/.env. Nếu không khớp, Tools V2 sẽ bị từ chối kết nối.

Bước 4: Khởi động

Kết quả mong đợi:

Deleted user-data folder
Server started on port 3005
Swagger documentation available at http://localhost:3005/swagger
Connected to MongoDB
All task groups set to pending successfully

Bước 5: Kiểm tra

Xem tài liệu API tại http://localhost:3005/swagger.

Các biến môi trường quan trọng

Kết nối và xác thực

Biến	Mô tả
`API_HOST`	Địa chỉ Go API Backend
`API_KEY`	Phải khớp với `API_KEY` trong `api/.env`
`WEBHOOK_API_KEY`	Phải khớp với `WEBHOOK_KEY` trong `api/.env`
`IP_ALLOWED`	IP được phép gọi API của Tools V2 (mặc định: `127.0.0.1,11.0.3.11`)
`SERVER_ID`	Định danh máy chủ này trong hệ thống (mặc định: IP của máy)

Giới hạn tài nguyên

Biến	Mô tả	Giá trị khi phát triển
`BROWSER_LIMIT_PER_PROCESS`	Số tab Chrome tối đa	`1`
`CRON_TASK_LIMIT`	Số traffic task chạy đồng thời	`1`
`CRON_REPORT_LIMIT`	Số report task chạy đồng thời	`1`
`CRON_SEARCH_LIMIT`	Số search task chạy đồng thời	`1`

Tính năng tùy chọn

Các biến sau chỉ cần khi dùng chức năng gửi báo cáo bảo mật. Khi chỉ test traffic generation, có thể bỏ qua.

Biến	Mô tả
`ANTICAPTCHA_API_KEY`	API key từ anti-captcha.com để tự động giải CAPTCHA
`CHATGPT_API_KEY`	API key OpenAI để tạo nội dung báo cáo bằng AI
`CHATGPT_MODEL`	Model GPT dùng (mặc định: `gpt-4o-mini`)
`DIGITAL_OCEAN_*`	Cấu hình lưu ảnh bằng chứng lên DigitalOcean Spaces
`CLOUDINARY_*`	Cấu hình lưu ảnh bằng chứng lên Cloudinary (dự phòng)
`SMTP_HOST`, `SMTP_USER`, `SMTP_PASS`	Cấu hình Gmail để gửi báo cáo qua email

Cấu hình Gmail App Password (cho chức năng gửi báo cáo qua email)

Gmail yêu cầu App Password thay vì mật khẩu thường khi dùng SMTP:

Bật xác thực 2 bước trên tài khoản Google

Vào Google Account → Security → 2-Step Verification → App passwords

Tạo App Password cho "Mail" → "Other device"

Dùng mật khẩu 16 ký tự này cho SMTP_PASS trong .env

Chạy bằng Docker

Bước 1: Tạo file cấu hình

Trong .env, đổi DB_MONGO_HOST sang tên container:

DB_MONGO_HOST=traffic_tool_mongodb_v2
DB_MONGO_PORT=27017

Các biến khác giữ nguyên.

Bước 2: Mở comment service `tool` trong docker-compose.yml

Mở file tools_v2/docker-compose.yml, tìm và bỏ comment phần service tool (xóa dấu # ở đầu mỗi dòng).

Bước 3: Build và khởi động

Lần đầu build mất 5-10 phút (tải Bun, cài packages, tải Chrome).

Tắt tính năng khi phát triển

Tắt CAPTCHA nếu chưa có API key:

CAPTCHA_SOLVING_ENABLED=false

Giả lập thành công để test nhanh mà không cần mở Chrome thật:

FAKE_SUCCESS=true
FAKE_SUCCESS_RATIO=1.0

Xử lý sự cố

Lỗi: "error while loading shared libraries" (Linux)

Thiếu thư viện hệ thống cho Chrome:

Lỗi: "Chrome not found" hoặc "Failed to launch the browser process"

Lỗi: "Cannot connect to MongoDB"

Lỗi: "bun: command not found"

Lỗi: "ECONNREFUSED" khi kết nối Go API

Kiểm tra Go API đang chạy và API_HOST trong .env trỏ đúng địa chỉ:

Lỗi: "401 Unauthorized" khi gọi Go API

API_KEY trong tools_v2/.env không khớp với API_KEY trong api/.env.

Lỗi: "403 Forbidden" khi gửi webhook

WEBHOOK_API_KEY trong tools_v2/.env không khớp với WEBHOOK_KEY trong api/.env. Hoặc IP của máy chưa có trong WHITE_LIST_IP_TOOL_TRAFFIC của api/.env.

Setup Guide

Hướng Dẫn Cài Đặt — Tools V2 Worker Engine#

Yêu cầu#

Cài đặt#

Bước 1: Cài dependencies#

Bước 2: Khởi động MongoDB riêng cho Tools V2#

Bước 3: Tạo file cấu hình#

Bước 4: Khởi động#

Bước 5: Kiểm tra#

Các biến môi trường quan trọng#

Kết nối và xác thực#

Giới hạn tài nguyên#

Tính năng tùy chọn#

Cấu hình Gmail App Password (cho chức năng gửi báo cáo qua email)#

Chạy bằng Docker#

Bước 1: Tạo file cấu hình#

Bước 2: Mở comment service tool trong docker-compose.yml#

Bước 3: Build và khởi động#

Tắt tính năng khi phát triển#

Xử lý sự cố#