Vector 命令行接口（CLI）完全指南：子命令、参数与环境变量详解-酒店常州论坛

Vector 命令行接口（CLI）完全指南：子命令、参数与环境变量详解

【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector

导读

Vector 将整个可观测性数据管道（采集、转换、聚合、输出）封装在单个二进制文件中，并通过一套统一的命令行接口对外暴露全部管理能力。本文基于官方文档 website/content/en/docs/reference/cli.md 展开，系统梳理vector根命令的全部 flags、options、子命令以及环境变量，并结合 website/cue/reference/cli.cue（文档数据源）与 src/cli.rs（clap 实际定义）逐项给出默认值、取值枚举与底层实现细节。读完本文，你将能够熟练使用vector完成配置校验、单元测试、拓扑可视化、事件采样（tap）、指标观测（top）与 VRL 调试等日常运维操作。

总览：单二进制 + 统一入口

Vector 本身就是一个可执行文件，所有功能都挂在同一个入口上，其通用语法为：

vector [FLAGS] [OPTIONS] [SUBCOMMAND] [ARGS]

不带任何子命令直接执行vector，即启动 Vector 数据管道（前台运行，直至收到信号退出）；
携带子命令（如validate、graph、tap）时，Vector 执行一次性管理操作后退出。

命令行结构由 src/cli.rs 中的Opts结构定义：根参数RootOpts通过#[command(flatten)]合并进Opts，子命令则封装在SubCommand枚举中。所有长参数均使用 kebab-case 命名（rename_all = "kebab-case"），并且绝大多数参数都绑定了对应的环境变量（通过env = "VECTOR_XXX"声明），因此你既可以用命令行参数，也可以用环境变量完成同样的配置。

根命令（Root Command）

通用 Flags

根级 flags 大多用于控制日志输出与全局行为，其中多数支持重复叠加（通过 clap 的ArgAction::Count实现）：

Flag	简写	说明	环境变量	默认值
`--help`	`-h`	打印帮助信息	—	—
`--version`	`-V`	打印版本信息	—	—
`--verbose`	`-v`	输出更详细的日志，可重复叠加以逐级提升级别，会覆盖`--quiet`	—	—
`--quiet`	`-q`	降低内部日志详细程度，可重复叠加，会覆盖`--verbose`	—	—
`--require-healthy`	`-r`	启动时若任一 sink 健康检查失败则直接退出	`VECTOR_REQUIRE_HEALTHY`	`false`
`--watch-config`	`-w`	监听配置文件变化并自动热重载	`VECTOR_WATCH_CONFIG`	`false`
`--no-graceful-shutdown-limit`	—	收到 SIGINT/SIGTERM 后永不强制超时退出（直到被 SIGKILL 终止），不能与`--graceful-shutdown-limit-secs`同时设置	`VECTOR_NO_GRACEFUL_SHUTDOWN_LIMIT`	`false`
`--openssl-no-probe`	—	禁用 OpenSSL 对系统根证书位置的探测与配置	`VECTOR_OPENSSL_NO_PROBE`	`false`
`--allow-empty-config`	—	允许在没有任何组件的情况下启动（通常需配合`--watch-config`使用）	`VECTOR_ALLOW_EMPTY_CONFIG`	`false`
`--dangerously-allow-env-var-interpolation`	—	允许配置文件中的环境变量插值（默认关闭，开启可能把环境变量中的机密暴露进配置）	`VECTOR_DANGEROUSLY_ALLOW_ENV_VAR_INTERPOLATION`	`false`

关于日志级别的叠加规则，src/cli.rs 中的log_level()方法给出了精确映射：默认info；-v为debug、-vv为trace；-q为warn、-qq为error、-qqq及以上为off。对于validate、graph、generate、list、test等一次性管理命令，根级别的 verbose/quiet 计数还会先做一次偏移调整，避免干扰命令自身的输出。

通用 Options

Option	简写	说明	环境变量	默认值
`--config`	`-c`	从指定文件读取配置，支持通配符路径与逗号分隔的多个文件；格式按扩展名（`.yaml`/`.toml`/`.json`）识别，无法识别时回退为 YAML	`VECTOR_CONFIG`	`/etc/vector/vector.yaml`
`--config-dir`	`-C`	从目录读取配置（可多个），非`.toml`/`.json`/`.yaml`/`.yml`结尾的文件被忽略	`VECTOR_CONFIG_DIR`	—
`--config-yaml`	—	读取配置并强制按 YAML 格式解释（支持通配符与多文件）	`VECTOR_CONFIG_YAML`	—
`--config-toml`	—	读取配置并强制按 TOML 格式解释	`VECTOR_CONFIG_TOML`	—
`--config-json`	—	读取配置并强制按 JSON 格式解释	`VECTOR_CONFIG_JSON`	—
`--graceful-shutdown-limit-secs`	—	收到 SIGINT/SIGTERM 后等待优雅退出的秒数，超时则强制退出	`VECTOR_GRACEFUL_SHUTDOWN_LIMIT_SECS`	`60`
`--watch-config-method`	—	配置文件监听方式：`recommended`（事件驱动，推荐）或`poll`（轮询，适用于 NFS 等事件监听失效的场景）	`VECTOR_WATCH_CONFIG_METHOD`	`recommended`
`--watch-config-poll-interval-seconds`	—	轮询监听时的检查间隔（仅当`--watch-config-method`为`poll`时生效）	`VECTOR_WATCH_CONFIG_POLL_INTERVAL_SECONDS`	`30`
`--color`	—	ANSI 终端着色控制，枚举值`auto`（自动检测）/`always`（始终开启）/`never`（关闭）	`VECTOR_COLOR`	`auto`
`--log-format`	—	日志输出格式：`text`或`json`	`VECTOR_LOG_FORMAT`	`text`
`--threads`	`-t`	处理线程数，默认等于可用 CPU 核数	`VECTOR_THREADS`	可用核数
`--chunk-size-events`	—	每个 source 发送批次的事件数，也是 source 输出缓冲区大小的基数	`VECTOR_CHUNK_SIZE_EVENTS`	`1000`
`--internal-log-rate-limit`	`-i`	内部日志限流窗口（秒），窗口内首条日志正常输出、第二条输出抑制警告、后续静默，窗口结束再次触发时汇总被抑制条数	`VECTOR_INTERNAL_LOG_RATE_LIMIT`	`10`
`--internal-logs-source-rate-limit`	—	作用于广播`internal_logs`source 的频道限流（秒），默认不设置，保证消费者收到每条日志	`VECTOR_INTERNAL_LOGS_SOURCE_RATE_LIMIT`	未设置
`--max-decompressed-size-bytes`	—	解压后负载允许的最大字节数，防止压缩炸弹耗尽内存	`VECTOR_MAX_DECOMPRESSED_SIZE_BYTES`	`104857600`（100 MiB）

一个典型的启动命令：

vector --config /etc/vector/vector.yaml --require-healthy -v

在 src/cli.rs 中可以核对上述定义：例如config参数通过value_delimiter(',')支持逗号分隔多文件；verbose/quiet使用ArgAction::Count支持重复计数；color的Auto模式在 Unix 下通过std::io::stdout().is_terminal()检测终端（Windows 的 cmd.exe 下直接禁用 ANSI），详见 src/cli.rs。

子命令详解

SubCommand枚举定义于 src/cli.rs，官方文档收录了以下九个公开子命令（另有convert-config、generate-schema、completion（隐藏）、service（仅 Windows 编译时启用）等未列入文档的子命令，可从源码枚举中查得）。各子命令都继承了根级 flags 与 options（_default_flags、_core_flags、_core_options），因此--config、--verbose等参数在子命令下同样可用。

`vector graph`：拓扑可视化

以 DOT 语言输出管道拓扑图，可配合 GraphViz 渲染成图片：

vector graph --config /etc/vector/vector.yaml | dot -Tsvg > graph.svg

该命令的--config等核心 options 与根命令一致；vector graph的渲染流程见 src/graph.rs 中的cmd实现。

`vector generate`：生成配置

根据组件列表生成一份 Vector 配置，参数pipeline使用组件/子组件语法描述流水线：

参数/选项	说明
`pipeline`（位置参数，string）	流水线表达式，例如`stdin/remap,filter/console`
`--fragment`/`-f`（flag）	跳过全局字段的生成，只输出组件片段
`--file`（option，string）	将生成的配置写入文件，例如`/etc/vector/my-config.toml`

示例：

vector generate stdin/remap,filter/console --file /etc/vector/my-config.toml

`vector list`：列出可用组件

列出当前二进制内编译进来的全部组件后退出，常用于确认某个组件是否可用：

vector list

Option	说明	默认值
`--format`	输出编码格式，枚举：`text`（文本）、`json`（JSON）、`avro`（Apache Avro）	`text`

`vector validate`：校验配置

校验目标配置的完整性与正确性后退出（不启动管道），是 CI 中检查配置变更的首选命令：

vector validate /etc/vector/vector.yaml

位置参数paths（list）：任意数量的配置文件；不指定时默认校验/etc/vector/vector.yaml。
--config-yaml/--config-toml/--config-json：分别强制按对应格式解释配置文件。
专属 flags：
- --no-environment：跳过环境检查（包括组件级检查与健康检查）；
- --skip-healthchecks：仅跳过健康检查；
- --deny-warnings/-d：将告警视为失败，任何 warning 都导致校验失败。

`vector test`：配置单元测试（实验性）

执行配置中内置的单元测试并退出。该命令标记为实验性，接口可能随版本变化；单元测试的编写方式可参考仓库中的unit_test相关模块（src/config/unit_test）。位置参数paths与validate相同，也支持--config-yaml/--config-toml/--config-json强制格式。

vector test /etc/vector/vector.yaml

`vector tap`：事件采样（实验性）

通过 Vector gRPC API 观察流经组件的真实事件：观察"进入 transforms/sinks 的输入"以及"从 sources/transforms 流出的输出"，并按固定间隔采样打印。

Flag	简写	说明
`--quiet`	`-q`	仅输出事件本身，抑制 stderr 上的诊断信息
`--meta`	`-m`	输出中附带`component_id`元数据，真实事件嵌套在`event`键下
`--no-reconnect`	`-n`	API 连接断开后不自动重连
`--duration_ms`	`-d`	指定采样时长（毫秒），例如`10000`表示采样 10 秒后自动退出

Option	简写	说明	默认值
`--url`	`-u`	Vector gRPC API 服务端点	—
`--interval`	`-i`	采样间隔（毫秒）	`500`
`--limit`	`-l`	每个采样间隔最多输出的事件数	`100`
`--format`	`-f`	事件输出编码，枚举：`json`、`yaml`、`logfmt`	`json`
`--inputs-of`	—	观察指定组件的输入（逗号分隔，支持 glob 模式）	空
`--outputs-of`	—	观察指定组件的输出（逗号分隔，支持 glob 模式）；仅当未指定任何`--outputs-of`/`--inputs-of`时默认值为`*`	`*`
`components`（位置参数，list）	—	待观察的组件（sources、transforms），逗号分隔，支持 glob	`*`

示例：

vector tap -u http://127.0.0.1:8686 --outputs-of 'sample*' -d 10000

`vector top`：控制台实时观测

以 TUI 形式在控制台展示本地或远程 Vector 实例的拓扑与指标（需编译topfeature）：

Flag	简写	说明
`--human-metrics`	`-H`	人性化指标数字，例如`1,100 → 1.10 k`、`1,000,000 → 1.00 M`
`--no-reconnect`	`-n`	连接断开后不自动重连

Option	简写	说明	默认值
`--components`	`-c`	待观察的组件 ID（逗号分隔，支持 glob）	`*`
`--interval`	`-i`	指标采样间隔（毫秒）	`1000`
`--url`	`-u`	Vector gRPC API 服务端点	—

vector top --url http://127.0.0.1:8686 -c 'kafka*'

tap与top都依赖 Vector 的 gRPC API，需要在目标实例的配置中启用api并开放对应地址（见 src/api）。

`vector vrl`：VRL 调试器

Vector Remap Language（VRL）的独立 CLI，可在不运行管道的情况下单步调试 VRL 程序，非常适合编写remap转换时反复试验：

vector vrl ".foo = true"

参数/选项	说明
`program`（位置参数，string）	要执行的 VRL 程序，例如`".foo = true"`将对象`foo`字段置为`true`
`--input`/`-i`（option）	存放待操作对象（一个或多个）的文件；留空则从 stdin 读取
`--program`/`-p`（option）	存放程序的脚本文件，可替代位置参数`PROGRAM`
`--print-object`/`-o`（flag）	打印（修改后的）整个对象，而非最后一条表达式的结果；等价于以`.`作为末条表达式

示例——从文件读取 JSON 对象并执行程序：

vector vrl -i event.json -p remap.vrl

`vector help`：帮助信息

vector help打印根命令帮助；vector help <subcommand>打印指定子命令的帮助。所有子命令的帮助也可以直接用vector <subcommand> --help查看。

环境变量（Environment Variables）

所有核心环境变量在 website/cue/reference/cli.cue 中集中定义，并通过 website/layouts/shortcodes/cli/env-vars.html 注入页面。除下列全局变量外，该小节还会合并aws_cloudwatch_logs、docker_logs、gcp_stackdriver_logs等组件专属的环境变量。

配置加载类

环境变量	说明	默认值
`VECTOR_CONFIG`	从文件读取配置（支持通配符与多文件），格式由扩展名推断，无法识别回退 YAML	`/etc/vector/vector.yaml`
`VECTOR_CONFIG_DIR`	从目录读取配置，非`.toml`/`.json`/`.yaml`/`.yml`文件被忽略	—
`VECTOR_CONFIG_YAML`	按 YAML 格式读取配置	—
`VECTOR_CONFIG_TOML`	按 TOML 格式读取配置	—
`VECTOR_CONFIG_JSON`	按 JSON 格式读取配置	—

日志与可观测类

环境变量	说明	默认值
`VECTOR_LOG`	日志级别，枚举：`ERROR`（等价`-qq`）、`WARN`（等价`-q`）、`INFO`（默认）、`DEBUG`（等价`-v`）、`TRACE`（等价`-vv`）	`INFO`
`VECTOR_LOG_FORMAT`	日志格式：`text`或`json`	`text`
`VECTOR_COLOR`	ANSI 着色：`auto`/`always`/`never`	`auto`
`VECTOR_INTERNAL_LOG_RATE_LIMIT`	内部日志限流窗口（秒），作用于 stdout/stderr 输出	`10`
`VECTOR_INTERNAL_LOGS_SOURCE_RATE_LIMIT`	`internal_logs`source 广播频道限流（秒），独立于上面的 stdout/stderr 限流	未设置
`VECTOR_HOSTNAME`	覆盖日志与指标中使用的 hostname，容器或 Kubernetes 场景下尤其有用（例如在 Pod 中取`spec.nodeName`）	—
`PROCFS_ROOT`	指定系统 procfs 挂载根路径，用于在容器内采集宿主主机指标	系统`/proc`
`SYSFS_ROOT`	指定系统 sysfs 挂载根路径，示例`/mnt/host/sys`	系统`/sys`
`RUST_BACKTRACE`	出错时打印 Rust backtrace，仅建议调试时开启（会降低性能）	`false`

运行与关闭行为类

环境变量	说明	默认值
`VECTOR_THREADS`	处理线程数	可用 CPU 核数
`VECTOR_CHUNK_SIZE_EVENTS`	每个 source 发送批次的事件数，及 source 输出缓冲的基数	`1000`
`VECTOR_REQUIRE_HEALTHY`	启动时任一 sink 健康检查失败即退出	`false`
`VECTOR_WATCH_CONFIG`	监听配置变更并热重载	`false`
`VECTOR_WATCH_CONFIG_METHOD`	监听方式：`recommended`或`poll`	`recommended`
`VECTOR_WATCH_CONFIG_POLL_INTERVAL_SECONDS`	轮询间隔（秒），仅`poll`模式生效	`30`
`VECTOR_GRACEFUL_SHUTDOWN_LIMIT_SECS`	SIGINT/SIGTERM 后的优雅退出等待秒数，超时强制退出	`60`
`VECTOR_NO_GRACEFUL_SHUTDOWN_LIMIT`	永不强制超时退出，直到被 SIGKILL 终止	`false`
`VECTOR_ALLOW_EMPTY_CONFIG`	允许无任何组件的空配置启动（通常配合配置热重载使用）	`false`

安全与兼容类

环境变量	说明	默认值
`VECTOR_DANGEROUSLY_ALLOW_ENV_VAR_INTERPOLATION`	允许配置中的环境变量插值（默认关闭，开启可能泄露环境机密）	`false`
`VECTOR_STRICT_ENV_VARS`	环境变量插值严格模式：缺失变量报错而非告警。该选项已弃用，未来版本将移除"降级为告警"的能力	`true`
`VECTOR_OPENSSL_NO_PROBE`	禁用 OpenSSL 根证书位置探测（该探测会修改进程内`SSL_CERT_FILE`/`SSL_CERT_DIR`，可能影响继承 Vector 环境的`exec`source）	`false`
`VECTOR_MAX_DECOMPRESSED_SIZE_BYTES`	解压后负载的最大字节数上限，防止压缩炸弹耗尽内存	`104857600`（100 MiB）

环境变量与命令行参数的对应关系可以在 src/cli.rs 的#[arg(env = "...")]声明中逐一印证，例如VECTOR_CONFIG↔--config、VECTOR_THREADS↔--threads。当两者同时出现时，命令行参数优先。

文档数据从哪里来：CUE 驱动文档生成

website/content/en/docs/reference/cli.md 本身非常精简，正文通过两个 shortcode 渲染出完整内容：

{{< cli/commands >}}：由 website/layouts/shortcodes/cli/commands.html 渲染，读取site.Data.docs.cli生成根命令与各子命令的 usage、flags/options/args 表格（支持枚举展开、环境变量交叉链接）；
{{< cli/env-vars >}}：由 website/layouts/shortcodes/cli/env-vars.html 渲染，合并cli.env_vars与部分组件专属环境变量。

而site.Data.docs.cli的源头正是 website/cue/reference/cli.cue：该文件以 CUE 模式（schema）定义了#Flags、#Options、#Commands、#Args、#EnvVars等结构化约束（例如带enum的 option 自动将 type 置为enum、无默认值的 option 标记为 required），再填充实际的命令与变量数据，最后生成 JSON 供站点使用。这意味着本文列出的所有参数、枚举与默认值都可以在 cli.cue 与 src/cli.rs 中双向核对，文档与实现保持一致。

实操建议：把 CLI 接入日常流程

CI 配置检查：任何配置变更合并前执行vector validate --deny-warnings <config>，让告警也阻塞发布；
变更前试运行单元测试：vector test <config>可在不启动管道的情况下验证test段断言；
拓扑审查：vector graph --config <config> | dot -Tpng > topology.png快速审查数据流；
线上排障：启用api后，用vector tap观察具体组件的输入输出、用vector top监控各组件吞吐与错误；
VRL 开发：先用vector vrl本地调好程序，再粘贴进remap转换，可显著减少线上试错；
容器场景：通过VECTOR_HOSTNAME注入有意义的节点名，通过PROCFS_ROOT/SYSFS_ROOT采集宿主指标。

如需进一步了解配置文件的完整语法与组件编写方式，可继续阅读 config/vector.yaml 与 website/content/en/docs/reference/configuration 下的参考文档。

【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析