
# CLI工具使用手册

## 简介

### 介绍
本工具是一个用于管理日志服务的命令行工具，支持通过命令行参数或配置文件进行操作。适用于需要快速管理日志项目、日志库、日志检索、日志下载等场景。

### 主要功能
- 配置管理：支持配置Access Key、Secret Key、Endpoint、RegionId等信息,后期使用其他API 可以通过使用配置文件，减少参数输入。
- 日志项目管理：支持创建、删除、查询日志项目等功能。
- 日志单元管理：支持创建、删除、查询日志单元等功能。
- 日志检索：支持按条件检索日志。
- 日志下载：支持创建、删除、查询下载任务等功能。
- 服务开通：支持开通日志服务，查询日志服务状态。
- 机器组管理：支持管理日志采集的机器组。（暂不支持）
- 采集配置管理：支持配置日志采集规则。（暂不支持）
- 仪表盘管理：支持创建和管理日志仪表盘。（暂不支持）

---

## 安装

### 操作系统
- Windows
- macOS
- Linux

### 支持版本
- Go 1.18及以上版本

### 安装方式
1. 下载源码,解压源码包ctyun_lts_cli_sdk.zip：

2. 构建成可执行文件：（目录下已包含两个可执行文件ctlts）
  - windows 下构建：
    ```bash
    go build -o ctlts.exe main.go
    ```
  - linux/macOS 下构建：
    ```bash
    go build -o ctlts main.go
    ```

3. 运行可执行文件，更加提示使用对应功能：
  - Linux/macOS：
    ```bash
    ./ctlts
    ```
  - Windows：
    ```bash
    ctlts.exe
    ```
    如果需要自定义操作系统和架构：
    可使用命令：
```bash
SET GOOS=windows
SET GOARCH=amd64
go build -o ctlts.exe main.go
```
---

## 配置说明
  每次使用OpenApi 命令时，都需要配置accessKeyId、accessKeySecret、regionId、endpoint四个参数信息，可以通过设置配置文件，将参数信息保存到config.yaml 内,简化后续OpenApi命令使用。
### 配置文件路径
- 默认路径：`./`
- 配置文件名：`config.yaml`

### 配置文件格式
```yaml
config:
  huadong1:
    ak: 1820251a9c********************** 
    sk: 02749f3451********************** 
    endpoint: https://ctlts-global.ctapi.ctyun.cn
    region_id: bb9fdb42056f11eda1610242ac110002
  huabei2:
    ak: 1820251a9c**********************
    sk: 02749f3451**********************
    endpoint: https://ctlts-global.ctapi.ctyun.cn
    region_id: 200000001852
```

### 资源池-regionId 映射

| 资源池名称 | regionId                         |
| ---------- | -------------------------------- |
| 华东1      | bb9fdb42056f11eda1610242ac110002 |
| 华北2      | 200000001852                     |
| 西南1      | 200000002368                     |
| 华南2      | 200000002530                     |
| 长沙42     | 200000002401                     |
| 上海36     | 200000001790                     |
| 武汉41     | 200000001781                     |
| 呼和浩特3  | 200000003573                     |
| 南昌5      | 200000002527                     |
| 青岛20     | 200000001703                     |
| 庆阳2      | 200000003664                     |
| 沈阳8      | 200000003335                     |
| 太原4      | 200000002689                     |
| 乌鲁木齐7  | 200000004098                     |
| 西安7      | 200000001851                     |
| 贵州-西南2 | 200000002927                     |
| 郑州5      | 200000002586                     |
| 芜湖4      | 200000003327                     |
| 常州69     | 200000002526                     |
| 重庆52     | 200000002015                     |
| 杭州7      | 200000003329                     |


### 配置命令
```bash
./ctlts configure --ak=<string> --sk=<string> --endpoint=<string> --region_id=<string> --region_name=<string>

#cli 工具默认配置region_id为huadong1，如果在华东1地区，可简化为如下：
./ctlts configure --ak=<string> --sk=<string> 
```

使用完配置命令后，会在配置文件路径下，生成config.yaml 文件，里面包含配置信息。后续使用OpenApi命令时，只需要指定配置文件名即可，如：./ctlts project --config=huadong1    或者  ./ctlts project -c=huadong1 

## 输入输出

### 输入
- 命令行参数：通过`-`或`--`指定参数。
- 配置文件：通过`--config=huadong1` 或 `-c=huadong1` 指定配置文件中的配置信息。

### 输出
- 成功：返回操作结果。
- 失败：返回错误信息。

---

## CLI执行日志
在默认目录下,会自动生成request.log,里面包含openApi 的执行命令、OpenApi的url、返回结果，如下所示：
```
2025-02-18T16:27:27+08:00 - ctglts project listProject --config=huadong1 --project_name=lts

2025-02-18T16:27:27+08:00 - https://ctlts-global.ctapi.ctyun.cn/v1/project/list

2025-02-18T16:27:27+08:00 - {"statusCode":0,"error":null,"requestId":"69e47e41-16f8060a0","message":null,"returnObj":[***]}
```

request.log 会轮询文件，可以在utils.go 文件里面修改信息：
```
const (
	maxLogSize     = 10 * 1024 * 1024 // 10MB
	maxRotatedLogs = 2                // 最多保留 2 个轮转文件
	logFileName    = "request.log"    // 日志文件名
)
```

## 命令参考

### 命令规范
- 命令格式：`./ctlts <command> <subcommand> [options]`


执行： ./ctlts
 ```
Usage:
  ctlts [command]

Available Commands:
  configure    Configure Log credentials(ak,sk,endpoint,region_id) save to config.yaml
  dataDownload Ctyun Log Service Data Download openApi
  help         Help about any command
  instance     Ctyun Log Instance openApi
  log          Ctyun Log Service OpenApi
  logUnit      Ctyun Log LogUnit openApi
  project      Ctyun Log projects openApi
 ```

查看project 相关OpenApi列表: ./ctlts project
 ```
Usage:
  ctlts project [command]

Available Commands:
  checkProjectExist        check log project exist by project name and project code
  countProject             Count the number of log projects
  createProject            Create a new log project
  deleteProject            delete log project
  getCodeByName            get project code by project name
  getProject               Get log project details by project code
  getProjectByCode         Get log project information by project code
  getProjectDescription    Get a log project's description by project code
  listProject              list log project all or by project name
  pageProject              search log project by page
  queryProjectAliasName    Query project alias names by original project names
  queryProjectNameByCode   Query original project names by project codes
  renameProject            Rename a log project by project code
  updateProject            update log project description
  updateProjectDescription Update a log project's description by project code

Flags:
  -a, --ak string          access_id
  -c, --config string      use config.yaml ,such as: --config=huadong1
  -e, --endpoint string    endpoint
  -h, --help               help for project
  -i, --region_id string   region_id
  -s, --sk string          access_key
 ```

查看createProject OpenApi：./ctlts project createProject
```
Usage:
  ctlts project createProject [flags]

Examples:
ctlts log createProject --project_name=<string> [--description=<string>] [--ak=<string> --sk=<string> --endpoint=<string> --region_id=<string> or --config=<string>]

Flags:
  -d, --description string    log project description
  -h, --help                  help for createProject
  -n, --project_name string   Name of the project to create

Global Flags:
  -a, --ak string          access_id
  -c, --config string      use config.yaml ,such as: --config=huadong1
  -e, --endpoint string    endpoint
  -i, --region_id string   region_id
  -s, --sk string          access_key
```

执行createProject OpenApi：
```
  ./ctlts project createProject --project_name="test" -c=huadong1

  或者

  ./ctlts project createProject -n="test" -c=huadong1
```


### 全局选项
所有OpenApi 都需要的选项：
```
  -a, --ak string          access_id
  -s, --sk string          access_key
  -e, --endpoint string    endpoint
  -i, --region_id string   region_id
  -c, --config string      use config.yaml ,such as: --config=huadong1
```

### 命令类别

可参考天翼云OpenApi 门户的文档，查看日志项目相关的接口的参数：
https://eop.ctyun.cn/ebp/ctapiDocument/search?sid=169

#### 日志项目
```
 ./ctlts project
 支持的OpenApi：
 Available Commands:
  checkProjectExist        check log project exist by project name and project code
  countProject             Count the number of log projects
  createProject            Create a new log project
  deleteProject            delete log project
  getCodeByName            get project code by project name
  getProject               Get log project details by project code
  getProjectByCode         Get log project information by project code
  getProjectDescription    Get a log project's description by project code
  listProject              list log project all or by project name
  pageProject              search log project by page
  queryProjectAliasName    Query project alias names by original project names
  queryProjectNameByCode   Query original project names by project codes
  renameProject            Rename a log project by project code
  updateProject            update log project description
  updateProjectDescription Update a log project's description by project code
```
#### 日志单元
```
 ./ctlts logUnit
支持的OpenApi：
Available Commands:
  checkLogUnitExist       Check if a specified log unit exists
  countUnit               Get the count of log units
  createIndex             Create index information for a specified log unit
  createLogUnit           Create a new log unit
  deleteIndex             Delete index for a specified log unit
  deleteLogUnit           delete a new log unit
  getIndex                Query index information for a specified log unit
  getIndexCount           Get index count for a specified log unit by unit code
  getLogUnitAliasName     Get the alias name of a specified log unit by unit code
  getLogUnitNote          Get the note (description) of a specified log unit by unit code
  getLogUnitOriginName    Get the original name of a specified log unit by unit code
  getLogUnitTags          Get tags for a specified log unit by unit code
  getLogUnitTtlDays       Get the TTL days of a specified log unit
  getUnitByCode           Get log unit information by unit code
  listLogUnit             list log unit all or by unitName
  pageLogUnit             search log unit by page
  queryLogUnitAliasNames  Query alias names of log units in a specified project
  queryLogUnitOriginNames Query origin names of log units in a specified project
  renameLogUnit           Rename the alias of a specified log unit
  updateIndex             Update index information for a specified log unit
  updateLogUnit           update a new log unit
  updateLogUnitNote       Update the description of a specified log unit
  updateTtl               Update TTL for a specified log unit
```
#### 检索分析
```
 ./ctlts log
 Available Commands:
  getLogs     get logs from log service
```
#### 日志下载
```
 ./ctlts dataDownload
Available Commands:
  create      Create download task
  delete      Delete download task
  getSignUrl  Get the download link for the specified download task
  list        List download task
  query       Get the download message for the specified download task.
```
#### 服务开通
```
 ./ctlts instance
 Available Commands:
  checkLicense      Check order instance status
  getInstanceInfo   Get instance information under tenant resource pool
  getInstanceStatus Get instance status
  orderLogInstance  Order cloud log service instance
```
#### 机器组
 暂不支持

#### 采集配置
 暂不支持

#### 仪表盘
 暂不支持

## 最佳实践
 **

## 错误诊断

### 常见错误
1. **参数缺失**：
   - 检查必填参数是否提供。
   - 使用`-h`查看帮助信息。

2. **API请求失败**：
   - 检查Access Key、Secret Key、Endpoint、RequestId是否正确。
   - 检查网络连接是否正常。

3. **可变参数，赋值为空字符串却被赋值为"="**：
   - ./ctlts log updateProject -p=1efd19f951e230 -c=huadong1 --d=""  赋值时 d 被赋值为"="
   - 可以使用完备的flag 参数，将-d="" 换成 --description=""
   - ./ctlts log updateProject -p=1efd19f951e230 -c=huadong1 --description=""
---

## 其他资源

- [OpenApi官方文档](https://eop.ctyun.cn/ebp/ctapiDocument/search?sid=169)