portview

portview

portview 可列出 Linux、macOS 和 Windows 上的端口及其使用进程。 它会显示进程名称、命令、内存用量和运行时间。你可以检查端口、停止其进程，或在交互式终端界面中监控变化。

它还支持 Docker、通过 SSH 连接远程主机，以及供编码 Agent 使用的 MCP 服务。

安装

Homebrew：

brew install mapika/tap/portview

Linux / macOS：

curl -fsSL https://raw.githubusercontent.com/mapika/portview/main/install.sh | sh

Windows（PowerShell）：

irm https://raw.githubusercontent.com/mapika/portview/main/install.ps1 | iex

也可以使用 cargo install portview，或从 Releases 下载二进制文件。

功能介绍

portview                          # list all listening ports
portview 3000                     # inspect port 3000 in detail
portview node                     # find ports by process name
portview watch                    # interactive TUI with live refresh
portview watch --docker           # TUI with Docker containers as rows
portview kill 3000 --force        # terminate the process using port 3000
portview doctor                   # diagnose port conflicts and issues
portview ssh user@server          # inspect ports on a remote host
portview ssh user@server watch    # remote TUI over SSH
portview ssh user@server --agentless   # no portview needed on the remote
portview mcp                      # run as an MCP server for AI agents

特性

扫描

$ portview
╭──────┬───────┬─────┬──────────────┬──────┬────────────┬────────┬────────┬────────────────────────────╮
│ PORT │ PROTO │ PID │ ADDR         │ USER │ PROCESS    │ UPTIME │ MEM    │ COMMAND                    │
├──────┼───────┼─────┼──────────────┼──────┼────────────┼────────┼────────┼────────────────────────────┤
│ 3000 │ TCP   │ 8   │ 127.0.0.1    │ root │ node       │     7s │  44 MB │ node /opt/app/web.js       │
│ 5000 │ TCP   │ 11  │ 127.0.0.1    │ root │ python3.12 │     7s │  18 MB │ python3 /opt/app/worker.py │
│ 6380 │ TCP   │ 12  │ 127.0.0.1    │ root │ node       │     7s │ 1.2 GB │ node /opt/app/cache.js     │
│ 7000 │ TCP   │ 10  │ 127.0.0.1    │ root │ node       │     7s │  45 MB │ node /opt/app/ingest.js    │
│ 8080 │ TCP   │ 9   │ 127.0.0.1    │ root │ node       │     7s │  44 MB │ node /opt/app/api.js       │
╰──────┴───────┴─────┴──────────────┴──────┴────────────┴────────┴────────┴────────────────────────────╯

--all 会包含非监听连接，每个连接占一行。 --wide 会显示完整命令。--json 会为脚本生成 JSON 输出。

即使无法确定所有者，端口仍会列出；无法填充的列会显示 -。这可能是因为没有使用 sudo，无法查看其他用户的进程，也可能是因为 TIME_WAIT 等套接字在打开它的进程退出后仍然存在。

下方的扫描、doctor 和 MCP 示例均为真实输出，由 demo/record.sh 在隔离命名空间中捕获，因此用户是 root，路径为 /opt/app。Docker 示例仅供说明，因为它需要正在运行的守护进程。

MCP 服务（供 AI Agent 使用）

portview mcp 通过标准输入输出，使用 Model Context Protocol 提供端口查询、诊断和进程终止功能。 要将其注册到 Claude Code：

claude mcp add portview -- portview mcp

也可以手动配置：

{
  "mcpServers": {
    "portview": {
      "command": "portview",
      "args": ["mcp"]
    }
  }
}

工具	功能
list_ports	列出监听端口及可用的进程详情
inspect_port	检查端口，包括进程工作目录和子进程
find_process	按进程名称或命令子字符串查找端口
doctor	检查冲突、通配地址暴露、连接堆积和高内存用量
diff_ports	报告自基准状态以来新增、关闭或所有者发生变化的端口
kill_port	终止使用某端口的进程；dry_run 可预览目标。此工具会向客户端标记为具有破坏性

MCP 服务已包含在 portview 二进制文件中。传入 --read-only 可禁用 kill_port 工具：

portview mcp --read-only

已在 MCP Registry 中登记，名称为 mcp-name: io.github.Mapika/portview。

监视模式（交互式 TUI）

portview watch                    # live-refresh every 1s
portview watch --docker           # include Docker containers
portview watch --sort mem         # sort by memory on launch

按键	操作
j/k、↑/↓	浏览各行
Enter	检查端口（完整命令、cwd、子进程、连接）
d/D	终止进程或管理 Docker 容器
/	筛选所有列
←/→、r	切换排序列、反转排序方向
t	切换进程树视图
a	切换全部/仅监听
q	退出

树视图（t）：将子进程归组到其父进程下。

详情视图（Enter）：显示未换行的完整命令、工作目录、包含端口的子进程列表，以及打开的连接（在 --all 模式下）。

Doctor

portview doctor 会检查端口冲突、通配符绑定、连接堆积和高内存使用情况：

$ portview doctor
  ✓ No port conflicts
  ✓ No wildcard exposure issues
  ! Port 7000 has 16 CLOSE_WAIT connections — possible connection leak
  ! node (PID 12) is listening on port 6380 and using 1.2 GB of memory

  2 warnings found

检查项	标记
端口冲突	多个 PID 绑定到同一端口
通配符暴露	数据库（postgres、redis、mysql、mongod、…）正在 0.0.0.0 上监听
Docker 主机冲突	容器发布了主机已占用的端口
连接堆积	某个端口上存在大量 TIME_WAIT 或 CLOSE_WAIT 连接；这些情况本身并不能证明存在泄漏
高内存使用	监听进程使用的常驻内存超过 1 GB

Docker 会自动检测。使用 portview doctor --json 进行脚本处理（出错时退出代码为 1）。

在 CI 中

GitHub Action 会运行 doctor，并可在出错或出现警告时使工作流失败：

- uses: mapika/portview@v2
  with:
    fail-on: error        # error | warning | never

它会在运行记录中为每项发现添加行内注释、写入摘要表，并将 findings（JSON）、count、errors 和 warnings 作为步骤输出提供：

- uses: mapika/portview@v2
  id: doctor
  with:
    fail-on: never
- run: echo '${{ steps.doctor.outputs.findings }}' | jq .

如果 PATH 中已有 portview，请设置 install: false。适用于 Linux 和 macOS 运行器。

SSH 远程模式

通过 SSH 检查远程主机上的端口：

portview ssh user@server              # one-shot scan
portview ssh user@server watch        # full interactive TUI
portview ssh user@server doctor       # remote diagnostics
portview ssh user@server 3000         # inspect a remote port
portview ssh user@server --ssh-opt "-p 2222"  # custom SSH port

远程 TUI 中的终止操作会通过 SSH 转发。

如果远程主机上没有安装 portview，SSH 模式会使用 ss 和 ps 收集数据；如果没有 ss，则使用 lsof 和 ps。这需要远程主机上有 POSIX shell 和数据收集工具。

$ portview ssh user@server
portview not found on user@server — falling back to agentless mode (ss + ps over SSH).
╭──────┬───────┬─────┬──────────────┬──────┬─────────┬────────┬───────┬──────────────────────╮
│ PORT │ PROTO │ PID │ ADDR         │ USER │ PROCESS │ UPTIME │ MEM   │ COMMAND              │
├──────┼───────┼─────┼──────────────┼──────┼─────────┼────────┼───────┼──────────────────────┤
│ 3000 │ TCP   │ 6   │ 127.0.0.1    │ root │ node    │     3s │ 45 MB │ node /opt/app/web.js │
│ 8080 │ TCP   │ 7   │ 127.0.0.1    │ root │ node    │     3s │ 45 MB │ node /opt/app/api.js │
╰──────┴───────┴─────┴──────────────┴──────┴─────────┴────────┴───────┴──────────────────────╯

即使远程主机上已安装 portview，也可以使用 --agentless 以这种方式收集数据。它支持扫描、端口检查、进程搜索、 诊断和监视模式。

对收集到的数据运行诊断：

portview ssh user@server doctor --agentless

这会使用与本地模式相同的诊断检查。由于无 Agent 模式不会查询远程容器，因此会跳过 Docker 检查。

监视远程端口，并可在 TUI 中终止进程：

portview ssh user@server watch --agentless

监视模式通过单个持久 SSH 连接收集更新。

Docker 集成

使用 --docker 纳入 Docker 容器发布的端口：

$ portview --docker
╭──────┬───────┬───────┬──────────────┬────────┬──────────┬────────┬────────┬────────────────────────────╮
│ PORT │ PROTO │ PID   │ ADDR         │ USER   │ PROCESS  │ UPTIME │ MEM    │ COMMAND                    │
├──────┼───────┼───────┼──────────────┼────────┼──────────┼────────┼────────┼────────────────────────────┤
│ 3000 │ TCP   │ 48291 │ 127.0.0.1    │ mark   │ node     │ 3h 12m │ 248 MB │ next dev [docker:web]      │
│ 8080 │ TCP   │ -     │ 0.0.0.0      │ docker │ pv-nginx │      - │      - │ nginx:alpine :8080->80/tcp │
╰──────┴───────┴───────┴──────────────┴────────┴──────────┴────────┴────────┴────────────────────────────╯

仅容器对应的行没有主机进程，因此 PID、UPTIME 和 MEM 会显示为 -。

在监视模式下，在 Docker 行上按 d 可停止或重启容器，也可查看其日志。

JSON 输出

portview --json                   # pipe to jq, scripts, dashboards
portview --docker --json          # includes Docker ownership data
portview watch --json             # streaming JSON, one array per tick
portview doctor --json            # machine-readable diagnostics

自定义颜色

PORTVIEW_COLORS="port=red,pid=magenta,command=bright_cyan" portview

列：port、proto、pid、user、process、uptime、mem、command。使用 --no-color 可禁用颜色。

工作原理

本地端口和进程数据来自操作系统接口：

字段	Linux	macOS	Windows
端口	/proc/net/tcp{,6}、udp{,6}	proc_pidfdinfo	GetExtendedTcp/UdpTable
PID	通过 /proc/*/fd/ 由 inode 查找 PID	proc_listpids	包含在套接字表中
进程	/proc/<pid>/exe	proc_pidpath	QueryFullProcessImageNameW
内存	/proc/<pid>/status VmRSS	proc_pidinfo	K32GetProcessMemoryInfo
运行时间	/proc/<pid>/stat	proc_pidinfo	GetProcessTimes

在 Linux 上，portview 会从 /proc/<pid>/exe 读取可执行文件名。 /proc/<pid>/comm 中的线程名可能会被运行时更改，且长度限制为 15 字节。

Docker 集成使用 docker CLI。SSH 模式使用系统的 ssh 客户端，在远程主机上运行 portview 或无 Agent 数据收集工具。 MCP 模式使用 stdin/stdout 上以换行符分隔的 JSON-RPC 2.0。

从源代码构建

git clone https://github.com/mapika/portview
cd portview
cargo build --release

需要 Rust 1.85+（edition 2024）。Shell 补全和 man 手册页会在构建时生成。

仓库包含一个 Dockerfile。要从容器中检查主机， 请共享主机的网络和 PID 命名空间：

docker run --rm -i --network host --pid host portview

贡献

开发环境设置和指南请参阅 CONTRIBUTING.md，重新生成录制内容请参阅 demo/README.md。

更改应能在所有三个平台上通过类型检查，而不只是你使用的平台：

cargo check --target aarch64-apple-darwin
cargo check --target x86_64-pc-windows-msvc

限制

• **Linux：**会列出其他用户占用的端口，但要识别进程需要使用 sudo（因为它会读取 /proc/<pid>/fd/）。对于无法归属的行，PID、用户、进程和命令均显示为 -，而不是隐藏这些行。
• **macOS：**未使用 sudo 时，不会列出其他用户占用的端口——套接字会通过 proc_pidfdinfo 按进程枚举，因此无法打开的进程不会贡献任何可枚举内容。出于同样的原因，doctor 无法检测此处的 TIME_WAIT 堆积；CLOSE_WAIT 则可正常检测。
• **Windows：**会列出由无法访问的系统进程占用的端口，并显示 PID，但名称和用户显示为 -。终止操作始终会强制结束进程。使用 Administrator 身份运行可查看完整详情。
• **Docker：**需要 docker CLI 和守护进程访问权限
• **SSH：**如果远程端缺少 portview，每条命令都会回退到无代理采集：在 Linux 上使用 ss 和 ps，在没有 ss 的系统上使用 lsof。远程端需要安装其中一种工具，并具备 POSIX shell。无代理采集无法检查远程端的 Docker，因此该检查会报告为已跳过，而非通过。

许可证

MIT