【免费下载链接】sonarCLI tool for inspecting and managing services listening on localhost ports项目地址https://gitcode.com/gh_mirrors/sonar17/sonar点击查看免费下载Sonar 是一款本地端口管理与服务启动 CLI 工具它用port: auto自动端口分配和${port}变量让多个 git worktree 并行跑同一套开发服务时不再互相抢占端口。本文详解这两个机制的原理、配置方法和日常用法帮你彻底告别 EADDRINUSE。为什么 worktree 并行开发总撞端口用git worktree开多个分支并行开发是常见做法但每个 worktree 里都要启动同样的开发服务前端、API、数据库。如果端口写死在sonar.yaml或启动命令里主 worktree 的vite占了5173新 worktree 一启动就报EADDRINUSE手动改成别的端口又忘了同步改前端里写死的API_URL两个 worktree 的sonar list输出混在一起分不清哪个服务属于谁Sonar 的思路是把端口交给工具决定服务之间通过环境变量互相发现地址而不是硬编码localhost:8080。快速上手sonar.yaml 里的 port: auto在仓库根目录的sonar.yaml中把不希望固定的服务端口声明为port: autoname: my-app services: - name: db cmd: docker compose up db port: 5432 - name: api cmd: uv run uvicorn app:app --port ${port} port: auto depends_on: [db] - name: frontend cmd: npm run dev -- --port ${port} --strictPort port: auto depends_on: [api] env: VITE_API_URL: ${api.url}然后一条命令启动sonar start输出类似✓ db http://localhost:5432 pid 41022 ✓ api http://localhost:21408 pid 41040 ✓ frontend http://localhost:21409 pid 41077api和frontend的端口是 Sonar 现场分配的完全不用你操心。${port} 变量展开规则4 种写法其他原样保留${port}类引用由 refs.go 实现规则非常克制——只认 4 种形态写法含义${port}本服务自己的端口${url}本服务的http://localhost:port${api.port}另一个服务api的端口${api.url}另一个服务api的完整 URL两个关键点只在cmd和env中生效且必须在服务实际启动前所有被引用服务的端口都确定后展开见 start.go 中addressBook的解析流程其他${...}一律原样保留。比如${HOME}、${FOO:-x}不会被误伤——因为命令最终会交给sh -c执行这一点对已有 shell 变量的项目特别友好引用了文件中不存在的服务、或对方根本没声明端口会在加载配置时直接报错而不是运行到一半才失败。端口从哪来同一 worktree 稳定、不同 worktree 错开这是零冲突的核心。认领逻辑在 claims.go 和 hash.go按项目 worktree 服务名派生每个port: auto服务以project/worktree/service为认领键对键做 FNV-1a 哈希落入10000–32699区间内某个 10 端口块作为起点再向上探测跳过正在监听和已被认领的端口同一 checkout 每次得到同一个端口哈希是确定性的所以主 worktree 的api永远是21408重启、重开终端都不变——书签、文档里写的地址依然有效不同 worktree 得到不同端口键不同哈希起点就不同新 worktree 的api可能落在21411天然错开认领有 24 小时 TTL每次启动会刷新服务停止后用sonar down会主动释放认领端口立刻归还这个范围10000–32699也刻意避开了常用开发端口和操作系统临时端口区内核不会把认领的端口分给出站连接。worktree 自动分组my-app 与 my-appfeature-xSonar 通过 checkout.go 识别 git 检出位置主检出是my-app每个git worktree add出来的联检出名my-appworktree。这意味着两个 worktree 同时sonar start后$ sonar list --tree my-app (3 ports, running) ~/code/my-app ├─ 5432 db postgres:17 ├─ 21408 api uvicorn app:app └─ 21409 frontend vite my-appfix-x (3 ports, running) ~/code/my-appfix-x ├─ 5432 db postgres:17 ├─ 21411 api uvicorn app:app └─ 21412 frontend vite两组完全独立sonar kill -g my-appfix-x只停掉 worktree 里的服务主检出纹丝不动。而且即使 worktree 里有一份旧的sonar.yaml副本它也只描述服务、不覆盖组名不会把 worktree 折回主检出组里。不启动就能查端口sonar env写脚本、跑测试、配编辑器时经常需要知道这个服务将会用哪个端口。sonar env走的是与groups.start完全相同的端口解析路径但不启动任何进程实现见 env.gosonar env # 所有服务的端口、URL、展开后的环境变量 sonar env frontend # 单个服务输出 export 行 eval $(sonar env frontend) npm testport: auto且未运行的服务在这里拿到的就是之后sonar start会绑定的同一个端口——先读后启动所见即所得。手动认领端口sonar claim 与 worktree_ports除了随服务自动认领claim.go 提供了显式认领适合给 AI agent 或脚本预留端口sonar claim # 为当前 worktree 认领 1 个端口 sonar claim --count 3 # 认领 3 个 sonar claim --ttl 2h # 缩短 24 小时默认 TTL sonar claim --release # 归还本 worktree 的端口 sonar claims # 列出机器上所有存活认领另外sonar.yaml顶层的worktree_ports见 config.go可以声明这个项目每次认领几个端口sonar claim不带--count时就会按它来上限 100。日常操作速查场景命令启动当前目录的项目sonar start后台启动等价 sonar upsonar start -d查看端口解析结果sonar env只启动部分服务sonar start api frontend停止并释放自动认领的端口sonar down整组杀端口不释放认领sonar kill -g my-app等待端口就绪再跑迁移sonar wait 5432 --timeout 60s npm run migrate健康检查sonar list --health两个容易混淆的点depends_on会等依赖服务的端口真正监听后才启动本服务等待上限 30 秒单个依赖超时只跳过它、不影响其他服务sonar down会释放port: auto的认领而sonar kill -g只停进程、不动认领。小结Sonar 解决 worktree 端口冲突的三板斧port: auto把端口分配交给 daemon 的认领账本哈希派生保证同 worktree 稳定、跨 worktree 错开${port}/${service.url}让服务间通过环境变量互相发现配置里零硬编码worktree 自动成为独立分组my-appfix-x启动、查看、停止全程隔离装好 Sonar、把固定端口改成port: auto、命令里改用${port}多 worktree 并行开发就可以放心开了。更多细节可参考 README.md 和 MCP 协议定义 protocol.schema.json。赞分享【免费下载链接】sonarCLI tool for inspecting and managing services listening on localhost ports项目地址https://gitcode.com/gh_mirrors/sonar17/sonar点击查看免费下载相关推荐从零到接收一份完整的 SDR 软件无线电免费教程从零到接收一份完整的 SDR 软件无线电免费教程 对于从未接触过无线电的人来说用 SDR 做软件无线电是一个务实的起点它免费、开源、跨平台配合一桌面应用音频处理智能硬件Overstory Git Worktree 隔离机制多智能体并行开发零冲突的完整解析Overstory Git Worktree 隔离机制多智能体并行开发零冲突的完整解析 Overstory 是一款面向 AI 编程智能体如 Claude Cclaude-task-master 并行开发实战用 Git Worktree 让多个 AI 编码助手同时工作互不冲突claude task master 并行开发实战用 Git Worktree 让多个 AI 编码助手同时工作互不冲突 导读本文基于 claude taskAI Agent开发工具CLIMCP创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考