ctop 0.7.7 配置参数详解

目标：把 ctop 的全部可配置项一次讲清——它没有传统意义的守护进程配置文件，配置体系由「运行时配置文件 ~/.ctop（TOML）+ 启动参数（flag）+ 连接器环境变量 + 界面内开关」四部分组成，本文逐项给出实测取值、默认值与生效验证——已在 Ubuntu 22.04（x86_64，Docker Engine 29.8.1，ctop 0.7.7 build 11a1cb1）实测通过。

一、环境信息

操作系统：Ubuntu 22.04（x86_64），内核 6.8.0-138-generic
容器运行时：Docker Engine 29.8.1（API 1.56）
ctop：0.7.7（官方发布二进制，build 11a1cb1）
配置文件实测落点：/root/.ctop（无 XDG 环境）与 /root/xdgtest/ctop/config（设 XDG_CONFIG_HOME 时）
源码依据：bcicen/ctop master 分支 keys.go、config/file.go 与 v0.7.7 tag main.go（查询日期 2026-10-23）

二、前置条件

已按《Ubuntu 22.04 安装 ctop 0.7.7 指南》装好 ctop 并能 ctop -v 打印版本；
执行用户对配置目录有写权限（保存配置用）：root 默认写 /root/.ctop，普通用户写自己的家目录；
本文所有"界面内操作"均在 SSH 终端 TTY 中实测。

三、参数查看与修改方式

ctop 的参数分四个入口，优先级从高到低为：启动参数 > 配置文件 > 程序默认值（环境变量决定连接目标，与前三者正交）。优先级结论来自源码 v0.7.7 main.go 的启动顺序——先 config.Read() 读配置文件，再解析命令行 flag 覆盖同名项——并经下文实测印证。

入口	覆盖对象	生效时机
界面内按键（`f`/`s`/`r`/`a`/`H`/`c`/`S` 等）	过滤、排序、列开关、顶栏	立即，`S` 键持久化
配置文件 `~/.ctop`（TOML）	列组合、过滤串、排序字段、4 个开关	启动时读取
启动参数（`-a/-f/-r/-s/-i` 等）	与配置文件同名项	启动时覆盖
环境变量（`DOCKER_HOST`、`RUNC_ROOT`、`RUNC_SYSTEMD_CGROUP`）	连接器目标与路径	启动时读取

查看当前全部启动参数与默认值的最直接方式（实测全量回显）：

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

四、参数总览

4.1 配置文件键（~/.ctop，TOML 格式，共 7 键）

节	键	类型	默认值	作用
[options]	columns	字符串	`status,name,id,cpu,mem,net,io,pids,uptime`	网格列组合（逗号分隔列名）
[options]	filterStr	字符串	`""`（空）	启动时的初始过滤串
[options]	sortField	字符串	`state`	排序字段
[toggles]	allContainers	bool	`true`	是否显示非运行态容器
[toggles]	enableHeader	bool	`true`	是否显示顶部状态栏
[toggles]	fullRowCursor	bool	`true`	光标整行高亮
[toggles]	sortReversed	bool	`false`	是否反向排序

（默认值取自全新环境首次 S 保存生成的文件，见 5.1；fullRowCursor 无对应按键，仅存在于配置文件。）

4.2 启动参数（flag，共 8 个）

参数	默认值	作用
`-a`	关	只显示运行中容器（等价把 allContainers 切为 false）
`-connector <名>`	`docker`	选择连接器（可选 docker / runc）
`-f <串>`	空	设置初始过滤串（覆盖配置文件 filterStr）
`-h`	—	打印帮助并退出（退出码 0）
`-i`	关	反转默认配色（亮/暗色主题互换）
`-r`	关	反向排序（覆盖配置文件 sortReversed）
`-s <字段>`	配置文件 sortField	指定初始排序字段（cpu/id/io/mem/mem %/name/net/pids/state/uptime）
`-v`	—	打印版本并退出（退出码 0）

4.3 连接器环境变量（共 3 个）

变量	默认值	作用
`DOCKER_HOST`	`unix://var/run/docker.sock`	Docker 连接目标（官方 connectors 文档；标准 Docker 环境变量）
`RUNC_ROOT`	`/run/runc`	runC 连接器的容器状态根目录（官方 connectors 文档）
`RUNC_SYSTEMD_CGROUP`	未设	置位后 runC 连接器启用 systemd cgroups（官方 connectors 文档）

五、核心参数详解

5.1 配置文件 ~/.ctop：路径判定、生成与逐键说明

路径判定规则（源码 config/file.go 的 getConfigPath()/xdgSupport()，实测印证）：环境中存在任意以 XDG_ 开头的环境变量时走 XDG 路径——设了 XDG_CONFIG_HOME 用它，否则用 $HOME/.config，文件名为 <路径>/ctop/config；完全没有 XDG_* 变量的纯服务器 Shell 则落在 $HOME/.ctop。实测两种环境各保存一次：

无 XDG 环境（S 键保存提示）： wrote config to /root/.ctop
XDG_CONFIG_HOME=/root/xdgtest（S 键保存提示）： wrote config to /root/xdgtest/ctop/config

生成方式：ctop 不随安装自带配置文件，首次在界面按 S（大写）即把当前状态写入。实测在过滤、排序、列开关调整后保存，文件内容（逐字节实测）：

[options]
  columns = "status,name,cpu,mem,net,io,pids,uptime"
  filterStr = "ctop"
  sortField = "name"

[toggles]
  allContainers = true
  enableHeader = true
  fullRowCursor = true
  sortReversed = false

逐键说明：

columns：逗号分隔的列名序列，实测可用列名即界面 c 面板的 14 项（见 5.4）；上例为手工关闭 Container ID 列后的保存结果（对照默认值少了 id）；
filterStr：启动即生效的子串过滤条件，匹配容器名/镜像等字段，实测设为 ctop 后标题栏自动带出；
sortField：十个可选值 cpu / id / io / mem / mem % / name / net / pids / state / uptime（实测排序菜单全量选项）；全新环境的默认排序是 state；
allContainers：true 显示全部（含已停止），false 仅运行态；与界面 a 键、启动参数 -a 对应；
enableHeader：控制顶部"程序名 + 时间 + 计数 + 过滤串"状态栏显隐，对应界面 H 键；
fullRowCursor：光标高亮整行（配置文件专有，无快捷键）；
sortReversed：排序方向反向，对应界面 r 键与 -r 参数。

加载验证（实测）：保存上述文件后重启 ctop（不带任何参数），标题栏直接显示过滤串、网格不再有 CID 列、行序按 name 排列——配置加载生效：

  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

也可以手工编辑该文件（TOML 语法）再启动，效果与 S 保存相同。

5.2 启动参数：覆盖关系与实测

flag 在配置文件之后解析，同名项一律以 flag 为准。实测：配置文件中 filterStr = "ctop" 仍在，执行 ctop -f web，标题栏显示 filter: web 且只剩 1 个匹配容器——flag 覆盖了配置文件：

  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

各参数语义与 ctop -h 一致（见第三章回显）；-a（仅活动容器）、-s（初始排序字段）、-r（反向排序）、-i（反转配色）、-connector（连接器选择）。其中 -s 的合法值与排序菜单一致，传非法值会被启动校验拦截。

5.3 连接器环境变量：连接目标与排障

Docker 连接器完全复用标准 Docker 环境变量约定，默认连本机套接字。实测把 DOCKER_HOST 指向一个不存在的 TCP 端口，ctop 不退出而是弹错误框并持续重连：

  ┌ ctop - error ──────────────────────────────────────────────────┐
  │  [05:17:43 UTC] cannot connect to Docker endpoint              │
  │  [05:17:43 UTC] attempting to reconnect...                     │

切换到 runC 连接器（-connector runc）时依赖 RUNC_ROOT（默认 /run/runc）可访问；实测无该目录的机器直接报：

  ┌ ctop - error ──────────────────────────────────────────────────┐
  │  [05:17:55 UTC] open /run/runc: no such file or directory      │
  │  [05:17:55 UTC] attempting to reconnect...                     │

RUNC_SYSTEMD_CGROUP 按官方文档置位后启用 systemd cgroups 风格的 cgroup 路径解析（该行为依赖系统使用 systemd 管理 cgroup，本文未在纯 Docker 环境展开实测，取值以官方文档为准）。

5.4 界面内运行时开关与 S 键持久化

以下开关在界面上按键即时生效，其中多数可通过 S 键写入配置文件长期保留：

列开关（c 键）：打开 Columns 面板，实测面板全量条目为 14 项——Status Indicator、Container Name、Container ID、Image name、Exposed ports、Exposed IPs、Date created、CPU Usage、CPU Usage (% of system total)、Memory Usage、Network RX/TX、Disk IO Read/Write、Container PID Count、Running uptime duration；Up/Down（或 k/j）移动、空格勾选/取消（实测：取消 Container ID 后网格立即少一列，columns 键值随之变化）、Page Up/Page Down 调整列顺序（面板内提示原文 Re-order: <Page Up> / <Page Down>）、q 关闭面板。
排序（s 键）：弹出 Sort Field 菜单（十个字段，见 5.1），上下选择后回车确认。
过滤（f 键）：底部弹出 Filter 输入框，输入即实时过滤，标题栏同步显示 filter: <串>。
顶栏开关（H 键）：实测关闭后再 S 保存，配置文件 enableHeader 变为 false。
反向排序（r 键）：实测切换后 S 保存，sortReversed 变为 true。
全容器切换（a 键）：实测在 22 个运行容器 + 1 个已停止容器的环境切换，标题计数 22 ↔ 23，对应 allContainers。

⚠️ 注意：S 保存的是"当前全部状态"，包括临时过滤串。若不希望下次启动带着过滤条件，先按 f 清空过滤再按 S。

六、生产配置模板

ctop 本身无常驻服务与资源开销调优空间，配置模板的目标是"打开即是顺手的工作台"。以下模板适用于单机排障场景（root 运行、容器数量几十以内、希望默认只看运行态并按 CPU 排序），保存为 /root/.ctop 即可：

[options]
  # 列组合：状态、名字、镜像、CPU、内存、网络、IO、进程数、运行时长
  columns = "status,name,image,cpu,mem,net,io,pids,uptime"
  # 启动不预置过滤（现场按 f 临时过滤）
  filterStr = ""
  # 默认按 CPU 降序观察热点容器
  sortField = "cpu"

[toggles]
  # 只看运行中的容器，避免已停止容器干扰排序
  allContainers = false
  # 保留顶部状态栏（时间/计数/过滤提示）
  enableHeader = true
  # 光标整行高亮，宽终端下更易定位
  fullRowCursor = true
  # CPU 热点在最上（降序）
  sortReversed = false

模板要点：sortField = "cpu" 搭配 sortReversed = false（实测 cpu 排序本身即高值在前）把最忙容器置顶；allContainers = false 排除停止容器；image 列在排查"同镜像多实例"问题时建议保留。改完无需重启生效机制——该文件在下次启动 ctop 时读取。

七、常见问题（FAQ）

Q1：改了 ~/.ctop 却不生效？

先确认路径找对了：在带桌面环境（存在 XDG_* 变量）的会话里，配置文件不在 ~/.ctop 而在 ~/.config/ctop/config（或 $XDG_CONFIG_HOME/ctop/config）。判定方法（实测）：在当前 Shell 执行 env | grep -c '^XDG_'，输出 0 才会读写 ~/.ctop。其次确认文件是合法 TOML——见 Q2。

Q2：配置文件写坏了会怎样？

实测把 columns 行删掉半个引号后启动：ctop 正常进入界面，全部参数回到默认值（全量容器、默认列组合、state 排序），不会报错也不会崩溃——读取失败被静默忽略。排查方法：把文件改回合法 TOML（可先用 S 键生成一份正确样例对照），逐键核对 4.1 的键名拼写。

Q3：为什么命令行参数"压不住"配置文件？

正常情况下 flag 一定覆盖配置文件（实测 5.2）。若发现没覆盖，多半是参数写错被忽略（如 0.7.7 不存在的 -H，实测报 flag provided but not defined: -H，退出码 2）；用 ctop -h 核对参数表即可。

Q4：S 保存后某列不见了，怎么恢复？

columns 保存的是当时勾选结果。两种恢复方式：① 界面按 c 在 Columns 面板重新空格勾选目标列，再 S 保存；② 直接编辑配置文件把 columns 改回默认 status,name,id,cpu,mem,net,io,pids,uptime，重启生效（实测同一路径加载机制）。

Q5：配置文件能改刷新间隔吗？

不能。0.7.7 的配置键就是 4.1 表中的 7 个，没有刷新周期参数（界面约每秒刷新一次，代码内置）。需要更长周期采样请用 docker stats 等命令行工具落盘。

八、参考链接

官方 README 的 Config file 一节：https://github.com/bcicen/ctop#config-file
连接器与环境变量官方文档：https://github.com/bcicen/ctop/blob/master/_docs/connectors.md
v0.7.7 源码（config/file.go、main.go）：https://github.com/bcicen/ctop/tree/v0.7.7
站内相关：《ctop 介绍与选型指南》、《Ubuntu 22.04 安装 ctop 0.7.7 指南》、《ctop 0.7.7 常用 CLI 命令与工具详解》