268 lines
8.6 KiB
Markdown
268 lines
8.6 KiB
Markdown
# WhereAmI - 多协议轮转代理工具
|
||
|
||
## 项目简介
|
||
|
||
WhereAmI 是一个基于 Python 和 PyQt6 的现代化多协议轮转代理工具，能够将各种外部代理（HTTP/HTTPS/SOCKS4/SOCKS5）通过本地 SOCKS5 转发服务部署到 `127.0.0.1:8745`，配合 Proxifier 等工具使用。
|
||
|
||
## 核心特性
|
||
|
||
### 🚀 三步工作流程
|
||
1. **验证代理**：并发测试所有代理的连通性，对 SOCKS5 代理进行握手验证
|
||
2. **获取代理**：从验证通过的代理列表中选择可用代理作为上游代理
|
||
3. **转发到 8745 端口**：启动 SOCKS5 服务器监听 8745 端口，双向转发数据
|
||
|
||
### 🎯 主要功能
|
||
- ✅ **多协议支持**：HTTP、HTTPS、SOCKS4、SOCKS5
|
||
- ✅ **自动获取代理**：从指定网页抓取代理列表
|
||
- ✅ **本地文件支持**：从 JSON 文件加载代理配置
|
||
- ✅ **健康检测**：TCP 延迟测试 + Google 连通性测试
|
||
- ✅ **代理轮转**：手动切换 / 自动定时切换
|
||
- ✅ **实时状态监控**：GUI 界面显示代理状态、延迟、统计信息
|
||
- ✅ **日志记录**：详细的运行日志，支持文件和控制台输出
|
||
|
||
## 技术栈
|
||
|
||
- **开发语言**: Python 3.9+
|
||
- **GUI 框架**: PyQt6
|
||
- **网络请求**: requests, aiohttp
|
||
- **HTML 解析**: BeautifulSoup4, lxml
|
||
- **配置文件**: PyYAML
|
||
- **SOCKS 支持**: PySocks
|
||
- **日志系统**: loguru
|
||
- **加密**: cryptography
|
||
|
||
## 安装步骤
|
||
|
||
### 1. 克隆项目
|
||
```bash
|
||
git clone <repository-url>
|
||
cd WhereAmI
|
||
```
|
||
|
||
### 2. 安装依赖
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 3. 运行程序
|
||
```bash
|
||
python main.py
|
||
```
|
||
|
||
## 使用说明
|
||
|
||
### 快速开始
|
||
|
||
1. **启动程序**
|
||
```bash
|
||
python main.py
|
||
```
|
||
|
||
2. **配置代理源**
|
||
- 点击 "⚙️ 配置" 按钮
|
||
- 设置自动获取 URL（默认已配置为泰国代理网站）
|
||
- 或启用本地文件模式
|
||
|
||
3. **获取代理**
|
||
- 点击 "🌐 获取免费代理" 按钮
|
||
- 程序会自动从网页抓取并检测代理
|
||
|
||
4. **启动服务**
|
||
- 点击 "▶ 开始服务" 按钮
|
||
- 服务将在 `127.0.0.1:8745` 启动 SOCKS5 代理
|
||
|
||
5. **配置 Proxifier**
|
||
- 打开 Proxifier
|
||
- 添加代理服务器：`127.0.0.1:8745`，类型选择 SOCKS5
|
||
- 设置代理规则，将需要代理的应用添加到规则中
|
||
|
||
6. **切换代理**
|
||
- 手动切换：点击 "🔄 切换下一个" 按钮
|
||
- 自动切换：在配置中设置为 auto 模式
|
||
|
||
### 配置说明
|
||
|
||
配置文件 `config.yaml` 包含以下主要配置项：
|
||
|
||
```yaml
|
||
# 代理源配置
|
||
proxy_sources:
|
||
auto_fetch:
|
||
enabled: true # 是否启用自动获取
|
||
url: "http://cn.freevpnnode.com/free-proxy-for-thailand/" # 抓取URL
|
||
refresh_interval: 10 # 刷新间隔（分钟）
|
||
local_file:
|
||
enabled: true # 是否启用本地文件
|
||
path: "local.json" # 本地文件路径
|
||
|
||
# 轮转策略
|
||
rotation:
|
||
mode: "manual" # manual | auto
|
||
auto_switch_interval: 300 # 自动切换间隔（秒）
|
||
latency_threshold: 500 # 延迟阈值（毫秒）
|
||
|
||
# 输出配置
|
||
output:
|
||
host: "127.0.0.1" # 监听地址
|
||
port: 8745 # 监听端口
|
||
|
||
# 检测配置
|
||
health_check:
|
||
timeout: 5 # TCP连接超时（秒）
|
||
connectivity_test_url: "https://www.google.com/"
|
||
connectivity_timeout: 10 # 连通性测试超时（秒）
|
||
max_failures: 3 # 最大失败次数
|
||
retry_delay: 600 # 重试延迟（秒）
|
||
```
|
||
|
||
### 本地代理文件格式
|
||
|
||
项目使用两个JSON文件来管理代理：
|
||
|
||
#### 1. `proxy.json` - 自动抓取的代理（自动生成）
|
||
此文件由程序自动创建，保存从网页抓取的代理列表。**不要手动编辑此文件**，每次获取新代理时会被覆盖。
|
||
|
||
#### 2. `local.json` - 用户手动添加的代理（推荐）
|
||
此文件用于存放您自己的可靠代理。格式示例：
|
||
|
||
```json
|
||
[
|
||
{
|
||
"ip_address": "192.168.1.100",
|
||
"port": 1080,
|
||
"username": "no need",
|
||
"password": "no need",
|
||
"protocol": "socks5",
|
||
"country": "CN",
|
||
"anonymity": "elite",
|
||
"speed": "fast",
|
||
"uptime_percentage": "99%",
|
||
"response_time": "100ms",
|
||
"latency": "50ms",
|
||
"last_updated": "now"
|
||
}
|
||
]
|
||
```
|
||
|
||
**必填字段：**
|
||
- `ip_address`: 代理 IP 地址
|
||
- `port`: 代理端口
|
||
- `username`: 用户名（无认证填 "no need"）
|
||
- `password`: 密码（无认证填 "no need"）
|
||
- `protocol`: 协议类型（http/https/socks4/socks5）
|
||
|
||
**可选字段：**
|
||
- `country`: 国家代码
|
||
- `anonymity`: 匿名级别
|
||
- `speed`: 速度描述
|
||
- `uptime_percentage`: 在线率
|
||
- `response_time`: 响应时间
|
||
- `latency`: 延迟
|
||
- `last_updated`: 最后更新时间
|
||
|
||
## GUI 界面说明
|
||
|
||
### 主界面布局
|
||
|
||
#### 顶部状态栏
|
||
- **状态指示器**：显示服务运行状态（运行中/已停止）
|
||
- **当前代理信息**：显示正在使用的代理 IP、端口、协议、延迟
|
||
- **统计信息**：显示总代理数、可用数、优秀数、不可用数
|
||
|
||
#### 控制按钮区
|
||
- **▶ 开始服务**：启动 SOCKS5 代理服务（需要先选择一个代理节点）
|
||
- **⏹ 停止服务**：停止代理服务
|
||
- **🔄 切换下一个**：切换到下一个可用代理
|
||
- **🌐 获取免费代理**：从网页抓取代理并检测（默认功能）
|
||
- **📁 使用本地代理**：仅加载 `local.json` 中的代理
|
||
- **🔧 其他代理（预留）**：暂未实现，预留用于后续测试
|
||
- **⚙️ 配置**：打开配置对话框
|
||
|
||
#### 标签页
|
||
1. **代理列表**：显示所有代理的详细信息表格
|
||
- 列：IP地址、端口、协议、国家、状态、延迟、匿名级别、速度、运行时间、最后更新
|
||
- 状态颜色：🟢 优秀、🟡 可用、🔴 不可用、⚪ 未知
|
||
- **过滤选项**："显示不可用代理"复选框，控制是否显示不可用的代理
|
||
- **选择代理**：点击表格行来选择要使用的代理节点
|
||
|
||
2. **连接日志**：显示所有通过代理的连接记录
|
||
- 格式：`[时间戳] 本地IP:端口 -> 远程代理IP:端口`
|
||
- 示例：`[2026-06-14 22:30:15] 127.0.0.1:54321 -> 192.168.1.100:1080`
|
||
- 支持清空日志
|
||
|
||
3. **日志**：显示程序运行日志
|
||
- 支持清空日志
|
||
- 显示时间戳和详细操作信息
|
||
|
||
## 常见问题
|
||
|
||
### Q1: 如何测试代理是否工作？
|
||
A: 启动服务后，使用 curl 命令测试：
|
||
```bash
|
||
curl -x socks5://127.0.0.1:8745 https://ip.sb
|
||
```
|
||
|
||
### Q2: 为什么有些代理显示为不可用？
|
||
A: 代理可能因为以下原因被标记为不可用：
|
||
- TCP 连接超时（>5秒）
|
||
- Google 连通性测试失败
|
||
- 连续失败 3 次以上
|
||
|
||
### Q3: 如何添加自己的代理？
|
||
A: 编辑 `local.json` 文件，按照格式添加您的可靠代理信息。程序会自动合并 `proxy.json`（抓取的代理）和 `local.json`（手动添加的代理）。建议优先使用 `local.json` 添加稳定可靠的代理。
|
||
|
||
### Q4: 端口 8745 被占用怎么办？
|
||
A: 在配置中修改监听端口，或使用以下命令查找占用进程：
|
||
```bash
|
||
netstat -ano | findstr "8745"
|
||
```
|
||
|
||
### Q5: 如何实现自动切换代理？
|
||
A: 在配置中将 `rotation.mode` 设置为 `"auto"`，并设置 `auto_switch_interval` 为期望的切换间隔（秒）。
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
WhereAmI/
|
||
├── main.py # 主入口
|
||
├── config.yaml # 配置文件
|
||
├── proxy.json # 自动抓取的代理（程序自动生成）
|
||
├── local.json # 用户手动添加的代理（推荐）
|
||
├── requirements.txt # 依赖包
|
||
├── README.md # 项目说明
|
||
├── core/ # 核心逻辑
|
||
│ ├── __init__.py
|
||
│ ├── models.py # 数据模型
|
||
│ ├── data_source.py # 数据源获取
|
||
│ ├── health_checker.py # 健康检测器
|
||
│ ├── proxy_manager.py # 代理管理器
|
||
│ └── simple_proxy_forwarder.py # 简化转发器
|
||
├── gui/ # GUI界面
|
||
│ ├── __init__.py
|
||
│ └── main_window.py # 主窗口
|
||
├── utils/ # 工具类
|
||
│ └── __init__.py
|
||
└── logs/ # 日志目录
|
||
└── whereami.log
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. **首次运行**：请确保安装了所有依赖包
|
||
2. **代理质量**：免费代理稳定性较差，建议定期更新代理列表
|
||
3. **安全性**：不要在免费代理上登录敏感账户或传输机密数据
|
||
4. **法律合规**：请遵守当地法律法规，合理使用代理服务
|
||
|
||
## 许可证
|
||
|
||
本项目仅供学习和研究使用。
|
||
|
||
## 贡献
|
||
|
||
欢迎提交 Issue 和 Pull Request！
|
||
|
||
---
|
||
|
||
**版本**: v1.0.0
|
||
**更新日期**: 2026-06-14
|