# web-transfer

**Repository Path**: nachao/web-transfer

## Basic Information

- **Project Name**: web-transfer
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-21
- **Last Updated**: 2026-02-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Web Transfer - 内网穿透工具

这是一个用 Go 编写的内网穿透工具，允许你通过公网服务器访问本地服务。支持多客户端、服务代码路由、Windows/Linux 服务部署等功能。

## 📋 快速理解端口配置

### 三个关键端口，三个不同角色

```
┌─────────────────────────────────────────────────────────────────┐
│                          公网服务器                              │
│  IP: 162.14.120.45                                              │
│                                                                 │
│  ┌──────────────────┐      ┌──────────────────┐                │
│  │  6110 端口       │      │  6111 端口       │                │
│  │  (HTTP_PORT)     │      │  (CLIENT_PORT)   │                │
│  │                  │      │                  │                │
│  │  公网用户访问    │      │  客户端连接这里   │                │
│  └────────┬─────────┘      └────────┬─────────┘                │
│           │                          │                          │
└───────────┼──────────────────────────┼──────────────────────────┘
            │                          │
            │ 公网请求                 │ TCP 长连接
            ↓                          ↓
    http://162.14.120.45:6110/    本地客户端程序
    my-service/api/test           (web-transfer-client)
                                      │
                                      │ 转发请求
                                      ↓
                              http://localhost:5001/api/test
                              (你的本地服务)
```

### 端口说明

| 端口 | 用途 | 谁连接它 | 谁监听它 | 示例 |
|------|------|---------|---------|------|
| **6110** | 公网访问端口 | 公网用户 | 服务器监听 | `http://162.14.120.45:6110/my-service/api/test` |
| **6111** | 客户端连接端口 | **本地客户端程序** | 服务器监听 | `SERVER_ADDR=162.14.120.45:6111` |
| **5001** | 本地服务端口 | 客户端程序 | 你的本地服务 | `http://localhost:5001` |

### 核心概念

1. **6110 端口** - 公网用户访问这个端口来请求你的服务
2. **6111 端口** - 你的**客户端程序**（不是本地服务）主动连接这个端口
3. **5001 端口** - 你的本地服务监听的端口，客户端程序会将请求转发到这里

### 完整流程

```
1. 公网用户访问: http://162.14.120.45:6110/my-service/api/test
                    ↓
2. 服务器(6110)接收请求，提取服务代码 "my-service"
                    ↓
3. 服务器查找已注册的 "my-service" 客户端
                    ↓
4. 通过 6111 端口的 TCP 连接转发请求给客户端
                    ↓
5. 客户端收到请求，转发到本地: http://localhost:5001/api/test
                    ↓
6. 本地服务处理并返回响应
                    ↓
7. 客户端将响应通过 6111 连接返回给服务器
                    ↓
8. 服务器将响应返回给公网用户
```

## ✨ 功能特性

- ✅ **多客户端支持**：支持多个客户端连接到同一服务器，通过服务代码区分
- ✅ **服务代码路由**：通过 `/service-code/path` 格式访问不同的本地服务
- ✅ **Windows 服务**：支持部署为 Windows 服务（使用 NSSM），开机自启动
- ✅ **Linux 服务**：支持部署为 systemd 服务
- ✅ **多配置管理**：支持多个配置文件，方便管理不同的客户端
- ✅ **自动重连**：客户端自动重连服务器，断线自动恢复
- ✅ **日志记录**：完整的日志记录，便于排查问题

## 🏗️ 架构说明

### 服务器端 (server.go)

服务器运行在公网上，负责：
- 监听 **6110 端口**接收来自互联网的 HTTP 请求
- 监听 **6111 端口**等待本地客户端建立 TCP 长连接
- 根据请求 URL 中的服务代码（如 `my-service`），将请求转发给对应的客户端

### 客户端 (client.go)

客户端运行在本地，负责：
- 主动连接到服务器的 **6111 端口**（配置 `SERVER_ADDR`）
- 注册自己的服务代码（如 `my-service`）
- 接收服务器转发的 HTTP 请求
- 将请求转发到本地目标服务（如 `http://localhost:5001`）
- 将本地服务的响应返回给服务器

### 工作流程图

```
公网用户浏览器
    │
    │ HTTP 请求: http://162.14.120.45:6110/my-service/api/test
    ↓
公网服务器 (监听 6111 端口)
    │
    │ 提取服务代码: my-service
    │ 查找已注册的客户端
    ↓
    ├──────────────────────────────────────────┐
    │ 通过 6111 端口的 TCP 连接转发请求         │
    └──────────────────────────────────────────┘
    ↓
本地客户端程序 (web-transfer-client)
    │ 已连接到服务器 6111 端口
    │ 已注册服务代码: my-service
    ↓
    ├──────────────────────────────────────────┐
    │ 转发请求到本地目标服务                      │
    │ http://localhost:5001/api/test           │
    └──────────────────────────────────────────┘
    ↓
你的本地服务 (如 Node.js/Python/Java 应用)
    │ 监听本地 5001 端口
    │ 处理请求并返回响应
    ↓
响应原路返回给公网用户
```

## 🚀 快速开始

### 第一步：理解你的配置

假设你的情况是：
- 公网服务器 IP: `162.14.120.45`
- 你想在本地运行一个服务（如 Web 应用）在 `localhost:5001`
- 你希望公网用户可以通过 `http://162.14.120.45:6110/my-app/...` 访问你的本地服务

那么你需要：
1. **服务器端**已经运行在 `162.14.120.45`，监听 `6110` 和 `6111` 端口
2. **本地运行客户端程序**，配置它连接到服务器的 `6111` 端口
3. **本地服务**（你的 Web 应用）监听 `5001` 端口

### 第二步：配置客户端

创建或编辑 `config.conf` 文件：

```conf
# 应用名称（用于服务名称）
APP_NAME=web-transfer-client

# 服务器地址 - 客户端程序连接这个地址
SERVER_ADDR=162.14.120.45:6111

# 本地目标服务 - 客户端将请求转发到这里
LOCAL_TARGET=http://localhost:5001

# 服务代码 - 公网访问时使用的路径前缀
SERVICE_CODE=my-app
```

**重要说明：**
- `SERVER_ADDR`：配置的是**6111 端口**，不是 6110
- `LOCAL_TARGET`：你的本地服务地址，如 `http://localhost:5001`
- `SERVICE_CODE`：自定义的服务代码，用于区分不同的客户端

### 第三步：构建客户端

#### Windows

```bash
# 使用默认配置 (config.conf)
client-scripts\build.bat

# 使用指定配置
client-scripts\build.bat my-app
```

#### Linux

```bash
# 使用默认配置
./client-scripts/build.sh

# 使用指定配置
./client-scripts/build.sh my-app
```

构建完成后，可执行文件在 `build/` 目录：
- Windows: `web-transfer-client-windows-amd64.exe`
- Linux: `web-transfer-client-linux-amd64`

### 第四步：部署服务器（如果还没有）

如果你的服务器上还没有运行服务器程序：

```bash
# 登录到服务器
ssh root@162.14.120.45

# 编译并运行服务器
go build -o web-transfer-server server.go
./web-transfer-server
```

服务器会监听：
- `6110` 端口：接收公网 HTTP 请求
- `6111` 端口：等待客户端连接

确保防火墙开放这两个端口：
```bash
# 如果使用 ufw
sudo ufw allow 6110/tcp
sudo ufw allow 6111/tcp

# 如果使用 firewalld
sudo firewall-cmd --add-port=6110/tcp --permanent
sudo firewall-cmd --add-port=6111/tcp --permanent
sudo firewall-cmd --reload
```

### 第五步：运行客户端

#### 直接运行（测试）

```bash
# Windows
.\build\web-transfer-client-windows-amd64.exe

# Linux
./build/web-transfer-client-linux-amd64
```

你会看到类似的输出：
```
========================================
Web Transfer Client 启动
========================================
服务代码: my-app
服务器地址: 162.14.120.45:6111
本地目标: http://localhost:5001
========================================
配置验证通过，开始连接服务器...
尝试连接到服务器: 162.14.120.45:6111
已连接到服务器
已注册服务代码: my-app
```

#### 部署为服务（推荐）

**Windows 服务部署：**

1. 以管理员身份运行 PowerShell 或 CMD

2. 部署服务：
```bash
client-scripts\publish.bat
```

3. 管理服务：
```bash
# 查看服务状态
client-scripts\status.bat

# 停止服务
client-scripts\stop.bat

# 卸载服务
client-scripts\unpublish.bat
```

**Linux 服务部署：**

```bash
# 部署服务（需要 root 权限）
sudo ./client-scripts/publish.sh

# 管理服务
sudo systemctl start web-transfer-client
sudo systemctl stop web-transfer-client
sudo systemctl status web-transfer-client
sudo systemctl enable web-transfer-client  # 开机自启动

# 查看日志
sudo journalctl -u web-transfer-client -f
```

### 第六步：测试访问

1. **启动你的本地服务**（监听 5001 端口）

2. **通过公网访问**：

```bash
# 浏览器访问
http://162.14.120.45:6110/my-app/

# 或使用 curl
curl http://162.14.120.45:6110/my-app/api/test
```

3. **验证请求到达本地服务**：

检查你的本地服务日志，确认收到了来自公网的请求。

## 📊 多配置管理

项目支持多个配置文件，方便管理不同的客户端实例。

### 创建新配置

```bash
# Windows
client-scripts\create-config.bat my-new-service

# 或手动创建 configs/my-new-service.conf
```

配置示例：
```conf
APP_NAME=web-transfer-client-my-new-service
SERVER_ADDR=162.14.120.45:6111
LOCAL_TARGET=http://localhost:3000
SERVICE_CODE=my-new-service
```

### 使用配置

```bash
# 构建
client-scripts\build.bat my-new-service

# 部署
client-scripts\publish.bat my-new-service

# 查看状态
client-scripts\status.bat
```

### 列出所有配置

```bash
# Windows
client-scripts\list-configs.bat

# 查看所有服务
client-scripts\list-services.bat
```

## 🎯 使用场景示例

### 场景 1：穿透本地 Web 应用

**需求**：在本地运行了一个 React 应用（端口 3000），想让朋友通过公网访问。

**配置**：
```conf
SERVER_ADDR=162.14.120.45:6111
LOCAL_TARGET=http://localhost:3000
SERVICE_CODE=react-app
```

**访问地址**：`http://162.14.120.45:6110/react-app/`

### 场景 2：穿透 API 服务

**需求**：本地开发了一个 API 服务（端口 5000），需要在外网测试。

**配置**：
```conf
SERVER_ADDR=162.14.120.45:6111
LOCAL_TARGET=http://localhost:5000
SERVICE_CODE=api-test
```

**访问地址**：`http://162.14.120.45:6110/api-test/api/users`

### 场景 3：多服务同时穿透

**需求**：同时穿透多个本地服务。

**配置 1**（configs/frontend.conf）：
```conf
APP_NAME=web-transfer-client-frontend
SERVER_ADDR=162.14.120.45:6111
LOCAL_TARGET=http://localhost:3000
SERVICE_CODE=frontend
```

**配置 2**（configs/backend.conf）：
```conf
APP_NAME=web-transfer-client-backend
SERVER_ADDR=162.14.120.45:6111
LOCAL_TARGET=http://localhost:5000
SERVICE_CODE=backend
```

**部署两个客户端**：
```bash
# 客户端 1
client-scripts\build.bat frontend
client-scripts\publish.bat frontend

# 客户端 2
client-scripts\build.bat backend
client-scripts\publish.bat backend
```

**访问地址**：
- 前端：`http://162.14.120.45:6110/frontend/`
- 后端：`http://162.14.120.45:6110/backend/api/users`

## 🔧 配置文件说明

### 客户端配置项

| 配置项 | 说明 | 必需 | 示例 |
|--------|------|------|------|
| `APP_NAME` | 应用名称（用于服务名称） | 是 | `web-transfer-client` |
| `SERVER_ADDR` | 服务器地址（IP:端口） | 是 | `162.14.120.45:6111` |
| `LOCAL_TARGET` | 本地目标服务地址 | 是 | `http://localhost:5001` |
| `SERVICE_CODE` | 服务代码（用于路由） | 是 | `my-service` |
| `CLIENT_DEPLOY_PATH` | 客户端部署路径 | 否 | Windows: `C:\Program Files\web-transfer-client`<br>Linux: `/opt/web-transfer-client` |
| `NSSM_PATH` | NSSM 安装路径（Windows） | 否 | 自动查找 |

### 服务器配置项

| 配置项 | 说明 | 必需 | 默认值 |
|--------|------|------|--------|
| `HTTP_PORT` | HTTP 服务端口（公网访问） | 否 | `8080` |
| `CLIENT_PORT` | 客户端连接端口 | 否 | `9000` |

## 🔍 故障排查

### 问题 1：客户端无法连接服务器

**症状**：
```
连接服务器失败: dial tcp 162.14.120.45:6111: connectex: No connection could be made...
```

**排查步骤**：

1. **检查服务器是否运行**：
```bash
# 在服务器上检查端口是否监听
netstat -tuln | grep 6111
```

2. **检查防火墙**：
```bash
# 服务器上检查防火墙规则
sudo ufw status
sudo firewall-cmd --list-all
```

3. **测试端口连通性**：
```bash
# 从本地测试
telnet 162.14.120.45 6111
# 或使用 nc
nc -zv 162.14.120.45 6111
```

4. **确认配置正确**：
- `SERVER_ADDR` 应该是 `162.14.120.45:6111`（客户端连接端口）
- **不是** `162.14.120.45:6110`（这是公网访问端口）

### 问题 2：公网访问返回 503 Service Unavailable

**症状**：
```
服务代码 'my-service' 的客户端未连接
```

**原因**：客户端未成功连接或注册到服务器

**排查步骤**：

1. **检查客户端日志**：
```bash
# Windows
type "C:\Program Files\web-transfer-client\service.log"

# Linux
sudo journalctl -u web-transfer-client -n 50
```

2. **确认客户端已注册**：
查找日志中的 "已注册服务代码" 消息

3. **检查服务代码是否匹配**：
- 客户端配置的 `SERVICE_CODE`
- 访问 URL 中的服务代码（如 `http://server:6110/my-service/...`）

两者必须一致！

### 问题 3：Windows 服务无法启动

**错误代码 3：系统找不到指定的路径**

**解决方法**：
```bash
# 使用修复脚本
client-scripts\fix-service.bat web-transfer-client

# 或手动设置工作目录
cd client-scripts
.\nssm.exe set web-transfer-client AppDirectory "C:\Program Files\web-transfer-client"
.\nssm.exe start web-transfer-client
```

**服务启动后立即停止**：

1. 查看错误日志：
```bash
type "C:\Program Files\web-transfer-client\service-error.log"
```

2. 手动测试可执行文件：
```bash
cd "C:\Program Files\web-transfer-client"
.\web-transfer-client-windows-amd64.exe
```

3. 检查配置是否正确加载

### 问题 4：请求超时

**症状**：请求长时间无响应，最终返回 504 Gateway Timeout

**排查步骤**：

1. **检查本地服务是否运行**：
```bash
# 测试本地服务
curl http://localhost:5001/api/test
```

2. **检查 LOCAL_TARGET 配置**：
- 确认端口正确（如 `localhost:5001`）
- 确认协议正确（`http://` 或 `https://`）

3. **检查本地服务防火墙**：
确保本地服务允许来自 localhost 的连接

## 🔒 安全建议

1. **生产环境**：
   - 使用 HTTPS（在服务器前加 Nginx 反向代理）
   - 添加身份验证机制
   - 限制允许连接的客户端 IP

2. **防火墙**：
   - 只开放必要的端口（6110、6111）
   - 使用防火墙规则限制访问

3. **服务账户**：
   - Windows 服务使用最小权限账户运行
   - Linux 服务使用专用用户运行

## 📝 配置示例文件

### 完整的服务器配置 (config.conf)

```conf
# 应用名称
APP_NAME=web-transfer

# 服务器地址
DEPLOY_HOST=162.14.120.45

# 部署路径
DEPLOY_PATH=/opt/web-transfer

# HTTP端口（接收公网请求）
HTTP_PORT=6110

# 客户端连接端口（与本地客户端通信）
CLIENT_PORT=6111

# SSH配置
DEPLOY_USER=root
DEPLOY_PORT=22
SSH_KEY=~/.ssh/id_ed25519

# 数据存储目录
DATA_DIR=/opt/web-transfer/data
```

### 完整的客户端配置 (config.conf)

```conf
# 应用名称
APP_NAME=web-transfer-client

# 服务器地址（客户端连接这个地址）
SERVER_ADDR=162.14.120.45:6111

# 本地目标服务（客户端转发到这里）
LOCAL_TARGET=http://localhost:5001

# 服务代码（用于路由）
SERVICE_CODE=my-app

# 客户端部署路径（可选）
# CLIENT_DEPLOY_PATH=C:\Program Files\web-transfer-client

# NSSM路径（可选）
# NSSM_PATH=C:\Program Files\nssm
```

## 📚 相关文档

- [客户端部署说明](client-scripts/README.md)
- [NSSM 使用说明](client-scripts/README-NSSM.md)
- [配置文件位置说明](配置文件位置说明.md)
- [配置文件用途说明](配置文件用途说明.md)
- [服务启动问题排查](服务启动问题排查.md)

## 📄 许可证

MIT License