From 6b71fa43518509d0501643acea216d7ef35a2be7 Mon Sep 17 00:00:00 2001 From: Jowe <123822645+Selei1983@users.noreply.github.com> Date: Fri, 6 Feb 2026 16:44:42 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0v2.6.0=E6=95=85?= =?UTF-8?q?=E9=9A=9C=E6=8E=92=E6=9F=A5=E6=8C=87=E5=8D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 包含部署过程中常见问题的诊断和解决方案。 Co-Authored-By: Claude Sonnet 4.5 --- TROUBLESHOOTING_v2.6.0.md | 345 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 345 insertions(+) create mode 100644 TROUBLESHOOTING_v2.6.0.md diff --git a/TROUBLESHOOTING_v2.6.0.md b/TROUBLESHOOTING_v2.6.0.md new file mode 100644 index 0000000..77b6740 --- /dev/null +++ b/TROUBLESHOOTING_v2.6.0.md @@ -0,0 +1,345 @@ +# ZJPB v2.6.0 部署故障排查指南 + +## 问题现象 +```bash +supervisorctl restart zjpb +zjpb: ERROR (no such process) +``` + +--- + +## 🔍 故障诊断步骤 + +### 1. 检查应用当前运行状态 + +```bash +cd /opt/1panel/apps/zjpb + +# 检查Python进程 +ps aux | grep app.py +ps aux | grep gunicorn | grep zjpb + +# 检查端口占用（通常是5000或8000） +netstat -tlnp | grep :5000 +netstat -tlnp | grep :8000 +``` + +**预期结果**: +- 如果有进程，说明应用在运行，只是不在supervisor管理下 +- 如果没有进程，说明应用已停止 + +--- + +### 2. 检查应用管理方式 + +在1Panel环境中，应用可能通过以下方式管理： + +#### 方式A: systemd服务 + +```bash +# 检查是否有systemd服务 +systemctl list-units | grep zjpb +ls -la /etc/systemd/system/zjpb.service + +# 如果存在，使用systemctl管理 +systemctl status zjpb +systemctl restart zjpb +systemctl start zjpb +``` + +#### 方式B: manage.sh脚本 + +```bash +# 检查是否有管理脚本 +ls -la manage.sh +cat manage.sh + +# 如果存在，使用脚本管理 +./manage.sh status +./manage.sh restart +./manage.sh start +``` + +#### 方式C: 1Panel内置管理 + +```bash +# 检查1Panel容器 +docker ps | grep zjpb + +# 如果是Docker容器 +docker restart zjpb +``` + +#### 方式D: supervisor配置问题 + +```bash +# 检查supervisor配置 +ls -la /etc/supervisor/conf.d/zjpb.conf +cat /etc/supervisor/conf.d/zjpb.conf + +# 重新加载supervisor配置 +supervisorctl reread +supervisorctl update +supervisorctl status +``` + +--- + +## 🚀 快速解决方案 + +### 方案1: 手动启动（推荐，最快） + +```bash +cd /opt/1panel/apps/zjpb + +# 1. 激活虚拟环境 +source venv/bin/activate + +# 2. 安装新依赖 +pip install Flask-Limiter==3.5.0 + +# 3. 查找并停止旧进程 +pkill -f "gunicorn.*zjpb" +pkill -f "python.*app.py" + +# 4. 启动应用（后台运行） +nohup gunicorn -w 4 -b 0.0.0.0:5000 wsgi:app > logs/gunicorn.log 2>&1 & + +# 或者如果有wsgi.py +nohup gunicorn -c gunicorn_config.py wsgi:app > logs/gunicorn.log 2>&1 & + +# 5. 验证启动 +ps aux | grep gunicorn +netstat -tlnp | grep :5000 + +# 6. 查看日志 +tail -f logs/gunicorn.log +``` + +### 方案2: 使用manage.sh（如果存在） + +```bash +cd /opt/1panel/apps/zjpb + +# 安装依赖 +source venv/bin/activate +pip install Flask-Limiter==3.5.0 + +# 使用脚本重启 +./manage.sh stop +./manage.sh start +./manage.sh status +``` + +### 方案3: 配置supervisor（推荐长期方案） + +如果要使用supervisor管理，需要创建配置文件： + +```bash +# 1. 创建supervisor配置 +cat > /etc/supervisor/conf.d/zjpb.conf << 'EOF' +[program:zjpb] +directory=/opt/1panel/apps/zjpb +command=/opt/1panel/apps/zjpb/venv/bin/gunicorn -c gunicorn_config.py wsgi:app +autostart=true +autorestart=true +startsecs=10 +startretries=3 +user=root +redirect_stderr=true +stdout_logfile=/opt/1panel/apps/zjpb/logs/supervisor.log +stdout_logfile_maxbytes=50MB +stdout_logfile_backups=10 +environment=PATH="/opt/1panel/apps/zjpb/venv/bin" +EOF + +# 2. 重新加载配置 +supervisorctl reread +supervisorctl update + +# 3. 启动应用 +supervisorctl start zjpb +supervisorctl status zjpb +``` + +### 方案4: 通过1Panel Web界面 + +1. 登录1Panel管理面板 +2. 找到"网站"或"应用"菜单 +3. 找到zjpb应用 +4. 点击"停止" → 等待 → 点击"启动" + +--- + +## ✅ 部署验证 + +启动成功后，执行以下验证： + +```bash +# 1. 检查进程 +ps aux | grep gunicorn + +# 2. 检查端口 +netstat -tlnp | grep :5000 + +# 3. 测试HTTP访问 +curl http://localhost:5000/ + +# 4. 查看日志 +tail -50 logs/gunicorn.log +tail -50 logs/error.log + +# 5. 测试详情页（替换为实际的code） +curl http://localhost:5000/site/12345678 +``` + +**预期结果**: +- 进程存在 +- 端口被监听 +- HTTP返回200 +- 日志无错误 + +--- + +## 🐛 常见错误处理 + +### 错误1: ImportError: No module named 'utils.rate_limiter' + +**原因**: 新文件未正确拉取 + +**解决**: +```bash +cd /opt/1panel/apps/zjpb +git status +git pull origin master +ls -la utils/rate_limiter.py # 确认文件存在 +``` + +### 错误2: ModuleNotFoundError: No module named 'flask_limiter' + +**原因**: 依赖未安装 + +**解决**: +```bash +source venv/bin/activate +pip install Flask-Limiter==3.5.0 +``` + +### 错误3: 端口被占用 + +**现象**: `Address already in use` + +**解决**: +```bash +# 查找占用端口的进程 +lsof -i :5000 +netstat -tlnp | grep :5000 + +# 停止旧进程 +kill -9 + +# 或批量停止 +pkill -f "gunicorn.*zjpb" +``` + +### 错误4: Permission denied + +**解决**: +```bash +# 确保目录权限 +chown -R root:root /opt/1panel/apps/zjpb +chmod +x manage.sh # 如果有 +``` + +--- + +## 📋 完整的重启流程（推荐） + +```bash +#!/bin/bash +# 安全的重启流程 + +cd /opt/1panel/apps/zjpb + +echo "=== Step 1: 备份当前代码 ===" +git stash + +echo "=== Step 2: 拉取最新代码 ===" +git pull origin master + +echo "=== Step 3: 激活虚拟环境 ===" +source venv/bin/activate + +echo "=== Step 4: 安装依赖 ===" +pip install Flask-Limiter==3.5.0 + +echo "=== Step 5: 停止旧进程 ===" +pkill -f "gunicorn.*zjpb" || echo "No process to kill" +sleep 2 + +echo "=== Step 6: 启动应用 ===" +nohup gunicorn -w 4 -b 0.0.0.0:5000 wsgi:app > logs/gunicorn.log 2>&1 & +sleep 3 + +echo "=== Step 7: 验证启动 ===" +if ps aux | grep -v grep | grep gunicorn | grep zjpb; then + echo "✅ 应用启动成功" + echo "进程信息:" + ps aux | grep gunicorn | grep zjpb +else + echo "❌ 应用启动失败" + echo "查看日志:" + tail -20 logs/gunicorn.log + exit 1 +fi + +echo "=== Step 8: 测试访问 ===" +curl -s http://localhost:5000/ | head -5 +echo "" +echo "✅ 部署完成！" +``` + +将上述脚本保存为 `deploy_v2.6.sh`，然后执行： + +```bash +chmod +x deploy_v2.6.sh +./deploy_v2.6.sh +``` + +--- + +## 📞 需要提供的信息 + +如果以上方案都无法解决，请提供以下信息： + +```bash +# 1. 当前进程状态 +ps aux | grep python +ps aux | grep gunicorn + +# 2. 端口占用 +netstat -tlnp | grep -E ":(5000|8000)" + +# 3. 项目文件 +ls -la /opt/1panel/apps/zjpb/ + +# 4. 日志内容 +tail -50 /opt/1panel/apps/zjpb/logs/error.log +tail -50 /opt/1panel/apps/zjpb/logs/gunicorn.log + +# 5. Git状态 +cd /opt/1panel/apps/zjpb +git status +git log --oneline -3 + +# 6. Python环境 +which python +python --version +pip list | grep Flask +``` + +--- + +**最快解决方案**: 使用方案1手动启动，后续再配置自动化管理。 + +**推荐方案**: 配置systemd服务（更稳定）或使用1Panel内置管理。