pranshuparmar/witr

来源：https://github.com/pranshuparmar/witr

witr

为什么这个在运行？

附 交互式 TUI 模式 ✨

Go 版本（https://github.com/pranshuparmar/witr/blob/main/go.mod） Go 报告卡（https://goreportcard.com/report/github.com/pranshuparmar/witr） 发布（https://github.com/pranshuparmar/witr/actions/workflows/release.yml）支持的平台 最新发布（https://github.com/pranshuparmar/witr/releases/latest） 包管理器（https://repology.org/project/witr/versions）

📖 阅读 witr 背后故事（https://medium.com/@pranshu.parmar/witr-why-is-this-running-a9a97cbedd18）

---

目的 • 安装 • ✨ TUI • 标志 • 示例 • 平台 目标 • 核心概念 • 输出行为 • 成功标准 • 赞助方

---

1. 目的

witr 的存在是为了回答一个简单的问题：

为什么这个在运行？

当系统上有一个进程、服务或绑定在端口上的东西在运行时，总有其原因。这个原因往往不是直接的，不是显而易见的，或者分散在多个层面（如超级守护进程、容器、服务或 shell）中。现有工具（ps、top、lsof、ss、systemctl、docker ps）只展示状态和元数据。它们显示 什么 在运行，但留给用户通过手动关联多个工具的输出结果去推断 为什么。

witr 使这种因果关系变得明确。它通过单一的、人类可读的输出或 交互式 TUI 仪表盘，解释某个正在运行的东西来自哪里、它是如何启动的、以及哪些系统链对其当前的存在负责。

---

2. 安装

witr 以单个静态二进制文件的形式分发，支持 Linux、macOS、FreeBSD 和 Windows。

witr 也在多个操作系统和生态系统中独立打包和维护。关于打包状态的最新概览，请参阅 Repology（https://repology.org/project/witr/versions）。请注意，由于独立的审核与验证，社区包的版本可能落后于 GitHub 发布版。

如果你使用包管理器（Homebrew、Conda、Winget 等），建议通过它安装以便于更新。否则，安装脚本是快速上手的方式。

---

2.1 快速安装

Unix（Linux、macOS 和 FreeBSD）

curl -fsSL https://raw.githubusercontent.com/pranshuparmar/witr/main/install.sh | bash

脚本说明： 脚本将完成以下操作：

• 检测你的操作系统（linux、darwin 或 freebsd）
• 检测你的 CPU 架构（amd64 或 arm64）
• 下载最新的发布版二进制文件和 man 手册页
• 安装到 /usr/local/bin/witr
• 安装 man 手册页到 /usr/local/share/man/man1/witr.1
• 可通过 INSTALL_PREFIX 环境变量覆盖默认安装路径

Windows（PowerShell）

irm https://raw.githubusercontent.com/pranshuparmar/witr/main/install.ps1 | iex

脚本说明： 脚本将完成以下操作：

• 下载最新发布版（zip）并验证校验和。
• 将 witr.exe 解压到 %LocalAppData%\witr\bin。
• 将 bin 目录添加到当前用户的 PATH 环境变量。

---

2.2 包管理器

Homebrew（macOS 和 Linux） 你可以使用 Homebrew（https://brew.sh/）在 macOS 或 Linux 上安装 witr：

brew install witr

Conda（macOS、Linux 和 Windows） 你可以使用 conda（https://docs.conda.io/en/latest/）、mamba（https://mamba.readthedocs.io/en/latest/）或 pixi（https://pixi.prefix.dev/latest/）在 macOS、Linux 和 Windows 上安装 witr：

conda install -c conda-forge witr
# 或者使用 mamba
mamba install -c conda-forge witr
# 或者使用 pixi
pixi global install witr

Arch Linux（AUR） 在 Arch Linux 及其衍生版本上，从 AUR 包（https://aur.archlinux.org/packages/witr-bin）安装：

yay -S witr-bin
# 或者使用 paru
paru -S witr-bin
# 或者使用你喜欢的 AUR 助手

Winget（Windows） 你可以通过 winget（https://learn.microsoft.com/en-us/windows/package-manager/winget/）安装 witr：

winget install -e --id PranshuParmar.witr

NPM（跨平台） 你可以使用 npm（https://www.npmjs.com/package/@pranshuparmar/witr）安装 witr：

npm install -g @pranshuparmar/witr

FreeBSD Ports 你可以在 FreeBSD 上从 FreshPorts port（https://www.freshports.org/sysutils/witr/)）安装 witr：

pkg install witr
# 或
pkg install sysutils/witr

或者从 Ports 编译：

cd /usr/ports/sysutils/witr/
make install clean

Chocolatey（Windows） 你可以使用 Chocolatey（https://community.chocolatey.org）安装 witr：

choco install witr

Scoop（Windows） 你可以使用 Scoop（https://scoop.sh）安装 witr：

scoop install main/witr

AOSC OS 你可以从 AOSC OS 仓库（https://packages.aosc.io/packages/witr）安装 witr：

oma install witr

GNU Guix 你可以从 GNU Guix 仓库（https://packages.guix.gnu.org/packages/witr/）安装 witr：

guix install witr

Uniget（Linux） 你可以使用 uniget（https://uniget.dev/）安装 witr：

uniget install witr

Aqua（macOS、Linux 和 Windows） 你可以使用 aqua（https://aquaproj.github.io/）安装 witr：

# 添加包
aqua g -i pranshuparmar/witr
# 安装包
aqua i pranshuparmar/witr

Brioche（Linux） 你可以使用 brioche（https://brioche.dev/）安装 witr：

brioche install -r witr

预构建包（deb、rpm、apk） witr 为主要的 Linux 发行版提供原生包。你可以从 GitHub 发布页面（https://github.com/pranshuparmar/witr/releases/latest）下载最新的 .deb、.rpm 或 .apk 包。

• 使用 curl 的通用下载命令：

# 替换为对应的文件名
curl -LO https://github.com/pranshuparmar/witr/releases/latest/download/

• Debian/Ubuntu (.deb)：

sudo dpkg -i ./witr-*.deb
# 或者，使用 apt 解决依赖：
sudo apt install ./witr-*.deb

• Fedora/RHEL/CentOS (.rpm)：

sudo rpm -i ./witr-*.rpm

• Alpine Linux (.apk)：

sudo apk add --allow-untrusted ./witr-*.apk

---

2.3 源码和手动安装

Go（跨平台） 你可以直接从源码安装最新版本：

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

这会安装 witr 二进制文件到你的 $GOPATH/bin 或 $HOME/go/bin 目录。请确保该目录在 PATH 中。

手动安装 如果你更喜欢手动安装，请按以下简单步骤操作：

Unix（Linux、macOS、FreeBSD）

# 1. 确定操作系统和架构
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m)
[ "$ARCH" = "x86_64" ] && ARCH="amd64"
[ "$ARCH" = "aarch64" ] && ARCH="arm64"

# 2. 下载二进制文件
curl -fsSL "https://github.com/pranshuparmar/witr/releases/latest/download/witr-${OS}-${ARCH}" -o witr

# 3. 验证校验和（可选）
curl -fsSL "https://github.com/pranshuparmar/witr/releases/latest/download/SHA256SUMS" -o SHA256SUMS
grep "witr-${OS}-${ARCH}" SHA256SUMS | (sha256sum -c - 2>/dev/null || shasum -a 256 -c - 2>/dev/null)
rm SHA256SUMS

# 4. 重命名并安装
chmod +x witr
sudo mkdir -p /usr/local/bin
sudo mv witr /usr/local/bin/witr

# 5. 安装 man 手册页（可选）
sudo mkdir -p /usr/local/share/man/man1
sudo curl -fsSL https://github.com/pranshuparmar/witr/releases/latest/download/witr.1 -o /usr/local/share/man/man1/witr.1

Windows（PowerShell）

# 1. 确定架构
if ($env:PROCESSOR_ARCHITECTURE -eq "AMD64") {
    $ZipName = "witr-windows-amd64.zip"
} elseif ($env:PROCESSOR_ARCHITECTURE -eq "ARM64") {
    $ZipName = "witr-windows-arm64.zip"
} else {
    Write-Error "不支持的架构：$($env:PROCESSOR_ARCHITECTURE)"
    exit 1
}

# 2. 下载 zip 文件
Invoke-WebRequest -Uri "https://github.com/pranshuparmar/witr/releases/latest/download/$ZipName" -OutFile "witr.zip"

# 3. 解压二进制文件
Expand-Archive -Path "witr.zip" -DestinationPath "." -Force

# 4. 验证校验和（可选）
Invoke-WebRequest -Uri "https://github.com/pranshuparmar/witr/releases/latest/download/SHA256SUMS" -OutFile "SHA256SUMS"
$hash = Get-FileHash -Algorithm SHA256 .\witr.zip
$expected = Select-String -Path .\SHA256SUMS -Pattern $ZipName
if ($expected -and $hash.Hash.ToLower() -eq $expected.Line.Split(' ')[0]) {
    Write-Host "校验和正确"
} else {
    Write-Host "校验和不匹配"
}

# 5. 安装到本地 bin 目录
$InstallDir = "$env:LocalAppData\witr\bin"
New-Item -ItemType Directory -Path $InstallDir -Force | Out-Null
Move-Item .\witr.exe $InstallDir\witr.exe -Force

# 6. 添加到用户 PATH（持久化）
$UserPath = [Environment]::GetEnvironmentVariable("Path", "User")
if ($UserPath -notlike "*$InstallDir*") {
    [Environment]::SetEnvironmentVariable("Path", "$UserPath;$InstallDir", "User")
    $env:Path += ";$InstallDir"
    Write-Host "已添加至 Path。可能需要重启 PowerShell。"
}

# 7. 清理
Remove-Item witr.zip
Remove-Item SHA256SUMS

---

2.4 无需安装直接运行

Nix Flake 如果你使用 Nix，可以从源码构建 witr 并直接运行（无需安装）：

nix run github:pranshuparmar/witr -- --help

Pixi 如果你使用 pixi（https://pixi.prefix.dev/latest/），可以在 Linux 或 macOS 上直接运行（无需安装）：

pixi exec witr --help

---

2.5 其他操作

验证安装

witr --version
man witr

Shell 补全 witr 支持所有标志的 Tab 补全。要启用它，请在 shell 配置文件中添加相应行：

Bash

echo 'eval "$(witr completion bash)"' >> ~/.bashrc
source ~/.bashrc

Zsh

echo 'eval "$(witr completion zsh)"' >> ~/.zshrc
source ~/.zshrc

Fish

witr completion fish | source
# 持久化：
witr completion fish > ~/.config/fish/completions/witr.fish

PowerShell

witr completion powershell | Out-String | Invoke-Expression
# 持久化：将上面这行添加到 $PROFILE

卸载 如果你通过包管理器（Homebrew、Conda 等）安装，请使用相应的卸载命令（例如 brew uninstall witr）。

要完全删除通过脚本/手动安装的 witr：

Unix（Linux、macOS、FreeBSD）

sudo rm -f /usr/local/bin/witr
sudo rm -f /usr/local/share/man/man1/witr.1

Windows

Remove-Item -Recurse -Force "$env:LocalAppData\witr"

---

3. 交互模式（TUI）

不加任何参数运行 witr 或使用 -i 标志可以启动交互模式（TUI）。这提供了一个实时、基于终端的仪表盘，用于探索进程和端口。

主要功能：

• 实时进程列表：所有运行中进程的实时视图，支持排序和过滤。
• 端口视图：查看打开的端口，并立即看到哪些进程占用了它们。
• 进程详情：深入查看某个进程，显示其完整的祖先进程树、子进程、环境变量、工作目录等。
• 进程操作：直接在界面中向进程发送信号（杀死、终止、暂停、恢复）或调整其优先级（Renice）。
• 鼠标支持：可以使用鼠标导航、排序列和点击行。

---

4. 标志与选项

--env              显示进程的环境变量
-x, --exact        使用精确名称匹配（不进行子串搜索）
-f, --file strings 查找持有指定文件路径的进程（可重复）
-h, --help         显示 witr 帮助信息
-i, --interactive  交互模式（TUI）
--json             以 JSON 格式显示结果
--no-color         禁用彩色输出
-p, --pid strings  查找指定 PID 的进程（可重复）
-o, --port strings 查找指定端口的进程（可重复）
-s, --short        仅显示祖先进程链
-t, --tree         仅以树形显示祖先进程
--verbose          显示扩展的进程信息
-v, --version      显示 witr 版本
--warnings         仅显示警告

不提供标志的位置参数被视为进程名或服务名。可以传递多个名称。默认情况下，名称匹配使用子串匹配（模糊搜索）。使用 --exact 只匹配确切名称的进程。

所有目标标志（--pid、--port、--file）都可重复使用，并且可以彼此混合使用，也可以与位置名称参数混合使用。当提供多个目标时，结果会依次显示，并带有标示分隔符。

所有输出模式（标准、short、tree、JSON、env、warnings、verbose）都适用于多个输入。

如果没有提供任何参数或相关标志（--pid、--port、--file），或显式使用了 --interactive 标志，则会启动 TUI。

---

5. 示例输出

5.1 基于名称的查询

witr node

Target      : node
Process     : node (pid 14233)
User        : pm2
Command     : node index.js
Started     : 2 days ago (Mon 2025-02-02 11:42:10 +05:30)
Restarts    : 1
Why It Exists : systemd (pid 1) → pm2 (pid 5034) → node (pid 14233)
Source      : pm2
Working Dir : /opt/apps/expense-manager
Git Repo    : expense-manager (main)
Listening   : 127.0.0.1:5001

---

5.2 简短输出

witr --port 5000 --short

systemd (pid 1) → PM2 v5.3.1: God (pid 1481580) → python (pid 1482060)

---

5.3 树形输出

witr --pid 143895 --tree

systemd (pid 1)
└─ init-systemd(Ub (pid 2)
    └─ SessionLeader (pid 143858)
        └─ Relay(143860) (pid 143859)
            └─ bash (pid 143860)
                └─ sh (pid 143886)
                    └─ node (pid 143895)
                        ├─ node (pid 143930)
                        ├─ node (pid 144189)
                        └─ node (pid 144234)

注意：树形视图包含子进程（最多 10 个）并高亮目标进程。

---

5.4 多个匹配结果

witr ng

多个匹配的进程：
[1] nginx (pid 2311) nginx -g daemon off;
[2] nginx (pid 24891) nginx -g daemon off;
[3] ngrok (pid 14233) ngrok http 5000
重新运行：witr --pid <pid>

要避免子串匹配，只查找确切名称的进程，请使用 --exact 标志：

witr nginx -x

---

5.5 基于文件的查询

witr --file /var/lib/dpkg/lock

解释持有该文件的进程。

---

5.6 多个输入

witr nginx --port 5432 --pid 1234

----- [name: nginx] -----
Target        : nginx
Process       : nginx (pid 2311)
...

----- [port: 5432] -----
Target        : postgres
Process       : postgres (pid 891)
...

----- [pid: 1234] -----
Target        : node
Process       : node (pid 1234)
...

所有目标标志都可重复且可混合。结果按你输入的先后顺序显示。所有输出模式（--short、--tree、--json、--env、--warnings、--verbose）都适用于多个输入。

---

6. 平台支持

• Linux（x86_64、arm64） - 完全功能支持（/proc）。
• macOS（x86_64、arm64） - 使用 ps、lsof、sysctl、pgrep。
• Windows（x86_64、arm64） - 使用 Get-CimInstance、tasklist、netstat。
• FreeBSD（x86_64、arm64） - 使用 procstat、ps、lsof。

---

5.1 功能兼容性矩阵

功能	Linux	macOS	Windows	FreeBSD	说明
进程选择
按名称	✅	✅	✅	✅
按 PID	✅	✅	✅	✅
按端口	✅	✅	✅	✅
按文件	✅	✅	❌	✅
多个/混合输入	✅	✅	✅	✅	可重复标志，混合类型。
精确匹配	✅	✅	✅	✅
完整命令行	✅	✅	✅	✅
进程启动时间	✅	✅	✅	✅
工作目录	✅	✅	✅	✅
环境变量	✅	⚠️	❌	✅	macOS：由于 SIP 限制，部分支持。
网络
监听端口	✅	✅	✅	✅
绑定地址	✅	✅	✅	✅
端口 → PID 解析	✅	✅	✅	✅
服务检测
服务管理器	✅	✅	✅	✅	Linux：systemd，macOS：launchd，Windows：Services，FreeBSD：rc.d
服务描述	✅	✅	✅	✅	Linux：Description，macOS：Comment，Windows：Display Name，FreeBSD：rc 头部
配置来源	✅	✅	✅	✅	Linux：Unit File，macOS：Plist，Windows：Registry Key，FreeBSD：Rc Script
超级守护进程	✅	✅	✅	✅
容器	✅	✅	✅	✅	Docker（含 Compose 映射）、Podman、K8s