GoProxy/POOL_DESIGN.md

# GoProxy 架构设计

## 系统概览

GoProxy 是一个单二进制的智能代理池系统，由多个协作的 goroutine 组成。核心设计理念：**免费池自动运转 + 订阅池按需导入，两池独立管理但统一对外服务**。

```
                         ┌─────────────────────────┐
                         │       WebUI (:7778)      │
                         │  管理面板 / 订阅管理 / 设置 │
                         └──────────┬──────────────┘
                                    │
  ┌──────────────────┐   ┌──────────┴──────────────┐   ┌──────────────────┐
  │  免费代理源 (20+) │──▶│       SQLite 代理池       │◀──│  订阅源 (Clash/   │
  │  公开列表自动抓取  │   │  proxies / subscriptions  │   │  V2ray/Base64)   │
  └──────────────────┘   └──────────┬──────────────┘   └──────────────────┘
                                    │                           │
                         ┌──────────┴──────────────┐   ┌───────┴────────┐
                         │      对外代理服务          │   │   sing-box     │
                         │  HTTP  (:7776 / :7777)    │   │  协议转换进程   │
                         │  SOCKS5 (:7779 / :7780)   │   │  vmess/trojan  │
                         └───────────────────────────┘   │  → local socks5│
                                                         └────────────────┘
```

## 模块依赖

```
main.go (orchestrator)
  ├── config/       配置管理（环境变量 + config.json），sync.RWMutex 线程安全
  ├── storage/      SQLite 持久化（proxies + subscriptions + source_status）
  ├── fetcher/      免费代理抓取（20+ 源，断路器保护）
  ├── validator/    代理验证（连接 + 出口 IP + 地理位置 + 延迟 + HTTPS 隧道）
  ├── pool/         池子管理（slot 准入、替换逻辑、状态机）
  ├── checker/      健康检查（批次验证，free 删除 / custom 禁用）
  ├── optimizer/    质量优化（替换慢代理，仅作用于免费池）
  ├── custom/       订阅管理
  │   ├── parser.go     格式自动识别（Clash YAML / V2ray 链接 / Base64 / 纯文本）
  │   ├── singbox.go    sing-box 进程管理（配置生成 + 启停 + 端口映射）
  │   └── manager.go    刷新循环 + 探测唤醒 + 过期清理
  ├── proxy/        对外代理服务
  │   ├── server.go       HTTP 代理（支持 CONNECT 隧道）
  │   └── socks5_server.go SOCKS5 代理（原生协议实现）
  ├── webui/        管理面板（嵌入式 HTML + REST API）
  └── logger/       内存日志收集（供 WebUI 展示）
```

## 数据模型

### proxies 表

| 字段 | 类型 | 说明 |
|------|------|------|
| address | TEXT UNIQUE | 代理地址 (host:port) |
| protocol | TEXT | http / socks5 |
| source | TEXT | free / custom |
| subscription_id | INTEGER | 所属订阅 ID（0=免费） |
| exit_ip | TEXT | 出口 IP |
| exit_location | TEXT | "国家代码 城市" |
| latency | INTEGER | 延迟 (ms) |
| quality_grade | TEXT | S(<=500ms) / A(<=1000) / B(<=2000) / C(>2000) |
| status | TEXT | active / degraded / disabled / candidate_replace |
| fail_count | INTEGER | 连续失败次数 |
| use_count / success_count | INTEGER | 使用统计 |

### subscriptions 表

| 字段 | 类型 | 说明 |
|------|------|------|
| url | TEXT | 订阅 URL |
| file_path | TEXT | 本地文件路径 |
| format | TEXT | auto（全自动识别） |
| status | TEXT | active / paused |
| last_fetch | DATETIME | 最后拉取时间 |
| last_success | DATETIME | 最后有可用节点的时间 |
| contributed | INTEGER | 是否为访客贡献 |

## 免费池状态机

```
                   总量>95%
  ┌─────────────────────────────────────┐
  │                                     ▼
┌──────┐  总量<95%  ┌─────────┐  协议<20%  ┌──────────┐  缺失协议或<10%  ┌───────────┐
│HEALTHY│──────────▶│ WARNING │───────────▶│ CRITICAL │─────────────────▶│ EMERGENCY │
└──────┘           └─────────┘            └──────────┘                  └───────────┘
```

各状态对应的行为：

| 状态 | 延迟阈值 | 抓取模式 | 说明 |
|------|---------|---------|------|
| healthy | 2000ms | 不抓取 | 优化器定期替换慢代理 |
| warning | 4000ms | refill (快源) | 补充到 95% |
| critical | 4000ms | refill (快源) | 优先补充缺失协议 |
| emergency | 4000ms | emergency (全源) | 忽略断路器，全力抓取 |

## 订阅池生命周期

```
添加订阅 → 验证(拉取+解析) → 入库
                                │
        ┌───────────────────────┘
        ▼
  刷新订阅（定时/手动）
        │
        ├── 拉取内容（直连 → 代理 fallback）
        ├── 自动识别格式
        ├── 删除该订阅旧代理
        ├── 分类节点
        │   ├── HTTP/SOCKS5 → 直接入池
        │   └── vmess/trojan/... → sing-box 转换 → 本地 SOCKS5 入池
        ├── 验证入池代理（含地理过滤）
        │   ├── 通过 → status=active, 更新 last_success
        │   └── 失败/被过滤 → status=disabled
        └── 更新订阅 proxy_count
```

### 探测唤醒

```
每 N 分钟（默认 10）
    │
    ├── 获取所有 source=custom AND status=disabled 的代理
    ├── 逐个验证
    │   ├── 通过 + 未被地理过滤 → EnableProxy → 更新 last_success
    │   └── 失败 或 被地理过滤 → 保持 disabled
    └── 日志输出恢复数量
```

### 自动清理

每分钟检查：创建超过 7 天且 `last_success` 距今超过 7 天的订阅 → 删除订阅 + 关联代理 + 重建 sing-box。

## 代理选择策略

5 种模式通过 `CustomProxyMode` + `CustomPriority` + `CustomFreePriority` 三个配置组合：

| UI 选项 | Mode | Priority | FreePriority | 选择逻辑 |
|---------|------|----------|-------------|---------|
| 混合·订阅优先 | mixed | true | false | 先 custom，无可用 fallback 全部 |
| 混合·免费优先 | mixed | false | true | 先 free，无可用 fallback 全部 |
| 混合·平等 | mixed | false | false | sourceFilter=""，不区分来源 |
| 仅订阅 | custom_only | - | - | sourceFilter="custom" |
| 仅免费 | free_only | - | - | sourceFilter="free" |

HTTP 代理服务可使用 HTTP 或 SOCKS5 上游代理。SOCKS5 代理服务仅使用 SOCKS5 上游代理。

## sing-box 集成

```
订阅节点 (vmess/vless/trojan/ss/hysteria2/anytls)
    │
    ▼
生成 sing-box JSON 配置：
  inbounds:  每个节点一个本地 SOCKS5 端口 (20001, 20002, ...)
  outbounds: 每个节点对应一个加密协议出站
  route:     inbound → outbound 一一映射
    │
    ▼
启动 sing-box 子进程 (sing-box run -c config.json)
    │
    ▼
本地 socks5://127.0.0.1:20001 ... 入池为 source=custom 代理
```

Docker 镜像自带 sing-box 二进制，支持 amd64/arm64。本地运行需手动安装。

## 后台 Goroutine

| Goroutine | 间隔 | 职责 |
|-----------|------|------|
| 状态监控 | 30s | 检查免费池状态，触发 smartFetchAndFill |
| 健康检查 | 5min | 批量验证代理，free 删除 / custom 禁用 |
| 优化轮换 | 30min | 替换免费池中的慢代理 |
| 订阅刷新 | 1min tick | 检查到期订阅，执行刷新 |
| 探测唤醒 | 10min | 探测 disabled 的订阅代理 |
| 配置监听 | event | WebUI 配置变更后调整 slot |

## 地理过滤

全局生效，对两个池子行为不同：

| 操作 | 免费代理 | 订阅代理 |
|------|---------|---------|
| 启动清理 | DELETE | status → disabled |
| 验证时不通过 | 不入池 | 入池但 disabled |
| 探测唤醒 | - | 被过滤的不启用 |
| 配置变更 | 下次清理生效 | 下次清理生效 |

白名单（`AllowedCountries`）优先于黑名单（`BlockedCountries`）。

## 端口映射

| 端口 | 服务 | 模式 |
|------|------|------|
| 7776 | HTTP 代理 | 最低延迟 |
| 7777 | HTTP 代理 | 随机轮换 |
| 7778 | WebUI | 管理面板 |
| 7779 | SOCKS5 代理 | 随机轮换 |
| 7780 | SOCKS5 代理 | 最低延迟 |
| 20001+ | sing-box 本地 | 仅 127.0.0.1 |