volcengine-cli

# 火山引擎 CLI (ve) 使用指南

## CLI 基本信息

- 二进制文件: `ve`
- 安装位置: `~/.local/bin/ve`
- 配置文件: `~/.volcengine/config.json`
- 命令格式: `ve [service] [action] [--参数名 值]`

## 配置管理

```bash
ve configure set --profile <名称> --region <区域> --access-key <AK> --secret-key <SK>
ve configure get [--profile <名称>]
ve configure list
ve configure profile --name <名称>   # 切换当前 profile
```

常用区域: `cn-beijing`, `cn-shanghai`, `cn-guangzhou`

使用非默认 profile 查询: `ve --profile <名称> <service> <action>`

## 核心使用模式

### 查询类操作

大多数 Describe/List 操作默认只返回 10 条结果。务必使用分页参数获取完整数据:

```bash
ve --profile <profile> <service> <Action> --MaxResults 100
```

如果返回的 `NextToken` 非空，需要继续翻页:
```bash
ve --profile <profile> <service> <Action> --MaxResults 100 --NextToken "<token>"
```

### 数组参数

数组参数使用 `.N` 后缀 (N 从 1 开始):
```bash
ve ecs DescribeInstances --InstanceIds.1 i-xxx --InstanceIds.2 i-yyy
```

### 全局参数

- `--profile <name>`: 指定 profile（覆盖默认）
- `--region <region>`: 注意此参数在某些版本中可能不生效，建议通过 profile 指定 region
- `--endpoint <url>`: 自定义 endpoint

## 常用服务速查

| 服务 | 命令前缀 | 说明 |
|------|----------|------|
| ECS | `ve ecs` | 云服务器 |
| VPC | `ve vpc` | 私有网络、EIP、安全组 |
| VKE | `ve vke` | 容器服务 Kubernetes |
| CLB/ALB | `ve clb` / `ve alb` | 负载均衡 |
| StorageEBS | `ve storageebs` | 云盘 |
| CDN | `ve cdn` | 内容分发 |
| DNS | `ve dns` | 域名解析 |
| IAM | `ve iam` | 身份与访问管理 |
| Redis | `ve redis` | 缓存数据库 |
| RDS MySQL | `ve rdsmysqlv2` | 云数据库 MySQL |
| MongoDB | `ve mongodb` | 云数据库 MongoDB |
| NAT | `ve natgateway` | NAT 网关 |
| CEN | `ve cen` | 云企业网 |
| ARK | `ve ark` | 方舟大模型平台 |
| Billing | `ve billing` | 计费 |
| AutoScaling | `ve autoscaling` | 弹性伸缩 |

## 查询 API 文档

ve CLI 的 `--help` 信息非常简略，只列出参数名不解释含义。当需要了解某个 API 的详细参数说明时，查询官方文档:

**API 文档 URL 模式:**
```
https://api.volcengine.com/api-docs/view?serviceCode=<service>&version=<version>&action=<Action>
```

**服务概览 URL 模式:**
```
https://api.volcengine.com/api-docs/view/overview?serviceCode=<service>&version=<version>
```

常用服务的 API 版本见 `references/api-versions.md`。

当遇到不确定的参数或需要了解 API 行为时，使用 WebFetch 工具查询对应的文档 URL。

## 常见操作示例

### ECS 实例

```bash
# 查询所有实例（注意 MaxResults）
ve --profile shanghai ecs DescribeInstances --MaxResults 100

# 按状态筛选
ve --profile shanghai ecs DescribeInstances --Status RUNNING --MaxResults 100

# 查询实例详情
ve ecs DescribeInstances --InstanceIds.1 i-xxxxx

# 启动/停止/重启实例
ve ecs StartInstance --InstanceId i-xxxxx
ve ecs StopInstance --InstanceId i-xxxxx
ve ecs RebootInstance --InstanceId i-xxxxx
```

### VPC 与网络

```bash
# 查询 VPC
ve vpc DescribeVpcs --MaxResults 100

# 查询安全组
ve vpc DescribeSecurityGroups --MaxResults 100

# 查询 EIP
ve vpc DescribeEipAddresses --MaxResults 100
```

### 云盘

```bash
# 查询云盘
ve storageebs DescribeVolumes --MaxResults 100
```

## 重要注意事项

1. **分页**: 默认只返回 10 条，始终加 `--MaxResults 100`
2. **Region**: `--region` 全局参数可能不生效，优先使用 `--profile` 切换区域
3. **输出格式**: 返回 JSON，用 python/jq 解析处理
4. **错误处理**: 如遇 `SignatureDoesNotMatch`，检查 AK/SK 配置是否正确
5. **代理**: 如需访问 GitHub 等被墙网站，使用 `--proxy http://proxy.bigquant.ai`