sarthakagrawal927/port-whisperer

# port-whisperer (Rust) 开发者友好的端口扫描工具，支持框架检测、Docker 感知和进程健康监控。 [LarsenCundric/port-whisperer](https://github.com/LarsenCundric/port-whisperer) 的 Rust 移植版 —— 单一静态二进制文件，零运行时依赖。 ## 安装 单行命令（下载预编译二进制文件）： ``` curl -fsSL https://raw.githubusercontent.com/sarthakagrawal927/port-whisperer/main/install.sh | sh ``` 或使用 Cargo： ``` cargo install --git https://github.com/sarthakagrawal927/port-whisperer ``` 或从源码构建： ``` git clone https://github.com/sarthakagrawal927/port-whisperer cd port-whisperer cargo install --path . ``` ## 用法 ``` ports Show dev server ports (filtered) ports --all Show all listening ports ports Inspect a specific port (+ interactive kill) ports open Open localhost: in browser ports free Kill whatever's on that port (SIGTERM → SIGKILL) ports json JSON output for scripting ports json --all JSON output including system ports ports log Show port history ports log History for a specific port ports ps Show running dev processes sorted by CPU% ports ps --all Show all processes ports clean Find & kill orphaned/zombie dev processes ports watch Monitor port changes in real-time ports help Show help ``` ## 示例 ``` ╭────────┬───────┬───────────┬───────────┬─────────┬─────────────┬────────╮ │ PORT ┆ PID ┆ PROCESS ┆ FRAMEWORK ┆ PROJECT ┆ HEALTH ┆ UPTIME │ ╞════════╪═══════╪═══════════╪═══════════╪═════════╪═════════════╪════════╡ │ :3000 ┆ 12345 ┆ node ┆ Next.js ┆ my-app ┆ ● healthy ┆ 2h15m │ ├╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┤ │ :5432 ┆ 789 ┆ postgres ┆ PostgreSQL┆ ┆ ● healthy ┆ 5d3h │ ╰────────┴───────┴───────────┴───────────┴─────────┴─────────────┴────────╯ ``` ## 功能特性 - **框架检测** —— 通过命令行检查、`package.json` 依赖和配置文件识别 Next.js、Vite、Express、Django、Rails、FastAPI 等 30 多种框架 - **Docker 感知** —— 将主机端口映射到容器名称和镜像 - **项目解析** —— 从进程 cwd 向上遍历以查找项目根目录（`package.json`、`Cargo.toml`、`go.mod` 等） - **进程健康** —— 颜色编码：绿色（健康）、黄色（孤立）、红色（僵尸）。只有 PPID 为 1 的 dev server 才会被标记为孤立 —— daemon、应用程序和 Homebrew 服务会被正确分类为健康 - **智能过滤** —— 默认隐藏系统应用（Spotify、Chrome、Slack、Warp 等）；`--all` 显示所有内容 - **优雅终止** —— 始终先尝试 SIGTERM，等待最多 2 秒，然后回退到 SIGKILL - **快速释放** —— `ports free 3000` 终止占用该端口的进程，无需确认 - **浏览器打开** —— `ports open 3000` 在默认浏览器中打开 localhost - **JSON 输出** —— `ports json` 用于脚本编写和管道传输至 `jq`；包含所有字段（端口、pid、框架、健康状况、内存、运行时间、命令、cwd、docker 信息） - **端口历史** —— 每次 `ports` 扫描都会将带时间戳的快照记录到 `~/.ports-history/`；`ports log` 显示历史记录，`ports log ` 筛选特定端口 - **监视模式** —— 实时监控端口打开/关闭事件（每 2 秒轮询一次） ## 工作原理 三次批量 shell 调用，而非每个进程 N 次： 1. `lsof -iTCP -sTCP:LISTEN` —— 查找所有监听端口 2. `ps -p -o pid,ppid,stat,rss,lstart,command` —— 单次调用获取所有 PID 3. `lsof -a -d cwd -p ` —— 解析工作目录以进行项目检测 框架检测是分层的：首先检查已知的服务器进程，然后是命令行关键字，接着是 `package.json` 依赖、配置文件、Docker 镜像名称，最后回退到进程名称。 ## 测试 ``` cargo test ``` 57 个测试：36 个单元测试（etime 解析、系统应用检测、孤立分类、框架检测、JSON 输出、日志过滤）+ 21 个覆盖所有命令和边缘情况的集成测试。 ## 限制 - **仅限 macOS** —— `lsof` 和 `ps` 标志是 darwin 特有的。Linux 支持需要不同的解析方式。 - **进程名称被截断** —— `lsof` 将名称限制在约 9 个字符（例如 `redis-server` 显示为 `redis-ser`）。检测仍然有效，但显示被截断。 - **框架检测是启发式的** —— 它分层使用命令行关键字、`package.json` 依赖、配置文件和 Docker 镜像。边缘情况会回退显示原始进程名称。 - **孤立检测是保守的** —— 只有具有 PPID 1 的开发类进程（node、python、cargo 等）才会被标记。它会遗漏不常见的运行时，但这比误杀你的终端要好。 ## 路线图 - **`ports group`** —— 按项目对端口进行分组（一个应用通常占用多个端口：dev server、HMR、API） - **Linux 支持** —— 调整 `lsof`/`ps` 解析以适应 Linux 标志和 `/proc` 文件系统 ## 致谢 - 原作：[LarsenCundric/port-whisperer](https://github.com/LarsenCundric/port-whisperer) (Node.js) - Rust 移植版由 [Claude Code](https://claude.ai/claude-code) (Anthropic) 编写 ## 许可证 MIT

标签：Awesome, CLI, Docker, Rust, SOC Prime, URL短链接分析, WiFi技术, WSL, 可视化界面, 安全防御评估, 开发工具, 开发者友好, 插件系统, 数字取证, 数据统计, 服务探测, 框架识别, 端口扫描, 端口管理, 系统管理, 网络工具, 网络流量审计, 自动化脚本, 请求拦截, 进程健康检查, 通知系统, 静态二进制