# ZJPB v2.3.0 部署指南

**版本**: v2.3.0
**发布日期**: 2025-12-31
**核心功能**: 新闻获取准确性优化

---

## 📋 版本概述

v2.3.0版本专注于解决新闻获取准确性问题，通过引入专用新闻关键词字段和严格匹配策略，显著提升新闻相关性。

### ✨ 核心改进

1. **专用新闻关键词字段**
   - Sites表新增`news_keywords`字段
   - 支持为每个网站设置专属搜索关键词
   - 避免网站名称混淆导致的不相关新闻

2. **严格匹配搜索策略**
   - 使用双引号包裹关键词，确保完整匹配
   - 优先使用news_keywords，降级使用网站名称
   - 提高新闻相关性和准确性

3. **前台手动刷新功能**
   - 详情页新增"获取最新资讯"按钮
   - 用户可主动刷新最新新闻
   - 无需后台权限，前台直接使用

---

## 🔧 技术变更

### 数据库变更

**Sites表**：
```sql
ALTER TABLE sites
ADD COLUMN news_keywords VARCHAR(200)
COMMENT '新闻获取关键词（用于精准匹配相关新闻）'
AFTER features;
```

### 代码变更

| 文件 | 变更类型 | 说明 |
|------|---------|------|
| `models.py` | 修改 | Site模型添加news_keywords字段 |
| `migrate_news_keywords.py` | 新增 | 数据库迁移脚本 |
| `app.py` | 修改 | • 后台表单配置<br>• search_site_news调用<br>• 新API路由 |
| `utils/news_searcher.py` | 修改 | 支持news_keywords参数 |
| `templates/detail_new.html` | 修改 | 刷新按钮和JavaScript |

---

## 🚀 部署步骤

### 方法一：Git Pull 部署（推荐）

#### 1. 备份数据库

```bash
# SSH登录服务器
cd /opt/1panel/apps/zjpb

# 备份数据库
mysqldump -h localhost -u ai_nav -p ai_nav > backup_before_v2.3_$(date +%Y%m%d_%H%M%S).sql
```

#### 2. 拉取最新代码

```bash
# 停止应用
./manage.sh stop

# 查看当前状态
git status

# 如有本地修改，先暂存
git stash

# 拉取最新代码
git pull origin master

# 如有stash，可选择恢复
# git stash pop

# 查看当前版本
git log --oneline -3
```

#### 3. 运行数据库迁移

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

# 运行迁移脚本
python migrate_news_keywords.py
```

**预期输出**：
```
============================================================
开始执行数据库迁移 v2.3.0
============================================================

1. 添加 news_keywords 字段...
>>> news_keywords 字段添加成功

2. 为现有网站设置默认关键词（使用网站名称）...
>>> 已更新 X 个网站的默认关键词

============================================================
>>> 数据库迁移完成！
============================================================
```

#### 4. 重启应用

```bash
# 重启应用
./manage.sh restart

# 检查状态
./manage.sh status

# 查看日志（可选）
./manage.sh logs
```

---

### 方法二：手动文件上传（备用）

如果Git pull失败，可以手动上传修改的文件：

#### 需要上传的文件

1. `models.py`
2. `migrate_news_keywords.py` (新文件)
3. `app.py`
4. `utils/news_searcher.py`
5. `templates/detail_new.html`

**上传后执行**：
```bash
cd /opt/1panel/apps/zjpb
source venv/bin/activate
python migrate_news_keywords.py
./manage.sh restart
```

---

## ✅ 部署验证

### 1. 数据库验证

```sql
-- 检查sites表结构
DESCRIBE sites;

-- 应该看到新字段
-- news_keywords | varchar(200) | YES

-- 检查现有数据
SELECT id, name, news_keywords
FROM sites
LIMIT 5;
```

### 2. 后台验证

访问后台管理：http://your-domain.com/admin/login

**检查项**：
- [ ] 进入"网站管理"
- [ ] 点击"编辑"任意网站
- [ ] 查看是否有"新闻关键词"输入框
- [ ] 输入测试关键词，保存成功

### 3. 前台验证

访问任意网站详情页：http://your-domain.com/site/xxxxxxxx

**检查项**：
- [ ] 页面正常加载
- [ ] 滚动到"相关新闻"模块
- [ ] 查看是否有"获取最新资讯"按钮
- [ ] 点击按钮测试刷新功能（需配置BOCHA_API_KEY）

### 4. API测试

```bash
# 测试刷新新闻API
curl -X POST http://your-domain.com/api/refresh-site-news/12345678 \
  -H "Content-Type: application/json"

# 预期返回
{
  "success": true,
  "message": "成功获取 X 条新资讯",
  "total_found": X,
  "saved_count": X
}
```

---

## 📝 使用指南

### 后台管理员

#### 设置新闻关键词

1. 登录后台：`/admin/login`
2. 进入"网站管理" → 选择要编辑的网站
3. 找到"新闻关键词"字段
4. 输入精准的搜索关键词

**关键词设置建议**：
- ✅ **推荐**：使用产品官方全称或核心品牌词
  - 示例：`ChatGPT`、`GitHub Copilot`、`Midjourney`
- ✅ **多个关键词**：可以使用空格分隔（会被当作一个整体匹配）
  - 示例：`Claude AI`、`Google Gemini`
- ❌ **避免**：过于宽泛的词
  - 错误示例：`AI`、`工具`、`助手`

#### 批量设置关键词

```sql
-- 示例：批量设置关键词
UPDATE sites SET news_keywords = 'ChatGPT' WHERE name = 'ChatGPT';
UPDATE sites SET news_keywords = 'GitHub Copilot' WHERE name = 'GitHub Copilot';
UPDATE sites SET news_keywords = 'Claude AI' WHERE name = 'Claude';
```

### 前台用户

#### 手动刷新新闻

1. 访问网站详情页
2. 滚动到"相关新闻"模块
3. 点击"获取最新资讯"按钮
4. 等待1-2秒，页面自动刷新

**注意**：
- 刷新功能需要配置BOCHA_API_KEY
- 每次刷新获取最新5条一周内的新闻
- 自动去重，不会重复保存

---

## 🔍 问题排查

### 1. 迁移脚本报错

**错误**：`news_keywords字段已存在`

**解决**：正常现象，脚本会自动跳过已存在的字段

---

### 2. 后台表单没有新字段

**可能原因**：
- 代码未更新
- 浏览器缓存

**解决方案**：
```bash
# 确认代码已更新
grep -n "news_keywords" app.py

# 清除浏览器缓存，强制刷新（Ctrl + F5）

# 重启应用
./manage.sh restart
```

---

### 3. 刷新按钮不显示

**可能原因**：
- detail_new.html未更新
- 模板缓存

**解决方案**：
```bash
# 确认模板已更新
grep -n "refresh-news-btn" templates/detail_new.html

# 清除Flask缓存，重启应用
./manage.sh restart
```

---

### 4. 刷新新闻失败

**错误信息**：`新闻功能未启用`

**原因**：BOCHA_API_KEY未配置

**解决方案**：
```bash
# 编辑.env文件
nano /opt/1panel/apps/zjpb/.env

# 添加或确认以下配置
BOCHA_API_KEY=sk-your-api-key-here
BOCHA_BASE_URL=https://api.bocha.cn

# 重启应用
./manage.sh restart
```

---

## 🔄 回滚方案

如果部署后出现问题，可以快速回滚：

### 1. 回滚代码

```bash
cd /opt/1panel/apps/zjpb
./manage.sh stop

# 查看提交历史
git log --oneline -5

# 回滚到v2.2.0（假设是前一个提交）
git reset --hard <v2.2.0的commit-id>

./manage.sh start
```

### 2. 回滚数据库（可选）

```bash
# 删除新添加的字段（如需要）
mysql -h localhost -u ai_nav -p ai_nav

ALTER TABLE sites DROP COLUMN news_keywords;
```

**注意**：删除字段会丢失已设置的关键词数据，谨慎操作！

---

## 📊 性能影响

### 数据库

- **新增字段**：1个VARCHAR(200)字段
- **存储增长**：约200字节/网站
- **查询性能**：无影响（字段不参与索引查询）

### 应用性能

- **后台表单**：无明显影响
- **前台刷新**：
  - API调用耗时：1-3秒（取决于博查API响应）
  - 不影响页面正常浏览
  - 仅在用户主动点击时触发

---

## 🆕 新增API端点

### POST /api/refresh-site-news/<site_code>

手动刷新指定网站的新闻

**参数**：
- `site_code`：网站编码（URL路径参数）

**返回**：
```json
{
  "success": true,
  "message": "成功获取 3 条新资讯",
  "total_found": 5,
  "saved_count": 3
}
```

**权限**：无需登录，前台可用

---

## 📈 版本对比

| 功能 | v2.2.0 | v2.3.0 |
|------|--------|--------|
| 新闻搜索 | ✅ | ✅ |
| 搜索关键词 | 仅网站名称 | 专用关键词优先 |
| 匹配策略 | 普通匹配 | 严格匹配（双引号） |
| 手动刷新 | ❌ | ✅ 前台按钮 |
| 关键词管理 | ❌ | ✅ 后台配置 |

---

## 🔧 维护建议

### 定期检查关键词

建议定期检查新闻获取效果，优化关键词设置：

```sql
-- 查看没有设置关键词的网站
SELECT id, name, news_keywords
FROM sites
WHERE news_keywords IS NULL OR news_keywords = '';

-- 查看新闻获取较少的网站
SELECT s.name, s.news_keywords, COUNT(n.id) as news_count
FROM sites s
LEFT JOIN news n ON s.id = n.site_id
GROUP BY s.id
HAVING news_count < 3
ORDER BY news_count;
```

### 关键词优化流程

1. 识别新闻数量少的网站
2. 访问该网站，了解官方品牌名称
3. 在后台设置更精准的关键词
4. 点击前台刷新按钮测试效果
5. 根据结果调整关键词

---

## 📞 技术支持

**项目**: ZJPB - 焦提示词 | AI工具导航
**版本**: v2.3.0
**更新日期**: 2025-12-31

**常见问题**：
1. 查看应用日志：`./manage.sh logs`
2. 检查数据库连接：确认.env中的DB_配置
3. 验证API配置：确认BOCHA_API_KEY正确

---

## 🎯 后续优化建议

v2.3.0之后可以考虑的优化方向：

1. **智能关键词推荐**
   - 根据网站URL自动提取品牌词
   - AI分析网站内容推荐关键词

2. **新闻质量评分**
   - 使用AI评估新闻相关性
   - 自动过滤低质量新闻

3. **批量关键词管理**
   - 后台批量设置关键词
   - 导入导出关键词配置

4. **新闻效果统计**
   - 统计每个网站的新闻点击率
   - 根据数据优化关键词策略

---

## 📝 更新日志

### v2.3.0 (2025-12-31)

**新增**：
- ✨ Sites表添加news_keywords字段
- ✨ 后台管理支持设置新闻关键词
- ✨ 详情页新增"获取最新资讯"按钮
- ✨ 新API端点：`/api/refresh-site-news/<code>`

**优化**：
- 🎯 新闻搜索使用专用关键词（优先级高于网站名称）
- 🎯 严格匹配策略（双引号包裹关键词）
- 🎯 所有search_site_news调用传递news_keywords参数

**修复**：
- 🐛 解决网站名称相似导致的新闻混淆问题
- 🐛 提高新闻相关性和准确性

---

**部署文档版本**: v1.0
**最后更新**: 2025-12-31
**维护者**: ZJPB开发团队