# ping-test-web

**Repository Path**: niclas0923/ping-test-web

## Basic Information

- **Project Name**: ping-test-web
- **Description**: 为通过多个内网穿透指定的同一地址做延迟和稳定性的比较，当然也可以通过它来测试多个网址的连接延迟。它是为了moonlight和sunshine组成的远程连接制作的，为你选择最稳定，延迟最低的地址。

- **Primary Language**: NodeJS
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-01-28
- **Last Updated**: 2025-12-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: React, Express, TypeScript

## README

# Ping Test Web

基于 React + Vite 的前端与 Express 后端组合，用于对一组网络地址进行延迟与稳定性测试。支持地址备注与启用开关、并发与超时配置、实时统计、图表展示以及易用的交互细节。

## 核心功能

### 地址管理
- 以列表方式编辑地址，支持新增/删除、备注与启用开关（默认启用）
- 自动保存机制，编辑停顿约 500ms 后静默保存到后端
- 支持每个地址独立的备注信息

### 测试配置
- 可配置采样次数、间隔时间、超时时间、并发数
- 支持浏览器端测试和服务器端测试两种模式
- 浏览器端测试：允许访问内网地址，请求由用户浏览器直接发起
- 服务器端测试：禁止访问内网地址，防止 SSRF 攻击

### 实时测试
- 按配置的采样次数、间隔与并发数进行请求
- 支持实时停止测试
- 显示整体测试进度

### 结果统计
- 每次采样后更新成功率、平均/最小/最大延迟与抖动
- 显示最近一次延迟
- 结果排序：优先按成功率（降序），再按平均延迟（升序），最后按抖动（升序）

### 可视化展示
- 折线图展示各地址的延迟变化趋势
- 悬停结果行显示该地址所有延迟值
- 图表支持按采样点显示各系列数据与平均值提示

### 用户认证
- 基于 JWT 的用户认证系统
- 支持用户注册、登录、刷新令牌
- 多用户数据分离，每个用户有独立的 JSON 文件存储数据
- 双密钥机制（管理员密钥和普通用户密钥），支持自动 24 小时旋转
- 基于密钥的用户创建，无需管理员干预

### 管理员功能
- 管理员专属控制台，用于查看和刷新密钥
- 登录失败限制，防止暴力破解
- 支持刷新所有密钥

## 技术栈

### 前端
- React 18
- Vite
- TypeScript
- Tailwind CSS
- lucide-react（图标库）
- react-router-dom（路由管理）
- React Context API（状态管理）

### 后端
- Node.js
- Express
- CORS
- dotenv（环境变量管理）
- bcrypt（密码哈希）
- jsonwebtoken（JWT 认证）
- csurf（CSRF 保护）
- cookie-parser（Cookie 解析）

### 工具
- vite-tsconfig-paths
- ESLint（代码检查）
- Nodemon（后端开发热重载）

## 快速开始

### 安装依赖

```bash
npm install
```

### 启动服务

#### 同时启动前端与后端

```bash
npm run dev
```

- 前端：Vite（默认 5173，端口占用会自动递增）
- 后端：Express（默认 3002，可通过环境变量 `PORT` 指定）
- 代理：开发服务器将 `/api` 请求代理到 `http://localhost:3002`

#### 分开启动

```bash
npm run client:dev   # 仅前端
npm run server:dev   # 仅后端（nodemon + tsx）
```

### 构建与预览

```bash
npm run build   # 构建前端产物到 dist/
npm run preview # 预览构建产物（需独立运行后端）
```

### 质量检查

```bash
npm run check   # TypeScript 类型检查
npm run lint    # ESLint 代码检查
```

### 生产启动（本地或自托管）

```bash
npm run start  # 启动 Express 后端并服务 dist 静态前端
```

## 首次使用

### 获取密钥

- 启动服务后，查看 `data/key.json` 文件，获取初始 `adminKey` 和 `userKey`
- 或者通过管理员 API 获取：`GET /api/auth/key`（需要管理员认证）
- 管理员登录后，可通过 `http://localhost:5173/admin` 页面查看和刷新密钥

### 创建用户

1. 访问 `http://localhost:5173/user-create`
2. 输入用户名、密码和密钥
3. 使用 `adminKey` 创建管理员用户，使用 `userKey` 创建普通用户

### 登录

1. 访问 `http://localhost:5173/login`
2. 使用刚创建的用户名和密码登录

### 开始测试

1. 登录后会自动跳转到主页
2. 添加要测试的地址，配置测试参数
3. 点击「开始测试」按钮开始测试
4. 测试过程中可以随时停止或清空结果

## 环境变量配置

复制 `.env.example` 为 `.env` 并根据需要修改：

```bash
cp .env.example .env
```

### 可配置项

- `PORT` - 服务端口（默认 3002）
- `ALLOWED_ORIGINS` - CORS 允许的来源，多个用逗号分隔（开发环境可用 `*`，生产环境建议设置具体域名）
- `NODE_ENV` - 运行环境（`development`/`production`）
- `JWT_SECRET` - JWT 签名密钥（默认使用随机生成的密钥）
- `JWT_EXPIRES_IN` - 访问令牌过期时间（默认 1h）
- `JWT_REFRESH_EXPIRES_IN` - 刷新令牌过期时间（默认 7d）

## 项目结构

```
api/                    # 后端代码
  app.ts                # 应用与中间件配置
  server.ts             # 本地服务入口
  index.ts              # Vercel Serverless 入口
  models/               # 类型定义
    user.ts            # 用户相关类型
  routes/               # API 路由
    addresses.ts       # 地址管理
    settings.ts        # 测试参数
    test.ts            # 单地址测试
    auth.ts            # 认证相关
  middleware/           # 中间件
    auth.ts            # JWT 认证
    loginLimit.ts      # 登录失败限制
  utils/                # 工具函数
    keyManager.ts      # 密钥管理
    userStore.ts       # 用户数据存储
    fileInit.ts        # 文件初始化

src/                    # 前端代码
  context/              # 上下文
    AuthContext.tsx    # 认证上下文
  components/           # 组件
    PingTest.tsx       # 核心测试组件
    LineChart.tsx      # 折线图组件
  pages/                # 页面
    Home.tsx           # 主页
    Login.tsx          # 登录页面
    UserCreate.tsx     # 用户创建页面
    AdminPage.tsx      # 管理员控制台
  App.tsx              # 路由配置
  main.tsx             # 前端入口
  index.css            # 样式文件

data/                   # 数据目录
  key.json             # 密钥数据
  user/                # 用户数据
    {userId}.json      # 每个用户的独立 JSON 文件

public/                 # 静态资源
index.html             # SPA 容器
vite.config.ts         # Vite 配置
vercel.json            # Vercel 部署配置
```

## 安全特性

### 认证与授权
- JWT 认证，无状态设计
- 密码使用 bcrypt 哈希存储
- 刷新令牌机制，减少令牌泄露风险
- 角色权限管理，区分管理员和普通用户
- 登录失败限制，默认 5 次尝试后锁定 5 分钟

### SSRF 防护
- 服务器端测试禁止访问私有 IP 地址段
- 浏览器端测试允许访问内网地址
- DNS 解析后再次验证 IP 地址，防止 DNS 重绑定攻击
- 前后端双重验证，根据测试模式动态调整安全策略

### 请求速率限制
- 全局速率限制：默认每分钟最多 100 个 API 请求
- 登录请求限制：每分钟最多 5 次登录请求
- 用户创建限制：每个 IP 地址 5 分钟内最多创建 5 个用户

### CSRF 保护
- 使用 csurf 中间件提供 CSRF 保护
- 基于 Cookie 的 CSRF 令牌

### 安全头部
- X-Frame-Options: DENY
- X-Content-Type-Options: nosniff
- X-XSS-Protection: 1; mode=block
- Content-Security-Policy（基本策略）

## 部署

### Vercel 部署

1. Fork 项目到你的 GitHub 账户
2. 在 Vercel 上导入项目
3. 配置环境变量
4. 部署完成

### 自托管部署

1. 构建前端：`npm run build`
2. 配置环境变量：复制 `.env.example` 为 `.env` 并修改
3. 启动服务：`npm run start`

### 部署注意事项

- 生产环境建议设置具体的 `ALLOWED_ORIGINS`，避免使用 `*`
- 配置强 `JWT_SECRET`，避免使用默认值
- Serverless 环境下，`data` 目录的文件存储可能不可靠，建议使用云存储或数据库
- 定期备份用户数据
- 启用 HTTPS

## 使用提示

- 地址列表仅启用项参与测试
- 测试进行中可随时停止或清空结果
- 清空结果会先停止测试
- 悬停结果行显示该地址所有延迟值
- 支持按采样点显示各系列数据与平均值提示
- 测试参数修改后会自动保存

## 许可证

本项目采用 Apache License 2.0 许可证，详情参见 `LICENSE` 文件。