witr 详细部署教程：一站式溯源进程、端口与容器 | 极客的赛博空间

witr (Why is this running?) 是一个强大的系统诊断工具，旨在回答一个核心问题：“这东西为什么在运行？”。它通过一个命令，就能清晰地展示进程、端口、容器或文件的完整因果链（从何而来、如何启动、由谁维持），无需再手动组合 ps、lsof、systemctl 等多个工具。本教程将指导您在主要操作系统上完成部署。

1. 系统要求

witr 是一个单一静态二进制文件，无需额外运行时环境，支持以下平台：

Linux (x86_64, arm64)
macOS (x86_64, arm64)
Windows (x86_64, arm64)
FreeBSD (x86_64, arm64)

注意：部分高级功能（如查看所有进程、端口）在 Linux/FreeBSD 上可能需要 sudo 权限，在 Windows 上则需要以管理员身份运行终端。

2. 安装方法

witr 提供了多种安装方式，您可以根据偏好选择最方便的一种。

2.1 快速安装脚本（推荐）

这是最快、最通用的方式，适合所有主流系统。

Unix 系统 (Linux, macOS, FreeBSD)

打开终端，执行以下命令：

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

脚本会自动检测系统架构，下载最新二进制文件，并将其安装到 /usr/local/bin/witr，同时安装手册页。

Windows 系统 (PowerShell)

以管理员身份打开 PowerShell，执行：

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

脚本会下载 witr.exe 到 %LocalAppData%\witr\bin，并自动将该路径添加到用户 PATH 环境变量中。安装完成后，可能需要重启终端才能生效。

2.2 使用系统包管理器

如果您更喜欢使用系统的包管理器，witr 已被许多主流仓库收录。

操作系统	包管理器	安装命令
Debian/Ubuntu	APT	`sudo apt install witr`
macOS/Linux	Homebrew	`brew install witr`
macOS	MacPorts	`sudo port install witr`
macOS/Linux/Windows	Conda	`conda install -c conda-forge witr`
Arch Linux	AUR (yay)	`yay -S witr-bin`
Windows	Winget	`winget install -e --id PranshuParmar.witr`
Windows	Chocolatey	`choco install witr`
Windows	Scoop	`scoop install main/witr`
FreeBSD	pkg	`pkg install witr`
跨平台	npm	`npm install -g @pranshuparmar/witr`

注意：通过包管理器安装的版本可能略滞后于 GitHub 最新版，但稳定性更高。

2.3 手动安装（适用于无包管理器环境）

如果上述方法均不可用，可以手动下载二进制文件。

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. 添加执行权限并移动到 PATH
chmod +x witr
sudo mv witr /usr/local/bin/witr

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" }

# 2. 下载并解压
Invoke-WebRequest -Uri "https://github.com/pranshuparmar/witr/releases/latest/download/$ZipName" -OutFile "witr.zip"
Expand-Archive -Path "witr.zip" -DestinationPath "." -Force

# 3. 移动到用户目录并添加 PATH
$InstallDir = "$env:LocalAppData\witr\bin"
New-Item -ItemType Directory -Path $InstallDir -Force | Out-Null
Move-Item .\witr.exe $InstallDir\witr.exe -Force

# 4. 将安装目录添加到用户 PATH（需要重启终端生效）
[Environment]::SetEnvironmentVariable("Path", "$env:Path;$InstallDir", "User")

2.4 验证与配置

安装完成后，运行以下命令验证是否成功：

1	witr --version

如果显示版本号，则说明安装成功。

为了使用更方便，可以启用 Shell 自动补全（以 Bash 为例）：

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

3. 快速上手与使用示例

3.1 基础查询：追踪进程

1 2	# 查询名为 "node" 的所有进程 witr node

输出示例：

Target      : node
Process     : node (pid 14233)
User        : pm2
Command     : node index.js
Started     : 2 days ago
Why It Exists :
  systemd (pid 1) → pm2 (pid 5034) → node (pid 14233)
Source      : pm2

这个输出清晰地展示了 node 进程是由 pm2 通过 systemd 启动的完整链条。

3.2 按端口查询

1 2	# 查询占用端口 5000 的进程及其来源 witr --port 5000

3.3 简洁模式输出

1 2	# 只显示因果链，不显示其他细节（适合脚本或快速排查） witr --port 5000 --short

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

3.4 查询容器

1 2	# 查询名为 "redis" 的容器信息（自动检测 Docker/Podman/Incus 等运行时） witr --container redis

3.5 混合查询

可以同时查询多个目标：

1	witr nginx --port 5432 --pid 1234

结果会按您输入的顺序分块显示。

3.6 使用 JSON 格式输出

便于脚本解析和处理：

1	witr node --json \| jq .

4. 交互式 TUI 模式

直接运行 witr 或不带任何参数，即可启动一个终端仪表盘 (TUI)：

1
2
3

witr
# 或显式指定
witr -i

在 TUI 中，您可以通过键盘或鼠标切换四个标签页：

Processes (进程)：实时列表，可排序、过滤，选中后右侧显示完整进程树。
Ports (端口)：显示监听端口及其所属进程。
Containers (容器)：统一显示 Docker、Podman 等所有运行中容器。
Locks (锁)：显示系统范围的文件锁，按 a 可切换为“所有打开的文件”。

快捷键：

↑/↓ 或鼠标：选择项目。
/：在当前列表中搜索。
在进程详情页，可按 k (Kill) 或 t (Terminate) 发送信号。

5. 卸载方法

如果需要卸载 witr：

通过包管理器安装的：使用对应命令，如 brew uninstall witr。
通过脚本或手动安装的：
- Unix：sudo rm -f /usr/local/bin/witr
- Windows：Remove-Item -Recurse -Force "$env:LocalAppData\witr"

6. 常见问题排查

问题	可能原因	解决方案
`witr: command not found`	安装目录未在 PATH 中	1. 确认安装路径。2. 重启终端。3. 手动将安装目录添加到 `PATH`。
查询不到进程/端口信息	权限不足	在命令前加 `sudo` (Unix) 或以管理员身份运行终端 (Windows)。
macOS 上某些系统进程不可见	系统完整性保护 (SIP) 限制	这是系统安全机制，无法绕过，不影响对普通用户进程的查询。
TUI 界面显示异常	终端不支持或字体问题	请使用支持真彩色和 Unicode 的现代终端（如 iTerm2, Windows Terminal）。