# NexCMP 1.6.1 — full documentation

> Complete NexCMP documentation in one file. Source: https://nexcmp.com/ko/docs/ · generated 2026-11-02.


---

<!-- source: https://nexcmp.com/ko/docs/getting-started/what-is-nexcmp/ -->

# NexCMP란 무엇인가요 {#what-is-nexcmp}

NexCMP는 **자체 서버**에 설치하여 클라우드 인프라를 판매 가능한 제품으로 전환해 주는 소프트웨어입니다. 다음과 같은 기능을 제공합니다:

- 사용자가 회원가입, 크레딧 충전, 가상 머신 및 기타 서비스 주문, 콘솔 열기, 스냅샷 생성 및 지원 요청을 수행할 수 있는 **고객 포털**;
- 고객, 요금제, 가격, 결제, 인프라 및 설정을 관리할 수 있는 **관리자 콘솔**(`/admin`);
- **빌링**: 고객별 지갑, 시간별 또는 월별 과금, 인보이스, 프로모션 및 리소스 할당량;
- **화이트라벨 리셀러**: 자체 도메인으로 귀하의 용량을 판매하는 다른 브랜드;
- 자동화를 위한 **API**, 명령행 도구(`cmp`) 및 MCP 서버;
- 선택 사항인 **AI Chat**(지원 어시스턴트) 및 **AI Agent**(일반 언어로 VM 관리).

## 연동 대상 {#what-it-connects-to}

NexCMP는 가상 머신을 직접 호스팅하지 않으며, 이를 구동하는 플랫폼을 제어합니다. *소스*(프로바이더)는 다음 중 하나입니다:

| Source | 권장 용도 | 가이드 |
|---|---|---|
| Apache CloudStack | 영역, 네트워크, 가상 라우터 및 공인 IP가 있는 프라이빗 또는 퍼블릭 클라우드 | [CloudStack](https://nexcmp.com/ko/docs/infrastructure/cloudstack/) |
| Proxmox VE | 이미 운영 중인 단일 서버 또는 클러스터 | [Proxmox VE](https://nexcmp.com/ko/docs/infrastructure/proxmox/) |

기타 모듈에는 자체 인프라가 필요합니다: [베어메탈 서버](https://nexcmp.com/ko/docs/infrastructure/dedicated/), [VPN 및 프록시 노드](https://nexcmp.com/ko/docs/infrastructure/vpn-proxy-nodes/), [S3 오브젝트 스토리지](https://nexcmp.com/ko/docs/infrastructure/s3/), [Kubernetes 및 프라이빗 클라우드](https://nexcmp.com/ko/docs/infrastructure/kubernetes-and-private-cloud/). 모든 인프라를 다루는 단일 표는 [Infrastructure requirements](https://nexcmp.com/ko/docs/infrastructure/requirements/)를 참조하세요.

## 아키텍처 {#how-it-is-built}

NexCMP는 단일 Ubuntu 서버에서 두 개의 systemd 서비스로 실행되는 단일 프로그램입니다:

- `nexcmp` — 웹 서버: 고객 포털, 관리자 콘솔, API, 설치 마법사;
- `nexcmp-vmd` — 백그라운드 워커: 프로비저닝 작업, CloudStack 또는 Proxmox와의 동기화, 청구 실행을 처리합니다.

데이터는 `/var/lib/nexcmp`(SQLite 데이터베이스 및 파일)에, 설정은 `/etc/nexcmp`에, 프로그램은 `/opt/nexcmp`에 저장됩니다. 전체 구조는 [Architecture](https://nexcmp.com/ko/docs/infrastructure/architecture/)를 참조하세요.

## 다음 단계 {#where-to-go-next}

1. [requirements](https://nexcmp.com/ko/docs/getting-started/requirements/)를 확인하세요.
2. 라이선스 발급 — [License and purchase](https://nexcmp.com/ko/docs/getting-started/license-and-purchase/).
3. [Install](https://nexcmp.com/ko/docs/getting-started/installation/) 후 [setup wizard](https://nexcmp.com/ko/docs/getting-started/setup-wizard/)를 실행하세요.
4. 플랫폼 연결: [CloudStack](https://nexcmp.com/ko/docs/infrastructure/cloudstack/) 또는 [Proxmox VE](https://nexcmp.com/ko/docs/infrastructure/proxmox/).


---

<!-- source: https://nexcmp.com/ko/docs/getting-started/requirements/ -->

# NexCMP 서버 요구 사항 {#requirements-for-the-nexcmp-server}

이 페이지에서는 NexCMP를 실행하는 서버를 다룹니다. CloudStack, Proxmox VE 또는 기타 인프라에 필요한 사항은 [인프라 요구 사항](https://nexcmp.com/ko/docs/infrastructure/requirements/)에서 확인하세요.

## 서버 {#server}

| 항목 | 요구 사항 | 설치 프로그램 확인 여부 |
|---|---|---|
| 운영체제 | Ubuntu **22.04** 또는 **24.04** | 예 — 그 외의 경우 오류와 함께 중단됨 |
| CPU 아키텍처 | x86_64 | 예 |
| 메모리 | 최소 2 GB (설치 프로그램은 약 1.8 GB 미만인 경우 거부함) | 예 |
| 여유 디스크 | `/`에 최소 8 GB 여유 공간 | 예 |
| 권한 | root (`sudo`) | 예 |
| 패키지 | `curl`, `ca-certificates`, `zstd`, `tar`, `openssl`, `python3`, `openssh-client` — 자동 설치됨 | 누락된 경우 설치됨 |
| HTTPS 사용 | `nginx` 및 `certbot` — `--no-nginx`를 전달하지 않는 한 자동 설치됨 | 누락된 경우 설치됨 |

::: tip 크기 산정
소규모 설치(수백 명의 고객)는 2 vCPU / 4 GB RAM에서 원활하게 실행됩니다. 디스크 사용량은 주로 SQLite 데이터베이스와 선택적 업데이트 및 백업 복사본이 차지하므로, 운영 환경의 경우 20 GB 이상을 계획하세요.
:::

## 네트워크 {#network}

| 방향 | 포트 | 용도 |
|---|---|---|
| 인바운드 | 80/tcp | Let's Encrypt 검증 및 HTTPS 리디렉션 |
| 인바운드 | 443/tcp | 고객 포털, 관리자 콘솔, API |
| 인바운드 | 3000/tcp | 최초 설치 시 설정 마법사 및 긴급 액세스 전용 — [설치](https://nexcmp.com/ko/docs/getting-started/installation/#the-panel-port-3000) 참고 |
| 아웃바운드 | `nexcmp.com`로의 443/tcp | 라이선스 활성화, 일일 라이선스 확인, 업데이트 |
| 아웃바운드 | CloudStack API / Proxmox API로 | 프로비저닝 및 동기화 |
| 아웃바운드 | 활성화한 결제, 이메일 및 AI 제공업체로의 443/tcp | Stripe, PayPal, SMTP, AI 제공업체 등 |

Let's Encrypt에서 인증서를 직접 발급받으려면 서버에 **공인 IPv4 주소**가 필요합니다. 도메인이 Cloudflare를 통해 프록시되는 경우 [DNS 및 Cloudflare](https://nexcmp.com/ko/docs/getting-started/dns-and-cloudflare/)를 참고하세요.

## DNS

- 하나의 **메인 도메인**(예: `cloud.example.com`) — 포털은 `https://cloud.example.com/`이고 관리자 콘솔은 `https://cloud.example.com/admin`입니다.
- 선택 사항: `admin.<domain>` 및 `partner.<domain>`. 해당 이름이 서버(또는 Cloudflare)로 확인되면 설치 프로그램이 인증서에 추가합니다.
- 도메인은 라이선스에 등록된 도메인과 일치해야 합니다.

## 이 서버에서는 필요하지 않음 {#not-required-on-this-server}

NexCMP는 일반적인 권한 없는 서비스 사용자(`nexcmp`)로 실행됩니다. 런타임에 root 권한, Docker, 별도의 데이터베이스 서버, Redis 또는 하이퍼바이저 소프트웨어가 **필요하지 않습니다**.


---

<!-- source: https://nexcmp.com/ko/docs/getting-started/license-and-purchase/ -->

# 라이선스 및 구매 {#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)에서 계정을 만들고 이메일을 인증합니다.
2. 에디션을 선택합니다:
   - **NexCMP Free** — 자체 ASN과 본인 명의로 등록된 서브넷을 보유한 네트워크 운영자를 위한 에디션입니다. [nexcmp.com/deploy](https://nexcmp.com/deploy)에서 신청서를 제출하세요(회사, ASN, 서브넷, 패널 도메인). 계정 이메일은 공개 레지스트리(WHOIS)에 ASN 또는 서브넷 소유자로 등록된 회사 도메인이어야 합니다. 모든 신청서는 검토를 거치며, 결과는 이메일로 통보되고 승인된 후에만 라이선스 키가 표시됩니다.
   - **NexCMP Source** — ASN이 필요 없는 일회성 업그레이드입니다. [nexcmp.com/pricing](https://nexcmp.com/pricing)을 참조하세요.
3. 라이선스 페이지를 엽니다. **라이선스 키**(형식: `NXC-XXXXX-XXXXX-XXXXX-XXXXX`), **메인 도메인** 및 바로 사용할 수 있는 설치 명령어가 표시됩니다.

::: warning 키를 비공개로 유지
라이선스 키는 설치를 활성화하는 데 사용됩니다. 비밀번호처럼 취급하고 티켓, 채팅, 스크린샷에 공유하지 마세요.
:::

## 라이선스 구성 내용 {#what-a-license-contains}

| 필드 | 의미 |
|---|---|
| 메인 도메인 | 포털이 실행되는 호스트 이름입니다. 활성화 시 키가 이 도메인에 바인딩됩니다. |
| 리셀러 도메인 | 화이트라벨 포털로 서비스되는 추가 호스트 이름 — [Resellers](https://nexcmp.com/ko/docs/customers/resellers/) 참조. |
| 업데이트 기한 | **업데이트 및 버그 수정**을 받을 수 있는 기한입니다. Free 라이선스는 승인일로부터 **1년**간 제공되며, 라이선스 페이지에서 연간 $99로 갱신할 수 있습니다. 보안 수정 사항은 이 기한이 지난 후에도 항상 제공됩니다. |
| 상태 | `active` 또는 일시 중지 / 만료 / 취소됨. |

## 무료 1년이 만료된 경우 {#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 또는 기타 패널에서의 무료 마이그레이션 또는 A부터 Z까지의 전체 설정)이 포함됩니다. 새로운 소스 릴리스는 12개월 동안 제공되며, 이후 갱신(연간 $99)은 선택 사항이고 다운로드한 소스는 계속 소유할 수 있습니다. [Source license terms](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)에서 갱신) License & updates에서 **Check now**을(를) 클릭합니다.

## 새 서버 또는 도메인으로 이전하기 {#moving-to-a-new-server-or-domain}

동일한 키와 등록된 도메인으로 새 서버에서 활성화합니다([Installation](https://nexcmp.com/ko/docs/getting-started/installation/) 참조). 등록된 도메인을 변경하려면 먼저 [nexcmp.com/licenses](https://nexcmp.com/licenses)의 라이선스 페이지에서 변경한 후, 새 `--domain`(와)과 함께 설치 프로그램을 다시 실행하세요.


---

<!-- source: https://nexcmp.com/ko/docs/getting-started/installation/ -->

# NexCMP 설치 {#install-nexcmp}

설치 프로그램은 라이선스 서버에서 제공하는 단일 스크립트입니다. 머신을 확인하고, 라이선스를 활성화하며, 프로그램을 다운로드 및 검증하고, 서비스를 설치하며, (선택 사항으로) Let's Encrypt 인증서와 함께 nginx를 설정합니다.

## 시작하기 전에 {#before-you-start}

- [requirements](https://nexcmp.com/ko/docs/getting-started/requirements/)을(를) 충족하는 서버와 루트(root) 권한.
- [license page](https://nexcmp.com/licenses)의 **라이선스 키** 및 **메인 도메인** — [License and purchase](https://nexcmp.com/ko/docs/getting-started/license-and-purchase/) 참조.
- 도메인의 DNS 레코드 — [DNS and Cloudflare](https://nexcmp.com/ko/docs/getting-started/dns-and-cloudflare/) 참조. 먼저 설치하고 나중에 DNS를 수정해도 됩니다. 설치 프로그램이 누락된 항목을 알려주므로 단순히 다시 실행하면 됩니다.

## 설치 {#install}

1. 서버에 로그인한 후 루트 권한을 획득합니다(또는 `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. 체크 마크가 나타날 때까지 기다립니다. 새 설치는 몇 분 정도 걸리며, 첫 시작 시 데이터베이스 스키마를 생성하므로 느린 디스크에서는 최대 1분이 소요될 수 있습니다.
4. 마지막 요약을 읽어보세요. 포털 및 관리자 URL, **설정 코드**, 그리고 다음 단계가 출력됩니다.

![포털 URL, 관리자 URL 및 일회용 설정 코드로 완료되는 설치 프로그램](https://nexcmp.com/ko/docs/images/getting-started/installation-01-finish.webp)

## 매개변수 {#parameters}

| Parameter | Default | 의미 |
|---|---|---|
| `--license KEY` | 최초 설치 시 필수 | 라이선스 키입니다. |
| `--domain NAME` | 최초 설치 시 필수 | 메인 도메인입니다. 라이선스와 일치해야 합니다. `https://` 및 후행 경로는 제거됩니다. |
| `--email ADDRESS` | none | Let's Encrypt 만료 알림을 위한 담당자 이메일입니다. 이메일이 없으면 인증서가 이메일 없이 등록됩니다. |
| `--port N` | `3000` | 패널의 로컬 포트 (1–65535). |
| `--no-nginx` | off | nginx / TLS를 설치하거나 설정하지 않습니다. 자체 리버스 프록시를 운영하거나 NexCMP를 먼저 살펴보고 싶을 때 사용하세요. |
| `--behind-cloudflare` | auto-detected | "도메인이 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 GB RAM, 8 GB 여유 디스크.
2. **필요한 패키지를 설치합니다** (`curl`, `zstd`, `openssl`, `python3`, `openssh-client` 등).
3. **서비스 사용자** `nexcmp` 및 디렉터리를 생성합니다: `/opt/nexcmp` (프로그램용, root 소유, 서비스는 읽기 전용), `/etc/nexcmp` (설정), `/var/lib/nexcmp` (데이터), `/var/log/nexcmp`.
4. 도메인에 대한 **라이선스를 활성화**하고 이 머신에 대한 고정 인스턴스 ID를 저장합니다.
5. **사용 권한이 있는 최신 릴리스를 다운로드**한 다음 SHA-256 및 Ed25519 서명을 검증합니다. 유효한 서명이 없는 릴리스는 거부됩니다. 실행 중인 최신 버전을 이전 버전으로 다운그레이드하지 않습니다.
6. **설정 및 systemd 유닛을 작성하고** (`nexcmp`, `nexcmp-vmd`, `nexcmp-update`) 서비스를 시작합니다. `/healthz`의 응답을 대기합니다.
7. **nginx 및 TLS를 설정합니다** (`--no-nginx`인 경우 제외): certbot(webroot 챌린지)을 사용하여 도메인 및 해당 이름도 확인될 때 `admin.<domain>` / `partner.<domain>`에 대한 Let's Encrypt 인증서를 발급받습니다. DNS가 아직 이 서버(또는 Cloudflare)를 가리키지 않는 경우 이 단계를 건너뛰고 그 사실을 알립니다.
8. URL 및 (관리자가 아직 없는 경우) **설정 코드**가 포함된 **요약 정보를 출력합니다**.

## 패널 포트 (3000) {#the-panel-port-3000}

- 최초 설치 시 패널은 `0.0.0.0:3000`에서 수신 대기하므로 `http://<server-IP>:3000/setup`에서 설정 마법사를 열 수 있습니다.
- 마법사가 완료되고 **또한** TLS가 활성화되면 패널은 `127.0.0.1`에서만 수신 대기하며, nginx가 `https://<domain>`을 그곳으로 프록시합니다.
- 비상 시(nginx 손상, DNS 오류) 제한된 시간 동안 포트를 열 수 있습니다: `sudo nexcmp open-port 30` (30분 후 자동 닫힘) — 또는 SSH 터널을 사용합니다: `ssh -L 3000:127.0.0.1:3000 <server>` 및 `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 <server>`, `http://127.0.0.1:3000/setup` 브라우징)을 통해 마법사를 엽니다. DNS가 생성되면 `--no-nginx` 없이 설치 프로그램을 다시 실행하십시오.

## Docker 및 Kubernetes {#docker-and-kubernetes}

공식 배포된 컨테이너 이미지는 없습니다. 설치 프로그램(네이티브 systemd 설치)이 공식 지원되는 설치 방법입니다.

## 확인 {#verify}

```bash
sudo nexcmp status
```

버전, `nexcmp: active`, `nexcmp-vmd: active`, `healthz: ok` 및 마법사가 완료될 때까지는 설정 코드가 표시되어야 합니다. [setup wizard](https://nexcmp.com/ko/docs/getting-started/setup-wizard/)로 계속 진행하십시오.

문제가 발생하면 [Installation errors](https://nexcmp.com/ko/docs/troubleshooting/installation-errors/)를 참조하십시오.


---

<!-- source: https://nexcmp.com/ko/docs/getting-started/dns-and-cloudflare/ -->

# DNS 및 Cloudflare {#dns-and-cloudflare}

NexCMP에는 하나의 DNS 이름(즉, **메인 도메인**)이 필요하며 두 가지 모드로 작동합니다.

## 모드 A: DNS가 서버를 직접 가리키는 경우 {#mode-a-dns-points-straight-at-the-server}

1. `cloud.example.com → <server public IPv4>` **A** 레코드를 생성합니다 (서버에 IPv6가 있는 경우 **AAAA** 레코드도 생성).
2. 사용하는 경우 선택 사항: 동일한 IP를 가리키는 `admin.cloud.example.com` 및 `partner.cloud.example.com`.
3. [installer](https://nexcmp.com/ko/docs/getting-started/installation/)를 실행(또는 재실행)합니다. 이름이 서버 자신의 공인 IP로 확인되는 것을 감지하고 포트 80의 HTTP-01 챌린지를 통해 Let's Encrypt 인증서를 발급받습니다.

## 모드 B: 도메인이 Cloudflare를 통해 프록시되는 경우 {#mode-b-the-domain-is-proxied-by-cloudflare}

주황색 클라우드(**Proxied**)를 사용하여 동일한 레코드를 생성합니다. 설치 프로그램은 이름이 Cloudflare 주소로만 확인되는 것을 감지하고 Cloudflare 모드로 전환됩니다:

- nginx는 여전히 서버의 80/443 포트에서 수신 대기합니다;
- 방문자의 실제 IP는 `CF-Connecting-IP` 헤더에서 읽어오며, Cloudflare의 공개 IP 대역에서 들어오는 연결에 대해서**만** 적용되므로 다른 사용자가 위조할 수 없습니다.
- 인증서는 Let's Encrypt를 통해 발급받으며(Cloudflare가 챌린지를 오리진으로 전달), 아직 발급이 불가능한 경우 "Full" 모드가 작동하도록 **자체 서명 오리진 인증서**를 생성하고 추후 설치 프로그램을 재실행하여 Let's Encrypt로 업그레이드합니다.

`--behind-cloudflare`(으)로 이 모드를 강제 적용할 수 있습니다.

::: important Cloudflare에서 SSL/TLS 모드 설정
Cloudflare에서 **SSL/TLS › Overview**(으)로 이동하여, 설치 프로그램에 Let's Encrypt 인증서가 확인되면 **Full (strict)**을 선택하십시오. 자체 서명 오리진 인증서의 경우 **Full**을 사용하십시오. **Flexible**은 리디렉션 루프를 유발합니다.
:::

::: tip
"Always Use HTTPS"가 켜져 있으면 Cloudflare는 검증 요청을 오리진의 443 포트로 보냅니다. 설치 프로그램은 먼저 임시 자체 서명 인증서를 생성한 다음 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 타이머를 통해 자동으로 갱신됩니다. 갱신 시 웹루트 `/var/www/nexcmp-acme`을(를) 사용하므로 80 포트에 (직접 또는 Cloudflare를 통해) 계속 접근할 수 있어야 합니다.

## 자주 발생하는 문제 {#common-problems}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| 설치 프로그램에 "DNS … does not point to … (nor to Cloudflare) — skipping nginx/TLS" 메시지가 표시됨 | DNS 레코드가 누락되었거나 잘못되었거나 전파되지 않음 | 레코드를 수정하고 전파될 때까지 기다린 후 설치 프로그램을 다시 실행합니다. |
| Cloudflare 프록시 환경에서 브라우저에 `ERR_TOO_MANY_REDIRECTS`이(가) 표시됨 | SSL 모드가 **Flexible**으로 설정됨 | **Full (strict)**(또는 **Full**)(으)로 설정합니다. |
| Cloudflare 오류 525/526 | 오리진 인증서가 거부됨 | 자체 서명 오리진 인증서의 경우 **Full**을 사용하고, Let's Encrypt의 경우 **Full (strict)**을 사용합니다. |
| 로그의 모든 방문자 IP가 Cloudflare IP로 표시됨 | Cloudflare 모드가 아님 | `--behind-cloudflare` 옵션으로 설치 프로그램을 다시 실행합니다. |

자세한 내용은 [설치 오류](https://nexcmp.com/ko/docs/troubleshooting/installation-errors/)를 참고하십시오.


---

<!-- source: https://nexcmp.com/ko/docs/getting-started/setup-wizard/ -->

# 설정 마법사 {#setup-wizard}

> **어드민 위치:** 마법사는 첫 번째 관리자가 생성될 때까지만 `/setup`에 독립 페이지로 표시됩니다. 이후에는 System › Admin › Start(`/setup`)에서 동일한 점검 항목을 확인할 수 있습니다.

마법사는 네 단계의 간단한 과정을 통해 새로 설치된 시스템을 바로 사용 가능한 패널로 완성합니다. 3000 포트(`http://<server-IP>:3000/setup`) 또는 TLS가 이미 활성화된 경우 `https://<domain>/setup`에서 제공됩니다.

::: warning 3단계 이후 마법사가 사라집니다
관리자가 생성되면 마법사가 닫히고 설정 코드가 삭제됩니다. 이후 패널에 접속하려면 관리자 콘솔을 사용하십시오.
:::

## Step 0 — 설정 코드 {#step-0-—-setup-code}

설치 프로그램 완료 시 **일회성 설정 코드**가 출력됩니다. 다음 명령으로 다시 확인할 수 있습니다:

```bash
sudo nexcmp status
```

이를 **Setup code**에 붙여넣고 **Continue**을 클릭합니다. 이 코드는 마법사를 보호하기 위한 장치로, 열린 포트를 찾더라도 이 코드가 없으면 관리자를 생성할 수 없습니다.

![일회성 설정 코드를 입력하는 설정 마법사의 Step 0](https://nexcmp.com/ko/docs/images/getting-started/setup-wizard-00-code.webp)

## Step 1 — 라이선스 {#step-1-—-license}

| 필드 | 값 |
|---|---|
| 라이선스 키 | `NXC-XXXXX-XXXXX-XXXXX-XXXXX` — 설치 프로그램에 의해 미리 활성화되므로 이 단계에서는 일반적으로 "Activated for cloud.example.com"이 표시됩니다. |
| 메인 도메인 | 라이선스에 등록된 도메인 |

설치 프로그램이 이미 라이선스를 활성화한 경우, 마법사가 이를 인식하고 다음 단계로 진행합니다. 그렇지 않은 경우 키와 도메인을 입력하고 **Activate**를 클릭하세요. 오류는 빨간색으로 표시됩니다. [Installation errors](https://nexcmp.com/ko/docs/troubleshooting/installation-errors/)를 참조하세요.

![주요 도메인에 대해 라이선스가 이미 활성화된 상태로 표시되는 설정 마법사 1단계](https://nexcmp.com/ko/docs/images/getting-started/setup-wizard-01-license.webp)

## Step 2 — CloudStack (or Connect later) {#step-2-—-cloudstack-or-connect-later}

두 가지 선택지가 있습니다:

- **지금 연결.** CloudStack **API URL** (`https://cloudstack.example.com/client/api`), **API key** 및 **Secret key**를 입력하고 **Test connection**을 클릭한 다음 **Zone**, **Guest network for customer VMs**, **Zone display name**, 그리고 두 자리 **Country**를 선택합니다. **Save CloudStack**을 클릭하세요.
- **나중에 연결.** **Connect later**를 클릭하세요. 다른 기능은 모두 정상 작동하며, CloudStack이나 Proxmox VE는 나중에 Infrastructure 메뉴에서 연결할 수 있습니다. 그때까지는 상태 패널에 연결된 소스가 없다는 알림이 표시됩니다.

![CloudStack API URL, API key 및 secret key 필드에 예시 값이 입력된 마법사 2단계](https://nexcmp.com/ko/docs/images/getting-started/setup-wizard-02-cloudstack-form.webp)

::: important 전용 CloudStack 계정 사용
ROOT 관리자 키를 사용하지 마세요. NexCMP를 위한 전용 도메인과 계정을 생성하고 해당 API 키를 사용하세요. [CloudStack](https://nexcmp.com/ko/docs/infrastructure/cloudstack/#create-a-dedicated-account-and-api-key)을 참조하세요. 마법사는 선택한 네트워크가 해당 키의 존 및 계정에 속하는지 확인합니다.
:::

![Test connection 이후: 존 및 게스트 네트워크 목록, 존 표시 이름 및 국가 필드](https://nexcmp.com/ko/docs/images/getting-started/setup-wizard-02b-cloudstack-picked.webp)

**Proxmox VE**만 사용할 계획인 경우 **Connect later**를 선택하고 [Proxmox VE](https://nexcmp.com/ko/docs/infrastructure/proxmox/) 안내를 따르세요.

## Step 3 — 관리자 및 브랜드 {#step-3-—-administrator-and-brand}

| 필드 | 규칙 |
|---|---|
| 관리자 이메일 (로그인) | 유효한 이메일 주소입니다. 이것이 관리자 사용자 이름이 됩니다. |
| 비밀번호 | 문자와 숫자를 포함하여 12자 이상이어야 합니다. |
| 브랜드 이름 | 고객에게 표시되는 이름입니다 (기본값 "Cloud"). 최대 60자까지 가능합니다. |
| 지원 이메일 | 기본값은 관리자 이메일입니다. |

![관리자 이메일, 비밀번호, 브랜드 이름 및 지원 이메일이 입력된 마법사 3단계](https://nexcmp.com/ko/docs/images/getting-started/setup-wizard-03-admin.webp)

**Finish setup**을 클릭하세요. 패널이 재시작되고 (약 1~2초 소요) 페이지가 `https://<domain>/admin/`의 관리자 로그인 페이지로 이동합니다. 해당 주소가 아직 응답하지 않는 경우 (DNS 또는 TLS 대기 중), 대신 현재 주소의 `/`로 이동합니다.

![패널이 재시작 중이라는 메시지와 함께 완료된 마법사 화면](https://nexcmp.com/ko/docs/images/getting-started/setup-wizard-03-done.webp)

## 마법사가 설정하는 항목 {#what-the-wizard-sets-up-for-you}

- 브랜드 이름, 사이트 URL (`https://<domain>`), 관리자 URL (`https://<domain>/admin`), 콘솔 URL (`https://<domain>/console`), 지원 이메일 및 발신자 이름.
- NexCMP에 기본 포함된 모듈의 기본 설정: DDoS & BGP, AI, 웹 SSH는 **꺼짐**, 대역폭 측정은 **켜짐** 상태입니다. [Modules](https://nexcmp.com/ko/docs/infrastructure/modules/)를 참조하세요.
- CloudStack을 연결한 경우: 공급자 #1, 첫 번째 존, 게스트 네트워크, 그리고 고객 지원을 위해 고객 VM에 연결되는 운영 키 쌍.

다음: [First login](https://nexcmp.com/ko/docs/getting-started/first-login/).


---

<!-- source: https://nexcmp.com/ko/docs/getting-started/first-login/ -->

# 첫 로그인 및 다음 단계 {#first-login-and-next-steps}

> **관리자 위치:** 로그인 페이지는 `/admin`이며, 로그인 후 랜딩 페이지는 Overview › Dashboard입니다.

## 주소 {#addresses}

| 항목 | URL |
|---|---|
| 고객 포털 | `https://<domain>/` |
| 관리자 콘솔 | `https://<domain>/admin` |
| 설정 / IP 긴급 접속 | `http://<server-IP>:3000/` ([패널 포트](https://nexcmp.com/ko/docs/getting-started/installation/#the-panel-port-3000) 참조) |
| 상태 확인 | `https://<domain>/healthz` |

## 로그인 {#sign-in}

1. `https://<domain>/admin`을(를) 엽니다.
2. 마법사에서 생성한 관리자 이메일과 비밀번호를 입력합니다.
3. **Dashboard** 화면으로 이동합니다. 라이선스가 유효하지 않거나 소스가 연결되지 않은 경우 상단에 배너가 표시됩니다.

![관리자 로그인 페이지](https://nexcmp.com/ko/docs/images/getting-started/first-login-01-login.webp)

## 권장 체크리스트 {#recommended-checklist}

순서대로 진행하세요. 각 항목은 해당 페이지로 연결됩니다.

| # | 작업 | 페이지 |
|---|---|---|
| 1 | 내 계정에 2단계 인증 활성화 | [Security](https://nexcmp.com/ko/docs/administration/security/) |
| 2 | 인프라 소스 연결 ("나중에 연결"을 선택한 경우) | [CloudStack](https://nexcmp.com/ko/docs/infrastructure/cloudstack/) 또는 [Proxmox VE](https://nexcmp.com/ko/docs/infrastructure/proxmox/) |
| 3 | 영역 및 머신 템플릿 / OS 목록 확인 | [Zones](https://nexcmp.com/ko/docs/infrastructure/zones/), [Templates](https://nexcmp.com/ko/docs/infrastructure/templates/) |
| 4 | 요금제 및 가격 검토 | [Plans](https://nexcmp.com/ko/docs/catalog/plans/) |
| 5 | 로고, 색상 및 법적 고지 페이지 설정 | [Branding](https://nexcmp.com/ko/docs/customers/branding/), [Legal](https://nexcmp.com/ko/docs/customers/legal/) |
| 6 | 발신 이메일 구성 및 테스트 발송 | [SMTP and emails](https://nexcmp.com/ko/docs/administration/smtp-and-emails/) |
| 7 | 결제 채널을 하나 이상 활성화하고 잔액 충전 테스트 | [Payment channels](https://nexcmp.com/ko/docs/billing/payment-channels/) |
| 8 | 판매할 모듈 결정 | [Modules](https://nexcmp.com/ko/docs/infrastructure/modules/) |
| 9 | 고객으로 테스트 주문 생성 후 삭제 | [Ordering](https://nexcmp.com/ko/docs/portal/ordering/) |
| 10 | 첫 백업 생성 | [Backup and restore](https://nexcmp.com/ko/docs/getting-started/backup-and-restore/) |

## 첫 번째 주문 생성 (스모크 테스트) {#create-your-first-order-smoke-test}

1. 시크릿 창에서 고객 포털을 열고 테스트 계정을 등록합니다.
2. 크레딧(바우처 또는 테스트 결제)을 추가합니다.
3. 영역에서 가장 작은 요금제를 주문합니다.
4. 관리자 페이지의 Services › Virtual Machines에서 주문이 나타나는지 확인하고, 콘솔을 연 후 삭제합니다.

VM이 *running* 상태에 도달하지 않으면 **Infrastructure › Cloud provider › Sync & errors**을(를) 열고 오류 내용을 확인하세요.


---

<!-- source: https://nexcmp.com/ko/docs/getting-started/updating/ -->

# NexCMP 업데이트 {#updating-nexcmp}

> **관리자 페이지 위치:** System › Admin › License & updates (`/license`) → *Update* 카드.

## 제공되는 항목 {#what-you-receive}

| 릴리스 유형 | 제공 시점 |
|---|---|
| 보안 패치 | **항상** 제공 (업데이트 기한 만료 후에도 제공) |
| 기능 릴리스 | "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 우측 상단에서 버전을 확인합니다.

![실행 중인 버전과 Check for new version 버튼이 있는 Update 카드](https://nexcmp.com/ko/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` — [Backup and restore](https://nexcmp.com/ko/docs/getting-started/backup-and-restore/) 참조.
2. Update 카드의 변경 내역을 확인하십시오. VPN 에이전트 업데이트 및 Bare Metal 가격 책정 규칙을 비롯한 1.3 이후 변경 사항은 [1.6.1까지의 릴리스 노트](https://nexcmp.com/ko/docs/getting-started/release-notes/)를 참조하십시오.
3. 트래픽이 적은 시간에 업데이트를 진행하세요. 실행 중인 가상 머신은 건드리지 않지만, 고객이 몇 초 동안 포털을 사용할 수 없습니다.

## 업데이트 후 {#after-you-update}

- `sudo nexcmp status`을(를) 실행하고 두 서비스가 모두 활성화되어 있는지 확인합니다.
- 관리자 대시보드와 **Needs attention** 페이지를 엽니다.
- 데이터베이스 마이그레이션은 새 버전이 처음 시작될 때 자동으로 실행됩니다.
- VPN 노드를 운영 중인 경우, 해당 노드의 에이전트를 별도로 업데이트하고 사용량 측정값을 확인하십시오. 패널을 업데이트하면 새 에이전트를 사용할 수 있게 되지만, 모든 원격 노드가 이미 해당 버전을 실행 중임을 보장하지는 않습니다. [VPN 노드 데이터 허용량](https://nexcmp.com/ko/docs/infrastructure/vpn-proxy-nodes/#data-allowance-on-a-vpn-node)을 참조하십시오.

업데이트가 실패하는 경우 [Update errors](https://nexcmp.com/ko/docs/troubleshooting/update-errors/)를 참조하세요.


---

<!-- source: https://nexcmp.com/ko/docs/getting-started/release-notes/ -->

# 릴리스 노트 {#release-notes}

> **관리자 메뉴 위치:** System › Admin › License & updates(`/license`), **Update** 카드.

본 문서는 1.3 이후부터 **NexCMP 1.6.1**까지의 변경 사항을 다룹니다. 업데이트 전에 백업을 수행하고 설치 환경의 **Update** 카드에서 제공하는 릴리스를 사용하십시오. 명령어 및 서명 확인 방법은 [NexCMP 업데이트](https://nexcmp.com/ko/docs/getting-started/updating/)를 참조하십시오.

## 1.6.1

- **Bare Metal 지표:** 고객 **Overview**에 CPU, RAM, 디스크 작업 및 네트워크 타일이 최근 이력과 함께 표시됩니다. 누락된 측정값에는 대시(-)와 이유가 표시됩니다. 네트워크 측정값은 트래픽 카운터가 필요하며, iDRAC 하드웨어 인벤토리에서 추정되지 않습니다.
- **Bare Metal 샘플 플랜:** 샘플 이름에는 `BM-40C-<RAM>`이 사용됩니다. 수정하지 않은 기본 제공 샘플 플랜에는 중립적인 이름이 지정됩니다. 수정한 플랜은 유지되며, 참조된 플랜은 기존 코드를 유지합니다. 플랜을 판매 가능 상태로 전환하기 전에 실제 서버 하드웨어를 확인하십시오.
- **플랜 변경:** 관리자 요청 목록이 서버 측에서 정렬되며 가로로 스크롤할 때도 작업 버튼이 계속 표시됩니다.
- **버그 신고:** 양식을 스크롤해도 버튼이 계속 표시됩니다. 비밀번호 마스킹 시 주변 진단 텍스트는 그대로 유지됩니다.
- **로딩 속도 개선:** 페이지 리소스와 자주 사용하는 관리자 데이터를 더 일찍 로드하여 탐색 지연을 줄였습니다.

[Bare Metal 설정, 가격 책정 및 고객 제어](https://nexcmp.com/ko/docs/infrastructure/dedicated/) 및 [버그 신고](https://nexcmp.com/ko/docs/administration/report-a-bug/)를 참조하십시오.

## 1.6.0

- **Bare Metal 설정:** **Safety › Management network connection**에서 iDRAC 네트워크, ISO 서버 주소, 패널 콜백 주소를 입력하십시오. 설정이 완료될 때까지 샘플 값으로 인해 실제 운영 작업이 차단됩니다.
- **ISO 호스팅:** `sudo nexcmp dedicated-setup-iso`는 관리 네트워크 ISO 웹 서버를 구성합니다. 설치 프로그램은 `--baremetal` 또는 ISO 옵션을 통해 콘솔 및 ISO 도구를 설치할 수 있습니다. 도구가 누락된 경우 `tools_missing` 메시지와 함께 실제 운영 작업이 차단됩니다.
- **Bare Metal 가격:** 새로 설치했거나 사용하지 않은 설치본은 USD 가격으로 시작합니다. 이미 VND 가격 데이터가 있는 설치본은 VND를 유지하며 여전히 USD/VND 환율이 필요합니다. 업데이트하더라도 기존 가격을 달러로 재해석하지 않습니다.
- **고객 서버 페이지:** 사전 갱신, 청구 주기 변경 예약, 플랜 변경 요청, 인보이스 확인, 설치 후 OS 로그인 정보 확인이 가능합니다. 새 소유자는 이전 소유자의 비밀번호를 볼 수 없습니다.
- **고객 프로필:** 개요, 서비스, 청구, 할당량, 보안, 지원, 제휴, 로그 등 8개 탭으로 구성됩니다. 서비스는 검색 및 정렬이 가능한 하나의 표를 공유합니다.
- **서비스 작업:** 잠금, 잠금 해제, 환불 없는 취소 및 환불 포함 취소 시 공통 대화 상자를 사용합니다. 환불 금액은 원래 지갑이나 크레딧 할당으로 반환되며, 결제 대행사로 자동 환불되지는 않습니다.

[Dedicated servers](https://nexcmp.com/ko/docs/infrastructure/dedicated/) 및 [Managing customers](https://nexcmp.com/ko/docs/customers/managing-customers/) 문서를 참고하십시오. NexCMP에서는 BYOIP 및 Bare Metal 서버에 고객 서브넷을 연결하는 기능이 계속해서 지원되지 않습니다.

## 1.5.2

메인 관리자는 **Report a bug**(**Docs** 옆)를 열어 별도의 로그인 없이 라이선스 계정으로 티켓을 전송할 수 있습니다. 진단 정보는 선택 사항입니다. 직원, 고객 및 AI 어시스턴트는 이 작업을 통해 리포트를 전송할 수 없습니다. [Report a bug](https://nexcmp.com/ko/docs/administration/report-a-bug/)를 참조하십시오.

## 1.5.1

- **VPN 사용량:** 에이전트 노드가 패널로 트래픽을 보고합니다. 허용된 GB 용량을 모두 소진한 구독은 차단되며, 대역폭 업그레이드 또는 새 주기가 시작된 후 다시 사용할 수 있게 됩니다. 사용량 보고가 없는 노드는 **Not measured**로 표시되며 GB 기준 차단이 적용되지 않습니다.
- **VPN 에이전트:** 1.5.1 버전은 미확인 사용량을 재시도하고, 종료 시 최종 트래픽을 전송하며, 엔드포인트가 중지될 때 열려 있는 연결을 닫습니다. 패널뿐만 아니라 원격 에이전트도 업데이트하십시오.
- **단종된 VPN 애드온:** High IP Reputation, High Concurrency, High Priority Network는 더 이상 판매되지 않습니다. 기존 구독의 향후 갱신 금액에서 해당 요금이 제외되며, 지난 기간에 대해서는 환불되지 않습니다. 카탈로그에서 애드온을 삭제한 경우 갱신 금액을 수동으로 확인하십시오.
- **프로토콜 레이블:** IPv4 HTTP 프록시는 일반 HTTP입니다. IPv4 주소는 순환되지 않습니다. IPv6 프록시의 포트 443은 SOCKS5를 서비스하며, HTTPS 프록시 엔드포인트가 아닙니다.
- **신규 설정:** 데이터베이스 초기화 시 패널과 워커 간의 일시적인 마이그레이션 충돌을 재시도하므로 첫 번째 프로바이더를 저장할 때 재시작할 필요가 없습니다.

[VPN and IPv6 proxy nodes](https://nexcmp.com/ko/docs/infrastructure/vpn-proxy-nodes/) 문서를 참고하십시오.

## 1.5.0

**AI Models**는 기본적으로 꺼져 있는 선택형 게이트웨이 및 청구 모듈입니다. 직접 운영하거나 리셀 권한이 있는 모델 소스를 추가하고, 모델 동기화, 가격 및 라우팅 설정, 모델 활성화를 거친 후 판매를 개시하십시오. 번들로 제공되는 프로바이더 계정, 모델 또는 가격은 없습니다. 이는 AI Chat 및 AI Agent 모듈과 별개입니다. [AI Models](https://nexcmp.com/ko/docs/infrastructure/ai-models/) 문서를 참고하십시오.

## 1.4.2

IPv6 프록시 노드 설치에는 릴리스 패키지에 포함된 데몬과 네트워크 스크립트를 사용합니다. 비밀번호 기반 SSH 설치를 위해 패널에 `sshpass`이(가) 필요합니다. 패널은 순환 일정을 실행하며, 노드 설정 시 게이트웨이 주소가 할당 대상에서 제외됩니다. Branding에서 맞춤형 VPN 서비스 표시 이름을 설정할 수 있습니다. [VPN and IPv6 proxy nodes](https://nexcmp.com/ko/docs/infrastructure/vpn-proxy-nodes/) 문서를 참고하십시오.

## 1.4.0–1.4.1

- **AI 관리:** 관리자 AI Chat, 개인 AI 계정, 관리자 API 키, 관리자 MCP 서버, OAuth 커넥터, 구성 가져오기/내보내기 및 설정 체크리스트를 사용할 수 있습니다. [Configure with AI](https://nexcmp.com/ko/docs/configure-with-ai/overview/) 문서를 참고하십시오.
- **라이선스:** Free 및 Source 워크플로에는 공식 빌드와 커스텀 소스 빌드가 포함됩니다. 계정, 라이선스, 다운로드 및 문서에는 `nexcmp.com`을(를) 사용합니다. [License and purchase](https://nexcmp.com/ko/docs/getting-started/license-and-purchase/) 문서를 참고하십시오.
- **문서 링크:** 관리자 화면의 **Docs**를 클릭하면 현재 페이지의 가이드가 열립니다.
- **통화:** 신규 설치 시 기본적으로 고객의 언어 설정을 따릅니다. USD/VND는 공개 환율 표 또는 직접 지정한 고정 환율을 사용합니다. [Currency and exchange rates](https://nexcmp.com/ko/docs/catalog/currency-and-exchange-rates/) 문서를 참고하십시오.
- **혼합 소스 존:** CloudStack과 Proxmox VE가 존을 공유할 때 퍼블릭 Cloud Server 가격이 정상 작동합니다. 요금제는 자체 인프라 소스를 사용합니다.
- **오퍼링 기반 가격 책정:** 백분율은 판매 가격에 대한 마진율입니다. 반올림을 적용하기 전 기준으로 원가 $60에 40% 마진을 더하면 $100가 산출됩니다.

## 업그레이드 체크리스트 {#upgrade-checklist}

1. 백업을 수행하고 **Update** 카드를 확인한 후 업데이트를 진행하고 `sudo nexcmp status`을(를) 실행하십시오.
2. GB 소진 차단 기능에 의존하기 전에 VPN 에이전트를 업데이트하고 노드가 측정된 트래픽을 정상 보고하는지 확인하십시오.
3. Bare Metal을 사용하는 경우 판매 또는 실운영을 개시하기 전에 관리 네트워크 필드, 필수 도구, 가격 단위, 템플릿 및 샘플 요금제를 확인하십시오.
4. 고객 프로필을 열고 서비스 목록을 확인하십시오. 환불 포함 취소를 확정하기 전에 금액과 원래 결제 할당 내역을 확인하십시오.
5. 인프라가 준비될 때까지 선택적 모듈은 비활성화 상태로 유지하십시오. AI Models의 경우 판매를 개시하기 전에 공급자, 가격이 책정된 모델 및 고객 요청 성공 여부를 확인하십시오.


---

<!-- source: https://nexcmp.com/ko/docs/getting-started/backup-and-restore/ -->

# 백업 및 복구 {#backup-and-restore}

> **관리자 위치:** System › Admin › Backup(`/backup`)은 DDoS & BGP 모듈이 활성화된 경우에만 표시됩니다. 표준 설치의 경우 아래의 명령줄을 사용하세요.

## 백업되는 항목 {#what-is-backed-up}

`sudo nexcmp backup`은(는) 다음이 포함된 압축 아카이브 하나를 생성합니다:

| 항목 | 내용 |
|---|---|
| `data/**/*.db` | `/var/lib/nexcmp`의 모든 SQLite 데이터베이스, SQLite의 온라인 백업 API로 복사됨 — 패널이 실행 중인 동안에도 일관성 유지 |
| `files.tar` | `/var/lib/nexcmp`의 다른 모든 파일(설정 파일, 브랜딩 업로드, `secrets/`), 단 데이터베이스와 `updates/` 폴더는 제외 |
| `etc/` | `/etc/nexcmp`의 사본(인스톨러 설정, 인스턴스 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
```

해당 폴더를 서버 외부로 복사합니다 (오브젝트 스토리지, NAS, 다른 서버).

## 복원 {#restore}

NexCMP **동일 버전(또는 그 이상)**이 설치된 서버에 복원합니다.

1. 동일한 라이선스와 도메인을 사용하여 [installer](https://nexcmp.com/ko/docs/getting-started/installation/)(으)로 NexCMP를 설치하되, 설정 마법사는 실행하지 **마세요**.
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://<domain>/admin`에 로그인합니다.

::: tip 리허설 수행
필요해지기 전에 여분의 서버에서 1~6단계를 한 번 연습해 보세요. 한 번도 복원해 보지 않은 백업은 희망사항일 뿐입니다.
:::

## 포함되지 않는 항목 {#not-included}

- nginx 설정 및 인증서 (설インストーラー에 의해 재생성됨; Let's Encrypt 인증서는 재발급됨).
- CloudStack / Proxmox VE 서버 및 그 위의 가상 머신 — 자체 도구를 사용하여 백업하세요.


---

<!-- source: https://nexcmp.com/ko/docs/getting-started/uninstall/ -->

# NexCMP 제거 {#uninstall-nexcmp}

::: warning 고객 액세스 중단
제거하면 포털과 빌링이 중지됩니다. CloudStack 또는 Proxmox VE의 가상 머신은 계속 실행되지만, 이를 관리하거나 과금할 수 있는 주체가 없어집니다. 먼저 [backup](https://nexcmp.com/ko/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 <domain>`을(를) 사용하여 인증서를 제거하세요.
- 다른 곳에서 활성화하려면 [nexcmp.com/licenses](https://nexcmp.com/licenses)의 라이선스 페이지에서 도메인을 해제하세요.
- 더 이상 필요하지 않은 경우 NexCMP를 위해 생성한 전용 CloudStack 계정 / Proxmox API 토큰을 삭제하세요.


---

<!-- source: https://nexcmp.com/ko/docs/getting-started/cli-reference/ -->

# `nexcmp` 명령어 참조 {#nexcmp-command-reference}

설치 프로그램은 `/usr/local/bin/nexcmp`에 도우미를 배치합니다. NexCMP 서버에서 실행하세요. 시스템을 변경하는 명령어에는 `sudo`이(가) 필요합니다. (API용 고객 측 도구는 별도의 프로그램입니다. [cmp CLI](https://nexcmp.com/ko/docs/developers/cmp-cli/) 참조)

| 명령어 | 루트 필요 여부 | 작동 내용 |
|---|---|---|
| `nexcmp status` | 아니요 (`sudo`을(를) 통해 자세히 확인) | 버전, 서비스 상태(`nexcmp`, `nexcmp-vmd`), `/healthz`, 라이선스 요약, 공개 포트 상태, 마법사가 완료되지 않은 경우 설정 코드 |
| `nexcmp update` | 예 | 저장된 파라미터와 함께 설치된 릴리스에 포함된 설치 프로그램을 실행합니다 — [Updating](https://nexcmp.com/ko/docs/getting-started/updating/) 참조 |
| `nexcmp backup [dir]` | 예 | `/var/backups/nexcmp`(또는 `dir`) 백업 — [Backup and restore](https://nexcmp.com/ko/docs/getting-started/backup-and-restore/) 참조 |
| `nexcmp uninstall [--purge]` | 예 | 서비스 및 프로그램 제거; `--purge`는 데이터도 함께 제거함 — [Uninstall](https://nexcmp.com/ko/docs/getting-started/uninstall/) 참조 |
| `nexcmp open-port [minutes]` | 예 | **긴급**: 1~1440분(기본값 30) 동안 모든 인터페이스의 패널 포트(기본값 3000)에서 수신 대기한 후 자동으로 닫힘 |
| `nexcmp close-port` | 예 | 지금 긴급 창 닫기 |
| `nexcmp fix-owner` | 예 | root 소유인 `/var/lib/nexcmp` 내의 파일을 `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로 되어 있는 경우(예: root 권한으로 다른 `nexcmp` 명령을 `sudo`(으)로 실행하여 생성된 경우), 서비스 사용자가 읽을 수 없으므로 `status`에서 경고를 출력합니다. 전형적인 증상으로 라이선스에 HTTP 421이 표시됩니다. `sudo nexcmp fix-owner`(으)로 해결하십시오. 동일한 수정 작업이 서비스가 시작될 때마다 자동으로 실행됩니다.

## 긴급 액세스 {#emergency-access}

도메인, nginx 또는 TLS에 문제가 발생한 경우에도 패널에 접속할 수 있습니다.

```bash
sudo nexcmp open-port 30          # http://<server-IP>: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`.


---

<!-- source: https://nexcmp.com/ko/docs/infrastructure/requirements/ -->

# 인프라 요구사항 {#infrastructure-requirements}

> **관리자 메뉴 위치:** 인프라(왼쪽 메뉴 영역) 및 모듈 활성화를 위한 System › Admin › License & updates (`/license`).

이 페이지에서는 각 모듈이 NexCMP 서버 **외부**에 필요로 하는 항목을 나열합니다. 서버 자체(Ubuntu, 메모리, 디스크, 포트)에 대해서는 [Requirements for the NexCMP server](https://nexcmp.com/ko/docs/getting-started/requirements/)를 참조하십시오. 모듈을 활성화하려면 [Modules](https://nexcmp.com/ko/docs/infrastructure/modules/)를 참조하십시오.

## 모듈별 상세 정보 {#module-by-module}

| 모듈 | 최소 인프라 | 상세 정보 |
|---|---|---|
| **Virtual Machines on CloudStack** | Apache CloudStack 4.23(테스트 완료), KVM, 게스트 네트워크 및 공인 IP 대역이 있는 고급 존, API 키가 있는 전용 도메인 및 계정(ROOT 금지), 최소 하나의 준비된 템플릿과 하나의 서비스 오퍼링 | [CloudStack](https://nexcmp.com/ko/docs/infrastructure/cloudstack/) |
| **Virtual Machines on Proxmox VE** | Proxmox VE 9.x(9.2 버전 검증됨); 사용자 정의 역할이 있는 API 토큰; 클론을 지원하는 스토리지; 브리지; 게이트웨이가 있는 IPv4 블록; OS 및 노드당 하나의 cloud-init 템플릿 | [Proxmox VE](https://nexcmp.com/ko/docs/infrastructure/proxmox/) |
| **OS templates** | CloudStack: libguestfs와 이미지용 웹 서버가 설치된 Linux 빌드 머신. Proxmox VE: 게스트 에이전트가 포함된 cloud-image 템플릿 | [OS templates](https://nexcmp.com/ko/docs/infrastructure/templates/) |
| **Bare metal / Dedicated Server** | 관리 네트워크상에서 패널을 통해 HTTPS(Redfish)로 접근할 수 있는 iDRAC 9 탑재 Dell 서버, 해당 네트워크상에서 ISO 파일을 제공하는 HTTP server, NexCMP 서비스가 쓰기 가능한 ISO 폴더 | [Dedicated servers](https://nexcmp.com/ko/docs/infrastructure/dedicated/) |
| **AI Models** | 리셀 권한이 있는 하나 이상의 모델 소스(OpenAI 호환 또는 Anthropic 호환 API 및 자체 키 보유), 패널에서 각 소스로의 아웃바운드 HTTPS(포트 443, 공용 도메인 이름) 또는 Allowed internal hosts에 등록된 내부 게이트웨이, GPU나 특수 하드웨어는 불필요 | [AI Models](https://nexcmp.com/ko/docs/infrastructure/ai-models/) |
| **VPN** | 인터페이스에 공인 IPv4 주소가 할당되었거나 라우팅된 하나 이상의 Linux 호스트(x86_64, systemd, root), 패널로 향하는 아웃바운드 HTTPS | [VPN 및 프록시 노드](https://nexcmp.com/ko/docs/infrastructure/vpn-proxy-nodes/) |
| **IPv6 Proxy** | 공인 IPv4 주소, 80, 443 및 60001-65535 포트가 열려 있고 아웃바운드 트래픽을 처리할 수 있는 /32에서 /64 사이의 IPv6 프리픽스를 가진 Linux 호스트(x86_64, systemd, `nft`, `ip`, `ss`, `sysctl`); 최초 1회 설치를 위한 비밀번호 방식 SSH 접근 | [VPN 및 프록시 노드](https://nexcmp.com/ko/docs/infrastructure/vpn-proxy-nodes/) |
| **Object Storage (S3)** | RADOS Gateway(RGW), Admin Ops 사용자, 포트 443의 공인 HTTPS 엔드포인트가 있는 Ceph 클러스터 | [S3](https://nexcmp.com/ko/docs/infrastructure/s3/) |
| **Kubernetes** | Kubernetes Service(CKS)가 활성화되고, 최소 하나의 Kubernetes 버전 ISO와 정확히 2 vCPU 및 2048 MB의 무료 컨트롤 플레인 서비스 오퍼링이 있는 CloudStack | [Kubernetes 및 프라이빗 클라우드](https://nexcmp.com/ko/docs/infrastructure/kubernetes-and-private-cloud/) |
| **Private Cloud** | VPC 오퍼링과 대역폭 플랜당 하나의 네트워크 오퍼링(및 잠긴 1 Mbps 오퍼링)이 있는 CloudStack | [Kubernetes 및 프라이빗 클라우드](https://nexcmp.com/ko/docs/infrastructure/kubernetes-and-private-cloud/) |
| **OS & ISO Images** | 보조 스토리지 VM이 고객 이미지 다운로드를 위해 인터넷에 접근할 수 있는(직접 링크, 리디렉션 없음) CloudStack; CloudStack 계정은 템플릿과 ISO를 등록할 수 있음 | [Modules](https://nexcmp.com/ko/docs/infrastructure/modules/) |
| **Bandwidth** | 기본 소스에서 추가 작업 없음: 사용량은 CloudStack VM 통계에서 읽어옵니다. Proxmox VE의 VM은 측정되지 않습니다 | [Bandwidth](https://nexcmp.com/ko/docs/catalog/bandwidth/) |
| **AI Chat and AI Agent** | 패널 서버가 접근할 수 있는 OpenAI 호환 API(베이스 URL, 모델, 키). 서버에 추가 소프트웨어 불필요 | [AI providers](https://nexcmp.com/ko/docs/ai/ai-providers/) |
| **DDoS & BGP** | 루트로 실행되는 데몬(BGP, 필터링, 플로우 통계)이 있는 엣지 라우터 호스트가 필요한 애드온 패키지. 표준 설치에 포함되어 있지 않음 | [Modules](https://nexcmp.com/ko/docs/infrastructure/modules/) |
| **DDoS Shield** | DDoS & BGP 애드온 | [Modules](https://nexcmp.com/ko/docs/infrastructure/modules/) |
| **Web SSH terminal** | 별도의 SSH 프록시 서비스와 해당 라우트. 표준 설치에 포함되어 있지 않으며, AI Agent는 필요로 하지 않음 | [Modules](https://nexcmp.com/ko/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 | 등록, 하트비트, 구성 |
| 고객 | VPN 및 프록시 노드 | IP별 포트 65001-65535(VPN); 80, 443, 60001-65535(IPv6 프록시) | 서비스 자체 |

::: tip 관리 Networks 비공개 유지
iDRAC 및 하이퍼바이저 관리 주소는 고객이 접근할 수 없는 네트워크에 있어야 합니다. NexCMP는 사용자가 허용한 사설 대역 외의 iDRAC 주소를 거부합니다.
:::

## 판매 전 체크리스트 {#checklist-before-you-sell}

1. 첫 번째 서비스의 인프라가 연결되어 있고 **Test connection**이(가) 녹색입니다.
2. 영역을 판매할 준비가 되었습니다 ([Zones](https://nexcmp.com/ko/docs/infrastructure/zones/) 참조): 활성 백엔드, 플랜 및 준비된 템플릿.
3. 결제 채널이 구성되어 있습니다 ([Payment channels](https://nexcmp.com/ko/docs/billing/payment-channels/) 참조).
4. 이메일이 작동합니다 ([SMTP and e-mails](https://nexcmp.com/ko/docs/administration/smtp-and-emails/) 참조).
5. 테스트 주문을 하나 생성하고 VM을 삭제했습니다.


---

<!-- source: https://nexcmp.com/ko/docs/infrastructure/architecture/ -->

# 아키텍처 {#architecture}

> **관리자 위치:** 참조 페이지입니다. 여기에 설명된 서비스는 `sudo nexcmp status`로 확인할 수 있으며, 연결은 Infrastructure 및 System › Settings에서 구성합니다.

## 구조도 {#the-picture}

![NexCMP 아키텍처: 고객은 DNS와 선택적으로 Cloudflare를 통해 nginx에 접속하고, nginx는 포트 3000에서 패널로 프록시하며, 패널과 워커는 CloudStack, Proxmox VE, iDRAC, Ceph, 결제 게이트웨이, SMTP 및 AI 공급자에 호출을 보내고, VPN 및 IPv6 프록시 노드는 패널로 다시 통신합니다.](https://nexcmp.com/ko/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)에서 수신 대기하고 모든 요청을 `127.0.0.1:3000`의 **panel**로 전달합니다. 설치 마법사 완료 후 패널은 루프백 인터페이스에서만 수신 대기합니다.
3. **panel**(`nexcmp.service`)은 고객 포털, 관리자 콘솔, REST API, 설치 마법사 및 노드에 필요한 다운로드(에이전트 바이너리, 설치 스크립트, `cmp` 커맨드라인 도구)를 제공합니다. 또한 하루에 한 번 라이선스를 확인합니다.
4. **worker**(`nexcmp-vmd.service`)는 로컬 전용인 `127.0.0.1:8112`에서 수신 대기합니다. 프로비저닝 작업, CloudStack 및 Proxmox VE와의 동기화, 빌링 틱, 대역폭 수집, 브라우저 콘솔 연결 등 시간이 걸리거나 일정에 따라 실행되어야 하는 모든 작업을 수행합니다.
5. 이 두 프로세스에서 NexCMP는 외부로 호출을 보냅니다: **CloudStack**(관리 API), **Proxmox VE**(포트 8006의 API, 인증서 고정), **Dell iDRAC**(관리 네트워크의 HTTPS 기반 Redfish), **Ceph RGW**(HTTPS 기반 S3 및 Admin Ops), **결제 게이트웨이**(웹훅 URL도 호출하는 Stripe, PayPal, USDT 및 계좌 이체 제공업체), **SMTP 서버**, OpenAI 호환 API를 제공하는 **AI 공급자**, 그리고 선택적으로 **Telegram**.
6. **VPN 노드**는 `cmp-agent`을(를) 실행합니다. 각 노드는 일회용 토큰으로 한 번 등록한 후 HTTPS를 통해 5초마다 패널에 하트비를 보내고 응답으로 구성을 받습니다. **IPv6 프록시 노드**는 패널이 SSH를 통해 한 번 설치한 후 패널에서 구성을 가져옵니다.
7. 상태는 SQLite 데이터베이스와 `/var/lib/nexcmp`의 일부 파일에 저장됩니다. CloudStack, Proxmox, S3, iDRAC 및 AI 공급자의 자격 증명은 동일한 영역에 있는 마스터 키 파일로 암호화(AES-256-GCM)되어 저장됩니다.

## 서비스 및 프로세스 {#services-and-processes}

| 프로세스 | 실행 권한 | 수신 대기 | 역할 |
|---|---|---|---|
| `nginx` | root (workers `www-data`) | 80, 443 | TLS, 리디렉션, 패널 프록시 |
| `nexcmp` | `nexcmp` | 3000 (최초 설치 시 모든 인터페이스, 이후 `127.0.0.1`) | 포털, 관리자 콘솔, API, 마법사, 다운로드 |
| `nexcmp-vmd` | `nexcmp` | `127.0.0.1:8112` | 작업, 동기화, 빌링, 대역폭, 콘솔 |
| `nexcmp-update` | root | none | 관리자 콘솔 요청에 따른 업데이트 적용 (패스 유닛이 요청 대기) |
| `cmp-agent` (VPN 노드) | root | VPN 리스너 포트 | 패널에 보고, 공인 IPv4에서 프록시 리스너 실행 |

패널과 워커는 Linux capability 없이 일반 사용자로 실행되며, `/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/ko/docs/getting-started/backup-and-restore/)을 참고하세요. 마스터 키 파일은 데이터베이스와 함께 백업해야 하며, 그렇지 않으면 복원된 데이터베이스가 저장된 자격 증명을 해독할 수 없습니다.

## 통신 주체 {#who-connects-to-whom}

| 방향 | 경로 | 포트 | 참고 |
|---|---|---|---|
| 고객에서 패널로 | 인터넷, DNS, 선택적 Cloudflare, nginx | 443 | [DNS 및 Cloudflare](https://nexcmp.com/ko/docs/getting-started/dns-and-cloudflare/)를 참고하세요. |
| 패널에서 라이선스 서버로 | `nexcmp.com` | 443 | 활성화, 일일 점검 및 업데이트. |
| 패널에서 CloudStack으로 | API | 443 또는 8080 | VM 콘솔, 대역폭 및 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 모듈이 켜져 있을 때만 해당됩니다. |
| 결제 게이트웨이에서 패널로 | 웹훅 | 443 | Stripe 및 PayPal 콜백. |
| 노드에서 패널로 | `cmp-agent` | 443 | 등록, 하트비트, 업그레이드. |
| 패널에서 IPv6 프록시 노드로 | SSH | 입력한 포트 | 최초 1회 설치 전용. |

## 중요한 이유 {#why-it-matters}

- **접속할 수 있는 패널은 공격당할 수 있는 패널입니다.** 설정 마법사가 완료되면 포트 3000을 닫아두세요. TLS가 활성화되면 설치 프로그램이 자동으로 처리합니다.
- **무엇이든 생성하고 과금하려면 워커가 실행 중이어야 합니다.** `sudo nexcmp status`은 두 서비스와 헬스 체크를 모두 보여줍니다.
- **아웃바운드 방화벽을 계획하세요.** 패널 서버의 아웃바운드 트래픽이 필터링되는 경우, 위 표의 목적지를 허용해야 합니다.
- **관리 트래픽은 공용 경로를 우회합니다.** CloudStack, Proxmox VE, iDRAC 및 Ceph에 대한 연결은 nginx나 Cloudflare를 거치지 않고 패널 서버에서 해당 시스템으로 직접 연결됩니다.


---

<!-- source: https://nexcmp.com/ko/docs/infrastructure/modules/ -->

# 모듈 {#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**를 확인하고 새로 고쳐져 메뉴가 즉시 변경됩니다.

![각 모듈의 스위치가 있는 License & updates의 Module 카드](https://nexcmp.com/ko/docs/images/infrastructure/modules-01-license-modules.webp)

### 모듈 목록 {#the-modules}

| 모듈 (표시된 이름) | Default | 추가되는 기능 | 필요 사항 | 페이지 |
|---|---|---|---|---|
| **Virtual Machines** | 항상 켜짐 | VM 카탈로그, 주문, 콘솔, 스냅샷 | CloudStack 또는 Proxmox VE | [CloudStack](https://nexcmp.com/ko/docs/infrastructure/cloudstack/), [Proxmox VE](https://nexcmp.com/ko/docs/infrastructure/proxmox/) |
| **Bandwidth** | **켜짐** | VM, Kubernetes, S3용 할당량, 애드온, 알림 및 초과 사용 조치 | 추가 항목 없음 (CloudStack VM 통계) | [Bandwidth](https://nexcmp.com/ko/docs/catalog/bandwidth/) |
| **OS & ISO Images** | off | 고객이 자체 OS 이미지 및 ISO를 등록하고 GB 단위로 과금됨 | CloudStack; 보조 스토리지 VM용 인터넷 액세스 | [Requirements](https://nexcmp.com/ko/docs/infrastructure/requirements/) |
| **Kubernetes** | off | Kubernetes 클러스터 (CKS) | CKS가 활성화된 CloudStack | [Kubernetes 및 프라이빗 클라우드](https://nexcmp.com/ko/docs/infrastructure/kubernetes-and-private-cloud/) |
| **Private Cloud** | off | 전용 대역폭 플랜이 포함된 VPC | CloudStack VPC 및 네트워크 오퍼링 | [Kubernetes 및 프라이빗 클라우드](https://nexcmp.com/ko/docs/infrastructure/kubernetes-and-private-cloud/) |
| **Object Storage** | off | Ceph RGW 기반 S3 계정, 종량제 | Ceph RGW 및 S3 서비스가 포함된 존 | [S3](https://nexcmp.com/ko/docs/infrastructure/s3/) |
| **VPN** | off | 자체 노드에서의 VPN | `cmp-agent`을(를) 실행 중인 노드 | [VPN 및 프록시 노드](https://nexcmp.com/ko/docs/infrastructure/vpn-proxy-nodes/) |
| **IPv6 Proxy** | off | 자체 노드에서의 IPv6 프록시 | IPv6 프리픽스가 있는 프록시 노드 | [VPN 및 프록시 노드](https://nexcmp.com/ko/docs/infrastructure/vpn-proxy-nodes/) |
| **Bare Metal** | off | iDRAC을 통한 Dell 서버: 주문, OS 설치, 콘솔, 전원 | 관리 네트워크의 iDRAC 9 | [Dedicated servers](https://nexcmp.com/ko/docs/infrastructure/dedicated/) |
| **AI Models** | off | AI 모델에 대한 액세스를 판매하는 게이트웨이: 단일 키로 다중 모델 지원, 모델별 요금, 사용량 한도, 로그, 지갑 결제 | 직접 준비하는 모델 소스: 자체 키를 사용하는 OpenAI 호환 또는 Anthropic 호환 API | [AI Models](https://nexcmp.com/ko/docs/infrastructure/ai-models/) |
| **AI** | off | AI Chat(자동 지원) 및 AI Agent(자연어로 VM 관리) | OpenAI 호환 제공자 | [AI providers](https://nexcmp.com/ko/docs/ai/ai-providers/) |
| **DDoS Shield** | off | 고객을 위한 IP 보호; DDoS 및 BGP가 필요하므로 없으면 스위치가 비활성화 상태로 유지됨 | DDoS & BGP 애드온 | 아래 참조 |
| **DDoS & BGP** | 꺼짐, **추가 기능** | 엣지 라우터 콘솔: BGP, RTBH, XDP, 세션 및 엣지 트래픽 | 루트 데몬이 실행 중인 엣지 호스트 | 아래 참조 |

### 스위치별 역할 {#which-switch-does-what}

- **Bare Metal**은 두 개의 레이어로 구성됩니다. 모듈 스위치는 관리자 메뉴와 API를 표시합니다. 고객 대상 판매는 **Services › Dedicated Server**에서 직접 텍스트를 입력하여 확인하는 별도의 스위치로 관리되며, **Infrastructure › Bare Metal › Safety**에서 **live ops**를 켤 때까지 iDRAC에 대한 모든 쓰기 작업이 차단됩니다. [Dedicated servers](https://nexcmp.com/ko/docs/infrastructure/dedicated/) 항목을 참조하십시오.
- **Kubernetes**, **Private Cloud**, **VPN**, **IPv6 Proxy** 및 **Images**의 경우 모듈 스위치와 서비스 페이지의 판매 스위치가 동일한 설정으로 작동합니다.
- **AI**은(는) **System › Settings › AI provider**에 구성된 제공자도 필요합니다.
- **AI Models**은 2단계로 구성됩니다. 모듈 스위치는 관리자 메뉴와 API를 표시합니다. 고객 대상 판매는 AI Models 페이지 상단의 별도 판매 스위치로 관리되며, 기본값은 비활성화 상태입니다. [AI Models](https://nexcmp.com/ko/docs/infrastructure/ai-models/)을 참고하십시오.

### 시작 시 읽어오는 모듈 {#modules-read-at-start-up}

세 가지 기능은 일반적인 스위치가 아닙니다. **서비스가 시작될 때 한 번** 읽히며 표준 설치에 포함되지 않는 인프라가 필요합니다.

| 기능 | 설정 | 상태 | 필요한 항목 |
|---|---|---|---|
| DDoS & BGP | `module_ddos` | 꺼져 있을 때는 **Add-on package**, 켜져 있을 때는 **Installed**(으)로 표시됩니다. 콘솔에 스위치가 없습니다. | 루트로 실행되는 엣지 라우터 데몬(BGP, RTBH, XDP, 플로우 통계). 패널은 권한이 없는 사용자로 실행되므로 이를 실행할 수 없습니다. |
| AI | `module_ai` | 일반적인 스위치입니다. 라우팅이 즉시 반영됩니다. AI Chat의 백업 작업(티켓 조사, 예약된 응답)은 서비스가 다음번에 다시 시작될 때 시작됩니다. 콘솔에 재시작을 권장한다는 메시지가 표시됩니다. | AI 제공자. |
| Web SSH terminal | `feature_ssh_web` | 기본적으로 꺼져 있으며 콘솔에 스위치 없음 | 별도의 SSH 프록시 서비스 및 해당 라우팅. 이 기능이 없으면 포털의 Console 탭에 VNC 페이지만 표시됩니다. **AI Agent does not need it**: 패널이 자체적으로 만드는 SSH 연결을 통해 명령을 실행합니다. |

시작 설정을 변경한 후 서비스를 재시작하세요: `sudo systemctl restart nexcmp nexcmp-vmd`.

## 확인 {#verify}

1. 다시 로드한 후 모듈의 메뉴 항목이 표시되거나 사라집니다.
2. 고객용 모듈의 경우, 로그인한 고객에게 포털의 새로운 메뉴 항목이 표시됩니다. 꺼져 있는 모듈은 아무것도 표시하지 않거나 "coming soon"을 표시합니다.

## 제한 사항 및 참고 사항 {#limits-and-notes}

- 모듈을 끈다고 해서 데이터가 삭제되지는 않습니다. 실행 중인 VM, 클러스터, S3 계정 및 구독은 계속 실행되고 과금되며, 고객이 새로 생성만 할 수 없게 됩니다.
- 할당량 페이지에는 모듈이 켜져 있는 서비스만 나열됩니다.

## Troubleshooting {#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 실드에는 DDoS & BGP 애드온이 필요합니다" | Same, for DDoS Shield | 애드온을 먼저 설치하세요. |
| 모듈 라우트가 404를 반환함 `module_disabled` | 모듈이 꺼져 있음 | 모듈을 켜세요. |
| AI Chat은 응답하지만 티켓 조사가 시작되지 않음 | 재시작 없이 AI 모듈이 켜졌음 | `sudo systemctl restart nexcmp nexcmp-vmd`. |
| 읽기 전용 직원은 저장할 수 없음 | 역할이 읽기 전용임 | 관리자 계정을 사용하세요. |




---

<!-- source: https://nexcmp.com/ko/docs/infrastructure/zones/ -->

# Zones {#zones}

> **관리자 위치:** Infrastructure › Datacenter › Zone (`/infra/zones`). 리전의 상세 페이지는 `/infra/zones/<id>`입니다.

## 작동 내용 {#what-it-does}

**리전(zone)**은 고객이 주문 시 선택하는 위치로, 국기와 국가 및 도시, 그리고 그곳에서 판매되는 서비스로 구성됩니다. 이는 백엔드 플랫폼의 리전, 클러스터, 노드와는 별개인 영업 개념입니다. 리전 뒤에는 CloudStack 리전, Proxmox VE 클러스터, IP 대역이 있는 VPN 노드, S3 백엔드 등의 **인프라**를 연결합니다.

리전 1은 [설정 마법사](https://nexcmp.com/ko/docs/getting-started/setup-wizard/)를 통해 입력한 표시 이름과 국가로 생성됩니다. 더 많은 곳에 인프라가 있거나 VPN 및 S3에 고유한 위치를 지정하려는 경우 리전을 더 추가하세요.

## 요구 사항 {#requirements}

| 항목 | 요구 사항 |
|---|---|
| Permissions | 관리자 계정. 읽기 전용 직원 역할은 조회만 가능하고 변경할 수는 없습니다. |
| 인프라 | 리전에는 무언가 연결되기 전까지 아무것도 판매되지 않습니다 (아래의 "어떤 서비스가 어디서 판매되는가" 참조). |
| 종속성 | VM용 [CloudStack](https://nexcmp.com/ko/docs/infrastructure/cloudstack/) 또는 [Proxmox VE](https://nexcmp.com/ko/docs/infrastructure/proxmox/), VPN용 [VPN 및 프록시 노드](https://nexcmp.com/ko/docs/infrastructure/vpn-proxy-nodes/), 오브젝트 스토리지용 [S3](https://nexcmp.com/ko/docs/infrastructure/s3/). |

## 인프라 준비 {#prepare-the-infrastructure}

필요하지 않습니다. 리전은 NexCMP 내부의 레코드입니다.

## NexCMP에서 연결 {#connect-in-nexcmp}

### Create a zone {#create-a-zone}

1. **Infrastructure › Datacenter › Zone**을 열고 **Add zone**을 클릭합니다.
2. 양식을 작성합니다:

   | 필드 | Example value | 참고 |
   |---|---|---|
   | Country | `United States` | Chooses the flag. |
   | City | `New York` | Optional. |
   | Name (Vietnamese), Name (English) | `New York` | 각 언어별로 고객에게 표시되는 이름입니다. |
   | Slug | `us-new-york` | a-z, 0-9, 하이픈, 2-32자. 직접 입력할 때까지 국가와 도시를 기반으로 채워집니다. |
   | Visibility | Public | **Public** 구역은 모든 고객에게 표시되고, **Hidden** 구역은 관리자에 의해서만 지정됩니다. |
   | 순서 | `0` | 목록에서 숫자가 작은 항목이 먼저 표시됩니다. |
   | 이 구역에서 판매되는 서비스 | Virtual Machines (VM), VPN, Object Storage (S3) | 하나 이상 선택하세요. |
   | 활성 | On | **Off**는 고객에게 해당 구역을 숨깁니다. |
   | Default | off | 아직 선택하지 않은 고객에게 미리 선택되는 구역입니다. 정확히 하나의 구역이 기본값으로 지정됩니다. |

      ![국가, 도시, 슬러그 및 서비스가 선택된 구역 추가 대화상자](https://nexcmp.com/ko/docs/images/infrastructure/zones-01-add-zone.webp)

3. **Create zone**을 클릭합니다. 목록에는 국기, 소유자, 서비스, 상태 및 VM, 요금제, 연결된 인프라 개수와 함께 구역이 표시됩니다.

      ![기본 구역과 두 번째 구역이 있는 구역 목록](https://nexcmp.com/ko/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/ko/docs/images/infrastructure/zones-03-detail.webp)

### 서비스별 판매 위치 {#which-service-sells-where}

| 서비스 | 구역에 추가되는 방식 |
|---|---|
| CloudStack의 Virtual Machines | 마법사(또는 **Infrastructure › Cloud provider › CloudStack**)를 통해 CloudStack이 구역 1에 연결됩니다. |
| Proxmox VE의 Virtual Machines | 클러스터의 **Clusters** 탭에서 **Attach cluster to zone**을 선택합니다. 클러스터는 **기존** 구역(일반적으로 CloudStack을 통해 판매하는 구역)에 합류합니다. |
| VPN | 공인 IP 대역을 보고하는 VPN 노드는 해당 국가의 구역을 생성(또는 가입)하고 대역을 VPN 풀에 넣습니다. **VPN IP pools**에서도 대역의 구역과 노드를 지정할 수 있습니다. |
| IPv6 Proxy | 새로운 IPv6 프록시 노드는 **off** 상태로 구역을 생성합니다. 고객이 선택할 수 있도록 여기서 구역을 켭니다. |
| Object Storage (S3) | 구역에서 S3 서비스를 선택한 다음 **Ceph S3 (RGW)** 아래에서 백엔드를 연결합니다. |

### 구역에서 가상 머신을 판매할 수 있는 시점은 언제인가요? {#when-can-a-zone-sell-virtual-machines}

존은 활성화된 판매 가능한 백엔드가 최소 1개 이상 있고 **그리고** 표시되는 플랜이 최소 1개 이상 존재하며 **그리고** 해당 백엔드에 준비된 템플릿이 최소 1개 이상 등록되기 전까지 **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 {#troubleshooting}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| "존 이름은 필수입니다" / "국가를 선택하십시오" / "최소 1개 이상의 서비스를 선택하십시오" | 필수 입력란이 비어 있음 | 이름을 입력하고, 국가를 선택한 다음 서비스를 체크하세요. |
| "유효하지 않은 슬러그 (a-z 0-9 -, 2-32자)" | 슬러그에 다른 문자가 포함되었거나 길이가 올바르지 않음 | 소문자, 숫자, 하이픈(-)만 사용하세요. |
| 태그 "not ready to sell VMs" | 해당 존에 활성화된 판매 가능 백엔드, 플랜 또는 준비된 템플릿이 없음 | 인프라를 연결한 후 플랜과 템플릿을 추가하세요. [Plans](https://nexcmp.com/ko/docs/catalog/plans/) 및 [Templates](https://nexcmp.com/ko/docs/infrastructure/templates/)를 참고하세요. |
| "still attached"로 인해 삭제가 비활성화됨 | 존에 백엔드, VM, 플랜 또는 VPN 대역이 남아 있음 | 먼저 제거하거나 이동하세요. |
| "Default zone"으로 인해 삭제가 비활성화됨 | 기본 존으로 설정된 상태임 | 다른 존을 기본 존으로 설정하세요. |
| 고객에게 존이 표시되지 않음 | 숨김 처리되었거나, 비활성화되었거나, 서비스가 체크되지 않음 | Visibility를 Public으로, Active를 On으로 설정하고 서비스를 체크하세요. |
| 백엔드 양식에 S3 존이 누락됨 | 존에서 S3 서비스가 체크되지 않음 | 존을 편집하고 **Object Storage (S3)**를 체크하세요. |




---

<!-- source: https://nexcmp.com/ko/docs/infrastructure/cloudstack/ -->

# CloudStack

> **관리자 위치:** Infrastructure › Cloud provider › CloudStack › API connection (`/infra/cloudstack?tab=connect`). 첫 번째 연결은 [setup wizard](https://nexcmp.com/ko/docs/getting-started/setup-wizard/) 2단계에서도 진행할 수 있습니다.

## 작동 내용 {#what-it-does}

NexCMP는 Apache CloudStack 클라우드에서 실행되는 가상 머신을 판매합니다. CloudStack API를 통해 VM을 배포, 시작, 중지, 크기 조절, 스냅샷 생성 및 삭제하고, 존에서 공인 IP 주소를 할당하며, 청구 및 대역폭 사용량을 읽고, 관리자 콘솔에 용량과 상태를 표시합니다. CloudStack은 하이퍼바이저의 진실의 원천(source of truth)으로 유지되며, NexCMP는 그 상단의 스토어프론트, 빌링 및 포털 역할을 합니다.

CloudStack이 메인 VM 소스인(또는 소스가 될) 경우 이 페이지를 사용하세요. 옆에 두 번째 소스를 추가하려면 [Proxmox VE](https://nexcmp.com/ko/docs/infrastructure/proxmox/)를 참고하세요.

## 요구 사항 {#requirements}

| 항목 | 요구 사항 |
|---|---|
| CloudStack 버전 | 4.23이 테스트된 릴리스입니다. VM 콘솔에는 4.18 이상이 필요하며, 실행 중인 VM의 실시간 CPU/RAM 크기 조절에는 KVM이 포함된 4.23이 필요합니다. |
| 존 유형 | 고객 VM을 위한 게스트 네트워크가 하나 이상 있고 사용 가능한 주소가 있는 공인 IP 대역이 있는 존. |
| 하이퍼바이저 | KVM이 테스트된 하이퍼바이저입니다. |
| 계정 | NexCMP를 위해 생성된 **전용 도메인 및 계정**. ROOT 관리자 키는 절대 사용하지 마세요. |
| API 도달 가능성 | 패널 서버는 관리 서버 API URL(`https://cloudstack.example.com/client/api`)에 HTTP(S)로 도달할 수 있어야 합니다. VM 콘솔, 대역폭 및 Kubernetes 기능은 동일한 엔드포인트를 사용합니다. |
| 선택적 읽기 전용 키 | 두 번째 읽기 전용 키를 사용하면 관리자 콘솔에 호스트, 스토리지, 시스템 VM 및 공인 IP 대역이 표시됩니다. VM 판매에는 필요하지 않습니다. |
| 공인 IP | 존 내의 사용 가능한 공인 IPv4 주소. NexCMP가 판매할 수 있는 프리픽스는 Sales IP pools에서 설정됩니다. |
| 템플릿 | 준비된 비밀번호 사용 가능 템플릿 1개 이상과 계정에서 볼 수 있는 서비스 오퍼링 1개 이상. [Templates](https://nexcmp.com/ko/docs/infrastructure/templates/)를 참조하세요. |
| 스토리지 | 계정 볼륨을 위한 기본 스토리지, 그리고 스냅샷이나 이미지를 판매하는 경우 보조 스토리지. |
| 종속성 | 없음. Kubernetes, Private Cloud, Images, Bandwidth는 이 페이지에 의존합니다. |

::: warning ROOT 관리자 키를 사용하지 마십시오
NexCMP 전용 도메인과 계정을 만드세요. 그러면 키가 해당 도메인에만 도달하며, 키가 유출되어도 클라우드의 나머지 부분에는 영향을 미치지 않습니다. 설정 마법사는 또한 선택한 네트워크가 키를 소유한 영역 **및** 계정에 속하는지 확인합니다.
:::

## 인프라 준비 {#prepare-the-infrastructure}

명령어는 CloudStack 관리자로 로그인한 상태에서 [CloudMonkey](https://cloudstack.apache.org/)(`cmk`)를 사용합니다. 예시 이름과 꺾쇠괄호 안의 플레이스홀더를 교체하십시오.

### 전용 계정 및 API 키 생성 {#create-a-dedicated-account-and-api-key}

1. NexCMP가 소유할 모든 항목을 담을 도메인을 생성합니다.

   ```bash
   cmk create domain name=nexcmp
   ```

   출력에서 `id`을(를) 확인해 두세요. 아래에서 `<domain-id>`로 사용됩니다.

2. 계정에 부여할 역할을 찾습니다.

   ```bash
   cmk list roles type=DomainAdmin filter=id,name
   ```

   | 역할 | 선택 시기 |
   |---|---|
   | **Domain Admin** (권장) | 전체 기능 세트: VM, 네트워크, Kubernetes용 프로젝트, VPC, 이미지. `nexcmp` 도메인까지만 권한이 미칩니다. |
   | User | VM 수명 주기 전용입니다. 전역 설정 `allow.user.expunge.recover.vm`이 true가 아닌 한 일반 사용자는 VM을 영구 삭제(expunge)할 수 없으며, 이 경우 NexCMP가 VM을 중지하고 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=<role-id> domainid=<domain-id>
   ```

4. 새 사용자를 위한 API 키 쌍을 생성합니다.

   ```bash
   cmk list users domainid=<domain-id> username=nexcmp-api filter=id,username
   cmk generate userkeys id=<user-id>
   ```

   `apikey` 및 `secretkey`을 복사합니다. 이는 NexCMP에 입력할 **API key** 및 **Secret key**입니다. NexCMP는 이를 암호화하여 저장하며, 이후에는 마지막 4자리만 표시합니다.

5. 도메인에 제한적인 리소스 한도(Instances, 볼륨, 공용 IP, 네트워크, Snapshots, 템플릿, 프로젝트)가 설정되어 있지 않은지 확인하십시오.

   ```bash
   cmk list resourcelimits domainid=<domain-id>
   ```

### 고객 VM용 게스트 네트워크 생성 {#create-the-guest-network-for-customer-vms}

고객 VM은 새 계정에 속한 하나의 게스트 네트워크에 배포됩니다. NexCMP는 static NAT를 통해 각 VM에 공용 IP를 연결하므로 가상 라우터(VR) 및 Static NAT, Firewall, Port Forwarding 서비스를 갖춘 격리된 네트워크가 적합합니다.

```bash
cmk list networkofferings state=Enabled guestiptype=Isolated filter=id,name
cmk create network name=customers displaytext=customers zoneid=<zone-id> \
  networkofferingid=<offering-id> account=nexcmp-api domainid=<domain-id>
```

오퍼링의 기본 egress 정책을 확인하십시오. "deny"로 설정되어 있으면 방화벽 egress 규칙이 추가될 때까지 고객 VM의 아웃바운드 액세스가 차단됩니다.

### 오퍼링 및 템플릿 표시 설정 {#make-offerings-and-templates-visible}

- **Service offerings** 및 **network offerings**는 공개(public) 상태이거나 `nexcmp` 도메인에 할당되어야 합니다. 그렇지 않으면 해당 계정에서 이를 조회하거나 사용할 수 없습니다.
- 최소 하나 이상의 템플릿을 등록하거나 공유하십시오([Templates](https://nexcmp.com/ko/docs/infrastructure/templates/) 참조). NexCMP에는 ready 및 featured 상태인 템플릿이 표시됩니다.

### 선택 사항: 인프라 페이지용 읽기 전용 키 {#optional-read-only-key-for-infrastructure-pages}

**Capacity**, **Host**, **Storage**, **System VM** 탭과 공용 IP 대역 목록은 6개 명령어에 대한 읽기 권한만 필요한 보조 키를 사용합니다. 전체 관리자 키를 재사용하는 대신 제한된 역할을 생성하십시오:

```bash
cmk create role name=nexcmp-readonly type=Admin
# <role-id> is the id printed above
for api in listHosts listCapacity listSystemVms listVlanIpRanges listClusters listStoragePools; do
  cmk create rolepermission roleid=<role-id> rule=$api permission=allow
done
cmk create rolepermission roleid=<role-id> rule='*' permission=deny
```

그런 다음 해당 역할을 가진 계정을 ROOT 도메인에 생성하고(Zone 전체 데이터를 읽어야 하므로), 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}

[설정 마법사](https://nexcmp.com/ko/docs/getting-started/setup-wizard/)의 2단계에서는 동일한 값을 묻습니다. **Test connection**은 키가 볼 수 있는 존과 네트워크를 나열합니다. 존과 게스트 네트워크, 존의 표시 이름과 국가를 선택한 후 **Save CloudStack**을 클릭합니다. 마법사는 해당 존에 없거나 키에서 볼 수 없는 네트워크는 거부합니다.

![CloudStack API URL과 키가 입력되고 Test connection 후 존과 네트워크가 선택된 마법사 2단계](https://nexcmp.com/ko/docs/images/infrastructure/cloudstack-01-wizard-step.webp)

### 나중에 관리자 콘솔에서 {#later-in-the-admin-console}

1. **Infrastructure › Cloud provider › CloudStack**을 열고 **API connection** 탭을 선택합니다.
2. **Connection** 카드에 입력합니다:

   | 필드 | Example value |
   |---|---|
   | Endpoint API | `https://cloudstack.example.com/client/api` |
   | API 키 (쓰기 권한) | `XXXX`(저장된 키를 유지하려면 비워 두세요) |
   | Secret key | `XXXX` |
   | RO API 키 / RO 시크릿 키 | 선택 사항, 읽기 전용 계정에서 가져옴 |
   | Zone ID | 존의 UUID |

      ![예제 엔드포인트와 마스킹된 키가 있는 API connection 탭](https://nexcmp.com/ko/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을 위한 기본 게스트 네트워크, 커스텀 오퍼링 및 기본 키 페어를 설정합니다.

      ![기본 네트워크 ID가 설정된 VM Policy의 Provisioning 탭](https://nexcmp.com/ko/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**를 설정합니다. 모든 자유 주소를 허용하려면 접두사를 비워 둡니다.

      ![판매 가능한 접두사 203.0.113.이 설정된 Sales IP pools](https://nexcmp.com/ko/docs/images/infrastructure/cloudstack-05-sales-ip-pool.webp)

### NexCMP가 읽고 쓰는 항목 {#what-nexcmp-reads-and-writes}

| 영역 | 읽기 | 변경 |
|---|---|---|
| VMs | 목록, 상태, 사용량 이력, 콘솔 엔드포인트 | 배포, 시작, 중지, 재부팅, 재설치, 삭제, 크기 조정, 비밀번호 및 SSH Keys 초기화 |
| 디스크 및 스냅샷 | 볼륨, VM 스냅샷, 백업 | 생성, 연결, 해제, 크기 변경, 삭제, 스냅샷, 복원 |
| 네트워킹 | 네트워크, 라우터, 공인 IP, 방화벽, 포트 포워딩, 로드 밸런서 규칙 | 공인 IP 할당 및 해제, 정적 NAT, 방화벽, 포트 포워딩, 송신 규칙, 프라이빗 클라우드를 위한 네트워크 및 ACL |
| 카탈로그 | 서비스, 디스크 및 네트워크 오퍼링, 템플릿, ISO, OS 유형 | 템플릿 및 ISO(이미지) 등록 및 삭제, 커스텀 플랜 생성 시 서비스 오퍼링 |
| Kubernetes | 지원되는 버전, 클러스터, 설정 | 프로젝트, 리소스 제한, 네트워크, 클러스터(Kubernetes 모듈) |
| 읽기 전용 키 | 호스트, 클러스터, 스토리지 풀, 시스템 VM, 용량, VLAN IP 대역 | 없음 |

### 실시간 CPU, RAM 및 대역폭 {#live-cpu-and-ram-and-bandwidth}

- **핫플러그.** 실행 중인 VM은 템플릿에서 허용하고(동적 확장 가능) 게스트 OS가 새 CPU와 RAM을 온라인 상태로 전환하는 경우에만 재부팅 없이 크기를 조정할 수 있습니다. NexCMP는 이름이 `vN`으로 끝나고 N이 6 이상인 템플릿에 대해 Auto Scaling을 켜거나, 템플릿의 **vCPU/RAM hot-plug** 필드에서 직접 설정한 경우에 이를 활성화합니다. [Templates](https://nexcmp.com/ko/docs/infrastructure/templates/) 문서를 참고하세요.
- **대역폭 소스.** 기본 설정에서 NexCMP는 CloudStack VM 통계(`listVirtualMachinesUsageHistory`, 5분마다 폴링되며 VM 네트워크 인터페이스별로 합산됨)에서 트래픽을 측정합니다. 이 수치에는 VM 간 트래픽이 포함되므로 엣지 라우터가 집계하는 값보다 약간 높을 수 있습니다. CloudStack VM 통계 수집을 활성화 상태로 유지하세요. 통계 보존 기간보다 긴 공백 시간은 건너뜁니다. [Bandwidth](https://nexcmp.com/ko/docs/catalog/bandwidth/) 문서를 참고하세요.

## 확인 {#verify}

1. **Test connection**은(는) 사용자의 존과 CloudStack 버전이 포함된 "Write key: OK" 메시지를 반환합니다.
2. **Infrastructure › Cloud provider › Providers**에서 해당 공급자가 최근 테스트 시간과 함께 활성 상태로 표시됩니다. 대시보드 상태 패널에 더 이상 "CloudStack: not connected"가 표시되지 않습니다.
3. **Sales IP pools**에 사용 가능한 주소가 표시됩니다(약 1분마다 새로 고쳐짐).
4. 고객 포털 또는 관리자 콘솔에서 소형 VM을 주문하고 Running 상태에 도달하는지, 공인 IP가 할당되는지, 콘솔을 열 수 있는지 확인하세요.

## 제한 사항 및 참고 사항 {#limits-and-notes}

- 현재 NexCMP 릴리스에서는 하나의 CloudStack 클러스터만 연결할 수 있습니다. **Add cloud provider** 대화상자에서는 두 번째 클러스터의 키를 테스트할 수 있지만 저장할 수는 없습니다.
- 하나의 CloudStack 존이 NexCMP의 기본 존에 연결됩니다. 여러 존이 있는 CloudStack의 경우 입력한 존으로 범위가 제한되므로 다른 존의 VM, IP 및 네트워크는 무시됩니다.
- CloudStack에서 게스트 네트워크를 삭제하면 이후 모든 배포가 실패하게 됩니다. 네트워크가 사라지면 관리자 콘솔에 빨간색 알림이 표시됩니다.
- 자격 증명은 서버 외부로 절대 유출되지 않습니다. API는 마지막 4자리의 문자만 반환합니다.

## Troubleshooting {#troubleshooting}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| `listCapabilities: cloudstack 401: unable to verify user credentials and/or request signature` | 잘못된 API 키 또는 시크릿, 다른 사용자의 키, 또는 패널 서버의 시계 설정 문제 | `cmk generate userkeys`을(를) 사용하여 키를 다시 생성하고 둘 다 붙여넣으세요. 패널 서버의 시간을 확인하세요. |
| 테스트: `listZones: …` 또는 시간 초과 | 패널 서버가 API URL에 도달할 수 없음 | 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 …" | 역할 권한 누락 또는 잘못된 계정 | 허용된 6개의 명령어가 올바른지, 계정이 ROOT 도메인에 속해 있는지 확인하세요. |
| "Zone public IP ranges not measured yet" 또는 "no public IP ranges declared" | 읽기 전용 키가 없거나 해당 존에 공인 IP 대역이 실제로 선언되지 않음 | 읽기 전용 키를 추가하거나 CloudStack에 공인 IP 대역을 추가합니다. |
| "풀 비어 있음 — vmd 동기화를 위해 60초 대기" | 작업자(worker)가 1분마다 IP 목록을 새로고침합니다. | 1분간 기다린 후 새로고침합니다. |
| "203.0.113. 범위에 사용 가능한 IP가 없음" | 판매 가능한 프리픽스의 모든 주소가 사용 중입니다. | 영역에 주소를 추가하고, 프리픽스를 넓히거나 사용하지 않는 IP를 반환합니다. |
| "네트워크 데이터를 가져오지 못했습니다 (CloudStack 응답 없음 또는 키 권한 부족)" | 키 권한이 손실되었거나 CloudStack이 응답하지 않습니다. | **Test connection**을 실행하고 계정이 활성화되어 있는지 확인합니다. |
| "게스트 네트워크가 존재하지 않습니다" | CloudStack에서 네트워크가 삭제되었습니다. | 네트워크를 다시 생성하고 프로비저닝(Provisioning) 아래에서 기본값으로 설정합니다. |




---

<!-- source: https://nexcmp.com/ko/docs/infrastructure/proxmox/ -->

# Proxmox VE

> **관리자 위치:** Infrastructure › Cloud provider › Providers (`/infra/providers`), 그런 다음 Overview, Clusters, VMs, Servers 및 Credentials 탭이 있는 공급자 페이지 (`/infra/providers/<id>`). 플랜은 Services › Virtual Machines › Plans & pricing (`/vm/catalog`)에서 설정합니다.

## 작동 내용 {#what-it-does}

NexCMP는 CloudStack과 함께 또는 대신하여 하나 이상의 Proxmox VE 클러스터에서 실행되는 가상 머신을 판매할 수 있습니다. VM은 전체 복제(full clone)로 OS 템플릿을 복제한 다음 크기, 정의한 풀의 IP 주소, 루트 비밀번호 및 SSH 키 등 cloud-init을 통해 구성됩니다. 고객은 포털에서 전원 제어, 콘솔, 스냅샷, 재설치, 비밀번호 재설정 및 메트릭을 사용할 수 있습니다. 고객은 클러스터, 노드 또는 소스 이름을 볼 수 없습니다.

이미 Proxmox VE를 운영 중이거나 가격이 다른 두 번째 VM 풀을 제공하고자 할 때 사용합니다.

## 요구 사항 {#requirements}

| 항목 | 요구 사항 |
|---|---|
| Proxmox VE | PVE 9.x. 9.2 버전에서 검증되었습니다. `import` 스토리지 콘텐츠 및 `import-from` 디스크 옵션이 필요합니다 (PVE 8.2 이상). |
| 패널의 네트워크 | 클러스터 API에 대한 HTTPS `https://<host or IP>:8006`. 경로, 사용자 이름 또는 쿼리는 없어야 합니다. 패널과 작업자(worker)가 모두 연결되며, 브라우저 콘솔은 패널을 통해 프록시됩니다. |
| 계정 | **API 토큰** 및 아래 나열된 권한을 가진 사용자 정의 역할을 사용하는 전용 PVE 사용자. `root@pam`은 절대 사용하지 마세요. |
| 스토리지 | 클론을 지원하는 VM 디스크용 스토리지(예: `local-lvm`). 내장 템플릿 빌더의 경우, `local`(이)라는 이름의 스토리지(콘텐츠 유형: `import` 및 `snippets`). |
| 네트워크 | 고객 IP가 속한 네트워크에 도달할 수 있는 Linux 브리지 (예: `vmbr0`). VLAN 태그를 입력하는 경우 VLAN 인식(VLAN-aware) 브리지를 사용하세요. |
| IP | 게이트웨이가 포함되어 해당 브리지로 라우팅되는 IPv4 블록 (/16 ~ /30). NexCMP가 직접 주소를 할당하며 Proxmox에는 IP 관리 기능이 없습니다. |
| 템플릿 | QEMU 게스트 에이전트가 포함된, 배포하는 모든 노드의 OS당 하나의 cloud-init 템플릿 VM. |
| 영역 | 클러스터를 연결할 기존 영역. [Zones](https://nexcmp.com/ko/docs/infrastructure/zones/)을 참조하세요. |
| 종속성 | 없음. |

## 인프라 준비 {#prepare-the-infrastructure}

클러스터 노드에서 루트 권한으로 명령을 실행합니다.

### 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`이(가) 필요합니다. PVE 9에는 `VM.Monitor` 권한이 없으므로 추가하지 마세요.

2. 사용자와 토큰을 생성합니다. `--privsep 1`은(는) 토큰의 권한이 사용자 권한과 토큰 자체 권한의 **교집합**임을 의미합니다.

   ```bash
   pveum user add nexcmp@pve --comment "NexCMP"
   pveum user token add nexcmp@pve api --privsep 1
   ```

   명령을 실행하면 토큰 **secret이 1회만** 출력됩니다(UUID 형식). 지금 복사해 두십시오. 토큰 ID는 `nexcmp@pve!api`입니다.

3. 사용자와 토큰 **모두**에 해당 역할을 부여하십시오. 이 단계를 놓치기 쉬우며, 권한 분리가 적용된 상태에서 사용자에게 권한이 없으면 토큰만 `Datastore.Audit`과 같은 403 오류를 받게 됩니다.

   ```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=<secret>' https://192.0.2.10:8006/api2/json/version
   ```

   `version`이 포함된 JSON 문서가 반환되면 토큰이 정상 작동하는 것입니다. (`-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
```

- 고객 VM은 NexCMP에 입력한 브리지에 `virtio` 네트워크 인터페이스를 할당받습니다. VLAN을 설정한 경우 해당 브리지는 VLAN-aware 상태여야 합니다.
- 고객 VM을 **노드의 관리 주소와 분리된** 브리지 또는 VLAN에 배치하십시오. 동일한 네트워크를 공유할 경우 Proxmox 방화벽의 자동 관리 IP 세트로 인해 노드의 22, 8006, 3128, 5900-5999, 60000-60050 포트가 해당 네트워크의 모든 VM에 개방됩니다. 분리할 수 없는 경우 관리 ACCEPT 규칙 위에 VM 서브넷에서 해당 포트로의 명시적 DROP 규칙을 추가하십시오.

### 3. 스토리지 참고 사항 (LVM-thin) {#_3-storage-notes-lvm-thin}

- 씬 풀의 **zeroing 설정을 기본값으로 유지**하십시오. 이를 비활성화(`lvchange -Zn`)하면 새로 할당된 청크에 기존 데이터가 남아 클론된 VM의 파티션 테이블이나 파일 시스템이 손상될 수 있습니다.
- "write cache: disabled"로 표시되는 디스크는 몇 MB/s 속도로만 복제될 수 있습니다. `hdparm -W /dev/sdX`을(를) 통해 확인하고 디스크에 전원 손실 방지 기능이 있는 경우 쓰기 캐시를 활성화하세요.

### 4. `import` 콘텐츠 활성화 (내장 템플릿 빌더 전용) {#_4-enable-the-import-content-only-for-the-built-in-template-builder}

내장 빌더는 `local`(이)라는 이름의 스토리지로 클라우드 이미지를 다운로드하고 그로부터 템플릿을 생성합니다. 해당 스토리지의 콘텐츠 목록에 `import`(과)과 `snippets`을(를) 추가하세요. 기존에 사용 중인 유형은 유지하고, `--content`이(가) 전체 목록을 교체합니다:

```bash
pvesm status --storage local     # note the current content
pvesm set local --content iso,vztmpl,backup,import,snippets
```

### 5. 클라우드 이미지로 OS 템플릿 빌드 {#_5-build-an-os-template-from-a-cloud-image}

템플릿은 NexCMP가 복제하는 cloud-init VM입니다. 각 템플릿은 VM ID와 함께 **OS key**(예: `ubuntu-24.04`) 단축키 아래에 등록됩니다. 복제가 선택된 노드에서 실행되므로 **VM을 수신할 모든 노드에** OS당 하나의 템플릿을 빌드하세요.

**옵션 A (권장): 직접 빌드.** 기본 Ubuntu 및 Debian 클라우드 이미지에는 게스트 에이전트가 포함되어 있지 않고 루트 로그인을 허용하지 않으며, NexCMP는 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'
```

그런 다음 템플릿 VM을 생성합니다 (ID 9000은 예시이며, 템플릿 ID는 `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** 카드는 qcow2 이미지를 다운로드하고 템플릿을 빌드하여 등록합니다. 이 카드는 cloud-init 및 게스트 에이전트 플래그가 포함된 VM을 생성하지만 이미지 내부의 내용은 변경하지 않습니다. 루트 로그인을 이미 허용하고 게스트 에이전트를 실행하는 이미지와 함께 사용하거나, cloud-init vendor-data 스니펫을 함께 제공하는 경우에만 사용하세요.


게스트 에이전트는 **Reset password** 기능과 VM의 IP 주소 표시를 위해 필요합니다.

### 6. 인증서 지문 확인 (선택 사항) {#_6-know-the-certificate-fingerprint-optional}

NexCMP는 TLS 인증서의 SHA-256 지문을 고정(pinning)하여 클러스터를 신뢰하므로 자체 서명된 인증서도 무방합니다. 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**을(를) 선택하고 입력하세요:

   | 필드 | Example value |
   |---|---|
   | Name | `Proxmox cluster 1` |
   | Endpoint | `https://192.0.2.10:8006` |
   | Token id | `nexcmp@pve!api` |
   | Token secret | `XXXX` (1단계에서 출력된 UUID) |
   | Slug | `pve-1` (a-z, 0-9, 하이픈, 2-32자) |
   | Default node | `pve1` (비워 둠: 여유 RAM이 가장 많은 온라인 노드) |
   | 스토리지 | `local-lvm` |
   | Bridge | `vmbr0` |

      ![Proxmox VE가 선택되어 있고 예시 엔드포인트, 토큰, 스토리지 값이 입력된 클라우드 공급자 추가 대화상자](https://nexcmp.com/ko/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 브리지 및 선택적 VLAN 태그 (0은 없음). |
   | CPU type | 기본값은 `host`입니다. 노드의 CPU 세대가 다른 경우 `x86-64-v2-AES`을 사용하세요. |
   | vmid from | 고객 VM에 부여되는 첫 번째 VM ID (기본값 1000). |
   | Storage ISO, Storage backup | 사용하지 않는 경우 비워 둡니다. 비워 두면 ISO 및 백업 기능이 제공되지 않습니다. |
   | Template OS | 줄당 하나, `os-key=vmid`, 예: `ubuntu-24.04=9000`. |
   | Pinned TLS fingerprint (SHA-256) | 첫 번째 테스트로 채워집니다. 클러스터 인증서를 교체한 후 지우고 다시 테스트하세요. |

      ![클러스터 탭, 예시 노드, 스토리지, 브리지 및 OS 템플릿 목록이 있는 클러스터 구성 카드](https://nexcmp.com/ko/docs/images/infrastructure/proxmox-03-cluster-config.webp)

5. 선택 사항: 위의 옵션 B를 사용한 경우, **Create OS template from cloud image**(OS 키 `ubuntu-24.04`, vmid `9000`, 노드 `pve1`, qcow2 이미지 URL)를 채우고 **Create template**을 클릭합니다. 백그라운드에서 몇 분간 실행되며, 결과는 감사 로그(Audit log)에서 확인하실 수 있습니다.

      ![클라우드 이미지 카드로 OS 템플릿 생성 (예시 Ubuntu 이미지 URL 포함)](https://nexcmp.com/ko/docs/images/infrastructure/proxmox-04-template-from-image.webp)

6. **Add pool**을 **Cluster IP pool**에서 클릭하고 VM이 주소를 할당받을 풀을 생성합니다:

   | 필드 | Example value |
   |---|---|
   | 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는 네트워크 주소, 브로드캐스트 주소, 게이트웨이 또는 예약된 주소를 절대 할당하지 않습니다. 동일한 클러스터의 풀은 겹칠 수 없습니다. 풀은 주소가 전혀 사용되지 않을 때만 삭제할 수 있습니다.

      ![예시 /24 및 게이트웨이가 포함된 IP 풀 추가 대화상자](https://nexcmp.com/ko/docs/images/infrastructure/proxmox-05-ip-pool.webp)

7. **Attach cluster to zone**에서 영역과 선택적으로 노드 이름을 선택한 다음 **Attach to zone**을 클릭합니다. 클러스터는 이미 VM을 판매 중인 영역에 합류하므로 하나의 영역에 CloudStack과 Proxmox를 함께 구성할 수 있습니다. 새 소스는 **기본적으로 판매되지 않으며** 기존 플랜의 동작 방식을 변경하지 않습니다.

      ![기존 영역이 선택된 영역에 클러스터 연결 카드](https://nexcmp.com/ko/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}

클러스터의 VM 목록을 보려면 **Servers** 탭을 엽니다. **Import**은(는) 시간, 전원 꺼짐 시간 또는 트래픽에 대한 과금 없이 기존 VM을 고객 계정에 무료로 할당합니다. 고객은 시작, 중지, 재부팅 및 콘솔 열기를 할 수 있지만 삭제할 수는 없으며 오직 관리자만 가능합니다. NexCMP는 가져오는 동안 클러스터에서 읽기만 수행합니다.

- 클러스터는 해당 VM의 **노드 이름**이 있는 영역에 연결되어어야 합니다(노드를 비워두면 가져오기가 리전이 설정되지 않았다고 보고합니다).
- VM을 **보호** 상태로 만들려면(중지, 재부팅, 재설치, 스냅샷 복원, 삭제 및 요금제 변경이 거부됨) 명령줄에서 다음으로 가져옵니다 `--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 크기 조정, 디스크 확장 | 예, 단 VM이 중지되고 변경된 후 다시 시작됨 (라이브 크기 조정 불가) |
| Snapshots | 예, VM당 최대 5개: 생성, 목록 조회, 복원, 삭제 |
| Reinstall | 예: VM이 템플릿에서 다시 빌드되며 새 비밀번호와 함께 ID, IP 및 설정이 유지됨 |
| 비밀번호 초기화 | 예, 게스트 에이전트를 통해 |
| 콘솔 | 예, 패널을 통해 프록시되는 브라우저 콘솔 |
| 지표 | 예: CPU, 메모리, 네트워크 및 디스크 |
| ISO 마운트, 백업, 방화벽, IPv6, 포트 포워딩, IP 변경, 추가 볼륨, Auto Scaling, DDoS Shield, VPC, 대역폭 측정 | 사용 불가. 고객 VM 페이지는 소스가 지원하지 않는 기능을 숨깁니다. |

## 확인 {#verify}

1. **Test connection**이(가) OK를 표시하고 공급자 상태가 활성 상태입니다.
2. **Clusters**에 스토리지 및 브리지와 함께 노드가 온라인 상태로 나열됩니다.
3. **Cluster IP pool**에 여유, 사용 중 및 보류 중인 개수가 표시됩니다.
4. 클러스터가 연결된 후 OS 키가 **Services › Virtual Machines › Template**의 영역 템플릿 아래에 표시됩니다.
5. 클러스터를 사용하는 요금제에서 테스트 VM을 주문합니다. 풀에서 주소, 루트 비밀번호 및 작동하는 콘솔을 할당받아야 하며, 풀에는 1개의 주소가 사용 중인 것으로 표시됩니다.

## 제한 사항 및 참고 사항 {#limits-and-notes}

::: tip 혼합 소스 영역
NexCMP 1.4.0부터는 CloudStack과 Proxmox VE가 영역을 공유하는 경우에도 공개 Cloud Server 가격표가 정상 작동합니다. 각 요금제는 자체 **Infrastructure source**를 사용합니다. 클러스터를 연결한 후 공개 가격표를 확인하고 각 소스별로 테스트 주문을 진행해 보십시오.
:::

- 여러 Proxmox 클러스터를 추가할 수 있습니다. 각각은 하나의 공급자입니다.
- 영역은 하나의 기본 소스를 제공하며, 자체 **Infrastructure source**가 있는 요금제는 해당 클러스터가 활성 상태이고 요금제의 영역에 있는 한 정확히 그 클러스터에 배포됩니다.
- CloudStack과 동일한 영역 뒤에 있는 클러스터는 CloudStack에 레거시 요금제를 유지합니다. 출시 전에 엔드투엔드 주문을 테스트하세요.
- API 토큰은 볼 수 없고 교체만 가능합니다. **Credentials** 탭에서 교체하세요. Proxmox에서 새 토큰을 먼저 생성하고 입력한 후 **Test connection**을 실행한 다음 이전 토큰을 해지합니다.
- Test, Sync 및 cluster-info 작업은 관리자당 분당 6회 호출로 제한됩니다.
- NexCMP는 고객에게 청구하며, 클러스터의 하드웨어 및 라이선스 비용은 귀하의 부담입니다.


## Troubleshooting {#troubleshooting}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| 테스트: "Key rejected (wrong access key / secret, or revoked)" 또는 HTTP 401/403 | 토큰 ID 또는 시크릿이 잘못되었거나 ACL이 토큰에만 부여됨 | 두 `pveum acl modify` 명령어(사용자 **및** 토큰)를 다시 실행하고 토큰 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 인증서가 고정된 지문과 일치하지 않음(cluster TLS certificate DOES NOT match pinned fingerprint)" | 클러스터 인증서가 교체됨 | Clusters 탭에서 **Pinned TLS fingerprint**를 지우고 저장한 후, **Test connection**을(를) 다시 실행합니다. |
| 슬러그 거부됨 | a-z, 0-9, 하이픈이 아니거나 2-32자가 아님 | `pve-1`과(와) 유사한 형식을 사용합니다. |
| "토큰 ID 형식: user@realm!tokenid 및 secret이 필요함(Token id format: user@realm!tokenid and secret is required)" | 토큰 ID 또는 secret 누락 | 둘 다 입력하세요. secret은 토큰 생성 시 출력된 UUID입니다. |
| "잘못된 템플릿 라인: …(Invalid template line: …)" | **Template OS**의 라인이 `key=vmid`이(가) 아님 | 키에는 문자, 숫자, `.`, `_`, `-`를 사용하고 vmid는 100 이상으로 지정합니다. |
| "OS 키: a-z 0-9 . _ - 및 vmid ≥ 100" | **Create template**의 키 또는 ID가 잘못됨 | OS 키를 수정하고 사용 가능한 vmid를 사용합니다. |
| 템플릿 생성 시 "vmid … 이미 존재함(vmid … already exists)" | vmid가 이미 사용 중임 | 다른 ID를 선택합니다. |
| "URL이 내부 주소를 가리킴(url points to internal address)" | 이미지 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**을(를) 수정하거나 비워 둡니다. |
| "이미지가 클러스터에 속하지 않음(image does not belong to cluster)" | 플랜의 OS가 **Template OS**에 없음 | 목록에 키를 추가하고 저장합니다. |
| 배포가 대기 상태를 거친 후 복제 단계에서 실패함 | 템플릿 VM이 선택한 노드에 없음 | 해당 노드에 템플릿을 생성하거나, **Default node**을(를) 템플릿이 있는 노드로 설정합니다. |
| 고객이 루트 계정으로 로그인할 수 없음 | 이미지가 루트 로그인을 차단함 | 옵션 A와 같이 템플릿을 다시 빌드합니다. |
| 비밀번호 재설정이 작동하지 않음 | 게스트 내에 게스트 에이전트가 없음 | 템플릿에 `qemu-guest-agent`을(를) 설치하고 활성화합니다. |
| "이름, CIDR, 게이트웨이는 필수 항목입니다" | 풀 필드 누락 | 세 항목 모두 입력합니다. |
| Pool create: "overlaps with pool …", "gateway must be within range (not network/broadcast address)" 또는 "cidr: network address must be …" | 풀 중복, 잘못된 게이트웨이 또는 네트워크 경계에 있지 않은 CIDR | 사용 가능한 대역, 그 내부의 게이트웨이, 그리고 네트워크 주소 형식으로 작성된 CIDR을 사용합니다(예: `198.51.100.0/24`). |
| 가져오기: "리전이 설정되지 않았습니다" | VM의 노드 이름 없이 클러스터가 연결됨 | 노드 이름과 함께 클러스터를 영역에 연결합니다. |


---

<!-- source: https://nexcmp.com/ko/docs/infrastructure/templates/ -->

# OS 템플릿 및 ISO {#os-templates-and-isos}

> **관리자 위치:** Services › Virtual Machines › Template (`/vm/templates`). Proxmox 템플릿은 Infrastructure › Cloud provider › Providers › (cluster) › Clusters에서 클러스터별로 나열됩니다.

## 작동 내용 {#what-it-does}

템플릿은 새 VM이 시작되는 운영체제 이미지입니다. NexCMP는 이미지를 직접 저장하지 않고, CloudStack이 보고하는 내용(준비된 추천 템플릿)이나 Proxmox 클러스터에 나열된 내용을 읽어 고객용 이름, 아이콘, 로그인 사용자와 함께 판매할 항목을 선택할 수 있게 합니다. 이 페이지에서는 비밀번호 로그인, 실시간 CPU 및 RAM 확장, 스왑 파일, 플랜 크기로 확장되는 루트 디스크 등 NexCMP와 호환되는 이미지를 준비하는 방법을 설명합니다.

## 요구 사항 {#requirements}

| 항목 | 요구 사항 |
|---|---|
| CloudStack 템플릿 빌더 | `libguestfs-tools`(`virt-customize`, `virt-sparsify`, `guestfish`), `qemu-utils`, `curl` 및 약 5 GB의 여유 디스크가 있는 Linux 머신. KVM 및 root 권한은 필요하지 않습니다. 패키지 설치를 위한 인터넷 접속이 필요합니다(또는 `--offline`(으)로 빌드). |
| 빌더 위치 | 패널 서버의 `/opt/nexcmp/releases/<version>/share/templates/` 안에 모든 릴리스와 함께 제공됩니다. 해당 위치에서 실행할 필요는 없으며, 폴더를 임의의 Linux 머신으로 복사하면 됩니다. |
| 웹 서버 | 완성된 `.qcow2` 파일을 게시하기 위해 CloudStack의 보조 스토리지 VM이 도달할 수 있는 모든 HTTP(S) 서버. 인터넷에서 도달할 수 있을 필요는 없습니다. |
| CloudStack | 템플릿을 등록할 수 있는 계정, 그리고 영역 ID와 일치하는 OS 타입 ID. [CloudStack](https://nexcmp.com/ko/docs/infrastructure/cloudstack/)을(를) 참조하세요. |
| Proxmox VE | QEMU 게스트 에이전트가 포함된 Cloud-init 템플릿 VM (OS 및 노드당 하나). [Proxmox VE](https://nexcmp.com/ko/docs/infrastructure/proxmox/)을(를) 참조하세요. |
| 종속성 | 먼저 연결된 [CloudStack](https://nexcmp.com/ko/docs/infrastructure/cloudstack/) 또는 [Proxmox VE](https://nexcmp.com/ko/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/<version>/share/templates ~/templates && cd ~/templates
   ./build-template.sh --distro ubuntu-24.04 --version v7 --work ./out
   ```

   패널에 등록되는 선택적 첫 부팅 모니터링 에이전트를 포함하려면 `--panel-url https://cloud.example.com`을(를) 추가합니다(HTTPS 전용). 이 옵션이 없으면 에이전트가 추가되지 않습니다. 기타 옵션: 다운로드한 이미지를 사용하려면 `--base <file>`, 패키지 설치를 건너뛰려면 `--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은 VM에 CPU와 IP를 조회하고 스냅샷을 위해 일시 중단할 수 있습니다. |
| CloudStack 데이터 소스를 사용하는 cloud-init, `set_passwords` 모든 부팅 시, SSH 비밀번호 로그인 | 생성된 비밀번호는 가상 라우터에서 가져오며 **Reset password**가 정상 작동합니다. |
| 핫애드된 CPU 및 RAM을 위한 udev 규칙 | 핫애드된 vCPU와 RAM이 자동으로 활성화되므로 실시간 스케일링과 Auto Scaling이 작동합니다. |
| 스왑 파일 서비스 | 디스크가 확장된 후 RAM의 50%와 4 GiB 중 작은 값으로 `/swapfile`를 생성합니다. `touch /etc/cmp-swap.disabled`는 이를 끕니다. |
| cloud-init `growpart` 및 `resizefs` | 작은 루트 디스크는 첫 부팅 시 요금제의 디스크 크기로 커집니다. |
| 비어 있는 machine-id, SSH 호스트 키 없음 | 모든 VM은 고유한 아이덴티티를 가집니다. |

::: warning 템플릿 이름 지정 `<OS> <version> <vN>`
NexCMP는 이름이 `vN` 또는 `vN.M`으로 끝나고 **N of 6 or more**(`Ubuntu 24.04 v7`, `Rocky Linux 9 v7.1`)인 템플릿에 대해 **Auto Scaling**을 켭니다. 빌더는 `--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=<zone-id> format=QCOW2 hypervisor=KVM \
     ostypeid=<os-type-id> passwordenabled=true sshkeyenabled=true isdynamicallyscalable=true \
     requireshvm=true isextractable=false ispublic=true isfeatured=true \
     checksum="{SHA-256}<sha256 of the file>" \
     details[0].guest.cpu.mode=host-passthrough details[0].rootDiskController=osdefault
   ```

   - `passwordenabled=true`를 통해 CloudStack이 VM 비밀번호를 생성하도록 합니다.
   - `isdynamicallyscalable=true`는 실시간 스케일링을 허용합니다.
   - 현재 Rocky 및 Alma 이미지가 부팅하려면 `host-passthrough`가 필요하며, `osdefault`는 디스크 컨트롤러를 이식 가능하게 유지합니다.

4. **Download Complete / Ready** 상태가 될 때까지 템플릿을 기다리세요.

공급업체 이미지는 작은 가상 크기를 유지합니다(Ubuntu 및 Debian은 약 3.5 GiB, Rocky는 10 GiB). 요금제의 디스크는 템플릿의 디스크보다 작을 수 없음을 기억하세요.

### Proxmox VE: 템플릿 만들기 {#proxmox-ve-make-a-template}

배포하는 모든 노드에 OS별 cloud-init VM 템플릿을 만드시고 게스트 에이전트 설치 및 루트 로그인을 활성화한 다음, `os-key=vmid`(으)로 등록하세요. 전체 명령어는 [Proxmox VE](https://nexcmp.com/ko/docs/infrastructure/proxmox/)에 있습니다. 위의 CloudStack 빌더는 Proxmox용이 **아닙니다**. CloudStack 데이터 소스용 cloud-init을 구성합니다.

### ISO {#isos}

고객은 **Images** 모듈(CloudStack) 또는 전용 서버 모듈을 통해 자신의 ISO를 마운트합니다. 이들은 이 페이지의 OS 템플릿과는 별개입니다. [Modules](https://nexcmp.com/ko/docs/infrastructure/modules/) 및 [Dedicated servers](https://nexcmp.com/ko/docs/infrastructure/dedicated/)를 참조하세요.

## NexCMP에서 연결 {#connect-in-nexcmp}

1. **Services › Virtual Machines › Template**을 엽니다. **Sync now**를 클릭하거나 최대 15분간 기다립니다. 동기화가 진행되면 CloudStack에서 준비 완료 및 추천(featured) 상태인 템플릿이 추가됩니다.

      ![준비 상태 및 CPU 핫플러그 열이 포함된 동기화된 템플릿을 나열하는 템플릿 페이지](https://nexcmp.com/ko/docs/images/infrastructure/templates-01-list.webp)

2. 새 템플릿에서 **Edit**을 클릭하고 고객에게 표시될 내용을 설정하세요:

   | 필드 | Example value |
   |---|---|
   | 고객용 표시 이름 | `Ubuntu 24.04 LTS` |
   | OS 패밀리 | `ubuntu` (아이콘 및 기본 사용자) |
   | 버전 | `24.04` |
   | 로그인 사용자 이름 | `ubuntu` (Windows: `Administrator`; 기타: `root`) |
   | 아이콘 | 이미지 URL, 경로 또는 이름 |
   | 순서 | `10` |
   | 활성 | On |
   | vCPU/RAM 핫플러그(실시간 스케일) | **Auto by name (v6 or later)**, **Yes** 또는 **No (needs a restart)** |

      ![고객용 이름, OS 패밀리, 로그인 사용자 및 핫플러그 옵션이 있는 템플릿 편집 대화상자](https://nexcmp.com/ko/docs/images/infrastructure/templates-02-edit.webp)

3. 템플릿을 켭니다. 더 이상 CloudStack에 나열되지 않는 템플릿은 자동으로 숨겨지며(구성이 되어 있는 경우 텔레그램으로 알림을 받음), NexCMP에서 삭제되지는 않습니다.

### 새 빌드로 템플릿 교체 {#replace-a-template-with-a-newer-build}

판매된 템플릿에서 **More › Replace with new version**을 사용합니다. 새롭고 준비되었으며 현재 비활성화된 템플릿을 선택합니다. 그러면 판매된 항목이 새 빌드를 가리키며 이름, 순서 및 아이콘을 유지합니다. 이전 항목은 돌아가는 방법으로 비활성화됩니다(돌아가려면 새 항목에서 **Replace** 사용). 실행 중인 VM은 변경되지 않습니다. 새 빌드가 다른 OS 제품군인 경우 먼저 확인란을 선택하세요.

## 확인 {#verify}

1. 행에 **ready**가 표시되고, N이 6 이상인 `vN` 명명된 빌드의 경우 **CPU hot-plug: supported**가 표시됩니다.
2. 템플릿에서 테스트 VM을 하나 배포하고 VM 내부를 확인합니다:
   - 포털에 표시된 비밀번호로 로그인할 수 있습니다;
   - `df -h /`에 요금제의 디스크 크기가 표시됩니다;
   - 라이브 스케일(재부팅 없는 **Change plan**) 후 `nproc` 및 `free -m`가 증가합니다;
   - `swapon --show`에 `/swapfile`이(가) 나열됩니다(스왑과 2 GiB를 더한 것보다 여유 공간이 적은 디스크는 건너뜀);
   - `systemctl is-active qemu-guest-agent` 실행 시 `active`이 출력됩니다.
3. 에이전트를 사전 포함하여 빌드한 경우 첫 번째 부팅 후 1분 이내에 패널의 모니터링 대상 호스트 목록에 VM이 표시됩니다. 패널은 공용 소스 IP로 VM을 식별하므로 VM 자체의 공용 IP가 필요합니다.

## 제한 사항 및 참고 사항 {#limits-and-notes}

- 빌더는 Linux 전용이며 Linux 이미지만 빌드합니다. 다른 이미지(예: Windows)는 다른 방법으로 CloudStack에 등록할 수 있으며, NexCMP는 CloudStack이 보고한 항목을 나열합니다.
- amd64 에이전트만 제공되며, 다른 아키텍처에서는 에이전트 설치를 건너뜁니다.
- 이미지는 `guestfish`으로 검사되지만 빌더에 의해 실제로 부팅되지는 않습니다. 새 이미지를 판매하기 전에 항상 테스트 VM을 하나 배포해 보십시오.
- 첫 부팅 전 `touch /etc/cmp-agent.disabled`을 실행하여 특정 VM에서 에이전트를 건너뛸 수 있습니다. 나중에 `systemctl disable --now cmp-agent cmp-agent-install; rm -rf /etc/cmp-agent /usr/local/bin/cmp-agent`로 제거한 다음 관리 콘솔에서 해당 에이전트를 삭제하십시오.

## Troubleshooting {#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` | 이름은 N이 6 이상인 `vN` 형식이어야 합니다 | `--version v7`을 사용하십시오. |
| `--panel-url must be a plain https:// URL` | 에이전트가 다운로드되어 root 권한으로 실행되므로 일반 HTTP는 거부됩니다 | 공백, 따옴표 또는 쿼리 스트링이 없는 `https://` URL을 사용하십시오. |
| 템플릿이 **not ready** 상태로 유지됩니다 | CloudStack에서 다운로드가 완료되지 않았습니다 | **Download Complete** 상태가 될 때까지 기다리고, 보조 스토리지 VM이 해당 URL에 접근할 수 있는지 확인하십시오. |
| 행에 **no-pass**가 표시됩니다 | 템플릿이 `passwordenabled=true` 없이 등록되었습니다 | 해당 플래그를 포함하여 다시 등록하십시오. |
| CPU 핫플러그가 **unsupported**로 표시됩니다 | 이름이 `vN`(N은 6 이상)으로 끝나지 않습니다 | 템플릿 이름을 바꾸거나, 이미지에 udev 규칙이 있는 경우 Edit에서 **vCPU/RAM hot-plug**를 **Yes**로 설정하십시오. |
| 최초 연결 후 "Empty template list"가 표시됩니다 | 동기화가 실행되지 않았습니다 | **Sync now**를 클릭하거나(워커가 실행 중이어야 함) 15분 주기를 기다리십시오. |


---

<!-- source: https://nexcmp.com/ko/docs/infrastructure/dedicated/ -->

# 전용 서버 (베어메탈) {#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는 Redfish API를 통해 **iDRAC로 물리 서버를 직접** 관리합니다. 고객은 서버 전체를 대여하여 전원 켜기 및 끄기, 브라우저 콘솔 열기, ISO 마운트 또는 템플릿에서 운영체제 설치, 하드웨어 및 지표 확인을 수행할 수 있습니다. iDRAC 주소, 사용자 이름 또는 비밀번호는 절대 볼 수 없습니다.

자체 랙의 전용 서버를 재판매하는 데 사용하세요.

## 요구 사항 {#requirements}

| 항목 | 요구 사항 |
|---|---|
| 하드웨어 | **iDRAC 9** 및 Redfish API를 지원하는 Dell 서버. |
| 관리 네트워크 | **직접 제공해야 합니다.** 패널 서버는 **HTTPS 443**(콘솔의 경우 iDRAC VNC 포트, 기본값 **5901**)을 통해 모든 iDRAC에 연결할 수 있어야 하며, 모든 iDRAC은 아래의 ISO 웹 서버에 연결할 수 있어야 합니다. iDRAC 주소는 설정 `dedicated_bmc_cidrs`에 나열하는 **사설 대역의 IPv4 주소**(RFC 1918, /16 이하 프리픽스)여야 합니다. DNS 이름 및 IPv6은 거부됩니다. NexCMP는 이 네트워크를 생성하지 않으며 대신 테스트할 수도 없습니다. |
| iDRAC 계정 | 각 iDRAC당 **Administrator** 권한을 가진 계정 1개. NexCMP는 이 계정을 사용하여 서버 정보를 읽고 허용된 소수의 명령(전원, 가상 미디어, 1회성 부팅, 콘솔)을 전송합니다. 고객용 iDRAC 계정은 절대 생성하지 않습니다. |
| 패널 서버의 도구 | `xorriso` 및 `genisoimage`(각 서버의 설치 ISO 빌드)과 `novnc`(브라우저 콘솔 페이지). `sudo apt-get install -y xorriso genisoimage novnc` 명령으로 직접 설치하거나, 인스톨러가 설치하도록 `--baremetal` 옵션으로 실행하거나 ISO 서버 옵션을 전달하십시오. Bare Metal 모듈이 이미 켜져 있는 경우 업데이트 시에도 자동 설치됩니다. 하나라도 누락되면 **Safety**에 빨간색 알림이 표시되고, **live ops** 활성화가 거부되며(오류 `tools_missing`), 콘솔 및 OS 설치 시 나중에 실패하는 대신 도구 누락 알림을 즉시 반환합니다. |
| ISO 웹 서버 | NexCMP ISO 폴더를 iDRAC에 제공하는 관리 네트워크상의 일반 **HTTP** 서버. 주소는 사설 IPv4 주소 및 선택적 포트 형태(예: `http://10.20.0.2:8080`, **경로 제외**)이며 `dedicated_iso_base_url`에 저장됩니다. byte range를 지원해야 합니다. 이 폴더는 패널의 워커가 작성하므로, 웹 서버는 일반적으로 **패널 서버 자체**에서 실행되어 해당 서버가 관리 네트워크에서 사용하는 주소를 수신 대기합니다. 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이 필요합니다(원클릭 명령이 이를 설치함). |
| 콜백 주소 | `dedicated_callback_base`, 설치 중인 서버가 도달할 수 있고 패널을 가리키는 `https://<your-domain>`. |
| 스토리지 | ISO 라이브러리 및 고객 제공 ISO를 위한 여유 디스크. |
| 종속성 | 모듈 **Bare Metal**, 영역(zone), 그리고 서버의 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. **Create an administrator account on the iDRAC** for NexCMP (iDRAC web UI 또는 `racadm`). 강력하고 고유한 비밀번호를 사용하세요. iDRAC의 기본 제공 계정을 재사용하지 마세요.
3. **한 번의 명령으로 iDRAC에 ISO 폴더 게시.** 패널 서버에서 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`). 이 명령은 다음 작업을 수행합니다:

   - NexCMP 서비스 사용자가 소유한 `pub` 및 `server`을(를) 포함하는 폴더를 생성합니다.
   - `nexcmp-iso` 그룹을 생성하고 nginx 사용자를 추가하여, iDRAC이 마운트하는 동안 nginx만 ISO를 읽을 수 있고 다른 사용자는 읽을 수 없도록 합니다.
   - nginx 사이트 `nexcmp-iso`(`nginx -t`이(가) 승인한 경우에만 유지되며 nginx 미설치 시 설치됨) 및 systemd drop-in `nexcmp-vmd.service.d/iso.conf`(폴더용 `ReadWritePaths`, `SupplementaryGroups=nexcmp-iso`)을(를) 설치합니다.
   - ISO 설정(`dedicated_iso_base_url`, 3개 폴더, 그룹)을 작성하고 NexCMP 워커를 재시작합니다.

   다른 값으로 다시 실행할 수 있으며, `sudo nexcmp dedicated-setup-iso --remove`을(를) 통해 nginx 사이트와 drop-in을 다시 제거할 수 있습니다(ISO 파일은 유지됨). 설치 시점에 실행할 수도 있습니다. 설치 명령에 `--iso-listen`, `--iso-allow`(및 `--iso-dir`)을 추가하십시오. 이 명령은 관리 네트워크를 **생성하지 않으며** 어떠한 iDRAC에도 접속하지 않습니다. 값이 잘못되었거나 주소가 이 서버에 없거나 포트가 이미 사용 중인 경우 변경 사항을 적용하기 전에 메시지를 표시하고 중단되며, `nginx -t`이(가) 거부하는 nginx 사이트는 유지되지 않습니다.

4. **ISO 웹 서버가 제공하는 항목.** nginx 사이트는 `GET`(및 바이트 범위를 포함한 `HEAD`)으로 `/pub/<name>.iso`에 대해서만 응답하며 그 외에는 아무것도 허용하지 않습니다. 디렉터리 목록 표시가 없으며, 폴더 하위의 다른 경로(라이브러리 및 `server/`에 접근 불가)도 없고, 다른 메서드도 지원하지 않으며, 오직 `--allow` 네트워크에서만 접근 가능합니다(그 외에는 403 수신). NexCMP는 iDRAC이 읽어야 하는 각 ISO를 `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/<version>/` 하위)). 이를 복사하고 `__...__` 마커(listen 주소, 폴더, allow 행, 그룹)를 바꾼 다음 위의 규칙을 준수하십시오.

5. **OS 이미지를 준비합니다.** 자체 설치형 ISO를 라이브러리 폴더에 배치합니다(아래의 **Templates** 참조). 고객은 링크를 통해 ISO를 추가할 수도 있으며, 해당 파일은 서버로 다운로드되고 iDRAC에 URL로 전달되지 않습니다.


## NexCMP에서 연결 {#connect-in-nexcmp}

### 1. 모듈 켜기 {#_1-turn-the-module-on}

**System › Admin › License & updates**에서 **Bare Metal**을 켭니다. Infrastructure 아래에 **Bare Metal** 카테고리가 나타납니다. [Modules](https://nexcmp.com/ko/docs/infrastructure/modules/)을 참조하세요.

### 2. 관리 네트워크 연결 설정 {#_2-set-the-management-network-connection}

**Infrastructure › Bare Metal › Safety**를 엽니다. **Management network connection** 카드에는 정상 작동 여부를 결정하는 세 가지 값이 포함되어 있습니다:

| 필드 | 설정 | 입력할 내용 |
|---|---|---|
| iDRAC network (CIDR) | `dedicated_bmc_cidrs` | iDRAC의 프라이빗 네트워크(예: `10.20.0.0/24`)입니다. 프라이빗 CIDR만 허용되며, /16 이하 크기로 쉼표로 구분하여 최대 8개까지 입력할 수 있습니다. 이 범위에 속한 iDRAC만 가져올 수 있습니다. |
| iDRAC용 ISO 서버 | `dedicated_iso_base_url` | 경로를 제외한 `http://<private IPv4>[:port]` 형식: 이전 섹션에서 설정한 ISO 웹 서버 주소(예: `http://10.20.0.2:8080`)입니다. 원스텝 명령을 실행하면 자동으로 입력됩니다. |
| Panel callback address | `dedicated_callback_base` | 경로를 제외한 `https://<your-domain>` 형식: 설치 중인 서버가 완료 상태를 보고하기 위해 호출하는 주소입니다. 해당 서버의 네트워크에서 접근할 수 있어야 합니다. `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에 대한 모든 쓰기 명령(전원, 가상 미디어, 콘솔 및 OS 설치)을 제어하는 시스템 전체 스위치입니다. 기본적으로 **off** 상태로 시작하며, 위의 관리 네트워크 연결에 샘플 값이 남아 있는 동안에는 켤 수 없습니다(스위치가 `config_placeholder`로 응답하며 해당 필드를 표시합니다). 상태 읽기는 정상 작동하지만 쓰기 작업은 API 및 worker 내부에서 다시 거부됩니다. 보조 잠금 장치인 **ops_locked**는 각 서버를 보호합니다. 새로 가져온 서버는 live ops가 켜져 있어도 항상 잠금 상태로 유지됩니다.

![Live ops가 꺼져 있고 차단된 작업 목록이 표시된 Safety 페이지](https://nexcmp.com/ko/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**을 클릭합니다. 테스트는 읽기 명령만 전송하며 아무것도 저장하지 않습니다.

   | 필드 | Example value |
   |---|---|
   | iDRAC 주소 (URL 또는 호스트) | `10.20.0.11` |
   | 계정 | `nexcmp-admin` |
   | 비밀번호 | `XXXX` |
   | 레이블 | `rack1-01` (비어 있음: 자동 생성됨) |
   | 풀에서 IP 할당 | 선택 사항; 서버의 서비스 IP 풀 선택 |
   | 판매 목록에 포함 | 준비될 때까지 꺼둠 |

      ![예시 주소와 성공적인 읽기 전용 테스트가 있는 Stock 및 iDRAC 가져오기](https://nexcmp.com/ko/docs/images/infrastructure/dedicated-02-import-server.webp)

3. **Save to stock**을 클릭합니다. NexCMP는 iDRAC에서 모델, CPU, RAM, 디스크, NIC 및 서비스 태그를 읽어옵니다. 서버가 **잠긴(locked)** 상태로 재고에 들어갑니다.
4. 여러 대의 서버에는 **Bulk import**를 사용합니다. 줄당 하나의 서버, 필드는 콤마, 세미콜론 또는 탭으로 구분합니다. **Preview**는 허용 목록, iDRAC 주소 또는 서비스 태그의 중복을 확인하고 하드웨어를 읽습니다(한 번에 최대 4대의 서버).

### 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 웹 서버의 관리 네트워크 주소를 입력하십시오.
- **고객 ISO 제한(Customer ISO limits)**은 단일 ISO의 크기, 총 ISO 스토리지, 최소 여유 공간, ISO 보관 시간(시간), 최대 다운로드 시간 및 동시 다운로드 수를 설정합니다.

![iDRAC용 HTTP 주소와 ISO 제한이 표시된 고객 ISO](https://nexcmp.com/ko/docs/images/infrastructure/dedicated-03-iso-settings.webp)

### 6. OS 템플릿 {#_6-os-templates}

**Infrastructure › Bare Metal › Templates**를 엽니다. 라이브러리 폴더에서 검색된 자동 설치 ISO 목록이 표시됩니다. 파일에서 **Register**를 클릭하여 OS 제품군, 버전 및 계정을 입력하고(파일명에서 자동 입력됨), 템플릿을 **Enable**로 전환합니다. 템플릿을 활성화해도 작업이 바로 시작되지는 않으며, 모든 설치는 안전 게이트를 거칩니다. **Unregister**는 템플릿 행만 제거하며 파일 자체는 삭제하지 않습니다.

![등록된 ISO와 등록되지 않은 ISO가 있는 Bare Metal 템플릿](https://nexcmp.com/ko/docs/images/infrastructure/dedicated-04-os-templates.webp)

### 7. IP 풀 {#_7-ip-pools}

**Infrastructure › Bare Metal › IP Pools**를 열고 서버가 서비스 주소로 수신할 IPv4 범위를 추가합니다. 각 서버는 하나의 주소를 받으며, 가져올 때 **Assign an IP from a pool**을 선택하면 다음 사용 가능한 주소가 할당됩니다. 사용 가능한 주소는 풀별로 계산됩니다.

![예시 범위와 사용 가능한 개수가 표시된 Bare Metal IP 풀](https://nexcmp.com/ko/docs/images/infrastructure/dedicated-05-ip-pools.webp)

### 8. 플랜 및 판매 {#_8-plans-and-sale}

1. **Services › Dedicated Server › Plans & pricing**을 엽니다. 4개의 샘플 요금제(1.6.1에서는 `BM-40C-<RAM>`(으)로 명명됨)를 수정하거나 가격, 결제 주기, 설치비를 직접 설정하여 새로 생성하십시오. **신규 설치 환경에서는 가격을 센트 단위의 미국 달러로 입력하며 지갑에서 정확히 해당 금액이 청구되므로 환율이 필요하지 않습니다.** 베트남 동으로 가격이 책정된 요금제가 이미 존재했던 설치 환경에서는 동화가 유지되며 설정에 환율이 여전히 필요합니다(환율이 없으면 주문이 `dedicated_fx_unavailable`(으)로 거부됨). 샘플 요금제는 가격 0 및 **disabled** 상태로 시작하며, 판매할 요금제는 0을 초과하는 가격이어야 합니다. 실제로 가져오는 하드웨어와 각 요금제를 대조하여 확인하십시오. 샘플 요금제 이름이 서버 하드웨어를 감지하거나 변경하지는 않습니다.
2. 서버를 열고(Infrastructure › Bare Metal › the server › **Sales**), **플랜을 연결**한 다음 **Sellable**을 켭니다.
3. **라이브 OPS**(안전 페이지, 입력 확인 포함)를 켜고 운영하려는 서버의 잠금을 해제합니다(서버의 **Lock** 탭, 감사 로그에 기록되는 사유 입력).
4. **Services › Dedicated Server**에서 판매를 켭니다. 이 작업은 결과를 읽고 `ENABLE SALES`을(를) 입력하는 두 단계로 이루어집니다. 그때까지 고객에게는 주문 페이지가 표시되지 않으며 청구되지 않습니다.

![판매 스위치가 꺼진 Dedicated Server 요금제](https://nexcmp.com/ko/docs/images/infrastructure/dedicated-06-plans.webp)

### 고객이 서버 페이지에서 수행할 수 있는 작업 {#what-customers-can-do-on-their-server-page}

고객 서버 페이지는 7개 그룹(Overview, Control, Network, Hardware, Billing, Activity, Settings)에 걸쳐 16개의 탭으로 구성되어 있습니다. **Billing** 그룹에는 다음 항목이 포함됩니다.

- **Plan & renewal**: 1개월에서 24개월분을 한 번에 선결제할 수 있습니다. 새 만료일은 현재 갱신일 기준으로 계산되며 지갑에서 1회 차감됩니다. 자동 갱신은 켜거나 끌 수 있습니다.
- **Billing cycle**: 다른 주기(예: 분기별)를 선택할 수 있습니다. **다음** 갱신 시점부터 적용되며 현재는 비용이 청구되거나 환불되지 않습니다.
- **Change plan**: 고객이 다른 플랜으로의 변경을 **요청**할 수 있습니다. 요청 시점에는 요금이 청구되지 않습니다. 하드웨어를 업그레이드하거나 서버를 이전한 후 **Services › Dedicated Server › Plan changes**에서 승인 또는 거부합니다. 업그레이드가 승인되면 고객이 이미 결제한 잔여 기간에 대한 차액이 청구되며, 다운그레이드는 환불되지 않고 다음 주기부터 적용됩니다.
- **Invoices**: 해당 서버의 모든 인보이스(주문, 갱신, 업그레이드)입니다.

**Plan changes**에서 요청을 ID, 날짜, 상태, 요금제 또는 서버별로 정렬할 수 있으며, 정렬은 서버의 전체 결과를 대상으로 적용됩니다. 좁은 화면에서 가로로 스크롤할 때도 작업 열은 계속 표시됩니다.

**Overview** 상단에는 최근 24시간 동안의 소형 차트와 함께 **CPU**, **RAM**, **Disk**, **Network**를 표시하는 4개의 실시간 타일이 제공됩니다. CPU, RAM, Disk는 최근 iDRAC 폴링 기준 사용률(%)이며(Disk는 여유 공간이 아닌 I/O 활동량), Network는 트래픽 카운터에서 가져온 현재 인바운드/아웃바운드 속도 및 당월 합계입니다. 서버가 꺼져 있거나, iDRAC에 연결할 수 없거나, 머신이 해당 값을 보고하지 않는 경우 타일에 **—** 및 간단한 사유가 표시되며, 임의로 생성된 0이 표시되지는 않습니다. 이러한 측정값은 Dell iDRAC에서 가져오며, 트래픽 카운터가 없으면 Network 타일은 **—** 상태로 유지됩니다. 타일은 페이지가 열려 있는 동안 매분 새로고침되며, 클릭하면 **Hardware** 또는 **Bandwidth** 탭이 열립니다.

**Overview**에서 **Access** 카드는 설치된 운영체제의 사용자 이름과 비밀번호를 표시하며, 기본적으로 숨김 처리되어 있고 **Show** 및 **Copy** 버튼이 제공됩니다. 1회성이 아니라 매 설치 후마다 확인할 수 있으며, 서버의 새 소유자는 이전 소유자의 비밀번호를 절대 볼 수 없습니다. 서버 내부에서 OS 비밀번호를 변경하더라도 카드에는 설치 시점에 설정된 비밀번호가 계속 표시됩니다. **Bandwidth** 탭은 트래픽 카운터가 데이터를 제공하는 경우에만 표시됩니다(제한 사항 참조). **Subnet** 탭은 없습니다. 임대 서버에 자체 IP 프리픽스를 가져오는 기능은 NexCMP에서 지원하지 않습니다.

### 고객이 할 수 있는 작업과 할 수 없는 작업 {#what-customers-can-and-cannot-do}

| 고객 가능 작업 | 절대 불가 |
|---|---|
| 인벤토리, 상태, 전원 상태 및 지표 확인 | iDRAC 주소, 사용자 이름 또는 비밀번호 확인 |
| 전원 켜기, 정상 종료, 재부팅, 강제 종료, 재설정 | iDRAC 계정 또는 iDRAC 네트워크 설정 변경 |
| 브라우저 콘솔 열기(한 번에 하나의 세션) | BIOS 또는 RAID 변경, 로그 지우기, 펌웨어 업데이트, iDRAC 재설정 |
| ISO 또는 사용자 ISO 링크 마운트, 한 번 부팅 설정, 활성화된 템플릿에서 OS 재설치 | 원시 Redfish 호출 실행(NexCMP에는 해당 기능이 없음) |

NexCMP는 고객용 iDRAC 계정을 생성하지 않습니다. 고객은 포털의 제어 기능만 사용하며, iDRAC 주소와 로그인 정보는 고객에게 일절 공개되지 않습니다.

## 확인 {#verify}

0. **Safety**에서 **Management network connection** 카드에 빨간색 라벨이 표시되지 않고 Bare Metal 페이지에 빨간색 알림이 표시되지 않습니다. 관리 네트워크의 호스트에서 `curl -I http://<iso-address>/` 실행 시 파일 목록이 표시되지 않습니다.
1. 가져오기 폼의 **Test connection**은 모델, CPU, RAM 및 서비스 태그를 반환합니다.
2. 서버가 하드웨어 정보와 함께 **Servers**에 표시됩니다. **라이브 오퍼레이션이 꺼져 있는** 경우, 전원 작업은 "Server control is temporarily disabled system-wide" 메시지와 함께 거부됩니다.
3. 라이브 오퍼레이션을 켜고 테스트 서버 하나를 잠금 해제한 후, **Operations** 또는 서버 페이지에서 서버를 껐다 켜고 콘솔을 엽니다.
4. 테스트 플랜으로 테스트 주문을 생성합니다. 서버가 할당되고, OS가 설치되며, 설치가 완료되면 서버가 패널에 보고합니다.

## 제한 사항 및 참고 사항 {#limits-and-notes}

- 모든 물리 서버에는 최대 하나의 활성 구독이 있습니다.
- 쓰기 명령은 live ops가 켜져 있고(**both**) 서버 잠금이 해제된(**and**) 두 조건이 모두 충족될 때만 전송됩니다. 각 명령 직전에 worker 내부에서 이 검사를 다시 수행합니다.
- **Installing** 상태는 주문이 완료되기 전에 새 OS가 해당 포트(SSH 22, Windows 3389, Proxmox 8006)에서 응답할 때까지 대기하며, 설치에는 제한 시간이 있습니다(`dedicated_install_timeout_min`, 기본값 150분).
- 전용 서버의 대역폭은 표준 설치에 포함되지 않는 트래픽 카운터 에이전트를 통해 측정됩니다. 이 에이전트가 없으면 아무것도 기록되지 않으며, 포털에서 Bandwidth 탭이 숨겨지고 API는 `capabilities.bandwidth`을(를) `false`(으)로 반환합니다.
- 임대 서비스에 대한 관리자 작업(잠금, 잠금 해제, 환불 포함 또는 미포함 취소)은 다른 모든 서비스와 동일하게 통합된 작업이며, 환불금은 결제에 사용된 잔액으로 반환됩니다.
- 서버는 리셀러 간에 재판매되지 않습니다. Dedicated는 메인 사이트에서만 판매됩니다.


## Troubleshooting {#troubleshooting}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| 주소 오류로 테스트 실패 | 주소가 `dedicated_bmc_cidrs` 내의 IPv4 리터럴이 아니거나(프라이빗, /16 이하) 허용되지 않은 포트인 경우 | iDRAC의 IPv4 주소를 사용하고 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://<private IPv4>[:port]`이(가) 아님, 콜백이 `https://<domain>`이(가) 아님) 또는 `example.com`와(과) 같은 샘플 주소 | 필드 아래의 메시지를 확인하십시오. 저장된 값은 변경되지 않습니다. |
| 아무것도 변경하지 않고 `nexcmp dedicated-setup-iso`이(가) 중단됨 | `--listen`이(가) 이 서버의 주소가 아니거나, 포트가 이미 사용 중이거나, 값이 유효하지 않음 | 이 서버가 관리 네트워크에서 사용하는 주소나 다른 포트를 사용하거나 메시지에 명시된 값을 수정하십시오. |
| "iDRAC TLS 인증서가 고정된 인증서와 다릅니다. 폴링 및 쓰기 작업이 중지되었습니다" | iDRAC 인증서가 교체됨(새 인증서, iDRAC 교체) | 서버를 열고 **Access** 탭에서 두 지문(fingerprint)을 비교한 후, 변경이 의도된 것이면 **Repin certificate**를 클릭합니다. |
| "시스템 전체에서 서버 제어가 일시적으로 비활성화되었습니다" | 라이브 오퍼레이션이 꺼져 있음 | Turn it on in **Safety**. |
| "이 서버는 작업이 잠겨 있습니다" | 서버별 잠금이 닫혀 있음 | 사유와 함께 서버의 **Lock** 탭에서 잠금을 해제하세요. |
| "이 서버에서 다른 작업이 아직 실행 중입니다" | 이전 작업이 완료되지 않았습니다 | Wait; check **Operations**. |
| "이 서버에서 다른 콘솔 세션이 이미 열려 있습니다" | 한 번에 하나의 콘솔만 허용됨 | 다른 세션을 닫으세요. |
| "서버 컨트롤러를 일시적으로 사용할 수 없습니다" | iDRAC가 응답하지 않음 | 관리 네트워크와 iDRAC를 확인하세요. |
| iDRAC에서 403 또는 404 오류와 함께 ISO 마운트 실패 | 웹 서버가 파일을 읽을 수 없거나 기본 주소가 잘못됨 | ISO 웹 서버의 권한 및 iDRAC에 ISO를 제공하는 **HTTP address serving ISOs to iDRAC**을 확인하세요. |
| "선택한 위치에 이 플랜의 재고가 없습니다" | 해당 영역에 해당 플랜을 판매할 수 있는 서버가 없음 | 플랜을 서버에 연결하고 **Sellable**을 켜세요. |
| "지금 할당할 수 있는 IPv4 주소가 없습니다" | IP 풀이 비어 있음 | 풀에 주소를 추가하세요. |
| "현재 자동 OS 설치를 사용할 수 없습니다" | Install prerequisites missing | 템플릿이 활성화되어 있고 ISO 폴더에 쓰기 권한이 있는지 확인하세요. 고객은 여전히 ISO와 콘솔을 통해 설치할 수 있습니다. |
| Installation stalls | 설치 중인 서버가 콜백 주소에 도달할 수 없음 | `dedicated_callback_base` 및 서버의 네트워크가 HTTPS를 통해 패널에 도달할 수 있는지 확인하세요. |


---

<!-- source: https://nexcmp.com/ko/docs/infrastructure/vpn-proxy-nodes/ -->

# 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는 운영 중인 서버에서 **직접 소유한 IP 주소**로 나가는 VPN 및 프록시 액세스를 판매합니다. 두 가지 종류의 노드가 존재합니다:

- **VPN 노드.** 소형 Go 프로그램인 `cmp-agent`이(가) Linux 호스트에서 실행됩니다. 호스트의 공인 IPv4 주소를 검색하고, 판매되는 각 주소에서 SOCKS5, HTTP 및 UDP 리스너를 열며, 고객이 연결된 **동일한 IP**에서 트래픽을 내보냅니다(동일 IP 아그레스). 몇 초마다 패널에 보고합니다.
- **IPv6 proxy node.** 호스트로 라우팅하는 IPv6 프리픽스의 주소를 고객에게 제공하는 프록시 서비스입니다. 패널이 SSH를 통해 자동으로 설치해 줍니다.

서버를 보유한 국가에서 깨끗한 IP 주소를 재판매하는 데 사용하세요.

## 요구 사항 {#requirements}

### VPN node {#vpn-node}

| 항목 | 요구 사항 |
|---|---|
| 운영체제 | systemd 및 4.15 이상의 커널을 지원하는 Linux 배포판(IPv6 free-bind 지원). 제공되는 에이전트 바이너리는 **x86_64**(amd64) 전용입니다. |
| 권한 | 설치를 위한 root 권한. 서비스는 `CAP_NET_ADMIN`, `CAP_NET_RAW` 및 `CAP_DAC_READ_SEARCH`만 유지합니다. |
| 도구 | `curl` 또는 `wget`, 그리고 `sha256sum` (설치 프로그램은 파일 확인 없이는 진행을 거부합니다). |
| 공인 주소 | 호스트의 인터페이스에 할당된 공인 IPv4 주소(각각 `/32` 1개씩) **또는** 추가 서브넷으로 추가한 호스트 라우팅 프리픽스(IPv4 /16~/32, IPv6 /48~/128). 사설, CGNAT 및 문서화 대역은 무시됩니다. |
| 네트워크, 인바운드 | 고객은 판매된 각 공인 IP에 **65001-65535 포트**(SOCKS5 및 HTTP용 TCP, UDP 어소시에이트용 UDP)로 연결합니다. 각 엔드포인트는 연속된 세 개의 포트 세트를 사용합니다. |
| 네트워크, 아웃바운드 | 패널 도메인으로의 HTTPS(443). 에이전트는 또한 3.5초 제한으로 `ip-api.com`(HTTP) 및 `ipinfo.io`(HTTPS)에서 자체 국가를 조회합니다. |
| 메일 | 포트 25로의 아웃바운드 연결은 항상 차단되며, 이를 허용하는 설정은 제공되지 않습니다. |
| Docker, VPN 및 가상 인터페이스 | `docker*`, `veth*`, `br-*`, `cni*`, `flannel*`, `virbr*`, `cali*`, `tun*`, `tap*`, `wg*`, `tailscale*` 이름의 인터페이스는 주소를 기여하지 않습니다. |
| 종속성 | 모듈 **VPN**, (호스트의 국가에서 자동으로 생성된) 영역 및 HTTPS로 접속 가능한 NexCMP 패널. |

### IPv6 프록시 노드 {#ipv6-proxy-node}

| 항목 | 요구 사항 |
|---|---|
| 운영체제 | **x86_64** 기반 systemd가 탑재된 Linux. 명령어 `systemctl`, `nft`, `ip`, `ss`, `sysctl`, `useradd`가 존재해야 합니다. 그렇지 않으면 설치가 중단되고 누락된 명령어가 표시됩니다. |
| 설치 접근 권한 | 공인 IPv4 주소(사설, 루프백 및 CGNAT 주소는 거부됨), SSH 포트, root 또는 `sudo` 권한을 가진 계정 및 해당 **비밀번호**. 비밀번호는 설치용으로만 사용되며 저장되지 않습니다. |
| 사용 가능한 포트 | **80, 443 및 60000 이상의 모든 포트**가 비어 있어야 합니다. 설치 프로그램은 이미 실행 중인 서비스를 중단하거나 변경하지 않으며, 사용 중인 포트를 보고하고 중단합니다. |
| IPv6 | 호스트가 아웃바운드 트래픽의 소스로 사용할 수 있는 `2000::/3` 내부의 **/32와 /64** 사이의 공인 프리픽스로, 호스트로 **라우팅**되거나 NDP 프록시와 함께 **온링크**로 전달됩니다(아래 참조). |
| 네트워크 | 고객은 노드의 IPv4에 포트 80(HTTP 프록시), 포트 443(SOCKS5) 및 포트 60001~65535(고정 IP당 하나의 포트)로 연결합니다. 노드에는 인증서가 없으므로 HTTPS 프록시는 지원되지 않습니다. 트래픽은 IPv6로만 전송되며, IPv6 주소가 있는 목적지로만 나갑니다. 노드는 HTTPS를 통해 패널에서 구성을 가져옵니다. |
| 패널 서버의 노드 소프트웨어 | 노드 데몬 및 네트워크 스크립트는 NexCMP 릴리스 패키지에 포함되어 제공됩니다. 패널은 설치 중에 설치 폴더(`/opt/nexcmp/releases/<version>/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://<your license domain>`). |


## 인프라 준비 {#prepare-the-infrastructure}

### VPN node {#vpn-node-1}

1. **지원되는 Linux와 네트워크 인터페이스에 설정되거나 호스트로 라우팅되어 판매할 공인 IPv4 주소를 사용하여 호스트를 프로비저닝**합니다.
2. **라우팅된 블록을 판매하는 경우**, 노드를 추가할 때 해당 블록을 **Extra subnet**으로 입력하도록 계획하십시오. 에이전트는 호스트가 블록 내의 모든 주소에 대한 트래픽을 수락하도록 라우트 `local <block> dev lo`을 설치한 다음 발견된 주소를 보고합니다. 또한 에이전트는 호스트의 실제 라우팅 테이블을 읽고 **게이트웨이** 주소는 절대 판매하거나 캡처하지 않습니다. 블록에 호스트 라우트 중 하나의 넥스트 홉(예: 온링크 블록의 라우터 주소)이 포함된 경우, 에이전트는 해당 주소를 제외한 블록 주변 영역에 대해서만 `local` 라우트를 설치하고 게이트웨이를 패널에 보고하며, 패널은 해당 주소를 풀 및 모든 할당에서 제외합니다. 추가 서브넷이 변경되거나 에이전트가 중지되면 설치된 라우트가 제거됩니다.
3. **방화벽을 엽니다.** 공인 주소에서 인바운드 TCP 및 UDP **65001-65535**를 허용하고, 패널로의 아웃바운드 HTTPS를 허용합니다.
4. **선택 사항: IP별 바이트 카운터.** Conntrack 회계 처리(`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 프리픽스는 두 가지 방법 중 하나로 노드에 도달합니다. 설치 프로그램은 실제 아웃바운드 연결로 둘 다 테스트하고 작동하는 것을 유지합니다.

| 종류 | 의미 | 구성하는 항목 |
|---|---|---|
| **라우팅됨** | 업스트림이 접두사(예: /48 또는 /56)를 **노드 자체의 주소로 라우팅**합니다. 아웃바운드 패킷은 접두사의 모든 주소를 소스로 사용할 수 있으며 응답은 노드로 돌아옵니다. | 공급자에 게이트웨이가 노드인 라우팅된 접두사를 요청하십시오. 노드에서 추가로 설정할 것은 없습니다. 프록시 서비스는 투명 소켓, 고정 정책 라우팅 테이블 및 `nft`을(를) 사용합니다. |
| **On-link** | /64는 노드와 동일한 LAN에 위치합니다. 사용 중인 각 주소에 대해 노드가 네이버 디스커버리에 응답하는 경우에만 응답이 작동합니다(**NDP proxy**). | 서비스는 해당 인터페이스에만 `net.ipv6.conf.<if>.accept_ra=2`, `forwarding=1` 및 `proxy_ndp=1`를 설정하고, 기존 값을 기억하며, 중지 시 복원하고, 노드가 풀의 라우터가 되지 않도록 풀 주소의 포워딩을 차단합니다. |

체크 작동 방식: 노드는 후보 접두사의 무작위 주소에서 6초 이내에 공인 IPv6 주소(포트 443)로 TCP 연결을 시도합니다. 후보는 /64 이하의 접두사를 가진 인터페이스의 글로벌 주소와 /16 및 /64 사이의 `local`, `unreachable` 또는 `blackhole` 유형의 라우트입니다. /64보다 짧은 접두사는 내부의 무작위 /64가 작동하는 경우 **routed**로 승인됩니다.

::: warning 동일한 접두사를 두 번 사용하지 마십시오
접두사는 다른 노드의 접두사와 겹칠 수 없으며, 패널 자체의 IPv6 풀에 이미 속한 접두사보다 넓을 수 없습니다. 패널 풀 **내부**의 /64는 허용됩니다. 겹치는 경우 설치 결과에 "assign range … (node …)"로 보고되며 해당 접두사는 건너뜁니다.
:::

노드가 자체적으로 적용하는 제한: 고객은 풀 주소에서 메일(포트 25, 465, 587, 2525)을 보낼 수 없으며, 데몬 자체의 IPv4 트래픽은 응답, 패널 및 DNS로 제한됩니다.

## NexCMP에서 연결 {#connect-in-nexcmp}

### VPN node {#vpn-node-2}

1. **System › Admin › License & updates**에서 **VPN** 스위치를 켭니다. [Modules](https://nexcmp.com/ko/docs/infrastructure/modules/)을(를) 참조하십시오.

      ![VPN 및 IPv6 프록시 스위치가 있는 모듈 카드](https://nexcmp.com/ko/docs/images/infrastructure/vpn-proxy-nodes-01-modules.webp)

2. **Infrastructure › VPN & Proxy nodes › Agents & external nodes**을(를) 엽니다. 노드를 추가하는 두 가지 방법이 있습니다.

   **a. SSH를 통한 설치.** **+ Add server (SSH)**을(를) 클릭하고 다음을 입력하십시오.

   | 필드 | Example value |
   |---|---|
   | Server IPv4 address | `192.0.2.50` |
   | SSH port | `22` |
   | SSH user | `root` |
   | SSH password | `XXXX` |
   | Display name | `node-ny-1` (empty: IP로 이름 지정) |
   | Server role | External VPN / Proxy Node |
   | Zone assignment | GeoIP에 의한 자동(영역 생성 / 할당) 또는 기존 영역 |
   | Extra subnet (optional) | 인터페이스를 자동 스캔하려면 비워 두거나 `203.0.113.0/24`과(와) 같은 라우팅된 블록 입력 |
   | 설치 후 판매 활성화 | 감지된 모든 주소를 판매 가능으로 표시하려면 켜기 |

   **Connect & install**을(를) 클릭합니다. 패널이 SSH를 통해 연결하고, 일회용 티켓으로 노드에서 원라인 설치 프로그램을 실행하며, 노드 이름, GeoIP 위치 및 감지된 범위를 표시합니다.

      ![예제 서버 주소 및 역할이 포함된 SSH를 통한 노드 추가 대화상자](https://nexcmp.com/ko/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/ko/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. 첫 번째 하트비트 후 노드가 목록에 표시됩니다. 노드의 국가 개별 조회 후 패널 데이터베이스를 통해 GeoIP로 감지되며, 해당 국가의 **zone**이 존재하지 않을 경우 생성되어 공개 상태로 설정되고, 호스트에서 발견된 주소들은 풀 대역이 됩니다.
4. **Infrastructure › VPN & Proxy nodes › VPN IP pools**을 열어 대역, 해당 zone 및 노드를 확인하고, 각 대역의 zone, 노드 또는 **Sellable** 스위치를 변경합니다. **Enable range**는 신규 주문 시 빈 IP를 사용할 수 있게 하며, **Disable range**는 신규 할당만 중단하고 임대 중인 IP는 계속 작동합니다.

      ![노드에서 보고된 대역이 포함된 VPN IP 풀](https://nexcmp.com/ko/docs/images/infrastructure/vpn-proxy-nodes-04-vpn-pool.webp)

5. **Services › VPN**을 열고 가격표를 설정한 후 판매를 활성화합니다. **Subscriptions**의 **Sell VPN** 스위치는 License & updates의 VPN 모듈 스위치와 동일합니다.
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**를 클릭합니다.

      ![예시 주소와 사유가 입력된 IPv6 노드 추가 대화상자](https://nexcmp.com/ko/docs/images/infrastructure/vpn-proxy-nodes-05-proxy6-add-node.webp)

3. 이후 패널은 순서대로 머신과 포트를 확인하고, 데몬, 네트워크 스크립트, 서비스 유닛 및 노드 전용 환경 파일(노드 토큰 및 비밀번호 서명 키)을 복사하고, 사용 가능한 프리픽스에 대한 **probe**를 실행하며, 풀에 프리픽스를 기록하고, 서비스를 시작한 후 첫 번째 보고를 위해 최대 90초 동안 대기합니다. **Install log**에서 각 단계를 확인할 수 있습니다.
4. 새 노드는 (노드 IPv4의 GeoIP를 기반으로) **off** 상태로 zone을 생성합니다. 고객이 선택할 수 있도록 **Infrastructure › Datacenter › Zone**에서 zone을 켭니다.
5. 노드당 전체 **Mbps cap**을 설정합니다(방향별 10~100000). **Services › IPv6 Proxy**에서 가격표를 설정하고 판매를 활성화합니다.
6. **IPv6 Proxy › Settings › Panel URL for nodes**을 확인하십시오. 노드는 구성을 가져오고 보고서를 전송하기 위해 이 주소(`https://host`, 경로 제외)를 호출합니다. 비워 두면 `https://<your license domain>`을 의미합니다. 노드 자체의 IPv4가 변경 없이 도달할 수 있도록 패널을 직접 가리키는 호스트 주소여야 합니다.

::: tip 로테이션 일정
고객은 30초에서 600초 사이의 자동 로테이션 주기를 설정할 수 있습니다. NexCMP에서는 패널이 해당 일정(및 매시간 연결 로그 정리)을 실행하며, 노드는 약 5초 이내에 새 주소를 적용합니다.
:::

### 노드 보고 방식 {#how-a-node-reports}

| | VPN node (`cmp-agent`) | IPv6 프록시 노드 |
|---|---|---|
| 등록 | HTTPS를 통한 일회성 티켓 또는 토큰, 이후 자체 키 사용 | 일회성 SSH 설치, 이후 노드 토큰 사용 |
| 하트비트 | **5초**마다 (모니터링 전용 에이전트의 경우 10초); 패널에서 3~300초로 설정 가능. 실패 시 5초 단위로 최대 60초까지 백오프 수행 | 노드는 약 60초마다 보고서를 전송하고 설정을 가져옴 |
| 온라인으로 표시 | 최근 **60초** 내 하트비트 수신 | 최근 **120초** 내 **alive**, 그렇지 않은 경우 **missed heartbeat** |
| 설정 변경 | 다음 하트비트 시 적용 | 약 5초 내 적용 |
| 업데이트 | 패널이 새 버전, URL 및 SHA-256과 함께 `upgrade` 명령을 전송할 수 있음 | 노드 행에서 재설치 |

### VPN 노드의 데이터 허용량 {#data-allowance-on-a-vpn-node}

NexCMP **1.5.1**부터 VPN 노드 에이전트는 하트비트마다 처리한 트래픽을 전송하며, 패널은 이를 현재 기간의 플랜 사용량에 추가합니다. 동일한 수치가 고객(Overview 및 Bandwidth 탭)과 관리자(VPN › Subscriptions, Used 열 및 노드 행) 모두에게 표시됩니다.

- **차단.** 플랜이 해당 기간의 허용 GB를 모두 사용하면 패널이 해당 플랜의 엔드포인트를 에이전트로 전송하는 것을 중단하므로, 새로운 연결은 거부되고 기존 연결은 닫힙니다. 차단은 1회의 하트비트 이내에 수행되므로 플랜 사용량이 한도를 약간 초과할 수 있습니다. Unlimited 등급 플랜은 차단되지 않습니다.
- **차단 해제.** 고객이 대역폭을 추가 구매하거나 다음 기간이 시작되면 1회의 하트비트 이내에 플랜 서비스가 다시 제공됩니다.
- **측정되지 않음.** 에이전트가 사용량을 전송하지 않은 노드(예: 구버전 에이전트)는 **Not measured**(으)로 표시되며, 해당 요금제는 GB 사용량으로 인해 차단되지 않습니다.
- **에이전트를 업데이트하십시오.** 노드에는 **1.5.1** 에이전트를 사용하십시오. 이전 버전의 에이전트도 트래픽이 계속 집계되지만 실패한 하트비트, 중지된 엔드포인트 또는 재시작 시 발생한 바이트가 누락될 수 있으며 플랜이 중단될 때 열려 있는 연결을 닫지 않습니다. 노드 행(Reinstall)에서 업데이트하거나 `upgrade` 명령어로 업데이트하십시오.
- 집계는 프록시를 통과하는 페이로드를 기준으로 이루어지므로, 네트워크 전송 바이트보다 약간 적습니다(약 1%).

### 단종된 VPN 부가 서비스 {#retired-vpn-add-ons}

High IP Reputation, High Concurrency 및 High Priority Network는 신규 주문 시 더 이상 제공되지 않습니다. 기존 구독은 선택한 부가 서비스를 유지하지만, 갱신 금액에서는 단종된 요금이 제외됩니다. 이미 결제된 기간에 대해서는 환불되지 않습니다. 요금 조정 시 해당 부가 서비스의 현재 카탈로그 가격이 사용되므로, 해당 가격을 변경했거나 부가 서비스를 삭제한 경우에는 다음 갱신 전에 구독의 갱신 금액을 검토하십시오.

## 확인 {#verify}

1. 노드 행이 온라인 상태입니다. VPN 노드의 경우 **Agents & external nodes**에서 zone, 국가, 역할 및 감지된 대역이 표시됩니다.
2. **VPN IP pools**에는 사용 가능한 IP가 있는 대역이 나열되며, zone의 상세 페이지에는 VPN 인프라가 표시됩니다.
3. 테스트 VPN 또는 프록시 상품을 주문합니다. 고객에게 엔드포인트 `ip:port`, 사용자 이름 및 비밀번호가 제공되며, 이를 통해 연결하여 확인된 공인 IP가 노드의 IP인지 확인합니다(예: `curl --proxy socks5h://USER:XXXX@IP:PORT https://ifconfig.me`).
4. IPv6 노드에서 호스트 상에서 실행:

   ```bash
   systemctl is-active <node service>
   nft list tables | grep proxy6
   ss -ltn | grep -E ':(80|443|6[0-9]{4})\b'
   ```

## 제한 사항 및 참고 사항 {#limits-and-notes}

- Windows 호스트는 모니터링 에이전트는 실행할 수 있으나 VPN 역할은 실행할 수 없습니다.
- VPN 플랜의 데이터 허용량(기간별 GB): NexCMP 1.5.1부터 패널은 VPN 노드 에이전트가 보고한 트래픽을 합산하고 해당 기간의 GB를 모두 소진하면 플랜의 프록시를 차단합니다(아래 "Data allowance on a VPN node" 참조). IPv6 Proxy 플랜에는 GB 허용량이 없으며 플랜당 Mbps 단위로 속도를 제한합니다.
- VPN 플랜의 IPv4 주소는 순환되지 않습니다. 고객이 블랙리스트에 등록된 IP를 신고하면 관리자 또는 리셀러가 동일한 존에서 교체를 승인합니다. IPv6 Proxy만 순환됩니다.
- 하트비트당 최대 64개의 대역이보고됩니다.
- VPN 엔드포인트 세트는 판매된 IP당 3개의 포트를 사용합니다. 포트 65001-65535를 통해 각 IP는 제한된 수의 엔드포인트(178개의 포트 세트)를 제공하며, 패널은 이전에 사용된 세트를 건너뜁니다.
- IPv6 프록시 노드는 해당 노드에 IP를 보유한 상품이 없을 때만 삭제할 수 있습니다. 노드의 대역과 토큰이 제거되며, 호스트의 소프트웨어는 제거되지 않습니다.
- 사용 중인 VM이 포함된 대역을 재판매하는 것도 가능합니다. VPN은 포트 65001-65535만 사용하므로 다른 서비스와 IP를 공유합니다.

## Troubleshooting {#troubleshooting}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| "등록 실패(잘못된 토큰이거나 서버에 연결할 수 없음)" | 잘못되었거나 이미 사용된 토큰, 또는 패널에 접근할 수 없음 | 새 토큰을 생성하거나 SSH 설치를 다시 시도하세요. |
| "파일 서명 불일치 - 중지" | 다운로드한 에이전트가 게시된 SHA-256과 다릅니다. | 패널의 `/dl/` 폴더를 확인하고 다운로드 과정에서 파일이 변조되지 않았는지 확인하세요. |
| "이 설치 프로그램은 Linux 전용입니다" / "아키텍처 …은(는) 아직 지원되지 않습니다" | Windows 또는 x86_64 이외의 아키텍처(릴리스에는 x86_64용 에이전트만 제공됨) | x86_64 Linux 호스트를 사용하세요. |
| 노드가 표시되지 않음 | 노드가 HTTPS를 통해 패널에 도달할 수 없습니다. | 노드에서 `curl https://<domain>/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` 명령을 실행한 후 노드를 다시 설치하십시오. |
| IPv6 노드 설치 시 "not found in the installed package" | 1.4.2 이전 버전의 패널이거나 노드 파일이 포함되지 않은 커스텀 빌드 | NexCMP를 1.4.2 이상으로 업데이트하십시오. 커스텀 빌드의 경우 `build.sh`을 사용하십시오. 이제 `brandy-proxy6d` 및 `brandy-proxy6-net`가 함께 패키징되어 있습니다. |
| IPv6 설치 시작 시 "SSH: …" 또는 "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**에서 영역을 활성화하세요. |


---

<!-- source: https://nexcmp.com/ko/docs/infrastructure/ai-models/ -->

# AI 모델 {#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 소스 제공업체의 이용약관을 먼저 확인하십시오
많은 모델 소스가 재판매나 제3자에 대한 액세스 권한 양도를 제한합니다. 사용 및 재판매 권한이 승인된 소스만 사용해야 하며, 해당 소스의 이용약관과 적용되는 법률을 준수하십시오. 본 페이지의 내용은 법률적 조언이 아닙니다.
:::

AI Models는 **AI Chat and AI Agent**(**AI** 모듈, [AI providers](https://nexcmp.com/ko/docs/ai/ai-providers/) 참조)와 별개의 제품입니다. 두 모듈은 서로 종속되지 않습니다.

## 요구 사항 {#requirements}

| 항목 | 요구 사항 |
|---|---|
| 모듈 | License & updates, Modules에서 **AI Models** 활성화(기본값은 비활성화). |
| Providers | 재판매 권한이 있는 하나 이상의 모델 소스로, 각각 OpenAI 호환 API(`/chat/completions`), Anthropic 호환 API(`/messages`) 또는 둘 다를 갖추고 있어야 합니다. 각 소스마다 base URL과 API key가 필요합니다. |
| 네트워크 | 패널은 퍼블릭 도메인 이름을 통해 **포트 443의 HTTPS**로 각 공급자에 연결할 수 있어야 합니다. 내부 호스트, 다른 포트 또는 일반 HTTP를 사용하는 공급자는 **Allowed internal hosts**(설정 `ai_endpoint_allow`)에 등록해야 합니다. |
| 고객 | 이메일 인증이 완료되고 지갑 잔액이 충전된 고객 계정. |
| 하드웨어 | 없음. NexCMP는 요청 전달만 수행하며, GPU나 모델 파일은 필요하지 않습니다. |

## 인프라 준비 {#prepare-the-infrastructure}

1. 사용할 각 모델 소스에서 API 키를 발급받고 기본 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` 응답을 반환하며 공급자에게 요청을 전송하지 않습니다.

![AI Models 스위치가 켜진 Module 카드](https://nexcmp.com/ko/docs/images/infrastructure/ai-models-01-modules.webp)

### 2. 공급자 추가 {#_2-add-a-provider}

1. **AI Models › Providers**를 열고 **Add provider**를 선택합니다.
2. 짧은 **slug**, **name**(관리자에게만 표시됨), **type**(OpenAI 호환, Anthropic 호환 또는 둘 다), **base URL**, **API key** 및 **priority**(낮은 숫자가 먼저 시도됨)를 입력합니다.
3. 저장합니다. 키는 암호화되어 저장되며 이후에는 마지막 4자리만 표시됩니다. 키는 로그인한 관리자 세션에서만 입력할 수 있습니다.

두 가지 형식을 실제로 모두 지원하는 게이트웨이에만 **Both**를 사용하십시오. NexCMP는 두 형식 간의 변환을 지원하지 **않습니다**. OpenAI 호환 공급자가 제공하는 모델은 `/ai/v1/chat/completions`에서, Anthropic 호환 공급자가 제공하는 모델은 `/ai/v1/messages`에서 호출됩니다.

![유형, 우선순위, 상태가 포함된 3개의 샘플 공급자가 나열된 Providers 페이지](https://nexcmp.com/ko/docs/images/infrastructure/ai-models-02-providers.webp)

### 3. 연결 테스트 {#_3-test-the-connection}

공급자에서 **Test connection**을 선택합니다. NexCMP가 키를 사용하여 `GET <base URL>/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백만 토큰당 미국 달러 기준 **판매 가격**을 설정합니다: **입력**, **캐시된 입력** 및 **출력**.
3. 선택 사항으로 모델의 **원가**를 입력할 수 있습니다. 입력 시 **Profit**에 일별 및 모델별 원가 대비 수익이 표시되며, 원가에 최소 마진(설정 `ai_min_margin_pct`, 기본값 10)을 더한 금액 미만의 판매 가격은 의도적인 손실을 확인하지 않는 한 거부됩니다. **Set price from cost**는 직접 선택한 마진율을 적용하며 기본 마진율은 없습니다.
4. 모델을 활성화합니다. 판매 가격이 없는 모델은 활성화할 수 없습니다. 0으로 남겨둔 cached input 가격에는 input 가격이 적용됩니다.

![input, cached input, output 판매 가격 및 온오프 스위치가 표시된 Models 페이지](https://nexcmp.com/ko/docs/images/infrastructure/ai-models-03-models.webp)

### 6. 라우트 및 페일오버 {#_6-routes-and-failover}

모델에서 **Routes**는 해당 모델을 제공하는 공급자를 순서대로 나열합니다. 보조 공급자를 대체 수단으로 추가하고, 순서를 설정하며, 필요에 따라 공급자마다 다른 모델 이름을 지정할 수 있습니다(공급자에게 전달되는 이름은 공개하는 이름과 달라도 무방합니다). 공급자가 서버 오류, 인증 또는 결제 오류, 모델 누락, 속도 제한을 반환하면 NexCMP는 다음 라우트를 시도합니다. 요청이 전송된 후 읽기 타임아웃이 발생한 경우 이중 결제를 방지하기 위해 다른 공급자에게 요청을 전송하지 **않습니다**.

각 공급자의 요청 속도는 분당 `ai_provider_rpm`회로 조절됩니다(기본값 50). 공급자가 인증 또는 결제 오류를 계속 반환할 경우, Telegram이 구성되어 있으면 NexCMP가 관리자에게 Telegram으로 알림을 보냅니다.

### 7. 판매 스위치 켜기 {#_7-open-the-sale-switch}

AI Models 페이지 상단의 **판매 스위치**(설정 `feature_ai_models`)는 기본적으로 꺼져 있습니다. 꺼져 있는 동안에는 고객에게 서비스가 아직 오픈되지 않은 것으로 표시되며 공개 가격표에도 이용 불가로 안내됩니다. 최소 하나의 모델이 켜져 있고 판매 가격과 키가 있는 라우트가 설정되어 있는지 확인한 후 스위치를 켭니다.

### 고객이 이용할 수 있는 기능 {#what-customers-can-do}

고객 포털의 **AI › API**:

- **Models**: 모델 및 가격, 기본 URL, 바로 사용할 수 있는 예제 명령어를 표시합니다.
- **API Keys**: 키를 생성, 이름 변경, 순환, 비활성화 및 삭제합니다. 시크릿은 한 번만 표시되며 해시만 저장됩니다. 키별 설정: 허용 모델, 만료일, 소프트 예산(경고) 및 하드 예산(`402`으로 차단), 분당 요청 수, 분당 토큰 수.
- **Usage**: 모델별, 키별, 일별 사용량(내보내기 지원).
- **Logs**: 필터링 가능한 요청 기록(시간, 키, 모델, 토큰, 비용, 상태, 지연 시간). **프롬프트와 응답은 기록되지 않습니다.** 로그는 기본적으로 90일 동안 보관됩니다(`ai_log_retention_days`).
- **Settings**: 계정 예산 및 예산 알림용 이메일 주소.
- **Playground**: 모델과 대화하고, 모델을 나란히 비교하며, 해당하는 코드를 복사합니다.

![두 가지 API 형식의 기본 URL이 표시된 고객 API Keys 페이지](https://nexcmp.com/ko/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분마다 sweep 작업이 수행되며, 아직 정산되지 않은 사용량은 게이트웨이가 확인하는 잔액에서 이미 차감됩니다.

리셀러는 자체 도메인에서 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. 지갑 잔액이 0인 상태에서 동일한 호출을 실행하면 `402 insufficient_balance`이(가) 반환됩니다.

## 제한 사항 및 참고 사항 {#limits-and-notes}

- 이 모듈에는 공급자, 모델 또는 가격이 내장되어 있지 않으며, 공급자로부터 가격표를 읽어오지 않습니다.
- 웹 검색 등 공급자 측에서 실행되고 호출당 요금이 부과되는 도구는 사용량을 측정할 수 없으므로 거부됩니다. 제한된 요청 파라미터 목록만 전달됩니다.
- 토큰 사용량은 공급자의 응답에서 가져오며, 응답에 사용량이 없는 경우 NexCMP가 이를 추정하여 해당 기록을 추정치로 표시합니다.
- 공급자로부터 반환된 오류는 고객에게 전달되기 전에 정리됩니다(이름, 호스트, 주소 및 공급자의 모델 이름 제거). 고객에게는 어떤 공급자가 요청을 처리했는지 노출되지 않습니다.
- 고객은 관리 패널의 도메인을 통해 게이트웨이에 접속하므로 해당 도메인의 TLS가 정상 작동해야 합니다.
- NexCMP는 이 모듈에 대해 서비스 수준 계약(SLA), 파인튜닝 또는 GPU 호스팅을 제공하지 않습니다.

## Troubleshooting {#troubleshooting}

| 증상 | 원인 및 해결 방법 |
|---|---|
| 모든 AI Models 페이지 및 게이트웨이에서 `404 module_disabled` 반환 | 모듈이 비활성화되어 있습니다. License & updates, Modules에서 **AI Models**을 활성화하십시오. |
| `endpoint_host_not_allowed`, `endpoint_must_be_https` 또는 `invalid_endpoint_port` 오류와 함께 공급자 추가 실패 | 기본 URL은 공용 도메인 이름의 443 포트에서 HTTPS여야 합니다. 내부 호스트, 다른 포트 또는 일반 HTTP의 경우 `host:port`을 **Allowed internal hosts** 아래에 등록하십시오. |
| `blocked_endpoint` | 주소가 IP이거나 도메인 이름이 사설 IP 주소로 확인됩니다. 의도한 구성인 경우 **Allowed internal hosts**에 등록하십시오. |
| **Test connection** 실행 시 `auth` 표시 | 키가 잘못되었거나 접근 권한이 없습니다. 키를 다시 입력하십시오. |
| 모델을 활성화할 수 없음(`no_price`) | 먼저 판매 가격을 설정하십시오. |
| 고객에게 `503 ai_unavailable` 오류 발생 | 판매 스위치가 꺼져 있거나 리셀러의 AI 스위치가 꺼져 있습니다. |
| 고객에게 `503 upstream_unavailable` 오류 발생 | 요청된 형식으로 해당 모델을 제공하는 활성화된 라우트(키 포함)가 없습니다. 모델의 라우트 및 공급자 유형을 확인하십시오. |
| 고객에게 `402 insufficient_balance` 오류 발생 | 지갑 잔액이 최소 기준 미만이거나 요청에 부족합니다. 고객에게 충전을 요청하십시오. |


---

<!-- source: https://nexcmp.com/ko/docs/infrastructure/s3/ -->

# 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는 RGW Admin Ops API를 통해 **고객의 Ceph RADOS Gateway (RGW)**에서 일치하는 사용자를 생성 및 삭제하고, 과금을 위해 사용량을 읽어들이며, 종량제 방식으로 과금합니다. 무료 티어를 초과하는 스토리지 사용량(GB/월 단위, 시간당 부과) 및 다운로드 트래픽(GB당 부과)이 대상입니다. 업로드는 무료입니다.

RGW가 포함된 Ceph 클러스터를 운영하며 오브젝트 스토리지를 재판매하려는 경우에 사용합니다.

## 요구 사항 {#requirements}

| 항목 | 요구 사항 |
|---|---|
| Ceph | 최소 하나의 RGW 데몬이 포함된 클러스터로, **Admin Ops API**가 활성화되어 있어야 합니다(기본값 `rgw_enable_apis`에 `admin` 포함). |
| 관리자 사용자 | 아래 기능이 포함된 NexCMP용 RGW 사용자입니다. 고객 데이터를 소유한 사용자는 사용하지 마세요. |
| 엔드포인트 | 고객이 사용하는 S3 엔드포인트 및 Admin Ops 엔드포인트. 둘 다 `https://host` 형식으로 작성하되 **경로 없이 포트 443만 사용**해야 하며, **공인** 주소로 확인되어야 합니다. 루프백, 링크 로컬, 멀티캐스트, 사설 및 고유 로컬 주소는 거부됩니다. |
| 인증서 | 엔드포인트 호스트용 유효한 인증서. |
| 사용량 로그 | 사용량 API가 트래픽을 보고할 수 있도록 RGW 사용량 로깅 켜기(`rgw_enable_usage_log = true`). |
| 영역 | **Object Storage (S3)** 서비스가 체크된 마스터 영역. [Zones](https://nexcmp.com/ko/docs/infrastructure/zones/)을 참조하세요. |
| 스토리지 | 판매하는 할당량에 필요한 Ceph 용량. |
| 종속성 | **Object Storage** 모듈. 다운로드 트래픽은 [Bandwidth](https://nexcmp.com/ko/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`을 복사합니다. 이 값들은 NexCMP의 **Admin access key** 및 **Admin secret key**가 됩니다.

2. 사용량 로그를 켜고 게이트웨이를 재시작합니다:

   ```bash
   ceph config set client.rgw rgw_enable_usage_log true
   ```

3. 포트 443에서 HTTPS 뒤에 게이트웨이를 배치하고(리버스 프록시 또는 RGW 자체 TLS 사용), DNS 이름을 게시한 후 패널 서버에서 테스트합니다:

   ```bash
   curl -fsS -o /dev/null -w '%{http_code}\n' https://s3.example.com/
   ```

   타임아웃이 아니라 S3 XML 응답(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**를 클릭합니다:

   | 필드 | Example value |
   |---|---|
   | Backend name | `Ceph RGW 1` |
   | 영역 | 1단계의 영역 |
   | RGW Admin Ops endpoint | `https://s3.example.com` |
   | 고객 S3 엔드포인트 | `https://s3.example.com` |
   | S3 서명 리전 | `default` |
   | 관리자 액세스 키 | `XXXX` |
   | 관리자 시크릿 키 | `XXXX` |
   | 활성 | on |
   | 판매 활성화 (먼저 연결 테스트 필요) | **off** (당분간) |
   | 변경 사유 | `initial setup` |

      ![예시 엔드포인트, 리전 및 마스킹된 키가 포함된 백엔드 S3 대화상자](https://nexcmp.com/ko/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) | 고객이 실행 중인 VM을 하나 이상 보유하는 동안 계정당 100 GB로 고정되며, 용량 기준으로 S3 계정 간에 공유됩니다. |
   | 부채 한도 (VND) | 허용되는 미납 사용량 한도입니다. |
   | 청구 임계값 (VND) | 이 금액을 초과하면 사용량이 하나의 인보우스로 집계됩니다. |
   | S3 생성 최소 잔액 (VND) | 계정을 생성하는 데 필요한 지갑 잔액입니다. |
   | 고객당 최대 S3 계정 수, 기본 기술 쿼터 (GB) | 신규 계정 제한입니다. |

      ![S3 PAYG 가격 양식](https://nexcmp.com/ko/docs/images/infrastructure/s3-04-pricing.webp)

   S3 가격은 VND로 입력됩니다. 표시 및 지갑 차감을 위해 당시의 환율로 환산되며, [Currency and exchange rates](https://nexcmp.com/ko/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}

- 이미 계정이 연결된 백엔드는 **존, 엔드포인트 및 리전**이 유지되며, 변경하려면 새 백엔드를 생성해야 합니다.
- 하나의 존에는 자체 백엔드를 가질 수 있으며, 계정과 백엔드는 영구적으로 존에 고정됩니다.
- 무료 티어와 "업로드 무료"는 옵션이 아닌 고정 규칙입니다.
- 키는 암호화되어 저장되며 콘솔에는 "현재 키를 유지하려면 비워두십시오" 필드만 표시됩니다. 키 쌍은 항상 함께 입력됩니다.
- 고객의 시크릿 키는 생성 시 한 번만 표시되며 다시는 표시되지 않습니다. 분실된 키는 회전(rotating)하여 교체합니다.

## Troubleshooting {#troubleshooting}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| "Endpoint requires HTTPS" | 엔드포인트가 일반 HTTP를 사용함 | 포트 443에서 HTTPS를 게시합니다. |
| "엔드포인트 포트가 허용되지 않음" | 443이 아닌 포트 | 표준 HTTPS 포트를 사용하세요. |
| "엔드포인트 주소가 허용되지 않습니다" | 이름이 프라이빗, 루프백, 링크 로컬 또는 유니크 로컬 주소로 해결됩니다 | 공인 주소를 사용하세요. |
| "엔드포인트는 프로토콜과 호스트만 포함해야 합니다" | 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**을(를) 실행한 후 판매를 활성화하세요. |
| "엔드포인트에 대한 모든 새 키가 필요합니다" | 두 키 모두 없이 엔드포인트가 변경되었습니다 | 액세스 키와 시크릿 키를 함께 입력하세요. |
| "백엔드에 이미 연결된 리소스가 있습니다. 영역이나 엔드포인트를 변경하려면 새 백엔드를 만드세요" | 이 백엔드에 계정이 존재합니다 | 새 백엔드를 만드세요. |
| "S3 서비스가 포함된 마스터 영역을 선택하세요" | 존이 마스터 존이 아니거나 S3 서비스가 없습니다 | 존에서 **Object Storage (S3)**을(를) 체크하세요. |
| "Invalid region" | 리전 이름에 문자, 숫자, `-` 및 `_` 이외의 문자가 포함되어 있습니다 | `default` 또는 RGW 존그룹 이름을 사용하세요. |
| "Ceph 사용량 요약이 누락되어 청구되지 않았습니다" | 사용량 로그가 비활성화되어 있습니다 | `rgw_enable_usage_log`을(를) 활성화하세요. |


---

<!-- source: https://nexcmp.com/ko/docs/infrastructure/kubernetes-and-private-cloud/ -->

# Kubernetes and 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.** 고객은 CloudStack Kubernetes Service(CKS)를 통해 CloudStack에 관리형 Kubernetes 클러스터를 생성합니다. 제어 플레인은 무료이며 고객은 **작업자** 노드 비용을 지불합니다. NexCMP는 각 클러스터에 대해 별도의 네트워크와 공인 IP를 생성하고 고객별 클러스터를 분리합니다.
- **Private Cloud.** 고객은 라우터, 서브넷(티어), 방화벽 규칙(네트워크 ACL) 및 내부 가상 머신이 포함된 프라이빗 네트워크(CloudStack VPC)를 제공받습니다. 전용의 무제한 속도(예: 50, 100, 500 Mbps, 1 및 3 Gbps)를 제공하는 **대역폭 플랜**으로 판매됩니다. 각 고객은 기본적으로 하나의 VPC를 가질 수 있습니다.

두 기능 모두 [CloudStack](https://nexcmp.com/ko/docs/infrastructure/cloudstack/)을 기반으로 구축되었으며 동일한 연결을 통해 해당 API를 사용합니다.

## 요구 사항 {#requirements}

### Kubernetes {#kubernetes}

| 항목 | 요구 사항 |
|---|---|
| CloudStack | 4.23 (테스트됨). CKS가 **활성화**되어 있어야 합니다(`cloud.kubernetes.service.enabled = true`). |
| 계정 | 전용 도메인의 **Domain Admin** 계정 (NexCMP가 고객별로 CloudStack 프로젝트와 해당 리소스 제한을 생성할 수 있도록 합니다). [CloudStack](https://nexcmp.com/ko/docs/infrastructure/cloudstack/#create-a-dedicated-account-and-api-key)을 참조하세요. |
| `endpoint.url` | CloudStack 글로벌 설정은 클러스터 VM에서 접근할 수 있는 관리 API를 가리켜야 합니다. NexCMP는 엔드포인트 확인 값과 결과를 표시합니다. |
| 버전 | 바이너리 ISO가 포함된, **Enabled** 상태의 Kubernetes 지원 버전 항목이 하나 이상 있어야 합니다. 지원 종료(EOL)가 지난 버전은 판매할 수 없습니다. |
| 컨트롤 플레인 오퍼링 | 계정에 표시되는, **정확히 2 vCPU, 2048 MB RAM 및 CPU 제한**이 있는 무료 서비스 오퍼링 (`limitcpuuse = true`). 서버는 다른 모든 요청을 `cp_offering_invalid`(으)로 거부합니다. |
| 네트워크 | 활성화된 CKS 호환 격리 네트워크 오퍼링. |
| IP | 판매 가능한 대역 내의 무료 공인 IPv4 주소; 각 클러스터는 하나씩 사용합니다. |
| 용량 | 각 클러스터는 컨트롤 플레인과 소형 라우터 VM용으로 2~4 GB의 RAM을 사용합니다. 용량 탭을 확인하세요. |

### Private Cloud {#private-cloud}

| 항목 | 요구 사항 |
|---|---|
| CloudStack | 4.23 (테스트됨), VPC 활성화. |
| VPC 오퍼링 | VPC 오퍼링 1개. 듀얼 스택 오퍼링은 각 티어에도 IPv6 /64를 부여합니다. |
| 티어 네트워크 오퍼링 | **대역폭 플랜당 하나의 네트워크 오퍼링** (VPC용으로 생성, **네트워크 속도**(Mbps)는 해당 플랜과 동일)과, 미납으로 VPC가 잠겼을 때 적용되는 **1 Mbps**의 **잠긴** 오퍼링 1개가 필요합니다. |
| 계정 | 전용 계정 (Domain Admin 권장). VPC 네트워크는 프로젝트가 아닌 계정에 유지됩니다. |
| IP | 무료 공인 IPv4 주소 (각 VPC는 소스 NAT용으로 하나씩 사용합니다). |
| 주소 공간 | 각 VPC는 `10.128.0.0/9`에서 /16을 할당받습니다. 해당 대역은 자체 네트워크에서 사용하지 마십시오. |
| 종속성 | CloudStack 연결 완료; **Private Cloud** 모듈. |

## 인프라 준비 {#prepare-the-infrastructure}

### Kubernetes: CKS 활성화 및 버전 추가 {#kubernetes-enable-cks-and-add-versions}

1. 서비스를 활성화하고 엔드포인트를 설정한 후 관리 서버를 재시작합니다:

   ```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`은(는) 클러스터의 컨트롤러가 콜백하므로, 클러스터 VM이 도달할 수 있는 주소여야 합니다.

2. CloudStack 소스 트리의 `create-kubernetes-binaries-iso.sh` 스크립트를 사용하여 판매하려는 버전에 대한 Kubernetes 바이너리 ISO를 빌드하고, 웹 서버에 호스팅한 뒤 등록합니다:

   ```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=<zone-id> \
     mincpunumber=2 minmemory=2048
   cmk list kubernetessupportedversions filter=name,semanticversion,state,isostate
   ```

   ISO 상태가 **Ready**가 되고 버전이 **Enabled** 상태가 될 때까지 기다립니다.

3. 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=<domain-id>
   ```

4. CKS 네트워크 오퍼링이 활성화되어 있는지 확인합니다:

   ```bash
   cmk list networkofferings state=Enabled forvpc=false filter=id,name
   ```

### Private Cloud: 오퍼링 생성 {#private-cloud-create-the-offerings}

CloudStack UI (**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 오퍼링을 사용합니다 (IPv6을 원할 경우 듀얼 스택). 새로운 오퍼링이 필요한 경우, CloudStack의 기본 VPC 오퍼링을 복제하고 활성화하세요.
3. 판매하는 **각** 대역폭 플랜에 대해 **VPC용** 네트워크 오퍼링을 생성하고 (기본 "isolated network offering for VPC networks" 복제), **Network rate (Mb/s)**을(를) 플랜 속도인 `50`, `100`, `500`, `1000`, `3000`(으)로 설정합니다. 각 오퍼링을 활성화하세요.
4. 잠긴 VPC를 위해 **네트워크 속도 1**(`VPC-LOCKED-1M`)인 오퍼링을 하나 더 생성합니다. 고객은 SSH를 통해 서버에 계속 접속할 수 있지만 속도가 제한됩니다.
5. 모든 오퍼링의 UUID를 기록해 둡니다. 다음 섹션에서 NexCMP에 필요합니다.

::: warning 제공된 오퍼링 ID가 클라우드에 존재하지 않음
Private Cloud 양식에는 다른 CloudStack 설치에 속하는 오퍼링 UUID가 미리 채워져 있습니다. **모두** 본인의 UUID로 교체하세요. 그렇지 않으면 첫 번째 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**, CKS 네트워크 오퍼링, `cloud.kubernetes.*` 설정 및 ISO와 버전 목록과 함께 표시됩니다. 문제를 해결한 후 **Recheck**를 클릭합니다.
2. **Sales config**에서 **Control plane Offering**을 선택하고(exact 2 vCPU / 2048 MB / CPU cap이 아니면 경고가 표시됨), **Max workers per cluster**(1~9: CKS는 제어 노드를 포함해 10개 노드 허용)를 설정한 다음, **Enable CKS for this backend** 스위치를 켜고 **Save**를 클릭합니다. 오퍼링이 선택될 때까지 스위치는 비활성화 상태로 유지됩니다.

      ![제어판 오퍼링이 선택되고 CKS 상태 카드가 표시된 Kubernetes (CKS) 탭](https://nexcmp.com/ko/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 정책](https://nexcmp.com/ko/docs/images/infrastructure/kubernetes-and-private-cloud-03-policy.webp)

### Private Cloud {#private-cloud-1}

1. **Services › Private Cloud**(개요)를 엽니다. 정책 카드에서 **VPC offering** 및 **Locked offering tier**를 본인의 UUID로 교체합니다. 제한 사항(계정당 VPC, 계층, VPC당 VM 및 ACL 규칙, 생성에 필요한 플랜 요금의 시간 단위 잔액, 24시간당 플랜 변경, 0이 긴급 정지를 의미하는 동시 작업)과 DNS 서버를 확인합니다. **Save**를 클릭합니다(사유를 묻는 창이 나타남).

      ![VPC 오퍼링과 잠긴 오퍼링 필드가 표시된 Private Cloud 개요](https://nexcmp.com/ko/docs/images/infrastructure/kubernetes-and-private-cloud-04-vpc-policy.webp)

2. **Services › Private Cloud › Plans & pricing**을 엽니다. 각 플랜에 대해 **Edit**을 클릭하고 **VND price per month**, **On sale**, 그리고 네트워크 속도가 플랜의 Mbps와 일치하는 **CloudStack tier offering** UUID를 설정합니다. 행에는 최대 사용 시의 비용과 수익이 표시되므로 비용 대비 손실이 발생하는 플랜을 확인할 수 있습니다.

      ![Private Cloud 대역폭 플랜에 대한 플랜 편집 대화상자](https://nexcmp.com/ko/docs/images/infrastructure/kubernetes-and-private-cloud-05-vpc-plan.webp)

3. **Sell Private Cloud** 스위치를 켭니다. 먼저 테스트하려면 테스트 계정 ID를 **Beta accounts**에 추가하세요. 해당 계정은 판매 스위치가 꺼져 있어도 서비스를 이용할 수 있습니다.

## 확인 {#verify}

1. Kubernetes: 상태 카드에 `kubernetesserviceenabled: true`, 양호한 엔드포인트 확인 및 활성화된 버전이 표시됩니다. 고객 권한으로 1개의 워커가 있는 테스트 클러스터를 생성하면 실행 중 상태가 되어야 하고 `kubectl get nodes`에 준비 완료 상태가 표시되어야 합니다. 생성 후 삭제하면 네트워크와 IP가 풀로 반환됩니다.
2. Private Cloud: 테스트 고객으로서 가장 작은 요금제로 VPC를 생성합니다. VPC가 활성 상태로 표시되고, 티어에 서브넷이 할당되며, 티어의 VM이 VPC 라우터를 통해 인터넷에 접속할 수 있고, **Change plan**으로 더 큰 요금제로 변경하면 연결 끊김 없이 약 20초 내에 적용됩니다.

## 제한 사항 및 참고 사항 {#limits-and-notes}

- Kubernetes: 워커는 VM 요금제 가격으로 과금되며 VM 제한에서 VM으로 산정됩니다. 10개 노드라는 CKS 제한으로 인해 클러스터에는 최대 9개의 워커를 둘 수 있습니다.
- Kubernetes: 클러스터의 컨트롤 플레인, 라우터 및 공인 IP는 고객에게 무료로 제공되며, 비용은 귀하가 부담합니다.
- Private Cloud: 모든 요금제는 **unmetered**입니다. 양식의 가격은 월별 베트남 동 단위이며, 비용 열은 귀하의 가격이 아닌 참고 가격을 사용하므로 자체 금액을 사용해야 합니다.
- 잠긴 VPC는 1 Mbps로 제한되며, 과금되지 않고 자동으로 삭제되지 않습니다.
- Private Cloud는 이중화된 쌍이 아닌 VPC당 하나의 라우터를 사용합니다. 호스트에 장애가 발생하면 CloudStack이 몇 분 안에 재구축합니다.

## Troubleshooting {#troubleshooting}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| `cp_offering_invalid` / "본 오퍼링은 2 vCPU / 2048 MB / limitcpuuse가 아닙니다" | 컨트롤 플레인 오퍼링의 크기가 다르거나 CPU 제한이 없음 | 3단계와 같이 오퍼링을 생성하고 다시 선택합니다. |
| **Enable CKS** 스위치가 꺼져 있음 | 선택된 컨트롤 플레인 오퍼링이 없음 | 먼저 하나를 선택하세요. |
| `kubernetesserviceenabled: false` | CloudStack에서 CKS가 꺼져 있음 | 이를 활성화하고 관리 서버를 재시작합니다. |
| 엔드포인트 확인 실패 | 클러스터 VM에서 `endpoint.url`에 접근할 수 없음 | 접근 가능한 URL을 설정하고, 관리 서버를 재시작한 후 **Recheck**을 클릭합니다. |
| "지원 종료(EOL): 판매용으로 활성화할 수 없음" | 버전의 지원 종료일이 지남 | 더 최신 버전을 등록합니다. |
| "버전 없음: Sync from CloudStack 클릭" | 등록된 Kubernetes 버전이 없음 | 버전을 등록하고 동기화합니다. |
| "CKS 백엔드가 꺼져 있음: 판매 플래그가 켜져 있어도 고객이 클러스터를 생성할 수 없음" | 판매 스위치는 켜져 있으나 CKS 백엔드가 꺼져 있음 | CloudStack 탭에서 CKS를 활성화합니다. |
| "최소 1개의 플랜이 판매 중이어야 함" | 마지막 워커 요금제가 제거됨 | 최소 하나의 요금제를 유지하거나 Kubernetes 판매를 끄세요. |
| 클러스터 생성 중 멈춤 | 용량이 부족하거나 ISO가 누락됨 | 용량 탭과 버전의 ISO 상태를 확인합니다. |
| 새 VPC가 첫 단계에서 실패함 | VPC 오퍼링 또는 티어 오퍼링 ID가 유효하지 않음 | 모든 오퍼링 UUID를 CloudStack의 것으로 교체합니다. |
| "cs_offering_id는 UUID여야 함" | 오퍼링 ID가 UUID가 아님 | `cmk list networkofferings`에서 ID를 복사하여 붙여넣으세요. |
| 요금제 변경 실패 | 새 티어 오퍼링이 존재하지 않거나 네트워크 레이트가 잘못되었습니다 | 오퍼링 UUID와 네트워크 레이트를 확인하세요. |




---

<!-- source: https://nexcmp.com/ko/docs/catalog/plans/ -->

# 요금제 및 가격 책정 {#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 연결(요금제에서 CloudStack 서비스 오퍼링 지정) 또는 리전에 연결된 Proxmox VE 클러스터. [CloudStack](https://nexcmp.com/ko/docs/infrastructure/cloudstack/) 및 [Proxmox VE](https://nexcmp.com/ko/docs/infrastructure/proxmox/)를 참조하세요. |
| 영역 | 가상 머신을 판매하는 리전. [Zones](https://nexcmp.com/ko/docs/infrastructure/zones/)를 참조하세요. |
| 템플릿 | 활성화되고 준비된 1개 이상의 템플릿. [OS templates](https://nexcmp.com/ko/docs/infrastructure/templates/)를 참조하세요. |
| 환율 | VND로 가격을 입력하는 경우에만 해당됩니다. [Currency and exchange rates](https://nexcmp.com/ko/docs/catalog/currency-and-exchange-rates/)를 참조하세요. |
| Permissions | 관리자: 모든 가격 변경 시 사유를 요구합니다. |

## 인프라 준비 {#prepare-the-infrastructure}

- **CloudStack:** 판매할 서비스 오퍼링(공개 또는 NexCMP 도메인과 공유)을 생성합니다. 요금제는 하나의 오퍼링을 지정합니다. **Offering CloudStack** 탭에는 CloudStack에서 실시간으로 가져온 오퍼링 및 디스크 오퍼링 목록이 표시됩니다(60초간 캐시됨). 요금제 테이블이 비어 있는 경우, 워커가 실제 오퍼링을 바탕으로 6개의 요금제를 자동으로 생성합니다.
- **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/hour, 월간 가격 및 모든 결제 주기. **월간 가격 = 시간당 가격 × 730**이며, 더 긴 주기는 **월간 가격 × 개월 수 × (1 − 할인율)**로 계산됩니다.

### 요금제 추가 {#add-a-plan}

1. **Services › Virtual Machines › Plans & pricing**으로 이동하여 **Add plan**을 클릭합니다.
2. 양식을 작성합니다:

   | 필드 | Example value |
   |---|---|
   | 요금제 이름 | `VM-2-4` |
   | Slug | 비워 둠: 이름으로 생성됨 |
   | 영역 | 기본 존 |
   | 인프라 소스 | CloudStack의 경우 비워 둠, 또는 Proxmox 클러스터 |
   | 서비스 오퍼링 CloudStack (실시간) | 선택 (CloudStack에만 표시됨) |
   | CPU (코어), RAM (MB), 루트 디스크 (GB) | `2`, `4096`, `40` |
   | 디스크 오퍼링 | 선택 사항, 사용자 지정 루트 크기용 |
   | 단위별 가격 입력 / 가격 | `USD / month`, `12` |
   | 간단한 설명 | `2 vCPU, 4 GB RAM, 40 GB NVMe` |
   | 순서 | `10` |
   | 활성 | 켜짐: 고객이 구매 가능 |
   | Visibility | 카탈로그에 표시 |
   | 가격 변경 사유 | `initial price` |


3. **OK**을 클릭합니다. 테이블에 요금제가 시간당 및 월간 가격과 함께 활성화된 각 주기별 셀과 함께 표시됩니다.

      ![시간당, 월간, 주기별 가격이 표시된 Plans table](https://nexcmp.com/ko/docs/images/catalog/plans-02-list.webp)

### 결제 주기 {#billing-cycles}

**Cycle** 탭을 열어 고객이 선택할 수 있는 결제 주기와 할인율을 설정합니다.

| 주기 | Default | 참고 |
|---|---|---|
| 시간제 | 항상 켜짐 | 시간 단위로 청구됩니다. |
| 월간 | 켜짐, 0% | |
| 1년 | 켜짐, 10% | |
| 2년 | 켜짐, 15% | |
| 3년 | 켜짐, 20% | |

주기를 이름 변경하고, 할인율(0~90%)을 변경하며, 켜거나 끌 수 있습니다. 변경 사항은 저장 **이후**에 구매 또는 갱신된 VM에 적용되며, 실행 중인 VM은 기존에 고정된 가격을 유지합니다.

![청구 주기별 할인이 표시된 주기 탭](https://nexcmp.com/ko/docs/images/catalog/plans-03-cycles.webp)

### 기본 요금제를 설정하고 다른 요금제 파생하기 {#set-a-base-plan-and-derive-the-others}

**기본 요금제 설정 + 다른 요금제 파생** 기능은 하나의 가격을 기준으로 전체 테이블의 가격을 재조정합니다. 기본 요금제와 그 가격을 선택한 다음, 요금제 간의 **현재 가격 비율**을 유지하거나 **구성 요소 가격**(vCPU 당, RAM 1GB 당, NVMe 1GB 당 µ$/시간, 선택 사항으로 0~50% 번들 할인 적용)을 기준으로 계산할 수 있습니다. 변경 사항이 적용되기 전에 미리보기 테이블에 이전 가격과 새 가격이 표시됩니다. **Apply**를 클릭하고 사유를 입력하십시오.

새 가격을 적용하면 실행 중인 **시간제** VM은 다음 청구 시간부터 **인하된** 가격이 적용되고, 선불 VM은 갱신 시 적용됩니다. 가격이 **인상**되는 경우, 실행 중인 VM은 기존 가격을 유지합니다.

### 사용자 정의 요금제 {#custom-plans}

**Custom plan** 탭을 통해 고객은 원하는 vCPU, RAM, NVMe 크기를 직접 선택할 수 있습니다. vCPU 1개, RAM 1GB, NVMe 1GB당 시간당 단가(비율 할인으로 계산하려면 비워 둠), 각각의 최소값·최대값·증분, 적용할 결제 주기를 설정합니다. **custom** 플랜은 동일한 크기의 고정 플랜보다 더 비싸야 합니다. 그렇지 않으면 고객이 고정 플랜을 건너뛸 것이기 때문이며, 페이지는 custom이 더 저렴한 행에 경고를 표시합니다. 판매하려면 **Enable custom plans for customers**를 켜고, 끄면 포털에 "Coming soon"이 표시됩니다. 각 커스텀 VM에는 숨겨진 고유 플랜 행이 할당되며, 해당 VM이 존재하는 동안에는 이 행을 수정하거나 삭제할 수 없습니다.


### 변경, 숨기기, 복제, 삭제 {#change-hide-clone-delete}

| 작업 | 작동 내용 |
|---|---|
| **Edit** | 이름, 설명, 순서, 가격, 활성 상태 및 표시 여부를 변경합니다. |
| **켜기/끄기** | **Off**: 고객이 구매할 수 없으며, 실행 중인 VM에는 영향을 주지 않습니다. |
| **숨기기 / 표시** | 숨겨진 요금제는 카탈로그에 표시되지 않지만 기존 VM은 이를 유지하며 관리자가 할당할 수 있습니다. |
| **Clone** | 새 소스, 크기 또는 가격으로 동일한 영역에 새 요금제를 생성하며, 선택적으로 기존 요금제를 숨길 수 있습니다. CloudStack과 Proxmox에서 동일한 구성을 판매하려면 복제하고 다른소스를 선택하십시오. |
| **위/아래로 이동** | 순서를 변경합니다. |
| **Delete** | 판매 및 테이블에서 요금제를 제거합니다. 이미 이를 사용 중인 VM은 요금제를 유지합니다. |

::: warning 사용 중인 요금제는 잠깁니다
요금제에 VM이 할당되면 실행 중인 VM이 예기치 않게 변경되지 않도록 **영역, 오퍼링, CPU, RAM, 디스크 및 소스**가 잠깁니다. 새 구성을 만들려면 **Clone**을 사용하십시오. 기존 요금제는 VM을 유지합니다.
:::

## 확인 {#verify}

1. 예상되는 시간당 및 월간 가격과 함께 요금제가 테이블에 표시됩니다.
2. 고객 포털에서 주문을 시작합니다. 영역이 요금제를 제공하며 주기 가격이 **Cycle** 탭과 일치합니다.
3. 테스트 주문을 진행하고 표시된 가격과 지갑 차감액을 확인한 후 VM을 삭제하십시오.

## 제한 사항 및 참고 사항 {#limits-and-notes}

- 요금제는 **하나**의 영역과 **하나**의 소스에 속합니다.
- 가격은 µ$/시간 단위로 저장되며, 표시되는 VND 가격은 **VND rounding step**(통화 페이지 참조)에 따라 파생되고 반올림됩니다. 지갑은 항상 USD로 표시됩니다.
- 리셀러는 목록 가격에서 파생된 도매 및 소매 가격을 받으며, 기존 요금제의 가격을 변경해도 구성을 변경한 복제본에는 맞춤 리셀러 가격이 복사되지 않습니다.
- 사용자 정의 요금제의 최소, 최대 및 단위 제한은 CloudStack 자체 제한을 기준으로 확인됩니다. CloudStack의 `storage.max.volume.size`을 초과하는 최대 디스크 크기는 배포 실패 및 환불을 유발합니다.

## Troubleshooting {#troubleshooting}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| "요금제 이름 필요" / "서비스 오퍼링 필요" | 누락된 필드 | 이름을 입력하고, CloudStack의 경우 오퍼링을 선택하세요. |
| "CPU/RAM/disk는 > 0이어야 합니다" | 크기가 비어 있거나 0입니다 | 세 가지 모두 입력하세요. |
| "잘못된 가격 (µ$/시간은 1 … 100,000,000이어야 합니다)" | 가격이 허용 범위를 벗어났습니다 | 단위와 금액을 확인하세요. |
| "가격 변경에는 사유가 필요합니다" | 수정 시 사유가 비어 있음 | 사유를 입력하세요 (3자 이상). |
| "오퍼링 "X"는 4c/8192이지만 요금제는 2c/4096으로 지정되어 있습니다. CloudStack은 오퍼링 기준으로 프로비저닝합니다. 저장하시겠습니까?" | 요금제 수치가 오퍼링과 다릅니다 | 일치시키거나 CloudStack 크기를 유지하도록 확인하세요. |
| "CloudStack에서 오퍼링을 가져오지 못했습니다" | 연결이 끊어졌거나 키에 권한이 없습니다 | [CloudStack](https://nexcmp.com/ko/docs/infrastructure/cloudstack/)을(를) 참조하세요. |
| "CloudStack에서 템플릿이 준비되지 않아 배포가 실패합니다. 그래도 활성화하시겠습니까?" | 완료되지 않은 템플릿을 활성화했습니다 | 템플릿이 준비될 때까지 기다리세요. |
| 요금제를 수정할 수 없음 ("VM이 있음 - 잠김") | VM이 해당 요금제를 사용 중입니다 | 복제하세요. |
| 고객에게 요금제가 표시되지 않음 | 꺼져 있거나, 숨겨져 있거나, 영역이 준비되지 않음 | **Active**, **Visibility** 및 영역 태그를 확인하세요. [Zones](https://nexcmp.com/ko/docs/infrastructure/zones/)을(를) 참조하세요. |
| "결제 주기를 1개 이상 선택하세요" | 사용자 정의 요금제에 선택된 주기가 없음 | 하나 이상 선택하세요. |
| "번들 할인율은 0–50%여야 합니다" | 범위를 벗어남 | 0에서 50 사이의 값을 사용하세요. |
| VND 가격 옵션이 누락됨 | 환율 정보가 아직 없음 | 먼저 환율을 업데이트하세요. |


---

<!-- source: https://nexcmp.com/ko/docs/catalog/bandwidth/ -->

# 대역폭 할당량 및 애드온 {#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}

대역폭은 측정 대상 서비스마다 월간 트래픽 **할당량**을 부여합니다. NexCMP는 사용량을 측정하여 80% 및 100% 도달 시 고객에게 경고하며, 할당량을 초과하면 **초과 사용 정책**에 따라 조치합니다. 고객은 지갑에서 추가 테라바이트 **애드온**을 구매할 수 있으며, 관리자가 무료로 애드온을 부여할 수도 있습니다.

| 서비스 | 할당량 |
|---|---|
| 가상 머신 | VM당 월 기준 (기본값 2048 GB, 즉 2 TB) |
| Kubernetes | VM 할당량에 워커 수를 곱한 값 |
| Object Storage | 고객당 월 다운로드 트래픽 (기본값 100 GB); 초과 시 일반 종량제 가격 적용 |
| VPN | 요금제의 할당량을 유지하며, VPN 페이지에서 대역폭을 업그레이드합니다 |
| Private Cloud | **무제한** |

## 요구 사항 {#requirements}

| 항목 | 요구 사항 |
|---|---|
| 모듈 | **Bandwidth**는 기본적으로 켜져 있습니다. 숨기려면 License & updates에서 끕니다. |
| 측정 소스 | 기본 소스인 **CloudStack VM statistics**를 사용합니다. CloudStack에서 VM 통계 수집을 활성화 상태로 유지하세요. 기본 보관 기간인 720분이면 충분합니다. |
| Proxmox VE | Proxmox VE의 VM은 **측정되지 않습니다**. |
| 환율 | 추가 기능 가격은 VND로 입력됩니다. [Currency and exchange rates](https://nexcmp.com/ko/docs/catalog/currency-and-exchange-rates/)를 참조하세요. |
| 종속성 | VM 및 Kubernetes 트래픽은 [CloudStack](https://nexcmp.com/ko/docs/infrastructure/cloudstack/), 스토리지 다운로드는 [S3](https://nexcmp.com/ko/docs/infrastructure/s3/)를 사용합니다. |

## 인프라 준비 {#prepare-the-infrastructure}

CloudStack이 연결되어 있으면 별도로 필요하지 않습니다. NexCMP는 계정의 모든 VM에 대해 5분마다 한 번의 호출로 최대 2시간의 윈도우 내에서 `listVirtualMachinesUsageHistory` 데이터를 읽습니다. 각 샘플은 1분 분량을 다루며 **합산**됩니다. 샘플은 데이터가 도착할 시간을 주기 위해 3분 전 시점을 기준으로 수집됩니다. CloudStack의 보존 기간(약 12시간)보다 긴 공백은 건너뛰고 기록됩니다.

::: info 숫자의 의미
사용량은 각 VM의 네트워크 인터페이스에서 집계되므로 인터넷으로 향하는 트래픽뿐만 아니라 VM 간 트래픽도 포함됩니다. 엣지 라우터에서 집계하는 것보다 약간 높을 수 있습니다.
:::

## NexCMP에서 연결 {#connect-in-nexcmp}

1. **Services › Bandwidth › Quotas, pricing & policy**를 엽니다.
2. 값을 설정하고 **Save**를 클릭합니다. 사유를 묻는 입력창이 나타나며 기록됩니다. 작업자는 약 30초 내에 변경 사항을 적용합니다.

   | 필드 | Default | 의미 |
   |---|---|---|
   | Enable Bandwidth (고객 메뉴 및 추가 기능 구매) | on | 모듈 판매 측면의 스위치입니다. |
   | VM, GB/월 (Kubernetes = 이 값 × 워커 수) | 2048 | 기간별 VM당 할당량입니다. |
   | S3, 고객당 GB 다운로드/월 | 100 | 이를 초과하면 일반적인 S3 종량제가 적용됩니다. |
   | 할당량 방향 (VM, Kubernetes) | 수신 + 송신 | 또는 **Outbound only**입니다. |
   | +1 TB 가격 (VND) | 100,000 | 시세 환율에 따라 센트로 변환됩니다. |
   | 구매당 최대 (TB) | 50 | |
   | 초과 사용 정책 | 정지 | **notify**, **throttle** 또는 **suspend**(아래 참조). |
   | 실제 정지 집행일 | 마이그레이션 날짜 + 24시간 | 이 날짜 전까지는 아무것도 정지되지 않으며 고객에게 경고만 발송됩니다. |
   | 속도 제한 (Mbps) | | throttle에서만 사용됩니다. |

      ![대역폭 정책: 기본 할당량, 애드온 가격 및 초과 사용량 정책](https://nexcmp.com/ko/docs/images/catalog/bandwidth-01-policy.webp)

### 초과 사용 정책 {#overage-policies}

| 정책 | 서비스가 100%를 초과할 때 발생하는 일 |
|---|---|
| **notify** | 고객에게 알림이 전송됩니다. 그 외에는 아무 일도 일어나지 않습니다. |
| **throttle** | 현재는 notify와 같습니다. 이 릴리스에서는 속도 제한기가 연결되어 있지 않습니다. |
| **suspend** (기본값) | 고객이 추가 기능을 구매하거나 다음 기간이 시작될 때까지 VM, 클러스터 또는 S3 계정이 정지됩니다. **suspend-from** 날짜부터만 유효합니다. |

80% 및 100% 경고(벨 및 이메일)는 임계값, 기간, 서비스당 한 번씩 항상 실행됩니다. 할당량을 초과한 상태로 대역폭 때문에 정지된 서비스를 잠금 해제하면 다음 검사(5분 이내) 시 다시 정지됩니다. 계속 실행하려면 **추가 기능을 부여**하세요.

### 사용량 확인 및 추가 제공 {#watch-usage-and-grant-add-ons}

**Services › Bandwidth › Summary**를 엽니다. 현재 기간의 사용량, 추가 기능을 포함한 할당량, 남은 할당량, 80% 및 100% 지점이 표시된 모든 서비스가 나열됩니다. KPI 타일에는 서비스 수, 지난 30일 동안 판매된 추가 기능 수, 수집기 상태(실행 중, 커서)가 표시됩니다. **Daily** 표에는 현재 기간의 일별 데이터가 표시됩니다.

![수집기 상태 및 서비스별 사용량이 표시된 Bandwidth Summary](https://nexcmp.com/ko/docs/images/catalog/bandwidth-02-summary.webp)

고객에게 여유를 주려면 서비스에서 **Grant**를 사용하여 요금 없이 테라바이트 단위의 추가 기능을 제공합니다. 구매 및 제공 내역을 최신순으로 유형 필터와 함께 보려면 **Add-on**을 엽니다.

![구매 및 무료 제공 내역을 보여주는 Add-on 내역](https://nexcmp.com/ko/docs/images/catalog/bandwidth-03-addons.webp)

### 고객 화면 {#what-customers-see}

고객 포털에는 사용량, 남은 할당량, 지갑에서 결제하는 **buy +1 TB** 작업(구매당 최대 한도까지)이 포함된 **Bandwidth** 메뉴가 추가됩니다. 추가 기능은 현재 기간 동안 유효합니다.

## 확인 {#verify}

1. **Summary**의 수집기가 실행 중이며 몇 분마다 커서가 앞으로 이동합니다.
2. 트래픽이 있는 VM은 약 10~15분 후에 사용량이 표시됩니다.
3. 알림을 확인하려면 **test** 설치에서 VM 할당량을 몇 GB로 낮추고 트래픽을 발생시키세요. 프로덕션 환경에서는 이 작업을 수행하지 마세요. 할당량은 모든 VM에 적용됩니다.

## 제한 사항 및 참고 사항 {#limits-and-notes}

- 사용량은 기간(1개월)별로 집계됩니다. 추가 기능과 할당량은 현재 기간에 적용됩니다.
- "Enforce actual suspend from"은 모듈이 처음 활성화된 순간 고객이 정지되는 것을 방지합니다.
- 이 릴리스에서는 스로틀 정책이 알림만 제공합니다.
- 할당량을 변경하면 리셀러 사이트를 포함한 모든 사이트에 적용됩니다. 리셀러의 소매 및 도매 추가 기능 가격은 할인 또는 마크업을 따릅니다.
- **Dedicated servers**의 대역폭은 별개의 문제입니다. [Dedicated servers](https://nexcmp.com/ko/docs/infrastructure/dedicated/)를 참조하세요.

## Troubleshooting {#troubleshooting}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| 실행 중인 VM의 사용량이 0으로 유지됨 | 워커가 중지되었거나, CloudStack 연결이 끊어졌거나, VM 통계가 비활성화됨 | `sudo nexcmp status` 및 **Test connection**을 [CloudStack](https://nexcmp.com/ko/docs/infrastructure/cloudstack/)에서 확인하고 CloudStack VM 통계를 활성화하십시오. |
| 사용량에 누락된 구간이 있음 | CloudStack 보관 기간이 초과되었거나 워커가 약 12시간 이상 중단됨 | 복구할 수 없으며 누락된 구간이 기록됩니다. |
| 사용량이 예상보다 약간 많음 | VM 간 트래픽 및 기타 인터페이스 트래픽이 포함됨 | 정상적인 동작이므로 고객에게 안내하세요. |
| 정지된 서비스를 해제했는데도 다시 정지 상태로 돌아감 | 여전히 할당량을 초과한 상태임 | 추가 기능을 제공하거나 할당량을 늘리세요. |
| 정책이 **suspend**인데도 아무것도 정지되지 않음 | 정지 시작일이 미래로 설정되어 있음 | 현재 시각으로 설정하세요(적용 시 페이지에 "ACTIVE"가 표시됨). |
| "bw_over_policy는 notify, throttle 또는 suspend 중 하나여야 합니다" | API를 통해 잘못된 정책이 전송됨 | 세 가지 값 중 하나를 사용하세요. |
| Proxmox VM에 사용량이 표시되지 않음 | 측정 대상이 아님 | 정상입니다. |
| 고객이 추가 기능을 구매할 수 없음 | 대역폭이 꺼져 있거나 지갑이 비어 있음 | 스위치와 지갑을 확인하세요. |




---

<!-- source: https://nexcmp.com/ko/docs/catalog/currency-and-exchange-rates/ -->

# 통화 및 환율 {#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 금액을 현지 통화로 확인할 수 있으며, 지갑 잔액은 변경되지 않습니다. 대역폭 애드온, S3, Private Cloud 및 VND 가격 정책을 유지하는 기존 Bare Metal 플랜을 비롯한 일부 서비스는 VND로 입력된 가격을 지원합니다. SePay를 통한 계좌 이체는 VND로 결제됩니다.

환율은 **관리자가 직접 게시**합니다. 자동으로 새로 고쳐지지 않으므로 저장한 환율은 업데이트 버튼을 누를 때까지 그대로 유지됩니다.

## 요구 사항 {#requirements}

| 항목 | 요구 사항 |
|---|---|
| 인터넷 액세스 | 패널 서버는 `open.er-api.com`(USD/VND용) 및 `api.frankfurter.dev`(기타 통화용)에 연결할 수 있어야 합니다(**Update exchange rates**를 누를 때). |
| Permissions | 관리자만 변경할 수 있으며, 모든 변경 시에는 사유를 입력해야 합니다. |
| 종속성 | 없음. [Plans](https://nexcmp.com/ko/docs/catalog/plans/), [Bandwidth](https://nexcmp.com/ko/docs/catalog/bandwidth/), [S3](https://nexcmp.com/ko/docs/infrastructure/s3/) 및 VND 은행 송금에 환율이 사용됩니다. |

## 인프라 준비 {#prepare-the-infrastructure}

필요하지 않습니다. 서버가 아웃바운드 트래픽을 필터링하는 경우 위의 두 서비스에 대한 HTTPS를 허용하세요.

## NexCMP에서 연결 {#connect-in-nexcmp}

### 1. 사이트 통화 선택 {#_1-choose-the-site-currency}

**System › Settings › Brand**를 열고 **Site currency**를 설정합니다.

| 선택 | 고객 화면 |
|---|---|
| **Language-based (auto)** (신규 설치 시 기본값) | 포털이 언어에 맞춰 표시 통화를 선택합니다(아래 표 참조). 고객이 USD를 대신 선택할 수도 있습니다. |
| **USD** | USD로만 표시되는 가격 및 잔액. 통화 전환 및 변환된 금액 없음. |
| **VND** | 레거시 설정이며, Auto와 동일한 언어 기반 표시 규칙을 따릅니다. |

저장합니다. 고객 페이지는 약 1분 내에 업데이트됩니다.


사이트가 고객의 언어를 따르는 경우:

| 언어 | 표시 통화 |
|---|---|
| 영어 | 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** 카드에는 USD당 환율, 소스(Frankfurter) 및 마지막 업데이트 시간을 포함한 11개의 표시 통화가 나열됩니다. **Update exchange rates**를 클릭합니다.

   이 버튼은 한 번에 두 가지 작업을 수행합니다. **USD/VND**용 공개 시장 가격표를 읽어오고, 나머지 11개 환율을 읽어옵니다. 둘 중 하나라도 저장되기 전에 두 환율이 모두 검증됩니다. 하나라도 실패하면 아무것도 변경되지 않으며 기존 환율이 유지됩니다.


3. **Active exchange rate** 카드에는 현재 적용 중인 USD/VND 환율, 소스 태그(공개 시장 또는 고정), 마진, 시장 기준 수치와 해당 타임스탬프가 표시됩니다.
4. **Config** 카드 (사유와 함께 저장):

   | 필드 | 의미 | 범위 |
   |---|---|---|
   | 마진 (bp, 100 = 1 %) | 시장 기준 환율에 가산됩니다. 최종 적용 환율은 기준 환율에 마진을 더한 후 올림하여 계산됩니다. | 0 ~ 1000 |
   | 고정 환율(USD당 VND, 0 = 시장 환율 적용) | 직접 설정하는 환율입니다. 시장 수치를 대체합니다. | 0 또는 15,000 ~ 50,000 |
   | 변동 임계값 (bp) | 현재 환율과의 차이가 이 값을 초과하는 새로운 시장 환율은 직접 확인할 때까지 **보류**됩니다. | 50 ~ 2000 (기본값 500) |
   | VND 반올림 단위 | VND 가격 및 은행 송금 금액을 반올림합니다. | 1, 100, 1,000 (기본값) 또는 10,000 |

5. 새로운 시장 환율이 임계값 이상으로 급변하면 **Pending exchange rate** 카드가 나타나며 해당 환율은 **적용되지 않습니다**. 선택한 기준과 대조하여 확인한 후 **Apply this rate**을(를) 클릭하십시오.

   1 USD당 15,000~50,000 VND 범위를 벗어나는 시장 환율은 비정상적인 값으로 간주되어 거부됩니다. 수동 새로고침은 5분에 1회로 제한되므로 버튼에 대기 요청이 표시될 수 있습니다.

6. **Exchange rate history** 테이블에는 조회되거나 확정된 모든 환율의 시간, 적용 환율, 시장 기준 환율, 출처, 적용 여부, 작업자 및 메모(변동 폭이 커 보류된 환율은 **held**로 표시)가 나열됩니다.

## 환율 사용 방식 {#how-a-rate-is-used}

| 위치 | 규칙 |
|---|---|
| 지갑 및 인보이스 | USD 센트. 환율로 인해 잔액이 변경되지는 않습니다. |
| VND로 입력된 VM 플랜 | 저장 시점의 적용 환율로 **1회** 변환된 후 USD로 저장됩니다. 이후 환율이 변동되어도 해당 VM 플랜의 가격은 재조정되지 않습니다. |
| SePay를 통한 은행 송금 | 고객이 `ceil(USD × rate)`을(를) 지불하며, 반올림 단위로 올림 처리됩니다. USD/VND 환율이 존재할 때까지 SePay는 **차단**됩니다. |
| Bare Metal 플랜 | 신규 설치 환경에서는 USD를 직접 사용합니다. 기존 VND 플랜은 가격 단위를 유지하며 과금 시 환율이 필요합니다. [Dedicated servers](https://nexcmp.com/ko/docs/infrastructure/dedicated/)를 참조하십시오. |
| VND로 입력된 기타 국제 결제 | 가장 가까운 센트로 반올림됩니다. |
| 포털에 표시 | 표시 통화의 발행 환율을 곱한 USD로, 해당 언어 형식에 맞게 포맷됩니다. |

## 확인 {#verify}

1. **Active exchange rate**에 최근 "fetched" 시간과 함께 USD/VND 값이 표시됩니다.
2. **Currency by language** 그리드에 비어 있지 않은 환율이 표시됩니다.
3. 고객 포털에서 언어를 베트남어로 변경(사이트 통화 Auto)하면 가격이 동(VND)으로 표시되고, 일본어로 변경하면 엔(JPY)으로 표시됩니다. 사이트 통화가 USD인 경우 달러로만 표시됩니다.
4. 요금제 폼(Plans & pricing)의 **Enter price by** 목록에 **VND / month**가 제공됩니다.

## 제한 사항 및 참고 사항 {#limits-and-notes}

- 자동 새로 고침이 지원되지 않습니다. 새로운 환율이 필요할 때 **Update exchange rates**를 누르고, 환율이 중요한 경우 알림을 설정하세요.
- USD/VND에는 공개 시장 환율이 사용되며, 이는 은행 매매 기준율이 아닌 참고 환율입니다. 기타 표시 통화는 Frankfurter에서 가져오며, 14일 이상 경과한 데이터나 불완전한 환율 표는 거부됩니다.
- 마진과 고정 환율은 USD/VND에만 적용되며, 11개 표시 통화에는 마진이 적용되지 않습니다.
- 각 고객 언어는 하나의 통화를 가집니다. 고객이 동일 언어에 대해 USD를 선택하지 않은 경우, 언어를 변경하면 해당 언어의 기본 통화로 재설정됩니다.
- 리셀러 사이트도 동일한 환율을 따릅니다.

## Troubleshooting {#troubleshooting}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| "새로운 환율이 임계값을 벗어남 - 보류 중, 수동 확인 필요" | 변동 폭이 임계값보다 큽니다 | 확인 후 **Apply this rate**을 클릭하거나 임계값을 변경하세요. |
| "서버가 새 환율을 거부함" | 시장 환율이 15,000~50,000 범위를 벗어났거나 형식이 잘못됨 | 잠시 후 다시 시도하거나 고정 환율을 설정하세요. |
| 새로고침 시 다시 시도하기 전 대기하라는 메시지가 표시됨 | Too frequent updates | Wait and retry. |
| "환율을 가져올 수 없음: …" | 패널 서버가 환율 서비스에 연결할 수 없습니다 | 아웃바운드 HTTPS를 허용하고 다시 시도하세요. |
| **Sepay blocked** tag | 아직 게시된 USD/VND 환율이 없습니다 | **Update exchange rates**을 누르거나 고정 환율을 설정하세요. |
| 포털에서 통화가 누락됨 | 해당 환율이 누락되었습니다 | **Update exchange rates**을 누르세요. |
| 고객에게 가격이 USD로만 표시됨 | 사이트 통화가 USD이거나 환율이 누락되었습니다 | **Site currency**를 Auto로 설정하고 환율을 게시하십시오. |
| "Fx 불완전한 환율 테이블; 이전 환율 유지됨" | Frankfurter가 11개 미만의 통화를 반환했습니다 | 나중에 다시 시도하세요. 변경된 사항이 없습니다. |
| 요금제 양식에 VND 옵션이 누락됨 | No USD/VND rate | 먼저 환율을 게시하세요. |




---

<!-- source: https://nexcmp.com/ko/docs/billing/payment-channels/ -->

# 결제 채널 {#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://<domain>/v1/billing/...`(으)로 웹훅을 전송하므로, 패널은 유효한 TLS를 통해 인터넷에서 접근할 수 있어야 합니다([DNS and Cloudflare](https://nexcmp.com/ko/docs/getting-started/dns-and-cloudflare/) 참고). |
| 계정 | 사용하려는 각 제공업체의 자체 계정입니다. 자격 증명은 관리자 페이지에 입력되며 다시 표시되지 않고 마지막 4글자만 표시됩니다. |
| 관리자 역할 | 관리자 계정입니다. |
| 의존성 | 없음. VN 은행 채널에는 [환율](https://nexcmp.com/ko/docs/catalog/currency-and-exchange-rates/)이 추가로 필요합니다. |

## 지원 채널 {#the-channels}

| 채널 | 고객 화면 | 설정 위치 | 문서 |
|---|---|---|---|
| 카드 (Stripe) | 카드 양식, 저장된 카드 | Payment channels › Stripe | [Stripe](https://nexcmp.com/ko/docs/billing/stripe/) |
| Apple Pay, Google Pay, Link | 월렛 버튼 (Stripe Express Checkout) | Stripe 및 도메인 등록 | [Stripe](https://nexcmp.com/ko/docs/billing/stripe/#apple-pay-google-pay-and-link) |
| Alipay | Alipay로 리디렉션 (Stripe에서 JPY로 청구) | Stripe 및 Fees & limits | [Stripe](https://nexcmp.com/ko/docs/billing/stripe/#alipay) |
| PayPal | PayPal 버튼, 저장된 PayPal 계정 | Payment channels › PayPal | [PayPal](https://nexcmp.com/ko/docs/billing/paypal/) |
| USDT | 입금 주소 및 정확한 금액 | Payment channels › USDT | [USDT](https://nexcmp.com/ko/docs/billing/usdt/) |
| VN 은행 송금 | QR 코드 및 송금 세부 정보 (베트남어 인터페이스 전용) | Payment channels › VN bank transfer 메뉴 | [Bank transfer (Vietnam)](https://nexcmp.com/ko/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일 통계가 포함된 게이트웨이를 나열하는 Payment channels 개요](https://nexcmp.com/ko/docs/images/billing/payment-channels-01-overview.webp)

![채널 스위치와 수수료 필드가 있는 Fees and limits 페이지](https://nexcmp.com/ko/docs/images/billing/payment-channels-02-fees.webp)

### 스위치 및 수수료 (Fees & limits) {#switches-and-fees-fees-limits}

| 설정 | Default | 의미 |
|---|---|---|
| 카드 (Stripe) | On | 예치 화면의 카드 양식. Stripe 비밀 키가 설정될 때까지 숨겨집니다. |
| Apple Pay, Google Pay, Link | On | 월렛 버튼. Stripe에서 도메인이 인증된 경우에만 표시됩니다. |
| Alipay | 꺼짐 | Stripe 대시보드에서 Alipay가 활성화되어 있어야 합니다. |
| PayPal | 꺼짐 | PayPal이 설정된 경우에만 표시됩니다. |
| USDT (Binance) | 꺼짐 | Binance에서 입금 주소가 검증될 때까지 스위치가 잠깁니다. |
| Stripe 수수료 % / 고정 금액 (센트) | 3.6 % 및 0 | 고객에게 수수료를 표시하고 적립 금액을 계산하는 데 사용됩니다. 실제 Stripe 요율로 설정하세요. |
| PayPal 수수료 % / 고정 금액 | 4.4 % 및 30 센트 | PayPal용 동일 설정. |
| USDT 수수료 % | 1 % | USDT용 동일 설정. |
| 고객이 충전 수수료 부담 | 꺼짐 | **On**: 고객이 금액 + 수수료를 결제하고 지갑에는 전액이 충전됩니다. **Off**: 수수료가 차감된 후 남은 금액이 지갑에 충전됩니다. |

고객은 결제 전에 항상 수수료와 최종 지갑 크레딧을 확인합니다. 채널을 끄면 버튼이 숨겨지고 서버는 `method_disabled` (HTTP 403)과 함께 새로운 결제를 거부합니다.

::: tip 충전 한도
충전당 최소 및 최대 금액은 동일한 페이지에 있습니다 — [Minimum top-up](https://nexcmp.com/ko/docs/billing/minimum-top-up/)을 참고하세요.
:::

## 확인 {#verify}

1. 요약 표에서 해당 채널은 **Enabled** 및 **Configured**로 표시되며, **Test**을 클릭한 후 **Last 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/ko/docs/customers/resellers/)를 참조하세요.
- **환불:** Stripe 및 PayPal 결제는 결제 목록에서 환불할 수 있으며, USDT 결제는 원본으로 환불할 수 없습니다 (서버가 `usdt_no_refund`로 응답함).
- **유지보수 모드**에서도 게이트웨이 웹훅을 계속 수신하므로, 유지보수 직전에 이루어진 결제는 유실되지 않습니다.

## Troubleshooting {#troubleshooting}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| 고객의 입금 화면에 채널이 누락됨 | 꺼져 있음, 설정되지 않음, 또는 (베트남 은행) 인터페이스가 베트남어가 아님 | **Fees & limits** 및 채널 탭을 확인하세요; [Bank transfer (Vietnam)](https://nexcmp.com/ko/docs/billing/bank-transfer-vn/)을 참고하세요. |
| KPI **Faulty channels**가 0보다 큼 | 자격 증명 없이 채널이 활성화되었거나 24시간 이상 결제가 대기 중임 | 행을 열고 **Configure**를 클릭하세요. 지연된 결제의 경우 **Gateway events**를 열고 재전송하세요. |
| 고객은 결제했으나 잔액이 변경되지 않음 | 웹훅이 도착하지 않음 | 채널 탭에서 웹훅 URL을 확인한 후 **Gateway events**에서 이벤트를 다시 전송하세요. |
| 서버 응답 `method_disabled` | 스위치가 꺼져 있음 | **Fees & limits**에서 켜고 저장하세요. |
| USDT 스위치가 회색으로 비활성화됨 | 입금 주소가 확인되지 않음 | USDT 탭에서 **Test & verify address**를 클릭하세요. |


---

<!-- source: https://nexcmp.com/ko/docs/billing/stripe/ -->

# 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/ko/docs/billing/auto-top-up/)할 수 있도록 허용합니다. 해외 고객을 위한 기본 채널로 사용하세요.

## 요구 사항 {#requirements}

| 항목 | 요구 사항 |
|---|---|
| Stripe 계정 | **USD** 단위로 결제를 수락할 수 있는 Stripe 계정입니다. Alipay는 JPY로 청구되며 Stripe에서 계정에 활성화해야 합니다. |
| 키 | 시크릿 키(`sk_live_...` 또는 `sk_test_...`)와 퍼블리시드 키(`pk_live_...` 또는 `pk_test_...`)입니다. 양식에서는 이러한 접두사가 있는 키만 허용됩니다. |
| 네트워크 | 패널이 인터넷을 통해 HTTPS로 접근 가능해야 하며(Stripe가 웹훅을 호출함), 포트 443에서 `api.stripe.com`에 도달할 수 있어야 합니다. |
| 도메인(지갑 전용) | 고객용 도메인은 `/.well-known/apple-developer-merchantid-domain-association`을(를) 지원해야 하며, NexCMP가 이를 자동으로 처리합니다. |
| 의존성 | 없음. |

::: info 공유 Stripe 계정
NexCMP는 자체적으로 생성한 결제에 대한 웹훅 이벤트만 처리하므로, 다른 애플리케이션에서도 사용하는 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. 수동으로 웹훅을 만들 필요는 **없습니다**. NexCMP가 자동으로 생성해 줄 수 있습니다(아래 5단계 참조). 수동으로 하려면 **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, 청구 활성화 여부, 웹훅 존재 여부, Alipay 사용 가능 여부가 보고됩니다. 빨간색 선은 해당 부분에 주의가 필요함을 의미합니다.
5. **Webhook** 카드에서 **Create webhook**을 클릭하고 확인합니다. NexCMP가 Stripe에 필요한 모든 이벤트가 포함된 엔드포인트 생성을 요청하고 **Webhook signing secret**(`whsec_...`)을 자동으로 채웁니다. 필드에 미리 채워진 URL은 `https://<your-domain>/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/ko/docs/billing/payment-channels/#switches-and-fees-fees-limits)를 참조하세요.

![모드, 시크릿 키, 퍼블리시드 키가 예시 값으로 채워진 Stripe 페이지](https://nexcmp.com/ko/docs/images/billing/stripe-01-keys.webp)


### 웹훅 {#webhook}

"Missing webhook_secret" 빨간색 배너는 서명 비밀이 저장될 때까지 유지됩니다. 이 비밀이 없으면 Stripe에서 돈을 가져갔더라도 Stripe 충전이 **기록되지 않습니다**.

| 항목 | 값 |
|---|---|
| URL | `https://<your-domain>/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**을 다시 클릭하세요. 기존 엔드포인트는 유지되므로 나중에 Stripe Dashboard에서 수동으로 삭제해야 합니다.

Webhook 카드의 **24h events** 및 **Latest event** 행은 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가 Stripe의 결제 수단 도메인에 해당 도메인을 등록하고 Stripe에 검증을 요청합니다.
3. 결과 창에 **Apple Pay**, **Google Pay**, **Link**의 상태가 표시됩니다. Apple Pay는 상태가 `active`일 때만 표시됩니다.
4. **Fees & limits**에서 **Apple Pay · Google Pay · Link**를 켭니다.

![등록된 도메인과 Apple Pay, Google Pay, Link 상태를 보여주는 지갑 카드](https://nexcmp.com/ko/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 rate를 정기적으로 업데이트하십시오. 7일보다 오래되면 페이지에 경고가 표시됩니다.

## 확인 {#verify}

1. 테스트 모드에서 테스트 고객으로 포털에 로그인하고, **Billing**을 열고 **Deposit**을 클릭한 뒤 **Card**를 선택하고 Stripe 테스트 카드`4242 4242 4242 4242`(임의의 미래 날짜, 임의의 CVC)로 최소 금액을 결제하세요.
2. 잔액은 몇 초 안에 충전되며 결제 내역은 상태가 *Completed*로 표시된 채 **Finance › Billing › Top-ups**에 나타납니다.
3. **Payment channels › Gateway events › Stripe**을 엽니다. 처리 시간과 함께 `checkout.session.completed` 또는 `payment_intent.succeeded`가 표시되어야 합니다.
4. Stripe 페이지로 돌아가면 **24h events**가 0보다 큽니다.

라이브로 전환하기 전에 **Mode**를 `live`(으)로 전환하고 라이브 키를 붙여넣은 뒤 다시 **Create webhook**을 클릭하세요(테스트 모드와 라이브 모드의 웹훅은 별개입니다).

## 한도 및 참고 사항 {#limits-notes}

- **금액 및 통화:** 지갑 통화는 USD입니다. 카드, 지갑 및 링크 결제는 USD로 청구되며, Alipay는 고객에게 JPY로 표시되고 설정된 환율로 환산됩니다.
- **수수료:** Stripe의 실제 수수료는 자동으로 다시 읽어오지 않으며, 설정한 수수료율에 따라 고객에게 표시되는 금액과 지갑에 적립되는 금액이 결정됩니다. 수수료를 추가로 청구하려면 *Fees & limits*에서 **Customer pays top-up fee**를 선택하세요.
- **저장된 카드:** 고객이 *Save card for auto top-up*을 체크하면 카드가 내 서버가 아니라 Stripe에 저장됩니다. [Saved payment methods](https://nexcmp.com/ko/docs/billing/saved-payment-methods/)를 참고하세요.
- **환불:** 카드로 환불하는 과정은 2단계로 이루어집니다. 관리자가 완료된 결제에 대해 환불 요청을 생성하고(**Finance › Billing › Top-ups**에서 해당 결제의 환불 작업 실행) **Finance › Payouts › Card refunds**(`/billing/payouts`)에서 이를 승인합니다. Alipay 환불은 비동기식이며, 실패한 환불(`refund.failed`)은 보류된 금액을 지갑으로 돌려줍니다.
- **분쟁:** `charge.dispute.created` NexCMP에서는 고객의 계정을 차단하고 선불 서비스를 중지하며(삭제되는 것은 없음) 관리자 알림을 보냅니다. 분쟁에서 승소한 경우(`charge.dispute.closed`), 해당 금액이 지갑으로 다시 적립됩니다.
- **대기 중인 결제:** 웹훅이 도착하지 않는 경우, NexCMP는 10분 이상 대기 상태로 유지된 결제를 Stripe와 자체적으로 대조하여 완료 처리합니다. 7일이 지난 결제는 무시됩니다.
- **Resellers**는 자신의 Stripe 계정(웹훅 `https://<their-domain>/v1/billing/stripe/webhook/r/<id>`)을 연결할 수 있습니다. [Resellers](https://nexcmp.com/ko/docs/customers/resellers/)를 참고하세요.

## Troubleshooting {#troubleshooting}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| "Secret key는 sk_live_/sk_test_로 시작해야 합니다" | 잘못된 키가 붙여넣어짐 | **Developers › API keys**에서 시크릿 키를 복사하여 붙여넣으세요. |
| "Secret key가 라이브/테스트 모드와 일치하지 않습니다" | 모드와 키가 일치하지 않음 | **Mode**이(가) 키의 접두사와 일치하도록 만드세요. |
| "Publishable key는 pk_로 시작해야 합니다" | Wrong key | 공개 키를 사용하세요. |
| 연결에 실패했습니다 | 잘못된 키, 폐기된 키 또는 서버가 `api.stripe.com`에 도달할 수 없음 | 키를 다시 붙여넣고 서버에서 `curl -I https://api.stripe.com`(으)로 테스트하세요. |
| 빨간색 배너 "Missing webhook_secret" | 서명 비밀키가 저장되지 않음 | **Create webhook**을(를) 클릭하거나 Stripe 대시보드에서 `whsec_...` 비밀키를 붙여넣은 후 **Save**을(를) 클릭하세요. |
| 금액은 출금되었으나 잔액이 변경되지 않음 | 웹훅이 전달되지 않았거나 서명 검증에 실패함 | URL이 `/v1/billing/stripe/webhook`(으)로 끝나고, 비밀키가 엔드포인트와 일치하는지 확인한 후 **Gateway events**에서 이벤트를 다시 재생하세요. Stripe에서 엔드포인트를 열고 전송 시도 내역을 확인하세요(HTTP 400은 서명 비밀키가 잘못되었음을 의미합니다). |
| "Create webhook" fails | URL이 HTTPS가 아니거나 접근할 수 없음 | 공개 `https://` 도메인을 사용하세요. |
| Apple Pay 상태가 활성화되지 않음 | Domain not validated | 도메인 연결 파일이 200 응답을 반환한 후 **Register / verify domain**을(를) 다시 클릭하세요. |
| 확인 대화상자에 Alipay가 표시되지 않음 | Not activated at Stripe | Stripe 대시보드에서 활성화한 후 **Check**을(를) 클릭하세요. |
| 고객에게 카드 양식이 표시되지 않음 | **Card (Stripe)**이(가) 꺼져 있거나 비밀키가 없음 | **Fees & limits**에서 켜고 키를 저장하세요. |


---

<!-- source: https://nexcmp.com/ko/docs/billing/paypal/ -->

# PayPal

> **관리자 페이지 위치:** Finance › Payment channels › PayPal (`/payments/paypal`). 켜기/끄기 스위치와 수수료는 Finance › Payment channels › Fees & limits (`/payments/fees`)에 있습니다.

## 작동 내용 {#what-it-does}

고객이 PayPal 잔액, 은행 계좌 또는 PayPal에 등록된 카드로 USD 지갑을 충전할 수 있습니다. 또한 고객은 NexCMP가 [automatic top-up](https://nexcmp.com/ko/docs/billing/auto-top-up/)을 위해 PayPal 계정을 기억하도록 설정할 수 있습니다. PayPal을 선호하는 고객을 위해 [Stripe](https://nexcmp.com/ko/docs/billing/stripe/)와 함께 사용하세요.

## 요구 사항 {#requirements}

| 항목 | 요구 사항 |
|---|---|
| PayPal account | USD를 받을 수 있는 PayPal **비즈니스** 계정 |
| REST app | PayPal Developer Dashboard(**Apps & Credentials**)의 **Client ID** 및 **Client secret**을 제공하는 하나의 REST 앱. 테스트용으로는 **Sandbox** 탭을, 프로덕션용으로는 **Live** 탭을 사용하세요. |
| 네트워크 | 인터넷에서 접근 가능한 HTTPS(PayPal이 웹훅을 호출함) 및 `api-m.paypal.com`(라이브) 또는 `api-m.sandbox.paypal.com`(샌드박스) 포트 443에 대한 아웃바운드 접근. |
| Permissions | REST 앱에는 환불 및 웹훅 기능이 필요합니다. **Check** 대화상자에서 두 범위가 모두 있는지 확인할 수 있습니다. |
| 의존성 | 없음. |

## 인프라 준비 {#prepare-the-infrastructure}

1. 비즈니스 계정으로 [developer.paypal.com](https://developer.paypal.com)에 로그인한 후 **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**를 클릭합니다. 입력한 자격 증명을 테스트하고(저장 불필요) 연결 상태, 앱 ID, 모드, 환불 및 웹훅 스코프 포함 여부, 토큰 수명 주기를 보고합니다.
5. **Save**를 클릭합니다.
6. **Webhook** 카드에서 URL이 `https://<your-domain>/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 페이지](https://nexcmp.com/ko/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`.

각 웹훅은 PayPal의 서명 검증 API를 호출하여 검증되며, 한 번 저장되고 멱등성 있게 처리됩니다. NexCMP는 웹훅 본문의 금액을 절대 신뢰하지 않으며, 결제를 승인하기 전에 PayPal에서 결제 건을 가져옵니다.

## 확인 {#verify}

1. **Mode**를 `sandbox` 상태로 유지합니다. 포털에서 **Billing › Deposit**을 열고 **PayPal**을 선택한 다음, **Continue on PayPal**(또는 PayPal 버튼)을 클릭하고 샌드박스 구매자 계정으로 로그인합니다.
2. 결제를 승인합니다. 포털로 돌아오면 잔액이 증가하고 **Finance › Billing › Top-ups**에 결제가 *Completed* 상태로 표시됩니다.
3. **Payment channels › Gateway events › PayPal & USDT**를 엽니다. `PAYMENT.CAPTURE.COMPLETED` 이벤트가 목록에 표시됩니다.
4. 모든 것이 정상 작동하면 **Mode**를 `live`로 전환하고 라이브 자격 증명을 입력한 후 **Save**를 누르고, **Create webhook**을 다시 클릭합니다(샌드박스 웹훅과 라이브 웹훅은 별개입니다).

## 한도 및 참고 사항 {#limits-notes}

- **결제 완료 방식.** 주문은 USD로 생성되며, 고객이 승인한 후 **서버**가 이를 캡처하고(멱등성 요청 ID) 지갑에 정확히 한 번 적립합니다. 고객이 브라우저를 닫는 경우에 대비해 웹훅과 10분마다 실행되는 대조 작업이 안전망 역할을 합니다.
- **보류 및 중단된 주문.** 주문은 12시간 동안 열려 있을 수 있습니다. 고객은 최대 5개의 보류 중인 주문을 가질 수 있습니다(서버는 `too_many_pending`, HTTP 429로 응답). 24시간이 지나도 캡처되지 않은 주문은 실패로 표시됩니다.
- **웹훅이 설정되지 않은 경우.** Webhook ID가 저장될 때까지 패널은 모든 PayPal 웹훅에 HTTP 503으로 응답합니다. 포털을 통한 결제와 10분 주기의 대조 작업은 여전히 지갑에 적립되지만, PayPal이 웹훅으로 보고하는 내용(분쟁, 취소, 지연 결제)은 적용되지 않습니다. **Create webhook**을 클릭하세요.
- **저장된 PayPal 계정.** 고객이 PayPal 저장을 선택하거나(또는 [automatic top-up](https://nexcmp.com/ko/docs/billing/auto-top-up/)을 활성화하는 첫 번째 예치금을 완료하면) PayPal은 결제 토큰을 볼트에 저장합니다. NexCMP는 식별자와 PayPal 이메일만 보관합니다. [Saved payment methods](https://nexcmp.com/ko/docs/billing/saved-payment-methods/)를 참조하세요.
- **환불 및 분쟁**은 Stripe와 동일하게 처리됩니다. 환불 요청은 **Finance › Payouts › Card refunds**에서 승인하며, 분쟁이 발생하면 고객 계정이 차단되고 문제를 해결할 때까지 선불 서비스가 중지됩니다.
- **수수료.** PayPal의 수수료는 자동으로 불러오지 않으며, 설정한 백분율과 고정 수수료에 따라 고객에게 표시되는 금액과 적립되는 금액이 결정됩니다. 실제 요율은 국가에 따라 다릅니다(양식에는 베트남의 경우 4.4%, 미국의 경우 3.49%로 안내됨).

## Troubleshooting {#troubleshooting}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| "Client ID가 너무 짧습니다" | 20자 미만이 붙여넣어짐 | 전체 Client ID를 복사합니다. |
| "Webhook URL은 반드시 https여야 합니다" | URL이 `http://`로 입력됨 | 공개 `https://` 도메인을 사용하세요. |
| 확인에서 연결 오류 보고됨 | 잘못된 모드(샌드박스에서의 라이브 키 또는 그 반대), 잘못된 시크릿, 아웃바운드 액세스 없음 | **Mode**을 키 유형에 맞추고, 서버에서 `curl -I https://api-m.paypal.com`을(를) 테스트합니다. |
| 환불 / 웹훅 범위에 "no"가 표시됨 | REST 앱에 기능이 부족함 | PayPal Developer Dashboard의 앱에서 기능을 활성화하세요. |
| 배너 "PayPal key set, NO webhook" | 웹훅 ID 누락 | **Create webhook**을 클릭하세요. |
| 확인에 "Webhook not found" 표시됨 | 웹훅이 PayPal에서 삭제되었거나 다른 앱에 속해 있음 | **Create webhook**을 다시 클릭하세요. |
| 고객에게 PayPal이 결제를 거절했다고 안내됨 | PayPal이 해당 자금 출처를 거부함 | 고객에게 다른 결제 수단을 선택하도록 요청하세요. |
| 고객에게 "Too many pending requests"가 표시됨 | 5개의 미결제 주문 | 만료될 때까지 기다리거나 완료 처리하세요. |
| PayPal 버튼이 누락됨 | **Fees & limits**에서 PayPal이 꺼져 있거나 설정되지 않음 | 켜고 자격 증명을 저장하세요. |


---

<!-- source: https://nexcmp.com/ko/docs/billing/usdt/ -->

# 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를 송금하면, NexCMP는 **읽기 전용** 바이낸스 API 키를 통해 입금 내역을 읽고 미결제 요청과 입금이 일치할 때 지갑을 충전합니다. 바이낸스에서 부과하는 수수료 외에는 결제 처리 수수료가 없으며, NexCMP는 어떠한 개인키도 보유하지 않습니다.

## 요구 사항 {#requirements}

| 항목 | 요구 사항 |
|---|---|
| 바이낸스 계정 | 선택한 네트워크에서 USDT 입금이 활성화된 인증된 바이낸스 계정. |
| API 키 | **Enable Reading** 페이지만 허용된 바이낸스 API 키. Enable Withdrawals, Internal Transfer, Spot/Margin Trading은 반드시 **꺼져** 있어야 합니다. |
| IP 제한 | 강력히 권장됨: 키를 서버의 아웃바운드 IP로 제한하세요(**Test & verify address** 대화상자에 표시됨). |
| 네트워크 | `api.binance.com`(으)로의 아웃바운드 HTTPS. 인바운드 포트는 필요하지 않습니다. |
| 지원되는 네트워크 | `TRX`(Tron, TRC20), `BSC`(BNB Smart Chain, BEP20), `SOL`(Solana), `ETH`(Ethereum, ERC20). 코인은 USDT로 고정되어 있습니다. |
| 의존성 | 없음. |

::: warning 네트워크를 한 번만 선택하세요
잘못된 네트워크로 송금한 고객은 자금을 잃게 됩니다. 고객의 거래소가 지원하는 수수료가 낮은 네트워크를 선택하고(TRX와 BSC가 일반적인 선택임), 자주 변경하지 마세요.
:::

## 인프라 준비 {#prepare-the-infrastructure}

1. 바이낸스에서 **Account › API Management**을 열고 새 API 키를 생성합니다(시스템 생성). "NexCMP"와 같은 레이블을 지정하세요.
2. 권한을 편집합니다: **Enable Reading**만 체크된 상태로 둡니다. 출금, 이체 또는 거래를 활성화하지 마세요.
3. **Restrict access to trusted IPs only** 아래에 NexCMP 서버의 공인 IP 주소를 추가합니다. 아직 모르는 경우 제한 없이 키를 생성하고 NexCMP에서 첫 번째 테스트를 실행한 후(아웃바운드 IP가 출력됨) IP를 추가하세요.
4. **API key** 및 **Secret key**를 복사합니다(시크릿은 한 번만 표시됨).
5. **Wallet › Deposit › Crypto**를 열고 **USDT** 및 사용할 **네트워크**를 선택한 다음 **입금 주소**를 복사합니다(예: TRX의 `T...` 주소 또는 BSC/ETH의 `0x...`).

## 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 입금 주소**를 붙여넣습니다. 형식은 네트워크에 대해 검증됩니다(TRX의 경우 `T` + 33자, BSC 및 ETH의 경우 `0x` + 40 1진수 문자, SOL의 경우 base58).
4. **Save**를 클릭합니다. 주소나 네트워크를 변경하면 검증이 초기화되며 다시 검증할 때까지 채널이 일시 중지됩니다. 페이지에서 확인을 요청합니다.
5. **Test & verify address**를 클릭합니다. (저장되지 않은 변경 사항은 거부되며, 검증은 저장된 구성을 기준으로 실행됩니다.) 대화상자에 다음 정보가 표시됩니다.
   - 키 권한(읽기, 출금, 내부 이체, 거래, IP 제한) — 위험한 권한에 대한 빨간색 경고;
   - 서버의 아웃바운드 IP(바이낸스에 입력할 값);
   - 네트워크(입금 열림 또는 닫힘, 필수 승인 수, 먼지(dust));
   - 해당 네트워크에 대해 바이낸스가 발행한 주소 및 사용자의 주소와 **일치**하는지 여부.
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는 지난 24시간 동안의 바이낸스 입금을 읽습니다. 일치하는 입금은 요청을 *confirming*으로 이동시키며, 바이낸스에 필요한 승인이 완료되면 지갑에 크레딧이 적립됩니다. 자금이 확인된 요청은 승인이 대기되는 동안 절대 만료되지 않습니다.
5. 만료 시간(기본값 30분) 내에 지불되지 않은 요청은 만료됨으로 표시됩니다.

## 확인 {#verify}

1. 주소가 검증되고 USDT가 켜진 후 테스트 고객으로 로그인하여 소액 입금(최소 충전 금액)을 요청합니다.
2. 다른 지갑이나 거래소에서 정확한 금액을 전송합니다. 몇 분 정도 기다려 주세요.
3. 포털에 *Transfer seen — confirming*이 표시된 다음 *USDT received — balance updated*가 표시됩니다.
4. USDT 페이지에 최근 **Last poll** 시간과 0인 **Unmatched**가 표시됩니다.

## 한도 및 참고 사항 {#limits-notes}

- **Rate.** 1 USDT = 1.00 USD. **USDT fee %**의 수수료는 고객에게 표시되며 **Customer pays top-up fee**에 따라 금액에서 차감되거나 추가됩니다.
- **No refunds.** NexCMP는 USDT 결제를 소스 계정에 환불하지 않습니다(HTTP 409 `usdt_no_refund`). 필요한 경우 시스템 외부에서 수동으로 환불하세요.
- **Pending limit.** 고객은 제한된 수의 오픈 요청을 가질 수 있으며, 이를 초과하면 서버가 `too_many_pending`(HTTP 429)으로 응답합니다.
- **Resellers**는 자신만의 바이낸스 계정을 사용할 수 있습니다. [Resellers](https://nexcmp.com/ko/docs/customers/resellers/)를 참조하세요.
- **Binance 계정을 다른 시스템과 공유하는 경우**, 두 폴러(poller)가 절대 동일한 입금을 동시에 조회하지 않도록 각 시스템에 서로 다른 네트워크를 할당하세요.

### 일치하지 않는 입금 {#unmatched-deposits}

요청과 일치하지 않는 입금(잘못된 금액, 잘못된 네트워크, 만료된 요청)은 `deposit.unmatched` 이벤트 및 관리자 알림을 생성합니다. **Payment channels › Gateway events › PayPal & USDT**를 열고, 이벤트를 찾아 Binance에서 트랜잭션을 확인한 후 할당 작업을 클릭하여 올바른 고객에게 크레딧을 부여하세요. 그 후 USDT 페이지 및 채널 개요의 **Unmatched** 카운터가 0으로 떨어집니다.

## Troubleshooting {#troubleshooting}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| "API key와 secret은 함께 입력해야 합니다" | 하나의 필드만 입력됨 | 둘 다 입력하세요. |
| "주소가 네트워크 형식...이 아닙니다" | 주소가 선택한 네트워크와 일치하지 않음 | Binance에서 동일한 네트워크로 다시 복사하세요. |
| "저장되지 않은 변경 사항 — 먼저 저장한 후 테스트하세요" | 저장된 설정으로 테스트가 실행됨 | **Save**를 클릭한 후 테스트하세요. |
| 경고 "키에 출금 허용(Enable Withdrawals)이 설정되어 있음" | 초과된 권한 | Binance API 관리에서 제거하세요. |
| 경고 "키가 IP로 제한되지 않음" | `ipRestrict`이(가) 꺼져 있음 | 대화상자에 표시된 서버의 아웃바운드 IP를 추가하세요. |
| 경고 "키에 읽기 허용(Enable Reading)이 없음" | 권한 누락 | Enable Reading을 활성화하세요. |
| 경고 "Binance에서 해당 네트워크의 USDT 입금이 비활성화되어 있음" | 네트워크 일시 중단됨 | 다른 네트워크를 선택하거나 대기하세요. |
| "위험: 설정된 주소가 Binance가 발급한 주소와 다릅니다" | 잘못된 주소 또는 네트워크 | Binance에서 해당 네트워크의 주소를 다시 복사하세요. |
| Fees & limits에서 USDT 스위치가 비활성화됨 | 주소가 확인되지 않음 | 일치할 때까지 **Test & verify address**를 실행하세요. |
| 고객이 결제했으나 크레딧이 충전되지 않음 | 반올림된 금액 또는 잘못된 네트워크 | Gateway events에서 이벤트를 찾아 수동으로 할당하세요. |
| 입금은 확인되었으나 오랜 시간 대기 중 | 아직 충분한 컨펌이 이루어지지 않음 | 기다려 주세요. 컨펌 중에는 요청이 만료되지 않습니다. |


---

<!-- source: https://nexcmp.com/ko/docs/billing/bank-transfer-vn/ -->

# 은행 송금 (베트남) {#bank-transfer-vietnam}

> **관리자 메뉴 위치:** Finance › Payment channels › VN bank transfer (`/payments/bank`). 환율: Finance › Payment channels › Exchange rates (`/payments/fx`).

## 작동 내용 {#what-it-does}

고객이 베트남 동으로 일반 은행 송금을 통해 USD 지갑을 충전할 수 있도록 합니다. NexCMP는 VietQR 코드, 계좌 정보 및 고유한 **송금 메모**를 표시하며, [Sepay](https://sepay.vn)는 은행 계좌를 모니터링하다가 입금이 완료되면 웹훅을 호출하여 NexCMP가 지갑에 크레딧을 부여합니다. 베트남 고객을 대상으로 판매하는 경우에 사용하세요.

::: info 베트남어 인터페이스에서만 표시됨
VN 은행 옵션은 포털이 **Vietnamese**로 표시될 때만 고객에게 제공됩니다. 다른 언어를 사용하는 고객은 이를 볼 수 없습니다.
:::

## 요구 사항 {#requirements}

| 항목 | 요구 사항 |
|---|---|
| 은행 계좌 | [my.sepay.vn](https://my.sepay.vn)의 Sepay 계정과 연결된 베트남 은행 계좌(또는 Sepay 가상 계좌, **VA**). |
| Sepay | 웹훅 연동이 활성화된 Sepay 계정. |
| 환율 | USD 대비 VND 환율이 반드시 존재해야 합니다. 먼저 **Exchange rates**에서 환율을 업데이트하세요. 환율이 없으면 채널은 `fx_unavailable`를 반환하며 고객이 송금을 시작할 수 없습니다. |
| 네트워크 | Sepay가 `https://<your-domain>/v1/billing/sepay/webhook`을(를) 호출할 수 있도록 패널에 HTTPS로 접속할 수 있어야 합니다. |
| 의존성 | [통화 및 환율](https://nexcmp.com/ko/docs/catalog/currency-and-exchange-rates/). |

## 인프라 준비 {#prepare-the-infrastructure}

Sepay 쪽 설정:

1. [my.sepay.vn](https://my.sepay.vn)에서 은행 계좌를 연결하거나(또는 VA 생성) 거래 내역이 정상적으로 표시되는지 확인합니다.
2. **메모 접두사(memo prefix)**를 결정합니다. 2~5자의 대문자이며, 예: `PAY`. NexCMP는 접두사 뒤에 8자의 무작위 숫자를 붙여 메모를 생성합니다(예: `PAY48210937`). 접두사는 `ORD`을(를) 포함해서는 안 되며, 동일한 계좌로 입금을 받는 다른 시스템에서 사용 중이 아니어야 합니다.
3. Sepay 계정이 *결제 코드 구조(payment code structure)*를 사용하는 경우, 해당 위치에도 동일한 접두사를 등록하여 Sepay가 메모를 인식할 수 있도록 합니다.
4. 웹훅은 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자)을 입력합니다. 선택 사항으로 Sepay의 **userapi token**을 입력할 수 있으며, 이는 웹훅이 누락된 송금을 대사(reconcile)하는 용도로만 사용됩니다.
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. `https://<your-domain>/v1/billing/sepay/webhook` 형식으로 표시되는 **Webhook URL to paste into my.sepay.vn**을 **Copy**로 복사합니다. Sepay에서 웹후크 연동을 열고, URL을 붙여넣은 뒤 동일한 인증 유형과 키를 선택하고 "money in" 이벤트를 활성화합니다.
8. **Test connection**을 클릭합니다. 그런 다음 **Enable Sepay for clients (main site)**를 켜고 **Save**를 클릭하세요.

![예시 값이 입력된 수취 계좌, 메모 접두사, 웹훅 인증이 포함된 VN bank transfer 페이지](https://nexcmp.com/ko/docs/images/billing/bank-transfer-vn-01-config.webp)

![Sepay 스위치가 켜져 있고 기본 한도가 설정된 Channel and limits 카드](https://nexcmp.com/ko/docs/images/billing/bank-transfer-vn-02-limits.webp)

### 웹훅 보안 {#webhook-security}

| 방식 | Sepay 전송 항목 |
|---|---|
| HMAC-SHA256 | `X-SePay-Signature: sha256=<hex>` 헤더, `"<X-SePay-Timestamp>.<raw body>"` 기준 계산됨. 타임스탬프는 최대 300초까지 차이가 날 수 있습니다. |
| API 키 | `Authorization: Apikey <key>` 헤더. |

헤더만 검사하며(본문이나 쿼리 문자열은 절대 검사하지 않음) 비교는 일정한 시간이 소요되는 방식으로 수행됩니다. 설정된 계정이나 VA로 들어오는 입금(`transferType = in`)만 사용됩니다. 각 Sepay 거래는 한 번만 저장되므로 재시도된 웹훅으로 인해 금액이 두 번 적립되지 않습니다. NexCMP는 거래를 고의로 무시하는 경우에도 `200 {"success":true}`로 응답하며, Sepay가 재시도할 수 있도록 일시적인 오류에 대해서만 HTTP 5xx를 반환합니다.

## 고객 결제 방식 {#how-the-customer-pays}

1. **Billing › Deposit**(베트남어 인터페이스)에서 고객이 VN 계좌 이체 옵션과 금액을 선택한 후 이체 생성 버튼을 클릭합니다.
2. NexCMP는 저장된 환율(**Exchange rates**에서 설정한 마진 및 반올림 단계 포함)로 USD 금액을 변환하고, VND 금액을 반올림 단계에 맞춰 **올림 처리**합니다.
3. 고객은 계좌 번호, 은행, 금액, 메모가 포함된 QR 코드(VietQR, 로컬 생성)를 보게 됩니다.
4. 이체 완료 후 Sepay가 웹훅을 호출하면 NexCMP가 `floor(VND received × 100 / rate)` 센트를 적립합니다. 환율은 주문 생성 시점에 고정되며, 주문 만료 후 자금이 도착한 경우 고정 환율과 현재 환율 중 더 높은 환율이 적용됩니다.
5. 주문은 **Order expiry** 후에 만료되며, 안전장치로 **Reconcile every**분마다 대사 작업이 실행됩니다(userapi 토큰 필요).

## 확인 {#verify}

1. 베트남어 인터페이스에서 고객으로서 테스트 주문을 생성합니다. 금액, 계좌, 메모가 올바른지 확인합니다.
2. 허용된 최소 금액을 정확한 메모와 함께 이체합니다.
3. 1분 내에 포털에 예치가 완료된 것으로 표시되고 지갑 잔액이 증가하며, 은행 페이지의 **State** 카드에 마지막 웹훅 시간이 표시됩니다.
4. **Finance › Billing › Top-ups**를 열고 결제가 수신된 VND 금액과 함께 나열되어 있는지 확인합니다.

## 한도 및 참고 사항 {#limits-notes}

- **최소금액.** 고객에게 표시되는 VND 최소금액은 **Min / order**와 [minimum top-up](https://nexcmp.com/ko/docs/billing/minimum-top-up/)의 VND 가치 중 더 큰 값입니다.
- **대기 중인 주문.** 고객은 오픈 상태의 주문을 **Max pending orders / account**개(기본값 3개)까지만 가질 수 있습니다.
- **동일한 메모 중복 사용.** 동일한 메모로 두 번 이체하면 현재 환율로 두 번째 완료된 결제가 생성됩니다.
- 은행 계좌로의 **자동 환불은 지원되지 않습니다**.
- **수수료.** 해당 채널에는 **Fees & limits**에 고정 수수료 항목이 없으며, 환율 마진이 유일한 조정 요소입니다.
- **Resellers**는 자신의 계정을 설정할 수 있으며, 해당 웹훅 URL은 `/v1/billing/sepay/webhook/r/<id>`로 끝납니다.

### 일치하지 않는 이체 {#unmatched-transfers}

계정에 도달했으나 유효한 메모가 없는 자금은 페이지 하단의 **Unmatched transactions**에 표시됩니다(*All channel owners* 또는 *Master* 필터 사용). 고객과 함께 은행 참조 번호를 확인한 후 **Assign**을 클릭하고 계정을 선택합니다. 지갑에는 현재 환율이 적용되어 적립됩니다.

## Troubleshooting {#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` | 접두사가 유효하지 않음 | `ORD` 없이 2~5자의 대문자를 사용하세요. |
| `account_name` 오류 | 악센트 부호 또는 소문자 포함 | 악센트가 없는 대문자, 숫자, 공백, 점 또는 하이픈을 사용하세요. |
| `webhook_secret: 8–200 characters` | 키가 너무 짧음 | 인쇄 가능한 문자를 8자 이상 사용하세요. |
| 고객에게 옵션이 표시되지 않음 | 베트남어 인터페이스가 아니거나, 스위치가 꺼져 있거나, 환율이 없음 | 언어, 스위치, 환율을 확인하세요. |
| 고객은 결제했으나 크레딧이 충전되지 않음 | 웹훅이 도착하지 않았거나, 메모가 변경되었거나, 금액이 잘못됨 | Sepay의 웹훅 로그를 확인하세요. 메모가 잘못된 경우 이체 내역은 **Unmatched transactions**에 표시됩니다. |
| 웹훅이 401 또는 403을 반환함 | 인증 방식 또는 키가 일치하지 않음 | Sepay와 NexCMP에서 동일한 방식과 키를 사용하세요. |
| 고객에게 "Too many pending requests"가 표시됨 | 대기 중인 주문 한도에 도달함 | 완료되거나 만료될 때까지 기다립니다. |




---

<!-- source: https://nexcmp.com/ko/docs/billing/minimum-top-up/ -->

# 최소 충전 {#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**을 클릭합니다.

![최소 충전 10.00 및 최대 5000.00이 설정된 지갑 및 충전 카드](https://nexcmp.com/ko/docs/images/billing/minimum-top-up-01-limits.webp)

| 설정 | Default | 허용 범위 | 규칙 |
|---|---|---|---|
| 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 은행 송금 | VND 금액은 SePay 한도 내에 있어야 **하며** 해당 USD 환산 가치(지갑에 입금되는 금액)는 최소 및 최대 범위 내여야 합니다. 포털에는 두 VND 최소값 중 더 큰 금액이 표시됩니다. [Bank transfer (Vietnam)](https://nexcmp.com/ko/docs/billing/bank-transfer-vn/)을 참고하십시오. |
| [자동 충전](https://nexcmp.com/ko/docs/billing/auto-top-up/) | 모든 자동 청구 금액은 최소값 이상, 최대값 이하입니다. 고정 모드에서는 고객의 금액이 최소값과 $1,000 사이여야 합니다. |
| 충전 코드 ([Vouchers](https://nexcmp.com/ko/docs/billing/promotions/)) | 영향받지 않음. |
| 관리자 크레딧 / 차감 | 영향받지 않음. |
| 리셀러 지갑 충전 | Resellers › Defaults에 별도의 최소 금액(`rs_topup_min_cents`, 기본값 $20)이 적용됩니다. |

## 관련 하한선 {#related-floors}

최소 충전이 유일한 잔액 규칙은 아닙니다. 다음 항목은 **Services › Virtual Machines › Policy** (`/vm/policy`)에 있습니다.

| 규칙 | Default | 의미 |
|---|---|---|
| 최소 잔액 (`min_balance_cents`) | $5.00 | 고객이 VM을 생성하는 데 필요한 최소 지갑 잔액. |
| 할당량 | 꺼짐 | **Quotas** 기능이 켜져 있는 경우, VM을 생성하려면 해당 VM의 일정 시간 동안의 사용 요금을 충당할 수 있는 잔액도 필요합니다. [Quotas](https://nexcmp.com/ko/docs/billing/quotas/) 문서를 참고하세요. |

## 확인 {#verify}

1. 포털에서 **Billing › Deposit**으로 이동하여 최소금액 바로 아래의 금액을 입력합니다. 결제 버튼이 비활성화되고 범위 안내 메시지가 표시됩니다.
2. 최소금액을 입력하고 결제가 시작되는지 확인합니다.

## 한도 및 참고 사항 {#limits-notes}

- 변경 사항은 신규 결제부터 적용됩니다. 이미 생성된 주문은 생성 당시의 금액을 유지합니다.
- 고객에게 표시되는 안내 문구("최소 $10.00, 최대 $5,000.00") 및 빠른 금액 선택 버튼은 새 제한을 자동으로 따릅니다.
- VND를 표시하는 경우(**Exchange rates** 페이지), 최소금액은 표시 목적으로만 저장된 환율로 변환되며 지갑과 한도는 USD로 유지됩니다.

## Troubleshooting {#troubleshooting}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| "최소 충전 금액은 최대 충전 금액보다 작거나 같아야 합니다" | Values crossed | 최소금액을 낮추거나 최대금액을 높이세요. |
| 고객이 베트남 은행 송금으로 소액을 결제할 수 없음 | Sepay VND 최소금액 또는 USD 최소금액이 더 높음 | 은행 페이지에서 **Min / order** 또는 USD 최소금액을 낮추세요. |
| 충전 중 서버 오류 `invalid_argument` 발생 | 금액이 허용 범위를 벗어남 | 표시된 범위 내의 금액을 입력하세요. |


---

<!-- source: https://nexcmp.com/ko/docs/billing/saved-payment-methods/ -->

# Saved payment methods {#saved-payment-methods}

> **포털 위치:** Billing › Settings(`/billing?settings=1`). **관리자 위치:** Customers › List › a customer › Overview(`/customers/<id>`), **Payment** 카드에서 저장된 결제 수단 및 자동 충전 내역을 확인할 수 있습니다.

## 작동 내용 {#what-it-does}

저장된 결제 수단을 사용하면 NexCMP가 고객이 **직접 조작하지 않아도** 결제할 수 있으므로, 잔액 부족으로 서비스가 중단되는 일이 방지됩니다. 이 기능은 [automatic top-up](https://nexcmp.com/ko/docs/billing/auto-top-up/)에서만 사용됩니다. 결제 수단은 Stripe에 저장된 **카드**(Stripe가 재사용 가능한 카드를 반환하는 Apple Pay, Google Pay 또는 Link를 통해 사용된 카드 포함)와 PayPal 볼트에 저장된 **PayPal 계정**의 두 가지 종류가 있습니다.

## 요구 사항 {#requirements}

| 항목 | 요구 사항 |
|---|---|
| Channels | [Stripe](https://nexcmp.com/ko/docs/billing/stripe/) 및/또는 [PayPal](https://nexcmp.com/ko/docs/billing/paypal/)이 구성되고 활성화되어 있어야 합니다. |
| Site | 플랫폼에서 결제 채널을 수집하는 메인 사이트 또는 리셀러 사이트. 자체 Stripe 계정을 사용하는 리셀러 사이트는 카드를 저장할 수 없습니다. |
| Customer | 해당 카드 또는 PayPal을 사용하여 충전한 적이 있는 고객 계정. |

## 결제 수단이 저장되는 방식 {#how-a-method-gets-saved}

1. 고객이 **Billing**을 열고 **Deposit**을 클릭한 뒤 **Card** 또는 **PayPal**로 결제합니다.
2. 나중에 결제 수단을 재사용할 수 있도록 결제가 생성됩니다. Stripe는 Stripe에 고객과 함께 카드를 저장(세션 외 사용)하며, PayPal은 볼트 토큰을 저장합니다. NexCMP는 참조 정보(Stripe 결제 수단 ID 및 고객 ID, 또는 PayPal 볼트 ID)와 `visa •••• 4242` 또는 PayPal 이메일 같은 표시 라벨만 보관합니다. **카드 번호는 서버에 절대 저장되지 않습니다.**
3. 결제가 완료되면, 고객이 이전에 설정을 선택한 적이 없는 경우 [automatic top-up](https://nexcmp.com/ko/docs/billing/auto-top-up/)이 한 번 활성화됩니다. 화면에 별도의 체크박스나 메시지는 표시되지 않습니다. 서버는 증거로 시간, 고객의 IP 주소, 결제 수단을 기록합니다.
4. 다음부터는 충전 화면의 카드 드롭다운에 **Saved card ...**가, PayPal의 경우 **Saved PayPal ...**이 표시됩니다.


## Manage and remove {#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**을 열면 카드와 자동 충전 스위치(on)가 표시됩니다.
2. 다른 입금을 시작하면 드롭다운에 저장된 카드가 표시됩니다.
3. 관리자 화면의 고객 **Payment** 카드에 동일한 카드 라벨이 표시됩니다.

## 한도 및 참고 사항 {#limits-notes}

- **Stripe Link 및 지갑.** Link, Apple Pay, Google Pay는 Stripe 기능입니다. NexCMP는 Link 관련 정보를 저장하지 않으며, Stripe가 반환하는 카드 참조값만 유지합니다.
- **PayPal.** 고객이 시작하는 모든 PayPal 입금에는 클릭이 필요하며, 저장된 PayPal은 다른 기능이 아닌 자동 충전에만 사용됩니다.
- **리셀러 사이트.** 리셀러가 자체 Stripe 또는 PayPal 계정을 사용하는 경우, 해당 사이트에서는 저장된 결제 수단이 숨겨지고 자동 충전을 사용할 수 없습니다.
- **분쟁 (Disputes).** 결제에 대한 분쟁이 발생하면 계정이 차단되고 선불 서비스가 중지됩니다. [Stripe](https://nexcmp.com/ko/docs/billing/stripe/)를 참조하십시오.
- **마지막 결제 수단 제거** 시 자동 충전이 꺼지며, 고객의 지갑 잔액은 유지됩니다.
- **증적.** 동의 기록은 서버에서 작성되며(고객이 수정할 수 없음) 분쟁 처리를 위해 보관됩니다.

## Troubleshooting {#troubleshooting}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| 고객에게 설정 버튼이나 저장된 카드가 표시되지 않음 | 사이트가 리셀러 소유의 결제 채널을 사용 중이거나 아직 카드 결제 내역이 없음 | 플랫폼 채널을 통해 카드 또는 PayPal로 입금합니다. |
| Stripe 결제 후 "Saved card"가 누락됨 | 재사용할 수 없는 수단(예: Alipay)으로 결제됨 | 카드로 다시 결제합니다. |
| PayPal: "이 계정을 아직 저장할 수 없습니다" | PayPal이 볼트 토큰을 반환하지 않음 | 일회성 결제로 진행하거나 다른 PayPal 계정을 사용해 보십시오. |
| 카드 제거 후 자동 충전이 중지됨 | 예상 동작: 카드 제거 시 기능 비활성화 | 다음 입금 시 새 결제 수단을 저장합니다. |


---

<!-- source: https://nexcmp.com/ko/docs/billing/auto-top-up/ -->

# 자동 충전 {#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/ko/docs/billing/saved-payment-methods/)으로 청구하고 지갑을 충전하여, 잔액 부족으로 실행 중인 서비스가 중단되지 않도록 합니다. 백그라운드 작업이 **5분마다** 활성화된 모든 고객을 확인합니다.

## 요구 사항 {#requirements}

| 항목 | 요구 사항 |
|---|---|
| 채널 | [Stripe](https://nexcmp.com/ko/docs/billing/stripe/) 및/또는 [PayPal](https://nexcmp.com/ko/docs/billing/paypal/) 설정됨. |
| 저장된 수단 | 고객에게 저장된 카드 또는 PayPal 계정이 있음. |
| Site | 메인 사이트, 또는 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/ko/docs/billing/minimum-top-up/) 이상, 최대 top-up 및 일일 한도 이하 |
| **Fixed amount** | 고객 고유의 임계값 ($1 ~ $500) | 고객 고유의 금액 (최소 충전금액부터 $1,000까지, 그리고 임계값보다 큼) |

**By usage** 모드에서 실행 중인 서비스가 없으면 아무것도 청구되지 않습니다.

임계값과 비교되는 잔액은 **지갑의 실제 현금**입니다. 프로모션 코드의 서비스 크레딧은 별도로 보관되며 합산되지 않습니다([Promotions](https://nexcmp.com/ko/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)**에서 다음을 설정합니다:

   | 설정 | Default | 범위 | 의미 |
   |---|---|---|---|
   | 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**을 클릭합니다.

![글로벌 스위치 및 일일 한도가 포함된 Fees and limits 페이지의 Auto top-up 섹션](https://nexcmp.com/ko/docs/images/billing/auto-top-up-01-limits.webp)

## 고객 화면 {#what-the-customer-sees}

1. 포털에서 고객은 **Billing**을 열고 **Settings**를 클릭합니다.
2. 패널에는 저장된 결제 수단, 켜기/끄기 스위치, 모드(**By usage** 또는 **Fixed amount**), 예상 현재 사용량 및 다음 청구 금액, 그리고 **Recent automatic top-ups**가 표시됩니다.
3. **Fixed amount**로 전환하면 임계값과 금액을 입력할 수 있습니다. 스위치를 끄면 청구가 중단됩니다.

![By usage 모드의 자동 충전 및 최근 자동 충전 내역이 있는 고객 청구 설정](https://nexcmp.com/ko/docs/images/billing/auto-top-up-02-portal.webp)

## 확인 {#verify}

1. 테스트 고객으로 테스트 카드([Stripe](https://nexcmp.com/ko/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회 하락당 1회 결제.** 결제 후 잔액이 임계값 위로 올라가거나 대기 시간이 끝날 때까지 작업이 대기합니다 (성공 후 1시간, 보류 중인 결제 후 24시간, 시스템 오류 후 30분).
- **일일 한도.** 두 일일 한도 중 하나에 도달하면 결제가 이루어지지 않으며 *Daily limit reached* 줄이 기록됩니다 (6시간마다 최대 1회).
- **실패.** 거절된 카드, 만료된 카드 또는 잔액 부족은 카드 실패로 간주됩니다. 작업은 1시간, 6시간, 24시간 후에 재시도됩니다. **3회 연속 카드 실패 후 자동 충전이 꺼지고** 고객에게 알림이 전송됩니다 (*Auto top-up failed*). 고객의 확인이 필요한 결제(예: 3-D Secure)는 실패로 계산되지 않으며, 고객에게 확인하도록 안내됩니다.
- **중복 결제 방지.** 각 결제는 임계값 이하로 떨어진 시점마다 원자적으로 청구되며 게이트웨이의 멱등성 키를 사용합니다.
- **카드를 제거하면** 자동 충전이 꺼집니다.
- **리셀러.** 리셀러가 자체 결제 채널을 사용하는 경우 고객은 자동 충전을 활성화할 수 없습니다 (HTTP 403 `feature_disabled`).

## Troubleshooting {#troubleshooting}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| 고객이 켤 수 없음: "카드로 또는 PayPal로 한 번 충전" | 저장된 결제 수단 없음 | 먼저 카드 또는 PayPal로 한 번 충전하세요. |
| 오류 `no_card` (422) | 선택한 게이트웨이에 저장된 결제 수단이 없음 | 결제 수단이 있는 게이트웨이를 선택하거나 결제 수단을 저장하세요. |
| 금액 관련 오류 `invalid_argument` | 허용된 범위를 벗어난 고정 모드 | 임계값 $1~$500, 충전 금액은 최소 충전 금액과 $1,000 사이, 금액은 임계값보다 커야 합니다. |
| 잔액이 부족한데도 결제되지 않음 | 전역 꺼짐, By usage 모드에서 실행 중인 서비스 없음, 일일 한도 도달 또는 이전 결제 대기 중 | 스위치, 내역 및 한도를 확인하세요. |
| "N회 연속 실패 — 3회 후 자동 충전 꺼짐" | 카드가 계속 실패함 | 고객이 카드를 새 보증금으로 교체합니다. |
| 상태 *Needs your confirmation* | 은행에서 3-D Secure를 요구함 | 고객이 일반 충전을 한 번 완료합니다. |


---

<!-- source: https://nexcmp.com/ko/docs/billing/invoices-and-ledger/ -->

# 인보이스 및 원장 {#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 센트로 저장되며 한 번 기록됩니다. 핵심 개념: **지갑 원장**이 잔액의 단일 진실 공급원이며 인보이스, 충전 결제 및 보고서는 이를 바탕으로 생성되는 뷰입니다. 원장은 **추가 전용(append-only)**입니다. 실수는 역분개 항목을 추가하여 수정하며, 기록을 직접 편집하지 않습니다.

## 요구 사항 {#requirements}

| 항목 | 요구 사항 |
|---|---|
| 역할 | 관리자. |
| 판매자 세부 정보 | **System › Settings › General**의 **Seller & invoicing** 탭 (`/settings?tab=seller`), **Seller details (printed on invoices)** 카드에서 법인명, 사업자 등록번호, 주소, 연락처 이메일 및 인보이스 번호 접두사를 설정합니다. |
| 의존성 | 들어오는 자금을 위한 [Payment channels](https://nexcmp.com/ko/docs/billing/payment-channels/). |

## 구성 요소 {#the-pieces}

| 관리자 탭 | 목록 내용 | 권장 용도 |
|---|---|---|
| **Overview** | 오늘 및 이번 달 매출, 종류별 원장 합계(예치금, 청구, 환불, 조정, 쿠폰), 상태별 인보이스, 대기 중인 환불, 바로가기, 최근 30일간 서비스별 지출 | 일일 점검 |
| **Transactions** | 지갑 원장, 변동당 한 줄 | 고객의 잔액 설명 |
| **Invoices** | 인보이스 및 모든 서비스의 모든 구매 내역을 보여주는 두 번째 뷰 **Orders** | 문서 찾기, 재발송, 결제 완료 처리 |
| **Top-ups** | 결제 게이트웨이를 통해 수취한 금액 | 결제 확인 및 환불 |
| **Payouts** | 카드 환불, 제휴사 정산, 리셀러 출금 | 출금 승인 |
| **Vouchers** | 충전 코드 | [Promotions](https://nexcmp.com/ko/docs/billing/promotions/) 참조 |
| **Reports** | 서비스별, 리셀러별 매출 | 회계 |

### 거래(원장) {#transactions-ledger}

열: 시간, 고객, **종류**, 서비스, 금액(부호 포함), VM, 참조, 주체, 메모. 필터: 종류, 서비스, 고객 ID, 사이트(리셀러가 있는 경우), 날짜 범위 및 VM 링크.

| 종류 | 의미 |
|---|---|
| `deposit` | 게이트웨이를 통한 충전 |
| `charge` | 서비스에 대해 청구된 금액(주문, 갱신, 시간제 사용 등) |
| `refund` | 지갑으로 반환된 금액 |
| `adjust` | 관리자 크레딧 또는 데비트, 그리고 충전 코드(`vch:`으로 시작하는 참조) — 개요에는 쿠폰이 별도의 행으로 표시됩니다. |

모든 행에는 `dep:stripe:<payment-id>`과 같은 참조가 있으며, 동일한 참조를 두 번 기록할 수 없으므로 중복 웹훅으로 인해 크레딧이 두 번 적립되지 않습니다. 수동 조정을 추가하려면 **Customers › List › customer › Credit / debit**을 사용합니다. 사유는 필수이며, 양수 금액은 잔액 부족으로 잠긴 VM의 잠금 해제도 시도하고, 작업은 두 단계로 확인됩니다.

![종류, 서비스, 금액 및 참조가 표시된 월렛 원장 행을 보여주는 Transactions 탭](https://nexcmp.com/ko/docs/images/billing/invoices-and-ledger-01-ledger.webp)

### 인보이스 {#invoices}

고객이 지갑에서 결제되는 항목을 구매 또는 갱신하거나 충전할 때 인보이스가 자동으로 생성됩니다. 번호는 `<prefix><YYYYMM>-<000001>` 형식(예: `NX202610-000042`)입니다. 리셀러 사이트는 자체 접두사와 일련번호를 사용합니다. 접두사를 변경해도 기존 번호는 변경되지 않습니다.

| 필드 | 값 |
|---|---|
| 종류 | 영수증, 갱신, 충전, 수동, 환불 |
| 상태 | 미결제, 결제완료, 연체, 취소됨, 환불됨 |

행에서의 작업:

| 작업 | 효과 |
|---|---|
| **View** / **Print** | 인보이스를 엽니다. 포털에서 인쇄하거나 PDF로 저장할 수도 있습니다. |
| **Mark paid**(미결제 또는 연체 상태인 경우만) | **지갑 잔액을 이동하지 않고** 결제 완료로 표시합니다. 고객이 NexCMP 외부에서 결제한 경우에 사용하세요. 사유는 필수입니다. 갱신 인보이스의 경우 잠긴 VM을 연장하고 잠금 해제합니다. |
| **Cancel**(미결제 또는 연체 상태인 경우만) | 인보이스를 취소합니다. 사유는 필수입니다. |
| **Resend** | 인보이스를 이메일로 다시 보냅니다. |

**Create manual invoice** (탭 상단의 버튼): 고객 ID, 1~50개의 라인(설명, 수량, 단가), 선택 사항인 VM ID, 선택 사항인 납부 기한(0~365일, 기본값 7), 선택 사항인 메모. 미결제 상태로 생성되며 고객은 **Billing › Invoice History**에서 확인할 수 있습니다.

서비스의 미결제 인보이스는 잔액이 충전되는 즉시 **지갑에서 자동으로 정산**되므로, 고객은 잔액만 충전하면 됩니다.


### Top-ups (payments) {#top-ups-payments}

시도당 1개 행: 시간, 고객, **게이트웨이 및 수단**, 유형(충전 또는 자동 충전), 상태(대기 중, 완료됨, 실패함, 환불됨, 분쟁 중, 취소됨), 고객 결제 금액, 수수료, 지갑 충전 금액, 게이트웨이 참조 번호 및 완료 시간. 완료된 Stripe 및 PayPal 결제에는 **Refund** 작업이 있습니다. 웹훅을 확인하려면 게이트웨이 이벤트 페이지([Payment channels](https://nexcmp.com/ko/docs/billing/payment-channels/))를 사용하세요.

### Payouts {#payouts}

세 개의 하위 탭: **Card refunds**(환불 요청 승인 또는 거부, 요청은 완료된 결제에서 생성됨), **Affiliate payouts**(수수료 인출) 및 **Reseller withdrawals**. 모든 결정은 감사 대상이 됩니다.

### Reports {#reports}

**Revenue** (30일 추이, 월별, 우수 고객), **By service** 및 **By reseller**.

![수익 KPI와 30일 추이를 보여주는 Reports 탭](https://nexcmp.com/ko/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}

- **추가 전용.** 원장 라인은 수정하거나 삭제할 수 없으며, 사유를 기재하여 조정 항목을 추가해야 합니다.
- **통화.** 금액은 USD이며, 표시 통화는 보기 위한 용도일 뿐입니다([Currency and exchange rates](https://nexcmp.com/ko/docs/catalog/currency-and-exchange-rates/) 참조).
- **카드로 환불**은 2단계(요청 후 Payouts에서 승인)로 진행되며, USDT 및 은행 송금은 원 출금처로 환불되지 않습니다.
- 입력한 사유와 함께 System › Logs › Admin actions에서 **모든 내역이 감사**됩니다.
- **주문 대 인보이스.** 시간당 사용량은 시간별로 청구되지 않으며, Orders 뷰에서는 여전히 확인할 수 있도록 일별로 그룹화합니다.

## Troubleshooting {#troubleshooting}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| 고객 잔액이 올바르지 않은 경우 | 예상치 못한 청구, 조정 또는 바우처 | **Transactions**을 고객 ID로 필터링하고 참조 번호와 메모를 확인합니다. |
| "인보이스가 이미 결제되었습니다" (409) | 이미 결제된 인보이스에 결제 완료 표시 | 조치할 필요가 없습니다. |
| 인보이스를 취소할 수 없음 | 미결제 또는 연체된 인보이스만 취소 가능 | 결제된 인보이스의 경우 환불 또는 조정을 사용하세요. |
| 인보이스에 판매자 정보가 누락됨 | 입력되지 않음 | System › Settings › General › Seller & invoicing에서 **Seller details**를 완료하세요. |
| 신용/직불카드 거부됨 | 금액이 0이거나 $100,000를 초과함 | 1센트에서 $100,000 사이의 금액을 사용하세요. |
| 결제 상태가 오랜 시간 *Pending*으로 표시됨 | 웹훅 누락 | **Gateway events**를 확인하고 다시 재생하세요. |


---

<!-- source: https://nexcmp.com/ko/docs/billing/promotions/ -->

# 프로모션 {#promotions}

> **관리자 페이지 위치:** Finance › Billing › Vouchers (`/billing/vouchers`). **포털 위치:** Billing › Redeem code (예치금 서랍 내부에도 있음).

## 작동 내용 {#what-it-does}

**충전 코드**(바우처)는 고객에게 제공하는 일회용 비밀 코드입니다. 생성 방식에 따라 다음 기능이 제공됩니다:

| 유형 | 고객 혜택 | 적용 위치 |
|---|---|---|
| 모든 서비스 대상 **Bonus credit** | 지갑에 적립되는 금액 | 지갑 잔액. 모든 용도로 사용 가능. |
| 선택한 서비스 대상 **Bonus credit** | 서비스 크레딧 | 해당 서비스 결제에만 사용할 수 있는 별도 지갑. |
| **Discount %** | 선택한 서비스의 첫 주문에 대한 할인율 | 크레딧이 적립되지 않으며, 결제 시 할인이 적용됩니다. |

캠페인, 보상 크레딧, 파트너 제휴 또는 첫 주문 할인에 활용하세요.

## 요구 사항 {#requirements}

| 항목 | 요구 사항 |
|---|---|
| 역할 | 관리자. |
| 고객 | 고객이 포털에 로그인한 상태에서 코드를 사용합니다(게스트 불가). 기본적으로 고객은 이메일 인증을 완료해야 합니다. |
| VND 코드 | VND로 생성된 코드는 저장된 환율을 사용하여 사용 시점에 USD로 환산됩니다([Currency and exchange rates](https://nexcmp.com/ko/docs/catalog/currency-and-exchange-rates/) 참조). |

## 배치 생성 {#create-a-batch}

1. **Finance › Billing › Vouchers**를 열고 **Create vouchers**를 클릭합니다.
2. 양식을 작성합니다. 예시 값은 괄호 안에 있습니다.

   | 필드 | 참고 |
   |---|---|
   | 배치 이름 | 1–80자 (`Spring welcome`). |
   | 대상 | **Main site clients**, **Single reseller's customers**(고객 목록 필요) 또는 **Reseller wallet**. |
   | 대상 사용자 | **All in target audience** 또는 **Specified** — 줄당 이메일 또는 고객 ID 하나씩, 최대 1,000개. 리셀러 고객의 경우 반드시 *Specified*여야 합니다. |
   | 대상별 1개 코드 | *Specified* 선택 시 나열된 고객당 하나의 코드가 생성됩니다. |
   | 코드 유형 | **Bonus credit** 또는 **Discount %**. |
   | 적용 대상 | 하나 이상의 서비스 선택; 비워두면 **All services**. |
   | 통화, 액면가 | USD는 $1.00부터, VND는 10,000부터 1,000 단위로 설정(보너스 크레딧만 해당). |
   | 할인율 (%) | 1에서 100 사이 (할인 %만 해당). |
   | 최대 할인 한도 (USD) | 할인 %에 필수, $1.00부터 시작. 사용 1회당 최대 할인 금액입니다. |
   | 최소 주문 금액 (USD) | `0` = 없음. 첫 주문 금액이 이 금액 이상이어야 합니다. |
   | 코드 수 | 1에서 1,000개의 무작위 코드. |
   | 코드당 사용 횟수 | 1~100,000. `1`은 코드당 1명을 의미하며, 공유 코드인 경우 값을 높이세요. |
   | 계정당 최대 사용 횟수 | 최소 1 이상. % 할인인 경우 `1`이어야 합니다. |
   | 시작 시간(선택 사항), 만료일 | 만료일은 오늘 이후이자 시작일 이후여야 하며, 최대 2년 이내여야 합니다. |
   | 코드 접두사(0~6자) | 문자만 가능하며, 비워 둘 경우 사이트 접두사가 사용됩니다. |
   | 사용자 지정 코드(수량이 1개인 경우에만 해당) | A~Z 및 0~9 문자로 구성된 6~32자. 공유하기는 쉽지만 추측하기도 쉬우므로 사용 횟수를 낮게 설정하세요. |
   | 이메일 인증 필수 | 기본적으로 활성화되어 있습니다. |
   | 내부 메모, 사유 | 사유는 필수이며 감사 로그에 기록됩니다. |

3. 최악의 경우를 파악할 수 있도록 폼에 **최대 노출 금액**(액면가 x 코드 수 x 사용 횟수)이 표시됩니다. **Generate codes**를 클릭합니다.
4. **지금 코드를 복사하세요.** 코드는 한 번만 표시되며 NexCMP에는 해시와 마지막 4자리만 저장됩니다. **Copy all** 또는 **Download CSV**를 사용하고 확인란을 체크한 뒤 창을 닫으세요.



## 유형별 동작 방식 {#how-each-type-behaves}

### 크레딧 보너스(선택된 서비스 없음) {#wallet-bonus-no-service-selected}

크레딧은 **조정** 항목(참조 `vch:...`)으로 지갑에 적립됩니다. 카드 결제 수단으로 환불되지 않으며, 파트너 커미션이 적립되지 않고, 인보증을 생성하지 않으며, 할당량 산정을 위한 지갑 잔액에 포함됩니다. VND 코드는 사용 시점의 환율을 적용합니다.

### 서비스 크레딧(서비스 선택됨) {#service-credit-services-selected}

- 이 크레딧은 **별도의 포켓**에 보관되며 선택한 서비스의 비용(신규 주문, 갱신, 시간당 또는 일일 요금, 업그레이드) 결제에만 사용할 수 있고 지갑보다 **먼저** 소모됩니다.
- 인출, 양도 또는 현금으로 전환할 수 없으며 코드와 함께 만료됩니다.
- 원장에는 전체 청구 금액과 일치하는 크레딧 내역이 함께 표시되므로, 지갑에서는 고객이 실제로 지불한 금액만 차감되면서도 서비스별 매출은 정확하게 유지됩니다.
- [할당량](https://nexcmp.com/ko/docs/billing/quotas/) 티어를 높이지 **않으며** [자동 충전](https://nexcmp.com/ko/docs/billing/auto-top-up/) 기능에 의해 무시됩니다.
- 크레딧이나 할인이 적용되어 결제된 요금이 환불되는 경우, 코드가 지불했던 금액만큼 지갑 환불금에서 차감되어 크레딧 포켓으로 반환됩니다.

### % 할인 {#discount}

1. 고객이 코드를 입력하면 **활성화**됩니다. % 할인 코드는 계정당 한 번만 사용할 수 있습니다.
2. 시간당 요금이 아닌 선택된 서비스의 **첫 번째 청구** 금액 중 **최소 주문 금액** 이상인 부분에 대해 백분율 할인이 적용되며, **최대 할인 한도**를 초과할 수 없습니다.
3. 할인 금액은 청구 시점에 서버에서 다시 계산되며 브라우저에 표시된 금액은 무시됩니다. 사용 내역 행은 코드가 실제로 사용되고 실제 할인이 적용될 때 기록됩니다.
4. 시간당 사용 요금에는 코드가 적용되지 않습니다.

## 고객이 수행하는 작업 {#what-the-customer-does}

1. 포털에서 **Billing**을 열고 **Redeem code**를 클릭하거나, 예치금 서랍에서 **Have a top-up code?**를 사용합니다.
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개로 이루어진 배치 생성: 할인율 % 20, 최대 한도 $5, 최소 주문 금액 $10, 대상 서비스 Virtual Machines.
2. 테스트 고객으로서 이를 사용합니다. 포털에 활성화되었다고 표시됩니다.
3. 최소 $10 이상(월간 주기) 비용이 발생하는 VM을 주문합니다. 인보이스에 할인(최대 $5)이 적용된 내역이 표시됩니다.
4. 배치에서 해당 코드가 실제 할인과 함께 1회 사용된 것으로 표시됩니다.

## 한도 및 참고 사항 {#limits-notes}

- 코드는 생성 시 **audience**와 **sité**에 종속되며, 나중에 이동할 수 없습니다.
- 리셀러는 월간 노출 한도 내에서 자신의 고객에게 코드를 발행할 수 있습니다. [Resellers](https://nexcmp.com/ko/docs/customers/resellers/)를 참조하세요.
- 고객용 사이드바 프로모션 슬라이드(**Marketing › Promo slides**)는 별도의 기능이며 할인을 제공하지 않습니다.
- 일반 텍스트로 된 코드는 저장되지 않으므로, 분실된 배치는 복구할 수 없습니다. 비활성화하고 새 배치를 만드세요.

## Troubleshooting {#troubleshooting}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| "퍼센트 코드: 계정당 1회 사용" (`percent_one_per_account`) | Discount %에 대해 계정당 최대 사용 횟수가 1보다 큼 | `1`(으)로 설정합니다. |
| 최대 한도가 필수라는 폼 오류 메시지 표시 | 최대 할인 한도가 없는 Discount % | 최소 $1.00 이상을 입력하세요. |
| 고객을 찾을 수 없음 | 목록의 이메일 또는 ID가 존재하지 않음 | 목록을 수정하세요 (오류 메시지에 알 수 없는 항목이 표시됩니다). |
| 고객이 "invalid code" 메시지를 확인함 | 잘못된 사이트, 만료됨, 비활성화됨, 소진됨, 대상 고객이 아님, 또는 이메일 인증 안 됨 | 배치와 고객을 확인하세요. |
| 크레딧이 사용되지 않음 | 청구 건이 다른 서비스에 속함 | 크레딧은 배치에서 선택한 서비스에만 적용됩니다. |
| 할인이 적용되지 않음 | 최소 주문 금액 미달, 시간당 과금, 또는 다른 서비스용으로 활성화된 코드 | 조건을 충족하는 첫 주문을 진행하세요. |
| 고객의 코드 사용이 잠김 | 잘못된 시도가 너무 많이 발생함 | 잠금이 해제될 때까지 기다리세요. |




---

<!-- source: https://nexcmp.com/ko/docs/billing/quotas/ -->

# 할당량 {#quotas}

> **관리자 위치:** Services › Virtual Machines › Policy › Quota 탭(`/vm/policy?tab=quota`). 고객별: Customers › List › a customer › Overview(`/customers/<id>`), **Quota** 카드. **포털 위치:** Client › Quotas(`/client/quotas`).

## 작동 내용 {#what-it-does}

할당량은 신규 계정의 어뷰징으로부터 시스템을 보호합니다. 고객이 지갑에 실제 자금을 많이 충전할수록 더 많은 리소스를 생성할 수 있습니다. 여기에는 두 가지 계층이 있습니다:

- **VM 및 Kubernetes 리소스**: 총 vCPU, RAM 및 디스크와 VM 수. 티어는 고정 플랜입니다.
- **서비스 할당량**: 입금액에 따라 결정되는 5개의 티어(L0부터 L4까지)에 따른 IP, 클러스터, VPC, 저장소 GB 등의 수량입니다.

할당량은 요금이 청구되기 **전에** 확인됩니다. 한도를 초과한 요청은 HTTP 403 `quota_exceeded` 및 고객에게 필요한 충전 금액을 안내하는 메시지와 함께 거부됩니다.

## 요구 사항 {#requirements}

| 항목 | 요구 사항 |
|---|---|
| 역할 | 관리자. |
| 스위치 | **Enable quota**(`quota_enabled`)는 기본적으로 **꺼져** 있습니다. 활성화하기 전까지 아래 내용은 적용되지 않습니다. |
| 고정 플랜 | 적어도 하나의 커스텀이 아닌 플랜([Plans](https://nexcmp.com/ko/docs/catalog/plans/) 참조) — 리소스 티어는 고정 플랜입니다. 플랜이 없는 경우 VM 수 규칙만 적용됩니다. |
| 의존성 | 서비스 할당량 행은 설치 시 활성화된 제품(VPN, IPv6 프록시, Kubernetes, 프라이빗 클라우드, 이미지, Object Storage, 전용 서버)에만 존재합니다. |

## 기준 계산 방식 {#how-the-basis-is-calculated}

NexCMP는 카드 결제만 확인하지 않습니다. **기준**은 고객의 **기록된 지갑 잔액**입니다. 게이트웨이 충전, 관리자 크레딧(**Credit / debit**) 및 적립된 지갑 바우처 모두 지갑 원장을 통해 한 번씩 합산됩니다. 프로모션 코드의 주문 할인 및 서비스 크레딧은 지갑 자금이 아니므로 합산되지 않습니다. 고객이 도달한 최고 기준은 사이트별로 **유지**되며, 사용이나 환불로 인해 이미 달성된 티어가 낮아지지 않습니다.

### VM 및 Kubernetes 리소스 {#vm-and-kubernetes-resources}

1. 티어는 24시간 운영 비용을 기준으로 정렬된 사이트의 고정 플랜입니다.
2. 고객은 24시간 비용이 자신의 기준을 초과하지 않는 가장 높은 티어에 속하게 됩니다. 한도는 해당 플랜의 vCPU, RAM 및 디스크입니다. 가장 저렴한 플랜조차 감당할 수 없는 고객에게도 가장 저렴한 플랜의 리소스가 제공됩니다.
3. 한도에 합산되는 사용량은 실행 중인 모든 VM(잠긴 VM 포함), 구매한 데이터 볼륨(분리된 경우도 포함), Kubernetes 워커 및 제어 평면(워커도 VM으로 합산)입니다.
4. **VM 수:** **Max VMs at 24h tier**(기본값 2)까지 허용됩니다. 다음 VM부터는 고객의 *현재* 지갑 잔액이 기존 모든 VM과 신규 VM을 합산한 **30일(720시간)** 분량의 비용을 충족해야 하며, 최대 **Max VMs when meeting 30-day threshold**(기본값 10)까지 허용됩니다.
5. **VM 생성** 시에는 해당 VM의 최소 **N시간** 분량 잔액(**Create VM: balance ≥ N hours**, 기본값 2)과 플랫폼 최소 잔액도 필요합니다.
6. VM 크기를 줄이는 것은 차단되지 않습니다. 증가하는 항목만 확인하므로 디스크 한도를 초과한 고객이라도 vCPU 한도가 허용한다면 vCPU를 추가할 수 있습니다.

## 구성 {#configure}

1. **Services › Virtual Machines › Policy**를 열고 **Quota** 탭을 선택합니다.
2. **Enable quota**를 켭니다.
3. 세 가지 숫자(모두 편집 가능)를 검토합니다:

   | 필드 | Default | 범위 |
   |---|---|---|
   | VM 생성: 잔액 ≥ N시간 | 2 | 1 ~ 720 |
   | Max VMs at 24h tier | 2 | 1 ~ 100 |
   | 30일 임계값 충족 시 최대 VM 수 | 10 | 1 ~ 1000 (이전 필드보다 작을 수 없음) |

4. **Tier-based service quotas**에서 표(아래)를 편집합니다.
5. **Save**를 클릭합니다. NexCMP가 **사유(reason)**를 입력받으며, 이는 변경 전후의 값과 함께 감사 로그에 기록됩니다. 변경 사항은 모든 고객에게 적용됩니다.

![활성화 스위치, VM 한도 및 티어 기반 서비스 할당량 표가 있는 Quota 탭](https://nexcmp.com/ko/docs/images/billing/quotas-01-policy.webp)

### 서비스 할당량 표 {#service-quota-table}

이 표는 5개의 등급으로 구성됩니다. **L0**부터 **L4**까지의 헤더 셀은 **센트 단위의 예치금 임계값**을 나타냅니다. 기본값 `0, 1000, 5000, 20000, 100000`은 신규 계정의 경우 L0, $10 이상은 L1, $50 이상은 L2, $200 이상은 L3, $1,000 이상은 L4를 의미합니다. 첫 번째 임계값은 `0` 상태로 유지되어야 합니다. 각 행은 등급별로 키 하나의 할당량을 설정하며, **-1은 무제한**을 의미합니다.

| 키 | 의미 | L0 | L1 | L2 | L3 | L4 |
|---|---|---|---|---|---|---|
| `vpn.ips` | VPN IP | 2 | 10 | 30 | 100 | 500 |
| `proxy6.ips` | IPv6 프록시 IP | 500 | 2000 | 10000 | 50000 | -1 |
| `dedicated.servers` | 베어메탈 서버 | 1 | 2 | 5 | 20 | 50 |
| `s3.storage_gb` | 할당된 Object Storage GB | 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` | 커스텀 이미지 스토리지 GB | 50 | 100 | 200 | 500 | 2000 |

이 표에는 이번 릴리스에 포함되지 않은 제품에 대한 몇 가지 행도 나열되어 있으며, 해당 행은 변경하지 마십시오. 제품이 비활성화된 키는 숨겨지며 적용되지 않습니다. 값은 `-1`이거나 `0`과 `10,000,000` 사이여야 합니다.

서비스 할당량은 VM 등급과 마찬가지로 카드 결제 총액이 아닌 도달한 최고 지갑 잔액인 **자금 기준**을 따릅니다. 리셀러 고객은 동일한 기본값을 사용하며, 리셀러는 이를 조회만 할 수 있습니다.

## 고객별 재할당 {#per-customer-overrides}

1. **Customers › List**를 연 다음 해당 고객을 엽니다. **Overview**에서 **Quota** 카드를 찾습니다.
2. **VM 리소스:** **Quota override**를 클릭하고 다음 중 하나를 선택합니다.
   - **충전 잔액 기준(재할당 제거)** — 기본 동작입니다.
   - **무제한(VM 수 포함)** — 이 고객에 대한 모든 제한을 제거합니다.
   - **플랜 등급** — 리소스 상한선을 해당 플랜으로 고정하며, VM 수 규칙은 계속 적용됩니다.

   사유를 입력하세요. 플랫폼 관리자는 모든 등급을 설정할 수 있으며, 리셀러가 설정한 재할당은 고객의 보관된 기준을 초과할 수 없습니다.
3. **서비스:** *Service quotas* 아래의 표에는 각 키의 *In use*, 유효 제한 및 해당 *Source*(등급 또는 재할당)가 표시됩니다. 행의 **Edit**을 클릭하고 **New quota**(`-1` = 무제한, 비워둠 = 등급 기본값으로 복원)와 사유를 입력합니다.

![등급, 리소스 사용량, 재할당이 포함된 서비스 할당량 표가 있는 Customer Quota 카드](https://nexcmp.com/ko/docs/images/billing/quotas-02-customer.webp)

모든 재할당은 관리자, 사유 및 변경 전후 값과 함께 감사 로그에 기록됩니다.

## 고객 화면 {#what-the-customer-sees}

**Client › Quotas**(`/client/quotas`)는 고객의 **현재 등급**, 사용된 vCPU·RAM·disk 및 VM 총수(VM과 Kubernetes로 분할), **적격 지갑 잔액**, **보유 리소스 기준**(소비해도 감소하지 않음), 그리고 다음 등급까지 충전해야 할 금액을 보여줍니다. 슬라이더를 통해 목표 등급을 선택하고 예치금 화면으로 바로 이동할 수 있습니다. **Service Quotas** 카드는 각 서비스의 할당량, 사용량, 등급(L0~L4), 다음 등급을 위해 추가로 예치해야 할 금액, 그리고 지원 티켓 초안을 여는 **Request increase** 버튼을 나열합니다. **Quota policy** 버튼은 규칙을 설명합니다.

![현재 등급, 리소스 사용량 및 서비스 할당량이 표시된 Portal Quotas 페이지](https://nexcmp.com/ko/docs/images/billing/quotas-03-portal.webp)

## 확인 {#verify}

1. **Enable quota**를 켜고 잔액이 $0인 새로운 테스트 고객을 사용합니다.
2. 가장 저렴한 플랜보다 더 큰 VM을 생성해 보십시오. `quota_exceeded` 및 "Exceeds the resources of tier ... Top up $X more to unlock tier ..." 메시지와 함께 요청이 거부됩니다.
3. 표시된 금액을 충전하십시오. 등급이 즉시 변경되며 동일한 요청이 성공합니다.
4. L0 한도를 초과하여 VPN IP를 구매합니다: 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**)에 따라 신규 계정은 예치금이 $10에 도달할 때까지 VM이 2개로 제한됩니다. 할당량이 켜져 있으면 해당 규칙은 더 이상 적용되지 않습니다.
- **관리자가 생성한 VM은 차단되지 않습니다.**
- **오류 발생 시 차단됩니다.** 할당량 상태를 읽을 수 없는 경우, 요청은 허용되는 대신 `quota_unavailable`(으)로 거부됩니다.
- **API, CLI 및 MCP** 요청은 동일한 핸들러를 사용하므로 동일한 제한이 적용됩니다.
- **프로모션 크레딧**은 등급을 높이지 않습니다([Promotions](https://nexcmp.com/ko/docs/billing/promotions/) 참조).
- **등급 임계값은 달러가 아니라 센트**입니다.

## Troubleshooting {#troubleshooting}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| `quota_exceeded`, 사유 `resources` | 새로운 총 vCPU/RAM/디스크가 등급을 초과함 | 메시지에 표시된 금액을 충전하거나 오버라이드를 설정하세요. |
| `quota_exceeded`, 사유 `vm_30d` | 24시간 등급 VM 수를 초과하고 지갑이 아직 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**을(를) 플랜 비용과 비교하세요. | 플랜 가격표를 확인하세요: 플랜 가격 인상으로 인해 임계값이 이동할 수 있습니다. |


---

<!-- source: https://nexcmp.com/ko/docs/customers/managing-customers/ -->

# 고객 관리 {#managing-customers}

> **관리자 위치:** Customers › Customers › List (`/customers`), Deletion requests (`/customers/requests`), Service transfers (`/customers/transfers`) 및 API keys (`/customers/apikeys`).

## 작동 내용 {#what-it-does}

고객 영역은 지원 직원이 계정을 조회하고, 지갑, 서비스, 티켓 및 로그인 내역을 확인하며, 잠금, 잠금 해제, 이메일 인증, 비밀번호 재설정, 크레딧 추가 또는 제거, 가장(impersonation), VM 생성 또는 계정 폐쇄 등의 작업을 수행하는 곳입니다.

## 요구 사항 {#requirements}

| 항목 | 요구 사항 |
|---|---|
| 역할 | 관리자. 모든 쓰기 작업은 사유를 요구하며 감사 로그(System › Logs › Admin actions)에 기록됩니다. |
| 이메일 | 비밀번호 재설정 및 초대 이메일에는 정상 작동하는 [SMTP configuration](https://nexcmp.com/ko/docs/administration/smtp-and-emails/)이(가) 필요합니다. |

## 고객 목록 {#the-customer-list}

**Customers › List**를 엽니다. Customers는 기본 사이트의 계정이며, 리셀러 계정도 함께 표시되고 사이트별로 필터링할 수 있습니다.

![필터, 국가, 유입 경로, 잔액 및 VM 수 컬럼이 포함된 고객 목록](https://nexcmp.com/ko/docs/images/customers/managing-customers-01-list.webp)

| 컬럼 | 의미 |
|---|---|
| **Email** (및 이름) | 클릭하여 고객을 엽니다. |
| **State** | *Active*, *Locked* 또는 *Deleted*, 그리고 *verified* 또는 *unverified* 이메일. 잠금 태그 위에 마우스를 올려 사유를 확인하세요. |
| **Login** | 고객이 보유한 로그인 수단: 비밀번호, Google, GitHub, 패스키. |
| **Country** | **IP 주소**에서 파생된 국기와 이름: 가입 IP의 국가, 또는 알 수 없는 경우 마지막 로그인 IP의 국가. 툴팁에 사용된 IP가 표시됩니다. |
| **유입 경로** | *Referral*: 고객이 제휴 링크를 통해 가입한 경우 추천인과 추천 코드 링크가 표시되며, 그렇지 않은 경우 "Not recorded"로 표시됩니다. |
| **Balance**, **VMs** | 지갑 잔액(음수 값은 빨간색으로 표시) 및 실행 중인 VM의 수입니다. |
| **IP 등록 / 최근** | 가입 시 및 마지막 로그인 시 사용된 IP와 두 자리 국가 코드가 표시됩니다. 하나의 주소에서 여러 계정이 생성되었는지 확인하는 데 사용하세요. |
| **Tenant** | 고객의 내부 테넌트 ID입니다. |
| **Created**, **Last login** | 상대 시간입니다. |
| **Site** | 리셀러가 있는 경우에 표시됩니다. |

**Search**는 이메일, 이름 또는 IP를 지원합니다. **Filters:** 상태(전체, 활성, 잠김, 삭제됨), 로그인 방식(전체, Google, GitHub, 패스키, 아직 비밀번호 없음) 및 사이트. 필터는 URL에 유지되므로 필터링된 목록을 북마크하거나 동료와 공유할 수 있습니다.

**정렬은 전역으로 적용됩니다.** *Email*, *State*, *Balance*, *VMs*, *Created* 또는 *Last login*의 헤더를 클릭하면 현재 보고 있는 페이지뿐만 아니라 서버의 **전체** 고객 기반이 정렬되며 페이지 번호가 1로 돌아갑니다.

**목록은 자동으로 업데이트됩니다.** 화면을 보고 있는 동안 몇 초마다 새로고침되므로(대화 상자가 열려 있거나 입력 중일 때는 일시 중지됨) 페이지를 새로고침하지 않아도 신규 가입 및 잔액 변경 사항이 즉시 반영됩니다. 고객 페이지는 화면에 표시되는 동안 약 30초마다 새로고침되며, 각 탭은 처음 열릴 때 자체 데이터를 로드합니다.

### 고객 생성 {#create-a-customer}

1. **Create customer**을 클릭합니다.
2. **이메일**, 선택 사항인 **표시 이름**, 선택 사항인 **비밀번호**(비워 두면 고객이 초대 링크를 통해 설정함)를 입력하고 **이메일 초대 발송** 여부를 선택합니다.
3. 확인합니다. 수동으로 생성한 계정은 초대를 발송할 때 인증된 것으로 처리됩니다.

## 고객 페이지 {#a-customer-s-page}

행을 클릭하십시오. 페이지에는 8개의 탭이 있으며, 선택한 탭이 URL에 유지되므로 북마크할 수 있습니다. 탭은 처음 열릴 때 데이터를 로드하며 다른 탭으로 전환해도 상태가 유지됩니다.

| 탭 | 내용 |
|---|---|
| **Overview** | 신원, 가입 및 최근 로그인 정보, 지갑 및 서비스 요약 |
| **Services** | 고객 서비스 목록 테이블(유형 및 상태 필터, 검색, 서버 측 정렬 및 페이지네이션 제공) |
| **Billing** | 지갑 및 크레딧, 원장, 청구서, 결제, 환불, 저장된 결제 수단 및 자동 충전 |
| **Quota** | 리소스 한도 및 오버라이드. [Quotas](https://nexcmp.com/ko/docs/billing/quotas/)를 참조하십시오. |
| **Security** | 세션, 인증, 로그인 방식, 로그인 기록 및 API 키. [API keys](https://nexcmp.com/ko/docs/developers/api-keys/)를 참조하십시오. |
| **Support** | 최근 티켓 |
| **Affiliate** | 추천 프로그램 상태 |
| **Log** | 감사 및 활동 내역 |

헤더의 작업 버튼(삭제된 계정의 경우 숨겨짐):

| 버튼 | 작동 내용 |
|---|---|
| **Lock account** / **Unlock** | 로그인 및 API 액세스를 차단합니다. 선택적으로 모든 VM을 중지(삭제하지는 않음)할 수도 있습니다. VM이 아닌 선불 서비스(Kubernetes, Private Cloud, VPN 등)도 함께 중지됩니다. 관리자에 의해 잠긴 VM은 VM 페이지에서 개별적으로 해제해야 합니다. |
| **Verify email** | 고객이 링크를 클릭하지 않아도 이메일이 인증된 것으로 표시합니다. |
| **Send reset link** | 비밀번호 재설정 링크를 이메일로 전송합니다(1시간 유효, 1회용). SMTP가 설정되지 않은 경우 직접 보낼 수 있도록 링크가 한 번 표시됩니다. 관리자는 비밀번호를 절대 볼 수 없습니다. |
| **Impersonate** | 1시간 동안 고객 권한으로 로그인합니다. [Log in as a customer](https://nexcmp.com/ko/docs/customers/login-as/) 문서를 참조하세요. |
| **Credit / debit** | 원장 조정을 통해 지갑 잔액을 추가하거나 차감합니다. [Invoices and ledger](https://nexcmp.com/ko/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개의 행을 선택하고 일괄 작업을 선택하십시오. 결과에는 각 행의 성공 또는 실패 여부가 표시됩니다. 일괄 환불은 각 서비스의 추천 금액을 사용합니다. 추천 환불액이 0인 서비스는 환불 모드에서 건너뛰며, 개별 검토 또는 환불 없는 취소가 필요합니다.

DDoS Shield, 디스크 및 백업은 여기에서 읽기 전용 행으로 표시됩니다. 대역폭 애드온은 상위 서비스를 따릅니다. AI Models 접근은 잠글 수 있지만 취소할 구독이 없습니다. 대여한 Bare Metal 서버를 잠그려면 주문이 아닌 해당 구독에 대해 작업을 수행하십시오.

### 계정 폐쇄 (소프트 딜리트) {#closing-an-account-soft-delete}

계정이 *deleted* 상태로 설정되고 차단되며, 세션이 취소되고 아직 지급되지 않은 추천 수수료가 회수됩니다. 인보이스와 원장은 회계 목적을 위해 유지됩니다. 고객에게 **활성 상태의 서비스** (VM, Kubernetes, Private Cloud, Dedicated, VPN, IPv6 프록시)나 S3 계정 또는 미정산 S3 사용량이 남아 있는 경우 이 작업이 거부됩니다. 먼저 해당 항목들을 삭제하세요.

## 삭제 요청 {#deletion-requests}

고객은 계정 페이지에서 삭제를 요청할 수 있습니다. 요청은 **Customers › Deletion requests**(기본 필터: 대기 중)에 고객, 사유, 활성 VM 수, 잔액, 요청 시간과 함께 표시됩니다.

- **Approve deletion**은 고객에게 활성 VM이 없을 때만 가능합니다. 확인을 위해 이메일 주소를 입력하세요. 계정이 소프트 딜리트되며, **남은 지갑 잔액은 자동으로 환불되지 않습니다**. 환급해야 할 금액이 있는 경우 먼저 환불을 생성하세요.
- **Reject**에는 사유가 필요합니다.

## 서비스 이전 {#service-transfers}

**Customers › Service transfers**에서는 **동일한 사이트 내**에서 한 계정에서 다른 계정으로 **VM 또는 VPN 구독**을 이동하기 위한 요청 목록을 보여줍니다.

- 이 화면은 읽기 및 생성 전용입니다. 관리자가 고객을 대신하여 요청을 생성하거나 취소할 수 있습니다. 소유자나 수신자를 대신하여 승인하는 버튼은 의도적으로 **없습니다**.
- 진행 방식: 소유자가 1회용 이메일 링크(30분 유효, 활성화된 경우 TOTP 포함)를 통해 확인한 후, 수신자가 로그인하여 수락합니다(수신자가 대금 지급 의무를 승계합니다). 7일 이내에 수락되지 않은 요청은 만료됩니다.
- 규칙: 서비스는 활성 상태여야 하며, 미납 인보이스와 실행 중인 작업이 없어야 합니다. 수신자는 동일한 사이트에서 이메일이 인증된 활성 고객이어야 합니다. VM을 이전하면 SSH 키가 제거되고 자동 갱신이 꺼지며, VPN을 이전하면 연결 비밀번호가 변경됩니다.
- 이미 발행된 인보이스는 이전 소유자에게 유지되며, 새 소유자는 이전 소유자의 데이터가 숨겨진 상태로 해당 서비스의 빌링 내역을 읽을 수 있습니다.
- 고객은 포털의 **Transfers**에서 직접 요청을 생성할 수 있습니다(시간당 5개 요청, 동시 진행 3개 제한).

## 확인 {#verify}

1. 초대 이메일과 함께 고객을 생성합니다. 새 계정은 몇 초 내에 목록 최상단에 나타납니다.
2. **Balance** 기준으로 정렬: 정렬은 모든 고객을 대상으로 합니다.
3. 고객 잠금: 상태 태그가 *Locked*로 변경되며 고객은 더 이상 로그인할 수 없습니다. 잠금을 해제할 수 있습니다.

## 한도 및 참고 사항 {#limits-notes}

- 국가 열은 IP를 기반으로 한 참고용이며 거주지의 증거가 아닙니다. 사설 주소나 알 수 없는 주소는 국가가 표시되지 않습니다.
- 계정을 잠그더라도 아무것도 환불되지 않으며, 중지 작업을 함께 선택하지 않는 한 VM이 삭제되지 않습니다.
- 계정 잠금을 해제해도 관리자가 잠근 VM은 자동으로 잠금 해제되지 않으며, VM 페이지에서 개별적으로 열어야 합니다.

## Troubleshooting {#troubleshooting}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| "고객에게 활성 서비스가 남아 있습니다 ... 먼저 중지/삭제하세요" | 고객에게 서비스 또는 S3 계정이 있습니다 | 제거한 후 소프트 삭제하세요. |
| 삭제 승인에 "N VMs alive"라고 표시됨 | 동일한 사유 | VM을 먼저 삭제하세요. |
| "e-mail queued" 대신 재설정 링크가 표시됨 | SMTP가 설정되지 않음 | 이메일을 설정하거나 링크를 직접 보내세요. |
| 로그인 수단을 제거할 수 없음 (`last_login_method`) | 고객의 유일한 로그인 수단입니다 | 다른 수단을 먼저 추가하세요. |
| 잠금이 선불 서비스를 중지하지 않음 | 중지 오류가 보고되었습니다 | 잠금 후 메시지를 확인하세요. 시스템이 자동으로 중지를 재시도합니다. |
| 이전을 생성할 수 없음 | 미납 청구서, 실행 중인 작업, 다른 사이트의 수신자 또는 미인증 상태 | 문제를 해결하고 다시 시도하세요. |


---

<!-- source: https://nexcmp.com/ko/docs/customers/login-as/ -->

# 고객으로 로그인 {#log-in-as-a-customer}

> **관리자 위치:** Customers › Customers › List › a customer › header button **Impersonate**(`/customers/<id>`).

## 작동 내용 {#what-it-does}

**Impersonate**(로그인 대행) 기능을 사용하면 지원 관리자가 고객의 시점에서 포털을 정확히 확인하여 문제를 재현하거나 주문을 도울 수 있습니다. 세션은 1시간 동안 지속되며 일반 세션과 명확히 구분됩니다. 계정에 대한 지속적인 접근을 부여할 수 있는 모든 작업은 차단되며, 모든 사용 내역은 기록됩니다.

## 요구 사항 {#requirements}

| 항목 | 요구 사항 |
|---|---|
| 역할 | 관리 콘솔에 로그인한 관리자. |
| Customer | 계정은 반드시 **활성** 상태여야 합니다. 잠기거나 삭제된 계정은 "계정이 활성화되지 않았습니다"(HTTP 409)를 반환합니다. |
| 사유 | 사유는 필수이며 감사 로그에 기록됩니다. |
| 브라우저 | 관리자 주소에 대한 팝업을 허용하세요. 포털이 새 창으로 열립니다. |

## 단계 {#steps}

1. **Customers › List**를 열고 고객을 클릭합니다.
2. **Impersonate**를 클릭합니다. 고객의 사이트가 1시간 동안 고객 권한으로 열리며 모든 작업이 감사된다는 내용의 대화상자가 표시됩니다.
3. **사유**(예: "티켓 1234 — VM을 생성할 수 없음")를 입력하고 **Open app**을 클릭합니다.
4. 고객의 사이트에 `?impersonated=1`이(가) 포함된 대시보드가 새 창으로 열립니다. 브라우저에서 창을 차단한 경우 팝업을 허용하고 다시 클릭하세요.

![사유 필드가 채워진 Impersonate 대화상자](https://nexcmp.com/ko/docs/images/customers/login-as-01-dialog.webp)

리셀러의 고객인 경우, 링크는 고객의 자체 사이트에서만 작동하므로 창은 **리셀러의 고유 도메인**에서 열립니다.

## 동작 방식 {#how-it-works}

1. 관리자 작업은 1시간 동안 유효한 **일회용 토큰**을 생성하고 감사 로그에 `customer.login_as`(관리자, IP, 사유, 사이트)을 기록합니다.
2. 새 창이 `https://<site>/v1/portal/impersonate/<token>`(으)로 열립니다. 첫 번째 요청은 작은 페이지만 표시하고 토큰을 소모하지 **않으며**(브라우저 프리페칭으로 인해 토큰이 소모되는 것 방지), 이후 페이지가 POST로 확인합니다.
3. POST 요청 시 토큰이 소모됩니다. 두 번째로 사용하거나 1시간 후에 사용하는 경우 "가장(Impersonation) 링크가 만료되었거나 이미 사용되었습니다"라는 메시지가 반환됩니다.
4. NexCMP는 **1시간** 동안 지속되는 고객 세션을 생성하고(일반 세션은 30일 지속), 로그인 방법 `impersonate`(으)로 로그인 항목을 기록하며, `customer.login_as.used`을(를) 로그에 남깁니다.
5. 이 토큰은 고객의 자체 사이트에서만 작동하며, 다른 호스트에서는 404를 반환합니다.

## 대리 로그인 세션에서 차단되는 작업 {#what-is-blocked-in-an-impersonated-session}

1시간을 초과하는 권한을 부여하거나 고객의 보안을 변경하는 모든 작업은 HTTP 403 `impersonate_forbidden` 오류를 반환합니다.

| 차단됨 | 이유 |
|---|---|
| 비밀번호, TOTP 변경, Google/GitHub 연동 또는 해제, 패스키 편집 | 고객 본인의 자격 증명 |
| 계정 삭제 | 복구 불가 |
| **API keys** 생성 또는 편집 | 장기 지속 액세스 |
| CLI, 데스크톱 또는 MCP 로그인 승인 (디바이스 링크) | 장기 지속 액세스 |
| Kubernetes 액세스, S3 keys, SSH keys, 루트 비밀번호, 콘솔 공유 링크, VPN 또는 프록시 자격 증명 생성 | 세션 종료 후에도 유지되는 보안 정보 |
| 충전 코드 사용 | 금전 관련 캠페인 |
| 제휴 수수료 인출 또는 정산 변경 | 시스템 외부로 자금 유출 |
| AI keys, 예산 또는 알림 e-mail 편집 | 고객 설정 |

그 외의 모든 기능은 정상 작동합니다. 페이지 조회, VM 생성 및 관리, 주문 등을 수행할 수 있습니다. 작업은 고객의 신원과 잔액으로 실행되며, 관리자가 세션 배후에 있었다는 사실은 앞서 언급한 감사 로그에 기록됩니다.

## 확인 {#verify}

1. 테스트 고객으로 대리 로그인합니다. 포털이 열리며 해당 고객의 데이터가 표시됩니다.
2. 비밀번호 변경을 시도하면 "forbidden" (대리 로그인) 오류가 발생합니다.
3. **System › Logs › Admin actions**에서 관리자 이름, 사유, 사이트가 포함된 `customer.login_as` 항목과 그 뒤의 `customer.login_as.used` 항목을 확인합니다.
4. 창을 닫고 동일한 링크를 다시 열면 "link expired or already used" 메시지가 표시됩니다.

## 한도 및 참고 사항 {#limits-notes}

- 1시간 제한은 고정되어 있습니다 (3600초). 계속하려면 다시 대리 로그인하세요.
- 조회 및 재현 위주로 진행하고, 고객의 요청이 없는 한 비용이 발생하는 작업은 피하세요.
- 고객 페이지의 **Revoke sessions**을 사용하여 세션을 조기에 취소하세요 (고객 세션도 함께 로그아웃됩니다).
- 리셀러는 리셀러 메뉴에서 자체 **Sign in to partner console** 대리 로그인(60분)을 사용할 수 있습니다. [Resellers](https://nexcmp.com/ko/docs/customers/resellers/)를 참조하세요.

## Troubleshooting {#troubleshooting}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| "계정이 활성화되지 않았습니다" | 계정 잠김 또는 삭제됨 | 먼저 잠금을 해제하거나 고객 페이지를 직접 확인하세요. |
| 브라우저에서 창 차단 | 팝업 차단기 | 관리자 주소에 대한 팝업을 허용하고 다시 시도하세요. |
| "링크가 만료되었거나 이미 사용되었습니다" | 1시간 제한 초과 또는 재사용 | 다시 대리 로그인하세요. |
| "Not found" 열림 | 잘못된 호스트에서 링크가 사용됨 | 대화상자가 연 창을 사용하고, 다른 곳에 링크를 붙여넣지 마세요. |
| 작업 중 "forbidden" 오류 발생 | 대리 로그인 세션에서 차단됨 | 고객에게 직접 요청하거나 관리자 화면을 사용하세요. |


---

<!-- source: https://nexcmp.com/ko/docs/customers/resellers/ -->

# 리셀러 (화이트라벨) {#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.<your-domain>`의 **파트너 콘솔**에서 비즈니스를 운영합니다.

## 요구 사항 {#requirements}

| 항목 | 요구 사항 |
|---|---|
| 라이선스 | 커스텀 리셀러 도메인마다 라이선스에 **리셀러 도메인 슬롯** 1개가 필요합니다. 라이선스 페이지에 `used/max` 슬롯과 추가 구매 링크가 표시됩니다. 여유 슬롯이 없으면 도메인 추가 시 "Out of license reseller domain slots" 오류와 함께 실패합니다. |
| DNS | 각 리셀러 도메인은 귀하의 서버를 가리키도록 설정해야 합니다(아래 참조). |
| 웹 서버 및 TLS | 해당 호스트 이름의 유효한 인증서가 있는 리버스 프록시를 통해 호스트 이름이 NexCMP 패널에 연결될 수 있어야 합니다. |
| 이메일 | 초대 및 알림 이메일을 위한 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` | 리셀러의 A 레코드가 가리켜야 하는 공인 IPv4. |
   | `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. 리버스 프록시가 리셀러 호스트 이름을 NexCMP 패널로 전달하고 각각에 대한 인증서를 제공하는지 확인하세요. 설치 프로그램은 메인 도메인(및 해결되는 `admin.` 및 `partner.` 이름)에 대해서만 nginx와 Let's Encrypt를 구성합니다. Cloudflare를 사용하는 경우 호스트 이름을 프록시하고 Full SSL 모드를 사용하세요.

## NexCMP에서 연결 {#connect-in-nexcmp}

### 리셀러 생성 {#create-the-reseller}

1. **Customers › Resellers › List**를 열고 **New reseller**를 클릭합니다. 마법사는 8단계로 구성되어 있으며 마지막에 모든 항목을 프로비저닝합니다. 각 단계는 안전하게 다시 시도할 수 있습니다.

   | 단계 | 입력 내용 |
   |---|---|
   | **Reseller** | 법인명 또는 상호, **슬러그**(4~31자의 a~z, 0~9 또는 `-`, 문자로 시작하며 인프라 접두사로도 사용됨), 담당자 이름, 이메일 및 전화번호, 기본 언어, 리셀러의 결제 세부 정보 (크레딧 충전 구매자 기준). |
   | **Console account** | 사용자 이름, 계정 이메일, 전체 이름; **이메일로 일회용 초대 링크 전송**(72시간 유효, 권장) 또는 임시 비밀번호 1회 표시. |
   | **Brand** | 브랜드 이름, 단축 이름, 태그라인, 기본 색상, 지원 이메일 및 전화번호, 고객 인쇄용 인보이스에 표시되는 판매자 이름, 로고(밝은 배경 및 어두운 배경), 정사각형 마크 및 파비콘: PNG, JPEG, WEBP 또는 ICO(최대 256 KB, **SVG 불가**). |
   | **Domains** | **또한 www**가 포함된 고객 도메인, 기본 도메인, **테스트 도메인**(sslip.io) 및 **dry-run** 옵션 또는 플랫폼 서브도메인. 마법사는 **DNS OK / DNS not ready** 및 생성해야 할 레코드를 표시합니다. |
   | **Pricing & wallet** | 도매 할인율(%), 리테일 하한선(리스트 가격의 %), 기본 마크업(%), 크레딧 한도, 초기 잔액, 잔액 부족 알림, 고객·VM·도메인 한도, 사이트 기능(고객 가입, DDoS 보호, 지원 티켓, 커스텀 플랜, 리사이즈, Auto Scaling)입니다. |
   | **Payment channels** | 고객 결제 수금 주체(아래 참고) 및 선택 사항인 자체 PayPal 및 자체 베트남 은행 송금입니다. |
   | **Email** | 발신자 이름 및 회신 주소(Reply-To). From 주소는 리셀러 도메인용 DKIM이 설정될 때까지 플랫폼 주소로 유지됩니다. |
   | **Review** | 모든 내용을 확인한 후 **Provision everything**을 클릭하거나 **Save draft (provision later)**를 선택하세요. |

2. 프로비저닝은 백그라운드에서 계속 진행됩니다(30초마다). 리셀러를 열어 진행 상황을 확인하고, 단계가 실패한 경우 **Continue provisioning** 또는 **Retry**를 사용하세요.

![예시 값이 입력된 첫 번째 단계의 새 리셀러 마법사](https://nexcmp.com/ko/docs/images/customers/resellers-01-wizard.webp)

### DNS 지정(리셀러가 수행) {#point-dns-the-reseller-does-this}

리셀러(또는 귀하)는 **Domains & SSL** 탭에 표시된 레코드를 생성합니다.

| Record | Name | 값 |
|---|---|---|
| TXT (소유권 확인, 최초 1회만) | `_site-verify.<domain>` | `sv=<token>` 화면에 표시됨 |
| A (`shop.example.net` 등 루트 도메인) | the domain | your `rs_server_ipv4` |
| CNAME (`cloud.example.net` 등 하위 도메인) | the domain | your `rs_cname_target` (또는 `rs_server_ipv4`에 대한 A 레코드) |
| CNAME (선택 사항) | `www.<domain>` | your `rs_cname_target` |

추가 사항:

- 서버가 해당 IPv6 주소로 응답하지 않는 한 모든 **AAAA** (IPv6) 레코드를 제거하세요.
- 도메인이 인증되는 동안 CDN 프록시를 **꺼짐**(회색 구름)으로 설정하세요.
- 도메인에 **CAA** 레코드가 있는 경우 `letsencrypt.org`을(를) 허용하세요.

TXT 레코드의 토큰은 도메인마다 다르므로 화면에서 복사해야 합니다. 시스템은 처음 48시간 동안은 5분마다, 이후에는 매시간 DNS를 재확인하며, 72시간이 지나도 TXT 레코드가 누락된 도메인은 해제합니다.

### 도메인 상태 {#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`)은 리셀러당 한 행으로 구성된 매트릭스이며, 도매 **할인율**(discount), **마크업**(markup) 및 서비스별 스위치(예: DDoS Shield 및 VPN)가 포함됩니다. 스위치는 플랫폼 전체 기능이 켜져 있을 때 편집할 수 있으며, 그렇지 않은 경우 셀이 읽기 전용으로 표시되고 설정으로 연결됩니다. **Top-up codes** 하위 탭에서는 각 리셀러가 월에 발행할 수 있는 코드 수를 설정합니다 ([Promotions](https://nexcmp.com/ko/docs/billing/promotions/) 참조).

가격 규칙:

- 도매가 = 정가 x (1 - 할인율)이며, 리셀러의 **Wholesale pricing** 탭에서 플랜별 및 결제 주기별로 재정의할 수 있습니다.
- 리셀러가 소매가를 설정하며 **최저 기준**(정가의 백분율) 아래로 내려갈 수 없습니다.
- 고객이 구매할 때 리셀러의 **지갑(wallet)**에서 도매가가 결제됩니다. 지갑에는 크레딧 한도, 유예 기간 및 초과 한도가 적용됩니다 (Defaults 참조).

## 기본값 {#defaults}

**Customers › Resellers › Defaults**(`/resellers/settings`)는 모든 리셀러에게 적용되는 `rs_*` 키입니다. 변경할 때마다 사유를 묻고 감사(audit) 기록이 남습니다.

| 그룹 | 키 | Default | 의미 |
|---|---|---|---|
| General | `rs_enabled` | 1 | 리셀러 프로그램 사용. |
| | `rs_platform_collect_enabled` | 0 | 플랫폼이 리셀러를 대신하여 고객 결제를 수금할 수 있도록 허용합니다. **법적 검토 후에만 활성화하세요.** |
| | `rs_totp_required` | 1 | 리셀러 콘솔 계정은 2단계 인증을 사용해야 합니다. |
| | `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` | 비어 있음 | 리셀러 이메일의 보낸 사람 주소. |
| | `rs_invoice_show_processor` | 1 | 인보이스에 결제 대행사를 표시합니다. |
| | `rs_gw_stripe_enabled`, `rs_gw_usdt_enabled` | 1 | 리셀러가 자체 Stripe 또는 USDT를 구성할 수 있는지 여부. |

## 고객 결제 수금 주체 {#who-collects-customer-payments}

| 모드 | 의미 |
|---|---|
| **리셀러 수금 (자체 채널)** — 기본값 | 리셀러가 자체 Stripe, PayPal, USDT 또는 은행 계좌를 연결합니다. 웹훅은 `https://<reseller-domain>/v1/billing/<gateway>/webhook/r/<id>`입니다. 저장된 카드 및 [auto top-up](https://nexcmp.com/ko/docs/billing/auto-top-up/)은 이러한 사이트에서 사용할 수 없습니다. |
| **플랫폼 수금** | 귀하의 채널이 리셀러 사이트에 표시됩니다. `rs_platform_collect_enabled = 1`까지 잠겨 있습니다. |
| **혼합** | 채널별로 선택하는 조합. |

## 리셀러에게 표시되는 내용 {#what-the-reseller-sees}

`https://partner.<your-domain>`의 파트너 콘솔에는 개요, 보고서, 고객, VM, 티켓, 주문, 결제, 가격, 브랜드, 랜딩 및 법률, 도메인 및 SSL, 이메일, 지갑, 결제 채널이 있습니다. 콘솔 계정은 *reseller* (전체) 또는 *staff* (읽기 전용) 역할을 가집니다. 직접 확인하려면 리셀러를 열고 **Sign in to partner console**을 클릭하세요. 60분 동안 진입하며, 모든 쓰기 작업은 관리자 로그와 리셀러 로그 모두에 이름과 함께 기록되고, 자금 관련 작업은 두 번째 확인이 필요합니다.

## 확인 {#verify}

1. 프로비저닝 후 리셀러의 목록 행에 *active*와 녹색 **Provisioning** 열이 표시됩니다.
2. 브라우저에서 리셀러의 도메인을 엽니다. 리셀러 고유의 브랜드가 적용된 로그인 페이지가 나타납니다. `https://<reseller-domain>/admin`은(는) 404를 반환합니다.
3. 해당 도메인에서 테스트 고객으로 가입합니다. **Customers › List**에서 **Site** 열에 리셀러가 표시된 고객을 확인할 수 있습니다.
4. 라이선스 페이지에 사용 중인 슬롯이 1개 늘어난 것으로 표시됩니다.

## 한도 및 참고 사항 {#limits-notes}

- 커스텀 또는 테스트 도메인당 1개의 라이선스 슬롯이 사용되며, 플랫폼 서브도메인은 슬롯을 소모하지 않습니다.
- 리셀러를 일시 중단해도 데이터는 유지되며, **Close reseller**는 모든 도메인 슬롯을 반환하고 VM 삭제는 보존 기간이 지난 후에만 허용됩니다.
- 리셀러의 고객은 내 고객 목록에 표시되며 다른 고객과 마찬가지로 가장하여 로그인할 수 있습니다(링크는 리셀러의 도메인에서 열림).
- 리셀러는 나의 결제 채널, 기본 할당량 또는 다른 리셀러를 보거나 변경할 수 없습니다.

## Troubleshooting {#troubleshooting}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| "라이센스 리셀러 도메인 슬롯 초과" | 모든 슬롯 사용됨 | 슬롯을 확보(도메인 제거)하거나 라이선스 페이지에서 추가로 구매하세요. |
| `pending_verify` 상태인 도메인 | TXT 레코드 누락 | 표시된 대로 정확히 TXT 레코드를 생성하고 **Check now**을(를) 사용하세요. |
| `pending_dns` 상태인 도메인 | A/CNAME이 본인을 가리키지 않거나, AAAA 레코드가 있거나, CDN 프록시가 켜져 있음 | DNS를 수정하고 프록시를 끈 다음 **Check now**을(를) 클릭하세요. |
| `error` 상태 | 행의 코드 확인(예: Let's Encrypt를 차단하는 CAA, 속도 제한) | 문제를 해결하고 **Retry**을(를) 클릭하세요. |
| 브라우저에 알 수 없는 호스트 또는 "421" 오류가 표시됨 | 호스트 이름이 라이선스에 없거나 패널로 라우팅되지 않음 | 리셀러를 통해 도메인을 추가하고(슬롯 소모) 리버스 프록시를 수정하세요. |
| 지침에 잘못된 IP 또는 호스트가 표시됨 | `rs_server_ipv4` / `rs_cname_target`에 여전히 샘플 값이 있음 | Defaults에서 설정하세요. |
| 리셀러가 플랫폼 수금을 활성화할 수 없음 | 잠김 | 법적 검토 후 `rs_platform_collect_enabled`을(를) 설정하세요. |




---

<!-- source: https://nexcmp.com/ko/docs/customers/branding/ -->

# 브랜딩 {#branding}

> **Where in the admin:** System › Settings › Brand (`/settings/branding`). 관련 항목: URL 및 송장에 인쇄되는 판매자 세부 정보를 위한 System › Settings › General (`/settings`).

## 작동 내용 {#what-it-does}

NexCMP는 화이트라벨 솔루션입니다. 제품에 공급업체 이름이 표시되지 않으며 고객이 보는 모든 것은 **귀사**의 브랜드입니다. 브랜드 설정은 로그인 및 가입 페이지, 포털, 관리자 콘솔, 이메일에 적용됩니다.

## 요구 사항 {#requirements}

| 항목 | 요구 사항 |
|---|---|
| 역할 | 관리자. |
| 파일 | 로고: SVG, PNG, JPEG, WEBP 또는 ICO, **각 최대 512 KB**. |
| 의존성 | 없음. |

## 단계 {#steps}

1. **System › Settings › Brand**을(를) 엽니다.
2. **Identity** 카드에서 다음을 입력합니다:

   | 필드 | 참고 |
   |---|---|
   | **Brand name** (필수) | 최대 60자. 포털, 이메일, 송장, 법적 페이지에 표시됩니다. |
   | **인보이스상의 판매자 이름** | 최대 120자. 비워두면 브랜드 이름이 사용됩니다. |
   | **Brand color** | `#rrggbb` 색상 값. 필드 옆의 작은 버튼을 누르면 기본 제공 색상으로 재설정됩니다. |
   | **Site currency** | **USD**: 가격과 잔액은 통화 전환 없이 USD로만 표시됩니다. **VND**: 저장된 환율로 변환된 금액도 함께 표시됩니다([Currency and exchange rates](https://nexcmp.com/ko/docs/catalog/currency-and-exchange-rates/) 참조). |

3. **Save**를 클릭합니다.
4. **Logo & favicon** 카드에서 **Upload**(또는 **Replace**)를 사용하여 **Logo (light background)**, **Logo (dark background)**, **Favicon** 이미지 3장을 업로드합니다. **Remove**를 누르면 개별 이미지가 삭제됩니다.

![식별 필드와 업로드된 이미지 3장이 포함된 Brand 페이지](https://nexcmp.com/ko/docs/images/customers/branding-01-brand.webp)

### General의 관련 설정 {#related-settings-in-general}

**System › Settings › General**에는 전체 설정을 완성하는 두 개의 탭이 있습니다:

| 탭 | 필드 |
|---|---|
| **Branding & URLs** | 브랜드명(이메일, 인보이스), 기본 언어(영어 또는 베트남어), **Customer app URL**, **Console URL**, **Admin URL**(리셀러 대행 링크), **Partner console URL**(초대 링크, 리셀러 이메일). 설치 마법사는 이를 `https://<domain>`, `https://<domain>/admin`, `https://<domain>/console`(으)로 채웁니다. |
| **Seller & invoicing** | 법인명, 사업자 등록번호, 주소, 연락처 이메일, 인보이스 번호 접두사. [Invoices and ledger](https://nexcmp.com/ko/docs/billing/invoices-and-ledger/)를 참조하십시오. |

이메일의 **From name**은 **System › Settings › Email**([SMTP and e-mails](https://nexcmp.com/ko/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. 브라우저 탭에서 파비콘을 확인합니다(브라우저는 파비콘을 캐시하므로, 여전히 이전 파비콘이 보이면 캐시를 지우고 새로고침하세요).
3. 테스트 이메일을 트리거하고(예: 테스트 고객을 위한 **Send reset link**) 제목과 바닥글의 브랜드명을 확인합니다.

## 한도 및 참고 사항 {#limits-notes}

- 어두운 배경용 로고는 고객 또는 관리자가 다크 테마로 전환할 때 사용됩니다.
- 리셀러는 자신만의 브랜드를 가지며, 256 KB 이하의 PNG, JPEG, WEBP, ICO 파일을 업로드할 수 있습니다(SVG 불가). [Resellers](https://nexcmp.com/ko/docs/customers/resellers/)를 참조하십시오.
- 브랜드 색상이나 로고 변경 사항은 다음 페이지 로드 시 반영되며, 이미 발송된 이메일은 변경되지 않습니다.

## Troubleshooting {#troubleshooting}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| 업로드 거부됨: `svg_unsafe` | SVG에 스크립트, 링크 또는 외부 참조가 포함되어 있습니다. | 스크립트와 외부 이미지가 없는 순수 SVG를 내보내거나 PNG를 사용하세요. |
| `asset_too_large` | 파일 용량이 512 KB를 초과함 | 이미지를 압축하거나 크기를 조정하세요. |
| `asset_type` | SVG, PNG, JPEG, WEBP, ICO 형식이 아님 | 파일 형식을 변환하세요. |
| `invalid_argument: primary` | 색상이 `#rrggbb`이(가) 아님 | 6자리 1진 색상 코드를 사용하세요. |
| 이전 로고가 계속 표시됨 | 브라우저 캐시 | 강력 새로고침을 수행하세요. 파비콘은 적용되는 데 시간이 더 걸릴 수 있습니다. |
| 가격이 USD로만 표시됨 | 사이트 통화가 USD로 설정됨 | VND로 전환하고 환율이 저장되어 있는지 확인하세요. |


---

<!-- source: https://nexcmp.com/ko/docs/customers/legal/ -->

# 법적 문서 페이지 {#legal-pages}

> **관리자 위치:** System › Settings › Legal (`/settings/legal`). **고객 노출 위치:** 회원가입 및 결제 페이지에서 링크되는 `https://<your-domain>/terms` 및 `/privacy`.

## 작동 내용 {#what-it-does}

설치 시 **Terms of Service** 및 **Privacy Policy**의 두 페이지가 게시됩니다. 직접 작성하기 전까지 NexCMP는 소프트웨어 공급업체를 언급하지 않고 특정 서비스를 약속하지 않는 **중립적인 기본 텍스트**를 표시합니다. 판매를 시작하기 전에 변호사의 검토를 거친 텍스트로 교체하세요.

## 요구 사항 {#requirements}

| 항목 | 요구 사항 |
|---|---|
| 역할 | 관리자. |
| 내용 | 일반 마크다운, 페이지 및 언어당 최대 **50 KB**. |
| 의존성 | 브랜드 이름 및 판매자 세부 정보([Branding](https://nexcmp.com/ko/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**를 클릭하고 저장합니다.

![기본 텍스트를 시작점으로 표시하는 Terms of Service 카드가 있는 Legal 설정](https://nexcmp.com/ko/docs/images/customers/legal-01-terms.webp)

## 기본 페이지의 내용 {#what-the-default-pages-contain}

기본 텍스트는 제품 내에 `legal_default.json`(으)로 저장되며 브랜드 이름, 판매자 이름, 사이트 URL 및 문의 이메일(System › Settings › General 아래 **Seller & invoicing**에서 가져옴; 이메일이 설정되지 않은 경우 지원 팀을 가리킴)로 채워집니다.

| 페이지 | 섹션 |
|---|---|
| **Terms of Service** | 1 서비스 · 2 계정 및 인증 · 3 가격 및 청구 · 4 환불 · 5 귀하의 데이터 · 6 허용된 이용 · 7 가용성 및 지원 · 8 정지 및 해지 · 9 책임 · 10 변경 및 준거법(판매자의 사업장 소재지 법률) |
| **Privacy Policy** | 1 수집하는 정보 · 2 이용 목적 · 3 쿠키 및 로컬 스토리지 · 4 제3자 제공 · 5 보유 기간 · 6 이용자의 권리 · 7 문의 |

::: warning 법적 자문 아님
기본 텍스트는 중립적인 템플릿입니다. 실제 고객에게 사용하기 전에 특히 환불, 책임 및 준거법에 관한 섹션을 검토받으시기 바랍니다.
:::

## 마크다운 규칙 {#markdown-rules}

- 지원되는 항목: 제목(`# 1. Title`), 단락, 글머리 기호 및 번호 매기기 목록, **굵은 글씨**, 링크 `[text](https://example.com)`.
- 링크는 `http://` 또는 `https://`(으)로 시작해야 합니다.
- **원시 HTML은 거부됩니다** (모든 `<tag>`, `<!--`, `<?`): 오류 `html_not_allowed`.
- `javascript:`, `data:` 또는 `vbscript:`가 포함된 링크는 거부됩니다: 오류 `unsafe_link`.
- 줄바꿈 및 탭을 제외한 제어 문자는 거부됩니다: `invalid_chars`. 50 KB 초과: `too_large`.
- 포털에서 텍스트를 직접 렌더링하며, `http(s)` 링크만 클릭할 수 있고 나머지는 모두 일반 텍스트입니다.

## 언어 동작 {#language-behaviour}

- 고객은 작성된 언어로 자신의 언어를 봅니다. 영어와 베트남어만 존재하며, 다른 포털 언어는 영어 버전으로 표시됩니다.
- **English**만 작성한 경우, 베트남어(또는 기타 언어)를 선택한 고객은 기본값이 아니라 작성한 영어 텍스트를 보게 됩니다.
- 둘 다 작성하지 않은 경우 해당 언어의 기본 텍스트가 사용됩니다.

## 확인 {#verify}

1. 저장 후 시크릿 창에서 `https://<your-domain>/terms`을(를) 엽니다. "Terms of Service — [brand]" 제목 아래에 텍스트가 표시됩니다.
2. 카드의 태그가 *Using your text*로 변경됩니다.
3. `/privacy`을(를) 열고 연락처 이메일을 확인합니다.

## 한도 및 참고 사항 {#limits-notes}

- 설치된 제품에는 `terms` 및 `privacy`만 존재합니다. 원래 플랫폼의 다른 페이지(이용약관, 환불 정책 등)는 이 에디션에 포함되지 않으며, `/aup` 및 `/refund` 요청은 약관으로 리디렉션됩니다.
- 리셀러는 파트너 콘솔(**Landing & legal**)에서 자체 법적 페이지를 작성할 수 있습니다. [Resellers](https://nexcmp.com/ko/docs/customers/resellers/)을(를) 참조하세요.
- 텍스트를 변경해도 기존 고객에게 동의를 다시 요청하지 않습니다.

## Troubleshooting {#troubleshooting}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| 저장 거부됨: `html_not_allowed` | 텍스트 내 HTML 태그 | 태그를 제거하고 마크다운을 사용하세요. |
| 저장 거부됨: `unsafe_link` | `javascript:`, `data:` 또는 `vbscript:` 링크 | `https://` 링크를 사용하세요. |
| 저장 거부됨: `too_large` | 50 KB 초과 | 텍스트를 줄이세요. |
| 베트남어가 작성되어 있는데 고객에게는 영어로 표시됨 | 베트남어 탭이 비어 있음 | 베트남어 텍스트를 작성하거나 붙여넣으세요. |


---

<!-- source: https://nexcmp.com/ko/docs/portal/overview/ -->

# 고객 포털 개요 {#customer-portal-overview}

> **포털 위치:** `https://<your-domain>/` — 고객은 `/login`에서 로그인합니다. 관리자는 `/admin`를 사용하며, 관리자 계정인 경우 동일한 로그인으로 양쪽 모두 열립니다.

포털은 고객이 매일 사용하는 공간입니다. 이름, 로고 및 색상으로 브랜딩되며([Branding](https://nexcmp.com/ko/docs/customers/branding/)), 활성화한 서비스만 표시됩니다([Modules](https://nexcmp.com/ko/docs/infrastructure/modules/)).

## 대시보드 {#the-dashboard}

로그인 후 **Dashboard**에 다음이 표시됩니다.

| 블록 | 의미 |
|---|---|
| 지갑 잔액 | 현재 크레딧 및 현재 소모율 기준으로 지속 가능한 예상 일수 |
| 이번 달 지출 | 현재까지의 청구 금액 및 월말 예상치 |
| 가상 머신 | 상태, IP, CPU 및 RAM, 빠른 작업(콘솔, 재시작)이 포함된 각 VM |
| 대역폭 | 1시간, 6시간, 24시간, 7일, 30일 동안의 인바운드/아웃바운드 트래픽 |
| 최근 활동 | 계정의 최신 이벤트 |
| 빠른 시작 | 체크리스트: VM 생성, SSH 키 추가, 충전, 자동 충전 활성화, 이메일 확인 |

![지갑 잔액, 지출 예측, 실행 중인 가상 머신 및 빠른 시작 체크리스트가 있는 고객 대시보드](https://nexcmp.com/ko/docs/images/portal/overview-01-dashboard.webp)

## 탐색 {#navigation}

메뉴는 서비스를 유형별로 그룹화합니다. 비활성화했거나 소스가 연결되지 않은 서비스는 표시되지 않습니다.

| 영역 | 페이지 |
|---|---|
| Instances | [Virtual machines](https://nexcmp.com/ko/docs/portal/virtual-machines/) 및 상세 페이지 |
| 배포 | [Ordering](https://nexcmp.com/ko/docs/portal/ordering/) — 리소스 생성 |
| 스토리지 | 활성화된 경우 스냅샷, 백업 및 볼륨 — [Snapshots](https://nexcmp.com/ko/docs/portal/snapshots/) |
| 결제 | [Wallet and top-ups](https://nexcmp.com/ko/docs/portal/sign-up-and-wallet/), 송장, 주문, 할당량 |
| 계정 | 프로필, 로그인 및 보안, 환경 설정, 자동 충전 |
| 지원 | 채팅 위젯 및 티켓 — [Support](https://nexcmp.com/ko/docs/portal/support/) |
| API 문서 | `/apidoc` — [API](https://nexcmp.com/ko/docs/developers/api/) |

## 계정 {#account}

**Account**에는 **Profile** (이름, 이메일, 고객 ID, 계정 삭제 요청), **Sign-in & security** (비밀번호, 패스키, 연동된 Google/GitHub), **Preferences** (언어, 표시 통화), **Auto top-up** ([Auto top-up](https://nexcmp.com/ko/docs/billing/auto-top-up/))의 4개 탭이 있습니다.

고객은 계정을 직접 삭제할 수 없습니다. **Request account deletion**을 누르면 모든 가상 머신이 삭제된 후 운영자가 요청을 검토하며 (Customers › Deletion requests), 대기 중인 동안 고객이 철회할 수 있습니다.

## 언어 및 통화 {#language-and-currency}

포털은 16개 언어로 제공되며 언어에 따라 선택된 표시 통화로 가격을 표시합니다. [Currency and exchange rates](https://nexcmp.com/ko/docs/catalog/currency-and-exchange-rates/)를 참조하세요. 고객은 **Preferences**에서 둘 다 전환할 수 있습니다.

## 고객 할당량 {#customer-quotas}

**Billing › Quotas**는 결제한 내용을 바탕으로 고객이 사용할 수 있는 각 리소스(CPU, 메모리, 스토리지, IP, VM)의 양을 보여줍니다. [Quotas](https://nexcmp.com/ko/docs/billing/quotas/)를 참조하세요.


---

<!-- source: https://nexcmp.com/ko/docs/portal/sign-up-and-wallet/ -->

# 가입, 지갑 및 충전 {#sign-up-wallet-and-top-up}

> **포털 내 위치:** `/register`, `/login`, Billing (`/billing`).

## 계정 생성 {#create-an-account}

1. 고객이 `https://<your-domain>/register`에 접속하여 이메일과 비밀번호(문자와 숫자 포함 10자 이상)를 입력하거나, 활성화한 경우 **Google**, **GitHub** 또는 **패스키**를 사용합니다 — [Security](https://nexcmp.com/ko/docs/administration/security/#customer-sign-in) 참조.
2. 캡차(captcha)가 활성화된 경우 이를 완료합니다.
3. [SMTP](https://nexcmp.com/ko/docs/administration/smtp-and-emails/)를 통해 인증 이메일이 발송됩니다. 판매 설정에 필요한 경우 VM을 생성하기 전에 인증이 필수입니다.

![이메일 및 비밀번호 필드가 있는 등록 페이지](https://nexcmp.com/ko/docs/images/portal/sign-up-and-wallet-01-register.webp)

::: tip
SMTP가 작동하지 않으면 고객이 이메일을 인증하거나 비밀번호를 재설정할 수 없습니다. [SMTP](https://nexcmp.com/ko/docs/administration/smtp-and-emails/)를 먼저 설정하세요.
:::

## 지갑 {#the-wallet}

모든 결제는 청구 통화의 **지갑** 잔액에서 이루어집니다. **Billing** 페이지에 표시되는 항목은 다음과 같습니다:

| 섹션 | 의미 |
|---|---|
| 지출 가능액 | 잔액 및 대기 중인 충전금 |
| 누적 요금 | 현재 주기 동안 소비된 시간별 서비스로, 아직 정산되지 않은 금액 |
| 미결제 잔액 | 지불해야 할 미납 금액 |
| 청구 내역 | **Invoice History**, **Payment Order**, **Ledger**, **Orders** 탭 |

![지출 가능액, 누적 요금 및 내역 탭이 표시된 Billing 페이지](https://nexcmp.com/ko/docs/images/portal/sign-up-and-wallet-02-billing.webp)

## 크레딧 추가 {#add-credit}

1. **Deposit**을 클릭합니다.
2. 금액을 입력합니다. 최소 금액은 [minimum top-up](https://nexcmp.com/ko/docs/billing/minimum-top-up/)입니다.
3. 결제 수단(카드, PayPal, USDT 또는 베트남 인터페이스의 경우 계좌 이체)을 선택합니다. 결제 수단은 [Payment channels](https://nexcmp.com/ko/docs/billing/payment-channels/)에서 활성화한 항목들입니다.
4. 결제합니다. 결제 제공업체가 확인하면 잔액이 업데이트됩니다.

저장된 카드, Stripe Link 및 PayPal은 재사용할 수 있으며 [auto top-up](https://nexcmp.com/ko/docs/billing/auto-top-up/)에 사용할 수 있습니다. [Saved payment methods](https://nexcmp.com/ko/docs/billing/saved-payment-methods/)를 참조하세요.

## 코드 사용 {#redeem-a-code}

**Redeem code**는 발행한 바우처(Finance › Billing › Vouchers)에서 크레딧을 추가하거나 프로모션 코드를 적용합니다 — [Promotions](https://nexcmp.com/ko/docs/billing/promotions/) 참조.

## 인보이스 {#invoices}

결제된 각 주문은 판매자 정보([General settings](https://nexcmp.com/ko/docs/administration/general-settings/))가 표시되는 인보이스를 생성합니다. 고객은 **Invoice History**에서 인보이스를 열어 브라우저에서 인쇄하거나 PDF로 저장할 수 있습니다.

## 시간당 과금 {#hourly-charges}

시간당 서비스는 리소스가 존재하는 동안 매시간 과금되며, 금액이 누적되어 1시간 미만의 금액은 $0.00으로 반올림될 수 있습니다. 잔액이 부족한 경우 과금 규칙에 따라 서비스가 일시 중지되고 고객에게 이메일로 안내됩니다 (`low_balance`).


---

<!-- source: https://nexcmp.com/ko/docs/portal/ordering/ -->

# 서비스 주문 {#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** — [zone](https://nexcmp.com/ko/docs/infrastructure/zones/). 가격과 포함된 트래픽은 리전에 따라 다를 수 있습니다.
3. **Plan** — 고정 플랜 (vCPU, RAM, NVMe 디스크, 시간당 가격) 또는 **Custom** (고객이 vCPU, RAM, 디스크를 직접 선택하며 리소스별로 가격 책정). 플랜은 [Plans](https://nexcmp.com/ko/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/ko/docs/images/portal/ordering-01-plan.webp)

![주문 페이지의 결제 주기 및 운영체제 단계](https://nexcmp.com/ko/docs/images/portal/ordering-02-cycle-os.webp)

## 주문 완료 {#placing-the-order}

요약 정보에 가격이 표시됩니다. 주문은 [quota check](https://nexcmp.com/ko/docs/billing/quotas/) 및 [minimum balance](https://nexcmp.com/ko/docs/billing/minimum-top-up/) 규칙을 거친 후 프로비저닝 전에 지갑에서 **과금**됩니다. VM은 대개 1분 이내에 *Running* 상태가 되며, 고객은 VM의 **Activity** 탭에서 배포 단계를 확인할 수 있고 초기 비밀번호(10분간 1회 조회 가능)가 포함된 "VM ready" 이메일을 받게 됩니다.

## 주문이 중단되는 원인 {#what-can-stop-an-order}

| 메시지 / 원인 | 해결 방법 |
|---|---|
| 잔액 부족 | 충전 — [Sign-up, wallet and top-up](https://nexcmp.com/ko/docs/portal/sign-up-and-wallet/) |
| 할당량 초과 | 할당량 상향 — [Quotas](https://nexcmp.com/ko/docs/billing/quotas/) |
| 이메일 미인증 | 고객의 이메일 인증 |
| 선택한 리전에 플랜 없음 | 해당 존에서 플랜 사용 가능하도록 설정 — [Plans](https://nexcmp.com/ko/docs/catalog/plans/) |
| 유효하지 않은 라이선스 | 고객이 새 서비스를 생성할 수 없음 — [License](https://nexcmp.com/ko/docs/getting-started/license-and-purchase/#if-the-license-is-not-valid) |


---

<!-- source: https://nexcmp.com/ko/docs/portal/virtual-machines/ -->

# 가상 머신 {#virtual-machines}

> **포털 위치:** Instances (`/vms`) 및 VM 페이지 (`/vms/<id>`).

**Instances**에는 고객의 VM 이름, OS, 상태, IP, 사양 및 비용이 표시됩니다. 항목을 클릭하면 해당 페이지가 열립니다.

## VM 페이지 {#the-vm-page}

탭: **Overview**, **Console**, **AI SSH Agent** (AI 모듈 활성화 시), **Monitoring**, **Storage**, **Network**, **Configuration**, **Billing**, **Activity**.

![상태, 사양, IP, 대역폭 차트, 작업 로그가 표시되는 가상 머신 개요](https://nexcmp.com/ko/docs/images/portal/virtual-machines-01-overview.webp)

### 작업 {#actions}

| 작업 | 효과 |
|---|---|
| 콘솔 | 브라우저 콘솔 열기 — [Console](https://nexcmp.com/ko/docs/portal/console/) |
| Restart / Stop / Force stop | 전원 제어 |
| 비밀번호 초기화 | 새 비밀번호를 생성하며 한 번만 표시됨 |
| OS 재설치 | 템플릿에서 다시 빌드하며 데이터가 손실됨 |
| IP 변경 | 공인 IP 교체 (소스가 지원하는 경우) |
| Auto Scaling 활성화 | 활성화 시 부하에 따라 CPU/RAM 확장 |
| 삭제 | VM을 제거하며 시간제 과금이 중단됨 |

### 표시되는 정보 {#information-shown}

가동 시간, 이번 달 비용, 실시간 사용량이 포함된 vCPU/RAM/디스크, 공인 및 사설 IP, 사용자 이름, 대역폭 차트, 작업 로그, 청구 요약(요금제, 주기, 시간, 잔여량).

::: info 필드는 소스에 따라 다름
VM 페이지에는 소스가 지원하는 항목만 표시됩니다. 예를 들어 Proxmox VE VM에는 포트 포워딩이나 IP 변경 기능이 없으며, OS 목록은 클러스터의 템플릿 세트를 따릅니다. [Proxmox VE](https://nexcmp.com/ko/docs/infrastructure/proxmox/)의 기능 표를 참고하세요.
:::

## Billing 탭 {#billing-tab}

요금제, 주기, 총 시간, 남은 시간 및 청구 로그를 표시합니다. 시간제 VM은 삭제될 때까지 요금이 누적됩니다. 고객은 **switch cycle**을 통해 할인된 가격으로 더 긴 기간을 선결제할 수 있습니다.

## 관리자용 {#for-administrators}

동일한 VM이 관리자 콘솔의 Services › Virtual Machines 아래에 표시되며, 여기서 고객을 대신해 작업을 수행하거나 고객으로 [log in as](https://nexcmp.com/ko/docs/customers/login-as/)할 수 있습니다.


---

<!-- source: https://nexcmp.com/ko/docs/portal/console/ -->

# 콘솔 {#console}

> **포털 위치:** VM 페이지 → **Console** 탭. **관리자 위치:** System › Admin › License & updates → modules (웹 SSH).

## 작동 내용 {#what-it-does}

**Console** 탭은 VM 내부 네트워크가 끊긴 경우에도 브라우저에서 VM으로의 그래픽(VNC) 세션을 엽니다. SSH 모듈이 활성화된 경우 두 번째 옵션으로 **웹 SSH** 터미널을 사용할 수 있습니다.

## 요구 사항 {#requirements}

| 항목 | VNC 콘솔 | 웹 SSH |
|---|---|---|
| CloudStack | 패널에서 접근 가능한 콘솔 프록시 VM(CPVM) — [CloudStack](https://nexcmp.com/ko/docs/infrastructure/cloudstack/) 참고 | VM에서 접근 가능한 SSH 포트 |
| Proxmox VE | 패널을 통한 작동 (Proxmox API를 통한 noVNC; TLS 지문 고정됨) — [Proxmox VE](https://nexcmp.com/ko/docs/infrastructure/proxmox/) 참고 | 동일 |
| 패널 | [General settings](https://nexcmp.com/ko/docs/administration/general-settings/)에 설정된 콘솔 URL | `ssh-proxy` service and module flag `feature_ssh_web`; 기본적으로 꺼져 있음 — [Modules](https://nexcmp.com/ko/docs/infrastructure/modules/) 참고 |

웹 SSH 모듈이 꺼져 있는 경우 탭에 **VNC only**가 표시됩니다.

## 사용 방법 {#use-it}

1. VM 열기 → **Console**.
2. **Console**(또는 **Open in new window**)을 클릭합니다. 단기 티켓이 발급되고 `https://<domain>/console`에서 콘솔이 열립니다.
3. VM의 사용자 이름과 비밀번호로 로그인합니다 (Overview 탭에 표시되며, 분실 시 재설정하세요).

![가상 머신의 Console 탭](https://nexcmp.com/ko/docs/images/portal/console-01-tab.webp)

## Troubleshooting {#troubleshooting}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| 즉시 "Disconnected" | 브라우저가 이전 콘솔 경로를 유지함 | 도메인의 사이트 데이터를 지우고 다시 시도 |
| 검은 화면 | VM이 중지되었거나 부팅 중임 | VM을 시작하고 대기 |
| CloudStack에서 콘솔이 열리지 않음 | 콘솔 프록시 VM이 실행 중이 아니거나 접근할 수 없음 | CloudStack에서 시스템 VM 확인 |
| SSH 옵션 없음 | Web SSH 모듈 꺼짐 | `ssh-proxy` 설치 후에만 활성화하세요 |


---

<!-- source: https://nexcmp.com/ko/docs/portal/snapshots/ -->

# Snapshots 및 backups {#snapshots-and-backups}

> **포털 위치:** Snapshots (`/snapshots`), Snapshot schedules (`/snapshots/schedules`), Backups (`/backups`). 관리자 패널에서 해당 기능이 활성화된 경우에만 표시됩니다.

## 작동 내용 {#what-it-does}

Snapshots는 VM 디스크의 상태를 저장하여 고객이 잘못된 변경 후 롤백할 수 있도록 합니다. Snapshots는 수동으로 생성하거나 일정에 따라 생성할 수 있습니다.

## 가용성 {#availability}

| Source | Snapshots | 참고 |
|---|---|---|
| CloudStack | 예 | 볼륨 스냅샷; 설정된 대로 과금되는 스토리지 |
| Proxmox VE | 예 | VM당 최대 **5개**; 생성, 목록 조회, 복구 및 삭제 |

스냅샷 기능이 켜져 있고 고객에게 이를 지원하는 소스의 VM이 있는 경우에만 메뉴 항목이 나타납니다.

## 사용 방법 {#use-it}

1. **Snapshots**을 열고 **Create**를 클릭한 후, VM을 선택하고 이름을 입력합니다.
2. 상태가 *ready*가 될 때까지 기다립니다.
3. 되돌리려면 스냅샷에서 **Restore**를 선택하고 확인하세요. VM이 해당 상태로 돌아갑니다(필요한 경우 재시작됨).
4. 더 이상 필요 없는 스냅샷을 삭제합니다.


::: warning
복구하면 스냅샷 이후에 기록된 모든 내용이 삭제됩니다. 보호된 VM은 포털에서 복구하거나 삭제할 수 없습니다.
:::




---

<!-- source: https://nexcmp.com/ko/docs/portal/support/ -->

# 고객 지원 {#support-for-customers}

> **포털 위치:** 모든 페이지의 채팅 말풍선, `/chat`, 그리고 Support tickets. **관리자 위치:** Customers › Support › Tickets (`/support/tickets`), **Settings** 탭.

## 고객용 {#for-customers}

- **채팅 말풍선** (모든 페이지의 하단 모서리): 질문을 입력하면 [AI Chat](https://nexcmp.com/ko/docs/ai/ai-chat/)이 문서와 고객의 계정 데이터를 사용하여 답변합니다. **Expand**를 누르면 `/chat`에서 동일한 대화가 열립니다.
- **직원과 대화**: 관리자 텔레그램 그룹을 통해 대화를 담당 팀에게 넘깁니다.
- **Telegram / Zalo** 버튼: 지원 설정에서 링크를 설정한 경우에만 나타납니다.
- **티켓**: 장기적인 문제 해결용; 답변은 이메일로 발송됩니다 (`ticket_reply`).

## 관리자용 {#for-you}

1. **Customers › Support › Tickets**를 엽니다. 새 티켓과 채팅이 대화 내용과 함께 여기에 표시됩니다.
2. 스레드에서 답변합니다. 고객에게는 [SMTP](https://nexcmp.com/ko/docs/administration/smtp-and-emails/)를 통해 이메일이 전송됩니다.
3. **Settings** 탭에서 채팅 위젯을 켜거나 끄고, 텔레그램 및 잘로(Zalo) 링크(https만 허용)를 설정하며, AI 자동 답변 여부를 선택할 수 있습니다. [AI Chat](https://nexcmp.com/ko/docs/ai/ai-chat/)을 참조하세요.
4. [Telegram alerts](https://nexcmp.com/ko/docs/administration/telegram-notifications/)를 연결하여 새 채팅 발생 시 팀이 알림을 받도록 하세요.




---

<!-- source: https://nexcmp.com/ko/docs/ai/ai-providers/ -->

# AI 공급자 {#ai-provider}

> **관리자 위치:** System › Settings › AI provider (`/settings/ai`). AI 모듈 스위치는 해당 위치와 System › Admin › License & updates (`/license`)의 **Module** 카드에도 있습니다.

## 작동 내용 {#what-it-does}

AI Chat(자동 고객지원 채팅)과 AI Agent(자연어 기반 VM 관리)에는 모델이 내장되어 제공되지 않습니다. **자체 제공업체**를 직접 선택할 수 있습니다. OpenAI, OpenRouter, LiteLLM 게이트웨이 또는 자체 vLLM 서버처럼 **OpenAI 호환** `chat/completions` API를 제공하는 모든 서비스가 해당합니다. NexCMP는 엔드포인트와 API key(암호화됨)를 저장하고 모든 AI 기능에 이를 사용합니다. 요금은 해당 제공업체에 직접 지불합니다.

## 요구 사항 {#requirements}

| 항목 | 요구 사항 |
|---|---|
| Endpoint | OpenAI 호환 기본 URL(`https://api.openai.com/v1`, `https://ai.example.com/v1`). NexCMP는 `/chat/completions`을(를) `/v1`(으)로 끝나는 URL에 추가하며, 그 외 다른 URL에는 `/v1/chat/completions`을(를) 추가합니다. 이미 `/chat/completions`(으)로 끝나는 URL은 그대로 사용됩니다. |
| 모델 | **도구(함수) 호출**을 지원하는 모델입니다. AI Chat과 Agent 모두 이 모델을 사용합니다. |
| API 키 | 해당 엔드포인트의 키입니다. 공급자 측에 **지출 한도**가 설정된 키를 사용하는 것이 좋습니다 (예: 월별 예산이 설정된 LiteLLM 가상 키). |
| 네트워크 | 패널 서버는 HTTP(S)를 통해 엔드포인트에 도달할 수 있어야 합니다. 양식에 입력된 URL은 포트 80, 443, 8080 또는 8443의 인터넷 주소만 허용되며, 내부 주소를 사용하려면 먼저 공급자를 저장한 후 테스트하세요. |
| 의존성 | **AI** 모듈이 켜져 있어야 합니다. Agent에 대해서는 [AI Agent](https://nexcmp.com/ko/docs/ai/ai-agent/#requirements)를 참고하세요. |

## 인프라 준비 {#prepare-the-infrastructure}

1. 공급자에 가입하고 API 키를 생성합니다. 공급자가 예산 또는 요청 수 제한을 지원하는 경우 월별 한도를 설정하세요.
2. **기본 URL**과 정확한 **모델 이름**(선택 사항으로 최대 4개의 대체 모델)을 기록해 둡니다.
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"}]}'
   ```

   `choices[0].message.content`이(가) 포함된 JSON 응답은 엔드포인트가 작동함을 의미합니다.

## NexCMP에서 연결 {#connect-in-nexcmp}

1. **System › Settings › AI provider**를 엽니다.
2. **Module AI** 카드에서 모듈을 **켜짐**으로 전환합니다. 켜질 때까지 고객은 포털에서 AI Chat이나 AI Agent를 볼 수 없습니다. (**License & updates**에서도 전환할 수 있습니다.)
3. **Connection** 카드에서 다음을 입력합니다:

   | 필드 | 예시 | 참고 |
   |---|---|---|
   | 이 공급자 사용 | on | 켜려면 기본 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개. 기본 모델이 실패할 때 사용됩니다. |
   | 추론 수준 | 기본값 (전송되지 않음) | `Minimal`, `Low`, `Medium` 또는 `High`. 추론 모델(Gemini, o-series)의 경우 낮은 수준에서 훨씬 빠르게 응답합니다. 일반 모델의 경우 기본값으로 두세요. |

4. **Save**를 클릭한 다음 **Test connection**을 클릭합니다. 테스트는 짧은 질문 하나를 보내고 `Connected — <model>, <ms> ms` 또는 공급자가 반환한 오류를 표시합니다.

![AI 모듈이 켜져 있고 연결 양식에 예시 값이 입력된 AI provider 페이지](https://nexcmp.com/ko/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에 "내 잔액이 얼마인가요?"라고 물어봅니다. 실제 잔액을 알려주는 응답이 오면 공급자가 도구 호출을 올바르게 처리하고 있음을 의미합니다.

## 한도 및 참고 사항 {#limits-notes}

- **단일 공급자.** NexCMP는 Chat, Agent 및 티켓 조사를 위해 단일 구성된 공급자를 사용합니다. 대체 모델은 해당 공급자 내에서 복원력을 제공합니다.
- **키 안전성.** 저장된 키는 저장된 엔드포인트로만 전송됩니다. 기본 URL을 변경하는 경우 테스트하기 전에 키를 다시 입력해야 합니다.
- **고객별 제한.** AI Chat은 로그인한 고객 전용이며, 분당 및 채팅당 메시지 제한이 적용됩니다. 에이전트는 계정당 일일 호출 제한이 있습니다. [AI Chat](https://nexcmp.com/ko/docs/ai/ai-chat/) 및 [AI Agent](https://nexcmp.com/ko/docs/ai/ai-agent/)을 참조하세요.
- **개인정보 보호.** 고객의 질문과 AI가 해당 고객을 위해 읽는 데이터(읽기 전용)는 제공업체로 전송됩니다. [개인정보처리방침](https://nexcmp.com/ko/docs/customers/legal/)에 이를 명시하세요.
- **비용 제어.** NexCMP는 AI 비용을 측정하지 않으며, 제공업체의 예산 기능을 사용해야 합니다.
- 모듈은 언제든지 끌 수 있습니다. AI 메뉴 항목이 사라지고 AI 라우트는 404를 반환합니다 `module_disabled`. AI Chat의 일부 백그라운드 작업(티켓 조사, 지연 답변)은 패널을 다시 시작할 때 변경 사항을 반영합니다.

## Troubleshooting {#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` | 빈 필드 | 둘 다 입력하세요. |
| "Base URL 차단됨: public 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 - _ . / : @` | 잘못된 문자 | 제공업체의 정확한 모델 ID를 사용하세요. |
| `fallback_models: up to 4 model names` | 너무 많음 | 4개 이하로 유지하세요. |
| 401 오류로 테스트 실패 | Wrong key | 키와 엔드포인트를 확인하세요. |
| 404 또는 "model not found" 오류로 테스트 실패 | 잘못된 경로 또는 모델 | Base URL(`/v1`)과 모델 ID를 확인하세요. |
| `Too many tests — wait a minute` (429) | 분당 10회 초과 테스트 | 잠시 기다리세요. |
| 포털에 여전히 AI 메뉴가 표시되지 않음 | 모듈이 꺼져 있거나 제공업체가 "사용 중" 상태가 아님 | 모듈을 켜고 제공업체를 활성화하세요. |


---

<!-- source: https://nexcmp.com/ko/docs/ai/ai-chat/ -->

# 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**을 클릭하면 텔레그램을 통해 직원에게 채팅이 전달되며, 제때 답변이 없으면 티켓으로 전환됩니다. 동일한 AI 설정으로 시스템이 직원을 위해 **티켓을 조사**할 수도 있습니다.

## 요구 사항 {#requirements}

| 항목 | 요구 사항 |
|---|---|
| 모듈 및 제공업체 | **AI** 모듈이 켜져 있고 [AI provider](https://nexcmp.com/ko/docs/ai/ai-providers/)가 저장되어 사용 중이어야 합니다. 제공업체가 없으면 어시스턴트가 설정되지 않았다고 안내합니다. |
| 고객 | **로그인한 고객 전용.** 설치된 NexCMP에는 공개 사이트가 없으므로 로그인하지 않은 방문자는 "Sign in to use AI Chat" 메시지를 보게 됩니다. |
| 직원 채널 (선택 사항) | 관리자 알림을 위한 텔레그램 봇 및 채팅 ([Telegram notifications](https://nexcmp.com/ko/docs/administration/telegram-notifications/) 참조). 동일한 채널로 채팅 전달 및 티켓 초안이 수신됩니다. |
| 의존성 | [AI provider](https://nexcmp.com/ko/docs/ai/ai-providers/). |

## 인프라 준비 {#prepare-the-infrastructure}

AI 제공업체 외에 추가 요구사항은 없습니다. 직원 연계를 원하시는 경우:

1. @BotFather를 통해 텔레그램 봇을 생성하고 토큰을 기록해 두세요.
2. 그룹을 만들거나 봇과의 개인 채팅을 사용하고, 채팅 ID를 기록합니다.
3. System › Settings › Admin alerts([Telegram notifications](https://nexcmp.com/ko/docs/administration/telegram-notifications/) 참조)에 둘 다 입력합니다. 지원 기능에서 해당 봇과 채팅을 재사용합니다.

## NexCMP에서 연결 {#connect-in-nexcmp}

1. AI 모듈이 켜져 있고 공급자 테스트가 녹색으로 표시되는지 확인합니다([AI provider](https://nexcmp.com/ko/docs/ai/ai-providers/)).
2. **Customers › Support › Ticket**를 열고 **AI settings** 탭을 선택합니다. 왼쪽 카드 상단에는 *AI provider: configured*, *Telegram: channel present*, *On shift* 또는 *Off shift*의 세 가지 태그가 표시됩니다.
3. 왼쪽 카드 **AI + Telegram**:

   | 스위치 또는 필드 | Default | 의미 |
   |---|---|---|
   | AI가 자동으로 티켓 조사 | On | 새 티켓이나 메시지의 경우 AI가 고객의 데이터를 읽고(읽기 전용) 예상 원인과 답변 초안을 **내부 노트**로 작성합니다. 고객에게 절대 발송되지 않습니다. |
   | 관리자에게 Telegram 알림 | On | 노트가 Telegram으로 전송되며 Send, Edit 및 Skip 버튼이 함께 제공됩니다. |
   | AI 자동 응답 | 꺼짐 | 모든 안전 조건이 충족될 때(신뢰도 85% 이상, 경고 없음) 간단한 사용법이나 영업 답변을 스스로 전송합니다. 3분 후에 전송되며 Telegram에서 취소할 수 있습니다. |
   | 자동 응답이 허용된 카테고리 | `how_to`, `sales` | 해당 항목만 허용됩니다. |
   | 기본 모델, 대체 모델 | 공급자에서 설정 | 일반적으로 AI 공급자 페이지에서 저장된 상태 그대로 둡니다. |
   | 작업이 허용된 Telegram 사용자 ID | 비어 있음 | 비워 두면 알림 채널의 채팅을 의미합니다. |

4. 오른쪽 카드 **Live chat (customer widget)**:

   | 필드 | Default | 의미 |
   |---|---|---|
   | 채팅 위젯 사용 | 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 링크** | 비어 있음 | `https://zalo.me/...` 채팅에 **Chat on Zalo** 버튼(QR 코드 포함)을 표시합니다. 비워 두면 숨겨집니다. |
   | **Telegram 링크** | 비어 있음 | `https://t.me/...` **Telegram** 버튼을 표시합니다. 비워 두면 숨겨집니다. |
   | 로그인된 고객의 AI 전환 시스템 전체 일일 한도 | 2000 | |
   | 게스트의 시스템 전체 일일 한도 | 500 | 독자적인 풀이며, 게스트가 채팅할 수 없는 동안에는 사용되지 않습니다. |
   | 자동 티켓 조사의 시스템 전체 일일 한도 | 200 | |
   | 관리자 경로("Open admin" Telegram 버튼) | 비어 있음 | 관리자 URL (예: `https://cloud.example.com/admin`). |

   각 스위치나 필드는 변경할 때마다 저장됩니다.

5. 하단에는 **Reply templates**(제목, 언어 VI/EN/ZH, 최대 4,000자의 텍스트)를 통해 직원에게 상용구 답변을 제공합니다.

![AI 및 Telegram 스위치, 라이브 채팅 제한 및 바로 가기 링크가 포함된 AI settings 탭](https://nexcmp.com/ko/docs/images/ai/ai-chat-01-settings.webp)

![어시스턴트, Zalo 및 Telegram 바로 가기 버튼, 상담원 연결 옵션이 포함된 고객 채팅 페이지](https://nexcmp.com/ko/docs/images/ai/ai-chat-02-portal.webp)

## 어시스턴트가 할 수 있는 일과 할 수 없는 일 {#what-the-assistant-can-and-cannot-do}

- **읽기:** 지식 베이스와 공개 문서를 검색하고, 읽기 전용 도구를 통해 로그인한 고객의 데이터를 읽습니다. 다른 고객의 데이터는 볼 수 없습니다.
- **실행:** 고객의 자체 API 권한을 사용합니다. *읽기*는 즉시 실행됩니다. 변경되거나 비용이 발생하는 작업은 **확인 카드**("확인 필요" 및 *비용 발생* 또는 *삭제* 태그 포함)를 생성하며, 고객이 **Confirm**을 클릭하기 전에는 아무것도 실행되지 않습니다. 하나의 채팅에는 최대 3개의 대기 중인 카드가, 하나의 계정에는 시간당 최대 10개의 확인된 쓰기 작업이 허용됩니다.
- **금지:** 콘솔 열기, SSH 또는 콘솔 토큰 생성, Kubernetes 액세스 파일 다운로드, 비밀번호 재설정, 프록시 비밀번호나 S3 보안 비밀과 같은 민감 정보를 표시할 수 없습니다. 보안 비밀은 모델의 컨텍스트나 채팅 기록에 절대 포함되지 않습니다.
- **안전성:** 답변은 출력 필터를 거치며, 고객의 텍스트와 도구 결과는 지시사항이 아닌 데이터로 처리됩니다.
- **안내 배너:** 채팅창에 "AI 어시스턴트가 답변했습니다. 불완전할 수 있으니 중요한 사항은 상담원과 문의하세요."라는 문구가 표시됩니다.

## 상담원 전환 {#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 턴은 제공업체를 호출합니다. 지출을 제한하려면 **AI turns / day / customer**를 낮추십시오.
- **자동 응답은 기본적으로 꺼져 있습니다.** 초안을 잠시 모니터링한 후에만 활성화하십시오.
- **언어:** 어시스턴트는 고객의 언어로 답변하며, 베트남어는 텍스트에서 감지됩니다.
- **리셀러:** 리셀러 사이트에서는 위젯 대신 티켓을 사용합니다.

## Troubleshooting {#troubleshooting}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| 고객에게 채팅이 표시되지 않음 | AI 모듈이 꺼져 있거나 **Enable chat widget**이 꺼져 있음 | 둘 다 켭니다. |
| "Sign in to use AI Chat" | 방문자가 로그인하지 않음 | NexCMP의 정상 동작: 먼저 로그인하십시오. |
| configured된 AI provider가 없다고 어시스턴트가 답변함 | 제공업체가 누락되었거나 사용되지 않거나 키가 누락됨 | [AI provider](https://nexcmp.com/ko/docs/ai/ai-providers/) 설정을 완료합니다. |
| 몇 가지 질문 후 AI가 "talk to a human"이라고 답변함 | 고객별 일일 한도에 도달함 | **AI turns / day / customer**를 높입니다. |
| 텔레그램 태그에 "no channel" 표시됨 | 봇 또는 채팅 ID가 설정되지 않음 | [Telegram notifications](https://nexcmp.com/ko/docs/administration/telegram-notifications/) 설정. |
| Zalo 또는 Telegram 버튼이 누락됨 | 링크 필드가 비어 있음 | 링크를 입력하세요. |
| 채팅에 "Too many requests" 표시됨 | 한 IP에서 1분에 20개 초과 메시지 전송됨 | 잠시 기다려 주세요. |
| 채팅 대화 가득 참 | 메시지 40개 도달함 | 새 대화를 시작하세요. |


---

<!-- source: https://nexcmp.com/ko/docs/ai/ai-agent/ -->

# 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 VM에 SSH로 직접 연결하여 "시스템 상태 확인", "Docker 설치", "최근 오류 찾기", "디스크 공간 확보"와 같은 평문으로 설명된 작업을 수행합니다. 제안하는 모든 명령어와 그 출력을 표시합니다. 읽기 전용 명령어는 자동으로 실행될 수 있으며, 서버를 변경하는 작업은 고객이 **Run**을 누를 때까지 대기합니다.

## 요구 사항 {#requirements}

| 항목 | 요구 사항 |
|---|---|
| AI 모듈 및 공급자 | **AI** 모듈이 켜져 있고 작동 중인 [AI provider](https://nexcmp.com/ko/docs/ai/ai-providers/)가 필요합니다. 또한 에이전트는 도구 호출(tool calling)을 지원하는 모델이 필요합니다. |
| 패널 서버의 `openssh-client` | 에이전트는 패널 자체의 `ssh` 프로그램(`/usr/bin/ssh`)을 사용하여 명령어를 실행합니다. 설치 프로그램이 `openssh-client`을(를) 설치하며, `ssh -V`(으)로 확인할 수 있습니다. 이 프로그램이 없으면 에이전트는 "ssh client is not installed on the panel server" 오류를 보고합니다. |
| 별도 SSH 게이트웨이 없음 | 기본 설치에서는 내장 SSH가 사용되며 `ssh-proxy` 웹 터미널은 **필요하지 않습니다**. 선택 사항인 *web SSH* 기능(`feature_ssh_web`)이 활성화되고 `ssh-proxy` 서비스가 설치된 경우에만 에이전트가 `ssh-proxy`을(를) 거쳐 연결됩니다. |
| 네트워크 | 패널 서버는 VM의 IP에 있는 SSH 포트(기본값 22)에 도달할 수 있어야 합니다. 패널과 게스트 네트워크 간의 방화벽과 보안 그룹을 확인하세요. |
| VM | 고객 소유, **실행 중**, 잠기지 않음, 공개 또는 도달 가능한 IP 주소를 가진 **Linux** VM (Windows VM은 지원되지 않음). |
| SSH 자격 증명 | NexCMP에 저장된 VM 로그인 계정 및 비밀번호(VM 생성 시 또는 비밀번호 재설정 시 암호화되어 저장됨) 또는 패널의 운영 키가 설치된 경우 해당 키. 둘 다 없는 경우 에이전트는 로그인할 수 없다고 표시합니다. |

## 인프라 준비 {#prepare-the-infrastructure}

1. 패널 서버에서 SSH 클라이언트 확인:

   ```bash
   ssh -V
   sudo apt-get install -y openssh-client   # only if missing
   ```

2. 패널 서버가 게스트 VM에 SSH로 연결할 수 있는지 확인:

   ```bash
   nc -vz 198.51.100.10 22
   ```

   주소를 테스트 VM의 IP로 바꾸세요. 이 작업이 실패하면 라우팅 또는 방화벽을 먼저 수정하세요.
3. 게스트가 NexCMP에 저장된 사용자의 비밀번호 로그인을 허용하는지(일부 클라우드 이미지는 비활성화함), 또는 패널의 운영 키가 게스트에 설치되어 있는지 확인하세요.

## NexCMP에서 연결 {#connect-in-nexcmp}

1. [AI provider](https://nexcmp.com/ko/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` 클라이언트를 사용하는 패널 서버이며, 한 번에 하나의 비대화식 명령이 실행됩니다. 대상은 요청이 아닌 **데이터베이스의** VM IP이며, 소유자 본인의 실행 중이고 잠기지 않은 VM만 접근할 수 있습니다.
- **인증:** 저장된 비밀번호는 프로세스 환경의 일회용 `SSH_ASKPASS` 헬퍼를 통해 전달되며, 디스크에 기록되거나 명령줄에 포함되지 않습니다. 호스트 키는 고정되지 않습니다(VM은 새 키로 재설치됨). 명령당 출력은 200 KB로 제한되며 각 명령에는 시간 제한(60초)이 있습니다.
- **에이전트 루프:** AI가 명령을 제안하고 출력을 읽으며, 한 턴은 최대 **10단계** 후에 종료됩니다.
- **모드:**

  | 모드 | 동작 |
  |---|---|
  | **Confirm** | 모든 명령은 **Run**을 기다립니다. |
  | **Auto** | 엄격한 읽기 전용 허용 목록을 통과한 명령만 자동으로 실행됩니다(예: `df -h`, `ps`, `journalctl`). 그 외의 것과 파서가 확실하게 분석할 수 없는 것(변수, 명령 치환, 파일 리디렉션)은 **Run**을 기다립니다. |

- **위험 레이블:** 파일을 덮어쓰거나 삭제하고, 디스크에 쓰고, 계정이나 SSH 키를 변경하고, 외부 서버로 데이터를 전송하고, 원시 네트워크 연결을 열고, 난독화된 코드를 실행하고, 스크립트를 다운로드하여 실행하고, 기기를 종료 또는 재시작하거나, 다른 서버에 도달하는 명령은 Auto 모드에서도 항상 **Needs confirmation**을 표시합니다.
- **신뢰할 수 없는 출력:** 명령 출력은 신뢰할 수 없는 데이터로 모델에 표시되며, 그 안의 지시는 따르지 않습니다.

## 확인 {#verify}

1. 실행 중인 테스트 VM을 선택합니다. 페이지에 *SSH connected*가 표시됩니다.
2. "Check CPU, RAM and disk"라고 요청합니다. Auto 모드에서는 읽기 전용 명령이 실행되고 답변에 그 결과가 요약됩니다.
3. "Install Nginx"라고 요청합니다. **Run** 및 **Skip**과 함께 설치 명령이 나타나며, **Run**을 누르기 전에는 아무것도 실행되지 않습니다.
4. 상단의 카운터는 오늘 사용된 AI 호출 횟수를 보여줍니다(예: `3/300`).

## 한도 및 참고 사항 {#limits-notes}

- **일일 한도:** 고객당 하루(UTC 기준) 300회의 AI 호출이 허용되며, 00:00 UTC에 초기화됩니다. 한도가 소모되면 에이전트는 "Daily AI quota reached"로 응답합니다.
- **동시성:** 고객당 동시에 최대 2개의 에이전트가 실행될 수 있으며, 세션은 한 번에 한 턴씩 실행됩니다.
- **세션:** 세션당 최대 100개의 메시지, 메시지당 4,000자가 허용됩니다. 세션은 하나의 VM에 속하며, VM이 삭제되거나 이전되면 기존 세션은 읽기 전용이 됩니다.
- **잠기거나 중지된 VM 또는 Windows:** VM이 *Locked*, *Stopped*, *Windows* 또는 *No address*로 표시되며 선택할 수 없습니다.
- **가장(Impersonation):** 고객을 가장하는 관리자는 에이전트의 자격 증명 기능을 사용할 수 없습니다([Log in as a customer](https://nexcmp.com/ko/docs/customers/login-as/) 참고).
- **책임:** 에이전트는 실수를 할 수 있습니다. 포털은 고객에게 명령을 실행하기 전에 검토하도록 안내합니다. 승인된 명령에 대한 책임은 고객에게 있음을 약관에 명시하세요.
- AI 모듈을 끄면 에이전트 항목이 제거되고 라우트는 404를 반환합니다 `module_disabled`.

## Troubleshooting {#troubleshooting}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| "패널 서버에 ssh 클라이언트가 설치되어 있지 않습니다 (apt install openssh-client)" | `ssh` 바이너리 없음 | `sudo apt-get install -y openssh-client`. |
| "에이전트가 로그인할 수 없습니다" / `ssh: no saved credentials for this VM` | 저장된 비밀번호 및 운영 키 없음 | 포털에서 VM 비밀번호를 재설정하여 다시 저장되도록 하거나 운영 키를 설치합니다. |
| "서버가 제때 응답하지 않았습니다" | 방화벽, SSH가 수신 대기 중이 아님, VM이 바쁨 | 패널 서버에서 `nc -vz <ip> 22`을(를) 테스트하고, VM에서 `sshd`을(를) 시작합니다. |
| "이 서버의 SSH에 연결할 수 없습니다" | 라우팅 또는 보안 그룹 | 패널 서버가 포트 22를 통해 VM에 도달할 수 있도록 허용합니다. |
| "VM이 실행 중이 아님" / "권한 없음" | VM이 중지되었거나, 잠겼거나, 삭제되었거나 고객의 소유가 아님 | 시작하거나, 잠금을 해제하거나, 다른 VM을 선택합니다. |
| "사용 불가: N (중지됨, 잠김 또는 Windows)" | 위에 나열된 이유 | VM은 Linux여야 하며 실행 중이어야 합니다. |
| "SSH 게이트웨이를 일시적으로 사용할 수 없습니다" | 웹 SSH 기능이 활성화되었으나 `ssh-proxy`이(가) 다운됨 | `ssh-proxy`을(를) 시작하거나, 기본 제공 SSH를 사용하려면 웹 SSH 기능을 끕니다. |
| "AI 응답이 너무 느립니다 (90초 초과)" | 제공자 응답 지연 | 더 빠른 모델 또는 더 낮은 **Reasoning effort**을(를) 사용하세요. |
| "일일 AI 할당량 도달" | 300회 호출 사용됨 | 00:00 UTC까지 기다리세요. |
| "이 세션이 여전히 실행 중입니다" | 다른 턴이 진행 중 | 기다리거나 **Stop**을(를) 누르세요. |




---

<!-- source: https://nexcmp.com/ko/docs/developers/api/ -->

# REST API

> **포털 위치:** `https://<your-domain>/apidoc`의 API 참조 (공개) 및 `/api-keys`의 API 키. **관리자 위치:** Customers › API keys (`/customers/apikeys`)에는 고객이 생성한 키가 나열됩니다.

## 작동 내용 {#what-it-does}

고객이 포털에서 수행할 수 있는 모든 작업(VM 목록 조회 및 제어, 인프라 관리, 청구서 읽기, SSH 키 관리, Kubernetes, 스토리지, 지원 티켓)은 `https://<your-domain>/v1/` 아래의 버전이 지정된 REST API를 통해 사용할 수 있습니다. 고객은 범위가 지정된 **API key**를 사용하여 스크립트와 CI에서 이를 호출합니다. 동일한 API가 [`cmp` command-line tool](https://nexcmp.com/ko/docs/developers/cmp-cli/) 및 [MCP server](https://nexcmp.com/ko/docs/developers/mcp/)에 전송되며, 레퍼런스는 실행 중인 설치에서 생성되므로 활성화한 기능이 정확히 나열됩니다.

## 요구 사항 {#requirements}

| 항목 | 요구 사항 |
|---|---|
| 공용 HTTPS 주소 | API는 기본 도메인(및 각 리셀러의 고유 도메인)에서 서비스됩니다. |
| API 키 | 포털에서 고객이 생성합니다. [API keys](https://nexcmp.com/ko/docs/developers/api-keys/)을(를) 참조하세요. |
| 의존성 | 없음. 활성화하지 않은 모듈(예: Kubernetes 또는 Object Storage)의 엔드포인트는 레퍼런스에서 숨겨지고 거부됩니다. |

## 인프라 준비 {#prepare-the-infrastructure}

설치할 내용이 없습니다. NexCMP 앞에 리버스 프록시가 있는 경우 `/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, 키 접두사, 모든 범위, 그리고 메서드, 경로, 범위 및 `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`을(를) 붙여넣습니다. 참조 페이지에서는 JavaScript 및 Python용 단일 파일 API 클라이언트도 제공합니다.

### 인증 {#authentication}

`Authorization` 헤더에 키를 전송합니다.

```bash
curl -s https://cloud.example.com/v1/billing/wallet \
  -H "Authorization: Bearer vk_XXXX"
```

- 고객 키는 `vk_`(으)로 시작합니다. 키는 **사이트 귀속형**입니다. `cloud.example.com`에서 생성된 키는 리셀러 도메인에서 작동하지 않습니다.
- 브라우저 세션 토큰(`pt_...`)은 포털 전용이므로, 자동화 작업에는 키를 사용하세요.
- 키의 **권한(scope)**에 따라 호출 가능한 작업이 결정되며, 누락된 권한은 HTTP 403 `scope_required`을(를) 반환합니다. [API keys](https://nexcmp.com/ko/docs/developers/api-keys/)을(를) 참조하세요.
- `GET /v1/apikeys/self`을(를) 사용하여 키를 확인하세요. 호출하는 키의 이름, 권한, 만료일 및 남은 요청 제한 허용량(모든 키로 호출 가능)을 반환합니다.

### 예제 {#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}

모든 오류는 고정된 `code` 및 사람이 읽을 수 있는 `message`(이)가 포함된 JSON입니다.

```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 키 비활성화. |
| 403 | `scope_required`, `endpoint_not_public`, `account_blocked`, `quota_exceeded`, `impersonate_forbidden` | 키에 권한이 없음; 엔드포인트를 키에서 사용할 수 없음; 계정이 잠김; [quota](https://nexcmp.com/ko/docs/billing/quotas/)에 도달함; 대행(impersonated) 세션에서는 허용되지 않는 작업. |
| 404 | `not_found` | 찾을 수 없음 — 다른 사용자의 리소스인 경우에도 반환됩니다. |
| 422 | `invalid_argument` | 유효성 검사 오류 (응답에 필드 이름이 명시됨). |
| 429 | `rate_limited` | 요청이 너무 많습니다. `Retry-After` 동안 기다려 주세요. |
| 503 | `maintenance` | 유지보수 모드가 켜져 있습니다. 읽기는 가능하지만 쓰기는 거부됩니다. |

### 요청 제한 {#rate-limits}

| 제한 | Default |
|---|---|
| 키당 | 분당 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. 포털에서 `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}

- **키로 절대 사용할 수 없는 작업:** 잔액 충전, 출금, 카드 변경 또는 자동 충전, 비밀번호·이메일·2FA 변경, 계정 삭제, 다른 키 생성·편집·철회. 이러한 작업에는 로그인된 브라우저 세션이 필요합니다.
- **숨겨진 모듈:** 참조 문서와 OpenAPI 문서에는 해당 사이트에서 활성화된 기능만 나열됩니다.
- **응답 크기 및 페이징:** 목록 조회 엔드포인트는 페이징 처리가 적용됩니다(`page`, `per_page`). 각 엔드포인트에 대한 OpenAPI 문서를 참조하세요.
- **시간 및 금액:** 필드 이름에 별도의 언급이 없는 한 금액은 USD 센트 단위입니다.
- **관리자 API:** 관리자 콘솔에는 자체적인 **System › Admin › API** 페이지와 관리를 위한 관리자 키(`ofw_...`)가 있으며, 여기서 설명하는 고객 API와는 별개입니다.
- **버전 관리:** 경로 접두사 `/v1`은(는) 안정적이며, 응답에 새 필드가 추가될 수 있습니다.

## Troubleshooting {#troubleshooting}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| 새 키 사용 시 401 오류 | 다른 도메인의 키이거나, 만료되었거나, 공백이 포함되어 입력됨 | 호출하는 도메인에서 키를 생성하고 `Authorization: Bearer vk_...` 헤더를 확인하세요. |
| 403 `scope_required` | 스코프 누락 | 포털에서 키를 편집하고 스코프를 추가하세요. |
| 401 `key_ip_denied` 또는 `site_mismatch` | 다른 IP로 제한된 키("허용된 IP")이거나 다른 도메인에서 생성됨 | 키의 허용된 IP에 서버 IP를 추가하거나, 키가 생성된 도메인을 호출하세요. |
| 존재하는 VM에 대한 404 | 다른 계정 소유의 VM임 | 소유자의 키를 사용하세요. |
| `Idempotency-Key`을(를) 요구하는 400/422 | 헤더가 없는 유료 작업 | `Idempotency-Key: <uuid>`을(를) 추가하세요. |
| 429 | 한도 초과 | 요청을 줄이거나 `Retry-After`을(를) 사용하세요. |
| `/apidoc`의 표시 값이 예상보다 적음 | 모듈이 꺼져 있음 | License & updates에서 모듈을 활성화하세요. |




---

<!-- source: https://nexcmp.com/ko/docs/developers/api-keys/ -->

# 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/ko/docs/developers/cmp-cli/) 또는 AI 어시스턴트([MCP](https://nexcmp.com/ko/docs/developers/mcp/))가 부여된 권한(**scopes**) 범위 내에서 특정 고객을 대신하여 [REST API](https://nexcmp.com/ko/docs/developers/api/)를 호출할 수 있습니다. 고객 키는 `vk_`(으)로 시작합니다. 서비스 조회 및 관리는 가능하지만, 결제나 계정 자체는 **절대** 건드릴 수 없습니다.

## 요구 사항 {#requirements}

| 항목 | 요구 사항 |
|---|---|
| Customer | 로그인된 포털 세션 (키는 다른 키를 생성 또는 편집할 수 없으며, 고객으로 가장한 관리자도 불가능합니다). |
| 스위치 | API 키는 기본적으로 켜져 있습니다. 꺼져 있는 경우 호출 시 401 `api_keys_disabled`을(를) 반환합니다. |
| 의존성 | 제품의 스코프는 해당 제품이 사이트에서 활성화된 경우에만 표시됩니다. |

## 키 생성 (고객) {#create-a-key-customer}

1. 포털에 로그인한 후 **API keys**를 엽니다.
2. **Create key**을(를) 클릭합니다.
3. 양식을 작성합니다:

   | 필드 | 규칙 |
   |---|---|
   | **Key name** | 필수 항목, 최대 60자 ("deploy server", "backup script"). |
   | **이 키로 수행할 수 있는 작업** | 필요한 스코프를 최소 하나 이상 선택하세요. 읽기 전용 키에는 쓰기 스코프를 부여하지 마세요. 과금이 발생하거나 데이터를 삭제하는 스코프는 주의해서 다루어야 합니다. |
   | **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`), 스코프, 만료일, 마지막 사용일, 요청 횟수 및 상태(*Active*, *Expired*, *Revoked*)만 표시됩니다.

### 편집, 폐기, 감사 {#edit-revoke-audit}

- **Edit**는 이름, 스코프, 허용된 IP 및 만료일을 변경합니다. 대행 세션 중에는 허용되지 않습니다.
- **Revoke**는 키를 즉시 중지하며 취소할 수 없습니다. 사용 로그를 계속 확인할 수 있도록 행은 유지됩니다.
- **Key usage log**는 최근 60일 동안의 쓰기 명령어 및 모든 오류를 시간, 요청, 키, 결과, 소스 IP와 함께 표시합니다.
- 계정은 기본적으로 최대 **10개의 활성 키**를 보유할 수 있습니다.
- CLI 또는 MCP 로그인을 통해 생성된 키는 **Connected apps & devices**에 표시되며 해당 위치에서 취소할 수 있습니다.

## Scopes {#scopes}

스코프 이름은 `area:action` 형식입니다. 제공되는 스코프는 활성화한 제품에 따라 다릅니다.

| Scope | Allows |
|---|---|
| `catalog:read` | 플랜 및 카탈로그 읽기. |
| `vm:read` | VM, 메트릭 및 VM 인보이스 읽기. |
| `vm:write` | 전원 작업, 사소한 변경, 방화벽, 빠른 스냅샷. |
| `vm:create` | **VM 생성(요금 부과).** |
| `vm:plan` | **플랜 변경 또는 크기 조정(요금 부과).** |
| `vm:destroy` | **VM 삭제.** |
| `vm:restore` | **스냅샷에서 VM 복원(디스크 덮어쓰기).** |
| `vm:console` | VNC 콘솔 티켓 열기. |
| `sshkey:read`, `sshkey:write` | SSH 키 읽기, 추가 및 제거. |
| `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는 클러스터 관리자 권한). |
| `vpc:read`, `vpc:write`, `vpc:create`, `vpc:destroy` | Private Cloud. |
| `image:read`, `image:write` | OS 및 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` | Dedicated servers(지갑에서 주문 생성; 삭제 시 OS 재설치). |
| `shield:read`, `shield:write`, `shield:agent` | DDoS Shield(해당 모듈이 활성화된 경우에만 해당). |

키의 스코프 외부에 대한 호출은 **403 `scope_required`**(으)로 응답하며, 어떤 키도 호출할 수 없는 경로는 **403 `endpoint_not_public`**(으)로 응답합니다.

### 키가 절대 할 수 없는 일 {#what-a-key-can-never-do}

금액 충전 또는 출금, 카드 또는 자동 충전 변경, 비밀번호·이메일·2FA 변경, 계정 삭제, 다른 키 생성·편집·취소는 어떠한 스코프로도 불가능합니다. 이 작업들은 항상 로그인된 브라우저가 필요합니다. 키가 유출되더라도 고객의 자금이나 계정에는 접근할 수 없습니다.

## 신뢰할 수 있는 규칙 {#rules-you-can-rely-on}

| 규칙 | Detail |
|---|---|
| Site-bound | 키는 생성된 사이트(도메인)에서만 작동합니다. |
| 요청 제한 | 키별 및 계정별: 기본적으로 분당 120개 및 300개의 요청. |
| 멱등성 | 비용이 발생하거나 반복할 수 없는 작업에는 `Idempotency-Key` 헤더가 필요합니다. |
| 할당량 | 키는 고객과 동일한 [quotas](https://nexcmp.com/ko/docs/billing/quotas/)의 적용을 받습니다. |
| Locked account | 잠긴 고객의 키는 작동이 중지됩니다(403 `account_blocked`). |
| 감사 | 관리자에 의한 취소는 관리자 감사 로그에 기록됩니다. |

## 관리자 보기 {#administrator-view}

1. **Customers › API keys**(`/customers/apikeys`)을 엽니다. 테이블에는 키 이름 및 첫 문자, 소유자, 범위, 상태, 최근 사용(시간, 요청 수, IP), 만료일이 표시됩니다.
2. 리셀러가 있는 경우 사이트별로 필터링합니다. 이름, ID 또는 키 시작 부분으로 검색합니다.
3. 활성 키를 중지하려면 **Revoke**를 클릭하고, 사용 내역을 보려면 **Log**를 클릭합니다.
4. 관리자는 키를 **조회하고 취소할 수 있지만** 고객을 위해 키를 읽거나 생성할 수는 없습니다.

![범위, 상태, 최근 사용 및 취소 버튼이 포함된 고객 API 키의 관리자 목록](https://nexcmp.com/ko/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"`은(는) VM 목록을 반환합니다.
3. `curl -s -X POST .../v1/vm/<id>/start -H "Authorization: Bearer vk_XXXX"`은(는) 403 `scope_required`(으)로 응답합니다.
4. 키를 취소합니다. 이제 첫 번째 호출은 401 `key_revoked`(으)로 응답합니다.

## 한도 및 참고 사항 {#limits-notes}

- 키는 다시 표시되지 않습니다. 비밀번호처럼 취급하고 비밀 관리자나 CI 시크릿에 보관하세요.
- 스크립트당 하나의 키, 최소한의 범위, 짧은 만료 기간 및 IP 허용 목록을 사용하는 것이 좋습니다. 새 키를 생성하고 기존 키를 취소하여 교체하세요.
- 디바이스 로그인(CLI, MCP)의 키는 기본적으로 90일로 설정됩니다.
- 키를 취소해도 삭제되거나 이전된 리소스는 영향을 받지 않습니다.

## Troubleshooting {#troubleshooting}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| 오류 `too_many_keys` (422) | 활성 키 제한(기본값 10개)에 도달함 | 오래된 키를 취소하세요. |
| 오류 `invalid_argument`: 선택된 범위 없음 | 선택된 범위가 없음 | 범위를 하나 이상 선택하세요. |
| 허용된 IP 관련 오류 `invalid_argument` | 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` 설정). |




---

<!-- source: https://nexcmp.com/ko/docs/developers/cmp-cli/ -->

# `cmp` 명령줄 도구 {#cmp-command-line-tool}

> **포털 위치:** 설치 명령어는 API 참조(`https://<your-domain>/apidoc`, 명령줄 인터페이스 섹션)에 있습니다. 로그인 승인: `https://<your-domain>/link`. 연결된 기기: API 키(`/api-keys`) › Connected apps & devices.

## 작동 내용 {#what-it-does}

`cmp`은(는) 고객(및 관리자)을 위한 소형 명령줄 프로그램으로, **모든 API 작업을 명령어**로 변환합니다(`cmp vm list`, `cmp vm start <id>`, `cmp billing invoice list`). 릴리스 시점에 **사용자** 설치 환경의 OpenAPI 문서로부터 빌드되므로 활성화된 기능과 명령어가 일치합니다. Linux, macOS 및 Windows(amd64 및 arm64)용 단일 정적 바이너리로 제공되며 추가로 설치할 것이 없습니다.

## 요구 사항 {#requirements}

| 항목 | 요구 사항 |
|---|---|
| 서버 | 추가 항목 없음. 릴리스 패키지는 NexCMP 릴리스 내부에 포함되어 있으며 패널에서 `https://<your-domain>/cli/`를 통해 제공됩니다. |
| 고객 머신 | Linux, macOS 또는 Windows(PowerShell 5.1+). 서명 확인에만 `ssh-keygen`(OpenSSH 8.0+)이 필요합니다. |
| 자격 증명 | 일회용 코드를 통한 브라우저 로그인 또는 [API key](https://nexcmp.com/ko/docs/developers/api-keys/). |
| 네트워크 | 패널과의 HTTPS 연결. CLI는 일반 `http://` 연결을 통한 키 전송을 `localhost`(으)로만 제한합니다. |

## 인프라 준비 {#prepare-the-infrastructure}

없음. 패널은 이러한 파일을 `/cli/`에서 직접 제공합니다 (빌드나 업로드 불필요):

| 파일 | 용도 |
|---|---|
| `install.sh`, `install.ps1` | Linux/macOS 및 Windows용 설치 프로그램이며, 패널 주소가 포함되어 있습니다. |
| `latest.json` | 현재 버전, 파일 목록, 크기, sha256. |
| `v<version>/cmp_<version>_<os>_<arch>.tar.gz` 또는 `.zip` | 프로그램 파일: linux amd64/arm64, darwin amd64/arm64/universal, windows amd64/arm64. |
| `v<version>/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
```

설치 프로그램은 OS와 CPU에 맞는 패키지를 선택하고, `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
```

![macOS 및 Linux용 cmp 설치 명령어가 포함된 API 참조 섹션](https://nexcmp.com/ko/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일). 비용이 발생하거나 데이터를 삭제하는 권한은 기본적으로 해제되어 있습니다. 승인을 클릭하세요.
3. CLI는 고객이 직접 생성한 키와는 별개인 **자신만의 키**를 받아 `~/.config/cmp/config.json`에 저장합니다 (권한 `0600`; Windows의 경우 `%APPDATA%\cmp`). 이 키는 **API keys › Connected apps & devices**에 표시되며 여기서 취소할 수 있습니다.

코드는 10분 후에 만료됩니다. 승인에는 다른 키나 대행 세션이 아닌, 이메일이 인증된 실제 로그인된 포털 세션이 필요합니다.

유용한 플래그: `--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 <group> [subgroup] <action> [<id> ...] [flags]
```

- 경로 파라미터는 위치 인자이며, 쿼리 파라미터와 바디 필드는 케밥 케이스 플래그(`--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 <k>` | 유료 명령어의 키 선택. |
| `--retry <n>` | HTTP 429 응답 시 `Retry-After` 동안 대기 후 최대 n회 재시도. |
| `--timeout <s>` | 응답 헤더 대기 시간(초, 기본값 60). |
| `--debug` | 키가 마스킹된 상태로 표준 오류(stderr)에 HTTP 통신 내용 출력. |

지갑에서 **과금되거나 데이터를 삭제하는** 명령어는 확인을 요구하며, 유료 작업인 경우 자동으로 생성된 `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 <name>`은(는) 전환합니다. 리셀러의 고객은 자체 도메인 `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/ko/docs/developers/api/#rate-limits) 참조).

## Troubleshooting {#troubleshooting}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| `curl .../cli/install.sh`이(가) 404를 반환함 | 서버의 릴리스에 CLI 폴더가 없거나 호스트가 라이선스에 포함되어 있지 않음 | `https://<domain>/cli/latest.json` 및 도메인을 확인하고 NexCMP를 업데이트하세요. |
| "서명을 확인할 수 없음" | `ssh-keygen`이(가) 누락되었거나 너무 오래됨 | OpenSSH 8.0+를 설치하거나, 위험을 감수하는 경우에만 `CMP_REQUIRE_SIGNATURE=0`을(를) 설정하세요. |
| `cmp login`에서 코드가 만료되었다고 표시됨 | 10분이 경과함 | `cmp login`을(를) 다시 실행하세요. |
| 종료 코드 3 | 키에 범위가 없거나, 만료되었거나 취소됨 | `cmp whoami`; 더 넓은 범위로 생성하거나 다시 승인하세요. |
| 스크립트 내 종료 코드 6 | 터미널 없이 유료 또는 파괴적인 명령어가 실행됨 | `--yes`(과)과 사용자 지정 `--idempotency-key`을(를) 추가하세요. |
| "http를 통한 키 전송 거부" | 일반 http API URL | `https://`을(를) 사용하거나, 테스트 환경인 경우에만 `CMP_ALLOW_HTTP=1`을(를) 사용하세요. |
| 브라우저가 잘못된 사이트를 염 | 리셀러에 대해 `--api-url`이(가) 설정되지 않음 | `cmp login --api-url https://<reseller-domain>`. |




---

<!-- source: https://nexcmp.com/ko/docs/developers/mcp/ -->

# MCP 서버 {#mcp-server}

> **포털 내 위치:** API reference › Tools (`https://<your-domain>/apidoc`)에서 엔드포인트와 클라이언트 스니펫을 확인할 수 있으며, 키는 API keys (`/api-keys`)에서 생성합니다. 관리자 설정은 별도로 존재하지 않으며, 엔드포인트는 패널에 내장되어 있습니다.

## 작동 내용 {#what-it-does}

**Model Context Protocol (MCP)**을 사용하면 AI 어시스턴트가 도구를 호출할 수 있습니다. NexCMP는 `https://<your-domain>/mcp`에 MCP 엔드포인트를 제공합니다. 모든 공개 API 작업이 하나의 **도구**(`vm_list`, `vm_start`, `billing_wallet`, ...)가 되므로, 고객은 어시스턴트에게 "내 VM 중 어떤 것이 실행 중인가요?" 또는 "스테이징 VM을 중지해 줘"라고 요청할 수 있습니다. 어시스턴트는 고객 본인의 API 키와 권한으로만 동작합니다.

::: tip NexCMP 자체를 AI로 구성하시겠습니까?
이 페이지는 **고객용** MCP 엔드포인트(`/mcp`)입니다. AI 어시스턴트가 관리자로서 패널을 구성하도록 하려면 [Configure with AI](https://nexcmp.com/ko/docs/configure-with-ai/mcp-admin/)(엔드포인트 `/mcp/admin`, 관리자 키 `ak_`)를 참조하세요.
:::

## 요구 사항 {#requirements}

| 항목 | 요구 사항 |
|---|---|
| 서버 | 설치할 필요가 없습니다. 엔드포인트는 패널에서 직접 서비스하며 패널이 도달할 수 있는 곳이면 어디서나 접근 가능합니다. 리버스 프록시는 `/mcp`을(를) 패널로 전달해야 합니다. |
| Customer | 어시스턴트에 필요한 스코프가 포함된 [API key](https://nexcmp.com/ko/docs/developers/api-keys/)(`vk_...`). |
| 클라이언트 | **Streamable HTTP** 전송과 커스텀 `Authorization` 헤더를 지원하는 MCP 클라이언트: Claude Code, Claude Desktop(`mcp-remote` 브리지 경유), Cursor, Copilot 에이전트 모드가 있는 VS Code 등. |
| 프로토콜 버전 | 2025-11-25, 2025-06-18 및 2025-03-26. |

## 인프라 준비 {#prepare-the-infrastructure}

`https://<your-domain>/mcp`이(가) 방화벽이나 프록시 규칙에 의해 차단되지 않도록 하는 것 외에는 추가 조치가 필요 없습니다. 다른 오리진의 브라우저 기반 MCP 클라이언트는 해당 오리진이 허용되지 않은 경우 거부되며, 명령줄 및 데스크톱 클라이언트는 `Origin` 헤더를 전송하지 않으므로 그대로 작동합니다.

## 연결 (고객 측) {#connect-customer-side}

1. 어시스턴트가 사용할 스코프만 선택하고, 짧은 만료 시간 및 가능하면 IP 제한을 설정하여 포털(**API keys › Create key**)에서 API 키를 생성합니다.
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`; Cursor가 시작되는 환경에 `CLOUD_API_KEY`을(를) 설정):

   ```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}

| 항목 | Detail |
|---|---|
| Endpoint | JSON-RPC 2.0 메시지가 포함된 `POST /mcp`; 응답은 `application/json`입니다. `GET /mcp`은(는) 405(서버-클라이언트 스트림 없음)를 반환하고, `DELETE /mcp`은(는) 세션을 종료합니다. |
| 인증 | `Authorization: Bearer vk_...`만 허용됩니다(세션 토큰, 쿠키, 관리자 키는 401 및 `WWW-Authenticate: Bearer` 헤더와 함께 거부됨). |
| 세션 | `Mcp-Session-Id`은(는) `initialize`에 의해 발급되며 해당 키에 바인딩되고 24시간 동안 유효합니다. 키당 최대 16개의 세션이 허용됩니다. |
| 도구 | 키에 표시되는 공개 API 작업당 하나씩 제공됩니다. 도구 이름은 공백과 대시 대신 `_`이(가) 들어간 CLI 명령(`vm firewall add`은(는) `vm_firewall_add`이(가) 됨)이며 OpenAPI `operationId`과(와) 일치합니다. 키에 해당 스코프가 있고 모듈이 활성화된 경우에만 도구가 나열됩니다. |
| 기능 | 도구만 지원(리소스나 프롬프트 없음). |
| 크기 | 요청 본문 최대 1 MB; 도구 결과 텍스트 최대 약 100 KB (초과분은 안내와 함께 잘림); 호출 시간 최대 55초. |

### 안전 규칙 {#safety-rules}

- **REST와 동일한 게이트.** 각 `tools/call` 요청은 패널 자체의 요청 파이프라인(범위, 사이트, IP 제한, 속도 제한, 멱등성, 소유권 검사(타인 리소스의 경우 404), 할당량)을 거칩니다. MCP는 키가 보유하지 않은 권한을 부여할 수 없습니다.
- **확인.** 비용이 발생하거나, 삭제를 수행하거나, 자격 증명(콘솔 티켓, kubeconfig, S3 또는 SSH 비밀번호, 비밀번호 초기화, 새 키)을 반환하는 도구는 `confirm: true` 인수가 필요합니다. 도구 설명은 사용자가 승인한 경우에만 이를 전달하도록 어시스턴트에 지시하므로 웹 페이지나 로그에 숨겨진 지시 사항이 임의로 실행될 수 없습니다.
- **멱등성.** 유료 도구는 `idempotency_key`을(를) 수락하며, 생략된 경우 도구 이름과 인수로부터 안정적인 키가 파생되므로 동일한 재시도로 인해 요금이 중복 청구되지 않습니다.
- **도구로 노출되지 않는 항목:** 스트리밍 엔드포인트(AI Agent 채팅), 일회성 SSH 또는 콘솔 WebSocket 티켓, 바이너리 다운로드, VPN 앱 엔드포인트(`/v1/ext/*`).
- **절대 불가능:** API는 잔액 충전, 비밀번호 변경, 계정 삭제 또는 키 생성을 절대 허용하지 않으므로 어시스턴트가 이를 수행할 수 없습니다.

### 제한 {#limits}

| 제한 | Default |
|---|---|
| 키당 도구 호출 | 분당 60회 |
| 키당 MCP 요청 | 분당 240회 |
| 일반 키 및 계정 제한 외 추가 적용 | [REST API](https://nexcmp.com/ko/docs/developers/api/#rate-limits) 참고 |

한도를 초과하면 엔드포인트는 JSON-RPC 오류 및 `Retry-After`과(와) 함께 HTTP 429를 응답합니다.

## 확인 {#verify}

1. 위의 `curl` 명령어는 `tools` 목록이 포함된 JSON-RPC 결과를 반환합니다. 키의 범위와 일치하는 도구만 표시됩니다.
2. 클라이언트에게 "내 VM 목록 보여줘"라고 요청하세요. 어시스턴트가 `vm_list`을(를) 호출하고 결과를 표시합니다.
3. 포털에서 키의 **Last used** 시간이 갱신되며, 쓰기 호출은 **Key usage log**에 표시됩니다.

## 한도 및 참고 사항 {#limits-notes}

- **브라우저 로그인(OAuth).** 참조 페이지에서는 MCP OAuth를 지원하는 클라이언트를 위한 브라우저 로그인 방법도 설명합니다. 설치된 NexCMP에서 지원 및 테스트된 방법은 API 키(또는 CLI의 경우 `cmp login`)입니다.
- **리셀러 사이트**에는 MCP 섹션이 표시되지 않으며, 고객은 API용 리셀러 도메인을 사용합니다.
- **최소 권한 원칙.** 읽기 범위가 포함된 전용 키를 어시스턴트별로 먼저 생성하고, 필요할 때만 쓰기 범위를 추가하세요.
- 어시스턴트의 액세스를 즉시 차단하려면 **API keys**에서 키를 취소하세요.

## Troubleshooting {#troubleshooting}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| `WWW-Authenticate: Bearer`과(와) 함께 발생하는 401 | 키가 없거나, 잘못되었거나, 세션 토큰인 경우 | `Authorization: Bearer vk_...`을(를) 전송하세요. |
| `Origin`과(와) 관련된 403 | 다른 오리진의 브라우저 페이지 | 데스크톱 또는 CLI 클라이언트를 사용하거나, 관리자에게 오리진(`mcp_allowed_origins`) 허용을 요청하세요. |
| `Mcp-Session-Id`이(가) 포함된 요청의 404 | 세션이 다른 키에 속해 있거나 만료됨 | `initialize`을(를) 다시 실행하세요. |
| `GET /mcp`에서 발생하는 405 | 예상된 동작: 서버에 이벤트 스트림이 없음 | POST만 사용하세요(클라이언트가 자동으로 처리합니다). |
| 도구 목록이 짧음 | 키 범위 또는 모듈 | 키에 범위를 추가하고 모듈을 활성화하세요. |
| `confirm: true`이(가) 필요하다고 응답하는 도구 | 유료, 삭제 또는 민감한 도구 | 사용자가 승인한 후 어시스턴트가 `confirm`을(를) 설정해야 합니다. |
| 429 | MCP 또는 키 속도 제한 | `Retry-After`을(를) 기다리세요. |
| 헤더로 클라이언트가 연결할 수 없음 | 사용자 지정 헤더를 지원하지 않는 클라이언트 | `mcp-remote` 브리지를 사용하세요. |




---

<!-- source: https://nexcmp.com/ko/docs/configure-with-ai/overview/ -->

# AI로 설정하기 {#configure-with-ai}

> **관리자 메뉴 위치:** AI Chat(`/agent`) 및 System › Settings › API & AI agents(`/agent/keys`). 이 페이지의 모든 항목은 관리자 전용입니다.

## 작동 내용 {#what-it-does}

NexCMP 1.4.0부터 AI 어시스턴트에 패널 설정을 요청할 수 있습니다. Proxmox VE 또는 CloudStack 연결, 존 생성, 비용 기반 요금제 테이블 구축, 이메일·결제 및 브랜딩 설정, 고객 검색, 전체 구성 내보내기 등이 가능합니다. 어시스턴트는 고정된 **관리자 도구** 세트를 통해서만 작동합니다. 절대 쉘 권한을 얻지 않으며, 서버의 파일을 읽지 않고, 저장된 비밀번호나 API 키를 볼 수 없습니다.

수십 개의 페이지를 직접 클릭하는 대신 몇 분 만에 초기 설정을 완료하고 싶거나, 여러 설치를 관리하며 구성을 파일로 유지하고 싶을 때 사용하세요.

## 세 가지 사용 방법 {#three-ways-to-use-it}

| 방법 | AI와 대화하는 대상 | 실행 위치 | 시작하기 |
|---|---|---|---|
| **관리자의 AI Chat** | NexCMP 관리자 | 선택한 AI 소스: OpenAI, Anthropic, Gemini 또는 OpenRouter의 API 키, 패널 자체의 AI 공급자, 또는 로그인한 공식 AI CLI | [관리자 내 AI Chat](https://nexcmp.com/ko/docs/configure-with-ai/ai-chat-in-admin/) |
| **MCP를 통한 자체 AI 클라이언트** | Claude Code, Codex CLI, Gemini CLI, Cursor, Claude Desktop, claude.ai 또는 ChatGPT의 사용자 | 사용자의 기기 또는 공급자의 앱에서 `https://cloud.example.com/mcp/admin`에 있는 패널로 연결됨 | [Connect an AI client](https://nexcmp.com/ko/docs/configure-with-ai/mcp-admin/) |
| **코드 기반 구성 (IaC)** | 사용자 또는 스크립트 | YAML 파일과 서버의 `nexcmp config` 명령어 (또는 Import/Export 페이지) | [Configuration as code](https://nexcmp.com/ko/docs/configure-with-ai/config-as-code/) |

세 가지 방법 모두 동일한 도구를 호출하고 동일한 보안 계층을 거치므로 혼용할 수 있습니다. 어시스턴트로 구성을 초안 작성하고, YAML로 내보내고, 편집기에서 검토한 뒤 나중에 적용하세요.

## 보안 모델 {#safety-model}

| 규칙 | 의미하는 바 |
|---|---|
| **범위 (Scopes)** | 키나 연결은 체크한 범위(`admin:read`, `catalog:write`, `infra:write`, `billing:write`, `customers:write`, `settings:write`, `ai:write`, `secrets:write`)로 제한됩니다. 범위가 없으면 호출이 거부됩니다. [Admin API keys](https://nexcmp.com/ko/docs/configure-with-ai/admin-api-keys/#scopes)를 참조하세요. |
| **Expiry** | 모든 키와 연결은 만료됩니다. 생성한 키는 1~90일(기본값 30일) 동안 유지됩니다. OAuth 액세스 토큰은 1시간 동안 유효합니다. |
| **IP 제한 및 속도 제한** | 키는 IP 대역 및 분당 호출 수(기본값 120회)로 제한할 수 있습니다. |
| **2단계 확인** | 금전 이동, 데이터 삭제, 결제 자격 증명 변경 또는 로그인 보안 변경을 수행하는 작업은 먼저 미리보기를 반환하며 승인할 때까지 실행되지 않습니다. AI Chat 내의 모든 변경 사항은 직접 누르는 확인 카드입니다. |
| **키가 절대 할 수 없는 일** | 관리자 생성, 2FA 변경, 키 생성 또는 취소, 고객으로 로그인, 패널 백업·복원·업데이트 등 유사한 작업입니다. 이는 관리자가 직접 수행해야 합니다. |
| **활동 로그** | 허용되거나 거부된 모든 호출은 키, 클라이언트, 도구, IP 및 결과와 함께 기록됩니다. System › Settings › API & AI agents › Activity를 참조하십시오. |
| **비밀 정보는 절대 반환되지 않음** | 비밀번호, API 키와 토큰은 설정할 수 있지만 절대 다시 읽어올 수 없습니다. AI가 보는 답변에는 마스킹된 상태로 표시됩니다. |
| **데모 설치 버전은 읽기 전용입니다** | 데모 패널에서는 모든 쓰기 작업이 `demo_read_only`(으)로 거부됩니다. |

::: important AI가 읽을 수 있는 내용
`admin:read`을(를) 통해 어시스턴트는 고객 이름, 이메일 주소, 잔액 및 결제 기록을 읽을 수 있습니다. 공급업체(OpenAI, Anthropic, Google, OpenRouter)에서 실행되는 AI 소스를 사용하는 경우 질문에 답하기 위해 해당 데이터가 해당 공급업체로 전송됩니다. 어시스턴트에게 필요한 최소한의 권한 범위만 부여하고, 해당 데이터를 신뢰할 수 있는 소스를 선택하세요.
:::

## 빠른 시작 {#quick-start}

1. 관리자에 로그인하고 **AI Chat**을(를) 엽니다. 연결된 AI 소스가 아직 없는 경우 **System › Settings › AI accounts**을(를) 열고 소스를 연결합니다([AI accounts and subscriptions](https://nexcmp.com/ko/docs/configure-with-ai/ai-accounts-and-subscriptions/) 참조).
2. "Check my setup progress"를 입력하고 엔터 키를 누릅니다. 어시스턴트가 [Setup progress checklist](https://nexcmp.com/ko/docs/configure-with-ai/setup-checklist/)을(를) 읽고 남은 작업을 알려줍니다.
3. 다음 단계를 수행하도록 요청합니다. 각 확인 카드를 검토하고 **Confirm**을(를) 눌러 적용합니다.

무엇을 물어봐야 할지 처음 살펴보려면 [Example prompts](https://nexcmp.com/ko/docs/configure-with-ai/example-prompts/)을(를) 참조하세요.

![대화, 도구 결과 및 확인 카드가 표시된 AI Chat 페이지](https://nexcmp.com/ko/docs/images/configure-with-ai/overview-01-ai-chat.webp)

## 한도 및 참고 사항 {#limits-notes}

- **데모 및 읽기 전용.** 데모 패널에서는 페이지가 표시되지만 아무것도 저장할 수 없습니다.
- **셸 없음.** 어시스턴트는 [Connect an AI client](https://nexcmp.com/ko/docs/configure-with-ai/mcp-admin/#tools)에 나열된 관리자 도구만 호출할 수 있습니다. 서버에서 명령을 실행할 수 없습니다.
- **네트워크 및 라우팅 모듈**(BGP, XDP, 인터페이스, NAT 등)은 AI에게 읽기 전용이며, 관리자 계정, 백업, 업데이트와 같은 민감한 영역은 키 접근이 완전히 차단됩니다.
- **가격**은 USD 기준입니다. 플랜 가격은 시간당 달러 단위, 잔액은 센트 단위입니다.
- **비용.** AI 답변 비용은 연결한 AI 소스(API 사용량 또는 자체 구독)에 지불됩니다. AI Chat에서 일일 지출 한도를 설정할 수 있습니다. NexCMP 라이선스 모델은 https://nexcmp.com/pricing을(를) 참조하세요.

## Troubleshooting {#troubleshooting}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| AI Chat에 연결된 AI 소스가 없다고 표시됨 | 관리자 계정에 소스가 설정되지 않음 | System › Settings › AI accounts를 열고 소스를 연결하세요. |
| 어시스턴트가 `insufficient_scope`(으)로 답변함 | 키 또는 연결에 해당 도구에 대한 권한 범위가 없음 | 필요한 권한 범위가 포함된 키를 생성하거나, 다시 연결하여 동의 화면에서 체크합니다. [Admin API keys](https://nexcmp.com/ko/docs/configure-with-ai/admin-api-keys/#errors) 참조. |
| 모든 변경 사항에 확인 카드가 표시됨 | AI Chat에서 예상되는 동작 | **Confirm**을(를) 눌러 적용하거나 **Reject**을(를) 눌러 취소합니다. |
| 쓰기 작업이 `demo_read_only`(으)로 실패함 | 패널이 데모 모드임 | 데모가 아닌 설치 버전을 사용하세요. |


---

<!-- source: https://nexcmp.com/ko/docs/configure-with-ai/ai-chat-in-admin/ -->

# 관리자의 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/ko/docs/configure-with-ai/setup-checklist/) 및 빈 목록 내)을 누르면 준비된 질문과 함께 채팅이 열립니다.

고객을 응대하는 고객용 [AI Chat](https://nexcmp.com/ko/docs/ai/ai-chat/) 및 [AI Agent](https://nexcmp.com/ko/docs/ai/ai-agent/)가 아닙니다.

## 요구 사항 {#requirements}

| 항목 | 요구 사항 |
|---|---|
| 역할 | 로그인한 관리자. 채팅, 키, 환경설정은 관리자 계정에 속하며 다른 관리자는 볼 수 없습니다. |
| 답변 소스 | 연결된 항목이 하나 이상 필요합니다: API 키, 로그인, 패널 자체의 AI 공급자, 또는 로그인한 AI CLI. [AI accounts and subscriptions](https://nexcmp.com/ko/docs/configure-with-ai/ai-accounts-and-subscriptions/)을(를) 참조하세요. |
| 데모 | 데모 패널에서는 예전 채팅을 읽을 수 있지만 메시지를 보낼 수는 없습니다. |

## 답변 소스 선택 {#choose-where-answers-come-from}

입력창 아래의 선택기에서 소스를 선택하세요(연결한 소스들이 표시됩니다). **System › Settings › AI accounts**에서도 기본 소스, 기본 모델, 일일 한도를 설정할 수 있습니다.

| Source | 연결 방법 | 참고 |
|---|---|---|
| OpenAI (ChatGPT 모델) | platform.openai.com에서 API 키를 붙여넣기 | OpenAI 사용량에 따라 과금됩니다. |
| Anthropic (Claude) | console.anthropic.com에서 API 키를 붙여넣기 | Anthropic 사용량에 따라 과금됩니다. |
| Google Gemini | aistudio.google.com의 API 키를 붙여넣거나 **Sign in with Google** 사용 | Google로 로그인을 사용하려면 **직접** 생성한 자체 Google Cloud 프로젝트의 OAuth 클라이언트가 필요합니다. |
| OpenRouter | 키를 붙여넣거나 **Sign in with OpenRouter** 사용 | 하나의 계정으로 여러 모델 사용. |
| 패널 AI 공급자 | System › Settings › AI provider에서 이미 설정됨 | 고객용 AI Chat에서 사용하는 것과 동일한 공급자입니다. [AI provider](https://nexcmp.com/ko/docs/ai/ai-providers/). |
| Claude, ChatGPT 또는 Gemini 구독 | 패널 서버에 공식 CLI가 설치되어 로그인됨 | [AI accounts and subscriptions](https://nexcmp.com/ko/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/ko/docs/images/configure-with-ai/ai-chat-in-admin-01-chat.webp)

메시지당 최대 10회의 도구 라운드가 진행됩니다. 어시스턴트는 채팅의 최근 30개 메시지를 기억합니다. 도구의 결과는 지시사항이 아니라 데이터로 표시되어 모델에 전달됩니다.

## 확인 카드 {#confirmation-cards}

AI Chat에서는 금전적 작업뿐만 아니라 **모든 변경 사항이 카드**로 표시됩니다. 어시스턴트가 제안하고 관리자가 결정합니다.

카드 표시 내용:

- 주의가 필요한 이유를 나타내는 제목(예: "고객 잔액 변경").
- 호출: 메서드 및 경로.
- 변경되는 필드 표: 현재 값과 새로운 값. 비밀 값은 `••••`으로 표시됩니다.
- 카운트다운 (카드는 5분 후 만료됨).
- **Confirm** 및 **Reject**.

**Confirm**을 누르면 패널 자체가 변경 사항을 적용한 후 그 결과를 어시스턴트에 알립니다. 어시스턴트는 이 버튼을 누를 수 없고, API를 통해 승인할 수 없으며, 확인되기 전에는 변경 사항이 적용되었다고 주장하지 않도록 지시받습니다. 페이지를 새로고침하면 아직 유효한 카드가 다시 표시됩니다. 또한 **System › Settings › API & AI agents**의 "Waiting for your confirmation" 아래에도 표시됩니다.

![잔액 변경, 카운트다운, Confirm 및 Reject 버튼이 표시되는 확인 카드](https://nexcmp.com/ko/docs/images/configure-with-ai/ai-chat-in-admin-02-confirm.webp)

## 비밀 값 {#secrets}

비밀번호 및 API 키는 채팅 텍스트를 통해 전달되어서는 안 됩니다. 입력란 옆의 **Secret** 필드(자물쇠 아이콘)를 사용하세요:

1. 자물쇠 아이콘을 클릭하고 **이름**(문자, 숫자, 밑줄, 예: `smtp_password`)과 **값**을 입력합니다.
2. 메시지에서 해당 이름을 참조하세요: "smtp_password 시크릿을 SMTP 비밀번호로 사용하세요".
3. 어시스턴트는 다음과 같이 작성된 비밀 값을 대신하는 플레이스홀더만 볼 수 있습니다:

   ```text
   {{secret:smtp_password}}
   ```

   패널은 도구를 실행하는 시점에 이를 실제 값으로 교체합니다. 이 값은 채팅 기록에 저장되지 않으며 AI 소스로 전송되지도 않습니다.

실수로 키처럼 보이는 내용을 메시지에 붙여넣은 경우, 패널은 이를 동일한 보호된 저장소로 이동시키고 기록에서 마스킹 처리하지만, 이는 어디까지나 안전망일 뿐 방법으로 의존해서는 안 됩니다. 비밀 값은 입력된 대화 및 마지막 메시지 후 최대 1시간 동안만 패널의 메모리에 유지되며, 패널을 재시작해도 지워집니다. 어시스턴트가 요청하는 경우 다시 입력하세요.

비밀 값을 설정하려면 채팅 세션에 대한 `secrets:write` 권한도 필요합니다(아래 참조).

## 채팅 권한 {#permissions-of-the-chat}

각 메시지는 답변이 유지되는 동안(최대 15분)만 존재하는 임시 키로 실행되며, 패널 서버에서만 작동하고 확인 카드를 통해서만 사용할 수 있습니다. 권한 범위는 **System › Settings › AI accounts › Chat session permissions**에서 체크한 항목입니다. `admin:read`은 항상 켜져 있습니다. `secrets:write`를 제외한 모든 범위는 기본적으로 켜져 있으며, 어시스턴트가 (Secret 필드를 통해) 비밀번호와 키를 설정할 수 있게 하려면 `secrets:write`을 체크하세요. 데모 패널에서는 채팅이 읽기 전용입니다.

## 일일 지출 한도 {#daily-spending-cap}

AI Chat은 API 소스 답변의 예상 비용을 합산합니다. 기본 한도는 **관리자 1인당 하루 5 USD**입니다. **AI accounts › Defaults for AI Chat**에서 다른 금액을 설정할 수 있습니다(0은 제한 없음을 의미). 페이지에는 "used today"가 표시됩니다. 한도에 도달하면 다음 날이 되거나 한도를 높일 때까지 채팅에서 새 메시지를 거부합니다(`daily_cap`). AI CLI 구독인 소스는 구독을 통해 청구되므로 집계에 포함되지 않습니다.

## 확인 {#verify}

1. **AI accounts**에서 소스의 **Test**를 클릭합니다. 모델 이름과 밀리초 단위의 응답 시간이 반환됩니다.
2. AI Chat에서 "Check my setup progress"라고 질문합니다. 답변에 [checklist](https://nexcmp.com/ko/docs/configure-with-ai/setup-checklist/)의 단계들이 나열되고 `setup_checklist` 도구 카드가 표시됩니다.
3. 소규모 변경을 요청합니다(예: "Set the brand name to Example Cloud"). 확인 카드가 나타나면 **Confirm**을 누르고 브랜딩 페이지를 확인하세요.
4. **API & AI agents › Activity**에는 채널 `chat`과 함께 호출 내역이 나열됩니다.

## 한도 및 참고 사항 {#limits-notes}

- 어시스턴트에는 셸이 없으며 서버의 파일을 읽을 수 없습니다. 오직 [admin tools](https://nexcmp.com/ko/docs/configure-with-ai/mcp-admin/#tools)만 호출합니다.
- 키로 수행할 수 없는 변경 사항([list](https://nexcmp.com/ko/docs/configure-with-ai/admin-api-keys/#what-a-key-can-never-do))은 AI Chat에서도 수행할 수 없습니다.
- 모델의 작업을 확인하세요. 확인 카드에 전송될 내용이 정확히 표시되므로, 특히 가격과 금액을 주의 깊게 읽어보세요.
- API 답변은 AI 공급업체를 통해 청구됩니다. 한도는 추정치이므로 공급업체 측에서도 지출 한도를 설정하세요.
- CLI 답변은 5분 후에 중단됩니다.

## Troubleshooting {#troubleshooting}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| "오늘의 AI 지출 한도에 도달했습니다" (`daily_cap`) | 일일 한도에 도달했습니다 | AI 계정에서 한도를 상향하거나 내일을 기다리세요. |
| "다른 답변이 아직 실행 중입니다 — 기다리거나 중지 누르기" (`busy`) | 관리자당 한 번에 하나의 답변만 가능 | **Stop**을 누르거나 기다리세요. |
| 선택 도구에 소스가 나타나지 않음 | 연결되지 않았거나 (Claude CLI) "I understand" 스위치가 꺼져 있음 | AI 계정에서 연결하세요. |
| "API 키처럼 보이지 않습니다" | 입력한 키에 공백이 있거나 너무 김 | 키만 복사하여 붙여넣으세요. |
| 테스트 실패 | 잘못된 키, 크레딧 부족 또는 벤더 서버 다운 | 벤더사에서 키와 청구 상태를 확인하세요. |
| 어시스턴트가 작업을 수행할 수 없다고 답변함 | 채팅 세션에 권한(scope)이 없거나 AI 실행이 제한된 작업임 | AI 계정에서 권한을 체크하거나 관리자 패널에서 직접 수행하세요. |
| 카드가 만료되었다고 표시됨 | 5분이 지났음 | 어시스턴트에게 변경 사항을 다시 제안하도록 요청하세요. |
| CLI 소스에서 "usage limit" 또는 "not logged in" 오류 발생 | 구독 한도 또는 세션 문제 | 다시 로그인하거나 기다리세요. [AI accounts and subscriptions](https://nexcmp.com/ko/docs/configure-with-ai/ai-accounts-and-subscriptions/)을 참고하세요. |


---

<!-- source: https://nexcmp.com/ko/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 활성화됨(아래 참조), 서버에서 벤더 및 `nodejs.org` 그리고 npm 레지스트리로의 아웃바운드 HTTPS, 그리고 **2 GB 이상의 RAM** (CLI 실행 시 약 1 GB의 여유 공간 필요; 2 GB 미만인 경우 설치 프로그램이 경고함). Node.js 20 이상이 있으면 사용하며, 그렇지 않으면 설치 프로그램이 체크섬 검사와 함께 Node.js 22를 다운로드합니다. |
| 사용자 컴퓨터의 CLI | CLI를 설치하기 위한 Node.js 20 이상 및 본인의 구독. |

## API 소스 연결 {#connect-an-api-source}

1. **System › Settings › AI accounts**를 열고 **Accounts** 탭에 머뭅니다.
2. 소스 카드에서 **Connect**을 클릭합니다. 새 탭에서 공급자의 키 페이지가 열리면 거기서 키를 생성하세요.
3. 해당 필드에 키를 붙여넣고 저장합니다. 카드가 마지막 네 글자와 함께 연결된 상태를 표시합니다.
4. 다른 모델을 원하면 **default model**을 선택한 다음 **Test**을 클릭합니다. 결과가 "Connected - example-model, 850 ms"와 비슷하게 표시되면 정상입니다.

![API 소스 카드, 연결된 OpenAI 카드, Panel AI 공급자 카드가 있는 AI 계정 페이지](https://nexcmp.com/ko/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)** 아래 카드에 **직접** Google Cloud 프로젝트에서 생성한 OAuth 클라이언트(`.apps.googleusercontent.com`로 끝나는 클라이언트 ID 및 시크릿)를 저장한 후에 나타납니다. NexCMP는 공유 Google 클라이언트를 제공하지 않습니다. |
| 패널 AI 공급자 | System › Settings › AI provider([AI provider](https://nexcmp.com/ko/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/ko/docs/configure-with-ai/ai-chat-in-admin/#daily-spending-cap)을 참조하세요. |
| 채팅 세션 권한 | 어시스턴트가 사용할 수 있는 범위입니다. `admin:read`은 항상 켜져 있고, `secrets:write`은 기본적으로 꺼져 있습니다. [Admin API keys](https://nexcmp.com/ko/docs/configure-with-ai/admin-api-keys/#scopes)를 참조하세요. |

**Save defaults**을 클릭합니다.

## 자체 AI 구독 사용 {#use-your-own-ai-subscription}

별도의 API 키 없이 이미 이용 중인 Claude, ChatGPT 또는 Gemini 플랜을 사용하여 NexCMP를 구동할 수 있습니다. 방법은 두 가지가 있습니다.

### 방법 1 (권장): 본인 컴퓨터의 CLI {#way-1-recommended-the-cli-on-your-own-computer}

자신의 컴퓨터에서 공급업체의 자체 도구를 사용하고, 공급업체의 일반적인 방식으로 자체 계정에 로그인합니다. NexCMP는 수명이 짧은 키로 서명된 MCP 호출만 수신합니다. **AI accounts › Use your own AI subscription**을 열면 도구별로 3단계 과정이 표시됩니다.

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 연결에 대한 모든 세부 정보는 [AI 클라이언트 연결](https://nexcmp.com/ko/docs/configure-with-ai/mcp-admin/)에 나와 있습니다.

동일한 탭에서 OAuth로 로그인하여 별도의 키가 필요 없는 **claude.ai** 및 **ChatGPT** 커넥터용 URL을 확인할 수 있습니다: [OAuth 커넥터](https://nexcmp.com/ko/docs/configure-with-ai/oauth-connectors/).

![7일 키 버튼과 3개 CLI용 설치, 로그인, 연결 명령어가 포함된 Use your own AI subscription 탭](https://nexcmp.com/ko/docs/images/configure-with-ai/ai-accounts-and-subscriptions-02-subscription.webp)

### 방법 2: 패널 서버의 CLI (설치 / 로그인 버튼) {#way-2-the-cli-on-the-panel-server-install-login-buttons}

"CLI를 통한 구독(Claude, ChatGPT, Gemini)" 아래의 카드를 사용하면 NexCMP가 패널 서버에 공식 CLI를 설치하고 자체 로그인 흐름을 열어 주므로, **AI Chat**에서 구독 정보로 답변할 수 있습니다.

**격리 방식.** CLI는 별도의 프로세스(`nexcmp-ai.service`)에서 전용 시스템 사용자 `nexcmp-ai`로 실행되며, sudo 권한이 없고 NexCMP의 데이터 및 설정 폴더에 접근할 수 없으며 메모리 제한이 적용됩니다. 모든 AI Chat 메시지마다 CLI는 허용된 NexCMP MCP 도구(셸 및 파일 도구는 비활성화됨)와 서버 전용 키만을 사용하여 시작됩니다. NexCMP는 CLI의 로그인을 읽거나 복사하지 않으며, CLI는 이를 관리자 계정용 비공개 폴더에 보관합니다.

별도로 활성화할 필요가 없습니다. 패널이 1.4.0 버전 이상으로 설치되거나 업데이트될 때 `nexcmp-ai` 사용자 및 서비스를 자동으로 설정하므로 카드를 바로 사용할 수 있습니다.

**설치 및 로그인 (관리자별):**

1. CLI 카드에서 **Login**을 클릭합니다. CLI가 아직 설치되지 않은 경우 패널이 먼저 설치를 진행합니다. 진행률 표시기와 간단한 로그를 통해 다운로드 과정(필요한 경우 Node.js, 그 후 CLI)이 표시됩니다. 서버의 RAM이 2 GB 미만인 경우 경고가 표시됩니다.
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 구독 카드, Codex 카드의 일회용 코드, 그리고 Claude 카드의 이해 완료 스위치](https://nexcmp.com/ko/docs/images/configure-with-ai/ai-accounts-and-subscriptions-03-cli.webp)

### AI 벤더의 약관 {#terms-of-the-ai-vendors}

소비자 구독을 통한 로그인은 변경될 수 있는 각 벤더의 약관 적용을 받습니다. 아래의 내용은 2026년 10월 기준으로 벤더가 공표한 내용을 요약한 것이며, 법률 자문이나 벤더를 대신하는 공식 성명이 아닙니다. 이 기능을 활성화하기 전에 최신 페이지를 확인하십시오.

| 벤더 | 벤더 페이지의 내용 | 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 계정으로 로그인, 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 러너 소켓의 준비 여부, AI Console의 활성화/비활성화 상태, 각 CLI의 "installed" 또는 "not installed" 여부를 출력합니다. `sudo nexcmp status`은 "AI runner: active"도 함께 보여줍니다.
- 활성화되면 AI Chat 아래에 **AI Console** 탭이 나타납니다. 로그인된 CLI를 선택하고 관리자 비밀번호(사용 중인 경우 2FA 코드 포함)를 다시 입력한 뒤 세션을 엽니다. 여기서 실행하는 명령어는 MCP 도구를 통해서만 NexCMP를 관리할 수 있으며 쉘 및 파일 도구는 비활성화된다는 안내 배너가 표시됩니다.
- 데모 설치 환경에서는 `nexcmp-ai` 사용자를 생성하지 않습니다.

![CLI 선택기, 비밀번호 필드 및 MCP 전용 경고 배너가 있는 AI Console 시작 화면](https://nexcmp.com/ko/docs/images/configure-with-ai/ai-accounts-and-subscriptions-04-console.webp)

## 확인 {#verify}

1. API 소스에서 **Test**를 실행하면 모델 이름이 반환됩니다.
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는 '설치'를 클릭한 시점에 벤더의 공식 퍼블릭 패키지로부터 설치됩니다.

## Troubleshooting {#troubleshooting}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| 로그인이 비활성화되고 카드가 "AI tools are not ready on the server yet"라고 표시됨 | `nexcmp-ai` 서비스가 실행 중이지 않음 | 패널을 최신 버전으로 업데이트한 후 `sudo nexcmp status`을(를) 확인하세요. 읽기 전용 데모에서는 정상적인 동작입니다. |
| "이 서버에 AI tools가 아직 설치되지 않았습니다" | `nexcmp-ai` 서비스가 실행 중이지 않음(구버전 패널 또는 데모 패널) | 패널을 업데이트한 후 `sudo nexcmp ai-console install claude`(또는 `codex`, `gemini`)을(를) 실행하세요. |
| 2 GB 미만의 RAM에 대한 경고 | 서버 사양이 낮음 | 설치가 느려지거나 실패할 수 있습니다. 메모리를 늘리거나 방식 1을 사용하세요. |
| "Node.js download checksum mismatch" 또는 "download failed" | 서버가 nodejs.org에 도달할 수 없거나 프록시가 다운로드를 변조함 | 아웃바운드 HTTPS를 허용하고 다시 시도하세요. |
| 설이 오류로 끝남 | npm이 패키지를 설치할 수 없음 | 카드의 로그를 읽고, npm 레지스트리로의 아웃바운드 접근을 확인한 후 다시 시도하세요. |
| 로그인이 오류로 끝나거나 시간 초과됨 | 10분 제한 시간이 지났거나 코드가 잘못됨 | **Login**을(를) 다시 클릭하고 더 빠르게 완료하세요. |
| AI Chat에서 Claude 소스가 누락됨 | **I understand** 스위치가 꺼져 있거나 CLI가 로그인되지 않음 | 벤더 페이지를 읽은 후 스위치를 켜고 로그인하세요. |
| Gemini에서 "Sign in with Google"이 누락됨 | 저장된 Google OAuth 클라이언트가 아직 없음 | 자체 Google Cloud 프로젝트에서 클라이언트를 생성하고 카드의 **Set up Google sign-in (optional)** 아래에 저장하거나, 대신 API 키를 붙여넣으십시오. |
| "Sign in with OpenRouter" 실행 시 오류 발생 | 취소했거나 팝업이 차단됨 | 팝업을 허용하고 다시 시도하십시오. |
| CLI 응답에 "usage limit"이 표시됨 | 요금제의 할당량이 모두 소진됨 | 잠시 기다리거나 소스를 변경하십시오. |




---

<!-- source: https://nexcmp.com/ko/docs/configure-with-ai/admin-api-keys/ -->

# 관리자 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 클라이언트 또는 스크립트가 부여된 권한에 한해 패널을 관리할 수 있습니다. `/v1/admin/` 경로의 관리자 API 및 관리자 MCP 엔드포인트 `/mcp/admin`에서 작동하며, 그 외 다른 곳에서는 작동하지 않습니다.

::: info 고객 키와 다름
고객은 `vk_`(으)로 시작하는 키를 고객 포털([API keys and scopes](https://nexcmp.com/ko/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](#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/ko/docs/images/configure-with-ai/admin-api-keys-01-create.webp)

![복사 버튼과 경고와 함께 새 키를 한 번만 보여주는 대화상자](https://nexcmp.com/ko/docs/images/configure-with-ai/admin-api-keys-02-shown-once.webp)

## Scopes {#scopes}

키는 허용된 범위의 도구와 엔드포인트만 사용할 수 있습니다. 쓰기 권한 범위에는 읽기 권한이 포함되지 않으므로, 읽기와 쓰기가 모두 필요한 키는 `admin:read`도 함께 필요합니다.

| Scope | 허용하는 작업 |
|---|---|
| `admin:read` | 설정, 카탈로그, 고객, 빌링 및 로그 읽기. 보안 정보는 절대 반환되지 않습니다. |
| `catalog:write` | 플랜, OS 템플릿, 할당량, 할인 코드. |
| `infra:write` | 인프라 소스(CloudStack, Proxmox), 영역, 서버. |
| `billing:write` | 결제 게이트웨이, 통화, 인보이스, 잔액. 금액 관련 작업은 확인이 필요합니다. |
| `customers:write` | 고객 및 리셀러. |
| `settings:write` | 일반 설정, 브랜딩, 이메일, 법적 페이지, 모듈, 알림. |
| `ai:write` | AI 제공자 및 AI 기능. |
| `secrets:write` | 비밀번호 및 API 키를 작성합니다. 설정은 가능하지만 읽을 수는 없습니다. |

::: tip 비밀번호 설정에는 두 가지 범위가 필요합니다
비밀번호, API 키 또는 토큰 값을 전송하는 모든 호출(SMTP 비밀번호, 결제 키, 텔레그램 봇 토큰, AI 제공자 키, CloudStack 또는 Proxmox 자격 증명)에는 `secrets:write` **및** 해당 영역의 범위(예: SMTP의 경우 `settings:write`)가 필요합니다. 비밀번호를 직접 입력하려면 `secrets:write`를 비워두고 관리자 페이지에서 입력하세요.
:::

## 키 취소 {#revoke-a-key}

1. 테이블에서 키를 찾습니다(상태는 **Active**, **Expired** 또는 **Revoked**이며, **Last used**는 시간과 클라이언트를 표시합니다).
2. **Revoke**를 클릭하고 확인합니다.

키가 즉시 작동을 멈춥니다. 취소는 영구적이므로 다시 필요한 경우 새 키를 만드세요.

## 키가 절대 할 수 없는 일 {#what-a-key-can-never-do}

어떤 범위를 가지든 키는 이러한 영역에 절대 접근할 수 없습니다. 관리자 로그인이 필요합니다.

- 관리자 사용자 생성 또는 변경, 2FA 및 로그인 보안, 관리자 세션, 관리자 API 토큰.
- 관리자 키, OAuth 연결, AI 계정 생성·목록 조회·취소 또는 AI 콘솔 사용.
- 패널 백업 또는 복원, 업데이트, 라이선스 변경.
- 고객 또는 리셀러로 로그인, 고객 콘솔 열기, VM 자격 증명 또는 kubeconfig 읽기, SSH 키 설정, 비밀번호 전송 또는 재설정.
- 네트워크 및 라우팅 모듈(BGP, FRR, RTBH, XDP, 인터페이스, 정적 및 정책 라우트, NAT) 또는 외부 에이전트 및 포털 통합 변경. 이는 읽기 전용입니다.
- `demo_*`, `admin_*`, 호스트 목록, 패스키, 재인증 및 캡차 비밀번호 등의 설정 변경.

규칙에 포함되지 않은 모든 항목은 쓰기의 경우 기본적으로 차단되며, 읽기의 경우 `admin:read`을 통해 읽을 수 있습니다.

### 확인이 필요한 작업 {#actions-that-need-your-confirmation}

다음 작업은 미리보기를 승인한 후에만 성공합니다([Two-step confirmation](#two-step-confirmation) 참조):

- 고객 잔액 또는 리셀러 월렛 변경, 자금 지금, 결제 기록, 환율.
- 가격 변경(플랜 가격, 대량 플랜 생성, 이미지 및 스토리지 가격 책정) 및 할인 또는 금액 코드 생성.
- 결제 게이트웨이 자격 증명 또는 CloudStack 연결 저장.
- 모든 항목 삭제, 고객 차단 또는 삭제, 고객 한도 변경, 리셀러 일시 정지 또는 종료.
- 고객 서버 제어 또는 고객을 위한 유료 서버 생성.
- 일반 설정을 통한 사이트 전체 스위치, 로그인 보안 설정 또는 결제 설정 변경.

## 2단계 확인 {#two-step-confirmation}

호출에 확인이 필요한 경우 아직 변경되지 않습니다. 응답은 HTTP **428**과 `confirm_required`, `confirm_token`, `preview`(메서드, 경로, 사유, 새 값 및 가능한 경우 현재 값) 및 `expires_in: 300`을 반환합니다.

1. 클라이언트가 미리보기를 표시합니다.
2. 승인 후, 헤더 `X-Confirm-Token: <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 이상)만 필터링하며, 기간을 최근 1시간, 24시간 또는 7일로 제한할 수 있습니다. NexCMP는 최신 200,000개의 항목을 보관합니다. 키를 통해 수행된 변경 사항은 `ak:<admin>/<key name>` 이름으로 Logs › Admin actions에도 표시됩니다.

![상태, 클라이언트, 도구 및 IP가 표시된 Activity 탭 목록](https://nexcmp.com/ko/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`)은 [Connect an AI client](https://nexcmp.com/ko/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/ko/docs/configure-with-ai/oauth-connectors/))에서 취소할 수 있습니다.




---

<!-- source: https://nexcmp.com/ko/docs/configure-with-ai/mcp-admin/ -->

# 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 클라이언트가 도구를 호출할 수 있습니다. 패널은 `https://cloud.example.com/mcp/admin`에서 관리자 MCP 서버를 제공합니다. 자신의 AI 도구를 이에 연결하고 자연어로 질문하세요: "설정해야 할 남은 항목은 무엇인가요?", "Proxmox 클러스터 추가", "40% 마진으로 플랜 생성". 클라이언트는 아래 관리자 도구를 호출하며, 패널은 범위를 확인하고 위험한 작업 전 확인을 요청하며 모든 호출을 기록합니다.

::: info 두 개의 MCP 엔드포인트
`/mcp`은 **고객** 엔드포인트(고객 API 키, `vk_`; [MCP server](https://nexcmp.com/ko/docs/developers/mcp/) 참조)입니다. `/mcp/admin`은 여기에 설명된 **관리자** 엔드포인트입니다(관리자 키 `ak_` 또는 OAuth). 둘은 절대 혼용되지 않습니다. 관리자 도구는 `/mcp`에 표시되지 않으며, `/mcp/admin`은 관리자 키만 허용합니다.
:::

## 요구 사항 {#requirements}

| 항목 | 요구 사항 |
|---|---|
| Endpoint | 패널 자체 도메인의 `https://cloud.example.com/mcp/admin`입니다. **Connect an AI** 탭에서 정확한 URL을 복사하십시오. 동일한 페이지에 서버 자체에서 실행되는 도구용 로컬 URL(`http://127.0.0.1:<port>/mcp/admin`)도 나열되어 있습니다. |
| 자격 증명 | 원하는 범위가 설정된 [admin API key](https://nexcmp.com/ko/docs/configure-with-ai/admin-api-keys/)(`ak_...`), **또는** 웹 코넥터용 OAuth 로그인([OAuth connectors](https://nexcmp.com/ko/docs/configure-with-ai/oauth-connectors/)). |
| 클라이언트 | **Streamable HTTP** 전송과 사용자 지정 `Authorization` 헤더를 지원하는 모든 MCP 클라이언트. 프로토콜 버전 2025-11-25, 2025-06-18 및 2025-03-26. |
| 네트워크 | 패널 앞에 자체 리버스 프록시를 배치하는 경우 `/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/ko/docs/configure-with-ai/admin-api-keys/)를 참조하세요.
2. **Connect an AI** 탭을 엽니다. "key created" 대화상자가 열려 있는 동안에는 아래의 모든 스니펫에 실제 키가 이미 포함되어 있습니다. 그렇지 않은 경우 자리표시자 `ak_YOUR_KEY`가 표시됩니다.
3. 클라이언트에 맞는 스니펫을 복사하여 아래 설명된 대로 실행하거나 붙여넣습니다.

![MCP URL이 포함된 Connect an AI 탭과 클라이언트당 복사 버튼이 있는 카드 하나](https://nexcmp.com/ko/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에서 커넥터 설정으로 이동하여 커스텀 커넥터를 추가하고, `https://cloud.example.com/mcp/admin`을(를) 붙여넣은 다음, NexCMP 관리자 계정으로 로그인하고 동의 화면에서 권한을 선택합니다. 상세 정보: [OAuth connectors](https://nexcmp.com/ko/docs/configure-with-ai/oauth-connectors/).

### ChatGPT (developer mode) {#chatgpt-developer-mode}

키가 필요하지 않습니다. ChatGPT에서 개발자 모드를 켜고, URL `https://cloud.example.com/mcp/admin`(으)로 MCP 커넥터를 추가한 다음, OAuth를 선택하고 NexCMP 관리자 계정으로 로그인합니다. 상세 정보: [OAuth connectors](https://nexcmp.com/ko/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]` 아래에 추가하여 호출을 허용할 수 있습니다. 결제, 보안 및 삭제 작업에 대해서는 패널이 여전히 미리보기를 반환하고 확인을 요청합니다. 30/10/2026에 Codex CLI 0.166으로 확인되었습니다.
:::

### 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"`을(를) 사용하면 파일에 키를 넣지 않을 수 있습니다. 2026/10/30 기준 Gemini CLI 0.66에서 확인됨.

### 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",
)
```

완전한 실행 (2026/10/30 기준 `openai-agents` 0.24에서 확인됨 — 읽기 도구, 그리고 확인 미리보기를 반환하고 `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/<name>`은(는) 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 결과입니다.
2. 클라이언트에게 "run system_health"를 실행하도록 요청합니다. 경고, 연결된 인프라의 상태, 결제, 이메일, AI 및 라이선스 상태를 반환합니다.
3. **API & AI agents › Activity**를 엽니다. 클라이언트 이름 및 `mcp`과 함께 호출 목록이 표시됩니다.
4. 서버에서 `sudo nexcmp status`은(는) 엔드포인트가 응답할 때 `ready`이라고 말하는 "MCP admin" 줄을 출력합니다(키가 없는 HTTP 401은 정상 상태임).

## 도구 {#tools}

서버는 58개의 도구를 제공합니다. 클라이언트는 키의 스코프가 허용하는 도구만 볼 수 있습니다. 읽기 도구에는 `admin:read`이(가) 필요하고, 쓰기 도구에는 자체 스코프가 필요합니다. 쓰기 도구에는 선택적 `confirm_token` 인수도 제공됩니다([Confirmation](#confirmation-confirm-token) 참조). 인수는 각 도구의 스키마에 대해 검사되며, 알 수 없거나 오타가 있는 인수는 이름을 지정하는 메시지와 함께 거부됩니다.

가격은 USD 기준입니다. 플랜 가격은 시간당 달러(`hourly_usd`), 잔액은 센트 단위입니다. 보안 비밀은 설정할 수 있지만 절대 반환되지 않습니다.

### 개요 및 로그 {#overview-and-logs}

| 도구 | 작동 내용 | Scope | 데이터 변경 | 사용자에게 확인 |
|---|---|---|---|---|
| `system_health` | 주의가 필요한 경고, 인프라 상태, 결제, 이메일, AI, 라이선스 및 업데이트 상태. | `admin:read` | 아니오 | 아니오 |
| `setup_checklist` | 구성된 항목과 남은 항목: 라이선스, 인프라, 영역, OS 템플릿, 플랜, 결제, 이메일, 브랜딩, 법적 고지, 테스트 주문. | `admin:read` | 아니오 | 아니오 |
| `license_status` | 라이선스 상태 및 최신 NexCMP 버전 존재 여부. | `admin:read` | 아니오 | 아니오 |
| `audit_search` | 관리자 감사 로그 및 API 키 로그 검색. | `admin:read` | 아니오 | 아니오 |

### 설정, 브랜딩, 법적 고지, 모듈 {#settings-branding-legal-modules}

| 도구 | 작동 내용 | Scope | 데이터 변경 | 사용자에게 확인 |
|---|---|---|---|---|
| `settings_get` | 일반 설정 읽기(`keys` 필터; 후행 `*`은(는) 접두사와 일치함). | `admin:read` | 아니오 | 아니오 |
| `settings_update` | 플랫 `values` 객체에서 일반 설정을 변경합니다. `settings_get`에 나열된 키만 허용됩니다. | `settings:write` | 예 | 키가 결제, 로그인 보안, 사이트 전체 스위치 또는 가격에 영향을 미치는 경우 |
| `branding_get` | 브랜드 이름, 색상, 표시 통화, 판매자 이름, 로고 및 파비콘 URL. | `admin:read` | 아니오 | 아니오 |
| `branding_update` | 브랜드 이름(최대 60자), 색상(`#rrggbb`), 표시 통화(`usd` 또는 `vnd`) 및 판매자 이름을 설정합니다. | `settings:write` | 예 | 아니오 |
| `branding_logo_set` | https URL 또는 base64(PNG, JPEG, WEBP, ICO 또는 SVG, 최대 512 KB)를 통해 밝거나 어두운 로고 또는 파비콘을 업로드합니다. | `settings:write` | 예 | 아니오 |
| `legal_get` | 이용 약관 및 개인정보 처리방침(영어 및 베트남어)과 중립적인 기본값. | `admin:read` | 아니오 | 아니오 |
| `legal_update` | 약관 및 개인정보 텍스트(간단한 마크다운, HTML 없음, 각각 최대 50 KB)를 설정합니다. 빈 문자열은 기본값으로 복원합니다. | `settings:write` | 예 | 아니오 |
| `modules_get` | 어떤 선택적 모듈이 켜져 있고 어떤 것을 전환할 수 있는지. | `admin:read` | 아니오 | 아니오 |
| `module_set` | 선택적 모듈을 켜거나 끕니다(`key`은 `settable` 중 하나여야 함). | `settings:write` | 예 | 아니오 |

### 이메일 및 알림 {#email-and-alerts}

| 도구 | 작동 내용 | Scope | 데이터 변경 | 사용자에게 확인 |
|---|---|---|---|---|
| `smtp_get` | 발신 이메일 설정(비밀번호 마스킹됨) 및 큐 상태. | `admin:read` | 아니오 | 아니오 |
| `smtp_configure` | SMTP 서버를 설정합니다. 호스트, 포트 또는 보안을 변경하려면 비밀번호를 다시 입력해야 합니다. | `settings:write`(비밀번호의 경우 `secrets:write` 추가) | 예 | 아니오 |
| `smtp_test` | 저장된 설정으로 실제 테스트 이메일을 보냅니다. | `settings:write` | 이메일 발송 | 아니오 |
| `telegram_get` | 관리자 알림 채널(채팅 ID; 봇 토큰은 절대 반환되지 않음). | `admin:read` | 아니오 | 아니오 |
| `telegram_configure` | 텔레그램 알림 채널(봇 토큰 및 채팅 ID)을 추가 또는 업데이트하고 관리자 알림을 켜거나 끕니다. | `settings:write`(토큰의 경우 `secrets:write` 추가) | 예 | 아니오 |
| `telegram_test` | 텔레그램 채널로 테스트 메시지를 보냅니다. | `settings:write` | 메시지 발송 | 아니오 |

### 결제 및 통화 {#payments-and-currency}

| 도구 | 작동 내용 | Scope | 데이터 변경 | 사용자에게 확인 |
|---|---|---|---|---|
| `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}

| 도구 | 작동 내용 | Scope | 데이터 변경 | 사용자에게 확인 |
|---|---|---|---|---|
| `cloudstack_get` | 저장된 CloudStack 엔드포인트, 존 및 네트워크 ID(키 마스킹됨). | `admin:read` | 아니오 | 아니오 |
| `cloudstack_test` | 저장하지 않고 API 키와 시크릿으로 엔드포인트를 테스트하며 존을 나열합니다. | `infra:write`(키를 전달하므로 `secrets:write` 추가) | 아니오 | 아니오 |
| `cloudstack_connect` | CloudStack 연결을 저장합니다. | `infra:write` (+ `secrets:write`) | 예 | 항상 |
| `proxmox_list` | 소스 및 상태와 함께 추가된 Proxmox VE 클러스터. | `admin:read` | 아니오 | 아니오 |
| `proxmox_add` | API 토큰(`user@realm!tokenid`) 및 시크릿을 사용하여 Proxmox VE 클러스터를 추가합니다. | `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}

| 도구 | 작동 내용 | Scope | 데이터 변경 | 사용자에게 확인 |
|---|---|---|---|---|
| `templates_list` | 고객이 설치할 수 있는 OS 템플릿. | `admin:read` | 아니오 | 아니오 |
| `templates_sync` | CloudStack에서 OS 템플릿을 가져옵니다. | `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` | 비용과 마진율을 사용하여 제공 상품(또는 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}

| 도구 | 작동 내용 | Scope | 데이터 변경 | 사용자에게 확인 |
|---|---|---|---|---|
| `customers_search` | 이메일, 이름 또는 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 공급자 {#ai-provider}

| 도구 | 작동 내용 | Scope | 데이터 변경 | 사용자에게 확인 |
|---|---|---|---|---|
| `ai_provider_get` | 고객 AI Chat 및 AI Agent가 사용하는 OpenAI 호환 제공자입니다(키 마스킹됨). | `admin:read` | 아니오 | 아니오 |
| `ai_provider_set` | 제공자 설정: 기본 URL, 모델, API 키, 대체 모델, 추론 노력도, 활성화 여부. | `ai:write` (키의 경우 `secrets:write` 추가) | 예 | 아니오 |
| `ai_provider_test` | 작동하는지 확인하기 위해 저장된 제공자에게 질문을 하나 합니다. | `ai:write` | 아니오 | 아니오 |

### 설정 파일 {#configuration-files}

| 도구 | 작동 내용 | Scope | 데이터 변경 | 사용자에게 확인 |
|---|---|---|---|---|
| `config_export` | 설정을 YAML로 내보냅니다(비밀 값은 `secret://` 참조로 변경됨). | `admin:read` | 아니오 | 아니오 |
| `config_plan` | YAML 설정과 라이브 패널을 비교하고 변경될 내용을 나열합니다. | `admin:read` | 아니오 | 아니오 |
| `config_apply` | YAML 설정을 섹션별로 적용합니다. 각 변경 사항은 일반적인 범위 및 확인 규칙을 따릅니다. | `admin:read` + 모든 변경 사항의 범위 | 예 | 변경 당 |

파일 형식은 [Configuration as code](https://nexcmp.com/ko/docs/configure-with-ai/config-as-code/)을(를) 참조하세요.

## 프롬프트 {#prompts}

서버는 클라이언트가 단축키로 표시할 수 있는 기성 프롬프트 3개도 제공합니다.

| 프롬프트 | 인수 | AI에게 수행하도록 요청하는 작업 |
|---|---|---|
| `initial-setup` | none | `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 1GB당, 디스크 1GB당 월 비용을 요청하고, 비용, 월별 가격 및 시간당 가격이 포함된 미리보기 테이블을 표시하고, 승인 후 플랜을 생성합니다. |

## 확인 (`confirm_token`) {#confirmation-confirm-token}

자금을 이동하거나, 데이터를 삭제하거나, 결제 자격 증명을 변경하거나, 로그인 보안을 변경하는 작업은 2단계로 진행됩니다.

1. 첫 번째 호출에서는 아무것도 변경되지 않습니다. 도구 결과는 "CONFIRMATION REQUIRED"로 시작하며 **미리보기**(호출될 내용, 민감한 이유, 새 값 및 현재 값)와 `confirm_token`을(를) 포함합니다.
2. 클라이언트는 사용자에게 미리보기를 표시해야 합니다. 사용자가 승인한 경우에만 동일한 인수에 `confirm_token`을(를) 더하여 동일한 도구를 다시 호출합니다.
3. 토큰은 정확히 해당 요청에 한해 한 번만 작동하며 5분 후에 만료됩니다.

AI가 도구 결과를 지침이 아닌 데이터로 취급하고, 승인하지 않은 토큰으로 호출을 다시 반복하지 않도록 서버 지침에 설정되어 있습니다. 사용자가 보안의 마지막 보루이므로 미리보기를 확인하세요.

::: warning 자동 승인 금지
일부 클라이언트는 모든 도구 호출을 자동으로 승인할 수 있습니다. 쓰기 도구의 경우 호출별 승인을 유지하거나 읽기 전용 키를 사용하여 AI의 잘못된 계획이 패널에 무단으로 적용되지 않도록 하세요.
:::

## 동작 방식 {#how-it-works}

| 항목 | Detail |
|---|---|
| 전송 | `POST /mcp/admin`(JSON-RPC 2.0 메시지 포함), 응답은 `application/json`입니다. 배치당 최대 20개의 메시지입니다. `GET /mcp/admin`는 405(서버 스트림 없음)를 반환하고, `DELETE /mcp/admin`은 세션을 종료합니다. |
| 인증 | `Authorization: Bearer ak_...`(수동 키 또는 OAuth 액세스 토큰). 자격 증명이 누락되거나 잘못된 경우 `WWW-Authenticate: Bearer ... resource_metadata=...`과 함께 401 오류가 반환되어 OAuth 클라이언트가 자체적으로 로그인을 시작할 수 있습니다. |
| 세션 | `Mcp-Session-Id`은 `initialize`에서 발급되며, 해당 키에 바인딩되고 24시간 동안 유효합니다. |
| 기능 | 도구 및 프롬프트. 리소스는 없음. |
| 크기 | 요청 본문은 최대 1 MB이며, 도구 결과는 약 100 KB 이후 잘립니다. |
| 출처 | 다른 사이트에서 `Origin` 헤더를 포함하여 보낸 요청은 거부됩니다(`origin_not_allowed`). 명령줄 및 데스크톱 클라이언트는 헤더를 보내지 않습니다. |
| REST와 동일한 관문 | 각 도구 호출은 사용자의 키를 사용하여 패널 자체의 요청 파이프라인을 통해 다시 전송되므로, 범위, IP 대역, 속도 제한, 확인 및 활동 로그가 직접 API 호출과 정확히 동일하게 적용됩니다. |

## 한도 및 참고 사항 {#limits-notes}

- 볼 수 없는 도구는 권한을 부여하지 않은 범위입니다. 새 키에 해당 범위를 추가하세요.
- AI 클라이언트를 통해 비밀번호나 API 키를 설정한다는 것은 해당 비밀번호나 API 키가 해당 AI를 거쳐간다는 뜻입니다. 원하시는 경우 `secrets:write`을 끄고 관리자 페이지에서 직접 비밀번호를 입력하거나, AI Chat **Secret** 필드(관리자 페이지의 [AI Chat](https://nexcmp.com/ko/docs/configure-with-ai/ai-chat-in-admin/#secrets)) 또는 `secret://` 참조([Configuration as code](https://nexcmp.com/ko/docs/configure-with-ai/config-as-code/#secrets))를 사용하세요.
- 클라이언트는 세션을 공유하지 않으며, 각 연결은 `initialize`으로 시작합니다.
- AI 클라이언트의 연결을 즉시 차단하려면 **API & AI agents**에서 키를 취소하세요.

## Troubleshooting {#troubleshooting}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| 401 `invalid_key` | 잘못되었거나 잘렸거나 관리자 권한이 아닌 키(예: `vk_` 키) | `ak_` 키를 사용하세요. |
| 401 `key_expired` 또는 `key_revoked` | 키가 만료되었거나 취소됨 | 새 키를 생성하세요. |
| 403 `ip_not_allowed` | 사용자의 IP가 키의 허용 IP 대역에 포함되지 않음 | 허용된 IP에서 연결하세요. |
| 403 `origin_not_allowed` | 다른 출처의 브라우저 페이지가 엔드포인트를 호출함 | 데스크톱 또는 CLI 클라이언트를 사용하세요. |
| `Mcp-Session-Id`이(가) 포함된 요청의 404 | 세션이 다른 키에 속해 있거나 만료됨 | `initialize`을 다시 보내세요. |
| 400 지원되지 않는 `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 및 리버스 프록시를 확인하세요. |

모든 오류 코드는 [Admin API keys](https://nexcmp.com/ko/docs/configure-with-ai/admin-api-keys/#errors)에서 확인하세요.




---

<!-- source: https://nexcmp.com/ko/docs/configure-with-ai/oauth-connectors/ -->

# claude.ai 및 ChatGPT 커넥터 {#claude-ai-and-chatgpt-connectors}

> **관리자 위치:** System › Settings › API & AI agents (`/agent/keys`), **Connected apps** 탭. 동의 화면은 커넥터가 접근을 요청할 때 `/agent/consent`에서 열립니다 (메뉴에는 없습니다).

## 작동 내용 {#what-it-does}

웹 AI 앱은 디스크에서 키를 읽을 수 없습니다. **OAuth**를 통해 연결됩니다. 패널의 MCP URL을 추가하면 앱이 로그인을 위해 자체 관리자로 리디렉션하고, 앱이 수행할 작업과 유지 기간을 선택하면 앱이 수명이 짧은 토큰을 받습니다. 키를 복사하거나 붙여넣지 않으며, 언제든지 앱을 차단할 수 있습니다.

claude.ai 커스텀 커넥터, ChatGPT 개발자 모드 커넥터, 그리고 동적 클라이언트 등록을 지원하는 기타 모든 MCP 클라이언트에 이를 사용하세요. 명령줄 도구도 동일한 흐름을 사용할 수 있지만, [admin API key](https://nexcmp.com/ko/docs/configure-with-ai/admin-api-keys/)가 더 간단합니다.

## 요구 사항 {#requirements}

| 항목 | 요구 사항 |
|---|---|
| URL | `https://cloud.example.com/mcp/admin`, 인터넷에서 접근 가능해야 함 (벤더 서버가 연결됨). |
| 리버스 프록시 | 패널 앞에 자체 프록시를 배치하는 경우, `/mcp/admin`, `/oauth-admin/` 및 `/.well-known/` 경로를 패널로 전달해야 합니다. |
| 귀하 | 동의 화면에 사용하는 **동일한 브라우저**에서 NexCMP 관리자에 로그인한 상태여야 합니다. |
| 클라이언트 | Streamable HTTP를 통한 MCP, PKCE (S256)가 포함된 OAuth 2.1 및 동적 클라이언트 등록을 지원합니다. |

## 연결 {#connect}

1. AI 앱에서 커스텀 MCP 커넥터를 추가하고 `https://cloud.example.com/mcp/admin`을(를) 붙여넣습니다. claude.ai에서는 커넥터 설정(커스텀 커넥터 추가)에 있고, ChatGPT에서는 개발자 모드(MCP 커넥터 추가, 인증 OAuth)에 있습니다.
2. 앱에서 **Sign in**(또는 "Connect")을 선택합니다. 브라우저에 NexCMP 관리자 동의 화면이 열립니다. 로그인되어 있지 않은 경우 먼저 로그인하면 화면이 계속 진행됩니다.
3. 카드를 읽어보세요: "**Example AI app** wants to manage this NexCMP admin" (요청하는 앱 이름) 및 다시 리디렉션될 주소가 표시됩니다.
4. 부여할 범위를 체크하세요. 앱이 요청한 항목은 미리 체크되어 있으며, 요청된 항목이 없으면 `admin:read`만 체크됩니다. [Scopes](https://nexcmp.com/ko/docs/configure-with-ai/admin-api-keys/#scopes)를 참조하세요.
5. 연결 유지 기간을 선택하세요: **7**, **30** 또는 **90**일 (기본값 30).
6. **Allow**를 클릭합니다. 브라우저가 앱으로 돌아가며 이제 연결됩니다. 거부하려면 **Deny**를 클릭합니다.

![AI 앱 허용을 요청하는 동의 화면으로, 범위 체크박스, 기간 선택, 허용 및 거부 버튼이 포함됨](https://nexcmp.com/ko/docs/images/configure-with-ai/oauth-connectors-01-consent.webp)

::: important 키와 마찬가지로 범위 선택
작업을 수행하는 데 필요한 최소한의 집합을 부여하세요. 자금, 삭제 및 보안 작업은 여전히 미리원에서 중지되며 승인이 필요하지만, `settings:write`이(가) 포함된 연결은 브랜딩과 이메일을 변경할 수 있습니다.
:::

## 관리 및 해제 {#manage-and-revoke}

**System › Settings › API & AI agents › Connected apps**를 엽니다. 테이블에는 연결한 모든 앱(애플리케이션, 범위, 연결 시점, 만료 시점, 마지막 사용 시점)이 나열됩니다.

앱을 차단하려면 **Revoke**를 클릭하고 확인합니다. 해당 토큰 즉시 작동이 중지되며, 앱은 다시 연결하려면 동의 과정을 다시 거쳐야 합니다.

![하나의 AI 앱과 해당 범위, 만료일 및 해제 버튼이 나열된 Connected apps 탭](https://nexcmp.com/ko/docs/images/configure-with-ai/oauth-connectors-02-connected-apps.webp)

## 작동 방식 {#how-the-flow-works}

| 단계 | Detail |
|---|---|
| 탐색 | 앱이 `/.well-known/oauth-protected-resource/mcp/admin`을(를) 읽고 이어 `/.well-known/oauth-authorization-server/oauth-admin`을(를) 읽습니다. 발급자는 `https://cloud.example.com/oauth-admin`입니다. |
| 등록 | 앱이 자체적으로 등록합니다(`POST /oauth-admin/register`, RFC 7591). 퍼블릭 클라이언트만 지원됩니다(클라이언트 시크릿 없음). 리디렉션 주소는 `https`이거나 동일한 컴퓨터의 경우 `http`(루프백)여야 합니다. |
| 인증 | `GET /oauth-admin/authorize`(PKCE 메서드 `S256` 사용). `resource` 매개변수는 전송 시 이 패널의 `/mcp/admin` URL이어야 합니다. 요청은 10분 동안 유효하며 요청을 시작한 브라우저에 연결됩니다. |
| Consent | 범위와 기간(위)을 선택합니다. 권한 부여 코드는 60초 동안 유효하며 한 번만 작동합니다. |
| Tokens | `POST /oauth-admin/token`은(는) **액세스 토큰**(`ak_o...` 키, 1시간 동안 또는 연결이 종료될 때 중 빠른 시점까지 유효)과 **리프레시 토큰**(`akr_...`)을 반환합니다. 갱신할 때마다 새로운 리프레시 토큰이 반환되며 이전 토큰은 작동을 멈춥니다. 연결은 선택한 일수가 지나면 종료됩니다. |
| Revocation | 연결된 앱의 **Revoke** 또는 앱에서 `POST /oauth-admin/revoke` 호출(RFC 7009). |

액세스 토큰은 부여한 범위가 지정된 관리자 키처럼 작동합니다. 동일한 범위 규칙, 확인,율 제한 및 활동 로그가 적용됩니다. 호출 내역은 **Activity** 탭에 표시됩니다.

## 확인 {#verify}

1. 앱에서 "run system_health"(또는 "what tools do you have?")라고 질문합니다. 앱은 범위에서 허용하는 도구([the tool list](https://nexcmp.com/ko/docs/configure-with-ai/mcp-admin/#tools))를 나열합니다.
2. **Connected apps**를 엽니다. **Last used**가 이동합니다.
3. **Activity**를 엽니다. 호출 내역이 앱 이름 및 `mcp`와(과) 함께 나열됩니다.

## 한도 및 참고 사항 {#limits-notes}

- 1시간 후에 앱에서 로그인을 다시 요구하는 경우, 클라이언트가 토큰을 갱신하지 않을 때 정상적으로 발생하는 현상이므로 다시 연결하세요.
- 두 번 사용된 리프레시 토큰은 도난당한 것으로 간주되어 전체 연결이 취소됩니다. 앱에서 다시 연결하세요.
- 두 번 사용된 권한 부여 코드는 거부되며(`invalid_grant`) 해당 코드로 이미 발급된 토큰은 취소됩니다.
- OAuth 액세스는 범위 규칙이 허용하는 범위를 초과하지 않습니다. [what a key can never do](https://nexcmp.com/ko/docs/configure-with-ai/admin-api-keys/#what-a-key-can-never-do)은(는) 연결된 앱에도 적용됩니다.
- 공급업체는 메뉴와 지원 기능을 변경합니다. 공급업체의 앱이 회원님의 요금제에서 커스텀 커넥터를 제공하지 않는 경우, 대신 데스크톱 또는 명령줄 클라이언트와 함께 [admin API key](https://nexcmp.com/ko/docs/configure-with-ai/admin-api-keys/)를 사용하세요.

## Troubleshooting {#troubleshooting}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| 동의 화면에 "Wrong browser"가 표시됨 | 로그인한 브라우저가 아닌 다른 브라우저에서 요청이 시작됨 | 동일한 브라우저의 AI 앱에서 연결을 다시 시작하세요. |
| 동의 화면에 요청이 만료되었거나 누락되었다고 표시됨 | 10분이 넘게 지났거나 링크가 두 번 열림 | AI 앱에서 연결을 다시 시작하세요. |
| "Unknown client" 또는 "redirect address does not match" 페이지 | 앱 등록이 만료되었거나 등록되지 않은 리디렉션 주소를 사용함 | 앱에서 커넥터를 제거한 후 다시 추가하세요. |
| `invalid_target` | 전송된 `resource`이(가) 이 패널의 `/mcp/admin` URL이 아님 | **Connect an AI** 탭에 표시된 정확한 URL을 사용하세요. |
| `invalid_request` about PKCE | 클라이언트가 `code_challenge_method=S256`을(를) 전송하지 않음 | PKCE를 지원하는 OAuth 2.1 클라이언트를 사용하세요. |
| 앱은 연결되지만 호출 시 `insufficient_scope`이(가) 반환됨 | 해당 스코프를 체크하지 않음 | 연결을 해제하고 스코프를 체크한 상태로 다시 연결하세요. |
| 앱이 URL에 도달할 수 없음 | DNS, TLS 또는 리버스 프록시가 `/mcp/admin`, `/oauth-admin/` 또는 `/.well-known/`을(를) 차단함 | 프록시 규칙을 확인하세요. |




---

<!-- source: https://nexcmp.com/ko/docs/configure-with-ai/config-as-code/ -->

# 코드 기반 설정 {#configuration-as-code}

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

## 작동 내용 {#what-it-does}

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

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

## 요구 사항 {#requirements}

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

## 내보내기, 편집, 미리보기, 적용 {#export-edit-preview-apply}

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

   ```bash
   sudo nexcmp config export -o nexcmp.yaml
   ```

   `-o`이(가) 없으면 YAML이 화면에 출력됩니다.
2. `nexcmp.yaml`을(를) 편집합니다(아래의 [example](#example-file) 참조). `version: 1`을(를) 맨 위에 유지하세요.
3. 변경될 내용을 미리 봅니다. 이는 아무것도 변경하지 않습니다:

   ```bash
   sudo nexcmp config plan -f nexcmp.yaml
   ```

   각 행은 섹션, 항목, 필드 및 `old → new`을(를) 표시합니다. `$` 표시된 행은 결제 섹션에 속합니다([Billing sections](#billing-sections) 참조). 패널이 파일과 이미 일치하는 경우 "No changes"가 표시됩니다.
4. 적용합니다. `--yes`이(가) 없으면 명령어는 **dry run**으로 실행되며 동일한 목록만 출력합니다.

   ```bash
   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입니다.

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

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

## 숙지해야 할 규칙 {#rules-to-remember}

- **멱등성.** 동일한 파일을 두 번 적용해도 두 번째에는 아무것도 변경되지 않습니다. `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`(공개 읽기 가능).

### 결제 섹션 {#billing-sections}

`payments`, `currency` 및 `plans`는 가격이나 금전적 경로를 변경합니다. `nexcmp config apply --yes`에 `--confirm-billing`를 추가하지 않으면 이들 변경이 **건너뛰어집니다**. 대신 `skipped`("billing section - pass confirm_billing") 아래에 나열됩니다. 이 플래그는 확인을 의미합니다. 이 플래그가 있으면 파일의 모든 결제 변경 사항(및 확인을 요구하는 기타 모든 변경 사항)이 두 번째 프롬프트 없이 적용됩니다. 먼저 `plan`를 실행하고 `$`로 표시된 각 줄을 읽어보세요.

AI(MCP 클라이언트 또는 AI Chat의 `config_apply` 도구)가 동일한 파일을 적용할 때는 이 플래그가 무시되며, 대신 금전적 변경 사항은 사용자의 승인을 기다립니다.

## 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** 버튼을 누르면 스키마가 열립니다.

![Export 카드와 내보낸 YAML이 포함된 Import 카드가 있는 Import/Export page](https://nexcmp.com/ko/docs/images/configure-with-ai/config-as-code-01-import-export.webp)

![빌링 태그와 Apply selected 버튼이 섹션별로 그룹화된 변경 사항 미리보기 표](https://nexcmp.com/ko/docs/images/configure-with-ai/config-as-code-02-preview.webp)

## 명령줄에서 도구 실행하기 {#run-any-tool-from-the-command-line}

`nexcmp admin`은(는) AI 어시스턴트([the tool list](https://nexcmp.com/ko/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"}}'
```

인수(Argument)는 `key=value` 쌍(값은 파싱 가능한 경우 JSON으로, 그렇지 않으면 텍스트로 읽힘) 또는 하나의 `--json '{...}'` 객체입니다. 작업에 확인이 필요한 경우, 명령은 미리보기를 출력하고 종료 코드 3과 "Nothing changed"와 함께 중지됩니다. 미리보기를 읽은 후, 적용하려면 `--yes`(을)를 포함하여 동일한 명령을 다시 실행하세요. root로 실행하면 모든 스코프가 포함된 15분짜리 키를 획득하므로 확인 단계가 안전장치 역할을 합니다. `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/ko/docs/configure-with-ai/ai-chat-in-admin/) 또는 관리자 페이지를 통해 연결하세요.
- 존(Zone)과 플랜은 `slug`을(를) 기준으로 매칭됩니다. 파일 내의 슬러그(slug)를 이름 변경하지 마세요. 새 항목으로 생성됩니다.
- 이미 고객이 사용 중인 플랜은 크기를 변경할 수 없습니다. 대신 새 플랜을 생성하세요.
- 비밀 정보가 포함되어 있지 않더라도, 가격, 주소, 계정 이름이 나열되므로 내보낸 파일은 비공개로 유지하세요.

## Troubleshooting {#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` | 데모 패널 | 실제 설치 환경에 적용합니다. |




---

<!-- source: https://nexcmp.com/ko/docs/configure-with-ai/example-prompts/ -->

# 프롬프트 예시 {#example-prompts}

> **관리자 페이지 위치:** AI Chat (`/agent`) 또는 관리자 페이지의 플로팅 **Ask AI** 버튼. [MCP](https://nexcmp.com/ko/docs/configure-with-ai/mcp-admin/)를 통해 연결된 모든 AI 클라이언트에서도 동일한 프롬프트를 사용할 수 있습니다.

## 작동 내용 {#what-it-does}

다음 프롬프트는 요청 방법을 보여줍니다. 각 프롬프트에는 어시스턴트가 백그라운드에서 수행하는 작업, 필요한 권한 범위(외부 클라이언트 또는 키용), 승인을 요구하는 지점이 나열되어 있습니다. 예시 값을 본인 환경에 맞게 변경하세요.

::: tip 채팅 창에 비밀 정보를 직접 입력하지 마세요
비밀번호, API 키, 토큰의 경우 AI Chat 입력창 옆의 **Secret** 필드를 사용하세요([details](https://nexcmp.com/ko/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`(권한 범위: `admin:read`)을(를) 호출하고 실제 상태를 바탕으로 답변합니다. [Setup progress checklist](https://nexcmp.com/ko/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` 및 수락하는 단계의 권한 범위가 필요합니다. 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. 어시스턴트는 API 토큰 ID(`user@realm!tokenid`)와 시크릿을 요청합니다. 시크릿을 **Secret** 필드에 입력하세요. 먼저 제한된 권한의 토큰을 만드세요: [Proxmox VE](https://nexcmp.com/ko/docs/infrastructure/proxmox/).
2. `proxmox_add`, `proxmox_test`, `zone_create`, `proxmox_attach_zone`을(를) 호출합니다.
3. `plans_from_offerings`을(를) 사용하여 플랜을 제안하고 승인을 기다립니다(다음 예시 참조).

권한 범위: `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)을 사용합니다. 범위: `catalog:write`, `admin:read`. [Plans](https://nexcmp.com/ko/docs/catalog/plans/) 참조.

![원가, 월 요금, 시간당 요금이 포함된 상품 미리보기 테이블을 보여주는 AI Chat 응답](https://nexcmp.com/ko/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`을(를) 호출하고 메시지가 수락되었는지 알려줍니다. 권한 범위: `settings:write`, `secrets:write`. [SMTP and e-mail templates](https://nexcmp.com/ko/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`은(는) 항상 2단계 작업으로 진행됩니다. 시크릿 값이 마스킹된 미리보기를 확인하고 승인합니다. 그 후 `payment_test`을(를) 통해 Stripe 자격 증명을 확인합니다. 권한 범위: `billing:write`, `secrets:write`. 테스트 결제가 완료된 후에만 라이브 모드로 전환하세요. [Stripe](https://nexcmp.com/ko/docs/billing/stripe/)를 참조하세요.

## 텔레그램 알림 켜기 {#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`을(를) 호출합니다. 권한 범위: `settings:write`, `secrets:write`. [Telegram notifications](https://nexcmp.com/ko/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"가 표시되며 감사 로그에 기록될 금액과 사유가 표시됩니다. 범위: `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`(으)로 저장하고 버전 제어 시스템에 보관하세요. [Configuration as code](https://nexcmp.com/ko/docs/configure-with-ai/config-as-code/)을(를) 참조하세요. 권한 범위: `admin:read`.

## 효과적인 프롬프트 작성 {#write-good-prompts}

- 목표와 사실(이름, 가격, 이메일 주소 등)을 제공하세요. 비밀 정보를 입력하지 마세요.
- 비용이 발생하거나 데이터가 삭제되는 작업은 먼저 미리보기를 요청하세요.
- 어시스턴트에게 "값을 변경하기 전에 현재 값을 읽어보라"고 요청하세요. 내장된 지침에 이미 포함되어 있습니다.
- 답변이 잘못되어 보인다면 "어떤 도구를 어떤 인자로 호출했나요?"라고 물어보세요. AI Chat의 도구 카드에서 둘 다 확인할 수 있습니다.

## Troubleshooting {#troubleshooting}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| 어시스턴트에 해당 도구가 없다고 나오는 경우 | 해당 도구의 권한이 부여되지 않았거나 AI의 작업이 차단된 경우 | [Admin API keys](https://nexcmp.com/ko/docs/configure-with-ai/admin-api-keys/#what-a-key-can-never-do)를 확인하거나 관리자 페이지에서 직접 수행하세요. |
| 비밀번호를 입력하라고 요구하는 경우 | 모델이 지침을 무시한 경우 | 거부하고, Secret 필드를 사용하거나 관리자 페이지에서 직접 값을 입력하세요. |
| "실행(do it)" 후 아무것도 바뀌지 않는 경우 | 변경 사항이 확인을 대기 중인 경우 | 확인 카드로 스크롤하여 **Confirm**을 누르세요. |
| 예상치 못한 가격으로 플랜이 생성된 경우 | 프롬프트에 입력된 비용이나 마진이 잘못된 경우 | Plans 페이지에서 플랜을 수정하거나 어시스턴트에게 재가격을 요청하세요. 가격 변경 시 확인을 요청합니다. |


---

<!-- source: https://nexcmp.com/ko/docs/configure-with-ai/setup-checklist/ -->

# 설정 진행률 체크리스트 {#setup-progress-checklist}

> **관리자 메뉴 위치:** Overview › Dashboard (`/`), 상단의 **Setup progress** 카드. Plans, Customers, Zones, Payments, Infrastructure의 빈 목록에서도 동일한 도움말이 표시됩니다.

## 작동 내용 {#what-it-does}

새로 설치된 시스템은 첫 고객이 주문하고 결제하기 전에 10가지 항목을 설정해야 합니다. **Setup progress** 카드는 실제 설정 상태를 기준으로 이를 확인하고, 완료된 개수를 표시하며, **다음 단계**를 안내하고 해당 페이지로 연결해 줍니다. AI 소스가 연결되어 있는 경우 **Do it for me**는 해당 단계에 대한 질문이 준비된 [AI assistant](https://nexcmp.com/ko/docs/configure-with-ai/ai-chat-in-admin/)를 엽니다. 어시스턴트(및 [MCP](https://nexcmp.com/ko/docs/configure-with-ai/mcp-admin/)를 사용하는 모든 AI 클라이언트)는 `setup_checklist` 도구를 통해 동일한 목록을 읽을 수 있습니다.

## 10단계 {#the-ten-steps}

| # | 단계 | 완료로 인정되는 조건 | 설정 위치 |
|---|---|---|---|
| 1 | 라이선스 활성화 | 도메인에 라이선스가 활성화됨 | System › Admin › License & updates (`/license`). [License and purchase](https://nexcmp.com/ko/docs/getting-started/license-and-purchase/)를 참고하세요. |
| 2 | 인프라 소스 연결 | CloudStack이 연결되었거나 하나 이상의 Proxmox VE 클러스터가 추가됨 | Infrastructure › Cloud provider › Providers (`/infra/providers`). [CloudStack](https://nexcmp.com/ko/docs/infrastructure/cloudstack/) 및 [Proxmox VE](https://nexcmp.com/ko/docs/infrastructure/proxmox/)를 참고하세요. |
| 3 | Create a zone | 하나 이상의 존(Zone) 존재 | Infrastructure › Datacenter › Zone (`/infra/zones`). [Zones](https://nexcmp.com/ko/docs/infrastructure/zones/)를 참고하세요. |
| 4 | OS 템플릿 | 하나 이상의 템플릿이 활성화됨 | Services › Virtual Machines › Plans & pricing, Templates 탭 (`/vm/catalog?tab=templates`). [OS templates](https://nexcmp.com/ko/docs/infrastructure/templates/)를 참고하세요. |
| 5 | 플랜 생성 | 하나 이상의 플랜이 활성화됨 | Services › Virtual Machines › Plans & pricing (`/vm/catalog`). [Plans and pricing](https://nexcmp.com/ko/docs/catalog/plans/)를 참고하세요. |
| 6 | 결제 설정 | Stripe, PayPal, 암호화폐 또는 계좌 이체가 설정됨 | Finance › Payment channels (`/payments`). [Payment channels](https://nexcmp.com/ko/docs/billing/payment-channels/)을 참조하세요. |
| 7 | Email (SMTP) | 발신 이메일이 설정됨 | System › Settings › Email (`/settings/email`). [SMTP and e-mail templates](https://nexcmp.com/ko/docs/administration/smtp-and-emails/)을 참조하세요. |
| 8 | 브랜딩 | 로고가 업로드되었거나 브랜드 이름이 기본값에서 변경됨 | System › Settings › Brand (`/settings/branding`). [Branding](https://nexcmp.com/ko/docs/customers/branding/)을 참조하세요. |
| 9 | Terms & privacy | 하나 이상의 법적 텍스트가 입력됨 | System › Settings › Legal (`/settings/legal`). [Legal pages](https://nexcmp.com/ko/docs/customers/legal/)을 참조하세요. |
| 10 | 테스트 주문 생성 | 하나 이상의 주문이 존재함 | 모든 기능이 정상 작동하는지 확인하기 위해 고객 포털에서 고객으로서 주문을 생성합니다. 카드는 Billing page (`/billing`)(으)로 연결됩니다. |

카드는 `done/total`(예: 6/10), 진행률 표시줄, **Open**이 있는 다음 단계 및 AI 소스가 연결된 경우 **Do it for me**를 표시합니다. 단계를 클릭하여 해당 페이지로 이동합니다. 단계 옆의 작은 링크는 해당 문서 페이지를 엽니다. 일부 단계에는 "2 zone(s)"와 같은 세부 정보도 표시됩니다.

![10단계 중 3단계를 완료하고 Open 및 Do it for me 버튼이 있는 개요의 설정 진행 상황 카드](https://nexcmp.com/ko/docs/images/configure-with-ai/setup-checklist-01-card.webp)

## 사용 방법 {#use-it}

1. 개요를 엽니다. 카드는 상단에 위치합니다. 화살표를 사용하여 접을 수 있으며, 패널은 브라우저에서 선택한 설정을 기억합니다.
2. **Open**을 클릭하여 다음 단계 페이지로 이동하거나 **Do it for me**를 클릭합니다.
3. **Do it for me**를 사용하면 "40% 마진을 적용한 내 상품 기반 스타터 플랜 테이블을 제안하고, 생성하기 전에 미리보기를 보여줘."와 같은 요청과 함께 어시스턴트가 열립니다. 질문에 답한 다음 각 카드를 검토하고 **Confirm**합니다. [AI Chat in the admin](https://nexcmp.com/ko/docs/configure-with-ai/ai-chat-in-admin/)을 참조하세요.
4. 모든 10단계를 완료하면 카드가 사라집니다.

### Empty lists {#empty-lists}

Plans, Customers, Zones, Payments 또는 Infrastructure가 비어 있는 경우, 페이지에 설명, 작업 버튼 **Next step**, **Do it for me** 및 문서 링크가 포함된 블록이 표시되므로 빈 테이블을 보지 않게 됩니다.

![다음 단계 설명과 Do it for me 버튼이 있는 빈 Plans 페이지](https://nexcmp.com/ko/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`을(를) 호출하고, 각 미완료 단계가 중요한 이유를 설명하며, 필요한 정보를 요청하고 일치하는 도구를 사용합니다. 필요한 스코프: 목록을 읽기 위한 `admin:read` 및 완료하려는 단계의 스코프. [Example prompts](https://nexcmp.com/ko/docs/configure-with-ai/example-prompts/)을 참조하세요.

## 확인 {#verify}

1. 단계를 완료한 후 개요가 다시 로드될 때 카드의 완료 수가 증가합니다.
2. 어시스턴트에서 `setup_checklist`은(는) 완료된 단계에 `done: true`을(를) 포함하여 동일한 숫자를 반환합니다.

## 한도 및 참고 사항 {#limits-notes}

- 검사 항목은 작동 여부가 아니라 저장된 내용을 확인합니다. 설정된 게이트웨이는 테스트가 실패하더라도 완료된 것으로 간주됩니다. 각 페이지의 **Test** 버튼과 문제 해결을 위한 `system_health` 도구를 사용하세요.
- 이 카드는 관리자 전용입니다.
- **Do it for me**에는 System › Settings › AI accounts 아래에 연결된 AI 소스가 필요합니다. 연결된 소스가 없으면 **Open**만 표시됩니다.
- 10단계를 모든 설치에 동일하게 적용되며, 사용할 계획이 없는 단계(예: 프라이빗 클라우드의 결제)도 미완료 상태로 계산됩니다.

## Troubleshooting {#troubleshooting}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| 카드가 없음 | 모든 10단계를 완료했거나 카드를 로드할 수 없음 | 개요를 다시 로드하세요. 상태를 확인하려면 AI Chat에서 `setup_checklist`에 물어보세요. |
| 작업을 완료한 후에도 단계가 열려 있음 | 저장이 완료되지 않았거나 조건이 아직 충족되지 않았습니다 (예: 템플릿이 존재하지만 비활성화된 경우) | 해당 단계의 페이지를 열고 위의 표를 확인하세요. |
| 로고를 변경한 후에도 브랜딩 상태가 유지됨 | 로고가 존재하거나 브랜드 이름이 기본값인 "NexCMP"와 다른 경우 브랜딩으로 간주됨 | 로고를 업로드하거나 사용자 정의 이름을 설정하세요. |
| **Do it for me**가 작동하지 않음 | 연결된 AI 소스가 없거나 데모 패널인 경우 | AI 계정에서 소스를 연결하세요. |


---

<!-- source: https://nexcmp.com/ko/docs/administration/smtp-and-emails/ -->

# 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 등) |
| 네트워크 | NexCMP 서버에서 SMTP 호스트 및 포트로의 아웃바운드 TCP (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. 제공업체에 표시된 SPF, DKIM 및 DMARC DNS 레코드를 게시합니다.
3. SMTP 사용자(또는 API-SMTP 키)를 생성하고 호스트, 포트, 사용자 이름 및 비밀번호를 기록합니다.

## NexCMP에서 연결 {#connect-in-nexcmp}

1. **System › Settings › Email**, **SMTP** 탭을 엽니다.
2. 양식을 작성합니다:

| 필드 | 예시 | 참고 |
|---|---|---|
| 호스트 | `smtp.example.net` | SMTP 서버 |
| 포트 | `587` | |
| 보안 | STARTTLS (587) | 제공업체에서 요구하는 모드 선택 |
| 사용자 이름 | `smtp-user` | |
| 비밀번호 | (숨김) | 쓰기 전용: 설정 여부만 페이지에 표시됨 |
| 보내는 사람 이메일 | `no-reply@example.com` | 제공업체에서 인증되어야 함 |
| 보내는 사람 이름 | `Example Cloud` | 브랜드 이름이 기본값으로 지정됨 |
| 회신 주소 (선택 사항) | `support@example.com` | 고객 회신이 전송되는 위치 |

![호스트, 포트, 보안, 사용자 이름, 발신자 필드 및 Send test 버튼이 있는 Settings의 SMTP tab, Email](https://nexcmp.com/ko/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**을 엽니다. 각 메시지에는 상태(대기 중, 발송됨, 실패)와 전송 결과가 표시됩니다. 실패한 메시지는 최대 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/ko/docs/images/administration/smtp-and-emails-02-templates.webp)

## 제한 사항 및 참고 사항 {#limits-and-notes}

- 설치당 하나의 SMTP 계정이 사용됩니다. 리셀러가 별도로 설정되지 않은 경우, 리셀러의 고객도 동일한 계정을 통해 이메일을 받습니다.
- 공급자의 발송 제한이 적용되며, NexCMP는 재시도 외에는 별도로 조절하지 않습니다.
- SMTP가 없어도 패널은 작동하지만, 고객이 회원가입 인증 및 비밀번호 재설정을 완료할 수 없습니다.

## Troubleshooting {#troubleshooting}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| 테스트 이메일이 도착하지 않음 | 잘못된 자격 증명, 차단된 포트, 승인되지 않은 발신자 | `journalctl -u nexcmp-vmd`에서 SMTP 오류를 확인하고, STARTTLS와 함께 포트 587을 시도하며, 공급자에서 From 주소를 확인하세요. |
| 메시지가 스팸함으로 감지요 | SPF/DKIM/DMARC 누락 또는 불일치 | 공급자의 레코드를 게시하고 해당 도메인에서 발송하세요. |
| Sent emails에 "failed" 표시 | 공급자가 메시지를 거부함 | 공급자의 응답을 보려면 행을 엽니다. |
| 저장 후 비밀번호 필드가 비어 있음 | 설계상 의도됨(쓰기 전용) | 비밀번호가 저장되면 레이블에 "current: set"이 표시됩니다. |


---

<!-- source: https://nexcmp.com/ko/docs/administration/telegram-notifications/ -->

# 텔레그램 및 관리자 알림 {#telegram-and-admin-alerts}

> **관리자 위치:** System › Settings › Admin alerts (`/settings/alerts`). 지원 바로가기: Customers › Support › Tickets (`/support/tickets`), **Settings** 탭.

## 작동 내용 {#what-it-does}

NexCMP는 조치가 필요하거나 고객이 가입하거나 입금이 확인되었을 때 운영자(관리자)에게 **알림**을 보냅니다. 알림은 텔레그램, 웹훅, 이메일 등의 **채널** 하나 이상으로 전송됩니다.

관리자 채널로 전송되는 이벤트에는 배포 실패, VM 누락, 네트워크 중단, 사용 가능한 IP 30개 미만, 만료 임박 항목(1시간 경고), Stripe 분쟁, 중단된 워커, 임계치 초과 클러스터 RAM, 신규 고객 가입 및 입금 반영이 포함됩니다. 고객 이벤트는 텔레그램에서 수락할 때까지 30초에서 최대 1시간까지 지연 시간을 늘려가며 지속적으로 대기열에 추가되고 재시도됩니다.

## 요구 사항 {#requirements}

| 항목 | 요구 사항 |
|---|---|
| 텔레그램 | **@BotFather**를 통해 생성한 봇(토큰)과 메시지를 받을 그룹 또는 사용자의 **채팅 ID** |
| 네트워크 | `api.telegram.org`(으)로의 아웃바운드 HTTPS |
| 웹훅(대체) | 알림 페이로드를 수락하는 HTTPS 엔드포인트 |

## 텔레그램 준비 {#prepare-telegram}

1. Telegram에서 **@BotFather**를 열고 `/newbot`을(를) 보낸 뒤 이름을 선택하고, **bot token**을 복사합니다(`123456789:AA...`).
2. 그룹을 만들고 봇을 추가한 후 아무 메시지나 보냅니다.
3. **채팅 ID** 찾기: 브라우저에서 `https://api.telegram.org/bot<token>/getUpdates`을(를) 열고 `chat.id`을(를) 확인하세요(그룹 ID는 `-`로 시작합니다).

## NexCMP에서 연결 {#connect-in-nexcmp}

1. **System › Settings › Admin alerts**을(를) 엽니다.
2. **Add channel**에서 **Type: Telegram**을(를) 선택하고, **Destination**을(를) 채팅 ID로 설정하며 **Secret (bot token)**에 토큰을 입력합니다. **Add**을(를) 클릭합니다.
3. **Send admin Telegram (VM module)** 토글이 켜져 있는지 확인합니다. *VM module status (read-only)* 줄에 "on"이 표시됩니다.

![Telegram으로 설정된 채널 추가 폼이 있는 관리자 알림 페이지](https://nexcmp.com/ko/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** 버튼이 표시될 수 있습니다. 지원 설정에서 구성할 때까지 숨겨져 있습니다: Telegram용 `https://t.me/...` 링크와 Zalo 링크 또는 QR을 입력합니다. `https://` 링크만 허용됩니다. 지원 채팅은 질문과 답변 초안과 함께 Telegram 그룹에 알릴 수도 있습니다 — [AI Chat](https://nexcmp.com/ko/docs/ai/ai-chat/)을(를) 참조하세요.

## 제한 사항 및 참고 사항 {#limits-and-notes}

- 봇 토큰은 채널과 함께 저장되며 다시 표시되지 않습니다.
- Telegram 이벤트는 대상과 토큰이 모두 있는 첫 번째 활성화된 Telegram 채널을 사용합니다.

## Troubleshooting {#troubleshooting}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| 메시지가 도착하지 않음 | 잘못된 채팅 ID, 그룹에 봇이 없음, 또는 봇에 메시지를 보낸 적이 없음 | `getUpdates`을(를) 사용하여 ID를 다시 확인하세요. 먼저 봇이나 그룹에 메시지를 보내세요. |
| 잠시 작동하다가 멈춤 | BotFather에서 토큰이 해지됨 | 새 토큰을 생성하고 채널을 업데이트하세요. |
| 로그의 `Telegram: no channel` | 활성화된 Telegram 채널 없음 | 위와 같이 추가하세요. |




---

<!-- source: https://nexcmp.com/ko/docs/administration/audit-log/ -->

# 감사 로그 및 활동 {#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 {#tabs}

| 탭 | 내용 |
|---|---|
| **Activity** | 모든 소스에 걸친 통합 타임라인: 관리자 작업, VM 이벤트, 로그인, 제휴 및 시스템 오류 |
| **Admin actions** | 관리자가 변경한 사항(예: `customer.block`, `customer.delete`) 및 관리자의 IP |
| **Console** | 관리자 콘솔 로그인 및 업데이트 요청과 같은 시스템 요청 |
| **Login** | 고객 로그인 및 실패 |
| **VM events** | 가상 머신별 배포 단계, 생성, 비밀번호, 삭제 및기타 수명 주기 이벤트 |

## Reading a row {#reading-a-row}

열: **Time**, **Source**, **Level**, **Actor**(주체), **Target**, **Services**, **Action**(`customer.delete`와 같은 이벤트 코드), **Details**. 전체 레코드를 보려면 **Open**을(를) 클릭하세요.

![타임라인 상단에 소스, 사이트, 서비스 필터가 표시된 Activity 페이지](https://nexcmp.com/ko/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}

기록은 `/var/lib/nexcmp`의 NexCMP 데이터베이스에 저장되며 [백업](https://nexcmp.com/ko/docs/getting-started/backup-and-restore/)에 포함됩니다. 보관 기간은 로그 유형에 따라 다릅니다. 180일이 지난 고객 로그인 시도 기록과 60일이 지난 고객 API 키 요청 로그는 정리됩니다. 관리자 API 키 감사는 최근 기록을 최대 약 200,000개까지 유지합니다. 이러한 제한이 통합 활동 타임라인에도 동일한 보관 기간이 적용됨을 의미하지는 않습니다.

## 일반적인 용도 {#common-uses}

| 질문 | 확인할 위치 |
|---|---|
| 이 고객을 정지한 사람은 누구인가요? | 관리자 작업, 검색 `customer.block` |
| VM이 사라진 이유는 무엇인가요? | VM events, VM의 ID로 필터링; Activity도 확인 |
| 고객이 이메일을 받았나요? | Overview › Support › Sent emails |
| 마지막 업데이트 요청은 언제 이루어졌나요? | Console 탭 |




---

<!-- source: https://nexcmp.com/ko/docs/administration/security/ -->

# 보안 {#security}

> **관리자 위치:** System › Admin › Console security (`/account`), Admin users (`/users`); System › Settings › Customer logins (`/settings/login`).

## 관리자 콘솔 {#admin-console}

### 2단계 인증 (TOTP) {#two-factor-authentication-totp}

콘솔은 인터넷을 통해 접근 가능하므로 TOTP를 활성화하세요.

1. **System › Admin › Console security**를 엽니다.
2. **Two-factor authentication (TOTP)** 아래에서 **Start setup**을 클릭합니다.
3. Google Authenticator, Authy, 1Password 또는 Bitwarden으로 QR 코드를 스캔한 다음 6자리 코드를 입력합니다.

### 허용된 콘솔 IP 범위 {#allowed-console-ip-ranges}

**Allowed console IP ranges**에 줄당 하나의 IP 또는 CIDR(IPv4 또는 IPv6)을 입력합니다. **비워 두면 어디서나 허용됩니다.** 이 범위를 벗어나면 로그인과 관리자 API 모두 차단됩니다.

::: warning 잠금 방지
페이지에 현재 IP가 표시되며 새 목록에 해당 IP가 포함되어야 합니다. **+ Add my IP**를 사용하세요. 만약 잠긴 경우 서버에서 [emergency access](https://nexcmp.com/ko/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` | 관리자 API에 대한 전체 액세스 |
| `staff` | 전체 시스템에 대한 읽기 전용 |
| `user` | 단일 고객 리소스에 대한 읽기 전용 보기 |

루트 계정은 [setup wizard](https://nexcmp.com/ko/docs/getting-started/setup-wizard/)에서 생성된 계정입니다. 행 작업: **Edit**, **Reset PW**, **Key**, **Delete**. 비밀번호는 솔티드 해시로 저장되며, 계정을 변경하거나 잠그면 즉시 세션이 종료됩니다.

## 고객 로그인 {#customer-sign-in}

**System › Settings › Customer logins**를 엽니다.

| 설정 | 작동 내용 |
|---|---|
| **Google sign-in** | 활성화한 다음 OAuth 클라이언트 ID와 시크릿을 입력합니다. 페이지에 표시되는 **Callback URL**을 *Google Cloud Console › APIs & Services › Credentials › OAuth client ID › Authorized redirect URIs*에 복사합니다. **Test configuration**을 사용합니다. |
| **GitHub login** | 동일하게 *GitHub › Settings › Developer settings › OAuth Apps › Authorization callback URL*을 사용합니다 |
| **Passkey** | 지문, PIN 또는 하드웨어 키 로그인으로, 기본적으로 켜져 있습니다. 패스키는 도메인에 바인딩되며 각 리셀러 도메인은 개별적으로 작동합니다. 리브랜딩 후 고객이 유용한 힌트를 볼 수 있도록 *Legacy passkey Domain*에 이전 도메인을 입력하세요 |
| **로그인 방식 추가 시 재인증** | 패스키 추가 또는 Google/GitHub 연동 전에 비밀번호를 다시 확인합니다(기본값: 꺼짐) |
| **Captcha** | 가입 시 Cloudflare Turnstile 또는 Google reCAPTCHA 사용: 활성화하고 공급자를 선택한 후 사이트 키와 시크릿 키를 입력합니다 |
| **Block e-mail domains** | 한 줄에 하나의 도메인(최대 2000개). 일치하는 주소는 가입 시 거부되며 `email_domain_blocked` |

![콜백 URL과 함께 Google 로그인을 보여주는 고객 로그인 페이지](https://nexcmp.com/ko/docs/images/administration/security-01-customer-logins.webp)

### 기본 제공 정책 {#built-in-policies}

| 정책 | 값 |
|---|---|
| Customer password | 최소 10자, 영문자와 숫자 |
| Customer session | 30일; "고객으로 로그인" 세션은 1시간 동안 유지됩니다 |
| E-mail verification | 영업 설정에서 *require e-mail verified*가 켜져 있을 때 VM 생성 전에 필수입니다 |
| Anti-carding | 최소 충전 금액 미만인 계정은 제한된 수의 VM만 생성할 수 있습니다 |

## 서버 강화 {#server-hardening}

- 설정 및 TLS 완료 후 포트 3000은 닫힙니다. [Installation](https://nexcmp.com/ko/docs/getting-started/installation/#the-panel-port-3000)을 참조하세요.
- 서비스는 제한된 systemd 샌드박스가 적용된 권한 없는 `nexcmp` 사용자로 실행됩니다.
- API 키, 결제 자격 증명 및 SMTP 비밀번호는 암호화되어 저장되며, 마스터 키는 `/var/lib/nexcmp/secrets`에 있습니다. [backups](https://nexcmp.com/ko/docs/getting-started/backup-and-restore/)을 보호하세요.
- 릴리스는 설치 전에 SHA-256 및 Ed25519 서명으로 검증됩니다.




---

<!-- source: https://nexcmp.com/ko/docs/administration/general-settings/ -->

# 일반 설정 {#general-settings}

> **관리자 위치:** System › Settings › General (`/settings`). 변경 사항은 즉시 적용됩니다(30초 캐시).

이 페이지는 세 개의 섹션으로 구성되어 있습니다.

## 브랜딩 및 URL {#branding-urls}

| 필드 | 용도 |
|---|---|
| 브랜드 이름 (이메일, 인보이스) | 이메일 및 인쇄물에 표시됩니다. 로고와 색상은 [Branding](https://nexcmp.com/ko/docs/customers/branding/)에 있습니다 |
| Default language | 신규 방문자를 위한 언어 |
| 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 |
| 연락처 이메일 | `billing@example.com` |
| 인보이스 번호 접두사 | `INV` (1–8자, A–Z 및 0–9) |

기존 인보이스는 발급 당시의 판매자 정보와 번호를 유지하며, 변경 사항은 **신규** 인보이스에만 적용됩니다.

## 유지보수 및 지역 {#maintenance-region}

**Customer app MAINTENANCE**를 켜서 배너를 표시하고 관리자 콘솔은 계속 작동하는 동안 **모든 고객 쓰기 작업을 차단**합니다. 고객이 보게 될 **Maintenance message**를 입력하세요. 인프라 업그레이드 시 이 기능을 사용하세요.

![브랜드 이름, 기본 언어 및 URL 필드가 있는 일반 설정 페이지](https://nexcmp.com/ko/docs/images/administration/general-settings-01-general.webp)

## 기타 설정 페이지 {#other-settings-pages}

| 페이지 | 가이드 |
|---|---|
| 브랜드 | [Branding](https://nexcmp.com/ko/docs/customers/branding/) |
| 법적 고지 | [Legal](https://nexcmp.com/ko/docs/customers/legal/) |
| 고객 로그인 | [Security](https://nexcmp.com/ko/docs/administration/security/) |
| 이메일 | [SMTP 및 이메일 템플릿](https://nexcmp.com/ko/docs/administration/smtp-and-emails/) |
| 관리자 알림 | [Telegram 및 관리자 알림](https://nexcmp.com/ko/docs/administration/telegram-notifications/) |
| AI 공급자 | [AI providers](https://nexcmp.com/ko/docs/ai/ai-providers/) |


---

<!-- source: https://nexcmp.com/ko/docs/administration/report-a-bug/ -->

# 버그 신고 {#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를 통해 `https://nexcmp.com`에 연결할 수 있어야 함(라이선스 확인 및 업데이트에 사용되는 주소와 동일) |

## 보고서 전송 {#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/ko/docs/images/administration/report-a-bug-01-dialog.webp)

보고서가 접수되면 대화상자에 티켓 번호와 링크가 표시됩니다. 팀의 답변은 nexcmp.com 라이선스 계정의 이메일 주소로 발송되며, 해당 사이트에 라이선스 소유자로 로그인하면 **Support** 아래에도 티켓이 표시됩니다.

## 전송되는 항목 {#what-is-sent}

**What will be sent** 상자에는 전송을 클릭하기 전에 다음 내용이 정확히 표시됩니다:

| 전송 항목 | 상세 정보 |
|---|---|
| 입력 텍스트 | 제목, 설명, 재현 단계 및 영향도 |
| 버전, 플랜, 도메인 | NexCMP 버전, Free 또는 Source 플랜, 설치 도메인 |
| 현재 페이지 | 현재 위치한 관리자 페이지(`?` 또는 `#` 뒤의 내용은 제외) |
| 브라우저 | 브라우저의 User-Agent 텍스트(이름, 버전 및 운영체제, 최대 200자로 제한) |
| 최근 오류 | 현재 브라우저 탭의 최근 오류 최대 5개. 스크립트 오류는 메시지만 전송되며, 실패한 요청은 메서드, 경로, 상태 코드만 전송됨 |

**Attach diagnostics**를 끌 수 있으며, 이 경우 직접 입력한 텍스트와 버전, 플랜, 도메인만 전송됩니다.

## 전송되지 않는 항목 {#what-is-never-sent}

- 비밀번호, 토큰, 쿠키 및 API 키. 입력 텍스트나 오류 메시지에서 이러한 형태를 띠는 모든 항목은 전송되기 전 서버에서 마스킹(`***` 또는 `[redacted]`로 표시) 처리됩니다.
- 요청 및 응답의 본문 — 실패한 요청은 메서드, 경로, 상태만 기록됩니다.
- 고객 데이터(이름, 이메일, 주문, 청구서) 및 고객의 IP 주소.
- 사용자의 브라우저 IP 주소 및 서버의 파일. 모든 라이선스 확인과 마찬가지로 라이선스 서버에는 서버가 접속하는 IP 주소만 표시됩니다.

티켓은 서버가 이미 보유한 라이선스 토큰을 통해 설치 환경과 연결되므로, 버전, 도메인, 설치 환경 정보는 서버에 의해 설정되며 브라우저에서 변경할 수 없습니다.

## 제한 {#limits}

| 제한 | 값 |
|---|---|
| 제목 | 150자 |
| 설명 및 재현 단계 | 합산 8 KB |
| Reports | 설치 환경 전체 기준 시간당 5건, 일일 20건 |

동일한 리포트를 두 번 전송해도(예: 네트워크 오류 발생 후) 티켓이 중복 생성되지 않습니다.

## Troubleshooting {#troubleshooting}

| 메시지 | 원인 | 해결 방법 |
|---|---|---|
| 라이선스를 먼저 활성화하십시오 | 설치 환경에 활성화된 라이선스가 없음 | **License & updates**를 열고 활성화한 후 다시 전송하십시오 |
| 라이선스 서버에 연결할 수 없습니다 | 서버가 `nexcmp.com`에 연결할 수 없음 | 서버의 아웃바운드 HTTPS 및 DNS를 확인한 다음 **Send report**를 다시 누르십시오(입력한 내용은 유지됩니다) |
| 이 설치 환경에서 버그 보고가 너무 많이 전송되었습니다 | 시간당 5건 또는 일일 20건 한도에 도달함 | 잠시 기다린 후 다시 시도하거나, 이미 열려 있는 티켓에 새로운 확인 내용을 추가하십시오 |
| 이 라이선스는 정지되었습니다 | 라이선스가 정지되었거나 환불됨 | [License and purchase](https://nexcmp.com/ko/docs/getting-started/license-and-purchase/)를 참조하십시오 |
| 이 설치가 철회되었습니다 | 라이선스 포털에서 설치 환경이 취소됨 | **License & updates**에서 다시 활성화하십시오 |
| 라이선스 토큰을 갱신할 수 없습니다 | 서버에서 라이선스 토큰을 갱신할 수 없음 | **License & updates**를 열고 **Refresh**를 누른 다음 다시 전송하십시오 |
| Report a bug 버튼이 없음 | 직원, 리셀러, 고객 계정으로 로그인되어 있거나 읽기 전용 데모 환경임 | 기본 관리자 계정으로 로그인하십시오 |

::: tip AI 어시스턴트 및 API 키 안내
관리자 콘솔의 어시스턴트와 관리자 API 키는 사용자를 대신해 버그 리포트를 전송할 수 없습니다. 해당 버튼을 사용하려면 기본 관리자로 로그인한 실제 사용자여야 합니다.
:::


---

<!-- source: https://nexcmp.com/ko/docs/troubleshooting/installation-errors/ -->

# 설치 오류 {#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 또는 기타 CPU | x86_64 서버를 사용하세요. |
| `requires ≥ 2 GB RAM (host has … MB)` | 메모리 부족 | RAM을 추가하세요. |
| `requires ≥ 8 GB free disk space on / (… GB available)` | 루트 파일 시스템 용량 거의 부족 | 공간을 확보하거나 `/`을(를) 확장하세요. |
| `missing --license` / `missing --domain` | 해당 매개변수 없이 최초 설치 진행 | 둘 다 전달하세요 — [Installation](https://nexcmp.com/ko/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 …): <message>` | 라이선스 서버가 키를 거부함 | 메시지를 확인하세요: 잘못된 키, 라이선스와 일치하지 않는 도메인, 정지 또는 취소된 라이선스. [nexcmp.com/licenses](https://nexcmp.com/licenses)에서 라이선스 페이지를 확인하세요. |
| `no release available for this license yet` | 라이선스에 다운로드 가능한 릴리스가 없음 | 영업팀에 문의하세요. [Support](https://nexcmp.com/ko/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` | 패널이 3분 이내에 `/healthz`에 응답하지 않음 | 저널을 확인하세요. 일반적인 원인: 포트(기본값 3000)가 이미 사용 중임(`ss -ltnp | grep 3000`) — `--port`을(를) 사용하여 다시 설치; `/var/lib/nexcmp` 내 파일의 소유권이 root로 되어 있음 — `sudo nexcmp fix-owner` 실행. |

## nginx 및 TLS {#nginx-and-tls}

| 메시지 | 원인 | 해결 방법 |
|---|---|---|
| `DNS <domain> does not point to <IP> (nor to Cloudflare) — skipping nginx/TLS` | A/AAAA 레코드가 누락되었거나 잘못됨 | [DNS and Cloudflare](https://nexcmp.com/ko/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://<domain>`을(를) 열 수 없음 | DNS 또는 TLS가 준비되지 않음 | `sudo nexcmp status`; [emergency access](https://nexcmp.com/ko/docs/getting-started/cli-reference/#emergency-access)을(를) 사용하세요. |
| `ERR_TOO_MANY_REDIRECTS` | Cloudflare SSL 모드가 **Flexible**으로 설정됨 | **Full (strict)**으로 설정 — [상세 정보](https://nexcmp.com/ko/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`. |


---

<!-- source: https://nexcmp.com/ko/docs/troubleshooting/update-errors/ -->

# 업데이트 오류 {#update-errors}

> **관리자 위치:** System › Admin › License & updates (`/license`)

업데이트는 [NexCMP 업데이트](https://nexcmp.com/ko/docs/getting-started/updating/)에 설명되어 있습니다. 업데이트 카드 또는 `sudo nexcmp update`에서 오류가 보고되는 경우:

| 메시지 | 원인 | 해결 방법 |
|---|---|---|
| `update plan expired — renew on the license page to receive this feature release` | 업데이트 지원 기한이 릴리스 날짜보다 이전입니다. 보안 수정 사항은 계속 제공되지만 기능 릴리스는 제공되지 않습니다 | [nexcmp.com/licenses](https://nexcmp.com/licenses)(NexCMP Free의 경우 연간 $99)에서 갱신한 후 다시 확인하세요. 그동안 소프트웨어는 계속 실행됩니다. |
| `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**를 클릭하세요. |

## 롤백 {#roll-back}

새 버전에 문제가 발생하는 경우:

```bash
sudo systemctl stop nexcmp-vmd nexcmp
sudo cp /opt/nexcmp/bin/nexcmp.bak /opt/nexcmp/bin/nexcmp
echo <previous-version> | sudo tee /opt/nexcmp/VERSION
sudo systemctl start nexcmp nexcmp-vmd
```

데이터베이스 마이그레이션이 이미 실행된 경우, 업데이트 전에 수행한 [백업](https://nexcmp.com/ko/docs/getting-started/backup-and-restore/)도 함께 복원하세요.

## `sudo nexcmp update`에서 설치 프로그램을 찾을 수 없다고 표시됨 {#sudo-nexcmp-update-says-it-cannot-find-the-installer}

`nexcmp update`은(는) 설치된 릴리스 내부에 포함된 설치 프로그램(`/opt/nexcmp/releases/<version>/share/install.sh`)을 실행합니다. 해당 파일이 누락된 경우 라이선스 페이지에서 설치 명령을 다시 실행하세요.


---

<!-- source: https://nexcmp.com/ko/docs/troubleshooting/faq/ -->

# FAQ {#faq}

## 라이선스 {#licensing}

**라이선스가 만료되거나 서버의 인터넷 연결이 끊어지면 어떻게 되나요?** 토큰은 14일 동안 유효하며 매일 갱신됩니다. 그 이후에는 고객이 **새로운** 서비스를 생성할 수 없지만, 실행 중인 서비스, 빌링 및 로그인은 계속 작동합니다. [라이선스 및 구매](https://nexcmp.com/ko/docs/getting-started/license-and-purchase/)를 참조하세요.

**업데이트 지원 기한이 끝난 후에도 보안 수정 사항을 받을 수 있나요?** 네, 보안 릴리스는 항상 제공되며 기능 릴리스에는 활성화된 지원 기한이 필요합니다.

**두 번째 서버나 도메인에서 NexCMP를 실행할 수 있나요?** 라이선스에 등록된 키와 도메인으로 활성화하세요. [라이선스 및 구매](https://nexcmp.com/ko/docs/getting-started/license-and-purchase/#moving-to-a-new-server-or-domain)를 참조하세요.

## 설치 {#installation}

**NexCMP에는 Docker, PostgreSQL 또는 Redis가 필요한가요?** 아니요. SQLite 데이터베이스를 사용하는 단일 프로그램이며, 권한이 없는 사용자로 systemd에 의해 실행됩니다. [요구 사항](https://nexcmp.com/ko/docs/getting-started/requirements/)을 참조하세요.

**공인 도메인 없이 설치할 수 있나요?** 네, `--no-nginx` 및 SSH 터널을 사용하세요. [설치](https://nexcmp.com/ko/docs/getting-started/installation/#installing-without-a-public-domain-lab-or-test)를 참조하세요.

**설정 후 3000번 포트가 닫혀 있는 이유는 무엇인가요?** 보안을 위해 마법사가 완료되고 TLS가 활성화되면 패널은 `127.0.0.1`에서 수신 대기합니다. 긴급 상황 시 `sudo nexcmp open-port`을(를) 사용하세요.

## 인프라 {#infrastructure}

**CloudStack과 Proxmox VE를 함께 사용할 수 있나요?** 네. 하나의 존에 둘 다 포함될 수 있으며 각 요금제는 소스를 선택합니다. [Proxmox VE](https://nexcmp.com/ko/docs/infrastructure/proxmox/) 및 [존](https://nexcmp.com/ko/docs/infrastructure/zones/)을 참조하세요.

**CloudStack의 ROOT API 키가 필요한가요?** 아니요 — 필요하지 않으며 사용해서도 안 됩니다. 전용 계정을 만드세요 — [CloudStack](https://nexcmp.com/ko/docs/infrastructure/cloudstack/).

**가상 머신에서 일부 탭이나 버튼이 나타나지 않는 이유는 무엇인가요?** 페이지에는 VM의 소스가 지원하는 기능만 표시됩니다(예: Proxmox VE에는 포트 포워딩이 없음). [Proxmox VE](https://nexcmp.com/ko/docs/infrastructure/proxmox/)의 기능 테이블을 참조하세요.

## 작업 {#operations}

**NexCMP를 다른 서버로 어떻게 이동하나요?** 백업하고, 새 서버에 동일한 라이선스로 동일한 버전을 설치한 후 복원합니다 — [Backup and restore](https://nexcmp.com/ko/docs/getting-started/backup-and-restore/) 참조.

**로그는 어디에 있나요?** `journalctl -u nexcmp -u nexcmp-vmd`, `/var/log/nexcmp`, 그리고 시스템 관리자 콘솔의 System › Logs. [Audit log](https://nexcmp.com/ko/docs/administration/audit-log/)를 참조하세요.

**설치 전에 고객 포털을 미리 볼 수 있습니까?** 네. [nexcmp.com](https://nexcmp.com/platform/)의 서비스 페이지에서 샘플 데이터와 함께 고객 포털을 탭별로 확인하실 수 있습니다. 전체 화면 뷰어로 보시려면 *View demo*를 여십시오. 실제 설치 환경을 확인하시려면 영업팀에 문의해 주십시오.


---

<!-- source: https://nexcmp.com/ko/docs/troubleshooting/support/ -->

# 지원 {#support}

## 문의 {#contact}

문의 양식은 없습니다. **sales@nexcmp.com**(으)로 이메일을 보내주세요 — 라이선스, 갱신, 도메인 및 기술적 질문을 다룹니다. [nexcmp.com/licenses](https://nexcmp.com/licenses)의 라이선스 페이지에서도 동일한 주소로 연결됩니다.

## 문의하기 전 {#before-you-write}

1. 이 문서를 검색하고(`/` 누름) [Installation errors](https://nexcmp.com/ko/docs/troubleshooting/installation-errors/) 및 [Update errors](https://nexcmp.com/ko/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 키, 비밀번호, 설정 코드, 결제 자격 증명 또는 백업 아카이브를 보내지 마세요. 로그와 스크린샷에서 마스킹 처리하세요.
:::

## 보안 보고 {#security-reports}

취약점을 발견했다고 생각되는 경우, 제목에 "Security"를 포함하여 동일한 주소로 이메일을 보내고 수정될 때까지 세부 정보를 공개적으로 게시하지 마세요.