如何使用 Hyperlift CLI 连接到 Hyperlift

Hyperlift CLI 是一个命令行工具，用于通过终端管理 Spaceship 平台上的 Hyperlift 应用程序。 

该工具是开源的，见此处。它与 Spaceship External API通信，并使用 API 密钥和密钥机密进行身份验证。在它的帮助下，您可以执行以下操作：

• 查看和管理应用程序；

• 构建、启动、停止和重启应用程序；

• 查看运行时和构建日志；

• 查看应用程序指标；

• 管理环境变量；

• 使用 JSON 输出进行脚本编写和自动化；

• 请让 CLI 保持最新。

CLI 与 Spaceship External API 通信，并使用 Spaceship API 密钥和密钥机密进行身份验证。因此，内部和管理信息会被隐藏，因为 CLI 会直接访问内部服务。

本文将介绍：

1. 如何安装 Hyperlift CLI；

2. 如何创建 API 凭据；

3. 如何登录 CLI；

4. 如何通过 CLI 管理 Hyperlift 应用程序；

5. 如何查看日志和指标；

6. 如何管理环境变量；

7. 如何更新 CLI。

1. 安装 Hyperlift CLI

Hyperlift CLI 可安装在 macOS、Windows 和 Linux 上。根据您的操作系统，运行安装命令。该脚本会自动检测您的操作系统和架构，下载相应的发行版，验证它，并安装 hyperlift 命令。

macOS

如果您使用 Homebrew，请运行：

brew install nccloud/tap/hyperlift

Windows

如果您使用 Scoop，请运行：

scoop bucket add nccloud https://github.com/NCCloud/scoop-bucket

scoop install hyperlift

Linux 或 macOS

您也可以使用安装脚本：

curl -fsSL https://raw.githubusercontent.com/NCCloud/hyperlift-cli/main/scripts/install.sh | sh

手动安装

或者，从Hyperlift CLI Releases page下载适用于您操作系统的压缩包，解压后将 hyperlift可执行文件添加到系统的 PATH 中。

2. 创建 API 凭据

Hyperlift CLI 使用 Spaceship API 密钥和机密来验证您的请求。

要创建 API 凭据：

1. 登录您的 Spaceship 账户。

2. 打开 API Manager。

3. 点击 + New API key 按钮以创建新密钥：
   
   

   

   
   

4. 为密钥命名，并选择您要执行的操作所需的权限：
   
   

   

   
   

5. 如果您选择 Custom access 访问级别，Hyperlift 有三个访问选项：
   

   

如果您只需要查看应用程序、日志或指标，仅具有 Read 范围的密钥就已足够。应用程序管理和环境变量需要额外的范围。

6. 复制已创建的 API 密钥和机密，并保存这些详细信息。

重要提示： API 机密仅在您创建凭据时显示一次。请务必安全保存。

点击 Done：

7. 已创建的密钥将列在 API Manager 菜单下：

3. 登录 Hyperlift CLI

安装 CLI 并创建 API 凭据后，请运行：

hyperlift auth login

CLI 将提示您输入 API 密钥和机密。

成功验证后，API 密钥会存储在 Hyperlift 配置文件中，而 API 机密会在可用时安全地存储在您操作系统的钥匙串中。

要检查您的登录状态，请运行：

hyperlift auth whoami

要注销并删除已存储的凭据，请运行：

hyperlift auth logout

提示： 如果您收到“Not logged in”消息，请再次运行 hyperlift auth login。如果您收到 403 错误，则您的 API 密钥可能缺少所需的范围。 

非交互式身份验证

如果您需要从脚本进行身份验证，可以使用命令行选项提供凭据：

hyperlift auth login --key "$KEY" --secret "$SECRET"

但是，使用 --secret 会将机密暴露为命令行参数。为了获得更好的安全性，您可以通过标准输入传递机密：

printf '%s' "$SECRET" | hyperlift auth login --key "$KEY" --with-stdin

4. 管理 Hyperlift 应用程序的基本命令

使用 apps 命令查看和管理您的 Hyperlift 应用程序。

查看应用程序

使用 apps命令查看和管理您的 Hyperlift 应用程序。

构建应用程序

要开始构建应用程序，请运行：

hyperlift apps build <app-id>

默认情况下，该命令会在 API 接受构建请求后返回。

如果您希望 CLI 等待直到构建完成，请添加 --wait 选项：

hyperlift apps build <app-id> --wait

您还可以指定 CLI 应等待多长时间：

hyperlift apps build <app-id> --wait --timeout 15m

默认超时时间为 10 分钟。

启动、停止或重启应用程序

使用以下命令管理应用程序状态：

默认情况下，这些命令会在 API 接受请求后返回。如果您希望 CLI 等待直到操作完成，请添加 --wait。

例如：

hyperlift apps restart <app-id> --wait

查看应用程序日志

您可以使用 logs 命令查看运行时日志和构建日志。

注意：--follow 选项会定期检查新的日志条目。它不会建立实时流式连接。

查看应用程序指标

使用 metrics 命令监控应用程序的资源使用情况。可用指标包括：

• 内存使用情况；

• CPU 使用情况；

• 网络接收速率；

• 网络发送速率；

• 临时存储使用情况；

• 持久存储使用情况。

管理环境变量

您可以使用 env命令来查看、添加、更新和删除环境变量。

重要提示： 更新环境变量会重启应用程序。在再次更改环境变量之前，请等待应用程序重新运行。

Hyperlift 使用 APPLICATION_PORT 环境变量来确定应用程序可用的端口。其默认值为 8080。

自定义命令输出 

默认情况下，Hyperlift CLI 命令以人类可读的格式显示信息。

如果您需要在脚本或其他工具中使用输出，可以使用以下选项。

注意：--json 和 --quiet 选项不能同时使用。

更新 Hyperlift CLI

获取各命令的帮助

每个 Hyperlift CLI 命令都有其自己的帮助信息。

帮助输出包括所选命令的可用选项和参数。

有关最新命令列表和技术详细信息，请参阅Hyperlift CLI repository。