Hướng Dẫn Cài Đặt — Go API Backend

Thư mục: api/ | Cổng mặc định: 33003 | Công nghệ: Go 1.22.4 + Fiber v2

Yêu cầu

Go >= 1.22.4

Docker >= 24.0 (để chạy MySQL, MongoDB, Redis)

Air (tùy chọn — để tự động reload khi sửa code)

Cài Go:

Cài Air (tự động reload khi sửa code):

Cài đặt

Bước 1: Cài dependencies

Lần đầu mất khoảng 1-2 phút để tải thư viện.

Bước 2: Khởi động cơ sở dữ liệu

API cần 3 cơ sở dữ liệu: MySQL, MongoDB và Redis. Tất cả đã được cấu hình sẵn trong docker-compose.yaml.

Kiểm tra 3 container đã chạy:

Đợi khoảng 15 giây để MySQL khởi động hoàn toàn trước khi tiếp tục.

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

Mở file .env và chỉnh sửa các giá trị sau (giữ nguyên các giá trị khác):

# Bật tự động tạo bảng database khi khởi động lần đầu
AUTO_MIGRATE_DATABASE=true

# Kết nối database
# Dùng localhost + cổng ánh xạ ra ngoài vì API chạy trực tiếp trên máy, không trong Docker
DB_MYSQL_HOST=localhost
DB_MYSQL_PORT=33022

DB_MONGO_HOST=localhost
DB_MONGO_PORT=33021

REDIS_HOST=localhost
REDIS_PORT=33023

# Webhook — API tự gọi lại chính mình để nhận kết quả từ Worker
WEBHOOK_HOST=http://localhost:33003
WEBHOOK_TASK_UPDATE_STATUS_URL=http://localhost:33003/webhook/task/update-status
WEBHOOK_PROXY_GET_PROXY_URL=http://localhost:33003/webhook/proxy/get-proxy
WEBHOOK_SEARCH_KEYWORD_URL=http://localhost:33003/webhook/keyword-result
WEBHOOK_URL=http://localhost:33003/webhook/task/update-process

# Tắt 2FA và session timeout khi phát triển để tiện đăng nhập
DISABLE_2FA=true
DISABLE_SESSION_TIMEOUT=true

Tại sao đổi cổng? File .env.example dùng cổng nội bộ Docker (3306, 27017, 6379). Khi API chạy trực tiếp trên máy (không trong Docker), phải dùng cổng được ánh xạ ra ngoài: MySQL → 33022, MongoDB → 33021, Redis → 33023.

Về API_KEY và WEBHOOK_KEY: Hai giá trị này đã có sẵn trong .env.example — giữ nguyên khi phát triển. Khi lên production, thay bằng giá trị ngẫu nhiên mạnh hơn. API_KEY phải khớp với API_KEY trong tools_v2/.env.

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

Kết quả mong đợi:

DEBUG: Loaded environment in development mode
[CRON] Starting RunCron - Initializing all cronjobs...
[CRON] Registered: SCHEDULE_SEND_TASK
[CRON] Registered: SCHEDULE_RESET_TASK
...
Server started on port 33003

Bước 5: Tạo tài khoản admin lần đầu

Sau khi API khởi động, tạo tài khoản để đăng nhập vào Dashboard:

Endpoint /api/user/register chỉ hoạt động khi APP_MODE=development.

Bước 6: Kiểm tra

Chạy toàn bộ trong Docker (API + database)

Dùng khi không muốn cài Go trực tiếp trên máy.

Trong .env, giữ nguyên các giá trị database mặc định (dùng tên service Docker):

DB_MYSQL_HOST=traffic_tool_mysql
DB_MYSQL_PORT=3306
DB_MONGO_HOST=traffic_tool_mongodb
DB_MONGO_PORT=27017
REDIS_HOST=traffic_tool_redis
REDIS_PORT=6379
AUTO_MIGRATE_DATABASE=true

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

Biến	Mô tả	Giá trị mặc định
`APP_MODE`	Chế độ chạy	`development`
`AUTO_MIGRATE_DATABASE`	Tự tạo bảng khi khởi động	`false` → đổi thành `true`
`SERVER_PORT`	Cổng API	`33003`
`API_KEY`	Key xác thực cho Tools V2	Có sẵn trong `.env.example`
`WEBHOOK_KEY`	Key xác thực webhook	Có sẵn trong `.env.example`
`JWT_SECRET`	Khóa ký JWT token	`secret-key` → đổi khi production
`DISABLE_2FA`	Tắt xác thực 2 lớp	`true` khi phát triển
`DISABLE_SESSION_TIMEOUT`	Tắt hết hạn phiên	`true` khi phát triển
`WHITE_LIST_IP_TOOL_TRAFFIC`	IP được phép gọi API từ Tools V2	`127.0.0.1,...`
`LIMIT_SEND_TASK_PER_SERVER`	Số task tối đa giao cho mỗi server	`30`

Xử lý sự cố

Lỗi: "dial tcp: connection refused" — không kết nối được database

Lỗi: "port 33003 already in use"

Lỗi: "Unknown database 'tool_traffic_api'"

Bảng database không được tạo

Kiểm tra AUTO_MIGRATE_DATABASE=true trong .env, sau đó khởi động lại API.

Tools V2 bị lỗi "401 Unauthorized" khi gọi API

API_KEY trong tools_v2/.env không khớp với API_KEY trong api/.env. Hai giá trị phải giống nhau chính xác.

Tools V2 bị lỗi "403 Forbidden" khi gửi webhook

IP của máy chạy Tools V2 chưa có trong WHITE_LIST_IP_TOOL_TRAFFIC:

WHITE_LIST_IP_TOOL_TRAFFIC=127.0.0.1,<IP_máy_chạy_Tools_V2>

Setup Guide

Hướng Dẫn Cài Đặt — Go API Backend#

Yêu cầu#

Cài đặt#

Bước 1: Cài dependencies#

Bước 2: Khởi động cơ sở dữ liệu#

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

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

Bước 5: Tạo tài khoản admin lần đầu#

Bước 6: Kiểm tra#

Chạy toàn bộ trong Docker (API + database)#

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

Xử lý sự cố#