Tài Liệu Cấu Hình Môi Trường — API Backend Traffic Tools V2

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

API Backend sử dụng thư viện spf13/viper để đọc file .env vào struct EnvStruct được định nghĩa trong pkg/env.go. Toàn bộ cấu hình được typed — mỗi biến có kiểu dữ liệu Go cụ thể (string, int, bool, time.Duration) thay vì string thô.

Quy trình nạp khi khởi động:

Viper đọc file .env ở thư mục gốc dự án.

Map giá trị vào EnvStruct theo tag mapstructure.

pkg.Env là biến global duy nhất lưu giữ toàn bộ cấu hình.

Toàn bộ module import pkg.Env để đọc cấu hình, không đọc os.Getenv trực tiếp.

Nếu không tìm thấy file .env, Viper tự động đọc từ biến môi trường hệ thống.

2. Danh Sách Đầy Đủ Biến Môi Trường

2.1. Cấu Hình Ứng Dụng

Biến	Kiểu	Giá Trị Mặc Định	Ý Nghĩa
`APP_MODE`	string	`development`	Chế độ chạy: `development`, `production`. Ảnh hưởng đến CORS, log level và các tính năng debug.
`SERVER_PORT`	string	`33003`	Cổng HTTP server lắng nghe.
`AUTO_MIGRATE_DATABASE`	bool	`false`	Nếu `true`, GORM tự động migrate schema MySQL khi khởi động. Chỉ bật ở Dev.
`API_KEY`	string	—	Key xác thực cho các request không JWT (internal service calls).

2.2. Cơ Sở Dữ Liệu MySQL

Biến	Giá Trị Dev	Giá Trị Production	Ý Nghĩa
`DB_MYSQL_HOST`	`traffic_tool_mysql`	IP máy chủ MySQL production	Hostname của MySQL server
`DB_MYSQL_PORT`	`3306`	`3306`	Cổng MySQL
`DB_MYSQL_USER`	`root`	Tài khoản có quyền hạn chế	Username kết nối
`DB_MYSQL_PASS`	`PwDev123`	Mật khẩu phức tạp	Mật khẩu MySQL
`DB_MYSQL_NAME`	`tool_traffic_api`	`tool_traffic_api`	Tên database

Lưu ý production: Không dùng root — tạo user riêng với quyền chỉ SELECT, INSERT, UPDATE, DELETE trên database tool_traffic_api.

2.3. Cơ Sở Dữ Liệu MongoDB

Biến	Giá Trị Dev	Giá Trị Production	Ý Nghĩa
`DB_MONGO_HOST`	`traffic_tool_mongodb`	IP máy chủ MongoDB	Hostname của MongoDB server
`DB_MONGO_PORT`	`27017`	`27017`	Cổng MongoDB
`DB_MONGO_USER`	`root`	Tài khoản không phải root	Username
`DB_MONGO_PASS`	`PwDev123`	Mật khẩu phức tạp	Mật khẩu MongoDB
`DB_MONGO_NAME`	`tool-traffic-api`	`tool-traffic-api`	Tên database MongoDB

2.4. Redis

Biến	Giá Trị Dev	Ý Nghĩa
`REDIS_HOST`	`traffic_tool_redis`	Hostname Redis
`REDIS_PORT`	`6379`	Cổng Redis
`REDIS_USER`	(trống)	Username nếu Redis có auth
`REDIS_PASS`	(trống)	Mật khẩu Redis
`REDIS_DB`	`0`	Database index trong Redis (0-15)

2.5. Bảo Mật Và Xác Thực

Biến	Ý Nghĩa
`JWT_SECRET`	Secret key ký/verify JWT token. Tuyệt đối không dùng giá trị mặc định ở Production.
`WEBHOOK_SECKET_KEY`	Key xác thực webhook từ nội bộ.
`WEBHOOK_KEY`	Key 64 ký tự hex, dùng cho xác thực webhook calls.
`WHITE_LIST_IP_TOOL_TRAFFIC`	Comma-separated list các IP worker được phép gọi `/api/task/request`. Ví dụ: `127.0.0.1,10.0.0.5`.

2.6. Cấu Hình Session

Biến	Kiểu	Giá Trị Mặc Định	Ý Nghĩa
`SESSION_TIMEOUT`	time.Duration	`1h`	Thời gian session hết hạn sau lần hoạt động cuối.
`DISABLE_SESSION_TIMEOUT`	bool	`false`	Tắt kiểm tra session timeout (chỉ dùng trong development).
`DEV_SESSION_TIMEOUT`	time.Duration	`24h`	Session timeout kéo dài cho development khi `DISABLE_SESSION_TIMEOUT=true`.
`DISABLE_2FA`	bool	`false`	Tắt xác thực 2FA (chỉ dùng trong development).

2.7. Cấu Hình Cron Job

Mỗi biến chứa một biểu thức cron (chuẩn 5-field):

Biến	Biểu Thức Mặc Định	Tần Suất
`SCHEDULE_RESET_TASK`	`/10 * * *`	Mỗi 10 phút: reset task bị kẹt
`SCHEDULE_SEND_TASK`	`* * * * *`	Mỗi phút: giao task mới đến server
`SCHEDULE_REPORT_TRAFFIC`	`0 2-22/2 * * *`	Mỗi 2 giờ từ 2h-22h: tổng hợp báo cáo
`SCHEDULE_REPORT_TRAFFIC_EXTRA`	`59 23 * * *`	23:59 mỗi ngày: báo cáo cuối ngày
`SCHEDULE_SERVER_HOURLY_REPORT`	`0 * * * *`	Mỗi đầu giờ: báo cáo tình trạng server
`SCHEDULE_SEARCH_KEYWORD`	`/30 * * *`	Mỗi 30 phút: kiểm tra thứ hạng từ khóa
`SCHEDULE_CONFIRM_FIRE`	`/30 * * *`	Mỗi 30 phút: xác nhận tác vụ hoàn thành
`SCHEDULE_CHANGE_ACTIVE_PROXY`	Theo cấu hình	Kích hoạt/vô hiệu hóa proxy theo lịch
`SCHEDULE_CHECK_PROJECT_DEAD`	Theo cấu hình	Phát hiện project không còn hoạt động
`MATTERMOST_SCHEDULE`	`0 0 9 * * *`	9:00 sáng hàng ngày: báo cáo Mattermost

2.8. Cấu Hình Webhook

Biến	Ý Nghĩa
`WEBHOOK_HOST`	Base URL của chính API server này. Tools_v2 dùng để gọi lại webhook. Ví dụ: `http://traffic_tool_api:33003`.
`WEBHOOK_TASK_UPDATE_STATUS_URL`	URL admin update trạng thái task: `{WEBHOOK_HOST}/webhook/task/update-status`.
`WEBHOOK_PROXY_GET_PROXY_URL`	URL lấy proxy: `{WEBHOOK_HOST}/webhook/proxy/get-proxy`.
`WEBHOOK_SEARCH_KEYWORD_URL`	URL nhận kết quả từ khóa: `{WEBHOOK_HOST}/webhook/keyword-result`.
`WEBHOOK_URL`	URL cập nhật tiến trình: `{WEBHOOK_HOST}/webhook/task/update-process`.
`WEBHOOK_CHECK_PROXY_ALIVE_URL`	URL kiểm tra IP còn sống: `https://api.ipify.org/`.

2.9. Cấu Hình Proxy

Biến	Kiểu	Ý Nghĩa
`PROXY_USE_MAX`	int	Số lần tối đa một IP proxy được phép dùng trước khi bị thay thế. Mặc định: 1.
`PROXY_ROTATE_MAX_CONCURRENT`	int	Số goroutine đồng thời tối đa được phép xoay IP.
`LIMIT_SEND_TASK_PER_SERVER`	int	Số tác vụ tối đa giao cho mỗi server worker trong một chu kỳ cron. Mặc định: 300.

2.10. Cấu Hình Traffic Pool

Giới hạn số lượng traffic theo từng loại mỗi ngày:

Biến	Giá Trị Mặc Định	Ý Nghĩa
`TRAFFIC_GG_ADS`	`100`	Giới hạn traffic Google Ads click
`TRAFFIC_CC_ADS`	`100000`	Giới hạn traffic CocCoc Ads click
`TRAFFIC_KILL`	`750000`	Giới hạn traffic Negative SEO (Kill)
`TRAFFIC_HOME`	`5000`	Giới hạn traffic truy cập trang chủ
`TRAFFIC_NORMAL_CLICK`	`100000`	Giới hạn traffic click tự nhiên

2.11. Telegram Bot

Biến	Ý Nghĩa
`TELEGRAM_BOT_TOKEN`	Token của Telegram bot (từ BotFather).
`TELEGRAM_CHAT_ID`	Chat ID nhận thông báo chung.
`TELEGRAM_CHAT_REPORT_ID`	Chat ID nhận báo cáo định kỳ.
`TELEGRAM_CHAT_ERROR_ID`	Chat ID nhận cảnh báo lỗi hệ thống.
`ENABLE_PUSH_MESSAGE_ERROR_TO_TELEGRAM`	bool — Bật/tắt gửi lỗi lên Telegram.
`ENABLE_TELEGRAM_REPORT`	bool — Bật/tắt gửi báo cáo định kỳ lên Telegram.

2.12. Mattermost

Biến	Giá Trị Mặc Định	Ý Nghĩa
`MATTERMOST_API_URL`	`https://chat.nospace.network`	URL Mattermost server
`MATTERMOST_API_TOKEN`	—	Token xác thực Mattermost
`MATTERMOST_CHANNEL_ID`	—	ID kênh nhận thông báo
`MATTERMOST_VERIFY_SSL`	`true`	Xác minh SSL certificate
`MATTERMOST_TIMEOUT`	—	Timeout kết nối (giây)
`MATTERMOST_CONNECT_TIMEOUT`	—	Timeout kết nối ban đầu (giây)
`MATTERMOST_SCHEDULE`	`0 0 9 * * *`	Lịch gửi báo cáo (9:00 sáng hàng ngày)

2.13. Tích Hợp Scan Domain

Biến	Ý Nghĩa
`PROXY_SCAN_DOMAIN_URL`	Endpoint dịch vụ proxy scan để kiểm tra IP bị chặn theo domain.
`API_SCAN_DOMAIN_URL`	API ngoài kiểm tra tình trạng domain.
`API_ACCESS_TOKEN`	Token xác thực cho API scan domain.

2.14. DigitalOcean Spaces

Biến	Ý Nghĩa
`DIGITALOCEAN_ACCESS_KEY`	Access key cho DigitalOcean Spaces
`DIGITALOCEAN_SECRET_KEY`	Secret key cho DigitalOcean Spaces
`DIGITALOCEAN_REGION`	Region của bucket (ví dụ: `sgp1`)
`DIGITALOCEAN_BUCKET_NAME`	Tên bucket lưu trữ file
`DIGITALOCEAN_ENDPOINT`	Endpoint URL của DigitalOcean Spaces
`DIGITALOCEAN_CDN_URL`	URL CDN để truy cập file đã upload

2.15. Proxy Provider Credentials

Biến	Ý Nghĩa
`PROXY_XOAY_USERNAME`	Username cho dịch vụ ProxyXoay
`PROXY_XOAY_PASSWORD`	Password cho dịch vụ ProxyXoay
`ENODE_PROXY_TOKEN`	Token cho dịch vụ Enode Proxy
`ZING_PROXY_TOKEN`	Token cho dịch vụ Zing Proxy
`M2_PROXY_TOKEN`	Token cho dịch vụ M2 Proxy

3. File .env.example — Template Chuẩn

File .env.example được commit vào Git như một tài liệu sống về tất cả biến cần thiết. Developer mới clone dự án sẽ copy file này và điền giá trị cục bộ:

Quy tắc với .env trong dự án này:

.env — Không bao giờ commit. Chứa giá trị thực.

.env.example — Luôn commit. Chứa cấu trúc và ghi chú.

.env.original — Bản lưu trữ cấu hình gốc, không dùng trực tiếp.

4. Cấu Hình Docker Compose

File docker-compose.yaml khởi động toàn bộ hạ tầng cục bộ:

Tên hostname trong .env trùng với tên service Docker Compose để kết nối nội bộ qua Docker network. Khi chạy local không qua Docker, thay hostname bằng localhost và port tương ứng.

Lệnh khởi động:

5. Cấu Hình .air.toml — Hot Reload

File .air.toml cấu hình Air để tự động reload khi code thay đổi:

[build]
  cmd = "go build -o ./tmp/main ./cmd/main.go"
  bin = "./tmp/main"
  include_ext = ["go"]
  exclude_dir = ["logs", "tmp", "testdata", "mysql-data"]
  delay = 500  # ms chờ trước khi rebuild

Khi lưu file .go, Air tự động rebuild và restart server trong vòng 500ms.

6. Lưu Ý Bảo Mật Cho Production

JWT_SECRET: Phải là chuỗi ngẫu nhiên tối thiểu 32 ký tự. Không dùng secret-key mặc định.

WEBHOOK_KEY: Phải là chuỗi 64 ký tự hex ngẫu nhiên. Không dùng key trong .env.example.

Database passwords: Phải đặt mật khẩu mạnh, khác hoàn toàn Dev.

WHITE_LIST_IP_TOOL_TRAFFIC: Chỉ thêm IP của các server worker thực tế, không thêm 0.0.0.0.

ENABLE_PUSH_MESSAGE_ERROR_TO_TELEGRAM: Đặt true ở Production để nhận cảnh báo lỗi kịp thời.

AUTO_MIGRATE_DATABASE: Đặt false ở Production. Migration phải được review và chạy thủ công.

DISABLE_2FA: Luôn false ở Production. Chỉ dùng true trong development.

DISABLE_SESSION_TIMEOUT: Luôn false ở Production.

7. Giá Trị Mặc Định Tự Động

Hàm LoadEnv() tự động đặt giá trị mặc định cho một số biến nếu không được cấu hình:

8. Cấu Hình Môi Trường Development Vs Production

Tính Năng	Development	Production
CORS	`AllowOrigins = "*"`	Chỉ các origin cụ thể
2FA	Tắt (`DISABLE_2FA=true`)	Bật bắt buộc
Session Timeout	24 giờ	1 giờ (cấu hình qua `SESSION_TIMEOUT`)
Auto Migrate	Bật (`AUTO_MIGRATE_DATABASE=true`)	Tắt
Log Level	Debug + Info	Info + Error
Route Print	Bật (`EnablePrintRoutes=true`)	Tắt
Telegram Error	Tùy chọn	Bật bắt buộc

9. Cấu Hình Kết Nối Database Chi Tiết

9.1. MySQL Connection String

GORM tạo connection string theo format:

{user}:{password}@tcp({host}:{port})/{dbname}?charset=utf8mb4&parseTime=True&loc=Local

Ví dụ development:

root:PwDev123@tcp(localhost:33022)/tool_traffic_api?charset=utf8mb4&parseTime=True&loc=Local

Tham số quan trọng:

charset=utf8mb4 — Hỗ trợ đầy đủ Unicode bao gồm emoji.

parseTime=True — Tự động parse DATETIME MySQL thành time.Time Go.

loc=Local — Sử dụng múi giờ local của server (Asia/Ho_Chi_Minh).

9.2. MongoDB Connection String

mongodb://{user}:{password}@{host}:{port}/{dbname}?authSource=admin

Ví dụ development:

mongodb://root:PwDev123@localhost:33021/tool-traffic-api?authSource=admin

9.3. Redis Connection

10. Cấu Hình Connection Pool

10.1. MySQL Connection Pool

GORM sử dụng database/sql connection pool bên dưới. Cấu hình trong pkg/database/mysql_pool.go:

10.2. MongoDB Connection Pool

MongoDB driver tự quản lý connection pool. Cấu hình trong pkg/database/mongo_pool.go:

11. Cấu Hình Fiber Server

Fiber được khởi tạo với các tham số sau trong cmd/main.go:

EnablePrintRoutes — In danh sách tất cả routes khi khởi động (chỉ development).

ReadTimeout — Thời gian tối đa để đọc toàn bộ request body.

WriteTimeout — Thời gian tối đa để ghi response.

IdleTimeout — Thời gian tối đa giữ kết nối idle (keep-alive).

12. Cấu Hình Log Rotation

Log rotation được cấu hình trong cmd/main.go sử dụng lumberjack:

Log được ghi đồng thời vào cả stdout và file thông qua io.MultiWriter:

13. Cấu Hình Static Files

API phục vụ file tĩnh từ thư mục public/:

Thư mục public/import_excel/ chứa file Excel mẫu để import proxy (proxy.xlsx). Người dùng có thể tải về qua GET /public/import_excel/proxy.xlsx.

14. Cấu Hình Middleware Timeout

pkg/middleware/timeout.go định nghĩa timeout mặc định cho request processing:

Middleware này được áp dụng toàn cục để ngăn các request xử lý quá lâu làm nghẽn goroutine pool. Các endpoint đặc biệt như /api/proxy/import-all có timeout riêng được xử lý ở tầng service.

15. Cấu Hình Webhook Middleware

pkg/middleware/webhook_middleware.go xác thực các request đến webhook endpoints:

Worker phải gửi header X-Webhook-Key: {WEBHOOK_KEY} với mọi request đến webhook endpoints. Giá trị WEBHOOK_KEY phải khớp với giá trị trong .env của API server.

16. Cấu Hình IP Whitelist

pkg/middleware/validate_ip.go kiểm tra IP của request đến các endpoint nhạy cảm:

Biến WHITE_LIST_IP_TOOL_TRAFFIC trong .env chứa danh sách IP được phép, phân cách bằng dấu phẩy. Viper tự động parse thành []string khi load cấu hình.

Environment & Configuration

Tài Liệu Cấu Hình Môi Trường — API Backend Traffic Tools V2#

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

2. Danh Sách Đầy Đủ Biến Môi Trường#

2.1. Cấu Hình Ứng Dụng#

2.2. Cơ Sở Dữ Liệu MySQL#

2.3. Cơ Sở Dữ Liệu MongoDB#

2.4. Redis#

2.5. Bảo Mật Và Xác Thực#

2.6. Cấu Hình Session#

2.7. Cấu Hình Cron Job#

2.8. Cấu Hình Webhook#

2.9. Cấu Hình Proxy#

2.10. Cấu Hình Traffic Pool#

2.11. Telegram Bot#

2.12. Mattermost#

2.13. Tích Hợp Scan Domain#

2.14. DigitalOcean Spaces#

2.15. Proxy Provider Credentials#

3. File .env.example — Template Chuẩn#

4. Cấu Hình Docker Compose#

5. Cấu Hình .air.toml — Hot Reload#

6. Lưu Ý Bảo Mật Cho Production#

7. Giá Trị Mặc Định Tự Động#

8. Cấu Hình Môi Trường Development Vs Production#

9. Cấu Hình Kết Nối Database Chi Tiết#

9.1. MySQL Connection String#

9.2. MongoDB Connection String#

9.3. Redis Connection#

10. Cấu Hình Connection Pool#

10.1. MySQL Connection Pool#

10.2. MongoDB Connection Pool#

11. Cấu Hình Fiber Server#

12. Cấu Hình Log Rotation#

13. Cấu Hình Static Files#

14. Cấu Hình Middleware Timeout#

15. Cấu Hình Webhook Middleware#

16. Cấu Hình IP Whitelist#