Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

简介

ltop(localist top)是一款只盯一台机器的终端监控器。btop、nethogs、iftop 各答对一部分的问题,它三个一起答:

  1. 流量去哪了? —— 谁在和谁通信、走哪块网卡、速率多少,每连接、每进程 的字节计费(TCP 和 UDP)都有。
  2. 进程在干什么? —— 谁正在吃带宽和磁盘,整场会话累计吃了多少;进程退出 了也留账。
  3. 局域网上有谁? —— 哪些设备在线、哪个是网关、到每台设备的流量是多少。

工作方式

六个盒子各司一职(NET、LAN、DISK I/O、DISKS、CONNS、PROCS),ratatui 渲染,btop 风格的盲文图表。主程序免特权运行——不要 root、不要 setuid、 没有守护进程。Linux 上有一个可选的特权助手(ltop-bpf,小型 eBPF 采集器), 补齐每进程/每连接的 TCP 与 UDP 字节计费;没有它其余功能照常。macOS 上同样 六个盒子读 Apple 原生源(nettop、libproc、IOKit、路由 socket)。所有显示面 背后是同一份数据面: ltop --json 输出 schema-v1 快照,ltop watch 无头录制, ltop report 聚合时间窗——这正是 ltop 能被 AI 代理直接使用的原因(比轮询 省 ~97% token,见 AI 代理)。

亮点

  • 真实的逐连接计费 —— 每条 TCP 连接都有实时 B/s 和累计总量;UDP 连接由 eBPF 计量,列与 TCP 相同。关闭的连接留 5 秒墓碑行,突发流量不会看丢。
  • 跨重启存活的进程总量 —— PROCS 按进程累计整场会话的网络(TCP+UDP)与 磁盘 I/O;退出的进程灰显保留,带捕获的完整命令行,一键重启。
  • 带流量的 LAN 邻居 —— 被动 ARP 加周期 UDP knock 扫描发现同子网设备 (IP、MAC、mDNS 主机名、接口);每个邻居带实时连接数、速率和累计字节, enter 置顶它并让 CONNS 只看这个对端。
  • 无头 watch + report —— 时间窗录成崩溃安全的 JSONL,再聚合出精确的窗口 总和、峰值速率和活跃时长(人读表格或 ~2 KB JSON)。
  • 72 套内嵌 btop 主题 —— 任何 btop 主题直接可用;Omarchy 下可跟随桌面 主题,--follow-theme 让运行中的 ltop 实时变色(默认关)。界面英文或中文 (lang = zh)。
  • 三布局一键切换 —— Tab 循环 classic / wide / tall;1–6 开关盒子; z 把焦点盒子放大全屏。

下一步

  • 快速上手 —— 安装加最要紧的键,两分钟。
  • 安装 —— 全渠道、平台要求、eBPF 助手部署。
  • TUI 界面 —— 全部界面: 盒子、布局、键位。
  • AI 代理 —— JSON 快照、watch + report、打包好的 agent skill。

现状

ltop 以 MIT 协议发布,日常开发环境是 Omarchy(Arch Linux),每个 release 在 QEMU/KVM 的五个发行版加 macOS 实机上验证——见兼容性。分发渠道: Homebrew、crates.io、GitHub Releases tarball(x86_64 + aarch64);AUR ltop-bin 打包就绪,等 AUR 开放注册。

快速上手

1. 安装(一条命令)

brew install uMaj35ty/ltop/ltop     # macOS 与 Linux —— 预编译二进制

或者有 Rust 工具链的话:

cargo install ltop                  # 源码编译(crates.io)

或者从 GitHub Releases 下 tarball(x86_64 / aarch64,Linux 与 macOS)。 全部渠道见安装。

2. 运行

ltop

不要 root,不要配置。落地即 classic 布局: 左边图表(上 NET 下 DISK I/O), 右边表格(LAN、CONNS、PROCS、DISKS)。

3. 最要紧的键

下面十个覆盖日常;页脚永远显示当前上下文,完整表在 m → help(也见 TUI 界面)。

按键作用
Tab布局循环: classic → wide → tall
1–6开关盒子(1 net、2 lan、3 disk i/o、4 disks、5 conns、6 procs)
/按名字子串搜索进程/连接
p / c / l单焦点 PROCS / CONNS / LAN(点亮一个,其余变暗)
↑↓ + enter选中行 → 详情面板(完整命令行、逐连接分解、运行时长)
LAN 行上 enter置顶该邻居并让 CONNS 只看它——“这台设备到底在干什么”
f / oCONNS: 过滤循环(all/lan/tcp/udp)/ 排序循环(proc 分组、sum、name、rate)
rPROCS: 排序循环(net-sum、net-rate、disk-sum、disk-rate、name)
z焦点盒子全屏缩放(esc 退出)
m菜单: 主题、设置、图表、帮助
space暂停/恢复采样(暂停期间漏掉的字节恢复时补齐)
q退出

4. 可选: 每进程/每连接字节计费(Linux)

没有这一步 ltop 也能用——CONNS 有 TCP 实时速率,PROCS 有来自 socket 抽样的 网络总量;缺的是精确的 UDP 每进程计费和每连接总量。一条命令开启:

sudo cp target/release/ltop-bpf /usr/local/bin/      # 从 release tarball 或源码构建
sudo cp deploy/ltop-bpf.service /etc/systemd/system/
sudo systemctl enable --now ltop-bpf

Homebrew 装的二进制相同;助手要与 TUI 出自同一个 release(见 eBPF 计费和升级注意事项)。

5. 可选: AI 工作流

记住这一对命令:

ltop watch --duration 10m --proc chrome   # 无头录制(免 root,崩溃安全),
                                         # 结束时打印输出路径
ltop report <该路径> --json               # report 只收单个文件

report 给出精确的窗口总和与峰值,不是抽样猜测——10 分钟窗口 JSON 约 1k token,轮询 --json 要 4 万。见 AI 代理。

6. 调成自己喜欢的样子

  • 主题: m → theme 循环 72 套内嵌 btop 主题;Omarchy 下选 omarchy 跟随桌面。--theme <file> 加载任意 btop 主题文件;--follow-theme 让运行中的 ltop 跟着桌面变色。详见主题。
  • 语言: ~/.config/ltop/config.conf 里 lang = zh,所有人类可读输出 (TUI 和 CLI)切中文;JSON 键恒为英文。
  • 设置面板: m → settings 写入 ~/.config/ltop/config.conf(刷新率、 日志保留、扫描间隔、排序默认……)。见数据面。

安装

ltop 是两个二进制:

  • ltop —— TUI 和全部 CLI(--json、watch、report……)。免特权运行。
  • ltop-bpf —— 可选的特权 eBPF 采集器(仅 Linux)。没有它 ltop 照样有用, 见 eBPF 计费。

平台: Linux 与 macOS,x86_64 和 aarch64。预编译 Linux 二进制要求 glibc 2.35+(Ubuntu 22.04 LTS 基线);不提供静态 musl 包。

Homebrew(macOS 与 Linux)

项目 tap 的预编译二进制:

brew install uMaj35ty/ltop/ltop

升级走同一条 formula(brew upgrade ltop)。formula 已不带退役的 loli 软链;brew upgrade 会自动清掉旧的。

crates.io

cargo install ltop

stable Rust 工具链源码编译;两个二进制都装进 ~/.cargo/bin。注意:

  • 不需要 clang。 eBPF 对象通常在编译期用系统 clang 构建——但 clang(或 bpf target)不可用时构建照样成功,嵌入空对象: TUI 正常运行,只有 UDP 每进程计费静默缺席。该情况下 ltop-bpf 启动时会明确报错拒启。
  • 从源码构建 eBPF 采集器需要带 bpf target 的 clang(Arch 默认 clang 就有)。

GitHub Releases

每个 release 提供 x86_64 和 aarch64、Linux 与 macOS 的 tarball,内含 两个二进制和 systemd 单元。二进制未签名——macOS 先去掉隔离属性:

xattr -c ltop-*-darwin.tar.gz

Linux 侧解包后:

sudo cp ltop /usr/local/bin/
sudo cp ltop-bpf /usr/local/bin/          # 可选,仅 Linux
sudo cp ltop-bpf.service /etc/systemd/system/
sudo systemctl enable --now ltop-bpf      # 可选

AUR

ltop-bin——打包件已就绪,等 AUR 开放账号注册即发布,届时更新本页。

部署/升级 eBPF 助手

助手要随 TUI 一起重新部署——陈旧的 ltop-bpf 还在往旧路径写快照, 每进程计费会静默归零:

sudo cp target/release/ltop-bpf /usr/local/bin/
sudo systemctl restart ltop-bpf

验证

ltop --version          # TUI/CLI 版本
ltop --json | head -c 300    # 一份 schema-v1 快照;"meta.udp_helper": true
                        # 说明 eBPF 助手在跑(Linux)
sudo ltop-bpf --once    # 采集器冒烟测试: 采一次、打印、退出

源码构建

git clone https://github.com/uMaj35ty/ltop
cd ltop
cargo build --release

# 国内镜像(历史与 tag 完全一致,中文优先 README):
git clone https://atomgit.com/uMaj35ty/ltop
# 产物在 target/release/: ltop、ltop-bpf(Linux)

要求: Rust stable;Linux 上构建 eBPF 对象需要带 bpf target 的 clang (没有会怎样见上文)。eBPF 探针内含 x86_64 与 aarch64 两种架构的 pt_regs 寄存器映射,全程不需要 nightly。

每个 release 在 QEMU/KVM 里验证(开箱二进制、kprobe 挂载、systemd 单元、 无助手时的静默降级)——矩阵见兼容性。

TUI 界面

六个盒子各司一职。Tab 循环三种布局——classic(左图表右表格)、 wide(上图表下表格)、tall(单列)——1–6 开关盒子,关掉的盒子 干净收起。z 把焦点盒子放大全屏,esc 退出。space 冻结画面;暂停期间 发生的流量在恢复时补齐,不会漏账。

六个盒子

1 — NET

每网卡实时吞吐(盲文面积图,rx/tx 独立渐变色),加链路状态、速率、双工、 MTU 和地址。累计流量显示两份: ltop 启动以来(可重置)和接口启动以来。 n 切换图表模式;点表头切换网卡。

2 — LAN

自动发现的同子网设备(原理见 LAN 发现): IP、MAC、mDNS 主机名、 接口,网关有标记。每个邻居带实时连接数、当前速率和累计字节——数字与 CONNS 联动,“到那台机器的流量是多少“看一眼就知道,enter 置顶邻居并让 CONNS 只看这个对端。

3 / 4 — DISK I/O 与 DISKS

读/写速率图表(堆叠设备去重——nvme0n1 和它的 dm-0(root) 只算一份), 旁边是设备列表: 容量条加每设备实时速率,文件系统类型以暗色小字缀在设备名 后。macOS 上只列挂载卷: 虚拟机与模拟器会把虚拟盘以宿主可见的合成设备 形式挂出来——动辄十几个——而宿主看不到它们内部的容量与用量,这些行只是 噪声。Linux 上 VM 的磁盘不会成为宿主块设备(只是文件系统里的普通文 件),设备树如实反映硬件,保留完整物理树(盘 → 分区 → dm,含未挂载结构 行,LUKS/LVM 分层可读)。d 展开 挂载列表并把方向键/跳转键指向 disks 列表,i 切换图表模式。列表超长时 右缘出现 btop 式滚动条——点轨道翻页、拖滑块滚动,无需聚焦(滚轮本来就 不需要)。

5 — CONNS

系统全部 socket。TCP 连接显示真实逐连接 B/s 和总量;UDP 连接由 eBPF 计量 (Linux,经 eBPF 助手),列与 TCP 相同。行带协议标签 (tcp/udp,本地对端标 lan),关闭的连接留 5 秒灰显墓碑行 (tombstone_ttl_ms 可配)——结束的传输在屏幕上还读得到。f 循环过滤 (all → lan → tcp → udp),o 循环排序——包括 proc 分组,同名进程折进 可展开的组头(▸ firefox ×17,组头带 Σ;组头上 enter 折叠/展开,搜索命中 自动展开)。

6 — PROCS

每进程会话累计: 网络(TCP+UDP——eBPF 在系统调用处计字节,短命连接不会 漏)和磁盘 I/O,加实时速率。退出的进程灰显保留,带捕获的命令行;s 一键重启,或 enter 开详情面板复制完整命令。r 循环排序(net-sum → net-rate → disk-sum → disk-rate → name)。退出进程的账本默认 30 分钟后 清除(proc_exit_retention_min,0 = 永久保留)。

焦点、选中与详情

  • p / c / l 单焦点 PROCS / CONNS / LAN: 选中的盒子撑满注意力,其余 变暗成占位。esc 清除。
  • 方向键选中会跟着行走——重排、组折叠之后,你看的还是同一行。
  • conns/procs 行上 enter 开详情面板: 进程显示状态、运行时长、完整 捕获命令行、exe/cwd、RSS 和 UDP 分解;连接显示协议、属主、生命周期、 总量与速率。面板内: space/t 追踪置顶(被追踪的行排最上),k 终止, s 重启,↑↓ 移动字段光标,y 用 OSC 52 复制选中值(ssh 下直达本地 剪贴板,不依赖 X11)。
  • LAN 行上 enter 置顶邻居(红色高亮,钉在最上)同时让 CONNS 只看 这个对端;再按一次取消,esc/f 也能清。

搜索

/ 按名字子串搜索进程与连接(Tab 换目标盒子,enter 应用,esc 清除)。 过滤后的视图仍按你选的模式排序。

终止的保护栏

k 终止选中的进程(或关闭 socket)。终止其他用户的进程需要在配置里开 allow_global_kill = true,默认拒绝。

监控日志

L(或启动时 --log)把每进程账本记到 ~/.local/state/ltop/ltop-log-<ts>.jsonl,间隔 log_interval_ms(默认 60 秒),格式与 watch 同为 schema-v1 快照;保留期 log_retention_days (默认 7 天),启动时清旧。回放与导出: --replay [--csv OUT]。详见 数据面。

完整键位表

按键作用
q / Ctrl-C退出
space暂停/恢复采样(恢复时补齐)
/搜索(Tab 换盒子,enter 应用,esc 清除)
m菜单: 主题 / 设置 / 重置 / 图表 / 帮助 / 退出
Esc清除焦点与选中;关闭面板
1–6开关盒子: net、lan、disk i/o、disks、conns、procs
Tab布局 classic → wide → tall
p / c / l单焦点 procs / conns / lan
rprocs 排序循环
f / oconns 过滤循环 / 排序循环
组头上 enter、←→折叠 / 展开进程组
d展开/收起磁盘挂载树;方向键/跳转键随即指向 disks 列表
elan 排序: ip → hostname → mac → iface
n / inet / disk 图表模式
↑↓ PgUp PgDn / 滚轮移动选中;PgUp/PgDn 按可视高度翻页;滚轮滚动光标下的列表;点击选中
disks 滚动条点轨道翻页、拖滑块滚动——无需聚焦
LAN 行上 enter置顶邻居 + CONNS 过滤到该对端
conns/procs 行上 enter详情面板(追踪 t/space,终止 k,重启 s,复制 y)
z焦点盒子全屏缩放
Home/End/g/G跳到首行/末行
L监控日志开关
sLAN 扫描开关(主屏;详情面板里 s 是重启)
+/-刷新间隔 ±250 ms

常用设置(都在 m → settings,持久化到 ~/.config/ltop/config.conf): 刷新 tick_ms(默认 2000)、墓碑 TTL、录制开关(与 L 键同路径)、日志 间隔/保留、扫描间隔、默认排序/过滤、theme、lang、 proc_expand_default(进程组默认展开)、proc_exit_retention_min、 allow_global_kill(暴露 k 键,默认关)、allow_global_log(暴露 L 录制 热键,默认关)。

主题

ltop 读 btop 兼容的主题文件: 任何 btop 主题直接可用,自己写也行——哪怕 只是两行,修掉终端上读不清的那几个颜色。

主题放哪

  • 内嵌: 72 套主题——41 套来自 btop 官方主题集,31 套来自 Omarchy 内置主题——主题菜单(m → theme)或命令行 --theme <name> 选择 (见致谢)。
  • Omarchy: 若存在 ~/.local/state/omarchy/current/theme/btop.theme, 菜单会多出 omarchy 条目——选中即跟随桌面主题,桌面换主题时热重载。
  • --follow-theme: 启动时读到的是当时的快照;加 --follow-theme 则桌面主题变化时运行中的 ltop 也跟着变色。默认关(它要轮询主题 文件,想要上面 GIF 的效果再开)。
  • 自定义: .theme 文件放进 ~/.config/ltop/themes/,或直接加载:
ltop --theme ~/my-colors.theme

--theme 加载的主题是钉死的——不跟随 omarchy。

文件格式

每行一个键值对,# 开头是注释。颜色接受 #RRGGBB、缩写 #RGB、两位 灰度缩写(#80 = 中灰),main_bg 还接受空值,含义是“终端默认色“ (透明背景,终端半透明用户需要):

theme[main_fg] = "#c0caf5"
theme[inactive_fg] = "#565f89"

致谢

内嵌主题库建立在以下项目的成果之上,在此致谢:

  • btop(aristocratos/btop, Aristocratos 作品)——ltop 的主题格式就是 btop 格式,内嵌 41 套主题 转换自 btop 官方主题集。感谢 Aristocratos 与该主题集的每一位作者。
  • Omarchy(dhh/omarchy,DHH 作品) ——内嵌 31 套主题来自 Omarchy 内置主题集。感谢 DHH 与这些主题的 创作者。

为 btop 或 Omarchy 写的主题在这里继续可用——成果属于创作者,内嵌时 保留出处。

变量参考

键控制什么
main_bg弹窗/对话框背景;留空 = 终端默认
main_fg正文——表格单元格、详情值、帮助描述
inactive_fg弱化文本——标签、提示、次要信息、时间戳
hi_fg高亮: 盒子边框、键位、组标题、徽章
title弹窗/盒子标题
graph_text强调色: 进程名、UDP 徽章、着重
net_boxNET 盒边框
proc_boxLAN 盒边框(键名沿用 btop,保兼容)
mem_boxDISK 盒边框(键名沿用 btop,保兼容)
download_start/mid/end下载渐变: 图表、rx 速率、ESTAB 徽章
upload_start/mid/end上传渐变: 图表、tx 速率
used_start/mid/end磁盘用量色
temp_start/mid/end告警渐变

渐变必须三档齐全(start/mid/end);缺任何一档整条渐变被忽略,用内建默认。

最小示例

只覆盖读不清的颜色,其余回落到当前选中的内建主题:

theme[main_fg] = "#e0e0e0"
theme[inactive_fg] = "#909090"

存为 ~/.config/ltop/themes/readable.theme,主题菜单里选 readable 即可。

完整示例

最省事的完整主题是拷一份内建 btop 主题来改:

cp /usr/share/btop/themes/dracula.theme ~/.config/ltop/themes/my.theme

完整文件长这样(Dracula 配色,供参考):

theme[main_bg] = "#282a36"
theme[main_fg] = "#f8f8f2"
theme[title] = "#bd93f9"
theme[hi_fg] = "#8be9fd"
theme[inactive_fg] = "#6272a4"
theme[graph_text] = "#ff79c6"
theme[net_box] = "#bd93f9"
theme[proc_box] = "#ff79c6"
theme[mem_box] = "#8be9fd"
theme[download_start] = "#8be9fd"
theme[download_mid] = "#8be9fd"
theme[download_end] = "#57c7ff"
theme[upload_start] = "#ff79c6"
theme[upload_mid] = "#ff79c6"
theme[upload_end] = "#bd93f9"
theme[used_start] = "#50fa7b"
theme[used_mid] = "#f1fa8c"
theme[used_end] = "#ff5555"
theme[temp_start] = "#50fa7b"
theme[temp_mid] = "#f1fa8c"
theme[temp_end] = "#ff5555"

已知限制

LAN 盒的 MAC 列在 macOS 上无论主题如何都隐藏——系统对非 Apple 签名二进制 做了脱敏。见兼容性。

LAN 发现

LAN 盒回答“我网上有谁“——不要 root、不用 nmap、不出 TUI。发现靠两个机制:

  1. 被动 —— 每次刷新都读内核邻居表(ARP/NDP),机器说 过话的设备立刻 出现,带着内核还记着的新鲜度。
  2. 主动 UDP knock 扫描 —— 后台线程遍历本地子网(由本机接口地址+前缀 推出),向候选地址发小 UDP 包。包本身多半无人应答,但这个尝试会让内核 去做 ARP 解析,于是内核会把邻居报出来——ltop 自己不需要 raw socket, 也不需要 root。扫描节奏是 sweep_interval_s(默认 60 秒),安静的 网络可以关掉(sweep = false)。主屏按 s 也能随时开关。

两路结果按(接口, IP)合并。主机名走尽力而为的三级解析——mDNS 反查 → NetBIOS node status → 反向 DNS;网关有标记;macOS 的邻居表脱敏绕过方式是 经路由 socket 逐条探测内核缓存——那边哪些可见哪些不可见见 兼容性 → macOS。真实 MAC 来自 ltop lan-setup:一个 每用户 launchd 代理,经 Apple 平台签名工具轮转 arp/ifconfig 快照 (免 root、免 entitlement)——未启用时 MAC 显示 —。

每个邻居显示什么

列含义
IP / hostname地址,能解析就带 mDNS 名
MAC硬件地址(macOS 未启用 ltop lan-setup 时显示 —)
iface从本机哪块网卡可达
Σ connsCONNS 里指向这个对端的活跃连接数
rate到这个对端的当前 rx+tx
Σ bytesltop 启动以来到这个对端的累计字节

流量列是重点: LAN 盒和 CONNS 共用连接账本,每个邻居自带属于它的那一份 流量。

交互

  • e 循环 LAN 排序(ip → hostname → mac → iface)。
  • ↑↓ 选中;选中会跟着邻居走——重排、扫描后位置不丢(设备从 ARP 里短暂 消失也不影响)。
  • enter 置顶邻居——钉在最上、红色高亮——同时让 CONNS 只看这个 对端。这是“这台设备到底在干什么“的快车道: 选中、回车、读逐连接分解。 再按 enter 取消;esc/f 也能清。
  • l 单焦点 LAN 盒;z 全屏(子网设备多的时候好用)。

刻意不做的

  • 子网从本机接口推出,不扫描已连接前缀之外的地址。
  • 完全屏蔽 ARP 的设备(个别开了防火墙的主机)只有在内核因其他流量留下 缓存时才出现。
  • 扫描只是“发往空处的 UDP“: 不做 TCP connect、不探端口、不发 raw 包—— 在操作系统眼里就是几次普通的(失败的)投递尝试。

eBPF 计费

为什么需要它

常规路子有两个绕不过去的坑:

  • netlink//proc 不给逐 socket 的 UDP 字节计数。 TCP 还有字节队列 可看,UDP 什么都没有。
  • 逐 socket 抽样会漏短命 TCP 连接。 一个采样周期内完成全程的连接完全 不可见——而这恰恰常是你想抓的流量(DNS、小请求、话痨型辅助进程)。

ltop-bpf 把计数挪到字节发生的地方: 在 send/recv 系统调用(v4 和 v6) 上挂 kprobe,按 pid 和 socket inode 在内核 map 里累计载荷字节。 两本账喂给同一个 UI,于是 PROCS 拿到不会漏短命连接的每进程总量,CONNS 也能像 TCP 一样把字节记到单条 UDP 连接上。

架构

ltop-bpf(root,systemd)                ltop(免特权 TUI)
  kprobe 挂 send/recv v4+v6               每 tick 读 /run/ltop/udp.json
  pid 账本 ─┐                             按实例 ID 重基线后做差
            ├─ /run/ltop/udp.json  ──►    (饱和差分)
  inode 账本┘   每秒原子重写                合并进自己的账本

特权采集器和免特权 UI 之间只有一份每秒重写的全局可读快照文件。TUI 永远 不需要特权,助手也不需要知道终端的存在。

部署

sudo cp ltop-bpf /usr/local/bin/
sudo cp ltop-bpf.service /etc/systemd/system/
sudo systemctl enable --now ltop-bpf
  • 冒烟测试: sudo ltop-bpf --once 采一次打印即退; sudo bash scripts/udp-smoke.sh 造可计费的 UDP 流量并端到端验证快照; python3 scripts/snap-diff.py 打印每 pid 的原始差分。
  • 升级: 助手要随 TUI 一起重新部署(为什么见 FAQ)。
  • 源码构建需要带 bpf target 的 clang;预编译 tarball 内含编译好的 对象。

数据干净靠什么

几道护栏保证长时间运行的计数不出脏数据:

  1. LRU map 自清理。 pid 和 socket map 都是 BPF_MAP_TYPE_LRU_HASH (各 16384 项): 空闲进程和关闭的 socket 自己被驱逐,几千进程的机器 也耗不尽 map。
  2. 实例 ID + 饱和差分。 每个助手实例(flock 单实例锁守护)给快照 打唯一 ID;TUI 发现 ID 变了就重新基线,差分用饱和运算——pid/socket 复用、守护进程带着旧文件重启,都变不出负数或垃圾值。
  3. CO-RE,不做每内核构建。 唯一和结构体耦合的部分(从 sk 走到 socket inode)用 CO-RE 重定位,加载时对着内核 BTF 解析字段。没有 BTF 的内核也能跑(Ubuntu 22.04 基线已验证)——字段偏移加载时解。

探针在退出时自动摘除——采集器崩了也不会留下 kprobe;寄存器读取有 16 MiB 值域闸门,野 len 污染不了账本。

数字怎么读

eBPF 账本计的是载荷字节(系统调用处)。NET 盒计的是接口字节 (驱动层,每个包都算)。两者范围本来就不同——头、重传、没经过你进程 系统调用的 LAN 杂音只存在于接口数字里——所以 PROCS 总量比 NET 盒低 10–40% 是正常形状,不是 bug。精确拆解见 FAQ。

没有助手时

ltop 默认免特权、从不要求助手: 没有它,UDP 每进程列干脆不出现(TCP 靠 socket 抽样照常),--json 里 meta.udp_helper 读 false。macOS 没有 eBPF 也没有助手——Apple 原生计费方式和差异说明见 兼容性 → macOS。

数据面

ltop 的每个显示面背后都是同一份序列化快照——schema v1,随二进制一起 版本化,脚本和 agent 可以放心依赖。同样的结构体喂给这些入口:

入口命令形态
一次性快照ltop --json单个 JSON 对象(不过滤约 8k token)
字段参考ltop --schema随版本更新的机器可读字段表
监控日志L / --logJSONL,每 log_interval_ms(默认 60 秒)一行
无头采集ltop watchJSONL,每 --interval(默认 5 秒)一行
窗口摘要ltop report人读表格;--json 给 ~2 KB JSON
ltop --json      # 结构化快照(约 1.2 秒: 连采两轮,速率字段才有值)
ltop --schema    # 权威字段表——随二进制版本化,永不漂移

快照覆盖五个域: meta(版本、os、arch、udp_helper 标志)、net (每接口速率与累计计数)、procs(每进程网络+磁盘计费,带 UDP 分解)、 conns(逐连接 socket)、disk(容量/吞吐)、lan(邻居)。值得知道的 语义直接标在输出里——比如 macOS 的 MAC 脱敏(启用 ltop lan-setup 后即为真值)。

监控日志(TUI)

TUI 里按 L,或启动带 --log,快照记到 ~/.local/state/ltop/ltop-log-<ts>.jsonl:

  • log_interval_ms(默认 60 000)定节奏; log_tracked_only = true 只记 被追踪的进程。
  • log_retention_days(默认 7)在启动和开关时清理过期文件。

无头 watch

ltop watch --duration 10m --proc chrome   # 完整语法见 `ltop watch --help`
  • 停止条件: --duration(10s/5m/2h)、--stop 哨兵文件(出现即消费 并停止)、SIGINT——后者是优雅停: 最后一份快照落盘。
  • 输出默认 ~/.local/state/ltop/ltop-session-<ts>.jsonl,与 TUI 监控日志 分开、不受它的保留期清理;自己的 --retention(默认 7 天,0 = 永久) 在启动时清理。
  • 逐行追加,崩溃安全;免 root。
  • --proc <name> 聚焦模式只记匹配的进程及其连接——按名追踪,重启换了 pid 时间线也不断。
  • 写盘量随间隔线性(1 秒 ≈ 8 KB/行 ≈ 28 MB/h;默认 5 秒约 5–6 MB/h)。 清理靠 --retention。

report

ltop report <file.jsonl> [--json]

读 watch 产物或 TUI 监控日志(同一 schema),给出窗口摘要: 每进程窗口 总和(跨 pid 重启的窗口差分)、峰值速率、活跃时长、最后存活/退出状态; 每连接的总和/峰值/生命周期(按 inode 键,消失的连接保留最后已知总量); 网卡范围的全局总量与最忙时段。

过滤: --top N(默认 5,按流量)、--proc(子串,含 * 时通配)、 --fields net,udp,disk,conns、--json 机器可读。建在其上的 AI 工作流见 AI 代理。

遗留与调试

  • ltop --dump —— 人读的单轮采样打到 stdout(调试用;要解析请用 --json,dump 会截断对不齐)。
  • ltop --replay [--csv OUT] [--top N] —— 从旧版 session-* 日志(v1, 仅 procs)重建会话增量并导出 CSV。新格式文件归 report,旧文件会被 拒收并指路到这里。

配置

~/.config/ltop/config.conf 是纯 key = value,应用内设置面板 (m → settings)写入,手改安全(重启生效):

键默认含义
langen界面/消息语言;zh 切中文(JSON 键恒英文)
layoutclassic启动布局(classic/wide/tall)
tick_ms1000刷新间隔
graph_net / graph_diskhybrid / centered默认图表样式
boxes全开可见盒子
log_interval_ms60000监控日志节奏
log_retention_days7监控日志保留天数
log_tracked_onlyfalse只记被追踪的进程
sweep / sweep_interval_strue / 60LAN UDP knock 扫描开关与节奏
tombstone_ttl_ms5000关闭连接在 CONNS 留多久
themeomarchy主题名(见主题)
theme_live_followfalse桌面主题变化时运行中的 ltop 跟着变色(同 --follow-theme)
proc_expand_defaultfalseCONNS 进程组默认展开
proc_exit_retention_min30退出进程账本 N 分钟后清除(0 = 永久)
conn_filter / conn_sort / proc_sort / lan_sortall / proc / net-sum / ip默认列表模式
allow_global_killfalse允许终止其他用户的进程
net_graph_coupledfalseNET 图表比例耦合:上下行悬殊时,小方向图按真实比例占图表高度,不再满幅放大
net_graph_scale_ratio5上面的触发阈值,单位倍(2–20);低于阈值保持普通自动缩放

AI 代理

ltop 把“这台机器的网络/磁盘/LAN 状态“当数据处理,而不是让你去刮屏幕: 一份 schema 稳定的 JSON 快照喂 TUI、CLI、日志和无头工具。本页是给 agent 用的工作参考; 同样内容在仓库里打包成了现成的 agent skill: docs/skills/ltop-observe/SKILL.md (含诊断配方)。

一次性问题: --json

ltop --json | jq '<查询>'     # 快照; 约 1.2 秒(连采两轮才有速率)
ltop --schema                 # 版本化字段参考,永不漂移

单帧过滤后的快照约 1.7k token——传统命令组合(ss/lsof/df/arp 输出 再解析)约 2.2 万,不过滤约 8k。一次性问题这就是对的工具。

CLI 面严格: 未知子命令和手滑(ltop repor)一律 exit 1 并给明确报错—— 没有任何东西会“意外落进交互 TUI“; JSON 键不随 lang 变,恒英文。

时间窗: watch + report

“盯 10 分钟再汇报“这类任务不要轮询 --json(5 秒节奏 10 分钟约 4 万 token)。录一次,摘要一次:

ltop watch --duration 10m --proc chrome    # 无头、崩溃安全、免 root
ltop report <watch 打印的路径> --json    # report 只收单个文件

report --json 返回约 2 KB 的精确数字——窗口总和(末快照累计 − 首快照 累计,跨 pid 重启分段)、峰值速率、活跃时长——不是抽样猜测。实机实测: 同样信息省 ~97% token。

{"schema":1,"file":"…","host":"…",
 "window":{"start":…,"end":…,"snapshots":N,"interval_s":S},
 "totals":{"scope":"nic","nic_rx":…,"nic_tx":…,"peak_ts":…,"peak_rx_bps":…,"peak_tx_bps":…},
 "procs":[{"name":"chrome","net_recv":…,"net_sent":…,"peak_rx_bps":…,"peak_tx_bps":…,
           "udp_recv":…,"udp_sent":…,"peak_udp_bps":…,"disk_read":…,"disk_written":…,
           "peak_disk_bps":…,"active_s":…,"alive":true}],
 "conns":[{"remote":"1.2.3.4:443","proto":"tcp","recv":…,"sent":…,"peak_rx_bps":…,
           "peak_tx_bps":…,"duration_s":…,"state":"ESTAB","process":"chrome"}]}

--top N(默认 5)、--proc(子串或含 * 的通配)、--fields net,udp,disk,conns 可以再裁。

和 jq 的分工

watch 产物和 TUI 监控日志就是普通 JSONL——report 不聚合的任何切片都是 一条 jq 的事(文件同 schema,report 两者都读)。窗口数学给 report, 任意查询给 jq,当前瞬间给 --json。

读快照——最容易读错的地方

  • meta.udp_helper: true 表示 Linux eBPF 助手在跑、UDP 每进程计费完整; false(或 macOS)时 UDP 数字不完整。
  • conns[].process 为 null 是其他用户的 socket(Linux)。别断言 这些连接“与任何进程无关“——只是归不到你的 uid 头上。
  • procs[].disk_* 只覆盖当前用户的进程。
  • net.interfaces[].session_rx/tx = ltop 启动以来(可重置); alive_rx/tx = 接口启动以来。
  • 进程总量是载荷字节,接口总量是网卡字节——差 10–40% 是设计使然 (为什么)。

配方(来自打包的 skill)

  • 网速慢? net.interfaces[] 按 rx_bps+tx_bps 排序; 查 operstate 和 speed_mbps; 再看忙接口上 bps_recv+bps_sent 最高的 conns[]—— conns[].process 就是吃流量的(限你自己的用户)。
  • 磁盘忙? disk.devices[] 看吞吐对容量,再按磁盘速率排 procs[] 找写盘的。
  • LAN 清点? lan.neighbours[]——网关已标记、mDNS 主机名、tracked 是置顶设备。
  • “盯 chrome 10 分钟汇报流量”——上面那对命令,两条都带 --proc chrome。

展望

ltop mcp 子命令(手写 stdio JSON-RPC,包 --json 和 watch+report,后续 加多机 fleet 聚合)在 0.3 路线图上; 上面的 JSON 接口就是它的底座,schema v1 今天已稳定。

兼容性

要求

源码构建要 Rust stable; 平台为 x86_64 / aarch64 的 Linux 或 macOS。 预编译 Linux 二进制基线 glibc 2.35(Ubuntu 22.04 LTS)。eBPF 计费仅 Linux,构建期需要带 bpf target 的 clang; 运行期没有任何特殊要求—— 不要 BTF、不要 nightly、不要内核头。

已测环境

每个 release 的 tarball 都在 QEMU/KVM 里逐发行版验证: 开箱二进制、eBPF 探针挂载(含 kprobe)、systemd 单元、无助手时的静默降级。日常开发环境是 Omarchy(Arch),它同时充当参考桌面。

环境内核eBPF 计费备注
Arch Linux (rolling)7.2.7✓ 完整同时是开发机(Omarchy 桌面)
Ubuntu 24.04 LTS6.8✓ 完整glibc 2.39
Ubuntu 22.04 LTS5.15✓ 完整无 BTF 可跑; glibc 2.35 基线
Ubuntu 24.04 LTS (aarch64)6.8✓ 完整QEMU aarch64; 树莓派级硬件预期一致
Debian 136.12✓ 完整glibc 2.41
Fedora 44 (Workstation live)6.19✓ 完整SELinux enforcing: 零拒绝
macOS 27(Apple Silicon,MacBook Air)darwin 27n/a(nettop 路径)实机验证; 见 macOS

裁过 kprobes/BTF 的特种内核(如 Ubuntu 的 -kvm 云内核)是唯一已知的坑: 换 generic 内核。那是内核 flavor 的限制,不是 ltop 的。

SELinux

Fedora(enforcing)下两个二进制加 systemd 单元零拒绝——助手走标准 bpf syscall 路径挂 kprobe,只往 /run/ltop/ 写一份全局可读快照。

macOS

macOS 没有 eBPF; 同样六个盒子读 Apple 原生源:

  • PROCS 和 CONNS 轮询 nettop(每进程行与每 socket 流,TCP+UDP 一次 spawn 全拿); CONNS 归属经 libproc 扫调用者自己的 socket——其他用户的 连接显示 n/a。
  • DISK 读 IOKit IOMedia 统计加每进程 rusage。
  • LAN 解析 arp -an 和默认路由——并对平台的邻居表脱敏做了绕行(见下)。
  • macOS 构建不含 ltop-bpf。

与 Linux 路径的已知差异:

  • socket 计数是活 socket 上的累计值,靠抽样: 一个采样周期内完成的 传输不计入。(eBPF 路径在系统调用处计数,不漏。)
  • 系统对非 Apple 签名二进制隐藏部分本地网络——与“本地网络“隐私开关 无关: 邻居表枚举为空,单条路由查询返回的 MAC 被脱敏成接口合成地址, getifaddrs 字节计数冻结(全部与 Apple 签名工具同秒交叉验证过)。 macOS 27 更进一步: 从应用里 shell 出的 Apple 签名 arp 也返回空, getifaddrs 把所有网卡 MAC 报成 02:00:00:00:00:00(读取权改由未公开 的 com.apple.developer.networking.topology-observation entitlement 按 「责任进程归因 × 平台签名」双维度门控)。ltop 的绕法: NET 盒改用 netstat -ib 计数,LAN 盒经路由 socket 逐条探测内核缓存重建邻居列表, ltop lan-setup 另装一个每用户 launchd 代理,经 Apple 平台签名工具 轮转 arp/ifconfig 快照——LAN/NET 盒显示真实 MAC,免 root、免 entitlement。未启用时 MAC 显示 —。
  • 裸终端的帧buffer 字体可能缺盲文字形; 走 ssh 或用正经终端模拟器则齐全。

分发渠道回顾

细节见安装: Homebrew(macOS 与 Linux)、crates.io (源码)、GitHub Releases tarball(x86_64/aarch64)、AUR ltop-bin 待 注册开放。

已知限制

  • 其他用户的连接只能归到 uid 层(Linux 的 /proc/<pid>/fd 不可读; macOS 经 libproc 显示 n/a)。
  • WiFi 网卡内核不给链路 speed,字段留空。
  • CONNS 的 TCP 总量含整条连接生命周期(内核语义)——见 FAQ。
  • ltop-bpf 重启后 eBPF 计数从零开始; UI 经快照实例 ID 自动重新基线。
  • 配置文件: 未知键与注释行在保存时保留(0.2.10+),但已知键携带本版本 不认识的值时(如更新版本新增的排序名),会回落默认并在下次保存时被重写。
  • macOS 只计活 socket(nettop 语义): 一个采样周期内完成的传输不计。

与其他工具对比

ltop 不想取代 btop 或 nethogs。它补的是它们空着的那一块: 这台机器、这个 局域网上谁在和谁通信——按进程、按连接,且带机器可读的数据面。

btop —— 建议两个一起用

系统总览归 btop: CPU、内存、传感器、全部进程。ltop 借了它的视觉语言 (盲文图表、盒子网格、连主题格式都兼容),但只盯网络、磁盘 I/O 和 LAN—— 而且盯得更深: 跨重启存活的每进程会话总量、TCP 和 UDP 的逐连接字节、带 流量的 LAN 邻居、可事后分析的无头采集。

作者自己每天 btop 和 ltop 并排开——btop 看系统,ltop 看流量——也推荐 这么用。你现成的 btop 主题在 ltop 里直接可用。

nethogs —— 每进程,但只有当下

nethogs 打一份每进程 bytes-per-second 列表(大部分场景要 root),两次 刷新之间什么都记不住。ltop 记会话账本: 退出的进程带着总量留在屏幕上, TCP/UDP 经 eBPF 精确归属,还有逐连接行、磁盘 I/O 和 LAN 维度。如果你只要 一份实时列表而且有 root,nethogs 更小; 其余都是 ltop 的地盘。

iftop —— 每地址对,单接口

iftop 显示一块接口上地址对之间的带宽。ltop 的 CONNS 盒覆盖同样的视图, 外加每连接总量与速率、属主进程,以及“LAN 邻居 ↔ 连接“的联动。iftop 剩下 的优势: 预装的地方更多。

shell 管道(ss / lsof / arp / df)

对脚本和 agent 来说这才是要紧的对比: 五种输出格式要解析、一半答案要 root、逐 socket 的 UDP 字节哪里都没有、上小时发生了什么完全无记忆。 ltop --json 一份 schema 稳定的快照答完(过滤后约 1.7k token), watch + report 把“刚才发生了什么“变成两条命令加精确数字——见 AI 代理。

常见问题

rx 和 tx 两张图形状一样

不是 bug——两个效应叠加。每张图按各自窗口内的峰值归一化(btop 同款, 为了小波动也可读),而下载时上行几乎全是 TCP ACK,其速率与下行包速率 一一对应。你会看到 tx/rx ≈ 1/30——正是 ACK 的理论占比(约每 2 个数据段 1 个 ACK,2900 字节数据对 66 字节确认);图表把这条微小的波形放大到 满幅,两条曲线自然长得像。两个方向差距悬殊时读头部数字、在 m → graphs 里换 Block 图表模式,或开启比例耦合让小方向按真实占比占 图表高度:m → graphs → c(要持久化设 net_graph_coupled = true; 触发倍数 net_graph_scale_ratio,默认 5 倍)。

PROCS 总量比 NET 盒低

所有平台都如此,是设计使然。NET 盒计接口字节(驱动层: 每个包都算, 含头、重传和背景杂音); PROCS 计归到进程头上的载荷字节(Linux 在系统 调用处 eBPF 计,macOS 靠活 socket 计),部分平台还只算你自己的进程。差值 就是“是接口流量、但不是你进程载荷“的那部分。精确拆解见 eBPF 计费 → 数字怎么读。

CONNS 总量包含 ltop 启动之前的流量

也是设计使然,仅 TCP: 连接的 Σ 来自内核逐 socket 计数器,覆盖连接的完整 生命周期——包括 ltop 启动之前。UDP Σ 由 ltop(助手在线时)从会话开始 累计。这处差异(加上包头)也是 CONNS 和 PROCS 总量互相对不上的原因之一; 经代理的流量记在代理进程头上。

升级后每进程计费归零

陈旧的 ltop-bpf 还在往旧路径写快照,而新 TUI diff 的是另一个文件—— 症状是每进程数字静默读零。修法: 助手永远随 TUI 一起部署:

sudo cp ltop-bpf /usr/local/bin/          # 与 TUI 同一 release
sudo systemctl restart ltop-bpf

UDP 列缺失/不完整

Linux 上这意味着 eBPF 助手没在跑——查 ltop --json 的 meta.udp_helper, 然后部署助手(TUI 本身免 root; 没有助手 TCP 列靠 socket 抽样照常)。macOS 的 UDP 每进程数字来自活 socket 抽样,一个采样周期内 完成的传输不计——已记录的平台差异,不是 bug。

conns[].process 有些是 null

那些 socket 属于其他用户(Linux): 归属扫描只扫你自己 uid 的 socket。 “null“是“归不到你头上”,不是“没有进程在用“。

CONNS 里有个叫 “n/a” 的组(旧版本显示 uid:4294967295)

macOS 上的对应情形: 非特权的 ltop 只能归属你自己用户的 socket (libproc,与 Linux 读自己的 /proc//fd 同语义)。其他用户、系统守护 进程和内核的连接看得到流量,但归不到进程,于是聚在 n/a 组里——0.2.12 起如此; 旧版本把哨兵值原样打成 uid:4294967295,是同一个桶。这是权限 边界,不是数据缺失。想看归属,用 sudo ltop 跑一次即可(root 能枚举 全部进程,组随之清空); 是否以 root 跑监控请自行权衡。

--json 要等约 1.2 秒

背后连采两轮,每个速率字段才有真实差分可填。脚本上,这点延迟换来的是 速率而不只是计数; --dump 没这个等待但会截断值——解析请认准 --json。

watch 把磁盘写满了

写盘量随 --interval 线性: 1 秒 ≈ 8 KB/行 ≈ 28 MB/h; 默认 5 秒约 5–6 MB/h。采集文件默认 --retention 7 天(下次 watch 启动时清理; 0 永久保留)。长期记录是监控日志的活(L / --log)——默认 60 秒 粒度、7 天保留。

loli 命令没了

0.2.4 退役——localist top 时代的历史遗留,tarball/brew/AUR 都不再附带。 想要就自己软链一个(帮助文本跟着调用名走):

ln -s "$(command -v ltop)" ~/.local/bin/loli

AUR 包呢?

ltop-bin 打包已就绪,等 AUR 重新开放账号注册。在那之前用 Homebrew、 crates.io 或 GitHub Releases。

盲文字形缺(盒子显示成 ? 或空白)

终端字体缺 Unicode 盲文区。换个字体齐的终端模拟器,或走 ssh——裸 framebuffer 控制台可能缺字形。macOS 自带 Terminal 的裸渲染尤其如此。

老内核/云镜像

eBPF 助手运行下限 = glibc 2.35 + 有 kprobes 的内核; TUI 本身只要二进制 能链接就能跑。Ubuntu 的 -kvm 云内核裁了 kprobes——换 generic 内核。 Ubuntu 22.04 的 5.15 无 BTF 可跑(CO-RE 加载时解析)。

ltop 会不会偷偷联网/狂扫我的网络?

没有遥测,永远没有。唯一的对外动作是 LAN 扫描: 往自己子网发小 UDP 包 (默认每 60 秒,sweep = false 可关),借内核做 ARP 解析——不探端口、 不发 raw 包、不出已连接前缀一步。

怎么把报告变成 JSON 给 agent/脚本?

ltop report <file.jsonl> --json

……然后读 AI 代理——包括为什么循环轮询 --json 每 10 分钟要 多烧约 4 万 token,而 report 只要约 1k。

安全

本页说明 ltop 会触碰你系统与网络的哪些部分、拒绝做哪些事,以及它读取的 不可信输入如何被处理。运营政策(支持版本、漏洞上报渠道)见仓库的 SECURITY.md。

权限

  • TUI 全程免 root 运行。 所有数据源都是任意进程可读的:/proc、 getifaddrs、PF_ROUTE/netlink dump、临时 UDP socket。终止/重启进程 由内核限制在你自己的 uid 内。
  • ltop-bpf 是唯一的特权组件,且完全可选。它以 systemd 服务运行, 只持有 CAP_BPF + CAP_PERFMON(< 5.11 内核另需 CAP_SYS_RESOURCE), 只写 /run/ltop 下的一个快照文件,无任何监听端口、不发起网络连接。 随包的 unit 已做沙箱:NoNewPrivileges、ProtectSystem=strict(仅 /run/ltop 可写)、ProtectHome、PrivateTmp、内核接口保护,以及 不含 CAP_SYS_ADMIN 的能力边界集。

磁盘上的数据

数据位置权限
监控日志(L / --log)~/.local/state/ltop/0600
watch 采集~/.local/state/ltop/0600
配置~/.config/ltop/config.conf0644(仅界面偏好)
eBPF 快照/run/ltop/udp.json0644,root 属主——设计上全局可读

会话日志与采集文件记录连接对端、进程名和主机名,因此一律以 0600 创建,不依赖 umask。eBPF 快照全局可读是因为免 root 的 TUI 要读它;在 共享主机上这意味着每个本地用户都能看到各进程的字节收发量——多用户 机器部署助手前请把这一点纳入考量。

ltop 没有任何遥测:不检查更新、无统计上报,除下面的 LAN 探测外 没有任何数据离开你的机器。

网络行为

LAN 盒会主动查询本地网络:

  • 逐邻居的单播 mDNS、NetBIOS Node Status 与反向 DNS 查询 (主机名解析);
  • 可配置的 UDP “knock” 扫描——向子网内每主机发一个到 discard 端口 9 的空数据报,每轮最多 1022 台,默认 60 秒一轮,设置里可关。

所有行为都以你的局域网为边界。应答按不可信输入处理:DNS/NBNS 事务 ID 逐查询随机化并与源地址一同校验;所有解析器是有界检查的安全 Rust;不可 信字符串在进入任何终端输出前会被净化;eBPF 快照读取有文件大小上限。

漏洞上报

请使用仓库的 GitHub Private Vulnerability Reporting(可利用的问题 不要开公开 issue)。完整政策见 SECURITY.md。

参与贡献

欢迎 issue 与 PR。本页汇总项目的工程约定,让第一次 PR 就能对齐第十次 PR 的标准。

环境准备

  • Rust(stable 近期版);Linux 上还需要带 BPF target 的 clang—— eBPF 对象由 build.rs 在构建时从 bpf/net_bpf.c 编译。macOS 只需要 Xcode 工具链。
  • cargo test 必须全过,cargo clippy --all-targets -- -D warnings 必须零警告——零警告是硬门槛,CI 在 Linux x86_64、Linux aarch64、 macOS 三个目标上强制执行。

评审与 CI 会坚持的约定

  • 平台门控。 macOS 专属的 FFI 声明与函数一律加 #[cfg(target_os = "macos")]——未门控的 extern 声明会把链接错误带进 Linux 构建,而 Linux 侧 clippy 看不见 macOS 专属代码的 lint,所以平台 相关改动必须在对应目标上验证(CI 的 test-macos/test-aarch64 就是 为这个存在的)。
  • 偏移类常量要有出处。 结构偏移(kinfo_proc、socket_fdinfo、 rusage_info_v2 等)以 SDK 头文件为准并经真机验证;注释里写明来源, 复核时读头文件本身,不要转信二手值。
  • 不可信输入必须净化。 来自 LAN(mDNS/NBNS 主机名)、本地进程、 配置文件与外部 JSONL 的字符串不得裸写终端:TUI 走 ratatui(控制符被 丢弃),CLI 输出走 sanitize_text。新增输出路径必须同样处理。
  • 测试用真实 fixture,不互相模拟。 watch 有消费 ltop watch 真实 输出的端到端测试;replay 同时带现行与旧格式 fixture;UI 测试断言渲染 缓冲。修 bug 必须钉回归:改回旧代码确认测试会挂(突变验证)是修复的 一部分。
  • 界面双语。 用户可见文案走 src/config.rs 的 tr 词典——英文与 中文词条成对添加。盒标题与技术 token 按设计保留英文。
  • 文档随代码。 用户可见改动同步更新 mdBook(双语),定位性改动更新 README,CHANGELOG.md 按既有风格书写。

PR 流程

  • 从 master 拉分支;一个 PR 只做一件事。
  • 提交信息惯例:一行高密度摘要,讲清做了什么与为什么(见 git log)。
  • CI 必须绿(三个 CI 目标的 test + clippy)。发版由维护者执行:tag → 签名 tarball → Homebrew tap → crates.io → 文档站。

安全敏感改动

如果改动涉及 LAN 解析器、eBPF 助手、文件权限或安全 页面的任何内容,请在 PR 描述里明确指出。审计基线在仓库历史里(0.2.9); 请把你所保持的性质显式写出来——例如“LAN 提供的字符串永远不会未经 过滤地到达终端“。

致谢

ltop 的外观带着感激与出处,借用自两个项目与其背后的作者:

  • btop(aristocratos/btop, Aristocratos 作品):主题格式与 btop 兼容,内嵌 41 套主题来自 btop 官方主题集;
  • Omarchy(dhh/omarchy,DHH 作品): 内嵌 31 套主题来自其内置主题集。

感谢 Aristocratos、DHH 与每一位主题创作者——见 主题 → 致谢。