ZH-CN
免费获取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.ps1Linux/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

API参考页面中包含适用于 macOS 和 Linux 的 cmp install 命令

登录 ​

bash
cmp login
  1. CLI 会打印一次性 code 和一个链接（https://cloud.example.com/link?code=WDJB-MJHT），打开浏览器并等待。
  2. 在浏览器中登录门户，检查客户端名称、设备、IP 和国家/地区，勾选权限（作用域）并选择密钥的有效期（默认 90 天）。涉及扣费或删除数据的权限默认不勾选。点击批准。
  3. CLI 接收其自己的密钥（独立于客户手动创建的密钥），并将其存储在 ~/.config/cmp/config.json 中（模式 0600；Windows 上为 %APPDATA%\cmp）。它会显示在 API keys › Connected apps & devices 下，并可在该处吊销。

该代码在 10 分钟后过期。批准需要一个经过身份验证的真实门户会话以及已验证的电子邮箱——不能是其他密钥，也不能是模拟会话。

实用的标志：--scopes vm:read,billing:read、--name "build server"、--no-browser、--profile、--api-url。

对于 CI 或无浏览器的服务器，请使用来自门户的密钥：

bash
printf %s "$KEY" | cmp login --with-token
export CMP_TOKEN=vk_XXXX      # nothing is written to disk
cmp whoami

使用命令 ​

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 显示配置文件和你的面板 URL。
  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 URL使用 https://，或者仅在实验室环境中红使用 CMP_ALLOW_HTTP=1。
浏览器打开了错误的网站未给分销商设置 --api-urlcmp login --api-url https://<reseller-domain>.