g-baskin/port-scanner
GitHub: g-baskin/port-scanner
基于 Tauri 2 和 React 构建的 macOS 原生桌面应用，用于扫描和管理 TCP 监听端口、查看进程与系统资源指标，并支持一键终止进程或在浏览器中打开本地服务。
Stars: 1 | Forks: 1
# 端口扫描器
一款轻量级的 **macOS** 桌面应用，用于扫描 TCP 监听器、检查正在运行的进程、查看系统内存/磁盘指标、在浏览器中打开 `http://localhost:{port}`，并在你需要清爽状态时终止进程。使用 **Tauri 2**、**Vite**、**React** 和 **TypeScript** 构建。
## macOS 兼容性 (Apple Silicon 与 Intel)
- **Apple Silicon (M1 / M2 / M3 / M4 及更新机型)** — 完全支持。在 ARM Mac 上原生构建，或使用 Rust 的 `aarch64-apple-darwin` target。
- **Intel Mac** — 通过 `x86_64-apple-darwin` 支持。
- **macOS 版本** — 目标为 **macOS 11 (Big Sur)** 及更新版本（Tauri 2 基准）。使用最新的 Xcode Command Line Tools 以获得最佳效果。
通过 [rustup](https://rustup.rs/) 安装 Rust 并为你的 Mac 选择默认工具链；它会自动使用正确的架构。
### 可选：通用 macOS 二进制文件
为了发布一个能在 ARM 和 Intel 上同时运行的 `.app`，请分别构建各个架构并使用 `lipo` 合并（或使用 CI matrix）。示例概述：
```
rustup target add aarch64-apple-darwin x86_64-apple-darwin
# 使用 npm run tauri build -- --target 构建每个目标
# 然后使用 lipo 将主二进制文件合并为单个 bundle（参见 Tauri 文档中关于 universal builds 的内容）。
```
对于日常使用，在你的机器上进行单一架构的构建就足够了。
## 环境要求
- [Rust](https://rustup.rs/) (stable)
- **Node.js 22+** 和 **npm**
## 开发
```
git clone https://github.com/g-baskin/port-scanner.git
cd port-scanner
npm install
npm run tauri dev
```
UI 从 Vite dev server（端口 **1420**）加载；Tauri 打开原生窗口。
## 构建（发布版 `.app`）
这是一个**真正的 macOS 应用程序**（一个 `.app` bundle），而不是你日常使用中从 Terminal 运行的脚本。构建完成后，可以像其他任何程序一样将该应用拖入 **Applications（应用程序）**。
```
npm run tauri build
```
输出：
- `src-tauri/target/release/bundle/macos/PORT SCANNER - created by @g-baskin.app`
（名称遵循 [`src-tauri/tauri.conf.json`](src-tauri/tauri.conf.json) 中的 `productName`）
Bundle 配置仅使用 **`"targets": ["app"]`**（此处不生成 `.dmg`），以便 `tauri build` 能够可靠地完成，而不会出现在某些环境中可能会失败的 DMG 可选步骤。
将 `.app` 拷贝到 **/Applications** 或桌面。如果 Gatekeeper 提示，右键点击 → **打开**。
### 为什么构建的应用程序没有提交到这个 git repo 中
`.app` 有几十兆字节，并且每次构建都会改变。将其提交到 `main` 分支会**使 git 历史变得臃肿**，并遇到 GitHub 文件大小的限制。因此：
- **开发者：** 使用 `npm run tauri build` 在本地构建。
- **其他所有人：** 从 **GitHub Release** 安装（下方的 zip），或从 [Actions](https://github.com/g-baskin/port-scanner/actions) 下载 **CI artifact**。
### 从 GitHub Release 安装（推荐用于分享）
当维护者推送 **version tag** `v*`（例如 `v0.1.0`）时，[.github/workflows/release-macos.yml](.github/workflows/release-macos.yml) 会构建该应用程序，并创建一个附带 **`PortScanner-macos.zip`** 的 **Release**。
1. 打开 [Releases](https://github.com/g-baskin/port-scanner/releases)。
2. 从最新的 release 中下载 **`PortScanner-macos.zip`**。
3. 解压 → 你会得到 **`PORT SCANNER - created by @g-baskin.app`**。
4. 将该 `.app` 拖入 **/Applications**。
**在你的机器上创建新的 release：**
```
git pull origin main
git tag v0.1.0 # pick the next version
git push origin v0.1.0 # triggers the Release workflow
```
为每个 release 使用新的 tag（例如 `v0.1.1`、`v0.2.0`）。
## 功能
| 功能 | 描述 |
|--------|-------------|
| **端口视图** | TCP 监听器，包含进程、PID、端口、bind address、uptime、project folder、复制/打开/终止操作 |
| **进程视图** | 完整的进程列表，包含命令、uptime、project folder、listener 地址、复制/终止操作 |
| **系统视图** | 内存、磁盘、正在运行的进程数，以及监听进程数，无需重复进行 listener 扫描 |
| **仪表盘** | 实时数量和 uptime/系统摘要，可随当前视图/筛选条件变化 |
| **图表** | 每个 listener 的相对 uptime 条形图（可折叠） |
| **可排序列** | 点击端口表头进行排序（Excel 风格），切换升序/降序 |
| **筛选** | 搜索框，根据名称、PID、端口、bind、命令、project、cwd、uptime 缩小行范围 |
| **保护** | 🛡 每个 listener 行 — 阻止终止操作（存储在 localStorage 中） |
| **终止确认** | 执行 SIGKILL 前的 Modal 框；可在 ⚙ 设置中选择 **跳过** |
| **复制** | ⧉ 将行字段复制为制表符分隔的文本 |
| **在浏览器中打开** | 遵循 **http/https** 及可选的 **path**（⚙ 设置） |
| **自动刷新** | 工具栏：关闭 / 5秒 / 10秒 / 30秒 + **暂停** |
| **导出** | 导出当前筛选视图的 **CSV** / **JSON**；系统导出包含指标及可见进程 |
| **绑定到** | 易读的 bind，例如 `localhost:3001` 对比 `0.0.0.0:3001` |
| **终止** | 带有上次扫描得到的 PID 白名单的 `kill -9` |
| **以管理员扫描** | 可选的 `osascript` 提权，以获取更完整的 `lsof` 视图 |
| **仓库链接** | 点击标题栏中的 **@g-baskin** 即可在浏览器中打开此 GitHub 仓库 |
## 用户文档
### 布局
| 区域 | 用途 |
|------|---------|
| **标题栏** | 应用名称，指向源代码 repo 的 **@g-baskin** 链接，上次扫描使用提权时显示的 **admin** 徽章 |
| **头部操作** | **⚙ 设置**，**↻ 刷新**，**以管理员扫描** |
| **状态栏** | 选定视图的实时计数：端口/进程/系统指标 |
| **工具栏** | **端口 / 进程 / 系统** 切换器，**筛选** 框，**自动** 刷新间隔，**暂停**，**CSV** / **JSON** 导出 |
| **Uptime 图表** | 仅限端口视图；可折叠的条形图（uptime 最长的排在前面） |
| **表格** | 端口：每个 TCP listener 一行。进程/系统：每个进程一行。 |
| **页脚** | 总 listener 数（或筛选时的“显示 X / 共 Y 条”），admin/自动刷新提示 |
### 排序
点击任何可排序的列标题（**进程**、**PID**、**端口**、**绑定到**、**打开**）。第一次点击升序排序；再次点击**同一**列将反转为降序。点击新列总是从升序开始。当前活跃的列会显示 **▲** 或 **▼**。
### 筛选
在工具栏筛选框中输入内容以隐藏不匹配的行。匹配不区分大小写，检查内容包含进程名、PID、端口/listener、易读的 bind、原始地址、命令、project folder、cwd 和 uptime 文本。**导出** (CSV/JSON) 仅导出筛选后**你所能看到的行**。
### 保护 (🛡)
第一列用于切换该**确切 listener**（PID + 端口 + bind）的保护状态。当 🛡 开启时，该行的**终止**将被禁用（显示为 **—**）。受保护的行键保存在浏览器的 **localStorage** 中，键名为 `port-scanner-settings-v1`（参见下文的**设置与持久化**），因此它们在应用重启后依然有效。
### 终止与确认
**终止**向进程 PID 发送 `kill -9`（仅当它出现在最近的一次扫描中时）。除非你在 ⚙ 设置中启用了**跳过终止确认**，否则会出现一个**确认 Modal 框**。**取消**会关闭对话框；**终止**会继续执行。
### 复制 (⧉)
将一行以**制表符分隔**的文本复制到剪贴板：打开的 URL（遵循设置）、进程名、PID、端口和易读的 bind。非常适合粘贴到笔记、工单或电子表格中。
### 在浏览器中打开 (↗)
为该行的端口打开配置好的 URL：`{scheme}://localhost:{port}{optionalPath}`。默认为 `http://localhost:{port}`。可以在 ⚙ 设置中更改 scheme 和 path。
### 设置 (⚙)
| 选项 | 效果 |
|--------|--------|
| **在浏览器中打开** | `http://` 或 `https://` |
| **端口后的 URL path** | 可选后缀，例如 `/` 或 `/dashboard`（如果省略则自动添加前导 `/`） |
| **跳过终止确认** | 如果勾选，**终止**将立即执行，不弹出 Modal 框 |
### 设置与持久化
首选项和受保护的行以 JSON 格式存储在本地 **localStorage** 中：
- **键名：** `port-scanner-settings-v1`
- **字段：** `protectedRowKeys`（字符串数组）、`openScheme`、`openPath`、`autoRefreshSec`、`skipKillConfirm`
清除该应用的站点数据会将其移除。它们**不会**被同步到 GitHub 或任何服务器。
### 自动刷新
选择**关闭**、**5秒**、**10秒**或**30秒**。启用后，应用将按该间隔重新运行常规扫描，**不会**清除每行的终止状态。使用**暂停**可暂时挂起自动刷新。当自动刷新开启且未暂停时，页脚会显示 `auto Ns`。
### 导出
- **端口 CSV/JSON** — 每个可见 listener 一条记录。
- **进程 CSV/JSON** — 每个可见进程一条记录。
- **系统 CSV/JSON** — 系统指标加上可见进程。
文件下载时文件名中会包含时间戳。
### 扫描与终止（技术相关）
- 默认扫描：`lsof -n -P -iTCP -sTCP:LISTEN`
- **以管理员扫描**：通过 AppleScript **以管理员权限**（密码提示）执行相同命令。
- **终止**仅允许出现在**最近一次**扫描中的 PID（Rust 后端中的白名单）。
### GitHub Actions (CI)
每次推送到 `main` 分支时，[.github/workflows/build-macos.yml](.github/workflows/build-macos.yml) 都会：
1. 在 **macOS**（GitHub 托管的 runner）上检出 repo。
2. 安装 Node **22**，使用 [`rust-toolchain.toml`](rust-toolchain.toml) 中固定的 Rust 工具链，运行 `npm ci`、`cargo fmt --check`、`cargo clippy -D warnings`、`cargo test`、`npm run build`，然后运行 `npm run tauri build`，其中 **`CI`** 未设置（`CI: false`），以防止 Tauri CLI 错误解析 flags。
3. 将从 `src-tauri/target/release/bundle/macos/` 构建好的 **`.app`** 作为名为 `port-scanner-macos-app` 的工作流 **artifact** 上传。
该 artifact 与**固定的 macOS runner 的原生架构**相匹配。除非你自行添加 secrets 和步骤，否则它**不会**被进行代码签名或公证。
### GitHub Actions (CD — Releases)
当你**推送**与 `v*`（例如 `v0.1.0`）匹配的 tag 时，[.github/workflows/release-macos.yml](.github/workflows/release-macos.yml) 会运行与 CI 相同的格式化、lint、前端构建和 Tauri 构建门禁，然后将 `.app` 打包为 **`PortScanner-macos.zip`**，并创建一个附带该文件的 **GitHub Release**（`softprops/action-gh-release`）。这是在**不**将二进制文件存储在 git tree 中的情况下，发布“真实应用程序”供下载的受支持方式。
### 分发与代码签名 (macOS)
未签名的构建会为下载者触发 **Gatekeeper** 警告。要发布一个被广泛信任的 `.app`：
1. 加入 **Apple Developer Program**。
2. 在 Xcode 中，创建一个 **Developer ID Application** 证书。
3. 设置 Tauri 签名环境变量（`APPLE_CERTIFICATE`、`APPLE_CERTIFICATE_PASSWORD`、`APPLE_ID`、`APPLE_PASSWORD``APPLE_TEAM_ID`），并按照 [Tauri v2 — macOS 代码签名](https://v2.tauri.app/distribute/sign/macos/) 进行签名和公证。
本仓库**不**包含签名证书或密码；如果你扩展工作流，请在本地或作为**加密的 GitHub Actions secrets** 配置它们。
## Windows
**不支持。** Rust 后端使用 macOS 独有的工具（`lsof`、`osascript`、`/bin/kill`、`open`）。未来的 Windows 构建需要在相同的 Tauri 命令下使用替代实现（例如 `netstat` / Win API）。欢迎贡献。
## License — GPL-3.0
本项目基于 **GNU General Public License v3.0** 授权 — 详见 [LICENSE](LICENSE)。
简而言之：
- 你可以**使用、修改和销售**基于此代码的二进制文件或服务。
- 如果你**分发**了修改后的版本，你必须根据 GPL-3.0 向接收者**分享相应的源代码**，并**保留版权和许可声明**（包括 [NOTICE](NOTICE)）。
- 没有强制要求向本仓库发送 pull request，但你**绝不能**向获取你版本的人隐瞒源代码。
这不构成法律建议；请阅读完整的许可文本。
## 贡献
欢迎提交 Issues 和 pull requests。对于较大的更改，请先开一个 issue 以便我们在方法上达成一致（尤其是对于 Windows 支持）。
在提交之前，请运行：
```
npm run check
```
该命令将构建前端，检查 Rust 格式，运行拒绝警告的 Clippy，并运行 Rust 单元测试。
标签：React, Syscalls, Tauri, 可视化界面, 数据统计, 桌面应用, 端口扫描, 自动化攻击