# TÀI LIỆU KỸ THUẬT & HƯỚNG DẪN HỆ THỐNG CLOUD VPS QUỐC TẾ (VPS-TRIAL) > **Dự án:** Hệ thống Cloud VPS Quốc Tế - Shop MMO Studio > **Phiên bản:** 2.0 (Hạ tầng Akamai / Linode Cloud API) > **Cập nhật lần cuối:** 24/10/2026 --- ## 1. TỔNG QUAN HỆ THỐNG Module **Cloud VPS Quốc Tế** (`/vps-trial`) là giải pháp cung cấp dịch vụ máy chủ ảo điện toán đám mây quốc tế tốc độ cao, khởi tạo tự động 100% không cần can thiệp thủ công: * **Hạ tầng Cloud:** Akamai Connected Cloud (Linode Enterprise Infrastructure). * **Datacenter đa quốc gia:** Singapore (`ap-south`), Tokyo Nhật Bản (`jp-tyo`), Los Angeles US (`us-lax`), Newark/New York US (`us-east`), Frankfurt Đức (`eu-central`), v.v. * **Đa dạng Hệ điều hành:** * **Windows:** Windows Server 2022, 2019, 2016 Datacenter, Windows 11 Pro, Windows 10 Pro (Kết nối Remote Desktop RDP port 3389, User `Administrator`). * **Linux:** Ubuntu 24.04/22.04 LTS, Debian 12, AlmaLinux 9, Rocky Linux 9, CentOS Stream 9, Kali Linux, Alpine, Arch (Kết nối SSH port 22, User `root`). * **Cơ chế thanh toán:** Tự động trừ số dư ví người dùng theo chu kỳ 30 ngày (1 tháng). Hoàn tiền 100% ngay lập tức nếu cụm cloud bận hoặc hết tài nguyên. * **Cơ chế dự phòng (Failover):** Tự động luân chuyển token khi 1 token Linode bị chạm giới hạn hoặc hết quota. --- ## 2. KIẾN TRÚC & CƠ CHẾ VẬN HÀNH ``` +---------------------------------------+ | NGƯỜI DÙNG / CLIENT | +-------------------+-------------------+ | +-------------------------+-------------------------+ | | Giao diện Website RESTful API v1 [/vps-trial, /vps-quocte-history] [/api/v1/vps/*] | | +-------------------------+-------------------------+ | v +-----------------------+ | HỆ THỐNG XÁC THỰC | | Session / API-Key/Sec | +-----------+-----------+ | v +-----------------------+ | KIỂM TRA SỐ DƯ & TRỪ TIỀN| | (Bảo vệ số dư âm) | +-----------+-----------+ | v +-----------------------+ | LinodeAPI Engine | | - Multi-Token Pool | | - Auto Failover | | - StackScript / OS | +-----------+-----------+ | v +-----------------------+ | Akamai Linode Cloud | | Tạo Instance & Cấp IP| +-----------+-----------+ | +---------------------+---------------------+ | | v v [Thành công: 2 - 4 phút] [Thất bại: Hết tài nguyên] - Trạng thái: provisioning - Tự động hoàn tiền 100% - Realtime Sync -> running - Ghi log lý do lỗi - Mở khóa RDP (3389) / SSH (22) ``` ### 2.1. Quá trình Nạp OS (Provisioning: 2 - 4 phút) * Ngay sau khi Linode API nhận lệnh tạo máy chủ, máy chủ ở trạng thái `provisioning` (nạp image hệ điều hành vào ổ đĩa ảo và khởi động nhân). * **Web UI Realtime Polling:** Trang `/vps-quocte-history` tự động thăm dò `syncStatus` mỗi 7 giây qua Ajax. Khi Linode báo `running`, badge chuyển xanh và tự động hiển thị thông báo sẵn sàng kết nối mà người dùng không cần F5. * **API Realtime Sync:** Khi gọi `GET /api/v1/vps/detail`, backend tự động gọi API Linode kiểm tra; nếu đã hoàn tất sẽ cập nhật database và trả về `status: "running"`. ### 2.2. Quy định Giới hạn Thao tác (Cooldown 60 phút) * Để bảo vệ tài nguyên máy chủ và tránh nguy cơ DDoS/Spam lệnh khởi động, các thao tác điều khiển: * **Khởi động lại (Reboot)** * **Tắt nguồn (Power Off / Shutdown)** * **Bật nguồn (Power On / Boot)** * **Quy tắc:** Chỉ được thực hiện **60 phút 1 lần** cho mỗi máy chủ. * **Giao diện:** Nút bấm tự động khóa `disabled` kèm đồng hồ đếm ngược từng giây (`Thao tác sau: X phút Ys`). * **Backend & API:** Kiểm tra cột `last_action_time` trong database, từ chối lệnh với mã lỗi `ACTION_COOLDOWN` (HTTP 429) nếu chưa hết 60 phút. --- ## 3. CÁC ĐƯỜNG DẪN TRÊN HỆ THỐNG | Đường dẫn (URL) | Chức năng | Phân quyền | | :--- | :--- | :--- | | `https://shopmmostudio.com/vps-trial` | Đặt mua Cloud VPS Quốc Tế | Thành viên | | `https://shopmmostudio.com/vps-quocte-history` | Lịch sử & Điều khiển VPS Quốc Tế | Thành viên | | `https://shopmmostudio.com/document-api-vps` | Tài liệu tích hợp API VPS Quốc Tế | Tất cả / Lập trình viên | | `https://shopmmostudio.com/client/document-api` | Tài liệu API Sản phẩm (Tài khoản/Key) | Tất cả / Lập trình viên | | `https://shopmmostudio.com/api-keys` | Tạo và quản lý API Key / Secret | Thành viên | --- ## 4. TÀI LIỆU RESTFUL API (/api/v1/vps/) ### 4.1. Thông tin kết nối & Xác thực * **Base URL:** `https://shopmmostudio.com/api/v1/vps` * **Headers bắt buộc:** ```http X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx X-API-Secret: sk_secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx Content-Type: application/json ``` --- ### 4.2. Endpoint 1: Lấy danh sách Gói cấu hình & OS * **Method:** `GET` * **URL:** `/api/v1/vps/plans` * **Headers:** Không bắt buộc (truyền thêm để lấy số dư tài khoản). * **Response mẫu (HTTP 200):** ```json { "success": true, "timestamp": 1792813050, "data": { "plans": [ { "id": 4, "plan_id": "g6-standard-1", "name": "Cloud VPS Standard 2GB", "cpu_cores": 1, "ram_mb": 2048, "ram_formatted": "2GB", "disk_gb": 50, "transfer_gb": 2000, "price_monthly": 15000, "price_formatted": "15.000đ", "billing_cycle": "30_days" } ], "operating_systems": { "windows": [ { "id": "windows-2022", "name": "Windows Server 2022 Datacenter", "default_port": 3389, "connection_type": "RDP" } ], "linux": [ { "id": "ubuntu24.04", "name": "Ubuntu 24.04 LTS", "default_port": 22, "connection_type": "SSH" } ] }, "regions": [ { "id": "ap-south", "name": "Singapore (ap-south)", "country": "Singapore", "is_recommended": true } ] } } ``` --- ### 4.3. Endpoint 2: Khởi tạo / Mua Cloud VPS * **Method:** `POST` * **URL:** `/api/v1/vps/order` (hoặc `/api/v1/vps/create`) * **Request Body (JSON):** ```json { "plan_id": 4, "image": "windows-2022", "region": "ap-south", "password": "MyStrongPassword@123", "label": "my-vps-01" } ``` * **Tham số:** * `plan_id` *(int|string, Bắt buộc)*: ID gói cấu hình (VD: `4` hoặc `"g6-standard-1"`). * `image` *(string, Tùy chọn)*: Mã HĐH (Mặc định: `"windows-2022"`). * `region` *(string, Tùy chọn)*: Vùng datacenter (Mặc định: `"ap-south"`). * `password` *(string, Tùy chọn)*: Mật khẩu root/Admin (ít nhất 8 ký tự). Nếu bỏ trống sẽ tự sinh mật khẩu ngẫu nhiên. * `label` *(string, Tùy chọn)*: Tên gợi nhớ của VPS. * **Response mẫu (HTTP 201 Created):** ```json { "success": true, "message": "Khởi tạo Cloud VPS thành công!", "data": { "order_id": 18, "trans_id": "VPS_9D28B1CA4E", "linode_id": 61284920, "plan": { "id": 4, "name": "Cloud VPS Standard 2GB", "plan_id": "g6-standard-1", "cpu": 1, "ram_mb": 2048, "disk_gb": 50 }, "operating_system": { "id": "windows-2022", "name": "Windows Server 2022 Datacenter", "is_windows": true }, "connection": { "ip": "172.104.45.182", "ipv6": "2400:8902::f03c:93ff:fe2b:110a", "username": "Administrator", "password": "MyStrongPassword@123", "port": 3389, "protocol": "RDP" }, "region": "ap-south", "amount": 15000, "balance_before": 100000, "balance_after": 85000, "status": "provisioning", "notice": "Máy chủ đang nạp Hệ điều hành trên Cloud (khoảng 2-4 phút). Kết nối RDP/SSH sẽ sẵn sàng ngay khi máy chuyển sang trạng thái running.", "created_at": "2026-10-24 10:45:00", "expires_at": "2026-11-23 10:45:00" } } ``` --- ### 4.4. Endpoint 3: Danh sách Cloud VPS đã mua * **Method:** `GET` * **URL:** `/api/v1/vps/orders` (hoặc `/api/v1/vps/list`) * **Query Parameters:** * `page` *(int)*: Số trang (Mặc định: 1) * `limit` *(int)*: Số lượng bản ghi/trang (Tối đa: 100, Mặc định: 10) * `status` *(string)*: Lọc theo trạng thái (`running`, `provisioning`, `offline`, `all`) * `search` *(string)*: Tìm kiếm theo IP, mã đơn (`trans_id`), hoặc tên máy (`label`) --- ### 4.5. Endpoint 4: Chi tiết & Trạng thái Realtime * **Method:** `GET` * **URL:** `/api/v1/vps/detail` (hoặc `/api/v1/vps/status`) * **Query Parameters:** `trans_id` hoặc `order_id` * **Đặc tính:** Nếu máy chủ đang `provisioning` hoặc `booting`, endpoint tự động truy vấn Linode API; nếu máy đã boot xong sẽ tự cập nhật status sang `running`. --- ### 4.6. Endpoint 5: Điều khiển máy chủ (Reboot / Shutdown / Boot) * **Method:** `POST` * **URL:** `/api/v1/vps/action` * **Request Body (JSON):** ```json { "trans_id": "VPS_9D28B1CA4E", "action": "reboot" } ``` * **Hành động (`action`):** * `reboot`: Khởi động lại máy chủ. * `shutdown` (hoặc `poweroff`): Tắt nguồn máy chủ. * `boot` (hoặc `poweron`): Bật nguồn máy chủ. * **Lưu ý Cooldown:** Giới hạn 60 phút / 1 lần thao tác. Nếu chưa đủ thời gian, trả về HTTP 429: ```json { "success": false, "message": "Mỗi thao tác điều khiển máy chủ chỉ được thực hiện 60 phút 1 lần. Vui lòng thử lại sau 48 phút nữa!", "data": { "error_code": "ACTION_COOLDOWN" } } ``` --- ## 5. BẢNG MÃ LỖI THƯỜNG GẶP (ERROR CODES) | Error Code | HTTP Code | Ý nghĩa & Hướng xử lý | | :--- | :--- | :--- | | `INVALID_API_KEY` | 401 | API Key không chính xác hoặc không tồn tại. | | `INVALID_API_SECRET` | 401 | API Secret không khớp với API Key. | | `INSUFFICIENT_BALANCE` | 400 | Số dư ví không đủ để thanh toán gói cấu hình đã chọn. | | `PLAN_NOT_FOUND` | 400 | ID gói cấu hình không tồn tại hoặc đã ngừng kinh doanh. | | `SERVER_PROVISIONING` | 400 | Máy đang cài OS (~2-4 phút). Chưa thể gửi lệnh điều khiển. | | `ACTION_COOLDOWN` | 429 | Đang trong thời gian cooldown 60 phút của thao tác trước đó. | | `NOT_FOUND` | 404 | Không tìm thấy máy chủ theo `trans_id` hoặc `order_id`. | | `PROVISION_FAILED` | 500 | Hạ tầng Cloud Linode bận. Tiền đã được tự động hoàn lại ví 100%. | --- ## 6. CẤU TRÚC CƠ SỞ DỮ LIỆU LIÊN QUAN ### 6.1. Bảng `vps_linode_plans` (Gói cấu hình mở bán) * `id` *(INT AUTO_INCREMENT)*: ID gói cấu hình. * `plan_id` *(VARCHAR(100))*: Mã định danh Linode (VD: `g6-standard-1`, `g6-standard-2`). * `name` *(VARCHAR(255))*: Tên hiển thị của gói (VD: Cloud VPS Standard 2GB). * `cpu` *(INT)*: Số vCPU Cores. * `ram` *(INT)*: Bộ nhớ RAM (MB). * `disk` *(INT)*: Dung lượng ổ đĩa SSD NVMe (GB). * `transfer` *(INT)*: Dung lượng băng thông mạng mỗi tháng (GB). * `price_monthly` *(DECIMAL(15,2))*: Giá bán theo chu kỳ 30 ngày (VNĐ). * `status` *(TINYINT(1))*: Trạng thái mở bán (`1` = Đang bán, `0` = Ẩn). ### 6.2. Bảng `vps_linode_orders` (Đơn hàng máy chủ của khách) * `id` *(INT AUTO_INCREMENT)*: ID bản ghi đơn hàng. * `trans_id` *(VARCHAR(100))*: Mã giao dịch đơn hàng duy nhất (`VPS_XXXXXXXXXX`). * `user_id` *(INT)*: ID người dùng sở hữu máy chủ. * `token_id` *(INT)*: ID của token Linode đã dùng để khởi tạo instance. * `token_label` *(VARCHAR(255))*: Tên nhãn token quản trị. * `linode_id` *(BIGINT)*: ID máy chủ trên Akamai Linode. * `label` *(VARCHAR(255))*: Nhãn máy chủ (`vps-xxxxxxxx`). * `type` *(VARCHAR(100))*: Loại gói cấu hình (VD: `g6-standard-1`). * `region` *(VARCHAR(100))*: Vùng đặt máy chủ (VD: `ap-south`). * `image` *(VARCHAR(150))*: Tên hệ điều hành hiển thị. * `ip` *(VARCHAR(100))*: Địa chỉ IPv4 Public của máy chủ. * `ipv6` *(VARCHAR(150))*: Địa chỉ IPv6 của máy chủ. * `root_pass` *(VARCHAR(255))*: Mật khẩu đăng nhập RDP (Windows) hoặc SSH (Linux). * `cpu`, `ram`, `disk` *(INT)*: Cấu hình phần cứng thực tế. * `amount` *(DECIMAL(15,2))*: Số tiền đã thanh toán. * `status` *(VARCHAR(50))*: Trạng thái máy (`provisioning`, `running`, `offline`, `stopped`). * `last_action_time` *(INT)*: Timestamp Unix lần cuối người dùng bấm Reboot/Tắt/Bật (Dùng cho Cooldown 60 phút). * `date_create` *(DATETIME)*: Thời gian khởi tạo đơn hàng. * `expires_at` *(DATETIME)*: Thời hạn hết hạn máy chủ (+30 ngày). * `updated_at` *(DATETIME)*: Thời gian cập nhật trạng thái gần nhất. --- ## 7. DANH SÁCH FILE NGUỒN TRÊN SERVER ``` /www/wwwroot/shopmmostudio.com/ ├── views/ │ └── client/ │ ├── vps-trial.php # Trang giao diện đặt mua Cloud VPS Quốc Tế │ ├── vps-quocte-history.php # Trang quản lý & điều khiển VPS Quốc Tế │ ├── document-api-vps.php # Trang tài liệu RESTful API VPS Quốc Tế │ ├── document-api.php # Trang tài liệu RESTful API Sản phẩm │ └── nav.php # Menu điều hướng chính & mobile ├── ajaxs/ │ └── client/ │ └── vps-trial.php # Xử lý Ajax tạo VPS, điều khiển, sync status web ├── api/ │ └── v1/ │ └── vps/ │ ├── plans.php # API GET /api/v1/vps/plans │ ├── order.php # API POST /api/v1/vps/order (create.php) │ ├── orders.php # API GET /api/v1/vps/orders (list.php) │ ├── detail.php # API GET /api/v1/vps/detail (status.php) │ └── action.php # API POST /api/v1/vps/action ├── libs/ │ ├── LinodeAPI.php # Thư viện giao tiếp Akamai Linode API v4 │ └── services/ │ └── ApiKeyService.php # Quản lý & xác thực API Key / Secret, Rate Limit ├── index.php # Khai báo Action whitelist └── .htaccess # Định tuyến URL Apache RewriteRule ```