zjpb.net/DEPLOY_v2.2_CHECKLIST.md

# v2.2.0 部署检查清单

## 部署前准备

### 1. 本地文件准备
- [x] v2.2.0.patch (56KB) - 已生成
- [x] git_patch_deploy_v2.2.sh - 已创建
- [x] DEPLOY_v2.2.0.md - 完整部署文档
- [x] migrate_news_fields.py - 数据库迁移脚本

### 2. 备份（重要！）
- [ ] 生产数据库已备份
  ```bash
  # 在1Panel中备份或执行
  mysqldump -h 112.124.42.38 -u ai_nav -p ai_nav > backup_v2.2_$(date +%Y%m%d).sql
  ```
- [ ] 代码已备份（Git会自动保存）

### 3. 环境检查
- [ ] 服务器可以访问 api.bocha.cn
- [ ] Python 3.8+ 已安装
- [ ] 虚拟环境已创建
- [ ] Git已配置

---

## 部署步骤

### 步骤1：上传文件
上传以下2个文件到 `/opt/1panel/apps/zjpb/`：
- [ ] v2.2.0.patch
- [ ] 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：执行部署
```bash
cd /opt/1panel/apps/zjpb
chmod +x git_patch_deploy_v2.2.sh
./git_patch_deploy_v2.2.sh
```

### 步骤3：配置API Key
编辑.env文件，添加博查API配置：
```bash
nano /opt/1panel/apps/zjpb/.env
```

添加：
```bash
BOCHA_API_KEY=sk-76d0236a50d445ae92e75b634ed5313c
BOCHA_BASE_URL=https://api.bocha.cn
```

### 步骤4：重启应用
```bash
cd /opt/1panel/apps/zjpb
./manage.sh restart
```

---

## 部署验证

### 前台验证
- [ ] 访问首页正常
- [ ] 访问网站详情页正常
- [ ] "相关新闻"模块显示（首次访问会触发获取）
- [ ] 新闻可以点击查看原文
- [ ] "相似推荐"在右侧边栏显示

### 后台验证
- [ ] 登录后台成功 `/admin/login`
- [ ] 进入"新闻管理" `/admin/newsadmin/`
- [ ] 可以看到新闻列表（如果已有新闻）
- [ ] 新闻列表显示source_name和source_icon

### 数据库验证
```sql
-- 检查news表新字段
DESCRIBE news;
-- 应该看到：
-- source_name VARCHAR(100)
-- source_icon VARCHAR(500)
```

### 功能测试
- [ ] 访问一个网站详情页，检查是否自动获取新闻
- [ ] 刷新页面，新闻应该不会重复获取（使用缓存）
- [ ] 第二天首次访问，应该会更新新闻

---

## 部署后检查

### 日志检查
```bash
cd /opt/1panel/apps/zjpb
./manage.sh logs
```

检查是否有错误信息：
- [ ] 没有Python异常
- [ ] 没有数据库错误
- [ ] 没有API调用错误

### Git状态
```bash
git log --oneline -3
```

应该看到v2.2.0的提交：
- [ ] release: v2.2.0 相关的提交记录

### 应用状态
```bash
./manage.sh status
```

- [ ] zjpb 正在运行
- [ ] 进程PID正常

---

## 问题排查

### 1. 新闻不显示
**可能原因**：
- BOCHA_API_KEY未配置或配置错误
- API余额不足
- 网站没有相关新闻

**排查步骤**：
```bash
# 测试API配置
cd /opt/1panel/apps/zjpb
source venv/bin/activate
python test_news_feature.py

# 检查环境变量
cat .env | grep BOCHA

# 查看日志
./manage.sh logs | grep -i "news\|bocha"
```

### 2. 数据库迁移失败
**症状**：字段不存在错误

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

### 3. 补丁应用失败
**症状**：git apply报错

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

# 备份修改
git stash

# 重新应用
git apply v2.2.0.patch
```

---

## 回滚方案（如需要）

### 快速回滚
```bash
cd /opt/1panel/apps/zjpb
./manage.sh stop

# 回滚到v2.1.0
git reset --hard HEAD~2

# 重启
./manage.sh start
```

### 恢复数据库（可选）
```bash
mysql -h 112.124.42.38 -u ai_nav -p ai_nav < backup_v2.2_YYYYMMDD.sql
```

---

## 完成标记

部署完成后，确认以下所有项：
- [ ] 补丁应用成功
- [ ] 数据库迁移成功
- [ ] 应用启动正常
- [ ] 前台功能正常
- [ ] 后台功能正常
- [ ] 新闻功能测试通过
- [ ] 日志无错误
- [ ] Git提交记录正确

---

## 一键部署命令（完整版）

```bash
# ============================================
# v2.2.0 完整部署命令
# ============================================

# 1. 进入项目目录
cd /opt/1panel/apps/zjpb

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

# 3. 执行部署
chmod +x git_patch_deploy_v2.2.sh
./git_patch_deploy_v2.2.sh

# 4. 配置API Key（如果.env中还没有）
nano .env
# 添加以下两行：
# BOCHA_API_KEY=sk-76d0236a50d445ae92e75b634ed5313c
# BOCHA_BASE_URL=https://api.bocha.cn

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

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

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

echo "部署完成！请访问网站测试功能"
```

---

## 预期结果

执行部署脚本后，应该看到类似输出：

```
================================
ZJPB v2.2 Git Patch 部署
================================

当前目录: /opt/1panel/apps/zjpb

1. 停止应用...
2. 检查Git状态...
3. 备份当前修改（如有）...
4. 应用v2.2.0补丁...
   >>> 补丁应用成功
5. 提交更改到Git...
6. 激活虚拟环境...
7. 检查依赖...
8. 运行数据库迁移...
正在创建 source_name 和 source_icon 字段...
>>> 数据库迁移成功
9. 重启应用...
10. 检查应用状态...
zjpb 正在运行 (PID: xxxx)

================================
>>> 部署完成！
================================

Git提交历史：
xxxxxxx release: v2.2.0 - 博查新闻搜索功能
```

---

## 时间估算

- 上传文件：1-2分钟
- 执行部署：3-5分钟
- 配置验证：2-3分钟
- **总计**：约10分钟

---

**检查清单版本**: v1.0
**创建日期**: 2025-12-30
**适用版本**: ZJPB v2.2.0