# NexCMP 1.6.1 — full documentation > Complete NexCMP documentation in one file. Source: https://nexcmp.com/ru/docs/ · generated 2026-11-02. --- # Что такое NexCMP {#what-is-nexcmp} NexCMP — это ПО, устанавливаемое на **ваш собственный сервер**, чтобы превратить облачную инфраструктуру в готовый к продаже продукт. Вы получаете: - **клиентский портал**, где пользователи регистрируются, пополняют баланс, заказывают виртуальные машины и другие услуги, открывают консоль, создают Snapshots и обращаются в поддержку; - **панель администратора** (`/admin`) для управления клиентами, тарифами, ценами, платежами, инфраструктурой и настройками; - **биллинг**: баланс для каждого клиента, почасовая или помесячная оплата, счета, промоакции и квоты на ресурсы; - **white-label реселлеров**: возможность для других брендов продавать ваши ресурсы под собственным доменом; - **API**, утилиту командной строки (`cmp`) и MCP-сервер для автоматизации; - дополнительные модули **AI Chat** (ассистент поддержки) и **AI Agent** (управление виртуальной машиной на естественном языке). ## Поддерживаемые платформы {#what-it-connects-to} NexCMP не размещает виртуальные машины самостоятельно, а управляет платформой, которая выполняет эту задачу. В качестве *источника* (также называемого провайдером) может выступать: | Source | Типичное применение | Руководство | |---|---|---| | Apache CloudStack | Частное или публичное облако с зонами, сетями, виртуальными маршрутизаторами и публичными IP | [CloudStack](https://nexcmp.com/ru/docs/infrastructure/cloudstack/) | | Proxmox VE | Отдельные серверы или уже развернутые кластеры | [Proxmox VE](https://nexcmp.com/ru/docs/infrastructure/proxmox/) | Для других модулей требуется отдельная инфраструктура: [серверы bare-metal](https://nexcmp.com/ru/docs/infrastructure/dedicated/), [узлы VPN и прокси](https://nexcmp.com/ru/docs/infrastructure/vpn-proxy-nodes/), [объектное хранилище S3](https://nexcmp.com/ru/docs/infrastructure/s3/), [Kubernetes и Private Cloud](https://nexcmp.com/ru/docs/infrastructure/kubernetes-and-private-cloud/). Сводная таблица по всем компонентам приведена в разделе [Требования к инфраструктуре](https://nexcmp.com/ru/docs/infrastructure/requirements/). ## Как устроен NexCMP {#how-it-is-built} NexCMP представляет собой единое приложение с двумя службами systemd на одном сервере Ubuntu: - `nexcmp` — веб-сервер: клиентский портал, панель администратора, API, мастер настройки; - `nexcmp-vmd` — фоновый воркер: задачи провижининга, синхронизация с CloudStack или Proxmox, биллинговые циклы. Данные хранятся в `/var/lib/nexcmp` (базы данных SQLite и файлы), конфигурация — в `/etc/nexcmp`, сама программа — в `/opt/nexcmp`. Подробная схема приведена в разделе [Архитектура](https://nexcmp.com/ru/docs/infrastructure/architecture/). ## Дальнейшие шаги {#where-to-go-next} 1. Изучите [требования](https://nexcmp.com/ru/docs/getting-started/requirements/). 2. Получите лицензию — [Лицензирование и покупка](https://nexcmp.com/ru/docs/getting-started/license-and-purchase/). 3. [Выполните установку](https://nexcmp.com/ru/docs/getting-started/installation/), затем запустите [мастер настройки](https://nexcmp.com/ru/docs/getting-started/setup-wizard/). 4. Подключите вашу платформу: [CloudStack](https://nexcmp.com/ru/docs/infrastructure/cloudstack/) или [Proxmox VE](https://nexcmp.com/ru/docs/infrastructure/proxmox/). --- # Требования к серверу NexCMP {#requirements-for-the-nexcmp-server} На этой странице описаны требования к серверу для NexCMP. Требования к CloudStack, Proxmox VE и остальной инфраструктуре приведены в разделе [Требования к инфраструктуре](https://nexcmp.com/ru/docs/infrastructure/requirements/). ## Сервер {#server} | Параметр | Требование | Проверяется установщиком | |---|---|---| | Операционная система | Ubuntu **22.04** или **24.04** | Да — на любых других ОС завершается с ошибкой | | Архитектура процессора | x86_64 | Да | | Оперативная память | Минимум 2 ГБ (установщик прерывает работу, если доступно менее примерно 1.8 ГБ) | Да | | Свободное место на диске | Минимум 8 ГБ свободного места на `/` | Да | | Права доступа | root (`sudo`) | Да | | Пакеты | `curl`, `ca-certificates`, `zstd`, `tar`, `openssl`, `python3`, `openssh-client` — устанавливаются автоматически | Устанавливаются, если отсутствуют | | Для HTTPS | `nginx` и `certbot` — устанавливаются автоматически, если не указан `--no-nginx` | Устанавливаются, если отсутствуют | ::: tip Выбор конфигурации Для небольшой инсталляции (несколько сотен клиентов) вполне достаточно 2 vCPU / 4 ГБ RAM. Основной объем диска занимают базы данных SQLite, а также опциональные файлы обновлений и резервные копии — для продакшена закладывайте от 20 ГБ. ::: ## Сеть {#network} | Направление | Порт | Назначение | |---|---|---| | Входящий | 80/tcp | Проверка Let's Encrypt и перенаправление на HTTPS | | Входящий | 443/tcp | Клиентский портал, консоль администратора, API | | Входящий | 3000/tcp | Только для мастера первоначальной установки и аварийного доступа — см. [Установка](https://nexcmp.com/ru/docs/getting-started/installation/#the-panel-port-3000) | | Исходящий | 443/tcp на `nexcmp.com` | Активация лицензии, ежедневная проверка лицензии, обновления | | Исходящий | к вашему CloudStack API / Proxmox API | Предоставление ресурсов и синхронизация | | Исходящий | 443/tcp к подключенным платежным, почтовым и AI-провайдерам | Stripe, PayPal, SMTP, AI-провайдер и т. д. | Серверу требуется **публичный IPv4-адрес**, если сертификат Let's Encrypt должен выпускаться напрямую. Если домен проксируется через Cloudflare, см. [DNS и Cloudflare](https://nexcmp.com/ru/docs/getting-started/dns-and-cloudflare/). ## DNS - Один **основной домен** (например, `cloud.example.com`) — портал доступен по адресу `https://cloud.example.com/`, а консоль администратора — по адресу `https://cloud.example.com/admin`. - Необязательно: `admin.` и `partner.`. Если эти имена разрешаются на сервер (или на Cloudflare), установщик добавит их в сертификат. - Домен должен совпадать с доменом, указанным в вашей лицензии. ## Не требуется на этом сервере {#not-required-on-this-server} NexCMP работает от имени обычного непривилегированного системного пользователя (`nexcmp`). Ему **не** требуются root во время работы, Docker, отдельный сервер баз данных, Redis или какое-либо ПО гипервизора. --- # Лицензия и покупка {#license-and-purchase} > **В панели администратора:** System › Admin › License & updates (`/license`) NexCMP активируется с помощью **лицензионного ключа**, которым вы управляете в своем [аккаунте NexCMP](https://nexcmp.com/licenses). Редакции и актуальные цены указаны на [nexcmp.com/pricing](https://nexcmp.com/pricing); на этой странице описывается работа лицензии после ее получения. ## Получение лицензии {#get-a-license} 1. Создайте аккаунт на [nexcmp.com](https://nexcmp.com/register) и подтвердите свой e-mail. 2. Выберите редакцию: - **NexCMP Free** — для операторов связи с собственным ASN и подсетью, зарегистрированной на их имя. Отправьте заявку на [nexcmp.com/deploy](https://nexcmp.com/deploy) (компания, ASN, подсеть, домен панели). E-mail вашего аккаунта должен находиться на корпоративном домене, указанном в публичном реестре (WHOIS) для ASN или подсети. Каждая заявка проверяется вручную; о решении вы узнаете по e-mail, а лицензионный ключ появится только после одобрения. - **NexCMP Source** — единовременный апгрейд, ASN не требуется. См. [nexcmp.com/pricing](https://nexcmp.com/pricing). 3. Откройте страницу своей лицензии. На ней отображаются **лицензионный ключ** (формат `NXC-XXXXX-XXXXX-XXXXX-XXXXX`), **основной домен** и готовая команда для установки. ::: warning Храните ключ в тайне Лицензионный ключ активирует установку. Относитесь к нему как к паролю: не отправляйте его в тикеты, чаты и не показывайте на скриншотах. ::: ## Содержимое лицензии {#what-a-license-contains} | Поле | Значение | |---|---| | Основной домен | Имя хоста, на котором работает портал. Ключ привязывается к нему при активации. | | Домены реселлеров | Дополнительные имена хостов, используемые в качестве white-label порталов — см. [Реселлеры](https://nexcmp.com/ru/docs/customers/resellers/). | | Обновления до | Дата, до которой вы получаете **обновления и исправления ошибок**. Для лицензии Free предоставляется **1 год** с даты одобрения; продление стоит $99 в год на странице лицензии. Исправления безопасности предоставляются всегда, даже после этой даты. | | Статус | `active` или suspended / expired / revoked. | ## Когда заканчивается бесплатный год {#when-the-free-year-ends} ПО **продолжает работать** после наступления даты «Обновления до»: клиенты, услуги и биллинг не затрагиваются. Вы перестаете получать новые функциональные релизы и исправления ошибок (исправления безопасности продолжают поступать). Для продления перейдите на страницу лицензии на [nexcmp.com/licenses](https://nexcmp.com/licenses) ($99 в год); продление добавляет 12 месяцев к текущей дате окончания. NexCMP Free включает только исправления ошибок — без технической поддержки и приложений. ## Что дает NexCMP Source {#what-nexcmp-source-adds} Лицензия Source — это единовременный апгрейд вашей лицензии за $1,999: полный исходный код, все приложения NexCMP (Android, iOS, Windows, macOS, Linux, Chrome / Edge / Brave и Firefox), собранные и брендированные для вас, а также 30 рабочих дней с опытным инженером — бесплатная миграция с VMware, WHMCS или другой панели, либо полная настройка под ключ. Новые релизы исходного кода включены на 12 месяцев; их дальнейшее продление ($99 в год) опционально, а загруженный исходный код остается у вас навсегда. См. [Условия лицензии Source](https://nexcmp.com/legal/source-license/). ## Как происходит проверка лицензии {#how-the-installation-checks-its-license} - При установке сервер активирует ключ для вашего домена и получает **подписанный токен**. - Токен продлевается автоматически каждые **24 часа**. Он остается действительным в течение **14 дней**, поэтому кратковременные сбои интернет-соединения не влияют на работу. - Все релизы и токены проверяются встроенной в программу подписью Ed25519; модифицированные загрузки отклоняются. Проверить статус можно в любое время в консоли администратора или с помощью `sudo nexcmp status`. ## Если лицензия недействительна {#if-the-license-is-not-valid} Если срок действия токена истек, лицензия приостановлена или домен больше не совпадает: - клиенты **не могут создавать новые услуги**, а в консоли администратора отображается баннер; - уже работающие услуги, **биллинг и существующие клиенты не затрагиваются**; - устраните причину (восстановите подключение сервера к интернету, продлите лицензию на [nexcmp.com/licenses](https://nexcmp.com/licenses)) и нажмите **Check now** в License & updates. ## Перенос на другой сервер или домен {#moving-to-a-new-server-or-domain} Выполните активацию на новом сервере с тем же ключом и зарегистрированным доменом (см. [Установка](https://nexcmp.com/ru/docs/getting-started/installation/)). Чтобы изменить зарегистрированный домен, сначала измените его на странице лицензии на [nexcmp.com/licenses](https://nexcmp.com/licenses), а затем перезапустите инсталлятор с новым `--domain`. --- # Установить NexCMP {#install-nexcmp} Инсталлятор представляет собой единый скрипт, предоставляемый вашим сервером лицензий. Он проверяет систему, активирует лицензию, скачивает и проверяет программу, устанавливает службы и (опционально) настраивает nginx с сертификатом Let's Encrypt. ## Перед началом {#before-you-start} - Сервер, соответствующий [требованиям](https://nexcmp.com/ru/docs/getting-started/requirements/), и root-доступ. - Ваш **лицензионный ключ** и **основной домен** со [страницы лицензии](https://nexcmp.com/licenses) — см. [Лицензия и покупка](https://nexcmp.com/ru/docs/getting-started/license-and-purchase/). - DNS-запись для домена — см. [DNS и Cloudflare](https://nexcmp.com/ru/docs/getting-started/dns-and-cloudflare/). Вы также можете сначала выполнить установку, а DNS настроить позже: инсталлятор сообщит, чего не хватает, и его можно будет просто запустить снова. ## Установка {#install} 1. Войдите на сервер и переключитесь на пользователя root (или используйте префикс `sudo`). 2. Выполните команду со страницы вашей лицензии. Она выглядит следующим образом: ```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. Дождитесь появления отметок об успешном выполнении. Чистая установка занимает несколько минут; при первом запуске создается схема базы данных, что на медленных дисках может занять до одной минуты. 4. Ознакомьтесь с итоговыми данными в конце. Там выводятся URL-адреса портала и панели администратора, **код настройки** и дальнейшие действия. ![Завершение работы инсталлятора с URL портала, URL админ-панели и одноразовым кодом настройки](https://nexcmp.com/ru/docs/images/getting-started/installation-01-finish.webp) ## Параметры {#parameters} | Параметр | По умолчанию | Значение | |---|---|---| | `--license KEY` | обязательно при первой установке | Лицензионный ключ. | | `--domain NAME` | обязательно при первой установке | Основной домен. Должен совпадать с указанным в лицензии. `https://` и завершающие пути отсекаются. | | `--email ADDRESS` | нет | Контактный e-mail для уведомлений Let's Encrypt об истечении срока действия. Без него сертификат регистрируется без e-mail. | | `--port N` | `3000` | Локальный порт панели (1–65535). | | `--no-nginx` | отключено | Не устанавливать и не настраивать nginx / TLS. Используйте этот параметр, если вы настраиваете собственный reverse proxy или хотите сначала ознакомиться с NexCMP. | | `--behind-cloudflare` | определяется автоматически | Принудительно включить режим «домен проксируется через Cloudflare». Обычно определяется по DNS. | | `--channel NAME` | `stable` | Канал релизов. | Повторный запуск инсталлятора **без параметров** использует сохраненные значения (`/etc/nexcmp/install.conf`) и безопасно обновляет систему, сохраняя данные, конфигурацию и учетные записи. Именно это и выполняет `sudo nexcmp update`. ## Что делает инсталлятор {#what-the-installer-does} 1. **Проверяет сервер** — Ubuntu 22.04/24.04, x86_64, не менее 2 ГБ RAM, 8 ГБ свободного дискового пространства. 2. **Устанавливает необходимые пакеты** (`curl`, `zstd`, `openssl`, `python3`, `openssh-client` …). 3. **Создает сервисного пользователя** `nexcmp` и каталоги: `/opt/nexcmp` (программа, владелец — root, доступ сервису только для чтения), `/etc/nexcmp` (конфигурация), `/var/lib/nexcmp` (данные), `/var/log/nexcmp`. 4. **Активирует лицензию** для домена и сохраняет фиксированный идентификатор экземпляра для этой машины. 5. **Загружает последний доступный вам релиз**, затем проверяет его хэш SHA-256 и подпись Ed25519. Релиз без корректной подписи отклоняется. Установщик никогда не понижает версию запущенной системы. 6. **Записывает конфигурацию и юниты systemd** (`nexcmp`, `nexcmp-vmd`, `nexcmp-update`) и запускает службы; затем ожидает ответа от `/healthz`. 7. **Настраивает nginx и TLS** (если не указан флаг `--no-nginx`): получает сертификат Let's Encrypt с помощью certbot (проверка webroot) для основного домена и для `admin.` / `partner.`, если эти имена также резолвятся. Если DNS еще не указывает на этот сервер (или Cloudflare), этот шаг пропускается с выводом уведомления. 8. **Выводит сводку** с URL-адресами и, если администратор еще не создан, **код первоначальной настройки**. ## Порт панели (3000) {#the-panel-port-3000} - При первой установке панель слушает `0.0.0.0:3000`, чтобы вы могли открыть мастер первоначальной настройки по адресу `http://:3000/setup`. - После завершения работы мастера **и** активации TLS панель слушает только `127.0.0.1`; nginx проксирует на нее запросы с `https://`. - Для экстренных случаев (неисправность nginx, ошибки DNS) можно временно открыть порт: `sudo nexcmp open-port 30` (на 30 минут, после чего он закроется автоматически) — либо использовать SSH-туннель: `ssh -L 3000:127.0.0.1:3000 ` и перейти на `http://127.0.0.1:3000/`. ::: warning Обычный HTTP Порт 3000 работает по обычному протоколу HTTP. Используйте его только для мастера первоначальной настройки в доверенной сети или через SSH-туннель. Не оставляйте его открытым. ::: ## Установка без публичного домена (лаборатория или тестирование) {#installing-without-a-public-domain-lab-or-test} Вы можете выполнить установку на сервере без настроенного DNS: ```bash curl -fsSL https://nexcmp.com/install.sh | sudo bash -s -- \ --license NXC-XXXXX-XXXXX-XXXXX-XXXXX --domain lab.example.com --no-nginx ``` Затем откройте мастер через SSH-туннель (`ssh -L 3000:127.0.0.1:3000 `, перейдите на `http://127.0.0.1:3000/setup`). Повторно запустите установщик без флага `--no-nginx`, когда DNS будет настроен. ## Docker и Kubernetes {#docker-and-kubernetes} Готовые образы контейнеров не публикуются. Поддерживаемый способ установки — инсталлятор (нативная установка systemd). ## Проверка {#verify} ```bash sudo nexcmp status ``` На экране должны отображаться версия, `nexcmp: active`, `nexcmp-vmd: active`, `healthz: ok` и — до завершения работы мастера — код первоначальной настройки. Перейдите к [мастеру первоначальной настройки](https://nexcmp.com/ru/docs/getting-started/setup-wizard/). В случае сбоя см. раздел [Ошибки при установке](https://nexcmp.com/ru/docs/troubleshooting/installation-errors/). --- # DNS и Cloudflare {#dns-and-cloudflare} NexCMP требует одно доменное имя (свой **основной домен**) и поддерживает два режима работы. ## Режим A: DNS указывает напрямую на сервер {#mode-a-dns-points-straight-at-the-server} 1. Создайте запись **A** `cloud.example.com → ` (а также запись **AAAA**, если у сервера есть IPv6). 2. При необходимости создайте `admin.cloud.example.com` и `partner.cloud.example.com`, указывающие на тот же IP-адрес. 3. Запустите (или перезапустите) [установщик](https://nexcmp.com/ru/docs/getting-started/installation/). Он определит, что имя резолвится в собственный публичный IP-адрес сервера, и получит сертификат Let's Encrypt через проверку HTTP-01 на порту 80. ## Режим B: домен проксируется через Cloudflare {#mode-b-the-domain-is-proxied-by-cloudflare} Создайте те же записи с оранжевым облаком (**Proxied**). Установщик обнаружит, что имя резолвится только в адреса Cloudflare, и переключится в режим Cloudflare: - nginx по-прежнему слушает порты 80/443 на вашем сервере; - реальный IP-адрес посетителя считывается из заголовка `CF-Connecting-IP` — **только** для подключений из опубликованных диапазонов Cloudflare, поэтому подделать его никто не сможет; - сертификат получается через Let's Encrypt (Cloudflare пересылает проверку challenge на ваш origin-сервер); если это пока невозможно, создается **самоподписанный origin-сертификат**, чтобы работал режим «Full», а повторный запуск установщика позже обновит его до Let's Encrypt. Вы можете принудительно включить этот режим с помощью `--behind-cloudflare`. ::: important Настройка режима SSL/TLS в Cloudflare В Cloudflare перейдите в **SSL/TLS › Overview** и выберите **Full (strict)**, как только установщик сообщит о получении сертификата Let's Encrypt. При использовании самоподписанного origin-сертификата выберите **Full**. Режим **Flexible** приведет к циклической переадресации. ::: ::: tip Если опция «Always Use HTTPS» включена, Cloudflare отправляет запрос валидации на порт 443 вашего origin-сервера. Установщик обрабатывает это, сначала создавая временный самоподписанный сертификат, а затем повторяя попытку получения Let's Encrypt. ::: ## Проверка {#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 ``` Сертификаты обновляются автоматически по таймеру certbot. Для обновления используется webroot `/var/www/nexcmp-acme`, поэтому порт 80 должен оставаться доступным (напрямую или через Cloudflare). ## Частые проблемы {#common-problems} | Симптом | Причина | Решение | |---|---|---| | Установщик сообщает «DNS … does not point to … (nor to Cloudflare) — skipping nginx/TLS» | DNS-запись отсутствует, указана неверно или еще не разошлась | Исправьте запись, дождитесь распространения DNS и запустите установщик снова. | | Браузер показывает `ERR_TOO_MANY_REDIRECTS` за Cloudflare | Режим SSL установлен в **Flexible** | Установите **Full (strict)** (или **Full**). | | Ошибка Cloudflare 525/526 | Origin-сертификат отклонен | Используйте **Full** с самоподписанным origin-сертификатом или **Full (strict)** с Let's Encrypt. | | В логах для всех посетителей отображаются IP-адреса Cloudflare | Режим Cloudflare не активен | Запустите установщик повторно с параметром `--behind-cloudflare`. | Подробнее в разделе [Ошибки при установке](https://nexcmp.com/ru/docs/troubleshooting/installation-errors/). --- # Мастер первоначальной настройки {#setup-wizard} > **Где найти в панели управления:** мастер представляет собой отдельную страницу `/setup`, доступную только до создания первого администратора. Затем те же проверки доступны в System › Admin › Start (`/setup`). Мастер настройки превращает чистую установку в готовую панель управления всего за четыре шага. Он работает на порту 3000 (`http://:3000/setup`) или, если TLS уже активен, по адресу `https:///setup`. ::: warning Мастер настройки исчезает после шага 3 Как только администратор создан, мастер закрывается, а код настройки удаляется. Для дальнейшего доступа к панели используйте консоль администратора. ::: ## Шаг 0 — Код настройки {#step-0-—-setup-code} В самом конце установщик выводит **одноразовый код настройки**. Его можно просмотреть снова с помощью команды: ```bash sudo nexcmp status ``` Вставьте его в поле **Setup code** и нажмите **Continue**. Код защищает мастер настройки: никто из тех, кто обнаружит открытый порт, не сможет создать администратора без него. ![Шаг 0 мастера настройки с запросом одноразового кода настройки](https://nexcmp.com/ru/docs/images/getting-started/setup-wizard-00-code.webp) ## Шаг 1 — Лицензия {#step-1-—-license} | Поле | Значение | |---|---| | Ключ лицензии | `NXC-XXXXX-XXXXX-XXXXX-XXXXX` — предварительно активируется установщиком, поэтому на этом шаге обычно отображается «Activated for cloud.example.com» | | Основной домен | Домен, зарегистрированный для лицензии | Если установщик уже активировал лицензию, мастер распознает это и перейдет к следующему шагу. В противном случае введите ключ и домен и нажмите **Activate**. Ошибки выделяются красным цветом — см. [Ошибки установки](https://nexcmp.com/ru/docs/troubleshooting/installation-errors/). ![Шаг 1 мастера настройки: лицензия уже активирована для основного домена](https://nexcmp.com/ru/docs/images/getting-started/setup-wizard-01-license.webp) ## Шаг 2 — CloudStack (или Connect later) {#step-2-—-cloudstack-or-connect-later} У вас есть два варианта: - **Подключить сейчас.** Введите CloudStack **API URL** (`https://cloudstack.example.com/client/api`), **API key** и **Secret key**, нажмите **Test connection**, затем выберите **Zone**, **гостевую сеть для клиентских ВМ**, **отображаемое имя зоны** и двухбуквенный код **Country**. Нажмите **Save CloudStack**. - **Подключить позже.** Нажмите **Connect later**. Все остальные функции продолжат работать; подключить CloudStack или Proxmox VE можно позже в разделе Infrastructure. До этого момента панель состояния будет напоминать, что ни один источник не подключен. ![Шаг 2 мастера с полями CloudStack API URL, API key и Secret key, заполненными примерами значений](https://nexcmp.com/ru/docs/images/getting-started/setup-wizard-02-cloudstack-form.webp) ::: important Используйте отдельную учетную запись CloudStack Не используйте ключ администратора ROOT. Создайте для NexCMP отдельный домен и учетную запись и используйте ее API-ключ — см. [CloudStack](https://nexcmp.com/ru/docs/infrastructure/cloudstack/#create-a-dedicated-account-and-api-key). Мастер проверяет, что выбранная сеть принадлежит этой зоне и учетной записи данного ключа. ::: ![После Test connection: списки зон и гостевых сетей, поля отображаемого имени зоны и страны](https://nexcmp.com/ru/docs/images/getting-started/setup-wizard-02b-cloudstack-picked.webp) Если вы планируете использовать только **Proxmox VE**, выберите **Connect later** и следуйте инструкциям в [Proxmox VE](https://nexcmp.com/ru/docs/infrastructure/proxmox/). ## Шаг 3 — Администратор и бренд {#step-3-—-administrator-and-brand} | Поле | Правила | |---|---| | Email администратора (логин) | Действующий адрес электронной почты. Это имя пользователя администратора. | | Пароль | Не менее 12 символов, включая буквы и цифры. | | Название бренда | Отображается вашим клиентам (по умолчанию «Cloud»). До 60 символов. | | Email службы поддержки | По умолчанию совпадает с email администратора. | ![Шаг 3 мастера с полями email администратора, пароля, названия бренда и email службы поддержки](https://nexcmp.com/ru/docs/images/getting-started/setup-wizard-03-admin.webp) Нажмите **Finish setup**. Панель перезапустится (примерно 1–2 секунды), и страница перенаправит вас на форму входа администратора по адресу `https:///admin/`. Если этот адрес пока не отвечает (ожидается настройка DNS или TLS), вы будете перенаправлены на `/` по текущему адресу. ![Мастер после завершения настройки с сообщением о перезапуске панели](https://nexcmp.com/ru/docs/images/getting-started/setup-wizard-03-done.webp) ## Что настраивает мастер {#what-the-wizard-sets-up-for-you} - Название бренда, URL сайта (`https://`), URL панели администратора (`https:///admin`), URL консоли (`https:///console`), email службы поддержки и имя отправителя. - Стандартные настройки для модулей, входящих в состав NexCMP: DDoS & BGP, AI и web SSH **отключены**, а учет трафика — **включен**. См. [Модули](https://nexcmp.com/ru/docs/infrastructure/modules/). - Если вы подключили CloudStack: провайдер № 1, его первая зона, гостевая сеть и служебная пара ключей, которая прикрепляется к клиентским ВМ для их поддержки. Далее: [Первый вход](https://nexcmp.com/ru/docs/getting-started/first-login/). --- # Первый вход и дальнейшие действия {#first-login-and-next-steps} > **Где в панели управления:** страница входа — `/admin`; после входа открывается Overview › Dashboard. ## Адреса {#addresses} | Что | URL | |---|---| | Клиентский портал | `https:///` | | Панель администратора | `https:///admin` | | Настройка / аварийный доступ по IP | `http://:3000/` (см. [порт панели](https://nexcmp.com/ru/docs/getting-started/installation/#the-panel-port-3000)) | | Проверка работоспособности | `https:///healthz` | ## Вход в систему {#sign-in} 1. Откройте `https:///admin`. 2. Введите e-mail и пароль администратора, заданные в мастере установки. 3. Вы перейдете на **Dashboard**. Если лицензия недействительна или не подключен источник, вверху появится баннер. ![Страница входа в панель администратора](https://nexcmp.com/ru/docs/images/getting-started/first-login-01-login.webp) ## Рекомендуемый чек-лист {#recommended-checklist} Выполните эти шаги по порядку — каждый ведет на соответствующую страницу. | # | Задача | Страница | |---|---|---| | 1 | Включить двухфакторную аутентификацию для своей учетной записи | [Security](https://nexcmp.com/ru/docs/administration/security/) | | 2 | Подключить источник инфраструктуры (если вы выбрали «Connect later») | [CloudStack](https://nexcmp.com/ru/docs/infrastructure/cloudstack/) или [Proxmox VE](https://nexcmp.com/ru/docs/infrastructure/proxmox/) | | 3 | Проверить зоны и шаблоны машин / список ОС | [Zones](https://nexcmp.com/ru/docs/infrastructure/zones/), [Templates](https://nexcmp.com/ru/docs/infrastructure/templates/) | | 4 | Проверить тарифные планы и цены | [Plans](https://nexcmp.com/ru/docs/catalog/plans/) | | 5 | Задать логотип, цвета и юридические страницы | [Branding](https://nexcmp.com/ru/docs/customers/branding/), [Legal](https://nexcmp.com/ru/docs/customers/legal/) | | 6 | Настроить исходящую почту и отправить тестовое письмо | [SMTP and emails](https://nexcmp.com/ru/docs/administration/smtp-and-emails/) | | 7 | Включить хотя бы один платежный канал и протестировать пополнение | [Payment channels](https://nexcmp.com/ru/docs/billing/payment-channels/) | | 8 | Выбрать, какие модули вы будете продавать | [Modules](https://nexcmp.com/ru/docs/infrastructure/modules/) | | 9 | Оформить тестовый заказ от имени клиента и удалить его | [Ordering](https://nexcmp.com/ru/docs/portal/ordering/) | | 10 | Создать первую резервную копию | [Backup and restore](https://nexcmp.com/ru/docs/getting-started/backup-and-restore/) | ## Создание первого заказа (smoke-тест) {#create-your-first-order-smoke-test} 1. Откройте клиентский портал в приватном окне и зарегистрируйте тестовый аккаунт. 2. Пополните баланс (ваучером или тестовым платежом). 3. Закажите минимальный тариф в вашей зоне. 4. Убедитесь, что заказ появился в панели администратора в Services › Virtual Machines, откройте его консоль и затем удалите его. Если виртуальная машина не переходит в статус *running*, откройте **Infrastructure › Cloud provider › Sync & errors** и посмотрите текст ошибки. --- # Обновление NexCMP {#updating-nexcmp} > **Где в панели управления:** System › Admin › License & updates (`/license`) → карточка *Update*. ## Что вы получаете {#what-you-receive} | Тип релиза | Когда предоставляется | |---|---| | Исправление безопасности | **Всегда**, даже после даты в поле «updates until» | | Релиз с новыми функциями | Только если он был опубликован **не позднее** даты в поле «updates until» | Обе даты можно посмотреть в **License & updates**. Продлить подписку можно на [nexcmp.com/licenses](https://nexcmp.com/licenses). ## Обновление через панель администратора {#update-from-the-admin-console} 1. Перейдите в **System › Admin › License & updates**. 2. В карточке **Update** нажмите **Check for update**. В карточке отображаются текущая версия, новейшая доступная для установки версия, отметка *security* (при наличии) и список изменений. 3. Нажмите **Update to X.Y.Z** и подтвердите действие. Программа скачает релиз, проверит его **подпись SHA-256 и Ed25519**, атомарно заменит исполняемый файл (сохранив копию `.bak`) и перезапустится. Время простоя составит около **10 секунд**. 4. Обновите страницу и проверьте версию в правом верхнем углу License & updates. ![Карточка Update с текущей версией и кнопкой Check for new version](https://nexcmp.com/ru/docs/images/getting-started/updating-01-card.webp) ## Обновление из командной строки {#update-from-the-command-line} ```bash sudo nexcmp update ``` При этом запускается установщик, входящий в состав *текущего установленного релиза* (а не скачиваемый в этот момент скрипт), с сохраненными параметрами из `/etc/nexcmp/install.conf`. Он обновляет исполняемый файл, юниты systemd, шаблоны nginx и агент ноды, сохраняя данные, конфигурацию и учетные записи. ::: tip Версия никогда не понижается Если сервер предлагает версию старее текущей, установщик сохраняет работающую версию. ::: ## Перед обновлением {#before-you-update} 1. Создайте резервную копию: `sudo nexcmp backup` — см. раздел [Резервное копирование и восстановление](https://nexcmp.com/ru/docs/getting-started/backup-and-restore/). 2. Ознакомьтесь со списком изменений в карточке Update. Описание изменений с версии 1.3 см. в разделе [Примечания к выпуску по 1.6.1](https://nexcmp.com/ru/docs/getting-started/release-notes/), включая обновление VPN-агента и правила тарификации Bare Metal. 3. Выполняйте обновление в период низкой нагрузки: работающие виртуальные машины не будут затронуты, но клиенты не смогут пользоваться порталом в течение нескольких секунд. ## После обновления {#after-you-update} - Выполните `sudo nexcmp status` и убедитесь, что обе службы активны. - Откройте Dashboard администратора и страницу **Needs attention**. - Миграции базы данных выполняются автоматически при первом запуске новой версии. - Если вы используете VPN-ноды, обновите их агент отдельно и проверьте учет трафика. Обновление панели делает новый агент доступным, но не гарантирует, что он уже запущен на всех удаленных нодах. См. [Лимиты трафика для VPN-нод](https://nexcmp.com/ru/docs/infrastructure/vpn-proxy-nodes/#data-allowance-on-a-vpn-node). Если обновление завершилось сбоем, см. [Ошибки обновления](https://nexcmp.com/ru/docs/troubleshooting/update-errors/). --- # Примечания к выпуску {#release-notes} > **Где найти в панели:** System › Admin › License & updates (`/license`), карточка **Update**. Эти примечания охватывают изменения после 1.3 по **NexCMP 1.6.1**. Перед обновлением создайте резервную копию и используйте релиз, предложенный в карточке **Update** вашей системы. Команды и проверку подписей см. в разделе [Обновление NexCMP](https://nexcmp.com/ru/docs/getting-started/updating/). ## 1.6.1 - **Метрики Bare Metal:** в клиентском разделе **Overview** отображаются карточки CPU, RAM, дисковой активности и сети с историей за последнее время. При отсутствии данных отображается прочерк и причина. Показания сети требуют счетчика трафика — они не считываются из инвентаря оборудования iDRAC. - **Примеры планов Bare Metal:** в названиях примеров используется `BM-40C-`. Встроенные примеры планов, которые вы не редактировали, получают нейтральные названия. Отредактированные планы сохраняются, а план, на который есть ссылки, сохраняет свой код. Проверьте фактическое оборудование сервера, прежде чем открывать план для продажи. - **Смена тарифов:** список запросов в панели администратора сортируется на сервере, а кнопки действий остаются видимыми при горизонтальной прокрутке. - **Отправка отчета об ошибке:** форма прокручивается с сохранением видимости кнопок. Маскирование паролей сохраняет окружающий диагностический текст. - **Загрузка:** ресурсы страниц и часто используемые данные панели администратора загружаются раньше, чтобы сократить задержки при переходе между разделами. См. [Настройка Bare Metal, тарификация и управление для клиентов](https://nexcmp.com/ru/docs/infrastructure/dedicated/) и [Отправка отчета об ошибке](https://nexcmp.com/ru/docs/administration/report-a-bug/). ## 1.6.0 - **Настройка Bare Metal:** укажите сети iDRAC, адрес ISO-сервера и адрес обратного вызова панели в **Safety › Management network connection**. Тестовые значения блокируют рабочие операции до завершения настройки. - **Размещение ISO:** `sudo nexcmp dedicated-setup-iso` настраивает веб-сервер ISO в сети управления. Инсталлятор может установить консоль и утилиты для работы с ISO с помощью `--baremetal` или параметров ISO. Отсутствие утилит блокирует рабочие операции с ошибкой `tools_missing`. - **Цены на Bare Metal:** в новой или неиспользовавшейся системе цены изначально заданы в USD. В системе, где уже есть данные о тарифах в VND, сохраняется валюта VND и по-прежнему требуется курс USD/VND. При обновлении эти существующие цены не пересчитываются как доллары. - **Страница сервера у клиента:** продление заранее, планирование смены расчетного периода, запрос смены тарифа, просмотр счетов и учетных данных для входа в ОС после установки. Новый владелец не может видеть пароль предыдущего владельца. - **Профили клиентов:** восемь вкладок объединяют обзор, услуги, биллинг, квоты, безопасность, поддержку, партнерскую программу и журналы. Все услуги сведены в единую таблицу с поиском и сортировкой. - **Действия с услугами:** для блокировки, разблокировки, отмены без возврата средств и отмены с возвратом используется общее диалоговое окно. Средства возвращаются на исходный кошелек или кредитный баланс; возврат через платежные системы автоматически не выполняется. См. [Выделенные серверы](https://nexcmp.com/ru/docs/infrastructure/dedicated/) и [Управление клиентами](https://nexcmp.com/ru/docs/customers/managing-customers/). Функции BYOIP и подключения клиентской подсети к серверу Bare Metal в NexCMP по-прежнему недоступны. ## 1.5.2 Главный администратор может открыть **Report a bug** рядом с **Docs** и отправить тикет в аккаунт лицензии без отдельного входа в систему. Отправка диагностических данных не обязательна. Сотрудники, клиенты и AI-ассистенты не могут отправлять отчеты через это действие. См. [Сообщение об ошибке](https://nexcmp.com/ru/docs/administration/report-a-bug/). ## 1.5.1 - **Использование VPN:** агентские узлы передают данные о трафике в панель. Подписка, исчерпавшая лимит в ГБ, отключается; она снова становится доступной после увеличения объема трафика или в начале нового расчетного периода. Узлы без отчетов об использовании отображают **Not measured** и не отключаются по лимиту ГБ. - **VPN-агент:** версия 1.5.1 повторяет отправку неподтвержденных данных об использовании, отправляет финальную статистику трафика при завершении работы и закрывает открытые соединения при остановке эндпоинта. Обновите как удаленные агенты, так и панель. - **Устаревшие дополнения VPN:** High IP Reputation, High Concurrency и High Priority Network больше не продаются. Их стоимость исключена из суммы будущих продлений существующих подписок; за прошлые периоды возврат средств не производится. Если дополнение было удалено из каталога, проверьте сумму продления вручную. - **Обозначения протоколов:** IPv4 HTTP-прокси работает по обычному HTTP. Адреса IPv4 не ротируются. Порт 443 у IPv6-прокси обслуживает SOCKS5; он не является эндпоинтом HTTPS-прокси. - **Чистая установка:** при инициализации базы данных автоматически повторяются попытки при временных конфликтах миграций между панелью и воркером, поэтому сохранение первого провайдера не требует перезапуска. См. [Узлы VPN и IPv6-прокси](https://nexcmp.com/ru/docs/infrastructure/vpn-proxy-nodes/). ## 1.5.0 **AI Models** — это дополнительный модуль шлюза и биллинга, по умолчанию отключенный. Добавьте источники моделей, которыми вы управляете или имеете право перепродавать, синхронизируйте модели, настройте цены и маршруты, включите модели и откройте продажи. Предустановленные аккаунты провайдеров, модели или цены отсутствуют. Этот модуль работает отдельно от модуля AI Chat и AI Agent. См. [AI Models](https://nexcmp.com/ru/docs/infrastructure/ai-models/). ## 1.4.2 Установка узла IPv6-прокси использует демон и сетевой скрипт, входящие в релизный пакет. Панели требуется `sshpass` для установки по SSH с аутентификацией по паролю. Панель выполняет расписание ротации, а при настройке узла адрес шлюза исключается из распределения. В брендинге можно задать собственное отображаемое имя VPN-сервиса. См. [Узлы VPN и IPv6-прокси](https://nexcmp.com/ru/docs/infrastructure/vpn-proxy-nodes/). ## 1.4.0–1.4.1 - **AI-администрирование:** доступны AI Chat администратора, персональные AI-аккаунты, API-ключи администратора, MCP-сервер администратора, коннекторы OAuth, импорт/экспорт конфигурации и чек-лист начальной настройки. См. [Настройка с помощью AI](https://nexcmp.com/ru/docs/configure-with-ai/overview/). - **Лицензирование:** рабочие процессы Free и Source включают официальные сборки и пользовательские сборки из исходного кода. Аккаунт, лицензирование, загрузки и документация используют `nexcmp.com`. См. [Лицензирование и покупка](https://nexcmp.com/ru/docs/getting-started/license-and-purchase/). - **Ссылки на документацию:** кнопка **Docs** в панели администратора открывает руководство для текущей страницы. - **Валюты:** в новой установке валюта по умолчанию определяется языком клиента. Курс USD/VND берется из общедоступной таблицы курсов валют или задается вашей фиксированной ставкой. См. [Валюта и обменные курсы](https://nexcmp.com/ru/docs/catalog/currency-and-exchange-rates/). - **Зоны со смешанными источниками:** публичные цены Cloud Server работают, когда CloudStack и Proxmox VE совместно используют одну зону. Тарифные планы используют собственный источник инфраструктуры. - **Цены на основе предложений:** процент является маржой от цены продажи. Маржа 40% при себестоимости $60 дает $100 до округления. ## Чек-лист обновления {#upgrade-checklist} 1. Создайте резервную копию, ознакомьтесь с карточкой **Update**, выполните обновление и запустите `sudo nexcmp status`. 2. Обновите VPN-агенты и убедитесь, что узлы передают данные об измеренном трафике, прежде чем полагаться на отключение по лимиту ГБ. 3. При использовании Bare Metal проверьте поля сети управления, необходимые инструменты, единицу тарификации, шаблоны и примеры тарифных планов перед открытием продаж или запуском в эксплуатацию. 4. Откройте профиль клиента и проверьте список его услуг. Проверьте сумму и исходное распределение платежа перед подтверждением отмены с возвратом средств. 5. Держите опциональные модули выключенными, пока их инфраструктура не будет готова. Для AI Models перед открытием продаж проверьте провайдера, модель с настроенной ценой и успешный тестовый запрос клиента. --- # Резервное копирование и восстановление {#backup-and-restore} > **Где найти в панели:** пункт System › Admin › Backup (`/backup`) отображается только при включенном модуле DDoS & BGP; для стандартной установки используйте командную строку ниже. ## Что входит в резервную копию {#what-is-backed-up} Команда `sudo nexcmp backup` создает один сжатый архив, содержащий: | Компонент | Содержимое | |---|---| | `data/**/*.db` | Все базы данных SQLite в `/var/lib/nexcmp`, скопированные через online backup API в SQLite — согласованы даже во время работы панели | | `files.tar` | Все остальные файлы в `/var/lib/nexcmp` (файлы настроек, загруженные элементы брендинга, `secrets/`), кроме баз данных и каталога `updates/` | | `etc/` | Копия `/etc/nexcmp` (параметры установщика, instance ID, порт и адрес привязки) | ::: warning Архив содержит ваши мастер-ключи В `secrets/` хранится ключ, шифрующий API-ключи, учетные данные платежных систем и пароли SMTP в базе данных. Архив создается с правами доступа `0600`. Храните его в зашифрованном виде вне сервера. Без этих ключей восстановленная база данных не сможет расшифровать секреты. ::: ## Создание резервной копии {#take-a-backup} ```bash sudo nexcmp backup # writes to /var/backups/nexcmp sudo nexcmp backup /mnt/nas/nexcmp # or to another directory ``` Команда выводит путь к архиву, например `/var/backups/nexcmp/nexcmp-backup-20261030-120000.tar.zst`. ### Настройка расписания {#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 ``` Скопируйте каталог за пределы сервера (в Object Storage, NAS или на другой сервер). ## Восстановление {#restore} Выполняйте восстановление на сервер, где установлена **та же (или более новая) версия** NexCMP. 1. Установите NexCMP с помощью [installer](https://nexcmp.com/ru/docs/getting-started/installation/), используя ту же лицензию и домен, но **не** запускайте мастер первоначальной настройки. 2. Остановите службы: ```bash sudo systemctl stop nexcmp-vmd nexcmp ``` 3. Распакуйте архив во временный каталог: ```bash sudo mkdir /root/restore && sudo tar --zstd -xf nexcmp-backup-20261030-120000.tar.zst -C /root/restore ``` 4. Верните файлы на место: ```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. Запустите службы и проверьте статус: ```bash sudo systemctl start nexcmp nexcmp-vmd sudo nexcmp status ``` 6. Войдите в `https:///admin` под учетной записью администратора *исходной* системы. ::: tip Отрепетируйте восстановление Выполните шаги 1–6 на резервном сервере заранее, пока не возникла экстренная ситуация. Резервная копия, которую ни разу не восстанавливали — это лишь иллюзия надежности. ::: ## Что не входит в резервную копию {#not-included} - Конфигурация nginx и сертификаты (генерируются инсталлятором заново; сертификаты Let's Encrypt запрашиваются повторно). - Ваши серверы CloudStack / Proxmox VE и виртуальные машины на них — создавайте их резервные копии штатными средствами соответствующих платформ. --- # Удаление NexCMP {#uninstall-nexcmp} ::: warning Клиенты потеряют доступ Удаление останавливает работу портала и биллинга. Виртуальные машины в CloudStack или Proxmox VE продолжат работать, но управление и тарификация прекратятся. Сначала создайте [резервную копию](https://nexcmp.com/ru/docs/getting-started/backup-and-restore/). ::: ## Удаление программы с сохранением данных {#remove-the-program-keep-the-data} ```bash sudo nexcmp uninstall ``` Эта операция отключает и удаляет службы `nexcmp` и `nexcmp-vmd`, сайт и конфигурационный фрагмент nginx, `/opt/nexcmp` и команду `nexcmp`. **Данные сохраняются** в `/var/lib/nexcmp` и `/etc/nexcmp`, поэтому последующая установка на этот же сервер продолжит работу с сохраненного состояния. ## Полное удаление {#remove-everything} ```bash sudo nexcmp uninstall --purge ``` Дополнительно удаляет `/var/lib/nexcmp`, `/etc/nexcmp`, `/var/log/nexcmp` и системного пользователя `nexcmp`. Действие необратимо. ## После удаления {#after-uninstalling} - Сертификаты Let's Encrypt и пакеты `nginx` / `certbot` остаются в системе. При необходимости удалите сертификат с помощью `sudo certbot delete --cert-name `. - Освободите привязку домена на странице лицензии [nexcmp.com/licenses](https://nexcmp.com/licenses), если планируете активировать ее на другом сервере. - Удалите выделенную учетную запись CloudStack или токен API Proxmox, созданные для NexCMP, если они больше не требуются. --- # Справочник команд `nexcmp` {#nexcmp-command-reference} Инсталлятор размещает утилиту в `/usr/local/bin/nexcmp`. Запускайте ее на сервере NexCMP. Командам, изменяющим систему, требуются права `sudo`. (Клиентская утилита для работы с API — это отдельная программа, см. [cmp CLI](https://nexcmp.com/ru/docs/developers/cmp-cli/).) | Команда | Требуется root | Назначение | |---|---|---| | `nexcmp status` | Нет (подробнее с `sudo`) | Версия, статус служб (`nexcmp`, `nexcmp-vmd`), `/healthz`, информация о лицензии, статус открытых портов, код настройки, если мастер еще не завершен | | `nexcmp update` | Да | Запускает инсталлятор из установленного релиза с сохраненными параметрами — см. [Обновление](https://nexcmp.com/ru/docs/getting-started/updating/) | | `nexcmp backup [dir]` | Да | Резервное копирование в `/var/backups/nexcmp` (или `dir`) — см. [Резервное копирование и восстановление](https://nexcmp.com/ru/docs/getting-started/backup-and-restore/) | | `nexcmp uninstall [--purge]` | Да | Удаление служб и программы; `--purge` также удаляет данные — см. [Удаление](https://nexcmp.com/ru/docs/getting-started/uninstall/) | | `nexcmp open-port [minutes]` | Да | **Аварийный режим**: прослушивание порта панели (по умолчанию 3000) на всех интерфейсах от 1 до 1440 минут (по умолчанию 30), затем автоматическое закрытие | | `nexcmp close-port` | Да | Закрыть окно аварийного доступа прямо сейчас | | `nexcmp fix-owner` | Да | Вернуть файлы в `/var/lib/nexcmp`, принадлежащие root, пользователю `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) ``` Если файлы в каталоге данных принадлежат root (например, созданы при запуске другой команды `nexcmp` с `sudo` от имени root), `status` выводит предупреждение, так как пользователь службы не может их прочитать — типичным симптомом является ошибка лицензии HTTP 421. Исправьте это с помощью `sudo nexcmp fix-owner`. То же исправление запускается автоматически при каждом старте службы. ## Аварийный доступ {#emergency-access} Если домен, nginx или TLS не работают, вы по-прежнему можете получить доступ к панели: ```bash sudo nexcmp open-port 30 # http://:3000/ for 30 minutes sudo nexcmp close-port # close it earlier ``` Более безопасный способ без открытия портов: `ssh -L 3000:127.0.0.1:3000 user@server` и открыть в браузере `http://127.0.0.1:3000/`. ## Окружение {#environment} | Переменная | Назначение | |---|---| | `NEXCMP_BASE` | Переопределение базового URL сервера лицензий (по умолчанию `https://nexcmp.com`); только для тестирования | Файлы и каталоги: программа `/opt/nexcmp`, конфигурация `/etc/nexcmp`, данные `/var/lib/nexcmp`, логи `/var/log/nexcmp` и `journalctl -u nexcmp -u nexcmp-vmd`. --- # Требования к инфраструктуре {#infrastructure-requirements} > **Где найти в панели управления:** Инфраструктура (левое меню) и System › Admin › License & updates (`/license`) для включения модулей. На этой странице перечислены внешние требования для каждого модуля **за пределами** сервера NexCMP. Требования к самому серверу (Ubuntu, память, диск, порты) см. в разделе [Требования к серверу NexCMP](https://nexcmp.com/ru/docs/getting-started/requirements/). Инструкции по включению модулей приведены в разделе [Модули](https://nexcmp.com/ru/docs/infrastructure/modules/). ## По модулям {#module-by-module} | Модуль | Минимальная инфраструктура | Подробнее | |---|---|---| | **Виртуальные машины на CloudStack** | Apache CloudStack 4.23 (протестировано), KVM, зона Advanced с гостевой сетью и диапазоном публичных IP; выделенный домен и учетная запись с ключом API (ни в коем случае не ROOT); минимум один готовый шаблон и один тарифный план (service offering) | [CloudStack](https://nexcmp.com/ru/docs/infrastructure/cloudstack/) | | **Виртуальные машины на Proxmox VE** | Proxmox VE 9.x (проверено на 9.2); токен API с пользовательской ролью; хранилище с поддержкой клонирования; сетевой мост; блок IPv4 со шлюзом; один шаблон cloud-init на каждую ОС и на каждый узел | [Proxmox VE](https://nexcmp.com/ru/docs/infrastructure/proxmox/) | | **Шаблоны ОС** | CloudStack: хост сборки на Linux с libguestfs и веб-сервер для раздачи образов. Proxmox VE: шаблоны cloud-image с guest-agent | [Шаблоны ОС](https://nexcmp.com/ru/docs/infrastructure/templates/) | | **Bare metal / Выделенный сервер** | Серверы Dell с iDRAC 9, доступные по HTTPS (Redfish) из панели через сеть управления; HTTP-сервер в этой сети для раздачи ISO-файлов; каталоги ISO с правами на запись для службы NexCMP | [Выделенные серверы](https://nexcmp.com/ru/docs/infrastructure/dedicated/) | | **AI Models** | Один или несколько источников моделей, которые вы имеете право перепродавать, с API, совместимым с OpenAI или Anthropic, и собственным ключом; исходящий HTTPS (порт 443, публичный домен) от панели к каждому источнику или внутренний шлюз из списка Allowed internal hosts; без GPU или специального оборудования | [AI Models](https://nexcmp.com/ru/docs/infrastructure/ai-models/) | | **VPN** | Один или несколько хостов Linux (x86_64, systemd, root) с публичными IPv4-адресами на интерфейсе или маршрутизируемыми на него, исходящий HTTPS к вашей панели | [Узлы VPN и прокси](https://nexcmp.com/ru/docs/infrastructure/vpn-proxy-nodes/) | | **IPv6 Proxy** | Хосты Linux (x86_64, systemd, `nft`, `ip`, `ss`, `sysctl`) со статическим публичным IPv4, свободными портами 80, 443 и 60001-65535, а также префиксом IPv6 от /32 до /64 с работающим исходящим трафиком; SSH-доступ по паролю для разовой установки | [Узлы VPN и прокси](https://nexcmp.com/ru/docs/infrastructure/vpn-proxy-nodes/) | | **Object Storage (S3)** | Кластер Ceph с RADOS Gateway (RGW), пользователем Admin Ops и публичным HTTPS-эндпоинтом на порту 443 | [S3](https://nexcmp.com/ru/docs/infrastructure/s3/) | | **Kubernetes** | CloudStack с включенным Kubernetes Service (CKS), как минимум одним ISO-образом версии Kubernetes и бесплатным сервисным предложением control-plane ровно на 2 vCPU и 2048 MB | [Kubernetes и Private Cloud](https://nexcmp.com/ru/docs/infrastructure/kubernetes-and-private-cloud/) | | **Private Cloud** | CloudStack с предложением VPC и одним сетевым предложением на каждый тариф пропускной способности (плюс заблокированное предложение на 1 Mbps) | [Kubernetes и Private Cloud](https://nexcmp.com/ru/docs/infrastructure/kubernetes-and-private-cloud/) | | **OS & ISO Images** | CloudStack, где secondary storage VM имеет доступ к Интернету для загрузки образов клиентов (прямые ссылки, без редиректов); учетная запись CloudStack может регистрировать шаблоны и ISO | [Modules](https://nexcmp.com/ru/docs/infrastructure/modules/) | | **Bandwidth** | Ничего дополнительного при использовании стандартного источника: данные считываются из статистики VM в CloudStack. Для VM на Proxmox VE учет трафика не ведется | [Bandwidth](https://nexcmp.com/ru/docs/catalog/bandwidth/) | | **AI Chat and AI Agent** | OpenAI-совместимый API (базовый URL, модель и ключ), к которому у сервера панели есть доступ. Никакого дополнительного ПО на ваших серверах | [AI-провайдеры](https://nexcmp.com/ru/docs/ai/ai-providers/) | | **DDoS & BGP** | Пакет расширения, требующий хост пограничного маршрутизатора с демонами, работающими от имени root (BGP, фильтрация, статистика потоков). Он не входит в стандартную установку | [Modules](https://nexcmp.com/ru/docs/infrastructure/modules/) | | **DDoS Shield** | Дополнение DDoS & BGP | [Modules](https://nexcmp.com/ru/docs/infrastructure/modules/) | | **Web SSH terminal** | Отдельная служба SSH-прокси и маршрут для нее. Она не входит в стандартную установку; для AI Agent она не требуется | [Modules](https://nexcmp.com/ru/docs/infrastructure/modules/) | ## Сетевые маршруты: краткий обзор {#network-paths-at-a-glance} | Откуда | Куда | Порт | Назначение | |---|---|---|---| | Сервер панели | Сервер управления CloudStack | 443 или 8080 (в зависимости от настроек публикации) | API | | Сервер панели | Узел Proxmox VE | 8006/tcp | API и консоль | | Сервер панели | Dell iDRAC | 443/tcp (и порт VNC, по умолчанию 5901) | Redfish и консоль | | iDRAC | Веб-сервер ISO | выбранный HTTP-порт (например, 8080) | Виртуальные носители | | Сервер панели | Ceph RGW | 443/tcp | Admin Ops | | Сервер панели | Узел IPv6-прокси | указанный порт SSH | Однократная установка | | Узлы VPN и прокси | Панель (через nginx) | 443/tcp | Регистрация, heartbeat, конфигурация | | Клиенты | Узлы VPN и прокси | порты 65001-65535 на IP (VPN); 80, 443, 60001-65535 (IPv6-прокси) | Сам сервис | ::: tip Изолируйте сети управления Адреса управления iDRAC и гипервизоров должны находиться в недоступной для клиентов сети. NexCMP отклоняет адреса iDRAC за пределами разрешенных вами приватных диапазонов. ::: ## Чек-лист перед запуском продаж {#checklist-before-you-sell} 1. Инфраструктура первой услуги подключена, и проверка **Test connection** прошла успешно. 2. Зона готова к продаже (см. [Zones](https://nexcmp.com/ru/docs/infrastructure/zones/)): активный бэкенд, тарифный план и готовый шаблон. 3. Настроен платежный канал (см. [Payment channels](https://nexcmp.com/ru/docs/billing/payment-channels/)). 4. Электронная почта работает (см. [SMTP and e-mails](https://nexcmp.com/ru/docs/administration/smtp-and-emails/)). 5. Вы создали один тестовый заказ и удалили виртуальную машину. --- # Архитектура {#architecture} > **Где найти в панели:** это справочная страница. Описанные службы можно проверить с помощью `sudo nexcmp status`; подключения настраиваются в Infrastructure и System › Settings. ## Схема {#the-picture} ![Архитектура NexCMP: клиенты обращаются к nginx через DNS и при необходимости Cloudflare, nginx проксирует запросы к панели на порт 3000, панель и worker обращаются к CloudStack, Proxmox VE, iDRAC, Ceph, платежным шлюзам, SMTP и AI-провайдеру, а узлы VPN и IPv6-прокси передают данные обратно в панель](https://nexcmp.com/ru/docs/images/infrastructure/architecture.svg) ### Описание схемы {#the-same-diagram-in-words} 1. Клиент или администратор открывает `https://cloud.example.com` (клиентский портал), `https://cloud.example.com/admin` (панель администратора) или вызывает REST API. DNS направляет домен на ваш сервер либо на Cloudflare, который выполняет проксирование. 2. **nginx** на сервере панели слушает порты 80 (редирект и продление сертификатов) и 443 (TLS) и перенаправляет все запросы к **panel** на `127.0.0.1:3000`. После завершения мастера первоначальной настройки панель слушает только loopback-интерфейс. 3. Служба **panel** (`nexcmp.service`) отвечает за клиентский портал, панель администратора, REST API, мастер настройки и файлы для загрузки на узлы (бинарный файл агента, скрипт установки, CLI-утилиту `cmp`). Она также проверяет лицензию раз в сутки. 4. Служба **worker** (`nexcmp-vmd.service`) слушает порт `127.0.0.1:8112` только локально. Она выполняет фоновые и периодические задачи: подготовку ресурсов, синхронизацию с CloudStack и Proxmox VE, биллинговые циклы, сбор статистики по трафику и подключения к консоли в браузере. 5. Из этих двух процессов NexCMP выполняет внешние вызовы: **CloudStack** (management API), **Proxmox VE** (API на порту 8006, pinning сертификата), **Dell iDRAC** (Redfish через HTTPS в сети управления), **Ceph RGW** (S3 и Admin Ops через HTTPS), **платежные шлюзы** (Stripe, PayPal, USDT и провайдеры банковских переводов, отправляющие вебхуки), **ваш SMTP-сервер**, **AI-провайдер** с OpenAI-совместимым API и опционально **Telegram**. 6. **Узлы VPN** работают под управлением `cmp-agent`. Каждый узел регистрируется один раз по одноразовому токену, затем каждые 5 секунд отправляет heartbeat по HTTPS в панель и получает конфигурацию в ответе. **Узлы IPv6-прокси** устанавливаются панелью один раз по SSH, после чего запрашивают свою конфигурацию у панели. 7. Состояние хранится в базах данных SQLite и нескольких файлах в каталоге `/var/lib/nexcmp`. Учетные данные CloudStack, Proxmox, S3, iDRAC и AI-провайдера хранятся в зашифрованном виде (AES-256-GCM) с мастер-ключами в том же каталоге. ## Службы и процессы {#services-and-processes} | Процесс | Пользователь | Слушает | Назначение | |---|---|---|---| | `nginx` | root (воркеры `www-data`) | 80, 443 | TLS, редирект, проксирование к панели | | `nexcmp` | `nexcmp` | 3000 (все интерфейсы при первой установке, затем `127.0.0.1`) | Портал, панель администратора, API, мастер настройки, загрузки | | `nexcmp-vmd` | `nexcmp` | `127.0.0.1:8112` | Задачи, синхронизация, биллинг, трафик, консоль | | `nexcmp-update` | root | нет | Применяет обновления по запросу панели администратора (path unit ожидает запрос) | | `cmp-agent` (на VPN-узлах) | root | порты прослушивания VPN | Передает данные в панель, запускает прокси-листенеры на публичных IPv4-адресах | Панель и воркер работают от имени обычного пользователя без каких-либо Linux capabilities, с файловой системой только для чтения, за исключением `/var/lib/nexcmp` и `/var/log/nexcmp`. Им не требуются root, Docker, отдельная база данных и Redis. ## Файлы и их расположение {#files-and-where-they-are} | Путь | Содержимое | |---|---| | `/opt/nexcmp` | Программа: релизы, `bin/`, общие файлы, такие как конструктор шаблонов. Владелец — root, для службы доступен только для чтения. | | `/etc/nexcmp` | Параметры инсталлятора (`install.conf`), порт и привязка (`nexcmp.env`). | | `/var/lib/nexcmp` | Базы данных SQLite, загруженный брендинг, каталог загрузки агента, состояние лицензии, файлы мастер-ключа. Обязательно создавайте резервную копию. | | `/var/log/nexcmp` | Логи. | См. [Резервное копирование и восстановление](https://nexcmp.com/ru/docs/getting-started/backup-and-restore/). Файлы мастер-ключа необходимо сохранять вместе с базами данных, иначе восстановленная база данных не сможет расшифровать сохраненные учетные данные. ## Кто к кому подключается {#who-connects-to-whom} | Направление | Путь | Порт | Примечания | |---|---|---|---| | От клиента к панели | Интернет, DNS, опционально Cloudflare, nginx | 443 | См. [DNS и Cloudflare](https://nexcmp.com/ru/docs/getting-started/dns-and-cloudflare/). | | От панели к серверу лицензий | `nexcmp.com` | 443 | Активация, ежедневная проверка и обновления. | | От панели к CloudStack | API | 443 или 8080 | Консоль ВМ, учет трафика и функции Kubernetes используют тот же эндпоинт. | | От панели к Proxmox VE | API и консоль WebSocket | 8006 | Сертификат зафиксирован по SHA-256. | | От панели к iDRAC | Redfish | 443, VNC 5901 | Только сеть управления. | | От iDRAC к серверу ISO | HTTP | ваш порт | iDRAC скачивает ISO. | | От панели к Ceph RGW | Admin Ops | 443 | | | От панели к SMTP | SMTP | 587 или 465 | | | От панели к AI-провайдеру | HTTPS | 443 | Только когда включен AI-модуль. | | От платежного шлюза к панели | Webhook | 443 | Обратные вызовы Stripe и PayPal. | | От узла к панели | `cmp-agent` | 443 | Регистрация, heartbeat, обновление. | | От панели к прокси-узлу IPv6 | SSH | указанный вами порт | Только при первичной установке. | ## Почему это важно {#why-it-matters} - **Доступная панель — потенциальная цель для атаки.** Держите порт 3000 закрытым после завершения работы мастера настройки. При активном TLS установщик делает это автоматически. - **Воркер должен быть запущен**, чтобы создавать ресурсы и выполнять тарификацию. `sudo nexcmp status` показывает обе службы и проверку работоспособности. - **Настройте исходящий межсетевой экран.** Если исходящий трафик сервера панели фильтруется, разрешите адреса назначения из таблицы выше. - **Трафик управления не проходит через публичную сеть.** Подключения к CloudStack, Proxmox VE, iDRAC и Ceph идут напрямую с сервера панели к этим системам, минуя nginx и Cloudflare. --- # Модули {#modules} > **В панели администратора:** System › Admin › License & updates (`/license`), карточка **Module**. ## Назначение {#what-it-does} Модуль — это сервис или функция, которую можно включить или отключить целиком. Если модуль **отключен**, он скрыт из меню администратора, и клиенты не могут его приобрести; для модулей расширения маршруты API возвращают `404 module_disabled`. Включение модуля лишь активирует функцию в интерфейсе: используемую инфраструктуру все равно необходимо подключить (см. последний столбец). ## Требования {#requirements} | Параметр | Требование | |---|---| | Учетная запись | Администратор с правами на запись. Сотрудники с доступом только для чтения видят переключатели, но не могут их изменять. | | Инфраструктура | См. таблицу: для каждого модуля указаны его требования. | | Зависимости | Некоторым модулям требуются другие (DDoS Shield требует DDoS & BGP). | ## Подготовка инфраструктуры {#prepare-the-infrastructure} Для самого переключения не требуется. Подключите инфраструктуру каждого модуля, как описано на странице по ссылке в таблице. ## Подключение в NexCMP {#connect-in-nexcmp} 1. Перейдите в **System › Admin › License & updates** и прокрутите страницу до карточки **Module**. Там указано, что отключенные модули скрыты из меню администратора и недоступны для заказа клиентами. 2. Переключите нужный модуль. На странице появится подтверждение **Saved: reloading menu**, после чего она перезагрузится, и меню сразу обновится. ![Карточка Module в License & updates с переключателем для каждого модуля](https://nexcmp.com/ru/docs/images/infrastructure/modules-01-license-modules.webp) ### Модули {#the-modules} | Модуль (в интерфейсе) | По умолчанию | Что добавляет | Требования | Страница | |---|---|---|---|---| | **Virtual Machines** | всегда включен | Каталог VM, заказы, консоль, Snapshots | CloudStack или Proxmox VE | [CloudStack](https://nexcmp.com/ru/docs/infrastructure/cloudstack/), [Proxmox VE](https://nexcmp.com/ru/docs/infrastructure/proxmox/) | | **Bandwidth** | **включен** | Квоты, дополнительные опции, оповещения и действия при перерасходе для VM, Kubernetes и S3 | Ничего дополнительно (статистика VM в CloudStack) | [Bandwidth](https://nexcmp.com/ru/docs/catalog/bandwidth/) | | **OS & ISO Images** | отключено | Клиенты регистрируют собственные образы ОС и ISO с тарификацией за ГБ | CloudStack; доступ в интернет для ее Secondary Storage VM | [Требования](https://nexcmp.com/ru/docs/infrastructure/requirements/) | | **Kubernetes** | отключено | Кластеры Kubernetes (CKS) | CloudStack с включенным CKS | [Kubernetes и Private Cloud](https://nexcmp.com/ru/docs/infrastructure/kubernetes-and-private-cloud/) | | **Private Cloud** | отключено | VPC с тарифами на выделенную полосу пропускания | CloudStack VPC и сетевые предложения | [Kubernetes и Private Cloud](https://nexcmp.com/ru/docs/infrastructure/kubernetes-and-private-cloud/) | | **Object Storage** | отключено | Аккаунты S3 на Ceph RGW, с оплатой по мере потребления | Ceph RGW и зона с сервисом S3 | [S3](https://nexcmp.com/ru/docs/infrastructure/s3/) | | **VPN** | отключено | VPN на собственных нодах | Ноды под управлением `cmp-agent` | [Узлы VPN и прокси](https://nexcmp.com/ru/docs/infrastructure/vpn-proxy-nodes/) | | **IPv6 Proxy** | отключено | IPv6-прокси на собственных нодах | Прокси-ноды с префиксом IPv6 | [Узлы VPN и прокси](https://nexcmp.com/ru/docs/infrastructure/vpn-proxy-nodes/) | | **Bare Metal** | отключено | Серверы Dell через iDRAC: заказы, установка ОС, консоль, питание | iDRAC 9 в сети управления | [Выделенные серверы](https://nexcmp.com/ru/docs/infrastructure/dedicated/) | | **AI Models** | отключено | Шлюз для продажи доступа к моделям ИИ: единый ключ для множества моделей, цены по моделям, лимиты использования, логи, биллинг через кошелек | Источники моделей с вашей стороны: API, совместимый с OpenAI или Anthropic, с собственным ключом | [AI Models](https://nexcmp.com/ru/docs/infrastructure/ai-models/) | | **AI** | отключено | AI Chat (автоматизированная поддержка) и AI Agent (администрирование VM на естественном языке) | OpenAI-совместимый провайдер | [AI-провайдеры](https://nexcmp.com/ru/docs/ai/ai-providers/) | | **DDoS Shield** | отключено | Защита IP для клиентов; требует DDoS & BGP, поэтому без него переключатель остается отключенным | Дополнение DDoS & BGP | ниже | | **DDoS & BGP** | выкл., **add-on** | Консоль пограничного маршрутизатора: BGP, RTBH, XDP, сессии и граничный трафик | Пограничный хост с демонами, работающими от root | ниже | ### За что отвечает каждый переключатель {#which-switch-does-what} - **Bare Metal** имеет два уровня. Переключатель модуля включает меню администратора и API. Продажа клиентам включается отдельным переключателем с текстовым подтверждением в **Services › Dedicated Server**, а любая запись в iDRAC заблокирована, пока вы не включите **live ops** в **Infrastructure › Bare Metal › Safety**. См. [Dedicated servers](https://nexcmp.com/ru/docs/infrastructure/dedicated/). - Для **Kubernetes**, **Private Cloud**, **VPN**, **IPv6 Proxy** и **Images** переключатель модуля и переключатель продаж на странице сервиса управляют одной и той же настройкой. - Для **AI** также требуется настроенный провайдер в **System › Settings › AI provider**. - В **AI Models** два уровня. Переключатель модуля включает меню панели управления и API. Продажа клиентам включается отдельным переключателем в верхней части страниц AI Models (по умолчанию выключен). См. [AI Models](https://nexcmp.com/ru/docs/infrastructure/ai-models/). ### Модули, считываемые при запуске {#modules-read-at-start-up} Три функции не являются обычными переключателями. Они считываются **один раз при запуске служб** и требуют инфраструктуры, не входящей в стандартную установку. | Функция | Настройка | Состояние | Что требуется | |---|---|---|---| | DDoS & BGP | `module_ddos` | Отображается как **Add-on package**, если отключено, и **Installed**, если включено. В консоли переключатель отсутствует. | Демоны пограничного маршрутизатора (BGP, RTBH, XDP, статистика потоков), работающие от root. Панель работает от непривилегированного пользователя и не может их запускать. | | AI | `module_ai` | Обычный переключатель. Маршруты применяются сразу; фоновые задачи AI Chat (анализ тикетов, запланированные ответы) запускаются при следующем перезапуске служб. В консоли отображается рекомендация перезапуска. | AI-провайдер. | | Веб-терминал SSH | `feature_ssh_web` | По умолчанию отключено, переключатель в консоли отсутствует | Отдельная служба SSH-прокси и ее маршрут. Без нее на вкладке Console в портале отображается только VNC. Для **AI Agent она не требуется**: он выполняет команды через SSH-соединение, которое панель устанавливает самостоятельно. | После изменения параметра запуска перезапустите службы: `sudo systemctl restart nexcmp nexcmp-vmd`. ## Проверка {#verify} 1. Пункт меню модуля появляется (или исчезает) после перезагрузки. 2. Для клиентского модуля на портале появляется новый пункт меню для авторизованного клиента. Отключенный модуль ничего не отображает или показывает «coming soon». ## Ограничения и примечания {#limits-and-notes} - Отключение модуля ничего не удаляет. Работающие VM, кластеры, аккаунты S3 и подписки продолжают работать и тарифицироваться; клиенты просто не могут создавать новые. - На страницах квот отображаются только те сервисы, чьи модули включены. ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | Пункт меню не появился | Страница не была перезагружена | Перезагрузите панель администратора. | | Переключатель DDoS Shield отключен | Модуль DDoS & BGP не установлен | Для DDoS Shield требуется дополнение DDoS & BGP. | | "This module is an add-on package and cannot be switched here" (HTTP 409 или 422) | Вы (или скрипт) попытались переключить DDoS & BGP | Это пакет дополнения; у него нет переключателя. | | «Для DDoS Shield требуется дополнение DDoS & BGP» | То же самое для DDoS Shield | Сначала установите дополнение. | | Модульный маршрут возвращает 404 `module_disabled` | Модуль выключен | Включите модуль. | | AI Chat отвечает, но анализ тикета не начинается | Модуль AI был включен без перезапуска | `sudo systemctl restart nexcmp nexcmp-vmd`. | | Сотрудники с доступом только для чтения не могут сохранить изменения | Их роль имеет доступ только для чтения | Используйте учетную запись администратора. | --- # Зоны {#zones} > **В панели администратора:** Infrastructure › Datacenter › Zone (`/infra/zones`). Страница сведений о зоне — `/infra/zones/`. ## Назначение {#what-it-does} **Зона** — это локация, которую клиент выбирает при заказе: страна и город с флагом, а также доступные там услуги. Это коммерческая концепция, независимая от зон, кластеров и узлов подключенных платформ. К зоне привязывается **инфраструктура**: зона CloudStack, кластер Proxmox VE, узлы VPN с диапазонами IP-адресов, хранилище S3. Зона 1 создается с помощью [мастера настройки](https://nexcmp.com/ru/docs/getting-started/setup-wizard/) с указанными вами названием и страной. Добавляйте новые зоны, если ваша инфраструктура размещена на нескольких площадках или если для VPN и S3 требуются отдельные локации. ## Требования {#requirements} | Параметр | Требование | |---|---| | Права доступа | Учетная запись администратора. Роль сотрудника с доступом только для чтения позволяет просматривать данные, но не изменять их. | | Инфраструктура | Зона ничего не продает, пока к ней не привязаны ресурсы (см. раздел «Какие услуги где продаются» ниже). | | Зависимости | [CloudStack](https://nexcmp.com/ru/docs/infrastructure/cloudstack/) или [Proxmox VE](https://nexcmp.com/ru/docs/infrastructure/proxmox/) для виртуальных машин, [узлы VPN и прокси](https://nexcmp.com/ru/docs/infrastructure/vpn-proxy-nodes/) для VPN, [S3](https://nexcmp.com/ru/docs/infrastructure/s3/) для объектного хранилища. | ## Подготовка инфраструктуры {#prepare-the-infrastructure} Не требуется. Зона — это запись внутри NexCMP. ## Подключение в NexCMP {#connect-in-nexcmp} ### Создание зоны {#create-a-zone} 1. Перейдите в **Infrastructure › Datacenter › Zone** и нажмите **Add zone**. 2. Заполните форму: | Поле | Пример значения | Примечания | |---|---|---| | Country | `United States` | Определяет флаг. | | City | `New York` | Необязательно. | | Name (Vietnamese), Name (English) | `New York` | Название, отображаемое клиентам на каждом языке. | | Slug | `us-new-york` | Символы a-z, 0-9, дефис, от 2 до 32 символов. Заполняется автоматически на основе страны и города, пока вы не введете свое значение. | | Visibility | Public | Зоны **Public** видны всем клиентам; зоны **Hidden** назначаются только администратором. | | Порядок | `0` | Меньшие номера отображаются в списках первыми. | | Услуги, продаваемые в этой зоне | Виртуальные машины (VM), VPN, Object Storage (S3) | Отметьте хотя бы одну. | | Активность | On | **Off** скрывает зону от клиентов. | | По умолчанию | отключено | Зона, предварительно выбранная для клиентов, не сделавших выбор. Зона по умолчанию может быть только одна. | ![Диалоговое окно добавления зоны со страной, городом, слагом и отмеченными услугами](https://nexcmp.com/ru/docs/images/infrastructure/zones-01-add-zone.webp) 3. Нажмите **Create zone**. В списке появится зона с ее флагом, владельцем, услугами, состоянием и количеством VM, планов и подключенной инфраструктуры. ![Список зон с зоной по умолчанию и второй зоной](https://nexcmp.com/ru/docs/images/infrastructure/zones-02-list.webp) ### Просмотр подключенных ресурсов {#look-at-what-is-attached} Нажмите на строку, чтобы открыть зону. На вкладке **Provider infrastructure** перечислены все подключенные бэкенды с указанием провайдера, типа (CloudStack или Proxmox VE), региона, состояния и приоритета. На вкладке **VPN infrastructure** указаны диапазоны VPN и узлы зоны, а также ссылки на пул VPN. ![Сведения о зоне с вкладкой Provider infrastructure](https://nexcmp.com/ru/docs/images/infrastructure/zones-03-detail.webp) ### Где продаются какие услуги {#which-service-sells-where} | Услуга | Как услуга добавляется в зону | |---|---| | Виртуальные машины на CloudStack | Мастер настройки (или **Infrastructure › Cloud provider › CloudStack**) подключает CloudStack к зоне 1. | | Виртуальные машины на Proxmox VE | На вкладке кластера **Clusters** нажмите **Attach cluster to zone**. Кластер подключается к **существующей** зоне, обычно к той, в которой продажи идут через CloudStack. | | VPN | VPN-узел, передающий свои публичные диапазоны IP, создает (или подключается к) зону для своей страны и добавляет диапазоны в пул VPN. Назначить зону и узел для диапазона можно также в разделе **VPN IP pools**. | | IPv6 Proxy | Новый узел IPv6-прокси создает зону в выключенном состоянии (**off**). Включите зону здесь, чтобы клиенты могли ее выбрать. | | Object Storage (S3) | Отметьте услугу S3 в зоне, затем подключите бэкенд в разделе **Ceph S3 (RGW)**. | ### Когда зона может продавать виртуальные машины? {#when-can-a-zone-sell-virtual-machines} У зоны отображается метка **not ready to sell VMs**, пока к ней не будет привязан хотя бы один активный доступный для продажи бэкенд **и** хотя бы один видимый тарифный план **и** хотя бы один готовый шаблон на этом бэкенде. В форме заказа клиента отображаются только готовые зоны. ## Проверка {#verify} 1. Зона отображается в списке в состоянии **On** с правильным флагом. 2. На странице сведений о зоне отображаются ожидаемый бэкенд или диапазоны VPN. 3. Для VM: метка **not ready to sell VMs** исчезла. В клиентском портале начните оформление заказа и убедитесь, что зона доступна для выбора. ## Ограничения и примечания {#limits-and-notes} - В этом релизе NexCMP клиенты заказывают виртуальные машины в **зоне по умолчанию** (зона 1). Другие зоны используются для VPN, IPv6 Proxy и Object Storage либо для подготовки локации до появления инфраструктуры; об этом же говорится в примечании под списком зон. - Зону можно удалить только тогда, когда к ней ничего не подключено: нет бэкендов, VM, планов или диапазонов VPN. Зону по умолчанию удалить нельзя: сначала назначьте по умолчанию другую зону. - Зоны, принадлежащие реселлеру, вы можете только включать или выключать, а также скрывать или отображать; остальные поля заблокированы. - Слаг входит во внутренние идентификаторы. Задайте его один раз. ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | "Имя зоны обязательно" / "Выберите страну" / "Выберите хотя бы 1 услугу" | Обязательное поле не заполнено | Укажите название, выберите страну и отметьте услугу. | | "Недопустимый slug (a-z 0-9 -, 2-32 символа)" | В слаге недопустимые символы или неподходящая длина | Используйте только строчные буквы, цифры и дефис. | | Метка "not ready to sell VMs" | В этой зоне нет активного бэкенда для продажи, тарифного плана или готового шаблона | Подключите инфраструктуру, затем добавьте план и шаблон. См. [Plans](https://nexcmp.com/ru/docs/catalog/plans/) и [Templates](https://nexcmp.com/ru/docs/infrastructure/templates/). | | Кнопка Delete неактивна с сообщением "still attached" | К зоне привязаны бэкенды, ВМ, тарифные планы или пулы VPN | Сначала удалите или переместите их. | | Кнопка Delete неактивна с сообщением "Default zone" | Зона назначена по умолчанию | Назначьте зоной по умолчанию другую зону. | | Клиенты не видят зону | Она скрыта, неактивна или для нее не выбрана ни одна услуга | Установите для Visibility значение Public, для Active — On и отметьте нужную услугу. | | Зона S3 отсутствует в форме бэкенда | Для этой зоны не отмечена услуга S3 | Откройте редактирование зоны и отметьте **Object Storage (S3)**. | --- # CloudStack > **Где найти в панели:** Infrastructure › Cloud provider › CloudStack › API connection (`/infra/cloudstack?tab=connect`). Первичное подключение также можно выполнить в [мастере настройки](https://nexcmp.com/ru/docs/getting-started/setup-wizard/), шаг 2. ## Назначение {#what-it-does} NexCMP продает виртуальные машины, работающие в вашем облаке Apache CloudStack. Платформа развертывает, запускает, останавливает, масштабирует, удаляет ВМ и создает их Snapshots через CloudStack API, выделяет публичные IP-адреса из зоны, собирает данные об использовании для биллинга и учета трафика, а также отображает емкость и статус в консоли администратора. CloudStack остается единым источником данных для гипервизоров, а NexCMP служит витриной, биллингом и клиентским порталом поверх него. Используйте этот раздел, если CloudStack является (или станет) вашей основной платформой для ВМ. Информацию о подключении второй платформы параллельно см. в разделе [Proxmox VE](https://nexcmp.com/ru/docs/infrastructure/proxmox/). ## Требования {#requirements} | Параметр | Требование | |---|---| | Версия CloudStack | Протестированная версия — 4.23. Для консоли ВМ требуется 4.18 или новее, а для динамического изменения CPU/RAM работающей ВМ — 4.23 с KVM. | | Тип зоны | Зона как минимум с одной гостевой сетью для пользовательских ВМ и диапазоном публичных IP со свободными адресами. | | Гипервизор | Протестированный гипервизор — KVM. | | Учетная запись | **Выделенный домен и аккаунт**, созданные для NexCMP. Никогда не используйте ключ администратора ROOT. | | Доступность API | Сервер панели должен иметь доступ к URL API сервера управления (`https://cloudstack.example.com/client/api`) по HTTP(S). Консоль ВМ, учет трафика и функции Kubernetes используют тот же эндпоинт. | | Дополнительный ключ только для чтения | Второй ключ с правами только на чтение позволяет консоли администратора отображать хосты, хранилища, системные ВМ и пулы публичных IP. Для продажи ВМ он не требуется. | | Публичный IP | Свободные публичные IPv4-адреса в зоне. Префикс, который разрешено продавать NexCMP, настраивается в Sales IP pools. | | Шаблоны | Как минимум один готовый шаблон с поддержкой пароля и один service offering, доступный вашему аккаунту. См. [Templates](https://nexcmp.com/ru/docs/infrastructure/templates/). | | Хранилище | Основное хранилище для томов аккаунта и, если вы продаете snapshots или образы, вторичное хранилище. | | Зависимости | Ничего. Kubernetes, Private Cloud, Images и Bandwidth зависят от этой страницы. | ::: warning Не используйте ключ администратора ROOT Создайте отдельный домен и аккаунт для NexCMP. В этом случае ключ будет иметь доступ только к этому домену, и скомпрометированный ключ не затронет остальную часть вашего облака. Мастер настройки также проверяет, что выбранная сеть принадлежит зоне **и** аккаунту, владеющему ключом. ::: ## Подготовка инфраструктуры {#prepare-the-infrastructure} В командах используется [CloudMonkey](https://cloudstack.apache.org/) (`cmk`) с авторизацией под администратором CloudStack. Замените примеры имен и плейсхолдеры в угловых скобках. ### Создайте отдельный аккаунт и API-ключ {#create-a-dedicated-account-and-api-key} 1. Создайте домен, в котором будут находиться все ресурсы NexCMP. ```bash cmk create domain name=nexcmp ``` Обратите внимание на `id` в выводе; далее это значение используется как ``. 2. Найдите роль, которую вы хотите назначить аккаунту. ```bash cmk list roles type=DomainAdmin filter=id,name ``` | Роль | Когда выбирать | |---|---| | **Domain Admin** (рекомендуется) | Полный набор функций: ВМ, сети, проекты для Kubernetes, VPC, образы. Действие роли ограничено доменом `nexcmp`. | | User | Только жизненный цикл ВМ. Обычный пользователь не может окончательно удалять (expunge) ВМ, если глобальный параметр `allow.user.expunge.recover.vm` не установлен в true; в этом случае NexCMP останавливает ВМ, а CloudStack окончательно удаляет ее по истечении `expunge.delay`. | 3. Создайте аккаунт и его первого пользователя. Используйте длинный случайный пароль — вводить его повторно не потребуется. ```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. Сгенерируйте пару API-ключей для нового пользователя. ```bash cmk list users domainid= username=nexcmp-api filter=id,username cmk generate userkeys id= ``` Скопируйте `apikey` и `secretkey`. Это **API key** и **Secret key**, которые вводятся в NexCMP. NexCMP сохраняет их в зашифрованном виде и в дальнейшем отображает только последние четыре символа. 5. Убедитесь, что для домена не заданы строгие ограничения ресурсов (instances, volumes, публичные IP, сети, snapshots, шаблоны, проекты). ```bash cmk list resourcelimits domainid= ``` ### Создайте гостевую сеть для клиентских ВМ {#create-the-guest-network-for-customer-vms} Клиентские ВМ развертываются в одной гостевой сети, принадлежащей новому аккаунту. Рекомендуется использовать изолированную сеть с виртуальным маршрутизатором (VR) и сервисами Static NAT, Firewall и Port Forwarding, поскольку NexCMP назначает каждой ВМ публичный IP с помощью статического 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= ``` Проверьте политику исходящего трафика (default egress policy) в offering: если задано «deny», у клиентских ВМ не будет доступа во внешнюю сеть, пока не добавлены правила firewall egress. ### Сделайте offerings и шаблоны видимыми {#make-offerings-and-templates-visible} - **Service offerings** и **network offerings** должны быть публичными или назначенными домену `nexcmp`, иначе аккаунт не сможет просматривать или использовать их. - Зарегистрируйте или откройте доступ как минимум к одному шаблону (см. [Templates](https://nexcmp.com/ru/docs/infrastructure/templates/)). NexCMP отображает шаблоны со статусом ready и featured. ### Необязательно: ключ только для чтения для страниц инфраструктуры {#optional-read-only-key-for-infrastructure-pages} Вкладки **Capacity**, **Host**, **Storage** и **System VM**, а также список диапазонов публичных IP используют второй ключ, которому требуется доступ только на чтение к шести командам. Создайте роль с ограниченными правами вместо использования ключа полного администратора: ```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 ``` Затем создайте аккаунт с этой ролью (в домене ROOT, поскольку он считывает данные всей зоны), сгенерируйте для него ключи, как в шаге 4, и укажите их в поле **RO API key** в следующем разделе. ### Проверьте сетевой маршрут {#check-the-network-path} С сервера панели: ```bash curl -fsS -o /dev/null -w '%{http_code}\n' https://cloudstack.example.com/client/api ``` Любой HTTP-ответ (даже 4xx) подтверждает доступность порта. Таймаут указывает на проблемы с брандмауэром или DNS на вашей стороне. ## Подключение в NexCMP {#connect-in-nexcmp} ### В мастере настройки {#in-the-setup-wizard} На шаге 2 [мастера настройки](https://nexcmp.com/ru/docs/getting-started/setup-wizard/) запрашиваются те же параметры. Нажатие **Test connection** выводит список доступных для ключа зон и сетей; выберите зону и гостевую сеть, укажите отображаемое имя зоны и страну, затем нажмите **Save CloudStack**. Мастер отклонит сеть, если она не относится к этой зоне или недоступна ключу. ![Шаг 2 мастера настройки с заполненными URL API CloudStack и ключами, а также выбранными зоной и сетью после нажатия Test connection](https://nexcmp.com/ru/docs/images/infrastructure/cloudstack-01-wizard-step.webp) ### Позже, в консоли администратора {#later-in-the-admin-console} 1. Перейдите в **Infrastructure › Cloud provider › CloudStack** и выберите вкладку **API connection**. 2. Заполните карточку **Connection**: | Поле | Пример значения | |---|---| | Endpoint API | `https://cloudstack.example.com/client/api` | | API key (доступ на запись) | `XXXX` (оставьте пустым, чтобы сохранить текущий ключ) | | Secret key | `XXXX` | | RO-ключ API / секретный RO-ключ | необязательно, из аккаунта с доступом только для чтения | | Zone ID | UUID вашей зоны | ![Вкладка API connection с примером эндпоинта и скрытыми ключами](https://nexcmp.com/ru/docs/images/infrastructure/cloudstack-02-connect-form.webp) 3. Перед сохранением нажмите **Test connection**. Это проверит введенные ключи без их сохранения: ключ с доступом на запись с помощью `listZones` и `listCapabilities`, а ключ только для чтения — с помощью `listSystemVms`. 4. Нажмите **Save connection**. Оставьте параметр **Enable CloudStack connection** включенным: при его выключении воркер останавливает все задачи CloudStack без потери данных. 5. Перейдите в **Services › Virtual Machines › Policy › Provisioning**, чтобы задать гостевую сеть по умолчанию, кастомные тарифные планы и пару ключей по умолчанию для новых VM. ![VM Policy, вкладка Provisioning с ID сети по умолчанию](https://nexcmp.com/ru/docs/images/infrastructure/cloudstack-04-provisioning.webp) 6. Перейдите в **Infrastructure › Cloud provider › Sales IP pools** и в блоке **Configure sales ranges** настройте **Sellable IP range prefixes** (например, `203.0.113.`) и **Excluded IP prefixes**, если определенные адреса в зоне нельзя продавать. Оставьте префикс пустым, чтобы разрешить продажу всех свободных адресов. ![Раздел Sales IP pools с заданным доступным для продажи префиксом 203.0.113.](https://nexcmp.com/ru/docs/images/infrastructure/cloudstack-05-sales-ip-pool.webp) ### Что NexCMP считывает и изменяет {#what-nexcmp-reads-and-writes} | Область | Чтение | Изменение | |---|---|---| | VMs | список, состояния, история использования, эндпоинт консоли | развертывание, запуск, остановка, перезагрузка, переустановка, удаление, масштабирование, сброс пароля и SSH-ключа | | Диски и Snapshots | тома, VM Snapshots, Backups | создание, подключение, отключение, изменение размера, удаление, создание Snapshots, восстановление | | Сеть | сети, маршрутизаторы, публичные IP, файрвол, проброс портов, правила балансировщика нагрузки | назначение и освобождение публичных IP, статический NAT, файрвол, проброс портов, правила исходящего трафика, сети и ACL для Private Cloud | | Каталог | сервисные, дисковые и сетевые предложения, шаблоны, ISO, типы ОС | регистрация и удаление шаблонов и ISO (Images), сервисных предложений при создании кастомных планов | | Kubernetes | поддерживаемые версии, кластеры, конфигурация | проекты, лимиты ресурсов, сети, кластеры (модуль Kubernetes) | | Ключ только для чтения | хосты, кластеры, пулы хранилищ, системные ВМ, емкость, диапазоны IP-адресов VLAN | ничего | ### Динамическое изменение CPU и RAM, а также пропускная способность {#live-cpu-and-ram-and-bandwidth} - **Hot-plug.** Изменение размера работающей ВМ без перезагрузки возможно только в том случае, если это разрешено ее шаблоном (dynamically scalable), а гостевая ОС может подключать новые CPU и RAM на лету. NexCMP включает Auto Scaling для шаблонов, имя которых оканчивается на `vN`, где N равно 6 или больше, либо когда вы задаете это вручную в поле **vCPU/RAM hot-plug** шаблона. См. [Templates](https://nexcmp.com/ru/docs/infrastructure/templates/). - **Bandwidth source.** При настройках по умолчанию NexCMP учитывает трафик по статистике ВМ в CloudStack (`listVirtualMachinesUsageHistory`, опрашивается каждые 5 минут и суммируется для каждого сетевого интерфейса ВМ). Эти значения включают трафик между ВМ, поэтому могут быть немного выше, чем на пограничном маршрутизаторе. Оставьте сбор статистики ВМ в CloudStack включенным; пропуски, превышающие срок хранения статистики, игнорируются. См. [Bandwidth](https://nexcmp.com/ru/docs/catalog/bandwidth/). ## Проверка {#verify} 1. **Test connection** возвращает «Write key: OK» с указанием вашей зоны и версии CloudStack. 2. В **Infrastructure › Cloud provider › Providers** провайдер отображается как активный со свежим временем проверки. На панели состояния дашборда больше не отображается «CloudStack: not connected». 3. В **Sales IP pools** отображается список свободных адресов (обновляется примерно раз в минуту). 4. Закажите небольшую ВМ через клиентский портал или консоль администратора и убедитесь, что она переходит в статус Running, получает публичный IP-адрес и у вас открывается консоль. ## Ограничения и примечания {#limits-and-notes} - В этой версии NexCMP можно подключить один кластер CloudStack. В диалоговом окне **Add cloud provider** можно проверить ключи второго кластера, но сохранить его нельзя. - К зоне по умолчанию в NexCMP привязывается одна зона CloudStack; если в CloudStack несколько зон, работа ограничивается указанной вами зоной, поэтому ВМ, IP-адреса и сети других зон игнорируются. - Удаление гостевой сети в CloudStack приведет к сбою всех новых развертываний. При исчезновении сети в консоли администратора появится предупреждение красного цвета. - Учетные данные никогда не покидают сервер. API возвращает только последние четыре символа. ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | `listCapabilities: cloudstack 401: unable to verify user credentials and/or request signature` | Неверный API-ключ или пароль (secret), ключ другого пользователя или рассинхронизация времени на сервере панели | Сгенерируйте ключи заново с помощью `cmk generate userkeys` и вставьте оба значения. Проверьте время на сервере панели. | | Тест: `listZones: …` или таймаут | Сервер панели не может подключиться к URL-адресу API | Проверьте DNS, фаервол и точность пути `/client/api`. | | Мастер: «network not found in that zone for this API key» | Выбранная сеть принадлежит другому аккаунту или другой зоне | Создайте сеть в выделенном аккаунте (см. выше) и снова нажмите **Test connection**. | | Мастер: «pick a zone and a network» | Тест не выполнен, либо не выбрана зона или сеть | Нажмите **Test connection** и выберите значения из обоих списков. | | Баннер «CloudStack key not configured» | Ключ еще не сохранен («Connect later») | Заполните карточку Connection, нажмите **Save connection**, затем **Test connection**. | | Баннер «CloudStack connection is OFF» | Переключатель **Enable CloudStack connection** выключен | Включите его и сохраните изменения. | | Ключ только для чтения: «unusable …» при проверке | Отсутствуют права роли или указан неверный аккаунт | Проверьте шесть разрешенных команд и убедитесь, что аккаунт находится в домене ROOT. | | «Zone public IP ranges not measured yet» или «no public IP ranges declared» | Нет ключа только для чтения или в зоне действительно нет публичного диапазона | Добавьте ключ только для чтения или добавьте диапазон публичных IP в CloudStack. | | "Пул пуст — подождите 60 с для синхронизации vmd" | Воркер обновляет список IP раз в минуту | Подождите минуту и обновите страницу. | | "Закончились свободные IP в диапазоне 203.0.113." | Все адреса в доступном для продажи префиксе заняты | Добавьте адреса в зону, расширьте префикс или освободите неиспользуемые IP. | | "Не удалось получить данные сети (CloudStack не отвечает или у ключа недостаточно прав)" | Ключ потерял доступ или CloudStack недоступен | Запустите **Test connection** и убедитесь, что аккаунт включен. | | "Гостевая сеть НЕ существует" | Сеть была удалена в CloudStack | Создайте сеть заново и установите ее по умолчанию в Provisioning. | --- # Proxmox VE > **Где в панели:** Infrastructure › Cloud provider › Providers (`/infra/providers`), затем страница провайдера (`/infra/providers/`) со вкладками Overview, Clusters, VMs, Servers и Credentials. Тарифы настраиваются в Services › Virtual Machines › Plans & pricing (`/vm/catalog`). ## Назначение {#what-it-does} NexCMP позволяет продавать виртуальные машины, работающие на одном или нескольких кластерах Proxmox VE, параллельно с CloudStack или вместо него. VM создается полным клонированием шаблона ОС (full clone), а затем настраивается через cloud-init: размер, IP-адрес из заданного вами пула, пароль root и SSH-ключ. В портале клиентам доступны управление питанием, консоль, снимки, переустановка, сброс пароля и метрики. Название кластера, ноды или источника они никогда не видят. Используйте эту возможность, если вы уже работаете с Proxmox VE или хотите предложить клиентам второй пул VM с другими ценами. ## Требования {#requirements} | Параметр | Требование | |---|---| | Proxmox VE | PVE 9.x. Интеграция проверена на 9.2. Требуются тип содержимого хранилища `import` и опция диска `import-from` (PVE 8.2 или новее). | | Сеть со стороны панели | HTTPS к API кластера, `https://:8006`. Без пути, имени пользователя или query-параметров. Подключаются как панель, так и воркер; консоль браузера проксируется через панель. | | Учетная запись | Выделенный пользователь PVE с **API token** и пользовательская роль с привилегиями, перечисленными ниже. Никогда не используйте `root@pam`. | | Хранилище | Хранилище для дисков VM с поддержкой клонирования (например, `local-lvm`). Для встроенного сборщика шаблонов — хранилище с именем `local` и типами содержимого `import` и `snippets`. | | Сеть | Linux-мост (например, `vmbr0`), имеющий доступ к сети с IP-адресами клиентов. Используйте VLAN-aware мост, если указывается VLAN-тег. | | IP-адреса | Блок IPv4 (от /16 до /30), маршрутизируемый на этот мост, со шлюзом. NexCMP назначает адреса самостоятельно; в Proxmox нет управления IP-адресами. | | Шаблоны | По одной шаблонной VM с cloud-init на каждую ОС на каждом узле, куда выполняется развертывание, с QEMU guest agent. | | Зона | Существующая зона для привязки кластера. См. [Зоны](https://nexcmp.com/ru/docs/infrastructure/zones/). | | Зависимости | Ничего. | ## Подготовка инфраструктуры {#prepare-the-infrastructure} Выполните команды от имени root на любом узле кластера. ### 1. Создайте роль, пользователя и токен API с минимальными правами {#_1-create-a-least-privilege-role-user-and-api-token} 1. Создайте роль. Список привилегий точно соответствует используемым в NexCMP; в нем нет прав на изменение пользователей, настроек хранилищ или дата-центра. ```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` требуется для скачивания cloud-image. В PVE 9 привилегии `VM.Monitor` нет, добавлять ее не нужно. 2. Создайте пользователя и токен. `--privsep 1` означает, что права токена являются **пересечением** прав пользователя и собственных прав токена. ```bash pveum user add nexcmp@pve --comment "NexCMP" pveum user token add nexcmp@pve api --privsep 1 ``` Команда выводит **секрет токена один раз** (UUID). Скопируйте его сразу. Token id — `nexcmp@pve!api`. 3. Назначьте роль **как пользователю, так и токену**. Об этом шаге часто забывают: при разделении привилегий только токен получает ошибки 403, такие как `Datastore.Audit`, если у пользователя нет прав. ```bash pveum acl modify / --roles NexCMP --users nexcmp@pve pveum acl modify / --roles NexCMP --tokens 'nexcmp@pve!api' ``` 4. Проверьте его с сервера панели: ```bash curl -sk -H 'Authorization: PVEAPIToken=nexcmp@pve!api=' https://192.0.2.10:8006/api2/json/version ``` JSON-документ с `version` означает, что токен работает. (Параметр `-k` используется только для этой быстрой проверки; NexCMP сам закрепляет сертификат, см. ниже.) ### 2. Проверьте сетевой мост и хранилище {#_2-check-the-bridge-and-the-storage} ```bash pvesm status # storages, type, content and free space ip -br link show type bridge ``` - ВМ клиентов получают сетевые интерфейсы `virtio` на сетевом мосту, указанном в NexCMP. Если вы задаете VLAN, сетевой мост должен быть VLAN-aware. - Размещайте ВМ клиентов на сетевом мосту или в VLAN, **изолированных от адреса управления узлом**. Если они находятся в общей сети, автоматический IP-набор управления брандмауэра Proxmox открывает порты узла 22, 8006, 3128, 5900-5999 и 60000-60050 для каждой ВМ в этой сети. Если их нельзя разделить, добавьте явное правило DROP для подсети ВМ к этим портам выше правила ACCEPT управления. ### 3. Примечания к хранилищу (LVM-thin) {#_3-storage-notes-lvm-thin} - Оставьте **обнуление thin-pool по умолчанию**. Его отключение (`lvchange -Zn`) может привести к сохранению старых данных в выделяемых чанках и повреждению таблиц разделов или файловых систем клонированных ВМ. - Диски, сообщающие «write cache: disabled», могут клонироваться со скоростью всего несколько МБ/с. Проверьте это с помощью `hdparm -W /dev/sdX` и включите кэш записи, если диск оснащен защитой от потери питания. ### 4. Включите тип содержимого `import` (только для встроенного конструктора шаблонов) {#_4-enable-the-import-content-only-for-the-built-in-template-builder} Встроенный конструктор загружает cloud-образ в хранилище с именем `local` и создает на его основе шаблон. Добавьте `import` (и `snippets`) в список типов содержимого этого хранилища. Сохраните типы, которые вы уже используете; команда `--content` заменяет весь список целиком: ```bash pvesm status --storage local # note the current content pvesm set local --content iso,vztmpl,backup,import,snippets ``` ### 5. Создание шаблона ОС из cloud-образа {#_5-build-an-os-template-from-a-cloud-image} Шаблон представляет собой ВМ с cloud-init, которую клонирует NexCMP. Каждый из них регистрируется под коротким **OS key**, таким как `ubuntu-24.04`, с указанием своего VM id. Создавайте по одному шаблону на каждую ОС **на каждом узле, который будет принимать ВМ**, так как клонирование выполняется на выбранном узле. **Вариант A, рекомендуемый: самостоятельная сборка.** Стандартные cloud-образы Ubuntu и Debian не содержат гостевого агента и не разрешают вход под root, а NexCMP задает пароль root через cloud-init. Сначала подготовьте образ: ```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' ``` Затем создайте шаблонную ВМ (id 9000 приведен для примера; задавайте идентификаторы шаблонов меньше значения `vmid from`, по умолчанию 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 ``` **Вариант B: встроенный конструктор.** Карточка **Create OS template from cloud image** на вкладке Clusters (см. ниже) загружает образ qcow2, собирает шаблон и регистрирует его. Она создает ВМ с cloud-init и флагом гостевого агента, но не изменяет содержимое образа. Используйте этот вариант только для образов, где уже разрешен вход под root и запущен гостевой агент, либо если вы также передаете фрагмент vendor-data для cloud-init. Гостевой агент необходим для работы **Reset password** и отображения IP-адреса ВМ. ### 6. Получение отпечатка сертификата (необязательно) {#_6-know-the-certificate-fingerprint-optional} NexCMP доверяет кластеру, закрепляя SHA-256 отпечаток его TLS-сертификата, поэтому самоподписанный сертификат вполне подойдет. Чтобы узнать значение, которое закрепит NexCMP: ```bash openssl x509 -in /etc/pve/local/pve-ssl.pem -noout -fingerprint -sha256 ``` ## Подключение в NexCMP {#connect-in-nexcmp} 1. Перейдите в **Infrastructure › Cloud provider › Providers** и нажмите **Add cloud provider**. Выберите **Proxmox VE** и заполните поля: | Поле | Пример значения | |---|---| | Name | `Proxmox cluster 1` | | Endpoint | `https://192.0.2.10:8006` | | Token id | `nexcmp@pve!api` | | Token secret | `XXXX` (UUID, выведенный на шаге 1) | | Slug | `pve-1` (a-z, 0-9, дефис, от 2 до 32 символов) | | Default node | `pve1` (пусто: нода в сети с наибольшим объемом свободной RAM) | | Хранилище | `local-lvm` | | Bridge | `vmbr0` | ![Окно Add cloud provider с выбранным Proxmox VE и примерами значений endpoint, токена и хранилища](https://nexcmp.com/ru/docs/images/infrastructure/proxmox-01-add-provider.webp) 2. Нажмите **Save & open provider** и укажите причину при появлении запроса. Токен шифруется перед сохранением. 3. На вкладке **Overview** нажмите **Test connection**. Первый успешный тест **закрепляет TLS-отпечаток кластера**; с этого момента другой сертификат будет отклоняться. 4. Откройте вкладку **Clusters**. В карточке **Node · storage · bridge** отображаются данные, полученные через API; в карточке **Cluster configuration** задаются настройки: | Поле | Значение | |---|---| | Default node | Нода для новых VM. Пустое значение означает ноду в сети с наибольшим объемом свободной RAM. | | Storage, Bridge, VLAN | Дисковое хранилище, сетевой мост (NIC bridge) и необязательный VLAN-тег (0 означает отсутствие). | | CPU type | `host` по умолчанию. Используйте `x86-64-v2-AES`, если у нод разные поколения CPU. | | vmid from | Начальный ID, присваиваемый клиентским VM (по умолчанию 1000). | | Storage ISO, Storage backup | Оставьте пустыми, если они не используются; пустое значение означает, что функции ISO и резервного копирования не предоставляются. | | Template OS | По одной записи на строку, `os-key=vmid`, например `ubuntu-24.04=9000`. | | Pinned TLS fingerprint (SHA-256) | Заполняется при первом тесте. Очистите поле и выполните повторный тест после замены сертификата кластера. | ![Вкладка Clusters, карточка Cluster configuration с примером ноды, хранилища, bridge и списка шаблонов ОС](https://nexcmp.com/ru/docs/images/infrastructure/proxmox-03-cluster-config.webp) 5. Необязательно: если вы выбрали вариант B выше, заполните **Create OS template from cloud image** (OS key `ubuntu-24.04`, vmid `9000`, нода `pve1`, URL-адрес qcow2-образа) и нажмите **Create template**. Процесс выполняется в фоновом режиме несколько минут; результат отображается в Audit log. ![Карточка Create OS template from cloud image с примером URL-адреса образа Ubuntu](https://nexcmp.com/ru/docs/images/infrastructure/proxmox-04-template-from-image.webp) 6. Нажмите **Add pool** в **Cluster IP pool** и создайте пул, из которого VM будут получать адреса: | Поле | Пример значения | |---|---| | Name | `customers-1` | | CIDR | `198.51.100.0/24` | | Gateway | `198.51.100.1` (никогда не назначается VM) | | DNS | `1.1.1.1,8.8.8.8` (от 1 до 4 адресов IPv4) | | Bridge, VLAN | `vmbr0`, `0` | | Already used IPs | по одному на строку, `ip note`, например `198.51.100.10 monitoring` | NexCMP никогда не назначает адрес сети, широковещательный адрес, шлюз или зарезервированный адрес. Пулы одного кластера не могут перекрываться. Пул можно удалить только тогда, когда ни один из его адресов не используется. ![Диалоговое окно Add IP pool с примером сети /24 и шлюза](https://nexcmp.com/ru/docs/images/infrastructure/proxmox-05-ip-pool.webp) 7. В **Attach cluster to zone** выберите зону и, при необходимости, имя ноды, затем нажмите **Attach to zone**. Кластер подключается к зоне, в которой уже продаются VM, благодаря чему в одной зоне могут сосуществовать CloudStack и Proxmox. Новый источник **по умолчанию не продается** и не меняет поведение существующих тарифов. ![Карточка Attach cluster to zone с выбранной существующей зоной](https://nexcmp.com/ru/docs/images/infrastructure/proxmox-06-attach-zone.webp) 8. Откройте **Services › Virtual Machines › Plans & pricing** и нажмите **Add plan**. В поле **Infrastructure source** выберите кластер Proxmox, затем настройте CPU, RAM, диск и цену. Для тарифа Proxmox не требуется сервисное предложение CloudStack. Чтобы продавать одну и ту же конфигурацию из обоих источников, используйте **Clone** для тарифа и выберите другой источник. Размер диска в тарифе должен быть не меньше размера диска в шаблоне: Proxmox не может уменьшать диск. ### Импорт существующей VM {#import-a-vm-that-already-exists} Откройте вкладку **Servers**, чтобы просмотреть список виртуальных машин в кластере. Действие **Import** бесплатно привязывает существующую виртуальную машину к аккаунту клиента: оплата за часы, время в выключенном состоянии или трафик не взимается. Клиент может запускать, останавливать, перезагружать ВМ и открывать консоль, но не может удалить её — это доступно только администратору. Во время импорта NexCMP выполняет только чтение данных из кластера. - Кластер должен быть привязан к зоне **с указанием имени ноды** этой виртуальной машины (если оставить имя ноды пустым, процесс импорта вернет ошибку о том, что регион не настроен). - Чтобы сделать виртуальную машину **защищенной** (остановка, перезагрузка, переустановка, восстановление из Snapshots, уничтожение и смена тарифа блокируются), импортируйте её из командной строки с помощью `--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 ``` ### Что поддерживается и не поддерживается в Proxmox {#what-is-and-is-not-supported-on-proxmox} | Функция | Proxmox VE | |---|---| | Создание, включение/выключение/перезагрузка, удаление | Да | | Изменение объема CPU и RAM, увеличение диска | Да, но ВМ останавливается, параметры изменяются, затем она запускается снова (live resize не поддерживается) | | Snapshots | Да, до 5 на одну ВМ: создание, просмотр списка, восстановление, удаление | | Переустановка | Да: ВМ пересоздается из шаблона с сохранением своего id, IP и настроек, но с новым паролем | | Сброс пароля | Да, через гостевой агент | | Консоль | Да, консоль в браузере, проксируемая панелью | | Метрики | Да: CPU, память, сеть и диск | | Монтирование ISO, Backups, firewall, IPv6, проброс портов, смена IP, дополнительные тома, Auto Scaling, DDoS Shield, VPC, учет трафика | Недоступно. На странице виртуальной машины клиента скрыты функции, которые не поддерживаются источником. | ## Проверка {#verify} 1. **Test connection** отображает OK, а статус провайдера — active. 2. В **Clusters** ваши ноды показаны со статусом online, вместе с хранилищем и сетевым мостом. 3. В **Cluster IP pool** отображается количество свободных, используемых и зарезервированных адресов. 4. После подключения кластера ключ ОС появляется в списке шаблонов зоны в **Services › Virtual Machines › Template**. 5. Закажите тестовую ВМ по тарифу, использующему этот кластер. Она должна получить адрес из пула, пароль root и рабочую консоль, а в пуле один адрес должен отображаться как занятый. ## Ограничения и примечания {#limits-and-notes} ::: tip Зоны со смешанными источниками Начиная с NexCMP 1.4.0 публичный прайс-лист Cloud Server работает и тогда, когда CloudStack и Proxmox VE используют одну общую зону. В каждом тарифе используется собственный **Infrastructure source**. После подключения кластера проверьте публичный прайс-лист и оформите тестовый заказ для каждого источника. ::: - Можно добавить несколько кластеров Proxmox. Каждый из них выступает как отдельный провайдер. - Зона предоставляет один источник по умолчанию; тариф с собственной настройкой **Infrastructure source** развертывается именно в этом кластере, если он активен и относится к зоне тарифа. - Кластер, находящийся в той же зоне, что и CloudStack, сохраняет свои существующие тарифы на CloudStack. Перед запуском протестируйте полный цикл заказа. - Токен API можно только заменить, просмотреть его нельзя. Замените его на вкладке **Credentials**: сначала создайте новый токен в Proxmox, укажите его, нажмите **Test connection** и затем отзовите старый токен. - Действия Test, Sync и cluster-info ограничены шестью вызовами в минуту на одного администратора. - NexCMP выставляет счета вашим клиентам; расходы на оборудование и лицензии кластера вы несете самостоятельно. ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | Test: "Key rejected (wrong access key / secret, or revoked)" или HTTP 401/403 | Неверный token id или secret, либо права ACL были назначены только токену | Повторно выполните обе команды `pveum acl modify` (пользователь **и** токен) и проверьте, что token id — `user@realm!tokenid`. | | Тест: "Could not connect to the provider" или "Timed out" | Файрвол, неверный хост или порт | Проверьте `https://host:8006` с сервера панели. | | Тест: "Invalid endpoint or not on the allowlist" | Эндпоинт содержит путь, имя пользователя, параметры запроса или не использует HTTPS | Используйте в точности `https://host:8006`. | | "TLS-сертификат кластера НЕ соответствует привязанному отпечатку" | Сертификат кластера был заменен | Очистите **Pinned TLS fingerprint** на вкладке Clusters, сохраните и снова выполните **Test connection**. | | Slug отклонен | Содержит символы помимо a-z, 0-9, дефиса или длина не от 2 до 32 символов | Используйте значение вида `pve-1`. | | "Формат Token id: user@realm!tokenid, и требуется secret" | Отсутствует token id или secret | Укажите оба значения; secret — это UUID, отображаемый при создании токена. | | "Недопустимая строка шаблона: …" | Строка в **Template OS** не соответствует `key=vmid` | Используйте буквы, цифры, `.`, `_`, `-` в ключе и vmid не менее 100. | | "OS key: a-z 0-9 . _ - и vmid ≥ 100" | Неверный ключ или id в **Create template** | Исправьте ключ ОС и используйте свободный vmid. | | "vmid … already exists" при создании шаблона | vmid уже занят | Выберите другой id. | | "url указывает на внутренний адрес" | URL образа указывает на внутренний IP-адрес | Используйте публичный URL; разрешение доменных имен выполняется Proxmox. | | Сбой задачи шаблона при скачивании | В хранилище `local` не включен тип содержимого `import` | `pvesm set local --content …,import,snippets`, затем повторите попытку. Имя файла должно оканчиваться на `.qcow2`, `.raw`, `.vmdk`, `.ova` или `.ovf`. | | "cluster has no online nodes" или "node … is not online" | Узел по умолчанию недоступен или указан с ошибкой | Исправьте **Default node** или оставьте поле пустым. | | "образ не принадлежит кластеру" | ОС тарифного плана отсутствует в **Template OS** | Добавьте ключ в список и сохраните. | | Развертывание ожидает, затем завершается сбоем при клонировании | ВМ шаблона находится не на выбранном узле | Создайте шаблон на этом узле или укажите в **Default node** узел, на котором он находится. | | Клиент не может войти под пользователем root | Образ блокирует вход под root | Пересоберите шаблон, как описано в Option A. | | Сброс пароля не дает результата | В гостевой ОС не установлен guest agent | Установите и включите `qemu-guest-agent` в шаблоне. | | «Имя, CIDR и шлюз обязательны» | Не заполнено обязательное поле пула | Заполните все три поля. | | Создание пула: "overlaps with pool …", "gateway must be within range (not network/broadcast address)" или "cidr: network address must be …" | Пересечение пулов, неверный шлюз или CIDR не на границе сети | Используйте свободный диапазон, шлюз внутри него и CIDR, указанный как сетевой адрес (например, `198.51.100.0/24`). | | Импорт: "region is not set up" | Кластер подключен без имени узла VM | Подключите кластер к зоне с указанием имени узла. | --- # Шаблоны ОС и ISO-образы {#os-templates-and-isos} > **В панели управления:** Services › Virtual Machines › Template (`/vm/templates`). Шаблоны Proxmox отображаются для каждого кластера в Infrastructure › Cloud provider › Providers › (cluster) › Clusters. ## Назначение {#what-it-does} Шаблон — это образ операционной системы, из которого развертывается новая VM. NexCMP не хранит образы самостоятельно: система считывает данные из CloudStack (готовые шаблоны из категории featured) или список из кластера Proxmox и позволяет выбрать, какие из них предлагать клиентам, задав отображаемое имя, иконку и имя пользователя. На этой странице описано, как подготовить образы для корректной работы с NexCMP: вход по паролю, горячее масштабирование CPU и RAM, swap-файл и автоматическое расширение корневого диска до размера тарифа. ## Требования {#requirements} | Параметр | Требование | |---|---| | Сборщик шаблонов CloudStack | Машина под управлением Linux с `libguestfs-tools` (`virt-customize`, `virt-sparsify`, `guestfish`), `qemu-utils`, `curl` и около 5 GB свободного места на диске. KVM и права root не требуются. Необходим доступ в интернет для установки пакетов (или сборка с флагом `--offline`). | | Где находится сборщик | Поставляется с каждым релизом в `/opt/nexcmp/releases//share/templates/` на сервере панели. Запускать его именно там необязательно: каталог можно скопировать на любую Linux-машину. | | Веб-сервер | Любой HTTP(S)-сервер, доступный виртуальной машине вторичного хранилища CloudStack, для публикации готового файла `.qcow2`. Доступ из интернета не требуется. | | CloudStack | Учетная запись с правами регистрации шаблонов, а также ID вашей зоны и соответствующего типа ОС. См. [CloudStack](https://nexcmp.com/ru/docs/infrastructure/cloudstack/). | | Proxmox VE | Шаблонные VM cloud-init с QEMU guest agent, по одной на каждую ОС и узел. См. [Proxmox VE](https://nexcmp.com/ru/docs/infrastructure/proxmox/). | | Зависимости | Предварительно подключенный [CloudStack](https://nexcmp.com/ru/docs/infrastructure/cloudstack/) или [Proxmox VE](https://nexcmp.com/ru/docs/infrastructure/proxmox/). | ## Подготовка инфраструктуры {#prepare-the-infrastructure} ### CloudStack: сборка шаблона {#cloudstack-build-a-template} Поддерживаемые базовые образы (образ загружается от поставщика с проверкой контрольной суммы до внесения каких-либо изменений): | Образ | `--distro` | Имя пользователя | |---|---|---| | 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` | Другие дистрибутивы: добавьте строку в `distros.conf` (URL образа, файл контрольной суммы, семейство `deb` или `rpm`). 1. Скопируйте сборщик на сборочную машину и запустите его: ```bash cp -r /opt/nexcmp/releases//share/templates ~/templates && cd ~/templates ./build-template.sh --distro ubuntu-24.04 --version v7 --work ./out ``` Добавьте `--panel-url https://cloud.example.com`, чтобы встроить опциональный агент мониторинга при первой загрузке, регистрирующийся в вашей панели (только HTTPS). Без него агент не добавляется. Другие параметры: `--base ` для использования заранее скачанного образа, `--offline` для пропуска установки пакетов. 2. В результате создаются `out/ubuntu-24.04-v7.qcow2` и его `.sha256`. Сборка завершается запуском `verify-image.sh`, который проверяет готовый образ в режиме «только чтение» и отклоняет некорректный (он сохраняется как `.unverified`). Проверку можно перезапустить в любой момент: `./verify-image.sh out/ubuntu-24.04-v7.qcow2 --no-agent`. Что сборщик добавляет в образ: | Параметр | Назначение | |---|---| | `qemu-guest-agent` | CloudStack может запрашивать у ВМ данные о процессорах и IP-адресах, а также переводить ее в согласованное состояние для Snapshots. | | cloud-init с источником данных CloudStack, `set_passwords` при каждой загрузке, вход по SSH по паролю | Сгенерированный пароль запрашивается из виртуального маршрутизатора, и функция **Reset password** работает. | | Правило udev для горячего подключения CPU и RAM | Горячеподключенные vCPU и RAM подключаются автоматически, поэтому динамическое масштабирование и Auto Scaling работают. | | Служба файла подкачки | Создает `/swapfile` размером в меньшее из двух значений: 50% RAM или 4 GiB после расширения диска. `touch /etc/cmp-swap.disabled` отключает его. | | cloud-init `growpart` и `resizefs` | Небольшой корневой диск расширяется до размера диска по тарифу при первой загрузке. | | Пустой machine-id, отсутствие хостовых ключей SSH | Каждая ВМ получает собственный уникальный идентификатор. | ::: warning Назовите шаблон ` ` NexCMP включает **Auto Scaling** для шаблонов, имя которых оканчивается на `vN` или `vN.M` с **N от 6 и выше** (`Ubuntu 24.04 v7`, `Rocky Linux 9 v7.1`). Сборщик применяет это правило для `--version`. Зарегистрируйте шаблон в точности с выведенным именем. ::: 3. Опубликуйте файл и зарегистрируйте его в CloudStack. Используйте выведенный сборщиком хэш SHA-256 и регистрируйте шаблон только после полной записи файла: ```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` позволяет CloudStack генерировать пароль ВМ. - `isdynamicallyscalable=true` разрешает динамическое масштабирование. - `host-passthrough` требуется для загрузки актуальных образов Rocky и Alma; `osdefault` обеспечивает переносимость дискового контроллера. 4. Дождитесь, пока статус шаблона не сменится на **Download Complete / Ready**. Образ поставщика сохраняет небольшой виртуальный размер (около 3.5 GiB для Ubuntu и Debian, 10 GiB для Rocky). Помните, что диск в тарифном плане не может быть меньше диска шаблона. ### Proxmox VE: создание шаблона {#proxmox-ve-make-a-template} Соберите шаблон ВМ с cloud-init для каждой ОС на каждом целевом узле развертывания, установив гостевой агент и включив вход для root, затем зарегистрируйте его как `os-key=vmid`. Все команды приведены в [Proxmox VE](https://nexcmp.com/ru/docs/infrastructure/proxmox/). Описанный выше сборщик для CloudStack **не предназначен** для Proxmox: он настраивает cloud-init под источник данных CloudStack. ### ISO-образы {#isos} Клиенты подключают собственные ISO-образы через модуль **Images** (CloudStack) или модуль Dedicated Server. Они не связаны с шаблонами ОС, описанными на этой странице. См. [Модули](https://nexcmp.com/ru/docs/infrastructure/modules/) и [Выделенные серверы](https://nexcmp.com/ru/docs/infrastructure/dedicated/). ## Подключение в NexCMP {#connect-in-nexcmp} 1. Откройте **Services › Virtual Machines › Template**. Нажмите **Sync now** или подождите до 15 минут. Синхронизация добавит готовые (ready) и рекомендованные (featured) в CloudStack шаблоны. ![Страница Template со списком синхронизированных шаблонов, их состоянием готовности и столбцом горячего подключения CPU](https://nexcmp.com/ru/docs/images/infrastructure/templates-01-list.webp) 2. Нажмите **Edit** для нового шаблона и настройте параметры, которые увидят клиенты: | Поле | Пример значения | |---|---| | Отображаемое имя для клиентов | `Ubuntu 24.04 LTS` | | Семейство ОС | `ubuntu` (значок и пользователь по умолчанию) | | Версия | `24.04` | | Имя пользователя для входа | `ubuntu` (для Windows: `Administrator`; для остальных: `root`) | | Значок | URL изображения, путь или имя | | Порядок | `10` | | Активность | On | | Горячее подключение vCPU/RAM (live scale) | **Auto by name (v6 or later)**, **Yes** или **No (needs a restart)** | ![Диалоговое окно Edit template с отображаемым для клиентов именем, семейством ОС, именем пользователя для входа и параметром горячего подключения](https://nexcmp.com/ru/docs/images/infrastructure/templates-02-edit.webp) 3. Включите шаблон. Шаблон, который больше не отображается в CloudStack, скрывается автоматически (при соответствующей настройке вы получите оповещение в Telegram); он никогда не удаляется из NexCMP. ### Замена шаблона на более новую сборку {#replace-a-template-with-a-newer-build} Используйте **More › Replace with new version** для продаваемого шаблона. Выберите новый, готовый и отключенный в данный момент шаблон. После этого продаваемая запись начнет указывать на новую сборку, сохранив свое имя, порядок и иконку; старая запись отключается для возможности отката (для возврата используйте **Replace** в новой записи). Работающие VM затронуты не будут. Если новая сборка относится к другому семейству ОС, сначала установите флажок подтверждения. ## Проверка {#verify} 1. В строке отображается **ready** и, для сборок с именем `vN`, где N равно 6 или больше, **CPU hot-plug: supported**. 2. Разверните одну тестовую VM из шаблона и проверьте внутри нее: - можно войти с паролем, указанным в портале; - `df -h /` показывает размер диска по тарифу; - после масштабирования на лету (**Change plan** без перезагрузки) значения `nproc` и `free -m` увеличиваются; - `swapon --show` выводит `/swapfile` (диски, где свободно меньше swap плюс 2 GiB, пропускают его); - `systemctl is-active qemu-guest-agent` выводит `active`. 3. Если вы встроили агент в образ, VM появится в списке мониторинга панели через минуту после первой загрузки. У VM должен быть собственный публичный IP: панель распознает ее по исходящему публичному IP. ## Ограничения и примечания {#limits-and-notes} - Сборщик работает только в Linux и собирает образы Linux. Другие образы (например, Windows) можно зарегистрировать в CloudStack другими способами; NexCMP отображает то, что передает CloudStack. - Поставляется только агент для amd64; на других архитектурах установка агента пропускается. - Образ проверяется с помощью `guestfish`, но сборщик никогда его не загружает. Всегда развертывайте одну тестовую VM перед продажей нового образа. - Пропустите установку агента на одной VM с помощью `touch /etc/cmp-agent.disabled` перед первой загрузкой. Удалите его позже командой `systemctl disable --now cmp-agent cmp-agent-install; rm -rf /etc/cmp-agent /usr/local/bin/cmp-agent`, затем удалите агент в консоли администратора. ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | `virt-customize` не удается загрузить пакеты | У сборочной машины нет исходящего сетевого подключения | Настройте DNS или прокси на этой машине либо выполните сборку с `--offline` на базовом образе, где пакеты уже установлены. | | `libguestfs: error: /usr/bin/supermin exited with error status 1` | Ядро хоста недоступно для чтения текущему пользователю (Ubuntu) | `sudo chmod +r /boot/vmlinuz*` или запустите сборку от имени root. | | Контрольная сумма не совпадает или образ вендора больше не существует | Вендоры перемещают файлы «latest» | Скачайте образ самостоятельно, сверьте его с файлом контрольной суммы вендора и передайте через `--base`. | | Rocky: невозможно смонтировать более новую версию XFS | Слишком старое ядро хоста | Выполните сборку на машине с актуальным ядром. | | `--version must be v6 or higher` | Имя должно иметь вид `vN`, где N равно 6 или больше | Используйте `--version v7`. | | `--panel-url must be a plain https:// URL` | Агент скачивается и запускается от root, поэтому обычный HTTP отклоняется | Используйте URL `https://` без пробелов, кавычек или строки параметров. | | Шаблон остается в статусе **not ready** | CloudStack еще не завершил загрузку | Дождитесь **Download Complete** и проверьте, доступен ли URL с secondary storage VM. | | В строке отображается **no-pass** | Шаблон был зарегистрирован без `passwordenabled=true` | Зарегистрируйте его заново с этим флагом. | | Для CPU hot-plug отображается **unsupported** | Имя не заканчивается на `vN` (где N равно 6 или больше) | Переименуйте шаблон или установите **vCPU/RAM hot-plug** в **Yes** в меню Edit, если в образе настроено правило udev. | | «Empty template list» после первого подключения | Синхронизация еще не выполнялась | Нажмите **Sync now** (требуется работающий worker) или дождитесь 15-минутного цикла. | --- # Выделенные серверы (bare metal) {#dedicated-servers-bare-metal} > **Раздел в панели управления:** Infrastructure › Bare Metal (Servers `/infra/baremetal`, IP Pools, Stock / iDRAC import, Operations, Templates, Customer ISOs, Safety). Тарифы и подписки: Services › Dedicated Server (`/dedicated`). Включите модуль в разделе System › Admin › License & updates (`/license`). ## Назначение {#what-it-does} NexCMP управляет физическими серверами **напрямую через iDRAC** по Redfish API. Клиенты арендуют сервер целиком: включают и выключают питание, открывают веб-консоль, монтируют ISO или устанавливают операционную систему из шаблона, а также просматривают сведения об оборудовании и метрики. При этом адрес, имя пользователя и пароль iDRAC клиентам никогда не раскрываются. Используйте модуль для перепродажи выделенных серверов из собственных стоек. ## Требования {#requirements} | Параметр | Требование | |---|---| | Оборудование | Серверы Dell с **iDRAC 9** и Redfish API. | | Сеть управления | **Предоставляется вами.** Сервер панели должен иметь доступ к каждому iDRAC по порту **HTTPS 443** (а также к VNC-порту iDRAC, по умолчанию **5901**, для консоли), а каждый iDRAC должен иметь доступ к указанному ниже веб-серверу ISO. Адрес iDRAC должен быть **IPv4-адресом из частного диапазона** (RFC 1918, префикс /16 или меньше), который вы указываете в настройке `dedicated_bmc_cidrs`. DNS-имена и IPv6 не принимаются. NexCMP не создает эту сеть и не может проверить ее за вас. | | Учетная запись iDRAC | Одна учетная запись с привилегиями **Administrator** на каждом iDRAC. NexCMP использует ее для считывания данных сервера и отправки разрешенных команд (питание, виртуальные носители, однократная загрузка, консоль). NexCMP никогда не создает учетные записи iDRAC для ваших клиентов. | | Утилиты на сервере панели | `xorriso` и `genisoimage` (собирают установочный ISO каждого сервера) и `novnc` (страница консоли в браузере). Установите их с помощью `sudo apt-get install -y xorriso genisoimage novnc` или доверьте это установщику: запустите его с `--baremetal` либо передайте ему параметры ISO-сервера; обновление также устанавливает их, если модуль Bare Metal уже включен. Если какая-либо утилита отсутствует, во вкладке **Safety** появится красное предупреждение, переключатель **live ops** не включится (ошибка `tools_missing`), а консоль и установка ОС сообщат об отсутствующей утилите вместо сбоя на более позднем этапе. | | Веб-сервер ISO | Обычный сервер **HTTP** в сети управления, раздающий папку ISO NexCMP для iDRAC. Его адресом является частный IPv4-адрес и опциональный порт, например `http://10.20.0.2:8080`, **без пути**, сохраненный в `dedicated_iso_base_url`. Он должен поддерживать диапазоны байтов (byte ranges). Запись в папку выполняет воркер панели, поэтому веб-сервер обычно работает на **самом сервере панели**, прослушивая адрес этого сервера в сети управления. В комплект поставки NexCMP входит готовый сайт nginx и команда в один шаг для его настройки (см. ниже). | | Папки ISO | Папка для ISO-файлов и находящиеся внутри нее `pub` (то, что считывают iDRAC) и `server` (пользовательские ISO). Одношаговая команда использует `/srv/nexcmp-iso`; без нее применяются значения по умолчанию после установки (настройки `dedicated_iso_lib_dir`, `dedicated_iso_pub_dir`, `dedicated_iso_server_dir`). Воркер NexCMP должен иметь права на **запись** в них. Он работает с файловой системой только для чтения, за исключением `/var/lib/nexcmp`, поэтому для папки в другом месте требуется systemd drop-in (одношаговая команда устанавливает его). | | Callback-адрес | `dedicated_callback_base` — `https://`, доступный с устанавливаемого сервера и указывающий на вашу панель. | | Хранилище | Свободное место на диске для библиотеки ISO и пользовательских ISO-образов. | | Зависимости | Модуль **Bare Metal**, зона и IP-пулы серверов. | ::: warning Примеры значений — это не конфигурация При чистой установке параметры `dedicated_bmc_cidrs`, `dedicated_iso_base_url` и `dedicated_callback_base` содержат примеры значений (тестовая частная сеть и `https://example.com`). Они не относятся к вашей сети. Пока хотя бы один из них содержит пример значения, на страницах Bare Metal отображается красное уведомление **Management network not configured**, импорт iDRAC не проходит проверку разрешенных списков, а переключатель **live ops** отказывается включаться (ошибка `config_placeholder`). Задайте эти три значения в разделе **Infrastructure › Bare Metal › Safety › Management network connection** (см. ниже). ::: ## Подготовка инфраструктуры {#prepare-the-infrastructure} 1. **Поместите каждый iDRAC в сеть управления**, недоступную для клиентов, и назначьте каждому фиксированный частный IPv4-адрес. Проверьте Redfish API с сервера панели: ```bash curl -sk -u 'nexcmp-admin:XXXX' https://10.20.0.11/redfish/v1/Systems | head ``` 2. **Создайте учетную запись администратора на iDRAC** для NexCMP (через веб-интерфейс iDRAC или `racadm`). Используйте надежный уникальный пароль. Никогда не используйте встроенную учетную запись iDRAC. 3. **Публикация папки ISO для iDRAC в одну команду.** На сервере панели от имени root с указанием адреса этого сервера в сети управления и сети iDRAC: ```bash sudo nexcmp dedicated-setup-iso --listen 10.20.0.2:8080 --allow 10.20.0.0/24 ``` `--listen` должен быть адресом этого сервера (частный IPv4, порт 8080 по умолчанию). В `--allow` указываются сети iDRAC (частные CIDR, /16 или меньше, до 8 через запятую); только они смогут выполнять скачивание, и команда также запишет их в `dedicated_bmc_cidrs`, если в этой настройке все еще указан пример значения. `--dir /path` позволяет выбрать другую папку ISO (по умолчанию `/srv/nexcmp-iso`). Команда: - создает папку с подпапками `pub` и `server` внутри, владельцем которых становится сервисный пользователь NexCMP; - создает группу `nexcmp-iso` и добавляет в нее пользователя nginx, чтобы nginx мог читать ISO, пока тот подключен к iDRAC, и доступ был закрыт для всех остальных; - устанавливает сайт nginx `nexcmp-iso` (сохраняется, только если `nginx -t` принимает его; если nginx отсутствует, он будет установлен) и systemd drop-in `nexcmp-vmd.service.d/iso.conf` (`ReadWritePaths` для папки, `SupplementaryGroups=nexcmp-iso`); - записывает настройки ISO (`dedicated_iso_base_url`, три папки, группу) и перезапускает воркер NexCMP. Ее можно запускать повторно с другими значениями, а флаг `sudo nexcmp dedicated-setup-iso --remove` удаляет сайт nginx и drop-in (файлы ISO сохраняются). Команду также можно выполнить во время установки: добавьте `--iso-listen`, `--iso-allow` (и `--iso-dir`) к команде установки. Команда **не** создает сеть управления и не обращается к iDRAC; если значения неверны, адрес не принадлежит этому серверу или порт занят, она завершает работу с сообщением об ошибке до внесения изменений, а сайт nginx, отклоненный `nginx -t`, не сохраняется. 4. **Что раздает веб-сервер ISO.** Сайт nginx отвечает на запросы `GET` (и `HEAD`, с диапазонами байтов) для `/pub/.iso` и больше ни на что: листинг директорий отключен, другие пути внутри каталога недоступны (библиотека и `server/` недосягаемы), другие методы запрещены, а доступ открыт только из сетей `--allow` (остальные получают 403). NexCMP предоставляет каждый ISO-образ, который должен прочитать iDRAC, как файл или временную ссылку в `pub`; nginx переходит по ссылке, только если у ссылки и её цели один и тот же владелец (сервисный пользователь), поэтому ссылка на системный файл отклоняется. Проверьте это с другого хоста в сети управления: ```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 ``` Тестовый файл в `pub` должен отвечать на запрос `Range` кодом 206. *Если настраивать вручную:* конфигурация сайта nginx и дроп-ин поставляются как шаблоны в релизном пакете (`share/dedicated/nginx-iso.conf` и `share/dedicated/vmd-iso.conf` в каталоге `/opt/nexcmp/releases//`). Скопируйте их, замените маркеры `__...__` (listen address, folder, строки allow, group) и сохраните указанные выше правила. 5. **Подготовьте образы ОС.** Поместите ISO-образы с автоустановкой в папку библиотеки (см. **Templates** ниже). Клиенты также могут добавлять ISO по ссылке; они скачиваются на сервер и никогда не передаются в iDRAC в виде URL. ## Подключение в NexCMP {#connect-in-nexcmp} ### 1. Включите модуль {#_1-turn-the-module-on} В разделе **System › Admin › License & updates** включите переключатель **Bare Metal**. Категория **Bare Metal** появится в меню Infrastructure. См. [Modules](https://nexcmp.com/ru/docs/infrastructure/modules/). ### 2. Настройка подключения к сети управления {#_2-set-the-management-network-connection} Откройте **Infrastructure › Bare Metal › Safety**. В карточке **Management network connection** задаются три значения, от которых зависит работоспособность всей системы: | Поле | Настройка | Что указать | |---|---|---| | Сеть iDRAC (CIDR) | `dedicated_bmc_cidrs` | Приватные сети ваших iDRAC, например `10.20.0.0/24`. Только частные CIDR размером /16 или меньше, до 8 диапазонов через запятую. Импортировать можно только iDRAC из этих диапазонов. | | ISO-сервер для iDRAC | `dedicated_iso_base_url` | `http://[:port]`, без пути: адрес веб-сервера ISO из предыдущего раздела, например `http://10.20.0.2:8080`. Автоматическая команда заполнит его за вас. | | Callback-адрес панели | `dedicated_callback_base` | `https://`, без пути: адрес, к которому обращается устанавливаемый сервер для отчета о завершении. Он должен быть доступен из сети этого сервера. Значения вроде `example.com`, `localhost` и аналогичные не принимаются. | Форма проверяет формат по мере ввода, а сервер повторно проверяет его при сохранении; некорректное значение отклоняется с указанием причины, а сохраненное значение остается прежним. Поле, содержащее шаблонное значение по умолчанию, помечается красной меткой **Not configured**, а на каждой странице Bare Metal отображается красное уведомление **Management network not configured**, пока все три параметра не будут заданы корректно. Изменения записываются в журнал аудита вместе с указанной вами причиной. Повторное сохранение шаблонного значения не считается настройкой, если только вы не ввели его вручную. ### 3. Проверка защитного шлюза (пока оставьте его закрытым) {#_3-check-the-safety-gate-leave-it-closed-for-now} Откройте **Infrastructure › Bare Metal › Safety**. **Live ops** — это глобальный переключатель для всех команд записи в iDRAC (питание, виртуальные носители, консоль и установка ОС). Изначально он **выключен**, и его нельзя включить, пока в параметрах подключения к сети управления остаются шаблонные значения (переключатель возвращает `config_placeholder` и перечисляет незаполненные поля). Операции записи отклоняются на уровне API и внутри воркера, тогда как чтение статуса продолжает работать. Вторая блокировка, **ops_locked**, защищает каждый отдельный сервер: вновь импортированные серверы всегда заблокированы, даже если live ops включен. ![Страница Safety с выключенным Live ops и списком заблокированных действий](https://nexcmp.com/ru/docs/images/infrastructure/dedicated-01-safety.webp) ### 4. Импорт серверов {#_4-import-servers} 1. Откройте **Infrastructure › Bare Metal › Stock / iDRAC import**. 2. В блоке **Add one server** введите адрес iDRAC, учетную запись и пароль, затем нажмите **Test connection**. Тест отправляет только команды чтения и ничего не сохраняет. | Поле | Пример значения | |---|---| | Адрес iDRAC (URL или хост) | `10.20.0.11` | | Учетная запись | `nexcmp-admin` | | Пароль | `XXXX` | | Метка | `rack1-01` (пусто: генерируется) | | Назначить IP из пула | необязательно; выберите сервисный пул IP-адресов сервера | | Включить в список продаж | выключено, пока вы не будете готовы | ![Stock и импорт iDRAC с примером адреса и успешным тестом только для чтения](https://nexcmp.com/ru/docs/images/infrastructure/dedicated-02-import-server.webp) 3. Нажмите **Save to stock**. NexCMP считывает модель, CPU, RAM, диски, сетевые адаптеры и сервисный тег из iDRAC. Сервер добавляется на склад **заблокированным**. 4. Для массового добавления серверов используйте **Bulk import**: по одному серверу на строку, поля разделяются запятой, точкой с запятой или Tab. Функция **Preview** проверяет список разрешенных адресов, дубликаты адреса iDRAC или сервисного тега и считывает информацию об оборудовании (до четырех серверов одновременно). ### 5. Пользовательские ISO и веб-адрес ISO {#_5-customer-isos-and-the-iso-web-address} Откройте **Infrastructure › Bare Metal › Customer ISOs**. - Параметр **HTTP address serving ISOs to iDRAC** — это `dedicated_iso_base_url`, то же значение, что и в карточке Safety (его можно изменить в любом из этих мест). Укажите адрес вашего веб-сервера ISO в сети управления. - Параметры **Customer ISO limits** задают размер одного ISO, общий объем хранилища ISO, минимальное свободное место, срок хранения ISO (в часах), максимальное время скачивания и количество одновременных скачиваний. ![Customer ISOs с HTTP-адресом для iDRAC и ограничениями ISO](https://nexcmp.com/ru/docs/images/infrastructure/dedicated-03-iso-settings.webp) ### 6. Шаблоны ОС {#_6-os-templates} Откройте **Infrastructure › Bare Metal › Templates**. Здесь перечислены ISO-образы с автоустановкой, найденные в папке библиотеки. Нажмите **Register** напротив файла, чтобы указать семейство ОС, версию и учетную запись (заполняются автоматически по имени файла), затем переведите шаблон в положение **Enable**. Включение шаблона ничего не запускает: каждая установка по-прежнему проходит проверку safety gate. Действие **Unregister** лишь удаляет строку шаблона, но не сам файл. ![Bare Metal Templates с зарегистрированным и незарегистрированным ISO](https://nexcmp.com/ru/docs/images/infrastructure/dedicated-04-os-templates.webp) ### 7. IP-пулы {#_7-ip-pools} Откройте **Infrastructure › Bare Metal › IP Pools** и добавьте диапазоны IPv4, которые серверы получают в качестве сервисных адресов. Каждый сервер получает один адрес; опция **Назначить IP из пула** при импорте выбирает следующий свободный адрес. Количество свободных адресов подсчитывается для каждого пула. ![Bare Metal IP Pools с примерами диапазонов и количеством свободных адресов](https://nexcmp.com/ru/docs/images/infrastructure/dedicated-05-ip-pools.webp) ### 8. Тарифные планы и продажи {#_8-plans-and-sale} 1. Откройте **Services › Dedicated Server › Plans & pricing**. Отредактируйте четыре демонстрационных тарифа (в версии 1.6.1 они называются `BM-40C-`) или создайте свои: цену, расчетные периоды и стоимость установки. **При новой установке цены указываются в долларах США с точностью до цента, и с кошелька списывается именно эта сумма: курс обмена не требуется.** В установках, где цены тарифов уже были заданы во вьетнамских донгах, сохраняются донги и по-прежнему требуется курс обмена в настройках (без него заказы отклоняются с ошибкой `dedicated_fx_unavailable`). Демонстрационные тарифы изначально имеют цену 0 и находятся в статусе **disabled**: для выставления на продажу цена тарифа должна быть больше 0. Сопоставляйте каждый тариф с фактически импортируемым оборудованием: имя демонстрационного тарифа не определяет и не изменяет аппаратную конфигурацию сервера. 2. Откройте сервер (Infrastructure › Bare Metal › the server › **Sales**), **прикрепите тарифный план** и включите **Sellable**. 3. Включите **live ops** (страница Safety, с текстовым подтверждением) и разблокируйте серверы, с которыми планируете работать (вкладка сервера **Lock**, с указанием причины, заносимой в журнал аудита). 4. В разделе **Services › Dedicated Server** включите продажи. Это выполняется в два шага: ознакомьтесь с последствиями, а затем введите `ENABLE SALES`. До этого момента клиенты не видят страницу заказа, и средства с них не списываются. ![Тарифные планы Dedicated Server с выключенным переключателем продаж](https://nexcmp.com/ru/docs/images/infrastructure/dedicated-06-plans.webp) ### Возможности клиентов на странице сервера {#what-customers-can-do-on-their-server-page} Страница сервера клиента содержит шестнадцать вкладок в семи группах (Overview, Control, Network, Hardware, Billing, Activity, Settings). Группа **Billing** содержит: - **Тариф и продление**: оплата от 1 до 24 месяцев вперед за один шаг; новая дата отсчитывается от текущей даты продления, а средства списываются с баланса единоразово. Автопродление можно включить или выключить. - **Billing cycle**: выбор другого расчетного периода (например, раз в квартал); он начинает действовать со **следующего** продления, при этом в текущий момент списания и возвраты не производятся. - **Change plan**: клиент может **запросить** другой тариф. При отправке запроса списания не производятся. Вы одобряете или отклоняете его в разделе **Services › Dedicated Server › Plan changes** после апгрейда оборудования или переноса сервера. При одобренном апгрейде списывается разница за остаток уже оплаченного периода; даунгрейд не предполагает возврата средств и вступает в силу со следующего периода. - **Invoices**: все счета данного сервера (заказ, продления, смены тарифа). В разделе **Plan changes** можно сортировать запросы по ID, дате, состоянию, тарифам или серверу; сортировка применяется ко всей выборке на сервере. Колонка действий остается видимой при горизонтальной прокрутке на узком экране. В верхней части **Overview** четыре динамические плитки отображают **CPU**, **RAM**, **Disk** и **Network** с небольшим графиком за последние 24 часа. CPU, RAM и Disk показывают процент использования по данным последнего опроса iDRAC (Disk — это активность ввода-вывода, а не свободное место); Network показывает текущую входящую и исходящую скорость, а также общий объем за месяц по данным счетчика трафика. Если сервер выключен, iDRAC недоступен или машина не передает это значение, на плитке отображается **—** и краткая причина; вымышленный 0 никогда не показывается. Эти показатели поступают из Dell iDRAC, а без счетчика трафика на плитке Network остается **—**. Плитки обновляются каждую минуту, пока открыта страница, а при клике открывается вкладка **Hardware** или **Bandwidth**. Во вкладке **Overview** на карточке **Access** отображаются имя пользователя и пароль установленной операционной системы, по умолчанию скрытые кнопками **Show** и **Copy**. Они доступны после каждой установки, а не только один раз, при этом новый владелец сервера никогда не увидит пароль предыдущего владельца. Если пароль ОС был изменен внутри сервера, на карточке по-прежнему отображается пароль, заданный при установке. Вкладка **Bandwidth** отображается только при наличии агента учета трафика (см. раздел «Ограничения»). Вкладка **Subnet** отсутствует: аренда собственных IP-префиксов (BYOIP) для выделенного сервера в NexCMP не поддерживается. ### Что клиенты могут и чего не могут делать {#what-customers-can-and-cannot-do} | Клиенты могут | Недоступно никогда | |---|---| | Просматривать инвентарь, состояние работоспособности, статус питания и метрики | Видеть адрес, имя пользователя или пароль iDRAC | | Включать питание, выполнять штатное выключение, перезагрузку, принудительное выключение, сброс | Изменять учетные записи iDRAC или сетевые настройки iDRAC | | Открывать консоль в браузере (не более одной сессии одновременно) | Изменять BIOS или RAID, очищать журналы, обновлять прошивку, сбрасывать iDRAC | | Монтировать ISO или ссылку на собственный ISO, настраивать однократную загрузку, переустанавливать ОС из активного шаблона | Выполнять прямые вызовы Redfish (такие функции отсутствуют в NexCMP) | NexCMP не создает учетные записи iDRAC для клиентов: они пользуются только элементами управления в портале, а адрес и учетные данные iDRAC им никогда не показываются. ## Проверка {#verify} 0. В разделе **Safety** карточка **Management network connection** не содержит красных меток, а на страницах Bare Metal отсутствуют красные предупреждения. При обращении с хоста в сети управления `curl -I http:///` не выводит список файлов. 1. Кнопка **Test connection** в форме импорта возвращает модель, CPU, RAM и service tag. 2. Сервер появляется в **Servers** со своим оборудованием. При **live ops off** действие по управлению питанием отклоняется с сообщением «Управление сервером временно отключено на уровне всей системы». 3. После включения live ops и разблокировки одного тестового сервера выключите и включите питание сервера в **Operations** или на странице сервера, а затем откройте консоль. 4. Оформите тестовый заказ с тестовым планом: сервер назначается, ОС устанавливается, и установка завершается отправкой отчета сервера в панель. ## Ограничения и примечания {#limits-and-notes} - У каждого физического сервера может быть не более одной действующей подписки. - Команда на запись отправляется только тогда, когда **одновременно** включен режим live ops **и** снята блокировка с сервера. Проверка повторяется внутри worker непосредственно перед каждой командой. - В статусе **Installing** система ожидает ответа новой ОС на ее порту (SSH 22, Windows 3389, Proxmox 8006) до завершения заказа; время установки ограничено (`dedicated_install_timeout_min`, по умолчанию 150 минут). - Учет трафика для выделенных серверов ведется через агент учета трафика, который не входит в стандартную установку. Без него учет не ведется, портал скрывает вкладку Bandwidth, а API возвращает `capabilities.bandwidth` как `false`. - Действия администратора с арендованным сервером (блокировка, разблокировка, отмена с возвратом средств или без) унифицированы с другими услугами; возвраты зачисляются на тот баланс, с которого производилась оплата. - Серверы не перепродаются через реселлеров: услуга Dedicated продается только с основного сайта. ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | Тест завершается с ошибкой адреса | Адрес не является IPv4-литералом из `dedicated_bmc_cidrs` (частный диапазон, /16 или меньше) либо порт не разрешен | Используйте IPv4-адрес iDRAC и добавьте его подсеть в Safety › Management network connection (`dedicated_bmc_cidrs`). DNS-имена и IPv6 не поддерживаются. | | Красное предупреждение «Management network not configured» или переключатель оперативных действий возвращает `config_placeholder` | Одно из значений `dedicated_bmc_cidrs`, `dedicated_iso_base_url`, `dedicated_callback_base` по-прежнему содержит шаблонное значение по умолчанию | Укажите фактические значения в меню Safety › Management network connection. | | Поле отклоняется при сохранении | Неверный формат (CIDR не является частным или шире чем /16, адрес ISO не `http://[:port]`, callback не `https://`) либо указан шаблонный адрес вроде `example.com` | Ознакомьтесь с сообщением под полем; сохраненное значение остается без изменений. | | `nexcmp dedicated-setup-iso` завершает работу до внесения каких-либо изменений | `--listen` не является адресом этого сервера, порт уже занят либо указано недопустимое значение | Используйте адрес этого сервера в сети управления, выберите другой порт или исправьте значение, указанное в сообщении. | | "TLS-сертификат iDRAC отличается от закрепленного — опрос и операции записи остановлены" | Сертификат iDRAC был заменен (новый сертификат, замена iDRAC) | Откройте сервер, перейдите на вкладку **Access**, сравните оба отпечатка и, если изменение выполнено намеренно, нажмите **Repin certificate**. | | «Управление серверами временно отключено на уровне всей системы» | Операции в реальном времени отключены | Включите их в **Safety**. | | «Этот сервер заблокирован для выполнения операций» | Сервер заблокирован для операций | Разблокируйте сервер на вкладке **Lock**, указав причину. | | «На этом сервере все еще выполняется другая операция» | Предыдущая операция еще не завершена | Подождите; проверьте **Operations**. | | «Для этого сервера уже открыт другой сеанс консоли» | Допускается только одна сессия консоли | Закройте другую сессию. | | «Контроллер сервера временно недоступен» | iDRAC не отвечает | Проверьте сеть управления и iDRAC. | | Сбой монтирования ISO с ошибкой 403 или 404 от iDRAC | Веб-сервер не может прочитать файл или указан неверный базовый адрес | Проверьте права веб-сервера ISO и параметр **HTTP address serving ISOs to iDRAC**. | | «Этого тарифного плана нет в наличии в выбранной локации» | В этой локации нет доступных для продажи серверов с данным тарифом | Привяжите тариф к серверу и включите **Sellable**. | | «В данный момент нет доступных адресов IPv4 для назначения» | Пул IP-адресов пуст | Добавьте адреса в пул. | | «Автоматическая установка ОС сейчас недоступна» | Не выполнены предварительные требования для установки | Убедитесь, что шаблон включен и каталоги ISO доступны для записи; клиенты по-прежнему могут выполнить установку через ISO и консоль. | | Установка зависает | Устанавливаемый сервер не может подключиться к callback-адресу | Проверьте `dedicated_callback_base` и доступность панели по HTTPS из сети сервера. | --- # Узлы VPN и IPv6-прокси {#vpn-and-ipv6-proxy-nodes} > **Где в панели:** Infrastructure › VPN & Proxy nodes › Agents & external nodes (`/agents`), VPN IP pools (`/vpn/pool`), IPv6 Proxy nodes (`/vpn/proxy6/nodes`). Сами услуги находятся в Services › VPN и Services › IPv6 Proxy. Оба модуля включаются в System › Admin › License & updates. ## Назначение {#what-it-does} NexCMP позволяет продавать доступ к VPN и прокси с выходом через **принадлежащие вам IP-адреса** на ваших серверах. Поддерживаются два типа узлов: - **VPN-узел.** Небольшая программа на Go, `cmp-agent`, запускается на вашем Linux-хосте. Она определяет публичные IPv4-адреса на хосте, открывает слушатели SOCKS5, HTTP и UDP на каждом проданном адресе и направляет исходящий трафик с **того же IP**, к которому подключился клиент (same-IP egress). Узел отправляет отчеты в панель каждые несколько секунд. - **Узел IPv6-прокси.** Прокси-сервис, выделяющий клиентам адреса из префикса IPv6, маршрутизируемого на хост. Панель устанавливает его автоматически по SSH. Используйте их для перепродажи чистых IP-адресов в странах, где расположены ваши серверы. ## Требования {#requirements} ### VPN-узел {#vpn-node} | Параметр | Требование | |---|---| | Операционная система | Дистрибутив Linux с systemd и ядром версии 4.15 или новее (поддержка IPv6 free-bind). Входящий в комплект бинарный файл агента собран только для **x86_64** (amd64). | | Права доступа | root для установки. Служба сохраняет только `CAP_NET_ADMIN`, `CAP_NET_RAW` и `CAP_DAC_READ_SEARCH`. | | Инструменты | `curl` или `wget`, а также `sha256sum` (установщик прерывает работу без проверки файла). | | Публичные адреса | Публичные IPv4-адреса, назначенные на интерфейсе хоста (по одному `/32` на каждый), **или** маршрутизируемый на хост префикс, добавленный как дополнительная подсеть (IPv4 от /16 до /32, IPv6 от /48 до /128). Приватные диапазоны, CGNAT и диапазоны документации игнорируются. | | Сеть, входящий трафик | Клиенты подключаются к каждому проданному публичному IP по **портам 65001-65535** (TCP для SOCKS5 и HTTP, UDP для UDP associate). Каждая конечная точка использует набор из трех последовательных портов. | | Сеть, исходящий трафик | HTTPS (443) к домену вашей панели. Агент также определяет свою страну через `ip-api.com` (HTTP) и `ipinfo.io` (HTTPS) с лимитом в 3.5 секунды. | | Почта | Исходящие подключения к порту 25 всегда заблокированы; настройки для его открытия нет. | | Docker, VPN и виртуальные интерфейсы | Интерфейсы с именами `docker*`, `veth*`, `br-*`, `cni*`, `flannel*`, `virbr*`, `cali*`, `tun*`, `tap*`, `wg*` и `tailscale*` не предоставляют адреса. | | Зависимости | Модуль **VPN**, зона (создается автоматически по стране хоста) и панель NexCMP, доступная по HTTPS. | ### Узел IPv6-прокси {#ipv6-proxy-node} | Параметр | Требование | |---|---| | Операционная система | Linux с systemd на **x86_64**. Команды `systemctl`, `nft`, `ip`, `ss`, `sysctl` и `useradd` должны присутствовать; в противном случае установка останавливается и сообщает имя отсутствующей команды. | | Доступ для установки | Публичный IPv4-адрес (приватные, loopback и CGNAT-адреса отклоняются), порт SSH, учетная запись с правами root или `sudo` и ее **пароль**. Пароль используется только для установки и не сохраняется. | | Свободные порты | Порты **80, 443 и все порты выше 60000** должны быть свободны. Установщик не останавливает и не изменяет уже запущенные службы; он сообщает о занятых портах и прекращает работу. | | IPv6 | Публичный префикс от **/32 до /64** внутри `2000::/3`, который хост может использовать в качестве источника исходящего трафика, предоставленный как **routed** на хост или **on-link** с NDP proxy (см. ниже). | | Сеть | Клиенты подключаются к IPv4 ноды по порту 80 (HTTP-прокси), порту 443 (SOCKS5) и портам 60001-65535 (один порт на каждый статический IP). У ноды нет сертификата, поэтому HTTPS-прокси отсутствует. Трафик уходит только по IPv6 и только на адреса назначения, имеющие IPv6-адрес. Нода запрашивает свою конфигурацию у панели по HTTPS. | | ПО ноды на сервере панели | Демон ноды и его сетевой скрипт входят в релизный пакет NexCMP. Панель копирует их из папки установки (`/opt/nexcmp/releases//bin` или `/opt/nexcmp/bin` в кастомной сборке) на каждую ноду во время установки. Серверу панели также требуются `sshpass` и SSH-клиент; установщик добавляет `sshpass`, а на сервере, установленном до версии 1.4.2, его можно добавить с помощью `sudo apt-get install -y sshpass`. | | Зависимости | Модуль **IPv6 Proxy** и URL панели, к которому обращаются ноды (**IPv6 Proxy › Settings › Panel URL for nodes**, по умолчанию `https://`). | ## Подготовка инфраструктуры {#prepare-the-infrastructure} ### VPN-узел {#vpn-node-1} 1. **Подготовьте хост** с поддерживаемой версией Linux и публичными IPv4-адресами для продажи, настроенными на сетевом интерфейсе или маршрутизируемыми на хост. 2. **Если вы продаете маршрутизируемый блок**, запланируйте указать его как **Extra subnet** при добавлении ноды. Агент устанавливает маршрут `local dev lo`, чтобы хост принимал трафик для каждого адреса в блоке, а затем сообщает найденные адреса. Агент также считывает реальную таблицу маршрутизации хоста и никогда не продает и не захватывает адрес **шлюза**: если блок содержит next-hop одного из маршрутов хоста (например, адрес маршрутизатора прямо подключенного блока on-link), агент устанавливает маршруты `local` только для частей блока вокруг него, сообщает шлюз панели, а панель исключает этот адрес из пула и всех выделений. Он удаляет установленные маршруты при изменении дополнительной подсети или остановке агента. 3. **Откройте порты в брандмауэре.** Разрешите входящий TCP и UDP **65001-65535** на публичных адресах и исходящий HTTPS к панели. 4. **Необязательно: учет байтов по IP.** Conntrack accounting (`net.netfilter.nf_conntrack_acct = 1`) позволяет роли мониторинга подсчитывать байты на каждый IP. Панель может включить его, отправив агенту команду `acct`, которая также записывает `/etc/sysctl.d/99-cmp-agent.conf`. Самой роли VPN это не требуется. 5. **Проверьте доступность панели с ноды:** ```bash curl -fsS -o /dev/null -w '%{http_code}\n' https://cloud.example.com/install.sh ``` ### Узел IPv6-прокси {#ipv6-proxy-node-1} Префикс IPv6 передается на ноду одним из двух способов. Установщик тестирует оба с помощью реальных исходящих соединений и сохраняет работающий вариант. | Тип | Что это значит | Что вы настраиваете | |---|---|---| | **Routed** | Ваш апстрим-провайдер маршрутизирует префикс (например, /48 или /56) **на собственный адрес ноды**. Исходящие пакеты могут использовать любой адрес из префикса в качестве источника, а ответы возвращаются на ноду. | Запросите у провайдера маршрутизируемый префикс со следующим хопом (next hop) на ноду. На самой ноде ничего настраивать не нужно: сервис прокси использует transparent sockets, фиксированную таблицу policy-routing и `nft`. | | **On-link** | Префикс /64 находится в той же локальной сети (LAN), что и нода. Ответные пакеты приходят только в том случае, если нода отвечает на запросы neighbour discovery для каждого используемого адреса (**NDP proxy**). | Сервис задает (только на этом интерфейсе) `net.ipv6.conf..accept_ra=2`, `forwarding=1` и `proxy_ndp=1`, сохраняет прежние значения, восстанавливает их при остановке и блокирует форвардинг адресов пула, чтобы нода не становилась маршрутизатором для этого пула. | Как работает проверка: нода пытается установить TCP-соединение с публичным IPv6-адресом (порт 443) со случайного адреса проверяемого префикса в течение 6 секунд. Кандидатами являются глобальные адреса на интерфейсах с префиксом /64 или короче, а также маршруты типа `local`, `unreachable` или `blackhole` от /16 до /64. Префикс короче /64 считается **маршрутизируемым** (routed), если случайный /64 внутри него работает. ::: warning Не используйте один и тот же префикс повторно Префикс не должен пересекаться с префиксом другой ноды и не может быть шире префикса, уже входящего в собственный IPv6-пул панели. Подсеть /64 **внутри** пула панели разрешена. Пересечения отображаются в результате установки как «assign range … (node …)», и такой префикс пропускается. ::: Ограничения, применяемые самой нодой: клиенты не могут отправлять почту (порты 25, 465, 587, 2525) с адресов пула, а собственный IPv4-трафик демона ограничен ответами, обменом с панелью и DNS. ## Подключение в NexCMP {#connect-in-nexcmp} ### VPN-узел {#vpn-node-2} 1. В **System › Admin › License & updates** включите переключатель **VPN**. См. [Modules](https://nexcmp.com/ru/docs/infrastructure/modules/). ![Карточка Module с переключателями VPN и IPv6 Proxy](https://nexcmp.com/ru/docs/images/infrastructure/vpn-proxy-nodes-01-modules.webp) 2. Перейдите в **Infrastructure › VPN & Proxy nodes › Agents & external nodes**. Добавить ноду можно двумя способами. **а. Установка по SSH.** Нажмите **+ Add server (SSH)** и заполните поля: | Поле | Пример значения | |---|---| | Server IPv4 address | `192.0.2.50` | | SSH port | `22` | | SSH user | `root` | | SSH password | `XXXX` | | Display name | `node-ny-1` (если пусто: по умолчанию имя формируется из IP) | | Server role | External VPN / Proxy Node | | Zone assignment | Auto by GeoIP (create / assign Zone) или существующая зона | | Extra subnet (optional) | оставьте пустым для автосканирования интерфейсов или укажите маршрутизируемый блок, например `203.0.113.0/24` | | Включить продажу после установки | включите, чтобы сделать все обнаруженные адреса доступными для продажи | Нажмите **Connect & install**. Панель подключится по SSH, запустит на ноде однострочный скрипт установки с одноразовым тикетом и отобразит имя ноды, GeoIP-локацию и обнаруженные диапазоны. ![Диалоговое окно Add Node via SSH с примером адреса сервера и роли](https://nexcmp.com/ru/docs/images/infrastructure/vpn-proxy-nodes-02-add-server-ssh.webp) **b. Ручная установка.** Нажмите **Generate manual install token**. Команда отображается **один раз**; скопируйте ее и выполните на ноде: ```bash curl -fsSL https://cloud.example.com/install.sh | sudo sh -s -- --token XXXX --name node-ny-1 ``` Установка по токену регистрирует машину только для мониторинга: в целях безопасности панель не позволяет машине с общим токеном самостоятельно назначить себе роль VPN (добавление `--roles vpn` к команде не имеет эффекта). После того как машина появится в списке, откройте ее и назначьте роль **VPN** вручную. Установка по SSH (вариант a) сразу назначает ноде роль VPN. Новый токен аннулирует старый; уже зарегистрированные хосты продолжают работать, так как используют собственный ключ. ![Диалоговое окно команды установки с одноразовым токеном](https://nexcmp.com/ru/docs/images/infrastructure/vpn-proxy-nodes-03-install-command.webp) Что делает установщик: скачивает `cmp-agent-linux-amd64` из вашей панели, **проверяет SHA-256**, устанавливает его в `/usr/local/bin/cmp-agent`, регистрируется с помощью токена, записывает `/etc/cmp-agent/agent.json` и запускает службу systemd `cmp-agent`. Для удаления: `curl -fsSL https://cloud.example.com/install.sh | sudo sh -s -- --uninstall`. 3. После первого heartbeat узел появляется в списке. Его страна определяется через GeoIP (сначала собственный опрос узла, затем база данных панели); если **zone** для этой страны еще не существует, она создается и становится общедоступной, а обнаруженные на хосте адреса превращаются в диапазоны пула. 4. Откройте **Infrastructure › VPN & Proxy nodes › VPN IP pools**, чтобы просмотреть диапазоны, их зону и узел, а также изменить зону, узел или переключатель **Sellable** для каждого диапазона. Действие **Enable range** позволяет использовать свободные IP диапазона для новых заказов; **Disable range** лишь останавливает новые выделения, а уже арендованные IP продолжают работать. ![Пулы VPN IP с диапазонами, переданными узлом](https://nexcmp.com/ru/docs/images/infrastructure/vpn-proxy-nodes-04-vpn-pool.webp) 5. Перейдите в **Services › VPN**, настройте прайс-лист и включите продажи. Переключатель **Sell VPN** на вкладке **Subscriptions** аналогичен переключателю модуля VPN в License & updates. 6. **Необязательно: переименуйте сервис.** В **Settings › Branding** параметр **VPN service display name** изменяет отображение названия VPN-сервиса в клиентском меню, на странице заказа, странице сведений и в списке развертывания (например, `IPv4 Proxy`, `Datacenter Proxy` или `Static Residential Proxy`; до 40 символов, если оставить пустым — сохраняется `VPN`). Это влияет только на надписи: маршруты, данные и API не изменяются. ### Узел IPv6-прокси {#ipv6-proxy-node-2} 1. В разделе **System › Admin › License & updates** включите переключатель **IPv6 Proxy**. 2. Откройте **Infrastructure › VPN & Proxy nodes › IPv6 Proxy nodes** и нажмите **Add node (SSH)**. Введите IPv4-адрес узла, порт SSH, пользователя, пароль, необязательное имя и **Reason** (заносится в журнал аудита), затем нажмите **Install**. ![Диалоговое окно Add IPv6 node с примером адреса и причины](https://nexcmp.com/ru/docs/images/infrastructure/vpn-proxy-nodes-05-proxy6-add-node.webp) 3. Затем панель поочередно выполняет следующие действия: проверяет машину и порты, копирует демон, сетевой скрипт, service unit и файл окружения узла (токен узла и ключ подписи паролей), запускает **probe** для поиска доступных префиксов, сохраняет префиксы в пуле, запускает службу и ожидает первого отчета до 90 секунд. В **Install log** отображается каждый шаг. 4. Новый узел создает свою зону в состоянии **off** (на основе GeoIP IPv4-адреса узла). Включите зону в **Infrastructure › Datacenter › Zone**, чтобы клиенты могли ее выбрать. 5. Задайте общий **Mbps cap** для каждого узла (от 10 до 100000 для каждого направления). В разделе **Services › IPv6 Proxy** настройте прайс-лист и включите продажи. 6. Проверьте **IPv6 Proxy › Settings › Panel URL for nodes**. Ноды обращаются по этому адресу (`https://host`, без пути), чтобы получать свою конфигурацию и отправлять отчеты. Пустое поле означает `https://`. Это должен быть хост, адрес которого указывает напрямую на панель, чтобы собственный IPv4 ноды достигал ее без изменений. ::: tip Расписание ротации Клиенты могут настроить интервал автоматической ротации от 30 до 600 секунд. В NexCMP это расписание (а также ежечасную очистку журналов подключений) выполняет панель; ноды применяют новый адрес примерно в течение 5 секунд. ::: ### Как узел отправляет отчеты {#how-a-node-reports} | | VPN-узел (`cmp-agent`) | Узел IPv6-прокси | |---|---|---| | Регистрация | Одноразовый тикет или токен по HTTPS, затем собственный ключ | Однократная установка по SSH, затем токен узла | | Heartbeat | Каждые **5 секунд** (10 с для агента только мониторинга); панель может задавать от 3 до 300 с. После сбоя интервал увеличивается с шагом 5 с вплоть до 60 с | Узел отправляет отчет примерно каждые 60 секунд и запрашивает конфигурацию | | Отображение в сети | Heartbeat в течение последних **60 секунд** | **alive** в течение последних **120 секунд**, иначе **missed heartbeat** | | Изменение конфигурации | Применяется при следующем heartbeat | Применяется примерно в течение 5 секунд | | Обновления | Панель может отправить команду `upgrade` с новой версией, URL и SHA-256 | Переустановка из строки узла | ### Лимит трафика на VPN-ноде {#data-allowance-on-a-vpn-node} Начиная с NexCMP **1.5.1** агент VPN-ноды отправляет объем переданного трафика с каждым heartbeat, а панель добавляет его к расходу по тарифу за текущий период. Это же число отображается клиенту (вкладки Overview и Bandwidth) и вам (VPN › Subscriptions, колонка Used и строка ноды). - **Отключение.** Когда тариф исчерпывает свой объем ГБ за период, панель прекращает отправлять эндпоинты этого тарифа агенту, поэтому новые подключения отклоняются, а активные закрываются. Отключение происходит в течение одного heartbeat-интервала, поэтому тариф может незначительно превысить лимит. Тарифы с уровнем Unlimited никогда не отключаются. - **Возобновление.** Обслуживание тарифа возобновляется в течение одного heartbeat-интервала после того, как клиент докупит трафик или когда начнется следующий период. - **Not measured.** Узел, агент которого не передал данные об использовании (например, устаревший агент), отображается как **Not measured**, и его тарифы никогда не отключаются по объему GB. - **Обновите агент.** Используйте агент **1.5.1** на узлах. Старые агенты по-прежнему учитываются, но они могут терять байты при сбое heartbeat, остановке endpoint или перезапуске, а также не закрывают открытые соединения при отключении тарифа. Выполните обновление из строки узла (Reinstall) или с помощью команды `upgrade`. - Учитывается полезная нагрузка, проходящая через прокси, поэтому значение немного ниже (примерно на 1 %), чем фактический объем переданных по сети байтов. ### Устаревшие дополнения VPN {#retired-vpn-add-ons} Опции High IP Reputation, High Concurrency и High Priority Network больше не предлагаются при оформлении новых заказов. В действующих подписках выбранные дополнения сохраняются, но при продлении плата за эти архивные опции больше не взимается. Возврат средств за ранее оплаченные периоды не производится. Для перерасчета используется текущая цена дополнения в каталоге; если вы изменили эту цену или удалили дополнение, проверьте сумму продления подписки до даты следующего продления. ## Проверка {#verify} 1. В строке узла отображается статус онлайн. Для VPN-узла в **Agents & external nodes** показаны его зона, страна, роль и обнаруженные диапазоны. 2. В **VPN IP pools** перечислены диапазоны со свободными IP; на странице сведений о зоне отображается инфраструктура VPN. 3. Закажите тестовый тарифный план VPN или прокси. Клиент получает эндпоинт `ip:port`, имя пользователя и пароль; подключитесь через него и проверьте, что видимый публичный IP совпадает с IP узла (например, `curl --proxy socks5h://USER:XXXX@IP:PORT https://ifconfig.me`). 4. На узле IPv6 выполните на хосте: ```bash systemctl is-active nft list tables | grep proxy6 ss -ltn | grep -E ':(80|443|6[0-9]{4})\b' ``` ## Ограничения и примечания {#limits-and-notes} - Хосты Windows могут запускать агент мониторинга, но не поддерживают роль VPN. - Лимит трафика (ГБ за период) для VPN-тарифа: начиная с NexCMP 1.5.1 панель суммирует трафик, о котором сообщает агент VPN-узла, и отключает прокси тарифа при исчерпании лимита ГБ за период (см. «Лимит трафика на VPN-узле» ниже). Тарифы IPv6 Proxy не имеют лимита в ГБ; в них ограничивается скорость в Мбит/с на тариф. - IPv4-адреса в тарифе VPN не ротируются. Клиент сообщает о попадании IP в черный список; вы или реселлер одобряете замену из той же зоны. Ротируются только IPv6 Proxy. - За один heartbeat передается не более 64 диапазонов. - Набор эндпоинтов VPN использует три порта на каждый проданный IP. В диапазоне портов 65001-65535 каждый IP обслуживает ограниченное число эндпоинтов (178 наборов портов); панель пропускает наборы, которые использовались ранее. - Удаление прокси-ноды IPv6 разрешено только тогда, когда ни один тариф не содержит IP на ней. При этом удаляются диапазоны и токен ноды; ПО на хосте не деинсталлируется. - Перепродажа диапазона, в котором также размещены ваши собственные виртуальные машины, возможна: VPN использует только порты 65001-65535 и может делить IP с другими сервисами. ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | «ошибка регистрации (недействительный токен или сервер недоступен)» | Неверный или уже использованный токен, либо панель недоступна | Сгенерируйте новый токен или повторите установку через SSH. | | «несоответствие подписи файла — STOP» | Загруженный агент не совпадает с опубликованной контрольной суммой SHA-256 | Проверьте папку панели `/dl/` и убедитесь, что загружаемый файл не модифицируется в процессе передачи. | | «установщик предназначен только для Linux» / «архитектура … пока не поддерживается» | Windows или архитектура, отличная от x86_64 (в релиз входит агент только для x86_64) | Используйте хост под управлением Linux на архитектуре x86_64. | | Нода не появляется | Нода не может связаться с панелью по HTTPS | Проверьте `curl https:///install.sh` с ноды; проверьте DNS и брандмауэр. | | Нода отображается с неверной страной | Определение страны завершилось сбоем, поэтому использовалась база адресов панели | Разрешите исходящий доступ к `ip-api.com` и `ipinfo.io` или явно выберите зону в форме SSH. | | Диапазоны не обнаружены | Отсутствует публичный IPv4 на невиртуальном интерфейсе | Добавьте публичный адрес или укажите маршрутизируемый блок в поле **Extra subnet**. | | VPN работает, но трафик выходит с другого IP | Проданный IP не назначен или не маршрутизируется на хост | Убедитесь, что IP настроен на интерфейсе или охвачен `local … dev lo`. | | «на сервере панели отсутствует sshpass» | Хост панели не может авторизоваться на узлах по паролю | Выполните `sudo apt-get install -y sshpass openssh-client` на сервере панели, затем установите узел повторно. | | "not found in the installed package" при установке IPv6-узла | Версия панели ниже 1.4.2 или кастомная сборка без файлов узла | Обновите NexCMP до версии 1.4.2 или новее; для кастомной сборки используйте `build.sh`, которая теперь упаковывает `brandy-proxy6d` и `brandy-proxy6-net`. | | "SSH: …" в начале установки IPv6 или "SSH to internal/loopback addresses is not allowed" | Неверный порт, пользователь или пароль, SSH заблокирован либо адрес является приватным | Используйте публичный IPv4 ноды и проверьте доступ вручную с помощью `ssh -p PORT USER@IP`. | | «архитектура … не поддерживается (только x86_64)» | Архитектура ноды не x86_64 | Используйте хост с архитектурой x86_64. | | «на узле отсутствует команда: …» | Не установлены `nft`, `ip`, `ss`, `sysctl`, `systemctl` или `useradd` | Установите пакеты и запустите установку повторно. | | «порты на узле заняты другой службой: … — 80, 443, 60001-65535 должны быть свободны» | Порт 80, 443 или порт выше 60000 занят | Перенесите другой сервис; установщик не останавливает его автоматически. | | «на узле не найден префикс IPv6 с доступом в Интернет (сбой проверки исходящего трафика)» | Нет маршрутизируемого префикса, NDP-прокси невозможен или отсутствует исходящий IPv6 | Убедитесь, что префикс маршрутизируется на ноду, на интерфейсе есть связность IPv6 и ничто не фильтрует исходящий трафик. | | «все обнаруженные диапазоны уже принадлежат другому узлу» | Префикс уже используется другой нодой | Удалите его с другой ноды или выберите другой префикс. | | Установка завершается ошибкой "no initial report received from node" | Служба запустилась, но не связалась с панелью в течение 90 секунд | Проверьте URL панели, переданный узлам, и сетевой доступ к ней с узла по HTTPS; см. **Install log**. | | В строке узла отображается **missed heartbeat** | Нет отчетов в течение 120 секунд | Проверьте службу на узле, системное время и сетевой маршрут к панели. | | Клиенты не видят локацию с IPv6 | Зона отключена | Включите зону в разделе **Zone**. | --- # AI Models {#ai-models} > **В панели управления:** System › Admin › License & updates (`/license`), чтобы включить модуль. Затем Services › AI Models: Providers (`/ai/providers`), Models (`/ai/models`), Profit (`/ai/profit`) и Audit (`/ai/audit`). Клиенты используют AI › API в клиентском портале. ## Назначение {#what-it-does} AI Models — это шлюз и биллинговый уровень на базе вашей панели. Клиенты получают ключи API и обращаются к **единому эндпоинту на вашем домене** в формате, совместимом с OpenAI или Anthropic. Вы сами выбираете, какие модели предлагать и сколько стоит 1 млн токенов. NexCMP проверяет ключ, лимиты и баланс кошелька, перенаправляет запрос добавленному провайдеру, ведет учет токенов и списывает средства с предоплатного кошелька клиента. **Источники моделей вы подключаете сами.** В NexCMP нет предустановленных провайдеров, моделей, адресов по умолчанию и цен. Платформа не предоставляет модели, ключи API, токены или аккаунты провайдеров. ::: warning Сначала проверьте условия использования источников Многие источники моделей ограничивают перепродажу или передачу доступа третьим лицам. Используйте только те источники, к которым у вас есть право доступа и перепродажи, и соблюдайте их правила, а также применимое законодательство. Данная страница не является юридической консультацией. ::: AI Models — это отдельный продукт, независимый от **AI Chat and AI Agent** (модуль **AI**, см. [AI providers](https://nexcmp.com/ru/docs/ai/ai-providers/)). Эти два модуля не зависят друг от друга. ## Требования {#requirements} | Параметр | Требование | |---|---| | Модуль | **AI Models**, включенный в License & updates, Modules. По умолчанию выключен. | | Провайдеры | Один или несколько источников моделей, которые вам разрешено перепродавать, каждый с OpenAI-совместимым API (`/chat/completions`), Anthropic-совместимым API (`/messages`) или обоими. Для каждого требуются базовый URL и API-ключ. | | Сеть | Панель должна иметь доступ к каждому провайдеру по **HTTPS через порт 443** по публичному доменному имени. Провайдер на внутреннем хосте, другом порту или обычном HTTP должен быть указан в **Allowed internal hosts** (параметр `ai_endpoint_allow`). | | Клиенты | Аккаунт клиента с подтвержденным адресом электронной почты и балансом в кошельке. | | Оборудование | Нет. NexCMP только перенаправляет запросы: без GPU и файлов моделей. | ## Подготовка инфраструктуры {#prepare-the-infrastructure} 1. Получите ключ API от каждого используемого источника моделей и сохраните его base URL (например, `https://api.example.com/v1`). 2. Проверьте условия перепродажи у поставщика источника. 3. Если источник работает внутри вашей сети, определите его адрес, например `http://10.0.0.5:8000/v1`. Вы укажете `10.0.0.5:8000` в **Allowed internal hosts**. ## Подключение в NexCMP {#connect-in-nexcmp} ### 1. Включите модуль {#_1-turn-the-module-on} Откройте **System › Admin › License & updates**, найдите карточку **Module** и включите **AI Models**. Меню обновится, и появится раздел **Services › AI Models**. Пока модуль выключен, страницы клиента, страницы панели управления и шлюз отвечают `404 module_disabled`, а обращения к провайдерам не выполняются. ![Карточка Module с включенным переключателем AI Models](https://nexcmp.com/ru/docs/images/infrastructure/ai-models-01-modules.webp) ### 2. Добавьте провайдера {#_2-add-a-provider} 1. Откройте **AI Models › Providers** и выберите **Add provider**. 2. Укажите короткий **slug**, **name** (отображается только вам), **type** (OpenAI-compatible, Anthropic-compatible или Both), **base URL**, **API key** и **priority** (чем меньше число, тем раньше выполняется попытка). 3. Сохраните. Ключ хранится в зашифрованном виде, и впоследствии отображаются только последние четыре символа. Ключ можно ввести только в авторизованной сессии администратора. Используйте **Both** только для шлюза, который действительно поддерживает оба формата. NexCMP **не** выполняет конвертацию между двумя форматами: к модели OpenAI-compatible провайдера обращение идет по адресу `/ai/v1/chat/completions`, а к модели Anthropic-compatible провайдера — по адресу `/ai/v1/messages`. ![Страница Providers со списком из трех тестовых провайдеров с указанием типа, приоритета и статуса](https://nexcmp.com/ru/docs/images/infrastructure/ai-models-02-providers.webp) ### 3. Проверка подключения {#_3-test-the-connection} Нажмите **Test connection** у нужного провайдера. NexCMP обращается к `GET /models` с этим ключом и сообщает статус **ok** либо причину ошибки: **auth** (неверный ключ), **blocked**, **billing** или **unreachable**. Тестирование ограничено 6 запросами в минуту. ### 4. Синхронизация моделей {#_4-sync-the-models} Нажмите **Sync models**. NexCMP считывает список моделей провайдера и добавляет каждую новую модель **отключенной и без цены**. Модель, которой больше нет в списке провайдера, помечается флагом. Когда модуль включен, список также синхронизируется автоматически каждые 6 часов (параметр `ai_models_sync_hours`). ### 5. Настройка цен и включение моделей {#_5-set-prices-and-switch-models-on} 1. Откройте **AI Models › Models**. 2. Для каждой модели, которую вы хотите продавать, укажите **цену продажи** в долларах США за 1 миллион токенов: **input**, **cached input** и **output**. 3. При желании укажите вашу **себестоимость** модели. Тогда в **Profit** будет отображаться выручка относительно себестоимости по дням и по моделям, а цена продажи ниже себестоимости плюс минимальная маржа (параметр `ai_min_margin_pct`, по умолчанию 10) будет отклоняться, если только вы не подтвердите осознанную работу в убыток. Функция **Set price from cost** применяет заданную вами наценку; наценка по умолчанию не установлена. 4. Включите модель. Модель без цены продажи включить невозможно. Если цена cached input оставлена равной нулю, тарификация выполняется по цене input. ![Страница Models с ценами продажи input, cached input и output, а также переключателями включения](https://nexcmp.com/ru/docs/images/infrastructure/ai-models-03-models.webp) ### 6. Маршруты и отказоустойчивость {#_6-routes-and-failover} В карточке модели в разделе **Routes** перечислены обслуживающие ее провайдеры по порядку. Добавьте резервного провайдера, настройте очередность и при необходимости укажите отдельное имя модели для каждого провайдера (имя, отправляемое провайдеру, может отличаться от опубликованного вами). Если провайдер возвращает ошибку сервера, ошибку авторизации или биллинга, отсутствие модели либо превышение лимита запросов, NexCMP пробует следующий маршрут. Если после отправки запроса истекает таймаут ожидания ответа, запрос **не** перенаправляется другому провайдеру, чтобы вы не платили дважды. Для каждого провайдера действует ограничение частоты запросов `ai_provider_rpm` в минуту (по умолчанию 50). Если провайдер продолжает возвращать ошибки авторизации или биллинга, NexCMP отправляет оповещение администратору в Telegram (при настроенном Telegram). ### 7. Включение переключателя продаж {#_7-open-the-sale-switch} В верхней части страниц AI Models **переключатель продаж** (параметр `feature_ai_models`) по умолчанию выключен. Пока он выключен, клиенты видят, что сервис еще не запущен, а в публичном прайс-листе он отображается как недоступный. Убедитесь, что хотя бы одна модель включена, имеет цену продажи и маршрут с ключом, после чего включите переключатель. ### Возможности клиентов {#what-customers-can-do} В клиентском портале, **AI › API**: - **Models** отображает ваши модели и цены, base URL и готовые примеры команд. - **API Keys**: создание, переименование, ротация, отключение и удаление ключей. Секретный ключ отображается только один раз; сохраняется только его хеш. Для каждого ключа: разрешенные модели, срок действия, мягкий бюджет (предупреждение) и жесткий бюджет (блокировка с `402`), запросы в минуту и токены в минуту. - **Usage** по моделям, ключам и дням, с возможностью экспорта. - **Logs**: фильтруемые записи запросов (время, ключ, модель, токены, стоимость, статус, задержка). **Промпты и ответы не сохраняются.** Логи хранятся 90 дней по умолчанию (`ai_log_retention_days`). - **Settings**: бюджет аккаунта и адрес электронной почты для оповещений о бюджете. - **Playground**: общение с моделью в чате, параллельное сравнение моделей и копирование подходящего кода. ![Страница API Keys у клиента с базовыми URL для обоих форматов API](https://nexcmp.com/ru/docs/images/infrastructure/ai-models-04-keys.webp) Эндпоинты шлюза на вашем домене: ```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 ``` ### Кошелек и биллинг {#wallet-and-billing} Потребление ресурсов AI списывается с того же предоплаченного кошелька, что и остальные услуги. Перед отправкой запроса провайдеру NexCMP резервирует сумму максимальной возможной стоимости запроса; если баланс ниже минимума (`ai_min_balance_cents`, по умолчанию 20 центов) или недостаточен, запрос отклоняется с `402 insufficient_balance`, и **обращение к провайдеру не выполняется**. Использование агрегируется по аккаунтам и фиксируется проводками в журнале кошелька каждый час с проверкой каждые 5 минут; еще не списанные средства уже вычитаются из баланса, видимого шлюзу. Реселлеры могут продавать AI Models на собственном домене: их наценка или скидка применяется к вашей продажной цене, а с их оптового кошелька списывается оптовая цена. Переключатель AI в настройках каждого реселлера (включен по умолчанию) определяет доступ к продаже. ## Проверка {#verify} 1. После шага 3 **Test connection** показывает **ok** и количество моделей. 2. После шага 4 новые модели отображаются в списке отключенными и без цены. 3. От имени клиента с пополненным кошельком создайте ключ и выполните запрос к шлюзу: ```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"}]}' ``` Ответ `200` содержит результат работы модели. **Usage** отображает запрос, а **Profit** покажет его, если вы указали себестоимость. 4. При нулевом балансе кошелька тот же запрос возвращает `402 insufficient_balance`. ## Ограничения и примечания {#limits-and-notes} - В модуль не встроены провайдеры, модели или цены, а прайс-листы никогда не загружаются от провайдера автоматически. - Инструменты, выполняемые на стороне провайдера и тарифицируемые за вызов (например, веб-поиск), отклоняются из-за невозможности их учета. Дальше передается только ограниченный список параметров запроса. - Расход токенов берется из ответа провайдера; если в ответе их нет, NexCMP оценивает объем расчетным путем и помечает запись как приблизительную. - Ошибки от провайдера очищаются перед отправкой клиенту (удаляются имена, хосты, адреса и внутреннее имя модели у провайдера). Клиенты никогда не видят, какой провайдер обслужил запрос. - Клиенты обращаются к шлюзу через домен вашей панели, поэтому TLS для этого домена должен работать корректно. - NexCMP не предоставляет SLA, дообучение моделей или GPU-хостинг в рамках этого модуля. ## Устранение неполадок {#troubleshooting} | Симптом | Причина и решение | |---|---| | Каждая страница AI Models и шлюз возвращают `404 module_disabled` | Модуль отключен. Включите **AI Models** в меню License & updates, Modules. | | Добавление провайдера завершается ошибкой `endpoint_host_not_allowed`, `endpoint_must_be_https` или `invalid_endpoint_port` | Базовый URL должен использовать протокол HTTPS на порту 443 с публичным доменным именем. Для внутреннего хоста, другого порта или обычного HTTP укажите `host:port` в **Allowed internal hosts**. | | `blocked_endpoint` | Адрес является IP-адресом, либо имя разрешается в приватный адрес. Добавьте его в **Allowed internal hosts**, если это предусмотрено настройкой. | | **Test connection** сообщает `auth` | Ключ неверен или не имеет прав доступа. Введите ключ заново. | | Не удается включить модель (`no_price`) | Сначала задайте продажную цену. | | Клиенты получают `503 ai_unavailable` | Переключатель продажи выключен, либо отключен переключатель AI у реселлера. | | Клиенты получают `503 upstream_unavailable` | Нет активного маршрута с ключом, обслуживающего эту модель в запрошенном формате. Проверьте маршруты модели и тип провайдера. | | Клиенты получают `402 insufficient_balance` | Баланс кошелька ниже минимального или недостаточен для выполнения запроса. Попросите клиента пополнить баланс. | --- # Object Storage (S3, Ceph RGW) {#object-storage-s3-ceph-rgw} > **Раздел в панели:** Infrastructure › Cloud provider › Ceph S3 (RGW) (`/infra/s3`). Аккаунты: Services › Object Storage › S3 accounts (`/s3`). Тарифы: Services › Object Storage › PAYG pricing (`/s3/policy`). Включите модуль в System › Admin › License & updates. ## Назначение {#what-it-does} Клиенты создают аккаунты S3 на портале и получают ключи доступа. NexCMP создает и удаляет соответствующих пользователей на **вашем Ceph RADOS Gateway (RGW)** через RGW Admin Ops API, считывает метрики использования для биллинга и рассчитывает оплату по модели pay-as-you-go: хранилище сверх бесплатного лимита за ГБ в месяц (с почасовым списанием) и исходящий трафик за ГБ. Входящий трафик бесплатен. Используйте эту интеграцию, если у вас развернут кластер Ceph с RGW и вы хотите перепродавать объектное хранилище. ## Требования {#requirements} | Параметр | Требование | |---|---| | Ceph | Кластер хотя бы с одним демоном RGW и включенным **Admin Ops API** (значение по умолчанию `rgw_enable_apis` включает `admin`). | | Пользователь-администратор | Пользователь RGW для NexCMP с указанными ниже правами доступа. Не используйте пользователя, которому принадлежат данные клиентов. | | Эндпоинты | Эндпоинт S3 для клиентов и эндпоинт Admin Ops. Оба указываются как `https://host` **без пути, только порт 443** и должны разрешаться в **публичный** адрес: loopback-, link-local-, multicast-, частные и unique-local адреса отклоняются. | | Сертификат | Действующий сертификат для хоста эндпоинта. | | Журнал использования | Включенное ведение журнала использования RGW (`rgw_enable_usage_log = true`), чтобы usage API мог передавать данные о трафике. | | Зона | Мастер-зона с отмеченной услугой **Object Storage (S3)**. См. [Zones](https://nexcmp.com/ru/docs/infrastructure/zones/). | | Хранилище | Достаточный объем в Ceph для продаваемых квот. | | Зависимости | Модуль **Object Storage**. Исходящий трафик также учитывается в [Bandwidth](https://nexcmp.com/ru/docs/catalog/bandwidth/). | ## Подготовка инфраструктуры {#prepare-the-infrastructure} На узле управления Ceph: 1. Создайте пользователя-администратора и назначьте ему необходимые права Admin Ops: ```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 ``` Скопируйте `access_key` и `secret_key` из вывода команды. Это **Admin access key** и **Admin secret key** в NexCMP. 2. Включите ведение журнала использования и перезапустите шлюзы: ```bash ceph config set client.rgw rgw_enable_usage_log true ``` 3. Разместите шлюзы за HTTPS на порту 443 (через reverse proxy или собственный TLS RGW), опубликуйте DNS-имя и выполните проверку с сервера панели: ```bash curl -fsS -o /dev/null -w '%{http_code}\n' https://s3.example.com/ ``` В ответе должен прийти XML от S3 (HTTP 200 или 403), а не таймаут. ## Подключение в NexCMP {#connect-in-nexcmp} 1. **Подключите услугу S3 к зоне.** Перейдите в **Infrastructure › Datacenter › Zone**, откройте редактирование зоны и отметьте флажком **Object Storage (S3)**. В форме добавления бэкенда отображаются только мастер-зоны с услугой S3. 2. Перейдите в **Infrastructure › Cloud provider › Ceph S3 (RGW)** и нажмите **Add backend**: | Поле | Пример значения | |---|---| | Имя бэкенда | `Ceph RGW 1` | | Зона | зона из шага 1 | | Эндпоинт RGW Admin Ops | `https://s3.example.com` | | Клиентский эндпоинт S3 | `https://s3.example.com` | | Регион подписи S3 | `default` | | Ключ доступа администратора | `XXXX` | | Секретный ключ администратора | `XXXX` | | Активность | включено | | Включить продажи (требуется предварительная проверка подключения) | **выключено** на данный момент | | Причина изменения | `initial setup` | ![Диалоговое окно бэкенда S3 с примерами эндпоинтов, региона и скрытыми ключами](https://nexcmp.com/ru/docs/images/infrastructure/s3-02-backend-dialog.webp) 3. Нажмите **OK** (сохранить), затем **Check** в строке. NexCMP обратится к Admin Ops API с ключом администратора. Сообщение **Ceph connection successful** и тег **Verified** означают, что всё работает. 4. Нажмите **Edit**, включите **Enable sales** и сохраните изменения. NexCMP не позволит открыть продажи, пока проверка не завершится успешно. 5. Перейдите в **Services › Object Storage › PAYG pricing** и настройте тарифы: | Поле | Значение | |---|---| | Хранилище сверх бесплатного лимита (VND/GB/месяц) | Стоимость хранения; списывается каждый час как цена за месяц, деленная на 730. | | Скачивание (VND/GB) | Стоимость исходящего трафика. | | Загрузка (VND/GB) | Всегда 0. | | Бесплатный лимит при работающей VM (GB) | Фиксированно 100 GB на аккаунт, пока у клиента есть хотя бы одна работающая VM; распределяется между его аккаунтами S3 пропорционально объему. | | Лимит задолженности (VND) | Допустимый объем неоплаченного потребления. | | Порог биллинга (VND) | Потребление сводится в один счет, как только сумма превышает этот порог. | | Минимальный баланс для создания S3 (VND) | Баланс кошелька, необходимый для создания аккаунта. | | Максимум аккаунтов S3 на клиента, Техническая квота по умолчанию (GB) | Лимиты для новых аккаунтов. | ![Форма тарифов S3 PAYG](https://nexcmp.com/ru/docs/images/infrastructure/s3-04-pricing.webp) Цены на S3 указываются в VND. Они конвертируются для отображения и списания средств с кошелька по действующему курсу; см. [Валюта и обменные курсы](https://nexcmp.com/ru/docs/catalog/currency-and-exchange-rates/). ## Проверка {#verify} 1. **Check** возвращает "Ceph connection successful". 2. Войдя как клиент (или с тестового аккаунта), создайте аккаунт S3. В Ceph `radosgw-admin user list` покажет нового пользователя, а в **S3 accounts** он появится в списке. 3. Создайте бакет с помощью любого S3-клиента, используя ключи клиента и клиентский эндпоинт. Загрузите файл. 4. После очередного почасового биллингового цикла в **S3 accounts** отобразится потребление. ## Ограничения и примечания {#limits-and-notes} - Бэкенд, к которому уже привязаны аккаунты, сохраняет свои **зону, эндпоинт и регион**; чтобы изменить их, создайте новый бэкенд. - У одной зоны может быть свой бэкенд; аккаунты и бэкенды привязываются к зоне навсегда. - Бесплатный лимит и условие «загрузка бесплатна» — это фиксированные правила, а не настраиваемые параметры. - Ключи хранятся в зашифрованном виде; в консоли отображается только поле «оставьте пустым, чтобы сохранить текущий ключ». Пара ключей всегда вводится целиком. - Секретные ключи клиентов отображаются только один раз при создании. В случае утери ключ можно только ротировать. ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | "Endpoint requires HTTPS" | Эндпоинт использует обычный HTTP | Опубликуйте HTTPS на порту 443. | | "Порт эндпоинта не разрешен" | Порт, отличный от 443 | Используйте стандартный порт HTTPS. | | «Адрес эндпоинта не разрешен» | Имя разрешается в приватный, loopback-, link-local или unique-local адрес | Используйте публичный адрес. | | «Эндпоинт должен содержать только протокол и хост» | URL содержит путь, параметры запроса или учетные данные пользователя | Используйте только `https://host`. | | «Не удалось разрешить эндпоинт» | DNS не разрешается с сервера панели | Исправьте настройки DNS. | | "Failed to connect to Ceph" | Ошибка межсетевого экрана или TLS | Проверьте с помощью `curl` с сервера панели. | | "Ceph returned HTTP 403 AccessDenied" | Неверные ключи или отсутствие необходимых прав доступа | Проверьте ключи и повторно выполните `radosgw-admin caps add`. | | "Invalid Ceph response" | Эндпоинт не является RGW Admin Ops API | Укажите адрес RGW, а не веб-страницы. | | «Перед включением продаж необходимо успешно пройти проверку подключения» | Продажи были включены до успешного выполнения **Check** | Выполните **Check**, затем включите продажи. | | «Требуются все новые ключи для эндпоинта» | Эндпоинт изменен без указания обоих ключей | Укажите access key и secret key одновременно. | | «К бэкенду уже привязаны ресурсы; создайте новый бэкенд для изменения зоны или эндпоинта» | На этом бэкенде существуют аккаунты | Создайте новый бэкенд. | | «Выберите мастер-зону со службой S3» | Зона не является master-зоной или в ней нет сервиса S3 | Отметьте **Object Storage (S3)** для этой зоны. | | "Invalid region" | Регион содержит символы помимо букв, цифр, `-` и `_` | Используйте `default` или имя вашей zonegroup в RGW. | | «Отсутствует сводка использования Ceph; тарификация не выполнена» | Логирование использования отключено | Включите `rgw_enable_usage_log`. | --- # Kubernetes и Private Cloud {#kubernetes-and-private-cloud} > **Где найти в панели управления:** Kubernetes: Infrastructure › Cloud provider › CloudStack › Kubernetes (CKS) (`/infra/cloudstack?tab=k8s`), затем Services › Kubernetes (Overview, Clusters, Versions, Policy). Private Cloud: Services › Private Cloud (Overview `/vpc`, VPC `/vpc/list`, Plans & pricing `/vpc/plans`). Включите оба модуля в разделе System › Admin › License & updates. ## Назначение {#what-it-does} - **Kubernetes.** Клиенты создают управляемые кластеры Kubernetes в CloudStack с помощью CloudStack Kubernetes Service (CKS). Control plane предоставляется бесплатно; клиенты оплачивают **worker**-ноды. NexCMP создает отдельную сеть и публичный IP для каждого кластера, изолируя кластеры клиентов друг от друга. - **Private Cloud.** Клиенты получают изолированную сеть (CloudStack VPC) с маршрутизатором, подсетями (tiers), правилами брандмауэра (network ACL) и виртуальными машинами внутри нее. Услуга тарифицируется по **плану пропускной способности** с выделенной безлимитной скоростью (например, 50, 100, 500 Mbps, 1 и 3 Gbps). По умолчанию каждому клиенту доступен один VPC. Оба сервиса построены на базе [CloudStack](https://nexcmp.com/ru/docs/infrastructure/cloudstack/) и используют его API через одно подключение. ## Требования {#requirements} ### Kubernetes {#kubernetes} | Параметр | Требование | |---|---| | CloudStack | 4.23 (протестировано). CKS должен быть **включен** (`cloud.kubernetes.service.enabled = true`). | | Учетная запись | Учетная запись **Domain Admin** в выделенном домене, чтобы NexCMP мог создавать проект CloudStack для каждого клиента и лимиты ресурсов внутри него. См. [CloudStack](https://nexcmp.com/ru/docs/infrastructure/cloudstack/#create-a-dedicated-account-and-api-key). | | `endpoint.url` | Глобальная настройка CloudStack должна указывать на ваш management API, доступный из виртуальных машин кластера. NexCMP показывает значение и результат проверки эндпоинта. | | Версии | Как минимум одна поддерживаемая версия Kubernetes с ISO бинарных файлов в состоянии **Enabled**. Версии с истекшим сроком поддержки нельзя выставлять на продажу. | | Предложение для control plane | Бесплатное сервисное предложение с **точно 2 vCPU, 2048 MB RAM и CPU cap** (`limitcpuuse = true`), видимое для учетной записи. Все остальное сервер отклоняет с `cp_offering_invalid`. | | Сеть | Включенное изолированное сетевое предложение с поддержкой CKS. | | IP-адреса | Свободные публичные IPv4-адреса в диапазоне для продажи; каждый кластер использует один. | | Емкость | Каждый кластер расходует от 2 до 4 GB RAM на control plane и небольшую ВМ маршрутизатора. Следите за вкладками емкости. | ### Private Cloud {#private-cloud} | Параметр | Требование | |---|---| | CloudStack | 4.23 (протестировано) с включенным VPC. | | Предложение VPC | Одно предложение VPC. Предложение dual-stack также выделяет каждому уровню подсеть IPv6 /64. | | Сетевые предложения для уровней | **Одно сетевое предложение на каждый тариф пропускной способности**, созданное для VPC, со значением **network rate** (Mbps), равным тарифу, плюс одно **заблокированное** предложение на **1 Mbps**, применяемое при блокировке VPC за неуплату. | | Учетная запись | Выделенная учетная запись (рекомендуется Domain Admin). Сети VPC остаются в учетной записи, а не в проектах. | | IP-адреса | Свободные публичные IPv4-адреса (каждый VPC использует один для source NAT). | | Адресное пространство | Каждый VPC получает подсеть /16 из `10.128.0.0/9`. Не используйте этот диапазон в собственных сетях. | | Зависимости | CloudStack подключен; модуль **Private Cloud**. | ## Подготовка инфраструктуры {#prepare-the-infrastructure} ### Kubernetes: включение CKS и добавление версий {#kubernetes-enable-cks-and-add-versions} 1. Включите службу и укажите эндпоинт, затем перезапустите management-сервер: ```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`, поэтому адрес должен быть доступен из виртуальных машин кластера. 2. Соберите ISO с бинарными файлами Kubernetes для продаваемой версии с помощью скрипта `create-kubernetes-binaries-iso.sh` из исходного кода CloudStack, разместите его на веб-сервере и зарегистрируйте: ```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 ``` Дождитесь, пока статус ISO перейдет в **Ready**, а версия — в **Enabled**. 3. Создайте предложение для control plane, ограниченное доменом 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. Убедитесь, что сетевое предложение CKS включено: ```bash cmk list networkofferings state=Enabled forvpc=false filter=id,name ``` ### Private Cloud: создание предложений {#private-cloud-create-the-offerings} В интерфейсе CloudStack (**Service Offerings › Network Offerings › Add network offering**) или с помощью `cmk`: 1. Просмотрите список имеющихся предложений: ```bash cmk list vpcofferings filter=id,name,state cmk list networkofferings forvpc=true filter=id,name,networkrate,state ``` 2. Используйте включенное предложение VPC (dual-stack, если требуется IPv6). Если нужно создать новое, клонируйте стандартное предложение VPC в CloudStack и включите его. 3. Для **каждого** продаваемого тарифа пропускной способности создайте сетевое предложение **для VPC** (клонируйте стандартное «isolated network offering for VPC networks») и укажите в **Network rate (Mb/s)** скорость тарифа: `50`, `100`, `500`, `1000`, `3000`. Включите каждое предложение. 4. Создайте еще одно предложение со значением **network rate 1** (`VPC-LOCKED-1M`) для заблокированных VPC: клиенты по-прежнему смогут подключаться к своим серверам по SSH, но скорость будет ограничена. 5. Запишите UUID каждого offering: они понадобятся NexCMP в следующем разделе. ::: warning Предустановленные ID offering отсутствуют в вашем облаке Форма Private Cloud предварительно заполнена UUID offering из другой инсталляции CloudStack. Замените **каждый** из них на собственный, иначе первый же заказ VPC завершится ошибкой. ::: ## Подключение в NexCMP {#connect-in-nexcmp} ### Kubernetes {#kubernetes-1} 1. Откройте **Infrastructure › Cloud provider › CloudStack** и выберите вкладку **Kubernetes (CKS)**. В карточке справа **CKS status on CloudStack (read-only)** отображаются `kubernetesserviceenabled`, `endpoint.url` с **Endpoint check**, network offering для CKS, параметры `cloud.kubernetes.*` и список ISO и версий. Нажмите **Recheck** после внесения исправлений. 2. В **Sales config** выберите **Control plane Offering** (появится предупреждение, если параметры отличаются от ровно 2 vCPU / 2048 MB / CPU cap), укажите **Max workers per cluster** (от 1 до 9: CKS поддерживает до 10 узлов, включая управляющий), включите **Enable CKS for this backend** и нажмите **Save**. Переключатель остается неактивным, пока не выбран offering. ![Вкладка Kubernetes (CKS) с выбранным control plane offering и карточкой статуса CKS](https://nexcmp.com/ru/docs/images/infrastructure/kubernetes-and-private-cloud-01-cks.webp) 3. Откройте **Services › Kubernetes › Versions** и нажмите **Sync from CloudStack**. Включите **Available for new clusters** для продаваемых версий, установите версию по умолчанию и при необходимости дату **End of life (EOL)**. 4. Откройте **Services › Kubernetes › Policy**. В **Worker plans** добавьте тарифы с **Plan code** (латинские буквы A-Z, цифры 0-9, дефис, до 16 символов). Укажите **NVMe per worker (GB)**, **Min and max workers** и лимиты кластера (активные кластеры на аккаунт, операций создания за 24 часа, глобальный лимит, параллельные операции CKS). Затем включите **Sell Kubernetes (CKS)**. В продаже должен оставаться как минимум один тариф. ![Политика Kubernetes с тарифами worker и переключателем продаж](https://nexcmp.com/ru/docs/images/infrastructure/kubernetes-and-private-cloud-03-policy.webp) ### Private Cloud {#private-cloud-1} 1. Откройте **Services › Private Cloud** (Overview). В карточке политики замените **VPC offering** и **Locked offering tier** на собственные UUID. Проверьте лимиты (VPC на аккаунт, уровней tier, ВМ и правил ACL на VPC, необходимый для создания баланс в часах стоимости тарифа, смен тарифа за 24 часа, параллельных операций, где 0 — экстренная остановка) и DNS-серверы. Нажмите **Save** (потребуется указать причину). ![Обзор Private Cloud с полями VPC offering и locked offering](https://nexcmp.com/ru/docs/images/infrastructure/kubernetes-and-private-cloud-04-vpc-policy.webp) 2. Откройте **Services › Private Cloud › Plans & pricing**. Для каждого тарифа нажмите **Edit** и укажите **VND price per month**, **On sale** и UUID **CloudStack tier offering**, пропускная способность которого соответствует скорости тарифа в Mbps. В строке отображаются себестоимость и прибыль при полной нагрузке, что позволяет увидеть тарифы ниже вашей себестоимости. ![Диалоговое окно редактирования тарифа пропускной способности Private Cloud](https://nexcmp.com/ru/docs/images/infrastructure/kubernetes-and-private-cloud-05-vpc-plan.webp) 3. Включите **Sell Private Cloud**. Для предварительного тестирования добавьте ID тестовых аккаунтов в **Beta accounts**: эти аккаунты смогут использовать сервис при выключенном переключателе продаж. ## Проверка {#verify} 1. Kubernetes: карточка статуса отображает `kubernetesserviceenabled: true`, успешный endpoint check и включенную версию. Создайте тестовый кластер с одним worker-узлом от лица клиента; он должен перейти в статус running, а `kubectl get nodes` должен показать готовность. Затем удалите его: сеть и IP вернутся в пул. 2. Private Cloud: создайте VPC с минимальным тарифом от лица тестового клиента. VPC отображает статус active, уровень tier получает подсеть, ВМ на уровне tier имеет доступ в интернет через роутер VPC, а **Change plan** на более крупный тариф вступает в силу примерно за 20 секунд без разрыва соединений. ## Ограничения и примечания {#limits-and-notes} - Kubernetes: worker-узлы тарифицируются как ВМ по ценам тарифа и учитываются как ВМ в лимитах на ВМ. Кластер может содержать не более 9 worker-узлов из-за ограничения CKS в 10 узлов. - Kubernetes: control plane, роутер и публичный IP кластера бесплатны для клиента; их себестоимость покрываете вы. - Private Cloud: все тарифы — **unmetered**. Цены в форме указаны во вьетнамских донгах в месяц; в столбце себестоимости используется ориентировочная цена, поэтому используйте собственные расчеты. - Заблокированный VPC ограничен скоростью 1 Mbps, не тарифицируется и не удаляется автоматически. - Private Cloud использует один роутер на VPC, а не резервированную пару. В случае сбоя его хоста CloudStack восстанавливает его за несколько минут. ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | `cp_offering_invalid` / "Этот Offering не соответствует 2 vCPU / 2048 MB / limitcpuuse" | Offering для control-plane имеет другие параметры или не имеет ограничения CPU | Создайте offering, как описано в шаге 3, и выберите его снова. | | Переключатель **Enable CKS** неактивен | Не выбран offering для control-plane | Сначала выберите один из них. | | `kubernetesserviceenabled: false` | CKS отключен в CloudStack | Включите его и перезапустите management server. | | Ошибка проверки endpoint | `endpoint.url` недоступен из виртуальных машин кластера | Укажите доступный URL, перезапустите management server и нажмите **Recheck**. | | "EOL: невозможно включить для продажи" | Срок поддержки версии истек | Зарегистрируйте более новую версию. | | "Нет версий: нажмите Sync from CloudStack" | Не зарегистрировано ни одной версии Kubernetes | Зарегистрируйте версию и выполните синхронизацию. | | "CKS backend отключен: клиенты не могут создавать кластеры, даже если включен флаг продажи" | Переключатель продаж включен, но бэкенд CKS отключен | Включите CKS на вкладке CloudStack. | | "Как минимум 1 план должен быть в продаже" | Удален последний план worker | Оставьте хотя бы один план или отключите продажу Kubernetes. | | Создание кластера зависло | Недостаточно ресурсов или отсутствует ISO | Проверьте вкладки емкости и статус ISO для этой версии. | | Сбой создания нового VPC на первом шаге | Недопустимый ID для VPC offering или tier offering | Замените каждый UUID offering на значение из вашей инсталляции CloudStack. | | "cs_offering_id должен быть UUID" | ID offering не является UUID | Вставьте id из `cmk list networkofferings`. | | Ошибка при смене плана | Новый tier offering не существует или указан неверный network rate | Проверьте UUID для offering и его network rate. | --- # Тарифные планы и цены {#plans-and-pricing} > **Где в панели управления:** Services › Virtual Machines › Plans & pricing (`/vm/catalog`), с вкладками Plan, Custom plan, Cycle и Offering CloudStack. Шаблоны находятся на отдельной странице Services › Virtual Machines › Template (`/vm/templates`). ## Назначение {#what-it-does} **План** — это конфигурация, доступная клиентам для покупки: vCPU, RAM, корневой диск и цена в определенной зоне из одного источника (CloudStack или кластер Proxmox VE). Клиент выбирает план, операционную систему и **платежный цикл** (почасовой, ежемесячный или более длительный предоплаченный период). Планы продаются в панели клиента, через API и на сайтах реселлеров. ## Требования {#requirements} | Параметр | Требование | |---|---| | Source | Подключенный CloudStack (план указывает на service offering в CloudStack) или кластер Proxmox VE, привязанный к зоне. См. [CloudStack](https://nexcmp.com/ru/docs/infrastructure/cloudstack/) и [Proxmox VE](https://nexcmp.com/ru/docs/infrastructure/proxmox/). | | Зона | Зона с возможностью заказа виртуальных машин. См. [Zones](https://nexcmp.com/ru/docs/infrastructure/zones/). | | Шаблоны | Как минимум один включенный и готовый шаблон. См. [OS templates](https://nexcmp.com/ru/docs/infrastructure/templates/). | | Курс обмена валют | Только если вы указываете цены в VND. См. [Currency and exchange rates](https://nexcmp.com/ru/docs/catalog/currency-and-exchange-rates/). | | Права доступа | Администратор; каждое изменение цены требует указания причины. | ## Подготовка инфраструктуры {#prepare-the-infrastructure} - **CloudStack:** создайте service offerings, которые вы хотите продавать (публичные или общие с доменом NexCMP). План указывает на один offering. На вкладке **Offering CloudStack** отображаются offerings и disk offerings напрямую из CloudStack в реальном времени (кэшируются на 60 секунд). Когда таблица планов пуста, фоновый процесс автоматически создает шесть планов на основе ваших реальных offerings. - **Proxmox VE:** в Proxmox ничего настраивать не требуется; в плане задаются собственные параметры CPU, RAM и диска. Размер диска не должен быть меньше размера диска в шаблоне. ## Подключение в NexCMP {#connect-in-nexcmp} ### Как хранятся цены {#how-prices-are-stored} NexCMP хранит каждую цену в **микродолларах в час** (µ$/hour; 1 µ$ — это 1/1,000,000 USD). Вы можете ввести цену в удобных для вас единицах, и форма пересчитает ее: | Единица измерения | Примечания | |---|---| | USD / час (6 знаков после запятой) | Сохраняется как есть. | | USD / месяц | Делится на значение настройки часов в месяце (730). | | VND / месяц | Конвертируется один раз по текущему курсу, затем сохраняется в µ$/hour. Отображается только при наличии курса. | Форма показывает результат: µ$/hour, USD/час, цену за месяц и для каждого расчетного цикла. **Цена за месяц = цена за час × 730**; более длительный цикл рассчитывается как **цена за месяц × месяцы × (1 − скидка)**. ### Добавление плана {#add-a-plan} 1. Перейдите в **Services › Virtual Machines › Plans & pricing** и нажмите **Add plan**. 2. Заполните форму: | Поле | Пример значения | |---|---| | Название плана | `VM-2-4` | | Slug | пусто: формируется из названия | | Зона | ваша зона по умолчанию | | Источник инфраструктуры | пусто для CloudStack или кластер Proxmox | | Сервисное предложение CloudStack (в реальном времени) | выберите вариант (отображается только для CloudStack) | | CPU (ядро), RAM (МБ), Root disk (ГБ) | `2`, `4096`, `40` | | Disk offering | необязательно, для собственного размера корневого диска | | Enter price by / Price | `USD / month`, `12` | | Краткое описание | `2 vCPU, 4 GB RAM, 40 GB NVMe` | | Порядок | `10` | | Активность | Вкл.: клиенты могут покупать | | Visibility | Отображается в каталоге | | Причина изменения цены | `initial price` | 3. Нажмите **OK**. План появится в таблице с почасовой и ежемесячной ценой, а также ячейкой для каждого включенного цикла. ![Таблица планов с почасовыми, ежемесячными ценами и ценами за расчетный цикл](https://nexcmp.com/ru/docs/images/catalog/plans-02-list.webp) ### Расчетные циклы {#billing-cycles} Откройте вкладку **Cycle**, чтобы настроить доступные клиентам циклы и скидки для них. | Цикл | По умолчанию | Примечания | |---|---|---| | Почасовой | всегда включен | Оплата списывается каждый час. | | Ежемесячный | вкл., 0% | | | 1 год | вкл., 10% | | | 2 года | вкл., 15% | | | 3 года | вкл., 20% | | Вы можете переименовать расчетный цикл, изменить его скидку (от 0 до 90%) и включить или отключить его. Изменения применяются к виртуальным машинам, купленным или продленным **после** сохранения; запущенные ВМ сохраняют свою зафиксированную цену. ![Вкладка Cycle со скидками по расчетным циклам](https://nexcmp.com/ru/docs/images/catalog/plans-03-cycles.webp) ### Задать базовый план и рассчитать остальные {#set-a-base-plan-and-derive-the-others} Функция **Set base plan + derive other plans** пересчитывает всю таблицу на основе одной цены. Выберите базовый план и его цену, затем либо сохраните **текущие соотношения цен** между планами, либо выполните расчет на основе **цен компонентов** (µ$/hour за vCPU, за ГБ RAM и за ГБ NVMe с дополнительной скидкой на пакет от 0 до 50%). В таблице предварительного просмотра отображаются старые и новые цены до сохранения изменений. Нажмите **Apply** и укажите причину. При применении новых цен: запущенные ВМ с **почасовой** оплатой получают **более низкую** цену со следующего расчетного часа, а предоплаченные ВМ — при продлении. Если цена **повышается**, запущенные ВМ сохраняют прежнюю цену. ### Пользовательские планы {#custom-plans} Вкладка **Custom plan** позволяет клиентам самостоятельно выбирать количество vCPU, объем RAM и NVMe. Задайте почасовую цену за единицу для одного vCPU, одного ГБ RAM и одного ГБ NVMe (оставьте поле пустым для расчета на основе процентной скидки), минимум, максимум и шаг для каждого параметра, а также применимые расчетные циклы. **Пользовательский** план должен стоить дороже фиксированного плана того же размера, иначе клиенты перестанут выбирать фиксированные планы; страница отмечает строки, где пользовательский план дешевле. Включите **Enable custom plans for customers** для их продажи; при отключении в портале отображается «Coming soon». Для каждой настраиваемой ВМ создается отдельная скрытая строка плана; такие строки нельзя редактировать или удалять, пока ВМ существует. ### Изменение, скрытие, клонирование, удаление {#change-hide-clone-delete} | Действие | Назначение | |---|---| | **Edit** | Изменяет название, описание, порядок, цену, статус активности и видимость. | | **On/Off** | **Off**: клиенты не могут совершить покупку; на запущенные ВМ это не влияет. | | **Hide / Show** | Скрытый план отсутствует в каталоге, но существующие ВМ сохраняют его, а администратор может назначить его вручную. | | **Clone** | Создает новый план в той же зоне с новым источником, размером или ценой, при необходимости скрывая старый. Чтобы продавать одну и ту же конфигурацию из CloudStack и Proxmox, клонируйте ее и выберите другой источник. | | **Move up/down** | Изменяет порядок отображения. | | **Delete** | Снимает план с продажи и удаляет его из таблицы. ВМ, которые уже используют его, сохраняют этот план. | ::: warning Используемые планы заблокированы Как только к плану привязываются ВМ, его **zone, offering, CPU, RAM, disk и source** блокируются, чтобы запущенные ВМ не изменились незаметно. Используйте **Clone** для создания новой конфигурации; старый план сохраняет свои ВМ. ::: ## Проверка {#verify} 1. План появляется в таблице с ожидаемой почасовой и ежемесячной ценой. 2. В клиентском портале начните оформление заказа: в зоне доступен этот план, а цены за цикл соответствуют вкладке **Cycle**. 3. Оформите тестовый заказ, проверьте списание с кошелька на соответствие отображаемой цене и удалите ВМ. ## Ограничения и примечания {#limits-and-notes} - План относится к **одной** зоне и **одному** источнику. - Цены хранятся в µ$/hour; отображаемая цена в VND рассчитывается и округляется с помощью **VND rounding step** (см. страницу валют). Баланс кошелька всегда ведется в USD. - Реселлеры получают оптовую и розничную цены, рассчитанные на основе базовой цены каталога; изменение цены для существующего плана не копирует индивидуальные цены реселлеров в клон с измененной конфигурацией. - Лимиты минимума, максимума и шага пользовательских планов проверяются на соответствие ограничениям CloudStack; максимальный размер диска выше лимита CloudStack `storage.max.volume.size` приведет к сбою развертывания и возврату средств. ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | "Требуется название плана" / "Требуется сервисный тариф" | Не заполнено обязательное поле | Укажите имя; для CloudStack выберите offering. | | «CPU/RAM/диск должны быть > 0» | Одно из значений объема не указано или равно нулю | Заполните все три значения. | | «Недопустимая цена (µ$/hr должно быть 1 … 100,000,000)» | Цена выходит за пределы допустимого диапазона | Проверьте единицу измерения и сумму. | | «Для изменения цены требуется указать причину» | При редактировании не указана причина | Укажите причину (не менее 3 символов). | | «Offering „X“ имеет параметры 4c/8192, но в плане указано 2c/4096 — CloudStack выполнит подготовку по offering. Сохранить?» | Параметры плана отличаются от параметров offering | Приведите их в соответствие или подтвердите сохранение параметров CloudStack. | | «Не удалось получить offerings из CloudStack» | Отсутствует подключение или у ключа недостаточно прав | См. [CloudStack](https://nexcmp.com/ru/docs/infrastructure/cloudstack/). | | «Шаблон не готов в CloudStack — развертывание завершится ошибкой. Все равно включить?» | Включен шаблон, подготовка которого еще не завершена | Дождитесь готовности шаблона. | | План нельзя изменить («has VMs - locked») | План используется виртуальными машинами | Клонируйте его. | | План не отображается у клиентов | Отключен, скрыт или зона еще не готова | Проверьте **Active**, **Visibility** и тег зоны. См. [Zones](https://nexcmp.com/ru/docs/infrastructure/zones/). | | «Выберите хотя бы 1 платежный цикл» | Для настраиваемого плана не выбран расчетный период | Отметьте хотя бы одну. | | «Скидка на комплект должна быть 0–50%» | Значение выходит за допустимые пределы | Укажите значение от 0 до 50. | | Отсутствует вариант цены в VND | Курс обмена еще не задан | Сначала обновите курс. | --- # Квоты трафика и дополнительные пакеты {#bandwidth-quotas-and-add-ons} > **Где найти в панели:** Services › Bandwidth: Summary (`/bandwidth`), Add-on (`/bandwidth/addons`) и Quotas, pricing & policy (`/bandwidth/policy`). Переключатель модуля находится в System › Admin › License & updates. ## Назначение {#what-it-does} Модуль Bandwidth задает ежемесячную **квоту** на трафик для каждой тарифицируемой услуги. NexCMP отслеживает потребление, предупреждает клиента при достижении 80% и 100%, а при превышении квоты действует в соответствии с вашей **политикой перерасхода**. Клиенты могут покупать **дополнительные пакеты** терабайтов с баланса своего кошелька; вы также можете начислять их бесплатно. | Услуга | Квота | |---|---| | Виртуальные машины | На одну VM в месяц (по умолчанию 2048 GB, то есть 2 TB) | | Kubernetes | Квота VM, умноженная на количество worker-узлов | | Object Storage | Исходящий трафик на клиента в месяц (по умолчанию 100 GB); сверх этого лимита действует стандартный тариф pay-as-you-go | | VPN | Сохраняет квоту своего плана; увеличить пропускную способность можно на странице VPN | | Private Cloud | **Без учета трафика** | ## Требования {#requirements} | Параметр | Требование | |---|---| | Модуль | **Bandwidth** включен по умолчанию. Отключите его в License & updates, чтобы скрыть. | | Источник измерений | Для источника по умолчанию — **CloudStack VM statistics**. Оставьте сбор статистики ВМ в CloudStack включенным; стандартного срока хранения в 720 минут достаточно. | | Proxmox VE | Трафик ВМ на Proxmox VE **не учитывается**. | | Курс обмена валют | Цена дополнения указывается в VND. См. [Валюта и обменные курсы](https://nexcmp.com/ru/docs/catalog/currency-and-exchange-rates/). | | Зависимости | [CloudStack](https://nexcmp.com/ru/docs/infrastructure/cloudstack/) — для трафика ВМ и Kubernetes, [S3](https://nexcmp.com/ru/docs/infrastructure/s3/) — для скачивания из хранилища. | ## Подготовка инфраструктуры {#prepare-the-infrastructure} Дополнительных действий, кроме подключения CloudStack, не требуется. NexCMP считывает `listVirtualMachinesUsageHistory` для всех ВМ аккаунта за один вызов каждые 5 минут интервалами не более двух часов. Каждая выборка охватывает одну минуту и **суммируется**. Выборки берутся со сдвигом на три минуты назад, чтобы данные успели поступить. Пропуск, превышающий срок хранения данных в CloudStack (около 12 часов), пропускается и фиксируется. ::: info Что означают эти показатели Расход учитывается на сетевом интерфейсе каждой ВМ, поэтому включает трафик между ВМ, а не только трафик в интернет. Значение может быть немного выше, чем при учете на пограничном маршрутизаторе. ::: ## Подключение в NexCMP {#connect-in-nexcmp} 1. Откройте **Services › Bandwidth › Quotas, pricing & policy**. 2. Задайте значения и нажмите **Save**; будет запрошена и сохранена причина. Воркер применит изменения примерно в течение 30 секунд. | Поле | По умолчанию | Значение | |---|---|---| | Включить Bandwidth (меню клиента и покупка дополнений) | включено | Переключатель для коммерческой части модуля. | | ВМ, ГБ/месяц (Kubernetes = это значение × воркеры) | 2048 | Квота на ВМ за расчетный период. | | S3, ГБ скачивания/месяц на клиента | 100 | Сверх этого лимита действует стандартная оплата S3 по модели pay-as-you-go. | | Направление квоты (ВМ, Kubernetes) | Входящий + исходящий | Или **Outbound only**. | | Цена за +1 ТБ (VND) | 100,000 | Конвертируется в центы по курсу котировки. | | Максимум за одну покупку (ТБ) | 50 | | | Политика при превышении лимита | suspend | **notify**, **throttle** или **suspend** (см. ниже). | | Применять фактическую блокировку с | дата миграции + 24 часа | До этой даты услуги не блокируются; клиенты получают только предупреждения. | | Ограничение скорости при throttle (Мбит/с) | | Используется только для throttle. | ![Политика Bandwidth: стандартные квоты, цена дополнений и правила при превышении лимита](https://nexcmp.com/ru/docs/images/catalog/bandwidth-01-policy.webp) ### Политики при превышении лимита {#overage-policies} | Политика | Что происходит при превышении 100% лимита услуги | |---|---| | **notify** | Клиент получает уведомление. Других действий не выполняется. | | **throttle** | В настоящее время аналогично notify: ограничение скорости в этом релизе не подключено. | | **suspend** (по умолчанию) | ВМ, кластер или аккаунт S3 блокируются до тех пор, пока клиент не приобретет дополнение или не начнется следующий период. Действует только с даты **suspend-from**. | Оповещения о достижении 80% и 100% (колокольчик и email) отправляются всегда — по одному разу для каждого порога, периода и услуги. Если разблокировать услугу, заблокированную из-за превышения трафика, пока квота все еще превышена, следующая проверка (в течение 5 минут) снова ее заблокирует. Чтобы услуга продолжала работать, **предоставьте дополнение**. ### Контроль расхода и выдача надбавок {#watch-usage-and-grant-add-ons} Откройте **Services › Bandwidth › Summary**. Здесь перечислены все услуги с расходом за текущий период, квотой с учетом надбавок, остатком трафика и отметками 80% и 100%. На карточках KPI показано количество услуг, проданные надбавки за последние 30 дней и состояние коллектора (запущен, курсор). В таблице **Daily** текущий период представлен по дням. ![Bandwidth Summary с состоянием коллектора и расходом по услугам](https://nexcmp.com/ru/docs/images/catalog/bandwidth-02-summary.webp) Чтобы предоставить клиенту запас, используйте **Grant** в строке услуги (бесплатная надбавка целыми терабайтами). В разделе **Add-on** доступна история покупок и выдач, от новых к старым, с фильтром по типу. ![История Add-on с покупками и бесплатными выдачами](https://nexcmp.com/ru/docs/images/catalog/bandwidth-03-addons.webp) ### Что видит клиент {#what-customers-see} В клиентском портале появляется раздел **Bandwidth** с текущим расходом, остатком квоты и действием **купить +1 TB** с оплатой из баланса кошелька (в пределах установленного лимита на одну покупку). Надбавки действуют в течение текущего периода. ## Проверка {#verify} 1. Коллектор на странице **Summary** работает, а его курсор сдвигается вперед каждые несколько минут. 2. Для ВМ с сетевым трафиком статистика расхода появляется примерно через 10–15 минут. 3. Чтобы проверить оповещения, снизьте квоту ВМ до нескольких гигабайт на **тестовой** инсталляции и создайте трафик. Не делайте этого в рабочей среде: квота действует на все ВМ. ## Ограничения и примечания {#limits-and-notes} - Расход рассчитывается за период (месяц). Надбавки и квоты применяются к текущему периоду. - Параметр «Enforce actual suspend from» защищает клиентов от приостановки сразу в момент первого включения модуля. - Политика ограничения скорости (throttle) в этом выпуске работает только в режиме уведомлений. - Изменение квоты применяется ко всем сайтам, включая реселлерские. Розничные и оптовые цены надбавок у реселлеров рассчитываются с учетом их скидки или наценки. - Трафик для раздела **Dedicated servers** настраивается отдельно; см. [Dedicated servers](https://nexcmp.com/ru/docs/infrastructure/dedicated/). ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | Расход работающей ВМ остается на нуле | Воркер остановлен, потеряна связь с CloudStack или отключен сбор статистики ВМ | Проверьте `sudo nexcmp status` и **Test connection** в [CloudStack](https://nexcmp.com/ru/docs/infrastructure/cloudstack/); включите сбор статистики ВМ в CloudStack. | | В данных о расходе есть пропуски | Превышен срок хранения данных в CloudStack либо воркер простаивал более 12 часов | Восстановить невозможно; пропуск зафиксирован в журнале. | | Расход трафика немного выше ожидаемого | Учитывается межмашинный трафик ВМ и трафик других интерфейсов | Штатное поведение; объясните это клиентам. | | Приостановленная услуга снова приостанавливается после разблокировки | Лимит квоты все еще превышен | Выдайте надбавку или увеличьте квоту. | | Услуги не приостанавливаются, хотя задана политика **suspend** | Дата в параметре suspend-from еще не наступила | Укажите текущее время (когда правило действует, на странице отображается «ACTIVE»). | | "bw_over_policy должно быть notify, throttle или suspend" | Через API передано недопустимое значение политики | Используйте одно из трех допустимых значений. | | Для ВМ Proxmox не отображается расход | Их трафик не учитывается | Штатное поведение. | | Клиенты не могут купить надбавки | Учет трафика отключен либо на балансе кошелька недостаточно средств | Проверьте переключатель модуля и баланс кошелька. | --- # Валюта и курсы обмена {#currency-and-exchange-rates} > **Где найти в панели управления:** Finance › Payment channels › Exchange rates (`/payments/fx`) — для курсов. System › Settings › Brand (`/settings/branding`) — для переключателя **Site currency**. ## Назначение {#what-it-does} NexCMP ведет кошельки и счета в USD. Цены планов VM хранятся в микродолларах в час. Отображаемые валюты позволяют клиентам видеть суммы в USD в их собственной валюте по установленному курсу; они не меняют баланс кошелька. Для некоторых услуг принимаются цены, указанные в VND, включая дополнительные пакеты трафика, S3, Private Cloud и существующие планы Bare Metal с ценами в VND. Банковские переводы через SePay оплачиваются в VND. Курсы валют **публикуются администратором**. Автоматического обновления нет: сохраненные курсы остаются неизменными, пока вы не нажмете кнопку обновления. ## Требования {#requirements} | Параметр | Требование | |---|---| | Доступ в интернет | Сервер панели должен иметь доступ к `open.er-api.com` (для USD/VND) и `api.frankfurter.dev` (для остальных валют) при нажатии **Update exchange rates**. | | Права доступа | Администратор для внесения изменений; при каждом изменении запрашивается причина. | | Зависимости | Ничего. Курс используется в разделах [Plans](https://nexcmp.com/ru/docs/catalog/plans/), [Bandwidth](https://nexcmp.com/ru/docs/catalog/bandwidth/), [S3](https://nexcmp.com/ru/docs/infrastructure/s3/) и при банковских переводах в VND. | ## Подготовка инфраструктуры {#prepare-the-infrastructure} Не требуется. Если ваш сервер фильтрует исходящий трафик, разрешите доступ по HTTPS к двум указанным выше сервисам. ## Подключение в NexCMP {#connect-in-nexcmp} ### 1. Выберите валюту сайта {#_1-choose-the-site-currency} Перейдите в **System › Settings › Brand** и настройте параметр **Site currency**: | Вариант | Что видит клиент | |---|---| | **На основе языка (авто)** (по умолчанию в новой установке) | Портал выбирает валюту отображения в зависимости от языка (таблица ниже). Клиент может вручную выбрать USD. | | **USD** | Цены и баланс отображаются только в USD. Переключатель валют и пересчитанные суммы отсутствуют. | | **VND** | Устаревший параметр; применяет те же правила отображения по языку, что и Auto. | Сохраните изменения. Страницы клиентов обновятся примерно в течение минуты. Когда сайт определяет валюту по языку клиента: | Язык | Валюта отображения | |---|---| | Английский | USD | | Вьетнамский | VND | | Китайский (упрощенный / традиционный) | CNY / TWD | | Японский, корейский | JPY, KRW | | Французский, немецкий, испанский, итальянский | EUR | | Португальский, русский | BRL, RUB | | Арабский, хинди | SAR, INR | | Индонезийский, тайский | IDR, THB | Валюта, курс которой не опубликован, не предлагается: портал автоматически переключается на USD. ### 2. Опубликуйте курсы валют {#_2-publish-the-rates} 1. Перейдите в **Finance › Payment channels › Exchange rates**. 2. В карточке **Currency by language** перечислены 11 валют отображения с их курсом к USD, источником данных (Frankfurter) и временем последнего обновления. Нажмите **Update exchange rates**. Кнопка выполняет два действия одновременно: считывает публичные рыночные котировки для **USD/VND** и запрашивает остальные 11 курсов. Оба источника проверяются до сохранения данных. Если хотя бы один запрос завершится с ошибкой, изменения не сохраняются и остаются прежние курсы. 3. В карточке **Active exchange rate** показаны действующий курс USD/VND, метка его источника (рыночный или фиксированный), маржа и справочные рыночные котировки с временными метками. 4. Карточка **Config** (сохранение с указанием причины): | Поле | Значение | Диапазон | |---|---|---| | Маржа (б. п., 100 = 1 %) | Добавляется к рыночному базовому курсу. Итоговый курс равен базовому курсу плюс маржа с округлением в большую сторону. | От 0 до 1000 | | Фиксированный курс (VND за USD, 0 = по рынку) | Курс, задаваемый вручную. Он заменяет рыночное значение. | 0 или от 15,000 до 50,000 | | Порог скачка (б. п.) | Если новый рыночный курс отличается от текущего более чем на эту величину, он **приостанавливается** до вашего подтверждения. | От 50 до 2000 (по умолчанию 500) | | Шаг округления VND | Округляет цены в VND и суммы банковских переводов. | 1, 100, 1,000 (по умолчанию) или 10,000 | 5. Если новый рыночный курс отклоняется сильнее установленного порога, появляется карточка **Pending exchange rate**, а сам курс **не применяется**. Сверьте его с выбранным источником и нажмите **Apply this rate**. Рыночный курс за пределами диапазона от 15,000 до 50,000 VND за USD отклоняется как недопустимый. Ручное обновление ограничено одним запросом раз в пять минут, поэтому кнопка может предложить подождать. 6. В таблице **Exchange rate history** перечислены все полученные или подтвержденные курсы с указанием времени, действующего курса, рыночного ориентира, источника, статуса применения, автора действия и примечания (заблокированные скачки отмечены как **held**). ## Как используется курс {#how-a-rate-is-used} | Где используется | Правило | |---|---| | Кошелек и счета | Центы USD. Курс никогда не меняет баланс. | | Тарифы VM, заданные в VND | Конвертируются **один раз** по курсу, действующему на момент сохранения, и затем хранятся в USD. Последующие изменения курса не влияют на стоимость этих тарифов VM. | | Банковский перевод через Sepay | Клиент оплачивает `ceil(USD × rate)` с округлением в большую сторону до заданного шага. Платежи через Sepay **блокируются**, пока курс USD/VND не задан. | | Тарифы Bare Metal | В новых установках сразу используется USD. Существующие тарифы в VND сохраняют свою валюту цен, и для списания требуется курс; см. [Выделенные серверы](https://nexcmp.com/ru/docs/infrastructure/dedicated/). | | Другие международные платежи, введенные в VND | Округляются до ближайшего цента. | | Отображение в портале | USD умножается на опубликованный курс отображаемой валюты с форматированием для выбранного языка. | ## Проверка {#verify} 1. В **Active exchange rate** отображается значение USD/VND с недавним временем получения. 2. В таблице **Currency by language** отображаются непустые курсы. 3. В клиентском портале переключите язык на вьетнамский (валюта сайта Auto): цены отобразятся в донгах; переключите на японский: в иенах. При валюте сайта USD отображаются только доллары. 4. В форме тарифа (Plans & pricing) в списке **Enter price by** доступен вариант **VND / month**. ## Ограничения и примечания {#limits-and-notes} - Автоматическое обновление отсутствует. Нажмите **Update exchange rates**, когда понадобятся актуальные курсы, и настройте напоминание, если курсы для вас важны. - Для USD/VND используется публичный рыночный курс; это справочный курс, а не банковская котировка покупки или продажи. Остальные валюты отображения поступают из Frankfurter; данные старше 14 дней или неполная таблица отклоняются. - Маржа и фиксированный курс влияют только на USD/VND. Для 11 валют отображения маржа не применяется. - Каждому языку клиента соответствует одна валюта. Смена языка переключает ее на валюту этого языка, если только клиент не выбрал USD для того же языка. - Сайты реселлеров используют те же курсы. ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | «Новый обменный курс превышает допустимое отклонение — ON HOLD, требуется подтверждение вручную» | Скачок курса превышает установленный порог | Проверьте значение и нажмите **Apply this rate** или измените порог. | | «Сервер отклонил новый обменный курс» | Рыночное значение находится вне диапазона от 15,000 до 50,000 или имеет неверный формат | Подождите и повторите попытку или задайте фиксированный курс. | | При обновлении предлагается подождать перед повторной попыткой | Слишком частые обновления | Подождите и повторите попытку. | | «не удалось получить курс: …» | Сервер панели не может получить доступ к сервисам курсов валют | Разрешите исходящий трафик по HTTPS и повторите попытку. | | Тег **Sepay blocked** | Курс USD/VND еще не был опубликован | Нажмите **Update exchange rates** или установите фиксированный курс. | | В портале отсутствует валюта | Отсутствует ее курс | Нажмите **Update exchange rates**. | | Клиенты видят цены только в USD | Валютой сайта является USD, либо отсутствует курс | Установите **Site currency** в значение Auto и опубликуйте курсы. | | «Неполная таблица курсов Fx; сохранены предыдущие курсы» | Сервис Frankfurter вернул менее 11 валют | Повторите попытку позже; изменения не внесены. | | В форме тарифа отсутствует опция VND | Отсутствует курс USD/VND | Сначала опубликуйте курс. | --- # Платежные каналы {#payment-channels} > **В панели администратора:** Finance › Payment channels (`/payments`). Переключатели и комиссии: Finance › Payment channels › Fees & limits (`/payments/fees`). В NexCMP используется **предоплатный USD-кошелек**. Клиенты пополняют кошелек через платежный канал; затем все услуги оплачиваются с этого кошелька. Канал отображается клиентам только тогда, когда он одновременно **включен** и **настроен**. ## Назначение {#what-it-does} Платежные каналы связывают ваши платежные аккаунты (Stripe, PayPal, Binance, вьетнамский банк) с кошельком клиента. Подтвержденный платеж формирует ровно одно зачисление на кошелек — каждое зачисление привязано к ID платежа в шлюзе, поэтому повторный вебхук никогда не зачислит средства дважды. Используйте эту страницу, чтобы увидеть, какие каналы готовы к работе, каковы их показатели за последние 30 дней и какие из них требуют внимания. ## Требования {#requirements} | Параметр | Требование | |---|---| | Публичный HTTPS-адрес | Шлюзы отправляют вебхуки на `https:///v1/billing/...`, поэтому ваша панель должна быть доступна из Интернета с действительным TLS-сертификатом (см. [DNS и Cloudflare](https://nexcmp.com/ru/docs/getting-started/dns-and-cloudflare/)). | | Учетные записи | Собственный аккаунт у каждого используемого провайдера. Учетные данные вводятся в панели администратора и больше никогда не отображаются (показываются только последние 4 символа). | | Роль администратора | Учетная запись администратора. | | Зависимости | Нет. Для банковского канала VN дополнительно требуется [exchange rate](https://nexcmp.com/ru/docs/catalog/currency-and-exchange-rates/). | ## Каналы {#the-channels} | Канал | Что видит клиент | Где настраивается | Статья | |---|---|---|---| | Card (Stripe) | Форма карты, сохраненная карта | Payment channels › Stripe | [Stripe](https://nexcmp.com/ru/docs/billing/stripe/) | | Apple Pay, Google Pay, Link | Кнопки кошельков (Stripe Express Checkout) | Stripe, плюс регистрация домена | [Stripe](https://nexcmp.com/ru/docs/billing/stripe/#apple-pay-google-pay-and-link) | | Alipay | Перенаправление в Alipay (списание через Stripe в JPY) | Stripe, плюс Fees & limits | [Stripe](https://nexcmp.com/ru/docs/billing/stripe/#alipay) | | PayPal | Кнопки PayPal, сохраненный аккаунт PayPal | Payment channels › PayPal | [PayPal](https://nexcmp.com/ru/docs/billing/paypal/) | | USDT | Адрес для пополнения и точная сумма | Payment channels › USDT | [USDT](https://nexcmp.com/ru/docs/billing/usdt/) | | VN bank transfer | QR-код и реквизиты перевода (только в интерфейсе на вьетнамском языке) | Payment channels › VN bank transfer | [Bank transfer (Vietnam)](https://nexcmp.com/ru/docs/billing/bank-transfer-vn/) | ## Подготовка инфраструктуры {#prepare-the-infrastructure} Не требуется. Все настраивается в панели администратора; на сервер устанавливать ничего не нужно. ## Подключение в NexCMP {#connect-in-nexcmp} 1. Перейдите в **Finance › Payment channels** (`/payments`). В сводной таблице перечислены все каналы и их состояние. 2. Откройте вкладку нужного канала (**Stripe**, **PayPal**, **USDT**, **VN bank transfer**) и следуйте указаниям в соответствующей статье. Каждая вкладка содержит кнопку **Save** и, если применимо, кнопку **Test**. 3. Перейдите в **Fees & limits** (`/payments/fees`), найдите блок **Payment gateways & fees (wallet top-up)**, включите канал с помощью переключателя и нажмите **Save channels & fees**. ![Обзор каналов оплаты со списком шлюзов, статусами активации и настройки, а также статистикой за 30 дней](https://nexcmp.com/ru/docs/images/billing/payment-channels-01-overview.webp) ![Страница комиссий и лимитов с переключателями каналов и полями комиссий](https://nexcmp.com/ru/docs/images/billing/payment-channels-02-fees.webp) ### Переключатели и комиссии (Fees & limits) {#switches-and-fees-fees-limits} | Настройка | По умолчанию | Значение | |---|---|---| | Card (Stripe) | On | Форма ввода карты на экране пополнения. Скрыта, пока для Stripe не указан секретный ключ. | | Apple Pay, Google Pay, Link | On | Кнопки кошельков. Отображаются только после подтверждения домена в Stripe. | | Alipay | Выкл | Требуется активация Alipay в Stripe Dashboard. | | PayPal | Выкл | Отображается только после настройки PayPal. | | USDT (Binance) | Выкл | Переключатель заблокирован, пока адрес для пополнения не будет проверен через Binance. | | Комиссия Stripe: % / фиксированная (в центах) | 3.6 % и 0 | Используется для отображения комиссии клиенту и расчета зачисляемой суммы. Укажите ваш фактический тариф Stripe. | | Комиссия PayPal: % / фиксированная | 4.4 % и 30 cents | То же самое для PayPal. | | USDT fee % | 1 % | То же самое для USDT. | | Клиент оплачивает комиссию за пополнение | Выкл | **On**: клиент оплачивает сумму + комиссию, и на баланс зачисляется полная сумма. **Off**: комиссия вычитается, и на баланс зачисляется сумма за вычетом комиссии. | Клиент всегда видит комиссию и итоговую сумму зачисления перед оплатой. Отключение канала скрывает кнопку, и сервер отклоняет новые платежи с `method_disabled` (HTTP 403). ::: tip Лимиты на пополнение Минимальная и максимальная сумма одного пополнения настраиваются на той же странице — см. [Minimum top-up](https://nexcmp.com/ru/docs/billing/minimum-top-up/). ::: ## Проверка {#verify} 1. В обзорной таблице для канала отображается **Enabled** и **Configured**; колонка **Last test** заполняется после нажатия **Test** на вкладке канала. 2. Войдите в портал под тестовым клиентом и откройте **Billing › Deposit**. Кнопка канала отображается. 3. Совершите небольшой платеж (тестовые карты и тестовые аккаунты описаны в статье канала). Баланс пополнится, появится уведомление **Top-up received**, а платеж отобразится в **Finance › Billing › Top-ups** (`/billing/deposits`). ## Ограничения и примечания {#limits-notes} - **Колонки обзора:** *30 days* (количество платежей, успешных, неудачных и общий объем), *Stuck 24h* (платежи в обработке более суток) и *Unmatched* (поступившие переводы USDT или банковские платежи без привязки к заказу). В строке KPI суммируются объем за 30 дней, количество проблемных каналов (включены без настройки или содержат зависшие платежи) и общее число нераспознанных платежей. - **События вебхуков** перечислены в **Payment channels › Gateway events** (`/payments/events`). У Stripe есть отдельная вкладка, а PayPal и USDT используют общую. Неудачное событие можно повторить — реестр кошелька идемпотентен, поэтому повторный запуск никогда не приведет к двойному зачислению. - **Resellers** могут использовать собственные каналы Stripe, PayPal, USDT и банковские переводы. Их строки также отображаются здесь, а селектор сайтов в шапке фильтрует их. См. [Resellers](https://nexcmp.com/ru/docs/customers/resellers/). - **Возвраты:** платежи Stripe и PayPal можно вернуть из списка платежей; платежи в USDT нельзя вернуть обратно источнику (сервер отвечает `usdt_no_refund`). - **Maintenance mode** по-прежнему принимает вебхуки шлюзов, поэтому платеж, совершенный непосредственно перед обслуживанием, не будет потерян. ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | Канал отсутствует на экране пополнения у клиента | Отключен, не настроен или (для вьетнамского банка) выбран не вьетнамский язык интерфейса | Проверьте **Fees & limits** и вкладку канала; см. [Bank transfer (Vietnam)](https://nexcmp.com/ru/docs/billing/bank-transfer-vn/). | | Показатель KPI **Faulty channels** больше 0 | Канал включен без учетных данных либо платежи ожидают обработки более 24 часов | Откройте строку и нажмите **Configure**; для зависших платежей откройте **Gateway events** и выполните повтор. | | Клиент оплатил счет, но баланс не изменился | Вебхук не поступил | Проверьте URL вебхука на вкладке канала, затем повторите событие в **Gateway events**. | | Сервер отвечает `method_disabled` | Переключатель выключен | Включите его в **Fees & limits** и сохраните изменения. | | Переключатель USDT неактивен | Адрес для пополнения не верифицирован | Нажмите **Test & verify address** на вкладке USDT. | --- # Stripe > **Где найти в панели:** Finance › Payment channels › Stripe (`/payments/stripe`). Переключатели и комиссии: Finance › Payment channels › Fees & limits (`/payments/fees`). ## Назначение {#what-it-does} Stripe принимает платежи с карт для пополнения баланса. С тем же аккаунтом вы можете подключить **Apple Pay**, **Google Pay**, **Link** и **Alipay**, а также позволить клиентам **сохранять карту** для [автоматического пополнения](https://nexcmp.com/ru/docs/billing/auto-top-up/). Используйте его как основной канал для международных клиентов. ## Требования {#requirements} | Параметр | Требование | |---|---| | Аккаунт Stripe | Аккаунт Stripe с возможностью принимать платежи в **USD**. Платежи через Alipay списываются в JPY и должны быть активированы со стороны Stripe для вашего аккаунта. | | Ключи | Секретный ключ (`sk_live_...` или `sk_test_...`) и публичный ключ (`pk_live_...` или `pk_test_...`). Форма принимает только ключи с этими префиксами. | | Сеть | Панель управления должна быть доступна по HTTPS из интернета (для входящих webhook от Stripe) и иметь исходящий доступ к `api.stripe.com` по порту 443. | | Домен (только для кошельков) | Клиентский домен должен отдавать `/.well-known/apple-developer-merchantid-domain-association` — NexCMP настраивает это автоматически. | | Зависимости | Нет. | ::: info Использование одного аккаунта Stripe NexCMP обрабатывает события webhook только для платежей, созданных им самим, поэтому вы можете использовать аккаунт Stripe параллельно с другими приложениями. ::: ## Подготовка инфраструктуры {#prepare-the-infrastructure} На стороне Stripe: 1. Войдите в [Stripe Dashboard](https://dashboard.stripe.com). Включите или отключите **Test mode** в зависимости от того, проводите ли вы тестирование или запускаете приём платежей. Ключи одного режима не подходят для другого. 2. Перейдите в **Developers › API keys**. Скопируйте **Publishable key**, затем откройте и скопируйте **Secret key**. Храните секретный ключ в безопасности. 3. (Необязательно) Перейдите в **Settings › Payment methods** и активируйте **Alipay**, если хотите принимать этот способ оплаты. 4. Создавать webhook вручную **не требуется** — NexCMP сделает это автоматически (см. шаг 5 ниже). Если вы предпочитаете ручную настройку, создайте endpoint в **Developers › Webhooks** с URL и событиями, указанными в разделе [Webhook](#webhook). ## Подключение в NexCMP {#connect-in-nexcmp} 1. Откройте **Finance › Payment channels › Stripe** (`/payments/stripe`). 2. В блоке **API keys** выберите **Mode** (`live` или `test`), вставьте **Secret key** и **Publishable key**. 3. Нажмите **Save**. Ключи сохраняются в конфигурационном файле на сервере, доступном только сервисной учётной записи NexCMP. Они никогда не передаются обратно в браузер; в дальнейшем на странице отображаются только последние 4 символа. 4. Нажмите **Check**. В диалоговом окне отобразятся статус подключения, режим, доступный и ожидающий баланс, ID аккаунта, доступность списаний, наличие webhook и поддержка Alipay. Красная строка означает, что соответствующий пункт требует внимания. 5. В блоке **Webhook** нажмите **Create webhook** и подтвердите действие. NexCMP запросит у Stripe создание endpoint со всеми необходимыми событиями и автоматически подставит **Webhook signing secret** (`whsec_...`). Предзаполненный в поле URL имеет формат `https:///v1/billing/stripe/webhook`, например `https://cloud.example.com/v1/billing/stripe/webhook`. 6. Откройте **Fees & limits** (`/payments/fees`), оставьте включённым **Card (Stripe)**, укажите ваши фактические тарифы в полях **Stripe fee %** и **Stripe fixed fee (cents)**, после чего нажмите **Save channels & fees**. См. [Payment channels](https://nexcmp.com/ru/docs/billing/payment-channels/#switches-and-fees-fees-limits). ![Страница Stripe с заполненными тестовыми значениями режима, секретного и публичного ключей](https://nexcmp.com/ru/docs/images/billing/stripe-01-keys.webp) ### Webhook {#webhook} Красный баннер «Missing webhook_secret» отображается до тех пор, пока не сохранён секрет подписи. Без него пополнения через Stripe **не зачисляются**, даже если средства были успешно списаны со стороны Stripe. | Параметр | Значение | |---|---| | URL | `https:///v1/billing/stripe/webhook` | | События | `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` | | Подпись | Заголовок Stripe `Stripe-Signature`, HMAC-SHA256, допустимое отклонение времени — 300 секунд. Запросы с некорректной подписью получают HTTP 400. | | Идемпотентность | Каждый ID события сохраняется один раз; повторная доставка никогда не приводит к повторному зачислению средств. | Если вы выполнили обновление с версии, регистрировавшей меньшее число событий, нажмите **Create webhook** повторно — старый endpoint сохранится, поэтому после этого удалите его вручную в Stripe Dashboard. Строки **24h events** и **Latest event** в карточке Webhook показывают, доходят ли запросы Stripe до панели. Отдельные события перечислены в **Payment channels › Gateway events** (`/payments/events`, вкладка Stripe), где каждое событие можно просмотреть (**Payload**) или повторить (**Replay**). ### Apple Pay, Google Pay и Link {#apple-pay-google-pay-and-link} 1. В карточке **Wallets (Apple Pay · Google Pay · Link) & Alipay** поле **Customer app Domain registered with Stripe** предварительно заполнено хостом вашего сайта (например, `cloud.example.com`). 2. Нажмите **Register / verify domain** и подтвердите действие. NexCMP зарегистрирует домен в Payment method domains в Stripe и запросит у Stripe его проверку. 3. Результат покажет статус для **Apple Pay**, **Google Pay** и **Link**. Apple Pay отображается только тогда, когда статус равен `active`. 4. В **Fees & limits** оставьте опцию **Apple Pay · Google Pay · Link** включенной. ![Карточка Wallet с зарегистрированным доменом и статусами Apple Pay, Google Pay и Link](https://nexcmp.com/ru/docs/images/billing/stripe-03-wallets.webp) ::: tip Apple Pay остается неактивным Для работы Apple Pay необходимо, чтобы файл подтверждения домена возвращал HTTP 200 на вашем публичном домене. Если перед панелью используется Cloudflare или другой прокси, не блокируйте `/.well-known/`. ::: ### Alipay {#alipay} Alipay подключается по желанию. Включите его в **Stripe Dashboard › Settings › Payment methods**, нажмите **Check** и дождитесь подтверждения доступности Alipay, затем включите **Alipay (Stripe, JPY display)** в **Fees & limits**. Задайте **Alipay fee %**, **Alipay fixed fee**, курс **¥/USD rate** (50–500) и спред **FX spread %** (0–20). Регулярно обновляйте курс ¥/USD: если он старше 7 дней, на странице появится предупреждение. ## Проверка {#verify} 1. В тестовом режиме войдите в портал под тестовым клиентом, откройте **Billing**, нажмите **Deposit**, выберите **Card** и внесите минимальную сумму с помощью тестовой карты Stripe `4242 4242 4242 4242` (любая дата в будущем, любой CVC). 2. Баланс пополнится в течение нескольких секунд, а платеж появится в **Finance › Billing › Top-ups** со статусом *Completed*. 3. Откройте **Payment channels › Gateway events › Stripe**: там должны отображаться `checkout.session.completed` или `payment_intent.succeeded` со временем обработки. 4. При возврате на страницу Stripe значение **24h events** должно быть больше 0. Перед запуском в продакшн переключите **Mode** на `live`, вставьте боевые ключи и снова нажмите **Create webhook** (вебхуки для тестового и боевого режимов настраиваются раздельно). ## Ограничения и примечания {#limits-notes} - **Суммы и валюта.** Кошельки ведутся в USD. Платежи картой, через кошельки и Link списываются в USD; Alipay отображается клиенту в JPY и конвертируется по вашему курсу. - **Комиссии.** Реальная комиссия Stripe не считывается автоматически; размер комиссии, который видит клиент и который зачисляется на кошелек, определяется заданным вами процентом. Выберите **Customer pays top-up fee** в *Fees & limits*, чтобы взимать комиссию сверх суммы пополнения. - **Сохраненные карты.** Если клиент отмечает *Save card for auto top-up*, данные карты сохраняются на стороне Stripe, а не на вашем сервере. См. [Saved payment methods](https://nexcmp.com/ru/docs/billing/saved-payment-methods/). - **Возвраты.** Возврат средств на карту выполняется в два этапа: администратор создает запрос на возврат для завершенного платежа (**Finance › Billing › Top-ups**, действие возврата для платежа), а затем подтверждает его в **Finance › Payouts › Card refunds** (`/billing/payouts`). Возвраты Alipay асинхронны; при неудачном возврате (`refund.failed`) удержанная сумма возвращается на кошелек. - **Споры (Disputes).** При `charge.dispute.created` NexCMP блокирует аккаунт клиента, приостанавливает его предоплаченные услуги (данные не удаляются) и отправляет оповещение администратору. В случае выигрыша спора (`charge.dispute.closed`) сумма возвращается на кошелек. - **Ожидающие платежи.** Если вебхук не поступил, NexCMP самостоятельно сверяет со Stripe платежи, остающиеся в статусе pending более 10 минут, и завершает их. Платежи старше 7 дней игнорируются. - **Resellers** могут подключить собственный аккаунт Stripe (вебхук `https:///v1/billing/stripe/webhook/r/`); см. [Resellers](https://nexcmp.com/ru/docs/customers/resellers/). ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | "Секретный ключ должен начинаться с sk_live_/sk_test_" | Вставлен неверный ключ | Вставьте секретный ключ из **Developers › API keys**. | | «Секретный ключ не соответствует режиму live/test» | Несоответствие режима и ключа | Приведите **Mode** в соответствие с префиксом ключа. | | «Публикуемый ключ должен начинаться с pk_» | Неверный ключ | Используйте publishable key. | | Проверка сообщает об ошибке подключения | Неверный ключ, ключ отозван или сервер не может связаться с `api.stripe.com` | Вставьте ключ заново; проверьте подключение с помощью `curl -I https://api.stripe.com` с сервера. | | Красный баннер «Missing webhook_secret» | Секрет подписи не сохранен | Нажмите **Create webhook** или вставьте секрет `whsec_...` из Stripe Dashboard и нажмите **Save**. | | Средства списаны, но баланс не изменился | Вебхук не доставлен или подпись не проходит проверку | Убедитесь, что URL заканчивается на `/v1/billing/stripe/webhook`, секрет соответствует эндпоинту, и повторите событие в **Gateway events**. В Stripe откройте эндпоинт и проверьте попытки доставки (HTTP 400 означает неверный секрет подписи). | | Сбой «Create webhook» | URL не использует HTTPS или недоступен | Используйте ваш публичный домен `https://`. | | Статус Apple Pay не активен | Домен не подтвержден | Нажмите **Register / verify domain** повторно после того, как файл подтверждения домена начнет возвращать ответ 200. | | Alipay недоступен в окне Check | Не активирован в Stripe | Активируйте его в Stripe Dashboard, затем нажмите **Check**. | | Клиент не видит форму карты | Способ **Card (Stripe)** отключен или не указан secret key | Включите его в **Fees & limits** и сохраните ключи. | --- # PayPal > **Раздел в панели управления:** Finance › Payment channels › PayPal (`/payments/paypal`). Переключатель активности и комиссии находятся в Finance › Payment channels › Fees & limits (`/payments/fees`). ## Назначение {#what-it-does} Позволяет клиентам пополнять баланс в USD со счета PayPal, банковского счета или привязанной карты. Клиенты также могут разрешить NexCMP сохранить аккаунт PayPal для [автоматического пополнения](https://nexcmp.com/ru/docs/billing/auto-top-up/). Используйте этот способ вместе со [Stripe](https://nexcmp.com/ru/docs/billing/stripe/) для клиентов, предпочитающих PayPal. ## Требования {#requirements} | Параметр | Требование | |---|---| | Аккаунт PayPal | Аккаунт PayPal **Business** с возможностью приема USD. | | REST-приложение | Одно REST-приложение в PayPal Developer Dashboard (**Apps & Credentials**), предоставляющее **Client ID** и **Client secret**. Используйте вкладку **Sandbox** для тестирования и **Live** для рабочей среды. | | Сеть | Доступность по HTTPS из Интернета (PayPal отправляет запросы к вебхуку) и исходящий доступ к `api-m.paypal.com` (live) или `api-m.sandbox.paypal.com` (sandbox), порт 443. | | Права доступа | REST-приложению требуются разрешения на возврат средств и работу с вебхуками. В диалоговом окне **Check** отображается наличие обоих разрешений. | | Зависимости | Нет. | ## Подготовка инфраструктуры {#prepare-the-infrastructure} 1. Войдите на [developer.paypal.com](https://developer.paypal.com) с учетной записью Business и откройте **Apps & Credentials**. 2. Выберите **Sandbox** (тестирование) или **Live**, затем нажмите **Create App**. Укажите имя, например «NexCMP». 3. Скопируйте **Client ID** и **Secret** приложения. 4. Для тестирования используйте раздел **Testing Tools › Sandbox Accounts**, чтобы найти или создать тестовый аккаунт *Personal* (покупатель). 5. Вам не нужно создавать вебхук вручную: NexCMP создает его с помощью кнопки **Create webhook**. ## Подключение в NexCMP {#connect-in-nexcmp} 1. Откройте **Finance › Payment channels › PayPal** (`/payments/paypal`). 2. В разделе **API keys** выберите **Mode**: `live` (реальные средства, `api-m.paypal.com`) или `sandbox` (`api-m.sandbox.paypal.com`). 3. Вставьте **Client ID** (не менее 20 символов) и **Client secret**. 4. Нажмите **Check**. Проверяются введенные учетные данные (сохранять не требуется) и выводятся сведения о подключении, App ID, режиме, наличии разрешений refund и webhooks, а также сроке действия токена. 5. Нажмите **Save**. 6. В карточке **Webhook** убедитесь, что URL указан как `https:///v1/billing/paypal/webhook` (должен быть `https`), затем нажмите **Create webhook** и подтвердите действие. NexCMP запрашивает у PayPal создание или обновление вебхука с 11 событиями и сохраняет полученный **Webhook ID**. Кнопка использует **сохраненные** ключи — сохраните изменения, если вы только что их редактировали. 7. Снова нажмите **Check**: в строке **Webhook** должно быть указано «exists, 11 events». 8. Откройте **Fees & limits**, включите **PayPal**, укажите значения **PayPal fee %** (по умолчанию 4.4) и **PayPal fixed fee (cents)** (по умолчанию 30) согласно вашему тарифу и нажмите **Save channels & fees**. ![Страница PayPal с включенным режимом sandbox и введенными тестовыми учетными данными](https://nexcmp.com/ru/docs/images/billing/paypal-01-keys.webp) ### События вебхука {#webhook-events} NexCMP регистрирует следующие 11 событий: `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`. Каждый вебхук проверяется через API верификации подписи PayPal, сохраняется один раз и обрабатывается идемпотентно. NexCMP никогда не доверяет сумме из тела вебхука: перед зачислением средств он запрашивает данные о списании напрямую у PayPal. ## Проверка {#verify} 1. Оставьте **Mode** в значении `sandbox`. В клиентском портале откройте **Billing › Deposit**, выберите **PayPal**, нажмите **Continue on PayPal** (или кнопку PayPal) и выполните вход под тестовым аккаунтом покупателя sandbox. 2. Подтвердите платеж. Вы вернетесь в портал, баланс увеличится, а платеж появится в разделе **Finance › Billing › Top-ups** со статусом *Completed*. 3. Откройте **Payment channels › Gateway events › PayPal & USDT**: событие `PAYMENT.CAPTURE.COMPLETED` появится в списке. 4. Убедившись, что все работает, переключите **Mode** на `live`, введите боевые учетные данные, нажмите **Save**, а затем снова **Create webhook** (вебхуки для sandbox и live настраиваются отдельно). ## Ограничения и примечания {#limits-notes} - **Как завершается платеж.** Заказ создается в USD; после подтверждения клиентом **сервер** выполняет списание (с идемпотентным request ID) и начисляет средства на баланс ровно один раз. Вебхук и фоновая сверка каждые 10 минут служат страховкой на случай, если клиент закроет браузер. - **Незавершенные и брошенные заказы.** Заказ может оставаться открытым в течение 12 часов. У клиента может быть не более 5 незавершенных заказов одновременно (сервер возвращает `too_many_pending`, HTTP 429). Заказ, списание по которому не произошло в течение 24 часов, помечается как неудавшийся. - **Вебхук не настроен.** Панель отвечает кодом HTTP 503 на все вебхуки PayPal до тех пор, пока не сохранен Webhook ID. Списания через портал и сверка каждые 10 минут по-прежнему зачисляют средства на баланс, однако любые события, передаваемые PayPal через вебхук (споры, возвраты, задержанные списания), не будут обработаны — нажмите **Create webhook**. - **Сохраненный аккаунт PayPal.** Когда клиент решает сохранить PayPal (или выполняет первое пополнение, включающее [автоматическое пополнение](https://nexcmp.com/ru/docs/billing/auto-top-up/)), PayPal сохраняет платежный токен в своем хранилище. NexCMP хранит только идентификатор и e-mail учетной записи PayPal. См. [Сохраненные способы оплаты](https://nexcmp.com/ru/docs/billing/saved-payment-methods/). - **Возвраты и споры** обрабатываются так же, как в Stripe: запросы на возврат подтверждаются в разделе **Finance › Payouts › Card refunds**; при возникновении спора аккаунт клиента блокируется, а предоплаченные услуги приостанавливаются до его урегулирования. - **Комиссии.** Фактическая комиссия PayPal не запрашивается из сервиса; процентная ставка и фиксированная комиссия, заданные в настройках, определяют, какую сумму увидит клиент и сколько будет зачислено. Реальный тариф зависит от вашей страны (в подсказке к форме указано 4.4 % для Вьетнама и 3.49 % для США). ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | «Client ID слишком короткий» | Вставлено менее 20 символов | Скопируйте Client ID полностью. | | «Webhook URL должен использовать https» | В URL указан `http://` | Используйте ваш публичный домен `https://`. | | Check сообщает об ошибке подключения | Неверный режим (боевые ключи в sandbox или наоборот), неверный secret, нет исходящего доступа | Сопоставьте **Mode** с типом ключа; проверьте `curl -I https://api-m.paypal.com` с сервера. | | В разрешениях refund / webhooks указано «no» | У REST-приложения нет необходимых разрешений | Включите эти функции для приложения в PayPal Developer Dashboard. | | Баннер «PayPal key set, NO webhook» | Отсутствует Webhook ID | Нажмите **Create webhook**. | | «Webhook not found» в Check | Вебхук был удален в PayPal или принадлежит другому приложению | Снова нажмите **Create webhook**. | | Клиент получает сообщение, что PayPal отклонил платеж | PayPal отклонил выбранный способ оплаты | Попросите клиента выбрать другой способ оплаты. | | Клиент видит ошибку «Too many pending requests» | 5 открытых заказов | Дождитесь истечения их срока действия или завершите их. | | Отсутствует кнопка PayPal | PayPal отключен в **Fees & limits** или не настроен | Включите его и сохраните учетные данные. | --- # USDT (Binance) {#usdt-binance} > **Раздел в панели управления:** Finance › Payment channels › USDT (`/payments/usdt`). Переключатель и комиссия: Finance › Payment channels › Fees & limits (`/payments/fees`). Нераспознанные депозиты: Finance › Payment channels › Gateway events › PayPal & USDT (`/payments/events?tab=gateways`). ## Назначение {#what-it-does} Клиенты переводят USDT на **ваш адрес депозита в Binance**; NexCMP считывает историю депозитов через API-ключ Binance **только для чтения** и пополняет кошелек, когда депозит совпадает с открытым запросом. С вашей стороны нет комиссий платежного шлюза, кроме комиссий самой платформы Binance, а приватные ключи никогда не хранятся в NexCMP. ## Требования {#requirements} | Параметр | Требование | |---|---| | Аккаунт Binance | Верифицированный аккаунт Binance с включенным приемом депозитов в USDT в выбранной сети. | | API-ключ | API-ключ Binance только с правом **Enable Reading**. Права Enable Withdrawals, Internal Transfer и Spot/Margin Trading должны быть **отключены**. | | Ограничение по IP | Настоятельно рекомендуется: ограничьте ключ исходящим IP-адресом сервера (он отображается в окне **Test & verify address**). | | Сеть | Исходящий HTTPS к `api.binance.com`. Открывать входящие порты не требуется. | | Поддерживаемые сети | `TRX` (Tron, TRC20), `BSC` (BNB Smart Chain, BEP20), `SOL` (Solana), `ETH` (Ethereum, ERC20). Валюта фиксирована: USDT. | | Зависимости | Нет. | ::: warning Выберите сеть один раз Клиенты, отправившие средства через неподдерживаемую сеть, потеряют их. Выберите сеть с низкими комиссиями, которую поддерживают биржи ваших клиентов (обычно это TRX и BSC), и старайтесь не менять ее часто. ::: ## Подготовка инфраструктуры {#prepare-the-infrastructure} 1. В Binance откройте **Account › API Management** и создайте новый API-ключ (system generated). Укажите метку, например «NexCMP». 2. Отредактируйте разрешения: оставьте включенным только **Enable Reading**. Не включайте разрешения на вывод средств, переводы или торговлю. 3. В разделе **Restrict access to trusted IPs only** укажите публичный IP-адрес вашего сервера NexCMP. Если он вам пока неизвестен, создайте ключ без ограничений, выполните первый тест в NexCMP (он выведет исходящий IP) и затем добавьте этот IP-адрес. 4. Скопируйте **API key** и **Secret key** (секретный ключ отображается только один раз). 5. Перейдите в **Wallet › Deposit › Crypto**, выберите **USDT** и используемую **сеть**, после чего скопируйте **адрес для депозита** (например, адрес `T...` в сети TRX или `0x...` в BSC/ETH). ## Подключение в NexCMP {#connect-in-nexcmp} 1. Перейдите в **Finance › Payment channels › USDT** (`/payments/usdt`). 2. В блоке **API key (Binance › API Management)** вставьте **API key** и **API secret**. Оба значения необходимо указывать одновременно. 3. В поле **Deposit address** выберите **Network** и вставьте **адрес для депозита USDT в выбранной сети**. Формат сверяется с требованиями сети (`T` + 33 символа для TRX, `0x` + 40 шестнадцатеричных символов для BSC и ETH, base58 для SOL). 4. Нажмите **Save**. Изменение адреса или сети сбрасывает верификацию и приостанавливает работу канала до повторной проверки; страница запросит подтверждение. 5. Нажмите **Test & verify address**. (Несохраненные изменения отклоняются — проверка выполняется по сохраненной конфигурации.) В диалоговом окне отображаются: - разрешения ключа (чтение, вывод средств, внутренние переводы, торговля, ограничение по IP) — опасные разрешения выделяются красным предупреждением; - исходящий IP-адрес сервера (для ввода в Binance); - состояние сети (депозиты открыты или закрыты, требуемое число подтверждений, dust); - адрес, выданный Binance для этой сети, и его **совпадение** с вашим. 6. Когда адрес совпадет, NexCMP зафиксирует время верификации. Только после этого можно открыть **Fees & limits**, включить **USDT (Binance)**, проверить **USDT fee %** (по умолчанию 1) и **USDT request expires after (mins)** (5–180, по умолчанию 30), а затем нажать **Save channels & fees**. ## Как сопоставляется платеж {#how-a-payment-is-matched} 1. Клиент указывает сумму в **Billing › Deposit › USDT** и нажимает **Get deposit address**. 2. NexCMP создает запрос и показывает адрес, сеть и **точную сумму** с шестью знаками после запятой — например, `19.173742`. Последние четыре знака представляют собой случайный nonce, делающий сумму уникальной для этого запроса. 3. Клиент должен отправить **ровно** указанную сумму в выбранной сети. Платеж, который не совпадает (округленная сумма, неверная сеть), не может быть зачислен автоматически. 4. Каждые 60 секунд NexCMP опрашивает входящие депозиты в Binance за последние 24 часа. При совпадении депозита запрос переходит в статус *confirming*, а после набора нужного числа подтверждений в Binance средства зачисляются на баланс. Запрос, по которому зафиксировано поступление средств, не истекает, пока ожидаются подтверждения. 5. Запрос, не оплаченный в течение срока действия (по умолчанию 30 минут), помечается как истекший. ## Проверка {#verify} 1. После проверки адреса и включения USDT войдите под учетной записью тестового клиента и запросите депозит на небольшую сумму (минимальное пополнение). 2. Отправьте точную сумму с другого кошелька или биржи. Подождите несколько минут. 3. В портале отобразится статус *Transfer seen — confirming*, а затем *USDT received — balance updated*. 4. На странице USDT отображается недавнее время **Last poll** и значение 0 в **Unmatched**. ## Ограничения и примечания {#limits-notes} - **Курс.** 1 USDT = 1.00 USD. Комиссия из поля **USDT fee %** отображается клиенту и либо вычитается из суммы, либо добавляется к ней в зависимости от настройки **Customer pays top-up fee**. - **Без возвратов.** NexCMP не выполняет автоматический возврат платежей USDT на адрес отправителя (HTTP 409 `usdt_no_refund`). При необходимости оформляйте возврат вручную вне системы. - **Лимит незавершенных запросов.** Количество открытых запросов для клиента ограничено; при превышении сервер возвращает `too_many_pending` (HTTP 429). - **Resellers** могут использовать собственную учетную запись Binance; см. [Resellers](https://nexcmp.com/ru/docs/customers/resellers/). - **Если вы используете один аккаунт Binance** для нескольких систем, выделите каждой системе отдельную сеть, чтобы два поллера не обрабатывали один и тот же депозит. ### Несопоставленные депозиты {#unmatched-deposits} Депозит, не соответствующий ни одному запросу (неверная сумма, не та сеть, истекший запрос), создает событие `deposit.unmatched` и оповещение для администратора. Откройте **Payment channels › Gateway events › PayPal & USDT**, найдите событие, проверьте транзакцию на Binance и нажмите действие привязки, чтобы зачислить средства нужному клиенту. После этого счетчик **Unmatched** на странице USDT и в обзоре каналов сбросится до 0. ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | «API key и secret необходимо вводить вместе» | Заполнено только одно поле | Заполните оба поля. | | «Адрес не соответствует формату сети ...» | Адрес не соответствует выбранной сети | Скопируйте его заново из Binance для той же сети. | | «Несохраненные изменения — сначала Save, затем Test» | Тест выполняется с сохраненными настройками | Нажмите **Save**, затем протестируйте. | | Предупреждение "key has Enable Withdrawals" | Избыточные права | Удалите их в Binance API Management. | | Предупреждение "key not restricted to IP" | `ipRestrict` отключено | Добавьте исходящий IP-адрес сервера, указанный в диалоговом окне. | | Предупреждение "key lacks Enable Reading" | Недостаточно прав | Включите разрешение Enable Reading. | | Предупреждение "Binance has deposits disabled for USDT on the network" | Сеть временно недоступна | Выберите другую сеть или подождите. | | «ОПАСНО: настроенный адрес отличается от адреса, выдаваемого Binance» | Неверный адрес или сеть | Скопируйте адрес из Binance повторно для этой сети. | | Переключатель USDT неактивен в Fees & limits | Адрес не верифицирован | Выполняйте **Test & verify address**, пока адреса не совпадут. | | Клиент оплатил, но средства не зачислены | Округленная сумма или неверная сеть | Найдите событие в Gateway events и привяжите его вручную. | | Депозит обнаружен, но долго находится в ожидании | Недостаточно подтверждений сети | Подождите: пока идут подтверждения, срок действия запроса не истекает. | --- # Банковский перевод (Вьетнам) {#bank-transfer-vietnam} > **В панели администратора:** Finance › Payment channels › VN bank transfer (`/payments/bank`). Курс обмена: Finance › Payment channels › Exchange rates (`/payments/fx`). ## Назначение {#what-it-does} Позволяет клиентам пополнять баланс в USD обычным банковским переводом во вьетнамских донгах. NexCMP показывает код VietQR, реквизиты счета и уникальный **transfer memo**; [Sepay](https://sepay.vn) отслеживает поступления на ваш банковский счет и вызывает вебхук при получении средств, а NexCMP зачисляет их на баланс. Используйте этот способ, если вы работаете с клиентами во Вьетнаме. ::: info Отображается только во вьетнамском интерфейсе Оплата через банк Вьетнама предлагается клиенту только тогда, когда в портале выбран **Vietnamese**. Клиенты с любым другим языком интерфейса ее не увидят. ::: ## Требования {#requirements} | Параметр | Требование | |---|---| | Банковский счет | Вьетнамский банковский счет (или виртуальный счет Sepay, **VA**), подключенный к аккаунту Sepay на [my.sepay.vn](https://my.sepay.vn). | | Sepay | Аккаунт Sepay с включенной интеграцией webhook. | | Курс обмена валют | Должен быть задан курс USD к VND: сначала обновите его в **Exchange rates**. Без курса канал возвращает `fx_unavailable`, и клиенты не смогут начать перевод. | | Сеть | Ваша панель должна быть доступна по HTTPS, чтобы Sepay мог вызывать `https:///v1/billing/sepay/webhook`. | | Зависимости | [Валюта и обменные курсы](https://nexcmp.com/ru/docs/catalog/currency-and-exchange-rates/). | ## Подготовка инфраструктуры {#prepare-the-infrastructure} На стороне Sepay: 1. В [my.sepay.vn](https://my.sepay.vn) подключите банковский счет (или создайте VA) и убедитесь, что транзакции отображаются. 2. Определите **префикс назначения платежа** — от 2 до 5 заглавных букв, например `PAY`. NexCMP формирует назначение платежа как префикс, за которым следуют 8 случайных цифр (например, `PAY48210937`). Префикс не должен содержать `ORD`, и его не должна использовать ни одна другая система, принимающая средства на этот же счет. 3. Если в вашем аккаунте Sepay используется *payment code structure*, зарегистрируйте там тот же префикс, чтобы Sepay распознавал назначение платежа. 4. Создайте webhook позже, когда на странице NexCMP появятся URL и ключ (шаг 7 ниже). ## Подключение в NexCMP {#connect-in-nexcmp} 1. Откройте **Finance › Payment channels › Exchange rates** и нажмите **Update exchange rates**, если курс еще не сохранен. 2. Откройте **Finance › Payment channels › VN bank transfer** (`/payments/bank`). 3. В разделе **Receiving account** заполните: | Поле | Пример | Правило | |---|---|---| | Банк | `VCB` Vietcombank | Выберите из списка; BIN заполнится автоматически. | | Номер счета | `0123456789` | 4–24 цифры или заглавные буквы. | | Виртуальный счет (VA — необязательно) | | Если указано, клиенты переводят средства на VA, и он отображается в QR-коде. | | Имя владельца счета | `NGUYEN VAN A` | Без диакритики, ВЕРХНИЙ РЕГИСТР, 2–60 символов. | | Префикс назначения платежа | `PAY` | 2–5 заглавных букв, без `ORD`. | 4. В разделе **Webhook authentication** выберите **Auth method**: **HMAC-SHA256** (рекомендуется) или **API key**, и введите **Webhook key / HMAC secret** (8–200 символов). При необходимости укажите **userapi token** от Sepay; он используется только для сверки переводов, webhook по которым был утерян. 5. В разделе **Channel & limits** задайте лимиты (значения по умолчанию указаны в скобках): **Min / order** (10,000 VND), **Max / order** (200,000,000 VND), **Order expiry** (120 минут, 15–1440), **Max pending orders / account** (3, 1–10), **Reconcile every** (10 минут) и, при необходимости, **Allowed webhook IPs** (через запятую; если поле не заполнено, IP-адрес только записывается в журнал). 6. Нажмите **Save**. Красный баннер «Sepay not configured» исчезнет, как только счет, имя, префикс и ключ станут корректными. 7. Скопируйте **Webhook URL to paste into my.sepay.vn** (он имеет вид `https:///v1/billing/sepay/webhook`) с помощью **Copy**. В Sepay откройте интеграцию вебхука, вставьте URL, выберите тот же тип аутентификации и ключ и включите событие «money in». 8. Нажмите **Test connection**. Затем включите **Enable Sepay for clients (main site)** и нажмите **Save**. ![Страница VN bank transfer с примерами значений для счета получателя, префикса назначения платежа и аутентификации webhook](https://nexcmp.com/ru/docs/images/billing/bank-transfer-vn-01-config.webp) ![Блок Channel and limits с включенным переключателем Sepay и лимитами по умолчанию](https://nexcmp.com/ru/docs/images/billing/bank-transfer-vn-02-limits.webp) ### Безопасность webhook {#webhook-security} | Метод | Что должен отправлять Sepay | |---|---| | HMAC-SHA256 | Заголовок `X-SePay-Signature: sha256=`, вычисленный для `"."`; разница во времени не должна превышать 300 секунд. | | API-ключ | Заголовок `Authorization: Apikey `. | Проверяются только заголовки (тело запроса и строка параметров никогда не проверяются), при этом сравнение выполняется за константное время. Обрабатываются только входящие переводы (`transferType = in`) на настроенный счет или виртуальный счет (VA). Каждая транзакция Sepay сохраняется один раз, поэтому повторный вызов вебхука никогда не приводит к двойному зачислению. NexCMP возвращает `200 {"success":true}` даже при намеренном игнорировании транзакции, а статус HTTP 5xx — только при временных сбоях, чтобы Sepay повторил попытку. ## Как клиент производит оплату {#how-the-customer-pays} 1. В разделе **Billing › Deposit** (вьетнамский интерфейс) клиент выбирает вариант банковского перевода по Вьетнаму, указывает сумму и нажимает кнопку создания перевода. 2. NexCMP конвертирует сумму в USD по сохраненному курсу (с учетом маржи и шага округления, заданных в **Exchange rates**) и **округляет сумму в VND в большую сторону** до шага округления. 3. Клиент видит QR-код (VietQR, генерируется локально) с номером счета, банком, суммой и назначением платежа. 4. После перевода Sepay вызывает вебхук, и NexCMP начисляет `floor(VND received × 100 / rate)` центов. Курс фиксируется при создании заказа; если средства поступают после истечения срока действия заказа, применяется более высокий курс из зафиксированного и текущего. 5. Срок действия заказов истекает через **Order expiry**; для подстраховки каждые **Reconcile every** минут выполняется сверка (требуется токен userapi). ## Проверка {#verify} 1. Создайте тестовый заказ от имени клиента во вьетнамском интерфейсе. Убедитесь, что сумма, счет и назначение платежа указаны верно. 2. Переведите минимально допустимую сумму, точно указав назначение платежа. 3. В течение минуты в портале отобразится завершение пополнения, а баланс кошелька увеличится; на карточке **State** страницы банка появится время последнего вебхука. 4. Откройте **Finance › Billing › Top-ups** и убедитесь, что платеж отображается с полученной суммой в VND. ## Ограничения и примечания {#limits-notes} - **Минимум.** Минимальная сумма в VND, которую видит клиент, представляет собой большее из значений **Min / order** и эквивалента [minimum top-up](https://nexcmp.com/ru/docs/billing/minimum-top-up/) в VND. - **Незавершенные заказы.** У клиента может быть не более **Max pending orders / account** открытых заказов (по умолчанию 3). - **Повтор назначения платежа.** Повторный перевод с тем же назначением создает второй завершенный платеж по текущему курсу. - **Автоматический возврат** на банковский счет не предусмотрен. - **Комиссия.** Для этого канала нет отдельной фиксированной комиссии в **Fees & limits**; единственной корректировкой является маржа курса. - **Resellers** могут настроить собственный аккаунт; URL их вебхука заканчивается на `/v1/billing/sepay/webhook/r/`. ### Несопоставленные переводы {#unmatched-transfers} Средства, поступившие на счет, но не содержащие корректного назначения платежа, отображаются в блоке **Unmatched transactions** внизу страницы (фильтр *All channel owners* или *Master*). Уточните у клиента банковский идентификатор платежа, затем нажмите **Assign** и выберите аккаунт. Баланс кошелька пополнится по текущему курсу. ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | Баннер «Sepay not configured» | Банк, счет, имя владельца, префикс или ключ отсутствуют либо указаны неверно | Заполните карточки **Receiving account** и **Webhook authentication**. | | Баннер «USD/VND rate blocked» (`fx_unavailable`) | Курс обмена не сохранен | **Exchange rates › Update exchange rates**. | | `prefix: 2–5 capital letters, no ORD` | Недопустимый префикс | Используйте от 2 до 5 заглавных букв без `ORD`. | | Ошибка `account_name` | Диакритические знаки или строчные буквы | Используйте ЗАГЛАВНЫЕ буквы без диакритики, цифры, пробел, точку или дефис. | | `webhook_secret: 8–200 characters` | Ключ слишком короткий | Используйте не менее 8 печатных символов. | | Клиент не видит этот способ оплаты | Интерфейс не на вьетнамском языке, переключатель выключен или не задан курс | Проверьте язык, переключатель и курс. | | Клиент оплатил, но средства не зачислены | Webhook не поступил, назначение платежа изменено или указана неверная сумма | Проверьте журнал webhook в SePay; если назначение платежа было неверным, перевод будет в **Unmatched transactions**. | | Webhook возвращает ошибку 401 или 403 | Несоответствие метода аутентификации или ключа | Используйте одинаковые метод и ключ в SePay и NexCMP. | | Клиент видит ошибку «Too many pending requests» | Достигнут лимит заказов в обработке | Завершите их или дождитесь истечения срока действия. | --- # Минимальная сумма пополнения {#minimum-top-up} > **В панели администратора:** Finance › Payment channels › Fees & limits (`/payments/fees`), карточка **Wallet & top-up (Billing › Policy)**. ## Назначение {#what-it-does} Каждый платежный канал отклоняет сумму меньше **минимального пополнения** или больше **максимального пополнения за транзакцию**. Значения по умолчанию — **$10.00** и **$5,000.00**. Используйте минимум, чтобы избежать микроплатежей, комиссии шлюза за которые превышают их сумму. ## Требования {#requirements} | Параметр | Требование | |---|---| | Роль | Администратор. | | Зависимости | Нет. | ## Настройка лимитов {#set-the-limits} 1. Откройте **Finance › Payment channels › Fees & limits** (`/payments/fees`). 2. В карточке **Wallet & top-up (Billing › Policy)** измените значения **Min top-up (USD)** и **Max top-up per transaction (USD)**. 3. Нажмите **Save Wallet & top-up**. ![Карточка Wallet & top-up с минимальным пополнением 10.00 и максимальным 5000.00](https://nexcmp.com/ru/docs/images/billing/minimum-top-up-01-limits.webp) | Настройка | По умолчанию | Допустимый диапазон | Правило | |---|---|---|---| | Min top-up (USD) | $10.00 | от $0 до $10,000 | Должно быть меньше или равно максимальному значению. | | Максимальная сумма пополнения за транзакцию (USD) | $5,000.00 | от $1 до $1,000,000 | Должно быть не меньше минимального значения. | Значения сохраняются в центах (`min_topup_cents`, `max_topup_cents`). ## Где применяются лимиты {#where-the-limits-apply} | Где используется | Поведение | |---|---| | Карты, Apple/Google Pay, Link, Alipay, PayPal, USDT | Суммы вне диапазона отклоняются сервером. В клиентском портале отображается «Enter an amount between {min} and {max}». | | VN bank transfer | Сумма в VND должна укладываться в лимиты SePay, **а также** ее сумма в USD (зачисляемая на кошелек) должна быть в пределах минимума и максимума. В клиентском портале отображается больший из двух минимумов в VND. См. [Банковский перевод (Вьетнам)](https://nexcmp.com/ru/docs/billing/bank-transfer-vn/). | | [Автоматическое пополнение](https://nexcmp.com/ru/docs/billing/auto-top-up/) | Каждое автоматическое списание составляет не менее минимума и не более максимума. В фиксированном режиме указанная клиентом сумма должна быть в диапазоне от минимума до $1,000. | | Коды пополнения ([Vouchers](https://nexcmp.com/ru/docs/billing/promotions/)) | Не распространяется. | | Начисление / списание администратором | Не распространяется. | | Пополнение кошелька реселлера | Отдельный минимум (`rs_topup_min_cents`, по умолчанию $20) в разделе Resellers › Defaults. | ## Связанные минимальные пороги {#related-floors} Минимальная сумма пополнения — не единственное правило баланса. В **Services › Virtual Machines › Policy** настраиваются следующие параметры (`/vm/policy`): | Правило | По умолчанию | Значение | |---|---|---| | Минимальный баланс (`min_balance_cents`) | $5.00 | Минимальный баланс кошелька, необходимый клиенту для создания виртуальной машины. | | Квоты | Выкл | При включённых **Quotas** для создания VM также требуется баланс, покрывающий определённое количество часов работы этой VM. См. [Quotas](https://nexcmp.com/ru/docs/billing/quotas/). | ## Проверка {#verify} 1. В клиентском портале откройте **Billing › Deposit** и укажите сумму чуть ниже минимальной. Кнопка оплаты будет неактивна, и появится сообщение о допустимом диапазоне. 2. Введите минимальную сумму и убедитесь, что процесс оплаты запускается. ## Ограничения и примечания {#limits-notes} - Изменения применяются к новым платежам. Уже созданные заказы сохраняют суммы, с которыми они были сформированы. - Подсказка для клиентов («Минимум $10.00, максимум $5,000.00») и кнопки быстрого выбора суммы автоматически обновляются согласно новым лимитам. - Если отображается валюта VND (страница **Exchange rates**), минимальная сумма пересчитывается по сохранённому курсу только для отображения; баланс и лимиты остаются в USD. ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | «Минимальная сумма пополнения должна быть меньше или равна максимальной» | Перепутаны значения | Уменьшите минимальную сумму или увеличьте максимальную. | | Клиент не может оплатить небольшую сумму через банковский перевод VN | Минимальная сумма SePay в VND или минимум в USD выше | Уменьшите **Min / order** на странице банка или снизьте минимальную сумму в USD. | | Ошибка сервера `invalid_argument` при пополнении баланса | Сумма вне допустимого диапазона | Запросите сумму в пределах указанного диапазона. | --- # Сохранённые способы оплаты {#saved-payment-methods} > **В клиентском портале:** Billing › Settings (`/billing?settings=1`). **В панели администратора:** Customers › List › a customer › Overview (`/customers/`), блок **Payment** — здесь отображаются сохранённый способ и история автопополнений. ## Назначение {#what-it-does} Сохранённый способ оплаты позволяет NexCMP списывать средства с клиента **без его личного участия**, поэтому услуги не приостанавливаются из-за исчерпания средств на балансе. Он используется только функцией [автоматического пополнения](https://nexcmp.com/ru/docs/billing/auto-top-up/). Существует два типа: **карта**, сохранённая в Stripe (включая карты, используемые через Apple Pay, Google Pay или Link, если Stripe возвращает многоразовую карту), и **аккаунт PayPal**, сохранённый в хранилище PayPal vault. ## Требования {#requirements} | Параметр | Требование | |---|---| | Каналы | [Stripe](https://nexcmp.com/ru/docs/billing/stripe/) и/или [PayPal](https://nexcmp.com/ru/docs/billing/paypal/) настроены и включены. | | Сайт | Основной сайт или сайт реселлера, платежи которого принимает платформа. Сайт реселлера со своим аккаунтом Stripe не поддерживает сохранение карт. | | Клиент | Аккаунт клиента, выполнивший пополнение с помощью карты или PayPal. | ## Как сохраняется способ оплаты {#how-a-method-gets-saved} 1. Клиент открывает **Billing**, нажимает **Deposit** и оплачивает через **Card** или **PayPal**. 2. Платёж создаётся с возможностью повторного использования способа оплаты: Stripe сохраняет карту в профиле клиента в Stripe (для списаний off-session), PayPal сохраняет токен хранилища. NexCMP хранит только идентификаторы (Stripe payment-method ID и customer ID либо PayPal vault ID) и отображаемую метку, например `visa •••• 4242` или email-адрес PayPal. **Номера карт никогда не попадают на ваш сервер.** 3. После завершения платежа [автоматическое пополнение](https://nexcmp.com/ru/docs/billing/auto-top-up/) включается один раз, если клиент ранее не настраивал этот параметр. Никаких дополнительных флажков или сообщений на экране нет. Сервер фиксирует время, IP-адрес клиента и способ оплаты в качестве подтверждения. 4. В следующий раз на экране пополнения в раскрывающемся списке карт будет предложен вариант **Saved card ...**, а для PayPal — **Saved PayPal ...**. ## Управление и удаление {#manage-and-remove} 1. В клиентском портале перейдите в **Billing** и нажмите **Settings**. На панели отобразятся сохранённые способы (карта Stripe и/или PayPal) и параметры автоматического пополнения. 2. Чтобы удалить карту, нажмите **Remove card** и подтвердите действие. Stripe отвяжет карту, и **автопополнение будет отключено**. 3. Чтобы удалить PayPal, нажмите **Remove saved PayPal** и подтвердите действие. ### Интерфейс администратора {#admin-view} Откройте клиента в **Customers › List**. Карточка **Payment** на вкладке **Overview** отображает сохраненные способы оплаты (**Saved cards**), шлюз для автоматических списаний, сохраненные данные согласия (время, IP, метод) и последние 20 попыток автосписания со статусом и причиной (**Auto top-up history**). ## Проверка {#verify} 1. От имени тестового клиента внесите минимальный депозит картой. После завершения платежа откройте **Billing › Settings**: отобразятся карта и включенный переключатель автопополнения. 2. Начните еще одно пополнение: в выпадающем списке появится сохраненная карта. 3. В панели администратора на карточке клиента **Payment** отобразится та же сохраненная карта. ## Ограничения и примечания {#limits-notes} - **Stripe Link и кошельки.** Link, Apple Pay и Google Pay являются функциями Stripe. NexCMP не хранит специфичные для Link данные, а сохраняет только возвращаемый Stripe идентификатор карты. - **PayPal.** Каждое пополнение через PayPal, инициированное клиентом, требует подтверждения кликом; сохраненный PayPal используется исключительно для автопополнения. - **Сайты реселлеров.** Если реселлер использует собственный аккаунт Stripe или PayPal, сохраненные способы оплаты скрыты, а автопополнение для этого сайта недоступно. - **Диспуты и споры.** Чарджбэк по любому платежу блокирует аккаунт и останавливает предоплаченные услуги; см. [Stripe](https://nexcmp.com/ru/docs/billing/stripe/). - **Удаление последнего способа оплаты** отключает автопополнение; средства на балансе кошелька клиента сохраняются. - **Подтверждение согласия.** Запись о согласии формируется сервером (клиент не может ее изменить) и сохраняется для разрешения споров. ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | Клиент не видит кнопку Settings или сохраненную карту | Сайт использует платежный канал реселлера либо оплат картой еще не было | Пополните баланс картой или через PayPal через канал платформы. | | Отсутствует «Saved card» после оплаты через Stripe | Оплата выполнена способом, не поддерживающим повторные списания (например, Alipay) | Повторите платеж банковской картой. | | PayPal: «пока не удается сохранить этот аккаунт» | PayPal не вернул токен хранилища (vault token) | Продолжите с разовым платежом или используйте другой аккаунт PayPal. | | Автопополнение отключилось после удаления карты | Ожидаемое поведение: удаление карты отключает автопополнение | Сохраните новый способ при следующем пополнении баланса. | --- # Автопополнение {#auto-top-up} > **В панели администратора:** Finance › Payment channels › Fees & limits (`/payments/fees`), карточка **Wallet & top-up (Billing › Policy)**, раздел **Auto top-up (Stripe / PayPal)**. **В портале клиента:** Billing › Settings (`/billing?settings=1`). ## Назначение {#what-it-does} Когда баланс клиента опускается ниже нормы, NexCMP списывает средства через [сохраненный способ оплаты](https://nexcmp.com/ru/docs/billing/saved-payment-methods/) и пополняет кошелек, предотвращая приостановку услуг. Фоновая задача проверяет клиентов **каждые 5 минут**. ## Требования {#requirements} | Параметр | Требование | |---|---| | Канал | Настроен [Stripe](https://nexcmp.com/ru/docs/billing/stripe/) и/или [PayPal](https://nexcmp.com/ru/docs/billing/paypal/). | | Сохраненный способ | У клиента сохранена карта или аккаунт PayPal. | | Сайт | Основной сайт или сайт реселлера, платежи Stripe/PayPal которого принимает платформа. | | Глобальный переключатель | Параметр **Auto top-up enabled** включен (по умолчанию включен). | ## Принцип работы {#how-it-works} После **первого пополнения через Stripe или PayPal** сервер сохраняет способ оплаты и включает автопополнение в режиме **By usage** — только если клиент никогда не настраивал автопополнение сам. Дополнительного флажка на экране депозита нет; сервер фиксирует время, IP-адрес и метод в качестве подтверждения. Если позже клиент отключит автопополнение, автоматически оно больше не включится. | Режим | Триггер (баланс ниже ...) | Сумма списания | |---|---|---| | **By usage** (по умолчанию после первого пополнения) | стоимость следующих 24 часов работы сервисов (почасовые VM плюс предоплатные продления, наступающие через 24 часа), но не менее **$5** | стоимость 24 часов, округленная вверх до целого доллара: не менее [minimum top-up](https://nexcmp.com/ru/docs/billing/minimum-top-up/), не более максимального пополнения и дневного лимита | | **Fixed amount** | порог, заданный клиентом (от $1 до $500) | сумма, заданная клиентом (от минимального пополнения до $1,000 и строго больше порога) | Если запущенных сервисов нет, в режиме **By usage** списания не производятся. При сравнении с порогом учитываются только **реальные средства на балансе**. Бонусные средства по промокодам хранятся отдельно и не учитываются (см. [Promotions](https://nexcmp.com/ru/docs/billing/promotions/)). Комиссия обрабатывается как при обычном пополнении: если опция **Customer pays top-up fee** включена, с карты списывается сумма плюс комиссия, а на баланс поступает полная сумма; если выключена — на баланс зачисляется сумма за вычетом комиссии. ## Настройка глобальных лимитов {#configure-the-global-limits} 1. Откройте **Finance › Payment channels › Fees & limits** (`/payments/fees`). 2. В **Auto top-up (Stripe / PayPal)** задайте: | Настройка | По умолчанию | Диапазон | Значение | |---|---|---|---| | Auto top-up enabled | On | on или off | Значение Off немедленно останавливает все фоновые списания. | | Порог автопополнения по умолчанию (USD, резервный для фиксированного режима) | $5.00 | от $0 до $10,000 | Используется только как начальный порог в фиксированном режиме. | | Макс. число автопополнений за 24 ч на клиента | 3 | от 1 до 50 | Учитываются успешные попытки и попытки в обработке. | | Лимит суммы автопополнений за 24 ч на клиента (USD) | $500.00 | от $0 до $1,000,000 | Общая сумма автосписаний за скользящие сутки. | 3. Нажмите **Save Wallet & top-up**. ![Раздел Auto top-up страницы Fees and limits с общим переключателем и суточными лимитами](https://nexcmp.com/ru/docs/images/billing/auto-top-up-01-limits.webp) ## Что видит клиент {#what-the-customer-sees} 1. В портале клиент открывает **Billing** и нажимает **Settings**. 2. На панели отображаются сохраненные методы, переключатель on/off, режим (**By usage** или **Fixed amount**), расчетный текущий расход, сумма следующего списания и блок **Recent automatic top-ups**. 3. Переключение на **Fixed amount** позволяет указать порог и сумму. Выключение переключателя прекращает списания. ![Настройки биллинга клиента с автопополнением в режиме By usage и списком недавних автоматических пополнений](https://nexcmp.com/ru/docs/images/billing/auto-top-up-02-portal.webp) ## Проверка {#verify} 1. Под тестовым клиентом выполните первое пополнение с тестовой карты ([Stripe](https://nexcmp.com/ru/docs/billing/stripe/#verify)). Откройте **Billing › Settings**: автопополнение включено. 2. Запустите небольшую VM, чтобы появился расход, и снизьте баланс ниже порогового значения (например, через **Customers › customer › Credit / debit**). 3. Примерно через 5 минут произойдет списание. В карточке клиента **Overview › Payment** в блоке **Auto top-up history** отобразится попытка со статусом *Done*, а клиенту отправится уведомление *Top-up received*. ## Ограничения и примечания {#limits-notes} - **Одно списание за одно падение баланса.** После списания задача ожидает, пока баланс снова не поднимется выше порогового значения или не истечет время ожидания: 1 час после успешного списания, 24 часа после незавершенного платежа, 30 минут после системной ошибки. - **Дневные лимиты.** При достижении любого из дневных лимитов списание не выполняется, а в журнал записывается строка *Daily limit reached* (не чаще одного раза в 6 часов). - **Ошибки.** Отклонение карты, истекший срок действия или недостаточность средств считаются ошибкой карты. Задача повторяет попытку через 1 час, затем через 6 часов, затем через 24 часа. **После 3 последовательных ошибок карты автопополнение отключается**, а клиент получает уведомление (*Auto top-up failed*). Платеж, требующий подтверждения клиентом (например, 3-D Secure), не считается ошибкой; клиенту предлагается его подтвердить. - **Без двойных списаний.** Каждое списание блокируется атомарно при падении ниже порога и использует ключ идемпотентности на стороне шлюза. - **Удаление карты** отключает автопополнение. - **Реселлеры.** Если реселлер использует собственный платежный канал, клиент не может включить автопополнение (HTTP 403 `feature_disabled`). ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | Клиент не может включить: "Top up once with a card or PayPal" | Нет сохраненного способа оплаты | Сначала выполните одно пополнение картой или через PayPal. | | Ошибка `no_card` (422) | Для выбранного шлюза нет сохраненного способа оплаты | Выберите шлюз, у которого он есть, или сохраните способ оплаты. | | Ошибка `invalid_argument` в сумме | Режим Fixed вне допустимого диапазона | Порог $1–$500, сумма между минимальным пополнением и $1,000, сумма превышает порог. | | Списание не происходит, хотя баланс низкий | Глобальный переключатель выключен, нет запущенных сервисов в режиме By usage, достигнут дневной лимит или предыдущее списание все еще ожидает | Проверьте переключатель, историю и лимиты. | | "N неудачных попыток подряд — автопополнение отключается после 3" | Постоянные сбои при оплате картой | Клиент заменяет карту, выполнив новое пополнение. | | Статус *Needs your confirmation* | Банк требует 3-D Secure | Клиент один раз завершает обычное пополнение. | --- # Счета и книга учета {#invoices-and-ledger} > **В панели администратора:** Finance › Billing (`/billing`) с вкладками Overview, Transactions (`/billing/ledger`), Invoices (`/billing/invoices`), Top-ups (`/billing/deposits`), Payouts (`/billing/payouts`), Vouchers (`/billing/vouchers`) и Reports (`/billing/reports`). **В клиентском портале:** Billing (`/billing`). ## Назначение {#what-it-does} Каждая сумма в NexCMP хранится в центах USD и записывается один раз. Главный принцип: **книга учета кошелька** является единственным источником правды о балансе; счета, платежи пополнения и отчеты формируются на ее основе. Книга учета ведется **только на добавление** — ошибка исправляется добавлением сторнирующей записи, а не редактированием истории. ## Требования {#requirements} | Параметр | Требование | |---|---| | Роль | Администратор. | | Реквизиты продавца | Укажите юридическое наименование, налоговый идентификатор, адрес, контактный e-mail и префикс номеров счетов в **System › Settings › General**, вкладка **Seller & invoicing** (`/settings?tab=seller`), блок **Seller details (printed on invoices)**. | | Зависимости | [Payment channels](https://nexcmp.com/ru/docs/billing/payment-channels/) для входящих платежей. | ## Основные компоненты {#the-pieces} | Вкладка админ-панели | Что отображается | Типичное применение | |---|---|---| | **Overview** | Доход за сегодня и текущий месяц, итоги по журналу по типам (пополнение, списание, возврат, корректировка, ваучер), счета по статусам, ожидающие возвраты, быстрые действия, расходы по услугам за последние 30 дней | Ежедневный контроль | | **Transactions** | Журнал операций кошелька, по одной строке на каждое движение | Детализация баланса клиента | | **Invoices** | Счета и дополнительное представление **Orders** со всеми заказами по каждой услуге | Поиск документа, повторная отправка, отметка об оплате | | **Top-ups** | Платежи, полученные через платежные шлюзы | Проверка платежа, оформление возврата | | **Payouts** | Возвраты на карты, партнерские выплаты, вывод средств реселлеров | Подтверждение исходящих выплат | | **Vouchers** | Коды пополнения | См. [Promotions](https://nexcmp.com/ru/docs/billing/promotions/) | | **Reports** | Выручка, по услугам, по реселлерам | Бухгалтерский учет | ### Transactions (журнал операций) {#transactions-ledger} Колонки: время, клиент, **тип**, услуга, сумма (со знаком), VM, идентификатор, инициатор, примечание. Фильтры: тип, услуга, ID клиента, сайт (при наличии реселлеров), диапазон дат и ссылка на VM. | Тип | Значение | |---|---| | `deposit` | Пополнение через платежный шлюз | | `charge` | Списание за услугу (заказ, продление, почасовая оплата...) | | `refund` | Возврат средств на кошелек | | `adjust` | Кредитование или дебетование администратором, а также коды пополнения (идентификатор начинается с `vch:`) — в сводке ваучеры отображаются отдельной строкой | Каждая запись имеет уникальный идентификатор, например `dep:stripe:`; повторная запись с тем же идентификатором невозможна, поэтому дублирующий вебхук не приведет к повторному зачислению. Чтобы внести ручную корректировку, перейдите в **Customers › List › customer › Credit / debit**: указание причины обязательно, положительная сумма также пытается разблокировать VM, заблокированные из-за нехватки средств, а само действие требует подтверждения в два этапа. ![Вкладка Transactions со строками журнала кошелька, отображающими тип, услугу, сумму и идентификатор](https://nexcmp.com/ru/docs/images/billing/invoices-and-ledger-01-ledger.webp) ### Счета (Invoices) {#invoices} Счет формируется автоматически при покупке или продлении услуги клиентом с баланса кошелька, а также при пополнении баланса. Номера имеют вид `-<000001>` (например, `NX202610-000042`); сайты реселлеров используют собственный префикс и последовательность номеров. Изменение префикса не затрагивает уже сформированные номера. | Поле | Значения | |---|---| | Тип | Receipt, Renewal, Top-up, Manual, Refund | | Статус | Unpaid, Paid, Overdue, Cancelled, Refunded | Действия со строкой: | Действие | Действие | |---|---| | **View** / **Print** | Открывает счет; в портале его также можно распечатать или сохранить в PDF. | | **Mark paid** (только для unpaid или overdue) | Помечает счет оплаченным **без списания средств с кошелька** — используйте, если клиент оплатил счет вне NexCMP. Требуется указать причину. Для счета на продление действие также продлевает услугу и разблокирует заблокированную VM. | | **Cancel** (только для unpaid или overdue) | Аннулирует счет. Требуется указать причину. | | **Resend** | Повторно отправляет счет на e-mail. | **Create manual invoice** (кнопка в верхней части вкладки): ID клиента, от 1 до 50 строк (описание, количество, цена за единицу), необязательный VM ID, срок оплаты в днях (от 0 до 365, по умолчанию 7, необязательно), необязательное примечание. Счет создается со статусом неоплаченного; клиент видит его в **Billing › Invoice History**. Неоплаченные счета за услуги **погашаются автоматически с баланса кошелька**, как только на нем появляются средства, поэтому клиенту достаточно просто пополнить баланс. ### Пополнения (платежи) {#top-ups-payments} Одна строка на каждую попытку: время, клиент, **шлюз и метод**, тип (пополнение или автопополнение), статус (pending, completed, failed, refunded, disputed, canceled), сумма оплаты клиентом, комиссия, сумма зачисления в кошелек, референс шлюза и время завершения. Для завершенных платежей через Stripe и PayPal доступно действие **Refund**. Вебхуки можно просмотреть на страницах событий шлюзов ([Payment channels](https://nexcmp.com/ru/docs/billing/payment-channels/)). ### Выплаты {#payouts} Три вложенные вкладки: **Card refunds** (одобрение или отклонение запросов на возврат; запрос создается на основе завершенного платежа), **Affiliate payouts** (вывод партнерских комиссий) и **Reseller withdrawals** (вывод средств реселлерами). Каждое решение фиксируется в журнале аудита. ### Отчеты {#reports} **Revenue** (динамика за 30 дней, по месяцам, ведущие клиенты), **By service** и **By reseller**. ![Вкладка Reports с ключевыми показателями выручки и динамикой за 30 дней](https://nexcmp.com/ru/docs/images/billing/invoices-and-ledger-03-reports.webp) ## Что видит клиент {#what-the-customer-sees} В разделе **Billing** клиенту доступны **Balance**, **Deposit**, **Redeem code**, **Settings** (автопополнение) и история с вкладками **Invoice History**, **Payment Order**, **Ledger** и **Orders** (все услуги в одном списке с фильтрацией по сервису и типу). Для каждого счета доступны действия **View**, **Print** и **Save as PDF**; суммы указаны в USD и при необходимости отображаются в выбранной валюте. ## Проверка {#verify} 1. Выполните небольшое пополнение от имени тестового клиента. 2. В **Transactions** появится строка `deposit`, в **Top-ups** платеж отобразится со статусом *Completed*, а выручка в **Overview** увеличится. 3. Купите какую-либо услугу: появится строка `charge`, а в **Invoices** отобразится счет со статусом *Receipt* или *Renewal* с настроенными вами реквизитами продавца. ## Ограничения и примечания {#limits-notes} - **Только добавление (append-only).** Отредактировать или удалить запись в книге учета невозможно; добавьте корректировку с указанием причины. - **Валюта.** Все суммы указываются в USD; валюта отображения носит исключительно информационный характер (см. [Валюта и обменные курсы](https://nexcmp.com/ru/docs/catalog/currency-and-exchange-rates/)). - **Возврат на карту** выполняется в два этапа (запрос, затем подтверждение в Payouts); платежи в USDT и банковские переводы не возвращаются на исходный счет. - **Все действия фиксируются в аудите** в разделе System › Logs › Admin actions с указанием введенной вами причины. - **Заказы и счета.** Почасовое потребление не выставляется в счетах каждый час; в представлении Orders оно группируется по дням для удобства просмотра. ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | Баланс клиента отображается некорректно | Неожиданное списание, корректировка или ваучер | Отфильтруйте **Transactions** по ID клиента и проверьте референсы и примечания. | | «Счет уже оплачен» (409) | Попытка отметить как оплаченный уже оплаченный счет | Действий не требуется. | | Не удается отменить счет | Отменить можно только неоплаченные или просроченные счета | Для оплаченных счетов используйте возврат или корректировку. | | В счетах отсутствуют реквизиты продавца | Реквизиты не заполнены | Заполните **Seller details** в System › Settings › General › Seller & invoicing. | | Операция начисления / списания отклонена | Сумма равна нулю или превышает $100,000 | Укажите сумму от 1 цента до $100,000. | | Платеж долго остается в статусе *Pending* | Вебхук не получен | Перейдите в **Gateway events** и выполните повторную отправку. | --- # Промоакции {#promotions} > **В панели администратора:** Finance › Billing › Vouchers (`/billing/vouchers`). **В клиентском портале:** Billing › Redeem code (также доступно в панели Deposit). ## Назначение {#what-it-does} **Код пополнения** (ваучер) — это одноразовый секретный код для клиентов. В зависимости от настроек при создании он позволяет: | Тип | Что получает клиент | Куда зачисляются средства | |---|---|---| | **Bonus credit** для всех услуг | Зачисление средств на баланс | Баланс кошелька. Можно потратить на любые услуги. | | **Bonus credit** для выбранных услуг | Кредит на определенные услуги | Отдельный субсчет, с которого можно оплачивать только указанные услуги. | | **Discount %** | Процентная скидка на первый заказ выбранных услуг | Средства не начисляются; скидка применяется при оформлении заказа. | Используйте их для рекламных кампаний, компенсаций клиентам, партнерских программ или скидок на первый заказ. ## Требования {#requirements} | Параметр | Требование | |---|---| | Роль | Администратор. | | Клиенты | Клиенты активируют коды после входа в портал (гостевой доступ не поддерживается). По умолчанию требуется подтвержденный e-mail. | | Коды в VND | Код, созданный в VND, конвертируется в USD при активации по сохраненному курсу обмена (см. [Currency and exchange rates](https://nexcmp.com/ru/docs/catalog/currency-and-exchange-rates/)). | ## Создание партии кодов {#create-a-batch} 1. Откройте **Finance › Billing › Vouchers** и нажмите **Create vouchers**. 2. Заполните форму. Примеры значений указаны в скобках. | Поле | Примечания | |---|---| | Batch name | От 1 до 80 символов (`Spring welcome`). | | Target | **Main site clients**, **Single reseller's customers** (требуется список клиентов) или **Reseller wallet**. | | Eligible users | **All in target audience** или **Specified** — по одному e-mail или ID клиента на строку, до 1,000. Для клиентов реселлера необходимо выбрать *Specified*. | | 1 код на цель | При выборе *Specified* создает по одному коду на каждого указанного клиента. | | Code type | **Bonus credit** или **Discount %**. | | Applies to | Выберите одну или несколько услуг; если оставить пустым — **All services**. | | Currency, Face value | USD от $1.00 или VND от 10,000 с шагом 1,000 (только для бонусного кредита). | | Discount (%) | От 1 до 100 (только для Discount %). | | Максимальный лимит скидки (USD) | Обязательно для Discount %, от $1.00. Задает максимальный размер скидки на одну активацию. | | Minimum order (USD) | `0` = без ограничений. Первый заказ должен быть не меньше этой суммы. | | Code count | От 1 до 1,000 случайных кодов. | | Использований на код | От 1 до 100,000. `1` означает одного пользователя на код; увеличьте значение для общего кода. | | Макс. использований на аккаунт | Не менее 1. Для Discount % должно быть `1`. | | Start time (необязательно), Expires | Срок действия должен быть позже сегодняшнего дня и позже начала, максимум на 2 года вперед. | | Префикс кода (0–6 симв.) | Только буквы; если поле пустое, используется префикс сайта. | | Пользовательский код (только при count = 1) | От 6 до 32 символов A–Z и 0–9. Легко поделиться, но легко подобрать: держите лимит использований низким. | | Требовать подтвержденный email | Включено по умолчанию. | | Внутренняя заметка, Reason | Причина обязательна и записывается в журнал аудита. | 3. В форме отображается **Maximum exposure** (номинал x коды x использования), чтобы вы видели наихудший сценарий. Нажмите **Generate codes**. 4. **Скопируйте коды сейчас.** Они показываются только один раз: NexCMP хранит лишь хеш и последние 4 символа. Используйте **Copy all** или **Download CSV**, отметьте подтверждение и закройте окно. ## Как работает каждый тип {#how-each-type-behaves} ### Wallet bonus (сервисы не выбраны) {#wallet-bonus-no-service-selected} На баланс кошелька начисляется сумма записью типа **adjustment** (ссылка `vch:...`). Она не подлежит возврату на карту, не приносит партнерской комиссии, не создает счет и учитывается в балансе кошелька для квот. Для кодов в VND используется обменный курс на момент активации. ### Service credit (сервисы выбраны) {#service-credit-services-selected} - Кредит хранится на **отдельном счете**, может покрывать расходы только выбранных сервисов (новые заказы, продления, почасовые или посуточные списания, апгрейды) и расходуется **раньше** основного кошелька. - Его нельзя вывести, перевести или конвертировать в деньги, и он сгорает вместе с кодом. - В журнале операций отображается полное списание плюс соответствующая кредитная строка, поэтому учет выручки по сервису остается точным, а баланс кошелька уменьшается только на сумму, фактически уплаченную клиентом. - Он **не** повышает уровень [quota](https://nexcmp.com/ru/docs/billing/quotas/) и игнорируется функцией [auto top-up](https://nexcmp.com/ru/docs/billing/auto-top-up/). - Если списание, оплаченное кредитом или со скидкой, возвращается, покрытая кодом часть исключается из возврата на кошелек и возвращается на кредитный счет. ### Discount % {#discount} 1. Клиент вводит код: он становится **активированным**. Процентный код можно использовать только один раз на аккаунт. 2. К **первому списанию** за выбранный сервис, не являющемуся почасовой оплатой и составляющему не менее **Minimum order**, применяется скидка в процентах, но не более **Maximum discount cap**. 3. Скидка пересчитывается сервером в момент списания; сумма в браузере игнорируется. Строка активации создается в момент фактического использования кода с указанием реальной скидки. 4. К списаниям за почасовое использование код не применяется никогда. ## Действия клиента {#what-the-customer-does} 1. Откройте **Billing** в портале и нажмите **Redeem code**, или выберите **Have a top-up code?** в боковой панели Deposit. 2. Введите код (регистр не важен; дефисы необязательны) и нажмите **Check**. В портале появится информация о бонусе, например *Valid code: +$5.00*, *$5.00 credit for VPN* или *20% off voucher for Virtual Machines (up to $5.00)*, а также *Valid for orders from $10.00*. 3. Нажмите **Redeem** и подтвердите. Каждый код можно использовать один раз на аккаунт. Коды привязаны к сайту: код одного сайта «недействителен» на другом, без каких-либо указаний на то, что он существует где-то еще. Подбор кодов ограничивается по частоте, и после нескольких неудачных попыток аккаунт блокируется на несколько минут («Осталось N попыток до временной блокировки»). ## Отслеживание и отключение {#track-and-stop} - В разделе **Batches** перечислены все партии с их статусом (*active*, *disabled*, *expired*, *used up*), количеством активаций и объемом обязательств. Откройте партию, чтобы перейти на вкладки **Codes** (в маскированном виде) и **Redemptions**, а также выполнить **Export CSV**. - Вкладка **Redemptions** содержит список всех активаций по всем партиям; в **Reseller quotas** отображается, насколько израсходован ежемесячный лимит выдачи каждого реселлера; в **Settings** можно включить или отключить коды реселлеров и задать ежемесячный лимит по умолчанию. - Кнопка **Disable batch** отключает все неиспользованные коды; ранее выполненные активации сохраняются. Отключить можно и отдельный код. ## Проверка {#verify} 1. Создайте партию из 1 кода: Discount % — 20, cap — $5, минимальный заказ — $10, услуга — Virtual Machines. 2. Активируйте его от имени тестового клиента. На портале появится сообщение об успешной активации. 3. Закажите VM стоимостью не менее $10 (ежемесячный расчетный период): в инвойсе будет указана скидка (не более $5). 4. В партии у кода отобразится 1 активация с фактической скидкой. ## Ограничения и примечания {#limits-notes} - При создании коды привязываются к **audience** и **site**; перенести их позже невозможно. - Реселлеры могут выдавать коды своим клиентам в пределах ежемесячного лимита обязательств; см. [Resellers](https://nexcmp.com/ru/docs/customers/resellers/). - Промо-слайды в боковой панели для клиентов (**Marketing › Promo slides**) являются отдельной функцией и не дают скидок. - Поскольку код никогда не хранится в открытом виде, восстановить утерянную партию невозможно: отключите ее и создайте новую. ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | «Процентные промокоды: одно использование на аккаунт» (`percent_one_per_account`) | Параметр Max uses per account больше 1 для Discount % | Установите значение `1`. | | В форме указано, что лимит (cap) обязателен | Выбран Discount % без указания Maximum discount cap | Укажите не менее $1.00. | | Клиенты не найдены | В списке указан несуществующий e-mail или ID | Исправьте список (в ошибке указаны неизвестные записи). | | Клиент сообщает об ошибке «invalid code» | Другой сайт, срок действия истек, код отключен, исчерпан, предназначен другому клиенту или e-mail не подтвержден | Проверьте партию и клиента. | | Кредит не был применен | Списание относится к другой услуге | Кредит применяется только к услугам, выбранным для партии. | | Скидка не применена | Сумма заказа ниже минимальной, почасовая оплата или код был активирован для другой услуги | Оформите первый заказ, соответствующий условиям. | | Клиент заблокирован и не может активировать код | Слишком много неудачных попыток | Дождитесь окончания срока блокировки. | --- # Квоты {#quotas} > **В панели администратора:** Services › Virtual Machines › Policy › вкладка Quota (`/vm/policy?tab=quota`). Для отдельного клиента: Customers › List › a customer › Overview (`/customers/`), карточка **Quota**. **На портале:** Client › Quotas (`/client/quotas`). ## Назначение {#what-it-does} Квоты защищают от злоупотреблений со стороны новых аккаунтов: чем больше реальных средств клиент внес на кошелек, тем больше ресурсов он может создать. Предусмотрено два уровня: - **Ресурсы VM и Kubernetes**: общий объем vCPU, RAM и диска, а также количество VM. Уровнями служат ваши фиксированные тарифы. - **Квоты сервисов**: количество IP, кластеров, VPC, ГБ хранилища и т. д. на пяти уровнях (от L0 до L4), зависящих от суммы внесенных средств. Квоты проверяются **до** списания средств. Запрос, превышающий лимит, отклоняется с ошибкой HTTP 403 `quota_exceeded` и сообщением о том, какую сумму клиенту необходимо внести. ## Требования {#requirements} | Параметр | Требование | |---|---| | Роль | Администратор. | | Переключатель | Опция **Enable quota** (`quota_enabled`) по умолчанию **отключена**. Ни одно из правил ниже не действует, пока вы ее не включите. | | Фиксированные тарифы | Как минимум один некастомный тариф (см. [Plans](https://nexcmp.com/ru/docs/catalog/plans/)) — уровнями ресурсов служат ваши фиксированные тарифы. Без тарифов действует только правило по количеству VM. | | Зависимости | Строки квот сервисов отображаются только для продуктов, включенных в вашей системе (VPN, IPv6 proxy, Kubernetes, Private Cloud, Images, Object Storage, Dedicated). | ## Как рассчитывается база {#how-the-basis-is-calculated} NexCMP учитывает не только платежи по картам. **Базой** служит **фактический баланс кошелька** клиента: пополнения через шлюзы, начисления администратора (**Credit / debit**) и активированные ваучеры кошелька учитываются один раз через журнал кошелька. Скидки на заказы и сервисные бонусы по промокодам не являются средствами кошелька и не учитываются. Максимальная база, которой когда-либо достигал клиент, **сохраняется** (для каждого сайта) — расходы или возвраты никогда не понижают уже открытый уровень. ### Ресурсы VM и Kubernetes {#vm-and-kubernetes-resources} 1. Уровни представляют собой фиксированные тарифы сайта, отсортированные по стоимости их работы за 24 часа. 2. Клиент переводится на наивысший тариф, стоимость которого за 24 часа не превышает его базис. Лимитом выступают vCPU, RAM и диск этого тарифа. Клиент, который не может позволить себе даже самый дешевый тариф, все равно получает ресурсы самого дешевого тарифа. 3. В расходе ресурсов учитываются все активные VM (включая заблокированные), приобретенные дисковые тома (даже отключенные), а также воркеры и control plane кластеров Kubernetes (воркеры также считаются как VM). 4. **Количество VM:** до **Max VMs at 24h tier** (по умолчанию 2). Для создания каждой следующей VM *текущий* баланс кошелька клиента должен покрывать **30 дней (720 часов)** работы всех существующих VM плюс новой, вплоть до значения **Max VMs when meeting 30-day threshold** (по умолчанию 10). 5. **Создание VM** также требует наличия на балансе суммы минимум на **N часов** работы этой VM (**Create VM: balance ≥ N hours**, по умолчанию 2) и минимального баланса платформы. 6. Уменьшение конфигурации VM никогда не блокируется. Проверяется только увеличиваемый параметр, поэтому клиент, превысивший лимит диска, все равно может добавить vCPU, если это позволяет лимит по vCPU. ## Настройка {#configure} 1. Перейдите в **Services › Virtual Machines › Policy** и выберите вкладку **Quota**. 2. Включите **Enable quota**. 3. Проверьте три параметра (все доступны для редактирования): | Поле | По умолчанию | Диапазон | |---|---|---| | Создание VM: баланс ≥ N часов | 2 | от 1 до 720 | | Max VMs at 24h tier | 2 | от 1 до 100 | | Макс. количество VM при выполнении порога 30 дней | 10 | от 1 до 1000 (не меньше предыдущего поля) | 4. В блоке **Tier-based service quotas** настройте таблицу (ниже). 5. Нажмите **Save**. NexCMP запросит **причину** изменения, которая будет записана в журнал аудита вместе со старыми и новыми значениями. Изменение применяется ко всем клиентам. ![Вкладка Quota с переключателем активации, лимитами VM и таблицей квот сервисов по уровням](https://nexcmp.com/ru/docs/images/billing/quotas-01-policy.webp) ### Таблица квот сервисов {#service-quota-table} В таблице пять уровней. Ячейки заголовка от **L0** до **L4** содержат **порог депозита в центах**: значения по умолчанию `0, 1000, 5000, 20000, 100000` означают L0 для нового аккаунта, L1 от $10, L2 от $50, L3 от $200 и L4 от $1,000. Первый порог должен оставаться `0`. Каждая строка задает квоту одного ключа для каждого уровня; **-1 означает без ограничений**. | Ключ | Значение | L0 | L1 | L2 | L3 | L4 | |---|---|---|---|---|---|---| | `vpn.ips` | IP-адреса VPN | 2 | 10 | 30 | 100 | 500 | | `proxy6.ips` | IP-адреса IPv6-прокси | 500 | 2000 | 10000 | 50000 | -1 | | `dedicated.servers` | Серверы Bare-metal | 1 | 2 | 5 | 20 | 50 | | `s3.storage_gb` | Выделенный объем Object Storage, ГБ | 2048 | 4096 | 10240 | 51200 | -1 | | `k8s.clusters` | Кластеры Kubernetes | 1 | 2 | 5 | 10 | 30 | | `k8s.workers` | Рабочие узлы Kubernetes | 3 | 9 | 18 | 50 | 200 | | `vpc.count` | Сети Private Cloud | 1 | 2 | 5 | 10 | 30 | | `images.gb` | Хранилище пользовательских образов, ГБ | 50 | 100 | 200 | 500 | 2000 | В таблице также приведено несколько строк для продуктов, не входящих в этот релиз; оставьте их без изменений. Ключ, продукт которого отключен, скрыт и для него квоты не применяются. Значение должно быть `-1` или в диапазоне от `0` до `10,000,000`. Квоты на услуги рассчитываются по **базе внесенных средств**, как и уровни ВМ: учитывается максимальный когда-либо достигнутый баланс кошелька, а не общая сумма платежей картой. Для клиентов реселлера действуют те же значения по умолчанию, и реселлер может только просматривать их. ## Индивидуальные переопределения для клиентов {#per-customer-overrides} 1. Откройте **Customers › List**, затем выберите клиента. В **Overview** найдите карточку **Quota**. 2. **Ресурсы ВМ:** нажмите **Quota override** и выберите один из вариантов - **By top-up balance (remove override)** — поведение по умолчанию; - **Unlimited (including VM count)** — снимает любые ограничения для этого клиента; - **уровень тарифного плана** — фиксирует лимит ресурсов на уровне этого тарифа; правило по количеству ВМ по-прежнему действует. Укажите причину. Администраторы платформы могут установить любой уровень; переопределение, заданное реселлером, не может превышать сохраненную базу клиента. 3. **Сервисы:** в таблице раздела *Service quotas* для каждого ключа отображаются *In use*, действующий лимит и его *Source* (tier или override). Нажмите **Edit** в строке, укажите **New quota** (`-1` = без ограничений, пустое поле = возврат к значению уровня по умолчанию) и причину. ![Карточка Quota клиента с уровнем, использованием ресурсов и таблицей квот на сервисы с переопределением](https://nexcmp.com/ru/docs/images/billing/quotas-02-customer.webp) Каждое переопределение фиксируется в журнале аудита с указанием администратора, причины и значений до и после. ## Что видит клиент {#what-the-customer-sees} В **Client › Quotas** (`/client/quotas`) отображаются **текущий уровень** клиента, использованный и общий объем vCPU, RAM, диска и количество ВМ (с разделением между ВМ и Kubernetes), **доступный баланс кошелька**, **зафиксированный базис ресурсов** (он не уменьшается при расходовании средств) и сумма пополнения для перехода на следующий уровень. Ползунок позволяет выбрать целевой уровень и сразу перейти к экрану пополнения. В карточке **Service Quotas** перечислены все сервисы с квотой, использованным объемом, текущим уровнем (от L0 до L4), суммой, необходимой для пополнения до следующего уровня, а также кнопка **Request increase**, открывающая черновик тикета в службу поддержки. Кнопка **Quota policy** разъясняет действующие правила. ![Страница Quotas в клиентском портале с текущим уровнем, использованием ресурсов и квотами на сервисы](https://nexcmp.com/ru/docs/images/billing/quotas-03-portal.webp) ## Проверка {#verify} 1. Включите **Enable quota** и используйте нового тестового клиента с балансом $0. 2. Попробуйте создать ВМ большего размера, чем позволяет ваш самый дешевый тариф. Запрос будет отклонен с `quota_exceeded` и сообщением «Exceeds the resources of tier ... Top up $X more to unlock tier ...». 3. Пополните баланс на указанную сумму. Уровень сразу же изменится, и тот же запрос завершится успешно. 4. Купите IP-адреса VPN сверх лимита L0: вы получите HTTP 403 `quota_exceeded` с `"scope":"service"` и ссылкой на `/client/quotas`. 5. В карточке Quota клиента в поле **Source** отображается *tier*; задайте переопределение и убедитесь, что значение изменилось на *override*. ## Ограничения и примечания {#limits-notes} - **Отключено — значит отключено.** Если `quota_enabled` отключена, старое правило `new_account_max_vms` (**Services › Virtual Machines › Policy › Sales**) ограничивает новые аккаунты 2 ВМ до тех пор, пока сумма их депозитов не достигнет $10. При включенной квоте это правило больше не применяется. - **Созданные администратором VM не блокируются.** - **При ошибках доступ блокируется (fail-closed).** Если состояние квоты не удается прочитать, запрос отклоняется с `quota_unavailable` вместо разрешения. - Запросы через **API, CLI и MCP** используют те же обработчики, поэтому к ним применяются те же лимиты. - **Промо-кредит** не повышает уровень (см. [Promotions](https://nexcmp.com/ru/docs/billing/promotions/)). - **Пороговые значения уровней указаны в центах**, а не в долларах. ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | `quota_exceeded`, причина `resources` | Новое общее количество vCPU/RAM/диска превышает лимит уровня | Пополните баланс на сумму из сообщения или настройте переопределение. | | `quota_exceeded`, причина `vm_30d` | Превышено число VM для 24-часового уровня, и баланс еще не покрывает 30 дней работы всего парка | Пополните баланс на указанную сумму. | | `quota_exceeded`, причина `vm_max` | Достигнут абсолютный лимит по числу VM | Увеличьте **Max VMs when meeting 30-day threshold** или используйте переопределение. | | `quota_exceeded`, `scope: service` | Достигнут лимит для конкретной услуги | Увеличьте значение в таблице или переопределите этот параметр для клиента. | | `quota_unavailable` | Не удалось проверить состояние квоты | Повторите попытку; если ошибка сохраняется, проверьте журнал сервера. | | "quota_max_vms_30d must be >= quota_max_vms_24h" при сохранении | Значения перепутаны местами | Убедитесь, что 30-дневное значение не меньше 24-часового. | | Клиент сообщает о снижении уровня | Уровень не снижается; сравните **Held resource basis** со стоимостью тарифа | Проверьте прайс-лист тарифов: повышение цены тарифа может сместить пороги. | --- # Управление клиентами {#managing-customers} > **Где найти в панели:** Customers › Customers › List (`/customers`), Deletion requests (`/customers/requests`), Service transfers (`/customers/transfers`) и API keys (`/customers/apikeys`). ## Назначение {#what-it-does} В разделе Customers служба поддержки находит аккаунт, просматривает баланс, услуги, тикеты и историю входов, а также выполняет действия: блокировку, разблокировку, подтверждение e-mail, сброс пароля, начисление или списание средств, вход под именем клиента, создание VM или закрытие аккаунта. ## Требования {#requirements} | Параметр | Требование | |---|---| | Роль | Администратор. Каждое действие на запись требует указания причины и фиксируется в журнале аудита (System › Logs › Admin actions). | | E-mail | Для отправки писем со сбросом пароля и приглашениями требуется настроенная [конфигурация SMTP](https://nexcmp.com/ru/docs/administration/smtp-and-emails/). | ## Список клиентов {#the-customer-list} Откройте **Customers › List**. В списке представлены клиенты основного сайта; аккаунты реселлеров также отображаются и могут быть отфильтрованы по сайту. ![Список клиентов с фильтрами и столбцами страны, источника перехода, баланса и количества VM](https://nexcmp.com/ru/docs/images/customers/managing-customers-01-list.webp) | Столбец | Значение | |---|---| | **Email** (и имя) | Нажмите, чтобы открыть профиль клиента. | | **State** | *Active*, *Locked* или *Deleted*, а также статус подтверждения e-mail (*verified* или *unverified*). Наведите курсор на значок блокировки, чтобы увидеть причину. | | **Login** | Доступные клиенту способы входа: пароль, Google, GitHub, passkey. | | **Country** | Флаг и название страны, определенные по **IP-адресу**: страна IP при регистрации или, если она неизвестна, IP последнего входа. Подсказка указывает, какой именно IP был использован. | | **Referral source** | *Referral* со ссылкой на реферера и реферальным кодом, если клиент зарегистрировался по партнерской ссылке; в противном случае — «Not recorded». | | **Balance**, **VMs** | Баланс кошелька (отрицательные значения выделены красным) и количество активных VMs. | | **IP при регистрации / последний** | IP-адрес при регистрации и последнем входе с двухбуквенным кодом страны. Позволяет выявлять несколько аккаунтов с одного адреса. | | **Tenant** | Внутренний tenant ID клиента. | | **Created**, **Last login** | Относительное время. | | **Site** | Отображается при наличии реселлеров. | **Search** принимает e-mail, имя или IP. **Фильтры:** статус (all, active, locked, deleted), способ входа (any, Google, GitHub, passkey, no password yet) и сайт. Фильтры сохраняются в URL, поэтому отфильтрованный список можно сохранить в закладки или отправить коллеге. **Сортировка глобальная.** При нажатии на заголовок *Email*, *State*, *Balance*, *VMs*, *Created* или *Last login* на сервере сортируется **вся** база клиентов, а не только текущая страница, а номер страницы сбрасывается на 1. **Список обновляется автоматически.** Он обновляется каждые несколько секунд при просмотре (обновление приостанавливается, пока открыто диалоговое окно или пока вы вводите текст), поэтому новые регистрации и изменения баланса появляются без перезагрузки страницы. Страница клиента обновляется примерно каждые 30 секунд, пока она открыта; каждая вкладка загружает свои данные при первом открытии. ### Создание клиента {#create-a-customer} 1. Нажмите **Create customer**. 2. Укажите **e-mail**, необязательное **отображаемое имя**, необязательный **пароль** (если оставить пустым, клиент задаст его сам по ссылке в приглашении) и выберите, следует ли **отправить письмо с приглашением**. 3. Подтвердите действие. Созданный вручную аккаунт считается подтвержденным, если вы отправляете приглашение. ## Страница клиента {#a-customer-s-page} Нажмите на строку. На странице восемь вкладок; выбранная вкладка сохраняется в URL, поэтому ее можно добавить в закладки. Вкладки загружаются при первом открытии и сохраняют свое состояние при переключении. | Вкладка | Содержимое | |---|---| | **Overview** | Идентификационные данные, сведения о регистрации и последнем входе, сводка по кошельку и услугам | | **Services** | Единая таблица услуг клиента с фильтрами по типу и статусу, поиском, серверной сортировкой и пагинацией | | **Billing** | Кошелек и кредит, журнал операций, счета, платежи, возвраты, сохраненный способ оплаты и автопополнение | | **Quota** | Лимиты ресурсов и переопределения; см. [Квоты](https://nexcmp.com/ru/docs/billing/quotas/) | | **Security** | Сессии, аутентификация, методы входа, история входов и ключи API; см. [Ключи API](https://nexcmp.com/ru/docs/developers/api-keys/) | | **Support** | Последние тикеты | | **Affiliate** | Статус реферальной программы | | **Log** | История действий и аудит | Кнопки действий в заголовке (скрыты для удаленных аккаунтов): | Кнопка | Назначение | |---|---| | **Lock account** / **Unlock** | Блокирует вход и доступ к API. При необходимости также останавливает все VMs (без их удаления). Предоплаченные услуги, не являющиеся VMs (Kubernetes, Private Cloud, VPN и т. д.), также останавливаются. VMs, заблокированные администратором, необходимо разблокировать отдельно на странице VM. | | **Verify email** | Помечает e-mail как подтвержденный без перехода клиента по ссылке. | | **Send reset link** | Отправляет по эл. почте ссылку для сброса пароля (действует 1 час, одноразовая). Если SMTP не настроен, ссылка показывается однократно, чтобы вы могли отправить её самостоятельно. Администратор никогда не видит пароль. | | **Impersonate** | Выполняет вход от имени клиента на один час. См. [Вход от имени клиента](https://nexcmp.com/ru/docs/customers/login-as/). | | **Credit / debit** | Пополняет баланс кошелька или списывает средства с него с помощью корректировки книги учёта. См. [Счета и книга учёта](https://nexcmp.com/ru/docs/billing/invoices-and-ledger/). | | **Revoke sessions** | Завершает сеансы клиента на всех устройствах; токены приложений перестают действовать. | | **Create VM** | Создаёт VM для клиента. | | **Soft delete** | Закрывает аккаунт. Для подтверждения необходимо ввести адрес эл. почты. | ### Управление отдельной услугой {#manage-an-individual-service} Откройте вкладку клиента **Services**, найдите услугу по имени, ID, IP или конфигурации и используйте действия в строке. Те же действия доступны в собственном списке услуги в панели администратора. В диалоговом окне предлагаются только действия, поддерживаемые этой услугой и ее текущим состоянием. | Действие | Действие | |---|---| | **Lock** | Останавливает услугу с сохранением данных. Клиент видит ее как заблокированную и не может ею управлять. Пополнение баланса не снимает блокировку администратора; автоматическое продление заблокированной услуги приостанавливается. | | **Unlock** | Снимает блокировку администратора. Не отменяет блокировку за нарушения или другие защитные блокировки. | | **Cancel without refund** | Отменяет услугу без создания записи о возврате в журнале операций. В окне подтверждения выводится предупреждение о том, что отмена необратима. | | **Cancel and refund** | Отображает исходные платежи, их распределение между кошельком и кредитом, предыдущие возвраты и максимальную сумму к возврату. Проверьте сумму перед подтверждением. | Указывайте причину для каждого действия. Причина предназначена для администраторов; клиент получает нейтральное сервисное событие или уведомление. Возвращаемые средства кошелька поступают обратно на кошелек, а кредитные или промо-начисления возвращаются на кредитный баланс. Это действие не отправляет средства обратно через Stripe, банковский перевод или PayPal. Для нескольких услуг одного типа выберите до 50 строк и укажите массовое действие. В результатах отображается успешное выполнение или ошибка для каждой строки. При массовом возврате используется рекомендуемая сумма каждой услуги; услуги с нулевой рекомендуемой суммой возврата пропускаются в режиме возврата и требуют индивидуальной проверки или отмены без возврата средств. DDoS Shield, диски и backups здесь доступны только для чтения. Дополнения полосы пропускания следуют за родительской услугой. Доступ к AI Models можно заблокировать, но у него нет подписки для отмены. Чтобы заблокировать арендованный сервер Bare Metal, примените действие к его подписке, а не к заказу. ### Закрытие аккаунта (soft delete) {#closing-an-account-soft-delete} Аккаунт переводится в статус *deleted*, блокируется, его сеансы отзываются, а ещё не выплаченные реферальные вознаграждения аннулируются. Счета и книга учёта сохраняются для бухгалтерской отчётности. Действие отклоняется, пока у клиента остаётся **любая активная услуга** (VM, Kubernetes, Private Cloud, Dedicated, VPN, IPv6-прокси), аккаунт S3 или неоплаченное использование S3. Сначала удалите их. ## Запросы на удаление {#deletion-requests} Клиент может запросить удаление на странице своего аккаунта. Запросы отображаются в **Customers › Deletion requests** (фильтр по умолчанию: ожидающие) с указанием клиента, причины, количества активных VM, баланса и времени запроса. - Действие **Approve deletion** возможно только при отсутствии у клиента активных VM. Введите адрес эл. почты для подтверждения. Аккаунт удаляется программно (soft delete); **остаток средств на балансе кошелька автоматически не возвращается** — сначала оформите возврат, если это необходимо. - Для **Reject** требуется указать причину. ## Перенос услуг {#service-transfers} В **Customers › Service transfers** отображаются запросы на перенос **VM или подписки VPN** из одного аккаунта в другой **на том же сайте**. - Экран доступен только для чтения и создания: вы можете создать запрос от имени клиента или отменить его. Кнопка одобрения за владельца или получателя намеренно **отсутствует**. - Схема работы: владелец подтверждает перенос по одноразовой ссылке из эл. письма (действительна 30 минут, с TOTP, если включено), после чего получатель входит в систему и принимает запрос (получатель берёт на себя платёжные обязательства). Запрос, не принятый в течение 7 дней, аннулируется. - Правила: услуга должна быть активна, без неоплаченных счетов и выполняющихся фоновых задач; получатель должен быть действующим клиентом с подтверждённым адресом эл. почты на том же сайте. При переносе VM удаляется ключ SSH и отключается автопродление; при переносе VPN меняются пароли подключения. - Уже выставленные счета остаются у прежнего владельца; новый владелец может просматривать историю счетов по услуге со скрытыми данными прежнего владельца. - Клиенты могут создавать собственные запросы в **Transfers** на портале (до 5 запросов в час и не более 3 открытых одновременно). ## Проверка {#verify} 1. Создайте клиента с отправкой приглашения по эл. почте. Новый аккаунт появится вверху списка через несколько секунд. 2. Отсортируйте по **Balance**: сортировка применяется ко всем клиентам. 3. Заблокируйте клиента: метка состояния сменится на *Locked*, и клиент больше не сможет войти. Разблокируйте его. ## Ограничения и примечания {#limits-notes} - Столбец со страной носит справочный характер на основе IP и не служит подтверждением резидентства. Для частных или неизвестных адресов страна не указывается. - Блокировка аккаунта не влечёт возврат средств и не удаляет VM, если вы не решили также остановить их. - Разблокировка аккаунта не разблокирует VM, заблокированные администратором; разблокируйте их отдельно на странице VM. ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | "У клиента всё ещё есть активные услуги ... сначала остановите/удалите их" | У клиента есть услуги или аккаунт S3 | Удалите их, затем выполните мягкое удаление. | | При подтверждении удаления отображается «N VMs alive» | Та же причина | Сначала удалите виртуальные машины. | | Вместо «e-mail queued» отображается ссылка для сброса | Не настроен SMTP | Настройте e-mail или отправьте ссылку самостоятельно. | | Не удается удалить способ входа (`last_login_method`) | Это единственный способ входа клиента | Сначала добавьте другой способ. | | Блокировка не останавливает предоплаченные услуги | Возникли ошибки при остановке | Ознакомьтесь с сообщением после блокировки; система повторит попытку остановки автоматически. | | Не удается создать трансфер | Неоплаченный счет, выполняющаяся задача, получатель на другом сайте или не верифицирован | Устраните причину и повторите попытку. | --- # Вход от имени клиента {#log-in-as-a-customer} > **Где в панели администратора:** Customers › Customers › List › a customer › header button **Impersonate** (`/customers/`). ## Назначение {#what-it-does} Функция **Impersonate** (вход от имени клиента) позволяет администратору поддержки видеть портал глазами конкретного клиента, чтобы воспроизвести проблему или помочь с заказом. Сессия длится один час и изолирована от обычной сессии: любые действия, которые могли бы предоставить постоянный доступ к аккаунту, заблокированы, а каждое использование фиксируется в журнале. ## Требования {#requirements} | Параметр | Требование | |---|---| | Роль | Администратор, выполнивший вход в панель управления. | | Клиент | Аккаунт должен быть **active**. Заблокированный или удаленный аккаунт возвращает ошибку «account is not active» (HTTP 409). | | Причина | Указание причины обязательно; она записывается в журнал аудита. | | Браузер | Разрешите всплывающие окна для адреса панели управления: портал откроется в новом окне. | ## Шаги {#steps} 1. Откройте **Customers › List** и нажмите на клиента. 2. Нажмите **Impersonate**. В диалоговом окне появится пояснение, что сайт клиента откроется от его имени на один час, а все действия фиксируются в журнале аудита. 3. Укажите **причину** (например, «Ticket 1234 — cannot create VM») и нажмите **Open app**. 4. В новом окне откроется сайт клиента и отобразится панель управления с `?impersonated=1`. Если браузер заблокировал окно, разрешите всплывающие окна и нажмите еще раз. ![Диалоговое окно Impersonate с заполненным полем причины](https://nexcmp.com/ru/docs/images/customers/login-as-01-dialog.webp) Для клиента реселлера окно открывается на **собственном домене реселлера**, так как ссылка работает только на сайте самого клиента. ## Принцип работы {#how-it-works} 1. Действие администратора создает **одноразовый токен**, действующий в течение одного часа, и записывает `customer.login_as` (администратор, IP, причина, сайт) в журнал аудита. 2. В новом окне открывается `https:///v1/portal/impersonate/`. Первый запрос лишь отображает небольшую страницу и **не** расходует токен (чтобы предварительная загрузка в браузере не потратила его); затем страница выполняет подтверждение с помощью POST. 3. Запрос POST расходует токен. Повторное использование или переход по истечении одного часа возвращает ошибку «The impersonation link has expired or was already used». 4. NexCMP создает клиентскую сессию на **один час** (обычная сессия длится 30 дней), регистрирует запись о входе с методом `impersonate` и записывает в журнал `customer.login_as.used`. 5. Токен действует только на сайте самого клиента; на другом хосте возвращается ошибка 404. ## Что блокируется в сеансе имперсонации {#what-is-blocked-in-an-impersonated-session} Любое действие, предоставляющее доступ более чем на один час или изменяющее настройки безопасности клиента, возвращает HTTP 403 `impersonate_forbidden`: | Заблокировано | Назначение | |---|---| | Смена пароля, TOTP, привязка или отвязка Google/GitHub, редактирование passkey | Собственные учетные данные клиента | | Удаление аккаунта | Необратимо | | Создание или редактирование **API keys** | Долгосрочный доступ | | Подтверждение входа через CLI, десктоп-приложение или MCP (привязка устройства) | Долгосрочный доступ | | Создание доступа к Kubernetes, ключей S3, SSH keys, root-паролей, ссылок для доступа к консоли, учетных данных VPN или прокси | Секреты, действующие дольше самой сессии | | Активация кодов пополнения | Финансовые промоакции | | Вывод средств или изменение параметров выплаты партнерской комиссии | Вывод средств из системы | | Редактирование ключей AI, бюджетов или email-адресов для оповещений | Конфигурация клиента | Все остальное работает: вы можете просматривать страницы, создавать виртуальные машины и управлять ими, оформлять заказы и т. д. Действия выполняются от имени клиента и расходуют его средства; приведенные выше записи аудита фиксируют, что за сеансом стоял администратор. ## Проверка {#verify} 1. Выполните вход от имени тестового клиента. Откроется портал с данными этого клиента. 2. Попробуйте изменить пароль: появится сообщение «forbidden» (impersonation). 3. В **System › Logs › Admin actions** найдите `customer.login_as` с вашим именем, причиной и сайтом, за которой следует `customer.login_as.used`. 4. Закройте окно и снова перейдите по той же ссылке: появится сообщение «link expired or already used». ## Ограничения и примечания {#limits-notes} - Ограничение в один час фиксировано (3600 секунд). Чтобы продолжить, выполните вход от имени клиента повторно. - Отдавайте предпочтение просмотру и воспроизведению неполадок; избегайте действий, расходующих средства, если клиент прямо об этом не просил. - Завершите сессию досрочно с помощью **Revoke sessions** на странице клиента (это также приведет к выходу самого клиента). - Для реселлеров предусмотрена собственная имперсонация через **Sign in to partner console** (на 60 минут) в разделе Resellers; см. [Resellers](https://nexcmp.com/ru/docs/customers/resellers/). ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | «Аккаунт не активен» | Аккаунт заблокирован или удален | Сначала разблокируйте его или проверьте информацию на странице клиента. | | Браузер блокирует окно | Блокировщик всплывающих окон | Разрешите всплывающие окна для адреса панели администратора и повторите попытку. | | «Срок действия ссылки истек или она уже использована» | Истек лимит в один час или ссылка уже использована | Выполните вход от имени клиента снова. | | Открывается «Not found» | Ссылка была открыта на другом хосте | Используйте окно, открытое диалогом; не вставляйте ссылку в других местах. | | Действие возвращает «forbidden» | Заблокировано в сессиях имперсонации | Попросите клиента выполнить действие самостоятельно или воспользуйтесь разделами панели администратора. | --- # Реселлеры (white-label) {#resellers-white-label} > **Где в панели управления:** Customers › Resellers › List (`/resellers`), Domains & SSL (`/resellers/domains`), Permissions & wholesale (`/resellers/entitlements`), Defaults (`/resellers/settings`). Слоты реселлеров: System › Admin › License & updates (`/license`). ## Назначение {#what-it-does} **Реселлер** получает брендированную копию клиентского портала на **собственном домене**, с собственной клиентской базой, балансом, тарифами и (опционально) платежными шлюзами. Он покупает у вас по оптовой цене и продает по своей. Его клиенты не видят ваш бренд, а с домена реселлера невозможно открыть вашу консоль администратора. Реселлер ведет бизнес через **партнерскую консоль** по адресу `https://partner.`. ## Требования {#requirements} | Параметр | Требование | |---|---| | Лицензия | Один **слот реселлерского домена** в лицензии на каждый собственный домен реселлера. На странице лицензии отображается количество слотов `used/max` и ссылка для покупки дополнительных. При отсутствии свободного слота добавление домена завершается ошибкой "Out of license reseller domain slots". | | DNS | Каждый реселлерский домен должен быть направлен на ваш сервер (см. ниже). | | Веб-сервер и TLS | Имя хоста должно направляться на панель NexCMP через ваш reverse proxy с действующим сертификатом для этого имени. | | E-mail | SMTP, настроенный для отправки писем с приглашениями и уведомлениями. | | Главный переключатель | **Reseller settings › General › `rs_enabled`** включен по умолчанию. | ## Подготовка инфраструктуры {#prepare-the-infrastructure} 1. Определите публичный адрес сервера: его IPv4-адрес и, если вы предпочитаете CNAME, имя хоста, указывающее на него (например, `sites.cloud.example.com`). 2. Откройте **Customers › Resellers › Defaults** (`/resellers/settings`), блок **Domains & SSL**, и укажите: | Ключ | Значение | |---|---| | `rs_server_ipv4` | Публичный IPv4, на который должны указывать A-записи реселлеров. | | `rs_cname_target` | Имя хоста, на которое должны указывать CNAME-записи реселлеров. | | `rs_master_hosts` | Имена хостов, принадлежащие вашему основному сайту (их нельзя передавать реселлерам). | | `rs_platform_domain` | Необязательный родительский домен для **поддоменов платформы** (например, `partners.cloud.example.com`, чтобы предоставлять реселлерам `acme.partners.cloud.example.com`). Пустое поле отключает опцию. | | `rs_sites_stale_minutes` | Количество минут, по истечении которых служба сертификатов считается устаревшей (по умолчанию 15). | | `rs_ssl_fail_hours` | Количество часов неудачных попыток до регистрации ошибки (по умолчанию 48). | ::: warning Проверьте эти значения перед отправкой инструкций Параметры `rs_server_ipv4`, `rs_cname_target` и `rs_master_hosts` содержат демонстрационные значения. Замените их на данные вашего сервера и домена **до того**, как предоставите DNS-инструкции реселлеру, иначе инструкции на экране будут указывать на неверный адрес. ::: 3. Нажмите **Save** (потребуется указать причину). 4. Убедитесь, что ваш reverse proxy перенаправляет имена хостов реселлера на панель NexCMP и отдает сертификат для каждого из них. Установщик настраивает nginx и Let's Encrypt только для основного домена (и имен `admin.` и `partner.`, которые резолвятся). Если используется Cloudflare, включите проксирование имени хоста и режим Full SSL. ## Подключение в NexCMP {#connect-in-nexcmp} ### Создание реселлера {#create-the-reseller} 1. Откройте **Customers › Resellers › List** и нажмите **New reseller**. Мастер состоит из 8 шагов и инициализирует все настройки в конце; любой шаг можно безопасно повторить. | Шаг | Заполняемые данные | |---|---| | **Reseller** | Юридическое или коммерческое наименование, **slug** (от 4 до 31 символов a–z, 0–9 или `-`, начинается с буквы; также служит префиксом инвойсов), контактное лицо, e-mail и телефон, язык по умолчанию, платежные реквизиты реселлера (как покупателя пополнений баланса). | | **Console account** | Имя пользователя, e-mail учетной записи, ФИО; выберите **Send a one-time invite link by e-mail** (действует 72 часа, рекомендуется) или покажите временный пароль один раз. | | **Brand** | Название бренда, краткое наименование, слоганы, основные цвета, e-mail и телефон службы поддержки, имя продавца в инвойсах клиентов, логотипы (для светлого и темного фона), квадратный значок и favicon: PNG, JPEG, WEBP или ICO размером до 256 КБ, **без SVG**. | | **Domains** | Домен(ы) клиента с **also www**, выбор основного, **test domain** (sslip.io) и опция **dry-run** либо поддомен платформы. Мастер отображает **DNS OK / DNS not ready** и записи, которые необходимо создать. | | **Pricing & wallet** | Оптовая скидка (%), минимальная розничная цена (% от каталожной), наценка по умолчанию (%), кредитный лимит, начальный баланс, оповещение о низком балансе, лимиты на клиентов, ВМ и домены, функции сайта (регистрация клиентов, защита от DDoS, тикеты поддержки, индивидуальный тариф, изменение размера, Auto Scaling). | | **Payment channels** | Кто принимает платежи клиентов (см. ниже), а также подключение собственного PayPal и банковского перевода VN (опционально). | | **Email** | Имя отправителя и Reply-To. Адрес From остается адресом платформы до тех пор, пока для домена реселлера не будет настроен DKIM. | | **Review** | Проверьте все параметры и нажмите **Provision everything** или **Save draft (provision later)**. | 2. Подготовка продолжается в фоновом режиме (каждые 30 секунд). Откройте реселлера, чтобы отслеживать прогресс, и используйте **Continue provisioning** или **Retry**, если какой-либо шаг завершился с ошибкой. ![Мастер добавления реселлера на первом шаге с примерами значений](https://nexcmp.com/ru/docs/images/customers/resellers-01-wizard.webp) ### Направление DNS (выполняется реселлером) {#point-dns-the-reseller-does-this} Реселлер (или вы) создает записи, указанные на вкладке **Domains & SSL**: | Запись | Name | Значение | |---|---|---| | TXT (подтверждение владения, только в первый раз) | `_site-verify.` | `sv=`, указанное на экране | | A (apex-домен, например `shop.example.net`) | домен | ваш `rs_server_ipv4` | | CNAME (поддомен, например `cloud.example.net`) | домен | ваш `rs_cname_target` (или A-запись на `rs_server_ipv4`) | | CNAME (опционально) | `www.` | ваш `rs_cname_target` | Также: - Удалите любые записи **AAAA** (IPv6), если только ваш сервер не отвечает по этому IPv6-адресу. - Отключите CDN-прокси (**off**, серое облако) на время проверки домена. - Если у домена настроены записи **CAA**, разрешите `letsencrypt.org`. Токен в TXT-записи уникален для каждого домена; скопируйте его с экрана. Система повторно проверяет DNS каждые 5 минут в течение первых 48 часов, затем каждый час, и освобождает имя, для которого TXT-запись так и не появилась спустя 72 часа. ### Статусы доменов {#domain-states} В разделе **Customers › Resellers › Domains & SSL** (все реселлеры) и на вкладке реселлера **Domains & SSL**: | Состояние | Значение | |---|---| | `pending_verify` | Ожидание TXT-записи. | | `pending_dns` / `verifying` | Ожидание направления A или CNAME на вас. | | `issuing` | Выпуск сертификата. | | `active` | Обслуживает сайт реселлера. | | `cert_expiring` | Срок действия сертификата подходит к концу; ожидается продление. | | `dns_lost` | DNS больше не указывает на вас; через 30 дней домен будет удален. | | `error` | См. код ошибки; нажмите **Retry** после устранения проблемы. | | `removing` / `removed` | Удаляется; слот лицензии освобождается. | Действия в строке: **Check now**, **Retry**, **Make primary**, **Test mode** (для тестового домена), **Remove**. ## Права доступа и оптовые цены {#permissions-wholesale} **Customers › Resellers › Permissions & wholesale** (`/resellers/entitlements`) представляет собой матрицу: по одной строке на реселлера с оптовой **скидкой** и **наценкой**, а также переключатели для каждой услуги (например, DDoS Shield и VPN). Переключатель доступен для редактирования, если функция включена на уровне платформы; иначе ячейка доступна только для чтения и ведет к соответствующей настройке. На вкладке **Top-up codes** задается количество кодов пополнения, которое реселлер может выпускать в месяц (см. [Promotions](https://nexcmp.com/ru/docs/billing/promotions/)). Правила ценообразования: - Оптовая цена = базовая цена x (1 - скидка); ее можно переопределить для каждого тарифа и расчетного периода на вкладке реселлера **Wholesale pricing**. - Реселлер сам устанавливает розничные цены, но не может опускаться ниже минимального порога (**floor**, процент от базовой цены). - С **кошелька** реселлера списывается оптовая цена при покупках его клиентов. Для кошелька действуют кредитный лимит, льготный период и лимит овердрафта (см. Defaults). ## Defaults {#defaults} В разделе **Customers › Resellers › Defaults** (`/resellers/settings`) находятся ключи `rs_*`, применяемые ко всем реселлерам. При каждом изменении запрашивается причина, и действие фиксируется в аудите. | Группа | Ключ | По умолчанию | Значение | |---|---|---|---| | Общие | `rs_enabled` | 1 | Реселлерская программа включена. | | | `rs_platform_collect_enabled` | 0 | Разрешает платформе принимать платежи клиентов в пользу реселлеров. **Включайте только после юридической проверки.** | | | `rs_totp_required` | 1 | Учетные записи консоли реселлера должны использовать двухфакторную аутентификацию. | | | `rs_agreement_version` | 1 | Версия партнерского соглашения, которую реселлеры обязаны принять. | | Цены по умолчанию | `rs_default_discount_bp` | 2000 (20 %) | Оптовая скидка для новых реселлеров (в базисных пунктах, от 0 до 9000). | | | `rs_default_markup_bp` | 2500 (25 %) | Наценка по умолчанию (от 0 до 50000). | | | `rs_default_floor_bp` | 9000 (90 %) | Минимальный порог розничной цены (от 0 до 20000). | | | `rs_default_max_domains` | 3 | Допустимое количество доменов на одного реселлера. | | Кошелек и выплаты | `rs_grace_hours` | 72 | Льготный период до приостановки услуг клиентов при нулевом балансе реселлера. | | | `rs_overdraft_cap_cents` | 5000 | Разрешенный овердрафт по кошельку. | | | `rs_retention_days` | 14 | Количество дней до удаления VM закрытого реселлера. | | | `rs_payout_hold_days` | 30 | Срок удержания комиссии (в днях) перед выводом средств. | | | `rs_payout_min_cents` | 5000 | Минимальная сумма вывода. | | | `rs_topup_min_cents` | 2000 | Минимальная сумма пополнения кошелька реселлером. | | Платежи и почта | `rs_webhook_base` | пусто | Публичный базовый URL для вебхуков шлюзов реселлера (если пусто — используется URL сайта). | | | `rs_mail_from` | пусто | Адрес отправителя (From) для писем реселлера. | | | `rs_invoice_show_processor` | 1 | Отображать платежный шлюз в счетах. | | | `rs_gw_stripe_enabled`, `rs_gw_usdt_enabled` | 1 | Разрешено ли реселлерам подключать собственные аккаунты Stripe или USDT. | ## Кто принимает платежи клиентов {#who-collects-customer-payments} | Режим | Значение | |---|---| | **Принимает реселлер (собственные каналы)** — по умолчанию | Реселлер подключает собственный аккаунт Stripe, PayPal, USDT или банковский счет. Его вебхуки: `https:///v1/billing//webhook/r/`. Сохраненные карты и [auto top-up](https://nexcmp.com/ru/docs/billing/auto-top-up/) для таких сайтов недоступны. | | **Принимает платформа** | На сайте реселлера отображаются ваши каналы оплаты. Заблокировано до `rs_platform_collect_enabled = 1`. | | **Смешанный режим** | Комбинация, настраиваемая отдельно для каждого канала. | ## Что видит реселлер {#what-the-reseller-sees} В консоли партнера по адресу `https://partner.` доступны разделы Overview, Reports, Customers, VMs, Tickets, Orders, Payments, Prices, Brand, Landing & legal, Domains & SSL, Email, Wallet и Payment channels. Пользователи консоли получают роль *reseller* (полный доступ) или *staff* (только чтение). Чтобы войти в нее самостоятельно, откройте карточку реселлера и нажмите **Sign in to partner console**: сессия действует 60 минут, каждая операция записи логируется с вашим именем в журнале администратора и реселлера, а финансовые операции требуют повторного подтверждения. ## Проверка {#verify} 1. После развертывания в строке реселлера в списке отображается *active* и зеленый столбец **Provisioning**. 2. Откройте домен реселлера в браузере: появится собственная страница входа реселлера с его брендингом. `https:///admin` возвращает 404. 3. Зарегистрируйте тестового клиента на этом домене: клиент появится в разделе **Customers › List** с указанием реселлера в столбце **Site**. 4. На странице лицензии отображается еще один занятый слот. ## Ограничения и примечания {#limits-notes} - Один слот лицензии на каждый собственный или тестовый домен; поддомены платформы не занимают слоты. - Приостановка реселлера сохраняет данные; действие **Close reseller** освобождает все слоты доменов, а удаление VM разрешено только после истечения срока хранения. - Клиенты реселлера отображаются в общем списке клиентов; войти под их учетной записью можно как обычно (ссылка откроется на домене реселлера). - Реселлеры не могут просматривать или изменять ваши платежные каналы, значения квот по умолчанию и других реселлеров. ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | «Исчерпаны слоты доменов реселлера по лицензии» | Все слоты заняты | Освободите слот (удалите домен) или приобретите дополнительные слоты на странице лицензии. | | Домен завис в статусе `pending_verify` | Отсутствует TXT-запись | Создайте TXT-запись точно так, как указано; нажмите **Check now**. | | Домен завис в статусе `pending_dns` | Запись A/CNAME указывает не на вас, присутствует AAAA-запись либо включено проксирование CDN | Исправьте DNS, отключите проксирование, затем нажмите **Check now**. | | Состояние `error` | См. код в строке (например, CAA блокирует Let's Encrypt, превышен лимит запросов) | Исправьте проблему и нажмите **Retry**. | | В браузере отображается ошибка неизвестного хоста или «421» | Имя хоста не включено в лицензию или не маршрутизируется на панель | Добавьте домен через реселлера (расходует слот) и исправьте обратный прокси. | | В инструкциях указан неверный IP-адрес или хост | В `rs_server_ipv4` / `rs_cname_target` по-прежнему указаны примерные значения | Задайте их в Defaults. | | Реселлер не может включить сбор платежей через платформу | Заблокировано | Установите `rs_platform_collect_enabled` после юридической проверки. | --- # Брендинг {#branding} > **В панели управления:** System › Settings › Brand (`/settings/branding`). См. также: System › Settings › General (`/settings`) для настройки URL и реквизитов продавца для счетов. ## Назначение {#what-it-does} NexCMP работает по модели white-label: в продукте не упоминается разработчик, и клиенты видят исключительно **ваш** бренд. Настройки бренда применяются к страницам входа и регистрации, порталу, панели управления и e-mail. ## Требования {#requirements} | Параметр | Требование | |---|---| | Роль | Администратор. | | Файлы | Логотипы: SVG, PNG, JPEG, WEBP или ICO, **до 512 КБ каждый**. | | Зависимости | Нет. | ## Шаги {#steps} 1. Откройте **System › Settings › Brand**. 2. В блоке **Identity** заполните: | Поле | Примечания | |---|---| | **Brand name** (обязательно) | До 60 символов. Отображается в портале, письмах, счетах и на юридических страницах. | | **Наименование продавца в счетах** | До 120 символов. Если не заполнено, используется название бренда. | | **Brand color** | Цвет в формате `#rrggbb`; небольшая кнопка рядом с полем сбрасывает значение к исходному цвету. | | **Site currency** | **USD**: цены и балансы отображаются только в USD, без переключения валюты. **VND**: также отображается конвертированная сумма по сохраненному курсу (см. [Валюта и обменные курсы](https://nexcmp.com/ru/docs/catalog/currency-and-exchange-rates/)). | 3. Нажмите **Save**. 4. В карточке **Logo & favicon** загрузите три изображения — **Logo (light background)**, **Logo (dark background)** и **Favicon** — с помощью **Upload** (или **Replace**); **Remove** удаляет изображение. ![Страница Brand с полями идентификации и тремя загруженными изображениями](https://nexcmp.com/ru/docs/images/customers/branding-01-brand.webp) ### Связанные настройки в General {#related-settings-in-general} В разделе **System › Settings › General** есть две вкладки, дополняющие эти параметры: | Вкладка | Поля | |---|---| | **Branding & URLs** | Название бренда (email, счета), язык по умолчанию (English или Vietnamese), **Customer app URL**, **Console URL**, **Admin URL** (ссылка для олицетворения реселлера) и **Partner console URL** (ссылки-приглашения, email реселлеров). Мастер настройки заполняет их значениями `https://`, `https:///admin` и `https:///console`. | | **Seller & invoicing** | Название юрлица, ИНН/налоговый номер, адрес, контактный email и префикс номера счета. См. [Счета и журнал операций](https://nexcmp.com/ru/docs/billing/invoices-and-ledger/). | Параметр **From name** для email настраивается в **System › Settings › Email** ([SMTP и электронная почта](https://nexcmp.com/ru/docs/administration/smtp-and-emails/)). ## Проверка загружаемых файлов {#uploaded-files-are-checked} - Растровые изображения распознаются по их содержимому (а не по имени файла) и проверяются по размеру. - **SVG-файлы пересобираются** по белому списку безопасных фигур. Файл, содержащий скрипты, `foreignObject`, атрибуты событий, внешние ссылки, теги `url(...)` с внешними адресами, DOCTYPE или сущности, **отклоняется** (`svg_unsafe`). - Слишком большой файл отклоняется с ошибкой `asset_too_large`, неверный тип — с `asset_type`, неподдерживаемые размеры — с `asset_dimensions`. - Файлы отдаются с вашего собственного домена со строгими заголовками безопасности. ## Проверка {#verify} 1. Откройте страницу входа в портал в приватном окне: отобразятся логотип, название и цвет. 2. Проверьте favicon на вкладке браузера (браузеры кэшируют favicons; если отображается старый, обновите страницу с очисткой кэша). 3. Отправьте тестовое письмо (например, **Send reset link** для тестового клиента) и проверьте название бренда в теме и подвале. ## Ограничения и примечания {#limits-notes} - Логотип для темного фона используется, когда клиент или администратор переключается на темную тему. - У реселлеров собственный брендинг; они могут загружать файлы PNG, JPEG, WEBP или ICO размером до 256 КБ (без SVG). См. [Реселлеры](https://nexcmp.com/ru/docs/customers/resellers/). - Изменение цвета бренда или логотипа применяется при следующей загрузке страницы; уже отправленные письма не изменяются. ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | Загрузка отклонена: `svg_unsafe` | SVG содержит скрипты, ссылки или внешние ресурсы | Экспортируйте чистый SVG (без скриптов и внешних изображений) или используйте PNG. | | `asset_too_large` | Файл больше 512 КБ | Сожмите файл или уменьшите разрешение изображения. | | `asset_type` | Формат отличается от SVG, PNG, JPEG, WEBP или ICO | Конвертируйте файл. | | `invalid_argument: primary` | Цвет не соответствует формату `#rrggbb` | Используйте шестизначный HEX-код. | | По-прежнему виден старый логотип | Кэш браузера | Выполните жесткую перезагрузку страницы; обновление favicon может занять больше времени. | | Цены отображаются только в USD | Основная валюта сайта — USD | Переключитесь на VND и убедитесь, что обменный курс сохранен. | --- # Юридические страницы {#legal-pages} > **Где в панели управления:** System › Settings › Legal (`/settings/legal`). **Где их видят клиенты:** `https:///terms` и `/privacy`, ссылки при регистрации и оформлении заказа. ## Назначение {#what-it-does} В вашей установке публикуются две страницы: **Terms of Service** и **Privacy Policy**. Пока вы не составите собственный вариант, NexCMP показывает **нейтральный текст по умолчанию**, в котором не упоминается разработчик ПО и не дается обещаний конкретных услуг. Замените его текстом, согласованным с вашим юристом, до начала продаж. ## Требования {#requirements} | Параметр | Требование | |---|---| | Роль | Администратор. | | Содержимое | Обычный markdown, до **50 KB** на страницу и язык. | | Зависимости | Название бренда и реквизиты продавца ([Branding](https://nexcmp.com/ru/docs/customers/branding/)) подставляются в текст по умолчанию. | ## Шаги {#steps} 1. Перейдите в **System › Settings › Legal**. Для каждой страницы предусмотрена карточка с тегом *Using the default text* или *Using your text*. 2. Выберите вкладку языка: **English** или **Tiếng Việt**. 3. Введите текст. Пока поле пустое, текст по умолчанию отображается полупрозрачным плейсхолдером. Чтобы взять его за основу, нажмите **Start from the default text** и отредактируйте. 4. Нажмите **Save**. Счетчик размера покажет `used / 50 KB`. 5. Нажмите **View on the customer site**, чтобы открыть `/terms` или `/privacy`. 6. Чтобы вернуться к тексту по умолчанию для одного языка, нажмите **Clear, back to default** и сохраните изменения. ![Настройки Legal с карточкой Terms of Service, где показан текст по умолчанию в качестве основы](https://nexcmp.com/ru/docs/images/customers/legal-01-terms.webp) ## Что содержат страницы по умолчанию {#what-the-default-pages-contain} Текст по умолчанию хранится в продукте как `legal_default.json` и заполняется названием бренда, наименованием продавца, URL сайта и контактным e-mail (из раздела **Seller & invoicing** в System › Settings › General; если e-mail не указан, дается ссылка на службу поддержки). | Страница | Разделы | |---|---| | **Terms of Service** | 1 Услуги · 2 Аккаунты и верификация · 3 Цены и расчеты · 4 Возвраты · 5 Данные пользователя · 6 Правила допустимого использования · 7 Доступность и поддержка · 8 Приостановление и прекращение обслуживания · 9 Ответственность · 10 Изменения и применимое право (законодательство по месту регистрации продавца) | | **Privacy Policy** | 1 Собираемые данные · 2 Цели использования · 3 Файлы cookie и локальное хранилище · 4 Доступ третьих лиц · 5 Сроки хранения · 6 Права пользователя · 7 Контакты | ::: warning Не является юридической консультацией Текст по умолчанию — это нейтральный шаблон. Передайте его на проверку юристу перед началом работы с клиентами, особенно разделы о возвратах, ответственности и применимом праве. ::: ## Правила разметки markdown {#markdown-rules} - Поддерживаются: заголовки (`# 1. Title`), абзацы, маркированные и нумерованные списки, **полужирный шрифт** и ссылки `[text](https://example.com)`. - Ссылки должны начинаться с `http://` или `https://`. - **Прямой ввод HTML запрещен** (любые ``, ` # Обзор клиентского портала {#customer-portal-overview} > **Где найти в портале:** `https:///` — клиенты входят через `/login`. Администраторы используют `/admin`; при наличии прав администратора один логин подходит к обоим интерфейсам. Портал — это то, с чем ваши клиенты работают каждый день. Он оформлен в вашем фирменном стиле с вашим логотипом и цветами ([Branding](https://nexcmp.com/ru/docs/customers/branding/)) и отображает только те сервисы, которые вы включили ([Modules](https://nexcmp.com/ru/docs/infrastructure/modules/)). ## Дашборд {#the-dashboard} После входа в **Dashboard** отображаются: | Блок | Значение | |---|---| | Баланс кошелька | Текущий остаток средств и примерная оценка, на сколько дней его хватит при текущей скорости расхода | | Расход за этот месяц | Начисления на текущий момент и прогноз расходов до конца месяца | | Виртуальные машины | Каждая ВМ со статусом, IP-адресом, CPU и RAM, а также быстрые действия (Console, Restart) | | Трафик | Входящий и исходящий трафик за 1 ч, 6 ч, 24 ч, 7 дн, 30 дн | | Последние действия | Последние события в аккаунте | | Быстрый старт | Контрольный список: создать ВМ, добавить SSH-ключ, пополнить баланс, включить автопополнение, подтвердить e-mail | ![Клиентский дашборд с балансом кошелька, прогнозом расходов, работающей виртуальной машиной и чек-листом быстрого старта](https://nexcmp.com/ru/docs/images/portal/overview-01-dashboard.webp) ## Навигация {#navigation} Меню группирует сервисы по категориям. Отключенные сервисы (или те, у которых не подключен источник) не отображаются. | Область | Страница | |---|---| | Instances | [Виртуальные машины](https://nexcmp.com/ru/docs/portal/virtual-machines/) и страницы с подробными сведениями о них | | Deploy | [Заказ](https://nexcmp.com/ru/docs/portal/ordering/) — создание ресурса | | Хранилище | Снимки, резервные копии и тома, если они включены — [Snapshots](https://nexcmp.com/ru/docs/portal/snapshots/) | | Billing | [Кошелек и пополнения](https://nexcmp.com/ru/docs/portal/sign-up-and-wallet/), счета, заказы, квоты | | Учетная запись | Профиль, вход и безопасность, настройки интерфейса, автопополнение | | Поддержка | Виджет чата и тикеты — [Support](https://nexcmp.com/ru/docs/portal/support/) | | Документация API | `/apidoc` — [API](https://nexcmp.com/ru/docs/developers/api/) | ## Учетная запись {#account} В разделе **Account** есть четыре вкладки: **Profile** (имя, e-mail, ID клиента, запрос на удаление аккаунта), **Sign-in & security** (пароль, passkey, привязанные аккаунты Google/GitHub), **Preferences** (язык, валюта отображения) и **Auto top-up** ([Auto top-up](https://nexcmp.com/ru/docs/billing/auto-top-up/)). Клиент не может удалить аккаунт напрямую: он нажимает **Request account deletion**; после удаления всех виртуальных машин оператор рассматривает запрос (Customers › Deletion requests), при этом клиент может отозвать его, пока он находится на рассмотрении. ## Язык и валюта {#language-and-currency} Портал доступен на 16 языках и отображает цены в валюте, соответствующей выбранному языку; см. [Валюта и обменные курсы](https://nexcmp.com/ru/docs/catalog/currency-and-exchange-rates/). Клиенты могут изменить оба параметра в **Preferences**. ## Квоты клиентов {#customer-quotas} В разделе **Billing › Quotas** показано, какой объем каждого ресурса (CPU, память, хранилище, IP, VM) клиент может использовать в зависимости от внесенной оплаты — см. [Квоты](https://nexcmp.com/ru/docs/billing/quotas/). --- # Регистрация, кошелек и пополнение {#sign-up-wallet-and-top-up} > **Где найти в портале:** `/register`, `/login`, Billing (`/billing`). ## Создание аккаунта {#create-an-account} 1. Клиент открывает `https:///register` и вводит e-mail и пароль (не менее 10 символов, включая буквы и цифры) либо использует **Google**, **GitHub** или **passkey**, если они включены — см. [Безопасность](https://nexcmp.com/ru/docs/administration/security/#customer-sign-in). 2. Если включена captcha, клиент проходит проверку. 3. Письмо с подтверждением отправляется через ваш [SMTP](https://nexcmp.com/ru/docs/administration/smtp-and-emails/). Подтверждение требуется перед созданием VM, если это задано в настройках продаж. ![Страница регистрации с полями ввода e-mail и пароля](https://nexcmp.com/ru/docs/images/portal/sign-up-and-wallet-01-register.webp) ::: tip Без работающего SMTP клиенты не смогут подтвердить e-mail или сбросить пароль. Сначала настройте [SMTP](https://nexcmp.com/ru/docs/administration/smtp-and-emails/). ::: ## Кошелек {#the-wallet} Все оплачивается с баланса **кошелька** в вашей расчетной валюте. На странице **Billing** отображаются: | Раздел | Значение | |---|---| | Доступные средства | Баланс плюс ожидающие зачисления пополнения | | Текущие начисления | Почасовые услуги, потребленные в текущем цикле, но еще не списанные | | Задолженность | Любая сумма задолженности | | История биллинга | Вкладки **Invoice History**, **Payment Order**, **Ledger**, **Orders** | ![Страница Billing с разделами доступных средств, текущих начислений и вкладками истории](https://nexcmp.com/ru/docs/images/portal/sign-up-and-wallet-02-billing.webp) ## Пополнение баланса {#add-credit} 1. Нажмите **Deposit**. 2. Введите сумму. Минимальное значение — ваша [минимальная сумма пополнения](https://nexcmp.com/ru/docs/billing/minimum-top-up/). 3. Выберите способ оплаты (карта, PayPal, USDT или банковский перевод, если выбран вьетнамский интерфейс) — доступны те каналы, которые вы включили в [Payment channels](https://nexcmp.com/ru/docs/billing/payment-channels/). 4. Оплатите. Баланс обновится после подтверждения платежным провайдером. Сохраненные карты, Stripe Link и PayPal можно использовать повторно, в том числе для [автопополнения](https://nexcmp.com/ru/docs/billing/auto-top-up/); см. [Сохраненные способы оплаты](https://nexcmp.com/ru/docs/billing/saved-payment-methods/). ## Активация промокода {#redeem-a-code} **Redeem code** зачисляет средства по созданному вами ваучеру (Finance › Billing › Vouchers) или применяет промокод — см. [Промоакции](https://nexcmp.com/ru/docs/billing/promotions/). ## Счета (Invoices) {#invoices} Для каждого оплаченного заказа формируется счет, в котором указаны реквизиты продавца ([General settings](https://nexcmp.com/ru/docs/administration/general-settings/)). Клиенты могут открыть его во вкладке **Invoice History** и распечатать или сохранить в формате PDF из браузера. ## Почасовая оплата {#hourly-charges} Оплата за почасовые услуги списывается за каждый час существования ресурса; суммы накапливаются, и отдельный час может округляться до $0.00. При недостаточном балансе услуги приостанавливаются согласно вашим правилам биллинга, а клиент получает уведомление по электронной почте (`low_balance`). --- # Заказ услуги {#ordering-a-service} > **Где в портале:** Deploy (`/deploy/vm`). **Где в панели администратора** настраивается отображение: Services (тарифы, цены) и System › Admin › License & updates (модули). Страница заказа представляет собой единую форму с нумерованными шагами. При выборе другой услуги на шаге 1 страница сохраняется, а последующие шаги меняются. ## Шаги {#steps} 1. **Service** — Cloud Servers и другие включенные вами услуги (Kubernetes, Object Storage, Images, Private Cloud, VPN …). 2. **Location** — [зона](https://nexcmp.com/ru/docs/infrastructure/zones/). Цены и включенный трафик могут различаться в зависимости от локации. 3. **Plan** — фиксированный тариф (vCPU, RAM, NVMe-диск, почасовая цена) или **Custom** (клиент сам выбирает vCPU, RAM и диск с оплатой за ресурсы). Тарифы настраиваются в [Plans](https://nexcmp.com/ru/docs/catalog/plans/). 4. **Billing cycle** — **Hourly** или предоплатные ежемесячные/ежегодные циклы со скидкой (например, 1 год −10%, 2 года −15%, 3 года −20%). 5. **Operating system** — список шаблонов, **My Images** (собственные образы клиента) и версия. 6. **Hostname & quantity** — имя (или **Randomize**) и количество серверов. ![Страница заказа с шагами выбора услуги, локации и тарифа](https://nexcmp.com/ru/docs/images/portal/ordering-01-plan.webp) ![Шаги выбора платежного цикла и операционной системы на странице заказа](https://nexcmp.com/ru/docs/images/portal/ordering-02-cycle-os.webp) ## Оформление заказа {#placing-the-order} В сводке отображается стоимость. Списание за заказ происходит с баланса **до** развертывания, после [проверки квот](https://nexcmp.com/ru/docs/billing/quotas/) и правил [минимального баланса](https://nexcmp.com/ru/docs/billing/minimum-top-up/). Обычно VM переходит в статус *Running* примерно за минуту; клиент видит шаги развертывания на вкладке **Activity** виртуальной машины и получает письмо «VM ready» с начальным паролем (доступен один раз в течение 10 минут). ## Что может помешать оформлению заказа {#what-can-stop-an-order} | Сообщение / причина | Решение | |---|---| | Недостаточно средств на балансе | Пополнить баланс — [Регистрация, баланс и пополнение](https://nexcmp.com/ru/docs/portal/sign-up-and-wallet/) | | Превышена квота | Увеличьте квоту — [Quotas](https://nexcmp.com/ru/docs/billing/quotas/) | | Электронная почта не подтверждена | Клиент подтверждает адрес электронной почты | | Нет тарифов для выбранной локации | Сделайте тариф доступным в этой зоне — [Plans](https://nexcmp.com/ru/docs/catalog/plans/) | | Лицензия недействительна | Клиенты не могут создавать новые услуги — [License](https://nexcmp.com/ru/docs/getting-started/license-and-purchase/#if-the-license-is-not-valid) | --- # Виртуальные машины {#virtual-machines} > **Где в портале:** Instances (`/vms`) и страница VM (`/vms/`). В разделе **Instances** перечислены VM клиента с указанием имени, ОС, статуса, IP-адреса, характеристик и стоимости. Нажмите на нужную, чтобы открыть ее страницу. ## Страница VM {#the-vm-page} Вкладки: **Overview**, **Console**, **AI SSH Agent** (при включенном модуле AI), **Monitoring**, **Storage**, **Network**, **Configuration**, **Billing**, **Activity**. ![Обзор виртуальной машины со статусом, характеристиками, IP-адресом, графиком трафика и журналом действий](https://nexcmp.com/ru/docs/images/portal/virtual-machines-01-overview.webp) ### Действия {#actions} | Действие | Действие | |---|---| | Консоль | Открывает консоль в браузере — [Console](https://nexcmp.com/ru/docs/portal/console/) | | Перезагрузка / Остановка / Принудительная остановка | Управление питанием | | Сброс пароля | Генерирует новый пароль, отображается один раз | | Reinstall OS | Переустанавливает из шаблона; данные будут потеряны | | Change IP | Заменяет публичный IP-адрес (если поддерживается источником) | | Enable Auto Scaling | Масштабирует CPU/RAM при нагрузке, если включено | | Delete | Удаляет VM; почасовая тарификация прекращается | ### Отображаемая информация {#information-shown} Аптайм, расходы за текущий месяц, vCPU/RAM/диск с текущим потреблением, публичный и приватный IP, имя пользователя, график трафика, журнал действий и сводка биллинга (тариф, цикл, часы, остаток). ::: info Поля зависят от источника На странице VM отображается только то, что поддерживается её источником. Например, для VM в Proxmox VE недоступны проброс портов и смена IP, а список ОС определяется набором шаблонов в кластере. См. таблицу возможностей в разделе [Proxmox VE](https://nexcmp.com/ru/docs/infrastructure/proxmox/). ::: ## Вкладка биллинга {#billing-tab} Отображает тариф, цикл, общее количество часов, оставшееся время и журнал биллинга. Почасовые VM тарифицируются до момента удаления. Клиент может изменить цикл (**switch cycle**), чтобы внести предоплату на более длительный период со скидкой. ## Для администраторов {#for-administrators} Эта же VM доступна в панели администратора по пути Services › Virtual Machines, где вы можете выполнять действия от имени клиента или [авторизоваться под его аккаунтом](https://nexcmp.com/ru/docs/customers/login-as/). --- # Консоль {#console} > **В клиентском портале:** страница VM → вкладка **Console**. **В панели администратора:** System › Admin › License & updates → модули (web SSH). ## Назначение {#what-it-does} Вкладка **Console** открывает графическую сессию (VNC) к VM прямо в браузере, даже если сеть внутри VM недоступна. Веб-терминал **web SSH** доступен в качестве второй опции, если включен модуль SSH. ## Требования {#requirements} | Параметр | Консоль VNC | Web SSH | |---|---|---| | CloudStack | Console proxy VM (CPVM) доступна из панели — см. [CloudStack](https://nexcmp.com/ru/docs/infrastructure/cloudstack/) | Доступный порт SSH на VM | | Proxmox VE | Работает через панель (noVNC через Proxmox API; TLS-отпечаток зафиксирован) — см. [Proxmox VE](https://nexcmp.com/ru/docs/infrastructure/proxmox/) | Аналогично | | Панель | Console URL задан в [General settings](https://nexcmp.com/ru/docs/administration/general-settings/) | Служба `ssh-proxy` и флаг модуля `feature_ssh_web`; по умолчанию выключено — см. [Modules](https://nexcmp.com/ru/docs/infrastructure/modules/) | Если модуль web SSH выключен, во вкладке отображается **VNC only**. ## Использование {#use-it} 1. Откройте страницу VM → **Console**. 2. Нажмите **Console** (или **Open in new window**). Создается временный тикет, и консоль открывается по адресу `https:///console`. 3. Авторизуйтесь, используя имя пользователя и пароль VM (отображаются на вкладке Overview; при утере сбросьте пароль). ![Вкладка Console виртуальной машины](https://nexcmp.com/ru/docs/images/portal/console-01-tab.webp) ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | Сразу «Disconnected» | Браузер сохранил устаревший путь к консоли | Очистите данные сайта для этого домена и повторите попытку | | Черный экран | VM остановлена или запускается | Запустите VM и подождите | | Консоль не открывается в CloudStack | Console proxy VM не запущена или недоступна | Проверьте системные VM в CloudStack | | Нет опции SSH | Модуль Web SSH отключен | Включайте его только после установки `ssh-proxy` | --- # Snapshots и Backups {#snapshots-and-backups} > **Где найти в портале:** Snapshots (`/snapshots`), Snapshot schedules (`/snapshots/schedules`), Backups (`/backups`). Доступно только при включении функции в админ-панели. ## Назначение {#what-it-does} Snapshot сохраняет состояние диска VM, чтобы клиент мог выполнить откат после неудачного изменения. Snapshots можно создавать вручную или по расписанию. ## Доступность {#availability} | Source | Snapshots | Примечания | |---|---|---| | CloudStack | Да | Снимки томов; тарификация хранилища согласно настройкам | | Proxmox VE | Да | До **5 на ВМ**; создание, просмотр, откат и удаление | Пункт меню отображается только при включенной функции снимков и наличии у клиента ВМ с поддерживающим ее источником. ## Использование {#use-it} 1. Откройте **Snapshots**, нажмите **Create**, выберите ВМ и укажите имя. 2. Дождитесь перехода статуса в *ready*. 3. Для возврата выберите **Restore** у снимка и подтвердите — ВМ вернется к этому состоянию (и при необходимости перезапустится). 4. Удаляйте снимки, которые вам больше не нужны. ::: warning При восстановлении все данные, записанные после создания снимка, теряются. Защищенные ВМ нельзя восстановить или удалить из портала. ::: --- # Поддержка клиентов {#support-for-customers} > **Где найти в портале:** виджет чата на каждой странице, `/chat` и Support tickets. **Где в админ-панели:** Customers › Support › Tickets (`/support/tickets`), вкладка **Settings**. ## Для клиентов {#for-customers} - **Виджет чата** (в нижнем углу каждой страницы): клиент задает вопрос, а [AI Chat](https://nexcmp.com/ru/docs/ai/ai-chat/) отвечает на основе документации и данных его аккаунта. **Expand** открывает диалог на `/chat`. - **Talk to staff**: переводит диалог на сотрудников (через Telegram-группу администраторов). - Кнопки **Telegram / Zalo**: отображаются только после настройки ссылок в параметрах поддержки. - **Тикеты**: для сложных вопросов; ответы отправляются по эл. почте (`ticket_reply`). ## Для вас {#for-you} 1. Перейдите в **Customers › Support › Tickets**; новые тикеты и чаты появляются здесь вместе с историей переписки. 2. Отвечайте прямо в переписке. Клиент получает ответ на эл. почту через ваш [SMTP](https://nexcmp.com/ru/docs/administration/smtp-and-emails/). 3. На вкладке **Settings** включите или отключите виджет чата, укажите ссылки на Telegram и Zalo (только https) и выберите режим автоответов ИИ — см. [AI Chat](https://nexcmp.com/ru/docs/ai/ai-chat/). 4. Подключите [Telegram alerts](https://nexcmp.com/ru/docs/administration/telegram-notifications/), чтобы ваша команда получала оповещения о новых чатах. --- # Провайдер ИИ {#ai-provider} > **Где найти в админ-панели:** System › Settings › AI provider (`/settings/ai`). Переключатель модуля ИИ есть там и в System › Admin › License & updates (`/license`), карточка **Module**. ## Назначение {#what-it-does} AI Chat (автоматическая поддержка) и AI Agent (управление ВМ на естественном языке) поставляются без встроенной модели. Вы выбираете **собственного провайдера**: любой сервис с `chat/completions` API, **совместимым с OpenAI**, — например OpenAI, OpenRouter, шлюз LiteLLM или собственный сервер vLLM. NexCMP сохраняет эндпоинт и API-ключ (в зашифрованном виде) и использует их для всех функций ИИ. Оплата производится напрямую провайдеру. ## Требования {#requirements} | Параметр | Требование | |---|---| | Endpoint | OpenAI-совместимый базовый URL (`https://api.openai.com/v1`, `https://ai.example.com/v1`). NexCMP добавляет `/chat/completions` к URL, заканчивающимся на `/v1`; для других URL добавляется `/v1/chat/completions`; URL, уже оканчивающийся на `/chat/completions`, используется как есть. | | Модель | Модель с поддержкой **вызова инструментов (функций)**. На нее опираются как AI Chat, так и агент. | | API-ключ | Ключ для этого эндпоинта. Рекомендуется использовать ключ с **лимитом расходов** на стороне провайдера (например, виртуальный ключ LiteLLM с месячным бюджетом). | | Сеть | Сервер панели должен иметь доступ к эндпоинту по HTTP(S). URL, указанный в форме, может вести только в интернет на порты 80, 443, 8080 или 8443; чтобы использовать внутренний адрес, сначала сохраните провайдера, а затем выполните проверку. | | Зависимости | Включенный модуль **AI**. Информацию об агенте см. в [AI Agent](https://nexcmp.com/ru/docs/ai/ai-agent/#requirements). | ## Подготовка инфраструктуры {#prepare-the-infrastructure} 1. Зарегистрируйтесь у провайдера и создайте API-ключ. Если провайдер поддерживает бюджеты или лимиты запросов, установите ежемесячный лимит. 2. Запишите **базовый URL** и точное **название модели** (а также, при необходимости, до четырех резервных моделей). 3. Проверьте его с сервера NexCMP перед вводом: ```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"}]}' ``` Ответ JSON с `choices[0].message.content` означает, что эндпоинт работает. ## Подключение в NexCMP {#connect-in-nexcmp} 1. Перейдите в **System › Settings › AI provider**. 2. В карточке **Module AI** переключите модуль в положение **on**. Пока он не включен, клиенты не видят AI Chat и AI Agent в портале. (Его также можно включить в **License & updates**.) 3. В карточке **Connection** заполните: | Поле | Пример | Примечания | |---|---|---| | Использовать этого провайдера | включено | Для включения требуются базовый URL, модель и ключ. | | Display name | `LiteLLM` | До 60 символов. | | Базовый URL (OpenAI-совместимый) | `https://ai.example.com/v1` | `http://` или `https://`, до 300 символов, без пробелов. | | API-ключ провайдера | `sk-XXXX` | Хранится в зашифрованном виде; после сохранения отображаются только последние 4 символа. Оставьте пустым, чтобы сохранить текущий ключ. | | Модель по умолчанию | `gpt-4o-mini` | Буквы, цифры и `- _ . / : @`. | | Резервные модели | `gemini-2.5-flash` | Разделяются запятыми, до 4 моделей. Используются при сбое модели по умолчанию. | | Reasoning effort | Default (не отправляется) | `Minimal`, `Low`, `Medium` или `High`. Для рассуждающих моделей (Gemini, серия o) низкий уровень обеспечивает гораздо более быстрый ответ. Для обычных моделей оставьте значение Default. | 4. Нажмите **Save**, затем **Test connection**. Проверка отправит один короткий вопрос и отобразит `Connected — , ms` или ошибку, возвращенную провайдером. ![Страница AI-провайдера с включенным модулем AI и формой подключения, заполненной примерами значений](https://nexcmp.com/ru/docs/images/ai/ai-providers-01-connection.webp) ### Что происходит при сохранении {#what-saving-does} - Настройки провайдера сохраняются как единая запись конфигурации, а ключ шифруется с помощью AES-256-GCM для этой цели с использованием мастер-ключа установки. - Параметры поддержки **Primary model** и **Fallback model** (используемые в AI Chat) автоматически настраиваются на вашу модель по умолчанию и первую резервную модель. - Изменение записывается в журнал аудита (эндпоинт, модель, факт изменения ключа — сам ключ никогда не записывается). ## Проверка {#verify} 1. **Test connection** отображается зеленым цветом. 2. Войдите в портал под тестовым клиентом: в меню теперь доступны **AI Chat** (или значок чата) и **AI Agent**. 3. Спросите у AI Chat «What is my balance?». Ответ с указанием вашего реального баланса подтверждает, что провайдер корректно обрабатывает вызовы инструментов. ## Ограничения и примечания {#limits-notes} - **Один провайдер.** NexCMP использует единого настроенного провайдера для чата, агента и анализа тикетов. Резервные модели обеспечивают отказоустойчивость в рамках этого провайдера. - **Безопасность ключа.** Сохраненный ключ отправляется только на сохраненный эндпоинт. При изменении Base URL необходимо заново ввести ключ перед тестированием. - **Лимиты на клиента.** AI Chat доступен только авторизованным клиентам с лимитами сообщений в минуту и на чат. Для агента действует суточный лимит вызовов на аккаунт. См. [AI Chat](https://nexcmp.com/ru/docs/ai/ai-chat/) и [AI Agent](https://nexcmp.com/ru/docs/ai/ai-agent/). - **Конфиденциальность.** Вопросы клиентов и данные, которые считывает AI для этого клиента (в режиме только для чтения), отправляются вашему провайдеру. Укажите это в своей [политике конфиденциальности](https://nexcmp.com/ru/docs/customers/legal/). - **Контроль затрат.** NexCMP не ведет учет стоимости AI; используйте функции управления бюджетом у провайдера. - Модуль можно отключить в любой момент: пункты меню AI исчезнут, а маршруты AI будут возвращать 404 `module_disabled`. Некоторые фоновые задачи AI Chat (анализ тикетов, отложенные ответы) применят изменения после следующего перезапуска панели. ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | `base_url must be an http(s) URL` | Пропущена схема или присутствуют пробелы | Используйте `https://host/v1`. | | `api_key is required to enable the provider` | Ключ не сохранен | Введите ключ и сохраните. | | `base_url and model are required to enable the provider` | Пустое поле | Заполните оба поля. | | "Базовый URL заблокирован: только публичные http(s), порты 80/443/8080/8443" | Тестирование несохраненного внутреннего адреса или другого порта | Сначала сохраните провайдера, затем выполните проверку. | | `api_key is required (enter the key again when you change the endpoint)` | Base URL отличается от сохраненного | Введите ключ повторно. | | `model: letters, digits and - _ . / : @` | Недопустимый символ | Укажите точный идентификатор модели провайдера. | | `fallback_models: up to 4 model names` | Слишком много | Оставьте не более четырех. | | Тест завершается с ошибкой 401 | Неверный ключ | Проверьте ключ и эндпоинт. | | Тест завершается с ошибкой 404 или "model not found" | Неверный путь или модель | Проверьте base URL (`/v1`) и идентификатор модели. | | `Too many tests — wait a minute` (429) | Более 10 проверок в минуту | Подождите. | | В портале по-прежнему не отображается меню AI | Модуль отключен или провайдер не отмечен как "in use" | Включите модуль и активируйте провайдера. | --- # AI Chat {#ai-chat} > **В панели администратора:** Customers › Support › Ticket, вкладка **AI settings** (`/support/tickets?tab=settings`). Провайдер и модуль: System › Settings › AI provider (`/settings/ai`). **В клиентском портале:** плавающая кнопка чата и страница `/chat` (режим **Ask AI**). ## Назначение {#what-it-does} AI Chat отвечает на вопросы клиентов в любое время, находит данные *их собственного* аккаунта (баланс, услуги, платежи, недавние ошибки) и может выполнять действия от их имени — создать VM, изменить тариф — после подтверждения клиентом. Если ассистент не может помочь, клиент нажимает **Talk to a human**: чат передается вашим сотрудникам в Telegram и, если никто не ответит вовремя, превращается в тикет. Те же настройки AI позволяют системе **анализировать тикеты** для ваших сотрудников. ## Требования {#requirements} | Параметр | Требование | |---|---| | Модуль и провайдер | Включенный модуль **AI**, а также сохраненный и активный [AI provider](https://nexcmp.com/ru/docs/ai/ai-providers/). Без провайдера ассистент сообщит, что он не настроен. | | Клиенты | **Только авторизованные клиенты.** В установленном NexCMP нет публичного сайта, поэтому неавторизованный посетитель видит сообщение "Sign in to use AI Chat". | | Канал для сотрудников (необязательно) | Telegram-бот и чат для оповещений администратора (см. [Telegram notifications](https://nexcmp.com/ru/docs/administration/telegram-notifications/)). Этот же канал используется для передачи чатов и черновиков тикетов. | | Зависимости | [AI provider](https://nexcmp.com/ru/docs/ai/ai-providers/). | ## Подготовка инфраструктуры {#prepare-the-infrastructure} Помимо AI provider ничего не требуется. Если вы хотите настроить передачу чатов сотрудникам: 1. Создайте Telegram-бота с помощью @BotFather и сохраните токен. 2. Создайте группу или используйте личный чат с ботом и сохраните ID чата. 3. Укажите оба значения в System › Settings › Admin alerts (см. [Telegram notifications](https://nexcmp.com/ru/docs/administration/telegram-notifications/)). Функции поддержки используют этого же бота и чат. ## Подключение в NexCMP {#connect-in-nexcmp} 1. Убедитесь, что модуль AI включен и проверка провайдера проходит успешно ([AI provider](https://nexcmp.com/ru/docs/ai/ai-providers/)). 2. Откройте **Customers › Support › Ticket** и выберите вкладку **AI settings**. В верхней части левой карточки отображаются три статуса: *AI provider: configured*, *Telegram: channel present* и *On shift* или *Off shift*. 3. Левая карточка **AI + Telegram**: | Переключатель или поле | По умолчанию | Значение | |---|---|---| | Автоматический анализ тикетов с помощью AI | On | При получении нового тикета или сообщения AI считывает данные клиента (только для чтения) и формирует вероятную причину проблемы и черновик ответа в виде **внутренней заметки**. Клиенту сообщение не отправляется. | | Оповещения администратора в Telegram | On | Заметка приходит в Telegram с кнопками Send, Edit и Skip. | | AI auto-reply | Выкл | Автоматически отправляет простые ответы по инструкциям или продажам при выполнении всех условий безопасности (уверенность от 85 % и выше, отсутствие предупреждений); отправляется через 3 минуты с возможностью отмены в Telegram. | | Категории с разрешенным автоответом | `how_to`, `sales` | Только указанные. | | Основная модель, резервная модель | задается из настроек провайдера | Обычно оставляют значения, сохраненные на странице AI-провайдера. | | ID пользователя Telegram с правом выполнения действий | пусто | Пустое поле означает чат канала оповещений. | 4. Правая карточка **Live chat (customer widget)**: | Поле | По умолчанию | Значение | |---|---|---| | Enable chat widget | On | Виджет чата и страница `/chat`. | | Часы работы поддержки (вьетнамское время) | `08:00-22:00` | Время, когда сотрудники должны отвечать в Telegram. В нерабочие часы или при отсутствии Telegram-канала кнопка **Talk to a human** сразу преобразует чат в тикет. | | Макс. время ожидания сотрудника (минуты), затем перевод в тикет | 10 | От 1 до 240. | | Реплики AI / день / клиент | 40 | От 1 до 1000. После исчерпания лимита ассистент предлагает клиенту переключиться на оператора. | | Новые чаты / час / IP | 20 | От 1 до 1000. | | **Zalo OA link** | пусто | `https://zalo.me/...` Отображает кнопку **Chat on Zalo** (с QR-кодом) в чате. Если поле пустое, кнопка скрыта. | | **Telegram link** | пусто | `https://t.me/...` Отображает кнопку **Telegram**. Если поле пустое, кнопка скрыта. | | Общий дневной лимит реплик AI для авторизованных клиентов | 2000 | | | Общий дневной лимит для гостей | 500 | Отдельный пул; не используется, пока гостевой чат недоступен. | | Общий дневной лимит автоматического анализа тикетов | 200 | | | Путь к панели администратора (кнопка Telegram «Open admin») | пусто | URL вашей панели администратора, например `https://cloud.example.com/admin`. | Каждый переключатель или поле сохраняются сразу при изменении. 5. Внизу блок **Reply templates** (название, язык VI/EN/ZH, текст до 4,000 символов) предоставляет сотрудникам готовые ответы. ![Вкладка AI settings с переключателями AI и Telegram, лимитами онлайн-чата и быстрыми ссылками](https://nexcmp.com/ru/docs/images/ai/ai-chat-01-settings.webp) ![Страница чата клиента с ассистентом, кнопками быстрого доступа к Zalo и Telegram и возможностью переключиться на оператора](https://nexcmp.com/ru/docs/images/ai/ai-chat-02-portal.webp) ## Что ассистент может и чего не может делать {#what-the-assistant-can-and-cannot-do} - **Чтение:** выполняет поиск по вашей базе знаний и открытой документации, а также считывает личные данные авторизованного клиента через инструменты, предназначенные только для чтения. Данные других клиентов ему недоступны. - **Действия:** использует права доступа API самого клиента. Операции *чтения* выполняются сразу. Любые действия, влекущие изменения или списание средств, создают **карточку подтверждения** («Needs your confirmation» с тегами *Costs money* или *Delete*); ничего не произойдет, пока клиент не нажмет **Confirm**. В одном чате может находиться не более 3 карточек в ожидании, а для одного аккаунта действует ограничение до 10 подтвержденных операций записи в час. - **Запрещено:** он не может открывать консоли, создавать токены SSH или консоли, скачивать файлы доступа к Kubernetes, сбрасывать пароли или отображать секретные данные, такие как пароли прокси или ключи S3. Секретные данные никогда не попадают в контекст модели или историю чата. - **Безопасность:** его ответы проходят фильтрацию на выходе; текст клиента и результаты работы инструментов обрабатываются как данные, а не как инструкции. - **Баннер прозрачности:** в чате отображается сообщение «Answered by an AI assistant — it may be imperfect. Talk to a human for anything critical.» ## Переключение на оператора {#staff-hand-off} 1. Клиент нажимает **Talk to a human** и может указать свой адрес электронной почты. 2. Сообщение с перепиской поступает в Telegram-чат сотрудников. Сотрудники отвечают на это сообщение, и ответ появляется в клиентском чате от имени «[brand] Support». 3. Если никто не отвечает в течение времени ожидания (по умолчанию 10 минут), чат преобразуется в тикет в разделе **Customers › Support › Ticket**. То же самое происходит сразу в нерабочие часы службы поддержки или если Telegram не настроен, при этом клиенту сообщается об открытии тикета. 4. Администраторы также видят активные чаты на вкладке **Live chat**. ## Проверка {#verify} 1. Авторизуйтесь как тестовый клиент, откройте чат и задайте вопрос о ваших услугах. Ассистент ответит на него. 2. Попросите его создать что-либо платное: появится карточка подтверждения, и ничего не будет создано, пока вы не нажмете **Confirm**. 3. Нажмите **Talk to a human**. Сообщение поступит в ваш Telegram-чат (если он настроен) или по истечении времени ожидания будет создан тикет. 4. Если ссылки на Zalo и Telegram указаны, обе кнопки быстрого доступа отобразятся в чате. ## Ограничения и примечания {#limits-notes} - **Ограничения частоты запросов (на IP):** 20 сообщений в минуту и несколько переключений на оператора в час; **40 сообщений на диалог**. Эти лимиты фиксированы. - **Расходы:** каждая реплика ИИ обращается к вашему провайдеру. Уменьшите значение **AI turns / day / customer**, чтобы ограничить расходы. - **Автоответ по умолчанию отключен.** Включайте его только после того, как некоторое время понаблюдаете за черновиками. - **Языки:** ассистент отвечает на языке клиента; вьетнамский язык распознается по тексту. - **Реселлеры:** сайты реселлеров используют тикеты вместо виджета. ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | Клиенты не видят чат | Модуль AI отключен или выключена опция **Enable chat widget** | Включите обе опции. | | «Sign in to use AI Chat» | Посетитель не авторизован | Стандартное поведение NexCMP: сначала выполните вход. | | Ассистент сообщает, что провайдер AI не настроен | Провайдер отсутствует, не используется или не указан ключ | Заполните [AI provider](https://nexcmp.com/ru/docs/ai/ai-providers/). | | ИИ отвечает «talk to a human» после нескольких вопросов | Исчерпан дневной лимит на клиента | Увеличьте значение **AI turns / day / customer**. | | В теге Telegram отображается «no channel» | Не настроен бот или chat ID | Настройте [уведомления в Telegram](https://nexcmp.com/ru/docs/administration/telegram-notifications/). | | Отсутствует кнопка Zalo или Telegram | Поле ссылки не заполнено | Укажите ссылку. | | «Too many requests» в чате | Более 20 сообщений в минуту с одного IP | Подождите одну минуту. | | Лимит сообщений в чате исчерпан | Достигнут лимит в 40 сообщений | Начните новый диалог. | --- # AI Agent {#ai-agent} > **В панели администратора:** System › Settings › AI provider (`/settings/ai`) — переключатель модуля и провайдер; System › Admin › License & updates (`/license`) — переключатель модуля. **В клиентском портале:** AI Agent (`/ai/agent`) и страница `/chat/agent` либо режим **Agent** внутри чата. ## Назначение {#what-it-does} AI Agent подключается к Linux-ВМ клиента по SSH и выполняет задачи, описанные простыми словами: «check system health», «install Docker», «find recent errors», «free up disk space». Он показывает каждую предлагаемую команду и результат её выполнения. Команды только для чтения могут выполняться автоматически; любые действия, изменяющие состояние сервера, ожидают нажатия кнопки **Run** клиентом. ## Требования {#requirements} | Параметр | Требование | |---|---| | Модуль и провайдер AI | Включенный модуль **AI** и настроенный [AI provider](https://nexcmp.com/ru/docs/ai/ai-providers/). Для работы Agent также требуется модель с поддержкой tool calling. | | `openssh-client` на сервере панели | Agent выполняет команды с помощью собственной утилиты `ssh` панели (`/usr/bin/ssh`). Установщик развертывает `openssh-client`; проверить наличие можно с помощью `ssh -V`. Без неё Agent возвращает ошибку «ssh client is not installed on the panel server». | | Без отдельного SSH-шлюза | В стандартной установке используется встроенный SSH, и веб-терминал `ssh-proxy` **не** требуется. Только когда включена опциональная функция *web SSH* (`feature_ssh_web`) и установлена служба `ssh-proxy`, Agent вместо этого работает через `ssh-proxy`. | | Сеть | Сервер панели должен иметь доступ к IP-адресу ВМ по порту SSH (по умолчанию 22). Проверьте фаерволы и группы безопасности между панелью и гостевой сетью. | | VM | Принадлежащая клиенту, **работающая**, не заблокированная ВМ на базе **Linux** (ВМ с Windows отклоняются) с публичным или доступным IP-адресом. | | Учетные данные SSH | Имя пользователя и пароль ВМ, сохраненные в NexCMP (в зашифрованном виде при создании ВМ или сбросе пароля), либо сервисный ключ панели, если он установлен. Если нет ни того, ни другого, Agent сообщит о невозможности входа. | ## Подготовка инфраструктуры {#prepare-the-infrastructure} 1. Проверьте наличие SSH-клиента на сервере панели: ```bash ssh -V sudo apt-get install -y openssh-client # only if missing ``` 2. Проверьте, может ли сервер панели подключиться по SSH к гостевой ВМ: ```bash nc -vz 198.51.100.10 22 ``` Замените адрес на IP-адрес тестовой ВМ. Если подключение не удается, сначала настройте маршрутизацию или фаервол. 3. Убедитесь, что гостевая ОС разрешает вход по паролю для сохраненного в NexCMP пользователя (в некоторых облачных образах он отключен), либо что на гостевой ОС установлен сервисный ключ панели. ## Подключение в NexCMP {#connect-in-nexcmp} 1. Завершите настройку [AI provider](https://nexcmp.com/ru/docs/ai/ai-providers/): модуль включен, провайдер сохранен, проверка **Test connection** прошла успешно. 2. В панели администратора больше ничего настраивать не нужно. Переключатель модуля активирует отображение пунктов **AI Agent** в клиентском портале. 3. От лица клиента: откройте **AI Agent**, выберите работающий сервер и нажмите **Choose server**. Страница сначала проверит SSH фиксированной безопасной командой (без вызова AI) и отобразит *SSH connected* либо причину ошибки. 4. Введите задачу или выберите быстрый старт (*Check system health*, *Install Docker*, *Install Nginx*, *Find recent errors*, *Security check*, *Free up disk space*). ## Принцип выполнения команд {#how-it-runs-commands} - **Откуда:** с сервера панели с помощью системного клиента `ssh`, по одной неинтерактивной команде за раз. Целевым адресом всегда является IP-адрес ВМ **из базы данных**, а не из запроса; доступ возможен только к работающей и незаблокированной ВМ самого владельца. - **Аутентификация:** сохраненный пароль передается через одноразовый вспомогательный процесс `SSH_ASKPASS` в окружении процесса — он не записывается на диск и не передается в командной строке. Ключи хоста не фиксируются (ВМ переустанавливаются с новыми ключами). Вывод каждой команды ограничен 200 KB, а время выполнения ограничено (60 секунд). - **Цикл Agent:** ИИ предлагает команды и считывает их вывод; один раунд завершается максимум после **10 шагов**. - **Режимы:** | Режим | Поведение | |---|---| | **Confirm** | Каждая команда ожидает нажатия **Run**. | | **Auto** | Автоматически выполняются только команды из строгого разрешающего списка команд только для чтения (например, `df -h`, `ps`, `journalctl`). Все остальные команды, а также все, что парсер не может однозначно проанализировать (переменные, подстановка команд, перенаправление в файлы), ожидает нажатия **Run**. | - **Метки риска:** для команд, которые перезаписывают или удаляют файлы, записывают данные на диски, изменяют учетные записи или SSH Keys, отправляют данные на внешний сервер, открывают низкоуровневые сетевые соединения, выполняют обфусцированный код, загружают и запускают скрипты, выключают или перезагружают машину либо обращаются к другим серверам, всегда отображается **Needs confirmation**, даже в режиме Auto. - **Недоверенный вывод:** вывод команд передается модели как ненадежные данные; инструкции внутри него не выполняются. ## Проверка {#verify} 1. Выберите работающую тестовую ВМ. На странице отобразится *SSH connected*. 2. Отправьте запрос «Check CPU, RAM and disk». В режиме Auto команды только для чтения выполнятся автоматически, а в ответе будет представлена их сводка. 3. Отправьте запрос «Install Nginx». Появится команда установки с кнопками **Run** и **Skip**; ничего не будет выполнено, пока вы не нажмете **Run**. 4. Счетчик в верхней части показывает количество обращений к ИИ, использованных за сегодня (например, `3/300`). ## Ограничения и примечания {#limits-notes} - **Дневной лимит:** 300 обращений к ИИ на клиента в сутки (UTC); сбрасывается в 00:00 UTC. При исчерпании лимита Agent отвечает «Daily AI quota reached». - **Параллельные запуски:** не более 2 одновременных запусков Agent на клиента; в рамках сессии выполняется только один шаг за раз. - **Сессии:** до 100 сообщений на сессию, до 4,000 символов в сообщении. Сессия привязана к одной ВМ; при удалении или передаче ВМ старая сессия становится доступной только для чтения. - **Заблокированная или остановленная ВМ, либо Windows:** ВМ отображается со статусом *Locked*, *Stopped*, *Windows* или *No address*, и ее нельзя выбрать. - **Вход от имени пользователя:** администратор, вошедший от имени клиента, не может использовать функции Agent для работы с учетными данными (см. [Log in as a customer](https://nexcmp.com/ru/docs/customers/login-as/)). - **Ответственность:** Agent может ошибаться. Портал предупреждает клиентов о необходимости проверять команды перед выполнением. Укажите в своих условиях обслуживания, что клиенты несут ответственность за одобряемые ими команды. - Отключение модуля ИИ удаляет пункты Agent, а маршруты возвращают 404 `module_disabled`. ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | "SSH-клиент не установлен на сервере панели (apt install openssh-client)" | Отсутствует бинарный файл `ssh` | `sudo apt-get install -y openssh-client`. | | "Агенту не удалось войти" / `ssh: no saved credentials for this VM` | Нет сохраненного пароля и ключа для операций | Сбросьте пароль ВМ в портале, чтобы сохранить его повторно, или установите ключ для операций. | | "Сервер не ответил вовремя" | Брандмауэр, SSH не слушает порт, ВМ занята | Проверьте `nc -vz 22` с сервера панели; запустите `sshd` на ВМ. | | "Не удалось подключиться к SSH на этом сервере" | Маршрутизация или группа безопасности | Разрешите серверу панели доступ к ВМ по порту 22. | | "ВМ не запущена" / "Доступ запрещен" | ВМ остановлена, заблокирована, удалена или принадлежит другому клиенту | Запустите её, разблокируйте или выберите другую. | | "Недоступно: N (остановлена, заблокирована или Windows)" | Причины, перечисленные выше | ВМ должна работать под управлением Linux и быть запущена. | | "SSH-шлюз временно недоступен" | Функция Web SSH включена, но `ssh-proxy` не работает | Запустите `ssh-proxy` или отключите функцию Web SSH, чтобы использовать встроенный SSH. | | "ИИ отвечает слишком медленно (более 90 секунд)" | Медленный ответ провайдера | Используйте более быструю модель или меньшее значение **Reasoning effort**. | | "Достигнут дневной лимит ИИ" | Использовано 300 вызовов | Подождите до 00:00 UTC. | | "Эта сессия все еще выполняется" | Выполняется другой запрос | Подождите или нажмите **Stop**. | --- # REST API > **В портале:** справочник API по адресу `https:///apidoc` (публичный) и API-ключи по адресу `/api-keys`. **В панели администратора:** в разделе Customers › API keys (`/customers/apikeys`) перечислены ключи, созданные клиентами. ## Назначение {#what-it-does} Каждое действие, доступное клиенту на портале — просмотр и управление ВМ, чтение счетов, управление SSH Keys, Kubernetes, хранилищем, тикетами поддержки — доступно через версионированный REST API по адресу `https:///v1/`. Клиенты обращаются к нему из скриптов и CI с помощью **API key** с ограниченной областью действия. Этот же API используется [`cmp` утилитой командной строки](https://nexcmp.com/ru/docs/developers/cmp-cli/) и [MCP-сервером](https://nexcmp.com/ru/docs/developers/mcp/), а справочник генерируется на основе запущенной системы, поэтому он всегда содержит именно те функции, которые у вас включены. ## Требования {#requirements} | Параметр | Требование | |---|---| | Публичный HTTPS-адрес | API работает на вашем основном домене (и на собственном домене каждого реселлера). | | API-ключ | Создаётся клиентом в портале; см. [API keys](https://nexcmp.com/ru/docs/developers/api-keys/). | | Зависимости | Нет. Эндпоинты модулей, которые вы не включили (например, Kubernetes или Object Storage), скрыты из справочника и отклоняются. | ## Подготовка инфраструктуры {#prepare-the-infrastructure} Ничего устанавливать не нужно. Если перед NexCMP используется reverse proxy, перенаправляйте `/v1/`, `/mcp`, `/cli/` и `/apidoc` на панель (в конфигурации nginx установщика это уже настроено). ## Подключение в NexCMP {#connect-in-nexcmp} ### Интерактивный справочник {#the-interactive-reference} Откройте `https://cloud.example.com/apidoc` (замените хост на ваш домен; клиенты реселлера видят справочник на домене реселлера и с его именем). Здесь представлена документация по эндпоинтам с примерами запросов и ответов для curl, `cmp` CLI, JavaScript, Python и Go, поле поиска (Ctrl или Cmd + K) и панель **Try it**. Функция Try it отправляет запросы только к текущему сайту с ключом, который вставляет посетитель (он сохраняется в сессии браузера); по умолчанию она работает только на чтение, а для операций записи или платных вызовов требуются дополнительный переключатель и подтверждение. ### Загрузки и машиночитаемые документы {#downloads-and-machine-readable-documents} Все они публичны, не требуют ключа и генерируются для каждого сайта: | URL | Содержимое | |---|---| | `/apidoc` | Интерактивный справочник. | | `/v1/public/openapi.json` | Документ OpenAPI 3.1. | | `/v1/public/openapi.yaml` | То же, YAML. | | `/v1/public/postman.json` | Коллекция Postman. | | `/v1/public/insomnia.json` | Экспорт для Insomnia. | | `/v1/public/api.md` | Справочник в виде одного файла Markdown. | | `/v1/public/api-catalog` | Облегчённый JSON: бренд, базовый URL, префикс ключа, каждый scope и каждый эндпоинт с указанием метода, пути, scope и необходимости `Idempotency-Key`. | ```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 ``` В Postman выберите **Import › Link** и вставьте `https://cloud.example.com/v1/public/postman.json`. На странице справочника также доступны однофайловые клиенты API для JavaScript и Python. ### Аутентификация {#authentication} Передавайте ключ в заголовке `Authorization`: ```bash curl -s https://cloud.example.com/v1/billing/wallet \ -H "Authorization: Bearer vk_XXXX" ``` - Ключи клиентов начинаются с `vk_`. Ключи **привязаны к сайту**: ключ, созданный на `cloud.example.com`, не работает на домене реселлера. - Токены сессий браузера (`pt_...`) предназначены только для портала; для автоматизации используйте ключ. - **Scopes** ключа определяют доступные операции; при отсутствии scope возвращается HTTP 403 `scope_required`. См. [API keys](https://nexcmp.com/ru/docs/developers/api-keys/). - Проверить ключ можно с помощью `GET /v1/apikeys/self`: запрос возвращает имя ключа, scopes, срок действия и остаток лимита запросов (доступно любому ключу). ### Примеры {#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 ``` Точные поля запроса для каждой операции приведены в `/apidoc`. ### Ошибки {#errors} Каждая ошибка возвращается в формате JSON со стабильным `code` и понятным сообщением `message`: ```json {"error": {"code": "scope_required", "message": "Key lacks scope vm:write"}} ``` | HTTP | Типичный `code` | Значение | |---|---|---| | 401 | `unauthenticated`, `key_invalid`, `key_revoked`, `key_expired`, `key_ip_denied`, `site_mismatch`, `api_keys_disabled` | Ключ отсутствует, неизвестен, отозван или просрочен; IP клиента вне белого списка ключа; ключ от другого сайта или API keys отключены. | | 403 | `scope_required`, `endpoint_not_public`, `account_blocked`, `quota_exceeded`, `impersonate_forbidden` | У ключа нет нужного scope; эндпоинт недоступен для ключей; аккаунт заблокирован; достигнута [квота](https://nexcmp.com/ru/docs/billing/quotas/); действие запрещено в сессии подмены пользователя. | | 404 | `not_found` | Не найдено — также возвращается для ресурсов других пользователей. | | 422 | `invalid_argument` | Ошибка валидации (поле указано в ответе). | | 429 | `rate_limited` | Слишком много запросов; подождите до `Retry-After`. | | 503 | `maintenance` | Включён режим обслуживания: чтение работает, операции записи отклоняются. | ### Лимиты запросов {#rate-limits} | Лимит | По умолчанию | |---|---| | На ключ | 120 запросов в минуту | | На аккаунт (все ключи суммарно) | 300 запросов в минуту | Каждый ответ содержит `X-RateLimit-Limit`, `X-RateLimit-Remaining` и `X-RateLimit-Reset`; при ошибке 429 добавляется `Retry-After`. ### Идемпотентность {#idempotency} Для платных и неповторяемых команд (создание, смена тарифа, покупка, удаление и т. д.) **требуется** заголовок `Idempotency-Key` (любая строка до 200 символов; отлично подходит UUID). Отправьте тот же ключ повторно после таймаута, и сервер вернёт **исходный** результат (с заголовком `Idempotency-Replayed: 1`) вместо повторного выполнения операции. Повторное использование ключа для другой команды возвращает 422; если запрос ещё обрабатывается, возвращается 409/`Retry-After`. Без этого заголовка платный вызов отклоняется. ## Проверка {#verify} 1. Создайте ключ со scope `vm:read` в портале (**API keys › Create key**). 2. Выполните: ```bash curl -i https://cloud.example.com/v1/apikeys/self -H "Authorization: Bearer vk_XXXX" ``` Вы получите HTTP 200 и заголовки с лимитами запросов. 3. `curl -s https://cloud.example.com/v1/vm -H "Authorization: Bearer vk_XXXX"` возвращает список VM аккаунта. В портале вызовы отображаются в столбце ключа **Last used** и в **Key usage log**. ## Ограничения и примечания {#limits-notes} - **Недоступно через ключ:** пополнение баланса, вывод средств, изменение карт или автопополнения, смена пароля, e-mail или 2FA, удаление аккаунта, создание, редактирование и отзыв других ключей. Для этих действий требуется активная сессия в браузере. - **Скрытые модули:** в справочнике и документе OpenAPI отображаются только те возможности, которые включены на данном сайте. - **Размер ответа и пагинация:** эндпоинты со списками используют пагинацию (`page`, `per_page`); точные параметры для каждого эндпоинта смотрите в документе OpenAPI. - **Время и суммы:** суммы указываются в центах USD, если в названии поля не указано иное. - **Admin API:** в консоли администратора есть собственный раздел **System › Admin › API** и ключи администратора (`ofw_...`) для управления системой; они отделены от описанного здесь API клиента. - **Версионирование:** префикс пути `/v1` стабилен; в ответы могут добавляться новые поля. ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | 401 при использовании нового ключа | Ключ от другого домена, истек или введен с пробелами | Создайте ключ на вызываемом домене; проверьте заголовок `Authorization: Bearer vk_...`. | | 403 `scope_required` | Отсутствует scope | Отредактируйте ключ в портале и добавьте scope. | | 401 `key_ip_denied` или `site_mismatch` | Ключ ограничен другими IP-адресами («allowed IPs») или создан на другом домене | Добавьте IP-адрес своего сервера в разрешенные IP ключа или обращайтесь к домену, на котором он был создан. | | 404 для существующей VM | VM принадлежит другому аккаунту | Используйте ключ владельца. | | 400/422 с требованием `Idempotency-Key` | Платная операция без заголовка | Добавьте `Idempotency-Key: `. | | 429 | Превышен лимит | Снизьте частоту запросов; используйте `Retry-After`. | | `/apidoc` возвращает меньше данных, чем ожидалось | Модуль отключен | Включите модуль в License & updates. | --- # Ключи API и области доступа {#api-keys-and-scopes} > **В портале:** API keys (`/api-keys`). **В панели администратора:** Customers › Customers › API keys (`/customers/apikeys`). ## Назначение {#what-it-does} **API key** позволяет скрипту, задаче CI, [`cmp` CLI](https://nexcmp.com/ru/docs/developers/cmp-cli/) или ИИ-ассистенту ([MCP](https://nexcmp.com/ru/docs/developers/mcp/)) вызывать [REST API](https://nexcmp.com/ru/docs/developers/api/) от имени конкретного клиента с предоставленными правами (**scopes**). Клиентские ключи начинаются с `vk_`. Они могут читать и управлять сервисами, но **никогда** не имеют доступа к деньгам или самой учетной записи. ## Требования {#requirements} | Параметр | Требование | |---|---| | Клиент | Авторизованная сессия в портале (ключ не может создавать или изменять другие ключи, как и администратор, вошедший от имени клиента). | | Переключатель | Ключи API включены по умолчанию. Если они отключены, запросы возвращают 401 `api_keys_disabled`. | | Зависимости | Scopes продукта отображаются только тогда, когда этот продукт включен на сайте. | ## Создание ключа (клиент) {#create-a-key-customer} 1. Войдите в портал и откройте **API keys**. 2. Нажмите **Create key**. 3. Заполните форму: | Поле | Правило | |---|---| | **Имя ключа** | Обязательно, до 60 символов («deploy server», «backup script»). | | **Что разрешено этому ключу** | Отметьте нужные scopes — как минимум один. Ключу только для чтения не следует давать разрешения на запись. Будьте осторожны со scopes, которые влекут списание средств или удаление данных. | | **Expiry** | Бессрочно, 30 дней, 90 дней или 1 год (API принимает от 1 до 3650 дней). | | **Разрешить вызовы только с этих IP** | Один IP-адрес или диапазон CIDR на строку, до 20 (IPv4 или IPv6). Пустое значение означает любой IP. По возможности всегда указывайте IP-адрес своего сервера. | 4. Подтвердите форму. Ключ отображается **один раз** в окне «Key created — shown ONCE». Скопируйте его и нажмите **I saved the key**. Сохраняется только хеш SHA-256, поэтому даже администратор не сможет просмотреть его снова; в случае утери отзовите ключ и создайте новый. 5. В портале также отображается готовая команда `curl` для проверки ключа. Ключ выглядит как `vk_` с последующей длинной случайной строкой. В списке отображаются только первые символы (например, `vk_a1b2c3d4`), scopes, срок действия, время последнего использования, количество запросов и статус (*Active*, *Expired*, *Revoked*). ### Редактирование, отзыв, аудит {#edit-revoke-audit} - **Edit** позволяет изменить имя, скоупы, разрешенные IP-адреса и срок действия. Действие недоступно во время сеанса имперсонации. - **Revoke** немедленно отзывает ключ без возможности отмены. Запись сохраняется, чтобы журнал использования оставался доступным. - **Key usage log** отображает команды записи и все ошибки за последние 60 дней: время, запрос, ключ, результат и исходный IP-адрес. - По умолчанию в аккаунте может быть не более **10 активных ключей**. - Ключи, созданные через CLI или вход по MCP, отображаются в разделе **Connected apps & devices** и могут быть отозваны там же. ## Скоупы {#scopes} Имена скоупов имеют формат `area:action`. Список доступных зависит от подключенных у вас продуктов. | Скоуп | Разрешает | |---|---| | `catalog:read` | Чтение тарифных планов и каталога. | | `vm:read` | Просмотр виртуальных машин, метрик и счетов за ВМ. | | `vm:write` | Управление питанием, базовые изменения, фаервол, быстрые Snapshots. | | `vm:create` | **Создание ВМ (платно).** | | `vm:plan` | **Смена тарифа или изменение размера (платно).** | | `vm:destroy` | **Удаление ВМ.** | | `vm:restore` | **Восстановление ВМ из Snapshots (перезаписывает диск).** | | `vm:console` | Открытие тикетов VNC-консоли. | | `sshkey:read`, `sshkey:write` | Чтение, добавление и удаление SSH Keys. | | `volume:read`, `volume:write`, `volume:create`, `volume:destroy` | Диски данных (создание и расширение платны; удаление ведет к потере данных). | | `backup:read`, `backup:write`, `backup:restore` | Backups (восстановление перезаписывает диск). | | `billing:read` | Кошелек, счета, история платежей — **только чтение**. | | `bandwidth:buy` | **Покупка дополнительного трафика (платно).** | | `account:read`, `account:write` | Профиль, обзор, активность, уведомления; `account:write` только отмечает уведомления как прочитанные. | | `apikey:read` | Просмотр списка ключей аккаунта и журнала использования (без создания, изменения и отзыва). | | `apikey:self` | По умолчанию для каждого ключа: проверка вызывающего ключа (`GET /v1/apikeys/self`). | | `ticket:read`, `ticket:write` | Тикеты техподдержки. | | `aff:read`, `transfer:read` | Партнерская программа и трансфер услуг — только чтение. | | `k8s:read`, `k8s:write`, `k8s:create`, `k8s:scale`, `k8s:destroy`, `k8s:kubeconfig` | Kubernetes (создание и масштабирование платны; kubeconfig с правами cluster-admin). | | `vpc:read`, `vpc:write`, `vpc:create`, `vpc:destroy` | Private Cloud. | | `image:read`, `image:write` | Образы ОС и ISO (хранилище тарифицируется почасово). | | `s3:read`, `s3:write`, `s3:create`, `s3:destroy`, `s3:keys` | Object Storage (секрет S3 отображается только один раз). | | `vpn:read`, `vpn:detail`, `vpn:write`, `vpn:create`, `vpn:destroy` | VPN и прокси IPv6 (данные подключения включают пароли прокси). | | `dedicated:read`, `dedicated:write`, `dedicated:console`, `dedicated:create`, `dedicated:destroy` | Выделенные серверы (создание списывает средства с кошелька; удаление переустанавливает ОС). | | `shield:read`, `shield:write`, `shield:agent` | DDoS Shield, только если модуль включен. | Вызов за пределами скоупов ключа возвращает ответ **403 `scope_required`**; путь, который не разрешено вызывать ни одному ключу, возвращает **403 `endpoint_not_public`**. ### Что никогда не может делать ключ {#what-a-key-can-never-do} Ни один скоуп не позволяет: пополнять баланс или выводить средства, изменять привязанные карты или автопополнение, менять пароль, e-mail или 2FA, удалять аккаунт, создавать, изменять или отзывать другие ключи. Для этих действий всегда требуется авторизованная сессия в браузере. Даже в случае утечки ключ не позволит получить доступ к средствам или аккаунту клиента. ## Правила, на которые можно положиться {#rules-you-can-rely-on} | Правило | Описание | |---|---| | Привязка к сайту | Ключ работает только на том сайте (домене), где он был создан. | | Лимиты запросов | Для ключа и для аккаунта: по умолчанию 120 и 300 запросов в минуту соответственно. | | Идемпотентность | Платные или неповторяемые операции требуют заголовка `Idempotency-Key`. | | Квоты | На ключ распространяются те же [квоты](https://nexcmp.com/ru/docs/billing/quotas/), что и на клиента. | | Блокировка аккаунта | Ключи заблокированного клиента перестают работать (403 `account_blocked`). | | Аудит | Отзыв ключа администратором записывается в журнал аудита администратора. | ## Представление администратора {#administrator-view} 1. Перейдите в **Customers › API keys** (`/customers/apikeys`). В таблице отображаются имя и первые символы ключа, владелец, области доступа, статус, последнее использование (время, количество запросов, IP) и срок действия. 2. Фильтруйте по сайту, если у вас есть реселлеры. Ищите по имени, ID или первым символам ключа. 3. Нажмите **Revoke**, чтобы отозвать активный ключ, или **Log** для просмотра журнала его использования. 4. Администраторы **видят и отзывают** ключи, но не могут просматривать их полностью или создавать их для клиентов. ![Список API-ключей клиентов для администратора с областями доступа, статусом, последним использованием и кнопкой Revoke](https://nexcmp.com/ru/docs/images/developers/api-keys-02-admin.webp) ## Проверка {#verify} 1. Создайте ключ только с областью доступа `vm:read`. 2. `curl -s https://cloud.example.com/v1/vm -H "Authorization: Bearer vk_XXXX"` возвращает список ВМ. 3. `curl -s -X POST .../v1/vm//start -H "Authorization: Bearer vk_XXXX"` возвращает ответ 403 `scope_required`. 4. Отозовите ключ; теперь первый вызов возвращает 401 `key_revoked`. ## Ограничения и примечания {#limits-notes} - Ключ больше никогда не отображается. Относитесь к нему как к паролю и сохраните в менеджере секретов или в секретах CI. - Рекомендуется использовать один ключ на скрипт, минимальные области доступа, короткий срок действия и белый список IP; выполняйте ротацию, создавая новый ключ и отзывая старый. - Срок действия ключей при входе с устройства (CLI, MCP) по умолчанию составляет 90 дней. - Отзыв ключа не влияет на удаленные или переданные ресурсы. ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | Ошибка `too_many_keys` (422) | Достигнут лимит активных ключей (по умолчанию 10) | Отозовите старый ключ. | | Ошибка `invalid_argument`: не выбрана область доступа | Не отмечена ни одна область доступа | Отметьте хотя бы одну область доступа. | | Ошибка `invalid_argument` в разрешенных IP | Запись не является IP-адресом или диапазоном, указана неверная длина префикса или задано более 20 записей | Один IP или CIDR на строку, например `203.0.113.0/24`. | | Создание отклонено при олицетворении | `impersonate_forbidden` | Попросите клиента создать ключ. | | 401 `key_expired` | Истек срок действия | Создайте новый ключ. | | 401 `key_ip_denied` | IP-адрес источника запроса не входит в список разрешенных | Добавьте этот IP или очистите список. | | 401 `api_keys_disabled` | Функция отключена | Обратитесь к администратору (настройка `api_keys_enabled`). | --- # Утилита командной строки `cmp` {#cmp-command-line-tool} > **Где найти в портале:** команды установки находятся в справочнике API (`https:///apidoc`, раздел Command-line interface). Подтверждение входа: `https:///link`. Подключенные устройства: API keys (`/api-keys`) › Connected apps & devices. ## Назначение {#what-it-does} `cmp` — это компактная утилита командной строки для ваших клиентов (и для вас), которая превращает **каждую операцию API в отдельную команду**: `cmp vm list`, `cmp vm start `, `cmp billing invoice list`. Она собирается на основе документа OpenAPI **вашей** установки во время релиза, поэтому набор команд в точности соответствует включенным функциям. Это единый статический бинарный файл для Linux, macOS и Windows (amd64 и arm64), не требующий установки дополнительных компонентов. ## Требования {#requirements} | Параметр | Требование | |---|---| | Сервер | Ничего дополнительно. Пакеты релиза включены в состав NexCMP и раздаются панелью по адресу `https:///cli/`. | | Компьютер клиента | Linux, macOS или Windows (PowerShell 5.1+). `ssh-keygen` (OpenSSH 8.0+) требуется только для проверки подписи. | | Учетные данные | Вход через браузер с одноразовым кодом или [API key](https://nexcmp.com/ru/docs/developers/api-keys/). | | Сеть | HTTPS-подключение к вашей панели. CLI отклоняет отправку ключа по обычному `http://`, за исключением `localhost`. | ## Подготовка инфраструктуры {#prepare-the-infrastructure} Ничего. Панель отдает эти файлы из `/cli/` (сборка или загрузка не требуются): | Файл | Назначение | |---|---| | `install.sh`, `install.ps1` | Инсталляторы для Linux/macOS и Windows; они содержат адрес вашей панели. | | `latest.json` | Текущая версия, список файлов, размеры, sha256. | | `v/cmp___.tar.gz` или `.zip` | Программы: linux amd64/arm64, darwin amd64/arm64/universal, windows amd64/arm64. | | `v/SHA256SUMS`, `SHA256SUMS.sig` | Контрольные суммы и их подпись ed25519. | | `cmp-cli.pub` | Открытый ключ релиза. | ## Установка (клиент) {#install-customer} macOS и Linux: ```bash curl -fsSL https://cloud.example.com/cli/install.sh | sh ``` Windows PowerShell: ```powershell irm https://cloud.example.com/cli/install.ps1 | iex ``` Инсталлятор выбирает пакет под нужную ОС и процессор, скачивает `SHA256SUMS` и его подпись, проверяет подпись встроенным в скрипт ключом, сверяет хеш пакета и устанавливает `cmp` в `/usr/local/bin` (от root) или `~/.local/bin`; в Windows — в `%LOCALAPPDATA%\cmp\bin` (с добавлением в пользовательский `PATH`). При ошибке любой проверки ничего не устанавливается. | Переменная | Значение | |---|---| | `CMP_VERSION` | Установить эту версию вместо последней. | | `CMP_INSTALL_DIR` | Папка установки. | | `CMP_REQUIRE_SIGNATURE` | `1` = прерывать установку, если подпись не удается проверить. | | `CMP_BASE_URL` | Базовый адрес загрузки (для зеркал). | Ручная загрузка и проверка: ```bash curl -fsSLO https://cloud.example.com/cli/latest.json sha256sum --check --ignore-missing SHA256SUMS ``` ![Раздел API-справочника с командой cmp install для macOS и Linux](https://nexcmp.com/ru/docs/images/developers/cmp-cli-01-install.webp) ## Вход {#log-in} ```bash cmp login ``` 1. CLI выводит одноразовый **код** и ссылку (`https://cloud.example.com/link?code=WDJB-MJHT`), открывает браузер и ожидает. 2. Войдите в портал через браузер, проверьте имя клиента, устройство, IP-адрес и страну, отметьте нужные разрешения (scopes) и выберите срок действия ключа (по умолчанию 90 дней). Разрешения, списывающие средства или удаляющие данные, изначально отключены. Нажмите approve. 3. CLI получает **собственный ключ**, отдельный от созданных клиентом вручную, и сохраняет его в `~/.config/cmp/config.json` (права `0600`; `%APPDATA%\cmp` в Windows). Он отображается в **API keys › Connected apps & devices** и может быть отозван там же. Срок действия кода — 10 минут. Для подтверждения требуется реальная активная сессия в портале с подтвержденным e-mail, а не другой ключ или сессия имперсонации. Полезные флаги: `--scopes vm:read,billing:read`, `--name "build server"`, `--no-browser`, `--profile`, `--api-url`. Для CI или серверов без браузера используйте ключ из портала: ```bash printf %s "$KEY" | cmp login --with-token export CMP_TOKEN=vk_XXXX # nothing is written to disk cmp whoami ``` ## Использование команд {#using-commands} ```text cmp [subgroup] [ ...] [flags] ``` - Параметры пути передаются позиционными аргументами; параметры запроса и поля тела преобразуются во флаги в формате kebab-case (`--start-port 443`). - `--data '{"a":1}'`, `--data @file.json` или `--data -` отправляет тело JSON целиком; флаги переопределяют его поля. - `cmp help vm firewall add` (или `--help`) отображает подробную информацию о любой команде. ```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 ``` Встроенные команды: `login`, `logout`, `whoami`, `config`, `api`, `completion`, `version`, `update`, `help`. Все остальные берутся из API-документа. Глобальные флаги: | Флаг | Значение | |---|---| | `-o, --output json\|table\|yaml` | Формат. По умолчанию `table` в терминале и `json` при передаче через пайп. | | `--profile`, `--api-url` | Какую сохраненную учетную запись и какой сайт использовать. | | `-y, --yes` | Пропускать подтверждение для деструктивных или платных команд. | | `--idempotency-key ` | Выбрать ключ для платной команды. | | `--retry ` | При HTTP 429 ждать `Retry-After` и повторять запрос до n раз. | | `--timeout ` | Время ожидания заголовков ответа в секундах (по умолчанию 60). | | `--debug` | Выводить процесс HTTP-обмена в stderr со скрытыми ключами. | Команды, которые **списывают средства с кошелька или удаляют данные**, запрашивают подтверждение и при оплате отправляют автоматически сгенерированный `Idempotency-Key` (выводится в stderr, что позволяет безопасно повторить попытку с `--idempotency-key`). Без терминала они отклоняются, если не передан флаг `--yes`. ### Коды возврата {#exit-codes} | Код | Значение | |---|---| | 0 | Успешно | | 1 | Другая ошибка (сеть, незарегистрированные коды HTTP 4xx/5xx) | | 2 | Ошибка использования | | 3 | Не авторизован (401/403) | | 4 | Не найдено (404) | | 5 | Превышен лимит запросов (429) | | 6 | Требуется подтверждение или отклонено | | 130 | Прервано | ### Профили и переменные окружения {#profiles-and-environment} `cmp config` выводит список профилей; `cmp config use ` переключает; клиенты реселлера используют собственный домен: `cmp login --api-url https://shop.example.net --profile shop`. Приоритет: флаг, окружение, файл конфигурации. Переменные: `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' ``` Автодополнение для оболочки: `cmp completion bash|zsh|fish|powershell`. ## Обновление и удаление {#update-and-uninstall} ```bash cmp version cmp update --check cmp update ``` `cmp update` загружает `latest.json`, `SHA256SUMS` и подпись, проверяет подпись с помощью открытого ключа, **встроенного в текущий бинарный файл**, проверяет хеш пакета и только затем обновляет исполняемый файл. Для отката версии требуется `--force`. При обновлении NexCMP панель раздает релиз CLI, поставляемый с новой версией. Для удаления удалите исполняемый файл `cmp` и каталог конфигурации (его путь показывает `cmp config path`). При утере устройства отзовите ключ в разделе **API keys**. ## Проверка {#verify} 1. `cmp version` выводит версию и версию документа API. 2. `cmp login`, подтвердите в браузере, затем `cmp whoami` покажет профиль и URL вашей панели. 3. `cmp vm list` возвращает список ваших VM; `cmp vm list -o json | jq .` выводит исходный JSON. ## Ограничения и примечания {#limits-notes} - Список команд зависит от вашей сборки: пакеты генерируются на основе документа OpenAPI вашей системы при сборке релиза, поэтому для продуктов, отключенных в вашем релизе, команд не будет. Для неизвестных CLI путей используйте `cmp api`. - CLI распространяется по лицензии MIT. - Каждый пакет подписан ключом ed25519; ключ верификации зашит в установщик и бинарный файл, а не загружается при обновлении. - Ключи ограничены по лимитам запросов на ключ и на аккаунт (см. [REST API](https://nexcmp.com/ru/docs/developers/api/#rate-limits)). ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | `curl .../cli/install.sh` возвращает 404 | В релизе на сервере отсутствует папка CLI или хост не включен в лицензию | Проверьте `https:///cli/latest.json` и домен; обновите NexCMP. | | "не удалось проверить подпись" | `ssh-keygen` отсутствует или устарел | Установите OpenSSH 8.0+ или задайте `CMP_REQUIRE_SIGNATURE=0`, только если принимаете риски. | | `cmp login` сообщает, что срок действия кода истек | Прошло 10 минут | Выполните `cmp login` повторно. | | Код возврата 3 | У ключа отсутствуют права (scope), он истек или отозван | `cmp whoami`; создайте или подтвердите заново с расширенными правами. | | Код возврата 6 в скрипте | Платная или деструктивная команда запущена без терминала | Добавьте `--yes` (и собственный `--idempotency-key`). | | "отказывается передавать ключ по http" | URL API использует обычный http | Используйте `https://`, или `CMP_ALLOW_HTTP=1` только для тестовой среды. | | Браузер открывает не тот сайт | Для реселлера не задан `--api-url` | `cmp login --api-url https://`. | --- # Сервер MCP {#mcp-server} > **Где найти в портале:** в разделе API reference › Tools (`https:///apidoc`) представлены эндпоинт и примеры для клиентов; ключи создаются в API keys (`/api-keys`). В панели администратора настроек нет: эндпоинт встроен в панель. ## Назначение {#what-it-does} **Model Context Protocol (MCP)** позволяет AI-ассистенту вызывать инструменты. NexCMP предоставляет эндпоинт MCP по адресу `https:///mcp`. Каждая публичная операция API становится **инструментом** (`vm_list`, `vm_start`, `billing_wallet`, ...), поэтому клиент может спросить ассистента: «какие из моих VM запущены?» или «останови staging VM». Ассистент действует исключительно с собственным API-ключом и правами клиента. ::: tip Настройка самого NexCMP с помощью AI? На этой странице описан **клиентский** эндпоинт MCP (`/mcp`). Чтобы разрешить AI-ассистенту настраивать панель от имени администратора, см. [Configure with AI](https://nexcmp.com/ru/docs/configure-with-ai/mcp-admin/) (эндпоинт `/mcp/admin`, ключи администратора `ak_`). ::: ## Требования {#requirements} | Параметр | Требование | |---|---| | Сервер | Устанавливать ничего не нужно: эндпоинт обслуживается панелью и доступен везде, где доступна сама панель. Ваш обратный прокси должен перенаправлять `/mcp` на панель. | | Клиент | [API-ключ](https://nexcmp.com/ru/docs/developers/api-keys/) (`vk_...`) с областями видимости (scopes), необходимыми ассистенту. | | Клиент | Клиент MCP с поддержкой транспорта **Streamable HTTP** и пользовательского заголовка `Authorization`: Claude Code, Claude Desktop (через мост `mcp-remote`), Cursor, VS Code с режимом Copilot agent mode и аналогичные. | | Версии протокола | 2025-11-25, 2025-06-18 и 2025-03-26. | ## Подготовка инфраструктуры {#prepare-the-infrastructure} Ничего, кроме проверки того, что `https:///mcp` не заблокирован межсетевым экраном или правилом прокси. Браузерный клиент MCP из другого источника (origin) отклоняется, если этот origin не разрешен; клиенты командной строки и десктопные клиенты не отправляют заголовок `Origin` и работают как есть. ## Подключение (со стороны клиента) {#connect-customer-side} 1. Создайте API-ключ в портале (**API keys › Create key**) только с теми областями видимости (scopes), которые требуются ассистенту, коротким сроком действия и, по возможности, ограничением по IP. 2. Добавьте сервер в свой клиент. Замените `cloud.example.com` и ключ. **Claude Code** ```bash claude mcp add --transport http cloud https://cloud.example.com/mcp \ --header "Authorization: Bearer vk_XXXX" ``` **Cursor** (`~/.cursor/mcp.json` или `.cursor/mcp.json`; задайте `CLOUD_API_KEY` в окружении, из которого запускается Cursor): ```json { "mcpServers": { "cloud": { "url": "https://cloud.example.com/mcp", "headers": { "Authorization": "Bearer ${env:CLOUD_API_KEY}" } } } } ``` **Claude Desktop** (требуется Node.js 18+; `claude_desktop_config.json`), через мост `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" } } } } ``` Укажите заголовок без пробела после двоеточия и поместите значение целиком в переменную окружения, как показано выше. 3. Перезапустите клиент и попросите его вывести список доступных инструментов. Проверка подключения без клиента: ```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"}' ``` ## Принцип работы {#how-it-works} | Параметр | Описание | |---|---| | Endpoint | `POST /mcp` с сообщением JSON-RPC 2.0; ответ — `application/json`. `GET /mcp` возвращает 405 (нет потока от сервера к клиенту); `DELETE /mcp` завершает сессию. | | Аутентификация | Только `Authorization: Bearer vk_...` (токены сессий, cookies и ключи администратора отклоняются с кодом 401 и заголовком `WWW-Authenticate: Bearer`). | | Сессия | `Mcp-Session-Id` выдается `initialize`, привязан к этому ключу, действует 24 часа; не более 16 сессий на ключ. | | Инструменты | Один на каждую публичную операцию API, доступную ключу. Имя инструмента — это команда CLI с `_` вместо пробелов и дефисов (`vm firewall add` превращается в `vm_firewall_add`) и совпадает с OpenAPI `operationId`. Инструмент отображается в списке только при наличии соответствующего scope у ключа и включенном модуле. | | Возможности | Только инструменты (без resources и prompts). | | Размер | Тело запроса до 1 МБ; текст результата инструмента примерно до 100 КБ (остальное усекается с примечанием); вызов длится не более 55 секунд. | ### Правила безопасности {#safety-rules} - **Тот же шлюз, что и для REST.** Каждый `tools/call` проходит через стандартный конвейер обработки запросов панели: применяются ограничения по scope, сайту, IP, rate limit, идемпотентность, проверка владения (404 для чужих ресурсов) и квоты. MCP не может предоставить права, которых нет у ключа. - **Подтверждение.** Инструменты, которые списывают средства, удаляют ресурсы или возвращают учетные данные (тикеты консоли, kubeconfig, секреты S3 или SSH, сброс паролей, новые ключи), требуют аргумент `confirm: true`. В описании инструмента ассистенту предписано передавать его только после одобрения пользователем, поэтому скрытая инструкция на веб-странице или в логе не сможет выполнить действие самостоятельно. - **Идемпотентность.** Платные инструменты принимают `idempotency_key`; если параметр не указан, постоянный ключ формируется на основе имени инструмента и его аргументов, поэтому повторный запрос с теми же данными не приведет к повторному списанию. - **Не предоставляются в виде инструментов:** потоковые эндпоинты (чат AI Agent), одноразовые WebSocket-тикеты для SSH или консоли, скачивание бинарных файлов и эндпоинты приложения VPN (`/v1/ext/*`). - **Исключено полностью:** API ни при каких условиях не позволяет пополнять баланс, изменять пароли, удалять аккаунт или создавать ключи, поэтому никакой ассистент не сможет выполнить эти действия. ### Лимиты {#limits} | Лимит | По умолчанию | |---|---| | Вызовов инструментов на ключ | 60 в минуту | | Запросов MCP на ключ | 240 в минуту | | Плюс стандартные лимиты ключа и аккаунта | См. [REST API](https://nexcmp.com/ru/docs/developers/api/#rate-limits) | При превышении лимита эндпоинт возвращает HTTP 429 с ошибкой JSON-RPC и `Retry-After`. ## Проверка {#verify} 1. Приведенная выше команда `curl` возвращает результат JSON-RPC со списком `tools`. Отображаются только инструменты, соответствующие scopes ключа. 2. В своем клиенте запросите «list my VMs»: ассистент вызовет `vm_list` и покажет результат. 3. В портале обновляется время **Last used** ключа, а вызовы на запись появляются в **Key usage log**. ## Ограничения и примечания {#limits-notes} - **Вход через браузер (OAuth).** На справочной странице также описан вход через браузер для клиентов с поддержкой MCP OAuth. В установленном экземпляре NexCMP поддерживаемым и протестированным методом является API-ключ (или `cmp login` для CLI). - **Сайты реселлеров** не отображают раздел MCP; их клиенты используют домен реселлера для работы с API. - **Принцип наименьших привилегий.** Создавайте для каждого ассистента отдельный ключ, сначала только с правами на чтение; добавляйте права на запись только при необходимости. - Отозовите ключ в **API keys**, чтобы мгновенно закрыть ассистенту доступ. ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | 401 с `WWW-Authenticate: Bearer` | Ключ отсутствует, указан неверно или передан токен сессии | Передайте `Authorization: Bearer vk_...`. | | 403 с ошибкой `Origin` | Страница браузера с другого origin | Используйте десктопный клиент или CLI либо попросите администратора разрешить origin (`mcp_allowed_origins`). | | 404 при запросе с `Mcp-Session-Id` | Сессия принадлежит другому ключу или истекла | Выполните `initialize` повторно. | | 405 при `GET /mcp` | Ожидаемое поведение: на сервере нет потока событий | Используйте только POST (клиенты делают это автоматически). | | Список инструментов неполный | Scopes ключа или отключенные модули | Добавьте scopes к ключу; включите модуль. | | Инструмент сообщает, что требуется `confirm: true` | Платный инструмент, операция удаления или конфиденциальные данные | Ассистент должен передать `confirm` после вашего подтверждения. | | 429 | Rate limit для MCP или ключа | Подождите `Retry-After`. | | Клиент не может подключиться с заголовком | Клиент без поддержки пользовательских заголовков | Используйте мост `mcp-remote`. | --- # Настройка с помощью ИИ {#configure-with-ai} > **Где найти в панели:** AI Chat (`/agent`) и System › Settings › API & AI agents (`/agent/keys`). Все функции на этих страницах доступны только администраторам. ## Назначение {#what-it-does} Начиная с NexCMP 1.4.0 вы можете поручить настройку панели ИИ-ассистенту: подключить Proxmox VE или CloudStack, создать зону, сформировать тарифную сетку на основе затрат, настроить почту, платежи и брендинг, найти клиента или экспортировать всю конфигурацию. Ассистент работает через фиксированный набор **admin tools**. Он не получает доступ к shell, не читает файлы на сервере и не видит сохраненные пароли или ключи API. Используйте эту возможность для быстрой первоначальной настройки за считаные минуты вместо обхода десятков страниц, а также если вы управляете несколькими инсталляциями и хотите хранить их конфигурацию в файле. ## Три способа использования {#three-ways-to-use-it} | Способ | Кто обращается к ИИ | Где выполняется | С чего начать | |---|---|---|---| | **AI Chat в панели** | Вы, в панели управления NexCMP | Выбранный вами источник ИИ: API-ключ от OpenAI, Anthropic, Gemini или OpenRouter, встроенный AI-провайдер панели или официальный AI CLI, в котором вы авторизовались | [AI Chat в панели](https://nexcmp.com/ru/docs/configure-with-ai/ai-chat-in-admin/) | | **Собственный AI-клиент через MCP** | Вы, в Claude Code, Codex CLI, Gemini CLI, Cursor, Claude Desktop, claude.ai или ChatGPT | На вашем компьютере или в приложении разработчика с подключением к вашей панели по адресу `https://cloud.example.com/mcp/admin` | [Подключение AI-клиента](https://nexcmp.com/ru/docs/configure-with-ai/mcp-admin/) | | **Конфигурация как код** | Вы или скрипт | YAML-файл и команда `nexcmp config` на сервере (или страница Import/Export) | [Конфигурация как код](https://nexcmp.com/ru/docs/configure-with-ai/config-as-code/) | Все три способа используют одни и те же инструменты и единый уровень безопасности, поэтому их можно комбинировать: подготовить черновик конфигурации с ассистентом, экспортировать в YAML, проверить в редакторе и применить позже. ## Модель безопасности {#safety-model} | Правило | Что это значит для вас | |---|---| | **Области доступа** | Ключ или подключение ограничены областями доступа, которые вы отметили (`admin:read`, `catalog:write`, `infra:write`, `billing:write`, `customers:write`, `settings:write`, `ai:write`, `secrets:write`). Без необходимой области запрос отклоняется. См. [Admin API keys](https://nexcmp.com/ru/docs/configure-with-ai/admin-api-keys/#scopes). | | **Expiry** | У каждого ключа и подключения есть срок действия: от 1 до 90 дней для создаваемых вами ключей (по умолчанию 30 дней). Срок действия токенов доступа OAuth составляет один час. | | **Ограничение по IP и лимит запросов** | Действие ключа можно ограничить диапазонами IP-адресов и количеством запросов в минуту (по умолчанию 120). | | **Двухэтапное подтверждение** | Действия, связанные с переводом средств, удалением данных, изменением платежных реквизитов или настроек безопасности входа, сначала возвращают предварительный просмотр и не выполняются без вашего подтверждения. В AI Chat каждое изменение оформлено в виде карточки подтверждения, которую вы нажимаете сами. | | **Действия, недоступные для ключей** | Создание администраторов, изменение 2FA, создание или отзыв ключей, вход под учетной записью клиента, резервное копирование, восстановление или обновление панели и другие подобные операции. Для них требуется ваше личное присутствие в панели управления. | | **Журнал активности** | Каждый запрос, разрешенный или отклоненный, фиксируется с указанием ключа, клиента, инструмента, IP-адреса и результата. См. System › Settings › API & AI agents › Activity. | | **Секретные данные никогда не возвращаются** | Пароли, ключи API и токены можно задать, но невозможно прочитать. В ответах, доступных ИИ, они скрыты маской. | | **Демо-установки доступны только для чтения** | В демо-панели любая запись отклоняется с ошибкой `demo_read_only`. | ::: important Что может читать ИИ С `admin:read` ассистент может читать имена клиентов, адреса электронной почты, балансы и биллинговые записи. Если вы используете AI-источник от внешнего поставщика (OpenAI, Anthropic, Google, OpenRouter), эти данные отправляются ему для формирования ответа. Предоставляйте ассистенту минимально необходимый набор разрешений (scopes) и выбирайте источник, которому вы доверяете. ::: ## Быстрый старт {#quick-start} 1. Войдите в панель администратора и откройте **AI Chat**. Если AI-источник еще не подключен, перейдите в **System › Settings › AI accounts** и подключите его (см. [AI accounts and subscriptions](https://nexcmp.com/ru/docs/configure-with-ai/ai-accounts-and-subscriptions/)). 2. Введите «Check my setup progress» и нажмите Enter. Ассистент прочитает [Setup progress checklist](https://nexcmp.com/ru/docs/configure-with-ai/setup-checklist/) и сообщит, что осталось сделать. 3. Попросите его выполнить следующий шаг. Проверьте каждую карточку подтверждения и нажмите **Confirm** для применения. Примеры запросов приведены в разделе [Example prompts](https://nexcmp.com/ru/docs/configure-with-ai/example-prompts/). ![Страница AI Chat с диалогом, результатом работы инструмента и карточкой подтверждения](https://nexcmp.com/ru/docs/images/configure-with-ai/overview-01-ai-chat.webp) ## Ограничения и примечания {#limits-notes} - **Демо-режим только для чтения.** В демо-панели страницы доступны для просмотра, но сохранить изменения нельзя. - **Нет доступа к shell.** Ассистент может вызывать только инструменты администратора, перечисленные в [Connect an AI client](https://nexcmp.com/ru/docs/configure-with-ai/mcp-admin/#tools). Он не может выполнять команды на сервере. - **Сетевые модули и маршрутизация** (BGP, XDP, интерфейсы, NAT и подобные) доступны для ИИ только в режиме чтения, а критически важные разделы, такие как учетные записи администраторов, резервные копии и обновления, полностью закрыты для ключей. - **Цены** указаны в USD: стоимость тарифов — в долларах за час, балансы — в центах. - **Стоимость.** Ответы ИИ оплачиваются подключенному AI-источнику (использование API или ваша собственная подписка). В AI Chat можно задать ежедневный лимит расходов. Модель лицензирования NexCMP описана в https://nexcmp.com/pricing. ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | AI Chat сообщает, что AI-источник не подключен | Для вашей учетной записи администратора не настроен источник | Откройте System › Settings › AI accounts и подключите его. | | Ассистент возвращает `insufficient_scope` | У ключа или подключения нет необходимых прав (scope) для этого инструмента | Создайте ключ с нужным разрешением (scope) либо переподключитесь и отметьте его на экране согласия. См. [Admin API keys](https://nexcmp.com/ru/docs/configure-with-ai/admin-api-keys/#errors). | | При каждом изменении отображается карточка подтверждения | Штатное поведение в AI Chat | Нажмите **Confirm** для применения или **Reject** для отмены. | | Операции записи завершаются с ошибкой `demo_read_only` | Панель работает в демо-режиме | Используйте не демонстрационную установку. | --- # AI Chat в панели администратора {#ai-chat-in-the-admin} > **Где найти в панели:** AI Chat (`/agent`, отдельный пункт меню) и плавающая кнопка **Ask AI** на каждой странице панели. Источники ответов настраиваются в System › Settings › AI accounts (`/agent/accounts`). ## Назначение {#what-it-does} AI Chat — это встроенный в панель администратора ассистент. Вы описываете задачу («подключить кластер Proxmox», «настроить почту»), ассистент считывает текущее состояние с помощью инструментов администратора, предлагает изменения и отображает каждое из них в виде **карточки подтверждения**. Никакие изменения не применяются, пока вы не нажмете **Confirm**. Панель **Ask AI** — это тот же чат в виде узкой боковой панели, что позволяет задавать вопросы, не уходя со страницы. Такие кнопки, как **Do it for me** (в [Setup progress checklist](https://nexcmp.com/ru/docs/configure-with-ai/setup-checklist/) и в пустых списках), открывают его с готовым вопросом. Это не клиентские [AI Chat](https://nexcmp.com/ru/docs/ai/ai-chat/) и [AI Agent](https://nexcmp.com/ru/docs/ai/ai-agent/), которые обслуживают ваших клиентов. ## Требования {#requirements} | Параметр | Требование | |---|---| | Роль | Авторизованный администратор. Чаты, ключи и настройки привязаны к вашей учетной записи администратора; другие администраторы их не видят. | | Источник ответов | Подключен хотя бы один: API-ключ, учетная запись, собственный AI-провайдер панели или авторизованный AI CLI. См. [Учетные записи и подписки AI](https://nexcmp.com/ru/docs/configure-with-ai/ai-accounts-and-subscriptions/). | | Демо | В демо-панели можно просматривать старые чаты, но нельзя отправлять сообщения. | ## Выбор источника ответов {#choose-where-answers-come-from} Выберите источник в селекторе под полем ввода (в нем перечислены все подключенные источники). В **System › Settings › AI accounts** также можно задать источник по умолчанию, модель по умолчанию и дневной лимит. | Source | Способ подключения | Примечания | |---|---|---| | OpenAI (модели ChatGPT) | Вставить API-ключ из platform.openai.com | Тарифицируется OpenAI по факту использования. | | Anthropic (Claude) | Вставить API-ключ из console.anthropic.com | Тарифицируется Anthropic по факту использования. | | Google Gemini | Вставить API-ключ из aistudio.google.com или **Sign in with Google** | Для входа через Google требуется OAuth-клиент, созданный **вами** в вашем собственном проекте Google Cloud. | | OpenRouter | Вставить ключ или **Sign in with OpenRouter** | Один аккаунт для множества моделей. | | AI-провайдер панели | Уже настроен в System › Settings › AI provider | Тот же провайдер, который используется в клиентском AI Chat. [AI provider](https://nexcmp.com/ru/docs/ai/ai-providers/). | | Подписка Claude, ChatGPT или Gemini | Официальный CLI установлен и авторизован на сервере панели | См. [Учетные записи и подписки AI](https://nexcmp.com/ru/docs/configure-with-ai/ai-accounts-and-subscriptions/). | Добавленные ключи хранятся в зашифрованном виде и доступны только вашей учетной записи администратора. Они больше никогда не отображаются, и другой администратор не сможет их расшифровать. ## Использование чата {#use-the-chat} 1. Откройте **AI Chat** (или нажмите **Ask AI**). 2. Нажмите **New chat** или откройте предыдущий диалог из списка слева. 3. Введите запрос и нажмите Enter (Shift+Enter — переход на новую строку). Можно прикрепить изображения или текстовые файлы (до 4 на сообщение, до 3 MB каждый), чтобы показать ошибку или приложить документ. 4. Ответ генерируется в режиме реального времени. Каждый инструмент, вызываемый ассистентом, отображается в виде сворачиваемой карточки с названием инструмента, его аргументами и кратким результатом. 5. Нажмите **Stop**, чтобы прервать генерацию ответа. Каждый администратор может одновременно генерировать только один ответ. ![AI Chat со списком чатов, ответом с карточками инструментов и полем ввода с селектором источника и полем Secret](https://nexcmp.com/ru/docs/images/configure-with-ai/ai-chat-in-admin-01-chat.webp) Для одного сообщения выполняется до 10 итераций вызова инструментов. Ассистент помнит последние 30 сообщений чата. Результаты работы инструментов передаются в модель с пометкой данных, а не инструкций. ## Карточки подтверждения {#confirmation-cards} В AI Chat **каждое изменение оформляется как карточка**, а не только финансовые операции. Ассистент предлагает — вы решаете. В карточке отображаются: - Заголовок с объяснением, почему требуется внимание, например «changes a customer balance». - Вызов: метод и путь. - Таблица изменяемых полей: текущее значение и новое. Секретные значения отображаются как `••••`. - Обратный отсчет (карточки действуют в течение 5 минут). - **Confirm** и **Reject**. **Confirm** применяет изменение силами самой панели, после чего сообщает ассистенту о результате. Ассистент не может нажать эту кнопку, не может подтвердить действие через API, и проинструктирован никогда не заявлять о применении изменения до его подтверждения. При перезагрузке страницы карточки, срок действия которых еще не истек, сохраняются. Они также отображаются в верхней части **System › Settings › API & AI agents** в разделе «Waiting for your confirmation». ![Карточка подтверждения с изменением баланса, обратным отсчетом и кнопками Confirm и Reject](https://nexcmp.com/ru/docs/images/configure-with-ai/ai-chat-in-admin-02-confirm.webp) ## Секреты {#secrets} Пароли и ключи API нельзя передавать через текст чата. Используйте поле **Secret** (значок замка) рядом со строкой ввода: 1. Нажмите на значок замка и укажите **имя** (буквы, цифры и символ подчеркивания, например `smtp_password`) и **значение**. 2. В сообщении сошлитесь на это имя: «use the secret smtp_password as the SMTP password». 3. Ассистент видит только заполнитель, обозначающий секрет, в следующем виде: ```text {{secret:smtp_password}} ``` Панель подставляет настоящее значение в момент вызова инструмента. Значение не сохраняется в истории чата и не передается в источник AI. Если вы случайно вставите в сообщение нечто похожее на ключ, панель переместит его в то же защищенное хранилище и замаскирует в истории, однако относитесь к этому как к подстраховке, а не к рабочему методу. Секреты хранятся только в памяти панели, исключительно в рамках диалога, где они были введены, и не более одного часа после последнего сообщения; перезапуск панели также удаляет их. Введите их заново, если ассистент запросит это повторно. Для передачи секрета также требуется право `secrets:write` для сессии чата (см. ниже). ## Права доступа чата {#permissions-of-the-chat} Каждое сообщение выполняется с временным ключом, который существует в течение формирования ответа (не более 15 минут), действует только с сервера панели и может использоваться исключительно через карточки подтверждения. Его области действия соответствуют тем, что отмечены в **System › Settings › AI accounts › Chat session permissions**. Право `admin:read` включено всегда. Все области действия, кроме `secrets:write`, включены по умолчанию; отметьте `secrets:write`, если хотите, чтобы ассистент мог задавать пароли и ключи (через поле Secret). На демонстрационной панели чат доступен только для чтения. ## Дневной лимит расходов {#daily-spending-cap} AI Chat суммирует ориентировочную стоимость ответов от источников API. Лимит по умолчанию составляет **5 USD на администратора в день**. Укажите другую сумму (0 означает отсутствие лимита) в разделе **AI accounts › Defaults for AI Chat**. На странице отображается «used today». При достижении лимита чат отклоняет новые сообщения (`daily_cap`) до следующего дня или до увеличения лимита. Источники, работающие по подписке AI CLI, не учитываются, так как они оплачиваются в рамках вашей подписки. ## Проверка {#verify} 1. В разделе **AI accounts** нажмите **Test** напротив источника. В ответе отобразится название модели и время в миллисекундах. 2. В AI Chat спросите «Check my setup progress». В ответе будут перечислены шаги из [контрольного списка](https://nexcmp.com/ru/docs/configure-with-ai/setup-checklist/) и появится карточка инструмента `setup_checklist`. 3. Запросите небольшое изменение, например «Set the brand name to Example Cloud». Появится карточка подтверждения; нажмите **Confirm** и проверьте страницу Branding. 4. В **API & AI agents › Activity** отображаются вызовы с каналом `chat`. ## Ограничения и примечания {#limits-notes} - У ассистента нет командной оболочки, и он не может читать файлы на сервере. Он вызывает только [инструменты администрирования](https://nexcmp.com/ru/docs/configure-with-ai/mcp-admin/#tools). - Изменения, которые невозможно выполнить с помощью ключей ([список](https://nexcmp.com/ru/docs/configure-with-ai/admin-api-keys/#what-a-key-can-never-do)), нельзя внести и через AI Chat. - Проверяйте действия модели. В карточке подтверждения точно показано, что именно будет отправлено; внимательно ознакомьтесь с ней, особенно с ценами и суммами. - Ответы по API тарифицируются поставщиком AI. Лимит является ориентировочным; настройте ограничение расходов также и на стороне поставщика. - Формирование ответа через CLI прекращается через 5 минут. ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | «Достигнут дневной лимит расходов на AI» (`daily_cap`) | Исчерпан дневной лимит | Увеличьте его в AI accounts или подождите до завтра. | | "Еще выполняется другой ответ — подождите или нажмите Stop" (`busy`) | Один ответ за раз для каждого администратора | Нажмите **Stop** или подождите. | | Источник не отображается в списке выбора | Он не подключен или (для Claude CLI) выключен переключатель «I understand» | Подключите его в AI accounts. | | "это не похоже на ключ API" | Вставленный ключ содержит пробелы или слишком длинный | Вставьте только ключ. | | Тест завершается ошибкой | Неверный ключ, нет средств на балансе или провайдер недоступен | Проверьте ключ и биллинг на стороне вендора. | | Ассистент сообщает, что не может выполнить действие | В сессии чата не выбран scope либо действие недоступно для AI | Отметьте нужный scope в AI accounts или выполните действие в панели администратора. | | В карточке указано, что срок действия истек | Прошло более 5 минут | Попросите ассистента предложить изменение снова. | | CLI-источник сообщает «usage limit» или «not logged in» | Лимит подписки или истекшая сессия | Войдите снова или подождите; см. [Аккаунты AI и подписки](https://nexcmp.com/ru/docs/configure-with-ai/ai-accounts-and-subscriptions/). | --- # Аккаунты AI и подписки {#ai-accounts-and-subscriptions} > **Где в панели:** System › Settings › AI accounts (`/agent/accounts`), вкладки **Accounts** и **Use your own AI subscription**. Дополнительный терминал — AI Console (`/agent/console`), который отображается под AI Chat, только когда он включен. ## Назначение {#what-it-does} Для работы AI Chat необходим источник ответов. На этой странице вы можете подключить его для своей учетной записи администратора: - **API-источники**: OpenAI, Anthropic (Claude), Google Gemini и OpenRouter с помощью API-ключа или входа в аккаунт. - **AI-провайдер панели**, если он уже настроен в System › Settings › AI provider. - **Собственная AI-подписка** (Claude, ChatGPT, Gemini) через **официальную утилиту командной строки** вендора — на сервере панели или на вашем компьютере. Все подключенные данные привязаны к вашей учетной записи администратора. Ключи и токены хранятся в зашифрованном виде только для вас; другие администраторы не смогут их использовать. ## Требования {#requirements} | Параметр | Требование | |---|---| | Роль | Авторизованный администратор. В демо-панели ничего нельзя подключить или удалить. | | API-источники | Аккаунт и API-ключ у вендора (в карточке есть ссылка **Get API key**, открывающая страницу вендора). | | CLI на сервере панели | Включенная AI Console (см. ниже), исходящий HTTPS с сервера к вендору, к `nodejs.org` и реестру npm, а также **от 2 GB RAM** (во время работы CLI требуется около 1 GB свободной памяти; установщик предупредит, если доступно менее 2 GB). Используется Node.js 20 или новее при наличии, иначе установщик скачивает Node.js 22 с проверкой контрольной суммы. | | CLI на вашем компьютере | Node.js 20 или новее для установки CLI и собственная подписка. | ## Подключение API-источника {#connect-an-api-source} 1. Перейдите в **System › Settings › AI accounts** и оставайтесь на вкладке **Accounts**. 2. На карточке источника нажмите **Connect**. На новой вкладке откроется страница ключей провайдера; создайте там ключ. 3. Вставьте ключ в поле и сохраните. На карточке отобразится статус подключения с четырьмя последними символами ключа. 4. Выберите **default model**, если хотите использовать другую модель, затем нажмите **Test**. При успешном тесте отображается сообщение вида «Connected - example-model, 850 ms». ![Страница аккаунтов AI с карточками источников API, подключенной карточкой OpenAI и карточкой провайдера AI для панели](https://nexcmp.com/ru/docs/images/configure-with-ai/ai-accounts-and-subscriptions-01-accounts.webp) | Source | Альтернативный способ входа | |---|---| | OpenRouter | **Sign in with OpenRouter** открывает OpenRouter во всплывающем окне или новой вкладке; подтвердите доступ, и вы вернетесь на эту страницу с активным подключением. | | Google Gemini | **Sign in with Google** появляется после сохранения в блоке **Set up Google sign-in (optional)** на карточке клиента OAuth, созданного в **вашем собственном** проекте Google Cloud (идентификатор клиента, заканчивающийся на `.apps.googleusercontent.com`, и его секрет). В комплекте с NexCMP общий Google-клиент не поставляется. | | AI-провайдер панели | Использует провайдера, уже настроенного в System › Settings › AI provider ([AI provider](https://nexcmp.com/ru/docs/ai/ai-providers/)). Вставлять ничего не требуется. | Чтобы отключить источник, нажмите **Remove** на его карточке. Это удалит сохраненный ключ для вашего аккаунта. ### Значения по умолчанию, дневной лимит и права доступа {#defaults-daily-cap-and-permissions} В нижней части вкладки **Accounts** в блоке **Defaults for AI Chat** доступны три параметра: | Настройка | Значение | |---|---| | Источник и модель по умолчанию | Используется для новых чатов. Вы по-прежнему можете менять источник для каждого сообщения отдельно. | | Дневной лимит расходов (USD, 0 = без ограничений) | По умолчанию: 5. На странице отображается «used today». См. раздел [AI Chat in the admin](https://nexcmp.com/ru/docs/configure-with-ai/ai-chat-in-admin/#daily-spending-cap). | | Chat session permissions | Области доступа (scopes), доступные ассистенту. `admin:read` включен всегда; `secrets:write` отключен по умолчанию. См. раздел [Admin API keys](https://nexcmp.com/ru/docs/configure-with-ai/admin-api-keys/#scopes). | Нажмите **Save defaults**. ## Использование собственной подписки на AI {#use-your-own-ai-subscription} Вы можете управлять NexCMP с помощью уже оплаченного тарифа Claude, ChatGPT или Gemini без отдельного API-ключа. Существует два способа. ### Способ 1 (рекомендуемый): CLI на вашем компьютере {#way-1-recommended-the-cli-on-your-own-computer} Вы используете официальную утилиту разработчика на собственном компьютере и входите в свой аккаунт стандартным способом провайдера. NexCMP принимает только MCP-вызовы, подписанные краткосрочным ключом. Откройте **AI accounts › Use your own AI subscription**; там описаны три шага для каждого инструмента. 1. Нажмите **Create a 7-day key** и выберите уровень доступа: **Read only** (`admin:read`) или **Read + configuration** (`admin:read`, `catalog:write`, `infra:write`, `settings:write`). После этого команды ниже будут содержать фактический ключ. 2. Установите CLI и выполните вход. Ключ отображается только на этой странице и только один раз. | Инструмент | Установка | Вход в систему | |---|---|---| | Claude Code | `npm install -g @anthropic-ai/claude-code` | выполните `claude`, затем `/login` | | Codex CLI | `npm install -g @openai/codex` | `codex login` | | Gemini CLI | `npm install -g @google/gemini-cli` | выполните `gemini`, выберите «Login with Google» | 3. Подключите инструмент к панели с помощью одной команды или блока настроек, скопированного со страницы: ```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. Запустите утилиту и задайте вопрос, например: «what is left to set up in nexcmp?». Все подробности подключения по протоколу MCP описаны в разделе [Connect an AI client](https://nexcmp.com/ru/docs/configure-with-ai/mcp-admin/). На этой же вкладке указан URL для коннекторов **claude.ai** и **ChatGPT**, которые авторизуются через OAuth и не требуют ключа: [OAuth connectors](https://nexcmp.com/ru/docs/configure-with-ai/oauth-connectors/). ![Вкладка Use your own AI subscription с кнопкой создания 7-дневного ключа и командами установки, входа и подключения для трех CLI](https://nexcmp.com/ru/docs/images/configure-with-ai/ai-accounts-and-subscriptions-02-subscription.webp) ### Способ 2: CLI на сервере панели (кнопки Install / Login) {#way-2-the-cli-on-the-panel-server-install-login-buttons} Карточки в разделе «Subscription through a CLI (Claude, ChatGPT, Gemini)» позволяют NexCMP установить официальный CLI на сервер панели и запустить его собственный процесс входа, чтобы **AI Chat** мог отвечать в рамках вашей подписки. **Как обеспечивается изоляция.** CLI запускаются в отдельном процессе (`nexcmp-ai.service`) от имени собственного системного пользователя `nexcmp-ai`, без прав sudo, без доступа к каталогам данных и конфигурации NexCMP и с ограничением по памяти. Для каждого сообщения AI Chat CLI запускается с разрешением только на MCP-инструменты NexCMP (инструменты командной строки и работы с файлами отключены) и с ключом, действующим только с сервера. NexCMP не считывает и не копирует данные авторизации CLI: CLI сохраняет их в закрытом каталоге вашей учетной записи администратора. Ничего включать вручную не требуется: панель настраивает пользователя и службу `nexcmp-ai` при установке или обновлении до 1.4.0, поэтому карточки сразу готовы к работе. **Установка и вход (для каждого администратора):** 1. В карточке CLI нажмите **Login**. Если CLI еще не установлен, панель сначала выполнит установку: индикатор выполнения и краткий журнал покажут процесс загрузки (Node.js при необходимости, затем CLI). Если на сервере менее 2 ГБ оперативной памяти, появится предупреждение. 2. В карточке отобразятся запрашиваемые CLI данные: - **Codex CLI**: нажмите **Open the sign-in page** и введите одноразовый код, отображаемый на карточке. (В настройках безопасности вашего ChatGPT должен быть включен вход с устройств OpenAI). - **Claude Code и Gemini CLI**: нажмите **Open the sign-in page**, выполните вход, затем вставьте код подтверждения со страницы поставщика в поле **Paste the verification code here** и нажмите **Send code**. 3. Статус карточки изменится на «Signed in» с указанием аккаунта и версии. Если вход не завершен в течение 10 минут, он отменяется; нажмите **Login** еще раз. 4. В **AI Chat** источник теперь появится в списке выбора (например, «ChatGPT (via Codex CLI)»). 5. **Sign out** удаляет данные авторизации CLI для вашей учетной записи. Для Claude на карточке предусмотрен дополнительный переключатель — **I understand and accept the vendor's terms for using a subscription this way**, по умолчанию отключенный. Источник не будет доступен в AI Chat, пока переключатель не активирован. ![Карточки подписок CLI с кнопками Install и Login, одноразовым кодом на карточке Codex и переключателем I understand на карточке Claude](https://nexcmp.com/ru/docs/images/configure-with-ai/ai-accounts-and-subscriptions-03-cli.webp) ### Условия поставщиков AI {#terms-of-the-ai-vendors} Авторизация с использованием пользовательской подписки регулируется условиями соответствующего поставщика, которые могут меняться. Приведенные ниже примечания представляют собой сводку материалов, опубликованных поставщиками по состоянию на октябрь 2026 года, не являются юридической консультацией и не выражают позицию поставщиков. Ознакомьтесь с актуальными страницами условий перед включением этой функции. | Поставщик | Что указано на странице поставщика | Source | |---|---|---| | Anthropic (Claude) | Авторизация в оригинальном Claude Code с использованием собственного тарифного плана разрешена. Использование подписки через сторонние продукты либо сбор или передача данных авторизации продуктом трактуются иначе, а лимиты тарифов рассчитаны на обычное индивидуальное использование. Поэтому на карточке Claude размещены примечание и переключатель **I understand**, а Способ 1 является более предпочтительным вариантом. | https://code.claude.com/docs/en/legal-and-compliance | | OpenAI (Codex) | Codex поддерживает вход с помощью учетной записи ChatGPT или ключа API. OpenAI рекомендует использовать ключи API для автоматизации и предостерегает от запуска Codex в ненадежных или общедоступных средах. Используйте карточку только для себя. | https://developers.openai.com/codex/auth | | Google (Gemini CLI) | Поддерживаются вход через Google (Sign in with Google), ключ API и Vertex AI; условия зависят от способа входа, и применяются квоты вашего тарифного плана. | https://geminicli.com/docs/get-started/authentication | Если вы хотите полностью избежать этого вопроса, используйте источник **API key** или Способ 1 на своем компьютере. ## AI Console {#ai-console} AI Console — это опциональная страница терминала для запуска одного из подключенных CLI на сервере панели. По умолчанию она **отключена**. - Включить или отключить ее, а также управлять CLI можно на сервере: ```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` выводит информацию о готовности сокета AI runner, статусе AI Console (включена или отключена) и о каждом CLI («installed» или «not installed»). `sudo nexcmp status` также отображает «AI runner: active». - После включения в AI Chat появится вкладка **AI Console**. Выберите подключенный CLI, повторно введите пароль администратора (и код 2FA при наличии) и откройте сессию. Баннер предупредит, что команды здесь могут управлять NexCMP только через его инструменты MCP; инструменты shell и работы с файлами отключены. - В демо-установках пользователь `nexcmp-ai` никогда не создается. ![Начальный экран AI Console с выбором CLI, полем ввода пароля и предупреждающим баннером об использовании только MCP](https://nexcmp.com/ru/docs/images/configure-with-ai/ai-accounts-and-subscriptions-04-console.webp) ## Проверка {#verify} 1. **Test** для источника API возвращает имя модели. 2. На карточке CLI отображается статус «Signed in» с указанием аккаунта. 3. На сервере: `sudo nexcmp ai-console status` указывает, что CLI установлен, а `systemctl is-active nexcmp-ai` выводит `active`. 4. В AI Chat выберите источник, отправьте запрос «Check my setup progress», и появится карточка инструмента. ## Ограничения и примечания {#limits-notes} - Время ответа CLI ограничено 5 минутами, одновременно может выполняться не более одного ответа на администратора. Дневной лимит не учитывает ответы CLI. - Каждое изменение от источника CLI по-прежнему требует подтверждения через карточку в AI Chat; CLI не может вносить изменения самостоятельно. - В тарифных планах действуют собственные лимиты использования. Если провайдер возвращает «usage limit» или «not logged in», чат отобразит это сообщение. - Удаление источника не приводит к удалению переписок. - Своевременно обновляйте сервер: CLI устанавливаются из публичных пакетов вендоров в момент нажатия Install. ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | Вход отключен, и на карточке отображается «AI tools are not ready on the server yet» | Служба `nexcmp-ai` не запущена | Обновите панель до последней версии, затем проверьте `sudo nexcmp status`. В демо-режиме, доступном только для чтения, это нормальное поведение. | | «Инструменты ИИ еще не установлены на этом сервере» | Служба `nexcmp-ai` не запущена (устаревшая версия или демо-панель) | Обновите панель, затем выполните `sudo nexcmp ai-console install claude` (или `codex`, `gemini`). | | Предупреждение о том, что объем RAM менее 2 GB | Недостаточно ресурсов сервера | Установка может замедлиться или завершиться сбоем; увеличьте объем памяти или используйте Способ 1. | | «Node.js download checksum mismatch» или «download failed» | Сервер не может связаться с nodejs.org, либо прокси-сервер изменил загружаемый файл | Разрешите исходящий трафик по HTTPS и повторите попытку. | | Установка завершается ошибкой | npm не удалось установить пакет | Ознакомьтесь с журналом на карточке, проверьте исходящий доступ к реестру npm и повторите попытку. | | Вход завершается ошибкой или по таймауту | Истек 10-минутный интервал или был указан неверный код | Нажмите **Login** еще раз и выполните вход быстрее. | | Источник Claude отсутствует в AI Chat | Переключатель **I understand** выключен или не выполнен вход в CLI | Включите переключатель после ознакомления со страницей вендора, затем выполните вход. | | Кнопка «Sign in with Google» отсутствует для Gemini | Клиент Google OAuth еще не сохранен | Создайте клиент в собственном проекте Google Cloud и сохраните его в блоке **Set up Google sign-in (optional)** на карточке либо укажите API-ключ. | | «Sign in with OpenRouter» возвращает ошибку | Вы отменили действие или всплывающее окно было заблокировано | Разрешите всплывающие окна и повторите попытку. | | В ответе CLI указано «usage limit» | Квота тарифа исчерпана | Подождите или переключите источник. | --- # Ключи API администратора {#admin-api-keys} > **В панели администратора:** System › Settings › API & AI agents (`/agent/keys`), вкладка **API keys**. На этой же странице доступны вкладки **Connect an AI**, **Connected apps** и **Activity**. ## Назначение {#what-it-does} Ключ API администратора (префикс `ak_`) позволяет AI-клиенту или скрипту управлять вашей панелью строго в рамках выданных прав. Он работает в API администратора по адресу `/v1/admin/` и на эндпоинте MCP администратора `/mcp/admin`. В других местах он не действует. ::: info Отличие от ключей клиентов Клиенты создают ключи, начинающиеся с `vk_`, в панели клиента ([Ключи API и области доступа](https://nexcmp.com/ru/docs/developers/api-keys/)). Они имеют доступ только к API клиента и `/mcp`. Ключ `ak_` отклоняется в API клиента, а ключ `vk_` — в API администратора. ::: ## Требования {#requirements} | Параметр | Требование | |---|---| | Роль | Вы должны войти в панель администратора. Ключи не могут создавать другие ключи. | | Демо | В демо-панели страница доступна только для чтения: ключи нельзя создавать или отзывать. | | Сетевая доступность | Клиент должен иметь доступ к `https://cloud.example.com/mcp/admin` или `/v1/admin/...` на вашей панели (проверьте межсетевой экран, если настроены ограничения по IP). | ## Создание ключа {#create-a-key} 1. Перейдите в **System › Settings › API & AI agents** и оставайтесь на вкладке **API keys**. 2. Нажмите **Create new key**. 3. Заполните форму: | Поле | Правила | |---|---| | Name | До 60 символов, например «Claude Code on my laptop». | | Скоупы | Отметьте хотя бы одну. См. [Scopes](#scopes). Начните только с `admin:read`. | | Срок действия | 1, 7, 30, 60 или 90 дней. По умолчанию 30. Максимум 90. Создать ключ без срока действия нельзя. | | Диапазоны IP (необязательно) | По одному адресу IPv4, IPv6 или CIDR на строку, например `203.0.113.0/24` или `2001:db8::/48`. Не более 32. Оставьте пустым, чтобы разрешить любые IP. | | Запросов в минуту | От 1 до 6000. По умолчанию 120. | 4. Нажмите **Create key**. В появившемся окне ключ будет показан один раз, например `ak_XXXX`. **Скопируйте его сейчас**: NexCMP сохраняет только хеш и больше никогда его не покажет. 5. Нажмите **I have saved the key**. Откройте вкладку **Connect an AI**, чтобы получить готовые команды, уже содержащие только что созданный ключ (доступно только на этой странице до ее обновления). ![Окно создания нового ключа с заполненным именем, флажками областей доступа, сроком действия и диапазоном IP](https://nexcmp.com/ru/docs/images/configure-with-ai/admin-api-keys-01-create.webp) ![Окно с однократным отображением нового ключа, кнопкой Copy и предупреждением](https://nexcmp.com/ru/docs/images/configure-with-ai/admin-api-keys-02-shown-once.webp) ## Скоупы {#scopes} Ключ может использовать только те инструменты и эндпоинты, которые разрешены его областями доступа. Права на запись не включают доступ на чтение: ключу, которому требуется чтение и запись, также необходим `admin:read`. | Скоуп | Что разрешает | |---|---| | `admin:read` | Чтение настроек, каталога, клиентов, биллинга и логов. Секретные данные никогда не возвращаются. | | `catalog:write` | Тарифы, шаблоны ОС, квоты, промокоды. | | `infra:write` | Источники инфраструктуры (CloudStack, Proxmox), зоны, серверы. | | `billing:write` | Платежные шлюзы, валюта, счета, балансы. Финансовые операции требуют подтверждения. | | `customers:write` | Клиенты и реселлеры. | | `settings:write` | Общие настройки, брендинг, email, правовые страницы, модули, уведомления. | | `ai:write` | Провайдер AI и функции AI. | | `secrets:write` | Запись паролей и ключей API. Их можно задать, но нельзя прочитать обратно. | ::: tip Для установки секрета требуются две области доступа Любой запрос, передающий пароль, ключ API или токен (пароль SMTP, платежный ключ, токен бота Telegram, ключ провайдера AI, учетные данные CloudStack или Proxmox), требует `secrets:write` **и** область доступа соответствующего раздела (например, `settings:write` для SMTP). Если вы предпочитаете вводить секреты вручную, оставьте `secrets:write` отключенным и укажите их в панели администратора. ::: ## Отозвать ключ {#revoke-a-key} 1. Найдите ключ в таблице (статус **Active**, **Expired** или **Revoked**; в столбце **Last used** указаны время и клиент). 2. Нажмите **Revoke** и подтвердите действие. Ключ перестает действовать мгновенно. Отзыв необратим; если ключ понадобится снова, создайте новый. ## Что никогда не может делать ключ {#what-a-key-can-never-do} Ключ ни при каких условиях не дает доступа к этим разделам, независимо от его областей доступа. Для них требуется войти в панель администратора. - Создание или изменение пользователей-администраторов, 2FA и безопасности входа, сессий администраторов и токенов API администратора. - Создание, просмотр списка или отзыв ключей администратора, подключений OAuth и аккаунтов AI, а также использование AI Console. - Резервное копирование или восстановление панели, ее обновление или изменение лицензии. - Вход от имени клиента или реселлера, открытие консоли клиента, чтение учетных данных виртуальных машин или kubeconfig, установка SSH Keys, а также отправка или сброс паролей. - Изменение модулей сети и маршрутизации (BGP, FRR, RTBH, XDP, интерфейсы, статические маршруты и маршрутизация на основе политик, NAT), внешних агентов и интеграции портала. Они доступны только для чтения. - Изменение таких параметров, как `demo_*`, `admin_*`, списки хостов, passkey, секреты повторной аутентификации и капчи. Все, что не охвачено правилами, по умолчанию закрыто для записи и доступно для чтения с `admin:read`. ### Действия, требующие вашего подтверждения {#actions-that-need-your-confirmation} Они выполняются только после того, как вы одобрите предварительный просмотр (см. [Двухэтапное подтверждение](#two-step-confirmation)): - Изменение баланса клиента или кошелька реселлера, выплата средств, биллинговые записи, курс обмена валют. - Изменение цен (тарифных планов, массовое создание планов, тарификация образов и хранилища) и создание скидочных или денежных кодов. - Сохранение учетных данных платежного шлюза или подключения к CloudStack. - Удаление любых объектов, блокировка или удаление клиента, изменение лимитов клиента, приостановка или закрытие реселлера. - Операции с серверами клиентов или создание платного сервера для клиента. - Изменение глобальных переключателей, настроек безопасности входа или параметров оплаты через общие настройки. ## Двухэтапное подтверждение {#two-step-confirmation} Когда запрос требует подтверждения, изменения сразу не применяются. Возвращается ответ HTTP **428** с `confirm_required`, `confirm_token`, `preview` (метод, путь, причина, новые значения и, если доступны, текущие значения) и `expires_in: 300`. 1. Клиент отображает предварительный просмотр. 2. После вашего одобрения он повторяет тот же **самый** запрос (с теми же методом, путем и телом) с заголовком `X-Confirm-Token: `. Инструменты MCP вместо этого принимают аргумент `confirm_token`. 3. Токен действует один раз и истекает через 5 минут. Ключи, созданные в панели администратора для AI Chat, можно подтвердить только на экране: в ответе возвращается `confirm_in: "ui"`, и в панели администратора появляется карточка подтверждения. AI не может одобрить его. ## Ограничение частоты запросов и правила IP {#rate-limit-and-ip-rules} - При превышении поминутного лимита запрос возвращает `rate_limited` (HTTP 429) с `Retry-After: 60`. - Если заданы диапазоны IP, запросы с любых других адресов возвращают `ip_not_allowed` (HTTP 403). ## Журнал активности {#activity-log} На вкладке **Activity** перечислены все запросы, выполненные с ключом, начиная с последних: время, ключ, клиент, способ поступления (`http`, `mcp`, `chat`, `cli`, `confirm`, `preview`), метод и путь, инструмент, HTTP-статус, IP-адрес и (скрытые) подробности. Можно выполнять поиск по пути, инструменту или имени ключа, отображать только ошибки (HTTP 400 и выше) или только запросы, ожидающие подтверждения (428 и выше), а также ограничить период последним часом, 24 часами или 7 днями. NexCMP хранит последние 200,000 записей. Изменения, внесенные через ключ, также отображаются в Logs › Admin actions под именем `ak:/`. ![Вкладка Activity со списком запросов со статусом, клиентом, инструментом и IP](https://nexcmp.com/ru/docs/images/configure-with-ai/admin-api-keys-03-activity.webp) ## Проверка {#verify} Проверьте ключ только для чтения с любого компьютера, входящего в диапазон IP: ```bash curl -s https://cloud.example.com/v1/admin/agent/tools \ -H "Authorization: Bearer ak_XXXX" ``` Вы получите JSON-список инструментов, разрешенных вашими областями действия. Выполните один из них: ```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 '{}' ``` Время **Last used** ключа обновится, а вызов появится во вкладке **Activity**. Полный список инструментов и спецификация OpenAPI (`/v1/admin/openapi.json`) описаны в разделе [Подключение AI-клиента](https://nexcmp.com/ru/docs/configure-with-ai/mcp-admin/). ## Ошибки {#errors} Ошибки возвращаются в формате JSON: `{"error": {"code": "...", "message": "..."}}`. | HTTP | `code` | Значение | Решение | |---|---|---|---| | 401 | `invalid_key` | Ключ отсутствует, имеет неверный формат или неизвестен. Также возвращается при использовании ключа `ak_` для пути, не относящегося к административным. | Проверьте ключ; используйте его только для `/v1/admin/` и `/mcp/admin`. | | 401 | `key_expired` | Срок действия ключа истек. | Создайте новый ключ. | | 401 | `key_revoked` | Ключ был отозван. | Создайте новый ключ. | | 403 | `ip_not_allowed` | IP-адрес отправителя запроса находится за пределами диапазонов IP ключа. | Выполните запрос с разрешенного IP-адреса или создайте ключ с нужным диапазоном. | | 403 | `local_only_key` | Ключ, созданный для AI Chat или серверного CLI, был использован с другого компьютера. | Такие ключи работают только на самом сервере панели. | | 403 | `insufficient_scope` | У ключа нет необходимой области действия; ответ содержит `required_scope`. | Создайте ключ с этой областью действия. | | 403 | `forbidden_for_keys` | Эндпоинт или параметр, который вы пытаетесь изменить, закрыт для ключей. | Выполните это в панели администратора. | | 403 | `demo_read_only` | Панель находится в демо-режиме, а запрос выполняет запись. | Используйте панель не в демо-режиме. | | 403 | `confirm_in_ui` | Это действие необходимо подтвердить на экране в панели администратора. | Одобрите карточку подтверждения. | | 428 | `confirm_required` | Предпросмотр готов; ничего не изменилось. Содержит `confirm_token`. | Отобразите предпросмотр, затем повторите запрос с `X-Confirm-Token`. | | 409 | `confirm_expired` | Срок действия токена превышает 5 минут. | Отправьте запрос повторно для получения нового предпросмотра. | | 409 | `confirm_mismatch` | Токен относится к другому запросу (отличается метод, путь или тело). | Повторите полностью идентичный запрос. | | 409 | `confirm_invalid` | Неизвестный или уже использованный токен. | Отправьте запрос повторно для получения нового предпросмотра. | | 429 | `rate_limited` | Слишком много запросов за эту минуту. | Подождите `Retry-After`. | | 400 | `invalid_path` | Путь содержит запрещенные последовательности символов. | Используйте обычный путь. | | 413 | `too_large` | Размер тела запроса превышает 10 MB. | Отправьте меньше данных. | | 400 | `invalid_argument` | Аргумент инструмента отсутствует, неизвестен или имеет неверный тип; в сообщении указано его имя. | Исправьте аргумент. | ## Ограничения и примечания {#limits-notes} - Используйте ключи с коротким сроком действия и ограниченными правами. Предпочтительно создавать отдельный ключ для каждого клиента, чтобы можно было отозвать конкретный ключ. - Возможности ключа определяются его областями действия. Комбинация `secrets:write` и `billing:write` наиболее чувствительна; финансовые операции все равно останавливаются на этапе предпросмотра. - Ключи, созданные автоматически (для AI Chat, серверного CLI), действуют всего несколько минут и работают только на сервере панели. - Чтобы мгновенно отключить AI-клиент, отзовите его ключ. OAuth-подключения отзываются на вкладке **Connected apps** ([OAuth connectors](https://nexcmp.com/ru/docs/configure-with-ai/oauth-connectors/)). --- # Подключение AI-клиента (MCP) {#connect-an-ai-client-mcp} > **В панели управления:** System › Settings › API & AI agents (`/agent/keys`); на вкладке **Connect an AI** указан URL эндпоинта и готовые сниппеты с только что созданным ключом. ## Назначение {#what-it-does} Протокол **Model Context Protocol (MCP)** позволяет AI-клиентам вызывать инструменты. Панель предоставляет административный MCP-сервер по адресу `https://cloud.example.com/mcp/admin`. Подключите к нему AI-инструмент и управляйте инфраструктурой на обычном языке: «что осталось настроить?», «добавь кластер Proxmox», «создай тарифы с маржой 40%». Клиент вызывает админские инструменты; панель проверяет права доступа, запрашивает подтверждение перед опасными операциями и логирует каждый вызов. ::: info Два MCP-эндпоинта `/mcp` — **клиентский** эндпоинт (клиентские API-ключи, `vk_`; см. [MCP server](https://nexcmp.com/ru/docs/developers/mcp/)). `/mcp/admin` — описанный здесь **административный** эндпоинт (админские ключи `ak_` или OAuth). Они полностью разделены: админские инструменты недоступны на `/mcp`, а `/mcp/admin` принимает только админские ключи. ::: ## Требования {#requirements} | Параметр | Требование | |---|---| | Endpoint | `https://cloud.example.com/mcp/admin` на собственном домене вашей панели. Скопируйте точный URL на вкладке **Connect an AI**. На этой же странице указан локальный URL (`http://127.0.0.1:/mcp/admin`) для инструментов, работающих на самом сервере. | | Учетные данные | [Административный API-ключ](https://nexcmp.com/ru/docs/configure-with-ai/admin-api-keys/) (`ak_...`) с нужными правами доступа **или** вход через OAuth для веб-коннекторов ([OAuth connectors](https://nexcmp.com/ru/docs/configure-with-ai/oauth-connectors/)). | | Клиент | Любой MCP-клиент с поддержкой транспорта **Streamable HTTP** и кастомного заголовка `Authorization`. Версии протокола: 2025-11-25, 2025-06-18 и 2025-03-26. | | Сеть | Если перед панелью используется собственный reverse proxy, он должен проксировать `/mcp/admin`. Веб-коннекторы (claude.ai, ChatGPT) подключаются с серверов провайдера, поэтому URL должен быть доступен из интернета. | ## Подготовка инфраструктуры {#prepare-the-infrastructure} На сервере ничего устанавливать не нужно. Если вы настроили ограничение ключа по IP, убедитесь, что адрес клиента входит в разрешенный диапазон. Сначала проверьте доступность: ```bash curl -i -X POST https://cloud.example.com/mcp/admin ``` Ответ `401` с заголовком `WWW-Authenticate: Bearer ... resource_metadata=...` означает, что эндпоинт работает и ожидает учетные данные. ## Подключение в NexCMP {#connect-in-nexcmp} 1. Создайте ключ: **System › Settings › API & AI agents › API keys › New key**. Для первого теста выберите только `admin:read`; права на запись можно добавить позже при необходимости. См. [Admin API keys](https://nexcmp.com/ru/docs/configure-with-ai/admin-api-keys/). 2. Перейдите на вкладку **Connect an AI**. Пока открыто окно с новым ключом, сниппеты ниже уже содержат ваш реальный ключ. В противном случае отображается плейсхолдер `ak_YOUR_KEY`. 3. Скопируйте сниппет для вашего клиента и запустите или вставьте его, как описано далее. ![Вкладка Connect an AI с MCP URL и карточками с кнопкой копирования для каждого клиента](https://nexcmp.com/ru/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" ``` Затем запустите `claude` и введите запрос: «list the tools from nexcmp» или «what is left to set up?». Проверено 30/10/2026 с Claude Code 2.1: `claude mcp add --transport http …` записывает сервер (добавьте `-s project`, чтобы сохранить его в `.mcp.json` проекта — Claude Code запрашивает подтверждение серверов проекта при первом запуске). Для скриптов `claude -p "…" --mcp-config .mcp.json --strict-mcp-config --allowedTools "mcp__nexcmp__*"` выполняется без запроса подтверждения и позволяет Claude использовать только инструменты панели. ### Claude Desktop {#claude-desktop} Требуется Node.js 18 или новее. Добавьте следующий фрагмент в `claude_desktop_config.json` (используется мост `mcp-remote`) и перезапустите Claude Desktop: ```json { "mcpServers": { "nexcmp": { "command": "npx", "args": ["-y", "mcp-remote", "https://cloud.example.com/mcp/admin", "--header", "Authorization:Bearer ak_XXXX"] } } } ``` Если система некорректно обрабатывает пробел в аргументе заголовка, передайте все значение через переменную окружения (аналогично клиентскому эндпоинту): `"args": [..., "--header", "Authorization:${NEXCMP_AUTH_HEADER}"]` с `"env": { "NEXCMP_AUTH_HEADER": "Bearer ak_XXXX" }`. ### claude.ai (custom connector) {#claude-ai-custom-connector} Ключ не требуется: авторизация выполняется через OAuth. В claude.ai откройте настройки коннекторов, добавьте custom connector, вставьте `https://cloud.example.com/mcp/admin`, войдите под учетной записью администратора NexCMP и выберите разрешения на экране подтверждения. Подробнее: [OAuth connectors](https://nexcmp.com/ru/docs/configure-with-ai/oauth-connectors/). ### ChatGPT (developer mode) {#chatgpt-developer-mode} Ключ не требуется. В ChatGPT включите developer mode, добавьте MCP-коннектор с URL `https://cloud.example.com/mcp/admin`, выберите OAuth и войдите под учетной записью администратора NexCMP. Подробнее: [OAuth connectors](https://nexcmp.com/ru/docs/configure-with-ai/oauth-connectors/). ### Codex CLI {#codex-cli} Добавьте в `~/.codex/config.toml`: ```toml [mcp_servers.nexcmp] url = "https://cloud.example.com/mcp/admin" bearer_token_env_var = "NEXCMP_KEY" ``` Затем экспортируйте ключ в командной оболочке, запускающей Codex: ```bash export NEXCMP_KEY=ak_XXXX codex codex mcp list # shows nexcmp with "Bearer token" auth ``` ::: tip Неинтерактивный `codex exec` В `codex exec` (скрипты, CI) Codex не запрашивает подтверждение перед вызовом инструментов и пропускает инструменты, изменяющие данные. Добавьте `default_tools_approval_mode = "approve"` в `[mcp_servers.nexcmp]`, чтобы разрешить их вызов; панель по-прежнему возвращает предпросмотр и запрашивает подтверждение для финансовых операций, действий безопасности и удаления. Проверено на Codex CLI 0.166 от 30/10/2026. ::: ### Gemini CLI {#gemini-cli} Добавьте в `~/.gemini/settings.json`: ```json { "mcpServers": { "nexcmp": { "httpUrl": "https://cloud.example.com/mcp/admin", "headers": { "Authorization": "Bearer ak_XXXX" } } } } ``` Gemini CLI отключает серверы MCP в папках, которым он не доверяет. Запустите его в доверенной папке (или подтвердите доверие при запросе), затем проверьте командой `gemini mcp list` — отобразится `nexcmp … Connected`. Вы можете не хранить ключ в файле с помощью `"Authorization": "Bearer $NEXCMP_KEY"`. Проверено на Gemini CLI 0.66 от 30/10/2026. ### Cursor {#cursor} Добавьте в `~/.cursor/mcp.json` (или `.cursor/mcp.json` в проекте): ```json { "mcpServers": { "nexcmp": { "url": "https://cloud.example.com/mcp/admin", "headers": { "Authorization": "Bearer ak_XXXX" } } } } ``` ::: tip Хранение ключа вне конфигурационных файлов Если клиент это поддерживает, считывайте ключ из переменной окружения, а не записывайте его в файл: Codex делает это по умолчанию (`bearer_token_env_var`), а Cursor принимает `"Bearer ${env:NEXCMP_KEY}"`. Никогда не фиксируйте в коммитах файлы, содержащие ключ. ::: ### 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", ) ``` Полный цикл выполнения (проверено на `openai-agents` 0.24 от 30/10/2026 — инструмент чтения, затем изменение баланса, вернувшее предпросмотр для подтверждения и примененное при повторном вызове с `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} Передайте сервер как инструмент с типом `mcp`. Оставьте `require_approval` в `always`, чтобы программа запрашивала подтверждение перед каждым вызовом: ```json { "type": "mcp", "server_label": "nexcmp", "server_url": "https://cloud.example.com/mcp/admin", "headers": { "Authorization": "Bearer ak_XXXX" }, "require_approval": "always" } ``` ### Другие варианты (обычный HTTP) {#anything-else-plain-http} Клиент без поддержки MCP может вызывать те же инструменты по HTTP. `GET /v1/admin/agent/tools` выводит их список, `POST /v1/admin/agent/tools/` выполняет инструмент с аргументами в теле JSON, а `GET /v1/admin/openapi.json` возвращает спецификацию OpenAPI 3.1 (каждый инструмент — это отдельная операция). Для всех требуется `Authorization: Bearer ak_...`. ## Проверка {#verify} 1. Список инструментов без клиента: ```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"}' ``` В ответе придет результат JSON-RPC со списком инструментов, разрешенных вашими scopes. 2. В клиенте запросите «run system_health». Инструмент возвращает предупреждения, состояние подключенной инфраструктуры, платежей, почты, AI и статус лицензии. 3. Откройте **API & AI agents › Activity**: отобразится список вызовов с именем клиента и `mcp`. 4. На сервере команда `sudo nexcmp status` выведет строку «MCP admin» со статусом `ready`, если эндпоинт отвечает (HTTP 401 без ключа является нормальным состоянием). ## Инструменты {#tools} Сервер предоставляет 58 инструментов. Клиент видит только те инструменты, которые разрешены областями видимости (scopes) его ключа: для инструментов чтения требуется `admin:read`, для инструментов записи — соответствующий им scope. Инструменты записи также принимают опциональный аргумент `confirm_token` (см. [Confirmation](#confirmation-confirm-token)). Аргументы проверяются по схеме каждого инструмента: неизвестные или некорректно указанные аргументы отклоняются с сообщением об ошибке. Цены указываются в USD: стоимость тарифов — в долларах в час (`hourly_usd`), баланс — в центах. Секретные значения можно устанавливать, но они никогда не возвращаются в ответе. ### Обзор и журналы {#overview-and-logs} | Инструмент | Назначение | Скоуп | Изменяет данные | Требует подтверждения | |---|---|---|---|---| | `system_health` | Оповещения, требующие внимания, состояние инфраструктуры, платежей, почты, AI, статус лицензии и обновлений. | `admin:read` | Нет | Нет | | `setup_checklist` | Что настроено и что осталось настроить: лицензия, инфраструктура, зона, шаблоны ОС, тарифы, платежи, почта, брендинг, юридические документы, тестовый заказ. | `admin:read` | Нет | Нет | | `license_status` | Статус лицензии и наличие более новой версии NexCMP. | `admin:read` | Нет | Нет | | `audit_search` | Поиск по журналу аудита администратора и журналу API-ключей. | `admin:read` | Нет | Нет | ### Настройки, брендинг, юридические документы, модули {#settings-branding-legal-modules} | Инструмент | Назначение | Скоуп | Изменяет данные | Требует подтверждения | |---|---|---|---|---| | `settings_get` | Чтение общих настроек (`keys` фильтрует параметры; символ `*` на конце означает поиск по префиксу). | `admin:read` | Нет | Нет | | `settings_update` | Изменение общих настроек из плоского объекта `values`. Принимаются только ключи, возвращаемые `settings_get`. | `settings:write` | Да | Если ключ затрагивает платежи, безопасность входа, глобальные переключатели или цены | | `branding_get` | Название бренда, цвет, валюта отображения, наименование продавца, URL логотипа и favicon. | `admin:read` | Нет | Нет | | `branding_update` | Установка названия бренда (до 60 символов), цвета (`#rrggbb`), валюты отображения (`usd` или `vnd`) и наименования продавца. | `settings:write` | Да | Нет | | `branding_logo_set` | Загрузка светлого или тёмного логотипа либо favicon по HTTPS URL или base64 (PNG, JPEG, WEBP, ICO или SVG, до 512 КБ). | `settings:write` | Да | Нет | | `legal_get` | Условия обслуживания и политика конфиденциальности (на английском и вьетнамском языках), а также нейтральные значения по умолчанию. | `admin:read` | Нет | Нет | | `legal_update` | Настройка текста условий и политики (простой markdown, без HTML, до 50 КБ каждый). Пустая строка возвращает значение по умолчанию. | `settings:write` | Да | Нет | | `modules_get` | Список включённых опциональных модулей и тех, которые можно переключать. | `admin:read` | Нет | Нет | | `module_set` | Включение или отключение опционального модуля (`key` должен быть одним из `settable`). | `settings:write` | Да | Нет | ### Электронная почта и оповещения {#email-and-alerts} | Инструмент | Назначение | Скоуп | Изменяет данные | Требует подтверждения | |---|---|---|---|---| | `smtp_get` | Настройки исходящей почты (пароль скрыт) и состояние очереди. | `admin:read` | Нет | Нет | | `smtp_configure` | Настройка сервера SMTP. При смене хоста, порта или параметров безопасности требуется повторный ввод пароля. | `settings:write` (+ `secrets:write` для пароля) | Да | Нет | | `smtp_test` | Отправка реального тестового письма с сохранёнными настройками. | `settings:write` | Отправляет письмо | Нет | | `telegram_get` | Каналы уведомлений администратора (ID чатов; токены ботов никогда не возвращаются). | `admin:read` | Нет | Нет | | `telegram_configure` | Добавление или обновление канала оповещений Telegram (токен бота и ID чата) и переключение оповещений администратора. | `settings:write` (+ `secrets:write` для токена) | Да | Нет | | `telegram_test` | Отправка тестового сообщения в канал Telegram. | `settings:write` | Отправляет сообщение | Нет | ### Платежи и валюта {#payments-and-currency} | Инструмент | Назначение | Скоуп | Изменяет данные | Требует подтверждения | |---|---|---|---|---| | `payments_get` | Статус Stripe, PayPal, криптовалюты (USDT) и банковского перевода, а также включённые каналы и комиссии. | `admin:read` | Нет | Нет | | `payment_configure` | Настройка учётных данных одного шлюза (`stripe`, `paypal`, `crypto` или `bank`). | `billing:write` (+ `secrets:write`) | Да | Всегда | | `payment_test` | Проверка сохранённых учётных данных шлюза на стороне провайдера. | `billing:write` | Нет | Нет | | `currency_get` | Отображаемая валюта и курс USD к VND (автоматический или фиксированный). | `admin:read` | Нет | Нет | | `currency_set` | Настройка отображаемой валюты и/или фиксированного курса (0 — автоматический, иначе от 15000 до 50000). | `billing:write` | Да | При изменении фиксированного курса | ### Инфраструктура и зоны {#infrastructure-and-zones} | Инструмент | Назначение | Скоуп | Изменяет данные | Требует подтверждения | |---|---|---|---|---| | `cloudstack_get` | Сохранённая точка подключения к CloudStack, идентификаторы зон и сетей (ключи скрыты). | `admin:read` | Нет | Нет | | `cloudstack_test` | Тестирование точки подключения с ключом и секретом API без сохранения; выводит список зон. | `infra:write` (+ `secrets:write`, так как передаются ключи) | Нет | Нет | | `cloudstack_connect` | Сохранение подключения к CloudStack. | `infra:write` (+ `secrets:write`) | Да | Всегда | | `proxmox_list` | Кластеры Proxmox VE, добавленные в качестве источников, с их статусом работоспособности. | `admin:read` | Нет | Нет | | `proxmox_add` | Добавление кластера Proxmox VE с токеном API (`user@realm!tokenid`) и его секретом. | `infra:write` (+ `secrets:write`) | Да | Нет | | `proxmox_test` | Подключение к кластеру по ID; при первом успешном соединении привязывается его TLS-сертификат. | `infra:write` | Да | Нет | | `proxmox_attach_zone` | Продажа кластера Proxmox в существующей зоне, опционально с узлом в качестве региона. | `infra:write` | Да | Нет | | `zones_list` | Зоны (локации), доступные для выбора клиентам. | `admin:read` | Нет | Нет | | `zone_create` | Создание зоны. | `infra:write` | Да | Нет | ### Каталог и тарифные планы {#catalog-and-plans} | Инструмент | Назначение | Скоуп | Изменяет данные | Требует подтверждения | |---|---|---|---|---| | `templates_list` | Шаблоны ОС, доступные клиентам для установки. | `admin:read` | Нет | Нет | | `templates_sync` | Импорт шаблонов ОС из CloudStack. | `catalog:write` | Да | Нет | | `template_update` | Включение или скрытие шаблона, переименование, настройка пользователя по умолчанию или порядка сортировки. | `catalog:write` | Да | Нет | | `offerings_list` | Сервисные предложения CloudStack (CPU, память, корневой диск) для формирования тарифов. | `admin:read` | Нет | Нет | | `plans_list` | Тарифные планы с ценой за час и за месяц, конфигурацией, зоной и количеством использующих их серверов. | `admin:read` | Нет | Нет | | `plan_create` | Создание тарифного плана. Цена указывается в `hourly_usd`. Для тарифов CloudStack требуется `cs_offering_id`; для Proxmox — `backend_id`. | `catalog:write` | Да | Нет | | `plan_update` | Переименование, отображение или скрытие, включение или отключение, а также изменение цен тарифа. Изменение конфигурации активного тарифа требует создания копии. | `catalog:write` | Да | При изменении цены | | `plans_from_offerings` | Сформировать начальную таблицу тарифов из offerings (или конфигураций Proxmox) на основе вашей себестоимости и процента наценки. Возвращает предпросмотр; вызовите повторно с `apply=true`, чтобы создать тарифы. | `catalog:write` | С `apply=true` | Всегда при применении | | `quota_defaults_get` | Лимиты клиентов по умолчанию. | `admin:read` | Нет | Нет | | `quota_defaults_set` | Изменить настройки `quota_*`. | `catalog:write` | Да | Нет | | `coupons_list` | Пакеты скидочных кодов и подарочных сертификатов. | `admin:read` | Нет | Нет | | `coupon_create` | Создать пакет кодов: тип `money` (номинал в центах USD) или `percent` (от 1 до 100, с максимальной скидкой). | `catalog:write` | Да | Всегда | ### Клиенты и реселлеры {#customers-and-resellers} | Инструмент | Назначение | Скоуп | Изменяет данные | Требует подтверждения | |---|---|---|---|---| | `customers_search` | Поиск клиентов по e-mail, имени или IP. | `admin:read` | Нет | Нет | | `customer_get` | Аккаунт, баланс, серверы и недавние списания конкретного клиента. | `admin:read` | Нет | Нет | | `customer_adjust_balance` | Начислить (положительное значение) или списать (отрицательное значение) средства в центах USD. Обязательно указать причину. | `billing:write` | Да | Всегда | | `customer_block` | Заблокировать клиента с возможностью остановки его серверов. Обязательно указать причину. | `customers:write` | Да | Всегда | | `customer_unblock` | Разблокировать клиента. | `customers:write` | Да | Нет | | `resellers_list` | Реселлеры с балансом и статусом. | `admin:read` | Нет | Нет | | `reseller_get` | Сайт, баланс, пользователи и платежные шлюзы конкретного реселлера. | `admin:read` | Нет | Нет | ### Провайдер ИИ {#ai-provider} | Инструмент | Назначение | Скоуп | Изменяет данные | Требует подтверждения | |---|---|---|---|---| | `ai_provider_get` | OpenAI-совместимый провайдер, используемый клиентскими функциями AI Chat и AI Agent (ключ скрыт). | `admin:read` | Нет | Нет | | `ai_provider_set` | Настроить провайдера: base URL, модель, API-ключ, резервные модели, reasoning effort, активность. | `ai:write` (+ `secrets:write` для ключа) | Да | Нет | | `ai_provider_test` | Задать сохраненному провайдеру один вопрос для проверки его работоспособности. | `ai:write` | Нет | Нет | ### Файлы конфигурации {#configuration-files} | Инструмент | Назначение | Скоуп | Изменяет данные | Требует подтверждения | |---|---|---|---|---| | `config_export` | Экспортировать конфигурацию в формате YAML (секреты заменяются ссылками `secret://`). | `admin:read` | Нет | Нет | | `config_plan` | Сравнить YAML-конфигурацию с текущей панелью и показать список планируемых изменений. | `admin:read` | Нет | Нет | | `config_apply` | Применить YAML-конфигурацию раздел за разделом. Каждое изменение подчиняется стандартным правилам разрешений и подтверждения. | `admin:read` + разрешения каждого изменения | Да | Для каждого изменения | Формат файла описан в разделе [Конфигурация как код](https://nexcmp.com/ru/docs/configure-with-ai/config-as-code/). ## Промпты {#prompts} Сервер также предоставляет три готовых промпта, которые клиенты могут отображать в виде быстрых действий: | Промпт | Параметр | Что требуется сделать AI | |---|---|---| | `initial-setup` | нет | Вызвать `setup_checklist`, объяснить каждый оставшийся шаг в одном предложении, запросить необходимые данные, выполнить шаг подходящим инструментом, показать предпросмотр финансовых изменений и настроек безопасности, после чего завершить через `system_health`. | | `add-proxmox` | `endpoint` (необязательно, `https://host:8006`) | Запросить токен API, затем вызвать `proxmox_add`, `proxmox_test`, инструменты зон и `proxmox_attach_zone`; после чего предложить тарифы с помощью `plans_from_offerings` и ожидать подтверждения. | | `launch-pricing` | `margin_pct` (необязательно, по умолчанию 40) | Запросить вашу ежемесячную себестоимость vCPU, ГБ RAM и ГБ диска, показать таблицу предпросмотра с себестоимостью, ценой в месяц и ценой в час, а затем создать тарифы после вашего подтверждения. | ## Подтверждение (`confirm_token`) {#confirmation-confirm-token} Действия, связанные с переводом средств, удалением данных, изменением платежных реквизитов или настроек авторизации, выполняются в два шага: 1. Первый вызов ничего не меняет. Ответ инструмента начинается со строки «CONFIRMATION REQUIRED» и содержит **предпросмотр** (что будет вызвано, почему операция чувствительна, новые и текущие значения) и `confirm_token`. 2. Клиент обязан показать вам предпросмотр. Только после вашего одобрения он повторно вызывает тот же инструмент с теми же параметрами и передает `confirm_token`. 3. Токен действует однократно, только для этого конкретного запроса и сгорает через 5 минут. Инструкции сервера предписывают ИИ воспринимать результаты инструментов как данные, а не как инструкции, и ни в коем случае не повторять вызов с токеном, который вы не подтвердили. Главная защита — это вы: читайте предпросмотр. ::: warning Не одобряйте автоматически Некоторые клиенты могут автоматически одобрять каждый вызов инструмента. Для инструментов записи оставьте подтверждение каждого вызова включенным или используйте ключ только для чтения, чтобы ошибочный план ИИ не был применен в панели незамеченным. ::: ## Принцип работы {#how-it-works} | Параметр | Описание | |---|---| | Транспорт | `POST /mcp/admin` с сообщением JSON-RPC 2.0; ответ — `application/json`. До 20 сообщений в пакете. `GET /mcp/admin` возвращает 405 (нет серверного потока); `DELETE /mcp/admin` завершает сессию. | | Аутентификация | `Authorization: Bearer ak_...` (созданный вручную ключ или токен доступа OAuth). При отсутствии или неверных учетных данных возвращается 401 с `WWW-Authenticate: Bearer ... resource_metadata=...`, что позволяет OAuth-клиентам самостоятельно запускать вход. | | Сессии | `Mcp-Session-Id` выдается через `initialize`, привязан к этому ключу и действует 24 часа. | | Возможности | Инструменты и промпты. Без ресурсов. | | Размер | Тело запроса до 1 МБ; результат работы инструмента усекается примерно после 100 КБ. | | Origin | Запрос с заголовком `Origin` от другого сайта отклоняется (`origin_not_allowed`). Клиенты командной строки и десктопные клиенты его не отправляют. | | Тот же шлюз, что и для REST | Каждый вызов инструмента повторно отправляется через собственный конвейер запросов панели с вашим ключом, поэтому области видимости, диапазоны IP, лимит запросов, подтверждение и журнал активности применяются в точности так же, как и для прямых вызовов API. | ## Ограничения и примечания {#limits-notes} - Если инструмент вам не виден, значит, для него не была предоставлена область видимости. Добавьте эту область видимости в новый ключ. - Установка пароля или ключа API через ИИ-клиент означает, что секретные данные проходят через этот ИИ. При желании оставьте `secrets:write` отключенным и вводите секреты самостоятельно в панели администратора либо используйте поле **Secret** в AI Chat ([AI Chat в панели администратора](https://nexcmp.com/ru/docs/configure-with-ai/ai-chat-in-admin/#secrets)) или ссылки `secret://` ([Конфигурация как код](https://nexcmp.com/ru/docs/configure-with-ai/config-as-code/#secrets)). - Клиенты не используют общие сессии: каждое подключение начинается с `initialize`. - Отозовите ключ в **API & AI agents**, чтобы немедленно отключить ИИ-клиент. ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | 401 `invalid_key` | Неверный, усеченный ключ или ключ без прав администратора (например, ключ `vk_`) | Используйте ключ `ak_`. | | 401 `key_expired` или `key_revoked` | Срок действия ключа истек или он был отозван | Создайте новый ключ. | | 403 `ip_not_allowed` | Ваш IP находится вне разрешенных для ключа диапазонов IP | Подключитесь с разрешенного IP. | | 403 `origin_not_allowed` | Страница браузера с другого origin обратилась к эндпоинту | Используйте десктопный клиент или CLI. | | 404 при запросе с `Mcp-Session-Id` | Сессия принадлежит другому ключу или истекла | Отправьте `initialize` повторно. | | 400 unsupported `MCP-Protocol-Version` | Клиент использует версию, неизвестную серверу | Обновите клиент; поддерживаются: 2025-11-25, 2025-06-18, 2025-03-26. | | Список инструментов неполный | Области видимости ключа | Создайте ключ с более широкими областями видимости. | | `insufficient_scope` при вызове | Инструменту требуется вторая область видимости, например `secrets:write` | Добавьте область видимости в новый ключ. | | 429 `rate_limited` | Количество вызовов в минуту превышает лимит ключа | Дождитесь `Retry-After` или увеличьте лимит в новом ключе. | | claude.ai или ChatGPT не могут подключиться | URL недоступен из интернета, либо прокси блокирует `/mcp/admin` или `/oauth-admin/` | Проверьте DNS, TLS и обратный прокси. | Все коды ошибок приведены в разделе [Ключи API администратора](https://nexcmp.com/ru/docs/configure-with-ai/admin-api-keys/#errors). --- # Коннекторы claude.ai и ChatGPT {#claude-ai-and-chatgpt-connectors} > **Где найти в панели:** System › Settings › API & AI agents (`/agent/keys`), вкладка **Connected apps**. Экран подтверждения открывается по адресу `/agent/consent` при запросе доступа коннектором (в меню его нет). ## Назначение {#what-it-does} Веб-приложения ИИ не могут прочитать ключ с вашего диска. Они подключаются через **OAuth**: вы добавляете MCP URL панели, приложение перенаправляет вас в панель администратора для входа, вы выбираете разрешенные действия и срок доступа, а приложение получает краткосрочные токены. Никаких ключей копировать не нужно. Доступ приложению можно закрыть в любой момент. Используйте этот способ для кастомных коннекторов claude.ai, коннекторов ChatGPT в режиме разработчика и любых других MCP-клиентов с поддержкой OAuth и динамической регистрации клиентов. Утилиты командной строки могут использовать тот же сценарий, но для них проще использовать [admin API key](https://nexcmp.com/ru/docs/configure-with-ai/admin-api-keys/). ## Требования {#requirements} | Параметр | Требование | |---|---| | URL | `https://cloud.example.com/mcp/admin`, доступный из интернета (к нему подключаются серверы поставщика). | | Обратный прокси | Если перед панелью используется собственный прокси-сервер, он должен перенаправлять `/mcp/admin`, `/oauth-admin/` и пути `/.well-known/` на панель. | | Вы | Выполнен вход в панель NexCMP **в том же браузере**, где открывается экран подтверждения. | | Клиент | Поддержка MCP over Streamable HTTP, OAuth 2.1 с PKCE (S256) и динамической регистрации клиентов. | ## Подключение {#connect} 1. В ИИ-приложении добавьте кастомный MCP-коннектор и вставьте `https://cloud.example.com/mcp/admin`. В claude.ai это находится в настройках коннекторов (add custom connector); в ChatGPT — в режиме разработчика (add an MCP connector, аутентификация OAuth). 2. Выберите **Sign in** (или «Connect») в приложении. Браузер откроет экран подтверждения NexCMP. Если вы еще не вошли в систему, сначала выполните вход — после этого процесс продолжится. 3. Ознакомьтесь с карточкой: «**Example AI app** wants to manage this NexCMP admin» (название запрашивающего приложения) и адресом, на который вы будете возвращены. 4. Отметьте запрашиваемые права (scopes). Права, запрошенные приложением, уже выбраны; если ничего не запрашивалось, отмечен только `admin:read`. См. [Scopes](https://nexcmp.com/ru/docs/configure-with-ai/admin-api-keys/#scopes). 5. Выберите срок действия подключения: **7**, **30** или **90** дней (по умолчанию 30). 6. Нажмите **Allow**. Браузер вернется в приложение, которое теперь подключено. Для отказа нажмите **Deny**. ![Экран подтверждения с запросом разрешения для ИИ-приложения, чекбоксами scopes, выбором срока действия и кнопками Allow и Deny](https://nexcmp.com/ru/docs/images/configure-with-ai/oauth-connectors-01-consent.webp) ::: important Выбирайте scopes так же, как для ключа Предоставляйте минимально необходимый набор прав. Операции с финансами, удалением и безопасностью по-прежнему потребуют предварительного просмотра и вашего подтверждения, однако подключение с `settings:write` всё равно сможет изменить брендинг и почту. ::: ## Управление и отзыв {#manage-and-revoke} Перейдите в **System › Settings › API & AI agents › Connected apps**. В таблице перечислены все подключенные приложения: приложение, scopes, дата подключения, срок действия и дата последнего использования. Чтобы закрыть доступ приложению, нажмите **Revoke** и подтвердите действие. Его токены перестанут действовать немедленно; для повторного подключения приложению потребуется снова пройти экран подтверждения. ![Вкладка Connected apps с одним ИИ-приложением, его scopes, сроком действия и кнопкой Revoke](https://nexcmp.com/ru/docs/images/configure-with-ai/oauth-connectors-02-connected-apps.webp) ## Как устроен процесс {#how-the-flow-works} | Шаг | Описание | |---|---| | Обнаружение | Приложение считывает `/.well-known/oauth-protected-resource/mcp/admin`, затем `/.well-known/oauth-authorization-server/oauth-admin`. Значение issuer: `https://cloud.example.com/oauth-admin`. | | Регистрация | Приложение регистрируется (`POST /oauth-admin/register`, RFC 7591). Поддерживаются только публичные клиенты (без client secret). Адрес перенаправления должен быть `https` или `http` на том же компьютере (loopback). | | Авторизация | `GET /oauth-admin/authorize` с методом PKCE `S256`. Параметр `resource`, если передан, должен содержать URL `/mcp/admin` этой панели. Запрос действителен в течение 10 минут и привязан к браузеру, который его инициировал. | | Согласие | Вы выбираете области доступа и срок действия (выше). Код авторизации действителен 60 секунд и работает один раз. | | Токены | `POST /oauth-admin/token` возвращает **access token** (ключ `ak_o...`, действительный 1 час или до завершения соединения, в зависимости от того, что наступит раньше) и **refresh token** (`akr_...`). При каждом обновлении возвращается новый refresh token, а старый перестает действовать. Соединение завершается по истечении выбранного количества дней. | | Отзыв | **Revoke** в Connected apps или вызов `POST /oauth-admin/revoke` со стороны приложения (RFC 7009). | Access token работает как ключ администратора с предоставленными вами областями доступа: те же правила областей, подтверждение, rate limit и журнал действий. Его вызовы отображаются на вкладке **Activity**. ## Проверка {#verify} 1. В приложении запросите «run system_health» (или «what tools do you have?»). Приложение выведет список инструментов, разрешенных вашими областями доступа ([список инструментов](https://nexcmp.com/ru/docs/configure-with-ai/mcp-admin/#tools)). 2. Откройте **Connected apps**: значение **Last used** обновится. 3. Откройте **Activity**: вызовы отображаются с указанием названия приложения и `mcp`. ## Ограничения и примечания {#limits-notes} - Если приложение снова запрашивает вход через час, это нормальное поведение, когда клиент не обновляет токен; подключитесь заново. - Повторно использованный refresh token считается скомпрометированным: все соединение отзывается. Подключитесь заново из приложения. - Повторно использованный код авторизации отклоняется (`invalid_grant`), а ранее выданные по нему токены отзываются. - Доступ по OAuth никогда не дает больше прав, чем разрешено правилами областей: ограничение [что ключ не может делать](https://nexcmp.com/ru/docs/configure-with-ai/admin-api-keys/#what-a-key-can-never-do) распространяется и на подключенные приложения. - Разработчики меняют интерфейс и поддерживаемые возможности. Если приложение разработчика на вашем тарифе не поддерживает пользовательские коннекторы, используйте [admin API key](https://nexcmp.com/ru/docs/configure-with-ai/admin-api-keys/) с десктопным или консольным клиентом. ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | На экране согласия отображается «Wrong browser» | Запрос был инициирован в браузере, отличном от того, где выполнен вход | Повторите подключение из AI-приложения в том же браузере. | | На экране согласия сообщается, что запрос истек или отсутствует | Прошло более 10 минут или ссылка была открыта дважды | Повторите подключение из AI-приложения. | | Страница «Unknown client» или «redirect address does not match» | Регистрация приложения устарела или оно использует незарегистрированный адрес перенаправления | Удалите коннектор в приложении и добавьте его заново. | | `invalid_target` | Отправленный `resource` не соответствует URL `/mcp/admin` этой панели | Используйте точный URL, указанный на вкладке **Connect an AI**. | | `invalid_request` о PKCE | Клиент не отправляет `code_challenge_method=S256` | Используйте клиент с поддержкой OAuth 2.1 и PKCE. | | Приложение подключается, но вызов возвращает `insufficient_scope` | Эта область доступа не была выбрана | Отозовите соединение и подключитесь снова, отметив нужную область доступа. | | Приложению не удается получить доступ к URL | DNS, TLS или обратный прокси блокирует `/mcp/admin`, `/oauth-admin/` или `/.well-known/` | Проверьте правила проксирования. | --- # Конфигурация как код {#configuration-as-code} > **В панели управления:** System › Settings › Import/Export (`/agent/config`). На сервере: команды `nexcmp config export`, `plan` и `apply`, а также `nexcmp admin `. ## Назначение {#what-it-does} Конфигурацию панели (брендинг, общие настройки, почту, Telegram-уведомления, модули, валюту, платежные шлюзы, лимиты, зоны, тарифные планы, AI-провайдера и юридические документы) можно сохранить в виде одного YAML-файла. Вы можете редактировать файл вручную, поручить редактирование AI-ассистенту, хранить его в системе контроля версий и применять к этой же или другой панели. До внесения любых изменений вы всегда видите список различий. Секретные данные никогда не записываются в файл. Используйте эту возможность, чтобы клонировать конфигурацию на другую установку, проверять изменения перед их публикацией, восстанавливать настройки после ошибок или позволить AI сгенерировать полную конфигурацию, которую вы сможете просмотреть как единый документ. ## Требования {#requirements} | Параметр | Требование | |---|---| | NexCMP | 1.4.0 или новее. | | Командная строка | Вы вошли под `root` на сервере панели (используйте `sudo`). Команда сама запрашивает у панели временный ключ (15 минут, все области действия). Чтобы использовать ключ с более ограниченными правами, укажите в `NEXCMP_KEY` [API-ключ администратора](https://nexcmp.com/ru/docs/configure-with-ai/admin-api-keys/) и передайте его через sudo, например `sudo --preserve-env=NEXCMP_KEY nexcmp config plan -f nexcmp.yaml`. | | Страница администратора | Выполнен вход в панель администратора. На демо-панели страница доступна только для чтения. | | Секреты | Значения передаются во время применения (см. [Секреты](#secrets)) и никогда не хранятся в файле. | ## Экспорт, редактирование, предпросмотр и применение {#export-edit-preview-apply} 1. Экспортируйте текущую конфигурацию: ```bash sudo nexcmp config export -o nexcmp.yaml ``` Без `-o` YAML выводится на экран. 2. Отредактируйте `nexcmp.yaml` (см. [пример](#example-file) ниже). Оставьте `version: 1` в начале файла. 3. Посмотрите, что изменится. Это действие ничего не меняет: ```bash sudo nexcmp config plan -f nexcmp.yaml ``` В каждой строке отображаются раздел, элемент, поле и `old → new`. Строки, помеченные `$`, относятся к разделам биллинга (см. [Разделы биллинга](#billing-sections)). Если настройки панели уже совпадают с файлом, отображается «No changes». 4. Примените изменения. Без `--yes` команда выполняется как **тестовый запуск** и лишь выводит тот же список: ```bash sudo nexcmp config apply -f nexcmp.yaml --yes ``` 5. Ознакомьтесь с результатом: `applied`, `pending` (ожидает вашего подтверждения), `skipped` и `errors`. | Параметр | Значение | |---|---| | `-f ` | YAML-файл (обязателен для `plan` и `apply`). | | `--yes` | Фактическое применение. Без этого параметра `apply` выполняется как тестовый запуск. | | `--confirm-billing` | Применить также разделы биллинга (`payments`, `currency`, `plans`). Без этого параметра они пропускаются. | | `--section ` | Применить только этот раздел. Чтобы указать несколько разделов, повторите параметр. | | `-o ` | С `export`: записать YAML в файл. | Код возврата равен 0, если все изменения применены или изменений не было, 1 — при возврате ошибки, 2 — при ошибке использования или ключа. ### Секреты {#secrets} Вместо секретных данных в файле хранятся ссылки, например `password: secret://smtp_password`. При применении значение берется из переменной окружения с именем `NEXCMP_SECRET_` и именем ссылки заглавными буквами: ```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 ``` Если для ссылки не передано значение, ранее сохраненный в панели секрет **остается без изменений**. Секрет, который не был сохранен и не был передан, остается пустым. | Имя ссылки | Где используется | |---|---| | `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` | ## Пример файла {#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). ``` Файл может содержать любое подмножество разделов. Неуказанные разделы остаются без изменений. Файл размером более 1 MB, отсутствие `version: 1`, несовпадающий номер версии или неизвестный раздел отклоняются до запуска каких-либо действий. ## Разделы {#sections} | Раздел | Что настраивает | Примечания | |---|---|---| | `branding` | Название бренда (до 60 символов), основной цвет, валюта отображения (`usd` или `vnd`), наименование продавца. | Логотипы не входят в файл; используйте [страницу брендинга](https://nexcmp.com/ru/docs/customers/branding/). | | `settings` | Фиксированный список общих настроек: `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`. | Остальные ключи игнорируются. | | `email.smtp` | SMTP-хост, порт, тип шифрования (`starttls`, `tls`, `none`), пользователь, пароль, имя и адрес отправителя, reply-to. | [SMTP и шаблоны писем](https://nexcmp.com/ru/docs/administration/smtp-and-emails/). При изменении хоста, порта или типа шифрования потребуется заново указать пароль. | | `telegram` | Включение или отключение канала оповещений, chat id, bot token. | [Уведомления в Telegram](https://nexcmp.com/ru/docs/administration/telegram-notifications/). | | `modules` | Включение или отключение дополнительных модулей (`key: true/false`). | Только параметры, переключение которых доступно в панели. См. [Модули](https://nexcmp.com/ru/docs/infrastructure/modules/). | | `currency` | Валюта отображения и ручной курс USD к VND (`0` — автоматически, иначе от 15000 до 50000). | Раздел биллинга. См. [Валюта и курсы обмена](https://nexcmp.com/ru/docs/catalog/currency-and-exchange-rates/). | | `payments` | Учетные данные `stripe`, `paypal`, `crypto`, `bank` и переключатели `channels` (`pay_card_enabled`, `pay_wallets_enabled`, `pay_alipay_enabled`, `pay_paypal_enabled`, `pay_usdt_enabled`, `pay_sepay_enabled`). | Раздел биллинга. См. [Платежные каналы](https://nexcmp.com/ru/docs/billing/payment-channels/). | | `quotas` | Лимиты `quota_*`. | См. [Квоты](https://nexcmp.com/ru/docs/billing/quotas/). | | `zones` | Зоны по `slug` (обязательные: `slug`, `name`, `country`; необязательные: `city`, `enabled`, `is_default`). | Создаются новые зоны. Уже существующая зона **не изменяется** файлом. См. [Зоны](https://nexcmp.com/ru/docs/infrastructure/zones/). | | `plans` | Тарифные планы по `slug` (обязательные: `slug`, `name`, `cpu`, `ram_mb`, `disk_gb`, `hourly_usd`; необязательные: `cs_offering_id`, `backend_id`, `zone_id`, `enabled`, `visible`, `sort`, `description`). | Раздел биллинга. Новые тарифные планы создаются, существующие обновляются по slug. Цены указаны в USD в час. См. [Тарифные планы](https://nexcmp.com/ru/docs/catalog/plans/). | | `ai_provider` | AI-провайдер панели, используемый клиентскими AI Chat и AI Agent. | [AI provider](https://nexcmp.com/ru/docs/ai/ai-providers/). | | `legal` | Текст условий обслуживания и конфиденциальности для каждого языка (`en`, `vi`). | [Юридические страницы](https://nexcmp.com/ru/docs/customers/legal/). | Порядок применения соответствует порядку выше: элементы инфраструктуры перед тарифными планами. ## Правила, о которых следует помнить {#rules-to-remember} - **Идемпотентность.** Повторное применение того же файла ничего не меняет во второй раз. `plan` показывает "No changes". - **Никаких удалений.** Файл никогда не удаляет зону, тарифный план или настройку. Удаление записи из файла оставляет панель без изменений. - **Обычные правила безопасности продолжают действовать.** Из командной строки каждое изменение проходит через те же проверки, что и изменение через API: области действия и правила IP. Изменение, требующее подтверждения (например, глобальный переключатель), отображается в `pending` с предпросмотром вместо применения, если только вы не передадите `--confirm-billing`, подтверждающий их все. - **AI-клиенты не могут разблокировать биллинг.** Когда `config_apply` вызывается MCP-клиентом, `confirm_billing` игнорируется; финансовые изменения ожидают вас. - **Проверяйте перед применением.** JSON Schema описывает каждое поле. Укажите ее в редакторе или передайте AI, чтобы он сформировал корректный YAML: `https://cloud.example.com/v1/admin/agent/config/schema.json` (доступна для публичного чтения). ### Разделы биллинга {#billing-sections} `payments`, `currency` и `plans` изменяют цены или пути движения средств. `nexcmp config apply --yes` **пропускает** их, если вы не добавите `--confirm-billing`; в этом случае они перечисляются в `skipped` ("billing section - pass confirm_billing"). Этот флаг служит вашим подтверждением: с ним каждое изменение биллинга в файле (и любое другое изменение, требующее подтверждения) применяется без повторного запроса. Сначала выполните `plan` и ознакомьтесь с каждой строкой, отмеченной `$`. Когда тот же файл применяется AI (инструмент `config_apply` в MCP-клиенте или AI Chat), флаг игнорируется, а финансовые изменения ожидают вашего одобрения. ## Использование страницы Import/Export {#use-the-import-export-page} 1. Перейдите в **System › Settings › Import/Export**. 2. В разделе **Export** нажмите **Get current configuration**, затем **Download .yaml**, чтобы сохранить `nexcmp.yaml`. Секретные данные отображаются в виде заполнителей. 3. В разделе **Import** выберите файл, перетащите его в поле или вставьте YAML. 4. Необязательно: откройте **Secrets that come with it (not in the file)** и добавьте имя и значение для каждой ссылки, например `smtp_password`. 5. Нажмите **Preview changes**. Таблица группирует изменения по разделам; разделы, связанные с финансами, помечены тегом "Money-related". Снимите отметку с разделов, которые вам не нужны. 6. Если в списке есть разделы, связанные с финансами, отметьте **Also apply money-related changes (prices, payment gateways, balances)**. Без этой отметки они будут пропущены. 7. Нажмите **Apply selected**. В результате будет показано, что было применено, пропущено или завершилось ошибкой. Изменение, требующее подтверждения, отображается в виде карточки; нажмите на ней **Confirm**. Кнопка **JSON Schema** в правом верхнем углу открывает схему. ![Страница Import/Export с карточкой экспорта и карточкой импорта с экспортированным YAML](https://nexcmp.com/ru/docs/images/configure-with-ai/config-as-code-01-import-export.webp) ![Таблица предварительного просмотра изменений, сгруппированных по разделам, с тегом биллинга и кнопкой Apply selected](https://nexcmp.com/ru/docs/images/configure-with-ai/config-as-code-02-preview.webp) ## Запуск любого инструмента из командной строки {#run-any-tool-from-the-command-line} `nexcmp admin` запускает те же инструменты, что и AI-ассистенты ([список инструментов](https://nexcmp.com/ru/docs/configure-with-ai/mcp-admin/#tools)), и выводит 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"}}' ``` Аргументы передаются как пары `key=value` (значения парсятся как JSON, если это возможно, иначе как текст) или один объект `--json '{...}'`. Если действие требует подтверждения, команда выводит предпросмотр и завершается с кодом 3 и сообщением «Nothing changed». Проверьте предпросмотр, затем выполните ту же команду с флагом `--yes` для применения. При запуске от root команда получает 15-минутный ключ со всеми областями видимости (scopes), поэтому шаг подтверждения служит защитой; с флагом `NEXCMP_KEY` применяются собственные области видимости ключа. ## Проверка {#verify} 1. `sudo nexcmp config plan -f nexcmp.yaml` сразу после `apply --yes` выводит «No changes». 2. В панели администратора на измененных страницах отображаются новые значения, а список изменений доступен в **Logs › Admin actions**. 3. Повторное применение того же файла ничего не меняет. ## Ограничения и примечания {#limits-notes} - Файл охватывает перечисленные выше настройки, но не клиентов, серверы, счета или источники инфраструктуры (подключения CloudStack и Proxmox). Подключайте их через [AI Chat](https://nexcmp.com/ru/docs/configure-with-ai/ai-chat-in-admin/) или страницы панели администратора. - Зоны и тарифы сопоставляются по `slug`. Не переименовывайте slug в файле: он будет создан как новый элемент. - Нельзя изменить размер тарифа, который уже используется клиентами; вместо этого создайте новый тариф. - Храните экспортированные файлы в тайне, даже если они не содержат секретных данных: в них указаны ваши цены, адреса и названия аккаунтов. ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | `missing version: 1` | Файл не начинается с `version: 1` | Добавьте его. | | `unsupported version 2` | В файле указана другая версия | Эта панель поддерживает только версию 1. | | `unknown section 'x' (known: ...)` | Ключ верхнего уровня написан с ошибкой или не поддерживается | Используйте разделы, указанные выше. | | `YAML error: ...` | Некорректный YAML (отступы, знаки табуляции) | Исправьте строку, указанную в сообщении. | | `config is larger than 1 MB` | Файл слишком большой | Разделите его и используйте `--section`. | | `no API key: set NEXCMP_KEY=ak_... or run as root on the server` | Команда не нашла ключ | Запустите с `sudo` или экспортируйте `NEXCMP_KEY` и сохраните ее при вызове через sudo. | | `panel not reachable` | Служба панели не запущена на стандартном порту | Проверьте `sudo nexcmp status`. | | Строки биллинга под `skipped` | Для разделов биллинга требуется `--confirm-billing` | Добавьте этот флаг и сначала проверьте строки `$`. | | Элементы под `pending` | Изменение требует подтверждения | Откройте **API & AI agents** или результаты Import/Export и нажмите **Confirm** на карточке. | | Секретное значение не обновилось | Значение `NEXCMP_SECRET_` не было задано, поэтому сохраненный секрет остался без изменений | Экспортируйте переменную и примените снова. | | Запись под `errors` с HTTP 403 `insufficient_scope` | У ключа нет необходимой области видимости (scope) для этого раздела | Используйте ключ с нужным scope или запустите от root. | | Запись под `errors` с HTTP 403 `demo_read_only` | Демо-панель | Примените на рабочей установке. | --- # Примеры промптов {#example-prompts} > **Где найти в панели:** AI Chat (`/agent`) или плавающая кнопка **Ask AI** на любой странице панели. Эти же промпты работают в любом AI-клиенте, подключенном через [MCP](https://nexcmp.com/ru/docs/configure-with-ai/mcp-admin/). ## Назначение {#what-it-does} Эти примеры показывают, как формулировать запросы. Для каждого промпта описано, что ассистент делает в фоновом режиме, какие scope ему требуются (для внешнего клиента или ключа) и где потребуется ваше подтверждение. Замените примеры значений своими данными. ::: tip Никогда не вводите секретные данные в текст чата Для паролей, API-ключей и токенов используйте поле **Secret** рядом со строкой ввода AI Chat ([подробнее](https://nexcmp.com/ru/docs/configure-with-ai/ai-chat-in-admin/#secrets)). AI видит только плейсхолдер секрета, а не само значение. При использовании внешнего AI-клиента секрет проходит через него, поэтому безопаснее вводить его в панели управления. ::: ## Проверка текущего состояния {#check-where-you-are} ```text Check my setup progress and tell me the next three things to do, in order. ``` Ассистент вызывает `setup_checklist` и `system_health` (scope `admin:read`) и отвечает на основе реального состояния системы. См. [Чек-лист настройки](https://nexcmp.com/ru/docs/configure-with-ai/setup-checklist/). ## Первоначальная настройка {#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. ``` Это аналогично MCP-промпту `initial-setup`. Требуется `admin:read`, а также scope для подтверждаемых вами шагов. Для каждого изменения в AI Chat будет отображаться карточка подтверждения. ## Добавление кластера 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. ``` Что происходит: 1. Ассистент запросит ID токена API (`user@realm!tokenid`) и его секрет. Введите секрет в поле **Secret**. Сначала создайте токен с ограниченными правами: [Proxmox VE](https://nexcmp.com/ru/docs/infrastructure/proxmox/). 2. Он вызывает `proxmox_add`, `proxmox_test`, `zone_create` и `proxmox_attach_zone`. 3. Он предлагает тарифы с помощью `plans_from_offerings` и ожидает вашего подтверждения (см. следующий пример). Scope: `infra:write`, `secrets:write`, `catalog:write`, `admin:read`. ## Создание тарифной сетки с маржой 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. ``` Ассистент вызывает `plans_from_offerings` с `margin_pct` 40 и вашей себестоимостью. Маржа — это доля прибыли в цене продажи: при 40% тариф с себестоимостью $60 продается за $100. Первый вызов возвращает только предпросмотр. После вашего подтверждения инструмент вызывается повторно с `apply=true`: тарифы создаются за один шаг и запрашивается одно подтверждение, так как изменяются цены. Для Proxmox используются `backend_id` и стандартный набор конфигураций (1, 2, 2 и 4 vCPU). Scope: `catalog:write`, `admin:read`. См. [Тарифы](https://nexcmp.com/ru/docs/catalog/plans/). ![Ответ AI Chat с таблицей предпросмотра тарифов с себестоимостью, ежемесячной и почасовой ценой](https://nexcmp.com/ru/docs/images/configure-with-ai/example-prompts-01-plan-preview.webp) ## Настройка почты и отправка тестового письма {#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. ``` Ассистент вызывает `smtp_get`, `smtp_configure` и `smtp_test` и сообщает, было ли принято сообщение. Scope: `settings:write`, `secrets:write`. См. [SMTP и шаблоны писем](https://nexcmp.com/ru/docs/administration/smtp-and-emails/). ## Настройка 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` всегда выполняется в два этапа: вы видите предпросмотр со скрытыми значениями секретов и подтверждаете его. Затем `payment_test` проверяет учетные данные в Stripe. Scope: `billing:write`, `secrets:write`. Переключайтесь в рабочий режим только после тестового платежа. См. [Stripe](https://nexcmp.com/ru/docs/billing/stripe/). ## Включение оповещений в 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. ``` Ассистент вызывает `telegram_configure` и `telegram_test`. Scope: `settings:write`, `secrets:write`. См. [Уведомления в Telegram](https://nexcmp.com/ru/docs/administration/telegram-notifications/). ## Поиск клиента и пополнение баланса {#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. ``` Ассистент вызывает `customers_search` и `customer_get` (только чтение), затем `customer_adjust_balance` с `delta_cents` 1000 и указанием причины. Для этого **всегда** требуется ваше подтверждение: в карточке подтверждения отображается «changes a customer balance», а также сумма и причина, которая будет записана в журнал аудита. Scope: `admin:read`, `billing:write`. ## Экспорт конфигурации {#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. ``` Ассистент вызывает `config_export`. Секреты заменяются ссылками `secret://`. Сохраните результат как `nexcmp.yaml` и поместите его в систему контроля версий. См. [Конфигурация как код](https://nexcmp.com/ru/docs/configure-with-ai/config-as-code/). Scope: `admin:read`. ## Как писать эффективные промпты {#write-good-prompts} - Указывайте цель и фактические данные: имена, цены, адреса электронной почты. Не вставляйте секретные данные. - Сначала запрашивайте предварительный просмотр для любых действий, связанных с расходами или удалением данных. - Просите ассистента «прочитать текущее значение перед его изменением». Встроенные инструкции уже содержат это правило. - Если ответ кажется неверным, спросите «какой инструмент был вызван и с какими аргументами?». Карточки инструментов в AI Chat показывают и то, и другое. ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | Ассистент сообщает, что у него нет инструмента для этого действия | Для этого инструмента не предоставлены права доступа или действие закрыто для AI | Проверьте [Admin API keys](https://nexcmp.com/ru/docs/configure-with-ai/admin-api-keys/#what-a-key-can-never-do) или выполните действие в панели администратора. | | Запрашивается ввод пароля | Модель проигнорировала инструкции | Отклоните запрос; используйте поле Secret или введите значение в панели администратора. | | После команды «do it» ничего не меняется | Изменения ожидают вашего подтверждения | Прокрутите страницу до карточки подтверждения и нажмите **Confirm**. | | Планы были созданы с неожиданной ценой | В запросе были неверно указаны затраты или маржа | Отредактируйте планы на странице Plans или попросите ассистента пересчитать цены; изменение цен требует подтверждения. | --- # Чек-лист прогресса настройки {#setup-progress-checklist} > **Где в панели управления:** Overview › Dashboard (`/`), карточка **Setup progress** вверху. Пустые списки в Plans, Customers, Zones, Payments и Infrastructure показывают ту же подсказку. ## Назначение {#what-it-does} В новой установке необходимо настроить десять параметров, прежде чем первый клиент сможет оформить заказ и оплатить его. Карточка **Setup progress** проверяет их по реальной конфигурации, показывает количество выполненных шагов, указывает **следующий шаг** и дает ссылку на соответствующую страницу. Если подключен источник AI, кнопка **Do it for me** открывает [AI assistant](https://nexcmp.com/ru/docs/configure-with-ai/ai-chat-in-admin/) с готовым запросом для этого шага. Ассистент (как и любой AI-клиент через [MCP](https://nexcmp.com/ru/docs/configure-with-ai/mcp-admin/)) может считывать этот же список с помощью инструмента `setup_checklist`. ## Десять шагов {#the-ten-steps} | # | Шаг | Считается выполненным, если | Где настраивается | |---|---|---|---| | 1 | Лицензия активна | Лицензия активирована для вашего домена | System › Admin › License & updates (`/license`). См. [Лицензия и покупка](https://nexcmp.com/ru/docs/getting-started/license-and-purchase/). | | 2 | Подключить источник инфраструктуры | Подключен CloudStack или добавлен хотя бы один кластер Proxmox VE | Infrastructure › Cloud provider › Providers (`/infra/providers`). См. [CloudStack](https://nexcmp.com/ru/docs/infrastructure/cloudstack/) и [Proxmox VE](https://nexcmp.com/ru/docs/infrastructure/proxmox/). | | 3 | Создание зоны | Существует хотя бы одна зона | Infrastructure › Datacenter › Zone (`/infra/zones`). См. [Зоны](https://nexcmp.com/ru/docs/infrastructure/zones/). | | 4 | Шаблоны ОС | Включен хотя бы один шаблон | Services › Virtual Machines › Plans & pricing, вкладка Templates (`/vm/catalog?tab=templates`). См. [Шаблоны ОС](https://nexcmp.com/ru/docs/infrastructure/templates/). | | 5 | Создать планы | Включен хотя бы один план | Services › Virtual Machines › Plans & pricing (`/vm/catalog`). См. [Планы и цены](https://nexcmp.com/ru/docs/catalog/plans/). | | 6 | Настроить платежи | Настроены Stripe, PayPal, криптовалюта или банковский перевод | Finance › Payment channels (`/payments`). См. [Payment channels](https://nexcmp.com/ru/docs/billing/payment-channels/). | | 7 | Email (SMTP) | Настроена исходящая почта | System › Settings › Email (`/settings/email`). См. [SMTP и шаблоны писем](https://nexcmp.com/ru/docs/administration/smtp-and-emails/). | | 8 | Брендинг | Загружен логотип или название бренда изменено со значения по умолчанию | System › Settings › Brand (`/settings/branding`). См. [Брендинг](https://nexcmp.com/ru/docs/customers/branding/). | | 9 | Условия и конфиденциальность | Заполнен хотя бы один юридический документ | System › Settings › Legal (`/settings/legal`). См. [Юридические страницы](https://nexcmp.com/ru/docs/customers/legal/). | | 10 | Оформить тестовый заказ | Создан хотя бы один заказ | Оформите заказ от лица клиента в клиентском портале, чтобы убедиться в сквозной работоспособности; карточка ведет на страницу Billing (`/billing`). | На карточке отображаются `done/total` (например, 6/10), индикатор выполнения, следующий шаг с кнопкой **Open** и, если подключен источник AI, кнопка **Do it for me**. Нажмите на шаг, чтобы перейти на соответствующую страницу. Рядом с шагом небольшая ссылка открывает соответствующую страницу документации; для некоторых шагов также отображаются подробности, например «2 zone(s)». ![Карточка прогресса настройки на Overview: выполнено три из десяти шагов, кнопки Open и Do it for me](https://nexcmp.com/ru/docs/images/configure-with-ai/setup-checklist-01-card.webp) ## Использование {#use-it} 1. Откройте Overview. Карточка находится вверху. С помощью стрелки ее можно свернуть; панель сохраняет ваш выбор в браузере. 2. Нажмите **Open**, чтобы перейти на страницу следующего шага, или нажмите **Do it for me**. 3. При нажатии **Do it for me** открывается ассистент с запросом вроде «Предложите таблицу начальных тарифов на основе моих предложений с маржой 40%, покажите предпросмотр перед созданием». Ответьте на его вопросы, затем проверьте и нажмите **Confirm** на каждой карточке. См. [AI Chat в панели администратора](https://nexcmp.com/ru/docs/configure-with-ai/ai-chat-in-admin/). 4. После выполнения всех десяти шагов карточка скрывается. ### Пустые списки {#empty-lists} Когда разделы Plans, Customers, Zones, Payments или Infrastructure пусты, на странице отображается блок **Next step** с пояснением, кнопкой действия, **Do it for me** и ссылкой на документацию, поэтому вы никогда не увидите пустую таблицу. ![Пустая страница Plans с пояснением к следующему шагу и кнопкой Do it for me](https://nexcmp.com/ru/docs/images/configure-with-ai/setup-checklist-02-empty.webp) ## Запрос своими словами {#ask-for-it-in-your-own-words} Использовать карточку необязательно. В AI Chat или любом подключенном AI-клиенте вы можете спросить: ```text Check my setup progress and take me through the open steps, one at a time. ``` Это также промпт MCP `initial-setup`. Ассистент вызывает `setup_checklist`, объясняет важность каждого открытого шага, запрашивает необходимые данные и применяет соответствующий инструмент. Необходимые scopes: `admin:read` для чтения списка плюс scope шага, который вы хотите выполнить. См. [Примеры запросов](https://nexcmp.com/ru/docs/configure-with-ai/example-prompts/). ## Проверка {#verify} 1. После завершения шага счетчик на карточке увеличится при следующей загрузке Overview. 2. В ассистенте `setup_checklist` возвращает те же значения, с `done: true` на завершенном шаге. ## Ограничения и примечания {#limits-notes} - Проверки оценивают только сохраненные данные, а не их работоспособность. Настроенный шлюз считается готовым, даже если тест завершился ошибкой. Используйте кнопки **Test** на каждой странице и инструмент `system_health` при возникновении неполадок. - Карточка доступна только администраторам. - Для работы **Do it for me** требуется подключенный источник AI в разделе System › Settings › AI accounts; без него отображается только **Open**. - Эти десять шагов одинаковы для любой установки; шаг, который вы не планируете использовать (например, платежи в частном облаке), все равно считается незавершенным. ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | Карточка отсутствует | Все десять шагов выполнены, либо карточку не удалось загрузить | Перезагрузите Overview. Отправьте `setup_checklist` в AI Chat, чтобы проверить состояние. | | Шаг остается незавершенным после выполнения | Сохранение не завершилось или условие еще не выполнено (например, шаблон существует, но отключен) | Откройте страницу шага и сверьтесь с таблицей выше. | | Branding остается открытым после смены логотипа | Branding засчитывается, если загружен логотип или название бренда отличается от «NexCMP» по умолчанию | Загрузите логотип или укажите собственное название. | | **Do it for me** ничего не делает | Не подключен источник AI или используется демо-панель | Подключите источник в AI accounts. | --- # SMTP и шаблоны писем {#smtp-and-e-mail-templates} > **В панели администратора:** System › Settings › Email (`/settings/email`) — вкладки **SMTP** и **Email templates**. Журнал доставки: Overview › Support › Sent emails (`/support/emails`). ## Назначение {#what-it-does} NexCMP отправляет письма для подтверждения регистрации, сброса пароля, уведомления «VM ready» (с первоначальным паролем), счета, оповещения о низком балансе, продлениях, пополнениях, ответы техподдержки и многое другое. Все они отправляются через **одну предоставленную вами учетную запись SMTP**. Сообщения и шаблоны доступны на 16 языках; используется язык клиента. ## Требования {#requirements} | Параметр | Требование | |---|---| | SMTP-сервер | Хост, порт и учетные данные любого провайдера (собственный сервер, Brevo, Amazon SES, Mailgun, Google Workspace …) | | Сеть | Исходящий TCP-трафик от сервера NexCMP к хосту и порту SMTP (587 STARTTLS, 465 TLS или 25) | | Домен отправителя | Домен под вашим управлением с опубликованными для провайдера записями **SPF и DKIM**, а также записью DMARC | | Разрешения | Учетной записи SMTP должна быть разрешена отправка с адреса **From** | ::: warning Доставляемость Письма вроде «VM ready» содержат пароли. Если SPF/DKIM/DMARC домена отправителя не настроены для SMTP-провайдера, они попадут в спам. На странице есть напоминание об этом. ::: ## Подготовка почтового провайдера {#prepare-the-e-mail-provider} 1. В панели провайдера добавьте и подтвердите домен отправителя (например, `example.com`). 2. Опубликуйте DNS-записи SPF, DKIM и DMARC, указанные провайдером. 3. Создайте пользователя SMTP (или ключ API-SMTP) и сохраните хост, порт, имя пользователя и пароль. ## Подключение в NexCMP {#connect-in-nexcmp} 1. Откройте **System › Settings › Email**, вкладка **SMTP**. 2. Заполните форму: | Поле | Пример | Примечания | |---|---|---| | Хост | `smtp.example.net` | SMTP-сервер | | Порт | `587` | | | Безопасность | STARTTLS (587) | Выберите режим, требуемый вашим провайдером | | Имя пользователя | `smtp-user` | | | Пароль | (скрыто) | Только для записи: на странице отображается лишь то, задано ли значение | | Email отправителя | `no-reply@example.com` | Должен быть авторизован у провайдера | | Имя отправителя | `Example Cloud` | По умолчанию совпадает с названием вашего бренда | | Reply-To (необязательно) | `support@example.com` | Куда приходят ответы клиентов | ![Вкладка SMTP в разделе Settings, Email с полями хоста, порта, безопасности, имени пользователя, отправителя и кнопкой Send test](https://nexcmp.com/ru/docs/images/administration/smtp-and-emails-01-smtp.webp) 3. Нажмите **Save**, затем **Send test** и укажите свой адрес. Настройки сохраняются в файле с ограниченным доступом (`smtp.json`, права 0600), и только фоновый воркер `nexcmp-vmd` отправляет почту; веб-служба лишь ставит её в очередь. ## Проверка {#verify} - Тестовое сообщение поступает во входящие (проверьте также папку со спамом). В исходном тексте письма проверьте `dkim=pass` и `spf=pass`. - Откройте **Support › Sent emails**: у каждого сообщения отображаются статус (queued, sent, failed) и результат доставки. При сбоях отправка повторяется до 3 раз. - Зарегистрируйте тестового клиента на портале и убедитесь, что письмо для подтверждения пришло. ## Редактирование шаблонов писем {#edit-e-mail-templates} На вкладке **Email templates** перечислены все шаблоны по ключам с указанием доступных языков (например, `verify_email`, `reset_password`, `vm_ready`, `invoice_paid`, `low_balance`, `topup_received`, `ticket_reply`, `scale_up` …). 1. Нажмите на шаблон и выберите язык. 2. Отредактируйте тему и текст письма. Переменные заполняются при постановке сообщения в очередь. 3. Сохраните изменения. Они применятся **немедленно** ко всем сообщениям, поставленным в очередь позже. ![Вкладка Email templates со списком ключей шаблонов и их языков](https://nexcmp.com/ru/docs/images/administration/smtp-and-emails-02-templates.webp) ## Ограничения и примечания {#limits-and-notes} - Один SMTP-аккаунт на установку. Клиенты реселлеров получают письма через этот же аккаунт, если для реселлера не настроено иное. - Действуют лимиты отправки провайдера; NexCMP не ограничивает скорость, кроме повторных попыток при ошибках. - Без SMTP панель работает, но клиенты не смогут подтвердить регистрацию и сбросить пароль. ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | Тестовое письмо не приходит | Неверные учетные данные, порт заблокирован, отправитель не авторизован | Проверьте ошибку SMTP в `journalctl -u nexcmp-vmd`; попробуйте порт 587 со STARTTLS; проверьте адрес From на стороне провайдера. | | Письма попадают в спам | Записи SPF/DKIM/DMARC отсутствуют или настроены некорректно | Добавьте записи провайдера и отправляйте письма с этого домена. | | Статус «failed» в Sent emails | Провайдер отклонил сообщение | Откройте строку, чтобы посмотреть ответ провайдера. | | Поле пароля пустое после сохранения | Штатное поведение (только для записи) | После сохранения пароля отображается метка «current: set». | --- # Telegram и оповещения администратора {#telegram-and-admin-alerts} > **Где найти в панели:** System › Settings › Admin alerts (`/settings/alerts`). Ссылки на поддержку: Customers › Support › Tickets (`/support/tickets`), вкладка **Settings**. ## Назначение {#what-it-does} NexCMP оповещает **вас** — оператора — о важных событиях, регистрации клиентов или зачислении средств. Уведомления отправляются в один или несколько **каналов**: Telegram, вебхук или e-mail. В каналы администратора отправляются события: сбой развертывания, отсутствие VM, сбой сети, менее 30 свободных IP, истекающая услуга (за 1 час), диспут в Stripe, остановка воркера, превышение порога RAM в кластере, новая регистрация клиента и зачисление депозита. Клиентские события надежно ставятся в очередь и повторяются с увеличивающимся интервалом (от 30 секунд до 1 часа), пока Telegram их не примет. ## Требования {#requirements} | Параметр | Требование | |---|---| | Telegram | Бот, созданный через **@BotFather** (токен), и **chat ID** группы или пользователя, которые должны получать сообщения | | Сеть | Исходящие HTTPS-запросы к `api.telegram.org` | | Вебхук (альтернатива) | Конечная точка HTTPS, принимающая полезную нагрузку уведомлений | ## Подготовка Telegram {#prepare-telegram} 1. В Telegram откройте **@BotFather**, отправьте `/newbot`, выберите имя и скопируйте **bot token** (`123456789:AA...`). 2. Создайте группу, добавьте в нее бота и отправьте любое сообщение. 3. Найдите **chat ID**: откройте `https://api.telegram.org/bot/getUpdates` в браузере и найдите `chat.id` (ID групп начинаются с `-`). ## Подключение в NexCMP {#connect-in-nexcmp} 1. Откройте **System › Settings › Admin alerts**. 2. В блоке **Add channel** выберите **Type: Telegram**, укажите chat ID в поле **Destination** и токен в поле **Secret (bot token)**. Нажмите **Add**. 3. Убедитесь, что переключатель **Send admin Telegram (VM module)** включен; в строке *VM module status (read-only)* отображается «on». ![Страница Admin alerts с формой Add channel, настроенной для Telegram](https://nexcmp.com/ru/docs/images/administration/telegram-notifications-01-channel.webp) ## Проверка {#verify} Канал появится в списке **Configured channels**. Вызовите событие (например, зарегистрируйте тестового клиента), и сообщение придет в группу. Если ни один канал не настроен, страница предупреждает: «Without a channel, attacks will go unnoticed», а события Telegram в журнале фиксируются только локально. ## Кнопки связи для клиентов {#support-shortcuts-for-customers} Виджет поддержки клиентов может отображать кнопки **Telegram** и **Zalo**. Они скрыты, пока не настроены в параметрах поддержки: укажите ссылку `https://t.me/...` для Telegram и ссылку или QR-код для Zalo. Принимаются только ссылки `https://`. Чат поддержки также может отправлять уведомления в вашу группу Telegram с вопросом и черновиком ответа — см. [AI Chat](https://nexcmp.com/ru/docs/ai/ai-chat/). ## Ограничения и примечания {#limits-and-notes} - Токен бота сохраняется в настройках канала и больше никогда не отображается. - Для отправки событий Telegram используется первый активный канал Telegram, у которого заданы и получатель, и токен. ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | Сообщения не приходят | Неверный chat ID, бот не добавлен в группу или боту еще не отправляли сообщений | Проверьте ID еще раз через `getUpdates`; сначала отправьте сообщение боту или в группу. | | Работает некоторое время, затем перестает | Токен отозван в BotFather | Создайте новый токен и обновите настройки канала. | | `Telegram: no channel` в журналах | Нет активного канала Telegram | Добавьте канал, как описано выше. | --- # Журнал аудита и активность {#audit-log-and-activity} > **Где найти в панели управления:** System › Logs › Activity (`/logs`), Admin actions (`/logs/admin`), Console (`/logs/console`), Login (`/logs/logins`), VM events (`/logs/vm-events`); Overview › Support › Sent emails. NexCMP фиксирует каждое важное действие. Используйте страницу **Activity** как общую хронологию, а остальные вкладки — для детального поиска. ## Вкладки {#tabs} | Вкладка | Содержимое | |---|---| | **Activity** | Единая хронология по всем источникам: действия администраторов, события VM, входы в систему, реферальная программа и системные ошибки | | **Admin actions** | Изменения, внесенные администраторами (например, `customer.block`, `customer.delete`), с указанием их IP-адресов | | **Console** | Входы в консоль администратора и системные запросы, такие как запрос на обновление | | **Login** | Успешные и неудачные попытки входа клиентов | | **VM events** | Шаги развертывания, создание, смена пароля, удаление и другие события жизненного цикла каждой виртуальной машины | ## Структура записи {#reading-a-row} Столбцы: **Time**, **Source**, **Level**, **Actor** (инициатор), **Target**, **Services**, **Action** (код события, например `customer.delete`) и **Details**. Нажмите **Open**, чтобы просмотреть запись целиком. ![Страница Activity с фильтрами по источнику, сайту и сервису над лентой событий](https://nexcmp.com/ru/docs/images/administration/audit-log-01-activity.webp) ## Фильтрация и поиск {#filter-and-search} 1. Выберите **source**, **site** и **service** в выпадающих списках. 2. Задайте диапазон **From date** / **To date**. 3. Введите код события (например, `customer.block` или `destroy`) в поле поиска — поиск по активности проверяет код события. ## Хранение и экспорт {#retention-and-exports} Записи хранятся в базах данных NexCMP в `/var/lib/nexcmp` и включаются в [резервные копии](https://nexcmp.com/ru/docs/getting-started/backup-and-restore/). Срок хранения зависит от журнала: попытки входа клиентов старше 180 дней и журналы запросов по API-ключам клиентов старше 60 дней очищаются. Аудит API-ключей администратора сохраняет примерно до 200,000 последних записей. Эти ограничения не означают такой же срок хранения для единой ленты активности. ## Типовые сценарии {#common-uses} | Вопрос | Где искать | |---|---| | Кто приостановил этого клиента? | Admin actions, поиск `customer.block` | | Почему исчезла VM? | VM events, фильтр по ID VM; также Activity | | Получил ли клиент письмо? | Overview › Support › Sent emails | | Когда запрашивалось последнее обновление? | Вкладка Console | --- # Безопасность {#security} > **В панели управления:** System › Admin › Console security (`/account`), Admin users (`/users`); System › Settings › Customer logins (`/settings/login`). ## Панель администратора {#admin-console} ### Двухфакторная аутентификация (TOTP) {#two-factor-authentication-totp} Консоль доступна из Интернета, поэтому включите TOTP. 1. Перейдите в **System › Admin › Console security**. 2. В блоке **Two-factor authentication (TOTP)** нажмите **Start setup**. 3. Отсканируйте QR-код в Google Authenticator, Authy, 1Password или Bitwarden и введите 6-значный код. ### Разрешенные диапазоны IP для консоли {#allowed-console-ip-ranges} В блоке **Allowed console IP ranges** укажите по одному IP или CIDR (IPv4 или IPv6) на строку. **Пустое значение разрешает доступ отовсюду.** Вне этого диапазона блокируются и вход, и admin API. ::: warning Не заблокируйте собственный доступ На странице показан ваш текущий IP-адрес: он обязательно должен входить в новый список. Используйте **+ Add my IP**. Если доступ все же потерян, воспользуйтесь [экстренным доступом](https://nexcmp.com/ru/docs/getting-started/cli-reference/#emergency-access) с сервера. ::: ### Смена пароля {#change-password} Заполните поля **Current password**, **New password** и **Confirm new password**. Используйте длинный уникальный пароль (от 12 символов; мастер установки требует не менее 12 символов для первого администратора). ### Учетные записи и роли администраторов {#administrator-accounts-and-roles} Перейдите в **System › Admin › Admin users** и нажмите **+ Create account**. | Роль | Доступ | |---|---| | `admin` | Полный доступ к admin API | | `staff` | Только чтение во всей системе | | `user` | Просмотр ресурсов одного клиента только для чтения | Учетная запись root создается в [мастере первоначальной настройки](https://nexcmp.com/ru/docs/getting-started/setup-wizard/). Действия со строкой: **Edit**, **Reset PW**, **Key**, **Delete**. Пароли хранятся в виде хешей с солью; изменение или блокировка аккаунта сразу завершает его сессии. ## Вход для клиентов {#customer-sign-in} Перейдите в **System › Settings › Customer logins**. | Настройка | Назначение | |---|---| | **Google sign-in** | Включите, затем укажите OAuth client ID и secret. Скопируйте **Callback URL**, показанный на странице, в раздел *Google Cloud Console › APIs & Services › Credentials › OAuth client ID › Authorized redirect URIs*. Нажмите **Test configuration**. | | **Вход через GitHub** | Аналогично, в разделе *GitHub › Settings › Developer settings › OAuth Apps › Authorization callback URL* | | **Passkey** | Вход по отпечатку пальца, PIN-коду или аппаратному ключу; включен по умолчанию. Passkey привязаны к домену; каждый домен реселлера работает независимо. Укажите старый домен в *Legacy passkey Domain* после ребрендинга, чтобы клиенты получили подсказку | | **Повторная аутентификация при добавлении способов входа** | Запрашивать пароль повторно перед добавлением passkey или привязкой Google/GitHub (по умолчанию выключено) | | **Captcha** | Cloudflare Turnstile или Google reCAPTCHA при регистрации: включите, выберите провайдера, укажите site key и secret key | | **Блокировка почтовых доменов** | Один домен на строку (не более 2000). Совпадающие адреса отклоняются при регистрации с ошибкой `email_domain_blocked` | ![Страница «Customer logins» с настройкой входа через Google и callback URL](https://nexcmp.com/ru/docs/images/administration/security-01-customer-logins.webp) ### Встроенные политики {#built-in-policies} | Политика | Значение | |---|---| | Пароль клиента | Не менее 10 символов, буквы и цифры | | Сессия клиента | 30 дней; сессии «войти как клиент» длятся 1 час | | Подтверждение e-mail | Обязательно перед созданием VM, если в настройках продаж включен параметр *require e-mail verified* | | Защита от кардинга | Аккаунты с пополнением меньше минимального могут создавать лишь ограниченное число VM | ## Усиление безопасности сервера {#server-hardening} - Порт 3000 закрывается после первоначальной настройки и TLS; см. [Установка](https://nexcmp.com/ru/docs/getting-started/installation/#the-panel-port-3000). - Служба работает от имени непривилегированного пользователя `nexcmp` в изолированном окружении systemd. - Ключи API, платежные реквизиты и пароли SMTP хранятся в зашифрованном виде; мастер-ключ находится в `/var/lib/nexcmp/secrets` — защищайте [резервные копии](https://nexcmp.com/ru/docs/getting-started/backup-and-restore/). - Перед установкой релизы проверяются с помощью SHA-256 и подписи Ed25519. --- # Общие настройки {#general-settings} > **В панели управления:** System › Settings › General (`/settings`). Изменения вступают в силу немедленно (кэш 30 секунд). Страница содержит три раздела. ## Брендинг и URL {#branding-urls} | Поле | Назначение | |---|---| | Название бренда (e-mail, счета) | Отображается в письмах и счетах. Логотип и цвета настраиваются в [Branding](https://nexcmp.com/ru/docs/customers/branding/) | | Язык по умолчанию | Язык для новых посетителей | | Customer app URL | Публичный адрес портала, например `https://cloud.example.com` | | Console URL | Адрес службы консоли VM | | Admin URL | Ссылка, используемая при входе от имени клиента реселлера | | Partner console URL | Используется в ссылках приглашений, письмах реселлерам и при перенаправлении после пополнения | Мастер подставит эти значения из вашего домена; меняйте их только при переносе портала. ## Продавец и счета {#seller-invoicing} Указывается в каждом счете: | Поле | Пример | |---|---| | Юридическое лицо | Example Cloud Ltd | | ИНН / Налоговый номер | `TAX-000000` | | Адрес | 1 Example Street, New York | | Контактный e-mail | `billing@example.com` | | Префикс номеров счетов | `INV` (от 1 до 8 символов, A–Z и 0–9) | Ранее выставленные счета сохраняют исходные реквизиты продавца и номер; изменения действуют только на **новые** счета. ## Техобслуживание и регион {#maintenance-region} Включите **Customer app MAINTENANCE**, чтобы показать баннер и **заблокировать все операции записи для клиентов**, пока панель администратора продолжает работать. Укажите **Maintenance message**, которое увидят клиенты. Используйте этот режим при обновлении инфраструктуры. ![Страница General settings с полями названия бренда, языка по умолчанию и URL](https://nexcmp.com/ru/docs/images/administration/general-settings-01-general.webp) ## Другие страницы настроек {#other-settings-pages} | Страница | Руководство | |---|---| | Brand | [Брендинг](https://nexcmp.com/ru/docs/customers/branding/) | | Legal | [Юридическая информация](https://nexcmp.com/ru/docs/customers/legal/) | | Customer logins | [Security](https://nexcmp.com/ru/docs/administration/security/) | | Email | [SMTP и шаблоны писем](https://nexcmp.com/ru/docs/administration/smtp-and-emails/) | | Admin alerts | [Telegram и уведомления для администраторов](https://nexcmp.com/ru/docs/administration/telegram-notifications/) | | Провайдер ИИ | [AI-провайдеры](https://nexcmp.com/ru/docs/ai/ai-providers/) | --- # Сообщить об ошибке {#report-a-bug} > **В панели администратора:** Top bar › **Report a bug** (рядом с Docs; отображается только главному администратору). Обнаружили ошибку в NexCMP? Нажмите **Report a bug**, опишите проблему и отправьте ее. Отчет сразу поступает команде NexCMP в виде тикета к вашему лицензионному аккаунту — вам не нужно нигде дополнительно авторизоваться или вручную копировать файлы журналов. Функция доступна на любом тарифе: исправление ошибок включено как в NexCMP Free, так и в NexCMP Source. ::: info Отчеты об ошибках не являются обращениями в поддержку В NexCMP Free нет технической поддержки, поэтому используйте эту форму только для сообщений о неполадках в ПО. Помощь с настройкой и миграцией входит в [NexCMP Source](https://nexcmp.com/pricing). ::: ## Требования {#requirements} | Параметр | Что требуется | |---|---| | Версия | NexCMP 1.5.2 или новее | | Кто может отправлять | Основной аккаунт администратора. Аккаунты сотрудников (только для чтения), консоли реселлеров, клиенты и демо-режим отправлять отчеты не могут | | Лицензия | Активированная лицензия (Free или Source), действие которой не приостановлено | | Сеть | Сервер должен иметь доступ к `https://nexcmp.com` по HTTPS (тот же адрес, что используется для проверки лицензии и обновлений) | ## Отправка отчета {#send-a-report} 1. Нажмите **Report a bug** в верхней панели. На телефоне откройте меню и выберите **Report a bug**. 2. Введите короткую тему в поле **Subject**. 3. В поле **What happened** опишите ваши действия, полученный результат и то, что вы ожидали увидеть. 4. При необходимости укажите **шаги для воспроизведения**. 5. Выберите **Impact**: **Blocking** (работа заблокирована), **Major** (не работает ключевая функция) или **Minor** (незначительная или косметическая проблема). 6. Оставьте включенным переключатель **Attach diagnostics** (рекомендуется) и ознакомьтесь с блоком **What will be sent**. 7. Нажмите **Send report**. В 1.6.1 тело формы прокручивается, а кнопки действий остаются видимыми, в том числе на телефоне. Значения паролей после `password:` или `password=` маскируются без удаления остальной части отчета. Проверьте текст перед отправкой и исключите данные клиентов и учетные данные. ![Диалоговое окно Report a bug с темой, описанием, уровнем критичности и списком отправляемых данных](https://nexcmp.com/ru/docs/images/administration/report-a-bug-01-dialog.webp) После принятия отчета в диалоговом окне отобразится номер тикета и ссылка. Ответы команды будут приходить на email вашего лицензионного аккаунта на nexcmp.com, а сам тикет также появится в разделе **Support** при входе под аккаунтом владельца лицензии. ## Какие данные отправляются {#what-is-sent} В блоке **What will be sent** перед отправкой точно указано следующее: | Отправляемые данные | Подробнее | |---|---| | Введенный вами текст | Тема, описание, шаги воспроизведения и уровень критичности | | Версия, тариф, домен | Версия NexCMP, Free или Source, и домен вашей установки | | Текущая страница | Страница панели администратора, на которой вы находитесь, без параметров после `?` или `#` | | Браузер | Строка User-Agent вашего браузера (название, версия и операционная система), сокращенная до 200 символов | | Последние ошибки | До 5 последних ошибок на этой вкладке браузера. Для ошибок скрипта передается только текст сообщения, для сбойных запросов — только метод, путь и код статуса | Вы можете отключить **Attach diagnostics** — тогда будут отправлены только введенный вами текст, версия, тариф и домен. ## Какие данные никогда не передаются {#what-is-never-sent} - Пароли, токены, cookies и ключи API. Любые подобные значения в вашем тексте или в тексте ошибки маскируются (отображаются как `***` или `[redacted]`) на вашем сервере еще до отправки. - Содержимое запросов и ответов — для неудачных запросов записываются только метод, путь и статус. - Данные ваших клиентов (имена, email-адреса, заказы, счета) и их IP-адреса. - IP-адрес вашего браузера и любые файлы с вашего сервера. Как и при любой проверке лицензии, сервер лицензирования видит IP-адрес, с которого подключается ваш сервер. Тикет привязывается к вашей инсталляции с помощью токена лицензии, который уже хранится на сервере, поэтому версия, домен и инсталляция определяются сервером и не могут быть изменены из браузера. ## Лимиты {#limits} | Лимит | Значение | |---|---| | Тема | 150 символов | | Описание и шаги | 8 КБ суммарно | | Отчеты | 5 в час и 20 в день на всю инсталляцию | Повторная отправка одного и того же отчета (например, после сетевой ошибки) не создает второй тикет. ## Устранение неполадок {#troubleshooting} | Сообщение | Причина | Решение | |---|---|---| | Сначала активируйте лицензию | В инсталляции нет активированной лицензии | Откройте **License & updates** и выполните активацию, затем отправьте отчет снова | | Не удалось связаться с сервером лицензирования | Сервер не может подключиться к `nexcmp.com` | Проверьте исходящие HTTPS-подключения и DNS на сервере, затем снова нажмите **Send report** — введенный текст сохранится | | Слишком много отчетов об ошибках от этой инсталляции | Вы исчерпали лимит: 5 в час или 20 в день | Подождите и повторите попытку; новые сведения можно добавить в открытый тикет | | Действие лицензии приостановлено | Лицензия приостановлена или по ней был оформлен возврат | См. [Лицензия и покупка](https://nexcmp.com/ru/docs/getting-started/license-and-purchase/) | | Инсталляция отозвана | Инсталляция была отозвана на портале лицензий | Активируйте ее снова в разделе **License & updates** | | Не удалось обновить токен лицензии | Серверу не удалось обновить свой токен лицензии | Откройте **License & updates**, нажмите **Refresh** и отправьте отчет снова | | Нет кнопки Report a bug | Вы вошли под учетной записью сотрудника, реселлера или клиента либо находитесь в демо-режиме только для чтения | Войдите под учетной записью главного администратора | ::: tip Для AI-ассистента и API-ключей Ассистент в панели управления и ключи API администратора не могут отправлять отчеты об ошибках от вашего имени: для использования кнопки требуется вход пользователя с правами главного администратора. ::: --- # Ошибки установки {#installation-errors} Установщик останавливается при первой неустранимой проблеме и выводит красную строку с `✗`. Устраните причину и **повторите команду** — повторный запуск установщика безопасен. Информационные сообщения начинаются с `•`, успешно выполненные шаги — с `✓`. ## Проверки сервера {#machine-checks} | Сообщение | Причина | Решение | |---|---|---| | `must be run as root (sudo)` | Запуск не от имени root | Добавьте в начале команды `sudo` или выполните ее от root. | | `only Ubuntu 22.04/24.04 is supported (this host: …)` | Другой дистрибутив или версия | Используйте сервер с Ubuntu 22.04 или 24.04. | | `only x86_64 is supported` | ARM или другая архитектура процессора | Используйте сервер на базе x86_64. | | `requires ≥ 2 GB RAM (host has … MB)` | Недостаточно оперативной памяти | Добавьте RAM. | | `requires ≥ 8 GB free disk space on / (… GB available)` | Корневая файловая система почти заполнена | Освободите место или увеличьте `/`. | | `missing --license` / `missing --domain` | Первая установка без обязательных параметров | Укажите оба параметра — см. [Установка](https://nexcmp.com/ru/docs/getting-started/installation/#parameters). | | `unknown argument: …` | Опечатка в параметре | Проверьте написание; запустите с параметром `--help`. | | `apt-get failed (another apt/dpkg process, e.g. unattended-upgrades, may still be running)` | Менеджер пакетов заблокирован | Подождите несколько минут (чистая Ubuntu выполняет автоматические обновления после загрузки) и запустите снова. | | `… is a symlink — aborting` | `/opt/nexcmp` или `/etc/nexcmp` является символической ссылкой | Замените ее реальным каталогом — установщик отклоняет символические ссылки в целях безопасности. | ## Активация лицензии {#license-activation} | Сообщение | Причина | Решение | |---|---|---| | `cannot connect to https://nexcmp.com` | Нет исходящего HTTPS-соединения с сервером лицензий | Проверьте DNS, фаервол и прокси на сервере: `curl -I https://nexcmp.com`. | | `license activation failed (HTTP …): ` | Сервер лицензий отклонил ключ | Прочтите сообщение: неверный ключ, домен не соответствует лицензии, лицензия приостановлена или отозвана. Проверьте страницу лицензий на [nexcmp.com/licenses](https://nexcmp.com/licenses). | | `no release available for this license yet` | Для этой лицензии нет доступного для скачивания релиза | Свяжитесь с отделом продаж; см. [Поддержка](https://nexcmp.com/ru/docs/troubleshooting/support/). | ## Скачивание и проверка {#download-and-verification} | Сообщение | Причина | Решение | |---|---|---| | `failed to download release X` | Сетевая ошибка при скачивании | Запустите снова. | | `sha256 mismatch (… ≠ …)` | Файл поврежден при передаче или был изменен | Запустите снова; если ошибка повторяется, возможно, прокси изменяет загружаемые файлы — попробуйте из другой сети. | | `release X is unsigned — refusing to install` | Сервер не предоставил подпись | Ни в коем случае не обходите проверку; обратитесь в службу поддержки. | | `INVALID SIGNATURE for version X — aborting` | Подпись Ed25519 не проходит проверку | **Не** устанавливайте. Обратитесь в службу поддержки — это означает, что файл не является официальным релизом. | | `openssl failed to read public key` | Устаревшая или поврежденная версия OpenSSL | Обновите пакет `openssl`. | | `invalid version: …` | Непредвиденные данные от сервера | Запустите снова; обратитесь в службу поддержки, если проблема сохраняется. | ## Запуск службы {#service-start} | Сообщение | Причина | Решение | |---|---|---| | `service failed to start — check: journalctl -u nexcmp -n 50` | Панель не ответила на `/healthz` в течение 3 минут | Проверьте журнал. Распространенные причины: порт (по умолчанию 3000) уже занят (`ss -ltnp | grep 3000`) — выполните переустановку с `--port`; файлы принадлежат root в `/var/lib/nexcmp` — выполните `sudo nexcmp fix-owner`. | ## nginx и TLS {#nginx-and-tls} | Сообщение | Причина | Решение | |---|---|---| | `DNS does not point to (nor to Cloudflare) — skipping nginx/TLS` | A/AAAA-запись отсутствует или указана неверно | См. [DNS и Cloudflare](https://nexcmp.com/ru/docs/getting-started/dns-and-cloudflare/), затем запустите снова. | | `certbot could not get a certificate yet — re-run the installer once DNS has settled` | Сбой проверки Let's Encrypt (порт 80 заблокирован, DNS еще не обновился, лимит запросов) | Откройте порт 80, дождитесь распространения DNS, запустите снова. Проверьте `/var/log/letsencrypt/letsencrypt.log`. | | `certbot could not renew now — keeping the existing certificate` | Временный сбой обновления сертификата | Не критично; запустите снова позже. | | `nginx rejected the HTTPS configuration — kept the previous one (check: nginx -t)` | Конфликт с другим сайтом nginx (одинаковый `server_name`, дублирующиеся параметры) | Выполните `sudo nginx -t` и устраните конфликт, затем запустите снова. | | `apt-get could not install nginx` / `certbot` или `E: Failed to fetch … 404 Not Found` | Менеджер пакетов заблокирован, или индекс пакетов сервера устарел (типично для образов шаблонов, которые давно не обновлялись) | Выполните `sudo apt-get update`, дождитесь завершения всех остальных процессов apt, затем снова запустите установщик. | | `openssl could not create the self-signed certificate` | Проблема с OpenSSL | Обновите `openssl`; запустите снова. | ## После установки {#after-installation} | Симптом | Причина | Решение | |---|---|---| | Браузер не может открыть `https://` | DNS или TLS не готовы | `sudo nexcmp status`; используйте [аварийный доступ](https://nexcmp.com/ru/docs/getting-started/cli-reference/#emergency-access). | | `ERR_TOO_MANY_REDIRECTS` | Режим Cloudflare SSL **Flexible** | Установите **Full (strict)** — [подробнее](https://nexcmp.com/ru/docs/getting-started/dns-and-cloudflare/). | | Мастер сообщает, что «setup code» недействителен | Опечатка или код от предыдущей установки | Выполните `sudo nexcmp status` и скопируйте текущий код. | | Для лицензии отображается HTTP 421 | Владельцем файлов в `/var/lib/nexcmp` является root | `sudo nexcmp fix-owner`, затем `sudo systemctl restart nexcmp`. | --- # Ошибки обновления {#update-errors} > **В панели администратора:** System › Admin › License & updates (`/license`) Процесс обновления описан в разделе [Updating NexCMP](https://nexcmp.com/ru/docs/getting-started/updating/). Если блок Update или `sudo nexcmp update` сообщает об ошибке: | Сообщение | Причина | Решение | |---|---|---| | `update plan expired — renew on the license page to receive this feature release` | Дата «updates until» предшествует дате релиза. Исправления безопасности продолжают поступать; функциональные релизы — нет | Продлите на [nexcmp.com/licenses](https://nexcmp.com/licenses) ($99 в год для NexCMP Free), затем повторите проверку. ПО продолжит работать. | | `sha256 mismatch (downloaded …, expected …)` | Загруженный файл поврежден или изменен | Повторите попытку. Если ошибка повторяется, проверьте прокси на маршруте. | | `downgrade/same version rejected: X is not newer than Y` | Выбранная версия не новее запущенной | Никаких действий не требуется — у вас актуальная версия. | | `extraction failed / main binary missing` | Поврежден архив или переполнен диск | Проверьте `df -h`; повторите попытку. | | `systemctl restart failed` | Служба не смогла перезапуститься после замены бинарного файла | `journalctl -u nexcmp -n 80`; предыдущий бинарный файл сохранен как `/opt/nexcmp/bin/nexcmp.bak` — см. откат ниже. | | Ошибка сервера при обращении к серверу обновлений | Нет маршрута к `nexcmp.com` или истек токен лицензии | Проверьте исходящий HTTPS-трафик; нажмите **Check now** в блоке License. | ## Откат {#roll-back} Если новая версия работает некорректно: ```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 ``` Если миграция базы данных уже выполнена, также восстановите [резервную копию](https://nexcmp.com/ru/docs/getting-started/backup-and-restore/), сделанную перед обновлением. ## `sudo nexcmp update` сообщает, что не удается найти установщик {#sudo-nexcmp-update-says-it-cannot-find-the-installer} `nexcmp update` запускает установщик, поставляемый внутри установленного релиза (`/opt/nexcmp/releases//share/install.sh`). Если этот файл отсутствует, повторно выполните команду установки со страницы вашей лицензии. --- # FAQ {#faq} ## Лицензирование {#licensing} **Что произойдет, если срок действия лицензии истечет или сервер потеряет доступ к интернету?** Токен остается действительным в течение 14 дней и обновляется ежедневно. После этого клиенты не смогут создавать **новые** сервисы; работающие сервисы, биллинг и вход в систему продолжат функционировать. См. [License and purchase](https://nexcmp.com/ru/docs/getting-started/license-and-purchase/). **Будут ли поступать исправления безопасности после окончания срока подписки на обновления?** Да — обновления безопасности предоставляются всегда; для получения функциональных релизов требуется активная подписка. **Можно ли запустить NexCMP на втором сервере или домене?** Выполните активацию с помощью ключа и домена, зарегистрированных в лицензии — см. [License and purchase](https://nexcmp.com/ru/docs/getting-started/license-and-purchase/#moving-to-a-new-server-or-domain). ## Установка {#installation} **Требуются ли для NexCMP Docker, PostgreSQL или Redis?** Нет. Это единая программа с базами данных SQLite, работающая под управлением systemd от непривилегированного пользователя. См. [Requirements](https://nexcmp.com/ru/docs/getting-started/requirements/). **Можно ли установить панель без публичного домена?** Да, используйте `--no-nginx` и SSH-туннель — см. [Installation](https://nexcmp.com/ru/docs/getting-started/installation/#installing-without-a-public-domain-lab-or-test). **Почему порт 3000 закрыт после настройки?** В целях безопасности панель слушает `127.0.0.1` сразу после завершения мастера и включения TLS. Для экстренных случаев используйте `sudo nexcmp open-port`. ## Инфраструктура {#infrastructure} **Можно ли использовать CloudStack и Proxmox VE одновременно?** Да. В одной зоне могут присутствовать обе системы; каждый тариф выбирает свой источник. См. [Proxmox VE](https://nexcmp.com/ru/docs/infrastructure/proxmox/) и [Zones](https://nexcmp.com/ru/docs/infrastructure/zones/). **Нужен ли ROOT API key для CloudStack?** Нет — и использовать его не следует. Создайте отдельную учетную запись — [CloudStack](https://nexcmp.com/ru/docs/infrastructure/cloudstack/). **Почему некоторые вкладки или кнопки не отображаются у виртуальной машины?** Страницы показывают только то, что поддерживает источник виртуальной машины (например, в Proxmox VE нет переадресации портов). См. таблицу возможностей в [Proxmox VE](https://nexcmp.com/ru/docs/infrastructure/proxmox/). ## Эксплуатация {#operations} **Как перенести NexCMP на другой сервер?** Создайте резервную копию, установите ту же версию на новом сервере с той же лицензией, выполните восстановление — см. [Резервное копирование и восстановление](https://nexcmp.com/ru/docs/getting-started/backup-and-restore/). **Где находятся логи?** `journalctl -u nexcmp -u nexcmp-vmd`, `/var/log/nexcmp` и панель администратора в System › Logs. См. [Журнал аудита](https://nexcmp.com/ru/docs/administration/audit-log/). **Можно ли посмотреть клиентский портал до установки?** Да. На страницах сервисов на [nexcmp.com](https://nexcmp.com/platform/) клиентский портал показан вкладка за вкладкой с демонстрационными данными; откройте *View demo* для полноэкранного просмотра. Чтобы посмотреть реальную установку, напишите в отдел продаж. --- # Поддержка {#support} ## Контакты {#contact} Формы обратной связи нет. Отправьте письмо на **sales@nexcmp.com** — этот адрес предназначен для вопросов по лицензированию, продлению, доменам и технической части. Страница вашей лицензии на [nexcmp.com/licenses](https://nexcmp.com/licenses) также содержит ссылку на этот адрес. ## Перед обращением {#before-you-write} 1. Поищите в этой документации (нажмите `/`) и проверьте [Ошибки установки](https://nexcmp.com/ru/docs/troubleshooting/installation-errors/) и [Ошибки обновления](https://nexcmp.com/ru/docs/troubleshooting/update-errors/). 2. Соберите указанные ниже сведения — они помогут поддержке ответить за одно обращение. ## Что указать {#what-to-include} | Параметр | Как получить | |---|---| | Версия NexCMP | `sudo nexcmp status` или System › Admin › License & updates | | Основной домен и последние 4 символа лицензионного ключа | License & updates (никогда не отправляйте ключ целиком) | | Что вы сделали и что ожидали получить | Точные шаги | | Текст ошибки или скриншот | Скройте конфиденциальные данные перед отправкой | | Статус службы | `sudo nexcmp status` | | Последние строки логов | `sudo journalctl -u nexcmp -u nexcmp-vmd -n 100 --no-pager` | | Инфраструктура | Версия CloudStack или Proxmox VE, одна зона или несколько | ::: warning Никогда не отправляйте конфиденциальные данные Не отправляйте лицензионные ключи, API-ключи, пароли, setup code, платежные реквизиты или архивы резервных копий. Маскируйте их в логах и на скриншотах. ::: ## Сообщения об уязвимостях {#security-reports} Если вы считаете, что обнаружили уязвимость, отправьте письмо на тот же адрес с темой «Security» и не публикуйте подробности до ее устранения.