# python-kcp-proxy

**Repository Path**: david9988/python-kcp-proxy

## Basic Information

- **Project Name**: python-kcp-proxy
- **Description**: python-kcp-proxy
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-08
- **Last Updated**: 2026-03-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# KCP Proxy

基于 KCP 协议的高性能 SOCKS5 代理系统，采用 AES-128-GCM 加密。

## 功能特性

- **SOCKS5 协议支持**：完整实现 SOCKS5，支持 CONNECT 和 UDP ASSOCIATE 命令
- **KCP 协议**：快速可靠的基于 UDP 的传输协议
- **AES-128-GCM 加密**：提供数据传输的认证加密
- **自动重连**：客户端在连接丢失时自动重连到服务器
- **跨平台**：纯 Python 实现，支持 Linux、macOS 和 Windows

## 环境要求

- Python 3.10+
- kcp-py >= 0.1.5
- cryptography >= 41.0.0

## 安装

### 使用 uv（推荐）

[uv](https://github.com/astral-sh/uv) 是一个极快的 Python 包安装器和虚拟环境管理器。

#### 全局安装 uv（可选）

```bash
pip install uv
# 或
curl -LsSf https://astral.sh/uv/install.sh | sh
```

#### 创建虚拟环境并安装依赖

```bash
# 创建虚拟环境
uv venv

# 激活虚拟环境
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate   # Windows

# 安装依赖
uv sync
```

#### 安装到现有环境

```bash
# 安装包和依赖
uv pip install kcp-proxy

# 开发者安装（包含 dev 依赖）
uv pip install -e ".[dev]"
```

### 从 PyPI 安装

```bash
pip install kcp-proxy
```

### 从源码安装

```bash
git clone https://github.com/yourusername/kcp-proxy.git
cd kcp-proxy
pip install -e .
```

### 开发者安装

```bash
pip install -e ".[dev]"
```

这将以可编辑模式安装包以及开发依赖（pytest 等）。

## 项目结构

```
python-kcp-proxy/
├── kcp_proxy/              # 主要包
│   ├── __init__.py        # 包导出
│   ├── cli.py             # 命令行接口入口点
│   ├── client.py          # KCPProxyClient、SOCKS5Server 类
│   ├── crypto.py          # AES-128-GCM 加密
│   ├── kcp_session.py     # KCP 会话管理
│   ├── server.py          # KCPServer 类
│   ├── socks5.py          # SOCKS5 协议实现
│   └── utils.py           # 工具函数
├── tests/                 # 测试套件
│   ├── __init__.py
│   ├── packet_counter.py  # 包统计工具（性能分析）
│   ├── test_self.py
│   ├── test_integration.py
│   ├── test_units.py
│   └── ...
├── pyproject.toml         # 项目配置
├── requirements.txt       # 依赖项
└── README.md              # 本文件
```

## 使用方法

### 使用 CLI（推荐）

#### 服务器

启动 KCP 代理服务器：

```bash
kcp-proxy-server --port 8388 --key "your-secret-key"
```

选项：
- `--port, -p`：UDP 监听端口（默认：8388）
- `--host, -H`：绑定的主机（默认：0.0.0.0）
- `--key, -k`：加密密钥（必需）
- `--log-level, -L`：日志级别（DEBUG, INFO, WARNING, ERROR）

#### 客户端

启动本地 SOCKS5 代理客户端：

```bash
kcp-proxy-client --server 1.2.3.4 --server-port 8388 --key "your-secret-key" --listen-port 1080
```

选项：
- `--server, -s`：KCP 服务器主机（必需）
- `--server-port, -p`：KCP 服务器端口（默认：8388）
- `--key, -k`：加密密钥（必需）
- `--listen-host, -H`：本地 SOCKS5 监听主机（默认：127.0.0.1）
- `--listen-port, -l`：本地 SOCKS5 监听端口（默认：1080）
- `--log-level, -L`：日志级别（DEBUG, INFO, WARNING, ERROR）

### 直接使用 Python

#### 服务器

```bash
python -m kcp_proxy.server --port 8388 --key "your-secret-key"
```

#### 客户端

```bash
python -m kcp_proxy.client --server 1.2.3.4 --server-port 8388 --key "your-secret-key"
```

## 快速开始

1. **在远程服务器上启动服务端**：
   ```bash
   kcp-proxy-server --port 8388 --key "my-secret-password"
   ```

2. **在本地机器上启动客户端**：
   ```bash
   kcp-proxy-client --server your.server.ip --server-port 8388 --key "my-secret-password"
   ```

3. **使用 SOCKS5 代理**（通过 curl）：
   ```bash
   curl -x socks5h://127.0.0.1:1080 https://www.example.com
   ```

4. **或在浏览器中配置** SOCKS5 代理为 `127.0.0.1:1080`

## 架构说明

```
┌─────────────┐      SOCKS5      ┌─────────────┐      KCP+AES      ┌─────────────┐
│   客户端    │ ─────────────► │   客户端    │ ───────────────►  │   服务器    │
│   应用      │    连接         │   代理      │    UDP 数据包     │   代理      │
└─────────────┘                  └─────────────┘                   └─────────────┘
                                        │                                 │
                                        │                                 ▼
                                        │                          ┌─────────────┐
                                        └──────────────────────────│   目标      │
                                             TCP 转发              │   服务器    │
                                                                   └─────────────┘
```

## KCP 参数优化

### 默认配置

```python
KCP_INTERVAL = 10        # ms, KCP 更新间隔
KCP_SNDWND = 256         # 发送窗口大小
KCP_RCVWND = 512         # 接收窗口大小
KCP_TIMEOUT = 60         # 秒，连接超时
no_congestion_control = True  # 关闭拥塞控制
```

### 高丢包网络优化

在丢包率较高的网络环境下（如跨国链路），建议：

1. **关闭拥塞控制** (`no_congestion_control=True`)：
   - 拥塞控制在检测到丢包时会大幅降低发送窗口
   - 关闭后依靠 KCP 重传机制保证可靠性
   - 可提升 20-30 倍吞吐量

2. **增加重传次数** (`resend_count=5`)：
   - 默认 2 次，高丢包环境建议 5 次
   - 平衡延迟和可靠性

3. **使用包统计工具分析**：
   ```bash
   # 服务端
   python -m tests.packet_counter server -p 8388 -k "your-key"

   # 客户端
   python -m tests.packet_counter client -s server:8388 -k "your-key" -l 1080
   ```

   观察指标：
   - UDP 发送/接收比率（判断丢包）
   - KCP 发出/接收流量（判断应用数据吞吐）
   - 活跃会话数（判断并发连接）

## 安全考虑

1. **使用强加密密钥**：密钥通过 SHA256 派生 AES-128 密钥
2. **启用防火墙**：仅允许服务器端口的 UDP 流量
3. **使用 HTTPS**：通过代理访问敏感数据时始终使用 HTTPS
4. **更改默认端口**：避免使用默认的 8388 端口
5. **高丢包网络性能**：在丢包率>5% 的网络下，关闭拥塞控制可显著提升性能

## 性能说明

### 拥塞控制的影响

在丢包率较高的网络环境下（如跨国链路）：

| 场景 | 拥塞控制开启 | 拥塞控制关闭 |
|------|-------------|-------------|
| 丢包率 5% | 吞吐量下降 80%+ | 吞吐量稳定 |
| 丢包率 10% | 几乎无法浏览 | 正常浏览 |
|  YouTube 加载 | 请求 pending | 正常播放 |

**建议**：如果网络质量较差，保持 `no_congestion_control=True`。

### 瓶颈分析

使用 `tests/packet_counter.py` 进行性能分析：
- **UDP 发送/接收**：判断网络层丢包
- **KCP 发出/接收**：判断应用层吞吐
- **活跃会话**：判断并发连接健康度

## 运行测试

### 使用 uv

```bash
# 激活虚拟环境
source .venv/bin/activate

# 运行所有测试
pytest tests/

# 运行特定测试文件
pytest tests/test_self.py
pytest tests/test_units.py
pytest tests/test_integration.py

# 详细输出
pytest -v tests/
```

### 使用 pip（备用）

```bash
# 安装测试依赖
pip install -e ".[dev]"

# 运行所有测试
pytest tests/

# 运行特定测试文件
pytest tests/test_self.py
pytest tests/test_units.py
pytest tests/test_integration.py

# 详细输出
pytest -v tests/
```

## 开发

### 代码结构

- `kcp_proxy/crypto.py`：AES-128-GCM 加密，基于计数器的 nonce
- `kcp_proxy/kcp_session.py`：带加密的 KCP 会话封装
- `kcp_proxy/socks5.py`：SOCKS5 握手和请求解析
- `kcp_proxy/utils.py`：地址解析/编码工具
- `kcp_proxy/server.py`：服务端 KCP 会话管理
- `kcp_proxy/client.py`：客户端 KCP 会话，支持自动重连
- `kcp_proxy/cli.py`：CLI 入口点

### KCP 配置

默认 KCP 参数在 `KCPSession` 和 `KCPClientSession` 中：

- `KCP_INTERVAL = 10` ms
- `KCP_SNDWND = 256` 发送窗口
- `KCP_RCVWND = 512` 接收窗口
- `KCP_TIMEOUT = 60` 秒
- `no_congestion_control = True` (关闭拥塞控制，适合高丢包网络)
- `resend_count = 5` (重传次数)

**注意**：在高丢包网络环境下，关闭拥塞控制 (`no_congestion_control=True`) 可显著提升性能。

## 许可证

MIT 许可证