feat: v2.6.0 - API安全优化和文档整合
## 核心优化 - 移除详情页自动调用博查API的逻辑，改为按需加载 - 添加基于IP的频率限制（每小时3次） - 实现验证码防护机制（超过阈值后要求验证） - 新增频率限制工具类 utils/rate_limiter.py ## 成本控制 - API调用减少约90%+（只在用户点击时调用） - 防止恶意滥用和攻击 - 可配置的频率限制和验证码策略 ## 文档整合 - 创建 docs/ 目录结构 - 归档历史版本文档到 docs/archive/ - 移动部署文档到 docs/deployment/ - 添加文档索引 docs/README.md ## 技术变更 - 新增依赖: Flask-Limiter==3.5.0 - 修改: app.py (移除自动调用，新增API端点) - 修改: templates/detail_new.html (按需加载UI) - 新增: utils/rate_limiter.py (频率限制和验证码) - 新增: docs/archive/DEVELOP_v2.6.0_API_SECURITY.md ## 部署说明 1. pip install Flask-Limiter==3.5.0 2. 重启应用 3. 无需数据库迁移 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Jowe
408
docs/archive/NEWS_FEATURE_v2.2.md
Normal file
408
docs/archive/NEWS_FEATURE_v2.2.md
Normal file
@@ -0,0 +1,408 @@
|
||||
# ZJPB v2.2.0 - 新闻搜索功能
|
||||
|
||||
**版本**: v2.2.0
|
||||
**发布日期**: 2025-01-30
|
||||
**主要功能**: 集成博查Web Search API，自动获取网站相关新闻
|
||||
|
||||
---
|
||||
|
||||
## 📋 功能概述
|
||||
|
||||
v2.2.0版本引入了全新的新闻搜索和展示功能，通过博查AI搜索引擎API，自动为每个网站获取最新的相关新闻，并在网站详情页进行展示。
|
||||
|
||||
### ✨ 核心特性
|
||||
|
||||
1. **智能新闻搜索** 🔍
|
||||
- 基于网站名称自动搜索相关新闻
|
||||
- 支持自定义搜索时间范围（一天、一周、一月、一年）
|
||||
- 自动排除网站自身的内容，确保新闻来源多样性
|
||||
|
||||
2. **新闻管理系统** 📰
|
||||
- 后台新闻列表管理
|
||||
- 支持手动编辑和删除新闻
|
||||
- 新闻来源信息展示（网站名称、图标）
|
||||
|
||||
3. **前台新闻展示** 🎨
|
||||
- 网站详情页展示最多5条相关新闻
|
||||
- 显示新闻标题、摘要、来源、发布时间
|
||||
- 点击新闻直接跳转到原文链接
|
||||
|
||||
4. **定期任务支持** ⏰
|
||||
- 提供cron任务脚本，支持定期批量获取新闻
|
||||
- 可配置获取数量、时间范围等参数
|
||||
|
||||
---
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 1. 配置博查API
|
||||
|
||||
在`.env`文件中添加博查API配置：
|
||||
|
||||
```env
|
||||
# 博查 Web Search API配置
|
||||
BOCHA_API_KEY=sk-your-api-key-here
|
||||
BOCHA_BASE_URL=https://api.bocha.cn
|
||||
```
|
||||
|
||||
获取API Key：访问 [博查AI开放平台](https://open.bocha.cn) 注册并获取API密钥。
|
||||
|
||||
### 2. 数据库迁移
|
||||
|
||||
运行迁移脚本，为News表添加新字段：
|
||||
|
||||
```bash
|
||||
python migrate_news_fields.py
|
||||
```
|
||||
|
||||
迁移会添加以下字段：
|
||||
- `source_name`: 新闻来源网站名称
|
||||
- `source_icon`: 新闻来源网站图标URL
|
||||
|
||||
### 3. 测试新闻获取
|
||||
|
||||
#### 方法1：使用Python测试脚本
|
||||
|
||||
```bash
|
||||
# 测试NewsSearcher类
|
||||
python utils/news_searcher.py
|
||||
```
|
||||
|
||||
#### 方法2：使用后台API
|
||||
|
||||
登录后台后，使用API接口：
|
||||
|
||||
**单个网站获取新闻**：
|
||||
```bash
|
||||
curl -X POST http://localhost:5000/api/fetch-site-news \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"site_id": 1,
|
||||
"count": 10,
|
||||
"freshness": "oneMonth"
|
||||
}'
|
||||
```
|
||||
|
||||
**批量获取新闻**：
|
||||
```bash
|
||||
curl -X POST http://localhost:5000/api/fetch-all-news \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"count": 5,
|
||||
"freshness": "oneMonth",
|
||||
"limit": 10
|
||||
}'
|
||||
```
|
||||
|
||||
### 4. 查看新闻
|
||||
|
||||
1. 访问任意网站详情页（例如：`http://localhost:5000/site/12345678`）
|
||||
2. 滚动到页面下方，查看"相关新闻"部分
|
||||
3. 点击新闻标题或"阅读全文"链接跳转到原文
|
||||
|
||||
---
|
||||
|
||||
## 📖 使用指南
|
||||
|
||||
### 后台管理
|
||||
|
||||
#### 新闻管理界面
|
||||
|
||||
1. 登录后台：`http://localhost:5000/admin`
|
||||
2. 点击左侧菜单"新闻管理"
|
||||
3. 可以查看、编辑、删除已获取的新闻
|
||||
|
||||
**新闻列表字段**：
|
||||
- ID
|
||||
- 关联网站
|
||||
- 新闻标题
|
||||
- 来源网站
|
||||
- 新闻类型
|
||||
- 发布时间
|
||||
- 是否启用
|
||||
|
||||
#### 手动获取新闻
|
||||
|
||||
虽然提供了API接口，但目前没有直接的后台UI按钮。可以通过以下方式触发：
|
||||
|
||||
1. 使用API接口（参见快速开始）
|
||||
2. 使用定期任务脚本（参见下文）
|
||||
|
||||
### 定期任务设置
|
||||
|
||||
使用`fetch_news_cron.py`脚本定期自动获取新闻。
|
||||
|
||||
#### 手动执行
|
||||
|
||||
```bash
|
||||
# 默认参数：处理10个网站，每个网站获取5条新闻，时间范围一个月
|
||||
python fetch_news_cron.py
|
||||
|
||||
# 自定义参数
|
||||
python fetch_news_cron.py --limit 20 --count 10 --freshness oneWeek
|
||||
```
|
||||
|
||||
**参数说明**：
|
||||
- `--limit`: 处理的网站数量限制（默认：10）
|
||||
- `--count`: 每个网站获取的新闻数量（默认：5）
|
||||
- `--freshness`: 新闻时间范围（可选：noLimit, oneDay, oneWeek, oneMonth, oneYear）
|
||||
|
||||
#### 配置Crontab
|
||||
|
||||
在Linux服务器上配置定期任务：
|
||||
|
||||
```bash
|
||||
# 编辑crontab
|
||||
crontab -e
|
||||
|
||||
# 添加以下行（每天早上8点执行）
|
||||
0 8 * * * cd /opt/1panel/apps/zjpb && /opt/1panel/apps/zjpb/venv/bin/python fetch_news_cron.py --limit 10 >> logs/news_fetch.log 2>&1
|
||||
|
||||
# 或每6小时执行一次
|
||||
0 */6 * * * cd /opt/1panel/apps/zjpb && /opt/1panel/apps/zjpb/venv/bin/python fetch_news_cron.py --limit 20 >> logs/news_fetch.log 2>&1
|
||||
```
|
||||
|
||||
**注意**：
|
||||
- 确保创建`logs`目录：`mkdir -p logs`
|
||||
- 修改路径为实际的项目路径
|
||||
- 根据API配额合理设置执行频率
|
||||
|
||||
---
|
||||
|
||||
## 🗂️ 文件结构
|
||||
|
||||
### 新增文件
|
||||
|
||||
```
|
||||
zjpb/
|
||||
├── utils/
|
||||
│ └── news_searcher.py # 博查API封装类
|
||||
├── migrate_news_fields.py # 数据库迁移脚本
|
||||
├── fetch_news_cron.py # 定期任务脚本
|
||||
└── NEWS_FEATURE_v2.2.md # 本文档
|
||||
```
|
||||
|
||||
### 修改文件
|
||||
|
||||
```
|
||||
zjpb/
|
||||
├── config.py # 添加博查API配置
|
||||
├── models.py # News模型添加source_name/source_icon字段
|
||||
├── app.py # 添加新闻获取API路由，更新NewsAdmin
|
||||
└── templates/
|
||||
└── detail_new.html # 优化新闻展示UI
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 技术实现
|
||||
|
||||
### API集成
|
||||
|
||||
使用博查Web Search API进行新闻搜索：
|
||||
|
||||
- **接口地址**: `https://api.bocha.cn/v1/web-search`
|
||||
- **认证方式**: Bearer Token
|
||||
- **请求方法**: POST
|
||||
- **返回格式**: JSON
|
||||
|
||||
### 数据模型
|
||||
|
||||
News模型字段：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | Integer | 主键 |
|
||||
| site_id | Integer | 关联网站ID（外键） |
|
||||
| title | String(200) | 新闻标题 |
|
||||
| content | Text | 新闻内容/摘要 |
|
||||
| news_type | String(50) | 新闻类型 |
|
||||
| url | String(500) | 新闻链接 |
|
||||
| source_name | String(100) | ⭐ 来源网站名称（新增） |
|
||||
| source_icon | String(500) | ⭐ 来源网站图标（新增） |
|
||||
| published_at | DateTime | 发布时间 |
|
||||
| is_active | Boolean | 是否启用 |
|
||||
| created_at | DateTime | 创建时间 |
|
||||
| updated_at | DateTime | 更新时间 |
|
||||
|
||||
### API路由
|
||||
|
||||
**1. 单个网站获取新闻**
|
||||
|
||||
- **路径**: `/api/fetch-site-news`
|
||||
- **方法**: POST
|
||||
- **权限**: 需要登录
|
||||
- **参数**:
|
||||
```json
|
||||
{
|
||||
"site_id": 1,
|
||||
"count": 10,
|
||||
"freshness": "oneMonth"
|
||||
}
|
||||
```
|
||||
|
||||
**2. 批量获取新闻**
|
||||
|
||||
- **路径**: `/api/fetch-all-news`
|
||||
- **方法**: POST
|
||||
- **权限**: 需要登录
|
||||
- **参数**:
|
||||
```json
|
||||
{
|
||||
"count": 5,
|
||||
"freshness": "oneMonth",
|
||||
"limit": 10
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 配置选项
|
||||
|
||||
在`config.py`中的新闻相关配置：
|
||||
|
||||
```python
|
||||
# 博查 Web Search API配置
|
||||
BOCHA_API_KEY = os.environ.get('BOCHA_API_KEY')
|
||||
BOCHA_BASE_URL = os.environ.get('BOCHA_BASE_URL') or 'https://api.bocha.cn'
|
||||
BOCHA_SEARCH_ENDPOINT = '/v1/web-search'
|
||||
|
||||
# 新闻搜索配置
|
||||
NEWS_SEARCH_COUNT = 10 # 每次搜索返回的新闻数量
|
||||
NEWS_SEARCH_FRESHNESS = 'oneMonth' # 默认搜索一个月内的新闻
|
||||
NEWS_SEARCH_SUMMARY = True # 是否显示摘要
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 注意事项
|
||||
|
||||
### API配额限制
|
||||
|
||||
- 博查API根据充值金额有请求频率限制
|
||||
- 建议合理设置定期任务频率，避免过度消耗配额
|
||||
- 详情参见：[博查API定价](https://open.bocha.cn)
|
||||
|
||||
### 去重机制
|
||||
|
||||
系统会根据新闻URL自动去重，同一条新闻不会重复保存。
|
||||
|
||||
### 搜索策略
|
||||
|
||||
- 搜索关键词：`{网站名称} 最新 新闻`
|
||||
- 自动排除：网站自身域名的内容
|
||||
- 时间优先：优先显示最新发布的新闻
|
||||
|
||||
### 性能优化
|
||||
|
||||
- 批量获取时建议限制数量（`--limit 10-20`）
|
||||
- 避免短时间内频繁调用API
|
||||
- 数据库查询已优化，使用索引和去重
|
||||
|
||||
---
|
||||
|
||||
## 🐛 故障排查
|
||||
|
||||
### 1. 新闻获取失败
|
||||
|
||||
**可能原因**：
|
||||
- 博查API Key未配置或无效
|
||||
- API配额不足
|
||||
- 网络连接问题
|
||||
|
||||
**解决方法**：
|
||||
```bash
|
||||
# 检查环境变量
|
||||
python -c "import os; from dotenv import load_dotenv; load_dotenv(); print(os.getenv('BOCHA_API_KEY'))"
|
||||
|
||||
# 测试API连接
|
||||
python utils/news_searcher.py
|
||||
```
|
||||
|
||||
### 2. 数据库字段不存在
|
||||
|
||||
**错误信息**：`Unknown column 'source_name' in 'field list'`
|
||||
|
||||
**解决方法**：
|
||||
```bash
|
||||
# 运行数据库迁移
|
||||
python migrate_news_fields.py
|
||||
```
|
||||
|
||||
### 3. 详情页不显示新闻
|
||||
|
||||
**可能原因**：
|
||||
- 数据库中没有该网站的新闻记录
|
||||
- 新闻被设置为不启用（is_active=False）
|
||||
|
||||
**解决方法**：
|
||||
```bash
|
||||
# 为该网站获取新闻
|
||||
curl -X POST http://localhost:5000/api/fetch-site-news \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"site_id": YOUR_SITE_ID}'
|
||||
```
|
||||
|
||||
### 4. 定期任务不执行
|
||||
|
||||
**检查清单**：
|
||||
- [ ] Crontab配置是否正确
|
||||
- [ ] Python路径是否正确
|
||||
- [ ] 日志文件是否有写入权限
|
||||
- [ ] 查看cron日志：`grep CRON /var/log/syslog`
|
||||
|
||||
---
|
||||
|
||||
## 📈 未来改进
|
||||
|
||||
### 计划功能
|
||||
|
||||
- [ ] 后台UI按钮直接触发新闻获取
|
||||
- [ ] 新闻分类和标签支持
|
||||
- [ ] 新闻摘要AI优化
|
||||
- [ ] 新闻热度排序
|
||||
- [ ] 用户收藏新闻功能
|
||||
- [ ] 新闻RSS订阅
|
||||
|
||||
### 性能优化
|
||||
|
||||
- [ ] 使用异步任务队列（Celery）
|
||||
- [ ] 新闻缓存机制
|
||||
- [ ] 图片CDN加速
|
||||
|
||||
---
|
||||
|
||||
## 📞 技术支持
|
||||
|
||||
- **项目名称**: ZJPB - 焦提示词 | AI工具导航
|
||||
- **版本**: v2.2.0
|
||||
- **发布日期**: 2025-01-30
|
||||
- **博查API文档**: https://bocha-ai.feishu.cn/wiki/RXEOw02rFiwzGSkd9mUcqoeAnNK
|
||||
|
||||
---
|
||||
|
||||
## 📝 更新日志
|
||||
|
||||
### v2.2.0 (2025-01-30)
|
||||
|
||||
**新增**：
|
||||
- ✨ 集成博查Web Search API
|
||||
- ✨ 新闻自动搜索和存储功能
|
||||
- ✨ News模型添加source_name和source_icon字段
|
||||
- ✨ 网站详情页新闻展示优化
|
||||
- ✨ 后台新闻管理界面增强
|
||||
- ✨ 定期任务脚本（fetch_news_cron.py）
|
||||
- ✨ API路由：/api/fetch-site-news 和 /api/fetch-all-news
|
||||
|
||||
**修改**：
|
||||
- 🔧 config.py添加博查API配置
|
||||
- 🔧 NewsAdmin添加source_name字段显示
|
||||
- 🔧 detail_new.html优化新闻展示UI
|
||||
|
||||
**文档**：
|
||||
- 📖 NEWS_FEATURE_v2.2.md 功能文档
|
||||
- 📖 migrate_news_fields.py 迁移脚本文档
|
||||
|
||||
---
|
||||
|
||||
**祝您使用愉快！** 🎉
|
||||
Reference in New Issue
Block a user