program/部署与升级指南.md

神东煤炭综采工作面数据管理与AI分析系统 - 部署与升级指南

目录

1. 系统简介
2. 系统要求
3. 新版本功能说明
4. Git一键升级（推荐）
5. 服务器升级指南（重要）
6. Ubuntu直接部署
7. Docker部署（推荐）
8. Docker Compose部署（推荐）
9. 配置说明
10. Nginx反向代理
11. SSL HTTPS配置
12. 常见问题
13. 备份与恢复

---

系统简介

本系统是神东煤炭集团开发的综采工作面数据管理与AI分析系统，支持：

• 实时数据采集与监测
• 多工作面数据管理
• 智能故障诊断（AI驱动）
• 数据趋势分析
• 可视化报表展示

---

系统要求

项目	要求
操作系统	Ubuntu 20.04 LTS / 22.04 LTS / CentOS 7+
Python	3.8 - 3.11
数据库	MySQL 5.7+ / 神通数据库（兼容MySQL协议）
内存	最低 2GB，推荐 4GB+
磁盘	最低 10GB可用空间
网络	需要访问数据库服务器和AI API服务

---

新版本功能说明

本次更新内容

1. 首页概览优化

   • 新增顶部统计卡片（工作面数量、监测点总数、总采集次数、今日采集、总数据量）
   • 新增工作面统计表格，支持点击跳转到实时监测页面

2. AI分析数据量优化

   • 故障诊断：限制最多200个监测点，按设备类型分组采样
   • 趋势分析：限制最多200个监测点，历史数据限制2000条
   • 防止AI API上下文超限，提升分析成功率

3. AI分析数据摘要

   • 在分析结果上方显示数据摘要卡片
   • 以表格形式展示使用的监测点中文名称
   • 方便用户了解AI分析的数据基础

4. 数据统计API增强

   • /api/stats/all 返回总体统计数据
   • 包含各工作面详细统计信息

---

Git一键升级（推荐）

适用场景: 服务器已初始化Git仓库，需要快速升级到最新版本

前提条件: 已执行 init_git.sh 初始化Git仓库

快速升级

# 进入项目目录
cd /path/to/websitedata/mining-system

# 升级到最新版本（自动备份、拉取代码、更新依赖、重启服务）
bash upgrade.sh

升级到指定版本

# 升级到指定标签
bash upgrade.sh v1.2.0

# 升级到指定commit
bash upgrade.sh abc123def

# 切换到开发分支
bash upgrade.sh develop

查看版本状态

# 显示当前版本、远程更新、备份信息等
bash upgrade.sh status

仅执行备份

# 备份配置文件、数据库和outputs目录
bash upgrade.sh backup

回滚到上一版本

# 交互式回滚（会提示确认）
bash upgrade.sh rollback

升级流程说明

升级脚本 upgrade.sh 自动执行以下步骤：

1. 备份系统 - 备份配置文件、数据库、outputs目录到 backups/ 目录
2. 停止服务 - 通过systemd或进程方式停止当前服务
3. 保存本地文件 - 将需要保留的文件保存到临时目录
4. 拉取最新代码 - 从Git仓库拉取指定版本的代码
5. 恢复本地文件 - 将配置文件、数据库等恢复到项目目录
6. 更新依赖 - 根据新的 requirements.txt 更新Python依赖
7. 数据库迁移 - 如有迁移脚本，自动执行
8. 重启服务 - 通过systemd重启服务
9. 验证升级 - 检查API是否正常响应

初始化Git仓库（首次使用）

如果服务器上的系统是通过文件复制方式部署的，需要先初始化Git仓库：

cd /path/to/websitedata/mining-system
bash init_git.sh

初始化脚本会自动：

• 创建 .gitignore 文件
• 初始化Git仓库
• 配置远程仓库地址
• 拉取最新代码
• 保留本地配置文件和数据库

升级脚本配置

upgrade.sh 中的关键配置（可根据实际情况修改）：

配置项	默认值	说明
GIT_REPO	http://10.224.35.147:3000/redline/program.git	Git仓库地址
SERVICE_NAME	mining-system	systemd服务名称
PRESERVE_FILES	config.py, mining_data.db, .env	升级时保留的文件
PRESERVE_DIRS	outputs, logs	升级时保留的目录

备份管理

升级脚本会自动管理备份：

• 备份目录: backups/
• 保留策略: 最近10个完整备份
• 备份内容:
  • config-backup-YYYYMMDD_HHMMSS.txt - 配置文件和Git信息备份
  • config.py.YYYYMMDD_HHMMSS.bak - 配置文件备份
  • mining_data.db.YYYYMMDD_HHMMSS.bak - 数据库备份
  • outputs-YYYYMMDD_HHMMSS.tar.gz - 输出目录备份

---

服务器升级指南（重要）

适用场景: 你已经在服务器上部署了旧版本，需要升级到新版本

升级前准备

1. 备份现有系统

# 假设原项目路径为 /path/to/websitedata/mining-system
# 请根据实际情况修改路径

PROJECT_DIR="/path/to/websitedata/mining-system"
BACKUP_DIR="/path/to/backups"
DATE=$(date +%Y%m%d_%H%M%S)

# 创建备份目录
sudo mkdir -p $BACKUP_DIR

# 备份整个项目目录
sudo tar -czf $BACKUP_DIR/mining-system-backup-$DATE.tar.gz \
    -C /path/to/websitedata \
    mining-system

# 备份数据库（如使用本地SQLite）
sudo cp $PROJECT_DIR/mining_data.db $BACKUP_DIR/mining_data.db-$DATE.backup

# 备份配置文件
sudo cp $PROJECT_DIR/config.py $BACKUP_DIR/config.py-$DATE.backup

# 备份systemd服务文件（如已配置）
sudo cp /etc/systemd/system/mining-system.service $BACKUP_DIR/ 2>/dev/null || true

# 备份Nginx配置（如已配置）
sudo cp /etc/nginx/sites-available/mining-system $BACKUP_DIR/ 2>/dev/null || true

echo "备份完成: $BACKUP_DIR/mining-system-backup-$DATE.tar.gz"

2. 停止当前服务

# 如果使用systemd服务
sudo systemctl stop mining-system

# 如果使用手动启动，找到并停止进程
sudo lsof -ti:5000 | xargs sudo kill -9 2>/dev/null || true

# 确认服务已停止
sudo systemctl status mining-system
# 或
sudo lsof -i :5000

执行升级

方式一：覆盖文件升级（推荐）

# 1. 上传新版本的整个 mining-system 目录到服务器
# 使用 scp 命令从本地上传：
# scp -r ./mining-system user@server:/path/to/websitedata/

# 2. 保留原有配置文件和数据库
cd /path/to/websitedata/mining-system

# 备份新版配置文件（用旧版覆盖）
cp config.py config.py.new
cp /path/to/backups/config.py.$(ls -t /path/to/backups/ | grep config.py | head -1) config.py

# 保留数据库文件（如果已有数据采集）
# mining_data.db 应该在升级时自动保留

# 3. 进入项目目录
cd /path/to/websitedata/mining-system

# 4. 激活虚拟环境并更新依赖
source venv/bin/activate

# 如虚拟环境不存在，重新创建
if [ ! -d "venv" ]; then
    python3 -m venv venv
    source venv/bin/activate
fi

# 升级pip
pip install --upgrade pip

# 安装/更新依赖（如有新增依赖）
pip install -r requirements.txt

# 5. 验证文件完整性
ls -la *.py
echo "---"
cat requirements.txt

# 6. 测试启动
python3 app.py &
sleep 3
curl -s http://localhost:5000/api/stats/all
echo ""

# 如果返回正常JSON数据，说明升级成功
# 按 Ctrl+C 停止测试进程

方式二：全新部署然后迁移配置

# 1. 上传新版本到新的目录
scp -r ./mining-system user@server:/path/to/websitedata/mining-system-new

# 2. 在服务器上配置
cd /path/to/websitedata/mining-system-new

# 3. 复制旧版配置文件
cp /path/to/websitedata/mining-system/config.py ./config.py

# 4. 复制数据库文件（如使用SQLite）
cp /path/to/websitedata/mining-system/mining_data.db ./mining_data.db

# 5. 创建虚拟环境并安装依赖
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

# 6. 测试启动
python3 app.py

# 7. 确认运行正常后，替换旧目录
# 停止服务
sudo systemctl stop mining-system

# 备份旧目录
sudo mv /path/to/websitedata/mining-system /path/to/websitedata/mining-system-old

# 移动新目录
sudo mv /path/to/websitedata/mining-system-new /path/to/websitedata/mining-system

# 更新systemd服务路径（如路径有变化）
sudo nano /etc/systemd/system/mining-system.service
# 确保 WorkingDirectory 和 ExecStart 路径正确

# 重启服务
sudo systemctl daemon-reload
sudo systemctl start mining-system
sudo systemctl status mining-system

升级后验证

# 1. 检查服务状态
sudo systemctl status mining-system

# 2. 检查API是否正常
curl -s http://localhost:5000/api/stats/all | python3 -m json.tool

# 3. 检查网页是否正常访问
# 浏览器访问 http://服务器IP:5000

# 4. 验证新功能
# - 首页应显示统计卡片
# - 首页应显示工作面统计表格
# - AI分析结果上方应显示数据摘要

# 5. 查看日志
sudo journalctl -u mining-system -f --since "5 minutes ago"

回滚方案

如果升级后出现问题，可以快速回滚：

# 1. 停止服务
sudo systemctl stop mining-system

# 2. 使用备份恢复
BACKUP_FILE=$(ls -t /path/to/backups/mining-system-backup-* | head -1)
sudo tar -xzf $BACKUP_FILE -C /path/to/websitedata/

# 3. 恢复服务文件（如需要）
sudo cp /path/to/backups/mining-system.service /etc/systemd/system/ 2>/dev/null || true

# 4. 重载并启动
sudo systemctl daemon-reload
sudo systemctl start mining-system

echo "已回滚到: $BACKUP_FILE"

---

Ubuntu直接部署

1. 更新系统

sudo apt-get update && sudo apt-get upgrade -y

2. 安装Python及依赖

sudo apt-get install -y \
    python3 \
    python3-pip \
    python3-venv \
    python3-dev \
    build-essential \
    git \
    curl \
    wget

3. 上传项目并安装

# 上传项目文件到服务器
# scp -r ./mining-system user@server:/path/to/websitedata/

cd /path/to/websitedata/mining-system

# 执行一键安装
sudo bash install.sh

4. 手动安装（如不使用脚本）

cd /path/to/websitedata/mining-system

# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate

# 安装依赖
pip install --upgrade pip
pip install -r requirements.txt

# 创建标签名称目录
mkdir -p ../name

5. 配置数据库连接

编辑 config.py，修改数据库配置：

DB_HOST = os.getenv('DB_HOST', '你的数据库IP')
DB_PORT = int(os.getenv('DB_PORT', 3306))
DB_USER = os.getenv('DB_USER', '你的用户名')
DB_PASSWORD = os.getenv('DB_PASSWORD', '你的密码')
DB_NAME = os.getenv('DB_NAME', '你的数据库名')

6. 启动服务

# 前台启动（测试用）
bash start.sh

# 或使用systemd服务（生产环境）
sudo bash install.sh  # 选择配置系统服务
sudo systemctl start mining-system
sudo systemctl enable mining-system

---

Docker部署（推荐）

环境准备

确保服务器已安装 Docker 和 Docker Compose：

# 安装Docker
curl -fsSL https://get.docker.com | sudo bash

# 安装Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

# 验证安装
docker --version
docker-compose --version

创建Dockerfile

在项目根目录创建 Dockerfile：

FROM python:3.10-slim

WORKDIR /app

# 安装系统依赖
RUN apt-get update && apt-get install -y \
    gcc \
    default-libmysqlclient-dev \
    && rm -rf /var/lib/apt/lists/*

# 复制依赖文件并安装
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 复制项目文件
COPY . .

# 创建必要目录
RUN mkdir -p /app/../name

# 暴露端口
EXPOSE 5000

# 健康检查
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:5000/')" || exit 1

# 启动命令
CMD ["python", "app.py"]

创建.dockerignore

在项目根目录创建 .dockerignore：

venv/
__pycache__/
*.pyc
*.pyo
*.db-journal
.env
.DS_Store
*.log
.git/

构建并运行

# 构建镜像
docker build -t mining-system:latest .

# 运行容器（使用环境变量配置）
docker run -d \
    --name mining-system \
    --restart unless-stopped \
    -p 5000:5000 \
    -e DB_HOST=你的数据库IP \
    -e DB_PORT=3306 \
    -e DB_USER=你的用户名 \
    -e DB_PASSWORD=你的密码 \
    -e DB_NAME=你的数据库名 \
    -e DEFAULT_AI_MODEL=qwen \
    -v /path/to/name:/app/../name \
    mining-system:latest

# 查看日志
docker logs -f mining-system

# 停止容器
docker stop mining-system

# 启动容器
docker start mining-system

使用配置文件

如果需要使用 config.py 而不是环境变量：

# 将config.py复制到项目目录，然后
docker run -d \
    --name mining-system \
    --restart unless-stopped \
    -p 5000:5000 \
    -v /path/to/mining-system:/app \
    -v /path/to/name:/app/../name \
    mining-system:latest

---

Docker Compose部署（推荐）

创建 docker-compose.yml

在项目根目录创建 docker-compose.yml：

version: '3.8'

services:
  mining-system:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: mining-system
    restart: unless-stopped
    ports:
      - "5000:5000"
    environment:
      - DB_HOST=你的数据库IP
      - DB_PORT=3306
      - DB_USER=你的用户名
      - DB_PASSWORD=你的密码
      - DB_NAME=你的数据库名
      - DEFAULT_AI_MODEL=qwen
    volumes:
      # 标签名称目录映射
      - ./name:/app/../name
      # 日志目录（可选）
      - ./logs:/app/logs
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:5000/')"]
      interval: 30s
      timeout: 3s
      retries: 3
      start_period: 10s
    networks:
      - mining-network

  # 可选：Nginx反向代理
  nginx:
    image: nginx:alpine
    container_name: mining-nginx
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf
      # SSL证书（如使用HTTPS）
      # - ./ssl:/etc/nginx/ssl
    depends_on:
      - mining-system
    networks:
      - mining-network

networks:
  mining-network:
    driver: bridge

使用Docker Compose启动

# 启动所有服务
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f

# 查看mining-system日志
docker-compose logs -f mining-system

# 停止所有服务
docker-compose down

# 重启服务
docker-compose restart

# 更新并重启（修改代码后）
docker-compose up -d --build

# 进入容器内部
docker-compose exec mining-system bash

Docker Compose 环境变量文件

创建 .env 文件管理敏感信息：

# .env 文件（不要提交到git）
DB_HOST=192.168.x.x
DB_PORT=3306
DB_USER=your_username
DB_PASSWORD=your_password
DB_NAME=your_database
DEFAULT_AI_MODEL=qwen

# AI模型配置
AI_API_URL=http://your-ai-api:port/path
AI_API_KEY=your-api-key

修改 docker-compose.yml 使用环境变量文件：

services:
  mining-system:
    # ... 其他配置
    env_file:
      - .env
    # 移除 environment 部分，改用 env_file

---

配置说明

环境变量配置

变量名	说明	默认值
DB_HOST	数据库主机地址	192.168.75.129
DB_PORT	数据库端口	3306
DB_USER	数据库用户名	-
DB_PASSWORD	数据库密码	-
DB_NAME	数据库名称	-
DEFAULT_AI_MODEL	默认AI模型 (kimi/deepseek/qwen/zhipu)	qwen
SECRET_KEY	Flask密钥	-
API_URL	组态王API地址	-
USER_HANDLE	组态王用户句柄	-

标签中文名称配置

标签的中文名称从CSV文件加载：

websitedata/
├── mining-system/    # 本应用
│   ├── app.py
│   ├── config.py
│   └── ...
└── name/             # 标签名称CSV文件目录
    ├── 52300工作面采煤机.csv
    ├── 52300工作面泵站主站.csv
    └── ...

CSV文件格式要求：

• 包含 TagName 列（标签英文名）
• 包含 Description 列（中文描述/名称）

AI模型配置

系统支持多个AI模型，在 config.py 中配置：

AI_MODELS = {
    'kimi': {
        'name': 'Kimi (Qwen3.5-122B-A10B)',
        'api_url': 'http://your-ai-api/chat/completions',
        'api_key': 'your-api-key',
        'model': 'Qwen3.5-122B-A10B'
    },
    'deepseek': {
        'name': 'DeepSeek-V3.2-671B',
        # ...
    },
    # 更多模型...
}

---

Nginx反向代理

安装Nginx

sudo apt-get install -y nginx

配置反向代理

sudo nano /etc/nginx/sites-available/mining-system

server {
    listen 80;
    server_name your-server-ip;  # 修改为服务器IP或域名

    access_log /var/log/nginx/mining-access.log;
    error_log /var/log/nginx/mining-error.log;

    client_max_body_size 50M;

    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
        
        # AI分析可能需要较长时间
        proxy_connect_timeout 600;
        proxy_send_timeout 600;
        proxy_read_timeout 600;
    }

    # 静态文件缓存（可选，如Nginx直接服务静态文件）
    location /static/ {
        alias /path/to/mining-system/static/;
        expires 30d;
        add_header Cache-Control "public, immutable";
    }
}

# 启用配置
sudo ln -s /etc/nginx/sites-available/mining-system /etc/nginx/sites-enabled/
sudo rm /etc/nginx/sites-enabled/default  # 可选
sudo nginx -t
sudo systemctl reload nginx

---

SSL HTTPS配置

使用Let's Encrypt

# 安装certbot
sudo apt-get install -y certbot python3-certbot-nginx

# 获取并配置证书
sudo certbot --nginx -d your-domain.com

# 验证自动续期
sudo certbot renew --dry-run

使用自有证书

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /etc/nginx/ssl/cert.pem;
    ssl_certificate_key /etc/nginx/ssl/key.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    location / {
        proxy_pass http://127.0.0.1:5000;
        # ... 其他代理配置
    }
}

# HTTP重定向到HTTPS
server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$host$request_uri;
}

---

常见问题

1. 数据库连接失败

pymysql.err.OperationalError: (2003, "Can't connect to MySQL server")

解决方案:

• 检查网络连通性: ping 数据库IP
• 检查端口: telnet 数据库IP 端口
• 检查防火墙规则
• 确认数据库MySQL兼容模式已启用

2. Docker容器启动失败

# 查看容器日志
docker logs mining-system

# 常见问题：
# 1. 数据库连接超时 - 检查数据库IP是否在Docker网络中可达
# 2. 权限问题 - 检查卷挂载目录权限
# 3. 端口冲突 - 检查5000端口是否被占用

3. 升级后页面异常

# 清理浏览器缓存
# 或强制刷新 Ctrl+F5

# 检查JavaScript错误
# 浏览器F12 -> Console

# 重启服务
sudo systemctl restart mining-system
# 或
docker-compose restart

4. AI分析无响应

• 检查AI API服务是否可用
• 检查网络是否可达AI服务地址
• 查看日志: sudo journalctl -u mining-system -f 或 docker-compose logs -f

5. 内存不足

# 增加swap
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

---

备份与恢复

完整备份

PROJECT_DIR="/path/to/websitedata/mining-system"
BACKUP_DIR="/path/to/backups"
DATE=$(date +%Y%m%d)

sudo mkdir -p $BACKUP_DIR

# 备份项目
sudo tar -czf $BACKUP_DIR/mining-system-$DATE.tar.gz \
    -C /path/to/websitedata \
    mining-system

# 备份数据库
sudo cp $PROJECT_DIR/mining_data.db $BACKUP_DIR/mining_data.db-$DATE

# 备份配置文件
sudo cp /etc/systemd/system/mining-system.service $BACKUP_DIR/ 2>/dev/null || true
sudo cp /etc/nginx/sites-available/mining-system $BACKUP_DIR/ 2>/dev/null || true

恢复

# 恢复项目
sudo tar -xzf mining-system-20260625.tar.gz -C /path/to/websitedata/

# 恢复数据库
sudo cp mining_data.db.20260625 /path/to/websitedata/mining-system/

# 恢复服务
sudo systemctl daemon-reload
sudo systemctl restart mining-system
sudo systemctl reload nginx  # 如配置了Nginx

Docker环境备份

# 导出容器数据
docker commit mining-system mining-system-backup:$(date +%Y%m%d)

# 备份卷数据
docker run --rm -v mining-system_name:/data -v $(pwd):/backup alpine tar czf /backup/name-volume-backup.tar.gz -C /data .

# 恢复
docker load < mining-system-backup.tar

---

技术支持

如有问题，请联系神东煤炭集团西安研发团队。