日常开发、线上排查故障时，你还在用 lsof -iTCP -sTCP:LISTEN | grep ... 一点点查端口吗？查完还得花费时间分辨是 Docker 容器服务，还是本机运行的服务。
sonar 是一个面向开发者的端口管理工具，可以直观看到本机所有监听中的服务，包括 Docker 容器、Compose 项目、资源占用和访问地址。相比 lsof、netstat 这些传统命令，它不仅能查端口，还支持查看日志、进入容器、健康检查、监控服务变化、分析服务依赖关系，以及一键管理整套开发环境，特别适合日常开发和排查端口占用问题。
为啥不用 lsof？
lsof 只能看到“谁占用了端口”，但开发/运维场景真正关心：
是 Docker 还是本机进程？
属于哪个 Compose 项目？
服务是否健康？
有没有资源异常？
能不能直接查看日志？
而 sonar 把这些你需要的场景直接整合在了一起。
快速上手
支持的系统
macOS（使用lsof）
Linux（使用ss）
Windows（使用netstat）
方式一：获取安装包
公 众 号 BugShare 发送 sonar 获取安装包。
软件包对应系统命名：
darwin: macOS 内核
linux: Linux 系统
windows: Windows 系统
下载对应系统的软件包并解压后，将二进制文件按需加入 PATH 环境变量中。
# Linux
cp sonar ~/.local/bin/
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
# macOS
mkdir -p ~/.sonar
cp sonar ~/.sonar/
echo 'export PATH="$HOME/.sonar:$PATH"' >> ~/.zshrc
source ~/.zshrc
# Windows
1. 将 sonar.exe 放到一个固定目录，例如：D:\tools\sonar\
2. 依次打开：设置 -> 系统 -> 高级系统设置 -> 环境变量 -> 系统变量 -> Path
3. 新建 - 添加： D:\tools\sonar\
4. 一路确定保存
5. 重新打开 PowerShell / CMD
方式二：终端命令
# Homebrew（macOS / Linux）
# macOS 上，会自动安装 sonar-tray 菜单栏应用程序
brew install raskrebs/sonar/sonar
# 安装脚本
curl -sfL https://raw.githubusercontent.com/raskrebs/sonar/main/scripts/install.sh | bash
# Windows（PowerShell）
irm https://raw.githubusercontent.com/raskrebs/sonar/main/scripts/install.ps1 | iex
# 使用 Go
go install github.com/raskrebs/sonar@latest
托盘应用程序
仅限 macOS，如果你用 Homebrew 安装，会自动装一个菜单栏应用；
在菜单栏实时显示端口数量和状态。点击可以展开查看所有端口。
功能使用
列出端口
直接查看本机所有监听端口及对应服务。
sonar list # 显示所有监听端口
sonar list --stats # 显示 CPU、内存、状态、运行时长等信息
sonar list --filter docker # 仅显示 Docker 容器端口
sonar list --sort name # 按进程名称排序
sonar list --json # 以 JSON 格式输出
sonar list -a # 包含桌面应用程序
sonar list -c port,cpu,mem,uptime,state # 自定义显示列
sonar list --health # 执行 HTTP 健康检查
sonar list --host user@server # 通过 SSH 扫描远程机器
默认情况下，Sonar 会隐藏与开发无关的桌面应用和系统服务，例如 Figma、AirPlay 以及 macOS 的 .app 和 /System/Library 守护进程。使用 -a 参数可显示这些进程。
可选列：port、process、pid、type、url、cpu、mem、threads、uptime、state、connections、health、latency、container、image、containerport、compose、project、user、bind、ip
检查端口
显示端口完整信息，包括命令、用户、绑定地址、CPU/内存/线程、运行时长、健康检查结果及 Docker 相关详情。
终止进程
# 按端口杀进程
sonar kill 3000 # 发送 SIGTERM 信号终止进程
sonar kill 3000 -f # 强制终止进程（SIGKILL）
# 批量杀进程
sonar kill-all --filter docker # 停止所有 Docker 容器
sonar kill-all --project my-app # 停止指定 Compose 项目
sonar kill-all --filter user -y # 跳过确认提示
Docker 容器会通过 docker stop 停止，而不是直接发送进程信号。
查看日志
对于 Docker 容器，会执行 docker logs -f；对于本地进程，会通过 lsof 自动发现并跟踪日志文件，必要时回退到 macOS log stream 或 Linux /proc/<pid>/fd。
高级使用
连接到服务
sonar attach 3000 # 进入 Docker 容器 shell，或建立 TCP 连接
sonar attach 3000 --shell bash # 使用指定 shell（如 bash）
如果不是 Docker 容器，则尝试 TCP 连接。
实时监控
sonar watch # 每 2 秒轮询一次，并显示变化
sonar watch --stats # 实时显示资源占用（类似 docker stats）
sonar watch -i 500ms # 更快的轮询间隔
sonar watch --notify # 端口上下线时发送桌面通知
sonar watch --host user@server # 监控远程机器
--notify 很有用，后台运行 sonar watch --notify 后，服务启动或异常退出时会自动弹出桌面通知。
依赖关系图
sonar graph # 显示服务之间的通信关系
sonar graph --json # 以结构化 JSON 格式输出
sonar graph --dot # 以 Graphviz DOT 格式输出
显示服务间的实际链接关系，例如前端连接后端、后端连接 PostgreSQL。支持 JSON 和 Graphviz DOT 格式输出，可直观看到运行时真实的服务调用链路。
项目端口快照
sonar profile create my-app # 保存当前端口快照
sonar profile list # 列出所有已保存配置
sonar profile show my-app # 查看配置详情
sonar up my-app # 检查配置中的端口是否正在运行
sonar down my-app # 停止配置中的所有端口
Profile 可以保存项目的端口状态，例如 PostgreSQL、Redis、前后端等服务。创建后，通过 sonar up my-app 一键检查未启动服务，sonar down my-app 一键关闭整套环境。
等待端口
sonar wait 5432 # 等待端口开始接受连接
sonar wait 5432 3000 6379 # 等待多个端口就绪
sonar wait 5432 --timeout 30s # 30 秒后超时失败
sonar wait 5432 --http # 等待 HTTP 200 响应，而不只是 TCP 可连接
sonar wait 5432 --http=/health # 检查指定 HTTP 接口
sonar wait 5432 -i 500ms # 自定义轮询间隔
sonar wait 5432 -q # 静默模式，仅返回退出码（适用于脚本）
适合在 docker compose up -d 等脚本中等待服务启动。--http 会等待接口真正返回 HTTP 200-399，而不只是端口可连接，可避免服务“端口已开但还没准备好”的情况；也可以通过 --http=/health 检查指定健康接口。
端口映射
把 6873 端口转发到 3002，实现轻量级端口映射。
查找空闲端口
sonar next # 从 3000 开始查找下一个可用端口
sonar next 8000 # 从 8000 开始查找下一个可用端口
sonar next 3000-3100 # 在指定范围内查找可用端口
sonar next -n 3 # 查找 3 个连续可用端口
sonar next --json # 以 JSON 格式输出
适合开发脚本、临时服务或自动分配端口场景。
其它
sonar open 3000 # 在浏览器中打开服务
sonar tray # 菜单栏应用，实时显示状态（macOS）
sonar --no-color # 禁用彩色输出（同时支持 NO_COLOR 环境变量）
配置（可选）
sonar 支持从 ~/.config/sonar/config.yaml 读取默认配置；配置文件是可选的，未提供时会使用内置默认值。命令行参数始终优先于配置文件。
sonar config init # 生成带注释的配置模板
sonar config path # 显示配置文件路径
sonar config edit # 使用 $EDITOR 打开配置文件
配置示例：
list:
columns: [port, process, container, image, containerport, url] # 默认显示列
sort: port # 排序方式：port | pid | name | type
filter: "" # 过滤类型：docker | user | system | ""（全部）
all: false # 默认不显示桌面应用
color: true # 是否启用彩色输出
services: # 自定义端口服务名称
9000: php-fpm
5050: my-dashboard
最后总结
如果你经常和 Docker、Compose、多服务开发环境打交道，sonar 基本可以替代大部分 lsof、netstat、docker ps 的日常排查工作。
