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

# 端口管理工具

## 问题描述

在开发过程中，经常遇到端口被占用的问题，特别是：
- Next.js 开发服务器默认使用端口 3000
- 后端服务使用端口 8000
- 其他开发工具可能占用常用端口

## 解决方案

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

### 1. 快速端口清理

**单个端口清理：**
```bash
./scripts/kill_port_auto.sh 3000
```

**清理所有开发端口：**
```bash
./scripts/clear_dev_ports.sh
```

### 2. 智能启动脚本

**启动后端服务（自动处理端口冲突）：**
```bash
./start_service.sh --dev
```

**启动前端开发服务器（自动处理端口冲突）：**
```bash
./scripts/start_web_dev.sh
```

### 3. Shell 函数和别名

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

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

然后你可以使用：

```bash
# 检查端口使用情况
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 端口被占用

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

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

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

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

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

# 或者使用 shell 函数
killdevports
```

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

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

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

## 注意事项

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

## 故障排除

### 端口仍然被占用
如果端口清理后仍然显示被占用，可能是：
1. 进程重启速度过快
2. 有系统级服务占用端口
3. 需要等待更长时间让系统释放端口

### 脚本权限问题
确保脚本有执行权限：
```bash
chmod +x scripts/*.sh
```

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