Smart Port Allocation

智能端口分配助手

任务目标

• 本 Skill 用于：根据项目名称自动生成可记忆且不易冲突的端口号
• 能力包含：键盘映射算法、端口合法性验证、候选端口智能选择、多端口策略支持
• 触发条件：启动本地多个服务、配置项目前后端端口、微服务架构端口分配

前置准备

• 无需安装额外依赖，使用 npx 直接调用 port-key 工具
• 确保系统已安装 Node.js 和 npm（port-key 通过 npx 自动下载和执行）

操作步骤

• 标准流程：

1. 处理项目名称

• 短名称规则：如果项目名称较短（1-2 个单词或 1-8 个字母），直接使用完整名称
• 示例："dashboard" → "dashboard"
• 示例："myapp" → "myapp"
• 长名称规则：如果项目名称较长（多个单词或超过 8 个字母），提取每个单词的首字母
• 示例："我爱我家" → "wawj"
• 示例："user authentication service" → "uas"
• 示例："ecommerce payment gateway" → "epg"
• 示例："enterprise resource planning system" → "erps"
• 混合语言支持：自动识别中英文，提取拼音或英文字母的首字母

2. 生成单个项目端口

• 使用 npx 调用 port-key 工具
• 示例：npx -y @lionad/port-key "myproject" → 默认配置下输出 7604
• 智能体将解析返回结果，向用户说明端口号及其含义

3. 处理多组件场景

• 对于需要多个端口的项目（前端、后端、数据库等），使用以下两种策略之一：
• 角色前缀法：将角色放到名称开头，确保角色参与前缀映射（更容易产生不同端口）
• 前端：fe-<project>
• 后端：api-<project>
• 数据库：db-<project>
• 顺序分配法：使用基础端口，然后连续分配
• Web 服务：基础端口
• 后端 API：基础端口 + 1
• 数据库：基础端口 + 2

4. 端口冲突处理

• 检查生成的端口是否与本地运行服务冲突
• 如有冲突，将冲突端口加入 ~/.port-key/config.json 的 blockedPorts 后重试（或临时设置 PORTKEY_HOME 指向一个独立目录）

• 可选分支：
• 当项目名称很短（1-3 字母）：工具自动启用零填充策略生成指定位数端口
• 当项目名称很长（多个单词）：自动提取首字母（如 "我爱我家" → "wawj"）
• 当需要特定端口范围：通过 ~/.port-key/config.json 配置 minPort、maxPort
• 当需要屏蔽某些端口：通过 ~/.port-key/config.json 配置 blockedPorts

资源索引

• 领域参考：见 references/port-key.md（何时读取：需要了解 port-key 工具的详细参数、使用方法或输出格式时）
• 领域参考：见 references/port-best-practices.md（何时读取：需要端口分配策略建议或避免冲突的最佳实践时）

注意事项

• 端口范围必须在 1024-65535 之间（系统端口 0-1023 被屏蔽）
• 生成的端口号仅作为建议，实际使用前请验证端口是否可用
• 端口分配策略应保持团队内部一致，便于记忆和管理
• 多项目开发时建议记录端口分配情况，避免重复
• 使用 npx -y 可自动确认下载，避免交互式提示
• 长项目名称处理：智能体会自动提取首字母，也可手动指定简短名称（如将 "用户认证服务" 指定为 "uas"）
• 首字母规则：英文单词取首字母，中文取拼音首字母，保持可读性和记忆性

使用示例

示例 1：单个项目端口分配（短名称）

场景：启动一个名为 "dashboard" 的新项目 执行方式：使用 npx 调用工具

npx -y @lionad/port-key "dashboard"

输出示例：

3126

智能体说明：默认配置下，项目名称 "dashboard" 通过键盘映射生成端口号 3126。工具只做端口范围与屏蔽列表校验，不检测端口是否被占用。

示例 1.1：单个项目端口分配（长名称 - 自动提取首字母）

场景：启动一个名为 "用户认证服务" 的新项目 智能体处理：自动提取首字母 "uas"（User Authentication Service） 执行方式：

npx -y @lionad/port-key "uas"

输出示例：

7120

智能体说明：项目名称 "用户认证服务" 较长，已提取首字母 "uas" 生成端口号 7120（短输入默认会尾部补 0 到 4 位）。

示例 2：多组件项目端口分配

场景：全栈项目需要前端、后端、数据库三个端口 执行方式：使用角色前缀策略（默认配置下更容易生成不同端口）

# 1. 生成基础端口
npx -y @lionad/port-key "myapp"
# 默认输出：7610

# 2. 前端：角色前缀
npx -y @lionad/port-key "fe-myapp"
# 示例输出：4376

# 3. 后端：角色前缀
npx -y @lionad/port-key "api-myapp"
# 示例输出：1087

# 4. 数据库：角色前缀
npx -y @lionad/port-key "db-myapp"
# 示例输出：3576

示例 3：避免端口冲突

场景：已知端口 3000、3001 已被占用 执行方式：将占用端口加入配置文件的屏蔽列表，然后重新生成

# ~/.port-key/config.json（示例）
# { "blockedPorts": [3000, 3001, 8080] }

npx -y @lionad/port-key "blog"

智能体说明：工具不会检测端口是否被占用；“已占用”需要由智能体用系统命令检查，并把冲突端口加入 blockedPorts 后再生成。

示例 4：指定位数和语言

场景：需要 5 位端口号，且希望显示英文输出 执行方式：使用 --digits 和 --lang 参数

npx -y @lionad/port-key "myproject" --digits 5 --lang en

示例 5：长项目名称处理（中文）

场景：处理中文项目名称 "我爱我家" 智能体处理：自动提取拼音首字母 "wawj" 执行方式：

npx -y @lionad/port-key "wawj"

输出示例：

2127

智能体说明：默认配置下，项目名称 "我爱我家"（Wǒ Ài Wǒ Jiā）已提取首字母 "wawj"，生成端口号 2127。

示例 6：长项目名称处理（英文）

场景：处理英文长项目名称 "Enterprise Resource Planning System" 智能体处理：自动提取首字母 "erps" 执行方式：

npx -y @lionad/port-key "erps"

输出示例：

3402

智能体说明：默认配置下，项目名称 "Enterprise Resource Planning System" 已提取首字母 "erps"，生成端口号 3402。

端口分配最佳实践

目录

• 端口分类与规范
• 本地开发端口分配策略
• 避免端口冲突的方法
• 团队协作与文档管理
• 常见问题排查

概览

本文档提供端口分配的最佳实践指南，帮助开发者在本地开发和团队协作中有效管理端口资源，避免端口冲突，提升开发效率。

端口分类与规范

端口范围划分

• 系统端口（0-1023）：由 IETF 分配，需要 root 权限，严格禁止使用
• 用户端口（1024-49151）：由 IANA 分配，注册服务使用，谨慎使用
• 动态/私有端口（49152-65535）：未分配，临时使用最安全

推荐端口范围

• 常规开发：3000-3999 或 8000-8999
• 微服务集群：5000-5999 或 9000-9999
• 测试环境：10000-19999
• 注意（PortKey 默认）：PortKey 默认会屏蔽一批常见端口（如 3000、3001、5173、8080 等）；若团队强制使用某些端口段，建议在 ~/.port-key/config.json 中统一 blockedPorts/minPort/maxPort。

本地开发端口分配策略

单项目场景

原则：一个项目使用一个主端口，根据项目特性选择范围

• 前端项目：推荐 3000-3999（如 3000, 3173, 3333）
• 后端服务：推荐 8000-8999（如 8000, 8080, 8765）
• 数据库：使用标准端口或 5000-5999（如 5432, 5701）

多组件项目场景

策略 A：角色前缀法（推荐） 将角色放到名称开头，确保角色参与端口映射的前缀候选，减少“多个组件映射到同一端口”的概率。

示例项目 "shop"
- 基础端口：2690（shop）
- 前端：4326（fe-shop）
- 后端：1082（api-shop）
- 数据库：3526（db-shop）

策略 B：顺序分配法 从基础端口开始连续分配

示例项目 "shop"
- 基础端口：2690
- 前端：2690
- 后端：2691
- 数据库：2692

说明：

• PortKey 默认会优先取 4 位候选；当项目名本体已经足够生成 4 位候选时，简单追加后缀（如 <project>-db）可能不会影响“最先被选中的候选”，导致多个组件仍然得到同一个端口。
• 如需使用“角色后缀法”，建议结合 preferDigitCount: 5（配置文件）或直接使用“角色前缀法”。

微服务架构场景

原则：使用命名约束 + 范围隔离

1. 按功能模块划分端口段

   用户服务：10000-10099
   订单服务：10100-10199
   支付服务：10200-10299

2. 使用项目前缀 + 功能标识

   user-auth：10001
   user-profile：10002
   order-create：10101
   order-query：10102

3. 预留端口段

• 预留 20% 的端口空间用于扩展
• 使用高位端口作为备用（如 19990-19999）

避免端口冲突的方法

冲突预防

1. 使用端口映射工具

• 使用 smart-port-allocation Skill 生成基于项目名称的唯一端口
• 端口号与项目名称绑定，可预测且更少随机冲突（仍可能发生碰撞，需配合屏蔽列表/范围管理）

2. 端口范围隔离

• 不同类型服务使用不同端口段
• 开发/测试/生产环境使用不同范围

3. 端口记录与追踪

• 维护端口使用清单（见下文团队协作章节）

冲突检测

1. 启动前检查

   # 检查端口是否被占用（Linux/Mac）
   lsof -i :<port>

   # 检查端口是否被占用（Windows）
   netstat -ano | findstr :<port>

2. 定期审计

• 定期扫描常用端口段（3000-3999, 8000-8999）
• 识别僵尸进程和未释放的端口

3. 使用智能工具

• 集成端口检测到启动脚本（PortKey 本身不检测端口占用）
• 冲突时将端口加入 ~/.port-key/config.json 的 blockedPorts，再重新生成

冲突解决

1. 短期方案：临时调整端口，记录变更 2. 长期方案：重新规划端口分配策略，统一调整 3. 根本方案：使用容器化技术（Docker）隔离端口空间

团队协作与文档管理

端口使用文档模板

创建 PORTS.md 文件记录端口分配情况：

# 项目端口分配清单

## 项目概述
- 示例项目：shop
- 端口策略：角色前缀法（`fe-` / `api-` / `db-`）

## 端口分配表

| 服务名称 | 端口 | 说明 | 负责人 |
|---------|-----|------|--------|
| 前端商城 | 4326 | Vue3 应用 | 张三 |
| 后端 API | 1082 | Node.js 服务 | 李四 |
| 数据库   | 3526 | MongoDB | 王五 |
| 缓存服务 | 4338 | Redis | 王五 |

## 端口范围
- 角色前缀法下端口可能分散，建议记录“具体端口”而不是强行划分连续端口段
- 若使用顺序分配法，可将同一项目的一组端口规划为连续段（如 2690-2699）

## 注意事项
- 避免使用 3000, 8080 等常见端口
- 新服务优先使用未分配端口
- 端口变更需更新此文档

端口分配流程

1. 新项目启动

• 使用 smart-port-allocation Skill 生成端口
• 检查端口是否可用
• 更新 PORTS.md 文档

2. 项目交接

• 移交 PORTS.md 文档
• 说明端口分配策略和注意事项
• 交接后验证端口可用性

3. 定期审计

• 每季度检查端口使用情况
• 清理僵尸项目端口
• 优化端口分配策略

常见问题排查

问题 1：端口被占用

症状：启动服务时提示 "Address already in use"

排查步骤： 1. 使用 lsof -i :<port> 查看占用进程 2. 判断占用进程类型：

• 如果是同一服务的旧实例：kill 进程重新启动
• 如果是其他服务：选择新端口或调整其他服务

3. 更新端口文档记录

问题 2：端口映射不一致

症状：不同机器上同一项目使用不同端口

原因：

• 未使用标准化端口分配工具
• 团队成员各自随机选择端口
• 使用了不同的用户配置（如 preferDigitCount、blockedPorts、minPort/maxPort）

解决方案： 1. 统一使用 smart-port-allocation Skill 2. 将端口配置写入项目 package.json 或 .env 文件 3. 纳入代码审查，确保端口配置正确 4. 团队统一 ~/.port-key/config.json 的关键配置（或在启动脚本中用 PORTKEY_HOME 指定同一份配置）

问题 3：端口范围耗尽

症状：可用端口用完，无法为新服务分配端口

解决方案： 1. 审计现有端口使用情况，清理僵尸服务 2. 扩展端口范围（如从 3000-3999 扩展到 3000-4999） 3. 使用容器化技术，通过端口映射复用端口

问题 4：跨平台端口兼容性

症状：Windows 和 Linux/macOS 端口行为不一致

解决方案： 1. 避免使用系统端口（0-1023） 2. 使用 1024-65535 范围内的端口 3. 在 CI/CD 中验证端口配置

总结

关键原则

1. 可预测性：端口分配应有规律可循，便于记忆 2. 唯一性：同一端口不应被多个服务占用 3. 文档化：所有端口分配都应记录在案 4. 团队一致：团队内部应使用统一的分配策略 5. 自动化：使用工具生成端口，减少人为错误

推荐工作流

1. 新项目启动 → 使用 Skill 生成端口 2. 验证端口可用性 → 更新 PORTS.md 3. 定期审计 → 优化端口分配策略 4. 团队协作 → 保持文档同步

工具推荐

• 智能端口分配：smart-port-allocation Skill
• 端口检测：lsof, netstat
• 进程管理：kill, taskkill
• 容器隔离：Docker, Docker Compose

PortKey 工具使用指南

目录

• 工具简介
• 安装与执行
• 核心参数说明
• 使用示例
• 输出格式
• 高级用法
• 常见问题

工具简介

PortKey 是一个基于键盘映射的端口生成工具，通过将项目名称的字母映射为数字，生成可记忆且不易冲突的端口号。

核心原理

• 使用标准 QWERTY 键盘布局，将字母映射到数字
• 根据字母在键盘上的行列位置确定对应数字
• 自动处理端口合法性验证（端口范围与屏蔽列表）
• 名称处理：长项目名称/中文名称的首字母提取由智能体或调用方完成

键盘映射规则

1: qaz   2: wsx   3: edc   4: rfv   5: tgb
6: yhn   7: ujm   8: ik    9: ol    0: p

示例：

• cfetch → c(3) f(4) e(3) t(5) c(3) h(6) → 343536 → 默认输出 3435（取 4 位候选）

项目名称处理规则

• 短名称（1-2 个单词或 ≤8 个字母）：直接使用
• "dashboard" → "dashboard"
• "myapp" → "myapp"
• 长名称（多个单词或 >8 个字母）：提取首字母
• "我爱我家"（Wǒ Ài Wǒ Jiā）→ "wawj"
• "user authentication service" → "uas"
• "enterprise resource planning system" → "erps"
• "ecommerce payment gateway" → "epg"
• 混合语言：自动识别中英文，提取拼音或英文字母首字母

安装与执行

使用 npx（推荐）

无需预安装，直接使用 npx 自动下载和执行：

npx -y @lionad/port-key <project-name>

参数说明

• -y: 自动确认，跳过下载确认提示
• @lionad/port-key: npm 包名

核心参数说明

必需参数

• project-name: 项目名称（必填）
• 支持字母和数字
• 自动转换为小写
• 推荐使用简短名称（1-8 个字母）以获得最佳效果
• 示例："myproject", "dashboard", "shop", "wawj"（"我爱我家"的首字母）
• 注意：PortKey 工具本身不处理中文或长名称，首字母提取由智能体完成

可选参数

--digits <count> 或 -d <count>

设置端口号的位数

• 可选值: 4, 5
• 默认值: 4
• 说明: 优先生成指定位数的端口号

示例：

npx -y @lionad/port-key "myproject" --digits 4   # 生成 4 位端口
npx -y @lionad/port-key "myproject" --digits 5   # 生成 5 位端口

--lang <code>

设置输出语言

• 可选值: en, cn
• 默认值: cn
• 说明: 控制日志消息的语言

示例：

npx -y @lionad/port-key "myproject" --lang en
npx -y @lionad/port-key "myproject" --lang cn

--map <object>

自定义键盘映射

• 格式: JSON 或 JS 对象字面量
• 默认值: 标准 QWERTY 映射
• 说明: 自定义字母到数字的映射关系

示例：

npx -y @lionad/port-key "myproject" --map '{"1":"abc","2":"def"}'

使用示例

基础用法

# 生成默认 4 位端口
npx -y @lionad/port-key "myproject"
# 输出: 7604

# 生成 5 位端口
npx -y @lionad/port-key "myproject" --digits 5
# 无法从输入生成有效端口。
# Rejected candidates:
#   76049: Invalid port number
#   97335: Invalid port number

首字母提取示例（智能体处理）

# 长项目名称：用户认证服务 → 提取 "uas"
npx -y @lionad/port-key "uas"
# 输出: 7120

# 长项目名称：我爱我家 → 提取 "wawj"
npx -y @lionad/port-key "wawj"
# 输出: 2127

# 长项目名称：Enterprise Resource Planning System → 提取 "erps"
npx -y @lionad/port-key "erps"
# 输出: 3402

注意：首字母提取由智能体完成，PortKey 工具只接收处理后的简短名称。

端口范围与屏蔽列表（通过配置文件）

PortKey CLI 不提供 --min-port/--max-port/--blocked-ports 参数；如需限制范围或屏蔽端口，请使用用户配置文件（见下文“配置文件”）。

多组件项目

# 1. 生成基础端口
npx -y @lionad/port-key "myapp"
# 输出: 7610

# 2. 前端服务（角色前缀更容易生成不同端口）
npx -y @lionad/port-key "fe-myapp"
# 输出: 4376

# 3. 后端服务
npx -y @lionad/port-key "api-myapp"
# 输出: 1087

# 4. 数据库
npx -y @lionad/port-key "db-myapp"
# 输出: 3576

处理短项目名

# 短项目名会自动填充零
npx -y @lionad/port-key "air" --digits 4
# 输出: 1840

# 长项目名截取指定位数
npx -y @lionad/port-key "dashboard" --digits 4
# 输出: 3126

处理长项目名（配合智能体）

# 智能体将长名称转换为首字母后调用
# 例如："用户认证服务" → "uas"
npx -y @lionad/port-key "uas"
# 输出: 7120

# 例如："电子商务支付网关" → "epg"
npx -y @lionad/port-key "epg"
# 输出: 3050

# 例如："Customer Relationship Management System" → "crms"
npx -y @lionad/port-key "crms"
# 输出: 3472

输出格式

标准输出

默认情况下，PortKey 输出生成的端口号（纯数字）：

$ npx -y @lionad/port-key "myproject"
# 输出 7604

首次运行且本机没有配置文件时，CLI 可能会在 stderr 打印一段提示信息；stdout 仍然只输出端口号，脚本中建议用命令替换读取 stdout（如 PORT=$(...)）。

详细输出（MCP 模式）

当作为 MCP server 使用时（@lionad/port-key-mcp），会返回 JSON 格式的详细信息：

{
  "digits": "760497335",
  "port": 7604,
  "rejectedCandidates": []
}

字段说明：

• digits: 映射后的数字序列
• port: 最终选择的端口号
• rejectedCandidates: 被拒绝的候选端口列表（如有）

高级用法

配置文件

PortKey 会从 ~/.port-key/config.json 读取用户配置：

{
  "preferDigitCount": 5,
  "paddingZero": true,
  "blockedPorts": [3000, 3001, 6666],
  "minPort": 1024,
  "maxPort": 49151
}

也可以通过环境变量 PORTKEY_HOME 指定配置目录（目录下仍使用 .port-key/config.json）。

MCP Server 集成

将 PortKey 作为 MCP server 使用：

{
  "mcpServers": {
    "port-key": {
      "command": "npx",
      "args": ["@lionad/port-key-mcp"]
    }
  }
}

批量生成端口

在 Shell 脚本中批量生成端口：

#!/bin/bash
projects=("project-a" "project-b" "project-c")

for project in "${projects[@]}"; do
  port=$(npx -y @lionad/port-key "$project")
  echo "$project: $port"
done

集成到启动脚本

将端口生成集成到项目启动脚本：

#!/bin/bash
PROJECT_NAME="myapp"

# 生成端口
PORT=$(npx -y @lionad/port-key "$PROJECT_NAME")

# 启动服务
export PORT=$PORT
npm start

常见问题

Q1: 为什么生成的端口不在期望的范围内？

A: 检查以下几点： 1. 检查 ~/.port-key/config.json 中的 minPort/maxPort 配置（如有） 2. 检查 blockedPorts 是否屏蔽了范围内的端口 3. 确认期望范围在 1024-65535 之间（0-1023 始终被屏蔽）

Q2: 短项目名生成的端口位数不足？

A: 使用 --digits 参数指定位数，工具会自动填充零：

npx -y @lionad/port-key "air" --digits 4

Q3: 长项目名称如何处理？

A: 智能体会自动处理长项目名称：

• 中文长名称：提取拼音首字母，如 "我爱我家" → "wawj"
• 英文长名称：提取单词首字母，如 "User Authentication Service" → "uas"
• 也可以手动指定简短名称，如使用 "uas" 代替 "用户认证服务"
• 首字母提取后，由智能体调用 PortKey 生成端口

Q4: 如何验证生成的端口是否可用？

A: 使用以下命令检查端口占用：

# Linux/Mac
lsof -i :<port>

# Windows
netstat -ano | findstr :<port>

Q5: 能否自定义键盘映射？

A: 可以使用 --map 参数自定义：

npx -y @lionad/port-key "myproject" --map '{"1":"abc","2":"def"}'

Q6: 多组件项目如何分配端口？

A: 推荐两种方式： 1. 角色前缀法：fe-myapp, api-myapp, db-myapp 2. 顺序分配法：基础端口、基础+1、基础+2

详细策略见 port-best-practices.md

Q7: 生成的端口与现有服务冲突怎么办？

A: PortKey 不检测端口占用；请先用系统命令确认冲突端口，然后将冲突端口加入 ~/.port-key/config.json 的 blockedPorts 后重试（或换用不同的项目名/角色前缀）。

Q8: 如何在团队中统一端口分配？

A: 建议遵循以下步骤： 1. 使用相同的工具和参数 2. 在文档记录端口分配 3. 使用版本管理端口配置 4. 定期审计端口使用情况 5. 统一首字母规则：团队内部统一长项目名称的首字母提取规则

相关文档

• 端口分配最佳实践：详细的端口分配策略和团队协作指南
• PortKey GitHub：https://github.com/Lionad-Morotar/port-key