DataOps-platform/scripts/TROUBLESHOOTING.md

DataOps Platform 故障排查指南

问题：应用启动失败，日志文件不存在

症状

[ERROR] dataops-platform 重启失败!
tail: cannot open '/opt/dataops-platform/logs/gunicorn_error.log' for reading: No such file or directory

可能原因

1. 时区模块问题（最常见）

   • Python 3.9+ 使用 zoneinfo 模块需要系统时区数据
   • 缺少 tzdata 包会导致应用无法启动
   • 我们的代码修改引入了 from zoneinfo import ZoneInfo

2. 日志目录不存在

   • /opt/dataops-platform/logs 目录未创建
   • 权限问题导致无法写入日志

3. 虚拟环境问题

   • Python 依赖缺失
   • 虚拟环境损坏

4. 配置文件问题

   • Supervisor 配置错误
   • 环境变量缺失

快速修复步骤

方法 1: 使用自动修复脚本（推荐）

cd /opt/dataops-platform/scripts
sudo chmod +x fix_startup.sh
sudo ./fix_startup.sh

这个脚本会自动：

• 创建日志目录
• 安装 tzdata（时区数据）
• 测试 Python 环境和时区模块
• 修复文件权限
• 重新加载 Supervisor 配置
• 启动应用并进行健康检查

方法 2: 使用诊断脚本

如果自动修复失败，先运行诊断脚本查看详细问题：

cd /opt/dataops-platform/scripts
sudo chmod +x diagnose_issue.sh
sudo ./diagnose_issue.sh

诊断脚本会检查：

• 目录结构
• Supervisor 配置
• Python 环境
• 应用导入
• 日志文件
• 端口占用
• 配置文件

方法 3: 手动修复

步骤 1: 安装时区数据（最重要）

sudo apt-get update
sudo apt-get install -y tzdata

步骤 2: 创建日志目录

sudo mkdir -p /opt/dataops-platform/logs
sudo chown ubuntu:ubuntu /opt/dataops-platform/logs

步骤 3: 测试 Python 环境

cd /opt/dataops-platform
source venv/bin/activate
python -c "
try:
    from zoneinfo import ZoneInfo
except ImportError:
    from backports.zoneinfo import ZoneInfo
print('时区模块正常')
"

如果报错，安装 backports（Python 3.8 需要）：

pip install backports.zoneinfo

步骤 4: 测试应用导入

cd /opt/dataops-platform
source venv/bin/activate
python -c "from app import create_app; app = create_app(); print('应用导入成功')"

步骤 5: 重启服务

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl restart dataops-platform

查看日志

Supervisor 日志（最有用）

# 查看 stderr（错误输出）
sudo tail -f /var/log/supervisor/dataops-platform-stderr.log

# 查看 stdout（标准输出）
sudo tail -f /var/log/supervisor/dataops-platform-stdout.log

应用日志

# Gunicorn 错误日志
tail -f /opt/dataops-platform/logs/gunicorn_error.log

# Gunicorn 访问日志
tail -f /opt/dataops-platform/logs/gunicorn_access.log

Supervisor 主日志

sudo tail -f /var/log/supervisor/supervisord.log

常见错误及解决方案

错误 1: ModuleNotFoundError: No module named 'zoneinfo'

原因: Python < 3.9 需要使用 backports.zoneinfo

解决方案:

# 检查 Python 版本
python --version

# Python 3.8 需要安装 backports.zoneinfo
cd /opt/dataops-platform
source venv/bin/activate
pip install backports.zoneinfo

# 同时安装系统时区数据
sudo apt-get update
sudo apt-get install -y tzdata

错误 2: ZoneInfoNotFoundError: 'No time zone found with key Asia/Shanghai'

原因: 系统缺少时区数据库

解决方案:

sudo apt-get update
sudo apt-get install -y tzdata

错误 3: Permission denied

原因: 文件权限问题

解决方案:

sudo chown -R ubuntu:ubuntu /opt/dataops-platform
sudo chmod -R 755 /opt/dataops-platform/scripts

错误 4: Address already in use

原因: 端口 5500 被占用

解决方案:

# 查找占用端口的进程
sudo netstat -tlnp | grep :5500

# 或使用 lsof
sudo lsof -i :5500

# 停止旧进程
sudo supervisorctl stop dataops-platform
sudo pkill -f "gunicorn.*dataops"

手动启动测试

如果 Supervisor 启动失败，可以手动启动应用进行测试：

cd /opt/dataops-platform
source venv/bin/activate
gunicorn -c gunicorn_config.py 'app:create_app()'

这样可以直接看到启动时的错误信息。

验证修复

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

1. 检查进程状态

sudo supervisorctl status dataops-platform

应该显示 RUNNING

2. 检查端口

sudo netstat -tlnp | grep :5500

应该看到 gunicorn 进程监听 5500 端口

3. 健康检查

curl http://localhost:5500/api/system/health

应该返回 200 状态码

4. 测试时区

cd /opt/dataops-platform
source venv/bin/activate
python -c "from app.core.common.timezone_utils import now_china_naive; print(now_china_naive())"

应该输出当前东八区时间

联系支持

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

1. 诊断脚本输出：sudo ./diagnose_issue.sh > diagnosis.log 2>&1
2. Supervisor stderr 日志：sudo tail -100 /var/log/supervisor/dataops-platform-stderr.log
3. Python 版本：python --version
4. 系统版本：cat /etc/os-release

相关文件

• 部署脚本：deploy_dataops.sh
• 启动脚本：start_dataops.sh
• 重启脚本：restart_dataops.sh
• 诊断脚本：diagnose_issue.sh
• 修复脚本：fix_startup.sh
• Supervisor 配置：/etc/supervisor/conf.d/dataops-platform.conf
• Gunicorn 配置：/opt/dataops-platform/gunicorn_config.py