ZH-TW
免費取得NexCMP
適用於 NexCMP 1.6.1·已更新 ·以 Markdown 檢視

cmp 指令列工具 ​

**在入口網站中的位置：**安裝指令位於API參考文件（https://<your-domain>/apidoc，Command-line interface章節）。核准登入：https://<your-domain>/link。已連線裝置：API keys (/api-keys) › Connected apps & devices。

功能 ​

cmp 是一個供您的客戶（以及您自己）使用的輕量指令列程式，它能將所有 API 操作轉化為指令：cmp vm list、cmp vm start <id>、cmp billing invoice list。它是從您的安裝實例在發布時的 OpenAPI 文件所建置，因此指令會與您啟用的功能完全相符。它是一個適用於 Linux、macOS 與 Windows（amd64 和 arm64）的單一靜態二進位檔，無需安裝其他任何東西。

需求 ​

項目需求
伺服器無需額外安裝。發布套件已包含在 NexCMP 發布版本中，並由面板透過 https://<your-domain>/cli/ 提供。
客戶端機器Linux、macOS 或 Windows（PowerShell 5.1+）。僅需 ssh-keygen（OpenSSH 8.0+）即可驗證簽章。
憑證透過一次性代碼進行瀏覽器登入，或使用 API key。
網路連線至你的面板必須使用 HTTPS。CLI 拒絕透過明文 http:// 發送金鑰，除非是至 localhost。

準備基礎設施 ​

不需要任何操作。面板直接從 /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發行公開金鑰。

安裝（客戶） ​

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_SIGNATURE1 = 當無法驗證簽章時中止。
CMP_BASE_URL下載基礎網址（用於鏡像站）。

手動下載與驗證：

bash
curl -fsSLO https://cloud.example.com/cli/latest.json
sha256sum --check --ignore-missing SHA256SUMS

包含適用於 macOS 與 Linux 之 cmp 安裝指令的 API 參考章節

登入 ​

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

使用指令 ​

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，否則會拒絕執行。

結束代碼 ​

代碼含意
0成功
1其他錯誤（未列出的網路、HTTP 4xx/5xx）
2用法錯誤
3未授權 (401/403)
4找不到 (404)
5超出速率限制 (429)
6需要確認或已被拒絕
130已中斷

設定檔與環境 ​

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。

更新與解除安裝 ​

bash
cmp version
cmp update --check
cmp update

cmp update 會下載 latest.json、SHA256SUMS 與簽章，使用內建在執行中二進位檔的公鑰驗證簽章，驗證套件雜湊後才會自我替換。降版需要 --force。當你更新 NexCMP 時，面板會提供隨新版本發布的 CLI 版本。

若要解除安裝，請刪除 cmp 二進位檔與設定目錄（cmp config path 會顯示它）。如果機器遺失，請在 API keys 下撤銷金鑰。

驗證 ​

  1. cmp version 印出版本與 API 文件版本。
  2. cmp login，在瀏覽器中核准，然後 cmp whoami 會顯示設定檔與你的面板網址。
  3. cmp vm list 傳回你的虛擬機器；cmp vm list -o json | jq . 顯示原始 JSON。

限制與注意事項 ​

  • 指令清單取決於你的建置：這些套件是在發布建置時從你安裝的 OpenAPI 文件所產生，因此在你的版本中停用的產品將不會有對應指令。若遇到 CLI 不知的路徑，請使用 cmp api。
  • CLI 採用 MIT 授權條款。
  • 每個套件皆以 ed25519 金鑰簽署；簽章金鑰內嵌於安裝程式與二進位檔中，不會在更新時擷取。
  • 每個金鑰與每個帳戶皆設有金鑰數量限制（請參閱 REST API）。

故障排除 ​

症狀原因修正方式
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-urlcmp login --api-url https://<reseller-domain>.