Cấu Hình Môi Trường — Tools V2 Worker Engine

1. Tổng Quan

1.1. Cơ Chế Đọc Cấu Hình

Tools V2 đọc toàn bộ cấu hình từ biến môi trường thông qua file src/utils/env.ts. File này export một object env duy nhất được dùng xuyên suốt toàn bộ codebase. Không có nơi nào trong code đọc process.env trực tiếp ngoài env.ts.

Cơ chế hoạt động:

Khi server khởi động, loadEnv() được gọi một lần duy nhất.

Tất cả biến được đọc, coerce sang đúng kiểu dữ liệu, và apply defaults.

Object env được freeze và export.

Mọi module import env từ @/utils/env hoặc @/utils.

1.2. Phân Biệt Development Và Production

env.ts phân biệt hai chế độ dựa trên biến NODE_ENV:

Khi isLocal = true, một số giới hạn được nới lỏng:

TASK_RETRY_LIMIT: Không giới hạn (Number.MAX_SAFE_INTEGER).

PROXY_RETRY_LIMIT: Không giới hạn.

MAX_RETRY_COUNT: Không giới hạn.

BROWSER_LIMIT_PER_PROCESS: Luôn là 1.

SEARCH_TASK_LIMIT: Không giới hạn.

1.3. Biến Hardcode Trong Code

Một số giá trị quan trọng được hardcode trong env.ts và không thể override qua .env:

CRON_TASK_LIMIT = 25: Số task traffic đồng thời tối đa.

CRON_REPORT_LIMIT = 2: Số report task đồng thời tối đa.

CRON_SEARCH_LIMIT = 1: Số search task đồng thời tối đa.

BROWSER_LIMIT = 100: Hard limit tuyệt đối cho browser instances.

Lý do hardcode: Đảm bảo production luôn dùng giá trị đúng, tránh vô tình set quá cao gây crash server.

1.4. File `.env` Và `.env.example`

.env: File thực tế chứa credentials. Không bao giờ commit vào Git.

.env.example: Template với cấu trúc đầy đủ và giá trị mẫu. Luôn commit vào Git.

.env.backup: Bản backup cấu hình. Không dùng trực tiếp.

Khi setup lần đầu:

2. Nhóm Biến: Server

2.1. Danh Sách Biến

Biến	Kiểu	Mặc định	Mô tả
`PORT`	number	`3005`	Cổng HTTP server lắng nghe
`NODE_ENV`	string	`development`	Chế độ chạy: `development` hoặc `production`
`DEBUG`	boolean	`false`	Bật debug logging chi tiết
`RUNTIME`	string	`bun`	Phải là `bun` để bật AOT compilation trong Elysia
`SERVER_ID`	string	`tools_v2_server`	Định danh duy nhất của worker instance

2.2. Chi Tiết Từng Biến

PORT:

Cổng HTTP server lắng nghe.

Mặc định: 3005.

Trong Docker, port này được map ra host qua ports trong docker-compose.yml.

Swagger UI truy cập tại http://localhost:{PORT}/swagger.

NODE_ENV:

Giá trị hợp lệ: development, production.

Ảnh hưởng đến isLocal flag trong env.ts.

Khi development: Giới hạn retry được nới lỏng, browser limit = 1.

Khi production: Giới hạn nghiêm ngặt, browser limit đọc từ env.

DEBUG:

Khi true: Browser chạy có giao diện (không headless) trong development.

Khi false: Browser chạy headless.

Trong Docker, luôn headless bất kể DEBUG.

RUNTIME:

Phải là bun để createElysia() bật aot: true.

AOT (Ahead-of-Time) compilation tối ưu performance của Elysia.

SERVER_ID:

Định danh duy nhất của worker instance.

Thường là IP của server: "10.0.0.2", "192.168.1.5".

Go API dùng SERVER_ID để tracking worker health và phân phối tasks.

Mỗi server phải có SERVER_ID khác nhau.

3. Nhóm Biến: Xác Thực API

3.1. Danh Sách Biến

Biến	Kiểu	Mặc định	Mô tả
`API_KEY`	string	`""`	Token xác thực cho requests từ Tools V2 đến Go API
`WEBHOOK_API_KEY`	string	`"webhook-key"`	Token xác thực cho webhook từ Go API vào Tools V2
`PROXY_API_KEY`	string	`""`	Token xác thực riêng cho proxy endpoints
`IP_ALLOWED`	string	`""`	Danh sách IP được phép gọi API, phân cách bằng dấu phẩy

3.2. Chi Tiết Từng Biến

API_KEY:

Được gửi trong header X-API-Key khi Tools V2 gọi Go API.

Phải khớp với API_KEY được cấu hình trên Go API Backend.

Nếu không khớp, Go API trả về HTTP 401.

Ví dụ: '#!6f1!0#aa77%@G$%8262x4AaD460c*3TExbqS9@0fPHF2F&!!^468J72W'

WEBHOOK_API_KEY:

Được gửi trong header khi Go API gọi webhook vào Tools V2.

ipValidationMiddleware kiểm tra key này.

Phải khớp với key được cấu hình trên Go API.

Alias: WEBHOOK_KEY (cả hai đều được đọc, ưu tiên WEBHOOK_API_KEY).

PROXY_API_KEY:

Token riêng cho endpoint lấy proxy.

Tách biệt với API_KEY để có thể revoke độc lập.

IP_ALLOWED:

Comma-separated list IP được phép gọi API của Tools V2.

Ví dụ: "127.0.0.1,11.0.3.11,10.0.0.1".

Nếu rỗng: Tất cả IP đều được phép (không khuyến nghị trong production).

ipValidationMiddleware kiểm tra IP nguồn của mỗi request.

Trong Docker, MongoDB container có IP 11.0.3.11 nên cần thêm vào list.

4. Nhóm Biến: Kết Nối Go API Backend

4.1. Danh Sách Biến

Biến	Kiểu	Mặc định	Mô tả
`API_HOST`	string	`https://traffic-api.longtu.club`	URL của Go API Backend
`API_BASE_URL`	string	Giống `API_HOST`	Alias cho `API_HOST`
`WEBHOOK_HOST`	string	Giống `API_HOST`	Alias cho `API_HOST`

4.2. Chi Tiết

API_HOST:

URL đầy đủ của Go API Backend, bao gồm protocol và port.

Development: http://localhost:33001.

Production: https://traffic-api.longtu.club.

Tools V2 gọi {API_HOST}/api/task/request để lấy tasks.

Tools V2 gọi {API_HOST}/webhook/task/update-status để gửi kết quả.

Alias:

API_BASE_URL và WEBHOOK_HOST đều fallback về API_HOST.

Cả ba biến đều được đọc, ưu tiên theo thứ tự: API_HOST > WEBHOOK_HOST > default.

5. Nhóm Biến: MongoDB

5.1. Danh Sách Biến

Biến	Kiểu	Mặc định	Mô tả
`DB_MONGO_HOST`	string	`localhost`	Hostname của MongoDB server
`DB_MONGO_PORT`	number	`27017`	Port của MongoDB
`DB_MONGO_USERNAME`	string	`""`	Username MongoDB
`DB_MONGO_PASSWORD`	string	`""`	Password MongoDB
`DB_MONGO_DATABASE`	string	`traffic-tool`	Tên database

5.2. MongoDB URI Tự Động

env.ts tự động xây dựng MONGODB_URI từ các biến trên:

5.3. Cấu Hình Theo Môi Trường

Development (chạy trực tiếp, MongoDB trong Docker):

DB_MONGO_HOST=localhost
DB_MONGO_PORT=27017
DB_MONGO_USERNAME=root
DB_MONGO_PASSWORD=PwDev123
DB_MONGO_DATABASE=tool-traffic-tools

Development (cả Tools V2 và MongoDB trong Docker):

DB_MONGO_HOST=traffic_tool_mongodb_v2
DB_MONGO_PORT=27017
DB_MONGO_USERNAME=root
DB_MONGO_PASSWORD=PwDev123
DB_MONGO_DATABASE=tool-traffic-tools

Khi Tools V2 chạy trong Docker, phải dùng container name traffic_tool_mongodb_v2 thay vì localhost vì cả hai container trong cùng Docker network.

5.4. Docker Compose MongoDB

docker-compose.yml khởi động MongoDB với cấu hình:

MongoDB version: 8 (latest stable).

IP tĩnh trong Docker network: 11.0.3.11.

Data được persist trong Docker volume mongodb_data.

Port được map ra host theo DB_MONGO_PORT.

6. Nhóm Biến: Giới Hạn Browser Và Cron

6.1. Danh Sách Biến

Biến	Kiểu	Giá trị Dev	Giá trị Prod	Mô tả
`CRON_TASK_LIMIT`	number	25 (hardcode)	25 (hardcode)	Số traffic task đồng thời tối đa
`CRON_REPORT_LIMIT`	number	2 (hardcode)	2 (hardcode)	Số report task đồng thời tối đa
`CRON_SEARCH_LIMIT`	number	1 (hardcode)	1 (hardcode)	Số search task đồng thời tối đa
`BROWSER_LIMIT_PER_PROCESS`	number	1 (forced)	Đọc từ env	Tổng số Chrome instances tối đa
`BROWSER_LIMIT`	number	100 (hardcode)	100 (hardcode)	Hard limit tuyệt đối

6.2. Lưu Ý Quan Trọng

CRON_TASK_LIMIT, CRON_REPORT_LIMIT, CRON_SEARCH_LIMIT được hardcode trong env.ts và không thể override qua .env. Giá trị trong .env.example chỉ là tham khảo, không có tác dụng.

BROWSER_LIMIT_PER_PROCESS trong development luôn là 1 bất kể giá trị trong .env. Chỉ trong production mới đọc từ env.

6.3. Tính Toán Giới Hạn Browser

Khi cấu hình BROWSER_LIMIT_PER_PROCESS cho production, tính toán như sau:

RAM khả dụng cho Chrome = Tổng RAM - 4GB (OS và các process khác).

Mỗi Chrome instance trung bình 300MB RAM.

BROWSER_LIMIT_PER_PROCESS = RAM khả dụng / 300MB × 0.7 (buffer 30%).

Ví dụ với server 16GB RAM:

RAM khả dụng: 16 - 4 = 12GB = 12288MB.

Tối đa: 12288 / 300 = 40 instances.

Với buffer 30%: 40 × 0.7 = 28 instances.

Cấu hình: BROWSER_LIMIT_PER_PROCESS=28.

7. Nhóm Biến: Traffic Control

7.1. Danh Sách Biến

Biến	Kiểu	Mặc định	Mô tả
`TASK_RETRY_LIMIT`	number	`8` (prod), unlimited (dev)	Số lần retry tối đa cho một task
`PROXY_RETRY_LIMIT`	number	`15` (prod), unlimited (dev)	Số lần retry tối đa cho một proxy
`MAX_RETRY_COUNT`	number	`3` (prod), unlimited (dev)	Số lần retry tối đa chung
`KILL_TRAFFIC_RATIO`	number	`0.8`	Tỷ lệ kill traffic trong tổng allocation
`HOME_TRAFFIC_RATIO`	number	`0.25`	Tỷ lệ home traffic trong tổng allocation
`HOME_TRAFFIC_PER_TARGET_LIMIT`	number	`3`	Số home traffic task đồng thời cho cùng một URL
`HOME_TRAFFIC_LIMIT`	number	`2`	Giới hạn tổng home traffic tasks
`TASK_TRAFFIC_LIMIT`	number	`CRON_TASK_LIMIT * 2`	Tổng traffic tasks tối đa trong queue
`SEARCH_TASK_LIMIT`	number	`1000` (prod)	Tổng search tasks tối đa
`GEOLOCATION_RANDOM_RADIUS_KM`	number	`2.0`	Bán kính ngẫu nhiên geolocation (km)
`FAKE_SUCCESS`	boolean	`false`	Giả lập thành công (chỉ dùng để test)
`FAKE_SUCCESS_RATIO`	number	`0.5`	Tỷ lệ giả lập thành công
`MODE`	string	`browser`	Chế độ chạy: `browser` hoặc `api`
`ENABLE_ADS_RELATIONS`	boolean	`false`	Bật ads relations matching
`ENABLE_GEOLOCATION`	boolean	`true`	Bật geolocation spoofing
`ORIGINAL_SESSION_TASK_LIMIT`	number	`0`	Giới hạn task dùng original session
`SEARCH_FLOW`	string	`click`	Loại search flow: `click` hoặc `report`

7.2. Chi Tiết Biến Quan Trọng

TASK_RETRY_LIMIT:

Số lần tối đa một task group được retry trước khi bị xóa.

Mỗi lần task reset về PENDING, retries_total tăng 1.

Khi retries_total > TASK_RETRY_LIMIT, task bị xóa và đánh dấu ERROR.

Development: Không giới hạn (để test không bị mất task).

Production: Mặc định 8 lần.

KILL_TRAFFIC_RATIO:

Tỷ lệ slots được dành cho kill traffic trong ResourceAllocator.

Mặc định 0.8 = 80% slots cho kill traffic khi có kill tasks.

Giá trị này ảnh hưởng đến _getDefaultAllocation() trong resource-allocator.ts.

HOME_TRAFFIC_PER_TARGET_LIMIT:

Số lượng home traffic tasks đang chạy đồng thời cho cùng một URL mục tiêu.

LinkTracker dùng giá trị này để giới hạn.

Mặc định 3: Tối đa 3 phiên Chrome cùng truy cập một URL.

GEOLOCATION_RANDOM_RADIUS_KM:

Khi geolocation được bật, vị trí thực tế được randomize trong bán kính này.

Mặc định 2.0 km: Vị trí có thể lệch tối đa 2km so với vị trí proxy.

Tạo sự đa dạng trong geolocation data.

FAKE_SUCCESS:

Chỉ dùng để test. Khi true, task được đánh dấu thành công mà không thực sự thực thi.

FAKE_SUCCESS_RATIO: Tỷ lệ task được fake thành công (0.5 = 50%).

Không bao giờ bật trong production.

8. Nhóm Biến: Anti-Captcha

8.1. Danh Sách Biến

Biến	Kiểu	Mặc định	Mô tả
`CAPTCHA_SOLVING_ENABLED`	boolean	`true`	Bật/tắt toàn bộ module giải CAPTCHA
`CAPTCHA_FALLBACK_TO_MANUAL`	boolean	`true`	Fallback sang OpenAI Vision khi Anti-Captcha thất bại
`ANTICAPTCHA_API_KEY`	string	—	API key của anti-captcha.com
`ANTICAPTCHA_BASE_URL`	string	`https://api.anti-captcha.com`	Base URL của Anti-Captcha API
`ANTICAPTCHA_TIMEOUT`	number	`300000`	Timeout chờ giải CAPTCHA (ms) = 5 phút
`ANTICAPTCHA_RETRY_ATTEMPTS`	number	`3`	Số lần retry khi giải thất bại

8.2. Chi Tiết

CAPTCHA_SOLVING_ENABLED:

Khi false: Toàn bộ module CAPTCHA bị tắt. Tasks gặp CAPTCHA sẽ thất bại.

Khi true: Hệ thống tự động phát hiện và giải CAPTCHA.

CAPTCHA_FALLBACK_TO_MANUAL:

Khi true: Nếu Anti-Captcha API thất bại, thử OpenAI Vision.

Khi false: Chỉ dùng Anti-Captcha API, không fallback.

Nên bật trong production để tăng tỷ lệ thành công.

ANTICAPTCHA_API_KEY:

API key của tài khoản anti-captcha.com.

Dịch vụ tính phí theo số lần giải.

Cần theo dõi số dư tài khoản để tránh gián đoạn.

Không bao giờ commit key thật vào Git.

ANTICAPTCHA_TIMEOUT:

Thời gian tối đa chờ Anti-Captcha API trả về token.

Mặc định 300000ms = 5 phút.

Nếu vượt quá timeout, task được đánh dấu thất bại.

9. Nhóm Biến: OpenAI

9.1. Danh Sách Biến

Biến	Kiểu	Mặc định	Mô tả
`CHATGPT_API_KEY`	string	—	OpenAI API key (alias chính)
`OPENAI_API_KEY`	string	Fallback về `CHATGPT_API_KEY`	OpenAI API key (alias phụ)
`CHATGPT_MODEL`	string	`gpt-4o-mini`	Model mặc định (alias chính)
`OPENAI_MODEL`	string	Fallback về `CHATGPT_MODEL`	Model mặc định (alias phụ)

9.2. Chi Tiết

CHATGPT_API_KEY / OPENAI_API_KEY:

Cả hai đều được đọc, ưu tiên CHATGPT_API_KEY.

Dùng cho hai mục đích: tạo nội dung báo cáo và giải CAPTCHA bằng Vision.

Tính phí theo số tokens.

Không bao giờ commit key thật vào Git.

CHATGPT_MODEL / OPENAI_MODEL:

Model mặc định: gpt-4o-mini.

gpt-4o-mini được chọn vì cân bằng giữa chi phí và chất lượng.

Có thể override per-platform từ cấu hình trên Go API.

Không nên dùng gpt-4o vì chi phí cao hơn nhiều.

10. Nhóm Biến: Lưu Trữ Ảnh

10.1. DigitalOcean Spaces (Primary)

Biến	Mô tả
`DIGITAL_OCEAN_BUCKET_NAME`	Tên bucket, ví dụ `tools-greeting1073`
`DIGITAL_OCEAN_REGION`	Region: `sgp1` (Singapore)
`DIGITAL_OCEAN_ACCESS_KEY_ID`	Access Key ID
`DIGITAL_OCEAN_SECRET_ACCESS_KEY`	Secret Access Key
`DIGITAL_OCEAN_ENDPOINT`	Endpoint: `https://sgp1.digitaloceanspaces.com`
`DIGITAL_OCEAN_CDN_URL`	CDN URL: `https://tools-greeting1073.sgp1.cdn.digitaloceanspaces.com`

10.2. Cloudinary (Fallback)

Biến	Mô tả
`CLOUDINARY_CLOUD_NAME`	Cloud name
`CLOUDINARY_API_KEY`	API Key
`CLOUDINARY_API_SECRET`	API Secret
`CLOUDINARY_UPLOAD_PRESET`	Upload preset

10.3. Chiến Lược Upload

Hệ thống thử upload theo thứ tự:

Thử DigitalOcean Spaces trước.

Nếu thất bại, thử Cloudinary.

Nếu cả hai thất bại, lưu local trong storage/screenshots/.

URL ảnh được gửi về Go API qua webhook. Nếu lưu local, URL sẽ là đường dẫn local và không accessible từ bên ngoài.

11. Nhóm Biến: Email SMTP

11.1. Danh Sách Biến

Biến	Kiểu	Mặc định	Mô tả
`SMTP_HOST`	string	`smtp.gmail.com`	SMTP server hostname
`SMTP_PORT`	string	`587`	SMTP port
`SMTP_SECURE`	string	`false`	Dùng SSL/TLS (`true`) hay STARTTLS (`false`)
`SMTP_USER`	string	—	Email address
`SMTP_PASS`	string	—	App password (không phải mật khẩu Gmail thường)

11.2. Cấu Hình Gmail

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

Bật 2-Step Verification trên tài khoản Google.

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

Tạo App Password cho "Mail" và "Other device".

Dùng App Password này cho SMTP_PASS.

Cấu hình Gmail chuẩn:

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your-email@gmail.com
SMTP_PASS=xxxx xxxx xxxx xxxx

11.3. Cấu Hình Với SMTP Khác

Với các SMTP server khác (SendGrid, Mailgun, v.v.):

SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=apikey
SMTP_PASS=SG.your-sendgrid-api-key

12. Nhóm Biến: ZingProxy

12.1. Danh Sách Biến

Biến	Kiểu	Mặc định	Mô tả
`ZING_PROXY_API_KEY`	string	JWT token mặc định	API key của ZingProxy
`ZING_PROXY_BASE_URL`	string	`https://api.zingproxy.com/proxy`	Base URL của ZingProxy API

12.2. Chi Tiết

ZingProxy là nhà cung cấp proxy chính. API key là JWT token với thời hạn sử dụng. Cần cập nhật khi token hết hạn.

ZING_PROXY_BASE_URL là endpoint để lấy proxy mới từ ZingProxy. Được dùng bởi zing-proxy.service.ts.

13. Nhóm Biến: Logging

13.1. Danh Sách Biến

Biến	Kiểu	Mặc định	Mô tả
`LOG_LEVEL`	string	`info`	Mức log: `debug`, `info`, `warn`, `error`
`LOG_SERVICE`	string	`app`	Tên service mặc định trong log
`LOG_TIMESTAMP`	boolean	`false`	Thêm timestamp vào log
`LOG_COLORIZED`	boolean	`false`	Tô màu log trong console
`LOG_WRITE_TO_FILE`	boolean	`false`	Ghi log ra file
`LOG_WRITE_TO_CONSOLE`	boolean	`false`	In log ra console
`LOG_DIR`	string	`storage/log`	Thư mục lưu log files
`LOG_FOR_RECORD`	boolean	`false`	Ghi log chi tiết cho audit
`ENABLE_SCREENSHOTS`	string	`true`	Bật/tắt chụp màn hình bằng chứng

13.2. Cấu Hình Khuyến Nghị

Development:

LOG_LEVEL=debug
LOG_COLORIZED=true
LOG_WRITE_TO_FILE=true
LOG_WRITE_TO_CONSOLE=true
LOG_TIMESTAMP=true
LOG_FOR_RECORD=true

Production:

LOG_LEVEL=info
LOG_COLORIZED=false
LOG_WRITE_TO_FILE=true
LOG_WRITE_TO_CONSOLE=true
LOG_TIMESTAMP=true
LOG_FOR_RECORD=true

13.3. Log Level Ảnh Hưởng

debug: Log tất cả, bao gồm cursor coordinates, network calls. Rất verbose.

info: Log các sự kiện quan trọng: task start/complete, proxy rotation.

warn: Log cảnh báo: proxy chậm, retry attempts.

error: Chỉ log lỗi nghiêm trọng.

Trong production, dùng info để tránh log quá nhiều làm đầy disk.

14. So Sánh Cấu Hình Theo Môi Trường

14.1. Bảng So Sánh Đầy Đủ

Biến	Development	Staging	Production
`NODE_ENV`	`development`	`production`	`production`
`DEBUG`	`true`	`false`	`false`
`PORT`	`3005`	`3005`	`3005`
`API_HOST`	`http://localhost:33001`	URL staging	URL production
`SERVER_ID`	IP máy dev	IP server staging	IP server production
`CRON_TASK_LIMIT`	25 (hardcode)	25 (hardcode)	25 (hardcode)
`BROWSER_LIMIT_PER_PROCESS`	1 (forced)	Theo RAM server	Theo RAM server
`TASK_RETRY_LIMIT`	Unlimited	`8`	`8`
`PROXY_RETRY_LIMIT`	Unlimited	`15`	`15`
`LOG_LEVEL`	`debug`	`info`	`info`
`LOG_COLORIZED`	`true`	`false`	`false`
`CAPTCHA_SOLVING_ENABLED`	`true`	`true`	`true`
`CAPTCHA_FALLBACK_TO_MANUAL`	`false`	`true`	`true`
`DB_MONGO_HOST`	`localhost`	Container name	Container name

14.2. Biến Chỉ Khác Nhau Giữa Môi Trường

Các biến sau cần thay đổi khi chuyển môi trường:

NODE_ENV: Ảnh hưởng đến isLocal flag và nhiều behaviors.

API_HOST: URL của Go API Backend tương ứng.

SERVER_ID: Phải là IP hoặc identifier duy nhất của server.

DB_MONGO_HOST: localhost khi dev, container name khi trong Docker.

IP_ALLOWED: Danh sách IP được phép gọi API.

BROWSER_LIMIT_PER_PROCESS: Tùy theo RAM của server.

15. Dockerfile Và Build

15.1. Development Dockerfile — `.docker/dev/Dockerfile`

Dockerfile development:

Dùng oven/bun:latest làm base image.

Cài đặt Google Chrome thực (không phải Chromium).

Copy toàn bộ source code vào container.

Chạy với hot-reload (bun run dev).

15.2. Production Build

Production không dùng Dockerfile trong .docker/dev/. Thay vào đó, CI/CD pipeline build image riêng trên Bastion Build Server và push lên AWS ECR.

Quy trình build production:

Bastion Build Server pull code từ GitLab.

Build Docker image với docker buildx build.

Push image lên AWS ECR với tag latest và commit hash.

Các server Vnetwork pull image từ ECR và chạy.

15.3. Biến Môi Trường Trong Docker

Khi chạy trong Docker, biến môi trường được truyền qua:

env_file: .env trong docker-compose.yml.

Hoặc environment: section trong docker-compose.yml.

Hoặc -e VAR=value khi chạy docker run.

Trong production, biến môi trường được lưu trong file .env trên server và mount vào container.

16. Bảo Mật Biến Môi Trường

16.1. Biến Cần Bảo Vệ Đặc Biệt

Các biến sau chứa credentials nhạy cảm, không bao giờ được commit vào Git hoặc log ra console:

API_KEY: Token xác thực với Go API.

WEBHOOK_API_KEY: Token xác thực webhook.

ANTICAPTCHA_API_KEY: API key Anti-Captcha (tính phí).

CHATGPT_API_KEY / OPENAI_API_KEY: OpenAI API key (tính phí).

DIGITAL_OCEAN_SECRET_ACCESS_KEY: AWS-compatible secret key.

CLOUDINARY_API_SECRET: Cloudinary secret.

SMTP_PASS: Gmail App Password.

ZING_PROXY_API_KEY: ZingProxy JWT token.

DB_MONGO_PASSWORD: MongoDB password.

16.2. Quy Tắc Bảo Mật

File .env phải có trong .gitignore.

Không bao giờ hardcode credentials trong code.

Trong CI/CD, dùng GitLab CI/CD Variables (Protected) để lưu credentials.

Rotate API keys định kỳ hoặc khi nghi ngờ bị lộ.

Dùng App Password cho Gmail thay vì mật khẩu thường.

Giới hạn quyền của API keys (chỉ cấp quyền cần thiết).

16.3. Kiểm Tra `.gitignore`

File .gitignore phải bao gồm:

.env
.env.backup
storage/
tmp/
dist/
node_modules/

16.4. Xử Lý Khi Credentials Bị Lộ

Nếu phát hiện credentials bị lộ:

Revoke API key ngay lập tức trên dashboard của dịch vụ.

Tạo API key mới.

Cập nhật .env trên tất cả servers.

Restart workers để load credentials mới.

Kiểm tra logs để xem có hoạt động bất thường không.

17. Kiểm Tra Cấu Hình

17.1. Kiểm Tra Sau Khi Setup

Sau khi cấu hình .env, kiểm tra theo thứ tự:

Bước 1 — Kiểm tra server khởi động:

Bước 2 — Kiểm tra health:

Bước 3 — Kiểm tra kết nối Go API:

Bước 4 — Kiểm tra cấu hình (development only):

17.2. Dấu Hiệu Cấu Hình Sai

Server không khởi động: Kiểm tra PORT có bị chiếm không.

"Cannot connect to MongoDB": Kiểm tra DB_MONGO_HOST, DB_MONGO_PORT, credentials.

Tasks không được nhận: Kiểm tra API_HOST, API_KEY.

Webhook thất bại: Kiểm tra WEBHOOK_API_KEY, IP_ALLOWED.

CAPTCHA không giải được: Kiểm tra ANTICAPTCHA_API_KEY, số dư tài khoản.

Screenshot không upload: Kiểm tra DigitalOcean credentials.

Email không gửi được: Kiểm tra SMTP credentials, App Password.

17.3. Xem Cấu Hình Hiện Tại

Trong development, có thể xem toàn bộ cấu hình đang dùng:

Trong production, không bao giờ expose env qua API. Header Show-Env: true chỉ hoạt động khi NODE_ENV=development.

18. Template `.env` Đầy Đủ

Dưới đây là template .env đầy đủ với tất cả biến và giải thích:

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

# ============================================================
# AUTHENTICATION
# ============================================================
API_KEY='your-api-key-here'
WEBHOOK_API_KEY='your-webhook-key-here'
PROXY_API_KEY='your-proxy-api-key-here'
IP_ALLOWED=127.0.0.1,11.0.3.11

# ============================================================
# GO API BACKEND
# ============================================================
API_HOST=http://localhost:33001

# ============================================================
# MONGODB
# ============================================================
DB_MONGO_HOST=localhost
DB_MONGO_PORT=27017
DB_MONGO_USERNAME=root
DB_MONGO_PASSWORD=PwDev123
DB_MONGO_DATABASE=tool-traffic-tools

# ============================================================
# BROWSER LIMITS (CRON_TASK_LIMIT hardcoded = 25)
# ============================================================
BROWSER_LIMIT_PER_PROCESS=1

# ============================================================
# TRAFFIC CONTROL
# ============================================================
TASK_RETRY_LIMIT=8
PROXY_RETRY_LIMIT=15
KILL_TRAFFIC_RATIO=0.8
HOME_TRAFFIC_RATIO=0.25
HOME_TRAFFIC_PER_TARGET_LIMIT=3
HOME_TRAFFIC_LIMIT=2
ENABLE_GEOLOCATION=true
GEOLOCATION_RANDOM_RADIUS_KM=2.0
MODE=browser
ENABLE_ADS_RELATIONS=false

# ============================================================
# 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 (PRIMARY STORAGE)
# ============================================================
DIGITAL_OCEAN_BUCKET_NAME=your-bucket-name
DIGITAL_OCEAN_REGION=sgp1
DIGITAL_OCEAN_ACCESS_KEY_ID=your-access-key
DIGITAL_OCEAN_SECRET_ACCESS_KEY=your-secret-key
DIGITAL_OCEAN_ENDPOINT=https://sgp1.digitaloceanspaces.com
DIGITAL_OCEAN_CDN_URL=https://your-bucket.sgp1.cdn.digitaloceanspaces.com

# ============================================================
# CLOUDINARY (FALLBACK STORAGE)
# ============================================================
CLOUDINARY_CLOUD_NAME=your-cloud-name
CLOUDINARY_API_KEY=your-api-key
CLOUDINARY_API_SECRET=your-api-secret
CLOUDINARY_UPLOAD_PRESET=ml_default

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

# ============================================================
# ZING PROXY
# ============================================================
ZING_PROXY_API_KEY=your-zing-proxy-jwt-token
ZING_PROXY_BASE_URL=https://api.zingproxy.com/proxy

# ============================================================
# LOGGING
# ============================================================
LOG_LEVEL=info
LOG_SERVICE=app
LOG_TIMESTAMP=true
LOG_COLORIZED=true
LOG_WRITE_TO_FILE=true
LOG_WRITE_TO_CONSOLE=true
LOG_DIR=storage/log
LOG_FOR_RECORD=true
ENABLE_SCREENSHOTS=true

Environment & Configuration

Cấu Hình Môi Trường — Tools V2 Worker Engine#

1. Tổng Quan#

1.1. Cơ Chế Đọc Cấu Hình#

1.2. Phân Biệt Development Và Production#

1.3. Biến Hardcode Trong Code#

1.4. File .env Và .env.example#

2. Nhóm Biến: Server#

2.1. Danh Sách Biến#

2.2. Chi Tiết Từng Biến#

3. Nhóm Biến: Xác Thực API#

3.1. Danh Sách Biến#

3.2. Chi Tiết Từng Biến#

4. Nhóm Biến: Kết Nối Go API Backend#

4.1. Danh Sách Biến#

4.2. Chi Tiết#

5. Nhóm Biến: MongoDB#

5.1. Danh Sách Biến#

5.2. MongoDB URI Tự Động#

5.3. Cấu Hình Theo Môi Trường#

5.4. Docker Compose MongoDB#

6. Nhóm Biến: Giới Hạn Browser Và Cron#

6.1. Danh Sách Biến#

6.2. Lưu Ý Quan Trọng#

6.3. Tính Toán Giới Hạn Browser#

7. Nhóm Biến: Traffic Control#

7.1. Danh Sách Biến#

7.2. Chi Tiết Biến Quan Trọng#

8. Nhóm Biến: Anti-Captcha#

8.1. Danh Sách Biến#

8.2. Chi Tiết#

9. Nhóm Biến: OpenAI#

9.1. Danh Sách Biến#

9.2. Chi Tiết#

10. Nhóm Biến: Lưu Trữ Ảnh#

10.1. DigitalOcean Spaces (Primary)#

10.2. Cloudinary (Fallback)#

10.3. Chiến Lược Upload#

11. Nhóm Biến: Email SMTP#

11.1. Danh Sách Biến#

11.2. Cấu Hình Gmail#

11.3. Cấu Hình Với SMTP Khác#

12. Nhóm Biến: ZingProxy#

12.1. Danh Sách Biến#

12.2. Chi Tiết#

13. Nhóm Biến: Logging#

13.1. Danh Sách Biến#

13.2. Cấu Hình Khuyến Nghị#

13.3. Log Level Ảnh Hưởng#

14. So Sánh Cấu Hình Theo Môi Trường#

14.1. Bảng So Sánh Đầy Đủ#

14.2. Biến Chỉ Khác Nhau Giữa Môi Trường#

15. Dockerfile Và Build#

15.1. Development Dockerfile — .docker/dev/Dockerfile#

15.2. Production Build#

15.3. Biến Môi Trường Trong Docker#

16. Bảo Mật Biến Môi Trường#

16.1. Biến Cần Bảo Vệ Đặc Biệt#

16.2. Quy Tắc Bảo Mật#

16.3. Kiểm Tra .gitignore#

16.4. Xử Lý Khi Credentials Bị Lộ#

17. Kiểm Tra Cấu Hình#

17.1. Kiểm Tra Sau Khi Setup#

17.2. Dấu Hiệu Cấu Hình Sai#

17.3. Xem Cấu Hình Hiện Tại#

18. Template .env Đầy Đủ#