wehub-resource-sync
b8ca3436aa
30 KiB
Note
本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
1. 用途
witr 旨在回答一个简单的问题：
为什么它在运行？
当系统上有某个东西在运行时——无论是进程、服务，还是绑定到端口的对象——总有一个原因。这个原因往往并不直接、不易察觉，或分散在多个层面，例如 supervisor、容器、服务或 shell。
现有工具（ps, top, lsof, ss, systemctl, docker ps）会暴露状态与元数据。它们展示的是_正在运行什么_，却让用户不得不在多个工具之间手动比对输出，自行推断_为什么_在运行。
witr 将这种因果关系明确呈现出来。
它会在一份易于阅读的单次输出或交互式 TUI 仪表盘中，说明正在运行的对象从何而来、如何被启动，以及当前是哪些系统链路让它得以存在。
2. 安装
witr 以单个静态二进制形式分发，支持 Linux、macOS、FreeBSD 和 Windows。
witr 还在多种操作系统与生态系统中独立打包与维护。打包状态的最新概览可在 Repology. 查看。请注意，由于独立的审查与验证流程，社区软件包可能会滞后于 GitHub 发布版本。
Tip
如果你使用软件包管理器（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）并校验 checksum。
- 将
witr.exe解压到%LocalAppData%\witr\bin。 - 将 bin 目录添加到你的用户
PATH。
2.2 软件包管理器
APT（Debian、Ubuntu 及衍生发行版） 
你可以从官方 Debian 与 Ubuntu 软件源（Ubuntu 26.04+、Debian sid 及更高版本）以及 Kali Linux、Devuan、Raspbian 等衍生发行版安装 witr：
sudo apt install witr
注意：通过 apt 分发的版本可能滞后于最新 GitHub 发布版本。如需最新功能，请使用安装脚本或其他安装方式。
Conda（macOS、Linux 与 Windows） 
你可以使用 conda, mamba, 或 pixi 在 macOS、Linux 和 Windows 上安装 witr：
conda install -c conda-forge witr
# alternatively using mamba
mamba install -c conda-forge witr
# alternatively using pixi
pixi global install witr
Arch Linux（AUR） 
在 Arch Linux 及衍生发行版上，可从 AUR 软件包: 安装：
yay -S witr-bin
# alternatively using paru
paru -S witr-bin
# or use your preferred AUR helper
FreeBSD Ports 
你可以从 FreshPorts port: 在 FreeBSD 上安装 witr：
pkg install witr
# or
pkg install sysutils/witr
或从 Ports 构建：
cd /usr/ports/sysutils/witr/
make install clean
Aqua (macOS, Linux & Windows) 
你可以使用 aqua: 安装 witr：
# Add package
aqua g -i pranshuparmar/witr
# Install package
aqua i pranshuparmar/witr
预编译软件包（deb、rpm、apk）
witr 为主要 Linux 发行版提供原生软件包。你可以从 GitHub 发布页. 下载最新的 .deb、.rpm 或 .apk 软件包。
-
使用
curl的通用下载命令：# Replace <package name with the actual package that you need> curl -LO https://github.com/pranshuparmar/witr/releases/latest/download/<package-name> -
Debian/Ubuntu (.deb):
sudo dpkg -i ./witr-*.deb # Or, using apt for dependency resolution: 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. Determine OS and Architecture
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m)
[ "$ARCH" = "x86_64" ] && ARCH="amd64"
[ "$ARCH" = "aarch64" ] && ARCH="arm64"
# 2. Download the binary
curl -fsSL "https://github.com/pranshuparmar/witr/releases/latest/download/witr-${OS}-${ARCH}" -o witr
# 3. Verify checksum (Optional)
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. Rename and install
chmod +x witr
sudo mkdir -p /usr/local/bin
sudo mv witr /usr/local/bin/witr
# 5. Install man page (Optional)
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. Determine Architecture
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 "Unsupported architecture: $($env:PROCESSOR_ARCHITECTURE)"
exit 1
}
# 2. Download the zip
Invoke-WebRequest -Uri "https://github.com/pranshuparmar/witr/releases/latest/download/$ZipName" -OutFile "witr.zip"
# 3. Extract the binary
Expand-Archive -Path "witr.zip" -DestinationPath "." -Force
# 4. Verify checksum (Optional)
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 "Checksum OK" } else { Write-Host "Checksum Mismatch" }
# 5. Install to local bin directory
$InstallDir = "$env:LocalAppData\witr\bin"
New-Item -ItemType Directory -Path $InstallDir -Force | Out-Null
Move-Item .\witr.exe $InstallDir\witr.exe -Force
# 6. Add to User Path (Persistent)
$UserPath = [Environment]::GetEnvironmentVariable("Path", "User")
if ($UserPath -notlike "*$InstallDir*") {
[Environment]::SetEnvironmentVariable("Path", "$UserPath;$InstallDir", "User")
$env:Path += ";$InstallDir"
Write-Host "Added to Path. You may need to restart PowerShell."
}
# 7. Cleanup
Remove-Item witr.zip
Remove-Item SHA256SUMS
2.4 免安装运行
Nix Flake
如果你使用 Nix，可以从源码构建 witr 并免安装运行：
nix run github:pranshuparmar/witr -- --help
2.5 其他操作
验证安装
witr --version
man witr
Shell 补全
witr 支持所有标志（flag）的 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
# To make it permanent:
witr completion fish > ~/.config/fish/completions/witr.fish
PowerShell
witr completion powershell | Out-String | Invoke-Expression
# To make it permanent, add the above line to your $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）。它提供一个实时的、基于终端的仪表盘，包含四个标签页，用于探索进程、端口、容器和文件锁。
主要特性：
- 进程标签页：实时、可排序、可筛选的所有运行进程列表，侧边面板显示高亮进程的祖先树。
- 端口标签页：打开/监听中的端口，侧边面板附带所属进程。使用
a在仅 LISTEN 与 ALL 之间切换。 - 容器标签页：在一个列表中汇总 Docker、Podman、nerdctl、K8s/crictl、Incus、LXC、LXD 和 FreeBSD jails 上所有运行中的容器——名称、镜像、状态、端口、命令，以及每个容器的详情视图（挂载、网络和 compose 项目元数据）。
- 锁标签页：系统级文件锁（Linux 上的 POSIX/FLOCK，macOS/FreeBSD 上基于 lsof）。按
a切换到“所有打开文件”模式，其中被锁定的条目会与所有值得关注的打开 fd 合并；在/中输入以在合并结果中搜索。 - 进程详情：深入查看进程，了解其完整祖先树、子进程、环境变量、工作目录、套接字、文件上下文等。
- 进程操作：直接从 UI 发送信号（Kill、Terminate、Pause、Resume）或 Renice 进程（仅 Unix）。
- 鼠标支持：使用鼠标导航、排序列和点击行。
- 自适应主题：颜色自动适配浅色和深色终端背景。
- 自动刷新：进程、端口、容器和锁列表按自适应节奏自动刷新（起始间隔 3 秒，负载高时退避）。
4. 标志与选项
-c, --container strings container(s) to look up (repeatable)
--env show environment variables for the process
-x, --exact use exact name matching (no substring search)
-f, --file strings file(s) held open by a process (repeatable)
-h, --help help for witr
-i, --interactive interactive mode (TUI)
--json show result as JSON
--no-color disable colorized output
-p, --pid strings pid(s) to look up (repeatable)
-o, --port strings port(s) to look up (repeatable)
-s, --short show only ancestry
-t, --tree show only ancestry as a tree
--verbose show extended process information
-v, --version version for witr
--warnings show only warnings
位置参数（不带标志）被视为进程或服务名称。可传入多个名称。默认情况下，名称匹配使用子串匹配（模糊搜索）。使用 --exact 仅匹配名称完全一致的进程。
所有目标标志（--pid、--port、--file、--container）可重复指定，也可彼此混用，并与位置名称参数混用。提供多个目标时，结果会按顺序显示，并带有带标签的分隔线。所有输出模式（standard、short、tree、JSON、env、warnings、verbose）均支持多个输入。
--container 标志会在 Docker、Podman、nerdctl、K8s/crictl、Incus、LXC、LXD 和 FreeBSD jails 中搜索，并匹配容器名称、镜像、命令以及 compose 项目/服务标签。
若未提供任何参数或相关标志（--pid、--port、--file、--container），或显式使用 --interactive 标志，则会启动 TUI。
5. 核心概念
witr 将 一切视为进程问题。
端口、服务、容器和命令最终都会映射到 PID。一旦确定 PID，witr 会构建一条因果链，解释 该 PID 为何存在。
其核心回答以下问题：
- 正在运行什么？
- 它是如何启动的？
- 是什么让它保持运行？
- 它属于什么上下文？
6. 示例输出
6.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)
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)
Sockets : 127.0.0.1:5001 (TCP | LISTENING)
6.2 简短输出
witr --port 5000 --short
systemd (pid 1) → PM2 v5.3.1: God (pid 1481580) → python (pid 1482060)
6.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 个）并高亮目标进程。
6.4 多个匹配
witr ng
Multiple matching processes found:
[1] nginx (pid 2311)
nginx -g daemon off;
[2] nginx (pid 24891)
nginx -g daemon off;
[3] ngrok (pid 14233)
ngrok http 5000
Re-run with:
witr --pid <pid>
要避免子串匹配、仅查找名称完全一致的进程，请使用 --exact 标志：
witr nginx -x
6.5 基于文件的查询
witr --file /var/lib/dpkg/lock
解释哪个进程正在占用该文件。
6.6 基于容器的查询
witr --container redis
在每个检测到的运行时（Docker、Podman、nerdctl、K8s/crictl、Incus、LXC、LXD、FreeBSD jails）中，按名称、镜像、命令或 compose 项目/服务查找容器。传入 --verbose 可在输出中包含挂载、网络和 compose 元数据。
6.7 多个输入
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）均支持多个输入。
7. 输出行为
7.1 输出原则
- 默认单屏显示（尽力而为）
- 确定性排序
- 叙述式说明
- 尽力检测，并明确标示不确定性
7.2 退出码
witr 返回有意义的退出码，供脚本、CI 流水线和监控使用：
| Code | Meaning |
|---|---|
| 0 | Clean：找到进程，无警告 |
| 1 | Warnings：找到进程，但有一个或多个警告 |
| 2 | Not found：未找到匹配的进程或服务 |
| 3 | Permission denied：权限不足 |
| 4 | Invalid input：参数无效或匹配歧义 |
| 5 | Internal error：发生意外故障 |
示例用法：
witr nginx --short
case $? in
0) echo "All clear" ;;
1) echo "Warnings detected" ;;
2) echo "Process not running" ;;
3) echo "Need elevated privileges" ;;
4) echo "Invalid input or ambiguous match" ;;
5) echo "Internal error" ;;
esac
7.3 标准输出章节
Target
用户查询的对象。
Process
可执行文件、PID、用户、命令、启动时间和重启次数。
Why It Exists
展示进程如何产生的因果祖先链。 这是 witr 的核心价值。
来源
负责启动或监管该进程的主要系统（尽力而为）。
示例：
- systemd 单元（含定时器触发服务的调度信息）（Linux）
- launchd 服务（含调度/触发详情）（macOS）
- SSH 会话（含远程 IP 与终端）
- docker 容器
- pm2
- cron
- 交互式 shell（可检测 tmux/screen 会话）
- Snap/Flatpak 沙箱（Linux）
仅会选择 一个主要来源。
上下文（尽力而为）
- 工作目录
- Git 仓库名称与分支
- 容器名称/镜像（docker、podman、kubernetes、colima、containerd）
- 公共绑定与私有绑定
警告
非阻塞性观察项，例如：
- 进程以 root 运行
- 非 root 进程具有危险的 Linux capabilities（CAP_SYS_ADMIN 等）
- 进程正在公共接口上监听（0.0.0.0 / ::）
- 多次重启（仅当超过阈值时警告）
- 进程占用大量内存（>1GB RSS）
- 进程已运行超过 90 天
- 已删除的二进制文件、库注入指标（LD_PRELOAD、DYLD_*）
8. 平台支持
- Linux（x86_64、arm64）— 完整功能支持（
/proc）。 - macOS（x86_64、arm64）— 使用
ps、lsof、sysctl、pgrep。 - Windows（x86_64、arm64）— 原生 Win32 API（ToolHelp32、PSAPI、Service Control Manager）。不依赖 PowerShell 或 WMI。
- FreeBSD（x86_64、arm64）— 使用
procstat、ps、lsof。
8.1 功能兼容性矩阵
| 功能 | Linux | macOS | Windows | FreeBSD | 说明 |
|---|---|---|---|---|---|
| 进程选择 | |||||
| 按名称 | ✅ | ✅ | ✅ | ✅ | |
| 按 PID | ✅ | ✅ | ✅ | ✅ | |
| 按端口 | ✅ | ✅ | ✅ | ✅ | |
| 按文件 | ✅ | ✅ | ✅ | ✅ | |
| 按容器 | ✅ | ✅ | ✅ | ✅ | 需要运行时 CLI 在 PATH 中（docker/podman/nerdctl/crictl/incus/lxc/lxc-ls/jls）。 |
| 多个/混合输入 | ✅ | ✅ | ✅ | ✅ | 可重复的标志、混合类型。 |
| 精确匹配 | ✅ | ✅ | ✅ | ✅ | |
| 完整命令行 | ✅ | ✅ | ✅ | ✅ | |
| 进程启动时间 | ✅ | ✅ | ✅ | ✅ | |
| 工作目录 | ✅ | ✅ | ✅ | ✅ | |
| 环境变量 | ✅ | ⚠️ | ⚠️ | ✅ | macOS：SIP 限制；Windows：受保护进程不可访问。 |
| 网络 | |||||
| 监听端口 | ✅ | ✅ | ✅ | ✅ | |
| 绑定地址 | ✅ | ✅ | ✅ | ✅ | |
| 端口 → PID 解析 | ✅ | ✅ | ✅ | ✅ | |
| 端口 → 容器回退 | ✅ | ✅ | ✅ | ✅ | 当端口由 PID 1 通过 systemd socket activation 或容器运行时占用时使用。 |
| 服务检测 | |||||
| 服务管理器 | ✅ | ✅ | ✅ | ✅ | 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、nerdctl、K8s（Kubepods/crictl）、Containerd。macOS/Linux 上的 Colima。Linux 上的 Incus/LXC/LXD。FreeBSD 上的 Jails。 |
| SSH 会话检测 | ✅ | ✅ | ✅ | ✅ | 检测远程 IP 与终端。 |
| tmux/screen 检测 | ✅ | ✅ | ❌ | ✅ | 在来源中显示会话名称。 |
| 调度检测 | ✅ | ✅ | ❌ | ❌ | Linux：systemd timers，macOS：launchd intervals/calendar。 |
| Snap/Flatpak 检测 | ✅ | ❌ | ❌ | ❌ | |
| 健康状态与诊断 | |||||
| CPU 使用率检测 | ✅ | ✅ | ✅ | ✅ | |
| 内存使用率检测 | ✅ | ✅ | ✅ | ✅ | |
| 健康状态检测 | ✅ | ✅ | ✅ | ✅ | |
| 打开的文件/句柄 | ✅ | ✅ | ⚠️ | ✅ | Windows：仅计数。 |
| 文件锁 | ✅ | ✅ | ❌ | ✅ | Linux：/proc/locks；macOS/FreeBSD：源自 lsof/fstat。 |
| 已删除二进制文件检测 | ✅ | ✅ | ✅ | ✅ | 若可执行文件缺失则发出警告。 |
| Capability 警告 | ✅ | ❌ | ❌ | ❌ | 对非 root 进程的危险 capabilities 发出警告。 |
| 上下文 | |||||
| Git 仓库/分支检测 | ✅ | ✅ | ✅ | ✅ | |
| 交互模式（TUI） | |||||
| 进程标签页 | ✅ | ✅ | ✅ | ✅ | |
| 端口标签页 | ✅ | ✅ | ✅ | ✅ | |
| 容器标签页 | ✅ | ✅ | ✅ | ✅ | |
| 锁标签页 | ✅ | ✅ | ❌ | ✅ | 切换（a）显示所有打开的文件。 |
| 进程详情 | ✅ | ✅ | ✅ | ✅ | |
| 进程操作 | ✅ | ✅ | ❌ | ✅ |
图例： ✅ 完整支持 | ⚠️ 部分/有限支持 | ❌ 不可用
8.2 权限说明
Linux/FreeBSD
witr 会检查系统目录，这可能需要提升权限。
若未看到预期信息，请尝试使用 sudo 运行 witr：
sudo witr [your arguments]
macOS
在 macOS 上，witr 使用 ps、lsof 和 launchctl 收集进程信息。某些操作可能需要提升权限：
sudo witr [your arguments]
注意：由于 macOS 系统完整性保护（System Integrity Protection，SIP），即使用 sudo 也可能无法访问某些系统进程详情。
Windows
在 Windows 上，witr 直接调用 Win32 API（ToolHelp32、PSAPI、Service Control Manager），而非启动 PowerShell 或 WMI，启动迅速且不会出现 Get-CimInstance 卡顿。要查看其他用户或系统服务所拥有的进程详情，必须以 Administrator 身份运行终端。
# Run in Administrator PowerShell
.\witr.exe [your arguments]
9. 成功标准
witr 在以下情况下算是成功：
- 用户能在数秒内回答「为什么它在运行？」
- 减少了对多种工具的依赖
- 在压力下输出仍易于理解
- 用户在事故处理期间信任它
10. 赞助商
特别感谢支持 witr 的朋友们 ❤️
