docs/PORT_MANAGEMENT.md

端口管理指南

端口占用问题说明

常见原因

1. 进程未完全退出

   • 使用 Ctrl+C 后进程可能仍在后台运行
   • 子进程没有被正确清理

2. TCP TIME_WAIT 状态

   • TCP连接关闭后会进入 TIME_WAIT 状态
   • 通常持续 30-120 秒
   • 这是 TCP 协议的正常行为

3. 多个实例运行

   • 启动了多个程序实例
   • 没有正确关闭之前的实例

解决方案

方法1: 使用提供的脚本（推荐）

# 清理7860端口
./kill_port.sh 7860

# 或清理其他端口
./kill_port.sh 8000

方法2: 手动清理

查找占用端口的进程

# 方法1: 使用 lsof
sudo lsof -i:7860

# 方法2: 使用 netstat
sudo netstat -tlnp | grep 7860

# 方法3: 使用 ss
sudo ss -tlnp | grep 7860

# 方法4: 使用 fuser
sudo fuser 7860/tcp

杀死进程

# 如果知道进程ID (PID)
kill -9 <PID>

# 一行命令清理端口
sudo lsof -ti:7860 | xargs kill -9

# 或使用 fuser
sudo fuser -k 7860/tcp

方法3: 使用改进后的 app.py

新版本的 app.py 已经实现了：

1. 端口复用 (SO_REUSEADDR 和 SO_REUSEPORT)

   • 避免 "Address already in use" 错误
   • 允许快速重启服务

2. 信号处理

   • 捕获 SIGINT (Ctrl+C) 和 SIGTERM 信号
   • 优雅关闭服务器，释放端口

3. 自动端口清理

   • 启动时检查端口占用
   • 尝试自动清理占用的进程

预防措施

1. 正确停止服务器

# 使用 Ctrl+C 停止
# 程序会捕获信号并优雅退出

# 或发送 SIGTERM 信号
kill -15 <PID>

2. 使用进程管理器

systemd（生产环境推荐）

# 创建 systemd 服务文件
sudo nano /etc/systemd/system/learning-app.service

[Unit]
Description=Interactive Learning App
After=network.target

[Service]
Type=simple
User=zhangl
WorkingDirectory=/data/zhangl/code/hf/point
ExecStart=/usr/bin/python3 /data/zhangl/code/hf/point/app.py
Restart=on-failure
KillMode=mixed
KillSignal=SIGTERM
TimeoutStopSec=5

[Install]
WantedBy=multi-user.target

# 启用并启动服务
sudo systemctl daemon-reload
sudo systemctl enable learning-app
sudo systemctl start learning-app

# 管理服务
sudo systemctl stop learning-app      # 停止
sudo systemctl restart learning-app   # 重启
sudo systemctl status learning-app    # 查看状态

supervisor（备选方案）

[program:learning-app]
directory=/data/zhangl/code/hf/point
command=python3 app.py
autostart=true
autorestart=true
user=zhangl
redirect_stderr=true
stdout_logfile=/var/log/learning-app.log
stopasgroup=true
killasgroup=true

3. 使用虚拟终端

# 使用 screen
screen -S learning-app
python3 app.py
# 按 Ctrl+A 然后 D 分离会话

# 重新连接
screen -r learning-app

# 使用 tmux
tmux new -s learning-app
python3 app.py
# 按 Ctrl+B 然后 D 分离会话

# 重新连接
tmux attach -t learning-app

常用命令汇总

# 查看所有监听的端口
sudo netstat -tlnp

# 查看所有Python进程
ps aux | grep python

# 查看特定用户的进程
ps aux | grep zhangl

# 杀死所有Python进程（危险！）
# pkill -9 python3

# 查看端口连接状态
sudo netstat -an | grep 7860

# 测试端口是否可访问
nc -zv localhost 7860
telnet localhost 7860

故障排除

问题1: 端口仍被占用

# 使用 root 权限清理
sudo lsof -ti:7860 | xargs sudo kill -9

# 或重启网络服务
sudo systemctl restart networking

问题2: Permission denied

# 确保脚本有执行权限
chmod +x kill_port.sh

# 使用 sudo 运行
sudo ./kill_port.sh 7860

问题3: 找不到占用进程

# 可能是僵尸进程，尝试
sudo kill -9 $(ps aux | grep 'defunct' | awk '{print $2}')

# 或重启系统（最后手段）
sudo reboot

监控端口使用

# 实时监控端口
watch -n 1 'sudo lsof -i:7860'

# 记录端口使用日志
while true; do
    echo "$(date): $(sudo lsof -i:7860 | wc -l) connections"
    sleep 5
done >> port_monitor.log

参考资料

• TCP TIME_WAIT 状态详解
• SO_REUSEADDR vs SO_REUSEPORT
• Linux 信号处理