# GoProxy

> **智能代理池系统** — 基于 Go 的轻量级、低资源消耗、自适应的代理池服务

[![Docker Hub](https://img.shields.io/docker/v/isboyjc/goproxy?label=Docker%20Hub&logo=docker)](https://hub.docker.com/r/isboyjc/goproxy)
[![GitHub Container Registry](https://img.shields.io/badge/GHCR-latest-blue?logo=github)](https://github.com/isboyjc/GoProxy/pkgs/container/goproxy)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Go Version](https://img.shields.io/badge/Go-1.25-00ADD8?logo=go)](https://go.dev/)

GoProxy 从多个公开代理源自动抓取 HTTP/SOCKS5 代理，通过严格验证（出口 IP + 位置 + 延迟）后加入智能代理池，对外提供统一的 HTTP 代理服务。系统采用质量分级、智能补充、自动优化等机制，确保代理池始终保持高质量和稳定性。

**GitHub**：[github.com/isboyjc/GoProxy](https://github.com/isboyjc/GoProxy)

![](https://cdn.isboyjc.com/img/Xnip2026-03-29_03-35-06.png)

## ✨ 核心特性

### 🎯 智能池子机制
- **固定容量管理**：可配置池子大小和 HTTP/SOCKS5 协议比例
- **质量分级**：S/A/B/C 四级评分（基于延迟），智能选择高质量代理
- **动态状态感知**：Healthy → Warning → Critical → Emergency 四级状态自适应
- **严格准入标准**：必须通过出口 IP、地理位置、延迟三重验证才可入池
- **智能替换**：新代理必须显著优于现有代理（默认快 30%）才触发替换

### 🚀 按需抓取
- **源分组策略**：快更新源（5-30min）用于紧急补充，慢更新源（每天）用于优化轮换
- **断路器保护**：连续失败的源自动降级/禁用，冷却后恢复
- **多模式抓取**：
  - **Emergency**：单协议缺失或池子 <10%，使用所有可用源
  - **Refill**：池子 <80%，使用快更新源
  - **Optimize**：池子健康时，随机抽取少量慢源优化替换

### 🏥 分层健康管理
- **轻量批次检查**：每次仅检查 20 个代理，避免资源浪费
- **智能跳过 S 级**：池子健康时跳过 S 级代理检查
- **定时优化轮换**：健康状态下，定期抓取优质代理替换池中延迟高的

### 🔄 智能重试机制
- **自动故障切换**：代理请求失败时立即切换到另一个代理重试（最多 3 次）
- **失败即删除**：连接失败或请求超时的代理立即从池子中移除
- **用户无感知**：自动重试在服务端完成，用户只会收到成功响应或最终失败提示
- **防重复尝试**：已尝试过的失败代理不会在同一请求中再次使用

### 🚪 双端口策略
- **7777 端口（随机轮换）**：每次请求随机选择代理，IP 高度分散，适合爬虫和数据采集
- **7776 端口（最低延迟）**：固定使用延迟最低的代理，除非失败才切换，适合长连接和流媒体
- **自动切换**：两个端口都支持失败自动重试，7776 失败后切换到次优代理
- **共享池子**：两个端口使用同一个代理池，统一管理和优化
- **可选认证**：支持 Basic Auth 认证保护，对外开放时可启用

### 🎨 黑客风格 WebUI
- **Matrix 美学**：荧光绿 + 纯黑背景，CRT 扫描线效果，JetBrains Mono 等宽字体
- **双角色权限**：访客模式（只读）+ 管理员模式（完全控制），可安全公网开放
- **实时仪表盘**：池子状态、质量分布可视化、协议统计，带荧光光晕效果
- **完整配置界面**：池子容量、延迟标准、验证参数、优化策略均可在线调整（管理员）
- **代理注册表**：详细展示地址、出口 IP、位置、延迟、质量等级、使用统计
- **中英文切换**：支持中文/英文界面切换，默认中文
- **交互优化**：点击地址复制、单个代理刷新、实时日志倒计时

### 📊 适用场景
- **小型 VPS**：低资源消耗（固定池子 + 按需抓取 + 限流查询）
- **稳定需求**：自动剔除失败代理，始终保持健康池子
- **质量优先**：S/A 级代理优先使用，自动优化延迟

### 📝 扩展文档

- [地理过滤配置指南](GEO_FILTER.md) - 国家代码、使用场景、测试方法
- [数据目录说明](DATA_DIRECTORY.md) - 数据库、配置文件、备份恢复
- [代理认证测试](test/AUTH_TEST.md) - 代理认证测试和多语言客户端示例
- [测试脚本使用](test/README.md) - Bash/Go/Python 测试脚本详细说明
- [架构设计文档](POOL_DESIGN.md) - 完整的系统设计和实现细节

## 📦 项目结构

```text
.
├── main.go                        # 程序入口，协调所有模块
├── config/                        # 配置系统（池子容量、延迟标准、验证参数等）
├── pool/                          # 🆕 池子管理器（入池判断、替换逻辑、状态计算）
├── fetcher/                       # 🆕 智能抓取器（源分组、断路器、按需抓取）
│   ├── fetcher.go                 # 多模式抓取逻辑
│   ├── source_manager.go          # 源状态管理和断路器
│   └── ip_query.go                # IP查询限流和多源降级
├── validator/                     # 代理验证（连接测试 + 出口IP检测 + 地理过滤）
├── checker/                       # 🆕 分批健康检查器
├── optimizer/                     # 🆕 优化轮换器（定时优化池子质量）
├── storage/                       # 🆕 扩展存储层（质量等级、使用统计、源状态表）
├── proxy/                         # 🆕 对外 HTTP 代理服务（双端口 + 可选认证）
├── webui/                         # 🆕 黑客风格 WebUI（健康仪表盘、配置界面、RBAC）
├── logger/                        # 内存日志收集
├── test/                          # 🧪 测试脚本与文档
│   ├── test_proxy.sh              # Bash 测试脚本
│   ├── test_proxy.go              # Go 测试脚本
│   ├── test_proxy.py              # Python 测试脚本
│   ├── README.md                  # 测试脚本使用说明
│   └── AUTH_TEST.md               # 认证功能测试指南
├── .github/workflows/
│   └── docker-image.yml           # 🆕 GitHub Actions 自动构建（多平台镜像）
├── .env.example                   # 🆕 环境变量配置模板
├── docker-compose.yml             # 🆕 Docker Compose 配置（自动更新镜像）
├── Dockerfile                     # Docker 构建文件
├── data/                          # 🆕 数据目录（SQLite 数据库、配置文件）
│   └── .gitkeep                   # 目录占位符和说明
├── GEO_FILTER.md                  # 🆕 地理过滤配置指南
├── DATA_DIRECTORY.md              # 🆕 数据目录说明文档
├── POOL_DESIGN.md                 # 完整架构设计文档
└── README.md                      # 本文件
```

## 🚀 快速开始

### 运行要求
- Go `1.25`
- CGO 编译环境（依赖 `github.com/mattn/go-sqlite3`）

### 本地运行

```bash
go run .
```

或先编译再启动：

```bash
go build -o proxygo .
./proxygo
```

程序启动后会：
1. 加载配置（环境变量 + `config.json`）
2. 初始化数据库和限流器
3. 清理不符合条件的代理（屏蔽国家出口、无地理信息）
4. 启动 WebUI（`:7778`）
5. 立即执行智能填充（按需抓取 + 严格验证）
6. 启动后台协程：
   - 状态监控（每 30 秒）
   - 健康检查（默认 5 分钟）
   - 优化轮换（默认 30 分钟）
7. 启动两个代理服务（支持可选认证）：
   - `:7776` - 最低延迟模式（稳定连接）
   - `:7777` - 随机轮换模式（IP 多样性）

### 默认端口
- **代理服务（随机轮换）**：`127.0.0.1:7777` - 每次请求随机选择代理，IP 多样性高
- **代理服务（最低延迟）**：`127.0.0.1:7776` - 固定使用延迟最低的代理，性能优先
- **WebUI**：`http://127.0.0.1:7778`
- **默认密码**：`goproxy`（可通过 `WEBUI_PASSWORD` 环境变量自定义）

### 使用代理

GoProxy 提供**两个代理端口**，满足不同场景需求：

#### 🎲 7777 端口 - 随机轮换模式

适合需要 **IP 多样性** 的场景（爬虫、数据采集、负载均衡）：

```bash
curl -x http://127.0.0.1:7777 https://httpbin.org/ip
```

**特点**：
- 每次请求随机选择一个代理
- 优先使用高质量（S/A 级）代理
- IP 地址高度分散

#### ⚡ 7776 端口 - 最低延迟模式

适合需要 **稳定连接** 的场景（长连接、流媒体、实时通信）：

```bash
curl -x http://127.0.0.1:7776 https://httpbin.org/ip
```

**特点**：
- 固定使用池中延迟最低的代理
- 除非该代理失败，否则不会切换
- 失败时自动删除并切换到下一个最低延迟代理
- 性能和稳定性最优

#### 环境变量配置

**本地使用（无认证）**：
```bash
# 使用随机模式
export http_proxy=http://127.0.0.1:7777
export https_proxy=http://127.0.0.1:7777

# 或使用稳定模式
export http_proxy=http://127.0.0.1:7776
export https_proxy=http://127.0.0.1:7776
```

**远程使用（带认证）**：
```bash
# 格式：http://username:password@host:port
export http_proxy=http://proxy:your_password@192.168.1.100:7777
export https_proxy=http://proxy:your_password@192.168.1.100:7777
```

#### 端口对比

| 特性 | 7777（随机轮换） | 7776（最低延迟） |
|------|-----------------|-----------------|
| **选择策略** | 随机选择（优先高质量） | 固定使用延迟最低的 |
| **IP 多样性** | ⭐⭐⭐⭐⭐ 高度分散 | ⭐ 基本固定 |
| **连接稳定性** | ⭐⭐⭐ 每次切换 | ⭐⭐⭐⭐⭐ 固定不变 |
| **性能表现** | ⭐⭐⭐⭐ 平均延迟 | ⭐⭐⭐⭐⭐ 最优延迟 |
| **适用场景** | 爬虫、数据采集、防封禁 | 长连接、流媒体、下载 |
| **失败切换** | 自动重试 3 次 | 失败后切换到次优代理 |

#### 自动重试机制说明

当你通过 GoProxy 发送请求时，如果上游代理失败，系统会**自动处理**：

1. **立即删除失败代理**：从池子中移除不可用的代理
2. **自动切换重试**：随机选择另一个可用代理重新发送请求（最多重试 3 次）
3. **用户完全无感知**：整个过程在服务端完成，你的应用只会收到成功响应或最终失败提示
4. **防止重复尝试**：同一请求中不会重复使用已失败的代理

**示例流程**：
```
用户请求 → 代理A失败(删除) → 自动切换代理B → 代理B成功 → 返回响应
```

这意味着即使池子中有部分失效代理，你的应用依然可以正常工作，系统会自动保持池子质量。

## 🐳 Docker 部署

> 💡 **自动构建**：GitHub Actions 自动构建多架构镜像（linux/amd64、linux/arm64），默认推送到 GHCR，可选推送到 Docker Hub  
> 💾 **数据持久化**：必须挂载 `data/` 目录以保存代理池数据和配置，详见 [`DATA_DIRECTORY.md`](DATA_DIRECTORY.md)

### 🔄 GitHub Actions 自动构建

项目配置了自动化 CI/CD 流程：

**触发条件**：
- 推送到 `main` 分支 → 构建 `latest` 标签
- 推送版本标签（如 `v1.0.0`）→ 构建多个版本标签（`1.0.0`, `1.0`, `1`, `latest`）
- 手动触发（workflow_dispatch）

**镜像仓库**：
- **GHCR**（默认）：`ghcr.io/isboyjc/goproxy` - 零配置，自动推送
- **Docker Hub**（可选）：`docker.io/isboyjc/goproxy` - 需配置 secrets：
  - `DOCKERHUB_USERNAME` - Docker Hub 用户名
  - `DOCKERHUB_TOKEN` - Docker Hub Access Token

**工作流程文件**：[`.github/workflows/docker-image.yml`](.github/workflows/docker-image.yml)

### 快速启动（推荐）

使用 docker-compose，支持环境变量配置，自动拉取最新镜像：

```bash
# 1. 复制环境变量模板
cp .env.example .env

# 2. 根据需要编辑 .env（可选，默认配置即可使用）
# vim .env

# 3. 启动服务（自动拉取最新镜像）
docker compose up -d

# 4. 访问 WebUI
# http://localhost:7778（默认密码：goproxy）
```

### 使用预构建镜像（docker run）

**推荐使用 GitHub Container Registry**（自动构建，无需额外配置）：

```bash
docker pull ghcr.io/isboyjc/goproxy:latest
docker run -d --name proxygo \
  -p 127.0.0.1:7776:7776 -p 127.0.0.1:7777:7777 -p 7778:7778 \
  -e WEBUI_PASSWORD=your_password -v "$(pwd)/data:/app/data" \
  ghcr.io/isboyjc/goproxy:latest
```

**或使用 Docker Hub**（如果已配置）：

```bash
docker pull isboyjc/goproxy:latest
docker run -d --name proxygo \
  -p 127.0.0.1:7776:7776 -p 127.0.0.1:7777:7777 -p 7778:7778 \
  -e WEBUI_PASSWORD=your_password -v "$(pwd)/data:/app/data" \
  isboyjc/goproxy:latest
```

### 环境变量配置

**核心配置**（`.env` 文件）：

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `PROXY_HOST` | `127.0.0.1` | 代理服务绑定地址（`0.0.0.0` = 对外开放） |
| `BLOCKED_COUNTRIES` | `CN` | 屏蔽的国家代码（逗号分隔，如 `CN,RU`，留空=不屏蔽） |
| `PROXY_AUTH_ENABLED` | `false` | 是否启用代理认证 |
| `PROXY_AUTH_USERNAME` | `proxy` | 代理认证用户名 |
| `PROXY_AUTH_PASSWORD` | 空 | 代理认证密码 |
| `WEBUI_PASSWORD` | `goproxy` | WebUI 登录密码 |

完整环境变量列表请查看 `.env.example` 文件。

**常用配置示例**：

```bash
# 场景 1：本地使用（默认，最安全）
# 直接运行 docker compose up -d 即可

# 场景 2：对外开放 + 启用认证（推荐）
cat > .env << EOF
PROXY_HOST=0.0.0.0
PROXY_AUTH_ENABLED=true
PROXY_AUTH_USERNAME=myuser
PROXY_AUTH_PASSWORD=secure_pass_123
WEBUI_PASSWORD=admin_pass_456
BLOCKED_COUNTRIES=CN
EOF
docker compose up -d

# 场景 3：屏蔽多个国家
cat > .env << EOF
BLOCKED_COUNTRIES=CN,RU,KP,IR
WEBUI_PASSWORD=admin_pass
EOF
docker compose up -d

# 场景 4：不屏蔽任何国家
cat > .env << EOF
BLOCKED_COUNTRIES=
WEBUI_PASSWORD=admin_pass
EOF
docker compose up -d
```

### 安全部署配置

**默认配置**：代理服务仅本地访问（`127.0.0.1`），WebUI 可对外访问。

**如需对外开放代理服务**，强烈建议启用认证：

| 使用场景 | 配置建议 | 安全级别 |
|---------|---------|---------|
| **个人 VPS + 本地使用** | `PROXY_HOST=127.0.0.1`（默认） | ⭐⭐⭐⭐⭐ 最安全 |
| **团队共享 + 认证** | `PROXY_HOST=0.0.0.0` + 启用认证 | ⭐⭐⭐⭐ 安全 |
| **内网 + 防火墙** | `PROXY_HOST=0.0.0.0` + iptables 白名单 | ⭐⭐⭐ 中等 |

**启用代理认证**（编辑 `.env`）：

```bash
PROXY_HOST=0.0.0.0
PROXY_AUTH_ENABLED=true
PROXY_AUTH_USERNAME=myuser
PROXY_AUTH_PASSWORD=secure_pass_123
```

**客户端使用（带认证）**：

```bash
# 环境变量方式
export http_proxy=http://myuser:secure_pass_123@server-ip:7777
export https_proxy=http://myuser:secure_pass_123@server-ip:7777

# curl 直接指定
curl -x http://myuser:secure_pass_123@server-ip:7777 https://httpbin.org/ip

# Python requests
proxies = {'http': 'http://myuser:secure_pass_123@server-ip:7777', 'https': '...'}
```

> 💡 **认证测试指南**：详细的认证功能测试和多语言客户端示例，请查看 [`test/AUTH_TEST.md`](test/AUTH_TEST.md)

## ⚙️ 配置说明

### 配置文件示例

所有配置均可通过 WebUI 的 **Configure Pool** 界面在线调整，也可以手动编辑 `config.json`：

```json
{
  "pool_max_size": 100,
  "pool_http_ratio": 0.5,
  "pool_min_per_protocol": 10,
  "max_latency_ms": 2000,
  "max_latency_healthy": 1500,
  "max_latency_emergency": 3000,
  "validate_concurrency": 300,
  "validate_timeout": 8,
  "health_check_interval": 5,
  "health_check_batch_size": 20,
  "optimize_interval": 30,
  "replace_threshold": 0.7
}
```

### 配置参数详解

**服务端口配置**

| 参数 | 默认值 | 说明 |
| --- | --- | --- |
| `proxy_port` | `:7777` | 随机轮换代理端口 |
| `stable_proxy_port` | `:7776` | 最低延迟代理端口 |
| `webui_port` | `:7778` | WebUI 端口 |

**代理认证配置**

| 参数 | 默认值 | 说明 |
| --- | --- | --- |
| `proxy_auth_enabled` | `false` | 是否启用代理认证（对外开放时建议启用） |
| `proxy_auth_username` | `proxy` | 代理认证用户名 |
| `proxy_auth_password_hash` | 空 | 代理认证密码 SHA256 哈希（通过环境变量 `PROXY_AUTH_PASSWORD` 设置原始密码） |

> 💡 **注意**：代理认证配置通过**环境变量**设置，不在 `config.json` 中。启动时从 `PROXY_AUTH_ENABLED`、`PROXY_AUTH_USERNAME`、`PROXY_AUTH_PASSWORD` 环境变量读取。

**池子容量配置**

| 参数 | 默认值 | 说明 | 推荐范围 |
| --- | --- | --- | --- |
| `pool_max_size` | `100` | 代理池总容量 | 50-500 |
| `pool_http_ratio` | `0.5` | HTTP 协议占比 | 0.3-0.8 |
| `pool_min_per_protocol` | `10` | 每协议最少保证数量 | 5-50 |

**延迟标准配置**

| 参数 | 默认值 | 说明 | 推荐范围 |
| --- | --- | --- | --- |
| `max_latency_ms` | `2000` | 标准模式最大延迟（毫秒） | 1000-3000 |
| `max_latency_healthy` | `1500` | 健康模式严格延迟（毫秒） | 800-2000 |
| `max_latency_emergency` | `3000` | 紧急模式放宽延迟（毫秒） | 2000-5000 |

**验证与健康检查配置**

| 参数 | 默认值 | 说明 | 推荐范围 |
| --- | --- | --- | --- |
| `validate_concurrency` | `300` | 并发验证数量 | 100-500 |
| `validate_timeout` | `8` | 验证超时（秒） | 5-15 |
| `health_check_interval` | `5` | 检查间隔（分钟） | 3-15 |
| `health_check_batch_size` | `20` | 每批检查数量 | 10-50 |

**优化配置**

| 参数 | 默认值 | 说明 | 推荐范围 |
| --- | --- | --- | --- |
| `optimize_interval` | `30` | 优化轮换间隔（分钟） | 15-120 |
| `replace_threshold` | `0.7` | 替换阈值（新代理需快 30%） | 0.5-0.9 |

### 不同场景配置建议

**小型 VPS（1C2G）**
```json
{
  "pool_max_size": 50,
  "pool_http_ratio": 0.5,
  "validate_concurrency": 100,
  "health_check_interval": 10,
  "health_check_batch_size": 10,
  "optimize_interval": 60
}
```

**中型服务器（2C4G+）**
```json
{
  "pool_max_size": 200,
  "pool_http_ratio": 0.6,
  "validate_concurrency": 300,
  "health_check_interval": 5,
  "health_check_batch_size": 30,
  "optimize_interval": 30
}
```

**低延迟优先**
```json
{
  "pool_max_size": 100,
  "max_latency_ms": 1000,
  "max_latency_healthy": 800,
  "optimize_interval": 15,
  "replace_threshold": 0.8
}
```

**高可用优先（需要更多代理）**
```json
{
  "pool_max_size": 300,
  "pool_http_ratio": 0.7,
  "pool_min_per_protocol": 20,
  "max_latency_ms": 3000
}
```

### 固定配置

以下配置在代码中固定或通过环境变量设置，无需在 `config.json` 中调整：

| 配置项 | 值 | 说明 |
| --- | --- | --- |
| `WebUIPort` | `:7778` | WebUI 端口 |
| `ProxyPort` | `:7777` | 随机轮换代理端口 |
| `StableProxyPort` | `:7776` | 最低延迟代理端口 |
| `ValidateURL` | `http://www.gstatic.com/generate_204` | 验证目标地址 |
| `IPQueryRateLimit` | `10 次/秒` | IP 查询限流 |
| `SourceFailThreshold` | `3` | 源降级阈值（连续失败） |
| `SourceDisableThreshold` | `5` | 源禁用阈值（连续失败） |
| `SourceCooldownMinutes` | `30` | 源禁用冷却时间 |
| `MaxRetry` | `3` | 代理请求失败重试次数 |

**环境变量配置**（启动时读取）：

| 环境变量 | 默认值 | 说明 |
| --- | --- | --- |
| `PROXY_AUTH_ENABLED` | `false` | 是否启用代理认证 |
| `PROXY_AUTH_USERNAME` | `proxy` | 代理认证用户名 |
| `PROXY_AUTH_PASSWORD` | 空 | 代理认证密码（原始密码，自动哈希） |
| `BLOCKED_COUNTRIES` | `CN` | 屏蔽的国家代码（逗号分隔，如 `CN,RU,KP`，留空=不屏蔽） |

## 🎨 WebUI 使用指南

访问地址：`http://127.0.0.1:7778`

### 👥 双角色权限系统

GoProxy WebUI 支持**访客模式**和**管理员模式**：

#### 访客模式（只读）

**无需登录**即可访问，可以查看所有数据但不能操作：

- ✅ 查看池子状态和质量分布
- ✅ 查看代理列表和详细信息
- ✅ 查看系统日志
- ✅ 点击复制代理地址
- ❌ 不能抓取代理
- ❌ 不能刷新延迟
- ❌ 不能删除代理
- ❌ 不能修改配置

**适用场景**：
- 团队成员监控代理池状态
- 展示给客户或第三方查看
- 公网开放访问（只读数据安全）

#### ⚡ 管理员模式（完全控制）

**登录后**拥有所有操作权限：

- ✅ 所有访客模式的查看功能
- ✅ 手动触发代理抓取
- ✅ 刷新所有代理延迟
- ✅ 刷新单个代理信息
- ✅ 删除指定代理
- ✅ 修改池子配置（容量、延迟标准、检查间隔等）

**默认密码**：`goproxy`（通过环境变量 `WEBUI_PASSWORD` 自定义）

### 健康仪表盘

**四宫格指标卡**
- **Pool Status**：当前池子状态（HEALTHY/WARNING/CRITICAL/EMERGENCY）
- **Total Proxies**：总代理数 / 池子容量
- **HTTP**：HTTP 代理数 / HTTP 槽位数 + 平均延迟
- **SOCKS5**：SOCKS5 代理数 / SOCKS5 槽位数 + 平均延迟

**质量分布可视化**
- 横向条形图展示 S/A/B/C 四级质量分布
- 实时显示各级别代理数量

### 代理注册表

**表格字段**
- **Grade**：质量等级（S/A/B/C，基于延迟计算）
- **Protocol**：协议类型（HTTP/SOCKS5）
- **Address**：代理地址（host:port），点击可复制
- **Exit IP**：代理的出口 IP 地址
- **Location**：出口地理位置（国旗 emoji + 国家代码 + 城市）
- **Latency**：连接延迟（毫秒，动态颜色编码：绿/黄/橙/红）
- **Usage**：使用统计（使用总次数 / 成功次数，成功率指标）
- **Action**：操作按钮（刷新单个代理、删除代理，管理员可见）

**操作功能**

**所有用户可用**：
- **协议筛选**：下拉选择协议类型（全部/HTTP/SOCKS5）
- **国家筛选**：下拉选择出口国家（全部/动态国家列表，带国旗 emoji）
- **点击复制地址**：点击代理地址单元格直接复制到剪贴板
- **查看数据**：池子状态、质量分布、系统日志

**管理员专属**（需登录）：
- **Fetch Proxies**：手动触发智能抓取
- **Refresh Latency**：重新验证所有代理并更新延迟
- **刷新单个代理**：点击行内刷新按钮验证单个代理
- **删除代理**：点击行内删除按钮移除指定代理
- **Configure Pool**：打开配置界面修改池子参数

### 配置界面（⚡ 管理员专属）

点击 **Configure Pool** 打开配置模态框，包含：

**Pool Capacity 部分**
- Max Size：池子总容量
- HTTP Ratio：HTTP 协议占比（0.5 = 50%）
- Min Per Protocol：每协议最小保证

**Latency Standards 部分**
- Standard：标准模式延迟阈值
- Healthy：健康模式严格延迟
- Emergency：紧急模式放宽延迟

**Validation & Health Check 部分**
- Validate Concurrency：并发验证数
- Validate Timeout：验证超时
- Health Check Interval：健康检查间隔
- Health Check Batch Size：每批检查数量

**Optimization 部分**
- Optimize Interval：优化轮换间隔
- Replace Threshold：替换阈值（0.7 = 新代理需快 30%）

保存后立即生效，系统会自动调整池子策略。

## 🏗️ 核心架构

### 智能池子生命周期

```text
[启动] → 状态监控 → 判断池子健康度
              ↓
         需要补充？
          ↙     ↘
        是        否
         ↓         ↓
    智能抓取    保持监控
    (多模式)       ↓
         ↓      优化轮换
    严格验证   (定时执行)
         ↓         ↓
    智能入池    替换劣质代理
    (替换逻辑)     ↓
         ↓    分批健康检查
         ↓    (剔除失败)
         ↓         ↓
         └─────────┘
              ↓
         持续优化循环
```

### 状态转换机制

```text
Healthy (总数≥95% 且 各协议≥80%槽位)
   ↓ 代理失效
Warning (总数<95% 或 任一协议<80%)
   ↓ 继续失效
Critical (总数<50% 或 任一协议<20%槽位)
   ↓ 继续失效
Emergency (总数<10% 或 单协议缺失)
   ↑
   └─ 自动触发紧急抓取 ─┘
```

> 💡 **自动补充阈值**：当总数低于 95% 时进入 Warning 状态并触发自动补充，确保池子始终接近满容量运行。

### 抓取模式选择

| 池子状态 | 抓取模式 | 使用源 | 触发条件 |
| --- | --- | --- | --- |
| Emergency | 紧急模式 | 所有可用源 | 单协议缺失或总数<10% |
| Critical/Warning | 补充模式 | 快更新源 | 总数<95%或协议不均 |
| Healthy | 优化模式 | 慢更新源（随机2-3个） | 定时触发（30分钟） |

### 质量分级标准

| 等级 | 延迟范围 | 说明 | 权重 |
| --- | --- | --- | --- |
| S | ≤500ms | 超快，优先使用，健康状态跳过检查 | 最高 |
| A | 501-1000ms | 良好，稳定可用 | 高 |
| B | 1001-2000ms | 可用，会被优化替换 | 中 |
| C | >2000ms | 淘汰候选，优先替换 | 低 |

## 🔧 数据库 Schema

### proxies 表

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | INTEGER | 主键 |
| `address` | TEXT | 代理地址（UNIQUE） |
| `protocol` | TEXT | 协议类型（http/socks5） |
| `exit_ip` | TEXT | 出口 IP |
| `exit_location` | TEXT | 出口位置 |
| `latency` | INTEGER | 延迟（毫秒） |
| `quality_grade` | TEXT | 质量等级（S/A/B/C） |
| `use_count` | INTEGER | 使用次数 |
| `success_count` | INTEGER | 成功次数 |
| `fail_count` | INTEGER | 失败次数 |
| `last_used` | DATETIME | 最后使用时间 |
| `last_check` | DATETIME | 最后检查时间 |
| `created_at` | DATETIME | 创建时间 |
| `status` | TEXT | 状态（active/degraded/candidate_replace） |

### source_status 表

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | INTEGER | 主键 |
| `url` | TEXT | 源地址（UNIQUE） |
| `success_count` | INTEGER | 成功次数 |
| `fail_count` | INTEGER | 失败次数 |
| `consecutive_fails` | INTEGER | 连续失败次数 |
| `last_success` | DATETIME | 最后成功时间 |
| `last_fail` | DATETIME | 最后失败时间 |
| `status` | TEXT | 状态（active/degraded/disabled） |
| `disabled_until` | DATETIME | 禁用到期时间 |

## 🔍 代理源

系统内置 16 个代理源，分为快更新和慢更新两组：

**快更新源（5-30分钟更新）**
- proxifly/free-proxy-list (HTTP/SOCKS4/SOCKS5)
- ProxyScraper/ProxyScraper (HTTP/SOCKS4/SOCKS5)
- monosans/proxy-list (HTTP)

**慢更新源（每天更新）**
- TheSpeedX/SOCKS-List (HTTP/SOCKS4/SOCKS5)
- monosans/proxy-list (SOCKS4/SOCKS5)
- databay-labs/free-proxy-list (HTTP/SOCKS5)

系统会根据池子状态自动选择合适的源组：
- 紧急/补充模式：使用快更新源，快速填充
- 优化模式：随机选择慢更新源，精细优化

## 🚦 核心机制详解

### 1. 智能入池机制

每个代理在入池前需通过：
1. **连接验证**：能否成功连接 `http://www.gstatic.com/generate_204`
2. **出口 IP 检测**：获取代理的出口 IP
3. **地理位置查询**：获取出口 IP 的国家/城市
4. **延迟测试**：测量连接延迟
5. **质量评估**：根据延迟计算质量等级

**入池判断逻辑**
- ✅ 协议槽位未满：直接加入
- ✅ 槽位满但总量允许10%浮动：浮动加入
- 🔄 池子满且质量更优：替换延迟最高的现有代理（需快30%+）
- ❌ 池子满且质量不足：拒绝

### 2. 健康检查机制

**批次检查策略**
- 每次检查 20 个代理（可配置）
- 优先检查长时间未检查的
- 池子健康时跳过 S 级代理（降低资源消耗）

**检查结果处理**
- ✅ 验证通过：更新延迟、出口 IP、质量等级
- ❌ 验证失败：失败计数 +1，≥3次自动删除

### 3. 优化轮换机制

**触发条件**
- 池子状态：Healthy
- 定时触发：默认 30 分钟

**优化流程**
1. 从慢更新源随机抽取 2-3 个源
2. 抓取候选代理并验证
3. 筛选出延迟 ≤1500ms 的优质代理
4. 尝试替换池中 B/C 级代理（需快30%+）

**资源控制**
- 仅在池子健康时执行
- 抽取少量源，避免浪费
- 严格质量标准（≤1500ms）

### 4. 源管理与断路器

**状态跟踪**
- 记录每个源的成功/失败次数
- 连续失败 3 次：降级（Degraded）
- 连续失败 5 次：禁用 30 分钟（Disabled）
- 冷却期结束：自动恢复为 Active

**好处**
- 避免浪费资源在失效源上
- 自动恢复，无需人工干预
- 保护系统免受源故障影响

## 📖 常见问题

### Q: 为什么池子容量是固定的？
A: 固定容量可以：
- **可预测资源消耗**：内存、CPU、网络带宽均可控
- **提升代理质量**：通过严格准入和替换保持高质量
- **简化管理逻辑**：避免无限增长和复杂的淘汰策略

### Q: 如何调整池子大小和协议比例？
A: 
1. 访问 WebUI → 点击 **Configure Pool**
2. 修改 **Max Size** 和 **HTTP Ratio**
3. 点击 **Save Configuration**
4. 系统会自动调整槽位分配

示例：
- 池子大小 200，HTTP 比例 0.7 → HTTP 槽位 140，SOCKS5 槽位 60
- 池子大小 50，HTTP 比例 0.3 → HTTP 槽位 15，SOCKS5 槽位 35

### Q: 池子状态如何计算？
A: 
- **Healthy**：总数 ≥95% 且各协议 ≥80% 槽位
- **Warning**：总数 <95% 或任一协议 <80% 槽位
- **Critical**：总数 <50% 或任一协议 <20% 槽位
- **Emergency**：总数 <10% 或单协议缺失

### Q: 如何优化延迟？
A: 系统会自动优化，也可以手动调整：
1. 降低 `max_latency_healthy`（严格模式）
2. 增加 `optimize_interval` 频率（更频繁优化）
3. 调高 `replace_threshold`（要求新代理更快）
4. 点击 **Refresh Latency** 立即重新验证

### Q: 为什么有的代理没有出口 IP？
A: 
- IP 查询有限流（10 次/秒）
- 部分代理可能不支持 IP 查询
- 系统会在后续健康检查中补全信息
- 没有出口信息的代理会在启动时被自动清理

### Q: 如何配置地理过滤？
A: 
通过 `BLOCKED_COUNTRIES` 环境变量配置需要屏蔽的国家：

```bash
# 默认屏蔽中国大陆（CN）
BLOCKED_COUNTRIES=CN

# 屏蔽多个国家（逗号分隔）
BLOCKED_COUNTRIES=CN,RU,KP

# 不屏蔽任何国家（留空）
BLOCKED_COUNTRIES=
```

**工作机制**：
- **验证阶段**：检测到屏蔽国家出口直接拒绝入池
- **启动清理**：自动删除数据库中屏蔽国家的代理
- **精确匹配**：使用 ISO 3166-1 alpha-2 国家代码（CN、HK、US 等）

**常用国家代码**：`CN`=中国大陆 | `HK`=香港 | `RU`=俄罗斯 | `US`=美国 | `JP`=日本 | `SG`=新加坡

> 📖 **详细配置指南**：更多国家代码、使用场景、测试方法，请查看 [`GEO_FILTER.md`](./GEO_FILTER.md)

### Q: 资源消耗如何？
A: 
- **内存**：池子 100 个约 50MB，200 个约 100MB
- **CPU**：空闲时 <1%，验证时 10-30%（取决于并发数）
- **网络**：
  - IP 查询限流 10 次/秒
  - 按需抓取，避免无效流量
  - 健康检查批次小（20 个）

### Q: 代理服务如何启用认证？
A: 
1. 编辑 `.env` 文件：
   ```bash
   PROXY_AUTH_ENABLED=true
   PROXY_AUTH_USERNAME=myuser
   PROXY_AUTH_PASSWORD=mypass
   ```
2. 重启服务：`docker compose up -d`
3. 客户端使用：`http://myuser:mypass@server-ip:7777`

详细说明和测试方法请查看 [`test/AUTH_TEST.md`](./test/AUTH_TEST.md)

### Q: 代理认证和 WebUI 认证有什么区别？
A: 
- **代理认证**：保护 7776/7777 代理服务端口，防止代理被滥用
- **WebUI 认证**：保护 7778 管理后台，区分访客和管理员权限
- 两者独立配置，互不影响

## 🛠️ 开发与调试

### 查看日志

日志会输出到 stdout，同时在 WebUI 的 **System Log** 部分实时展示。

关键日志标识：
- `[pool]`：池子管理器
- `[fetch]`：抓取器
- `[source]`：源管理器
- `[health]`：健康检查器
- `[optimize]`：优化器
- `[monitor]`：状态监控器

### 数据库操作

```bash
# 查看当前代理
sqlite3 data/proxy.db "SELECT address, protocol, latency, quality_grade, status FROM proxies LIMIT 10;"

# 查看质量分布
sqlite3 data/proxy.db "SELECT quality_grade, COUNT(*) FROM proxies WHERE status='active' GROUP BY quality_grade;"

# 查看源状态
sqlite3 data/proxy.db "SELECT url, status, consecutive_fails FROM source_status;"

# 清空池子（慎用）
sqlite3 data/proxy.db "DELETE FROM proxies;"
```

## 🧪 测试代理服务

项目提供了三种测试脚本，用于验证代理服务功能和性能（位于 `test/` 目录）。

### 快速测试

```bash
# 测试随机轮换模式（默认 7777 端口）
./test/test_proxy.sh

# 测试最低延迟模式（7776 端口）
./test/test_proxy.sh 7776

# 使用 Go 脚本
go run test/test_proxy.go          # 默认 7777
go run test/test_proxy.go 7776     # 测试 7776

# 使用 Python 脚本
python test/test_proxy.py          # 默认 7777
python test/test_proxy.py 7776     # 测试 7776

# 按 Ctrl+C 停止测试并查看统计
```

测试脚本特点：
- **持续运行模式**：类似 `ping` 命令，持续发送请求
- 实时显示每次请求的出口 IP 和延迟
- 动态更新成功率统计
- 验证代理轮换机制
- 按 `Ctrl+C` 停止并显示完整统计报告

### 测试输出示例

```
PROXY 127.0.0.1:7777 (http://ip-api.com/json/?fields=countryCode,query): continuous mode

proxy from 🇺🇸 203.0.113.45: seq=1 time=1234ms
proxy from 🇩🇪 198.51.100.78: seq=2 time=987ms
proxy from 🇬🇧 192.0.2.123: seq=3 time=1567ms
proxy #4: request failed (timeout)
proxy from 🇯🇵 198.51.100.12: seq=5 time=890ms
...（持续运行，按 Ctrl+C 停止）

^C
---
50 requests transmitted, 47 received, 3 failed, 6.0% packet loss
```

**测试认证功能**：
```bash
# 启用认证后测试
curl -x http://myuser:mypass@127.0.0.1:7777 https://httpbin.org/ip

# 无认证请求（应该返回 407 错误）
curl -x http://127.0.0.1:7777 https://httpbin.org/ip
```

**更多测试指南**：
- 基础功能测试：[`test/README.md`](./test/README.md)
- 认证功能测试：[`test/AUTH_TEST.md`](./test/AUTH_TEST.md)

## 🙏 致谢与声明

本项目基于 [jonasen1988/proxygo](https://github.com/jonasen1988/proxygo) 进行魔改和增强。

### 原项目
- **项目地址**：https://github.com/jonasen1988/proxygo
- **作者**：jonasen1988
- **基础功能**：代理抓取、验证、存储、HTTP代理服务、WebUI管理

### 本项目增强功能
在原项目基础上，我们进行了大量改进和功能增强：

- 🆕 **智能池子机制**：固定容量管理、质量分级（S/A/B/C）、智能替换逻辑
- 🆕 **按需抓取策略**：源分组、断路器保护、Emergency/Refill/Optimize 多模式
- 🆕 **分层健康管理**：批次检查、智能跳过 S 级、定时优化轮换
- 🆕 **智能重试机制**：自动故障切换、失败即删除、防重复尝试
- 🆕 **双端口服务**：7777 随机轮换（IP 多样性）+ 7776 最低延迟（稳定连接）
- 🆕 **代理认证保护**：可选 Basic Auth 认证，对外开放时保护代理服务不被滥用
- 🆕 **黑客风格 WebUI**：Matrix 美学、实时仪表盘、完整配置界面、中英文切换
- 🆕 **双角色权限**：访客模式（只读）+ 管理员模式（完全控制），可安全公网开放
- 🆕 **扩展存储层**：质量等级、使用统计、源状态管理
- 🆕 **测试套件**：Bash/Go/Python 三种测试脚本，持续运行模式，显示国旗 emoji
- 🆕 **CI/CD 自动化**：GitHub Actions 自动构建多架构镜像（amd64/arm64），双仓库发布
- 🆕 **环境变量配置**：docker-compose + .env 文件，灵活配置各种部署场景

感谢原作者提供的基础实现，让我们能够在此之上构建更强大的代理池系统。

同时感谢 [LINUX DO](https://linux.do/) 社区的支持。

## 📝 License

MIT License