# WhereAmI - 多协议轮转代理工具

## 项目概述
**项目名称**：WhereAmI  
**项目描述**：基于Python的轮转代理工具，将各种外部代理（HTTP/HTTPS/SOCKS4/SOCKS5）通过本地SOCKS5转发服务部署到127.0.0.1:8745，配合Proxifier使用

---

## 核心功能需求

### 1. 多协议支持
- **输入协议**：HTTP、HTTPS、SOCKS4、SOCKS5
- **输出协议**：统一转换为本地SOCKS5代理（127.0.0.1:8745）
- **实现方式**：python先连接对应代理，然后转发到本地8745端口，应用程序连接socks5代理的8745端口即可

### 2. 代理切换机制
#### 2.1 手动切换模式
- GUI界面提供代理列表，用户可手动选择并切换到指定代理
- 显示当前使用代理的详细信息（IP、端口、延迟、状态等）

#### 2.2 自动定时切换模式
- **切换条件**：
  1. 达到设定的时间间隔（默认300秒，可配置）
  2. 且10秒内无活动连接（可配置）
- **切换策略**：
  - 按顺序切换到下一个可用节点
  - 跳过已失效或延迟过高的节点
  - 记录切换历史

### 3. 代理获取方式
#### 3.1 自动获取（网络抓取）
- **默认URL**：`http://cn.freevpnnode.com/free-proxy-for-thailand/`
- **可配置**：GUI中可修改抓取URL
- **解析流程**：
  1. 请求网页获取HTML内容
  2. 提取表格中的代理信息（参考page.html结构）
  3. 字段映射：IP地址、端口、用户名、密码、国家、协议、匿名级别、速度、运行时间、延迟、更新时间
  4. 生成JSON文件保存（格式参照local.json）
  
#### 3.2 本地文件读取
- **文件格式**：JSON（参照local.json模板）
- **必填字段**：
  ```json
  {
    "ip_address": "string",
    "port": "integer",
    "username": "string (\"no need\"表示无需认证)",
    "password": "string (\"no need\"表示无需认证)",
    "protocol": "http|https|socks4|socks5"
  }
  ```
- **可选字段**：country、anonymity、speed、uptime_percentage、response_time、latency、last_updated

### 4. 代理健康检测
#### 4.1 检测方法
- **延迟测试**：
  - TCP连接超时：5秒
  - 合格标准：< 500ms（可配置）
  - 优秀标准：< 200ms
  
- **连通性测试**：
  - Google连接测试：访问 `https://www.google.com/`
  - 超时时间：10秒
  - 预期响应：204状态码
  
#### 4.2 检测周期
- **初始检测**：获取代理后立即全量检测
- **定期复检**：每60秒检测一次正在使用的代理
- **失败重试**：连续失败3次标记为不可用，10分钟后重新检测

#### 4.3 代理分级
- **可用**：延迟<500ms 且 Google测试通过
- **优秀**：延迟<200ms 且 Google测试通过
- **不可用**：延迟>=500ms 或 Google测试失败 或 连续失败3次

### 5. GUI界面设计
#### 5.1 主界面布局
- **顶部区域**：
  - 服务状态指示器（运行/停止）
  - 当前代理信息卡片（IP、端口、协议、延迟、国家）
  - 快速操作按钮（开始/停止、立即切换）
  
- **中部区域**：
  - 代理列表表格（支持排序、筛选）
    - 列：IP、端口、协议、国家、延迟、状态、最后检测时间
    - 状态标识：可用 🟡一般 🔴不可用
  - 实时延迟趋势图（最近5分钟）
  
- **底部区域**：
  - 日志输出窗口（可清空）
  - 统计信息（总代理数、可用数、已切换次数）

#### 5.2 配置面板
- **代理源设置**：
  - 自动获取URL输入框
  - 本地文件路径选择
  - 刷新间隔设置（分钟）
  
- **轮转策略设置**：
  - 切换模式：手动 / 自动
  - 自动切换间隔（秒）
  - 无活动等待时间（秒）
  - 延迟阈值（毫秒）
  
- **输出设置**：
  - SOCKS5监听地址（默认127.0.0.1）
  - SOCKS5监听端口（默认8745）
  
- **检测设置**：
  - 检测超时时间（秒）
  - 连通性测试URL
  - 复检间隔（秒）

#### 5.3 交互功能
- 右键菜单：复制代理信息、标记为优先、删除
- 拖拽排序：调整代理优先级
- 导入/导出：配置文件、代理列表
- 历史记录：查看切换历史、性能统计

### 6. 配置管理
#### 6.1 配置文件格式（config.yaml）
```yaml
# 代理源配置
proxy_sources:
  auto_fetch:
    enabled: true
    url: "http://cn.freevpnnode.com/free-proxy-for-thailand/"
    refresh_interval: 10  # 分钟
  local_file:
    enabled: true
    path: "local.json"

# 轮转策略
rotation:
  mode: "manual"  # manual | auto
  auto_switch_interval: 300  # 秒
  min_idle_time: 10  # 无活动连接最小等待时间（秒）
  skip_high_latency: true  # 跳过延迟>阈值的代理
  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  # 连通性测试超时（秒）
  recheck_interval: 60  # 复检间隔（秒）
  max_failures: 3  # 最大失败次数
  retry_delay: 600  # 失败后重试延迟（秒）

# 日志配置
logging:
  level: "INFO"  # DEBUG | INFO | WARNING | ERROR
  file: "whereami.log"
  max_size: 10  # MB
  backup_count: 5
```

### 3. 数据流设计
```
[网页/本地文件] → [ProxyManager] → [HealthChecker] → [可用代理池]
                                              ↓
[RotationEngine] ← [无活动检测] ← [SOCKS Server] ← [客户端连接]
         ↓
    [切换代理] → [更新SOCKS Server上游]
```

---

## 异常处理与容错

### 1. 常见异常场景
- **所有代理失效**：
  - 提示用户并尝试重新获取代理
  - 保持最后一次可用的代理继续服务
  - 后台持续检测新代理
  
- **网络波动**：
  - 短暂断网（<30秒）：保持当前代理，不切换
  - 长时间断网（>=30秒）：暂停服务，显示警告
  - 网络恢复：自动重新检测并恢复服务
  
- **端口占用**：
  - 检测8745端口是否被占用
  - 如被占用，提示用户关闭占用进程或更换端口
  
- **Proxifier未运行**：
  - 仅作为提示，不影响程序运行
  - 在GUI中显示Proxifier状态建议

### 2. 数据安全
- **认证信息加密**：使用Fernet对称加密存储username/password
- **日志脱敏**：日志中隐藏完整的IP和密码信息
- **HTTPS证书**：测试时可选择跳过证书验证（配置项）

---

## 性能优化

### 2. 缓存策略
- **检测结果缓存**：缓存60秒，避免重复检测
- **代理列表缓存**：本地JSON缓存，减少网络请求
- **配置热重载**：修改配置后无需重启

### 3. 资源控制
- **最大并发检测数**：10个（可配置）
- **代理池上限**：100个（可配置）
- **内存限制**：超过阈值时清理旧数据

---

## 扩展性设计

### 1. 插件化数据源
- 定义DataSource接口，支持添加新的代理网站
- 示例：ssrfree.com、proxynova.com等

### 2. 自定义测试脚本
- 允许用户编写Python脚本自定义连通性测试方法
- 通过配置文件指定测试脚本路径

### 3. API接口（未来）
- RESTful API：获取当前代理、切换代理、获取统计
- WebSocket：实时推送代理状态变化




GUI功能细化:
实时状态显示：
    当前使用的代理信息（IP、端口、协议、延迟）
    可用代理列表及状态（在线/离线/延迟）
    历史使用记录
操作按钮：
    开始/停止服务
    立即切换下一个代理
    使用本地代理
    获取免费代理    （使用cn.freevpnnode.com源）
    获取其他代理    （预留按钮，启动scratch.py并检测）
    导入/导出配置
监控图表：
    延迟趋势图
    切换历史记录
使用一个次级页面展示配置并且可以在GUI上快速更改