日常开发、线上排查故障时，你还在用 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 tray

功能使用

列出端口

直接查看本机所有监听端口及对应服务。

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

检查端口

sonar info 3000

显示端口完整信息，包括命令、用户、绑定地址、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 停止，而不是直接发送进程信号。

查看日志

sonar logs 3000

对于 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 检查指定健康接口。

端口映射

sonar map 6873 3002

把 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 的日常排查工作。