# DataOps Platform 故障排查指南

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

### 症状
```bash
[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: 使用自动修复脚本（推荐）

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

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

### 方法 2: 使用诊断脚本

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

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

诊断脚本会检查：
- 目录结构
- Supervisor 配置
- Python 环境
- 应用导入
- 日志文件
- 端口占用
- 配置文件

### 方法 3: 手动修复

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

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

#### 步骤 2: 创建日志目录

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

#### 步骤 3: 测试 Python 环境

```bash
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 需要）：
```bash
pip install backports.zoneinfo
```

#### 步骤 4: 测试应用导入

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

#### 步骤 5: 重启服务

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

## 查看日志

### Supervisor 日志（最有用）

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

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

### 应用日志

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

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

### Supervisor 主日志

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

## 常见错误及解决方案

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

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

**解决方案**:
```bash
# 检查 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'

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

**解决方案**:
```bash
sudo apt-get update
sudo apt-get install -y tzdata
```

### 错误 3: Permission denied

**原因**: 文件权限问题

**解决方案**:
```bash
sudo chown -R ubuntu:ubuntu /opt/dataops-platform
sudo chmod -R 755 /opt/dataops-platform/scripts
```

### 错误 4: Address already in use

**原因**: 端口 5500 被占用

**解决方案**:
```bash
# 查找占用端口的进程
sudo netstat -tlnp | grep :5500

# 或使用 lsof
sudo lsof -i :5500

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

## 手动启动测试

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

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

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

## 验证修复

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

### 1. 检查进程状态

```bash
sudo supervisorctl status dataops-platform
```

应该显示 `RUNNING`

### 2. 检查端口

```bash
sudo netstat -tlnp | grep :5500
```

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

### 3. 健康检查

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

应该返回 200 状态码

### 4. 测试时区

```bash
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`