@kenny_zx/websocket-version-checker

v1.1.2

Published

2 months ago

基于WebSocket的实时版本更新检查和通知系统，支持Vue 2/3和原生JavaScript

0High
0Medium
0Low

kenny_zx

websocket version-checker update-notification realtime vue element-ui socket.io

WebSocket Version Checker

基于WebSocket的实时版本更新检查和通知系统，支持Vue 2/3和原生JavaScript。

✨ 特性

🚀 实时推送 - 基于WebSocket，版本更新延迟<1秒
📦 低资源消耗 - 降低98%的请求量和带宽
🔄 自动重连 - 网络断开自动恢复
💓 心跳检测 - 保持连接活性
🎯 多环境支持 - 区分开发/UAT/生产环境
🛠️ 框架无关 - 支持Vue 2/3、React、原生JS
📱 跨平台 - 浏览器、桌面应用、移动端

📦 安装

npm install @kenny_zx/websocket-version-checker socket.io-client

🚀 快速开始

Vue 2 + Element UI

// main.js
import Vue from 'vue'
import ElementUI from 'element-ui'
import { createVue2Plugin } from '@kenny_zx/websocket-version-checker'
import io from 'socket.io-client'

Vue.use(ElementUI)

// 安装版本检查插件
Vue.use(createVue2Plugin({
  websocketUrl: 'http://127.0.0.1:13481',
  systemName: '您的系统名称'
}))

// App.vue
export default {
  mounted() {
    // 连接并开始监听
    this.$versionChecker.connect(io)
  },
  beforeDestroy() {
    // 断开连接
    this.$versionChecker.disconnect()
  }
}

原生JavaScript

import { WebSocketVersionChecker } from '@kenny_zx/websocket-version-checker'
import io from 'socket.io-client'

// 创建检查器
const checker = new WebSocketVersionChecker({
  websocketUrl: 'http://127.0.0.1:13481',
  systemName: '您的系统名称'
}, (versionData, isFirstRun, checkerInstance) => {
  // 自定义通知处理
  console.log('收到版本更新:', versionData)
  
  if (versionData.status === 'package_uploaded') {
    alert(`包上传成功！\n下载地址：${versionData.download_url}`)
  } else {
    if (confirm(`发现新版本 ${versionData.version_number}，是否立即更新？`)) {
      checkerInstance.setLocalVersion(versionData.version_number)
      window.location.reload()
    }
  }
})

// 连接
checker.connect(io)

📖 API文档

WebSocketVersionChecker

构造函数

new WebSocketVersionChecker(config, notificationHandler)

参数：

config (Object) - 配置对象
- websocketUrl (String) - WebSocket服务器地址，默认 http://127.0.0.1:13481
- systemName (String) - 系统名称，默认 系统名称
- heartbeatInterval (Number) - 心跳间隔（毫秒），默认 30000
- maxFailCount (Number) - 最大失败次数，默认 3
- localVersionKey (String) - 本地版本存储键，默认 system_version_number
- ignoredVersionKey (String) - 忽略版本存储键，默认 system_ignored_version
notificationHandler (Function) - 自定义通知处理器
- 参数1: versionData - 版本数据对象
- 参数2: isFirstRun - 是否首次运行
- 参数3: checkerInstance - 检查器实例

方法

connect(io)

连接到WebSocket服务器
参数：io - Socket.IO客户端实例

disconnect()

断开WebSocket连接

reconnect(io)

重新连接WebSocket服务器
参数：io - Socket.IO客户端实例

subscribe()

订阅版本更新

unsubscribe()

取消订阅版本更新

getLocalVersion()

获取本地保存的版本号
返回：String

setLocalVersion(version)

保存版本号到本地
参数：version - 版本号字符串

getIgnoredVersion()

获取被忽略的版本号
返回：String

setIgnoredVersion(version)

保存忽略的版本号
参数：version - 版本号字符串

clearIgnoredVersion()

清除忽略的版本号

compareVersion(newVersion, oldVersion)

比较版本号大小
返回：Boolean - 新版本是否大于旧版本

🎯 使用场景

场景1: 开发环境直接部署

// 后端创建版本记录
{
  systemName: '您的系统',
  versionNumber: 'v2026.0128.1530',
  versionName: '开发环境部署',
  status: 'released',  // ← 实际部署
  // ...
}

// 前端收到推送，显示"发现新版本"通知
// 用户点击"立即更新"，页面自动刷新

场景2: UAT/生产环境包上传

// 后端创建版本记录
{
  systemName: '您的系统',
  versionNumber: 'v2026.0128.1747',
  versionName: 'UAT环境包上传',
  status: 'package_uploaded',  // ← 包上传
  downloadUrl: 'http://example.com/dist.zip'
}

// 前端收到推送，显示"包上传成功"通知
// 显示下载地址，用户点击"我知道了"关闭

🔄 版本数据格式

{
  version_number: 'v2026.0128.1530',     // 版本号
  version_name: '测试环境部署',          // 版本名称
  description: '部署到测试服务器',        // 描述
  release_notes: '1. feat: xxx\n2. fix: xxx',  // 发布说明
  release_by: '张三',                    // 发布人
  status: 'released',                    // 状态: released | package_uploaded
  download_url: 'http://...',            // 下载地址（可选）
  release_date: '2026-01-28T15:30:00'   // 发布时间
}

🎨 自定义通知UI

Element UI样式

import { Notification } from 'element-ui'

const notificationHandler = (versionData, isFirstRun, checker) => {
  if (isFirstRun) {
    Notification.info({
      title: '当前系统版本',
      message: `版本号：${versionData.version_number}`
    })
  } else {
    Notification.warning({
      title: '发现新版本',
      message: `版本号：${versionData.version_number}`
    })
  }
}

const checker = new WebSocketVersionChecker(config, notificationHandler)

原生浏览器通知

const notificationHandler = (versionData, isFirstRun, checker) => {
  if (Notification.permission === 'granted') {
    new Notification('发现新版本', {
      body: `版本号：${versionData.version_number}`,
      icon: '/favicon.ico'
    })
  }
}

🧪 完整示例

查看 examples/ 目录：

vue2-element-ui/ - Vue 2 + Element UI完整示例
vue3-element-plus/ - Vue 3 + Element Plus示例
vanilla-js/ - 原生JavaScript示例
react/ - React示例

🔧 后端集成

Egg.js + Socket.IO

// app/io/controller/versionController.js
async subscribe() {
  const { ctx } = this
  const { systemName } = ctx.args[0] || {}
  
  const room = systemName ? `version:${systemName}` : 'version:all'
  await ctx.socket.join(room)
  
  // 发送当前版本
  const latestVersion = await ctx.service.systemVersion.getLatestVersion(systemName)
  ctx.socket.emit('version:current', {
    code: 200,
    data: latestVersion
  })
}

// 创建版本后推送
async createVersion() {
  const result = await service.systemVersion.createVersion(versionData)
  
  // WebSocket推送
  app.io.of('/').to(`version:${systemName}`).emit('version:update', {
    code: 200,
    data: result
  })
}

📊 性能优势

| 指标 | 轮询方式 | WebSocket方式 | 提升 | |-----|---------|--------------|------| | 延迟 | 10-30秒 | <1秒 | 30倍 | | 请求量 | 120次/小时 | 2次/小时 | 降低98% | | 带宽 | 360KB/小时 | 6KB/小时 | 降低98% |

🐛 故障排查

问题1: 连接失败

检查：

curl http://127.0.0.1:13481

解决：

确保后端服务正在运行
检查防火墙设置
验证WebSocket端口可访问

问题2: 收不到推送