sampler 1.1.0 常用 CLI 命令与工具详解

sampler 1.1.0 命令行与界面操作实测详解：-c/-e/-v 参数逐项、退出码速查、TUI 按键与菜单、布局调整回写配置（注释丢失警告）、tmux 常驻组合、rcon 边界说明与常用命令速查表。

sampler系统监控Linux命令行2026/10/23

sampler 1.1.0 常用 CLI 命令与工具详解

目标：讲清 sampler 1.1.0 的命令行用法与全屏界面操作——启动参数逐项实测、TUI 键盘交互与布局调整、退出时的配置回写行为、tmux 常驻组合，以及远程管理能力边界。所有命令、回显与界面画面均在 Ubuntu 22.04 服务器实测（2026-10-23）。配置文件写法见《sampler 1.1.0 配置参数详解》，安装见《Ubuntu 22.04 安装 sampler 1.1.0 指南》。

一、命令行总览

sampler 的 CLI 极简：没有子命令、没有守护进程形态、没有远程管理接口，全部选项只有 4 个。sampler --help 实测全文：

Usage:
  sampler [OPTIONS]

Application Options:
  -c, --config=  Path to YAML config file
  -e, --env=     Specify name=value variable to use in script placeholder as
                 $name. This flag takes precedence over the same name
                 variables, specified in config yml
  -v, --version  Print version

Help Options:
  -h, --help     Show this help message

一次完整的日常使用就是三步：写好 YAML → sampler -c 配置.yml 进入全屏界面 → 方向键/回车微调布局后 q 退出。

二、启动参数逐项详解

2.1 -c / --config：指定配置文件（事实必填）

sampler -c /root/config.yml
  • 路径支持绝对与相对路径，界面状态栏会显示实际加载的路径（实测 sampler 1.1.0 @ /root/config.yml）；
  • 虽然参数类型可省略，但省略 -c 无法进入界面：程序打印提示后退出，实测回显与退出码：
Please specify config file using --config flag. Example: sampler --config example.yml

退出码为 0——这是 1.1.0 的实现细节（提示后按成功状态退出）。脚本里预检配置时不能依赖退出码，要抓输出内容；同理，sampler 不带参数永远不会「误运行」一个默认仪表盘。

2.2 -e / --env：注入临时变量（可重复）

sampler -c mysql.yml -e DB_HOST=10.0.0.5 -e DB_PASS=xxxx
  • 值必须是 name=value 形式，在配置的 sample/init/transform 脚本里以 $name 引用；
  • 可以重复传多个（实测一次传 -e a=1 -e b=2 正常启动进入界面）；
  • 优先级实测结论：-e > 配置内 variables > 系统环境变量——同名时逐级覆盖（实测 -e vtest=fromcli 覆盖配置内同名变量，采样进程 env dump 显示 CLI 值）；
  • 注入范围实测：-e 变量会进入采样进程和触发器进程；配置内 variables 只进入采样进程、不进触发器进程（对照实测，详见《sampler 1.1.0 配置参数详解》第七节）。触发器里要用变量时一律走 -e。

2.3 -v / --version：打印版本

sampler -v

实测回显（单行，无版本前缀）：

1.1.0

2.4 -h / --help：帮助

输出即第一节的全文，退出码 0。

三、退出码速查

调用场景实测行为退出码
sampler -v / -h正常输出0
不带任何参数打印「Please specify config file…」提示0
配置校验错误（缺 sample、label/title 重复、init 互斥）Config validation error: …0
YAML 语法/类型错误Failed to read config file: …1
配置合法但无终端Failed to initialize ui: open /dev/tty: …1
空配置/未知顶层键/非法主题（panic 类）panic: …2
TUI 正常退出（q）界面关闭，可能回写配置（见 4.3 节）0

规律：校验类错误的退出码反而是 0，解析/环境类错误是 1，panic 是 2。做自动化预检请匹配输出文本而非退出码。

四、TUI 键盘交互（实测）

4.1 全局按键

按键作用实测说明
p / P暂停/恢复采样暂停时状态栏出现 P A U S E D（实测实录：sampler 1.1.0 @ /root/cfgs/ok-mi P A U S E D ection (p) pause (q) quit）；暂停期间所有采样停止，恢复后从当前时刻继续，历史断档不回填
方向键 ←→↑↓进入组件选择模式状态栏出现 (<->) selection 提示，被选中组件出现选中框
Enter对选中组件弹出操作菜单菜单见 4.2 节
ESC逐级返回默认模式从菜单/移动/缩放状态退出
鼠标左键点击选中/移动组件支持鼠标操作（实测环境未展开，源码支持）
q / Q / Ctrl-C退出程序若布局被调整过会先回写配置文件（见 4.3 节）

4.2 操作菜单（MOVE / RESIZE / PINPOINT / RESUME）

对选中组件按 Enter，弹出菜单（实测画面，菜单项纵向排列在组件中央）：

               MOVE
              RESIZE
             PINPOINT
              RESUME
  • MOVE：进入移动模式，方向键平移组件，Enter 确认；
  • RESIZE：进入缩放模式，方向键调整宽高，Enter 确认；
  • PINPOINT：数据点定位，仅对 runcharts 折线图有效——用于把光标钉在曲线上回看某时刻的数值（源码中该模式只接图表组件）；
  • RESUME：退出菜单回到默认模式。

4.3 布局调整与配置文件回写（实测）

在界面上 MOVE/RESIZE 之后按 q 退出，程序会把全部组件的最新 position 写回 -c 指定的配置文件。实测完整链路：选择组件 → 菜单选 MOVE → 按 3 次右方向键 → Enter 确认 → q 退出，配置文件 diff：

1d0
< # comment marker
4c3
<     position: [[0, 0], [40, 10]]
---
>     position: [[3, 0], [40, 10]]

两条实测结论：

  1. position 变化会落盘——界面里的布局调整即配置变更，无需手工改文件；
  2. 回写是全文件重序列化：注释会丢失（实测 # comment marker 行被抹除），键顺序与缩进按程序输出风格重排。配置文件里写了注释的，git 提交前要留意 diff；介意的话退出前用 RESUME 放弃调整，或对配置文件只读。

💡 实践建议：把仪表盘配置纳入 Git 管理——每次 q 退出的布局微调自动成为一次可审阅的文件变更。

4.4 状态栏与渲染节奏

  • 状态栏左侧固定显示 sampler 1.1.0 @ 配置文件路径，右侧随模式变化：默认 (q) quit (p) pause、选择模式 (<->) selection、暂停 P A U S E D；
  • 界面渲染频率与采样频率解耦：按所有组件中最小的 rate-ms × 0.5 计算，下限 100ms、上限 1000ms（源码常量核实）。例如最小 rate-ms=1000 时界面约 0.5 秒刷新一次；把某组件 rate-ms 调到 100 会带快全局刷新。

五、远程管理能力边界（rcon 问题说明）

1.1.0 没有 rcon、没有远程管理接口、没有 REST API。官方仓库主干 README 中出现过的 rcon 相关玩法未随 v1.1.0 发布，不要按新版文档写配置。1.1.0 的远程观测只有一条路径：交互 shell + SSH——在组件的 init 里先 ssh user@host 登录远端，sample 命令即在远端执行（见《sampler 1.1.0 配置参数详解》第九节）。另一个事实边界：v1.1.0 移除了早期版本的服务端数据回传，采样数据不出本机、不落盘，程序退出即清空。

六、tmux 常驻组合实操

sampler 是全屏交互程序，断开 SSH 即退出。需要长期挂着仪表盘时用 tmux 常驻：

tmux new-session -d -x 80 -y 40 -s sampler "TERM=xterm-256color sampler -c /root/config.yml"
tmux attach -t sampler      # 接入查看
tmux detach                 # Ctrl-b d 或此命令脱离，仪表盘继续跑
tmux kill-session -t sampler

实测要点：

  • -x 80 -y 40 很重要：sampler 按 80×40 画布布局，实测在 80×24 的默认小窗里组件被压缩，矮组件只剩空框不显示文字（复现与处置见《sampler 1.1.0 配置参数详解》第一节）；
  • TERM=xterm-256color 显式指定：避免 termbox: TERM environment variable not set 报错，且保证 256 色色号正确渲染；
  • 多仪表=多 tmux 会话：-s sampler-db、-s sampler-queue 各挂一份配置，互不干扰；
  • tmux 会话里同样可用全部 TUI 按键（p 暂停、方向键调整、q 退出回写），布局调整照常落盘。

七、常用命令速查

场景命令
查看版本sampler -v
查看帮助sampler --help
启动仪表盘sampler -c /root/config.yml
带临时变量启动sampler -c app.yml -e HOST=10.0.0.5 -e PORT=3306
tmux 常驻tmux new-session -d -x 80 -y 40 -s sampler "TERM=xterm-256color sampler -c /root/config.yml"
接入/脱离查看tmux attach -t sampler / tmux detach
暂停/恢复采样界面内按 p
停止界面内按 q（布局有变动会回写配置）

八、FAQ

Q1：能不重启就改采样频率吗？ 不能。1.1.0 没有热重载：改 YAML 后退出重开（注意 q 退出可能回写布局，建议改完配置直接重开）。

Q2：多个 -e 变量怎么传？ 重复 -e name=value 即可（实测支持任意个）；不要写成 -e a=1,b=2，后者会整体当作一个名为 a 之外无法拆分的变量值。

Q3：为什么脚本里判断 sampler 是否运行成功不可靠？ 见第三节退出码速查——缺参数、配置校验错误都返回 0。可靠做法是匹配输出中的 Config validation error / Failed to 字样，或直接在 tmux 里确认界面。

Q4：暂停期间会不会丢曲线数据？ 会形成断档。暂停只停止采样，恢复后从当下继续画，中间的空窗不会补数据点。

Q5：q 退出后配置文件格式变了、注释没了，正常吗？ 正常且必然——回写是全文件重新序列化（实测见 4.3 节）。需要保留注释就别在界面里调整布局，或把注释挪到外部文档。

九、参考链接

  1. 官方仓库：https://github.com/sqshq/sampler
  2. v1.1.0 发布页：https://github.com/sqshq/sampler/releases/tag/v1.1.0
  3. 系列文档：《sampler 介绍与选型指南》、《Ubuntu 22.04 安装 sampler 1.1.0 指南》、《sampler 1.1.0 配置参数详解》