简介
ltop(localist top)是一款只盯一台机器的终端监控器。btop、nethogs、iftop 各答对一部分的问题,它三个一起答:
- 流量去哪了? —— 谁在和谁通信、走哪块网卡、速率多少,每连接、每进程 的字节计费(TCP 和 UDP)都有。
- 进程在干什么? —— 谁正在吃带宽和磁盘,整场会话累计吃了多少;进程退出 了也留账。
- 局域网上有谁? —— 哪些设备在线、哪个是网关、到每台设备的流量是多少。
工作方式
六个盒子各司一职(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 / o | CONNS: 过滤循环(all/lan/tcp/udp)/ 排序循环(proc 分组、sum、name、rate) |
r | PROCS: 排序循环(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(或
bpftarget)不可用时构建照样成功,嵌入空对象: TUI 正常运行,只有 UDP 每进程计费静默缺席。该情况下ltop-bpf启动时会明确报错拒启。 - 从源码构建 eBPF 采集器需要带
bpftarget 的 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 |
r | procs 排序循环 |
f / o | conns 过滤循环 / 排序循环 |
组头上 enter、←→ | 折叠 / 展开进程组 |
d | 展开/收起磁盘挂载树;方向键/跳转键随即指向 disks 列表 |
e | lan 排序: ip → hostname → mac → iface |
n / i | net / disk 图表模式 |
↑↓ PgUp PgDn / 滚轮 | 移动选中;PgUp/PgDn 按可视高度翻页;滚轮滚动光标下的列表;点击选中 |
| disks 滚动条 | 点轨道翻页、拖滑块滚动——无需聚焦 |
LAN 行上 enter | 置顶邻居 + CONNS 过滤到该对端 |
conns/procs 行上 enter | 详情面板(追踪 t/space,终止 k,重启 s,复制 y) |
z | 焦点盒子全屏缩放 |
Home/End/g/G | 跳到首行/末行 |
L | 监控日志开关 |
s | LAN 扫描开关(主屏;详情面板里 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_box | NET 盒边框 |
proc_box | LAN 盒边框(键名沿用 btop,保兼容) |
mem_box | DISK 盒边框(键名沿用 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。发现靠两个机制:
- 被动 —— 每次刷新都读内核邻居表(ARP/NDP),机器说 过话的设备立刻 出现,带着内核还记着的新鲜度。
- 主动 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 | 从本机哪块网卡可达 |
| Σ conns | CONNS 里指向这个对端的活跃连接数 |
| rate | 到这个对端的当前 rx+tx |
| Σ bytes | ltop 启动以来到这个对端的累计字节 |
流量列是重点: 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)。
- 源码构建需要带
bpftarget 的 clang;预编译 tarball 内含编译好的 对象。
数据干净靠什么
几道护栏保证长时间运行的计数不出脏数据:
- LRU map 自清理。 pid 和 socket map 都是
BPF_MAP_TYPE_LRU_HASH(各 16384 项): 空闲进程和关闭的 socket 自己被驱逐,几千进程的机器 也耗不尽 map。 - 实例 ID + 饱和差分。 每个助手实例(
flock单实例锁守护)给快照 打唯一 ID;TUI 发现 ID 变了就重新基线,差分用饱和运算——pid/socket 复用、守护进程带着旧文件重启,都变不出负数或垃圾值。 - 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 / --log | JSONL,每 log_interval_ms(默认 60 秒)一行 |
| 无头采集 | ltop watch | JSONL,每 --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)写入,手改安全(重启生效):
| 键 | 默认 | 含义 |
|---|---|---|
lang | en | 界面/消息语言;zh 切中文(JSON 键恒英文) |
layout | classic | 启动布局(classic/wide/tall) |
tick_ms | 1000 | 刷新间隔 |
graph_net / graph_disk | hybrid / centered | 默认图表样式 |
boxes | 全开 | 可见盒子 |
log_interval_ms | 60000 | 监控日志节奏 |
log_retention_days | 7 | 监控日志保留天数 |
log_tracked_only | false | 只记被追踪的进程 |
sweep / sweep_interval_s | true / 60 | LAN UDP knock 扫描开关与节奏 |
tombstone_ttl_ms | 5000 | 关闭连接在 CONNS 留多久 |
theme | omarchy | 主题名(见主题) |
theme_live_follow | false | 桌面主题变化时运行中的 ltop 跟着变色(同 --follow-theme) |
proc_expand_default | false | CONNS 进程组默认展开 |
proc_exit_retention_min | 30 | 退出进程账本 N 分钟后清除(0 = 永久) |
conn_filter / conn_sort / proc_sort / lan_sort | all / proc / net-sum / ip | 默认列表模式 |
allow_global_kill | false | 允许终止其他用户的进程 |
net_graph_coupled | false | NET 图表比例耦合:上下行悬殊时,小方向图按真实比例占图表高度,不再满幅放大 |
net_graph_scale_ratio | 5 | 上面的触发阈值,单位倍(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 LTS | 6.8 | ✓ 完整 | glibc 2.39 |
| Ubuntu 22.04 LTS | 5.15 | ✓ 完整 | 无 BTF 可跑; glibc 2.35 基线 |
| Ubuntu 24.04 LTS (aarch64) | 6.8 | ✓ 完整 | QEMU aarch64; 树莓派级硬件预期一致 |
| Debian 13 | 6.12 | ✓ 完整 | glibc 2.41 |
| Fedora 44 (Workstation live) | 6.19 | ✓ 完整 | SELinux enforcing: 零拒绝 |
| macOS 27(Apple Silicon,MacBook Air) | darwin 27 | n/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-observationentitlement 按 「责任进程归因 × 平台签名」双维度门控)。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/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.conf | 0644(仅界面偏好) |
| eBPF 快照 | /run/ltop/udp.json | 0644,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 与每一位主题创作者——见 主题 → 致谢。