# ZJPB v2.6.0 快速部署指南

**版本**: v2.6.0
**部署时间**: 2026-02-06
**重要性**: ⚠️ 高（成本优化，建议立即部署）

---

## 📋 更新内容

### 主要改进
✅ **成本优化**: API调用减少90%+，大幅降低博查API费用
✅ **安全防护**: 添加频率限制和验证码防护，防止滥用
✅ **文档整合**: 清理根目录，文档归档到docs/目录

### 技术变更
- 移除详情页自动调用博查API
- 改为用户点击按钮按需加载
- 新增频率限制（每IP每小时3次）
- 新增验证码防护机制

---

## 🚀 快速部署 (5分钟)

### 方式一：通过1Panel + Git

1. **SSH连接服务器**
   ```bash
   ssh root@server.zjpb.net
   ```

2. **进入项目目录**
   ```bash
   cd /opt/1panel/apps/zjpb
   ```

3. **拉取最新代码**
   ```bash
   git pull origin master
   ```

4. **安装新依赖**
   ```bash
   source venv/bin/activate
   pip install Flask-Limiter==3.5.0
   # 或
   pip install -r requirements.txt
   ```

5. **重启应用**
   - **方式A**: 通过1Panel Web界面
     - 登录1Panel → 找到zjpb应用 → 点击"重启"

   - **方式B**: 通过命令行
     ```bash
     supervisorctl restart zjpb
     # 或
     systemctl restart zjpb
     ```

6. **验证部署**
   - 访问任意工具详情页
   - 确认页面加载快了（不再自动调用API）
   - 点击"加载资讯"按钮，确认能正常获取新闻

---

## ✅ 部署验证清单

### 功能验证
- [ ] 详情页正常打开，速度更快
- [ ] 新闻区域显示占位提示或已有新闻
- [ ] 点击"加载资讯"按钮能正常加载
- [ ] 加载后新闻正常显示
- [ ] 连续点击4次，出现频率限制提示

### 错误检查
```bash
# 查看应用日志
tail -f logs/error.log

# 确认无报错
# 正常情况应该看到类似日志：
# "Rate limit triggered: 192.168.x.x" (频率限制触发)
```

### 性能对比
**部署前**: 打开详情页加载时间 2-3秒（调用API）
**部署后**: 打开详情页加载时间 0.5-1秒（无API调用）

---

## ⚙️ 可选配置

### 调整频率限制（可选）

编辑 `app.py:193` 附近：

```python
# 更宽松：每小时5次
is_limited, remaining, reset_time = limiter.is_rate_limited(
    client_ip,
    limit=5,              # 改为5
    window_minutes=60
)

# 更严格：每30分钟2次
is_limited, remaining, reset_time = limiter.is_rate_limited(
    client_ip,
    limit=2,              # 改为2
    window_minutes=30     # 改为30
)
```

修改后需要重启应用。

### 配置验证码（推荐）

**当前状态**: 使用简单验证（开发模式）
**生产建议**: 配置Google reCAPTCHA或hCaptcha

详见：`docs/archive/DEVELOP_v2.6.0_API_SECURITY.md`

---

## 🐛 故障排查

### 问题1: 点击按钮没反应

**检查**:
```bash
# 查看浏览器控制台是否有JavaScript错误
# 查看后端日志
tail -f logs/error.log
```

**解决**: 确认 `utils/rate_limiter.py` 文件存在

### 问题2: 提示"博查API未配置"

**检查**:
```bash
cat .env | grep BOCHA_API_KEY
```

**解决**: 确认 `.env` 中有 `BOCHA_API_KEY=xxx`

### 问题3: 导入错误 "No module named 'utils.rate_limiter'"

**解决**:
```bash
# 确认文件存在
ls utils/rate_limiter.py

# 如果不存在，手动创建或从Git拉取
git checkout utils/rate_limiter.py
```

---

## 📊 成本对比

**假设场景**: 日均1000次详情页访问

| 版本 | 自动调用 | 手动加载 | 总调用 | 日成本 | 月成本 |
|------|---------|---------|--------|--------|--------|
| v2.5 | 1000次 | 0次 | 1000次 | ¥10 | ¥300 |
| v2.6 | 0次 | ~50次 | 50次 | ¥0.5 | ¥15 |

**节省**: 每月约 ¥285 💰

---

## 🔄 回滚方案

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

```bash
cd /opt/1panel/apps/zjpb

# 回滚到v2.5
git reset --hard e71230c

# 重启应用
supervisorctl restart zjpb
```

---

## 📚 相关文档

- 完整开发文档: `docs/archive/DEVELOP_v2.6.0_API_SECURITY.md`
- 文档索引: `docs/README.md`
- 部署信息: `DEPLOY_INFO.md`

---

## 💡 下一步建议

### 立即执行
✅ 部署v2.6.0（成本优化）
✅ 验证功能正常

### 1周内执行
- [ ] 配置Redis存储（持久化频率限制数据）
- [ ] 配置生产环境验证码服务
- [ ] 监控API调用量变化

### 1个月内执行
- [ ] 添加API调用统计面板
- [ ] 优化验证码用户体验
- [ ] 实现白名单机制

---

**部署时间**: < 5分钟
**风险等级**: 低（可快速回滚）
**收益**: 成本优化90%+ 🎉

---

最后更新: 2026-02-06