Ubuntu 24.04 安装 gtop 1.1.5 指南

在 Ubuntu 24.04 服务器上从零安装 Node.js 终端监控仪表盘 gtop 并跑通首次启动验证，覆盖官方推荐的 npm 在线安装、离线 tgz 安装、GitHub 源码安装三种方案，以及升级/卸载/多版本管理与 5 类实测常见问题。全部命令与回显均在 Ubuntu 24.04.5 LTS（x86_64）环境实测通过。

gtop系统监控LinuxNode.js命令行2026/10/23

Ubuntu 24.04 安装 gtop 1.1.5 指南

目标：在 Ubuntu 24.04 服务器上从零安装 Node.js 终端监控仪表盘 gtop 并跑通首次启动验证，覆盖官方推荐的 npm 在线安装、离线 tgz 安装、GitHub 源码安装三种方案，以及升级/卸载/多版本管理与 5 类实测常见问题。全部命令与回显均在 Ubuntu 24.04.5 LTS（x86_64）环境实测通过。

一、环境信息

  • 操作系统：Ubuntu 24.04.5 LTS（/etc/os-release 首两行实测 PRETTY_NAME="Ubuntu 24.04.5 LTS"）
  • 架构：x86_64（uname -m 实测）
  • 服务器规格：12 核 CPU、32 GB 内存（free -m 实测 Mem: 32050）
  • Node.js：v22.23.4（官方 Linux x64 二进制包安装）
  • npm：10.9.9（随 Node.js 二进制包内置）
  • gtop：1.1.5（npm 最新稳定版，2026-10-23 实查）
  • 终端环境：TERM=xterm-256color、LANG=C.UTF-8（gtop 渲染依赖，见「三、版本选型说明」）

二、前置条件

2.1 系统要求

gtop 官方 README（2026-10-23 实查）声明的运行环境为：

  • Linux / macOS / Windows（Windows 仅部分支持，CPU 与进程两个监控模块在 Windows 下不工作）；
  • Node.js >= v8。

gtop 本体不依赖 ncurses 等系统库——它完全由 Node.js 实现（Braille 字符画布），系统层面只需要一个能正确显示 UTF-8 的终端（tty/ssh 会话）。

2.2 安装 Node.js 运行时（>= v8，实测 22.x）

若服务器还没有 Node.js，推荐用 Node.js 官方二进制包安装（不依赖发行版仓库的旧版本，解压即用）。以下为 Ubuntu 24.04 上的完整实测步骤：

# 1. 安装下载与解压工具
apt-get update && apt-get install -y curl xz-utils ca-certificates

实测回显（节选尾部）：

Reading package lists...
done.

# 2. 下载 Node.js 22 LTS 官方 Linux x64 二进制包（版本可按需替换，写文档时以 nodejs.org/dist 实际列表为准）
cd /opt
curl -fsSLO https://nodejs.org/dist/v22.23.4/node-v22.23.4-linux-x64.tar.xz

# 3. 校验与确认（官方 dist 页面公布 sha256，本文实测值如下）
ls -la node-v22.23.4-linux-x64.tar.xz
sha256sum node-v22.23.4-linux-x64.tar.xz

实测回显：

-rw-r--r-- 1 root root 31029996 Oct 23 02:40 node-v22.23.4-linux-x64.tar.xz
1805bcd35e6815559bd2eb97db438d3fdb0eb3a5e6a977b7c1badca76337e9ce  node-v22.23.4-linux-x64.tar.xz

# 4. 解压到 /usr/local（--strip-components=1 去掉包内顶层目录，使 bin/lib 直接并入 /usr/local）
tar -xJf node-v22.23.4-linux-x64.tar.xz -C /usr/local --strip-components=1

# 5. 验证
node -v
npm -v
which node npm

实测回显：

v22.23.4
10.9.9
/usr/local/bin/node
/usr/local/bin/npm

💡 说明：也可以用发行版仓库或 NodeSource 仓库安装 Node.js，只要 node -v 输出 >= 8 即可满足 gtop 要求；本文选择官方二进制包是因为它不引入额外软件源、路径统一在 /usr/local 下、升级卸载都只是文件操作。实测中还验证了 Node v14.21.3 与 v24.22.1 均可正常安装并运行 gtop（见「三、版本选型说明」的兼容矩阵）。

2.3 终端环境要求

gtop 是全屏 TUI 程序，启动与渲染依赖：

  1. 一个真实终端：必须在有 tty 的交互会话（本机终端、SSH、tmux/screen 会话）中运行。标准输出被重定向（管道、</dev/null、非交互执行）时会直接报错退出（Error: Width must be multiple of 2!，排障见「十二、常见问题」）。
  2. UTF-8 locale：界面图形由 Braille 盲文字符与 ACS 线条字符拼出，建议 LANG/LC_ALL 为 *.UTF-8（如 C.UTF-8、en_US.UTF-8），否则曲线区域可能显示为问号或错位字符。
  3. 终端类型：TERM=xterm-256color（官方 README 推荐值）。

三、版本选型说明

npm view gtop version

实测回显（Ubuntu 24.04 服务器上执行）：

1.1.5
  • gtop 目前唯一可安装的最新稳定版即 1.1.5（npm 发布时间 2023-08-11，GitHub Releases 最新 tag 同为 v1.1.5；2026-10-23 实查，项目维护状态详见 《gtop 介绍与选型指南》第二节）。因此不存在"选旧版规避 bug"的空间，选型重点是选对 Node.js 运行时版本。
  • Node.js 兼容矩阵（本文实测）：
Node.js 版本npm 版本安装TUI 渲染q 退出结论
v14.21.36.14.18成功（61 包）正常正常（退出码 0）可用
v22.23.410.9.9成功（61 包）正常正常（退出码 0）可用（本文采用，LTS）
v24.22.111.19.1成功正常—可用（当前主线）

矩阵解读：三档 Node 版本实测均正常，说明"老项目跑不动新 Node"的顾虑在 gtop 1.1.5 上不成立（其依赖 systeminformation 已是 v5 系列）；选 Node 22 LTS 兼顾稳定与长期支持即可。

  • 依赖规模：npm install -g gtop 实际安装 61 个包（含传递依赖），磁盘占用很小（gtop 自身 tar 包仅 5.4 KB，大头是 blessed/blessed-contrib/systeminformation 及其依赖）。

四、方案 A：npm 在线安装（官方推荐）

这是官方 README 给出的标准安装方式，一条命令完成。

npm install gtop -g

实测全量回显（Ubuntu 24.04，npm 10.9.9）：

npm warn deprecated charm@0.1.2: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

added 61 packages in 12s

3 packages are looking for funding
  run `npm fund` for details
npm notice
npm notice New major version of npm available! 10.9.9 -> 12.2.1
npm notice Changelog: https://github.com/npm/cli/releases/tag/v12.2.1
npm notice To update run: npm install -g npm@12.2.1
npm notice

回显解读：

  • npm warn deprecated charm@0.1.2：gtop 的传递依赖中有一个已被 npm 标记"不再维护"的过时小包（charm，终端字符处理库），这是上游依赖树的历史遗留，不是安装失败，实测不影响 gtop 功能，可忽略。
  • added 61 packages in 12s：安装成功，61 个包 12 秒装完。
  • 3 packages are looking for funding：3 个依赖请求赞助的提示，无功能影响。

安装结果验证：

which gtop
readlink -f $(which gtop)
npm ls -g gtop

实测回显：

/usr/local/bin/gtop
/usr/local/lib/node_modules/gtop/bin/gtop
/usr/local/lib
`-- gtop@1.1.5

即：npm 在 /usr/local/bin/gtop 放置入口脚本，实体在 /usr/local/lib/node_modules/gtop/bin/gtop（内容为三行 Node 启动脚本，require('../lib/gtop').init()）。

五、方案 B：离线安装（npm tgz 包）

适合"外网机下载、内网机安装"的场景。分两步：在可联网机器上把 gtop 包打成一个 tgz 文件，再拷贝到目标服务器安装。

# 1. 在可联网机器上下载 gtop 1.1.5 的 npm 包（tgz）
mkdir -p /opt/pkg && cd /opt/pkg
npm pack gtop@1.1.5
ls -la gtop-1.1.5.tgz
sha256sum gtop-1.1.5.tgz

实测回显：

gtop-1.1.5.tgz
-rw-r--r-- 1 root root 5528 Oct 23 02:27 gtop-1.1.5.tgz
a8e90b828e33160c6a0ac4fb11231f292496e8049c0dac814e46fdd0c90817c1  gtop-1.1.5.tgz

# 2. 将 gtop-1.1.5.tgz 拷贝到目标服务器（如 scp）后，从本地文件安装
npm install -g /opt/pkg/gtop-1.1.5.tgz

实测回显（在另一台只装有 Node 14 的服务器上执行）：

+ gtop@1.1.5
added 61 packages from 79 contributors in 11.907s

# 3. 验证
which gtop

实测回显：

/usr/local/bin/gtop

⚠️ 注意：tgz 里只含 gtop 自身的代码，安装时 npm 仍会到 registry.npmjs.org（或已配置的镜像源）下载那 61 个依赖包——本方案解决的是"gtop 包本身走离线渠道"，并不等于全离线。目标服务器完全断网时，需要先部署内网 npm 镜像仓（如 verdaccio）把依赖同步进内网，再把 npm registry 指向内网源后安装。

六、方案 C：源码仓库安装（GitHub）

适合需要跟进 master 分支改动、或打算修改源码做定制（布局/刷新间隔等，见《gtop 1.1.5 配置参数详解》的源码定制节）的用户。

npm install -g git+https://github.com/aksakalli/gtop.git

实测回显（节选尾部）：

added 61 packages in 31s

3 packages are looking for funding
  run `npm fund` for details

# 验证安装的版本
grep -m1 '"version"' /usr/local/lib/node_modules/gtop/package.json

实测回显：

  "version": "1.1.5",

即 master 分支当前就是 1.1.5 的代码，与 npm 版一致。此方式要求目标服务器能访问 github.com，且本机有 git 可用（npm 会调用 git 拉取仓库）。

七、方案对比与选择建议

方案命令入口需访问外网适用场景实测结果
A. npm 在线（官方推荐）npm install gtop -gnpm registry可联网服务器，最简单61 包 / 12s
B. tgz 离线包npm install -g ./gtop-1.1.5.tgz仅装 gtop 本体时不需要；依赖仍需 registry 或内网镜像有包审计/内网分发流程的环境61 包 / 11.9s
C. GitHub 源码npm install -g git+https://github.com/aksakalli/gtop.gitgithub.com + registry要改源码定制或跟 master61 包 / 31s

选择建议：普通服务器直接用方案 A；有离线分发要求用方案 B（记得依赖也要有内网来源）；要动源码用方案 C。

八、Snap 渠道现状说明（实测已失效）

gtop 官方 README 挂有 Snap 徽章，但 2026-10-23 通过 Snap Store API（api.snapcraft.io，携带 Snap-Device-Series: 16 与 X-Ubuntu-Series: 16 头）查询 gtop 时返回：

{"error_list":[{"code":"resource-not-found","message":"Snap 'gtop' (NnX5vI2liFjr5pirfLo0KHLoEXkjFiNa) has no published revisions in the given context."}],"errors":[...],"result":"error"}

即该 snap 名称已注册但没有任何已发布的版本通道，snap install gtop 当前不可用。请勿把 Snap 写入部署方案；本文不提供 Snap 安装路径。

九、首次启动与运行验证

安装完成后，在终端会话中直接执行：

gtop

gtop 立即进入全屏仪表盘：上方整幅 CPU History 折线图（逐核曲线，右侧图例逐核显示实时百分比），中部为 Memory and Swap History 曲线与 Memory/Swap 两个环形图，下部为 Network History 迷你图与 Processes 进程表（默认按 %CPU 降序）、左下 Disk usage 环形图。

本文验证方式：在 tmux 会话中启动 gtop 并抓取屏幕内容。完整步骤：

apt-get install -y tmux          # 若未安装 tmux
tmux new-session -d -s gtop -x 120 -y 40
tmux send-keys -t gtop 'gtop' Enter
sleep 6
tmux capture-pane -t gtop -p | sed -n '1p;13,14p;23,24p;34,35p'

实测回显（120×40 屏幕，输出节选；边框线条字符在字符终端中显示为连续线条，抓取为文本时以 lqqqk 类 ACS 字符呈现）：

lqCPU Historyqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqk
lqMemory and Swap HistoryqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqklqMemoryqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqk
x     ⠓⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒    xx               ⣿⣧100%⣿⡇               x
lqDisk usageqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqkx 2682   sleep 6                  0.0   0.0                x
x                         ⣾⡿⠉ ⠈⠹⣿⡆                         xx 2752   sh                       0.0   0.0                x

五大图块（CPU History / Memory / Disk usage / Processes / Network History）均正常渲染，即安装验证通过。进程表里的 sleep 6、sh 等正是当前会话的真实进程。

按 q 退出（实测退出码 0，终端画面恢复正常缓冲）：

tmux send-keys -t gtop q
sleep 1
tmux ls

实测回显：

no server running on /tmp/tmux-0/default

tmux 会话随 gtop 退出而关闭，证明 gtop 进程已正常结束。

十、升级、降级与多版本管理

gtop 走 npm 全局包管理，全部经 npm 完成（以下命令均在 Ubuntu 24.04 实测）：

# 查看最新版本号
npm view gtop version

实测回显：

1.1.5

# 查看当前已装版本
npm ls -g gtop

实测回显：

/usr/local/lib
`-- gtop@1.1.5

# 安装/降级到指定版本（gtop 未再发新版，此命令在后续若出新版时同样适用）
npm install -g gtop@1.1.5

实测回显（节选尾部）：

  run `npm fund` for details

说明：npm 对"已安装同版本"会重新安装一遍依赖树（约十几秒），执行完 npm ls -g gtop 确认版本号即可。gtop 没有并行多版本机制（单一全局入口 /usr/local/bin/gtop）；如确需多版本并存，可用 npm config set prefix 切换不同全局目录分别安装（见「十二、常见问题」12.2 的 prefix 用法）。

十一、卸载与清理

# 卸载 gtop
npm uninstall -g gtop

实测回显：

removed 61 packages in 178ms

# 验证卸载干净
which gtop || echo "gtop 已不在 PATH"
npm ls -g gtop

实测回显：

gtop 已不在 PATH
/usr/local/lib
`-- (empty)

若要连同 Node.js 运行时一起清理（仅限本文的官方二进制包方式），删除解压出来的文件即可：

rm -rf /usr/local/bin/node /usr/local/bin/npm /usr/local/bin/npx /usr/local/lib/node_modules
rm -f /opt/node-v22.23.4-linux-x64.tar.xz

十二、常见问题（FAQ）

Q1：运行 gtop 报 Error: Width must be multiple of 2! 然后退出？

这是 gtop 最高频的报错，实测定位如下：gtop 的画布（drawille 字符画布）按"终端宽度的 2 倍"建画布，当它拿不到终端宽度（标准输出不是 tty，或伪终端尺寸为 0×0）时宽度值为 NaN，直接抛出该错误并退出（实测退出码 1）。触发场景包括：把 gtop 放进管道/重定向执行（如 gtop > log）、在无终端尺寸的执行环境里调用（CI 脚本、nohup 等）。实测复现：

gtop --version

实测回显（非交互执行，stdout 非 tty）：

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)
    ...

解决：在真实交互终端里直接运行 gtop（本命令不带任何参数也能启动，gtop 会忽略所有命令行参数，见《gtop 1.1.5 常用 CLI 命令与工具详解》）。在 tmux/screen 中运行同样有效，但必须先建立会话再进入，而不是把 gtop 挂到无尺寸的后台管道上。

Q2：非 root 用户执行 npm install -g gtop 报 EACCES？

实测现象（普通用户 dev 执行）：

npm error code EACCES
npm error syscall rename
npm error path /usr/local/lib/node_modules/gtop
npm error dest /usr/local/lib/node_modules/.gtop-8PWQsU19
npm error errno -13
npm error Error: EACCES: permission denied, rename '/usr/local/lib/node_modules/gtop' -> '/usr/local/lib/node_modules/.gtop-8PWQsU19'

原因：全局目录 /usr/local/lib/node_modules 归 root 所有，普通用户无写权限。解决（不改系统目录，把当前用户的全局前缀切到家目录）：

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
npm install -g gtop

实测回显（节选尾部）：

3 packages are looking for funding
  run `npm fund` for details

然后把 ~/.npm-global/bin 加入 PATH（写入 ~/.bashrc 后 source ~/.bashrc）：

export PATH=$HOME/.npm-global/bin:$PATH
which gtop

实测回显：

gtop

Q3：界面出现问号或乱码字符？

官方 README 给出的处理方式（2026-10-23 实查原文）：用 UTF-8 locale 与明确的终端类型启动：

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

实测对照：设 LANG=C.UTF-8、TERM=xterm-256color 时，Braille 曲线（⣿⣾⠉）与 ACS 边框均正常；不设 UTF-8 locale 时字符终端会退化为 ASCII 替代字符，图形区块观感变差。SSH 工具侧还需确认使用支持 UTF-8 与 256 色的终端模拟器。

Q4：npm install 时的 npm warn deprecated charm@0.1.2 是不是装坏了？

不是。charm 是 gtop 依赖树里一个年久失修的底层小包，npm 只是提示"该包不再受官方支持"。实测安装继续完成（added 61 packages），gtop 功能不受影响。由于上游 1.1.5 之后未再发版，这个警告会一直存在，忽略即可。

Q5：man gtop 为什么没有手册页？

gtop 的 npm 包内确实带有手册源文件（/usr/local/lib/node_modules/gtop/CLI.md 与预生成的 gtop.1），但 npm 全局安装不会把 man 文件安装进系统 manpath，实测 man gtop 无输出。要看官方命令文档，直接读包内文件：

cat /usr/local/lib/node_modules/gtop/CLI.md

（其内容与逐键实测解读见《gtop 1.1.5 常用 CLI 命令与工具详解》。）

十三、参考链接

  1. gtop 官方 README（安装/Usage/排障）：https://github.com/aksakalli/gtop
  2. Node.js 官方二进制包下载：https://nodejs.org/dist/
  3. gtop npm 仓库页：https://www.npmjs.com/package/gtop
  4. Snap Store 中 gtop 条目（当前无已发布版本）：https://snapcraft.io/gtop
  5. 本系列认知篇：《gtop 介绍与选型指南》
  6. 本系列配置篇：《gtop 1.1.5 配置参数详解》
  7. 本系列命令篇：《gtop 1.1.5 常用 CLI 命令与工具详解》