catonline_ai/vw-agentic-rag/docs/topics/PORT_MANAGEMENT.md

端口管理工具

问题描述

在开发过程中，经常遇到端口被占用的问题，特别是：

• Next.js 开发服务器默认使用端口 3000
• 后端服务使用端口 8000
• 其他开发工具可能占用常用端口

解决方案

我们提供了多种自动化工具来处理端口占用问题：

1. 快速端口清理

单个端口清理：

./scripts/kill_port_auto.sh 3000

清理所有开发端口：

./scripts/clear_dev_ports.sh

2. 智能启动脚本

启动后端服务（自动处理端口冲突）：

./start_service.sh --dev

启动前端开发服务器（自动处理端口冲突）：

./scripts/start_web_dev.sh

3. Shell 函数和别名

将以下内容添加到你的 ~/.bashrc 或 ~/.zshrc：

# 加载端口管理函数
source /path/to/your/project/scripts/port_functions.sh

然后你可以使用：

# 检查端口使用情况
checkport 3000

# 杀死特定端口的进程
killport 3000

# 快速清理常用开发端口
killdevports

# 便捷别名
kp3000    # 杀死 3000 端口进程
kp8000    # 杀死 8000 端口进程
kp8002    # 杀死 8000 端口进程

工具说明

kill_port.sh

交互式端口清理工具，会显示进程信息并询问是否确认删除。

kill_port_auto.sh

自动端口清理工具，直接清理指定端口，无需确认。

clear_dev_ports.sh

批量清理常用开发端口（3000, 3001, 8000, 8001, 8000, 5000, 5001）。

start_web_dev.sh

智能前端启动脚本，自动处理端口冲突并启动 Next.js 开发服务器。

port_functions.sh

Shell 函数库，提供便捷的端口管理命令。

使用示例

场景1：Next.js 端口被占用

# 方法1：使用自动清理脚本
./scripts/kill_port_auto.sh 3000
cd web && pnpm dev

# 方法2：使用智能启动脚本
./scripts/start_web_dev.sh

# 方法3：使用 shell 函数（需要先加载）
killport 3000

场景2：批量清理开发环境

# 清理所有常用开发端口
./scripts/clear_dev_ports.sh

# 或者使用 shell 函数
killdevports

场景3：检查端口使用情况

# 检查特定端口
ss -tulpn | grep :3000

# 或者使用我们的函数
checkport 3000

注意事项

1. 权限：这些脚本会强制终止进程，请确保不会误杀重要进程
2. 数据保存：在清理端口前，请保存你的工作，因为进程会被强制终止
3. 系统兼容性：这些脚本在 Linux/WSL 环境中测试通过
4. 安全性：建议只在开发环境中使用这些工具

故障排除

端口仍然被占用

如果端口清理后仍然显示被占用，可能是：

1. 进程重启速度过快
2. 有系统级服务占用端口
3. 需要等待更长时间让系统释放端口

脚本权限问题

确保脚本有执行权限：

chmod +x scripts/*.sh

找不到进程信息

某些系统可能需要 root 权限才能查看所有进程信息。