docs: 添加v2.6.0故障排查指南
包含部署过程中常见问题的诊断和解决方案。 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Jowe
345
TROUBLESHOOTING_v2.6.0.md
Normal file
345
TROUBLESHOOTING_v2.6.0.md
Normal file
@@ -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 <PID>
|
||||
|
||||
# 或批量停止
|
||||
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内置管理。
|
||||
Reference in New Issue
Block a user