Metadata-Version: 2.4
Name: volc-flink-cli
Version: 1.0.2
Summary: Volcano Engine Flink Stream Computing Python Client CLI
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.0.0
Requires-Dist: volcengine-python-sdk>=5.0.0
Requires-Dist: tos>=2.9.0

# 火山引擎流式计算 Flink 版 CLI / Python SDK

面向火山引擎流式计算 Flink 版的命令行工具与 Python SDK（非官方），覆盖登录认证、项目/资源池、草稿（SQL/JAR）、任务运维、日志与事件、Catalog 元数据、Session 集群等常用能力。

## 目录

- [安装](#安装)
- [快速开始](#快速开始)
- [常用场景](#常用场景)
  - [草稿（Drafts）](#草稿drafts)
  - [任务（Jobs）](#任务jobs)
  - [监控（Monitor）](#监控monitor)
  - [Catalog（元数据）](#catalog元数据)
  - [Sessions（Session 集群）](#sessionssession-集群)
- [配置与安全](#配置与安全)
- [Python API](#python-api)
- [开发说明](#开发说明)
- [常见问题](#常见问题)

## 安装

### 环境要求

- Python 3.7+

### 安装方式

```bash
pip install .
```

开发模式（可编辑安装）：

```bash
pip install -e .
```

安装完成后获得命令：`volc_flink`。

## 快速开始

### 1）登录

```bash
volc_flink login --region cn-beijing
```

### 2）选定项目（推荐）

先列举项目：

```bash
volc_flink projects list
```

设置默认项目（之后大部分命令可省略 `-p/--project` 或 `--project-id`）：

```bash
volc_flink config set-default-project --project-id YOUR_PROJECT_ID
```

也可以按项目名设置：

```bash
volc_flink config set-default-project --name YOUR_PROJECT_NAME
```

### 3）查看帮助

```bash
volc_flink --help
volc_flink drafts --help
volc_flink jobs --help
```

## 常用场景

### 草稿（Drafts）

#### 1）列目录 / 列草稿

列草稿目录（用于创建草稿时选择目录）：

```bash
volc_flink drafts dirs
```

创建草稿目录：

```bash
volc_flink drafts mkdir --name "/a/b/c"
```

删除草稿目录：

```bash
volc_flink drafts rmr --name "/a/b/c"
volc_flink drafts rmr --id "2037507470509535234"
```

删除草稿：

```bash
volc_flink drafts rm --id "2037518350102020097"
volc_flink drafts rm --name "my_draft"
volc_flink drafts rm --name "/a/b/c/my_draft.sql"
```

列草稿（用于查询草稿 ID、类型、目录等）：

```bash
volc_flink drafts apps --directory "/a/b/c"
```

兼容命令（等价于 `drafts apps`）：

```bash
volc_flink drafts list --directory "/a/b/c"
```

#### 2）校验 SQL 草稿（Validate）

说明：Validate 不只做语法解析，也可能会触发 connector/catalog 的校验，因此失败不一定是 SQL 语法错误。

```bash
# 通过草稿 ID 校验
volc_flink drafts validate --draft-id YOUR_DRAFT_ID

# 通过草稿名称或路径校验（自动解析草稿ID）
volc_flink drafts validate --draft "my_draft"
volc_flink drafts validate --draft "/a/b/c/my_draft.sql"
```

#### 3）创建草稿（SQL）

```bash
volc_flink drafts create \
  --name "test-streaming-sql" \
  --directory "/a/b/c" \
  --job-type FLINK_STREAMING_SQL \
  --engine-version FLINK_VERSION_1_17 \
  --sql "SELECT 1;"
```

#### 4）创建草稿（JAR：本地上传到 TOS）

```bash
volc_flink drafts create \
  --name "test-batch-jar" \
  --directory "/a/b/c" \
  --job-type FLINK_BATCH_JAR \
  --engine-version FLINK_VERSION_1_20 \
  --jar-path ./examples/jar/WordCount-flink-1-20.jar \
  --main-class org.apache.flink.streaming.examples.wordcount.WordCount
```

#### 5）依赖与动态参数

Dependency 字段为 JSON 字符串，例如：

```json
{"jars":["tos://flink-cwz-paimon/flink-client/resrouce/jars/WordCount-flink-1-20.jar"]}
```

给草稿添加依赖（支持 tos 路径或本地路径，本地会自动上传并输出 `tos://...` 路径）：

```bash
volc_flink drafts dependency add \
  --draft "/a/b/c/jar_job" \
  --jar tos://YOUR_BUCKET/path/to/jars/dep1.jar \
  --jar ./path/to/dep2.jar
```

动态参数（DynamicOptions）为 String-String KV JSON，例如：

```json
{"parallelism.default":"4","taskmanager.numberOfTaskSlots":"4"}
```

设置/删除动态参数：

```bash
volc_flink drafts params show --draft "/a/b/c/jar_job"
volc_flink drafts params set --draft "/a/b/c/jar_job" --kv parallelism.default=4
volc_flink drafts params unset --draft "/a/b/c/jar_job" --key parallelism.default
```

#### 6）更新与发布

更新 SQL：

```bash
volc_flink drafts update --draft "/a/b/c/sql_job" --sql-file /path/to/job.sql
```

发布草稿：

```bash
volc_flink drafts publish --draft "/a/b/c/sql_job" --resource-pool YOUR_RESOURCE_POOL_NAME
```

### 任务（Jobs）

列举任务与详情：

```bash
volc_flink jobs list
volc_flink jobs detail --job-id YOUR_JOB_ID
```

查询任务运行记录/事件：

```bash
volc_flink jobs instances --job-id YOUR_JOB_ID --limit 20
volc_flink jobs events --job-id YOUR_JOB_ID --limit 50
```

启动/停止/重启（支持 `--inspect` 轮询状态）：

```bash
volc_flink jobs start --job-id YOUR_JOB_ID --inspect --timeout 300
volc_flink jobs stop --job-id YOUR_JOB_ID --inspect --timeout 300
volc_flink jobs restart --job-id YOUR_JOB_ID --inspect --timeout 300
```

Rescale（调整规格并自动发布重启）：

```bash
volc_flink jobs rescale --job-id YOUR_JOB_ID --parallelism 32 --tm-spec 4C16GB --tm-slots 4 --jm-spec 2C8GB --inspect --timeout 300
```

### 监控（Monitor）

查询事件：

```bash
volc_flink monitor events --job-id YOUR_JOB_ID --limit 50
```

查询日志（默认选择最新实例，支持时间范围、cursor、tail）：

```bash
volc_flink monitor logs --job-id YOUR_JOB_ID --level ERROR --since "2025-01-01 12:00:00" --until "2025-01-01 13:00:00"
volc_flink monitor logs --job-id YOUR_JOB_ID --follow --interval 2
volc_flink monitor logs --job-id YOUR_JOB_ID --cursor YOUR_CURSOR
```

查询 FlinkUI：

```bash
volc_flink monitor flinkui url --job-id YOUR_JOB_ID
volc_flink monitor flinkui overview --job-id YOUR_JOB_ID
volc_flink monitor flinkui exceptions --job-id YOUR_JOB_ID
```

### Catalog（元数据）

列出 Catalog 列表：

```bash
volc_flink catalog tree
```

展开某个 Catalog（以列表形式列出该 Catalog 下的 Database）：

```bash
volc_flink catalog tree --catalog-id 45
```

展开某个 Database（列出 Table）：

```bash
volc_flink catalog tree --catalog-id 45 --database test_db
```

查看详细信息：

```bash
volc_flink catalog catalogs list
volc_flink catalog catalogs show --catalog-id 45
volc_flink catalog databases show --catalog-id 45 --database test_db
volc_flink catalog tables show --catalog-id 45 --database test_db --table prds_pk1
```

### Sessions（Session 集群）

列举 Session 集群：

```bash
volc_flink sessions list
```

创建 Session 集群：

```bash
volc_flink sessions create \
  --name "abcdef" \
  --resource-pool "cwz-test" \
  --queue "o-00c004d6dape" \
  --engine-version "FLINK_VERSION_1_20" \
  --context "DEBUG" \
  --tm-min 1 --tm-max 10 \
  --tm-vcore 2 --tm-memory 8 \
  --slots-per-tm 2 \
  --jm-vcore 1 --jm-memory 4
```

启动/停止：

```bash
volc_flink sessions start --id YOUR_SESSION_ID
volc_flink sessions stop --id YOUR_SESSION_ID
```

获取 FlinkUI（工具会自动获取 token 并通过网关拼接 URL）：

```bash
volc_flink sessions ui --id YOUR_SESSION_ID
```

### Files（TOS 文件）

说明：Files 模块使用 `config set-tos-jar-prefix` 配置的 `tos://...` 目录作为根目录，对其下对象进行管理。

列出文件：

```bash
volc_flink files list
volc_flink files list --prefix "sub/dir" --limit 50
```

上传/更新：

```bash
volc_flink files upload --file ./a.jar
volc_flink files upload --file ./a.jar --name "custom/a.jar"
volc_flink files update --name "custom/a.jar" --file ./a.jar
```

查看详情与获取下载链接：

```bash
volc_flink files detail --name "custom/a.jar"
volc_flink files url --name "custom/a.jar" --expires 3600
```

## 配置与安全

### 配置文件位置

- Windows：`C:\Users\YourUsername\.volcano_flink\credentials.json`
- Linux/macOS：`~/.volcano_flink/credentials.json`

### 安全说明

- 密钥信息存储在用户本地目录，文件权限设置为仅当前用户可读写（0600）
- 建议定期更换访问密钥
- 生产环境建议使用更安全的密钥管理方案

## Python API

```python
from volcano_flink_client.auth.auth import AuthManager
from volcano_flink_client.api import ApiClient
from volcano_flink_client.projects.projects import ProjectManager

auth_manager = AuthManager()
credentials = auth_manager.login(access_key="YOUR_AK", secret_key="YOUR_SK", region="cn-beijing")
api_client = ApiClient(credentials)

project_manager = ProjectManager(api_client)
projects = project_manager.list_projects()
for p in projects:
    print(p.name, p.id)
```

## 开发说明

### 代码结构

```
volcano_flink_client/
├── api.py               # HTTP 请求与签名
├── auth/                # 认证管理
├── projects/            # 项目操作
├── resource_pools/      # 资源池操作
├── drafts/              # 草稿操作
├── jobs/                # 任务操作
├── catalogs/            # Catalog 元数据
└── sessions/            # Session 集群
```

### 本地验证

```bash
python integration_test.py
```

## 常见问题

### Q：如何获取 AK/SK？

进入火山引擎控制台的访问控制页面创建与管理访问密钥：<https://console.volcengine.com/iam/accesskey/>

### Q：命令忘了怎么用？

```bash
volc_flink --help
volc_flink <module> --help
volc_flink <module> <cmd> --help
```

### Q：登录失败怎么办？

- 确认 AK/SK 正确
- 确认网络可访问火山引擎 OpenAPI
- 确认账号具备对应权限
