TÀI LIỆU HƯỚNG DẪN CÀI ĐẶT VÀ SỬ DỤNG - FIVEM LAUNCHER BACKEND

Đây là tài liệu hướng dẫn cấu hình và triển khai chi tiết dành cho mã nguồn API Backend của FiveM Launcher. Mã nguồn được viết bằng ngôn ngữ Golang, sử dụng framework Fiber và hệ quản trị cơ sở dữ liệu MySQL.

---

1. YÊU CẦU HỆ THỐNG

Để có thể biên dịch và chạy được mã nguồn này, cá nhân hoặc hệ thống máy chủ của bạn cần phải được cài đặt các phần mềm sau:

• Go (Golang) phiên bản 1.20 trở lên.
• MySQL phiên bản 8.0 trở lên hoặc MariaDB phiên bản 10.4 trở lên.
• Git (nếu cần quản lý phiên bản mã nguồn).

---

2. CẤU HÌNH HỆ THỐNG VÀ BIẾN MÔI TRƯỜNG

Trước khi bắt đầu khởi chạy ứng dụng, bạn cần phải thiết lập tệp tin cấu hình biến môi trường.

1. Truy cập vào thư mục gốc của dự án.
2. Sao chép tệp tin cấu hình mẫu .env.example thành một tệp tin mới và đặt tên là .env.
3. Mở tệp tin .env bằng trình chỉnh sửa mã và cấu hình lại các thông số sau cho phù hợp với môi trường của bạn:

Hệ Quản Trị Cơ Sở Dữ Liệu (Database)

• DB_HOST: Địa chỉ IP hoặc tên miền của máy chủ MySQL (Thông thường là 127.0.0.1 đối với localhost).
• DB_PORT: Cổng của MySQL (Mặc định là 3306).
• DB_USER: Tên đăng nhập của tài khoản MySQL.
• DB_PASSWORD: Mật khẩu của tài khoản MySQL.
• DB_NAME: Tên cơ sở dữ liệu của bạn (Ví dụ: fivem_backend).

Lưu ý: Bạn phải tự tạo cơ sở dữ liệu trống với tên tương ứng trong ứng dụng MySQL trước khi chạy chương trình.

Bảo Mật (Security)

• JWT_SECRET: Chuỗi ký tự bí mật được sử dụng để ký xác thực token. Bạn bắt buộc phải thay đổi chuỗi ký tự này thành một chuỗi văn bản dài, ngẫu nhiên để đảm bảo an toàn an ninh mạng cho người dùng.

Dịch Vụ Gửi Email (Email Service)

• RESEND_API_KEY: Giấy phép API Key của dịch vụ gửi email Resend.com.
• EMAIL_FROM: Địa chỉ email người gửi hệ thống mặc định (Ví dụ: noreply@example.com).

---

3. HƯỚNG DẪN TRIỂN KHAI TRÊN HỆ ĐIỀU HÀNH LINUX

Các bước dưới đây hướng dẫn bạn cách biên dịch và chạy ứng dụng trên các bản phân phối Linux như Ubuntu hoặc Debian.

Bước 1: Tải các thư viện dự án

Mở terminal (giao diện dòng lệnh) tại thư mục chứa mã nguồn và thực thi lệnh:

go mod tidy

Bước 2: Biên dịch mã nguồn

Thực thi lệnh sau để biên dịch mã nguồn ra tệp tin thực thi phù hợp cho phần cứng cục bộ Linux (64-bit):

GOOS=linux GOARCH=amd64 go build -o backend-app ./cmd/server

Sau khi lệnh hoàn tất, hệ thống sẽ tự động tổng hợp ra một tệp tin mang tên backend-app.

Bước 3: Cấp quyền thực thi

Tiếp tục tại giao diện dòng lệnh, cấp quyền thực thi tệp tin cho hệ thống:

chmod +x backend-app

Bước 4: Khởi chạy ứng dụng

Bạn có thể dùng terminal để khởi chạy trực tiếp tệp tin hệ thống và theo dõi nhật ký:

./backend-app

Tuy nhiên, trong môi trường Production (Sản phẩm thực tế), việc sử dụng phần mềm quản lý tiến trình như systemd hoặc PM2 là rất cần thiết để ứng dụng có thể tự khởi động lại nếu bị lỗi hệ thống.

Ví dụ cách khởi động thông qua ứng dụng PM2:

pm2 start ./backend-app --name "fivem-backend"
pm2 save

---

4. HƯỚNG DẪN TRIỂN KHAI TRÊN HỆ ĐIỀU HÀNH WINDOWS

Các bước sau đây được sử dụng đối với phần cứng chạy hệ điều hành Windows Server hoặc trên máy tính Windows cá nhân của bạn.

Bước 1: Tải các thư viện dự án

Mở nền tảng PowerShell hoặc Command Prompt (CMD) tại thư mục chứa mã nguồn dự án và chạy biến chuẩn:

go mod tidy

Bước 2: Biên dịch mã nguồn

Thực thi lệnh sau trên CMD để biên dịch hệ thống tổng:

go build -o backend-app.exe ./cmd/server

Nếu bạn đang biên dịch trên một môi trường máy ảo khác có cùng hệ điều hành, cấu trúc chuẩn hóa được viết lại như sau:

set GOOS=windows
set GOARCH=amd64
go build -o backend-app.exe ./cmd/server

Bước 3: Khởi chạy ứng dụng

Ngay sau khi quá trình biên dịch hoàn tất (tệp tin backend-app.exe xuất hiện), bạn có thể nháy đúp chuột vào tệp tin backend-app.exe thông qua Explorer hoặc chạy lệnh truy xuất trên nền cmd:

backend-app.exe

Cửa sổ terminal sẽ hiển thị nhật ký khởi động chi tiết. Vui lòng không đóng cửa sổ này trong suốt thời gian bạn muốn duy trì kết nối.

---

5. KIỂM TRA TÌNH TRẠNG VÀ TÀI LIỆU LẬP TRÌNH API (SWAGGER)

Sau khi hệ thống ứng dụng được khởi động thành công và liên kết domain https://runtime.gtavss.com hoặc domain tùy chỉnh tương ứng trong cấu hình của bạn:

Bạn có thể kiểm tra trạng thái hoạt động của Backend Server qua máy chủ nội hạt: Đường dẫn trạng thái: https://runtime.gtavss.com/health

Đồng thời, ứng dụng cung cấp giao diện quản trị tài liệu API Swagger tích hợp. Bạn có thể sử dụng giao diện này để kiểm thử và tích hợp phần mềm Launcher riêng biệt của bạn. Đường dẫn tài liệu API: https://runtime.gtavss.com/swagger/index.html