zjpb.net/TROUBLESHOOTING_v2.6.0.md

ZJPB v2.6.0 部署故障排查指南

问题现象

supervisorctl restart zjpb
zjpb: ERROR (no such process)

---

🔍 故障诊断步骤

1. 检查应用当前运行状态

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服务

# 检查是否有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脚本

# 检查是否有管理脚本
ls -la manage.sh
cat manage.sh

# 如果存在，使用脚本管理
./manage.sh status
./manage.sh restart
./manage.sh start

方式C: 1Panel内置管理

# 检查1Panel容器
docker ps | grep zjpb

# 如果是Docker容器
docker restart zjpb

方式D: supervisor配置问题

# 检查supervisor配置
ls -la /etc/supervisor/conf.d/zjpb.conf
cat /etc/supervisor/conf.d/zjpb.conf

# 重新加载supervisor配置
supervisorctl reread
supervisorctl update
supervisorctl status

---

🚀 快速解决方案

方案1: 手动启动（推荐，最快）

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（如果存在）

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管理，需要创建配置文件：

# 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. 点击"停止" → 等待 → 点击"启动"

---

✅ 部署验证

启动成功后，执行以下验证：

# 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'

原因: 新文件未正确拉取

解决:

cd /opt/1panel/apps/zjpb
git status
git pull origin master
ls -la utils/rate_limiter.py  # 确认文件存在

错误2: ModuleNotFoundError: No module named 'flask_limiter'

原因: 依赖未安装

解决:

source venv/bin/activate
pip install Flask-Limiter==3.5.0

错误3: 端口被占用

现象: Address already in use

解决:

# 查找占用端口的进程
lsof -i :5000
netstat -tlnp | grep :5000

# 停止旧进程
kill -9 <PID>

# 或批量停止
pkill -f "gunicorn.*zjpb"

错误4: Permission denied

解决:

# 确保目录权限
chown -R root:root /opt/1panel/apps/zjpb
chmod +x manage.sh  # 如果有

---

📋 完整的重启流程（推荐）

#!/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，然后执行：

chmod +x deploy_v2.6.sh
./deploy_v2.6.sh

---

📞 需要提供的信息

如果以上方案都无法解决，请提供以下信息：

# 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内置管理。