# NexCMP 1.6.1 — full documentation

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


---

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

# 什麼是 NexCMP {#what-is-nexcmp}

NexCMP 是安裝在**你自己的伺服器**上的軟體，能將雲端基礎設施轉化為可供販售的產品。它提供你：

- 一個**客戶入口網站**，供使用者註冊、儲值、訂購虛擬機器與其他服務、開啟主控台、建立快照以及聯絡客服；
- 一個**管理主控台**（`/admin`），供你管理客戶、方案、價格、付款、基礎設施與設定；
- **/計費系統**：每個客戶一個錢包、按時計費或按月計費、發票、促銷活動與資源配額；
- **白牌經銷商**：其他品牌能夠在其自己的網域下販售你的資源容量；
- 一個 **API**、一個命令列工具（`cmp`）以及一個用於自動化的 MCP 伺服器；
- 選配的 **AI Chat**（客服助理）與 **AI Agent**（以日常語言管理虛擬機器）。

## 它連線的對象 {#what-it-connects-to}

NexCMP 本身並不託管虛擬機器。它驅動的是負責託管的平台。一個*來源*（也稱為提供者）為下列之一：

| Source | 典型用途 | 指南 |
|---|---|---|
| Apache CloudStack | 具備區域、網路、虛擬路由器與公開 IP 的私有雲或公有雲 | [CloudStack](https://nexcmp.com/zh-tw/docs/infrastructure/cloudstack/) |
| Proxmox VE | 你已經在運行的單一伺服器或叢集 | [Proxmox VE](https://nexcmp.com/zh-tw/docs/infrastructure/proxmox/) |

其他模組需要各自的基礎設施：[裸機伺服器](https://nexcmp.com/zh-tw/docs/infrastructure/dedicated/)、[VPN 與代理節點](https://nexcmp.com/zh-tw/docs/infrastructure/vpn-proxy-nodes/)、[S3 物件儲存空間](https://nexcmp.com/zh-tw/docs/infrastructure/s3/)、[Kubernetes 與私有雲](https://nexcmp.com/zh-tw/docs/infrastructure/kubernetes-and-private-cloud/)。請參閱涵蓋所有項目的單一表格 [Infrastructure requirements](https://nexcmp.com/zh-tw/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/zh-tw/docs/infrastructure/architecture/)。

## 接下來去哪裡 {#where-to-go-next}

1. 查看 [requirements](https://nexcmp.com/zh-tw/docs/getting-started/requirements/)。
2. 取得授權 — — [License and purchase](https://nexcmp.com/zh-tw/docs/getting-started/license-and-purchase/)。
3. [Install](https://nexcmp.com/zh-tw/docs/getting-started/installation/)，然後執行 [setup wizard](https://nexcmp.com/zh-tw/docs/getting-started/setup-wizard/)。
4. 連線你的平台：[CloudStack](https://nexcmp.com/zh-tw/docs/infrastructure/cloudstack/) 或 [Proxmox VE](https://nexcmp.com/zh-tw/docs/infrastructure/proxmox/)。


---

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

# NexCMP 伺服器需求 {#requirements-for-the-nexcmp-server}

本頁面涵蓋執行 NexCMP 的伺服器。您的 CloudStack、Proxmox VE 或其他基礎設施需求請參閱 [Infrastructure requirements](https://nexcmp.com/zh-tw/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 | 僅限初次安裝時的安裝精靈與緊急存取 — 請參閱 [Installation](https://nexcmp.com/zh-tw/docs/getting-started/installation/#the-panel-port-3000) |
| 輸出 | 443/tcp 至 `nexcmp.com` | 授權啟用、每日授權檢查、更新 |
| 輸出 | 至您的 CloudStack API / Proxmox API | 佈建與同步 |
| 輸出 | 443/tcp 至您啟用的付款、電子郵件與 AI 提供者 | Stripe、PayPal、SMTP、AI 提供者等等 |

如果您希望 Let's Encrypt 直接發憑證，伺服器需要具備**公開 IPv4 位址**。如果網域透過 Cloudflare 進行代理，請參閱 [DNS and Cloudflare](https://nexcmp.com/zh-tw/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/zh-tw/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/zh-tw/docs/customers/resellers/)。 |
| 更新期限 | 您可藉此接收**更新與錯誤修正**的截止日期。Free授權自核准日起享有**1年**效期；您可以在授權頁面上以每年$99的價格進行續約。即使超過此日期，安全性修正仍會持續提供。 |
| 狀態 | `active`，或為suspended / expired / revoked。 |

## 免費年度到期時 {#when-the-free-year-ends}

當「Updates until」日期過後，軟體仍會**繼續執行**：客戶、服務與計費皆不受影響。您將停止接收新功能發布與錯誤修正更新（安全性修正仍會送達）。如需繼續使用，請至授權頁面 [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/zh-tw/docs/getting-started/installation/)）。若要變更註冊網域，請先至您的授權頁面 [nexcmp.com/licenses](https://nexcmp.com/licenses) 進行變更，然後使用新的 `--domain` 重新執行安裝程式。


---

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

# 安裝NexCMP {#install-nexcmp}

安裝程式是由您的授權伺服器所提供的一個單一指令碼。它會檢查機器、啟用您的授權、下載並驗證程式、安裝服務，並（選擇性地）透過 Let's Encrypt 憑證設定 nginx。

## 開始之前 {#before-you-start}

- 符合[requirements](https://nexcmp.com/zh-tw/docs/getting-started/requirements/)的伺服器，以及 root 權限。
- 來自您[license page](https://nexcmp.com/licenses)的**授權金鑰**與**主網域**——請參閱[License and purchase](https://nexcmp.com/zh-tw/docs/getting-started/license-and-purchase/)。
- 該網域的 DNS 記錄——請參閱[DNS and Cloudflare](https://nexcmp.com/zh-tw/docs/getting-started/dns-and-cloudflare/)。您也可以先安裝再稍後修復 DNS；安裝程式會告訴您缺少什麼，且可以直接再次執行。

## 安裝 {#install}

1. 登入伺服器並切換為 root（或使用 `sudo` 做為前綴）。
2. 執行您授權頁面上的指令。它看起來像這樣：

```bash
curl -fsSL https://nexcmp.com/install.sh | sudo bash -s -- \
  --license NXC-XXXXX-XXXXX-XXXXX-XXXXX \
  --domain cloud.example.com \
  --email admin@example.com
```

3. 等待勾選符號出現。全新安裝需要幾分鐘；首次啟動會建立資料庫結構描述，在慢速磁碟上可能需要最多一分鐘。
4. 閱讀結尾處的摘要。它會印出客戶端入口網站與管理員網址、**安裝代碼**以及下一步。

![安裝程式完成時顯示的入口網站網址、管理員網址與一次性安裝代碼](https://nexcmp.com/zh-tw/docs/images/getting-started/installation-01-finish.webp)

## 參數 {#parameters}

| 參數 | 預設值 | 含意 |
|---|---|---|
| `--license KEY` | 首次安裝時必填 | 授權金鑰。 |
| `--domain NAME` | 首次安裝時必填 | 主網域。必須與授權相符。`https://` 與結尾路徑將會被移除。 |
| `--email ADDRESS` | 無 | 用於 Let's Encrypt 到期通知的聯絡電子郵件。若未提供，則註冊憑證時將不包含電子郵件。 |
| `--port N` | `3000` | 面板的本機連接埠（1–65535）。 |
| `--no-nginx` | 關閉 | 不安裝或設定 nginx / TLS。當您執行自己的反向代理伺服器或想要先試用 NexCMP 時使用此選項。 |
| `--behind-cloudflare` | 自動偵測 | 強制使用「網域由 Cloudflare 代理」模式。通常會從 DNS 自動偵測。 |
| `--channel NAME` | `stable` | 版本通道。 |

再次**不帶參數**執行安裝程式會重複使用已儲存的參數（`/etc/nexcmp/install.conf`）並安全升級，同時保留資料、設定與帳號。這正是 `sudo nexcmp update` 的運作方式。

## 安裝程式的動作 {#what-the-installer-does}

1. **檢查機器**——Ubuntu 22.04/24.04、x86_64、至少 2 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 驗證）為網域取得 Let's Encrypt 憑證，並在這些名稱也能解析時為 `admin.<domain>` / `partner.<domain>` 取得憑證。如果 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/zh-tw/docs/getting-started/setup-wizard/)。

如果發生錯誤，請參閱 [Installation errors](https://nexcmp.com/zh-tw/docs/troubleshooting/installation-errors/)。


---

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

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

NexCMP 需要一個 DNS 名稱——其**主網域**——並以兩種模式運作。

## 模式 A：DNS 直接指向伺服器 {#mode-a-dns-points-straight-at-the-server}

1. 建立 **A** 記錄 `cloud.example.com → <server public IPv4>`（如果伺服器有 IPv6，則建立 **AAAA** 記錄）。
2. 選用（若您有使用）：`admin.cloud.example.com` 與 `partner.cloud.example.com` 指向相同的 IP。
3. 執行（或重新執行）[installer](https://nexcmp.com/zh-tw/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 的計時器自動續約。續約使用 webroot `/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)**。 |
| 記錄中顯示所有訪客都是 Cloudflare IP | 不在 Cloudflare 模式下 | 使用 `--behind-cloudflare` 重新執行安裝程式。 |

更多資訊請參閱 [Installation errors](https://nexcmp.com/zh-tw/docs/troubleshooting/installation-errors/)。


---

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

# 安裝精靈 {#setup-wizard}

> **管理員位置：** 精靈是位於 `/setup` 的獨立頁面，只會顯示到建立第一個管理員為止。之後相同的檢查項目會移至 System › Admin › Start（`/setup`）。

精靈可在四個簡單的步驟內，將全新安裝轉為可運作的控制面板。它運行於連接埠 3000（`http://<server-IP>:3000/setup`），或者當 TLS 已經啟用時，運行於 `https://<domain>/setup`。

::: warning 精靈在步驟 3 後會消失
建立管理員後，精靈即會關閉並刪除設定碼。若要之後存取控制面板，請使用管理主控台。
:::

## 步驟 0 — 設定碼 {#step-0-—-setup-code}

安裝程式會在結尾印出一組**一次性設定碼**。您可以使用以下指令再次查看：

```bash
sudo nexcmp status
```

將其貼到 **Setup code** 並點擊 **Continue**。此設定碼可保護精靈：任何發現開放連接埠的人都無法在沒有它的情況下建立管理員。

![要求輸入一次性設定碼的安裝精靈步驟 0](https://nexcmp.com/zh-tw/docs/images/getting-started/setup-wizard-00-code.webp)

## 步驟 1 — 授權 {#step-1-—-license}

| 欄位 | 值 |
|---|---|
| 授權金鑰 | `NXC-XXXXX-XXXXX-XXXXX-XXXXX` — 由安裝程式預設啟用，因此這個步驟通常會顯示「Activated for cloud.example.com」 |
| 主網域 | 授權合約上註冊的網域 |

如果安裝程式已經啟用授權，精靈會自動識別並繼續。否則請輸入金鑰與網域並點擊 **Activate**。錯誤會以紅色顯示 — 請參閱 [Installation errors](https://nexcmp.com/zh-tw/docs/troubleshooting/installation-errors/)。

![顯示授權已為主網域啟用的安裝精靈第 1 步](https://nexcmp.com/zh-tw/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**。其他功能皆可正常運作；您隨後可在 Infrastructure 下連接 CloudStack 或 Proxmox VE。在此之前，健康狀態面板會提醒您尚未連接任何來源。

![填入範例數值的 CloudStack API URL、API key 與 secret key 欄位的精靈第 2 步](https://nexcmp.com/zh-tw/docs/images/getting-started/setup-wizard-02-cloudstack-form.webp)

::: important 使用專屬的 CloudStack 帳戶
請勿使用 ROOT 管理員金鑰。請為 NexCMP 建立專屬的網域與帳戶並使用其 API key — 請參閱 [CloudStack](https://nexcmp.com/zh-tw/docs/infrastructure/cloudstack/#create-a-dedicated-account-and-api-key)。精靈會檢查所選網路是否屬於該金鑰的 Zone 與帳戶。
:::

![測試連線後：Zone 與 Guest network 清單、Zone display name 以及 Country 欄位](https://nexcmp.com/zh-tw/docs/images/getting-started/setup-wizard-02b-cloudstack-picked.webp)

如果您計劃僅使用 **Proxmox VE**，請選擇 **Connect later** 並遵循 [Proxmox VE](https://nexcmp.com/zh-tw/docs/infrastructure/proxmox/) 的說明。

## Step 3 — 管理員與品牌 {#step-3-—-administrator-and-brand}

| 欄位 | 規則 |
|---|---|
| Admin email (login) | 有效的電子郵件地址。這是您的管理員使用者名稱。 |
| Password | 至少 12 個字元，包含英文字母與數字。 |
| Brand name | 顯示給您的客戶（預設為「Cloud」）。最多 60 個字元。 |
| Support email | 預設為管理員電子郵件。 |

![包含管理員電子郵件、密碼、品牌名稱與支援電子郵件的精靈第 3 步](https://nexcmp.com/zh-tw/docs/images/getting-started/setup-wizard-03-admin.webp)

點擊 **Finish setup**。面板會重新啟動（約 1–2 秒），頁面會將您導向位於 `https://<domain>/admin/` 的管理員登入頁面。如果該位址尚未回應（DNS 或 TLS 處理中），則會將您導向目前位址上的 `/`。

![完成後的精靈，顯示面板正在重新啟動的訊息](https://nexcmp.com/zh-tw/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 與 web SSH 為**關閉**；頻寬計量為**開啟**。請參閱 [Modules](https://nexcmp.com/zh-tw/docs/infrastructure/modules/)。
- 如果您已連接 CloudStack：提供者 #1、其第一個 Zone、Guest network，以及附加至客戶虛擬機器以便您提供支援的操作金鑰對。

下一步：[First login](https://nexcmp.com/zh-tw/docs/getting-started/first-login/)。


---

<!-- source: https://nexcmp.com/zh-tw/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/zh-tw/docs/getting-started/installation/#the-panel-port-3000)） |
| 健康狀態檢查 | `https://<domain>/healthz` |

## 登入 {#sign-in}

1. 開啟`https://<domain>/admin`。
2. 輸入您在安裝精靈中建立的管理員電子郵件與密碼。
3. 您將進入**Dashboard**。若授權無效或未連線來源，頂部會顯示橫幅。

![管理員登入頁面](https://nexcmp.com/zh-tw/docs/images/getting-started/first-login-01-login.webp)

## 建議檢查清單 {#recommended-checklist}

請依序完成這些項目——每個項目皆有連結至對應頁面。

| # | 任務 | 頁面 |
|---|---|---|
| 1 | 為您的帳號啟用雙因素驗證 | [Security](https://nexcmp.com/zh-tw/docs/administration/security/) |
| 2 | 連線基礎設施來源（若您選擇「稍後連線」） | [CloudStack](https://nexcmp.com/zh-tw/docs/infrastructure/cloudstack/)或[Proxmox VE](https://nexcmp.com/zh-tw/docs/infrastructure/proxmox/) |
| 3 | 檢查區域以及機器範本/作業系統清單 | [Zones](https://nexcmp.com/zh-tw/docs/infrastructure/zones/)、[Templates](https://nexcmp.com/zh-tw/docs/infrastructure/templates/) |
| 4 | 檢閱方案與價格 | [Plans](https://nexcmp.com/zh-tw/docs/catalog/plans/) |
| 5 | 設定您的標誌、顏色與法律頁面 | [Branding](https://nexcmp.com/zh-tw/docs/customers/branding/)、[Legal](https://nexcmp.com/zh-tw/docs/customers/legal/) |
| 6 | 設定外寄電子郵件並發送測試信 | [SMTP and emails](https://nexcmp.com/zh-tw/docs/administration/smtp-and-emails/) |
| 7 | 啟用至少一個支付管道並測試加值 | [Payment channels](https://nexcmp.com/zh-tw/docs/billing/payment-channels/) |
| 8 | 決定您要銷售的模組 | [Modules](https://nexcmp.com/zh-tw/docs/infrastructure/modules/) |
| 9 | 以客戶身分下單測試並將其刪除 | [Ordering](https://nexcmp.com/zh-tw/docs/portal/ordering/) |
| 10 | 建立第一次備份 | [Backup and restore](https://nexcmp.com/zh-tw/docs/getting-started/backup-and-restore/) |

## 建立您的第一筆訂單（冒煙測試） {#create-your-first-order-smoke-test}

1. 在私密視窗中開啟客戶入口網站並註冊測試帳號。
2. 新增餘額（使用折價券或測試付款）。
3. 訂閱您區域中的最小方案。
4. 觀看它出現在管理員後台的 Services › Virtual Machines 中、開啟其主機畫面，然後將其銷毀。

若虛擬機器未能達到*執行中*狀態，請開啟**Infrastructure › Cloud provider › Sync & errors**並閱讀錯誤訊息。


---

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

# 更新 NexCMP {#updating-nexcmp}

> **管理者後台位置：**System › Admin › License & updates (`/license`) → *Update* 卡片。

## 您將獲得 {#what-you-receive}

| 發布類型 | 交付時間 |
|---|---|
| 安全性修正 | **始終**提供，即使超過您的「更新截止」日期 |
| 功能發布 | 僅限於在您的「更新截止」日期**當天或之前**發布的內容 |

您可以在 **License & updates** 下查看這兩個日期。請至 [nexcmp.com/licenses](https://nexcmp.com/licenses) 續約您的授權。

## 從管理主控台更新 {#update-from-the-admin-console}

1. 開啟 **System › Admin › License & updates**。
2. 在 **Update** 卡片中點擊 **Check for update**。該卡片會顯示目前版本、您可以安裝的最新版本、相關的 *security* 標籤以及變更日誌。
3. 點擊 **Update to X.Y.Z** 並確認。程式會下載該版本、驗證其 **SHA-256 與 Ed25519 簽章**、以原子方式替換二進位檔（保留一個 `.bak` 複本）並重新啟動。預計會有大約 **10 秒**的停機時間。
4. 重新載入頁面，並在 License & updates 的右上角檢查版本。

![顯示執行中版本與檢查新版本按鈕的 Update 卡片](https://nexcmp.com/zh-tw/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/zh-tw/docs/getting-started/backup-and-restore/)。
2. 請閱讀Update卡片中的變更記錄。如需了解1.3版以來的變更，請參閱[至1.6.1版的版本資訊](https://nexcmp.com/zh-tw/docs/getting-started/release-notes/)，包括VPN代理程式更新與Bare Metal定價規則。
3. 請在離峰時段進行更新；執行中的虛擬機器不會受到影響，但客戶在幾秒鐘內將無法使用入口網站。

## 更新之後 {#after-you-update}

- 執行 `sudo nexcmp status` 並確認兩個服務皆為主動執行狀態。
- 開啟管理員 Dashboard 與 **Needs attention** 頁面。
- 資料庫遷移會在升級至新版本首次啟動時自動執行。
- 若您有執行VPN節點，請個別更新其代理程式並檢查用量讀數。更新控制面板僅代表新版代理程式已可供使用，並不表示所有遠端節點都已在執行該版本。請參閱[VPN節點流量配額](https://nexcmp.com/zh-tw/docs/infrastructure/vpn-proxy-nodes/#data-allowance-on-a-vpn-node)。

如果更新失敗，請參閱 [Update errors](https://nexcmp.com/zh-tw/docs/troubleshooting/update-errors/)。


---

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

# 版本資訊 {#release-notes}

> **管理後台位置：**System › Admin › License & updates（`/license`）中的**Update**卡片。

本版本資訊涵蓋1.3版之後至**NexCMP 1.6.1**的變更。更新前請先備份，並使用您安裝系統中**Update**卡片所提供的版本。指令與簽章檢查方式請參閱[更新NexCMP](https://nexcmp.com/zh-tw/docs/getting-started/updating/)。

## 1.6.1

- **Bare Metal指標：**客戶端**Overview**提供CPU、RAM、磁碟活動與網路資訊圖塊及近期歷史記錄。缺少測量值時會顯示破折號與原因。網路讀數需要流量計數器；系統不會從iDRAC硬體清單推算該數值。
- **Bare Metal 範例方案：**範例名稱使用`BM-40C-<RAM>`。您未曾編輯過的內建範例方案將獲得中性名稱。已編輯的方案會予以保留，且被參照的方案會保留其代碼。在將方案設為可銷售之前，請先確認實際的伺服器硬體。
- **方案變更：**管理後台的申請清單於伺服器端進行排序，並在水平捲動時保持操作按鈕可見。
- **回報錯誤：**表單捲動時會保持按鈕可見。密碼遮罩會保留周圍的診斷文字。
- **載入：**頁面資源與常用管理端資料改為提前載入，以縮短頁面切換延遲。

請參閱[Bare Metal設定、定價與客戶控制項](https://nexcmp.com/zh-tw/docs/infrastructure/dedicated/)及[回報錯誤](https://nexcmp.com/zh-tw/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匯率。系統更新不會將現有價格重新解讀為美元。
- **客戶伺服器頁面：**支援提前續費、排程變更計費週期、申請變更方案、查閱發票，並於安裝完成後檢視作業系統登入資訊。新擁有者無法查看前任擁有者的密碼。
- **客戶資料：**以八個分頁整理總覽、服務、計費、配額、安全性、支援、推薦與記錄。所有服務共用同一個支援搜尋與排序的表格。
- **服務操作：**鎖定、解鎖、不退款取消或退款取消均使用通用對話方塊。退款會退回原本的錢包或額度分配；金流處理商不會自動退款。

請參閱[專屬伺服器](https://nexcmp.com/zh-tw/docs/infrastructure/dedicated/)與[管理客戶](https://nexcmp.com/zh-tw/docs/customers/managing-customers/)。在NexCMP中仍無法使用BYOIP以及將客戶子網路連接至Bare Metal伺服器。

## 1.5.2

主管理員可開啟**Report a bug**（位於**Docs**旁），無需另外登入即可向授權帳戶發送工單。診斷資訊為選填項目。員工、客戶與AI助理無法透過此操作發送回報。請參閱[Report a bug](https://nexcmp.com/zh-tw/docs/administration/report-a-bug/)。

## 1.5.1

- **VPN用量：**Agent節點會向控制面板回報流量。用盡GB配額的訂閱將會被中斷；在頻寬升級或進入新週期後將重新可用。未回報用量的節點會顯示**Not measured**，且不會依據GB中斷。
- **VPN Agent：**1.5.1版會重試未確認的用量、在關機時發送最終流量，並在端點停止時關閉已建立的連線。請更新遠端Agent以及控制面板。
- **已淘汰的VPN加購項目：**High IP Reputation、High Concurrency與High Priority Network已不再販售。其費用已從現有訂閱的未來續費金額中移除；過去的計費週期不予退款。若加購項目已從目錄中刪除，請手動檢查續費金額。
- **協定標籤：**IPv4 HTTP Proxy為純HTTP。IPv4位址不會輪替。IPv6 Proxy的連接埠443提供SOCKS5服務；其並非HTTPS Proxy端點。
- **全新設定：**資料庫初始化會重試控制面板與worker之間的暫時性移轉衝突，因此儲存第一個提供者時無需重新啟動。

請參閱[VPN與IPv6 Proxy節點](https://nexcmp.com/zh-tw/docs/infrastructure/vpn-proxy-nodes/)。

## 1.5.0

**AI Models**為選用的閘道與計費模組，預設為關閉。您可以新增自行營運或獲授權轉售的模型來源、同步模型、設定價格與路由、啟用模型，然後開放銷售。系統未隨附任何提供者帳戶、模型或價格。此模組獨立於AI Chat與AI Agent模組。請參閱[AI Models](https://nexcmp.com/zh-tw/docs/infrastructure/ai-models/)。

## 1.4.2

IPv6 Proxy節點安裝會使用發行套件中隨附的常駐程式與網路指令碼。控制面板需要`sshpass`以進行基於密碼的SSH安裝。控制面板會執行輪替排程，且節點設定會在分配時排除閘道位址。品牌自訂功能可設定自訂VPN服務顯示名稱。請參閱[VPN與IPv6 Proxy節點](https://nexcmp.com/zh-tw/docs/infrastructure/vpn-proxy-nodes/)。

## 1.4.0–1.4.1

- **AI管理：**提供管理員AI Chat、個人AI帳戶、管理員API金鑰、管理員MCP伺服器、OAuth連接器、組態匯入／匯出以及設定檢查清單。請參閱[使用AI進行設定](https://nexcmp.com/zh-tw/docs/configure-with-ai/overview/)。
- **授權：**Free與Source工作流程包含官方組建與自訂原始碼組建。帳戶、授權、下載與說明文件均使用`nexcmp.com`。請參閱[授權與購買](https://nexcmp.com/zh-tw/docs/getting-started/license-and-purchase/)。
- **說明文件連結：**管理後台中的**Docs**可開啟當前頁面的指南。
- **幣別：**全新安裝預設會遵循客戶的語言。USD/VND來自公開匯率表或您的固定匯率。請參閱[幣別與匯率](https://nexcmp.com/zh-tw/docs/catalog/currency-and-exchange-rates/)。
- **混合來源區域：**當CloudStack與Proxmox VE共用區域時，公開雲端伺服器價格依然有效。配置方案會使用其各自的基礎架構來源。
- **衍生自方案的價格：**百分比為相對於售價的毛利率。在成本為$60的情況下，40%的毛利率在任何四捨五入前得出的價格為$100。

## 升級檢查清單 {#upgrade-checklist}

1. 備份、閱讀**Update**卡片、更新並執行`sudo nexcmp status`。
2. 在依賴GB中斷功能之前，請先更新VPN Agent並確認節點有回報測得的流量。
3. 若使用Bare Metal，在開放銷售或正式營運前，請檢查管理網路欄位、必要工具、計價單位、範本與範例方案。
4. 開啟客戶資料並驗證其服務清單。在確認退款取消之前，請檢查金額與原始付款分配。
5. 在基礎設施準備就緒之前，請將選用模組保持關閉。針對AI Models，在開放銷售前請先確認提供者、已定價的模型以及已成功的客戶請求。


---

<!-- source: https://nexcmp.com/zh-tw/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/zh-tw/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/zh-tw/docs/getting-started/uninstall/ -->

# 解除安裝 NexCMP {#uninstall-nexcmp}

::: warning 客戶將無法存取
解除安裝會停止器門戶與計費。您 CloudStack 或 Proxmox VE 上的虛擬機器將持續執行，但將失去管理與計費功能。請先建立 [backup](https://nexcmp.com/zh-tw/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/zh-tw/docs/getting-started/cli-reference/ -->

# `nexcmp` 指令參考 {#nexcmp-command-reference}

安裝程式會在 `/usr/local/bin/nexcmp` 放置一個輔助工具。請在 NexCMP 伺服器上執行它。會變更系統的指令需要 `sudo`。（用於 API 的客戶端工具是不同的程式，請參閱 [cmp CLI](https://nexcmp.com/zh-tw/docs/developers/cmp-cli/)。）

| 指令 | 需要 root | 功能 |
|---|---|---|
| `nexcmp status` | 否（使用 `sudo` 取得更多詳細資料） | 版本、服務狀態（`nexcmp`、`nexcmp-vmd`）、`/healthz`、授權摘要、公開連接埠狀態、若精靈未完成則顯示設定代碼 |
| `nexcmp update` | 是 | 使用儲存的參數執行已安裝版本中隨附的安裝程式 — 請參閱 [Updating](https://nexcmp.com/zh-tw/docs/getting-started/updating/) |
| `nexcmp backup [dir]` | 是 | 備份至 `/var/backups/nexcmp`（或 `dir`）——見 [Backup and restore](https://nexcmp.com/zh-tw/docs/getting-started/backup-and-restore/) |
| `nexcmp uninstall [--purge]` | 是 | 移除服務與程式；`--purge` 同時也會移除資料——見 [Uninstall](https://nexcmp.com/zh-tw/docs/getting-started/uninstall/) |
| `nexcmp open-port [minutes]` | 是 | **Emergency**：在所有介面上監聽面板連接埠（預設 3000）1–1440 分鐘（預設 30），然後自動關閉 |
| `nexcmp close-port` | 是 | 立即關閉緊急視窗 |
| `nexcmp fix-owner` | 是 | 將 `/var/lib/nexcmp` 中屬於 root 的檔案還給 `nexcmp` 使用者 |

## `nexcmp status`

```text
Version   : 1.6.1
nexcmp     : active
nexcmp-vmd : active
healthz    : ok
License   : active · domain cloud.example.com · token valid until 2026-11-12 · updates until 2027-10-30
Public port: 127.0.0.1 only (nginx proxy; emergency: sudo nexcmp open-port)
```

如果資料目錄中的檔案是由 root 擁有（例如以 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/zh-tw/docs/infrastructure/requirements/ -->

# 基礎架構需求 {#infrastructure-requirements}

> **管理員位置**：Infrastructure（左側選單區域）與 System › Admin › License & updates（`/license`）用於啟用模組。

此頁面列出每個模組在 NexCMP 伺服器**外部**的需求。至於伺服器本身（Ubuntu、記憶體、磁碟、連接埠），請參閱 [Requirements for the NexCMP server](https://nexcmp.com/zh-tw/docs/getting-started/requirements/)。若要啟用模組，請參閱 [Modules](https://nexcmp.com/zh-tw/docs/infrastructure/modules/)。

## 逐一介紹模組 {#module-by-module}

| 模組 | 最低基礎設施 | 詳細資料 |
|---|---|---|
| **Virtual Machines on CloudStack** | Apache CloudStack 4.23（已測試）、KVM、具備客體網路與公開 IP 範圍的進階區域；具備 API 金鑰的專用網域與帳戶（絕非 ROOT）；至少一個就緒範本與一個服務方案 | [CloudStack](https://nexcmp.com/zh-tw/docs/infrastructure/cloudstack/) |
| **Virtual Machines on Proxmox VE** | Proxmox VE 9.x（已在 9.2 驗證）；具備自訂角色的 API Token；可複製的儲存空間；網橋；帶有閘道的 IPv4 區塊；每個作業系統與每個節點一個 cloud-init 範本 | [Proxmox VE](https://nexcmp.com/zh-tw/docs/infrastructure/proxmox/) |
| **OS templates** | CloudStack：具備 libguestfs 與映像檔網頁伺服器的 Linux 建置機器。Proxmox VE：具備客體代理程式的 cloud-image 範本 | [OS templates](https://nexcmp.com/zh-tw/docs/infrastructure/templates/) |
| **Bare metal / Dedicated Server** | 可從管理網路上的面板透過 HTTPS（Redfish）存取的 Dell 伺服器與 iDRAC 9；該網路上提供 ISO 檔案的 HTTP 伺服器；供 NexCMP 服務使用的可寫入 ISO 資料夾 | [Dedicated servers](https://nexcmp.com/zh-tw/docs/infrastructure/dedicated/) |
| **AI Models** | 一或多個您獲授權轉售的模型來源，具備相容OpenAI或相容Anthropic的API及您自備的金鑰；從控制台到各來源的連外HTTPS（連接埠443、公網網域名稱），或列於Allowed internal hosts下的內部閘道；無需GPU或特殊硬體 | [AI Models](https://nexcmp.com/zh-tw/docs/infrastructure/ai-models/) |
| **VPN** | 一個或多個 Linux 主機（x86_64、systemd、root），其介面上具有公開 IPv4 位址或路由至該位址，且具備連至您面板的對外 HTTPS | [VPN 與代理節點](https://nexcmp.com/zh-tw/docs/infrastructure/vpn-proxy-nodes/) |
| **IPv6 Proxy** | 具備公開 IPv4、連接埠 80、443 與 60001-65535 可用，以及適用於對外流量之由 /32 至 /64 之 IPv6 前綴的 Linux 主機（x86_64、systemd、`nft`、`ip`、`ss`、`sysctl`）；用於一次性安裝且帶密碼的 SSH 存取 | [VPN 與代理節點](https://nexcmp.com/zh-tw/docs/infrastructure/vpn-proxy-nodes/) |
| **Object Storage (S3)** | 具備 RADOS Gateway (RGW)、Admin Ops 使用者以及連接埠 443 公用 HTTPS 端點的 Ceph 叢集 | [S3](https://nexcmp.com/zh-tw/docs/infrastructure/s3/) |
| **Kubernetes** | 已啟用 Kubernetes Service (CKS) 的 CloudStack、至少一個 Kubernetes 版本 ISO，以及一個剛好 2 vCPU 與 2048 MB 的免費控制平臺服務方案 | [Kubernetes and Private Cloud](https://nexcmp.com/zh-tw/docs/infrastructure/kubernetes-and-private-cloud/) |
| **Private Cloud** | 具備 VPC 方案且每個頻寬方案一個網路方案（外加一個鎖定的 1 Mbps 方案）的 CloudStack | [Kubernetes and Private Cloud](https://nexcmp.com/zh-tw/docs/infrastructure/kubernetes-and-private-cloud/) |
| **OS & ISO Images** | 次要儲存 VM 可連線至網際網路以下載客戶映像檔（直接連結、無重新導向）的 CloudStack；CloudStack 帳戶可註冊範本與 ISO | [Modules](https://nexcmp.com/zh-tw/docs/infrastructure/modules/) |
| **Bandwidth** | 預設來源無需額外設定：使用量是從 CloudStack VM 統計資料讀取。Proxmox VE 上的 VM 不計費 | [Bandwidth](https://nexcmp.com/zh-tw/docs/catalog/bandwidth/) |
| **AI Chat and AI Agent** | 面板伺服器可連線的相容 OpenAI API（基底 URL、模型與金鑰）。您的伺服器上無需額外軟體 | [AI providers](https://nexcmp.com/zh-tw/docs/ai/ai-providers/) |
| **DDoS & BGP** | 需要邊界路由器主機與以 root 身分執行之常駐程式（BGP、過濾、流量統計）的附加套件。它不屬於標準安裝的一部分 | [Modules](https://nexcmp.com/zh-tw/docs/infrastructure/modules/) |
| **DDoS Shield** | DDoS & BGP 附加元件 | [Modules](https://nexcmp.com/zh-tw/docs/infrastructure/modules/) |
| **Web SSH terminal** | 獨立的 SSH 代理服務與其路由。它不屬於標準安裝的一部分；AI Agent 不需要它 | [Modules](https://nexcmp.com/zh-tw/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 保持管理網路為私有
iDRAC 與hypervisor管理位址應位於客戶無法觸及的網路上。NexCMP會拒絕不在您允許的私有範圍內的iDRAC位址。
:::

## 開始銷售前的檢查清單 {#checklist-before-you-sell}

1. 第一個服務背後的基礎設施已連線，且 **Test connection** 呈現綠色。
2. 區域已準備好銷售 (請參閱 [Zones](https://nexcmp.com/zh-tw/docs/infrastructure/zones/))：具備啟用的後端、方案與準備就緒的範本。
3. 已設定付款管道 (請參閱 [Payment channels](https://nexcmp.com/zh-tw/docs/billing/payment-channels/))。
4. 電子郵件功能正常 (請參閱 [SMTP and e-mails](https://nexcmp.com/zh-tw/docs/administration/smtp-and-emails/))。
5. 您已下單一筆測試訂單並刪除了虛擬機器。


---

<!-- source: https://nexcmp.com/zh-tw/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/zh-tw/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**。完成安裝精靈後，面板僅會傾聽迴圈介面 (loopback interface)。
3. **panel** (`nexcmp.service`) 提供客戶入口網站、管理主控台、REST API、安裝精靈以及節點所需的下載項目 (agent二進位檔、安裝腳本、`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)、**payment gateways** (Stripe、PayPal、USDT 與銀行轉帳提供者，亦會回呼您的 webhook URLs)、**您的 SMTP 伺服器**、具備 OpenAI 相容 API 的 **AI provider**，以及選用的 **Telegram**。
6. **VPN nodes** 執行 `cmp-agent`。每個節點透過一次性權杖註冊一次，接著每 5 秒透過 HTTPS 向面板發送一次心跳訊號，並在回覆中接收其設定。**IPv6 proxy nodes** 由面板透過 SSH 安裝一次，之後再從面板拉取設定。
7. 狀態存放在 SQLite 資料庫以及 `/var/lib/nexcmp` 中的少數檔案。CloudStack、Proxmox、S3、iDRAC 和 AI provider 的憑證皆使用主金鑰檔案於同個區域中進行加密儲存 (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 | 無 | 套用管理主控台要求的更新（路徑單元會等待請求） |
| `cmp-agent`（在 VPN 節點上） | root | VPN 監聽連接埠 | 向面板回報、在公開 IPv4 上執行代理監聽器 |

面板與背景工作處理常式以一般使用者身分執行，不具任何 Linux 權限，且檔案系統除 `/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/zh-tw/docs/getting-started/backup-and-restore/)。主金鑰檔案必須與資料庫一同備份，否則還原後的資料庫將無法解密其儲存的憑證。

## 連線架構 {#who-connects-to-whom}

| 方向 | 路徑 | 連接埠 | 注意事項 |
|---|---|---|---|
| 客戶至面板 | 網際網路、DNS、選用的 Cloudflare、nginx | 443 | 請參閱 [DNS 與 Cloudflare](https://nexcmp.com/zh-tw/docs/getting-started/dns-and-cloudflare/)。 |
| 面板至授權伺服器 | `nexcmp.com` | 443 | 啟用、每日檢查與更新。 |
| 面板至 CloudStack | API | 443 或 8080 | 虛擬機器主控台、頻寬與 Kubernetes 功能使用相同的端點。 |
| 面板至 Proxmox VE | API 與 WebSocket 主控台 | 8006 | 憑證透過 SHA-256 釘選。 |
| 面板至 iDRAC | Redfish | 443、VNC 5901 | 僅限管理網路。 |
| iDRAC 至 ISO 伺服器 | HTTP | 您的連接埠 | iDRAC 會拉取 ISO。 |
| 面板至 Ceph RGW | Admin Ops | 443 | |
| 面板至 SMTP | SMTP | 587 或 465 | |
| 面板至 AI 提供者 | HTTPS | 443 | 僅在 AI 模組開啟時。 |
| 支付閘道至面板 | Webhook | 443 | Stripe 與 PayPal 回呼。 |
| 節點至面板 | `cmp-agent` | 443 | 註冊、心跳、升級。 |
| 面板至 IPv6 代理節點 | SSH | 您輸入的連接埠 | 僅限安裝一次。 |

## 為什麼這很重要 {#why-it-matters}

- **連得到的主機就是會被攻擊的主機。** 設定精靈完成後，請保持連接埠 3000 關閉。啟用 TLS 時，安裝程式會自動執行此操作。
- **背景程式必須正在執行**，才能建立或計費任何項目。`sudo nexcmp status` 顯示兩項服務與健康狀態檢查。
- **規劃對外防火牆。** 若面板伺服器的對外流量經過過濾，請允許上方表格中的目的地位址。
- **管理流量不走公開路徑。** 連線至 CloudStack、Proxmox VE、iDRAC 與 Ceph 的流量會直接從面板伺服器連至這些系統，絕不透過 nginx 或 Cloudflare。


---

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

# 模組 {#modules}

> **管理員介面位置：** System › Admin › License & updates (`/license`)，**Module** 卡片。

## 功能 {#what-it-does}

模組是作為一個整體可切換開關的服務或功能。**關閉**的模組會在管理員選單中隱藏且客戶無法購買；若該模組為附加模組，其 API 路由會回應 `404 module_disabled`。開啟模組僅會公開該功能：其背後的基礎設施仍必須連線（請參閱最後一欄）。

## 需求 {#requirements}

| 項目 | 需求 |
|---|---|
| 帳號 | 具備寫入權限的管理員。唯讀員工可以看到開關但無法變更。 |
| 基礎架構 | 請參閱表格：每個模組皆列出其需求。 |
| 相依於 | 部分模組需要其他模組（DDoS 防禦需要 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/zh-tw/docs/images/infrastructure/modules-01-license-modules.webp)

### 各模組 {#the-modules}

| 模組（顯示名稱） | 預設值 | 新增功能 | 需求 | 頁面 |
|---|---|---|---|---|
| **Virtual Machines** | 永遠開啟 | 虛擬機器目錄、訂閱、主控台、快照 | CloudStack 或 Proxmox VE | [CloudStack](https://nexcmp.com/zh-tw/docs/infrastructure/cloudstack/), [Proxmox VE](https://nexcmp.com/zh-tw/docs/infrastructure/proxmox/) |
| **Bandwidth** | **開啟** | 虛擬機器、Kubernetes 與 S3 的配額、附加元件、警報與超額動作 | 無額外需求（CloudStack 虛擬機器統計資料） | [Bandwidth](https://nexcmp.com/zh-tw/docs/catalog/bandwidth/) |
| **OS & ISO Images** | 關閉 | 客戶註冊自己的作業系統映像檔與 ISO，依 GB 計費 | CloudStack；其次要儲存虛擬機器的網際網路存取權 | [Requirements](https://nexcmp.com/zh-tw/docs/infrastructure/requirements/) |
| **Kubernetes** | 關閉 | Kubernetes 叢集 (CKS) | 已啟用 CKS 的 CloudStack | [Kubernetes and Private Cloud](https://nexcmp.com/zh-tw/docs/infrastructure/kubernetes-and-private-cloud/) |
| **Private Cloud** | 關閉 | 具備專用頻寬方案的 VPC | CloudStack VPC 與網路方案 | [Kubernetes and Private Cloud](https://nexcmp.com/zh-tw/docs/infrastructure/kubernetes-and-private-cloud/) |
| **Object Storage** | 關閉 | Ceph RGW 上的 S3 帳戶，按量計費 | Ceph RGW 與具備 S3 服務的區域 | [S3](https://nexcmp.com/zh-tw/docs/infrastructure/s3/) |
| **VPN** | 關閉 | 您自己的節點上的 VPN | 執行 `cmp-agent` 的節點 | [VPN 與代理節點](https://nexcmp.com/zh-tw/docs/infrastructure/vpn-proxy-nodes/) |
| **IPv6 Proxy** | 關閉 | 您自己的節點上的 IPv6 代理 | 具備 IPv6 前綴的代理節點 | [VPN 與代理節點](https://nexcmp.com/zh-tw/docs/infrastructure/vpn-proxy-nodes/) |
| **Bare Metal** | 關閉 | 透過 iDRAC 管理 Dell 伺服器：訂單、作業系統安裝、主控台、電源 | 管理網路上的 iDRAC 9 | [Dedicated servers](https://nexcmp.com/zh-tw/docs/infrastructure/dedicated/) |
| **AI Models** | 關閉 | 銷售AI模型存取權的閘道：單一金鑰適用多個模型、依模型計價、使用量限制、記錄檔、錢包計費 | 自備的模型來源：相容OpenAI或相容Anthropic的API及自備金鑰 | [AI Models](https://nexcmp.com/zh-tw/docs/infrastructure/ai-models/) |
| **AI** | 關閉 | AI Chat（自動化支援）與 AI Agent（以日常語言進行虛擬機器管理） | 相容 OpenAI 的提供者 | [AI providers](https://nexcmp.com/zh-tw/docs/ai/ai-providers/) |
| **DDoS Shield** | 關閉 | 針對客戶的 IP 保護；需要 DDoS 與 BGP，因此在未啟用時其開關會保持停用 | DDoS & BGP 附加元件 | 下方 |
| **DDoS & BGP** | 關閉，**附加元件** | 邊緣路由器主控台：BGP、RTBH、XDP、連線階段與邊緣流量 | 具備 root daemon 的邊緣主機 | 下方 |

### 哪個開關負責什麼 {#which-switch-does-what}

- **Bare Metal**分為兩個層級。模組開關可顯示管理後台選單與 API。向客戶銷售則是位於**Services › Dedicated Server**底下的獨立開關（需輸入文字確認），且在您於**Infrastructure › Bare Metal › Safety**開啟 **live ops** 之前，對 iDRAC 的所有寫入操作都會被阻擋。請參閱[專用伺服器](https://nexcmp.com/zh-tw/docs/infrastructure/dedicated/)。
- 對於 **Kubernetes**、**Private Cloud**、**VPN**、**IPv6 Proxy** 與 **Images**，模組開關與服務頁面上的銷售開關會對應到相同的設定。
- **AI** 同時也需要在 **System › Settings › AI provider** 下設定提供者。
- **AI Models**分為兩層。模組開關會顯示管理選單與API。向客戶銷售則是位於AI Models頁面頂部的獨立銷售開關，預設為關閉。請參閱[AI Models](https://nexcmp.com/zh-tw/docs/infrastructure/ai-models/)。

### 模組在啟動時讀取 {#modules-read-at-start-up}

有三項功能不是普通的開關。它們會在**服務啟動時讀取一次**，並且需要標準安裝所不包含的基礎設施。

| 功能 | 設定 | 狀態 | 需求 |
|---|---|---|---|
| DDoS 與 BGP | `module_ddos` | 關閉時顯示為**附加元件套件**，開啟時顯示為**已安裝**。主控台中沒有開關。 | 以 root 執行的邊緣路由器 daemon（BGP、RTBH、XDP、流量統計）。面板是以無特權的使用者身分執行，無法執行它們。 |
| AI | `module_ai` | 一般開關。路由會立即跟進；AI Chat 的背景作業（工單調查、排程回覆）會在服務下次重新啟動時啟動。主控台會建議重新啟動。 | AI 提供者。 |
| Web SSH 終端機 | `feature_ssh_web` | 預設關閉，主控台中無開關 | 獨立的 SSH 代理服務及其路由。沒有它，入口網站的 Console 頁籤將只會顯示 VNC。**AI Agent 不需要它**：它是透過面板本身建立的 SSH 連線來執行命令。 |

修改啟動設定後，請重新啟動服務：`sudo systemctl restart nexcmp nexcmp-vmd`。

## 驗證 {#verify}

1. 重新載入後，模組的選單項目隨即會出現（或消失）。
2. 對於面向客戶的模組，已登入的客戶會在入口網站中看到新的選單項目。關閉的模組將不會顯示任何內容或顯示「即將推出」。

## 限制與注意事項 {#limits-and-notes}

- 關閉模組不會刪除任何資料。執行中的虛擬機器、叢集、S3 帳戶和訂閱會繼續運作並計費；客戶只是無法建立新的項目。
- 配額頁面僅會列出其模組為開啟狀態的服務。

## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| 選單項目未出現 | 頁面未重新載入 | 重新載入管理主控台。 |
| DDoS Shield 開關已停用 | 未安裝 DDoS & BGP | DDoS Shield 需要 DDoS & BGP 附加元件。 |
| 「此模組為附加套件，無法在此切換」（HTTP 409 或 422） | 您（或某個腳本）嘗試切換 DDoS & BGP | 這是附加套件；沒有對應的開關。 |
| 「DDoS Shield 需要 DDoS & BGP 附加元件」 | 同上，針對 DDoS Shield | 請先安裝附加元件。 |
| 模組路由回應 404 `module_disabled` | 模組已關閉 | 將模組切換為開啟。 |
| AI Chat 有回應但工單調查未啟動 | AI 模組在未重新啟動的情況下被開啟 | `sudo systemctl restart nexcmp nexcmp-vmd`. |
| 唯讀員工無法儲存 | 其角色為唯讀 | 請使用管理員帳戶。 |




---

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

# 區域 {#zones}

> **管理員位置：** Infrastructure › Datacenter › Zone (`/infra/zones`)。區域的詳細頁面為 `/infra/zones/<id>`。

## 功能 {#what-it-does}

**區域（zone）**是客戶在訂購時選擇的位置：帶有國旗的國家與城市，以及在該處銷售的服務。這是一個銷售概念，獨立於其背後平台的區域、叢集和節點。在區域背後，您可以附加**基礎設施**：CloudStack 區域、Proxmox VE 叢集、具有 IP 範圍的 VPN 節點、S3 後端。

區域 1 是由 [安裝精靈](https://nexcmp.com/zh-tw/docs/getting-started/setup-wizard/) 建立的，採用您輸入的顯示名稱與國家。當您在更多地方擁有基礎設施，或要為 VPN 與 S3 提供各自的位置時，請新增更多區域。

## 需求 {#requirements}

| 項目 | 需求 |
|---|---|
| 權限 | 管理員帳戶。唯讀員工角色僅可檢視而無法變更。 |
| 基礎架構 | 除非有項目附加到區域，否則該區域不會銷售任何東西（請參閱下方的「哪種服務在哪裡銷售」）。 |
| 相依於 | 用於虛擬機器的 [CloudStack](https://nexcmp.com/zh-tw/docs/infrastructure/cloudstack/) 或 [Proxmox VE](https://nexcmp.com/zh-tw/docs/infrastructure/proxmox/)、用於 VPN 的 [VPN and proxy nodes](https://nexcmp.com/zh-tw/docs/infrastructure/vpn-proxy-nodes/)、用於物件儲存的 [S3](https://nexcmp.com/zh-tw/docs/infrastructure/s3/)。 |

## 準備基礎設施 {#prepare-the-infrastructure}

不需要。區域是 NexCMP 內的記錄。

## 在 NexCMP 中連線 {#connect-in-nexcmp}

### 建立區域 {#create-a-zone}

1. 開啟 **Infrastructure › Datacenter › Zone** 並點擊 **Add zone**。
2. 填寫表單：

   | 欄位 | 範例值 | 注意事項 |
   |---|---|---|
   | 國家 | `United States` | 選擇國旗。 |
   | 城市 | `New York` | 選填。 |
   | 名稱（越南文）、名稱（英文） | `New York` | 客戶在各語言中看到的名稱。 |
   | Slug | `us-new-york` | a-z、0-9、連字號，2-32 個字元。會根據國家和城市自動填入，直到您自行輸入為止。 |
   | 可見性 | 公開 | **公開**區域對所有客戶可見；**隱藏**區域僅由管理員指定。 |
   | 順序 | `0` | 列表中數字較小的排在前面。 |
   | 在此區域銷售的服務 | 虛擬機器 (VM)、VPN、Object Storage (S3) | 請勾選至少一項。 |
   | 啟用 | 開啟 | **Off** 會對客戶隱藏此區域。 |
   | 預設值 | 關閉 | 針對尚未選擇的客戶預先選取的區域。剛好有一個預設區域。 |

      ![包含國家、城市、代稱與已勾選服務的新增區域對話框](https://nexcmp.com/zh-tw/docs/images/infrastructure/zones-01-add-zone.webp)

3. 點擊 **Create zone**。列表會顯示該區域的國旗、擁有者、服務、狀態以及 VM、方案與附加基礎架構的數量。

      ![包含預設區域與第二個區域的區域列表](https://nexcmp.com/zh-tw/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/zh-tw/docs/images/infrastructure/zones-03-detail.webp)

### 各服務的銷售地點 {#which-service-sells-where}

| 服務 | 如何加入區域 |
|---|---|
| CloudStack 上的虛擬機器 | 精靈 (或 **Infrastructure › Cloud provider › CloudStack**) 將 CloudStack 附加至區域 1。 |
| Proxmox VE 上的虛擬機器 | 在叢集的 **Clusters** 分頁中，選擇 **Attach cluster to zone**。叢集會加入**現有**的區域，通常是透過 CloudStack 銷售的區域。 |
| VPN | 回報其公有 IP 範圍的 VPN 節點會為其國家建立 (或加入) 區域，並將範圍放入 VPN 池中。您也可以在 **VPN IP pools** 下指派範圍的區域與節點。 |
| IPv6 代理 | 新的 IPv6 代理節點會在**關閉**狀態下建立其區域。請在此處將區域開啟，以便客戶選取。 |
| Object Storage (S3) | 在區域上勾選 S3 服務，然後在 **Ceph S3 (RGW)** 下附加後端。 |

### 區域何時可以銷售虛擬機器？ {#when-can-a-zone-sell-virtual-machines}

區域會顯示 **not ready to sell VMs** 標籤，直到該後端上至少有一個啟用且可銷售的後端 **and** 至少有一個可見的方案 **and** 至少有一個就緒的範本。客戶訂單表單僅列出已就緒的區域。

## 驗證 {#verify}

1. 該區域在列表中顯示為 **On**，並帶有正確的國旗。
2. 其詳細資料頁面會顯示您預期的後端或 VPN 範圍。
3. 針對 VM：**not ready to sell VMs** 標籤已消失。在客戶入口網站中，開始建立訂單並檢查是否提供該區域。

## 限制與注意事項 {#limits-and-notes}

- 在此 NexCMP 版本中，客戶在 **default zone** (zone 1) 中訂購虛擬機器。其他區域則用於 VPN、IPv6 Proxy 與 Object Storage，或在基礎設施就緒前預備位置；區域列表下方的備註也說明瞭這點。
- 只有在沒有附加任何項目時才能刪除區域：無後端、VM、方案或 VPN 範圍。預設區域無法刪除；請先將其他區域設為預設。
- 經銷商擁有的區域僅能由您開啟或關閉以及隱藏或顯示；其其他欄位皆會被鎖定。
- 短代號是內部參考的一部分。請設定一次後不再更改。

## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| 「區域名稱必填」/「請選擇國家」/「請至少選擇 1 項服務」 | 必填欄位為空 | 填寫名稱、選擇國家並勾選一項服務。 |
| 「無效的代稱（a-z 0-9 -，2-32 個字元）」 | 短代號包含其他字元或長度不正確 | 僅能使用小寫字母、數字及連字號。 |
| 標籤 "not ready to sell VMs" | 該區域中沒有作用中的可銷售後端、沒有方案或沒有準備就緒的範本 | 附加基礎設施，然後新增方案與範本。請參閱 [Plans](https://nexcmp.com/zh-tw/docs/catalog/plans/) 與 [Templates](https://nexcmp.com/zh-tw/docs/infrastructure/templates/)。 |
| 刪除按鈕因「仍有關聯」而停用 | 該區域包含後端、虛擬機器、方案或 VPN 範圍 | 請先移除或移動它們。 |
| 刪除按鈕因「預設區域」而停用 | 此區域為預設區域 | 請將其他區域設為預設。 |
| 客戶無法看到該區域 | 它處於隱藏、停用狀態，或未勾選任何服務 | 將「Visibility」設為「Public」、「Active」設為「On」並勾選該服務。 |
| 後端表單中缺少 S3 區域 | 該區域未勾選 S3 服務 | 編輯該區域並勾選 **Object Storage (S3)**。 |




---

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

# CloudStack

> **Where in the admin:** Infrastructure › Cloud provider › CloudStack › API connection (`/infra/cloudstack?tab=connect`)。首次連線亦可在 [setup wizard](https://nexcmp.com/zh-tw/docs/getting-started/setup-wizard/) 的步驟 2 進行。

## 功能 {#what-it-does}

NexCMP 銷售執行於您的 Apache CloudStack 雲端上的虛擬機器。它透過 CloudStack API 部署、啟動、停止、調整大小、快照及刪除虛擬機器，從區域分派公用 IP 位址，讀取計費與頻寬使用量，並在管理主控台中顯示容量與健康狀態。CloudStack 保持作為hypervisor的真實資料來源；NexCMP 則是其上的店面、計費與入口網站。

當 CloudStack 是（或將成為）您的主要 VM 來源時，請使用此頁面。若要設定次要來源，請參閱 [Proxmox VE](https://nexcmp.com/zh-tw/docs/infrastructure/proxmox/)。

## 需求 {#requirements}

| 項目 | 需求 |
|---|---|
| CloudStack 版本 | 4.23 為經過測試的發行版本。VM 主控台需要 4.18 或更新版本，而執行中 VM 的 CPU/RAM 即時調整大小則需要搭配 KVM 的 4.23 版本。 |
| 區域類型 | 包含至少一個供客戶 VM 使用的客端網路以及擁有可用位址之公用 IP 範圍的區域。 |
| Hypervisor | KVM 為經過測試的 hypervisor。 |
| 帳號 | 為 NexCMP 建立的**專屬網域與帳號**。切勿使用 ROOT 管理員金鑰。 |
| API 連線能力 | 面板伺服器必須能夠透過 HTTP(S) 存取管理伺服器 API URL (`https://cloudstack.example.com/client/api`)。VM 主控台、頻寬與 Kubernetes 功能皆使用相同的端點。 |
| 選用的唯讀金鑰 | 第二組唯讀金鑰可讓管理主控台顯示主機、儲存、系統 VM 與公用 IP 範圍。銷售 VM 時不需要此項。 |
| 公用 IP | 區域中的可用公用 IPv4 位址。NexCMP 可銷售的前綴可在 Sales IP pools 下進行設定。 |
| 範本 | 至少一個就緒、啟用密碼的範本，以及您的帳戶能看見的一個服務方案。請參閱 [Templates](https://nexcmp.com/zh-tw/docs/infrastructure/templates/)。 |
| 儲存 | 帳戶磁碟區的主要儲存空間，如果您銷售快照或映像，則需次要儲存空間。 |
| 相依於 | 無。Kubernetes、私有雲、映像和頻寬皆依賴此頁面。 |

::: 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**（建議） | 完整功能集：虛擬機器、網路、Kubernetes 專案、VPC、映像。其權限範圍止於 `nexcmp` 網域。 |
   | 使用者 | 僅限虛擬機器生命週期。一般使用者無法刪除虛擬機器，除非全域設定 `allow.user.expunge.recover.vm` 為 true；隨後 NexCMP 會停止虛擬機器，而 CloudStack 會在 `expunge.delay` 後將其永久刪除。 |

3. 建立帳戶及其第一個使用者。請使用長而隨機的密碼；該密碼日後不會再輸入。

   ```bash
   cmk create account name=nexcmp-api username=nexcmp-api \
     password='CHANGE-ME-LONG-RANDOM' email=ops@example.com \
     firstname=NexCMP lastname=API roleid=<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 會將其加密儲存，之後僅顯示最後四個字元。

5. 請確保該網域沒有嚴格的資源限制（實例、磁碟區、公用 IP、網路、快照、範本、專案）。

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

### 為客戶虛擬機器建立客體網路 {#create-the-guest-network-for-customer-vms}

客戶虛擬機器會部署至屬於該新帳戶的單一客體網路中。具有虛擬路由器 (VR) 以及靜態 NAT、防火牆和連接埠轉送服務的隔離網路運作良好，因為 NexCMP 會透過靜態 NAT 將公用 IP 附加至每個虛擬機器。

```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>
```

檢查方案的預設對外傳輸政策：若為「deny」，則在新增防火牆對外傳輸規則之前，客戶虛擬機器將無法進行對外連線。

### 讓方案與範本可見 {#make-offerings-and-templates-visible}

- **服務方案**與**網路方案**必須設為公開或指派至 `nexcmp` 網域，否則帳戶將無法列出或使用它們。
- 註冊或共用至少一個範本（請參閱 [Templates](https://nexcmp.com/zh-tw/docs/infrastructure/templates/)）。NexCMP 會列出就緒且設為精選的範本。

### 選用：用於基礎設施頁面的唯讀金鑰 {#optional-read-only-key-for-infrastructure-pages}

頁籤 **Capacity**、**Host**、**Storage** 與 **System VM** 以及公用 IP 範圍清單會使用第二把金鑰，該金鑰只需要對六個指令擁有讀取權限。請建立受限制的角色，而不要重複使用完整的管理員金鑰：

```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 網域中，因為它會讀取全區域資料），如步驟 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/zh-tw/docs/getting-started/setup-wizard/)的步驟 2 會要求輸入相同的數值。**Test connection** 會列出金鑰能看到的區域與網路；請選擇區域與訪客網路、區域的顯示名稱與國家，然後按一下 **Save CloudStack**。若網路不在該區域或金鑰無法存取，精靈將會拒絕。

![填入 CloudStack API URL 與金鑰，並在 Test connection 後選擇區域與網路的精靈步驟 2](https://nexcmp.com/zh-tw/docs/images/infrastructure/cloudstack-01-wizard-step.webp)

### 稍後在管理主控台中 {#later-in-the-admin-console}

1. 開啟 **Infrastructure › Cloud provider › CloudStack** 並選擇 **API connection** 標籤頁。
2. 填寫 **Connection** 卡片：

   | 欄位 | 範例值 |
   |---|---|
   | Endpoint API | `https://cloudstack.example.com/client/api` |
   | API金鑰（寫入權限） | `XXXX`（留空則保留已儲存的金鑰） |
   | Secret key | `XXXX` |
   | RO API金鑰 / RO秘密金鑰 | 選擇性，來自唯讀帳號 |
   | Zone ID | 您的區域 UUID |

      ![帶有範例端點與遮罩金鑰的 API connection 標籤頁](https://nexcmp.com/zh-tw/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** 以設定預設訪客網路、自訂方案以及新虛擬機器的預設金鑰對。

      ![具有預設網路 ID 的 VM Policy、Provisioning 標籤頁](https://nexcmp.com/zh-tw/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/zh-tw/docs/images/infrastructure/cloudstack-05-sales-ip-pool.webp)

### NexCMP 讀取與寫入的內容 {#what-nexcmp-reads-and-writes}

| 區域 | 讀取 | 變更 |
|---|---|---|
| VMs | 清單、狀態、使用歷史記錄、主控台端點 | 部署、啟動、停止、重新開機、重新安裝、銷毀、調整大小、重設密碼與 SSH key |
| 磁碟與快照 | 儲存卷、虛擬機器快照、備份 | 建立、掛載、卸載、調整大小、刪除、快照、還原 |
| 網路 | 網路、路由器、公用 IP、防火牆、連接埠轉發、負載平衡器規則 | 關聯與釋放公用 IP、靜態 NAT、防火牆、連接埠轉發、出口規則、私有雲網路與 ACL |
| 目錄 | 服務、磁碟與網路方案、範本、ISO、作業系統類型 | 註冊與刪除範本和 ISO（映像檔）、建立自訂方案時的服務方案 |
| Kubernetes | 支援的版本、叢集、組態 | 專案、資源限制、網路、叢集（Kubernetes 模組） |
| 唯讀金鑰 | 主機、叢集、儲存池、系統虛擬機器、容量、VLAN IP範圍 | 無 |

### 即時CPU與RAM以及頻寬 {#live-cpu-and-ram-and-bandwidth}

- **熱插拔。** 執行中的虛擬機器只有在模板允許（動態可擴展）且客體作業系統將新CPU與RAM上線時，才能在不重新啟動的情況下調整大小。當模板名稱以`vN`結尾且N大於或等於6，或當您在模板的**vCPU/RAM hot-plug**欄位中手動設定時，NexCMP會啟用Auto Scaling。請參閱[Templates](https://nexcmp.com/zh-tw/docs/infrastructure/templates/)。
- **頻寬來源。** 在預設設定下，NexCMP會從CloudStack虛擬機器統計資料中測量流量（`listVirtualMachinesUsageHistory`，每5分鐘輪詢一次並按虛擬機器網路介面加總）。這些數據包含虛擬機器之間的流量，因此可能會比邊界路由器計算的數值稍高。請保持啟用CloudStack虛擬機器統計資料收集功能；長於統計資料保留時間的間隔將被略過。請參閱[Bandwidth](https://nexcmp.com/zh-tw/docs/catalog/bandwidth/)。

## 驗證 {#verify}

1. **Test connection**傳回「Write key: OK」以及您的區域與CloudStack版本。
2. **Infrastructure › Cloud provider › Providers**顯示該提供者為啟用狀態且有最近的測試時間。儀表板健康狀態面板不再顯示「CloudStack: not connected」。
3. **Sales IP pools**會列出可用位址（大約每分鐘重新整理一次）。
4. 從客戶入口網站或管理員主控台訂購小型虛擬機器，並檢查其是否達到Running狀態、擁有公用IP以及您是否能夠開啟主控台。

## 限制與注意事項 {#limits-and-notes}

- 此版本的NexCMP僅能連線一個CloudStack叢集。**Add cloud provider**對話方塊可以測試第二個叢集的金鑰，但無法儲存。
- 一個CloudStack區域附加至NexCMP的預設區域；具有多個區域的CloudStack會限定於您輸入的區域，因此其他區域的虛擬機器、IP與網路將被忽略。
- 在CloudStack中刪除客體網路會導致每個新部署失敗。當網路消失時，管理員主控台會顯示紅色通知。
- 憑證絕不會離開伺服器。API僅傳回最後四個字元。

## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| `listCapabilities: cloudstack 401: unable to verify user credentials and/or request signature` | API金鑰或密鑰錯誤、來自其他使用者的金鑰，或面板伺服器上的時鐘問題 | 使用`cmk generate userkeys`重新產生金鑰並貼上兩者。檢查面板伺服器時間。 |
| 測試：`listZones: …`或逾時 | 面板伺服器無法連線至API URL | 檢查DNS、防火牆與確切的`/client/api`路徑。 |
| 精靈：「在該區域中找不到此API金鑰的網路」 | 所選網路屬於其他帳戶或區域 | 在專用帳戶中建立網路（見上方）並再次執行**Test connection**。 |
| 精靈：「挑選區域與網路」 | 未執行測試，或未選取區域或網路 | 按一下**Test connection**並選擇這兩個清單。 |
| 橫幅「CloudStack key not configured」 | 尚未儲存金鑰（「Connect later」） | 填寫連線卡片、**Save connection**，然後**Test connection**。 |
| 橫幅「CloudStack connection is OFF」 | **Enable CloudStack connection**開關已關閉 | 將其切換為開並儲存。 |
| 唯讀金鑰：測試中出現「unusable …」 | 缺少角色權限或帳戶錯誤 | 檢查六個允許的指令以及帳戶是否位於ROOT網域中。 |
| 「Zone public IP ranges not measured yet」或「no public IP ranges declared」 | 沒有唯讀金鑰，或該區域確實沒有公用範圍 | 新增唯讀金鑰，或在 CloudStack 中新增公開 IP 範圍。 |
| "集Pool為空——等待60秒進行vmd同步" | Worker 每分鐘會重新整理一次 IP 清單 | 等待一分鐘後重新載入。 |
| "範圍203.0.113.中的免費IP已耗盡" | 可銷售的前綴中的所有位址均已被佔用 | 將位址新增至區域、擴大前綴或釋放未使用的 IP。 |
| "無法取得網路資料（CloudStack無回應或金鑰權限不足）" | 金鑰失去存取權限，或者 CloudStack 離線 | 執行 **Test connection**；檢查帳戶是否已啟用。 |
| "訪客網路不存在" | 該網路已在 CloudStack 中刪除 | 重新建立網路並在 Provisioning 下將其設為預設值。 |




---

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

# Proxmox VE

> **管理員位置：**Infrastructure › Cloud provider › Providers（`/infra/providers`），然後是提供者頁面（`/infra/providers/<id>`），其中包含Overview、Clusters、VMs、Servers和Credentials分頁。方案設定於Services › Virtual Machines › Plans & pricing（`/vm/catalog`）。

## 功能 {#what-it-does}

NexCMP 可以銷售執行於一個或多個 Proxmox VE 叢集上的虛擬機器，作為 CloudStack 的替代方案或補充。虛擬機器是透過完整複製 OS 範本來建立的，然後透過 cloud-init 進行設定：大小、來自您定義的池中的 IP 位址、root 密碼與 SSH key。客戶可在入口網站中進行電源控制、主控台、快照、重新安裝、密碼重設與指標查看。他們永遠不會看到叢集、節點或來源名稱。

當您已經執行 Proxmox VE，或是想要提供第二個不同定價的 VM 池時請使用它。

## 需求 {#requirements}

| 項目 | 需求 |
|---|---|
| Proxmox VE | PVE 9.x。此整合已在 9.2 版本上驗證。它需要 `import` 儲存空間內容與 `import-from` 磁碟選項（PVE 8.2 或更新版本）。 |
| 來自面板的網路 | HTTPS 連線至叢集 API，`https://<host or IP>:8006`。無路徑、使用者名稱或查詢字串。面板和 worker 皆會連線；瀏覽器主控台會透過面板進行代理。 |
| 帳號 | 具有 **API token** 的專用 PVE 使用者，並搭配具有下列權限的自訂角色。切勿使用 `root@pam`。 |
| 儲存 | 支援複製（例如 `local-lvm`）的 VM 磁碟儲存空間。對於內建範本建立器，儲存空間名稱為 `local`，其內容類型包含 `import` 與 `snippets`。 |
| 網路 | 可連線至客戶 IP 所在網路的 Linux 橋接器（例如 `vmbr0`）。若您輸入 VLAN 標籤，請使用支援 VLAN 的橋接器。 |
| IP | 路由至該橋接器的 IPv4 區塊（/16 至 /30），並附帶閘道。NexCMP 會自行指派位址；Proxmox 沒有 IP 管理功能。 |
| 範本 | 每個您要部署的節點上，每種作業系統需要一個 cloud-init 範本 VM，並安裝 QEMU guest agent。 |
| 區域 | 用於附加叢集的現有區域。請參閱 [Zones](https://nexcmp.com/zh-tw/docs/infrastructure/zones/)。 |
| 相依於 | 無。 |

## 準備基礎設施 {#prepare-the-infrastructure}

在任何叢集節點上以 root 身分執行指令。

### 1. 建立最小權限角色、使用者與 API token {#_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. 建立使用者與 token。`--privsep 1` 意指 token 的權限為使用者自身權限與 token 自身權限的**交集**。

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

   此指令會印出 **secret once**（一個 UUID）這個 token。請立即複製。token 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 文件代表 token 正常運作。（`-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
```

- 客戶虛擬機器將在你在 NexCMP 中輸入的網橋上取得 `virtio` 個網路介面。若你設定了 VLAN，該網橋必須支援 VLAN。
- 將客戶虛擬機器放在**與節點管理位址分開的**網橋或 VLAN 上。若它們共用網路，Proxmox 防火牆的自動管理 IP 集合會將節點的連接埠 22、8006、3128、5900-5999 與 60000-60050 開放給該網路中的每一個虛擬機器。若無法將它們分開，請在管理 ACCEPT 規則上方，為虛擬機器子網新增針對這些連接埠的明確 DROP 規則。

### 3. 儲存空間注意事項 (LVM-thin) {#_3-storage-notes-lvm-thin}

- 將 thin-pool **zeroing 保持預設值**。將其關閉（`lvchange -Zn`）可能會在新配置的區塊中殘留舊資料，並損毀已複製虛擬機器的分割表或檔案系統。
- 回報「write cache: disabled」的硬碟只能以每秒幾 MB 的速度複製。請使用 `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. 從雲端映像檔建構作業系統範本 {#_5-build-an-os-template-from-a-cloud-image}

範本是供 NexCMP 進行複製的 cloud-init 虛擬機器。每個範本都會以簡短的 **OS key**（例如 `ubuntu-24.04`）及其 VM id 進行註冊。**在每個將接收虛擬機器的節點上**建立一個作業系統範本，因為複製作業會在所選的節點上執行。

**選項 A，建議做法：自行建構。** 標準的 Ubuntu 與 Debian 雲端映像檔不包含客體代理程式，也不允許 root 登入，而 NexCMP 是透過 cloud-init 設定 root 密碼。請先準備映像檔：

```bash
apt install -y libguestfs-tools
wget -O noble.qcow2 https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img
virt-customize -a noble.qcow2 --install qemu-guest-agent \
  --write /etc/cloud/cloud.cfg.d/99-nexcmp.cfg:$'ssh_pwauth: true\ndisable_root: false\n' \
  --write /etc/ssh/sshd_config.d/00-nexcmp.conf:$'PermitRootLogin yes\nPasswordAuthentication yes\n'
```

然後建立範本虛擬機器（id 9000 為範例；請將範本 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 與客體代理程式旗標建立虛擬機器，但不會改變映像檔內部的內容。請僅在映像檔已經允許 root 登入並執行客體代理程式時使用，或者在你同時提供 cloud-init vendor-data 程式碼片段時使用。


客體代理程式是 **Reset password** 以及顯示虛擬機器 IP 位址所需的元件。

### 6. 了解憑證指紋（選填） {#_6-know-the-certificate-fingerprint-optional}

NexCMP 透過釘選其 TLS 憑證的 SHA-256 指紋來信任叢集，因此自簽憑證即可適用。若要查看 NexCMP 將會釘選的值：

```bash
openssl x509 -in /etc/pve/local/pve-ssl.pem -noout -fingerprint -sha256
```

## 在 NexCMP 中連線 {#connect-in-nexcmp}

1. 開啟 **Infrastructure › Cloud provider › Providers** 並點擊 **Add cloud provider**。選擇 **Proxmox VE** 並填入：

   | 欄位 | 範例值 |
   |---|---|
   | Name | `Proxmox cluster 1` |
   | Endpoint | `https://192.0.2.10:8006` |
   | Token id | `nexcmp@pve!api` |
   | Token secret | `XXXX`（步驟 1 中印出的 UUID） |
   | Slug | `pve-1`（a-z、0-9、連字號，2-32 個字元） |
   | Default node | `pve1`（留空：擁有最多剩餘 RAM 的線上節點） |
   | 儲存 | `local-lvm` |
   | Bridge | `vmbr0` |

      ![已選取 Proxmox VE 並帶有範例端點、權杖與儲存空間值的新增雲端提供者對話方塊](https://nexcmp.com/zh-tw/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 | 用於新虛擬機器的節點。留空代表擁有最多剩餘 RAM 的線上節點。 |
   | Storage, Bridge, VLAN | 磁碟儲存空間、NIC 橋接器與選用的 VLAN 標籤（0 代表無）。 |
   | CPU type | 預設為 `host`。當節點具備不同 CPU 世代時請使用 `x86-64-v2-AES`。 |
   | vmid from | 指派給客戶虛擬機器的第一個 VM ID（預設為 1000）。 |
   | Storage ISO, Storage backup | 除非您要使用，否則請保持空白；留空表示不提供 ISO 與備份功能。 |
   | Template OS | 每行一個，`os-key=vmid`，例如 `ubuntu-24.04=9000`。 |
   | Pinned TLS fingerprint (SHA-256) | 由第一次測試填入。更換叢集憑證後，請清除它並再次測試。 |

      ![Clusters 分頁，包含範例節點、儲存空間、橋接器與作業系統範本清單的叢集組態卡片](https://nexcmp.com/zh-tw/docs/images/infrastructure/proxmox-03-cluster-config.webp)

5. 選填：如果您使用上述選項 B，請填寫 **Create OS template from cloud image**（作業系統金鑰 `ubuntu-24.04`、vmid `9000`、節點 `pve1`、qcow2 映像檔 URL），然後按一下 **Create template**。它會在背景執行數分鐘；結果可在稽核記錄中檢視。

      ![包含範例 Ubuntu 映像檔 URL 的「從雲端映像檔建立作業系統範本」卡片](https://nexcmp.com/zh-tw/docs/images/infrastructure/proxmox-04-template-from-image.webp)

6. 點擊 **Add pool**（位於 **Cluster IP pool**），並建立供虛擬機器取得位址的集區：

   | 欄位 | 範例值 |
   |---|---|
   | Name | `customers-1` |
   | CIDR | `198.51.100.0/24` |
   | Gateway | `198.51.100.1`（絕不指派給虛擬機器） |
   | 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/zh-tw/docs/images/infrastructure/proxmox-05-ip-pool.webp)

7. 在 **Attach cluster to zone** 中，選擇區域並可選擇性填入節點名稱，然後按一下 **Attach to zone**。此叢集將加入已在販售虛擬機器的區域，因此單一區域可同時擁有 CloudStack 與 Proxmox。新來源**預設不會販售**，且不會改變現有方案的運作方式。

      ![已選取現有區域的將叢集附加至區域卡片](https://nexcmp.com/zh-tw/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 無法縮小磁碟。


### 匯入已存在的虛擬機器 {#import-a-vm-that-already-exists}

開啟 **Servers** 分頁以列出叢集上的虛擬機器。**Import** 會免費將現有虛擬機器指派給客戶帳戶：時數、關機時間或流量均不收費。客戶可以啟動、停止、重新開機並開啟主控台，但無法刪除，只有管理員可以。NexCMP 在匯入時僅從叢集讀取。

- 叢集必須附加至具備該虛擬機器**節點名稱**的區域（若將節點留空，匯入時會回報未設定區域）。
- 若要將虛擬機器設為**受保護**狀態（將拒絕停止、重新開機、重新安裝、快照還原、銷毀與方案變更），請透過命令列進行匯入：`--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 大小、擴充磁碟 | 可以，但虛擬機器會先停止、變更後再啟動（不支援線上調整大小） |
| Snapshots | 可以，每個虛擬機器最多 5 個：建立、列出、還原、刪除 |
| 重新安裝 | 可以：虛擬機器將根據範本重建，並保留其 ID、IP 與設定，同時產生新密碼 |
| 重設密碼 | 可以，透過客體代理程式 |
| 主控台 | 可以，透過面板代理的瀏覽器主控台 |
| 度量指標 | 可以：CPU、記憶體、網路與磁碟 |
| ISO 掛載、備份、防火牆、IPv6、通訊埠轉送、變更 IP、額外儲存卷、Auto Scaling、DDoS Shield、VPC、頻寬計量 | 無法使用。客戶虛擬機器頁面會隱藏來源不支援的功能。 |

## 驗證 {#verify}

1. **Test connection** 顯示正常，且提供者狀態為啟用。
2. **Clusters** 列出您的節點為線上狀態，並顯示儲存空間與橋接器。
3. **Cluster IP pool** 顯示可用、已使用與保留的數量。
4. 附加叢集後，OS 金鑰會顯示在 **Services › Virtual Machines › Template** 的區域範本下方。
5. 從使用該叢集的方案訂購測試虛擬機器。它應該會從集區取得位址、root 密碼與正常運作的主控台；集區會顯示一個已使用的位址。

## 限制與注意事項 {#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**，然後再撤銷舊金鑰。
- 測試、同步與叢集資訊動作每個管理員每分鐘限制呼叫六次。
- NexCMP 負責向您的客戶收費；叢集的硬體與授權成本由您負擔。


## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| 測試：「金鑰遭到拒絕（存取金鑰/密鑰錯誤或已被撤銷）」或 HTTP 401/403 | 權杖 ID 或密鑰錯誤，或 ACL 僅授予該權杖 | 重新執行兩個 `pveum acl modify` 指令（使用者 **and** token）並檢查 token id 是否為 `user@realm!tokenid`。 |
| 測試：「Could not connect to the provider」或「Timed out」 | 防火牆、主機或連接埠錯誤 | 從面板伺服器檢查 `https://host:8006`。 |
| 測試：「Invalid endpoint or not on the allowlist」 | 端點包含路徑、使用者、查詢參數，或並非 HTTPS | 請確切使用 `https://host:8006`。 |
| 「叢集 TLS憑證與釘選的憑證指紋不符」 | 叢集憑證已被更換 | 清除 Clusters 標籤頁上的 **Pinned TLS fingerprint**，儲存後再次執行 **Test connection**。 |
| 代稱（Slug）被拒絕 | 非 a-z、0-9、連字號，或長度不在 2-32 個字元之間 | 請使用類似 `pve-1` 的格式。 |
| 「Token id格式：user@realm!tokenid，且需要secret」 | 缺少 token id 或密鑰 | 請兩者皆填；密鑰是建立 token 時所列印出的 UUID。 |
| 「無效的範本行：…」 | **Template OS** 中的某行並非 `key=vmid` | 在鍵中使用字母、數字、`.`、`_`、`-`，且 vmid 至少為 100。 |
| 「OS key：a-z 0-9 . _ - 且 vmid ≥ 100」 | **Create template** 中的鍵或 id 無效 | 修正 OS 鍵並使用未被佔用的 vmid。 |
| 建立範本時出現「vmid … already exists」 | vmid 已被佔用 | 請選擇其他 id。 |
| 「url指向內部位址」 | 映像檔 URL 為內部 IP | 請使用公開 URL；名稱會由 Proxmox 解析。 |
| 範本任務在下載時失敗 | 儲存空間 `local` 沒有 `import` 內容 | `pvesm set local --content …,import,snippets`，然後重試。檔名必須以 `.qcow2`、`.raw`、`.vmdk`、`.ova` 或 `.ovf` 結尾。 |
| 「cluster has no online nodes」或「node … is not online」 | 預設節點已離線或拼寫錯誤 | 修正 **Default node** 或保持空白。 |
| 「映像檔不屬於此叢集」 | 方案的 OS 不在 **Template OS** 中 | 將該鍵新增至列表並儲存。 |
| 部署等待中，隨後在複製時失敗 | 範本虛擬機器不在所選節點上 | 在該節點上建立範本，或將 **Default node** 設定為擁有該範本的節點。 |
| 客戶無法以 root 登入 | 映像檔阻擋了 root 登入 | 依照選項 A 重新建構範本。 |
| 重設密碼沒有任何作用 | 客體作業系統中沒有 guest agent | 在範本中安裝並啟用 `qemu-guest-agent`。 |
| 「名稱、CIDR 與閘道器為必填」 | 缺少 pool 欄位 | 請填寫全部三個。 |
| Pool create: "overlaps with pool …", "gateway must be within range (not network/broadcast address)" 或 "cidr: network address must be …" | 重疊的 pool、錯誤的 gateway，或不在網路邊界的 CIDR | 使用未使用的範圍、其中的 gateway 以及寫成網路位址的 CIDR（例如 `198.51.100.0/24`）。 |
| 匯入："region is not set up" | 附加叢集時未包含 VM 的節點名稱 | 將包含節點名稱的叢集附加至區域。 |


---

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

# 作業系統範本與 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 叢集所列出的內容，並讓您選擇要銷售哪些項目，同時提供對客端名稱、圖示與登入使用者。本頁面說明如何準備能與 NexCMP 搭配良好的映像檔：密碼登入、即時 CPU 與 RAM 調整大小、置換檔案（swap file），以及會擴展至方案大小的根磁碟。

## 需求 {#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 機器即可。 |
| 網頁伺服器 | 任何 CloudStack 次要儲存空間 VM 可以存取的 HTTP(S) 伺服器，用於發布完成的 `.qcow2` 檔案。它不需要從網際網路存取。 |
| CloudStack | 可註冊範本的帳戶，以及您的區域 ID 和相應的 OS 類型 ID。請參閱 [CloudStack](https://nexcmp.com/zh-tw/docs/infrastructure/cloudstack/)。 |
| Proxmox VE | 搭配 QEMU 訪客代理程式的 Cloud-init 範本 VM，每個 OS 與每個節點一個。請參閱 [Proxmox VE](https://nexcmp.com/zh-tw/docs/infrastructure/proxmox/)。 |
| 相依於 | 需先連線 [CloudStack](https://nexcmp.com/zh-tw/docs/infrastructure/cloudstack/) 或 [Proxmox VE](https://nexcmp.com/zh-tw/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 可以向虛擬機器詢問 CPU 與 IP 資訊，並為快照將其靜止化。 |
| 具備 CloudStack 資料來源的 cloud-init、每次開機時的 `set_passwords`、SSH 密碼登入 | 產生的密碼從虛擬路由器取得，且 **Reset password** 可以正常運作。 |
| 用於動態新增 CPU 與 RAM 的 udev 規則 | 動態新增的 vCPU 與 RAM 會自動上線，因此即時調整大小與 Auto Scaling 能夠運作。 |
| 交換檔服務 | 在磁碟擴充後，建立 `/swapfile` 相當於 RAM 的 50% 與 4 GiB 中較小者。`touch /etc/cmp-swap.disabled` 可將其關閉。 |
| cloud-init `growpart` 與 `resizefs` | 小型的根磁碟會在首次開機時自動擴充至方案的磁碟大小。 |
| 空的 machine-id，無 SSH 主機金鑰 | 每個虛擬機器都會取得其專屬識別身分。 |

::: warning 將範本命名為 `<OS> <version> <vN>`
對於名稱結尾為 `vN` 或 `vN.M` 且 **N 為 6 或以上**（`Ubuntu 24.04 v7`、`Rocky Linux 9 v7.1`）的範本，NexCMP 會開啟 **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 產生虛擬機器密碼。
   - `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}

在我部署的每個節點上為每個作業系統建立一個 cloud-init 虛擬機器範本，並安裝 guest agent 並啟用 root 登入，然後將其註冊為 `os-key=vmid`。完整的指令位於 [Proxmox VE](https://nexcmp.com/zh-tw/docs/infrastructure/proxmox/) 中。上面的 CloudStack 產生器**不**適用於 Proxmox：它為 CloudStack 資料來源設定 cloud-init。

### ISOs {#isos}

客戶透過 **Images** 模組（CloudStack）或「獨立伺服器」模組掛載自己的 ISO。這些與本頁面上的作業系統範本是分開的。請參閱 [Modules](https://nexcmp.com/zh-tw/docs/infrastructure/modules/) 與 [Dedicated servers](https://nexcmp.com/zh-tw/docs/infrastructure/dedicated/)。

## 在 NexCMP 中連線 {#connect-in-nexcmp}

1. 前往**Services › Virtual Machines › Template**。點擊**Sync now**或等待最多 15 分鐘。同步功能會加入已就緒且在 CloudStack 中標記為精選的範本。

      ![顯示已同步範本及其就緒狀態與 CPU 熱插拔欄位的範本頁面](https://nexcmp.com/zh-tw/docs/images/infrastructure/templates-01-list.webp)

2. 點擊新範本上的 **Edit** 並設定客戶看到的內容：

   | 欄位 | 範例值 |
   |---|---|
   | 對客戶顯示的名稱 | `Ubuntu 24.04 LTS` |
   | OS family | `ubuntu`（圖示與預設使用者） |
   | Version | `24.04` |
   | Login username | `ubuntu`（Windows：`Administrator`；其他：`root`） |
   | Icon | 映像檔URL、路徑或名稱 |
   | 順序 | `10` |
   | 啟用 | 開啟 |
   | vCPU/RAM熱插拔（線上調整規格） | **Auto by name (v6 or later)**、**Yes** 或 **No (needs a restart)** |

      ![編輯範本對話方塊，包含客戶端名稱、作業系統家族、登入使用者與熱插拔選項](https://nexcmp.com/zh-tw/docs/images/infrastructure/templates-02-edit.webp)

3. 啟用範本。CloudStack 不再列出的範本會自動隱藏（如果已設定，您將會在 Telegram 中收到警報）；它永遠不會從 NexCMP 中刪除。

### 將範本替換為較新的建置版本 {#replace-a-template-with-a-newer-build}

對已販售的範本使用 **More › Replace with new version**。挑選新的、就緒且目前停用的範本。該販售項目隨即指向新建置版本並保留其名稱、順序與圖示；舊版本會被停用作為退回途徑（若要返回，請對新項目使用 **Replace**）。執行中的虛擬機器不會受到影響。若新建置版本屬於不同的作業系統家族，請先勾選確認。

## 驗證 {#verify}

1. 該列顯示 **ready**，對於名稱以 `vN` 結尾且 N 為 6 或以上的建置版本，則顯示 **CPU hot-plug: supported**。
2. 從該範本部署一臺測試虛擬機器並在虛擬機器內部檢查：
   - 您可以使用門戶中顯示的密碼登入；
   - `df -h /` 顯示方案的磁碟大小；
   - 在線上調整規模（執行不需重開機的 **Change plan**）後，`nproc` 與 `free -m` 會增長；
   - `swapon --show` 列出 `/swapfile`（可用空間小於置換空間加 2 GiB 的磁碟會被略過）；
   - `systemctl is-active qemu-guest-agent` 印出 `active`。
3. 如果您將代理程式打包進去，虛擬機器會在首次開機一分鐘後出現在面板的監控主機中。該虛擬機器需要專屬的公開 IP：面板透過其公開來源 IP 來識別它。

## 限制與注意事項 {#limits-and-notes}

- 建置工具僅限 Linux 且用於建置 Linux 映像檔。其他映像檔（例如 Windows）可透過其他方式在 CloudStack 中註冊；NexCMP 會列出 CloudStack回報的內容。
- 僅隨附 amd64 代理程式；其他架構會略過代理程式安裝。
- 映像檔會透過 `guestfish` 進行檢查，但建置工具絕不會開機它。在販售新映像檔之前，務必先部署一臺測試虛擬機器。
- 在首次開機前使用 `touch /etc/cmp-agent.disabled` 在一臺虛擬機器上略過代理程式。稍後使用 `systemctl disable --now cmp-agent cmp-agent-install; rm -rf /etc/cmp-agent /usr/local/bin/cmp-agent` 將其移除，然後在管理員主控台中刪除該代理程式。

## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| `virt-customize` 下載套件失敗 | 建置機器沒有對外網路 | 修正該機器上的 DNS 或代理伺服器，或在已具備這些套件的基礎映像檔上使用 `--offline` 進行建置。 |
| `libguestfs: error: /usr/bin/supermin exited with error status 1` | 主機核心無法被目前的使用者讀取（Ubuntu） | `sudo chmod +r /boot/vmlinuz*`，或以 root 身分執行建置。 |
| 檢查碼不同，或者供應商映像檔已不存在 | 供應商移動了他們的「最新」檔案 | 請自行下載映像檔，對照供應商的檢查碼檔案進行檢查，並透過 `--base` 傳遞。 |
| Rocky：較新的 XFS 無法掛載 | 主機核心過舊 | 在具有較新核心的機器上建置。 |
| `--version must be v6 or higher` | 名稱必須是 `vN` 且 N 為 6 或以上 | 使用 `--version v7`。 |
| `--panel-url must be a plain https:// URL` | 代理程式是以 root 身分下載並執行，因此拒絕純 HTTP | 使用不含空格、引號或查詢字串的 `https://` URL。 |
| 範本保持 **not ready** 狀態 | CloudStack 尚未完成下載 | 等待 **Download Complete**，檢查次要儲存虛擬機器是否能連線至該 URL。 |
| 該列顯示 **no-pass** | 註冊範本時未帶入 `passwordenabled=true` | 使用該旗標再次註冊。 |
| CPU 熱插拔顯示 **unsupported** | 名稱未以 `vN` 結尾（N 為 6 或以上） | 重新命名範本，若映像檔具備 udev 規則，則可在編輯中將 **vCPU/RAM hot-plug** 設定為 **Yes**。 |
| 首次連線後出現「Empty template list」 | 同步尚未執行 | 點擊 **Sync now**（需要背景工作程序執行中）或等待 15 分鐘的循環週期。 |


---

<!-- source: https://nexcmp.com/zh-tw/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 **直接透過 iDRAC** 經由 Redfish API 管理實體伺服器。客戶租用整台伺服器：他們可以開關機、開啟瀏覽器主控台、掛載 ISO 或從範本安裝作業系統，並檢視硬體與計量數據。他們永遠不會看到 iDRAC 位址、使用者名稱或密碼。

用它來轉售來自您自己機櫃的專屬伺服器。

## 需求 {#requirements}

| 項目 | 需求 |
|---|---|
| 硬體 | 具備 **iDRAC 9** 與 Redfish API 的 Dell 伺服器。 |
| 管理網路 | **由您自行提供。**面板伺服器必須能夠透過**HTTPS 443**連線至每台iDRAC（以及供主控台使用的iDRAC VNC連接埠，預設為**5901**），且每台iDRAC都必須能夠連線至下方的ISO網頁伺服器。iDRAC位址必須是您在設定`dedicated_bmc_cidrs`中所列出的**私人範圍IPv4位址**（RFC 1918，/16或更小的前綴）。系統不接受DNS名稱與IPv6。NexCMP不會建立此網路，也無法為您進行測試。 |
| iDRAC 帳號 | 每台iDRAC上需有一個具備**Administrator**權限的帳號。NexCMP會使用此帳號讀取伺服器資訊，並傳送其允許執行的少數指令（電源、虛擬媒體、單次開機、主控台）。NexCMP絕不會為您的客戶建立iDRAC帳號。 |
| 面板伺服器上的工具 | `xorriso`與`genisoimage`（建置每台伺服器的安裝ISO）以及`novnc`（瀏覽器主控台頁面）。請使用`sudo apt-get install -y xorriso genisoimage novnc`進行安裝，或由安裝程式代勞：加上`--baremetal`執行安裝程式，或提供ISO伺服器選項；若Bare Metal模組已啟用，執行更新時也會一併安裝。若缺少任一工具，**Safety**會以紅色提示列出，**live ops**將拒絕啟用（錯誤`tools_missing`），且主控台與作業系統安裝會直接回應缺少工具，而非在後續步驟才失敗。 |
| ISO 網頁伺服器 | 管理網路上的一般**HTTP**伺服器，負責將NexCMP ISO資料夾提供給各iDRAC。其位址為私人IPv4位址與選填的連接埠（例如`http://10.20.0.2:8080`，**不含路徑**），儲存於`dedicated_iso_base_url`中。該伺服器必須支援位元組範圍。由於該資料夾由面板的Worker寫入，因此網頁伺服器通常直接在**面板伺服器本身**運作，並監聽該伺服器在管理網路上的位址。NexCMP隨附了現成的nginx站台與單一步驟指令以供配置（見下文）。 |
| ISO 資料夾 | 用於儲存ISO檔案的資料夾，內部包含`pub`（供iDRAC讀取）與`server`（客戶ISO）。單一步驟指令會使用`/srv/nexcmp-iso`；若未使用該指令，預設值將依循安裝設定（設定項`dedicated_iso_lib_dir`、`dedicated_iso_pub_dir`、`dedicated_iso_server_dir`）。NexCMP Worker必須能夠對其進行**寫入**。除`/var/lib/nexcmp`外，Worker以唯讀檔案系統運作，因此位於其他位置的資料夾需要systemd drop-in設定檔（單一步驟指令會自動安裝）。 |
| 回呼位址 | `dedicated_callback_base`，一個安裝中的伺服器可以存取並指向您的面板的 `https://<your-domain>`。 |
| 儲存 | 供 ISO 圖書館與客戶提供的 ISO 使用的可用磁碟空間。 |
| 相依於 | **Bare Metal** 模組、一個區域，以及伺服器的 IP 池。 |

::: warning 範例值並非正式設定
全新安裝會在`dedicated_bmc_cidrs`、`dedicated_iso_base_url`與`dedicated_callback_base`中帶有範例值（私人範例網路與`https://example.com`）。這些都不是您的實際網路。只要其中任何一項仍為範例值，Bare Metal頁面就會顯示紅色的**Management network not configured**提示、匯入iDRAC時將無法通過允許清單檢查，且**live ops**開關會拒絕開啟（錯誤`config_placeholder`）。請在**Infrastructure › Bare Metal › Safety › Management network connection**下設定這三個數值（見下文）。
:::

## 準備基礎設施 {#prepare-the-infrastructure}

1. **將每個 iDRAC 放在客戶無法存取的管理網路**上，並為每一個指派固定的私有 IPv4 位址。從面板伺服器檢查 Redfish API：

   ```bash
   curl -sk -u 'nexcmp-admin:XXXX' https://10.20.0.11/redfish/v1/Systems | head
   ```

2. **在 iDRAC 上為 NexCMP 建立管理員帳號**（透過 iDRAC 網頁 UI 或 `racadm`）。請使用強固且唯一的密碼。切勿重複使用 iDRAC 的內建帳號。
3. **將ISO資料夾發布給iDRAC — 單一指令。**在面板伺服器上以root身分執行，並附帶該伺服器在管理網路上的位址與iDRAC網路：

   ```bash
   sudo nexcmp dedicated-setup-iso --listen 10.20.0.2:8080 --allow 10.20.0.0/24
   ```

   `--listen`必須是此伺服器的位址（私人IPv4，若省略則連接埠為8080）。`--allow`列出iDRAC網路（私人CIDR，/16或更小，最多8個，以半形逗點分隔）；僅允許這些網路下載，且當該設定仍為範例值時，指令也會將它們做為`dedicated_bmc_cidrs`使用。`--dir /path`可指定其他ISO資料夾（預設為`/srv/nexcmp-iso`）。該指令會：

   - 建立包含內部`pub`與`server`的資料夾，擁有者為NexCMP服務使用者；
   - 建立群組`nexcmp-iso`並將nginx使用者加入其中，以便當iDRAC掛載ISO時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`、三個資料夾、群組）並重啟NexCMP Worker。

   您可以傳入其他數值再次執行，而`sudo nexcmp dedicated-setup-iso --remove`會將nginx站台與drop-in設定檔移除（ISO檔案將保留）。此操作亦可在安裝時執行：只需在安裝指令中加入`--iso-listen`、`--iso-allow`（以及`--iso-dir`）。此指令**不會**建立管理網路，也不會連線至任何iDRAC；若數值有誤、位址不在這台伺服器上或連接埠已被佔用，它會在變更任何設定前停止並顯示訊息，且若`nginx -t`拒絕該nginx站台，則不會予以保留。

4. **ISO Web伺服器提供服務的內容。**nginx站台僅回應`GET`（以及支援byte ranges的`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`中的測試檔案應以206回應`Range`請求。

   *改為手動操作：*nginx站台與drop-in在發行套件中以範本形式提供（即`share/dedicated/nginx-iso.conf`與`share/dedicated/vmd-iso.conf`，位於`/opt/nexcmp/releases/<version>/`之下）。複製它們並替換`__...__`標記（監聽位址、資料夾、allow行、群組），同時保留上述規則。

5. **準備好作業系統映像檔。** 將自動安裝的 ISO 放置在程式庫資料夾中（請參閱下方的 **Templates**）。客戶也可以從連結新增 ISO；這些會被下載到伺服器，絕不會作為 URL 提供給 iDRAC。


## 在 NexCMP 中連線 {#connect-in-nexcmp}

### 1. 啟用模組 {#_1-turn-the-module-on}

在 **System › Admin › License & updates** 上，開啟 **Bare Metal**。**Bare Metal** 分類會出現在「基礎設施」下方。請參閱 [Modules](https://nexcmp.com/zh-tw/docs/infrastructure/modules/)。

### 2. 設定管理網路連線 {#_2-set-the-management-network-connection}

開啟**Infrastructure › Bare Metal › Safety**。**Management network connection**卡片包含決定各項功能是否可運作的三個數值：

| 欄位 | 設定 | 輸入內容 |
|---|---|---|
| iDRAC網路（CIDR） | `dedicated_bmc_cidrs` | 您的iDRAC私人網路，例如`10.20.0.0/24`。僅限私人CIDR、/16或更小、最多8個、以逗號分隔。僅能匯入這些範圍內的iDRAC。 |
| 供iDRAC使用的ISO伺服器 | `dedicated_iso_base_url` | `http://<private IPv4>[:port]`，不含路徑：上一節中ISO網頁伺服器的位址，例如`http://10.20.0.2:8080`。一步指令會自動為您填入。 |
| 控制台回呼位址 | `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的寫入指令（電源、虛擬媒體、主控台與作業系統安裝）。其初始狀態為**關閉**，且在上述管理網路連線仍保留範例數值時無法開啟（該開關會回應`config_placeholder`並指出欄位名稱）。寫入操作會在API層級與worker內部再次被拒絕，而讀取狀態功能則持續運作。第二道鎖**ops_locked**用於保護個別伺服器：即使live ops已開啟，新匯入的伺服器也一律處於鎖定狀態。

![「Live ops」關閉且列出已封鎖動作的安全頁面](https://nexcmp.com/zh-tw/docs/images/infrastructure/dedicated-01-safety.webp)

### 4. 匯入伺服器 {#_4-import-servers}

1. 開啟 **Infrastructure › Bare Metal › Stock / iDRAC import**。
2. 在 **Add one server** 下方輸入 iDRAC 位址、帳號與密碼，然後點擊 **Test connection**。此測試僅傳送讀取指令且不儲存任何內容。

   | 欄位 | 範例值 |
   |---|---|
   | iDRAC位址（URL或主機） | `10.20.0.11` |
   | 帳號 | `nexcmp-admin` |
   | Password | `XXXX` |
   | Label | `rack1-01`（空白：自動產生） |
   | 從位址池指派IP | 選填；選擇伺服器的服務 IP 池 |
   | 納入銷售清單 | 在準備好之前保持關閉 |

      ![庫存與 iDRAC 匯入畫面，包含範例位址與成功的唯讀測試](https://nexcmp.com/zh-tw/docs/images/infrastructure/dedicated-02-import-server.webp)

3. 點擊 **Save to stock**。NexCMP 會從 iDRAC 讀取型號、CPU、RAM、磁碟、NIC 與服務標籤。該伺服器將以**上鎖**狀態進入庫存。
4. 若要處理多台伺服器，請使用 **Bulk import**：每行一台伺服器，欄位以逗號、分號或 Tab 分隔。**Preview** 會檢查允許清單、iDRAC 位址或服務標籤的重複項，並讀取硬體資訊（一次最多四台伺服器）。

### 5. 客戶ISO與ISO網頁位址 {#_5-customer-isos-and-the-iso-web-address}

開啟 **Infrastructure › Bare Metal › Customer ISOs**。

- **HTTP address serving ISOs to iDRAC**為`dedicated_iso_base_url`，與Safety卡片中的值相同（在任一處皆可編輯）。請輸入您ISO網頁伺服器的管理網路位址。
- **Customer ISO limits** 可設定單一 ISO 的大小、總 ISO 儲存空間、最低可用空間、ISO 保留時間（小時）、最大下載時間與同時下載次數。

![包含iDRAC的HTTP位址與ISO限制的客戶ISO](https://nexcmp.com/zh-tw/docs/images/infrastructure/dedicated-03-iso-settings.webp)

### 6. 作業系統範本 {#_6-os-templates}

開啟**Infrastructure › Bare Metal › Templates**。此處會列出在資源庫資料夾中找到的自動安裝ISO。在檔案上按一下**Register**以填寫OS系列、版本與帳號（會根據檔案名稱預先填入），接著將範本切換為**Enable**。啟用範本不會啟動任何作業：每次安裝仍需通過安全閘門。**Unregister**只會移除範本資料列，絕不會刪除檔案。

![包含已註冊與未註冊ISO的Bare Metal Templates](https://nexcmp.com/zh-tw/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 Pools](https://nexcmp.com/zh-tw/docs/images/infrastructure/dedicated-05-ip-pools.webp)

### 8. 方案與銷售 {#_8-plans-and-sale}

1. 開啟**Services › Dedicated Server › Plans & pricing**。編輯四個範例方案（在1.6.1中名為`BM-40C-<RAM>`）或建立您自己的方案：價格、週期與設定費。**在全新安裝中，價格以美元為單位輸入至分，且電子錢包將扣除完全相同的金額：無需匯率換算。**若原有安裝已採用越南盾定價方案，則會保留越南盾，且設定中仍需配置匯率（若未設定，訂單將會被拒絕並顯示`dedicated_fx_unavailable`）。範例方案的初始價格為0且處於**已停用**狀態：上架銷售的方案價格必須大於0。請根據您實際匯入的硬體檢查每個方案；範例方案名稱不會偵測或變更伺服器的硬體。
2. 開啟伺服器（Infrastructure › Bare Metal › the server › **Sales**），**附加方案**並開啟**Sellable**。
3. 開啟**live ops**（安全頁面，需輸入確認文字）並解鎖您想要操作的伺服器（伺服器的 **Lock** 分頁，需填入會記錄至稽核日誌的原因）。
4. 在 **Services › Dedicated Server** 中開啟銷售功能。這需要兩個步驟：閱讀後果說明，然後輸入 `ENABLE SALES`。在此之前，客戶不會看到訂單頁面且不會被收費。

![銷售開關關閉的 Dedicated Server 方案](https://nexcmp.com/zh-tw/docs/images/infrastructure/dedicated-06-plans.webp)

### 客戶在其伺服器頁面上可執行的操作 {#what-customers-can-do-on-their-server-page}

客戶的伺服器頁面包含7個群組共16個分頁（Overview、Control、Network、Hardware、Billing、Activity、Settings）。**Billing**群組包含：

- **方案與續約**：一次預先支付1到24個月；新到期日自目前續約日開始起算，並自錢包扣款一次。可隨時開啟或關閉自動續約。
- **Billing cycle**：選擇其他週期（例如每季）；自**下次**續約時生效，目前不會扣款或退款。
- **Change plan**：客戶可以**申請**更換方案。提交申請不會產生任何費用。在您升級硬體或遷移伺服器後，可在**Services › Dedicated Server › Plan changes**批准或拒絕。批准升級時會針對客戶已付款週期的剩餘天數收取差額；降級則不予退款，並自下一週期起生效。
- **Invoices**：該伺服器的所有帳單（訂單、續約、升級）。

在**Plan changes**中，可依ID、日期、狀態、方案或伺服器排序請求；排序會套用至伺服器端的所有結果。在較窄的螢幕上水平捲動時，操作欄將保持可見。

在**Overview**頂部，四個即時資訊圖塊顯示**CPU**、**RAM**、**Disk**與**Network**，並附有過去24小時的微型圖表。CPU、RAM與Disk為上次iDRAC輪詢的使用率百分比（Disk為I/O活動，非可用空間）；Network為目前連入與連出速度加上當月總計，取自流量計數器。當伺服器關機、無法連線至iDRAC，或機器未回報該數值時，圖塊會顯示**—**及簡短原因；絕不會顯示捏造的0。這些讀數來自Dell iDRAC，若沒有流量計數器，Network圖塊將維持**—**。頁面開啟時圖塊每分鐘重新整理一次，點擊即可開啟**Hardware**或**Bandwidth**分頁。

在**Overview**中，**Access**卡片會顯示您安裝的作業系統使用者名稱與密碼，預設隱藏並提供**Show**與**Copy**按鈕。每次安裝後皆可查看，不限一次，且伺服器的新擁有者絕不會看到前任擁有者的密碼。若在伺服器內部變更了作業系統密碼，該卡片仍會顯示安裝時設定的密碼。**Bandwidth**分頁僅在有流量計數器提供數據時顯示（請參閱限制）。系統未提供**Subnet**分頁：NexCMP不支援將自備IP前綴帶入租用的伺服器。

### 客戶可以與不可以執行的操作 {#what-customers-can-and-cannot-do}

| 客戶可以 | 永遠無法執行 |
|---|---|
| 查看硬體狀態、健康狀況、電源狀態與計量數據 | 查看 iDRAC 位址、使用者名稱或密碼 |
| 開機、正常關機、重新開機、強制關機、重設 | 變更 iDRAC 帳號或 iDRAC 網路設定 |
| 開啟瀏覽器主控台（一次一個連線工作階段） | 變更 BIOS 或 RAID、清除日誌、更新韌體、重設 iDRAC |
| 掛載 ISO 或自訂 ISO 連結、設定單次開機、從啟用的範本重新安裝作業系統 | 執行原始 Redfish 呼叫（這些功能在 NexCMP 中不存在） |

NexCMP不會為客戶建立iDRAC帳號：客戶僅能使用入口網站的控制功能，且系統絕不會向其顯示iDRAC位址與登入資訊。

## 驗證 {#verify}

0. 在**Safety**中，**Management network connection**卡片未顯示紅色標籤，且Bare Metal頁面未顯示紅色提示。從管理網路上的主機執行`curl -I http://<iso-address>/`不會列出檔案。
1. 匯入表單上的 **Test connection** 會傳回型號、CPU、RAM 與服務標籤。
2. 伺服器會顯示在 **Servers** 中並帶有其硬體資訊。當 **live ops off** 時，任何電源操作都會被拒絕，並顯示「Server control is temporarily disabled system-wide」。
3. 在開啟 live ops 並解鎖一台測試伺服器後，從 **Operations** 或伺服器頁面將伺服器關機再開機，並開啟主控台。
4. 使用測試方案建立測試訂單：指派伺服器、安裝作業系統，並在安裝結束時由伺服器向面板回報。

## 限制與注意事項 {#limits-and-notes}

- 每台實體伺服器最多只能有一個現役訂閱。
- 寫入指令只有在**同時**開啟 live ops **且**伺服器鎖定為解鎖狀態時才會送出。此檢查會在背景工作行程中於每個指令執行前立即重複進行。
- **Installing** 狀態會等待新作業系統在其連接埠（SSH 22、Windows 3389、Proxmox 8006）上回應後才完成訂單；安裝作業設有時間限制（`dedicated_install_timeout_min`，預設 150 分鐘）。
- 專屬伺服器的頻寬是由非標準安裝隨附的流量計數代理程式計算。若未安裝，將不會記錄任何資料，入口網站會隱藏Bandwidth分頁，且API會將`capabilities.bandwidth`回報為`false`。
- 針對租用項目的管理員操作（鎖定、解鎖、退款或不退款取消）與其他所有服務的操作一致，退款會退回當初付款的餘額帳戶。
- 伺服器不會透過經銷商進行二次銷售：Dedicated 僅從主網站銷售。


## 故障排除 {#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]`、callback不是`https://<domain>`），或是使用了例如`example.com`的範例位址 | 請查看欄位下方的訊息；已儲存的數值未變更。 |
| `nexcmp dedicated-setup-iso`在變更任何內容前即停止 | `--listen`不是此伺服器的位址、連接埠已被佔用，或數值無效 | 請使用此伺服器在管理網路上的位址、更換其他連接埠，或更正訊息中指出的數值。 |
| 「iDRAC TLS 憑證與釘選的不符 - 輪詢與寫入動作已停止」 | iDRAC 憑證已更換（新憑證、更換了 iDRAC） | 開啟伺服器，進入 **Access** 分頁，比較兩組指紋，若確為預期變更，請點擊 **Repin certificate**。 |
| 「系統全域已暫時停用伺服器控制」 | 即時運作已關閉 | 請在 **Safety** 中開啟。 |
| 「此伺服器已鎖定操作」 | 個別伺服器鎖定已啟用 | 請在伺服器的 **Lock** 標籤頁中解除鎖定並填入原因。 |
| 「此伺服器目前有其他正在執行的操作」 | 先前的操作尚未完成 | 請稍候；並檢查 **Operations**。 |
| 「此伺服器已有其他開啟的主控台工作階段」 | 同時只能有一個主控台 | 請關閉其他工作階段。 |
| 「伺服器控制器暫時無法使用」 | iDRAC 無回應 | 請檢查管理網路與 iDRAC。 |
| 掛載 ISO 失敗並收到來自 iDRAC 的 403 或 404 | 網頁伺服器無法讀取檔案，或是基底位址錯誤 | 請檢查 ISO 網頁伺服器的權限以及 **HTTP address serving ISOs to iDRAC**。 |
| 「所選區域中的此方案目前無庫存」 | 該區域中沒有使用該方案的可銷售伺服器 | 請將方案套用至伺服器並開啟 **Sellable**。 |
| 「目前沒有可指派的 IPv4 位址」 | IP 池已耗盡 | 請在池中新增位址。 |
| 「目前無法使用自動作業系統安裝」 | 安裝必要條件不足 | 請檢查是否已啟用範本且 ISO 資料夾具備寫入權限；客戶仍可透過 ISO 與主控台進行安裝。 |
| 安裝停滯 | 安裝中的伺服器無法連線至回呼位址 | 請檢查 `dedicated_callback_base` 以及伺服器網路是否能透過 HTTPS 連線至您的控制台。 |


---

<!-- source: https://nexcmp.com/zh-tw/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 節點。** 一個執行於您 Linux 主機上的小型 Go 程式 `cmp-agent`。它會自動偵測主機上的公開 IPv4 位址，在每個銷售的位址上開啟 SOCKS5、HTTP 與 UDP 監聽器，並從客戶連線的**相同 IP** 發出流量（同 IP 出口）。它會每隔幾秒向控制台回報狀態。
- **IPv6 代理節點。** 一個代理服務，可提供客戶來自您路由至主機之 IPv6 字首的位址。控制台會透過 SSH 為您安裝。

您可以使用它們在您擁有伺服器的國家/地區轉售乾淨的 IP 位址。

## 需求 {#requirements}

### VPN 節點 {#vpn-node}

| 項目 | 需求 |
|---|---|
| 作業系統 | 具備 systemd 與 4.15（或更新版本）核心的 Linux 發行版本（支援 IPv6 自由繫結）。隨附的代理程式二進位檔僅支援 **x86_64** (amd64)。 |
| 權限 | root（用於安裝）。服務僅保留 `CAP_NET_ADMIN`、`CAP_NET_RAW` 與 `CAP_DAC_READ_SEARCH`。 |
| 工具 | `curl` 或 `wget`，以及 `sha256sum`（安裝程式未檢查檔案將拒絕繼續）。 |
| 公開位址 | 指派在主機介面上的公開 IPv4 位址（每個 `/32` 一個），**或者**路由至主機並作為額外子網路新增的前綴（IPv4 /16 至 /32，IPv6 /48 至 /128）。私有位址、CGNAT 及說明文件範圍將被忽略。 |
| 網路，輸入 | 客戶連線至每個出售的公開 IP 之 **65001-65535 連接埠**（SOCKS5 與 HTTP 使用 TCP，UDP 關聯使用 UDP）。每個端點使用一組三個連續的連接埠。 |
| 網路，輸出 | HTTPS (443) 連線至您的面板網域。代理程式亦會透過 `ip-api.com` (HTTP) 與 `ipinfo.io` (HTTPS) 查詢其自身國家，逾時時間為 3.5 秒。 |
| 郵件 | 對外連接port 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 代理的 on-link 傳遞（見下方）。 |
| 網路 | 客戶連接至節點的IPv4 port 80（HTTP proxy）、port 443（SOCKS5）與port 60001-65535（每個固定IP對應一個port）。節點沒有憑證，因此沒有HTTPS proxy。流量僅透過IPv6送出，且只送往具有IPv6位址的目的地。節點會透過HTTPS從控制面板拉取設定。 |
| 面板伺服器上的節點軟體 | 節點守護程序（daemon）及其網路指令碼隨附於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 節點 {#vpn-node-1}

1. **佈建主機**，安裝支援的 Linux 並設定您想要出售的公開 IPv4 位址（可設定於網路介面上或路由至主機）。
2. **若您販售路由網段**，請規劃在新增節點時將其輸入為**Extra subnet**。Agent會安裝路由`local <block> dev lo`，使主機接收該網段中每個位址的流量，隨後回報找到的位址。Agent也會讀取主機的實際路由表，絕不販售或佔用**閘道**位址：若該網段包含主機其中一條路由的下一躍點（例如直連網段的路由器位址），Agent僅會為周圍的網段部分安裝`local`路由，並將閘道回報給控制面板，而控制面板會將該位址排除在位址池及所有分配之外。當額外子網路變更或Agent停止時，它會移除已安裝的路由。
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）路由**至節點自身的地址**。外發封包可以使用前綴中的任何地址作為來源，且回覆會返回該節點。 | 請向您的提供商索取一個下一個躍點為該節點的路由前綴。節點上無需額外設定：代理服務使用透明通訊 SOCKET、固定的策略路由表以及 `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 的前綴會被接受為**路由**。

::: warning 切勿重複使用相同前綴
前綴不得與其他節點的前綴重疊，且不得大於面板自身 IPv6 池中已有的前綴。面板池**內部**的 /64 是允許的。重疊會在安裝結果中回報為「assign range … (node …)」，並且會略過該前綴。
:::

節點自行套用的限制：客戶無法從池地址傳送郵件（連接埠 25、465、587、2525），且精靈自身的 IPv4 流量僅限於回覆以及面板和 DNS。

## 在 NexCMP 中連線 {#connect-in-nexcmp}

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

1. 在 **System › Admin › License & updates** 上，將 **VPN** 切換為開啟。請參閱 [Modules](https://nexcmp.com/zh-tw/docs/infrastructure/modules/)。

      ![帶有 VPN 與 IPv6 Proxy 開關的模組卡片](https://nexcmp.com/zh-tw/docs/images/infrastructure/vpn-proxy-nodes-01-modules.webp)

2. 開啟 **Infrastructure › VPN & Proxy nodes › Agents & external nodes**。您有兩種方法可以新增節點。

   **a. 透過 SSH 安裝。** 點擊 **+ Add server (SSH)** 並填入：

   | 欄位 | 範例值 |
   |---|---|
   | 伺服器 IPv4 地址 | `192.0.2.50` |
   | SSH 連埠 | `22` |
   | SSH 使用者 | `root` |
   | SSH 密碼 | `XXXX` |
   | 顯示名稱 | `node-ny-1`（留空：以 IP 命名） |
   | 伺服器角色 | 外部 VPN / 代理節點 |
   | 區域指派 | 依 GeoIP 自動（建立 / 指派區域），或現有區域 |
   | 額外子網域（選填） | 留空以自動掃描介面，或輸入路由網段如 `203.0.113.0/24` |
   | 安裝後啟用銷售 | 啟用以將所有偵測到的位址標記為可銷售 |

   按一下 **Connect & install**。面板會透過 SSH 連線、使用一次性票證在節點上執行單行安裝程式，並顯示節點名稱、GeoIP 位置與偵測到的範圍。

      ![透過 SSH 新增節點對話方塊，帶有範例伺服器地址與角色](https://nexcmp.com/zh-tw/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
   ```

   使用Token安裝僅會註冊機器以供監控：基於安全考量，控制面板不允許持有共用Token的機器自行指派VPN角色（在指令中加入`--roles vpn`無效）。機器出現在清單中後，請開啟該機器並手動為其新增**VPN**角色。透過SSH安裝（選項a）則會從一開始就賦予節點VPN角色。產生新Token會使舊Token失效；已註冊的主機會繼續正常運作，因為它們使用的是自己的金鑰。

      ![顯示一次性憑證指令的安裝指令對話方塊](https://nexcmp.com/zh-tw/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**，則會建立並設為公開，主機上找到的位址則會成為 pool 範圍。
4. 開啟 **Infrastructure › VPN & Proxy nodes › VPN IP pools** 以檢視範圍、其 zone 與節點，並可變更每個範圍的 zone、節點或 **Sellable** 開關。**Enable range** 允許新訂單使用其可用 IP；**Disable range** 僅停止新配置，已租用的 IP 仍會繼續運作。

      ![VPN IP 池與節點回報的範圍](https://nexcmp.com/zh-tw/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/zh-tw/docs/images/infrastructure/vpn-proxy-nodes-05-proxy6-add-node.webp)

3. 隨後面板會依序執行：檢查機器與連接埠、複製背景程式、網路腳本、服務單元與節點專屬的環境檔案（節點權杖與密碼簽章金鑰）、執行可用前綴的 **probe**、將前綴記錄至 pool 中，並啟動服務，同時等待最多 90 秒以接收首次回報。**Install log** 會顯示每個步驟。
4. 新節點會以 **off** 狀態建立其 zone（根據節點 IPv4 的 GeoIP）。請至 **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 的一次性 ticket 或權杖，之後使用其專屬金鑰 | 一次性 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節點agent會在每次活動訊號回報所承載的流量，控制台會將其計入當期方案用量。客戶端（Overview與Bandwidth分頁）以及您（VPN › Subscriptions、Used欄位與節點列）看到的數值完全相同。

- **中斷服務。**當方案用完當期的GB配額時，控制面板會停止向Agent發送該方案的端點，進而拒絕新連線並關閉已建立的連線。切斷會在一次活動訊號內生效，因此方案可能會略微超出上限。設有Unlimited層級的方案絕不會被中斷。
- **恢復服務。**客戶加購頻寬或進入下一計費週期後，方案會在一次活動訊號內恢復提供服務。
- **未計量。**代理程式尚未回傳用量的節點（例如較舊版本的代理程式）會顯示為**Not measured**，且其方案絕不會因GB用量而中斷。
- **更新agent。**節點上請使用agent **1.5.1**。較舊版本的agent仍會計量，但可能會遺失失敗心跳、已停止端點或重啟時的位元組數，且在方案被切斷時不會關閉已開啟的連線。請從節點列（Reinstall）或使用`upgrade`指令更新。
- 計量是以通過Proxy的有效負載為準，因此會略低於實體線路上的傳輸位元組數（約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 或 proxy 方案。客戶將獲得端點 `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節點agent回報的流量，並在當期GB數用盡時切斷該方案的Proxy（請參閱下方的「Data allowance on a VPN node」）。IPv6 Proxy方案沒有GB配額限制；其依方案限制Mbps速率。
- VPN方案的IPv4位址不會輪替。當客戶回報IP被列入黑名單時，由您或經銷商核准從同一區域更換。只有IPv6 Proxy會輪替。
- 每個心跳最多回報 64 個範圍。
- 每個售出的IP會使用一組三個VPN端點。透過65001-65535連接埠，每個IP僅提供有限數量的端點（178個連接埠組）；面板會略過先前使用過的連接埠組。
- 僅在沒有任何方案擁有該IP時，才允許刪除IPv6代理節點。這會移除節點的位址區段與權杖；主機上的軟體不會被解除安裝。
- 轉售同時承載您自身虛擬機的位址區段是可行的：VPN僅使用65001-65535連接埠，因此它會與其他服務共用該IP。

## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| 「enrollment failed (invalid token or server unreachable)」（註冊失敗：權杖無效或伺服器無法連線） | 權杖錯誤或已被使用，或者無法連線至面板 | 產生新的權杖，或重新嘗試SSH安裝。 |
| 「file signature mismatch - STOP」（檔案簽章不符 - 已停止） | 下載的代理程式與發布的SHA-256不符 | 檢查面板的`/dl/`資料夾，並確保下載過程中沒有任何東西被覆寫。 |
| 「this installer is for Linux only」/「architecture … is not supported yet」（此安裝程式僅適用於 Linux / 架構 … 尚不支援） | Windows，或非x86_64的架構（發行版本僅隨附x86_64的agent） | 請使用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`手動檢查存取權限。 |
| 「architecture … not supported (x86_64 only)」（架構 … 不支援，僅限 x86_64） | 節點不是x86_64架構 | 請使用x86_64主機。 |
| 「node missing command: …」（節點缺少指令：…） | 未安裝`nft`、`ip`、`ss`、`sysctl`、`systemctl`或`useradd` | 請安裝這些套件，然後再次執行安裝。 |
| 「ports in use by another service on node: … — 80、443、60001-65535 必須是空閒的」 | 80、443或60000以上的連接埠已被佔用 | 移動其他服務；安裝程式不會自動停止它。 |
| 「no IPv6 prefix with Internet access found from node (real egress probe failed)」（找不到節點具有網際網路存取的 IPv6 前綴：實際連線探測失敗） | 沒有路由字首、無法使用NDP代理，或沒有對外的IPv6 | 檢查字首是否已路由至節點、介面是否具備IPv6連線能力，且沒有任何東西過濾對外流量。 |
| 「all detected ranges already belong to another node」（所有偵測到的範圍皆已屬於其他節點） | 該字首已被其他節點使用 | 從其他節點移除它，或選擇其他字首。 |
| 安裝結束時顯示「no initial report received from node」 | 服務已啟動，但在90秒內未連線至控制面板 | 檢查提供給節點的面板URL以及節點至該處的HTTPS路徑；請參閱**Install log**。 |
| 節點列顯示**missed heartbeat** | 120秒內無回報 | 檢查節點上的服務、其時鐘以及至面板的路徑。 |
| 客戶未看到IPv6位置 | 區域已關閉 | 在**Zone**下啟用區域。 |


---

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

# AI Models {#ai-models}

> **管理後台位置：**System › Admin › License & updates（`/license`）以啟用模組。接著前往Services › AI Models：Providers（`/ai/providers`）、Models（`/ai/models`）、Profit（`/ai/profit`）與Audit（`/ai/audit`）。客戶則在客戶入口網站中使用AI › API。

## 功能 {#what-it-does}

AI Models是您控制台上的閘道與計費層。您的客戶取得API金鑰，並以OpenAI相容或Anthropic相容格式呼叫**您網域上的單一端點**。您可以選擇提供哪些模型，以及每1百萬個token的費用。NexCMP會檢查金鑰、限制與錢包，將請求傳送給您新增的提供商，計量token並從客戶的預付錢包扣款。

**您需自備模型來源。**NexCMP預設不隨附任何提供商、模型、預設位址或價格，亦不提供模型、API金鑰、token或提供商帳號。

::: warning 請先確認來源服務條款
許多模型來源限制轉售或將存取權轉讓給第三方。請僅使用您獲授權使用並可轉售的來源，並遵守其條款與適用的法律。本頁面不構成法律建議。
:::

AI Models是與**AI Chat and AI Agent**（模組**AI**，請參閱[AI提供商](https://nexcmp.com/zh-tw/docs/ai/ai-providers/)）各自獨立的產品。這兩個模組彼此互不依賴。

## 需求 {#requirements}

| 項目 | 需求 |
|---|---|
| 模組 | 已在License & updates的Modules下開啟**AI Models**。預設為關閉。 |
| 提供商 | 您獲得授權轉售的一或多個模型來源，各自具備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金鑰，並記下其base URL（例如`https://api.example.com/v1`）。
2. 確認該來源關於轉售的服務條款。
3. 若來源運行於您的內部網路中，請確定其位址（例如`http://10.0.0.5:8000/v1`）。您需要將`10.0.0.5:8000`列於**Allowed internal hosts**下。

## 在 NexCMP 中連線 {#connect-in-nexcmp}

### 1. 啟用模組 {#_1-turn-the-module-on}

開啟**System › Admin › License & updates**，找到**Module**卡片，並開啟**AI Models**。選單將重新載入並顯示**Services › AI Models**。在此模組關閉期間，客戶頁面、管理頁面與閘道皆會回應`404 module_disabled`，且不會連線至任何提供商。

![已開啟AI Models開關的Module卡片](https://nexcmp.com/zh-tw/docs/images/infrastructure/ai-models-01-modules.webp)

### 2. 新增提供商 {#_2-add-a-provider}

1. 開啟**AI Models › Providers**並選擇**Add provider**。
2. 輸入簡短的**slug**、**名稱**（僅您可見）、**類型**（OpenAI-compatible、Anthropic-compatible或Both）、**base URL**與**API key**，以及**優先級**（數字較小者優先嘗試）。
3. 儲存。金鑰將加密儲存，且後續僅顯示最後4個字元。金鑰僅能由已登入的管理員工作階段輸入。

僅在閘道確實同時支援兩種格式時才使用**Both**。NexCMP**不會**在兩種格式之間進行轉換：由相容OpenAI的提供商提供的模型需透過`/ai/v1/chat/completions`存取，而由相容Anthropic的提供商提供的模型則透過`/ai/v1/messages`存取。

![顯示三個範例提供商及其類型、優先順序和狀態的 Providers 頁面](https://nexcmp.com/zh-tw/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百萬個token的**銷售價格**：**input**、**cached input** 與 **output**。
3. 可選擇輸入您該模型的**成本**。接著 **Profit** 會依日期和模型顯示營收與成本的對比，且除非您確認刻意承受虧損，否則低於成本加上最低利潤（設定項目 `ai_min_margin_pct`，預設為 10）的銷售價格將會被拒絕。**Set price from cost** 會使用您自訂的加成比例；沒有預設加成。
4. 啟用該模型。未設定銷售價格的模型無法啟用。cached input 價格若保留為零，則會按 input 價格計費。

![包含 input、cached input 與 output 銷售價格及啟閉開關的 Models 頁面](https://nexcmp.com/zh-tw/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` 阻擋）、每分鐘請求數以及每分鐘 tokens 數。
- **Usage**：依模型、金鑰和日期顯示用量，並支援匯出。
- **Logs**：可篩選的請求記錄（時間、金鑰、模型、tokens、成本、狀態、延遲）。**不會記錄 prompt 和回應內容。**記錄預設保留 90 天（`ai_log_retention_days`）。
- **Settings**：帳戶預算以及預算警報的電子郵件地址。
- **Playground**：與模型交談、並排比較多個模型，並複製相應的程式碼。

![顯示兩種 API 格式基礎 URL 的客戶 API Keys 頁面](https://nexcmp.com/zh-tw/docs/images/infrastructure/ai-models-04-keys.webp)

位於您網域上的閘道端點：

```text
POST /ai/v1/chat/completions      OpenAI-compatible
POST /ai/v1/messages              Anthropic-compatible (also /ai/v1/messages/count_tokens)
GET  /ai/v1/models                model list
GET  /ai/v1/models/pricing        public price list, no key needed
```

### 錢包與帳單 {#wallet-and-billing}

AI使用量與其他所有服務一樣，皆從同一個預付錢包扣款。在請求送至供應商之前，NexCMP會為該請求可能產生的最高費用預留金額；若餘額低於最低額度（`ai_min_balance_cents`，預設為20美分）或金額不足，該請求將被拒絕並傳回`402 insufficient_balance`，且**不會呼叫任何供應商**。使用量按帳戶收集，並在每小時結束後結算為錢包帳本分錄，且每5分鐘清理一次；尚未結算的使用量已從閘道看到的餘額中扣除。

分銷商可在自己的網域上銷售AI Models：其加價或折扣會套用於您的售價，其批發錢包則會扣除批發價。每個分銷商獨立的AI開關（預設為開啟）控制誰可以進行銷售。

## 驗證 {#verify}

1. 完成步驟3後，**Test connection**會顯示**ok**與模型數量。
2. 完成步驟4後，新模型將列出，處於關閉狀態且沒有價格。
3. 以錢包內有儲值資金的客戶身分建立金鑰，並呼叫閘道：

   ```bash
   curl https://your-domain/ai/v1/chat/completions \
     -H "Authorization: Bearer sk-ai-…" -H "Content-Type: application/json" \
     -d '{"model":"model-one","messages":[{"role":"user","content":"hello"}]}'
   ```

   `200`回應帶有模型的回答。**Usage**會顯示該請求，若您有輸入成本，**Profit**也會顯示該請求。
4. 當錢包餘額為零時，相同的呼叫會傳回`402 insufficient_balance`。

## 限制與注意事項 {#limits-and-notes}

- 此模組未內建任何供應商、模型或價格，且絕不會從供應商讀取價目表。
- 在供應商端執行且按次計費的工具（例如網路搜尋）會被拒絕，因為它們無法進行計量。只有少數請求參數會被傳遞。
- Token使用量取自供應商的回覆；若回覆中未包含，NexCMP會進行估算並將該記錄標記為預估。
- 來自供應商的錯誤在傳送給客戶之前會先經過清理（移除名稱、主機、位址與供應商的模型名稱）。客戶絕不會看到是哪家供應商處理了請求。
- 客戶透過您控制台的網域連線至閘道，因此該網域的TLS必須能正常運作。
- NexCMP不為此模組提供服務等級協定、微調或GPU託管。

## 故障排除 {#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，或是名稱解析為私人位址。若確有此需求，請將其列於**Allowed internal hosts**之下。 |
| **Test connection**顯示`auth` | 金鑰錯誤或無存取權限。請重新輸入金鑰。 |
| 無法開啟模型（`no_price`） | 請先設定售價。 |
| 客戶收到`503 ai_unavailable` | 銷售開關處於關閉狀態，或分銷商的AI開關已關閉。 |
| 客戶收到`503 upstream_unavailable` | 沒有已啟用且具備金鑰的路由能以請求的格式提供該模型。請檢查該模型的路由與供應商類型。 |
| 客戶收到`402 insufficient_balance` | 錢包餘額低於最低限制或不足以支付該請求。請要求客戶儲值。 |


---

<!-- source: https://nexcmp.com/zh-tw/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`）。 |
| Admin user | 為NexCMP建立的RGW使用者，需具備下方列出的權限。請勿使用擁有客戶資料的使用者。 |
| Endpoints | 客戶使用的S3端點以及Admin Ops端點。兩者皆寫為`https://host`且**無路徑、僅限連接埠443**，並必須解析為**公開**位址：迴路、鏈結本地、多點廣播、私有及唯一本地位址將被拒絕。 |
| Certificate | 端點主機的有效憑證。 |
| Usage log | 已開啟RGW用量記錄（`rgw_enable_usage_log = true`），以便用量API可以回報流量。 |
| 區域 | 勾選了**Object Storage (S3)**服務的主區域。請參閱[Zones](https://nexcmp.com/zh-tw/docs/infrastructure/zones/)。 |
| 儲存 | Ceph中用於您所銷售配額的容量。 |
| 相依於 | 模組**Object Storage**。下載流量也會計入[Bandwidth](https://nexcmp.com/zh-tw/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**：

   | 欄位 | 範例值 |
   |---|---|
   | 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/zh-tw/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。 |
   | 執行中虛擬機器之免費額度（GB） | 當客戶擁有至少一台執行中的虛擬機器時，每個帳號固定為100 GB，依容量在其S3帳號之間共用。 |
   | 欠費額度上限（VND） | 允許的未付使用費金額。 |
   | 計費門檻（VND） | 使用量達到此金額後將合併為一張帳單。 |
   | 建立S3所需的最低餘額（VND） | 建立帳號所需的錢包餘額。 |
   | 每個客戶的S3帳號上限，預設技術配額（GB） | 新帳號的限制。 |

      ![S3 PAYG定價表單](https://nexcmp.com/zh-tw/docs/images/infrastructure/s3-04-pricing.webp)

   S3價格以VND輸入。顯示與錢包扣款時會依當時的匯率進行換算；請參閱[Currency and exchange rates](https://nexcmp.com/zh-tw/docs/catalog/currency-and-exchange-rates/)。

## 驗證 {#verify}

1. **Check**顯示「Ceph connection successful」。
2. 以客戶身分（或使用測試帳號）建立S3帳號。在Ceph上，`radosgw-admin user list`會顯示新使用者，且**S3 accounts**會列出該帳號。
3. 使用任何S3客戶端，以客戶的金鑰對應客戶端點建立值區（bucket）。上傳檔案。
4. 在下一個小時的計費時間點後，**S3 accounts**會顯示使用量。

## 限制與注意事項 {#limits-and-notes}

- 已附加帳號的後端會保留其**區域、端點與區域設定**；若要變更，請建立新的後端。
- 單一區域可擁有專屬後端；帳號與後端一律永久繫結至特定區域。
- 免費額度與「上傳免費」為固定規則，而非選項。
- 金鑰經過加密儲存；控制台僅顯示「留空以保留目前金鑰」欄位。金鑰對一律必須同時輸入。
- 客戶的祕密金鑰僅在建立時顯示一次，之後不再顯示。若金鑰遺失，需透過輪替（rotating）來取代。

## 故障排除 {#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/zh-tw/docs/infrastructure/kubernetes-and-private-cloud/ -->

# Kubernetes 與私有雲 {#kubernetes-and-private-cloud}

> **管理後台位置：** Kubernetes：Infrastructure › Cloud provider › CloudStack › Kubernetes (CKS) (`/infra/cloudstack?tab=k8s`)，以及 Services › Kubernetes (Overview, Clusters, Versions, Policy)。私有雲：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 叢集。控制平面是免費的，客戶僅需為 **worker** 節點付費。NexCMP 會為每個叢集建立獨立的網路與公開 IP，並將每個客戶的叢集隔離開來。
- **Private Cloud。** 客戶可獲得一個包含路由器、子網路 (tiers)、防火牆規則 (network ACLs) 以及虛擬機器的私有網路 (CloudStack VPC)。此服務按**頻寬方案**銷售，提供專用且不限流量的速率（例如 50、100、500 Mbps、1 Gbps 與 3 Gbps）。預設情況下，每位客戶可擁有一個 VPC。

兩者皆建置於 [CloudStack](https://nexcmp.com/zh-tw/docs/infrastructure/cloudstack/) 上，並透過相同的連線使用其 API。

## 需求 {#requirements}

### Kubernetes {#kubernetes}

| 項目 | 需求 |
|---|---|
| CloudStack | 4.23 (已測試)。CKS 必須處於**啟用**狀態 (`cloud.kubernetes.service.enabled = true`)。 |
| 帳號 | 專用網域中的 **Domain Admin** 帳戶，以便 NexCMP 能為每個客戶建立 CloudStack 專案及其內部的資源限制。請參閱 [CloudStack](https://nexcmp.com/zh-tw/docs/infrastructure/cloudstack/#create-a-dedicated-account-and-api-key)。 |
| `endpoint.url` | CloudStack 全域設定必須指向您的管理 API，且必須能從叢集虛擬機器存取。NexCMP 會顯示該數值與端點檢查的結果。 |
| 版本 | 至少有一個支援的 Kubernetes 版本項目及其二進位檔 ISO，狀態為 **Enabled**。已過支援周期的版本不得上架銷售。 |
| 控制平面方案 | 一個免費的服務方案，具有**剛好 2 vCPU、2048 MB RAM 與 CPU 上限** (`limitcpuuse = true`)，對該帳戶可見。伺服器會拒絕任何其他設定並回傳 `cp_offering_invalid`。 |
| 網路 | 一個已啟用的具備 CKS 功能的隔離網路方案。 |
| IP | 可銷售範圍內的免費公共 IPv4 位址；每個叢集使用一個。 |
| 容量 | 每個叢集會佔用您 2 到 4 GB 的 RAM 作為控制平面及小型路由器虛擬機器。請注意容量分頁。 |

### 私有雲 {#private-cloud}

| 項目 | 需求 |
|---|---|
| CloudStack | 4.23（已測試），已啟用 VPC。 |
| VPC 方案 | 一個 VPC 方案。雙堆疊方案也會為每個階層提供一個 IPv6 /64。 |
| 階層網路方案 | **每個頻寬方案一個網路方案**，為 VPC 建立，其**網路速率** (Mbps) 等於該方案，外加一個**已鎖定**的 **1 Mbps** 方案，當 VPC 因未付款而被鎖定時會套用此方案。 |
| 帳號 | 專用帳戶（建議使用 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` 會被叢集的控制器回呼，因此它必須是叢集虛擬機器能夠到達的位址。

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-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** 的網路方案（複製預設的「VPC 網路的隔離網路方案」），並將 **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。請將**每一個**都替換為你自己的，否則第一個 VPC 訂單將會失敗。
:::

## 在 NexCMP 中連線 {#connect-in-nexcmp}

### Kubernetes {#kubernetes-1}

1. 開啟 **Infrastructure › Cloud provider › CloudStack** 並選擇 **Kubernetes (CKS)** 標籤頁。右側的 **CKS status on CloudStack (read-only)** 卡片會顯示 `kubernetesserviceenabled`、包含 **Endpoint check** 的 `endpoint.url`、CKS 網路方案、`cloud.kubernetes.*` 設定以及 ISO 與版本列表。修正問題後，請按一下 **Recheck**。
2. 在 **Sales config** 中，選擇 **Control plane Offering**（若不符合剛好 2 vCPU / 2048 MB / CPU 上限將會顯示警告），設定 **Max workers per cluster**（1 到 9：CKS 允許包含控制節點在內共 10 個節點），將 **Enable CKS for this backend** 切換為開啟，然後按一下 **Save**。在選擇方案之前，此開關將維持停用狀態。

      ![Kubernetes (CKS) 標籤頁，已選擇控制平面方案並顯示 CKS 狀態卡片](https://nexcmp.com/zh-tw/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/zh-tw/docs/images/infrastructure/kubernetes-and-private-cloud-03-policy.webp)

### 私有雲 {#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/zh-tw/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/zh-tw/docs/images/infrastructure/kubernetes-and-private-cloud-05-vpc-plan.webp)

3. 將 **Sell Private Cloud** 切換為開啟。若要先行測試，請將測試帳號 ID 新增至 **Beta accounts**：這些帳號可在銷售開關關閉時使用此服務。

## 驗證 {#verify}

1. Kubernetes：狀態卡片會顯示 `kubernetesserviceenabled: true`、良好的端點檢查以及啟用的版本。以客戶身分建立一個單一背景工作節點的測試叢集；它應該會達到執行中狀態，且 `kubectl get nodes` 應該會顯示其就緒。事後請將其刪除：網路與 IP 將會返回集區中。
2. Private Cloud：以測試客戶身分使用最小的方案建立 VPC。VPC 應顯示為使用中，某個層級會取得其子網路，該層級中的 VM 透過 VPC 路由器連線至網際網路，且 **Change plan** 至較大方案可在約 20 秒內生效而不會中斷連線。

## 限制與注意事項 {#limits-and-notes}

- Kubernetes：背景工作節點的計費方式與方案價格的 VM 相同，且在 VM 限制中計入 VM 數量。由於 CKS 限制 10 個節點，因此一個叢集最多只能有 9 個背景工作節點。
- Kubernetes：叢集的控制平面、路由器和公開 IP 對客戶而言是免費的；其成本由你承擔。
- Private Cloud：所有方案皆為**不計量**。表單中的價格為越南盾每月；成本欄位使用的是非你所有的參考價格，因此請使用你自己的數字。
- 鎖定的 VPC 限制為 1 Mbps，不予計費且不會自動刪除。
- Private Cloud 每個 VPC 使用一個路由器，而非備援對。若其主機故障，CloudStack 會在幾分鐘內重建它。

## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| `cp_offering_invalid` / 「此方案不是 2 vCPU / 2048 MB / limitcpuuse」 | 控制平面方案有其他大小或沒有 CPU 上限 | 如步驟 3 建立方案並重新選擇。 |
| **Enable CKS** 開關已關閉 | 未選擇控制平面方案 | 請先選擇一個。 |
| `kubernetesserviceenabled: false` | CloudStack 中的 CKS 已關閉 | 請啟用它並重新啟動管理伺服器。 |
| 端點檢查失敗 | 無法從叢集虛擬機器連線至 `endpoint.url` | 設定可連線的 URL，重新啟動管理伺服器，然後點擊 **Recheck**。 |
| 「EOL: 無法啟用銷售」 | 版本已過生命週期終止 (EOL) 日期 | 註冊較新的版本。 |
| 「沒有版本：點擊從 CloudStack 同步」 | 未註冊 Kubernetes 版本 | 註冊版本並同步。 |
| 「CKS 後端為關閉：即使啟用銷售旗標，客戶也無法建立叢集」 | 銷售開關已開啟但 CKS 後端為關閉 | 在 CloudStack 分頁上啟用 CKS。 |
| 「至少必須有 1 個方案在販售中」 | 最後一個背景工作節點方案已被移除 | 保留至少一個方案，或關閉 Kubernetes 銷售。 |
| 叢集建立卡住 | 容量不足或缺少 ISO | 檢查容量分頁與版本的 ISO 狀態。 |
| 新 VPC 在第一步失敗 | VPC 方案或層級方案 ID 無效 | 將每個方案 UUID 替換為來自您 CloudStack 的 UUID。 |
| 「cs_offering_id 必須是 UUID」 | 方案 ID 不是 UUID | 貼上來自 `cmk list networkofferings` 的 ID。 |
| 方案變更失敗 | 新的層級方案不存在或網路速率錯誤 | 檢查方案 UUID 及其網路速率。 |




---

<!-- source: https://nexcmp.com/zh-tw/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、記憶體、根磁碟與價格，位於某個區域，來自單一來源 (CloudStack 或 Proxmox VE 叢集)。客戶選擇方案、作業系統與**計費週期** (每小時、每月或更長時間的預付期限)。方案可在客戶入口網站、透過 API 以及在經銷商網站上銷售。

## 需求 {#requirements}

| 項目 | 需求 |
|---|---|
| Source | 已連線 CloudStack (方案指向 CloudStack 服務方案) 或附加至該區域的 Proxmox VE 叢集。請參閱 [CloudStack](https://nexcmp.com/zh-tw/docs/infrastructure/cloudstack/) 與 [Proxmox VE](https://nexcmp.com/zh-tw/docs/infrastructure/proxmox/)。 |
| 區域 | 販售虛擬機器的區域。請參閱 [Zones](https://nexcmp.com/zh-tw/docs/infrastructure/zones/)。 |
| 範本 | 至少有一個已啟用且就緒的範本。請參閱 [OS templates](https://nexcmp.com/zh-tw/docs/infrastructure/templates/)。 |
| 匯率 | 僅限您以 VND 輸入價格時。請參閱 [Currency and exchange rates](https://nexcmp.com/zh-tw/docs/catalog/currency-and-exchange-rates/)。 |
| 權限 | 管理者；每一次價格變更都必須填寫原因。 |

## 準備基礎設施 {#prepare-the-infrastructure}

- **CloudStack：** 建立您想要銷售的服務方案（公開，或與 NexCMP 網域共用）。方案會指向一個服務方案。**Offering CloudStack** 標籤頁會即時列出來自 CloudStack 的服務方案與磁碟方案（快取 60 秒）。當方案表格為空時，背景工作會自動從您的實際服務方案建立六個方案。
- **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. 填寫表單：

   | 欄位 | 範例值 |
   |---|---|
   | 方案名稱 | `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` |
   | 啟用 | 開啟：客戶可以購買 |
   | 可見性 | 在目錄中顯示 |
   | 價格變更原因 | `initial price` |


3. 點擊 **OK**。該方案將顯示於表格中，並帶有每小時、每月價格以及每個啟用週期的欄位。

      ![方案表格包含每小時、每月與每週期價格](https://nexcmp.com/zh-tw/docs/images/catalog/plans-02-list.webp)

### 計費週期 {#billing-cycles}

開啟 **Cycle** 標籤頁以設定客戶可選擇的週期及其折扣。

| 週期 | 預設值 | 注意事項 |
|---|---|---|
| 按小時 | 永遠開啟 | 按每小時計費。 |
| 按月 | 開啟，0% | |
| 1 年 | 開啟，10% | |
| 2 年 | 開啟，15% | |
| 3 年 | 開啟，20% | |

您可以重新命名計費週期、更改其折扣（0至90%）並切換其啟用或停用狀態。變更會套用於在您儲存**後**購買或續約的虛擬機器；執行中的虛擬機器會保留其鎖定的價格。

![顯示每個計費週期折扣的 Cycle 標籤頁](https://nexcmp.com/zh-tw/docs/images/catalog/plans-03-cycles.webp)

### 設定基礎方案並推導其他方案 {#set-a-base-plan-and-derive-the-others}

**Set base plan + derive other plans** 會根據單一價格重新計算整個表格的價格。選擇基礎方案及其價格，然後選擇保持方案之間的**current price ratios**，或是從**component prices**（每個 vCPU、每 GB RAM 及每 GB NVMe 的 µ$/小時，並可選 0 到 50% 的組合折扣）進行計算。預覽表格會在寫入任何資料之前顯示新舊價格。點擊 **Apply**，並提供原因。

當您套用新價格時：執行中的**按時計費**虛擬機器將從下一個計費小時起享有**較低**的價格，預付費虛擬機器則會在續約時計入。如果價格**調漲**，執行中的虛擬機器將維持舊價格。

### 自訂方案 {#custom-plans}

**Custom plan** 標籤頁讓客戶能夠自訂其 vCPU、RAM 和 NVMe 大小。設定一個 vCPU、一 GB RAM 及一 GB NVMe 的每小時單價（留空則從百分比折扣推導）、各自的最小值、最大值與遞增量，以及套用的計費週期。**自訂**方案的價格應高於相同大小的固定方案，否則客戶會選擇跳過固定方案；該頁面會標記自訂方案較便宜的列。開啟 **Enable custom plans for customers** 即可開始銷售；關閉時則會在 portal 中顯示「Coming soon」。每個自訂虛擬機器都有其專屬的隱藏方案列；在該虛擬機器存在期間，這些列無法被編輯或刪除。


### 變更、隱藏、複製、刪除 {#change-hide-clone-delete}

| 動作 | 功能 |
|---|---|
| **Edit** | 變更名稱、描述、順序、價格、啟用狀態與可見性。 |
| **On/Off** | **Off**：客戶無法購買；執行中的虛擬機器不受影響。 |
| **Hide / Show** | 隱藏的方案不會顯示在目錄中，但現有虛擬機器仍會保留該方案，且管理員可以指派它。 |
| **Clone** | 在同一個區域中建立一個具有新來源、大小或價格的新方案，並可選擇隱藏舊方案。若要從 CloudStack 和 Proxmox 銷售相同的組態，請複製它並選擇另一個來源。 |
| **Move up/down** | 變更順序。 |
| **Delete** | 將方案從銷售清單及表格中移除。已使用該方案的虛擬機器將繼續保留。 |

::: warning 使用中的方案已被鎖定
當方案已有虛擬機器使用時，其**zone, offering, CPU, RAM, disk and source**將被鎖定，以避免執行中的虛擬機器遭到靜默變更。請使用 **Clone** 來建立新組態；舊方案會保留其原有的虛擬機器。
:::

## 驗證 {#verify}

1. 該方案會顯示在表格中，並帶有預期的每小時與每月價格。
2. 在客戶 portal 中開始建立訂單：區域會提供該方案，且週期價格與 **Cycle** 標籤頁相符。
3. 下一個測試訂單，檢查錢包扣款是否與顯示的價格相符，然後刪除該虛擬機器。

## 限制與注意事項 {#limits-and-notes}

- 一個方案僅屬於**一個**區域和**一個**來源。
- 價格以 µ$/小時儲存；顯示的 VND 價格是由**VND rounding step**（請參閱貨幣頁面）推導並四捨五入計算得出。錢包始終以 USD 計價。
- 經銷商可獲得從定價推導出的批發價與零售價；變更現有方案的價格時，不會將自訂的經銷商價格複製到您已變更組態的複製方案中。
- 自訂方案的最小、最大及遞增限制會與 CloudStack 自身的限制進行檢查；若磁碟最大值超過 CloudStack 的 `storage.max.volume.size`，將導致部署失敗並進行退款。

## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| 「Plan name required」/「Service offering required」（需要方案名稱 / 需要服務方案） | 缺少欄位 | 填寫名稱；針對CloudStack請選擇一個方案。 |
| 「CPU/RAM/磁碟必須 > 0」 | 大小為空或為零 | 請輸入全部三項。 |
| "無效的價格（µ$/hr必須在1到100,000,000之間）" | 價格超出範圍 | 請檢查單位與金額。 |
| "變更價格需要填寫原因" | 編輯時原因為空 | 請輸入原因（3個字元以上）。 |
| "方案 "X" 為4c/8192，但計畫指定2c/4096 - CloudStack將依方案進行佈建。是否儲存？" | 計畫的數值與方案不符 | 使其相符，或確認保留CloudStack的大小。 |
| "無法從CloudStack取得方案" | 連線中斷或金鑰權限不足 | 請參閱 [CloudStack](https://nexcmp.com/zh-tw/docs/infrastructure/cloudstack/)。 |
| "範本在CloudStack上尚未就緒 - 部署將會失敗。是否仍要啟用？" | 您啟用了尚未完成的範本 | 請等待範本就緒。 |
| 計畫無法編輯（「已有VM - 已鎖定」） | 有VM正在使用此計畫 | 請予以複製。 |
| 客戶看不到此計畫 | 已關閉、隱藏或區域尚未就緒 | 檢查 **Active**、**Visibility** 及區域標籤。請參閱 [Zones](https://nexcmp.com/zh-tw/docs/infrastructure/zones/)。 |
| "請至少選擇1個計費週期" | 自訂計畫未勾選任何週期 | 請勾選至少一項。 |
| "組合折扣必須介於0–50%" | 超出範圍 | 請使用0到50。 |
| 缺少VND價格選項 | 尚無匯率 | 請先更新匯率。 |


---

<!-- source: https://nexcmp.com/zh-tw/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%時警告客戶，並在超過配額時根據您的**超量政策**採取行動。客戶可以從其錢包購買額外TB的**附加元件**；您也可以免費授與附加元件。

| 服務 | 配額 |
|---|---|
| 虛擬機器 | 每個VM每月（預設2048 GB，即2 TB） |
| Kubernetes | VM配額乘以工作節點數量 |
| Object Storage | 每位客戶每月下載流量（預設100 GB）；超出部分適用正常的隨需付費價格 |
| VPN | 保留其計畫的配額；請在VPN頁面上升級頻寬 |
| 私有雲 | **不計流量** |

## 需求 {#requirements}

| 項目 | 需求 |
|---|---|
| 模組 | **Bandwidth** 預設為開啟。請至 License & updates 關閉以隱藏。 |
| 測量來源 | 使用預設來源時為 **CloudStack VM statistics**。請在 CloudStack 中保持啟用 VM 統計資料收集功能；預設保留 720 分鐘即已足夠。 |
| Proxmox VE | Proxmox VE 上的虛擬機器**不計費**。 |
| 匯率 | 加值服務價格以 VND 輸入。請參閱 [Currency and exchange rates](https://nexcmp.com/zh-tw/docs/catalog/currency-and-exchange-rates/)。 |
| 相依於 | [CloudStack](https://nexcmp.com/zh-tw/docs/infrastructure/cloudstack/) 用於 VM 與 Kubernetes 流量，[S3](https://nexcmp.com/zh-tw/docs/infrastructure/s3/) 用於儲存空間下載。 |

## 準備基礎設施 {#prepare-the-infrastructure}

只要已連線 CloudStack 即可，無需額外設定。NexCMP 每 5 分鐘以最多兩小時的時間範圍，透過單一呼叫讀取帳戶中所有 VM 的 `listVirtualMachinesUsageHistory`。每個樣本涵蓋一分鐘並會被**累加**。樣本會延遲三分鐘取得以確保資料已送達。超過 CloudStack 保留期限（約 12 小時）的資料間隙將被略過並記錄。

::: info 數字代表的意義
用量是根據每個 VM 的網路介面計算，因此包含 VM 之間的流量，不只限於對外網際網路流量。這可能會比邊界路由器計算的數值稍高。
:::

## 在 NexCMP 中連線 {#connect-in-nexcmp}

1. 開啟 **Services › Bandwidth › Quotas, pricing & policy**。
2. 設定數值並點擊 **Save**；系統會要求填寫原因並予以記錄。背景工作會在約 30 秒內套用變更。

   | 欄位 | 預設值 | 含意 |
   |---|---|---|
   | 啟用頻寬（客戶選單與購買加購項目） | on | 模組銷售端的開關。 |
   | VM、GB/月（Kubernetes = 此數值 × worker 數量） | 2048 | 每個 VM 每週期的配額。 |
   | S3，每位客戶每月下載 GB 數 | 100 | 超出部分適用一般的 S3 按量計費。 |
   | 配額方向（VM、Kubernetes） | 傳入 + 傳出 | 或 **Outbound only**。 |
   | +1 TB 價格 (VND) | 100,000 | 以報價匯率轉換為分。 |
   | 每次購買上限 (TB) | 50 | |
   | 超額政策 | suspend | **notify**、**throttle** 或 **suspend**（見下方）。 |
   | 強制實際停權生效日 | 移轉日期 + 24 小時 | 在此日期之前不會停權任何服務；僅會對客戶發出警告。 |
   | 限速速率 (Mbps) | | 僅限限速 (throttle) 使用。 |

      ![頻寬政策：預設額度、加購價格與超額政策](https://nexcmp.com/zh-tw/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**表格按天顯示當前週期。

![顯示收集器狀態與各服務使用量的頻寬摘要](https://nexcmp.com/zh-tw/docs/images/catalog/bandwidth-02-summary.webp)

若要為客戶保留空間，請對服務使用 **Grant**（免費贈送整TB的附加元件）。開啟 **Add-on** 查看購買與贈送歷史記錄，最新的在前，並附帶類型篩選器。

![顯示購買與免費贈送記錄的附加元件歷史記錄](https://nexcmp.com/zh-tw/docs/images/catalog/bandwidth-03-addons.webp)

### 客戶看到的內容 {#what-customers-see}

客戶入口網站會獲得一個 **Bandwidth** 選單，其中包含使用量、剩餘配額，以及從錢包扣款的 **buy +1 TB** 操作（最高可達您的單次購買上限）。附加元件在當前週期內有效。

## 驗證 {#verify}

1. **Summary** 上的收集器正在執行，且其游標每隔幾分鐘就會向前移動。
2. 帶有流量的虛擬機器在大約10到15分鐘後會顯示使用量。
3. 若要查看警報，請在**測試**安裝上將虛擬機器配額降低至幾GB並產生一些流量。請勿在生產環境中這樣做：此配額適用於每台虛擬機器。

## 限制與注意事項 {#limits-and-notes}

- 使用量按週期（一個月）計算。附加元件和配額適用於當前週期。
- "Enforce actual suspend from" 可防止您在首次啟用模組的當下就將客戶停權。
- 在此版本中，限速政策僅會發送通知。
- 更改配額會套用到所有網站，包含經銷商網站。經銷商的零售與批發附加元件價格遵循其折扣或加價。
- **Dedicated servers**的頻寬是另外一回事；請參閱 [Dedicated servers](https://nexcmp.com/zh-tw/docs/infrastructure/dedicated/)。

## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| 執行中的虛擬機器使用量保持為零 | 背景工作執行緒已停止、CloudStack已斷線，或虛擬機器統計資料已停用 | 檢查 `sudo nexcmp status` 且 **Test connection** 於 [CloudStack](https://nexcmp.com/zh-tw/docs/infrastructure/cloudstack/)；啟用 CloudStack 虛擬機器統計資料。 |
| 使用量資料有缺漏 | 超過了 CloudStack 的保留期限，或者背景工作執行緒離線超過約12小時 | 無法復原；該缺口已被記錄。 |
| 使用量比預期略高 | 包含虛擬機器之間的流量及其他介面流量 | 預期行為；請向客戶說明此事。 |
| 解鎖後，被停權的服務恢復時仍處於停權狀態 | 它仍然超出配額 | 授予附加元件或提高配額。 |
| 儘管政策設定為 **suspend**，但沒有任何項目被停權 | 停權起始日期是未來日期 | 將其設定為現在（生效時頁面會顯示 "ACTIVE"）。 |
| 「bw_over_policy 必須是 notify、throttle 或 suspend」 | 透過 API 發送了無效的政策 | 使用三個值之一。 |
| Proxmox 虛擬機器未顯示使用量 | 它們未被計費 | 預期行為。 |
| 客戶無法購買附加元件 | 頻寬功能已關閉，或錢包餘額為零 | 檢查開關與錢包。 |




---

<!-- source: https://nexcmp.com/zh-tw/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 金額；這並不會變更錢包餘額。部分服務接受以 VND 輸入價格，包括頻寬加購項目、S3、Private Cloud 以及保留 VND 計價的現有 Bare Metal 方案。透過 Sepay 進行的銀行轉帳則以 VND 支付。

匯率由**管理員發布**。系統不會自動重新整理，因此您儲存的匯率會維持原狀，直到您按下更新按鈕為止。

## 需求 {#requirements}

| 項目 | 需求 |
|---|---|
| 網際網路存取 | 控制面板伺服器必須能夠連線至`open.er-api.com`（用於USD/VND）與`api.frankfurter.dev`（用於其他貨幣），當您按下**Update exchange rates**時。 |
| 權限 | 由管理員進行變更；每次變更均需填寫原因。 |
| 相依於 | 無。[Plans](https://nexcmp.com/zh-tw/docs/catalog/plans/)、[Bandwidth](https://nexcmp.com/zh-tw/docs/catalog/bandwidth/)、[S3](https://nexcmp.com/zh-tw/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相同的依語言顯示規則。 |

儲存。客戶頁面會在約一分鐘內更新。


當網站遵循客戶的語言時：

| 語言 | 顯示貨幣 |
|---|---|
| 英文 | USD |
| 越南文 | VND |
| 中文（簡體 / 繁體） | CNY / TWD |
| 日文、韓文 | JPY、KRW |
| 法文、德文、西班牙文、義大利文 | EUR |
| 葡萄牙文、俄文 | BRL、RUB |
| 阿拉伯文、印地文 | SAR、INR |
| 印尼文、泰文 | IDR、THB |

未發布匯率的貨幣將不予提供：門市將會退回使用 USD。

### 2. 發布匯率 {#_2-publish-the-rates}

1. 開啟 **Finance › Payment channels › Exchange rates**。
2. 卡片 **Currency by language** 會列出 11 種顯示貨幣及其每美元匯率、資料來源 (Frankfurter) 以及上次更新時間。點擊 **Update exchange rates**。

   該按鈕會一次執行兩項操作：讀取公開市場的**USD/VND**匯率表，並讀取其他11種匯率。兩者皆通過檢查後才會儲存。若其中一項失敗，則不會進行任何變更並保留先前的匯率。


3. 資訊卡**Active exchange rate**會顯示生效中的USD/VND匯率、其來源標籤（公開市場或固定）、加成以及市場參考數據與其時間戳記。
4. 卡片 **Config**（以原因儲存）：

   | 欄位 | 含意 | Range |
   |---|---|---|
   | Margin (bp, 100 = 1 %) | 外加於市場參考匯率之上。有效匯率為參考匯率加上加成後無條件進位。 | 0 to 1000 |
   | 固定匯率（每USD兌VND，0 = 跟隨市場） | 由您自行設定的匯率。它將取代市場數據。 | 0 or 15,000 to 50,000 |
   | Jump threshold (bp) | 若新市場匯率與目前匯率的差異超過此數值，將會被**暫緩套用**，直到您確認為止。 | 50 to 2000 (default 500) |
   | VND rounding step | 對 VND 價格與銀行轉帳金額進行四捨五入。 | 1, 100, 1,000 (default) or 10,000 |

5. 若新市場匯率的波動幅度超過閾值，系統會顯示資訊卡**Pending exchange rate**且該匯率**不會被套用**。請對照您選擇的參考數據進行核對，然後點擊**Apply this rate**。

   市場匯率若超出每USD兌換15,000至50,000 VND的範圍，將視為不合理並予以拒絕。手動重新整理每5分鐘限請求一次，因此該按鈕可能會提示您稍候。

6. **Exchange rate history**表格列出每筆已抓取或已確認的匯率，包含時間、生效匯率、市場參考值、來源、是否已套用、操作人員以及備註（暫緩的匯率跳動會標記為**held**）。

## 匯率使用方式 {#how-a-rate-is-used}

| Place | Rule |
|---|---|
| Wallet and invoices | 美分。匯率絕不會改變餘額。 |
| 以VND輸入的虛擬機器方案 | 在儲存時依當前有效匯率換算**一次**，隨後以USD儲存。後續的匯率變動不會對這些虛擬機器方案重新定價。 |
| 透過 Sepay 進行銀行轉帳 | 客戶支付 `ceil(USD × rate)`，並向上取整至取整步階。在存在 USD/VND 匯率之前，Sepay 會被 **封鎖**。 |
| Bare Metal方案 | 新安裝直接使用USD。既有的VND方案會保留其計價單位，計費時需要匯率；請參閱[Dedicated servers](https://nexcmp.com/zh-tw/docs/infrastructure/dedicated/)。 |
| 其他以 VND 輸入的國際付款 | 四捨五入至最接近的分。 |
| 顯示於入口網站 | USD乘以公佈的顯示貨幣匯率，並針對語言進行格式化。 |

## 驗證 {#verify}

1. **Active exchange rate** 顯示帶有近期「已獲取」時間的 USD/VND 數值。
2. 網格 **Currency by language** 顯示非空白的匯率。
3. 在客戶入口網站中，將語言切換至越南語（網站幣別設為Auto）：價格會顯示為越南盾；切換至日語：顯示為日圓。若網站幣別設為USD，則僅顯示美元。
4. 在方案表單（Plans & pricing）上，**Enter price by** 清單提供 **VND / month** 選項。

## 限制與注意事項 {#limits-and-notes}

- 沒有自動重新整理。當您需要新匯率時請按下 **Update exchange rates**，如果匯率對您很重要，請設定提醒。
- USD/VND採用公開市場匯率；該匯率為參考匯率，而非銀行買入或賣出報價。其他顯示幣別來自Frankfurter；超過14天的日期或不完整的匯率表都會被拒絕。
- 幅度與固定匯率僅影響 USD/VND。其餘 11 種顯示貨幣不含幅度。
- 每個客戶語言對應一種貨幣。變更語言會重設為該語言的預設貨幣，除非客戶針對相同語言選用了 USD。
- 經銷商網站遵循相同的匯率。

## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| 「新匯率超出閾值偏差 — 已暫停，需要人工確認」 | 匯率跳動幅度大於閾值 | 請確認並點擊 **Apply this rate**，或變更閾值。 |
| 「伺服器拒絕新匯率」 | 市場數據超出15,000至50,000範圍或格式錯誤 | 請稍候再試，或設定固定匯率。 |
| 重新整理提示您稍候再試 | 更新過於頻繁 | 請稍候並重試。 |
| 「無法取得匯率：…」 | 面板伺服器無法連線至匯率服務 | 請允許外向 HTTPS 流量並重試。 |
| **Sepay blocked** 標籤 | 尚未發布 USD/VND 匯率 | 請點擊 **Update exchange rates** 或設定固定匯率。 |
| 入口網站中缺少某種貨幣 | 缺少其匯率 | 請點擊 **Update exchange rates**。 |
| 客戶僅能看到 USD 價格 | 網站貨幣為 USD，或缺少匯率 | 將**Site currency**設為Auto並發布匯率。 |
| 「Fx 匯率表不完整；保留先前的匯率」 | Frankfurter 傳回的貨幣少於 11 種 | 請稍後重試；未做任何變更。 |
| 方案表單中缺少 VND 選項 | 無 USD/VND 匯率 | 請先發布匯率。 |




---

<!-- source: https://nexcmp.com/zh-tw/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 作為金鑰，因此重複的 Webhook 絕不會重複加值。您可以使用此頁面查看哪些管道已就緒、過去 30 天的效能表現，以及哪些管道需要處理。

## 需求 {#requirements}

| 項目 | 需求 |
|---|---|
| 公開 HTTPS 地址 | 閘道會將 Webhook 傳送至 `https://<domain>/v1/billing/...`，因此您的面板必須能夠透過有效 TLS 從網際網路存取（請參閱 [DNS and Cloudflare](https://nexcmp.com/zh-tw/docs/getting-started/dns-and-cloudflare/)）。 |
| 帳戶 | 您要使用的每個提供者的專屬帳戶。憑證會在後台輸入且絕不會再次顯示（僅顯示最後 4 個字元）。 |
| 管理員角色 | 管理員帳戶。 |
| 相依項目 | 無。越南銀行管道另需設定一個[匯率](https://nexcmp.com/zh-tw/docs/catalog/currency-and-exchange-rates/)。 |

## 支付管道 {#the-channels}

| 管道 | 客戶看到的畫面 | 設定位置 | 文章 |
|---|---|---|---|
| 信用卡（Stripe） | 信用卡表單、已儲存的信用卡 | Payment channels › Stripe | [Stripe](https://nexcmp.com/zh-tw/docs/billing/stripe/) |
| Apple Pay、Google Pay、Link | 錢包按鈕（Stripe Express Checkout） | Stripe 與網域註冊 | [Stripe](https://nexcmp.com/zh-tw/docs/billing/stripe/#apple-pay-google-pay-and-link) |
| Alipay | 重新導向至 Alipay（由 Stripe 以 JPY 計費） | Stripe 與手續費和額度 | [Stripe](https://nexcmp.com/zh-tw/docs/billing/stripe/#alipay) |
| PayPal | PayPal 按鈕、已儲存的 PayPal 帳號 | Payment channels › PayPal | [PayPal](https://nexcmp.com/zh-tw/docs/billing/paypal/) |
| USDT | 存款地址與確切金額 | Payment channels › USDT | [USDT](https://nexcmp.com/zh-tw/docs/billing/usdt/) |
| 越南銀行轉帳 | QR 碼與轉帳明細（僅限越南語介面） | Payment channels › VN bank transfer | [Bank transfer (Vietnam)](https://nexcmp.com/zh-tw/docs/billing/bank-transfer-vn/) |

## 準備基礎設施 {#prepare-the-infrastructure}

不需要。所有設定皆於管理後台完成，伺服器端無需安裝任何東西。

## 在 NexCMP 中連線 {#connect-in-nexcmp}

1. 開啟 **Finance › Payment channels**（`/payments`）。總覽表格會列出每個管道及其狀態。
2. 開啟該管道的分頁（**Stripe**、**PayPal**、**USDT**、**VN bank transfer**）並參閱對應文章。每個分頁底部均設有 **Save** 按鈕，若適用則另有 **Test** 按鈕。
3. 開啟 **Fees & limits**（`/payments/fees`），尋找 **Payment gateways & fees (wallet top-up)** 卡片，透過開關啟用該管道，然後按一下 **Save channels & fees**。

![列出閘道器及其已啟用、已設定和 30 天統計數據的付款管道概覽](https://nexcmp.com/zh-tw/docs/images/billing/payment-channels-01-overview.webp)

![帶有通道開關與手續費欄位的費率與限制頁面](https://nexcmp.com/zh-tw/docs/images/billing/payment-channels-02-fees.webp)

### 開關與手續費（Fees & limits） {#switches-and-fees-fees-limits}

| 設定 | 預設值 | 含意 |
|---|---|---|
| 信用卡（Stripe） | 開啟 | 存款畫面上的信用卡表單。在 Stripe 取得密鑰前會保持隱藏。 |
| Apple Pay、Google Pay、Link | 開啟 | 錢包按鈕。僅會在網域於 Stripe 完成驗證後顯示。 |
| Alipay | 關閉 | 需要在 Stripe Dashboard 中啟用 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/zh-tw/docs/billing/minimum-top-up/)。
:::

## 驗證 {#verify}

1. 在總覽表中，該通道會顯示 **Enabled** 與 **Configured**；**Last test** 欄位會在您點擊該通道分頁上的 **Test** 後填入。
2. 以測試客戶身分登入入口網站，並前往**Billing › Deposit**。該支付管道的按鈕已顯示。
3. 進行小額付款（測試卡或沙盒帳戶請參閱該通道的說明文章）。餘額隨之增加，畫面上會出現 **Top-up received** 通知，且該筆付款會列在 **Finance › Billing › Top-ups**（`/billing/deposits`）中。

## 限制與注意事項 {#limits-notes}

- **總覽欄位：** *30 days*（付款次數、成功數、失敗數與總金額）、*Stuck 24h*（超過一天仍處於暫挂狀態的付款）以及 *Unmatched*（已入帳但找不到相符訂單的 USDT 或銀行轉帳）。KPI 列新增了 30 天總金額、異常通道數量（已啟用但未設定，或有暫挂付款）以及未匹配總數。
- **Webhook 事件** 列於 **Payment channels › Gateway events**（`/payments/events`）下方。Stripe 有專屬分頁；PayPal 與 USDT 共用一個。失敗的事件可以重新發送 — 錢包帳本具備冪等性，因此重新發送絕不會重複入帳。
- **Resellers** 可以擁有自己的 Stripe、PayPal、USDT 與銀行頻道。他們的資料列也會顯示在這裡，而標頭中的網站選擇器會進行篩選。請參閱 [Resellers](https://nexcmp.com/zh-tw/docs/customers/resellers/)。
- **退款：** Stripe 與 PayPal 付款可直接從付款清單中退款；USDT 付款無法退款至來源（伺服器回應 `usdt_no_refund`）。
- **維護模式** 仍會接收閘道 Webhook，因此在維護開始前一刻進行的付款不會遺失。

## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| 客戶的存款畫面上找不到通道 | 已關閉、未設定，或（越南銀行）介面不是越南文 | 檢查 **Fees & limits** 與通道分頁；請參閱 [Bank transfer (Vietnam)](https://nexcmp.com/zh-tw/docs/billing/bank-transfer-vn/)。 |
| KPI **Faulty channels** 大於 0 | 通道已啟用但沒有憑證，或付款暫挂超過 24 小時 | 開啟該資料列並點擊 **Configure**；若遇到卡住的付款，請開啟 **Gateway events** 並重新發送。 |
| 客戶已付款但餘額未變更 | Webhook 未送達 | 檢查通道分頁上的 Webhook URL，然後在 **Gateway events** 中重新發送事件。 |
| 伺服器回應 `method_disabled` | 開關已關閉 | 在 **Fees & limits** 中將其開啟並儲存。 |
| USDT 開關呈灰色停用狀態 | 存款地址未驗證 | 點擊 USDT 分頁上的 **Test & verify address**。 |


---

<!-- source: https://nexcmp.com/zh-tw/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/zh-tw/docs/billing/auto-top-up/)。將其作為國際客戶的主要管道。

## 需求 {#requirements}

| 項目 | 需求 |
|---|---|
| Stripe帳號 | 能夠以**USD**接受付款的Stripe帳號。Alipay以JPY計費，必須由Stripe為您的帳號啟用。 |
| 金鑰 | 密鑰（`sk_live_...`或`sk_test_...`）與發布金鑰（`pk_live_...`或`pk_test_...`）。表單僅接受帶有這些前綴的金鑰。 |
| 網路 | 您的控制台必須能夠從網際網路透過HTTPS存取（Stripe會呼叫Webhook），並且必須能夠透過連接埠443連線至`api.stripe.com`。 |
| 網域（僅限錢包） | 客戶端網域必須提供`/.well-known/apple-developer-merchantid-domain-association`服務——NexCMP會為您處理此事。 |
| 相依項目 | 無。 |

::: info 共用Stripe帳號
NexCMP僅處理自身建立之付款的Webhook事件，因此您可以使用同時服務其他應用程式的Stripe帳號。
:::

## 準備基礎設施 {#prepare-the-infrastructure}

在Stripe端：

1. 登入[Stripe Dashboard](https://dashboard.stripe.com)。切換**Test mode**的開關，以決定您是要進行測試執行還是正式上線。某一模式的金鑰在另一模式中永不適用。
2. 開啟**Developers › API keys**。複製**Publishable key**，並顯示並複製**Secret key**。請將密鑰保密。
3. （選用）開啟**Settings › Payment methods**並啟用**Alipay**（如果您想提供該選項）。
4. 您**不需要**手動建立Webhook——NexCMP可以為您建立（請參閱下方第5步）。如果您偏好手動建立，請在**Developers › Webhooks**中使用[Webhook](#webhook)中列出的URL與事件建立端點。

## 在 NexCMP 中連線 {#connect-in-nexcmp}

1. 開啟**Finance › Payment channels › Stripe**（`/payments/stripe`）。
2. 在**API keys**卡片中選擇**Mode**（`live`或`test`），貼上**Secret key**與**Publishable key**。
3. 點擊**Save**。金鑰會寫入伺服器上的設定檔，只有NexCMP服務帳號可以讀取。它們永遠不會被傳回瀏覽器；之後頁面僅顯示最後4個字元。
4. 點擊**Check**。對話框會回報連線狀況、模式、可用與待處理餘額、帳號ID、是否啟用收費、是否存在Webhook以及Alipay是否可用。紅線代表該部分需要注意。
5. 在**Webhook**卡片中點擊**Create webhook**並確認。NexCMP會要求Stripe建立包含所有必要事件的端點，並自動填入**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/zh-tw/docs/billing/payment-channels/#switches-and-fees-fees-limits)。

![填入範例數值的Stripe頁面，包含模式、密鑰與發布金鑰](https://nexcmp.com/zh-tw/docs/images/billing/stripe-01-keys.webp)


### Webhook {#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/zh-tw/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 (Stripe, JPY display)**中開啟**Fees & limits**。設定**Alipay fee %**、**Alipay fixed fee**、**¥/USD rate**（50–500）以及**FX spread %**（0–20）。請定期更新¥/USD匯率；當匯率超過7天未更新時，頁面會顯示警告。

## 驗證 {#verify}

1. 在測試模式下，以測試客戶身分登入入口網站，開啟**Billing**，按一下**Deposit**，選擇**Card**並使用Stripe測試卡`4242 4242 4242 4242`（任意未來日期、任意CVC）支付最低金額。
2. 餘額會在數秒內增加，且該筆付款會顯示於**Finance › Billing › Top-ups**中，狀態為*Completed*。
3. 前往**Payment channels › Gateway events › Stripe**：您應該會看到帶有處理時間的`checkout.session.completed`或`payment_intent.succeeded`。
4. 回到Stripe頁面，**24h events**大於0。

在正式上線之前，將**Mode**切換至`live`，貼上正式密鑰並再次按一下**Create webhook**（測試模式與正式模式的webhook是分開的）。

## 限制與注意事項 {#limits-notes}

- **金額與貨幣。** 電子錢包以USD計價。信用卡、錢包與Link付款以USD扣款；支付寶以JPY向客戶展示，並依您的匯率進行換算。
- **手續費。** Stripe的實際手續費不會自動回讀；您設定的手續費百分比決定了客戶看到的金額以及錢包入帳的金額。在*Fees & limits*中選擇**Customer pays top-up fee**以額外向客戶收取手續費。
- **已儲存的信用卡。** 當客戶勾選*Save card for auto top-up*時，信用卡會儲存在Stripe，而非您的伺服器上。請參閱[Saved payment methods](https://nexcmp.com/zh-tw/docs/billing/saved-payment-methods/)。
- **退款。**退款至信用卡為兩步驟流程：管理員先為已完成的付款建立退款申請（**Finance › Billing › Top-ups**，付款項目上的退款操作），接著在**Finance › Payouts › Card refunds**（`/billing/payouts`）底下核准。Alipay 退款為非同步處理；若退款失敗（`refund.failed`），暫扣金額將退回錢包。
- **爭議款。** 當 `charge.dispute.created` NexCMP 會凍結客戶帳戶、暫停其預付服務（不刪除任何資料）並發送管理員警報。若您勝訴（`charge.dispute.closed`），金額將會退回至錢包。
- **等待付款。** 若未收到 webhook，NexCMP 會自行針對在 Stripe 上保持待處理超過 10 分鐘的付款進行檢查並完成交易。超過 7 天的付款將被忽略。
- **Resellers** 可以連接他們自己的 Stripe 帳戶（webhook `https://<their-domain>/v1/billing/stripe/webhook/r/<id>`）；請參閱 [Resellers](https://nexcmp.com/zh-tw/docs/customers/resellers/)。

## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| 「Secret key必須以sk_live_/sk_test_開頭」 | 貼上了錯誤的金鑰 | 請從 **Developers › API keys** 貼上密鑰。 |
| 「密鑰與 live/test 模式不符」 | 模式與金鑰不符 | 使 **Mode** 與金鑰的前綴相符。 |
| 「Publishable key 必須以 pk_ 開頭」 | 金鑰錯誤 | 請使用可發布金鑰。 |
| 檢查顯示連線失敗 | 金鑰錯誤、金鑰遭撤銷，或伺服器無法連線至 `api.stripe.com` | 重新貼上金鑰；使用伺服器上的 `curl -I https://api.stripe.com` 進行測試。 |
| 紅色橫幅「Missing webhook_secret」 | 未儲存簽章密鑰 | 點擊 **Create webhook**，或是從 Stripe Dashboard 貼上 `whsec_...` 密鑰並點擊 **Save**。 |
| 已扣款但餘額未變更 | 未送達 Webhook 或簽章驗證失敗 | 檢查網址是否以 `/v1/billing/stripe/webhook` 結尾、密鑰是否與端點相符，並在 **Gateway events** 中重新執行事件。在 Stripe 中，開啟端點並查看傳遞嘗試（HTTP 400 代表簽章密鑰錯誤）。 |
| 「Create webhook」失敗 | 網址不是 HTTPS 或無法連線 | 請使用您的公開 `https://` 網域。 |
| Apple Pay 狀態未啟用 | 網域未驗證 | 在網域關聯檔案回應 200 後，再次點擊 **Register / verify domain**。 |
| 檢查對話框中無法使用 Alipay | 尚未在 Stripe 中啟用 | 請在 Stripe Dashboard 中啟用它，然後點擊 **Check**。 |
| 客戶未看到卡片表單 | **Card (Stripe)** 已關閉或沒有密鑰 | 請在 **Fees & limits** 中開啟並儲存金鑰。 |


---

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

# PayPal

> **後台位置：** Finance › Payment channels › PayPal (`/payments/paypal`)。開關與手續費位於 Finance › Payment channels › Fees & limits (`/payments/fees`)。

## 功能 {#what-it-does}

讓客戶能夠使用其 PayPal 餘額、銀行帳戶或保存在 PayPal 的卡片來加值 USD 錢包。客戶也可以讓 NexCMP 記住其 PayPal 帳戶以便進行 [自動加值](https://nexcmp.com/zh-tw/docs/billing/auto-top-up/)。對於偏好 PayPal 的客戶，可與 [Stripe](https://nexcmp.com/zh-tw/docs/billing/stripe/) 搭配使用。

## 需求 {#requirements}

| 項目 | 需求 |
|---|---|
| PayPal 帳戶 | 可接收 USD 的 PayPal **商務**帳戶。 |
| REST 應用程式 | PayPal 開發人員儀表板（**Apps & Credentials**）中的一個 REST 應用程式，可提供 **Client ID** 與 **Client secret**。請使用 **Sandbox** 標籤頁進行測試，**Live** 用於正式環境。 |
| 網路 | 必須能從網際網路透過 HTTPS 連線（PayPal 會呼叫 Webhook），且對外能連線至 `api-m.paypal.com`（正式）或 `api-m.sandbox.paypal.com`（沙箱），連接埠 443。 |
| 權限 | REST 應用程式需要退款和 Webhook 功能。**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** 來尋找或建立*個人*（買家）沙箱帳戶。
5. 您不需要自行建立 webhook；NexCMP 會透過 **Create webhook** 按鈕建立它。

## 在 NexCMP 中連線 {#connect-in-nexcmp}

1. 開啟 **Finance › Payment channels › PayPal** (`/payments/paypal`)。
2. 在 **API keys** 中，選擇 **Mode**：`live`（真實金錢，`api-m.paypal.com`）或 `sandbox`（`api-m.sandbox.paypal.com`）。
3. 貼上 **Client ID**（至少 20 個字元）與 **Client secret**。
4. 點擊 **Check**。它會測試您輸入的憑證（不需要儲存），並回報連線狀況、App ID、模式、是否具備退款與 webhooks 權限範圍，以及權杖的有效期限。
5. 點擊 **Save**。
6. 在 **Webhook** 卡片中確認 URL 為 `https://<your-domain>/v1/billing/paypal/webhook`（必須是 `https`），然後點擊 **Create webhook** 並確認。NexCMP 會要求 PayPal 建立或更新包含 11 個事件的 webhook，並儲存傳回的 **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/zh-tw/docs/images/billing/paypal-01-keys.webp)


### Webhook events {#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`。

每個 webhook 都會透過呼叫 PayPal 的簽章驗證 API 進行驗證，儲存一次並以冪等方式處理。NexCMP 絕不信任 webhook 內文中的金額：在將金額存入款項之前，它會從 PayPal 取得該筆請款資料。

## 驗證 {#verify}

1. 將**Mode**保持在`sandbox`。在入口網站中，前往**Billing › Deposit**，選擇**PayPal**，點擊**Continue on PayPal**（或 PayPal 按鈕），並使用 sandbox 買家帳號登入。
2. 核准付款。您將返回入口網站，餘額會增加，且該筆付款會顯示在 **Finance › Billing › Top-ups** 下方，狀態為 *Completed*。
3. 開啟 **Payment channels › Gateway events › PayPal & USDT**：將會列出 `PAYMENT.CAPTURE.COMPLETED` 事件。
4. 當一切運作正常時，將 **Mode** 切換為 `live`，輸入正式憑證，點擊 **Save**，然後再次點擊 **Create webhook**（沙盒與正式的 webhook 是分開的）。

## 限制與注意事項 {#limits-notes}

- **付款如何完成。** 訂單以 USD 建立；在客戶核准後，**伺服器**會進行請款（具備冪等請求 ID）並精確將錢包加值一次。如果客戶關閉瀏覽器，webhook 與每 10 分鐘執行一次的對帳作業將作為安全網。
- **待處理與放棄的訂單。** 訂單最多可保持開啟 12 小時。客戶最多可擁有 5 筆待處理訂單（伺服器會回應 `too_many_pending`，HTTP 429）。超過 24 小時仍未請款的訂單將被標記為失敗。
- **未設定 webhook。** 在儲存 Webhook ID 之前，面板會對每個 PayPal webhook 回應 HTTP 503。透過入口網站與 10 分鐘對帳所進行的請款仍會存入錢包，但 PayPal 透過 webhook 回報的任何事件（爭議、退款、延遲請款）都不會被套用——請點擊 **Create webhook**。
- **已儲存的 PayPal 帳戶。** 當客戶選擇儲存 PayPal（或完成首次儲存，這會啟用 [automatic top-up](https://nexcmp.com/zh-tw/docs/billing/auto-top-up/)）時，PayPal 會將付款權杖儲存在其保險庫中。NexCMP 僅保留識別碼與 PayPal 電子郵件。請參閱 [Saved payment methods](https://nexcmp.com/zh-tw/docs/billing/saved-payment-methods/)。
- **退款與爭議**的處理方式與 Stripe 類似：退款請求會在 **Finance › Payouts › Card refunds** 下方獲得核准；爭議會凍結客戶的帳戶並暫停其預付服務，直到您解決為止。
- **手續費。** PayPal 的手續費不會被讀回；您設定的百分比與固定手續費決定了客戶看到的金額以及存入的金額。實際費率取決於您的國家（表單提示越南為 4.4%、美國為 3.49%）。

## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| 「Client ID太短」 | 貼上的字元少於 20 個 | 複製完整的 Client ID。 |
| 「Webhook URL 必須使用 https」 | 輸入的 URL 包含 `http://` | 請使用您的公開 `https://` 網域。 |
| 檢查回報連線錯誤 | 模式錯誤（沙盒環境使用正式密鑰或反之）、密鑰錯誤、無對外連線能力 | 將 **Mode** 與密鑰類型相符；從伺服器測試 `curl -I https://api-m.paypal.com`。 |
| 範圍退款 / webhooks 顯示「no」 | REST 應用程式缺少功能 | 在 PayPal Developer Dashboard 的應用程式中啟用功能。 |
| 橫幅「PayPal key set, NO webhook」 | 缺少 Webhook ID | 點擊 **Create webhook**。 |
| 檢查中出現 "Webhook not found" | Webhook 已在 PayPal 刪除或屬於其他應用程式 | 再次點擊 **Create webhook**。 |
| 客戶收到 PayPal 拒絕付款的訊息 | PayPal 拒絕該資金來源 | 請客戶選擇其他付款來源。 |
| 客戶看到 "Too many pending requests" | 5 個未結訂單 | 等待它們過期或完成它們。 |
| 缺少 PayPal 按鈕 | PayPal 在 **Fees & limits** 中關閉或未設定 | 將其開啟並儲存憑證。 |


---

<!-- source: https://nexcmp.com/zh-tw/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 發送到**您的 Binance 存款地址**；NexCMP 透過**唯讀**的 Binance API 金鑰讀取存款歷史紀錄，並在存款符合未結請求時將金額存入錢包。除了 Binance 收取的費用之外，您無需支付任何付款處理商費用，且 NexCMP 絕不會持有任何私鑰。

## 需求 {#requirements}

| 項目 | 需求 |
|---|---|
| Binance 帳號 | 已驗證且在您選擇的網路上啟用 USDT 存款功能的 Binance 帳號。 |
| API 金鑰 | 僅啟用 **Enable Reading** 的 Binance API 金鑰。啟用提款（Withdrawals）、內部轉帳（Internal Transfer）與現貨/保證金交易（Spot/Margin Trading）必須**關閉**。 |
| IP 限制 | 強烈建議：將金鑰限制為伺服器的對外 IP（**Test & verify address** 對話方塊會顯示該 IP）。 |
| 網路 | 連往 `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. 在 Binance 中開啟 **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 個十六進位字元、SOL 則為 base58）。
4. 點擊 **Save**。變更地址或網路會重設驗證並暫停該管道，直到你再次驗證為止；頁面會要求你確認。
5. 點擊 **Test & verify address**。（未儲存的變更將被拒絕 — 檢查會在已儲存的設定上執行。）對話方塊會顯示：
   - 金鑰權限（讀取、提領、內部轉帳、交易、IP 限制）— 危險權限會顯示紅色警告；
   - 伺服器的對外 IP（需輸入至 Binance 中）；
   - 網路（存款開放或關閉、所需的確認數、小額餘幣 dust）；
   - Binance 針對該網路發出的地址，以及它是否與你的**相符**。
6. 當地址相符時，NexCMP 會記錄驗證時間。唯有如此，你才能開啟 **Fees & limits**、啟用 **USDT (Binance)**、檢查 **USDT fee %**（預設為 1）與 **USDT request expires after (mins)**（5–180，預設為 30），然後點擊 **Save channels & fees**。



## 付款是如何對應的 {#how-a-payment-is-matched}

1. 客戶在 **Billing › Deposit › USDT** 中輸入金額並點擊 **Get deposit address**。
2. NexCMP 會建立請求並顯示地址、網路以及帶有六位小數的**精確金額** — 例如 `19.173742`。最後四位小數是隨機 nonce，使該金額對該請求而言是獨一無二的。
3. 客戶必須在該網路上發送**精確的**金額。金額不符（四捨五入金額、錯誤網路）的付款無法自動指派。
4. NexCMP 每 60 秒會讀取過去 24 小時的 Binance 存款。相符的存款會將請求移至 *confirming* 狀態，一旦 Binance 達到所需的確認數，就會將款項存入錢包。只要確認仍在進行中，有看到資金的請求絕不會過期。
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** 可以使用他們自己的 Binance 帳戶；請參閱 [Resellers](https://nexcmp.com/zh-tw/docs/customers/resellers/)。
- **如果您與其他系統共用 Binance 帳戶**，請為每個系統配置不同的網路，確保兩個輪詢器不會看到相同的存款。

### 未匹配的存款 {#unmatched-deposits}

與任何請求皆不符的存款（金額錯誤、網路錯誤、請求已過期）會產生 `deposit.unmatched` 事件與管理員警示。請開啟 **Payment channels › Gateway events › PayPal & USDT**、尋找該事件、檢查 Binance 上的交易並點擊指派動作以將款項入帳至正確的客戶。此後，USDT 頁面與通道總覽上的 **Unmatched** 計數將降為 0。

## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| 「API key和secret必須同時輸入」 | 僅填寫了一個欄位 | 兩者皆須填寫。 |
| 「Address格式不符合network ...」 | 地址與所選網路不符 | 請從 Binance 重新複製相同網路的地址。 |
| 「未儲存的變更 — 請先Save再Test」 | 測試會執行於已儲存的設定 | 點擊 **Save**，然後進行測試。 |
| 警告 "key has Enable Withdrawals" | 權限過多 | 請在 Binance API 管理中將其移除。 |
| 警告 "key not restricted to IP" | `ipRestrict` 已關閉 | 請新增對話框中顯示的伺服器輸出 IP。 |
| 警告 "key lacks Enable Reading" | 缺少權限 | 請啟用「Enable Reading」。 |
| 警告 "Binance has deposits disabled for USDT on the network" | 網路已暫停 | 請選擇其他網路或稍候。 |
| 「DANGER：組態的address與Binance發行的address不同」 | 地址或網路錯誤 | 請從 Binance 重新複製該網路的地址。 |
| USDT 開關在「Fees & limits」中呈灰色 | 地址尚未驗證 | 執行 **Test & verify address** 直到相符為止。 |
| 客戶已付款但未入帳 | 金額遭四捨五入或網路錯誤 | 在「Gateway events」中尋找該事件並手動指派。 |
| 已偵測到存款但等待時間過長 | 確認次數尚不足 | 請耐心等候；確認期間請求並不會過期。 |


---

<!-- source: https://nexcmp.com/zh-tw/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) 會監控您的銀行帳戶並在款項到達時呼叫 Webhook，隨後 NexCMP 便會將款項存入錢包。若您的客戶位於越南，請使用此功能。

::: info 僅顯示於越南語介面
越南銀行選項僅在入口網站以**Vietnamese**顯示時才會提供給客戶。使用任何其他語言的客戶永遠不會看到它。
:::

## 需求 {#requirements}

| 項目 | 需求 |
|---|---|
| 銀行帳戶 | 連線至 [my.sepay.vn](https://my.sepay.vn) 之 Sepay 帳戶的越南銀行帳戶（或 Sepay 虛擬帳戶，**VA**）。 |
| Sepay | 已啟用 webhook 整合功能的 Sepay 帳戶。 |
| 匯率 | 必須存在 USD 對 VND 的匯率：請先至 **Exchange rates** 更新。若無匯率，通道將回應 `fx_unavailable` 且客戶無法發起轉帳。 |
| 網路 | 您的面板必須透過 HTTPS 存取，以便 Sepay 可以呼叫 `https://<your-domain>/v1/billing/sepay/webhook`。 |
| 相依項目 | [貨幣與匯率](https://nexcmp.com/zh-tw/docs/catalog/currency-and-exchange-rates/). |

## 準備基礎設施 {#prepare-the-infrastructure}

在 Sepay 端：

1. 在 [my.sepay.vn](https://my.sepay.vn) 連線您的銀行帳戶（或建立 VA）並確保交易會顯示。
2. **備註前綴** — 2 至 5 個大寫字母，例如 `PAY`。NexCMP 會將備註產生為前綴後接 8 個隨機數字（例如 `PAY48210937`）。前綴不得包含 `ORD`，且不應被存入相同帳戶的其他任何系統所使用。
3. 若您的 Sepay 帳戶使用*付款代碼結構*，請在那裡註冊相同的前綴以便 Sepay 識別備註。
4. 在 NexCMP 頁面提供您 URL 與金鑰後（如下方步驟 7），再建立 webhook。

## 在 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** 中填入：

   | 欄位 | 範例 | Rule |
   |---|---|---|
   | 銀行 | `VCB` Vietcombank | 從清單中選擇；BIN 會自動填入。 |
   | 帳號 | `0123456789` | 4–24 個數字或大寫字母。 |
   | 虛擬帳戶（VA — 選填） | | 若設定，客戶將轉帳至 VA 且 QR Code 會顯示它。 |
   | 戶名 | `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**；其僅用於對帳發生 webhook 遺失的轉帳。
5. 在 **Channel & limits** 中設定限制（括號內為預設值）：**Min / order**（10,000 VND）、**Max / order**（200,000,000 VND）、**Order expiry**（120 分鐘，15–1440）、**Max pending orders / account**（3，1–10）、**Reconcile every**（10 分鐘），以及選填的 **Allowed webhook IPs**（以逗號分隔；留空表示僅記錄 IP）。
6. 按一下 **Save**。一旦帳戶、名稱、前綴與金鑰有效，紅色的「Sepay not configured」橫幅便會消失。
7. 複製**Webhook URL to paste into my.sepay.vn**（顯示為`https://<your-domain>/v1/billing/sepay/webhook`），請使用**Copy**。在Sepay中開啟webhook整合，貼上該URL，選擇相同的驗證類型與金鑰，並啟用「money in」事件。
8. 按一下 **Test connection**。然後開啟 **Enable Sepay for clients (main site)** 與 **Save**。

![填入範例值的 VN bank transfer 頁面，包含收款帳戶、備註前綴與 webhook 驗證](https://nexcmp.com/zh-tw/docs/images/billing/bank-transfer-vn-01-config.webp)

![已開啟 Sepay 開關與預設限制的 Channel and limits 卡片](https://nexcmp.com/zh-tw/docs/images/billing/bank-transfer-vn-02-limits.webp)

### Webhook 安全性 {#webhook-security}

| 方法 | Sepay 必須傳送的內容 |
|---|---|
| HMAC-SHA256 | Header `X-SePay-Signature: sha256=<hex>`，計算自 `"<X-SePay-Timestamp>.<raw body>"`；時間戳記最多可能相差 300 秒。 |
| API 金鑰 | Header `Authorization: Apikey <key>`。 |

僅檢查標頭（絕不檢查內文或查詢字串），且比對過程採用常數時間。僅使用指向您已設定帳戶或虛擬帳戶 (VA) 的入金轉帳（`transferType = in`）。每筆 Sepay 交易僅會儲存一次，因此重試的 webhook 絕不會重複入帳。即使 NexCMP 故意忽略某筆交易，也會回傳 `200 {"success":true}`，且僅針對暫時性錯誤回傳 HTTP 5xx 以促使 Sepay 重試。

## 客戶如何付款 {#how-the-customer-pays}

1. 在 **Billing › Deposit**（越南語介面）中，客戶選擇越南銀行轉帳選項與金額，然後點擊建立轉帳按鈕。
2. NexCMP 會以儲存的匯率（包含您在 **Exchange rates** 中設定的利潤率與捨入步驟）將 USD 金額進行換算，並將 **VND 金額向上捨入**至捨入級距。
3. 客戶會看到一個包含帳號、銀行、金額與備註的 QR 碼（VietQR，於本地產生）。
4. 轉帳完成後，Sepay 會呼叫 webhook，NexCMP 會將 `floor(VND received × 100 / rate)` 美分入帳。匯率在建立訂單時即已鎖定；若款項在訂單過期後才到達，將會採用鎖定匯率與當下匯率中較高者。
5. 訂單會在 **Order expiry** 後過期；對帳作業每 **Reconcile every** 分鐘執行一次作為安全網（需要 userapi token）。

## 驗證 {#verify}

1. 以客戶身分在越南語介面上建立測試訂單。檢查金額、帳號與備註是否正確。
2. 以正確的備註轉帳允許的最低金額。
3. 在一分鐘內，入口網站會顯示存款已完成且錢包餘額增加；銀行頁面上的 **State** 卡片會顯示最後的 webhook 時間。
4. 開啟 **Finance › Billing › Top-ups** 並檢查付款是否已列出收到的 VND 金額。

## 限制與注意事項 {#limits-notes}

- **最低金額。** 客戶看到的 VND 最低金額為 **Min / order** 與 [minimum top-up](https://nexcmp.com/zh-tw/docs/billing/minimum-top-up/) 之 VND 價值兩者中的較大者。
- **待處理訂單。** 每個客戶最多只能有 **Max pending orders / account** 個未結訂單（預設為 3 個）。
- **相同備註兩次。** 使用相同備註轉帳兩次會以當下匯率建立第二筆已完成的付款。
- **無法自動退款**至銀行帳戶。
- **手續費。** 該通道在 **Fees & limits** 中沒有固定手續費項目；匯率利潤率是唯一的調整項。
- **Resellers**可設定自己的帳戶；其webhook URL以`/v1/billing/sepay/webhook/r/<id>`結尾。

### Unmatched transfers {#unmatched-transfers}

進入帳戶但沒有帶有效備註的款項會顯示在頁面底部的 **Unmatched transactions** 中（可篩選 *All channel owners* 或 *Master*）。與客戶確認銀行參考編號後，點擊 **Assign** 並選擇該帳戶。錢包將以當前匯率入帳。

## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| 橫幅「Sepay not configured」 | 銀行、帳戶、戶名、前綴或金鑰遺失或無效 | 完成 **Receiving account** 和 **Webhook authentication** 卡片。 |
| 橫幅「USD/VND rate blocked」（`fx_unavailable`） | 未儲存匯率 | 前往**Exchange rates › Update exchange rates**。 |
| `prefix: 2–5 capital letters, no ORD` | Prefix invalid | 使用 2–5 個大寫字母且不含 `ORD`。 |
| `account_name` error | Accents or lowercase | 使用未帶變音符號的大寫字母、數字、空格、點或連字號。 |
| `webhook_secret: 8–200 characters` | Key too short | 使用至少 8 個可列印字元。 |
| 客戶無法看到此選項 | 不在越南文介面、已關閉或無費率 | 請檢查語言、開關與費率。 |
| 客戶已付款但未入帳 | Webhook未送達、備註已更改、金額錯誤 | 請檢查Sepay的Webhook記錄；若備註錯誤，轉帳將會位於**Unmatched transactions**中。 |
| Webhook傳回401或403 | 驗證方法或金鑰不符 | 請在Sepay與NexCMP中使用相同的方法與金鑰。 |
| 客戶看到 "Too many pending requests" | 已達到待處理訂單上限 | 請完成或等待其過期。 |




---

<!-- source: https://nexcmp.com/zh-tw/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/zh-tw/docs/images/billing/minimum-top-up-01-limits.webp)

| 設定 | 預設值 | 允許範圍 | Rule |
|---|---|---|---|
| Min top-up (USD) | $10.00 | $0 至 $10,000 | 必須小於或等於最大值。 |
| 每筆交易最高加值金額 (USD) | $5,000.00 | $1 至 $1,000,000 | 必須至少等於最小值。 |

數值以分（cents）為單位儲存（`min_topup_cents`，`max_topup_cents`）。

## 限制適用範圍 {#where-the-limits-apply}

| Place | 行為 |
|---|---|
| 信用卡、Apple/Google Pay、Link、Alipay、PayPal、USDT | 伺服器會拒絕範圍外的金額。介面會顯示「Enter an amount between {min} and {max}」。 |
| 越南銀行轉帳 | VND金額必須在Sepay限制內，**且**其USD價值（錢包收到的金額）必須在最小與最大值之間。介面會顯示兩個VND最小值中較大的一個。請參閱 [Bank transfer (Vietnam)](https://nexcmp.com/zh-tw/docs/billing/bank-transfer-vn/)。 |
| [自動加值](https://nexcmp.com/zh-tw/docs/billing/auto-top-up/) | 每筆自動扣款皆會介於最小值與最大值之間。在固定模式下，客戶的金額必須介於最小值與$1,000之間。 |
| 加值代碼（[Vouchers](https://nexcmp.com/zh-tw/docs/billing/promotions/)） | 不受影響。 |
| 管理員加值／扣款 | 不受影響。 |
| 經銷商錢包加值 | Resellers › Defaults 底下的獨立最低金額（`rs_topup_min_cents`，預設 $20）。 |

## 相關下限 {#related-floors}

最低加值並非唯一的餘額規則。這些項目位於 **Services › Virtual Machines › Policy** (`/vm/policy`) 中：

| Rule | 預設值 | 含意 |
|---|---|---|
| 最低餘額（`min_balance_cents`） | $5.00 | 客戶建立虛擬機器所需的最低錢包餘額。 |
| 配額 | 關閉 | 當啟用**配額**時，建立虛擬機器還需要有足夠支付該虛擬機器一段時數的餘額。請參閱 [Quotas](https://nexcmp.com/zh-tw/docs/billing/quotas/)。 |

## 驗證 {#verify}

1. 在客戶入口網站中開啟 **Billing › Deposit** 並輸入一個略低於您最低金額的數額。付款按鈕將會停用並顯示範圍訊息。
2. 輸入最低金額並確認付款開始。

## 限制與注意事項 {#limits-notes}

- 變更僅適用於新的付款。已建立的訂單將保留其建立時的金額。
- 面向客戶的提示（「最低 $10.00，最高 $5,000.00」）與快速金額按鈕將自動遵循新的限制。
- 如果您顯示 VND（**Exchange rates** 頁面），最低金額將按儲存的匯率進行換算以便顯示；錢包與限制仍然維持以 USD 計價。

## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| 「最低儲值金額必須小於或等於最高金額」 | 數值交叉重疊 | 降低最低金額或提高最高金額。 |
| 客戶無法透過越南銀行轉帳支付小額款項 | Sepay VND 最低金額或 USD 最低金額較高 | 降低銀行頁面上的 **Min / order** 或 USD 最低金額。 |
| 進行加值時發生伺服器錯誤 `invalid_argument` | 金額超出範圍 | 請輸入顯示範圍內的金額。 |


---

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

# 已儲存的付款方式 {#saved-payment-methods}

> **Where in the portal:** Billing › Settings（`/billing?settings=1`）。**Where in the admin:** Customers › List › a customer › Overview（`/customers/<id>`），卡片 **Payment**，會顯示儲存的付款方式以及自動加值紀錄。

## 功能 {#what-it-does}

已儲存的付款方式可讓 NexCMP 在客戶**不在線的情況下**向其收費，確保他們的服務不會因錢包用盡而停止。它僅由[automatic top-up](https://nexcmp.com/zh-tw/docs/billing/auto-top-up/)使用。共有兩種類型：儲存在 Stripe 的**信用卡**（包括透過 Apple Pay、Google Pay 或 Link 使用且 Stripe 傳回可重複使用卡的信用卡），以及儲存在 PayPal 金庫中的 **PayPal 帳戶**。

## 需求 {#requirements}

| 項目 | 需求 |
|---|---|
| 管道 | 已設定並啟用 [Stripe](https://nexcmp.com/zh-tw/docs/billing/stripe/) 與/或 [PayPal](https://nexcmp.com/zh-tw/docs/billing/paypal/)。 |
| 網站 | 主站點，或由平台代收付款的經銷商網站。使用自身 Stripe 帳戶的經銷商網站無法儲存信用卡。 |
| 客戶 | 使用該信用卡或 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/zh-tw/docs/billing/auto-top-up/) 將會自動啟用一次。畫面中不會有額外的勾選方塊或訊息。伺服器會記錄時間、客戶的 IP 位址以及付款方式作為憑證。
4. 下次加值時，存款畫面中的信用卡下拉選單將提供 **Saved card ...**，PayPal 則提供 **Saved PayPal ...**。


## 管理與移除 {#manage-and-remove}

1. 在入口網站中前往 **Billing** 並點擊 **Settings**。面板會顯示已儲存的付款方式（Stripe 信用卡與/或 PayPal）以及自動加值選項。
2. 若要移除卡片，請點擊 **Remove card** 並確認。Stripe 會卸載該卡片，且**自動加值將會關閉**。
3. 若要移除 PayPal，請點擊 **Remove saved PayPal** 並確認。


### 管理員檢視 {#admin-view}

在**Customers › List**中開啟客戶。**Payment**卡片（位於**Overview**分頁）會顯示已儲存的付款方式標籤（**Saved cards**）、用於自動扣款的閘道、已儲存的同意證明（時間、IP、方式），以及最近20次自動扣款嘗試的狀態與原因（**Auto top-up history**）。

## 驗證 {#verify}

1. 以測試客戶身分使用信用卡儲值最低金額。付款完成後，前往**Billing › Settings**：即可看到該張卡片以及處於開啟狀態的自動加值開關。
2. 開始另一次儲值：下拉選單會提供已儲存的卡片。
3. 在管理員介面中，客戶的 **Payment** 卡片會顯示相同的卡片標籤。

## 限制與注意事項 {#limits-notes}

- **Stripe Link 與電子錢包。** Link、Apple Pay 與 Google Pay 均為 Stripe 的功能。NexCMP 不會儲存任何 Link 相關資訊，僅保留 Stripe 回傳的卡片參考編號。
- **PayPal。** 客戶發起的每一筆 PayPal 儲值都需要手動點擊；已儲存的 PayPal 僅用於自動加值，絕不應用於其他功能。
- **經銷商網站。** 若經銷商使用自己的 Stripe 或 PayPal 帳號，則該網站將會隱藏已儲存的方法，且無法使用自動加值功能。
- **爭議款。** 任何付款的爭議款都會凍結帳戶並停止其預付服務；請參閱 [Stripe](https://nexcmp.com/zh-tw/docs/billing/stripe/)。
- **移除最後一個方法**會關閉自動加值；客戶仍可保留錢包餘額。
- **證明。** 同意記錄由伺服器寫入（客戶無法編輯），並保留供處理爭議時使用。

## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| 客戶未看到 Settings 按鈕或已儲存的卡片 | 網站使用經銷商擁有的付款管道，或是尚未進行卡片付款 | 透過平台管道進行卡片或 PayPal 儲值。 |
| 進行 Stripe 付款後找不到 "Saved card" | 付款方式使用了無法重複使用的管道（例如 Alipay） | 再次使用卡片付款。 |
| PayPal：「目前無法儲存此帳號」 | PayPal 未回傳 vault token | 繼續進行單次付款，或嘗試其他 PayPal 帳號。 |
| 移除卡片後自動加值停止 | 預期行為：移除卡片即會停用該功能 | 在下次儲值時儲存新方法。 |


---

<!-- source: https://nexcmp.com/zh-tw/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/zh-tw/docs/billing/saved-payment-methods/)扣款並存入錢包，以避免執行中的服務因資金不足而遭到暫停。背景作業會**每 5 分鐘**檢查所有啟用的客戶。

## 需求 {#requirements}

| 項目 | 需求 |
|---|---|
| 管道 | 已設定 [Stripe](https://nexcmp.com/zh-tw/docs/billing/stripe/) 及/或 [PayPal](https://nexcmp.com/zh-tw/docs/billing/paypal/)。 |
| 已儲存的方法 | 客戶擁有已儲存的卡片或 PayPal 帳號。 |
| 網站 | 主站，或是其 Stripe/PayPal 管道由平台代收的經銷商網站。 |
| 全域開關 | **Auto top-up enabled** 為開啟狀態（預設為開啟）。 |

## 運作原理 {#how-it-works}

在客戶進行**首次 Stripe 或 PayPal 加值**後，伺服器會儲存付款方式，並以 **By usage** 模式開啟自動加值功能——前提是該客戶從未自行設定過自動加值。存款畫面沒有額外的勾選方塊；伺服器會記錄時間、IP 位址與付款方式作為憑證。如果客戶後來關閉自動加值，系統將不會再自動重新開啟。

| 模式 | 觸發條件（當餘額低於...） | 扣款金額 |
|---|---|---|
| **By usage**（首次加值後預設） | 接下來 24 小時的服務執行成本（計時虛擬機器加上 24 小時內到期的預付續約），但絕不高於 **$5** | 四捨五入至整數美元的 24 小時成本，至少為[minimum top-up](https://nexcmp.com/zh-tw/docs/billing/minimum-top-up/)，至多為 maximum top-up 與每日上限 |
| **Fixed amount** | 客戶自訂的門檻（$1 至 $500） | 客戶自訂的金額（從 minimum top-up 到 $1,000，且大於門檻） |

在 **By usage** 模式下若無執行中的服務，則不會進行扣款。

與門檻進行比較的餘額為**錢包中的真實現金**。促銷代碼產生的服務點數會分開保存且不予計入（參閱 [Promotions](https://nexcmp.com/zh-tw/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)** 中設定：

   | 設定 | 預設值 | Range | 含意 |
   |---|---|---|---|
   | Auto top-up enabled | 開啟 | 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 頁面自動加值區段](https://nexcmp.com/zh-tw/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/zh-tw/docs/images/billing/auto-top-up-02-portal.webp)

## 驗證 {#verify}

1. 以測試客戶身分使用測試卡進行首次加值（[Stripe](https://nexcmp.com/zh-tw/docs/billing/stripe/#verify)）。前往**Billing › Settings**：自動加值已開啟。
2. 執行小型虛擬機器以產生用量，並將餘額降至門檻以下（例如透過 **Customers › customer › Credit / debit**）。
3. 大約 5 分鐘內就會完成扣款。在客戶的 **Overview › Payment** 卡片中，**Auto top-up history** 會顯示狀態為 *Done* 的嘗試紀錄，並會發送 *Top-up received* 通知。

## 限制與注意事項 {#limits-notes}

- **每次餘額下降執行一次扣款。** 扣款後，作業會等待，直到餘額回升至閾值以上或等待時間結束：成功後 1 小時、待處理扣款後 24 小時、系統錯誤後 30 分鐘。
- **每日限制。** 當達到任一每日限制時，將不會進行扣款，並會寫入一筆 *Daily limit reached* 記錄（每 6 小時最多一次）。
- **失敗。** 信用卡被拒、過期或餘額不足均視為信用卡失敗。系統將在 1 小時後、6 小時後以及 24 小時後重試任務。**連續 3 次信用卡失敗後，自動加值將被關閉**，並且會通知客戶 (*Auto top-up failed*)。需要客戶確認的付款（例如 3-D Secure）不計入失敗；系統會提示客戶進行確認。
- **無重複扣款。** 每筆扣款在低於閾值時以原子方式執行，並在金鑰閘道使用冪等性金鑰。
- **移除信用卡**會關閉自動加值。
- **經銷商。** 若經銷商使用自己的付款管道，客戶將無法啟用自動加值 (HTTP 403 `feature_disabled`)。

## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| 客戶無法開啟：「請使用信用卡或 PayPal 加值一次」 | 無儲存的付款方式 | 請先使用信用卡或 PayPal 進行一次加值。 |
| 錯誤 `no_card` (422) | 所選的付款閘道沒有儲存的付款方式 | 請選擇有付款方式的閘道，或儲存一個付款方式。 |
| 金額發生錯誤 `invalid_argument` | 固定模式超出允許的範圍 | 閾值 $1–$500，金額介於最低加值額與 $1,000 之間，且金額須大於閾值。 |
| 餘額偏低但未進行任何扣款 | 全域開關已關閉、依使用量模式下無運行中的服務、已達每日限制，或先前的扣款仍在等待中 | 請檢查開關、記錄與限制。 |
| 「連續 N 次嘗試失敗 — 自動加值在 3 次後關閉」 | 信用卡持續扣款失敗 | 客戶更換為新的存款信用卡。 |
| 狀態 *Needs your confirmation* | 銀行要求進行 3-D Secure 驗證 | 客戶手動完成一次正常加值。 |


---

<!-- source: https://nexcmp.com/zh-tw/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 中的每個金額均以美元美分儲存並記錄一次。核心概念：**錢包分類帳**是餘額的唯一真實來源；發票、加值付款與報表都是基於它所建立的檢視。分類帳是**僅供附加 (append-only)** 的 — 錯誤只能透過新增沖銷分錄來修正，絕不透過編輯歷史記錄來修改。

## 需求 {#requirements}

| 項目 | 需求 |
|---|---|
| 角色 | 管理員。 |
| 賣家詳細資料 | 在 **System › Settings › General** 的 **Seller & invoicing** 分頁 (`/settings?tab=seller`) 中的 **Seller details (printed on invoices)** 卡片，設定法定名稱、統一編號、地址、聯絡電子郵件及發票號碼前綴。 |
| 相依項目 | 用於資金流入的 [Payment channels](https://nexcmp.com/zh-tw/docs/billing/payment-channels/)。 |

## 組成元件 {#the-pieces}

| 後台分頁 | 清單內容 | 典型用途 |
|---|---|---|
| **Overview** | 今日與本月營收、依種類區分的總帳總計（存款、扣款、退款、調整、折價券）、依狀態區分的發票、待處理退款、捷徑、過去 30 天內每個服務的消費 | 每日檢查 |
| **Transactions** | 錢包總帳，每個異動一行 | 說明客戶的餘額 |
| **Invoices** | 發票，以及包含每個服務每次購買記錄的第二個檢視畫面 **Orders** | 尋找文件、重新寄送、標記為已付款 |
| **Top-ups** | 透過支付閘道收到的款項 | 檢查付款、進行退款 |
| **Payouts** | 信用卡退款、聯盟行銷分潤、經銷商提領 | 核准支出款項 |
| **Vouchers** | 加值代碼 | 參見 [Promotions](https://nexcmp.com/zh-tw/docs/billing/promotions/) |
| **Reports** | 依服務、依經銷商區分的營收 | 會計 |

### 交易（總帳） {#transactions-ledger}

欄位：時間、客戶、**種類**、服務、金額（帶正負號）、虛擬機器、參考編號、操作者、備註。篩選條件：種類、服務、客戶 ID、網站（當您有多個經銷商時）、日期範圍，以及虛擬機器連結。

| 類型 | 含意 |
|---|---|
| `deposit` | 來自支付閘道的加值 |
| `charge` | 為服務扣取的款項（訂單、續約、按小時計費等） |
| `refund` | 退回錢包的款項 |
| `adjust` | 管理員信用額度或借方，以及加值代碼（參考編號開頭為 `vch:`）——總覽將折價券顯示為獨立的一行 |

每一列都有一個參考編號，例如 `dep:stripe:<payment-id>`；相同的參考編號永遠不能寫入兩次，這就是為什麼重複的 Webhook 無法重複入帳。使用 **Customers › List › customer › Credit / debit** 來新增手動調整：原因為必填欄位，正數金額也會嘗試解鎖因資金不足而遭鎖定的虛擬機器，且該動作需要兩步驟確認。

![顯示錢包總帳列的 Transactions 標籤頁，包含種類、服務、金額與參考編號](https://nexcmp.com/zh-tw/docs/images/billing/invoices-and-ledger-01-ledger.webp)

### 發票 {#invoices}

當客戶購買或續約從錢包扣款的項目，或是進行加值時，系統會自動建立發票。編號格式如 `<prefix><YYYYMM>-<000001>`（例如 `NX202610-000042`）；經銷商網站使用其專屬的前綴與序號。當您變更前綴時，現有編號絕不會改變。

| 欄位 | 數值 |
|---|---|
| 類型 | 收據、續約、加值、手動、退款 |
| 狀態 | 未付、已付、逾期、已取消、已退款 |

列上的動作：

| 動作 | 效果 |
|---|---|
| **View** / **Print** | 開啟發票；客戶入口網站也可以列印或儲存為 PDF。 |
| **Mark paid**（僅限未付或逾期） | **在不動用錢包資金的情況下**將其標記為已付款——當客戶在 NexCMP 外部付款給您時使用。原因為必填欄位。對於續約發票，它也會延長並解鎖被鎖定的虛擬機器。 |
| **Cancel**（僅限未付或逾期） | 取消發票。原因為必填欄位。 |
| **Resend** | 再次以電子郵件寄送發票。 |

**建立手動發票**（分頁頂部的按鈕）：客戶 ID、1 至 50 行（說明、數量、單價）、選填的 VM ID、選填的到期天數（0 至 365，預設 7）、選填備註。建立時為未付款狀態；客戶可在 **Billing › Invoice History** 中檢視。

只要錢包有資金，服務的未付款發票將**自動從錢包結清**，因此客戶只需進行加值即可。


### 加值（付款） {#top-ups-payments}

每筆嘗試佔一行：時間、客戶、**閘道與付款方式**、類型（加值或自動加值）、狀態（待處理、已完成、失敗、已退款、有爭議、已取消）、客戶支付金額、手續費、實際入帳金額、閘道參考編號與完成時間。已完成的 Stripe 與 PayPal 付款提供 **Refund** 動作。使用「閘道事件」頁面檢視 Webhook（[Payment channels](https://nexcmp.com/zh-tw/docs/billing/payment-channels/)）。

### Payouts {#payouts}

三個子分頁：**Card refunds**（核准或拒絕退款請求；該請求由已完成的付款建立）、**Affiliate payouts**（佣金提領）與 **Reseller withdrawals**。所有決定皆會留下稽核記錄。

### Reports {#reports}

**Revenue**（30 天趨勢、按月統計、前幾大客戶）、**By service** 與 **By reseller**。

![顯示營收KPI與30天趨勢的「報表」頁籤](https://nexcmp.com/zh-tw/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/zh-tw/docs/catalog/currency-and-exchange-rates/)）。
- **退款至卡片**分為兩個步驟（先提出申請，再於Payouts中審核）；USDT與銀行轉帳無法退款至原金流來源。
- **所有操作皆會記錄稽核**於System › Logs › Admin actions中，並記錄您輸入的原因。
- **訂單與發票。**按小時計算的用量不會按小時開立發票；Orders檢視會將其按天數群組以便檢視。

## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| 客戶餘額異常 | 發生未預期的扣款、調整或優惠券 | 依客戶ID篩選**Transactions**並閱讀參照編號與備註。 |
| "發票已經付款" (409) | 對已付費的發票標記為已付 | 無需處理。 |
| 無法取消發票 | 僅能取消未付或逾期發票 | 已付發票請使用退款或調整項目。 |
| 發票缺少賣家資訊 | 尚未填寫 | 請在System › Settings › General › Seller & invoicing中填寫**Seller details**。 |
| 信用卡拒付 | 金額為零或超過 $100,000 | 請使用 1 分錢到 $100,000 之間的金額。 |
| 付款狀態長時間顯示 *Pending* | Webhook遺失 | 參見**Gateway events**並重新發送。 |


---

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

# 促銷代碼 {#promotions}

> **管理員位置：** Finance › Billing › Vouchers (`/billing/vouchers`)。**客戶端位置：** Billing › Redeem code (亦可在 Deposit 抽屜內)。

## 功能 {#what-it-does}

**加值代碼**（優惠券）是您提供給客戶的一次性密碼。根據建立方式，它可以：

| 類型 | 客戶獲得的內容 | 價值歸屬 |
|---|---|---|
| 適用所有服務的**Bonus credit** | 加入錢包的金額 | 錢包餘額。可用於任何項目。 |
| 適用指定服務的**Bonus credit** | 服務額度 | 只能用於支付這些服務的獨立額度。 |
| **Discount %** | 指定服務首筆訂單的百分比折扣 | 不進行額度入帳，折扣於結帳時套用。 |

適用於行銷活動、補償額度、合作夥伴優惠或首筆訂單折扣。

## 需求 {#requirements}

| 項目 | 需求 |
|---|---|
| 角色 | 管理員。 |
| 客戶 | 客戶必須登入客戶端（而非以訪客身分）才能兌換代碼。預設情況下，客戶必須已驗證電子郵件。 |
| VND 代碼 | 以 VND 建立的代碼在兌換時會根據儲存的匯率轉換為 USD（參見 [Currency and exchange rates](https://nexcmp.com/zh-tw/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 起。這也是每次兌換您可能承擔的最大損失。 |
   | 最低訂單金額 (USD) | `0` = 無。首筆訂單金額必須至少達到此數值。 |
   | 代碼數量 | 1 到 1,000 個隨機代碼。 |
   | 每個代碼使用次數 | 1至100,000。`1`表示每個代碼限一人使用；若為共用代碼請調高此數值。 |
   | 每個帳號最高使用次數 | 至少為1。若為折扣百分比，則必須為`1`。 |
   | 開始時間（選填）、有效期限 | 有效期限必須在今天之後且在開始時間之後，最多可設定2年後。 |
   | 代碼前綴（0–6個字元） | 僅限字母；若留空則使用網站的前綴。 |
   | 自訂代碼（僅限數量 = 1時） | 6至32個字元，包含A–Z與0–9。容易分享但也容易被猜到：請將使用次數保持在較低數值。 |
   | 要求已驗證的電子郵件 | 預設為開啟。 |
   | 內部備註、原因 | 原因為必填項目，且會記錄至稽核日誌中。 |

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}

- 此額度存放在**獨立帳戶**中，僅能用於支付所選服務的費用（新訂單、續約、按小時或按天計費、升級），且會在扣除錢包餘額**之前**優先扣抵。
- 此額度無法提領、轉移或兌換為現金，且會隨代碼一同到期。
- 帳目明細會顯示完整費用及相對應的折抵行，因此各服務的營收保持正確，而錢包僅會扣除客戶實際支付的金額。
- 這**不會**提升[quota](https://nexcmp.com/zh-tw/docs/billing/quotas/)級別，且會被[auto top-up](https://nexcmp.com/zh-tw/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**並確認。每個代碼每個帳號限用一次。

代碼與網站繫結：來自某個網站的代碼在另一個網站上「無效」，且不會提示它存在於其他地方。錯誤猜測會受到速率限制，在嘗試多次後，帳戶會被鎖定數分鐘（「暫時鎖定前剩餘嘗試次數」）。

## 追蹤與停止 {#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 的虛擬機器（月繳週期）：帳單會顯示折扣（最多 $5）。
4. 在該批次中，該代碼會顯示 1 次兌換記錄與實際折扣。

## 限制與注意事項 {#limits-notes}

- 代碼在建立時即繫結至 **audience** 與 **site**；之後無法移動。
- 經銷商可以在每月風險額度內向自己的客戶發行代碼；請參閱 [Resellers](https://nexcmp.com/zh-tw/docs/customers/resellers/)。
- 客戶側邊欄宣傳輪播圖(**Marketing › Promo slides**)為獨立功能，不提供任何折扣。
- 由於從未儲存明文代碼，因此遺失的批次無法復原：請將其停用並建立新批次。

## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| 「百分比代碼：每帳戶限用一次」（`percent_one_per_account`） | Discount % 的每帳戶最大使用次數大於 1 | 將其設定為 `1`。 |
| 表單顯示上限為必填欄位 | 沒有設定 Maximum discount cap 的 Discount % | 請輸入至少 $1.00。 |
| 找不到客戶 | 清單中的電子郵件或 ID 不存在 | 修正清單（錯誤訊息會指出未知的項目）。 |
| 客戶回報「無效代碼」 | 網站錯誤、已過期、已停用、已用完、非目標客戶，或電子郵件未驗證 | 檢查批次與客戶。 |
| 未使用額度 | 該費用屬於其他服務 | 額度僅可用於支付批次上所選擇的服務。 |
| 未套用折扣 | 訂單低於最低金額、為小時計費，或者該代碼是針對其他服務啟用的 | 下一筆符合條件的首筆訂單。 |
| 客戶被鎖定而無法兌換 | 錯誤嘗試次數過多 | 等待鎖定期滿。 |




---

<!-- source: https://nexcmp.com/zh-tw/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數量。分級即為您的固定方案。
- **服務配額**：IP、叢集、VPC、儲存空間GB等數量，透過存款金額驅動分為五個層級（L0至L4）。

系統會在扣款**前**檢查配額。超出限制的請求將遭到拒絕並回傳HTTP 403 `quota_exceeded`，同時顯示訊息告知客戶應加值多少金額。

## 需求 {#requirements}

| 項目 | 需求 |
|---|---|
| 角色 | 管理員。 |
| 切換開關 | **Enable quota** (`quota_enabled`) 預設為**關閉**狀態。在您開啟之前，下方所有設定皆不生效。 |
| 固定方案 | 至少有一個非自訂方案（參見[Plans](https://nexcmp.com/zh-tw/docs/catalog/plans/)）— 資源級別即為您的固定方案。若無任何方案，則僅適用 VM 數量規則。 |
| 相依項目 | 服務配額列僅存在於您安裝中啟用的產品（VPN、IPv6 proxy、Kubernetes、Private Cloud、Images、Object Storage、Dedicated）。 |

## 基準的計算方式 {#how-the-basis-is-calculated}

NexCMP 不僅看刷卡付款。**基準**為客戶的**已入帳錢包餘額**：閘道加值、管理員信用額度（**Credit / debit**）以及兌換的錢包折價券，全部透過錢包總帳計入一次。促銷代碼的訂單折扣與服務信用額度並非錢包資金，不予計入。客戶曾達到的最高基準會被**保留**（每個站台）— 消費或退款絕不會調降已解鎖的級別。

### VM 與 Kubernetes 資源 {#vm-and-kubernetes-resources}

1. 級別即為站台的固定方案，依執行 24 小時的成本排序。
2. 客戶處於 24 小時成本不高於其基準的最高級別。限制為該方案的 vCPU、RAM 與磁碟。甚至負擔不起最便宜方案的客戶，仍可獲得最便宜方案的資源。
3. 計入限制的使用量包含所有執行中的 VM（包含鎖定的 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. 檢查三個數字（皆可編輯）：

   | 欄位 | 預設值 | Range |
   |---|---|---|
   | 建立虛擬機器：餘額 ≥ N 小時 | 2 | 1 至 720 |
   | Max VMs at 24h tier | 2 | 1 至 100 |
   | 滿足 30 天門檻時的虛擬機器上限 | 10 | 1 至 1000（不得低於前一個欄位） |

4. 在 **Tier-based service quotas** 中編輯表格（下方）。
5. 點擊 **Save**。NexCMP 會要求輸入**原因**，該原因將與新舊值一同寫入稽核日誌。此變更適用於所有客戶。

![Quota 標籤頁包含啟用開關、虛擬機器限制與層級式服務配額表格](https://nexcmp.com/zh-tw/docs/images/billing/quotas-01-policy.webp)

### 服務配額表 {#service-quota-table}

此表格有五個級別。標題儲存格 **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 IPs | 2 | 10 | 30 | 100 | 500 |
| `proxy6.ips` | IPv6 proxy IPs | 500 | 2000 | 10000 | 50000 | -1 |
| `dedicated.servers` | Bare-metal servers | 1 | 2 | 5 | 20 | 50 |
| `s3.storage_gb` | Object Storage GB allocated | 2048 | 4096 | 10240 | 51200 | -1 |
| `k8s.clusters` | Kubernetes clusters | 1 | 2 | 5 | 10 | 30 |
| `k8s.workers` | Kubernetes worker nodes | 3 | 9 | 18 | 50 | 200 |
| `vpc.count` | Private Cloud networks | 1 | 2 | 5 | 10 | 30 |
| `images.gb` | 自訂映像檔儲存空間 GB | 50 | 100 | 200 | 500 | 2000 |

該表格也列出了幾個不屬於此版本的產品列，請保持原樣。關閉產品的鍵會被隱藏且絕不會被強制執行。數值必須為 `-1` 或在 `0` 與 `10,000,000` 之間。

服務配額遵循**資金基礎**（類似虛擬機器層級）：取達到的最高錢包餘額，而非卡片付款總額。代理商客戶使用相同的預設值，且代理商僅能檢視這些預設值。

## 個別客戶覆寫 {#per-customer-overrides}

1. 開啟**Customers › List**,然後點選該客戶。在**Overview**中找到卡片**Quota**。
2. **虛擬機器資源：**點擊 **Quota override** 並選擇以下其中一項
   - **依充值餘額（移除覆寫）** — 預設行為；
   - **無限制（包含虛擬機器數量）** — 移除此客戶的所有上限；
   - **方案層級** — 將資源上限固定至該方案；虛擬機器數量規則仍然適用。

   輸入原因。平台管理員可以設定任何層級；代理商設定的覆寫不得超過客戶的保留基礎。
3. **服務：**「*Service quotas*」底下的表格顯示每個鍵的 *In use*、有效限制及其 *Source*（層級或覆寫）。點擊列上的 **Edit**，輸入 **New quota**（`-1` = 無限制，留空 = 返回層級預設值）以及原因。

![顯示層級、資源使用量以及帶有覆寫的服務配額表格的客戶配額卡片](https://nexcmp.com/zh-tw/docs/images/billing/quotas-02-customer.webp)

每個覆寫都會連同管理員、原因以及變更前後的數值記錄在稽核日誌中。

## 客戶看到的畫面 {#what-the-customer-sees}

**Client › Quotas**（`/client/quotas`）顯示客戶的**目前層級**、已使用與總 vCPU、RAM、硬碟和虛擬機器數量（分為虛擬機器與 Kubernetes）、**合格錢包餘額**、**保留資源基礎**（消費時不會減少），以及升級至下一層級所需的充值金額。滑桿可讓他們選擇目標層級並直接前往存款畫面。**Service Quotas** 卡片列出每項服務的配額、已使用量、其層級（L0 至 L4）、升級至下一層級還需存款的金額，以及一個會開啟支援單草稿的 **Request increase** 按鈕。**Quota policy** 按鈕用以說明規則。

![顯示目前層級、資源使用量與服務配額的 Portal Quotas 頁面](https://nexcmp.com/zh-tw/docs/images/billing/quotas-03-portal.webp)

## 驗證 {#verify}

1. 啟用 **Enable quota** 並使用餘額為 $0 的全新測試客戶。
2. 嘗試建立大於您最便宜方案的虛擬機器。請求會被拒絕並顯示 `quota_exceeded` 以及訊息「Exceeds the resources of tier ... Top up $X more to unlock tier ...」。
3. 充值顯示的金額。層級會立即變更，且相同的請求將會成功。
4. 購買超過 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之前最多只能建立2台虛擬機器。啟用配額後，該規則即不再適用。
- **管理員建立的虛擬機器不會被封鎖。**
- **錯誤時會安全關閉。** 如果無法讀取額度狀態，請求將會遭到 `quota_unavailable` 拒絕，而不是放行。
- **API、CLI 與 MCP** 請求使用相同的處理常式，因此適用相同的限制。
- **促銷點數**不會提升層級（請參閱 [Promotions](https://nexcmp.com/zh-tw/docs/billing/promotions/)）。
- **層級門檻是以分為單位**，而非美元。

## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| `quota_exceeded`，原因 `resources` | 新的總 vCPU/RAM/磁碟超出層級 | 充值訊息中顯示的金額或設定覆寫。 |
| `quota_exceeded`，原因 `vm_30d` | 超過 24 小時層級的虛擬機器數量且錢包尚未涵蓋該機隊 30 天的費用 | 充值顯示的金額。 |
| `quota_exceeded`，原因 `vm_max` | 已達到虛擬機器絕對上限 | 達到 30 天門檻時提高 **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/zh-tw/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}

客戶區域是支援人員用來查詢帳戶、查看其錢包、服務、支援單與登入歷史記錄並採取行動的地方：鎖定、解鎖、驗證電子郵件、重設密碼、新增或移除點數、模擬登入、建立虛擬機器或關閉帳戶。

## 需求 {#requirements}

| 項目 | 需求 |
|---|---|
| 角色 | 管理員。每項寫入操作均會要求提供原因，並寫入稽核日誌 (System › Logs › Admin actions)。 |
| 電子郵件 | 密碼重設與邀請電子郵件需要正常運作的 [SMTP configuration](https://nexcmp.com/zh-tw/docs/administration/smtp-and-emails/)。 |

## 客戶列表 {#the-customer-list}

開啟**Customers › List**. Customers為您主站點的帳號；經銷商帳號也會一併顯示，並可依站點篩選。

![帶有篩選條件以及國家、推薦來源、餘額與虛擬機器數量欄位的客戶列表](https://nexcmp.com/zh-tw/docs/images/customers/managing-customers-01-list.webp)

| 欄位 | 含意 |
|---|---|
| **Email**（與姓名） | 點擊以開啟客戶。 |
| **State** | *Active*、*Locked* 或 *Deleted*，以及 *verified* 或 *unverified* 電子郵件。將滑鼠停留在鎖定標籤上可查看原因。 |
| **Login** | 客戶擁有的登入方式：密碼、Google、GitHub、passkey。 |
| **Country** | 衍生自 **IP address** 的國旗與名稱：註冊 IP 的國家，若未知則為最後登入 IP 的國家。工具提示會說明使用的是哪一個。 |
| **推薦來源** | *Referral*會顯示推薦人的連結與推薦代碼（如果客戶是透過聯盟行銷連結註冊的）；否則顯示「Not recorded」。 |
| **Balance**、**VMs** | 錢包餘額（負值為紅色）與執行中的虛擬機器數量。 |
| **IP 已註冊 / 最後** | 註冊時與最後一次登入時使用的 IP，並附帶兩位字母的國家代碼。可用於識別來自同一個位址的多個帳號。 |
| **Tenant** | 客戶的內部租戶 ID。 |
| **Created**、**Last login** | 相對時間。 |
| **Site** | 當您擁有經銷商時會顯示。 |

**Search** 接受電子郵件、姓名或 IP。**Filters：** 狀態（全部、啟用、鎖定、已刪除）、登入方式（任何、Google、GitHub、passkey、尚未設定密碼）與站台。篩選條件會保留在 URL 中，因此可以將篩選後的列表加入書籤或與同事分享。

**排序是全域的。** 點擊 *Email*、*State*、*Balance*、*VMs*、*Created* 或 *Last login* 的表頭會對伺服器上的**整個**客戶群進行排序，而不僅僅是您目前檢視的頁面，且頁碼會回到 1。

**清單會自動更新。**在您瀏覽時每隔數秒便會重新整理（對話方塊開啟或您正在輸入時會暫停），因此無需重新載入即可顯示新註冊與餘額變動。客戶頁面在可見時約每30秒重新整理一次；每個分頁在首次開啟時會各自載入資料。

### 建立客戶 {#create-a-customer}

1. 點擊 **Create customer**。
2. 輸入 **e-mail**、選填的 **display name**、選填的 **password**（留空 = 由客戶透過邀請連結設定），並選擇是否**傳送邀請電子郵件**。
3. 確認。手動建立的帳號在您傳送邀請時即計為已驗證。

## 客戶頁面 {#a-customer-s-page}

點擊任一行。頁面共有八個分頁；當前選取的分頁會保留在URL中，方便您加入書籤。分頁在首次開啟時載入，切換離開時會保留其狀態。

| 標籤頁 | 內容 |
|---|---|
| **Overview** | 身分、註冊與上次登入資訊、錢包與服務摘要 |
| **Services** | 客戶服務的整合表格，具備類型與狀態篩選、搜尋、伺服器端排序與分頁功能 |
| **Billing** | 錢包與點數、帳本、發票、付款、退款、已儲存的付款方式以及自動加值 |
| **Quota** | 資源配額與覆寫；請參閱[Quotas](https://nexcmp.com/zh-tw/docs/billing/quotas/) |
| **Security** | 工作階段、身分驗證、登入方式、登入歷史記錄與API金鑰；請參閱[API keys](https://nexcmp.com/zh-tw/docs/developers/api-keys/) |
| **Support** | 最近的工單 |
| **Affiliate** | 推薦計畫狀態 |
| **Log** | 稽核與活動歷史記錄 |

標頭中的動作按鈕（對已刪除的帳號隱藏）：

| 按鈕 | 功能 |
|---|---|
| **Lock account** / **Unlock** | 封鎖登入與 API 存取。並可選擇停止所有虛擬機器（不刪除它們）。非虛擬機器的預付費服務（Kubernetes、Private Cloud、VPN 等）也會一併停止。由管理員鎖定的虛擬機器必須在虛擬機器頁面上單獨解鎖。 |
| **Verify email** | 將電子郵件標記為已驗證，無需客戶點擊連結。 |
| **Send reset link** | 寄送密碼重設連結（有效期限 1 小時，限用一次）。若未設定 SMTP，該連結將顯示一次，以便您自行寄送。管理員永遠無法看到密碼。 |
| **Impersonate** | 以該客戶身分登入一小時。請參閱 [Log in as a customer](https://nexcmp.com/zh-tw/docs/customers/login-as/)。 |
| **Credit / debit** | 透過帳目調整來新增或扣除錢包金額。請參閱 [Invoices and ledger](https://nexcmp.com/zh-tw/docs/billing/invoices-and-ledger/)。 |
| **Revoke sessions** | 將客戶在所有地方登出；應用程式權杖將停止運作。 |
| **Create VM** | 為客戶建立虛擬機器。 |
| **Soft delete** | 關閉帳戶。您必須輸入電子郵件以進行確認。 |


### 管理個別服務 {#manage-an-individual-service}

開啟客戶的**Services**分頁，透過名稱、ID、IP或設定尋找服務，並使用該列的操作功能。服務本身的後台清單中也提供相同的操作。對話方塊僅提供該服務及其當前狀態所支援的操作。

| 動作 | 效果 |
|---|---|
| **Lock** | 停止服務但保留其資料。客戶端會顯示為已鎖定且無法操作。儲值不會解除管理員的鎖定；鎖定期間將停止自動續約。 |
| **Unlock** | 解除管理員的鎖定。這不會解除不相關的濫用防護或其他保護鎖定。 |
| **Cancel without refund** | 取消服務且不產生退款帳本條目。確認提示會警告取消後無法復原。 |
| **Cancel and refund** | 顯示原始付款紀錄、其錢包/點數分配、先前的退款以及最高可退款金額。確認前請先核對金額。 |

請為每項操作輸入原因。此原因僅供管理員查看；客戶會收到中立的服務事件或通知。退還的錢包款項會退回至錢包，而信用額度或促銷配額則退回至信用額度。此操作不會透過Stripe、銀行轉帳或PayPal退回款項。

若有多項相同類型的服務，最多可選取50列並選擇批次操作。執行結果會列出每一列的成功或失敗。批次退款會採用每項服務的建議金額；在退款模式下，建議退款金額為零的服務會被略過，需要個別審核或進行不退款取消。

DDoS Shield、磁碟與backups在此處為唯讀列。頻寬加購項目會依循其上層服務。AI Models存取權限可以鎖定，但沒有可取消的訂閱。若要鎖定租用的Bare Metal伺服器，請操作其訂閱而非訂單。

### 關閉帳戶（軟刪除） {#closing-an-account-soft-delete}

帳戶狀態會設為*已刪除*、遭到封鎖、工作階段遭到撤銷，且尚未支付的推薦佣金將被沖銷。發票與帳目會保留供會計使用。當客戶仍有**任何線上服務**（虛擬機器、Kubernetes、私有雲、專用伺服器、VPN、IPv6 Proxy）、S3 帳戶或未結清的 S3 使用量時，此操作將被拒絕。請先刪除這些項目。

## 刪除請求 {#deletion-requests}

客戶可以從其帳戶頁面要求刪除。請求會顯示在 **Customers › Deletion requests**（預設篩選條件：處理中）中，包含客戶、原因、線上虛擬機器數量、餘額與請求時間。

- **Approve deletion** 僅在客戶沒有線上虛擬機器時才能執行。請輸入電子郵件以進行確認。帳戶將被軟刪除；**剩餘的錢包餘額不會自動退款**——若您欠款，請先建立退款。
- **Reject** 需要填寫原因。

## 服務轉移 {#service-transfers}

**Customers › Service transfers** 會列出將**虛擬機器或 VPN 訂閱**從**同一網站上**的一個帳戶移動到另一個帳戶的請求。

- 此畫面僅限檢視與建立：您可以代表客戶建立請求或予以取消。刻意**沒有**提供按鈕讓擁有者或接收者直接核准。
- 流程：擁有者透過單次使用的電子郵件連結確認（有效期限 30 分鐘，若有啟用 TOTP 則需包含），接著接收者登入並接受（接收者承擔付款義務）。未在 7 天內接受的請求將會失效。
- 規則：服務必須為使用中且無未結清發票，且無執行中的工作；接收者必須是同一網站上已驗證電子郵件的使用中客戶。虛擬機器轉移會移除 SSH Key 並關閉自動續約；VPN 轉移會變更連線密碼。
- 已發出的發票仍保留在前擁有者名下；新擁有者可以檢讀該服務的計費歷史記錄，但會隱藏前擁有者的資料。
- 客戶可以在入口網站的 **Transfers** 下建立自己的請求（每小時 5 個請求，同時最多 3 個未結案）。

## 驗證 {#verify}

1. 透過邀請郵件建立客戶。新帳戶會在幾秒鐘內顯示在列表頂端。
2. 依 **Balance** 排序：此排序涵蓋所有客戶。
3. 鎖定客戶：狀態標籤會變成*已鎖定*，且客戶將無法再登入。您可以將其解鎖。

## 限制與注意事項 {#limits-notes}

- 國家欄位是根據 IP 的參考指標，而非居住證明。私人或未知位址不會顯示國家。
- 鎖定帳戶不會退款，也不會刪除虛擬機器，除非您同時選擇將其停止。
- 將帳戶解鎖不會自動解鎖管理員所鎖定的虛擬機器；請在虛擬機器頁面上個別將其開啟。

## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| 「客戶仍有運行中的服務……請先停止或刪除」 | 該客戶擁有服務或 S3 帳戶 | 移除它們，然後執行軟刪除。 |
| 刪除核准提示「N 個 VM 執行中」 | 相同原因 | 請先刪除虛擬機器。 |
| 顯示重設連結而非「已將電子郵件加入佇列」 | 尚未設定 SMTP | 請設定電子郵件，或自行寄送連結。 |
| 無法移除登入方式 (`last_login_method`) | 這是該客戶唯一的登入方式 | 請先新增其他方式。 |
| 鎖定無法停止預付服務 | 回報了停止錯誤 | 請閱讀鎖定後的訊息；系統會自動重試停止。 |
| 無法建立轉移 | 有未付發票、執行中的工作、收件者位於其他站台或未驗證 | 修復狀況並重試。 |


---

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

# 以客戶身分登入 {#log-in-as-a-customer}

> **管理後台位置：**Customers › Customers › List › a customer › header button **Impersonate**（`/customers/<id>`）。

## 功能 {#what-it-does}

**Impersonate**（以該身分登入）讓支援管理員能以客戶完全相同的視角檢視 portal，以重現問題或協助處理訂單。工作階段持續一小時，且與一般工作階段明確區隔：所有可能授予帳戶永久存取權的功能都會被封鎖，且每次使用都會留下紀錄。

## 需求 {#requirements}

| 項目 | 需求 |
|---|---|
| 角色 | 已登入管理主控台的管理員。 |
| 客戶 | 帳戶必須為 **active**。已鎖定或已刪除的帳戶會回覆「帳戶未啟用」(HTTP 409)。 |
| 原因 | 必須填寫原因；該原因會寫入稽核記錄。 |
| 瀏覽器 | 請允許管理員位址彈出視窗：portal 會在新視窗中開啟。 |

## 步驟 {#steps}

1. 開啟 **Customers › List** 並點擊該客戶。
2. 點擊 **Impersonate**。對話框會說明客戶的站台將以該客戶身分開啟一小時，且所有動作都會被稽核。
3. 輸入**原因**（例如「Ticket 1234 — 無法建立 VM」）並點擊 **Open app**。
4. 新視窗會在客戶的站台上開啟並顯示含有 `?impersonated=1` 的儀表板。如果瀏覽器封鎖了視窗，請允許彈出視窗後再次點擊。

![填入原因欄位的 Impersonate 對話框](https://nexcmp.com/zh-tw/docs/images/customers/login-as-01-dialog.webp)

對於經銷商的客戶，視窗會在**經銷商自己的網域**上開啟，因為該連結僅適用於客戶自己的站台。

## 運作原理 {#how-it-works}

1. 管理員動作會建立一個有效期為一小時的**單次使用權杖**，並將 `customer.login_as`（管理員、IP、原因、站台）寫入稽核記錄。
2. 新視窗會開啟 `https://<site>/v1/portal/impersonate/<token>`。第一次請求僅會顯示一個小型頁面，且**不會**消耗權杖（避免瀏覽器預先提取消耗掉）；接著頁面會透過 POST 進行確認。
3. POST 會消耗該權杖。第二次使用，或在一小時後使用，會回覆「Impersonation 連結已過期或已被使用」。
4. NexCMP 會建立一個持續 **一小時** 的客戶工作階段（一般工作階段持續 30 天），以方法 `impersonate` 記錄登入條目，並記錄 `customer.login_as.used`。
5. 此權杖僅在客戶自己的站台上有效；在其他主機上會回覆 404。

## 模擬工作階段中封鎖的項目 {#what-is-blocked-in-an-impersonated-session}

任何提供超過一小時存取權限或變更客戶自身安全設定的操作，都會傳回 HTTP 403 `impersonate_forbidden`：

| 已封鎖 | 原因 |
|---|---|
| 變更密碼、TOTP、連結或取消連結 Google/GitHub、編輯通行密匙 | 客戶自身的憑證 |
| 刪除帳戶 | 不可逆 |
| 建立或編輯 **API keys** | 長期存取權限 |
| 批准 CLI、桌面或 MCP 登入（裝置連結） | 長期存取權限 |
| 建立 Kubernetes 存取權、S3 金鑰、SSH 金鑰、root 密碼、主控台共用連結、VPN 或代理伺服器憑證 | 生命週期超出工作階段的機密 |
| 兌換加值代碼 | 金錢活動 |
| 提領或變更推薦獎金的佣金發放 | 資金離開系統 |
| 編輯 AI 金鑰、預算或警示電子郵件 | 客戶設定 |

其他所有功能均可正常運作：您可以讀取頁面、建立或管理 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}

- 一小時限制為固定值（3600 秒）。若要繼續，請再次執行模擬。
- 建議以讀取與重現為主；除非客戶要求，否則請避免會花費金錢的操作。
- 使用客戶頁面上的 **Revoke sessions** 提早撤銷工作階段（這也會將客戶登出）。
- 經銷商擁有自己的 **Sign in to partner console** 模擬功能（60 分鐘），位於經銷商選單中；請參閱 [Resellers](https://nexcmp.com/zh-tw/docs/customers/resellers/)。

## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| 「帳戶未啟用」 | 帳戶已鎖定或刪除 | 請先解鎖，或改為查看客戶頁面。 |
| 瀏覽器封鎖視窗 | 彈出視窗封鎖程式 | 允許管理員位址的彈出視窗，然後再試一次。 |
| 「連結已失效或已被使用」 | 一小時限制或重複使用 | 再次執行模擬。 |
| 開啟時顯示 "Not found" | 連結在錯誤的主機上使用 | 請使用對話方塊開啟的視窗；請勿將連結貼到其他地方。 |
| 操作顯示 "forbidden" | 在模擬工作階段中遭到封鎖 | 請要求客戶執行，或使用管理員畫面。 |


---

<!-- source: https://nexcmp.com/zh-tw/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}

| 項目 | 需求 |
|---|---|
| 授權 | 您的授權中每個自訂代理商網域對應一個**代理商網域授權額度**。授權頁面會顯示 `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 個步驟並會在最後完成所有佈建；每個步驟皆可安全地重試。

   | 步驟 | 填寫內容 |
   |---|---|
   | **代理商** | 法定或營業名稱、**slug**（4 至 31 個字元，包含 a–z、0–9 或 `-`，以字母開頭；同時也是發票前綴）、聯絡人姓名、電子郵件與電話、預設語言、代理商的帳單詳細資料（作為錢包加值買家）。 |
   | **主控台帳戶** | 使用者名稱、帳戶電子郵件、全名；**透過電子郵件傳送單次邀請連結**（有效期限 72 小時，建議使用）或顯示一次性暫時密碼。 |
   | **品牌** | 品牌名稱、簡稱、標語、主要色彩、支援電子郵件與電話、列印在客戶發票上的賣家名稱、標誌（亮色與暗色背景）、方形標誌與圖示：PNG、JPEG、WEBP 或 ICO，大小上限 256 KB，**不支援 SVG**。 |
   | **Domains** | 包含**也有 www** 的客戶網域、哪一個是主要網域、**測試網域** (sslip.io) 與**乾跑**選項，或是平台子網域。精靈會顯示 **DNS OK / DNS not ready** 以及需要建立的記錄。 |
   | **Pricing & wallet** | 批發折扣 (%)、零售底價 (佔定價的 %)、預設加價 (%)、信用額度、初始餘額、低餘額警示、客戶、VM 與網域的限制、網站功能 (客戶註冊、DDoS 防護、支援工單、自訂方案、調整大小、Auto Scaling)。 |
   | **Payment channels** | 誰來收取客戶款項 (見下方) 以及自選的 PayPal 與自選越南銀行轉帳。 |
   | **Email** | 寄件者名稱與回信地址 (Reply-To)。在為轉售商網域設定 DKIM 之前，From 地址會維持平台地址。 |
   | **Review** | 檢查所有項目並點擊 **Provision everything**，或是 **Save draft (provision later)**。 |

2. 佈建會在背景繼續進行 (每 30 秒一次)。開啟轉售商以查看進度，若某個步驟失敗，請使用 **Continue provisioning** 或 **Retry**。

![帶有範例數值的首步驟新轉售商精靈](https://nexcmp.com/zh-tw/docs/images/customers/resellers-01-wizard.webp)

### 指向 DNS (由轉售商執行) {#point-dns-the-reseller-does-this}

轉售商 (或您) 建立顯示於 **Domains & SSL** 標籤頁上的記錄：

| 記錄 | Name | 值 |
|---|---|---|
| TXT (擁有權驗證，僅限首次) | `_site-verify.<domain>` | `sv=<token>` 顯示於畫面上 |
| A (頂級網域，例如 `shop.example.net`) | 該網域 | 您的 `rs_server_ipv4` |
| CNAME (子網域，例如 `cloud.example.net`) | 該網域 | 您的 `rs_cname_target` (或是指向 `rs_server_ipv4` 的 A 記錄) |
| CNAME (選填) | `www.<domain>` | 您的 `rs_cname_target` |

此外：

- 移除任何 **AAAA** (IPv6) 記錄，除非您的伺服器支援該 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`) 是一個矩陣：每個經銷商有一列，包含批發**折扣**與**加價**，以及每個服務（例如 DDoS Shield 和 VPN）一個開關。當全平台功能啟用時，開關可編輯；否則該儲存格為唯讀並連結至設定。**Top-up codes** 子標籤頁設定每個經銷商每月可發行多少代碼（見 [Promotions](https://nexcmp.com/zh-tw/docs/billing/promotions/)）。

定價規則：

- 批發價 = 定價 x (1 - 折扣)，且可在經銷商的 **Wholesale pricing** 標籤頁中按方案與計費週期進行覆寫。
- 經銷商設定零售價，且不得低於**底價**（定價的百分比）。
- 當客戶購買時，經銷商的**錢包**會支付批發價。錢包具有信用額度、寬限期與透支上限（見 Defaults）。

## Defaults {#defaults}

**Customers › Resellers › Defaults** (`/resellers/settings`) 是適用於所有經銷商的 `rs_*` 設定金鑰。每次變更均需填寫原因並會受到稽核。

| 群組 | 金鑰 | 預設值 | 含意 |
|---|---|---|---|
| 一般 | `rs_enabled` | 1 | 經銷商計劃已啟用。 |
| | `rs_platform_collect_enabled` | 0 | 允許平台為經銷商代收客戶付款。**請僅在經過法律審查後啟用。** |
| | `rs_totp_required` | 1 | 經銷商主控台帳號必須使用雙重認證。 |
| | `rs_agreement_version` | 1 | 他們必須接受的經銷商協議版本。 |
| 預設定價 | `rs_default_discount_bp` | 2000 (20 %) | 新經銷商的批發折扣（基點，0 至 9000）。 |
| | `rs_default_markup_bp` | 2500 (25 %) | 預設加價（0 至 50000）。 |
| | `rs_default_floor_bp` | 9000 (90 %) | 零售底價（0 至 20000）。 |
| | `rs_default_max_domains` | 3 | 每個經銷商允許的網域數量。 |
| 錢包與撥款 | `rs_grace_hours` | 72 | 經銷商錢包餘額不足時，客戶服務受影響前的寬限期。 |
| | `rs_overdraft_cap_cents` | 5000 | 錢包允許透支。 |
| | `rs_retention_days` | 14 | 已關閉經銷商的虛擬機器被銷毀前的天數。 |
| | `rs_payout_hold_days` | 30 | 佣金在可提領前保留的天數。 |
| | `rs_payout_min_cents` | 5000 | 最小提領金額。 |
| | `rs_topup_min_cents` | 2000 | 經銷商最小錢包加值金額。 |
| 付款與郵件 | `rs_webhook_base` | 空白 | 經銷商閘道 Webhook 的公開基礎 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 或銀行帳戶。其 Webhook 為 `https://<reseller-domain>/v1/billing/<gateway>/webhook/r/<id>`。這些網站不支援儲存的卡片與 [auto top-up](https://nexcmp.com/zh-tw/docs/billing/auto-top-up/)。 |
| **平台收款** | 您的管道會顯示在經銷商網站上。在 `rs_platform_collect_enabled = 1` 之前為鎖定狀態。 |
| **混合** | 按管道選擇的組合。 |

## 經銷商所看到的內容 {#what-the-reseller-sees}

位於 `https://partner.<your-domain>` 的夥伴主控台包含 Overview、Reports、Customers、VMs、Tickets、Orders、Payments、Prices、Brand、Landing & legal、Domains & SSL、Email、Wallet 和 Payment channels。主控台帳號擁有 *reseller*（完整）或 *staff*（唯讀）角色。若要親自查看，請開啟該經銷商並點擊 **Sign in to partner console**：您將進入 60 分鐘，每一次寫入操作都會在管理員記錄與經銷商記錄中記錄您的姓名，且金錢相關操作需要二次確認。

## 驗證 {#verify}

1. 佈建完成後，經銷商的清單列會顯示 *active* 以及綠色的 **Provisioning** 欄位。
2. 在瀏覽器中開啟經銷商的網域：隨即會顯示帶有其品牌的經銷商專屬登入頁面。`https://<reseller-domain>/admin` 回傳 404。
3. 在該網域上註冊測試客戶：該客戶會出現在 **Customers › List** 中，且 **Site** 欄位為該經銷商。
4. 授權頁面會顯示多使用了一個配額。

## 限制與注意事項 {#limits-notes}

- 每個自訂或測試網域佔用一個授權配額；平台子網域不佔用配額。
- 暫停經銷商會保留資料；**Close reseller** 會回收所有網域配額，且僅能在保留期過後才允許刪除虛擬機器。
- 經銷商客戶會出現在您的客戶清單中，且可以像其他客戶一樣進行模擬登入（連結會在經銷商的網域上開啟）。
- 經銷商無法檢視或變更您的付款管道、預設額度或其他經銷商。

## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| 「經銷商網域配額已用盡」 | 所有配額皆已使用 | 釋放配額（移除網域）或在授權頁面購買更多配額。 |
| 網域卡在 `pending_verify` | 缺少 TXT 記錄 | 建立完全如所示的 TXT 記錄；使用 **Check now**。 |
| 網域卡在 `pending_dns` | A/CNAME 未指向您、存在 AAAA 記錄，或 CDN 代理已開啟 | 修復 DNS、關閉代理，然後點擊 **Check now**。 |
| `error` 狀態 | 查看該列上的代碼（例如 CAA 封鎖 Let's Encrypt、速率限制） | 修復後點擊 **Retry**。 |
| 瀏覽器顯示主機未知或「421」 | 主機名稱不在授權中，或未路由至控制台 | 透過經銷商新增網域（會消耗一個配額）並修復反向代理。 |
| 說明顯示錯誤的 IP 或主機 | `rs_server_ipv4` / `rs_cname_target` 仍保有範例值 | 在 Defaults 中設定它們。 |
| 經銷商無法啟用平台收款 | 已鎖定 | 經過法律審查後設定 `rs_platform_collect_enabled`。 |




---

<!-- source: https://nexcmp.com/zh-tw/docs/customers/branding/ -->

# 品牌設定 {#branding}

> **Where in the admin:** System › Settings › Brand (`/settings/branding`)。相關設定：System › Settings › General (`/settings`) 用於 URL 以及列印在發票上的賣家詳細資訊。

## 功能 {#what-it-does}

NexCMP 採用白牌設計：產品不帶有任何供應商名稱，您的客戶所看到的全部都是**您的**品牌。品牌設定適用於登入與註冊頁面、入口網站、管理員控制台以及電子郵件。

## 需求 {#requirements}

| 項目 | 需求 |
|---|---|
| 角色 | 管理員。 |
| 檔案 | 標誌：SVG、PNG、JPEG、WEBP 或 ICO，**每個最高 512 KB**。 |
| 相依項目 | 無。 |

## 步驟 {#steps}

1. 開啟 **System › Settings › Brand**。
2. 在 **Identity** 卡片中填入：

   | 欄位 | 注意事項 |
   |---|---|
   | **Brand name** (required) | 最多 60 個字元。顯示於入口網站、電子郵件、發票與法律頁面中。 |
   | **發票上的賣方名稱** | 最多 120 個字元。留空則代表使用品牌名稱。 |
   | **Brand color** | 一個 `#rrggbb` 色彩；欄位旁邊的小按鈕可將其重設為內建色彩。 |
   | **Site currency** | **USD**：價格與餘額僅以 USD 顯示，無貨幣切換功能。**VND**：同時以儲存的匯率顯示轉換後的金額（請參閱[Currency and exchange rates](https://nexcmp.com/zh-tw/docs/catalog/currency-and-exchange-rates/)）。 |

3. 點擊 **Save**。
4. 在 **Logo & favicon** 卡片中上傳三張圖片 — **Logo (light background)**、**Logo (dark background)** 與 **Favicon** — 使用 **Upload**（或 **Replace**）；**Remove** 用於刪除其中一張。

![包含識別欄位與三個已上傳圖片的品牌頁面](https://nexcmp.com/zh-tw/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/zh-tw/docs/billing/invoices-and-ledger/)。 |

電子郵件的 **From name** 是在 **System › Settings › Email**（[SMTP and e-mails](https://nexcmp.com/zh-tw/docs/administration/smtp-and-emails/)）中設定。

## 已上傳檔案檢查 {#uploaded-files-are-checked}

- 點陣圖會根據其內容（而非檔名）進行識別與尺寸測量。
- **SVG 檔案會從安全的形狀清單重新重建**。包含腳本、`foreignObject`、事件屬性、外部連結、指向外部的 `url(...)`、DOCTYPE 或實體的檔案將會被**拒絕**（`svg_unsafe`）。
- 檔案過大會以 `asset_too_large` 拒絕，類型錯誤以 `asset_type` 拒絕，尺寸不符則以 `asset_dimensions` 拒絕。
- 檔案是從您自己的網域提供，並帶有嚴格的安全性標頭。

## 驗證 {#verify}

1. 在無痕視窗中開啟入口網站登入頁面：將會顯示標誌、名稱與顏色。
2. 檢查瀏覽器分頁的 favicon（瀏覽器會快取 favicon；若仍看到舊的圖示，請清除快取後重新載入）。
3. 觸發測試電子郵件（例如針對測試客戶的 **Send reset link**），並檢查主旨與頁尾中的品牌名稱。

## 限制與注意事項 {#limits-notes}

- 當客戶或管理員切換至深色主題時，就會使用深色背景的標誌。
- 經銷商擁有自己的品牌；他們可上傳最大 256 KB 的 PNG、JPEG、WEBP 或 ICO（不支援 SVG）。請參閱[Resellers](https://nexcmp.com/zh-tw/docs/customers/resellers/)。
- 對品牌顏色或標誌的變更會在下次載入頁面時顯示；已寄出的電子郵件不會改變。

## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| 上傳被拒絕：`svg_unsafe` | SVG 包含腳本、連結或外部參考 | 請匯出純 SVG（無腳本、無外部圖片）或使用 PNG。 |
| `asset_too_large` | 檔案大於 512 KB | 請壓縮或調整圖片尺寸。 |
| `asset_type` | 不是 SVG、PNG、JPEG、WEBP 或 ICO | 請轉換檔案格式。 |
| `invalid_argument: primary` | 顏色不是 `#rrggbb` | 請使用六位數的十六進位值。 |
| 舊標誌仍然可見 | 瀏覽器快取 | 請強制重新載入；favicon 可能需要較長時間更新。 |
| 價格僅顯示 USD | 網站貨幣為 USD | 請切換至 VND 並確保已儲存匯率。 |


---

<!-- source: https://nexcmp.com/zh-tw/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}

| 項目 | 需求 |
|---|---|
| 角色 | 管理員。 |
| 內容 | 純 Markdown，每頁與每種語言最多 **50 KB**。 |
| 相依項目 | 品牌名稱與賣家詳細資訊 ([Branding](https://nexcmp.com/zh-tw/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** 並儲存。

![顯示預設文字作為起點的服務條款卡片之法律設定畫面](https://nexcmp.com/zh-tw/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 Cookie 與本機儲存 · 4 其他檢視者 · 5 保留期限 · 6 您的權利 · 7 聯絡方式 |

::: warning 非法律意見
預設文字為中立範本。在與真實客戶一起使用之前，請先將其交由專業人員審閱，特別是關於退款、責任限制與準據法的章節。
:::

## Markdown 規則 {#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/zh-tw/docs/customers/resellers/)。
- 變更文字不會要求現有客戶再次接受。

## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| 儲存遭到拒絕：`html_not_allowed` | 文字中包含 HTML 標籤 | 移除標籤；改用 markdown。 |
| 儲存遭到拒絕：`unsafe_link` | `javascript:`、`data:` 或 `vbscript:` 連結 | 使用 `https://` 連結。 |
| 儲存遭到拒絕：`too_large` | 大於 50 KB | 縮短文字。 |
| 儘管寫了越南文，客戶看到的仍是英文 | 越南文分頁為空 | 寫入或貼上越南文文字。 |


---

<!-- source: https://nexcmp.com/zh-tw/docs/portal/overview/ -->

# 客戶入口網站概覽 {#customer-portal-overview}

> **入口網站位置：**`https://<your-domain>/` — 客戶於 `/login` 登入。管理員使用 `/admin`；當帳戶為管理員時，相同的登入資訊可開啟兩者。

入口網站是您的客戶每天使用的介面。它會帶有您的名稱、標誌與色彩（[Branding](https://nexcmp.com/zh-tw/docs/customers/branding/)），並且只顯示您已啟用的服務（[Modules](https://nexcmp.com/zh-tw/docs/infrastructure/modules/)）。

## 儀表板 {#the-dashboard}

登入後，**Dashboard** 會顯示：

| 區塊 | 含意 |
|---|---|
| 錢包餘額 | 目前信用額度以及根據目前消耗速率預估可使用天數 |
| 本月花費 | 至今的費用與月底預測 |
| 虛擬機器 | 各個虛擬機器的狀態、IP、CPU 與 RAM，以及快速動作（控制台、重新啟動） |
| 頻寬 | 1 小時、6 小時、24 小時、7 天、30 天的傳入/傳出流量 |
| 近期活動 | 帳戶上的最新事件 |
| 快速入門 | 檢查清單：建立虛擬機器、新增 SSH key、加值、啟用自動加值、驗證電子郵件 |

![客戶儀表板，包含錢包餘額、花費預測、執行中的虛擬機器與快速入門檢查清單](https://nexcmp.com/zh-tw/docs/images/portal/overview-01-dashboard.webp)

## 導覽 {#navigation}

選單會依類型將服務分組。您已停用（或其來源未連線）的服務將不會顯示。

| 區域 | 頁面 |
|---|---|
| Instances | [Virtual machines](https://nexcmp.com/zh-tw/docs/portal/virtual-machines/) 與其詳細資料頁面 |
| 部署 | [Ordering](https://nexcmp.com/zh-tw/docs/portal/ordering/) — 建立資源 |
| 儲存 | 啟用時的快照、備份與儲存卷 — [Snapshots](https://nexcmp.com/zh-tw/docs/portal/snapshots/) |
| 帳單 | [Wallet and top-ups](https://nexcmp.com/zh-tw/docs/portal/sign-up-and-wallet/)、發票、訂單、配額 |
| 帳號 | 個人檔案、登入與安全性、偏好設定、自動加值 |
| 支援 | 聊天小工具與支援單 — [Support](https://nexcmp.com/zh-tw/docs/portal/support/) |
| API文件 | `/apidoc` — [API](https://nexcmp.com/zh-tw/docs/developers/api/) |

## 帳號 {#account}

**Account**有四個分頁：**Profile**（姓名、電子郵件、客戶編號、刪除帳號要求）、**Sign-in & security**（密碼、通行密鑰、已連結的Google/GitHub）、**Preferences**（語言、顯示貨幣）與**Auto top-up**（[Auto top-up](https://nexcmp.com/zh-tw/docs/billing/auto-top-up/)）。

客戶無法直接刪除帳戶：他們點擊 **Request account deletion**；在所有虛擬機器刪除後，由操作員審核該請求 (Customers › Deletion requests)，且客戶在待審核期間可以撤回。

## 語言與貨幣 {#language-and-currency}

該入口網站提供16種語言，並根據語言顯示對應貨幣的價格；請參閱[Currency and exchange rates](https://nexcmp.com/zh-tw/docs/catalog/currency-and-exchange-rates/)。客戶可以在**Preferences**中切換兩者。

## 客戶配額 {#customer-quotas}

**Billing › Quotas**會顯示客戶根據已付金額可使用的各項資源（CPU、記憶體、儲存空間、IP、VM）額度——請參閱[Quotas](https://nexcmp.com/zh-tw/docs/billing/quotas/)。


---

<!-- source: https://nexcmp.com/zh-tw/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**或**passkey**——請參閱[Security](https://nexcmp.com/zh-tw/docs/administration/security/#customer-sign-in)。
2. 若啟用了驗證碼，則需完成驗證。
3. 驗證信會透過您的[SMTP](https://nexcmp.com/zh-tw/docs/administration/smtp-and-emails/)發送。當您的銷售設定有要求時，建立VM前必須先完成驗證。

![包含電子郵件與密碼欄位的註冊頁面](https://nexcmp.com/zh-tw/docs/images/portal/sign-up-and-wallet-01-register.webp)

::: tip
若沒有運作中的SMTP，客戶將無法驗證電子郵件或重設密碼。請先設定[SMTP](https://nexcmp.com/zh-tw/docs/administration/smtp-and-emails/)。
:::

## 錢包 {#the-wallet}

所有費用均從計費貨幣的**wallet**餘額中扣除。**Billing**頁面會顯示：

| 區段 | 含意 |
|---|---|
| 消費能力 | 餘額加上待處理的加值金額 |
| 累計中的費用 | 當前週期內已消耗但尚未結算的小時計費服務 |
| 未結清餘額 | 任何欠款金額 |
| 帳單記錄 | 分頁**Invoice History**、**Payment Order**、**Ledger**、**Orders** |

![顯示消費能力、累計費用與記錄分頁的Billing頁面](https://nexcmp.com/zh-tw/docs/images/portal/sign-up-and-wallet-02-billing.webp)

## 新增額度 {#add-credit}

1. 點擊**Deposit**。
2. 輸入金額。最低金額為您的[minimum top-up](https://nexcmp.com/zh-tw/docs/billing/minimum-top-up/)。
3. 選擇付款管道（若介面為越南文，則可選擇卡片、PayPal、USDT或銀行轉帳）——管道為您在[Payment channels](https://nexcmp.com/zh-tw/docs/billing/payment-channels/)中啟用的項目。
4. 付款。當付款提供者確認後，餘額即會更新。

已儲存的卡片、Stripe Link與PayPal可重複使用並用於[auto top-up](https://nexcmp.com/zh-tw/docs/billing/auto-top-up/)；請參閱[Saved payment methods](https://nexcmp.com/zh-tw/docs/billing/saved-payment-methods/)。

## 兌換代碼 {#redeem-a-code}

**Redeem code**可透過您發行的兌換券增加餘額 (Finance › Billing › Vouchers)，或套用促銷代碼——請參閱[Promotions](https://nexcmp.com/zh-tw/docs/billing/promotions/)。

## 發票 {#invoices}

每筆已付款的訂單都會產生一張發票，其中顯示您的賣家詳細資料（[General settings](https://nexcmp.com/zh-tw/docs/administration/general-settings/)）。客戶可從**Invoice History**開啟發票，並透過瀏覽器列印或儲存為PDF。

## 每小时计费 {#hourly-charges}

每小时服务会在资源存在的每个小时进行计费；费用会累积，单小时可能四舍五入至 $0.00。当余额不足时，系统会根据您的计费规则暂停服务，并透过电子邮件通知客户 (`low_balance`)。


---

<!-- source: https://nexcmp.com/zh-tw/docs/portal/ordering/ -->

# 订购服务 {#ordering-a-service}

> **在门户中的位置：** Deploy (`/deploy/vm`)。**在管理员后台中**您可控制此处显示的内容：Services (plans, prices) 與 System › Admin › License & updates (modules)。

订购页面是一个带有编号步骤的滚动表单。在步骤 1 选择其他服务时会保留页面并更改下方的步骤。

## 步驟 {#steps}

1. **Service** — 雲端伺服器，以及您启用的其他服务（Kubernetes、Object Storage、Images、Private Cloud、VPN …）。
2. **Location** — [zone](https://nexcmp.com/zh-tw/docs/infrastructure/zones/)。价格和包含的流量可能因位置而异。
3. **Plan** — 固定方案（vCPU、RAM、NVMe 磁盘、每小时价格）或 **Custom**（客户选择 vCPU、RAM 和磁盘；按资源计费）。方案来自 [Plans](https://nexcmp.com/zh-tw/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/zh-tw/docs/images/portal/ordering-01-plan.webp)

![订购页面的计费周期与作业系统步骤](https://nexcmp.com/zh-tw/docs/images/portal/ordering-02-cycle-os.webp)

## 送出订单 {#placing-the-order}

摘要会显示价格。订单在经过 [quota check](https://nexcmp.com/zh-tw/docs/billing/quotas/) 与 [minimum balance](https://nexcmp.com/zh-tw/docs/billing/minimum-top-up/) 规则后，会在供应 **之前** 从钱包扣款。VM 通常在大约一分钟内达到 *Running* 状态；客户可以在 VM 的 **Activity** 标签页中看到部署步骤，并收到包含初始密码的「VM ready」电子邮件（密码可查看一次，时效 10 分钟）。

## 可能阻止订单的原因 {#what-can-stop-an-order}

| 讯息 / 原因 | 修正方式 |
|---|---|
| 余额不足 | 加值 — [Sign-up, wallet and top-up](https://nexcmp.com/zh-tw/docs/portal/sign-up-and-wallet/) |
| 超出配额 | 提高配额 — [Quotas](https://nexcmp.com/zh-tw/docs/billing/quotas/) |
| 电子邮件未验证 | 客户验证电子邮件 |
| 所选位置没有可用方案 | 在该区域提供方案 — [Plans](https://nexcmp.com/zh-tw/docs/catalog/plans/) |
| 授权无效 | 客户无法建立新服务 — [License](https://nexcmp.com/zh-tw/docs/getting-started/license-and-purchase/#if-the-license-is-not-valid) |


---

<!-- source: https://nexcmp.com/zh-tw/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/zh-tw/docs/images/portal/virtual-machines-01-overview.webp)

### 操作 {#actions}

| 動作 | 效果 |
|---|---|
| 主控台 | 开启浏览器控制台 — [Console](https://nexcmp.com/zh-tw/docs/portal/console/) |
| Restart / Stop / Force stop | 电源控制 |
| 重設密碼 | 產生新密碼，僅顯示一次 |
| 重新安裝作業系統 | 從範本重建；資料將會遺失 |
| 變更 IP | 取代公開 IP（若來源支援） |
| 啟用 Auto Scaling | 啟用後會在負載下自動調整 CPU/RAM |
| 刪除 | 銷毀虛擬機器；停止按小時計費 |

### 顯示的資訊 {#information-shown}

運行時間、本月費用、即時使用率的 vCPU/RAM/磁碟、公開與私有 IP、使用者名稱、頻寬圖表、動作日誌以及計費摘要（方案、週期、小時、剩餘時間）。

::: info 欄位取決於來源
虛擬機器頁面僅會顯示其來源支援的功能。例如，Proxmox VE 虛擬機器沒有連接埠轉發或變更 IP 功能，且其作業系統清單遵循其叢集的範本設定。請參閱 [Proxmox VE](https://nexcmp.com/zh-tw/docs/infrastructure/proxmox/) 中的功能支援表。
:::

## 計費分頁 {#billing-tab}

顯示方案、週期、總小時數、剩餘時間和計費日誌。按小時計費的虛擬機器會持續累積費用直到被刪除。客戶可以**切換週期**以折扣價預付更長的時間。

## 給管理員 {#for-administrators}

相同的虛擬機器可在管理主控台的 Services › Virtual Machines 下檢視，您可以在此代表客戶執行操作或[以其身分登入](https://nexcmp.com/zh-tw/docs/customers/login-as/)。


---

<!-- source: https://nexcmp.com/zh-tw/docs/portal/console/ -->

# 主控台 {#console}

> **門戶位置：**虛擬機器頁面 → **Console** 分頁。**管理員位置：**System › Admin › License & updates → 模組（網頁 SSH）。

## 功能 {#what-it-does}

**Console** 分頁會在瀏覽器中開啟虛擬機器的圖形化 (VNC) 工作階段，即使虛擬機器內部網路中斷時亦然。當啟用 SSH 模組時，**網頁 SSH** 終端機可作為第二種選項。

## 需求 {#requirements}

| 項目 | VNC 主控台 | 網頁 SSH |
|---|---|---|
| CloudStack | 面板可連線的主控台代理虛擬機器 (CPVM) — 請參閱 [CloudStack](https://nexcmp.com/zh-tw/docs/infrastructure/cloudstack/) | 虛擬機器上可連線的 SSH 連接埠 |
| Proxmox VE | 透過面板運作（透過 Proxmox API 使用 noVNC；已釘選 TLS 指紋）— 請參閱 [Proxmox VE](https://nexcmp.com/zh-tw/docs/infrastructure/proxmox/) | 同上 |
| 面板 | 設定於 [General settings](https://nexcmp.com/zh-tw/docs/administration/general-settings/) 的主控台 URL | `ssh-proxy`服務與模組旗標`feature_ssh_web`；預設為關閉 — 請參閱 [Modules](https://nexcmp.com/zh-tw/docs/infrastructure/modules/) |

若網頁 SSH 模組關閉，該分頁會顯示 **VNC only**。

## 使用方式 {#use-it}

1. 開啟虛擬機器 → **Console**。
2. 點擊 **Console**（或 **Open in new window**）。系統將核發短期有效的票證，並在 `https://<domain>/console` 開啟主控台。
3. 使用虛擬機器的使用者名稱與密碼登入（顯示於 Overview 分頁；若遺失可進行重設）。

![虛擬機器的 Console 分頁](https://nexcmp.com/zh-tw/docs/images/portal/console-01-tab.webp)

## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| 立即顯示「Disconnected」 | 瀏覽器保留了舊的主控台路徑 | 清除該網域的網站資料並重試 |
| 黑畫面 | 虛擬機器已停止或正在開機 | 啟動虛擬機器並等待 |
| CloudStack 上的主控台無法開啟 | 主控台代理虛擬機器未執行或無法連線 | 檢查 CloudStack 中的系統虛擬機器 |
| 沒有 SSH 選項 | Web SSH 模組已關閉 | 請在安裝 `ssh-proxy` 後再啟用 |


---

<!-- source: https://nexcmp.com/zh-tw/docs/portal/snapshots/ -->

# Snapshots與備份 {#snapshots-and-backups}

> **Portal位置：** Snapshots (`/snapshots`)、Snapshot schedules (`/snapshots/schedules`)、Backups (`/backups`)。僅會在管理後台啟用該功能時顯示。

## 功能 {#what-it-does}

Snapshots會儲存虛擬機器磁碟的狀態，讓客戶在發生錯誤變更時可以還原。Snapshots可以手動建立或依照排程建立。

## 可用性 {#availability}

| Source | Snapshots | 注意事項 |
|---|---|---|
| CloudStack | 是 | 磁碟區快照；儲存空間將依設定計費 |
| Proxmox VE | 是 | **每台VM最多 5 個**；可建立、列出、還原與刪除 |

選單項目僅會在快照功能開啟且客戶擁有支援該來源的VM時才會出現。

## 使用方式 {#use-it}

1. 開啟 **Snapshots**，點擊 **Create**，選擇VM並輸入名稱。
2. 等待狀態變為 *ready*。
3. 若要返回，請在快照上選擇 **Restore** 並確認 — VM將回復至該狀態（必要時會重新啟動）。
4. 刪除不再需要的快照。


::: warning
還原將會捨棄快照建立之後寫入的所有資料。受到保護的VM無法從portal進行還原或刪除。
:::




---

<!-- source: https://nexcmp.com/zh-tw/docs/portal/support/ -->

# 客戶支援 {#support-for-customers}

> **Portal位置：** 每個頁面上的聊天氣泡、`/chat`，以及 Support tickets。**管理後台位置：** Customers › Support › Tickets (`/support/tickets`)，**Settings** 標籤頁。

## 給客戶 {#for-customers}

- **聊天氣泡**（每個頁面的底部角落）：提出問題；[AI Chat](https://nexcmp.com/zh-tw/docs/ai/ai-chat/) 會使用您的說明文件與客戶自身的帳戶資料進行回覆。**Expand** 會在 `/chat` 上開啟相同的對話。
- **與專員交談**：將對話轉交給您的團隊（透過您的管理員 Telegram 群組）。
- **Telegram / Zalo** 按鈕：僅在您於支援設定中設定連結後才會顯示。
- **工單**：用於較複雜的問題；回覆會透過電子郵件寄送 (`ticket_reply`)。

## 給您 {#for-you}

1. 開啟 **Customers › Support › Tickets**；新的工單與聊天會與對話記錄一同顯示在此處。
2. 在討論串中回覆。系統將透過您的 [SMTP](https://nexcmp.com/zh-tw/docs/administration/smtp-and-emails/) 將郵件寄給客戶。
3. 在 **Settings** 標籤頁中開啟或關閉聊天小工具、設定 Telegram 連結與 Zalo 連結（僅限 https），並選擇是否自動由 AI 回覆 — 請參閱 [AI Chat](https://nexcmp.com/zh-tw/docs/ai/ai-chat/)。
4. 連線 [Telegram alerts](https://nexcmp.com/zh-tw/docs/administration/telegram-notifications/)，以便您的團隊在有新聊天時收到通知。




---

<!-- source: https://nexcmp.com/zh-tw/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** `chat/completions` API 的服務 — 例如 OpenAI、OpenRouter、LiteLLM 閘道或您自己的 vLLM 伺服器。NexCMP 會儲存端點與 API 金鑰（已加密）並將其用於各項 AI 功能。您直接向提供者付費。

## 需求 {#requirements}

| 項目 | 需求 |
|---|---|
| Endpoint | 相容 OpenAI 的 Base URL（`https://api.openai.com/v1`、`https://ai.example.com/v1`）。NexCMP 會將 `/chat/completions` 加到以 `/v1` 結尾的 URL；對於任何其他 URL，則會加上 `/v1/chat/completions`；若 URL 本身已以 `/chat/completions` 結尾，則直接使用。 |
| 模型 | 支援**工具（函式）呼叫**的模型。AI Chat 與 Agent 均依賴它。 |
| API 金鑰 | 該端點的金鑰。建議在供應商端設定**消費上限**（例如具有每月預算的 LiteLLM 虛擬金鑰）。 |
| 網路 | 面板伺服器必須透過 HTTP(S) 存取該端點。表單中輸入的 URL 僅允許指向網際網路的 80、443、8080 或 8443 連接埠；若要使用內部位址，請先儲存供應商再進行測試。 |
| 相依項目 | **AI** 模組已開啟。關於 Agent 請參閱 [AI Agent](https://nexcmp.com/zh-tw/docs/ai/ai-agent/#requirements)。 |

## 準備基礎設施 {#prepare-the-infrastructure}

1. 向供應商註冊並建立 API 金鑰。若供應商支援預算或速率限制，請設定每月上限。
2. 記錄**基礎 URL** 與確切的**模型名稱**（並可選擇性最多四個備用模型）。
3. 在輸入之前，先從 NexCMP 伺服器進行測試：

   ```bash
   curl -s https://ai.example.com/v1/chat/completions \
     -H "Authorization: Bearer XXXX" -H "Content-Type: application/json" \
     -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Reply with one word: OK"}]}'
   ```

   帶有 `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、模型與金鑰才能啟用。 |
   | 顯示名稱 | `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 系列），低階層的回應速度會快得多。一般模型請保持預設值。 |

4. 點擊 **Save**，然後點擊 **Test connection**。測試會發送一個簡短的問題，並顯示 `Connected — <model>, <ms> ms` 或供應商傳回的錯誤。

![已開啟 AI 模組且連線表單已填入範例數值的 AI provider 頁面](https://nexcmp.com/zh-tw/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 僅限已登入的客戶使用，並設有每分鐘及每對話的訊息限制。Agent 每個帳號設有每日呼叫限制。參見 [AI Chat](https://nexcmp.com/zh-tw/docs/ai/ai-chat/) 與 [AI Agent](https://nexcmp.com/zh-tw/docs/ai/ai-agent/)。
- **隱私權。** 客戶的問題以及 AI 為該客戶讀取的資料（唯讀）將傳送給你的提供者。請在你的 [privacy policy](https://nexcmp.com/zh-tw/docs/customers/legal/) 中說明。
- **成本控制。** NexCMP 不計算 AI 成本；請使用提供者的預算功能。
- 該模組可隨時關閉：AI 選單項目將會消失，且 AI 路由會回傳 404 錯誤 `module_disabled`。AI Chat 的部分背景作業（工單調查、延遲回覆）會在面板下次重新啟動時套用變更。

## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| `base_url must be an http(s) URL` | 缺少通訊協定或包含空格 | 使用 `https://host/v1`。 |
| `api_key is required to enable the provider` | 未儲存金鑰 | 輸入金鑰並儲存。 |
| `base_url and model are required to enable the provider` | 欄位空白 | 兩者皆須填寫。 |
| 「Base URL已遭封鎖：僅限公開http(s)，連接埠80/443/8080/8443」 | 正在測試未儲存的內部地址或其他連接埠 | 請先儲存提供者，然後再進行測試。 |
| `api_key is required (enter the key again when you change the endpoint)` | Base URL 與已儲存的不同 | 重新輸入金鑰。 |
| `model: letters, digits and - _ . / : @` | 無效的字元 | 使用提供者的精確 model id。 |
| `fallback_models: up to 4 model names` | 數量過多 | 保留四個或更少。 |
| 測試失敗並回傳 401 | 金鑰錯誤 | 檢查金鑰與端點。 |
| 測試失敗並回傳 404 或 "model not found" | 路徑或模型錯誤 | 檢查 base URL（`/v1`）與 model id。 |
| `Too many tests — wait a minute` (429) | 每分鐘測試超過 10 次 | 請稍候。 |
| 入口網站仍未顯示 AI 選單 | 模組已關閉，或提供者未設定為「使用中」 | 開啟模組並啟用提供者。 |


---

<!-- source: https://nexcmp.com/zh-tw/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 可隨時回答客戶問題、查詢*客戶自己*的帳戶資料（餘額、服務、付款、近期錯誤），並可在客戶確認後為其執行動作——建立虛擬機器、變更方案。當助理無法協助時，客戶可點擊 **Talk to a human**：對話會傳送至您在 Telegram 上的客服人員，若在時限內無人回應則會轉為工單。相同的 AI 設定也能讓系統為您的客服人員**調查工單**。

## 需求 {#requirements}

| 項目 | 需求 |
|---|---|
| 模組與提供者 | 開啟 **AI** 模組並已儲存且使用中的 [AI provider](https://nexcmp.com/zh-tw/docs/ai/ai-providers/)。若沒有提供者，助理會回報尚未設定。 |
| 客戶 | **僅限已登入的客戶。** 在安裝好的 NexCMP 中沒有公開網站，因此未登入的訪客會看到 "Sign in to use AI Chat"。 |
| 客服人員頻道（選填） | 用於管理員警報的 Telegram 機器人與聊天室（見 [Telegram notifications](https://nexcmp.com/zh-tw/docs/administration/telegram-notifications/)）。同一個頻道會接收聊天轉接與工單草稿。 |
| 相依項目 | [AI provider](https://nexcmp.com/zh-tw/docs/ai/ai-providers/)。 |

## 準備基礎設施 {#prepare-the-infrastructure}

除了 AI provider 之外不需要其他項目。若您需要客服人員轉接：

1. 透過 @BotFather 建立一個 Telegram 機器人並記下權杖。
2. 建立一個群組或使用您與機器人的私人聊天室，並記下聊天室 ID。
3. 請將兩者輸入至 System › Settings › Admin alerts（參見 [Telegram notifications](https://nexcmp.com/zh-tw/docs/administration/telegram-notifications/)）。支援功能會重複使用該機器人與聊天室。

## 在 NexCMP 中連線 {#connect-in-nexcmp}

1. 確保 AI 模組已開啟且供應商測試通過（呈現綠燈）（[AI provider](https://nexcmp.com/zh-tw/docs/ai/ai-providers/)）。
2. 開啟 **Customers › Support › Ticket** 並選取 **AI settings** 標籤頁。左側卡片上方會顯示三個標籤：*AI provider: configured*、*Telegram: channel present* 以及 *On shift* 或 *Off shift*。
3. 左側卡片 **AI + Telegram**：

   | 開關或欄位 | 預設值 | 含意 |
   |---|---|---|
   | AI 自動調查工單 | 開啟 | 對於新工單或訊息，AI 會讀取客戶資料（唯讀），並將可能的成因與回覆草稿寫為**內部筆記**。它絕不會直接傳送給客戶。 |
   | Telegram 管理員警示 | 開啟 | 筆記會連同「傳送」、「編輯」和「略過」按鈕一同傳送到 Telegram。 |
   | AI 自動回覆 | 關閉 | 當所有安全條件成立（信心水準 85% 以上且無警告）時，自動傳送簡單的操作說明或銷售解答；於 3 分鐘後傳送，且可在 Telegram 上取消。 |
   | 允許自動回覆的分類 | `how_to`, `sales` | 僅限這些。 |
   | 主要模型、備用模型 | 從供應商設定 | 通常保持由 AI 供應商頁面儲存的設定即可。 |
   | 允許執行動作的 Telegram 使用者 ID | 空白 | 留空表示使用警示頻道聊天室。 |

4. 右側卡片 **Live chat (customer widget)**：

   | 欄位 | 預設值 | 含意 |
   |---|---|---|
   | 啟用聊天小工具 | 開啟 | 聊天氣泡與 `/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 Code）。留空則隱藏。 |
   | **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/zh-tw/docs/images/ai/ai-chat-01-settings.webp)

![帶有助理、Zalo 和 Telegram 快捷按鈕以及與真人交談選項的客戶聊天頁面](https://nexcmp.com/zh-tw/docs/images/ai/ai-chat-02-portal.webp)

## 助理可以與不能做的事 {#what-the-assistant-can-and-cannot-do}

- **讀取：**它會搜尋您的知識庫與公開說明文件，並透過唯讀工具讀取已登入客戶自己的資料。它無法看見其他客戶。
- **執行：**它使用客戶自己的 API 權限。*讀取*操作會立即執行。任何會變更或產生費用的操作都會建立一個**確認卡片**（「需要您的確認」，帶有 *會產生費用* 或 *刪除* 標籤）；在客戶點擊 **Confirm** 之前不會發生任何事。一個聊天最多可包含 3 張待處理卡片，一個帳號每小時最多可進行 10 次已確認的寫入操作。
- **絕不：**它無法開啟主控台、建立 SSH 或主控台權杖、下載 Kubernetes 存取檔案、重設密碼，或顯示代理伺服器密碼或 S3 機密等機密資訊。機密絕不會放入模型的內容或聊天記錄中。
- **安全性：**其回答會通過輸出過濾器；客戶的文字與工具結果會被視為資料，而非指令。
- **誠信橫幅：**聊天視窗會顯示「由 AI Chat 回答 — 可能不夠完美。若遇重要事項請與真人交談。」

## 人工轉接 {#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}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| 客戶看不到聊天室 | AI 模組關閉，或 **Enable chat widget** 關閉 | 將兩者皆開啟。 |
| "Sign in to use AI Chat" | 訪客未登入 | NexCMP 中的預期行為：請先登入。 |
| 助理表示未設定 AI 提供者 | 提供者遺失、未使用或金鑰遺失 | 完成 [AI provider](https://nexcmp.com/zh-tw/docs/ai/ai-providers/)。 |
| AI 在幾個問題後回覆「talk to a human」 | 已達到每位客戶的每日限制 | 調高 **AI turns / day / customer**。 |
| Telegram 標籤顯示「無頻道」 | 未設定 Bot 或 chat ID | 設定 [Telegram notifications](https://nexcmp.com/zh-tw/docs/administration/telegram-notifications/)。 |
| 缺少 Zalo 或 Telegram 按鈕 | 連結欄位為空白 | 填入連結。 |
| 聊天室中出現「請求過多」 | 單一 IP 每分鐘發送超過 20 則訊息 | 請稍候一分鐘。 |
| 聊天對話已滿 | 已達到 40 則訊息 | 開始新的對話。 |


---

<!-- source: https://nexcmp.com/zh-tw/docs/ai/ai-agent/ -->

# AI Agent {#ai-agent}

> **後台位置：** System › Settings › AI provider (`/settings/ai`) ——模組開關與提供者；System › Admin › License & updates (`/license`) ——模組開關。**portal 位置：** AI Agent (`/ai/agent`) 以及頁面 `/chat/agent`，或聊天室內的 **Agent** 模式。

## 功能 {#what-it-does}

AI Agent 會透過 SSH 連線至客戶自己的 Linux 虛擬機器，並執行以日常語言描述的任務：「檢查系統健康狀態」、「安裝 Docker」、「尋找近期錯誤」、「釋放磁碟空間」。它會顯示所提出的每一道指令及其輸出。唯讀指令可自動執行；任何會變更伺服器的操作都須等待客戶按下 **Run**。

## 需求 {#requirements}

| 項目 | 需求 |
|---|---|
| AI 模組與提供者 | 開啟 **AI** 模組並具備運作中的 [AI provider](https://nexcmp.com/zh-tw/docs/ai/ai-providers/)。Agent 也需要支援工具呼叫的模型。 |
| `openssh-client` 於面板伺服器上 | Agent 使用面板自身的 `ssh` 程式 (`/usr/bin/ssh`) 執行指令。安裝程式會安裝 `openssh-client`；請透過 `ssh -V` 檢查。若無此程式，Agent 會回報「ssh client is not installed on the panel server」。 |
| 無獨立 SSH 通道 | 在預設安裝中，會使用內建 SSH 且**不需要** `ssh-proxy` 網頁終端機。唯有啟用選用的 *web SSH* 功能 (`feature_ssh_web`) 並安裝 `ssh-proxy` 服務時，Agent 才會改透過 `ssh-proxy` 連線。 |
| 網路 | 面板伺服器必須能夠透過 SSH 連接埠（預設為 22）觸達虛擬機器的 IP。請檢查面板與客體網路之間的防火牆與安全性群組。 |
| VM | 客戶所有、**執行中**、未鎖定且為 **Linux**（拒絕 Windows 虛擬機器），並具有公開或可觸達的 IP 位址。 |
| SSH 憑證 | 由 NexCMP 儲存的虛擬機器登入使用者與密碼（建立虛擬機器或重設密碼時儲存，已加密），或安裝了面板的操作金鑰。若兩者皆不存在，Agent 會表示無法登入。 |

## 準備基礎設施 {#prepare-the-infrastructure}

1. 檢查面板伺服器上的 SSH 用戶端：

   ```bash
   ssh -V
   sudo apt-get install -y openssh-client   # only if missing
   ```

2. 檢查面板伺服器是否可對客體虛擬機器開啟 SSH：

   ```bash
   nc -vz 198.51.100.10 22
   ```

   將位址替換為測試虛擬機器的 IP。若此步驟失敗，請先修復路由或防火牆。
3. 確定客體允許 NexCMP 所儲存之使用者的密碼登入（某些雲端映像檔會停用此功能），或客體上已安裝面板的操作金鑰。

## 在 NexCMP 中連線 {#connect-in-nexcmp}

1. 完成 [AI provider](https://nexcmp.com/zh-tw/docs/ai/ai-providers/)：已開啟模組、已儲存提供者、**Test connection** 顯示綠色。
2. 管理端無需設定其他項目。模組開關會讓客戶 portal 中出現 **AI Agent** 項目。
3. 以客戶身分：開啟 **AI Agent**，選擇執行中的伺服器並點擊 **Choose server**。該頁面會先以固定的無害指令探測 SSH（不使用 AI 呼叫），並顯示 *SSH connected* 或失敗原因。
4. 輸入任務或選擇快速啟動（*Check system health*、*Install Docker*、*Install Nginx*、*Find recent errors*、*Security check*、*Free up disk space*）。



## 指令執行方式 {#how-it-runs-commands}

- **來源：**面板伺服器，透過系統 `ssh` 客戶端，一次執行一個非互動式指令。目標永遠是**資料庫中的**虛擬機器 IP，絕非來自請求；僅能連線至擁有者自己的執行中且未鎖定的虛擬機器。
- **驗證：**儲存的密碼會透過處理程序環境中的單次 `SSH_ASKPASS` 輔助程式傳遞——不會寫入磁碟或放入命令列。主機金鑰不進行釘選（虛擬機器會以新金鑰重新安裝）。每個指令的輸出限制為 200 KB，且每個指令皆設有時間限制（60 秒）。
- **Agent 迴圈：**AI 會提出指令並讀取輸出結果；一個回合在最多 **10 個步驟**後結束。
- **模式：**

  | 模式 | 行為 |
  |---|---|
  | **Confirm** | 每個指令皆需等待 **Run**。 |
  | **Auto** | 僅有符合嚴格唯讀允許清單的指令會自動執行（例如 `df -h`、`ps`、`journalctl`）。其他任何內容，以及解析器無法確切分析的內容（變數、指令替代、重新導向至檔案），皆需等待 **Run**。 |

- **風險標籤：**覆寫或刪除檔案、寫入磁碟、變更帳戶或 SSH 金鑰、將資料傳送至外部伺服器、開啟原始網路連線、執行混淆程式碼、下載並執行腳本、關閉或重新啟動機器，或連線至其他伺服器的指令，即使在 Auto 模式下，也一律會顯示 **Needs confirmation**。
- **不受信任的輸出：**指令輸出會作為不受信任的資料顯示給模型；其中的指令將不會被執行。

## 驗證 {#verify}

1. 選擇一部執行中的測試虛擬機器。頁面會顯示 *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 重設。用盡時，Agent 會回答「Daily AI quota reached」。
- **並行限制：**每位客戶同時最多 2 個 Agent 執行；一個工作階段一次執行一個回合。
- **工作階段：**每個工作階段最多 100 則訊息，每則訊息 4,000 個字元。一個工作階段屬於一部虛擬機器；若虛擬機器遭到刪除或轉移，舊的工作階段將變為唯讀。
- **鎖定或停止的虛擬機器，或 Windows：**虛擬機器會顯示為 *Locked*、*Stopped*、*Windows* 或 *No address*，且無法被選取。
- **模擬登入：**管理員模擬登入客戶時，無法使用 Agent 的憑證功能（請參閱 [Log in as a customer](https://nexcmp.com/zh-tw/docs/customers/login-as/)）。
- **責任：**Agent 可能會發生錯誤。門戶網站會提醒客戶在執行指令前進行審查。請在您的服務條款中告知客戶，他們須對自己批准的指令負責。
- 關閉 AI 模組會移除 Agent 項目，且路由會回傳 404 `module_disabled`。

## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| 「控制台伺服器未安裝ssh用戶端 (apt install openssh-client)」 | 沒有 `ssh` 二進位檔 | `sudo apt-get install -y openssh-client`. |
| 「Agent無法登入」/ `ssh: no saved credentials for this VM` | 沒有儲存的密碼且沒有操作金鑰 | 在門戶網站中重設虛擬機器密碼以使其重新儲存，或安裝操作金鑰。 |
| 「伺服器未及時回應」 | 防火牆、SSH 未監聽、虛擬機器忙碌中 | 從面板伺服器測試 `nc -vz <ip> 22`；在虛擬機器中啟動 `sshd`。 |
| "無法連線至此伺服器的 SSH" | 路由或安全性群組 | 允許面板伺服器透過連接埠 22 連線至虛擬機器。 |
| "虛擬機器未執行" / "禁止" | 虛擬機器已停止、鎖定、刪除或不屬於該客戶 | 啟動它、解鎖它或挑選另一台。 |
| "無法使用：N (已停止、鎖定或 Windows)" | 如上方所列之原因 | 該虛擬機器必須為 Linux 且正在執行。 |
| "SSH 閘道暫時無法使用" | Web SSH 功能已啟用但 `ssh-proxy` 已停機 | 啟動 `ssh-proxy`，或關閉 Web SSH 功能以使用內建 SSH。 |
| "AI 回應速度過慢 (超過 90 秒)" | 供應商速度緩慢 | 使用較快的模型或較低的 **Reasoning effort**。 |
| "已達每日 AI 配額" | 已使用 300 次呼叫 | 等待至 00:00 UTC。 |
| "此工作階段仍在執行中" | 另一個回合正在進行中 | 請等待或按下 **Stop**。 |




---

<!-- source: https://nexcmp.com/zh-tw/docs/developers/api/ -->

# REST API

> **在哪裡找到：** 於 `https://<your-domain>/apidoc` (公開) 的 API 參考與 `/api-keys` 的 API 金鑰。**在管理後台哪裡：** Customers › API keys (`/customers/apikeys`) 列出客戶建立的金鑰。

## 功能 {#what-it-does}

客戶能在 portal 中執行的每一個動作——列出並控制虛擬機器、讀取發票、管理 SSH Keys、Kubernetes、儲存空間、支援工單——都能透過 `https://<your-domain>/v1/` 下方的版本化 REST API 來使用。客戶透過具備範圍限制的 **API key** 從腳本和 CI 進行呼叫。相同的 API 也為 [`cmp` command-line tool](https://nexcmp.com/zh-tw/docs/developers/cmp-cli/) 與 [MCP server](https://nexcmp.com/zh-tw/docs/developers/mcp/) 提供資料，且參考文件是從執行中的安裝產生，因此它總是精確列出你已開啟的功能。

## 需求 {#requirements}

| 項目 | 需求 |
|---|---|
| 公開 HTTPS 地址 | API 提供於你的主要網域 (以及每個經銷商自己的網域)。 |
| API 金鑰 | 由客戶在 portal 中建立；請參閱 [API keys](https://nexcmp.com/zh-tw/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_...`）僅適用於入口網站；自動化作業請使用金鑰。
- 金鑰的**範圍**決定了它能呼叫的內容；缺少範圍會回應 HTTP 403 `scope_required`。請參閱 [API keys](https://nexcmp.com/zh-tw/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/zh-tw/docs/billing/quotas/)；在模擬工作階段中不允許此動作。 |
| 404 | `not_found` | 找不到 — 同時也會傳回屬於其他人的資源。 |
| 422 | `invalid_argument` | 驗證錯誤（回應中會列出欄位名稱）。 |
| 429 | `rate_limited` | 請求過多；請等待 `Retry-After`。 |
| 503 | `maintenance` | 維護模式已開啟：讀取正常運作，寫入遭到拒絕。 |

### 速率限制 {#rate-limits}

| 限制 | 預設值 |
|---|---|
| 每個金鑰 | 每分鐘 120 個請求 |
| 每個帳戶（所有金鑰合計） | 每分鐘 300 個請求 |

每個回應皆會帶有 `X-RateLimit-Limit`、`X-RateLimit-Remaining` 與 `X-RateLimit-Reset`；狀態碼 429 則會加上 `Retry-After`。

### 冪等性 {#idempotency}

會產生費用或無法重複執行的指令（建立、變更方案、購買、刪除……）**需要**一個 `Idempotency-Key` 標頭（任何長度達 200 字元的字串；使用 UUID 非常適合）。在逾時後再次傳送相同的金鑰，伺服器會傳回**原始**結果（附帶 `Idempotency-Replayed: 1`）而不是重複執行該操作。重複使用同一個金鑰執行不同的指令會回應 422；仍在處理中的請求會回應 409/`Retry-After`。若沒有此標頭，付費呼叫將會遭到拒絕。

## 驗證 {#verify}

1. 在入口網站中建立具有範圍 `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"` 會列出帳戶的虛擬機器。在入口網站中，金鑰的 **Last used** 欄位與 **Key usage log** 會顯示呼叫記錄。

## 限制與注意事項 {#limits-notes}

- **永不對金鑰開放：**加值、提領、變更卡片或自動加值、變更密碼、電子郵件或雙重認證（2FA）、刪除帳戶、建立、編輯或撤銷其他金鑰。這些操作需要已登入的瀏覽器工作階段。
- **隱藏模組：** 參考資料與 OpenAPI 文件僅列出該網站上啟用的功能。
- **回應大小與分頁：** 清單端點具備分頁功能（`page`、`per_page`）；請參閱各端點的 OpenAPI 文件。
- **時間與金額：** 金額以美金分（USD cents）計，除非欄位名稱另有說明。
- **管理員 API：** 管理主控台有自己的 **System › Admin › API** 頁面以及用於管理的管理者金鑰（`ofw_...`）；它們與此處描述的客戶端 API 是分開的。
- **版本控制：** 路徑前綴 `/v1` 是穩定的；回應中可能會新增欄位。

## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| 新金鑰回傳 401 | 金鑰來自其他網域、已過期，或輸入時帶有空格 | 請在您呼叫的網域上建立金鑰；檢查 `Authorization: Bearer vk_...` 標頭。 |
| 403 `scope_required` | 缺少範圍 | 在portal中編輯金鑰並新增範圍。 |
| 401 `key_ip_denied` 或 `site_mismatch` | 金鑰受限於其他 IP（「允許的 IP」）或在其他網域上建立 | 將您伺服器的 IP 新增至金鑰的允許 IP，或呼叫建立該金鑰的網域。 |
| 現有虛擬機器回傳 404 | 該虛擬機器屬於其他帳戶 | 使用擁有者的金鑰。 |
| 400/422 要求 `Idempotency-Key` | 未帶標頭的付費操作 | 新增 `Idempotency-Key: <uuid>`。 |
| 429 | 超出限制 | 請稍候再試；使用 `Retry-After`。 |
| `/apidoc` 顯示的內容少於預期 | 模組已關閉 | 在 License & updates 中啟用此模組。 |




---

<!-- source: https://nexcmp.com/zh-tw/docs/developers/api-keys/ -->

# API 金鑰與範圍 {#api-keys-and-scopes}

> **Portal 位置：** API keys (`/api-keys`)。**Admin 位置：** Customers › Customers › API keys (`/customers/apikeys`)。

## 功能 {#what-it-does}

**API key** 允許腳本、CI 作業、[`cmp` CLI](https://nexcmp.com/zh-tw/docs/developers/cmp-cli/) 或 AI 助理 ([MCP](https://nexcmp.com/zh-tw/docs/developers/mcp/)) 代表單一客戶呼叫 [REST API](https://nexcmp.com/zh-tw/docs/developers/api/)，且僅具備被授與的權限（**scopes**）。客戶金鑰以 `vk_` 開頭。它們可以讀取和管理服務，但**絕不能**觸及金錢或帳戶本身。

## 需求 {#requirements}

| 項目 | 需求 |
|---|---|
| 客戶 | 已登入的 portal 工作階段（金鑰無法建立或編輯其他金鑰，冒充客戶的管理員亦然）。 |
| 切換開關 | API 金鑰預設為開啟。如果關閉，呼叫將回傳 401 `api_keys_disabled`。 |
| 相依項目 | 產品的範圍僅在該網站啟用該產品時才會顯示。 |

## 建立金鑰（客戶） {#create-a-key-customer}

1. 登入 portal 並開啟 **API keys**。
2. 按一下 **Create key**。
3. 填寫表單：

   | 欄位 | Rule |
   |---|---|
   | **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. Portal 同時也會顯示一個現成的 `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:write` | 電源操作、微幅變更、防火牆、快速快照。 |
| `vm:create` | **建立虛擬機器（會產生費用）。** |
| `vm:plan` | **變更方案或調整大小（會產生費用）。** |
| `vm:destroy` | **刪除虛擬機器。** |
| `vm:restore` | **從快照還原虛擬機器（將覆寫磁碟）。** |
| `vm:console` | 開啟 VNC 主控台工單。 |
| `sshkey:read`, `sshkey:write` | 讀取、新增與移除 SSH Keys。 |
| `volume:read`, `volume:write`, `volume:create`, `volume:destroy` | 資料磁碟區（建立與擴充會產生費用；銷毀會遺失資料）。 |
| `backup:read`, `backup:write`, `backup:restore` | Backups（還原將會覆寫磁碟）。 |
| `billing:read` | 錢包、發票、付款記錄 — **僅限讀取**。 |
| `bandwidth:buy` | **購買頻寬附加元件（會產生費用）。** |
| `account:read`, `account:write` | 個人資料、總覽、活動、通知；`account:write` 僅將通知標示為已讀。 |
| `apikey:read` | 列出帳戶的金鑰與使用記錄（無法建立、編輯或撤銷）。 |
| `apikey:self` | 每個金鑰的隱含權限：檢查呼叫端金鑰（`GET /v1/apikeys/self`）。 |
| `ticket:read`, `ticket:write` | 支援工單。 |
| `aff:read`, `transfer:read` | 聯盟計畫與服務轉移 — 僅限讀取。 |
| `k8s:read`, `k8s:write`, `k8s:create`, `k8s:scale`, `k8s:destroy`, `k8s:kubeconfig` | Kubernetes（建立與擴展會產生費用；kubeconfig 具備 cluster-admin 權限）。 |
| `vpc:read`, `vpc:write`, `vpc:create`, `vpc:destroy` | Private Cloud。 |
| `image:read`, `image:write` | 作業系統與 ISO 映像檔（儲存空間採按小時計費）。 |
| `s3:read`, `s3:write`, `s3:create`, `s3:destroy`, `s3:keys` | Object Storage（S3 金鑰僅顯示一次）。 |
| `vpn:read`, `vpn:detail`, `vpn:write`, `vpn:create`, `vpn:destroy` | VPN 與 IPv6 Proxy（連線詳細資料包含 Proxy 密碼）。 |
| `dedicated:read`, `dedicated:write`, `dedicated:console`, `dedicated:create`, `dedicated:destroy` | 實體伺服器（從錢包建立訂單；銷毀會重新安裝作業系統）。 |
| `shield:read`, `shield:write`, `shield:agent` | DDoS Shield，僅在啟用該模組時適用。 |

超出金鑰範圍的呼叫會回傳 **403 `scope_required`**；金鑰無權呼叫的路徑會回傳 **403 `endpoint_not_public`**。

### 金鑰絕對無法執行的操作 {#what-a-key-can-never-do}

任何範圍皆無法執行以下操作：加值或提領資金、變更信用卡或自動加值、變更密碼、電子郵件或 2FA、刪除帳戶、以及建立、編輯或撤銷其他金鑰。這些操作一律需要透過已登入的瀏覽器執行。即使金鑰遭洩漏，也無法碰觸客戶的資金或帳戶。

## 您可以信賴的規則 {#rules-you-can-rely-on}

| Rule | Detail |
|---|---|
| Site-bound | 金鑰僅在建立它的網站（網域）上有效。 |
| 速率限制 | 每個金鑰與每個帳戶：預設分別為每分鐘 120 次與 300 次請求。 |
| 冪等性 | 會產生費用或無法重複執行的操作需要 `Idempotency-Key` 標頭。 |
| 配額 | 金鑰受限於與客戶相同的 [quotas](https://nexcmp.com/zh-tw/docs/billing/quotas/)。 |
| Locked account | 已鎖定客戶的金鑰會停止運作（403 `account_blocked`）。 |
| 稽核 | 管理員執行的撤銷動作會寫入管理員稽核記錄。 |

## 管理員檢視 {#administrator-view}

1. 開啟 **Customers › API keys**（`/customers/apikeys`）。表格會顯示金鑰名稱與前幾個字元、擁有者、範圍、狀態、最後使用時間（時間、請求次數、IP）及到期日。
2. 若您有經銷商，可依站台篩選。亦可依名稱、ID 或金鑰開頭搜尋。
3. 點擊 **Revoke** 以停用現有金鑰，或點擊 **Log** 查看其使用記錄。
4. 管理員**可以檢視與撤銷**金鑰，但無法為客戶讀取或建立金鑰。

![客戶 API 金鑰的管理員清單，包含範圍、狀態、最後使用時間與 Revoke 按鈕](https://nexcmp.com/zh-tw/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}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| 錯誤 `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/zh-tw/docs/developers/cmp-cli/ -->

# `cmp` 指令列工具 {#cmp-command-line-tool}

> **在入口網站中的位置：**安裝指令位於API參考文件（`https://<your-domain>/apidoc`，Command-line interface章節）。核准登入：`https://<your-domain>/link`。已連線裝置：API keys (`/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/zh-tw/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
```

安裝程式會選擇對應作業系統與 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/zh-tw/docs/images/developers/cmp-cli-01-install.webp)

## 登入 {#log-in}

```bash
cmp login
```

1. CLI 會印出一次性 **code** 與連結（`https://cloud.example.com/link?code=WDJB-MJHT`），開啟瀏覽器並等待。
2. 在瀏覽器中登入 portal，檢查客戶名稱、裝置、IP 與國家/地區，勾選權限（scopes）並選擇金鑰的有效期限（預設 90 天）。涉及付費或刪除資料的權限預設為未勾選。點擊核准。
3. CLI 會收到**專屬金鑰**（與客戶手動建立的金鑰分開），並將其儲存於 `~/.config/cmp/config.json`（權限模式為 `0600`；在 Windows 上為 `%APPDATA%\cmp`）。它會顯示在 **API keys › Connected apps & devices** 底下，並可在該處撤銷。

代碼會在 10 分鐘後過期。核准需要真實的已登入 portal 工作階段且具備已驗證的電子郵件——不能使用其他金鑰，也不能使用模擬（impersonated）工作階段。

實用的旗標（flags）：`--scopes vm:read,billing:read`、`--name "build server"`、`--no-browser`、`--profile`、`--api-url`。

若是 CI 或沒有瀏覽器的伺服器，請使用來自 portal 的金鑰：

```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]
```

- 路徑參數為位置引數；查詢參數與內文欄位則成為 kebab-case 旗標（`--start-port 443`）。
- `--data '{"a":1}'`、`--data @file.json` 或 `--data -` 可傳送整段 JSON 內文；旗標會覆寫其欄位。
- `cmp help vm firewall add`（或 `--help`）會顯示任何指令的詳細資訊。

```bash
cmp catalog plans
cmp vm list --state active --per-page 50
cmp vm get 3f2a1c9e-0000-4000-8000-000000000000
cmp vm start 3f2a1c9e-0000-4000-8000-000000000000
cmp vm firewall add 3f2a1c9e-... --protocol tcp --start-port 22 --cidr-list 203.0.113.0/24
cmp billing wallet
cmp api GET /v1/vm --query page=2      # raw call to any endpoint
```

內建指令：`login`、`logout`、`whoami`、`config`、`api`、`completion`、`version`、`update`、`help`。其餘皆來自 API 文件。

全域旗標：

| 旗標 | 含意 |
|---|---|
| `-o, --output json\|table\|yaml` | 格式。在終端機預設為 `table`，使用管線傳輸時預設為 `json`。 |
| `--profile`, `--api-url` | 指定的儲存登入與網站。 |
| `-y, --yes` | 略過具破壞性或付費指令的確認步驟。 |
| `--idempotency-key <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'
```

Shell 自動補全：`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` 會顯示設定檔與你的面板網址。
3. `cmp vm list` 傳回你的虛擬機器；`cmp vm list -o json | jq .` 顯示原始 JSON。

## 限制與注意事項 {#limits-notes}

- 指令清單取決於你的建置：這些套件是在發布建置時從你安裝的 OpenAPI 文件所產生，因此在你的版本中停用的產品將不會有對應指令。若遇到 CLI 不知的路徑，請使用 `cmp api`。
- CLI 採用 MIT 授權條款。
- 每個套件皆以 ed25519 金鑰簽署；簽章金鑰內嵌於安裝程式與二進位檔中，不會在更新時擷取。
- 每個金鑰與每個帳戶皆設有金鑰數量限制（請參閱 [REST API](https://nexcmp.com/zh-tw/docs/developers/api/#rate-limits)）。

## 故障排除 {#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 網址 | 使用 `https://`，或僅在測試環境使用 `CMP_ALLOW_HTTP=1`。 |
| 瀏覽器開啟了錯誤的網站 | 未針對經銷商設定 `--api-url` | `cmp login --api-url https://<reseller-domain>`. |




---

<!-- source: https://nexcmp.com/zh-tw/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`等），因此客戶可以詢問他們的助理「我的哪些虛擬機器正在執行？」或「停止staging虛擬機器」。助理僅會透過客戶自身的API金鑰與權限進行操作。

::: tip 要使用AI設定NexCMP本身嗎？
此頁面為**客戶**MCP端點（`/mcp`）。若要讓AI助理以管理員身分設定您自己的面板，請參閱[Configure with AI](https://nexcmp.com/zh-tw/docs/configure-with-ai/mcp-admin/)（端點`/mcp/admin`，管理員金鑰`ak_`）。
:::

## 需求 {#requirements}

| 項目 | 需求 |
|---|---|
| 伺服器 | 無需安裝：此端點由面板提供，只要面板可連線之處即可存取。您的反向代理伺服器必須將`/mcp`轉發至面板。 |
| 客戶 | 具備助理所需範圍的[API金鑰](https://nexcmp.com/zh-tw/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. 在入口網站（**API keys › Create key**）中建立一個API金鑰，僅包含您希望助理使用的範圍、較短的有效期限，以及可能的話，限制IP來源。
2. 將伺服器新增至您的客戶端。請替換`cloud.example.com`與金鑰。

   **Claude Code**

   ```bash
   claude mcp add --transport http cloud https://cloud.example.com/mcp \
     --header "Authorization: Bearer vk_XXXX"
   ```

   **Cursor**（`~/.cursor/mcp.json`或`.cursor/mcp.json`；在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_...`（工作階段權杖、Cookie與管理員金鑰會被拒絕並回傳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}

| 限制 | 預設值 |
|---|---|
| 每個金鑰的工具呼叫數 | 每分鐘 60 次 |
| 每個金鑰的 MCP 請求數 | 每分鐘 240 次 |
| 外加一般金鑰與帳戶限制 | 請參閱 [REST API](https://nexcmp.com/zh-tw/docs/developers/api/#rate-limits) |

超過限制時，端點會回應 HTTP 429 以及 JSON-RPC 錯誤與 `Retry-After`。

## 驗證 {#verify}

1. 上述 `curl` 指令會傳回包含 `tools` 清單的 JSON-RPC 結果。只有符合金鑰範圍的工具才會顯示。
2. 在您的用戶端中詢問「列出我的虛擬機器」：助理會呼叫 `vm_list` 並顯示結果。
3. 在入口網站中，該金鑰的 **Last used** 時間會更新，且寫入呼叫會顯示在 **Key usage log** 中。

## 限制與注意事項 {#limits-notes}

- **瀏覽器登入 (OAuth)。** 參考頁面也說明瞭針對支援 MCP OAuth 的用戶端透過瀏覽器登入。在已安裝的 NexCMP 中，支援且經過測試的方法是 API 金鑰（或適用於 CLI 的 `cmp login`）。
- **經銷商站台**不顯示 MCP 區段；其客戶使用經銷商的網域來存取 API。
- **最低權限原則。** 為每個助理建立一個專用金鑰，並優先賦予讀取範圍；僅在需要時才新增寫入範圍。
- 在 **API keys** 中撤銷金鑰即可立即切斷助理的存取權。

## 故障排除 {#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/zh-tw/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、建立區域、根據成本建立方案表、設定電子郵件、付款與品牌、尋找客戶，或匯出整個設定。助理透過一組固定的**管理工具**運作。它永遠不會取得shell、永遠不會讀取伺服器上的檔案，也永遠不會看到儲存的密碼或API key。

當您希望在幾分鐘內完成首次設定，而不必點擊十幾個頁面時，或者當您管理多個安裝並希望將其設定保留在檔案中時，請使用此功能。

## 使用的三種方式 {#three-ways-to-use-it}

| 方式 | 誰與AI對話 | 執行位置 | 從這裡開始 |
|---|---|---|---|
| **管理後台中的 AI Chat** | 您，在NexCMP管理後台中 | 您選擇的AI來源：來自OpenAI、Anthropic、Gemini或OpenRouter的API key、您面板自己的AI提供者，或是您登入的官方AI CLI | [管理員中的 AI Chat](https://nexcmp.com/zh-tw/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/zh-tw/docs/configure-with-ai/mcp-admin/) |
| **設定即程式碼** | 您或某個腳本 | 伺服器上的YAML檔案與 `nexcmp config` 指令（或「匯入/匯出」頁面） | [Configuration as code](https://nexcmp.com/zh-tw/docs/configure-with-ai/config-as-code/) |

這三者都會呼叫相同的工具並透過相同的安全層，因此您可以將它們混合使用：用助理起草設定、將其匯出為YAML、在您的編輯器中檢閱並稍後套用。

## 安全模型 {#safety-model}

| Rule | 這對您的意義 |
|---|---|
| **範圍** | 金鑰或連線僅限於您勾選的範圍（`admin:read`、`catalog:write`、`infra:write`、`billing:write`、`customers:write`、`settings:write`、`ai:write`、`secrets:write`）。若無範圍，呼叫將被拒絕。請參閱 [Admin API keys](https://nexcmp.com/zh-tw/docs/configure-with-ai/admin-api-keys/#scopes)。 |
| **Expiry** | 每個金鑰與連線都會過期：您建立的金鑰為1到90天，預設為30天。OAuth存取權杖持續一小時。 |
| **IP限制與速率限制** | 金鑰可限制於IP範圍及每分鐘的呼叫次數（預設為120次）。 |
| **雙步驟確認** | 移動資金、刪除資料、變更付款憑證或變更登入安全性的動作會先傳回預覽，在您核准之前不會執行任何動作。在AI Chat內部，每個變更都是一張您可以自行按下的確認卡片。 |
| **金鑰絕對不能做的事** | 建立管理員、變更2FA、建立或撤銷金鑰、以客戶身分登入、備份、還原或更新面板等。這些操作需要您在管理後台親自執行。 |
| **活動記錄** | 無論允許或拒絕，每次呼叫都會記錄金鑰、用戶端、工具、IP與結果。請參閱 System › Settings › API & AI agents › Activity. |
| **絕不回傳機密** | 密碼、API keys與權杖可以設定但絕不能被讀回。AI看到的回答會將其顯示為遮罩狀態。 |
| **展示安裝為唯讀** | 在示範面板上，所有寫入動作都會被 `demo_read_only` 拒絕。 |

::: important AI可以讀取的內容
透過 `admin:read`，助理可以讀取客戶姓名、電子郵件地址、餘額與帳單記錄。當您使用在供應商（OpenAI、Anthropic、Google、OpenRouter）執行的AI source時，該資料會傳送給該供應商以回答您的問題。請賦予助理其所需的最少權限範圍，並選擇您信任能處理該資料的source。
:::

## 快速入門 {#quick-start}

1. 登入管理後台並開啟 **AI Chat**。如果尚未連接任何AI source，請開啟 **System › Settings › AI accounts** 並連接一個（請參閱 [AI accounts and subscriptions](https://nexcmp.com/zh-tw/docs/configure-with-ai/ai-accounts-and-subscriptions/)）。
2. 輸入「Check my setup progress」並按下Enter。助理會讀取 [Setup progress checklist](https://nexcmp.com/zh-tw/docs/configure-with-ai/setup-checklist/) 並告訴您還剩下什麼。
3. 要求它執行下一步。檢視每個確認卡片並按下 **Confirm** 以套用。

若要首次了解可以詢問什麼，請參閱 [Example prompts](https://nexcmp.com/zh-tw/docs/configure-with-ai/example-prompts/)。

![包含對話、工具結果與確認卡片的AI Chat頁面](https://nexcmp.com/zh-tw/docs/images/configure-with-ai/overview-01-ai-chat.webp)

## 限制與注意事項 {#limits-notes}

- **Demo and read-only。** 這些頁面在示範面板上可見，但在那裡無法儲存任何東西。
- **No shell。** 助理只能呼叫 [Connect an AI client](https://nexcmp.com/zh-tw/docs/configure-with-ai/mcp-admin/#tools) 中列出的管理工具。它無法在伺服器上執行指令。
- **網路與路由模組**（BGP、XDP、介面、NAT等）對AI而言是唯讀的，而管理員帳戶、備份與更新等敏感區域則完全不對keys開放。
- **價格**以USD計算：方案價格為每小時美元，餘額以美分計算。
- **成本。** AI回答的費用需支付給您連接的AI source（API使用費，或您自己的訂閱）。在AI Chat中您可以設定每日花費上限。關於NexCMP授權模式，請參閱 https://nexcmp.com/pricing。

## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| AI Chat顯示未連接AI source | 您的管理員帳戶未設定source | 開啟System › Settings › AI accounts並連接一個。 |
| 助理回答 `insufficient_scope` | key或連線缺少該工具的權限範圍 | 建立具有所需權限範圍的key，或重新連線並在同意畫面上勾選它。請參閱 [Admin API keys](https://nexcmp.com/zh-tw/docs/configure-with-ai/admin-api-keys/#errors)。 |
| 每個變更都顯示確認卡片 | AI Chat中的預期行為 | 按下 **Confirm** 以套用或按下 **Reject** 以取消。 |
| 寫入失敗並顯示 `demo_read_only` | 面板處於示範模式 | 請使用非示範安裝。 |


---

<!-- source: https://nexcmp.com/zh-tw/docs/configure-with-ai/ai-chat-in-admin/ -->

# 管理後台中的AI Chat {#ai-chat-in-the-admin}

> **在管理後台中的位置：** AI Chat（`/agent`，其專屬選單項目）以及每個管理頁面上的浮動 **Ask AI** 按鈕。回答source是在System › Settings › AI accounts中設定（`/agent/accounts`）。

## 功能 {#what-it-does}

AI Chat是內建於管理後台中的助理。您描述您想要做的事（「connect my Proxmox cluster」、「set up email」），助理會透過管理工具讀取目前狀態、提出變更建議，並將每個變更顯示為**確認卡片**。在您按下 **Confirm** 之前，不會套用任何變更。 **Ask AI** 面板是狹窄側邊面板中的相同聊天視窗，因此您可以在檢視頁面時進行詢問。諸如 **Do it for me** 等按鈕（位於 [Setup progress checklist](https://nexcmp.com/zh-tw/docs/configure-with-ai/setup-checklist/) 中以及空白列表中）會以準備好的問題開啟它。

這不是面向客戶、為您的客戶服務的 [AI Chat](https://nexcmp.com/zh-tw/docs/ai/ai-chat/) 與 [AI Agent](https://nexcmp.com/zh-tw/docs/ai/ai-agent/)。

## 需求 {#requirements}

| 項目 | 需求 |
|---|---|
| 角色 | 已登入的管理員。對話、金鑰與偏好設定歸屬於您的管理員帳號；其他管理員無法看見。 |
| 回答來源 | 至少連線一項：API 金鑰、登入狀態、面板自身的 AI 提供者，或您已登入的 AI CLI。請參閱 [AI accounts and subscriptions](https://nexcmp.com/zh-tw/docs/configure-with-ai/ai-accounts-and-subscriptions/)。 |
| Demo | 在展示面板中，您可以讀取舊對話，但無法傳送訊息。 |

## 選擇回答的來源 {#choose-where-answers-come-from}

在輸入框下方的選單中挑選來源（會列出您已連線的來源）。**System › Settings › AI accounts** 也讓您能設定預設來源、預設模型與每日上限。

| Source | 如何連線 | 注意事項 |
|---|---|---|
| OpenAI (ChatGPT models) | 貼上來自 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** | 一個帳號即可使用多個模型。 |
| Panel AI provider | 已在 System › Settings › AI provider 中設定 | 與您的客戶 AI Chat 所使用的提供者相同。[AI provider](https://nexcmp.com/zh-tw/docs/ai/ai-providers/)。 |
| Claude、ChatGPT 或 Gemini 訂閱 | 官方 CLI 已安裝並已登入面板伺服器 | 請參閱 [AI accounts and subscriptions](https://nexcmp.com/zh-tw/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/zh-tw/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/zh-tw/docs/images/configure-with-ai/ai-chat-in-admin-02-confirm.webp)

## 機密 {#secrets}

密碼與 API 金鑰不得透過聊天文字傳送。請使用輸入框旁邊的 **Secret** 欄位（鎖頭圖示）：

1. 點擊鎖頭圖示並輸入**名稱**（英文字母、數字與底線，例如 `smtp_password`）以及**值**。
2. 在你的訊息中參照該名稱：「use the secret smtp_password as the SMTP password」。
3. 助理永遠只會看到代表該機密的預留位置，寫法如下：

   ```text
   {{secret:smtp_password}}
   ```

   面板會在執行工具的當下將其替換為真實值。該值不會儲存在聊天記錄中，也不會傳送至 AI 來源。

如果你不小心將看起來像金鑰的內容貼入訊息中，面板會將其移至相同的受保護儲存區並在記錄中遮罩，但請將此視為安全網而非正規方法。機密僅保留在面板的記憶體中，適用於輸入它們的對話，以及最後一則訊息後的至多一小時；面板重新啟動也會清除它們。若助理要求，請重新輸入。

設定機密也需要聊天工作階段的 `secrets:write` 權限（見下方）。

## 聊天的權限 {#permissions-of-the-chat}

每則訊息皆使用一個僅存在於回答期間（最長 15 分鐘）的暫時金鑰執行，該金鑰僅能從主控台伺服器運作，且只能透過確認卡片使用。其權限範圍為 **System › Settings › AI accounts › Chat session permissions** 中勾選的項目。`admin:read` 隨時保持開啟。除 `secrets:write` 外的所有範圍預設皆為開啟；若您希望助理能夠設定密碼與金鑰（透過 Secret 欄位），請勾選 `secrets:write`。在展示主控台中，對話為唯讀狀態。

## Daily spending cap {#daily-spending-cap}

AI Chat 會加總來自 API 來源之回答的估算成本。預設上限為**每位管理員每天 5 USD**。您可以在 **AI accounts › Defaults for AI Chat** 下設定其他金額（0 代表無限制）。該頁面會顯示「今日已使用金額」。當達到上限時，對話將拒絕新訊息（`daily_cap`），直到隔天或您調高上限為止。AI CLI 訂閱類型的來源不計入其中，因為它們是依您的訂閱方案計費。

## 驗證 {#verify}

1. 在 **AI accounts** 中點擊該來源上的 **Test**。系統會回覆模型名稱與毫秒為單位的時間。
2. 在 AI Chat 中詢問「Check my setup progress」。答案會列出 [checklist](https://nexcmp.com/zh-tw/docs/configure-with-ai/setup-checklist/) 中的步驟，並出現一個 `setup_checklist` 工具卡片。
3. 要求進行小幅變更，例如「Set the brand name to Example Cloud」。畫面上會出現確認卡片；按下 **Confirm** 並檢查 Branding 頁面。
4. **API & AI agents › Activity** 會列出帶有通道 `chat` 的呼叫記錄。

## 限制與注意事項 {#limits-notes}

- 助理沒有 shell，也無法讀取伺服器上的檔案。它只會呼叫 [admin tools](https://nexcmp.com/zh-tw/docs/configure-with-ai/mcp-admin/#tools)。
- 金鑰永遠無法執行的變更（[list](https://nexcmp.com/zh-tw/docs/configure-with-ai/admin-api-keys/#what-a-key-can-never-do)）也無法從 AI Chat 執行。
- 檢查模型的執行結果。確認卡片會準確顯示將要傳送的內容；請仔細閱讀，特別是價格與金額。
- API 回應會由 AI 供應商計費。上限僅供參考；請同時在供應商端設定消費限額。
- CLI 回應會在 5 分鐘後停止。

## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| "已達到今日 AI 支出上限" (`daily_cap`) | 您已達到每日上限 | 請在 AI 帳戶中提高上限，或等待明天。 |
| 「另一個回答仍在執行中 - 請稍候或按停止」 (`busy`) | 每個管理員同時只能有一個回答 | 按 **Stop** 或稍候。 |
| 來源未顯示在選取器中 | 尚未連線，或是 (Claude CLI)「我了解」開關已關閉 | 請在 AI 帳戶中進行連線。 |
| 「這看起來不像 API 金鑰」 | 貼上的金鑰包含空白或過長 | 請僅貼上金鑰。 |
| 測試失敗 | 金鑰錯誤、額度不足或供應商斷線 | 請檢查供應商的金鑰與帳單。 |
| 助理表示無法執行某項操作 | 聊天工作階段缺少權限範圍，或者該動作對 AI 關閉 | 請在 AI 帳戶中勾選權限範圍，或在管理後台執行。 |
| 卡片顯示已過期 | 已超過 5 分鐘 | 請要求助理再次提出變更建議。 |
| CLI 來源回報「使用量限制」或「未登入」 | 您的訂閱限制或工作階段 | 請重新登入或稍候；請參閱 [AI 帳戶與訂閱](https://nexcmp.com/zh-tw/docs/configure-with-ai/ai-accounts-and-subscriptions/)。 |


---

<!-- source: https://nexcmp.com/zh-tw/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/zh-tw/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 用戶端（用戶端 ID 以 `.apps.googleusercontent.com` 結尾，外加其密碼）。NexCMP 未隨附共用的 Google 用戶端。 |
| Panel AI provider | 使用已在 System › Settings › AI provider（[AI provider](https://nexcmp.com/zh-tw/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/zh-tw/docs/configure-with-ai/ai-chat-in-admin/#daily-spending-cap)。 |
| 聊天工作階段權限 | 助理可使用的範圍。`admin:read` 預設為開啟；`secrets:write` 預設為關閉。請參閱 [Admin API keys](https://nexcmp.com/zh-tw/docs/configure-with-ai/admin-api-keys/#scopes)。 |

點擊**Save defaults**。

## 使用您自己的AI訂閱方案 {#use-your-own-ai-subscription}

您可以使用您已經付費的Claude、ChatGPT或Gemini方案來驅動NexCMP，而無需額外申請API金鑰。有兩種方法可供選擇。

### 方法 1（推薦）：在您自己的電腦上使用CLI {#way-1-recommended-the-cli-on-your-own-computer}

您可以在自己的電腦上使用供應商自己的工具，並以供應商的正常方式登入您自己的帳戶。NexCMP只會接收以短期金鑰簽署的MCP呼叫。開啟 **AI accounts › Use your own AI subscription**；每個工具會顯示三個步驟。

1. 點擊**Create a 7-day key**並選擇層級：**Read only**（`admin:read`）或 **Read + configuration**（`admin:read`、`catalog:write`、`infra:write`、`settings:write`）。下方的指令隨即會包含實際的金鑰。
2. 安裝CLI並登入。金鑰只會在此頁面顯示一次。

   | 工具 | 安裝 | 登入 |
   |---|---|---|
   | Claude Code | `npm install -g @anthropic-ai/claude-code` | 執行 `claude`，然後執行 `/login` |
   | Codex CLI | `npm install -g @openai/codex` | `codex login` |
   | Gemini CLI | `npm install -g @google/gemini-cli` | 執行 `gemini`，選擇「Login with Google」 |

3. 使用從頁面複製的單一指令或程式碼區塊，將其連線至您的面板：

   ```bash
   # Claude Code
   claude mcp add --transport http nexcmp https://cloud.example.com/mcp/admin \
     --header "Authorization: Bearer ak_XXXX"
   ```

   ```toml
   # Codex CLI: ~/.codex/config.toml, then: export NEXCMP_KEY=ak_XXXX
   [mcp_servers.nexcmp]
   url = "https://cloud.example.com/mcp/admin"
   bearer_token_env_var = "NEXCMP_KEY"
   ```

   ```json
   // Gemini CLI: ~/.gemini/settings.json
   { "mcpServers": { "nexcmp": {
       "httpUrl": "https://cloud.example.com/mcp/admin",
       "headers": { "Authorization": "Bearer ak_XXXX" } } } }
   ```

4. 啟動工具並詢問，例如：「what is left to set up in nexcmp?」。MCP連線的所有詳細資訊均在 [Connect an AI client](https://nexcmp.com/zh-tw/docs/configure-with-ai/mcp-admin/) 中說明。

同一分頁亦顯示 **claude.ai** 與 **ChatGPT** 連接器的URL，其透過OAuth登入且不需要金鑰：[OAuth connectors](https://nexcmp.com/zh-tw/docs/configure-with-ai/oauth-connectors/)。

![帶有 7 天金鑰按鈕以及三個 CLI 的安裝、登入與連線指令的「使用您自己的 AI 訂閱」分頁](https://nexcmp.com/zh-tw/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 工具（shell 與檔案工具為關閉狀態），並且僅限伺服器端使用的金鑰。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 卡片上的 I understand 開關](https://nexcmp.com/zh-tw/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，則輸入您的 2FA 代碼）並開啟工作階段。橫幅會提醒您，此處的指令只能透過其 MCP 工具管理 NexCMP；shell 與檔案工具已被停用。
- 展示安裝絕不會建立 `nexcmp-ai` 使用者。

![帶有 CLI 選擇器、密碼欄位與僅支援 MCP 警告橫幅的 AI Console 啟動畫面](https://nexcmp.com/zh-tw/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}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| 登入已停用，且卡片顯示「AI tools are not ready on the server yet」 | `nexcmp-ai` 服務未執行 | 將面板更新至最新版本，然後檢查 `sudo nexcmp status`。在唯讀展示中這是正常的。 |
| "此伺服器尚未安裝 AI 工具" | `nexcmp-ai` 服務未執行（較舊的面板或展示面板） | 更新面板，然後 `sudo nexcmp ai-console install claude`（或 `codex`、`gemini`）。 |
| 關於 RAM 低於 2 GB 的警告 | 伺服器規格較小 | 安裝可能會很慢或失敗；請增加記憶體或使用方式 1。 |
| 「Node.js download checksum mismatch」或「download failed」 | 伺服器無法連線至 nodejs.org，或是代理伺服器修改了下載內容 | 請允許外向 HTTPS 流量並重試。 |
| 安裝以錯誤收尾 | npm 無法安裝此套件 | 請讀取卡片上的記錄檔，檢查對 npm 登錄檔的對外連線，然後重試。 |
| 登入以錯誤收尾或逾時 | 10 分鐘的時間視窗已過，或是驗證碼錯誤 | 再次點擊 **Login** 並更快完成。 |
| 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/zh-tw/docs/configure-with-ai/admin-api-keys/ -->

# Admin API keys {#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/zh-tw/docs/developers/api-keys/)）。這些金鑰僅能存取客戶 API 與 `/mcp`。客戶 API 會拒絕 `ak_` 金鑰，而管理員 API 會拒絕 `vk_` 金鑰。
:::

## 需求 {#requirements}

| 項目 | 需求 |
|---|---|
| 角色 | 您必須登入管理員帳號。金鑰無法建立其他金鑰。 |
| Demo | 在展示面板上此頁面為唯讀：無法建立或撤銷任何金鑰。 |
| Reachability | 用戶端必須能夠連線至您面板上的 `https://cloud.example.com/mcp/admin` 或 `/v1/admin/...`（若您使用IP限制，請檢查防火牆設定）。 |

## Create a key {#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`。 |
   | Expiry | 1、7、30、60或90天。預設為30。上限為90。無法建立未設定到期日的金鑰。 |
   | IP ranges (optional) | 每行一個IPv4、IPv6位址或CIDR，例如 `203.0.113.0/24` 或 `2001:db8::/48`。最多32個。留空則允許所有IP。 |
   | Calls per minute | 1 to 6000. Default 120. |

4. 點擊 **Create key**。對話方塊會顯示金鑰一次，例如 `ak_XXXX`。**請立即複製**：NexCMP僅儲存雜湊值，且絕無法再次顯示。
5. 點擊 **I have saved the key**。開啟 **Connect an AI** 分頁即可取得內含您剛剛建立之金鑰的隨貼即用指令（僅在此頁面有效，直到您重新載入頁面為止）。

![填入名稱、權限範圍核取方塊、到期日與IP範圍的新金鑰對話方塊](https://nexcmp.com/zh-tw/docs/images/configure-with-ai/admin-api-keys-01-create.webp)

![顯示新金鑰一次並附帶複製按鈕與警告的對話方塊](https://nexcmp.com/zh-tw/docs/images/configure-with-ai/admin-api-keys-02-shown-once.webp)

## Scopes {#scopes}

金鑰僅能使用其權限範圍所允許的工具與端點。寫入權限不包含讀取存取權：需要同時讀取與寫入的金鑰也必須具備 `admin:read`。

| Scope | What it allows |
|---|---|
| `admin:read` | 讀取設定、目錄、客戶、帳務與記錄。絕不會傳回機密資料。 |
| `catalog:write` | 方案、作業系統範本、配額、折扣碼。 |
| `infra:write` | 基礎架構來源（CloudStack、Proxmox）、區域、伺服器。 |
| `billing:write` | 支付閘道、貨幣、發票、餘額。金錢相關動作需要確認。 |
| `customers:write` | 客戶與經銷商。 |
| `settings:write` | 一般設定、品牌、電子郵件、法律頁面、模組、通知。 |
| `ai:write` | AI 提供者與 AI 功能。 |
| `secrets:write` | 寫入密碼與 API 金鑰。它們可以被設定，但永遠無法被讀取出來。 |

::: tip 設定密鑰需要兩個範圍
任何攜帶密碼、API 金鑰或權杖值的呼叫（例如 SMTP 密碼、付款金鑰、Telegram Bot 權杖、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 主控台。
- 備份或還原面板、更新面板，或變更其授權。
- 以客戶或經銷商身分登入、開啟客戶的主控台、讀取虛擬機器憑證或 kubeconfig、設定 SSH 金鑰，或傳送或重設密碼。
- 變更網路與路由模組（BGP、FRR、RTBH、XDP、介面、靜態與原則路由、NAT）或外部代理程式與入口整合。這些皆為唯讀。
- 變更諸如 `demo_*`、`admin_*`、主機清單、通行金鑰、重新驗證與驗證碼密鑰等設定。

規則未涵蓋的任何內容，寫入預設為關閉，讀取則可使用 `admin:read`。

### 需要您確認的動作 {#actions-that-need-your-confirmation}

這些動作只有在您核准預覽後才會成功（請參閱 [Two-step confirmation](#two-step-confirmation)）：

- 變更客戶餘額或經銷商錢包、撥款、帳務記錄、匯率。
- 變更價格（方案價格、批次方案建立、映像檔與儲存定價）以及建立折扣或金額代碼。
- 儲存金流閘道憑證或 CloudStack 連線。
- 刪除任何項目、封鎖或刪除客戶、變更客戶的限制、暫停或關閉經銷商。
- 對客戶伺服器執行動作，或為客戶建立付費伺服器。
- 透過一般設定變更全站開關、登入安全性設定或付款設定。

## 雙步驟確認 {#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 及以上），並將時間範圍限制在最近一小時、24 小時或 7 天。NexCMP 會保留最近 200,000 筆紀錄。透過金鑰所做的變更也會顯示在 Logs › Admin actions 中，並帶有 `ak:<admin>/<key name>` 名稱。

![Activity 標籤頁，列出包含狀態、客戶、工具與 IP 的呼叫](https://nexcmp.com/zh-tw/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/zh-tw/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/zh-tw/docs/configure-with-ai/oauth-connectors/)）中撤銷。




---

<!-- source: https://nexcmp.com/zh-tw/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/zh-tw/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/zh-tw/docs/configure-with-ai/admin-api-keys/) (`ak_...`)，**或**用於網路連線器的 OAuth 登入 ([OAuth connectors](https://nexcmp.com/zh-tw/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/zh-tw/docs/configure-with-ai/admin-api-keys/)。
2. 開啟 **Connect an AI** 分頁。當「金鑰已建立」對話方塊仍處於開啟狀態時，下方所有程式碼片段皆已包含您的真實金鑰。否則，它會顯示預留位置 `ak_YOUR_KEY`。
3. 複製適用於您客戶端的程式碼片段，並依照接下來的說明執行或貼上。

![Connect an AI 分頁，包含 MCP URL 以及每個客戶端一個帶有複製按鈕的卡片](https://nexcmp.com/zh-tw/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` 並詢問「列出 nexcmp 的工具」或「還有什麼需要設定？」。

於 2026/10/30 使用 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 (自訂連線器) {#claude-ai-custom-connector}

無需金鑰：它使用 OAuth 登入。在 claude.ai 中開啟連線器設定、新增自訂連線器、貼上 `https://cloud.example.com/mcp/admin`，然後使用您的 NexCMP 管理員帳戶登入並在同意畫面上選擇權限。詳細資訊：[OAuth connectors](https://nexcmp.com/zh-tw/docs/configure-with-ai/oauth-connectors/)。

### ChatGPT (開發者模式) {#chatgpt-developer-mode}

無需金鑰。在 ChatGPT 中開啟開發者模式、新增一個網址為 `https://cloud.example.com/mcp/admin` 的 MCP 連線器、選擇 OAuth 並使用您的 NexCMP 管理員帳戶登入。詳細資訊：[OAuth connectors](https://nexcmp.com/zh-tw/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的shell中匯出金鑰：

```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}"`。切勿將包含金鑰的檔案commit。
:::

### 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`會印出一行「MCP admin」，當端點回應時會顯示`ready`（沒有金鑰的HTTP 401是健康狀態）。

## 工具 {#tools}

伺服器提供58個工具。用戶端只能看到其金鑰範圍所允許的工具：讀取工具需要`admin:read`，寫入工具需要其自身的範圍。寫入工具也會取得選用的`confirm_token`引數（請參閱[Confirmation](#confirmation-confirm-token)）。引數會根據每個工具的Schema進行檢查：未知或拼寫錯誤的引數會被拒絕，並附帶指出它們的訊息。

價格以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` | 品牌名稱、顏色、顯示貨幣、賣家名稱、標誌與favicon網址。 | `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` | 設定條款與隱私權文字（簡易 markdown，不支援 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；bot token 絕不會回傳）。 | `admin:read` | 否 | 否 |
| `telegram_configure` | 新增或更新 Telegram 警報頻道（bot token 與聊天室 ID）並切換管理員警報開關。 | `settings:write`（token 另加 `secrets:write`） | 是 | 否 |
| `telegram_test` | 傳送測試訊息至 Telegram 頻道。 | `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 token（`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` | 客戶可以安裝的作業系統範本。 | `admin:read` | 否 | 否 |
| `templates_sync` | 從 CloudStack 匯入作業系統範本。 | `catalog:write` | 是 | 否 |
| `template_update` | 啟用或隱藏範本、重新命名、設定登入使用者或排序。 | `catalog:write` | 是 | 否 |
| `offerings_list` | 用於建立方案的 CloudStack 服務方案（CPU、記憶體、根磁碟）。 | `admin:read` | 否 | 否 |
| `plans_list` | 具有每小時與每月價格、大小、區域以及使用伺服器數量的方案。 | `admin:read` | 否 | 否 |
| `plan_create` | 建立方案。價格格式為 `hourly_usd`。CloudStack 方案需要 `cs_offering_id`；Proxmox 方案需要 `backend_id`。 | `catalog:write` | 是 | 否 |
| `plan_update` | 重新命名、顯示或隱藏、啟用或停用，或重新為方案定價。正在使用中的方案若要變更大小需要進行複製。 | `catalog:write` | 是 | 當價格變更時 |
| `plans_from_offerings` | 使用您的成本和利潤百分比，從產品（或 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`（以美分為單位的面額）或 `percent`（1 到 100，具有最高折扣）。 | `catalog:write` | 是 | 總是 |

### 客戶與經銷商 {#customers-and-resellers}

| 工具 | 功能 | Scope | 變更資料 | 詢問您 |
|---|---|---|---|---|
| `customers_search` | 透過電子郵件、姓名或IP尋找客戶。 | `admin:read` | 否 | 否 |
| `customer_get` | 單一客戶的帳戶、餘額、伺服器與近期帳單。 | `admin:read` | 否 | 否 |
| `customer_adjust_balance` | 以美元美分新增（正數）或扣除（負數）信用額度。必須填寫原因。 | `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 key、備用模型、推理強度、啟用狀態。 | `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/zh-tw/docs/configure-with-ai/config-as-code/)。

## 提示詞 {#prompts}

伺服器亦提供三個現成提示詞供客戶作為捷徑顯示：

| 提示詞 | 參數 | 要求 AI 執行的工作 |
|---|---|---|
| `initial-setup` | 無 | 呼叫 `setup_checklist`，以一句話解釋每個未完成的步驟，向您詢問所需的資訊，透過相容工具執行該步驟，預覽金錢或安全性變更，並以 `system_health` 結束。 |
| `add-proxmox` | `endpoint`（選填，`https://host:8006`） | 詢問 API token，接著執行 `proxmox_add`、`proxmox_test`、區域工具與 `proxmox_attach_zone`；隨後使用 `plans_from_offerings` 提出方案並等待您的核准。 |
| `launch-pricing` | `margin_pct`（選填，預設為 40） | 詢問您每個 vCPU、每 GB RAM 及每 GB 磁碟的每月成本，顯示包含成本、每月價格與每小時價格的預覽表格，並在您核准後建立方案。 |

## 確認（`confirm_token`） {#confirmation-confirm-token}

涉及資金轉移、資料刪除、變更付款憑證或登入安全性的動作皆為兩步驟：

1. 第一次呼叫不會變更任何內容。工具結果以「CONFIRMATION REQUIRED」開頭，並包含**預覽**（將呼叫的內容、為何具敏感性、新值與目前值）以及 `confirm_token`。
2. 客戶必須向您展示預覽。唯有在您核准後，它才會使用相同的引數加上 `confirm_token` 再次呼叫相同的工具。
3. 該 token 只能使用一次、僅限該特定請求，並會在 5 分鐘後過期。

伺服器指令會告訴 AI 將工具執行結果視為資料而非指令，並且絕不重複使用您未核准的 Token。您是最後防線：請閱讀預覽。

::: 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 金鑰代表該機密會經過該 AI。如果您介意，請保持 `secrets:write` 關閉並在管理後台自行輸入機密，或是使用 AI Chat **Secret** 欄位（管理後台中的 [AI Chat in the admin](https://nexcmp.com/zh-tw/docs/configure-with-ai/ai-chat-in-admin/#secrets)）或 `secret://` 參考（[Configuration as code](https://nexcmp.com/zh-tw/docs/configure-with-ai/config-as-code/#secrets)）。
- 客戶端不共用工作階段：每個連線皆以 `initialize` 開始。
- 在 **API & AI agents** 中撤銷金鑰即可立即切斷 AI 客戶端。

## 故障排除 {#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 unsupported `MCP-Protocol-Version` | 客戶端使用的版本伺服器無法識別 | 請更新客戶端；支援的版本：2025-11-25、2025-06-18、2025-03-26。 |
| 工具清單很短 | 金鑰範圍 | 請建立具有更多範圍的金鑰。 |
| 呼叫時發生 `insufficient_scope` | 工具需要第二個範圍，例如 `secrets:write` | 請將該範圍新增至新金鑰。 |
| 429 `rate_limited` | 每分鐘的呼叫次數超過金鑰允許的上限 | 請等待 `Retry-After` 或在新的金鑰上提高限制。 |
| claude.ai 或 ChatGPT 無法連線 | 無法從網際網路連線至該 URL，或是代理伺服器封鎖了 `/mcp/admin` 或 `/oauth-admin/` | 請檢查 DNS、TLS 與反向代理伺服器。 |

如需所有錯誤代碼，請參閱 [Admin API keys](https://nexcmp.com/zh-tw/docs/configure-with-ai/admin-api-keys/#errors)。




---

<!-- source: https://nexcmp.com/zh-tw/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 開發者模式連接器，以及任何支援具有動態用戶端註冊功能 OAuth 的其他 MCP 用戶端。命令列工具也可使用相同的流程，但對它們而言，使用 [admin API key](https://nexcmp.com/zh-tw/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** 想要管理此 NexCMP admin」（即提出要求的應用程式名稱），以及您將被導回的位址。
4. 勾選要授權的範圍。應用程式要求的項目會預先勾選；若未要求任何項目，則僅會勾選 `admin:read`。請參閱 [Scopes](https://nexcmp.com/zh-tw/docs/configure-with-ai/admin-api-keys/#scopes)。
5. 選擇連線持續的時間：**7**、**30** 或 **90** 天（預設為 30 天）。
6. 點擊 **Allow**。瀏覽器將返回應用程式，此時已完成連線。點擊 **Deny** 則可拒絕。

![要求授權 AI 應用程式的畫面，包含範圍核取方塊、時效選擇以及允許和拒絕按鈕](https://nexcmp.com/zh-tw/docs/images/configure-with-ai/oauth-connectors-01-consent.webp)

::: important 像管理金鑰一樣選擇範圍
授予剛好夠用的最小權限集。金錢、刪除和安全性操作仍會在預覽階段暫停並需要您的批准，但擁有 `settings:write` 的連線仍然可以變更您的品牌與電子郵件設定。
:::

## 管理與撤銷 {#manage-and-revoke}

開啟 **System › Settings › API & AI agents › Connected apps**。該表格會列出您連線過的所有應用程式：應用程式名稱、範圍、連線時間、到期時間以及最後使用時間。

若要中斷應用程式的連線，請點擊 **Revoke** 並確認。其憑證將立即失效；應用程式必須重新通過授權畫面才能再次連線。

![「Connected apps」分頁，列出一個 AI 應用程式及其範圍、到期時間與撤銷按鈕](https://nexcmp.com/zh-tw/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`（loopback）。 |
| 授權 | `GET /oauth-admin/authorize`，採用 PKCE 方法 `S256`。傳送 `resource` 參數時，必須為此面板的 `/mcp/admin` URL。此要求有效期限為 10 分鐘，且繫結至發起要求的瀏覽器。 |
| 授權 | 您選擇範圍與期限（如上）。授權碼有效時間為 60 秒且僅能使用一次。 |
| 權杖 | `POST /oauth-admin/token` 會傳回 **存取權杖**（一個 `ak_o...` 金鑰，有效時間 1 小時或直到連線結束，以較早者為準）與 **重新整理權杖**（`akr_...`）。每次重新整理都會傳回新的重新整理權杖；舊的將停止運作。連線將於您選擇的天數後結束。 |
| 撤銷 | 在「已連線應用程式」中點選 **Revoke**，或由應用程式呼叫 `POST /oauth-admin/revoke`（RFC 7009）。 |

存取權杖的行為如同具備您所授與範圍的管理員金鑰：遵循相同的範圍規則、確認、速率限制與活動記錄。其呼叫會顯示在 **Activity** 標籤頁中。

## 驗證 {#verify}

1. 在應用程式中詢問「run system_health」（或「what tools do you have?」）。應用程式會列出您的範圍所允許的工具（[the tool list](https://nexcmp.com/zh-tw/docs/configure-with-ai/mcp-admin/#tools)）。
2. 開啟 **Connected apps**：**Last used** 會更新。
3. 開啟 **Activity**：呼叫記錄會列出應用程式名稱與 `mcp`。

## 限制與注意事項 {#limits-notes}

- 若應用程式在一小時後再次要求登入，當客戶端未進行重新整理時這是正常現象；請重新連線。
- 若重新整理權杖被使用兩次將被視為遭竊：整個連線將被撤銷。請從應用程式重新連線。
- 使用兩次的授權碼將遭到拒絕（`invalid_grant`），且從該授權碼發出的權杖也將被撤銷。
- OAuth 存取權絕對不會超過範圍規則所允許的權限：[what a key can never do](https://nexcmp.com/zh-tw/docs/configure-with-ai/admin-api-keys/#what-a-key-can-never-do) 的限制同樣適用於已連線的應用程式。
- 供應商會變更其選單與支援的功能。若供應商的應用程式在您的方案中不提供自訂連接器，請改用 [admin API key](https://nexcmp.com/zh-tw/docs/configure-with-ai/admin-api-keys/) 搭配桌面或命令列客戶端。

## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| 同意畫面顯示「瀏覽器錯誤」 | 發起請求的瀏覽器與您目前登入的瀏覽器不同 | 請在同一個瀏覽器中從 AI 應用程式重新開始連線。 |
| 同意畫面顯示請求已過期或遺失 | 已超過 10 分鐘，或連結已被開啟兩次 | 請從 AI 應用程式重新開始連線。 |
| 出現「未知客戶端」或「重新導向地址不符」頁面 | 應用程式註冊已過期，或使用了未註冊的重新導向地址 | 請在應用程式中移除連接器並重新新增。 |
| `invalid_target` | 傳送的 `resource` 並非此面板的 `/mcp/admin` URL | 請使用 **Connect an AI** 標籤頁上顯示的正確 URL。 |
| `invalid_request` 關於 PKCE | 客戶端未傳送 `code_challenge_method=S256` | 請使用支援具備 PKCE 之 OAuth 2.1 的客戶端。 |
| 應用程式已連線但呼叫傳回 `insufficient_scope` | 您未勾選該範圍 | 請撤銷連線並重新連線且勾選該範圍。 |
| 應用程式無法連線至 URL | DNS、TLS 或反向代理伺服器封鎖了 `/mcp/admin`、`/oauth-admin/` 或 `/.well-known/` | 請檢查代理伺服器規則。 |




---

<!-- source: https://nexcmp.com/zh-tw/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}

您的面板設定（品牌、一般設定、電子郵件、Telegram 警報、模組、貨幣、付款閘道、限制、區域、方案、AI 提供者以及法律頁面）可以儲存為單一 YAML 檔案。您可以自行編輯檔案、請 AI 助理編輯、将其納入版本控制，或套用到相同或另一個面板。在任何變更生效前，您總是能看到差異清單。機密資訊絕不會寫入檔案中。

可用於將設定複製到第二個安裝環境、在正式上線前審查變更、在發生錯誤後還原設定，或是讓 AI 提出您可以作為單一文件閱讀的完整設定。

## 需求 {#requirements}

| 項目 | 需求 |
|---|---|
| NexCMP | 1.4.0 或更新版本。 |
| 命令列 | 您是 `root` 在面板伺服器上（請使用 `sudo`）。此指令會自行向面板要求臨時金鑰（15 分鐘，所有範圍）。若要改用較窄的金鑰，請將 `NEXCMP_KEY` 設定為 [admin API key](https://nexcmp.com/zh-tw/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/zh-tw/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/zh-tw/docs/administration/smtp-and-emails/)。變更主機、連接埠或安全性需要重新輸入密碼。 |
| `telegram` | 警報頻道開關、聊天 ID、機器人權杖。 | [Telegram notifications](https://nexcmp.com/zh-tw/docs/administration/telegram-notifications/)。 |
| `modules` | 選用模組開關 (`key: true/false`)。 | 只有面板允許切換的金鑰。參見 [Modules](https://nexcmp.com/zh-tw/docs/infrastructure/modules/)。 |
| `currency` | 顯示貨幣與手動 USD 對 VND 匯率 (`0` 自動，否則為 15000 至 50000)。 | 計費區段。參見 [Currency and exchange rates](https://nexcmp.com/zh-tw/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/zh-tw/docs/billing/payment-channels/)。 |
| `quotas` | `quota_*` 限制。 | 參見 [Quotas](https://nexcmp.com/zh-tw/docs/billing/quotas/)。 |
| `zones` | 依 `slug` 劃分的區域 (必填：`slug`、`name`、`country`；選填 `city`、`enabled`、`is_default`)。 | 建立新區域。檔案**不會變更**已存在的區域。參見 [Zones](https://nexcmp.com/zh-tw/docs/infrastructure/zones/)。 |
| `plans` | 依 `slug` 劃分的方案 (必填：`slug`、`name`、`cpu`、`ram_mb`、`disk_gb`、`hourly_usd`；選填 `cs_offering_id`、`backend_id`、`zone_id`、`enabled`、`visible`、`sort`、`description`)。 | 計費區段。建立新方案，現有方案則透過 slug 更新。價格以每小時 USD 計算。參見 [Plans](https://nexcmp.com/zh-tw/docs/catalog/plans/)。 |
| `ai_provider` | 客戶端 AI Chat 與 AI Agent 所使用的面板 AI 提供者。 | [AI provider](https://nexcmp.com/zh-tw/docs/ai/ai-providers/)。 |
| `legal` | 各語言的條款與隱私權文字 (`en`、`vi`)。 | [Legal pages](https://nexcmp.com/zh-tw/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 用戶端中的 `config_apply` 工具或 AI Chat) 套用相同的檔案時，此旗標將被忽略，金錢變更改為等待您的批准。

## 使用「匯入/匯出」頁面 {#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** 按鈕會開啟結構描述。

![帶有「匯出」卡片與包含已匯出 YAML 之「匯入」卡片的「匯入/匯出」頁面](https://nexcmp.com/zh-tw/docs/images/configure-with-ai/config-as-code-01-import-export.webp)

![依區段分組的變更預覽表格，包含計費標籤與一個Apply selected按鈕](https://nexcmp.com/zh-tw/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/zh-tw/docs/configure-with-ai/mcp-admin/#tools)）並輸出 JSON：

```bash
sudo nexcmp admin tools                       # name, scope and title of every tool
sudo nexcmp admin system_health
sudo nexcmp admin customers_search q=customer@example.com
sudo nexcmp admin settings_update --json '{"values":{"support_email":"support@example.com"}}'
```

引數可以是 `key=value` 對（值會在可解析時讀作 JSON，否則讀作文字）或一個 `--json '{...}'` 物件。如果動作需要確認，命令會印出預覽並以結束代碼 3 與「Nothing changed」停止。請讀取預覽，然後再次使用 `--yes` 執行相同的命令來套用它。以 root 身份執行時，命令會取得包含所有範圍的 15 分鐘金鑰，因此確認步驟是您的防護機制；若使用 `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/zh-tw/docs/configure-with-ai/ai-chat-in-admin/) 或管理頁面連線這些項目。
- 區域與方案透過 `slug` 進行對應。請勿在檔案中重新命名 slug：否則會被建立為新項目。
- 客戶已在使用的方案無法變更其大小；請改為建立新方案。
- 請妥善保管匯出的檔案，即使其中不包含機密：它們列出了您的價格、地址與帳戶名稱。

## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| `missing version: 1` | 檔案未以 `version: 1` 開頭 | 將其加入。 |
| `unsupported version 2` | 檔案具有不同的版本號碼 | 此面板僅讀取版本 1。 |
| `unknown section 'x' (known: ...)` | 拼寫錯誤或不支援的頂層金鑰 | 請使用上述區段。 |
| `YAML error: ...` | 無效的 YAML（縮排、字元對齊） | 修正訊息中指定的行。 |
| `config is larger than 1 MB` | 檔案太大 | 請分割檔案並使用 `--section`。 |
| `no API key: set NEXCMP_KEY=ak_... or run as root on the server` | 命令找不到金鑰 | 使用 `sudo` 執行，或匯出 `NEXCMP_KEY` 並透過 sudo 保留。 |
| `panel not reachable` | 面板服務未在預設連接埠上執行 | 檢查 `sudo nexcmp status`。 |
| `skipped` 下方的計費行 | 計費區段需要 `--confirm-billing` | 新增旗標並先檢閱 `$` 行。 |
| `pending` 下方的項目 | 變更需要確認 | 開啟 **API & AI agents** 或匯入／匯出結果，並在卡片上按下 **Confirm**。 |
| 有密鑰未更新 | 未設定 `NEXCMP_SECRET_<NAME>` 值，因此保留已儲存的密鑰 | 匯出變數並再次套用。 |
| `errors` 下方的項目包含 HTTP 403 `insufficient_scope` | 金鑰缺少該區段的範圍 | 使用具有該範圍的金鑰，或以 root 身份執行。 |
| `errors` 下方的項目包含 HTTP 403 `demo_read_only` | 展示面板 | 在真實安裝環境上套用。 |




---

<!-- source: https://nexcmp.com/zh-tw/docs/configure-with-ai/example-prompts/ -->

# 提示詞範例 {#example-prompts}

> **管理員位置：**任意管理員頁面上的 AI Chat (`/agent`) 或浮動的 **Ask AI** 按鈕。透過 [MCP](https://nexcmp.com/zh-tw/docs/configure-with-ai/mcp-admin/) 連線的任何 AI 客戶端也適用相同的提示詞。

## 功能 {#what-it-does}

這些提示詞展示瞭如何提問。每一個提示詞都列出了助理在幕後執行的動作、它需要的權限範圍（針對外部客戶端或金鑰），以及系統會要求您批准的位置。請將範例數值替換為您自己的數值。

::: tip 切勿在聊天文字中輸入任何機密資料
密碼、API 金鑰與權杖請使用 AI Chat 輸入框旁邊的 **Secret** 欄位（[details](https://nexcmp.com/zh-tw/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/zh-tw/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 token id (`user@realm!tokenid`) 及其密鑰。請將密鑰填入 **Secret** 欄位。請先建立一個權限受限的權杖：[Proxmox VE](https://nexcmp.com/zh-tw/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）。Scopes：`catalog:write`、`admin:read`。請參閱[Plans](https://nexcmp.com/zh-tw/docs/catalog/plans/)。

![AI Chat 回答，顯示包含成本、月費與時費的方案預覽表格](https://nexcmp.com/zh-tw/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/zh-tw/docs/administration/smtp-and-emails/)。

## 設定 Stripe {#set-up-stripe}

```text
Set up Stripe in test mode. My publishable key is pk_test_XXXX. Use the secret key and the
webhook secret from my Secret field (names stripe_secret_key and stripe_webhook_secret).
Then test the credentials and tell me which webhook URL I must add in Stripe.
```

`payment_configure` 始終是一個兩步驟動作：您會看到一個隱藏機密數值的預覽並予以批准。接著 `payment_test` 會向 Stripe 驗證憑證。範圍：`billing:write`、`secrets:write`。請僅在測試付款成功後再切換至正式環境。請參閱 [Stripe](https://nexcmp.com/zh-tw/docs/billing/stripe/)。

## 啟用 Telegram 警報 {#turn-on-telegram-alerts}

```text
Add my Telegram chat 123456789 for admin alerts. The bot token is in my Secret field as
telegram_bot_token. Send a test message.
```

助理會呼叫 `telegram_configure` 與 `telegram_test`。範圍：`settings:write`、`secrets:write`。請參閱 [Telegram notifications](https://nexcmp.com/zh-tw/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」，並呈現將記錄至稽核日誌的金額與原因。Scopes：`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/zh-tw/docs/configure-with-ai/config-as-code/)。範圍：`admin:read`。

## 撰寫良好的提示詞 {#write-good-prompts}

- 提供目標與事實：名稱、價格、電子郵件地址。請勿貼上機密。
- 對於任何涉及金錢花費或刪除資料的操作，請先要求預覽。
- 請要求助理「在變更之前讀取目前的值」。內建指示已經這麼說了。
- 如果答案看起來不對，請詢問「你呼叫了哪個工具、帶了什麼參數？」。AI Chat 中的工具卡片兩者都會顯示。

## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| 助理表示沒有對應功能的工具 | 該工具的範圍未授權，或者該動作對 AI 關閉 | 檢查 [Admin API keys](https://nexcmp.com/zh-tw/docs/configure-with-ai/admin-api-keys/#what-a-key-can-never-do)，或在管理員後台操作。 |
| 它要求您貼上密碼 | 模型忽略了指示 | 拒絕；請使用 Secret 欄位或在管理員後台輸入該值。 |
| 點擊「執行」後沒有任何變化 | 變更正在等待您的確認 | 捲動至確認卡片並按下 **Confirm**。 |
| 建立的方案價格不如預期 | 提示中的成本或利潤率錯誤 | 在方案頁面上編輯方案，或要求助理重新定價；變更價格需要確認。 |


---

<!-- source: https://nexcmp.com/zh-tw/docs/configure-with-ai/setup-checklist/ -->

# 安裝進度檢查清單 {#setup-progress-checklist}

> **後台位置：** Overview › Dashboard (`/`)，頂部的 **Setup progress** 卡片。Plans、Customers、Zones、Payments 和 Infrastructure 中的空白列表也會顯示相同的說明。

## 功能 {#what-it-does}

新安裝在第一位客戶訂購與付款之前需要完成十項工作。**Setup progress** 卡片會根據實際設定為您檢查這些項目、顯示已完成的數量、指出**下一步**並連結至對應的操作頁面。如果您連接了 AI 來源，**Do it for me** 會開啟包含該步驟現成問題的 [AI assistant](https://nexcmp.com/zh-tw/docs/configure-with-ai/ai-chat-in-admin/)。助理（以及透過 [MCP](https://nexcmp.com/zh-tw/docs/configure-with-ai/mcp-admin/) 的任何 AI 用戶端）可以使用 `setup_checklist` 工具讀取相同的清單。

## 十個步驟 {#the-ten-steps}

| # | 步驟 | 完成條件 | 操作位置 |
|---|---|---|---|
| 1 | 授權啟用 | 已為您的網域啟用授權 | System › Admin › License & updates (`/license`)。請參閱 [License and purchase](https://nexcmp.com/zh-tw/docs/getting-started/license-and-purchase/)。 |
| 2 | 連接基礎設施來源 | 已連接 CloudStack，或至少新增了一個 Proxmox VE 叢集 | Infrastructure › Cloud provider › Providers (`/infra/providers`)。請參閱 [CloudStack](https://nexcmp.com/zh-tw/docs/infrastructure/cloudstack/) 與 [Proxmox VE](https://nexcmp.com/zh-tw/docs/infrastructure/proxmox/)。 |
| 3 | 建立區域 | 至少存在一個區域 | Infrastructure › Datacenter › Zone (`/infra/zones`)。請參閱 [Zones](https://nexcmp.com/zh-tw/docs/infrastructure/zones/)。 |
| 4 | 作業系統範本 | 至少啟用一個範本 | Services › Virtual Machines › Plans & pricing 的 Templates 標籤頁 (`/vm/catalog?tab=templates`)。請參閱 [OS templates](https://nexcmp.com/zh-tw/docs/infrastructure/templates/)。 |
| 5 | 建立方案 | 至少啟用一個方案 | Services › Virtual Machines › Plans & pricing (`/vm/catalog`)。請參閱 [Plans and pricing](https://nexcmp.com/zh-tw/docs/catalog/plans/)。 |
| 6 | 設定付款 | 已設定 Stripe、PayPal、加密貨幣或銀行轉帳 | Finance › Payment channels (`/payments`)。請參閱[Payment channels](https://nexcmp.com/zh-tw/docs/billing/payment-channels/)。 |
| 7 | 電子郵件(SMTP) | 外發電子郵件已設定 | System › Settings › Email (`/settings/email`)。請參閱[SMTP與電子郵件範本](https://nexcmp.com/zh-tw/docs/administration/smtp-and-emails/)。 |
| 8 | 品牌設定 | 已上傳標誌，或品牌名稱已變更為非預設值 | System › Settings › Brand (`/settings/branding`)。請參閱[品牌形象](https://nexcmp.com/zh-tw/docs/customers/branding/)。 |
| 9 | 條款與隱私權 | 至少已填寫一份法律條款文字 | System › Settings › Legal (`/settings/legal`)。請參閱[法律頁面](https://nexcmp.com/zh-tw/docs/customers/legal/)。 |
| 10 | 建立測試訂單 | 至少存在一筆訂單 | 以客戶身分在客戶入口網站建立訂單，以檢查端對端運作是否正常；卡片會連結至Billing頁面 (`/billing`)。 |

卡片會顯示`done/total`（例如6/10）、進度列、附帶**Open**的下一個步驟，以及在連接AI來源時顯示的**Do it for me**。按一下步驟即可跳轉至其頁面。步驟旁的小連結可開啟對應的文件頁面；部分步驟還會顯示詳細資訊，例如「2 zone(s)」。

![Overview上的設定進度卡片，顯示十個步驟中已完成三個，以及Open和Do it for me按鈕](https://nexcmp.com/zh-tw/docs/images/configure-with-ai/setup-checklist-01-card.webp)

## 使用方式 {#use-it}

1. 開啟Overview。卡片位於頂端。使用箭頭可將其摺疊；控制台會在您的瀏覽器中記住此選擇。
2. 按一下**Open**前往下一個步驟的頁面，或按一下**Do it for me**。
3. 使用**Do it for me**時，助理會開啟並帶入請求，例如：「根據我的方案建議一份利潤率為40%的入門方案表，並在建立前先顯示預覽。」回答其提問，接著檢視並**Confirm**每張卡片。請參閱[管理控制台中的AI Chat](https://nexcmp.com/zh-tw/docs/configure-with-ai/ai-chat-in-admin/)。
4. 當十個步驟全部完成後，卡片便會消失。

### 空白清單 {#empty-lists}

當Plans、Customers、Zones、Payments或Infrastructure為空時，頁面會顯示**Next step**區塊，其中包含說明、操作按鈕、**Do it for me**以及文件連結，讓您永遠不會面對空白表格。

![顯示下一步說明與Do it for me按鈕的空白Plans頁面](https://nexcmp.com/zh-tw/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`，再加上您想要完成之步驟的權限範圍。請參閱[範例提示詞](https://nexcmp.com/zh-tw/docs/configure-with-ai/example-prompts/)。

## 驗證 {#verify}

1. 當您完成一個步驟後，下次載入Overview時卡片的計數便會增加。
2. 在助理中，`setup_checklist`會傳回相同的數字，並在已完成的步驟標上`done: true`。

## 限制與注意事項 {#limits-notes}

- 各項檢查僅確認是否已儲存，而非其是否能正常運作。已設定的閘道即使測試失敗亦視為完成。請使用各頁面上的**Test**按鈕，並在遇到問題時使用`system_health`工具。
- 此卡片僅供管理員使用。
- **Do it for me**需要先在System › Settings › AI accounts下連線AI來源；若未連線，則僅會顯示**Open**。
- 每次安裝的這十個步驟皆相同；即使是您不打算使用的步驟（例如私有雲上的付款功能），仍會計為未完成。

## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| 卡片未顯示 | 十個步驟已全部完成，或者無法載入卡片 | 重新載入Overview。在 AI Chat 中詢問 `setup_checklist` 以檢視狀態。 |
| 執行步驟後，該步驟仍然維持開啟狀態 | 儲存未完成，或條件尚未滿足（例如存在範本但已停用） | 開啟步驟頁面並檢查上方表格。 |
| 更改標誌後品牌設定保持開啟 | 當存在標誌或品牌名稱與預設「NexCMP」不同時，品牌設定即會計入 | 上傳標誌或設定您自己的名稱。 |
| **Do it for me** 沒有任何作用 | 未連線 AI 來源，或是處於展示面板 | 在 AI 帳戶中連線來源。 |


---

<!-- source: https://nexcmp.com/zh-tw/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 主機與連接埠（587 STARTTLS、465 TLS 或 25）的對外 TCP 連線 |
| 寄件者網域 | 您控制的網域，並已針對該提供者發布 **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` | |
| Password | （隱藏） | 僅寫入：頁面僅顯示是否已設定 |
| 寄件者信箱 | `no-reply@example.com` | 必須在提供者端取得授權 |
| 寄件者名稱 | `Example Cloud` | 預設為您的品牌名稱 |
| 回覆信箱（選填） | `support@example.com` | 客戶回覆的收件地址 |

![Settings 中 Email 的 SMTP 標籤頁，包含主機、連接埠、安全性、使用者名稱、寄件者欄位與 Send test 按鈕](https://nexcmp.com/zh-tw/docs/images/administration/smtp-and-emails-01-smtp.webp)

3. 點擊 **Save**，然後點擊 **Send test** 並輸入您自己的地址。

設定會儲存在具有存取限制的檔案中（`smtp.json`，權限 0600），且只有背景工作執行緒 `nexcmp-vmd` 會發送郵件；網頁服務僅負責將其加入佇列。

## 驗證 {#verify}

- 測試訊息已抵達收件匣（請一併檢查垃圾郵件）。在郵件原始碼中，確認 `dkim=pass` 與 `spf=pass`。
- 開啟 **Support › Sent emails**：每封訊息皆有狀態（queued、sent、failed）以及傳遞結果。失敗的訊息最多會重試 3 次。
- 在入口網站中註冊測試客戶，並確認驗證電子郵件已送達。

## 編輯電子郵件範本 {#edit-e-mail-templates}

**Email templates** 頁籤會依金鑰列出所有範本，以及其支援的語言（例如 `verify_email`、`reset_password`、`vm_ready`、`invoice_paid`、`low_balance`、`topup_received`、`ticket_reply`、`scale_up` …）。

1. 點擊範本並選擇語言。
2. 編輯主旨與內文。當訊息加入佇列時，系統會自動填入預留位置。
3. 儲存。變更會**立即**套用至之後加入佇列的訊息。

![Email templates 頁籤列出範本金鑰及其語言](https://nexcmp.com/zh-tw/docs/images/administration/smtp-and-emails-02-templates.webp)

## 限制與注意事項 {#limits-and-notes}

- 每個安裝實例僅支援一個 SMTP 帳號。經銷商的客戶會透過同一個帳號接收郵件，除非另有設定經銷商專屬帳號。
- 供應商的發送限制適用於此；NexCMP 除了重試之外不會進行額外限速。
- 若未設定 SMTP，面板仍可運作，但客戶將無法完成註冊驗證與密碼重設。

## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| 測試郵件從未送達 | 憑證錯誤、連接埠遭到封鎖、寄件者未獲授權 | 檢查 `journalctl -u nexcmp-vmd` 以查看 SMTP 錯誤；嘗試使用支援 STARTTLS 的 587 連接埠；向供應商驗證寄件者地址。 |
| 訊息被歸類為垃圾郵件 | SPF、DKIM 或 DMARC 遺失或設定不正確 | 發布供應商的記錄，並從該網域發送郵件。 |
| Sent emails 中顯示「failed」 | 供應商拒絕接收該訊息 | 展開該列以查看供應商的回應。 |
| 儲存後密碼欄位顯示空白 | 此為設計使然（僅能寫入） | 一旦儲存密碼，標籤就會顯示「current: set」。 |


---

<!-- source: https://nexcmp.com/zh-tw/docs/administration/telegram-notifications/ -->

# Telegram 與管理者警示 {#telegram-and-admin-alerts}

> **管理後台位置：** System › Settings › Admin alerts (`/settings/alerts`)。支援捷徑：Customers › Support › Tickets (`/support/tickets`)，**Settings** 頁籤。

## 功能 {#what-it-does}

當需要注意某些事項，以及當客戶註冊或存入款項時，NexCMP 會通知**您**（運營商）。警報會發送到一個或多個**管道**：Telegram、webhook 或電子郵件。

發送至管理者管道的事件包含：部署失敗、虛擬機器遺失、網路中斷、可用 IP 低於 30 個、即將到期的項目（1 小時警告）、Stripe 爭議、背景執行緒停止回應、叢集 RAM 超過閾值、新客戶註冊以及儲值入帳。客戶事件會持久化排入佇列，並以遞增延遲（30 秒至 1 小時）持續重試，直到 Telegram 接受為止。

## 需求 {#requirements}

| 項目 | 需求 |
|---|---|
| Telegram | 透過 **@BotFather** 建立的機器人（Token）以及應接收訊息的群組或使用者 **chat ID** |
| 網路 | 連線至 `api.telegram.org` 的對外 HTTPS |
| Webhook（替代方案） | 可接收警示負載的 HTTPS 端點 |

## 準備 Telegram {#prepare-telegram}

1. 在 Telegram 中開啟 **@BotFather**，發送 `/newbot`，選擇一個名稱；複製 **bot token** (`123456789:AA...`)。
2. 建立一個群組，將機器人加入其中，並發送任意訊息。
3. 尋找 **chat 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** 設為 chat ID，並將 **Secret (bot token)** 設為 token。點擊 **Add**。
3. 確保開關 **Send admin Telegram (VM module)** 為開啟狀態；*VM module status (read-only)* 欄位顯示「on」。

![顯示「Add channel」表單設為 Telegram 的 Admin alerts 頁面](https://nexcmp.com/zh-tw/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/zh-tw/docs/ai/ai-chat/)。

## 限制與注意事項 {#limits-and-notes}

- bot token 會隨頻道儲存，且不會再次顯示。
- Telegram 事件會使用第一個同時具有 destination 與 token 且已啟用的 Telegram 頻道。

## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| 沒有收到訊息 | chat ID 錯誤、機器人不在群組中，或者從未向機器人發送訊息 | 透過 `getUpdates` 重新檢查 ID；請先向機器人或群組發送訊息。 |
| 運作一段時間後停止 | Token 已在 BotFather 中被撤銷 | 建立新的 token 並更新頻道。 |
| 日誌中出現 `Telegram: no channel` | 沒有啟用的 Telegram 頻道 | 如上所述新增一個。 |




---

<!-- source: https://nexcmp.com/zh-tw/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}

| 標籤頁 | 內容 |
|---|---|
| **Activity** | 跨所有來源的統一時間軸：管理員操作、VM 事件、登入、推薦與系統錯誤 |
| **Admin actions** | 管理員變更的內容（例如 `customer.block`、`customer.delete`），包含管理員的 IP |
| **Console** | 管理控制台登入與系統請求（例如更新請求） |
| **Login** | 客戶登入與失敗記錄 |
| **VM events** | 每個虛擬機的部署步驟、建立、密碼、刪除與其他生命週期事件 |

## 讀取資料列 {#reading-a-row}

欄位：**Time**、**Source**、**Level**、**Actor**（誰）、**Target**、**Services**、**Action**（事件代碼，如 `customer.delete`）與 **Details**。點擊 **Open** 查看完整記錄。

![時間軸上方的來源、站台與服務篩選器活動頁面](https://nexcmp.com/zh-tw/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資料庫中，並包含在[backups](https://nexcmp.com/zh-tw/docs/getting-started/backup-and-restore/)中。保留期限視記錄而定：超過180天的客戶登入嘗試和超過60天的客戶API金鑰請求記錄會被清理。管理員API金鑰稽核最多保留約200,000筆近期記錄。這些限制並不代表統一活動時間軸也採用相同的保留期。

## 常見用途 {#common-uses}

| 問題 | 查看位置 |
|---|---|
| 誰停用了這位客戶？ | 管理員動作，搜尋 `customer.block` |
| 為什麼虛擬機器會消失？ | 虛擬機器事件，依虛擬機器 ID 篩選；亦可查看 Activity |
| 客戶是否收到電子郵件？ | Overview › Support › Sent emails |
| 何時請求上次更新？ | Console tab |




---

<!-- source: https://nexcmp.com/zh-tw/docs/administration/security/ -->

# 安全性 {#security}

> **後台位置：** System › Admin › Console security (`/account`)、Admin users (`/users`)；System › Settings › Customer logins (`/settings/login`)。

## 管理者控制台 {#admin-console}

### 雙因素驗證 (TOTP) {#two-factor-authentication-totp}

主控台可從網際網路存取，因此請啟用 TOTP。

1. 開啟 **System › Admin › Console security**。
2. 在 **Two-factor authentication (TOTP)** 下點擊 **Start setup**。
3. 使用 Google Authenticator、Authy、1Password 或 Bitwarden 掃描 QR 碼，然後輸入 6 位數代碼。

### 允許的主控台 IP 範圍 {#allowed-console-ip-ranges}

在 **Allowed console IP ranges** 下每行輸入一個 IP 或 CIDR（IPv4 或 IPv6）。**空白表示允許任何來源。** 若超出範圍，登入與管理 API 都將遭到封鎖。

::: warning 請勿將自己鎖在門外
頁面會顯示您目前的 IP，並要求新的清單必須包含它。請使用 **+ Add my IP**。若您仍遭到鎖定，請使用來自伺服器的 [emergency access](https://nexcmp.com/zh-tw/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/zh-tw/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碼或硬體金鑰登入；預設開啟。Passkeys會繫結至網域；每個經銷商網域皆獨立運作。品牌重塑後，請在*Legacy passkey Domain*中輸入舊網域，以便客戶獲得實用提示 |
| **新增登入方式時重新驗證** | 新增passkey或連結Google/GitHub之前再次要求輸入密碼（預設關閉） |
| **Captcha** | 註冊時使用Cloudflare Turnstile或Google reCAPTCHA：啟用、選擇提供商、輸入網站金鑰與密鑰 |
| **Block e-mail domains** | 每行一個網域（最多2000個）。註冊時若符合位址將遭到拒絕，並顯示`email_domain_blocked` |

![顯示Google登入及其callback URL的客戶登入頁面](https://nexcmp.com/zh-tw/docs/images/administration/security-01-customer-logins.webp)

### 內建原則 {#built-in-policies}

| 政策 | 值 |
|---|---|
| 客戶密碼 | 至少10個字元，包含字母與數字 |
| 客戶工作階段 | 30天；「以客戶身分登入」的工作階段持續1小時 |
| 電子郵件驗證 | 當銷售設定中開啟*require e-mail verified*時，於建立虛擬機器前必填 |
| 防盜刷 | 帳戶餘額低於最低加值金額時，僅能建立有限數量的虛擬機器 |

## 伺服器強化 {#server-hardening}

- 設定與TLS完成後，連接埠3000將會關閉；請參閱[Installation](https://nexcmp.com/zh-tw/docs/getting-started/installation/#the-panel-port-3000)。
- 服務以無特權的`nexcmp`使用者身分執行，並具備受限制的systemd沙箱。
- API金鑰、付款憑證與SMTP密碼皆以加密方式儲存；主金鑰位於`/var/lib/nexcmp/secrets`中 — 請保護好[backups](https://nexcmp.com/zh-tw/docs/getting-started/backup-and-restore/)。
- 安裝前會透過SHA-256與Ed25519簽章驗證版本。




---

<!-- source: https://nexcmp.com/zh-tw/docs/administration/general-settings/ -->

# 一般設定 {#general-settings}

> **Where in the admin:** System › Settings › General (`/settings`)。變更會立即生效（30秒快取）。

此頁面分為三個部分。

## 品牌與URL {#branding-urls}

| 欄位 | 用途 |
|---|---|
| 品牌名稱（電子郵件、發票） | 顯示於電子郵件與發票中。標誌與色彩位於[Branding](https://nexcmp.com/zh-tw/docs/customers/branding/) |
| 預設語言 | 新訪客的語言 |
| 客戶應用程式URL | 門戶的公開位址，例如`https://cloud.example.com` |
| 主控台URL | 虛擬機器主控台服務的位址 |
| 管理員URL | 當您「以...身分登入」經銷商客戶時所使用的連結 |
| 合作夥伴主控台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**。請在升級基礎架構時使用此功能。

![包含品牌名稱、預設語言與網址欄位的「一般設定」頁面](https://nexcmp.com/zh-tw/docs/images/administration/general-settings-01-general.webp)

## 其他設定頁面 {#other-settings-pages}

| 頁面 | 指南 |
|---|---|
| 品牌 | [Branding](https://nexcmp.com/zh-tw/docs/customers/branding/) |
| 法律 | [Legal](https://nexcmp.com/zh-tw/docs/customers/legal/) |
| 客戶登入 | [Security](https://nexcmp.com/zh-tw/docs/administration/security/) |
| 電子郵件 | [SMTP 與電子郵件範本](https://nexcmp.com/zh-tw/docs/administration/smtp-and-emails/) |
| 管理員警報 | [Telegram 與管理員警報](https://nexcmp.com/zh-tw/docs/administration/telegram-notifications/) |
| AI 提供者 | [AI providers](https://nexcmp.com/zh-tw/docs/ai/ai-providers/) |


---

<!-- source: https://nexcmp.com/zh-tw/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}

| 項目 | 必要條件 |
|---|---|
| Version | 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/zh-tw/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}

- 密碼、權杖、Cookie與API金鑰。在傳送任何內容之前，您的文字或錯誤訊息中任何看似此類資料的內容都會在伺服器端進行遮蔽（顯示為`***`或`[redacted]`）。
- 請求與回應的內容——失敗的請求僅會記錄方法、路徑與狀態。
- 您的客戶資料（姓名、電子郵件、訂單、發票）及其IP位址。
- 您的瀏覽器IP位址以及來自伺服器的任何檔案。與每次授權檢查相同，授權伺服器只會看到您伺服器連線時所使用的IP位址。

工單會透過伺服器已持有的授權權杖與您的安裝建立關聯，因此版本、網域及安裝均由伺服器設定，無法從瀏覽器變更。

## 限制 {#limits}

| 限制 | 值 |
|---|---|
| 主旨 | 150個字元 |
| 描述與步驟 | 合計8 KB |
| Reports | 整個安裝每小時5次且每天20次 |

重複傳送相同的回報（例如在發生網路錯誤後）不會建立第二張工單。

## 故障排除 {#troubleshooting}

| 訊息 | 原因 | 修正方式 |
|---|---|---|
| 請先啟用您的授權 | 該安裝尚未啟用授權 | 開啟**License & updates**並啟用，然後再次傳送 |
| 無法連線至授權伺服器 | 伺服器無法連線至`nexcmp.com` | 檢查伺服器的連外HTTPS與DNS，然後再次按下**Send report**——您輸入的文字將會保留 |
| 來自此安裝的錯誤回報過多 | 您已達到每小時5次或每天20次的上限 | 請稍候再試；或者將新發現補充至現有的未結工單中 |
| 此授權已遭停用 | 該授權已遭停用或退款 | 請參閱[授權與購買](https://nexcmp.com/zh-tw/docs/getting-started/license-and-purchase/) |
| 此安裝已遭撤銷 | 此安裝已在授權入口網站中遭撤銷 | 從**License & updates**重新啟用 |
| 無法重新整理授權權杖 | 伺服器無法更新其授權權杖 | 開啟**License & updates**，按下**Refresh**，然後再次傳送 |
| 沒有Report a bug按鈕 | 您是以員工、經銷商或客戶帳號登入，或是處於唯讀展示環境中 | 請以主要管理員身分登入 |

::: tip 關於AI助理與API金鑰
管理介面中的助理以及管理員API金鑰無法代表您傳送錯誤回報：該按鈕需要以主要管理員身分登入的人員操作。
:::


---

<!-- source: https://nexcmp.com/zh-tw/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/zh-tw/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、防火牆與proxy：`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/zh-tw/docs/troubleshooting/support/)。 |

## 下載與驗證 {#download-and-verification}

| 訊息 | 原因 | 修正方式 |
|---|---|---|
| `failed to download release X` | 下載期間發生網路問題 | 再次執行。 |
| `sha256 mismatch (… ≠ …)` | 檔案到達時受損或遭到竄改 | 再次執行；若重複發生，可能是proxy正在重寫下載內容——請嘗試從其他網路執行。 |
| `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/zh-tw/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/zh-tw/docs/getting-started/cli-reference/#emergency-access)。 |
| `ERR_TOO_MANY_REDIRECTS` | Cloudflare SSL模式為**Flexible** | 設定 **Full (strict)** — [details](https://nexcmp.com/zh-tw/docs/getting-started/dns-and-cloudflare/)。 |
| 精靈顯示「安裝代碼」錯誤 | 拼字錯誤或來自早期安裝的代碼 | 執行 `sudo nexcmp status` 並複製目前的代碼。 |
| 授權顯示 HTTP 421 | `/var/lib/nexcmp` 中的檔案擁有者為 root | `sudo nexcmp fix-owner`，然後 `sudo systemctl restart nexcmp`。 |


---

<!-- source: https://nexcmp.com/zh-tw/docs/troubleshooting/update-errors/ -->

# 更新錯誤 {#update-errors}

> **管理員位置：**System › Admin › License & updates（`/license`）

更新說明請參閱 [Updating NexCMP](https://nexcmp.com/zh-tw/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/zh-tw/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/zh-tw/docs/troubleshooting/faq/ -->

# 常見問題 {#faq}

## 授權 {#licensing}

**如果我的授權過期或伺服器失去網際網路連線會怎樣？** 權杖會維持 14 天有效並每日自動續約。在此之後，客戶無法建立**新的**服務；現正執行的服務、計費與登入功能將繼續運作。請參閱 [License and purchase](https://nexcmp.com/zh-tw/docs/getting-started/license-and-purchase/)。

**更新權限到期後，我還能獲得安全性修修正嗎？** 可以 — 安全性版本隨時提供；功能版本則需要有效的更新權限。

**我可以在第二台伺服器或網域上執行 NexCMP 嗎？** 請使用授權金鑰以及註冊於授權上的網域進行啟用 — 請參閱 [License and purchase](https://nexcmp.com/zh-tw/docs/getting-started/license-and-purchase/#moving-to-a-new-server-or-domain)。

## 安裝 {#installation}

**NexCMP 需要 Docker、PostgreSQL 或 Redis 嗎？** 不需要。它是一個包含 SQLite 資料庫的單一程式，由 systemd 以無特權使用者身分執行。請參閱 [Requirements](https://nexcmp.com/zh-tw/docs/getting-started/requirements/)。

**我可以在沒有公開網域的情況下安裝嗎？** 可以，請使用 `--no-nginx` 與 SSH 通道 — 請參閱 [Installation](https://nexcmp.com/zh-tw/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/zh-tw/docs/infrastructure/proxmox/) 與 [Zones](https://nexcmp.com/zh-tw/docs/infrastructure/zones/)。

**我需要 CloudStack 的 ROOT API 金鑰嗎？** 不需要，而且您不應該使用它。請建立一個專用帳戶 — [CloudStack](https://nexcmp.com/zh-tw/docs/infrastructure/cloudstack/)。

**為什麼虛擬機上有些頁籤或按鈕不會出現？** 頁面只會顯示虛擬機來源所支援的功能（例如 Proxmox VE 沒有連接埠轉發）。請參閱 [Proxmox VE](https://nexcmp.com/zh-tw/docs/infrastructure/proxmox/) 中的功能對照表。

## Operations {#operations}

**如何將 NexCMP 移動到另一台伺服器？** 備份、在新伺服器上安裝相同版本並使用相同授權、還原 — 請參閱 [Backup and restore](https://nexcmp.com/zh-tw/docs/getting-started/backup-and-restore/)。

**日誌在哪裡？**`journalctl -u nexcmp -u nexcmp-vmd`、`/var/log/nexcmp`，以及管理控制台中的 System › Logs. 請參閱[Audit log](https://nexcmp.com/zh-tw/docs/administration/audit-log/)。

**我可以在安裝前查看客戶入口網站嗎？**可以。[nexcmp.com](https://nexcmp.com/platform/)上的服務頁面以範例資料逐一呈現客戶入口網站的各個分頁；開啟*View demo*即可使用全螢幕檢視器。若想查看實際安裝環境，請來信業務團隊。


---

<!-- source: https://nexcmp.com/zh-tw/docs/troubleshooting/support/ -->

# 支援 {#support}

## Contact {#contact}

這裡沒有聯絡表單。請寄送電子郵件至 **sales@nexcmp.com** — 其涵蓋授權、續約、網域與技術問題。您位於 [nexcmp.com/licenses](https://nexcmp.com/licenses) 的授權頁面也連結至相同的信箱。

## Before you write {#before-you-write}

1. 搜尋這些文件（按 `/`）並檢查 [Installation errors](https://nexcmp.com/zh-tw/docs/troubleshooting/installation-errors/) 與 [Update errors](https://nexcmp.com/zh-tw/docs/troubleshooting/update-errors/)。
2. 收集以下事實 — 這能讓支援團隊在一次回覆中解決問題。

## What to include {#what-to-include}

| 項目 | How to get it |
|---|---|
| NexCMP version | `sudo nexcmp status` or System › Admin › License & updates |
| 主網域與授權金鑰的最後 4 個字元 | 授權與更新（絕不要傳送完整金鑰） |
| 您做了什麼以及您的預期結果 | Exact steps |
| 錯誤文字或螢幕截圖 | 傳送前請隱藏機敏資訊 |
| Service status | `sudo nexcmp status` |
| Recent log lines | `sudo journalctl -u nexcmp -u nexcmp-vmd -n 100 --no-pager` |
| 基礎架構 | CloudStack 或 Proxmox VE 版本、單一區域或多個區域 |

::: warning Never send secrets
請勿傳送授權金鑰、API 金鑰、密碼、安裝代碼、付款憑證或備份封存檔。請在記錄檔與螢幕截圖中遮蔽它們。
:::

## Security reports {#security-reports}

如果您認為發現了安全性漏洞，請將主旨包含「Security」的郵件寄至同一個信箱，並在修復前避免公開發布詳細資料。