# 智能矿山标签监测系统 - Ubuntu部署教程

## 目录
1. [系统要求](#系统要求)
2. [环境准备](#环境准备)
3. [数据库配置](#数据库配置)
4. [部署应用](#部署应用)
5. [配置系统服务](#配置系统服务)
6. [配置Nginx反向代理](#配置nginx反向代理)
7. [配置SSL HTTPS](#配置ssl-https)
8. [常见问题](#常见问题)

---

## 系统要求

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

---

## 环境准备

### 1. 更新系统
```bash
sudo apt-get update && sudo apt-get upgrade -y
```

### 2. 安装Python 3.10
```bash
# Ubuntu 20.04 需要添加PPA
sudo apt-get install -y software-properties-common
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt-get update

# 安装Python
sudo apt-get install -y python3.10 python3.10-venv python3.10-dev
```

### 3. 安装pip
```bash
curl -sS https://bootstrap.pypa.io/get-pip.py | sudo python3.10
```

### 4. 安装其他工具
```bash
sudo apt-get install -y git curl wget build-essential
```

---

## 数据库配置

### 神通数据库连接说明

本系统使用 `pymysql` 连接神通数据库（通过MySQL兼容协议）。

#### 1. 确认数据库连接信息
```
数据库IP: 10.x.x.x
数据库端口: 2003 (神通默认端口)
数据库名: xxx
用户名: xxx
密码: xxx
```

#### 2. 测试数据库连接
```bash
# 安装MySQL客户端测试连接
sudo apt-get install -y default-mysql-client

# 测试连接
mysql -h 10.x.x.x -P 2003 -u username -p
```

#### 3. 修改配置文件
编辑 `config.py`:
```python
# 数据库配置
DB_HOST = '10.x.x.x'        # 修改为实际IP
DB_PORT = 2003               # 修改为实际端口
DB_USER = 'your_username'    # 修改为实际用户名
DB_PASSWORD = 'your_password' # 修改为实际密码
DB_NAME = 'your_database'    # 修改为实际数据库名
```

---

## 部署应用

### 方式一：一键安装脚本（推荐）

```bash
# 1. 上传项目到服务器
# 使用scp或sftp上传整个 websitedata 目录

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

# 3. 执行安装脚本
sudo bash install.sh
```

安装脚本会自动：
- 检查并安装系统依赖
- 创建Python虚拟环境
- 安装Python包依赖
- 创建必要的目录
- 可选配置systemd服务

### 方式二：手动安装

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

# 2. 创建虚拟环境
python3.10 -m venv venv

# 3. 激活虚拟环境
source venv/bin/activate

# 4. 升级pip
pip install --upgrade pip

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

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

# 7. 放置标签CSV文件
# 将神浍数据库导出的标签名称CSV文件放入 ../name/ 目录
```

### 配置标签中文名称

标签的中文名称映射从CSV文件加载，文件位于 `../name/` 目录。

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

CSV文件格式要求：
- 包含 `TagName` 列（标签英文名）
- 包含 `Description` 列（中文描述/名称）

---

## 配置系统服务

### 使用systemd管理应用

#### 1. 创建服务文件
```bash
sudo nano /etc/systemd/system/mining-system.service
```

#### 2. 写入以下内容
```ini
[Unit]
Description=智能矿山标签监测系统
After=network.target

[Service]
Type=simple
User=www-data
Group=www-data
WorkingDirectory=/path/to/websitedata/mining-system
Environment="PATH=/path/to/websitedata/mining-system/venv/bin"
ExecStart=/path/to/websitedata/mining-system/venv/bin/python3 app.py
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal

# 环境变量（可选）
# Environment="FLASK_ENV=production"

[Install]
WantedBy=multi-user.target
```

**注意**: 将 `/path/to/` 替换为实际路径，将 `www-data` 替换为实际运行用户。

#### 3. 启用并启动服务
```bash
# 重载systemd配置
sudo systemctl daemon-reload

# 启用开机自启
sudo systemctl enable mining-system

# 启动服务
sudo systemctl start mining-system

# 查看状态
sudo systemctl status mining-system

# 查看日志
sudo journalctl -u mining-system -f
```

#### 4. 常用管理命令
```bash
sudo systemctl stop mining-system      # 停止
sudo systemctl restart mining-system   # 重启
sudo systemctl status mining-system    # 状态
sudo journalctl -u mining-system -f    # 日志
```

---

## 配置Nginx反向代理

### 1. 安装Nginx
```bash
sudo apt-get install -y nginx
```

### 2. 创建配置文件
```bash
sudo nano /etc/nginx/sites-available/mining-system
```

### 3. 写入配置（使用项目中的nginx.conf内容）
```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;
        
        proxy_connect_timeout 300;
        proxy_send_timeout 300;
        proxy_read_timeout 300;
    }
}
```

### 4. 启用配置
```bash
# 创建软链接
sudo ln -s /etc/nginx/sites-available/mining-system /etc/nginx/sites-enabled/

# 移除默认配置（可选）
sudo rm /etc/nginx/sites-enabled/default

# 测试配置
sudo nginx -t

# 重载Nginx
sudo systemctl reload nginx
```

---

## 配置SSL HTTPS

### 使用Let's Encrypt免费证书

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

# 2. 获取证书
sudo certbot --nginx -d your-domain.com

# 3. 自动续期（certbot会自动配置）
sudo certbot renew --dry-run
```

---

## 防火墙配置

### 使用ufw
```bash
# 安装ufw
sudo apt-get install -y ufw

# 允许SSH（重要！）
sudo ufw allow OpenSSH

# 允许HTTP/HTTPS
sudo ufw allow 'Nginx Full'

# 启用防火墙
sudo ufw enable

# 查看状态
sudo ufw status
```

### 使用iptables
```bash
# 允许SSH
sudo iptables -A INPUT -p tcp --dport 22 -j ACCEPT

# 允许HTTP
sudo iptables -A INPUT -p tcp --dport 80 -j ACCEPT

# 允许HTTPS
sudo iptables -A INPUT -p tcp --dport 443 -j ACCEPT

# 保存规则
sudo apt-get install -y iptables-persistent
sudo netfilter-persistent save
```

---

## 常见问题

### 1. pymysql连接超时
```
pymysql.err.OperationalError: (2003, "Can't connect to MySQL server")
```
**解决方案**:
- 检查数据库服务器是否可访问: `ping 10.x.x.x`
- 检查端口是否开放: `telnet 10.x.x.x 2003`
- 检查防火墙规则
- 确认神通数据库的MySQL兼容模式已启用

### 2. 标签中文名称不显示
**解决方案**:
- 检查 `../name/` 目录是否存在
- 确认CSV文件格式正确（包含TagName和Description列）
- 重启应用重新加载映射

### 3. 虚拟环境激活失败
```bash
# 确认python路径
which python3.10
# 重新创建虚拟环境
rm -rf venv
python3.10 -m venv venv
source venv/bin/activate
```

### 4. 权限问题
```bash
# 设置正确的文件所有者
sudo chown -R www-data:www-data /path/to/websitedata

# 或设置为你自己的用户
sudo chown -R $USER:$USER /path/to/websitedata
```

### 5. 端口被占用
```bash
# 检查5000端口占用
sudo lsof -i :5000

# 杀死占用进程
sudo kill -9 PID
```

### 6. 内存不足
如果服务器内存较小，可以增加swap:
```bash
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
# systemd服务日志
sudo journalctl -u mining-system -f

# 或直接查看应用输出
tail -f /path/to/logs/*.log
```

### Nginx日志
```bash
sudo tail -f /var/log/nginx/mining-access.log
sudo tail -f /var/log/nginx/mining-error.log
```

---

## 性能优化

### 1. 使用Gunicorn替代Flask开发服务器

```bash
# 安装gunicorn
pip install gunicorn

# 启动
gunicorn -w 4 -b 127.0.0.1:5000 app:app
```

修改systemd服务文件中的ExecStart:
```ini
ExecStart=/path/to/venv/bin/gunicorn -w 4 -b 127.0.0.1:5000 app:app
```

### 2. 启用数据库连接池
已在 `database.py` 中配置PooledDB连接池。

### 3. 静态文件由Nginx直接服务
在nginx.conf中启用静态文件缓存配置。

---

## 备份与恢复

### 备份配置
```bash
tar -czf mining-backup-$(date +%Y%m%d).tar.gz \
    /path/to/websitedata \
    /etc/systemd/system/mining-system.service \
    /etc/nginx/sites-available/mining-system
```

### 恢复
```bash
sudo tar -xzf mining-backup-20260530.tar.gz
sudo systemctl daemon-reload
sudo systemctl restart mining-system
sudo systemctl reload nginx
```

---

## 更新部署

```bash
cd /path/to/websitedata/mining-system

# 拉取最新代码（如果使用git）
git pull

# 激活虚拟环境
source venv/bin/activate

# 更新依赖
pip install -r requirements.txt

# 重启服务
sudo systemctl restart mining-system
```

---

## 技术支持

如有问题，请联系开发团队或查看项目README。