# NexCMP 1.6.1 — full documentation > Complete NexCMP documentation in one file. Source: https://nexcmp.com/vi/docs/ · generated 2026-11-02. --- # NexCMP là gì {#what-is-nexcmp} NexCMP là phần mềm bạn cài đặt trên **máy chủ của riêng mình** để biến hạ tầng đám mây thành sản phẩm có thể kinh doanh. Phần mềm mang đến cho bạn: - một **cổng khách hàng** nơi người dùng đăng ký, nạp tiền, đặt mua máy ảo cùng các dịch vụ khác, mở console, tạo Snapshots và gửi yêu cầu hỗ trợ; - một **admin console** (`/admin`) nơi bạn quản lý khách hàng, gói dịch vụ, giá bán, thanh toán, hạ tầng và cài đặt; - **billing**: ví riêng cho từng khách hàng, tính phí theo giờ hoặc theo tháng, hóa đơn, khuyến mại và hạn mức tài nguyên; - **đại lý white-label**: các thương hiệu khác có thể bán tài nguyên của bạn dưới tên miền riêng của họ; - một **API**, công cụ dòng lệnh (`cmp`) và MCP server để tự động hóa; - tùy chọn **AI Chat** (trợ lý hỗ trợ) và **AI Agent** (quản trị máy ảo bằng ngôn ngữ tự nhiên). ## Nền tảng kết nối {#what-it-connects-to} Bản thân NexCMP không trực tiếp lưu trữ máy ảo mà điều khiển nền tảng thực hiện việc đó. Một *source* (còn gọi là provider) có thể là: | Source | Mục đích sử dụng điển hình | Hướng dẫn | |---|---|---| | Apache CloudStack | Private hoặc public cloud với các zone, network, virtual router và IP public | [CloudStack](https://nexcmp.com/vi/docs/infrastructure/cloudstack/) | | Proxmox VE | Máy chủ đơn lẻ hoặc cluster bạn đang vận hành | [Proxmox VE](https://nexcmp.com/vi/docs/infrastructure/proxmox/) | Các module khác cần hạ tầng riêng: [máy chủ bare-metal](https://nexcmp.com/vi/docs/infrastructure/dedicated/), [node VPN và proxy](https://nexcmp.com/vi/docs/infrastructure/vpn-proxy-nodes/), [S3 Object Storage](https://nexcmp.com/vi/docs/infrastructure/s3/), [Kubernetes và Private Cloud](https://nexcmp.com/vi/docs/infrastructure/kubernetes-and-private-cloud/). Xem [Yêu cầu hạ tầng](https://nexcmp.com/vi/docs/infrastructure/requirements/) để xem bảng tổng hợp cho tất cả các dịch vụ. ## Kiến trúc hệ thống {#how-it-is-built} NexCMP là một chương trình duy nhất với hai dịch vụ systemd trên một máy chủ Ubuntu: - `nexcmp` — web server: cổng khách hàng, admin console, API, wizard thiết lập; - `nexcmp-vmd` — background worker: xử lý tác vụ cấp phát, đồng bộ với CloudStack hoặc Proxmox của bạn, và chạy chu kỳ billing. Dữ liệu được lưu tại `/var/lib/nexcmp` (cơ sở dữ liệu SQLite và tệp tin), cấu hình trong `/etc/nexcmp`, chương trình trong `/opt/nexcmp`. Xem [Kiến trúc](https://nexcmp.com/vi/docs/infrastructure/architecture/) để nắm được bức tranh toàn cảnh. ## Các bước tiếp theo {#where-to-go-next} 1. Kiểm tra [yêu cầu hệ thống](https://nexcmp.com/vi/docs/getting-started/requirements/). 2. Nhận license — [License và mua hàng](https://nexcmp.com/vi/docs/getting-started/license-and-purchase/). 3. [Cài đặt](https://nexcmp.com/vi/docs/getting-started/installation/), sau đó chạy [wizard thiết lập](https://nexcmp.com/vi/docs/getting-started/setup-wizard/). 4. Kết nối nền tảng của bạn: [CloudStack](https://nexcmp.com/vi/docs/infrastructure/cloudstack/) hoặc [Proxmox VE](https://nexcmp.com/vi/docs/infrastructure/proxmox/). --- # Yêu cầu đối với máy chủ NexCMP {#requirements-for-the-nexcmp-server} Trang này mô tả yêu cầu cho máy chủ chạy NexCMP. Yêu cầu dành cho CloudStack, Proxmox VE hoặc hạ tầng khác được nêu trong [Yêu cầu hạ tầng](https://nexcmp.com/vi/docs/infrastructure/requirements/). ## Máy chủ {#server} | Hạng mục | Yêu cầu | Trình cài đặt kiểm tra | |---|---|---| | Hệ điều hành | Ubuntu **22.04** hoặc **24.04** | Có — dừng lại và báo lỗi với các hệ điều hành khác | | Kiến trúc CPU | x86_64 | Có | | Bộ nhớ RAM | Tối thiểu 2 GB (trình cài đặt từ chối nếu dưới khoảng 1.8 GB) | Có | | Dung lượng đĩa trống | Tối thiểu 8 GB trống trên `/` | Có | | Quyền hạn | root (`sudo`) | Có | | Gói phần mềm | `curl`, `ca-certificates`, `zstd`, `tar`, `openssl`, `python3`, `openssh-client` — tự động cài đặt | Tự động cài nếu thiếu | | Với HTTPS | `nginx` và `certbot` — tự động cài đặt trừ khi bạn truyền `--no-nginx` | Tự động cài nếu thiếu | ::: tip Ước tính tài nguyên Một hệ thống quy mô nhỏ (vài trăm khách hàng) hoạt động mượt mà trên 2 vCPU / 4 GB RAM. Dung lượng đĩa chủ yếu dành cho cơ sở dữ liệu SQLite và các bản cập nhật cũng như bản sao lưu tùy chọn — hãy dự trù từ 20 GB trở lên cho production. ::: ## Mạng {#network} | Chiều | Cổng | Mục đích | |---|---|---| | Chiều vào | 80/tcp | Xác thực Let's Encrypt và chuyển hướng sang HTTPS | | Chiều vào | 443/tcp | Cổng thông tin khách hàng, bảng điều khiển quản trị, API | | Chiều vào | 3000/tcp | Chỉ dùng cho setup wizard khi cài đặt lần đầu và truy cập khẩn cấp — xem [Installation](https://nexcmp.com/vi/docs/getting-started/installation/#the-panel-port-3000) | | Chiều ra | 443/tcp đến `nexcmp.com` | Kích hoạt license, kiểm tra license hàng ngày, cập nhật | | Chiều ra | đến CloudStack API / Proxmox API của bạn | Cấp phát tài nguyên và đồng bộ hóa | | Chiều ra | 443/tcp đến các nhà cung cấp thanh toán, e-mail và AI mà bạn bật | Stripe, PayPal, SMTP, nhà cung cấp AI và các dịch vụ khác | Máy chủ cần có **địa chỉ IPv4 public** nếu bạn muốn Let's Encrypt cấp chứng chỉ trực tiếp. Nếu tên miền được proxy qua Cloudflare, hãy xem [DNS and Cloudflare](https://nexcmp.com/vi/docs/getting-started/dns-and-cloudflare/). ## DNS - Một **tên miền chính** (ví dụ `cloud.example.com`) — portal là `https://cloud.example.com/` và admin console là `https://cloud.example.com/admin`. - Tùy chọn: `admin.` và `partner.`. Nếu các tên miền đó trỏ về máy chủ (hoặc về Cloudflare), trình cài đặt sẽ thêm chúng vào chứng chỉ. - Tên miền phải khớp với tên miền đã đăng ký trên license của bạn. ## Không yêu cầu trên máy chủ này {#not-required-on-this-server} NexCMP chạy dưới dạng người dùng dịch vụ không đặc quyền thông thường (`nexcmp`). Hệ thống **không** cần quyền root khi vận hành, không cần Docker, máy chủ cơ sở dữ liệu riêng, Redis, hay bất kỳ phần mềm hypervisor nào. --- # License và mua hàng {#license-and-purchase} > **Vị trí trong trang admin:** System › Admin › License & updates (`/license`) NexCMP được kích hoạt bằng một **license key** mà bạn quản lý trong [tài khoản NexCMP](https://nexcmp.com/licenses) của mình. Các phiên bản và giá hiện tại được liệt kê tại [nexcmp.com/pricing](https://nexcmp.com/pricing); trang này giải thích cách license hoạt động khi bạn đã sở hữu. ## Nhận license {#get-a-license} 1. Tạo tài khoản tại [nexcmp.com](https://nexcmp.com/register) và xác minh email của bạn. 2. Chọn một phiên bản: - **NexCMP Free** — dành cho các nhà mạng có ASN riêng và subnet đăng ký dưới tên của chính mình. Gửi đơn đăng ký tại [nexcmp.com/deploy](https://nexcmp.com/deploy) (công ty, ASN, subnet, tên miền panel). Email tài khoản của bạn phải thuộc tên miền công ty mà cơ quan đăng ký công khai (WHOIS) liệt kê cho ASN hoặc subnet đó. Mỗi đơn đăng ký đều được xem xét; bạn sẽ nhận được email khi có kết quả và license key chỉ xuất hiện sau khi được phê duyệt. - **NexCMP Source** — nâng cấp một lần, không cần ASN. Xem [nexcmp.com/pricing](https://nexcmp.com/pricing). 3. Mở trang license của bạn. Trang này hiển thị **license key** (định dạng `NXC-XXXXX-XXXXX-XXXXX-XXXXX`), **main domain** và lệnh cài đặt sẵn sàng sử dụng. ::: warning Bảo mật key License key dùng để kích hoạt bản cài đặt. Hãy coi nó như mật khẩu: không dán vào ticket, đoạn chat hoặc ảnh chụp màn hình. ::: ## Nội dung của license {#what-a-license-contains} | Trường | Ý nghĩa | |---|---| | Main domain | Hostname mà portal của bạn chạy trên đó. Key được liên kết với hostname này khi kích hoạt. | | Reseller domains | Các hostname bổ sung hoạt động như portal white-label — xem [Resellers](https://nexcmp.com/vi/docs/customers/resellers/). | | Updates until | Ngày giới hạn bạn nhận được **bản cập nhật và bản vá lỗi**. License Free có thời hạn ban đầu là **1 year** kể từ ngày được phê duyệt; gia hạn với giá $99 mỗi năm trên trang license của bạn. Các bản vá bảo mật luôn được cung cấp, ngay cả sau ngày này. | | Status | `active`, hoặc suspended / expired / revoked. | ## Khi hết năm miễn phí {#when-the-free-year-ends} Phần mềm **vẫn tiếp tục hoạt động** khi ngày "Updates until" qua đi: khách hàng, dịch vụ và billing không bị ảnh hưởng. Bạn sẽ ngừng nhận các bản phát hành tính năng mới và bản cập nhật sửa lỗi (các bản vá bảo mật vẫn được cung cấp). Gia hạn với giá $99 mỗi năm trên trang license của bạn tại [nexcmp.com/licenses](https://nexcmp.com/licenses) để tiếp tục; việc gia hạn sẽ cộng thêm 12 tháng vào ngày kết thúc hiện tại. NexCMP Free chỉ bao gồm các bản sửa lỗi — không có hỗ trợ kỹ thuật và không có app. ## NexCMP Source bổ sung những gì {#what-nexcmp-source-adds} License Source là gói nâng cấp một lần trị giá $1,999 cho license của bạn: toàn bộ mã nguồn, tất cả app NexCMP (Android, iOS, Windows, macOS, Linux, Chrome / Edge / Brave và Firefox) được build và gắn thương hiệu riêng cho bạn, cùng 30 ngày làm việc với kỹ sư chuyên gia — miễn phí chuyển đổi từ VMware, WHMCS hoặc panel khác, hoặc thiết lập toàn diện từ A đến Z. Các bản phát hành mã nguồn mới được bao gồm trong 12 tháng; việc gia hạn sau đó ($99 mỗi năm) là tùy chọn, và mã nguồn bạn đã tải về là của bạn vĩnh viễn. Xem [Source license terms](https://nexcmp.com/legal/source-license/). ## Cách bản cài đặt kiểm tra license {#how-the-installation-checks-its-license} - Khi cài đặt, máy chủ sẽ kích hoạt key cho tên miền của bạn và nhận một **signed token**. - Token được tự động gia hạn mỗi **24 hours**. Token có hiệu lực trong **14 days**, vì vậy việc mất kết nối Internet trong thời gian ngắn sẽ không gây ảnh hưởng. - Tất cả bản phát hành và token đều được xác minh bằng chữ ký Ed25519 tích hợp sẵn trong chương trình; các bản tải về bị can thiệp sẽ bị từ chối. Kiểm tra trạng thái bất cứ lúc nào trong admin console hoặc bằng `sudo nexcmp status`. ## Nếu license không hợp lệ {#if-the-license-is-not-valid} Khi token hết hạn, license bị tạm ngưng hoặc tên miền không còn khớp: - khách hàng **không thể tạo dịch vụ mới** và admin console sẽ hiển thị banner; - các dịch vụ đang chạy, **billing và khách hàng hiện tại không bị ảnh hưởng**; - khắc phục nguyên nhân (kết nối lại máy chủ với Internet, gia hạn tại [nexcmp.com/licenses](https://nexcmp.com/licenses)) và nhấp vào **Check now** trong License & updates. ## Chuyển sang máy chủ hoặc domain mới {#moving-to-a-new-server-or-domain} Kích hoạt trên máy chủ mới bằng cùng license key và domain đã đăng ký (xem [Cài đặt](https://nexcmp.com/vi/docs/getting-started/installation/)). Để thay đổi domain đã đăng ký, trước tiên hãy thực hiện trên trang license của bạn tại [nexcmp.com/licenses](https://nexcmp.com/licenses), sau đó chạy lại trình cài đặt với `--domain` mới. --- # Cài đặt NexCMP {#install-nexcmp} Trình cài đặt là một script duy nhất được cung cấp bởi license server của bạn. Script này kiểm tra máy chủ, kích hoạt license, tải xuống và xác thực chương trình, cài đặt các service và (tùy chọn) thiết lập nginx với chứng chỉ Let's Encrypt. ## Trước khi bắt đầu {#before-you-start} - Một máy chủ đáp ứng các [yêu cầu](https://nexcmp.com/vi/docs/getting-started/requirements/) và quyền truy cập root. - **License key** và **main domain** từ [trang bản quyền](https://nexcmp.com/licenses) của bạn — xem [Bản quyền và mua hàng](https://nexcmp.com/vi/docs/getting-started/license-and-purchase/). - Bản ghi DNS cho domain — xem [DNS và Cloudflare](https://nexcmp.com/vi/docs/getting-started/dns-and-cloudflare/). Bạn cũng có thể cài đặt trước rồi cấu hình DNS sau; trình cài đặt sẽ thông báo những phần còn thiếu và bạn chỉ cần chạy lại. ## Cài đặt {#install} 1. Đăng nhập vào máy chủ và chuyển sang quyền root (hoặc thêm tiền tố `sudo`). 2. Chạy lệnh lấy từ trang license của bạn. Lệnh có dạng như sau: ```bash curl -fsSL https://nexcmp.com/install.sh | sudo bash -s -- \ --license NXC-XXXXX-XXXXX-XXXXX-XXXXX \ --domain cloud.example.com \ --email admin@example.com ``` 3. Đợi các dấu tích hoàn tất. Quá trình cài đặt mới mất vài phút; lần khởi động đầu tiên sẽ tạo database schema và có thể mất tới một phút trên ổ đĩa tốc độ chậm. 4. Xem phần tóm tắt ở cuối. Trình cài đặt sẽ hiển thị URL portal và admin, **setup code** cùng bước tiếp theo. ![Trình cài đặt hoàn tất với URL portal, URL admin và setup code dùng một lần](https://nexcmp.com/vi/docs/images/getting-started/installation-01-finish.webp) ## Tham số {#parameters} | Tham số | Mặc định | Ý nghĩa | |---|---|---| | `--license KEY` | bắt buộc khi cài đặt lần đầu | License key. | | `--domain NAME` | bắt buộc khi cài đặt lần đầu | Domain chính. Phải khớp với license. `https://` và các đường dẫn phía sau sẽ bị loại bỏ. | | `--email ADDRESS` | không có | Email liên hệ nhận thông báo hết hạn Let's Encrypt. Nếu không cung cấp, chứng chỉ sẽ được đăng ký không kèm email. | | `--port N` | `3000` | Port cục bộ của panel (1–65535). | | `--no-nginx` | tắt | Không cài đặt hoặc cấu hình nginx / TLS. Sử dụng tùy chọn này khi bạn tự chạy reverse proxy hoặc muốn trải nghiệm thử NexCMP trước. | | `--behind-cloudflare` | tự động phát hiện | Bắt buộc bật chế độ "domain được proxy qua Cloudflare". Thông thường chế độ này được tự động nhận diện từ DNS. | | `--channel NAME` | `stable` | Kênh phát hành. | Chạy lại trình cài đặt **không kèm tham số** sẽ tái sử dụng các tham số đã lưu (`/etc/nexcmp/install.conf`) và nâng cấp an toàn, giữ nguyên dữ liệu, cấu hình cùng các tài khoản. Đó chính xác là những gì `sudo nexcmp update` thực hiện. ## Những gì trình cài đặt thực hiện {#what-the-installer-does} 1. **Kiểm tra máy chủ** — Ubuntu 22.04/24.04, x86_64, tối thiểu 2 GB RAM, 8 GB dung lượng đĩa trống. 2. **Cài đặt các package** cần thiết (`curl`, `zstd`, `openssl`, `python3`, `openssh-client` …). 3. **Tạo service user** `nexcmp` và các thư mục: `/opt/nexcmp` (chương trình, thuộc sở hữu của root, chỉ đọc đối với service), `/etc/nexcmp` (cấu hình), `/var/lib/nexcmp` (dữ liệu), `/var/log/nexcmp`. 4. **Kích hoạt license** cho domain và lưu instance ID cố định cho máy chủ này. 5. **Tải xuống bản phát hành mới nhất mà bạn được cấp quyền**, sau đó xác thực SHA-256 và chữ ký Ed25519. Bản phát hành không có chữ ký hợp lệ sẽ bị từ chối. Trình cài đặt không bao giờ hạ cấp một phiên bản mới hơn đang chạy. 6. **Ghi cấu hình cùng các systemd unit** (`nexcmp`, `nexcmp-vmd`, `nexcmp-update`) và khởi động các dịch vụ; trình cài đặt sẽ đợi `/healthz` phản hồi. 7. **Thiết lập nginx và TLS** (trừ khi có `--no-nginx`): xin chứng chỉ Let's Encrypt bằng certbot (webroot challenge) cho tên miền và cho `admin.` / `partner.` nếu các tên miền này cũng phân giải được. Nếu DNS chưa trỏ về máy chủ này (hoặc Cloudflare), trình cài đặt sẽ bỏ qua bước này và thông báo rõ. 8. **In bản tóm tắt** kèm các URL và **setup code** (nếu chưa có quản trị viên nào). ## Cổng của panel (3000) {#the-panel-port-3000} - Trong lần cài đặt đầu tiên, panel sẽ lắng nghe trên `0.0.0.0:3000` để bạn có thể mở setup wizard tại `http://:3000/setup`. - Sau khi wizard hoàn tất **và** TLS đã kích hoạt, panel sẽ chỉ lắng nghe trên `127.0.0.1`; nginx sẽ proxy `https://` tới panel. - Trong trường hợp khẩn cấp (nginx bị lỗi, DNS cấu hình sai), bạn có thể mở cổng này trong thời gian giới hạn: `sudo nexcmp open-port 30` (30 phút, sau đó sẽ tự đóng) — hoặc dùng SSH tunnel: `ssh -L 3000:127.0.0.1:3000 ` và truy cập `http://127.0.0.1:3000/`. ::: warning HTTP không mã hóa Cổng 3000 sử dụng HTTP không mã hóa. Bạn chỉ nên dùng cổng này cho setup wizard trong mạng đáng tin cậy hoặc thông qua SSH tunnel. Không để cổng mở liên tục. ::: ## Cài đặt không cần tên miền công khai (lab hoặc thử nghiệm) {#installing-without-a-public-domain-lab-or-test} Bạn có thể cài đặt trên máy chủ chưa có DNS: ```bash curl -fsSL https://nexcmp.com/install.sh | sudo bash -s -- \ --license NXC-XXXXX-XXXXX-XXXXX-XXXXX --domain lab.example.com --no-nginx ``` Sau đó mở wizard qua SSH tunnel (`ssh -L 3000:127.0.0.1:3000 `, truy cập `http://127.0.0.1:3000/setup`). Chạy lại trình cài đặt mà không có `--no-nginx` sau khi đã cấu hình DNS. ## Docker và Kubernetes {#docker-and-kubernetes} Không có container image được phát hành. Trình cài đặt (cài đặt systemd gốc) là phương thức cài đặt được hỗ trợ. ## Kiểm tra {#verify} ```bash sudo nexcmp status ``` Bạn sẽ thấy phiên bản, `nexcmp: active`, `nexcmp-vmd: active`, `healthz: ok` và — cho đến khi wizard hoàn tất — setup code. Tiếp tục với [setup wizard](https://nexcmp.com/vi/docs/getting-started/setup-wizard/). Nếu gặp lỗi, vui lòng xem [Lỗi cài đặt](https://nexcmp.com/vi/docs/troubleshooting/installation-errors/). --- # DNS và Cloudflare {#dns-and-cloudflare} NexCMP cần một tên miền DNS — **tên miền chính** của hệ thống — và hoạt động ở hai chế độ. ## Chế độ A: DNS trỏ trực tiếp về máy chủ {#mode-a-dns-points-straight-at-the-server} 1. Tạo bản ghi **A** `cloud.example.com → ` (và bản ghi **AAAA** nếu máy chủ có IPv6). 2. Tùy chọn, nếu bạn sử dụng: `admin.cloud.example.com` và `partner.cloud.example.com` trỏ về cùng địa chỉ IP. 3. Chạy (hoặc chạy lại) [trình cài đặt](https://nexcmp.com/vi/docs/getting-started/installation/). Hệ thống sẽ nhận diện tên miền phân giải về IP công khai của máy chủ và xin chứng chỉ Let's Encrypt qua HTTP-01 challenge trên cổng 80. ## Chế độ B: tên miền được proxy qua Cloudflare {#mode-b-the-domain-is-proxied-by-cloudflare} Tạo các bản ghi tương tự với đám mây màu cam (**Proxied**). Trình cài đặt sẽ phát hiện tên miền chỉ phân giải về địa chỉ Cloudflare và chuyển sang chế độ Cloudflare: - nginx vẫn lắng nghe trên cổng 80/443 của máy chủ; - IP thực của khách truy cập được đọc từ header `CF-Connecting-IP` — **chỉ áp dụng** cho các kết nối đến từ các dải IP đã công bố của Cloudflare, nhờ đó tránh được nguy cơ bị giả mạo; - chứng chỉ được xin qua Let's Encrypt (Cloudflare chuyển tiếp challenge về máy chủ gốc); nếu chưa thể thực hiện, một **chứng chỉ gốc tự ký** sẽ được tạo để chế độ "Full" hoạt động, và việc chạy lại trình cài đặt sau đó sẽ nâng cấp lên Let's Encrypt. Bạn có thể bắt buộc dùng chế độ này bằng `--behind-cloudflare`. ::: important Thiết lập chế độ SSL/TLS trong Cloudflare Trong Cloudflare, hãy vào **SSL/TLS › Overview** và chọn **Full (strict)** sau khi trình cài đặt báo có chứng chỉ Let's Encrypt. Với chứng chỉ gốc tự ký, hãy chọn **Full**. **Flexible** sẽ gây vòng lặp chuyển hướng. ::: ::: tip Nếu bật "Always Use HTTPS", Cloudflare sẽ gửi yêu cầu xác thực đến cổng 443 của máy chủ gốc. Trình cài đặt xử lý việc này bằng cách tạo chứng chỉ tự ký tạm thời trước, sau đó thử lại với Let's Encrypt. ::: ## Kiểm tra {#check-it} ```bash dig +short cloud.example.com # A record (a Cloudflare address in mode B) curl -I https://cloud.example.com/healthz sudo certbot certificates # certificate name, domains and expiry ``` Chứng chỉ tự động gia hạn theo timer của certbot. Quá trình gia hạn sử dụng webroot `/var/www/nexcmp-acme`, vì vậy cổng 80 phải luôn truy cập được (trực tiếp hoặc qua Cloudflare). ## Các vấn đề thường gặp {#common-problems} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | Trình cài đặt báo "DNS … does not point to … (nor to Cloudflare) — skipping nginx/TLS" | Bản ghi DNS bị thiếu, sai hoặc chưa được cập nhật hoàn tất | Sửa bản ghi, đợi DNS cập nhật rồi chạy lại trình cài đặt. | | Trình duyệt hiển thị `ERR_TOO_MANY_REDIRECTS` phía sau Cloudflare | Chế độ SSL đang là **Flexible** | Đặt thành **Full (strict)** (hoặc **Full**). | | Lỗi Cloudflare 525/526 | Chứng chỉ máy chủ gốc bị từ chối | Dùng **Full** với chứng chỉ gốc tự ký, hoặc **Full (strict)** với Let's Encrypt. | | Khách truy cập đều hiển thị IP của Cloudflare trong log | Không ở chế độ Cloudflare | Chạy lại trình cài đặt với `--behind-cloudflare`. | Xem thêm tại [Các lỗi cài đặt](https://nexcmp.com/vi/docs/troubleshooting/installation-errors/). --- # Trình hướng dẫn thiết lập {#setup-wizard} > **Vị trí trong trang quản trị:** trình hướng dẫn là một trang độc lập tại `/setup` chỉ hiển thị cho đến khi quản trị viên đầu tiên được tạo. Sau đó, các bước kiểm tra tương tự sẽ nằm tại System › Admin › Start (`/setup`). Trình hướng dẫn chuyển đổi bản cài đặt mới thành bảng điều khiển hoạt động hoàn chỉnh qua bốn bước ngắn. Trình thiết lập chạy trên cổng 3000 (`http://:3000/setup`) hoặc tại `https:///setup` khi TLS đã kích hoạt. ::: warning Trình hướng dẫn sẽ biến mất sau bước 3 Sau khi quản trị viên được tạo, trình hướng dẫn sẽ đóng lại và setup code bị xóa. Để truy cập bảng điều khiển sau đó, hãy sử dụng admin console. ::: ## Bước 0 — Setup code {#step-0-—-setup-code} Trình cài đặt sẽ hiển thị một **setup code dùng một lần** ở cuối. Bạn có thể xem lại mã bằng: ```bash sudo nexcmp status ``` Dán mã vào **Setup code** và nhấp vào **Continue**. Mã này bảo vệ trình hướng dẫn: không ai phát hiện cổng mở có thể tạo quản trị viên nếu không có mã. ![Bước 0 của trình hướng dẫn thiết lập yêu cầu setup code dùng một lần](https://nexcmp.com/vi/docs/images/getting-started/setup-wizard-00-code.webp) ## Bước 1 — License {#step-1-—-license} | Trường | Giá trị | |---|---| | License key | `NXC-XXXXX-XXXXX-XXXXX-XXXXX` — đã được kích hoạt sẵn bởi trình cài đặt, nên bước này thông thường sẽ hiển thị "Activated for cloud.example.com" | | Main domain | Tên miền đã đăng ký trên license | Nếu trình cài đặt đã kích hoạt license, trình hướng dẫn sẽ nhận diện và chuyển tiếp. Nếu không, hãy nhập key cùng domain rồi nhấp vào **Activate**. Lỗi được hiển thị bằng màu đỏ — xem [Lỗi cài đặt](https://nexcmp.com/vi/docs/troubleshooting/installation-errors/). ![Bước 1 của trình hướng dẫn thiết lập hiển thị license đã được kích hoạt cho main domain](https://nexcmp.com/vi/docs/images/getting-started/setup-wizard-01-license.webp) ## Bước 2 — CloudStack (hoặc Connect later) {#step-2-—-cloudstack-or-connect-later} Bạn có hai lựa chọn: - **Kết nối ngay.** Nhập CloudStack **API URL** (`https://cloudstack.example.com/client/api`), **API key** và **Secret key**, nhấp vào **Test connection**, sau đó chọn **Zone**, **Guest network for customer VMs**, **Zone display name** và mã **Country** gồm hai chữ cái. Nhấp vào **Save CloudStack**. - **Kết nối sau.** Nhấp vào **Connect later**. Mọi tính năng khác vẫn hoạt động; bạn có thể kết nối CloudStack hoặc Proxmox VE sau đó trong mục Infrastructure. Cho đến lúc đó, health panel sẽ nhắc bạn rằng chưa có nguồn nào được kết nối. ![Bước 2 của trình hướng dẫn với các trường CloudStack API URL, API key và secret key được điền giá trị mẫu](https://nexcmp.com/vi/docs/images/getting-started/setup-wizard-02-cloudstack-form.webp) ::: important Sử dụng một tài khoản CloudStack chuyên dụng Không sử dụng key ROOT administrator. Hãy tạo một domain và account riêng cho NexCMP rồi sử dụng API key đó — xem [CloudStack](https://nexcmp.com/vi/docs/infrastructure/cloudstack/#create-a-dedicated-account-and-api-key). Trình hướng dẫn sẽ kiểm tra xem network đã chọn có thuộc zone và account của key đó hay không. ::: ![Sau Test connection: danh sách zone và guest network, các trường zone display name và country](https://nexcmp.com/vi/docs/images/getting-started/setup-wizard-02b-cloudstack-picked.webp) Nếu bạn chỉ định dùng **Proxmox VE**, hãy chọn **Connect later** và làm theo hướng dẫn tại [Proxmox VE](https://nexcmp.com/vi/docs/infrastructure/proxmox/). ## Bước 3 — Quản trị viên và thương hiệu {#step-3-—-administrator-and-brand} | Trường | Quy tắc | |---|---| | Admin email (login) | Địa chỉ email hợp lệ. Đây là tên đăng nhập quản trị viên của bạn. | | Mật khẩu | Tối thiểu 12 ký tự, bao gồm cả chữ cái và chữ số. | | Tên thương hiệu | Hiển thị cho khách hàng của bạn (mặc định "Cloud"). Tối đa 60 ký tự. | | Email hỗ trợ | Mặc định là email admin. | ![Bước 3 của trình hướng dẫn với email quản trị viên, mật khẩu, tên thương hiệu và email hỗ trợ](https://nexcmp.com/vi/docs/images/getting-started/setup-wizard-03-admin.webp) Nhấp vào **Finish setup**. Panel sẽ khởi động lại (khoảng 1–2 giây) và trang sẽ chuyển bạn đến màn hình đăng nhập admin tại `https:///admin/`. Nếu địa chỉ đó chưa phản hồi (do DNS hoặc TLS đang xử lý), trang sẽ chuyển bạn đến `/` trên địa chỉ hiện tại để thay thế. ![Trình hướng dẫn sau khi hoàn tất với thông báo panel đang khởi động lại](https://nexcmp.com/vi/docs/images/getting-started/setup-wizard-03-done.webp) ## Những gì trình hướng dẫn thiết lập cho bạn {#what-the-wizard-sets-up-for-you} - Tên thương hiệu, URL trang web (`https://`), URL admin (`https:///admin`), URL console (`https:///console`), email hỗ trợ và tên người gửi. - Cài đặt mặc định cho các module đi kèm NexCMP: DDoS & BGP, AI và web SSH ở trạng thái **tắt**; đo lường băng thông ở trạng thái **bật**. Xem [Modules](https://nexcmp.com/vi/docs/infrastructure/modules/). - Nếu bạn đã kết nối CloudStack: provider #1, zone đầu tiên của nó, guest network và một key pair vận hành được gắn vào các VM của khách hàng để bạn có thể hỗ trợ họ. Tiếp theo: [Đăng nhập lần đầu](https://nexcmp.com/vi/docs/getting-started/first-login/). --- # Đăng nhập lần đầu và các bước tiếp theo {#first-login-and-next-steps} > **Vị trí trong trang quản trị:** trang đăng nhập là `/admin`; sau khi đăng nhập, trang đích là Overview › Dashboard. ## Địa chỉ truy cập {#addresses} | Nội dung | URL | |---|---| | Customer portal | `https:///` | | Admin console | `https:///admin` | | Thiết lập / khẩn cấp qua IP | `http://:3000/` (xem [cổng panel](https://nexcmp.com/vi/docs/getting-started/installation/#the-panel-port-3000)) | | Health check | `https:///healthz` | ## Đăng nhập {#sign-in} 1. Mở `https:///admin`. 2. Nhập email quản trị viên và mật khẩu bạn đã tạo trong trình hướng dẫn. 3. Bạn sẽ đến trang **Dashboard**. Một biểu ngữ ở đầu trang sẽ xuất hiện nếu license không hợp lệ hoặc chưa kết nối nguồn hạ tầng nào. ![Trang đăng nhập admin](https://nexcmp.com/vi/docs/images/getting-started/first-login-01-login.webp) ## Danh sách kiểm tra khuyến nghị {#recommended-checklist} Thực hiện lần lượt theo thứ tự — mỗi mục đều có liên kết đến trang tương ứng. | # | Tác vụ | Trang | |---|---|---| | 1 | Bật xác thực hai yếu tố cho tài khoản của bạn | [Security](https://nexcmp.com/vi/docs/administration/security/) | | 2 | Kết nối nguồn hạ tầng (nếu bạn đã chọn "Connect later") | [CloudStack](https://nexcmp.com/vi/docs/infrastructure/cloudstack/) hoặc [Proxmox VE](https://nexcmp.com/vi/docs/infrastructure/proxmox/) | | 3 | Kiểm tra zone và danh sách template máy / hệ điều hành | [Zones](https://nexcmp.com/vi/docs/infrastructure/zones/), [Templates](https://nexcmp.com/vi/docs/infrastructure/templates/) | | 4 | Xem lại các gói dịch vụ và bảng giá | [Gói cước](https://nexcmp.com/vi/docs/catalog/plans/) | | 5 | Thiết lập logo, màu sắc và các trang pháp lý | [Thương hiệu](https://nexcmp.com/vi/docs/customers/branding/), [Pháp lý](https://nexcmp.com/vi/docs/customers/legal/) | | 6 | Cấu hình email gửi đi và gửi thử nghiệm | [SMTP và email](https://nexcmp.com/vi/docs/administration/smtp-and-emails/) | | 7 | Bật ít nhất một kênh thanh toán và kiểm tra nạp tiền | [Kênh thanh toán](https://nexcmp.com/vi/docs/billing/payment-channels/) | | 8 | Quyết định những module bạn sẽ bán | [Module](https://nexcmp.com/vi/docs/infrastructure/modules/) | | 9 | Đặt đơn hàng thử nghiệm với vai trò khách hàng rồi xóa đi | [Đặt hàng](https://nexcmp.com/vi/docs/portal/ordering/) | | 10 | Tạo bản sao lưu đầu tiên | [Sao lưu và khôi phục](https://nexcmp.com/vi/docs/getting-started/backup-and-restore/) | ## Tạo đơn hàng đầu tiên của bạn (smoke test) {#create-your-first-order-smoke-test} 1. Mở customer portal trong cửa sổ riêng tư và đăng ký một tài khoản thử nghiệm. 2. Nạp tiền (bằng voucher hoặc thanh toán thử nghiệm). 3. Đặt gói cước nhỏ nhất trong zone của bạn. 4. Xem máy ảo xuất hiện trong admin tại Services › Virtual Machines, mở console của nó, sau đó hủy. Nếu VM không đạt trạng thái *running*, hãy mở **Infrastructure › Cloud provider › Sync & errors** và xem thông báo lỗi. --- # Cập nhật NexCMP {#updating-nexcmp} > **Vị trí trong admin:** System › Admin › License & updates (`/license`) → thẻ *Update*. ## Những gì bạn nhận được {#what-you-receive} | Loại bản phát hành | Thời điểm cung cấp | |---|---| | Bản vá bảo mật | **Luôn luôn**, ngay cả sau ngày "updates until" của bạn | | Bản phát hành tính năng | Chỉ khi được phát hành **vào hoặc trước** ngày "updates until" của bạn | Bạn có thể xem cả hai ngày này tại **License & updates**. Gia hạn quyền lợi tại [nexcmp.com/licenses](https://nexcmp.com/licenses). ## Cập nhật từ admin console {#update-from-the-admin-console} 1. Mở **System › Admin › License & updates**. 2. Trong thẻ **Update**, nhấp vào **Check for update**. Thẻ này sẽ hiển thị phiên bản hiện tại, phiên bản mới nhất bạn có thể cài đặt, thẻ *security* nếu có liên quan và changelog. 3. Nhấp vào **Update to X.Y.Z** và xác nhận. Chương trình sẽ tải bản phát hành, xác thực **chữ ký SHA-256 và Ed25519**, thay thế file binary theo phương thức nguyên tử (giữ lại bản sao `.bak`) và khởi động lại. Dự kiến thời gian downtime khoảng **10 giây**. 4. Tải lại trang và kiểm tra phiên bản ở góc trên bên phải của License & updates. ![Thẻ Update với phiên bản đang chạy và nút Check for new version](https://nexcmp.com/vi/docs/images/getting-started/updating-01-card.webp) ## Cập nhật từ dòng lệnh {#update-from-the-command-line} ```bash sudo nexcmp update ``` Lệnh này sẽ chạy trình cài đặt được tích hợp *bên trong bản phát hành hiện đang cài đặt* (không phải script được tải xuống tại thời điểm đó) cùng các tham số đã lưu từ `/etc/nexcmp/install.conf`. Thao tác này sẽ làm mới file binary, các systemd unit, template nginx và node agent, đồng thời giữ nguyên dữ liệu, cấu hình và tài khoản. ::: tip Không bao giờ hạ cấp Nếu máy chủ cung cấp phiên bản cũ hơn phiên bản đang chạy, trình cài đặt sẽ giữ nguyên phiên bản đang chạy. ::: ## Trước khi cập nhật {#before-you-update} 1. Tạo bản sao lưu: `sudo nexcmp backup` — xem [Sao lưu và khôi phục](https://nexcmp.com/vi/docs/getting-started/backup-and-restore/). 2. Đọc changelog trong thẻ Update. Về các thay đổi từ bản 1.3, xem [Release notes cho tới 1.6.1](https://nexcmp.com/vi/docs/getting-started/release-notes/), bao gồm bản cập nhật agent VPN và quy tắc định giá Bare Metal. 3. Cập nhật vào khoảng thời gian thấp điểm; các máy ảo đang chạy sẽ không bị ảnh hưởng, nhưng khách hàng không thể dùng portal trong vài giây. ## Sau khi cập nhật {#after-you-update} - Chạy `sudo nexcmp status` và xác nhận cả hai dịch vụ đều đang hoạt động. - Mở Dashboard quản trị và trang **Needs attention**. - Database migration tự động chạy khi khởi động phiên bản mới lần đầu. - Nếu bạn vận hành các VPN node, hãy cập nhật agent của chúng riêng và kiểm tra dữ liệu đo lường mức sử dụng. Việc cập nhật panel chỉ giúp cung cấp agent mới, chứ không đồng nghĩa mọi node từ xa đã chạy agent đó. Xem [VPN node data allowance](https://nexcmp.com/vi/docs/infrastructure/vpn-proxy-nodes/#data-allowance-on-a-vpn-node). Nếu cập nhật thất bại, xem [Lỗi cập nhật](https://nexcmp.com/vi/docs/troubleshooting/update-errors/). --- # Release notes {#release-notes} > **Vị trí trong admin:** System › Admin › License & updates (`/license`), thẻ **Update**. Các ghi chú này trình bày những thay đổi sau bản 1.3 cho đến **NexCMP 1.6.1**. Hãy sao lưu trước khi cập nhật và dùng bản phát hành được đề xuất trong thẻ **Update** của hệ thống. Xem [Updating NexCMP](https://nexcmp.com/vi/docs/getting-started/updating/) để biết các câu lệnh và bước kiểm tra chữ ký. ## 1.6.1 - **Số liệu Bare Metal:** mục **Overview** của khách hàng hiển thị các ô CPU, RAM, hoạt động đĩa và mạng kèm lịch sử gần đây. Các thông số thiếu sẽ hiển thị dấu gạch ngang cùng lý do. Dữ liệu mạng yêu cầu bộ đếm lưu lượng; chúng không được suy luận từ phần cứng iDRAC. - **Gói Bare Metal mẫu:** tên gói mẫu sử dụng `BM-40C-`. Các gói mẫu tích hợp sẵn mà bạn chưa chỉnh sửa sẽ nhận tên trung tính. Các gói đã chỉnh sửa được giữ nguyên, và gói đang được tham chiếu vẫn giữ nguyên mã của nó. Hãy kiểm tra phần cứng máy chủ thực tế trước khi mở bán gói. - **Thay đổi gói:** danh sách yêu cầu trong admin sắp xếp phía server và giữ cố định các nút thao tác khi cuộn ngang. - **Báo lỗi:** biểu mẫu cuộn mượt và luôn hiển thị các nút thao tác. Cơ chế che mật khẩu vẫn giữ nguyên văn bản chẩn đoán xung quanh. - **Tải trang:** tài nguyên trang và dữ liệu admin thường dùng được tải sớm hơn để giảm độ trễ khi điều hướng. Xem [Bare Metal setup, pricing and customer controls](https://nexcmp.com/vi/docs/infrastructure/dedicated/) và [Report a bug](https://nexcmp.com/vi/docs/administration/report-a-bug/). ## 1.6.0 - **Cài đặt Bare Metal:** nhập mạng iDRAC, địa chỉ máy chủ ISO và địa chỉ callback của panel trong **Safety › Management network connection**. Các giá trị mẫu sẽ chặn các thao tác thực tế cho đến khi được cấu hình. - **Lưu trữ ISO:** `sudo nexcmp dedicated-setup-iso` thiết lập web server ISO thuộc mạng quản trị. Trình cài đặt có thể cài đặt console và các công cụ ISO bằng `--baremetal` hoặc các tùy chọn ISO. Thiếu công cụ sẽ chặn các thao tác thực tế với lỗi `tools_missing`. - **Giá Bare Metal:** bản cài đặt mới hoặc chưa sử dụng sẽ bắt đầu bằng giá USD. Bản cài đặt đã có sẵn dữ liệu giá VND sẽ giữ nguyên VND và vẫn yêu cầu tỷ giá USD/VND. Cập nhật sẽ không tự chuyển đổi các mức giá hiện có đó sang USD. - **Trang máy chủ của khách hàng:** gia hạn trước, lên lịch thay đổi chu kỳ thanh toán, yêu cầu đổi gói, xem hóa đơn và xem thông tin đăng nhập OS sau khi cài đặt. Chủ sở hữu mới không thể xem mật khẩu của chủ sở hữu trước đó. - **Hồ sơ khách hàng:** tám tab phân nhóm tổng quan, dịch vụ, thanh toán, hạn ngạch, bảo mật, hỗ trợ, tiếp thị liên kết và nhật ký. Các dịch vụ dùng chung một bảng có thể tìm kiếm và sắp xếp. - **Thao tác dịch vụ:** khóa, mở khóa, hủy không hoàn tiền hoặc hủy kèm hoàn tiền đều dùng chung một hộp thoại. Tiền hoàn sẽ trả về ví ban đầu hoặc hạn mức tín dụng; cổng thanh toán không được hoàn tiền tự động. Xem [Dedicated servers](https://nexcmp.com/vi/docs/infrastructure/dedicated/) và [Managing customers](https://nexcmp.com/vi/docs/customers/managing-customers/). BYOIP và gắn subnet của khách hàng vào máy chủ Bare Metal vẫn chưa được hỗ trợ trong NexCMP. ## 1.5.2 Quản trị viên chính có thể mở **Report a bug** cạnh **Docs** và gửi ticket đến tài khoản license mà không cần đăng nhập riêng. Dữ liệu chẩn đoán là tùy chọn. Nhân viên, khách hàng và trợ lý AI không thể gửi báo cáo qua thao tác này. Xem [Report a bug](https://nexcmp.com/vi/docs/administration/report-a-bug/). ## 1.5.1 - **Lưu lượng VPN:** các node agent báo cáo lưu lượng về panel. Gói thuê bao dùng hết dung lượng GB cho phép sẽ bị ngắt kết nối; gói sẽ khả dụng trở lại sau khi nâng cấp băng thông hoặc sang kỳ mới. Các node không có báo cáo lưu lượng sẽ hiển thị **Not measured** và không bị ngắt kết nối theo GB. - **VPN agent:** phiên bản 1.5.1 thử lại các bản ghi lưu lượng chưa được xác nhận, gửi lưu lượng cuối cùng khi tắt và đóng các kết nối đang mở khi một endpoint bị dừng. Hãy cập nhật các remote agent cũng như panel. - **Các add-on VPN ngừng cung cấp:** High IP Reputation, High Concurrency và High Priority Network không còn được mở bán. Phí của các add-on này được xóa khỏi số tiền gia hạn tương lai của các gói thuê bao hiện có; các kỳ trước đó không được hoàn tiền. Nếu một add-on đã bị xóa khỏi catalog, hãy kiểm tra thủ công số tiền gia hạn. - **Nhãn giao thức:** IPv4 HTTP proxy là HTTP thuần. Địa chỉ IPv4 không xoay vòng. Cổng 443 của IPv6 proxy phục vụ SOCKS5; đây không phải là endpoint proxy HTTPS. - **Cài đặt mới:** quá trình khởi tạo cơ sở dữ liệu sẽ thử lại khi gặp xung đột migration tạm thời giữa panel và worker, do đó việc lưu provider đầu tiên không yêu cầu khởi động lại. Xem [Node VPN và IPv6 proxy](https://nexcmp.com/vi/docs/infrastructure/vpn-proxy-nodes/). ## 1.5.0 **AI Models** là module gateway và tính cước tùy chọn, tắt theo mặc định. Thêm các nguồn mô hình bạn vận hành hoặc được ủy quyền bán lại, đồng bộ mô hình, đặt giá và định tuyến, bật mô hình, sau đó mở bán. Hệ thống không đi kèm sẵn tài khoản nhà cung cấp, mô hình hay bảng giá nào. Module này tách biệt với module AI Chat và AI Agent. Xem [AI Models](https://nexcmp.com/vi/docs/infrastructure/ai-models/). ## 1.4.2 Việc cài đặt node IPv6 proxy sử dụng daemon và script mạng đi kèm trong gói phát hành. Panel cần `sshpass` để cài đặt SSH dựa trên mật khẩu. Panel chạy lịch xoay vòng địa chỉ, và quá trình thiết lập node sẽ loại trừ địa chỉ gateway khỏi việc phân bổ. Branding có thể đặt tên hiển thị tùy chỉnh cho dịch vụ VPN. Xem [Node VPN và IPv6 proxy](https://nexcmp.com/vi/docs/infrastructure/vpn-proxy-nodes/). ## 1.4.0–1.4.1 - **Quản trị AI:** hỗ trợ admin AI Chat, tài khoản AI cá nhân, admin API key, admin MCP server, connector OAuth, nhập/xuất cấu hình và checklist thiết lập. Xem [Cấu hình bằng AI](https://nexcmp.com/vi/docs/configure-with-ai/overview/). - **License:** quy trình Free và Source bao gồm các bản build chính thức và bản build tùy chỉnh từ mã nguồn. Tài khoản, cấp phép license, tải về và tài liệu hướng dẫn sử dụng `nexcmp.com`. Xem [License và mua hàng](https://nexcmp.com/vi/docs/getting-started/license-and-purchase/). - **Liên kết tài liệu:** **Docs** trong trang quản trị sẽ mở tài liệu hướng dẫn cho trang hiện tại. - **Tiền tệ:** bản cài đặt mới sẽ mặc định theo ngôn ngữ của khách hàng. Tỷ giá USD/VND được lấy từ bảng tỷ giá công khai hoặc tỷ giá cố định của bạn. Xem [Tiền tệ và tỷ giá hối đoái](https://nexcmp.com/vi/docs/catalog/currency-and-exchange-rates/). - **Zone đa nguồn:** bảng giá Cloud Server công khai hoạt động khi CloudStack và Proxmox VE dùng chung một zone. Các plan sử dụng nguồn hạ tầng riêng của mình. - **Giá tính từ offering:** tỷ lệ phần trăm là biên lợi nhuận tính trên giá bán. Biên lợi nhuận 40% trên chi phí $60 sẽ cho ra mức giá $100, trước khi làm tròn. ## Checklist nâng cấp {#upgrade-checklist} 1. Sao lưu, đọc thẻ **Update**, cập nhật và chạy `sudo nexcmp status`. 2. Cập nhật các VPN agent và xác nhận các node có báo cáo lưu lượng đo được trước khi dựa vào tính năng ngắt kết nối theo GB. 3. Nếu sử dụng Bare Metal, hãy kiểm tra các trường mạng quản trị, công cụ bắt buộc, đơn vị giá, template và các plan mẫu trước khi mở bán hoặc vận hành chính thức. 4. Mở hồ sơ khách hàng và xác minh danh sách dịch vụ. Kiểm tra số tiền và phân bổ thanh toán gốc trước khi xác nhận hủy dịch vụ có hoàn tiền. 5. Giữ các module tùy chọn ở trạng thái tắt cho đến khi hạ tầng của chúng sẵn sàng. Đối với AI Models, hãy xác minh provider, mô hình đã được định giá và một yêu cầu thành công từ khách hàng trước khi mở bán. --- # Sao lưu và khôi phục {#backup-and-restore} > **Vị trí trong admin:** System › Admin › Backup (`/backup`) chỉ xuất hiện khi module DDoS & BGP được bật; với bản cài đặt tiêu chuẩn, hãy dùng dòng lệnh bên dưới. ## Dữ liệu được sao lưu {#what-is-backed-up} `sudo nexcmp backup` tạo một file lưu trữ nén chứa: | Thành phần | Nội dung | |---|---| | `data/**/*.db` | Mọi cơ sở dữ liệu SQLite trong `/var/lib/nexcmp`, được sao chép bằng online backup API của SQLite — nhất quán ngay cả khi panel đang chạy | | `files.tar` | Toàn bộ tệp khác trong `/var/lib/nexcmp` (tệp cài đặt, nội dung tải lên cho branding, `secrets/`), ngoại trừ cơ sở dữ liệu và thư mục `updates/` | | `etc/` | Một bản sao của `/etc/nexcmp` (cài đặt bộ cài, instance ID, port và bind) | ::: warning File lưu trữ chứa master key của bạn `secrets/` lưu giữ key mã hóa các API key, thông tin thanh toán và mật khẩu SMTP được lưu trong cơ sở dữ liệu. File lưu trữ được tạo với quyền `0600`. Hãy lưu trữ tệp dưới dạng mã hóa và ở ngoài máy chủ. Không có các key này, cơ sở dữ liệu được khôi phục sẽ không thể giải mã các secret. ::: ## Tạo bản sao lưu {#take-a-backup} ```bash sudo nexcmp backup # writes to /var/backups/nexcmp sudo nexcmp backup /mnt/nas/nexcmp # or to another directory ``` Lệnh sẽ in ra đường dẫn file lưu trữ, ví dụ `/var/backups/nexcmp/nexcmp-backup-20261030-120000.tar.zst`. ### Lên lịch sao lưu {#schedule-it} ```bash echo '17 3 * * * root /usr/local/bin/nexcmp backup /var/backups/nexcmp && find /var/backups/nexcmp -name "nexcmp-backup-*" -mtime +14 -delete' | sudo tee /etc/cron.d/nexcmp-backup ``` Sao chép thư mục ra ngoài máy chủ (Object Storage, NAS, máy chủ khác). ## Khôi phục {#restore} Khôi phục sang máy chủ đã cài đặt NexCMP **cùng phiên bản (hoặc mới hơn)**. 1. Cài đặt NexCMP bằng [installer](https://nexcmp.com/vi/docs/getting-started/installation/) với cùng license và domain, nhưng **không** chạy setup wizard. 2. Dừng các dịch vụ: ```bash sudo systemctl stop nexcmp-vmd nexcmp ``` 3. Giải nén file lưu trữ vào một thư mục tạm: ```bash sudo mkdir /root/restore && sudo tar --zstd -xf nexcmp-backup-20261030-120000.tar.zst -C /root/restore ``` 4. Đưa các tệp trở lại vị trí: ```bash sudo tar -xf /root/restore/files.tar -C /var/lib/nexcmp sudo cp -a /root/restore/data/. /var/lib/nexcmp/ sudo cp -a /root/restore/etc/. /etc/nexcmp/ sudo chown -R nexcmp:nexcmp /var/lib/nexcmp ``` 5. Khởi động các dịch vụ và kiểm tra: ```bash sudo systemctl start nexcmp nexcmp-vmd sudo nexcmp status ``` 6. Đăng nhập vào `https:///admin` bằng tài khoản administrator của hệ thống *được sao lưu*. ::: tip Diễn tập trước Hãy thực hiện bước 1–6 trên máy chủ dự phòng một lần trước khi bạn thực sự cần đến. Bản sao lưu chưa từng được khôi phục thử chỉ là một niềm hy vọng. ::: ## Không bao gồm {#not-included} - Cấu hình nginx và chứng chỉ (được bộ cài tạo lại; chứng chỉ Let's Encrypt sẽ được cấp lại). - Các máy chủ CloudStack / Proxmox VE và máy ảo trên đó — hãy sao lưu bằng các công cụ riêng của chúng. --- # Gỡ cài đặt NexCMP {#uninstall-nexcmp} ::: warning Khách hàng sẽ mất quyền truy cập Việc gỡ cài đặt sẽ dừng portal và hệ thống thanh toán. Các máy ảo trên CloudStack hoặc Proxmox VE của bạn vẫn tiếp tục chạy, nhưng sẽ không còn gì quản lý hay tính cước chúng. Hãy tạo một bản [sao lưu](https://nexcmp.com/vi/docs/getting-started/backup-and-restore/) trước. ::: ## Gỡ bỏ chương trình, giữ lại dữ liệu {#remove-the-program-keep-the-data} ```bash sudo nexcmp uninstall ``` Thao tác này sẽ vô hiệu hóa và gỡ bỏ các service `nexcmp` và `nexcmp-vmd`, nginx site và snippet, `/opt/nexcmp` cùng lệnh `nexcmp`. **Dữ liệu vẫn được giữ lại** trong `/var/lib/nexcmp` và `/etc/nexcmp`, nên nếu cài đặt lại sau này trên cùng một server, bạn có thể tiếp tục từ điểm đã dừng. ## Xóa toàn bộ {#remove-everything} ```bash sudo nexcmp uninstall --purge ``` Đồng thời xóa `/var/lib/nexcmp`, `/etc/nexcmp`, `/var/log/nexcmp` và user hệ thống `nexcmp`. Thao tác này không thể hoàn tác. ## Sau khi gỡ cài đặt {#after-uninstalling} - Các chứng chỉ Let's Encrypt cùng gói `nginx` / `certbot` được giữ nguyên. Bạn có thể xóa chứng chỉ bằng `sudo certbot delete --cert-name ` nếu muốn. - Giải phóng domain trên trang license của bạn tại [nexcmp.com/licenses](https://nexcmp.com/licenses) nếu bạn định kích hoạt nó ở nơi khác. - Xóa tài khoản CloudStack / Proxmox API token chuyên dụng đã tạo cho NexCMP nếu bạn không còn cần đến chúng nữa. --- # Tham chiếu lệnh `nexcmp` {#nexcmp-command-reference} Trình cài đặt đặt một công cụ hỗ trợ tại `/usr/local/bin/nexcmp`. Hãy chạy nó trên server NexCMP. Các lệnh thay đổi hệ thống cần `sudo`. (Công cụ phía khách hàng dành cho API là một chương trình khác, xem [cmp CLI](https://nexcmp.com/vi/docs/developers/cmp-cli/).) | Lệnh | Cần quyền root | Chức năng | |---|---|---| | `nexcmp status` | Không (chi tiết hơn với `sudo`) | Phiên bản, trạng thái service (`nexcmp`, `nexcmp-vmd`), `/healthz`, tóm tắt license, trạng thái public-port, setup code nếu trình hướng dẫn chưa hoàn tất | | `nexcmp update` | Có | Chạy trình cài đặt đi kèm trong bản phát hành đã cài đặt với các tham số đã lưu — xem [Cập nhật](https://nexcmp.com/vi/docs/getting-started/updating/) | | `nexcmp backup [dir]` | Có | Sao lưu vào `/var/backups/nexcmp` (hoặc `dir`) — xem [Sao lưu và khôi phục](https://nexcmp.com/vi/docs/getting-started/backup-and-restore/) | | `nexcmp uninstall [--purge]` | Có | Gỡ bỏ các service và chương trình; `--purge` cũng xóa dữ liệu — xem [Gỡ cài đặt](https://nexcmp.com/vi/docs/getting-started/uninstall/) | | `nexcmp open-port [minutes]` | Có | Chế độ **khẩn cấp**: lắng nghe trên cổng panel (mặc định 3000) trên mọi interface trong 1–1440 phút (mặc định 30), sau đó tự động đóng | | `nexcmp close-port` | Có | Đóng cửa sổ khẩn cấp ngay bây giờ | | `nexcmp fix-owner` | Có | Chuyển quyền sở hữu các tệp trong `/var/lib/nexcmp` thuộc về root về lại cho người dùng `nexcmp` | ## `nexcmp status` ```text Version : 1.6.1 nexcmp : active nexcmp-vmd : active healthz : ok License : active · domain cloud.example.com · token valid until 2026-11-12 · updates until 2027-10-30 Public port: 127.0.0.1 only (nginx proxy; emergency: sudo nexcmp open-port) ``` Nếu các tệp trong thư mục dữ liệu thuộc quyền sở hữu của root (ví dụ: được tạo khi chạy lệnh `nexcmp` khác bằng `sudo` dưới quyền root), `status` sẽ in cảnh báo vì service user không thể đọc chúng — triệu chứng điển hình là license báo lỗi HTTP 421. Khắc phục bằng `sudo nexcmp fix-owner`. Bản vá này cũng tự động chạy mỗi khi service khởi động. ## Truy cập khẩn cấp {#emergency-access} Khi domain, nginx hoặc TLS gặp sự cố, bạn vẫn có thể truy cập panel: ```bash sudo nexcmp open-port 30 # http://:3000/ for 30 minutes sudo nexcmp close-port # close it earlier ``` An toàn hơn mà không cần mở cổng công khai: `ssh -L 3000:127.0.0.1:3000 user@server` và truy cập `http://127.0.0.1:3000/`. ## Môi trường {#environment} | Biến | Mục đích | |---|---| | `NEXCMP_BASE` | Ghi đè URL gốc của license server (mặc định `https://nexcmp.com`); chỉ dùng để kiểm thử | Tệp và thư mục: chương trình `/opt/nexcmp`, cấu hình `/etc/nexcmp`, dữ liệu `/var/lib/nexcmp`, nhật ký `/var/log/nexcmp` và `journalctl -u nexcmp -u nexcmp-vmd`. --- # Yêu cầu hạ tầng {#infrastructure-requirements} > **Vị trí trong admin:** Infrastructure (khu vực menu bên trái) và System › Admin › License & updates (`/license`) để bật module. Trang này liệt kê những gì mỗi module cần **bên ngoài** máy chủ NexCMP. Về bản thân máy chủ (Ubuntu, bộ nhớ, ổ đĩa, port), xem [Yêu cầu đối với máy chủ NexCMP](https://nexcmp.com/vi/docs/getting-started/requirements/). Để bật module, xem [Modules](https://nexcmp.com/vi/docs/infrastructure/modules/). ## Từng module {#module-by-module} | Module | Hạ tầng tối thiểu | Chi tiết | |---|---|---| | **Máy ảo trên CloudStack** | Apache CloudStack 4.23 (đã kiểm thử), KVM, một advanced zone có guest network và dải IP public; một domain và account chuyên dụng kèm API key (tuyệt đối không dùng ROOT); tối thiểu một template sẵn sàng và một service offering | [CloudStack](https://nexcmp.com/vi/docs/infrastructure/cloudstack/) | | **Máy ảo trên Proxmox VE** | Proxmox VE 9.x (đã xác thực trên 9.2); một API token với role tùy chỉnh; storage hỗ trợ clone; một bridge; một khối IPv4 kèm gateway; một cloud-init template cho mỗi OS và mỗi node | [Proxmox VE](https://nexcmp.com/vi/docs/infrastructure/proxmox/) | | **OS template** | CloudStack: một máy build Linux có libguestfs và web server cho image. Proxmox VE: các cloud-image template có guest agent | [OS template](https://nexcmp.com/vi/docs/infrastructure/templates/) | | **Bare metal / Dedicated Server** | Máy chủ Dell với iDRAC 9 có thể truy cập qua HTTPS (Redfish) từ panel trong mạng quản trị; một HTTP server trong mạng đó để phân phối file ISO; các thư mục ISO có quyền ghi cho dịch vụ NexCMP | [Dedicated server](https://nexcmp.com/vi/docs/infrastructure/dedicated/) | | **AI Models** | Một hoặc nhiều nguồn model mà bạn được phép bán lại, với API tương thích OpenAI hoặc tương thích Anthropic và khóa API riêng của bạn; kết nối HTTPS chiều đi (cổng 443, tên miền công khai) từ panel đến từng nguồn, hoặc một gateway nội bộ được liệt kê trong Allowed internal hosts; không cần GPU hay phần cứng đặc biệt | [AI Models](https://nexcmp.com/vi/docs/infrastructure/ai-models/) | | **VPN** | Một hoặc nhiều host Linux (x86_64, systemd, root) có địa chỉ IPv4 public trên interface hoặc được định tuyến tới đó, kết nối HTTPS outbound tới panel của bạn | [Node VPN và proxy](https://nexcmp.com/vi/docs/infrastructure/vpn-proxy-nodes/) | | **IPv6 Proxy** | Các host Linux (x86_64, systemd, `nft`, `ip`, `ss`, `sysctl`) có IPv4 public, các port 80, 443 và 60001-65535 còn trống, cùng một tiền tố IPv6 từ /32 đến /64 hoạt động được cho lưu lượng outbound; quyền truy cập SSH bằng mật khẩu cho lần cài đặt ban đầu | [Node VPN và proxy](https://nexcmp.com/vi/docs/infrastructure/vpn-proxy-nodes/) | | **Object Storage (S3)** | Một cụm Ceph có RADOS Gateway (RGW), user Admin Ops, và một endpoint HTTPS public trên port 443 | [S3](https://nexcmp.com/vi/docs/infrastructure/s3/) | | **Kubernetes** | CloudStack đã bật Kubernetes Service (CKS), tối thiểu một ISO phiên bản Kubernetes, và một service offering miễn phí cho control-plane với chính xác 2 vCPU và 2048 MB | [Kubernetes và Private Cloud](https://nexcmp.com/vi/docs/infrastructure/kubernetes-and-private-cloud/) | | **Private Cloud** | CloudStack có một VPC offering và một network offering cho mỗi gói băng thông (cộng thêm một offering 1 Mbps bị khóa) | [Kubernetes và Private Cloud](https://nexcmp.com/vi/docs/infrastructure/kubernetes-and-private-cloud/) | | **OS & ISO Images** | CloudStack có secondary storage VM kết nối được Internet để tải xuống image của khách hàng (liên kết trực tiếp, không chuyển hướng); tài khoản CloudStack có quyền đăng ký template và ISO | [Module](https://nexcmp.com/vi/docs/infrastructure/modules/) | | **Bandwidth** | Không cần thêm gì với nguồn mặc định: mức sử dụng được đọc từ số liệu thống kê VM của CloudStack. Các VM trên Proxmox VE không được đo lường | [Bandwidth](https://nexcmp.com/vi/docs/catalog/bandwidth/) | | **AI Chat and AI Agent** | Một API tương thích OpenAI (base URL, model và key) mà server panel có thể truy cập. Không cần phần mềm bổ sung trên server của bạn | [Nhà cung cấp AI](https://nexcmp.com/vi/docs/ai/ai-providers/) | | **DDoS & BGP** | Gói add-on yêu cầu một host edge router chạy các daemon với quyền root (BGP, lọc gói tin, thống kê luồng dữ liệu). Gói này không thuộc bản cài đặt tiêu chuẩn | [Module](https://nexcmp.com/vi/docs/infrastructure/modules/) | | **DDoS Shield** | Gói add-on DDoS & BGP | [Module](https://nexcmp.com/vi/docs/infrastructure/modules/) | | **Web SSH terminal** | Một dịch vụ SSH proxy riêng biệt và một route tương ứng. Thành phần này không thuộc bản cài đặt tiêu chuẩn; AI Agent không cần đến nó | [Module](https://nexcmp.com/vi/docs/infrastructure/modules/) | ## Tổng quan đường truyền mạng {#network-paths-at-a-glance} | Từ | Đến | Cổng | Mục đích | |---|---|---|---| | Panel server | CloudStack management server | 443 hoặc 8080 (tùy cách bạn publish) | API | | Panel server | Proxmox VE node | 8006/tcp | API và console | | Panel server | Dell iDRAC | 443/tcp (và cổng VNC, mặc định 5901) | Redfish và console | | iDRAC | ISO web server | cổng HTTP bạn chọn (ví dụ: 8080) | Virtual media | | Panel server | Ceph RGW | 443/tcp | Admin Ops | | Panel server | IPv6 proxy node | Cổng SSH bạn nhập | Cài đặt một lần | | VPN và proxy node | Panel (qua nginx) | 443/tcp | Enrollment, heartbeat, cấu hình | | Khách hàng | VPN và proxy node | các cổng theo IP 65001-65535 (VPN); 80, 443, 60001-65535 (IPv6 proxy) | Bản thân dịch vụ | ::: tip Giữ mạng quản trị ở chế độ riêng tư Địa chỉ quản trị iDRAC và hypervisor phải nằm trên mạng mà khách hàng không thể truy cập. NexCMP từ chối các địa chỉ iDRAC nằm ngoài dải IP riêng tư bạn cho phép. ::: ## Checklist trước khi mở bán {#checklist-before-you-sell} 1. Hạ tầng phía sau dịch vụ đầu tiên đã được kết nối và **Test connection** hiển thị xanh. 2. Một zone đã sẵn sàng mở bán (xem [Zones](https://nexcmp.com/vi/docs/infrastructure/zones/)): backend đang hoạt động, có một gói dịch vụ và một template sẵn sàng. 3. Đã cấu hình kênh thanh toán (xem [Payment channels](https://nexcmp.com/vi/docs/billing/payment-channels/)). 4. E-mail hoạt động bình thường (xem [SMTP and e-mails](https://nexcmp.com/vi/docs/administration/smtp-and-emails/)). 5. Bạn đã tạo thử một đơn hàng và xóa VM đó. --- # Kiến trúc {#architecture} > **Vị trí trong trang admin:** đây là trang tài liệu tham khảo. Các dịch vụ được mô tả ở đây có thể xem bằng `sudo nexcmp status`; các kết nối được cấu hình tại Infrastructure và System › Settings. ## Sơ đồ minh họa {#the-picture} ![Kiến trúc NexCMP: khách hàng truy cập nginx qua DNS và tùy chọn Cloudflare, nginx proxy đến panel trên cổng 3000, panel và worker gọi đến CloudStack, Proxmox VE, iDRAC, Ceph, cổng thanh toán, SMTP và nhà cung cấp AI, còn các VPN và IPv6 proxy node kết nối ngược về panel](https://nexcmp.com/vi/docs/images/infrastructure/architecture.svg) ### Diễn giải sơ đồ chi tiết {#the-same-diagram-in-words} 1. Khách hàng hoặc quản trị viên mở `https://cloud.example.com` (portal), `https://cloud.example.com/admin` (admin console) hoặc gọi REST API. DNS trỏ tên miền về server của bạn, hoặc về Cloudflare để proxy tới đó. 2. **nginx** trên panel server lắng nghe trên cổng 80 (chuyển hướng và gia hạn chứng chỉ) và 443 (TLS), sau đó chuyển tiếp mọi request đến **panel** trên `127.0.0.1:3000`. Sau trình cài đặt ban đầu (setup wizard), panel chỉ lắng nghe trên giao diện loopback. 3. **panel** (`nexcmp.service`) phục vụ customer portal, admin console, REST API, setup wizard và các bản tải xuống cần thiết cho node (agent binary, script cài đặt, công cụ dòng lệnh `cmp`). Nó cũng kiểm tra license của bạn mỗi ngày một lần. 4. **Worker** (`nexcmp-vmd.service`) lắng nghe trên `127.0.0.1:8112`, chỉ khả dụng cục bộ. Tiến trình này chạy mọi tác vụ tốn thời gian hoặc cần thực thi theo lịch trình: tác vụ cấp phát tài nguyên, đồng bộ hóa với CloudStack và Proxmox VE, chu kỳ tính phí (billing ticks), thu thập băng thông và các kết nối console trên trình duyệt. 5. Từ hai tiến trình này, NexCMP gọi ra bên ngoài: **CloudStack** (management API), **Proxmox VE** (API trên cổng 8006, ghim chứng chỉ), **Dell iDRAC** (Redfish qua HTTPS trên mạng quản trị), **Ceph RGW** (S3 và Admin Ops qua HTTPS), **cổng thanh toán** (Stripe, PayPal, USDT và các đơn vị chuyển khoản ngân hàng, những bên này cũng sẽ gọi đến webhook URL của bạn), **máy chủ SMTP của bạn**, một **nhà cung cấp AI** tương thích API OpenAI, và tùy chọn **Telegram**. 6. **Các node VPN** chạy `cmp-agent`. Mỗi node đăng ký một lần bằng token dùng một lần, sau đó gửi heartbeat định kỳ 5 giây một lần qua HTTPS tới panel và nhận cấu hình trong phản hồi. **Các node proxy IPv6** được panel cài đặt một lần qua SSH, sau đó sẽ tự kéo cấu hình từ panel về. 7. Dữ liệu trạng thái được lưu trong các cơ sở dữ liệu SQLite và một số tệp trong `/var/lib/nexcmp`. Thông tin xác thực cho CloudStack, Proxmox, S3, iDRAC và nhà cung cấp AI được lưu trữ mã hóa (AES-256-GCM) cùng các tệp khóa master trong cùng khu vực này. ## Dịch vụ và tiến trình {#services-and-processes} | Tiến trình | Chạy dưới quyền | Lắng nghe trên | Nhiệm vụ | |---|---|---|---| | `nginx` | root (worker `www-data`) | 80, 443 | TLS, chuyển hướng, proxy tới panel | | `nexcmp` | `nexcmp` | 3000 (tất cả interface khi cài đặt lần đầu, sau đó là `127.0.0.1`) | Portal, admin console, API, wizard, tải xuống | | `nexcmp-vmd` | `nexcmp` | `127.0.0.1:8112` | Tác vụ, đồng bộ, tính phí, băng thông, console | | `nexcmp-update` | root | không có | Áp dụng các bản cập nhật do admin console yêu cầu (một path unit sẽ chờ yêu cầu) | | `cmp-agent` (trên các node VPN) | root | các cổng lắng nghe VPN | Báo cáo về panel, chạy các proxy listener trên IPv4 công cộng | Panel và worker chạy dưới quyền người dùng thông thường không có bất kỳ Linux capability nào, với hệ thống tệp ở chế độ chỉ đọc ngoại trừ `/var/lib/nexcmp` và `/var/log/nexcmp`. Cả hai không cần root, không cần Docker, không cần cơ sở dữ liệu riêng biệt và không cần Redis. ## Tệp tin và vị trí lưu trữ {#files-and-where-they-are} | Đường dẫn | Nội dung | |---|---| | `/opt/nexcmp` | Chương trình: các bản phát hành, `bin/`, các tệp dùng chung như trình tạo template. Thuộc sở hữu của root, chỉ đọc đối với dịch vụ. | | `/etc/nexcmp` | Cài đặt của bộ cài (`install.conf`), cổng và liên kết bind (`nexcmp.env`). | | `/var/lib/nexcmp` | Các cơ sở dữ liệu SQLite, thương hiệu đã tải lên, thư mục tải agent, trạng thái giấy phép, các tệp khóa master. Hãy sao lưu phần này. | | `/var/log/nexcmp` | Nhật ký. | Xem [Backup and restore](https://nexcmp.com/vi/docs/getting-started/backup-and-restore/). Các tệp khóa master phải được sao lưu cùng với cơ sở dữ liệu, nếu không cơ sở dữ liệu sau khi khôi phục sẽ không thể giải mã các thông tin xác thực đã lưu. ## Sơ đồ kết nối giữa các thành phần {#who-connects-to-whom} | Chiều | Đường dẫn | Cổng | Ghi chú | |---|---|---|---| | Khách hàng tới panel | Internet, DNS, Cloudflare tùy chọn, nginx | 443 | Xem [DNS and Cloudflare](https://nexcmp.com/vi/docs/getting-started/dns-and-cloudflare/). | | Panel tới máy chủ giấy phép | `nexcmp.com` | 443 | Kích hoạt, kiểm tra hàng ngày và cập nhật. | | Panel tới CloudStack | API | 443 hoặc 8080 | Console của VM, băng thông và các tính năng Kubernetes đều sử dụng cùng một endpoint. | | Panel tới Proxmox VE | API và WebSocket console | 8006 | Chứng chỉ được ghim bằng SHA-256. | | Panel tới iDRAC | Redfish | 443, VNC 5901 | Chỉ mạng quản lý. | | iDRAC đến ISO server | HTTP | cổng của bạn | iDRAC tải file ISO về. | | Panel đến Ceph RGW | Admin Ops | 443 | | | Panel đến SMTP | SMTP | 587 hoặc 465 | | | Panel đến nhà cung cấp AI | HTTPS | 443 | Chỉ khi module AI được bật. | | Cổng thanh toán đến panel | Webhook | 443 | Stripe và PayPal gửi callback. | | Node đến panel | `cmp-agent` | 443 | Enroll, heartbeat, nâng cấp. | | Panel đến node proxy IPv6 | SSH | cổng bạn nhập | Chỉ dùng một lần khi cài đặt. | ## Tầm quan trọng {#why-it-matters} - **Panel có thể truy cập được là panel có thể bị tấn công.** Hãy đóng cổng 3000 sau khi hoàn tất trình hướng dẫn thiết lập. Trình cài đặt đã tự động làm việc này khi TLS hoạt động. - **Worker phải đang chạy** để hệ thống có thể tạo tài nguyên hoặc tính cước. `sudo nexcmp status` hiển thị cả hai dịch vụ và bước kiểm tra trạng thái hoạt động. - **Lập kế hoạch tường lửa chiều ra.** Nếu lưu lượng outbound của máy chủ panel bị lọc, hãy cho phép các đích đến trong bảng trên. - **Lưu lượng quản lý không đi qua đường truyền công cộng.** Các kết nối đến CloudStack, Proxmox VE, iDRAC và Ceph đi thẳng từ máy chủ panel tới các hệ thống đó, không bao giờ qua nginx hoặc Cloudflare. --- # Module {#modules} > **Vị trí trong admin:** System › Admin › License & updates (`/license`), thẻ **Module**. ## Chức năng {#what-it-does} Module là một dịch vụ hoặc tính năng bạn có thể bật hoặc tắt toàn bộ. Một module ở trạng thái **tắt** sẽ bị ẩn khỏi menu admin và khách hàng không thể mua; các route API của nó sẽ trả lời `404 module_disabled` nếu module đó là add-on. Bật một module chỉ hiển thị tính năng: hạ tầng phía sau vẫn cần được kết nối (xem cột cuối cùng). ## Yêu cầu {#requirements} | Hạng mục | Yêu cầu | |---|---| | Tài khoản | Quản trị viên có quyền ghi. Nhân sự chỉ có quyền đọc có thể thấy các nút bật/tắt nhưng không thể thay đổi. | | Hạ tầng | Xem bảng: mỗi module liệt kê những gì cần thiết. | | Phụ thuộc vào | Một số module cần các module khác (DDoS Shield cần DDoS & BGP). | ## Chuẩn bị hạ tầng {#prepare-the-infrastructure} Không bắt buộc đối với thao tác gạt nút. Hãy kết nối hạ tầng của từng module theo mô tả trên trang được liên kết trong bảng. ## Kết nối trong NexCMP {#connect-in-nexcmp} 1. Mở **System › Admin › License & updates** và cuộn tới thẻ **Module**. Thẻ này cho biết các module bị tắt sẽ ẩn khỏi menu admin và khách hàng không thể mua. 2. Gạt công tắc của module. Trang xác nhận **Saved: reloading menu** và tải lại, nên menu sẽ thay đổi ngay lập tức. ![Thẻ Module trong License & updates với công tắc cho từng module](https://nexcmp.com/vi/docs/images/infrastructure/modules-01-license-modules.webp) ### Các module {#the-modules} | Module (như hiển thị) | Mặc định | Tính năng bổ sung | Cần có | Trang | |---|---|---|---|---| | **Virtual Machines** | luôn bật | Danh mục VM, đơn hàng, console, snapshots | CloudStack hoặc Proxmox VE | [CloudStack](https://nexcmp.com/vi/docs/infrastructure/cloudstack/), [Proxmox VE](https://nexcmp.com/vi/docs/infrastructure/proxmox/) | | **Bandwidth** | **bật** | Quota, add-on, cảnh báo và xử lý vượt mức cho VM, Kubernetes và S3 | Không cần cấu hình thêm (thống kê VM từ CloudStack) | [Bandwidth](https://nexcmp.com/vi/docs/catalog/bandwidth/) | | **OS & ISO Images** | tắt | Khách hàng tự đăng ký image hệ điều hành và ISO, tính phí theo GB | CloudStack; quyền truy cập Internet cho secondary storage VM của hệ thống | [Yêu cầu](https://nexcmp.com/vi/docs/infrastructure/requirements/) | | **Kubernetes** | tắt | Cluster Kubernetes (CKS) | CloudStack đã bật CKS | [Kubernetes và Private Cloud](https://nexcmp.com/vi/docs/infrastructure/kubernetes-and-private-cloud/) | | **Private Cloud** | tắt | VPC với các gói băng thông chuyên dụng | CloudStack VPC và network offering | [Kubernetes và Private Cloud](https://nexcmp.com/vi/docs/infrastructure/kubernetes-and-private-cloud/) | | **Object Storage** | tắt | Tài khoản S3 trên Ceph RGW, pay-as-you-go | Ceph RGW và một zone có dịch vụ S3 | [S3](https://nexcmp.com/vi/docs/infrastructure/s3/) | | **VPN** | tắt | VPN trên các node của chính bạn | Các node chạy `cmp-agent` | [Node VPN và proxy](https://nexcmp.com/vi/docs/infrastructure/vpn-proxy-nodes/) | | **IPv6 Proxy** | tắt | IPv6 proxy trên các node của chính bạn | Các node proxy có prefix IPv6 | [Node VPN và proxy](https://nexcmp.com/vi/docs/infrastructure/vpn-proxy-nodes/) | | **Bare Metal** | tắt | Máy chủ Dell qua iDRAC: đơn hàng, cài đặt hệ điều hành, console, nguồn | iDRAC 9 trên mạng quản trị (management network) | [Dedicated server](https://nexcmp.com/vi/docs/infrastructure/dedicated/) | | **AI Models** | tắt | Một gateway để bán quyền truy cập AI model: một khóa cho nhiều model, định giá theo từng model, giới hạn sử dụng, nhật ký và thanh toán qua ví | Nguồn model do bạn tự cung cấp: API tương thích OpenAI hoặc tương thích Anthropic kèm khóa API riêng của bạn | [AI Models](https://nexcmp.com/vi/docs/infrastructure/ai-models/) | | **AI** | tắt | AI Chat (hỗ trợ tự động) và AI Agent (quản trị VM bằng ngôn ngữ tự nhiên) | Nhà cung cấp tương thích OpenAI | [Nhà cung cấp AI](https://nexcmp.com/vi/docs/ai/ai-providers/) | | **DDoS Shield** | tắt | Bảo vệ IP cho khách hàng; cần DDoS & BGP, nên switch của tính năng này sẽ bị vô hiệu hóa nếu thiếu nó | Gói add-on DDoS & BGP | bên dưới | | **DDoS & BGP** | tắt, **add-on** | Console edge router: BGP, RTBH, XDP, session và lưu lượng edge | Một edge host chạy các daemon quyền root | bên dưới | ### Chức năng của từng switch {#which-switch-does-what} - **Bare Metal** có hai tầng. Switch module sẽ hiển thị menu quản trị và API. Việc mở bán cho khách hàng là một switch riêng biệt yêu cầu nhập xác nhận tại **Services › Dedicated Server**, và mọi thao tác ghi tới iDRAC đều bị chặn cho đến khi bạn bật **live ops** tại **Infrastructure › Bare Metal › Safety**. Xem [Máy chủ riêng](https://nexcmp.com/vi/docs/infrastructure/dedicated/). - Đối với **Kubernetes**, **Private Cloud**, **VPN**, **IPv6 Proxy** và **Images**, switch module và switch bán hàng trên trang dịch vụ tác động lên cùng một cài đặt. - **AI** cũng cần được cấu hình nhà cung cấp tại **System › Settings › AI provider**. - **AI Models** có hai tầng. Công tắc module sẽ hiển thị menu quản trị và API. Bán cho khách hàng là một công tắc bán riêng biệt ở đầu các trang AI Models, mặc định tắt. Xem [AI Models](https://nexcmp.com/vi/docs/infrastructure/ai-models/). ### Các module được đọc khi khởi động {#modules-read-at-start-up} Ba tính năng này không phải là switch thông thường. Chúng được đọc **một lần khi dịch vụ khởi động** và yêu cầu hạ tầng mà bản cài đặt tiêu chuẩn không có sẵn. | Tính năng | Cài đặt | Trạng thái | Yêu cầu cần có | |---|---|---|---| | DDoS & BGP | `module_ddos` | Hiển thị là **Add-on package** khi tắt, **Installed** khi bật. Không có switch trong console. | Các daemon edge router (BGP, RTBH, XDP, flow statistics) chạy dưới quyền root. Panel chạy dưới quyền người dùng không có đặc quyền và không thể thực thi chúng. | | AI | `module_ai` | Một switch thông thường. Các route sẽ cập nhật ngay lập tức; các background job của AI Chat (điều tra ticket, phản hồi theo lịch) sẽ bắt đầu vào lần khởi động lại dịch vụ tiếp theo. Console hiển thị khuyến nghị nên khởi động lại. | Nhà cung cấp AI. | | Terminal Web SSH | `feature_ssh_web` | Tắt theo mặc định, không có nút bật/tắt trong console | Một dịch vụ SSH proxy riêng biệt và route của nó. Nếu không có, tab Console của portal chỉ hiển thị VNC. **AI Agent không cần thành phần này**: nó chạy lệnh qua kết nối SSH do chính panel tự thiết lập. | Sau khi thay đổi thiết lập khởi động, hãy khởi động lại các dịch vụ: `sudo systemctl restart nexcmp nexcmp-vmd`. ## Kiểm tra {#verify} 1. Mục menu của module xuất hiện (hoặc biến mất) sau khi tải lại. 2. Với module hiển thị cho khách hàng, portal sẽ hiển thị mục menu mới khi khách hàng đăng nhập. Module bị tắt sẽ không hiển thị gì hoặc báo "coming soon". ## Giới hạn và lưu ý {#limits-and-notes} - Tắt module không làm xóa bất kỳ thứ gì. Các VM, cluster, tài khoản S3 và gói đăng ký đang hoạt động vẫn tiếp tục chạy và tính phí; khách hàng chỉ không thể tạo mới. - Trang hạn ngạch chỉ liệt kê các dịch vụ có module đang bật. ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | Mục menu không xuất hiện | Trang chưa được tải lại | Tải lại admin console. | | Nút bật/tắt DDoS Shield bị vô hiệu hóa | Chưa cài đặt DDoS & BGP | DDoS Shield cần add-on DDoS & BGP. | | "This module is an add-on package and cannot be switched here" (HTTP 409 hoặc 422) | Bạn (hoặc script) đã thử bật/tắt DDoS & BGP | Đây là gói add-on; không có nút bật/tắt. | | "DDoS Shield cần tiện ích bổ sung DDoS & BGP" | Tương tự, đối với DDoS Shield | Hãy cài đặt add-on trước. | | Route của module trả về 404 `module_disabled` | Module đang tắt | Bật module lên. | | AI Chat phản hồi nhưng điều tra ticket không bao giờ bắt đầu | Module AI đã được bật mà chưa khởi động lại | `sudo systemctl restart nexcmp nexcmp-vmd`. | | Nhân viên chỉ có quyền đọc không thể lưu | Vai trò của họ là chỉ đọc | Sử dụng tài khoản administrator. | --- # Zone {#zones} > **Vị trí trong admin:** Infrastructure › Datacenter › Zone (`/infra/zones`). Trang chi tiết của zone là `/infra/zones/`. ## Chức năng {#what-it-does} Một **zone** là vị trí mà khách hàng chọn khi đặt hàng: quốc gia và thành phố kèm quốc kỳ, cùng các dịch vụ được bán tại đó. Đây là khái niệm bán hàng, tách biệt với các zone, cluster và node của nền tảng phía sau. Đằng sau zone, bạn gắn **hạ tầng**: một CloudStack zone, một cluster Proxmox VE, các node VPN kèm dải IP, một S3 backend. Zone 1 được tạo bởi [trình hướng dẫn thiết lập](https://nexcmp.com/vi/docs/getting-started/setup-wizard/), với tên hiển thị và quốc gia bạn đã nhập. Thêm các zone khác khi bạn có hạ tầng ở nhiều nơi hơn, hoặc để gán vị trí riêng cho VPN và S3. ## Yêu cầu {#requirements} | Hạng mục | Yêu cầu | |---|---| | Quyền hạn | Tài khoản administrator. Vai trò nhân viên chỉ đọc (read-only) có thể xem nhưng không thể thay đổi. | | Hạ tầng | Một zone sẽ không bán gì cho đến khi có thành phần được gắn vào (xem phần "Dịch vụ nào bán ở đâu" bên dưới). | | Phụ thuộc vào | [CloudStack](https://nexcmp.com/vi/docs/infrastructure/cloudstack/) hoặc [Proxmox VE](https://nexcmp.com/vi/docs/infrastructure/proxmox/) cho VM, [node VPN và proxy](https://nexcmp.com/vi/docs/infrastructure/vpn-proxy-nodes/) cho VPN, [S3](https://nexcmp.com/vi/docs/infrastructure/s3/) cho Object Storage. | ## Chuẩn bị hạ tầng {#prepare-the-infrastructure} Không bắt buộc. Zone là một bản ghi bên trong NexCMP. ## Kết nối trong NexCMP {#connect-in-nexcmp} ### Tạo zone {#create-a-zone} 1. Mở **Infrastructure › Datacenter › Zone** và nhấp vào **Add zone**. 2. Điền thông tin vào biểu mẫu: | Trường | Giá trị ví dụ | Ghi chú | |---|---|---| | Quốc gia | `United States` | Chọn cờ quốc gia. | | Thành phố | `New York` | Tùy chọn. | | Tên (tiếng Việt), Tên (tiếng Anh) | `New York` | Tên hiển thị cho khách hàng theo từng ngôn ngữ. | | Slug | `us-new-york` | a-z, 0-9, dấu gạch nối, 2-32 ký tự. Tự động điền từ quốc gia và thành phố cho đến khi bạn tự nhập. | | Chế độ hiển thị | Public | Các zone **Public** hiển thị với mọi khách hàng; các zone **Hidden** chỉ do quản trị viên cấp. | | Thứ tự | `0` | Số nhỏ hơn sẽ đứng trước trong danh sách. | | Dịch vụ bán trong zone này | Virtual Machines (VM), VPN, Object Storage (S3) | Tích chọn ít nhất một dịch vụ. | | Kích hoạt | On | **Off** sẽ ẩn zone đối với khách hàng. | | Mặc định | tắt | Zone được chọn sẵn cho khách hàng chưa chọn zone. Luôn có duy nhất một zone làm mặc định. | ![Hộp thoại Add zone với quốc gia, thành phố, slug và các dịch vụ đã được chọn](https://nexcmp.com/vi/docs/images/infrastructure/zones-01-add-zone.webp) 3. Nhấp vào **Create zone**. Danh sách sẽ hiển thị zone cùng cờ quốc gia, chủ sở hữu, dịch vụ, trạng thái và số lượng VM, gói cước cùng hạ tầng được liên kết. ![Danh sách zone với zone mặc định và zone thứ hai](https://nexcmp.com/vi/docs/images/infrastructure/zones-02-list.webp) ### Xem các thành phần được liên kết {#look-at-what-is-attached} Nhấp vào một hàng để mở zone. Tab **Provider infrastructure** liệt kê từng backend được liên kết cùng nhà cung cấp, loại (CloudStack hoặc Proxmox VE), region, trạng thái và độ ưu tiên. Tab **VPN infrastructure** liệt kê các dải IP và node VPN của zone kèm liên kết tới VPN pool. ![Chi tiết zone với tab Provider infrastructure](https://nexcmp.com/vi/docs/images/infrastructure/zones-03-detail.webp) ### Dịch vụ nào được bán ở đâu {#which-service-sells-where} | Dịch vụ | Cách đưa vào một zone | |---|---| | Máy ảo trên CloudStack | Trình hướng dẫn (hoặc **Infrastructure › Cloud provider › CloudStack**) sẽ liên kết CloudStack với zone 1. | | Máy ảo trên Proxmox VE | Tại tab **Clusters** của cluster, chọn **Attach cluster to zone**. Cluster sẽ tham gia vào một zone **hiện có**, thường là zone đang bán qua CloudStack. | | VPN | Một node VPN khi báo cáo dải IP public của mình sẽ tạo (hoặc tham gia) zone tương ứng với quốc gia đó và đưa các dải IP vào VPN pool. Bạn cũng có thể gán zone và node cho dải IP trong **VPN IP pools**. | | IPv6 Proxy | Node IPv6 proxy mới sẽ tạo zone ở trạng thái **off**. Hãy bật zone tại đây để khách hàng có thể chọn. | | Object Storage (S3) | Tích chọn dịch vụ S3 trên zone, sau đó liên kết backend trong **Ceph S3 (RGW)**. | ### Khi nào một zone có thể bán máy ảo? {#when-can-a-zone-sell-virtual-machines} Zone sẽ hiển thị nhãn **not ready to sell VMs** cho đến khi có ít nhất một backend đang hoạt động và có thể bán **và** ít nhất một gói cước hiển thị **và** ít nhất một template sẵn sàng trên backend đó. Biểu mẫu đặt hàng của khách hàng chỉ liệt kê các zone đã sẵn sàng. ## Kiểm tra {#verify} 1. Zone hiển thị trong danh sách ở trạng thái **On** cùng quốc kỳ tương ứng. 2. Trang chi tiết hiển thị backend hoặc các dải VPN như mong đợi. 3. Đối với VM: thẻ **not ready to sell VMs** đã biến mất. Trong cổng khách hàng, hãy tạo thử đơn hàng và kiểm tra xem zone có được cung cấp hay không. ## Giới hạn và lưu ý {#limits-and-notes} - Trong phiên bản NexCMP này, khách hàng đặt máy ảo tại **default zone** (zone 1). Các zone khác được dùng cho VPN, IPv6 Proxy và Object Storage, hoặc để chuẩn bị một vị trí trước khi có hạ tầng; phần ghi chú bên dưới danh sách zone cũng nêu rõ điều này. - Zone chỉ có thể bị xóa khi không còn liên kết với bất kỳ tài nguyên nào: không có backend, VM, plan hay dải VPN. Default zone không thể bị xóa; trước tiên hãy đặt một zone khác làm mặc định. - Bạn chỉ có thể bật/tắt hoặc ẩn/hiện các zone thuộc sở hữu của reseller; các trường thông tin khác đều bị khóa. - Slug là một phần của các tham chiếu nội bộ. Hãy chọn một lần duy nhất. ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | "Tên zone là bắt buộc" / "Chọn quốc gia" / "Chọn ít nhất 1 dịch vụ" | Một trường bắt buộc đang bị bỏ trống | Nhập tên, chọn quốc gia và tick chọn một dịch vụ. | | "Slug không hợp lệ (a-z 0-9 -, 2-32 ký tự)" | Slug chứa ký tự khác hoặc có độ dài không hợp lệ | Chỉ sử dụng chữ cái viết thường, chữ số và dấu gạch nối. | | Thẻ "not ready to sell VMs" | Không có backend nào đang hoạt động có thể bán, không có plan hoặc không có template sẵn sàng trong zone đó | Gắn hạ tầng, sau đó thêm plan và template. Xem [Plans](https://nexcmp.com/vi/docs/catalog/plans/) và [Templates](https://nexcmp.com/vi/docs/infrastructure/templates/). | | Nút Delete bị vô hiệu hóa kèm thông báo "still attached" | Zone vẫn còn backend, VM, plan hoặc dải VPN | Hãy xóa hoặc chuyển chúng trước. | | Nút Delete bị vô hiệu hóa kèm thông báo "Default zone" | Zone đang là zone mặc định | Đặt một zone khác làm mặc định. | | Khách hàng không nhìn thấy zone | Zone đang bị ẩn, không hoạt động hoặc chưa được tick chọn dịch vụ nào | Đặt Visibility thành Public, Active thành On và tick chọn dịch vụ. | | Thiếu zone S3 trong biểu mẫu backend | Dịch vụ S3 chưa được tick chọn cho zone | Chỉnh sửa zone và tick chọn **Object Storage (S3)**. | --- # CloudStack > **Vị trí trong admin:** Infrastructure › Cloud provider › CloudStack › API connection (`/infra/cloudstack?tab=connect`). Bạn cũng có thể thiết lập kết nối đầu tiên trong [setup wizard](https://nexcmp.com/vi/docs/getting-started/setup-wizard/), bước 2. ## Chức năng {#what-it-does} NexCMP bán các máy ảo chạy trên đám mây Apache CloudStack của bạn. Hệ thống triển khai, khởi động, dừng, đổi cấu hình, tạo snapshot và xóa VM qua CloudStack API, cấp phát địa chỉ IP public từ zone, đọc mức sử dụng để tính cước và băng thông, đồng thời hiển thị dung lượng cùng trạng thái vận hành trong admin console. CloudStack luôn là source of truth cho các hypervisor; NexCMP đóng vai trò là giao diện bán hàng, hệ thống billing và portal lớp trên. Sử dụng trang này khi CloudStack là (hoặc sẽ là) nguồn VM chính của bạn. Để cấu hình thêm nguồn thứ hai song song, hãy xem [Proxmox VE](https://nexcmp.com/vi/docs/infrastructure/proxmox/). ## Yêu cầu {#requirements} | Hạng mục | Yêu cầu | |---|---| | Phiên bản CloudStack | 4.23 là bản phát hành đã được kiểm thử. VM console yêu cầu phiên bản 4.18 trở lên và tính năng nâng cấp CPU/RAM trực tiếp cho VM đang chạy yêu cầu 4.23 với KVM. | | Loại zone | Zone có ít nhất một guest network dành cho VM của khách hàng và một dải IP public còn địa chỉ trống. | | Hypervisor | KVM là hypervisor đã được kiểm thử. | | Tài khoản | Một **domain và account riêng biệt** được tạo cho NexCMP. Tuyệt đối không sử dụng ROOT administrator key. | | Khả năng kết nối API | Panel server phải kết nối được tới management server API URL (`https://cloudstack.example.com/client/api`) qua HTTP(S). Các tính năng VM console, bandwidth và Kubernetes cũng sử dụng cùng endpoint này. | | Key chỉ đọc tùy chọn | Key chỉ đọc thứ hai cho phép admin console hiển thị hosts, storage, system VMs và các dải public IP. Không bắt buộc nếu chỉ bán VM. | | Public IP | Địa chỉ IPv4 public còn trống trong zone. Prefix mà NexCMP được phép bán được cấu hình trong Sales IP pools. | | Templates | Tối thiểu một template ở trạng thái sẵn sàng, hỗ trợ mật khẩu và một service offering mà account của bạn có thể thấy. Xem [Templates](https://nexcmp.com/vi/docs/infrastructure/templates/). | | Storage | Primary storage cho các volume của account và secondary storage nếu bạn bán snapshots hoặc image. | | Phụ thuộc vào | Không có. Kubernetes, Private Cloud, Images và Bandwidth phụ thuộc vào trang này. | ::: warning Không sử dụng ROOT administrator key Hãy tạo một domain và account riêng cho NexCMP. Khi đó, key chỉ có quyền truy cập domain này, và nếu key bị lộ thì phần còn lại của hạ tầng cloud vẫn an toàn. Trình hướng dẫn cài đặt cũng kiểm tra xem network bạn chọn có thuộc zone **và** account sở hữu key hay không. ::: ## Chuẩn bị hạ tầng {#prepare-the-infrastructure} Các lệnh sử dụng [CloudMonkey](https://cloudstack.apache.org/) (`cmk`) đã đăng nhập bằng quyền quản trị viên CloudStack. Hãy thay thế tên ví dụ và các placeholder trong dấu ngoặc nhọn. ### Tạo account và API key riêng {#create-a-dedicated-account-and-api-key} 1. Tạo domain để chứa toàn bộ tài nguyên do NexCMP quản lý. ```bash cmk create domain name=nexcmp ``` Lưu lại `id` trong kết quả trả về; giá trị này được dùng làm `` ở bên dưới. 2. Tìm role bạn muốn gán cho account. ```bash cmk list roles type=DomainAdmin filter=id,name ``` | Role | Khi nào nên chọn | |---|---| | **Domain Admin** (khuyến nghị) | Đầy đủ tính năng: VMs, networks, projects cho Kubernetes, VPC, images. Phạm vi quyền hạn chỉ giới hạn trong domain `nexcmp`. | | User | Chỉ quản lý vòng đời VM. User thông thường không thể expunge VM trừ khi cài đặt toàn cục `allow.user.expunge.recover.vm` là true; khi đó NexCMP sẽ tắt VM và CloudStack sẽ expunge VM sau `expunge.delay`. | 3. Tạo account và user đầu tiên cho account đó. Hãy dùng mật khẩu ngẫu nhiên có độ dài lớn; mật khẩu này sẽ không cần nhập lại nữa. ```bash cmk create account name=nexcmp-api username=nexcmp-api \ password='CHANGE-ME-LONG-RANDOM' email=ops@example.com \ firstname=NexCMP lastname=API roleid= domainid= ``` 4. Tạo cặp API key cho user mới. ```bash cmk list users domainid= username=nexcmp-api filter=id,username cmk generate userkeys id= ``` Sao chép `apikey` và `secretkey`. Đây là **API key** và **Secret key** bạn sẽ nhập vào NexCMP. NexCMP sẽ lưu trữ chúng dưới dạng mã hóa và sau đó chỉ hiển thị bốn ký tự cuối. 5. Đảm bảo domain không bị giới hạn tài nguyên khắt khe (instances, volumes, public IP, networks, snapshots, templates, projects). ```bash cmk list resourcelimits domainid= ``` ### Tạo guest network cho VM của khách hàng {#create-the-guest-network-for-customer-vms} VM của khách hàng được triển khai vào một guest network thuộc về account mới. Một isolated network có virtual router (VR) cùng các dịch vụ Static NAT, Firewall và Port Forwarding sẽ hoạt động tốt, vì NexCMP gắn public IP vào từng VM thông qua static NAT. ```bash cmk list networkofferings state=Enabled guestiptype=Isolated filter=id,name cmk create network name=customers displaytext=customers zoneid= \ networkofferingid= account=nexcmp-api domainid= ``` Kiểm tra chính sách egress mặc định của offering: nếu là "deny", VM của khách hàng sẽ không thể truy cập ra ngoài cho đến khi các quy tắc firewall egress được thêm vào. ### Thiết lập quyền hiển thị cho offerings và templates {#make-offerings-and-templates-visible} - **Service offerings** và **network offerings** phải ở chế độ public hoặc được gán cho domain `nexcmp`, nếu không account sẽ không thể xem danh sách hoặc sử dụng chúng. - Đăng ký hoặc chia sẻ ít nhất một template (xem [Templates](https://nexcmp.com/vi/docs/infrastructure/templates/)). NexCMP sẽ liệt kê các template ở trạng thái sẵn sàng và featured. ### Tùy chọn: key chỉ đọc cho các trang hạ tầng {#optional-read-only-key-for-infrastructure-pages} Các tab **Capacity**, **Host**, **Storage** và **System VM** cùng danh sách dải IP public sử dụng key thứ hai chỉ cần quyền đọc đối với 6 lệnh. Hãy tạo một role giới hạn thay vì dùng lại key administrator đầy đủ quyền: ```bash cmk create role name=nexcmp-readonly type=Admin # is the id printed above for api in listHosts listCapacity listSystemVms listVlanIpRanges listClusters listStoragePools; do cmk create rolepermission roleid= rule=$api permission=allow done cmk create rolepermission roleid= rule='*' permission=deny ``` Sau đó tạo một account với role đó (trong ROOT domain, vì role này đọc dữ liệu trên toàn zone), tạo các key tương tự bước 4 và nhập chúng vào mục **RO API key** ở phần tiếp theo. ### Kiểm tra đường truyền mạng {#check-the-network-path} Từ máy chủ panel: ```bash curl -fsS -o /dev/null -w '%{http_code}\n' https://cloudstack.example.com/client/api ``` Bất kỳ phản hồi HTTP nào (kể cả 4xx) đều chứng minh cổng có thể kết nối được. Hiện tượng timeout cho thấy sự cố tường lửa hoặc DNS từ phía bạn. ## Kết nối trong NexCMP {#connect-in-nexcmp} ### Trong wizard cài đặt {#in-the-setup-wizard} Bước 2 của [wizard cài đặt](https://nexcmp.com/vi/docs/getting-started/setup-wizard/) yêu cầu các giá trị tương tự. **Test connection** sẽ liệt kê các zone và network mà key nhìn thấy; hãy chọn zone và guest network, tên hiển thị cho zone cùng quốc gia, sau đó nhấn **Save CloudStack**. Wizard sẽ từ chối network không nằm trong zone đó hoặc key không nhìn thấy. ![Bước 2 của wizard với CloudStack API URL và các key đã điền cùng zone và network được chọn sau khi nhấn Test connection](https://nexcmp.com/vi/docs/images/infrastructure/cloudstack-01-wizard-step.webp) ### Sau này, trong admin console {#later-in-the-admin-console} 1. Mở **Infrastructure › Cloud provider › CloudStack** và chọn tab **API connection**. 2. Điền vào thẻ **Connection**: | Trường | Giá trị ví dụ | |---|---| | Endpoint API | `https://cloudstack.example.com/client/api` | | API key (quyền ghi) | `XXXX` (để trống để giữ lại key đã lưu) | | Secret key | `XXXX` | | Khóa API RO / khóa bí mật RO | tùy chọn, lấy từ account chỉ đọc | | Zone ID | UUID của zone của bạn | ![Tab API connection với endpoint ví dụ và các key đã được che](https://nexcmp.com/vi/docs/images/infrastructure/cloudstack-02-connect-form.webp) 3. Nhấn **Test connection** trước khi lưu. Thao tác này sẽ kiểm tra các key bạn đã nhập mà không lưu: key ghi với `listZones` và `listCapabilities`, cùng key chỉ đọc với `listSystemVms`. 4. Nhấn **Save connection**. Hãy tiếp tục bật **Enable CloudStack connection**; việc tắt tùy chọn này sẽ khiến worker dừng toàn bộ tác vụ CloudStack mà không làm mất dữ liệu. 5. Mở **Services › Virtual Machines › Policy › Provisioning** để đặt guest network mặc định, custom offering và key pair mặc định cho các VM mới. ![VM Policy, tab Provisioning, với ID network mặc định](https://nexcmp.com/vi/docs/images/infrastructure/cloudstack-04-provisioning.webp) 6. Mở **Infrastructure › Cloud provider › Sales IP pools** và trong mục **Configure sales ranges**, hãy đặt **Sellable IP range prefixes** (ví dụ: `203.0.113.`) cùng **Excluded IP prefixes** nếu có một số địa chỉ trong zone không bao giờ được bán. Hãy để trống tiền tố nếu muốn cho phép mọi địa chỉ còn trống. ![Sales IP pools với tiền tố có thể bán 203.0.113. đã được thiết lập](https://nexcmp.com/vi/docs/images/infrastructure/cloudstack-05-sales-ip-pool.webp) ### Những dữ liệu NexCMP đọc và ghi {#what-nexcmp-reads-and-writes} | Hạng mục | Đọc | Thay đổi | |---|---|---| | VMs | danh sách, trạng thái, lịch sử sử dụng, console endpoint | deploy, start, stop, reboot, reinstall, destroy, scale, reset mật khẩu và SSH key | | Ổ đĩa và snapshot | các volume, snapshot VM, backup | tạo, gắn, gỡ, thay đổi kích thước, xóa, tạo snapshot, khôi phục | | Mạng | mạng, router, IP public, firewall, port forwarding, quy tắc load balancer | gán và giải phóng IP public, static NAT, firewall, port forwarding, quy tắc egress, mạng và ACL cho Private Cloud | | Catalog | service offering, disk offering và network offering, template, ISO, loại OS | đăng ký và xóa template cùng ISO (Images), service offering khi tạo gói tùy chỉnh | | Kubernetes | các phiên bản được hỗ trợ, cluster, cấu hình | project, giới hạn tài nguyên, mạng, cluster (module Kubernetes) | | Khóa chỉ đọc | host, cluster, storage pool, system VM, dung lượng, dải IP VLAN | không có | ### CPU và RAM trực tiếp, cùng băng thông {#live-cpu-and-ram-and-bandwidth} - **Hot-plug.** Bạn chỉ có thể thay đổi cấu hình một VM đang chạy mà không cần khởi động lại khi template của VM cho phép (dynamically scalable) và hệ điều hành khách tự động nhận thêm CPU và RAM. NexCMP sẽ bật Auto Scaling cho các template có tên kết thúc bằng `vN` với N từ 6 trở lên, hoặc khi bạn cấu hình thủ công trong trường **vCPU/RAM hot-plug** của template. Xem [Templates](https://nexcmp.com/vi/docs/infrastructure/templates/). - **Nguồn đo băng thông.** Với cấu hình mặc định, NexCMP đo lưu lượng từ số liệu thống kê VM của CloudStack (`listVirtualMachinesUsageHistory`, được thu thập mỗi 5 phút và cộng tổng theo từng giao diện mạng của VM). Số liệu này bao gồm cả lưu lượng giữa các VM, do đó có thể cao hơn một chút so với thống kê từ router biên. Hãy luôn bật tính năng thu thập thống kê VM của CloudStack; các khoảng thời gian gián đoạn dài hơn thời gian lưu trữ thống kê sẽ bị bỏ qua. Xem [Bandwidth](https://nexcmp.com/vi/docs/catalog/bandwidth/). ## Kiểm tra {#verify} 1. **Test connection** trả về "Write key: OK" cùng zone của bạn và phiên bản CloudStack. 2. **Infrastructure › Cloud provider › Providers** hiển thị nhà cung cấp ở trạng thái hoạt động với thời gian kiểm tra gần nhất. Bảng tình trạng trên dashboard không còn hiển thị thông báo "CloudStack: not connected". 3. **Sales IP pools** liệt kê các địa chỉ còn trống (tự động làm mới khoảng một phút một lần). 4. Đặt một VM nhỏ từ cổng khách hàng hoặc admin console và kiểm tra xem VM có chuyển sang trạng thái Running, có IP public và bạn có thể mở console hay không. ## Giới hạn và lưu ý {#limits-and-notes} - Trong phiên bản NexCMP này, bạn có thể kết nối một cluster CloudStack. Hộp thoại **Add cloud provider** có thể kiểm tra khóa của cluster thứ hai nhưng không thể lưu. - Một zone CloudStack được liên kết với zone mặc định của NexCMP; nếu CloudStack có nhiều zone, hệ thống sẽ giới hạn trong phạm vi zone bạn nhập, do đó VM, IP và mạng của các zone khác sẽ bị bỏ qua. - Việc xóa guest network trong CloudStack sẽ khiến mọi lượt triển khai mới thất bại. Admin console sẽ hiển thị thông báo màu đỏ khi mạng này biến mất. - Thông tin xác thực không bao giờ rời khỏi máy chủ. API chỉ trả về bốn ký tự cuối cùng. ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | `listCapabilities: cloudstack 401: unable to verify user credentials and/or request signature` | Sai API key hoặc secret, khóa của người dùng khác, hoặc máy chủ panel bị lệch đồng hồ | Tạo lại khóa bằng `cmk generate userkeys` và dán cả hai. Kiểm tra thời gian trên máy chủ panel. | | Test: `listZones: …` hoặc timeout | Máy chủ panel không thể kết nối tới API URL | Kiểm tra DNS, firewall và đường dẫn `/client/api` chính xác. | | Trình hướng dẫn: "network not found in that zone for this API key" | Mạng đã chọn thuộc về một tài khoản hoặc zone khác | Tạo mạng trong tài khoản chuyên dụng (xem ở trên) và chạy lại **Test connection**. | | Trình hướng dẫn: "pick a zone and a network" | Chưa chạy kiểm tra, hoặc chưa chọn zone hay mạng nào | Nhấp vào **Test connection** và chọn ở cả hai danh sách. | | Banner thông báo "CloudStack key not configured" | Chưa lưu khóa nào ("Connect later") | Điền thông tin trong thẻ Connection, bấm **Save connection**, sau đó bấm **Test connection**. | | Banner "CloudStack connection is OFF" | Nút gạt **Enable CloudStack connection** đang tắt | Bật nút gạt lên và lưu lại. | | Khóa read-only: báo "unusable …" khi kiểm tra | Thiếu quyền trong role hoặc sai account | Kiểm tra 6 lệnh được phép và đảm bảo account nằm trong ROOT domain. | | "Zone public IP ranges not measured yet" hoặc "no public IP ranges declared" | Chưa có khóa read-only, hoặc zone thực sự không có public range | Thêm khóa read-only, hoặc thêm một public IP range trong CloudStack. | | "Pool trống — chờ 60 s để đồng bộ vmd" | Danh sách IP được worker làm mới mỗi phút một lần | Chờ một phút rồi tải lại trang. | | "hết IP trống trong dải 203.0.113." | Mọi địa chỉ trong prefix mở bán đều đã được dùng hết | Thêm địa chỉ vào zone, mở rộng prefix hoặc giải phóng các IP chưa dùng. | | "Không thể lấy dữ liệu mạng (CloudStack không phản hồi hoặc key thiếu quyền)" | Khóa bị mất quyền truy cập, hoặc CloudStack đang offline | Chạy **Test connection**; kiểm tra xem account đã được kích hoạt chưa. | | "Mạng khách KHÔNG tồn tại" | Network đã bị xóa trong CloudStack | Tạo lại network và đặt làm mặc định trong mục Provisioning. | --- # Proxmox VE > **Vị trí trong admin:** Infrastructure › Cloud provider › Providers (`/infra/providers`), sau đó vào trang nhà cung cấp (`/infra/providers/`) với các tab Overview, Clusters, VMs, Servers và Credentials. Các gói dịch vụ được thiết lập tại Services › Virtual Machines › Plans & pricing (`/vm/catalog`). ## Chức năng {#what-it-does} NexCMP có thể bán máy ảo chạy trên một hoặc nhiều cụm Proxmox VE, song song hoặc thay thế cho CloudStack. VM được tạo bằng cách nhân bản full clone từ OS template, sau đó cấu hình qua cloud-init: kích thước, địa chỉ IP từ pool bạn định nghĩa, mật khẩu root và SSH key. Khách hàng có toàn quyền bật/tắt, mở console, tạo snapshot, cài lại hệ điều hành, đổi mật khẩu và xem metrics trên portal. Họ không bao giờ nhìn thấy tên cụm, node hay tên nguồn hạ tầng. Sử dụng tính năng này khi bạn đã có sẵn Proxmox VE, hoặc muốn cung cấp thêm một nhóm VM thứ hai với mức giá khác biệt. ## Yêu cầu {#requirements} | Hạng mục | Yêu cầu | |---|---| | Proxmox VE | PVE 9.x. Bản tích hợp đã được xác thực trên 9.2. Yêu cầu storage content `import` và tùy chọn disk `import-from` (PVE 8.2 trở lên). | | Network từ panel | HTTPS đến cluster API, `https://:8006`. Không kèm path, user name hay query. Cả panel và worker đều kết nối; browser console được proxy qua panel. | | Tài khoản | Một PVE user chuyên dụng với **API token** và role tùy chỉnh có các quyền liệt kê bên dưới. Tuyệt đối không dùng `root@pam`. | | Storage | Một storage cho VM disk hỗ trợ clone (ví dụ `local-lvm`). Với template builder tích hợp sẵn, cần storage có tên `local` với content type `import` và `snippets`. | | Mạng | Một Linux bridge (ví dụ `vmbr0`) kết nối tới network chứa IP của khách hàng. Dùng VLAN-aware bridge nếu bạn nhập VLAN tag. | | IP | Một dải IPv4 (/16 đến /30) được định tuyến tới bridge đó, kèm gateway. NexCMP tự cấp phát IP; Proxmox không quản lý IP. | | Templates | Một cloud-init template VM cho mỗi hệ điều hành, trên từng node bạn triển khai, kèm QEMU guest agent. | | Zone | Một zone hiện có để gắn cluster vào. Xem [Zones](https://nexcmp.com/vi/docs/infrastructure/zones/). | | Phụ thuộc vào | Không có. | ## Chuẩn bị hạ tầng {#prepare-the-infrastructure} Chạy các lệnh này dưới quyền root trên bất kỳ node nào của cluster. ### Bước 1: Tạo role, user và API token với đặc quyền tối thiểu {#_1-create-a-least-privilege-role-user-and-api-token} 1. Tạo role. Danh sách quyền này chính xác là những gì NexCMP sử dụng; danh sách không chứa quyền chỉnh sửa người dùng, cấu hình storage hay datacenter. ```bash pveum role add NexCMP -privs "VM.Allocate VM.Clone VM.Config.CDROM VM.Config.CPU VM.Config.Cloudinit VM.Config.Disk VM.Config.HWType VM.Config.Memory VM.Config.Network VM.Config.Options VM.PowerMgmt VM.Audit VM.Console VM.Snapshot VM.Snapshot.Rollback VM.Backup VM.GuestAgent.Audit VM.GuestAgent.Unrestricted Datastore.Audit Datastore.AllocateSpace Datastore.AllocateTemplate Sys.Audit Sys.AccessNetwork SDN.Use SDN.Audit Pool.Audit Mapping.Audit Mapping.Use" ``` `Sys.AccessNetwork` là bắt buộc để tải cloud image. PVE 9 không có quyền `VM.Monitor`; đừng thêm quyền này. 2. Tạo user và token. `--privsep 1` có nghĩa là quyền của token là **phần giao** giữa quyền của user và quyền riêng của token. ```bash pveum user add nexcmp@pve --comment "NexCMP" pveum user token add nexcmp@pve api --privsep 1 ``` Lệnh sẽ in ra **secret một lần duy nhất** của token (một UUID). Hãy sao chép lại ngay. Token id là `nexcmp@pve!api`. 3. Gán role cho **cả** user và token. Đây là bước mọi người hay bỏ sót: khi phân tách đặc quyền, chỉ riêng token sẽ gặp lỗi 403 như `Datastore.Audit` nếu user không có quyền. ```bash pveum acl modify / --roles NexCMP --users nexcmp@pve pveum acl modify / --roles NexCMP --tokens 'nexcmp@pve!api' ``` 4. Kiểm tra từ máy chủ panel: ```bash curl -sk -H 'Authorization: PVEAPIToken=nexcmp@pve!api=' https://192.0.2.10:8006/api2/json/version ``` Một tài liệu JSON với `version` đồng nghĩa token hoạt động bình thường. (`-k` chỉ dành cho bước kiểm tra nhanh này; NexCMP sẽ tự ghim certificate, xem bên dưới.) ### Bước 2: Kiểm tra bridge và storage {#_2-check-the-bridge-and-the-storage} ```bash pvesm status # storages, type, content and free space ip -br link show type bridge ``` - VM của khách hàng sẽ nhận network interface `virtio` trên bridge bạn đã nhập trong NexCMP. Nếu bạn thiết lập VLAN, bridge bắt buộc phải hỗ trợ VLAN-aware. - Đặt các VM của khách hàng trên bridge hoặc VLAN **tách biệt khỏi địa chỉ quản trị của node**. Nếu dùng chung mạng, IP set quản trị tự động của tường lửa Proxmox sẽ mở các port 22, 8006, 3128, 5900-5999 và 60000-60050 của node cho mọi VM trong mạng đó. Nếu không thể tách riêng, hãy thêm một quy tắc DROP rõ ràng cho subnet của VM tới các port này, nằm phía trên quy tắc ACCEPT quản trị. ### Bước 3: Lưu ý về storage (LVM-thin) {#_3-storage-notes-lvm-thin} - Hãy giữ **tính năng zeroing của thin-pool ở giá trị mặc định**. Việc tắt tính năng này (`lvchange -Zn`) có thể khiến dữ liệu cũ còn sót lại trong các chunk mới được phân bổ và làm hỏng bảng phân vùng hoặc hệ thống tệp của các VM được nhân bản. - Các ổ đĩa báo "write cache: disabled" có thể chỉ nhân bản ở tốc độ vài MB/s. Hãy kiểm tra bằng `hdparm -W /dev/sdX` và bật write cache nếu ổ đĩa có tính năng bảo vệ mất điện. ### Bước 4: Bật nội dung `import` (chỉ dành cho template builder tích hợp sẵn) {#_4-enable-the-import-content-only-for-the-built-in-template-builder} Builder tích hợp sẵn sẽ tải cloud image vào storage có tên `local` và tạo template từ đó. Hãy thêm `import` (và `snippets`) vào danh sách content của storage đó. Hãy giữ nguyên các loại bạn đang dùng; `--content` sẽ thay thế toàn bộ danh sách: ```bash pvesm status --storage local # note the current content pvesm set local --content iso,vztmpl,backup,import,snippets ``` ### Bước 5: Tạo OS template từ cloud image {#_5-build-an-os-template-from-a-cloud-image} Template là một VM dùng cloud-init mà NexCMP sẽ nhân bản. Mỗi template được đăng ký dưới một **OS key** ngắn gọn như `ubuntu-24.04` cùng với VM id của nó. Hãy tạo một template cho mỗi hệ điều hành **trên mọi node sẽ tiếp nhận VM**, vì quá trình nhân bản sẽ chạy trên chính node được chọn. **Tùy chọn A, khuyến nghị: tự tạo.** Các cloud image gốc của Ubuntu và Debian không chứa guest agent và không cho phép đăng nhập root, trong khi NexCMP thiết lập mật khẩu root thông qua cloud-init. Hãy chuẩn bị image trước: ```bash apt install -y libguestfs-tools wget -O noble.qcow2 https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img virt-customize -a noble.qcow2 --install qemu-guest-agent \ --write /etc/cloud/cloud.cfg.d/99-nexcmp.cfg:$'ssh_pwauth: true\ndisable_root: false\n' \ --write /etc/ssh/sshd_config.d/00-nexcmp.conf:$'PermitRootLogin yes\nPasswordAuthentication yes\n' ``` Sau đó tạo VM template (id 9000 chỉ là ví dụ; hãy giữ các ID template bên dưới giá trị `vmid from`, mặc định là 1000): ```bash qm create 9000 --name tpl-ubuntu-24-04 --memory 2048 --cores 2 --cpu host --ostype l26 \ --scsihw virtio-scsi-single --net0 virtio,bridge=vmbr0 --agent 1 --serial0 socket --vga serial0 qm set 9000 --scsi0 local-lvm:0,import-from=$PWD/noble.qcow2,discard=on,iothread=1 qm set 9000 --ide2 local-lvm:cloudinit --boot order=scsi0 qm template 9000 ``` **Tùy chọn B: builder tích hợp sẵn.** Thẻ **Create OS template from cloud image** trên tab Clusters (xem bên dưới) sẽ tải xuống image qcow2, dựng template và đăng ký template đó. Nó tạo VM kèm cloud-init và cờ guest agent, nhưng không can thiệp vào nội dung bên trong image. Chỉ sử dụng tùy chọn này với image đã cho phép đăng nhập root và đang chạy guest agent, hoặc khi bạn có cung cấp thêm đoạn cấu hình vendor-data của cloud-init. Guest agent là cần thiết cho tính năng **Reset password** và để hiển thị địa chỉ IP của VM. ### 6. Xem fingerprint của chứng chỉ (tùy chọn) {#_6-know-the-certificate-fingerprint-optional} NexCMP xác thực cluster bằng cách ghim fingerprint SHA-256 của chứng chỉ TLS, nên chứng chỉ tự ký (self-signed) vẫn hoạt động tốt. Để xem giá trị mà NexCMP sẽ ghim: ```bash openssl x509 -in /etc/pve/local/pve-ssl.pem -noout -fingerprint -sha256 ``` ## Kết nối trong NexCMP {#connect-in-nexcmp} 1. Mở **Infrastructure › Cloud provider › Providers** và nhấp vào **Add cloud provider**. Chọn **Proxmox VE** và điền thông tin: | Trường | Giá trị ví dụ | |---|---| | Name | `Proxmox cluster 1` | | Endpoint | `https://192.0.2.10:8006` | | Token id | `nexcmp@pve!api` | | Token secret | `XXXX` (UUID được in ra ở bước 1) | | Slug | `pve-1` (a-z, 0-9, dấu gạch nối, 2-32 ký tự) | | Default node | `pve1` (để trống: node online có nhiều RAM trống nhất) | | Storage | `local-lvm` | | Bridge | `vmbr0` | ![Hộp thoại Add cloud provider với Proxmox VE được chọn cùng các giá trị mẫu cho endpoint, token và storage](https://nexcmp.com/vi/docs/images/infrastructure/proxmox-01-add-provider.webp) 2. Nhấp vào **Save & open provider**, nhập lý do khi được yêu cầu. Token sẽ được mã hóa trước khi lưu trữ. 3. Trên tab **Overview**, nhấp vào **Test connection**. Lần kiểm tra thành công đầu tiên sẽ **ghim fingerprint TLS của cluster**; từ thời điểm đó, mọi chứng chỉ khác đều sẽ bị từ chối. 4. Mở tab **Clusters**. Thẻ **Node · storage · bridge** liệt kê các tài nguyên mà API tìm thấy; thẻ **Cluster configuration** chứa các cài đặt: | Trường | Ý nghĩa | |---|---| | Default node | Node được dùng cho các VM mới. Để trống nghĩa là chọn node online có nhiều RAM trống nhất. | | Storage, Bridge, VLAN | Disk storage, NIC bridge và VLAN tag tùy chọn (0 nghĩa là không dùng). | | CPU type | Mặc định là `host`. Dùng `x86-64-v2-AES` khi các node có thế hệ CPU khác nhau. | | vmid from | ID VM đầu tiên được cấp cho các VM của khách hàng (mặc định 1000). | | Storage ISO, Storage backup | Để trống trừ khi bạn sử dụng chúng; để trống đồng nghĩa tính năng ISO và backup sẽ không được cung cấp. | | Template OS | Mỗi dòng một mục, `os-key=vmid`, ví dụ `ubuntu-24.04=9000`. | | Pinned TLS fingerprint (SHA-256) | Được điền tự động sau lần kiểm tra đầu tiên. Hãy xóa trường này và kiểm tra lại sau khi bạn thay chứng chỉ cluster. | ![Tab Clusters, thẻ Cluster configuration với danh sách mẫu cho node, storage, bridge và OS template](https://nexcmp.com/vi/docs/images/infrastructure/proxmox-03-cluster-config.webp) 5. Tùy chọn: nếu bạn đã dùng Tùy chọn B ở trên, hãy điền **Create OS template from cloud image** (OS key `ubuntu-24.04`, vmid `9000`, node `pve1`, URL của image qcow2) và nhấp vào **Create template**. Tác vụ sẽ chạy ngầm trong vài phút; kết quả được ghi trong Audit log. ![Thẻ Create OS template from cloud image với URL image Ubuntu mẫu](https://nexcmp.com/vi/docs/images/infrastructure/proxmox-04-template-from-image.webp) 6. Nhấp vào **Add pool** trong **Cluster IP pool** và tạo pool để các VM lấy địa chỉ IP: | Trường | Giá trị ví dụ | |---|---| | Name | `customers-1` | | CIDR | `198.51.100.0/24` | | Gateway | `198.51.100.1` (không bao giờ cấp cho VM) | | DNS | `1.1.1.1,8.8.8.8` (1 đến 4 địa chỉ IPv4) | | Bridge, VLAN | `vmbr0`, `0` | | Already used IPs | mỗi dòng một mục, `ip note`, ví dụ `198.51.100.10 monitoring` | NexCMP không bao giờ gán địa chỉ mạng, địa chỉ broadcast, gateway hoặc địa chỉ đã được giữ trước (reserved). Các pool trong cùng một cluster không được chồng lấn nhau. Một pool chỉ có thể bị xóa khi không có địa chỉ nào của pool đó đang được sử dụng. ![Hộp thoại Add IP pool với dải /24 và gateway mẫu](https://nexcmp.com/vi/docs/images/infrastructure/proxmox-05-ip-pool.webp) 7. Trong **Attach cluster to zone**, hãy chọn zone và tùy chọn thêm tên node, sau đó nhấp vào **Attach to zone**. Cụm cluster sẽ tham gia vào zone vốn đang bán VM, nhờ đó một zone có thể chạy song song cả CloudStack lẫn Proxmox. Nguồn mới này **mặc định không được mở bán** và không làm thay đổi hành vi của các gói plan hiện có. ![Thẻ Attach cluster to zone khi đã chọn một zone hiện có](https://nexcmp.com/vi/docs/images/infrastructure/proxmox-06-attach-zone.webp) 8. Mở **Services › Virtual Machines › Plans & pricing** và nhấp vào **Add plan**. Tại **Infrastructure source**, hãy chọn cụm Proxmox cluster, sau đó thiết lập CPU, RAM, ổ đĩa và giá. Một plan Proxmox không cần CloudStack offering. Để bán cùng một cấu hình từ cả hai nguồn, hãy dùng tính năng **Clone** trên plan và chọn nguồn còn lại. Dung lượng đĩa của plan phải tối thiểu bằng dung lượng đĩa của template; Proxmox không thể thu nhỏ ổ đĩa. ### Import VM đã tồn tại sẵn {#import-a-vm-that-already-exists} Mở tab **Servers** để liệt kê các VM trên cluster. **Import** sẽ gán một VM hiện có vào tài khoản khách hàng hoàn toàn miễn phí: không tính phí theo giờ, thời gian tắt máy hay lưu lượng truyền tải. Khách hàng có thể bật, tắt, khởi động lại và mở console nhưng không thể xóa VM; chỉ quản trị viên mới có quyền này. NexCMP chỉ đọc dữ liệu từ cluster trong suốt quá trình import. - Cluster phải được gán vào một zone **kèm theo tên node** của VM đó (nếu để trống node, quá trình import sẽ báo lỗi rằng region chưa được thiết lập). - Để đặt VM ở chế độ **protected** (từ chối các thao tác stop, reboot, reinstall, snapshot restore, destroy và đổi plan), hãy import VM từ dòng lệnh với `--protect`: ```bash sudo -u nexcmp /opt/nexcmp/bin/nexcmp px-import --provider pve-1 --server-ref pve1/101 --account-id 12 --hostname web-1 --protect ``` ### Những tính năng được và không được hỗ trợ trên Proxmox {#what-is-and-is-not-supported-on-proxmox} | Tính năng | Proxmox VE | |---|---| | Khởi tạo, bật/tắt nguồn/khởi động lại, xóa | Có | | Thay đổi dung lượng CPU và RAM, mở rộng ổ đĩa | Có, nhưng VM sẽ bị tắt, thay đổi cấu hình rồi khởi động lại (không hỗ trợ live resize) | | Snapshots | Có, tối đa 5 bản trên mỗi VM: tạo, liệt kê danh sách, khôi phục, xóa | | Cài đặt lại | Có: VM được dựng lại từ template và giữ nguyên id, IP cùng các cài đặt, kèm theo mật khẩu mới | | Đặt lại mật khẩu | Có, thông qua guest agent | | Console | Có, console trên trình duyệt được proxy qua panel | | Metrics | Có: CPU, bộ nhớ, mạng và ổ đĩa | | Gắn ISO, Backups, tường lửa, IPv6, port forwarding, đổi IP, thêm volume, Auto Scaling, DDoS Shield, VPC, đo lường băng thông | Không khả dụng. Trang VM của khách hàng sẽ ẩn đi những tính năng mà nguồn hạ tầng không hỗ trợ. | ## Kiểm tra {#verify} 1. **Test connection** hiển thị OK và trạng thái provider là active. 2. **Clusters** liệt kê các node của bạn ở trạng thái online, cùng với storage và bridge. 3. **Cluster IP pool** hiển thị số lượng IP còn trống, đang dùng và đang giữ. 4. OS key sẽ xuất hiện bên dưới danh sách template của zone trong **Services › Virtual Machines › Template** sau khi gắn cluster. 5. Hãy đặt thử một VM từ gói plan sử dụng cluster này. VM sẽ nhận được một địa chỉ từ pool, mật khẩu root và console hoạt động bình thường; pool sẽ hiển thị một địa chỉ đã được sử dụng. ## Giới hạn và lưu ý {#limits-and-notes} ::: tip Zone đa nguồn Kể từ NexCMP 1.4.0, bảng giá Cloud Server công khai cũng hoạt động khi CloudStack và Proxmox VE dùng chung một zone. Mỗi plan sử dụng **Infrastructure source** riêng của mình. Sau khi gắn cluster, hãy kiểm tra bảng giá công khai và đặt hàng thử nghiệm cho từng nguồn. ::: - Bạn có thể thêm nhiều cụm Proxmox cluster. Mỗi cụm là một provider riêng biệt. - Một zone cung cấp một nguồn mặc định; gói plan có thiết lập **Infrastructure source** riêng sẽ được triển khai chính xác vào cluster đó, miễn là cluster đang active và nằm trong zone của plan. - Một cluster nằm sau cùng zone với CloudStack sẽ giữ nguyên các gói dịch vụ cũ trên CloudStack. Hãy kiểm thử toàn diện quy trình đặt hàng trước khi triển khai thực tế. - API token chỉ có thể thay thế chứ không thể xem lại. Hãy thay thế token trong tab **Credentials**: trước tiên tạo token mới trong Proxmox, nhập token, chạy **Test connection**, sau đó thu hồi token cũ. - Các thao tác Test, Sync và cluster-info bị giới hạn ở mức 6 lượt gọi mỗi phút cho mỗi quản trị viên. - NexCMP tính cước khách hàng của bạn; chi phí phần cứng và bản quyền của cluster do bạn tự chi trả. ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | Test: "Key rejected (wrong access key / secret, or revoked)" hoặc HTTP 401/403 | Sai token id hoặc secret, hoặc ACL chỉ mới được gán riêng cho token | Chạy lại hai lệnh `pveum acl modify` (cho user **và** token) rồi kiểm tra xem token id đã là `user@realm!tokenid` chưa. | | Test: "Could not connect to the provider" hoặc "Timed out" | Do tường lửa, sai host hoặc sai cổng | Kiểm tra `https://host:8006` từ server chạy panel. | | Kiểm tra: "Endpoint không hợp lệ hoặc không nằm trong allowlist" | Endpoint chứa path, user, query hoặc không phải HTTPS | Sử dụng chính xác `https://host:8006`. | | "Chứng chỉ TLS của cluster KHÔNG khớp với pinned fingerprint" | Chứng chỉ của cluster đã bị thay thế | Xóa **Pinned TLS fingerprint** trên tab Clusters, lưu lại rồi chạy lại **Test connection**. | | Slug bị từ chối | Không thuộc a-z, 0-9, dấu gạch nối hoặc độ dài không nằm trong khoảng 2-32 ký tự | Sử dụng định dạng tương tự như `pve-1`. | | "Định dạng token id: user@realm!tokenid và bắt buộc có secret" | Thiếu token id hoặc secret | Nhập cả hai; secret là chuỗi UUID hiển thị khi tạo token. | | "Dòng template không hợp lệ: …" | Một dòng trong **Template OS** không đúng định dạng `key=vmid` | Sử dụng chữ cái, chữ số, `.`, `_`, `-` trong key và vmid tối thiểu từ 100 trở lên. | | "OS key: a-z 0-9 . _ - và vmid ≥ 100" | Key hoặc id không hợp lệ trong **Create template** | Sửa lại OS key và sử dụng một vmid còn trống. | | "vmid … already exists" khi tạo template | vmid đã bị sử dụng | Chọn một id khác. | | "url trỏ đến địa chỉ nội bộ" | URL của image trỏ về một IP nội bộ | Sử dụng URL công khai; tên miền sẽ được Proxmox phân giải. | | Tác vụ tạo template thất bại khi tải xuống | Storage `local` không có loại nội dung `import` | `pvesm set local --content …,import,snippets`, sau đó thử lại. Tên tệp phải kết thúc bằng `.qcow2`, `.raw`, `.vmdk`, `.ova` hoặc `.ovf`. | | "cluster has no online nodes" hoặc "node … is not online" | Node mặc định đang tắt hoặc bị viết sai tên | Sửa lại **Default node** hoặc để trống. | | "image không thuộc về cluster" | Hệ điều hành của gói dịch vụ không có trong **Template OS** | Thêm key vào danh sách rồi lưu lại. | | Deploy ở trạng thái chờ rồi thất bại khi clone | VM template không nằm trên node đã chọn | Tạo template trên node đó, hoặc đặt **Default node** thành node đang chứa template. | | Khách hàng không thể đăng nhập bằng root | Image chặn đăng nhập root | Build lại template theo Tùy chọn A. | | Đặt lại mật khẩu không có tác dụng | Không có guest agent bên trong máy ảo | Cài đặt và bật `qemu-guest-agent` trong template. | | "Bắt buộc phải có Name, CIDR và gateway" | Thiếu trường pool | Điền đầy đủ cả ba trường. | | Pool create: "overlaps with pool …", "gateway must be within range (not network/broadcast address)" hoặc "cidr: network address must be …" | Pool bị trùng lặp, gateway sai, hoặc CIDR không nằm trên ranh giới mạng | Dùng một dải IP còn trống, gateway nằm trong dải đó và CIDR được ghi dưới dạng địa chỉ mạng (ví dụ: `198.51.100.0/24`). | | Import: "region chưa được thiết lập" | Cluster được gắn mà không có tên node của VM | Gắn cluster vào zone kèm tên node. | --- # Template hệ điều hành và ISO {#os-templates-and-isos} > **Vị trí trong trang admin:** Services › Virtual Machines › Template (`/vm/templates`). Template Proxmox được liệt kê theo từng cluster tại Infrastructure › Cloud provider › Providers › (cluster) › Clusters. ## Chức năng {#what-it-does} Template là image hệ điều hành dùng để khởi tạo VM mới. NexCMP không tự lưu trữ image: hệ thống đọc dữ liệu từ CloudStack (các template ready, featured) hoặc những gì bạn liệt kê cho Proxmox cluster, rồi cho phép bạn chọn template để mở bán kèm tên hiển thị cho khách, icon và user đăng nhập. Trang này hướng dẫn cách chuẩn bị các image tương thích tốt với NexCMP: đăng nhập bằng mật khẩu, co giãn CPU và RAM nóng, swap file, cùng ổ đĩa root tự động mở rộng theo gói cước. ## Yêu cầu {#requirements} | Hạng mục | Yêu cầu | |---|---| | CloudStack template builder | Một máy Linux có `libguestfs-tools` (`virt-customize`, `virt-sparsify`, `guestfish`), `qemu-utils`, `curl` và khoảng 5 GB dung lượng đĩa trống. Không cần KVM hay quyền root. Có kết nối Internet để cài package (hoặc build với `--offline`). | | Vị trí của builder | Công cụ này đi kèm trong mỗi bản phát hành tại `/opt/nexcmp/releases//share/templates/` trên server panel. Bạn không nhất thiết phải chạy trên đó: hãy sao chép thư mục sang bất kỳ máy Linux nào. | | Web server | Bất kỳ HTTP(S) server nào mà secondary storage VM của CloudStack có thể truy cập, dùng để phát hành file `.qcow2` hoàn thiện. Không bắt buộc phải truy cập được từ Internet. | | CloudStack | Một tài khoản có quyền đăng ký template, cùng ID của zone và OS type tương ứng. Xem [CloudStack](https://nexcmp.com/vi/docs/infrastructure/cloudstack/). | | Proxmox VE | VM template cloud-init có QEMU guest agent, một cho mỗi hệ điều hành và mỗi node. Xem [Proxmox VE](https://nexcmp.com/vi/docs/infrastructure/proxmox/). | | Phụ thuộc vào | Đã kết nối [CloudStack](https://nexcmp.com/vi/docs/infrastructure/cloudstack/) hoặc [Proxmox VE](https://nexcmp.com/vi/docs/infrastructure/proxmox/) trước đó. | ## Chuẩn bị hạ tầng {#prepare-the-infrastructure} ### CloudStack: tạo template {#cloudstack-build-a-template} Các base image được hỗ trợ (image từ nhà cung cấp được tải xuống và kiểm tra checksum trước khi thay đổi bất kỳ nội dung nào): | Image | `--distro` | Login user | |---|---|---| | Ubuntu 22.04 | `ubuntu-22.04` | `ubuntu` | | Ubuntu 24.04 | `ubuntu-24.04` | `ubuntu` | | Debian 12 | `debian-12` | `debian` | | Rocky Linux 9 | `rocky-9` | `rocky` | Thêm bản phân phối khác: thêm một dòng vào `distros.conf` (URL image, file checksum, họ `deb` hoặc `rpm`). 1. Sao chép builder sang máy build và chạy lệnh: ```bash cp -r /opt/nexcmp/releases//share/templates ~/templates && cd ~/templates ./build-template.sh --distro ubuntu-24.04 --version v7 --work ./out ``` Thêm `--panel-url https://cloud.example.com` để tích hợp agent giám sát tùy chọn lúc khởi động lần đầu tự động đăng ký với panel của bạn (chỉ qua HTTPS). Nếu không có tham số này, sẽ không có agent nào được thêm. Các tùy chọn khác: `--base ` để dùng image bạn đã tải về, `--offline` để bỏ qua việc cài đặt gói. 2. Kết quả là `out/ubuntu-24.04-v7.qcow2` và `.sha256` tương ứng. Quá trình build kết thúc bằng việc chạy `verify-image.sh`, lệnh này sẽ kiểm tra image hoàn thiện ở chế độ chỉ đọc và từ chối image lỗi (được giữ lại dưới dạng `.unverified`). Bạn có thể chạy lại bất cứ lúc nào: `./verify-image.sh out/ubuntu-24.04-v7.qcow2 --no-agent`. Những gì builder đưa vào image: | Hạng mục | Lý do | |---|---| | `qemu-guest-agent` | CloudStack có thể truy vấn VM về CPU và IP, đồng thời quiesce hệ thống để tạo Snapshots. | | cloud-init với data source CloudStack, `set_passwords` mỗi lần khởi động, đăng nhập SSH bằng mật khẩu | Mật khẩu được tạo sẽ được lấy từ virtual router và tính năng **Reset password** hoạt động bình thường. | | Quy tắc udev cho CPU và RAM gắn nóng | vCPU và RAM gắn nóng tự động online, giúp tính năng live scaling và Auto Scaling hoạt động trơn tru. | | Dịch vụ file swap | Tạo `/swapfile` với dung lượng nhỏ hơn giữa 50% RAM và 4 GiB sau khi đĩa đã mở rộng. `touch /etc/cmp-swap.disabled` dùng để tắt tính năng này. | | cloud-init `growpart` và `resizefs` | Đĩa root nhỏ sẽ tự động mở rộng theo dung lượng đĩa của gói dịch vụ trong lần khởi động đầu tiên. | | machine-id rỗng, không có SSH host key | Mỗi VM nhận được định danh riêng biệt. | ::: warning Đặt tên template là ` ` NexCMP bật **Auto Scaling** cho các template có tên kết thúc bằng `vN` hoặc `vN.M` với **N từ 6 trở lên** (`Ubuntu 24.04 v7`, `Rocky Linux 9 v7.1`). Builder bắt buộc điều này đối với `--version`. Hãy đăng ký template với chính xác tên được in ra. ::: 3. Xuất bản file và đăng ký vào CloudStack. Sử dụng mã SHA-256 được in ra sau khi build, và chỉ đăng ký sau khi file đã được ghi hoàn tất: ```bash cmk list ostypes keyword="Ubuntu 24.04" filter=id,description cmk register template name="Ubuntu 24.04 v7" displaytext="Ubuntu 24.04 v7" \ url=https://files.example.com/ubuntu-24.04-v7.qcow2 zoneid= format=QCOW2 hypervisor=KVM \ ostypeid= passwordenabled=true sshkeyenabled=true isdynamicallyscalable=true \ requireshvm=true isextractable=false ispublic=true isfeatured=true \ checksum="{SHA-256}" \ details[0].guest.cpu.mode=host-passthrough details[0].rootDiskController=osdefault ``` - `passwordenabled=true` cho phép CloudStack tạo mật khẩu VM. - `isdynamicallyscalable=true` cho phép live scaling. - `host-passthrough` là bắt buộc để các image Rocky và Alma hiện tại có thể khởi động; `osdefault` giúp disk controller tương thích linh hoạt. 4. Đợi template đạt trạng thái **Download Complete / Ready**. Image từ nhà cung cấp giữ kích thước ảo nhỏ gọn (khoảng 3.5 GiB đối với Ubuntu và Debian, 10 GiB đối với Rocky). Lưu ý rằng dung lượng đĩa của gói dịch vụ không thể nhỏ hơn đĩa của template. ### Proxmox VE: tạo template {#proxmox-ve-make-a-template} Hãy build một template VM cloud-init cho từng hệ điều hành trên mọi node bạn triển khai, đã cài sẵn guest agent và bật đăng nhập root, sau đó đăng ký dưới dạng `os-key=vmid`. Danh sách lệnh đầy đủ có tại [Proxmox VE](https://nexcmp.com/vi/docs/infrastructure/proxmox/). Builder CloudStack ở trên **không** dành cho Proxmox: nó cấu hình cloud-init cho data source CloudStack. ### ISO {#isos} Khách hàng có thể gắn ISO riêng của họ thông qua module **Images** (CloudStack) hoặc module Dedicated Server. Các ISO này độc lập với những OS template trên trang này. Xem [Modules](https://nexcmp.com/vi/docs/infrastructure/modules/) và [Dedicated servers](https://nexcmp.com/vi/docs/infrastructure/dedicated/). ## Kết nối trong NexCMP {#connect-in-nexcmp} 1. Mở **Services › Virtual Machines › Template**. Nhấp vào **Sync now** hoặc đợi tối đa 15 phút. Quá trình đồng bộ sẽ thêm các template đã sẵn sàng và được đặt featured trong CloudStack. ![Trang Template liệt kê các template đã đồng bộ cùng trạng thái sẵn sàng và cột CPU hot-plug](https://nexcmp.com/vi/docs/images/infrastructure/templates-01-list.webp) 2. Nhấp vào **Edit** trên một template mới và cấu hình những gì khách hàng nhìn thấy: | Trường | Giá trị ví dụ | |---|---| | Tên hiển thị cho khách hàng | `Ubuntu 24.04 LTS` | | Dòng hệ điều hành | `ubuntu` (icon và người dùng mặc định) | | Phiên bản | `24.04` | | Tên người dùng đăng nhập | `ubuntu` (Windows: `Administrator`; khác: `root`) | | Icon | URL image, đường dẫn hoặc tên | | Thứ tự | `10` | | Kích hoạt | On | | Cắm nóng vCPU/RAM (mở rộng trực tiếp) | **Auto by name (v6 or later)**, **Yes** hoặc **No (needs a restart)** | ![Hộp thoại chỉnh sửa template với tên hiển thị cho khách hàng, OS family, user đăng nhập và tùy chọn hot-plug](https://nexcmp.com/vi/docs/images/infrastructure/templates-02-edit.webp) 3. Bật template. Template không còn được CloudStack liệt kê sẽ tự động bị ẩn (và bạn sẽ nhận được thông báo qua Telegram nếu đã cấu hình); template này không bao giờ bị xóa khỏi NexCMP. ### Thay thế template bằng bản build mới hơn {#replace-a-template-with-a-newer-build} Dùng **More › Replace with new version** trên template đang bán. Chọn template mới ở trạng thái ready và đang bị tắt. Mục đang bán sau đó sẽ trỏ đến bản build mới, đồng thời giữ nguyên tên, thứ tự và icon; bản cũ sẽ bị tắt để làm đường lùi (để quay lại, dùng **Replace** trên mục mới). Các VM đang chạy không bị ảnh hưởng. Nếu bản build mới thuộc OS family khác, hãy tích chọn xác nhận trước. ## Kiểm tra {#verify} 1. Hàng hiển thị **ready** và đối với các bản build có tên `vN` với N từ 6 trở lên, hiển thị **CPU hot-plug: supported**. 2. Triển khai một VM thử nghiệm từ template và kiểm tra bên trong VM: - bạn có thể đăng nhập bằng mật khẩu hiển thị trên portal; - `df -h /` hiển thị dung lượng đĩa của gói; - sau khi live scale (**Change plan** không cần reboot), `nproc` và `free -m` tăng dung lượng; - `swapon --show` liệt kê `/swapfile` (các đĩa có dung lượng trống ít hơn swap cộng 2 GiB sẽ bỏ qua); - `systemctl is-active qemu-guest-agent` in ra `active`. 3. Nếu bạn đã tích hợp sẵn agent vào image, VM sẽ xuất hiện trong danh sách host được giám sát của bảng điều khiển sau khi khởi động lần đầu một phút. VM cần có IP public riêng: bảng điều khiển nhận diện VM qua IP nguồn public của nó. ## Giới hạn và lưu ý {#limits-and-notes} - Công cụ build chỉ chạy trên Linux và tạo các image Linux. Các image khác (ví dụ: Windows) có thể được đăng ký trong CloudStack bằng phương thức khác; NexCMP sẽ liệt kê những gì CloudStack báo cáo. - Chỉ agent bản amd64 được cung cấp sẵn; các kiến trúc khác sẽ bỏ qua việc cài đặt agent. - Image được kiểm tra bằng `guestfish` nhưng không bao giờ được công cụ build khởi động. Luôn triển khai một VM thử nghiệm trước khi mở bán image mới. - Bỏ qua agent trên một VM bằng `touch /etc/cmp-agent.disabled` trước lần khởi động đầu tiên. Gỡ bỏ sau đó bằng `systemctl disable --now cmp-agent cmp-agent-install; rm -rf /etc/cmp-agent /usr/local/bin/cmp-agent`, rồi xóa agent trong console quản trị. ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | `virt-customize` không tải được các gói | Máy build không có kết nối mạng ra ngoài | Sửa DNS hoặc proxy trên máy đó, hoặc build với `--offline` trên base image đã có sẵn các gói. | | `libguestfs: error: /usr/bin/supermin exited with error status 1` | User hiện tại không có quyền đọc kernel của host (Ubuntu) | `sudo chmod +r /boot/vmlinuz*`, hoặc chạy bản build với quyền root. | | Checksum khác biệt hoặc image của nhà cung cấp không còn tồn tại | Nhà cung cấp thay đổi vị trí các tệp "latest" của họ | Tự tải image về, đối chiếu với tệp checksum của nhà cung cấp và truyền vào bằng `--base`. | | Rocky: không thể mount định dạng XFS mới hơn | Kernel của host quá cũ | Build trên máy có kernel mới hơn. | | `--version must be v6 or higher` | Tên phải là `vN` với N từ 6 trở lên | Dùng `--version v7`. | | `--panel-url must be a plain https:// URL` | Agent được tải xuống và chạy dưới quyền root, do đó giao thức HTTP thường bị từ chối | Dùng URL `https://` không chứa khoảng trắng, dấu ngoặc kép hoặc query string. | | Template vẫn ở trạng thái **not ready** | CloudStack chưa tải xong | Chờ trạng thái **Download Complete**, kiểm tra xem secondary storage VM có thể kết nối tới URL không. | | Hàng hiển thị **no-pass** | Template được đăng ký mà không có `passwordenabled=true` | Đăng ký lại với flag đó. | | CPU hot-plug hiển thị **unsupported** | Tên không kết thúc bằng `vN` (N từ 6 trở lên) | Đổi tên template, hoặc đặt **vCPU/RAM hot-plug** thành **Yes** trong Edit nếu image có udev rule. | | "Empty template list" sau lần kết nối đầu tiên | Tiến trình đồng bộ chưa chạy | Nhấp **Sync now** (cần worker đang chạy) hoặc đợi chu kỳ 15 phút. | --- # Máy chủ dedicated (bare metal) {#dedicated-servers-bare-metal} > **Vị trí trong admin:** Infrastructure › Bare Metal (Servers `/infra/baremetal`, IP Pools, Stock / iDRAC import, Operations, Templates, Customer ISOs, Safety). Gói cước và gói đăng ký: Services › Dedicated Server (`/dedicated`). Bật module tại System › Admin › License & updates (`/license`). ## Chức năng {#what-it-does} NexCMP quản lý các máy chủ vật lý **trực tiếp qua iDRAC**, thông qua Redfish API. Khách hàng thuê toàn bộ máy chủ: họ có thể bật/tắt nguồn, mở console trên trình duyệt, mount ISO hoặc cài đặt hệ điều hành từ template, cũng như xem thông tin phần cứng và thông số giám sát. Họ không bao giờ nhìn thấy địa chỉ, user name hay password của iDRAC. Sử dụng tính năng này để bán lại máy chủ dedicated từ tủ rack của bạn. ## Yêu cầu {#requirements} | Hạng mục | Yêu cầu | |---|---| | Phần cứng | Máy chủ Dell với **iDRAC 9** và Redfish API. | | Mạng quản trị | **Do bạn tự chuẩn bị.** Máy chủ panel phải kết nối được tới từng iDRAC qua **HTTPS 443** (và cổng iDRAC VNC, mặc định là **5901**, dành cho console), đồng thời mỗi iDRAC phải kết nối được tới web server chứa ISO bên dưới. Địa chỉ iDRAC phải là **địa chỉ IPv4 trong dải private** (RFC 1918, prefix từ /16 trở xuống) mà bạn liệt kê trong cài đặt `dedicated_bmc_cidrs`. Tên miền DNS và IPv6 sẽ bị từ chối. NexCMP không tạo mạng này và không thể kiểm tra giúp bạn. | | Tài khoản iDRAC | Một tài khoản có quyền **Administrator** trên mỗi iDRAC. NexCMP dùng tài khoản này để đọc thông tin máy chủ và gửi một vài lệnh được phép (nguồn, virtual media, one-time boot, console). Hệ thống không bao giờ tạo tài khoản iDRAC cho khách hàng của bạn. | | Các công cụ trên máy chủ panel | `xorriso` và `genisoimage` (dùng để build ISO cài đặt cho từng máy chủ) và `novnc` (trang console trên trình duyệt). Cài đặt chúng bằng `sudo apt-get install -y xorriso genisoimage novnc`, hoặc để trình cài đặt tự thực hiện: chạy với `--baremetal`, hoặc truyền các tùy chọn ISO server; quá trình cập nhật cũng sẽ cài đặt chúng nếu module Bare Metal đã được bật. Nếu thiếu bất kỳ công cụ nào, **Safety** sẽ liệt kê trong thông báo màu đỏ, **live ops** sẽ từ chối bật (lỗi `tools_missing`), đồng thời console và tính năng cài đặt OS sẽ báo thiếu công cụ thay vì gặp sự cố về sau. | | ISO web server | Một server **HTTP** thông thường trên management network dùng để phân phối thư mục ISO của NexCMP cho các iDRAC. Địa chỉ của server này là một địa chỉ IPv4 private và cổng tùy chọn, ví dụ `http://10.20.0.2:8080`, **không kèm đường dẫn**, được lưu trong `dedicated_iso_base_url`. Server phải hỗ trợ byte ranges. Thư mục này do worker của panel ghi dữ liệu, nên web server thường chạy trên **chính máy chủ panel**, lắng nghe trên địa chỉ mà máy chủ đó sở hữu trong management network. NexCMP cung cấp sẵn cấu hình nginx site và lệnh thiết lập một bước cho mục này (xem bên dưới). | | Thư mục ISO | Một thư mục chứa các file ISO và bên trong gồm `pub` (nơi các iDRAC đọc) cùng `server` (ISO của khách hàng). Lệnh thiết lập một bước sử dụng `/srv/nexcmp-iso`; nếu không dùng lệnh này, các giá trị mặc định sẽ theo quá trình cài đặt (cài đặt `dedicated_iso_lib_dir`, `dedicated_iso_pub_dir`, `dedicated_iso_server_dir`). NexCMP worker phải có quyền **ghi** vào các thư mục này. Worker chạy với hệ thống tệp chỉ đọc ngoại trừ `/var/lib/nexcmp`, do đó thư mục ở vị trí khác cần có systemd drop-in (lệnh một bước sẽ tự cài đặt). | | Địa chỉ callback | `dedicated_callback_base`, một `https://` mà máy chủ đang cài đặt có thể truy cập được và trỏ về panel của bạn. | | Storage | Dung lượng đĩa trống cho thư viện ISO và các ISO do khách hàng cung cấp. | | Phụ thuộc vào | Module **Bare Metal**, một zone và các IP pool của máy chủ. | ::: warning Giá trị mẫu không phải là cấu hình Bản cài đặt mới sẽ mang các giá trị mẫu trong `dedicated_bmc_cidrs`, `dedicated_iso_base_url` và `dedicated_callback_base` (một mạng mẫu private và `https://example.com`). Chúng không phải là mạng của bạn. Chừng nào bất kỳ giá trị nào trong số đó vẫn là giá trị mẫu, các trang Bare Metal sẽ hiển thị thông báo màu đỏ **Management network not configured**, việc import iDRAC sẽ thất bại khi kiểm tra allow-list, và công tắc **live ops** sẽ từ chối bật (lỗi `config_placeholder`). Hãy thiết lập ba giá trị này tại **Infrastructure › Bare Metal › Safety › Management network connection** (xem bên dưới). ::: ## Chuẩn bị hạ tầng {#prepare-the-infrastructure} 1. **Đặt mọi iDRAC vào một mạng quản trị** mà khách hàng không thể truy cập, đồng thời gán cho mỗi iDRAC một địa chỉ IPv4 private tĩnh. Kiểm tra Redfish API từ panel server: ```bash curl -sk -u 'nexcmp-admin:XXXX' https://10.20.0.11/redfish/v1/Systems | head ``` 2. **Tạo tài khoản administrator trên iDRAC** cho NexCMP (giao diện web iDRAC, hoặc `racadm`). Hãy dùng mật khẩu mạnh, duy nhất. Không bao giờ dùng lại tài khoản tích hợp sẵn của iDRAC. 3. **Xuất bản thư mục ISO cho các iDRAC - chỉ với một lệnh.** Trên máy chủ panel, với quyền root, sử dụng địa chỉ mà máy chủ đó sở hữu trong management network và mạng iDRAC: ```bash sudo nexcmp dedicated-setup-iso --listen 10.20.0.2:8080 --allow 10.20.0.0/24 ``` `--listen` phải là một địa chỉ của máy chủ này (IPv4 private, mặc định là cổng 8080 nếu bỏ qua). `--allow` liệt kê (các) dải mạng iDRAC (CIDR private, từ /16 trở xuống, tối đa 8 dải, phân tách bằng dấu phẩy); chỉ các dải này mới có thể tải xuống, và lệnh cũng sử dụng chúng làm `dedicated_bmc_cidrs` khi cài đặt đó vẫn đang là giá trị mẫu. `--dir /path` dùng để chọn thư mục ISO khác (mặc định là `/srv/nexcmp-iso`). Lệnh này sẽ: - tạo thư mục chứa `pub` và `server` bên trong, thuộc sở hữu của service user NexCMP; - tạo group `nexcmp-iso` và thêm user nginx vào đó, nhờ vậy nginx có thể đọc file ISO khi iDRAC đang mount mà không ai khác có thể truy cập; - cài đặt nginx site `nexcmp-iso` (chỉ được giữ lại nếu `nginx -t` chấp nhận, nginx sẽ được cài đặt nếu chưa có) và một systemd drop-in `nexcmp-vmd.service.d/iso.conf` (`ReadWritePaths` cho thư mục, `SupplementaryGroups=nexcmp-iso`); - ghi các cài đặt ISO (`dedicated_iso_base_url`, ba thư mục, group) và khởi động lại NexCMP worker. Lệnh có thể chạy lại với các giá trị khác, và `sudo nexcmp dedicated-setup-iso --remove` sẽ gỡ bỏ nginx site cũng như drop-in (các file ISO vẫn được giữ lại). Bạn cũng có thể chạy lệnh này khi cài đặt: thêm `--iso-listen`, `--iso-allow` (và `--iso-dir`) vào lệnh cài đặt. Lệnh này **không** tạo management network và không kết nối tới bất kỳ iDRAC nào; nếu các giá trị bị sai, địa chỉ không thuộc máy chủ này hoặc cổng đã bị chiếm, lệnh sẽ dừng lại kèm thông báo trước khi thay đổi bất kỳ điều gì, và nginx site mà `nginx -t` từ chối sẽ không được giữ lại. 4. **Web server ISO phục vụ những gì.** Trang nginx phản hồi `GET` (và `HEAD`, với byte range) cho `/pub/.iso` và không có gì khác: không duyệt thư mục, không có đường dẫn nào khác dưới thư mục (thư viện và `server/` không thể truy cập), không có phương thức nào khác, và chỉ từ các mạng `--allow` (bất kỳ ai khác đều nhận mã 403). NexCMP hiển thị mỗi ISO mà một iDRAC cần đọc dưới dạng tệp hoặc liên kết ngắn hạn trong `pub`; nginx chỉ mở liên kết khi liên kết và đích của nó có cùng chủ sở hữu (service user), do đó liên kết đến tệp hệ thống sẽ bị từ chối. Hãy kiểm tra từ một host khác trên mạng quản trị: ```bash curl -I http://10.20.0.2:8080/ # 403 or 404, never a listing curl -I http://10.20.0.2:8080/pub/ # 403 or 404 ``` Một tệp thử nghiệm trong `pub` sẽ phản hồi yêu cầu `Range` với mã 206. *Nếu thực hiện thủ công:* site nginx và drop-in được cung cấp dưới dạng bản mẫu trong gói phát hành (`share/dedicated/nginx-iso.conf` và `share/dedicated/vmd-iso.conf` dưới `/opt/nexcmp/releases//`). Hãy sao chép chúng, thay thế các điểm đánh dấu `__...__` (địa chỉ listen, thư mục, các dòng allow, nhóm) và giữ nguyên các quy tắc ở trên. 5. **Chuẩn bị sẵn các image hệ điều hành.** Đặt các ISO tự cài đặt vào thư mục library (xem **Templates** bên dưới). Khách hàng cũng có thể thêm ISO từ một liên kết; các file này sẽ được tải về server, không bao giờ chuyển trực tiếp cho iDRAC dưới dạng URL. ## Kết nối trong NexCMP {#connect-in-nexcmp} ### Bước 1: Bật module {#_1-turn-the-module-on} Tại **System › Admin › License & updates**, hãy bật **Bare Metal**. Danh mục **Bare Metal** sẽ xuất hiện dưới Infrastructure. Xem [Modules](https://nexcmp.com/vi/docs/infrastructure/modules/). ### 2. Thiết lập kết nối mạng quản trị {#_2-set-the-management-network-connection} Mở **Infrastructure › Bare Metal › Safety**. Thẻ **Management network connection** chứa ba giá trị quyết định hệ thống có thể hoạt động được hay không: | Trường | Cài đặt | Nội dung cần nhập | |---|---|---| | Mạng iDRAC (CIDR) | `dedicated_bmc_cidrs` | (Các) mạng riêng của iDRAC của bạn, ví dụ `10.20.0.0/24`. Chỉ chấp nhận CIDR riêng, /16 hoặc nhỏ hơn, tối đa 8 dải mạng, phân tách bằng dấu phẩy. Chỉ các iDRAC trong những dải này mới có thể được nhập. | | Máy chủ ISO cho iDRAC | `dedicated_iso_base_url` | `http://[:port]`, không có đường dẫn: địa chỉ của ISO web server từ phần trước, ví dụ `http://10.20.0.2:8080`. Lệnh một bước sẽ tự động điền giúp bạn. | | Địa chỉ callback của panel | `dedicated_callback_base` | `https://`, không có đường dẫn: địa chỉ mà máy chủ đang được cài đặt gọi về để báo cáo hoàn tất. Địa chỉ này phải truy cập được từ mạng của máy chủ đó. `example.com`, `localhost` và các giá trị tương tự sẽ bị từ chối. | Biểu mẫu sẽ kiểm tra định dạng khi bạn nhập và máy chủ sẽ kiểm tra lại khi lưu; giá trị không hợp lệ sẽ bị từ chối kèm lý do và giá trị đã lưu vẫn giữ nguyên như cũ. Trường nào vẫn còn giữ giá trị mẫu ban đầu sẽ mang nhãn **Not configured** màu đỏ, và mọi trang Bare Metal sẽ hiển thị thông báo màu đỏ **Management network not configured** cho đến khi cả ba giá trị đều là thực tế. Các thay đổi được ghi vào audit log kèm theo lý do của bạn. Việc lưu lại giá trị mẫu sẽ không được tính là đã cấu hình trừ khi bạn tự tay nhập nó. ### 3. Kiểm tra cổng an toàn (tạm thời để đóng) {#_3-check-the-safety-gate-leave-it-closed-for-now} Mở **Infrastructure › Bare Metal › Safety**. **Live ops** là công tắc trên toàn hệ thống cho mọi lệnh ghi tới một iDRAC (nguồn điện, virtual media, console và cài đặt hệ điều hành). Nó khởi đầu ở trạng thái **off**, và không thể bật khi kết nối mạng quản trị ở trên vẫn còn giữ các giá trị mẫu (công tắc phản hồi `config_placeholder` và nêu rõ tên các trường). Các thao tác ghi bị từ chối tại API và một lần nữa bên trong worker, trong khi việc đọc trạng thái vẫn tiếp tục hoạt động. Khóa thứ hai, **ops_locked**, bảo vệ từng máy chủ: các máy chủ mới nhập luôn bị khóa, ngay cả khi live ops đang bật. ![Trang Safety với Live ops đang tắt và danh sách các hành động bị chặn](https://nexcmp.com/vi/docs/images/infrastructure/dedicated-01-safety.webp) ### 4. Nhập máy chủ {#_4-import-servers} 1. Mở **Infrastructure › Bare Metal › Stock / iDRAC import**. 2. Tại mục **Add one server**, hãy nhập địa chỉ iDRAC, tài khoản và mật khẩu, sau đó nhấp vào **Test connection**. Quá trình kiểm tra chỉ gửi các lệnh đọc và không lưu bất kỳ thông tin nào. | Trường | Giá trị ví dụ | |---|---| | Địa chỉ iDRAC (URL hoặc host) | `10.20.0.11` | | Tài khoản | `nexcmp-admin` | | Mật khẩu | `XXXX` | | Nhãn | `rack1-01` (để trống: tự động tạo) | | Gán IP từ một pool | tùy chọn; chọn pool IP dịch vụ của máy chủ | | Đưa vào danh sách mở bán | tắt cho đến khi bạn sẵn sàng | ![Stock và iDRAC import với địa chỉ ví dụ cùng kết quả kiểm tra chỉ đọc thành công](https://nexcmp.com/vi/docs/images/infrastructure/dedicated-02-import-server.webp) 3. Nhấp vào **Save to stock**. NexCMP sẽ đọc model, CPU, RAM, ổ đĩa, NIC và service tag từ iDRAC. Máy chủ được đưa vào kho ở trạng thái **locked**. 4. Đối với nhiều máy chủ, hãy sử dụng **Bulk import**: mỗi máy chủ một dòng, các trường phân tách bằng dấu phẩy, dấu chấm phẩy hoặc phím Tab. **Preview** sẽ kiểm tra allow-list, các địa chỉ iDRAC hoặc service tag bị trùng lặp, đồng thời đọc thông tin phần cứng (tối đa bốn máy chủ cùng lúc). ### 5. ISO của khách hàng và địa chỉ web ISO {#_5-customer-isos-and-the-iso-web-address} Mở **Infrastructure › Bare Metal › Customer ISOs**. - **HTTP address serving ISOs to iDRAC** là `dedicated_iso_base_url`, cùng giá trị như trong thẻ Safety (có thể chỉnh sửa ở một trong hai nơi). Hãy nhập địa chỉ mạng quản trị của ISO web server của bạn. - **Customer ISO limits** thiết lập dung lượng của một ISO, tổng dung lượng lưu trữ ISO, dung lượng trống tối thiểu, thời gian lưu giữ ISO (giờ), thời gian tải xuống tối đa và số lượng tác vụ tải xuống đồng thời. ![Customer ISOs với địa chỉ HTTP cho iDRAC và các giới hạn ISO](https://nexcmp.com/vi/docs/images/infrastructure/dedicated-03-iso-settings.webp) ### 6. Template OS {#_6-os-templates} Mở **Infrastructure › Bare Metal › Templates**. Trang này liệt kê các ISO tự cài đặt được tìm thấy trong thư mục library. Nhấp vào **Register** tại một file để điền nhóm hệ điều hành, phiên bản và tài khoản (được điền sẵn từ tên file), sau đó chuyển template sang **Enable**. Việc bật template sẽ không khởi chạy bất kỳ tác vụ nào: mọi quá trình cài đặt vẫn phải đi qua chốt an toàn. **Unregister** chỉ xóa dòng template, không bao giờ xóa file. ![Bare Metal Templates với ISO đã đăng ký và chưa đăng ký](https://nexcmp.com/vi/docs/images/infrastructure/dedicated-04-os-templates.webp) ### 7. IP pool {#_7-ip-pools} Mở **Infrastructure › Bare Metal › IP Pools** và thêm các dải IPv4 mà máy chủ nhận làm địa chỉ dịch vụ. Mỗi máy chủ nhận một địa chỉ; tùy chọn **Assign an IP from a pool** khi import sẽ lấy địa chỉ còn trống tiếp theo. Số lượng địa chỉ còn trống được tính theo từng pool. ![Bare Metal IP Pools với các dải IP ví dụ và số lượng còn trống](https://nexcmp.com/vi/docs/images/infrastructure/dedicated-05-ip-pools.webp) ### 8. Gói dịch vụ và mở bán {#_8-plans-and-sale} 1. Mở **Services › Dedicated Server › Plans & pricing**. Chỉnh sửa bốn gói mẫu (được đặt tên là `BM-40C-` trong 1.6.1) hoặc tạo gói của riêng bạn: giá, chu kỳ thanh toán và phí thiết lập. **Trên bản cài đặt mới, giá được nhập bằng đô la Mỹ, chính xác đến từng cent, và ví tiền sẽ bị trừ đúng số tiền đó: không cần tỷ giá hối đoái.** Bản cài đặt đã có sẵn các gói định giá bằng đồng Việt Nam vẫn giữ nguyên VND và vẫn cần tỷ giá hối đoái trong phần cài đặt (nếu không có, đơn hàng sẽ bị từ chối với `dedicated_fx_unavailable`). Các gói mẫu bắt đầu với giá bằng 0 và ở trạng thái **disabled**: gói dịch vụ muốn mở bán cần có giá lớn hơn 0. Hãy đối chiếu từng gói với phần cứng thực tế mà bạn import; tên gói mẫu không tự phát hiện hay thay đổi phần cứng của máy chủ. 2. Mở máy chủ (Infrastructure › Bare Metal › the server › **Sales**), **gán plan** và bật **Sellable**. 3. Bật **live ops** (trang Safety, kèm xác nhận bằng cách nhập văn bản) và mở khóa các máy chủ bạn muốn vận hành (tab **Lock** của máy chủ, kèm lý do được lưu vào audit log). 4. Tại **Services › Dedicated Server**, hãy bật tính năng bán hàng. Thao tác này gồm hai bước: đọc các hệ quả, sau đó nhập `ENABLE SALES`. Cho đến lúc đó, khách hàng sẽ không thấy trang đặt hàng và không bị tính phí. ![Các gói Dedicated Server khi công tắc bán hàng đang tắt](https://nexcmp.com/vi/docs/images/infrastructure/dedicated-06-plans.webp) ### Những thao tác khách hàng có thể thực hiện trên trang máy chủ của họ {#what-customers-can-do-on-their-server-page} Trang máy chủ của khách hàng có mười sáu tab thuộc bảy nhóm (Overview, Control, Network, Hardware, Billing, Activity, Settings). Nhóm **Billing** bao gồm: - **Plan & renewal**: thanh toán trước từ 1 đến 24 tháng chỉ trong một bước; ngày gia hạn mới được tính từ ngày gia hạn hiện tại và ví chỉ bị trừ tiền một lần. Tự động gia hạn có thể bật hoặc tắt. - **Billing cycle**: chọn một chu kỳ khác (ví dụ theo quý); chu kỳ mới áp dụng từ kỳ gia hạn **tiếp theo**, hiện tại không bị trừ tiền hay hoàn phí. - **Change plan**: khách hàng có thể **yêu cầu** đổi gói khác. Yêu cầu này không trừ tiền ngay. Bạn duyệt hoặc từ chối yêu cầu tại **Services › Dedicated Server › Plan changes**, sau khi đã nâng cấp phần cứng hoặc chuyển server. Nâng cấp được duyệt sẽ tính phí chênh lệch cho thời gian còn lại mà khách hàng đã thanh toán; hạ cấp sẽ không hoàn tiền và áp dụng từ kỳ tiếp theo. - **Invoices**: mọi hóa đơn của server đó (đơn hàng, gia hạn, nâng cấp). Tại **Plan changes**, sắp xếp các yêu cầu theo ID, ngày, trạng thái, gói hoặc máy chủ; việc sắp xếp áp dụng cho toàn bộ kết quả trên máy chủ. Cột thao tác vẫn hiển thị cố định khi bạn cuộn ngang trên màn hình hẹp. Ở đầu **Overview**, bốn ô thông tin trực tiếp hiển thị **CPU**, **RAM**, **Disk** và **Network**, đi kèm một biểu đồ nhỏ cho 24 giờ qua. CPU, RAM và Disk là phần trăm mức sử dụng từ lần thăm dò iDRAC gần nhất (Disk là hoạt động I/O, không phải dung lượng trống); Network là tốc độ tải vào và tải ra hiện tại cộng với tổng lưu lượng trong tháng, được lấy từ bộ đếm lưu lượng. Ô thông tin sẽ hiển thị **—** cùng lý do ngắn gọn khi máy chủ tắt, không thể kết nối iDRAC hoặc máy không báo cáo giá trị đó; hệ thống không bao giờ hiển thị số 0 giả định. Các chỉ số này đến từ Dell iDRAC, và nếu không có bộ đếm lưu lượng thì ô Network sẽ giữ nguyên ở mức **—**. Các ô này tự động làm mới mỗi phút khi trang đang mở, và khi nhấp chuột sẽ mở tab **Hardware** hoặc **Bandwidth**. Trên trang **Overview**, thẻ **Access** hiển thị tên người dùng và mật khẩu của hệ điều hành bạn đã cài đặt, mặc định bị ẩn kèm các nút **Show** và **Copy**. Thông tin này luôn khả dụng sau mỗi lần cài đặt chứ không chỉ hiển thị một lần, và chủ sở hữu mới của server không bao giờ thấy mật khẩu của chủ sở hữu trước đó. Nếu mật khẩu OS bị thay đổi bên trong server, thẻ vẫn hiển thị mật khẩu được thiết lập lúc cài đặt. Tab **Bandwidth** chỉ xuất hiện khi có agent đếm traffic cấp dữ liệu (xem phần Giới hạn). Không có tab **Subnet**: NexCMP không hỗ trợ việc mang dải IP prefix riêng vào server thuê. ### Những việc khách hàng có thể và không thể làm {#what-customers-can-and-cannot-do} | Khách hàng có thể | Không bao giờ được phép | |---|---| | Xem thông tin phần cứng, trạng thái sức khỏe, trạng thái nguồn và số liệu giám sát | Xem địa chỉ iDRAC, tên người dùng hoặc mật khẩu | | Bật nguồn, tắt nguồn an toàn (graceful shutdown), khởi động lại, buộc tắt nguồn, reset | Thay đổi tài khoản iDRAC hoặc cài đặt mạng iDRAC | | Mở console trên trình duyệt (mỗi lần một phiên) | Thay đổi BIOS hoặc RAID, xóa nhật ký, cập nhật firmware, reset iDRAC | | Gắn ISO hoặc liên kết ISO riêng, thiết lập boot một lần, cài lại hệ điều hành từ template đang bật | Thực thi lệnh gọi Redfish thô (các tính năng này không tồn tại trong NexCMP) | NexCMP không tạo tài khoản iDRAC cho khách hàng: họ chỉ sử dụng các trình điều khiển trên cổng portal, đồng thời địa chỉ và thông tin đăng nhập iDRAC không bao giờ hiển thị với họ. ## Kiểm tra {#verify} 0. Trên **Safety**, thẻ **Management network connection** không hiển thị nhãn màu đỏ và các trang Bare Metal không có thông báo màu đỏ. Từ một host trên management network, `curl -I http:///` không liệt kê các tệp. 1. **Test connection** trên biểu mẫu import sẽ trả về model, CPU, RAM và service tag. 2. Máy chủ xuất hiện trong **Servers** cùng thông tin phần cứng. Khi **live ops tắt**, thao tác nguồn sẽ bị từ chối với thông báo "Server control is temporarily disabled system-wide". 3. Sau khi bật live ops và mở khóa một máy chủ thử nghiệm, hãy tắt và bật nguồn máy chủ từ **Operations** hoặc trang máy chủ, rồi mở console. 4. Đặt một đơn hàng thử nghiệm với gói thử nghiệm: máy chủ được gán, hệ điều hành được cài đặt và quá trình cài đặt kết thúc khi máy chủ báo cáo về bảng điều khiển. ## Giới hạn và lưu ý {#limits-and-notes} - Mỗi máy chủ vật lý chỉ có tối đa một gói đăng ký đang hoạt động. - Lệnh ghi chỉ được gửi khi **cả hai** điều kiện thỏa mãn: live ops đang bật **và** khóa của máy chủ đã mở. Việc kiểm tra này được lặp lại bên trong worker ngay trước mỗi lệnh. - Trạng thái **Installing** sẽ chờ hệ điều hành mới phản hồi trên cổng tương ứng (SSH 22, Windows 3389, Proxmox 8006) trước khi đơn hàng hoàn tất; quá trình cài đặt có giới hạn thời gian (`dedicated_install_timeout_min`, mặc định 150 phút). - Băng thông cho dedicated server được tính từ một traffic-counter agent không đi kèm trong bản cài đặt tiêu chuẩn. Nếu không có agent này, hệ thống sẽ không ghi nhận gì, portal sẽ ẩn tab Bandwidth và API sẽ báo cáo `capabilities.bandwidth` là `false`. - Các thao tác quản trị đối với dịch vụ thuê server (khóa, mở khóa, hủy có hoặc không hoàn tiền) đều là các thao tác hợp nhất tương tự như mọi dịch vụ khác, với số tiền hoàn lại được cộng vào số dư ban đầu đã dùng để thanh toán. - Máy chủ không được bán lại qua đại lý: Dedicated chỉ được bán từ trang chính. ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | Kiểm tra thất bại do lỗi địa chỉ | Địa chỉ không phải là IPv4 literal trong `dedicated_bmc_cidrs` (private, /16 hoặc nhỏ hơn) hoặc cổng không được cho phép | Sử dụng địa chỉ IPv4 của iDRAC và thêm mạng của nó trong Safety › Management network connection (`dedicated_bmc_cidrs`). Tên miền DNS và IPv6 bị từ chối. | | Thông báo màu đỏ "Management network not configured", hoặc nút live ops phản hồi `config_placeholder` | Một trong các giá trị `dedicated_bmc_cidrs`, `dedicated_iso_base_url`, `dedicated_callback_base` vẫn giữ giá trị mẫu mặc định | Nhập các giá trị thực tế trong Safety › Management network connection. | | Một trường bị từ chối khi lưu | Sai định dạng (CIDR không phải mạng private hoặc rộng hơn /16, địa chỉ ISO không phải `http://[:port]`, callback không phải `https://`), hoặc là địa chỉ mẫu như `example.com` | Đọc thông báo bên dưới trường dữ liệu; giá trị đã lưu trước đó không thay đổi. | | `nexcmp dedicated-setup-iso` dừng lại trước khi thay đổi bất kỳ điều gì | `--listen` không phải là địa chỉ của server này, cổng đã được sử dụng hoặc một giá trị không hợp lệ | Sử dụng địa chỉ mà server này có trên management network, một cổng khác hoặc sửa lại giá trị được nêu trong thông báo. | | "Chứng chỉ TLS của iDRAC khác với chứng chỉ đã ghim - hoạt động polling và ghi đã dừng" | Chứng chỉ iDRAC đã bị thay thế (chứng chỉ mới, thay iDRAC khác) | Mở máy chủ, tab **Access**, so sánh hai fingerprint và nếu thay đổi này là đúng, nhấp vào **Repin certificate**. | | "Tính năng điều khiển máy chủ tạm thời bị vô hiệu hóa trên toàn hệ thống" | Live ops đang tắt | Bật tính năng này trong **Safety**. | | "Máy chủ này đang bị khóa đối với các thao tác" | Khóa riêng của máy chủ đang đóng | Mở khóa trong tab **Lock** của máy chủ kèm theo lý do. | | "Một thao tác khác vẫn đang chạy trên máy chủ này" | Thao tác trước đó chưa hoàn tất | Chờ hoàn tất; kiểm tra **Operations**. | | "Một phiên console khác đã được mở trên máy chủ này" | Chỉ cho phép một phiên console tại một thời điểm | Đóng phiên còn lại. | | "Bộ điều khiển của máy chủ tạm thời không khả dụng" | iDRAC không phản hồi | Kiểm tra mạng quản trị và iDRAC. | | Gắn ISO thất bại kèm mã lỗi 403 hoặc 404 từ iDRAC | Web server không thể đọc tệp hoặc địa chỉ gốc bị sai | Kiểm tra quyền hạn của web server chứa ISO và **HTTP address serving ISOs to iDRAC**. | | "Gói này đã hết hàng tại vị trí đã chọn" | Không có máy chủ khả dụng để bán cho gói cước đó trong khu vực | Gán gói cước cho máy chủ và bật **Sellable**. | | "Hiện không có địa chỉ IPv4 nào khả dụng để gán" | IP pool đã hết | Thêm địa chỉ vào pool. | | "Tính năng cài đặt hệ điều hành tự động hiện không khả dụng" | Thiếu các điều kiện tiên quyết để cài đặt | Kiểm tra xem template đã bật chưa và các thư mục ISO có quyền ghi hay không; khách hàng vẫn có thể cài qua ISO và console. | | Quá trình cài đặt bị treo | Máy chủ đang cài đặt không thể kết nối tới địa chỉ callback | Kiểm tra `dedicated_callback_base` và đảm bảo mạng của máy chủ có thể kết nối tới panel của bạn qua HTTPS. | --- # Node VPN và proxy IPv6 {#vpn-and-ipv6-proxy-nodes} > **Vị trí trong admin:** Infrastructure › VPN & Proxy nodes › Agents & external nodes (`/agents`), VPN IP pools (`/vpn/pool`), IPv6 Proxy nodes (`/vpn/proxy6/nodes`). Bản thân các dịch vụ nằm tại Services › VPN và Services › IPv6 Proxy. Cả hai module đều được bật trong System › Admin › License & updates. ## Chức năng {#what-it-does} NexCMP bán quyền truy cập VPN và proxy đi ra từ **địa chỉ IP bạn sở hữu**, trên các máy chủ do bạn vận hành. Hiện có hai loại node: - **Node VPN.** Một chương trình Go nhỏ, `cmp-agent`, chạy trên máy chủ Linux của bạn. Nó tự phát hiện các địa chỉ IPv4 public trên máy chủ, mở listener SOCKS5, HTTP và UDP trên từng địa chỉ được bán, rồi định tuyến lưu lượng đi ra từ **chính IP đó** mà khách hàng đã kết nối tới (same-IP egress). Nó báo cáo về panel định kỳ sau mỗi vài giây. - **IPv6 proxy node.** Dịch vụ proxy cung cấp cho khách hàng các địa chỉ từ prefix IPv6 bạn định tuyến đến máy chủ. Panel sẽ cài đặt dịch vụ này cho bạn qua SSH. Sử dụng chúng để bán lại các địa chỉ IP sạch tại những quốc gia nơi bạn có máy chủ. ## Yêu cầu {#requirements} ### VPN node {#vpn-node} | Hạng mục | Yêu cầu | |---|---| | Hệ điều hành | Bản phân phối Linux có systemd và kernel 4.15 trở lên (hỗ trợ IPv6 free-bind). Binary agent đi kèm chỉ dành cho **x86_64** (amd64). | | Quyền hạn | root, để cài đặt. Dịch vụ chỉ giữ lại `CAP_NET_ADMIN`, `CAP_NET_RAW` và `CAP_DAC_READ_SEARCH`. | | Công cụ | `curl` hoặc `wget`, và `sha256sum` (trình cài đặt từ chối tiếp tục nếu không kiểm tra tệp). | | Địa chỉ public | Các địa chỉ IPv4 public được gán trên một interface của máy chủ (mỗi địa chỉ một `/32`), **hoặc** một prefix được định tuyến đến máy chủ mà bạn thêm vào dưới dạng subnet phụ (IPv4 /16 đến /32, IPv6 /48 đến /128). Các dải private, CGNAT và tài liệu hướng dẫn sẽ bị bỏ qua. | | Mạng, inbound | Khách hàng kết nối tới từng IP public đã bán trên **cổng 65001-65535** (TCP cho SOCKS5 và HTTP, UDP cho UDP associate). Mỗi endpoint sử dụng một bộ ba cổng liên tiếp. | | Mạng, outbound | HTTPS (443) đến domain của panel của bạn. Agent cũng tra cứu quốc gia của chính nó trên `ip-api.com` (HTTP) và `ipinfo.io` (HTTPS), với giới hạn 3.5 giây. | | Mail | Các kết nối outbound tới port 25 luôn bị chặn; không có cài đặt nào để mở port này. | | Docker, VPN và các interface ảo | Các interface có tên `docker*`, `veth*`, `br-*`, `cni*`, `flannel*`, `virbr*`, `cali*`, `tun*`, `tap*`, `wg*` và `tailscale*` không đóng góp địa chỉ. | | Phụ thuộc vào | Module **VPN**, một zone (được tạo tự động từ quốc gia của máy chủ) và panel NexCMP có thể truy cập được qua HTTPS. | ### IPv6 proxy node {#ipv6-proxy-node} | Hạng mục | Yêu cầu | |---|---| | Hệ điều hành | Linux có systemd trên **x86_64**. Các lệnh `systemctl`, `nft`, `ip`, `ss`, `sysctl` và `useradd` phải tồn tại; nếu không, quá trình cài đặt sẽ dừng lại và nêu tên lệnh còn thiếu. | | Quyền truy cập để cài đặt | Một địa chỉ IPv4 public (từ chối các địa chỉ private, loopback và CGNAT), cổng SSH, tài khoản có quyền root hoặc quyền `sudo` và **mật khẩu** của tài khoản đó. Mật khẩu chỉ được dùng để cài đặt và không được lưu trữ. | | Các cổng còn trống | **80, 443 và mọi cổng trên 60000** phải còn trống. Trình cài đặt không bao giờ dừng hoặc thay đổi các dịch vụ đang chạy; nó sẽ báo cáo các cổng đang bận và dừng lại. | | IPv6 | Một prefix public trong khoảng **/32 và /64** bên trong `2000::/3` mà máy chủ có thể sử dụng làm nguồn cho lưu lượng outbound, được bàn giao theo kiểu **định tuyến** đến máy chủ hoặc **on-link** với NDP proxy (xem bên dưới). | | Mạng | Khách hàng kết nối tới IPv4 của node qua port 80 (HTTP proxy), port 443 (SOCKS5) và các port 60001-65535 (mỗi IP tĩnh một port). Node không có chứng chỉ nên không có HTTPS proxy. Lưu lượng ra chỉ đi qua IPv6 và chỉ tới các đích có địa chỉ IPv6. Node lấy cấu hình từ panel qua HTTPS. | | Phần mềm node trên máy chủ panel | Node daemon và script mạng của nó được tích hợp sẵn trong gói phát hành NexCMP. Panel sao chép chúng từ thư mục cài đặt của mình (`/opt/nexcmp/releases//bin`, hoặc `/opt/nexcmp/bin` trên bản build tùy biến) sang từng node trong quá trình cài đặt. Máy chủ panel cũng cần `sshpass` và một SSH client; trình cài đặt sẽ bổ sung `sshpass`, còn trên máy chủ được cài đặt trước phiên bản 1.4.2, bạn thêm nó bằng `sudo apt-get install -y sshpass`. | | Phụ thuộc vào | Module **IPv6 Proxy**, và URL panel mà các node gọi ngược về (**IPv6 Proxy › Settings › Panel URL for nodes**, mặc định là `https://`). | ## Chuẩn bị hạ tầng {#prepare-the-infrastructure} ### VPN node {#vpn-node-1} 1. **Khởi tạo máy chủ** với một bản phân phối Linux được hỗ trợ và các địa chỉ IPv4 public bạn muốn bán, được cấu hình trên network interface hoặc được định tuyến đến máy chủ. 2. **Nếu bạn bán một routed block**, hãy dự kiến nhập nó dưới dạng **Extra subnet** khi thêm node. Agent sẽ cài đặt một route `local dev lo` để host chấp nhận lưu lượng cho mọi địa chỉ trong block, sau đó báo cáo các địa chỉ tìm thấy. Agent cũng đọc bảng định tuyến thực tế của host và không bao giờ bán hoặc chiếm giữ địa chỉ **gateway**: nếu block chứa next-hop của một trong các route trên host (chẳng hạn như địa chỉ router của một block on-link), agent sẽ chỉ cài đặt các route `local` cho các phần của block xung quanh địa chỉ đó, báo cáo gateway về panel, và panel sẽ loại trừ địa chỉ đó khỏi pool cũng như mọi lượt cấp phát. Nó sẽ xóa các route đã cài đặt khi extra subnet thay đổi hoặc khi agent dừng. 3. **Mở firewall.** Cho phép TCP và UDP inbound **65001-65535** trên các địa chỉ public, và HTTPS outbound đến panel. 4. **Tùy chọn: bộ đếm byte theo từng IP.** Conntrack accounting (`net.netfilter.nf_conntrack_acct = 1`) cho phép vai trò giám sát đếm số byte theo từng IP. Panel có thể bật tính năng này bằng cách gửi lệnh `acct` tới agent, thao tác này cũng sẽ ghi `/etc/sysctl.d/99-cmp-agent.conf`. Bản thân vai trò VPN không cần đến tính năng này. 5. **Kiểm tra panel từ node:** ```bash curl -fsS -o /dev/null -w '%{http_code}\n' https://cloud.example.com/install.sh ``` ### IPv6 proxy node {#ipv6-proxy-node-1} Tiền tố IPv6 đến được node theo một trong hai cách. Trình cài đặt sẽ kiểm tra cả hai bằng các kết nối outbound thực tế và giữ lại cách thức hoạt động. | Loại | Ý nghĩa | Cấu hình cần thực hiện | |---|---|---| | **Routed** | Upstream của bạn định tuyến một tiền tố (ví dụ: /48 hoặc /56) **tới địa chỉ riêng của node**. Các gói tin outbound có thể sử dụng bất kỳ địa chỉ nào trong tiền tố làm nguồn và phản hồi sẽ quay trở lại node. | Yêu cầu nhà cung cấp của bạn cung cấp một tiền tố định tuyến có next hop là node. Không cần làm gì thêm trên node: dịch vụ proxy sử dụng transparent socket, một bảng policy-routing cố định và `nft`. | | **On-link** | Dải /64 nằm trên cùng mạng LAN với node. Phản hồi chỉ hoạt động nếu node phản hồi neighbour discovery cho từng địa chỉ đang được sử dụng (**NDP proxy**). | Dịch vụ sẽ thiết lập `net.ipv6.conf..accept_ra=2`, `forwarding=1` và `proxy_ndp=1` chỉ riêng trên giao diện đó, ghi nhớ các giá trị cũ, khôi phục lại khi dừng và chặn chuyển tiếp các địa chỉ của pool để node không trở thành router cho pool. | Cách thức kiểm tra hoạt động: node sẽ thử kết nối TCP đến một địa chỉ IPv6 public (cổng 443) từ một địa chỉ ngẫu nhiên thuộc tiền tố tiềm năng, trong vòng 6 giây. Các ứng viên là các địa chỉ global trên các giao diện có tiền tố từ /64 trở xuống, cùng các tuyến đường loại `local`, `unreachable` hoặc `blackhole` từ /16 đến /64. Tiền tố ngắn hơn /64 sẽ được chấp nhận là **routed** nếu một dải /64 ngẫu nhiên bên trong nó hoạt động. ::: warning Không sử dụng cùng một tiền tố hai lần Một tiền tố không được trùng lặp với tiền tố của node khác, và không được rộng hơn tiền tố đã thuộc về IPv6 pool riêng của panel. Một dải /64 **nằm trong** pool của panel được cho phép. Các trường hợp trùng lặp sẽ được báo cáo là "assign range … (node …)" trong kết quả cài đặt và tiền tố đó sẽ bị bỏ qua. ::: Các hạn chế mà node tự áp dụng: khách hàng không thể gửi thư (cổng 25, 465, 587, 2525) từ các địa chỉ trong pool, và lưu lượng IPv4 của chính daemon bị giới hạn ở các phản hồi cùng lưu lượng tới panel và DNS. ## Kết nối trong NexCMP {#connect-in-nexcmp} ### VPN node {#vpn-node-2} 1. Tại **System › Admin › License & updates**, hãy bật **VPN**. Xem [Modules](https://nexcmp.com/vi/docs/infrastructure/modules/). ![Thẻ Module với các công tắc VPN và IPv6 Proxy](https://nexcmp.com/vi/docs/images/infrastructure/vpn-proxy-nodes-01-modules.webp) 2. Mở **Infrastructure › VPN & Proxy nodes › Agents & external nodes**. Bạn có hai cách để thêm node. **a. Cài đặt qua SSH.** Nhấp vào **+ Add server (SSH)** và điền: | Trường | Giá trị ví dụ | |---|---| | Địa chỉ IPv4 của máy chủ | `192.0.2.50` | | Cổng SSH | `22` | | Người dùng SSH | `root` | | Mật khẩu SSH | `XXXX` | | Tên hiển thị | `node-ny-1` (để trống: đặt tên theo IP) | | Vai trò máy chủ | External VPN / Proxy Node | | Chỉ định Zone | Tự động theo GeoIP (tạo / chỉ định Zone), hoặc một zone hiện có | | Subnet bổ sung (tùy chọn) | để trống để tự động quét giao diện, hoặc một khối định tuyến như `203.0.113.0/24` | | Bật để bán sau khi cài đặt | bật để đánh dấu mọi địa chỉ được phát hiện là có thể bán | Nhấp vào **Connect & install**. Panel sẽ kết nối qua SSH, chạy trình cài đặt một dòng lệnh trên node với một ticket dùng một lần, và hiển thị tên node, vị trí GeoIP cùng các dải mạng được phát hiện. ![Hộp thoại Add Node via SSH với ví dụ về địa chỉ máy chủ và vai trò](https://nexcmp.com/vi/docs/images/infrastructure/vpn-proxy-nodes-02-add-server-ssh.webp) **b. Cài đặt thủ công.** Nhấp vào **Generate manual install token**. Lệnh sẽ chỉ hiển thị **một lần**; hãy sao chép và chạy lệnh đó trên node: ```bash curl -fsSL https://cloud.example.com/install.sh | sudo sh -s -- --token XXXX --name node-ny-1 ``` Việc cài đặt bằng token chỉ đăng ký máy để giám sát: để đảm bảo an toàn, panel không cho phép máy nắm giữ token dùng chung tự cấp vai trò VPN cho chính nó (việc thêm `--roles vpn` vào lệnh không có tác dụng). Sau khi máy xuất hiện trong danh sách, hãy mở máy đó và tự thêm vai trò **VPN**. Cài đặt qua SSH (tùy chọn a) sẽ gán vai trò VPN cho node ngay từ đầu. Token mới sẽ hủy bỏ token cũ; các host đã đăng ký trước đó vẫn tiếp tục hoạt động vì chúng sử dụng key riêng. ![Hộp thoại lệnh cài đặt hiển thị lệnh chứa token dùng một lần](https://nexcmp.com/vi/docs/images/infrastructure/vpn-proxy-nodes-03-install-command.webp) Quy trình bộ cài đặt thực hiện: tải xuống `cmp-agent-linux-amd64` từ panel của bạn, **xác minh SHA-256**, cài đặt vào `/usr/local/bin/cmp-agent`, đăng ký với token, ghi `/etc/cmp-agent/agent.json` và khởi chạy systemd service `cmp-agent`. Để gỡ bỏ: `curl -fsSL https://cloud.example.com/install.sh | sudo sh -s -- --uninstall`. 3. Sau lần heartbeat đầu tiên, node sẽ xuất hiện trong danh sách. Quốc gia của node được phát hiện qua GeoIP (node tự tra cứu trước, sau đó đối chiếu với cơ sở dữ liệu của panel); một **zone** cho quốc gia đó sẽ được tạo và đặt ở chế độ công khai nếu chưa tồn tại, và các địa chỉ tìm thấy trên host sẽ trở thành các dải pool. 4. Mở **Infrastructure › VPN & Proxy nodes › VPN IP pools** để xem các dải IP, zone và node tương ứng, đồng thời thay đổi zone, node hoặc nút gạt **Sellable** của từng dải. **Enable range** cho phép các đơn hàng mới sử dụng IP còn trống; **Disable range** chỉ dừng cấp phát mới, các IP đang thuê vẫn tiếp tục hoạt động. ![VPN IP pools với các dải IP được báo cáo bởi node](https://nexcmp.com/vi/docs/images/infrastructure/vpn-proxy-nodes-04-vpn-pool.webp) 5. Mở **Services › VPN**, thiết lập bảng giá và bật tính năng bán. Công tắc **Sell VPN** trên **Subscriptions** chính là công tắc của module VPN trong License & updates. 6. **Tùy chọn: đổi tên dịch vụ.** Trong **Settings › Branding**, **VPN service display name** dùng để thay đổi cách hiển thị tên dịch vụ VPN trong menu khách hàng, trang đặt hàng, trang chi tiết và danh sách triển khai (ví dụ `IPv4 Proxy`, `Datacenter Proxy` hoặc `Static Residential Proxy`; tối đa 40 ký tự, để trống sẽ giữ `VPN`). Cài đặt này chỉ thay đổi nhãn hiển thị: các route, dữ liệu và API không thay đổi. ### IPv6 proxy node {#ipv6-proxy-node-2} 1. Trên **System › Admin › License & updates**, bật **IPv6 Proxy**. 2. Mở **Infrastructure › VPN & Proxy nodes › IPv6 Proxy nodes** và nhấp vào **Add node (SSH)**. Nhập địa chỉ IPv4 của node, cổng SSH, user, password, tên tùy chọn và **Reason** (thông tin này được ghi vào nhật ký kiểm toán), sau đó nhấp vào **Install**. ![Hộp thoại thêm IPv6 node với địa chỉ và lý do mẫu](https://nexcmp.com/vi/docs/images/infrastructure/vpn-proxy-nodes-05-proxy6-add-node.webp) 3. Sau đó, panel sẽ lần lượt: kiểm tra máy chủ và các cổng, sao chép daemon, network script, service unit và tệp môi trường riêng của node (node token và khóa ký mật khẩu), chạy **probe** để tìm các prefix khả dụng, ghi nhận prefix vào pool, khởi động service và chờ tối đa 90 giây cho báo cáo đầu tiên. **Install log** sẽ hiển thị từng bước. 4. Node mới sẽ tạo zone tương ứng ở trạng thái **tắt** (dựa trên GeoIP từ IPv4 của node). Hãy bật zone trong **Infrastructure › Datacenter › Zone** để khách hàng có thể chọn. 5. Thiết lập **Mbps cap** tổng cho mỗi node (từ 10 đến 100000 cho mỗi chiều). Trong **Services › IPv6 Proxy**, hãy thiết lập bảng giá và bật tính năng bán hàng. 6. Kiểm tra **IPv6 Proxy › Settings › Panel URL for nodes**. Các node sẽ gọi địa chỉ này (`https://host`, không có đường dẫn) để lấy cấu hình và gửi báo cáo. Để trống có nghĩa là `https://`. Đây phải là host có địa chỉ trỏ thẳng tới panel, để IPv4 riêng của node kết nối tới mà không bị thay đổi. ::: tip Lịch xoay vòng Khách hàng có thể đặt khoảng thời gian xoay vòng tự động từ 30 đến 600 giây. Trong NexCMP, panel sẽ chạy lịch trình đó (cùng với việc dọn dẹp log kết nối hàng giờ); các node sẽ nhận địa chỉ mới trong khoảng 5 giây. ::: ### Cách thức báo cáo của node {#how-a-node-reports} | | VPN node (`cmp-agent`) | IPv6 proxy node | |---|---|---| | Đăng ký (Enrollment) | Ticket hoặc token dùng một lần qua HTTPS, sau đó dùng khóa riêng | Cài đặt một lần qua SSH, sau đó dùng node token | | Heartbeat | Mỗi **5 giây** (10 giây đối với agent chỉ giám sát); panel có thể thiết lập từ 3 đến 300 giây. Sau khi gặp lỗi, thời gian chờ tăng dần theo từng bước 5 giây lên đến tối đa 60 giây | Node gửi báo cáo định kỳ khoảng mỗi 60 giây và kéo cấu hình về | | Hiển thị là online | Có heartbeat trong vòng **60 giây** gần nhất | **alive** trong vòng **120 giây** gần nhất, nếu không sẽ là **missed heartbeat** | | Thay đổi cấu hình | Được áp dụng ở lần heartbeat tiếp theo | Được áp dụng trong khoảng 5 giây | | Cập nhật | Panel có thể gửi lệnh `upgrade` kèm phiên bản mới, URL và SHA-256 | Cài đặt lại từ hàng của node | ### Hạn mức dung lượng trên VPN node {#data-allowance-on-a-vpn-node} Từ phiên bản NexCMP **1.5.1**, agent của VPN node sẽ gửi lưu lượng đã chuyển tải theo từng heartbeat, và panel sẽ cộng dồn vào mức sử dụng của gói dịch vụ trong chu kỳ hiện tại. Con số này được hiển thị giống nhau cho khách hàng (các tab Overview và Bandwidth) cũng như cho bạn (VPN › Subscriptions, cột Used, và dòng của node). - **Ngắt kết nối.** Khi một gói dịch vụ đã dùng hết số GB trong chu kỳ, panel sẽ ngừng gửi các endpoint của gói đó tới agent, do đó các kết nối mới sẽ bị từ chối và các kết nối đang mở sẽ bị đóng. Việc ngắt diễn ra trong vòng một heartbeat, nên gói dịch vụ có thể vượt hạn mức một chút. Các gói có gói cước Unlimited sẽ không bao giờ bị ngắt. - **Mở lại dịch vụ.** Gói dịch vụ sẽ được phục vụ trở lại trong vòng một heartbeat sau khi khách hàng mua thêm băng thông hoặc khi chu kỳ tiếp theo bắt đầu. - **Not measured.** Node có agent chưa gửi dữ liệu sử dụng (ví dụ: agent phiên bản cũ) sẽ hiển thị là **Not measured**, và các gói của node đó không bao giờ bị ngắt vì lý do dung lượng GB. - **Cập nhật agent.** Sử dụng agent **1.5.1** trên các node. Các agent cũ hơn vẫn được tính lưu lượng, nhưng có thể làm mất số byte từ heartbeat bị lỗi, endpoint bị dừng hoặc khi khởi động lại, và chúng không đóng các kết nối đang mở khi gói dịch vụ bị ngắt. Cập nhật từ hàng của node (Reinstall) hoặc bằng lệnh `upgrade`. - Lưu lượng được tính theo payload truyền qua proxy, do đó sẽ thấp hơn một chút (khoảng 1 %) so với số byte thực tế trên đường truyền. ### Các add-on VPN đã ngừng hỗ trợ {#retired-vpn-add-ons} High IP Reputation, High Concurrency và High Priority Network không còn được cung cấp cho các đơn hàng mới. Các gói đăng ký hiện có vẫn giữ lại các add-on đã chọn, nhưng số tiền gia hạn sẽ được trừ đi khoản phí của các gói đã ngừng hỗ trợ. Không hoàn tiền cho các kỳ đã thanh toán. Việc điều chỉnh sử dụng giá niêm yết hiện tại của add-on; nếu bạn đã thay đổi mức giá đó hoặc xóa add-on, hãy kiểm tra lại số tiền gia hạn của gói đăng ký trước kỳ gia hạn tiếp theo. ## Kiểm tra {#verify} 1. Hàng của node hiển thị trạng thái online. Với VPN node, **Agents & external nodes** hiển thị zone, quốc gia, vai trò và các dải IP được phát hiện. 2. **VPN IP pools** liệt kê các dải IP còn trống; trang chi tiết của zone hiển thị hạ tầng VPN. 3. Đặt mua một gói VPN hoặc proxy thử nghiệm. Khách hàng sẽ nhận được endpoint `ip:port`, tên người dùng và mật khẩu; hãy kết nối qua đó và kiểm tra xem IP public hiển thị có phải là IP của node hay không (ví dụ `curl --proxy socks5h://USER:XXXX@IP:PORT https://ifconfig.me`). 4. Trên một node IPv6, chạy trên host: ```bash systemctl is-active nft list tables | grep proxy6 ss -ltn | grep -E ':(80|443|6[0-9]{4})\b' ``` ## Giới hạn và lưu ý {#limits-and-notes} - Các host Windows có thể chạy agent giám sát nhưng không thể chạy vai trò VPN. - Hạn mức dung lượng (GB mỗi chu kỳ) của gói VPN: từ NexCMP 1.5.1, panel sẽ cộng dồn lưu lượng do VPN node agent báo cáo và ngắt proxy của gói khi dùng hết số GB trong chu kỳ (xem "Data allowance on a VPN node" bên dưới). Các gói IPv6 Proxy không có hạn mức GB; chúng giới hạn tốc độ theo Mbps cho từng gói. - Địa chỉ IPv4 của gói VPN không tự động xoay. Khách hàng báo cáo IP bị đưa vào blacklist; bạn hoặc reseller duyệt cấp IP thay thế từ cùng zone. Chỉ IPv6 Proxy mới xoay. - Tối đa 64 dải IP được báo cáo trong mỗi heartbeat. - Một bộ endpoint VPN sử dụng ba cổng cho mỗi IP bán ra. Với các cổng 65001-65535, mỗi IP phục vụ một số lượng endpoint giới hạn (178 bộ cổng); panel sẽ bỏ qua các bộ cổng đã được sử dụng trước đó. - Chỉ được phép xóa node IPv6 proxy khi không còn gói dịch vụ nào giữ IP trên đó. Thao tác này sẽ xóa các dải IP và token của node; phần mềm trên host sẽ không bị gỡ cài đặt. - Bạn hoàn toàn có thể bán lại dải IP đang chạy các VM của chính mình: VPN chỉ sử dụng các cổng 65001-65535, vì vậy nó có thể chia sẻ IP với các dịch vụ khác. ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | "đăng ký thất bại (token không hợp lệ hoặc không thể kết nối máy chủ)" | Token sai hoặc đã qua sử dụng, hoặc không thể kết nối tới panel | Tạo token mới hoặc thử lại quá trình cài đặt qua SSH. | | "chữ ký tệp không khớp - STOP" | Agent đã tải xuống khác với mã SHA-256 được công bố | Kiểm tra thư mục `/dl/` của panel và đảm bảo không có gì ghi đè bản tải xuống trong quá trình truyền. | | "trình cài đặt này chỉ dành cho Linux" / "kiến trúc … hiện chưa được hỗ trợ" | Windows hoặc kiến trúc khác ngoài x86_64 (bản phát hành chỉ đi kèm agent cho x86_64) | Sử dụng host Linux x86_64. | | Node không bao giờ xuất hiện | Node không thể kết nối tới panel qua HTTPS | Kiểm tra `curl https:///install.sh` từ node; kiểm tra DNS và tường lửa. | | Node hiển thị sai quốc gia | Tra cứu quốc gia thất bại nên cơ sở dữ liệu địa chỉ của panel đã được sử dụng | Cho phép truy cập outbound tới `ip-api.com` và `ipinfo.io`, hoặc chọn zone rõ ràng trong biểu mẫu SSH. | | Không phát hiện thấy dải IP nào | Không có IPv4 public trên interface non-virtual | Thêm một địa chỉ public, hoặc nhập dải định tuyến dưới dạng **Extra subnet**. | | VPN hoạt động, lưu lượng ra từ một IP khác | IP bán ra chưa được gán hoặc định tuyến tới host | Đảm bảo IP nằm trên một interface hoặc được bao hàm bởi `local … dev lo`. | | "máy chủ panel không có sshpass" | Máy chủ panel không thể đăng nhập vào các node bằng mật khẩu | Chạy `sudo apt-get install -y sshpass openssh-client` trên máy chủ panel, sau đó cài đặt lại node. | | "not found in the installed package" khi cài đặt node IPv6 | Panel dùng phiên bản cũ hơn 1.4.2, hoặc bản build tùy chỉnh không có các file của node | Cập nhật NexCMP lên 1.4.2 hoặc mới hơn; với bản build tùy chỉnh, hãy dùng `build.sh`, lệnh này hiện đã đóng gói cả `brandy-proxy6d` và `brandy-proxy6-net`. | | "SSH: …" khi bắt đầu cài đặt IPv6, hoặc "SSH to internal/loopback addresses is not allowed" | Sai cổng, người dùng hoặc mật khẩu, SSH bị chặn, hoặc địa chỉ là private | Sử dụng IPv4 public của node và kiểm tra truy cập thủ công bằng `ssh -p PORT USER@IP`. | | "kiến trúc … không được hỗ trợ (chỉ x86_64)" | Node không phải là x86_64 | Sử dụng host x86_64. | | "node thiếu lệnh: …" | `nft`, `ip`, `ss`, `sysctl`, `systemctl` hoặc `useradd` chưa được cài đặt | Cài đặt các gói trên, sau đó chạy lại quá trình cài đặt. | | "cổng đang được dịch vụ khác sử dụng trên node: … — 80, 443, 60001-65535 phải còn trống" | Cổng 80, 443 hoặc cổng trên 60000 đang bận | Di chuyển dịch vụ khác sang cổng khác; trình cài đặt sẽ không tự dừng dịch vụ đó. | | "không tìm thấy tiền tố IPv6 có kết nối Internet từ node (kiểm tra egress thực tế thất bại)" | Không có prefix được định tuyến, không thể NDP proxy, hoặc không có IPv6 outbound | Kiểm tra xem prefix đã được định tuyến tới node chưa, interface có kết nối IPv6 không và không có gì chặn lưu lượng outbound. | | "tất cả các dải được phát hiện đã thuộc về một node khác" | Prefix đã được sử dụng bởi một node khác | Xóa prefix khỏi node kia hoặc chọn một prefix khác. | | Quá trình cài đặt kết thúc với "no initial report received from node" | Service đã khởi động nhưng không kết nối được tới panel trong vòng 90 giây | Kiểm tra URL của panel được cấp cho các node và đường truyền HTTPS từ node tới đó; xem **Install log**. | | Hàng của node hiển thị **missed heartbeat** | Không có báo cáo trong 120 giây | Kiểm tra service trên node, đồng hồ hệ thống và đường truyền tới panel. | | Khách hàng không thấy vị trí IPv6 nào | Zone đang tắt | Bật zone trong mục **Zone**. | --- # AI Models {#ai-models} > **Vị trí trong trang admin:** System › Admin › License & updates (`/license`) để bật module. Sau đó là Services › AI Models: Providers (`/ai/providers`), Models (`/ai/models`), Profit (`/ai/profit`) và Audit (`/ai/audit`). Khách hàng sử dụng AI › API trong portal khách hàng. ## Chức năng {#what-it-does} AI Models là một tầng gateway và thanh toán ngay trên panel của bạn. Khách hàng nhận API key và gọi tới **một endpoint duy nhất trên tên miền của bạn**, theo định dạng tương thích OpenAI hoặc Anthropic. Bạn chọn những model sẽ cung cấp và chi phí cho mỗi 1 triệu token. NexCMP kiểm tra key, hạn mức và số dư ví, gửi yêu cầu tới provider bạn đã thêm, đo lường lượng token và trừ tiền vào ví trả trước của khách hàng. **Bạn tự cung cấp các nguồn model.** NexCMP khi cài đặt không có sẵn provider, model, địa chỉ mặc định hay giá bán nào. Hệ thống không cung cấp model, API key, token hay tài khoản provider. ::: warning Kiểm tra điều khoản của nguồn model trước Nhiều nguồn model hạn chế việc bán lại hoặc chuyển tiếp quyền truy cập cho bên thứ ba. Chỉ sử dụng các nguồn mà bạn được phép dùng và bán lại, đồng thời tuân thủ các điều khoản của họ và quy định pháp luật hiện hành. Trang này không phải là lời khuyên pháp lý. ::: AI Models là một sản phẩm độc lập với **AI Chat and AI Agent** (module **AI**, xem [AI providers](https://nexcmp.com/vi/docs/ai/ai-providers/)). Hai module này không phụ thuộc vào nhau. ## Yêu cầu {#requirements} | Hạng mục | Yêu cầu | |---|---| | Module | **AI Models** được bật trong License & updates, Modules. Mặc định tính năng này tắt. | | Providers | Một hoặc nhiều nguồn model bạn được phép bán lại, mỗi nguồn có API tương thích OpenAI (`/chat/completions`), API tương thích Anthropic (`/messages`), hoặc cả hai. Mỗi nguồn cần một base URL và một API key. | | Mạng | Panel phải kết nối được tới từng provider qua **HTTPS trên cổng 443** bằng tên miền công khai. Provider chạy trên host nội bộ, cổng khác hoặc HTTP thông thường phải được liệt kê trong **Allowed internal hosts** (cài đặt `ai_endpoint_allow`). | | Khách hàng | Tài khoản khách hàng có địa chỉ email đã xác thực và số dư trong ví. | | Phần cứng | Không. NexCMP chỉ chuyển tiếp yêu cầu: không cần GPU và không lưu file model. | ## Chuẩn bị hạ tầng {#prepare-the-infrastructure} 1. Lấy API key từ từng nguồn model bạn sẽ sử dụng và ghi lại base URL của nguồn đó (ví dụ `https://api.example.com/v1`). 2. Kiểm tra điều khoản bán lại của nguồn model. 3. Nếu nguồn model chạy trong mạng nội bộ của bạn, hãy xác định địa chỉ của nguồn, ví dụ `http://10.0.0.5:8000/v1`. Bạn sẽ liệt kê `10.0.0.5:8000` trong mục **Allowed internal hosts**. ## Kết nối trong NexCMP {#connect-in-nexcmp} ### Bước 1: Bật module {#_1-turn-the-module-on} Mở **System › Admin › License & updates**, tìm thẻ **Module** và bật **AI Models**. Menu sẽ tải lại và **Services › AI Models** xuất hiện. Khi module tắt, các trang khách hàng, trang admin và gateway đều phản hồi `404 module_disabled`, và không có provider nào được liên hệ. ![Thẻ Module khi công tắc AI Models đang bật](https://nexcmp.com/vi/docs/images/infrastructure/ai-models-01-modules.webp) ### 2. Thêm provider {#_2-add-a-provider} 1. Mở **AI Models › Providers** và chọn **Add provider**. 2. Nhập một **slug** ngắn, **name** (chỉ bạn nhìn thấy), **type** (OpenAI-compatible, Anthropic-compatible hoặc Both), **base URL** cùng **API key**, và **priority** (số nhỏ hơn sẽ được ưu tiên thử trước). 3. Lưu lại. Key được lưu trữ dưới dạng mã hóa và sau đó chỉ hiển thị bốn ký tự cuối. Chỉ có thể nhập key từ phiên quản trị viên đã đăng nhập. Chỉ dùng **Both** cho gateway thực sự hỗ trợ cả hai định dạng. NexCMP **không** chuyển đổi qua lại giữa hai định dạng: model được cung cấp bởi provider tương thích OpenAI được truy cập tại `/ai/v1/chat/completions`, và provider tương thích Anthropic tại `/ai/v1/messages`. ![Trang Providers liệt kê ba provider mẫu kèm type, priority và status](https://nexcmp.com/vi/docs/images/infrastructure/ai-models-02-providers.webp) ### 3. Kiểm tra kết nối {#_3-test-the-connection} Chọn **Test connection** trên provider. NexCMP sẽ đọc `GET /models` cùng với key và báo **ok**, hoặc lý do thất bại: **auth** (sai key), **blocked**, **billing**, hoặc **unreachable**. Giới hạn tối đa 6 lần kiểm tra mỗi phút. ### 4. Đồng bộ hóa model {#_4-sync-the-models} Chọn **Sync models**. NexCMP sẽ đọc danh sách model của provider và thêm từng model mới ở trạng thái **tắt và chưa có giá**. Model không còn xuất hiện trong danh sách của provider sẽ bị gắn cờ cảnh báo. Khi module đang bật, danh sách cũng được tự động đồng bộ mỗi 6 giờ một lần (cài đặt `ai_models_sync_hours`). ### 5. Thiết lập giá và bật model {#_5-set-prices-and-switch-models-on} 1. Mở **AI Models › Models**. 2. Với mỗi model muốn bán, hãy đặt **selling price** theo đô la Mỹ cho mỗi 1 triệu token: **input**, **cached input** và **output**. 3. Bạn có thể tùy chọn nhập **cost** của model. Sau đó **Profit** sẽ hiển thị doanh thu so với chi phí theo ngày và theo model; giá bán thấp hơn chi phí cộng với biên lợi nhuận tối thiểu (cài đặt `ai_min_margin_pct`, mặc định 10) sẽ bị từ chối trừ khi bạn xác nhận chấp nhận bán lỗ có chủ đích. **Set price from cost** sử dụng mức markup do bạn chọn; không có markup mặc định. 4. Bật model lên. Model chưa có giá bán thì không thể bật. Giá cached input nếu để bằng 0 sẽ được tính theo giá input thông thường. ![Trang Models với giá bán input, cached input, output và các công tắc bật tắt](https://nexcmp.com/vi/docs/images/infrastructure/ai-models-03-models.webp) ### 6. Định tuyến và chuyển vùng dự phòng (failover) {#_6-routes-and-failover} Trên từng model, **Routes** liệt kê các provider cung cấp model đó theo thứ tự. Thêm provider thứ hai làm dự phòng, sắp xếp thứ tự và có thể tùy ý đặt tên model khác nhau cho từng provider (tên gửi tới provider có thể khác với tên bạn hiển thị công khai). Khi một provider trả về lỗi server, lỗi xác thực/thanh toán, thiếu model hoặc bị rate limit, NexCMP sẽ tự động thử route tiếp theo. Nếu yêu cầu đọc bị timeout sau khi request đã được gửi đi, nó sẽ **không** được gửi sang provider khác để tránh bạn bị tính phí hai lần. Mỗi provider được điều tiết ở mức `ai_provider_rpm` request mỗi phút (mặc định 50). Nếu provider liên tục trả về lỗi xác thực hoặc thanh toán, NexCMP sẽ cảnh báo quản trị viên qua Telegram khi Telegram đã được thiết lập. ### 7. Bật công tắc mở bán {#_7-open-the-sale-switch} Ở đầu các trang AI Models, **công tắc mở bán** (cài đặt `feature_ai_models`) mặc định tắt. Khi tắt, khách hàng sẽ thấy dịch vụ chưa mở và bảng giá công khai sẽ báo trạng thái không khả dụng. Hãy kiểm tra để chắc chắn có ít nhất một model đã bật, có giá bán và có route kèm key hợp lệ, sau đó bật công tắc lên. ### Khách hàng có thể làm gì {#what-customers-can-do} Trong portal khách hàng, tại **AI › API**: - **Models** hiển thị các model và giá bán của bạn, base URL cùng các câu lệnh mẫu dùng ngay. - **API Keys**: tạo, đổi tên, xoay vòng (rotate), vô hiệu hóa và xóa key. Secret key chỉ hiển thị một lần duy nhất; hệ thống chỉ lưu chuỗi băm (hash). Trên từng key: cho phép chọn model, hạn dùng, hạn mức mềm (cảnh báo) và hạn mức cứng (chặn với `402`), giới hạn request mỗi phút và token mỗi phút. - **Usage** theo model, key và ngày, hỗ trợ xuất dữ liệu. - **Logs**: lịch sử request có thể lọc (thời gian, key, model, token, chi phí, status, độ trễ). **Prompt và phản hồi hoàn toàn không được ghi lại.** Mặc định log được lưu giữ trong 90 ngày (`ai_log_retention_days`). - **Settings**: ngân sách tài khoản và địa chỉ email nhận cảnh báo ngân sách. - **Playground**: trò chuyện với model, so sánh các model song song và sao chép mã tương ứng. ![Trang API Keys của khách hàng với các base URL cho cả hai định dạng API](https://nexcmp.com/vi/docs/images/infrastructure/ai-models-04-keys.webp) Các endpoint gateway, trên domain của bạn: ```text POST /ai/v1/chat/completions OpenAI-compatible POST /ai/v1/messages Anthropic-compatible (also /ai/v1/messages/count_tokens) GET /ai/v1/models model list GET /ai/v1/models/pricing public price list, no key needed ``` ### Ví và thanh toán {#wallet-and-billing} Mức sử dụng AI được trừ vào cùng một ví trả trước như mọi dịch vụ khác. Trước khi request được gửi đến provider, NexCMP sẽ giữ trước số tiền tối đa mà request có thể tiêu tốn; nếu số dư dưới mức tối thiểu (`ai_min_balance_cents`, mặc định 20 cent) hoặc quá ít, request sẽ bị từ chối với `402 insufficient_balance` và **không có provider nào được gọi**. Mức sử dụng được tổng hợp theo từng tài khoản và kết toán vào sổ cái ví sau mỗi giờ, với chu kỳ quét mỗi 5 phút; mức sử dụng chưa kết toán đã được trừ trước vào số dư mà gateway ghi nhận. Reseller có thể bán AI Models trên domain riêng của họ: mức tăng giá hoặc chiết khấu của họ áp dụng trên giá bán của bạn và ví bán buôn của họ bị trừ theo giá bán buôn. Nút bật/tắt AI riêng cho từng reseller, mặc định bật, dùng để kiểm soát reseller nào được phép bán. ## Kiểm tra {#verify} 1. Sau bước 3, **Test connection** sẽ hiển thị **ok** và số lượng model. 2. Sau bước 4, các model mới được liệt kê, ở trạng thái tắt, chưa có giá. 3. Với tư cách khách hàng có tiền trong ví, hãy tạo một key và gọi đến gateway: ```bash curl https://your-domain/ai/v1/chat/completions \ -H "Authorization: Bearer sk-ai-…" -H "Content-Type: application/json" \ -d '{"model":"model-one","messages":[{"role":"user","content":"hello"}]}' ``` Phản hồi `200` sẽ chứa câu trả lời của model. **Usage** hiển thị request, và **Profit** sẽ hiển thị request đó nếu bạn đã nhập chi phí. 4. Khi số dư ví bằng 0, lệnh gọi tương tự sẽ trả về `402 insufficient_balance`. ## Giới hạn và lưu ý {#limits-and-notes} - Module này không tích hợp sẵn provider, model hay giá, và không bao giờ tự động đọc bảng giá từ provider. - Các tool chạy phía provider và tính phí theo lượt gọi, chẳng hạn như tìm kiếm web, sẽ bị từ chối vì không thể đo lường mức sử dụng. Chỉ có một danh sách ngắn các tham số request được chuyển tiếp. - Mức sử dụng token được lấy từ phản hồi của provider; nếu phản hồi không có, NexCMP sẽ ước tính và đánh dấu bản ghi là ước tính. - Lỗi từ provider được làm sạch trước khi gửi tới khách hàng (tên, host, địa chỉ và tên model của provider đều được gỡ bỏ). Khách hàng không bao giờ thấy provider nào đã xử lý request. - Khách hàng truy cập gateway thông qua domain của panel, vì vậy TLS của domain đó phải hoạt động bình thường. - NexCMP không cung cấp thỏa thuận mức dịch vụ (SLA), fine-tuning hay GPU hosting cho module này. ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân và cách xử lý | |---|---| | Mọi trang AI Models và gateway đều phản hồi `404 module_disabled` | Module đang tắt. Hãy bật **AI Models** trong License & updates, Modules. | | Thêm provider thất bại với lỗi `endpoint_host_not_allowed`, `endpoint_must_be_https` hoặc `invalid_endpoint_port` | Base URL phải là HTTPS trên cổng 443 tại một domain name công khai. Đối với host nội bộ, cổng khác hoặc HTTP thông thường, hãy thêm `host:port` vào **Allowed internal hosts**. | | `blocked_endpoint` | Địa chỉ là một IP, hoặc tên miền phân giải về một địa chỉ riêng tư. Hãy thêm địa chỉ đó vào **Allowed internal hosts** nếu bạn muốn như vậy. | | **Test connection** báo `auth` | Key không chính xác hoặc không có quyền truy cập. Hãy nhập lại key. | | Không thể bật model (`no_price`) | Hãy đặt giá bán trước. | | Khách hàng nhận được `503 ai_unavailable` | Nút bán đang tắt, hoặc nút AI của reseller đang tắt. | | Khách hàng nhận được `503 upstream_unavailable` | Không có route nào đang bật kèm key để phục vụ model đó ở định dạng được yêu cầu. Hãy kiểm tra các route của model và loại provider. | | Khách hàng nhận được `402 insufficient_balance` | Số dư ví dưới mức tối thiểu hoặc không đủ cho request. Hãy yêu cầu khách hàng nạp tiền. | --- # Object Storage (S3, Ceph RGW) {#object-storage-s3-ceph-rgw} > **Vị trí trong admin:** Infrastructure › Cloud provider › Ceph S3 (RGW) (`/infra/s3`). Tài khoản: Services › Object Storage › S3 accounts (`/s3`). Bảng giá: Services › Object Storage › PAYG pricing (`/s3/policy`). Bật module trong System › Admin › License & updates. ## Chức năng {#what-it-does} Khách hàng tạo tài khoản S3 từ portal và nhận access key. NexCMP tạo và xóa user tương ứng trên **Ceph RADOS Gateway (RGW) của bạn** thông qua RGW Admin Ops API, đọc mức sử dụng để tính cước và thanh toán theo hình thức pay-as-you-go: dung lượng lưu trữ vượt mức miễn phí theo mỗi GB/tháng (tính theo giờ) và lưu lượng tải xuống theo mỗi GB. Chiều tải lên hoàn toàn miễn phí. Sử dụng tính năng này khi bạn vận hành một cụm Ceph kèm RGW và muốn kinh doanh Object Storage. ## Yêu cầu {#requirements} | Hạng mục | Yêu cầu | |---|---| | Ceph | Cụm Ceph có ít nhất một daemon RGW và đã bật **Admin Ops API** (mặc định `rgw_enable_apis` bao gồm `admin`). | | Admin user | Một RGW user dành riêng cho NexCMP với các capability liệt kê bên dưới. Không dùng user đang chứa dữ liệu của khách hàng. | | Endpoint | S3 endpoint mà khách hàng sử dụng và Admin Ops endpoint. Cả hai đều được viết dưới dạng `https://host` **không có path, chỉ dùng port 443**, và phải phân giải về địa chỉ **public**: các địa chỉ loopback, link-local, multicast, private và unique-local sẽ bị từ chối. | | Chứng chỉ | Chứng chỉ hợp lệ cho host của endpoint. | | Usage log | Bật RGW usage logging (`rgw_enable_usage_log = true`) để usage API có thể báo cáo lưu lượng. | | Zone | Một master zone đã tích chọn service **Object Storage (S3)**. Xem [Zones](https://nexcmp.com/vi/docs/infrastructure/zones/). | | Storage | Dung lượng khả dụng trong Ceph đáp ứng các quota bạn bán. | | Phụ thuộc vào | Module **Object Storage**. Lưu lượng tải xuống cũng được tính vào [Bandwidth](https://nexcmp.com/vi/docs/catalog/bandwidth/). | ## Chuẩn bị hạ tầng {#prepare-the-infrastructure} Trên một Ceph admin node: 1. Tạo admin user và cấp các quyền hạn (capability) Admin Ops cần thiết: ```bash radosgw-admin user create --uid=nexcmp-admin --display-name="NexCMP admin" radosgw-admin caps add --uid=nexcmp-admin --caps="users=*;buckets=*;usage=read;metadata=read" radosgw-admin user info --uid=nexcmp-admin ``` Sao chép `access_key` và `secret_key` từ kết quả trả về. Đó chính là **Admin access key** và **Admin secret key** trong NexCMP. 2. Bật usage log và khởi động lại các gateway: ```bash ceph config set client.rgw rgw_enable_usage_log true ``` 3. Đặt các gateway phía sau HTTPS trên port 443 (dùng reverse proxy hoặc TLS tích hợp của RGW), cấu hình DNS và kiểm tra từ panel server: ```bash curl -fsS -o /dev/null -w '%{http_code}\n' https://s3.example.com/ ``` Bạn sẽ nhận được phản hồi XML từ S3 (HTTP 200 hoặc 403), không phải lỗi timeout. ## Kết nối trong NexCMP {#connect-in-nexcmp} 1. **Gán dịch vụ S3 cho một zone.** Mở **Infrastructure › Datacenter › Zone**, chỉnh sửa zone và tích chọn **Object Storage (S3)**. Chỉ các master zone có dịch vụ S3 mới xuất hiện trong biểu mẫu backend. 2. Mở **Infrastructure › Cloud provider › Ceph S3 (RGW)** và nhấp vào **Add backend**: | Trường | Giá trị ví dụ | |---|---| | Tên backend | `Ceph RGW 1` | | Zone | zone từ bước 1 | | Endpoint RGW Admin Ops | `https://s3.example.com` | | Endpoint S3 khách hàng | `https://s3.example.com` | | Region ký S3 | `default` | | Admin access key | `XXXX` | | Admin secret key | `XXXX` | | Kích hoạt | bật | | Enable sales (cần kiểm tra kết nối trước) | tạm thời **tắt** | | Lý do thay đổi | `initial setup` | ![Hộp thoại backend S3 với các endpoint mẫu, region và key đã được ẩn](https://nexcmp.com/vi/docs/images/infrastructure/s3-02-backend-dialog.webp) 3. Nhấp vào **OK** (lưu), sau đó nhấp **Check** ở hàng tương ứng. NexCMP sẽ gọi Admin Ops API bằng admin key. Thông báo **Ceph connection successful** và thẻ **Verified** cho biết kết nối thành công. 4. Nhấp vào **Edit**, chuyển **Enable sales** sang bật và lưu lại. NexCMP sẽ từ chối mở bán cho đến khi việc kiểm tra thành công. 5. Mở **Services › Object Storage › PAYG pricing** và thiết lập giá: | Trường | Ý nghĩa | |---|---| | Lưu trữ vượt mức miễn phí (VND/GB/tháng) | Giá lưu trữ; được tính theo giờ bằng giá tháng chia cho 730. | | Tải xuống (VND/GB) | Giá cho lưu lượng chiều ra. | | Tải lên (VND/GB) | Luôn bằng 0. | | Hạn mức miễn phí khi có Running VM (GB) | Cố định ở mức 100 GB cho mỗi tài khoản khi khách hàng có ít nhất một VM đang chạy, được chia sẻ giữa các tài khoản S3 của họ theo dung lượng. | | Hạn mức ghi nợ (VND) | Mức sử dụng chưa thanh toán tối đa được cho phép. | | Ngưỡng lập hóa đơn (VND) | Lượng sử dụng sẽ được gom vào một hóa đơn khi vượt qua số tiền này. | | Số dư tối thiểu để tạo S3 (VND) | Số dư ví cần để tạo tài khoản. | | Số tài khoản S3 tối đa cho mỗi khách hàng, Hạn ngạch kỹ thuật mặc định (GB) | Giới hạn áp dụng cho các tài khoản mới. | ![Biểu mẫu giá S3 PAYG](https://nexcmp.com/vi/docs/images/infrastructure/s3-04-pricing.webp) Giá S3 được nhập bằng VND. Các mức giá này được quy đổi để hiển thị và trừ tiền trong ví theo tỷ giá hiện hành; xem [Tiền tệ và tỷ giá hối đoái](https://nexcmp.com/vi/docs/catalog/currency-and-exchange-rates/). ## Kiểm tra {#verify} 1. **Check** hiển thị "Ceph connection successful". 2. Với tư cách là khách hàng (hoặc dùng tài khoản thử nghiệm), hãy tạo một tài khoản S3. Trên Ceph, `radosgw-admin user list` sẽ hiển thị user mới, và **S3 accounts** sẽ liệt kê tài khoản đó. 3. Tạo một bucket bằng bất kỳ S3 client nào bằng key của khách hàng tới customer endpoint. Tải lên một tệp. 4. Sau chu kỳ tính cước theo giờ tiếp theo, **S3 accounts** sẽ hiển thị mức sử dụng. ## Giới hạn và lưu ý {#limits-and-notes} - Backend đã gắn liền với các tài khoản sẽ giữ nguyên **zone, endpoint và region**; để thay đổi chúng, hãy tạo một backend mới. - Mỗi zone có thể có backend riêng; các tài khoản và backend sẽ được liên kết cố định với một zone. - Hạn mức miễn phí và quy định "tải lên là miễn phí" là các quy tắc cố định, không phải tùy chọn. - Các key được lưu trữ dưới dạng mã hóa; console chỉ hiển thị trường "leave blank to keep the current key". Cặp key luôn phải được nhập cùng nhau. - Secret key của khách hàng chỉ hiển thị một lần duy nhất khi tạo và không bao giờ xuất hiện lại. Nếu mất key, bạn chỉ có thể thay thế bằng cách rotate key. ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | "Endpoint requires HTTPS" | Endpoint đang dùng HTTP thông thường | Xuất bản HTTPS trên cổng 443. | | "Cổng endpoint không được phép" | Cổng khác 443 | Sử dụng cổng HTTPS tiêu chuẩn. | | "Địa chỉ endpoint không được phép" | Tên miền phân giải ra địa chỉ private, loopback, link-local hoặc unique-local | Sử dụng địa chỉ public. | | "Endpoint chỉ được chứa giao thức và host" | URL có chứa path, query hoặc thông tin người dùng | Chỉ sử dụng `https://host`. | | "Không thể phân giải endpoint" | Máy chủ panel không thể phân giải DNS | Sửa lại cấu hình DNS. | | "Failed to connect to Ceph" | Lỗi tường lửa hoặc lỗi TLS | Kiểm tra bằng `curl` từ máy chủ panel. | | "Ceph returned HTTP 403 AccessDenied" | Sai key hoặc thiếu quyền hạn (capabilities) | Kiểm tra lại các key và chạy lại `radosgw-admin caps add`. | | "Invalid Ceph response" | Endpoint không phải là RGW Admin Ops API | Trỏ endpoint về RGW, không trỏ về trang web. | | "Kiểm tra kết nối phải thành công trước khi bật bán hàng" | Bạn đã bật bán hàng trước khi chạy **Check** thành công | Chạy **Check**, sau đó mới kích hoạt bán hàng. | | "Bắt buộc có đầy đủ các key mới cho endpoint" | Đã đổi endpoint nhưng không cung cấp đủ cả hai key | Nhập đồng thời cả access key và secret key. | | "Backend đã có tài nguyên liên kết; hãy tạo backend mới để đổi zone hoặc endpoint" | Đã có tài khoản tồn tại trên backend này | Tạo một backend mới. | | "Chọn master zone có dịch vụ S3" | Zone này không phải là master zone hoặc chưa bật dịch vụ S3 | Tích chọn **Object Storage (S3)** trên zone. | | "Invalid region" | Region chứa các ký tự khác ngoài chữ cái, chữ số, `-` và `_` | Sử dụng `default` hoặc tên zonegroup RGW của bạn. | | "Thiếu tóm tắt mức sử dụng Ceph; không tính phí" | Usage log đang bị tắt | Bật `rgw_enable_usage_log`. | --- # Kubernetes và Private Cloud {#kubernetes-and-private-cloud} > **Vị trí trong admin:** Kubernetes: Infrastructure › Cloud provider › CloudStack › Kubernetes (CKS) (`/infra/cloudstack?tab=k8s`), sau đó là Services › Kubernetes (Overview, Clusters, Versions, Policy). Private Cloud: Services › Private Cloud (Overview `/vpc`, VPC `/vpc/list`, Plans & pricing `/vpc/plans`). Bật cả hai module tại System › Admin › License & updates. ## Chức năng {#what-it-does} - **Kubernetes.** Khách hàng tạo các cụm Kubernetes được quản lý trên CloudStack của bạn bằng CloudStack Kubernetes Service (CKS). Control plane hoàn toàn miễn phí; khách hàng chỉ trả phí cho các node **worker**. NexCMP tạo một network và IP public riêng cho từng cụm, đồng thời tách biệt các cụm của từng khách hàng. - **Private Cloud.** Khách hàng nhận được một mạng riêng (CloudStack VPC) gồm router, subnet (tier), quy tắc tường lửa (network ACL) và các máy ảo bên trong. Dịch vụ được bán theo **gói băng thông** với tốc độ dành riêng, không giới hạn dung lượng (ví dụ: 50, 100, 500 Mbps, 1 và 3 Gbps). Theo mặc định, mỗi khách hàng có thể sở hữu một VPC. Cả hai đều được xây dựng trên [CloudStack](https://nexcmp.com/vi/docs/infrastructure/cloudstack/) và sử dụng API thông qua cùng một kết nối. ## Yêu cầu {#requirements} ### Kubernetes {#kubernetes} | Hạng mục | Yêu cầu | |---|---| | CloudStack | 4.23 (đã kiểm thử). CKS phải được **bật** (`cloud.kubernetes.service.enabled = true`). | | Tài khoản | Tài khoản **Domain Admin** trong domain chuyên dụng, giúp NexCMP có thể tạo CloudStack project cho từng khách hàng và áp dụng giới hạn tài nguyên bên trong đó. Xem [CloudStack](https://nexcmp.com/vi/docs/infrastructure/cloudstack/#create-a-dedicated-account-and-api-key). | | `endpoint.url` | Cài đặt global của CloudStack phải trỏ đến management API của bạn, có thể truy cập được từ các VM trong cụm. NexCMP hiển thị giá trị này cùng kết quả kiểm tra endpoint. | | Phiên bản | Tối thiểu một mục Kubernetes supported-version kèm ISO binary ở trạng thái **Enabled**. Không thể mở bán các phiên bản đã hết vòng đời hỗ trợ. | | Control-plane offering | Một service offering miễn phí với **chính xác 2 vCPU, 2048 MB RAM và giới hạn CPU** (`limitcpuuse = true`), hiển thị cho tài khoản. Server sẽ từ chối mọi cấu hình khác kèm `cp_offering_invalid`. | | Mạng | Một isolated network offering hỗ trợ CKS đang ở trạng thái kích hoạt. | | IP | Địa chỉ IPv4 public còn trống trong dải có thể bán; mỗi cụm sử dụng một địa chỉ. | | Dung lượng | Mỗi cụm tiêu tốn của bạn từ 2 đến 4 GB RAM cho control plane và một VM router nhỏ. Hãy chú ý theo dõi các tab capacity. | ### Private Cloud {#private-cloud} | Hạng mục | Yêu cầu | |---|---| | CloudStack | 4.23 (đã kiểm thử) và đã bật VPC. | | VPC offering | Một VPC offering. Offering dual-stack cũng sẽ cấp cho mỗi tier một dải IPv6 /64. | | Tier network offerings | **Một network offering cho mỗi gói băng thông**, được tạo cho VPC, với **network rate** (Mbps) tương ứng với gói, kèm theo một offering **bị khóa** ở mức **1 Mbps** được áp dụng khi VPC bị khóa do chưa thanh toán. | | Tài khoản | Tài khoản chuyên dụng (khuyến nghị dùng Domain Admin). Mạng VPC nằm trong tài khoản, không nằm trong project. | | IP | Địa chỉ IPv4 public còn trống (mỗi VPC sử dụng một địa chỉ cho source NAT). | | Không gian địa chỉ | Mỗi VPC nhận một dải /16 từ `10.128.0.0/9`. Đảm bảo dải này không bị trùng lặp trên mạng nội bộ của bạn. | | Phụ thuộc vào | CloudStack đã kết nối; module **Private Cloud**. | ## Chuẩn bị hạ tầng {#prepare-the-infrastructure} ### Kubernetes: kích hoạt CKS và thêm phiên bản {#kubernetes-enable-cks-and-add-versions} 1. Kích hoạt dịch vụ và cấu hình endpoint, sau đó khởi động lại management server: ```bash cmk update configuration name=cloud.kubernetes.service.enabled value=true cmk update configuration name=endpoint.url value=https://cloudstack.example.com/client/api sudo systemctl restart cloudstack-management ``` `endpoint.url` được controller của cụm gọi lại, vì vậy đây phải là địa chỉ mà các VM trong cụm có thể kết nối tới. 2. Build file ISO binary của Kubernetes cho phiên bản bạn muốn bán bằng script `create-kubernetes-binaries-iso.sh` từ mã nguồn CloudStack, lưu trữ trên một web server và đăng ký file ISO này: ```bash cmk add kubernetessupportedversion name="Kubernetes 1.35.0" semanticversion=1.35.0 \ url=https://files.example.com/setup-v1.35.0-calico-amd64.iso zoneid= \ mincpunumber=2 minmemory=2048 cmk list kubernetessupportedversions filter=name,semanticversion,state,isostate ``` Chờ cho trạng thái ISO chuyển sang **Ready** và phiên bản ở trạng thái **Enabled**. 3. Tạo control-plane offering, giới hạn trong domain của NexCMP: ```bash cmk create serviceoffering name=K8S-CP-2-2 displaytext="Kubernetes control plane" \ cpunumber=2 cpuspeed=1000 memory=2048 limitcpuuse=true offerha=false domainid= ``` 4. Kiểm tra xem CKS network offering đã được bật chưa: ```bash cmk list networkofferings state=Enabled forvpc=false filter=id,name ``` ### Private Cloud: tạo các offering {#private-cloud-create-the-offerings} Trong CloudStack UI (**Service Offerings › Network Offerings › Add network offering**) hoặc bằng `cmk`: 1. Liệt kê những gì bạn hiện có: ```bash cmk list vpcofferings filter=id,name,state cmk list networkofferings forvpc=true filter=id,name,networkrate,state ``` 2. Sử dụng một VPC offering đang được bật (dual-stack nếu bạn muốn IPv6). Nếu cần tạo mới, hãy nhân bản VPC offering mặc định của CloudStack rồi bật nó lên. 3. Đối với **mỗi** gói băng thông bạn bán, hãy tạo một network offering **cho VPC** (nhân bản "isolated network offering for VPC networks" mặc định) và đặt **Network rate (Mb/s)** theo tốc độ của gói: `50`, `100`, `500`, `1000`, `3000`. Bật từng offering. 4. Tạo thêm một offering với **network rate 1** (`VPC-LOCKED-1M`) dành cho các VPC bị khóa: khách hàng vẫn có thể truy cập server qua SSH, nhưng tốc độ sẽ bị giới hạn. 5. Lưu lại UUID của từng offering. NexCMP sẽ cần chúng trong phần tiếp theo. ::: warning Các offering ID mặc định không tồn tại trong cloud của bạn Biểu mẫu Private Cloud được điền sẵn các UUID offering thuộc về một bản cài đặt CloudStack khác. Hãy thay thế **từng** UUID bằng thông tin của bạn, nếu không đơn hàng VPC đầu tiên sẽ thất bại. ::: ## Kết nối trong NexCMP {#connect-in-nexcmp} ### Kubernetes {#kubernetes-1} 1. Mở **Infrastructure › Cloud provider › CloudStack** và chọn tab **Kubernetes (CKS)**. Thẻ bên phải **CKS status on CloudStack (read-only)** hiển thị `kubernetesserviceenabled`, `endpoint.url` với **Endpoint check**, CKS network offering, các cài đặt `cloud.kubernetes.*` cùng danh sách ISO và phiên bản. Nhấp vào **Recheck** sau khi bạn sửa đổi gì đó. 2. Tại **Sales config**, chọn **Control plane Offering** (cảnh báo sẽ xuất hiện nếu thông số không chính xác là 2 vCPU / 2048 MB / CPU cap), đặt **Max workers per cluster** (từ 1 đến 9: CKS cho phép 10 node tính cả control node), bật **Enable CKS for this backend** và nhấn **Save**. Công tắc sẽ bị vô hiệu hóa cho đến khi một offering được chọn. ![Tab Kubernetes (CKS) với control plane offering đã chọn và thẻ trạng thái CKS](https://nexcmp.com/vi/docs/images/infrastructure/kubernetes-and-private-cloud-01-cks.webp) 3. Mở **Services › Kubernetes › Versions** và nhấp vào **Sync from CloudStack**. Bật **Available for new clusters** cho các phiên bản bạn bán, đặt phiên bản mặc định và ngày **End of life (EOL)** nếu muốn. 4. Mở **Services › Kubernetes › Policy**. Trong **Worker plans**, thêm các gói với một **Plan code** (A-Z, 0-9, dấu gạch nối, tối đa 16 ký tự). Đặt **NVMe per worker (GB)**, **Min and max workers** và các giới hạn cluster (số cluster đang hoạt động trên mỗi tài khoản, số lượt tạo mỗi 24 giờ, giới hạn toàn cục, các tác vụ CKS đồng thời). Sau đó bật **Sell Kubernetes (CKS)**. Ít nhất một gói phải luôn được mở bán. ![Kubernetes policy với các worker plan và công tắc mở bán](https://nexcmp.com/vi/docs/images/infrastructure/kubernetes-and-private-cloud-03-policy.webp) ### Private Cloud {#private-cloud-1} 1. Mở **Services › Private Cloud** (Overview). Trong thẻ policy, hãy thay thế **VPC offering** và **Locked offering tier** bằng UUID của chính bạn. Kiểm tra các giới hạn (số VPC trên mỗi tài khoản, số tier, VM và quy tắc ACL trên mỗi VPC, số dư tính theo số giờ phí gói cần có để tạo, số lần đổi gói mỗi 24 giờ, các tác vụ đồng thời với 0 là dừng khẩn cấp) cùng các DNS server. Nhấp vào **Save** (sẽ có yêu cầu nhập lý do). ![Tổng quan Private Cloud với các trường VPC offering và locked offering](https://nexcmp.com/vi/docs/images/infrastructure/kubernetes-and-private-cloud-04-vpc-policy.webp) 2. Mở **Services › Private Cloud › Plans & pricing**. Với mỗi gói, nhấp vào **Edit** rồi thiết lập **VND price per month**, **On sale** cùng UUID **CloudStack tier offering** có network rate tương ứng với Mbps của gói. Hàng này hiển thị chi phí và lợi nhuận khi sử dụng hết công suất, giúp bạn thấy được gói nào đang dưới giá vốn. ![Hộp thoại Edit plan cho gói băng thông Private Cloud](https://nexcmp.com/vi/docs/images/infrastructure/kubernetes-and-private-cloud-05-vpc-plan.webp) 3. Bật **Sell Private Cloud**. Để dùng thử trước, hãy thêm ID tài khoản test vào **Beta accounts**: các tài khoản này có thể sử dụng dịch vụ ngay cả khi công tắc mở bán đang tắt. ## Kiểm tra {#verify} 1. Kubernetes: thẻ trạng thái hiển thị `kubernetesserviceenabled: true`, kết quả endpoint check tốt và phiên bản đã bật. Hãy tạo thử một cluster một worker dưới tư cách khách hàng; cluster này sẽ chuyển sang trạng thái running và `kubectl get nodes` sẽ hiển thị ready. Xóa cluster sau đó: network và IP sẽ được trả lại pool. 2. Private Cloud: tạo một VPC với gói nhỏ nhất dưới vai trò khách hàng thử nghiệm. VPC hiển thị hoạt động, tier nhận subnet, VM trong tier kết nối được Internet qua router của VPC, và thao tác **Change plan** sang gói lớn hơn có hiệu lực trong khoảng 20 giây mà không làm gián đoạn kết nối. ## Giới hạn và lưu ý {#limits-and-notes} - Kubernetes: các worker node được tính phí như VM theo giá gói và tính vào giới hạn số lượng VM. Một cluster có thể có tối đa 9 worker do giới hạn 10 node của CKS. - Kubernetes: control plane, router và IP public của cluster được miễn phí cho khách hàng; bạn tự chi trả chi phí này. - Private Cloud: mọi gói cước đều là **unmetered**. Giá trong biểu mẫu tính bằng Việt Nam đồng mỗi tháng; cột chi phí sử dụng mức giá tham chiếu không phải của bạn, vì vậy hãy dùng số liệu riêng của bạn. - VPC bị khóa sẽ bị giới hạn băng thông ở mức 1 Mbps, không bị tính phí và không tự động bị xóa. - Private Cloud sử dụng một router cho mỗi VPC chứ không dùng cặp dự phòng. Nếu host của router gặp sự cố, CloudStack sẽ khởi tạo lại trong vài phút. ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | `cp_offering_invalid` / "Offering này không phải 2 vCPU / 2048 MB / limitcpuuse" | Offering của control-plane có cấu hình khác hoặc không đặt giới hạn CPU | Tạo offering như trong bước 3 và chọn lại. | | Nút gạt **Enable CKS** bị vô hiệu hóa | Chưa chọn offering cho control-plane | Hãy chọn một offering trước. | | `kubernetesserviceenabled: false` | CKS đang tắt trong CloudStack | Bật CKS và khởi động lại management server. | | Kiểm tra endpoint thất bại | Không thể truy cập `endpoint.url` từ các VM trong cluster | Thiết lập URL truy cập được, khởi động lại management server, nhấp **Recheck**. | | "EOL: không thể bật mở bán" | Phiên bản đã qua ngày ngừng hỗ trợ (end-of-life) | Đăng ký phiên bản mới hơn. | | "Không có phiên bản: hãy nhấp Sync from CloudStack" | Chưa đăng ký phiên bản Kubernetes nào | Đăng ký phiên bản và đồng bộ. | | "CKS backend đang TẮT: khách hàng không thể tạo cluster ngay cả khi cờ mở bán đã được bật" | Nút bán đang bật nhưng CKS backend đang tắt | Bật CKS trên tab CloudStack. | | "Phải có ít nhất 1 plan đang được mở bán" | Gói worker cuối cùng đã bị xóa | Giữ lại ít nhất một gói, hoặc tắt tính năng bán Kubernetes. | | Cluster bị treo ở trạng thái đang tạo | Không đủ dung lượng hoặc thiếu ISO | Kiểm tra các tab dung lượng và trạng thái ISO của phiên bản. | | VPC mới tạo thất bại ngay từ bước đầu tiên | ID của VPC offering hoặc tier offering không hợp lệ | Thay thế từng UUID của offering bằng giá trị từ CloudStack của bạn. | | "cs_offering_id phải là một UUID" | ID của offering không phải là định dạng UUID | Dán id lấy từ `cmk list networkofferings`. | | Đổi gói cước thất bại | Tier offering mới không tồn tại hoặc tốc độ mạng không chính xác | Kiểm tra UUID của offering và tốc độ mạng của offering đó. | --- # Gói cước và định giá {#plans-and-pricing} > **Vị trí trong trang quản trị:** Services › Virtual Machines › Plans & pricing (`/vm/catalog`), với các tab Plan, Custom plan, Cycle và Offering CloudStack. Template nằm ở trang riêng Services › Virtual Machines › Template (`/vm/templates`). ## Chức năng {#what-it-does} Một **plan** là cấu hình tài nguyên khách hàng có thể mua: vCPU, RAM, ổ đĩa root và mức giá, trong một zone, từ một nguồn (CloudStack hoặc cụm Proxmox VE). Khách hàng chọn plan, hệ điều hành và **chu kỳ thanh toán** (theo giờ, theo tháng hoặc kỳ trả trước dài hạn hơn). Plan được bán trên customer portal, qua API và trên website của đại lý. ## Yêu cầu {#requirements} | Hạng mục | Yêu cầu | |---|---| | Source | CloudStack đã kết nối (plan trỏ tới một service offering của CloudStack) hoặc một cụm Proxmox VE được gắn vào zone. Xem [CloudStack](https://nexcmp.com/vi/docs/infrastructure/cloudstack/) và [Proxmox VE](https://nexcmp.com/vi/docs/infrastructure/proxmox/). | | Zone | Một zone có cung cấp máy ảo. Xem [Zones](https://nexcmp.com/vi/docs/infrastructure/zones/). | | Templates | Ít nhất một template đã bật và sẵn sàng. Xem [OS templates](https://nexcmp.com/vi/docs/infrastructure/templates/). | | Tỷ giá hối đoái | Chỉ khi bạn nhập giá bằng VND. Xem [Currency and exchange rates](https://nexcmp.com/vi/docs/catalog/currency-and-exchange-rates/). | | Quyền hạn | Quản trị viên; mỗi lần thay đổi giá đều yêu cầu nhập lý do. | ## Chuẩn bị hạ tầng {#prepare-the-infrastructure} - **CloudStack:** tạo các service offering bạn muốn bán (công khai, hoặc chia sẻ với domain NexCMP). Một plan trỏ tới một offering. Tab **Offering CloudStack** liệt kê trực tiếp các offering và disk offering từ CloudStack (lưu cache trong 60 giây). Khi bảng plan trống, worker sẽ tự động tạo sáu plan từ các offering thực tế của bạn. - **Proxmox VE:** không cần cấu hình trên Proxmox; mỗi plan sẽ tự mang thông số CPU, RAM và ổ đĩa riêng. Ổ đĩa không được nhỏ hơn ổ đĩa của template. ## Kết nối trong NexCMP {#connect-in-nexcmp} ### Cách lưu trữ giá {#how-prices-are-stored} NexCMP lưu trữ mọi mức giá dưới dạng **micro-dollar mỗi giờ** (µ$/hour; 1 µ$ là 1/1,000,000 USD). Bạn có thể nhập giá theo đơn vị mình muốn và biểu mẫu sẽ tự động quy đổi: | Đơn vị | Ghi chú | |---|---| | USD / giờ (6 số thập phân) | Được lưu trữ nguyên trạng. | | USD / tháng | Chia cho số giờ mỗi tháng theo thiết lập (730). | | VND / tháng | Quy đổi một lần theo tỷ giá hiện tại, sau đó lưu dưới dạng µ$/giờ. Chỉ xuất hiện khi đã có tỷ giá. | Biểu mẫu hiển thị kết quả: µ$/giờ, USD/giờ, giá theo tháng và từng chu kỳ thanh toán. **Giá tháng = giá giờ × 730**; chu kỳ dài hơn là **giá tháng × số tháng × (1 − chiết khấu)**. ### Thêm plan {#add-a-plan} 1. Mở **Services › Virtual Machines › Plans & pricing** và nhấp vào **Add plan**. 2. Điền thông tin vào biểu mẫu: | Trường | Giá trị ví dụ | |---|---| | Tên plan | `VM-2-4` | | Slug | để trống: được tạo tự động từ tên | | Zone | zone mặc định của bạn | | Nguồn hạ tầng | để trống đối với CloudStack, hoặc một cụm Proxmox | | Gói dịch vụ CloudStack (trực tiếp) | chọn một mục (chỉ hiển thị cho CloudStack) | | CPU (nhân), RAM (MB), Ổ đĩa root (GB) | `2`, `4096`, `40` | | Disk offering | tùy chọn, dành cho dung lượng root tùy chỉnh | | Nhập giá theo / Giá | `USD / month`, `12` | | Mô tả ngắn | `2 vCPU, 4 GB RAM, 40 GB NVMe` | | Thứ tự | `10` | | Kích hoạt | Bật: khách hàng có thể mua | | Chế độ hiển thị | Hiển thị trong danh mục | | Lý do thay đổi giá | `initial price` | 3. Nhấp vào **OK**. Plan sẽ xuất hiện trong bảng với giá theo giờ, giá theo tháng và một ô cho mỗi chu kỳ đã bật. ![Bảng plan với giá theo giờ, theo tháng và theo từng chu kỳ](https://nexcmp.com/vi/docs/images/catalog/plans-02-list.webp) ### Chu kỳ thanh toán {#billing-cycles} Mở tab **Cycle** để thiết lập các chu kỳ khách hàng có thể chọn cùng mức giảm giá tương ứng. | Chu kỳ | Mặc định | Ghi chú | |---|---|---| | Theo giờ | luôn bật | Tính phí theo từng giờ. | | Hàng tháng | bật, 0% | | | 1 năm | bật, 10% | | | 2 năm | bật, 15% | | | 3 năm | bật, 20% | | Bạn có thể đổi tên chu kỳ, điều chỉnh mức giảm giá (0 đến 90%) và bật hoặc tắt chu kỳ đó. Thay đổi sẽ áp dụng cho các VM được mua hoặc gia hạn **sau khi** bạn lưu; các VM đang chạy vẫn giữ nguyên mức giá đã khóa. ![Tab Cycle với mức giảm giá theo từng chu kỳ thanh toán](https://nexcmp.com/vi/docs/images/catalog/plans-03-cycles.webp) ### Đặt gói cơ sở và suy ra các gói khác {#set-a-base-plan-and-derive-the-others} **Set base plan + derive other plans** định giá lại toàn bộ bảng từ một mức giá. Hãy chọn gói cơ sở và giá của gói, sau đó giữ nguyên **tỷ lệ giá hiện tại** giữa các gói hoặc tính toán từ **giá thành phần** (µ$/giờ cho mỗi vCPU, mỗi GB RAM và mỗi GB NVMe, kèm chiết khấu combo tùy chọn từ 0 đến 50%). Bảng xem trước hiển thị giá cũ và mới trước khi ghi nhận bất kỳ thay đổi nào. Nhấp vào **Apply** và nhập lý do. Khi bạn áp dụng giá mới: các VM **theo giờ** đang chạy sẽ nhận mức giá **thấp hơn** từ giờ thanh toán tiếp theo, còn các VM trả trước sẽ nhận mức giá này khi gia hạn. Nếu giá **tăng lên**, các VM đang chạy vẫn giữ nguyên giá cũ. ### Gói tùy chỉnh {#custom-plans} Tab **Custom plan** cho phép khách hàng tự chọn cấu hình vCPU, RAM và dung lượng NVMe. Hãy thiết lập đơn giá mỗi giờ cho một vCPU, một GB RAM và một GB NVMe (để trống để suy ra từ tỷ lệ phần trăm giảm giá), giá trị tối thiểu, tối đa và bước nhảy cho từng mục, cùng các chu kỳ thanh toán được áp dụng. Gói **tùy chỉnh** nên có giá cao hơn gói cố định có cùng cấu hình, nếu không khách hàng sẽ bỏ qua gói cố định; trang sẽ đánh dấu các hàng mà gói tùy chỉnh rẻ hơn. Bật **Enable custom plans for customers** để mở bán; khi tắt, cổng thông tin sẽ hiển thị "Coming soon". Mỗi VM tùy chỉnh sẽ có một hàng gói ẩn riêng; các hàng này không thể chỉnh sửa hoặc xóa khi VM vẫn đang tồn tại. ### Thay đổi, ẩn, nhân bản, xóa {#change-hide-clone-delete} | Thao tác | Chức năng | |---|---| | **Edit** | Thay đổi tên, mô tả, thứ tự, giá, trạng thái kích hoạt và khả năng hiển thị. | | **Bật/Tắt** | **Off**: khách hàng không thể mua; các VM đang chạy không bị ảnh hưởng. | | **Ẩn / Hiện** | Gói bị ẩn không nằm trong danh mục nhưng các VM hiện có vẫn giữ nguyên gói và quản trị viên có thể gán gói. | | **Clone** | Tạo gói mới trong cùng zone với nguồn, cấu hình hoặc giá mới, tùy chọn ẩn gói cũ. Để bán cùng cấu hình từ CloudStack và Proxmox, hãy nhân bản gói đó và chọn nguồn còn lại. | | **Di chuyển lên/xuống** | Thay đổi thứ tự. | | **Delete** | Xóa gói khỏi danh mục bán và khỏi bảng. Các VM đang dùng gói vẫn giữ nguyên gói. | ::: warning Các gói đang sử dụng sẽ bị khóa Khi một gói đã có VM, **zone, offering, CPU, RAM, ổ đĩa và nguồn** của gói sẽ bị khóa để các VM đang chạy không bị thay đổi ngoài ý muốn. Sử dụng **Clone** để tạo cấu hình mới; gói cũ vẫn giữ nguyên các VM của nó. ::: ## Kiểm tra {#verify} 1. Gói xuất hiện trong bảng với giá theo giờ và theo tháng đúng như mong đợi. 2. Trong cổng thông tin khách hàng, hãy bắt đầu tạo đơn hàng: zone sẽ cung cấp gói này và giá các chu kỳ khớp với tab **Cycle**. 3. Đặt một đơn hàng thử nghiệm, kiểm tra số tiền trừ trong ví so với giá hiển thị, sau đó xóa VM. ## Giới hạn và lưu ý {#limits-and-notes} - Một plan thuộc về **một** zone và **một** source. - Giá được lưu theo µ$/hour; giá VND hiển thị được quy đổi và làm tròn theo **VND rounding step** (xem trang tiền tệ). Ví tiền luôn ở đơn vị USD. - Đại lý nhận giá bán buôn và bán lẻ được quy đổi từ giá niêm yết; việc đổi giá của plan hiện có không sao chép giá đại lý tùy chỉnh sang bản clone đã thay đổi cấu hình. - Giới hạn min, max và step của custom plan được kiểm tra theo các giới hạn của CloudStack; dung lượng disk tối đa vượt quá `storage.max.volume.size` của CloudStack sẽ khiến quá trình deploy thất bại và được hoàn tiền. ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | "Bắt buộc nhập tên gói" / "Bắt buộc chọn service offering" | Thiếu trường thông tin | Điền tên; với CloudStack hãy chọn một offering. | | "CPU/RAM/disk phải > 0" | Một thông số bị trống hoặc bằng 0 | Nhập cả ba thông số. | | "Giá không hợp lệ (µ$/hr phải từ 1 … 100,000,000)" | Giá nằm ngoài phạm vi cho phép | Kiểm tra lại đơn vị và số tiền. | | "Thay đổi giá cần có lý do" | Chưa nhập lý do khi chỉnh sửa | Nhập lý do (từ 3 ký tự trở lên). | | "Offering \"X\" là 4c/8192 nhưng gói chỉ định 2c/4096 - CloudStack sẽ cấp phát theo offering. Vẫn lưu?" | Thông số của plan khác với offering | Điều chỉnh cho khớp, hoặc xác nhận để giữ thông số của CloudStack. | | "Không thể lấy danh sách offering từ CloudStack" | Mất kết nối hoặc key thiếu quyền | Xem [CloudStack](https://nexcmp.com/vi/docs/infrastructure/cloudstack/). | | "Template chưa sẵn sàng trên CloudStack - quá trình triển khai sẽ thất bại. Vẫn bật?" | Bạn đã kích hoạt một template chưa sẵn sàng | Chờ template sẵn sàng. | | Không thể chỉnh sửa plan ("has VMs - locked") | Đang có VM sử dụng plan này | Hãy clone plan này. | | Plan không hiển thị với khách hàng | Bị tắt, ẩn hoặc zone chưa sẵn sàng | Kiểm tra **Active**, **Visibility** và tag của zone. Xem [Zones](https://nexcmp.com/vi/docs/infrastructure/zones/). | | "Chọn ít nhất 1 chu kỳ thanh toán" | Chưa chọn chu kỳ nào cho custom plan | Tích chọn ít nhất một dịch vụ. | | "Giảm giá bundle phải từ 0–50%" | Nằm ngoài phạm vi | Nhập giá trị từ 0 đến 50. | | Thiếu tùy chọn giá VND | Chưa có tỷ giá quy đổi | Hãy cập nhật tỷ giá trước. | --- # Quota băng thông và add-on {#bandwidth-quotas-and-add-ons} > **Vị trí trong admin:** Services › Bandwidth: Summary (`/bandwidth`), Add-on (`/bandwidth/addons`) và Quotas, pricing & policy (`/bandwidth/policy`). Công tắc module nằm tại System › Admin › License & updates. ## Chức năng {#what-it-does} Tính năng Bandwidth cấp cho mỗi dịch vụ được tính phí theo dung lượng một **quota** lưu lượng hàng tháng. NexCMP đo lường mức sử dụng, cảnh báo khách hàng ở mức 80% và 100%, và khi vượt quota, hệ thống sẽ xử lý theo **overage policy** của bạn. Khách hàng có thể mua thêm **add-on** dung lượng terabyte từ ví của họ; bạn cũng có thể cấp add-on miễn phí. | Dịch vụ | Quota | |---|---| | Máy ảo | Mỗi VM mỗi tháng (mặc định 2048 GB, tức 2 TB) | | Kubernetes | Hạn mức VM nhân với số lượng worker | | Object Storage | Lưu lượng tải xuống mỗi khách hàng mỗi tháng (mặc định 100 GB); vượt mức sẽ áp dụng giá pay-as-you-go thông thường | | VPN | Giữ nguyên hạn mức của gói; nâng cấp băng thông trên trang VPN | | Private Cloud | **Không giới hạn lưu lượng** | ## Yêu cầu {#requirements} | Hạng mục | Yêu cầu | |---|---| | Module | **Bandwidth** được bật theo mặc định. Tắt tính năng này trong License & updates để ẩn đi. | | Nguồn đo lường | Với nguồn mặc định, **CloudStack VM statistics**. Hãy duy trì bật tính năng thu thập thống kê VM trong CloudStack; thời gian lưu trữ mặc định 720 phút là đủ. | | Proxmox VE | Các VM trên Proxmox VE **không bị tính lưu lượng**. | | Tỷ giá hối đoái | Giá add-on được nhập bằng VND. Xem [Tiền tệ và tỷ giá](https://nexcmp.com/vi/docs/catalog/currency-and-exchange-rates/). | | Phụ thuộc vào | [CloudStack](https://nexcmp.com/vi/docs/infrastructure/cloudstack/) cho lưu lượng VM và Kubernetes, [S3](https://nexcmp.com/vi/docs/infrastructure/s3/) cho lượt tải xuống từ storage. | ## Chuẩn bị hạ tầng {#prepare-the-infrastructure} Không yêu cầu gì thêm ngoài việc CloudStack đã được kết nối. NexCMP đọc `listVirtualMachinesUsageHistory` cho tất cả VM của tài khoản trong một lệnh gọi duy nhất, mỗi 5 phút một lần, theo các khoảng thời gian tối đa hai giờ. Mỗi mẫu bao gồm một phút và được **cộng dồn**. Các mẫu được lấy lùi lại ba phút trước đó để có đủ thời gian gửi đến. Khoảng gián đoạn dài hơn thời gian lưu trữ của CloudStack (khoảng 12 giờ) sẽ bị bỏ qua và ghi nhận lại. ::: info Ý nghĩa của các con số Mức sử dụng được tính trên giao diện mạng của từng VM, do đó bao gồm cả lưu lượng giữa các VM chứ không chỉ lưu lượng truy cập Internet. Số liệu này có thể cao hơn một chút so với số liệu ghi nhận bởi edge router. ::: ## Kết nối trong NexCMP {#connect-in-nexcmp} 1. Mở **Services › Bandwidth › Quotas, pricing & policy**. 2. Thiết lập các giá trị và nhấp vào **Save**; hệ thống sẽ yêu cầu nhập lý do và ghi lại. Worker sẽ áp dụng thay đổi trong khoảng 30 giây. | Trường | Mặc định | Ý nghĩa | |---|---|---| | Bật Bandwidth (menu khách hàng và mua add-on) | bật | Công tắc bật tính năng bán hàng của module. | | VM, GB/tháng (Kubernetes = giá trị này × worker) | 2048 | Hạn mức cho mỗi VM theo từng chu kỳ. | | S3, GB tải xuống/tháng cho mỗi khách hàng | 100 | Vượt mức này sẽ áp dụng giá pay-as-you-go S3 thông thường. | | Chiều tính hạn mức (VM, Kubernetes) | In + out | Hoặc **Outbound only**. | | Giá +1 TB (VND) | 100,000 | Được quy đổi sang cent theo tỷ giá niêm yết. | | Tối đa mỗi lần mua (TB) | 50 | | | Chính sách vượt hạn mức | suspend | **notify**, **throttle** hoặc **suspend** (bên dưới). | | Bắt đầu áp dụng suspend thực tế từ | ngày migration + 24 giờ | Trước ngày này, không có dịch vụ nào bị suspend; khách hàng chỉ được cảnh báo. | | Giới hạn tốc độ throttle (Mbps) | | Chỉ dùng cho throttle. | ![Chính sách băng thông: hạn mức mặc định, giá add-on và chính sách vượt hạn mức](https://nexcmp.com/vi/docs/images/catalog/bandwidth-01-policy.webp) ### Chính sách vượt hạn mức {#overage-policies} | Chính sách | Điều gì xảy ra khi dịch vụ vượt quá 100% | |---|---| | **notify** | Khách hàng được thông báo. Không có hành động nào khác. | | **throttle** | Hiện tại giống như notify: bộ giới hạn tốc độ chưa được kết nối trong bản phát hành này. | | **suspend** (mặc định) | VM, cluster hoặc tài khoản S3 sẽ bị tạm ngưng cho đến khi khách hàng mua add-on hoặc chu kỳ tiếp theo bắt đầu. Chỉ có hiệu lực từ ngày **suspend-from**. | Các cảnh báo 80% và 100% (chuông và e-mail) luôn chạy, một lần cho mỗi ngưỡng, chu kỳ và dịch vụ. Nếu bạn mở khóa một dịch vụ đã bị tạm ngưng do vượt băng thông trong khi dịch vụ đó vẫn vượt quota, lần kiểm tra tiếp theo (trong vòng 5 phút) sẽ tạm ngưng lại. Để giữ dịch vụ tiếp tục hoạt động, hãy **cấp add-on**. ### Theo dõi mức sử dụng và cấp add-on {#watch-usage-and-grant-add-ons} Mở **Services › Bandwidth › Summary**. Trang này liệt kê mọi dịch vụ cùng với mức sử dụng trong chu kỳ hiện tại, quota bao gồm cả add-on, quota còn lại và các mốc 80%, 100%. Các ô KPI hiển thị số lượng dịch vụ, số add-on đã bán trong 30 ngày qua và trạng thái collector (running, cursor). Bảng **Daily** hiển thị chu kỳ hiện tại theo từng ngày. ![Bandwidth Summary cùng trạng thái collector và mức sử dụng theo từng dịch vụ](https://nexcmp.com/vi/docs/images/catalog/bandwidth-02-summary.webp) Để cấp thêm dung lượng cho khách hàng, hãy dùng **Grant** trên dịch vụ (một add-on tính theo terabyte nguyên vẹn và hoàn toàn miễn phí). Mở **Add-on** để xem lịch sử mua và cấp add-on, mới nhất hiển thị trước, có bộ lọc theo loại. ![Lịch sử add-on hiển thị các lượt mua và lượt cấp miễn phí](https://nexcmp.com/vi/docs/images/catalog/bandwidth-03-addons.webp) ### Khách hàng nhìn thấy gì {#what-customers-see} Cổng khách hàng sẽ có menu **Bandwidth** hiển thị mức sử dụng, quota còn lại và thao tác **buy +1 TB** thanh toán từ ví (tối đa theo hạn mức mỗi lần mua của bạn). Các gói add-on có hiệu lực trong chu kỳ hiện tại. ## Kiểm tra {#verify} 1. Collector trên **Summary** đang chạy và cursor của nó tịnh tiến sau mỗi vài phút. 2. VM có lưu lượng mạng sẽ hiển thị mức sử dụng sau khoảng 10 đến 15 phút. 3. Để xem các cảnh báo, hãy giảm quota của VM xuống còn vài GB trên bản cài đặt **thử nghiệm** và tạo một lượng lưu lượng mạng. Đừng thực hiện điều này trên production: quota áp dụng cho tất cả VM. ## Giới hạn và lưu ý {#limits-and-notes} - Mức sử dụng được tính theo chu kỳ (một tháng). Add-on và quota áp dụng cho chu kỳ hiện tại. - "Enforce actual suspend from" bảo vệ bạn khỏi việc tạm ngưng khách hàng ngay tại thời điểm mô-đun được kích hoạt lần đầu. - Chính sách throttle chỉ gửi thông báo trong bản phát hành này. - Việc thay đổi quota sẽ áp dụng cho tất cả các site, bao gồm cả site reseller. Giá add-on bán lẻ và bán buôn của reseller sẽ tính theo mức chiết khấu hoặc tỷ lệ chênh giá của họ. - Băng thông cho **Dedicated servers** là một phần riêng biệt; xem [Dedicated servers](https://nexcmp.com/vi/docs/infrastructure/dedicated/). ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | Mức sử dụng vẫn bằng 0 đối với VM đang chạy | Worker bị dừng, CloudStack bị ngắt kết nối hoặc tính năng thống kê VM bị tắt | Kiểm tra `sudo nexcmp status` và **Test connection** trong [CloudStack](https://nexcmp.com/vi/docs/infrastructure/cloudstack/); bật thống kê VM trong CloudStack. | | Dữ liệu sử dụng bị ngắt quãng | Thời gian lưu trữ của CloudStack đã bị vượt quá, hoặc worker bị gián đoạn hơn khoảng 12 giờ | Không thể khôi phục; khoảng trống dữ liệu đã được ghi nhận. | | Mức sử dụng cao hơn một chút so với dự kiến | Bao gồm cả lưu lượng giữa các VM và lưu lượng giao diện khác | Hiện tượng bình thường; hãy giải thích điều này cho khách hàng. | | Dịch vụ bị tạm ngưng lại tiếp tục bị tạm ngưng sau khi bạn mở khóa | Dịch vụ vẫn đang vượt quá quota | Cấp add-on hoặc tăng quota. | | Không có dịch vụ nào bị tạm ngưng dù chính sách là **suspend** | Ngày suspend-from ở tương lai | Đặt về thời điểm hiện tại (trang hiển thị "ACTIVE" khi có hiệu lực). | | "bw_over_policy phải là notify, throttle hoặc suspend" | Policy không hợp lệ được gửi qua API | Sử dụng một trong ba giá trị. | | VM Proxmox không hiển thị mức sử dụng | Chúng không được đo lường mức sử dụng | Hoạt động bình thường theo thiết kế. | | Khách hàng không thể mua add-on | Bandwidth đang bị tắt, hoặc ví hết tiền | Kiểm tra nút bật/tắt và số dư ví. | --- # Tiền tệ và tỷ giá hối đoái {#currency-and-exchange-rates} > **Vị trí trong admin:** Finance › Payment channels › Exchange rates (`/payments/fx`) để chỉnh tỷ giá. System › Settings › Brand (`/settings/branding`) cho nút chuyển đổi **Site currency**. ## Chức năng {#what-it-does} NexCMP lưu trữ ví và hóa đơn bằng USD. Giá gói VM được lưu dưới dạng micro-dollar mỗi giờ. Tiền tệ hiển thị cho phép khách hàng xem số tiền USD theo loại tiền tệ của họ theo tỷ giá đã công bố; chúng không làm thay đổi số dư ví. Một số dịch vụ chấp nhận giá nhập bằng VND, bao gồm add-on băng thông, S3, Private Cloud và các gói Bare Metal hiện có vẫn giữ mức giá VND. Chuyển khoản ngân hàng qua SePay được thanh toán bằng VND. Tỷ giá được **quản trị viên công bố**. Hệ thống không tự động làm mới, vì vậy các tỷ giá bạn đã lưu sẽ giữ nguyên chính xác cho đến khi bạn nhấn nút cập nhật. ## Yêu cầu {#requirements} | Hạng mục | Yêu cầu | |---|---| | Kết nối Internet | Máy chủ panel phải kết nối được tới `open.er-api.com` (đối với USD/VND) và `api.frankfurter.dev` (đối với các loại tiền tệ khác) khi bạn nhấn **Update exchange rates**. | | Quyền hạn | Cần quyền quản trị viên để thay đổi; mỗi thay đổi đều yêu cầu nhập lý do. | | Phụ thuộc vào | Không cần thiết lập gì thêm. [Plans](https://nexcmp.com/vi/docs/catalog/plans/), [Bandwidth](https://nexcmp.com/vi/docs/catalog/bandwidth/), [S3](https://nexcmp.com/vi/docs/infrastructure/s3/) và chuyển khoản ngân hàng VND sẽ sử dụng tỷ giá này. | ## Chuẩn bị hạ tầng {#prepare-the-infrastructure} Không bắt buộc. Nếu máy chủ của bạn lọc lưu lượng ra ngoài (outbound), hãy cho phép kết nối HTTPS tới hai dịch vụ nêu trên. ## Kết nối trong NexCMP {#connect-in-nexcmp} ### 1. Chọn đơn vị tiền tệ của trang {#_1-choose-the-site-currency} Mở **System › Settings › Brand** và thiết lập **Site currency**: | Tùy chọn | Khách hàng nhìn thấy gì | |---|---| | **Language-based (auto)** (mặc định trên bản cài đặt mới) | Cổng portal sẽ chọn đơn vị tiền tệ hiển thị theo ngôn ngữ (bảng bên dưới). Khách hàng có thể chọn USD để thay thế. | | **USD** | Giá và số dư chỉ hiển thị bằng USD. Không có nút chuyển đổi tiền tệ và không có số tiền quy đổi. | | **VND** | Cài đặt cũ; tuân theo các quy tắc hiển thị dựa trên ngôn ngữ tương tự như Auto. | Lưu lại. Các trang của khách hàng sẽ cập nhật trong khoảng một phút. Khi trang web tuân theo ngôn ngữ của khách hàng: | Ngôn ngữ | Tiền tệ hiển thị | |---|---| | Tiếng Anh | USD | | Tiếng Việt | VND | | Tiếng Trung (giản thể / phồn thể) | CNY / TWD | | Tiếng Nhật, tiếng Hàn | JPY, KRW | | Tiếng Pháp, tiếng Đức, tiếng Tây Ban Nha, tiếng Ý | EUR | | Tiếng Bồ Đào Nha, tiếng Nga | BRL, RUB | | Tiếng Ả Rập, tiếng Hindi | SAR, INR | | Tiếng Indonesia, tiếng Thái | IDR, THB | Tiền tệ chưa được công bố tỷ giá sẽ không được hiển thị: cổng thông tin sẽ quay về dùng USD. ### 2. Công bố tỷ giá {#_2-publish-the-rates} 1. Mở **Finance › Payment channels › Exchange rates**. 2. Thẻ **Currency by language** liệt kê 11 loại tiền tệ hiển thị cùng tỷ giá theo USD, nguồn (Frankfurter) và thời gian cập nhật gần nhất. Nhấp vào **Update exchange rates**. Nút này thực hiện hai việc trong một bước: đọc bảng tỷ giá thị trường công khai cho **USD/VND** và đọc 11 tỷ giá còn lại. Cả hai đều được kiểm tra trước khi lưu bất kỳ tỷ giá nào. Nếu một bên gặp lỗi, sẽ không có gì thay đổi và các tỷ giá trước đó được giữ nguyên. 3. Thẻ **Active exchange rate** hiển thị tỷ giá USD/VND đang áp dụng, nhãn nguồn của tỷ giá (thị trường công khai hoặc cố định), biên lợi nhuận và các số liệu tham chiếu thị trường kèm mốc thời gian. 4. Thẻ **Config** (lưu kèm lý do): | Trường | Ý nghĩa | Khoảng giá trị | |---|---|---| | Margin (bp, 100 = 1 %) | Được cộng thêm vào tỷ giá tham chiếu thị trường. Tỷ giá áp dụng là tỷ giá tham chiếu cộng thêm biên độ, làm tròn lên. | 0 đến 1000 | | Tỷ giá cố định (VND mỗi USD, 0 = theo thị trường) | Tỷ giá do bạn tự thiết lập. Tỷ giá này thay thế số liệu thị trường. | 0 hoặc 15,000 đến 50,000 | | Jump threshold (bp) | Tỷ giá thị trường mới chênh lệch so với tỷ giá hiện tại vượt quá mức này sẽ bị **tạm giữ** cho đến khi bạn xác nhận. | 50 đến 2000 (mặc định 500) | | VND rounding step | Làm tròn giá VND và số tiền chuyển khoản ngân hàng. | 1, 100, 1,000 (mặc định) hoặc 10,000 | 5. Nếu tỷ giá thị trường mới biến động vượt quá ngưỡng, thẻ **Pending exchange rate** sẽ xuất hiện và tỷ giá đó **không được áp dụng**. Hãy kiểm tra lại tỷ giá so với nguồn tham chiếu bạn đã chọn và nhấn **Apply this rate**. Tỷ giá thị trường nằm ngoài khoảng 15,000 đến 50,000 VND mỗi USD sẽ bị từ chối vì không hợp lý. Thao tác làm mới thủ công bị giới hạn một yêu cầu mỗi năm phút, vì vậy nút bấm có thể yêu cầu bạn chờ. 6. Bảng **Exchange rate history** liệt kê mọi tỷ giá đã lấy về hoặc được xác nhận kèm thời gian, tỷ giá hiệu lực, tham chiếu thị trường, nguồn, trạng thái áp dụng, người thực hiện và ghi chú (các mức biến động bị giữ lại được đánh dấu **held**). ## Cách sử dụng tỷ giá {#how-a-rate-is-used} | Vị trí | Quy tắc | |---|---| | Ví và hóa đơn | USD cent. Tỷ giá không bao giờ thay đổi số dư. | | Các gói VM được nhập bằng VND | Được quy đổi **một lần** theo tỷ giá có hiệu lực khi bạn lưu, sau đó lưu trữ bằng USD. Các thay đổi tỷ giá sau này không định giá lại các gói VM đó. | | Chuyển khoản ngân hàng qua SePay | Khách hàng thanh toán `ceil(USD × rate)`, được làm tròn lên theo bước làm tròn. SePay bị **chặn** cho đến khi có tỷ giá USD/VND. | | Các gói Bare Metal | Các bản cài đặt mới sử dụng trực tiếp USD. Các gói VND hiện có vẫn giữ nguyên đơn vị giá và cần có tỷ giá khi tính phí; xem [Máy chủ chuyên dụng](https://nexcmp.com/vi/docs/infrastructure/dedicated/). | | Các khoản thanh toán quốc tế khác nhập bằng VND | Được làm tròn đến cent gần nhất. | | Hiển thị trên cổng thông tin | USD nhân với tỷ giá đã công bố của tiền tệ hiển thị, được định dạng theo ngôn ngữ tương ứng. | ## Kiểm tra {#verify} 1. **Active exchange rate** hiển thị giá trị USD/VND cùng thời gian "fetched" gần đây. 2. Bảng **Currency by language** hiển thị các tỷ giá không bị trống. 3. Trong cổng thông tin khách hàng, chuyển ngôn ngữ sang tiếng Việt (tiền tệ trang web là Auto): giá hiển thị bằng đồng; chuyển sang tiếng Nhật: yên. Với tiền tệ trang web là USD, chỉ hiển thị đô la. 4. Trên biểu mẫu gói dịch vụ (Plans & pricing), danh sách **Enter price by** có tùy chọn **VND / month**. ## Giới hạn và lưu ý {#limits-and-notes} - Không tự động làm mới. Hãy nhấn **Update exchange rates** khi bạn muốn cập nhật tỷ giá mới, và đặt lịch nhắc nếu tỷ giá quan trọng với bạn. - Tỷ giá thị trường công khai được sử dụng cho USD/VND; đây là tỷ giá tham chiếu chứ không phải báo giá mua hoặc bán của ngân hàng. Các loại tiền tệ hiển thị khác lấy từ Frankfurter; ngày cũ hơn 14 ngày hoặc bảng không đầy đủ sẽ bị từ chối. - Margin và tỷ giá cố định chỉ áp dụng cho USD/VND. 11 loại tiền tệ hiển thị còn lại không tính margin. - Mỗi ngôn ngữ của khách hàng tương ứng với một loại tiền tệ. Việc đổi ngôn ngữ sẽ đặt lại về tiền tệ của ngôn ngữ đó, trừ khi khách hàng đã chọn USD cho cùng ngôn ngữ. - Các site reseller cũng áp dụng các mức tỷ giá này. ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | "Tỷ giá mới chênh lệch vượt ngưỡng - TẠM DỪNG, cần xác nhận thủ công" | Mức biến động lớn hơn ngưỡng cho phép | Hãy kiểm tra và nhấp vào **Apply this rate**, hoặc thay đổi ngưỡng. | | "Máy chủ từ chối tỷ giá mới" | Số liệu thị trường nằm ngoài khoảng 15,000 đến 50,000 hoặc sai định dạng | Chờ và thử lại, hoặc thiết lập tỷ giá cố định. | | Làm mới yêu cầu bạn đợi trước khi thử lại | Cập nhật quá thường xuyên | Chờ và thử lại. | | "không thể lấy tỷ giá: …" | Máy chủ panel không thể kết nối tới các dịch vụ tỷ giá | Cho phép HTTPS outbound và thử lại. | | Thẻ **Sepay blocked** | Chưa có tỷ giá USD/VND nào được công bố | Nhấn **Update exchange rates** hoặc thiết lập tỷ giá cố định. | | Thiếu một loại tiền tệ trong portal | Chưa có tỷ giá của loại tiền đó | Nhấn **Update exchange rates**. | | Khách hàng chỉ thấy giá bằng USD | Site currency là USD, hoặc chưa có tỷ giá | Đặt **Site currency** thành Auto và xuất bản tỷ giá. | | "Bảng tỷ giá Fx không đầy đủ; giữ lại các tỷ giá trước đó" | Frankfurter trả về ít hơn 11 loại tiền tệ | Thử lại sau; chưa có thay đổi nào được thực hiện. | | Thiếu tùy chọn VND trong biểu mẫu gói dịch vụ | Không có tỷ giá USD/VND | Hãy công bố một tỷ giá trước. | --- # Kênh thanh toán {#payment-channels} > **Vị trí trong admin:** Finance › Payment channels (`/payments`). Bật/tắt và biểu phí: Finance › Payment channels › Fees & limits (`/payments/fees`). NexCMP sử dụng **ví USD trả trước**. Khách hàng nạp tiền vào ví thông qua kênh thanh toán; mọi dịch vụ sau đó đều được thanh toán từ ví. Một kênh chỉ hiển thị cho khách hàng khi vừa được **bật** vừa được **cấu hình**. ## Chức năng {#what-it-does} Payment channels kết nối tài khoản thanh toán của bạn (Stripe, PayPal, Binance, ngân hàng Việt Nam) với ví khách hàng. Mỗi thanh toán được xác nhận sẽ tạo thành đúng một khoản cộng tiền vào ví — mỗi khoản nạp được định danh bằng payment ID từ cổng thanh toán, do đó webhook gửi lặp lại sẽ không bao giờ cộng tiền hai lần. Hãy sử dụng trang này để xem kênh nào đã sẵn sàng, hiệu quả hoạt động trong 30 ngày qua và kênh nào cần xử lý. ## Yêu cầu {#requirements} | Hạng mục | Yêu cầu | |---|---| | Địa chỉ HTTPS công khai | Các cổng thanh toán gửi webhook đến `https:///v1/billing/...`, vì vậy bảng điều khiển của bạn phải truy cập được từ Internet qua kết nối TLS hợp lệ (xem [DNS and Cloudflare](https://nexcmp.com/vi/docs/getting-started/dns-and-cloudflare/)). | | Tài khoản | Tài khoản riêng của bạn tại từng nhà cung cấp muốn sử dụng. Thông tin xác thực được nhập trong trang admin và không bao giờ hiển thị lại (chỉ hiển thị 4 ký tự cuối). | | Vai trò Admin | Một tài khoản quản trị viên. | | Thành phần phụ thuộc | Không có. Riêng kênh ngân hàng VN cần thêm [tỷ giá quy đổi](https://nexcmp.com/vi/docs/catalog/currency-and-exchange-rates/). | ## Các kênh thanh toán {#the-channels} | Kênh | Giao diện khách hàng thấy | Cấu hình tại | Bài viết | |---|---|---|---| | Thẻ (Stripe) | Biểu mẫu nhập thẻ, thẻ đã lưu | Payment channels › Stripe | [Stripe](https://nexcmp.com/vi/docs/billing/stripe/) | | Apple Pay, Google Pay, Link | Các nút ví điện tử (Stripe Express Checkout) | Stripe, kèm xác thực tên miền | [Stripe](https://nexcmp.com/vi/docs/billing/stripe/#apple-pay-google-pay-and-link) | | Alipay | Chuyển hướng đến Alipay (Stripe thanh toán bằng JPY) | Stripe, kèm Fees & limits | [Stripe](https://nexcmp.com/vi/docs/billing/stripe/#alipay) | | PayPal | Các nút PayPal, tài khoản PayPal đã lưu | Payment channels › PayPal | [PayPal](https://nexcmp.com/vi/docs/billing/paypal/) | | USDT | Địa chỉ nạp tiền và số tiền chính xác | Payment channels › USDT | [USDT](https://nexcmp.com/vi/docs/billing/usdt/) | | Chuyển khoản ngân hàng VN | Mã QR và thông tin chuyển khoản (chỉ có trên giao diện tiếng Việt) | Payment channels › VN bank transfer | [Chuyển khoản ngân hàng (Việt Nam)](https://nexcmp.com/vi/docs/billing/bank-transfer-vn/) | ## Chuẩn bị hạ tầng {#prepare-the-infrastructure} Không yêu cầu. Mọi thứ đều được cấu hình trong admin; không cần cài đặt gì thêm trên máy chủ. ## Kết nối trong NexCMP {#connect-in-nexcmp} 1. Mở **Finance › Payment channels** (`/payments`). Bảng tổng quan liệt kê từng kênh cùng trạng thái tương ứng. 2. Mở tab riêng của kênh (**Stripe**, **PayPal**, **USDT**, **VN bank transfer**) và làm theo bài viết hướng dẫn. Cuối mỗi tab đều có nút **Save** và nút **Test** nếu kênh đó hỗ trợ. 3. Mở **Fees & limits** (`/payments/fees`), tìm thẻ **Payment gateways & fees (wallet top-up)**, bật kênh bằng công tắc tương ứng và nhấp **Save channels & fees**. ![Tổng quan payment channels liệt kê các cổng thanh toán cùng trạng thái bật, cấu hình và số liệu thống kê 30 ngày](https://nexcmp.com/vi/docs/images/billing/payment-channels-01-overview.webp) ![Trang Fees and limits với các công tắc bật kênh và các trường cấu hình phí](https://nexcmp.com/vi/docs/images/billing/payment-channels-02-fees.webp) ### Công tắc và phí (Fees & limits) {#switches-and-fees-fees-limits} | Cài đặt | Mặc định | Ý nghĩa | |---|---|---| | Thẻ (Stripe) | On | Biểu mẫu thẻ trên màn hình nạp tiền. Bị ẩn cho đến khi Stripe có secret key. | | Apple Pay, Google Pay, Link | On | Các nút ví điện tử. Chúng chỉ xuất hiện khi tên miền đã được xác minh trên Stripe. | | Alipay | Tắt | Cần kích hoạt Alipay trong Stripe Dashboard. | | PayPal | Tắt | Chỉ hiển thị khi PayPal đã được cấu hình. | | USDT (Binance) | Tắt | Nút gạt bị khóa cho đến khi địa chỉ nạp tiền được xác minh với Binance. | | Phí Stripe % / cố định (cents) | 3.6 % và 0 | Dùng để hiển thị phí cho khách hàng và tính toán số tiền được ghi có. Hãy đặt theo biểu phí Stripe thực tế của bạn. | | Phí PayPal % / cố định | 4.4 % và 30 cents | Tương tự, dành cho PayPal. | | Phí USDT % | 1 % | Tương tự, dành cho USDT. | | Khách hàng trả phí nạp tiền | Tắt | **On**: khách hàng thanh toán số tiền + phí và ví nhận toàn bộ số tiền. **Off**: phí được khấu trừ và ví nhận số tiền trừ đi phí. | Khách hàng luôn thấy phí và số tiền thực nhận vào ví trước khi thanh toán. Việc tắt một kênh sẽ ẩn nút thanh toán và máy chủ sẽ từ chối các khoản thanh toán mới với `method_disabled` (HTTP 403). ::: tip Hạn mức nạp tiền Số tiền tối thiểu và tối đa cho mỗi lần nạp tiền nằm trên cùng một trang — xem [Minimum top-up](https://nexcmp.com/vi/docs/billing/minimum-top-up/). ::: ## Kiểm tra {#verify} 1. Trên bảng tổng quan, kênh hiển thị **Enabled** và **Configured**; cột **Last test** sẽ được điền sau khi bạn nhấp vào **Test** trên tab của kênh. 2. Đăng nhập vào portal với tư cách khách hàng thử nghiệm và mở **Billing › Deposit**. Nút của kênh sẽ xuất hiện. 3. Thực hiện một khoản thanh toán nhỏ (xem bài viết của kênh để biết thẻ thử nghiệm hoặc tài khoản sandbox). Số dư tăng lên, thông báo **Top-up received** xuất hiện và khoản thanh toán được liệt kê trong **Finance › Billing › Top-ups** (`/billing/deposits`). ## Hạn mức & lưu ý {#limits-notes} - **Các cột trong bảng tổng quan:** *30 days* (số lượng giao dịch, thành công, thất bại và khối lượng), *Stuck 24h* (các khoản thanh toán vẫn đang chờ xử lý sau một ngày) và *Unmatched* (USDT hoặc chuyển khoản ngân hàng đã nhận nhưng không khớp với đơn hàng nào). Hàng KPI cộng tổng khối lượng 30 ngày, số lượng kênh lỗi (đã bật nhưng chưa cấu hình, hoặc có thanh toán bị nghẽn) và tổng số khoản không khớp. - **Các sự kiện webhook** được liệt kê tại **Payment channels › Gateway events** (`/payments/events`). Stripe có tab riêng; PayPal và USDT dùng chung một tab. Sự kiện thất bại có thể được phát lại — sổ cái ví có tính lũy đẳng, nên việc phát lại không bao giờ ghi có hai lần. - **Resellers** có thể có các kênh Stripe, PayPal, USDT và ngân hàng riêng. Các hàng của họ cũng xuất hiện ở đây, và bộ chọn site ở phần đầu trang sẽ lọc chúng. Xem [Resellers](https://nexcmp.com/vi/docs/customers/resellers/). - **Hoàn tiền:** Các khoản thanh toán Stripe và PayPal có thể được hoàn tiền từ danh sách thanh toán; các khoản thanh toán USDT không thể hoàn về nguồn ban đầu (máy chủ sẽ trả về `usdt_no_refund`). - **Maintenance mode** vẫn tiếp nhận webhook từ cổng thanh toán, do đó khoản thanh toán được thực hiện ngay trước thời gian bảo trì sẽ không bị mất. ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | Kênh thanh toán bị thiếu trên màn hình nạp tiền của khách hàng | Đã bị tắt, chưa cấu hình, hoặc (ngân hàng VN) giao diện không phải tiếng Việt | Kiểm tra **Fees & limits** và tab của kênh; xem [Bank transfer (Vietnam)](https://nexcmp.com/vi/docs/billing/bank-transfer-vn/). | | Chỉ số KPI **Faulty channels** lớn hơn 0 | Một kênh được bật nhưng chưa có thông tin xác thực, hoặc các khoản thanh toán bị treo hơn 24 giờ | Mở hàng tương ứng và nhấp vào **Configure**; đối với các khoản thanh toán bị treo, hãy mở **Gateway events** và phát lại. | | Khách hàng đã thanh toán nhưng số dư không thay đổi | Webhook không gửi đến được | Kiểm tra URL webhook trên tab của kênh, sau đó phát lại sự kiện trong **Gateway events**. | | Máy chủ phản hồi `method_disabled` | Nút gạt đang tắt | Bật nút gạt trong **Fees & limits** và lưu lại. | | Nút gạt USDT bị mờ | Địa chỉ nạp tiền chưa được xác minh | Nhấp vào **Test & verify address** trên tab USDT. | --- # Stripe > **Vị trí trong admin:** Finance › Payment channels › Stripe (`/payments/stripe`). Bật tắt và phí: Finance › Payment channels › Fees & limits (`/payments/fees`). ## Chức năng {#what-it-does} Stripe xử lý thanh toán qua thẻ để nạp tiền vào ví. Với cùng một tài khoản, bạn cũng có thể cung cấp **Apple Pay**, **Google Pay**, **Link** và **Alipay**, đồng thời cho phép khách hàng **lưu thẻ** để [nạp tiền tự động](https://nexcmp.com/vi/docs/billing/auto-top-up/). Hãy sử dụng kênh này làm kênh chính cho khách hàng quốc tế. ## Yêu cầu {#requirements} | Hạng mục | Yêu cầu | |---|---| | Tài khoản Stripe | Một tài khoản Stripe có thể chấp nhận thanh toán bằng **USD**. Alipay được tính phí bằng JPY và cần được Stripe kích hoạt cho tài khoản của bạn. | | Khóa API | Một secret key (`sk_live_...` hoặc `sk_test_...`) và một publishable key (`pk_live_...` hoặc `pk_test_...`). Biểu mẫu chỉ chấp nhận các khóa có tiền tố này. | | Mạng | Bảng điều khiển của bạn phải có thể truy cập được qua HTTPS từ Internet (Stripe gọi webhook) và phải kết nối được tới `api.stripe.com` qua cổng 443. | | Domain (chỉ dành cho ví điện tử) | Domain phía khách hàng phải phục vụ `/.well-known/apple-developer-merchantid-domain-association` — NexCMP sẽ tự động xử lý việc này cho bạn. | | Thành phần phụ thuộc | Không có. | ::: info Tài khoản Stripe dùng chung NexCMP chỉ xử lý các sự kiện webhook cho các khoản thanh toán do chính nó tạo ra, vì vậy bạn có thể sử dụng một tài khoản Stripe đang phục vụ cho cả ứng dụng khác. ::: ## Chuẩn bị hạ tầng {#prepare-the-infrastructure} Về phía Stripe: 1. Đăng nhập vào [Stripe Dashboard](https://dashboard.stripe.com). Bật hoặc tắt **Test mode** để quyết định bạn đang chạy thử nghiệm hay đưa vào hoạt động chính thức. Khóa của chế độ này không bao giờ hoạt động với chế độ kia. 2. Mở **Developers › API keys**. Sao chép **Publishable key**, sau đó hiện và sao chép **Secret key**. Hãy bảo mật secret key. 3. (Tùy chọn) Mở **Settings › Payment methods** và kích hoạt **Alipay** nếu bạn muốn cung cấp phương thức này. 4. Bạn **không** cần phải tạo webhook thủ công — NexCMP có thể tạo tự động cho bạn (xem bước 5 bên dưới). Nếu muốn tạo thủ công, hãy tạo một endpoint trong **Developers › Webhooks** với URL và các sự kiện được liệt kê trong [Webhook](#webhook). ## Kết nối trong NexCMP {#connect-in-nexcmp} 1. Mở **Finance › Payment channels › Stripe** (`/payments/stripe`). 2. Trong thẻ **API keys**, chọn **Mode** (`live` hoặc `test`), dán **Secret key** và **Publishable key**. 3. Nhấp vào **Save**. Các khóa được ghi vào tệp cấu hình trên máy chủ mà chỉ tài khoản dịch vụ của NexCMP mới có quyền đọc. Chúng không bao giờ được gửi ngược lại trình duyệt; sau đó trang sẽ chỉ hiển thị 4 ký tự cuối. 4. Nhấp vào **Check**. Hộp thoại sẽ báo cáo kết nối, chế độ, số dư khả dụng và đang chờ xử lý, ID tài khoản, trạng thái bật tính phí, sự tồn tại của webhook và tính khả dụng của Alipay. Dòng màu đỏ biểu thị phần đó cần được xử lý. 5. Trong thẻ **Webhook**, nhấp vào **Create webhook** và xác nhận. NexCMP sẽ yêu cầu Stripe tạo endpoint với đầy đủ các sự kiện cần thiết và tự động điền **Webhook signing secret** (`whsec_...`). URL được điền sẵn trong trường này là `https:///v1/billing/stripe/webhook`, ví dụ `https://cloud.example.com/v1/billing/stripe/webhook`. 6. Mở **Fees & limits** (`/payments/fees`), giữ bật **Card (Stripe)**, đặt **Stripe fee %** và **Stripe fixed fee (cents)** theo mức phí thực tế của bạn, rồi nhấp vào **Save channels & fees**. Xem [Payment channels](https://nexcmp.com/vi/docs/billing/payment-channels/#switches-and-fees-fees-limits). ![Trang Stripe với mode, secret key và publishable key được điền các giá trị mẫu](https://nexcmp.com/vi/docs/images/billing/stripe-01-keys.webp) ### Webhook {#webhook} Biểu ngữ màu đỏ "Missing webhook_secret" sẽ tiếp tục hiển thị cho đến khi signing secret được lưu. Nếu không có nó, các khoản nạp tiền qua Stripe sẽ **không được ghi nhận**, mặc dù Stripe đã trừ tiền. | Hạng mục | Giá trị | |---|---| | URL | `https:///v1/billing/stripe/webhook` | | Sự kiện | `checkout.session.completed`, `payment_intent.succeeded`, `payment_intent.payment_failed`, `charge.refunded`, `charge.dispute.created`, `charge.dispute.closed`, `radar.early_fraud_warning.created`, `refund.updated`, `refund.failed` | | Chữ ký | Header `Stripe-Signature` của Stripe, HMAC-SHA256, dung sai 300 giây. Các yêu cầu có chữ ký không hợp lệ sẽ nhận mã HTTP 400. | | Idempotency | Mỗi event ID chỉ được lưu một lần; việc gửi lại không bao giờ cộng tiền hai lần. | Nếu bạn đã nâng cấp từ một bản phát hành đăng ký ít sự kiện hơn, hãy nhấp lại vào **Create webhook** — endpoint cũ vẫn được giữ lại, vì vậy hãy xóa nó thủ công trong Stripe Dashboard sau đó. Các hàng **24h events** và **Latest event** trong thẻ Webhook cho bạn biết liệu Stripe có đang kết nối được tới panel hay không. Các sự kiện riêng lẻ được liệt kê trong **Payment channels › Gateway events** (`/payments/events`, tab Stripe), nơi bạn có thể xem từng sự kiện (**Payload**) hoặc phát lại (**Replay**). ### Apple Pay, Google Pay và Link {#apple-pay-google-pay-and-link} 1. Trong thẻ **Wallets (Apple Pay · Google Pay · Link) & Alipay**, trường **Customer app Domain registered with Stripe** được điền sẵn hostname của trang web bạn (ví dụ: `cloud.example.com`). 2. Nhấp vào **Register / verify domain** và xác nhận. NexCMP sẽ đăng ký domain trong payment method domains của Stripe và yêu cầu Stripe xác thực. 3. Kết quả sẽ hiển thị trạng thái của **Apple Pay**, **Google Pay** và **Link**. Apple Pay chỉ hiển thị khi trạng thái là `active`. 4. Trong **Fees & limits**, hãy bật **Apple Pay · Google Pay · Link**. ![Thẻ Wallet hiển thị domain đã đăng ký cùng trạng thái của Apple Pay, Google Pay và Link](https://nexcmp.com/vi/docs/images/billing/stripe-03-wallets.webp) ::: tip Apple Pay vẫn không hoạt động Apple Pay yêu cầu file domain-association phải phản hồi HTTP 200 trên public domain của bạn. Nếu bạn đặt Cloudflare hoặc proxy khác phía trước, đừng chặn `/.well-known/`. ::: ### Alipay {#alipay} Alipay là tùy chọn. Kích hoạt tính năng này trong **Stripe Dashboard › Settings › Payment methods**, nhấp vào **Check** và đợi cho đến khi hộp thoại hiển thị Alipay đã khả dụng, sau đó bật **Alipay (Stripe, JPY display)** trong **Fees & limits**. Thiết lập **Alipay fee %**, **Alipay fixed fee**, tỷ giá **¥/USD rate** (50–500) và **FX spread %** (0–20). Cập nhật tỷ giá ¥/USD thường xuyên; trang sẽ cảnh báo khi tỷ giá này cũ hơn 7 ngày. ## Kiểm tra {#verify} 1. Trong chế độ test mode, hãy đăng nhập vào portal với tư cách khách hàng thử nghiệm, mở **Billing**, nhấp vào **Deposit**, chọn **Card** và thanh toán số tiền tối thiểu bằng thẻ test của Stripe `4242 4242 4242 4242` (ngày bất kỳ trong tương lai, CVC bất kỳ). 2. Số dư sẽ tăng lên trong vài giây và khoản thanh toán sẽ xuất hiện trong **Finance › Billing › Top-ups** với trạng thái *Completed*. 3. Mở **Payment channels › Gateway events › Stripe**: bạn sẽ thấy `checkout.session.completed` hoặc `payment_intent.succeeded` kèm theo thời gian đã xử lý. 4. Quay lại trang Stripe, giá trị **24h events** sẽ lớn hơn 0. Trước khi đưa vào hoạt động chính thức, hãy chuyển **Mode** sang `live`, dán các live key và nhấp lại vào **Create webhook** (webhook của chế độ test và live là riêng biệt). ## Hạn mức & lưu ý {#limits-notes} - **Số tiền và đơn vị tiền tệ.** Ví được tính bằng USD. Các khoản thanh toán bằng thẻ, ví và link được tính phí bằng USD; Alipay hiển thị cho khách hàng bằng JPY và được quy đổi theo tỷ giá của bạn. - **Phí.** Phí thực tế của Stripe không được tự động đọc lại; phần trăm phí bạn thiết lập sẽ quyết định những gì khách hàng nhìn thấy và số tiền được cộng vào ví. Chọn **Customer pays top-up fee** trong *Fees & limits* để tính thêm phí này. - **Thẻ đã lưu.** Khi khách hàng tích chọn *Save card for auto top-up*, thẻ sẽ được lưu tại Stripe, không phải trên máy chủ của bạn. Xem [Saved payment methods](https://nexcmp.com/vi/docs/billing/saved-payment-methods/). - **Hoàn tiền.** Hoàn tiền về thẻ là quy trình gồm hai bước: quản trị viên tạo yêu cầu hoàn tiền cho một khoản thanh toán đã hoàn tất (**Finance › Billing › Top-ups**, thao tác hoàn tiền trên giao dịch) và sau đó phê duyệt yêu cầu đó trong **Finance › Payouts › Card refunds** (`/billing/payouts`). Hoàn tiền Alipay là bất đồng bộ; nếu thất bại (`refund.failed`), số tiền tạm giữ sẽ được hoàn lại vào ví. - **Tranh chấp.** Khi xảy ra `charge.dispute.created`, NexCMP sẽ khóa tài khoản của khách hàng, tạm dừng các dịch vụ trả trước của họ (không có gì bị xóa) và gửi cảnh báo tới quản trị viên. Nếu bạn thắng (`charge.dispute.closed`), số tiền sẽ được cộng lại vào ví. - **Thanh toán đang chờ.** Nếu webhook không bao giờ đến, NexCMP sẽ tự kiểm tra các khoản thanh toán ở trạng thái chờ quá 10 phút với Stripe và hoàn tất chúng. Các khoản thanh toán cũ hơn 7 ngày sẽ bị bỏ qua. - **Resellers** có thể kết nối tài khoản Stripe của riêng họ (webhook `https:///v1/billing/stripe/webhook/r/`); xem [Resellers](https://nexcmp.com/vi/docs/customers/resellers/). ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | "Secret key phải bắt đầu bằng sk_live_/sk_test_" | Dán sai khóa | Dán secret key từ **Developers › API keys**. | | "Secret key không khớp với chế độ live/test" | Chế độ và khóa không khớp nhau | Đảm bảo **Mode** khớp với tiền tố của khóa. | | "Publishable key phải bắt đầu bằng pk_" | Sai khóa | Sử dụng publishable key. | | Kiểm tra báo kết nối thất bại | Sai khóa, khóa đã bị thu hồi hoặc máy chủ không thể kết nối tới `api.stripe.com` | Dán lại khóa; kiểm tra bằng `curl -I https://api.stripe.com` từ máy chủ. | | Banner màu đỏ "Missing webhook_secret" | Signing secret chưa được lưu | Nhấp vào **Create webhook** hoặc dán secret `whsec_...` từ Stripe Dashboard và **Save**. | | Đã trừ tiền nhưng số dư không thay đổi | Webhook không được chuyển đến hoặc chữ ký không hợp lệ | Kiểm tra URL có kết thúc bằng `/v1/billing/stripe/webhook` hay không, secret có khớp với endpoint không, và gửi lại sự kiện trong **Gateway events**. Trên Stripe, hãy mở endpoint và kiểm tra các lần gửi (HTTP 400 nghĩa là sai signing secret). | | "Create webhook" thất bại | URL không phải HTTPS hoặc không thể truy cập | Sử dụng tên miền `https://` công khai của bạn. | | Trạng thái Apple Pay không hoạt động | Tên miền chưa được xác thực | Nhấp lại vào **Register / verify domain** sau khi tệp liên kết tên miền trả về mã 200. | | Alipay không khả dụng trong hộp thoại Check | Chưa được kích hoạt trên Stripe | Kích hoạt phương thức này trên Stripe Dashboard, sau đó nhấp vào **Check**. | | Khách hàng không thấy biểu mẫu thẻ | **Card (Stripe)** đang tắt hoặc thiếu secret key | Bật tùy chọn này trong **Fees & limits** và lưu các khóa. | --- # PayPal > **Vị trí trong admin:** Finance › Payment channels › PayPal (`/payments/paypal`). Công tắc bật/tắt và phí nằm trong Finance › Payment channels › Fees & limits (`/payments/fees`). ## Chức năng {#what-it-does} Cho phép khách hàng nạp tiền vào ví USD bằng số dư PayPal, tài khoản ngân hàng hoặc thẻ liên kết với PayPal. Khách hàng cũng có thể cho phép NexCMP lưu tài khoản PayPal để [nạp tiền tự động](https://nexcmp.com/vi/docs/billing/auto-top-up/). Sử dụng song song với [Stripe](https://nexcmp.com/vi/docs/billing/stripe/) cho những khách hàng thích dùng PayPal. ## Yêu cầu {#requirements} | Hạng mục | Yêu cầu | |---|---| | Tài khoản PayPal | Tài khoản PayPal **Business** có thể nhận USD. | | REST app | Một REST app trong PayPal Developer Dashboard (**Apps & Credentials**) cung cấp **Client ID** và **Client secret**. Sử dụng tab **Sandbox** để kiểm thử, **Live** cho môi trường production. | | Mạng | HTTPS có thể truy cập được từ Internet (PayPal gọi webhook) và quyền truy cập chiều đi tới `api-m.paypal.com` (live) hoặc `api-m.sandbox.paypal.com` (sandbox), cổng 443. | | Quyền hạn | REST app cần có các quyền refund và webhooks. Hộp thoại **Check** sẽ hiển thị xem cả hai scope này đã có hay chưa. | | Thành phần phụ thuộc | Không có. | ## Chuẩn bị hạ tầng {#prepare-the-infrastructure} 1. Đăng nhập vào [developer.paypal.com](https://developer.paypal.com) bằng tài khoản Business của bạn và mở **Apps & Credentials**. 2. Chọn **Sandbox** (thử nghiệm) hoặc **Live**, sau đó nhấn **Create App**. Đặt tên cho ứng dụng, ví dụ "NexCMP". 3. Sao chép **Client ID** và **Secret** của ứng dụng. 4. Để thử nghiệm, hãy vào **Testing Tools › Sandbox Accounts** để tìm hoặc tạo một tài khoản sandbox *Personal* (người mua). 5. Bạn không cần tự tạo webhook; NexCMP sẽ tạo webhook bằng nút **Create webhook**. ## Kết nối trong NexCMP {#connect-in-nexcmp} 1. Mở **Finance › Payment channels › PayPal** (`/payments/paypal`). 2. Trong **API keys**, chọn **Mode**: `live` (tiền thật, `api-m.paypal.com`) hoặc `sandbox` (`api-m.sandbox.paypal.com`). 3. Dán **Client ID** (tối thiểu 20 ký tự) và **Client secret**. 4. Nhấp **Check**. Thao tác này sẽ kiểm tra thông tin xác thực bạn đã nhập (không bắt buộc phải lưu) và báo cáo kết nối, App ID, chế độ hoạt động, xem các scope refund và webhooks có hiện diện hay không cũng như thời hạn hiệu lực của token. 5. Nhấp **Save**. 6. Trong thẻ **Webhook**, hãy xác nhận URL là `https:///v1/billing/paypal/webhook` (phải là `https`), sau đó nhấp **Create webhook** và xác nhận. NexCMP sẽ yêu cầu PayPal tạo hoặc cập nhật webhook với 11 sự kiện và lưu **Webhook ID** trả về. Nút này sử dụng các khóa **đã lưu** — hãy lưu trước nếu bạn vừa chỉnh sửa chúng. 7. Nhấp **Check** lại: dòng **Webhook** sẽ hiển thị "exists, 11 events". 8. Mở **Fees & limits**, bật **PayPal**, đặt **PayPal fee %** (mặc định 4.4) và **PayPal fixed fee (cents)** (mặc định 30) theo biểu phí của bạn rồi nhấp **Save channels & fees**. ![Trang PayPal ở chế độ sandbox với thông tin xác thực mẫu đã nhập](https://nexcmp.com/vi/docs/images/billing/paypal-01-keys.webp) ### Sự kiện webhook {#webhook-events} NexCMP đăng ký 11 sự kiện này: `CHECKOUT.ORDER.APPROVED`, `PAYMENT.CAPTURE.COMPLETED`, `PAYMENT.CAPTURE.PENDING`, `PAYMENT.CAPTURE.DECLINED`, `PAYMENT.CAPTURE.REFUNDED`, `PAYMENT.CAPTURE.REVERSED`, `CUSTOMER.DISPUTE.CREATED`, `CUSTOMER.DISPUTE.UPDATED`, `CUSTOMER.DISPUTE.RESOLVED`, `RISK.DISPUTE.CREATED`, `CHECKOUT.PAYMENT-APPROVAL.REVERSED`. Mỗi webhook đều được xác minh bằng cách gọi API xác thực chữ ký của PayPal, được lưu một lần và xử lý theo cơ chế idempotent. NexCMP không bao giờ tin cậy số tiền trong nội dung webhook: trước khi ghi có một capture, hệ thống sẽ lấy dữ liệu capture từ PayPal. ## Kiểm tra {#verify} 1. Giữ **Mode** ở `sandbox`. Trong portal, mở **Billing › Deposit**, chọn **PayPal**, nhấp **Continue on PayPal** (hoặc nút PayPal) và đăng nhập bằng tài khoản người mua sandbox. 2. Phê duyệt thanh toán. Bạn sẽ quay lại portal, số dư tăng lên và khoản thanh toán xuất hiện dưới **Finance › Billing › Top-ups** với trạng thái *Completed*. 3. Mở **Payment channels › Gateway events › PayPal & USDT**: sự kiện `PAYMENT.CAPTURE.COMPLETED` sẽ được liệt kê. 4. Khi mọi thứ hoạt động bình thường, hãy chuyển **Mode** sang `live`, nhập thông tin xác thực live, nhấp **Save**, sau đó nhấp **Create webhook** lại (webhook sandbox và live tách biệt nhau). ## Hạn mức & lưu ý {#limits-notes} - **Cách khoản thanh toán hoàn tất.** Đơn hàng được tạo bằng USD; sau khi khách hàng phê duyệt, **máy chủ** sẽ capture đơn hàng (với request ID theo cơ chế idempotent) và ghi có vào ví đúng một lần. Webhook cùng tác vụ đối soát chạy mỗi 10 phút là các lớp dự phòng an toàn nếu khách hàng đóng trình duyệt. - **Đơn hàng chờ xử lý và đơn hàng bị bỏ dở.** Một đơn hàng có thể ở trạng thái mở trong 12 giờ. Khách hàng chỉ có thể có tối đa 5 đơn hàng đang chờ xử lý (máy chủ sẽ phản hồi `too_many_pending`, HTTP 429). Đơn hàng vẫn chưa được capture sau 24 giờ sẽ bị đánh dấu thất bại. - **Chưa cấu hình webhook.** Bảng điều khiển sẽ trả về HTTP 503 cho mọi webhook của PayPal cho đến khi Webhook ID được lưu. Các khoản capture thực hiện qua portal và quá trình đối soát mỗi 10 phút vẫn ghi có vào ví, nhưng không có thông tin nào mà PayPal báo cáo qua webhook (tranh chấp, hoàn tiền, capture muộn) được áp dụng — hãy nhấp **Create webhook**. - **Tài khoản PayPal đã lưu.** Khi khách hàng chọn lưu PayPal (hoặc hoàn tất lần nạp tiền đầu tiên, thao tác này sẽ bật [nạp tiền tự động](https://nexcmp.com/vi/docs/billing/auto-top-up/)), PayPal sẽ lưu payment token trong vault của họ. NexCMP chỉ lưu một mã định danh và e-mail PayPal. Xem [Phương thức thanh toán đã lưu](https://nexcmp.com/vi/docs/billing/saved-payment-methods/). - **Hoàn tiền và tranh chấp** được xử lý tương tự Stripe: các yêu cầu hoàn tiền được phê duyệt tại **Finance › Payouts › Card refunds**; tranh chấp sẽ khóa tài khoản khách hàng và dừng các dịch vụ trả trước của họ cho đến khi bạn giải quyết xong. - **Phí.** Phí của PayPal không được đọc ngược lại; tỷ lệ phần trăm và phí cố định bạn cấu hình sẽ quyết định số tiền khách hàng nhìn thấy và số tiền được ghi có. Mức phí thực tế tùy thuộc vào quốc gia của bạn (biểu mẫu gợi ý 4.4 % cho Việt Nam và 3.49 % cho Hoa Kỳ). ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | "Client ID quá ngắn" | Đã dán ít hơn 20 ký tự | Sao chép toàn bộ Client ID. | | "URL Webhook phải là https" | URL được nhập với `http://` | Sử dụng tên miền `https://` công khai của bạn. | | Check báo lỗi kết nối | Sai chế độ (dùng live key trong sandbox hoặc ngược lại), sai secret, không có quyền truy cập outbound | Khớp **Mode** với loại key; kiểm tra `curl -I https://api-m.paypal.com` từ server. | | Scope refund / webhooks hiển thị "no" | REST app thiếu các tính năng này | Bật các tính năng này trên app trong PayPal Developer Dashboard. | | Banner "Đã thiết lập PayPal key, KHÔNG CÓ webhook" | Thiếu Webhook ID | Nhấp vào **Create webhook**. | | "Không tìm thấy Webhook" trong Check | Webhook đã bị xóa trên PayPal hoặc thuộc về app khác | Nhấp vào **Create webhook** một lần nữa. | | Khách hàng nhận được thông báo PayPal từ chối thanh toán | PayPal đã từ chối nguồn tiền đó | Yêu cầu khách hàng chọn nguồn thanh toán khác. | | Khách hàng thấy "Too many pending requests" | Có 5 đơn hàng đang mở | Chờ các đơn hàng hết hạn hoặc hoàn tất chúng. | | Thiếu nút PayPal | PayPal đang tắt trong **Fees & limits** hoặc chưa được cấu hình | Bật lên và lưu thông tin xác thực. | --- # USDT (Binance) {#usdt-binance} > **Vị trí trong admin:** Finance › Payment channels › USDT (`/payments/usdt`). Bật/tắt và phí: Finance › Payment channels › Fees & limits (`/payments/fees`). Tiền nạp chưa khớp: Finance › Payment channels › Gateway events › PayPal & USDT (`/payments/events?tab=gateways`). ## Chức năng {#what-it-does} Khách hàng gửi USDT vào **địa chỉ nạp Binance của bạn**; NexCMP sẽ đọc lịch sử nạp thông qua Binance API key **chỉ đọc** và cộng tiền vào ví khi khoản nạp khớp với một yêu cầu đang mở. Bạn không phải chịu thêm phí xử lý thanh toán nào ngoài phí của Binance, và NexCMP không bao giờ lưu trữ private key. ## Yêu cầu {#requirements} | Hạng mục | Yêu cầu | |---|---| | Tài khoản Binance | Tài khoản Binance đã xác minh và đã bật nạp USDT trên mạng bạn chọn. | | API key | Một Binance API key chỉ có quyền **Enable Reading**. Enable Withdrawals, Internal Transfer và Spot/Margin Trading phải ở trạng thái **off**. | | Giới hạn IP | Rất khuyến nghị: giới hạn key theo IP outbound của server (hộp thoại **Test & verify address** có hiển thị IP này). | | Mạng | HTTPS outbound tới `api.binance.com`. Không cần mở cổng inbound. | | Các mạng được hỗ trợ | `TRX` (Tron, TRC20), `BSC` (BNB Smart Chain, BEP20), `SOL` (Solana), `ETH` (Ethereum, ERC20). Coin được cố định là USDT. | | Thành phần phụ thuộc | Không có. | ::: warning Chọn mạng một lần duy nhất Khách hàng gửi nhầm mạng sẽ bị mất tiền. Hãy chọn mạng có phí thấp mà các sàn giao dịch của khách hàng hỗ trợ (TRX và BSC là các lựa chọn phổ biến) và không nên thay đổi thường xuyên. ::: ## Chuẩn bị hạ tầng {#prepare-the-infrastructure} 1. Trên Binance, mở **Account › API Management** và tạo một API key mới (do hệ thống tạo). Đặt cho nó một nhãn như "NexCMP". 2. Chỉnh sửa quyền: chỉ để chọn **Enable Reading**. Không bật quyền rút tiền, chuyển khoản hoặc giao dịch. 3. Tại mục **Restrict access to trusted IPs only**, thêm địa chỉ IP public của máy chủ NexCMP của bạn. Nếu bạn chưa biết địa chỉ này, hãy tạo key mà không giới hạn IP, chạy kiểm tra lần đầu trong NexCMP (hệ thống sẽ hiển thị outbound IP), sau đó thêm IP vào. 4. Sao chép **API key** và **Secret key** (khóa bí mật chỉ hiển thị một lần duy nhất). 5. Mở **Wallet › Deposit › Crypto**, chọn **USDT** cùng **mạng** bạn sẽ sử dụng, rồi sao chép **địa chỉ nạp tiền** (ví dụ: địa chỉ `T...` trên TRX hoặc `0x...` trên BSC/ETH). ## Kết nối trong NexCMP {#connect-in-nexcmp} 1. Mở **Finance › Payment channels › USDT** (`/payments/usdt`). 2. Tại mục **API key (Binance › API Management)**, dán **API key** và **API secret**. Cả hai đều phải được nhập cùng nhau. 3. Tại **Deposit address**, chọn **Network** và dán **địa chỉ nạp USDT trên mạng đã chọn**. Định dạng sẽ được kiểm tra theo từng mạng (`T` + 33 ký tự cho TRX, `0x` + 40 ký tự hex cho BSC và ETH, base58 cho SOL). 4. Nhấp vào **Save**. Việc thay đổi địa chỉ hoặc mạng sẽ đặt lại trạng thái xác minh và tạm dừng kênh thanh toán cho đến khi bạn xác minh lại; trang sẽ yêu cầu bạn xác nhận. 5. Nhấp vào **Test & verify address**. (Các thay đổi chưa lưu sẽ bị từ chối — quá trình kiểm tra chạy trên cấu hình đã lưu.) Hộp thoại sẽ hiển thị: - các quyền của key (reading, withdrawals, internal transfer, trading, giới hạn IP) — cảnh báo màu đỏ cho các quyền nguy hiểm; - outbound IP của máy chủ (để nhập vào Binance); - mạng (nạp tiền đang mở hay đóng, số xác nhận yêu cầu, dust); - địa chỉ mà Binance cấp cho mạng đó và liệu nó có **khớp** với địa chỉ của bạn hay không. 6. Khi địa chỉ khớp, NexCMP sẽ ghi lại thời gian xác minh. Chỉ khi đó bạn mới có thể mở **Fees & limits**, bật **USDT (Binance)**, kiểm tra **USDT fee %** (mặc định 1) cùng **USDT request expires after (mins)** (5–180, mặc định 30), rồi nhấp vào **Save channels & fees**. ## Cơ chế khớp thanh toán {#how-a-payment-is-matched} 1. Khách hàng nhập số tiền trong **Billing › Deposit › USDT** và nhấp vào **Get deposit address**. 2. NexCMP tạo một yêu cầu và hiển thị địa chỉ, mạng cùng **số tiền chính xác** với 6 chữ số thập phân — ví dụ: `19.173742`. Bốn chữ số thập phân cuối cùng là một nonce ngẫu nhiên giúp số tiền trở thành duy nhất cho yêu cầu đó. 3. Khách hàng phải gửi **chính xác** số tiền đó trên đúng mạng đó. Khoản thanh toán không khớp (làm tròn số tiền, sai mạng) sẽ không thể tự động gán. 4. Cứ mỗi 60 giây, NexCMP sẽ đọc các giao dịch nạp trên Binance trong 24 giờ qua. Giao dịch nạp trùng khớp sẽ chuyển yêu cầu sang trạng thái *confirming* và sau khi Binance có đủ số xác nhận cần thiết, tiền sẽ được cộng vào ví. Yêu cầu đã ghi nhận tiền sẽ không bao giờ hết hạn trong khi đang chờ xác nhận. 5. Yêu cầu không được thanh toán trong thời gian hiệu lực (mặc định 30 phút) sẽ được đánh dấu là hết hạn. ## Kiểm tra {#verify} 1. Sau khi địa chỉ đã được xác minh và USDT đã được bật, hãy đăng nhập với tư cách khách hàng thử nghiệm và tạo yêu cầu nạp một khoản nhỏ (mức nạp tối thiểu). 2. Gửi chính xác số tiền đó từ một ví hoặc sàn giao dịch khác. Chờ trong vài phút. 3. Portal hiển thị *Transfer seen — confirming*, sau đó là *USDT received — balance updated*. 4. Trang USDT hiển thị thời gian **Last poll** gần đây và **Unmatched** ở mức 0. ## Hạn mức & lưu ý {#limits-notes} - **Tỷ giá.** 1 USDT = 1.00 USD. Mức phí trong **USDT fee %** được hiển thị cho khách hàng và được trừ vào hoặc cộng thêm vào số tiền tùy thuộc vào **Customer pays top-up fee**. - **Không hoàn tiền.** Các khoản thanh toán USDT không bao giờ được NexCMP hoàn lại về nguồn (HTTP 409 `usdt_no_refund`). Hãy hoàn tiền thủ công ngoài hệ thống nếu cần. - **Giới hạn yêu cầu chờ.** Khách hàng có số lượng yêu cầu đang mở bị giới hạn; vượt quá mức này máy chủ sẽ trả về `too_many_pending` (HTTP 429). - **Resellers** có thể dùng tài khoản Binance riêng; xem [Resellers](https://nexcmp.com/vi/docs/customers/resellers/). - **Nếu bạn dùng chung tài khoản Binance** với hệ thống khác, hãy gán cho mỗi hệ thống một mạng khác nhau để hai poller không bao giờ nhìn thấy cùng một khoản nạp. ### Khoản nạp không khớp {#unmatched-deposits} Một khoản nạp không khớp với bất kỳ yêu cầu nào (sai số tiền, sai mạng, yêu cầu đã hết hạn) sẽ tạo một sự kiện `deposit.unmatched` và cảnh báo cho quản trị viên. Mở **Payment channels › Gateway events › PayPal & USDT**, tìm sự kiện, kiểm tra giao dịch trên Binance và nhấp vào thao tác gán để cộng tiền cho đúng khách hàng. Bộ đếm **Unmatched** trên trang USDT và trên trang tổng quan kênh thanh toán sau đó sẽ giảm về 0. ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | "API key và secret phải được nhập cùng nhau" | Chỉ điền một trường | Điền cả hai. | | "Địa chỉ không đúng định dạng của mạng ..." | Địa chỉ không khớp với mạng đã chọn | Sao chép lại từ Binance cho đúng mạng đó. | | "Thay đổi chưa lưu — Hãy Save trước rồi mới Test" | Kiểm tra chỉ chạy trên các cài đặt đã lưu | Nhấp vào **Save**, sau đó kiểm tra. | | Cảnh báo "key có Enable Withdrawals" | Thừa quyền | Gỡ bỏ quyền này trong Binance API Management. | | Cảnh báo "key chưa giới hạn IP" | `ipRestrict` đang tắt | Thêm IP outbound của máy chủ hiển thị trong hộp thoại. | | Cảnh báo "key thiếu quyền Enable Reading" | Thiếu quyền | Bật Enable Reading. | | Cảnh báo "Binance đã tắt nạp USDT trên mạng này" | Mạng bị tạm dừng | Chọn mạng khác hoặc chờ. | | "NGUY HIỂM: địa chỉ được cấu hình khác với địa chỉ Binance cung cấp" | Sai địa chỉ hoặc mạng | Sao chép lại địa chỉ từ Binance cho mạng đó. | | Công tắc USDT bị mờ trong Fees & limits | Địa chỉ chưa được xác minh | Chạy **Test & verify address** cho đến khi khớp. | | Khách hàng đã thanh toán nhưng chưa được cộng tiền | Số tiền bị làm tròn hoặc sai mạng | Tìm sự kiện trong Gateway events và gán thủ công. | | Đã ghi nhận khoản nạp nhưng thời gian chờ lâu | Chưa đủ số lượt xác nhận | Hãy chờ; yêu cầu sẽ không hết hạn trong khi đang xác nhận. | --- # Chuyển khoản ngân hàng (Việt Nam) {#bank-transfer-vietnam} > **Vị trí trong trang quản trị:** Finance › Payment channels › VN bank transfer (`/payments/bank`). Tỷ giá: Finance › Payment channels › Exchange rates (`/payments/fx`). ## Chức năng {#what-it-does} Cho phép khách hàng nạp tiền vào ví USD bằng hình thức chuyển khoản ngân hàng thông thường bằng đồng Việt Nam. NexCMP hiển thị mã VietQR, thông tin tài khoản và **transfer memo** duy nhất; [Sepay](https://sepay.vn) theo dõi tài khoản ngân hàng của bạn và gọi webhook khi có tiền vào, rồi NexCMP sẽ cộng tiền vào ví. Hãy sử dụng phương thức này nếu bạn bán dịch vụ cho khách hàng tại Việt Nam. ::: info Chỉ hiển thị trong giao diện tiếng Việt Tùy chọn ngân hàng VN chỉ hiển thị cho khách hàng khi portal đang ở ngôn ngữ **Vietnamese**. Khách hàng sử dụng bất kỳ ngôn ngữ nào khác sẽ không bao giờ nhìn thấy tùy chọn này. ::: ## Yêu cầu {#requirements} | Hạng mục | Yêu cầu | |---|---| | Tài khoản ngân hàng | Một tài khoản ngân hàng Việt Nam (hoặc tài khoản ảo Sepay, **VA**) được kết nối với tài khoản Sepay tại [my.sepay.vn](https://my.sepay.vn). | | Sepay | Tài khoản Sepay đã bật tính năng tích hợp webhook. | | Tỷ giá hối đoái | Cần phải có tỷ giá USD sang VND: hãy cập nhật tỷ giá này trong **Exchange rates** trước. Nếu không có tỷ giá, kênh thanh toán sẽ phản hồi `fx_unavailable` và khách hàng không thể bắt đầu giao dịch chuyển khoản. | | Mạng | Bảng điều khiển của bạn phải truy cập được qua HTTPS để Sepay có thể gọi `https:///v1/billing/sepay/webhook`. | | Thành phần phụ thuộc | [Tiền tệ và tỷ giá](https://nexcmp.com/vi/docs/catalog/currency-and-exchange-rates/). | ## Chuẩn bị hạ tầng {#prepare-the-infrastructure} Về phía Sepay: 1. Trong [my.sepay.vn](https://my.sepay.vn), hãy kết nối tài khoản ngân hàng của bạn (hoặc tạo VA) và đảm bảo các giao dịch hiển thị bình thường. 2. Quyết định **memo prefix** — 2 đến 5 chữ cái viết hoa, ví dụ `PAY`. NexCMP sẽ tạo memo gồm tiền tố này theo sau là 8 chữ số ngẫu nhiên (ví dụ `PAY48210937`). Tiền tố không được chứa `ORD` và không nên được dùng bởi bất kỳ hệ thống nào khác nhận tiền vào cùng tài khoản đó. 3. Nếu tài khoản Sepay của bạn sử dụng *cấu trúc mã thanh toán*, hãy đăng ký cùng tiền tố đó tại Sepay để hệ thống nhận diện được memo. 4. Hãy tạo webhook sau, khi trang NexCMP đã cung cấp cho bạn URL và key (bước 7 bên dưới). ## Kết nối trong NexCMP {#connect-in-nexcmp} 1. Mở **Finance › Payment channels › Exchange rates** và nhấp vào **Update exchange rates** nếu chưa có tỷ giá nào được lưu. 2. Mở **Finance › Payment channels › VN bank transfer** (`/payments/bank`). 3. Trong **Receiving account**, hãy điền: | Trường | Ví dụ | Quy tắc | |---|---|---| | Ngân hàng | `VCB` Vietcombank | Chọn từ danh sách; mã BIN sẽ tự động điền. | | Số tài khoản | `0123456789` | 4–24 chữ số hoặc chữ cái viết hoa. | | Tài khoản ảo (VA — tùy chọn) | | Nếu được thiết lập, khách hàng sẽ chuyển khoản tới VA và mã QR sẽ hiển thị thông tin này. | | Tên chủ tài khoản | `NGUYEN VAN A` | Không dấu, VIẾT HOA, 2–60 ký tự. | | Tiền tố memo chuyển khoản | `PAY` | 2–5 chữ cái viết hoa, không có `ORD`. | 4. Trong **Webhook authentication**, chọn **Auth method**: **HMAC-SHA256** (khuyên dùng) hoặc **API key**, rồi nhập **Webhook key / HMAC secret** (8–200 ký tự). Bạn có thể tùy chọn nhập **userapi token** từ Sepay; token này chỉ dùng để đối soát các giao dịch chuyển khoản bị mất webhook. 5. Trong **Channel & limits**, hãy thiết lập các giới hạn (giá trị mặc định trong ngoặc đơn): **Min / order** (10,000 VND), **Max / order** (200,000,000 VND), **Order expiry** (120 phút, 15–1440), **Max pending orders / account** (3, 1–10), **Reconcile every** (10 phút) và tùy chọn **Allowed webhook IPs** (phân tách bằng dấu phẩy; để trống nghĩa là IP chỉ được ghi log). 6. Nhấp vào **Save**. Banner màu đỏ "Sepay not configured" sẽ biến mất sau khi số tài khoản, tên, tiền tố và key hợp lệ. 7. Sao chép **Webhook URL to paste into my.sepay.vn** (có dạng `https:///v1/billing/sepay/webhook`) bằng **Copy**. Trong Sepay, mở tích hợp webhook, dán URL, chọn cùng loại xác thực và key, rồi bật sự kiện "money in". 8. Nhấp vào **Test connection**. Sau đó bật **Enable Sepay for clients (main site)** và chọn **Save**. ![Trang chuyển khoản ngân hàng Việt Nam với tài khoản nhận tiền, tiền tố memo và xác thực webhook được điền bằng các giá trị mẫu](https://nexcmp.com/vi/docs/images/billing/bank-transfer-vn-01-config.webp) ![Thẻ Channel and limits với công tắc Sepay được bật và các hạn mức mặc định](https://nexcmp.com/vi/docs/images/billing/bank-transfer-vn-02-limits.webp) ### Bảo mật webhook {#webhook-security} | Phương thức | Dữ liệu Sepay phải gửi | |---|---| | HMAC-SHA256 | Header `X-SePay-Signature: sha256=`, được tính trên `"."`; timestamp có thể chênh lệch tối đa 300 giây. | | API key | Header `Authorization: Apikey `. | Chỉ các header được kiểm tra (không bao giờ kiểm tra body hoặc query string) và phép so sánh diễn ra theo thời gian không đổi (constant-time). Chỉ các giao dịch chuyển tiền đến (`transferType = in`) vào tài khoản hoặc VA đã cấu hình của bạn mới được sử dụng. Mỗi giao dịch Sepay chỉ được lưu một lần, vì vậy webhook gửi lại sẽ không bao giờ cộng tiền hai lần. NexCMP phản hồi `200 {"success":true}` ngay cả khi chủ động bỏ qua một giao dịch, và chỉ trả về HTTP 5xx đối với các lỗi tạm thời để Sepay thử lại. ## Cách khách hàng thanh toán {#how-the-customer-pays} 1. Trong **Billing › Deposit** (giao diện tiếng Việt), khách hàng chọn tùy chọn chuyển khoản ngân hàng Việt Nam và số tiền, sau đó nhấp vào nút tạo giao dịch. 2. NexCMP quy đổi số tiền USD theo tỷ giá đã lưu (bao gồm biên độ và bước làm tròn bạn thiết lập trong **Exchange rates**) và **làm tròn tăng số tiền VND** theo bước làm tròn. 3. Khách hàng nhìn thấy mã QR (VietQR, được tạo cục bộ) kèm số tài khoản, ngân hàng, số tiền và memo. 4. Sau khi chuyển khoản, Sepay gọi webhook, NexCMP cộng `floor(VND received × 100 / rate)` cent. Tỷ giá được khóa khi đơn hàng được tạo; nếu tiền đến sau khi đơn hàng đã hết hạn, tỷ giá cao hơn giữa tỷ giá đã khóa và tỷ giá hiện tại sẽ được áp dụng. 5. Đơn hàng hết hạn sau **Order expiry**; quy trình đối soát chạy mỗi **Reconcile every** phút như một lớp bảo vệ dự phòng (cần userapi token). ## Kiểm tra {#verify} 1. Tạo một đơn hàng thử nghiệm dưới vai trò khách hàng trên giao diện tiếng Việt. Kiểm tra xem số tiền, tài khoản và memo đã chính xác chưa. 2. Chuyển số tiền tối thiểu được phép với chính xác memo. 3. Trong vòng một phút, cổng thông tin sẽ hiển thị khoản nạp đã hoàn tất và số dư ví tăng lên; thẻ **State** trên trang ngân hàng hiển thị thời gian webhook gần nhất. 4. Mở **Finance › Billing › Top-ups** và kiểm tra xem khoản thanh toán có được liệt kê cùng số tiền VND đã nhận hay không. ## Hạn mức & lưu ý {#limits-notes} - **Tối thiểu.** Mức VND tối thiểu mà khách hàng thấy là giá trị lớn hơn giữa **Min / order** và giá trị VND của [mức nạp tối thiểu](https://nexcmp.com/vi/docs/billing/minimum-top-up/). - **Đơn hàng chờ xử lý.** Khách hàng chỉ có thể có tối đa **Max pending orders / account** đơn hàng đang mở (mặc định là 3). - **Trùng memo hai lần.** Chuyển tiền hai lần với cùng một memo sẽ tạo khoản thanh toán hoàn tất thứ hai theo tỷ giá hiện tại. - **Không hoàn tiền tự động** về tài khoản ngân hàng. - **Phí.** Kênh này không có dòng phí cố định trong **Fees & limits**; biên độ tỷ giá là khoản điều chỉnh duy nhất. - **Resellers** có thể định cấu hình tài khoản của riêng họ; URL webhook của họ kết thúc bằng `/v1/billing/sepay/webhook/r/`. ### Giao dịch chuyển tiền chưa khớp {#unmatched-transfers} Tiền đã vào tài khoản nhưng không có memo hợp lệ sẽ xuất hiện trong **Unmatched transactions** ở cuối trang (lọc theo *All channel owners* hoặc *Master*). Kiểm tra mã tham chiếu ngân hàng với khách hàng, sau đó nhấp vào **Assign** và chọn tài khoản. Ví sẽ được cộng tiền theo tỷ giá hiện tại. ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | Banner thông báo "Sepay not configured" | Thiếu hoặc không hợp lệ thông tin ngân hàng, tài khoản, tên chủ tài khoản, tiền tố hoặc khóa | Hoàn tất các thẻ **Receiving account** và **Webhook authentication**. | | Banner thông báo "USD/VND rate blocked" (`fx_unavailable`) | Không có tỷ giá nào được lưu | Chọn **Exchange rates › Update exchange rates**. | | `prefix: 2–5 capital letters, no ORD` | Tiền tố không hợp lệ | Sử dụng 2–5 chữ cái in hoa không có `ORD`. | | Lỗi `account_name` | Có dấu hoặc chữ thường | Sử dụng chữ in HOA không dấu, chữ số, dấu cách, dấu chấm hoặc dấu gạch nối. | | `webhook_secret: 8–200 characters` | Khóa quá ngắn | Sử dụng ít nhất 8 ký tự in được. | | Khách hàng không thấy tùy chọn | Không ở giao diện tiếng Việt, công tắc đang tắt, hoặc chưa có tỷ giá | Kiểm tra ngôn ngữ, công tắc và tỷ giá. | | Khách hàng đã thanh toán nhưng không được cộng tiền | Webhook không tới, nội dung chuyển khoản bị đổi, sai số tiền | Kiểm tra webhook log của SePay; giao dịch chuyển khoản sẽ nằm trong **Unmatched transactions** nếu nội dung chuyển khoản bị sai. | | Webhook trả về 401 hoặc 403 | Phương thức xác thực hoặc khóa không khớp | Sử dụng cùng phương thức và khóa trong SePay và NexCMP. | | Khách hàng thấy "Too many pending requests" | Đã đạt giới hạn đơn hàng đang chờ xử lý | Chờ khách hoàn tất hoặc chờ đơn hết hạn. | --- # Mức nạp tiền tối thiểu {#minimum-top-up} > **Vị trí trong admin:** Finance › Payment channels › Fees & limits (`/payments/fees`), thẻ **Wallet & top-up (Billing › Policy)**. ## Chức năng {#what-it-does} Mọi kênh thanh toán đều từ chối số tiền thấp hơn **mức nạp tối thiểu** hoặc cao hơn **mức nạp tối đa cho mỗi giao dịch**. Các giá trị mặc định là **$10.00** và **$5,000.00**. Hãy sử dụng mức tối thiểu để tránh các khoản thanh toán quá nhỏ có phí cổng thanh toán lớn hơn giá trị thực tế. ## Yêu cầu {#requirements} | Hạng mục | Yêu cầu | |---|---| | Role | Quản trị viên. | | Thành phần phụ thuộc | Không có. | ## Thiết lập hạn mức {#set-the-limits} 1. Mở **Finance › Payment channels › Fees & limits** (`/payments/fees`). 2. Trong thẻ **Wallet & top-up (Billing › Policy)**, chỉnh sửa **Min top-up (USD)** và **Max top-up per transaction (USD)**. 3. Nhấp vào **Save Wallet & top-up**. ![Thẻ Wallet and top-up với mức nạp tối thiểu 10.00 và mức tối đa 5000.00](https://nexcmp.com/vi/docs/images/billing/minimum-top-up-01-limits.webp) | Cài đặt | Mặc định | Khoảng cho phép | Quy tắc | |---|---|---|---| | Min top-up (USD) | $10.00 | $0 đến $10,000 | Phải nhỏ hơn hoặc bằng mức tối đa. | | Mức nạp tối đa mỗi giao dịch (USD) | $5,000.00 | $1 đến $1,000,000 | Phải lớn hơn hoặc bằng mức tối thiểu. | Các giá trị được lưu trữ theo cent (`min_topup_cents`, `max_topup_cents`). ## Nơi áp dụng hạn mức {#where-the-limits-apply} | Vị trí | Hành vi | |---|---| | Thẻ, Apple/Google Pay, Link, Alipay, PayPal, USDT | Các số tiền nằm ngoài phạm vi sẽ bị máy chủ từ chối. Portal sẽ hiển thị "Enter an amount between {min} and {max}". | | Chuyển khoản ngân hàng VN | Số tiền VND phải nằm trong hạn mức của SePay **và** giá trị USD tương ứng (số tiền ví nhận được) phải nằm trong mức tối thiểu và tối đa. Portal sẽ hiển thị giá trị lớn hơn giữa hai mức tối thiểu VND. Xem [Bank transfer (Vietnam)](https://nexcmp.com/vi/docs/billing/bank-transfer-vn/). | | [Automatic top-up](https://nexcmp.com/vi/docs/billing/auto-top-up/) | Mỗi lần trừ tiền tự động đều phải tối thiểu bằng mức tối thiểu và tối đa bằng mức tối đa. Ở chế độ cố định, số tiền của khách hàng phải nằm trong khoảng từ mức tối thiểu đến $1,000. | | Mã nạp tiền ([Vouchers](https://nexcmp.com/vi/docs/billing/promotions/)) | Không bị ảnh hưởng. | | Admin nạp / trừ tiền | Không bị ảnh hưởng. | | Nạp tiền ví đại lý | Mức tối thiểu riêng (`rs_topup_min_cents`, mặc định $20) trong Resellers › Defaults. | ## Các mức sàn liên quan {#related-floors} Mức nạp tối thiểu không phải quy tắc số dư duy nhất. Các quy tắc này nằm trong **Services › Virtual Machines › Policy** (`/vm/policy`): | Quy tắc | Mặc định | Ý nghĩa | |---|---|---| | Số dư tối thiểu (`min_balance_cents`) | $5.00 | Số dư ví tối thiểu khách hàng cần có để tạo VM. | | Quotas | Tắt | Khi bật **Quotas**, việc tạo VM cũng cần số dư đủ trả cho một số giờ chạy VM đó. Xem [Quotas](https://nexcmp.com/vi/docs/billing/quotas/). | ## Kiểm tra {#verify} 1. Trên portal, mở **Billing › Deposit** và nhập số tiền thấp hơn mức tối thiểu một chút. Nút thanh toán sẽ bị vô hiệu hóa và thông báo khoảng tiền hợp lệ xuất hiện. 2. Nhập mức tối thiểu và xác nhận quá trình thanh toán bắt đầu. ## Hạn mức & lưu ý {#limits-notes} - Thay đổi sẽ áp dụng cho các khoản thanh toán mới. Các đơn nạp tiền đã tạo vẫn giữ nguyên số tiền ban đầu. - Gợi ý hiển thị cho khách hàng ("Tối thiểu $10.00, tối đa $5,000.00") và các nút chọn nhanh số tiền sẽ tự động cập nhật theo hạn mức mới. - Nếu bạn hiển thị VND (trang **Exchange rates**), mức tối thiểu sẽ được quy đổi theo tỷ giá đã lưu chỉ để hiển thị; ví tiền và các hạn mức vẫn tính bằng USD. ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | "Mức nạp tối thiểu phải nhỏ hơn hoặc bằng mức tối đa" | Giá trị bị ngược nhau | Hạ mức tối thiểu hoặc tăng mức tối đa. | | Khách hàng không thể thanh toán số tiền nhỏ qua chuyển khoản ngân hàng VN | Mức tối thiểu VND của SePay hoặc mức tối thiểu USD đang cao hơn | Hạ **Min / order** trên trang ngân hàng hoặc hạ mức tối thiểu USD. | | Lỗi máy chủ `invalid_argument` khi nạp tiền | Số tiền nằm ngoài khoảng cho phép | Yêu cầu nhập số tiền nằm trong khoảng hiển thị. | --- # Phương thức thanh toán đã lưu {#saved-payment-methods} > **Vị trí trong portal:** Billing › Settings (`/billing?settings=1`). **Vị trí trong admin:** Customers › List › a customer › Overview (`/customers/`), thẻ **Payment**, hiển thị phương thức đã lưu và lịch sử tự động nạp tiền. ## Chức năng {#what-it-does} Phương thức thanh toán đã lưu cho phép NexCMP trừ tiền khách hàng **khi họ không có mặt**, giúp dịch vụ không bao giờ bị gián đoạn do hết tiền trong ví. Phương thức này chỉ dùng cho [automatic top-up](https://nexcmp.com/vi/docs/billing/auto-top-up/). Có hai loại: **thẻ** lưu tại Stripe (bao gồm thẻ dùng qua Apple Pay, Google Pay hoặc Link khi Stripe trả về thẻ tái sử dụng) và **tài khoản PayPal** lưu trong PayPal vault. ## Yêu cầu {#requirements} | Hạng mục | Yêu cầu | |---|---| | Kênh thanh toán | [Stripe](https://nexcmp.com/vi/docs/billing/stripe/) và/hoặc [PayPal](https://nexcmp.com/vi/docs/billing/paypal/) đã được cấu hình và kích hoạt. | | Trang | Trang chính hoặc trang đại lý có kênh thanh toán do nền tảng thu hộ. Trang đại lý dùng tài khoản Stripe riêng không thể lưu thẻ. | | Khách hàng | Tài khoản khách hàng đã từng nạp tiền bằng thẻ hoặc PayPal. | ## Cách phương thức được lưu {#how-a-method-gets-saved} 1. Khách hàng mở **Billing**, nhấn **Deposit** và thanh toán bằng **Card** hoặc **PayPal**. 2. Giao dịch thanh toán được tạo để có thể tái sử dụng phương thức sau này: Stripe lưu thẻ cùng hồ sơ khách hàng tại Stripe (sử dụng off-session), PayPal lưu token vault. NexCMP chỉ giữ các mã tham chiếu (ID phương thức thanh toán và ID khách hàng của Stripe, hoặc vault ID của PayPal) cùng nhãn hiển thị như `visa •••• 4242` hoặc email PayPal. **Thông tin số thẻ không bao giờ đi qua máy chủ của bạn.** 3. Khi thanh toán hoàn tất, [tự động nạp tiền](https://nexcmp.com/vi/docs/billing/auto-top-up/) sẽ được bật một lần nếu khách hàng chưa từng cài đặt trước đó. Không có hộp kiểm hay thông báo phụ nào trên màn hình. Máy chủ sẽ ghi lại thời gian, địa chỉ IP của khách hàng và phương thức thanh toán làm bằng chứng. 4. Lần tiếp theo, màn hình nạp tiền sẽ hiển thị **Saved card ...** trong menu thả xuống chọn thẻ, và **Saved PayPal ...** cho PayPal. ## Quản lý và xóa {#manage-and-remove} 1. Trên portal, đi đến **Billing** và nhấp vào **Settings**. Bảng điều khiển sẽ hiển thị các phương thức đã lưu (thẻ Stripe và/hoặc PayPal) cùng các tùy chọn tự động nạp tiền. 2. Để xóa thẻ, nhấp vào **Remove card** và xác nhận. Stripe sẽ hủy liên kết thẻ và **tự động nạp tiền sẽ bị tắt**. 3. Để xóa PayPal, nhấp vào **Remove saved PayPal** và xác nhận. ### Giao diện admin {#admin-view} Mở thông tin khách hàng trong **Customers › List**. Thẻ **Payment** trên tab **Overview** hiển thị nhãn các phương thức đã lưu (**Saved cards**), cổng thanh toán dùng để tự động trừ tiền, bằng chứng chấp thuận đã lưu (thời gian, IP, phương thức) và 20 lần thử tự động trừ tiền gần nhất kèm trạng thái và lý do (**Auto top-up history**). ## Kiểm tra {#verify} 1. Dưới vai trò khách hàng thử nghiệm, hãy nạp số tiền tối thiểu bằng thẻ. Sau khi thanh toán hoàn tất, mở **Billing › Settings**: thẻ và công tắc tự động nạp tiền (ở trạng thái bật) sẽ hiển thị. 2. Bắt đầu một lượt nạp tiền khác: menu thả xuống sẽ hiển thị thẻ đã lưu. 3. Trong trang admin, thẻ **Payment** của khách hàng sẽ hiển thị cùng nhãn thẻ đó. ## Hạn mức & lưu ý {#limits-notes} - **Stripe Link và ví điện tử.** Link, Apple Pay và Google Pay là các tính năng của Stripe. NexCMP không lưu bất kỳ thông tin nào riêng cho Link; hệ thống chỉ lưu mã tham chiếu thẻ do Stripe trả về. - **PayPal.** Mỗi lần nạp tiền qua PayPal do khách hàng khởi tạo đều cần nhấp xác nhận; PayPal đã lưu chỉ được dùng cho tính năng tự động nạp tiền, không dùng cho bất kỳ tính năng nào khác. - **Trang đại lý (reseller).** Nếu reseller sử dụng tài khoản Stripe hoặc PayPal riêng, các phương thức đã lưu sẽ bị ẩn và tính năng tự động nạp tiền sẽ không khả dụng cho trang đó. - **Tranh chấp (dispute).** Mọi tranh chấp thanh toán đều sẽ khóa tài khoản và tạm dừng các dịch vụ trả trước; xem [Stripe](https://nexcmp.com/vi/docs/billing/stripe/). - **Việc xóa phương thức cuối cùng** sẽ tắt tính năng tự động nạp tiền; khách hàng vẫn giữ nguyên số dư ví. - **Bằng chứng.** Bản ghi chấp thuận do máy chủ tạo (khách hàng không thể chỉnh sửa) và được lưu trữ để xử lý khi có tranh chấp. ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | Khách hàng không thấy nút Settings hoặc thẻ đã lưu | Trang web sử dụng kênh thanh toán của reseller, hoặc chưa từng thanh toán qua thẻ | Thực hiện nạp tiền bằng thẻ hoặc PayPal qua kênh của nền tảng. | | Không thấy "Saved card" sau khi thanh toán qua Stripe | Thanh toán được thực hiện bằng phương thức không thể tái sử dụng (ví dụ: Alipay) | Thanh toán lại bằng thẻ. | | PayPal: "chưa thể lưu tài khoản này" | PayPal không trả về vault token | Tiếp tục với thanh toán một lần, hoặc thử một tài khoản PayPal khác. | | Tự động nạp tiền dừng lại sau khi xóa thẻ | Đúng theo thiết kế: xóa thẻ sẽ tắt tính năng này | Lưu phương thức mới trong lần nạp tiền tiếp theo. | --- # Tự động nạp tiền {#auto-top-up} > **Vị trí trong admin:** Finance › Payment channels › Fees & limits (`/payments/fees`), thẻ **Wallet & top-up (Billing › Policy)**, mục **Auto top-up (Stripe / PayPal)**. **Vị trí trong portal:** Billing › Settings (`/billing?settings=1`). ## Chức năng {#what-it-does} Khi số dư ví của khách hàng xuống quá thấp, NexCMP sẽ trừ tiền qua [phương thức thanh toán đã lưu](https://nexcmp.com/vi/docs/billing/saved-payment-methods/) và nạp vào ví, giúp các dịch vụ đang chạy không bị tạm ngưng vì thiếu tiền. Một tiến trình chạy ngầm sẽ kiểm tra tất cả khách hàng đã bật tính năng này **mỗi 5 phút**. ## Yêu cầu {#requirements} | Hạng mục | Yêu cầu | |---|---| | Kênh | Đã cấu hình [Stripe](https://nexcmp.com/vi/docs/billing/stripe/) và/hoặc [PayPal](https://nexcmp.com/vi/docs/billing/paypal/). | | Phương thức đã lưu | Khách hàng có thẻ đã lưu hoặc tài khoản PayPal đã liên kết. | | Trang | Trang chính, hoặc trang reseller có kênh Stripe/PayPal do nền tảng trực tiếp thu hộ. | | Công tắc toàn cục | **Auto top-up enabled** đang bật (mặc định bật). | ## Cách thức hoạt động {#how-it-works} Sau **lần nạp tiền đầu tiên qua Stripe hoặc PayPal** của khách hàng, máy chủ sẽ lưu phương thức thanh toán và tự động bật tính năng tự động nạp ở chế độ **By usage** — chỉ khi khách hàng đó chưa từng tự cấu hình tự động nạp. Không có ô tick bổ sung nào trên màn hình nạp tiền; máy chủ sẽ ghi lại thời gian, địa chỉ IP và phương thức thanh toán làm bằng chứng. Nếu sau đó khách hàng tắt tự động nạp, tính năng này sẽ không bao giờ tự bật lại. | Chế độ | Điều kiện kích hoạt (khi số dư thấp hơn...) | Số tiền bị trừ | |---|---|---| | **By usage** (mặc định sau lần nạp đầu tiên) | chi phí cho 24 giờ tiếp theo của các dịch vụ đang chạy (VM tính theo giờ cộng với các khoản gia hạn trả trước đến hạn trong 24 giờ), nhưng không bao giờ dưới **$5** | chi phí 24 giờ được làm tròn lên số USD nguyên, tối thiểu bằng [mức nạp tối thiểu](https://nexcmp.com/vi/docs/billing/minimum-top-up/), tối đa bằng mức nạp tối đa và hạn mức ngày | | **Fixed amount** | ngưỡng do chính khách hàng đặt ($1 đến $500) | số tiền do chính khách hàng đặt (từ mức nạp tối thiểu đến $1,000, và lớn hơn ngưỡng kích hoạt) | Khi không có dịch vụ nào đang chạy ở chế độ **By usage**, hệ thống sẽ không trừ tiền. Số dư được so sánh với ngưỡng kích hoạt là **tiền thực tế trong ví**. Tín dụng dịch vụ từ mã khuyến mại được hạch toán riêng và không được tính (xem [Khuyến mại](https://nexcmp.com/vi/docs/billing/promotions/)). Phí được xử lý như một lần nạp tiền thông thường: khi bật **Customer pays top-up fee**, thẻ sẽ bị trừ số tiền nạp cộng với phí và ví nhận đủ số tiền nạp; khi tắt, ví sẽ nhận số tiền nạp trừ đi phí. ## Cấu hình giới hạn toàn cục {#configure-the-global-limits} 1. Mở **Finance › Payment channels › Fees & limits** (`/payments/fees`). 2. Trong **Auto top-up (Stripe / PayPal)**, hãy thiết lập: | Cài đặt | Mặc định | Khoảng giá trị | Ý nghĩa | |---|---|---|---| | Auto top-up enabled | On | bật hoặc tắt | Tắt sẽ dừng ngay lập tức mọi giao dịch trừ tiền chạy ngầm. | | Ngưỡng nạp tiền tự động mặc định (USD, dự phòng cho chế độ cố định) | $5.00 | $0 đến $10,000 | Chỉ dùng làm ngưỡng khởi đầu trong chế độ cố định. | | Số lần nạp tiền tự động tối đa mỗi 24 giờ cho mỗi khách hàng | 3 | 1 đến 50 | Tính cả các lượt thử thành công lẫn đang chờ xử lý. | | Hạn mức số tiền nạp tự động mỗi 24 giờ cho mỗi khách hàng (USD) | $500.00 | $0 đến $1,000,000 | Tổng số tiền trừ tự động trong một ngày luân phiên (24 giờ). | 3. Nhấp vào **Save Wallet & top-up**. ![Phần Auto top-up của trang Fees and limits với công tắc toàn cục và các hạn mức hàng ngày](https://nexcmp.com/vi/docs/images/billing/auto-top-up-01-limits.webp) ## Giao diện khách hàng thấy {#what-the-customer-sees} 1. Trong portal, khách hàng mở **Billing** rồi nhấp vào **Settings**. 2. Bảng điều khiển hiển thị (các) phương thức đã lưu, công tắc bật/tắt, chế độ (**By usage** hoặc **Fixed amount**), mức sử dụng ước tính hiện tại cùng lần trừ tiền tiếp theo, và mục **Recent automatic top-ups**. 3. Chuyển sang **Fixed amount** cho phép họ nhập ngưỡng kích hoạt và số tiền nạp. Gạt tắt công tắc sẽ dừng mọi lượt trừ tiền. ![Cài đặt thanh toán của khách hàng với tính năng tự động nạp tiền ở chế độ By usage và các lần tự động nạp gần đây](https://nexcmp.com/vi/docs/images/billing/auto-top-up-02-portal.webp) ## Kiểm tra {#verify} 1. Với tư cách khách hàng thử nghiệm, hãy nạp tiền lần đầu bằng thẻ thử nghiệm ([Stripe](https://nexcmp.com/vi/docs/billing/stripe/#verify)). Mở **Billing › Settings**: tự động nạp tiền đã được bật. 2. Chạy một VM nhỏ để phát sinh mức sử dụng, rồi giảm số dư xuống dưới ngưỡng (ví dụ qua **Customers › customer › Credit / debit**). 3. Trong khoảng 5 phút, một khoản phí sẽ được trừ. Trong thẻ **Overview › Payment** của khách hàng, **Auto top-up history** hiển thị lượt nạp với trạng thái *Done*, đồng thời thông báo *Top-up received* được gửi đi. ## Hạn mức & lưu ý {#limits-notes} - **Mỗi lần giảm chỉ trừ một lần.** Sau khi trừ tiền, tác vụ sẽ chờ cho đến khi số dư tăng trở lại trên ngưỡng hoặc hết thời gian chờ: 1 giờ sau khi thành công, 24 giờ sau khi giao dịch đang chờ xử lý, 30 phút sau khi gặp lỗi hệ thống. - **Hạn mức hàng ngày.** Khi đạt đến bất kỳ hạn mức hàng ngày nào, hệ thống sẽ không trừ tiền và ghi nhận một dòng *Daily limit reached* (tối đa một lần mỗi 6 giờ). - **Thất bại.** Thẻ bị từ chối, thẻ hết hạn hoặc không đủ số dư được tính là lỗi thẻ. Tác vụ sẽ thử lại sau 1 giờ, sau đó là 6 giờ, rồi 24 giờ. **Sau 3 lần lỗi thẻ liên tiếp, tính năng tự động nạp tiền sẽ bị tắt** và khách hàng nhận được thông báo (*Auto top-up failed*). Thanh toán cần khách hàng xác nhận (ví dụ 3-D Secure) không bị tính là thất bại; khách hàng sẽ được nhắc xác nhận giao dịch. - **Không trừ tiền trùng lặp.** Mỗi lần trừ tiền được xử lý nguyên tử cho mỗi lần số dư giảm xuống dưới ngưỡng và sử dụng idempotency key tại cổng thanh toán. - **Xóa thẻ** sẽ tắt tính năng tự động nạp tiền. - **Reseller.** Nếu reseller sử dụng kênh thanh toán riêng, khách hàng sẽ không thể bật tính năng tự động nạp tiền (HTTP 403 `feature_disabled`). ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | Khách hàng không thể bật: "Top up once with a card or PayPal" | Chưa lưu phương thức thanh toán | Thực hiện nạp tiền một lần bằng thẻ hoặc PayPal trước. | | Lỗi `no_card` (422) | Cổng thanh toán được chọn chưa có phương thức đã lưu | Chọn cổng thanh toán đã có phương thức lưu sẵn, hoặc lưu một phương thức mới. | | Lỗi `invalid_argument` về số tiền | Chế độ Fixed nằm ngoài phạm vi cho phép | Ngưỡng $1–$500, số tiền nằm trong khoảng từ mức nạp tối thiểu đến $1,000, số tiền lớn hơn ngưỡng. | | Không bị trừ tiền dù số dư đang ở mức thấp | Công tắc chung bị tắt, không có dịch vụ nào đang chạy ở chế độ By usage, đạt hạn mức hàng ngày hoặc lần trừ tiền trước đó vẫn đang chờ xử lý | Kiểm tra công tắc, lịch sử và các hạn mức. | | "N lần thử thất bại liên tiếp — tự động nạp tiền sẽ tắt sau 3 lần" | Thẻ liên tục bị lỗi | Khách hàng thay thẻ bằng một lần nạp tiền mới. | | Trạng thái *Needs your confirmation* | Ngân hàng yêu cầu 3-D Secure | Khách hàng hoàn tất một lần nạp tiền thông thường. | --- # Hóa đơn và sổ cái {#invoices-and-ledger} > **Vị trí trong trang admin:** Finance › Billing (`/billing`) với các tab Overview, Transactions (`/billing/ledger`), Invoices (`/billing/invoices`), Top-ups (`/billing/deposits`), Payouts (`/billing/payouts`), Vouchers (`/billing/vouchers`) và Reports (`/billing/reports`). **Vị trí trong portal:** Billing (`/billing`). ## Chức năng {#what-it-does} Mọi số tiền trong NexCMP đều được lưu trữ dưới dạng cent USD và được ghi nhận một lần. Ý tưởng cốt lõi: **sổ cái ví** là nguồn dữ liệu chuẩn xác cho số dư; hóa đơn, giao dịch nạp tiền và báo cáo đều là các chế độ xem được dựng từ sổ cái này. Sổ cái là **append-only** — sai sót được xử lý bằng cách ghi thêm một bút toán đảo nghịch, tuyệt đối không chỉnh sửa lịch sử. ## Yêu cầu {#requirements} | Hạng mục | Yêu cầu | |---|---| | Role | Quản trị viên. | | Thông tin người bán | Thiết lập tên pháp lý, mã số thuế, địa chỉ, email liên hệ và tiền tố số hóa đơn tại **System › Settings › General**, tab **Seller & invoicing** (`/settings?tab=seller`), thẻ **Seller details (printed on invoices)**. | | Thành phần phụ thuộc | [Payment channels](https://nexcmp.com/vi/docs/billing/payment-channels/) cho dòng tiền vào. | ## Các thành phần {#the-pieces} | Tab admin | Nội dung hiển thị | Mục đích sử dụng điển hình | |---|---|---| | **Overview** | Doanh thu hôm nay và tháng này, tổng sổ cái theo loại (deposit, charge, refund, adjustment, voucher), hóa đơn theo trạng thái, khoản hoàn tiền đang chờ duyệt, phím tắt, chi tiêu theo từng dịch vụ trong 30 ngày qua | Kiểm tra hàng ngày | | **Transactions** | Sổ cái ví, mỗi biến động một dòng | Giải thích số dư của khách hàng | | **Invoices** | Hóa đơn, cùng chế độ xem thứ hai **Orders** hiển thị mọi giao dịch mua của từng dịch vụ | Tìm chứng từ, gửi lại, đánh dấu đã thanh toán | | **Top-ups** | Các khoản thanh toán nhận qua gateway | Kiểm tra giao dịch thanh toán, hoàn tiền | | **Payouts** | Hoàn tiền vào thẻ, chi trả affiliate, rút tiền reseller | Duyệt chi tiền | | **Vouchers** | Mã nạp tiền | Xem [Promotions](https://nexcmp.com/vi/docs/billing/promotions/) | | **Reports** | Doanh thu, theo dịch vụ, theo reseller | Kế toán | ### Giao dịch (sổ cái) {#transactions-ledger} Các cột: thời gian, khách hàng, **loại**, dịch vụ, số tiền (mang dấu), VM, mã tham chiếu, người thực hiện, ghi chú. Bộ lọc: loại, dịch vụ, ID khách hàng, site (khi bạn có reseller), khoảng ngày và liên kết VM. | Loại | Ý nghĩa | |---|---| | `deposit` | Nạp tiền qua gateway | | `charge` | Tiền thanh toán cho dịch vụ (đơn hàng, gia hạn, sử dụng theo giờ...) | | `refund` | Tiền hoàn lại vào ví | | `adjust` | Tiền cộng hoặc trừ bởi quản trị viên, và cả mã nạp tiền (mã tham chiếu bắt đầu bằng `vch:`) — trang tổng quan hiển thị voucher thành một dòng riêng | Mỗi dòng có một mã tham chiếu như `dep:stripe:`; cùng một mã tham chiếu không bao giờ được ghi hai lần, đó là lý do webhook gửi lặp lại không thể cộng tiền hai lần. Dùng **Customers › List › customer › Credit / debit** để thêm điều chỉnh thủ công: bắt buộc phải có lý do, số tiền dương cũng sẽ cố gắng mở khóa các VM bị khóa do thiếu tiền, và thao tác được xác nhận qua hai bước. ![Tab Transactions hiển thị các dòng sổ cái ví với loại, dịch vụ, số tiền và mã tham chiếu](https://nexcmp.com/vi/docs/images/billing/invoices-and-ledger-01-ledger.webp) ### Hóa đơn {#invoices} Hóa đơn được tạo tự động khi khách hàng mua hoặc gia hạn dịch vụ thanh toán từ ví, hoặc khi nạp tiền. Định dạng số có dạng như `-<000001>` (ví dụ `NX202610-000042`); các site reseller dùng tiền tố và dãy số riêng của họ. Các số hóa đơn hiện có sẽ không bao giờ thay đổi khi bạn đổi tiền tố. | Trường | Giá trị | |---|---| | Loại | Receipt, Renewal, Top-up, Manual, Refund | | Status | Unpaid, Paid, Overdue, Cancelled, Refunded | Các thao tác trên một dòng: | Thao tác | Tác dụng | |---|---| | **View** / **Print** | Mở hóa đơn; cổng portal cũng có thể in hoặc lưu dưới dạng PDF. | | **Mark paid** (chỉ áp dụng cho unpaid hoặc overdue) | Đánh dấu đã thanh toán **mà không luân chuyển tiền ví** — sử dụng khi khách hàng đã thanh toán cho bạn ngoài NexCMP. Bắt buộc phải có lý do. Đối với hóa đơn gia hạn, thao tác này cũng gia hạn và mở khóa VM đang bị khóa. | | **Cancel** (chỉ áp dụng cho unpaid hoặc overdue) | Hủy hóa đơn. Bắt buộc phải có lý do. | | **Resend** | Gửi lại hóa đơn qua email. | **Create manual invoice** (nút ở đầu tab): ID khách hàng, 1 đến 50 dòng (mô tả, số lượng, đơn giá), ID VM tùy chọn, số ngày đến hạn tùy chọn (0 đến 365, mặc định 7), ghi chú tùy chọn. Hóa đơn được tạo ở trạng thái unpaid; khách hàng sẽ thấy hóa đơn trong **Billing › Invoice History**. Hóa đơn dịch vụ chưa thanh toán sẽ được **tự động quyết toán từ ví** ngay khi có tiền, vì vậy khách hàng chỉ cần nạp tiền. ### Top-ups (thanh toán) {#top-ups-payments} Mỗi lần thực hiện là một dòng: thời gian, khách hàng, **cổng và phương thức**, loại (top-up hoặc auto top-up), trạng thái (pending, completed, failed, refunded, disputed, canceled), số tiền khách đã trả, phí, số tiền cộng vào ví, mã tham chiếu cổng và thời gian hoàn tất. Các khoản thanh toán Stripe và PayPal đã hoàn tất có hành động **Refund**. Sử dụng các trang Gateway events để xem webhook ([Kênh thanh toán](https://nexcmp.com/vi/docs/billing/payment-channels/)). ### Payouts {#payouts} Ba tab phụ: **Card refunds** (phê duyệt hoặc từ chối yêu cầu hoàn tiền; yêu cầu được tạo từ một khoản thanh toán đã hoàn tất), **Affiliate payouts** (rút tiền hoa hồng) và **Reseller withdrawals**. Mọi quyết định đều được ghi log kiểm toán. ### Reports {#reports} **Revenue** (xu hướng 30 ngày, theo từng tháng, khách hàng hàng đầu), **By service** và **By reseller**. ![Tab Reports hiển thị các KPI doanh thu và xu hướng ba mươi ngày](https://nexcmp.com/vi/docs/images/billing/invoices-and-ledger-03-reports.webp) ## Giao diện khách hàng thấy {#what-the-customer-sees} Trong **Billing**, khách hàng có **Balance**, **Deposit**, **Redeem code**, **Settings** (auto top-up) và phần lịch sử với các tab **Invoice History**, **Payment Order**, **Ledger** cùng **Orders** (tất cả dịch vụ trong một danh sách kèm bộ lọc theo dịch vụ và loại). Mỗi hóa đơn đều có **View**, **Print** và **Save as PDF**; các số tiền tính bằng USD, có thể hiển thị theo loại tiền tệ hiển thị nếu muốn. ## Kiểm tra {#verify} 1. Thực hiện một giao dịch nạp tiền nhỏ với tư cách khách hàng thử nghiệm. 2. **Transactions** hiển thị một dòng `deposit`, **Top-ups** hiển thị khoản thanh toán là *Completed*, và doanh thu trong **Overview** tăng lên. 3. Mua một dịch vụ: xuất hiện dòng `charge`, và **Invoices** hiển thị hóa đơn *Receipt* hoặc *Renewal* với thông tin người bán mà bạn đã cấu hình. ## Hạn mức & lưu ý {#limits-notes} - **Append-only.** Không có cách nào để chỉnh sửa hoặc xóa một dòng sổ cái; hãy thêm một khoản điều chỉnh kèm lý do. - **Tiền tệ.** Các số tiền đều là USD; loại tiền tệ hiển thị chỉ mang tính hình thức (xem [Tiền tệ và tỷ giá](https://nexcmp.com/vi/docs/catalog/currency-and-exchange-rates/)). - **Hoàn tiền về thẻ** gồm hai bước (yêu cầu, sau đó phê duyệt trong Payouts); USDT và chuyển khoản ngân hàng không được hoàn về nguồn ban đầu. - **Mọi hoạt động đều được ghi log kiểm toán** trong System › Logs › Admin actions cùng với lý do bạn đã nhập. - **Orders so với invoices.** Mức sử dụng theo giờ không được xuất hóa đơn theo từng giờ; chế độ xem Orders sẽ nhóm theo ngày để bạn vẫn có thể theo dõi. ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | Số dư của khách hàng có vẻ không đúng | Khoản tính phí, điều chỉnh hoặc voucher ngoài dự tính | Lọc **Transactions** theo ID khách hàng và đọc các mã tham chiếu cùng ghi chú. | | "Hóa đơn đã được thanh toán" (409) | Đánh dấu đã thanh toán cho một hóa đơn đã thanh toán | Không cần xử lý gì. | | Không thể hủy hóa đơn | Chỉ có thể hủy hóa đơn unpaid hoặc overdue | Đối với hóa đơn đã thanh toán, hãy sử dụng tính năng hoàn tiền hoặc điều chỉnh. | | Thiếu thông tin người bán trên hóa đơn | Chưa được điền | Điền đầy đủ **Seller details** trong System › Settings › General › Seller & invoicing. | | Ghi nợ / ghi có bị từ chối | Số tiền bằng 0 hoặc vượt quá $100,000 | Sử dụng số tiền từ 1 cent đến $100,000. | | Khoản thanh toán hiển thị *Pending* trong thời gian dài | Thiếu webhook | Xem **Gateway events** và phát lại (replay). | --- # Khuyến mãi {#promotions} > **Vị trí trong trang admin:** Finance › Billing › Vouchers (`/billing/vouchers`). **Vị trí trong portal:** Billing › Redeem code (cũng có trong drawer Deposit). ## Chức năng {#what-it-does} **Mã nạp tiền** (voucher) là một mã bí mật dùng một lần bạn cung cấp cho khách hàng. Tùy theo cách bạn tạo, mã có thể: | Loại | Khách hàng nhận được gì | Giá trị được chuyển vào đâu | |---|---|---| | **Bonus credit** cho mọi dịch vụ | Tiền được cộng vào ví | Số dư ví. Có thể dùng cho mọi dịch vụ. | | **Bonus credit** cho các dịch vụ đã chọn | Credit dịch vụ | Một ngăn riêng biệt chỉ có thể thanh toán cho các dịch vụ đó. | | **Discount %** | Tỷ lệ phần trăm giảm giá cho đơn hàng đầu tiên của các dịch vụ đã chọn | Không có tiền nạp vào; khoản giảm giá được áp dụng khi thanh toán. | Sử dụng cho các chiến dịch, credit đền bù, ưu đãi đối tác hoặc giảm giá cho đơn hàng đầu tiên. ## Yêu cầu {#requirements} | Hạng mục | Yêu cầu | |---|---| | Role | Quản trị viên. | | Khách hàng | Khách hàng đổi mã khi đã đăng nhập vào portal (không áp dụng cho khách vãng lai). Theo mặc định khách hàng phải có email đã xác minh. | | Mã VND | Mã được tạo bằng VND sẽ quy đổi sang USD khi quy đổi theo tỷ giá đã lưu (xem [Currency and exchange rates](https://nexcmp.com/vi/docs/catalog/currency-and-exchange-rates/)). | ## Tạo một đợt mã {#create-a-batch} 1. Mở **Finance › Billing › Vouchers** và nhấp vào **Create vouchers**. 2. Điền vào biểu mẫu. Các giá trị ví dụ nằm trong ngoặc. | Trường | Ghi chú | |---|---| | Batch name | 1–80 ký tự (`Spring welcome`). | | Target | **Main site clients**, **Single reseller's customers** (cần danh sách khách hàng) hoặc **Reseller wallet**. | | Eligible users | **All in target audience** hoặc **Specified** — một email hoặc ID khách hàng trên mỗi dòng, tối đa 1,000. Đối với khách hàng của reseller, bắt buộc phải là *Specified*. | | 1 mã cho mỗi mục tiêu | Với tùy chọn *Specified*, tạo một mã cho mỗi khách hàng trong danh sách. | | Code type | **Bonus credit** hoặc **Discount %**. | | Applies to | Chọn một hoặc nhiều dịch vụ; để trống = **All services**. | | Currency, Face value | USD từ $1.00, hoặc VND từ 10,000 theo bội số của 1,000 (chỉ áp dụng cho bonus credit). | | Discount (%) | 1 đến 100 (chỉ áp dụng cho Discount %). | | Mức trần giảm giá tối đa (USD) | Bắt buộc đối với Discount %, từ $1.00. Đây cũng là mức tối đa bạn có thể mất cho mỗi lần đổi mã. | | Đơn hàng tối thiểu (USD) | `0` = không áp dụng. Đơn hàng đầu tiên phải đạt tối thiểu số tiền này. | | Số lượng mã | 1 đến 1,000 mã ngẫu nhiên. | | Số lượt dùng mỗi mã | 1 đến 100,000. `1` nghĩa là một người dùng trên mỗi mã; hãy tăng giá trị này nếu là mã dùng chung. | | Số lượt dùng tối đa mỗi tài khoản | Tối thiểu là 1. Đối với Discount %, giá trị này phải là `1`. | | Thời gian bắt đầu (tùy chọn), Hết hạn | Thời điểm hết hạn phải sau ngày hôm nay và sau thời gian bắt đầu, tối đa không quá 2 năm. | | Tiền tố mã (0–6 ký tự) | Chỉ cho phép chữ cái; để trống sẽ sử dụng tiền tố của trang web. | | Mã tùy chỉnh (chỉ khi số lượng = 1) | 6 đến 32 ký tự từ A–Z và 0–9. Dễ chia sẻ nhưng cũng dễ đoán: hãy giữ số lượt dùng ở mức thấp. | | Yêu cầu email đã xác minh | Mặc định bật. | | Ghi chú nội bộ, Lý do | Lý do là bắt buộc và sẽ được ghi vào audit log. | 3. Biểu mẫu hiển thị **Maximum exposure** (mệnh giá x số mã x số lượt dùng) để bạn biết trường hợp rủi ro cao nhất. Nhấp vào **Generate codes**. 4. **Sao chép mã ngay bây giờ.** Mã chỉ hiển thị một lần duy nhất: NexCMP chỉ lưu trữ mã băm (hash) và 4 ký tự cuối. Sử dụng **Copy all** hoặc **Download CSV**, tích chọn xác nhận và đóng hộp thoại. ## Cơ chế hoạt động của từng loại mã {#how-each-type-behaves} ### Wallet bonus (không chọn dịch vụ) {#wallet-bonus-no-service-selected} Ví sẽ được ghi có một mục **adjustment** (tham chiếu `vch:...`). Khoản này không thể hoàn tiền về thẻ, không tạo hoa hồng affiliate, không tạo hóa đơn và được tính vào số dư ví để xét quota. Các mã VND áp dụng tỷ giá tại thời điểm quy đổi. ### Service credit (dịch vụ đã chọn) {#service-credit-services-selected} - Khoản credit nằm trong một **ngăn riêng**, chỉ có thể thanh toán các khoản phí của các dịch vụ đã chọn (đơn hàng mới, gia hạn, phí theo giờ hoặc theo ngày, nâng cấp) và được trừ **trước** số dư ví. - Khoản này không thể rút, chuyển nhượng hoặc quy đổi thành tiền, và sẽ hết hạn cùng với mã. - Sổ cái hiển thị đầy đủ khoản phí kèm theo dòng credit đối ứng, giúp doanh thu của từng dịch vụ luôn chính xác trong khi số dư ví chỉ giảm đúng số tiền khách thực tế chi trả. - Khoản này **không** làm tăng bậc [quota](https://nexcmp.com/vi/docs/billing/quotas/) và bị bỏ qua bởi [auto top-up](https://nexcmp.com/vi/docs/billing/auto-top-up/). - Nếu khoản phí thanh toán bằng credit hoặc giảm giá được hoàn tiền, phần tiền do mã chi trả sẽ được khấu trừ khỏi khoản hoàn về ví và trả lại vào ngăn credit. ### Discount % {#discount} 1. Khách hàng nhập mã: mã sẽ chuyển sang trạng thái **activated**. Mã phần trăm chỉ có thể dùng một lần cho mỗi tài khoản. 2. **Khoản tính phí đầu tiên** của một dịch vụ được chọn không phải là phí theo giờ, và đạt tối thiểu **Minimum order**, sẽ được giảm giá theo tỷ lệ phần trăm, không vượt quá **Maximum discount cap**. 3. Mức giảm giá được máy chủ tính toán lại tại thời điểm tính phí; số tiền trên trình duyệt sẽ bị bỏ qua. Dòng ghi nhận quy đổi được ghi lại khi mã thực sự được sử dụng, kèm theo mức giảm giá thực tế. 4. Các khoản phí sử dụng theo giờ không bao giờ áp dụng mã. ## Các thao tác của khách hàng {#what-the-customer-does} 1. Mở **Billing** trên portal và nhấp vào **Redeem code**, hoặc dùng **Have a top-up code?** trong ngăn Deposit. 2. Nhập mã (không phân biệt chữ hoa-thường; dấu gạch ngang là tùy chọn) và nhấp **Check**. Portal sẽ hiển thị quyền lợi nhận được, ví dụ *Valid code: +$5.00*, *$5.00 credit for VPN* hoặc *20% off voucher for Virtual Machines (up to $5.00)*, cùng *Valid for orders from $10.00*. 3. Nhấp **Redeem** và xác nhận. Mỗi mã chỉ được sử dụng một lần cho mỗi tài khoản. Mã được gắn chặt với từng site: mã của site này sẽ "không hợp lệ" trên site khác mà không có bất kỳ gợi ý nào về việc mã tồn tại ở nơi khác. Các lần đoán sai sẽ bị giới hạn tốc độ và sau vài lần thử, tài khoản sẽ bị tạm khóa trong vài phút ("N attempts left before a temporary lock"). ## Theo dõi và dừng {#track-and-stop} - **Batches** liệt kê từng đợt mã kèm trạng thái (*active*, *disabled*, *expired*, *used up*), số lượt đã đổi và tổng giá trị ưu đãi. Mở một đợt mã để xem các tab **Codes** (đã che) và **Redemptions**, cùng nút **Export CSV**. - **Redemptions** liệt kê mọi lượt quy đổi trên toàn bộ các đợt; **Reseller quotas** hiển thị hạn mức phát hành hàng tháng đã dùng của từng đại lý; **Settings** dùng để bật/tắt mã đại lý và đặt hạn mức mặc định hàng tháng. - **Disable batch** sẽ dừng toàn bộ mã chưa sử dụng; các lượt đã quy đổi trước đó vẫn được giữ nguyên. Bạn cũng có thể vô hiệu hóa từng mã riêng lẻ. ## Kiểm tra {#verify} 1. Tạo một đợt gồm 1 mã: Discount % 20, cap $5, minimum order $10, dịch vụ Virtual Machines. 2. Đăng nhập dưới vai trò khách hàng thử nghiệm để đổi mã. Portal sẽ thông báo mã đã được kích hoạt. 3. Đặt mua một VM có giá tối thiểu $10 (chu kỳ tháng): hóa đơn sẽ hiển thị mức giảm giá (tối đa $5). 4. Trong đợt mã, mã đó sẽ hiển thị 1 lượt quy đổi với số tiền giảm giá thực tế. ## Hạn mức & lưu ý {#limits-notes} - Mã được liên kết với **đối tượng áp dụng** và **site** ngay khi tạo; không thể thay đổi sau đó. - Đại lý có thể phát hành mã cho khách hàng của riêng họ trong hạn mức ngân sách hàng tháng; xem [Resellers](https://nexcmp.com/vi/docs/customers/resellers/). - Slide khuyến mãi trên thanh bên dành cho khách hàng (**Marketing › Promo slides**) là tính năng riêng biệt và không áp dụng bất kỳ giảm giá nào. - Vì mã dạng văn bản thuần không bao giờ được lưu trữ, đợt mã bị mất sẽ không thể khôi phục: hãy vô hiệu hóa đợt đó và tạo đợt mới. ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | "Mã phần trăm: một lần dùng cho mỗi tài khoản" (`percent_one_per_account`) | Max uses per account lớn hơn 1 đối với Discount % | Đặt giá trị thành `1`. | | Biểu mẫu thông báo bắt buộc phải có cap | Discount % không có Maximum discount cap | Nhập tối thiểu $1.00. | | Không tìm thấy khách hàng | Một email hoặc ID trong danh sách không tồn tại | Chỉnh sửa lại danh sách (thông báo lỗi sẽ nêu rõ các mục không hợp lệ). | | Khách hàng báo "invalid code" | Sai site, hết hạn, bị vô hiệu hóa, đã dùng hết, không thuộc nhóm khách hàng mục tiêu, hoặc chưa xác minh email | Kiểm tra lại đợt mã và thông tin khách hàng. | | Credit không được sử dụng | Khoản phí thuộc về một dịch vụ khác | Credit chỉ dùng để thanh toán cho các dịch vụ đã chọn trong đợt mã. | | Giảm giá không được áp dụng | Đơn hàng dưới mức tối thiểu, tính phí theo giờ, hoặc mã đã được kích hoạt cho dịch vụ khác | Tạo đơn hàng đầu tiên đủ điều kiện áp dụng. | | Khách hàng bị khóa quyền đổi mã | Nhập sai quá nhiều lần liên tiếp | Chờ cho đến khi hết thời gian tạm khóa. | --- # Quotas {#quotas} > **Vị trí trong trang admin:** Services › Virtual Machines › Policy › Quota tab (`/vm/policy?tab=quota`). Theo từng khách hàng: Customers › List › a customer › Overview (`/customers/`), thẻ **Quota**. **Vị trí trên portal:** Client › Quotas (`/client/quotas`). ## Chức năng {#what-it-does} Quota giúp bảo vệ bạn trước nguy cơ lạm dụng từ các tài khoản mới: khách hàng nạp càng nhiều tiền thực vào ví, họ càng có thể tạo nhiều tài nguyên. Cơ chế này gồm hai lớp: - **Tài nguyên VM và Kubernetes**: tổng vCPU, RAM, ổ đĩa và số lượng VM. Các tier tương ứng với các gói cố định của bạn. - **Quota dịch vụ**: giới hạn số lượng IP, cluster, VPC, dung lượng lưu trữ (GB), v.v., chia thành năm tier (từ L0 đến L4) dựa trên số tiền đã nạp. Quota được kiểm tra **trước khi** trừ tiền. Yêu cầu vượt quá hạn mức sẽ bị từ chối với mã HTTP 403 `quota_exceeded` cùng thông báo hướng dẫn khách hàng số tiền cần nạp thêm. ## Yêu cầu {#requirements} | Hạng mục | Yêu cầu | |---|---| | Role | Quản trị viên. | | Công tắc | **Enable quota** (`quota_enabled`) mặc định ở trạng thái **tắt**. Các thiết lập bên dưới sẽ không có hiệu lực cho đến khi bạn bật tùy chọn này. | | Gói cố định | Tối thiểu một gói không tùy chỉnh (xem [Plans](https://nexcmp.com/vi/docs/catalog/plans/)) — các tier tài nguyên chính là các gói cố định của bạn. Nếu không có gói nào, chỉ quy tắc về số lượng VM được áp dụng. | | Thành phần phụ thuộc | Các hàng quota dịch vụ chỉ hiển thị cho những sản phẩm được kích hoạt trong hệ thống cài đặt của bạn (VPN, IPv6 proxy, Kubernetes, Private Cloud, Images, Object Storage, Dedicated). | ## Cách tính mức cơ sở {#how-the-basis-is-calculated} NexCMP không chỉ xét riêng các khoản thanh toán bằng thẻ. **Mức cơ sở** (basis) là **số dư ví đã ghi nhận** của khách hàng: tiền nạp qua cổng thanh toán, tiền cộng từ quản trị viên (**Credit / debit**) và voucher nạp ví đã quy đổi đều được tính một lần qua sổ cái ví. Chiết khấu đơn hàng và tín dụng dịch vụ từ mã khuyến mại không phải là tiền trong ví nên không được tính. Mức cơ sở cao nhất mà khách hàng từng đạt được sẽ được **giữ nguyên** (theo từng site) — việc chi tiêu hoặc hoàn tiền không bao giờ làm hạ tier đã mở khóa. ### Tài nguyên VM và Kubernetes {#vm-and-kubernetes-resources} 1. Các tier tương ứng với các gói cố định của site, được sắp xếp theo chi phí vận hành trong 24 giờ. 2. Khách hàng được xếp vào tier cao nhất mà chi phí 24 giờ của tier đó không vượt quá mức cơ sở của họ. Giới hạn tài nguyên chính là vCPU, RAM và ổ đĩa của gói đó. Khách hàng chưa đủ điều kiện cho gói rẻ nhất vẫn nhận được tài nguyên của gói rẻ nhất. 3. Mức sử dụng tính vào giới hạn bao gồm mọi VM đang hoạt động (kể cả VM bị khóa), ổ đĩa dữ liệu đã mua (ngay cả khi chưa gắn) cùng các worker và control plane của Kubernetes (worker cũng được tính là VM). 4. **Số lượng VM:** tối đa bằng **Max VMs at 24h tier** (mặc định là 2). Từ VM tiếp theo trở đi, số dư ví *hiện tại* của khách hàng phải đủ chi trả cho **30 ngày (720 giờ)** của tất cả các VM hiện có cộng với VM mới, tối đa tới **Max VMs when meeting 30-day threshold** (mặc định là 10). 5. **Việc tạo VM** cũng yêu cầu số dư tối thiểu bằng chi phí của VM đó trong **N giờ** (**Create VM: balance ≥ N hours**, mặc định là 2) cùng số dư tối thiểu của nền tảng. 6. Hạ cấu hình VM không bao giờ bị chặn. Hệ thống chỉ kiểm tra thông số nâng cấp, vì vậy khách hàng dù đã vượt giới hạn ổ đĩa vẫn có thể thêm vCPU nếu giới hạn vCPU cho phép. ## Cấu hình {#configure} 1. Mở **Services › Virtual Machines › Policy** và chọn tab **Quota**. 2. Bật **Enable quota**. 3. Kiểm tra ba thông số sau (đều có thể chỉnh sửa): | Trường | Mặc định | Khoảng giá trị | |---|---|---| | Tạo VM: số dư ≥ N giờ | 2 | 1 đến 720 | | Max VMs at 24h tier | 2 | 1 đến 100 | | Số VM tối đa khi đạt ngưỡng 30 ngày | 10 | 1 đến 1000 (không được thấp hơn trường trước) | 4. Trong mục **Tier-based service quotas**, hãy chỉnh sửa bảng (bên dưới). 5. Nhấp **Save**. NexCMP sẽ yêu cầu nhập **lý do**, thông tin này sẽ được ghi vào nhật ký kiểm toán cùng với các giá trị cũ và mới. Thay đổi sẽ áp dụng cho tất cả khách hàng. ![Tab Quota với công tắc kích hoạt, các giới hạn VM và bảng quota dịch vụ theo bậc](https://nexcmp.com/vi/docs/images/billing/quotas-01-policy.webp) ### Bảng quota dịch vụ {#service-quota-table} Bảng có 5 bậc (tier). Các ô tiêu đề từ **L0** đến **L4** chứa **ngưỡng nạp tiền tính bằng cent**: giá trị mặc định `0, 1000, 5000, 20000, 100000` nghĩa là L0 cho tài khoản mới, L1 từ $10, L2 từ $50, L3 từ $200 và L4 từ $1,000. Ngưỡng đầu tiên phải giữ nguyên là `0`. Mỗi hàng thiết lập quota cho một key theo từng bậc; **-1 nghĩa là không giới hạn**. | Key | Ý nghĩa | L0 | L1 | L2 | L3 | L4 | |---|---|---|---|---|---|---| | `vpn.ips` | IP VPN | 2 | 10 | 30 | 100 | 500 | | `proxy6.ips` | IP proxy IPv6 | 500 | 2000 | 10000 | 50000 | -1 | | `dedicated.servers` | Máy chủ bare-metal | 1 | 2 | 5 | 20 | 50 | | `s3.storage_gb` | Dung lượng Object Storage GB được phân bổ | 2048 | 4096 | 10240 | 51200 | -1 | | `k8s.clusters` | Cụm Kubernetes | 1 | 2 | 5 | 10 | 30 | | `k8s.workers` | Worker node Kubernetes | 3 | 9 | 18 | 50 | 200 | | `vpc.count` | Mạng Private Cloud | 1 | 2 | 5 | 10 | 30 | | `images.gb` | Dung lượng lưu trữ custom image (GB) | 50 | 100 | 200 | 500 | 2000 | Bảng cũng liệt kê một vài hàng dành cho các sản phẩm không thuộc bản phát hành này; hãy giữ nguyên chúng. Một key có sản phẩm bị tắt sẽ được ẩn và không bao giờ bị áp đặt. Giá trị phải là `-1` hoặc nằm trong khoảng từ `0` đến `10,000,000`. Quota dịch vụ tuân theo **cơ sở nguồn tiền (funds basis)**, tương tự như các bậc VM: số dư ví cao nhất từng đạt được, không phải tổng số tiền thanh toán bằng thẻ. Khách hàng của reseller sử dụng cùng các giá trị mặc định này và reseller chỉ có thể xem chúng. ## Ghi đè theo từng khách hàng {#per-customer-overrides} 1. Mở **Customers › List**, sau đó chọn khách hàng. Trong **Overview**, tìm thẻ **Quota**. 2. **Tài nguyên VM:** nhấp vào **Quota override** và chọn một trong các tùy chọn - **By top-up balance (remove override)** — hành vi mặc định; - **Unlimited (including VM count)** — gỡ bỏ mọi giới hạn đối với khách hàng này; - một **plan tier** — cố định mức trần tài nguyên theo gói cước đó; quy tắc về số lượng VM vẫn được áp dụng. Nhập lý do. Quản trị viên nền tảng có thể thiết lập bất kỳ bậc nào; mức ghi đè do reseller thiết lập không được vượt quá cơ sở nguồn tiền được giữ lại của khách hàng. 3. **Dịch vụ:** bảng bên dưới *Service quotas* hiển thị từng key cùng với *In use*, giới hạn hiệu dụng và *Source* của nó (tier hoặc override). Nhấp vào **Edit** trên một hàng, nhập **New quota** (`-1` = không giới hạn, để trống = quay về mặc định của bậc) và lý do. ![Thẻ Quota của khách hàng với bậc, mức sử dụng tài nguyên và bảng quota dịch vụ kèm theo mức ghi đè](https://nexcmp.com/vi/docs/images/billing/quotas-02-customer.webp) Mọi thay đổi ghi đè đều được ghi lại trong audit log cùng với quản trị viên thực hiện, lý do và giá trị trước/sau khi đổi. ## Giao diện khách hàng thấy {#what-the-customer-sees} **Client › Quotas** (`/client/quotas`) hiển thị **bậc hiện tại** của khách hàng, số lượng vCPU, RAM, ổ đĩa và VM đã dùng cũng như tổng số (phân tách giữa VM và Kubernetes), **số dư ví hợp lệ**, **cơ sở tài nguyên được giữ** (không giảm đi khi họ chi tiêu) và số tiền cần nạp thêm để lên bậc tiếp theo. Một thanh trượt cho phép họ chọn bậc mục tiêu và chuyển thẳng đến màn hình nạp tiền. Thẻ **Service Quotas** liệt kê từng dịch vụ kèm theo quota, mức đã dùng, bậc của họ (L0 đến L4), số tiền cần nạp thêm cho bậc tiếp theo và nút **Request increase** để mở bản nháp ticket hỗ trợ. Nút **Quota policy** giải thích các quy định. ![Trang Quotas trên portal với bậc hiện tại, mức sử dụng tài nguyên và quota dịch vụ](https://nexcmp.com/vi/docs/images/billing/quotas-03-portal.webp) ## Kiểm tra {#verify} 1. Bật **Enable quota** và sử dụng một khách hàng thử nghiệm mới có số dư $0. 2. Hãy thử tạo một VM lớn hơn gói rẻ nhất của bạn. Yêu cầu sẽ bị từ chối với `quota_exceeded` và thông báo "Exceeds the resources of tier ... Top up $X more to unlock tier ...". 3. Nạp số tiền được hiển thị. Bậc sẽ thay đổi ngay lập tức và yêu cầu tương tự sẽ thành công. 4. Mua IP VPN vượt quá giới hạn L0: HTTP 403 `quota_exceeded` kèm `"scope":"service"` và liên kết đến `/client/quotas`. 5. Trong thẻ Quota của khách hàng, **Source** hiển thị *tier*; hãy thiết lập ghi đè và bạn sẽ thấy nó đổi thành *override*. ## Hạn mức & lưu ý {#limits-notes} - **Tắt nghĩa là tắt.** Khi `quota_enabled` tắt, quy tắc cũ `new_account_max_vms` (**Services › Virtual Machines › Policy › Sales**) sẽ giới hạn tài khoản mới ở mức 2 VM cho đến khi số tiền nạp đạt $10. Khi bật quota, quy tắc đó không còn áp dụng nữa. - **Các VM do admin tạo không bị chặn.** - **Lỗi sẽ xử lý theo hướng đóng an toàn (fail-closed).** Nếu không thể đọc trạng thái quota, yêu cầu sẽ bị từ chối với `quota_unavailable` thay vì được cho phép. - Các yêu cầu qua **API, CLI and MCP** đều dùng chung bộ xử lý, do đó cùng áp dụng các giới hạn này. - **Tín dụng khuyến mãi** không làm tăng tier (xem [Promotions](https://nexcmp.com/vi/docs/billing/promotions/)). - **Các ngưỡng tier được tính bằng cent**, không phải dollar. ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | `quota_exceeded`, lý do `resources` | Tổng vCPU/RAM/ổ đĩa mới vượt quá tier | Nạp thêm số tiền như thông báo hoặc thiết lập giá trị override. | | `quota_exceeded`, lý do `vm_30d` | Vượt quá số lượng VM của tier 24h và số dư ví chưa đủ chi trả 30 ngày cho toàn bộ dàn máy | Nạp thêm số tiền hiển thị. | | `quota_exceeded`, lý do `vm_max` | Đã chạm giới hạn VM tuyệt đối | Tăng **Max VMs when meeting 30-day threshold** hoặc sử dụng giá trị override. | | `quota_exceeded`, `scope: service` | Đã chạm giới hạn theo từng dịch vụ | Tăng giá trị trong bảng hoặc override khóa đó cho khách hàng. | | `quota_unavailable` | Không thể xác minh trạng thái quota | Thử lại; kiểm tra nhật ký server nếu lỗi vẫn tiếp diễn. | | "quota_max_vms_30d must be >= quota_max_vms_24h" khi lưu | Giá trị bị đảo ngược | Đặt giá trị 30 ngày tối thiểu bằng giá trị 24 giờ. | | Khách hàng báo tier bị hạ | Tier không bị hạ; hãy so sánh **Held resource basis** với chi phí gói | Kiểm tra bảng giá gói: việc tăng giá gói có thể làm thay đổi các ngưỡng. | --- # Quản lý khách hàng {#managing-customers} > **Vị trí trong admin:** Customers › Customers › List (`/customers`), Deletion requests (`/customers/requests`), Service transfers (`/customers/transfers`) và API keys (`/customers/apikeys`). ## Chức năng {#what-it-does} Khu vực Customers là nơi nhân viên hỗ trợ tra cứu tài khoản, xem ví tiền, dịch vụ, ticket và lịch sử đăng nhập, cũng như thực hiện thao tác: khóa, mở khóa, xác minh email, đặt lại mật khẩu, cộng hoặc trừ tiền, đăng nhập thay (impersonate), tạo VM hoặc đóng tài khoản. ## Yêu cầu {#requirements} | Hạng mục | Yêu cầu | |---|---| | Role | Quản trị viên. Mọi thao tác ghi đều yêu cầu lý do và được ghi lại vào audit log (System › Logs › Admin actions). | | E-mail | Email đặt lại mật khẩu và email lời mời yêu cầu [cấu hình SMTP](https://nexcmp.com/vi/docs/administration/smtp-and-emails/) hoạt động. | ## Danh sách khách hàng {#the-customer-list} Mở **Customers › List**. Khách hàng là các tài khoản trên site chính của bạn; tài khoản của reseller cũng xuất hiện và có thể lọc theo site. ![Danh sách khách hàng với bộ lọc và các cột quốc gia, nguồn giới thiệu, số dư và số lượng VM](https://nexcmp.com/vi/docs/images/customers/managing-customers-01-list.webp) | Cột | Ý nghĩa | |---|---| | **Email** (và tên) | Nhấp để mở thông tin khách hàng. | | **State** | *Active*, *Locked* hoặc *Deleted*, kèm theo email *verified* hoặc *unverified*. Rê chuột qua thẻ khóa để đọc lý do. | | **Login** | Các phương thức đăng nhập khách hàng có: mật khẩu, Google, GitHub, passkey. | | **Country** | Quốc kỳ và tên quốc gia được xác định từ **địa chỉ IP**: quốc gia của IP khi đăng ký hoặc của IP đăng nhập gần nhất nếu không xác định được IP đăng ký. Tooltip sẽ hiển thị thông tin loại IP nào đã được dùng. | | **Referral source** | "*Referral*" kèm liên kết tới người giới thiệu và mã giới thiệu khi khách hàng đăng ký qua liên kết affiliate; nếu không sẽ là "Not recorded". | | **Balance**, **VMs** | Số dư ví (giá trị âm hiển thị màu đỏ) và số lượng VM đang hoạt động. | | **IP đăng ký / gần nhất** | Địa chỉ IP được sử dụng khi đăng ký và ở lần đăng nhập gần nhất kèm mã quốc gia gồm hai chữ cái. Sử dụng thông tin này để phát hiện nhiều tài khoản đến từ cùng một địa chỉ. | | **Tenant** | ID tenant nội bộ của khách hàng. | | **Created**, **Last login** | Mốc thời gian tương đối. | | **Site** | Được hiển thị khi bạn có reseller. | **Search** hỗ trợ tìm theo e-mail, tên hoặc IP. **Bộ lọc:** trạng thái (all, active, locked, deleted), phương thức đăng nhập (any, Google, GitHub, passkey, no password yet) và site. Các bộ lọc được lưu trên URL, nhờ đó bạn có thể đánh dấu trang hoặc chia sẻ danh sách đã lọc với đồng nghiệp. **Sắp xếp trên toàn bộ dữ liệu.** Khi nhấp vào tiêu đề *Email*, *State*, *Balance*, *VMs*, *Created* hoặc *Last login*, hệ thống sẽ sắp xếp **toàn bộ** danh sách khách hàng trên máy chủ chứ không chỉ riêng trang bạn đang xem, đồng thời số trang sẽ quay về 1. **Danh sách tự động cập nhật.** Danh sách sẽ làm mới sau mỗi vài giây khi bạn xem (tạm dừng khi mở hộp thoại hoặc khi bạn nhập liệu), vì vậy các đăng ký mới và thay đổi số dư sẽ xuất hiện mà không cần tải lại trang. Trang khách hàng làm mới khoảng 30 giây một lần khi hiển thị; mỗi tab sẽ tải dữ liệu riêng khi mở lần đầu. ### Tạo khách hàng {#create-a-customer} 1. Nhấp vào **Create customer**. 2. Nhập **e-mail**, **tên hiển thị** tùy chọn, **mật khẩu** tùy chọn (để trống = khách hàng sẽ tự đặt qua liên kết mời) và chọn có **gửi e-mail mời** hay không. 3. Xác nhận. Tài khoản được tạo thủ công sẽ được tính là đã xác minh khi bạn gửi thư mời. ## Trang chi tiết khách hàng {#a-customer-s-page} Nhấp vào một hàng. Trang có tám tab; tab được chọn được lưu trong URL để bạn có thể đánh dấu trang. Các tab tải khi mở lần đầu và giữ nguyên trạng thái khi bạn chuyển sang tab khác. | Tab | Nội dung | |---|---| | **Overview** | Thông tin định danh, đăng ký và lần đăng nhập gần nhất, tóm tắt ví và dịch vụ | | **Services** | Một bảng chứa các dịch vụ của khách hàng, có bộ lọc loại và trạng thái, tìm kiếm, sắp xếp phía máy chủ và phân trang | | **Billing** | Ví và hạn mức tín dụng, sổ cái, hóa đơn, thanh toán, hoàn tiền, phương thức thanh toán đã lưu và tự động nạp tiền | | **Quota** | Giới hạn tài nguyên và ghi đè; xem [Quotas](https://nexcmp.com/vi/docs/billing/quotas/) | | **Security** | Phiên làm việc, xác thực, phương thức đăng nhập, lịch sử đăng nhập và API keys; xem [API keys](https://nexcmp.com/vi/docs/developers/api-keys/) | | **Support** | Các ticket gần đây | | **Affiliate** | Trạng thái chương trình giới thiệu | | **Log** | Lịch sử audit và hoạt động | Các nút thao tác ở phần header (ẩn đối với tài khoản đã xóa): | Nút | Chức năng | |---|---| | **Lock account** / **Unlock** | Chặn đăng nhập và quyền truy cập API. Tùy chọn dừng tất cả VM (không xóa). Các dịch vụ trả trước không phải là VM (Kubernetes, Private Cloud, VPN, v.v.) cũng sẽ bị dừng. Các VM bị quản trị viên khóa phải được mở lại riêng trên trang VM. | | **Verify email** | Đánh dấu email là đã xác minh mà khách hàng không cần nhấn vào liên kết. | | **Send reset link** | Gửi email chứa liên kết đặt lại mật khẩu (hiệu lực 1 giờ, dùng một lần). Nếu chưa cấu hình SMTP, liên kết sẽ hiển thị một lần để bạn tự gửi. Quản trị viên không bao giờ nhìn thấy mật khẩu. | | **Impersonate** | Đăng nhập với tư cách khách hàng trong vòng một giờ. Xem [Đăng nhập với tư cách khách hàng](https://nexcmp.com/vi/docs/customers/login-as/). | | **Credit / debit** | Cộng hoặc trừ tiền trong ví thông qua điều chỉnh sổ cái. Xem [Hóa đơn và sổ cái](https://nexcmp.com/vi/docs/billing/invoices-and-ledger/). | | **Revoke sessions** | Đăng xuất khách hàng khỏi tất cả các phiên; các app token sẽ ngừng hoạt động. | | **Create VM** | Tạo một VM cho khách hàng. | | **Soft delete** | Đóng tài khoản. Bạn phải nhập email để xác nhận. | ### Quản lý một dịch vụ riêng lẻ {#manage-an-individual-service} Mở tab **Services** của khách hàng, tìm dịch vụ theo tên, ID, IP hoặc cấu hình, và sử dụng các thao tác trên hàng tương ứng. Các thao tác tương tự cũng khả dụng trong danh sách quản trị riêng của dịch vụ. Hộp thoại chỉ đưa ra các thao tác được hỗ trợ bởi dịch vụ đó và trạng thái hiện tại của nó. | Thao tác | Tác dụng | |---|---| | **Lock** | Dừng dịch vụ nhưng vẫn giữ lại dữ liệu. Khách hàng thấy dịch vụ ở trạng thái bị khóa và không thể thao tác. Việc nạp tiền không gỡ bỏ khóa của quản trị viên; tính năng tự động gia hạn bị chặn khi đang khóa. | | **Unlock** | Hủy bỏ khóa của quản trị viên. Thao tác này không gỡ bỏ khóa do lạm dụng (abuse) hoặc các khóa bảo vệ khác không liên quan. | | **Cancel without refund** | Hủy dịch vụ mà không ghi nhận bút toán hoàn tiền vào sổ cái. Hộp thoại xác nhận sẽ cảnh báo rằng việc hủy dịch vụ không thể hoàn tác. | | **Cancel and refund** | Hiển thị các khoản thanh toán ban đầu, phân bổ ví/tín dụng, các lần hoàn tiền trước đó và số tiền hoàn lại tối đa. Hãy kiểm tra lại số tiền trước khi xác nhận. | Nhập lý do cho mỗi thao tác. Lý do này dành cho quản trị viên; khách hàng sẽ nhận được thông báo hoặc sự kiện dịch vụ mang tính trung lập. Tiền ví được hoàn trả sẽ quay về ví, và các khoản phân bổ từ tín dụng hoặc khuyến mại sẽ quay về tín dụng. Thao tác này không gửi lại tiền qua Stripe, chuyển khoản ngân hàng hoặc PayPal. Đối với nhiều dịch vụ cùng loại, chọn tối đa 50 hàng và chọn một thao tác hàng loạt. Kết quả sẽ liệt kê thành công hoặc thất bại cho từng hàng. Hoàn tiền hàng loạt sử dụng số tiền đề xuất của từng dịch vụ; các dịch vụ có số tiền hoàn lại đề xuất bằng 0 sẽ bị bỏ qua trong chế độ hoàn tiền và cần được xem xét riêng lẻ hoặc hủy mà không hoàn tiền. DDoS Shield, ổ đĩa và bản sao lưu là các hàng chỉ đọc tại đây. Các add-on băng thông đi theo dịch vụ cha của chúng. Quyền truy cập AI Models có thể bị khóa, nhưng không có gói đăng ký nào để hủy. Để khóa một máy chủ Bare Metal đang thuê, hãy thao tác trên gói đăng ký thay vì đơn hàng của máy chủ đó. ### Đóng tài khoản (soft delete) {#closing-an-account-soft-delete} Tài khoản được chuyển sang trạng thái *deleted*, bị khóa, các phiên đăng nhập bị thu hồi và hoa hồng giới thiệu chưa thanh toán sẽ được hủy bỏ. Hóa đơn và sổ cái vẫn được giữ lại để phục vụ kế toán. Thao tác này sẽ bị từ chối nếu khách hàng vẫn còn **bất kỳ dịch vụ nào đang hoạt động** (VM, Kubernetes, Private Cloud, Dedicated, VPN, IPv6 proxy), tài khoản S3 hoặc mức sử dụng S3 chưa thanh toán. Hãy xóa các mục đó trước. ## Yêu cầu xóa tài khoản {#deletion-requests} Khách hàng có thể gửi yêu cầu xóa từ trang tài khoản của họ. Các yêu cầu sẽ xuất hiện tại **Customers › Deletion requests** (bộ lọc mặc định: pending) cùng thông tin khách hàng, lý do, số lượng VM đang hoạt động, số dư và thời gian yêu cầu. - **Approve deletion** chỉ thực hiện được khi khách hàng không còn VM nào đang hoạt động. Nhập email để xác nhận. Tài khoản sẽ được soft-delete; **số dư ví còn lại sẽ không được hoàn tiền tự động** — hãy tạo hoàn tiền trước nếu bạn cần hoàn trả. - **Reject** cần nhập lý do. ## Chuyển nhượng dịch vụ {#service-transfers} **Customers › Service transfers** liệt kê các yêu cầu chuyển **VM hoặc gói đăng ký VPN** từ tài khoản này sang tài khoản khác **trên cùng một site**. - Màn hình này chỉ cho phép xem và tạo: bạn có thể tạo yêu cầu thay cho khách hàng hoặc hủy yêu cầu. Hệ thống cố ý **không** cung cấp nút phê duyệt thay cho chủ sở hữu hay người nhận. - Quy trình: chủ sở hữu xác nhận qua liên kết email dùng một lần (hiệu lực 30 phút, kèm TOTP nếu đã bật), sau đó người nhận đăng nhập và chấp nhận (người nhận sẽ tiếp quản các nghĩa vụ thanh toán). Yêu cầu không được chấp nhận trong vòng 7 ngày sẽ hết hạn. - Quy tắc: dịch vụ phải đang hoạt động, không có hóa đơn chưa thanh toán và không có tác vụ nào đang chạy; người nhận phải là khách hàng đang hoạt động với email đã được xác minh trên cùng một site. Việc chuyển nhượng VM sẽ xóa SSH key và tắt tính năng tự động gia hạn; việc chuyển nhượng VPN sẽ đổi mật khẩu kết nối. - Các hóa đơn đã phát hành vẫn thuộc về chủ sở hữu cũ; chủ sở hữu mới có thể xem lịch sử thanh toán của dịch vụ với thông tin của chủ sở hữu cũ được ẩn đi. - Khách hàng có thể tự tạo yêu cầu tại **Transfers** trong portal (tối đa 5 yêu cầu mỗi giờ và 3 yêu cầu đang mở cùng lúc). ## Kiểm tra {#verify} 1. Tạo khách hàng bằng email mời. Tài khoản mới sẽ xuất hiện ở đầu danh sách trong vòng vài giây. 2. Sắp xếp theo **Balance**: thứ tự sắp xếp sẽ áp dụng cho tất cả khách hàng. 3. Khóa khách hàng: thẻ trạng thái chuyển sang *Locked* và khách hàng không thể đăng nhập được nữa. Mở khóa lại. ## Hạn mức & lưu ý {#limits-notes} - Cột quốc gia chỉ mang tính tham khảo dựa trên IP, không phải bằng chứng cư trú. Địa chỉ IP nội bộ hoặc không xác định sẽ không hiển thị quốc gia. - Khóa tài khoản không hoàn lại bất kỳ khoản tiền nào và không xóa VM trừ khi bạn cũng chọn dừng chúng. - Mở khóa tài khoản không mở khóa các VM mà quản trị viên đã khóa; hãy mở khóa riêng từng VM trên trang VM. ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | "Khách hàng vẫn còn dịch vụ đang hoạt động ... dừng/xóa trước" | Khách hàng có các dịch vụ hoặc một tài khoản S3 | Gỡ bỏ chúng, sau đó soft delete. | | Phê duyệt xóa báo "N VMs alive" | Cùng nguyên nhân | Xóa các VM trước. | | Hiển thị liên kết đặt lại thay vì "e-mail queued" | Chưa cấu hình SMTP | Cấu hình e-mail, hoặc tự gửi liên kết. | | Không thể xóa phương thức đăng nhập (`last_login_method`) | Đó là cách duy nhất để khách hàng đăng nhập | Thêm một phương thức khác trước. | | Khóa không dừng các dịch vụ trả trước | Đã có báo cáo lỗi khi dừng | Đọc thông báo sau khi khóa; hệ thống sẽ tự động thử dừng lại. | | Không thể tạo một lượt chuyển nhượng | Hóa đơn chưa thanh toán, tác vụ đang chạy, người nhận ở site khác hoặc chưa xác minh | Khắc phục điều kiện này và thử lại. | --- # Đăng nhập với tư cách khách hàng {#log-in-as-a-customer} > **Vị trí trong admin:** Customers › Customers › List › a customer › nút header **Impersonate** (`/customers/`). ## Chức năng {#what-it-does} **Impersonate** (login-as) cho phép quản trị viên hỗ trợ xem portal chính xác như một khách hàng nhìn thấy, nhằm tái hiện sự cố hoặc hỗ trợ xử lý đơn hàng. Phiên này kéo dài một giờ và được tách biệt rõ ràng với phiên thông thường: mọi thao tác có thể cấp quyền truy cập lâu dài vào tài khoản đều bị chặn, và mỗi lần sử dụng đều được ghi log. ## Yêu cầu {#requirements} | Hạng mục | Yêu cầu | |---|---| | Role | Một quản trị viên đã đăng nhập vào admin console. | | Khách hàng | Tài khoản phải ở trạng thái **active**. Tài khoản bị khóa hoặc bị xóa sẽ trả về "account is not active" (HTTP 409). | | Lý do | Bắt buộc phải có lý do; lý do này được ghi vào audit log. | | Trình duyệt | Cho phép pop-up đối với địa chỉ admin: portal sẽ mở trong một cửa sổ mới. | ## Các bước thực hiện {#steps} 1. Mở **Customers › List** và nhấp vào khách hàng. 2. Nhấp vào **Impersonate**. Một hộp thoại sẽ giải thích rằng site của khách hàng sẽ mở dưới danh nghĩa khách hàng trong một giờ và mọi thao tác đều được audit. 3. Nhập **lý do** (ví dụ: "Ticket 1234 — cannot create VM") và nhấp vào **Open app**. 4. Một cửa sổ mới mở ra trên site của khách hàng và hiển thị dashboard với `?impersonated=1`. Nếu trình duyệt chặn cửa sổ này, hãy cho phép pop-up và nhấp lại. ![Hộp thoại Impersonate với trường lý do đã được điền](https://nexcmp.com/vi/docs/images/customers/login-as-01-dialog.webp) Đối với khách hàng của reseller, cửa sổ sẽ mở trên **tên miền riêng của reseller**, vì liên kết chỉ hoạt động trên chính site của khách hàng. ## Cách thức hoạt động {#how-it-works} 1. Hành động của admin sẽ tạo một **token dùng một lần** có hiệu lực trong một giờ và ghi `customer.login_as` (quản trị viên, IP, lý do, site) vào audit log. 2. Cửa sổ mới sẽ mở `https:///v1/portal/impersonate/`. Yêu cầu đầu tiên chỉ hiển thị một trang nhỏ và **không** tiêu thụ token (để tính năng prefetch của trình duyệt không làm mất token); sau đó trang sẽ xác nhận bằng một yêu cầu POST. 3. Yêu cầu POST sẽ tiêu thụ token này. Việc sử dụng lần thứ hai, hoặc dùng sau một giờ, sẽ nhận phản hồi "The impersonation link has expired or was already used". 4. NexCMP tạo một phiên khách hàng kéo dài **một giờ** (phiên thông thường kéo dài 30 ngày), ghi lại một mục đăng nhập với phương thức `impersonate`, và ghi nhật ký `customer.login_as.used`. 5. Token chỉ hoạt động trên chính site của khách hàng; trên host khác hệ thống sẽ trả về 404. ## Những gì bị chặn trong phiên mạo danh {#what-is-blocked-in-an-impersonated-session} Bất kỳ thao tác nào cấp quyền truy cập vượt quá một giờ, hoặc thay đổi thiết lập bảo mật riêng của khách hàng, đều trả về HTTP 403 `impersonate_forbidden`: | Thao tác bị chặn | Lý do | |---|---| | Đổi mật khẩu, TOTP, liên kết hoặc hủy liên kết Google/GitHub, chỉnh sửa passkey | Thông tin đăng nhập riêng của khách hàng | | Xóa tài khoản | Không thể hoàn tác | | Tạo hoặc chỉnh sửa **API keys** | Quyền truy cập dài hạn | | Phê duyệt đăng nhập CLI, desktop hoặc MCP (liên kết thiết bị) | Quyền truy cập dài hạn | | Tạo quyền truy cập Kubernetes, S3 keys, SSH keys, mật khẩu root, liên kết chia sẻ console, thông tin đăng nhập VPN hoặc proxy | Thông tin mật tồn tại lâu hơn phiên làm việc | | Quy đổi mã nạp tiền | Các chiến dịch tiền thưởng | | Rút tiền hoặc thay đổi phương thức thanh toán hoa hồng affiliate | Dòng tiền rời khỏi hệ thống | | Chỉnh sửa AI keys, ngân sách hoặc email cảnh báo | Cấu hình của khách hàng | Mọi thứ khác đều hoạt động: bạn có thể xem các trang, tạo hoặc quản lý VM, đặt hàng, v.v. Các hành động chạy dưới danh tính của khách hàng và sử dụng tiền của khách hàng; các mục nhật ký kiểm toán ở trên sẽ cho thấy quản trị viên đứng sau phiên làm việc đó. ## Kiểm tra {#verify} 1. Mạo danh một khách hàng thử nghiệm. Portal sẽ mở ra và hiển thị dữ liệu của khách hàng đó. 2. Thử đổi mật khẩu: bạn sẽ nhận thông báo "forbidden" (impersonation). 3. Trong **System › Logs › Admin actions**, tìm `customer.login_as` chứa tên bạn, lý do và site, theo sau là `customer.login_as.used`. 4. Đóng cửa sổ, mở lại cùng liên kết đó: "link expired or already used". ## Hạn mức & lưu ý {#limits-notes} - Giới hạn một giờ là cố định (3600 giây). Để tiếp tục, hãy thực hiện mạo danh lại. - Hãy ưu tiên việc đọc và tái hiện lỗi; tránh các hành động phát sinh chi phí trừ khi khách hàng yêu cầu bạn làm vậy. - Thu hồi phiên làm việc sớm bằng **Revoke sessions** trên trang khách hàng (thao tác này cũng sẽ đăng xuất cả khách hàng). - Đại lý có tính năng mạo danh **Sign in to partner console** riêng (60 phút) từ Resellers; xem [Resellers](https://nexcmp.com/vi/docs/customers/resellers/). ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | "Tài khoản không hoạt động" | Tài khoản bị khóa hoặc đã bị xóa | Hãy mở khóa tài khoản trước, hoặc xem thông tin trên trang khách hàng. | | Trình duyệt chặn cửa sổ | Trình chặn pop-up | Cho phép pop-up đối với địa chỉ admin và thử lại. | | "Liên kết đã hết hạn hoặc đã được sử dụng" | Hết hạn một giờ hoặc liên kết đã được dùng lại | Thực hiện mạo danh lại. | | Mở ra "Not found" | Liên kết được sử dụng trên sai host | Hãy sử dụng cửa sổ do hộp thoại mở ra; không dán liên kết sang nơi khác. | | Thao tác báo lỗi "forbidden" | Bị chặn trong các phiên mạo danh | Yêu cầu khách hàng thực hiện hoặc sử dụng các màn hình quản trị. | --- # Reseller (white-label) {#resellers-white-label} > **Vị trí trong trang quản trị:** Customers › Resellers › List (`/resellers`), Domains & SSL (`/resellers/domains`), Permissions & wholesale (`/resellers/entitlements`), Defaults (`/resellers/settings`). Slot reseller: System › Admin › License & updates (`/license`). ## Chức năng {#what-it-does} **Reseller** nhận được một bản portal khách hàng mang thương hiệu riêng trên **tên miền của họ**, với khách hàng, ví tiền, biểu giá và các kênh thanh toán riêng (tùy chọn). Họ mua dịch vụ từ bạn theo giá sỉ và bán lại theo giá của họ. Khách hàng của họ không bao giờ thấy thương hiệu của bạn, và tên miền reseller không bao giờ có thể mở console quản trị của bạn. Reseller vận hành hoạt động kinh doanh từ **partner console** tại `https://partner.`. ## Yêu cầu {#requirements} | Hạng mục | Yêu cầu | |---|---| | License | Một **slot reseller domain** trên license của bạn cho mỗi tên miền reseller tùy chỉnh. Trang license hiển thị `used/max` slot và liên kết để mua thêm. Nếu không còn slot trống, việc thêm tên miền sẽ thất bại với lỗi "Out of license reseller domain slots". | | DNS | Mỗi tên miền reseller phải được trỏ về máy chủ của bạn (xem bên dưới). | | Web server và TLS | Hostname phải trỏ tới panel NexCMP qua reverse proxy của bạn với chứng chỉ hợp lệ cho tên đó. | | E-mail | SMTP đã được cấu hình cho email mời và email thông báo. | | Công tắc chính | **Reseller settings › General › `rs_enabled`** được bật theo mặc định. | ## Chuẩn bị hạ tầng {#prepare-the-infrastructure} 1. Xác định địa chỉ công khai của máy chủ: địa chỉ IPv4 và hostname trỏ về địa chỉ đó nếu bạn muốn dùng CNAME (ví dụ: `sites.cloud.example.com`). 2. Mở **Customers › Resellers › Defaults** (`/resellers/settings`), nhóm **Domains & SSL** và thiết lập: | Key | Ý nghĩa | |---|---| | `rs_server_ipv4` | IPv4 công khai mà bản ghi A của reseller phải trỏ tới | | `rs_cname_target` | Hostname mà bản ghi CNAME của reseller phải trỏ tới | | `rs_master_hosts` | Các hostname thuộc trang web chính của bạn (không thể cấp cho reseller) | | `rs_platform_domain` | Tên miền cha tùy chọn cho **platform sub-domain** (ví dụ: `partners.cloud.example.com` để cấp cho reseller `acme.partners.cloud.example.com`). Để trống sẽ vô hiệu hóa tùy chọn này | | `rs_sites_stale_minutes` | Số phút trước khi dịch vụ chứng chỉ được coi là quá hạn (mặc định 15) | | `rs_ssl_fail_hours` | Số giờ thử lại thất bại trước khi báo lỗi (mặc định 48) | ::: warning Kiểm tra các giá trị này trước khi gửi hướng dẫn `rs_server_ipv4`, `rs_cname_target` và `rs_master_hosts` đi kèm các giá trị mẫu. Hãy thay thế chúng bằng máy chủ và tên miền của bạn **trước khi** gửi hướng dẫn DNS cho reseller, nếu không hướng dẫn trên màn hình sẽ trỏ sai địa chỉ. ::: 3. Nhấp **Save** (hệ thống sẽ yêu cầu nhập lý do). 4. Đảm bảo reverse proxy của bạn chuyển tiếp hostname của reseller tới panel NexCMP và cung cấp chứng chỉ cho từng hostname đó. Bộ cài đặt chỉ cấu hình nginx và Let's Encrypt cho tên miền chính (và các tên `admin.` cùng `partner.` phân giải được). Nếu bạn dùng Cloudflare, hãy bật proxy cho hostname và sử dụng chế độ Full SSL. ## Kết nối trong NexCMP {#connect-in-nexcmp} ### Tạo reseller {#create-the-reseller} 1. Mở **Customers › Resellers › List** và nhấp **New reseller**. Trình hướng dẫn có 8 bước và sẽ cấp phát mọi thứ ở bước cuối; bạn có thể thử lại từng bước một cách an toàn. | Bước | Thông tin cần điền | |---|---| | **Reseller** | Tên pháp lý hoặc tên thương mại, **slug** (4–31 ký tự a–z, 0–9 hoặc `-`, bắt đầu bằng chữ cái; đây cũng là tiền tố hóa đơn), tên liên hệ, email và số điện thoại, ngôn ngữ mặc định, thông tin thanh toán của reseller (với tư cách là bên nạp tiền vào ví). | | **Console account** | Tên người dùng, email tài khoản, họ và tên; **Send a one-time invite link by e-mail** (hiệu lực 72 giờ, khuyến nghị) hoặc hiển thị mật khẩu tạm thời một lần. | | **Brand** | Tên thương hiệu, tên viết tắt, tagline, màu sắc chủ đạo, email và số điện thoại hỗ trợ, tên người bán in trên hóa đơn khách hàng, logo (nền sáng và tối), square mark và favicon: PNG, JPEG, WEBP hoặc ICO tối đa 256 KB, **không dùng SVG**. | | **Domains** | (Các) tên miền khách hàng kèm **also www**, tên miền chính, **test domain** (sslip.io) và tùy chọn **dry-run**, hoặc tên miền con của nền tảng. Trình hướng dẫn hiển thị **DNS OK / DNS not ready** và các bản ghi cần tạo. | | **Pricing & wallet** | Chiết khấu sỉ (%), giá sàn bán lẻ (% giá niêm yết), markup mặc định (%), hạn mức tín dụng, số dư ban đầu, cảnh báo số dư thấp, giới hạn khách hàng, VM và tên miền, các tính năng trang web (đăng ký khách hàng, chống DDoS, ticket hỗ trợ, gói tùy chỉnh, resize, Auto Scaling). | | **Payment channels** | Bên thu các khoản thanh toán của khách hàng (xem bên dưới) cùng tùy chọn PayPal riêng và chuyển khoản ngân hàng Việt Nam riêng. | | **Email** | Tên người gửi và Reply-To. Địa chỉ From vẫn là địa chỉ của nền tảng cho đến khi DKIM được thiết lập cho tên miền đại lý. | | **Review** | Kiểm tra lại mọi thứ và nhấp vào **Provision everything**, hoặc **Save draft (provision later)**. | 2. Quá trình khởi tạo tiếp tục chạy nền (mỗi 30 giây). Mở đại lý để theo dõi tiến độ và sử dụng **Continue provisioning** hoặc **Retry** nếu có bước thất bại. ![Trình hướng dẫn đại lý mới ở bước đầu tiên với các giá trị mẫu](https://nexcmp.com/vi/docs/images/customers/resellers-01-wizard.webp) ### Trỏ DNS (đại lý thực hiện) {#point-dns-the-reseller-does-this} Đại lý (hoặc bạn) tạo các bản ghi hiển thị trên tab **Domains & SSL**: | Bản ghi | Name | Giá trị | |---|---|---| | TXT (quyền sở hữu, chỉ lần đầu) | `_site-verify.` | `sv=` hiển thị trên màn hình | | A (apex domain như `shop.example.net`) | tên miền | `rs_server_ipv4` của bạn | | CNAME (tên miền con như `cloud.example.net`) | tên miền | `rs_cname_target` của bạn (hoặc bản ghi A trỏ đến `rs_server_ipv4`) | | CNAME (tùy chọn) | `www.` | `rs_cname_target` của bạn | Ngoài ra: - Xóa mọi bản ghi **AAAA** (IPv6) trừ khi máy chủ của bạn phản hồi trên địa chỉ IPv6 đó. - Chuyển proxy CDN sang **off** (đám mây xám) trong khi tên miền đang được xác minh. - Nếu tên miền có các bản ghi **CAA**, hãy cho phép `letsencrypt.org`. Mã token trong bản ghi TXT là khác nhau đối với mỗi tên miền; hãy sao chép mã này từ màn hình. Hệ thống sẽ kiểm tra lại DNS mỗi 5 phút trong 48 giờ đầu tiên, sau đó kiểm tra hàng giờ và hủy bỏ tên miền nếu bản ghi TXT vẫn chưa có sau 72 giờ. ### Trạng thái tên miền {#domain-states} Trên **Customers › Resellers › Domains & SSL** (tất cả đại lý) và trong tab **Domains & SSL** của đại lý: | Trạng thái | Ý nghĩa | |---|---| | `pending_verify` | Đang chờ bản ghi TXT. | | `pending_dns` / `verifying` | Đang chờ bản ghi A hoặc CNAME trỏ về bạn. | | `issuing` | Chứng chỉ đang được cấp phát. | | `active` | Đang phục vụ trang web của đại lý. | | `cert_expiring` | Chứng chỉ sắp hết hạn; dự kiến sẽ gia hạn. | | `dns_lost` | DNS đã ngừng trỏ về bạn; tên miền sẽ bị xóa sau 30 ngày. | | `error` | Xem mã lỗi; chọn **Retry** sau khi đã khắc phục. | | `removing` / `removed` | Đang được thu hồi; slot giấy phép được hoàn trả. | Các thao tác trên hàng: **Check now**, **Retry**, **Make primary**, **Test mode** (cho tên miền thử nghiệm), **Remove**. ## Quyền hạn & giá bán buôn {#permissions-wholesale} **Customers › Resellers › Permissions & wholesale** (`/resellers/entitlements`) là một ma trận: mỗi reseller một hàng, gồm mức **discount** và **markup** bán buôn cùng một công tắc cho từng dịch vụ (ví dụ DDoS Shield và VPN). Công tắc có thể chỉnh sửa khi tính năng toàn nền tảng đang bật; nếu không, ô sẽ ở chế độ chỉ đọc và liên kết tới phần cài đặt. Tab phụ **Top-up codes** quy định số mã nạp tiền mỗi reseller được phép phát hành hàng tháng (xem [Khuyến mãi](https://nexcmp.com/vi/docs/billing/promotions/)). Quy tắc định giá: - Giá bán buôn = giá niêm yết x (1 - discount), và có thể ghi đè theo từng gói dịch vụ cũng như chu kỳ thanh toán trong tab **Wholesale pricing** của reseller. - Reseller tự đặt giá bán lẻ và không được thấp hơn mức sàn **floor** (tỷ lệ phần trăm so với giá niêm yết). - **Wallet** của reseller sẽ thanh toán theo giá bán buôn khi khách hàng của họ mua dịch vụ. Ví này có hạn mức tín dụng, thời gian ân hạn và mức trần thấu chi (xem Defaults). ## Defaults {#defaults} **Customers › Resellers › Defaults** (`/resellers/settings`) là các khóa `rs_*` áp dụng cho mọi reseller. Mỗi thay đổi đều yêu cầu nhập lý do và được ghi nhận kiểm toán. | Nhóm | Key | Mặc định | Ý nghĩa | |---|---|---|---| | General | `rs_enabled` | 1 | Bật chương trình reseller. | | | `rs_platform_collect_enabled` | 0 | Cho phép nền tảng thu tiền thanh toán từ khách hàng thay cho reseller. **Chỉ bật sau khi đã xem xét về mặt pháp lý.** | | | `rs_totp_required` | 1 | Tài khoản console của reseller bắt buộc phải sử dụng xác thực hai yếu tố. | | | `rs_agreement_version` | 1 | Phiên bản thỏa thuận reseller mà họ bắt buộc phải chấp nhận. | | Định giá mặc định | `rs_default_discount_bp` | 2000 (20 %) | Chiết khấu bán buôn cho reseller mới (điểm cơ bản, từ 0 đến 9000). | | | `rs_default_markup_bp` | 2500 (25 %) | Mức markup mặc định (0 đến 50000). | | | `rs_default_floor_bp` | 9000 (90 %) | Mức sàn bán lẻ (0 đến 20000). | | | `rs_default_max_domains` | 3 | Số tên miền được phép cho mỗi reseller. | | Ví và chi trả | `rs_grace_hours` | 72 | Thời gian ân hạn trước khi dịch vụ của khách hàng bị ảnh hưởng do ví reseller hết tiền. | | | `rs_overdraft_cap_cents` | 5000 | Mức thấu chi được phép trên ví. | | | `rs_retention_days` | 14 | Số ngày trước khi các VM của một reseller đã đóng bị hủy. | | | `rs_payout_hold_days` | 30 | Số ngày hoa hồng bị giữ trước khi có thể rút. | | | `rs_payout_min_cents` | 5000 | Số tiền rút tối thiểu. | | | `rs_topup_min_cents` | 2000 | Mức nạp ví tối thiểu của reseller. | | Thanh toán và thư | `rs_webhook_base` | để trống | URL gốc công khai cho webhook cổng thanh toán của reseller (để trống = dùng URL của trang). | | | `rs_mail_from` | để trống | Địa chỉ người gửi (From) cho email của reseller. | | | `rs_invoice_show_processor` | 1 | Hiển thị đơn vị xử lý thanh toán trên hóa đơn. | | | `rs_gw_stripe_enabled`, `rs_gw_usdt_enabled` | 1 | Cho phép reseller tự cấu hình Stripe hoặc USDT của riêng họ hay không. | ## Bên thu tiền thanh toán của khách hàng {#who-collects-customer-payments} | Chế độ | Ý nghĩa | |---|---| | **Reseller tự thu (kênh riêng)** — mặc định | Reseller kết nối tài khoản Stripe, PayPal, USDT hoặc tài khoản ngân hàng của riêng họ. Webhook của họ là `https:///v1/billing//webhook/r/`. Tính năng lưu thẻ và [tự động nạp tiền](https://nexcmp.com/vi/docs/billing/auto-top-up/) không khả dụng cho các trang này. | | **Nền tảng thu tiền** | Các kênh thanh toán của bạn sẽ hiển thị trên trang reseller. Bị khóa cho đến khi `rs_platform_collect_enabled = 1`. | | **Kết hợp** | Kết hợp tùy chọn theo từng kênh. | ## Giao diện hiển thị cho reseller {#what-the-reseller-sees} Partner console tại `https://partner.` bao gồm Overview, Reports, Customers, VMs, Tickets, Orders, Payments, Prices, Brand, Landing & legal, Domains & SSL, Email, Wallet và Payment channels. Tài khoản console có vai trò *reseller* (toàn quyền) hoặc *staff* (chỉ đọc). Để tự kiểm tra, hãy mở reseller và nhấp **Sign in to partner console**: bạn sẽ đăng nhập trong 60 phút, mọi thao tác ghi đều được ghi nhận kèm tên bạn ở cả admin log lẫn reseller log, còn các thao tác liên quan đến tiền bạc cần xác nhận lần hai. ## Kiểm tra {#verify} 1. Sau khi cấp phát xong, hàng của reseller trong danh sách sẽ hiển thị *active* và cột **Provisioning** màu xanh lá. 2. Mở domain của reseller trên trình duyệt: trang đăng nhập riêng của reseller sẽ xuất hiện cùng thương hiệu của họ. `https:///admin` sẽ trả về mã 404. 3. Đăng ký một khách hàng thử nghiệm trên domain đó: khách hàng sẽ xuất hiện trong **Customers › List** với reseller tương ứng ở cột **Site**. 4. Trang license sẽ hiển thị thêm một slot đã sử dụng. ## Hạn mức & lưu ý {#limits-notes} - Mỗi custom domain hoặc test domain tính một license slot; sub-domain của nền tảng không tính slot. - Tạm ngừng reseller vẫn giữ lại dữ liệu; **Close reseller** sẽ thu hồi toàn bộ domain slot, và việc hủy VM chỉ được phép sau thời gian lưu giữ. - Khách hàng của reseller xuất hiện trong danh sách khách hàng của bạn và có thể được mạo danh đăng nhập như mọi khách khác (liên kết sẽ mở trên domain của reseller). - Reseller không thể xem hoặc chỉnh sửa payment channels, hạn mức mặc định hay các reseller khác của bạn. ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | "Đã hết slot reseller domain theo license" | Đã dùng hết slot | Giải phóng một slot (xóa bớt domain) hoặc mua thêm trên trang license. | | Domain bị kẹt ở `pending_verify` | Thiếu bản ghi TXT | Tạo bản ghi TXT chính xác như hướng dẫn; sau đó dùng **Check now**. | | Domain bị kẹt ở `pending_dns` | Bản ghi A/CNAME chưa trỏ về bạn, có bản ghi AAAA, hoặc CDN proxy đang bật | Sửa lại DNS, tắt proxy, sau đó nhấn **Check now**. | | Trạng thái `error` | Xem mã lỗi trên hàng (ví dụ: CAA chặn Let's Encrypt, vượt giới hạn rate limit) | Khắc phục lỗi rồi nhấp **Retry**. | | Trình duyệt báo không tìm thấy host hoặc mã "421" | Host name chưa có trong license hoặc chưa được định tuyến đến panel | Thêm domain qua reseller (sẽ tốn một slot) và chỉnh lại reverse proxy. | | Hướng dẫn hiển thị sai IP hoặc host | `rs_server_ipv4` / `rs_cname_target` vẫn đang mang giá trị mẫu | Cấu hình lại các giá trị này trong Defaults. | | Reseller không thể bật thu hộ qua nền tảng | Bị khóa | Bật `rs_platform_collect_enabled` sau khi hoàn tất rà soát pháp lý. | --- # Tùy biến thương hiệu {#branding} > **Vị trí trong admin:** System › Settings › Brand (`/settings/branding`). Liên quan: System › Settings › General (`/settings`) cho URL và thông tin bên bán in trên hóa đơn. ## Chức năng {#what-it-does} NexCMP hỗ trợ white-label: sản phẩm không mang tên nhà cung cấp, mọi thứ khách hàng nhìn thấy đều là thương hiệu của **bạn**. Cài đặt thương hiệu áp dụng cho các trang đăng nhập và đăng ký, portal, admin console cùng email. ## Yêu cầu {#requirements} | Hạng mục | Yêu cầu | |---|---| | Role | Quản trị viên. | | Tệp tin | Logo: SVG, PNG, JPEG, WEBP hoặc ICO, **dung lượng tối đa 512 KB mỗi tệp**. | | Thành phần phụ thuộc | Không có. | ## Các bước thực hiện {#steps} 1. Mở **System › Settings › Brand**. 2. Tại thẻ **Identity**, điền các thông tin: | Trường | Ghi chú | |---|---| | **Brand name** (bắt buộc) | Tối đa 60 ký tự. Hiển thị trong portal, email, hóa đơn và các trang pháp lý. | | **Tên người bán trên hóa đơn** | Tối đa 120 ký tự. Để trống nghĩa là sử dụng tên thương hiệu. | | **Brand color** | Màu `#rrggbb`; nút nhỏ bên cạnh trường này sẽ đặt lại về màu mặc định. | | **Site currency** | **USD**: giá và số dư chỉ hiển thị bằng USD, không có nút chuyển đổi tiền tệ. **VND**: hiển thị thêm số tiền quy đổi theo tỷ giá được lưu trữ (xem [Tiền tệ và tỷ giá](https://nexcmp.com/vi/docs/catalog/currency-and-exchange-rates/)). | 3. Nhấp **Save**. 4. Trong thẻ **Logo & favicon**, tải lên ba hình ảnh — **Logo (light background)**, **Logo (dark background)** và **Favicon** — bằng **Upload** (hoặc **Replace**); **Remove** sẽ xóa ảnh. ![Trang Brand với các trường nhận diện và ba hình ảnh đã tải lên](https://nexcmp.com/vi/docs/images/customers/branding-01-brand.webp) ### Các cài đặt liên quan trong General {#related-settings-in-general} **System › Settings › General** có hai tab để hoàn thiện cấu hình: | Tab | Trường dữ liệu | |---|---| | **Branding & URLs** | Brand name (email, hóa đơn), ngôn ngữ mặc định (tiếng Anh hoặc tiếng Việt), **Customer app URL**, **Console URL**, **Admin URL** (liên kết mạo danh reseller) và **Partner console URL** (liên kết mời, email reseller). Trình hướng dẫn thiết lập sẽ điền sẵn các mục này bằng `https://`, `https:///admin` và `https:///console`. | | **Seller & invoicing** | Tên pháp nhân, mã số thuế, địa chỉ, email liên hệ và tiền tố số hóa đơn. Xem [Hóa đơn và sổ cái](https://nexcmp.com/vi/docs/billing/invoices-and-ledger/). | **From name** của email được thiết lập tại **System › Settings › Email** ([SMTP và email](https://nexcmp.com/vi/docs/administration/smtp-and-emails/)). ## Các tệp tải lên đều được kiểm tra {#uploaded-files-are-checked} - Ảnh raster được nhận diện từ nội dung tệp (không phải từ tên tệp) và được đo kích thước. - **Tệp SVG được dựng lại** từ danh sách các hình khối an toàn. Tệp chứa script, `foreignObject`, thuộc tính sự kiện, liên kết ngoài, `url(...)` trỏ ra ngoài, DOCTYPE hoặc entity sẽ **bị từ chối** (`svg_unsafe`). - Tệp quá lớn sẽ bị từ chối với `asset_too_large`, sai định dạng với `asset_type`, kích thước không hợp lệ với `asset_dimensions`. - Các tệp được phân phát từ chính domain của bạn với các security header nghiêm ngặt. ## Kiểm tra {#verify} 1. Mở trang đăng nhập portal trong cửa sổ ẩn danh: logo, tên và màu sắc sẽ xuất hiện. 2. Kiểm tra tab trình duyệt để xem favicon (trình duyệt lưu cache favicon; hãy tải lại sau khi xóa cache nếu bạn vẫn thấy favicon cũ). 3. Kích hoạt gửi thử một email (ví dụ **Send reset link** cho một khách hàng thử nghiệm) và kiểm tra tên thương hiệu trong tiêu đề cùng chân trang. ## Hạn mức & lưu ý {#limits-notes} - Logo cho nền tối được sử dụng khi khách hàng hoặc admin chuyển sang dark theme. - Reseller có thương hiệu riêng; họ tải lên tệp PNG, JPEG, WEBP hoặc ICO dung lượng tối đa 256 KB (không hỗ trợ SVG). Xem [Resellers](https://nexcmp.com/vi/docs/customers/resellers/). - Thay đổi về màu thương hiệu hoặc logo sẽ hiển thị ở lần tải trang tiếp theo; các email đã gửi sẽ không bị thay đổi. ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | Tải lên bị từ chối: `svg_unsafe` | SVG chứa script, liên kết hoặc tham chiếu bên ngoài | Xuất tệp SVG thuần (không có script, không có ảnh bên ngoài) hoặc dùng PNG. | | `asset_too_large` | Tệp vượt quá 512 KB | Nén hoặc thay đổi kích thước ảnh. | | `asset_type` | Không phải SVG, PNG, JPEG, WEBP hoặc ICO | Chuyển đổi định dạng tệp. | | `invalid_argument: primary` | Màu sắc không phải là `#rrggbb` | Sử dụng giá trị hex gồm 6 chữ số. | | Vẫn hiển thị logo cũ | Bộ nhớ cache trình duyệt | Tải lại cứng (hard-reload); favicon có thể mất nhiều thời gian hơn để cập nhật. | | Giá chỉ hiển thị bằng USD | Tiền tệ của trang là USD | Chuyển sang VND và đảm bảo tỷ giá đã được lưu. | --- # Các trang pháp lý {#legal-pages} > **Vị trí trong admin:** System › Settings › Legal (`/settings/legal`). **Vị trí khách hàng thấy:** `https:///terms` và `/privacy`, được liên kết từ trang đăng ký và thanh toán. ## Chức năng {#what-it-does} Bản cài đặt của bạn phát hành hai trang: **Terms of Service** và **Privacy Policy**. Cho đến khi bạn tự soạn nội dung riêng, NexCMP sẽ hiển thị **văn bản mặc định trung lập**, không đề cập đến nhà cung cấp phần mềm và không cam kết dịch vụ cụ thể nào. Hãy thay thế bằng văn bản đã được luật sư của bạn xem xét trước khi bắt đầu bán hàng. ## Yêu cầu {#requirements} | Hạng mục | Yêu cầu | |---|---| | Role | Quản trị viên. | | Nội dung | Định dạng markdown thuần, tối đa **50 KB** cho mỗi trang và ngôn ngữ. | | Thành phần phụ thuộc | Tên thương hiệu và thông tin người bán ([Branding](https://nexcmp.com/vi/docs/customers/branding/)) được chèn vào văn bản mặc định. | ## Các bước thực hiện {#steps} 1. Mở **System › Settings › Legal**. Mỗi trang trong số hai trang có thẻ riêng với nhãn *Using the default text* hoặc *Using your text*. 2. Chọn tab ngôn ngữ, **English** hoặc **Tiếng Việt**. 3. Nhập văn bản của bạn. Khi khung còn trống, văn bản mặc định sẽ hiển thị mờ dưới dạng placeholder. Để bắt đầu từ nội dung này, nhấp vào **Start from the default text**, sau đó chỉnh sửa. 4. Nhấp vào **Save**. Bộ đếm dung lượng sẽ hiển thị `used / 50 KB`. 5. Nhấp vào **View on the customer site** để mở `/terms` hoặc `/privacy`. 6. Để quay lại bản mặc định cho một ngôn ngữ, nhấp vào **Clear, back to default** và lưu. ![Cài đặt pháp lý với thẻ Terms of Service hiển thị văn bản mặc định làm điểm bắt đầu](https://nexcmp.com/vi/docs/images/customers/legal-01-terms.webp) ## Nội dung các trang mặc định bao gồm những gì {#what-the-default-pages-contain} Văn bản mặc định được lưu trữ trong sản phẩm dưới dạng `legal_default.json` và được điền tên thương hiệu, tên người bán, URL trang web cùng email liên hệ của bạn (từ **Seller & invoicing** trong System › Settings › General; nếu chưa đặt email, hệ thống sẽ trỏ về đội ngũ hỗ trợ của bạn). | Trang | Các mục | |---|---| | **Terms of Service** | 1 Dịch vụ · 2 Tài khoản và xác minh · 3 Giá cả và thanh toán · 4 Hoàn tiền · 5 Dữ liệu của bạn · 6 Quy định sử dụng hợp lệ · 7 Tính sẵn sàng và hỗ trợ · 8 Tạm ngưng và chấm dứt · 9 Trách nhiệm pháp lý · 10 Thay đổi và luật điều chỉnh (luật tại nơi kinh doanh của người bán) | | **Privacy Policy** | 1 Thông tin chúng tôi thu thập · 2 Mục đích sử dụng · 3 Cookie và bộ nhớ cục bộ · 4 Ai khác có thể xem · 5 Thời gian lưu trữ · 6 Quyền của bạn · 7 Liên hệ | ::: warning Không phải tư vấn pháp lý Văn bản mặc định là mẫu trung lập. Hãy nhờ xem xét lại trước khi áp dụng với khách hàng thực tế, đặc biệt là các mục về hoàn tiền, trách nhiệm pháp lý và luật điều chỉnh. ::: ## Quy tắc markdown {#markdown-rules} - Được hỗ trợ: tiêu đề (`# 1. Title`), đoạn văn, danh sách gạch đầu dòng và đánh số, **in đậm**, cùng liên kết `[text](https://example.com)`. - Liên kết phải bắt đầu bằng `http://` hoặc `https://`. - **HTML thô sẽ bị từ chối** (bất kỳ ``, ` # Tổng quan portal khách hàng {#customer-portal-overview} > **Vị trí trong portal:** `https:///` — khách hàng đăng nhập tại `/login`. Quản trị viên sử dụng `/admin`; cùng một tài khoản có thể truy cập cả hai nếu có quyền quản trị viên. Portal là nơi khách hàng của bạn sử dụng hằng ngày. Giao diện được gắn thương hiệu với tên, logo và màu sắc của bạn ([Branding](https://nexcmp.com/vi/docs/customers/branding/)) và chỉ hiển thị các dịch vụ bạn đã bật ([Modules](https://nexcmp.com/vi/docs/infrastructure/modules/)). ## Dashboard {#the-dashboard} Sau khi đăng nhập, **Dashboard** hiển thị: | Khối | Ý nghĩa | |---|---| | Số dư ví | Số dư hiện tại và ước tính số ngày sử dụng còn lại theo tốc độ chi tiêu hiện tại | | Chi tiêu tháng này | Chi phí phát sinh cho đến nay và dự báo vào cuối tháng | | Máy ảo | Từng VM kèm trạng thái, IP, CPU, RAM và các thao tác nhanh (Console, Restart) | | Băng thông | Lưu lượng truy cập vào/ra trong 1 h, 6 h, 24 h, 7 d, 30 d | | Hoạt động gần đây | Các sự kiện mới nhất trên tài khoản | | Bắt đầu nhanh | Danh sách kiểm tra: tạo VM, thêm SSH key, nạp tiền, bật tự động nạp tiền, xác minh email | ![Dashboard khách hàng hiển thị số dư ví, dự báo chi tiêu, máy ảo đang chạy và danh sách checklist khởi đầu nhanh](https://nexcmp.com/vi/docs/images/portal/overview-01-dashboard.webp) ## Điều hướng {#navigation} Menu nhóm các dịch vụ theo loại. Dịch vụ bạn đã tắt (hoặc nguồn chưa được kết nối) sẽ không xuất hiện. | Hạng mục | Trang | |---|---| | Instances | [Máy ảo](https://nexcmp.com/vi/docs/portal/virtual-machines/) và các trang chi tiết | | Deploy | [Đặt hàng](https://nexcmp.com/vi/docs/portal/ordering/) — tạo tài nguyên | | Storage | Snapshots, backups và ổ đĩa khi được bật — [Snapshots](https://nexcmp.com/vi/docs/portal/snapshots/) | | Billing | [Wallet and top-ups](https://nexcmp.com/vi/docs/portal/sign-up-and-wallet/), hóa đơn, đơn hàng, quota | | Tài khoản | Hồ sơ, đăng nhập và bảo mật, tùy chọn, tự động nạp tiền | | Hỗ trợ | Widget chat và ticket — [Support](https://nexcmp.com/vi/docs/portal/support/) | | Tài liệu API | `/apidoc` — [API](https://nexcmp.com/vi/docs/developers/api/) | ## Tài khoản {#account} **Account** có bốn tab: **Profile** (tên, email, mã khách hàng, yêu cầu xóa tài khoản), **Sign-in & security** (mật khẩu, passkey, liên kết Google/GitHub), **Preferences** (ngôn ngữ, tiền tệ hiển thị) và **Auto top-up** ([Auto top-up](https://nexcmp.com/vi/docs/billing/auto-top-up/)). Khách hàng không thể xóa tài khoản trực tiếp: họ nhấn **Request account deletion**; sau khi tất cả máy ảo bị xóa, quản trị viên sẽ xét duyệt yêu cầu (Customers › Deletion requests) và khách hàng có thể hủy yêu cầu khi đang chờ duyệt. ## Ngôn ngữ và tiền tệ {#language-and-currency} Portal hỗ trợ 16 ngôn ngữ và hiển thị giá theo loại tiền tệ được chọn theo ngôn ngữ; xem [Currency and exchange rates](https://nexcmp.com/vi/docs/catalog/currency-and-exchange-rates/). Khách hàng có thể thay đổi cả hai trong **Preferences**. ## Quota khách hàng {#customer-quotas} **Billing › Quotas** hiển thị mức tài nguyên (CPU, RAM, bộ nhớ lưu trữ, IP, VM) mà khách hàng được phép sử dụng dựa trên số tiền họ đã thanh toán — xem [Quotas](https://nexcmp.com/vi/docs/billing/quotas/). --- # Đăng ký, ví và nạp tiền {#sign-up-wallet-and-top-up} > **Vị trí trên portal:** `/register`, `/login`, Billing (`/billing`). ## Tạo tài khoản {#create-an-account} 1. Khách hàng mở `https:///register` và nhập email cùng mật khẩu (tối thiểu 10 ký tự gồm cả chữ và số), hoặc sử dụng **Google**, **GitHub** hay **passkey** nếu bạn đã bật — xem [Security](https://nexcmp.com/vi/docs/administration/security/#customer-sign-in). 2. Nếu captcha được bật, họ cần hoàn thành xác thực captcha. 3. Email xác minh được gửi qua [SMTP](https://nexcmp.com/vi/docs/administration/smtp-and-emails/) của bạn. Bắt buộc phải xác minh trước khi tạo VM nếu cài đặt bán hàng của bạn yêu cầu. ![Trang đăng ký với các trường email và mật khẩu](https://nexcmp.com/vi/docs/images/portal/sign-up-and-wallet-01-register.webp) ::: tip Nếu không có SMTP hoạt động, khách hàng không thể xác minh email hoặc đặt lại mật khẩu. Hãy cấu hình [SMTP](https://nexcmp.com/vi/docs/administration/smtp-and-emails/) trước. ::: ## Ví tiền {#the-wallet} Mọi khoản thanh toán đều được trừ từ số dư **wallet** theo loại tiền tệ thanh toán của bạn. Trang **Billing** hiển thị: | Mục | Ý nghĩa | |---|---| | Spending power | Số dư cộng với các khoản nạp đang chờ xử lý | | Accruing charges | Dịch vụ tính theo giờ phát sinh trong chu kỳ hiện tại, chưa quyết toán | | Outstanding balance | Mọi khoản tiền còn nợ | | Billing history | Các tab **Invoice History**, **Payment Order**, **Ledger**, **Orders** | ![Trang Billing với sức mua, chi phí phát sinh và các tab lịch sử](https://nexcmp.com/vi/docs/images/portal/sign-up-and-wallet-02-billing.webp) ## Nạp tiền {#add-credit} 1. Nhấp vào **Deposit**. 2. Nhập số tiền. Mức tối thiểu là [minimum top-up](https://nexcmp.com/vi/docs/billing/minimum-top-up/) do bạn đặt. 3. Chọn kênh thanh toán (thẻ, PayPal, USDT hoặc chuyển khoản ngân hàng khi giao diện là tiếng Việt) — các kênh là những cổng bạn đã bật trong [Payment channels](https://nexcmp.com/vi/docs/billing/payment-channels/). 4. Thanh toán. Số dư sẽ cập nhật ngay khi cổng thanh toán xác nhận. Thẻ đã lưu, Stripe Link và PayPal có thể tái sử dụng và dùng cho [auto top-up](https://nexcmp.com/vi/docs/billing/auto-top-up/); xem [Saved payment methods](https://nexcmp.com/vi/docs/billing/saved-payment-methods/). ## Đổi mã {#redeem-a-code} **Redeem code** cộng số dư từ voucher do bạn phát hành (Finance › Billing › Vouchers) hoặc áp dụng mã khuyến mãi — xem [Promotions](https://nexcmp.com/vi/docs/billing/promotions/). ## Hóa đơn {#invoices} Mỗi đơn hàng đã thanh toán sẽ tạo một hóa đơn hiển thị thông tin người bán của bạn ([General settings](https://nexcmp.com/vi/docs/administration/general-settings/)). Khách hàng có thể mở hóa đơn từ **Invoice History** rồi in hoặc lưu dưới dạng PDF từ trình duyệt. ## Tính phí theo giờ {#hourly-charges} Các dịch vụ theo giờ được tính phí mỗi giờ mà tài nguyên tồn tại; số tiền được tích lũy và một giờ riêng lẻ có thể làm tròn về $0.00. Khi số dư không đủ, dịch vụ sẽ bị tạm ngưng theo quy tắc thanh toán của bạn và khách hàng được thông báo qua email (`low_balance`). --- # Đặt mua dịch vụ {#ordering-a-service} > **Vị trí trên portal:** Deploy (`/deploy/vm`). **Vị trí trong admin** để bạn kiểm soát những gì hiển thị tại đây: Services (gói cấu hình, giá) và System › Admin › License & updates (các module). Trang đặt hàng là một biểu mẫu cuộn với các bước được đánh số. Việc chọn một dịch vụ khác ở bước 1 sẽ giữ nguyên trang và thay đổi các bước bên dưới. ## Các bước thực hiện {#steps} 1. **Service** — Cloud Servers và các dịch vụ khác mà bạn đã bật (Kubernetes, Object Storage, Images, Private Cloud, VPN …). 2. **Location** — [zone](https://nexcmp.com/vi/docs/infrastructure/zones/). Giá và lưu lượng mạng bao gồm có thể khác nhau tùy theo vị trí. 3. **Plan** — gói cố định (vCPU, RAM, ổ cứng NVMe, giá theo giờ) hoặc **Custom** (khách hàng tự chọn vCPU, RAM và ổ cứng; tính giá theo tài nguyên). Các gói được lấy từ [Plans](https://nexcmp.com/vi/docs/catalog/plans/). 4. **Billing cycle** — **Hourly** hoặc các chu kỳ trả trước hàng tháng/hàng năm có giảm giá (ví dụ 1 năm −10%, 2 năm −15%, 3 năm −20%). 5. **Operating system** — danh sách template, **My Images** (hình ảnh do chính khách hàng tải lên) và phiên bản. 6. **Hostname & quantity** — tên máy chủ (hoặc **Randomize**) và số lượng máy chủ. ![Trang đặt hàng hiển thị các bước chọn dịch vụ, vị trí và gói cấu hình](https://nexcmp.com/vi/docs/images/portal/ordering-01-plan.webp) ![Các bước chọn chu kỳ thanh toán và hệ điều hành trên trang đặt hàng](https://nexcmp.com/vi/docs/images/portal/ordering-02-cycle-os.webp) ## Đặt hàng {#placing-the-order} Phần tóm tắt hiển thị giá tiền. Đơn hàng được trừ tiền vào ví **trước khi** khởi tạo tài nguyên, sau khi [kiểm tra quota](https://nexcmp.com/vi/docs/billing/quotas/) và các quy tắc [số dư tối thiểu](https://nexcmp.com/vi/docs/billing/minimum-top-up/). Máy ảo thường chuyển sang trạng thái *Running* trong khoảng một phút; khách hàng có thể xem các bước triển khai trong tab **Activity** của VM và nhận email thông báo máy ảo sẵn sàng kèm mật khẩu ban đầu (chỉ hiển thị một lần trong 10 phút). ## Những nguyên nhân khiến đơn hàng bị dừng {#what-can-stop-an-order} | Thông báo / nguyên nhân | Cách khắc phục | |---|---| | Không đủ số dư | Nạp tiền — [Đăng ký, ví và nạp tiền](https://nexcmp.com/vi/docs/portal/sign-up-and-wallet/) | | Vượt quá quota | Nâng hạn mức quota — [Quotas](https://nexcmp.com/vi/docs/billing/quotas/) | | Email chưa được xác thực | Khách hàng xác thực email | | Không có gói nào cho vị trí đã chọn | Kích hoạt gói khả dụng tại zone đó — [Plans](https://nexcmp.com/vi/docs/catalog/plans/) | | Giấy phép không hợp lệ | Khách hàng không thể tạo dịch vụ mới — [License](https://nexcmp.com/vi/docs/getting-started/license-and-purchase/#if-the-license-is-not-valid) | --- # Máy ảo {#virtual-machines} > **Vị trí trên portal:** Instances (`/vms`) và trang chi tiết của VM (`/vms/`). **Instances** liệt kê các VM của khách hàng kèm tên, hệ điều hành, trạng thái, IP, thông số và chi phí. Nhấp vào một máy để mở trang chi tiết. ## Trang VM {#the-vm-page} Các tab: **Overview**, **Console**, **AI SSH Agent** (khi bật module AI), **Monitoring**, **Storage**, **Network**, **Configuration**, **Billing**, **Activity**. ![Tổng quan máy ảo với trạng thái, thông số, IP, biểu đồ băng thông và nhật ký hoạt động](https://nexcmp.com/vi/docs/images/portal/virtual-machines-01-overview.webp) ### Thao tác {#actions} | Thao tác | Tác dụng | |---|---| | Console | Mở console trên trình duyệt — [Console](https://nexcmp.com/vi/docs/portal/console/) | | Khởi động lại / Dừng / Buộc dừng | Điều khiển nguồn | | Đặt lại mật khẩu | Tạo mật khẩu mới, chỉ hiển thị một lần | | Cài lại OS | Cài đặt lại từ template; dữ liệu sẽ bị mất | | Đổi IP | Thay thế IP public (nếu nguồn hỗ trợ) | | Bật Auto Scaling | Tự động co giãn CPU/RAM theo tải khi được bật | | Xóa | Hủy VM; dừng tính phí theo giờ | ### Thông tin hiển thị {#information-shown} Uptime, chi phí tháng này, vCPU/RAM/ổ đĩa với mức sử dụng thực tế, IP public và IP private, tên người dùng, biểu đồ băng thông, nhật ký hoạt động và tóm tắt thanh toán (gói, chu kỳ, số giờ, thời gian còn lại). ::: info Các trường phụ thuộc vào nguồn Trang VM chỉ hiển thị những gì nguồn của nó hỗ trợ. Ví dụ: VM trên Proxmox VE không có port forwarding hoặc đổi IP, và danh sách OS tuân theo bộ template của cluster. Xem bảng tính năng trong [Proxmox VE](https://nexcmp.com/vi/docs/infrastructure/proxmox/). ::: ## Tab Billing {#billing-tab} Hiển thị gói dịch vụ, chu kỳ, tổng số giờ, thời gian còn lại và nhật ký thanh toán. Các VM tính theo giờ sẽ tiếp tục tích lũy cước cho đến khi bị xóa. Khách hàng có thể **chuyển chu kỳ** để trả trước cho thời gian dài hơn với mức chiết khấu. ## Dành cho quản trị viên {#for-administrators} Chính VM này cũng hiển thị tại Services › Virtual Machines trong trang quản trị, nơi bạn có thể thao tác thay mặt khách hàng hoặc [log in as](https://nexcmp.com/vi/docs/customers/login-as/) họ. --- # Console {#console} > **Vị trí trên portal:** trang chi tiết VM → tab **Console**. **Vị trí trên trang admin:** System › Admin › License & updates → modules (web SSH). ## Chức năng {#what-it-does} Tab **Console** mở phiên đồ họa (VNC) tới VM ngay trên trình duyệt, kể cả khi mạng bên trong VM bị gián đoạn. Terminal **web SSH** là tùy chọn thứ hai khi module SSH được bật. ## Yêu cầu {#requirements} | Hạng mục | Console VNC | Web SSH | |---|---|---| | CloudStack | Panel có thể kết nối tới Console proxy VM (CPVM) — xem [CloudStack](https://nexcmp.com/vi/docs/infrastructure/cloudstack/) | Cổng SSH trên VM có thể truy cập được | | Proxmox VE | Hoạt động qua panel (noVNC qua Proxmox API; vân tay TLS được ghim) — xem [Proxmox VE](https://nexcmp.com/vi/docs/infrastructure/proxmox/) | Tương tự | | Panel | Console URL được thiết lập trong [General settings](https://nexcmp.com/vi/docs/administration/general-settings/) | Service `ssh-proxy` và cờ module `feature_ssh_web`; tắt theo mặc định — xem [Modules](https://nexcmp.com/vi/docs/infrastructure/modules/) | Nếu module web SSH bị tắt, tab sẽ hiển thị **VNC only**. ## Cách sử dụng {#use-it} 1. Mở VM → **Console**. 2. Nhấp vào **Console** (hoặc **Open in new window**). Một ticket ngắn hạn sẽ được cấp và console sẽ mở tại `https:///console`. 3. Đăng nhập bằng tên người dùng và mật khẩu của VM (hiển thị trên tab Overview; đặt lại nếu bị mất). ![Tab Console của một máy ảo](https://nexcmp.com/vi/docs/images/portal/console-01-tab.webp) ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | Bị báo "Disconnected" ngay lập tức | Trình duyệt lưu đường dẫn console cũ | Xóa dữ liệu trang web (site data) cho domain và thử lại | | Màn hình đen | VM đang dừng hoặc đang khởi động | Khởi động VM và chờ | | Console không mở được trên CloudStack | Console proxy VM không chạy hoặc không thể truy cập | Kiểm tra các system VM trong CloudStack | | Không có tùy chọn SSH | Module Web SSH đang tắt | Chỉ bật sau khi `ssh-proxy` đã được cài đặt | --- # Snapshots và Backups {#snapshots-and-backups} > **Vị trí trên portal:** Snapshots (`/snapshots`), Snapshot schedules (`/snapshots/schedules`), Backups (`/backups`). Chỉ hiển thị khi tính năng được bật trong admin. ## Chức năng {#what-it-does} Snapshot lưu lại trạng thái ổ đĩa của VM để khách hàng có thể khôi phục khi có sự cố. Snapshots có thể được tạo thủ công hoặc theo lịch trình. ## Khả năng hỗ trợ {#availability} | Source | Snapshots | Ghi chú | |---|---|---| | CloudStack | Có | Volume snapshots; dung lượng lưu trữ tính phí theo cấu hình | | Proxmox VE | Có | Tối đa **5 bản mỗi VM**; tạo, xem danh sách, khôi phục và xóa | Mục menu chỉ xuất hiện khi tính năng snapshot được bật và khách hàng có VM thuộc nguồn hỗ trợ tính năng này. ## Cách sử dụng {#use-it} 1. Mở **Snapshots**, nhấn **Create**, chọn VM và đặt tên. 2. Chờ đến khi trạng thái chuyển sang *ready*. 3. Để quay lại, chọn **Restore** trên bản snapshot và xác nhận — VM sẽ quay về trạng thái đó (và được khởi động lại khi cần). 4. Xóa các snapshot bạn không còn sử dụng. ::: warning Quá trình khôi phục sẽ xóa bỏ toàn bộ dữ liệu ghi sau thời điểm snapshot. Các VM được bảo vệ không thể khôi phục hoặc xóa từ portal. ::: --- # Hỗ trợ khách hàng {#support-for-customers} > **Vị trí trên portal:** bong bóng chat trên mọi trang, `/chat`, và Support tickets. **Vị trí trong admin:** Customers › Support › Tickets (`/support/tickets`), tab **Settings**. ## Dành cho khách hàng {#for-customers} - **Bong bóng chat** (góc dưới cùng của mỗi trang): đặt câu hỏi; [AI Chat](https://nexcmp.com/vi/docs/ai/ai-chat/) sẽ trả lời dựa trên tài liệu của bạn và dữ liệu tài khoản của chính khách hàng. **Expand** để mở cùng cuộc trò chuyện trên `/chat`. - **Talk to staff**: chuyển tiếp cuộc trò chuyện tới đội ngũ của bạn (qua nhóm Telegram admin). - Nút **Telegram / Zalo**: chỉ xuất hiện sau khi bạn thiết lập liên kết trong phần cài đặt hỗ trợ. - **Tickets**: dành cho các vấn đề phức tạp hơn; câu trả lời được gửi qua email (`ticket_reply`). ## Dành cho bạn {#for-you} 1. Mở **Customers › Support › Tickets**; các ticket và phiên chat mới sẽ hiển thị tại đây cùng nội dung hội thoại. 2. Trả lời trong luồng trao đổi. Khách hàng sẽ nhận được email thông qua [SMTP](https://nexcmp.com/vi/docs/administration/smtp-and-emails/). 3. Trong tab **Settings**, bật hoặc tắt widget chat, đặt liên kết Telegram và Zalo (chỉ https), và chọn xem AI có tự động trả lời hay không — xem [AI Chat](https://nexcmp.com/vi/docs/ai/ai-chat/). 4. Kết nối [thông báo Telegram](https://nexcmp.com/vi/docs/administration/telegram-notifications/) để đội ngũ của bạn nhận thông báo khi có chat mới. --- # Nhà cung cấp AI {#ai-provider} > **Vị trí trong admin:** System › Settings › AI provider (`/settings/ai`). Nút bật module AI nằm tại đây và trong System › Admin › License & updates (`/license`), thẻ **Module**. ## Chức năng {#what-it-does} AI Chat (chat hỗ trợ tự động) và AI Agent (quản trị VM bằng ngôn ngữ tự nhiên) không đi kèm mô hình tích hợp sẵn. Bạn tự chọn **nhà cung cấp của riêng mình**: bất kỳ dịch vụ nào cung cấp `chat/completions` API **tương thích OpenAI** — ví dụ như OpenAI, OpenRouter, LiteLLM gateway hoặc vLLM server riêng của bạn. NexCMP lưu trữ endpoint và API key (được mã hóa) rồi sử dụng chúng cho mọi tính năng AI. Bạn thanh toán trực tiếp cho nhà cung cấp. ## Yêu cầu {#requirements} | Hạng mục | Yêu cầu | |---|---| | Endpoint | Base URL tương thích OpenAI (`https://api.openai.com/v1`, `https://ai.example.com/v1`). NexCMP sẽ thêm `/chat/completions` vào URL kết thúc bằng `/v1`; với mọi URL khác, hệ thống sẽ thêm `/v1/chat/completions`; URL đã kết thúc bằng `/chat/completions` sẽ được giữ nguyên. | | Model | Model hỗ trợ **tool (function) calling**. Cả AI Chat và Agent đều dựa vào tính năng này. | | API key | Key cho endpoint đó. Nên ưu tiên key có **giới hạn chi tiêu** (spending cap) ở phía nhà cung cấp (ví dụ: virtual key của LiteLLM với ngân sách hàng tháng). | | Mạng | Server chứa panel phải kết nối được tới endpoint qua HTTP(S). URL nhập trong form chỉ được phép trỏ ra Internet trên các cổng 80, 443, 8080 hoặc 8443; để sử dụng địa chỉ nội bộ, hãy lưu nhà cung cấp trước rồi mới kiểm tra. | | Thành phần phụ thuộc | Module **AI** đang bật. Đối với Agent, xem [AI Agent](https://nexcmp.com/vi/docs/ai/ai-agent/#requirements). | ## Chuẩn bị hạ tầng {#prepare-the-infrastructure} 1. Đăng ký với nhà cung cấp và tạo API key. Nếu nhà cung cấp hỗ trợ ngân sách hoặc rate limit, hãy đặt hạn mức hàng tháng. 2. Ghi lại **base URL** và chính xác **tên model** (cùng tối đa bốn fallback model tùy chọn). 3. Kiểm tra kết nối từ server NexCMP trước khi nhập: ```bash curl -s https://ai.example.com/v1/chat/completions \ -H "Authorization: Bearer XXXX" -H "Content-Type: application/json" \ -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Reply with one word: OK"}]}' ``` Phản hồi JSON có `choices[0].message.content` đồng nghĩa endpoint hoạt động bình thường. ## Kết nối trong NexCMP {#connect-in-nexcmp} 1. Mở **System › Settings › AI provider**. 2. Tại thẻ **Module AI**, gạt module sang **on**. Cho đến khi được bật, khách hàng sẽ không thấy AI Chat hoặc AI Agent trên portal. (Bạn cũng có thể bật tính năng này trong **License & updates**.) 3. Tại thẻ **Connection**, điền: | Trường | Ví dụ | Ghi chú | |---|---|---| | Use this provider | bật | Cần có base URL, model và key để bật. | | Tên hiển thị | `LiteLLM` | Tối đa 60 ký tự. | | Base URL (OpenAI-compatible) | `https://ai.example.com/v1` | `http://` hoặc `https://`, tối đa 300 ký tự, không chứa khoảng trắng. | | Provider API key | `sk-XXXX` | Được lưu trữ dưới dạng mã hóa; sau đó chỉ hiển thị 4 ký tự cuối. Để trống để giữ lại key đã lưu. | | Default model | `gpt-4o-mini` | Chữ cái, chữ số và `- _ . / : @`. | | Fallback models | `gemini-2.5-flash` | Phân tách bằng dấu phẩy, tối đa 4 model. Được sử dụng khi default model gặp sự cố. | | Reasoning effort | Default (not sent) | `Minimal`, `Low`, `Medium` hoặc `High`. Đối với các reasoning model (Gemini, o-series), mức thấp sẽ phản hồi nhanh hơn nhiều. Để Default đối với các model thông thường. | 4. Nhấp vào **Save**, sau đó chọn **Test connection**. Quá trình kiểm tra sẽ gửi một câu hỏi ngắn và hiển thị `Connected — , ms` hoặc lỗi do nhà cung cấp trả về. ![Trang AI provider với module AI đã được bật và form kết nối đã được điền các giá trị mẫu](https://nexcmp.com/vi/docs/images/ai/ai-providers-01-connection.webp) ### Cơ chế hoạt động khi lưu {#what-saving-does} - Cấu hình nhà cung cấp được lưu dưới dạng một mục cấu hình duy nhất và key được mã hóa bằng AES-256-GCM cho mục đích này bằng master key của bản cài đặt. - Cài đặt hỗ trợ **Primary model** và **Fallback model** (được AI Chat sử dụng) sẽ tự động được gán thành default model và fallback model đầu tiên của bạn. - Thay đổi được ghi vào audit log (endpoint, model, trạng thái thay đổi key — tuyệt đối không ghi lại key). ## Kiểm tra {#verify} 1. **Test connection** hiển thị màu xanh lá. 2. Đăng nhập vào portal với tư cách khách hàng thử nghiệm: menu lúc này sẽ hiển thị **AI Chat** (hoặc bong bóng chat) và **AI Agent**. 3. Hỏi AI Chat "What is my balance?". Câu trả lời trích dẫn đúng số dư thực tế cho thấy provider xử lý tool calls chính xác. ## Hạn mức & lưu ý {#limits-notes} - **Một provider duy nhất.** NexCMP sử dụng một provider được cấu hình duy nhất cho Chat, Agent và điều tra ticket. Các model dự phòng mang lại khả năng dự phòng linh hoạt trong chính provider đó. - **Bảo mật key.** Key đã lưu chỉ được gửi đến endpoint đã lưu. Nếu bạn thay đổi Base URL, bạn phải nhập lại key trước khi kiểm tra. - **Giới hạn theo từng khách hàng.** AI Chat chỉ dành cho khách hàng đã đăng nhập, có giới hạn tin nhắn theo phút và theo phiên chat. Agent có giới hạn số lượt gọi hàng ngày cho mỗi tài khoản. Xem [AI Chat](https://nexcmp.com/vi/docs/ai/ai-chat/) và [AI Agent](https://nexcmp.com/vi/docs/ai/ai-agent/). - **Quyền riêng tư.** Các câu hỏi của khách hàng và dữ liệu AI đọc cho khách hàng đó (chỉ đọc) sẽ được gửi đến provider của bạn. Hãy nêu rõ điều này trong [chính sách quyền riêng tư](https://nexcmp.com/vi/docs/customers/legal/) của bạn. - **Kiểm soát chi phí.** NexCMP không đo lường chi phí AI; hãy sử dụng các tính năng quản lý ngân sách của chính provider. - Module có thể tắt bất cứ lúc nào: các mục menu AI sẽ biến mất và các route AI sẽ trả về 404 `module_disabled`. Một số tác vụ nền của AI Chat (điều tra ticket, phản hồi trễ) sẽ áp dụng thay đổi ở lần khởi động lại tiếp theo của panel. ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | `base_url must be an http(s) URL` | Thiếu scheme hoặc khoảng trắng | Dùng `https://host/v1`. | | `api_key is required to enable the provider` | Chưa lưu key | Nhập key và lưu. | | `base_url and model are required to enable the provider` | Trường để trống | Điền cả hai. | | "Base URL bị chặn: chỉ http(s) công khai, cổng 80/443/8080/8443" | Kiểm tra địa chỉ nội bộ chưa lưu hoặc port khác | Lưu provider trước, sau đó kiểm tra. | | `api_key is required (enter the key again when you change the endpoint)` | Base URL khác với URL đã lưu | Nhập lại key. | | `model: letters, digits and - _ . / : @` | Ký tự không hợp lệ | Dùng chính xác model ID của provider. | | `fallback_models: up to 4 model names` | Quá nhiều | Giữ tối đa 4 model. | | Kiểm tra thất bại với mã 401 | Sai khóa | Kiểm tra key và endpoint. | | Kiểm tra thất bại với mã 404 hoặc "model not found" | Sai đường dẫn hoặc model | Kiểm tra base URL (`/v1`) và model ID. | | `Too many tests — wait a minute` (429) | Hơn 10 lượt kiểm tra mỗi phút | Chờ một lát. | | Portal vẫn không hiển thị menu AI | Module đang tắt hoặc provider chưa ở trạng thái "in use" | Bật module và kích hoạt provider. | --- # AI Chat {#ai-chat} > **Vị trí trong admin:** Customers › Support › Ticket, tab **AI settings** (`/support/tickets?tab=settings`). Provider và module: System › Settings › AI provider (`/settings/ai`). **Vị trí trong portal:** nút chat nổi và trang `/chat` (chế độ **Ask AI**). ## Chức năng {#what-it-does} AI Chat giải đáp thắc mắc của khách hàng bất cứ lúc nào, tra cứu dữ liệu tài khoản của *chính họ* (số dư, dịch vụ, thanh toán, lỗi gần đây) và có thể thay họ thao tác — tạo VM, đổi gói dịch vụ — sau khi khách hàng xác nhận. Khi trợ lý không thể hỗ trợ, khách hàng nhấn **Talk to a human**: cuộc trò chuyện sẽ được chuyển đến nhân viên của bạn trên Telegram và nếu không ai phản hồi kịp thời, nó sẽ chuyển thành ticket. Các cài đặt AI tương tự cũng cho phép hệ thống **điều tra ticket** hỗ trợ nhân viên của bạn. ## Yêu cầu {#requirements} | Hạng mục | Yêu cầu | |---|---| | Module và provider | Module **AI** đang bật cùng một [AI provider](https://nexcmp.com/vi/docs/ai/ai-providers/) đã được lưu và đang sử dụng. Nếu không có provider, trợ lý sẽ báo chưa được cấu hình. | | Khách hàng | **Chỉ dành cho khách hàng đã đăng nhập.** Bản cài đặt NexCMP không có trang công khai bên ngoài, vì vậy khách truy cập chưa đăng nhập sẽ thấy thông báo "Sign in to use AI Chat". | | Kênh nhân viên (tùy chọn) | Một bot và nhóm chat Telegram để nhận cảnh báo quản trị (xem [Telegram notifications](https://nexcmp.com/vi/docs/administration/telegram-notifications/)). Kênh này cũng dùng để nhận chuyển giao đoạn chat và các bản nháp ticket. | | Thành phần phụ thuộc | [AI provider](https://nexcmp.com/vi/docs/ai/ai-providers/). | ## Chuẩn bị hạ tầng {#prepare-the-infrastructure} Không yêu cầu gì thêm ngoài AI provider. Nếu bạn muốn chuyển tiếp cho nhân viên: 1. Tạo một bot Telegram bằng @BotFather và lưu lại token. 2. Tạo một nhóm hoặc dùng đoạn chat riêng của bạn với bot, rồi lưu lại chat ID. 3. Nhập cả hai thông tin tại System › Settings › Admin alerts (xem [Telegram notifications](https://nexcmp.com/vi/docs/administration/telegram-notifications/)). Các tính năng hỗ trợ sẽ dùng lại bot và chat này. ## Kết nối trong NexCMP {#connect-in-nexcmp} 1. Đảm bảo AI module đã bật và kiểm tra kết nối provider hiển thị màu xanh ([AI provider](https://nexcmp.com/vi/docs/ai/ai-providers/)). 2. Mở **Customers › Support › Ticket** và chọn tab **AI settings**. Phía trên thẻ bên trái hiển thị ba thẻ trạng thái: *AI provider: configured*, *Telegram: channel present* và *On shift* hoặc *Off shift*. 3. Thẻ bên trái **AI + Telegram**: | Công tắc hoặc trường | Mặc định | Ý nghĩa | |---|---|---| | AI tự động điều tra ticket | On | Đối với ticket hoặc tin nhắn mới, AI sẽ đọc dữ liệu khách hàng (chỉ đọc) rồi ghi lại nguyên nhân khả dĩ cùng bản nháp phản hồi dưới dạng **internal note**. AI không bao giờ tự ý gửi cho khách hàng. | | Cảnh báo Telegram tới admin | On | Ghi chú sẽ được gửi tới Telegram kèm theo các nút Send, Edit và Skip. | | AI auto-reply | Tắt | Tự động gửi câu trả lời hướng dẫn sử dụng đơn giản hoặc báo giá khi thỏa mãn mọi điều kiện an toàn (độ tin cậy từ 85 % trở lên, không có cảnh báo); gửi sau 3 phút và có thể hủy qua Telegram. | | Danh mục được phép tự động phản hồi | `how_to`, `sales` | Chỉ các danh mục này. | | Mô hình chính, mô hình dự phòng | thiết lập từ provider | Thông thường giữ nguyên theo cấu hình đã lưu trên trang AI provider. | | ID người dùng Telegram được phép thao tác | để trống | Để trống đồng nghĩa với nhóm chat của kênh cảnh báo. | 4. Thẻ bên phải **Live chat (customer widget)**: | Trường | Mặc định | Ý nghĩa | |---|---|---| | Enable chat widget | On | Bong bóng chat và trang `/chat`. | | Khung giờ hỗ trợ (giờ Việt Nam) | `08:00-22:00` | Khung giờ nhân viên trực để trả lời trên Telegram. Ngoài khung giờ này, hoặc khi chưa cấu hình kênh Telegram, bấm **Talk to a human** sẽ chuyển đoạn chat thành ticket ngay lập tức. | | Thời gian chờ nhân viên tối đa (phút), sau đó chuyển thành ticket | 10 | 1 đến 240. | | Lượt AI / ngày / khách hàng | 40 | 1 đến 1000. Sau khi chạm hạn mức, trợ lý ảo sẽ mời khách hàng kết nối với nhân viên hỗ trợ. | | Phiên chat mới / giờ / IP | 20 | 1 đến 1000. | | **Zalo OA link** | để trống | `https://zalo.me/...` Hiển thị nút **Chat on Zalo** (kèm mã QR) trong khung chat. Để trống sẽ ẩn đi. | | **Telegram link** | để trống | `https://t.me/...` Hiển thị nút **Telegram**. Để trống sẽ ẩn đi. | | Giới hạn lượt AI hàng ngày toàn hệ thống, khách hàng đã đăng nhập | 2000 | | | Giới hạn hàng ngày toàn hệ thống, khách vãng lai | 500 | Pool riêng; không được sử dụng khi khách vãng lai không thể chat. | | Giới hạn điều tra ticket tự động hàng ngày trên toàn hệ thống | 200 | | | Đường dẫn admin (nút Telegram "Open admin") | để trống | URL admin của bạn, ví dụ `https://cloud.example.com/admin`. | Mỗi nút gạt hoặc trường sẽ tự động lưu khi bạn thay đổi. 5. Ở phía dưới, **Reply templates** (tiêu đề, ngôn ngữ VI/EN/ZH, nội dung tối đa 4,000 ký tự) cung cấp các câu trả lời soạn sẵn cho nhân viên. ![Tab cài đặt AI với các nút gạt AI và Telegram cùng giới hạn live chat và liên kết phím tắt](https://nexcmp.com/vi/docs/images/ai/ai-chat-01-settings.webp) ![Trang chat của khách hàng với trợ lý ảo, các nút phím tắt Zalo và Telegram cùng tùy chọn trò chuyện với nhân viên hỗ trợ](https://nexcmp.com/vi/docs/images/ai/ai-chat-02-portal.webp) ## Những điều trợ lý ảo có thể và không thể làm {#what-the-assistant-can-and-cannot-do} - **Đọc:** trợ lý tìm kiếm trong cơ sở tri thức và tài liệu công khai của bạn, đồng thời đọc dữ liệu riêng của khách hàng đã đăng nhập thông qua các công cụ chỉ đọc. Trợ lý không thể xem dữ liệu của khách hàng khác. - **Thực thi:** trợ lý sử dụng quyền API riêng của khách hàng. Thao tác *đọc* sẽ chạy ngay lập tức. Bất kỳ thao tác nào làm thay đổi dữ liệu hoặc phát sinh chi phí sẽ tạo một **thẻ xác nhận** ("Needs your confirmation", với thẻ *Costs money* hoặc *Delete*); không có gì xảy ra cho đến khi khách hàng nhấp vào **Confirm**. Một phiên chat có thể chứa tối đa 3 thẻ đang chờ và một tài khoản có tối đa 10 thao tác ghi đã xác nhận mỗi giờ. - **Tuyệt đối không:** trợ lý không thể mở console, tạo token SSH hoặc console, tải xuống tệp truy cập Kubernetes, đặt lại mật khẩu, hoặc hiển thị thông tin bí mật như mật khẩu proxy hay S3 secret. Các thông tin bí mật không bao giờ được đưa vào context của mô hình hoặc lịch sử chat. - **An toàn:** câu trả lời của trợ lý phải đi qua bộ lọc đầu ra; văn bản của khách hàng và kết quả từ công cụ được xử lý dưới dạng dữ liệu, không phải là chỉ thị. - **Banner minh bạch:** khung chat hiển thị "Answered by an AI assistant — it may be imperfect. Talk to a human for anything critical." ## Chuyển tiếp cho nhân viên {#staff-hand-off} 1. Khách hàng nhấp vào **Talk to a human** và có thể để lại email. 2. Một tin nhắn chứa nội dung cuộc trò chuyện sẽ được gửi đến nhóm Telegram của nhân viên. Nhân viên trả lời bằng cách reply tin nhắn đó; câu trả lời sẽ xuất hiện trong khung chat của khách hàng dưới tên "[brand] Support". 3. Nếu không có ai trả lời trong thời gian chờ (mặc định 10 phút), cuộc trò chuyện sẽ chuyển thành ticket trong **Customers › Support › Ticket**. Trường hợp tương tự cũng diễn ra ngay lập tức ngoài giờ hỗ trợ hoặc khi chưa cấu hình Telegram, và khách hàng sẽ được thông báo rằng ticket đã được mở. 4. Quản trị viên cũng có thể xem các phiên chat đang diễn ra trong tab **Live chat**. ## Kiểm tra {#verify} 1. Đăng nhập với tư cách khách hàng thử nghiệm, mở khung chat và đặt câu hỏi về dịch vụ của bạn. Trợ lý ảo sẽ trả lời. 2. Yêu cầu trợ lý tạo một tài nguyên phát sinh chi phí: thẻ xác nhận sẽ xuất hiện và không có gì được tạo cho đến khi bạn nhấp vào **Confirm**. 3. Nhấp vào **Talk to a human**. Tin nhắn sẽ gửi đến nhóm Telegram của bạn (nếu đã cấu hình) hoặc ticket sẽ xuất hiện sau thời gian chờ. 4. Khi điền đầy đủ liên kết Zalo và Telegram, cả hai nút phím tắt sẽ xuất hiện trong khung chat. ## Hạn mức & lưu ý {#limits-notes} - **Giới hạn tần suất (mỗi IP):** 20 tin nhắn mỗi phút và một số ít lượt chuyển tiếp mỗi giờ; **40 tin nhắn mỗi cuộc trò chuyện**. Các giới hạn này là cố định. - **Chi phí:** mỗi lượt trao đổi của AI đều gọi tới nhà cung cấp của bạn. Hãy giảm **AI turns / day / customer** để giới hạn chi phí. - **Tính năng tự động trả lời bị tắt theo mặc định.** Chỉ bật tính năng này sau khi bạn đã theo dõi các bản nháp một thời gian. - **Ngôn ngữ:** trợ lý ảo trả lời bằng ngôn ngữ của khách hàng; tiếng Việt được nhận diện tự động từ văn bản. - **Đại lý (Reseller):** các trang đại lý sử dụng ticket thay vì widget chat. ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | Khách hàng không nhìn thấy khung chat | Module AI bị tắt, hoặc **Enable chat widget** đang tắt | Bật cả hai mục. | | "Đăng nhập để sử dụng AI Chat" | Khách truy cập chưa đăng nhập | Đúng như dự kiến trong NexCMP: hãy đăng nhập trước. | | Trợ lý thông báo chưa cấu hình AI provider | Thiếu provider, chưa được kích hoạt hoặc thiếu key | Hoàn tất cấu hình [AI provider](https://nexcmp.com/vi/docs/ai/ai-providers/). | | AI phản hồi "talk to a human" sau vài câu hỏi | Đã đạt giới hạn hằng ngày của mỗi khách hàng | Tăng giá trị **AI turns / day / customer**. | | Thẻ Telegram hiển thị "no channel" | Chưa cấu hình bot hoặc chat ID | Thiết lập [Telegram notifications](https://nexcmp.com/vi/docs/administration/telegram-notifications/). | | Nút Zalo hoặc Telegram không hiển thị | Trường liên kết đang để trống | Điền thông tin liên kết. | | Thông báo "Too many requests" trong khung chat | Quá 20 tin nhắn mỗi phút từ một IP | Chờ một phút. | | Cuộc trò chuyện đã đầy | Đã đạt giới hạn 40 tin nhắn | Bắt đầu một cuộc trò chuyện mới. | --- # AI Agent {#ai-agent} > **Vị trí trong trang admin:** System › Settings › AI provider (`/settings/ai`) — công tắc kích hoạt module và provider; System › Admin › License & updates (`/license`) — công tắc module. **Vị trí trong portal:** AI Agent (`/ai/agent`) và trang `/chat/agent`, hoặc chế độ **Agent** bên trong khung chat. ## Chức năng {#what-it-does} AI Agent kết nối tới VM Linux của khách hàng qua SSH và thực hiện các tác vụ được mô tả bằng ngôn ngữ tự nhiên: "kiểm tra tình trạng hệ thống", "cài đặt Docker", "tìm các lỗi gần đây", "giải phóng dung lượng đĩa". Hệ thống hiển thị từng lệnh được đề xuất và kết quả đầu ra tương ứng. Các lệnh chỉ đọc có thể tự động thực thi; bất kỳ thao tác nào làm thay đổi máy chủ đều phải đợi khách hàng nhấn **Run**. ## Yêu cầu {#requirements} | Hạng mục | Yêu cầu | |---|---| | Module AI và provider | Module **AI** đang bật và [AI provider](https://nexcmp.com/vi/docs/ai/ai-providers/) đang hoạt động. Agent cũng cần một model hỗ trợ tool calling. | | `openssh-client` trên máy chủ panel | Agent chạy các lệnh bằng chương trình `ssh` có sẵn trên panel (`/usr/bin/ssh`). Trình cài đặt sẽ cài `openssh-client`; kiểm tra bằng lệnh `ssh -V`. Nếu thiếu, Agent sẽ báo lỗi "ssh client is not installed on the panel server". | | Không cần SSH gateway riêng | Trong bản cài đặt mặc định, SSH tích hợp sẵn sẽ được sử dụng và **không** cần đến web terminal `ssh-proxy`. Chỉ khi tính năng *web SSH* tùy chọn (`feature_ssh_web`) được kích hoạt và dịch vụ `ssh-proxy` đã được cài đặt thì Agent mới chuyển qua kết nối thông qua `ssh-proxy`. | | Mạng | Máy chủ panel phải kết nối được tới IP của VM qua cổng SSH (mặc định là 22). Hãy kiểm tra tường lửa và security group giữa panel với mạng guest. | | VM | Thuộc sở hữu của khách hàng, đang **running**, không bị khóa, chạy hệ điều hành **Linux** (từ chối VM Windows), có địa chỉ IP công khai hoặc có thể truy cập được. | | Thông tin đăng nhập SSH | Tên người dùng và mật khẩu đăng nhập của VM do NexCMP lưu trữ (được mã hóa và lưu lại khi tạo VM hoặc khi đặt lại mật khẩu), hoặc SSH key vận hành của panel nếu có cài đặt. Nếu không có thông tin nào, Agent sẽ thông báo không thể đăng nhập. | ## Chuẩn bị hạ tầng {#prepare-the-infrastructure} 1. Kiểm tra SSH client trên máy chủ panel: ```bash ssh -V sudo apt-get install -y openssh-client # only if missing ``` 2. Kiểm tra máy chủ panel có thể mở kết nối SSH tới guest VM: ```bash nc -vz 198.51.100.10 22 ``` Thay thế địa chỉ bằng IP của một VM thử nghiệm. Nếu kết nối thất bại, hãy khắc phục sự cố định tuyến hoặc tường lửa trước. 3. Hãy đảm bảo máy khách cho phép đăng nhập bằng mật khẩu đối với người dùng được NexCMP lưu trữ (một số image đám mây tắt tính năng này), hoặc operations key của panel đã được cài đặt trên máy khách. ## Kết nối trong NexCMP {#connect-in-nexcmp} 1. Hoàn tất [AI provider](https://nexcmp.com/vi/docs/ai/ai-providers/): bật module, lưu provider, **Test connection** hiển thị màu xanh lá. 2. Không cần cấu hình thêm gì khác ở phía quản trị viên. Công tắc module sẽ hiển thị các mục **AI Agent** trong cổng thông tin khách hàng. 3. Dưới vai trò khách hàng: mở **AI Agent**, chọn một máy chủ đang chạy và nhấp vào **Choose server**. Trang trước tiên sẽ kiểm tra SSH bằng một lệnh an toàn cố định (không dùng lệnh gọi AI) và hiển thị *SSH connected* hoặc lý do thất bại. 4. Nhập tác vụ hoặc chọn một tác vụ nhanh (*Check system health*, *Install Docker*, *Install Nginx*, *Find recent errors*, *Security check*, *Free up disk space*). ## Cách thực thi lệnh {#how-it-runs-commands} - **Từ đâu:** từ máy chủ panel, sử dụng client `ssh` của hệ thống, từng lệnh không tương tác tại một thời điểm. Mục tiêu luôn là IP của VM **từ cơ sở dữ liệu**, không bao giờ lấy từ request; chỉ có thể truy cập VM đang chạy, không bị khóa của chính chủ sở hữu. - **Xác thực:** mật khẩu đã lưu được truyền qua một helper `SSH_ASKPASS` dùng một lần trong biến môi trường tiến trình — mật khẩu không được ghi vào ổ đĩa hay đặt trên dòng lệnh. Host key không được ghim cố định (VM được cài đặt lại với key mới). Đầu ra cho mỗi lệnh được giới hạn ở mức 200 KB và mỗi lệnh có giới hạn thời gian (60 giây). - **Vòng lặp Agent:** AI đề xuất các lệnh và đọc đầu ra; một lượt kết thúc sau tối đa **10 bước**. - **Các chế độ:** | Chế độ | Hành vi | |---|---| | **Confirm** | Mọi lệnh đều chờ **Run**. | | **Auto** | Chỉ các lệnh vượt qua danh sách cho phép nghiêm ngặt chỉ đọc mới tự chạy (ví dụ `df -h`, `ps`, `journalctl`). Bất kỳ lệnh nào khác và bất kỳ lệnh nào trình phân tích cú pháp không thể phân tích chắc chắn (biến số, thay thế lệnh, chuyển hướng tệp) đều phải chờ **Run**. | - **Nhãn rủi ro:** các lệnh ghi đè hoặc xóa tệp, ghi vào ổ đĩa, thay đổi tài khoản hoặc SSH Keys, gửi dữ liệu đến máy chủ bên ngoài, mở kết nối mạng thô, chạy mã bị làm mờ, tải xuống và chạy script, tắt hoặc khởi động lại máy, hay truy cập máy chủ khác luôn hiển thị **Needs confirmation**, ngay cả trong chế độ Auto. - **Đầu ra không tin cậy:** đầu ra của lệnh được hiển thị cho mô hình dưới dạng dữ liệu không tin cậy; các chỉ dẫn bên trong đầu ra sẽ không được làm theo. ## Kiểm tra {#verify} 1. Chọn một VM thử nghiệm đang chạy. Trang hiển thị *SSH connected*. 2. Yêu cầu "Check CPU, RAM and disk". Ở chế độ Auto, các lệnh chỉ đọc sẽ chạy và câu trả lời tóm tắt kết quả của chúng. 3. Yêu cầu "Install Nginx". Lệnh cài đặt xuất hiện kèm **Run** và **Skip**; không có gì chạy cho đến khi bạn nhấn **Run**. 4. Bộ đếm ở trên cùng hiển thị số lượt gọi AI đã dùng hôm nay (ví dụ `3/300`). ## Hạn mức & lưu ý {#limits-notes} - **Giới hạn hàng ngày:** 300 lượt gọi AI cho mỗi khách hàng mỗi ngày (UTC); giới hạn đặt lại vào 00:00 UTC. Khi hết hạn ngạch, Agent sẽ trả lời "Daily AI quota reached". - **Tính đồng thời:** tối đa 2 tác vụ Agent chạy cùng lúc cho mỗi khách hàng; một phiên chỉ chạy một lượt tại một thời điểm. - **Phiên làm việc:** tối đa 100 tin nhắn mỗi phiên, 4,000 ký tự mỗi tin nhắn. Phiên làm việc thuộc về một VM; nếu VM bị xóa hoặc chuyển giao, phiên làm việc cũ sẽ chuyển sang trạng thái chỉ đọc. - **VM bị khóa, dừng hoặc Windows:** VM sẽ hiển thị là *Locked*, *Stopped*, *Windows* hoặc *No address* và không thể chọn. - **Mạo danh:** quản trị viên đang mạo danh khách hàng không thể sử dụng các tính năng thông tin xác thực của Agent (xem [Log in as a customer](https://nexcmp.com/vi/docs/customers/login-as/)). - **Trách nhiệm:** Agent có thể mắc lỗi. Cổng thông tin luôn nhắc khách hàng xem xét kỹ các lệnh trước khi chạy. Hãy nêu rõ trong điều khoản của bạn rằng khách hàng chịu trách nhiệm về các lệnh mà họ phê duyệt. - Tắt module AI sẽ gỡ bỏ các mục Agent và các tuyến đường sẽ phản hồi 404 `module_disabled`. ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | "ssh client chưa được cài đặt trên panel server (apt install openssh-client)" | Không có binary `ssh` | `sudo apt-get install -y openssh-client`. | | "Agent không thể đăng nhập" / `ssh: no saved credentials for this VM` | Không có mật khẩu được lưu và không có operations key | Đặt lại mật khẩu VM trong portal để lưu lại, hoặc cài đặt operations key. | | "Máy chủ không phản hồi kịp thời" | Tường lửa, SSH không lắng nghe, VM đang bận | Kiểm tra `nc -vz 22` từ panel server; khởi động `sshd` trong VM. | | "Không thể kết nối SSH trên máy chủ này" | Định tuyến hoặc security group | Cho phép panel server kết nối tới VM qua cổng 22. | | "VM không chạy" / "Forbidden" | VM đã dừng, bị khóa, đã xóa hoặc không thuộc về khách hàng | Khởi động VM, mở khóa hoặc chọn VM khác. | | "Không khả dụng: N (đã dừng, bị khóa hoặc Windows)" | Các nguyên nhân được liệt kê ở trên | VM phải là Linux và đang chạy. | | "SSH gateway tạm thời không khả dụng" | Tính năng Web SSH đã bật nhưng `ssh-proxy` không hoạt động | Khởi động `ssh-proxy`, hoặc tắt tính năng web SSH để sử dụng SSH tích hợp sẵn. | | "AI phản hồi quá chậm (quá 90 giây)" | Provider phản hồi chậm | Sử dụng model nhanh hơn hoặc giảm **Reasoning effort**. | | "Đã đạt hạn mức AI hàng ngày" | Đã sử dụng hết 300 lượt gọi | Chờ đến 00:00 UTC. | | "Phiên này vẫn đang chạy" | Một lượt phản hồi khác đang diễn ra | Chờ hoặc nhấn **Stop**. | --- # REST API > **Vị trí trong portal:** API reference tại `https:///apidoc` (công khai) và API keys tại `/api-keys`. **Vị trí trong admin:** Customers › API keys (`/customers/apikeys`) liệt kê các khóa do khách hàng tạo. ## Chức năng {#what-it-does} Mọi thao tác khách hàng có thể thực hiện trên portal — xem danh sách và điều khiển VM, xem hóa đơn, quản lý SSH Keys, Kubernetes, lưu trữ, ticket hỗ trợ — đều khả dụng qua REST API có phân phiên bản tại `https:///v1/`. Khách hàng gọi API này từ script và CI bằng **API key** có giới hạn phạm vi. Cùng API này cũng cung cấp dữ liệu cho [`cmp` công cụ dòng lệnh](https://nexcmp.com/vi/docs/developers/cmp-cli/) và [MCP server](https://nexcmp.com/vi/docs/developers/mcp/), đồng thời tài liệu tham khảo được tạo trực tiếp từ bản cài đặt đang chạy, nên luôn liệt kê chính xác các tính năng mà bạn đã bật. ## Yêu cầu {#requirements} | Hạng mục | Yêu cầu | |---|---| | Địa chỉ HTTPS công khai | API được phân phối trên domain chính của bạn (và trên domain riêng của từng reseller). | | Một API key | Do khách hàng tạo trong portal; xem [API keys](https://nexcmp.com/vi/docs/developers/api-keys/). | | Thành phần phụ thuộc | Không có. Các endpoint của module bạn không bật (ví dụ Kubernetes hoặc Object Storage) sẽ bị ẩn khỏi tài liệu tham khảo và bị từ chối truy cập. | ## Chuẩn bị hạ tầng {#prepare-the-infrastructure} Không cần cài đặt gì thêm. Nếu có reverse proxy phía trước NexCMP, hãy chuyển tiếp `/v1/`, `/mcp`, `/cli/` và `/apidoc` tới panel (cấu hình nginx của bộ cài đặt đã thiết lập sẵn điều này). ## Kết nối trong NexCMP {#connect-in-nexcmp} ### Tài liệu tham khảo tương tác {#the-interactive-reference} Mở `https://cloud.example.com/apidoc` (thay thế host bằng tên miền của bạn; khách hàng của reseller sẽ thấy tài liệu tham khảo trên tên miền của reseller, với tên của reseller). Trang này chứa tài liệu endpoint kèm ví dụ request và response bằng curl, `cmp` CLI, JavaScript, Python và Go, ô tìm kiếm (Ctrl hoặc Cmd + K), cùng bảng điều khiển **Try it**. Try it chỉ gửi request đến cùng một site, sử dụng key do người truy cập dán vào (được lưu trong phiên trình duyệt); chế độ này mặc định là chỉ đọc, và các lệnh ghi hoặc lệnh có tính phí cần có thêm công tắc kích hoạt và xác nhận. ### Bản tải về và tài liệu máy đọc được {#downloads-and-machine-readable-documents} Tất cả đều công khai, không cần key và được tạo riêng cho từng site: | URL | Nội dung | |---|---| | `/apidoc` | Tài liệu tham khảo tương tác. | | `/v1/public/openapi.json` | Tài liệu OpenAPI 3.1. | | `/v1/public/openapi.yaml` | Tương tự, định dạng YAML. | | `/v1/public/postman.json` | Postman collection. | | `/v1/public/insomnia.json` | Bản xuất Insomnia. | | `/v1/public/api.md` | Tài liệu tham khảo dưới dạng một tệp Markdown duy nhất. | | `/v1/public/api-catalog` | JSON rút gọn: thương hiệu, base URL, tiền tố key, mọi scope và từng endpoint kèm method, path, scope cùng thông tin có yêu cầu `Idempotency-Key` hay không. | ```bash curl -s https://cloud.example.com/v1/public/api-catalog | python3 -m json.tool | head -40 curl -sO https://cloud.example.com/v1/public/openapi.yaml ``` Trong Postman, chọn **Import › Link** và dán `https://cloud.example.com/v1/public/postman.json`. Trang tài liệu tham khảo cũng cung cấp API client dạng tệp đơn cho JavaScript và Python. ### Xác thực {#authentication} Gửi key trong header `Authorization`: ```bash curl -s https://cloud.example.com/v1/billing/wallet \ -H "Authorization: Bearer vk_XXXX" ``` - Key của khách hàng bắt đầu bằng `vk_`. Các key đều **gắn liền với site**: key được tạo trên `cloud.example.com` sẽ không hoạt động trên tên miền của reseller. - Token phiên trình duyệt (`pt_...`) chỉ dành riêng cho portal; hãy sử dụng key để tự động hóa. - Các **scope** của key quyết định những gì key có thể gọi; thiếu scope sẽ trả về HTTP 403 `scope_required`. Xem [API keys](https://nexcmp.com/vi/docs/developers/api-keys/). - Kiểm tra key bằng `GET /v1/apikeys/self`: trả về tên, scope, thời hạn của key đang gọi và hạn mức rate limit còn lại (mọi key đều có thể gọi endpoint này). ### Ví dụ {#examples} ```bash # List virtual machines curl -s "https://cloud.example.com/v1/vm?page=1" -H "Authorization: Bearer vk_XXXX" # Start one (needs vm:write) curl -s -X POST https://cloud.example.com/v1/vm/3f2a1c9e-0000-4000-8000-000000000000/start \ -H "Authorization: Bearer vk_XXXX" # Create a VM (paid: needs vm:create and an Idempotency-Key) curl -s -X POST https://cloud.example.com/v1/vm \ -H "Authorization: Bearer vk_XXXX" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d @vm.json ``` Lấy các trường request chính xác của từng thao tác từ `/apidoc`. ### Lỗi {#errors} Mỗi lỗi đều là JSON với `code` cố định và `message` dễ đọc: ```json {"error": {"code": "scope_required", "message": "Key lacks scope vm:write"}} ``` | HTTP | `code` thường gặp | Ý nghĩa | |---|---|---| | 401 | `unauthenticated`, `key_invalid`, `key_revoked`, `key_expired`, `key_ip_denied`, `site_mismatch`, `api_keys_disabled` | Thiếu key hoặc key không xác định, đã bị thu hồi, hết hạn, IP người gọi nằm ngoài allowlist của key, key từ site khác hoặc API key đã bị tắt. | | 403 | `scope_required`, `endpoint_not_public`, `account_blocked`, `quota_exceeded`, `impersonate_forbidden` | Key thiếu scope; endpoint không khả dụng cho key; tài khoản bị khóa; đã chạm [quota](https://nexcmp.com/vi/docs/billing/quotas/); thao tác không được phép trong phiên mạo danh. | | 404 | `not_found` | Không tìm thấy — cũng được trả về cho các tài nguyên thuộc về người khác. | | 422 | `invalid_argument` | Lỗi xác thực dữ liệu (trường bị lỗi được nêu rõ trong response). | | 429 | `rate_limited` | Quá nhiều request; vui lòng chờ `Retry-After`. | | 503 | `maintenance` | Chế độ bảo trì đang bật: lệnh đọc hoạt động bình thường, lệnh ghi bị từ chối. | ### Rate limit {#rate-limits} | Hạn mức | Mặc định | |---|---| | Mỗi key | 120 request mỗi phút | | Mỗi tài khoản (tất cả các key gộp lại) | 300 request mỗi phút | Mọi response đều chứa `X-RateLimit-Limit`, `X-RateLimit-Remaining` và `X-RateLimit-Reset`; lỗi 429 sẽ có thêm `Retry-After`. ### Idempotency {#idempotency} Các lệnh gây phát sinh chi phí hoặc không thể lặp lại (tạo mới, đổi gói cước, mua, xóa...) **bắt buộc** phải có header `Idempotency-Key` (chuỗi bất kỳ tối đa 200 ký tự; UUID là một lựa chọn tốt). Khi gửi lại cùng một key sau khi bị timeout, máy chủ sẽ trả về kết quả **ban đầu** (kèm `Idempotency-Replayed: 1`) thay vì lặp lại thao tác. Dùng lại key cho một lệnh khác sẽ nhận về lỗi 422; request vẫn đang xử lý sẽ nhận về 409/`Retry-After`. Nếu không có header này, lệnh có tính phí sẽ bị từ chối. ## Kiểm tra {#verify} 1. Tạo một key với scope `vm:read` trong portal (**API keys › Create key**). 2. Chạy: ```bash curl -i https://cloud.example.com/v1/apikeys/self -H "Authorization: Bearer vk_XXXX" ``` Bạn sẽ nhận được mã HTTP 200 cùng các header rate-limit. 3. `curl -s https://cloud.example.com/v1/vm -H "Authorization: Bearer vk_XXXX"` liệt kê các VM của tài khoản. Trong portal, cột **Last used** của khóa và **Key usage log** sẽ hiển thị các lượt gọi. ## Hạn mức & lưu ý {#limits-notes} - **Không bao giờ khả dụng cho khóa:** nạp tiền, rút tiền, đổi thẻ hoặc tự động nạp tiền, đổi mật khẩu, email hoặc 2FA, xóa tài khoản, tạo, chỉnh sửa hoặc thu hồi các khóa khác. Những thao tác này yêu cầu phiên đăng nhập trên trình duyệt. - **Các module bị ẩn:** tài liệu tham khảo và tài liệu OpenAPI chỉ liệt kê các tính năng đã được bật trên trang đó. - **Dung lượng phản hồi và phân trang:** các endpoint dạng danh sách đều được phân trang (`page`, `per_page`); hãy xem tài liệu OpenAPI cho từng endpoint. - **Thời gian và tiền tệ:** tiền tệ tính bằng cent USD trừ khi tên trường có quy định khác. - **Admin API:** trang quản trị admin có trang **System › Admin › API** riêng và các khóa quản trị viên (`ofw_...`) dùng để quản trị; chúng tách biệt với API khách hàng được mô tả tại đây. - **Phiên bản:** tiền tố đường dẫn `/v1` là cố định; các trường mới có thể được thêm vào phản hồi. ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | Lỗi 401 với khóa mới | Khóa từ domain khác, đã hết hạn hoặc chứa khoảng trắng khi nhập | Hãy tạo khóa trên domain bạn gọi tới; kiểm tra header `Authorization: Bearer vk_...`. | | 403 `scope_required` | Thiếu scope | Chỉnh sửa khóa trong portal và thêm scope. | | 401 `key_ip_denied` hoặc `site_mismatch` | Khóa bị giới hạn theo IP khác ("allowed IPs") hoặc được tạo trên domain khác | Thêm IP máy chủ của bạn vào danh sách allowed IPs của khóa, hoặc gọi tới domain nơi khóa được tạo. | | Lỗi 404 với VM đang tồn tại | VM thuộc về tài khoản khác | Sử dụng khóa của chủ sở hữu. | | Lỗi 400/422 yêu cầu `Idempotency-Key` | Thao tác tính phí nhưng thiếu header | Thêm `Idempotency-Key: `. | | 429 | Vượt quá giới hạn | Giảm tần suất gọi; sử dụng `Retry-After`. | | `/apidoc` hiển thị ít hơn dự kiến | Module đã bị tắt | Bật module trong License & updates. | --- # API key và scope {#api-keys-and-scopes} > **Vị trí trong portal:** API keys (`/api-keys`). **Vị trí trong admin:** Customers › Customers › API keys (`/customers/apikeys`). ## Chức năng {#what-it-does} **API key** cho phép một script, CI job, [`cmp` CLI](https://nexcmp.com/vi/docs/developers/cmp-cli/) hoặc trợ lý AI ([MCP](https://nexcmp.com/vi/docs/developers/mcp/)) gọi [REST API](https://nexcmp.com/vi/docs/developers/api/) thay mặt cho một khách hàng, chỉ với các quyền hạn (**scope**) đã được cấp. Khóa của khách hàng bắt đầu bằng `vk_`. Chúng có thể đọc và quản lý các dịch vụ nhưng **không bao giờ** được can thiệp vào tiền tệ hoặc chính tài khoản đó. ## Yêu cầu {#requirements} | Hạng mục | Yêu cầu | |---|---| | Khách hàng | Một phiên đăng nhập portal (khóa không thể tạo hoặc chỉnh sửa các khóa khác, và quản trị viên đang mạo danh khách hàng cũng không thể). | | Công tắc | API key được bật theo mặc định. Nếu bị tắt, các lượt gọi sẽ nhận phản hồi 401 `api_keys_disabled`. | | Thành phần phụ thuộc | Các scope của một sản phẩm chỉ xuất hiện khi sản phẩm đó được bật trên trang. | ## Tạo khóa (khách hàng) {#create-a-key-customer} 1. Đăng nhập vào portal và mở **API keys**. 2. Nhấp vào **Create key**. 3. Điền thông tin vào biểu mẫu: | Trường | Quy tắc | |---|---| | **Key name** | Bắt buộc, tối đa 60 ký tự ("deploy server", "backup script"). | | **Key này có thể làm gì** | Chọn các scope bạn cần — tối thiểu một scope. Khóa chỉ đọc không nên nhận bất kỳ scope ghi nào. Hãy cẩn trọng với các scope phát sinh chi phí hoặc xóa dữ liệu. | | **Expiry** | Never, 30 ngày, 90 ngày hoặc 1 năm (API chấp nhận từ 1 đến 3650 ngày). | | **Chỉ cho phép lệnh gọi từ các IP này** | Mỗi dòng một IP hoặc dải CIDR, tối đa 20 (IPv4 hoặc IPv6). Để trống nghĩa là mọi IP. Hãy ghim IP máy chủ của bạn bất cứ khi nào có thể. | 4. Xác nhận biểu mẫu. Khóa được hiển thị **một lần duy nhất** trong cửa sổ "Key created — shown ONCE". Hãy sao chép khóa và nhấp vào **I saved the key**. Hệ thống chỉ lưu mã băm SHA-256 nên ngay cả quản trị viên cũng không thể đọc lại khóa; nếu làm mất, bạn cần thu hồi và tạo khóa mới. 5. Portal cũng hiển thị sẵn một lệnh `curl` để kiểm tra khóa. Khóa có tiền tố `vk_` theo sau bởi một chuỗi ký tự ngẫu nhiên dài. Danh sách chỉ hiển thị các ký tự đầu tiên (ví dụ `vk_a1b2c3d4`), scope, thời hạn hết hạn, lần sử dụng gần nhất, số lượng yêu cầu và trạng thái (*Active*, *Expired*, *Revoked*). ### Chỉnh sửa, thu hồi, audit {#edit-revoke-audit} - **Edit** dùng để thay đổi tên, scope, các IP được phép và thời hạn. Thao tác này không được phép trong phiên mạo danh. - **Revoke** dừng hoạt động của khóa ngay lập tức và không thể hoàn tác. Dòng này vẫn được giữ lại để nhật ký sử dụng của khóa tiếp tục khả dụng. - **Key usage log** hiển thị các lệnh ghi và mọi lỗi trong 60 ngày gần nhất: thời gian, yêu cầu, khóa, kết quả và IP nguồn. - Một tài khoản có thể giữ tối đa **10 khóa đang hoạt động** theo mặc định. - Các khóa được tạo qua đăng nhập CLI hoặc MCP sẽ xuất hiện tại **Connected apps & devices** và có thể thu hồi tại đó. ## Scope {#scopes} Tên scope có dạng `area:action`. Các scope khả dụng sẽ phụ thuộc vào những sản phẩm mà bạn đã bật. | Scope | Cho phép | |---|---| | `catalog:read` | Xem các gói dịch vụ và danh mục. | | `vm:read` | Xem VM, chỉ số và hóa đơn VM. | | `vm:write` | Tác vụ nguồn, thay đổi nhỏ, firewall, Snapshots nhanh. | | `vm:create` | **Tạo VM (phát sinh chi phí).** | | `vm:plan` | **Đổi gói hoặc đổi kích thước (phát sinh chi phí).** | | `vm:destroy` | **Xóa VM.** | | `vm:restore` | **Khôi phục VM từ snapshot (ghi đè ổ đĩa).** | | `vm:console` | Mở ticket console VNC. | | `sshkey:read`, `sshkey:write` | Xem, thêm và xóa SSH Keys. | | `volume:read`, `volume:write`, `volume:create`, `volume:destroy` | Data volume (tạo và mở rộng sẽ phát sinh chi phí; hủy sẽ mất dữ liệu). | | `backup:read`, `backup:write`, `backup:restore` | Backups (khôi phục sẽ ghi đè ổ đĩa). | | `billing:read` | Ví, hóa đơn, lịch sử thanh toán — **chỉ đọc**. | | `bandwidth:buy` | **Mua add-on băng thông (phát sinh chi phí).** | | `account:read`, `account:write` | Hồ sơ, tổng quan, hoạt động, thông báo; `account:write` chỉ đánh dấu thông báo là đã đọc. | | `apikey:read` | Liệt kê các khóa của tài khoản và nhật ký sử dụng (không thể tạo, sửa hoặc thu hồi). | | `apikey:self` | Mặc định trên mọi khóa: kiểm tra khóa đang gọi (`GET /v1/apikeys/self`). | | `ticket:read`, `ticket:write` | Ticket hỗ trợ. | | `aff:read`, `transfer:read` | Chương trình affiliate và chuyển nhượng dịch vụ — chỉ đọc. | | `k8s:read`, `k8s:write`, `k8s:create`, `k8s:scale`, `k8s:destroy`, `k8s:kubeconfig` | Kubernetes (tạo và mở rộng quy mô phát sinh chi phí; kubeconfig có quyền cluster-admin). | | `vpc:read`, `vpc:write`, `vpc:create`, `vpc:destroy` | Private Cloud. | | `image:read`, `image:write` | Image OS và ISO (dung lượng lưu trữ được tính phí theo giờ). | | `s3:read`, `s3:write`, `s3:create`, `s3:destroy`, `s3:keys` | Object Storage (S3 secret chỉ được hiển thị một lần). | | `vpn:read`, `vpn:detail`, `vpn:write`, `vpn:create`, `vpn:destroy` | VPN và proxy IPv6 (thông tin kết nối bao gồm mật khẩu proxy). | | `dedicated:read`, `dedicated:write`, `dedicated:console`, `dedicated:create`, `dedicated:destroy` | Máy chủ Dedicated (tạo đơn hàng từ ví; hủy sẽ cài đặt lại OS). | | `shield:read`, `shield:write`, `shield:agent` | DDoS Shield, chỉ khả dụng khi module đó được bật. | Lệnh gọi ngoài scope của key sẽ trả về **403 `scope_required`**; đường dẫn mà không key nào có thể gọi sẽ trả về **403 `endpoint_not_public`**. ### Những thao tác key không bao giờ có thể thực hiện {#what-a-key-can-never-do} Không scope nào cho phép: nạp hoặc rút tiền, đổi thẻ hoặc tự động nạp tiền, đổi mật khẩu, email hoặc 2FA, xóa tài khoản, tạo, sửa hoặc thu hồi key khác. Các thao tác này luôn cần trình duyệt đã đăng nhập. Ngay cả khi bị lộ, key cũng không thể can thiệp vào tiền hay tài khoản của khách hàng. ## Các quy tắc bạn có thể tin cậy {#rules-you-can-rely-on} | Quy tắc | Chi tiết | |---|---| | Gắn liền với site | Key chỉ hoạt động trên site (tên miền) nơi key được tạo. | | Rate limit | Mỗi key và mỗi tài khoản: mặc định 120 và 300 request mỗi phút. | | Idempotency | Các thao tác tốn phí hoặc không thể lặp lại cần có header `Idempotency-Key`. | | Quotas | Key phải tuân theo cùng [quotas](https://nexcmp.com/vi/docs/billing/quotas/) với khách hàng. | | Tài khoản bị khóa | Các key của khách hàng bị khóa sẽ ngừng hoạt động (403 `account_blocked`). | | Audit | Hành động thu hồi của quản trị viên được ghi vào admin audit log. | ## Giao diện quản trị viên {#administrator-view} 1. Mở **Customers › API keys** (`/customers/apikeys`). Bảng hiển thị tên key và các ký tự đầu, chủ sở hữu, scopes, trạng thái, lần dùng gần nhất (thời gian, số lượng request, IP), hạn dùng. 2. Lọc theo site nếu bạn có reseller. Tìm kiếm theo tên, ID hoặc phần đầu của key. 3. Nhấp **Revoke** để vô hiệu hóa một key đang hoạt động, hoặc **Log** để xem lịch sử sử dụng. 4. Quản trị viên **xem và thu hồi** key nhưng không thể đọc hay tạo key thay cho khách hàng. ![Danh sách API key của khách hàng dành cho quản trị viên với scopes, trạng thái, lần dùng gần nhất và nút Revoke](https://nexcmp.com/vi/docs/images/developers/api-keys-02-admin.webp) ## Kiểm tra {#verify} 1. Tạo một key chỉ có scope `vm:read`. 2. `curl -s https://cloud.example.com/v1/vm -H "Authorization: Bearer vk_XXXX"` trả về danh sách VM. 3. `curl -s -X POST .../v1/vm//start -H "Authorization: Bearer vk_XXXX"` trả về 403 `scope_required`. 4. Thu hồi key; lệnh gọi đầu tiên lúc này sẽ trả về 401 `key_revoked`. ## Hạn mức & lưu ý {#limits-notes} - Key sẽ không bao giờ hiển thị lại. Hãy xử lý nó như mật khẩu và lưu trữ trong secret manager hoặc CI secret. - Nên dùng mỗi script một key, scopes tối thiểu, hạn dùng ngắn và allowlist IP; xoay vòng key bằng cách tạo key mới và thu hồi key cũ. - Key từ đăng nhập thiết bị (CLI, MCP) có hạn mặc định là 90 ngày. - Các tài nguyên đã xóa hoặc đã chuyển nhượng không bị ảnh hưởng khi thu hồi key. ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | Lỗi `too_many_keys` (422) | Đã đạt giới hạn số key đang hoạt động (mặc định 10) | Thu hồi một key cũ. | | Lỗi `invalid_argument`: chưa chọn scope | Chưa tích chọn scope nào | Tích chọn ít nhất một scope. | | Lỗi `invalid_argument` ở IP được phép | Một mục không phải IP hoặc dải IP, sai độ dài prefix, hoặc có hơn 20 mục | Mỗi dòng một IP hoặc CIDR, ví dụ `203.0.113.0/24`. | | Thao tác tạo bị từ chối khi đang impersonate | `impersonate_forbidden` | Yêu cầu khách hàng tự tạo key. | | 401 `key_expired` | Đã quá hạn sử dụng | Tạo một key mới. | | 401 `key_ip_denied` | IP của bên gọi không nằm trong allowlist | Thêm IP vào hoặc xóa danh sách. | | 401 `api_keys_disabled` | Tính năng đang tắt | Liên hệ quản trị viên của bạn (cài đặt `api_keys_enabled`). | --- # Công cụ dòng lệnh `cmp` {#cmp-command-line-tool} > **Vị trí trên portal:** các lệnh cài đặt nằm ở tài liệu tham khảo API (`https:///apidoc`, mục Command-line interface). Phê duyệt đăng nhập: `https:///link`. Thiết bị đã kết nối: API keys (`/api-keys`) › Connected apps & devices. ## Chức năng {#what-it-does} `cmp` là một chương trình dòng lệnh nhỏ gọn dành cho khách hàng (và cho chính bạn), biến **mọi thao tác API thành một lệnh**: `cmp vm list`, `cmp vm start `, `cmp billing invoice list`. Chương trình được build từ tài liệu OpenAPI của chính bản cài đặt của **bạn** khi phát hành, do đó các lệnh luôn khớp với những tính năng bạn đã bật. Đây là một file binary tĩnh duy nhất dành cho Linux, macOS và Windows (amd64 và arm64) mà không cần cài đặt thêm gì khác. ## Yêu cầu {#requirements} | Hạng mục | Yêu cầu | |---|---| | Máy chủ | Không cần gì thêm. Các gói phát hành nằm sẵn bên trong bản phát hành NexCMP và được phân phối bởi panel tại `https:///cli/`. | | Máy của khách hàng | Linux, macOS hoặc Windows (PowerShell 5.1+). `ssh-keygen` (OpenSSH 8.0+) chỉ cần thiết để xác minh chữ ký. | | Thông tin xác thực | Đăng nhập qua trình duyệt bằng mã một lần, hoặc một [API key](https://nexcmp.com/vi/docs/developers/api-keys/). | | Mạng | HTTPS tới panel của bạn. CLI từ chối gửi key qua `http://` thông thường ngoại trừ đến `localhost`. | ## Chuẩn bị hạ tầng {#prepare-the-infrastructure} Không cần làm gì. Panel tự phục vụ các tệp này từ `/cli/` (không cần build hay tải lên): | Tệp | Mục đích | |---|---| | `install.sh`, `install.ps1` | Trình cài đặt cho Linux/macOS và Windows; chứa sẵn địa chỉ panel của bạn. | | `latest.json` | Phiên bản hiện tại, danh sách tệp, kích thước, sha256. | | `v/cmp___.tar.gz` hoặc `.zip` | Các chương trình: linux amd64/arm64, darwin amd64/arm64/universal, windows amd64/arm64. | | `v/SHA256SUMS`, `SHA256SUMS.sig` | Mã checksum và chữ ký ed25519 tương ứng. | | `cmp-cli.pub` | Public key của bản phát hành. | ## Cài đặt (khách hàng) {#install-customer} macOS và Linux: ```bash curl -fsSL https://cloud.example.com/cli/install.sh | sh ``` Windows PowerShell: ```powershell irm https://cloud.example.com/cli/install.ps1 | iex ``` Trình cài đặt sẽ chọn gói phù hợp với hệ điều hành và CPU, tải về `SHA256SUMS` cùng chữ ký, xác minh chữ ký bằng key nhúng trong script, kiểm tra hash của gói và cài đặt `cmp` vào `/usr/local/bin` (với quyền root) hoặc `~/.local/bin`; trên Windows vào `%LOCALAPPDATA%\cmp\bin` (được thêm vào `PATH` của người dùng). Nếu có bước kiểm tra thất bại, sẽ không có gì được cài đặt. | Biến | Ý nghĩa | |---|---| | `CMP_VERSION` | Cài đặt phiên bản này thay vì bản mới nhất. | | `CMP_INSTALL_DIR` | Thư mục cài đặt. | | `CMP_REQUIRE_SIGNATURE` | `1` = hủy bỏ khi không thể xác minh chữ ký. | | `CMP_BASE_URL` | URL gốc để tải về (dành cho mirror). | Tải về và xác minh thủ công: ```bash curl -fsSLO https://cloud.example.com/cli/latest.json sha256sum --check --ignore-missing SHA256SUMS ``` ![Mục tài liệu tham khảo API với lệnh cài đặt cmp cho macOS và Linux](https://nexcmp.com/vi/docs/images/developers/cmp-cli-01-install.webp) ## Đăng nhập {#log-in} ```bash cmp login ``` 1. CLI sẽ in ra một **mã** dùng một lần cùng đường dẫn (`https://cloud.example.com/link?code=WDJB-MJHT`), mở trình duyệt và chờ. 2. Trên trình duyệt, đăng nhập vào portal, kiểm tra tên client, thiết bị, IP và quốc gia, chọn các quyền (scope) và thời hạn hiệu lực của key (mặc định 90 ngày). Các quyền gây phát sinh chi phí hoặc xóa dữ liệu mặc định sẽ không được chọn. Bấm approve. 3. CLI sẽ nhận **key riêng**, tách biệt với các key mà khách hàng tự tạo thủ công, và lưu tại `~/.config/cmp/config.json` (mode `0600`; `%APPDATA%\cmp` trên Windows). Key này xuất hiện trong **API keys › Connected apps & devices** và có thể bị thu hồi tại đó. Mã sẽ hết hạn sau 10 phút. Việc phê duyệt yêu cầu một phiên portal đã đăng nhập thực tế với email đã xác minh — không dùng key khác và không dùng phiên mạo danh. Các flag hữu ích: `--scopes vm:read,billing:read`, `--name "build server"`, `--no-browser`, `--profile`, `--api-url`. Đối với CI hoặc máy chủ không có trình duyệt, hãy dùng key từ portal: ```bash printf %s "$KEY" | cmp login --with-token export CMP_TOKEN=vk_XXXX # nothing is written to disk cmp whoami ``` ## Sử dụng các lệnh {#using-commands} ```text cmp [subgroup] [ ...] [flags] ``` - Các path parameter là tham số vị trí; query parameter và trường body sẽ trở thành flag dạng kebab-case (`--start-port 443`). - `--data '{"a":1}'`, `--data @file.json` hoặc `--data -` gửi toàn bộ phần thân JSON; các flag sẽ ghi đè các trường của nó. - `cmp help vm firewall add` (hoặc `--help`) hiển thị thông tin chi tiết của lệnh bất kỳ. ```bash cmp catalog plans cmp vm list --state active --per-page 50 cmp vm get 3f2a1c9e-0000-4000-8000-000000000000 cmp vm start 3f2a1c9e-0000-4000-8000-000000000000 cmp vm firewall add 3f2a1c9e-... --protocol tcp --start-port 22 --cidr-list 203.0.113.0/24 cmp billing wallet cmp api GET /v1/vm --query page=2 # raw call to any endpoint ``` Các lệnh tích hợp sẵn: `login`, `logout`, `whoami`, `config`, `api`, `completion`, `version`, `update`, `help`. Mọi lệnh khác đều lấy từ tài liệu API. Các flag toàn cục: | Flag | Ý nghĩa | |---|---| | `-o, --output json\|table\|yaml` | Định dạng. Mặc định là `table` trên terminal và `json` khi dùng pipe. | | `--profile`, `--api-url` | Thông tin đăng nhập đã lưu nào và trang nào. | | `-y, --yes` | Bỏ qua bước xác nhận đối với các lệnh có tính phá hủy hoặc có tính phí. | | `--idempotency-key ` | Chọn key của một lệnh tính phí. | | `--retry ` | Khi gặp HTTP 429, đợi `Retry-After` và thử lại tối đa n lần. | | `--timeout ` | Số giây chờ response header (mặc định 60). | | `--debug` | Hiển thị quá trình trao đổi HTTP trên stderr, với các key được che. | Các lệnh **trừ tiền ví hoặc xóa dữ liệu** sẽ yêu cầu xác nhận và nếu có tính phí, sẽ gửi `Idempotency-Key` được tạo tự động (được in trên stderr để bạn có thể thử lại an toàn với `--idempotency-key`). Khi không có terminal, lệnh sẽ từ chối thực hiện trừ khi có `--yes`. ### Mã thoát {#exit-codes} | Mã | Ý nghĩa | |---|---| | 0 | Thành công | | 1 | Lỗi khác (mạng, HTTP 4xx/5xx không có trong danh sách) | | 2 | Lỗi sử dụng | | 3 | Không có quyền (401/403) | | 4 | Không tìm thấy (404) | | 5 | Bị giới hạn tốc độ (429) | | 6 | Yêu cầu xác nhận hoặc bị từ chối | | 130 | Bị gián đoạn | ### Profile và môi trường {#profiles-and-environment} `cmp config` liệt kê các profile; `cmp config use ` chuyển đổi; khách hàng của reseller sử dụng domain riêng của họ: `cmp login --api-url https://shop.example.net --profile shop`. Thứ tự ưu tiên: flag, biến môi trường, tệp cấu hình. Các biến: `CMP_TOKEN`, `CMP_PROFILE`, `CMP_API_URL`, `CMP_OUTPUT`, `CMP_CONFIG_DIR`, `CMP_ALLOW_HTTP`, `CMP_UPDATE_URL`. GitHub Actions: ```yaml - name: Install cmp run: | curl -fsSL https://cloud.example.com/cli/install.sh | CMP_INSTALL_DIR="$RUNNER_TEMP/bin" sh echo "$RUNNER_TEMP/bin" >> "$GITHUB_PATH" - name: List running VMs env: CMP_TOKEN: ${{ secrets.CMP_TOKEN }} # a read-only key run: cmp vm list -o json | jq -r '.items[] | select(.cs_state=="Running") | .hostname' ``` Shell completion: `cmp completion bash|zsh|fish|powershell`. ## Cập nhật và gỡ cài đặt {#update-and-uninstall} ```bash cmp version cmp update --check cmp update ``` `cmp update` tải về `latest.json`, `SHA256SUMS` và chữ ký, xác minh chữ ký bằng public key **được tích hợp sẵn trong tệp nhị phân đang chạy**, xác minh hash gói và chỉ sau đó mới tự thay thế. Việc hạ cấp cần có `--force`. Khi bạn cập nhật NexCMP, panel sẽ cung cấp bản phát hành CLI đi kèm với phiên bản mới. Để gỡ cài đặt, hãy xóa tệp nhị phân `cmp` và thư mục cấu hình (`cmp config path` sẽ hiển thị thư mục này). Hãy thu hồi key trong mục **API keys** nếu máy bị mất. ## Kiểm tra {#verify} 1. `cmp version` in ra phiên bản và phiên bản tài liệu API. 2. `cmp login`, phê duyệt trên trình duyệt, sau đó `cmp whoami` sẽ hiển thị profile và URL panel của bạn. 3. `cmp vm list` trả về danh sách VM của bạn; `cmp vm list -o json | jq .` hiển thị JSON thô. ## Hạn mức & lưu ý {#limits-notes} - Danh sách lệnh phụ thuộc vào bản build của bạn: các gói được tạo từ tài liệu OpenAPI của bản cài đặt khi bản phát hành được build, do đó sản phẩm bị tắt trong bản phát hành của bạn sẽ không có lệnh. Sử dụng `cmp api` cho đường dẫn mà CLI không nhận biết. - CLI được phát hành theo giấy phép MIT. - Mỗi gói được ký bằng một ed25519 key; key chữ ký được ghim bên trong trình cài đặt và tệp nhị phân, không được tải về tại thời điểm cập nhật. - Các key bị giới hạn theo từng key và theo từng tài khoản (xem [REST API](https://nexcmp.com/vi/docs/developers/api/#rate-limits)). ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | `curl .../cli/install.sh` trả về 404 | Bản phát hành trên máy chủ không có thư mục CLI, hoặc host không có trong license | Kiểm tra `https:///cli/latest.json` và domain; cập nhật NexCMP. | | "không thể xác minh chữ ký" | `ssh-keygen` bị thiếu hoặc quá cũ | Cài đặt OpenSSH 8.0+, hoặc chỉ đặt `CMP_REQUIRE_SIGNATURE=0` nếu bạn chấp nhận rủi ro. | | `cmp login` báo mã đã hết hạn | Đã quá 10 phút | Chạy lại `cmp login`. | | Exit code 3 | Khóa thiếu scope, đã hết hạn hoặc bị thu hồi | `cmp whoami`; tạo mới hoặc phê duyệt lại với nhiều scope hơn. | | Exit code 6 trong tập lệnh | Lệnh có tính phí hoặc phá hủy chạy mà không có terminal | Thêm `--yes` (và `--idempotency-key` của riêng bạn). | | "từ chối gửi key qua http" | URL API dùng http không mã hóa | Dùng `https://`, hoặc chỉ dùng `CMP_ALLOW_HTTP=1` cho môi trường lab. | | Trình duyệt mở sai trang | Chưa thiết lập `--api-url` cho reseller | `cmp login --api-url https://`. | --- # MCP server {#mcp-server} > **Vị trí trong portal:** API reference › Tools (`https:///apidoc`) hiển thị endpoint và các đoạn code client; khóa được tạo tại API keys (`/api-keys`). Không có cài đặt nào trong admin: endpoint là một phần của panel. ## Chức năng {#what-it-does} **Model Context Protocol (MCP)** cho phép trợ lý AI gọi các tool. NexCMP cung cấp một endpoint MCP tại `https:///mcp`. Mỗi thao tác API công khai trở thành một **tool** (`vm_list`, `vm_start`, `billing_wallet`,...), do đó khách hàng có thể hỏi trợ lý của họ "những VM nào của tôi đang chạy?" hoặc "dừng VM staging". Trợ lý chỉ hoạt động với API key và quyền hạn của chính khách hàng. ::: tip Cấu hình NexCMP bằng AI? Trang này nói về endpoint MCP cho **khách hàng** (`/mcp`). Để cho phép trợ lý AI cấu hình panel của bạn với tư cách quản trị viên, hãy xem [Configure with AI](https://nexcmp.com/vi/docs/configure-with-ai/mcp-admin/) (endpoint `/mcp/admin`, admin keys `ak_`). ::: ## Yêu cầu {#requirements} | Hạng mục | Yêu cầu | |---|---| | Máy chủ | Không cần cài đặt gì: endpoint được phân phối bởi panel và có thể truy cập ở bất kỳ đâu panel hoạt động. Reverse proxy của bạn phải chuyển tiếp `/mcp` đến panel. | | Khách hàng | Một [API key](https://nexcmp.com/vi/docs/developers/api-keys/) (`vk_...`) với các scope mà trợ lý cần. | | Client | Một MCP client hỗ trợ transport **Streamable HTTP** và header `Authorization` tùy chỉnh: Claude Code, Claude Desktop (thông qua bridge `mcp-remote`), Cursor, VS Code với Copilot agent mode và các công cụ tương tự. | | Phiên bản giao thức | 2025-11-25, 2025-06-18 và 2025-03-26. | ## Chuẩn bị hạ tầng {#prepare-the-infrastructure} Không có gì, ngoại trừ việc đảm bảo `https:///mcp` không bị chặn bởi tường lửa hoặc quy tắc proxy. MCP client dựa trên trình duyệt từ một origin khác sẽ bị từ chối trừ khi origin đó được cho phép; các client dòng lệnh và desktop không gửi header `Origin` và hoạt động bình thường. ## Kết nối (phía khách hàng) {#connect-customer-side} 1. Tạo một API key trong portal (**API keys › Create key**) chỉ với các scope bạn muốn trợ lý sử dụng, thời hạn ngắn và nếu có thể, giới hạn theo IP. 2. Thêm server vào client của bạn. Thay thế `cloud.example.com` và key. **Claude Code** ```bash claude mcp add --transport http cloud https://cloud.example.com/mcp \ --header "Authorization: Bearer vk_XXXX" ``` **Cursor** (`~/.cursor/mcp.json` hoặc `.cursor/mcp.json`; thiết lập `CLOUD_API_KEY` trong môi trường mà Cursor khởi chạy): ```json { "mcpServers": { "cloud": { "url": "https://cloud.example.com/mcp", "headers": { "Authorization": "Bearer ${env:CLOUD_API_KEY}" } } } } ``` **Claude Desktop** (cần Node.js 18+; `claude_desktop_config.json`), thông qua bridge `mcp-remote`: ```json { "mcpServers": { "cloud": { "command": "npx", "args": ["-y", "mcp-remote", "https://cloud.example.com/mcp", "--header", "Authorization:${CLOUD_AUTH_HEADER}"], "env": { "CLOUD_AUTH_HEADER": "Bearer vk_XXXX" } } } } ``` Viết header không có khoảng trắng sau dấu hai chấm và đặt toàn bộ giá trị vào biến môi trường, như trên. 3. Khởi động lại client và yêu cầu liệt kê các tool của bạn. Kiểm tra kết nối mà không cần client: ```bash curl -s https://cloud.example.com/mcp \ -H "Authorization: Bearer vk_XXXX" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' ``` ## Cách thức hoạt động {#how-it-works} | Hạng mục | Chi tiết | |---|---| | Endpoint | `POST /mcp` với thông điệp JSON-RPC 2.0; phản hồi là `application/json`. `GET /mcp` trả về 405 (không có stream từ server đến client); `DELETE /mcp` kết thúc phiên làm việc. | | Xác thực | Chỉ `Authorization: Bearer vk_...` (session token, cookie và admin key sẽ bị từ chối với mã 401 cùng header `WWW-Authenticate: Bearer`). | | Session | `Mcp-Session-Id` được cấp bởi `initialize`, gắn với key đó, có hiệu lực trong 24 giờ; tối đa 16 session cho mỗi key. | | Công cụ | Một tool cho mỗi thao tác API công khai hiển thị với key. Tên tool là lệnh CLI với `_` thay cho khoảng trắng và dấu gạch ngang (`vm firewall add` trở thành `vm_firewall_add`) và tương đương với OpenAPI `operationId`. Tool chỉ được liệt kê khi key có scope tương ứng và module đã được bật. | | Capabilities | Chỉ tools (không có resources hoặc prompts). | | Kích thước | Request body tối đa 1 MB; văn bản kết quả tool tối đa khoảng 100 KB (phần còn lại sẽ bị cắt kèm ghi chú); mỗi lệnh gọi mất tối đa 55 giây. | ### Quy tắc an toàn {#safety-rules} - **Cùng cơ chế kiểm soát như REST.** Mỗi `tools/call` đều đi qua pipeline xử lý request của chính panel: scope, site, giới hạn IP, rate limit, tính lũy thừa (idempotency), kiểm tra quyền sở hữu (404 đối với tài nguyên của người khác) và quota đều được áp dụng. MCP không thể cấp bất kỳ quyền nào mà key không có. - **Xác nhận.** Các tool phát sinh chi phí, xóa dữ liệu hoặc trả về thông tin xác thực (ticket console, kubeconfig, secret S3 hoặc SSH, đặt lại mật khẩu, key mới) đều yêu cầu đối số `confirm: true`. Phần mô tả của tool sẽ chỉ dẫn trợ lý chỉ truyền đối số này sau khi người dùng đã phê duyệt, vì vậy chỉ thị ẩn trong trang web hoặc log không thể tự ý kích hoạt. - **Tính lũy thừa.** Các tool trả phí chấp nhận `idempotency_key`; nếu bỏ trống, một key ổn định sẽ được tạo từ tên tool và các đối số, nhờ đó việc thử lại giống hệt nhau sẽ không bị tính phí hai lần. - **Không hiển thị dưới dạng tool:** các endpoint streaming (chat AI Agent), ticket WebSocket dùng một lần cho SSH hoặc console, tải xuống file nhị phân và các endpoint của ứng dụng VPN (`/v1/ext/*`). - **Không bao giờ khả thi:** API không bao giờ cho phép nạp tiền, đổi mật khẩu, xóa tài khoản hoặc tạo key, do đó không trợ lý nào có thể thực hiện các thao tác này. ### Giới hạn {#limits} | Hạn mức | Mặc định | |---|---| | Lượt gọi tool trên mỗi key | 60 mỗi phút | | Lượt request MCP trên mỗi key | 240 mỗi phút | | Cộng với các giới hạn thông thường của key và tài khoản | Xem [REST API](https://nexcmp.com/vi/docs/developers/api/#rate-limits) | Khi vượt quá giới hạn, endpoint sẽ trả về HTTP 429 kèm lỗi JSON-RPC và `Retry-After`. ## Kiểm tra {#verify} 1. Lệnh `curl` ở trên trả về kết quả JSON-RPC với danh sách `tools`. Chỉ các tool phù hợp với scope của key mới xuất hiện. 2. Trong client của bạn, hãy hỏi "list my VMs": trợ lý sẽ gọi `vm_list` và hiển thị kết quả. 3. Trong portal, thời gian **Last used** của key sẽ được cập nhật, và các lệnh gọi ghi sẽ xuất hiện trong **Key usage log**. ## Hạn mức & lưu ý {#limits-notes} - **Đăng nhập qua trình duyệt (OAuth).** Trang tài liệu tham khảo cũng mô tả việc đăng nhập qua trình duyệt đối với các client hỗ trợ MCP OAuth. Trong bản cài đặt NexCMP, phương thức được hỗ trợ và đã kiểm thử là API key (hoặc `cmp login` cho CLI). - **Trang reseller** không hiển thị phần MCP; khách hàng của họ sử dụng domain của reseller cho API. - **Đặc quyền tối thiểu.** Tạo một key riêng cho từng trợ lý với các scope chỉ đọc trước; chỉ thêm các scope ghi khi cần thiết. - Thu hồi key trong **API keys** để ngắt quyền truy cập của trợ lý ngay lập tức. ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | 401 kèm `WWW-Authenticate: Bearer` | Không có key, sai key hoặc là session token | Gửi `Authorization: Bearer vk_...`. | | 403 về `Origin` | Trang trình duyệt trên một origin khác | Sử dụng desktop client hoặc CLI client; hoặc yêu cầu quản trị viên của bạn cho phép origin (`mcp_allowed_origins`). | | 404 đối với request có `Mcp-Session-Id` | Session thuộc về key khác hoặc đã hết hạn | Chạy lại `initialize`. | | 405 đối với `GET /mcp` | Dự kiến: máy chủ không có event stream | Chỉ sử dụng POST (các client tự động thực hiện việc này). | | Danh sách tool bị ngắn | Scope của key hoặc module | Thêm scope cho key; bật module tương ứng. | | Tool phản hồi rằng nó cần `confirm: true` | Tool tính phí, xóa hoặc nhạy cảm | Trợ lý phải đặt `confirm` sau khi bạn phê duyệt. | | 429 | Rate limit của MCP hoặc key | Chờ `Retry-After`. | | Client không thể kết nối bằng header | Client không hỗ trợ custom-header | Sử dụng bridge `mcp-remote`. | --- # Cấu hình bằng AI {#configure-with-ai} > **Vị trí trong trang admin:** AI Chat (`/agent`) và System › Settings › API & AI agents (`/agent/keys`). Mọi nội dung trên các trang này chỉ dành cho quản trị viên. ## Chức năng {#what-it-does} Từ NexCMP 1.4.0, bạn có thể yêu cầu trợ lý AI cấu hình panel giúp mình: kết nối Proxmox VE hoặc CloudStack, tạo zone, xây dựng bảng gói dịch vụ từ chi phí của bạn, thiết lập email, cổng thanh toán và thương hiệu, tìm kiếm khách hàng hoặc xuất toàn bộ cấu hình. Trợ lý hoạt động thông qua một tập hợp **admin tool** cố định. Nó không bao giờ có quyền truy cập shell, không đọc file trên máy chủ và không nhìn thấy mật khẩu hay API key đã lưu. Hãy sử dụng tính năng này khi bạn muốn thiết lập ban đầu chỉ trong vài phút thay vì bấm qua hàng chục trang, hoặc khi bạn quản lý nhiều hệ thống cài đặt và muốn lưu cấu hình của chúng trong một file. ## Ba cách sử dụng {#three-ways-to-use-it} | Cách thức | Bên tương tác với AI | Nơi chạy | Bắt đầu từ đây | |---|---|---|---| | **AI Chat trong trang quản trị** | Bạn, trong trang admin NexCMP | Nguồn AI bạn chọn: API key từ OpenAI, Anthropic, Gemini hoặc OpenRouter, nhà cung cấp AI riêng của panel, hoặc CLI AI chính thức mà bạn đã đăng nhập | [AI Chat trong trang quản trị](https://nexcmp.com/vi/docs/configure-with-ai/ai-chat-in-admin/) | | **Client AI của bạn qua MCP** | Bạn, trong Claude Code, Codex CLI, Gemini CLI, Cursor, Claude Desktop, claude.ai hoặc ChatGPT | Trên máy của bạn hoặc trong ứng dụng của nhà cung cấp, kết nối tới panel của bạn tại `https://cloud.example.com/mcp/admin` | [Kết nối client AI](https://nexcmp.com/vi/docs/configure-with-ai/mcp-admin/) | | **Configuration as code** | Bạn hoặc một script | File YAML và lệnh `nexcmp config` trên máy chủ (hoặc trang Import/Export) | [Configuration as code](https://nexcmp.com/vi/docs/configure-with-ai/config-as-code/) | Cả ba cách đều gọi các tool tương tự và đi qua cùng một lớp bảo mật, vì vậy bạn có thể kết hợp chúng: soạn thảo cấu hình với trợ lý, xuất ra dạng YAML, xem lại trong trình soạn thảo và áp dụng sau. ## Mô hình an toàn {#safety-model} | Quy tắc | Ý nghĩa đối với bạn | |---|---| | **Scope** | Key hoặc kết nối bị giới hạn trong các scope bạn đã đánh dấu chọn (`admin:read`, `catalog:write`, `infra:write`, `billing:write`, `customers:write`, `settings:write`, `ai:write`, `secrets:write`). Nếu không có scope phù hợp, yêu cầu gọi sẽ bị từ chối. Xem [Admin API keys](https://nexcmp.com/vi/docs/configure-with-ai/admin-api-keys/#scopes). | | **Expiry** | Mọi key và kết nối đều có hạn sử dụng: từ 1 đến 90 ngày đối với key bạn tạo, mặc định là 30 ngày. Token truy cập OAuth có hiệu lực trong một giờ. | | **Giới hạn IP và rate limit** | Key có thể được giới hạn theo dải IP và số lượt gọi mỗi phút (mặc định là 120). | | **Xác nhận hai bước** | Các thao tác luân chuyển tiền, xóa dữ liệu, thay đổi thông tin thanh toán hoặc đổi bảo mật đăng nhập sẽ hiển thị bản xem trước và không thực hiện gì cho đến khi bạn phê duyệt. Trong AI Chat, mỗi thay đổi là một thẻ xác nhận do bạn tự bấm duyệt. | | **Những việc khóa không bao giờ làm được** | Tạo quản trị viên, đổi 2FA, tạo hoặc thu hồi khóa, đăng nhập dưới danh nghĩa khách hàng, sao lưu, khôi phục hoặc cập nhật panel, và các thao tác tương tự. Những việc này yêu cầu bạn tự thao tác trong admin. | | **Nhật ký hoạt động** | Mọi lệnh gọi, dù được phép hay bị từ chối, đều được ghi lại cùng với khóa, client, công cụ, IP và kết quả. Xem System › Settings › API & AI agents › Activity. | | **Thông tin bí mật không bao giờ được trả về** | Mật khẩu, API key và token có thể được thiết lập nhưng không bao giờ đọc lại được. Các câu trả lời mà AI nhìn thấy đều đã được che đi. | | **Bản cài đặt demo ở chế độ chỉ đọc** | Trên panel demo, mọi thao tác ghi đều bị từ chối với `demo_read_only`. | ::: important Những gì AI có thể đọc Với `admin:read`, trợ lý có thể đọc tên khách hàng, địa chỉ email, số dư và bản ghi thanh toán. Khi bạn sử dụng nguồn AI chạy tại nhà cung cấp bên ngoài (OpenAI, Anthropic, Google, OpenRouter), dữ liệu đó sẽ được gửi tới nhà cung cấp đó để trả lời câu hỏi của bạn. Hãy chỉ cấp cho trợ lý phạm vi quyền (scope) tối thiểu cần thiết và chọn nguồn AI mà bạn tin tưởng đối với dữ liệu đó. ::: ## Bắt đầu nhanh {#quick-start} 1. Đăng nhập vào admin và mở **AI Chat**. Nếu chưa có nguồn AI nào được kết nối, hãy mở **System › Settings › AI accounts** và kết nối một nguồn (xem [AI accounts and subscriptions](https://nexcmp.com/vi/docs/configure-with-ai/ai-accounts-and-subscriptions/)). 2. Nhập "Check my setup progress" và nhấn Enter. Trợ lý sẽ đọc [Setup progress checklist](https://nexcmp.com/vi/docs/configure-with-ai/setup-checklist/) và cho bạn biết những việc còn lại. 3. Yêu cầu trợ lý thực hiện bước tiếp theo. Xem lại từng thẻ xác nhận và nhấn **Confirm** để áp dụng. Để tham khảo những nội dung nên hỏi ban đầu, hãy xem [Example prompts](https://nexcmp.com/vi/docs/configure-with-ai/example-prompts/). ![Trang AI Chat với một cuộc trò chuyện, kết quả công cụ và một thẻ xác nhận](https://nexcmp.com/vi/docs/images/configure-with-ai/overview-01-ai-chat.webp) ## Hạn mức & lưu ý {#limits-notes} - **Bản demo và chế độ chỉ đọc.** Các trang vẫn hiển thị trên panel demo, nhưng không thể lưu bất kỳ thay đổi nào tại đó. - **Không có shell.** Trợ lý chỉ có thể gọi các công cụ admin được liệt kê trong [Connect an AI client](https://nexcmp.com/vi/docs/configure-with-ai/mcp-admin/#tools). Trợ lý không thể chạy lệnh trên máy chủ. - **Các module mạng và định tuyến** (BGP, XDP, interfaces, NAT và tương tự) đều ở chế độ chỉ đọc đối với AI; những phần nhạy cảm như tài khoản quản trị viên, bản sao lưu và cập nhật hoàn toàn không cho phép truy cập qua khóa. - **Giá** được tính bằng USD: giá gói tính bằng đô la mỗi giờ, số dư tính bằng cent. - **Chi phí.** Các câu trả lời của AI được thanh toán cho nguồn AI bạn kết nối (mức sử dụng API hoặc gói đăng ký của chính bạn). Trong AI Chat, bạn có thể đặt hạn mức chi tiêu hàng ngày. Về mô hình giấy phép NexCMP, xem https://nexcmp.com/pricing. ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | AI Chat thông báo chưa kết nối nguồn AI | Chưa thiết lập nguồn cho tài khoản admin của bạn | Mở System › Settings › AI accounts và kết nối một nguồn. | | Trợ lý phản hồi `insufficient_scope` | Khóa hoặc kết nối thiếu scope cho công cụ đó | Tạo một khóa với scope cần thiết, hoặc kết nối lại và đánh dấu chọn nó trên màn hình chấp thuận. Xem [Admin API keys](https://nexcmp.com/vi/docs/configure-with-ai/admin-api-keys/#errors). | | Mọi thay đổi đều hiển thị thẻ xác nhận | Đúng như dự kiến trong AI Chat | Nhấn **Confirm** để áp dụng hoặc **Reject** để hủy bỏ. | | Thao tác ghi thất bại với `demo_read_only` | Panel đang ở chế độ demo | Sử dụng bản cài đặt không phải demo. | --- # AI Chat trong trang quản trị {#ai-chat-in-the-admin} > **Vị trí trong admin:** AI Chat (`/agent`, mục menu riêng) và nút nổi **Ask AI** trên mọi trang admin. Các nguồn trả lời được thiết lập trong System › Settings › AI accounts (`/agent/accounts`). ## Chức năng {#what-it-does} AI Chat là trợ lý được tích hợp trong admin. Bạn mô tả nội dung mình muốn ("connect my Proxmox cluster", "set up email"), trợ lý sẽ đọc trạng thái hiện tại bằng các công cụ admin, đề xuất các thay đổi và hiển thị từng thay đổi dưới dạng **thẻ xác nhận**. Sẽ không có gì được áp dụng cho đến khi bạn nhấn **Confirm**. Khung **Ask AI** cũng là đoạn chat đó nhưng nằm ở bảng hẹp cạnh bên, giúp bạn có thể hỏi trong khi đang xem trang. Các nút như **Do it for me** (trong [Setup progress checklist](https://nexcmp.com/vi/docs/configure-with-ai/setup-checklist/) và trong các danh sách trống) sẽ mở khung này với câu hỏi đã chuẩn bị sẵn. Đây không phải là [AI Chat](https://nexcmp.com/vi/docs/ai/ai-chat/) và [AI Agent](https://nexcmp.com/vi/docs/ai/ai-agent/) hướng tới khách hàng, vốn dùng để phục vụ các khách hàng của bạn. ## Yêu cầu {#requirements} | Hạng mục | Yêu cầu | |---|---| | Role | Quản trị viên đã đăng nhập. Các đoạn chat, khóa và tùy chọn thuộc về tài khoản admin của bạn; những quản trị viên khác sẽ không nhìn thấy chúng. | | Một nguồn trả lời | Đã kết nối ít nhất một nguồn: một API key, một phiên đăng nhập, AI provider của chính bảng điều khiển hoặc một AI CLI mà bạn đã đăng nhập. Xem [Tài khoản AI và gói đăng ký](https://nexcmp.com/vi/docs/configure-with-ai/ai-accounts-and-subscriptions/). | | Demo | Trên bảng điều khiển demo, bạn có thể đọc các đoạn chat cũ nhưng không thể gửi tin nhắn. | ## Chọn nguồn trả lời {#choose-where-answers-come-from} Chọn nguồn trong bộ chọn bên dưới ô nhập liệu (nơi liệt kê các nguồn bạn đã kết nối). **System › Settings › AI accounts** cũng cho phép bạn đặt nguồn mặc định, model mặc định và giới hạn chi tiêu hàng ngày. | Source | Cách kết nối | Ghi chú | |---|---|---| | OpenAI (các model ChatGPT) | Dán API key từ platform.openai.com | OpenAI tính phí theo mức sử dụng. | | Anthropic (Claude) | Dán API key từ console.anthropic.com | Anthropic tính phí theo mức sử dụng. | | Google Gemini | Dán API key từ aistudio.google.com hoặc **Sign in with Google** | Đăng nhập bằng Google yêu cầu một OAuth client do chính **bạn** tạo trong dự án Google Cloud của mình. | | OpenRouter | Dán key hoặc **Sign in with OpenRouter** | Một tài khoản cho nhiều model. | | AI provider của bảng điều khiển | Đã được thiết lập trong System › Settings › AI provider | Cùng một provider mà AI Chat của khách hàng sử dụng. [AI provider](https://nexcmp.com/vi/docs/ai/ai-providers/). | | Gói đăng ký Claude, ChatGPT hoặc Gemini | CLI chính thức đã được cài đặt và đăng nhập trên máy chủ panel | Xem [Tài khoản AI và gói đăng ký](https://nexcmp.com/vi/docs/configure-with-ai/ai-accounts-and-subscriptions/). | Các key bạn dán được lưu trữ mã hóa chỉ dành riêng cho tài khoản admin của bạn. Chúng sẽ không bao giờ hiển thị lại và quản trị viên khác không thể giải mã chúng. ## Sử dụng chat {#use-the-chat} 1. Mở **AI Chat** (hoặc nhấp vào **Ask AI**). 2. Nhấp vào **New chat** hoặc mở một đoạn chat trước đó từ danh sách bên trái. 3. Nhập yêu cầu của bạn và nhấn Enter (Shift+Enter để xuống dòng). Bạn có thể đính kèm hình ảnh hoặc tệp văn bản (tối đa 4 tệp mỗi tin nhắn, 3 MB mỗi tệp) để minh họa lỗi hoặc dán tài liệu. 4. Theo dõi câu trả lời xuất hiện theo thời gian thực. Mỗi công cụ mà trợ lý gọi sẽ hiển thị dưới dạng một thẻ có thể thu gọn kèm tên công cụ, các đối số và kết quả tóm tắt. 5. Nhấn **Stop** để hủy câu trả lời đang chạy. Mỗi quản trị viên chỉ có một câu trả lời chạy tại một thời điểm. ![AI Chat với danh sách cuộc trò chuyện, câu trả lời chứa các thẻ công cụ cùng ô nhập liệu có bộ chọn nguồn và trường Secret](https://nexcmp.com/vi/docs/images/configure-with-ai/ai-chat-in-admin-01-chat.webp) Tối đa 10 lượt gọi công cụ diễn ra trên mỗi tin nhắn. Trợ lý ghi nhớ 30 tin nhắn gần nhất của cuộc trò chuyện. Kết quả từ các công cụ được chuyển đến mô hình và được đánh dấu là dữ liệu, không phải là chỉ dẫn. ## Thẻ xác nhận {#confirmation-cards} Trong AI Chat, **mọi thay đổi đều là một thẻ**, không chỉ riêng các hành động liên quan đến tiền. Trợ lý đề xuất; bạn quyết định. Một thẻ sẽ hiển thị: - Tiêu đề nêu rõ lý do cần chú ý, ví dụ "changes a customer balance". - Lệnh gọi: phương thức và đường dẫn. - Bảng các trường thay đổi: giá trị hiện tại và giá trị mới. Các giá trị bí mật hiển thị dưới dạng `••••`. - Đồng hồ đếm ngược (thẻ hết hạn sau 5 phút). - **Confirm** và **Reject**. **Confirm** sẽ yêu cầu chính panel áp dụng thay đổi, sau đó thông báo cho trợ lý những gì đã diễn ra. Trợ lý không thể nhấn nút, không thể phê duyệt qua API và được chỉ thị không bao giờ tuyên bố thay đổi đã được áp dụng trước khi nó được xác nhận. Nếu bạn tải lại trang, các thẻ còn hiệu lực sẽ xuất hiện lại. Chúng cũng hiển thị ở đầu trang **System › Settings › API & AI agents** dưới mục "Waiting for your confirmation". ![Thẻ xác nhận hiển thị thay đổi số dư, đồng hồ đếm ngược cùng các nút Confirm và Reject](https://nexcmp.com/vi/docs/images/configure-with-ai/ai-chat-in-admin-02-confirm.webp) ## Bí mật {#secrets} Mật khẩu và API key không được gửi qua nội dung chat. Hãy sử dụng trường **Secret** (biểu tượng ổ khóa) bên cạnh ô nhập liệu: 1. Nhấp vào biểu tượng ổ khóa và nhập **tên** (chữ cái, chữ số và dấu gạch dưới, ví dụ `smtp_password`) cùng **giá trị**. 2. Trong tin nhắn của bạn, hãy tham chiếu đến tên đó: "use the secret smtp_password as the SMTP password". 3. Trợ lý sẽ chỉ nhìn thấy một placeholder đại diện cho bí mật đó, được viết như sau: ```text {{secret:smtp_password}} ``` Panel sẽ thay thế nó bằng giá trị thực ngay tại thời điểm chạy công cụ. Giá trị này không được lưu trong lịch sử chat và không được gửi đến nguồn AI. Nếu bạn vô tình dán thông tin trông giống như một khóa vào tin nhắn, panel sẽ chuyển thông tin đó vào cùng kho lưu trữ được bảo vệ và ẩn đi trong lịch sử, nhưng bạn chỉ nên coi đó là biện pháp phòng ngừa dự phòng chứ không phải là phương thức chuẩn. Các bí mật chỉ tồn tại trong bộ nhớ của panel cho cuộc trò chuyện mà chúng được nhập vào và tối đa một giờ sau tin nhắn cuối cùng; việc khởi động lại panel cũng sẽ xóa sạch chúng. Hãy nhập lại nếu trợ lý yêu cầu. Việc thiết lập bí mật cũng cần quyền `secrets:write` cho phiên chat (xem bên dưới). ## Quyền hạn của chat {#permissions-of-the-chat} Mỗi tin nhắn chạy với một khóa tạm thời tồn tại trong suốt thời gian phản hồi (tối đa 15 phút), chỉ hoạt động từ máy chủ panel và chỉ có thể được sử dụng thông qua các thẻ xác nhận. Phạm vi (scope) của nó là những mục được chọn trong **System › Settings › AI accounts › Chat session permissions**. `admin:read` luôn được bật. Mọi scope ngoại trừ `secrets:write` đều được bật theo mặc định; hãy tích chọn `secrets:write` nếu bạn muốn trợ lý có thể đặt mật khẩu và khóa (thông qua trường Secret). Trên panel demo, chat ở chế độ chỉ đọc. ## Hạn mức chi tiêu hàng ngày {#daily-spending-cap} AI Chat cộng dồn chi phí ước tính của các câu trả lời từ các nguồn API. Hạn mức mặc định là **5 USD mỗi quản trị viên mỗi ngày**. Đặt một số tiền khác (0 nghĩa là không giới hạn) trong mục **AI accounts › Defaults for AI Chat**. Trang sẽ hiển thị "used today". Khi chạm hạn mức, chat sẽ từ chối tin nhắn mới (`daily_cap`) cho đến ngày hôm sau hoặc cho đến khi bạn nâng hạn mức. Các nguồn là gói đăng ký AI CLI không được tính vì chúng được lập hóa đơn theo gói thuê bao của bạn. ## Kiểm tra {#verify} 1. Trong **AI accounts**, nhấp vào **Test** tại nguồn tương ứng. Hệ thống sẽ phản hồi tên mô hình và thời gian tính bằng mili giây. 2. Trong AI Chat, hãy hỏi "Check my setup progress". Câu trả lời sẽ liệt kê các bước từ [checklist](https://nexcmp.com/vi/docs/configure-with-ai/setup-checklist/) và một thẻ công cụ `setup_checklist` sẽ xuất hiện. 3. Yêu cầu một thay đổi nhỏ, ví dụ: "Set the brand name to Example Cloud". Thẻ xác nhận sẽ xuất hiện; bấm **Confirm** và kiểm tra trang Branding. 4. **API & AI agents › Activity** liệt kê các lệnh gọi với channel `chat`. ## Hạn mức & lưu ý {#limits-notes} - Trợ lý không có shell và không thể đọc tệp trên server. Trợ lý chỉ gọi các [admin tools](https://nexcmp.com/vi/docs/configure-with-ai/mcp-admin/#tools). - Những thay đổi mà key không bao giờ có thể thực hiện ([danh sách](https://nexcmp.com/vi/docs/configure-with-ai/admin-api-keys/#what-a-key-can-never-do)) cũng không thể thực hiện từ AI Chat. - Kiểm tra kết quả của model. Thẻ xác nhận hiển thị chính xác những gì sẽ được gửi; hãy đọc kỹ, đặc biệt là giá và số tiền. - Câu trả lời qua API do nhà cung cấp AI tính phí. Hạn mức chỉ là ước tính; bạn cũng nên đặt hạn mức chi tiêu tại nhà cung cấp. - Câu trả lời qua CLI sẽ dừng sau 5 phút. ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | "Đã đạt hạn mức chi tiêu AI hôm nay" (`daily_cap`) | Bạn đã dùng hết hạn mức trong ngày | Tăng hạn mức trong AI accounts, hoặc đợi đến ngày mai. | | "Câu trả lời khác vẫn đang chạy - hãy đợi hoặc nhấn Stop" (`busy`) | Mỗi quản trị viên chỉ xử lý một câu trả lời tại một thời điểm | Bấm **Stop** hoặc đợi. | | Nguồn không hiển thị trong danh sách chọn | Chưa kết nối, hoặc (Claude CLI) nút gạt "I understand" đang tắt | Kết nối lại trong AI accounts. | | "đây không giống một API key" | Key dán vào có chứa khoảng trắng hoặc quá dài | Chỉ dán chuỗi key. | | Kiểm tra thất bại | Sai key, hết số dư, hoặc nhà cung cấp gặp sự cố | Kiểm tra key và thanh toán tại nhà cung cấp. | | Trợ lý báo không thể thực hiện | Phiên chat thiếu scope, hoặc hành động bị khóa đối với AI | Tích chọn scope trong AI accounts hoặc thực hiện trong admin. | | Thẻ báo đã hết hạn | Đã quá 5 phút | Yêu cầu trợ lý đề xuất lại thay đổi. | | Nguồn CLI báo "usage limit" hoặc "not logged in" | Hạn mức gói đăng ký hoặc phiên đăng nhập của bạn | Đăng nhập lại hoặc đợi; xem [Tài khoản và gói đăng ký AI](https://nexcmp.com/vi/docs/configure-with-ai/ai-accounts-and-subscriptions/). | --- # Tài khoản và gói đăng ký AI {#ai-accounts-and-subscriptions} > **Vị trí trong admin:** System › Settings › AI accounts (`/agent/accounts`), tab **Accounts** và **Use your own AI subscription**. Terminal tùy chọn là AI Console (`/agent/console`), chỉ hiển thị dưới AI Chat khi được bật. ## Chức năng {#what-it-does} AI Chat cần một nguồn để tạo câu trả lời. Trang này cho phép bạn kết nối nguồn đó cho tài khoản admin của mình: - **Nguồn API**: OpenAI, Anthropic (Claude), Google Gemini và OpenRouter, bằng API key hoặc đăng nhập. - **AI provider của panel**, nếu bạn đã thiết lập trong System › Settings › AI provider. - **Gói đăng ký AI riêng của bạn** (Claude, ChatGPT, Gemini) thông qua **công cụ dòng lệnh chính thức** của nhà cung cấp, trên server của panel hoặc trên chính máy tính của bạn. Mọi thứ bạn kết nối đều thuộc về tài khoản admin của bạn. Key và token được lưu trữ mã hóa cho riêng bạn; quản trị viên khác không thể sử dụng. ## Yêu cầu {#requirements} | Hạng mục | Yêu cầu | |---|---| | Role | Một quản trị viên đã đăng nhập. Trên panel demo, bạn không thể kết nối hoặc xóa bất kỳ mục nào. | | Nguồn API | Tài khoản và API key từ nhà cung cấp (thẻ có liên kết **Get API key** dẫn đến trang của nhà cung cấp). | | CLI trên máy chủ panel | AI Console đã được bật (xem bên dưới), kết nối HTTPS chiều đi (outbound) từ máy chủ tới nhà cung cấp, tới `nodejs.org` và npm registry, cùng **2 GB RAM trở lên** (CLI cần khoảng 1 GB RAM trống khi chạy; bộ cài đặt sẽ cảnh báo nếu dưới 2 GB). Node.js 20 trở lên sẽ được sử dụng nếu đã có sẵn, nếu không bộ cài đặt sẽ tải Node.js 22 kèm kiểm tra checksum. | | CLI trên máy tính của bạn | Node.js 20 trở lên để cài đặt CLI, cùng gói đăng ký thuê bao của riêng bạn. | ## Kết nối một nguồn API {#connect-an-api-source} 1. Mở **System › Settings › AI accounts** và ở lại tab **Accounts**. 2. Trên thẻ của nguồn tương ứng, nhấn **Connect**. Trang tạo key của nhà cung cấp sẽ mở ra trong tab mới; hãy tạo key tại đó. 3. Dán key vào trường nhập liệu rồi lưu lại. Thẻ sẽ hiển thị trạng thái đã kết nối kèm 4 ký tự cuối. 4. Chọn **default model** nếu bạn muốn dùng model khác, sau đó nhấn **Test**. Kết quả thành công sẽ có dạng "Connected - example-model, 850 ms". ![Trang AI accounts với các thẻ nguồn API, thẻ OpenAI đã kết nối và thẻ Panel AI provider](https://nexcmp.com/vi/docs/images/configure-with-ai/ai-accounts-and-subscriptions-01-accounts.webp) | Source | Phương thức đăng nhập thay thế | |---|---| | OpenRouter | **Sign in with OpenRouter** sẽ mở OpenRouter trong một popup hoặc tab; hãy phê duyệt và bạn sẽ được chuyển hướng lại trang này ở trạng thái đã kết nối. | | Google Gemini | **Sign in with Google** sẽ xuất hiện sau khi bạn đã lưu, tại mục **Set up Google sign-in (optional)** trên thẻ, một OAuth client được tạo trong chính dự án Google Cloud của **bạn** (client ID kết thúc bằng `.apps.googleusercontent.com` cùng client secret của nó). NexCMP không tích hợp sẵn client Google dùng chung. | | AI provider của bảng điều khiển | Sử dụng nhà cung cấp đã được cấu hình trong System › Settings › AI provider ([AI provider](https://nexcmp.com/vi/docs/ai/ai-providers/)). Không cần dán thông tin gì. | Để ngắt kết nối một nguồn, hãy nhấn **Remove** trên thẻ của nguồn đó. Thao tác này sẽ xóa key đã lưu cho tài khoản của bạn. ### Giá trị mặc định, giới hạn hằng ngày và quyền hạn {#defaults-daily-cap-and-permissions} Ở cuối tab **Accounts**, mục **Defaults for AI Chat** có ba cài đặt: | Cài đặt | Ý nghĩa | |---|---| | Nguồn và model mặc định | Được dùng cho các phiên chat mới. Bạn vẫn có thể thay đổi nguồn cho từng tin nhắn. | | Giới hạn chi tiêu hằng ngày (USD, 0 = không giới hạn) | Mặc định là 5. Trang sẽ hiển thị "used today". Xem [AI Chat trong admin](https://nexcmp.com/vi/docs/configure-with-ai/ai-chat-in-admin/#daily-spending-cap). | | Quyền hạn của phiên chat | Các phạm vi quyền (scopes) mà trợ lý có thể sử dụng. `admin:read` luôn được bật; `secrets:write` tắt theo mặc định. Xem [Admin API key](https://nexcmp.com/vi/docs/configure-with-ai/admin-api-keys/#scopes). | Nhấn **Save defaults**. ## Sử dụng gói AI của riêng bạn {#use-your-own-ai-subscription} Bạn có thể vận hành NexCMP bằng gói Claude, ChatGPT hoặc Gemini mà bạn đang trả phí mà không cần API key riêng. Có hai cách thực hiện. ### Cách 1 (khuyên dùng): CLI trên máy tính của bạn {#way-1-recommended-the-cli-on-your-own-computer} Bạn sử dụng công cụ của chính nhà cung cấp trên máy tính của mình và đăng nhập bằng tài khoản của bạn theo cách thông thường của nhà cung cấp. NexCMP chỉ nhận các lệnh gọi MCP được ký bằng key có thời hạn ngắn. Hãy mở **AI accounts › Use your own AI subscription**; giao diện sẽ hiển thị ba bước cho mỗi công cụ. 1. Nhấn **Create a 7-day key** và chọn cấp độ: **Read only** (`admin:read`) hoặc **Read + configuration** (`admin:read`, `catalog:write`, `infra:write`, `settings:write`). Các lệnh bên dưới sau đó sẽ chứa key thực tế. 2. Cài đặt CLI và đăng nhập. Key chỉ được hiển thị trên trang này và chỉ một lần duy nhất. | Công cụ | Cài đặt | Đăng nhập | |---|---|---| | Claude Code | `npm install -g @anthropic-ai/claude-code` | chạy `claude`, sau đó `/login` | | Codex CLI | `npm install -g @openai/codex` | `codex login` | | Gemini CLI | `npm install -g @google/gemini-cli` | chạy `gemini`, chọn "Login with Google" | 3. Kết nối với panel của bạn bằng một lệnh hoặc một khối lệnh được sao chép từ trang: ```bash # Claude Code claude mcp add --transport http nexcmp https://cloud.example.com/mcp/admin \ --header "Authorization: Bearer ak_XXXX" ``` ```toml # Codex CLI: ~/.codex/config.toml, then: export NEXCMP_KEY=ak_XXXX [mcp_servers.nexcmp] url = "https://cloud.example.com/mcp/admin" bearer_token_env_var = "NEXCMP_KEY" ``` ```json // Gemini CLI: ~/.gemini/settings.json { "mcpServers": { "nexcmp": { "httpUrl": "https://cloud.example.com/mcp/admin", "headers": { "Authorization": "Bearer ak_XXXX" } } } } ``` 4. Khởi động công cụ và hỏi, ví dụ "what is left to set up in nexcmp?". Mọi chi tiết về kết nối MCP đều có trong [Connect an AI client](https://nexcmp.com/vi/docs/configure-with-ai/mcp-admin/). Cùng tab đó hiển thị URL cho connector **claude.ai** và **ChatGPT**, đăng nhập bằng OAuth và không cần khóa: [OAuth connectors](https://nexcmp.com/vi/docs/configure-with-ai/oauth-connectors/). ![Tab Use your own AI subscription với nút khóa 7 ngày cùng các lệnh cài đặt, đăng nhập và kết nối cho ba CLI](https://nexcmp.com/vi/docs/images/configure-with-ai/ai-accounts-and-subscriptions-02-subscription.webp) ### Cách 2: CLI trên server panel (các nút Install / Login) {#way-2-the-cli-on-the-panel-server-install-login-buttons} Các thẻ bên dưới "Subscription through a CLI (Claude, ChatGPT, Gemini)" cho phép NexCMP cài đặt CLI chính thức trên server panel và mở quy trình đăng nhập riêng của nó, để **AI Chat** có thể trả lời bằng gói thuê bao của bạn. **Cơ chế cô lập.** Các CLI chạy trong một tiến trình riêng (`nexcmp-ai.service`) dưới user hệ thống `nexcmp-ai` của chính chúng, không có sudo, không có quyền truy cập vào các thư mục dữ liệu và cấu hình của NexCMP, đồng thời có giới hạn bộ nhớ. Với mỗi tin nhắn AI Chat, CLI được khởi động với chỉ các công cụ NexCMP MCP được cho phép (các công cụ shell và file bị tắt) và một khóa chỉ hoạt động từ chính server. NexCMP không đọc hoặc sao chép thông tin đăng nhập của CLI: CLI lưu giữ thông tin đó trong một thư mục riêng tư cho tài khoản admin của bạn. Bạn không cần phải bật gì cả: panel sẽ tự động thiết lập user và service `nexcmp-ai` khi được cài đặt hoặc cập nhật lên 1.4.0, nên các thẻ đã sẵn sàng để sử dụng. **Cài đặt và đăng nhập (theo từng quản trị viên):** 1. Trên thẻ của CLI, nhấp vào **Login**. Nếu CLI chưa được cài đặt, panel sẽ cài đặt nó trước: thanh tiến trình và nhật ký ngắn sẽ hiển thị quá trình tải xuống (Node.js nếu cần, sau đó là CLI). Cảnh báo sẽ xuất hiện khi server có ít hơn 2 GB RAM. 2. Thẻ sẽ hiển thị những gì CLI yêu cầu: - **Codex CLI**: nhấp vào **Open the sign-in page** và nhập mã dùng một lần mà thẻ hiển thị. (Tính năng đăng nhập thiết bị của OpenAI phải được bật trong cài đặt bảo mật ChatGPT của bạn.) - **Claude Code và Gemini CLI**: nhấp vào **Open the sign-in page**, đăng nhập, sau đó dán mã xác minh mà trang của nhà cung cấp hiển thị vào **Paste the verification code here** và nhấp vào **Send code**. 3. Thẻ sẽ chuyển sang trạng thái "Signed in" cùng thông tin tài khoản và phiên bản. Lượt đăng nhập không hoàn tất trong vòng 10 phút sẽ bị hủy; hãy nhấp lại vào **Login**. 4. Trong **AI Chat**, nguồn này giờ đây sẽ xuất hiện trong menu lựa chọn (ví dụ "ChatGPT (via Codex CLI)"). 5. **Sign out** sẽ xóa thông tin đăng nhập của CLI đối với tài khoản của bạn. Đối với Claude, thẻ có thêm một công tắc, **I understand and accept the vendor's terms for using a subscription this way**, mặc định tắt. Nguồn này sẽ không hiển thị trong AI Chat cho đến khi công tắc được bật. ![Các thẻ thuê bao CLI với Install và Login, mã dùng một lần trên thẻ Codex và công tắc I understand trên thẻ Claude](https://nexcmp.com/vi/docs/images/configure-with-ai/ai-accounts-and-subscriptions-03-cli.webp) ### Điều khoản của các nhà cung cấp AI {#terms-of-the-ai-vendors} Việc đăng nhập bằng gói thuê bao cá nhân chịu sự điều chỉnh theo các điều khoản của từng nhà cung cấp, và các điều khoản này có thể thay đổi. Các lưu ý dưới đây là tóm tắt những gì nhà cung cấp công bố tính đến tháng 10 năm 2026, không phải tư vấn pháp lý và không phải tuyên bố đại diện cho nhà cung cấp. Hãy đọc kỹ các trang hiện hành trước khi bật tính năng này. | Nhà cung cấp | Phạm vi trang của nhà cung cấp đề cập | Source | |---|---|---| | Anthropic (Claude) | Đăng nhập vào Claude Code nguyên bản bằng gói dịch vụ của chính bạn được hỗ trợ trong phạm vi này. Việc sử dụng gói đăng ký thông qua các sản phẩm khác, hoặc để một sản phẩm thu thập hay chuyển tiếp thông tin đăng nhập, lại được xử lý khác, và giới hạn của gói dịch vụ mặc định cho nhu cầu sử dụng cá nhân thông thường. Đó là lý do thẻ Claude có phần lưu ý cùng công tắc **I understand**, và tại sao Cách 1 là lựa chọn rành mạch hơn. | https://code.claude.com/docs/en/legal-and-compliance | | OpenAI (Codex) | Codex hỗ trợ đăng nhập bằng tài khoản ChatGPT hoặc API key. OpenAI khuyến nghị sử dụng API key cho mục đích tự động hóa và yêu cầu không để lộ Codex trong các môi trường công cộng hoặc không đáng tin cậy. Chỉ sử dụng thẻ này cho riêng bạn. | https://developers.openai.com/codex/auth | | Google (Gemini CLI) | Hỗ trợ Sign in with Google, API key và Vertex AI; các điều khoản phụ thuộc vào cách bạn đăng nhập và hạn mức gói dịch vụ của bạn sẽ được áp dụng. | https://geminicli.com/docs/get-started/authentication | Nếu bạn muốn tránh hoàn toàn vấn đề này, hãy dùng nguồn **API key** hoặc Cách 1 trên chính máy tính của bạn. ## AI Console {#ai-console} AI Console là trang terminal tùy chọn để chạy một trong các CLI đã đăng nhập trên máy chủ panel. Tính năng này **mặc định tắt**. - Bật hoặc tắt tính năng này, và quản lý các CLI trên máy chủ: ```bash sudo nexcmp ai-console enable # turn on (also creates the nexcmp-ai user and service) sudo nexcmp ai-console disable # turn off sudo nexcmp ai-console status # runner, console state and installed CLIs sudo nexcmp ai-console install claude # or codex, or gemini ``` `status` hiển thị trạng thái socket của AI runner đã sẵn sàng hay chưa, AI Console đang bật hay tắt, và đối với từng CLI là "installed" hay "not installed". `sudo nexcmp status` cũng hiển thị "AI runner: active". - Sau khi bật, tab **AI Console** sẽ xuất hiện dưới AI Chat. Chọn một CLI đã đăng nhập, nhập lại mật khẩu admin của bạn (cùng mã 2FA nếu có sử dụng) và mở một phiên làm việc. Một thanh thông báo sẽ nhắc bạn rằng các lệnh tại đây chỉ có thể quản lý NexCMP thông qua các công cụ MCP; các công cụ shell và tệp đều bị vô hiệu hóa. - Các bản cài đặt demo không bao giờ tạo người dùng `nexcmp-ai`. ![Màn hình khởi động AI Console với bộ chọn CLI, trường mật khẩu và thanh cảnh báo chỉ dùng MCP](https://nexcmp.com/vi/docs/images/configure-with-ai/ai-accounts-and-subscriptions-04-console.webp) ## Kiểm tra {#verify} 1. **Test** trên một nguồn API sẽ trả về tên model. 2. Trên thẻ CLI, trạng thái hiển thị "Signed in" kèm theo tài khoản. 3. Trên máy chủ: `sudo nexcmp ai-console status` liệt kê CLI ở trạng thái đã cài đặt, và `systemctl is-active nexcmp-ai` in ra `active`. 4. Trong AI Chat, chọn nguồn, hỏi "Check my setup progress", và một thẻ công cụ sẽ xuất hiện. ## Hạn mức & lưu ý {#limits-notes} - Mỗi câu trả lời từ CLI bị giới hạn tối đa 5 phút và chỉ xử lý một câu trả lời tại một thời điểm cho mỗi quản trị viên. Hạn mức hàng ngày không tính các câu trả lời từ CLI. - Mọi thay đổi từ nguồn CLI vẫn hiển thị dưới dạng thẻ xác nhận trong AI Chat; CLI không thể tự ý áp dụng các thay đổi. - Các gói thuê bao có hạn mức sử dụng riêng. Khi nhà cung cấp phản hồi "usage limit" hoặc "not logged in", khung chat sẽ hiển thị thông báo đó. - Việc xóa một nguồn không làm mất các cuộc hội thoại. - Hãy luôn cập nhật bản vá cho máy chủ: các CLI được cài đặt từ các gói công khai của nhà cung cấp tại thời điểm bạn nhấn Install. ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | Nút đăng nhập bị vô hiệu hóa và thẻ hiển thị "AI tools are not ready on the server yet" | Dịch vụ `nexcmp-ai` không chạy | Cập nhật panel lên phiên bản mới nhất, sau đó kiểm tra `sudo nexcmp status`. Trên bản demo chỉ đọc, điều này là bình thường. | | "Các công cụ AI chưa được cài đặt trên máy chủ này" | Dịch vụ `nexcmp-ai` không chạy (panel phiên bản cũ hoặc panel demo) | Cập nhật panel, sau đó `sudo nexcmp ai-console install claude` (hoặc `codex`, `gemini`). | | Cảnh báo RAM dưới 2 GB | Máy chủ có cấu hình thấp | Quá trình cài đặt có thể chậm hoặc thất bại; hãy bổ sung bộ nhớ hoặc dùng Cách 1. | | "Node.js download checksum mismatch" hoặc "download failed" | Máy chủ không thể kết nối tới nodejs.org, hoặc proxy đã làm thay đổi tệp tải về | Cho phép HTTPS outbound và thử lại. | | Quá trình cài đặt kết thúc với lỗi | npm không thể cài đặt package | Đọc log trên thẻ, kiểm tra kết nối outbound tới npm registry và thử lại. | | Đăng nhập gặp lỗi hoặc hết thời gian chờ | Đã quá thời hạn 10 phút hoặc mã bị sai | Nhấp lại vào **Login** và hoàn tất nhanh hơn. | | Nguồn Claude bị thiếu trong AI Chat | Công tắc **I understand** đang tắt, hoặc CLI chưa đăng nhập | Bật công tắc sau khi đọc trang của nhà cung cấp, sau đó đăng nhập. | | Tùy chọn "Sign in with Google" bị thiếu trên Gemini | Chưa lưu Google OAuth client nào | Tạo client trong dự án Google Cloud của riêng bạn và lưu dưới mục **Set up Google sign-in (optional)** trên thẻ, hoặc dán API key để thay thế. | | "Sign in with OpenRouter" trả về lỗi | Bạn đã hủy thao tác hoặc popup đã bị chặn | Cho phép mở popup và thử lại. | | Phản hồi từ CLI báo "usage limit" | Quota của gói dịch vụ đã dùng hết | Chờ hoặc chuyển nguồn khác. | --- # Admin API key {#admin-api-keys} > **Vị trí trong admin:** System › Settings › API & AI agents (`/agent/keys`), tab **API keys**. Trang này cũng có các tab **Connect an AI**, **Connected apps** và **Activity**. ## Chức năng {#what-it-does} Admin API key (tiền tố `ak_`) cho phép AI client hoặc script quản lý panel của bạn với đúng các quyền hạn mà bạn cấp. Key hoạt động trên admin API tại `/v1/admin/` và endpoint admin MCP `/mcp/admin`. Key không thể sử dụng ở bất kỳ nơi nào khác. ::: info Khác với customer key Khách hàng tạo các key bắt đầu bằng `vk_` trong customer portal ([API keys and scopes](https://nexcmp.com/vi/docs/developers/api-keys/)). Các key đó chỉ truy cập được customer API và `/mcp`. Key `ak_` sẽ bị từ chối trên customer API, và key `vk_` sẽ bị từ chối trên admin API. ::: ## Yêu cầu {#requirements} | Hạng mục | Yêu cầu | |---|---| | Role | Bạn phải đăng nhập vào admin. Key không thể tự tạo các key khác. | | Demo | Trên panel demo, trang này ở chế độ chỉ đọc: không thể tạo hoặc thu hồi key. | | Khả năng kết nối | Client phải kết nối được tới `https://cloud.example.com/mcp/admin` hoặc `/v1/admin/...` trên panel của bạn (hãy kiểm tra firewall nếu bạn áp dụng giới hạn IP). | ## Tạo key {#create-a-key} 1. Mở **System › Settings › API & AI agents** và ở lại tab **API keys**. 2. Nhấp vào **Create new key**. 3. Điền thông tin vào biểu mẫu: | Trường | Quy tắc | |---|---| | Name | Tối đa 60 ký tự, ví dụ "Claude Code on my laptop". | | Scope | Đánh dấu ít nhất một mục. Xem [Scopes](#scopes). Ban đầu chỉ nên chọn `admin:read`. | | Thời hạn | 1, 7, 30, 60 hoặc 90 ngày. Mặc định 30. Tối đa 90. Không thể tạo key không có thời hạn. | | Dải IP (tùy chọn) | Mỗi dòng một địa chỉ IPv4, IPv6 hoặc CIDR, ví dụ `203.0.113.0/24` hoặc `2001:db8::/48`. Tối đa 32 mục. Để trống để cho phép mọi IP. | | Số lượt gọi mỗi phút | 1 đến 6000. Mặc định 120. | 4. Nhấp vào **Create key**. Hộp thoại sẽ hiển thị key một lần duy nhất, ví dụ `ak_XXXX`. **Hãy sao chép ngay**: NexCMP chỉ lưu chuỗi hash và không thể hiển thị lại key. 5. Nhấp vào **I have saved the key**. Mở tab **Connect an AI** để lấy lệnh sẵn sàng dán đã chứa sẵn key bạn vừa tạo (chỉ hiển thị trên trang này cho đến khi bạn tải lại trang). ![Hộp thoại tạo khóa mới với tên, hộp kiểm phạm vi quyền, thời hạn và dải IP đã điền](https://nexcmp.com/vi/docs/images/configure-with-ai/admin-api-keys-01-create.webp) ![Hộp thoại hiển thị khóa mới một lần duy nhất kèm nút Copy và cảnh báo](https://nexcmp.com/vi/docs/images/configure-with-ai/admin-api-keys-02-shown-once.webp) ## Scope {#scopes} Một khóa chỉ có thể sử dụng các công cụ và endpoint mà phạm vi quyền (scopes) của nó cho phép. Quyền ghi không bao gồm quyền đọc: khóa cần cả đọc và ghi phải có thêm `admin:read`. | Scope | Quyền hạn | |---|---| | `admin:read` | Đọc cài đặt, danh mục, khách hàng, thanh toán và nhật ký. Không bao giờ trả về secret. | | `catalog:write` | Gói cước, OS template, hạn mức, mã giảm giá. | | `infra:write` | Nguồn hạ tầng (CloudStack, Proxmox), zone, server. | | `billing:write` | Cổng thanh toán, tiền tệ, hóa đơn, số dư. Các thao tác liên quan đến tiền cần xác nhận. | | `customers:write` | Khách hàng và đại lý. | | `settings:write` | Cài đặt chung, thương hiệu, email, trang pháp lý, module, thông báo. | | `ai:write` | Nhà cung cấp AI và các tính năng AI. | | `secrets:write` | Ghi mật khẩu và API key. Có thể thiết lập nhưng không thể đọc lại. | ::: tip Thiết lập secret cần hai phạm vi quyền Bất kỳ lệnh gọi nào mang giá trị mật khẩu, API key hoặc token (mật khẩu SMTP, khóa thanh toán, bot token Telegram, khóa nhà cung cấp AI, thông tin đăng nhập CloudStack hoặc Proxmox) đều cần `secrets:write` **và** phạm vi quyền của khu vực tương ứng (ví dụ: `settings:write` cho SMTP). Nếu bạn muốn tự nhập secret, hãy bỏ chọn `secrets:write` và nhập trực tiếp trong trang quản trị. ::: ## Thu hồi khóa {#revoke-a-key} 1. Tìm khóa trong bảng (trạng thái **Active**, **Expired** hoặc **Revoked**; **Last used** hiển thị thời gian và client). 2. Nhấp vào **Revoke** và xác nhận. Khóa sẽ ngừng hoạt động ngay lập tức. Thu hồi là vĩnh viễn; hãy tạo khóa mới nếu bạn cần sử dụng lại. ## Những thao tác key không bao giờ có thể thực hiện {#what-a-key-can-never-do} Khóa không bao giờ có thể truy cập các khu vực này, bất kể phạm vi quyền của nó là gì. Các khu vực này yêu cầu bạn phải đăng nhập vào trang quản trị. - Tạo hoặc thay đổi người dùng quản trị, 2FA và bảo mật đăng nhập, phiên đăng nhập quản trị và token admin API. - Tạo, liệt kê hoặc thu hồi khóa quản trị, kết nối OAuth và tài khoản AI, hoặc sử dụng AI Console. - Sao lưu hoặc khôi phục bảng điều khiển, cập nhật hoặc thay đổi giấy phép bản quyền. - Đăng nhập với tư cách khách hàng hoặc đại lý, mở console của khách hàng, đọc thông tin đăng nhập VM hoặc kubeconfig, thiết lập SSH Keys, hoặc gửi hay đặt lại mật khẩu. - Thay đổi các module mạng và định tuyến (BGP, FRR, RTBH, XDP, interface, static và policy route, NAT) hoặc agent bên ngoài và tích hợp cổng thông tin. Các mục này là chỉ đọc. - Thay đổi các cài đặt như `demo_*`, `admin_*`, danh sách máy chủ, passkey, secret dùng cho xác thực lại và captcha. Bất kỳ mục nào không được quy định bởi một quy tắc đều mặc định bị chặn ghi, và có thể đọc bằng `admin:read`. ### Hành động cần bạn xác nhận {#actions-that-need-your-confirmation} Các hành động này chỉ thành công sau khi bạn phê duyệt bản xem trước (xem [Xác nhận hai bước](#two-step-confirmation)): - Thay đổi số dư của khách hàng hoặc ví đại lý, chi trả tiền, bản ghi thanh toán, tỷ giá hối đoái. - Thay đổi giá (giá gói cước, tạo gói hàng loạt, định giá image và lưu trữ) và tạo mã giảm giá hoặc mã nạp tiền. - Lưu thông tin đăng nhập cổng thanh toán hoặc kết nối CloudStack. - Xóa bất kỳ dữ liệu nào, chặn hoặc xóa khách hàng, thay đổi giới hạn của khách hàng, tạm ngừng hoặc đóng tài khoản đại lý. - Thao tác trên server của khách hàng, hoặc tạo server trả phí cho khách hàng. - Thay đổi các công tắc trên toàn hệ thống, cài đặt bảo mật đăng nhập hoặc cài đặt thanh toán thông qua cài đặt chung. ## Xác nhận hai bước {#two-step-confirmation} Khi một lệnh gọi cần xác nhận, chưa có gì thay đổi. Phản hồi trả về mã HTTP **428** cùng `confirm_required`, `confirm_token`, `preview` (method, path, reason, các giá trị mới và các giá trị hiện tại nếu có) và `expires_in: 300`. 1. Client sẽ hiển thị bản xem trước cho bạn. 2. Sau khi bạn phê duyệt, nó sẽ lặp lại **chính xác** request đó (cùng method, path và body) với header `X-Confirm-Token: `. Các công cụ MCP sẽ nhận đối số `confirm_token` thay thế. 3. Token chỉ dùng được một lần và hết hạn sau 5 phút. Các key được tạo trong trang admin cho AI Chat chỉ có thể được xác nhận trên màn hình: phản hồi trả về `confirm_in: "ui"` và một thẻ xác nhận sẽ xuất hiện trong trang admin. AI không thể tự phê duyệt thao tác này. ## Giới hạn tần suất và quy tắc IP {#rate-limit-and-ip-rules} - Vượt quá giới hạn mỗi phút, lệnh gọi sẽ trả về `rate_limited` (HTTP 429) cùng `Retry-After: 60`. - Khi đã thiết lập dải IP, các lệnh gọi từ bất kỳ địa chỉ nào khác sẽ trả về `ip_not_allowed` (HTTP 403). ## Nhật ký hoạt động {#activity-log} Tab **Activity** liệt kê mọi lệnh gọi được thực hiện bằng key, mới nhất trước: thời gian, key, client, phương thức gửi đến (`http`, `mcp`, `chat`, `cli`, `confirm`, `preview`), method và path, tool, mã trạng thái HTTP, IP cùng chi tiết (đã che bớt). Bạn có thể tìm kiếm theo path, tool hoặc tên key, chỉ hiển thị lỗi (HTTP từ 400 trở lên) hoặc chỉ các lệnh gọi đang chờ xác nhận (từ 428 trở lên), và giới hạn khoảng thời gian trong 1 giờ, 24 giờ hoặc 7 ngày gần nhất. NexCMP lưu giữ 200,000 mục gần nhất. Các thay đổi được thực hiện qua key cũng xuất hiện trong Logs › Admin actions dưới tên `ak:/`. ![Tab Activity liệt kê các lệnh gọi kèm trạng thái, client, tool và IP](https://nexcmp.com/vi/docs/images/configure-with-ai/admin-api-keys-03-activity.webp) ## Kiểm tra {#verify} Kiểm tra key chỉ đọc từ bất kỳ máy nào nằm trong dải IP: ```bash curl -s https://cloud.example.com/v1/admin/agent/tools \ -H "Authorization: Bearer ak_XXXX" ``` Bạn sẽ nhận được danh sách JSON các tool mà scope của bạn cho phép. Hãy chạy thử một tool: ```bash curl -s -X POST https://cloud.example.com/v1/admin/agent/tools/system_health \ -H "Authorization: Bearer ak_XXXX" \ -H "Content-Type: application/json" -d '{}' ``` Thời gian **Last used** của key được cập nhật và lệnh gọi xuất hiện trong **Activity**. Danh sách tool đầy đủ và mô tả OpenAPI (`/v1/admin/openapi.json`) được trình bày trong mục [Kết nối AI client](https://nexcmp.com/vi/docs/configure-with-ai/mcp-admin/). ## Lỗi {#errors} Lỗi có định dạng JSON: `{"error": {"code": "...", "message": "..."}}`. | HTTP | `code` | Ý nghĩa | Cách khắc phục | |---|---|---|---| | 401 | `invalid_key` | Key bị thiếu, sai định dạng hoặc không xác định. Cũng được trả về khi key `ak_` được sử dụng trên path không thuộc admin. | Kiểm tra lại key; chỉ sử dụng trên `/v1/admin/` và `/mcp/admin`. | | 401 | `key_expired` | Key đã hết hạn. | Tạo một key mới. | | 401 | `key_revoked` | Key đã bị thu hồi. | Tạo một key mới. | | 403 | `ip_not_allowed` | IP của bên gọi nằm ngoài dải IP của key. | Gọi từ IP được cho phép, hoặc tạo key với dải IP phù hợp. | | 403 | `local_only_key` | Key được tạo cho AI Chat hoặc server CLI đã được dùng từ một máy khác. | Các key này chỉ hoạt động trên chính panel server. | | 403 | `insufficient_scope` | Key thiếu scope; phản hồi bao gồm `required_scope`. | Tạo key có scope đó. | | 403 | `forbidden_for_keys` | Endpoint, hoặc thiết lập bạn đang cố thay đổi, không mở cho truy cập bằng key. | Thực hiện thao tác này trong trang admin. | | 403 | `demo_read_only` | Panel đang ở chế độ demo và lệnh gọi này là thao tác ghi dữ liệu. | Sử dụng panel không phải bản demo. | | 403 | `confirm_in_ui` | Hành động này phải được xác nhận trực tiếp trên màn hình trong trang admin. | Phê duyệt thẻ xác nhận. | | 428 | `confirm_required` | Bản xem trước đã sẵn sàng; chưa có gì thay đổi. Bao gồm `confirm_token`. | Hiển thị bản xem trước, sau đó lặp lại với `X-Confirm-Token`. | | 409 | `confirm_expired` | Token đã tồn tại quá 5 phút. | Gửi lại request để lấy bản xem trước mới. | | 409 | `confirm_mismatch` | Token thuộc về một request khác (khác method, path hoặc body). | Lặp lại request giống hệt. | | 409 | `confirm_invalid` | Token không xác định hoặc đã được sử dụng. | Gửi lại request để lấy bản xem trước mới. | | 429 | `rate_limited` | Quá nhiều lệnh gọi trong phút này. | Chờ `Retry-After`. | | 400 | `invalid_path` | Path chứa các chuỗi ký tự bị cấm. | Dùng đường dẫn thông thường. | | 413 | `too_large` | Dung lượng body vượt quá 10 MB. | Gửi ít dữ liệu hơn. | | 400 | `invalid_argument` | Thiếu, không xác định hoặc sai kiểu đối số của công cụ; thông báo lỗi sẽ chỉ rõ đối số đó. | Sửa lại đối số. | ## Hạn mức & lưu ý {#limits-notes} - Hãy đặt thời hạn khóa ngắn và giới hạn phạm vi hẹp. Nên dùng mỗi client một khóa riêng để bạn có thể thu hồi từng khóa đơn lẻ. - Khóa có quyền hạn tương ứng với các scope của nó. `secrets:write` cùng `billing:write` là sự kết hợp nhạy cảm nhất; các tác vụ liên quan đến tiền vẫn sẽ dừng lại ở bước xem trước. - Các khóa được tạo tự động (cho AI Chat, server CLI) chỉ tồn tại trong vài phút và chỉ hoạt động từ chính server của panel. - Để ngắt kết nối client AI ngay lập tức, hãy thu hồi khóa của nó. Các kết nối OAuth được thu hồi tại tab **Connected apps** ([OAuth connectors](https://nexcmp.com/vi/docs/configure-with-ai/oauth-connectors/)). --- # Kết nối client AI (MCP) {#connect-an-ai-client-mcp} > **Vị trí trong admin:** System › Settings › API & AI agents (`/agent/keys`), tab **Connect an AI** hiển thị URL endpoint và đoạn mã cấu hình có sẵn cho từng client, điền sẵn khóa bạn vừa tạo. ## Chức năng {#what-it-does} **Model Context Protocol (MCP)** cho phép client AI gọi các công cụ. Panel của bạn cung cấp một admin MCP server tại `https://cloud.example.com/mcp/admin`. Hãy kết nối công cụ AI của bạn với server này và hỏi bằng ngôn ngữ tự nhiên: "what is left to set up?", "add my Proxmox cluster", "create plans with a 40% margin". Client sẽ gọi các công cụ quản trị bên dưới; panel sẽ kiểm tra scope, hỏi bạn trước mọi tác vụ có rủi ro và ghi log từng lệnh gọi. ::: info Hai MCP endpoint `/mcp` là endpoint dành cho **khách hàng** (API key khách hàng, `vk_`; xem [MCP server](https://nexcmp.com/vi/docs/developers/mcp/)). `/mcp/admin` là endpoint dành cho **quản trị** được mô tả ở đây (khóa admin `ak_` hoặc OAuth). Hai endpoint này không bao giờ lẫn lộn: các công cụ admin không hiển thị trên `/mcp`, và `/mcp/admin` chỉ chấp nhận khóa admin. ::: ## Yêu cầu {#requirements} | Hạng mục | Yêu cầu | |---|---| | Endpoint | `https://cloud.example.com/mcp/admin` trên chính domain panel của bạn. Hãy sao chép chính xác URL từ tab **Connect an AI**. Trang này cũng liệt kê một URL cục bộ (`http://127.0.0.1:/mcp/admin`) dành cho các công cụ chạy trực tiếp trên chính server. | | Thông tin xác thực | Một [admin API key](https://nexcmp.com/vi/docs/configure-with-ai/admin-api-keys/) (`ak_...`) với các scope bạn muốn, **hoặc** đăng nhập OAuth cho các connector nền web ([OAuth connectors](https://nexcmp.com/vi/docs/configure-with-ai/oauth-connectors/)). | | Client | Bất kỳ MCP client nào hỗ trợ transport **Streamable HTTP** và header `Authorization` tùy chỉnh. Các phiên bản giao thức 2025-11-25, 2025-06-18 và 2025-03-26. | | Mạng | Nếu bạn đặt reverse proxy riêng phía trước panel, nó phải chuyển tiếp `/mcp/admin`. Các connector nền web (claude.ai, ChatGPT) kết nối từ server của nhà cung cấp, do đó URL phải truy cập được từ internet. | ## Chuẩn bị hạ tầng {#prepare-the-infrastructure} Không cần cài đặt gì trên server. Nếu bạn giới hạn khóa theo IP, hãy đảm bảo địa chỉ client kết nối nằm trong dải cho phép. Kiểm tra khả năng kết nối trước: ```bash curl -i -X POST https://cloud.example.com/mcp/admin ``` Phản hồi `401` với header `WWW-Authenticate: Bearer ... resource_metadata=...` có nghĩa là endpoint đang hoạt động và yêu cầu thông tin xác thực. ## Kết nối trong NexCMP {#connect-in-nexcmp} 1. Tạo khóa: **System › Settings › API & AI agents › API keys › New key**. Với lần thử đầu tiên, chỉ nên dùng `admin:read`; thêm các write scope khi cần. Xem [Admin API keys](https://nexcmp.com/vi/docs/configure-with-ai/admin-api-keys/). 2. Mở tab **Connect an AI**. Khi hộp thoại "key created" vừa mới hiển thị, mỗi đoạn mã bên dưới đã chứa sẵn khóa thực của bạn. Nếu không, nó sẽ hiển thị placeholder `ak_YOUR_KEY`. 3. Sao chép đoạn mã cho client của bạn rồi chạy hoặc dán như hướng dẫn tiếp theo. ![Tab Connect an AI với URL MCP và mỗi client một thẻ kèm nút sao chép](https://nexcmp.com/vi/docs/images/configure-with-ai/mcp-admin-01-connect.webp) ### Claude Code {#claude-code} ```bash claude mcp add --transport http nexcmp https://cloud.example.com/mcp/admin \ --header "Authorization: Bearer ak_XXXX" ``` Sau đó khởi động `claude` và hỏi "list the tools from nexcmp" hoặc "what is left to set up?". Đã kiểm tra vào ngày 30/10/2026 với Claude Code 2.1: `claude mcp add --transport http …` ghi server (thêm `-s project` để lưu trong `.mcp.json` của project — Claude Code sẽ yêu cầu bạn phê duyệt server project trong lần đầu). Đối với script, `claude -p "…" --mcp-config .mcp.json --strict-mcp-config --allowedTools "mcp__nexcmp__*"` chạy mà không cần lời nhắc phê duyệt và chỉ cho phép Claude sử dụng các công cụ của panel. ### Claude Desktop {#claude-desktop} Yêu cầu Node.js 18 trở lên. Thêm nội dung này vào `claude_desktop_config.json` (sử dụng bridge `mcp-remote`) và khởi động lại Claude Desktop: ```json { "mcpServers": { "nexcmp": { "command": "npx", "args": ["-y", "mcp-remote", "https://cloud.example.com/mcp/admin", "--header", "Authorization:Bearer ak_XXXX"] } } } ``` Nếu hệ thống của bạn làm lỗi dấu cách trong đối số header, hãy đặt toàn bộ giá trị vào một biến môi trường, tương tự như với customer endpoint: `"args": [..., "--header", "Authorization:${NEXCMP_AUTH_HEADER}"]` với `"env": { "NEXCMP_AUTH_HEADER": "Bearer ak_XXXX" }`. ### claude.ai (custom connector) {#claude-ai-custom-connector} Không cần khóa: đăng nhập bằng OAuth. Trong claude.ai, mở cài đặt connectors, thêm custom connector, dán `https://cloud.example.com/mcp/admin`, sau đó đăng nhập bằng tài khoản admin NexCMP của bạn và chọn quyền trên màn hình xác nhận. Chi tiết: [OAuth connectors](https://nexcmp.com/vi/docs/configure-with-ai/oauth-connectors/). ### ChatGPT (developer mode) {#chatgpt-developer-mode} Không cần khóa. Trong ChatGPT, bật developer mode, thêm một MCP connector với URL `https://cloud.example.com/mcp/admin`, chọn OAuth và đăng nhập bằng tài khoản admin NexCMP của bạn. Chi tiết: [OAuth connectors](https://nexcmp.com/vi/docs/configure-with-ai/oauth-connectors/). ### Codex CLI {#codex-cli} Thêm vào `~/.codex/config.toml`: ```toml [mcp_servers.nexcmp] url = "https://cloud.example.com/mcp/admin" bearer_token_env_var = "NEXCMP_KEY" ``` Sau đó export khóa trong shell khởi chạy Codex: ```bash export NEXCMP_KEY=ak_XXXX codex codex mcp list # shows nexcmp with "Bearer token" auth ``` ::: tip `codex exec` không tương tác Trong `codex exec` (script, CI), Codex không hỏi trước khi gọi tool và bỏ qua các tool làm thay đổi dữ liệu. Thêm `default_tools_approval_mode = "approve"` dưới `[mcp_servers.nexcmp]` để cho phép gọi chúng; bảng điều khiển vẫn trả về bản xem trước và yêu cầu xác nhận đối với các tác vụ liên quan đến tiền tệ, bảo mật và xóa. Đã kiểm tra với Codex CLI 0.166 vào 30/10/2026. ::: ### Gemini CLI {#gemini-cli} Thêm vào `~/.gemini/settings.json`: ```json { "mcpServers": { "nexcmp": { "httpUrl": "https://cloud.example.com/mcp/admin", "headers": { "Authorization": "Bearer ak_XXXX" } } } } ``` Gemini CLI tắt MCP server trong các thư mục mà nó không tin cậy. Hãy khởi chạy nó trong thư mục bạn tin cậy (hoặc chọn tin cậy thư mục khi được hỏi), sau đó kiểm tra bằng `gemini mcp list` — kết quả sẽ hiển thị `nexcmp … Connected`. Bạn có thể không lưu khóa trong file bằng cách dùng `"Authorization": "Bearer $NEXCMP_KEY"`. Đã kiểm tra với Gemini CLI 0.66 vào 30/10/2026. ### Cursor {#cursor} Thêm vào `~/.cursor/mcp.json` (hoặc `.cursor/mcp.json` trong dự án): ```json { "mcpServers": { "nexcmp": { "url": "https://cloud.example.com/mcp/admin", "headers": { "Authorization": "Bearer ak_XXXX" } } } } ``` ::: tip Không lưu khóa trong file cấu hình Nếu client hỗ trợ, hãy đọc khóa từ biến môi trường thay vì ghi trực tiếp vào file: Codex thực hiện việc này theo mặc định (`bearer_token_env_var`), và Cursor hỗ trợ `"Bearer ${env:NEXCMP_KEY}"`. Không bao giờ commit file có chứa khóa. ::: ### OpenAI Agents SDK (Python) {#openai-agents-sdk-python} ```python from agents.mcp import MCPServerStreamableHttp nexcmp = MCPServerStreamableHttp( params={"url": "https://cloud.example.com/mcp/admin", "headers": {"Authorization": "Bearer ak_XXXX"}}, name="nexcmp", ) ``` Một lượt chạy hoàn chỉnh (đã kiểm tra với `openai-agents` 0.24 vào 30/10/2026 — tool đọc dữ liệu, sau đó là thay đổi số dư trả về bản xem trước để xác nhận và được áp dụng ở lần gọi thứ hai với `confirm_token`): ```python import asyncio from agents import Agent, Runner from agents.mcp import MCPServerStreamableHttp async def main(): async with MCPServerStreamableHttp(params={"url": "https://cloud.example.com/mcp/admin", "headers": {"Authorization": "Bearer ak_XXXX"}}, name="nexcmp") as nexcmp: agent = Agent(name="admin", model="gpt-5", mcp_servers=[nexcmp], instructions="You operate a hosting panel through the nexcmp tools. Ask me before confirming money actions.") result = await Runner.run(agent, "Run system_health and summarise it in one line.") print(result.final_output) asyncio.run(main()) ``` ### OpenAI Responses API {#openai-responses-api} Truyền server dưới dạng một tool thuộc loại `mcp`. Giữ `require_approval` ở `always` để chương trình hỏi bạn trước mỗi lần gọi: ```json { "type": "mcp", "server_label": "nexcmp", "server_url": "https://cloud.example.com/mcp/admin", "headers": { "Authorization": "Bearer ak_XXXX" }, "require_approval": "always" } ``` ### Các trường hợp khác (plain HTTP) {#anything-else-plain-http} Client không có MCP vẫn có thể gọi các tool này qua HTTP. `GET /v1/admin/agent/tools` liệt kê danh sách tool, `POST /v1/admin/agent/tools/` chạy một tool với JSON body chứa các đối số, và `GET /v1/admin/openapi.json` trả về mô tả OpenAPI 3.1 (mỗi tool là một operation). Tất cả đều cần `Authorization: Bearer ak_...`. ## Kiểm tra {#verify} 1. Liệt kê các tool mà không cần client: ```bash curl -s https://cloud.example.com/mcp/admin \ -H "Authorization: Bearer ak_XXXX" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' ``` Kết quả trả về là một JSON-RPC result chứa các tool mà scope của bạn cho phép. 2. Trong client của bạn, yêu cầu "run system_health". Lệnh này trả về các cảnh báo, tình trạng hạ tầng kết nối, thanh toán, email, AI và trạng thái giấy phép. 3. Mở **API & AI agents › Activity**: các lệnh gọi được liệt kê cùng tên client và `mcp`. 4. Trên server, `sudo nexcmp status` in ra dòng "MCP admin" thông báo `ready` khi endpoint phản hồi (HTTP 401 khi không có khóa là trạng thái bình thường). ## Công cụ {#tools} Server cung cấp 58 tool. Client chỉ thấy các tool được scope của khóa cho phép: tool đọc cần `admin:read`, tool ghi cần scope tương ứng. Tool ghi cũng có thêm đối số tùy chọn `confirm_token` (xem [Confirmation](#confirmation-confirm-token)). Các đối số được xác thực theo schema của từng tool: đối số không xác định hoặc sai kiểu sẽ bị từ chối kèm thông báo chỉ rõ tên đối số đó. Giá tính bằng USD: giá gói cước tính bằng USD mỗi giờ (`hourly_usd`), số dư tính bằng cent. Thông tin bảo mật có thể thiết lập nhưng không bao giờ được trả về. ### Tổng quan và nhật ký {#overview-and-logs} | Công cụ | Chức năng | Scope | Thay đổi dữ liệu | Yêu cầu xác nhận | |---|---|---|---|---| | `system_health` | Cảnh báo cần xử lý, tình trạng hạ tầng, thanh toán, email, AI, giấy phép và trạng thái cập nhật. | `admin:read` | Không | Không | | `setup_checklist` | Những mục đã cấu hình và còn lại: giấy phép, hạ tầng, zone, OS template, gói cước, thanh toán, email, thương hiệu, pháp lý, đơn hàng thử nghiệm. | `admin:read` | Không | Không | | `license_status` | Trạng thái giấy phép và liệu có phiên bản NexCMP mới hơn hay không. | `admin:read` | Không | Không | | `audit_search` | Tìm kiếm audit log quản trị và log API key. | `admin:read` | Không | Không | ### Cài đặt, thương hiệu, pháp lý, module {#settings-branding-legal-modules} | Công cụ | Chức năng | Scope | Thay đổi dữ liệu | Yêu cầu xác nhận | |---|---|---|---|---| | `settings_get` | Đọc cài đặt chung (`keys` lọc; ký tự `*` ở cuối khớp với tiền tố). | `admin:read` | Không | Không | | `settings_update` | Thay đổi cài đặt chung từ đối tượng `values` phẳng. Chỉ chấp nhận các key được liệt kê bởi `settings_get`. | `settings:write` | Có | Khi một key liên quan đến thanh toán, bảo mật đăng nhập, các nút bật tắt toàn trang hoặc giá bán | | `branding_get` | Tên thương hiệu, màu sắc, đơn vị tiền tệ hiển thị, tên người bán, URL logo và favicon. | `admin:read` | Không | Không | | `branding_update` | Đặt tên thương hiệu (tối đa 60 ký tự), màu sắc (`#rrggbb`), đơn vị tiền tệ hiển thị (`usd` hoặc `vnd`) và tên người bán. | `settings:write` | Có | Không | | `branding_logo_set` | Tải lên logo sáng hoặc tối hoặc favicon từ URL https hoặc base64 (PNG, JPEG, WEBP, ICO hoặc SVG, tối đa 512 KB). | `settings:write` | Có | Không | | `legal_get` | Điều khoản dịch vụ và chính sách quyền riêng tư (tiếng Anh và tiếng Việt) cùng các giá trị mặc định trung tính. | `admin:read` | Không | Không | | `legal_update` | Thiết lập văn bản điều khoản và quyền riêng tư (markdown đơn giản, không chứa HTML, tối đa 50 KB mỗi mục). Chuỗi rỗng sẽ khôi phục mặc định. | `settings:write` | Có | Không | | `modules_get` | Các module tùy chọn nào đang bật và module nào có thể bật tắt. | `admin:read` | Không | Không | | `module_set` | Bật hoặc tắt module tùy chọn (`key` phải là một trong `settable`). | `settings:write` | Có | Không | ### Email và cảnh báo {#email-and-alerts} | Công cụ | Chức năng | Scope | Thay đổi dữ liệu | Yêu cầu xác nhận | |---|---|---|---|---| | `smtp_get` | Cài đặt email gửi đi (mật khẩu bị ẩn) và trạng thái hàng đợi. | `admin:read` | Không | Không | | `smtp_configure` | Thiết lập máy chủ SMTP. Việc thay đổi host, port hoặc bảo mật sẽ yêu cầu nhập lại mật khẩu. | `settings:write` (+ `secrets:write` cho mật khẩu) | Có | Không | | `smtp_test` | Gửi email thử nghiệm thực tế với các cài đặt đã lưu. | `settings:write` | Gửi một email | Không | | `telegram_get` | Các kênh thông báo của quản trị viên (chat id; bot token không bao giờ được trả về). | `admin:read` | Không | Không | | `telegram_configure` | Thêm hoặc cập nhật kênh cảnh báo Telegram (bot token và chat id) và bật hoặc tắt cảnh báo quản trị viên. | `settings:write` (+ `secrets:write` cho token) | Có | Không | | `telegram_test` | Gửi tin nhắn thử nghiệm đến kênh Telegram. | `settings:write` | Gửi một tin nhắn | Không | ### Thanh toán và tiền tệ {#payments-and-currency} | Công cụ | Chức năng | Scope | Thay đổi dữ liệu | Yêu cầu xác nhận | |---|---|---|---|---| | `payments_get` | Trạng thái của Stripe, PayPal, crypto (USDT) và chuyển khoản ngân hàng, cùng các kênh được kích hoạt và phí. | `admin:read` | Không | Không | | `payment_configure` | Thiết lập thông tin xác thực cho một cổng (`stripe`, `paypal`, `crypto` hoặc `bank`). | `billing:write` (+ `secrets:write`) | Có | Luôn luôn | | `payment_test` | Kiểm tra thông tin xác thực đã lưu của cổng thanh toán với nhà cung cấp. | `billing:write` | Không | Không | | `currency_get` | Đơn vị tiền tệ hiển thị và tỷ giá USD sang VND (tự động hoặc thủ công). | `admin:read` | Không | Không | | `currency_set` | Đặt đơn vị tiền tệ hiển thị và/hoặc tỷ giá thủ công (0 nghĩa là tự động, nếu không sẽ từ 15000 đến 50000). | `billing:write` | Có | Khi bạn thay đổi tỷ giá thủ công | ### Hạ tầng và zone {#infrastructure-and-zones} | Công cụ | Chức năng | Scope | Thay đổi dữ liệu | Yêu cầu xác nhận | |---|---|---|---|---| | `cloudstack_get` | Endpoint CloudStack đã lưu cùng zone id và network id (các key bị ẩn). | `admin:read` | Không | Không | | `cloudstack_test` | Kiểm tra endpoint với API key và secret mà không lưu; liệt kê các zone. | `infra:write` (+ `secrets:write`, vì bạn truyền các key) | Không | Không | | `cloudstack_connect` | Lưu kết nối CloudStack. | `infra:write` (+ `secrets:write`) | Có | Luôn luôn | | `proxmox_list` | Các cụm Proxmox VE được thêm làm nguồn, cùng tình trạng hoạt động. | `admin:read` | Không | Không | | `proxmox_add` | Thêm cụm Proxmox VE bằng API token (`user@realm!tokenid`) và secret của nó. | `infra:write` (+ `secrets:write`) | Có | Không | | `proxmox_test` | Kết nối tới cụm theo id; lần thành công đầu tiên sẽ ghim chứng chỉ TLS của cụm. | `infra:write` | Có | Không | | `proxmox_attach_zone` | Bán cụm Proxmox trong một zone hiện có, tùy chọn với một node làm region. | `infra:write` | Có | Không | | `zones_list` | Các zone (vị trí) mà khách hàng có thể chọn. | `admin:read` | Không | Không | | `zone_create` | Tạo một zone. | `infra:write` | Có | Không | ### Danh mục và gói cước {#catalog-and-plans} | Công cụ | Chức năng | Scope | Thay đổi dữ liệu | Yêu cầu xác nhận | |---|---|---|---|---| | `templates_list` | Template OS khách hàng có thể cài đặt. | `admin:read` | Không | Không | | `templates_sync` | Import OS template từ CloudStack. | `catalog:write` | Có | Không | | `template_update` | Bật hoặc ẩn template, đổi tên, đặt user đăng nhập hoặc thứ tự sắp xếp. | `catalog:write` | Có | Không | | `offerings_list` | Service offering của CloudStack (CPU, RAM, root disk) dùng để tạo gói dịch vụ. | `admin:read` | Không | Không | | `plans_list` | Các gói dịch vụ với giá mỗi giờ và mỗi tháng, cấu hình, zone và số lượng server đang sử dụng. | `admin:read` | Không | Không | | `plan_create` | Tạo gói dịch vụ. Giá theo `hourly_usd`. Gói CloudStack cần `cs_offering_id`; gói Proxmox cần `backend_id`. | `catalog:write` | Có | Không | | `plan_update` | Đổi tên, hiện hoặc ẩn, bật hoặc tắt, hoặc định giá lại gói dịch vụ. Thay đổi cấu hình của gói đang được sử dụng sẽ cần tạo bản sao. | `catalog:write` | Có | Khi giá thay đổi | | `plans_from_offerings` | Tạo bảng gói dịch vụ khởi đầu từ offering (hoặc cấu hình Proxmox) dựa trên chi phí và phần trăm biên lợi nhuận của bạn. Trả về bản xem trước; gọi lại với `apply=true` để tạo các gói dịch vụ. | `catalog:write` | Với `apply=true` | Luôn hỏi khi áp dụng | | `quota_defaults_get` | Hạn mức khách hàng mặc định. | `admin:read` | Không | Không | | `quota_defaults_set` | Thay đổi cài đặt `quota_*`. | `catalog:write` | Có | Không | | `coupons_list` | Các đợt mã giảm giá và mã quà tặng. | `admin:read` | Không | Không | | `coupon_create` | Tạo một đợt mã: loại `money` (mệnh giá tính bằng cent USD) hoặc `percent` (1 đến 100, kèm mức giảm tối đa). | `catalog:write` | Có | Luôn luôn | ### Khách hàng và đại lý {#customers-and-resellers} | Công cụ | Chức năng | Scope | Thay đổi dữ liệu | Yêu cầu xác nhận | |---|---|---|---|---| | `customers_search` | Tìm kiếm khách hàng theo email, tên hoặc IP. | `admin:read` | Không | Không | | `customer_get` | Tài khoản, số dư, server và thanh toán gần đây của một khách hàng. | `admin:read` | Không | Không | | `customer_adjust_balance` | Cộng (dương) hoặc trừ (âm) số dư bằng cent USD. Bắt buộc nhập lý do. | `billing:write` | Có | Luôn luôn | | `customer_block` | Chặn khách hàng, tuỳ chọn dừng các server của họ. Bắt buộc nhập lý do. | `customers:write` | Có | Luôn luôn | | `customer_unblock` | Bỏ chặn khách hàng. | `customers:write` | Có | Không | | `resellers_list` | Các đại lý cùng ví tiền và trạng thái. | `admin:read` | Không | Không | | `reseller_get` | Trang web, ví tiền, người dùng và cổng thanh toán của một đại lý. | `admin:read` | Không | Không | ### Nhà cung cấp AI {#ai-provider} | Công cụ | Chức năng | Scope | Thay đổi dữ liệu | Yêu cầu xác nhận | |---|---|---|---|---| | `ai_provider_get` | Nhà cung cấp tương thích OpenAI được AI Chat và AI Agent của khách hàng sử dụng (key đã được ẩn). | `admin:read` | Không | Không | | `ai_provider_set` | Thiết lập nhà cung cấp: base URL, model, API key, fallback model, reasoning effort, enabled. | `ai:write` (+ `secrets:write` dành cho key) | Có | Không | | `ai_provider_test` | Đặt một câu hỏi cho nhà cung cấp đã lưu để kiểm tra xem có hoạt động không. | `ai:write` | Không | Không | ### Tệp cấu hình {#configuration-files} | Công cụ | Chức năng | Scope | Thay đổi dữ liệu | Yêu cầu xác nhận | |---|---|---|---|---| | `config_export` | Xuất cấu hình dưới dạng YAML (thông tin bảo mật trở thành tham chiếu `secret://`). | `admin:read` | Không | Không | | `config_plan` | So sánh cấu hình YAML với trang quản trị đang chạy và liệt kê các thay đổi. | `admin:read` | Không | Không | | `config_apply` | Áp dụng cấu hình YAML theo từng phần. Mỗi thay đổi đều tuân theo các quy tắc phạm vi và xác nhận thông thường. | `admin:read` + phạm vi của từng thay đổi | Có | Với mỗi thay đổi | Xem [Cấu hình dưới dạng code](https://nexcmp.com/vi/docs/configure-with-ai/config-as-code/) để biết định dạng tệp. ## Prompt {#prompts} Server cũng cung cấp ba prompt có sẵn để client có thể hiển thị dưới dạng phím tắt: | Prompt | Đối số | Yêu cầu AI thực hiện | |---|---|---| | `initial-setup` | không có | Gọi `setup_checklist`, giải thích từng bước chưa hoàn tất trong một câu, hỏi bạn thông tin cần thiết, thực hiện bước đó bằng công cụ phù hợp, xem trước các thay đổi về chi phí hoặc bảo mật, và kết thúc bằng `system_health`. | | `add-proxmox` | `endpoint` (tuỳ chọn, `https://host:8006`) | Yêu cầu cung cấp API token, sau đó là `proxmox_add`, `proxmox_test`, các công cụ zone và `proxmox_attach_zone`; tiếp theo đề xuất các gói dịch vụ bằng `plans_from_offerings` và chờ bạn phê duyệt. | | `launch-pricing` | `margin_pct` (tuỳ chọn, mặc định 40) | Hỏi chi phí hàng tháng trên mỗi vCPU, mỗi GB RAM và mỗi GB ổ đĩa của bạn, hiển thị bảng xem trước gồm chi phí, giá mỗi tháng và giá mỗi giờ, sau đó tạo các gói sau khi bạn phê duyệt. | ## Xác nhận (`confirm_token`) {#confirmation-confirm-token} Các thao tác luân chuyển tiền, xóa dữ liệu, thay đổi thông tin thanh toán hoặc bảo mật đăng nhập đều gồm hai bước: 1. Lần gọi đầu tiên không thay đổi điều gì. Kết quả của tool bắt đầu bằng "CONFIRMATION REQUIRED" và kèm theo một **bản xem trước** (thao tác nào sẽ được gọi, vì sao thao tác này nhạy cảm, các giá trị mới và giá trị hiện tại) cùng một `confirm_token`. 2. Client phải hiển thị bản xem trước cho bạn. Chỉ sau khi bạn phê duyệt, client mới gọi lại tool đó với cùng các đối số cộng thêm `confirm_token`. 3. Token chỉ dùng được một lần, riêng cho yêu cầu chính xác đó và hết hạn sau 5 phút. Hướng dẫn của server chỉ định AI xem kết quả tool là dữ liệu chứ không phải chỉ thị, và không bao giờ được lặp lại lệnh gọi bằng token mà bạn chưa phê duyệt. Bạn chính là chốt chặn an toàn: hãy đọc kỹ bản xem trước. ::: warning Không tự động phê duyệt Một số client có thể tự động phê duyệt mọi lệnh gọi tool. Đối với các write tool, hãy bật chế độ phê duyệt cho từng lệnh gọi hoặc dùng key chỉ đọc (read-only), để kế hoạch sai từ AI không thể tác động đến panel của bạn mà bạn không biết. ::: ## Cách thức hoạt động {#how-it-works} | Hạng mục | Chi tiết | |---|---| | Giao thức truyền tải | `POST /mcp/admin` với thông điệp JSON-RPC 2.0; phản hồi là `application/json`. Tối đa 20 thông điệp trong một batch. `GET /mcp/admin` trả về 405 (không có server stream); `DELETE /mcp/admin` kết thúc một phiên. | | Xác thực | `Authorization: Bearer ak_...` (key thủ công hoặc access token OAuth). Thiếu hoặc sai thông tin xác thực sẽ trả về 401 kèm `WWW-Authenticate: Bearer ... resource_metadata=...`, cho phép các OAuth client tự khởi tạo đăng nhập. | | Phiên | `Mcp-Session-Id` được cấp bởi `initialize`, liên kết với key đó và có hiệu lực trong 24 giờ. | | Capabilities | Tools và prompts. Không có resources. | | Kích thước | Request body tối đa 1 MB; kết quả của tool bị cắt ngắn sau khoảng 100 KB. | | Origin | Request mang header `Origin` từ trang khác sẽ bị từ chối (`origin_not_allowed`). Client dòng lệnh và desktop không gửi header này. | | Cùng cơ chế kiểm soát như REST | Mỗi lệnh gọi tool được gửi lại qua pipeline xử lý request của chính panel bằng key của bạn, vì vậy các scope, dải IP, rate limit, xác nhận và nhật ký hoạt động đều áp dụng y hệt như các lệnh gọi API trực tiếp. | ## Hạn mức & lưu ý {#limits-notes} - Nếu không thấy một tool nào đó, tức là bạn chưa cấp scope tương ứng. Hãy thêm scope vào một key mới. - Thiết lập mật khẩu hoặc API key qua AI client đồng nghĩa với việc thông tin bí mật sẽ đi qua AI đó. Nếu muốn, bạn có thể tắt `secrets:write` và tự nhập các thông tin bí mật trong admin, hoặc dùng trường **Secret** của AI Chat ([AI Chat trong admin](https://nexcmp.com/vi/docs/configure-with-ai/ai-chat-in-admin/#secrets)) hay các tham chiếu `secret://` ([Cấu hình dưới dạng code](https://nexcmp.com/vi/docs/configure-with-ai/config-as-code/#secrets)). - Các client không chia sẻ phiên với nhau: mỗi kết nối đều bắt đầu bằng `initialize`. - Thu hồi key trong **API & AI agents** để ngắt kết nối của AI client ngay lập tức. ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | 401 `invalid_key` | Key sai, bị cắt ngắn hoặc không có quyền admin (ví dụ key `vk_`) | Dùng key `ak_`. | | 401 `key_expired` hoặc `key_revoked` | Key đã hết hạn hoặc bị thu hồi | Tạo một key mới. | | 403 `ip_not_allowed` | IP của bạn nằm ngoài các dải IP của key | Kết nối từ một IP được cho phép. | | 403 `origin_not_allowed` | Một trang trình duyệt từ origin khác đã gọi endpoint này | Dùng client desktop hoặc CLI. | | 404 đối với request có `Mcp-Session-Id` | Phiên thuộc về một key khác hoặc đã hết hạn | Gửi lại `initialize`. | | 400 unsupported `MCP-Protocol-Version` | Client sử dụng phiên bản mà server không nhận biết | Cập nhật client; hỗ trợ: 2025-11-25, 2025-06-18, 2025-03-26. | | Danh sách tool bị ngắn | Scope của key | Tạo một key có nhiều scope hơn. | | `insufficient_scope` trong một lệnh gọi | Công cụ cần thêm một scope thứ hai, ví dụ `secrets:write` | Thêm scope đó vào một key mới. | | 429 `rate_limited` | Số lượt gọi mỗi phút vượt quá giới hạn của key | Chờ đến `Retry-After` hoặc tăng giới hạn trên một key mới. | | claude.ai hoặc ChatGPT không thể kết nối | URL không truy cập được từ internet, hoặc proxy chặn `/mcp/admin` hoặc `/oauth-admin/` | Kiểm tra DNS, TLS và reverse proxy. | Để xem tất cả mã lỗi, hãy xem [Admin API keys](https://nexcmp.com/vi/docs/configure-with-ai/admin-api-keys/#errors). --- # Connector claude.ai và ChatGPT {#claude-ai-and-chatgpt-connectors} > **Vị trí trong trang admin:** System › Settings › API & AI agents (`/agent/keys`), tab **Connected apps**. Màn hình cấp quyền mở tại `/agent/consent` khi connector yêu cầu quyền truy cập (mục này không có trong menu). ## Chức năng {#what-it-does} Các ứng dụng AI web không thể đọc key từ ổ đĩa của bạn. Chúng kết nối qua **OAuth**: bạn thêm URL MCP của panel, ứng dụng sẽ chuyển bạn đến trang admin của chính mình để đăng nhập, bạn chọn những gì ứng dụng được phép thực hiện và trong bao lâu, sau đó ứng dụng sẽ nhận token ngắn hạn. Không cần sao chép hay dán key nào. Bạn có thể ngắt kết nối ứng dụng bất kỳ lúc nào. Sử dụng tính năng này cho custom connector của claude.ai, connector ở developer mode của ChatGPT và bất kỳ MCP client nào khác hỗ trợ OAuth với dynamic client registration. Các công cụ dòng lệnh cũng có thể dùng quy trình này, nhưng [admin API key](https://nexcmp.com/vi/docs/configure-with-ai/admin-api-keys/) sẽ đơn giản hơn đối với chúng. ## Yêu cầu {#requirements} | Hạng mục | Yêu cầu | |---|---| | URL | `https://cloud.example.com/mcp/admin`, có thể truy cập từ internet (các máy chủ của nhà cung cấp sẽ kết nối tới URL này). | | Reverse proxy | Nếu bạn đặt proxy riêng phía trước panel, proxy phải chuyển tiếp các đường dẫn `/mcp/admin`, `/oauth-admin/` và `/.well-known/` tới panel. | | Bạn | Đã đăng nhập vào admin NexCMP **trên cùng trình duyệt** mà bạn dùng cho màn hình cấp quyền. | | Client | Hỗ trợ MCP qua Streamable HTTP, OAuth 2.1 với PKCE (S256) và dynamic client registration. | ## Kết nối {#connect} 1. Trong ứng dụng AI, thêm một custom MCP connector và dán `https://cloud.example.com/mcp/admin`. Trong claude.ai, mục này nằm trong cài đặt connectors (add custom connector); trong ChatGPT, mục này nằm trong developer mode (add an MCP connector, authentication OAuth). 2. Chọn **Sign in** (hoặc "Connect") trong ứng dụng. Trình duyệt của bạn sẽ mở màn hình cấp quyền của admin NexCMP. Nếu chưa đăng nhập, hãy đăng nhập trước; màn hình sẽ tiếp tục sau đó. 3. Đọc thông tin: "**Example AI app** wants to manage this NexCMP admin" (tên của ứng dụng đang yêu cầu), cùng địa chỉ mà bạn sẽ được chuyển hướng trở lại. 4. Đánh dấu chọn các scope cần cấp. Các scope mà ứng dụng yêu cầu đã được chọn sẵn; nếu ứng dụng không yêu cầu gì, chỉ có `admin:read` được chọn. Xem [Scopes](https://nexcmp.com/vi/docs/configure-with-ai/admin-api-keys/#scopes). 5. Chọn thời hạn kết nối: **7**, **30** hoặc **90** ngày (mặc định là 30). 6. Nhấp vào **Allow**. Trình duyệt quay trở lại ứng dụng, hiện đã được kết nối. Nhấp vào **Deny** để từ chối. ![Màn hình cấp quyền yêu cầu cho phép ứng dụng AI, với các hộp kiểm scope, tùy chọn thời hạn cùng các nút Allow và Deny](https://nexcmp.com/vi/docs/images/configure-with-ai/oauth-connectors-01-consent.webp) ::: important Chọn scope tương tự như khi tạo key Chỉ cấp bộ quyền tối thiểu vừa đủ cho nhu cầu. Các thao tác về tiền bạc, xóa và bảo mật vẫn sẽ dừng lại ở bước xem trước và cần bạn phê duyệt, nhưng một kết nối có `settings:write` vẫn có thể thay đổi thương hiệu và email của bạn. ::: ## Quản lý và thu hồi {#manage-and-revoke} Mở **System › Settings › API & AI agents › Connected apps**. Bảng sẽ liệt kê mọi ứng dụng bạn đã kết nối: ứng dụng, scope, thời điểm kết nối, thời điểm hết hạn và lần sử dụng gần nhất. Để ngắt kết nối một ứng dụng, hãy nhấp vào **Revoke** và xác nhận. Token của ứng dụng sẽ ngừng hoạt động ngay lập tức; ứng dụng phải đi qua màn hình cấp quyền lần nữa để kết nối lại. ![Tab Connected apps liệt kê một ứng dụng AI cùng các scope, thời hạn và nút Revoke](https://nexcmp.com/vi/docs/images/configure-with-ai/oauth-connectors-02-connected-apps.webp) ## Quy trình hoạt động {#how-the-flow-works} | Bước | Chi tiết | |---|---| | Discovery | Ứng dụng đọc `/.well-known/oauth-protected-resource/mcp/admin` rồi đến `/.well-known/oauth-authorization-server/oauth-admin`. Issuer là `https://cloud.example.com/oauth-admin`. | | Đăng ký | Ứng dụng tự đăng ký (`POST /oauth-admin/register`, RFC 7591). Chỉ hỗ trợ public client (không có client secret). Địa chỉ redirect phải là `https`, hoặc `http` trên cùng máy tính (loopback). | | Cấp quyền | `GET /oauth-admin/authorize` với phương thức PKCE `S256`. Tham số `resource`, khi được gửi, phải là URL `/mcp/admin` của bảng điều khiển này. Yêu cầu có hiệu lực trong 10 phút và được gắn với trình duyệt đã khởi tạo nó. | | Chấp thuận | Bạn chọn các scope và thời hạn (ở trên). Authorization code có hiệu lực trong 60 giây và chỉ sử dụng được một lần. | | Token | `POST /oauth-admin/token` trả về một **access token** (khóa `ak_o...`, có hiệu lực 1 giờ hoặc cho đến khi kết thúc kết nối, tùy điều kiện nào đến trước) và một **refresh token** (`akr_...`). Mỗi lần làm mới sẽ trả về một refresh token mới; token cũ sẽ ngừng hoạt động. Kết nối sẽ kết thúc sau số ngày bạn đã chọn. | | Thu hồi | **Revoke** trong Connected apps, hoặc ứng dụng gọi `POST /oauth-admin/revoke` (RFC 7009). | Access token hoạt động như một admin key với các scope bạn đã cấp: cùng quy tắc scope, xác nhận, rate limit và nhật ký hoạt động. Các lệnh gọi của token sẽ hiển thị trên tab **Activity**. ## Kiểm tra {#verify} 1. Trong ứng dụng, hãy hỏi "run system_health" (hoặc "what tools do you have?"). Ứng dụng sẽ liệt kê các công cụ mà scope của bạn cho phép ([danh sách công cụ](https://nexcmp.com/vi/docs/configure-with-ai/mcp-admin/#tools)). 2. Mở **Connected apps**: **Last used** thay đổi. 3. Mở **Activity**: các lệnh gọi được liệt kê cùng tên ứng dụng và `mcp`. ## Hạn mức & lưu ý {#limits-notes} - Nếu ứng dụng yêu cầu đăng nhập lại sau một giờ, điều này là bình thường khi client không tự làm mới; hãy kết nối lại. - Refresh token bị sử dụng hai lần sẽ bị coi là đã bị đánh cắp: toàn bộ kết nối sẽ bị thu hồi. Hãy kết nối lại từ ứng dụng. - Authorization code bị sử dụng hai lần sẽ bị từ chối (`invalid_grant`) và các token đã phát hành từ mã này sẽ bị thu hồi. - Quyền truy cập OAuth không bao giờ vượt quá các quy tắc scope cho phép: [những điều khóa không bao giờ có thể làm](https://nexcmp.com/vi/docs/configure-with-ai/admin-api-keys/#what-a-key-can-never-do) cũng áp dụng cho các ứng dụng đã kết nối. - Các nhà cung cấp có thể thay đổi menu và tính năng hỗ trợ. Nếu ứng dụng của nhà cung cấp không hỗ trợ custom connector trên gói của bạn, hãy sử dụng [admin API key](https://nexcmp.com/vi/docs/configure-with-ai/admin-api-keys/) với ứng dụng desktop hoặc dòng lệnh để thay thế. ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | Màn hình chấp thuận thông báo "Wrong browser" | Yêu cầu đã được khởi tạo trong trình duyệt khác với trình duyệt bạn đang đăng nhập | Bắt đầu lại kết nối từ ứng dụng AI trên cùng trình duyệt đó. | | Màn hình chấp thuận thông báo yêu cầu đã hết hạn hoặc không tồn tại | Đã quá 10 phút, hoặc liên kết đã bị mở hai lần | Bắt đầu lại kết nối từ ứng dụng AI. | | Trang "Unknown client" hoặc "redirect address does not match" | Bản đăng ký của ứng dụng đã cũ, hoặc ứng dụng sử dụng địa chỉ redirect chưa từng đăng ký | Xóa connector trong ứng dụng rồi thêm lại. | | `invalid_target` | `resource` được gửi không phải là URL `/mcp/admin` của bảng điều khiển này | Sử dụng chính xác URL hiển thị trên tab **Connect an AI**. | | `invalid_request` về PKCE | Client không gửi `code_challenge_method=S256` | Sử dụng client có hỗ trợ OAuth 2.1 cùng PKCE. | | Ứng dụng kết nối được nhưng một lệnh gọi trả về `insufficient_scope` | Bạn chưa tick chọn scope đó | Thu hồi kết nối và kết nối lại với scope đã được tích chọn. | | Ứng dụng không thể truy cập URL | DNS, TLS hoặc reverse proxy chặn `/mcp/admin`, `/oauth-admin/` hoặc `/.well-known/` | Kiểm tra lại các quy tắc proxy. | --- # Cấu hình dưới dạng mã {#configuration-as-code} > **Vị trí trong admin:** System › Settings › Import/Export (`/agent/config`). Trên máy chủ: các lệnh `nexcmp config export`, `plan` và `apply`, cùng `nexcmp admin `. ## Chức năng {#what-it-does} Cấu hình panel của bạn (branding, cài đặt chung, email, cảnh báo Telegram, module, tiền tệ, cổng thanh toán, giới hạn, zone, gói dịch vụ, nhà cung cấp AI và các trang pháp lý) có thể được lưu thành một file YAML duy nhất. Bạn có thể tự chỉnh sửa file, nhờ trợ lý AI chỉnh sửa, lưu vào hệ thống quản lý phiên bản và áp dụng cho cùng panel đó hoặc panel khác. Trước khi có bất kỳ thay đổi nào, bạn luôn thấy danh sách khác biệt. Secret không bao giờ được ghi vào file. Hãy dùng tính năng này để sao chép cấu hình sang bản cài đặt thứ hai, xem xét thay đổi trước khi áp dụng thực tế, khôi phục cài đặt sau sự cố hoặc để AI đề xuất toàn bộ cấu hình giúp bạn xem lại trong một tài liệu duy nhất. ## Yêu cầu {#requirements} | Hạng mục | Yêu cầu | |---|---| | NexCMP | 1.4.0 trở lên. | | Dòng lệnh | Bạn là `root` trên máy chủ panel (dùng `sudo`). Lệnh này sẽ tự động yêu cầu panel cấp một key tạm thời (15 phút, tất cả scope). Để dùng một key có phạm vi hẹp hơn, hãy đặt `NEXCMP_KEY` thành một [admin API key](https://nexcmp.com/vi/docs/configure-with-ai/admin-api-keys/) và giữ nguyên biến qua sudo, ví dụ `sudo --preserve-env=NEXCMP_KEY nexcmp config plan -f nexcmp.yaml`. | | Trang Admin | Đã đăng nhập vào admin. Trang này ở chế độ chỉ đọc trên panel demo. | | Bí mật | Giá trị được cung cấp tại thời điểm áp dụng (xem [Secrets](#secrets)); không bao giờ nằm trong file. | ## Xuất, chỉnh sửa, xem trước, áp dụng {#export-edit-preview-apply} 1. Xuất cấu hình hiện tại: ```bash sudo nexcmp config export -o nexcmp.yaml ``` Nếu không có `-o`, nội dung YAML sẽ được in ra màn hình. 2. Chỉnh sửa `nexcmp.yaml` (xem [ví dụ](#example-file) bên dưới). Giữ `version: 1` ở dòng đầu tiên. 3. Xem trước những thay đổi dự kiến. Lệnh này không thay đổi bất kỳ điều gì: ```bash sudo nexcmp config plan -f nexcmp.yaml ``` Mỗi dòng hiển thị section, item, trường và `old → new`. Các dòng có dấu `$` thuộc về các section thanh toán (xem [Billing sections](#billing-sections)). Nếu panel đã khớp với file, bạn sẽ thấy "No changes". 4. Áp dụng. Nếu không có `--yes`, lệnh sẽ chạy ở chế độ **dry run** và chỉ in ra danh sách tương tự: ```bash sudo nexcmp config apply -f nexcmp.yaml --yes ``` 5. Đọc kết quả: `applied`, `pending` (chờ bạn xác nhận), `skipped` và `errors`. | Tùy chọn | Ý nghĩa | |---|---| | `-f ` | File YAML (bắt buộc đối với `plan` và `apply`). | | `--yes` | Thực sự áp dụng. Nếu không có tùy chọn này, `apply` sẽ là dry run. | | `--confirm-billing` | Áp dụng cả các section thanh toán (`payments`, `currency`, `plans`). Nếu không có tùy chọn này, chúng sẽ bị bỏ qua. | | `--section ` | Chỉ áp dụng section này. Lặp lại tùy chọn nếu muốn áp dụng nhiều section. | | `-o ` | Khi dùng `export`: ghi nội dung YAML vào file. | Mã thoát (exit code) là 0 khi mọi thứ đã được áp dụng hoặc không có gì thay đổi, 1 khi có lỗi trả về, 2 khi sai cú pháp sử dụng hoặc lỗi key. ### Bí mật {#secrets} File chứa các tham chiếu thay vì secret, ví dụ `password: secret://smtp_password`. Khi áp dụng, giá trị sẽ được lấy từ biến môi trường có tên `NEXCMP_SECRET_` kết hợp với tên tham chiếu viết hoa: ```bash sudo -i read -rs NEXCMP_SECRET_SMTP_PASSWORD && export NEXCMP_SECRET_SMTP_PASSWORD read -rs NEXCMP_SECRET_STRIPE_SECRET_KEY && export NEXCMP_SECRET_STRIPE_SECRET_KEY nexcmp config apply -f nexcmp.yaml --yes --confirm-billing ``` Nếu một tham chiếu không có giá trị, secret đã lưu trong panel sẽ được **giữ nguyên**. Secret chưa từng được lưu và không được cung cấp sẽ để trống. | Tên tham chiếu | Nơi áp dụng | |---|---| | `smtp_password` | `email.smtp.password` | | `telegram_bot_token` | `telegram.bot_token` | | `stripe_secret_key`, `stripe_webhook_secret` | `payments.stripe` | | `paypal_client_secret` | `payments.paypal.client_secret` | | `binance_api_key`, `binance_api_secret` | `payments.crypto` | | `sepay_api_token`, `sepay_webhook_secret` | `payments.bank` | | `ai_provider_key` | `ai_provider.api_key` | ## File mẫu {#example-file} ```yaml # NexCMP configuration. Preview: nexcmp config plan -f nexcmp.yaml version: 1 branding: name: Example Cloud primary: "#1677ff" currency: usd seller_name: Example Cloud LLC settings: brand_name: Example Cloud support_email: support@example.com default_lang: en invoice_prefix: EX company_name: Example Cloud LLC company_address: "1 Example Street, New York, NY" min_topup_cents: 500 email: smtp: host: smtp.example.com port: 587 security: starttls username: mailer@example.com password: secret://smtp_password from_email: no-reply@example.com from_name: Example Cloud reply_to: support@example.com telegram: enabled: true chat_id: "123456789" bot_token: secret://telegram_bot_token modules: s3: true k8s: false currency: site_currency: usd manual_rate_vnd: 0 # 0 = automatic payments: stripe: mode: test publishable_key: pk_test_XXXX secret_key: secret://stripe_secret_key webhook_secret: secret://stripe_webhook_secret bank: bank_code: BANK account_number: "0000000000" account_name: EXAMPLE CLOUD LLC prefix: EX api_token: secret://sepay_api_token channels: pay_card_enabled: true quotas: quota_enabled: true quota_max_vms_24h: 5 quota_max_vms_30d: 30 zones: - slug: new-york name: New York country: US city: New York enabled: true is_default: true plans: - slug: vps-1c-1g name: 1 vCPU, 1 GB RAM, 25 GB cpu: 1 ram_mb: 1024 disk_gb: 25 hourly_usd: 0.0112 cs_offering_id: OFFERING_ID enabled: true visible: true ai_provider: enabled: true name: Example AI base_url: https://api.example.com/v1 model: example-model fallback_models: [example-model-mini] reasoning_effort: low api_key: secret://ai_provider_key legal: terms: en: | # Terms of service Your terms in simple markdown (no HTML). privacy: en: | # Privacy policy Your policy in simple markdown (no HTML). ``` Một file có thể chứa tập hợp con bất kỳ của các section. Section mà bạn bỏ qua sẽ không bị tác động. File lớn hơn 1 MB, thiếu `version: 1`, phiên bản khác hoặc chứa section không xác định sẽ bị từ chối trước khi có bất kỳ thao tác nào được thực thi. ## Các mục {#sections} | Mục | Nội dung điều khiển | Ghi chú | |---|---|---| | `branding` | Tên thương hiệu (tối đa 60 ký tự), màu chủ đạo, đơn vị tiền tệ hiển thị (`usd` hoặc `vnd`), tên người bán. | Logo không nằm trong file; hãy dùng [trang thương hiệu](https://nexcmp.com/vi/docs/customers/branding/). | | `settings` | Danh sách cố định các cài đặt chung: `brand_name`, `support_email`, `support_telegram_url`, `default_lang`, `require_email_verified`, `min_topup_cents`, `max_topup_cents`, `invoice_prefix`, `company_name`, `company_address`, `company_tax_id`, `auto_destroy_days`, `low_balance_cents`. | Các key khác sẽ bị bỏ qua. | | `email.smtp` | SMTP host, port, bảo mật (`starttls`, `tls`, `none`), user, password, tên và địa chỉ người gửi, reply-to. | [SMTP và mẫu e-mail](https://nexcmp.com/vi/docs/administration/smtp-and-emails/). Việc thay đổi host, port hoặc bảo mật yêu cầu nhập lại password. | | `telegram` | Bật hoặc tắt kênh cảnh báo, chat id, bot token. | [Thông báo Telegram](https://nexcmp.com/vi/docs/administration/telegram-notifications/). | | `modules` | Bật hoặc tắt các module tùy chọn (`key: true/false`). | Chỉ các key mà panel cho phép bật/tắt. Xem [Modules](https://nexcmp.com/vi/docs/infrastructure/modules/). | | `currency` | Đơn vị tiền tệ hiển thị và tỷ giá USD sang VND thủ công (`0` tự động, nếu không sẽ từ 15000 đến 50000). | Section billing. Xem [Tiền tệ và tỷ giá hối đoái](https://nexcmp.com/vi/docs/catalog/currency-and-exchange-rates/). | | `payments` | Thông tin xác thực `stripe`, `paypal`, `crypto`, `bank` và các công tắc `channels` (`pay_card_enabled`, `pay_wallets_enabled`, `pay_alipay_enabled`, `pay_paypal_enabled`, `pay_usdt_enabled`, `pay_sepay_enabled`). | Section billing. Xem [Kênh thanh toán](https://nexcmp.com/vi/docs/billing/payment-channels/). | | `quotas` | Giới hạn `quota_*`. | Xem [Quotas](https://nexcmp.com/vi/docs/billing/quotas/). | | `zones` | Các zone theo `slug` (bắt buộc: `slug`, `name`, `country`; tùy chọn `city`, `enabled`, `is_default`). | Các zone mới sẽ được tạo. Zone đã tồn tại sẽ **không bị thay đổi** bởi file. Xem [Zones](https://nexcmp.com/vi/docs/infrastructure/zones/). | | `plans` | Các plan theo `slug` (bắt buộc: `slug`, `name`, `cpu`, `ram_mb`, `disk_gb`, `hourly_usd`; tùy chọn `cs_offering_id`, `backend_id`, `zone_id`, `enabled`, `visible`, `sort`, `description`). | Section billing. Các plan mới sẽ được tạo, plan hiện có được cập nhật theo slug. Giá tính theo USD mỗi giờ. Xem [Plans](https://nexcmp.com/vi/docs/catalog/plans/). | | `ai_provider` | Nhà cung cấp AI của panel được dùng cho AI Chat và AI Agent của khách hàng. | [AI provider](https://nexcmp.com/vi/docs/ai/ai-providers/). | | `legal` | Nội dung điều khoản và quyền riêng tư theo từng ngôn ngữ (`en`, `vi`). | [Trang pháp lý](https://nexcmp.com/vi/docs/customers/legal/). | Thứ tự áp dụng tuân theo danh sách trên: các mục hạ tầng trước, plan sau. ## Các quy tắc cần nhớ {#rules-to-remember} - **Idempotent.** Áp dụng cùng một file hai lần sẽ không làm thay đổi gì ở lần thứ hai. `plan` hiển thị "No changes". - **Không xóa dữ liệu.** File không bao giờ xóa zone, plan hay cài đặt. Xóa một mục khỏi file vẫn sẽ giữ nguyên trạng thái trên panel. - **Các quy tắc an toàn thông thường vẫn được áp dụng.** Từ dòng lệnh, mỗi thay đổi đều trải qua các bước kiểm tra tương tự như thay đổi qua API: scope và quy tắc IP. Thay đổi cần xác nhận (ví dụ: công tắc ảnh hưởng toàn hệ thống) sẽ được báo cáo dưới `pending` kèm bản xem trước thay vì được áp dụng ngay, trừ khi bạn truyền `--confirm-billing` để xác nhận tất cả. - **Client AI không thể mở khóa billing.** Khi `config_apply` được gọi bởi client MCP, `confirm_billing` sẽ bị bỏ qua; các thay đổi liên quan đến tiền bạc sẽ chờ bạn xác nhận. - **Kiểm tra trước khi áp dụng.** JSON Schema mô tả chi tiết từng trường. Hãy trỏ trình soạn thảo vào schema này hoặc cung cấp cho AI để tạo file YAML hợp lệ: `https://cloud.example.com/v1/admin/agent/config/schema.json` (cho phép đọc công khai). ### Các section billing {#billing-sections} `payments`, `currency` và `plans` làm thay đổi giá hoặc luồng tiền. `nexcmp config apply --yes` **bỏ qua** các mục này trừ khi bạn thêm `--confirm-billing`; khi đó chúng được liệt kê dưới `skipped` ("billing section - pass confirm_billing"). Cờ này đóng vai trò xác nhận: khi có nó, mọi thay đổi billing trong file (và bất kỳ thay đổi nào khác yêu cầu xác nhận) sẽ được áp dụng mà không cần hỏi lại. Hãy chạy `plan` trước và đọc kỹ từng dòng được đánh dấu `$`. Khi tệp tương tự được áp dụng bởi AI (công cụ `config_apply` trong MCP client hoặc AI Chat), cờ này sẽ bị bỏ qua và các thay đổi liên quan đến tiền sẽ chờ bạn phê duyệt. ## Sử dụng trang Import/Export {#use-the-import-export-page} 1. Mở **System › Settings › Import/Export**. 2. Dưới mục **Export**, nhấp vào **Get current configuration**, sau đó chọn **Download .yaml** để lưu `nexcmp.yaml`. Các secret sẽ hiển thị dưới dạng placeholder. 3. Dưới mục **Import**, hãy chọn một tệp, kéo tệp vào khung hoặc dán nội dung YAML. 4. Tùy chọn: mở **Secrets that come with it (not in the file)** rồi thêm tên và giá trị cho từng tham chiếu, ví dụ `smtp_password`. 5. Nhấp vào **Preview changes**. Bảng sẽ nhóm các thay đổi theo từng phần; các phần liên quan đến tiền sẽ có nhãn "Money-related". Bỏ chọn những phần bạn không muốn áp dụng. 6. Nếu có các phần liên quan đến tiền được liệt kê, hãy đánh dấu chọn **Also apply money-related changes (prices, payment gateways, balances)**. Nếu không chọn, các phần này sẽ bị bỏ qua. 7. Nhấp vào **Apply selected**. Kết quả sẽ hiển thị những gì đã được áp dụng, bỏ qua hoặc thất bại. Thay đổi nào được trả về ở trạng thái chờ xác nhận sẽ xuất hiện dưới dạng thẻ xác nhận; hãy nhấn **Confirm** trên thẻ đó. Nút **JSON Schema** ở góc trên bên phải sẽ mở schema. ![Trang Import/Export với thẻ Export và thẻ Import chứa YAML đã xuất](https://nexcmp.com/vi/docs/images/configure-with-ai/config-as-code-01-import-export.webp) ![Bảng xem trước các thay đổi được nhóm theo phần kèm nhãn billing và nút Apply selected](https://nexcmp.com/vi/docs/images/configure-with-ai/config-as-code-02-preview.webp) ## Chạy bất kỳ công cụ nào từ dòng lệnh {#run-any-tool-from-the-command-line} `nexcmp admin` chạy cùng các công cụ như trợ lý AI ([danh sách công cụ](https://nexcmp.com/vi/docs/configure-with-ai/mcp-admin/#tools)) và xuất ra JSON: ```bash sudo nexcmp admin tools # name, scope and title of every tool sudo nexcmp admin system_health sudo nexcmp admin customers_search q=customer@example.com sudo nexcmp admin settings_update --json '{"values":{"support_email":"support@example.com"}}' ``` Các đối số là các cặp `key=value` (giá trị được đọc dưới dạng JSON khi parse được, nếu không sẽ là văn bản) hoặc một đối tượng `--json '{...}'`. Nếu thao tác cần xác nhận, lệnh sẽ in bản xem trước và dừng lại với mã thoát 3 kèm thông báo "Nothing changed". Hãy đọc bản xem trước, sau đó chạy lại lệnh với `--yes` để áp dụng. Khi chạy dưới quyền root, lệnh sẽ nhận một khóa 15 phút với đầy đủ phạm vi quyền, vì vậy bước xác nhận là chốt an toàn của bạn; với `NEXCMP_KEY`, phạm vi quyền riêng của khóa sẽ được áp dụng. ## Kiểm tra {#verify} 1. `sudo nexcmp config plan -f nexcmp.yaml` ngay sau `apply --yes` sẽ in ra "No changes". 2. Trong trang admin, các trang bạn đã thay đổi sẽ hiển thị giá trị mới, và **Logs › Admin actions** sẽ liệt kê các thay đổi. 3. Áp dụng lại cùng một tệp sẽ không thay đổi bất kỳ điều gì. ## Hạn mức & lưu ý {#limits-notes} - Tệp này áp dụng cho các cài đặt ở trên, không bao gồm khách hàng, máy chủ, hóa đơn hay tài nguyên hạ tầng (kết nối CloudStack và Proxmox). Hãy kết nối các mục đó bằng [AI Chat](https://nexcmp.com/vi/docs/configure-with-ai/ai-chat-in-admin/) hoặc qua các trang admin. - Zone và plan được khớp theo `slug`. Không đổi tên slug trong tệp: nó sẽ được tạo thành một mục mới. - Không thể thay đổi quy mô của plan mà khách hàng đang sử dụng; thay vào đó hãy tạo một plan mới. - Hãy bảo mật các tệp đã xuất dù chúng không chứa secret: chúng liệt kê giá cả, địa chỉ và tên tài khoản của bạn. ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | `missing version: 1` | Tệp không bắt đầu bằng `version: 1` | Thêm vào. | | `unsupported version 2` | Tệp có số phiên bản khác | Panel này chỉ đọc phiên bản 1. | | `unknown section 'x' (known: ...)` | Khóa top-level bị viết sai chính tả hoặc không được hỗ trợ | Sử dụng các phần ở trên. | | `YAML error: ...` | YAML không hợp lệ (thụt lề, ký tự tab) | Sửa dòng được chỉ ra trong thông báo. | | `config is larger than 1 MB` | Tệp quá lớn | Chia nhỏ tệp và sử dụng `--section`. | | `no API key: set NEXCMP_KEY=ak_... or run as root on the server` | Lệnh không tìm thấy khóa | Chạy bằng `sudo`, hoặc export `NEXCMP_KEY` và giữ biến môi trường đó qua sudo. | | `panel not reachable` | Dịch vụ panel không chạy trên cổng mặc định | Kiểm tra `sudo nexcmp status`. | | Các dòng billing dưới `skipped` | Các phần billing cần `--confirm-billing` | Thêm cờ này và xem lại các dòng `$` trước. | | Các mục dưới `pending` | Thay đổi cần được xác nhận | Mở **API & AI agents**, hoặc kết quả Import/Export, rồi nhấn **Confirm** trên thẻ. | | Secret không được cập nhật | Không có giá trị `NEXCMP_SECRET_` nào được thiết lập, nên secret đã lưu được giữ nguyên | Export biến này và áp dụng lại. | | Mục dưới `errors` gặp lỗi HTTP 403 `insufficient_scope` | Key thiếu scope của phần đó | Sử dụng key có scope này, hoặc chạy dưới quyền root. | | Mục dưới `errors` gặp lỗi HTTP 403 `demo_read_only` | Panel demo | Áp dụng trên bản cài đặt thực tế. | --- # Prompt mẫu {#example-prompts} > **Vị trí trong admin:** AI Chat (`/agent`) hoặc nút nổi **Ask AI** trên bất kỳ trang admin nào. Các prompt tương tự cũng hoạt động trong mọi AI client được kết nối qua [MCP](https://nexcmp.com/vi/docs/configure-with-ai/mcp-admin/). ## Chức năng {#what-it-does} Các prompt này hướng dẫn cách yêu cầu trợ lý. Mỗi prompt liệt kê những việc trợ lý thực hiện ngầm, các scope cần thiết (cho client bên ngoài hoặc key) và nơi bạn được yêu cầu phê duyệt. Hãy thay thế các giá trị ví dụ bằng giá trị của bạn. ::: tip Không bao giờ nhập secret vào nội dung chat Đối với mật khẩu, API key và token, hãy sử dụng trường **Secret** bên cạnh ô nhập AI Chat ([chi tiết](https://nexcmp.com/vi/docs/configure-with-ai/ai-chat-in-admin/#secrets)). AI chỉ nhìn thấy placeholder đại diện cho secret chứ không thấy giá trị thực. Với AI client bên ngoài, secret sẽ đi qua client đó, vì vậy bạn nên ưu tiên nhập trong admin. ::: ## Kiểm tra tiến trình hiện tại {#check-where-you-are} ```text Check my setup progress and tell me the next three things to do, in order. ``` Trợ lý gọi `setup_checklist` và `system_health` (scope `admin:read`) và trả lời từ trạng thái thực tế. Xem [Checklist tiến trình cài đặt](https://nexcmp.com/vi/docs/configure-with-ai/setup-checklist/). ## Thiết lập ban đầu {#first-setup} ```text Help me finish the initial setup. Go through the checklist, explain each open step in one sentence, ask me for what you need, and show me every change before it is applied. ``` Prompt này tương đương với prompt MCP `initial-setup`. Nó cần `admin:read` cùng với scope của các bước mà bạn chấp nhận. Mỗi thay đổi sẽ xuất hiện một thẻ xác nhận trong AI Chat. ## Thêm cluster Proxmox VE {#add-a-proxmox-ve-cluster} ```text I want to sell servers from my Proxmox VE cluster at https://pve.example.com:8006. Add it, test the connection, create a zone called "New York" in the US, attach the cluster to it, and then propose starter plans. ``` Điều gì sẽ diễn ra: 1. Trợ lý sẽ yêu cầu API token id (`user@realm!tokenid`) và secret của nó. Hãy nhập secret vào trường **Secret**. Trước tiên, hãy tạo một token bị giới hạn quyền: [Proxmox VE](https://nexcmp.com/vi/docs/infrastructure/proxmox/). 2. Nó gọi `proxmox_add`, `proxmox_test`, `zone_create` và `proxmox_attach_zone`. 3. Nó đề xuất các plan bằng `plans_from_offerings` và chờ bạn phê duyệt (xem ví dụ tiếp theo). Scope: `infra:write`, `secrets:write`, `catalog:write`, `admin:read`. ## Tạo bảng plan với biên lợi nhuận 40% {#create-a-plan-table-with-a-40-margin} ```text Suggest a starter plan table from my CloudStack offerings. My costs are $4 per vCPU per month, $2 per GB of RAM per month and $0.08 per GB of disk per month. Use a 40% margin, show me the table with cost, price per month and price per hour, and create the plans only after I approve. ``` Trợ lý gọi `plans_from_offerings` với `margin_pct` 40 cùng chi phí của bạn. Biên lợi nhuận là tỷ lệ phần trăm lợi nhuận trên giá bán: ở mức 40%, một plan có chi phí $60 sẽ được bán với giá $100. Lần gọi đầu tiên chỉ trả về bản xem trước. Khi bạn phê duyệt, trợ lý sẽ gọi lại công cụ với `apply=true` để tạo các plan trong một bước và yêu cầu một lần xác nhận vì có liên quan đến giá bán. Đối với Proxmox, trợ lý sử dụng `backend_id` cùng danh sách cấu hình mặc định (1, 2, 2 và 4 vCPU). Scope: `catalog:write`, `admin:read`. Xem [Plans](https://nexcmp.com/vi/docs/catalog/plans/). ![Câu trả lời của AI Chat hiển thị bảng xem trước các plan cùng chi phí, giá theo tháng và giá theo giờ](https://nexcmp.com/vi/docs/images/configure-with-ai/example-prompts-01-plan-preview.webp) ## Cấu hình email và gửi thư thử nghiệm {#configure-email-and-send-a-test-message} ```text Configure outgoing email with smtp.example.com, port 587, STARTTLS, user "mailer@example.com", sender name "Example Cloud", sender address "no-reply@example.com". Use my Secret field for the password "smtp_password". Then send a test email to admin@example.com. ``` Trợ lý gọi `smtp_get`, `smtp_configure` và `smtp_test`, sau đó thông báo cho bạn biết thư đã được chấp nhận hay chưa. Scope: `settings:write`, `secrets:write`. Xem [SMTP và mẫu email](https://nexcmp.com/vi/docs/administration/smtp-and-emails/). ## Thiết lập Stripe {#set-up-stripe} ```text Set up Stripe in test mode. My publishable key is pk_test_XXXX. Use the secret key and the webhook secret from my Secret field (names stripe_secret_key and stripe_webhook_secret). Then test the credentials and tell me which webhook URL I must add in Stripe. ``` `payment_configure` luôn là thao tác gồm hai bước: bạn xem bản xem trước với các giá trị bí mật được ẩn và phê duyệt. Sau đó `payment_test` kiểm tra thông tin xác thực với Stripe. Scopes: `billing:write`, `secrets:write`. Chỉ chuyển sang chế độ live sau khi thanh toán thử nghiệm. Xem [Stripe](https://nexcmp.com/vi/docs/billing/stripe/). ## Bật cảnh báo Telegram {#turn-on-telegram-alerts} ```text Add my Telegram chat 123456789 for admin alerts. The bot token is in my Secret field as telegram_bot_token. Send a test message. ``` Trợ lý gọi `telegram_configure` và `telegram_test`. Scopes: `settings:write`, `secrets:write`. Xem [Thông báo Telegram](https://nexcmp.com/vi/docs/administration/telegram-notifications/). ## Tìm khách hàng và nạp credit {#find-a-customer-and-add-credit} ```text Find the customer with e-mail customer@example.com, show me their balance and servers, and add $10.00 of credit because of the outage on Monday. ``` Trợ lý gọi `customers_search` và `customer_get` (chỉ đọc), sau đó gọi `customer_adjust_balance` với `delta_cents` 1000 và lý do. Thao tác này **luôn** cần bạn phê duyệt: thẻ xác nhận hiển thị "changes a customer balance" cùng số tiền và lý do sẽ được ghi vào audit log. Scopes: `admin:read`, `billing:write`. ## Xuất cấu hình của tôi {#export-my-configuration} ```text Export my whole configuration as YAML. Do not include secrets. Then tell me which settings differ from a typical new installation. ``` Trợ lý gọi `config_export`. Các secret được thay bằng tham chiếu `secret://`. Lưu kết quả dưới dạng `nexcmp.yaml` và đưa vào hệ thống kiểm soát phiên bản. Xem [Cấu hình dưới dạng mã](https://nexcmp.com/vi/docs/configure-with-ai/config-as-code/). Scope: `admin:read`. ## Viết prompt hiệu quả {#write-good-prompts} - Cung cấp mục tiêu và dữ kiện cụ thể: tên, giá, địa chỉ email. Không dán secret. - Luôn yêu cầu xem trước đối với bất kỳ thao tác nào tốn chi phí hoặc xóa dữ liệu. - Yêu cầu trợ lý "đọc giá trị hiện tại trước khi thay đổi". Hướng dẫn tích hợp sẵn đã quy định điều này. - Nếu câu trả lời có vẻ không đúng, hãy hỏi "bạn đã gọi tool nào và với đối số nào?". Các thẻ tool trong AI Chat hiển thị cả hai. ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | Trợ lý báo không có tool cho tác vụ nào đó | Scope cho tool đó chưa được cấp, hoặc tác vụ không mở cho AI | Kiểm tra [Admin API keys](https://nexcmp.com/vi/docs/configure-with-ai/admin-api-keys/#what-a-key-can-never-do), hoặc thực hiện trong admin. | | Trợ lý yêu cầu bạn dán mật khẩu | Mô hình đã bỏ qua hướng dẫn | Từ chối; sử dụng trường Secret hoặc nhập giá trị trong admin. | | Không có gì thay đổi sau lệnh "do it" | Các thay đổi đang chờ bạn xác nhận | Cuộn đến thẻ xác nhận và nhấn **Confirm**. | | Các gói dịch vụ được tạo với mức giá ngoài dự kiến | Chi phí hoặc biên lợi nhuận trong prompt bị sai | Chỉnh sửa các gói trên trang Plans hoặc yêu cầu trợ lý định giá lại; thay đổi giá sẽ yêu cầu xác nhận. | --- # Danh sách kiểm tra tiến độ thiết lập {#setup-progress-checklist} > **Vị trí trong admin:** Overview › Dashboard (`/`), thẻ **Setup progress** ở trên cùng. Danh sách trống tại Plans, Customers, Zones, Payments và Infrastructure cũng hiển thị trợ giúp tương tự. ## Chức năng {#what-it-does} Bản cài đặt mới cần mười mục trước khi khách hàng đầu tiên có thể đặt hàng và thanh toán. Thẻ **Setup progress** sẽ kiểm tra dựa trên cấu hình thực tế, hiển thị số mục đã xong, nêu rõ **bước tiếp theo** và liên kết đến trang thực hiện. Nếu bạn đã kết nối nguồn AI, **Do it for me** sẽ mở [trợ lý AI](https://nexcmp.com/vi/docs/configure-with-ai/ai-chat-in-admin/) với câu hỏi có sẵn cho bước đó. Trợ lý (và bất kỳ AI client nào qua [MCP](https://nexcmp.com/vi/docs/configure-with-ai/mcp-admin/)) đều có thể đọc danh sách này bằng tool `setup_checklist`. ## Mười bước {#the-ten-steps} | # | Bước | Được tính là hoàn thành khi | Nơi thực hiện | |---|---|---|---| | 1 | Giấy phép hoạt động | Giấy phép đã được kích hoạt cho tên miền của bạn | System › Admin › License & updates (`/license`). Xem [Giấy phép và mua hàng](https://nexcmp.com/vi/docs/getting-started/license-and-purchase/). | | 2 | Kết nối nguồn hạ tầng | CloudStack đã được kết nối, hoặc đã thêm ít nhất một cụm Proxmox VE | Infrastructure › Cloud provider › Providers (`/infra/providers`). Xem [CloudStack](https://nexcmp.com/vi/docs/infrastructure/cloudstack/) và [Proxmox VE](https://nexcmp.com/vi/docs/infrastructure/proxmox/). | | 3 | Tạo zone | Có ít nhất một zone | Infrastructure › Datacenter › Zone (`/infra/zones`). Xem [Zones](https://nexcmp.com/vi/docs/infrastructure/zones/). | | 4 | OS template | Có ít nhất một template được bật | Services › Virtual Machines › Plans & pricing, tab Templates (`/vm/catalog?tab=templates`). Tham khảo [OS templates](https://nexcmp.com/vi/docs/infrastructure/templates/). | | 5 | Tạo plan | Có ít nhất một plan được bật | Services › Virtual Machines › Plans & pricing (`/vm/catalog`). Tham khảo [Plans and pricing](https://nexcmp.com/vi/docs/catalog/plans/). | | 6 | Thiết lập thanh toán | Đã cấu hình Stripe, PayPal, crypto hoặc chuyển khoản ngân hàng | Finance › Payment channels (`/payments`). Tham khảo [Payment channels](https://nexcmp.com/vi/docs/billing/payment-channels/). | | 7 | Email (SMTP) | Đã cấu hình email gửi đi | System › Settings › Email (`/settings/email`). Xem [SMTP và mẫu email](https://nexcmp.com/vi/docs/administration/smtp-and-emails/). | | 8 | Tùy biến thương hiệu | Đã tải lên logo, hoặc đã đổi tên thương hiệu khỏi giá trị mặc định | System › Settings › Brand (`/settings/branding`). Xem [Branding](https://nexcmp.com/vi/docs/customers/branding/). | | 9 | Điều khoản & quyền riêng tư | Đã điền ít nhất một nội dung pháp lý | System › Settings › Legal (`/settings/legal`). Xem [Các trang pháp lý](https://nexcmp.com/vi/docs/customers/legal/). | | 10 | Đặt đơn hàng thử nghiệm | Có ít nhất một đơn hàng | Đặt một đơn hàng với tư cách khách hàng trên cổng thông tin khách hàng để kiểm tra toàn bộ quy trình vận hành thông suốt; thẻ này liên kết đến trang Billing (`/billing`). | Thẻ hiển thị `done/total` (ví dụ 6/10), thanh tiến trình, bước tiếp theo cùng nút **Open** và nút **Do it for me** khi có nguồn AI được kết nối. Nhấp vào một bước để chuyển đến trang tương ứng. Cạnh mỗi bước có liên kết nhỏ mở trang tài liệu phù hợp; một số bước cũng hiển thị thông tin chi tiết như "2 zone(s)". ![Thẻ tiến trình thiết lập trên Overview với ba trong mười bước đã hoàn thành cùng các nút Open và Do it for me](https://nexcmp.com/vi/docs/images/configure-with-ai/setup-checklist-01-card.webp) ## Cách sử dụng {#use-it} 1. Mở Overview. Thẻ nằm ở phía trên cùng. Dùng mũi tên để thu gọn thẻ; bảng điều khiển sẽ ghi nhớ lựa chọn của bạn trong trình duyệt. 2. Nhấp vào **Open** để chuyển đến trang của bước tiếp theo, hoặc nhấp vào **Do it for me**. 3. Với **Do it for me**, trợ lý sẽ mở ra cùng yêu cầu như "Suggest a starter plan table from my offerings with a 40% margin, show me the preview before creating it." Hãy trả lời các câu hỏi của trợ lý, sau đó xem lại và **Confirm** từng thẻ. Xem [AI Chat trong trang quản trị](https://nexcmp.com/vi/docs/configure-with-ai/ai-chat-in-admin/). 4. Khi hoàn tất cả mười bước, thẻ sẽ biến mất. ### Danh sách trống {#empty-lists} Khi Plans, Customers, Zones, Payments hoặc Infrastructure trống, trang sẽ hiển thị khối **Next step** kèm phần giải thích, nút thao tác, **Do it for me** và liên kết đến tài liệu, giúp bạn không bao giờ gặp phải một bảng trống. ![Trang Plans trống kèm phần giải thích bước tiếp theo và nút Do it for me](https://nexcmp.com/vi/docs/images/configure-with-ai/setup-checklist-02-empty.webp) ## Yêu cầu bằng cách diễn đạt của riêng bạn {#ask-for-it-in-your-own-words} Bạn không nhất thiết phải dùng thẻ này. Trong AI Chat hoặc bất kỳ AI client nào đã kết nối, bạn có thể hỏi: ```text Check my setup progress and take me through the open steps, one at a time. ``` Đây cũng là MCP prompt `initial-setup`. Trợ lý sẽ gọi `setup_checklist`, giải thích lý do từng bước chưa hoàn tất là quan trọng, hỏi thông tin cần thiết và sử dụng công cụ phù hợp. Các scope cần thiết: `admin:read` để đọc danh sách, kèm theo scope của bước bạn muốn thực hiện. Xem [Prompt mẫu](https://nexcmp.com/vi/docs/configure-with-ai/example-prompts/). ## Kiểm tra {#verify} 1. Sau khi bạn hoàn tất một bước, số đếm trên thẻ sẽ tăng lên vào lần tải Overview tiếp theo. 2. Trong assistant, `setup_checklist` sẽ trả về cùng các con số này, kèm `done: true` ở bước đã hoàn thành. ## Hạn mức & lưu ý {#limits-notes} - Các bước kiểm tra chỉ xem xét những gì đã được lưu, chứ không kiểm tra xem nó có hoạt động hay không. Một cổng thanh toán đã cấu hình vẫn tính là hoàn tất ngay cả khi kiểm tra thất bại. Hãy dùng các nút **Test** trên từng trang và công cụ `system_health` khi gặp sự cố. - Thẻ này chỉ dành cho quản trị viên. - **Do it for me** cần một nguồn AI được kết nối tại System › Settings › AI accounts; nếu không có thì chỉ hiển thị **Open**. - Mười bước này giống nhau trên mọi bản cài đặt; một bước bạn không có kế hoạch sử dụng (chẳng hạn thanh toán trên private cloud) vẫn sẽ tính là chưa hoàn tất. ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | Thẻ bị thiếu | Tất cả mười bước đã hoàn tất, hoặc không thể tải thẻ | Tải lại Overview. Hỏi `setup_checklist` trong AI Chat để kiểm tra trạng thái. | | Một bước vẫn chưa hoàn tất sau khi bạn đã thực hiện | Lưu chưa hoàn tất, hoặc điều kiện chưa được thỏa mãn (ví dụ template đã tồn tại nhưng đang bị tắt) | Mở trang của bước đó và kiểm tra bảng bên trên. | | Branding vẫn chưa hoàn tất sau khi đổi logo | Branding được tính khi đã có logo hoặc tên thương hiệu khác với giá trị mặc định "NexCMP" | Tải logo lên hoặc đặt tên thương hiệu của bạn. | | **Do it for me** không hoạt động | Chưa kết nối nguồn AI, hoặc đang dùng bảng điều khiển demo | Kết nối một nguồn trong AI accounts. | --- # SMTP và template email {#smtp-and-e-mail-templates} > **Vị trí trong admin:** System › Settings › Email (`/settings/email`) — các tab **SMTP** và **Email templates**. Nhật ký gửi thư: Overview › Support › Sent emails (`/support/emails`). ## Chức năng {#what-it-does} NexCMP gửi email để xác thực đăng ký, đặt lại mật khẩu, thông báo "VM ready" (kèm mật khẩu khởi tạo), hóa đơn, số dư thấp, gia hạn, nạp tiền, phản hồi hỗ trợ và nhiều tác vụ khác. Tất cả đều đi qua **một tài khoản SMTP do bạn cung cấp**. Thư và template hỗ trợ 16 ngôn ngữ; ngôn ngữ của khách hàng sẽ được ưu tiên sử dụng. ## Yêu cầu {#requirements} | Hạng mục | Yêu cầu | |---|---| | Máy chủ SMTP | Host, cổng và thông tin xác thực của bất kỳ nhà cung cấp nào (máy chủ riêng của bạn, Brevo, Amazon SES, Mailgun, Google Workspace …) | | Mạng | TCP chiều đi từ máy chủ NexCMP đến host và cổng SMTP (587 STARTTLS, 465 TLS hoặc 25) | | Tên miền người gửi | Tên miền thuộc quyền kiểm soát của bạn, đã phát hành bản ghi **SPF và DKIM** cho nhà cung cấp cùng một bản ghi DMARC | | Quyền gửi thư | Tài khoản SMTP phải được phép gửi dưới địa chỉ **From** | ::: warning Khả năng gửi thư thành công Các email như thông báo "VM ready" chứa mật khẩu. Nếu SPF/DKIM/DMARC của tên miền người gửi không khớp với nhà cung cấp SMTP, chúng sẽ bị đưa vào thư rác. Trang này sẽ nhắc nhở bạn về điều đó. ::: ## Chuẩn bị nhà cung cấp email {#prepare-the-e-mail-provider} 1. Trong bảng điều khiển của nhà cung cấp, hãy thêm và xác minh tên miền gửi thư của bạn (ví dụ: `example.com`). 2. Phát hành các bản ghi DNS cho SPF, DKIM và DMARC do nhà cung cấp hiển thị. 3. Tạo người dùng SMTP (hoặc khóa API-SMTP) và ghi lại host, cổng, tên đăng nhập cùng mật khẩu. ## Kết nối trong NexCMP {#connect-in-nexcmp} 1. Mở **System › Settings › Email**, tab **SMTP**. 2. Điền vào biểu mẫu: | Trường | Ví dụ | Ghi chú | |---|---|---| | Host | `smtp.example.net` | Máy chủ SMTP | | Cổng | `587` | | | Security | STARTTLS (587) | Chọn chế độ mà nhà cung cấp của bạn yêu cầu | | Username | `smtp-user` | | | Mật khẩu | (ẩn) | Chỉ ghi: trang chỉ hiển thị xem đã được thiết lập hay chưa | | From email | `no-reply@example.com` | Phải được ủy quyền tại nhà cung cấp | | From name | `Example Cloud` | Mặc định theo tên thương hiệu của bạn | | Reply-To (tùy chọn) | `support@example.com` | Nơi nhận phản hồi của khách hàng | ![Tab SMTP của Settings, Email với host, port, security, username, các trường người gửi và nút Send test](https://nexcmp.com/vi/docs/images/administration/smtp-and-emails-01-smtp.webp) 3. Nhấp vào **Save**, sau đó nhấn **Send test** và nhập địa chỉ của chính bạn. Các cài đặt được lưu trong một tệp bị hạn chế quyền truy cập (`smtp.json`, mode 0600) và chỉ có worker chạy ngầm `nexcmp-vmd` gửi thư; web service chỉ xếp thư vào hàng đợi. ## Kiểm tra {#verify} - Thư thử nghiệm được gửi đến hộp thư đến (hãy kiểm tra cả mục thư rác). Trong mã nguồn thư, hãy xác nhận `dkim=pass` và `spf=pass`. - Mở **Support › Sent emails**: mỗi thư có một trạng thái (queued, sent, failed) và kết quả gửi. Các thư gửi thất bại được thử lại tối đa 3 lần. - Đăng ký một khách hàng thử nghiệm trên portal và xác nhận email xác thực đã được gửi đến. ## Chỉnh sửa mẫu email {#edit-e-mail-templates} Tab **Email templates** liệt kê từng mẫu theo khóa, cùng các ngôn ngữ hiện có (ví dụ `verify_email`, `reset_password`, `vm_ready`, `invoice_paid`, `low_balance`, `topup_received`, `ticket_reply`, `scale_up` …). 1. Nhấp vào một mẫu và chọn một ngôn ngữ. 2. Chỉnh sửa tiêu đề và nội dung. Các placeholder sẽ được điền vào khi thư được xếp vào hàng đợi. 3. Lưu lại. Thay đổi sẽ áp dụng **ngay lập tức** cho các thư được xếp vào hàng đợi sau đó. ![Tab Email templates liệt kê các khóa mẫu và ngôn ngữ của chúng](https://nexcmp.com/vi/docs/images/administration/smtp-and-emails-02-templates.webp) ## Giới hạn và lưu ý {#limits-and-notes} - Một tài khoản SMTP cho mỗi bản cài đặt. Khách hàng của đại lý nhận email qua cùng một tài khoản trừ khi đại lý được cấu hình khác. - Áp dụng giới hạn gửi của nhà cung cấp; NexCMP không điều tiết lưu lượng ngoài việc thử gửi lại. - Nếu không có SMTP, panel vẫn hoạt động, nhưng khách hàng không thể hoàn tất xác thực đăng ký và đặt lại mật khẩu. ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | Email thử nghiệm không bao giờ đến | Thông tin đăng nhập sai, cổng bị chặn, người gửi chưa được ủy quyền | Kiểm tra `journalctl -u nexcmp-vmd` để xem lỗi SMTP; thử cổng 587 với STARTTLS; xác minh địa chỉ From tại nhà cung cấp. | | Thư bị đưa vào mục spam | Thiếu hoặc sai lệch cấu hình SPF/DKIM/DMARC | Xuất bản các bản ghi của nhà cung cấp và gửi từ tên miền đó. | | "thất bại" trong Email đã gửi | Nhà cung cấp đã từ chối thư | Mở hàng đó để xem phản hồi của nhà cung cấp. | | Trường mật khẩu hiển thị trống sau khi lưu | Theo thiết kế (chỉ ghi) | Nhãn hiển thị "current: set" sau khi mật khẩu đã được lưu. | --- # Telegram và cảnh báo quản trị {#telegram-and-admin-alerts} > **Vị trí trong admin:** System › Settings › Admin alerts (`/settings/alerts`). Phím tắt hỗ trợ: Customers › Support › Tickets (`/support/tickets`), tab **Settings**. ## Chức năng {#what-it-does} NexCMP thông báo cho **bạn** — đơn vị vận hành — khi có vấn đề cần chú ý, cũng như khi khách hàng đăng ký hoặc nạp tiền thành công. Cảnh báo được gửi tới một hoặc nhiều **kênh**: Telegram, webhook hoặc e-mail. Các sự kiện gửi đến kênh quản trị viên bao gồm: triển khai thất bại, mất VM, mạng ngừng hoạt động, IP trống dưới 30, dịch vụ sắp hết hạn (cảnh báo trước 1 giờ), tranh chấp Stripe, worker dừng hoạt động, RAM cụm vượt ngưỡng, khách hàng mới đăng ký và tiền nạp đã ghi nhận. Sự kiện khách hàng được lưu hàng đợi bền vững và thử lại với độ trễ tăng dần (từ 30 giây đến tối đa 1 giờ) cho đến khi Telegram chấp nhận. ## Yêu cầu {#requirements} | Hạng mục | Yêu cầu | |---|---| | Telegram | Bot được tạo bằng **@BotFather** (token) và **chat ID** của nhóm hoặc người dùng cần nhận tin nhắn | | Mạng | HTTPS chiều đi tới `api.telegram.org` | | Webhook (thay thế) | Một endpoint HTTPS tiếp nhận payload cảnh báo | ## Chuẩn bị Telegram {#prepare-telegram} 1. Trên Telegram, mở **@BotFather**, gửi `/newbot`, chọn một tên; sao chép **bot token** (`123456789:AA...`). 2. Tạo một nhóm, thêm bot vào nhóm và gửi một tin nhắn bất kỳ. 3. Tìm **chat ID**: mở `https://api.telegram.org/bot/getUpdates` trong trình duyệt và xem `chat.id` (ID nhóm bắt đầu bằng `-`). ## Kết nối trong NexCMP {#connect-in-nexcmp} 1. Mở **System › Settings › Admin alerts**. 2. Trong **Add channel**, chọn **Type: Telegram**, đặt **Destination** thành chat ID và **Secret (bot token)** thành token đó. Nhấp vào **Add**. 3. Đảm bảo nút chuyển **Send admin Telegram (VM module)** đang bật; dòng *VM module status (read-only)* hiển thị "on". ![Trang Admin alerts với biểu mẫu Add channel được đặt thành Telegram](https://nexcmp.com/vi/docs/images/administration/telegram-notifications-01-channel.webp) ## Kiểm tra {#verify} Kênh sẽ xuất hiện dưới mục **Configured channels**. Hãy kích hoạt một sự kiện (ví dụ đăng ký khách hàng thử nghiệm) và tin nhắn sẽ được gửi đến nhóm. Nếu chưa cấu hình kênh nào, trang sẽ cảnh báo "Without a channel, attacks will go unnoticed" và trong log, các sự kiện Telegram sẽ chỉ được ghi lại cục bộ. ## Lối tắt hỗ trợ cho khách hàng {#support-shortcuts-for-customers} Widget hỗ trợ khách hàng có thể hiển thị các nút **Telegram** và **Zalo**. Các nút này sẽ ẩn cho đến khi được cấu hình trong cài đặt hỗ trợ: nhập liên kết `https://t.me/...` cho Telegram và liên kết Zalo hoặc mã QR. Chỉ chấp nhận liên kết `https://`. Khung chat hỗ trợ cũng có thể thông báo cho nhóm Telegram của bạn câu hỏi kèm câu trả lời bản nháp — xem [AI Chat](https://nexcmp.com/vi/docs/ai/ai-chat/). ## Giới hạn và lưu ý {#limits-and-notes} - Bot token được lưu cùng với kênh và sẽ không bao giờ hiển thị lại. - Các sự kiện Telegram sử dụng kênh Telegram đang bật đầu tiên có đủ destination và token. ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | Không nhận được tin nhắn | Sai chat ID, bot chưa vào nhóm hoặc chưa từng gửi tin nhắn cho bot | Kiểm tra lại ID bằng `getUpdates`; gửi tin nhắn cho bot hoặc nhóm trước. | | Hoạt động một thời gian rồi ngừng | Token đã bị thu hồi trong BotFather | Tạo token mới và cập nhật lại kênh. | | `Telegram: no channel` trong log | Chưa có kênh Telegram nào được bật | Thêm một kênh như hướng dẫn ở trên. | --- # Nhật ký kiểm toán và hoạt động {#audit-log-and-activity} > **Vị trí trong trang admin:** System › Logs › Activity (`/logs`), Admin actions (`/logs/admin`), Console (`/logs/console`), Login (`/logs/logins`), VM events (`/logs/vm-events`); Overview › Support › Sent emails. NexCMP ghi lại mọi thao tác quan trọng. Sử dụng trang **Activity** làm dòng thời gian duy nhất và dùng các tab khác để thu hẹp phạm vi. ## Các tab {#tabs} | Tab | Nội dung | |---|---| | **Activity** | Dòng thời gian hợp nhất từ mọi nguồn: hành động admin, sự kiện VM, lượt đăng nhập, affiliate và lỗi hệ thống | | **Admin actions** | Những thay đổi do quản trị viên thực hiện (ví dụ `customer.block`, `customer.delete`), kèm IP của quản trị viên | | **Console** | Lượt đăng nhập Admin console và các yêu cầu hệ thống như yêu cầu cập nhật | | **Login** | Lượt đăng nhập của khách hàng và các lần đăng nhập thất bại | | **VM events** | Các bước deploy, tạo, đặt mật khẩu, xóa và các sự kiện vòng đời khác trên từng máy ảo | ## Đọc một dòng nhật ký {#reading-a-row} Các cột: **Time**, **Source**, **Level**, **Actor** (ai thực hiện), **Target**, **Services**, **Action** (mã sự kiện như `customer.delete`) và **Details**. Nhấp **Open** để xem toàn bộ bản ghi. ![Trang Activity với bộ lọc source, site và service phía trên dòng thời gian](https://nexcmp.com/vi/docs/images/administration/audit-log-01-activity.webp) ## Lọc và tìm kiếm {#filter-and-search} 1. Chọn **source**, **site** và **service** từ menu thả xuống. 2. Đặt khoảng thời gian **From date** / **To date**. 3. Nhập mã sự kiện (ví dụ `customer.block` hoặc `destroy`) vào ô tìm kiếm — tính năng tìm kiếm hoạt động sẽ khớp theo mã sự kiện. ## Lưu trữ và xuất dữ liệu {#retention-and-exports} Các bản ghi được lưu trong cơ sở dữ liệu NexCMP tại `/var/lib/nexcmp` và được bao gồm trong [backups](https://nexcmp.com/vi/docs/getting-started/backup-and-restore/). Thời gian lưu trữ phụ thuộc vào loại log: các lần thử đăng nhập của khách hàng cũ hơn 180 ngày và log yêu cầu API-key của khách hàng cũ hơn 60 ngày sẽ được dọn dẹp. Audit API-key của admin giữ lại tối đa khoảng 200,000 bản ghi gần nhất. Các giới hạn này không đồng nghĩa với thời gian lưu trữ tương tự cho dòng thời gian hoạt động hợp nhất. ## Trường hợp sử dụng phổ biến {#common-uses} | Câu hỏi | Nơi tra cứu | |---|---| | Ai đã tạm khóa khách hàng này? | Admin actions, tìm kiếm `customer.block` | | Vì sao VM biến mất? | VM events, lọc theo ID của VM; hoặc Activity | | Khách hàng đã nhận được email chưa? | Overview › Support › Sent emails | | Lần yêu cầu cập nhật gần nhất là khi nào? | Tab Console | --- # Security {#security} > **Vị trí trong trang quản trị:** System › Admin › Console security (`/account`), Admin users (`/users`); System › Settings › Customer logins (`/settings/login`). ## Admin console {#admin-console} ### Xác thực hai yếu tố (TOTP) {#two-factor-authentication-totp} Console có thể truy cập từ Internet, vì vậy bạn hãy bật TOTP. 1. Mở **System › Admin › Console security**. 2. Tại mục **Two-factor authentication (TOTP)**, nhấp vào **Start setup**. 3. Quét mã QR bằng Google Authenticator, Authy, 1Password hoặc Bitwarden, sau đó nhập mã gồm 6 chữ số. ### Dải IP được phép truy cập console {#allowed-console-ip-ranges} Tại mục **Allowed console IP ranges**, nhập một IP hoặc CIDR (IPv4 hoặc IPv6) trên mỗi dòng. **Để trống nghĩa là cho phép từ mọi nơi.** Ngoài dải này, cả đăng nhập và API quản trị đều bị chặn. ::: warning Tránh tự khóa quyền truy cập của chính bạn Trang hiển thị IP hiện tại của bạn và yêu cầu danh sách mới phải bao gồm IP này. Sử dụng **+ Add my IP**. Nếu vẫn bị khóa, bạn hãy dùng [truy cập khẩn cấp](https://nexcmp.com/vi/docs/getting-started/cli-reference/#emergency-access) từ máy chủ. ::: ### Đổi mật khẩu {#change-password} Điền **Current password**, **New password** và **Confirm new password**. Sử dụng mật khẩu dài và duy nhất (từ 12 ký tự trở lên; trình hướng dẫn thiết lập bắt buộc tối thiểu 12 ký tự cho quản trị viên đầu tiên). ### Tài khoản và vai trò quản trị viên {#administrator-accounts-and-roles} Mở **System › Admin › Admin users** và dùng **+ Create account**. | Role | Quyền truy cập | |---|---| | `admin` | Toàn quyền truy cập admin API | | `staff` | Chỉ đọc trên toàn bộ hệ thống | | `user` | Quyền chỉ đọc đối với tài nguyên của một khách hàng | Tài khoản root là tài khoản được tạo trong [trình hướng dẫn thiết lập](https://nexcmp.com/vi/docs/getting-started/setup-wizard/). Các thao tác trên hàng: **Edit**, **Reset PW**, **Key**, **Delete**. Mật khẩu được lưu trữ dưới dạng salted hash; việc đổi mật khẩu hoặc khóa tài khoản sẽ chấm dứt mọi phiên làm việc ngay lập tức. ## Đăng nhập của khách hàng {#customer-sign-in} Mở **System › Settings › Customer logins**. | Cài đặt | Chức năng | |---|---| | **Google sign-in** | Bật, sau đó nhập OAuth client ID và secret. Sao chép **Callback URL** hiển thị trên trang vào *Google Cloud Console › APIs & Services › Credentials › OAuth client ID › Authorized redirect URIs*. Dùng **Test configuration**. | | **GitHub login** | Tương tự, với *GitHub › Settings › Developer settings › OAuth Apps › Authorization callback URL* | | **Passkey** | Đăng nhập bằng vân tay, PIN hoặc khóa bảo mật phần cứng; bật theo mặc định. Passkey được liên kết với tên miền; mỗi tên miền đại lý hoạt động độc lập. Nhập tên miền cũ vào *Legacy passkey Domain* sau khi đổi thương hiệu để khách hàng nhận được gợi ý hữu ích | | **Xác thực lại khi thêm phương thức đăng nhập** | Yêu cầu nhập lại mật khẩu trước khi thêm passkey hoặc liên kết Google/GitHub (tắt theo mặc định) | | **Captcha** | Cloudflare Turnstile hoặc Google reCAPTCHA khi đăng ký: bật, chọn nhà cung cấp, nhập site key và secret key | | **Block e-mail domains** | Mỗi tên miền một dòng (tối đa 2000). Các địa chỉ trùng khớp sẽ bị từ chối khi đăng ký với `email_domain_blocked` | ![Trang Customer logins hiển thị Google sign-in cùng callback URL](https://nexcmp.com/vi/docs/images/administration/security-01-customer-logins.webp) ### Chính sách tích hợp sẵn {#built-in-policies} | Chính sách | Giá trị | |---|---| | Mật khẩu khách hàng | Tối thiểu 10 ký tự, gồm cả chữ cái và chữ số | | Phiên làm việc của khách hàng | 30 ngày; phiên "login as customer" kéo dài 1 giờ | | Xác thực e-mail | Bắt buộc trước khi tạo VM khi tính năng *require e-mail verified* được bật trong cài đặt bán hàng | | Anti-carding | Tài khoản nạp ít hơn mức tối thiểu chỉ có thể tạo số lượng VM giới hạn | ## Gia cố bảo mật máy chủ {#server-hardening} - Cổng 3000 được đóng sau khi thiết lập và TLS; xem [Installation](https://nexcmp.com/vi/docs/getting-started/installation/#the-panel-port-3000). - Dịch vụ chạy dưới quyền user không có đặc quyền `nexcmp` với systemd sandbox bị hạn chế. - API key, thông tin thanh toán và mật khẩu SMTP được lưu trữ mã hóa; master key nằm trong `/var/lib/nexcmp/secrets` — hãy bảo vệ [backups](https://nexcmp.com/vi/docs/getting-started/backup-and-restore/). - Các bản phát hành được xác minh bằng SHA-256 và chữ ký Ed25519 trước khi cài đặt. --- # Cài đặt chung {#general-settings} > **Vị trí trong trang admin:** System › Settings › General (`/settings`). Thay đổi có hiệu lực ngay lập tức (cache 30 giây). Trang này gồm có ba phần. ## Branding & URLs {#branding-urls} | Trường | Mục đích | |---|---| | Tên thương hiệu (e-mail, hóa đơn) | Hiển thị trong email và hóa đơn. Logo và màu sắc được cấu hình trong [Branding](https://nexcmp.com/vi/docs/customers/branding/) | | Ngôn ngữ mặc định | Ngôn ngữ cho khách truy cập mới | | Customer app URL | Địa chỉ công khai của portal, ví dụ `https://cloud.example.com` | | Console URL | Địa chỉ của dịch vụ VM console | | Admin URL | Liên kết được dùng khi bạn "đăng nhập với tư cách" khách hàng của reseller | | Partner console URL | Được dùng trong link mời, email gửi reseller và chuyển hướng sau khi nạp tiền | Trình hướng dẫn sẽ tự động điền các thông tin này từ domain của bạn; chỉ thay đổi nếu bạn chuyển portal sang nơi khác. ## Bên bán & lập hóa đơn {#seller-invoicing} Được in trên mỗi hóa đơn: | Trường | Ví dụ | |---|---| | Tên pháp nhân | Example Cloud Ltd | | Mã số thuế | `TAX-000000` | | Địa chỉ | 1 Example Street, New York | | Email liên hệ | `billing@example.com` | | Tiền tố số hóa đơn | `INV` (1–8 ký tự, A–Z và 0–9) | Các hóa đơn hiện có vẫn giữ thông tin bên bán và số hóa đơn đã phát hành; các thay đổi chỉ áp dụng cho hóa đơn **mới**. ## Bảo trì & khu vực {#maintenance-region} Bật **Customer app MAINTENANCE** để hiển thị banner và **chặn mọi thao tác ghi của khách hàng** trong khi admin console vẫn hoạt động bình thường. Nhập **Maintenance message** mà khách hàng sẽ thấy. Sử dụng tính năng này khi nâng cấp hạ tầng của bạn. ![Trang cài đặt General với tên thương hiệu, ngôn ngữ mặc định và các trường URL](https://nexcmp.com/vi/docs/images/administration/general-settings-01-general.webp) ## Các trang cài đặt khác {#other-settings-pages} | Trang | Hướng dẫn | |---|---| | Brand | [Branding](https://nexcmp.com/vi/docs/customers/branding/) | | Legal | [Legal](https://nexcmp.com/vi/docs/customers/legal/) | | Customer logins | [Security](https://nexcmp.com/vi/docs/administration/security/) | | Email | [SMTP và mẫu email](https://nexcmp.com/vi/docs/administration/smtp-and-emails/) | | Admin alerts | [Telegram và cảnh báo admin](https://nexcmp.com/vi/docs/administration/telegram-notifications/) | | Nhà cung cấp AI | [Nhà cung cấp AI](https://nexcmp.com/vi/docs/ai/ai-providers/) | --- # Báo cáo lỗi {#report-a-bug} > **Vị trí trong admin:** Top bar › **Report a bug** (cạnh Docs; chỉ hiển thị với quản trị viên chính). Bạn phát hiện lỗi trong NexCMP? Nhấn **Report a bug**, mô tả sự cố và gửi đi. Báo cáo sẽ được chuyển thẳng đến đội ngũ NexCMP dưới dạng một ticket trên tài khoản license của bạn chỉ trong một bước — không cần đăng nhập nơi khác, cũng không cần sao chép file log thủ công. Mọi gói đều có thể sử dụng: NexCMP Free hỗ trợ sửa lỗi, và NexCMP Source cũng vậy. ::: info Báo cáo lỗi không phải là yêu cầu hỗ trợ NexCMP Free không đi kèm hỗ trợ kỹ thuật, vì vậy hãy dùng biểu mẫu này cho các lỗi phần mềm. Hỗ trợ cài đặt và di chuyển dữ liệu thuộc gói [NexCMP Source](https://nexcmp.com/pricing). ::: ## Yêu cầu {#requirements} | Hạng mục | Yêu cầu | |---|---| | Phiên bản | NexCMP 1.5.2 trở lên | | Ai có thể gửi | Tài khoản quản trị viên chính. Tài khoản nhân viên (chỉ đọc), reseller console, khách hàng và bản demo chỉ đọc không thể gửi | | License | License đã kích hoạt (Free hoặc Source) và không bị tạm ngưng | | Mạng | Máy chủ phải kết nối được tới `https://nexcmp.com` qua HTTPS (cùng địa chỉ dùng để kiểm tra license và cập nhật) | ## Gửi báo cáo {#send-a-report} 1. Nhấp vào **Report a bug** ở thanh trên cùng. Trên điện thoại, hãy mở menu và chọn **Report a bug**. 2. Nhập **Subject** ngắn gọn. 3. Tại mục **What happened**, hãy mô tả những việc bạn đã làm, kết quả bạn thấy và những gì bạn mong đợi. 4. Tùy chọn liệt kê **Các bước tái hiện**. 5. Chọn mức độ **Impact**: **Blocking** (không thể làm việc), **Major** (tính năng chính bị hỏng) hoặc **Minor** (sự cố nhỏ hoặc về giao diện). 6. Giữ bật tùy chọn **Attach diagnostics** (khuyến nghị) và đọc khung **What will be sent**. 7. Nhấp vào **Send report**. Trong 1.6.1, phần thân biểu mẫu có thể cuộn trong khi các nút thao tác vẫn hiển thị, kể cả trên điện thoại. Các giá trị mật khẩu theo sau `password:` hoặc `password=` được che lại mà không xóa phần còn lại của báo cáo. Hãy kiểm tra lại nội dung trước khi gửi và lược bỏ dữ liệu khách hàng cùng thông tin xác thực. ![Hộp thoại Report a bug gồm tiêu đề, mô tả, mức độ ảnh hưởng và danh sách dữ liệu sẽ được gửi](https://nexcmp.com/vi/docs/images/administration/report-a-bug-01-dialog.webp) Khi báo cáo được tiếp nhận, hộp thoại sẽ hiển thị mã ticket và đường liên kết. Thư phản hồi (nếu có) sẽ được gửi đến địa chỉ email của tài khoản license trên nexcmp.com, đồng thời ticket cũng được liệt kê tại mục **Support** khi bạn đăng nhập với tư cách chủ sở hữu license. ## Dữ liệu được gửi {#what-is-sent} Khung **What will be sent** hiển thị chính xác các thông tin sau trước khi bạn nhấn Send: | Thông tin gửi đi | Chi tiết | |---|---| | Nội dung bạn nhập | Tiêu đề, mô tả, các bước thực hiện và mức độ ảnh hưởng | | Phiên bản, gói, domain | Phiên bản NexCMP, Free hoặc Source, cùng domain của hệ thống cài đặt | | Trang hiện tại | Trang bạn đang mở trong admin, loại bỏ mọi ký tự đằng sau `?` hoặc `#` | | Trình duyệt | Chuỗi user-agent của trình duyệt (tên, phiên bản và hệ điều hành), giới hạn tối đa 200 ký tự | | Lỗi gần đây | Tối đa 5 lỗi gần nhất trong tab trình duyệt này. Với lỗi script thì chỉ gồm nội dung thông báo; với request thất bại thì chỉ gồm method, đường dẫn và mã trạng thái | Bạn có thể tắt **Attach diagnostics**; khi đó chỉ có nội dung bạn nhập cùng phiên bản, gói và domain được gửi đi. ## Dữ liệu không bao giờ gửi {#what-is-never-sent} - Mật khẩu, token, cookie và API key. Bất kỳ thông tin nào tương tự trong văn bản của bạn hoặc trong thông báo lỗi đều được che đi (hiển thị dạng `***` hoặc `[redacted]`) ngay trên máy chủ của bạn trước khi gửi. - Nội dung của request và response — các request thất bại chỉ được ghi lại method, path và status. - Dữ liệu khách hàng của bạn (tên, email, đơn hàng, hóa đơn) và địa chỉ IP của họ. - Địa chỉ IP trình duyệt của bạn và bất kỳ tệp nào từ máy chủ. Giống như mọi lần kiểm tra license, máy chủ license sẽ thấy địa chỉ IP mà máy chủ của bạn kết nối đến. Ticket được liên kết với bản cài đặt của bạn thông qua license token mà máy chủ đang lưu giữ, do đó phiên bản, domain và bản cài đặt được máy chủ thiết lập và không thể thay đổi từ trình duyệt. ## Giới hạn {#limits} | Hạn mức | Giá trị | |---|---| | Subject | 150 ký tự | | Description cùng với steps | Tổng cộng 8 KB | | Reports | 5 mỗi giờ và 20 mỗi ngày cho toàn bộ bản cài đặt | Gửi cùng một báo cáo hai lần (ví dụ sau lỗi mạng) sẽ không tạo ticket thứ hai. ## Xử lý sự cố {#troubleshooting} | Thông báo | Nguyên nhân | Cách khắc phục | |---|---|---| | Kích hoạt license của bạn trước | Bản cài đặt chưa có license được kích hoạt | Mở **License & updates** và kích hoạt, sau đó gửi lại | | Không thể kết nối đến license server | Máy chủ không thể kết nối tới `nexcmp.com` | Kiểm tra kết nối HTTPS chiều ra (outbound) và DNS từ máy chủ, sau đó nhấn lại **Send report** — nội dung bạn nhập vẫn được giữ nguyên | | Quá nhiều báo cáo lỗi từ bản cài đặt này | Bạn đã đạt giới hạn 5 báo cáo mỗi giờ hoặc 20 báo cáo mỗi ngày | Hãy đợi rồi thử lại; thay vào đó, bạn có thể bổ sung các phát hiện mới vào ticket đang mở | | License này đã bị tạm ngưng | License bị tạm ngưng hoặc đã hoàn tiền | Xem [Giấy phép và mua hàng](https://nexcmp.com/vi/docs/getting-started/license-and-purchase/) | | Bản cài đặt này đã bị thu hồi | Bản cài đặt đã bị thu hồi trong cổng quản lý license | Kích hoạt lại từ **License & updates** | | Không thể làm mới license token | Máy chủ không thể làm mới license token của mình | Mở **License & updates**, nhấn **Refresh**, sau đó gửi lại | | Không có nút Report a bug | Bạn đang đăng nhập bằng tài khoản nhân viên, reseller hoặc khách hàng, hoặc đang ở bản demo chỉ đọc | Đăng nhập bằng tài khoản quản trị viên chính | ::: tip Dành cho AI assistant và API key Trợ lý trong trang quản trị và admin API key không thể thay mặt bạn gửi báo cáo lỗi: nút này yêu cầu một người thực đăng nhập với tư cách quản trị viên chính. ::: --- # Lỗi cài đặt {#installation-errors} Trình cài đặt sẽ dừng lại ở lỗi nghiêm trọng đầu tiên và in dòng chữ màu đỏ bắt đầu bằng `✗`. Hãy khắc phục nguyên nhân và **chạy lại lệnh đó** — trình cài đặt an toàn để chạy lại nhiều lần. Các dòng thông tin bắt đầu bằng `•`, các bước thành công bắt đầu bằng `✓`. ## Kiểm tra máy chủ {#machine-checks} | Thông báo | Nguyên nhân | Cách khắc phục | |---|---|---| | `must be run as root (sudo)` | Không chạy dưới quyền root | Thêm `sudo` vào trước lệnh, hoặc chạy với quyền root. | | `only Ubuntu 22.04/24.04 is supported (this host: …)` | Bản phân phối hoặc phiên bản khác | Hãy sử dụng máy chủ Ubuntu 22.04 hoặc 24.04. | | `only x86_64 is supported` | CPU ARM hoặc kiến trúc khác | Sử dụng máy chủ x86_64. | | `requires ≥ 2 GB RAM (host has … MB)` | Không đủ bộ nhớ | Bổ sung thêm RAM. | | `requires ≥ 8 GB free disk space on / (… GB available)` | Hệ thống tệp root gần đầy | Giải phóng dung lượng hoặc mở rộng `/`. | | `missing --license` / `missing --domain` | Cài đặt lần đầu thiếu các tham số đó | Truyền cả hai tham số — xem [Cài đặt](https://nexcmp.com/vi/docs/getting-started/installation/#parameters). | | `unknown argument: …` | Sai chính tả trong tham số | Kiểm tra chính tả; chạy lại với `--help`. | | `apt-get failed (another apt/dpkg process, e.g. unattended-upgrades, may still be running)` | Trình quản lý gói đang bị khóa | Chờ vài phút (Ubuntu mới cài sẽ tự động cập nhật sau khi khởi động) rồi chạy lại. | | `… is a symlink — aborting` | `/opt/nexcmp` hoặc `/etc/nexcmp` là liên kết tượng trưng (symlink) | Thay thế bằng một thư mục thực — trình cài đặt từ chối symlink vì lý do bảo mật. | ## Kích hoạt giấy phép {#license-activation} | Thông báo | Nguyên nhân | Cách khắc phục | |---|---|---| | `cannot connect to https://nexcmp.com` | Không có kết nối HTTPS chiều đi tới máy chủ cấp phép | Kiểm tra DNS, firewall và proxy trên máy chủ: `curl -I https://nexcmp.com`. | | `license activation failed (HTTP …): ` | Máy chủ cấp phép từ chối khóa | Đọc thông báo lỗi: sai khóa, tên miền không khớp với giấy phép, giấy phép bị tạm ngưng hoặc thu hồi. Kiểm tra trang quản lý giấy phép tại [nexcmp.com/licenses](https://nexcmp.com/licenses). | | `no release available for this license yet` | Giấy phép không có bản phát hành nào để tải xuống | Liên hệ bộ phận bán hàng; xem [Hỗ trợ](https://nexcmp.com/vi/docs/troubleshooting/support/). | ## Tải xuống và xác thực {#download-and-verification} | Thông báo | Nguyên nhân | Cách khắc phục | |---|---|---| | `failed to download release X` | Sự cố mạng trong quá trình tải xuống | Chạy lại. | | `sha256 mismatch (… ≠ …)` | Tệp bị lỗi khi truyền hoặc đã bị thay đổi | Chạy lại; nếu lỗi lặp lại, có thể proxy đang sửa đổi dữ liệu tải xuống — hãy thử từ một mạng khác. | | `release X is unsigned — refusing to install` | Máy chủ không trả về chữ ký | Tuyệt đối không bỏ qua bước này; hãy liên hệ hỗ trợ. | | `INVALID SIGNATURE for version X — aborting` | Chữ ký Ed25519 không khớp | **Không** cài đặt. Liên hệ hỗ trợ — điều này có nghĩa tệp không phải bản phát hành chính thức. | | `openssl failed to read public key` | OpenSSL quá cũ hoặc bị lỗi | Cập nhật gói `openssl`. | | `invalid version: …` | Dữ liệu bất thường từ máy chủ | Chạy lại; liên hệ hỗ trợ nếu lỗi vẫn tiếp diễn. | ## Khởi động dịch vụ {#service-start} | Thông báo | Nguyên nhân | Cách khắc phục | |---|---|---| | `service failed to start — check: journalctl -u nexcmp -n 50` | Panel không phản hồi `/healthz` trong vòng 3 phút | Đọc journal. Các nguyên nhân phổ biến: cổng (mặc định 3000) đã bị chiếm dụng (`ss -ltnp | grep 3000`) — hãy cài đặt lại với `--port`; các tệp thuộc sở hữu của root trong `/var/lib/nexcmp` — chạy `sudo nexcmp fix-owner`. | ## nginx và TLS {#nginx-and-tls} | Thông báo | Nguyên nhân | Cách khắc phục | |---|---|---| | `DNS does not point to (nor to Cloudflare) — skipping nginx/TLS` | Bản ghi A/AAAA bị thiếu hoặc không chính xác | Xem [DNS và Cloudflare](https://nexcmp.com/vi/docs/getting-started/dns-and-cloudflare/), sau đó chạy lại. | | `certbot could not get a certificate yet — re-run the installer once DNS has settled` | Xác thực Let's Encrypt thất bại (cổng 80 bị chặn, DNS chưa cập nhật, vượt quá rate limit) | Mở cổng 80, chờ DNS cập nhật rồi chạy lại. Kiểm tra `/var/log/letsencrypt/letsencrypt.log`. | | `certbot could not renew now — keeping the existing certificate` | Lỗi gia hạn tạm thời | Không ảnh hưởng; hãy chạy lại sau. | | `nginx rejected the HTTPS configuration — kept the previous one (check: nginx -t)` | Xung đột với một trang nginx khác (trùng `server_name`, cấu hình bị lặp) | Chạy `sudo nginx -t` và xử lý xung đột, sau đó chạy lại. | | `apt-get could not install nginx` / `certbot`, hoặc `E: Failed to fetch … 404 Not Found` | Trình quản lý gói bị khóa hoặc index gói của máy chủ đã cũ (thường gặp trên image mẫu đã lâu không cập nhật) | Chạy `sudo apt-get update`, chờ các tiến trình apt khác hoàn tất, sau đó chạy lại trình cài đặt. | | `openssl could not create the self-signed certificate` | Lỗi OpenSSL | Cập nhật `openssl`; chạy lại. | ## Sau khi cài đặt {#after-installation} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | Trình duyệt không thể mở `https://` | DNS hoặc TLS chưa sẵn sàng | `sudo nexcmp status`; sử dụng [quyền truy cập khẩn cấp](https://nexcmp.com/vi/docs/getting-started/cli-reference/#emergency-access). | | `ERR_TOO_MANY_REDIRECTS` | Chế độ SSL của Cloudflare là **Flexible** | Đặt thành **Full (strict)** — [chi tiết](https://nexcmp.com/vi/docs/getting-started/dns-and-cloudflare/). | | Wizard báo "setup code" không đúng | Nhập sai hoặc dùng mã từ lần cài đặt trước | Chạy `sudo nexcmp status` và sao chép mã hiện tại. | | License báo HTTP 421 | Các file trong `/var/lib/nexcmp` thuộc quyền sở hữu của root | `sudo nexcmp fix-owner`, sau đó `sudo systemctl restart nexcmp`. | --- # Lỗi cập nhật {#update-errors} > **Vị trí trong trang admin:** System › Admin › License & updates (`/license`) Các bản cập nhật được mô tả trong [Cập nhật NexCMP](https://nexcmp.com/vi/docs/getting-started/updating/). Khi thẻ Update hoặc `sudo nexcmp update` báo lỗi: | Thông báo | Nguyên nhân | Cách khắc phục | |---|---|---| | `update plan expired — renew on the license page to receive this feature release` | Ngày "updates until" của bạn trước ngày phát hành. Các bản vá bảo mật vẫn được cung cấp; các bản phát hành tính năng thì không | Gia hạn tại [nexcmp.com/licenses](https://nexcmp.com/licenses) ($99 mỗi năm cho NexCMP Free), sau đó kiểm tra lại. Phần mềm vẫn tiếp tục hoạt động trong lúc này. | | `sha256 mismatch (downloaded …, expected …)` | Bản tải về bị hỏng hoặc bị sửa đổi | Thử lại. Nếu vẫn lặp lại, hãy kiểm tra các proxy trên đường truyền. | | `downgrade/same version rejected: X is not newer than Y` | Phiên bản được chọn không mới hơn phiên bản đang chạy | Không cần làm gì — bạn đang ở phiên bản mới nhất. | | `extraction failed / main binary missing` | Tệp nén bị hỏng hoặc đầy ổ đĩa | Kiểm tra `df -h`; thử lại. | | `systemctl restart failed` | Dịch vụ không thể khởi động lại sau khi thay thế binary | `journalctl -u nexcmp -n 80`; binary trước đó được giữ lại dưới dạng `/opt/nexcmp/bin/nexcmp.bak` — xem rollback bên dưới. | | Lỗi máy chủ khi kết nối với máy chủ cập nhật | Không có route tới `nexcmp.com` hoặc token license đã hết hạn | Kiểm tra kết nối HTTPS chiều ra; nhấp vào **Check now** trên thẻ License. | ## Rollback {#roll-back} Nếu phiên bản mới hoạt động không đúng: ```bash sudo systemctl stop nexcmp-vmd nexcmp sudo cp /opt/nexcmp/bin/nexcmp.bak /opt/nexcmp/bin/nexcmp echo | sudo tee /opt/nexcmp/VERSION sudo systemctl start nexcmp nexcmp-vmd ``` Nếu migration cơ sở dữ liệu đã chạy, hãy khôi phục cả [bản sao lưu](https://nexcmp.com/vi/docs/getting-started/backup-and-restore/) đã tạo trước khi cập nhật. ## `sudo nexcmp update` báo không tìm thấy trình cài đặt {#sudo-nexcmp-update-says-it-cannot-find-the-installer} `nexcmp update` chạy trình cài đặt đi kèm bên trong bản phát hành đã cài đặt (`/opt/nexcmp/releases//share/install.sh`). Nếu thiếu file đó, hãy chạy lại lệnh cài đặt từ trang license của bạn. --- # FAQ {#faq} ## Licensing {#licensing} **Điều gì xảy ra nếu license của tôi hết hạn hoặc máy chủ mất kết nối Internet?** Token duy trì hiệu lực trong 14 ngày và gia hạn hàng ngày. Sau thời gian đó, khách hàng không thể tạo dịch vụ **mới**; các dịch vụ đang chạy, thanh toán và đăng nhập vẫn hoạt động bình thường. Xem [License và mua hàng](https://nexcmp.com/vi/docs/getting-started/license-and-purchase/). **Tôi có tiếp tục nhận các bản vá bảo mật sau khi quyền cập nhật kết thúc không?** Có — các bản phát hành bảo mật luôn được cung cấp; các bản phát hành tính năng cần có quyền cập nhật còn hiệu lực. **Tôi có thể chạy NexCMP trên máy chủ hoặc domain thứ hai không?** Hãy kích hoạt bằng key và domain đã đăng ký trên license — xem [License and purchase](https://nexcmp.com/vi/docs/getting-started/license-and-purchase/#moving-to-a-new-server-or-domain). ## Cài đặt {#installation} **NexCMP có cần Docker, PostgreSQL hay Redis không?** Không. Đây là một chương trình duy nhất với cơ sở dữ liệu SQLite, được chạy bởi systemd dưới quyền user không có đặc quyền. Xem [Requirements](https://nexcmp.com/vi/docs/getting-started/requirements/). **Tôi có thể cài đặt mà không cần domain public không?** Có, hãy sử dụng `--no-nginx` và SSH tunnel — xem [Installation](https://nexcmp.com/vi/docs/getting-started/installation/#installing-without-a-public-domain-lab-or-test). **Tại sao cổng 3000 bị đóng sau khi cài đặt?** Vì lý do bảo mật, bảng điều khiển sẽ lắng nghe trên `127.0.0.1` khi trình hướng dẫn hoàn tất và TLS được kích hoạt. Hãy dùng `sudo nexcmp open-port` cho các trường hợp khẩn cấp. ## Hạ tầng {#infrastructure} **Tôi có thể dùng chung CloudStack và Proxmox VE không?** Có. Một zone có thể có cả hai; mỗi plan sẽ chọn source tương ứng. Xem [Proxmox VE](https://nexcmp.com/vi/docs/infrastructure/proxmox/) và [Zones](https://nexcmp.com/vi/docs/infrastructure/zones/). **Tôi có cần ROOT API key của CloudStack không?** Không — và bạn không nên dùng nó. Hãy tạo một tài khoản riêng — [CloudStack](https://nexcmp.com/vi/docs/infrastructure/cloudstack/). **Tại sao một số tab hoặc nút không hiển thị trên máy ảo?** Các trang chỉ hiển thị những gì source của VM hỗ trợ (ví dụ: Proxmox VE không có port forwarding). Xem bảng tính năng trong [Proxmox VE](https://nexcmp.com/vi/docs/infrastructure/proxmox/). ## Vận hành {#operations} **Làm thế nào để chuyển NexCMP sang máy chủ khác?** Hãy sao lưu, cài đặt cùng phiên bản trên máy chủ mới với cùng license đó rồi khôi phục — xem [Backup and restore](https://nexcmp.com/vi/docs/getting-started/backup-and-restore/). **Xem log ở đâu?** `journalctl -u nexcmp -u nexcmp-vmd`, `/var/log/nexcmp`, và trong admin console tại System › Logs. Xem [Audit log](https://nexcmp.com/vi/docs/administration/audit-log/). **Tôi có thể xem customer portal trước khi cài đặt không?** Có. Các trang dịch vụ trên [nexcmp.com](https://nexcmp.com/platform/) hiển thị từng tab của customer portal kèm dữ liệu mẫu; hãy mở *View demo* để xem ở chế độ toàn màn hình. Để xem bản cài đặt thực tế, hãy liên hệ sales. --- # Hỗ trợ {#support} ## Liên hệ {#contact} Chúng tôi không dùng form liên hệ. Hãy gửi e-mail đến **sales@nexcmp.com** — địa chỉ này hỗ trợ về licensing, gia hạn, domain và các câu hỏi kỹ thuật. Trang license của bạn tại [nexcmp.com/licenses](https://nexcmp.com/licenses) cũng liên kết đến địa chỉ này. ## Trước khi liên hệ {#before-you-write} 1. Tìm kiếm trong tài liệu này (nhấn `/`) và kiểm tra [Installation errors](https://nexcmp.com/vi/docs/troubleshooting/installation-errors/) cùng [Update errors](https://nexcmp.com/vi/docs/troubleshooting/update-errors/). 2. Thu thập các thông tin dưới đây — chúng giúp đội ngũ hỗ trợ giải đáp chỉ trong một lần phản hồi. ## Thông tin cần cung cấp {#what-to-include} | Hạng mục | Cách lấy thông tin | |---|---| | Phiên bản NexCMP | `sudo nexcmp status` hoặc System › Admin › License & updates | | Domain chính và 4 ký tự cuối của license key | License & updates (không bao giờ gửi toàn bộ key) | | Thao tác bạn đã thực hiện và kết quả mong muốn | Các bước chi tiết | | Nội dung lỗi hoặc ảnh chụp màn hình | Ẩn thông tin bảo mật trước khi gửi | | Trạng thái dịch vụ | `sudo nexcmp status` | | Các dòng log gần nhất | `sudo journalctl -u nexcmp -u nexcmp-vmd -n 100 --no-pager` | | Hạ tầng | Phiên bản CloudStack hoặc Proxmox VE, một hay nhiều zone | ::: warning Tuyệt đối không gửi thông tin bảo mật Không gửi license key, API key, mật khẩu, mã thiết lập, thông tin thanh toán hoặc file sao lưu. Hãy che các thông tin này trong log và ảnh chụp màn hình. ::: ## Báo cáo bảo mật {#security-reports} Nếu bạn nghi ngờ đã phát hiện lỗ hổng bảo mật, hãy gửi e-mail đến cùng địa chỉ đó với tiêu đề chứa "Security" và tránh công khai chi tiết cho đến khi sự cố được khắc phục.