witr：进程溯源工具

witr 项目简介

witr 是一个跨平台命令行与终端交互式（TUI）诊断工具，专门用来回答一个看似简单却往往难以追溯的问题："这个进程为什么在运行？"。在系统中，几乎每个正在运行的进程、监听端口、容器或文件背后都隐藏着多层因果链——可能是 systemd 守护的某个服务、PM2 拉起的 Node 进程、Docker 容器里的命令，甚至是 tmux 终端发起的 shell。传统的 ps、lsof、ss、docker ps 等工具只能告诉你"什么在运行"，而 witr 则把这些线索串联起来，显式呈现"为什么在运行"。

核心特性

• 多目标查询：支持按名称、PID、端口、文件、容器查询；支持子串模糊匹配或 --exact 精确匹配。
• 因果链可视化：输出"为何存在（Why It Exists）"字段，展示从 init 系统（如 systemd）到目标进程的完整祖先链。
• 来源识别（Source）：自动识别 systemd unit、launchd plist、PM2、Docker、Cron、SSH 会话、tmux/screen、Snap/Flatpak 沙箱等。
• 上下文信息：包括工作目录、Git 仓库与分支、容器归属、监听地址等。
• 安全告警：非阻塞式警告，例如以 root 权限运行、危险 Linux 能力、监听公网接口、内存占用过高、二进制被删除等。
• 结构化输出：支持人类可读文本、--short（仅祖先后继）、--tree（带子进程的树形）、--json、--env、--warnings、--verbose 等多种模式。
• 交互式 TUI：无参数运行或显式使用 -i 启动，包含 Processes、Ports、Containers、Locks 四个标签页，支持鼠标、信号发送、Renice、自动刷新等。

安装方式

官方推荐使用一行脚本安装：

# Unix / Linux / macOS / FreeBSD
curl -fsSL https://raw.githubusercontent.com/pranshuparmar/witr/main/install.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/pranshuparmar/witr/main/install.ps1 | iex

此外，witr 已上架多个软件源与包管理器：APT（Debian sid / Ubuntu 26.04+）、Homebrew、MacPorts、Conda/Mamba/Pixi、AUR（witr-bin）、Winget、Chocolatey、Scoop、npm（@pranshuparmar/witr）、FreeBSD Ports、Nix Flake、GNU Guix、Aqua、Mise、Brioche、Uniget、AOSC OS 等。也可使用 Go 直接从源码安装：

go install github.com/pranshuparmar/witr/cmd/witr@latest

CLI 用法示例

# 按名称查询
witr node

# 按端口查询（仅显示祖先链）
witr --port 5000 --short

# 按 PID 查询并以树形显示（含子进程）
witr --pid 143895 --tree

# 查询持有某文件的进程
witr --file /var/lib/dpkg/lock

# 查询容器（跨 Docker、Podman、nerdctl、crictl、Incus、LXC 等）
witr --container redis

# 精确匹配、避免子串歧义
witr nginx -x

# 多种目标混合查询，结果按顺序输出
witr nginx --port 5432 --pid 1234

# 以 JSON 输出，便于脚本消费
witr --pid 1234 --json

输出结构

单条结果默认包含以下字段：

• Target：用户查询的目标。
• Process：可执行文件名、PID、用户、命令行、启动时间。
• Why It Exists：因果祖先后继链（核心价值）。
• Source：负责启动或监管的主要系统组件。
• Context：工作目录、Git 信息、容器归属等。
• Warnings：非阻塞告警。

退出码

平台支持

• Linux（x86_64、arm64）：完整支持，基于 /proc。
• macOS（x86_64、arm64）：使用 ps、lsof、sysctl、pgrep；受 SIP 限制的环境变量部分受限。
• Windows（x86_64、arm64）：直接调用 Win32 API（ToolHelp32、PSAPI、服务控制管理器），不依赖 PowerShell 与 WMI。
• FreeBSD（x86_64、arm64）：使用 procstat、ps、lsof。

各平台对容器运行时、tmux/screen 检测、计划任务、Snap/Flatpak、文件锁等能力的覆盖差异，可参考特性兼容性矩阵。

权限说明

Linux/FreeBSD 与 macOS 在查询系统级信息时可能需要 sudo；macOS 还受 SIP 影响，部分系统进程信息即便使用 sudo 也无法获取。Windows 下 witr 直接调用原生 Win32 API，规避了 PowerShell 与 WMI 依赖。

其他操作

• 验证安装：witr --version 与 man witr。
• 启用 shell 补全（Bash/Zsh/Fish/PowerShell）。
• 通过各包管理器对应命令卸载，或手动删除 /usr/local/bin/witr 与 man 页面。