ctop 0.7.7 常用 CLI 命令与工具详解
ctop 0.7.7 命令与 TUI 交互详解：全部启动参数与退出码实测、主网格/过滤/排序/容器菜单/单容器视图/日志/exec/列配置逐键操作实录、DOCKER_HOST 远程连接与 docker stats 组合用法。
ctop 0.7.7 常用 CLI 命令与工具详解
目标：把 ctop 的单命令用法与 TUI 全部交互键位一次讲透——启动参数（含逐个实测回显）、主网格、过滤、排序、容器菜单、单容器视图、日志、exec、列配置、配置保存、远程主机连接与容器管理操作，全部条目在 Ubuntu 22.04（x86_64，Docker Engine 29.8.1）实测通过，回显逐行照抄。
一、环境信息
- 操作系统：Ubuntu 22.04（x86_64），内核 6.8.0-138-generic
- 容器运行时：Docker Engine 29.8.1（API 1.56）
- ctop：0.7.7（官方发布二进制，build 11a1cb1）
- 演示容器：nginx:alpine Web 服务（映射 8133→80）与一个 busybox CPU 负载循环
- 界面帧说明：本文所有界面帧为终端逐字符捕获的实测文本，彩色高亮与数值随时间自然波动，帧内数值仅代表捕获时刻
二、工具概览
ctop 只有一个可执行文件、没有子命令体系：ctop [options] 一条命令进入 TUI。它的"命令体系"由两部分组成：
- 启动参数（flag）：决定启动时的过滤、排序、连接器等初始状态，共 8 个（
ctop -h实测清单见 4.2）； - TUI 键位：进入界面后的全部操作靠键盘完成，主网格 13 键 + 容器菜单 7 项 + 单视图/日志视图若干键，完整键位表可随时在界面内按
h查看内置帮助。
与 Docker 自带的 docker stats 相比：docker stats 是一次性 CLI（适合脚本），ctop 是交互式 TUI（适合人盯屏排查）；两者读的是同一套 Docker stats 数据。需要把指标落盘时用 docker stats --no-stream（见第七章组合用法）。
三、前置条件
- ctop 已安装（安装路径与多方案见《Ubuntu 22.04 安装 ctop 0.7.7 指南》），
ctop -v可打印版本； - 执行用户可访问 Docker 套接字（root 或 docker 组成员，否则界面弹权限错误框，见"九、常见问题"Q1）；
- 在真实终端（SSH 会话）中运行——TUI 无法在管道/无 TTY 环境工作（实测 panic，见 Q4）；
- 机器上有容器在跑才有内容可看。
四、启动参数详解
4.1 -v：版本信息并退出
ctop -v
ctop version 0.7.7, build 11a1cb1 go1.18
退出码 0（echo $? 实测）。这是最常用的安装验证手段。
4.2 -h：帮助与参数全量清单
ctop -h
-a show active containers only
-connector string
container connector to use (default "docker")
-f string
filter containers
-h display this help dialog
-i invert default colors
-r reverse container sort order
-s string
select container sort field
-v output version information and exit
ctop - interactive container viewer
usage: ctop [options]
options:
available connectors: docker, runc
参数带取值的（-connector/-f/-s）在帮助里给出了真实默认值：连接器默认 docker，-f/-s 默认空（即从配置文件或程序默认值取）。退出码 0。
4.3 -a：仅显示运行中容器
默认情况下 ctop 把已停止的容器也列出来（行首 ⏹ 标记、指标为 -）；-a 启动则只列运行态。实测对照（同一台机器，1 个已停止容器）：
ctop -a # 标题栏：22 containers（仅运行中）
ctop - 05:20:52 UTC 22 containers
NAME CID CPU MEM NET RX/TX IO R/W PIDS UPTIME
⏵ alfio-2.0.2609-b1 b6d04888dbdd 0% 723M / 31G 384M / 2M 0B / 0B 79 8h9m28s
启动后按 a 键可随时切换（实测切回含停止容器后标题变 23 containers），效果等同 allContainers 开关。
4.4 -f：初始过滤串
启动即按子串过滤，标题栏同步显示。实测 -f web（配置文件中的 filterStr = "ctop" 被参数覆盖，优先级实测见《ctop 0.7.7 配置参数详解》5.2）：
ctop -f web
ctop - 05:31:06 UTC 1 containers filter: web
NAME CPU MEM NET RX/TX IO R/W PIDS UPTIME
⏵ ctop-0.7.7-web 0% 12M / 31G 251K / 663K 0B / 0B 15 19m25s
4.5 -s：初始排序字段
合法值与界面排序菜单一致：cpu / id / io / mem / mem % / name / net / pids / state / uptime。实测 -s mem（按内存用量降序，三台容器按 156M→12M→3M 排列）：
ctop -s mem
ctop - 05:21:38 UTC 3 containers filter: ctop
NAME CPU MEM NET RX/TX IO R/W PIDS UPTIME
⏵ ctop-0.7.7-server 0% 156M / 31G 68M / 1M 0B / 0B 40 15m6s
⏵ ctop-0.7.7-web 0% 12M / 31G 250K / 663K 0B / 0B 15 9m54s
⏵ ctop-0.7.7-load 96% 3M / 31G 8K / 126B 0B / 0B 1 15m6s
传非法值在启动校验阶段直接报错退出（实测，退出码 1，界面不会打开）：
ctop -s bogus
invalid sort field: bogus
4.6 -r：反向排序
与 -s 搭配改变排序方向（如 -s name -r 名字倒序）。实测 -r 生效后按 S 保存，配置文件 sortReversed 由 false 变 true，证明参数与配置开关同源：
sortReversed = true
4.7 -i：反转默认配色
把亮/暗配色主题互换，适配深色或浅色终端背景。该参数改变的是颜色映射，文本捕获无法呈现，验证方式为在真实终端肉眼确认（启动不报错即生效）。
4.8 -connector：选择容器连接器
默认 docker；可选值在 ctop -h 尾行标注：available connectors: docker, runc。监控 Docker 容器无需改动；选择 runc 时依赖本机 /run/runc 状态目录，实测无该目录时界面弹错误框循环重连：
┌ ctop - error ──────────────────────────────────────────────────┐
│ [05:17:55 UTC] open /run/runc: no such file or directory │
│ [05:17:55 UTC] attempting to reconnect... │
4.9 不存在的参数与退出码约定
0.7.7 没有 -H 参数（网上旧教程常误写）。实测：
ctop -H tcp://127.0.0.1:2375
flag provided but not defined: -H
Usage of ctop:
-a show active containers only
-connector string
container connector to use (default "docker")
-f string
filter containers
-h display this help dialog
-i invert default colors
-r reverse container sort order
-s string
select container sort field
-v output version information and exit
退出码 2。退出码约定实测汇总：-v/-h 正常退出 0；参数非法 1（如 -s bogus）或不被识别 2（如 -H）；无 TTY panic 退出 2。
五、TUI 交互键位详解
以下每一条均在实测环境中按键操作并逐字符捕获界面帧。键位总表可随时按 h 查看（5.9 有全帧）。
5.1 主网格：列含义与状态符
默认视图（列组合可按 c 定制）：
ctop - 05:20:36 UTC 3 containers filter: ctop
NAME CPU MEM NET RX/TX IO R/W PIDS UPTIME
⏵ ctop-0.7.7-load 0% 3M / 31G 8K / 126B 0B / 0B 1 14m7s
⏵ ctop-0.7.7-server 0% 156M / 31G 68M / 1M 0B / 0B 28 14m7s
⏵ ctop-0.7.7-web 0% 12M / 31G 250K / 663K 0B / 0B 15 9m54s
- 标题栏：程序名、UTC 时间、容器计数、当前过滤串（
H键开关，见 5.10）； - 列：NAME（名称）、CID（短 ID）、CPU（百分比）、MEM（用量/上限）、NET RX/TX（累计收发）、IO R/W（累计读写）、PIDS（进程数）、UPTIME（运行时长）；
- 行首状态符：
⏵运行中（可展开）、⏹已停止（指标显示-）；实测还观察到☼前缀，用于标注 docker compose 项目容器； - 上下移动：方向键或 vim 风格
j/k（源码keys.go键位映射，实测j/k可用）。
5.2 f：过滤容器
按 f 弹出底部 Filter 输入框（预填当前过滤串），输入即实时过滤。实测输入 ctop 后的界面（标题栏与输入框同时可见）：
ctop - 05:08:54 UTC 3 containers filter: ctop
NAME CID CPU MEM NET RX/TX IO R/W PIDS UPTIME
⏵ ctop-0.7.7-load 8364c84613db 96% 3M / 31G 7K / 126B 0B / 0B 1 1m54s
⏵ ctop-0.7.7-server 0e95c4a419b1 0% 166M / 31G 67M / 857K 0B / 0B 19 1m54s
⏵ ctop-0.7.7-web 8969b085486b 0% 17M / 31G 8K / 126B 0B / 0B 13 1m55s
┌Filter────────────────────┐
│ ctop │
└──────────────────────────┘
清空与关闭（实测）：Esc 关闭输入框（过滤条件保留）；把框内文本逐字删空（退格）后回车即彻底清除过滤——实测清空后标题栏过滤提示消失、恢复全量列表。
5.3 s 与 r：排序字段与反向
按 s 弹出 Sort Field 菜单，实测全量选项（上下键移动、回车确认）：
┌Sort Field───┐
│ │
│ cpu │
│ id │
│ io │
│ mem │
│ mem % │
│ name │
│ net │
│ pids │
│ state │
│ uptime │
│ │
└─────────────┘
r 键随时反向当前排序；两者分别对应启动参数 -s/-r 与配置文件 sortField/sortReversed。
5.4 回车：容器操作菜单
在主网格选中某容器按回车，弹出操作菜单（实测全帧）：
┌Menu─────────────────┐3 containers filter: ctop
│ │
│ [o] single view │ CID CPU MEM NET RX/TX IO R/W PIDS UPTIME
│ [l] log view │
│ [s] stop │ 8364c84613db 96% 3M / 31G 8K / 126B 0B / 0B 1 3m14s
│ [p] pause │ 0e95c4a419b1 0% 163M / 31G 67M / 857K 0B / 0B 19 3m14s
│ [r] restart │ 8969b085486b 0% 17M / 31G 8K / 126B 0B / 0B 13 3m14s
│ [e] exec shell │
│ [c] cancel │
│ │
└─────────────────────┘
菜单项：单视图（o）、日志（l）、停止（s）、暂停（p）、重启（r）、进入 Shell（e）、取消（c）。s/p/r 是对容器的真实管理操作：实测选中负载容器按 s，弹出二次确认框（原文 stop container ctop-0.7.7-load?，选项 [c]ancel / [y]es），按 y 后容器被真实停止——宿主侧 docker ps -a 实测状态 Exited (137)。误操作防线就是这道确认框。
5.5 o：单容器视图
从容器菜单选 [o]（或主网格按 o）进入单容器滚动视图，一屏从上到下：信息框、CPU 曲线、MEM、NET、IO、Env。实测（Web 容器，NET 面板在持续请求时捕获到 TX 速率条）：
┌───────────────────────────────────────────────────────────────┐
│ id | 9803b639bb39 │
│ name | ctop-0.7.7-web │
│ image | nginx:alpine │
│ ports | 0.0.0.0:8133 -> 80/tcp │
│ | :::8133 -> 80/tcp │
│ IPs | ctop-077-net:10.89.58.2 │
│ state | running │
│ created | Fri Oct 23 05:11:39 2026 │
│ uptime | 8s │
│ health | │
└───────────────────────────────────────────────────────────────┘
指标面板结构（同一视图向下滚动实测）：CPU 滚动曲线（左轴刻度自适应）；MEM 当用量/上限；NET 两行速率 RX [0b/s]/TX [25.88kib/s]（附柱状条）；IO 两行 read/write [0b/s]；最底部 Env 面板逐行列出容器环境变量（实测 nginx 容器含 NGINX_VERSION | 1.31.8 等行）。单视图内再按 o 返回主网格。
5.6 l：容器日志视图
主网格选中容器按 l 打开实时滚动日志（标题注明容器名）。实测 Web 容器的 nginx 访问日志：
┌Logs [ctop-0.7.7-web]────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ 10.89.58.4 - - [23/Oct/2026:05:12:24 +0000] "GET / HTTP/1.1" 200 896 "-" "curl/7.81.0" "-" │
│ 10.89.58.4 - - [23/Oct/2026:05:12:24 +0000] "GET / HTTP/1.1" 200 896 "-" "curl/7.81.0" "-" │
视图内 t 键切换 Docker 时间戳前缀（实测切换后每行行首多出 2026-10-23T05:12:24.78Z 一类时间戳）；q 退回。
5.7 e：exec 进入容器 Shell
容器菜单选 [e] 直接在容器内开 Shell。实测在 Web 容器执行命令与退出：
/ # hostname && uname -r && id -u
9803b639bb39
6.8.0-138-generic
0
/ #
Shell 会话结束后退出 Shell 即回到 ctop 界面。该功能等价 docker exec，是"看现场"到"查现场"的关键一步。
5.8 c：列配置面板
主网格按 c 打开 Columns 面板，实测全量 14 项：
┌Columns─────────────────────────────────┐
│ │
│ Re-order: <Page Up> / <Page Down> │
│ │
│ Status Indicator [X] │
│ Container Name [X] │
│ Container ID [X] │
│ Image name [ ] │
│ Exposed ports [ ] │
│ Exposed IPs [ ] │
│ Date created [ ] │
│ CPU Usage [X] │
│ CPU Usage (% of system total) [ ] │
│ Memory Usage [X] │
│ Network RX/TX [X] │
│ Disk IO Read/Write [X] │
│ Container PID Count [X] │
│ Running uptime duration [X] │
│ │
└────────────────────────────────────────┘
[X] 为默认开启列；空格键切换勾选（实测取消 Container ID 后网格即时少一列）、Page Up/Page Down 调整列顺序（面板提示原文）、q 关闭。配合 S 保存后列组合写入配置文件 columns 键。
5.9 h：内置帮助（键位总表）
┌Help───────────────────────────────────────────────────────────────┐
│ │
│ <enter> - open container menu │
│ │
│ [a] - toggle display of all containers │
│ [f] - filter displayed containers │
│ [h] - open this help dialog │
│ [H] - toggle ctop header │
│ [s] - select container sort field │
│ [r] - reverse container sort order │
│ [o] - open single view │
│ [l] - view container logs ([t] to toggle timestamp when open) │
│ [e] - exec shell │
│ [w] - open browser (first port is http) │
│ [c] - configure columns │
│ [S] - save current configuration to file │
│ [q] - exit ctop │
│ │
└───────────────────────────────────────────────────────────────────┘
（实测全帧；其中 [w] open browser 为官方 README 键位表未收录的键，功能为用首个 HTTP 端口打开浏览器，仅在带桌面环境的终端可用。）
5.10 H 与 S：顶栏开关与配置保存
H键实测关闭顶部状态栏（标题栏整行消失，网格上移）；再按恢复。对应配置文件enableHeader。S键实测把当前过滤/排序/列组合/开关写入配置文件，底部提示wrote config to /root/.ctop（存在XDG_*环境变量时写入~/.config/ctop/config一类 XDG 路径，实测见《ctop 0.7.7 配置参数详解》5.1）；下次启动自动加载。
5.11 q：退出
主网格按 q 退出程序回到 Shell；弹窗/输入框打开时 q 优先关闭当前弹层（帮助框、列面板、确认框实测均可 q 关闭）。
六、远程主机与连接器实战
ctop 默认连本机 /var/run/docker.sock；通过标准 Docker 环境变量 DOCKER_HOST 可改连远程守护进程（SSH 隧道套接字、TCP 等，与 docker CLI 约定一致）。实测把 DOCKER_HOST 指向不可达的 TCP 端点，界面弹错误框并持续重连（进程不退出）：
DOCKER_HOST=tcp://127.0.0.1:2375 ctop
┌ ctop - error ──────────────────────────────────────────────────┐
│ [05:17:43 UTC] cannot connect to Docker endpoint │
│ [05:17:43 UTC] attempting to reconnect... │
⚠️ 注意：远程主机连接同样要求该账户对远程 docker 套接字有访问权限；TCP 方式（2375）为明文无认证，生产环境建议改用 SSH 隧道转发 Unix 套接字后再连。
连接器选择用 -connector（docker/runc，见 4.8）；runC 连接器另有 RUNC_ROOT、RUNC_SYSTEMD_CGROUP 两个环境变量（官方文档取值，默认 /run/runc）。
七、与 Docker 命令的组合使用
ctop 适合人看，脚本取数用 docker stats --no-stream。实测一条等价取数命令（取三台容器的 CPU/内存快照）：
docker stats --no-stream --format 'table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}' $(docker ps --filter name=ctop-0.7.7 -q)
NAME CPU % MEM USAGE / LIMIT
ctop-0.7.7-web 0.00% 11.2MiB / 31.3GiB
ctop-0.7.7-server 0.00% 111.9MiB / 31.3GiB
ctop-0.7.7-load 99.84% 3.367MiB / 31.3GiB
组合建议：TUI 里发现异常容器 → 复制容器名 → 终端里用 docker inspect <名> 查完整元数据、docker logs 拉全量日志；ctop 的日志/exec 视图覆盖不了的场景（导出、历史）都在 Docker CLI 侧补齐。
八、注意事项
- s/p/r 是真实管理操作：容器菜单的 stop/pause/restart 会真实作用于目标容器（实测 stop 后宿主侧状态
Exited (137)），生产环境操作前看清选中行。 - S 保存的副作用：会把临时过滤串一并写入配置，下次启动自动带上；不希望保存时先清空过滤（见 5.2）。
- TUI 依赖 TTY：管道、定时任务中运行会 panic（回显见 Q4）；无人值守取数用
docker stats。 - 退出码约定：
-v/-h返回 0；非法参数值 1、未知参数 2、无 TTY panic 2（均实测），可据此做安装探活。 - 普通用户权限：非 docker 组成员会持续弹
permission denied重连框（见 Q1），不会自动退出。
九、常见问题（FAQ）
Q1：启动后一直弹 connect: permission denied？
实测错误框：
│ [05:23:08 UTC] Get "http://unix.sock/info": dial unix /var/run/docker.sock: connect: permission denied │
│ [05:23:08 UTC] attempting to reconnect... │
当前用户不在 docker 组。解决：sudo usermod -aG docker <用户名> 后重新登录，或用 root 运行。
Q2：想连远程 Docker，-H 参数无效？
0.7.7 无 -H 参数（实测回显与退出码见 4.9）。正确做法：DOCKER_HOST=tcp://<主机>:2375 ctop 或 SSH 隧道 ssh -L /tmp/docker.sock:/var/run/docker.sock <主机> 后 DOCKER_HOST=unix:///tmp/docker.sock ctop。
Q3：-s 传了字段名却启动失败？
字段名必须在十个合法值内（cpu/id/io/mem/mem %/name/net/pids/state/uptime），实测非法值报 invalid sort field: bogus 且退出码 1。注意 mem % 含空格与百分号，Shell 里要加引号：ctop -s 'mem %'。
Q4：脚本里调用 ctop 报 panic？
实测回显：
panic: open /dev/tty: no such device or address [recovered]
panic: open /dev/tty: no such device or address
TUI 无法脱离终端运行；脚本取数改用 docker stats --no-stream（第七章实测命令）。
Q5：过滤串输错了怎么清？
按 f 打开输入框（预填当前串），退格清空后回车即恢复全量列表（实测标题栏过滤提示消失）；或直接改配置文件 filterStr = "" 后重启。