Triển Khai Môi Trường Local — Tools V2 Worker Engine

Phiên bản: 2.5.0
Cập nhật lần cuối: 26/03/2026

1. Yêu Cầu Hệ Thống

1.1. Phần Mềm Bắt Buộc

Bun phiên bản >= 1.2.5. Tải từ https://bun.sh.

Docker Desktop (Windows/macOS) hoặc Docker Engine (Linux) để chạy MongoDB.

Git phiên bản >= 2.30.0.

1.2. Hệ Điều Hành

Ubuntu 22.04 LTS — khuyến nghị, được test đầy đủ.

macOS Sonoma trở lên — hỗ trợ tốt.

Windows với WSL2 — hoạt động nhưng cần cấu hình thêm.

1.3. Phần Cứng Tối Thiểu

RAM: 4GB tối thiểu, 8GB khuyến nghị.

CPU: 2 cores tối thiểu, 4 cores khuyến nghị.

Disk: 10GB trống cho code, dependencies, log và screenshots.

1.4. Cài Đặt Bun

1.5. Cài Đặt Chromium Dependencies (Linux/WSL2)

Puppeteer cần các thư viện đồ họa để chạy Chrome headless trên Linux:

Nếu thiếu các thư viện này, Puppeteer sẽ báo lỗi Shared object missing khi cố mở Chrome.

2. Thiết Lập Lần Đầu

2.1. Clone Repository

2.2. Cài Đặt Dependencies

Bun sẽ tự động:

Đọc package.json và cài tất cả dependencies.

Tải Chromium binary (~150MB) vào ~/.cache/puppeteer.

Tạo bun.lock nếu chưa có.

Quá trình này mất khoảng 2-5 phút lần đầu.

2.3. Cấu Hình Biến Môi Trường

Chỉnh sửa .env với các giá trị quan trọng:

# Kết nối Go API Backend
API_HOST=http://localhost:33001
API_KEY=your-api-key-matching-go-api
WEBHOOK_API_KEY=your-webhook-key

# MongoDB (dùng Docker)
DB_MONGO_HOST=localhost
DB_MONGO_PORT=27017
DB_MONGO_USERNAME=root
DB_MONGO_PASSWORD=PwDev123
DB_MONGO_DATABASE=tool-traffic-tools

# Server identity
SERVER_ID="127.0.0.1"

# IP được phép gọi API
IP_ALLOWED=127.0.0.1,11.0.3.11

# Giới hạn browser (thấp cho dev)
BROWSER_LIMIT_PER_PROCESS=1

# Debug mode
NODE_ENV=development
DEBUG=true

2.4. Khởi Động MongoDB

Lệnh này khởi động MongoDB container với:

Container name: traffic_tool_mongodb_v2.

Port: 27017 (map ra host theo DB_MONGO_PORT).

IP tĩnh trong Docker network: 11.0.3.11.

Data persist trong Docker volume mongodb_data.

Kiểm tra MongoDB đang chạy:

3. Khởi Chạy Server

3.1. Chạy Với Hot-Reload (Khuyến Nghị Cho Development)

Lệnh này thực thi: bun run --inspect=localhost:4000/debugger --watch src/index.ts

--watch: Tự động reload khi file TypeScript thay đổi.

--inspect=localhost:4000/debugger: Bật debugger tại port 4000.

Output mong đợi khi khởi động thành công:

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

3.2. Chạy Không Hot-Reload

Dùng khi không cần hot-reload, ví dụ khi test performance.

3.3. Build JavaScript Bundle

Build thành JavaScript bundle. Vẫn cần Bun runtime để chạy.

3.4. Compile Thành Binary Tĩnh

Compile thành standalone binary:

Tự chứa Bun runtime, TypeScript code và tất cả npm modules.

Có thể chạy trên server khác không cần cài Bun.

Kích thước khoảng 50-100MB.

Dùng trong production deployment.

Chạy binary:

4. Kiểm Tra Hoạt Động

4.1. Kiểm Tra Server

4.2. Kiểm Tra Swagger UI

Mở trình duyệt tại http://localhost:3005/swagger để xem tất cả API endpoints với documentation đầy đủ.

4.3. Kiểm Tra Kết Nối MongoDB

4.4. Kiểm Tra Kết Nối Go API

Nếu Go API chưa chạy, Tools V2 vẫn khởi động được nhưng sẽ không nhận được tasks.

4.5. Kiểm Tra System Metrics

5. Debug Với Bun Inspector

5.1. Kết Nối Debugger

Khi chạy bun run dev, debugger được bật tại localhost:4000/debugger.

Kết nối từ Chrome DevTools:

Mở Chrome và truy cập chrome://inspect.

Click "Configure..." và thêm localhost:4000.

Click "inspect" khi thấy target xuất hiện.

DevTools mở với đầy đủ tính năng: breakpoints, call stack, variables.

5.2. Đặt Breakpoints

Trong DevTools:

Mở tab "Sources".

Navigate đến file TypeScript cần debug.

Click vào số dòng để đặt breakpoint.

Khi code chạy đến breakpoint, execution dừng lại.

5.3. Debug Cron Jobs

Cron jobs chạy mỗi giây, khó debug bằng breakpoint thông thường. Thay vào đó:

Thêm console.log hoặc logger.debug vào code.

Xem output trong terminal hoặc log files.

Dùng LOG_LEVEL=debug để xem log chi tiết hơn.

6. Các Lệnh Phát Triển Thường Dùng

6.1. Format Code

Prettier format toàn bộ code trong src/ theo cấu hình .prettierrc.json.

6.2. Kiểm Tra Lint

oxlint là linter viết bằng Rust, nhanh hơn ESLint nhiều lần. Flag --fix tự động sửa các lỗi có thể sửa được.

6.3. Kiểm Tra TypeScript

Kiểm tra TypeScript types mà không emit files. Chạy trước khi commit để đảm bảo không có type errors.

6.4. Dọn Dẹp Build

Xóa thư mục dist/ để build lại từ đầu.

6.5. Chạy Scripts Tiện Ích

7. Quy Trình Làm Việc Hàng Ngày

7.1. Bắt Đầu Ngày Làm Việc

7.2. Trước Khi Tạo Merge Request

7.3. Khi Thay Đổi Dependencies

8. Xử Lý Sự Cố Thường Gặp

8.1. Lỗi "Shared object missing" Khi Mở Chrome

Nguyên nhân: Thiếu Chromium system dependencies trên Linux.

Giải pháp:

8.2. Lỗi "Cannot connect to MongoDB"

Kiểm tra Docker container:

Nếu container không chạy:

Nếu container chạy nhưng vẫn lỗi, kiểm tra DB_MONGO_HOST trong .env:

Khi chạy trực tiếp (không Docker): DB_MONGO_HOST=localhost.

Khi chạy trong Docker: DB_MONGO_HOST=traffic_tool_mongodb_v2.

8.3. Lỗi "Port 3005 already in use"

8.4. Lỗi "API_HOST not reachable"

Kiểm tra Go API Backend đang chạy:

Nếu không phản hồi, khởi động Go API Backend trước khi chạy Tools V2.

8.5. Puppeteer Không Tìm Thấy Chrome

8.6. Lỗi "bun: command not found"

8.7. Hot-Reload Không Hoạt Động

Kiểm tra --watch flag có trong lệnh không:

Nếu dùng WSL2, hot-reload có thể chậm do filesystem events. Đây là giới hạn của WSL2.

8.8. Lỗi TypeScript Khi Chạy

Bun chạy TypeScript trực tiếp mà không cần biên dịch. Nếu có lỗi TypeScript:

Lưu ý: Bun bỏ qua một số TypeScript errors khi chạy. Luôn chạy typecheck để đảm bảo code đúng.

9. Cấu Hình Cho Từng Hệ Điều Hành

9.1. Ubuntu/Debian

Đây là môi trường được hỗ trợ tốt nhất. Không cần cấu hình đặc biệt ngoài cài Chromium dependencies.

9.2. macOS

Chrome thường đã được cài sẵn. Nếu không:

Puppeteer trên macOS dùng Chrome system thay vì Chromium bundled.

9.3. Windows với WSL2

Cài WSL2 với Ubuntu 22.04:

# Trong PowerShell (Admin)
wsl --install -d Ubuntu-22.04

Sau khi cài WSL2, làm theo hướng dẫn Ubuntu. Lưu ý:

Clone repository vào filesystem của WSL2, không phải Windows filesystem (/mnt/c/).

Docker Desktop cần bật WSL2 integration.

Hot-reload có thể chậm hơn native Linux.

10. Cấu Hình `.env` Cho Development

File .env đầy đủ cho development:

# Server
PORT=3005
NODE_ENV=development
DEBUG=true
RUNTIME=bun
SERVER_ID="127.0.0.1"

# Authentication
API_KEY='your-api-key-matching-go-api'
WEBHOOK_API_KEY='your-webhook-key'
PROXY_API_KEY='your-proxy-api-key'
IP_ALLOWED=127.0.0.1,11.0.3.11

# Go API Backend
API_HOST=http://localhost:33001

# MongoDB (Docker)
DB_MONGO_HOST=localhost
DB_MONGO_PORT=27017
DB_MONGO_USERNAME=root
DB_MONGO_PASSWORD=PwDev123
DB_MONGO_DATABASE=tool-traffic-tools

# Browser limits (thấp cho dev)
BROWSER_LIMIT_PER_PROCESS=1

# Traffic control
TASK_RETRY_LIMIT=3
ENABLE_GEOLOCATION=true
MODE=browser

# Anti-Captcha
CAPTCHA_SOLVING_ENABLED=true
CAPTCHA_FALLBACK_TO_MANUAL=true
ANTICAPTCHA_API_KEY=your-anticaptcha-key
ANTICAPTCHA_BASE_URL=https://api.anti-captcha.com
ANTICAPTCHA_TIMEOUT=300000
ANTICAPTCHA_RETRY_ATTEMPTS=3

# OpenAI
CHATGPT_API_KEY=sk-proj-your-openai-key
CHATGPT_MODEL=gpt-4o-mini

# DigitalOcean Spaces
DIGITAL_OCEAN_BUCKET_NAME=your-bucket
DIGITAL_OCEAN_REGION=sgp1
DIGITAL_OCEAN_ACCESS_KEY_ID=your-key-id
DIGITAL_OCEAN_SECRET_ACCESS_KEY=your-secret
DIGITAL_OCEAN_ENDPOINT=https://sgp1.digitaloceanspaces.com
DIGITAL_OCEAN_CDN_URL=https://your-bucket.sgp1.cdn.digitaloceanspaces.com

# Cloudinary (fallback)
CLOUDINARY_CLOUD_NAME=your-cloud
CLOUDINARY_API_KEY=your-key
CLOUDINARY_API_SECRET=your-secret
CLOUDINARY_UPLOAD_PRESET=ml_default

# SMTP
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password

# Logging
LOG_LEVEL=debug
LOG_COLORIZED=true
LOG_WRITE_TO_FILE=true
LOG_WRITE_TO_CONSOLE=true
LOG_TIMESTAMP=true
LOG_FOR_RECORD=true
ENABLE_SCREENSHOTS=true

11. Chạy Trong Docker (Development)

11.1. Khi Nào Dùng Docker

Chạy Tools V2 trong Docker hữu ích khi:

Muốn môi trường giống production hơn.

Không muốn cài Bun và Chrome trực tiếp trên máy.

Test Docker configuration trước khi deploy.

11.2. Uncomment Tool Service

Trong docker-compose.yml, service tool đang bị comment. Uncomment để chạy:

11.3. Cập Nhật `.env` Cho Docker

Khi cả Tools V2 và MongoDB đều chạy trong Docker, cập nhật:

# Dùng container name thay vì localhost
DB_MONGO_HOST=traffic_tool_mongodb_v2

11.4. Build Và Chạy

11.5. Dockerfile Development

.docker/dev/Dockerfile được thiết kế cho development:

Lưu ý: Dockerfile này dùng oven/bun:latest và cài Google Chrome thực. Build lần đầu mất khoảng 5-10 phút.

12. Quản Lý MongoDB Local

12.1. Kết Nối MongoDB

12.2. Xem Collections

12.3. Xóa Tất Cả Collections

Hoặc thủ công:

12.4. Backup Và Restore

13. Tích Hợp Với Go API Backend

13.1. Yêu Cầu

Để Tools V2 hoạt động đầy đủ, Go API Backend phải đang chạy và accessible tại API_HOST.

13.2. Kiểm Tra Tích Hợp

13.3. Chạy Không Có Go API

Tools V2 vẫn khởi động được khi Go API không chạy. Tuy nhiên:

Cron task-group-api-request-cron sẽ log lỗi mỗi giây.

Không có tasks mới được nhận.

Các tasks đang pending trong MongoDB vẫn được thực thi.

Để test mà không cần Go API, có thể tạo tasks trực tiếp qua API:

14. Checklist Thiết Lập Hoàn Chỉnh

Sau khi hoàn thành thiết lập, kiểm tra từng mục:

Bun >= 1.2.5 đã cài: bun --version.

Docker đang chạy: docker ps.

MongoDB container đang chạy: docker ps | grep mongodb.

File .env đã được tạo từ .env.example.

API_HOST trỏ đúng đến Go API Backend.

API_KEY khớp với cấu hình Go API.

IP_ALLOWED bao gồm 127.0.0.1 và 11.0.3.11.

Chromium dependencies đã cài (Linux).

Server khởi động thành công: bun run dev.

Health check trả về OK: curl http://localhost:3005/health.

Swagger UI accessible: http://localhost:3005/swagger.

MongoDB kết nối thành công (xem log khởi động).

Local

Triển Khai Môi Trường Local — Tools V2 Worker Engine#

1. Yêu Cầu Hệ Thống#

1.1. Phần Mềm Bắt Buộc#

1.2. Hệ Điều Hành#

1.3. Phần Cứng Tối Thiểu#

1.4. Cài Đặt Bun#

1.5. Cài Đặt Chromium Dependencies (Linux/WSL2)#

2. Thiết Lập Lần Đầu#

2.1. Clone Repository#

2.2. Cài Đặt Dependencies#

2.3. Cấu Hình Biến Môi Trường#

2.4. Khởi Động MongoDB#

3. Khởi Chạy Server#

3.1. Chạy Với Hot-Reload (Khuyến Nghị Cho Development)#

3.2. Chạy Không Hot-Reload#

3.3. Build JavaScript Bundle#

3.4. Compile Thành Binary Tĩnh#

4. Kiểm Tra Hoạt Động#

4.1. Kiểm Tra Server#

4.2. Kiểm Tra Swagger UI#

4.3. Kiểm Tra Kết Nối MongoDB#

4.4. Kiểm Tra Kết Nối Go API#

4.5. Kiểm Tra System Metrics#

5. Debug Với Bun Inspector#

5.1. Kết Nối Debugger#

5.2. Đặt Breakpoints#

5.3. Debug Cron Jobs#

6. Các Lệnh Phát Triển Thường Dùng#

6.1. Format Code#

6.2. Kiểm Tra Lint#

6.3. Kiểm Tra TypeScript#

6.4. Dọn Dẹp Build#

6.5. Chạy Scripts Tiện Ích#

7. Quy Trình Làm Việc Hàng Ngày#

7.1. Bắt Đầu Ngày Làm Việc#

7.2. Trước Khi Tạo Merge Request#

7.3. Khi Thay Đổi Dependencies#

8. Xử Lý Sự Cố Thường Gặp#

8.1. Lỗi "Shared object missing" Khi Mở Chrome#

8.2. Lỗi "Cannot connect to MongoDB"#

8.3. Lỗi "Port 3005 already in use"#

8.4. Lỗi "API_HOST not reachable"#

8.5. Puppeteer Không Tìm Thấy Chrome#

8.6. Lỗi "bun: command not found"#

8.7. Hot-Reload Không Hoạt Động#

8.8. Lỗi TypeScript Khi Chạy#

9. Cấu Hình Cho Từng Hệ Điều Hành#

9.1. Ubuntu/Debian#

9.2. macOS#

9.3. Windows với WSL2#

10. Cấu Hình .env Cho Development#

11. Chạy Trong Docker (Development)#

11.1. Khi Nào Dùng Docker#

11.2. Uncomment Tool Service#

11.3. Cập Nhật .env Cho Docker#

11.4. Build Và Chạy#

11.5. Dockerfile Development#

12. Quản Lý MongoDB Local#

12.1. Kết Nối MongoDB#

12.2. Xem Collections#

12.3. Xóa Tất Cả Collections#

12.4. Backup Và Restore#

13. Tích Hợp Với Go API Backend#

13.1. Yêu Cầu#

13.2. Kiểm Tra Tích Hợp#

13.3. Chạy Không Có Go API#

14. Checklist Thiết Lập Hoàn Chỉnh#