bottom 0.14.9 配置参数详解

目标：讲清终端监控 bottom（命令 btm）0.14.9 的配置文件体系——配置路径与优先级、[flags] 通用开关、[processes]/[cpu]/[disk]/[disk_io_graph]/[temperature]/[temperature_graph]/[memory_graph]/[network_graph]/[styles]/[[row]] 布局共 11 个配置段的全量参数含义与默认值，并给出三份按场景验证可用的生产配置模板。全部参数说明对照官方默认配置文件（首跑自动生成的 511 行 bottom.toml）与官方文档逐项核对，关键参数均在本机实测生效。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS（x86_64），内核 6.8.0-138-generic
• 软件版本：bottom 0.14.9（官方最新稳定版，2026-08-27 发布；2026-10-23 经 GitHub Releases 实查确认）
• 配置文件参照：btm -C /root/.config/bottom/bottom.toml 首跑自动生成的默认配置（实测 511 行 / 15946 字节）
• 佐证来源：官方文档 configuration/config-file/* 页面（flags、layout、processes、disk-table 等，2026-10-23 拉取核对）
• 实测手段：非交互 pty 终端内启动 btm -C <配置> 抓取渲染帧，核对布局/列名/排序标记是否按配置变化；报错路径逐条实测退出码与回显

二、前置条件

按本篇操作前，请先确认：

1. 已安装 bottom 0.14.9 并能运行 btm -V（安装过程见《Ubuntu 22.04 安装 bottom 0.14.9 指南》）。
2. 操作在真实终端（TTY）中进行：btm 是 TUI 程序，无终端会直接报错退出（实测 Error: No such device or address (os error 6)，退出码 1）。
3. 理解配置生效机制：修改配置文件保存后重启 btm 才生效（bottom 无运行时热加载命令）。

三、参数查看与修改方式

3.1 配置文件位置与优先级

bottom 的配置是单个 TOML 文件，查找顺序（Linux，官方文档 config-file/index.md 实查）：

生效优先级：命令行 flag > 配置文件 [flags] 段。官方默认配置注释原文：「Flags explicitly added when running (ie: btm -a) will override this config file if an option is also set here.」

3.2 首跑自动生成默认配置

若配置文件不存在，bottom 会自动创建一份全量注释的默认配置（所有键被 # 注释，值即默认值）：

btm -C /root/.config/bottom/bottom.toml

（btm 会启动 TUI，按 q 退出后查看文件）

ls -lh /root/.config/bottom/bottom.toml

实测回显：

-rw-r--r-- 1 root root 15946 Oct 23 03:18 bottom.toml

wc -l /root/.config/bottom/bottom.toml

实测回显：

511 /root/.config/bottom/bottom.toml

💡 说明：这份自动生成的文件就是最权威的「参数清单」——11 个配置段全量列出并带注释。修改时去掉对应行的 # 注释即可覆盖默认值。

3.3 配置校验行为（三类实测）

bottom 启动时解析配置，错误处理分三类，均实测：

① TOML 语法错误——报解析位置并拒绝启动（实测退出码 1）：

Error: TOML parse error at line 3, column 14
  |
3 | broken_key =

② 键值非法——明确指出哪个键错：

Error: Configuration file error: 'rate' was set with an invalid value, please update it in your config file.

③ 未知键——静默忽略：实测配置文件写入 [flags] no_such_option = true 后 btm 正常启动渲染（不报错不告警）。这意味着拼写错误的键不会被发现，改配置后务必用渲染效果验证。

3.4 JSON Schema 支持

配置文件支持 JSON Schema（官方文档 config-file/index.md 实查），IDE/编辑器（VS Code 的 Even Better TOML 插件等）配置 schema 后可获得键名补全与校验，可有效规避上面第 ③ 类「未知键静默忽略」陷阱。

四、参数总览

默认配置文件共含 11 个配置段，总览如下（段名 → 作用 → 核心键）：

💡 技术拓展：[flags] 段是 0.14.x 之前的「旧式扁平配置」，新版本把各组件参数拆进了独立段（如进程搜索行为从 [flags] regex 迁到 [processes] regex）。旧键目前仍兼容但标记为 Deprecated，新配置一律用新段。映射关系：hide_avg_cpu→cpu.hide_avg_cpu、current_usage/group_processes/case_sensitive/whole_word/regex/process_memory_as_value/tree/unnormalized_cpu/process_command/disable_advanced_kill/hide_k_threads/tree_collapse→processes.、cpu_left_legend→cpu.left_legend、enable_cache_memory/free_arc→memory_graph.、network_use_bytes/network_use_binary_prefix/network_use_log→network_graph.*、memory_legend/network_legend→memory_graph/network_graph.legend_position、average_cpu_row→cpu.basic_average_cpu_row。

五、核心参数分类详解

5.1 [flags]：通用开关（等价命令行参数）

本段键与命令行 flag 一一对应（完整 flag 清单与实测见《bottom 0.14.9 常用 CLI 命令与工具详解》），此处列最常用键：

整段生效实测：写入如下配置后启动，实测渲染帧直接呈现基础模式（与命令行 btm -b 相同布局——AVG/逐核条形、RAM/SWP 条形、Disks/Temperature 第二行）：

[flags]
basic = true
rate = "2s"
retention = "30m"

[processes]
default_sort = "mem"

实测渲染帧关键字样（ANSI 剥离后照抄）：

 AVG[||||                               5%]  3  [||                                  5%] ...
 RAM[                                                                     0.0GiB/31.3GiB]  RX: 0.0/s
 SWP[                                                                      0.0GiB/2.0GiB ]  TX: 0.0/s
 ◄ Disks                                                                                                                                                              Temperature ►

⚠️ 注意：rate/retention 属「行为类」配置，静态帧无法肉眼核对，其生效以「配置加载无报错 + 官方语义」为准；basic/排序类「呈现类」配置均有渲染帧实证。

5.2 [processes]：进程组件

default_sort 生效实测：配置 default_sort = "mem" 后启动，进程表头实测出现降序标记（按内存排序）：

│PID(p)         Name(n)         CPU%(c)         Mem%(m)▼       R/s            W/s            ...

columns 生效实测：配置 columns = ["PID", "Name", "CPU%", "User"] 后，进程表头实测只显示这四列：

│PID(p)                                       Name(n)                                       CPU%(c)▼                                     User                                      │
│1                                            sleep                                         0.0%                                         root                                      │

5.3 [cpu]：CPU 组件

5.4 [disk] 与 [disk_io_graph]：磁盘表与 I/O 图

[disk] 键表：

过滤器结构（name_filter 与 mount_filter 同构）：

[disk.mount_filter]
is_list_ignored = true          # true=忽略命中项（黑名单），false=仅显示命中项（白名单）
list = ["/etc/hostname", "/etc/hosts"]
regex = false                   # list 项是否按正则解析
case_sensitive = false          # 是否大小写敏感
whole_word = false              # 是否整词匹配

生效实测：默认磁盘表实测显示三条挂载（/etc/hostname、/etc/hosts、/etc/resolv.co…，本实验环境共享宿主块设备 /dev/sda3）：

│Disk(d)▲  Mount(m)        Used(u)  Free(n)  Total(t)  Used%(p)  R/s(r)     │
│/dev/sda3 /etc/hostname   519GB    287GB    844GB     64.3%     0B/s       │
│/dev/sda3 /etc/hosts      519GB    287GB    844GB     64.3%     0B/s       │
│/dev/sda3 /etc/resolv.co… 519GB    287GB    844GB     64.3%     0B/s       │

配置 mount_filter（list 如上，is_list_ignored = true）后重启，实测 /etc/hostname 与 /etc/hosts 行被滤除，仅剩：

│Disk(d)▲  Mount(m)        Used(u)  Free(n)  Total(t)  Used%(p)  R/s(r)     │
│/dev/sda3 /etc/resolv.co… 519GB    287GB    844GB     64.3%     4KB/s      │

⚠️ 排障实录：想滤「挂载点」必须用 mount_filter，用 name_filter 填挂载点不会命中——name_filter 匹配的是设备名（如 /dev/sda3）。实测用 name_filter 过滤 /etc/hostname 时磁盘表毫无变化，改 mount_filter 后立即生效。

[disk_io_graph] 键表：

5.5 [temperature] 与 [temperature_graph]：温度表与温度图

[temperature] 键表：

[temperature_graph] 键表：

⚠️ 注意：温度数据依赖硬件传感器暴露。无传感器的虚拟机/云主机上温度组件显示 No data 属正常现象（本篇实测环境即如此），过滤与排序参数需在有机型传感器数据后才能观察效果。

5.6 [memory_graph]：内存图

💡 说明：cache_memory = true 后内存图会多出一条 Cache 曲线，对「内存涨了但其实是页缓存」的判断很有用；swap 独立曲线始终显示。

5.7 [network_graph]：网络图

5.8 [styles]：主题与自定义配色

两级机制：内置主题（--theme 或 [styles] theme）与自定义配色（styles.* 子段）。

内置主题六选一（非法值实测报错，退出码 2，回显列出全部可选值）：

error: invalid value 'bogus' for '--theme <SCHEME>'
  [possible values: default, default-light, gruvbox, gruvbox-light, nord, nord-light]

自定义配色子段（颜色值支持 colour/color 两种拼写，实测配置加载渲染正常）：

加载实测：写入 [styles.cpu] all_entry_colour = "cyan" 与 [styles.tables] headers = {colour = "light blue", bold = true} 后启动，渲染正常无报错（帧 12,311 字节，含全部组件）。

优先级：命令行 --theme > 自定义配色 > [styles] theme（官方默认配置注释说明「This will have the lowest precedence if a custom colour palette is set, or overridden if the command-line flag for a built-in theme is set」）。

5.9 [[row]]：自定义布局

布局按「行 → 列 → 组件」三层 TOML 嵌套描述：[[row]] 是一行，[[row.child]] 是行内一列（或直接给组件），[[row.child.child]] 是列内再分的组件；每个层级可设 ratio（相对占比，默认 1），组件用 type 指定。支持的 type 全集：

默认布局（来自默认配置注释，ratio 为 30/40/30 三行）：

[[row]]
  ratio=30
  [[row.child]]
  type="cpu"
[[row]]
  ratio=40
  [[row.child]]
    ratio=4
    type="mem"
  [[row.child]]
    ratio=3
    [[row.child.child]]
      type="temp"
    [[row.child.child]]
      type="disk"
[[row]]
  ratio=30
  [[row.child]]
    type="net"
  [[row.child]]
    type="proc"
    default=true

💡 说明：default = true 标记启动时默认选中的组件；同一组件可重复出现（如两个 CPU 图放不同行）。

自定义布局生效实测：配置「CPU 一行 + Processes 一行」两组件布局后启动，实测渲染帧只剩这两个组件（Memory/Temperatures/Disks/Network 均消失），Processes 组件占满第二行：

┌ CPU ─ 1.38 1.68 2.75 ─────────────────────────────┐┌─────────────────────────┐
│100%│                                               ││CPU          Use         │
...
┌ Processes ─────────────────────────────────────────────────────────────────┐
│PID(p)                                       Name(n)             CPU%(c)▼   User │

六、生产配置模板（三份实测可用）

以下三份模板均在本机逐份加载实测（渲染正常、无报错），按「低配 VPS / 日常排障 / 长时观察」三档场景给出。

模板一：低配 VPS 轻量档（1C512MB 级小机：关图形曲线降 CPU 占用、降刷新率）：

[flags]
basic = true          # 基础模式，无字符画布绘制开销
rate = "2s"           # 2 秒刷新，降低采集频率
retention = "10m"     # 默认保留时长
enable_cache_memory = false

[processes]
columns = ["PID", "Name", "CPU%", "Mem%", "User"]
default_sort = "CPU%"

模板二：日常排障主力档（进程为中心，I/O 列齐全，长保留便于回看）：

[flags]
default_time_value = "5m"
retention = "1h"
rate = "1s"

[processes]
default_sort = "CPU%"
columns = ["PID", "Name", "CPU%", "Mem%", "R/s", "W/s", "User", "State", "Time"]

[[row]]
  ratio=60
  [[row.child]]
  type="proc"
[[row]]
  ratio=40
  [[row.child]]
    ratio=2
    type="cpu"
  [[row.child]]
    ratio=1
    type="net"

实测渲染帧关键证据（进程表置顶、自定义 9 列、CPU% 降序标记、下方 CPU+Network）：

┌ Processes ──────────────────────────────────────────────────────────────────┐
│PID(p)              Name(n)              CPU%(c)▼             Mem%(m)  ...   │
┌ CPU ─ 1.56 1.68 2.05 ───────────────────────┐┌ Network ────────────────────┐

模板三：长时观察档（趋势观察：大窗口长保留 + 噪声挂载过滤）：

[flags]
default_time_value = "10m"
time_delta = "1m"
retention = "2h"
rate = "3s"
autohide_time = true

[disk.mount_filter]
is_list_ignored = true
list = ["/etc/hostname", "/etc/hosts"]
regex = false
case_sensitive = false
whole_word = false

⚠️ 注意：retention 越大内存占用越高（时序点存在进程内存里），2h 档在低配机器上请先观察 btm 自身的内存占用再决定是否上调。

七、常见问题

Q1：改了配置为什么没生效？

bottom 无热加载，保存配置后必须退出并重启 btm。另外确认改的段名拼写正确——未知键会被静默忽略（实测 [flags] no_such_option = true 不报错），建议装 JSON Schema 补全校验（见 3.4 节）。

Q2：启动报 Configuration file error: 'rate' was set with an invalid value？

对应键的取值超出合法范围。实测 rate = "abc" 即报此错（rate 需为 ≥250ms 的时间值）。改回合法值即可；报错信息会直接给出键名。

Q3：启动报 TOML parse error？

语法错误（少了引号/等号后的值等），报错含行号与列号，照着修：

Error: TOML parse error at line 3, column 14
  |
3 | broken_key =

Q4：旧配置里的 [flags] regex = true 还能用吗？

能跑（旧键兼容），但已标记 Deprecated，语义已迁移到 [processes] regex。建议迁移（映射表见第四章技术拓展），避免未来版本移除后配置失效。

Q5：想白名单只显示某几块盘怎么做？

把过滤器的 is_list_ignored 设为 false（只显示命中项），如：

[disk.name_filter]
is_list_ignored = false
list = ["/dev/sda"]
regex = false
case_sensitive = false
whole_word = false

黑名单/白名单语义由 is_list_ignored 一个键切换，name_filter 与 mount_filter 可同时启用叠加过滤。

八、参考链接

1. 官方配置文档（config-file）：https://clementtsang.github.io/bottom-stable/configuration/config-file/
2. 官方 flags 对照表：https://github.com/ClementTsang/bottom/blob/main/docs/content/configuration/config-file/flags.md
3. 官方默认配置样例：https://github.com/ClementTsang/bottom/blob/main/sample_configs/default_config.toml
4. 站内本组件系列：《bottom 介绍与选型指南》、《Ubuntu 22.04 安装 bottom 0.14.9 指南》、《bottom 0.14.9 常用 CLI 命令与工具详解》