# PortHub

**Repository Path**: grow-project/port-hub

## Basic Information

- **Project Name**: PortHub
- **Description**: Mac 本地服务监控工具 - 一站式管理 Homebrew 服务、Docker 容器和系统端口。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-29
- **Last Updated**: 2026-06-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PortHub

Mac 本地服务监控工具 - 一站式管理 Homebrew 服务、Docker 容器和系统端口。

## 功能

- 🖥️ **系统状态监控**：查看 CPU、内存、网络、磁盘、电池和系统运行时间
- 🍺 **Homebrew 服务管理**：查看、启动、停止、重启 brew 服务
- 🐳 **Docker 容器管理**：启停、查看日志、删除容器
- 🔍 **端口扫描**：查看所有监听中的 TCP 端口及对应进程
- 📊 **菜单栏常驻**：随时一键操作，无需打开主窗口
- 🔄 **自动刷新**：5 秒自动更新状态（可配置）

## 系统要求

- macOS 14.0 (Sonoma) 或更高
- Apple Silicon 或 Intel Mac
- 可选：Homebrew（管理 brew 服务）
- 可选：Docker Desktop（管理容器）

## 快速安装（一键脚本）

```bash
cd /Users/liuk/tests/PortHub
./build-and-install.sh
```

脚本会自动：
1. 安装 xcodegen（如果没有）
2. 生成 Xcode 项目
3. 编译 Release 版本
4. 安装到 `/Applications/PortHub.app`
5. 自动启动

⚠️ **首次启动**：macOS Gatekeeper 会拦截未签名应用，请到：
**系统设置 → 隐私与安全性 → 拉到底部 → 点击 "仍要打开 PortHub"**

## 在 Xcode 中开发

```bash
# 1. 安装 xcodegen
brew install xcodegen

# 2. 生成 Xcode 项目
xcodegen generate

# 3. 在 Xcode 中打开
open PortHub.xcodeproj

# 4. ⌘R 运行
```

## 手动创建 Xcode 项目（不用 xcodegen）

1. 打开 Xcode → File → New → Project
2. 选 **macOS → App**
3. 配置：
   - Product Name: `PortHub`
   - Team: None
   - Organization Identifier: `com.porthub`
   - Interface: **SwiftUI**
   - Language: **Swift**
4. 保存路径选 `/Users/liuk/tests/PortHub`（覆盖 PortHubApp.swift）
5. 删除自动生成的 `ContentView.swift`
6. 把本仓库 `PortHub/` 目录下所有 `.swift` 文件**拖进**项目（勾选 "Copy items if needed"）
7. **Target → Signing & Capabilities**：
   - Signing Certificate: **Sign to Run Locally**（不签名）
   - 添加 Entitlements 文件：`PortHub.entitlements`
8. **Target → Build Settings → Deployment**：
   - macOS Deployment Target: `14.0`
9. **Target → Info → Custom macOS Application Target Properties** 中添加：
   - `LSMinimumSystemVersion`: `14.0`
10. ⌘R 运行

## 项目结构

```
PortHub/
├── PortHub/
│   ├── App/                      # 入口、AppDelegate
│   ├── Core/
│   │   ├── Services/             # 业务服务（ShellExecutor、BrewService...）
│   │   ├── Models/               # 数据模型
│   │   └── Utils/                # 工具类（Logger）
│   ├── Features/
│   │   ├── Dashboard/            # 主窗口
│   │   ├── Brew/                 # Brew 视图
│   │   ├── Docker/               # Docker 视图
│   │   ├── Ports/                # 端口扫描视图
│   │   ├── MenuBar/              # 菜单栏 UI
│   │   └── Settings/             # 偏好设置
│   └── Resources/                # Info.plist / Entitlements
├── project.yml                   # XcodeGen 配置
├── build-and-install.sh          # 一键编译安装脚本
└── README.md
```

## 关键技术点

### 1. PATH 问题（最大的坑）

macOS GUI 应用启动时，`PATH` **不包含** `/opt/homebrew/bin`，导致直接调用 `brew` / `docker` 会找不到命令。

`ShellExecutor` 中通过**手动注入完整 PATH** 解决：

```swift
private static let augmentedPATH = [
    "/opt/homebrew/bin", "/opt/homebrew/sbin",    // Apple Silicon
    "/usr/local/bin", "/usr/local/sbin",          // Intel
    "/usr/bin", "/bin", "/usr/sbin", "/sbin",
    "/Applications/Docker.app/Contents/Resources/bin"
].joined(separator: ":")
```

### 2. 沙盒必须关闭

`PortHub.entitlements`:
```xml
<key>com.apple.security.app-sandbox</key>
<false/>
```

否则无法用 `Process` 调用外部命令，也就无法上 **Mac App Store**（这是预期的，走 Developer ID 分发）。

### 3. 菜单栏 + 主窗口架构

使用 SwiftUI `MenuBarExtra` + `WindowGroup` 组合：
- 默认 `.accessory` 模式（只在菜单栏，无 Dock 图标）
- 打开主窗口时切换为 `.regular`

### 4. 系统状态采样

CPU、内存、网络、磁盘、电池均使用 macOS 公开 API（Mach / sysctl / getifaddrs / IOKit），不依赖 `top` / `vm_stat` / `iostat` 等 shell 命令，避免菜单栏常驻时频繁 fork 子进程。

这些 API 在 Apple Silicon 和 Intel Mac 上通用；项目未限定 `ARCHS`，默认构建为 `arm64 + x86_64` Universal Binary。

## 路线图

- [x] v1.0 - Brew/Docker/端口 基础功能
- [ ] v1.1 - 服务日志实时流（`docker logs -f`）
- [ ] v1.2 - 告警（端口异常推送通知）
- [ ] v1.3 - 自定义服务（非 brew 安装的进程）
- [ ] v1.4 - Docker Compose 项目支持
- [ ] v2.0 - 代码签名 + 公证 + Sparkle 自动更新

## 常见问题

**Q: 启动后菜单栏没图标？**
A: 检查 macOS 顶部菜单栏右侧的服务器图标。如果菜单栏过满，部分图标会被隐藏，可拖动调整。

**Q: 提示 "brew 命令未找到"？**
A: 确认 `/opt/homebrew/bin/brew`（Apple Silicon）或 `/usr/local/bin/brew`（Intel）存在。

**Q: Docker 显示 "未运行"？**
A: 确认 Docker Desktop 已启动，执行 `docker info` 应返回服务器信息。

**Q: 应用无法打开（"已损坏"）？**
A: 运行 `xattr -cr /Applications/PortHub.app` 移除 quarantine 属性。