jowelin/zjpb.net
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: v2.6.0 - API安全优化和文档整合

Browse Source 
## 核心优化
- 移除详情页自动调用博查API的逻辑，改为按需加载
- 添加基于IP的频率限制（每小时3次）
- 实现验证码防护机制（超过阈值后要求验证）
- 新增频率限制工具类 utils/rate_limiter.py

## 成本控制
- API调用减少约90%+（只在用户点击时调用）
- 防止恶意滥用和攻击
- 可配置的频率限制和验证码策略

## 文档整合
- 创建 docs/ 目录结构
- 归档历史版本文档到 docs/archive/
- 移动部署文档到 docs/deployment/
- 添加文档索引 docs/README.md

## 技术变更
- 新增依赖: Flask-Limiter==3.5.0
- 修改: app.py (移除自动调用，新增API端点)
- 修改: templates/detail_new.html (按需加载UI)
- 新增: utils/rate_limiter.py (频率限制和验证码)
- 新增: docs/archive/DEVELOP_v2.6.0_API_SECURITY.md

## 部署说明
1. pip install Flask-Limiter==3.5.0
2. 重启应用
3. 无需数据库迁移

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Jowe
2026-02-06 15:54:13 +08:00
parent c1a06ad684
commit 939717fa57
27 changed files with 1670 additions and 140 deletions
Download Patch File Download Diff File Expand all files Collapse all files

132
docs/archive/DEPLOY_CHECKLIST.md Normal file
View File

@@ -0,0 +1,132 @@
# 📦 1Panel部署打包清单
部署前请确保以下文件都已准备好：
## ✅ 必需文件
### 应用文件
- [x] app.py - 主应用文件
- [x] wsgi.py - WSGI入口（生产环境）
- [x] config.py - 配置文件
- [x] models.py - 数据模型
- [x] init_db.py - 数据库初始化脚本
- [x] requirements.txt - Python依赖列表
### 配置文件
- [x] gunicorn_config.py - Gunicorn配置
- [x] .env.example - 环境变量模板
- [ ] .env - 生产环境变量（需在服务器上创建）
### 部署脚本
- [x] deploy.sh - 一键部署脚本
- [x] manage.sh - 应用管理脚本
### 文档
- [x] DEPLOYMENT.md - 完整部署文档
- [x] QUICK_DEPLOY.md - 快速部署指南
- [x] README.md - 项目说明
### 目录结构
```
zjpb/
├── static/ # 静态文件
│ ├── css/
│ ├── js/
│ └── uploads/ # 上传文件目录
├── templates/ # 模板文件
│ ├── admin/
│ └── *.html
├── utils/ # 工具类
│ ├── website_fetcher.py
│ ├── tag_generator.py
│ └── bookmark_parser.py
├── migrations/ # 数据库迁移脚本
├── logs/ # 日志目录（自动创建）
└── venv/ # 虚拟环境（服务器上创建）
```
## 🚫 排除文件（不要上传到服务器）
- `__pycache__/` - Python缓存
- `*.pyc` - 编译的Python文件
- `.git/` - Git仓库
- `.env` - 本地环境变量
- `venv/` `env/` - 虚拟环境
- `test_*.py` - 测试文件
- `*.log` - 日志文件
- `logs/` - 日志目录
- `static/uploads/*` - 上传的文件
## 📋 部署前检查清单
### 本地准备
- [ ] 更新 requirements.txt
- [ ] 测试应用运行正常
- [ ] 准备 .env.example 模板
- [ ] 压缩项目文件
### 服务器准备
- [ ] 1Panel已安装
- [ ] MySQL数据库已创建
- [ ] 域名已解析（可选）
- [ ] SSH访问权限
### 部署步骤
- [ ] 上传项目文件到服务器
- [ ] 解压并设置目录权限
- [ ] 执行 deploy.sh 脚本
- [ ] 配置 .env 文件
- [ ] 初始化数据库
- [ ] 在1Panel中创建网站（反向代理）
- [ ] 启动应用
- [ ] 配置SSL证书（可选）
### 部署后验证
- [ ] 前台页面访问正常
- [ ] 后台登录成功
- [ ] 修改默认管理员密码
- [ ] 测试网站添加功能
- [ ] 测试标签创建功能
- [ ] 测试图片上传功能
## 🔐 安全检查
- [ ] 修改默认管理员密码
- [ ] 设置强密码的 SECRET_KEY
- [ ] 配置 .env 权限（chmod 600）
- [ ] 启用 SSL/HTTPS
- [ ] 配置防火墙规则
- [ ] 定期备份数据库
## 📝 压缩命令
Windows PowerShell:
```powershell
Compress-Archive -Path * -DestinationPath zjpb.zip -Force
```
Linux/Mac:
```bash
zip -r zjpb.zip . -x "*.pyc" "*__pycache__*" "*.git*" ".env" "venv/*" "test_*.py" "logs/*"
```
## 🎯 快速部署（服务器上）
```bash
# 1. 上传并解压
cd /www/wwwroot/zjpb
unzip zjpb.zip
# 2. 一键部署
chmod +x deploy.sh
./deploy.sh
# 3. 配置环境变量
nano .env
# 4. 启动应用
chmod +x manage.sh
./manage.sh start
```
详细步骤请参考：`DEPLOYMENT.md`

255
docs/archive/DEPLOY_CHECKLIST_v2.3.md Normal file
View File

@@ -0,0 +1,255 @@
# ZJPB v2.3.0 部署清单
**当前状态**: ✅ 代码已提交到本地Git，等待推送
---
## 📋 本地准备完成
✅ **代码修改**：
- models.py - Site模型添加news_keywords字段
- app.py - 后台表单、API路由、搜索逻辑
- utils/news_searcher.py - 严格匹配搜索
- templates/detail_new.html - 刷新按钮和UI
✅ **新增文件**：
- migrate_news_keywords.py - 数据库迁移脚本
- DEPLOY_v2.3.0.md - 完整部署文档
- DEPLOY_v2.3_QUICK.md - 快速部署指南
✅ **本地测试**：
- ✅ 数据库迁移成功（4个网站已设置默认关键词）
- ✅ Flask服务运行正常
- ✅ 后台管理可访问
✅ **Git提交**：
- Commit: `fdde699` - feat: v2.3.0 - 新闻获取准确性优化
- Tag: `v2.3.0` - Release v2.3.0: 新闻获取准确性优化
---
## 🚀 下一步操作（需要你执行）
### 第1步：推送代码到远程仓库
```bash
# 在本地项目目录执行
cd D:\315mac\Code\zjpb
# 推送代码（需要输入Git认证）
git push origin master
# 推送标签
git push origin v2.3.0
```
### 第2步：SSH登录服务器部署
```bash
# SSH登录服务器
ssh root@your-server
# 进入项目目录
cd /opt/1panel/apps/zjpb
# 停止应用
./manage.sh stop
# 拉取最新代码
git pull origin master
# 查看当前版本（应该看到fdde699）
git log --oneline -3
# 激活虚拟环境
source venv/bin/activate
# 运行数据库迁移
python migrate_news_keywords.py
# 重启应用
./manage.sh restart
# 检查状态
./manage.sh status
# 查看日志
./manage.sh logs
```
### 第3步：验证部署
#### 后台验证
```
1. 访问：http://zjpb.net/admin/login
2. 进入：网站管理
3. 编辑任意网站
4. 检查：是否有"新闻关键词"字段
```
#### 前台验证
```
1. 访问任意网站详情页
2. 滚动到"相关新闻"模块
3. 检查：是否有"获取最新资讯"按钮
4. 点击测试刷新功能
```
---
## 📊 部署变更摘要
### 数据库变更
```sql
ALTER TABLE sites
ADD COLUMN news_keywords VARCHAR(200)
COMMENT '新闻获取关键词（用于精准匹配相关新闻）'
AFTER features;
```
**影响**：
- 新增1个字段
- 约200字节/网站
- 无性能影响
### 代码变更
| 文件 | 行数变化 | 说明 |
|------|---------|------|
| models.py | +2 | 添加news_keywords字段定义 |
| app.py | +81 | 后台配置+新API路由 |
| utils/news_searcher.py | +16 | 支持关键词参数 |
| templates/detail_new.html | +125 | 刷新按钮+CSS+JS |
| migrate_news_keywords.py | +114 | 新建迁移脚本 |
**总计**：7个文件，+1009行，-8行
### API变更
**新增**：
- `POST /api/refresh-site-news/<site_code>` - 前台刷新新闻
**修改**：
- `search_site_news()` - 新增news_keywords参数
---
## ⚠️ 重要提示
### 1. 备份数据库
部署前务必备份：
```bash
mysqldump -h localhost -u ai_nav -p ai_nav > backup_v2.3_$(date +%Y%m%d).sql
```
### 2. BOCHA_API_KEY配置
确认服务器`.env`文件包含：
```bash
BOCHA_API_KEY=sk-76d0236a50d445ae92e75b634ed5313c
BOCHA_BASE_URL=https://api.bocha.cn
```
### 3. 迁移脚本幂等性
迁移脚本可以重复执行，会自动跳过已存在的字段。
---
## 🔍 常见问题
### Q1: Git拉取后没有新文件？
```bash
# 检查当前commit
git log --oneline -1
# 应该显示：fdde699 feat: v2.3.0 - 新闻获取准确性优化
# 如果不是，强制拉取
git fetch origin
git reset --hard origin/master
```
### Q2: 迁移脚本找不到？
```bash
# 确认文件存在
ls -la migrate_news_keywords.py
# 如果不存在，检查git状态
git status
# 拉取特定文件
git checkout origin/master -- migrate_news_keywords.py
```
### Q3: 后台表单没有新字段？
```bash
# 重启应用清除缓存
./manage.sh restart
# 检查代码是否更新
grep -n "news_keywords" app.py
# 应该看到：1007: 'news_keywords': '新闻关键词',
```
---
## 📈 性能监控
部署后建议监控：
1. **应用启动时间**：应在2-3秒内
2. **数据库查询性能**：无明显变化
3. **新闻刷新响应时间**：1-3秒（取决于博查API）
4. **错误日志**：关注news相关错误
```bash
# 监控日志
tail -f logs/gunicorn_error.log | grep -i "news\|error"
```
---
## ✅ 部署完成检查清单
**代码部署**：
- [ ] Git push成功
- [ ] 服务器Git pull成功
- [ ] 当前commit是fdde699
**数据库迁移**：
- [ ] migrate_news_keywords.py执行成功
- [ ] sites表有news_keywords字段
- [ ] 现有网站已设置默认关键词
**应用运行**：
- [ ] manage.sh status显示运行中
- [ ] 无错误日志
- [ ] 前后台访问正常
**功能验证**：
- [ ] 后台可编辑新闻关键词
- [ ] 前台显示刷新按钮
- [ ] 刷新功能正常工作
---
## 📞 技术支持
如遇问题：
1. **查看日志**：`./manage.sh logs`
2. **检查文档**：`DEPLOY_v2.3.0.md`（完整版）
3. **快速参考**：`DEPLOY_v2.3_QUICK.md`（精简版）
---
**清单版本**: v1.0
**创建时间**: 2025-12-31
**预计部署时间**: 5-10分钟

457
docs/archive/DEPLOY_v2.2.0.md Normal file
View File

@@ -0,0 +1,457 @@
# 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开发团队

298
docs/archive/DEPLOY_v2.2_CHECKLIST.md Normal file
View File

@@ -0,0 +1,298 @@
# 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

201
docs/archive/DEPLOY_v2.2_QUICK.md Normal file
View File

@@ -0,0 +1,201 @@
# ZJPB v2.2.0 部署操作指南
## 版本信息
- **版本**: v2.2.0
- **发布日期**: 2025-12-30
- **补丁大小**: 56KB
- **部署时间**: 约10分钟
---
## 核心功能
### 博查新闻搜索集成
✅ 自动获取网站相关新闻（博查Web Search API）
✅ 智能更新：每日首次访问触发更新
✅ 每个网站获取3条一周内新闻
✅ 新闻来源展示（名称+图标）
✅ 自动去重防止重复
### 数据库扩展
✅ News表新增 `source_name` 字段
✅ News表新增 `source_icon` 字段
### 界面优化
✅ 新闻模块在左侧主栏
✅ 相似推荐在右侧边栏
---
## 快速部署（3步）
### 第1步：上传文件到服务器
上传以下2个文件到 `/opt/1panel/apps/zjpb/`：
```
v2.2.0.patch
git_patch_deploy_v2.2.sh
```
### 第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` 文件，添加：
```bash
BOCHA_API_KEY=sk-76d0236a50d445ae92e75b634ed5313c
BOCHA_BASE_URL=https://api.bocha.cn
```
然后重启：
```bash
./manage.sh restart
```
---
## 验证部署
### ✓ 前台测试
1. 访问任意网站详情页
2. 检查"相关新闻"模块是否显示
3. 新闻应该显示来源网站名称和图标
4. 点击新闻标题可跳转到原文
### ✓ 后台测试
1. 登录 `/admin/login`
2. 进入"新闻管理" `/admin/newsadmin/`
3. 查看新闻列表是否正常显示
### ✓ 功能测试
```bash
cd /opt/1panel/apps/zjpb
source venv/bin/activate
python test_news_feature.py
```
---
## 关键文件
### 本地准备好的文件
```
D:\315mac\Code\zjpb\
├── v2.2.0.patch (56KB) 补丁文件
├── git_patch_deploy_v2.2.sh 部署脚本
├── DEPLOY_v2.2.0.md 完整部署文档
├── DEPLOY_v2.2_CHECKLIST.md 检查清单
├── migrate_news_fields.py 数据库迁移脚本
├── test_news_feature.py 测试脚本
└── fetch_news_cron.py 定期任务脚本
```
### 服务器需要的文件（只需2个）
```
v2.2.0.patch
git_patch_deploy_v2.2.sh
```
---
## Git提交历史
v2.2.0包含以下3个提交：
```
2e9f634 docs: 添加v2.2.0部署文档和脚本
495248b feat: v2.2.0 智能新闻更新和布局优化
d7d21e1 release: v2.2.0 - 博查新闻搜索功能
```
---
## 部署脚本自动完成的操作
```
1. 停止应用
2. 检查Git状态
3. 备份未提交的修改
4. 应用v2.2.0补丁
- utils/news_searcher.py (新增)
- app.py (更新)
- models.py (更新)
- config.py (更新)
- templates/detail_new.html (更新)
- migrate_news_fields.py (新增)
- test_news_feature.py (新增)
- fetch_news_cron.py (新增)
- NEWS_FEATURE_v2.2.md (新增)
5. 提交到Git
6. 激活虚拟环境
7. 安装依赖
8. 运行数据库迁移
9. 重启应用
10. 检查状态
```
---
## 回滚方案（如需要）
```bash
cd /opt/1panel/apps/zjpb
./manage.sh stop
git reset --hard HEAD~3 # 回滚到v2.1.0
./manage.sh start
```
---
## 常见问题
### Q1: 新闻不显示？
**A**: 检查 `.env` 中 `BOCHA_API_KEY` 是否配置正确
### Q2: 补丁应用失败？
**A**: 备份本地修改后重试
```bash
git stash
git apply v2.2.0.patch
```
### Q3: 数据库迁移失败？
**A**: 手动运行迁移脚本
```bash
python migrate_news_fields.py
```
---
## 成本估算
假设每天100个网站被访问：
- 每次API调用约 0.01元
- 每天成本约 1元
- 每月成本约 30元
---
## 下一步
部署完成后：
1. 访问网站测试功能
2. 查看应用日志确认无错误
3. 监控API调用情况
4. 根据需要调整新闻获取数量和时间范围
---
## 技术支持文档
- **完整文档**: `DEPLOY_v2.2.0.md`
- **检查清单**: `DEPLOY_v2.2_CHECKLIST.md`
- **功能文档**: `NEWS_FEATURE_v2.2.md`
---
**创建时间**: 2025-12-30 22:32
**准备就绪**: ✅
**可以开始部署**: ✅

496
docs/archive/DEPLOY_v2.3.0.md Normal file
View File

@@ -0,0 +1,496 @@
# 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开发团队

175
docs/archive/DEPLOY_v2.3_QUICK.md Normal file
View File

@@ -0,0 +1,175 @@
# ZJPB v2.3.0 快速部署指南
> 3步完成部署，5分钟上线
---
## 📦 版本信息
- **版本**: v2.3.0
- **日期**: 2025-12-31
- **核心**: 新闻准确性优化
---
## ⚡ 快速部署（3步）
### 第1步：拉取代码
```bash
cd /opt/1panel/apps/zjpb
./manage.sh stop
git pull origin master
```
### 第2步：数据库迁移
```bash
source venv/bin/activate
python migrate_news_keywords.py
```
### 第3步：重启应用
```bash
./manage.sh restart
./manage.sh status
```
✅ **部署完成！**
---
## ✅ 快速验证
### 1. 后台验证（1分钟）
```
1. 访问：http://your-domain.com/admin/login
2. 进入：网站管理 → 编辑任意网站
3. 检查：是否有"新闻关键词"字段
```
### 2. 前台验证（1分钟）
```
1. 访问：http://your-domain.com/site/xxxxxxxx
2. 滚动：到"相关新闻"模块
3. 检查：是否有"获取最新资讯"按钮
```
---
## 🎯 核心功能
### 1. 新闻关键词设置
**后台操作**：
```
网站管理 → 编辑 → 新闻关键词 → 输入"ChatGPT" → 保存
```
**效果**：
- 搜索更精准
- 避免名称混淆
- 提高相关性
### 2. 前台手动刷新
**用户操作**：
```
详情页 → 相关新闻 → 点击"获取最新资讯" → 等待刷新
```
**效果**：
- 获取最新5条新闻
- 自动去重
- 1-2秒完成
---
## 🔧 关键词设置技巧
### 推荐设置
| 网站名称 | 推荐关键词 | 说明 |
|---------|-----------|------|
| ChatGPT | `ChatGPT` | 官方品牌名 |
| GitHub Copilot | `GitHub Copilot` | 完整产品名 |
| Claude | `Claude AI` | 添加AI避免混淆 |
| 文心一言 | `文心一言` | 中文全称 |
### 避免设置
❌ `AI`、`工具`、`助手` - 过于宽泛
❌ `聊天机器人` - 不够精准
❌ `GPT` - 会匹配所有GPT相关
---
## 🐛 问题速查
### 问题1：后台没有新字段
```bash
# 检查代码
grep "news_keywords" app.py
# 清缓存重启
./manage.sh restart
```
### 问题2：刷新按钮不显示
```bash
# 检查模板
grep "refresh-news-btn" templates/detail_new.html
# 强制刷新浏览器（Ctrl + F5）
```
### 问题3：刷新失败
```bash
# 检查API配置
grep "BOCHA_API_KEY" .env
# 如未配置，添加：
echo "BOCHA_API_KEY=sk-your-key" >> .env
./manage.sh restart
```
---
## 📊 变更文件
| 文件 | 说明 |
|------|------|
| `models.py` | 添加字段 |
| `migrate_news_keywords.py` | 迁移脚本 |
| `app.py` | 后台+API |
| `utils/news_searcher.py` | 搜索逻辑 |
| `templates/detail_new.html` | 刷新按钮 |
---
## 🔄 回滚（如需要）
```bash
cd /opt/1panel/apps/zjpb
./manage.sh stop
git reset --hard HEAD~1 # 回到上一版本
./manage.sh start
```
---
## 📚 完整文档
详细信息请查看：`DEPLOY_v2.3.0.md`
---
**快速指南版本**: v1.0
**部署时间**: 约5分钟
**难度**: ⭐ 简单

375
docs/archive/DEPLOY_v2.4.0.md Normal file
View File

@@ -0,0 +1,375 @@
# ZJPB v2.4.0 部署指南 - SEO优化版本
## 版本说明
**版本号**: v2.4.0
**发布日期**: 2026-01-03
**主题**: SEO全面优化
**向下兼容**: 是
---
## 📋 版本更新内容
### 1. 自动化SEO基础设施
#### 1.1 Sitemap.xml 自动生成
- **路由**: `/sitemap.xml`
- **功能**: 动态生成符合搜索引擎标准的sitemap
- **包含内容**:
- 首页 (优先级: 1.0, 更新频率: daily)
- 所有工具详情页 (优先级: 0.8, 更新频率: weekly)
- 所有标签页 (优先级: 0.6, 更新频率: weekly)
- **特性**: 自动包含最后修改时间 (lastmod)
#### 1.2 Robots.txt 动态配置
- **路由**: `/robots.txt`
- **功能**: 指导搜索引擎爬虫
- **配置**:
- 允许爬取: 所有公开页面
- 禁止爬取: /admin/, /api/
- 自动引用sitemap.xml地址
### 2. 结构化数据 (Schema.org)
#### 2.1 工具详情页 - SoftwareApplication
- **类型**: `SoftwareApplication`
- **包含字段**:
- name, url, image, description
- featureList (主要功能列表)
- applicationCategory, operatingSystem
- keywords (关联标签)
- offers (价格信息)
- aggregateRating (基于浏览次数的评分)
#### 2.2 面包屑导航 - BreadcrumbList
- **类型**: `BreadcrumbList`
- **层级结构**: 首页 > 标签 > 工具详情
- **好处**: 搜索结果中显示完整导航路径
#### 2.3 Open Graph 标签
- **支持平台**: 微信、Twitter、Facebook等
- **包含内容**: title, description, url, image
- **效果**: 社交媒体分享时显示精美卡片
### 3. 内容自动内链系统
#### 3.1 智能识别工具名称
- **功能**: 自动识别内容中提到的其他工具并添加链接
- **实现**: 新增 `auto_link` Jinja2过滤器
- **策略**:
- 按名称长度降序匹配(优先匹配长名称)
- 每个工具名称仅链接一次
- 排除当前工具本身
- **样式**: 虚线下划线,蓝色文字,带tooltip
#### 3.2 应用范围
- 工具详情页的"产品概述"
- 工具详情页的"主要功能"
### 4. 标签专题页SEO优化
#### 4.1 新增Tag模型字段
- `seo_title`: SEO标题 (100字符)
- `seo_description`: SEO页面描述 (300字符)
- `seo_keywords`: SEO关键词 (200字符)
#### 4.2 动态Meta标签
- 标签页自动使用专属SEO信息
- 支持降级: 无配置时使用默认值
- 首页也有完整的meta标签配置
### 5. 面包屑导航
#### 5.1 可视化导航
- **结构**: 首页 > 标签 > 工具名
- **样式**: 灰色文字,悬停变蓝,当前项加粗
- **位置**: 详情页顶部,返回按钮上方
#### 5.2 增强用户体验
- 清晰的页面层级关系
- 便捷的快速导航
- aria-label支持屏幕阅读器
### 6. 页面级SEO改进
#### 6.1 工具详情页
- canonical链接(避免重复内容)
- 动态keywords meta标签
- 动态description meta标签
#### 6.2 标签页
- 专属的页面标题
- 专属的描述和关键词
- canonical URL
---
## 🚀 部署步骤
### 1. 备份数据库
```bash
# 备份当前数据库
mysqldump -u root -p zjpb > zjpb_backup_v2.3.0_$(date +%Y%m%d).sql
```
### 2. 停止应用
```bash
# 如果使用supervisor
sudo supervisorctl stop zjpb
# 或者如果使用gunicorn直接运行
pkill -f gunicorn
```
### 3. 更新代码
```bash
cd /path/to/zjpb
git pull origin master
# 或者手动上传更新的文件
```
### 4. 执行数据库迁移
```bash
# 激活虚拟环境
source venv/bin/activate # Linux/Mac
# 或
venv\Scripts\activate # Windows
# 执行迁移脚本
python migrate_tag_seo_fields.py
```
**迁移脚本说明:**
- 为`tags`表添加3个新字段
- 自动检查字段是否已存在,避免重复执行
- 支持MySQL COMMENT
### 5. 重启应用
```bash
# 使用supervisor
sudo supervisorctl start zjpb
sudo supervisorctl status zjpb
# 或使用gunicorn
gunicorn -c gunicorn_config.py app:app
```
### 6. 验证部署
#### 6.1 检查SEO路由
访问以下URL确认功能正常:
- `https://your-domain.com/sitemap.xml` - 应显示完整的sitemap
- `https://your-domain.com/robots.txt` - 应显示robots配置
#### 6.2 检查详情页
- 打开任意工具详情页
- 查看页面源代码,确认有Schema.org JSON-LD
- 确认面包屑导航显示正常
- 确认meta标签完整
#### 6.3 检查数据库
```sql
-- 确认新字段已添加
DESCRIBE tags;
-- 应该看到:
-- seo_title
-- seo_description
-- seo_keywords
```
---
## 📝 后续配置任务
### 1. 为标签填写SEO信息 (重要!)
登录后台管理系统 (`/admin`)，进入"标签管理":
**推荐配置示例:**
**标签名**: AI写作
- **SEO标题**: 最好用的AI写作工具推荐 - ZJPB
- **SEO描述**: 发现最优秀的AI写作工具,包括文章生成、内容润色、创意写作等功能。精选30+款专业AI写作助手,提升写作效率10倍。
- **SEO关键词**: AI写作,AI文章生成,智能写作,AI内容创作,写作助手
**注意事项:**
- SEO标题控制在60字符以内
- SEO描述控制在160字符以内
- SEO关键词用逗号分隔,不超过10个
### 2. 提交Sitemap到搜索引擎
#### 2.1 Google Search Console
1. 登录 https://search.google.com/search-console
2. 选择你的网站属性
3. 侧边栏点击"站点地图"
4. 输入 `sitemap.xml` 并提交
#### 2.2 百度搜索资源平台
1. 登录 https://ziyuan.baidu.com
2. 选择你的网站
3. "数据引入" > "链接提交" > "sitemap"
4. 提交sitemap地址
#### 2.3 必应站长工具
1. 登录 https://www.bing.com/webmasters
2. 选择你的网站
3. "配置我的网站" > "站点地图"
4. 提交sitemap地址
### 3. 验证结构化数据
使用Google Rich Results Test:
1. 访问 https://search.google.com/test/rich-results
2. 输入你的工具详情页URL
3. 确认"SoftwareApplication"和"BreadcrumbList"被正确识别
### 4. 优化内容以利用内链系统
**建议**:
- 在编写工具详细介绍时,自然地提及相关工具名称
- 系统会自动为这些名称添加内链
- 例如: "与ChatGPT类似,Claude也是..."
---
## 🔍 SEO效果监测
### 1. 关键指标
监测以下数据(建议使用Google Analytics):
- 自然搜索流量
- 页面停留时间
- 跳出率
- 页面加载速度
### 2. 搜索结果优化
观察搜索结果中是否出现:
- ✓ 面包屑导航路径
- ✓ 评分星级(来自aggregateRating)
- ✓ 丰富摘要信息
### 3. 索引监控
使用Google Search Console监控:
- 页面索引数量
- 覆盖率报告
- 增强功能报告(查看结构化数据状态)
---
## 🐛 故障排查
### 问题1: sitemap.xml 显示404
**原因**: 路由未正确注册
**解决**: 检查app.py中是否有sitemap路由,重启应用
### 问题2: 数据库迁移失败
**错误**: "Column already exists"
**原因**: 迁移脚本已执行过
**解决**: 这是正常现象,脚本会自动跳过已存在的字段
### 问题3: Schema.org数据不显示
**检查项**:
- 确认base_new.html中有 `{% block extra_head %}`
- 确认detail_new.html正确继承并使用该block
- 使用Google Rich Results Test验证
### 问题4: 内链不生效
**检查项**:
- 确认app.py中有`auto_link`过滤器定义
- 确认detail_new.html使用了 `| auto_link(site.id)`
- 数据库中是否有其他启用的工具
---
## 📈 性能影响评估
### 1. 页面加载
- Sitemap生成: +20ms (缓存后几乎无影响)
- Schema.org输出: +5ms
- 内链处理: +30ms (仅详情页)
### 2. 数据库
- 新增3个VARCHAR字段,存储开销: <1KB/标签
- 无新增查询,性能影响可忽略
### 3. 优化建议
- 未来可为sitemap添加缓存(如15分钟)
- 内链可考虑结果缓存
---
## 🎯 下一步建议
### 短期(1-2周)
1. 完成所有标签的SEO信息配置
2. 提交sitemap到主流搜索引擎
3. 验证所有结构化数据
### 中期(1个月)
1. 监控自然搜索流量变化
2. 根据Search Console数据优化关键词
3. A/B测试不同的SEO描述
### 长期(3个月+)
1. 定期更新sitemap(自动完成)
2. 分析哪些页面SEO表现最好
3. 考虑添加更多Schema类型(如FAQPage)
---
## 🔄 版本回滚
如需回滚到v2.3.0:
```bash
# 1. 停止应用
sudo supervisorctl stop zjpb
# 2. 还原代码
git checkout v2.3.0
# 或还原备份的文件
# 3. (可选)还原数据库
# 注意: 新增的SEO字段不影响旧版本运行,可保留
mysql -u root -p zjpb < zjpb_backup_v2.3.0_YYYYMMDD.sql
# 4. 重启应用
sudo supervisorctl start zjpb
```
---
## 📞 技术支持
- **GitHub Issues**: https://github.com/your-repo/zjpb/issues
- **文档**: 查看项目Wiki
- **版本历史**: CHANGELOG.md
---
## ✅ 部署检查清单
- [ ] 数据库已备份
- [ ] 代码已更新
- [ ] 迁移脚本执行成功
- [ ] 应用重启成功
- [ ] /sitemap.xml 可访问
- [ ] /robots.txt 可访问
- [ ] 工具详情页有结构化数据
- [ ] 面包屑导航显示正常
- [ ] 标签SEO字段可在后台编辑
- [ ] 已提交sitemap到搜索引擎
- [ ] 已用Rich Results Test验证
- [ ] 性能监控正常
---
**祝部署顺利! v2.4.0将为你的SEO带来显著提升。**
*最后更新: 2026-01-03*

594
docs/archive/DEVELOP_v2.4.1_TAB_FEATURE.md Normal file
View File

@@ -0,0 +1,594 @@
# ZJPB v2.4.1 开发文档 - 标签功能优化
**版本号**: v2.4.1
**开发日期**: 2026-01-04
**功能主题**: 最新/热门/推荐标签功能
**开发者**: Claude Code
**Git Commit**: 8011e5b
---
## 📋 功能概述
### 用户需求
用户原本要求实现"热门工具排行榜"功能，但在看到初版实现后明确拒绝了顶部独立排行榜的设计，提出了新的需求：
> "这个列表并不好看，不用在顶部单独增加模块，可以在tag下增加3个tab，分别是"最新"、"热门"、"推荐" 这三个，其中"推荐"可以在后台添加网站或者编辑的时候设置"
### 最终实现
- ✅ **完全移除**：删除顶部热门工具排行榜模块（约118行CSS + HTML）
- ✅ **Tab导航**：在分类标签下方添加三个tab（最新/热门/推荐）
- ✅ **数据库支持**：添加`is_recommended`字段到Site模型
- ✅ **后台管理**：支持在后台标记推荐工具
- ✅ **状态保持**：URL参数保持tab、分类、搜索、分页状态
- ✅ **完整测试**：所有功能已本地验证通过
---
## 🏗️ 技术架构
### 1. 数据库层
#### 新增字段
**表名**: `sites`
**字段名**: `is_recommended`
**类型**: `TINYINT(1)`
**默认值**: `0` (False)
**注释**: "是否推荐"
**DDL语句**:
```sql
ALTER TABLE sites ADD COLUMN is_recommended TINYINT(1) NOT NULL DEFAULT 0 COMMENT '是否推荐';
```
#### 迁移脚本
**文件**: `migrations/add_is_recommended.py`
**特性**:
- 幂等性检查（避免重复执行）
- 支持upgrade/downgrade
- 自动检测字段是否已存在
- 错误处理和事务回滚
### 2. 后端层
#### 路由修改
**文件**: `app.py`
**函数**: `index()` (Lines 70-148)
**新增参数处理**:
```python
current_tab = request.args.get('tab', 'latest') # 默认为"最新"
```
**三种模式的查询逻辑**:
1. **最新模式** (默认):
```python
if current_tab == 'latest' or not current_tab:
query = query.order_by(Site.created_at.desc(), Site.id.desc())
```
2. **热门模式**:
```python
elif current_tab == 'popular':
query = query.order_by(Site.view_count.desc(), Site.id.desc())
```
3. **推荐模式**:
```python
elif current_tab == 'recommended':
query = query.filter_by(is_recommended=True).order_by(Site.sort_order.desc(), Site.id.desc())
```
**关键特性**:
- 支持与分类筛选（tag）组合使用
- 支持与搜索（q）组合使用
- 支持分页
- 所有查询条件可叠加
#### Flask-Admin配置
**文件**: `app.py`
**类**: `SiteAdmin` (Lines 1345-1481)
**修改点**:
```python
# 列表显示添加推荐字段
column_list = ['id', 'code', 'name', 'url', 'slug', 'is_active', 'is_recommended', 'view_count', 'created_at']
# 添加推荐筛选器
column_filters = ['is_active', 'is_recommended', 'tags']
# 表单添加推荐字段
form_columns = ['name', 'url', 'slug', 'logo', 'short_desc', 'description', 'features', 'news_keywords', 'tags', 'is_active', 'is_recommended', 'sort_order']
# 中文标签
column_labels = {
'is_recommended': '是否推荐',
# ... 其他字段
}
```
### 3. 前端层
#### 模板文件
**文件**: `templates/index_new.html`
**删除内容** (约118行):
- `.popular-section` 相关所有CSS
- `.popular-header`, `.popular-title`, `.popular-badge` 样式
- `.popular-grid`, `.popular-item` 样式
- 顶部热门工具HTML结构
**新增内容**:
**Tab导航CSS** (Lines 339-397):
```css
.sort-tabs {
padding: 24px 0 0 0;
border-top: 1px solid var(--border-color);
margin-top: 24px;
}
.sort-tab {
padding: 8px 20px;
border-radius: 50px;
/* ... 完整样式见源码 */
}
.sort-tab.active {
background: var(--primary-blue);
border-color: var(--primary-blue);
color: white;
}
```
**Tab导航HTML** (Lines 443-462):
```html
<div class="sort-tabs">
<div class="sort-tabs-container">
<a href="/?{% if selected_tag %}tag={{ selected_tag.slug }}&{% endif %}tab=latest"
class="sort-tab {% if not current_tab or current_tab == 'latest' %}active{% endif %}">
<span class="icon">🕐</span>
最新
</a>
<a href="/?{% if selected_tag %}tag={{ selected_tag.slug }}&{% endif %}tab=popular"
class="sort-tab {% if current_tab == 'popular' %}active{% endif %}">
<span class="icon">🔥</span>
热门
</a>
<a href="/?{% if selected_tag %}tag={{ selected_tag.slug }}&{% endif %}tab=recommended"
class="sort-tab {% if current_tab == 'recommended' %}active{% endif %}">
<span class="icon">⭐</span>
推荐
</a>
</div>
</div>
```
**分页链接更新** (Lines 505-556):
所有分页链接都更新为保持tab状态：
```html
<!-- 示例 -->
<a href="?page={{ page_num }}{% if selected_tag %}&tag={{ selected_tag.slug }}{% endif %}{% if search_query %}&q={{ search_query }}{% endif %}{% if current_tab and current_tab != 'latest' %}&tab={{ current_tab }}{% endif %}">
```
**关键逻辑**:
- 默认tab为'latest'时不显示在URL中（保持URL简洁）
- 非默认tab时添加`&tab=xxx`参数
- 保持所有其他状态（tag, q, page）
---
## 📁 文件变更清单
### 新增文件
1. **migrations/add_is_recommended.py** (73 lines)
- 数据库迁移脚本
- 添加is_recommended字段
### 修改文件
1. **models.py**
- Line 29: 添加`is_recommended`字段定义
- Line 56: `to_dict()`方法添加字段序列化
2. **app.py**
- Lines 95: 添加`current_tab`参数处理
- Lines 130-139: 实现三种tab模式的查询逻辑
- Line 148: 传递`current_tab`到模板
- Lines 1360-1382: Flask-Admin配置更新
3. **templates/index_new.html**
- 删除: ~118行热门section相关代码
- Lines 339-397: 新增tab导航CSS
- Lines 443-462: 新增tab导航HTML
- Lines 505-556: 更新所有分页链接
**统计**: 4个文件修改，167行新增，181行删除
---
## 🔄 URL参数设计
### 参数说明
| 参数 | 说明 | 默认值 | 示例 |
|------|------|--------|------|
| `tag` | 分类筛选 | 无 | `tag=ai-chat` |
| `tab` | 排序模式 | `latest` | `tab=popular` |
| `q` | 搜索关键词 | 无 | `q=chatgpt` |
| `page` | 页码 | `1` | `page=2` |
### URL组合示例
```
# 只有tab
/?tab=popular
# 分类 + tab
/?tag=ai-chat&tab=popular
# 分类 + tab + 分页
/?tag=ai-chat&tab=recommended&page=2
# 分类 + tab + 搜索 + 分页
/?tag=ai-chat&tab=popular&q=对话&page=2
```
### 设计原则
- **简洁性**: 默认值（tab=latest, page=1）不出现在URL中
- **状态保持**: 所有操作（切换tab、翻页等）保持其他参数
- **向后兼容**: 无tab参数时默认为latest模式
- **SEO友好**: URL清晰可读
---
## 🧪 测试验证
### 本地测试（已完成）
**测试环境**:
- Flask Development Server
- 测试时间: 2026-01-04 00:16:41 - 00:54:25
- 数据库: MySQL
**测试用例**:
1. ✅ **数据库迁移**
- 执行时间: 00:28:18
- 结果: 成功添加is_recommended字段
- SQL: `ALTER TABLE sites ADD COLUMN is_recommended TINYINT(1) NOT NULL DEFAULT 0`
2. ✅ **三种tab模式**
- 最新 (00:38:37): `ORDER BY created_at DESC`
- 热门 (00:38:39): `ORDER BY view_count DESC`
- 推荐 (00:39:10): `WHERE is_recommended = true ORDER BY sort_order DESC`
3. ✅ **后台管理**
- 访问admin界面 (00:38:48)
- 编辑Site ID=1 (00:39:02)
- 成功设置is_recommended=1
4. ✅ **组合筛选**
- 分类 + tab: `?tag=ai-chat&tab=popular` (00:39:15)
- 所有组合均正常工作
5. ✅ **分页状态保持**
- URL参数在翻页时正确保持
### 生产部署（已完成）
**部署时间**: 2026-01-04
**部署方式**: Git pull + 数据库迁移 + 应用重启
**部署状态**: ✅ 成功
---
## 💡 核心技术要点
### 1. SQLAlchemy查询链式调用
```python
# 基础查询
query = Site.query.filter_by(is_active=True)
# 条件叠加
if tag_slug:
query = query.filter(Site.tags.contains(selected_tag))
# 排序方式
query = query.order_by(Site.created_at.desc(), Site.id.desc())
# 分页
pagination = query.paginate(page=page, per_page=100, error_out=False)
```
### 2. Jinja2条件CSS类
```html
<a class="sort-tab {% if current_tab == 'popular' %}active{% endif %}">
```
### 3. URL参数拼接
```html
href="/?{% if selected_tag %}tag={{ selected_tag.slug }}&{% endif %}tab=latest"
```
**技巧**: 使用`{% if %}`控制参数是否出现，避免空参数
### 4. Flask请求参数处理
```python
# 获取参数，提供默认值
current_tab = request.args.get('tab', 'latest')
# 安全获取整数
page = request.args.get('page', 1, type=int)
# 字符串处理
search_query = request.args.get('q', '').strip()
```
---
## 🎨 UI/UX设计
### 视觉设计
**Tab样式**:
- 未激活: 白色背景，灰色边框，灰色文字
- 悬停: 蓝色边框，浅蓝背景，蓝色文字
- 激活: 蓝色背景，白色文字
- 圆角: 50px（胶囊形状）
- 图标: Unicode emoji（🕐🔥⭐）
**位置**:
- 在分类标签下方
- 顶部有1px灰色分隔线
- 24px上边距
### 交互设计
**用户流程**:
1. 用户访问首页，默认显示"最新"工具
2. 点击分类标签，查看特定分类
3. 切换tab，改变排序方式
4. 所有状态通过URL保持，支持刷新和分享
**状态反馈**:
- 当前激活的tab高亮显示
- URL参数实时更新
- 页面内容即时切换
---
## 🔒 数据完整性
### 默认值处理
- 所有现有记录的`is_recommended`默认为`0` (False)
- 新创建的Site默认`is_recommended=False`
- 不影响现有数据
### 查询优化
```python
# 推荐模式只查询is_recommended=True的记录
query.filter_by(is_recommended=True)
# 使用索引字段排序
order_by(Site.sort_order.desc(), Site.id.desc())
```
### 数据库索引建议
```sql
-- 可选：如果推荐工具数量很多，建议添加索引
CREATE INDEX idx_is_recommended ON sites(is_recommended);
```
---
## 📊 性能影响评估
### 查询性能
- **Latest模式**: 使用created_at索引，性能无影响
- **Popular模式**: 使用view_count字段，建议添加索引
- **Recommended模式**: 数据量少（推荐工具有限），性能影响可忽略
### 数据库存储
- 新增1个TINYINT字段：1 byte/record
- 假设1000个工具：1 KB额外存储
- 影响可忽略
### 页面加载
- 无额外HTTP请求
- CSS/HTML增加约2KB（gzip后<1KB）
- 渲染时间 <5ms
---
## 🐛 已知问题和解决方案
### 问题1: 推荐tab显示为空
**原因**: 没有标记任何工具为推荐
**解决**: 在后台至少标记几个优质工具为推荐
### 问题2: 数据库迁移重复执行
**原因**: 迁移脚本被多次运行
**解决**: 脚本有幂等性检查，会自动跳过已存在的字段
### 问题3: URL过长
**原因**: 同时使用tag, tab, q, page参数
**解决**:
- 默认值不出现在URL（tab=latest, page=1）
- 这是正常行为，利于状态保持
---
## 🚀 未来优化建议
### 短期优化 (1-2周)
1. **添加数据库索引**
```sql
CREATE INDEX idx_view_count ON sites(view_count DESC);
CREATE INDEX idx_is_recommended ON sites(is_recommended);
```
2. **优化推荐工具管理**
- 在后台网站列表添加"快速推荐"按钮
- 批量操作：批量设置/取消推荐
3. **用户行为分析**
- 添加Google Analytics事件追踪
- 统计哪个tab使用最频繁
### 中期优化 (1个月)
1. **Tab切换动画**
- 添加淡入淡出效果
- 优化用户体验
2. **推荐算法**
- 根据浏览量、评分自动建议推荐
- 定期更新推荐列表
3. **A/B测试**
- 测试不同的默认tab（latest vs popular）
- 测试tab位置（上方 vs 下方）
### 长期优化 (3个月+)
1. **个性化推荐**
- 基于用户浏览历史
- 机器学习推荐算法
2. **多维度筛选**
- 添加更多tab（如"最受欢迎"、"编辑精选"）
- 组合筛选器
3. **缓存优化**
- Redis缓存热门查询
- 减少数据库压力
---
## 📚 相关文档
### 项目文档
- `DEPLOY_v2.4.0.md` - SEO功能部署文档
- `DEPLOY_CHECKLIST_v2.3.md` - 部署检查清单
- `README.md` - 项目总体说明
### 代码文件
- `app.py` - Flask应用主文件
- `models.py` - 数据库模型定义
- `templates/index_new.html` - 首页模板
- `migrations/add_is_recommended.py` - 本次迁移脚本
### Git提交
- **Commit ID**: `8011e5b`
- **Commit Message**: "feat: 实现最新/热门/推荐标签功能"
- **上一个版本**: `da30394` (热门工具排行榜 - 已废弃)
---
## 🔧 开发环境设置
### 本地开发
```bash
# 1. 克隆项目
git clone http://server.zjpb.net:3000/jowelin/zjpb.git
cd zjpb
# 2. 创建虚拟环境
python -m venv venv
source venv/bin/activate # Linux/Mac
# 或
venv\Scripts\activate # Windows
# 3. 安装依赖
pip install -r requirements.txt
# 4. 配置环境变量
cp .env.example .env
# 编辑.env文件，配置数据库等信息
# 5. 运行数据库迁移
python migrations/add_is_recommended.py
# 6. 启动开发服务器
python app.py
# 访问 http://localhost:5000
```
### 数据库配置
```python
# .env文件示例
FLASK_ENV=development
DATABASE_URL=mysql+pymysql://root:password@localhost/zjpb
SECRET_KEY=your-secret-key
BOCHA_API_KEY=your-api-key
```
---
## 📞 技术支持
### 问题反馈
- **Git仓库**: http://server.zjpb.net:3000/jowelin/zjpb
- **Issues**: 在Git仓库创建Issue
### 开发者联系
- **开发者**: Claude Code
- **开发日期**: 2026-01-04
- **版本**: v2.4.1
---
## ✅ 二次开发快速启动清单
下次重新开启开发时，参考以下清单：
- [ ] 阅读本文档，了解最新功能
- [ ] 查看Git log，了解最近提交
- [ ] 拉取最新代码：`git pull origin master`
- [ ] 激活虚拟环境
- [ ] 运行`python app.py`启动开发服务器
- [ ] 访问`http://localhost:5000`验证功能
- [ ] 登录后台`/admin`检查数据
- [ ] 查看`logs/error.log`确认无错误
---
## 📈 功能使用统计（建议追踪）
### 关键指标
- Tab点击率（latest vs popular vs recommended）
- 推荐工具数量
- 用户停留时间
- 分类+tab组合使用频率
### 数据查询示例
```sql
-- 查看推荐工具数量
SELECT COUNT(*) FROM sites WHERE is_recommended = 1 AND is_active = 1;
-- 查看各分类的推荐工具分布
SELECT t.name, COUNT(st.site_id) as recommended_count
FROM tags t
LEFT JOIN site_tags st ON t.id = st.tag_id
LEFT JOIN sites s ON st.site_id = s.id
WHERE s.is_recommended = 1 AND s.is_active = 1
GROUP BY t.id, t.name
ORDER BY recommended_count DESC;
-- 查看热门工具TOP 10
SELECT id, name, view_count
FROM sites
WHERE is_active = 1
ORDER BY view_count DESC
LIMIT 10;
```
---
**文档版本**: v1.0
**最后更新**: 2026-01-04
**下次更新**: 根据需要
---
祝二次开发顺利！🎉

462
docs/archive/DEVELOP_v2.6.0_API_SECURITY.md Normal file
View File

@@ -0,0 +1,462 @@
# ZJPB v2.6.0 开发文档 - API安全优化
**版本号**: v2.6.0
**开发日期**: 2026-02-06
**功能主题**: 博查API调用优化 + 频率限制 + 安全防护
**Git Commit**: (待提交)
---
## 📋 功能概述
### 问题背景
v2.5及之前版本存在严重的成本浪费问题：
- 每次访问详情页都自动调用博查API
- 没有频率限制，容易被滥用
- 缺少安全防护机制
### 优化目标
1. **按需加载**: 只在用户点击按钮时才调用API
2. **频率限制**: 每个IP每小时最多3次请求
3. **验证码防护**: 超过阈值后需要验证码
4. **成本控制**: 大幅降低无意义的API消耗
---
## 🎯 核心改进
### 1. 移除自动调用逻辑
**修改文件**: `app.py:151-240`
**before (v2.5)**:
```python
# 智能新闻更新：检查今天是否已更新过新闻
need_update = False
if not latest_news:
need_update = True
elif latest_news.created_at.date() < today:
need_update = True
# 如果需要更新，自动获取最新新闻
if need_update:
searcher = NewsSearcher(api_key)
news_items = searcher.search_site_news(...)
# 保存到数据库
```
**after (v2.6)**:
```python
# v2.6优化：移除自动调用博查API的逻辑，改为按需加载
# 只获取数据库中已有的新闻，不再自动调用API
news_list = News.query.filter_by(
site_id=site.id,
is_active=True
).order_by(News.published_at.desc()).limit(5).all()
```
**影响**: 每次页面访问减少1次API调用，节省成本约95%+
### 2. 按需加载API
**新增路由**: `/api/fetch-news/<code>`
**方法**: POST
**权限**: 公开（有频率限制）
**功能**:
- 用户点击"加载资讯"按钮时调用
- 返回JSON格式的新闻列表
- 前端动态渲染，无需刷新页面
### 3. 频率限制系统
**新增文件**: `utils/rate_limiter.py` (320行)
**核心类**:
- `RateLimiter`: 基于内存的频率限制器
- `CaptchaVerifier`: 验证码验证器
- `get_client_ip()`: 获取真实IP（考虑代理/CDN）
**限制策略**:
- 每个IP每小时最多3次请求
- 超过限制后需要等待或完成验证码
- 验证码要求持续30分钟
**配置参数**:
```python
# 在 fetch_news_for_site() 中配置
limiter.is_rate_limited(
client_ip,
action='news_fetch',
limit=3, # 每小时3次
window_minutes=60 # 时间窗口60分钟
)
```
### 4. 验证码集成
**支持的服务**:
- `simple`: 简单验证（开发测试用）
- `recaptcha`: Google reCAPTCHA v2/v3
- `hcaptcha`: hCaptcha
**集成步骤**:
1. 在`.env`中配置密钥：
```env
RECAPTCHA_SECRET_KEY=your-secret-key
# 或
HCAPTCHA_SECRET_KEY=your-secret-key
```
2. 修改`app.py`中的验证器实例化：
```python
verifier = CaptchaVerifier(
service='recaptcha',
secret_key=app.config.get('RECAPTCHA_SECRET_KEY')
)
```
3. 前端添加验证码组件（见下文）
---
## 🔧 技术实现
### 前端改进
**修改文件**: `templates/detail_new.html`
**1. 新闻区域显示逻辑**:
```html
<!-- 始终显示新闻区域 -->
<div class="content-block">
<button onclick="loadNews('{{ site.code }}')">
{% if has_news %}获取最新资讯{% else %}加载资讯{% endif %}
</button>
{% if news_list %}
<!-- 显示已有新闻 -->
{% else %}
<!-- 显示占位提示 -->
<div class="news-placeholder">
点击右上角"加载资讯"按钮获取最新内容
</div>
{% endif %}
</div>
```
**2. AJAX加载函数**:
```javascript
function loadNews(siteCode) {
fetch(`/api/fetch-news/${siteCode}`, {
method: 'POST',
headers: {'Content-Type': 'application/json'}
})
.then(response => response.json())
.then(data => {
if (data.success) {
// 动态渲染新闻列表
renderNews(data.news);
showMessage(data.message, 'success');
} else if (data.require_captcha) {
// 显示验证码
showCaptchaModal();
} else {
showMessage(data.error, 'error');
}
});
}
```
### 后端改进
**修改文件**: `app.py:185-307`
**流程图**:
```
用户请求
↓
获取客户端IP
↓
检查是否需要验证码 → YES → 返回429错误
↓ NO
检查频率限制 → 超限 → 要求验证码 → 返回429错误
↓ 未超限
验证验证码(如果提供)
↓
记录请求
↓
调用博查API
↓
保存到数据库
↓
返回新闻列表
```
---
## 📊 性能对比
### API调用次数
**场景**: 某个工具详情页被浏览100次
| 版本 | 自动调用 | 手动点击 | 总调用 | 成本 |
|------|---------|---------|--------|------|
| v2.5 | 100次 | 0次 | 100次 | ¥100 |
| v2.6 | 0次 | ~10次 | 10次 | ¥10 |
**节省**: 约90% API成本
### 频率限制效果
**攻击场景**: 恶意脚本每秒请求1次
| 版本 | 1小时调用 | 成本 |
|------|----------|------|
| v2.5 | 3600次 | ¥3600 |
| v2.6 | 3次 | ¥3 |
**防护**: 99.9% 成本节省
---
## 🚀 部署指南
### 1. 更新依赖
```bash
pip install Flask-Limiter==3.5.0
# 或
pip install -r requirements.txt
```
### 2. 更新代码
```bash
git pull origin master
# 或手动上传更新的文件
```
### 3. 无需数据库迁移
本次更新无数据库结构变更。
### 4. 重启应用
```bash
# 使用1Panel或命令行
sudo supervisorctl restart zjpb
```
### 5. 验证部署
1. 访问任意工具详情页
2. 确认不会自动加载新闻（页面加载快了）
3. 点击"加载资讯"按钮
4. 确认新闻正常显示
5. 连续点击4次，确认出现频率限制提示
---
## ⚙️ 配置选项
### 频率限制参数
在`app.py`的`fetch_news_for_site()`函数中：
```python
# 调整限制次数和时间窗口
is_limited, remaining, reset_time = limiter.is_rate_limited(
client_ip,
action='news_fetch',
limit=3, # 改为5次：更宽松
window_minutes=60 # 改为30分钟：更严格
)
# 调整验证码持续时间
limiter.require_captcha(
client_ip,
duration_minutes=30 # 改为60分钟：更严格
)
```
### 验证码配置
**使用Google reCAPTCHA**:
1. 注册并获取密钥：https://www.google.com/recaptcha/admin
2. 配置`.env`:
```env
RECAPTCHA_SITE_KEY=your-site-key
RECAPTCHA_SECRET_KEY=your-secret-key
```
3. 修改`app.py`:
```python
verifier = CaptchaVerifier(
service='recaptcha',
secret_key=app.config.get('RECAPTCHA_SECRET_KEY')
)
```
**使用hCaptcha**（国内推荐）:
1. 注册：https://www.hcaptcha.com/
2. 配置`.env`:
```env
HCAPTCHA_SITE_KEY=your-site-key
HCAPTCHA_SECRET_KEY=your-secret-key
```
3. 修改`app.py`:
```python
verifier = CaptchaVerifier(
service='hcaptcha',
secret_key=app.config.get('HCAPTCHA_SECRET_KEY')
)
```
---
## 🔐 安全特性
### IP识别策略
支持CDN/代理场景，按优先级获取真实IP：
1. `X-Forwarded-For` 头（第一个IP）
2. `X-Real-IP` 头
3. `request.remote_addr`
### 防绕过机制
- 基于IP地址限制（不依赖Cookie/Session）
- 验证码要求持续30分钟（不能通过清除缓存绕过）
- 时间窗口滑动（不是固定时段）
### 日志记录
建议添加日志记录（TODO）：
```python
# 记录频率限制触发
app.logger.warning(f"Rate limit triggered: {client_ip}")
# 记录验证码验证失败
app.logger.warning(f"Captcha failed: {client_ip}")
```
---
## 📝 文档整合
**新增目录结构**:
```
docs/
├── README.md # 文档索引
├── deployment/ # 部署相关文档
│ ├── DEPLOYMENT.md
│ ├── QUICK_DEPLOY.md
│ └── ...
└── archive/ # 历史版本文档
├── DEPLOY_v2.4.0.md
├── DEVELOP_v2.4.1_TAB_FEATURE.md
├── NEWS_FEATURE_v2.2.md
└── WORK_PROGRESS_20250130.md
```
**整合原因**: 简化根目录，提高可维护性
---
## 🐛 已知问题和注意事项
### 1. 内存存储限制
当前使用内存存储频率限制数据，重启应用后清空。
**生产环境建议**:
- 使用Redis存储（持久化）
- 使用Flask-Limiter扩展（自带Redis支持）
**Redis集成示例**:
```python
from flask_limiter import Limiter
from flask_limiter.util import get_remote_address
limiter = Limiter(
app,
key_func=get_remote_address,
storage_uri="redis://localhost:6379"
)
@app.route('/api/fetch-news/<code>')
@limiter.limit("3 per hour")
def fetch_news_for_site(code):
...
```
### 2. 验证码体验
当前简单验证码仅用于开发测试，生产环境必须配置实际验证码服务。
### 3. CDN缓存
如果使用CDN，确保`/api/fetch-news/*`路径不被缓存：
- Cloudflare: Page Rules设置`Cache Level: Bypass`
- 阿里云CDN: 配置缓存规则，排除API路径
---
## 🎯 未来改进
### 短期 (1周内)
- [ ] 配置Redis存储替换内存存储
- [ ] 配置生产环境验证码服务（reCAPTCHA或hCaptcha）
- [ ] 添加请求日志记录和监控
- [ ] 优化前端错误提示UI
### 中期 (1个月)
- [ ] 实现验证码UI组件
- [ ] 添加管理后台查看API调用统计
- [ ] 实现白名单机制（管理员IP不限制）
- [ ] 添加用户友好的限流提示页面
### 长期 (3个月+)
- [ ] 实现基于用户账号的限流（登录用户更高额度）
- [ ] API调用成本统计和预警
- [ ] 智能频率调整（基于历史行为）
- [ ] 分布式限流支持
---
## 📞 技术支持
- **开发者**: Claude Code
- **版本**: v2.6.0
- **发布日期**: 2026-02-06
---
## ✅ 部署检查清单
- [ ] 已安装Flask-Limiter依赖
- [ ] 已更新app.py代码
- [ ] 已更新detail_new.html模板
- [ ] 已添加utils/rate_limiter.py
- [ ] 已更新requirements.txt
- [ ] 应用重启成功
- [ ] 详情页不再自动加载新闻
- [ ] 点击按钮可以加载新闻
- [ ] 连续请求触发频率限制
- [ ] 错误提示正常显示
- [ ] （可选）已配置验证码服务
- [ ] （可选）已配置Redis存储
---
**祝部署顺利！v2.6将大幅降低API成本。** 🎉
*最后更新: 2026-02-06*

408
docs/archive/NEWS_FEATURE_v2.2.md Normal file
View File

@@ -0,0 +1,408 @@
# ZJPB v2.2.0 - 新闻搜索功能
**版本**: v2.2.0
**发布日期**: 2025-01-30
**主要功能**: 集成博查Web Search API，自动获取网站相关新闻
---
## 📋 功能概述
v2.2.0版本引入了全新的新闻搜索和展示功能，通过博查AI搜索引擎API，自动为每个网站获取最新的相关新闻，并在网站详情页进行展示。
### ✨ 核心特性
1. **智能新闻搜索** 🔍
- 基于网站名称自动搜索相关新闻
- 支持自定义搜索时间范围（一天、一周、一月、一年）
- 自动排除网站自身的内容，确保新闻来源多样性
2. **新闻管理系统** 📰
- 后台新闻列表管理
- 支持手动编辑和删除新闻
- 新闻来源信息展示（网站名称、图标）
3. **前台新闻展示** 🎨
- 网站详情页展示最多5条相关新闻
- 显示新闻标题、摘要、来源、发布时间
- 点击新闻直接跳转到原文链接
4. **定期任务支持** ⏰
- 提供cron任务脚本，支持定期批量获取新闻
- 可配置获取数量、时间范围等参数
---
## 🚀 快速开始
### 1. 配置博查API
在`.env`文件中添加博查API配置：
```env
# 博查 Web Search API配置
BOCHA_API_KEY=sk-your-api-key-here
BOCHA_BASE_URL=https://api.bocha.cn
```
获取API Key：访问 [博查AI开放平台](https://open.bocha.cn) 注册并获取API密钥。
### 2. 数据库迁移
运行迁移脚本，为News表添加新字段：
```bash
python migrate_news_fields.py
```
迁移会添加以下字段：
- `source_name`: 新闻来源网站名称
- `source_icon`: 新闻来源网站图标URL
### 3. 测试新闻获取
#### 方法1：使用Python测试脚本
```bash
# 测试NewsSearcher类
python utils/news_searcher.py
```
#### 方法2：使用后台API
登录后台后，使用API接口：
**单个网站获取新闻**：
```bash
curl -X POST http://localhost:5000/api/fetch-site-news \
-H "Content-Type: application/json" \
-d '{
"site_id": 1,
"count": 10,
"freshness": "oneMonth"
}'
```
**批量获取新闻**：
```bash
curl -X POST http://localhost:5000/api/fetch-all-news \
-H "Content-Type: application/json" \
-d '{
"count": 5,
"freshness": "oneMonth",
"limit": 10
}'
```
### 4. 查看新闻
1. 访问任意网站详情页（例如：`http://localhost:5000/site/12345678`）
2. 滚动到页面下方，查看"相关新闻"部分
3. 点击新闻标题或"阅读全文"链接跳转到原文
---
## 📖 使用指南
### 后台管理
#### 新闻管理界面
1. 登录后台：`http://localhost:5000/admin`
2. 点击左侧菜单"新闻管理"
3. 可以查看、编辑、删除已获取的新闻
**新闻列表字段**：
- ID
- 关联网站
- 新闻标题
- 来源网站
- 新闻类型
- 发布时间
- 是否启用
#### 手动获取新闻
虽然提供了API接口，但目前没有直接的后台UI按钮。可以通过以下方式触发：
1. 使用API接口（参见快速开始）
2. 使用定期任务脚本（参见下文）
### 定期任务设置
使用`fetch_news_cron.py`脚本定期自动获取新闻。
#### 手动执行
```bash
# 默认参数：处理10个网站，每个网站获取5条新闻，时间范围一个月
python fetch_news_cron.py
# 自定义参数
python fetch_news_cron.py --limit 20 --count 10 --freshness oneWeek
```
**参数说明**：
- `--limit`: 处理的网站数量限制（默认：10）
- `--count`: 每个网站获取的新闻数量（默认：5）
- `--freshness`: 新闻时间范围（可选：noLimit, oneDay, oneWeek, oneMonth, oneYear）
#### 配置Crontab
在Linux服务器上配置定期任务：
```bash
# 编辑crontab
crontab -e
# 添加以下行（每天早上8点执行）
0 8 * * * cd /opt/1panel/apps/zjpb && /opt/1panel/apps/zjpb/venv/bin/python fetch_news_cron.py --limit 10 >> logs/news_fetch.log 2>&1
# 或每6小时执行一次
0 */6 * * * cd /opt/1panel/apps/zjpb && /opt/1panel/apps/zjpb/venv/bin/python fetch_news_cron.py --limit 20 >> logs/news_fetch.log 2>&1
```
**注意**：
- 确保创建`logs`目录：`mkdir -p logs`
- 修改路径为实际的项目路径
- 根据API配额合理设置执行频率
---
## 🗂️ 文件结构
### 新增文件
```
zjpb/
├── utils/
│ └── news_searcher.py # 博查API封装类
├── migrate_news_fields.py # 数据库迁移脚本
├── fetch_news_cron.py # 定期任务脚本
└── NEWS_FEATURE_v2.2.md # 本文档
```
### 修改文件
```
zjpb/
├── config.py # 添加博查API配置
├── models.py # News模型添加source_name/source_icon字段
├── app.py # 添加新闻获取API路由，更新NewsAdmin
└── templates/
└── detail_new.html # 优化新闻展示UI
```
---
## 🔧 技术实现
### API集成
使用博查Web Search API进行新闻搜索：
- **接口地址**: `https://api.bocha.cn/v1/web-search`
- **认证方式**: Bearer Token
- **请求方法**: POST
- **返回格式**: JSON
### 数据模型
News模型字段：
| 字段 | 类型 | 说明 |
|------|------|------|
| id | Integer | 主键 |
| site_id | Integer | 关联网站ID（外键） |
| title | String(200) | 新闻标题 |
| content | Text | 新闻内容/摘要 |
| news_type | String(50) | 新闻类型 |
| url | String(500) | 新闻链接 |
| source_name | String(100) | ⭐ 来源网站名称（新增） |
| source_icon | String(500) | ⭐ 来源网站图标（新增） |
| published_at | DateTime | 发布时间 |
| is_active | Boolean | 是否启用 |
| created_at | DateTime | 创建时间 |
| updated_at | DateTime | 更新时间 |
### API路由
**1. 单个网站获取新闻**
- **路径**: `/api/fetch-site-news`
- **方法**: POST
- **权限**: 需要登录
- **参数**:
```json
{
"site_id": 1,
"count": 10,
"freshness": "oneMonth"
}
```
**2. 批量获取新闻**
- **路径**: `/api/fetch-all-news`
- **方法**: POST
- **权限**: 需要登录
- **参数**:
```json
{
"count": 5,
"freshness": "oneMonth",
"limit": 10
}
```
---
## 📊 配置选项
在`config.py`中的新闻相关配置：
```python
# 博查 Web Search API配置
BOCHA_API_KEY = os.environ.get('BOCHA_API_KEY')
BOCHA_BASE_URL = os.environ.get('BOCHA_BASE_URL') or 'https://api.bocha.cn'
BOCHA_SEARCH_ENDPOINT = '/v1/web-search'
# 新闻搜索配置
NEWS_SEARCH_COUNT = 10 # 每次搜索返回的新闻数量
NEWS_SEARCH_FRESHNESS = 'oneMonth' # 默认搜索一个月内的新闻
NEWS_SEARCH_SUMMARY = True # 是否显示摘要
```
---
## ⚠️ 注意事项
### API配额限制
- 博查API根据充值金额有请求频率限制
- 建议合理设置定期任务频率，避免过度消耗配额
- 详情参见：[博查API定价](https://open.bocha.cn)
### 去重机制
系统会根据新闻URL自动去重，同一条新闻不会重复保存。
### 搜索策略
- 搜索关键词：`{网站名称} 最新 新闻`
- 自动排除：网站自身域名的内容
- 时间优先：优先显示最新发布的新闻
### 性能优化
- 批量获取时建议限制数量（`--limit 10-20`）
- 避免短时间内频繁调用API
- 数据库查询已优化，使用索引和去重
---
## 🐛 故障排查
### 1. 新闻获取失败
**可能原因**：
- 博查API Key未配置或无效
- API配额不足
- 网络连接问题
**解决方法**：
```bash
# 检查环境变量
python -c "import os; from dotenv import load_dotenv; load_dotenv(); print(os.getenv('BOCHA_API_KEY'))"
# 测试API连接
python utils/news_searcher.py
```
### 2. 数据库字段不存在
**错误信息**：`Unknown column 'source_name' in 'field list'`
**解决方法**：
```bash
# 运行数据库迁移
python migrate_news_fields.py
```
### 3. 详情页不显示新闻
**可能原因**：
- 数据库中没有该网站的新闻记录
- 新闻被设置为不启用（is_active=False）
**解决方法**：
```bash
# 为该网站获取新闻
curl -X POST http://localhost:5000/api/fetch-site-news \
-H "Content-Type: application/json" \
-d '{"site_id": YOUR_SITE_ID}'
```
### 4. 定期任务不执行
**检查清单**：
- [ ] Crontab配置是否正确
- [ ] Python路径是否正确
- [ ] 日志文件是否有写入权限
- [ ] 查看cron日志：`grep CRON /var/log/syslog`
---
## 📈 未来改进
### 计划功能
- [ ] 后台UI按钮直接触发新闻获取
- [ ] 新闻分类和标签支持
- [ ] 新闻摘要AI优化
- [ ] 新闻热度排序
- [ ] 用户收藏新闻功能
- [ ] 新闻RSS订阅
### 性能优化
- [ ] 使用异步任务队列（Celery）
- [ ] 新闻缓存机制
- [ ] 图片CDN加速
---
## 📞 技术支持
- **项目名称**: ZJPB - 焦提示词 | AI工具导航
- **版本**: v2.2.0
- **发布日期**: 2025-01-30
- **博查API文档**: https://bocha-ai.feishu.cn/wiki/RXEOw02rFiwzGSkd9mUcqoeAnNK
---
## 📝 更新日志
### v2.2.0 (2025-01-30)
**新增**：
- ✨ 集成博查Web Search API
- ✨ 新闻自动搜索和存储功能
- ✨ News模型添加source_name和source_icon字段
- ✨ 网站详情页新闻展示优化
- ✨ 后台新闻管理界面增强
- ✨ 定期任务脚本（fetch_news_cron.py）
- ✨ API路由：/api/fetch-site-news 和 /api/fetch-all-news
**修改**：
- 🔧 config.py添加博查API配置
- 🔧 NewsAdmin添加source_name字段显示
- 🔧 detail_new.html优化新闻展示UI
**文档**：
- 📖 NEWS_FEATURE_v2.2.md 功能文档
- 📖 migrate_news_fields.py 迁移脚本文档
---
**祝您使用愉快！** 🎉

427
docs/archive/WORK_PROGRESS_20250130.md Normal file
View File

@@ -0,0 +1,427 @@
# ZJPB v2.1.0 开发进度记录
**日期**: 2025-01-30
**版本**: v2.1.0
**状态**: 部署进行中（90%完成）
---
## 📋 本次开发内容总结
### 新增功能
1. **Prompt管理系统** ✅
- 新增 `prompt_templates` 数据库表
- 后台新增"Prompt管理"菜单
- 可管理AI提示词模板（标签生成、功能生成、详细介绍生成）
- 默认初始化3条模板数据
2. **页脚优化** ✅
- 添加ICP备案号：浙ICP备2025154782号-1
- 添加Microsoft Clarity统计代码（ID: uoa2j40sf0）
- 更新版权年份为2025
- 优化页脚链接文字（中文化）
3. **图标优化** ✅
- 详情页：Material Icons → Emoji
- 替换图标：`arrow_back`→`←`, `north_east`→`↗`, `visibility`→`👁`, `calendar_today`→`📅`
- 首页：已使用emoji但有CSS残留（待上传修复文件）
4. **标签显示修复** ✅
- 修复编辑页/创建页标签名称无法显示问题
- 使用正则表达式提取 `<Tag XXX>` 格式中的标签名称
- 修改文件：`templates/admin/site/create.html`, `templates/admin/site/edit.html`
---
## ✅ 已完成的工作
### 代码开发
- [x] 创建 `PromptTemplate` 模型（`models.py`）
- [x] 创建数据库迁移脚本（`migrate_prompts.py`）
- [x] 添加 `PromptAdmin` 管理视图（`app.py`）
- [x] 修复详情页图标（`templates/detail_new.html`）
- [x] 修复标签显示问题（`templates/admin/site/create.html`, `edit.html`）
- [x] 优化页脚（`templates/base_new.html`）
- [x] 完善 `TagGenerator` 类，添加 `generate_description` 方法
### Git管理
- [x] Git提交所有修改（Commit ID: `9f5d006`）
- [x] Git提交信息：`release: v2.1.0 - Prompt管理系统、页脚优化、图标修复`
- [x] 文件统计：23 files changed, 5868 insertions(+), 96 deletions(-)
### 服务器部署
- [x] 配置Git用户信息
- [x] 恢复Git stash
- [x] 提交代码到服务器Git仓库
- [x] 安装新依赖：`markdown`, `pypinyin`, `gunicorn`
- [x] 运行数据库迁移（成功创建 `prompt_templates` 表及3条数据）
- [x] 修复 `manage.sh` 路径配置（`/www/wwwroot/zjpb` → `/opt/1panel/apps/zjpb`）
- [x] 修复gunicorn启动命令（`app:app` → `wsgi:app`）
- [x] 应用成功启动（PID: 20+）
---
## ✅ 已验证功能
1. **页脚ICP备案号** ✅ - 正常显示
2. **Microsoft Clarity统计** ✅ - 已加载
3. **详情页图标** ✅ - 全部为emoji
4. **搜索功能** ✅ - 正常工作
5. **数据库迁移** ✅ - 表和数据创建成功
6. **应用运行状态** ✅ - 服务正常
---
## 🔄 待完成任务
### 1. 上传缺失的文件（重要！）
需要上传以下2个文件到服务器：
**文件1**: `templates/index_new.html`
- **本地路径**: `D:\315mac\Code\zjpb\templates\index_new.html`
- **服务器路径**: `/opt/1panel/apps/zjpb/templates/index_new.html`
- **原因**: 删除Material Icons残留CSS（第259-261行已删除）
- **作用**: 修复首页图标显示问题
**文件2**: `utils/tag_generator.py`
- **本地路径**: `D:\315mac\Code\zjpb\utils\tag_generator.py`
- **服务器路径**: `/opt/1panel/apps/zjpb/utils/tag_generator.py`
- **原因**: 包含完整的 `generate_description` 方法（第150-219行）
- **作用**: 修复AI生成详细介绍报错（'TagGenerator' object has no attribute 'generate_description'）
**上传后执行**:
```bash
cd /opt/1panel/apps/zjpb
./manage.sh restart
```
### 2. 待验证功能
**后台Prompt管理**:
- [ ] 检查后台左侧菜单是否有"Prompt管理"
- [ ] 点击进入，查看是否有3条记录：
- 标签生成 (id: 1)
- 主要功能生成 (id: 2)
- 详细介绍生成 (id: 3)
**标签显示验证**:
- [ ] 后台 → 网站管理 → 编辑任意网站
- [ ] 检查标签区域是否显示蓝色标签带文字
- [ ] 不应该是空白蓝框
**AI功能测试**:
- [ ] 测试"AI生成标签"按钮
- [ ] 测试"AI生成详细介绍"按钮（需要先上传tag_generator.py）
- [ ] 测试"AI生成主要功能"按钮
**首页图标验证**:
- [ ] 清除浏览器缓存（Ctrl+Shift+Delete）
- [ ] 强制刷新首页（Ctrl+F5）
- [ ] 检查首页卡片图标是否为emoji（需要先上传index_new.html）
---
## 📊 数据库变更
### 新增表: `prompt_templates`
```sql
CREATE TABLE prompt_templates (
id INTEGER NOT NULL AUTO_INCREMENT,
`key` VARCHAR(50) NOT NULL COMMENT '唯一标识(tags/features/description)',
name VARCHAR(100) NOT NULL COMMENT '模板名称',
system_prompt TEXT NOT NULL COMMENT '系统提示词',
user_prompt_template TEXT NOT NULL COMMENT '用户提示词模板(支持变量)',
description VARCHAR(200) COMMENT '模板说明',
is_active BOOL COMMENT '是否启用',
created_at DATETIME COMMENT '创建时间',
updated_at DATETIME COMMENT '更新时间',
PRIMARY KEY (id),
UNIQUE (`key`)
)
```
### 已插入的默认数据（3条）
| ID | Key | Name | Description |
|----|-----|------|-------------|
| 1 | tags | 标签生成 | 根据网站名称和描述生成3-5个分类标签 |
| 2 | features | 主要功能生成 | 根据网站名称和描述生成5-8个主要功能点 |
| 3 | description | 详细介绍生成 | 根据网站名称和简短描述生成200-400字的详细介绍 |
---
## 🔧 服务器配置信息
### 基本信息
- **服务器路径**: `/opt/1panel/apps/zjpb`（不是 `/www/wwwroot/zjpb`）
- **Python虚拟环境**: `/opt/1panel/apps/zjpb/venv`
- **Git版本**: 2.43.0
- **Git用户**: `ZJPB Admin <admin@zjpb.net>`
### 已安装的依赖
- Flask==3.0.0
- Flask-SQLAlchemy==3.1.1
- Flask-Admin==1.6.1
- Flask-Login==0.6.3
- pymysql==1.1.0
- python-dotenv==1.0.0
- Werkzeug==3.0.1
- cryptography==41.0.7
- WTForms==2.3.3
- requests==2.31.0
- beautifulsoup4==4.12.2
- Pillow>=10.2.0
- openai>=1.0.0
- **markdown==3.10** (新增)
- **pypinyin==0.51.0** (已有)
- **gunicorn==21.2.0** (已有)
### 应用管理脚本
- **启动**: `./manage.sh start`
- **停止**: `./manage.sh stop`
- **重启**: `./manage.sh restart`
- **状态**: `./manage.sh status`
- **日志**: `./manage.sh logs`
### 配置文件修复记录
1. `manage.sh` - 路径已修复为 `/opt/1panel/apps/zjpb`
2. `gunicorn_config.py` - 路径已修复
3. `deploy.sh` - 路径已修复
4. `manage.sh` - 启动命令已修复为 `wsgi:app`
---
## 📝 Git提交记录
### 最新提交（服务器）
```
Commit: 9f5d006
Author: ZJPB Admin <admin@zjpb.net>
Date: 2025-12-30 01:21:xx
release: v2.1.0 - Prompt管理系统、页脚优化、图标修复
23 files changed, 5868 insertions(+), 96 deletions(-)
新增文件:
- DEPLOYMENT.md
- DEPLOY_CHECKLIST.md
- INCREMENTAL_DEPLOY.md
- QUICK_DEPLOY.md
- deploy.sh
- export_data.py
- git_patch_deploy.sh
- gunicorn_config.py
- manage.sh
- migrate_db.py
- migrate_prompts.py
- nul
- one_click_deploy.sh
- templates/admin/change_password.html
- test_deepseek.py
- v2.1.0.patch
- wsgi.py
```
### 本地提交（待推送）
```
Commit: 30b1ef7
Tag: v2.1.0
release: v2.1.0 - Prompt管理系统、页脚优化、图标修复
新增功能：
- Prompt管理：后台新增Prompt模板管理功能
- 数据库迁移：新增prompt_templates表及默认数据
- 页脚优化：添加ICP备案号和Microsoft Clarity统计
- 图标修复：详情页Material Icons替换为Emoji
- 标签显示：修复编辑页标签名称无法显示的问题
```
---
## 🐛 已知问题
### 1. 首页图标CSS残留
- **状态**: 待修复（需上传文件）
- **文件**: `templates/index_new.html`
- **问题**: 第259-261行有Material Icons CSS残留
- **解决方案**: 已删除，需上传到服务器
### 2. AI生成详细介绍报错
- **状态**: 待修复（需上传文件）
- **文件**: `utils/tag_generator.py`
- **错误**: `'TagGenerator' object has no attribute 'generate_description'`
- **原因**: 服务器版本缺少该方法
- **解决方案**: 上传包含完整方法的文件
### 3. Git Stash残留
- **状态**: 已处理
- **位置**: 服务器还有1个stash备份 `stash@{1}`
- **建议**: 可以保留作为备份，或清理：`git stash clear`
---
## 📂 关键文件清单
### 已修改的文件（本地最新）
1. `app.py` - 新增PromptAdmin视图
2. `models.py` - 新增PromptTemplate模型
3. `migrate_prompts.py` - 数据库迁移脚本
4. `templates/base_new.html` - 页脚优化
5. `templates/detail_new.html` - 图标修复
6. `templates/index_new.html` - 删除CSS残留
7. `templates/admin/site/create.html` - 标签显示修复
8. `templates/admin/site/edit.html` - 标签显示修复
9. `utils/tag_generator.py` - 完整的AI生成方法
10. `requirements.txt` - 依赖清单（未变更，markdown未加入）
### 新增的文件
1. `migrate_prompts.py` - Prompt表迁移脚本
2. `INCREMENTAL_DEPLOY.md` - 增量部署指南
3. `GIT_PATCH_DEPLOY.md` - Git Patch部署指南
4. `MANUAL_DEPLOY.md` - 手动部署指南
5. `CHECK_GIT.md` - Git检查指南
6. `one_click_deploy.sh` - 一键部署脚本
7. `git_patch_deploy.sh` - Git patch部署脚本
8. `quick_deploy_server.sh` - 服务器快速部署脚本
---
## 🚀 下次继续工作的步骤
### 立即执行（5分钟）
1. **上传缺失文件**（使用1Panel文件管理器）:
```
本地 → 服务器
D:\315mac\Code\zjpb\templates\index_new.html
→ /opt/1panel/apps/zjpb/templates/index_new.html
D:\315mac\Code\zjpb\utils\tag_generator.py
→ /opt/1panel/apps/zjpb/utils/tag_generator.py
```
2. **重启应用**（SSH或1Panel终端）:
```bash
cd /opt/1panel/apps/zjpb
./manage.sh restart
./manage.sh status
```
3. **清除浏览器缓存** (Ctrl+Shift+Delete 或 Ctrl+F5)
### 验证功能（5分钟）
1. **验证Prompt管理**:
- 登录 `/admin/login`
- 检查"Prompt管理"菜单
- 查看3条记录
2. **验证标签显示**:
- 后台 → 网站管理 → 编辑
- 检查标签是否显示名称
3. **验证AI功能**:
- 测试3个AI生成按钮
- 确保都能正常工作
4. **验证首页图标**:
- 刷新首页
- 检查所有图标是否为emoji
### 可选优化（未来）
- [ ] 将 `markdown` 添加到 `requirements.txt`
- [ ] 清理服务器上的临时文件（`nul`, `test_deepseek.py`, `*.patch`）
- [ ] 配置Git远程仓库（GitHub/Gitee）用于版本管理
- [ ] 优化gunicorn配置（worker数量、超时时间等）
- [ ] 设置应用自动启动（systemd service）
---
## 💡 技术要点记录
### Git Stash恢复
```bash
git stash list # 查看stash列表
git stash pop # 恢复最新stash
git stash apply # 恢复但不删除stash
git stash clear # 清除所有stash
```
### 正则表达式提取标签
```javascript
// 从 <Tag XXX> 格式提取标签名称
const match = tagText.match(/<Tag\s+(.+?)>/);
if (match) {
tagText = match[1]; // 提取 "XXX"
}
```
### Flask-Admin模型repr格式
```python
# Tag模型的__repr__返回
def __repr__(self):
return f'<Tag {self.name}>'
# 在Flask-Admin select中显示为：<Tag 图像生成>
# 需要JavaScript提取实际标签名
```
### Gunicorn启动配置
```python
# wsgi.py - 正确的应用入口
from app import create_app
app = create_app(os.getenv('FLASK_ENV', 'production'))
# manage.sh - 正确的启动命令
gunicorn -c gunicorn_config.py wsgi:app
```
---
## 📞 联系信息
- **项目名称**: ZJPB - 焦提示词 | AI工具导航
- **ICP备案号**: 浙ICP备2025154782号-1
- **统计代码**: Microsoft Clarity (ID: uoa2j40sf0)
- **数据库**: ai_nav @ 112.124.42.38 (MySQL)
- **服务器路径**: /opt/1panel/apps/zjpb
---
## 📚 相关文档
- `INCREMENTAL_DEPLOY.md` - 增量部署完整指南
- `GIT_PATCH_DEPLOY.md` - Git Patch部署方案
- `MANUAL_DEPLOY.md` - 手动上传部署方案
- `CHECK_GIT.md` - Git环境检查指南
- `DEPLOYMENT.md` - 通用部署文档
- `QUICK_DEPLOY.md` - 1Panel快速部署
---
## ✅ 部署完成度
**总体进度**: 90%
| 任务 | 状态 |
|------|------|
| 代码开发 | ✅ 100% |
| Git提交 | ✅ 100% |
| 服务器配置 | ✅ 100% |
| 数据库迁移 | ✅ 100% |
| 应用启动 | ✅ 100% |
| 文件上传 | ⏳ 80% (缺2个文件) |
| 功能验证 | ⏳ 60% (部分已验证) |
**预计剩余时间**: 10分钟（上传文件+验证）
---
**最后更新**: 2025-01-30 01:30
**下次继续**: 上传2个文件 → 重启应用 → 验证功能 → 完成部署 🎉