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

## 目录

1. [系统简介](#系统简介)
2. [系统要求](#系统要求)
3. [新版本功能说明](#新版本功能说明)
4. [Git一键升级（推荐）](#git一键升级推荐)
5. [服务器升级指南（重要）](#服务器升级指南重要)
6. [Ubuntu直接部署](#ubuntu直接部署)
7. [Docker部署（推荐）](#docker部署推荐)
8. [Docker Compose部署（推荐）](#docker-compose部署推荐)
9. [配置说明](#配置说明)
10. [Nginx反向代理](#nginx反向代理)
11. [SSL HTTPS配置](#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仓库

### 快速升级

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

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

### 升级到指定版本

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

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

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

### 查看版本状态

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

### 仅执行备份

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

### 回滚到上一版本

```bash
# 交互式回滚（会提示确认）
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仓库：

```bash
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. 备份现有系统

```bash
# 假设原项目路径为 /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. 停止当前服务

```bash
# 如果使用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
```

### 执行升级

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

```bash
# 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 停止测试进程
```

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

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

### 升级后验证

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

### 回滚方案

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

```bash
# 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. 更新系统

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

### 2. 安装Python及依赖

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

### 3. 上传项目并安装

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

cd /path/to/websitedata/mining-system

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

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

```bash
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`，修改数据库配置：

```python
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
# 前台启动（测试用）
bash start.sh

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

---

## Docker部署（推荐）

### 环境准备

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

```bash
# 安装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`：

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

### 构建并运行

```bash
# 构建镜像
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` 而不是环境变量：

```bash
# 将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`：

```yaml
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启动

```bash
# 启动所有服务
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
# .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` 使用环境变量文件：

```yaml
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` 中配置：

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

```bash
sudo apt-get install -y nginx
```

### 配置反向代理

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

```nginx
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";
    }
}
```

```bash
# 启用配置
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

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

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

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

### 使用自有证书

```nginx
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容器启动失败

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

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

### 3. 升级后页面异常

```bash
# 清理浏览器缓存
# 或强制刷新 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. 内存不足

```bash
# 增加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
```

---

## 备份与恢复

### 完整备份

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

### 恢复

```bash
# 恢复项目
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环境备份

```bash
# 导出容器数据
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
```

---

## 技术支持

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