코드 기반 설정

관리자 위치: System › Settings › Import/Export (/agent/config). 서버: 명령줄 nexcmp config export, plan, apply 및 nexcmp admin <tool>.

작동 내용

패널 설정(브랜딩, 일반 설정, 이메일, 텔레그램 알림, 모듈, 통화, 결제 게이트웨이, 제한, 존, 플랜, AI 공급업체 및 법적 페이지)을 하나의 YAML 파일로 저장할 수 있습니다. 파일을 직접 편집하거나, AI 어시스턴트에 편집을 요청하고, 버전 관리 시스템에서 유지하며, 동일한 패널이나 다른 패널에 적용할 수 있습니다. 변경 사항이 적용되기 전에 항상 변경 내용 목록을 확인할 수 있습니다. 보안 비밀은 파일에 기록되지 않습니다.

이 기능을 사용해 두 번째 설치에 설정을 복제하거나, 라이브 반영 전에 변경 사항을 검토하거나, 실수 후 설정을 복원하거나, AI가 전체 구성을 하나의 문서로 읽을 수 있는 제안을 작성하도록 할 수 있습니다.

요구 사항

항목	요구 사항
NexCMP	1.4.0 이상.
명령줄	패널 서버에 root 상태입니다(sudo 사용). 명령은 자체적으로 패널에 임시 키(15분, 모든 스코프)를 요청합니다. 대신 더 제한적인 키를 사용하려면 NEXCMP_KEY을(를) admin API key(으)로 설정하고 sudo를 통해 유지하세요(예: sudo --preserve-env=NEXCMP_KEY nexcmp config plan -f nexcmp.yaml).
관리자 페이지	관리자로 로그인됨. 데모 패널에서는 해당 페이지가 읽기 전용입니다.
비밀 값	적용 시점에 제공되는 값(Secrets 참조); 파일 내에는 절대 포함되지 않음.

내보내기, 편집, 미리보기, 적용

1. 현재 구성을 내보냅니다:

   sudo nexcmp config export -o nexcmp.yaml

   -o이(가) 없으면 YAML이 화면에 출력됩니다.

2. nexcmp.yaml을(를) 편집합니다(아래의 example 참조). version: 1을(를) 맨 위에 유지하세요.

3. 변경될 내용을 미리 봅니다. 이는 아무것도 변경하지 않습니다:

   sudo nexcmp config plan -f nexcmp.yaml

   각 행은 섹션, 항목, 필드 및 old → new을(를) 표시합니다. $ 표시된 행은 결제 섹션에 속합니다(Billing sections 참조). 패널이 파일과 이미 일치하는 경우 "No changes"가 표시됩니다.

4. 적용합니다. --yes이(가) 없으면 명령어는 dry run으로 실행되며 동일한 목록만 출력합니다.

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

5. 결과를 읽습니다: applied, pending(승인 대기 중), skipped 및 errors.

옵션	의미
-f <file>	YAML 파일(plan 및 apply에 필요).
--yes	실제로 적용합니다. 없으면 apply은(는) dry run으로 실행됩니다.
--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), 판매자 이름.	로고는 파일에 포함되지 않으며 branding page을(를) 사용하세요.
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), 사용자, 비밀번호, 발신자 이름 및 주소, 회신 주소.	SMTP and e-mail templates. 호스트, 포트 또는 보안을 변경하려면 비밀번호를 다시 입력해야 합니다.
telegram	알림 채널 켜기/끄기, 채팅 ID, 봇 토큰.	Telegram notifications.
modules	선택적 모듈 켜기/끄기(key: true/false).	패널에서 전환할 수 있는 키만 해당합니다. Modules를 참조하세요.
currency	표시 통화 및 수동 USD 대 VND 환율(0 자동, 그 외의 경우 15000~50000).	결제 섹션. 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).	결제 섹션. Payment channels를 참조하세요.
quotas	quota_* 제한.	Quotas를 참조하세요.
zones	slug별 영역(필수: slug, name, country; 선택: city, enabled, is_default).	새 영역이 생성됩니다. 이미 존재하는 영역은 파일에 의해 변경되지 않습니다. Zones를 참조하세요.
plans	slug별 플랜(필수: slug, name, cpu, ram_mb, disk_gb, hourly_usd; 선택: cs_offering_id, backend_id, zone_id, enabled, visible, sort, description).	결제 섹션. 새 플랜이 생성되고, 기존 플랜은 슬러그별로 업데이트됩니다. 가격은 시간당 USD 기준입니다. Plans를 참조하세요.
ai_provider	고객 AI Chat 및 AI Agent에서 사용하는 패널 AI 공급자.	AI provider.
legal	언어별 이용약관 및 개인정보 처리방침 텍스트(en, vi).	Legal pages.

적용 순서는 위에서 아래로, 즉 인프라 관련 항목이 플랜보다 먼저 처리됩니다.

숙지해야 할 규칙

• 멱등성. 동일한 파일을 두 번 적용해도 두 번째에는 아무것도 변경되지 않습니다. plan에 "No changes"가 표시됩니다.
• 삭제 없음. 파일은 영역, 플랜 또는 설정을 절대 삭제하지 않습니다. 파일에서 항목을 제거해도 패널은 그대로 유지됩니다.
• 일반적인 안전 규칙이 계속 적용됩니다. 명령줄에서 각 변경 사항은 API 변경과 동일한 검사(범위 및 IP 규칙)를 거칩니다. (사이트 전체 스위치와 같은) 확인이 필요한 변경 사항은 적용되는 대신 pending 아래에 미리보기와 함께 보고되며, 모두 확인하는 --confirm-billing을(를) 전달하는 경우는 예외입니다.
• AI 클라이언트는 결제 기능을 잠금 해제할 수 없습니다. MCP 클라이언트가 config_apply를 호출하면 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(MCP 클라이언트 또는 AI Chat의 config_apply 도구)가 동일한 파일을 적용할 때는 이 플래그가 무시되며, 대신 금전적 변경 사항은 사용자의 승인을 기다립니다.

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 어시스턴트(the tool list)와 동일한 도구를 실행하고 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"}}'

인수(Argument)는 key=value 쌍(값은 파싱 가능한 경우 JSON으로, 그렇지 않으면 텍스트로 읽힘) 또는 하나의 --json '{...}' 객체입니다. 작업에 확인이 필요한 경우, 명령은 미리보기를 출력하고 종료 코드 3과 "Nothing changed"와 함께 중지됩니다. 미리보기를 읽은 후, 적용하려면 --yes(을)를 포함하여 동일한 명령을 다시 실행하세요. root로 실행하면 모든 스코프가 포함된 15분짜리 키를 획득하므로 확인 단계가 안전장치 역할을 합니다. NEXCMP_KEY(을)를 사용하면 키 자체의 스코프가 적용됩니다.

확인

1. sudo nexcmp config plan -f nexcmp.yaml 직후에 apply --yes을(를) 실행하면 "No changes"가 출력됩니다.
2. 관리자 페이지에서 변경된 페이지에 새 값이 표시되며, Logs › Admin actions에 변경 내역이 나열됩니다.
3. 동일한 파일을 다시 적용해도 아무것도 변경되지 않습니다.

한도 및 참고 사항

• 이 파일은 위 설정들을 다루며 고객, 서버, 인보이스 또는 인프라 소스(CloudStack 및 Proxmox 연결)는 포함하지 않습니다. 해당 항목들은 AI Chat 또는 관리자 페이지를 통해 연결하세요.
• 존(Zone)과 플랜은 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을 누르세요.
비밀(secret)이 업데이트되지 않았습니다.	NEXCMP_SECRET_<NAME> 값이 설정되지 않아 저장된 비밀이 유지되었습니다.	변수를 내보낸 후 다시 적용하세요.
HTTP 403 오류와 함께 errors 아래에 항목 표시 insufficient_scope	키에 해당 섹션의 스코프가 없습니다.	스코프가 있는 키를 사용하거나 root로 실행하세요.
HTTP 403 오류와 함께 errors 아래에 항목 표시 demo_read_only	데모 패널	실제 설치 환경에 적용합니다.