# tunnel-server

**Repository Path**: junyan4918/tunnel-server

## Basic Information

- **Project Name**: tunnel-server
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-02
- **Last Updated**: 2025-12-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 反向隧道系统 (类似 ngrok)

基于 Node.js + WebSocket 实现的反向隧道系统，可将内网服务暴露到公网。

## 架构图

```
            ┌───────────────┐
公网 Client │ 访问云服务器:80 │   (比如访问 http://你的域名:80 )
            └───────▲───────┘
                    │ HTTP 请求
                    │
          ┌─────────┴─────────┐
          │   云服务器 Tunnel   │ ①接收公网请求
          │   (Node.js)         │ ②把请求转发给内网Agent
          └─────────▲─────────┘
                    │ WebSocket (端口 8081)
                    │
        ┌───────────┴────────────┐
        │        内网 Agent        │
        │（NodeJS 客户端本地运行）│
        │  连接 云服务器:WS隧道    │
        └───────────┬────────────┘
                    │ HTTP 请求转发到本地服务
                    ▼
            内网真实服务（127.0.0.1:8080）
```

## 项目结构

```
TunnelServer/
├── tunnel-server/      # 服务器端 (部署在公网)
│   ├── package.json
│   └── src/
│       └── index.js
├── tunnel-agent/       # 客户端 Agent (运行在内网)
│   ├── package.json
│   └── src/
│       └── index.js
├── test-local-server/  # 测试用本地服务
│   └── index.js
└── README.md
```

## 快速开始

### 1. 安装依赖

```bash
# 服务器端
cd tunnel-server
npm install

# 客户端
cd ../tunnel-agent
npm install
```

### 2. 启动服务器端 (在公网服务器上)

```bash
cd tunnel-server
npm start
```

服务器会启动三个端口：
- **端口 80**: HTTP 服务 - 接收公网请求
- **端口 8081**: WebSocket 服务 - Agent 连接
- **端口 8082**: 管理面板 - 查看连接状态

### 3. 启动客户端 Agent (在内网机器上)

```bash
cd tunnel-agent

# 使用环境变量配置
SERVER_URL=ws://your-server:8081 \
AGENT_NAME=my-local-server \
LOCAL_HOST=127.0.0.1 \
LOCAL_PORT=8080 \
npm start
```

### 4. 测试

启动一个本地测试服务：
```bash
cd test-local-server
node index.js
```

然后访问公网服务器的 80 端口，请求会被转发到内网的 8080 端口。

## 配置说明

### 服务器端环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| HTTP_PORT | 80 | 公网 HTTP 服务端口 |
| WS_PORT | 8081 | WebSocket 服务端口 |
| ADMIN_PORT | 8082 | 管理面板端口 |

### 客户端环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| SERVER_URL | ws://localhost:8081 | 服务器 WebSocket 地址 |
| AGENT_NAME | my-agent | Agent 名称标识 |
| LOCAL_HOST | 127.0.0.1 | 本地服务地址 |
| LOCAL_PORT | 8080 | 本地服务端口 |
| RECONNECT_INTERVAL | 5000 | 重连间隔(毫秒) |
| HEARTBEAT_INTERVAL | 30000 | 心跳间隔(毫秒) |

## 管理面板

访问 `http://your-server:8082` 可以查看：
- 在线 Agent 数量
- 待处理请求数
- 服务运行时间
- 已连接的 Agent 列表及其状态

## 工作流程

1. **Agent 连接**: 内网 Agent 启动后主动连接公网服务器的 WebSocket 端口
2. **保持连接**: 通过心跳机制维持长连接，断开后自动重连
3. **请求转发**: 
   - 公网用户访问服务器 80 端口
   - 服务器将 HTTP 请求封装后通过 WebSocket 发送给 Agent
   - Agent 将请求转发到本地服务
   - Agent 将本地服务的响应通过 WebSocket 返回给服务器
   - 服务器将响应返回给公网用户

## 注意事项

1. **端口权限**: 默认使用 80 端口，在 Linux 上可能需要 root 权限或使用 `setcap`
2. **防火墙**: 确保公网服务器的 80 和 8081 端口开放
3. **安全性**: 生产环境建议：
   - 为 WebSocket 连接添加认证
   - 使用 HTTPS/WSS
   - 限制可连接的 IP
4. **超时处理**: 默认请求超时 30 秒

## 扩展功能建议

- [ ] 多租户支持 (不同 subdomain 对应不同 Agent)
- [ ] Agent 认证机制
- [ ] 请求日志记录
- [ ] 流量统计
- [ ] WebSocket 连接加密 (WSS)
- [ ] 负载均衡