<div align="center">
```
██████ ███ ██████ ██ ██████
██ ██ ██ ██ ██ ██
██ ██ ██ ██ ██ ██ ██ ██
██ ██ ██ ██ ██ ██ ██ ████
██ ██ ██ ██ ██ ██ ██ ██
██████ ███ ██ ██ ██ ██ ██ ██
```
了解你的机器上正在运行什么。
</div>
Sonar 会显示所有在 localhost 上监听的内容,并将其整理得井井有条:每个端口
都属于一个**组**——通常是它启动时所在的仓库——而在该组内部,
则属于一个命名的**服务**。使用 `sonar start` 启动你的开发服务器,
整个项目就变成一个整体,你可以将其作为树状结构列出、
等待、跟踪日志,并用一条命令停止。Docker 容器、Compose
项目以及你手动启动的进程也会被自动识别,无需任何
配置。
```
$ sonar list --tree
my-app (3 ports, running) ~/code/my-app
├─ 5432 db postgres:17 http://localhost:5432
├─ 5173 frontend vite (v5.4) http://localhost:5173
└─ 8000 api uvicorn app:app http://localhost:8000
ungrouped (1 port)
└─ 3000 next-server (v16.1.6) http://localhost:3000
```
## 安装
### Homebrew (macOS / Linux)
```sh
brew install raskrebs/sonar/sonar
```
Homebrew 6 会拒绝来自第三方 tap 的 formula,直到你信任该 tap 一次
(`Error: Refusing to load formula raskrebs/sonar/sonar from untrusted tap`):
```sh
brew trust raskrebs/sonar
```
### 安装脚本
```sh
curl -sfL https://raw.githubusercontent.com/raskrebs/sonar/main/scripts/install.sh | bash
```
下载最新二进制文件到 `~/.local/bin`,并在需要时将其添加到你的 PATH 中。重启终端或执行 `source ~/.zshrc`。
在 Windows 上(PowerShell):
```powershell
irm https://raw.githubusercontent.com/raskrebs/sonar/main/scripts/install.ps1 | iex
```
自定义安装位置:
```sh
curl -sfL https://raw.githubusercontent.com/raskrebs/sonar/main/scripts/install.sh | SONAR_INSTALL_DIR=/usr/local/bin bash
```
安装特定版本:
```sh
curl -sfL https://raw.githubusercontent.com/raskrebs/sonar/main/scripts/install.sh | SONAR_VERSION=vX.Y.Z bash
```
```powershell
$env:SONAR_VERSION="vX.Y.Z"; irm https://raw.githubusercontent.com/raskrebs/sonar/main/scripts/install.ps1 | iex
```
### 使用 Go
```sh
go install github.com/raskrebs/sonar@latest
```
Shell 补全(端口号 Tab 补全):
```sh
sonar completion zsh > "${fpath[1]}/_sonar" # zsh
sonar completion bash > /etc/bash_completion.d/sonar # bash
sonar completion fish | source # fish
```
## 六十秒
在仓库根目录下用 `sonar.yaml` 描述你的项目如何运行,
以替代 `dev.sh`:
```yaml
name: 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}
```
然后启动它:
```sh
sonar start
```
```
✓ db http://localhost:5432 pid 41022 ~/.config/sonar/logs/my-app/db.log
✓ api http://localhost:21408 pid 41040 ~/.config/sonar/logs/my-app/api.log
✓ frontend http://localhost:21409 pid 41077 ~/.config/sonar/logs/my-app/frontend.log
3 started
following the logs; Ctrl+C stops the 3 services started here
api | INFO: Uvicorn running on http://127.0.0.1:21408
frontend | VITE v5.4 ready in 312 ms
```
Sonar 会为每个 `port: auto` 服务挑选一个空闲端口,并告知每个服务其他服务的位置,因此第二个工作树可以与第一个并行运行,而不会发生任何端口冲突。`sonar start -d` 在后台执行相同的操作,而 `sonar down` 会停止它并归还端口。在另一个终端中:
```sh
sonar list --tree
```
```
my-app (3 ports, running) ~/code/my-app
├─ 5432 db postgres:17 http://localhost:5432
├─ 21408 api uvicorn app:app http://localhost:21408
└─ 21409 frontend vite (v5.4) http://localhost:21409
```
没有 `sonar.yaml`?`sonar start -- npm run dev` 会将一条命令作为命名服务运行,而 `sonar list` 和 `sonar kill` 可作用于任何正在监听的对象。
下面标记为 `# check` 的示例会在每次 CI 运行时,由 `scripts/readme-check.sh` 针对全新构建执行。
## 命令
### `sonar list`
```sh
sonar list
sonar list --tree
sonar list --group my-app
sonar list --json
# check
```
```sh
sonar list --stats # CPU, memory, threads, uptime, state
sonar list --health # HTTP health checks
sonar list --filter docker # only Docker ports
sonar list --sort name # port | pid | name | type
sonar list -a # include desktop apps
sonar list -c port,process,group,cpu,mem
sonar list --host user@server # scan a remote machine over SSH
```
默认列是 `port`、`process`、`group`、`container`、`image`、
`containerport`、`url`,其中 `process` 显示你为端口指定的名称
(`sonar rename`),然后是服务名称,最后是检测到的内容。
可用列:`port`、`process`、`pid`、`type`、`url`、`group`、`cpu`、
`mem`、`threads`、`uptime`、`state`、`connections`、`health`、`latency`、
`container`、`image`、`containerport`、`compose`、`project`、`user`、`bind`、
`ip`。
恰好正在监听的桌面应用和系统服务——Figma、Discord、
Spotify、ControlCenter、macOS `.app` 包、`/System/Library/` 守护进程——
除非你传入 `-a`,否则会被隐藏。
### `sonar start`
从项目的 `sonar.yaml` 启动项目:
```sh
sonar start # every service in the nearest sonar.yaml
sonar start api frontend # only these (they still wait for their dependencies)
sonar start ../other-project # the sonar.yaml in or above another directory
sonar start -d # in the background, like `sonar up`
```
在前台,sonar 通过守护进程启动服务,在每行日志前加上服务名称来跟踪其日志,当你按下 Ctrl+C 时,它会停止自己启动的服务。已经在运行的服务保持不变,一旦 sonar 启动的每个服务都退出,sonar 会自行返回。
`--` 之前的参数指定一个目录或服务;`--` 之后的所有内容都是一个命令。或者将一条命令作为组中的命名服务运行:
```sh
sonar start -- npm run dev
sonar start --group my-app --name frontend -- npm run dev
sonar start --port 5173 -- npm run dev # expected port, before it binds
sonar start --detach --name api -- uv run uvicorn app:app
sonar start --list
```
无需传入任何参数:
- **Group** — `--group`,否则取最近的 `sonar.yaml` 中的 `name`,否则取
git 根目录的目录名(工作树会变成 `repo@worktree`),否则取当前目录
的名称。
- **Name** — `--name`,否则取 `sonar.yaml` 中 `cmd` 匹配的服务,否则
从命令推断(`npm run dev` → `dev`,`uv run api` → `api`,
`python -m uvicorn` → `uvicorn`,`./dev.sh` → `dev.sh`)。
- **Port** — `--port` 只是一个提示,并非绑定:在端口实际监听之前,
运行状态会显示为 `starting`,守护进程用它来将进程与端口进行匹配。
子进程继承 stdin、stdout、stderr、cwd 和环境变量,外加
`SONAR_GROUP`、`SONAR_NAME` 和 `SONAR_RUN_ID`。它会获得自己的进程组,
因此 `sonar kill` 会终止整棵进程树——包括开发服务器及其监视器和
工作进程。Ctrl+C 会被转发,sonar 以子进程的退出码退出。
`--detach` 会立即返回,并将输出写入
`~/.config/sonar/logs/<group>/<name>.log`。`--list` 显示 sonar 启动了什么,
并在其下方显示此后已结束的内容——包括退出码,以及它是崩溃了
还是被停止了(`--json` 用于机器可读形式):
```sh
sonar start --list
sonar start --detach --name demo --port 8123 -- sleep 5
sonar start --list --json
# check
```
### `sonar.yaml`
项目在仓库根目录的 `sonar.yaml` 中为自身及其服务命名。该文件是可选的——即使没有它,sonar 也会按 git 根目录进行分组——并且它应当被提交:
```yaml
name: my-app
services:
- name: db
cmd: docker compose up db
port: 5432
health: /
description: Postgres 17
icon: database
color: "#4f8cc9"
- name: api
cmd: uv run uvicorn app:app --port 8000
cwd: backend
port: 8000
health: /healthz
depends_on: [db]
- name: frontend
cmd: npm run dev
port: 5173
depends_on: [api]
ports: [9229] # ports that belong to this project without a service
```
- `name` — 组名。不能包含斜杠,不能包含空白字符。
- `cmd`、`cwd`、`port` — `sonar start` 如何启动服务。`cwd` 相对于该文件,且不能逃逸其所在目录。
- `health` — 服务运行期间守护进程轮询的 HTTP 路径,因此服务可能处于*运行中*但尚未*健康*。它会报告 `ok`、`fail` 或 `unknown`,并附带失败原因。
- `description`、`icon`、`color` — 桌面应用的自由格式元数据;sonar 从不推断它们。
- `depends_on` — 启动顺序。指定文件中不存在的服务,或形成循环,都是错误;无效文件只报告一次,且绝不会阻止扫描。
- `env` — sonar 启动服务时为该服务设置的环境变量。
#### `port: auto` 与引用
服务可以将端口交给 sonar 决定,并通过其环境变量找到其他服务,而不是硬编码 `localhost:8080`:
```yaml
services:
- name: api
cmd: uv run uvicorn app:app --port ${port}
port: auto
- name: frontend
cmd: npm run dev -- --port ${port} --strictPort
port: auto
depends_on: [api]
env:
VITE_API_URL: ${api.url}
```
`sonar start` 会为它启动的每个 `port: auto` 服务占用一个空闲端口:在同一个检出中每次都是同一个端口,而在其他每个检出中都是不同的端口,因此工作树永远不会与主检出冲突。服务会以 `PORT`、`SONAR_PORT` 和 `${port}` 的形式获得该端口,并且必须使用它——读取 `PORT`,或在命令行中传递 `${port}`。已经在运行的服务会保留其端口,因此稍后启动的服务仍然能找到它。已分配端口背后的占用从最后一次启动起持续一天;`claims.ttl` 可以改变这一点(参见 The daemon)。
`${port}` 和 `${url}`(`http://localhost:<port>`)是服务自身的;`${<service>.port}` 和 `${<service>.url}` 是另一个服务的。它们可用于 `cmd` 和 `env` 中。引用文件中不存在的服务,或引用没有端口的服务,会在加载文件时报错。`${` 和 `}` 之间的其他内容,如 `${HOME}`,会完全按原样保留。
如果文件名拼写为 `sonar.yml`,也会被读取;`sonar init` 始终写入 `sonar.yaml`。该文件以前是点文件 `.sonar.yaml`,该名称仍然有效:sonar 会按顺序查找 `sonar.yaml`、`sonar.yml`、`.sonar.yaml` 和 `.sonar.yml`,并读取找到的第一个。编辑会写回 sonar 读取的文件,因此不会在你背后重命名任何内容。`sonar doctor` 会指出使用旧名称的文件,而 `sonar doctor --fix` 会重命名它(当文件被跟踪时使用 `git mv`)。守护进程会监视它已知的项目,并在无需重启的情况下获取对文件的编辑。sonar 所做的每一次编辑——来自桌面应用、来自 `sonar groups add`、`rename` 和 `remove`、来自 agent——都会经过守护进程,守护进程会根据自己的语法树重新渲染文件,因此添加、重命名或删除服务的编辑,与元数据更改一样,注释、键顺序和布局都能保留下来。唯一的例外:为对齐行尾注释而添加的多余空格(`cmd: x # note`)会折叠为一个,因为 YAML 库会保留注释但不保留其列位置。
#### `sonar env`
文件解析出的内容无需启动任何东西即可读取:
```sh
sonar env # every service: port, url and its expanded env
sonar env frontend # one service, as export lines
sonar env --json # for tools
```
```
SERVICE PORT URL ENV
db 5432 http://localhost:5432
api 21408 http://localhost:21408 DB_URL=postgres://localhost:5432/app
frontend 21409 http://localhost:21409 VITE_API_URL=http://localhost:21408
```
一个 `port: auto` 且未运行的服务在此处获得其声明,与 `sonar start` 所做的声明相同,因此 `sonar env` 打印的内容就是后续启动时绑定的内容;已在运行的服务保持其当前端口。若指定名称,服务会以 `export` 行的形式输出,这样 shell 就能看到该服务将会:
```sh
eval "$(sonar env frontend)" && npm test
```
其背后是守护进程上的 `groups.env`,供编辑器或代理在服务存在之前连接工作树。
### `sonar up`
```sh
sonar up # the sonar.yaml at or above this directory
sonar up my-app # a group by name
sonar up --only api,frontend
sonar up --json
```
`sonar up` 就是 `sonar start -d`,它也可以从任意位置指定一个组,并在另一台主机上启动它。它会按照 `depends_on` 的顺序启动该组的 `sonar.yaml` 中声明的每一项服务:
服务会等待其依赖项声明的端口就绪后再启动,而已经在监听的服务则会被跳过。每个服务都在自己的进程组中分离运行,其输出保存在 `~/.config/sonar/logs/<group>/<service>.log`,并继承你运行 `sonar up` 时所在 shell 的环境,另外对于有端口的服务还会加上 `PORT`。
```
✓ db http://localhost:5432 pid 41022 ~/.config/sonar/logs/my-app/db.log
- api already running
✓ frontend http://localhost:5173 pid 41108 ~/.config/sonar/logs/my-app/frontend.log
2 started, 1 already running
```
启动失败的服务会单独占一行报告,并使命令以非零状态退出,无论其他服务情况如何。再次使用 `sonar down` 停止所有服务。
`sonar up` 需要守护进程,如果尚未运行则会启动它。
### `sonar down`
```sh
sonar down # the project in the nearest sonar.yaml
sonar down my-app # a group by name
sonar down --only api,worker # only these services
```
停止项目的每个服务——它监听的每个端口,以及 sonar 为它启动的、不占用端口的每个服务(例如 worker)——并释放 sonar 为其 `port: auto` 服务占用的端口。`--only` 将所有这些缩小到指定的服务,就像 `sonar up --only` 只启动部分服务一样;文件中未声明的名称会报错。`sonar kill -g my-app` 停止端口且不释放任何内容。
### `sonar groups` 和 `sonar init`
```sh
sonar init --dry-run
sonar init --service api:8000:/healthz --service web:5173
sonar groups
sonar groups --json
group=$(basename "$PWD") # sonar init names the group after the directory
sonar groups add "$group" worker --port 9000 --cmd 'uv run worker' --depends-on api
sonar groups rename "$group" worker jobs
sonar groups remove "$group" jobs
# check
```
`sonar groups` 列出 sonar 能看到的所有分组以及每个名称的来源:
`manual`(你通过 `sonar assign` 手动指定)、`start`(一次 `sonar start` 运行)、
`file`(一个 `sonar.yaml`)或 `auto`(git 根目录或 Compose 项目)。
`sonar groups <name>` 显示某个分组的端口和服务,以及已声明但未运行的服务。
`sonar init` 会在 git 根目录写入一个 `sonar.yaml`,内容来自它能确定的信息:
当前项目内正在监听的端口(桌面应用和低于 1024 的端口除外),
以及 compose 文件或 `package.json` 直接声明的信息——每个 compose 服务对应一个
服务,包含其发布的端口和 `depends_on`,以及由你的 lockfile 所确定的包管理器
运行的 `dev` 脚本。当两者不一致时,以正在监听的端口为准:它是证据,而非
声明。它写入的文件会说明它无法确定的部分。
除此之外不会检测任何其他内容。Makefile 目标、Procfile 行、深埋在框架中的
入口点——这些都是对你仓库的猜测,而列出它们的表格永远也做不完。那部分
交给 agent:
```sh
sonar init --agent # whichever agent is installed
sonar init --agent codex # name one
sonar init --agent claude -- --allow-dangerously-skip-permissions
```
`--agent` 会在当前终端中打开你已有的编码代理,并预先发送提示词:sonar 已知的内容、它本应写出的草稿、格式,以及由它写入文件且不启动任何内容的规则。你像往常一样观察它读取仓库并批准其编辑——它是你的代理,在你的权限之下——而 `--` 之后的任何内容都会传递给它。sonar 识别 `claude`、`codex`、`cursor-agent` 和 `opencode`;如果安装了多个,请指定一个。当代理退出时,sonar 会加载该文件并打印其声明的服务,或说明为何无法加载。在没有终端的情况下——管道、CI——`--agent` 会打印提示词而不是启动任何内容。
它拒绝在没有 `--force` 的情况下覆盖,而 `--dry-run` 会打印文件而不是写入。`--merge` 会追加到已存在的文件中而不是拒绝,而 `--service name:port[:health]`——可重复——会写入你指定的服务而不是它找到的服务,并为你保留的端口保留它猜测的命令。`--force` 和 `--merge` 互斥。
`sonar groups add <group> <name> --port N` 会向该组的 `sonar.yaml` 追加一个服务,其余部分使用 `--cmd`、`--cwd`、`--health`、`--description`、`--icon`、`--color` 以及可重复的 `--depends-on`。`sonar groups rename <group> <old> <new>` 会在文件中到处重命名一个服务,包括 `depends_on` 引用,而 `sonar groups remove <group> <name>` 会删除一个服务并将其从所有命名它的 `depends_on` 中移除。这三者都会拒绝会导致文件无效的编辑——重复的名称、另一个服务已占用的端口、不存在的服务——并且在确认整个编辑无误之前,它们都不会写入一个字节。
守护进程负责写入,这就是为什么无论编辑来自 CLI、桌面应用还是代理,文件返回时其注释和键顺序都保持不变。`sonar groups add`、`rename` 和 `remove` 需要守护进程,如果它尚未运行则会启动它;这三个名称是子命令,因此一个实际名为 `add` 的组需通过 `sonar groups --json` 读取。
### `sonar kill`
```sh
sonar kill 3000 # SIGTERM, then SIGKILL after 5s
sonar kill 3000 5432 -f # SIGKILL both straight away
sonar kill 3000 --tree # the listener and everything below it
sonar kill --pid 12345 --tree # by process id
sonar kill -g my-app # a whole group, confirms unless -y
sonar kill --all --filter docker -y # every container publishing a port
sonar kill --all --project my-app # one Compose project
sonar kill 3000 --ip 127.0.0.1 # one bind address of several
sonar kill --all --dry-run --json # the plan for the whole machine
```
`--dry-run` 接受任何选择器且不改变任何内容:它会打印 kill 将执行的操作,先子进程后父进程,并让所有进程继续运行。端到端地,针对你自己的监听器:
```sh
sonar start --detach --name plan --port 8231 -- sonar map 3000 8231
sonar wait 8231
sonar kill 8231 --dry-run --json # the plan; the mapping keeps running
sonar kill 8231 -y # and now for real
# check
```
位置参数会被读取为端口,仅当该端口号上没有任何进程监听时,才会被读取为 pid。`-g` 会以不区分大小写的方式匹配解析后的组、旧版运行标签或 id,以及 Compose 项目。
如果某个进程忽略 SIGTERM,且在 `--grace`(5 秒)之后端口仍在监听,则会向其发送 SIGKILL;`--no-escalate` 会关闭该行为。子进程会先于父进程收到信号,因此进程树会按顺序终止。Docker 容器通过 `docker stop` 停止,绝不会收到信号。由 `sonar start` 启动的监听进程始终会与其进程组一起停止。
`--json` 会为每个进程打印一行:
`{port, bind_address, pid, name, method, ok, error}`,其中 `method` 为
`sigterm`、`sigkill`、`docker_stop`、`map_stop` 或 `none`。空扫描退出码为
0;未知组退出码为 1。
### `sonar map`
```sh
sonar map 6873 3002 # also serve the service on 6873 from port 3002
```
在前台运行 TCP 代理,直到你停止它。`sonar kill` 会将停止的映射报告为 `map_stop`。
### `sonar rename`、`sonar assign`、`sonar history`
```sh
sonar rename 3000 storefront # a name of your own, survives restarts
sonar rename 3000 --clear
sonar assign 3000 my-app # pin a port to a group by hand
sonar assign 3000 --clear
sonar history # everything that came up, went down, restarted
sonar history 3000 --since 24h --limit 20
```
```sh
sonar history --since 1h
sonar history --json
# check
```
名称和固定信息存储在 sonar 的数据库中,以关于端口的最具体已知信息为键:运行(`run:<group>/<name>`)、容器(`docker:<project>/<service>`)、工作目录,最后是端口号。重命名的开发服务器在重启后保留其名称;仅固定到端口 3000 的名称适用于在那里响应的任何内容。这三个命令需要守护进程,如果它未运行则启动它。
### 读取端口
```sh
sonar info 3000 # command, user, bind, stats, health
sonar logs 3000 # tail; docker logs for containers
sonar wait 5432 3000 --timeout 60s # block until ready
sonar wait 5432 --http=/health # wait for HTTP 200-399, not just TCP
sonar next 3000 # first free port from 3000
sonar next 3000-3100 -n 3 # three consecutive free ports
sonar graph # who is connected to whom
sonar graph --dot # Graphviz
sonar open 3000 # open in the browser
sonar attach 3000 # shell into the container, or TCP
sonar watch # live view
sonar watch --stats --notify
```
```sh
sonar next 3000
sonar next 3000-3100 -n 3 --json
sonar graph --json
sonar info --help
# check
```
`sonar wait` 退出码为 `0`(就绪)、`1`(超时)或 `2`(中断),这使其成为在启动某物与测试它之间放置的理想选择:
```sh
docker compose up -d
sonar wait 5432 3000 --timeout 60s && npm run migrate && npm run test
```
**守护进程或直接扫描。** 每个读取命令都会询问守护进程是否正在运行,因为它已经拥有答案,无需再 fork `lsof`。如果没有守护进程在运行,它们会直接扫描,并在 stderr 上打印一条说明。`sonar kill` 遵循同样的规则:可达的守护进程执行终止操作,因此它会立即重新扫描,其下一个答案——以及端口历史——已经知道该端口已消失。读取和终止都不会在背后偷偷启动守护进程。`--no-daemon` 会静默地强制直接扫描,并且适用于任何命令:
```sh
sonar list --no-daemon --json
# check
```
### `sonar host`
```sh
sonar host # cpu, load, memory and disk of the machine sonar watches
sonar host --json
```
```sh
sonar host
# check
```
守护进程按扫描节奏测量自身所在机器,并将其发布为快照 `hosts` 集合中的 `localhost` 行:操作系统与内核、运行时间、CPU 百分比、负载平均值、内存以及承载 `/` 的磁盘。CPU 百分比是两次扫描之间完成的工作量,因此在守护进程扫描两次之前为 null;平台无法产生的数值——例如 Windows 上的负载平均值,它没有该指标——为 null 而非零。每个通过 `sonar remote add` 注册的主机都会带着自己的负载加入同一张表。该命令需要一个正在运行的守护进程:正是守护进程持有用于计算百分比的上一份样本。
GPU 列在其所属主机下,并带有利用率和内存信息:在 macOS 上来自 `ioreg`(Apple 芯片内存是统一的,因此只显示 GPU 占用的部分),在 Linux 上来自 `nvidia-smi` 或 amdgpu 的 sysfs 计数器。守护进程在后台每五秒读取一次,绝不在命令路径上读取;在没有来源的地方(Windows、仅 Intel 的 Linux)`gpus` 为 null,在没有 GPU 的机器上为 `[]`。
### `sonar remote install`
```sh
sonar remote install [email protected] # same version as this sonar
sonar remote install hetzner --version v0.6.0 # a Host from ~/.ssh/config
sonar remote install deploy@box --no-service # the binary, no daemon
```
把 sonar 放到一台你已经能 ssh 登录的主机上,并在那里启动它的守护进程。发布归档是**在远程主机上**下载并校验的——不会从本机复制任何东西——二进制文件落在 `~/.local/bin/sonar`,所以全程都不需要 root。守护进程在主机支持 systemd 用户单元时以 systemd 用户单元运行(`~/.config/systemd/user/sonar.service`),不支持时则以分离进程运行;当用户会话会在注销时结束并连带终止守护进程时,会打印 `loginctl enable-linger` 作为建议。
安装的版本就是你运行它的那个 sonar 的版本,因此两端使用相同的协议通信。再次运行会原地升级并重启守护进程,这正是安装和更新是同一条命令的原因。
目标会原样传给 `ssh`:`~/.ssh/config` 中的 `Host` 别名可用,它设置的 `ProxyJump`、`IdentityFile` 和 `Port` 也可用。`--identity` 和 `--ssh-arg` 用于覆盖配置未涵盖的标志。
### `sonar remote`
```sh
sonar remote add [email protected] # name taken from the target
sonar remote add hetzner [email protected] # or given
sonar remote list # status, latency, version, load
sonar remote remove hetzner
sonar list --host hetzner # that host's ports
sonar list --host "*" # every host, with a HOST column
sonar info 3000 --host hetzner
```
已注册的主机运行相同的守护进程,本机上的守护进程保持一条到它的 SSH 连接——`ssh <target> sonar daemon stdio`,在远程 `PATH` 之前先查找 `~/.local/bin`——并将它报告的内容多路复用进每个客户端已经读取的状态中。没有任何新的监听:远程守护进程的套接字对 SSH 用户保持私有,客户端自身从不使用 SSH。
现在每一行都携带它来自的主机。本地行显示 `localhost` 并保留它们一直拥有的键,因此今天读取 sonar 的任何东西都不会改变;远程行显示注册的名称,并以 `<host>/<port>:<bind>` 为键,这正是让两台机器上的端口 3000 成为两行的原因。订阅者只看到 localhost,除非它要求更多(`state.subscribe {"hosts": ["*"]}`)。
目标原样传给 `ssh`,因此 `~/.ssh/config` 别名、`ProxyJump` 和身份都适用;`--ssh-arg`、`--identity` 和 `--port` 覆盖配置未涵盖的内容,`--remote-bin` 指定位于其他位置的 sonar。默认命令通过 `sh` 运行,因此 Windows 主机(其 sonar 来自 PowerShell 安装程序)需要 `--remote-bin sonar`。sonar 不存储密码,也不存储密钥。离开的主机在守护进程重试期间保留其行和状态,只要它保持注册,退避时间就从一秒到三十秒。
`--host` 也仍然接受 sonar 一无所知的裸 `user@host`:它会回退到无代理的 `ssh` + `ss`/`lsof` 扫描,并打印提示到 `sonar remote install`。
#### 在另一台机器上操作
每次写入也接受 `--host`,并在那里执行与这里完全相同的操作:
```sh
sonar kill 3000 --host hetzner # stop a port on that machine
sonar kill -g api --host hetzner # a whole group of its services
sonar kill --all --filter docker --host hetzner # its containers
sonar up api --host hetzner # start a group from its sonar.yaml
sonar logs 3000 --host hetzner # tail its output here
sonar rename 3000 storefront --host hetzner # its name, in its database
sonar assign 3000 storefront --host hetzner
```
本地守护进程通过该主机的 bridge 转发调用,并将远程守护进程的应答原样交回,使用的信封与本地调用返回的相同——每一行结果都会标明它发生在哪台主机上,而 kill 的 `affected` 会携带该流为这些行所使用的 `<host>/<port>:<bind>` 键。流式命令会流式输出:`sonar up --host` 会在远端启动每个服务时打印它,而 Ctrl-C 会停止远端的工作,而不只是停止这个终端。
因为一行的键已经标明了它所在的主机,客户端可以直接把它作为选择器交回——`{"key": "hetzner/3000:127.0.0.1"}` 就是一个完整的选择器,主机也包含在内。一次调用只作用于一台机器;指定两台是错误,而不是在每台上各杀一半。
有两件事保持在本地。`sonar attach` 会把*这个*终端放到某个进程前面,因此它拒绝 `--host`,并提示你 ssh 过去在那里 attach。而 agent 会话是本守护进程持有的状态,因此 `sonar kill --session` 没有远程形式。其他所有操作都需要守护进程在这里运行——因为与另一台机器的连接就存在于这里——并且会明确说明这一点,而不是悄悄改为扫描本机。
`sonar up --host` 需要指定组名:你工作目录下的 `sonar.yaml` 是本机上的一个路径,而读取该文件并启动服务的是远程守护进程。
### 守护进程
一个后台进程扫描端口、解析组、轮询健康状态、维护数据库,并向所有订阅者流式推送变更——包括 CLI、桌面应用和编辑器。
```sh
sonar serve # in the foreground
sonar serve --detach # in the background
sonar daemon status # pid, uptime, subscribers, scans, intervals, claim ttl
sonar daemon path # the socket it listens on
sonar daemon log -n 50 -f # what it is doing
sonar daemon restart
sonar daemon stop
```
```sh
sonar daemon path
sonar daemon status --json
sonar daemon log -n 5
# check
```
| 内容 | 位置 |
|---|---|
| Socket | `$XDG_RUNTIME_DIR/sonar/daemon.sock`,否则为 `~/.config/sonar/daemon.sock`;Windows 上为 `\\.\pipe\sonar` |
| 数据库 | `~/.config/sonar/sonar.db`(`SONAR_DB` 可覆盖) |
| 守护进程日志 | `~/.config/sonar/daemon.log`,达到 5 MiB 时轮转,保留三份 |
| 运行日志 | `~/.config/sonar/logs/<group>/<service>.log` |
| 配置 | `~/.config/sonar/config.yaml` |
`SONAR_SOCKET` 在所有位置覆盖 socket 路径,对守护进程及其客户端均生效——适用于第二个隔离实例。socket 以 0600 权限创建于 0700 目录中,因此只有你可以与之通信。同一时间只运行一个守护进程;崩溃后遗留的 socket 会在下次启动时清理。
守护进程在 30 分钟无客户端且无订阅者后自行停止。可在配置文件中设置 `daemon.idle_timeout` 来更改,或设为 `0` 使其保持运行。
当有变化时,端口每 2 秒扫描一次;无变化时,扫描器会自行降速:有订阅者连接时为 5 秒,无订阅者时为 10 秒。`daemon.scan_interval` 可调整该基准值——最小 1 秒——两个上限也随之缩放,因此将其提高到 `5s` 会退避到 12.5s 和 25s,而不是将曲线固定在旧的上限。`daemon.stats_interval` 是订阅期间 cpu、内存和主机负载条刷新的独立节奏。两者均在守护进程启动时读取:编辑文件后,执行 `sonar daemon restart`。`sonar daemon status` 会打印当前生效的值(`scan base`、`stats tick`),以及扫描器当前所处的自适应间隔。
---
[Read more](https://github.com/raskrebs/sonar)