| .. | ||
| README.md | ||
Proxy Pool Mermaid 图集
本图集依据最终需求语义绘制。图中的 100k QPS 是待压测验证的集群目标；Extract 均表示一次性独占发放，不存在 Lease、Renew 或 Release。
01 系统上下文
flowchart LR
Client[Gateway Client] --> LB[Layer 4 Load Balancer]
ExtractClient[Extract Client] --> Dist[Distribution API]
Operator[Operator] --> Admin[Admin API]
LB --> Gateway[Gateway Cluster]
Gateway --> Internet[Target via Proxy]
Dist --> Controller[Controller Cluster]
Admin --> Controller
Controller --> Provider[Provider APIs]
Controller --> Checker[Checker Cluster]
Controller --> PG[(PostgreSQL)]
Controller --> Redis[(Redis)]
02 进程职责边界
flowchart TB
subgraph DataPlane[Data Plane]
G[proxy-gateway]
Snap[Immutable Snapshot]
G --> Snap
end
subgraph ControlPlane[Control Plane]
C[proxy-controller]
K[proxy-checker]
C <--> K
end
subgraph Tools[Tools]
L[proxy-loadgen]
end
C -->|Snapshot and ownership| G
G -->|batched outcomes| C
L --> G
03 领域模块依赖
flowchart TD
Cmd[cmd assembly] --> Gateway[gateway modules]
Cmd --> Controller[controller modules]
Cmd --> Adapters[adapters]
Gateway --> Domain[domain]
Controller --> Domain
Adapters --> Domain
Domain -. no import .-> HTTP[(HTTP)]
Domain -. no import .-> SQL[(SQL)]
Domain -. no import .-> Redis[(Redis)]
04 Gateway 请求路径
sequenceDiagram
participant C as Client
participant G as Gateway
participant D as Dispatcher
participant T as Transport
participant P as Proxy
C->>G: HTTP request
G->>G: auth and admission
G->>D: acquire route
D->>D: reserve capacity with CAS
D-->>G: allocation
G->>T: execute
T->>P: dial and handshake
P-->>T: response
T-->>C: stream response
T->>D: release active and report
05 CONNECT 提交点
stateDiagram-v2
[*] --> Accepted
Accepted --> Reserved: Acquire
Reserved --> Dialing: dial proxy
Dialing --> Cancelled: fail before commit
Dialing --> Active: proxy CONNECT succeeds
Active --> TunnelCommitted: send 200 to client
TunnelCommitted --> Closed: stream ends
Cancelled --> [*]
Closed --> [*]
note right of TunnelCommitted: transparent replay forbidden
06 HTTP 安全重试决策
flowchart TD
F[Attempt failed] --> H{Headers sent to client?}
H -->|yes| Stop[Do not retry]
H -->|no| M{Method allowed?}
M -->|no| Stop
M -->|GET or HEAD| A{Attempts remain?}
A -->|no| Stop
A -->|yes| X[Exclude failed Proxy]
X --> N[Acquire another Proxy]
07 Routing 首条命中
flowchart TD
Req[RouteRequest] --> R1{Rule 1 matches?}
R1 -->|yes| U1[Use Rule 1 upstream strategy]
R1 -->|no| R2{Rule 2 matches?}
R2 -->|yes| U2[Use Rule 2 upstream strategy]
R2 -->|no| RN{Default rule matches?}
RN -->|yes| UN[Use default strategy]
RN -->|no| Reject[Apply onUnavailable]
08 Sequential 原子切换
sequenceDiagram
participant F1 as Fetch goroutine 1
participant F2 as Fetch goroutine 2
participant U as Upstream A counter
participant R as Routing state
F1->>U: empty reaches threshold
F2->>U: concurrent empty
U->>R: depleted generation 7
U->>R: depleted generation 7
R->>R: CAS A to B succeeds once
R-->>F1: current B
R-->>F2: current B
09 Provider Fetch 调度
flowchart TD
Signal[Capacity signal] --> SF{Fetch already running?}
SF -->|yes| Merge[Merge into bounded signal]
SF -->|no| Leader[Acquire logical leader]
Leader --> Demand[Recompute slot demand]
Demand --> Limit{Below maxSize and maxTotal?}
Limit -->|no| Done[Stop]
Limit -->|yes| Rate[Wait requestInterval]
Rate --> Call[Call Provider under maxInFlight]
Call --> Classify[Classify result]
10 Fetch 结果分类
flowchart LR
Response[Provider response] --> Transport{Transport and auth valid?}
Transport -->|no| Error[Error and backoff]
Transport -->|yes| Parse{Template and parse valid?}
Parse -->|no| Error
Parse -->|yes| Legal{Legal candidates count}
Legal -->|zero| Empty[Empty plus one]
Legal -->|positive| New{New after dedupe?}
New -->|none| Duplicate[Duplicate-only and reset Empty]
New -->|some| Success[Success and reset Empty]
11 退避与 Retry-After
stateDiagram-v2
[*] --> Ready
Ready --> Calling: rate token acquired
Calling --> Ready: success or empty
Calling --> RetryAfter: HTTP 429
Calling --> Backoff: timeout or server error
RetryAfter --> Ready: provider deadline reached
Backoff --> Ready: exponential delay plus jitter
Backoff --> Open: max attempts exhausted
Open --> Ready: next scheduled cycle
12 Pool Reconcile
flowchart TD
Inventory[Managed inventory] --> Count[Count states and pending expected]
Capacity[Available slots] --> Need[Compute demand]
Count --> Bound{pool maxSize reached?}
Need --> Bound
Bound -->|yes| NoFetch[Do not fetch]
Bound -->|no| Quota{fetch maxTotal reached?}
Quota -->|yes| NoFetch
Quota -->|no| Fetch[Schedule bounded fetch]
13 Proxy 生命周期
stateDiagram-v2
[*] --> FETCHED
FETCHED --> CHECKING
CHECKING --> AVAILABLE: passed
CHECKING --> UNHEALTHY: exhausted
AVAILABLE --> SUSPECT: meaningful failure
SUSPECT --> AVAILABLE: recheck passed
SUSPECT --> UNHEALTHY: failures reached
AVAILABLE --> DRAINING: expiry or revoke
AVAILABLE --> EXTRACTED: exclusive transaction
DRAINING --> EXPIRED: capacity zero
UNHEALTHY --> REMOVED
EXTRACTED --> EXPIRED: TTL reached
EXPIRED --> REMOVED
14 原子容量转换
flowchart LR
C0[active A reserved R] --> Check{A plus R below limit?}
Check -->|no| Full[Reject candidate]
Check -->|yes CAS| Reserved[active A reserved R plus 1]
Reserved -->|Commit| Active[active A plus 1 reserved R]
Reserved -->|Cancel| C0
Active -->|Release| C0
15 Worker 所有权
flowchart TB
Controller[Controller allocator] -->|epoch 12| W1[Worker 1]
Controller -->|epoch 12| W2[Worker 2]
P1[Proxy shard A] --> W1
P2[Proxy shard B] --> W2
U[Unowned inventory] --> Controller
W1 -. cannot allocate .-> P2
W2 -. cannot allocate .-> P1
16 Snapshot 发布与 ACK
sequenceDiagram
participant DB as PostgreSQL
participant C as Controller
participant W as Worker
DB->>C: outbox revision 42
C->>C: build worker snapshot
C->>W: epoch 8 version 42 checksum
W->>W: validate and build indexes
W->>W: atomic swap
W-->>C: ACK epoch 8 version 42
C->>DB: mark outbox delivered
17 Snapshot 缺口恢复
flowchart TD
Delta[Receive delta version 45] --> Current{Current version is 44?}
Current -->|yes| Check[Verify checksum and epoch]
Current -->|no current 42| Reject[Reject delta]
Reject --> Full[Request full snapshot]
Full --> Build[Build indexes in background]
Check --> Apply[Apply delta atomically]
Build --> Apply
18 Snapshot 陈旧状态
stateDiagram-v2
[*] --> Fresh
Fresh --> StaleAllowed: controller disconnected
StaleAllowed --> Fresh: valid snapshot received
StaleAllowed --> DrainOnly: maxStaleAge exceeded
DrainOnly --> Fresh: full snapshot and new epoch
DrainOnly --> Stopped: existing traffic drained
19 健康任务调度
flowchart TD
Proxies[Proxy inventory] --> Priority{State priority}
Priority -->|new| New[Immediate basic check]
Priority -->|SUSPECT| Fast[Fast recheck]
Priority -->|stable AVAILABLE| Normal[Normal interval]
New --> Jitter[Stable hash plus jitter]
Fast --> Jitter
Normal --> Jitter
Jitter --> Bound[maxInFlight semaphore]
Bound --> Checker[Checker workers]
20 健康 Observation Reducer
flowchart LR
Obs[Health Observation] --> Scope{Scope}
Scope -->|global| Global[Global health reducer]
Scope -->|route target| Target[Target profile reducer]
Global --> Consecutive[Consecutive outcome state]
Consecutive --> Transition[AVAILABLE SUSPECT UNHEALTHY]
Target --> RouteHealth[Only affected route health]
RouteHealth -. no direct global delete .-> Transition
21 Extract partial
sequenceDiagram
participant C as Client
participant API as Distribution
participant DB as PostgreSQL
C->>API: count 10 fulfillment partial
API->>DB: lock eligible rows
DB-->>API: 6 rows
API->>DB: update 6 to EXTRACTED and audit
DB-->>API: commit
API-->>C: requested 10 returned 6
22 Extract allOrNothing
sequenceDiagram
participant C as Client
participant API as Distribution
participant DB as PostgreSQL
C->>API: count 10 fulfillment allOrNothing
API->>DB: lock eligible rows
DB-->>API: only 6 rows
API->>DB: rollback entire transaction
API-->>C: insufficient inventory and returned 0
23 Gateway 所有权回收后提取
sequenceDiagram
participant C as Controller
participant W as Gateway Worker
participant DB as PostgreSQL
C->>W: mark Proxy DRAINING at epoch 13
W->>W: stop new allocations
W-->>C: ACK active 0 reserved 0
C->>DB: clear worker ownership
C->>DB: AVAILABLE to EXTRACTED plus audit
DB-->>C: committed exclusive result
24 reserveForGateway 不变量
flowchart TD
Eligible[Eligible unowned count] --> Formula[extractable equals eligible minus reserve]
Reserve[reserveForGateway] --> Formula
Requested[requested count] --> Min[return min requested and extractable]
Formula --> Min
Min --> Result{fulfillment}
Result -->|partial| Commit[Commit available quantity]
Result -->|allOrNothing insufficient| Rollback[Return zero]
25 PostgreSQL 独占事务
flowchart TD
Begin[BEGIN] --> Select[SELECT eligible FOR UPDATE SKIP LOCKED]
Select --> Enough{Quantity satisfies mode?}
Enough -->|no allOrNothing| Rollback[ROLLBACK]
Enough -->|yes or partial| Update[UPDATE AVAILABLE to EXTRACTED]
Update --> Audit[INSERT extraction records]
Audit --> Outbox[INSERT outbox]
Outbox --> Commit[COMMIT]
Commit --> Return[Return proxies with expiry]
26 并发提取互斥
sequenceDiagram
participant A as Extract request A
participant DB as PostgreSQL
participant B as Extract request B
A->>DB: lock rows 1 to 10
B->>DB: skip locked rows 1 to 10
B->>DB: lock rows 11 to 20
A->>DB: commit EXTRACTED 1 to 10
B->>DB: commit EXTRACTED 11 to 20
Note over A,B: no Proxy returned twice
27 Outbox 一致性
sequenceDiagram
participant C as Controller transaction
participant DB as PostgreSQL
participant P as Publisher
participant W as Worker
C->>DB: state change plus outbox
DB-->>C: atomic commit
P->>DB: read undelivered event
P->>W: publish versioned event
W-->>P: idempotent ACK
P->>DB: mark delivered
28 配置热更新
flowchart LR
File[Read revision] --> Parse[Strict parse]
Parse --> Validate[References regex and security]
Validate --> Build[Build immutable config]
Build --> Diff[Diff tasks and resources]
Diff --> Swap[Atomic swap]
Swap --> Drain[Drain removed resources]
Validate -->|error| Keep[Keep old revision]
29 Gateway 优雅停机
sequenceDiagram
participant K as Kubernetes
participant G as Gateway
participant LB as Load Balancer
K->>G: SIGTERM
G->>G: readiness false
LB->>LB: remove endpoint
G->>G: reject new connections
G->>G: drain requests and tunnels
G->>G: release active capacities
G-->>K: exit before grace timeout
30 Controller 优雅停机
flowchart TD
Term[SIGTERM] --> NotReady[Readiness false]
NotReady --> StopWrites[Stop new Extract and Admin writes]
StopWrites --> StopFetch[Stop new Fetch]
StopFetch --> FinishTx[Commit or rollback current transactions]
FinishTx --> Flush[Flush outbox and reports]
Flush --> Lease[Release Provider leader lease]
Lease --> Exit[Close pools and exit]
31 Kubernetes 故障域拓扑
flowchart TB
LB[Load Balancer] --> ZA
LB --> ZB
LB --> ZC
subgraph ZA[Zone A]
GA1[Gateway]
CA[Controller]
KA[Checker]
end
subgraph ZB[Zone B]
GB1[Gateway]
CB[Controller]
KB[Checker]
end
subgraph ZC[Zone C]
GC1[Gateway]
CC[Controller]
KC[Checker]
end
32 Gateway 扩缩决策
flowchart TD
Metrics[QPS CPU memory connections latency] --> HPA[HPA decision]
HPA --> Up{Above target?}
Up -->|yes| ScaleUp[Scale up quickly]
Up -->|no| Stable{Stable below target for 10m?}
Stable -->|no| Hold[Hold replicas]
Stable -->|yes| Capacity{Failure-domain headroom remains?}
Capacity -->|no| Hold
Capacity -->|yes| ScaleDown[Scale down at most 10 percent]
33 网络信任边界
flowchart LR
Internet --> NLB[Public NLB]
NLB --> Gateway[Gateway 8080]
Ingress[Private Ingress] --> Distribution[Distribution 8081]
Operator[Operator VPN] --> Admin[Admin 8082]
Monitor[Monitoring namespace] --> Metrics[Metrics 9090]
Gateway --> PublicTargets[Public targets only]
Controller[Controller] --> Stores[External PG and Redis]
Controller --> Providers[Provider APIs]
34 可观测信号流
flowchart LR
Gateway -->|bounded metrics| Prom[Prometheus]
Controller -->|bounded metrics| Prom
Checker -->|bounded metrics| Prom
Prom --> Grafana[Grafana dashboards]
Prom --> Alerts[Alert rules]
Gateway -->|sampled redacted logs| Logs[Log backend]
Controller -->|audit events| Audit[(Audit storage)]
Alerts --> OnCall[On-call]
35 100k QPS 验证流程
flowchart TD
Baseline[Measure one Worker on production shape] --> Formula[Compute replicas at 60 percent target]
Formula --> Warmup[Warm Snapshot and connections]
Warmup --> Steady[Run 10k steady]
Steady --> Ramp[Step ramp to 100k]
Ramp --> Peak[Hold 100k peak window]
Peak --> Failure[Remove largest failure domain]
Failure --> Verify[Verify SLO and all invariants]
Verify --> Evidence[Archive raw metrics config and image digest]