pranshuparmar--witr/README.md

<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。  
> [English](./README.en.md) · [原始项目](https://github.com/pranshuparmar/witr) · [上游 README](https://github.com/pranshuparmar/witr/blob/HEAD/README.md)  
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

<div align="center">

# witr

### 为什么它在运行？
*搭配* [**交互式 TUI 模式**](#3-interactive-mode-tui) ✨

[![Go Version](https://img.shields.io/github/go-mod/go-version/pranshuparmar/witr?style=flat-square)](https://github.com/pranshuparmar/witr/blob/main/go.mod) [![CodeFactor](https://www.codefactor.io/repository/github/pranshuparmar/witr/badge?style=flat-square)](https://www.codefactor.io/repository/github/pranshuparmar/witr) [![Release](https://img.shields.io/github/actions/workflow/status/pranshuparmar/witr/release.yml?style=flat-square)](https://github.com/pranshuparmar/witr/actions/workflows/release.yml) [![Platforms](https://img.shields.io/badge/platforms-linux%20%7C%20macos%20%7C%20windows%20%7C%20freebsd-blue?style=flat-square)](#8-platform-support) <br>
[![Latest Release](https://img.shields.io/github/v/release/pranshuparmar/witr?label=Latest%20Release&style=flat-square)](https://github.com/pranshuparmar/witr/releases/latest) [![Package Managers](https://img.shields.io/badge/Package%20Managers-brew%20|%20conda%20|%20aur%20|%20winget%20|%20npm%20|%20ports%20|%20...%20-blue?style=flat-square)](https://repology.org/project/witr/versions)

📖 阅读 witr 背后的 [故事](https://medium.com/@pranshu.parmar/witr-why-is-this-running-a9a97cbedd18)

<img width="1232" height="693" alt="witr_banner" src="https://github.com/user-attachments/assets/e9c19ef0-1391-4a5f-a015-f4003d3697a9" />

</div>

---

<div align="center">

[**用途**](#1-purpose) • [**安装**](#2-installation) • [**TUI**](#3-interactive-mode-tui) • [**标志与选项**](#4-flags--options) • [**核心概念**](#5-core-concept) • [**示例**](#6-example-outputs)
<br>
[**输出行为**](#7-output-behavior) • [**平台**](#8-platform-support) • [**成功标准**](#9-success-criteria) • [**赞助商**](#10-sponsors)

</div>

---

## 1. 用途

**witr** 旨在回答一个简单的问题：

> **为什么它在运行？**

当系统上有某个东西在运行时——无论是进程、服务，还是绑定到端口的对象——总有一个原因。这个原因往往并不直接、不易察觉，或分散在多个层面，例如 supervisor、容器、服务或 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 发布版本。

> [!TIP]
> 如果你使用软件包管理器（Homebrew、Conda、Winget 等），建议通过它们安装，以便更易更新。否则，安装脚本是最快的入门方式。

---

### 2.1 快速安装

#### Unix（Linux、macOS 与 FreeBSD）

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

<details>
<summary>脚本详情</summary>

该脚本将：
- 检测你的操作系统（`linux`、`darwin` 或 `freebsd`）
- 检测你的 CPU 架构（`amd64` 或 `arm64`）
- 下载最新发布的二进制文件与 man 页面
- 安装到 `/usr/local/bin/witr`
- 将 man 页面安装到 `/usr/local/share/man/man1/witr.1`
- 传入 INSTALL_PREFIX 以覆盖默认安装路径

</details>

#### Windows（PowerShell）

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

<details>
<summary>脚本详情</summary>

该脚本将：
- 下载最新发布版本（zip）并校验 checksum。
- 将 `witr.exe` 解压到 `%LocalAppData%\witr\bin`。
- 将 bin 目录添加到你的用户 `PATH`。

</details>

---

### 2.2 软件包管理器

<details>
<summary><strong>APT（Debian、Ubuntu 及衍生发行版）</strong> <a href="https://packages.debian.org/sid/witr"><img src="https://repology.org/badge/version-for-repo/debian_unstable/witr.svg?style=flat-square" alt="Debian"></a></summary>
<br>


你可以从官方 Debian 与 Ubuntu 软件源（Ubuntu 26.04+、Debian sid 及更高版本）以及 Kali Linux、Devuan、Raspbian 等衍生发行版安装 **witr**：

```bash
sudo apt install witr
```

> 注意：通过 apt 分发的版本可能滞后于最新 GitHub 发布版本。如需最新功能，请使用安装脚本或其他安装方式。
</details>

<details>
<summary><strong>Homebrew（macOS 与 Linux）</strong> <a href="https://formulae.brew.sh/formula/witr"><img src="https://img.shields.io/homebrew/v/witr?style=flat-square" alt="Homebrew"></a></summary>
<br>


你可以使用 [Homebrew](https://brew.sh/) 在 macOS 或 Linux 上安装 **witr**：

```bash
brew install witr
```
</details>

<details>
<summary><strong>MacPorts（macOS）</strong> <a href="https://ports.macports.org/port/witr/"><img src="https://repology.org/badge/version-for-repo/macports/witr.svg?style=flat-square" alt="MacPorts"></a></summary>
<br>


你可以使用 [MacPorts](https://www.macports.org/) 在 macOS 上安装 **witr**：

```bash
sudo port install witr
```
</details>

<details>
<summary><strong>Conda（macOS、Linux 与 Windows）</strong> <a href="https://anaconda.org/conda-forge/witr"><img src="https://img.shields.io/conda/vn/conda-forge/witr?style=flat-square" alt="Conda"></a></summary>
<br>


你可以使用 [conda](https://docs.conda.io/en/latest/), [mamba](https://mamba.readthedocs.io/en/latest/), 或 [pixi](https://pixi.prefix.dev/latest/) 在 macOS、Linux 和 Windows 上安装 **witr**：

```bash
conda install -c conda-forge witr
# alternatively using mamba
mamba install -c conda-forge witr
# alternatively using pixi
pixi global install witr
```
</details>

<details>
<summary><strong>Arch Linux（AUR）</strong> <a href="https://aur.archlinux.org/packages/witr-bin"><img src="https://img.shields.io/aur/version/witr-bin?style=flat-square" alt="AUR"></a></summary>
<br>


在 Arch Linux 及衍生发行版上，可从 [AUR 软件包](https://aur.archlinux.org/packages/witr-bin): 安装：

```bash
yay -S witr-bin
# alternatively using paru
paru -S witr-bin
# or use your preferred AUR helper
```
</details>

<details>
<summary><strong>Winget（Windows）</strong> <a href="https://winstall.app/apps/PranshuParmar.witr"><img src="https://img.shields.io/winget/v/PranshuParmar.witr?style=flat-square" alt="Winget"></a></summary>
<br>


你可以通过 [winget](https://learn.microsoft.com/en-us/windows/package-manager/winget/): 安装 **witr**：

```powershell
winget install -e --id PranshuParmar.witr
```
</details>

<details>
<summary><strong>NPM（跨平台）</strong> <a href="https://www.npmjs.com/package/@pranshuparmar/witr"><img src="https://img.shields.io/npm/v/@pranshuparmar/witr?label=npm&color=blue&style=flat-square" alt="NPM"></a></summary>
<br>

你可以使用 [npm](https://www.npmjs.com/package/@pranshuparmar/witr): 安装 **witr**：

```bash
npm install -g @pranshuparmar/witr
```
</details>

<details>
<summary><strong>FreeBSD Ports</strong> <a href="https://www.freshports.org/sysutils/witr/"><img src="https://repology.org/badge/version-for-repo/freebsd/witr.svg?style=flat-square" alt="FreeBSD Port"></a></summary>
<br>


你可以从 [FreshPorts port](https://www.freshports.org/sysutils/witr/): 在 FreeBSD 上安装 **witr**：

```bash
pkg install witr
# or
pkg install sysutils/witr
```

或从 Ports 构建：

```bash
cd /usr/ports/sysutils/witr/
make install clean
```
</details>

<details>
<summary><strong>Chocolatey（Windows）</strong> <a href="https://community.chocolatey.org/packages/witr"><img src="https://img.shields.io/chocolatey/v/witr?style=flat-square" alt="Chocolatey"></a></summary>

<br>


你可以使用 [Chocolatey](https://community.chocolatey.org): 安装 **witr**：

```powershell
choco install witr
```
</details>

<details>
<summary><strong>Scoop (Windows)</strong> <a href="https://scoop.sh/#/apps?q=witr"><img src="https://img.shields.io/scoop/v/witr?bucket=main&style=flat-square" alt="Scoop"></a></summary>
<br>


你可以使用 [Scoop](https://scoop.sh): 安装 **witr**：

```powershell
scoop install main/witr
```
</details>

<details>
<summary><strong>AOSC OS</strong> <a href="https://packages.aosc.io/packages/witr"><img src="https://repology.org/badge/version-for-repo/aosc/witr.svg?style=flat-square" alt="AOSC OS"></a></summary>
<br>


你可以从 [AOSC OS 软件仓库](https://packages.aosc.io/packages/witr): 安装 **witr**：

```bash
oma install witr
```
</details>

<details>
<summary><strong>GNU Guix</strong> <a href="https://packages.guix.gnu.org/packages/witr/"><img src="https://repology.org/badge/version-for-repo/gnuguix/witr.svg?style=flat-square" alt="GNU Guix"></a></summary>
<br>


你可以从 [GNU Guix 软件仓库](https://packages.guix.gnu.org/packages/witr/): 安装 **witr**：

```bash
guix install witr
```
</details>

<details>
<summary><strong>Uniget (Linux)</strong> <a href="https://github.com/uniget-org/tools/tree/main/tools/witr"><img src="https://img.shields.io/badge/dynamic/yaml?url=https%3A%2F%2Fraw.githubusercontent.com%2Funiget-org%2Ftools%2Fmain%2Ftools%2Fwitr%2Fmanifest.yaml&query=%24.version&label=uniget&style=flat-square&color=blue" alt="Uniget"></a></summary>
<br>

你可以使用 [uniget](https://uniget.dev/): 安装 **witr**：

```bash
uniget install witr
```
</details>

<details>
<summary><strong>Aqua (macOS, Linux & Windows)</strong> <a href="https://github.com/aquaproj/aqua-registry/blob/main/pkgs/pranshuparmar/witr"><img src="https://img.shields.io/badge/dynamic/yaml?url=https%3A%2F%2Fraw.githubusercontent.com%2Faquaproj%2Faqua-registry%2Fmain%2Fpkgs%2Fpranshuparmar%2Fwitr%2Fpkg.yaml&query=%24.packages%5B0%5D.name&label=aqua&style=flat-square&color=blue" alt="Aqua"></a></summary>
<br>

你可以使用 [aqua](https://aquaproj.github.io/): 安装 **witr**：

```bash
# Add package
aqua g -i pranshuparmar/witr

# Install package
aqua i pranshuparmar/witr
```
</details>

<details>
<summary><strong>Brioche (Linux)</strong> <a href="https://github.com/brioche-dev/brioche-packages/tree/main/packages/witr"><img src="https://img.shields.io/static/v1?label=brioche&message=v0.3.2&color=blue&style=flat-square" alt="Brioche"></a></summary>
<br>

你可以使用 [brioche](https://brioche.dev/): 安装 **witr**：

```bash
brioche install -r witr
```
</details>

<details>
<summary><strong>Mise (macOS, Linux & Windows)</strong> <a href="https://github.com/pranshuparmar/witr/releases/latest"><img src="https://img.shields.io/github/v/release/pranshuparmar/witr?label=mise&style=flat-square" alt="Mise"></a></summary>
<br>

你可以使用 [mise](https://mise.jdx.dev/): 安装 **witr**：

```bash
mise use github:pranshuparmar/witr
```
</details>

<details>
<summary><strong>预编译软件包（deb、rpm、apk）</strong></summary>
<br>

**witr** 为主要 Linux 发行版提供原生软件包。你可以从 [GitHub 发布页](https://github.com/pranshuparmar/witr/releases/latest). 下载最新的 `.deb`、`.rpm` 或 `.apk` 软件包。

- 使用 `curl` 的通用下载命令：
  ```bash
  # 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):**
  ```bash
  sudo dpkg -i ./witr-*.deb
  # Or, using apt for dependency resolution:
  sudo apt install ./witr-*.deb
  ```
- **Fedora/RHEL/CentOS (.rpm):**
  ```bash
  sudo rpm -i ./witr-*.rpm
  ```
- **Alpine Linux (.apk):**
  ```bash
  sudo apk add --allow-untrusted ./witr-*.apk
  ```
</details>

---

### 2.3 源码与手动安装

<details>
<summary><strong>Go（跨平台）</strong></summary>
<br>

你可以直接从源码安装最新版本：

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

这会将 `witr` 二进制文件安装到你的 `$GOPATH/bin` 或 `$HOME/go/bin` 目录中。请确保该目录已加入你的 `PATH`。
</details>

<details>
<summary><strong>手动安装</strong></summary>
<br>

如果你更倾向于手动安装，请针对你的平台按以下简单步骤操作：

**Unix (Linux, macOS, FreeBSD)**

```bash
# 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)**

```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
```
</details>

---

### 2.4 免安装运行

<details>
<summary><strong>Nix Flake</strong></summary>
<br>

如果你使用 Nix，可以从源码构建 **witr** 并免安装运行：

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

</details>

<details>
<summary><strong>Pixi</strong></summary>
<br>

如果你使用 [pixi](https://pixi.prefix.dev/latest/),，可以在 Linux 或 macOS 上免安装运行：

```bash
pixi exec witr --help
```
</details>

---

### 2.5 其他操作

<details>
<summary><strong>验证安装</strong></summary>
<br>

```bash
witr --version
man witr
```
</details>

<details>
<summary><strong>Shell 补全</strong></summary>
<br>

`witr` 支持所有标志（flag）的 Tab 补全。要启用它，请将相应行添加到你的 shell 配置中：

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

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

**Fish**
```fish
witr completion fish | source
# To make it permanent:
witr completion fish > ~/.config/fish/completions/witr.fish
```

**PowerShell**
```powershell
witr completion powershell | Out-String | Invoke-Expression
# To make it permanent, add the above line to your $PROFILE
```
</details>

<details>
<summary><strong>卸载</strong></summary>
<br>

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

要完全移除 **witr** 的脚本/手动安装：

**Unix（Linux、macOS、FreeBSD）**

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

**Windows**

```powershell
Remove-Item -Recurse -Force "$env:LocalAppData\witr"
```
</details>

---
 
## 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 为何存在_。

其核心回答以下问题：

1. 正在运行什么？
2. 它是如何启动的？
3. 是什么让它保持运行？
4. 它属于什么上下文？

---

## 6. 示例输出

### 6.1 基于名称的查询

```bash
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 简短输出

```bash
witr --port 5000 --short
```

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

---

### 6.3 树形输出

```bash
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 多个匹配

```bash
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` 标志：

```bash
witr nginx -x
```

---

### 6.5 基于文件的查询

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

解释哪个进程正在占用该文件。

---

### 6.6 基于容器的查询

```bash
witr --container redis
```

在每个检测到的运行时（Docker、Podman、nerdctl、K8s/crictl、Incus、LXC、LXD、FreeBSD jails）中，按名称、镜像、命令或 compose 项目/服务查找容器。传入 `--verbose` 可在输出中包含挂载、网络和 compose 元数据。

---

### 6.7 多个输入

```bash
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：发生意外故障 |

#### 示例用法：

```bash
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：

```bash
sudo witr [your arguments]
```

#### macOS

在 macOS 上，witr 使用 `ps`、`lsof` 和 `launchctl` 收集进程信息。某些操作可能需要提升权限：

```bash
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** 身份运行终端。

```powershell
# Run in Administrator PowerShell
.\witr.exe [your arguments]
```

---

## 9. 成功标准

witr 在以下情况下算是成功：

- 用户能在数秒内回答「为什么它在运行？」
- 减少了对多种工具的依赖
- 在压力下输出仍易于理解
- 用户在事故处理期间信任它

---

## 10. 赞助商

特别感谢支持 **witr** 的朋友们 ❤️

<p>
  <a href="https://github.com/timcolson" title="Tim Colson">
    <img src="https://images.weserv.nl/?url=github.com/timcolson.png&mask=circle&w=80&h=80" width="80">
  </a>
  <a href="https://github.com/R-Bose" title="Rijurekh Bose">
    <img src="https://images.weserv.nl/?url=github.com/R-Bose.png&mask=circle&w=80&h=80" width="80">
  </a>
</p>