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 已被许多主流仓库收录。

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

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

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

Unix 系统 (Linux, macOS, FreeBSD)

1
2
3
4
5
6
7
8
9
10
11
12

# 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
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# 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

输出示例：

1
2
3
4
5
6
7
8

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 中，您可以通过键盘或鼠标切换四个标签页：

1. Processes (进程)：实时列表，可排序、过滤，选中后右侧显示完整进程树。
2. Ports (端口)：显示监听端口及其所属进程。
3. Containers (容器)：统一显示 Docker、Podman 等所有运行中容器。
4. 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. 常见问题排查

7. 总结

witr 是一个解决系统运维和开发中“溯源”痛点的利器。通过本教程，您应该已经成功安装了它。其核心价值在于将复杂的进程关系（PID、服务、容器、端口）归结为一条简单、明确的因果链，极大地提高了问题排查效率。

部署完成后，建议您立即尝试 witr [您关心的进程名]，体验其强大的溯源能力。