yaport 0.1.0

package/README.md

@@ -0,0 +1,427 @@
+# 丫口 (yaport)
+
+丫口是一个本机运行的 Web UI 和 CLI，用 SSH 读取远程机器当前监听中的 TCP/UDP 端口。
+
+English documentation is available below: [English](#english).
+
+## 适合什么场景
+
+- 快速查看远程机器的监听端口、监听地址、协议、状态、进程和 PID。
+- 通过 OpenSSH alias 连接机器，例如 `ssh erya` 对应 `--host erya`。
+- 通过一层或两层跳板机连接目标机器，底层使用 OpenSSH `ProxyJump`。
+- 目标机器或跳板机需要 SSH 密码时，可以在 GUI 填写，也可以通过 CLI 环境变量传入。
+- 面板和 CLI 都能配置连接超时、命令超时，适合慢链路或两层跳板机。
+- 如果远程机器有 nginx 配置，丫口会把能匹配端口的外部入口 URL 展示在端口行里。
+- 当前选中的机器会复用 OpenSSH ControlMaster 连接，降低两层跳板和密码认证的重复握手成本。
+
+丫口只做只读查询，不扫描网段，也不修改远程机器配置。
+
+## 安装
+
+全局安装：
+
+```bash
+pnpm add -g yaport
+```
+
+也可以直接用 pnpm dlx：
+
+```bash
+pnpm dlx yaport
+```
+
+本地开发运行：
+
+```bash
+pnpm install
+pnpm dev
+```
+
+## 启动 Web UI
+
+```bash
+yaport
+yaport --host 127.0.0.1 --port 5173
+yaport --data-file .yaport/machines.json
+yaport --no-open
+```
+
+默认行为：
+
+- `yaport` 会启动本机 server，并自动打开网页。
+- 默认监听 `127.0.0.1:5173`。
+- 默认机器配置目录按顺序查找 `./.yaport`、`~/.yaport`，命中即使用其中的 `machines.json`，不合并；都不存在时创建当前目录的 `./.yaport/machines.json`。
+- `--no-open` 适合脚本、agent、远程 shell，不自动打开浏览器。
+
+## 通过 CLI 添加机器
+
+GUI 能添加机器，但大量机器用 CLI 更快。`add-machine` 是非交互式命令，适合 agent 和脚本使用。
+
+OpenSSH alias，等价于 `ssh erya`：
+
+```bash
+yaport add-machine --name Erya --host erya --json
+```
+
+明确指定用户和端口：
+
+```bash
+yaport add-machine --name Prod --host 10.0.0.5 --user root --port 2222 --json
+```
+
+目标机器密码使用环境变量传入：
+
+```bash
+TARGET_PASSWORD='[redacted-target-password]' yaport add-machine \
+  --name Prod \
+  --host 10.0.0.5 \
+  --user root \
+  --password-env TARGET_PASSWORD \
+  --json
+```
+
+一层跳板机：
+
+```bash
+JUMP_PASSWORD='[redacted-jump-password]' TARGET_PASSWORD='[redacted-target-password]' yaport add-machine \
+  --name Prod \
+  --host prod.internal \
+  --user app \
+  --password-env TARGET_PASSWORD \
+  --connect-timeout 30 \
+  --command-timeout 90 \
+  --jump1-host jump.internal \
+  --jump1-user ops \
+  --jump1-password-env JUMP_PASSWORD \
+  --json
+```
+
+两层跳板机：
+
+```bash
+yaport add-machine \
+  --name DeepTarget \
+  --host target.internal \
+  --user app \
+  --jump1-host jump-a.internal \
+  --jump1-user ops \
+  --jump2-host jump-b.internal \
+  --jump2-user edge \
+  --json
+```
+
+常用参数：
+
+| 参数 | 说明 |
+| --- | --- |
+| `--name <name>` | UI 里展示的机器名称。 |
+| `--host <host>` | SSH host、IP 或 OpenSSH alias。 |
+| `--user <user>` | SSH 用户。OpenSSH alias 已配置时可以省略。 |
+| `--port <port>` | SSH 端口。OpenSSH alias 已配置时可以省略。 |
+| `--password-env <env>` | 从环境变量读取目标机器 SSH 密码。 |
+| `--connect-timeout <seconds>` | SSH 连接超时。可选值：`8`、`15`、`30`、`60`。默认 `15`。 |
+| `--command-timeout <seconds>` | 本机等待命令完成的总超时。可选值：`12`、`30`、`45`、`90`。默认 `45`。 |
+| `--jump1-host <host>` | 第一层跳板机。 |
+| `--jump2-host <host>` | 第二层跳板机。 |
+| `--jumpN-user <user>` | 第 N 层跳板机 SSH 用户。 |
+| `--jumpN-port <port>` | 第 N 层跳板机 SSH 端口。 |
+| `--jumpN-password-env <env>` | 从环境变量读取第 N 层跳板机密码。 |
+| `--json` | 输出稳定 JSON，不输出密码。 |
+| `--data-file <path>` | 指定机器配置文件，跳过默认两层查找。 |
+
+建议：
+
+- agent 和脚本优先使用 `--json`。
+- 密码优先使用 `--password-env` 和 `--jumpN-password-env`，不要把密码直接放进命令参数。
+- 使用 OpenSSH alias 时，`--user` 和 `--port` 可以留空。
+- 两层跳板或密码认证握手较慢时，建议使用 `--connect-timeout 30 --command-timeout 90`。
+
+## 端口信息
+
+丫口通过本机 OpenSSH 登录远程机器，并读取：
+
+- `ss -H -lntup`：监听中的 TCP/UDP 端口。
+- `ps -ww -p <pid> -o pid=,args=`：尽量补全进程命令行。
+- `nginx -T`：如果可读，推断 nginx 外部入口。
+
+`ss` 会先执行；拿到 PID 后，`ps` 和 `nginx -T` 会并发执行。任意一个失败都不会影响端口清单。
+
+表格展示：
+
+- 协议：TCP / UDP。
+- 监听地址。
+- 端口号。
+- 状态。
+- 进程名称或完整命令行。
+- PID。
+- 外部入口。
+
+## nginx 外部入口
+
+当 `nginx -T` 可读时，丫口会解析 `server` 配置并按端口匹配外部入口。
+
+规则：
+
+- `listen 443 ssl` 或端口 `443` 展示为 `https://server_name`。
+- 其他端口展示为 `http://server_name:port`。
+- `server_name _`、空值、变量域名不展示。
+- `nginx -T` 读不到不会影响端口清单，只显示“无外部入口”。
+- nginx 来源的入口会带一个 nginx 小图标；后续可以继续支持其他来源类型。
+- nginx 外部入口按机器缓存 5 分钟，包括短时间缓存读取失败，避免静默刷新时重复等待慢失败。
+
+## Web UI 行为
+
+- 添加机器表单默认折叠。
+- 添加机器时可以选择“连接超时”和“命令超时”。
+- TCP / UDP 指标卡带开关，默认开启，用于过滤下方记录。
+- “监听端口”指标卡可以按端口分组。
+- “进程”指标卡可以按进程分组。
+- 切换机器时按机器粒度保留上次结果，不会把上一台机器的端口展示到当前机器。
+- 当前选中的机器会使用 OpenSSH `ControlMaster=auto` 和 `ControlPersist=5m`，`ss`、`ps`、`nginx -T`、手动刷新和 1 分钟自动刷新会复用同一条 SSH master connection。
+- 未选中机器的后台静默刷新不启用连接复用，避免维护过多后台连接。
+- 网页在前台活跃时，选中机器默认每 1 分钟静默刷新，未选中机器默认每 5 分钟静默刷新。
+- 机器列表和当前选中机器会写入 `sessionStorage`，刷新页面后能先看到本地缓存，再等待 server 返回最新数据。
+
+## 数据与安全
+
+- 机器配置目录默认按顺序查找 `./.yaport`、`~/.yaport`，命中即使用其中的 `machines.json`，不合并；都不存在时创建当前目录的 `./.yaport/machines.json`。
+- 配置文件以 `0600` 权限写入。
+- API 和 CLI JSON 输出不会返回已保存的 SSH 密码。
+- 密码目前是本机明文保存；如果不想落盘，优先使用 SSH key 或 OpenSSH alias。
+- 丫口只从远程机器读取端口、进程和 nginx 配置，不会写远程文件。
+
+## 远程机器要求
+
+- 本机需要可用的 OpenSSH `ssh` 命令。
+- 远程机器需要有 `ss` 命令。
+- 进程命令行和 PID 是否完整，取决于当前 SSH 用户权限。
+- nginx 外部入口依赖远程机器能执行并读取 `nginx -T`。
+
+## 本地开发
+
+```bash
+pnpm install
+pnpm dev
+pnpm test
+pnpm build
+```
+
+打包后的 CLI 入口：
+
+```bash
+pnpm build
+node bin/yaport.js --help
+```
+
+## English
+
+Yaport is a local Web UI and CLI for reading currently listening TCP/UDP ports on remote machines through SSH.
+
+Yaport is read-only. It does not scan networks and does not modify remote machine configuration.
+
+## Use Cases
+
+- Inspect listening ports, listen addresses, protocols, states, processes, and PIDs on remote machines.
+- Connect through OpenSSH aliases, for example `ssh erya` maps to `--host erya`.
+- Connect through one or two jump hosts via OpenSSH `ProxyJump`.
+- Support SSH passwords for both target machines and jump hosts, from the GUI or CLI environment variables.
+- Configure connection and command timeouts from both the UI and CLI for slow links or two-hop jump paths.
+- Infer public-facing nginx URLs and show them next to matching listening ports.
+- Reuse an OpenSSH ControlMaster connection for the currently selected machine to reduce repeated handshakes on slow jump paths.
+
+## Installation
+
+Install globally:
+
+```bash
+pnpm add -g yaport
+```
+
+Or run it with pnpm dlx:
+
+```bash
+pnpm dlx yaport
+```
+
+For local development:
+
+```bash
+pnpm install
+pnpm dev
+```
+
+## Start the Web UI
+
+```bash
+yaport
+yaport --host 127.0.0.1 --port 5173
+yaport --data-file .yaport/machines.json
+yaport --no-open
+```
+
+Default behavior:
+
+- `yaport` starts the local server and opens the Web UI automatically.
+- The default bind address is `127.0.0.1:5173`.
+- The default machine config directory lookup checks `./.yaport` first, then `~/.yaport`. The first hit wins and Yaport uses that directory's `machines.json`; files are not merged. If neither directory exists, Yaport creates `./.yaport/machines.json`.
+- Use `--no-open` for scripts, agents, or remote shells.
+
+## Add Machines from the CLI
+
+The GUI can add machines, but the CLI is faster for repeated setup. `add-machine` is non-interactive and works well from agents and scripts.
+
+OpenSSH alias, same as `ssh erya`:
+
+```bash
+yaport add-machine --name Erya --host erya --json
+```
+
+Explicit user and port:
+
+```bash
+yaport add-machine --name Prod --host 10.0.0.5 --user root --port 2222 --json
+```
+
+Target password from an environment variable:
+
+```bash
+TARGET_PASSWORD='[redacted-target-password]' yaport add-machine \
+  --name Prod \
+  --host 10.0.0.5 \
+  --user root \
+  --password-env TARGET_PASSWORD \
+  --json
+```
+
+One jump host:
+
+```bash
+JUMP_PASSWORD='[redacted-jump-password]' TARGET_PASSWORD='[redacted-target-password]' yaport add-machine \
+  --name Prod \
+  --host prod.internal \
+  --user app \
+  --password-env TARGET_PASSWORD \
+  --connect-timeout 30 \
+  --command-timeout 90 \
+  --jump1-host jump.internal \
+  --jump1-user ops \
+  --jump1-password-env JUMP_PASSWORD \
+  --json
+```
+
+Two jump hosts:
+
+```bash
+yaport add-machine \
+  --name DeepTarget \
+  --host target.internal \
+  --user app \
+  --jump1-host jump-a.internal \
+  --jump1-user ops \
+  --jump2-host jump-b.internal \
+  --jump2-user edge \
+  --json
+```
+
+Common options:
+
+| Option | Description |
+| --- | --- |
+| `--name <name>` | Display name in the UI. |
+| `--host <host>` | SSH host, IP address, or OpenSSH alias. |
+| `--user <user>` | SSH user. Omit it when an OpenSSH alias already defines `User`. |
+| `--port <port>` | SSH port. Omit it when an OpenSSH alias already defines `Port`. |
+| `--password-env <env>` | Read the target machine SSH password from an environment variable. |
+| `--connect-timeout <seconds>` | SSH connection timeout. Choices: `8`, `15`, `30`, `60`. Default: `15`. |
+| `--command-timeout <seconds>` | Total local command timeout. Choices: `12`, `30`, `45`, `90`. Default: `45`. |
+| `--jump1-host <host>` | First jump host. |
+| `--jump2-host <host>` | Second jump host. |
+| `--jumpN-user <user>` | SSH user for jump host N. |
+| `--jumpN-port <port>` | SSH port for jump host N. |
+| `--jumpN-password-env <env>` | Read jump host N's password from an environment variable. |
+| `--json` | Print deterministic JSON. Passwords are never printed. |
+| `--data-file <path>` | Use a specific machine config file and skip the default two-level lookup. |
+
+Recommendations:
+
+- Use `--json` from agents and scripts.
+- Prefer `--password-env` and `--jumpN-password-env`; avoid putting passwords directly in process arguments.
+- Omit `--user` and `--port` when `--host` is an OpenSSH alias.
+- For slow two-hop jump paths or password handshakes, use `--connect-timeout 30 --command-timeout 90`.
+
+## Port Inventory
+
+Yaport logs in through local OpenSSH and reads:
+
+- `ss -H -lntup`: listening TCP/UDP ports.
+- `ps -ww -p <pid> -o pid=,args=`: full process command lines when available.
+- `nginx -T`: nginx configuration, when readable, to infer external routes.
+
+`ss` runs first. After PIDs are available, `ps` and `nginx -T` run concurrently. Either one may fail without breaking the port list.
+
+The table shows:
+
+- Protocol: TCP / UDP.
+- Listen address.
+- Port.
+- State.
+- Process name or full command line.
+- PID.
+- External routes.
+
+## nginx External Routes
+
+When `nginx -T` is readable, Yaport parses `server` blocks and matches routes by port.
+
+Rules:
+
+- `listen 443 ssl` or port `443` is shown as `https://server_name`.
+- Other ports are shown as `http://server_name:port`.
+- `server_name _`, empty names, and variable names are ignored.
+- If `nginx -T` cannot be read, the port list still works and the UI shows no external route.
+- nginx routes include a small nginx source icon. Other source types can be added later.
+- nginx external routes are cached per machine for 5 minutes, including short-lived failure caching, so silent refreshes do not repeatedly wait on slow config reads.
+
+## Web UI Behavior
+
+- The add-machine form is collapsed by default.
+- The add-machine form lets you choose connection timeout and command timeout.
+- TCP and UDP metric cards include switches, both enabled by default, to filter visible records.
+- The listening-port metric card can group the table by port.
+- The process metric card can group the table by process.
+- Switching machines keeps the selected machine's own cached result; it never shows another machine's ports as stale data.
+- The selected machine uses OpenSSH `ControlMaster=auto` and `ControlPersist=5m`; `ss`, `ps`, `nginx -T`, manual refresh, and 1-minute auto refresh reuse the same SSH master connection.
+- Background refreshes for unselected machines do not use connection reuse, so Yaport does not keep extra background master connections open.
+- While the page is visible, the selected machine refreshes silently every 1 minute, and unselected machines refresh silently every 5 minutes.
+- The machine list and selected machine ID are stored in `sessionStorage` for immediate visibility after page reload.
+
+## Data and Security
+
+- Machine config directory lookup checks `./.yaport` first, then `~/.yaport`. The first hit wins and Yaport uses that directory's `machines.json`; files are not merged. If neither directory exists, Yaport creates `./.yaport/machines.json`.
+- The config file is written with `0600` permissions.
+- API responses and CLI JSON output never return stored SSH passwords.
+- Passwords are currently stored locally in plain text. Prefer SSH keys or OpenSSH aliases if you do not want passwords on disk.
+- Yaport only reads remote ports, processes, and nginx configuration. It does not write remote files.
+
+## Remote Requirements
+
+- Local machine: OpenSSH `ssh`.
+- Remote machine: `ss`.
+- Process command lines and PIDs depend on the SSH user's permissions.
+- nginx external routes require `nginx -T` to be executable and readable on the remote machine.
+
+## Development
+
+```bash
+pnpm install
+pnpm dev
+pnpm test
+pnpm build
+```
+
+Packaged CLI entry:
+
+```bash
+pnpm build
+node bin/yaport.js --help
+```

package/bin/yaport.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from "../dist/server/cli.js";
+
+await main();