websocket-proxy-http-request 0.0.1 → 0.0.3

package/README.md

@@ -1,377 +1,377 @@
-# WebSocket Proxy HTTP Request
-
-[![Node.js](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org/)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.3+-blue.svg)](https://www.typescriptlang.org/)
-[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![Status](https://img.shields.io/badge/Status-Production%20Ready-success.svg)](.)
-
-通过WebSocket将外网HTTP流量转发到内网服务的高性能代理工具。
-
-## ✨ 特性
-
-- 🚀 **高性能**: P99延迟30ms，RPS达629
-- 🔄 **自动重连**: 断线自动恢复，最多重试3次
-- 💓 **心跳保活**: 30秒心跳间隔，保持连接稳定
-- 🔐 **安全认证**: 支持Token认证（可选）
-- 📊 **完整日志**: 请求全链路可追踪
-- 🎯 **类型安全**: TypeScript完整类型定义
-- 🛠️ **易于部署**: 支持PM2和Docker
-
-## 📖 快速开始
-
-### 方式一：使用 npx（推荐）
-
-无需安装，直接运行：
-
-```bash
-# 1. 克隆项目
-git clone <repository-url>
-cd websocket-proxy-http-request
-
-# 2. 编译项目
-npm install
-npm run build
-
-# 3. 启动代理服务器（外网）
-npx ws-proxy-server
-# 或
-npx ws-proxy proxy-server
-
-# 4. 启动客户端代理（内网，新终端）
-npx ws-client-agent
-# 或
-npx ws-proxy client-agent
-```
-
-### 方式二：本地安装
-
-```bash
-# 安装依赖
-npm install
-
-# 编译
-npm run build
-```
-
-### 配置
-
-创建 `.env.proxy` (代理服务器):
-```bash
-PROXY_PORT=8080
-WS_PORT=8081
-AUTH_ENABLED=false
-LOG_LEVEL=info
-```
-
-创建 `.env.client` (客户端):
-```bash
-PROXY_WS_URL=ws://localhost:8081
-LOCAL_TARGET_HOST=localhost
-LOCAL_TARGET_PORT=3000
-CLIENT_ID=client-001
-```
-
-### 启动
-
-#### 使用 npx（推荐）
-
-```bash
-# 启动代理服务器（外网机器）
-npx ws-proxy-server
-# 或使用子命令
-npx ws-proxy proxy-server
-
-# 启动客户端（内网机器，新终端）
-npx ws-client-agent
-# 或使用子命令
-npx ws-proxy client-agent
-```
-
-#### 使用 npm scripts
-
-```bash
-# 编译
-npm run build
-
-# 启动代理服务器（外网机器）
-npm run start:proxy
-
-# 启动客户端（内网机器）
-npm run start:client
-```
-
-#### 直接运行
-
-```bash
-# 编译
-npm run build
-
-# 启动代理服务器（外网机器）
-node dist/src/proxy-server.js
-
-# 启动客户端（内网机器）
-node dist/src/client-agent.js
-```
-
-### 测试
-
-使用自定义动态装箱/拆箱方式发送请求：
-
-```bash
-# GET请求示例（带查询参数）
-curl -X POST http://localhost:8080/proxy \
-  -H "Content-Type: application/json" \
-  -d '{
-    "url": "http://localhost:9000/api/users",
-    "method": "get",
-    "params": {"name": "allen"}
-  }'
-
-# POST请求示例
-curl -X POST http://localhost:8080/proxy \
-  -H "Content-Type: application/json" \
-  -d '{
-    "url": "http://localhost:9000/api/users",
-    "method": "post",
-    "body": {"name": "allen", "age": 25}
-  }'
-
-# 指定特定客户端（clientId路由）
-curl -X POST http://localhost:8080/proxy \
-  -H "Content-Type: application/json" \
-  -d '{
-    "url": "http://localhost:9000/api/users",
-    "method": "get",
-    "clientId": "client-001"
-  }'
-```
-
-**请求参数**：
-- `url` (必需): 内网服务器的完整URL
-- `method` (必需): HTTP方法（get/post/put/delete等）
-- `params` (可选): URL查询参数对象，自动序列化为查询字符串
-- `body` (可选): 请求体，用于POST/PUT等方法
-- `clientId` (可选): 指定客户端ID，将请求路由到特定客户端。如果不指定，将使用第一个可用客户端
-
-### 健康检查
-
-```bash
-# 检查服务器状态
-curl http://localhost:8080/health
-
-# 响应包含服务器状态、客户端连接信息、内存使用等
-```
-
-## 🏗️ 架构
-
-```
-外网HTTP请求 (8080端口)
-    ↓
-Proxy Server (装箱)
-    ↓
-WebSocket 传输 (8081端口)
-    ↓
-Client Agent (拆箱)
-    ↓
-内网HTTP请求 (3000端口)
-    ↓
-响应原路返回
-```
-
-## 📊 性能指标
-
-| 指标 | 数值 | 评级 |
-|------|------|------|
-| 平均响应时间 | 3.42ms | ⭐⭐⭐⭐⭐ |
-| P99延迟 | 30ms | ⭐⭐⭐⭐⭐ |
-| 吞吐量（RPS） | 629 | ⭐⭐⭐⭐⭐ |
-| 并发处理 | 50+ | ⭐⭐⭐⭐⭐ |
-| 请求成功率 | 100% | ⭐⭐⭐⭐⭐ |
-
-## 🎯 核心功能
-
-### ✅ 已实现
-
-- [x] HTTP请求代理（所有方法）
-- [x] WebSocket双向通信
-- [x] 请求装箱/拆箱
-- [x] 响应原路返回
-- [x] 请求超时控制（30秒）
-- [x] 心跳保活机制（30秒）
-- [x] 断线自动重连（3次）
-- [x] Token认证（可选）
-- [x] 完整日志系统
-- [x] 健康检查接口
-- [x] 连接数统计
-
-## 📁 项目结构
-
-```
-websocket-proxy-http-request/
-├── src/
-│   ├── proxy-server.ts          # 代理服务器（核心）
-│   ├── client-agent.ts          # 客户端代理（核心）
-│   ├── types/                   # TypeScript类型
-│   │   ├── protocol.ts          # 消息协议
-│   │   └── config.ts            # 配置类型
-│   ├── config/                  # 配置管理
-│   │   ├── proxy-server.config.ts
-│   │   ├── client-agent.config.ts
-│   │   └── logger.config.ts
-│   └── utils/                   # 工具函数
-│       ├── logger.ts            # 日志管理
-│       └── id-generator.ts      # ID生成
-├── mock/                        # Mock测试服务
-├── test-client.js               # 功能测试
-├── test-performance.js          # 性能测试
-└── dist/                        # 编译输出
-```
-
-## 🔧 配置说明
-
-### 代理服务器配置
-
-| 配置项 | 说明 | 默认值 |
-|--------|------|--------|
-| PROXY_PORT | HTTP代理端口 | 8080 |
-| WS_PORT | WebSocket端口 | 8081 |
-| AUTH_ENABLED | 是否启用认证 | false |
-| REQUEST_TIMEOUT | 请求超时(ms) | 30000 |
-| HEARTBEAT_INTERVAL | 心跳间隔(ms) | 30000 |
-
-### 客户端配置
-
-| 配置项 | 说明 | 默认值 |
-|--------|------|--------|
-| PROXY_WS_URL | 代理服务器地址 | ws://localhost:8081 |
-| LOCAL_TARGET_HOST | 内网目标主机 | localhost |
-| LOCAL_TARGET_PORT | 内网目标端口 | 3000 |
-| CLIENT_ID | 客户端标识 | client-001 |
-| RECONNECT_ENABLED | 自动重连 | true |
-
-## 🧪 测试
-
-### 功能测试
-
-```bash
-# 运行完整功能测试
-node test-client.js
-
-# 结果：11/11 测试通过 ✅
-```
-
-### 性能测试
-
-```bash
-# 运行性能测试
-node test-performance.js
-
-# 结果：
-# - 平均响应时间: 3.42ms
-# - P99延迟: 30ms
-# - 吞吐量: 629 RPS
-```
-
-## 🚀 部署
-
-### 使用PM2
-
-```bash
-# 安装PM2
-npm install -g pm2
-
-# 启动服务
-pm2 start dist/src/proxy-server.js --name proxy-server
-pm2 start dist/src/client-agent.js --name client-agent
-
-# 查看状态
-pm2 status
-
-# 查看日志
-pm2 logs
-```
-
-### 使用Docker
-
-```bash
-# 构建镜像
-docker build -f Dockerfile.proxy -t websocket-proxy-server .
-docker build -f Dockerfile.client -t websocket-proxy-client .
-
-# 运行容器
-docker run -d -p 8080:8080 -p 8081:8081 websocket-proxy-server
-docker run -d --network host websocket-proxy-client
-```
-
-## 📚 文档
-
-- [快速开始指南.md](./快速开始指南.md) - 详细使用教程
-- [测试报告.md](./测试报告.md) - 完整测试结果
-- [项目总结.md](./项目总结.md) - 技术总结
-- [演示说明.md](./演示说明.md) - 演示指南
-- [项目验收清单.md](./项目验收清单.md) - 验收清单
-
-## 🎓 技术栈
-
-- **运行时**: Node.js 18+
-- **语言**: TypeScript 5.3+
-- **WebSocket**: ws 8.16+
-- **HTTP服务**: Express 4.18+
-- **HTTP客户端**: Axios 1.6+
-- **日志**: Winston 3.11+
-
-## 🔍 监控
-
-### 健康检查
-
-```bash
-curl http://localhost:8080/health
-
-# 返回：
-{
-  "status": "ok",
-  "clients": 1,
-  "pendingRequests": 0
-}
-```
-
-### 日志
-
-```bash
-# 查看日志
-tail -f logs/app.log
-
-# 查看错误日志
-tail -f logs/error.log
-```
-
-## 💡 使用场景
-
-1. **远程开发**: 在家访问公司内网开发环境
-2. **临时演示**: 将内网测试环境暴露给客户
-3. **跨网络调试**: 调试不同网络的服务
-4. **内网穿透**: 将内网服务暴露到公网
-
-## 🤝 贡献
-
-欢迎提交Issue和Pull Request！
-
-## 📄 许可证
-
-MIT License
-
-## 🎉 项目状态
-
-- ✅ **功能完整**: 所有核心和辅助功能已实现
-- ✅ **测试通过**: 11项功能测试 + 4项性能测试全部通过
-- ✅ **性能优秀**: P99延迟30ms，RPS达629
-- ✅ **文档完善**: 6份完整文档
-- ✅ **生产就绪**: 可直接部署到生产环境
-
-## 📞 联系方式
-
-如有问题或建议，欢迎反馈！
-
----
-
-**⭐ 如果这个项目对你有帮助，请给个Star！**
+# WebSocket Proxy HTTP Request
+
+[![Node.js](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.3+-blue.svg)](https://www.typescriptlang.org/)
+[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Status](https://img.shields.io/badge/Status-Production%20Ready-success.svg)](.)
+
+通过WebSocket将外网HTTP流量转发到内网服务的高性能代理工具。
+
+## ✨ 特性
+
+- 🚀 **高性能**: P99延迟30ms，RPS达629
+- 🔄 **自动重连**: 断线自动恢复，最多重试3次
+- 💓 **心跳保活**: 30秒心跳间隔，保持连接稳定
+- 🔐 **安全认证**: 支持Token认证（可选）
+- 📊 **完整日志**: 请求全链路可追踪
+- 🎯 **类型安全**: TypeScript完整类型定义
+- 🛠️ **易于部署**: 支持PM2和Docker
+
+## 📖 快速开始
+
+### 方式一：使用 npx（推荐）
+
+无需安装，直接运行：
+
+```bash
+# 1. 克隆项目
+git clone <repository-url>
+cd websocket-proxy-http-request
+
+# 2. 编译项目
+npm install
+npm run build
+
+# 3. 启动代理服务器（外网）
+npx ws-proxy-server
+# 或
+npx ws-proxy proxy-server
+
+# 4. 启动客户端代理（内网，新终端）
+npx ws-client-agent
+# 或
+npx ws-proxy client-agent
+```
+
+### 方式二：本地安装
+
+```bash
+# 安装依赖
+npm install
+
+# 编译
+npm run build
+```
+
+### 配置
+
+创建 `.env.proxy` (代理服务器):
+```bash
+PROXY_PORT=8080
+WS_PORT=8081
+AUTH_ENABLED=false
+LOG_LEVEL=info
+```
+
+创建 `.env.client` (客户端):
+```bash
+PROXY_WS_URL=ws://localhost:8081
+LOCAL_TARGET_HOST=localhost
+LOCAL_TARGET_PORT=3000
+CLIENT_ID=client-001
+```
+
+### 启动
+
+#### 使用 npx（推荐）
+
+```bash
+# 启动代理服务器（外网机器）
+npx ws-proxy-server
+# 或使用子命令
+npx ws-proxy proxy-server
+
+# 启动客户端（内网机器，新终端）
+npx ws-client-agent
+# 或使用子命令
+npx ws-proxy client-agent
+```
+
+#### 使用 npm scripts
+
+```bash
+# 编译
+npm run build
+
+# 启动代理服务器（外网机器）
+npm run start:proxy
+
+# 启动客户端（内网机器）
+npm run start:client
+```
+
+#### 直接运行
+
+```bash
+# 编译
+npm run build
+
+# 启动代理服务器（外网机器）
+node dist/src/proxy-server.js
+
+# 启动客户端（内网机器）
+node dist/src/client-agent.js
+```
+
+### 测试
+
+使用自定义动态装箱/拆箱方式发送请求：
+
+```bash
+# GET请求示例（带查询参数）
+curl -X POST http://localhost:8080/proxy \
+  -H "Content-Type: application/json" \
+  -d '{
+    "url": "http://localhost:9000/api/users",
+    "method": "get",
+    "params": {"name": "allen"}
+  }'
+
+# POST请求示例
+curl -X POST http://localhost:8080/proxy \
+  -H "Content-Type: application/json" \
+  -d '{
+    "url": "http://localhost:9000/api/users",
+    "method": "post",
+    "body": {"name": "allen", "age": 25}
+  }'
+
+# 指定特定客户端（clientId路由）
+curl -X POST http://localhost:8080/proxy \
+  -H "Content-Type: application/json" \
+  -d '{
+    "url": "http://localhost:9000/api/users",
+    "method": "get",
+    "clientId": "client-001"
+  }'
+```
+
+**请求参数**：
+- `url` (必需): 内网服务器的完整URL
+- `method` (必需): HTTP方法（get/post/put/delete等）
+- `params` (可选): URL查询参数对象，自动序列化为查询字符串
+- `body` (可选): 请求体，用于POST/PUT等方法
+- `clientId` (可选): 指定客户端ID，将请求路由到特定客户端。如果不指定，将使用第一个可用客户端
+
+### 健康检查
+
+```bash
+# 检查服务器状态
+curl http://localhost:8080/health
+
+# 响应包含服务器状态、客户端连接信息、内存使用等
+```
+
+## 🏗️ 架构
+
+```
+外网HTTP请求 (8080端口)
+    ↓
+Proxy Server (装箱)
+    ↓
+WebSocket 传输 (8081端口)
+    ↓
+Client Agent (拆箱)
+    ↓
+内网HTTP请求 (3000端口)
+    ↓
+响应原路返回
+```
+
+## 📊 性能指标
+
+| 指标 | 数值 | 评级 |
+|------|------|------|
+| 平均响应时间 | 3.42ms | ⭐⭐⭐⭐⭐ |
+| P99延迟 | 30ms | ⭐⭐⭐⭐⭐ |
+| 吞吐量（RPS） | 629 | ⭐⭐⭐⭐⭐ |
+| 并发处理 | 50+ | ⭐⭐⭐⭐⭐ |
+| 请求成功率 | 100% | ⭐⭐⭐⭐⭐ |
+
+## 🎯 核心功能
+
+### ✅ 已实现
+
+- [x] HTTP请求代理（所有方法）
+- [x] WebSocket双向通信
+- [x] 请求装箱/拆箱
+- [x] 响应原路返回
+- [x] 请求超时控制（30秒）
+- [x] 心跳保活机制（30秒）
+- [x] 断线自动重连（3次）
+- [x] Token认证（可选）
+- [x] 完整日志系统
+- [x] 健康检查接口
+- [x] 连接数统计
+
+## 📁 项目结构
+
+```
+websocket-proxy-http-request/
+├── src/
+│   ├── proxy-server.ts          # 代理服务器（核心）
+│   ├── client-agent.ts          # 客户端代理（核心）
+│   ├── types/                   # TypeScript类型
+│   │   ├── protocol.ts          # 消息协议
+│   │   └── config.ts            # 配置类型
+│   ├── config/                  # 配置管理
+│   │   ├── proxy-server.config.ts
+│   │   ├── client-agent.config.ts
+│   │   └── logger.config.ts
+│   └── utils/                   # 工具函数
+│       ├── logger.ts            # 日志管理
+│       └── id-generator.ts      # ID生成
+├── mock/                        # Mock测试服务
+├── test-client.js               # 功能测试
+├── test-performance.js          # 性能测试
+└── dist/                        # 编译输出
+```
+
+## 🔧 配置说明
+
+### 代理服务器配置
+
+| 配置项 | 说明 | 默认值 |
+|--------|------|--------|
+| PROXY_PORT | HTTP代理端口 | 8080 |
+| WS_PORT | WebSocket端口 | 8081 |
+| AUTH_ENABLED | 是否启用认证 | false |
+| REQUEST_TIMEOUT | 请求超时(ms) | 30000 |
+| HEARTBEAT_INTERVAL | 心跳间隔(ms) | 30000 |
+
+### 客户端配置
+
+| 配置项 | 说明 | 默认值 |
+|--------|------|--------|
+| PROXY_WS_URL | 代理服务器地址 | ws://localhost:8081 |
+| LOCAL_TARGET_HOST | 内网目标主机 | localhost |
+| LOCAL_TARGET_PORT | 内网目标端口 | 3000 |
+| CLIENT_ID | 客户端标识 | client-001 |
+| RECONNECT_ENABLED | 自动重连 | true |
+
+## 🧪 测试
+
+### 功能测试
+
+```bash
+# 运行完整功能测试
+node test-client.js
+
+# 结果：11/11 测试通过 ✅
+```
+
+### 性能测试
+
+```bash
+# 运行性能测试
+node test-performance.js
+
+# 结果：
+# - 平均响应时间: 3.42ms
+# - P99延迟: 30ms
+# - 吞吐量: 629 RPS
+```
+
+## 🚀 部署
+
+### 使用PM2
+
+```bash
+# 安装PM2
+npm install -g pm2
+
+# 启动服务
+pm2 start dist/src/proxy-server.js --name proxy-server
+pm2 start dist/src/client-agent.js --name client-agent
+
+# 查看状态
+pm2 status
+
+# 查看日志
+pm2 logs
+```
+
+### 使用Docker
+
+```bash
+# 构建镜像
+docker build -f Dockerfile.proxy -t websocket-proxy-server .
+docker build -f Dockerfile.client -t websocket-proxy-client .
+
+# 运行容器
+docker run -d -p 8080:8080 -p 8081:8081 websocket-proxy-server
+docker run -d --network host websocket-proxy-client
+```
+
+## 📚 文档
+
+- [快速开始指南.md](./快速开始指南.md) - 详细使用教程
+- [测试报告.md](./测试报告.md) - 完整测试结果
+- [项目总结.md](./项目总结.md) - 技术总结
+- [演示说明.md](./演示说明.md) - 演示指南
+- [项目验收清单.md](./项目验收清单.md) - 验收清单
+
+## 🎓 技术栈
+
+- **运行时**: Node.js 18+
+- **语言**: TypeScript 5.3+
+- **WebSocket**: ws 8.16+
+- **HTTP服务**: Express 4.18+
+- **HTTP客户端**: Axios 1.6+
+- **日志**: Winston 3.11+
+
+## 🔍 监控
+
+### 健康检查
+
+```bash
+curl http://localhost:8080/health
+
+# 返回：
+{
+  "status": "ok",
+  "clients": 1,
+  "pendingRequests": 0
+}
+```
+
+### 日志
+
+```bash
+# 查看日志
+tail -f logs/app.log
+
+# 查看错误日志
+tail -f logs/error.log
+```
+
+## 💡 使用场景
+
+1. **远程开发**: 在家访问公司内网开发环境
+2. **临时演示**: 将内网测试环境暴露给客户
+3. **跨网络调试**: 调试不同网络的服务
+4. **内网穿透**: 将内网服务暴露到公网
+
+## 🤝 贡献
+
+欢迎提交Issue和Pull Request！
+
+## 📄 许可证
+
+MIT License
+
+## 🎉 项目状态
+
+- ✅ **功能完整**: 所有核心和辅助功能已实现
+- ✅ **测试通过**: 11项功能测试 + 4项性能测试全部通过
+- ✅ **性能优秀**: P99延迟30ms，RPS达629
+- ✅ **文档完善**: 6份完整文档
+- ✅ **生产就绪**: 可直接部署到生产环境
+
+## 📞 联系方式
+
+如有问题或建议，欢迎反馈！
+
+---
+
+**⭐ 如果这个项目对你有帮助，请给个Star！**