HƯỚNG DẪN SỬ DỤNG VÀ THIẾT LẬP: PROXY SERVICE TOOL

Tài liệu hướng dẫn cách thiết lập môi trường phát triển cục bộ (Local Development) và cấu hình hệ thống Proxy Service Tool.

I. YÊU CẦU MÔI TRƯỜNG

Để vận hành hệ thống, môi trường của bạn cần đáp ứng:

Bun: Phiên bản tối thiểu >= 1.2.5 (Trình quản lý gói và Runtime chính).

Docker Desktop: Dành cho việc khởi tạo MongoDB và Redis.

Bước 1: Khởi tạo mã nguồn và biến môi trường
Nhân bản dự án và cấu hình tệp môi trường:

Bước 2: Khởi động Hạ tầng Lưu trữ
Chạy MongoDB và Redis thông qua Docker:

Lưu ý: Đảm bảo tệp .env cấu hình DB_MONGO_HOST=localhost và REDIS_HOST=localhost nếu chạy theo phương thức này.

Bước 3: Tải thư viện và Khởi chạy
Cài đặt phụ thuộc và khởi động máy chủ với chế độ theo dõi thay đổi (Hot-reload):

Máy chủ sẽ lắng nghe tại cổng 33033 (hoặc cổng được định nghĩa trong biến PORT).

Bước 4: Thiết lập Quản trị viên (First-time Admin Setup)
Đăng ký tài khoản Quản trị viên đầu tiên thông qua API:

Sau đó, tiến hành đăng nhập để lấy Token JWT và đính kèm vào Header Authorization: Bearer <token> cho các tác vụ tiếp theo.

Điều hướng IP (Whitelisting): IP_ALLOWED định nghĩa danh sách các địa chỉ IP của Tool con được phép gọi hàm xin cấp Proxy.

Cơ chế Cấp phát (Leasing):

PROXY_USE_MAX: Quy định số lượng Tool con tối đa được phép dùng chung một địa chỉ Proxy tại cùng một thời điểm (Mặc định: 3).

WEBHOOK_RETURN_PROXY: Đường dẫn cơ sở để hệ thống đính kèm vào payload phản hồi, buộc Tool con phải gọi để trả Proxy.

Cấu hình Đối tác: Yêu cầu cung cấp các Token tương ứng (KIOT_API_KEY, ZING_PROXY_TOKEN) nếu muốn bật tính năng tự động nhập Proxy.