perf(网关): 实现上游账号连接池隔离

新增隔离策略与连接池缓存回收

连接池大小跟随账号并发并处理代理切换

同步配置默认值与示例并补充测试

backend/internal/config/config.go

@@ -12,6 +12,20 @@ const (
 	RunModeSimple   = "simple"
 )
 
+// 连接池隔离策略常量
+// 用于控制上游 HTTP 连接池的隔离粒度，影响连接复用和资源消耗
+const (
+	// ConnectionPoolIsolationProxy: 按代理隔离
+	// 同一代理地址共享连接池，适合代理数量少、账户数量多的场景
+	ConnectionPoolIsolationProxy = "proxy"
+	// ConnectionPoolIsolationAccount: 按账户隔离
+	// 每个账户独立连接池，适合账户数量少、需要严格隔离的场景
+	ConnectionPoolIsolationAccount = "account"
+	// ConnectionPoolIsolationAccountProxy: 按账户+代理组合隔离（默认）
+	// 同一账户+代理组合共享连接池，提供最细粒度的隔离
+	ConnectionPoolIsolationAccountProxy = "account_proxy"
+)
+
 type Config struct {
 	Server       ServerConfig       `mapstructure:"server"`
 	Database     DatabaseConfig     `mapstructure:"database"`
@@ -81,6 +95,8 @@ type GatewayConfig struct {
 	ResponseHeaderTimeout int `mapstructure:"response_header_timeout"`
 	// 请求体最大字节数，用于网关请求体大小限制
 	MaxBodySize int64 `mapstructure:"max_body_size"`
+	// ConnectionPoolIsolation: 上游连接池隔离策略（proxy/account/account_proxy）
+	ConnectionPoolIsolation string `mapstructure:"connection_pool_isolation"`
 
 	// HTTP 上游连接池配置（性能优化：支持高并发场景调优）
 	// MaxIdleConns: 所有主机的最大空闲连接总数
@@ -91,6 +107,15 @@ type GatewayConfig struct {
 	MaxConnsPerHost int `mapstructure:"max_conns_per_host"`
 	// IdleConnTimeoutSeconds: 空闲连接超时时间（秒）
 	IdleConnTimeoutSeconds int `mapstructure:"idle_conn_timeout_seconds"`
+	// MaxUpstreamClients: 上游连接池客户端最大缓存数量
+	// 当使用连接池隔离策略时，系统会为不同的账户/代理组合创建独立的 HTTP 客户端
+	// 此参数限制缓存的客户端数量，超出后会淘汰最久未使用的客户端
+	// 建议值：预估的活跃账户数 * 1.2（留有余量）
+	MaxUpstreamClients int `mapstructure:"max_upstream_clients"`
+	// ClientIdleTTLSeconds: 上游连接池客户端空闲回收阈值（秒）
+	// 超过此时间未使用的客户端会被标记为可回收
+	// 建议值：根据用户访问频率设置，一般 10-30 分钟
+	ClientIdleTTLSeconds int `mapstructure:"client_idle_ttl_seconds"`
 	// ConcurrencySlotTTLMinutes: 并发槽位过期时间（分钟）
 	// 应大于最长 LLM 请求时间，防止请求完成前槽位过期
 	ConcurrencySlotTTLMinutes int `mapstructure:"concurrency_slot_ttl_minutes"`
@@ -289,11 +314,14 @@ func setDefaults() {
 	// Gateway
 	viper.SetDefault("gateway.response_header_timeout", 300) // 300秒(5分钟)等待上游响应头，LLM高负载时可能排队较久
 	viper.SetDefault("gateway.max_body_size", int64(100*1024*1024))
+	viper.SetDefault("gateway.connection_pool_isolation", ConnectionPoolIsolationAccountProxy)
 	// HTTP 上游连接池配置（针对 5000+ 并发用户优化）
-	viper.SetDefault("gateway.max_idle_conns", 240)          // 最大空闲连接总数（HTTP/2 场景默认）
-	viper.SetDefault("gateway.max_idle_conns_per_host", 120) // 每主机最大空闲连接（HTTP/2 场景默认）
-	viper.SetDefault("gateway.max_conns_per_host", 240)      // 每主机最大连接数（含活跃，HTTP/2 场景默认）
+	viper.SetDefault("gateway.max_idle_conns", 240)            // 最大空闲连接总数（HTTP/2 场景默认）
+	viper.SetDefault("gateway.max_idle_conns_per_host", 120)   // 每主机最大空闲连接（HTTP/2 场景默认）
+	viper.SetDefault("gateway.max_conns_per_host", 240)        // 每主机最大连接数（含活跃，HTTP/2 场景默认）
 	viper.SetDefault("gateway.idle_conn_timeout_seconds", 300) // 空闲连接超时（秒）
+	viper.SetDefault("gateway.max_upstream_clients", 5000)
+	viper.SetDefault("gateway.client_idle_ttl_seconds", 900)
 	viper.SetDefault("gateway.concurrency_slot_ttl_minutes", 15) // 并发槽位过期时间（支持超长请求）
 
 	// TokenRefresh
@@ -354,6 +382,14 @@ func (c *Config) Validate() error {
 	if c.Gateway.MaxBodySize <= 0 {
 		return fmt.Errorf("gateway.max_body_size must be positive")
 	}
+	if strings.TrimSpace(c.Gateway.ConnectionPoolIsolation) != "" {
+		switch c.Gateway.ConnectionPoolIsolation {
+		case ConnectionPoolIsolationProxy, ConnectionPoolIsolationAccount, ConnectionPoolIsolationAccountProxy:
+		default:
+			return fmt.Errorf("gateway.connection_pool_isolation must be one of: %s/%s/%s",
+				ConnectionPoolIsolationProxy, ConnectionPoolIsolationAccount, ConnectionPoolIsolationAccountProxy)
+		}
+	}
 	if c.Gateway.MaxIdleConns <= 0 {
 		return fmt.Errorf("gateway.max_idle_conns must be positive")
 	}
@@ -366,6 +402,12 @@ func (c *Config) Validate() error {
 	if c.Gateway.IdleConnTimeoutSeconds <= 0 {
 		return fmt.Errorf("gateway.idle_conn_timeout_seconds must be positive")
 	}
+	if c.Gateway.MaxUpstreamClients <= 0 {
+		return fmt.Errorf("gateway.max_upstream_clients must be positive")
+	}
+	if c.Gateway.ClientIdleTTLSeconds <= 0 {
+		return fmt.Errorf("gateway.client_idle_ttl_seconds must be positive")
+	}
 	if c.Gateway.ConcurrencySlotTTLMinutes <= 0 {
 		return fmt.Errorf("gateway.concurrency_slot_ttl_minutes must be positive")
 	}

backend/internal/repository/http_upstream_benchmark_test.go

@@ -8,10 +8,21 @@ import (
 	"github.com/Wei-Shaw/sub2api/internal/config"
 )
 
+// httpClientSink 用于防止编译器优化掉基准测试中的赋值操作
+// 这是 Go 基准测试的常见模式，确保测试结果准确
 var httpClientSink *http.Client
 
-// BenchmarkHTTPUpstreamProxyClient 对比重复创建与复用代理客户端的开销。
+// BenchmarkHTTPUpstreamProxyClient 对比重复创建与复用代理客户端的开销
+//
+// 测试目的：
+// - 验证连接池复用相比每次新建的性能提升
+// - 量化内存分配差异
+//
+// 预期结果：
+// - "复用" 子测试应显著快于 "新建"
+// - "复用" 子测试应零内存分配
 func BenchmarkHTTPUpstreamProxyClient(b *testing.B) {
+	// 创建测试配置
 	cfg := &config.Config{
 		Gateway: config.GatewayConfig{ResponseHeaderTimeout: 300},
 	}
@@ -22,24 +33,33 @@ func BenchmarkHTTPUpstreamProxyClient(b *testing.B) {
 	}
 
 	proxyURL := "http://127.0.0.1:8080"
-	b.ReportAllocs()
+	b.ReportAllocs() // 报告内存分配统计
 
+	// 子测试：每次新建客户端
+	// 模拟未优化前的行为，每次请求都创建新的 http.Client
 	b.Run("新建", func(b *testing.B) {
 		parsedProxy, err := url.Parse(proxyURL)
 		if err != nil {
 			b.Fatalf("解析代理地址失败: %v", err)
 		}
+		settings := defaultPoolSettings(cfg)
 		for i := 0; i < b.N; i++ {
+			// 每次迭代都创建新客户端，包含 Transport 分配
 			httpClientSink = &http.Client{
-				Transport: buildUpstreamTransport(cfg, parsedProxy),
+				Transport: buildUpstreamTransport(settings, parsedProxy),
 			}
 		}
 	})
 
+	// 子测试：复用已缓存的客户端
+	// 模拟优化后的行为，从缓存获取客户端
 	b.Run("复用", func(b *testing.B) {
-		client := svc.getOrCreateClient(proxyURL)
-		b.ResetTimer()
+		// 预热：确保客户端已缓存
+		entry := svc.getOrCreateClient(proxyURL, 1, 1)
+		client := entry.client
+		b.ResetTimer() // 重置计时器，排除预热时间
 		for i := 0; i < b.N; i++ {
+			// 直接使用缓存的客户端，无内存分配
 			httpClientSink = client
 		}
 	})

backend/internal/repository/http_upstream_test.go

@@ -4,6 +4,7 @@ import (
 	"io"
 	"net/http"
 	"net/http/httptest"
+	"sync/atomic"
 	"testing"
 	"time"
 
@@ -12,45 +13,61 @@ import (
 	"github.com/stretchr/testify/suite"
 )
 
+// HTTPUpstreamSuite HTTP 上游服务测试套件
+// 使用 testify/suite 组织测试，支持 SetupTest 初始化
 type HTTPUpstreamSuite struct {
 	suite.Suite
-	cfg *config.Config
+	cfg *config.Config // 测试用配置
 }
 
+// SetupTest 每个测试用例执行前的初始化
+// 创建空配置，各测试用例可按需覆盖
 func (s *HTTPUpstreamSuite) SetupTest() {
 	s.cfg = &config.Config{}
 }
 
-func (s *HTTPUpstreamSuite) TestDefaultResponseHeaderTimeout() {
+// newService 创建测试用的 httpUpstreamService 实例
+// 返回具体类型以便访问内部状态进行断言
+func (s *HTTPUpstreamSuite) newService() *httpUpstreamService {
 	up := NewHTTPUpstream(s.cfg)
 	svc, ok := up.(*httpUpstreamService)
 	require.True(s.T(), ok, "expected *httpUpstreamService")
-	transport, ok := svc.defaultClient.Transport.(*http.Transport)
+	return svc
+}
+
+// TestDefaultResponseHeaderTimeout 测试默认响应头超时配置
+// 验证未配置时使用 300 秒默认值
+func (s *HTTPUpstreamSuite) TestDefaultResponseHeaderTimeout() {
+	svc := s.newService()
+	entry := svc.getOrCreateClient("", 0, 0)
+	transport, ok := entry.client.Transport.(*http.Transport)
 	require.True(s.T(), ok, "expected *http.Transport")
 	require.Equal(s.T(), 300*time.Second, transport.ResponseHeaderTimeout, "ResponseHeaderTimeout mismatch")
 }
 
+// TestCustomResponseHeaderTimeout 测试自定义响应头超时配置
+// 验证配置值能正确应用到 Transport
 func (s *HTTPUpstreamSuite) TestCustomResponseHeaderTimeout() {
 	s.cfg.Gateway = config.GatewayConfig{ResponseHeaderTimeout: 7}
-	up := NewHTTPUpstream(s.cfg)
-	svc, ok := up.(*httpUpstreamService)
-	require.True(s.T(), ok, "expected *httpUpstreamService")
-	transport, ok := svc.defaultClient.Transport.(*http.Transport)
+	svc := s.newService()
+	entry := svc.getOrCreateClient("", 0, 0)
+	transport, ok := entry.client.Transport.(*http.Transport)
 	require.True(s.T(), ok, "expected *http.Transport")
 	require.Equal(s.T(), 7*time.Second, transport.ResponseHeaderTimeout, "ResponseHeaderTimeout mismatch")
 }
 
-func (s *HTTPUpstreamSuite) TestGetOrCreateClient_InvalidURLFallsBackToDefault() {
-	s.cfg.Gateway = config.GatewayConfig{ResponseHeaderTimeout: 5}
-	up := NewHTTPUpstream(s.cfg)
-	svc, ok := up.(*httpUpstreamService)
-	require.True(s.T(), ok, "expected *httpUpstreamService")
-
-	got := svc.getOrCreateClient("://bad-proxy-url")
-	require.Equal(s.T(), svc.defaultClient, got, "expected defaultClient fallback")
+// TestGetOrCreateClient_InvalidURLFallsBackToDirect 测试无效代理 URL 回退
+// 验证解析失败时回退到直连模式
+func (s *HTTPUpstreamSuite) TestGetOrCreateClient_InvalidURLFallsBackToDirect() {
+	svc := s.newService()
+	entry := svc.getOrCreateClient("://bad-proxy-url", 1, 1)
+	require.Equal(s.T(), directProxyKey, entry.proxyKey, "expected direct proxy fallback")
 }
 
+// TestDo_WithoutProxy_GoesDirect 测试无代理时直连
+// 验证空代理 URL 时请求直接发送到目标服务器
 func (s *HTTPUpstreamSuite) TestDo_WithoutProxy_GoesDirect() {
+	// 创建模拟上游服务器
 	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		_, _ = io.WriteString(w, "direct")
 	}))
@@ -60,17 +77,21 @@ func (s *HTTPUpstreamSuite) TestDo_WithoutProxy_GoesDirect() {
 
 	req, err := http.NewRequest(http.MethodGet, upstream.URL+"/x", nil)
 	require.NoError(s.T(), err, "NewRequest")
-	resp, err := up.Do(req, "")
+	resp, err := up.Do(req, "", 1, 1)
 	require.NoError(s.T(), err, "Do")
 	defer func() { _ = resp.Body.Close() }()
 	b, _ := io.ReadAll(resp.Body)
 	require.Equal(s.T(), "direct", string(b), "unexpected body")
 }
 
+// TestDo_WithHTTPProxy_UsesProxy 测试 HTTP 代理功能
+// 验证请求通过代理服务器转发，使用绝对 URI 格式
 func (s *HTTPUpstreamSuite) TestDo_WithHTTPProxy_UsesProxy() {
+	// 用于接收代理请求的通道
 	seen := make(chan string, 1)
+	// 创建模拟代理服务器
 	proxySrv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		seen <- r.RequestURI
+		seen <- r.RequestURI // 记录请求 URI
 		_, _ = io.WriteString(w, "proxied")
 	}))
 	s.T().Cleanup(proxySrv.Close)
@@ -78,14 +99,16 @@ func (s *HTTPUpstreamSuite) TestDo_WithHTTPProxy_UsesProxy() {
 	s.cfg.Gateway = config.GatewayConfig{ResponseHeaderTimeout: 1}
 	up := NewHTTPUpstream(s.cfg)
 
+	// 发送请求到外部地址，应通过代理
 	req, err := http.NewRequest(http.MethodGet, "http://example.com/test", nil)
 	require.NoError(s.T(), err, "NewRequest")
-	resp, err := up.Do(req, proxySrv.URL)
+	resp, err := up.Do(req, proxySrv.URL, 1, 1)
 	require.NoError(s.T(), err, "Do")
 	defer func() { _ = resp.Body.Close() }()
 	b, _ := io.ReadAll(resp.Body)
 	require.Equal(s.T(), "proxied", string(b), "unexpected body")
 
+	// 验证代理收到的是绝对 URI 格式（HTTP 代理规范要求）
 	select {
 	case uri := <-seen:
 		require.Equal(s.T(), "http://example.com/test", uri, "expected absolute-form request URI")
@@ -94,6 +117,8 @@ func (s *HTTPUpstreamSuite) TestDo_WithHTTPProxy_UsesProxy() {
 	}
 }
 
+// TestDo_EmptyProxy_UsesDirect 测试空代理字符串
+// 验证空字符串代理等同于直连
 func (s *HTTPUpstreamSuite) TestDo_EmptyProxy_UsesDirect() {
 	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		_, _ = io.WriteString(w, "direct-empty")
@@ -103,13 +128,134 @@ func (s *HTTPUpstreamSuite) TestDo_EmptyProxy_UsesDirect() {
 	up := NewHTTPUpstream(s.cfg)
 	req, err := http.NewRequest(http.MethodGet, upstream.URL+"/y", nil)
 	require.NoError(s.T(), err, "NewRequest")
-	resp, err := up.Do(req, "")
+	resp, err := up.Do(req, "", 1, 1)
 	require.NoError(s.T(), err, "Do with empty proxy")
 	defer func() { _ = resp.Body.Close() }()
 	b, _ := io.ReadAll(resp.Body)
 	require.Equal(s.T(), "direct-empty", string(b))
 }
 
+// TestAccountIsolation_DifferentAccounts 测试账户隔离模式
+// 验证不同账户使用独立的连接池
+func (s *HTTPUpstreamSuite) TestAccountIsolation_DifferentAccounts() {
+	s.cfg.Gateway = config.GatewayConfig{ConnectionPoolIsolation: config.ConnectionPoolIsolationAccount}
+	svc := s.newService()
+	// 同一代理，不同账户
+	entry1 := svc.getOrCreateClient("http://proxy.local:8080", 1, 3)
+	entry2 := svc.getOrCreateClient("http://proxy.local:8080", 2, 3)
+	require.NotSame(s.T(), entry1, entry2, "不同账号不应共享连接池")
+	require.Equal(s.T(), 2, len(svc.clients), "账号隔离应缓存两个客户端")
+}
+
+// TestAccountProxyIsolation_DifferentProxy 测试账户+代理组合隔离模式
+// 验证同一账户使用不同代理时创建独立连接池
+func (s *HTTPUpstreamSuite) TestAccountProxyIsolation_DifferentProxy() {
+	s.cfg.Gateway = config.GatewayConfig{ConnectionPoolIsolation: config.ConnectionPoolIsolationAccountProxy}
+	svc := s.newService()
+	// 同一账户，不同代理
+	entry1 := svc.getOrCreateClient("http://proxy-a:8080", 1, 3)
+	entry2 := svc.getOrCreateClient("http://proxy-b:8080", 1, 3)
+	require.NotSame(s.T(), entry1, entry2, "账号+代理隔离应区分不同代理")
+	require.Equal(s.T(), 2, len(svc.clients), "账号+代理隔离应缓存两个客户端")
+}
+
+// TestAccountModeProxyChangeClearsPool 测试账户模式下代理变更
+// 验证账户切换代理时清理旧连接池，避免复用错误代理
+func (s *HTTPUpstreamSuite) TestAccountModeProxyChangeClearsPool() {
+	s.cfg.Gateway = config.GatewayConfig{ConnectionPoolIsolation: config.ConnectionPoolIsolationAccount}
+	svc := s.newService()
+	// 同一账户，先后使用不同代理
+	entry1 := svc.getOrCreateClient("http://proxy-a:8080", 1, 3)
+	entry2 := svc.getOrCreateClient("http://proxy-b:8080", 1, 3)
+	require.NotSame(s.T(), entry1, entry2, "账号切换代理应创建新连接池")
+	require.Equal(s.T(), 1, len(svc.clients), "账号模式下应仅保留一个连接池")
+	require.False(s.T(), hasEntry(svc, entry1), "旧连接池应被清理")
+}
+
+// TestAccountConcurrencyOverridesPoolSettings 测试账户并发数覆盖连接池配置
+// 验证账户隔离模式下，连接池大小与账户并发数对应
+func (s *HTTPUpstreamSuite) TestAccountConcurrencyOverridesPoolSettings() {
+	s.cfg.Gateway = config.GatewayConfig{ConnectionPoolIsolation: config.ConnectionPoolIsolationAccount}
+	svc := s.newService()
+	// 账户并发数为 12
+	entry := svc.getOrCreateClient("", 1, 12)
+	transport, ok := entry.client.Transport.(*http.Transport)
+	require.True(s.T(), ok, "expected *http.Transport")
+	// 连接池参数应与并发数一致
+	require.Equal(s.T(), 12, transport.MaxConnsPerHost, "MaxConnsPerHost mismatch")
+	require.Equal(s.T(), 12, transport.MaxIdleConns, "MaxIdleConns mismatch")
+	require.Equal(s.T(), 12, transport.MaxIdleConnsPerHost, "MaxIdleConnsPerHost mismatch")
+}
+
+// TestAccountConcurrencyFallbackToDefault 测试账户并发数为 0 时回退到默认配置
+// 验证未指定并发数时使用全局配置值
+func (s *HTTPUpstreamSuite) TestAccountConcurrencyFallbackToDefault() {
+	s.cfg.Gateway = config.GatewayConfig{
+		ConnectionPoolIsolation: config.ConnectionPoolIsolationAccount,
+		MaxIdleConns:            77,
+		MaxIdleConnsPerHost:     55,
+		MaxConnsPerHost:         66,
+	}
+	svc := s.newService()
+	// 账户并发数为 0，应使用全局配置
+	entry := svc.getOrCreateClient("", 1, 0)
+	transport, ok := entry.client.Transport.(*http.Transport)
+	require.True(s.T(), ok, "expected *http.Transport")
+	require.Equal(s.T(), 66, transport.MaxConnsPerHost, "MaxConnsPerHost fallback mismatch")
+	require.Equal(s.T(), 77, transport.MaxIdleConns, "MaxIdleConns fallback mismatch")
+	require.Equal(s.T(), 55, transport.MaxIdleConnsPerHost, "MaxIdleConnsPerHost fallback mismatch")
+}
+
+// TestEvictOverLimitRemovesOldestIdle 测试超出数量限制时的 LRU 淘汰
+// 验证优先淘汰最久未使用的空闲客户端
+func (s *HTTPUpstreamSuite) TestEvictOverLimitRemovesOldestIdle() {
+	s.cfg.Gateway = config.GatewayConfig{
+		ConnectionPoolIsolation: config.ConnectionPoolIsolationAccountProxy,
+		MaxUpstreamClients:      2, // 最多缓存 2 个客户端
+	}
+	svc := s.newService()
+	// 创建两个客户端，设置不同的最后使用时间
+	entry1 := svc.getOrCreateClient("http://proxy-a:8080", 1, 1)
+	entry2 := svc.getOrCreateClient("http://proxy-b:8080", 2, 1)
+	atomic.StoreInt64(&entry1.lastUsed, time.Now().Add(-2*time.Hour).UnixNano()) // 最久
+	atomic.StoreInt64(&entry2.lastUsed, time.Now().Add(-time.Hour).UnixNano())
+	// 创建第三个客户端，触发淘汰
+	_ = svc.getOrCreateClient("http://proxy-c:8080", 3, 1)
+
+	require.LessOrEqual(s.T(), len(svc.clients), 2, "应保持在缓存上限内")
+	require.False(s.T(), hasEntry(svc, entry1), "最久未使用的连接池应被清理")
+}
+
+// TestIdleTTLDoesNotEvictActive 测试活跃请求保护
+// 验证有进行中请求的客户端不会被空闲超时淘汰
+func (s *HTTPUpstreamSuite) TestIdleTTLDoesNotEvictActive() {
+	s.cfg.Gateway = config.GatewayConfig{
+		ConnectionPoolIsolation: config.ConnectionPoolIsolationAccount,
+		ClientIdleTTLSeconds:    1, // 1 秒空闲超时
+	}
+	svc := s.newService()
+	entry1 := svc.getOrCreateClient("", 1, 1)
+	// 设置为很久之前使用，但有活跃请求
+	atomic.StoreInt64(&entry1.lastUsed, time.Now().Add(-2*time.Minute).UnixNano())
+	atomic.StoreInt64(&entry1.inFlight, 1) // 模拟有活跃请求
+	// 创建新客户端，触发淘汰检查
+	_ = svc.getOrCreateClient("", 2, 1)
+
+	require.True(s.T(), hasEntry(svc, entry1), "有活跃请求时不应回收")
+}
+
+// TestHTTPUpstreamSuite 运行测试套件
 func TestHTTPUpstreamSuite(t *testing.T) {
 	suite.Run(t, new(HTTPUpstreamSuite))
 }
+
+// hasEntry 检查客户端是否存在于缓存中
+// 辅助函数，用于验证淘汰逻辑
+func hasEntry(svc *httpUpstreamService, target *upstreamClientEntry) bool {
+	for _, entry := range svc.clients {
+		if entry == target {
+			return true
+		}
+	}
+	return false
+}

backend/internal/service/account_test_service.go

@@ -256,7 +256,7 @@ func (s *AccountTestService) testClaudeAccountConnection(c *gin.Context, account
 		proxyURL = account.Proxy.URL()
 	}
 
-	resp, err := s.httpUpstream.Do(req, proxyURL)
+	resp, err := s.httpUpstream.Do(req, proxyURL, account.ID, account.Concurrency)
 	if err != nil {
 		return s.sendErrorAndEnd(c, fmt.Sprintf("Request failed: %s", err.Error()))
 	}
@@ -371,7 +371,7 @@ func (s *AccountTestService) testOpenAIAccountConnection(c *gin.Context, account
 		proxyURL = account.Proxy.URL()
 	}
 
-	resp, err := s.httpUpstream.Do(req, proxyURL)
+	resp, err := s.httpUpstream.Do(req, proxyURL, account.ID, account.Concurrency)
 	if err != nil {
 		return s.sendErrorAndEnd(c, fmt.Sprintf("Request failed: %s", err.Error()))
 	}
@@ -442,7 +442,7 @@ func (s *AccountTestService) testGeminiAccountConnection(c *gin.Context, account
 		proxyURL = account.Proxy.URL()
 	}
 
-	resp, err := s.httpUpstream.Do(req, proxyURL)
+	resp, err := s.httpUpstream.Do(req, proxyURL, account.ID, account.Concurrency)
 	if err != nil {
 		return s.sendErrorAndEnd(c, fmt.Sprintf("Request failed: %s", err.Error()))
 	}

backend/internal/service/antigravity_gateway_service.go

@@ -230,7 +230,7 @@ func (s *AntigravityGatewayService) Forward(ctx context.Context, c *gin.Context,
 		upstreamReq.Header.Set("Authorization", "Bearer "+accessToken)
 		upstreamReq.Header.Set("User-Agent", antigravity.UserAgent)
 
-		resp, err = s.httpUpstream.Do(upstreamReq, proxyURL)
+		resp, err = s.httpUpstream.Do(upstreamReq, proxyURL, account.ID, account.Concurrency)
 		if err != nil {
 			if attempt < antigravityMaxRetries {
 				log.Printf("Antigravity account %d: upstream request failed, retry %d/%d: %v", account.ID, attempt, antigravityMaxRetries, err)
@@ -380,7 +380,7 @@ func (s *AntigravityGatewayService) ForwardGemini(ctx context.Context, c *gin.Co
 		upstreamReq.Header.Set("Authorization", "Bearer "+accessToken)
 		upstreamReq.Header.Set("User-Agent", antigravity.UserAgent)
 
-		resp, err = s.httpUpstream.Do(upstreamReq, proxyURL)
+		resp, err = s.httpUpstream.Do(upstreamReq, proxyURL, account.ID, account.Concurrency)
 		if err != nil {
 			if attempt < antigravityMaxRetries {
 				log.Printf("Antigravity account %d: upstream request failed, retry %d/%d: %v", account.ID, attempt, antigravityMaxRetries, err)

backend/internal/service/gateway_service.go

@@ -644,7 +644,7 @@ func (s *GatewayService) Forward(ctx context.Context, c *gin.Context, account *A
 		}
 
 		// 发送请求
-		resp, err = s.httpUpstream.Do(upstreamReq, proxyURL)
+		resp, err = s.httpUpstream.Do(upstreamReq, proxyURL, account.ID, account.Concurrency)
 		if err != nil {
 			return nil, fmt.Errorf("upstream request failed: %w", err)
 		}
@@ -1308,7 +1308,7 @@ func (s *GatewayService) ForwardCountTokens(ctx context.Context, c *gin.Context,
 	}
 
 	// 发送请求
-	resp, err := s.httpUpstream.Do(upstreamReq, proxyURL)
+	resp, err := s.httpUpstream.Do(upstreamReq, proxyURL, account.ID, account.Concurrency)
 	if err != nil {
 		s.countTokensError(c, http.StatusBadGateway, "upstream_error", "Request failed")
 		return fmt.Errorf("upstream request failed: %w", err)

backend/internal/service/gemini_messages_compat_service.go

@@ -472,7 +472,7 @@ func (s *GeminiMessagesCompatService) Forward(ctx context.Context, c *gin.Contex
 		}
 		requestIDHeader = idHeader
 
-		resp, err = s.httpUpstream.Do(upstreamReq, proxyURL)
+		resp, err = s.httpUpstream.Do(upstreamReq, proxyURL, account.ID, account.Concurrency)
 		if err != nil {
 			if attempt < geminiMaxRetries {
 				log.Printf("Gemini account %d: upstream request failed, retry %d/%d: %v", account.ID, attempt, geminiMaxRetries, err)
@@ -725,7 +725,7 @@ func (s *GeminiMessagesCompatService) ForwardNative(ctx context.Context, c *gin.
 		}
 		requestIDHeader = idHeader
 
-		resp, err = s.httpUpstream.Do(upstreamReq, proxyURL)
+		resp, err = s.httpUpstream.Do(upstreamReq, proxyURL, account.ID, account.Concurrency)
 		if err != nil {
 			if attempt < geminiMaxRetries {
 				log.Printf("Gemini account %d: upstream request failed, retry %d/%d: %v", account.ID, attempt, geminiMaxRetries, err)
@@ -1756,7 +1756,7 @@ func (s *GeminiMessagesCompatService) ForwardAIStudioGET(ctx context.Context, ac
 		return nil, fmt.Errorf("unsupported account type: %s", account.Type)
 	}
 
-	resp, err := s.httpUpstream.Do(req, proxyURL)
+	resp, err := s.httpUpstream.Do(req, proxyURL, account.ID, account.Concurrency)
 	if err != nil {
 		return nil, err
 	}

backend/internal/service/http_upstream_port.go

@@ -2,8 +2,29 @@ package service
 
 import "net/http"
 
-// HTTPUpstream interface for making HTTP requests to upstream APIs (Claude, OpenAI, etc.)
-// This is a generic interface that can be used for any HTTP-based upstream service.
+// HTTPUpstream 上游 HTTP 请求接口
+// 用于向上游 API（Claude、OpenAI、Gemini 等）发送请求
+// 这是一个通用接口，可用于任何基于 HTTP 的上游服务
+//
+// 设计说明：
+// - 支持可选代理配置
+// - 支持账户级连接池隔离
+// - 实现类负责连接池管理和复用
 type HTTPUpstream interface {
-	Do(req *http.Request, proxyURL string) (*http.Response, error)
+	// Do 执行 HTTP 请求
+	//
+	// 参数:
+	//   - req: HTTP 请求对象，由调用方构建
+	//   - proxyURL: 代理服务器地址，空字符串表示直连
+	//   - accountID: 账户 ID，用于连接池隔离（隔离策略为 account 或 account_proxy 时生效）
+	//   - accountConcurrency: 账户并发限制，用于动态调整连接池大小
+	//
+	// 返回:
+	//   - *http.Response: HTTP 响应，调用方必须关闭 Body
+	//   - error: 请求错误（网络错误、超时等）
+	//
+	// 注意:
+	//   - 调用方必须关闭 resp.Body，否则会导致连接泄漏
+	//   - 响应体可能已被包装以跟踪请求生命周期
+	Do(req *http.Request, proxyURL string, accountID int64, accountConcurrency int) (*http.Response, error)
 }

backend/internal/service/openai_gateway_service.go

@@ -311,7 +311,7 @@ func (s *OpenAIGatewayService) Forward(ctx context.Context, c *gin.Context, acco
 	}
 
 	// Send request
-	resp, err := s.httpUpstream.Do(upstreamReq, proxyURL)
+	resp, err := s.httpUpstream.Do(upstreamReq, proxyURL, account.ID, account.Concurrency)
 	if err != nil {
 		return nil, fmt.Errorf("upstream request failed: %w", err)
 	}

deploy/config.example.yaml

@@ -29,11 +29,21 @@ gateway:
   response_header_timeout: 300
   # 请求体最大字节数（默认 100MB）
   max_body_size: 104857600
+  # 连接池隔离策略：
+  # - proxy: 按代理隔离，同一代理共享连接池（适合代理少、账户多）
+  # - account: 按账户隔离，同一账户共享连接池（适合账户少、需严格隔离）
+  # - account_proxy: 按账户+代理组合隔离（默认，最细粒度）
+  connection_pool_isolation: "account_proxy"
   # HTTP 上游连接池配置（HTTP/2 + 多代理场景默认）
   max_idle_conns: 240
   max_idle_conns_per_host: 120
   max_conns_per_host: 240
   idle_conn_timeout_seconds: 300
+  # 上游连接池客户端缓存配置
+  # max_upstream_clients: 最大缓存客户端数量，超出后淘汰最久未使用的
+  # client_idle_ttl_seconds: 客户端空闲回收阈值（秒），超时且无活跃请求时回收
+  max_upstream_clients: 5000
+  client_idle_ttl_seconds: 900
   # 并发槽位过期时间（分钟）
   concurrency_slot_ttl_minutes: 15