tool/tool-node
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(readme): 更新 README 文档，新增定时任务与邮件推送功能说明

Browse Source 
- 添加定时任务自动采集、邮件推送 HTML 报告等功能介绍
- 补充快速开始配置指引和 Web 配置界面使用说明
- 新增定时任务和邮件配置的 API 接口文档
- 完善部署指南，支持 PM2 和 systemd 方式
- 增加常见问题解答，涵盖定时任务与邮件相关问题
- 更新项目结构与技术栈说明，体现无数据库架构特点
This commit is contained in:
zhaojunlong
2025-12-15 15:27:53 +08:00
parent b4afc1ce5a
commit 00658a3445
1 changed files with 315 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

331
README.md
View File

@@ -1,6 +1,6 @@
# 南京公共工程建设中心 - 公告采集工具 # 南京公共工程建设中心 - 公告采集工具
一个用于采集南京公共工程建设中心公告信息的 Web 可视化工具。 一个用于采集南京公共工程建设中心公告信息的 Web 可视化工具，支持定时任务和邮件推送。
## 功能特性 ## 功能特性
@@ -12,13 +12,36 @@
- ✅ Web 可视化界面 - ✅ Web 可视化界面
- ✅ 导出 Word/Markdown 报告 - ✅ 导出 Word/Markdown 报告
- ✅ RESTful API 支持 - ✅ RESTful API 支持
- ✅ **定时任务自动采集**
- ✅ **邮件推送 HTML 报告**
- ✅ **Web 配置界面**
- ✅ **无需数据库，轻量部署**
## 安装 ## 快速开始
### 1. 安装依赖
```bash ```bash
npm install npm install
``` ```
### 2. 配置文件
首次使用需要创建配置文件：
```bash
# 复制示例配置文件
cp config.example.json config.json
# 编辑配置文件（或通过 Web 界面配置）
# 填写邮件服务器信息和定时任务设置
```
**配置文件说明：**
- `config.example.json` - 配置模板（不含敏感信息，可提交到 Git）
- `config.json` - 实际配置（包含密码等敏感信息，已在 .gitignore 中忽略）
## 使用方法 ## 使用方法
### 1. 启动服务器 ### 1. 启动服务器
@@ -53,6 +76,23 @@ npm start
- 实时统计项目信息 - 实时统计项目信息
- 一键导出 Word/Markdown 报告 - 一键导出 Word/Markdown 报告
**定时任务标签** ⭐ 新增
- Web 界面配置定时任务
- 支持 Cron 表达式自定义执行时间
- 可选时间范围（今日/本周/本月）
- 设置金额阈值自动筛选
- 实时查看任务运行状态
- 立即测试运行功能
**邮件配置标签** ⭐ 新增
- Web 界面配置 SMTP 邮件服务
- 支持主流邮箱（QQ、163、Gmail 等）
- 测试连接功能验证配置
- 支持多个收件人
- 自动发送精美 HTML 报告
## 报告示例 ## 报告示例
```markdown ```markdown
@@ -143,35 +183,233 @@ Content-Type: application/json
} }
``` ```
### 6. 获取配置
```
GET /api/config
```
返回当前配置信息（密码会被隐藏）
### 7. 更新配置
```
POST /api/config
Content-Type: application/json
{
"scheduler": {
"enabled": true,
"cronTime": "0 9 * * *",
"threshold": 100000,
"timeRange": "today"
},
"email": {
"smtpHost": "smtp.qq.com",
"smtpPort": 587,
"smtpUser": "your-email@qq.com",
"smtpPass": "your-password",
"recipients": "recipient@example.com"
}
}
```
### 8. 获取定时任务状态
```
GET /api/scheduler/status
```
### 9. 手动触发定时任务
```
POST /api/run-scheduled-task
```
## 定时任务配置
### 通过 Web 界面配置（推荐）
1. 访问 `http://localhost:3000`
2. 切换到 **"定时任务"** 标签
3. 配置以下选项：
- **启用定时任务**：勾选启用
- **执行时间**：选择预设时间或自定义 Cron 表达式
- **时间范围**：今日/本周/本月
- **金额阈值**：设置最低金额（单位：万元）
4. 切换到 **"邮件配置"** 标签
5. 配置 SMTP 邮件服务器信息
6. 点击"测试连接"验证配置
7. 点击"保存配置"，定时任务自动生效
### 通过配置文件
编辑 `config.json`：
```json
{
"scheduler": {
"enabled": true, // 是否启用
"cronTime": "0 9 * * *", // Cron表达式：每天9点
"threshold": 100000, // 金额阈值（万元，10亿）
"description": "每天9点采集大于10亿的项目",
"timeRange": "today" // 采集范围: today/thisWeek/thisMonth
},
"email": {
"smtpHost": "smtp.qq.com", // SMTP服务器
"smtpPort": 587, // 端口
"smtpUser": "your@qq.com", // 发件邮箱
"smtpPass": "授权码", // QQ邮箱授权码
"recipients": "to@qq.com" // 收件人（多个用逗号分隔）
}
}
```
### Cron 表达式说明
格式：`分 时 日 月 周`
常用示例：
- `0 9 * * *` - 每天 9:00
- `0 9,18 * * *` - 每天 9:00 和 18:00
- `0 9 * * 1` - 每周一 9:00
- `0 9 1 * *` - 每月1号 9:00
- `0 */6 * * *` - 每 6 小时
### 邮件服务配置参考
**QQ 邮箱：**
- SMTP: `smtp.qq.com`
- 端口: `587`
- 密码: 使用授权码（在 QQ 邮箱设置中生成）
**163 邮箱：**
- SMTP: `smtp.163.com`
- 端口: `465`
- 密码: 使用授权码
**Gmail：**
- SMTP: `smtp.gmail.com`
- 端口: `587`
- 需要开启"不够安全的应用访问"
## 服务器部署
### 方法 1：使用 PM2（推荐）
```bash
# 安装 PM2
npm install -g pm2
# 启动服务
pm2 start src/server.js --name gjzx-scraper
# 查看状态
pm2 status
# 查看日志
pm2 logs gjzx-scraper
# 设置开机自启
pm2 startup
pm2 save
```
### 方法 2：使用 systemd
创建服务文件 `/etc/systemd/system/gjzx-scraper.service`：
```ini
[Unit]
Description=GJZX Scraper Service
After=network.target
[Service]
Type=simple
User=your-user
WorkingDirectory=/path/to/tool-node
ExecStart=/usr/bin/node src/server.js
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target
```
启动服务：
```bash
sudo systemctl enable gjzx-scraper
sudo systemctl start gjzx-scraper
sudo systemctl status gjzx-scraper
```
### 注意事项
- ✅ **无需数据库**：项目采用无数据库架构，轻量部署
- ✅ **配置持久化**：所有配置保存在 `config.json` 文件中
- ✅ **进程保活**：使用 PM2 或 systemd 确保进程持续运行
- ⚠️ **防火墙**：确保 3000 端口可访问
- ⚠️ **配置安全**：不要将 `config.json` 提交到公开仓库
## 技术栈 ## 技术栈
- **后端**: Node.js + Express - **后端**: Node.js + Express
- **爬虫**: Axios + Cheerio - **爬虫**: Axios + Cheerio
- **定时任务**: node-cron
- **邮件服务**: nodemailer
- **前端**: 原生 HTML/CSS/JavaScript - **前端**: 原生 HTML/CSS/JavaScript
- **编码处理**: iconv-lite (支持 GBK/UTF-8) - **编码处理**: iconv-lite (支持 GBK/UTF-8)
- **文档导出**: docx.js - **文档导出**: docx.js
- **架构**: 无数据库设计
## 项目结构 ## 项目结构
``` ```
. .
├── src/ ├── src/
│ └── server.js # Web服务器及API │ ├── server.js # Web服务器及API
│ ├── scheduler.js # 定时任务调度器
│ └── emailService.js # 邮件发送服务
├── public/ ├── public/
│ ├── index.html # Web界面 │ ├── index.html # Web界面
│ └── app.js # 前端逻辑 │ └── app.js # 前端逻辑
├── config.json # 配置文件（不提交到Git）
├── config.example.json # 配置示例
├── package.json ├── package.json
└── README.md └── README.md
``` ```
## 架构特点
### 无数据库设计
本项目采用**无数据库架构**，具有以下特点：
- ✅ **轻量部署**：无需安装和配置数据库
- ✅ **实时数据**：每次从源站实时抓取最新数据
- ✅ **配置简单**：只需配置 config.json 文件
- ✅ **邮件归档**：报告通过邮件发送，邮箱即为历史记录
- ✅ **低资源消耗**：内存占用小，适合小型服务器
### 数据流程
```
定时触发 → 抓取网站数据 → 解析提取 → 筛选过滤 → 生成报告 → 发送邮件
↑ ↓
└──────────────────── 配置文件 ──────────────────────────┘
```
## 注意事项 ## 注意事项
1. 采集速度已限制为每条延迟 500ms-1s,避免请求过快 1. **采集速度**：已限制为每条延迟 500ms-1s，避免请求过快
2. 仅支持 gjzx.nanjing.gov.cn 域名的详情页解析 2. **域名支持**：仅支持 gjzx.nanjing.gov.cn 域名的详情页解析
3. 金额提取基于正则匹配,支持多种格式(预算金额、最高限价等) 3. **金额提取**：基于正则匹配，支持多种格式（预算金额、最高限价等）
4. Web 服务器默认端口 3000,可在 server.js 中修改 4. **端口配置**：Web 服务器默认端口 3000，可在 server.js 中修改
5. 按时间范围采集会在检测到所有公告早于起始日期时自动停止 5. **智能停止**：按时间范围采集会在检测到所有公告早于起始日期时自动停止
6. 编码自动识别,支持 GBK 和 UTF-8 网页 6. **编码处理**：自动识别，支持 GBK 和 UTF-8 网页
7. **配置安全**：config.json 包含敏感信息，已加入 .gitignore，不要提交到公开仓库
8. **进程保活**：部署时使用 PM2 或 systemd 确保定时任务持续运行
## 核心功能说明 ## 核心功能说明
@@ -204,24 +442,85 @@ Content-Type: application/json
## 常见问题 ## 常见问题
### Q: 为什么采集速度比较慢? ### Q: 为什么采集速度比较慢？
A: 为了避免对服务器造成过大压力,程序限制了请求频率(每条延迟 500ms-1s)。这是一个负责任的爬虫设计。 A: 为了避免对服务器造成过大压力，程序限制了请求频率（每条延迟 500ms-1s）。这是一个负责任的爬虫设计。
### Q: 如何采集指定日期范围的公告? ### Q: 如何采集指定日期范围的公告？
A: 在 Web 界面的"详情采集"和"生成报告"标签中勾选"按时间范围采集",然后输入起始和结束日期即可。 A: 在 Web 界面的"详情采集"和"生成报告"标签中勾选"按时间范围采集"，然后输入起始和结束日期即可。
### Q: 导出的报告在哪里? ### Q: 导出的报告在哪里？
A: 点击"导出 Word"或"导出 Markdown"按钮后会自动下载到浏览器的默认下载目录。 A: 点击"导出 Word"或"导出 Markdown"按钮后会自动下载到浏览器的默认下载目录。
### Q: 可以采集其他网站吗? ### Q: 可以采集其他网站吗？
A: 需要修改 server.js 中的 BASE_URL 和相应的解析函数,因为不同网站的 HTML 结构不同。 A: 需要修改 server.js 中的 BASE_URL 和相应的解析函数，因为不同网站的 HTML 结构不同。
### Q: 需要安装数据库吗？
A: **不需要！** 本项目采用无数据库架构，只需安装 Node.js 依赖即可运行。所有配置保存在 config.json 文件中，报告通过邮件发送。
### Q: 定时任务配置后不生效怎么办？
A: 请检查以下几点：
1. `config.json` 中 `scheduler.enabled` 是否为 `true`
2. 邮件配置是否正确（SMTP 服务器、用户名、密码）
3. Node.js 进程是否持续运行（使用 PM2 查看状态）
4. 查看服务器日志是否有错误信息
### Q: 如何修改定时任务的执行时间？
A: 有两种方式：
1. **Web 界面**（推荐）：访问网页，切换到"定时任务"标签，选择预设时间或自定义 Cron 表达式，点击保存
2. **配置文件**：编辑 `config.json` 中的 `scheduler.cronTime` 字段
### Q: 邮件发送失败怎么办？
A: 常见原因：
1. **QQ 邮箱**：需要使用授权码，不是登录密码（在 QQ 邮箱设置 → 账户 → POP3/SMTP 服务中生成）
2. **端口问题**：QQ 邮箱使用 587，某些邮箱可能需要 465（SSL）
3. **防火墙**：确保服务器可以访问 SMTP 端口
4. **测试连接**：在"邮件配置"标签中使用"测试连接"功能验证配置
### Q: 如何查看定时任务运行日志？
A: 如果使用 PM2 部署：
```bash
pm2 logs gjzx-scraper
```
如果使用 systemd：
```bash
sudo journalctl -u gjzx-scraper -f
```
### Q: 服务器重启后定时任务还会运行吗？
A: 需要设置开机自启：
- **PM2 方式**：执行 `pm2 startup` 和 `pm2 save`
- **systemd 方式**：执行 `sudo systemctl enable gjzx-scraper`
### Q: 可以设置多个定时任务吗？
A: 当前版本只支持一个定时任务。如需多个任务，可以：
1. 使用 Cron 表达式设置多个时间点（如 `0 9,18 * * *` 表示每天 9:00 和 18:00）
2. 部署多个实例，使用不同的配置文件和端口
## 更新日志 ## 更新日志
### v1.1.0 (2025-12-15)
- ✨ 新增定时任务功能（node-cron）
- ✨ 新增邮件推送服务（nodemailer）
- ✨ 新增 Web 配置界面（定时任务 + 邮件配置）
- ✨ 支持多时间范围（今日/本周/本月）
- ✨ 配置 API（读取/更新配置）
- ✨ 定时任务状态查询
- ✨ 手动触发任务功能
- 📝 完善文档，新增部署指南
### v1.0.0 (2025-12-12) ### v1.0.0 (2025-12-12)
- Web 可视化界面 - Web 可视化界面