Portstack - 本地端口管理器

自动发现端口冲突、定位占用进程、按策略释放/迁移端口，提供可脚本化/可交互的管理能力

产品目标

解决本地开发/运行时常见的 port 冲突问题：

发现 → 定位 → 处理（kill/迁移/分配新端口）→ 记录

支持在脚本、CI、本地启动流程中一键接入。

功能特性

| 命令 | 用途 | |------|------| | portstack doctor | 扫描配置端口，输出冲突报告和建议 | | portstack who <port> | 查询占用某端口的进程信息 | | portstack free <port> | 释放被占用的端口（可交互确认/强制/dry-run） | | portstack pick | 从指定范围挑选可用端口 | | portstack bind <name> <port> | 绑定项目与推荐端口 | | portstack list | 查看绑定与历史记录 | | portstack config get|set | 读写全局配置 | | portstack init | 自动扫描项目配置并生成 .portmanrc |

使用 npx（推荐）

无需安装，直接运行：

# 查端口被谁占用
npx portstack who 3000

# 挑选可用端口
npx portstack pick --range 3000-3999 --count 3

# 扫描冲突
npx portstack doctor

# 释放端口（会询问确认）
npx portstack free 3000

# 自动扫描项目配置并生成 .portmanrc
npx portstack init
npx portstack init --dry-run   # 仅预览
npx portstack init --force     # 覆盖已有配置
npx portstack init --merge     # 与已有配置合并
npx portstack init --root packages/web  # Monorepo 子包

快速开始

# 方式一：npx 直接运行（推荐）
npx portstack who 3000

# 方式二：从本地目录使用 npx
cd /path/to/portstack
npx . who 3000

# 方式三：本地安装后使用
npm install
npm run build
npm link
portstack who 3000

# 方式四：全局安装后直接使用
npm install -g portstack
portstack who 3000

# 检查 3000 端口被谁占用
portstack who 3000

# 在 3000-3999 范围内挑选 3 个可用端口
portstack pick --range 3000-3999 --count 3

# 扫描项目配置的端口（需在项目目录下有 .portmanrc）
portstack doctor

# 释放 3000 端口（默认会询问确认）
portstack free 3000
portstack free 3000 --force   # 强制释放，不询问
portstack free 3000 --dry-run # 仅预览，不实际执行

配置说明

项目配置 .portmanrc

{
  "apps": [
    { "name": "web", "preferredPort": 3000, "range": "3000-3099" },
    { "name": "api", "preferredPort": 8080, "range": "8080-8099" }
  ],
  "policy": {
    "onConflict": "ask",
    "killWhitelist": ["node", "python"],
    "killBlacklist": ["system", "launchd"]
  }
}

配置优先级

CLI 参数 > 项目配置 .portmanrc > 全局配置 ~/.portman/config.json > 默认值

输出格式

• 默认：人类可读格式
• --json：机器可读 JSON，便于脚本消费
• --pretty：格式化 JSON（默认 --json 时为紧凑格式）

技术架构

packages/
├── src/
│   ├── cli/           # CLI 命令入口
│   ├── core/          # 核心逻辑
│   │   ├── scanner.ts   # 端口检测
│   │   ├── resolver/   # 进程解析（平台适配）
│   │   ├── policy.ts   # 策略引擎
│   │   └── config.ts   # 配置管理
│   └── utils/         # 工具函数
└── bin/               # CLI 入口

支持的平台

• macOS：优先支持，使用 lsof
• Linux：支持，使用 ss / lsof
• Windows：支持，使用 netstat -ano + tasklist

里程碑

• M1：CLI 骨架 + who + pick（纯检测与挑选）✅
• M2：free + 策略（ask/force/dry-run）+ 日志 ✅
• M3：doctor + .portmanrc + 绑定/历史 ✅
• M4（可选）：watch / 本地 API

产品决策（已确认）

1. 主要运行平台：三端都支持，macOS/Linux 体验更完整
2. 解决冲突默认动作：ask（安全优先）
3. 守护进程 watch + API：先不做，等 CLI 稳定

实现状态（当前版本）

• ✅ who、pick、free、doctor、bind、list、config 已全部实现
• ✅ 跨平台支持：macOS、Linux、Windows
• ✅ 配置文件：.portmanrc、~/.portman/config.json
• ✅ 操作日志：~/.portman/actions.log
• ⏳ move 端口迁移（生成建议）：待实现
• ⏳ watch 常驻监听：待实现

License

MIT