--- title: Конфигурация как код description: Экспорт настроек панели в YAML, предпросмотр и применение через nexcmp config или Import/Export; секреты вне файла, валидация идет по JSON Schema. url: https://nexcmp.com/ru/docs/configure-with-ai/config-as-code/ applies_to: NexCMP 1.6.1 updated: 2026-11-02 --- # Конфигурация как код {#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` | Демо-панель | Примените на рабочей установке. |