Metadata-Version: 2.1
Name: wsocks
Version: 1.1.4
Summary: UNKNOWN
Home-page: https://github.com/sazima/WSocks
License: UNKNOWN
Platform: UNKNOWN
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: tornado
Requires-Dist: websockets
Requires-Dist: xxhash (>=3.0.0)
Requires-Dist: msgpack
Requires-Dist: pycryptodome (>=3.18.0)
Requires-Dist: uvloop (<0.15) ; sys_platform != "win32" and python_version < "3.7"
Requires-Dist: uvloop ; sys_platform != "win32" and python_version >= "3.7"
Requires-Dist: winloop (>=0.1.0) ; sys_platform == "win32"
Provides-Extra: no-uvloop

# SOCKS5/HTTP WebSocket 代理

基于 WebSocket 的高性能代理工具，支持 SOCKS5 和 HTTP CONNECT 协议，用于网络穿透和流量转发。

## 原理

```
本地应用 <--SOCKS5/HTTP--> 客户端 <--WebSocket--> 服务端 <--TCP--> 目标服务器
```

- **客户端**：在本地启动代理服务器（支持 SOCKS5 和 HTTP CONNECT），将流量通过 WebSocket 转发到远程服务端
- **服务端**：接收 WebSocket 连接，代理访问目标服务器
- 单端口自动识别协议类型（SOCKS5 / HTTP CONNECT）
- 使用 WebSocket 连接池，提升并发性能
- 通过密码和消息签名保证连接安全

## 与v2ray性能对比

测试环境：同一服务器节点（跨洋线路（RTT ~260ms））

### 延迟对比

| 测试目标 | wsocks | v2ray | 结果 |
|---------|--------|-------|------|
| Google | 654 ms | 661 ms | 快 7 ms |
| YouTube | 995 ms | 1101 ms | 快 106 ms |
| **平均延迟** | **825 ms** | **881 ms** | **快 56 ms** |

### 下载速度对比

| 指标 | wsocks | v2ray |
|------|--------|-------|
| 平均速度 | 0.47 MB/s | 0.43 MB/s |
| 峰值速度 | 0.76 MB/s | 0.49 MB/s |

测试脚本和测试数据参考 speed_test 目录

## 安装

```bash
pip install wsocks
```
如安装过程中提示 uvloop 安装失败，可以跳过 uvloop：

```bash
pip install 'wsocks[no-uvloop]'
```

## 使用方法

### 1. 服务端配置

编辑 `config_server.json`：

```json
{
  "server": {
    "host": "0.0.0.0",
    "port": 8888,
    "path": "/ws",
    "password": "your-password-here"
  },
  "log_level": "INFO"
}
```

### 2. 启动服务端

在有公网 IP 的服务器上运行：

```bash
wsocks_server -c config_server.json
```

### 3. 客户端配置

编辑 `config_client.json`：

```json
{
  "server": {
    "url": "ws://your-server.com:8888/ws",
    "password": "your-password-here",
    "compression": false,
    "ws_pool_size": 8,
    "heartbeat_enabled": true,
    "heartbeat_min": 20,
    "heartbeat_max": 50,
    "use_fingerprint": false,
    "impersonate": "chrome124"
  },
  "local": {
    "host": "127.0.0.1",
    "port": 1080
  },
  "udp": {
    "enabled": false,
    "timeout": 60
  },
  "log_level": "INFO"
}
```

**TLS 指纹伪装说明**:
- `use_fingerprint`: 设置为 `true` 启用 TLS 指纹伪装（需要 Python 3.10+ 和 `curl_cffi==0.14.0`， `pip install curl_cffi==0.14.0`）
- `impersonate`: 指定浏览器指纹，支持 Chrome、Safari、Firefox、Edge, [支持的浏览器指纹列表](#支持的浏览器指纹列表)
- 开发阶段，可能不稳定，如不需要此功能，保持 `use_fingerprint: false` 即可，无需安装额外依赖

正式使用务必自行配置使用wss

### 4. 启动客户端

```bash
wsocks_client -c config_client.json
```

### 5. 配置代理

支持两种代理方式（同一端口自动识别）：

**SOCKS5 代理**：
- 服务器：`127.0.0.1`
- 端口：`1080`

**HTTP 代理**：
- 服务器：`http://127.0.0.1:1080`

## 配置参数说明

### 服务端参数

| 参数 | 说明 | 默认值 |
|------|------|--------|
| host | 监听地址 | 0.0.0.0 |
| port | 监听端口 | 8888 |
| password | 连接密码 | - |
| timeout | 连接超时（秒） | 30 |
| max_connections | 最大并发连接数 | 1000 |

### 客户端参数

| 参数 | 说明 | 默认值   |
|------|------|-------|
| server.url | 服务端地址 | -     |
| server.password | 连接密码 | -     |
| server.compression | 启用数据压缩 | false |
| server.ws_pool_size | WebSocket 连接池大小 | 8     |
| server.heartbeat_enabled | 启用应用层随机心跳 | true  |
| server.heartbeat_min | 心跳最小间隔（秒） | 20    |
| server.heartbeat_max | 心跳最大间隔（秒） | 50    |
| server.use_fingerprint | 启用 TLS 指纹伪装 | false |
| server.impersonate | 浏览器指纹（chrome99-136/safari153-260/firefox133,135） | chrome124 |
| local.port | 本地代理端口（支持 SOCKS5 / HTTP） | 1080  |
| udp.enabled | 启用 UDP 转发（SOCKS5 UDP Associate） | false |
| udp.timeout | UDP 会话超时时间（秒） | 60    |



## 分流规则配置

在 `config_client.json` 中添加 `routing` 字段即可启用分流。未配置时所有流量走代理（与旧版行为一致）。

### 基本结构

```json
"routing": {
  "default": "proxy",
  "rules": [...]
}
```

| 字段 | 说明 | 可选值 |
|------|------|--------|
| `default` | 未命中任何规则时的默认动作 | `proxy` / `direct` / `block` |
| `rules` | 规则列表，按顺序匹配，首次命中即返回 | — |

### 规则类型

#### `domain_suffix` — 域名后缀匹配

匹配域名本身及所有子域名，如 `.cn` 同时匹配 `example.cn` 和 `sub.example.cn`。

```json
{
  "type": "domain_suffix",
  "value": [".cn", ".com.cn", ".edu.cn", ".gov.cn"],
  "action": "direct"
}
```

#### `domain` — 精确域名匹配

```json
{
  "type": "domain",
  "value": ["www.google.com", "api.github.com"],
  "action": "proxy"
}
```

#### `domain_keyword` — 域名关键词匹配

域名中包含关键词即命中。

```json
{
  "type": "domain_keyword",
  "value": ["baidu", "taobao", "alibaba"],
  "action": "direct"
}
```

#### `ip_cidr` — IP 段匹配

```json
{
  "type": "ip_cidr",
  "value": ["127.0.0.0/8", "192.168.0.0/16", "10.0.0.0/8", "172.16.0.0/12"],
  "action": "direct"
}
```

#### `ruleset` — 从文件加载规则

适合加载较大的规则集（如国内域名列表）。`path` 为规则文件路径（相对于工作目录或绝对路径）。

```json
{
  "type": "ruleset",
  "path": "direct.lst",
  "action": "direct"
}
```

规则文件支持两种格式，可混用：

```
# 注释以 # 开头

# 格式一：纯域名（视为 domain_suffix，匹配本身及子域名）
baidu.com
qq.com
taobao.com

# 格式二：Surge / Clash 风格
DOMAIN-SUFFIX,weibo.com
DOMAIN,www.jd.com
DOMAIN-KEYWORD,alipay
```

### 动作说明

| 动作 | 说明 |
|------|------|
| `proxy` | 通过 WebSocket 代理转发 |
| `direct` | 直接连接目标，不经过代理 |
| `block` | 拒绝连接 |

### 典型配置示例

#### 国内直连，境外走代理

```json
"routing": {
  "default": "proxy",
  "rules": [
    {
      "type": "ip_cidr",
      "value": ["127.0.0.0/8", "192.168.0.0/16", "10.0.0.0/8", "172.16.0.0/12"],
      "action": "direct"
    },
    {
      "type": "domain_suffix",
      "value": [".cn", ".com.cn", ".edu.cn", ".gov.cn", ".net.cn", ".org.cn"],
      "action": "direct"
    },
    {
      "type": "ruleset",
      "path": "direct.lst",
      "action": "direct"
    }
  ]
}
```

#### 仅代理被墙域名，其余直连（黑名单模式）

```json
"routing": {
  "default": "direct",
  "rules": [
    {
      "type": "ruleset",
      "path": "proxy.lst",
      "action": "proxy"
    }
  ]
}
```

> **说明**：`proxy.lst` 可由 GUI 工具将 GFWList 预处理后生成，wsocks-core 只读取标准格式文件。

### 规则匹配优先级

1. 规则按 **声明顺序** 依次匹配，首次命中即返回，后续规则不再检查
2. IP 地址请求优先走 `ip_cidr` 规则，域名请求走其余规则
3. 未命中任何规则时使用 `default` 动作

## 支持的浏览器指纹列表

| Browser         | Open Source                                                                                                                                                                         | Pro version                                                                |
|-----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|
| Chrome          | chrome99, chrome100, chrome101, chrome104, chrome107, chrome110, chrome116[1], chrome119[1], chrome120[1], chrome123[3], chrome124[3], chrome131[4], chrome133a[5][6], chrome136[6] | chrome132, chrome134, chrome135                                            |
| Chrome Android  | chrome99_android, chrome131_android [4]                                                                                                                                             | chrome132_android, chrome133_android, chrome134_android, chrome135_android |
| Chrome iOS      | N/A                                                                                                                                                                                 | coming soon                                                                |
| Safari [7]      | safari153 [2], safari155 [2], safari170 [1], safari180 [4], safari184 [6], safari260 [8]                                                                                            | coming soon                                                                |
| Safari iOS [7]  | safari172_ios[1], safari180_ios[4], safari184_ios [6], safari260_ios [8]                                                                                                            | coming soon                                                                |
| Firefox         | firefox133[5], firefox135[7]                                                                                                                                                        | coming soon                                                                |
| Firefox Android | N/A                                                                                                                                                                                 | firefox135_android                                                         |
| Tor             | tor145 [7]                                                                                                                                                                          | coming soon                                                                |
| Edge            | edge99, edge101                                                                                                                                                                     | edge133, edge135                                                           |
| Opera           | N/A                                                                                                                                                                                 | coming soon                                                                |
| Brave           | N/A                                                                                                                                                                                 | coming soon                                                                |


## 常见问题

**无法连接服务端**
- 检查服务端是否运行
- 确认防火墙端口已开放
- 验证密码是否一致

**上传速度慢**
- 增加 `ws_pool_size`（建议 8-32）

**连接频繁断开**
- 调整 `ping_interval` 和 `ping_timeout`
- 增加服务端 `timeout` 值
-

## 安全建议

- 修改默认密码，使用强密码
- 务必使用 WSS（WebSocket over TLS）
- 配置防火墙限制访问 IP

## 许可证

MIT License



