gtop 1.1.5 配置参数详解

目标：讲清 gtop 1.1.5 的配置模型——它没有配置文件、没有命令行参数，可用配置面只有「环境变量与终端适配」与「源码级定制」两类；本文给出两类配置的完整实测方法：环境变量逐项实测（LANG/LC_ALL/TERM/终端尺寸），图块数据源与刷新间隔逐项源码实查，并以"修改进程表刷新间隔 3000→1000 毫秒"为实例完整演示源码定制的修改、验证与还原。

一、环境信息

• 操作系统：Debian 12（bookworm），x86_64；12 核 CPU、32 GB 内存
• Node.js：v22.23.4（npm 10.9.9）
• gtop：1.1.5（npm 全局安装于 /usr/local/lib/node_modules/gtop）
• 终端：tmux 3.3a 会话内 TERM=xterm-256color、LANG=C.UTF-8（另有 script 伪终端对照实验）
• 证据来源：包内源码实查（/usr/local/lib/node_modules/gtop/ 下的 lib/gtop.js、lib/monitor/*.js、lib/utils.js）+ 本机实测运行

二、前置条件

• 已按 《Ubuntu 24.04 安装 gtop 1.1.5 指南》 完成安装，which gtop 能返回 /usr/local/bin/gtop；
• 本文涉及源码定制的实验需要 root（或对 /usr/local/lib/node_modules/gtop 有写权限）的用户；
• 验证实验统一用 tmux 会话承载 TUI（tmux new-session -d -s <名> -x 120 -y 40），保证有确定的终端尺寸。

三、配置模型总览：没有配置文件，也没有命令行参数

gtop 的配置模型在同类工具里属于极端简单的一档：全部行为硬编码在源码里，用户可调的只有三样——环境变量、终端属性、源码本身。这个结论不是推测，以下三条证据均来自 v1.1.5 实机：

证据 1：包内不存在任何配置文件。 安装目录文件清单实测：

ls /usr/local/lib/node_modules/gtop/

实测回显：

CLI.md
Dockerfile
LICENSE
README.md
bin
gtop.1
index.js
lib
node_modules
package.json

全目录没有 conf/cfg/config 类文件，也没有 . 开头的用户配置约定。

证据 2：入口脚本不解析参数。 启动入口 bin/gtop 全文只有三行（实测 cat 回显）：

#!/usr/bin/env node

require('../lib/gtop').init()

没有任何 argv 解析逻辑。

证据 3：命令行参数被整体忽略。 分别带 --help、--version 启动，实测两者都照常进入全屏 TUI（而非打印帮助或版本号）：

timeout 5 script -q -c "stty cols 120 rows 40; gtop --help" /dev/null </dev/null | wc -c
timeout 5 script -q -c "stty cols 120 rows 40; gtop --version" /dev/null </dev/null | wc -c

实测回显：

8552
8579

两次输出字节数与正常运行 gtop 的屏幕输出（8–11 KB 量级）一致，证明 gtop --help/gtop --version 实际渲染的就是仪表盘本身——gtop 不支持任何子命令与选项，写成 gtop [参数] 的用法都是无效的。

💡 说明：因此本文标题虽沿用系列统一的"配置参数详解"，实际内容对应的是 gtop 的"配置与定制"——这符合该项目的真实形态。网上若见"gtop 配置文件教程"类内容，请先对照本节证据甄别。

四、环境变量与终端适配（逐项实测）

gtop 渲染依赖终端环境，实际生效的环境变量有三类。

4.1 LANG / LC_ALL：locale 决定图形字符能否显示

gtop 的曲线用 Braille 盲文字符（⣿⣾⠉⠓ 等 2×4 点阵字符）绘制，边框用终端 ACS 线条字符集。locale 必须是 UTF-8 系，否则字符画布显示退化。官方 README（2026-10-23 实查）明确给出的推荐启动方式：

LANG=en_US.utf8 TERM=xterm-256color gtop

实测对照（同一台机器，只改 locale）：

结论与建议：保持系统 locale 为任意 *.UTF-8（C.UTF-8、en_US.UTF-8 均实测正常）；SSH 客户端同步使用 UTF-8 编码。

4.2 TERM：终端类型决定渲染模式

# 推荐值（官方 README 同款）
export TERM=xterm-256color

实测：TERM=xterm-256color 下 gtop 正常全屏渲染、按 q 正常退出。对照实验把 TERM 设为 dumb 后启动 gtop，程序仍会启动并尝试渲染，但屏幕布局错乱、区块内容堆叠成一团（实测抓屏可见全部图块内容挤作一团，无光标定位效果），必须强杀才能退出。结论：TERM 必须是真实的终端类型；dumb/未设置都属于"能跑但不可用"。

4.3 终端尺寸：宽度拿不到会直接崩溃

实测边界：

报错原文（实测回显）：

Error: Width must be multiple of 2!
    at new Canvas (/usr/local/lib/node_modules/gtop/node_modules/drawille-blessed-contrib/index.js:10:11)
    at new Context (/usr/local/lib/node_modules/gtop/node_modules/drawille-canvas-blessed-contrib/index.js:11:18)
    ...

原因：画布宽度按终端宽度×2 计算，终端宽度不可得（NaN）时画布构造失败直接抛错。注意该报错与"宽度是不是奇数"无关——实测 stty cols 119（奇数宽）下 gtop 照常运行；关键在于程序能否取到终端宽度。建议会话不小于 100×30，保证七图块不互相挤压。

💡 说明：gtop 没有单独的"最小尺寸"官方参数，上表边界为本文实测值；常见的触发场景是把 gtop 写进 cron/CI 脚本等无 tty 环境执行——那是用法错误而非配置问题（处置见《gtop 1.1.5 常用 CLI 命令与工具详解》常见问题节）。

五、图块数据源与刷新间隔（源码实查，硬编码）

七个图块的采集模块、systeminformation 接口与刷新间隔全部硬编码在 lib/monitor/ 下，逐文件实查结果如下（行号为 v1.1.5 实测）：

图块排布与外观参数硬编码在 lib/gtop.js：整体为 12×12 网格（contrib.grid({rows: 12, cols: 12, ...})），每块用 grid.set(行, 列, 宽, 高, 组件类型, 选项) 定义；进程表列宽 columnWidth: [7, 24, 7, 7]（PID、Command、%CPU、%MEM），CPU/内存曲线纵轴固定 maxY: 100。多核曲线的颜色顺序来自 lib/utils.js：

utils.colors = ['magenta', 'cyan', 'blue', 'yellow', 'green', 'red'];

即 CPU1 起依次为品红、青、蓝、黄、绿、红，六个色循环使用（12 核机器上第 7 核重新从品红开始，与实测屏幕上 CPU7 曲线颜色一致）。

进程表排序的实现也在 proc.js：按键 p/c/m 设置排序键（pid/cpu/mem），同一键再按一次反转升降序（源码 that.reverse = !that.reverse），排序动作立即触发一次重新采集刷新。这些行为均不可配置，只能通过改源码调整（见下节）。

六、源码级定制（实测演示）

6.1 可定制点清单

6.2 实测：把进程表刷新间隔从 3 秒改为 1 秒

以最常见的定制诉求"进程表刷新太慢"为例，完整实测一遍修改 → 验证 → 还原：

# 1. 备份原文件
cp /usr/local/lib/node_modules/gtop/lib/monitor/proc.js /tmp/proc.js.bak

# 2. 修改刷新间隔：3000 → 1000（毫秒）
sed -i 's/setInterval(updater, 3000)/setInterval(updater, 1000)/' \
  /usr/local/lib/node_modules/gtop/lib/monitor/proc.js

# 3. 确认修改生效
grep -n 'setInterval' /usr/local/lib/node_modules/gtop/lib/monitor/proc.js

实测回显：

27:  this.interval = setInterval(updater, 1000);

# 4. 重启 gtop 验证功能正常（tmux 会话内启动并抓屏检查 Processes 图块）
tmux new-session -d -s gtop2 -x 120 -y 40 'gtop'
sleep 5
tmux capture-pane -t gtop2 -p | grep Processes

实测回显：

lqNetwork HistoryqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqklqProcessesqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqk

修改后 gtop 正常启动、进程表正常渲染、按 q 正常退出——改源码不需要重新编译，Node.js 解释执行，重启进程即生效。进程表此时每 1 秒刷新一次（原 3 秒）。

# 5. 还原
cp /tmp/proc.js.bak /usr/local/lib/node_modules/gtop/lib/monitor/proc.js
grep -n 'setInterval(updater' /usr/local/lib/node_modules/gtop/lib/monitor/proc.js

实测回显：

27:  this.interval = setInterval(updater, 3000);

6.3 定制的边界

• 改源码是一次性技能而非可持续方案：gtop 上游自 2023-08 起未再发版（维护状态见 《gtop 介绍与选型指南》），你的改动不会被上游"冲掉"，但也无人帮你维护；
• 重装即还原：npm install -g gtop（或重装任意版本）会整体覆盖包目录，源码定制全部丢失——改源码前务必备份 lib/ 目录；
• 不要改 blessed/blessed-contrib 依赖内部：gtop 只引用了它们的公开组件，依赖内部行为不在本篇定制范围内。

七、常见问题（FAQ）

Q1：网上说 gtop 有配置文件/参数，为什么我找不到？

因为不存在。判断依据见本文第三节的三条证据（包内文件清单、入口脚本、参数忽略实测）。凡引用 gtop.conf、~/.gtoprc、gtop --option 之类的内容均非官方行为，请勿采用。

Q2：改了刷新间隔/布局后 gtop 启动报错怎么办？

先还原再排查：cp 回备份文件（见 6.2 第 5 步），或直接 npm uninstall -g gtop && npm install -g gtop 重装修复，然后核对修改处语法（Node.js 启动报错会打印出错的文件与行号，常见是把毫秒数字误删逗号、括号不配对）。

Q3：能把 CPU 曲线的 100% 上限改高吗？

技术上改 lib/gtop.js 中 CPU 图块的 maxY: 100 即可，但没有意义：CPU 使用率数据源（si.currentLoad 返回的 load 值）本身以 100 为满刻度，改高只会让曲线整体压扁。内存曲线同理（内存使用率也是百分比）。

Q4：环境变量在哪里持久化？

按标准 shell 惯例写入 ~/.bashrc（或 /etc/environment），例如：

echo 'export LANG=C.UTF-8 TERM=xterm-256color' >> ~/.bashrc
source ~/.bashrc

gtop 本身不读取任何自有配置文件，环境变量持久化完全遵循操作系统的通用做法。

八、参考链接

1. gtop 源码（v1.1.5 随 npm 包分发）：/usr/local/lib/node_modules/gtop/lib/（gtop.js、monitor/*.js、utils.js）
2. gtop 项目主页：https://github.com/aksakalli/gtop
3. 官方 README 排障节（LANG/TERM 建议）：https://github.com/aksakalli/gtop#troubleshooting
4. 本系列认知篇：《gtop 介绍与选型指南》
5. 本系列安装篇：《Ubuntu 24.04 安装 gtop 1.1.5 指南》
6. 本系列命令篇：《gtop 1.1.5 常用 CLI 命令与工具详解》