火山 Flink Cli 工具--流式计算 Flink版-火山引擎

文档中心

流式计算 Flink版

AI 能力集成

火山 Flink Cli 工具

产品概述

volc-flink 是火山引擎流式计算 Flink 的官方命令行工具。您可以在终端环境中通过它完成项目与资源池查询、作业开发与发布、作业运维、文件资源管理、Catalog/Database/Table 元数据查询、Savepoint 管理以及 Session 集群管理等操作，将火山引擎流式计算 Flink 平台的核心能力无缝集成到本地开发调试和 Agent 编排等多种场景中。

核心能力

多 Profile 鉴权与上下文管理：支持火山引擎 AK/SK 凭证，通过 Profile 在不同账号、地域、项目之间切换，并提供 auth login 命令进行交互式快速配置。
作业全生命周期管理：覆盖从草稿（Draft）创建、内容更新、SQL 校验、依赖与动态参数管理、发布到资源池，到作业的启动、停止、重启、扩缩容、删除等完整链路。
Flink 作业运维：提供作业、实例、Pod、日志、指标和事件的统一查询能力，支持 --follow 流式查看日志，便于线上问题排查。
元数据与资源查询：支持查看项目、资源池、Catalog、Database、Table 等资源的元数据信息。
文件资源管理：支持本地文件上传、文件资源列表查询、生成预签名下载 URL，与 JAR / CDC 草稿无缝衔接。
Savepoint 与 Session 管理：支持手动触发 Savepoint、按 Savepoint 启动作业，以及 Session 集群的创建、启停与删除。
结构化输出与命令发现：支持 pretty、json、ndjson 三种输出格式；通过 command list 与 schema 命令暴露完整的命令元数据，便于脚本与 Agent 集成。
跨平台兼容：提供 npm、Linux/macOS 二进制脚本和 Windows PowerShell 脚本三种安装方式。

安装

环境要求

您已注册火山引擎账号并完成实名认证，具体步骤，请参见账号注册及实名认证。
开通流式计算 Flink 版产品，且拥有作业开发相应权限。
您已获取账号的 AccessKey、SecretKey，具体步骤，请参见获取AccessKey、SecretKey。
选择 npm 安装方案时，要求 Node.js 版本不低于 14.0.0。
支持 macOS、Linux、Windows 的 x64 / arm64 平台。

安装方式

您可以根据自己的操作系统和环境，选择以下任意一种方式进行安装。

方式一：通过 npm 安装（推荐）

如果您的环境中已安装 Node.js 和 npm，推荐使用此方式。npm 会在安装时从 CDN 下载与 npm 包版本匹配、适用于当前平台的二进制文件。

npm install -g @volcflink/volc-flink

方式二：通过二进制安装脚本（Linux / macOS）

适用于无 Node.js 环境的 Linux 和 macOS 系统。该脚本会自动检测您的操作系统与硬件架构，下载对应的二进制文件。

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

方式三：通过 PowerShell 安装脚本（Windows）

适用于 Windows x64 / arm64 系统，尤其是无 Node.js 环境的场景。

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

安装完成后，在终端中执行 volc-flink --version，如果成功输出版本号，则代表安装成功。

快速开始

1. 登录并创建 Profile

交互式登录会提示您输入 Access Key 和 Secret Key，并将凭证安全地保存到本机配置目录（默认 ~/.volc-flink）。第一次创建的 Profile 会自动成为当前激活的 Profile。

volc-flink auth login --profile default

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

volc-flink auth status

2. 查看项目

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

volc-flink project list

3. 查看资源池

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

资源池用量会按计费类型展示：POST 按量付费资源池输出 resource_usage、used_cu 和 capacity_cu；PRE 包年包月与 MIX 混合弹性资源池输出 CPU 与内存用量字段。

命令总览

下表总结了 volc-flink 的主要命令组：

命令组	子命令	说明
`auth`	`login`, `logout`, `status`	登录、登出与查看认证状态。
`profile`	`list`, `get`, `use`, `update`, `delete`	管理本地多账号、多地域、多项目的 Profile 上下文。
`project`	`list`, `get`, `current`	查询火山引擎项目，以及当前 Profile 绑定的项目。
`resource-pool`	`list`, `get`	查询 Flink 计算资源池及其用量。
`catalog`	`list`, `get`, `database (list/get)`, `table (list/get)`	查询元数据：Catalog、Database、Table。
`file`	`list`, `get`, `upload`, `url`, `dir (list/create)`	管理文件资源（JAR、CDC YAML、依赖等）与资源目录。
`draft`	`list`, `get`, `create`, `update`, `delete`, `validate`, `publish`, `directory`, `dependency`, `param`	作业草稿（SQL / JAR / CDC）开发、依赖与参数管理、发布到资源池。
`job`	`list`, `get`, `start`, `stop`, `restart`, `rescale`, `delete`, `events`, `instance (list/get/pods/metrics/logs)`	作业生命周期管理与作业实例运维。
`savepoint`	`list`, `create`	查询与触发 Savepoint。
`session`	`list`, `get`, `create`, `start`, `stop`, `delete`	Session 集群的创建、启停与删除。
`command`	`list`	列出所有公开的叶子命令及其能力元数据。
`schema`	`<command-path...>`	打印指定叶子命令的结构化 schema（参数、约束、错误等）。
`completion`	`bash`, `fish`, `powershell`, `zsh`	生成 shell 自动补全脚本。
`help`	`[command]`	显示指定命令的帮助信息。

全局参数

以下全局参数可用于所有子命令：

参数	类型	默认值	说明
`--output`	string	pretty	输出格式，可选 `pretty` / `json` / `ndjson`。
`--yes`	bool	false	自动确认高风险操作（删除、停止、启动、重启、扩缩容、发布、创建 savepoint 等）。

输出格式说明：

pretty：人工友好的表格输出，适合在终端阅读。
json：结构化的 JSON envelope，包含 ok、data、error、context、meta 等字段，适合脚本解析。
ndjson：换行分隔的 JSON，适合流式日志等持续输出场景。

鉴权管理

auth 命令组用于管理本地凭证存储与登录状态。

存储指定 Profile 的凭证（支持交互式或环境变量驱动）。第一次创建的 Profile 会自动成为 active Profile。

volc-flink auth login [options]

参数	类型	必填	说明
`--profile`	string	是	Profile 名称。
`--region`	string	否	地域，例如 `cn-beijing`。
`--project-name`	string	否	绑定到该 Profile 的项目名称。
`--account-id`	string	否	火山引擎账号 ID。指定后会跳过 IAM `GetUser` 自动检测。
`--description`	string	否	Profile 描述信息。

示例：

# 交互式登录
volc-flink auth login --profile default

auth logout

移除当前或指定 Profile 的本地登录状态。

volc-flink auth logout [--profile <name>]

auth status

显示当前 active Profile 与凭证完整性。常用于排查 not_logged_in 类错误。

volc-flink auth status

Profile 管理

profile 命令组用于管理本地多个 Profile（账号、地域、项目）上下文。

profile list

列出所有已配置的 Profile，并标识当前 active Profile。

volc-flink profile list

profile get

按名称查看 Profile 详情。

volc-flink profile get --name <name>

profile use

切换 active Profile。

volc-flink profile use --name <name>

profile update

更新 Profile 字段（地域、项目、描述）。

参数	类型	必填	说明
`--name`	string	是	要更新的 Profile 名称。
`--region`	string	否	新地域。修改地域时必须同时传 `--project-id` 或 `--project-name`。
`--project-id`	string	否	项目 ID。
`--project-name`	string	否	项目名称（控制台“项目名称”字段）。
`--description`	string	否	Profile 描述。

示例：

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

profile delete

删除 Profile 及其本地存储的凭证。高风险操作，需要 --yes 显式确认。

volc-flink profile delete --name <name> --yes

项目管理

project list

列出当前凭证可见的项目。--output json 时会在 meta.pagination 中返回 page_num、page_size、total 与 has_more。

参数	类型	必填	说明
`--search`	string	否	过滤 ID、项目名或显示名包含该字符串的项目。
`--page`	int	否	从 1 开始的页码，默认 1。
`--page-size`	int	否	每页大小，默认 200。

project get

按 ID 或名称查询单个项目，二者必须传且仅传其一。

volc-flink project get --id <project-id>
# 或
volc-flink project get --name <project-name>

project current

显示当前 Profile 绑定的项目。

volc-flink project current

资源池

resource-pool list

列出当前激活项目内的资源池，支持按名称模糊过滤与分页。

参数	类型	必填	说明
`--name-key`	string	否	按池名称做服务端模糊匹配。
`--page`	int	否	页码，默认 1。
`--page-size`	int	否	每页大小，默认 200。

resource-pool get

按 ID、全名或显示名查询单个资源池，三者必须传且仅传其一。

volc-flink resource-pool get --id <resource-pool-id>
volc-flink resource-pool get --full-name <full-name>
volc-flink resource-pool get --name <name>

Catalog / Database / Table

catalog 命令组用于查询元数据资源，所有命令都是只读的。

查询 Catalog

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

查询 Database

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

查询 Table

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>

--catalog-id 与 --catalog-name 互斥，二者选一。--database 在查询表时必填。catalog table get 会返回字段 schema、分区键和属性。

文件资源

file 命令组用于管理上传到平台的文件资源（JAR、CDC YAML、依赖等）。

列出文件资源

volc-flink file list [--name-key <keyword>] [--page-num 1] [--page-size 20]

查询单个文件资源

volc-flink file get --id <file-id>  
# 或  
volc-flink file get --name <file-name>

上传文件

将本地文件上传并注册为文件资源。

参数	类型	必填	说明
`--file`	string	是	本地文件路径。
`--dir-id`	string	是	目标资源目录 ID。
`--name`	string	否	资源名称，默认取 `--file` 的 basename。
`--permission`	string	否	资源权限类型，默认 `PRIVATE`。
`--description`	string	否	资源描述。

示例：

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

生成预签名下载 URL

volc-flink file url --id <file-id> [--expires 1h]

资源目录管理

volc-flink file dir list
volc-flink file dir create --name <dir-name>

草稿管理

draft 命令组覆盖了从草稿创建、内容更新、SQL 校验、依赖与参数管理到发布的全流程，支持 SQL、JAR、CDC 三种作业类型。

草稿目录

# 列出草稿目录
volc-flink draft directory list

# 创建草稿目录（中间路径自动创建，幂等）
volc-flink draft directory create --path /demo

# 删除草稿目录（需要 --yes，且目录必须为空）
volc-flink draft directory delete --path /demo --yes

列出与查看草稿

volc-flink draft list
volc-flink draft get --id <draft-id>
volc-flink draft get --path /demo/demo_sql

--id 和 --path 二者择一传入。--path 需要使用绝对路径（包含草稿名）。

创建草稿

draft create 支持创建 SQL、JAR、CDC 三种类型的草稿。

参数	类型	必填	说明
`--name`	string	是	草稿名称。
`--directory`	string	否	草稿目录绝对路径，例如 `/demo`。
`--directory-id`	string	否	草稿目录 ID，与 `--directory` 二选一。
`--job-type`	string	是	作业类型：`FLINK_STREAMING_SQL`、`FLINK_BATCH_SQL`、`FLINK_STREAMING_JAR`、`FLINK_BATCH_JAR`、`FLINK_CDC_JAR`。
`--engine-version`	string	否	引擎版本：`FLINK_VERSION_1_16`、`FLINK_VERSION_1_17`、`FLINK_VERSION_1_20`。
`--sql` / `--sql-file`	string	否	SQL 内联文本或本地 `.sql` 文件路径。
`--cdc` / `--cdc-file`	string	否	CDC 内联 YAML 或本地 `.yaml` / `.yml` 文件路径。
`--cdc-version`	string	否	CDC 版本，默认 `v3.4`。
`--jar`	string	否	主 JAR 的本地路径或 `tos://` URI（以 `.jar` 结尾）。本地路径会先上传并注册为文件资源。与 `--jar-file-id` 互斥。
`--jar-file-id`	string	否	已存在的文件资源 ID（写入平台 Jar 字段）。与 `--jar` 互斥。
`--resource-dir-id`	string	否	资源目录 ID，仅当 `--jar` 是本地文件时使用。
`--main-class`	string	否	主类，例如 `com.example.Main`。
`--args`	string	否	主参数。
`--main-arg`	string	否	追加主参数（可重复）。

SQL 草稿示例：

volc-flink draft create \
  --name demo_sql \
  --directory /demo \
  --job-type FLINK_STREAMING_SQL \
  --engine-version FLINK_VERSION_1_17 \
  --sql-file ./demo.sql

JAR 草稿示例：

# 先上传 JAR 文件
volc-flink file upload \
  --file ./app.jar \
  --dir-id <resource-dir-id> \
  --name app.jar

# 再创建 JAR 草稿（用文件资源 ID）
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

CDC 草稿示例：

volc-flink draft create \
  --name demo_cdc \
  --directory /demo \
  --job-type FLINK_CDC_JAR \
  --engine-version FLINK_VERSION_1_16 \
  --cdc-version v3.4 \
  --cdc-file ./demo.yaml

更新与校验草稿

volc-flink draft update --path /demo/demo_sql --sql-file ./demo.sql
volc-flink draft validate --path /demo/demo_sql

draft validate 仅校验 SQL 草稿的 SQL 文本，输出 valid、type、reason、solution 等字段。

草稿依赖管理

# 列出草稿依赖
volc-flink draft dependency list --path /demo/demo_jar

# 添加依赖（支持 tos:// URI、本地 .jar 或文件资源 ID）
volc-flink draft dependency add \
  --path /demo/demo_jar \
  --file-id <dependency-file-id>

# 移除依赖（高风险，需要 --yes）
volc-flink draft dependency remove \
  --path /demo/demo_jar \
  --file-id <dependency-file-id> \
  --yes

--jar 与 --file-id 均支持重复传入，一次性增删多个依赖。

草稿动态参数

# 列出动态参数
volc-flink draft param list --path /demo/demo_sql

# 设置或覆盖动态参数（KEY=VALUE，可重复）
volc-flink draft param set \
  --path /demo/demo_sql \
  --kv parallelism.default=4 \
  --kv state.backend=rocksdb

# 删除动态参数（高风险，需要 --yes）
volc-flink draft param unset \
  --path /demo/demo_sql \
  --key state.backend \
  --yes

发布草稿

发布会影响线上资源，因此需要 --yes 确认。--resource-pool-id 与 --resource-pool 二者必须传且仅传其一。

参数	类型	必填	说明
`--id` / `--path`	string	是	草稿 ID 或绝对路径，二者择一。
`--resource-pool-id`	string	否	资源池 ID。与 `--resource-pool` 互斥。
`--resource-pool`	string	否	资源池名称。与 `--resource-pool-id` 互斥。
`--priority`	string	否	调度优先级，可选 `1`-`5`。
`--schedule-policy`	string	否	调度策略，可选 `GANG` / `DRF`。
`--schedule-timeout`	int	否	调度超时时间。

示例：

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

删除草稿

volc-flink draft delete --path /demo/demo_sql --yes

作业运维

job 命令组用于管理已发布的 Flink 作业及其运行时实例。所有变更类操作（启动、停止、重启、扩缩容、删除）都属于高风险操作，必须显式传入 --yes 才能执行。

列出与查看作业

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

job events 支持 --since / --until（Unix 秒级时间戳或 RFC3339）与 --limit（默认 50）。

说明

控制台 URL、ApplicationId 或 JobEngineKey 中形如 s-2052938780895191042 的 ID 是运行时 application / instance key，不是作业级命令使用的稳定 job_id。拿到这类 ID 时，先通过 volc-flink job instance get --id <instance-id> 查询对应的 job_id，再执行作业级操作。

启动 / 停止 / 重启 / 扩缩容 / 删除作业

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 restart 总是使用最新已发布的草稿版本。--from 控制状态恢复来源：

new：全新状态启动。
latest：从最新 checkpoint 启动（job start 默认 new，job restart 默认 latest）。
savepoint：从指定 savepoint 启动，需要同时传 --savepoint-id。

job start 与 job rescale 支持以下资源调整参数（均可选）：

参数	类型	说明
`--parallelism`	int	映射到 `parallelism.default`。
`--tm-vcore`	int	TaskManager 核数，映射到 `kubernetes.taskmanager.cpu`。
`--tm-memory`	int	TaskManager 内存（MiB），映射到 `taskmanager.memory.process.size`。
`--slots-per-tm`	int	映射到 `taskmanager.numberOfTaskSlots`。
`--jm-vcore`	int	JobManager 核数，映射到 `kubernetes.jobmanager.cpu`。
`--jm-memory`	int	JobManager 内存（MiB），映射到 `jobmanager.memory.process.size`。

job rescale 至少需要传入一个资源参数，且只作用于运行中的作业（通过运行时参数重启，不会更新或发布草稿）。

说明

作业启动或重启是异步操作，通常需要 2-3 分钟进入 RUNNING 状态。中间态应继续通过 job get 或 job events 观察。

作业实例

# 列出实例 
volc-flink job instance list --job-id <job-id>

# 查询单个实例
volc-flink job instance get --id <instance-id>

# 查看实例运行的 Pod
volc-flink job instance pods --id <instance-id>

查看日志

volc-flink job instance logs \
  --id <instance-id> \
  --component jobmanager \
  --limit 200

job instance logs 主要参数：

参数	类型	说明
`--id`	string	必填，作业实例 ID。
`--since` / `--until`	string	时间范围，Unix 秒级时间戳或 RFC3339。`--since` 缺省时默认 15 分钟之前。
`--limit`	int	单次拉取条数上限，默认 500。
`--component`	string	组件名，默认 `jobmanager`。
`--level`	string	日志级别过滤。
`--pod-name`	string	Pod 名称过滤；当 TaskManager 只有一个 Pod 时自动选中。
`--sort`	string	排序方式，`ASC` / `DESC`，默认 `DESC`。
`--follow`	bool	持续轮询拉取新日志，需要配合 `--output ndjson`。按 `Ctrl+C` 停止。
`--cursor`	string	分页游标，配合 `next_cursor` 使用。

流式查看日志：

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

查看指标

# 使用 health 预设
volc-flink job instance metrics --id <instance-id> --preset health

# 列出所有可查询的指标名
volc-flink job instance metrics --list

# 自定义指标，逗号分隔
volc-flink job instance metrics \
  --id <instance-id> \
  --metric "<metric-name-1>,<metric-name-2>"

--preset 与 --metric 互斥；不传 --list 时 --id 必填。--start / --end 接受 Unix 秒级时间戳或 RFC3339，默认窗口为最近 15 分钟。--raw 会返回完整时间序列点而非压缩摘要。

Savepoint

# 查看作业的 Savepoint 列表
volc-flink savepoint list --job-id <job-id>

# 手动触发 Savepoint（高风险，需要 --yes）
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

Session 集群

session 命令组用于管理 Flink Session 集群。

查询 Session

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

创建 Session

session create 需要同时提供资源池 ID 和资源池名称，以及全部 TaskManager / JobManager 资源参数。

参数	类型	必填	说明
`--name`	string	是	Session 集群名称。
`--resource-pool-id`	string	是	资源池 ID。
`--resource-pool-name`	string	是	资源池名称（需与 ID 对应）。
`--engine-version`	string	是	引擎版本，例如 `FLINK_VERSION_1_17`。
`--tm-min-number`	int	是	TaskManager 最小数量。
`--tm-max-number`	int	是	TaskManager 最大数量（必须 ≥ min）。
`--tm-vcore`	int	是	每个 TaskManager 的 vCore 数。
`--tm-memory`	int	是	每个 TaskManager 内存（GiB）。
`--slots-per-tm`	int	是	每个 TaskManager 的 slot 数量。
`--jm-vcore`	int	是	JobManager 的 vCore 数。
`--jm-memory`	int	是	JobManager 内存（GiB）。
`--context`	string	否	集群 context，默认 `DEBUG`。
`--dynamic-properties`	string	否	动态参数，JSON 对象格式。
`--kv`	string	否	动态参数 KEY=VALUE 形式，可重复，与 `--dynamic-properties` 冲突时以 `--kv` 为准。

示例：

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 集群创建或启动是异步操作，通常需要 2-3 分钟进入 RUNNING 状态；中间态可通过 session get 继续观察。

启动 / 停止 / 删除 Session

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

配置与环境变量

配置目录

默认配置目录为：

~/.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_CONFIG_DIR`	配置目录，默认 `~/.volc-flink`。
`VOLC_FLINK_VERSION`	安装脚本指定的 CLI 版本（仅安装阶段生效）。

命令发现与 Schema

command list 与 schema 命令是 volc-flink 为脚本和 AI Agent 准备的命令元数据接口。

command list

列出所有公开的叶子命令及其能力元数据（是否只读、是否需要 --yes、是否支持交互式等）。

volc-flink command list
volc-flink command list --output json

schema

打印指定叶子命令的结构化 schema：参数类型、约束、风险等级、输出字段、可能错误等。

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

规划参数时可关注以下字段：

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

Shell 自动补全

completion 命令可以为常见 shell 生成补全脚本：

volc-flink completion bash
volc-flink completion zsh
volc-flink completion fish
volc-flink completion powershell

将输出内容写入对应 shell 的补全目录或在 shell 启动文件中加载即可。

Agent / 自动化使用指南

本节面向 AI Agent 调用方。交互式终端中可以依赖 pretty 输出；Agent 使用时应优先依赖结构化命令元数据和 JSON envelope。

命令发现与参数规划

# 列出所有叶子命令
volc-flink command list --output json

# 在执行具体命令前，获取该叶子命令的完整 schema
volc-flink schema job start --output json
volc-flink schema draft create --output json

输出解析契约

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

volc-flink --profile <profile> job list --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 输出；它只面向人类阅读。

错误与退出码

所有命令失败时都会返回结构化错误。使用 --output json 时，错误会出现在 error.type、error.message、error.hint 字段中。常见错误类型与建议处理方式：

error.type	含义与建议处理
`not_logged_in`	未登录或凭证缺失，运行 `volc-flink auth login --profile <name>`。
`invalid_credentials`	凭证无效，重新执行 `volc-flink auth login`。
`missing_context`	当前 Profile 未绑定项目或地域，运行 `volc-flink profile update --project-id ...`。
`permission_denied`	权限不足，检查凭证对项目或资源的访问权限。
`validation_error`	参数错误或互斥约束未满足，按 `hint` 调整参数。
`confirmation_required`	高风险操作未传 `--yes`，确认意图后重新执行并加上 `--yes`。
`not_found`	资源不存在，确认 ID / 路径 / 名称是否正确。
`ambiguous_reference`	名称匹配到多个资源，改用 `--id`。
`precondition_failed`	前置条件不满足，根据 `hint` 调整后再执行。
`platform_error`	平台返回错误，结合错误信息排查或联系平台支持。

退出码约定

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

FAQ

Q: 我在 Windows 上安装了，为什么执行 volc-flink 提示找不到命令？
A: 如果您通过 PowerShell 脚本安装，脚本会自动更新系统的 PATH 环境变量。但是，您需要重启您的终端（如 PowerShell、CMD 或 Windows Terminal）来让新的环境变量生效。
Q: 草稿发布失败提示 confirmation_required 怎么办？
A: 发布、删除、启停、扩缩容等高风险命令都需要显式 --yes 才能执行，确认目标无误后在原命令末尾追加 --yes 重新执行即可。
Q: 为什么 job instance logs --follow 没有输出？
A: --follow 会持续轮询日志服务，需要配合 --output ndjson 才能正确输出。完整命令示例：volc-flink job instance logs --id <instance-id> --follow --output ndjson，按 Ctrl+C 停止。

最近更新时间：2026.05.26 16:23:37

这个页面对您有帮助吗？

有用

无用

流式计算 Flink版

核心能力 #

环境要求 #

安装方式 #

方式一：通过 npm 安装（推荐） #

方式二：通过二进制安装脚本（Linux / macOS） #

方式三：通过 PowerShell 安装脚本（Windows） #

1. 登录并创建 Profile #

2. 查看项目 #

3. 查看资源池 #

auth login #

auth logout #

auth status #

profile list #

profile get #

profile use #

profile update #

profile delete #

project list #

project get #

project current #

resource-pool list #

resource-pool get #

查询 Catalog #

查询 Database #

查询 Table #

列出文件资源 #

查询单个文件资源 #

上传文件 #

生成预签名下载 URL #

资源目录管理 #

草稿目录 #

列出与查看草稿 #

创建草稿 #

更新与校验草稿 #

草稿依赖管理 #

草稿动态参数 #

发布草稿 #

删除草稿 #

列出与查看作业 #

启动 / 停止 / 重启 / 扩缩容 / 删除作业 #

作业实例 #

查看日志 #

查看指标 #

从 Savepoint 启动作业 #

查询 Session #

创建 Session #

启动 / 停止 / 删除 Session #

配置目录 #

环境变量 #

command list #

schema #

命令发现与参数规划 #

输出解析契约 #

退出码约定 #

核心能力

环境要求

安装方式

方式一：通过 npm 安装（推荐）

方式二：通过二进制安装脚本（Linux / macOS）

方式三：通过 PowerShell 安装脚本（Windows）

1. 登录并创建 Profile

2. 查看项目

3. 查看资源池

auth login

auth logout

auth status

profile list

profile get

profile use

profile update

profile delete

project list

project get

project current

resource-pool list

resource-pool get

查询 Catalog

查询 Database

查询 Table

列出文件资源

查询单个文件资源

上传文件

生成预签名下载 URL

资源目录管理

草稿目录

列出与查看草稿

创建草稿

更新与校验草稿

草稿依赖管理

草稿动态参数

发布草稿

删除草稿

列出与查看作业

启动 / 停止 / 重启 / 扩缩容 / 删除作业

作业实例

查看日志

查看指标

从 Savepoint 启动作业

查询 Session

创建 Session

启动 / 停止 / 删除 Session

配置目录

环境变量

command list

schema

命令发现与参数规划

输出解析契约

退出码约定