DataOps-platform/docs/DEPLOYMENT_GUIDE.md

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）

前置条件检查

# 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（推荐）

cd /opt/dataops-platform
git pull origin main

方法 B: 使用 SCP 上传

# 在本地执行
scp -r app/ scripts/ docs/ *.md ubuntu@your-server:/opt/dataops-platform/

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

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

步骤 3: 验证部署

# 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+：

# 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: 应用启动失败

症状:

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

原因: 缺少系统时区数据

解决:

sudo apt-get update
sudo apt-get install -y tzdata
sudo supervisorctl restart dataops-platform

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

症状:

ModuleNotFoundError: No module named 'zoneinfo'

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

解决:

cd /opt/dataops-platform
source venv/bin/activate
pip install backports.zoneinfo
sudo supervisorctl restart dataops-platform

问题 3: ZoneInfoNotFoundError

症状:

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

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

解决:

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 字段

🔍 故障排查

查看实时日志

# 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

运行诊断脚本

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

手动启动测试

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

🎯 回滚方案

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

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

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

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

📞 技术支持

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

1. 诊断输出:

   cd /opt/dataops-platform/scripts
   sudo ./diagnose_issue.sh > ~/diagnosis.log 2>&1
   

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

2. 系统信息:

   python --version
   cat /etc/os-release
   

   ---

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