# DataOps Platform 部署指南

## 📋 本次更新内容

### 时区修正
将所有时间字段从 UTC 时间改为东八区（Asia/Shanghai）时间。

### 修改的文件
- ✅ `app/core/common/timezone_utils.py` - 新增时区工具模块（兼容 Python 3.8+）
- ✅ `app/models/data_product.py` - 时间字段修正
- ✅ `app/models/metadata_review.py` - 时间字段修正
- ✅ `app/core/data_service/data_product_service.py` - 时间处理修正
- ✅ `app/core/meta_data/redundancy_check.py` - 时间处理修正
- ✅ `app/core/business_domain/business_domain.py` - 时间处理修正

### 新增的文件
- 📄 `scripts/fix_startup.sh` - 自动修复脚本
- 📄 `scripts/diagnose_issue.sh` - 问题诊断脚本
- 📄 `scripts/TROUBLESHOOTING.md` - 故障排查指南
- 📄 `QUICK_FIX.md` - 快速修复指南
- 📄 `PYTHON38_COMPATIBILITY.md` - Python 3.8 兼容性说明
- 📄 `docs/timezone_fix_summary.md` - 时区修正总结

## 🚀 部署步骤（生产环境 Python 3.8）

### 前置条件检查

```bash
# 1. 检查 Python 版本
python --version
# 应该显示: Python 3.8.x

# 2. 检查 backports.zoneinfo 是否已安装
cd /opt/dataops-platform
source venv/bin/activate
python -c "import backports.zoneinfo; print('backports.zoneinfo 已安装')"
# 如果已安装，应该显示: backports.zoneinfo 已安装
```

### 步骤 1: 上传代码到服务器

**方法 A: 使用 Git（推荐）**
```bash
cd /opt/dataops-platform
git pull origin main
```

**方法 B: 使用 SCP 上传**
```bash
# 在本地执行
scp -r app/ scripts/ docs/ *.md ubuntu@your-server:/opt/dataops-platform/
```

### 步骤 2: 运行自动修复脚本

```bash
# 在服务器上执行
cd /opt/dataops-platform/scripts
sudo chmod +x fix_startup.sh diagnose_issue.sh
sudo ./fix_startup.sh
```

### 步骤 3: 验证部署

```bash
# 1. 检查服务状态
sudo supervisorctl status dataops-platform
# 预期输出: dataops-platform RUNNING pid xxx, uptime x:xx:xx

# 2. 测试健康检查
curl http://localhost:5500/api/system/health
# 预期输出: {"status":"healthy",...}

# 3. 测试时区功能
cd /opt/dataops-platform
source venv/bin/activate
python -c "from app.core.common.timezone_utils import now_china_naive; print('当前东八区时间:', now_china_naive())"
# 预期输出: 当前东八区时间: 2026-01-12 18:30:45.123456
```

## 🔧 技术细节

### Python 3.8 兼容性

代码已自动适配 Python 3.8 和 3.9+：

```python
# app/core/common/timezone_utils.py
try:
    # Python 3.9+
    from zoneinfo import ZoneInfo
except ImportError:
    # Python 3.8 使用 backports
    from backports.zoneinfo import ZoneInfo
```

### 依赖要求

| Python 版本 | zoneinfo 模块 | 系统依赖 |
|------------|--------------|---------|
| 3.8 | `backports.zoneinfo` (pip) | `tzdata` (apt) |
| 3.9+ | 标准库 `zoneinfo` | `tzdata` (apt) |

### 当前生产环境配置

- **Python 版本**: 3.8
- **已安装**: `backports.zoneinfo`
- **需确认**: 系统 `tzdata` 包

## ⚠️ 可能遇到的问题

### 问题 1: 应用启动失败

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

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

**解决**:
```bash
sudo apt-get update
sudo apt-get install -y tzdata
sudo supervisorctl restart dataops-platform
```

### 问题 2: ModuleNotFoundError: No module named 'zoneinfo'

**症状**:
```python
ModuleNotFoundError: No module named 'zoneinfo'
```

**原因**: Python 3.8 环境未安装 `backports.zoneinfo`

**解决**:
```bash
cd /opt/dataops-platform
source venv/bin/activate
pip install backports.zoneinfo
sudo supervisorctl restart dataops-platform
```

### 问题 3: ZoneInfoNotFoundError

**症状**:
```python
ZoneInfoNotFoundError: 'No time zone found with key Asia/Shanghai'
```

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

**解决**:
```bash
sudo apt-get update
sudo apt-get install -y tzdata
sudo supervisorctl restart dataops-platform
```

## 📊 验证清单

部署完成后，请验证以下功能：

- [ ] 服务启动成功（`supervisorctl status` 显示 RUNNING）
- [ ] 健康检查接口返回 200
- [ ] 时区模块正常工作
- [ ] 创建新数据订单，检查 `created_at` 字段
- [ ] 更新订单状态，检查 `updated_at` 和 `processed_at` 字段
- [ ] 注册数据产品，检查时间字段
- [ ] 查看数据产品，检查 `last_viewed_at` 字段

## 🔍 故障排查

### 查看实时日志

```bash
# Supervisor 错误日志（最重要）
sudo tail -f /var/log/supervisor/dataops-platform-stderr.log

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

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

### 运行诊断脚本

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

### 手动启动测试

```bash
cd /opt/dataops-platform
source venv/bin/activate
gunicorn -c gunicorn_config.py 'app:create_app()'
# 按 Ctrl+C 停止
```

## 📚 相关文档

- **快速修复**: `QUICK_FIX.md`
- **Python 3.8 兼容性**: `PYTHON38_COMPATIBILITY.md`
- **故障排查**: `scripts/TROUBLESHOOTING.md`
- **时区修正总结**: `docs/timezone_fix_summary.md`

## 🎯 回滚方案

如果部署后出现严重问题，可以回滚到之前的版本：

```bash
# 1. 回滚代码
cd /opt/dataops-platform
git reset --hard HEAD~1

# 2. 重启服务
sudo supervisorctl restart dataops-platform

# 3. 验证服务
sudo supervisorctl status dataops-platform
```

## 📞 技术支持

如果遇到问题，请提供以下信息：

1. **诊断输出**:
   ```bash
   cd /opt/dataops-platform/scripts
   sudo ./diagnose_issue.sh > ~/diagnosis.log 2>&1
   ```

2. **错误日志**:
   ```bash
   sudo tail -100 /var/log/supervisor/dataops-platform-stderr.log > ~/error.log
   ```

3. **系统信息**:
   ```bash
   python --version
   cat /etc/os-release
   ```

---

**部署日期**: 2026-01-12  
**版本**: v1.0 - 时区修正  
**兼容性**: Python 3.8+