GoFreeProxy

GoFreeProxy 是一个“免费代理池 + 统一入站代理入口”的单进程应用：

• 上游代理源：基于 proxifly/free-proxy-list 的 proxies/all/data.json（仅此一个数据源）。
• 后台定时拉取 → 全量验证（TCP + 协议探活）→ 形成可用池。
• 入站同端口支持：HTTP 代理 + SOCKS4 + SOCKS5（TCP）。
• 支持单账号鉴权，并支持 username-CC 通过用户名后缀指定地区（ISO alpha-2，两位大写；禁止 ZZ）。
• 每次新请求从目标可用池随机挑选上游代理（同池最多重试 2 次），并避免连续两次命中同一代理。
• 内置 /healthz 与 /metrics（Prometheus）。

本仓库的权威需求基线见 requirements.md。

1. 快速开始

1. 启动（默认读取当前目录 config.yaml，不存在会自动创建并继续启动）

go run ./cmd/gofreeproxy

2. 指定配置文件路径

go run ./cmd/gofreeproxy -c /path/to/config.yaml
# 或
go run ./cmd/gofreeproxy -config /path/to/config.yaml

3. 访问健康检查与指标

curl -sS http://127.0.0.1:19090/healthz
curl -sS http://127.0.0.1:19090/metrics

4. 使用代理（HTTP 代理示例）

curl -I -x http://admin:admin@127.0.0.1:8080 http://example.com

地区路由示例（美国）：

curl -I -x http://admin-US:admin@127.0.0.1:8080 http://example.com

注意：若 US 地区当前无可用代理，按需求将直接失败返回（不回退全局池）。

2. 配置说明

启动后若 config.yaml 不存在，会自动生成一个最小可运行模板。配置字段说明（摘录）：

• server.listen：主代理服务监听地址（默认 127.0.0.1:8080）
• server.read_timeout：兼容保留字段，当前版本固定按 30s 生效（配置值会被忽略并告警）
• auth.username/password：单账号鉴权（默认 admin/admin）
• fetch.interval/jitter/backoff：拉取周期、抖动、失败退避（默认 5m、±30s、30s→…→5m）
• validate.*：验证并发、TCP 超时、探活超时、探活 URL（默认 generate_204）
• runtime.*：单次尝试超时、重试次数、失败阈值、冷却与剔除策略
• snapshot.dir/retain：可用池快照目录与保留份数（默认 ./data，保留 3 份 gzip）
• log.*：日志目录/轮转（默认 ./data/gofreeproxy.log，50MB/7天/5份/压缩）
• metrics.listen：指标与健康检查监听地址（默认 127.0.0.1:19090）

3. 运行说明

• 首次启动若没有可用池快照，会进入“降级启动”：代理请求返回无可用代理错误；后台持续刷新，刷新成功后自动恢复服务。
• 刷新失败不会清空当前在役池；只有刷新成功才会无损替换新池。
• /healthz 返回概要字段：status、degraded、pool_total、pool_available、last_success_refresh。
• 为控制指标时序基数，Metrics 不包含 user/country 标签（详见 requirements.md 对应 RQ 条目）。

4. 致谢

本项目的上游代理数据来源于 proxifly/free-proxy-list 项目，在此对原项目及其维护者表示感谢。

5. 许可证

• proxifly/free-proxy-list 使用 GNU GPL v3 许可证。
• 本项目继承并采用相同许可证，详见仓库根目录 LICENSE 文件。