feat: implement comprehensive reading analytics system with bot detection
Features: - Add article view tracking with automatic deduplication (per user/IP) - Implement intelligent bot detection (35+ patterns: Google, Bing, Baidu, GPTBot, etc) - Create admin analytics dashboard with statistics and filtering - Display view count and comment count on article cards - Add search-based article filter (replaced dropdown for scalability) Analytics Dashboard: - Global stats: total views, human/bot views, unique IPs/users - Top 20 articles ranking with detailed metrics - Detailed view records with time, article, user, IP, user-agent - Filters: article title search, IP search, show/hide bots - Pagination support (50 records per page) Technical Implementation: - Async view recording (non-blocking) - Dual deduplication (application + database layer) - Database indexes for performance optimization - Batch query for comment counts - Full i18n support (Chinese/English) Files Added: - models/article_view.go: View tracking model - models/bot_detector.go: Bot detection logic - handlers/admin_analytics.go: Analytics page handler - templates/admin/analytics_views.html: Analytics UI - test_analytics.sh: Testing script - Documentation: implementation guide, usage guide, changelog Files Modified: - handlers/home.go: Add view recording and comment count queries - models/db.go: Add ArticleView to auto-migration - main.go: Add analytics routes - i18n/i18n.go: Add 35+ translation keys - templates/admin/dashboard.html: Add analytics entry link - templates/pages/home.html: Display view/comment counts on cards Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Claude Fable 5
@@ -0,0 +1,242 @@
|
||||
# 阅读统计系统 - 快速使用指南
|
||||
|
||||
## 🚀 立即开始
|
||||
|
||||
### 1. 启动应用
|
||||
```bash
|
||||
./go_blog
|
||||
```
|
||||
|
||||
首次启动会自动创建 `article_views` 数据库表。
|
||||
|
||||
### 2. 访问统计页面
|
||||
1. 浏览器打开：http://localhost:8080/login
|
||||
2. 登录（默认账号）：`admin` / `admin`
|
||||
3. 进入后台，点击 **"阅读统计"** 按钮
|
||||
4. 或直接访问：http://localhost:8080/admin/analytics/views
|
||||
|
||||
## 📊 功能说明
|
||||
|
||||
### 全局统计（顶部卡片）
|
||||
- **总阅读量**：所有访问记录数
|
||||
- **真人阅读**：排除爬虫的真实用户访问
|
||||
- **爬虫访问**：被识别为爬虫的访问数
|
||||
- **独立IP**：访问过的不同IP地址数量
|
||||
- **独立用户**：已登录用户的数量
|
||||
|
||||
### 文章排行榜
|
||||
- 显示阅读量最高的前20篇文章
|
||||
- 每篇显示：总阅读、真人阅读、爬虫访问、独立IP
|
||||
|
||||
### 详细访问记录
|
||||
每条记录显示：
|
||||
- **时间**：访问时间（精确到分钟）
|
||||
- **文章**：文章标题（可点击跳转）
|
||||
- **用户**：登录用户名或"匿名用户"
|
||||
- **IP地址**：访客IP
|
||||
- **User-Agent**：浏览器信息
|
||||
- **类型**：👤真人 或 🤖爬虫（橙色高亮）
|
||||
|
||||
### 筛选功能
|
||||
- **按文章筛选**：下拉选择特定文章
|
||||
- **按IP筛选**：输入IP地址（支持部分匹配）
|
||||
- **显示爬虫**：勾选后包含爬虫流量
|
||||
|
||||
## 🤖 爬虫识别
|
||||
|
||||
系统自动识别以下类型的爬虫：
|
||||
|
||||
### 搜索引擎
|
||||
- Google (Googlebot)
|
||||
- Bing (Bingbot)
|
||||
- Baidu (Baiduspider)
|
||||
- Yandex (Yandexbot)
|
||||
- DuckDuckGo (Duckduckbot)
|
||||
|
||||
### 社交媒体
|
||||
- Facebook (Facebookexternalhit, Facebot)
|
||||
- Twitter (Twitterbot)
|
||||
- LinkedIn (Linkedinbot)
|
||||
- Telegram
|
||||
- WhatsApp
|
||||
|
||||
### AI爬虫
|
||||
- GPTBot (OpenAI)
|
||||
- ClaudeBot (Anthropic)
|
||||
- 字节跳动 (Bytespider)
|
||||
|
||||
### SEO工具
|
||||
- Ahrefs
|
||||
- SEMrush
|
||||
- Moz (Dotbot)
|
||||
- Dataforseo
|
||||
|
||||
### 其他
|
||||
- 无头浏览器 (Headless, Phantom, Puppeteer, Selenium)
|
||||
- 网页归档 (Archive.org_bot)
|
||||
|
||||
## 🎯 测试统计功能
|
||||
|
||||
### 方法1：运行测试脚本
|
||||
```bash
|
||||
./test_analytics.sh
|
||||
```
|
||||
|
||||
该脚本会：
|
||||
- 检查应用状态
|
||||
- 模拟不同User-Agent的访问
|
||||
- 生成测试数据
|
||||
- 验证数据库记录
|
||||
|
||||
### 方法2：手动测试
|
||||
1. 访问几篇已发布的文章
|
||||
2. 刷新页面（不会重复计数）
|
||||
3. 使用不同浏览器访问（会记录为不同IP）
|
||||
4. 查看后台统计
|
||||
|
||||
### 方法3：用curl模拟爬虫
|
||||
```bash
|
||||
# 模拟GoogleBot
|
||||
curl -H "User-Agent: Googlebot/2.1" http://localhost:8080/article/your-article-slug
|
||||
|
||||
# 模拟BingBot
|
||||
curl -H "User-Agent: bingbot/2.0" http://localhost:8080/article/your-article-slug
|
||||
|
||||
# 正常浏览器
|
||||
curl -H "User-Agent: Mozilla/5.0 (Macintosh)" http://localhost:8080/article/your-article-slug
|
||||
```
|
||||
|
||||
## ✨ 核心特性
|
||||
|
||||
### 自动去重
|
||||
- 同一IP+用户组合只记录一次
|
||||
- 刷新页面不会重复计数
|
||||
- 双重保护：应用层+数据库层
|
||||
|
||||
### 异步记录
|
||||
- 不阻塞页面加载
|
||||
- 后台goroutine处理
|
||||
- 即使记录失败也不影响用户体验
|
||||
|
||||
### 性能优化
|
||||
- 数据库索引优化
|
||||
- 分页加载（50条/页）
|
||||
- 异步处理
|
||||
|
||||
### 国际化
|
||||
- 完整中英文支持
|
||||
- 自动语言切换
|
||||
|
||||
## 📁 相关文件
|
||||
|
||||
### 新建文件
|
||||
- `models/article_view.go` - 数据模型
|
||||
- `models/bot_detector.go` - 爬虫检测
|
||||
- `handlers/admin_analytics.go` - 统计handler
|
||||
- `templates/admin/analytics_views.html` - 统计页面
|
||||
- `test_analytics.sh` - 测试脚本
|
||||
|
||||
### 修改文件
|
||||
- `handlers/home.go` - 添加记录逻辑
|
||||
- `models/db.go` - 数据库迁移
|
||||
- `main.go` - 路由配置
|
||||
- `i18n/i18n.go` - 翻译
|
||||
- `templates/admin/dashboard.html` - 入口链接
|
||||
|
||||
## 🔧 高级配置
|
||||
|
||||
### 查询数据库（SQLite）
|
||||
```bash
|
||||
sqlite3 tmp/blog.db
|
||||
|
||||
# 查看所有访问记录
|
||||
SELECT * FROM article_views ORDER BY created_at DESC LIMIT 10;
|
||||
|
||||
# 统计真人和爬虫访问
|
||||
SELECT is_bot, COUNT(*) FROM article_views GROUP BY is_bot;
|
||||
|
||||
# 查看独立IP数
|
||||
SELECT COUNT(DISTINCT ip) FROM article_views;
|
||||
|
||||
# 某篇文章的访问统计
|
||||
SELECT COUNT(*) FROM article_views WHERE article_id = 1;
|
||||
```
|
||||
|
||||
### 清空统计数据
|
||||
```bash
|
||||
sqlite3 tmp/blog.db "DELETE FROM article_views;"
|
||||
```
|
||||
|
||||
## 💡 使用建议
|
||||
|
||||
### 日常使用
|
||||
1. **定期查看**：每周查看一次统计数据
|
||||
2. **关注真人阅读**：爬虫访问仅供参考
|
||||
3. **分析热门文章**：根据排行榜优化内容
|
||||
4. **识别可疑IP**：发现异常流量
|
||||
|
||||
### 数据维护
|
||||
1. **定期备份**：备份数据库文件
|
||||
2. **归档旧数据**：超过6个月的数据可以归档
|
||||
3. **监控存储**：注意数据库大小
|
||||
|
||||
### 隐私保护
|
||||
- IP地址完整记录，考虑是否需要脱敏
|
||||
- User-Agent信息敏感，注意保护
|
||||
- 遵守当地隐私法规（如GDPR）
|
||||
|
||||
## 🐛 故障排查
|
||||
|
||||
### 问题1：看不到访问记录
|
||||
**原因**：可能还没有人访问文章
|
||||
**解决**：访问几篇已发布的文章，等待几秒后刷新统计页面
|
||||
|
||||
### 问题2：统计页面显示0
|
||||
**原因**：
|
||||
- 数据库迁移未执行
|
||||
- article_views表不存在
|
||||
|
||||
**解决**：
|
||||
```bash
|
||||
# 停止应用
|
||||
pkill go_blog
|
||||
|
||||
# 重新启动（会自动迁移）
|
||||
./go_blog
|
||||
```
|
||||
|
||||
### 问题3：所有访问都被标记为爬虫
|
||||
**原因**：curl或工具的User-Agent被识别为爬虫
|
||||
**解决**：使用真实浏览器访问
|
||||
|
||||
### 问题4：访问页面返回404
|
||||
**原因**：路由未正确配置
|
||||
**检查**：
|
||||
```bash
|
||||
# 查看路由列表
|
||||
grep "analytics/views" main.go
|
||||
```
|
||||
|
||||
## 📈 未来扩展
|
||||
|
||||
可以考虑添加的功能：
|
||||
1. 📊 图表可视化（访问趋势图）
|
||||
2. 🌍 地理位置分析（IP定位）
|
||||
3. 📱 设备统计（移动端/桌面端）
|
||||
4. ⏰ 访问时段分析（热门时间）
|
||||
5. 📊 导出功能（CSV/Excel）
|
||||
6. 🔔 实时监控（WebSocket）
|
||||
7. 📧 定期报告（邮件通知）
|
||||
|
||||
## 📞 支持
|
||||
|
||||
遇到问题？
|
||||
1. 查看 `ANALYTICS_IMPLEMENTATION.md` 详细文档
|
||||
2. 检查应用日志
|
||||
3. 运行测试脚本 `./test_analytics.sh`
|
||||
|
||||
---
|
||||
|
||||
**就这么简单！** 🎉
|
||||
|
||||
现在你的博客已经拥有了专业的阅读统计系统，可以深入了解读者行为，优化内容策略！
|
||||
Reference in New Issue
Block a user