zjpb.net/docs/archive/DEPLOY_v2.3.0.md

ZJPB v2.3.0 部署指南

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

---

📋 版本概述

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

✨ 核心改进

1. 专用新闻关键词字段

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

2. 严格匹配搜索策略

   • 使用双引号包裹关键词，确保完整匹配
   • 优先使用news_keywords，降级使用网站名称
   • 提高新闻相关性和准确性

3. 前台手动刷新功能

   • 详情页新增"获取最新资讯"按钮
   • 用户可主动刷新最新新闻
   • 无需后台权限，前台直接使用

---

🔧 技术变更

数据库变更

Sites表：

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

代码变更

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

---

🚀 部署步骤

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

1. 备份数据库

# 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. 拉取最新代码

# 停止应用
./manage.sh stop

# 查看当前状态
git status

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

# 拉取最新代码
git pull origin master

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

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

3. 运行数据库迁移

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

# 运行迁移脚本
python migrate_news_keywords.py

预期输出：

============================================================
开始执行数据库迁移 v2.3.0
============================================================

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

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

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

4. 重启应用

# 重启应用
./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

上传后执行：

cd /opt/1panel/apps/zjpb
source venv/bin/activate
python migrate_news_keywords.py
./manage.sh restart

---

✅ 部署验证

1. 数据库验证

-- 检查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测试

# 测试刷新新闻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、工具、助手

批量设置关键词

-- 示例：批量设置关键词
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. 后台表单没有新字段

可能原因：

• 代码未更新
• 浏览器缓存

解决方案：

# 确认代码已更新
grep -n "news_keywords" app.py

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

# 重启应用
./manage.sh restart

---

3. 刷新按钮不显示

可能原因：

• detail_new.html未更新
• 模板缓存

解决方案：

# 确认模板已更新
grep -n "refresh-news-btn" templates/detail_new.html

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

---

4. 刷新新闻失败

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

原因：BOCHA_API_KEY未配置

解决方案：

# 编辑.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. 回滚代码

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. 回滚数据库（可选）

# 删除新添加的字段（如需要）
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路径参数）

返回：

{
  "success": true,
  "message": "成功获取 3 条新资讯",
  "total_found": 5,
  "saved_count": 3
}

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

---

📈 版本对比

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

---

🔧 维护建议

定期检查关键词

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

-- 查看没有设置关键词的网站
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开发团队