feat: add HTTP/SOCKS5 proxy support for API endpoints

- Add proxy field to ProviderEndpoint database model with migration
- Add ProxyConfig Pydantic model for proxy URL validation
- Extend HTTP client pool with create_client_with_proxy method
- Integrate proxy configuration in chat_handler_base.py and cli_handler_base.py
- Update admin API endpoints to support proxy configuration CRUD
- Add proxy configuration UI in frontend EndpointFormDialog

Fixes #28

src/api/admin/endpoints/routes.py

@@ -202,6 +202,7 @@ class AdminCreateProviderEndpointAdapter(AdminApiAdapter):
             rate_limit=self.endpoint_data.rate_limit,
             is_active=True,
             config=self.endpoint_data.config,
+            proxy=self.endpoint_data.proxy.model_dump() if self.endpoint_data.proxy else None,
             created_at=now,
             updated_at=now,
         )
@@ -284,6 +285,9 @@ class AdminUpdateProviderEndpointAdapter(AdminApiAdapter):
             raise NotFoundException(f"Endpoint {self.endpoint_id} 不存在")
 
         update_data = self.endpoint_data.model_dump(exclude_unset=True)
+        # 把 proxy 转换为 dict 存储
+        if "proxy" in update_data and update_data["proxy"] is not None:
+            update_data["proxy"] = dict(update_data["proxy"])
         for field, value in update_data.items():
             setattr(endpoint, field, value)
         endpoint.updated_at = datetime.now(timezone.utc)

src/api/handlers/base/chat_handler_base.py

@@ -466,7 +466,13 @@ class ChatHandlerBase(BaseMessageHandler, ABC):
             pool=config.http_pool_timeout,
         )
 
-        http_client = httpx.AsyncClient(timeout=timeout_config, follow_redirects=True)
+        # 创建 HTTP 客户端（支持代理配置）
+        from src.clients.http_client import HTTPClientPool
+
+        http_client = HTTPClientPool.create_client_with_proxy(
+            proxy_config=endpoint.proxy,
+            timeout=timeout_config,
+        )
         try:
             response_ctx = http_client.stream(
                 "POST", url, json=provider_payload, headers=provider_headers
@@ -634,10 +640,14 @@ class ChatHandlerBase(BaseMessageHandler, ABC):
             logger.info(f"  [{self.request_id}] 发送非流式请求: Provider={provider.name}, "
                 f"模型={model} -> {mapped_model or '无映射'}")
 
-            async with httpx.AsyncClient(
-                timeout=float(endpoint.timeout),
-                follow_redirects=True,
-            ) as http_client:
+            # 创建 HTTP 客户端（支持代理配置）
+            from src.clients.http_client import HTTPClientPool
+
+            http_client = HTTPClientPool.create_client_with_proxy(
+                proxy_config=endpoint.proxy,
+                timeout=httpx.Timeout(float(endpoint.timeout)),
+            )
+            async with http_client:
                 resp = await http_client.post(url, json=provider_payload, headers=provider_hdrs)
 
                 status_code = resp.status_code

src/api/handlers/base/cli_handler_base.py

@@ -454,7 +454,13 @@ class CliMessageHandlerBase(BaseMessageHandler):
             f"Key=***{key.api_key[-4:]}, "
             f"原始模型={ctx.model}, 映射后={mapped_model or '无映射'}, URL模型={url_model}")
 
-        http_client = httpx.AsyncClient(timeout=timeout_config, follow_redirects=True)
+        # 创建 HTTP 客户端（支持代理配置）
+        from src.clients.http_client import HTTPClientPool
+
+        http_client = HTTPClientPool.create_client_with_proxy(
+            proxy_config=endpoint.proxy,
+            timeout=timeout_config,
+        )
         try:
             response_ctx = http_client.stream(
                 "POST", url, json=provider_payload, headers=provider_headers
@@ -1419,10 +1425,14 @@ class CliMessageHandlerBase(BaseMessageHandler):
                 f"Key=***{key.api_key[-4:]}, "
                 f"原始模型={model}, 映射后={mapped_model or '无映射'}, URL模型={url_model}")
 
-            async with httpx.AsyncClient(
-                timeout=float(endpoint.timeout),
-                follow_redirects=True,
-            ) as http_client:
+            # 创建 HTTP 客户端（支持代理配置）
+            from src.clients.http_client import HTTPClientPool
+
+            http_client = HTTPClientPool.create_client_with_proxy(
+                proxy_config=endpoint.proxy,
+                timeout=httpx.Timeout(float(endpoint.timeout)),
+            )
+            async with http_client:
                 resp = await http_client.post(url, json=provider_payload, headers=provider_headers)
 
                 status_code = resp.status_code

src/clients/http_client.py

@@ -5,12 +5,43 @@
 
 from contextlib import asynccontextmanager
 from typing import Any, Dict, Optional
+from urllib.parse import urlparse
 
 import httpx
 
 from src.core.logger import logger
 
 
+def build_proxy_url(proxy_config: Dict[str, Any]) -> Optional[str]:
+    """
+    根据代理配置构建完整的代理 URL
+
+    Args:
+        proxy_config: 代理配置字典，包含 url, username, password
+
+    Returns:
+        完整的代理 URL，如 socks5://user:pass@host:port
+    """
+    if not proxy_config:
+        return None
+
+    proxy_url = proxy_config.get("url")
+    if not proxy_url:
+        return None
+
+    username = proxy_config.get("username")
+    password = proxy_config.get("password")
+
+    if username and password:
+        parsed = urlparse(proxy_url)
+        # 重新构建带认证的代理 URL
+        auth_proxy = f"{parsed.scheme}://{username}:{password}@{parsed.netloc}"
+        if parsed.path:
+            auth_proxy += parsed.path
+        return auth_proxy
+
+    return proxy_url
+
 
 class HTTPClientPool:
     """
@@ -121,6 +152,44 @@ class HTTPClientPool:
         finally:
             await client.aclose()
 
+    @classmethod
+    def create_client_with_proxy(
+        cls,
+        proxy_config: Optional[Dict[str, Any]] = None,
+        timeout: Optional[httpx.Timeout] = None,
+        **kwargs: Any,
+    ) -> httpx.AsyncClient:
+        """
+        创建带代理配置的HTTP客户端
+
+        Args:
+            proxy_config: 代理配置字典，包含 url, username, password
+            timeout: 超时配置
+            **kwargs: 其他 httpx.AsyncClient 配置参数
+
+        Returns:
+            配置好的 httpx.AsyncClient 实例
+        """
+        config: Dict[str, Any] = {
+            "http2": False,
+            "verify": True,
+            "follow_redirects": True,
+        }
+
+        if timeout:
+            config["timeout"] = timeout
+        else:
+            config["timeout"] = httpx.Timeout(10.0, read=300.0)
+
+        # 添加代理配置
+        proxy_url = build_proxy_url(proxy_config) if proxy_config else None
+        if proxy_url:
+            config["proxy"] = proxy_url
+            logger.debug(f"创建带代理的HTTP客户端: {proxy_config.get('url', 'unknown')}")
+
+        config.update(kwargs)
+        return httpx.AsyncClient(**config)
+
 
 # 便捷访问函数
 def get_http_client() -> httpx.AsyncClient:

src/models/admin_requests.py

@@ -13,6 +13,23 @@ from pydantic import BaseModel, Field, field_validator, model_validator
 from src.core.enums import APIFormat, ProviderBillingType
 
 
+class ProxyConfig(BaseModel):
+    """代理配置"""
+
+    url: str = Field(..., description="代理 URL (http://, https://, socks5://)")
+    username: Optional[str] = Field(None, max_length=255, description="代理用户名")
+    password: Optional[str] = Field(None, max_length=500, description="代理密码")
+
+    @field_validator("url")
+    @classmethod
+    def validate_proxy_url(cls, v: str) -> str:
+        """验证代理 URL 格式"""
+        v = v.strip()
+        if not re.match(r"^(http|https|socks5|socks4)://", v, re.IGNORECASE):
+            raise ValueError("代理 URL 必须以 http://, https://, socks5:// 或 socks4:// 开头")
+        return v
+
+
 class CreateProviderRequest(BaseModel):
     """创建 Provider 请求"""
 
@@ -165,6 +182,7 @@ class CreateEndpointRequest(BaseModel):
     rpm_limit: Optional[int] = Field(None, ge=0, description="RPM 限制")
     concurrent_limit: Optional[int] = Field(None, ge=0, description="并发限制")
     config: Optional[Dict[str, Any]] = Field(None, description="其他配置")
+    proxy: Optional[ProxyConfig] = Field(None, description="代理配置")
 
     @field_validator("name")
     @classmethod
@@ -220,6 +238,7 @@ class UpdateEndpointRequest(BaseModel):
     rpm_limit: Optional[int] = Field(None, ge=0)
     concurrent_limit: Optional[int] = Field(None, ge=0)
     config: Optional[Dict[str, Any]] = None
+    proxy: Optional[ProxyConfig] = Field(None, description="代理配置")
 
     # 复用验证器
     _validate_name = field_validator("name")(CreateEndpointRequest.validate_name.__func__)

src/models/database.py

@@ -538,6 +538,9 @@ class ProviderEndpoint(Base):
     # 额外配置
     config = Column(JSON, nullable=True)  # 端点特定配置（不推荐使用，优先使用专用字段）
 
+    # 代理配置
+    proxy = Column(JSONB, nullable=True)  # 代理配置: {url, username, password}
+
     # 时间戳
     created_at = Column(
         DateTime(timezone=True), default=lambda: datetime.now(timezone.utc), nullable=False

src/models/endpoint_models.py

@@ -8,6 +8,8 @@ from typing import Any, Dict, List, Optional
 
 from pydantic import BaseModel, ConfigDict, Field, field_validator
 
+from src.models.admin_requests import ProxyConfig
+
 # ========== ProviderEndpoint CRUD ==========
 
 
@@ -30,6 +32,9 @@ class ProviderEndpointCreate(BaseModel):
     # 额外配置
     config: Optional[Dict[str, Any]] = Field(default=None, description="额外配置（JSON）")
 
+    # 代理配置
+    proxy: Optional[ProxyConfig] = Field(default=None, description="代理配置")
+
     @field_validator("api_format")
     @classmethod
     def validate_api_format(cls, v: str) -> str:
@@ -64,6 +69,7 @@ class ProviderEndpointUpdate(BaseModel):
     rate_limit: Optional[int] = Field(default=None, ge=1, description="速率限制")
     is_active: Optional[bool] = Field(default=None, description="是否启用")
     config: Optional[Dict[str, Any]] = Field(default=None, description="额外配置")
+    proxy: Optional[ProxyConfig] = Field(default=None, description="代理配置")
 
     @field_validator("base_url")
     @classmethod
@@ -104,6 +110,9 @@ class ProviderEndpointResponse(BaseModel):
     # 额外配置
     config: Optional[Dict[str, Any]] = None
 
+    # 代理配置
+    proxy: Optional[Dict[str, Any]] = Field(default=None, description="代理配置")
+
     # 统计（从 Keys 聚合）
     total_keys: int = Field(default=0, description="总 Key 数量")
     active_keys: int = Field(default=0, description="活跃 Key 数量")