chore: initial commit — existing lottoData codebase

Files: - lottery.py (1189 lines) — DoubleColorBallGenerator core engine - fetch_data.py (131 lines) — history data fetcher from 55128.cn - web_executor.py (216 lines) — data fetch Web console (Flask :5000) - app.py (505 lines) — number generation Web service (Flask :8085) - index.html (1171 lines) — frontend SPA - web_console.html (323 lines) — fetch console frontend - deploy/ — systemd service + cron script + logs BIZ-74 architecture review baseline
2026-07-03 16:39:21 +08:00
commit 13a259b0f8
27 changed files with 5025 additions and 0 deletions
@@ -0,0 +1,178 @@
+# 双色球系统部署文档
+
+## 部署信息
+
+| 项目 | 值 |
+|------|-----|
+| 项目名称 | 双色球自动化系统 |
+| 部署时间 | 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