Ubuntu 22.04 安装 sampler 1.1.0 指南

目标：在 Ubuntu 22.04 服务器上从零安装终端命令输出可视化工具 sampler（sqshq/sampler）1.1.0，覆盖官方二进制安装（主推）、源码编译安装、Homebrew 安装三种方案，并沉淀 libasound2 缺失、TERM 未设置等真实排障过程。本文全部命令与回显均在 Ubuntu 22.04 环境逐条实测。

一、环境信息

项目	值
操作系统	Ubuntu 22.04.5 LTS（x86_64）
sampler 版本	1.1.0（官方最新稳定版，发布于 2019-12-24；2026-10-23 实查仍为最新）
官方二进制	sampler-1.1.0-linux-amd64，5,587,072 字节
官方二进制 sha256	16ebaa71be225d98801cfed6fcfca466002f604a2354a333029ba280c11601b4
运行时系统库	libasound2 1.2.6.1-1ubuntu1.2（Ubuntu 22.04 jammy 仓库候选版本）
编译方案工具链	golang-go 1.18.1 + libasound2-dev（Ubuntu 22.04 仓库版本）
Homebrew 方案实测依赖	alsa-lib 1.2.16.1_1（brew 自动带入；首次使用 Homebrew on Linux 还会装入 glibc/gcc/binutils 等工具链）
安装目标路径	/usr/local/bin/sampler

⚠️ 注意：sampler 1.1.0 是 2019 年底发布的版本，此后项目未再发版。安装的是这个「最终版」而非「最新开发态」，选型前请先阅读《sampler 介绍与选型指南》中对维护状态的说明。

二、前置条件

2.1 运行前置：libasound2 系统库（必须）

官方 README 说明 sampler 的触发器提示音（NASA quindar tone）依赖 ALSA 用户态库 libasound2。实测进一步确认：该库是硬依赖——官方 Linux 二进制以动态链接方式引用 libasound.so.2，缺库时程序根本无法加载。裸装 Ubuntu 22.04 Server 默认不带该库，必须先安装：

apt-get install -y libasound2

实测回显（输出节选，实测首尾）：

Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
The following additional packages will be installed:
  alsa-ucm-conf
...
Setting up libasound2:amd64 (1.2.6.1-1ubuntu1.2) ...
Setting up alsa-ucm-conf (1.2.6.3-1ubuntu1.12) ...

验证安装结果：

dpkg -l libasound2 | tail -1

实测回显：

ii  libasound2:amd64 1.2.6.1-1ubuntu1.2 amd64        shared library for ALSA applications

💡 说明：无头服务器没有声卡，libasound2 只是让程序能加载、触发器 sound 动作静默跳过；运行期 stderr 会打印几行 ALSA lib ... cannot find card '0' 类警告，属正常现象（见「十一、常见问题」）。

2.2 运行前置：真实终端（TTY）

sampler 是全屏 TUI 程序，必须在真实终端会话中运行。SSH 登录会话、tmux/screen、桌面终端均满足；nohup/cron 等无终端后台环境无法运行（实测回显见「十一、常见问题」）。本文所有验证命令均在 SSH 终端会话中执行。

三、版本选型说明

GitHub Releases 上 sampler 共 7 个标签，全部实查于 2026-10-23：

版本	发布日期	说明
v1.1.0	2019-12-24	最新稳定版；移除全部服务端数据回传；推荐安装
v1.0.3	2019-08-18	修复 asciibox/textbox 触发器
v1.0.2	2019-08-07	切换到 GPLv3
v1.0.1	2019-08-05	引入用户友好的配置校验
v1.0.0	2019-07-29	首个正式版，Windows 支持、PTY 模式
v0.9.1-beta / v0.9.0-beta	2019-06-02 / 2019-04-09	公测版

各平台的 v1.1.0 官方发行件：

发行件	大小	适用平台
sampler-1.1.0-linux-amd64	5.33 MB	Linux x86_64
sampler-1.1.0-darwin-amd64	6.14 MB	macOS Intel
sampler-1.1.0-windows-amd64.exe	5.41 MB	Windows x86_64

💡 说明：没有独立发行版仓库（apt/yum 源中没有 sampler 软件包），Ubuntu 上的安装路径就是「官方二进制」「源码编译」「Homebrew」三种，下文逐一展开。

四、方案 A：官方二进制安装（推荐）

4.1 方案说明

直接下载 GitHub Releases 上的 Linux amd64 单文件二进制放到 PATH 目录，最快、最贴近官方 README 的安装方式；适合绝大多数 x86_64 服务器。

4.2 下载与校验

wget https://github.com/sqshq/sampler/releases/download/v1.1.0/sampler-1.1.0-linux-amd64 -O /tmp/sampler-1.1.0-linux-amd64

下载完成后校验大小与 sha256（本篇实测值）：

ls -la /tmp/sampler-1.1.0-linux-amd64
sha256sum /tmp/sampler-1.1.0-linux-amd64

实测回显：

-rw-r--r-- 1 root root 5587072 Oct 23 12:02 /tmp/sampler-1.1.0-linux-amd64
16ebaa71be225d98801cfed6fcfca466002f604a2354a333029ba280c11601b4  /tmp/sampler-1.1.0-linux-amd64

⚠️ 注意：GitHub 直连慢或失败时，可经 HTTP 代理下载（命令实测可用）：
curl -x http://192.168.1.62:7897 -sLO https://github.com/sqshq/sampler/releases/download/v1.1.0/sampler-1.1.0-linux-amd64

4.3 安装到系统路径

install -m 0755 /tmp/sampler-1.1.0-linux-amd64 /usr/local/bin/sampler
which sampler

实测回显：

/usr/local/bin/sampler

4.4 排障实录：缺 libasound2 时的加载失败

如果跳过第 2.1 节直接安装运行，会得到如下真实报错（逐字实录）：

sampler --help

sampler: error while loading shared libraries: libasound.so.2: cannot open shared object file: No such file or directory

退出码为 127（命令未能加载执行）。用 ldd 定位缺哪个库：

ldd /usr/local/bin/sampler

实测回显（可看到 libasound.so.2 => not found）：

        linux-vdso.so.1 (0x00007ffee572c000)
        libasound.so.2 => not found
        libpthread.so.0 => /lib/x86_64-linux-gnu/libpthread.so.0 (0x000079c56e43e000)
        libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 (0x000079c56e215000)
        /lib64/ld-linux-x86-64.so.2 (0x000079c56e447000)

解决方案：执行第 2.1 节的 apt-get install -y libasound2 后复核：

ldd /usr/local/bin/sampler

实测回显（缺库项已消解）：

        linux-vdso.so.1 (0x00007fff4cbaa000)
        libasound.so.2 => /lib/x86_64-linux-gnu/libasound.so.2 (0x00007c933a044000)
        libpthread.so.0 => /lib/x86_64-linux-gnu/libpthread.so.0 (0x000079c56e43c000)
        libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 (0x000079c56e22f000)
        libm.so.6 => /lib/x86_64-linux-gnu/libm.so.6 (0x000079c56e226000)
        /lib64/ld-linux-x86-64.so.2 (0x000079c56e35b000)

4.5 验证安装

sampler -v

实测回显：

1.1.0

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

最后做一次真实启动验证。写一个最小配置：

cat > /root/config.yml <<'EOF'
runcharts:
  - title: LOAD AVERAGE
    position: [[0, 0], [40, 10]]
    rate-ms: 1000
    scale: 2
    items:
      - label: LOAD 1M
        sample: cat /proc/loadavg | awk '{print $1}'
EOF

在终端会话中启动（全屏 TUI；按 q 退出）：

sampler -c /root/config.yml

实测界面（tmux 会话内截取的 TUI 首屏，负载曲线随时间滚动）：

┌─ LOAD AVERAGE ─────────────────────────────────────────────────┐
│    ┊                                                           │
│1.67┊         ┊         ┊         ┊         ┊• LOAD 1M┊         │
│    ┊                                              ⢀⠔⠉⠉         │
│1.49┊         ┊         ┊         ┊         ┊       ⢰         │
│    ┊                                             ⡎             │
│1.28┊         ┊         ┊         ┊         ┊      ⠉⠉⠉⠉⠉      │
│    └┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈│
│04:11:23  04:11:28  04:11:33  04:11:38  04:11:43  04:11:48      │
└────────────────────────────────────────────────────────────────┘

 sampler 1.1.0 @ /root/config.yml                    (q) quit  (p) pause

💡 说明：截图中折线为盲文点阵字符（U+2800 区），Y 轴数值与 X 轴时间刻度由程序自动标定；底部状态栏左侧为 sampler 1.1.0 @ 配置文件路径，右侧为按键提示。配置文件的写法详见《sampler 1.1.0 配置参数详解》。

五、方案 B：源码编译安装

5.1 方案说明

适合无法使用官方二进制的环境（如需要自行改代码、安全审计要求从源码构建、或需要重打包）。sampler 是 Go 项目，编译链简单，但有一个 C 依赖需要提前准备：ALSA 开发头文件 libasound2-dev（声音模块的编译依赖）。

5.2 安装编译工具链

apt-get install -y golang-go git libasound2-dev build-essential
go version

实测回显：

go version go1.18.1 linux/amd64

5.3 获取源码

推荐下载 v1.1.0 源码包（与发布版一一对应）：

wget https://github.com/sqshq/sampler/archive/refs/tags/v1.1.0.tar.gz -O /tmp/sampler-1.1.0-src.tar.gz
tar -xzf /tmp/sampler-1.1.0-src.tar.gz -C /opt
cd /opt/sampler-1.1.0

5.4 编译

Go 模块依赖需要联网拉取，国内网络推荐显式指定模块代理（实测可用）：

GOPROXY=https://goproxy.cn,direct GO111MODULE=on go build -o /usr/local/bin/sampler .

⚠️ 排障实录：若漏装 libasound2-dev，编译会在声音模块处失败，真实报错如下（逐字实录）：
# github.com/hajimehoshi/oto
../go/pkg/mod/github.com/hajimehoshi/oto@v0.1.1/player_linux.go:23:10: fatal error: alsa/asoundlib.h: No such file or directory
   23 | #include <alsa/asoundlib.h>
      |          ^~~~~~~~~~~~~~~~~~
compilation terminated.
解决方案：apt-get install -y libasound2-dev 后重新执行 go build。

5.5 验证

/usr/local/bin/sampler -v
ls -la /usr/local/bin/sampler
sha256sum /usr/local/bin/sampler

实测回显：

1.1.0
-rwxr-xr-x 1 root root 4233728 Oct 23 04:23 /usr/local/bin/sampler
cade4a2211ef71e559e38f4cc6e86aca35c36469ddf2de9c6cd6c36e8b78b9e3  /usr/local/bin/sampler

💡 说明：自编译二进制的 sha256 与官方发行件（16ebaa71…）不同属正常现象——构建环境、Go 版本、链接方式都会影响产物指纹，以 -v 输出的版本号为准。

六、方案 C：Homebrew 安装（Linux）

6.1 方案说明

Homebrew 官方仓库（homebrew/core）收录了 sampler formula：版本 1.1.0，许可证 GPL-3.0-only，提供 Linux x86_64 预编译 bottle，安装时自动带入 alsa-lib 依赖（formula 元数据实查于 2026-10-23，formula 数据：https://formulae.brew.sh/api/formula/sampler.json）。适合已经在用 Homebrew 管理软件的 Linux 环境。

⚠️ 注意：本方案的前置是先安装 Homebrew on Linux（安装脚本：https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh，需要 curl、git、build-essential，官方要求以非 root 普通用户执行，安装器在 /home/linuxbrew/.linuxbrew 落地）。本节命令已在 Ubuntu 22.04 环境完整实测（含 Homebrew 引导安装与 sampler 安装全程）。

6.2 安装

brew install sampler

实测回显（节选）：brew 自动解析依赖并逐个 Pouring 预编译 bottle，最后安装 sampler 本体。首次在裸 Linux 上使用 Homebrew 时会先装入 glibc、gcc、binutils 等工具链依赖（Homebrew on Linux 的固有行为，体积较大，与 sampler 无关），随后自动带入 alsa-lib：

==> Installing sampler dependency: glibc (2.39_1)
==> Pouring glibc--2.39_1.x86_64_linux.bottle.2.tar.gz
...
==> Installing sampler dependency: binutils (2.47)
==> Pouring binutils--2.47.x86_64_linux.bottle.tar.gz
==> Installing sampler dependency: gcc (16.2.0)
==> Pouring gcc--16.2.0.x86_64_linux.bottle.1.tar.gz
==> Installing sampler dependency: alsa-lib (1.2.16.1_1)
==> Pouring alsa-lib--1.2.16.1_1.x86_64_linux.bottle.tar.gz
==> Installing sampler
==> Pouring sampler--1.1.0.x86_64_linux.bottle.tar.gz

安装完成后二进制以符号链接形式出现在 Homebrew 的 bin 目录（默认 /home/linuxbrew/.linuxbrew/bin，确保该目录在 PATH 中）。

6.3 验证

brew list --versions sampler alsa-lib
sampler -v
which sampler

实测回显：

alsa-lib 1.2.16.1_1
sampler 1.1.0
1.1.0
/home/linuxbrew/.linuxbrew/bin/sampler

二进制链接关系实测为 /home/linuxbrew/.linuxbrew/bin/sampler -> ../Cellar/sampler/1.1.0/bin/sampler。若 sampler 不在 PATH，把 eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)" 加入 ~/.bashrc 后重开终端。

💡 说明：Homebrew 渠道的版本与官方 Releases 同步（均为 1.1.0，项目停更后不再变化）；formula 元数据显示近一年（截至 2026-10-23）该渠道安装量约 290 次，属于小众但可用的路径。

七、多方案对比与选择建议

维度	A 官方二进制	B 源码编译	C Homebrew
得到的版本	1.1.0	1.1.0（源码对应 tag）	1.1.0
是否需联网	是（GitHub）	是（GitHub + Go 模块源）	是（brew 仓库 + ghcr.io）
系统依赖	libasound2	golang-go、git、libasound2-dev、build-essential	Homebrew 工具链（glibc/gcc 等 brew 自动装入）+ alsa-lib
安装位置	/usr/local/bin/sampler（自定）	同左（自定）	/home/linuxbrew/.linuxbrew/bin
升级方式	重新下载替换	重新拉 tag 编译	brew upgrade
适合场景	绝大多数服务器（推荐）	内网源码审计/自行改码	已有 Homebrew 体系

选择建议：可联网的 x86_64 服务器一律选方案 A，两分钟内完成且与官方 README 路径一致；需要改造源码或审计二进制来源时选方案 B；仅在团队已统一用 Homebrew 管理工具链时选方案 C。三种方案得到的都是同一个 1.1.0，运行行为无差异。

八、安装后配置说明

sampler 没有安装级配置：不存在系统级配置文件，一切行为由启动时 -c 指定的 YAML 决定（且 1.1.0 必须显式传 -c，不传会得到提示后退出，见「十、常见问题」）。建议的配置管理约定：

每个仪表盘一个 YAML 文件，按用途命名（如 load.yml、mysql.yml），集中放在 /etc/sampler/ 或运维用户的家目录；
配置纳入 Git 版本管理——sampler 退出时会把界面里调整过的组件布局回写到该文件（详见《sampler 1.1.0 常用 CLI 命令与工具详解》），等于布局变更自动留痕；
参数含义、默认值与全部组件写法见《sampler 1.1.0 配置参数详解》。

九、systemd 托管说明

sampler 是交互式 TUI 程序，不适合也不需要 systemd 服务托管：它没有守护进程形态，systemd 启动会因为没有 TTY 直接失败（实测报错见下一节）。需要在断开 SSH 后持续显示仪表盘时，用 tmux 常驻替代：

apt-get install -y tmux
tmux new-session -d -s sampler "TERM=xterm-256color sampler -c /root/config.yml"
tmux attach -t sampler    # 需要查看时接入

实测确认：该方式下 sampler 正常渲染，退出 attach 后继续采样；需要停止时 tmux kill-session -t sampler。

十、常见问题（FAQ）

Q1：启动报 open /dev/tty: no such device or address 怎么办？ 这是在无终端环境（nohup、cron、CI 管道、docker exec 非交互壳等）运行的典型报错，实测回显：

2026/10/23 04:03:17 Failed to initialize ui: open /dev/tty: no such device or address

退出码 1。解决：在真实终端会话中运行；需要常驻就用 tmux（见第九节）。

Q2：报 termbox: TERM environment variable not set 怎么办？ 终端类型变量未设置（常见于脚本封装的 tmux 会话或精简环境），实测回显：

2026/10/23 04:10:08 Failed to initialize ui: termbox: error while reading terminfo data: termbox: TERM environment variable not set

解决：显式指定终端类型再运行，如 TERM=xterm-256color sampler -c config.yml。

Q3：sampler 不带参数直接回车会怎样？ 得到提示语后立即退出，实测回显与退出码：

Please specify config file using --config flag. Example: sampler --config example.yml

退出码为 0。这是 1.1.0 的实现细节（提示后按成功状态退出），脚本里判断 sampler 是否执行成功时不要依赖该退出码。

Q4：运行时 stderr 刷 ALSA lib ... cannot find card '0' 警告？ 无头服务器无声卡，ALSA 找不到默认 PCM 设备，实测警告节选：

ALSA lib confmisc.c:855:(parse_card) cannot find card '0'
ALSA lib pcm.c:2664:(snd_pcm_open_noupdate) Unknown PCM default

程序不受影响，界面正常渲染；触发器的 sound: true 动作会静默跳过（没有声卡可响）。想消除警告可以把 stderr 重定向：sampler -c config.yml 2>/dev/null。

Q5：下载 GitHub Release 慢/失败？ 走 HTTP 代理重试（实测可用）：

curl -x http://192.168.1.62:7897 -sLO https://github.com/sqshq/sampler/releases/download/v1.1.0/sampler-1.1.0-linux-amd64

十一、卸载与清理

按安装方案对应清理即可：

# 方案 A / B 安装的二进制
rm -f /usr/local/bin/sampler

# 方案 C（Homebrew）
brew uninstall sampler

# 编译方案留下的源码目录（按实际路径）
rm -rf /opt/sampler-1.1.0

# 配置与临时下载件
rm -f /root/config.yml /tmp/sampler-1.1.0-linux-amd64 /tmp/sampler-1.1.0-src.tar.gz

卸载后确认：

which sampler || echo "sampler 已卸载"

实测回显：

sampler 已卸载

💡 说明：sampler 无数据库、无日志目录、无常驻服务，删除二进制即完成卸载，不产生残留。

十二、参考链接

官方仓库与 README 安装说明：https://github.com/sqshq/sampler
v1.1.0 发布页：https://github.com/sqshq/sampler/releases/tag/v1.1.0
Homebrew formula 元数据：https://formulae.brew.sh/api/formula/sampler.json
系列文档：《sampler 介绍与选型指南》《sampler 1.1.0 配置参数详解》《sampler 1.1.0 常用 CLI 命令与工具详解》（见 sampler 专栏）