# ZJPB v2.2.0 Git Patch 部署指南

## 版本信息

- **版本号**: v2.2.0
- **发布日期**: 2025-12-30
- **主要功能**: 博查新闻搜索集成

---

## 新功能概述

### 1. 博查Web Search API集成
- 自动获取网站相关新闻
- 支持手动和批量获取
- 新闻来源展示（网站名称+图标）

### 2. 智能新闻更新机制
- **每日首次访问触发更新**：用户访问网站详情页时，如果今天还没有更新过新闻，自动获取最新3条
- **历史新闻保留**：如果没有访问，保留历史新闻不会被删除
- **一周内新闻**：只获取最近一周的相关新闻
- **自动去重**：根据URL防止重复新闻

### 3. 数据库扩展
- News表新增字段：
  - `source_name`: 新闻来源网站名称
  - `source_icon`: 新闻来源网站图标URL

### 4. 用户界面优化
- 网站详情页新增"相关新闻"模块
- 新闻展示包括：标题、摘要、来源、发布时间、阅读链接
- "相似推荐"移至右侧边栏，界面更加清晰

### 5. 管理功能
- 后台新闻管理界面优化
- 支持批量获取所有网站的新闻
- 定期任务脚本 `fetch_news_cron.py`

---

## 部署前准备

### 1. 环境要求
- Python 3.8+
- MySQL 5.7+
- Git已配置
- 虚拟环境已创建

### 2. 配置检查

**必需配置**（生产服务器.env文件）：
```bash
# 博查 Web Search API配置（必需！）
BOCHA_API_KEY=your_api_key_here
BOCHA_BASE_URL=https://api.bocha.cn
```

如果没有配置BOCHA_API_KEY：
- 新闻功能不会运行
- 不会影响其他功能
- 详情页会正常显示，只是没有新闻模块

### 3. 备份数据库

在1Panel中备份数据库：
```bash
# 或者使用命令行
mysqldump -h 112.124.42.38 -u ai_nav -p ai_nav > backup_before_v2.2_$(date +%Y%m%d).sql
```

---

## 部署步骤

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

#### 1. 上传文件到服务器

需要上传2个文件到 `/opt/1panel/apps/zjpb/`：
- `v2.2.0.patch` (56KB)
- `git_patch_deploy_v2.2.sh`

**使用1Panel文件管理器**或**SCP命令**：
```bash
scp v2.2.0.patch root@your-server:/opt/1panel/apps/zjpb/
scp git_patch_deploy_v2.2.sh root@your-server:/opt/1panel/apps/zjpb/
```

#### 2. 执行部署脚本

SSH登录服务器或使用1Panel终端：
```bash
cd /opt/1panel/apps/zjpb

# 赋予执行权限
chmod +x git_patch_deploy_v2.2.sh

# 执行部署
./git_patch_deploy_v2.2.sh
```

#### 3. 脚本自动完成的操作

```
1. 停止应用
2. 检查Git状态
3. 备份未提交的修改（如有）
4. 应用v2.2.0补丁
   - 添加NewsSearcher工具类
   - 更新app.py（新闻路由+智能更新）
   - 更新models.py（News字段扩展）
   - 更新config.py（博查API配置）
   - 更新detail_new.html（新闻展示UI）
   - 添加数据库迁移脚本
   - 添加测试脚本和定期任务脚本
5. 提交到Git
6. 激活虚拟环境
7. 安装依赖
8. 运行数据库迁移（添加source_name和source_icon字段）
9. 重启应用
10. 检查状态
```

---

## 部署后验证

### 1. 前台验证

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

检查项：
- [ ] 页面正常加载
- [ ] 如果配置了BOCHA_API_KEY，首次访问会自动获取新闻
- [ ] "相关新闻"模块显示在左侧主栏
- [ ] "相似推荐"显示在右侧边栏
- [ ] 新闻显示来源名称和图标
- [ ] 点击新闻标题可以跳转到原文

### 2. 后台验证

**登录后台管理**：
```
http://your-domain.com/admin/login
```

检查项：
- [ ] 进入"新闻管理" `/admin/newsadmin/`
- [ ] 列表显示包含source_name和source_icon
- [ ] 可以搜索和过滤新闻
- [ ] 编辑新闻时可以看到新字段

### 3. 数据库验证

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

-- 应该看到新字段
-- source_name VARCHAR(100)
-- source_icon VARCHAR(500)

-- 检查现有新闻数据
SELECT id, title, source_name, source_icon
FROM news
ORDER BY created_at DESC
LIMIT 5;
```

### 4. API测试（可选）

如果配置了BOCHA_API_KEY，可以测试API：

```bash
# 在服务器上
cd /opt/1panel/apps/zjpb
source venv/bin/activate

# 运行测试脚本
python test_news_feature.py
```

### 5. 日志检查

```bash
# 查看应用日志
./manage.sh logs

# 或者查看Gunicorn日志
tail -f logs/gunicorn_error.log
```

---

## 配置博查API（重要）

### 1. 获取API Key

如果还没有博查API Key：
1. 访问 https://api.bocha.cn
2. 注册并获取API Key
3. 充值（建议至少10元，用于测试）

### 2. 配置.env文件

编辑生产服务器的.env文件：
```bash
nano /opt/1panel/apps/zjpb/.env
```

添加或更新：
```bash
# 博查 Web Search API配置
BOCHA_API_KEY=sk-your-actual-api-key-here
BOCHA_BASE_URL=https://api.bocha.cn
```

### 3. 重启应用

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

---

## 定期任务配置（可选）

如果想定期批量更新所有网站的新闻，可以配置cron任务：

### 1. 编辑crontab

```bash
crontab -e
```

### 2. 添加定时任务

```bash
# 每天凌晨2点更新前10个网站的新闻（每个网站获取3条）
0 2 * * * cd /opt/1panel/apps/zjpb && source venv/bin/activate && python fetch_news_cron.py --limit 10 --count 3 >> logs/cron_news.log 2>&1
```

### 3. 查看定期任务日志

```bash
tail -f /opt/1panel/apps/zjpb/logs/cron_news.log
```

---

## 常见问题排查

### 1. 新闻不显示

**检查项**：
- BOCHA_API_KEY是否配置正确？
- API Key是否有余额？
- 网站是否有相关新闻？
- 查看应用日志是否有错误

**测试命令**：
```bash
cd /opt/1panel/apps/zjpb
source venv/bin/activate
python test_news_feature.py
```

### 2. 数据库迁移失败

**症状**：source_name或source_icon字段不存在

**解决方案**：
```bash
cd /opt/1panel/apps/zjpb
source venv/bin/activate
python migrate_news_fields.py
```

### 3. 页面报错

**检查**：
```bash
# 查看错误日志
./manage.sh logs

# 检查进程状态
./manage.sh status

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

### 4. 补丁应用失败

**症状**：`git apply --check` 失败

**原因**：可能有未提交的本地修改冲突

**解决方案**：
```bash
# 查看冲突文件
git status

# 备份本地修改
git stash

# 重新应用补丁
git apply v2.2.0.patch

# 如需恢复本地修改
git stash pop
```

---

## 回滚方案

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

### 1. 回滚代码

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

# 回滚到上一个提交（v2.1.0）
git reset --hard HEAD~2

# 如果有stash备份，恢复它
git stash list
git stash pop

./manage.sh start
```

### 2. 回滚数据库（如需要）

```bash
# 删除新添加的字段
mysql -h 112.124.42.38 -u ai_nav -p ai_nav

ALTER TABLE news DROP COLUMN source_name;
ALTER TABLE news DROP COLUMN source_icon;
```

---

## 性能说明

### 1. 智能更新策略

- **触发条件**：用户首次访问网站详情页 + 今天还没更新过新闻
- **更新频率**：每个网站每天最多更新一次
- **查询数量**：每次获取3条新闻
- **时间范围**：最近一周内的新闻
- **API调用**：只有满足更新条件时才会调用

### 2. 对用户体验的影响

- **首次加载**：如果触发新闻更新，页面加载时间增加1-3秒
- **后续访问**：使用缓存的新闻，无额外延迟
- **错误处理**：API调用失败不影响页面正常显示
- **异步加载**：后续可优化为异步加载新闻模块

### 3. 成本估算

- 假设每天100个网站被访问，每个网站触发一次新闻更新
- 每次查询约0.01元（参考博查API定价）
- 每天成本约1元，每月约30元

---

## 版本对比

| 功能 | v2.1.0 | v2.2.0 |
|------|--------|--------|
| Prompt管理 | ✅ | ✅ |
| 标签生成 | ✅ | ✅ |
| 功能生成 | ✅ | ✅ |
| 详细介绍生成 | ✅ | ✅ |
| 新闻搜索 | ❌ | ✅ |
| 新闻展示 | ❌ | ✅ |
| 智能更新 | ❌ | ✅ |
| 新闻来源信息 | ❌ | ✅ |
| 定期任务 | ❌ | ✅ |

---

## 后续优化建议

1. **新闻模块异步加载**：使用AJAX加载新闻，不阻塞页面
2. **缓存优化**：使用Redis缓存新闻数据
3. **全文搜索**：支持在新闻内容中搜索关键词
4. **RSS订阅**：为网站新闻生成RSS feed
5. **新闻分类**：根据新闻类型自动分类
6. **新闻推荐**：基于用户行为推荐相关新闻

---

## 完整部署命令（一键复制）

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

# 检查上传的文件
ls -lh v2.2.0.patch git_patch_deploy_v2.2.sh

# 赋予执行权限
chmod +x git_patch_deploy_v2.2.sh

# 执行部署
./git_patch_deploy_v2.2.sh

# 配置API Key（如果还没配置）
nano .env
# 添加：BOCHA_API_KEY=your-key-here

# 重启应用（如果修改了.env）
./manage.sh restart

# 验证部署
./manage.sh status
git log --oneline -3
```

---

## 技术支持

如有问题，请检查：
1. 应用日志：`./manage.sh logs`
2. 数据库连接：检查.env中的DB_配置
3. API配置：检查BOCHA_API_KEY是否正确
4. 网络连接：确认服务器可以访问 api.bocha.cn

---

## 更新日志

### v2.2.0 (2025-12-30)
- 新增博查Web Search API集成
- 新增智能新闻更新机制
- News模型扩展（source_name, source_icon）
- 新增网站详情页新闻模块
- 新增定期任务脚本和测试工具
- 优化详情页布局（新闻左侧，推荐右侧）

---

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