🎯 BiliFanTrack - B站粉丝数实时监控系统

一个基于 Node.js + Vue 3 + WebSocket 的现代化实时监控应用，用于实时获取并展示 Bilibili 用户粉丝数量变化。

功能特性 • 快速开始 • API 文档 • 项目结构

---

✨ 功能特性

🎨 核心功能

• 📊 实时监控 - 自动获取并实时显示 Bilibili 用户粉丝数量变化
• 🔄 WebSocket 推送 - 基于 WebSocket 实现毫秒级实时数据推送
• 📁 本地存储 - 使用 JSON 文件存储历史数据（最多保留50条记录）
• 📈 趋势图表 - 使用 ECharts 绘制精美的粉丝数变化趋势图（可切换显示/隐藏）
• ✨ 动画效果 - 平滑的数字滚动动画，粉丝减少时的震动提示效果

🎯 界面特性

• 🎨 现代化 UI - 采用毛玻璃效果（Glassmorphism）设计风格
• 🌈 渐变主题 - 哔哩哔哩风格的蓝粉渐变配色方案
• 📱 响应式设计 - 完美适配桌面端、平板和移动设备
• 🎭 交互动画 - 丰富的悬停效果和过渡动画

⚡ 性能优化

• 💾 内存缓存 - 智能缓存机制减少 I/O 操作
• 🔄 批量写入 - 延迟批量写入数据库，提升性能
• 📡 智能 API 调用 - 自适应 API 调用间隔，失败时自动增加间隔
• 💓 心跳机制 - WebSocket 心跳保活，自动清理断开的连接
• 🔄 自动重连 - 前端 WebSocket 断开时自动重连（指数退避策略）

🛠️ 技术栈

后端技术

• 运行环境: Node.js 18+
• Web 框架: Express 4.x
• 实时通信: WebSocket (ws)
• HTTP 客户端: Axios
• 数据存储: JSON 文件（异步 I/O）
• 配置管理: dotenv
• 跨域处理: CORS

前端技术

• 框架: Vue 3 (Composition API)
• 构建工具: Vite 4.x
• 数字动画: CountUp.js
• 数据可视化: ECharts 5.x
• 样式: 原生 CSS（CSS Variables）

🚀 快速开始

前置要求

• Node.js 18.0 或更高版本
• npm 或 yarn 包管理器
• 至少 500MB 可用存储空间

安装步骤

1️⃣ 克隆项目

git clone <repository-url>
cd BiliFanTrack

2️⃣ 安装依赖

# 安装后端依赖
cd backend
npm install

# 安装前端依赖
cd ../frontend
npm install

3️⃣ 配置环境变量

在 backend 目录下创建 .env 文件：

# Bilibili 用户 ID（必需）
BILIBILI_UID=你的B站用户ID

# 服务器端口（可选，默认 3000）
PORT=3000

💡 提示: 获取用户 ID 的方法：

1. 访问用户的 Bilibili 主页
2. 查看 URL，例如：https://space.bilibili.com/123456789
3. 最后的数字就是用户 ID：123456789

4️⃣ 启动项目

方式一：开发模式（推荐）

# 终端 1: 启动后端服务
cd backend
npm start
# 或
node server.js

# 终端 2: 启动前端开发服务器
cd frontend
npm run dev

方式二：生产模式

# 1. 构建前端
cd frontend
npm run build

# 2. 将构建文件复制到后端 public 目录（Windows）
# Windows PowerShell:
cd ..
New-Item -ItemType Directory -Force -Path backend\public
Copy-Item -Recurse frontend\dist\* backend\public\

# Linux/Mac:
mkdir -p backend/public
cp -r frontend/dist/* backend/public/

# 3. 启动后端（同时提供静态文件服务）
cd backend
npm start

5️⃣ 访问应用

• 开发模式: http://localhost:5173
• 生产模式: http://localhost:3000

📦 生产环境部署

使用 PM2（推荐）

# 安装 PM2
npm install -g pm2

# 构建前端
cd frontend
npm run build

# 复制构建文件到后端
cd ..
mkdir -p backend/public
cp -r frontend/dist/* backend/public/

# 使用 PM2 启动后端服务
cd backend
pm2 start server.js --name BiliFanTrack

# 查看日志
pm2 logs BiliFanTrack

# 设置开机自启
pm2 startup
pm2 save

使用 Docker（可选）

# Dockerfile 示例
FROM node:18-alpine

WORKDIR /app

# 复制后端文件
COPY backend/package*.json ./
RUN npm install --production

COPY backend/ ./

# 复制前端构建文件
COPY backend/public ./public

EXPOSE 3000

CMD ["node", "server.js"]

环境变量配置

在生产环境中，建议使用环境变量或配置文件：

BILIBILI_UID=你的用户ID
PORT=3000
NODE_ENV=production

📁 项目结构

BiliFanTrack/
├── backend/                    # 后端服务目录
│   ├── server.js               # Express + WebSocket 主服务文件
│   ├── db.json                 # 数据存储文件（自动生成）
│   ├── package.json            # 后端依赖配置
│   ├── .env                    # 环境变量配置（需手动创建）
│   └── public/                 # 生产环境静态文件目录
│       └── ...                 # 前端构建后的文件
│
├── frontend/                    # 前端应用目录
│   ├── src/
│   │   ├── App.vue             # 主组件（包含所有UI逻辑）
│   │   ├── main.js             # 应用入口文件
│   │   └── style.css           # 全局样式文件
│   ├── index.html              # HTML 模板
│   ├── vite.config.js          # Vite 构建配置
│   ├── package.json            # 前端依赖配置
│   └── dist/                   # 构建输出目录（npm run build 后生成）
│
└── README.md                   # 项目说明文档

📡 API 接口

WebSocket 连接

端点: ws://localhost:3000

消息格式:

// 服务器推送消息
{
  "type": "fans_update",
  "fans": 12345,              // 当前粉丝数
  "previous": 12340,          // 之前的粉丝数
  "timestamp": "2024-01-01T12:00:00.000Z",  // ISO 时间戳
  "diff": 5                   // 变化量（正数为增加，负数为减少）
}

// 心跳消息（服务器 → 客户端）
{
  "type": "ping"
}

// 心跳响应（客户端 → 服务器）
{
  "type": "pong"
}

RESTful API

获取当前粉丝数

GET /api/current

响应示例:

{
  "success": true,
  "data": {
    "fans": 12345,
    "timestamp": "2024-01-01T12:00:00.000Z"
  }
}

获取历史粉丝数

GET /api/history

响应示例:

{
  "success": true,
  "count": 50,
  "data": [
    {
      "fans": 12345,
      "timestamp": "2024-01-01T12:00:00.000Z"
    },
    // ... 更多历史记录
  ]
}

获取服务器状态

GET /api/status

响应示例:

{
  "success": true,
  "timestamp": "2024-01-01T12:00:00.000Z",
  "connected_clients": 3,
  "bilibili_uid": "123456789",
  "last_update": "2024-01-01T11:59:50.000Z"
}

获取 Bilibili 用户信息（代理）

GET /api/bilibili/userinfo?mid=用户ID

响应示例:

{
  "success": true,
  "data": {
    "code": 0,
    "data": {
      "card": {
        "name": "用户名",
        "fans": 12345,
        // ... 其他用户信息
      }
    }
  }
}

🔧 开发说明

工作原理

1. 数据获取

   • 后端使用智能调度机制，初始间隔 5 秒
   • API 调用成功时缩短间隔，失败时增加间隔（5-30秒自适应）
   • 使用重试机制（最多3次）确保数据获取的可靠性

2. 实时推送

   • 当粉丝数发生变化时，通过 WebSocket 广播给所有连接的客户端
   • 使用心跳机制（30秒间隔）保持连接活跃
   • 自动清理断开的客户端连接

3. 数据存储

   • 历史数据保存在 backend/db.json 中
   • 使用延迟批量写入机制（5秒延迟），减少 I/O 操作
   • 最多保留 50 条历史记录

4. 前端动画

   • 使用 CountUp.js 实现平滑的数字滚动动画
   • 粉丝减少时显示震动效果和警告提示
   • 变化量实时显示，3秒后自动消失

5. 趋势图表

   • 使用 ECharts 绘制粉丝数变化趋势图
   • 支持切换显示/隐藏
   • 实时更新图表数据

性能优化特性

• ✅ 内存缓存: 减少数据库读写操作
• ✅ 批量写入: 延迟批量写入，提升 I/O 性能
• ✅ 智能 API 调用: 根据成功/失败情况动态调整调用间隔
• ✅ 异步处理: 所有 I/O 操作均为异步，不阻塞主线程
• ✅ 连接管理: 自动清理断开的 WebSocket 连接
• ✅ 优雅关闭: 服务器关闭时保存数据，关闭所有连接

自定义配置

可以在 backend/server.js 中修改以下配置：

const CACHE_CONFIG = {
  writeDelay: 5000,        // 数据库写入延迟（毫秒）
  maxBatchSize: 10,        // 最大批处理记录数
  apiTimeout: 5000,        // API 请求超时时间（毫秒）
  heartbeatInterval: 30000, // WebSocket 心跳间隔（毫秒）
  minApiInterval: 5000,    // 最小 API 调用间隔（毫秒）
  maxApiInterval: 30000,   // 最大 API 调用间隔（毫秒）
  reconnectAttempts: 3,    // API 请求失败重连次数
};

故障排查

问题：WebSocket 连接失败

• 检查后端服务是否正常启动
• 确认防火墙未阻止 3000 端口
• 查看浏览器控制台错误信息

问题：无法获取粉丝数

• 检查 .env 文件中的 BILIBILI_UID 是否正确
• 确认网络连接正常，可以访问 Bilibili API
• 查看后端控制台日志

问题：数据未保存

• 检查 backend 目录是否有写入权限
• 查看后端日志中的错误信息
• 确认 db.json 文件格式正确

📝 更新日志

v1.1.0（当前版本）

• ✨ 新增历史趋势图表功能（ECharts）
• 🎨 优化 UI 界面，增强视觉效果
• 📊 改进日志系统，添加时间戳和日志级别
• ⚡ 优化后端代码结构，增强错误处理
• 🔄 改进 WebSocket 连接管理和心跳机制
• 📱 优化响应式设计，提升移动端体验

v1.0.0

• 🎉 初始版本发布
• 📊 实时粉丝数监控
• 🔄 WebSocket 实时推送
• 💾 本地数据存储
• ✨ 平滑动画效果

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License

---

Made with ❤️ for Bilibili Fans

如果这个项目对你有帮助，请给一个 ⭐ Star！