# proxy

**Repository Path**: wangxuancheng/proxy

## Basic Information

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

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

Go 通用HTTP动态代理服务 README

# Go 通用HTTP动态代理服务
一款轻量、可配置的HTTP代理服务，支持动态转发任意接口请求到真实服务，完整透传请求头、参数、请求体及真实服务的响应状态/数据格式，支持通过.env配置文件灵活修改端口和目标服务地址。

## 功能特性
- ✅ 动态代理：适配任意接口地址，无需为每个接口单独配置路由
- ✅ 全量透传：请求方法、URL参数、请求头、请求体1:1转发
- ✅ 响应保真：原样返回真实服务的状态码、响应头、响应体
- ✅ 配置灵活：通过.env文件配置端口和目标服务地址，无需修改代码
- ✅ 容错处理：无.env文件时自动使用默认配置启动
- ✅ 服务化部署：支持Linux systemd管理，实现开机自启、状态监控

## 环境准备
- Go 1.18+（推荐最新稳定版）
- 可访问目标真实服务的网络环境
- Linux系统（若使用systemd部署）

## 快速开始

### 1. 初始化Go模块（首次使用）
在项目根目录执行，生成`go.mod`文件（替换为你的模块名，如`proxy-service`）：
```bash
go mod init proxy-service
```

### 2. 安装/整理依赖（关键步骤）
执行`go mod tidy`自动拉取依赖并清理未使用的包，确保依赖文件准确：
```bash
go mod tidy
```

### 3. 配置.env文件
在项目根目录新建`.env`文件，填写以下配置（替换为实际值）：
```env
# 真实服务的基础地址（必填，替换为你的实际地址）
TARGET_BASE_URL=https://your-real-service.com
# 代理服务监听端口（可选，默认8080）
PORT=8080
```

### 4. 运行代理服务
```bash
# 直接运行（开发调试）
go run main.go

# 编译后运行（单机部署）
go build -o proxy-server main.go
./proxy-server  # Linux/Mac
# 或
proxy-server.exe  # Windows
```

### 5. Linux系统服务部署（systemd，推荐生产环境）
通过systemd管理服务，可实现开机自启、状态监控、日志记录等功能，步骤如下：

#### 5.1 准备服务文件
在`/etc/systemd/system/`目录下新建服务文件`proxy-server.service`，内容如下（需根据实际路径修改）：
```ini
[Unit]
Description=Go 通用HTTP动态代理服务
After=network.target  # 网络启动后再启动服务

[Service]
Type=simple
User=root  # 若要切换非root用户，需先创建（如useradd -m proxy）再修改
WorkingDirectory=/www/wwwroot/go/proxy
ExecStart=/www/wwwroot/go/proxy/proxy-server
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target
```

#### 5.2 配置日志目录
创建日志目录并设置权限（确保服务运行用户有读写权限）：
```bash
# 创建日志目录
mkdir -p /var/log/proxy-server
# 设置权限（若使用非root用户，替换root为对应用户）
chown -R root:root /var/log/proxy-server
```

#### 5.3 加载并启动服务
```bash
# 重新加载systemd配置（新增服务文件后需执行）
sudo systemctl daemon-reload

# 启动代理服务
sudo systemctl start proxy-server

# 设置开机自启
sudo systemctl enable proxy-server

# 查看服务状态（验证是否启动成功）
sudo systemctl status proxy-server
```

#### 5.4 systemd常用命令
```bash
# 停止服务
sudo systemctl stop proxy-server

# 重启服务
sudo systemctl restart proxy-server

# 禁用开机自启
sudo systemctl disable proxy-server

# 查看服务日志（实时滚动）
sudo journalctl -u proxy-server -f

# 查看日志文件（直接读取日志文件）
cat /var/log/proxy-server/stdout.log
cat /var/log/proxy-server/stderr.log
```

#### 5.5 注意事项
1. 服务文件中`WorkingDirectory`和`ExecStart`的路径必须为绝对路径，且准确指向代理程序所在目录和程序文件；
2. 建议使用非root用户运行服务，需提前创建用户并确保该用户对程序目录和日志目录有读写权限；
3. 修改服务文件后，需重新执行`systemctl daemon-reload`和`systemctl restart proxy-server`使配置生效。

### 6. 交叉编译（跨平台打包，适配Linux服务器）
如需在 Windows/Mac 上编译可直接部署到 Linux 服务器的二进制文件，执行以下命令（编译后生成的`proxy-server`文件可直接在Linux x86_64服务器运行）：

#### Windows 环境
- PowerShell（单行执行）：
  ```powershell
  $env:GOOS="linux"; $env:GOARCH="amd64"; go build --ldflags "-extldflags -static -s -w" -o proxy-server .
  ```
- CMD（需分步执行，避免环境变量污染）：
  ```cmd
  set GOOS=linux
  set GOARCH=amd64
  go build --ldflags "-extldflags -static -s -w" -o proxy-server .
  # 恢复Windows环境变量（可选）
  set GOOS=windows
  set GOARCH=amd64
  ```

#### Linux/Mac 环境
```bash
GOOS=linux GOARCH=amd64 go build --ldflags "-extldflags -static -s -w" -o proxy-server .
```

#### 编译参数说明
- `--ldflags "-extldflags -static"`：静态编译，生成的二进制文件不依赖系统库，可直接在任意Linux x86_64服务器运行；
- `-s -w`：移除符号表和调试信息，减小二进制文件体积；
- `-o proxy-server`：指定编译后文件名为`proxy-server`（可自定义，如`api-proxy`）。

#### 执行权限
```
chmod +x proxy-server
```

## 配置说明
| 配置项          | 说明                                  | 默认值           |
|-----------------|---------------------------------------|------------------|
| TARGET_BASE_URL | 真实服务的基础地址（代理转发的目标）  | https://example.com |
| PORT            | 代理服务监听的端口号                  | 8080             |

## 核心逻辑说明
1. **路由规则**：默认代理所有请求（`/` 通配），也可修改代码限定前缀（如仅代理`/api/`开头的接口）：
   ```go
   // 替换main函数中的路由注册行
   http.HandleFunc("/api/", universalProxyHandler)
   ```
2. **请求透传**：排除冲突请求头（`Transfer-Encoding`/`Host`），其余全部转发；请求体读取后缓存，避免单次读取限制。
3. **响应透传**：原样复制真实服务的状态码、响应头、响应体，保证返回格式与真实服务完全一致。

## 常见问题
1. **依赖拉取失败**：检查网络是否能访问Go官方模块仓库，或配置国内代理：
   ```bash
   go env -w GOPROXY=https://goproxy.cn,direct
   ```
2. **代理返回404**：确认`TARGET_BASE_URL`配置正确，且接口路径在真实服务中存在。
3. **请求体转发异常**：确保请求体格式合法（如JSON/表单），真实服务支持对应Content-Type。
4. **编译后Linux运行报错**：使用上述交叉编译命令（带`-static`参数），避免动态库依赖问题。
5. **systemd服务启动失败**：
   - 检查服务文件中`WorkingDirectory`和`ExecStart`路径是否正确；
   - 检查运行用户对程序目录和日志目录是否有读写权限；
   - 执行`journalctl -u proxy-server`查看详细错误日志。

## 扩展建议
- 可添加请求/响应日志，便于排查问题；
- 可扩展多服务代理（按路径前缀映射不同目标服务）；
- 可添加超时配置，避免代理请求阻塞；
- 生产环境可配合Nginx做反向代理，增加HTTPS支持和负载均衡。