aitsc/docs/port_management_guide.md

# 端口管理指南

## 📋 **概述**

本指南介绍如何管理Flask应用的端口占用问题，确保服务稳定运行。

## 🛠️ **工具介绍**

### 1. 端口管理脚本 (`scripts/port_manager.sh`)

**功能：**
- 检查端口占用情况
- 清理端口占用
- 启动/停止/重启应用
- 查看应用状态
- 监控模式

**使用方法：**
```bash
# 检查端口占用
./scripts/port_manager.sh check

# 清理端口占用
./scripts/port_manager.sh clean

# 启动应用
./scripts/port_manager.sh start

# 停止应用
./scripts/port_manager.sh stop

# 重启应用
./scripts/port_manager.sh restart

# 查看状态
./scripts/port_manager.sh status

# 启动监控
./scripts/port_manager.sh monitor

# 显示帮助
./scripts/port_manager.sh help
```

### 2. 端口监控脚本 (`scripts/port_monitor.py`)

**功能：**
- 实时监控端口状态
- 自动检测服务异常
- 自动重启服务
- 生成监控报告
- 系统资源监控

**使用方法：**
```bash
# 查看当前状态
python scripts/port_monitor.py status

# 生成详细报告
python scripts/port_monitor.py report

# 重启服务
python scripts/port_monitor.py restart

# 启动监控模式
python scripts/port_monitor.py monitor

# 查看配置
python scripts/port_monitor.py config
```

### 3. Systemd服务配置 (`scripts/flask-app.service`)

**功能：**
- 系统级服务管理
- 自动启动/停止
- 故障自动重启
- 日志管理

## 🔧 **配置说明**

### 端口管理脚本配置

脚本中的主要配置项：
```bash
PORT=5002                    # 应用端口
APP_NAME="flask_prompt_master"  # 应用名称
PID_FILE="logs/gunicorn.pid"    # PID文件路径
LOG_DIR="logs"                  # 日志目录
```

### 监控脚本配置

配置文件：`logs/monitor_config.json`
```json
{
  "check_interval": 30,           // 检查间隔（秒）
  "max_restart_attempts": 3,      // 最大重启尝试次数
  "alert_threshold": 2,           // 告警阈值
  "port_timeout": 5,              // 端口检查超时时间
  "enable_alerts": true,          // 启用告警
  "auto_restart": true            // 自动重启
}
```

## 🚀 **部署步骤**

### 1. 安装systemd服务（可选）

```bash
# 复制服务文件
sudo cp scripts/flask-app.service /etc/systemd/system/

# 重新加载systemd
sudo systemctl daemon-reload

# 启用服务
sudo systemctl enable flask-app

# 启动服务
sudo systemctl start flask-app

# 查看状态
sudo systemctl status flask-app
```

### 2. 设置定时任务

```bash
# 编辑crontab
crontab -e

# 添加定时检查任务（每5分钟检查一次）
*/5 * * * * /home/renjianbo/aitsc/scripts/port_manager.sh status > /dev/null 2>&1
```

### 3. 配置日志轮转

创建日志轮转配置：`/etc/logrotate.d/flask-app`
```
/home/renjianbo/aitsc/logs/*.log {
    daily
    missingok
    rotate 30
    compress
    delaycompress
    notifempty
    create 644 renjianbo renjianbo
    postrotate
        systemctl reload flask-app > /dev/null 2>&1 || true
    endscript
}
```

## 📊 **监控和告警**

### 1. 监控指标

- **端口占用状态**：检查5002端口是否被正确占用
- **Gunicorn进程状态**：检查主进程和工作进程
- **服务响应状态**：检查HTTP服务是否正常响应
- **系统资源**：CPU、内存、磁盘使用率

### 2. 告警机制

- **自动告警**：检测到异常时自动记录告警日志
- **自动重启**：服务异常时自动尝试重启
- **重启限制**：防止频繁重启，设置重启间隔和次数限制

### 3. 日志文件

- `logs/port_monitor.log`：监控脚本日志
- `logs/port_alerts.log`：告警日志
- `logs/gunicorn_error.log`：Gunicorn错误日志
- `logs/gunicorn_access.log`：Gunicorn访问日志

## 🔍 **故障排查**

### 1. 端口被占用

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

**解决方案：**
```bash
# 检查端口占用
./scripts/port_manager.sh check

# 清理端口占用
./scripts/port_manager.sh clean

# 重新启动
./scripts/port_manager.sh start
```

### 2. 服务无响应

**症状：** 访问网站显示连接被拒绝

**解决方案：**
```bash
# 检查服务状态
./scripts/port_manager.sh status

# 重启服务
./scripts/port_manager.sh restart

# 查看错误日志
tail -f logs/gunicorn_error.log
```

### 3. 进程异常退出

**症状：** PID文件存在但进程不存在

**解决方案：**
```bash
# 清理所有相关进程
pkill -f gunicorn

# 重新启动
./scripts/port_manager.sh start
```

## 📈 **性能优化**

### 1. 监控配置优化

根据服务器性能调整监控参数：
```json
{
  "check_interval": 60,        // 降低检查频率
  "port_timeout": 3,           // 减少超时时间
  "max_restart_attempts": 5    // 增加重启尝试次数
}
```

### 2. 日志管理

定期清理日志文件：
```bash
# 清理30天前的日志
find logs/ -name "*.log" -mtime +30 -delete

# 压缩旧日志
find logs/ -name "*.log" -mtime +7 -exec gzip {} \;
```

### 3. 系统资源监控

设置资源告警阈值：
- CPU使用率 > 80%
- 内存使用率 > 90%
- 磁盘使用率 > 85%

## 🔒 **安全考虑**

### 1. 权限管理

确保脚本和日志文件权限正确：
```bash
# 设置脚本权限
chmod +x scripts/port_manager.sh
chmod +x scripts/port_monitor.py

# 设置日志目录权限
chmod 755 logs/
chmod 644 logs/*.log
```

### 2. 网络安全

- 限制端口访问：只允许必要的IP访问5002端口
- 防火墙配置：配置iptables规则
- SSL/TLS：使用HTTPS协议

### 3. 监控安全

- 监控脚本权限：只允许特定用户运行
- 日志安全：定期备份和加密敏感日志
- 告警安全：避免在告警中暴露敏感信息

## 📞 **技术支持**

### 1. 常见问题

**Q: 为什么端口会被其他进程占用？**
A: 可能是之前的Gunicorn进程未完全清理，或者有其他应用使用了相同端口。

**Q: 如何防止服务意外停止？**
A: 使用systemd服务配置自动重启，或启用监控脚本的自动重启功能。

**Q: 监控脚本消耗太多资源怎么办？**
A: 调整检查间隔，或使用更轻量级的监控方式。

### 2. 联系支持

- 查看日志文件获取详细错误信息
- 使用状态检查命令诊断问题
- 参考故障排查章节的解决方案

## 📝 **更新日志**

- **v1.0** - 初始版本，基础端口管理功能
- **v1.1** - 添加监控脚本和自动重启功能
- **v1.2** - 添加systemd服务配置和日志轮转
- **v1.3** - 优化监控性能和告警机制