GameServerManager/docs/网络检测功能说明.md

网络检测功能说明

功能概述

网络检测模块用于检测 GSManager 面板所依赖的各类在线服务的连接状态，帮助用户快速诊断网络问题。该模块集成在首页中，支持一键检测所有服务或单独检测特定服务。

功能特性

1. 检测方式

• TCP Ping：通过建立 TCP 连接测试服务可达性
• HTTP/HTTPS Ping：通过 HTTP 请求测试 Web 服务可用性
• 超时设置：默认超时时间为 10 秒
• 响应时间显示：显示每个服务的响应延迟

2. 检测范围

互联网连接

• 百度（www.baidu.com）
  • 用途：验证外网连接状态
  • 影响：无法对外请求时，Steam 游戏等需要联网的服务端会受影响

Steam 网络

• Steamworks API（全球）（api.steampowered.com）

  • 用途：Steam 游戏服务端联网功能
  • 影响：无法连接时，Steam 游戏服务端可能无法被搜索或通过 Steam 网络连接

• Steamworks API（合作/私有）（partner.steam-api.com）

  • 用途：Steam 合作伙伴 API
  • 影响：同上

Modrinth

• Modrinth API（api.modrinth.com）

  • 用途：搜索 Minecraft 整合包
  • 影响：无法搜索 MC 整合包

• Modrinth CDN（cdn.modrinth.com）

  • 用途：下载 Minecraft 整合包
  • 影响：无法下载 MC 整合包

Minecraft

• Mojang 会话服务器（sessionserver.mojang.com）

  • 用途：正版验证
  • 影响：正版玩家可能无法进服

• MSL API（https://api.mslmc.cn/v3）

  • 用途：部署 MC 核心
  • 影响：无法部署 MC 核心

GSManager

• GSManager 在线部署服务（http://gsm.server.xiaozhuhouses.asia:10002/）

  • 用途：在线部署和赞助者密钥功能
  • 影响：无法使用在线部署和赞助者密钥功能

• GSManager 镜像服务器（http://download.server.xiaozhuhouses.asia:8082/）

  • 用途：环境管理中的加速下载
  • 影响：无法使用加速下载功能

3. UI 功能

网络状态横幅

• 全部正常：显示绿色横幅提示"网络正常且无阻，您可以畅快使用GSManager中所有在线服务"
• 部分异常：显示黄色横幅提示"部分网络服务连接异常，可能影响相关功能的使用"
• 可关闭：用户可以点击关闭横幅

检测按钮

• 检测所有：一键检测所有网络服务

  • 检测中显示转圈加载图标
  • 所有项目同时显示检测中状态

• 单项检测：点击每个项目右侧的"检测"按钮

  • 仅检测当前项目
  • 检测中显示转圈加载图标

分类显示

• 可折叠设计：每个分类可以展开/折叠
• 分类状态图标：
  • 🔵 检测中：转圈加载图标
  • ✅ 全部成功：绿色对勾
  • ❌ 存在失败：红色叉号
  • ⚠️ 未检测：灰色提示图标
• 统计显示：显示每个分类的成功数量/总数

项目状态

• 状态图标：
  • 🔵 checking：蓝色转圈加载
  • ✅ success：绿色对勾
  • ❌ failed：红色叉号
  • ⚠️ pending：灰色提示图标
• 响应时间：成功时显示响应延迟（ms）
• 错误提示：失败时悬停显示详细错误信息

4. 自动检测

• 首次加载：用户进入首页时自动执行一次全面检测
• 手动检测：其他时候需要用户主动点击检测按钮

技术实现

前端实现

1. 类型定义（client/src/types/index.ts）

// 网络检测项
export interface NetworkCheckItem {
  id: string
  name: string
  url: string
  status: 'pending' | 'checking' | 'success' | 'failed'
  responseTime?: number
  errorMessage?: string
  lastCheckTime?: string
}

// 网络检测分类
export interface NetworkCheckCategory {
  id: string
  name: string
  items: NetworkCheckItem[]
}

// 网络检测状态管理
export interface NetworkCheckState {
  categories: NetworkCheckCategory[]
  allChecksComplete: boolean
  allChecksPassed: boolean
  checking: boolean
  lastCheckTime?: string
  
  checkAll: () => Promise<void>
  checkSingle: (categoryId: string, itemId: string) => Promise<void>
  reset: () => void
}

2. 状态管理（client/src/stores/networkCheckStore.ts）

使用 Zustand 进行状态管理，主要方法：

• checkAll()：检测所有项目

  • 立即将所有项目状态设为 checking
  • 调用 API 进行批量检测
  • 更新所有项目的检测结果

• checkSingle(categoryId, itemId)：检测单个项目

  • 将指定项目状态设为 checking
  • 调用 API 进行单项检测
  • 更新该项目的检测结果

• reset()：重置所有检测状态

3. API 客户端（client/src/utils/api.ts）

// 检测所有网络服务
async checkNetwork() {
  return this.get('/network/check-all')
}

// 检测单个网络服务
async checkSingleNetwork(url: string) {
  return this.post('/network/check-single', { url })
}

4. UI 组件（client/src/components/NetworkCheck.tsx）

组件功能：

• 网络状态横幅显示
• 检测按钮（全部/单项）
• 分类折叠展开
• 状态图标动态显示
• 响应时间格式化
• 错误提示悬浮显示

后端实现

1. 路由注册（server/src/index.ts）

import networkRouter from './routes/network.js'

app.use('/api/network', networkRouter)

2. 检测路由（server/src/routes/network.ts）

主要功能：

TCP Ping 实现

function tcpPing(host: string, port: number, timeout: number): Promise<Result>

• 使用 net.Socket 建立 TCP 连接
• 测量连接建立时间
• 支持超时控制

HTTP/HTTPS Ping 实现

function httpPing(url: string, timeout: number): Promise<Result>

• 使用 http/https 模块发送 GET 请求
• 自动识别 HTTP/HTTPS 协议
• 测量请求响应时间
• 支持超时控制

检测接口

检测所有服务

GET /api/network/check-all

返回示例：

{
  "success": true,
  "data": {
    "results": [
      {
        "id": "baidu",
        "name": "互联网连接状态",
        "url": "www.baidu.com",
        "status": "success",
        "responseTime": 45
      }
    ],
    "timestamp": "2024-01-01T00:00:00.000Z"
  }
}

检测单个服务

POST /api/network/check-single
Body: { "url": "www.baidu.com" }

返回示例：

{
  "success": true,
  "data": {
    "url": "www.baidu.com",
    "status": "success",
    "responseTime": 45,
    "timestamp": "2024-01-01T00:00:00.000Z"
  }
}

页面位置

首页完整检测模块

网络检测模块位于首页（HomePage）中，布局顺序：

1. 日期时间和天气显示
2. 欢迎信息
3. 系统信息卡片
4. 系统状态（CPU、内存、磁盘、网络使用率）
5. 🆕 网络检测模块 ← 在这里
6. 终端占用、活跃端口、活跃进程

游戏部署页面状态横幅

在游戏部署页面的各个标签页顶部添加了网络状态横幅：

1. SteamCMD 标签页 - 显示 Steam 网络状态（Steamworks API）
2. Minecraft 部署标签页 - 显示 MSL API 连接状态
3. Minecraft 整合包部署标签页 - 显示 Modrinth 网络状态（API + CDN）
4. 在线部署标签页 - 显示 GSManager 在线部署服务状态

使用方法

1. 首次进入

• 打开 GSManager 面板
• 登录后进入首页
• 系统自动执行网络检测
• 查看横幅和各项检测结果

2. 手动检测

• 点击"检测所有"按钮：检测所有网络服务
• 点击单项"检测"按钮：检测特定网络服务
• 点击分类标题：展开/折叠分类详情

3. 查看结果

• 绿色对勾：服务连接正常，显示响应时间
• 红色叉号：服务连接失败，悬停查看错误原因
• 转圈图标：正在检测中
• 灰色图标：尚未检测

故障排查

检测失败常见原因

1. 防火墙限制

   • 检查服务器防火墙规则
   • 确保允许出站连接

2. 网络问题

   • 检查服务器网络连接
   • 测试 DNS 解析是否正常

3. 服务不可用

   • 目标服务可能临时维护
   • 使用备用服务或稍后重试

4. 超时设置

   • 默认超时 10 秒
   • 网络较慢时可能超时

调试方法

1. 查看浏览器控制台

   • 检查 API 请求是否成功
   • 查看详细错误信息

2. 查看服务器日志

   • 检查 server/logs/combined.log
   • 查找网络检测相关错误

3. 手动测试

   • 在服务器上使用 ping 或 curl 测试连接
   • 验证网络是否畅通

注意事项

1. 认证要求

   • 所有检测接口需要用户登录认证
   • 使用 authenticateToken 中间件

2. 性能考虑

   • 检测操作并发执行
   • 默认超时 10 秒，避免长时间等待

3. 错误处理

   • 单个服务失败不影响其他服务检测
   • 所有错误都会被捕获并显示

4. 隐私安全

   • 仅检测连接状态，不传输敏感数据
   • 使用标准的网络协议

网络状态横幅组件

组件说明

NetworkStatusBanner 是一个可复用的网络状态横幅组件，用于在特定页面显示相关网络服务的连接状态。

特性

1. 自动检测 - 首次加载时自动检测网络状态
2. 状态显示 - 实时显示网络连接状态
3. 一键重测 - 支持手动重新检测
4. 可关闭 - 用户可以关闭横幅
5. 淡入动画 - 平滑的淡入淡出动画效果
6. 详细信息 - 多项目时显示详细的各项状态

使用方法

// 显示整个分类的所有项目
<NetworkStatusBanner categoryId="steam" autoCheck={true} />

// 只显示分类中的某一个项目
<NetworkStatusBanner categoryId="minecraft" itemId="msl-api" autoCheck={true} />

参数说明

• categoryId - 分类ID，可选值：internet、steam、modrinth、minecraft、gsmanager
• itemId - 项目ID（可选），如果指定则只显示该项
• autoCheck - 是否首次加载时自动检测，默认为 false

相关文件

前端文件

• client/src/types/index.ts - 类型定义
• client/src/stores/networkCheckStore.ts - 状态管理
• client/src/components/NetworkCheck.tsx - 完整检测 UI 组件
• client/src/components/NetworkStatusBanner.tsx - 状态横幅组件（新增）
• client/src/utils/api.ts - API 客户端
• client/src/pages/HomePage.tsx - 首页集成
• client/src/pages/GameDeploymentPage.tsx - 游戏部署页面集成

后端文件

• server/src/routes/network.ts - 网络检测路由
• server/src/routes/index.ts - 路由注册
• server/src/index.ts - 服务器主文件
• server/src/middleware/auth.ts - 认证中间件

技术栈

• 前端：React、TypeScript、Zustand、Tailwind CSS、Lucide Icons
• 后端：Node.js、Express、TypeScript
• 网络：net（TCP）、http/https（HTTP）

开发者

如需修改或扩展网络检测功能，请参考以上技术实现部分，按照现有代码结构进行开发。

---