Конфигурация как код

В панели управления: System › Settings › Import/Export (/agent/config). На сервере: команды nexcmp config export, plan и apply, а также nexcmp admin <tool>.

Назначение

Конфигурацию панели (брендинг, общие настройки, почту, Telegram-уведомления, модули, валюту, платежные шлюзы, лимиты, зоны, тарифные планы, AI-провайдера и юридические документы) можно сохранить в виде одного YAML-файла. Вы можете редактировать файл вручную, поручить редактирование AI-ассистенту, хранить его в системе контроля версий и применять к этой же или другой панели. До внесения любых изменений вы всегда видите список различий. Секретные данные никогда не записываются в файл.

Используйте эту возможность, чтобы клонировать конфигурацию на другую установку, проверять изменения перед их публикацией, восстанавливать настройки после ошибок или позволить AI сгенерировать полную конфигурацию, которую вы сможете просмотреть как единый документ.

Требования

Параметр	Требование
NexCMP	1.4.0 или новее.
Командная строка	Вы вошли под root на сервере панели (используйте sudo). Команда сама запрашивает у панели временный ключ (15 минут, все области действия). Чтобы использовать ключ с более ограниченными правами, укажите в NEXCMP_KEY API-ключ администратора и передайте его через sudo, например sudo --preserve-env=NEXCMP_KEY nexcmp config plan -f nexcmp.yaml.
Страница администратора	Выполнен вход в панель администратора. На демо-панели страница доступна только для чтения.
Секреты	Значения передаются во время применения (см. Секреты) и никогда не хранятся в файле.

Экспорт, редактирование, предпросмотр и применение

1. Экспортируйте текущую конфигурацию:

   sudo nexcmp config export -o nexcmp.yaml

   Без -o YAML выводится на экран.

2. Отредактируйте nexcmp.yaml (см. пример ниже). Оставьте version: 1 в начале файла.

3. Посмотрите, что изменится. Это действие ничего не меняет:

   sudo nexcmp config plan -f nexcmp.yaml

   В каждой строке отображаются раздел, элемент, поле и old → new. Строки, помеченные $, относятся к разделам биллинга (см. Разделы биллинга). Если настройки панели уже совпадают с файлом, отображается «No changes».

4. Примените изменения. Без --yes команда выполняется как тестовый запуск и лишь выводит тот же список:

   sudo nexcmp config apply -f nexcmp.yaml --yes

5. Ознакомьтесь с результатом: applied, pending (ожидает вашего подтверждения), skipped и errors.

Параметр	Значение
-f <file>	YAML-файл (обязателен для plan и apply).
--yes	Фактическое применение. Без этого параметра apply выполняется как тестовый запуск.
--confirm-billing	Применить также разделы биллинга (payments, currency, plans). Без этого параметра они пропускаются.
--section <name>	Применить только этот раздел. Чтобы указать несколько разделов, повторите параметр.
-o <file>	С export: записать YAML в файл.

Код возврата равен 0, если все изменения применены или изменений не было, 1 — при возврате ошибки, 2 — при ошибке использования или ключа.

Секреты

Вместо секретных данных в файле хранятся ссылки, например password: secret://smtp_password. При применении значение берется из переменной окружения с именем NEXCMP_SECRET_ и именем ссылки заглавными буквами:

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

Пример файла

# 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, несовпадающий номер версии или неизвестный раздел отклоняются до запуска каких-либо действий.

Разделы

Раздел	Что настраивает	Примечания
branding	Название бренда (до 60 символов), основной цвет, валюта отображения (usd или vnd), наименование продавца.	Логотипы не входят в файл; используйте страницу брендинга.
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 и шаблоны писем. При изменении хоста, порта или типа шифрования потребуется заново указать пароль.
telegram	Включение или отключение канала оповещений, chat id, bot token.	Уведомления в Telegram.
modules	Включение или отключение дополнительных модулей (key: true/false).	Только параметры, переключение которых доступно в панели. См. Модули.
currency	Валюта отображения и ручной курс USD к VND (0 — автоматически, иначе от 15000 до 50000).	Раздел биллинга. См. Валюта и курсы обмена.
payments	Учетные данные stripe, paypal, crypto, bank и переключатели channels (pay_card_enabled, pay_wallets_enabled, pay_alipay_enabled, pay_paypal_enabled, pay_usdt_enabled, pay_sepay_enabled).	Раздел биллинга. См. Платежные каналы.
quotas	Лимиты quota_*.	См. Квоты.
zones	Зоны по slug (обязательные: slug, name, country; необязательные: city, enabled, is_default).	Создаются новые зоны. Уже существующая зона не изменяется файлом. См. Зоны.
plans	Тарифные планы по slug (обязательные: slug, name, cpu, ram_mb, disk_gb, hourly_usd; необязательные: cs_offering_id, backend_id, zone_id, enabled, visible, sort, description).	Раздел биллинга. Новые тарифные планы создаются, существующие обновляются по slug. Цены указаны в USD в час. См. Тарифные планы.
ai_provider	AI-провайдер панели, используемый клиентскими AI Chat и AI Agent.	AI provider.
legal	Текст условий обслуживания и конфиденциальности для каждого языка (en, vi).	Юридические страницы.

Порядок применения соответствует порядку выше: элементы инфраструктуры перед тарифными планами.

Правила, о которых следует помнить

• Идемпотентность. Повторное применение того же файла ничего не меняет во второй раз. 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 (доступна для публичного чтения).

Разделы биллинга

payments, currency и plans изменяют цены или пути движения средств. nexcmp config apply --yes пропускает их, если вы не добавите --confirm-billing; в этом случае они перечисляются в skipped ("billing section - pass confirm_billing"). Этот флаг служит вашим подтверждением: с ним каждое изменение биллинга в файле (и любое другое изменение, требующее подтверждения) применяется без повторного запроса. Сначала выполните plan и ознакомьтесь с каждой строкой, отмеченной $.

Когда тот же файл применяется AI (инструмент config_apply в MCP-клиенте или AI Chat), флаг игнорируется, а финансовые изменения ожидают вашего одобрения.

Использование страницы Import/Export

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 в правом верхнем углу открывает схему.

Запуск любого инструмента из командной строки

nexcmp admin запускает те же инструменты, что и AI-ассистенты (список инструментов), и выводит JSON:

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 применяются собственные области видимости ключа.

Проверка

1. sudo nexcmp config plan -f nexcmp.yaml сразу после apply --yes выводит «No changes».
2. В панели администратора на измененных страницах отображаются новые значения, а список изменений доступен в Logs › Admin actions.
3. Повторное применение того же файла ничего не меняет.

Ограничения и примечания

• Файл охватывает перечисленные выше настройки, но не клиентов, серверы, счета или источники инфраструктуры (подключения CloudStack и Proxmox). Подключайте их через AI Chat или страницы панели администратора.
• Зоны и тарифы сопоставляются по slug. Не переименовывайте slug в файле: он будет создан как новый элемент.
• Нельзя изменить размер тарифа, который уже используется клиентами; вместо этого создайте новый тариф.
• Храните экспортированные файлы в тайне, даже если они не содержат секретных данных: в них указаны ваши цены, адреса и названия аккаунтов.

Устранение неполадок

Симптом	Причина	Решение
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_<NAME> не было задано, поэтому сохраненный секрет остался без изменений	Экспортируйте переменную и примените снова.
Запись под errors с HTTP 403 insufficient_scope	У ключа нет необходимой области видимости (scope) для этого раздела	Используйте ключ с нужным scope или запустите от root.
Запись под errors с HTTP 403 demo_read_only	Демо-панель	Примените на рабочей установке.