youfak/proxy-pool

Fork 0

youfak 6257265e14 docs: refresh project README

2026-07-30 21:58:34 +08:00

9.1 KiB

Raw Blame History

Proxy Pool

项目定位

面向多供应商动态代理资源的集中控制、独占提取与高并发转发平台。

Proxy Pool 将供应商接入、短 TTL 代理活动池和管理状态集中到 Controller，同时提供三类边界清晰的访问方式。集群 100,000 QPS 是设计目标，尚未经过代表性环境的负载测试证明。

项目背景

不同代理供应商的响应格式、鉴权方式、计费方式和代理存活时间并不一致；部分代理只有几十秒有效期。系统还需要同时处理容量预留、健康状态、路由切换、一次性提取和高并发转发。

Proxy Pool 用 Controller 协调这些变化，并让 Gateway 数据面只消费节点内存中的不可变快照，避免在转发热路径查询 PostgreSQL、Redis 或 Provider API。

使用方式

Gateway：调用方连接平台，由平台选择上游代理并转发 HTTP 或 HTTPS CONNECT。当前已有传输、调度和保护链组件，命令进程与控制面快照客户端待装配。
Distribution：调用方按条件提取真实代理；成功提取即独占消费，不支持归还、续租或状态查询。
Admin：运维人员查询状态、启停 Upstream、切换 Routing，并触发严格配置重载。Admin 与 Distribution 已由 Controller 运行在独立监听器上。

核心能力

严格配置：配置版本 1、YAML 未知字段拒绝、Secret 引用解析、公开监听保护、引用和容量边界校验。
Provider 获取与协调：Provider HTTP Client、响应上限、模板解析、分布式 Leader/请求额度、退避和补池 Supervisor 已接入 Controller。
Redis 活动池：短 TTL Proxy Upsert、去重、健康更新、Worker ownership、库存、过期清理、Distribution 幂等与分布式限流均使用原子操作或有界流程。
Distribution：支持 partial / allOrNothing、TTL 与健康过滤、Gateway 库存预留，以及 AVAILABLE -> EXTRACTED 的一次性独占提取。
Controller 入口：proxy-controller 已装配 Distribution、Admin、Metrics、 PostgreSQL 迁移与 Redis 活动池，并支持联动优雅停机。
PostgreSQL 管理面：持久化配置版本、Upstream/Routing 管理状态、Admin 审计与 Outbox；不保存 Proxy 明细或逐次提取记录。
Gateway 组件：HTTP 正向代理、HTTPS CONNECT、双向 Tunnel、重试、超时、目的地址保护、本地快照存储和容量调度已有实现与定向测试，但尚无 proxy-gateway 命令和控制面客户端。
安全边界：Gateway、Distribution 与 Admin 使用各自的认证语义，并支持 CIDR、可信代理、严格请求解析和敏感信息最小化。

架构概览

flowchart LR
    Client[调用方] -->|HTTP / CONNECT| Gateway[Gateway<br/>进程待装配]
    Client -->|独占提取| Distribution[Distribution]
    Operator[运维人员] -->|管理操作| Admin[Admin]
    subgraph CP[proxy-controller 已运行]
        Distribution --> Controller[Controller]
        Admin --> Controller
    end
    Controller -->|Fetch| Provider[Provider API]
    Controller --> Redis[(Redis)]
    Controller --> PostgreSQL[(PostgreSQL)]
    Checker[Checker<br/>健康链待闭环] -. Observation .-> Controller
    Controller -. Snapshot 链待闭环 .-> Gateway

PostgreSQL 只保存管理面状态，不保存 Proxy 明细或逐次提取记录。
Redis 保存短 TTL Proxy 活动池、Provider 协调、Distribution 幂等与分布式限流等可重建的短期状态。
Gateway 热路径 只读取节点内存，不查询 PostgreSQL、Redis 或 Provider API。

当前完成度

截至 2026-07-30，实施计划检查项为 52 / 74（70.3%）。详情见实施计划和交付完成度审计。

已完成：严格配置、Provider 获取与协调、Redis 活动池、Distribution 原子提取与限流、Controller 的 Admin/Distribution/Metrics 监听，以及 PostgreSQL 管理状态。
部分完成：Gateway 传输与调度组件、Snapshot 本地存储、Worker ownership 与运行态领域组件、Docker Compose/Kubernetes 静态部署清单和 protobuf 契约。
待完成：WorkerControlPlane gRPC session/snapshot/ACK 闭环、Checker 调度与健康状态链、Gateway 进程与快照客户端、完整 Routing 运行链，以及 loadgen 和代表性集群压测。

检查项数量不等于生产就绪度。静态部署清单与 protobuf descriptor 验证也不代表端到端拓扑已经完成；100,000 QPS 仍只是待验证的集群设计目标。

快速开始

前置条件为 Go 1.26、PowerShell，以及用于 fixture 测试的 Docker。先在当前 PowerShell 会话设置本地占位凭据；这些值仅用于本地验证：

$env:PROXY_POOL_GATEWAY_PASSWORD = "LOCAL_GATEWAY_PASSWORD"
$env:PROXY_POOL_EXTRACT_TOKEN = "LOCAL_EXTRACT_TOKEN"
$env:PROXY_POOL_ADMIN_TOKEN = "LOCAL_ADMIN_TOKEN"
$env:PROVIDER_A_TOKEN = "LOCAL_PROVIDER_A_TOKEN"
$env:PROVIDER_B_TOKEN = "LOCAL_PROVIDER_B_TOKEN"
$env:PROXY_POOL_CONFIG_FINGERPRINT_KEY = "LOCAL_HIGH_ENTROPY_KEY_AT_LEAST_32_BYTES"

PROXY_POOL_CONFIG_FINGERPRINT_KEY 在 Admin 启用时必须至少为 32 字节，并与业务 Secret 分离管理。

校验配置并执行仓库验证：

go run ./deploy/tools/configcheck deploy/config/local.yaml
./scripts/verify.ps1

Redis、PostgreSQL 和 Controller fixture 脚本会使用 Docker 启动隔离依赖：

./scripts/test-redis.ps1
./scripts/test-postgres.ps1
./scripts/test-controller.ps1

PostgreSQL 与 Redis 是 Controller 的启动依赖。确保它们在 deploy/config/local.yaml 配置的地址可达后，启动当前已实现的 Controller 进程：

go run ./cmd/proxy-controller -config deploy/config/local.yaml

本地配置中的 .invalid Provider URL 是故障演示占位，不会提供真实代理。当前仓库没有 Gateway、Checker 或 loadgen 命令，因此不提供对应启动命令。

关键配置与入口

本地配置与完整配置参考
Distribution API：默认本地入口 http://127.0.0.1:8081
Admin API：默认本地入口 http://127.0.0.1:8082
Controller Metrics：默认本地入口 http://127.0.0.1:9090，提供 /livez、 /readyz 和 /metrics
控制面协议：Worker/Checker 的 protobuf 契约； gRPC 运行链尚未闭环
运维手册：依赖、探针、发布边界与故障处置

核心不变量

Gateway 热路径只读节点内存，不访问 PostgreSQL、Redis 或 Provider API。
Proxy 容量使用 Reserved -> Active 原子转换，禁止超卖。
Distribution 成功时原子执行 AVAILABLE -> EXTRACTED；提取后不归还、不续租。
pool.maxSize 是当前未提取库存硬上限；fetch.maxTotal 是 Redis generation 内的累计获取停止阈值。
CONNECT 向客户端提交 200 后不透明重放。
公开监听必须有认证或 CIDR 访问保护。
PostgreSQL 只保存管理面状态；Proxy 明细只存在于 Redis 短 TTL 活动池和节点内存，Redis 中的短期状态可由 Provider 重建。

路线图

P0 - Worker 控制面闭环：Worker session、Snapshot ledger、ACK、运行态接收、 ownership 索引，以及 Gateway 快照客户端。
P0 - Checker 健康链：Checker 调度、实际探测、Observation reducer，以及 FETCHED -> AVAILABLE / SUSPECT / UNHEALTHY 状态链。
P1 - Gateway 与 Routing：proxy-gateway 命令、五种 Routing 策略、 onUnavailable、动态容量调整和 Drain 闭环。
P1 - 可观测与部署：低基数业务指标、完整 Compose/Kubernetes 进程拓扑，以及故障转移和恢复演练。
P2 - 容量证明：proxy-loadgen、HTTP/CONNECT/Extract 分场景压测，以及可复现的代表性 100,000 QPS 集群报告。

文档导航

设计与需求

开发与 API

部署与运维

审计与测试

9.1 KiB Raw Blame History Unescape Escape