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`）

```typescript
// 网络检测项
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`）

```typescript
// 检测所有网络服务
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`）

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

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

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

主要功能：

##### TCP Ping 实现
```typescript
function tcpPing(host: string, port: number, timeout: number): Promise<Result>
```
- 使用 `net.Socket` 建立 TCP 连接
- 测量连接建立时间
- 支持超时控制

##### HTTP/HTTPS Ping 实现
```typescript
function httpPing(url: string, timeout: number): Promise<Result>
```
- 使用 `http`/`https` 模块发送 GET 请求
- 自动识别 HTTP/HTTPS 协议
- 测量请求响应时间
- 支持超时控制

##### 检测接口

**检测所有服务**
```
GET /api/network/check-all
```
返回示例：
```json
{
  "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" }
```
返回示例：
```json
{
  "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. **详细信息** - 多项目时显示详细的各项状态

### 使用方法

```tsx
// 显示整个分类的所有项目
<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）

## 开发者

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

---