# pyroxy

**Repository Path**: pgpoem/pyroxy

## Basic Information

- **Project Name**: pyroxy
- **Description**: 基于 Python 的异步 TCP 代理服务器
- **Primary Language**: Unknown
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-27
- **Last Updated**: 2026-01-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# Pyroxy - TCP Relay Proxy Server

## 简介

Pyroxy 是一个基于 Python 的 TCP 中继代理服务器，支持自定义数据处理器进行数据转发和转换。

## 功能特性

- **TCP 代理中继**：在客户端和上游服务器之间转发 TCP 数据
- **异步处理**：使用 Python asyncio 实现高并发连接处理
- **可扩展的数据处理器**：支持自定义数据处理逻辑
- **灵活的配置**：通过配置文件轻松设置代理参数

## 核心组件

### TCPRelayProxy
主代理服务器类，负责管理客户端连接和上游连接。

主要方法：
- `__init__`：初始化代理服务器参数
- `start`：启动代理服务
- `handle_client_connection`：处理客户端连接
- `handle_upstream_connection`：处理上游服务器连接
- `forward_data`：转发数据
- `remove_client`：移除客户端连接

### DataProcessor
抽象数据处理器基类，定义数据处理接口。

核心方法：
- `process(raw_data: bytes) -> List[bytes]`：处理原始数据并返回处理后的数据列表

### DefaultDataProcessor
默认的数据处理器实现，提供基础的数据处理功能。

## 安装

1. 克隆项目：
```bash
git clone https://gitee.com/pgpoem/pyroxy.git
cd pyroxy
```

2. 安装依赖：
```bash
pip install -r requirements.txt
```

## 配置

编辑 `cfg.ini` 文件配置代理参数：

```ini
[proxy]
upstream_host = 上游服务器地址
upstream_port = 上游服务器端口
proxy_host = 代理监听地址
proxy_port = 代理监听端口
```

## 使用方法

### 基本使用

```python
from TCPRelayProxy import TCPRelayProxy
from DefaultDataProcessor import DefaultDataProcessor

# 创建代理实例
proxy = TCPRelayProxy(
    upstream_host="127.0.0.1",
    upstream_port=8080,
    proxy_host="0.0.0.0",
    proxy_port=8888,
    data_processor=DefaultDataProcessor()
)

# 启动代理服务
asyncio.run(proxy.start())
```

### 自定义数据处理器

```python
from TCPRelayProxy import TCPRelayProxy
from DataProcessor import DataProcessor

class CustomDataProcessor(DataProcessor):
    def process(self, raw_data: bytes) -> List[bytes]:
        # 自定义数据处理逻辑
        # ...
        return [processed_data]

# 使用自定义处理器
proxy = TCPRelayProxy(
    upstream_host="127.0.0.1",
    upstream_port=8080,
    proxy_host="0.0.0.0",
    proxy_port=8888,
    data_processor=CustomDataProcessor()
)

asyncio.run(proxy.start())
```

## 项目结构

```
pyroxy/
├── TCPRelayProxy.py      # 主代理服务器实现
├── DataProcessor.py      # 数据处理器抽象基类
├── DefaultDataProcessor.py  # 默认数据处理器
├── test.py               # 测试代码
├── cfg.ini               # 配置文件
├── pyproject.toml        # 项目配置
└── README.md             # 项目说明文档
```

## 依赖管理

项目使用 `pyproject.toml` 管理依赖，主要依赖包括：
- Python 3.7+
- asyncio（标准库）

## 许可证

本项目遵循 LICENSE 文件中指定的许可证协议。

## 贡献

欢迎提交 Issue 和 Pull Request 来改进本项目。