# 双色球系统部署文档

## 部署信息

| 项目 | 值 |
|------|-----|
| 项目名称 | 双色球自动化系统 |
| 部署时间 | 2026-06-29 |
| 部署人员 | 严维序 (opengineer) |
| 服务地址 | http://192.168.1.99:5000 |
| 宿主服务器 | Ubuntu-OpenClaw (192.168.1.99) |

---

## 一、项目结构

```
/home/vincent/Studio/lottoData/
├── venv/                       # Python 虚拟环境
├── web_executor.py             # Flask Web 服务 (监听 0.0.0.0:5000)
├── fetch_data.py               # 数据抓取脚本
├── lottery.py                  # 双色球号码生成器
├── web_console.html            # Web 控制台页面
├── LottoSpider/                # 爬虫模块
├── lottery/                    # 彩票模块
├── docs/                       # 文档
├── 双色球历史数据.xlsx          # 历史数据文件
└── deploy/                     # 部署文件
    ├── DEPLOY.md               # 本文档
    ├── lotto-web.service       # systemd 服务文件
    ├── fetch_daily.sh          # 每日抓取脚本
    ├── cron.log                # Cron 执行日志
    └── fetch_YYYYMMDD.log      # 每日抓取详细日志
```

---

## 二、依赖清单

| 包 | 版本 | 用途 |
|----|------|------|
| Flask | 3.1.3 | Web 服务框架 |
| pandas | 3.0.4 | 数据处理 |
| openpyxl | 3.1.5 | Excel 读写 |
| requests | 2.34.2 | HTTP 请求 |
| beautifulsoup4 | 4.15.0 | HTML 解析 |

安装命令：
```bash
python3 -m venv venv
./venv/bin/pip install flask pandas openpyxl requests beautifulsoup4
```

---

## 三、systemd 服务配置

### 服务文件

`/etc/systemd/system/lotto-web.service`

```ini
[Unit]
Description=双色球数据抓取 Web 服务
After=network.target

[Service]
Type=simple
User=vincent
WorkingDirectory=/home/vincent/Studio/lottoData
ExecStart=/home/vincent/Studio/lottoData/venv/bin/python3 /home/vincent/Studio/lottoData/web_executor.py
ExecStartPre=/home/vincent/Studio/lottoData/venv/bin/python3 -c "import flask; import pandas; import openpyxl; import requests; import bs4"
Restart=on-failure
RestartSec=5
KillMode=control-group

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

### 管理命令

```bash
# 安装/启用
sudo cp deploy/lotto-web.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable lotto-web
sudo systemctl start lotto-web

# 日常管理
sudo systemctl status lotto-web    # 查看状态
sudo systemctl restart lotto-web   # 重启
sudo systemctl stop lotto-web      # 停止
sudo journalctl -u lotto-web -f    # 查看实时日志
```

---

## 四、Cron 定时任务

### Cron 配置

```
30 2 * * * /home/vincent/Studio/lottoData/deploy/fetch_daily.sh >> /home/vincent/Studio/lottoData/deploy/cron.log 2>&1
```

每天凌晨 2:30 自动抓取双色球历史数据。

### 手动执行

```bash
/home/vincent/Studio/lottoData/deploy/fetch_daily.sh
# 或
/home/vincent/Studio/lottoData/venv/bin/python3 /home/vincent/Studio/lottoData/fetch_data.py
```

---

## 五、Web 接口

| 路径 | 方法 | 说明 |
|------|------|------|
| `/` | GET | Web 控制台页面 |
| `/api/status` | GET | 获取执行状态 |
| `/api/execute` | POST | 触发数据抓取 |

### 示例

```bash
# 查看状态
curl http://192.168.1.99:5000/api/status

# 触发抓取
curl -X POST http://192.168.1.99:5000/api/execute
```

---

## 六、验证清单

- [x] 依赖安装完整 (Flask, pandas, openpyxl, requests, beautifulsoup4)
- [x] systemd 服务运行正常 (active, enabled)
- [x] Web 服务可访问 (http://192.168.1.99:5000, HTTP 200)
- [x] API 接口正常 (/api/status, /api/execute)
- [x] Cron 定时任务已配置 (每日 2:30 抓取)
- [x] 手动抓取测试通过 (121 条记录保存成功)
- [x] 开机自启已配置 (systemd enable)

---

## 七、回滚方案

```bash
# 停止服务
sudo systemctl stop lotto-web
sudo systemctl disable lotto-web
sudo rm /etc/systemd/system/lotto-web.service
sudo systemctl daemon-reload

# 移除 cron
crontab -l | grep -v 'lottoData' | crontab -

# 不影响数据文件和代码
```

---

## 八、监控要点

1. **服务存活**：`systemctl status lotto-web` 确认 active
2. **Web 可达**：`curl http://127.0.0.1:5000/api/status`
3. **数据更新**：检查 `/home/vincent/Studio/lottoData/双色球历史数据.xlsx` 修改时间
4. **Cron 日志**：检查 `/home/vincent/Studio/lottoData/deploy/cron.log`
5. **磁盘空间**：Excel 文件约 250KB，可忽略

---

> 部署人：严维序 (opengineer) | 2026-06-29