# lnctl CLI 使用文档

# lnctl CLI 使用文档

本文档用于说明 `lnctl` 的常用命令、全局参数、认证方式、输出规则以及典型操作流程。

## 1. 快速开始

查看全局帮助：

```bash
lnctl --help
```

查看指定资源命令帮助：

```bash
lnctl vps --help
lnctl image list --help
lnctl api-key --help
```

查看版本信息：

```bash
lnctl --version
```

## 2. 全局参数

`lnctl` 支持以下全局参数，所有子命令均可使用。

| 参数 | 说明 |
|---|---|
| `--output` | 输出格式，支持 `json` / `yaml` / `table` |
| `--timeout` | 请求超时时间，单位秒，范围 `10-300`，默认值 `30` |
| `--version` | 输出版本信息 |

说明：

- 如果 `--output` 的值非法，CLI 会自动回退到默认 `json`。
- 如果当前命令不支持指定的输出格式，也会自动回退到默认 `json`。
- 如果 `--timeout` 的值非法或超出范围，CLI 会自动回退到默认 `30`。

示例：

```bash
lnctl image list --output json
lnctl vps show --ecs-resource-uuid <ecs-uuid> --output yaml
lnctl vps list --timeout 60
```

## 3. 命令总览

`lnctl` 当前支持以下一级资源命令：

| 命令 | 说明 |
|---|---|
| `vps` | VPS 实例管理 |
| `firewall` | 安全组查询 |
| `image` | 镜像查询 |
| `ssh-key` | SSH Key 查询 |
| `region` | 地域查询 |
| `package` | 套餐查询 |
| `task` | 异步任务查询 |
| `api-key` | 本地 API Key 管理 |
| `upgrade` | 升级 `lnctl` |

## 4. 认证说明

`lnctl` 默认使用本地保存的 API Key 进行认证。

默认文件路径：

```text
~/.lnctl/api-key.key
~/.lnctl/api-keys.enc
```

### 4.1 首次执行业务命令

如果首次执行需要认证的业务命令，例如：

```bash
lnctl image list
```

当本地没有默认 API Key 时，CLI 会自动进入交互配置流程：

```text
Enter local api-key name (local label only, not sent to server): dev
Enter api-key: ********
Saved api-key "dev" and set it as current.
```

保存成功后，当前命令会继续执行。

后续命令会自动读取当前默认 API Key。

### 4.2 local api-key name 是什么

`local api-key name` 是本地用于区分不同 API Key 的名称，不会发送到服务端。

常见命名示例：

```text
dev
test
prod
```

### 4.3 管理本地 API Key

查看 API Key 管理帮助：

```bash
lnctl api-key
```

添加 API Key：

```bash
lnctl api-key add
lnctl api-key add dev
```

查看本地已保存的 API Key：

```bash
lnctl api-key list
```

切换当前默认 API Key：

```bash
lnctl api-key switch
lnctl api-key switch prod
```

删除 API Key：

```bash
lnctl api-key delete
lnctl api-key delete prod
lnctl api-key delete prod --force
```

说明：

- `lnctl api-key add` 会交互输入 `local api-key name` 和 `api-key`。
- `lnctl api-key add <name>` 会使用指定名称，只交互输入 `api-key`。
- 如果名称已存在，更新前需要确认。
- 如果当前没有默认 API Key，新保存的 API Key 会自动成为默认值。
- 如果当前已经有默认 API Key，新保存的 API Key 只会保存，不会自动切换。
- `lnctl api-key delete <name> --force` 会跳过删除确认。
- `--force` 不支持 `-f` 简写。
- `--force` 只跳过确认，不会忽略 API Key 不存在的错误。

### 4.4 删除默认 API Key 后的处理规则

如果删除的是当前默认 API Key，CLI 会自动处理新的默认 API Key：

| 剩余 API Key 数量 | 处理方式 |
|---|---|
| 0 个 | 清空当前默认值 |
| 1 个 | 自动切换到剩余的 API Key |
| 多个 | 根据删除方式决定 |

当剩余多个 API Key 时：

- 交互删除或非 `--force` 删除时，会提示选择新的默认 API Key。
- 使用 `--force` 删除时，会自动选择稳定顺序中的第一个名称。

## 5. 参数值与特殊字符

如果参数值包含特殊字符，例如密码中包含逗号、空格或其他特殊符号，推荐使用以下写法：

```bash
--参数名='参数值'
```

建议：

- 使用 `=` 连接参数名和值。
- 使用单引号包围参数值。

示例：

```bash
lnctl vps create ... --password='a13579A,'
```

该规则同样适用于 `reset-password`、`reset-os` 等需要传入密码的命令。

## 6. VPS 管理

### 6.1 查询实例详情

```bash
lnctl vps show --ecs-resource-uuid <ecs-uuid>
```

### 6.2 查询实例列表

`vps list` 默认输出 `table`。

```bash
lnctl vps list --region-code <region> --zone-code <zone>
```

分页查询：

```bash
lnctl vps list \
  --region-code <region> \
  --zone-code <zone> \
  --page 1 \
  --page-size 10
```

### 6.3 创建实例

创建 VPS 时，`--password` 与 `--ssh-key-uuid` 二选一。

使用密码创建：

```bash
lnctl vps create \
  --package-code <package-code> \
  --region-code <region-code> \
  --zone-code <zone-code> \
  --image-resource-uuid <image-uuid> \
  --instance-name <instance-name> \
  --password <password>
```

使用 SSH Key 创建：

```bash
lnctl vps create \
  --package-code <package-code> \
  --region-code <region-code> \
  --zone-code <zone-code> \
  --image-resource-uuid <image-uuid> \
  --instance-name <instance-name> \
  --ssh-key-uuid <ssh-key-uuid>
```

### 6.4 密码规则

`create`、`reset-password`、`reset-os` 中使用 `--password` 时，密码需要符合以下规则：

- 长度为 `8-30` 位。
- 必须包含大写字母：`[A-Z]`。
- 必须包含小写字母：`[a-z]`。
- 必须包含数字：`[0-9]`。
- 必须包含以下特殊字符之一：

```text
()`~!@#$*-+={}[]:;,.?/
```

### 6.5 主机名称规则

实例名称需要符合以下规则：

- 最大长度 `64` 个字符。
- 只能包含：
  - 大写字母
  - 小写字母
  - 数字
  - 连字符 `-`

### 6.6 停止实例

```bash
lnctl vps stop --ecs-resource-uuid <ecs-uuid>
```

### 6.7 启动实例

```bash
lnctl vps start --ecs-resource-uuid <ecs-uuid>
```

### 6.8 重启实例

```bash
lnctl vps restart --ecs-resource-uuid <ecs-uuid>
```

### 6.9 重置密码

```bash
lnctl vps reset-password \
  --ecs-resource-uuid <ecs-uuid> \
  --password <new-password>
```

跳过确认：

```bash
lnctl vps reset-password \
  --ecs-resource-uuid <ecs-uuid> \
  --password <new-password> \
  --force
```

说明：

- 新密码需要符合上文的密码规则。
- 如果密码包含特殊字符，建议使用 `--password='<new-password>'`。

### 6.10 重装系统

重装系统时，`--password` 与 `--ssh-key-uuid` 二选一。

使用密码重装：

```bash
lnctl vps reset-os \
  --ecs-resource-uuid <ecs-uuid> \
  --image-resource-uuid <image-uuid> \
  --region-code <region-code> \
  --password <password>
```

使用 SSH Key 重装：

```bash
lnctl vps reset-os \
  --ecs-resource-uuid <ecs-uuid> \
  --image-resource-uuid <image-uuid> \
  --region-code <region-code> \
  --ssh-key-uuid <ssh-key-uuid>
```

跳过确认：

```bash
lnctl vps reset-os \
  --ecs-resource-uuid <ecs-uuid> \
  --image-resource-uuid <image-uuid> \
  --region-code <region-code> \
  --password <password> \
  --force
```

说明：

- 使用 `--password` 时，密码需要符合上文的密码规则。
- 如果密码包含特殊字符，建议使用 `--password='<password>'`。

### 6.11 删除实例

```bash
lnctl vps delete --ecs-resource-uuid <ecs-uuid>
```

跳过确认：

```bash
lnctl vps delete --ecs-resource-uuid <ecs-uuid> --force
```

## 7. 只读资源查询

### 7.1 查询安全组

```bash
lnctl firewall list \
  --page 1 \
  --page-size 10 \
  --region-code <region>
```

### 7.2 查询镜像

`image list` 默认输出 `table`，表格中包含 `REGION` 列。

```bash
lnctl image list \
  --page 1 \
  --page-size 10 \
  --region-code <region> \
  --image-type System
```

如需完整结构：

```bash
lnctl image list --region-code <region> --output json
```

### 7.3 查询 SSH Key

```bash
lnctl ssh-key list \
  --page 1 \
  --page-size 10
```

### 7.4 查询地域

```bash
lnctl region list
```

### 7.5 查询套餐

```bash
lnctl package list \
  --region-code <region> \
  --zone-code <zone>
```

## 8. 异步任务查询

创建、删除、开关机、重装系统等变更类命令，可能会返回异步任务。

可以通过以下命令查询任务状态：

```bash
lnctl task show --task-id <task-id>
```

也可以直接传入任务 ID：

```bash
lnctl task show <task-id>
```

## 9. 升级 lnctl

检查并升级到当前 release channel 的 latest 版本：

```bash
lnctl upgrade
```

跳过确认，适合脚本或自动化环境：

```bash
lnctl upgrade --yes
```

即使当前已经是 latest，也重新下载并安装：

```bash
lnctl upgrade --force --yes
```

说明：

- `lnctl upgrade` 不需要 LightNode API Key。
- Linux 和 macOS 会在同目录生成备份文件：`lnctl.bak`。
- Windows 会在当前终端启动 helper `cmd` 进程，继续完成延迟替换。
- Windows 备份文件为同目录：`lnctl.exe.bak`。
- Windows 升级的最终成功或失败结果会回到当前终端输出。

## 10. 输出规则

### 10.1 默认输出格式

| 命令类型 | 默认输出 |
|---|---|
| `list` 类命令 | `table` |
| 非 `list` 命令 | `json` |

说明：

- `list` 类命令如果没有显式传入 `--output`，默认输出 `table`。
- 非 `list` 命令默认输出 `json`。
- 需要完整结构时，建议显式使用 `json` 或 `yaml`。

示例：

```bash
lnctl image list --output json
lnctl vps show --ecs-resource-uuid <ecs-uuid> --output yaml
```

### 10.2 非法 output 处理

如果显式传入非法 `--output`，CLI 会提示：

```text
Invalid output value, reset to default: json
```

并自动回退到 `json`。

例如：

```bash
lnctl image list --output xml
```

### 10.3 不支持 table 的场景

如果当前命令不支持 `table`，但显式传入了 `--output table`，CLI 会提示：

```text
Invalid output value, reset to default: json
```

并自动回退到 `json`。

### 10.4 非法 timeout 处理

如果显式传入非法 `--timeout`，CLI 会提示：

```text
Invalid timeout value, reset to default: 30
```

并自动回退到 `30`。

## 11. 常见操作流程

### 11.1 首次使用

```bash
lnctl --version
lnctl image list
```

如果本地没有 API Key，会自动进入交互配置流程。

配置完成后，可以查看当前 API Key：

```bash
lnctl api-key list
```

### 11.2 创建一台 VPS

先查询地域、套餐和镜像：

```bash
lnctl region list
lnctl package list --region-code <region> --zone-code <zone>
lnctl image list --region-code <region> --image-type System
```

然后创建 VPS：

```bash
lnctl vps create \
  --package-code <package-code> \
  --region-code <region-code> \
  --zone-code <zone-code> \
  --image-resource-uuid <image-uuid> \
  --instance-name <instance-name> \
  --password '<password>'
```

如果命令返回异步任务，可以继续查询任务状态：

```bash
lnctl task show <task-id>
```

### 11.3 重装一台 VPS

```bash
lnctl vps reset-os \
  --ecs-resource-uuid <ecs-uuid> \
  --image-resource-uuid <image-uuid> \
  --region-code <region-code> \
  --password '<password>'
```

跳过确认：

```bash
lnctl vps reset-os \
  --ecs-resource-uuid <ecs-uuid> \
  --image-resource-uuid <image-uuid> \
  --region-code <region-code> \
  --password '<password>' \
  --force
```

### 11.4 删除一台 VPS

```bash
lnctl vps delete --ecs-resource-uuid <ecs-uuid>
```

跳过确认：

```bash
lnctl vps delete --ecs-resource-uuid <ecs-uuid> --force
```

## 12. 常见排查

### 12.1 提示 API Key 缺失

优先检查以下内容：

- 当前终端是否可交互。
- 是否已经执行过 `lnctl api-key add`。
- `~/.lnctl/api-key.key` 是否存在。
- `~/.lnctl/api-keys.enc` 是否存在。
- 本地是否已经设置当前默认 API Key。

可执行以下命令查看：

```bash
lnctl api-key list
```

### 12.2 变更命令返回异步任务

创建、删除、开关机、重装系统等命令可能先返回异步任务。

继续查询任务状态：

```bash
lnctl task show <task-id>
```

### 12.3 输出内容太长不易读

列表类命令优先使用默认 `table` 输出。

如果需要查看完整字段，再切换为：

```bash
--output json
```

或：

```bash
--output yaml
```

示例：

```bash
lnctl image list --output json
lnctl vps show --ecs-resource-uuid <ecs-uuid> --output yaml
```

### 12.4 `lnctl upgrade` 偶发网络失败

如果看到以下类型的下载错误：

```text
EOF
connection reset
timeout
```

可以按以下顺序处理：

1. 直接重试一次：

```bash
lnctl upgrade --yes
```

2. 如果本机配置了代理，优先确认代理是否可用。
3. 重点关注错误输出中的 `URL` 和 `Network error` 字段。

CLI 当前会先做短重试，再输出收敛后的网络错误提示。

### 12.5 Windows 升级会继续占用当前终端

这是预期行为。

原因：

- Windows 不能在运行中的 `lnctl.exe` 进程内直接覆盖自己。
- `lnctl upgrade` 会启动 helper `cmd` 进程，在当前终端继续完成最终替换。

处理方式：

- 请保持当前终端打开。
- 等待最终输出：

```text
Upgrade completed.
```

或：

```text
Upgrade failed: ...
```

升级完成后，可以再次确认版本：

```bash
lnctl --version
```
