@volcflink/volc-flink

v0.1.6

Published

4 days ago

Volcengine Serverless Flink command line interface.

0High
0Medium
0Low

moseshe

volc-flink

volc-flink 是火山引擎流式计算 Flink 的命令行工具，用于在终端中管理项目、资源池、草稿、作业、文件资源、Catalog、Savepoint 和 Session 集群。

功能概览

多 Profile 管理：保存不同账号、地域、项目和凭证上下文。
项目和资源查询：查看项目、资源池、Catalog、Database、Table。
草稿管理：创建、更新、校验、发布 SQL / JAR / CDC 草稿。
作业运维：启动、停止、重启、删除作业，查看实例、事件、日志和指标。
文件资源管理：上传文件、查看资源、生成预签名下载 URL。
结构化输出：支持 pretty、json、ndjson，方便人工查看和脚本集成。

完整命令树

volc-flink
├─ auth           (login | logout | status)
├─ profile        (list | get | use | update | delete)
├─ project        (list | get | current)
├─ resource-pool  (list | get)
├─ catalog        (list | get)
│  ├─ database    (list | get)
│  └─ table       (list | get)
├─ file           (list | get | upload | url)
│  └─ dir         (list | create)
├─ draft          (list | get | create | update | delete | validate | publish)
│  ├─ directory   (list | create | delete)
│  ├─ dependency  (list | add | remove)
│  └─ param       (list | set | unset)
├─ job            (list | get | start | stop | restart | delete | events)
│  └─ instance    (list | get | pods | metrics | logs)
├─ savepoint      (list | create)
├─ session        (list | get | create | start | stop | delete)
├─ command        (list)
└─ schema         (<command-path...>)

安装

通过 npm 安装（推荐）

npm 会在安装时从 CDN 下载最新版本、当前平台的二进制文件。

npm install -g @volcflink/volc-flink
volc-flink --version

安装后可使用 volc-flink。

要求：

Node.js 14 或更高版本。
支持 macOS、Linux、Windows 的 x64 / arm64 平台。

通过安装脚本安装

不依赖 npm 的 macOS/Linux 安装方式：

curl -fsSL https://lf3-static.bytednsdoc.com/obj/eden-cn/rupsm-zzlsylcylz/ljhwZthlaukjlkulzlp/volc-flink/install-cli.sh | sh

Windows PowerShell：

iwr https://lf3-static.bytednsdoc.com/obj/eden-cn/rupsm-zzlsylcylz/ljhwZthlaukjlkulzlp/volc-flink/install-cli.ps1 -useb | iex

可通过 VOLC_FLINK_VERSION 指定版本。

安装 Agent Skills（可选）

如果你希望在支持 skills 的 Agent 环境中使用本项目提供的 Flink 操作知识，可以从当前仓库安装 skills：

npx skills add [email protected]:serverless-flink/volc-flink-go.git -g -y

这一步只安装 Agent 使用的技能说明，不替代 volc-flink CLI 本身。需要实际执行命令时，仍应先按上面的方式安装 volc-flink。

从源码构建

在本仓库根目录执行：

go build -o bin/volc-flink .
./bin/volc-flink --version

本项目按 go.mod 使用 Go 1.26.2。也可以使用发布构建脚本生成多平台产物：

bash scripts/build-binaries.sh

构建结果会输出到 dist/。

快速开始

1. 登录并创建 Profile

交互式登录会提示输入 Access Key 和 Secret Key，并把凭证保存到本机配置目录。第一次创建的 profile 会自动成为当前 profile。若 Access Key 无法调用 IAM GetUser 自动解析账号 ID，CLI 会提示手动输入账号 ID。

volc-flink auth login

非交互环境可以通过环境变量传入凭证：

export VOLCENGINE_ACCESS_KEY=<access-key>
export VOLCENGINE_SECRET_KEY=<secret-key>

volc-flink auth login \
  --profile default \
  --project-name <project-name> \
  --account-id <account-id> \
  --non-interactive

查看当前登录和上下文状态：

volc-flink auth status

2. 选择项目

列出当前凭证可见的项目：

volc-flink project list

project list --output json 会在 meta.pagination 返回当前 page_num、page_size、total 和 has_more；使用 --search 时， total 表示搜索过滤后的项目数量。

project list/get 中的 name 是控制台“项目名称”，display_name 才是控制台“显示名称”。

如果需要调整当前 profile 的地域或项目：

volc-flink profile update \
  --name default \
  --region cn-beijing \
  --project-id <project-id>

如果当前 profile 已经配置了项目，修改 --region 时必须同时传 --project-id 或 --project-name；--project-name 对应控制台“项目名称”。 CLI 会在新 region 下校验项目存在后再保存 profile。若同时传 --project-id 和 --project-name，二者必须指向同一个项目，否则会直接报错且不保存。

切换 active profile：

volc-flink profile use --name default

也可以在任意命令上临时指定 profile：

volc-flink --profile prod job list

3. 查看资源池

volc-flink resource-pool list
volc-flink resource-pool get --id <resource-pool-id>

常用命令

草稿

创建草稿目录：

volc-flink draft directory create --path /demo

创建 SQL 草稿：

volc-flink draft create \
  --name demo_sql \
  --directory /demo \
  --job-type FLINK_STREAMING_SQL \
  --engine-version FLINK_VERSION_1_17 \
  --sql-file <path-to-sql-file>

更新和校验草稿：

volc-flink draft update --path /demo/demo_sql --sql-file <path-to-sql-file>
volc-flink draft validate --path /demo/demo_sql

发布草稿到资源池。发布会影响线上资源，因此需要 --yes 确认：

volc-flink draft publish \
  --path /demo/demo_sql \
  --resource-pool-id <resource-pool-id> \
  --yes

JAR 与依赖

上传文件资源：

volc-flink file upload \
  --file <path-to-app.jar> \
  --dir-id <resource-dir-id> \
  --name app.jar

创建 JAR 草稿：

volc-flink draft create \
  --name demo_jar \
  --directory /demo \
  --job-type FLINK_STREAMING_JAR \
  --engine-version FLINK_VERSION_1_17 \
  --jar-file-id <file-resource-id> \
  --main-class com.example.Main \
  --main-arg env=prod

给草稿添加依赖：

volc-flink draft dependency add \
  --path /demo/demo_jar \
  --file-id <dependency-file-id>

作业

volc-flink job list
volc-flink job get --id <job-id>
volc-flink job events --id <job-id> --limit 50

启动、停止、重启、扩缩容、删除作业都需要显式确认：

volc-flink job start --id <job-id> --from new --yes
volc-flink job stop --id <job-id> --with-savepoint --yes
volc-flink job restart --id <job-id> --from latest --yes
volc-flink job rescale --id <job-id> --parallelism 10 --yes
volc-flink job delete --id <job-id> --yes

job start 和 job rescale 支持 --parallelism、--tm-vcore、 --tm-memory、--slots-per-tm、--jm-vcore、--jm-memory。job rescale 只作用于运行中的作业，通过运行时参数重启，不会更新或发布草稿。

查看实例、日志和指标：

volc-flink job instance list --job-id <job-id>
volc-flink job instance get --id <instance-id>
volc-flink job instance pods --id <instance-id>
volc-flink job instance logs --id <instance-id> --component jobmanager --limit 200
volc-flink job instance metrics --id <instance-id> --preset health

job instance logs --since/--until accepts Unix seconds (not milliseconds) or RFC3339 timestamps.

流式查看日志需要 ndjson 输出：

volc-flink job instance logs --id <instance-id> --follow --output ndjson

Savepoint

volc-flink savepoint list --job-id <job-id>
volc-flink savepoint create --job-id <job-id> --description before-upgrade --yes

从 savepoint 启动作业：

volc-flink job start \
  --id <job-id> \
  --from savepoint \
  --savepoint-id <savepoint-id> \
  --yes

Catalog / Database / Table

volc-flink catalog list
volc-flink catalog get --name <catalog-name>

volc-flink catalog database list --catalog-name <catalog-name>
volc-flink catalog database get --catalog-name <catalog-name> --name <database-name>

volc-flink catalog table list --catalog-name <catalog-name> --database <database-name>
volc-flink catalog table get --catalog-name <catalog-name> --database <database-name> --name <table-name>

Session 集群

volc-flink session list
volc-flink session get --id <session-id>

创建 Session 集群：

volc-flink session create \
  --name debug-session \
  --resource-pool-id <resource-pool-id> \
  --resource-pool-name <resource-pool-name> \
  --engine-version FLINK_VERSION_1_17 \
  --tm-min-number 1 \
  --tm-max-number 2 \
  --tm-vcore 1 \
  --tm-memory 4 \
  --slots-per-tm 1 \
  --jm-vcore 1 \
  --jm-memory 4

启停或删除 Session：

volc-flink session start --id <session-id>
volc-flink session stop --id <session-id> --yes
volc-flink session delete --id <session-id> --yes

全局参数

常用全局参数：

--profile <name>：本次命令使用指定 profile，覆盖 active profile。
--output pretty|json|ndjson：指定输出格式。
--non-interactive：关闭交互式输入，适合 CI 或脚本。
--yes：确认高风险操作，例如删除、停止、发布、创建 savepoint。

示例：

volc-flink --profile prod job list --output json

pretty 适合人工阅读；json 输出稳定 JSON envelope，适合脚本解析；ndjson 适合流式日志等持续输出场景。

配置和环境变量

默认配置目录是：

~/.volc-flink

可以用 VOLC_FLINK_CONFIG_DIR 指定独立配置目录，适合测试或 CI：

export VOLC_FLINK_CONFIG_DIR=/tmp/volc-flink-config

常用环境变量：

VOLCENGINE_ACCESS_KEY：Access Key。
VOLCENGINE_SECRET_KEY：Secret Key。

命令发现

查看所有公开命令及其能力标记：

volc-flink command list

查看某个叶子命令的结构化 schema：

volc-flink schema draft create --output json

查看帮助：

volc-flink --help
volc-flink draft create --help

Agent / 自动化使用指南

本节面向 AI Agent、CI 脚本和其他自动化调用方。交互式终端中可以依赖 pretty 输出；自动化流程应优先依赖结构化命令元数据和 JSON envelope。

命令发现和参数规划

Agent 不应硬编码完整命令表。先使用命令发现接口获取当前二进制支持的能力：

volc-flink command list --output json

在执行具体命令前，使用 schema 获取该叶子命令的参数、约束、风险等级、输出字段和可能错误：

volc-flink schema job start --output json
volc-flink schema draft create --output json

规划参数时遵循这些字段：

arguments：参数名、类型、是否必填、允许值和对应 CLI flag。
constraints：互斥、必选其一等跨参数约束。
requires_yes：为 true 时，执行命令必须显式传入 --yes。
read_only：为 false 时表示命令会修改远端或本地状态。
possible_errors：优先用其中的 type 和 hint 生成修复步骤。

输出解析契约

自动化调用应始终指定输出格式：

volc-flink --profile <profile> <command> --output json

一次性命令使用 json。流式日志使用 ndjson：

volc-flink job instance logs --id <instance-id> --follow --output ndjson

json 输出统一为 envelope：

ok：命令是否成功。
data：成功时的业务数据。
error.type：失败类型，脚本应优先分支判断该字段。
error.message：面向用户的错误说明。
error.hint：可执行的修复建议，存在时应展示给用户。
context：本次命令解析到的 profile、region、project。
meta.command：实际执行的命令 ID。
meta.pagination：分页信息，仅部分 list 命令返回。

不要解析 pretty 输出；它只面向人类阅读。

安全执行规则

Agent 执行修改类命令时应遵循以下规则：

对 requires_yes=true 的命令，只有在用户明确授权或流程已确认目标资源后才添加 --yes。
优先使用 --id、--resource-pool-id、--job-id 等稳定 ID；名称选择器可能触发 ambiguous_reference。
删除、停止、重启、发布、创建 savepoint 等命令执行前，应把目标 ID、profile 和 project 展示给用户或上游系统确认。
不要把 AK/SK、profile 文件、VOLC_FLINK_CONFIG_DIR 下的内容写入日志或提交到仓库。
测试和 CI 中使用独立 VOLC_FLINK_CONFIG_DIR，避免污染用户的 ~/.volc-flink。

错误和退出码

所有命令失败时都会返回结构化错误。使用 --output json 时，错误会出现在 error.type、error.message、error.hint 字段中。

退出码约定：

0：成功。
1：平台返回错误、资源不存在、引用不唯一或前置条件不满足。
2：参数错误、缺少确认、命令路径不是叶子命令。
3：未登录、权限不足、上下文缺失、凭证或 profile 问题。
4：网络或超时错误。
5：CLI 内部错误。

安全提示

不要把真实 AK/SK、profile 文件或 ~/.volc-flink 内容提交到代码仓库。
在脚本中优先使用环境变量或安全的密钥管理系统注入凭证。
对会修改或删除资源的命令保持显式 --yes，避免在自动化流程中误操作。