Enable port reuse in TCP server to prevent "Address already in use" errors

PORT_MANAGEMENT.md

@@ -0,0 +1,232 @@
+# 端口管理指南
+
+## 端口占用问题说明
+
+### 常见原因
+
+1. **进程未完全退出**
+   - 使用 `Ctrl+C` 后进程可能仍在后台运行
+   - 子进程没有被正确清理
+
+2. **TCP TIME_WAIT 状态**
+   - TCP连接关闭后会进入 TIME_WAIT 状态
+   - 通常持续 30-120 秒
+   - 这是 TCP 协议的正常行为
+
+3. **多个实例运行**
+   - 启动了多个程序实例
+   - 没有正确关闭之前的实例
+
+## 解决方案
+
+### 方法1: 使用提供的脚本（推荐）
+
+```bash
+# 清理7860端口
+./kill_port.sh 7860
+
+# 或清理其他端口
+./kill_port.sh 8000
+```
+
+### 方法2: 手动清理
+
+#### 查找占用端口的进程
+```bash
+# 方法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
+```
+
+#### 杀死进程
+```bash
+# 如果知道进程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. 正确停止服务器
+
+```bash
+# 使用 Ctrl+C 停止
+# 程序会捕获信号并优雅退出
+
+# 或发送 SIGTERM 信号
+kill -15 <PID>
+```
+
+### 2. 使用进程管理器
+
+#### systemd（生产环境推荐）
+```bash
+# 创建 systemd 服务文件
+sudo nano /etc/systemd/system/learning-app.service
+```
+
+```ini
+[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
+```
+
+```bash
+# 启用并启动服务
+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（备选方案）
+```ini
+[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. 使用虚拟终端
+
+```bash
+# 使用 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
+```
+
+## 常用命令汇总
+
+```bash
+# 查看所有监听的端口
+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: 端口仍被占用
+```bash
+# 使用 root 权限清理
+sudo lsof -ti:7860 | xargs sudo kill -9
+
+# 或重启网络服务
+sudo systemctl restart networking
+```
+
+### 问题2: Permission denied
+```bash
+# 确保脚本有执行权限
+chmod +x kill_port.sh
+
+# 使用 sudo 运行
+sudo ./kill_port.sh 7860
+```
+
+### 问题3: 找不到占用进程
+```bash
+# 可能是僵尸进程，尝试
+sudo kill -9 $(ps aux | grep 'defunct' | awk '{print $2}')
+
+# 或重启系统（最后手段）
+sudo reboot
+```
+
+## 监控端口使用
+
+```bash
+# 实时监控端口
+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 状态详解](https://en.wikipedia.org/wiki/Transmission_Control_Protocol#Connection_termination)
+- [SO_REUSEADDR vs SO_REUSEPORT](https://stackoverflow.com/questions/14388706/how-do-so-reuseaddr-and-so-reuseport-differ)
+- [Linux 信号处理](https://man7.org/linux/man-pages/man7/signal.7.html)
+

app.py

@@ -65,6 +65,9 @@ def main():
     port = int(os.environ.get('PORT', 7860))
     
     try:
+        # 设置端口重用选项，避免 "Address already in use" 错误
+        socketserver.TCPServer.allow_reuse_address = True
+        
         # 创建服务器
         with socketserver.TCPServer(("0.0.0.0", port), CORSHTTPRequestHandler) as httpd:
             print(f"📱 服务器启动成功")

kill_port.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+# 端口清理工具
+# 使用方法: ./kill_port.sh [端口号]
+
+PORT=${1:-7860}
+
+echo "🔍 检查端口 $PORT 的占用情况..."
+
+# 查找占用端口的进程
+PID=$(lsof -ti:$PORT 2>/dev/null)
+
+if [ -z "$PID" ]; then
+    echo "✅ 端口 $PORT 当前未被占用"
+    exit 0
+fi
+
+echo "⚠️  发现进程占用端口 $PORT"
+echo "进程信息:"
+lsof -i:$PORT
+
+echo ""
+read -p "是否要杀死这些进程? (y/N): " -n 1 -r
+echo
+
+if [[ $REPLY =~ ^[Yy]$ ]]; then
+    echo "🔫 正在杀死进程..."
+    kill -9 $PID
+    sleep 1
+    
+    # 再次检查
+    NEW_PID=$(lsof -ti:$PORT 2>/dev/null)
+    if [ -z "$NEW_PID" ]; then
+        echo "✅ 端口 $PORT 已成功释放"
+    else
+        echo "❌ 端口 $PORT 仍被占用，可能需要 root 权限"
+        echo "💡 尝试运行: sudo ./kill_port.sh $PORT"
+    fi
+else
+    echo "❌ 操作已取消"
+fi
+