Quellcode durchsuchen

feat: add ip reputation

hujiarui vor 1 Monat
Ursprung
Commit
cb7c8afc6b

+ 40 - 0
app/api/endpoints/proxy.py

@@ -4,13 +4,53 @@ from app.core.database import get_db
 from app.utils.response import success
 from app.schemas.common import ApiResponse, PageResponse
 from app.schemas.proxy_pool import GetNextIpPayload, ProxyCreate, ProxyOut, ProxyUpdate
+from app.schemas.proxy_reputation import (
+    ProxyTelemetryReportRequest,
+    ProxyTelemetryReportResponse,
+    ProxyReputationMapResponse,
+)
 from app.services.proxy_service import ProxyService
+from app.services.proxy_reputation_service import ProxyReputationService
 
 public_router = APIRouter()
 protected_router = APIRouter()
 admin_required_router = APIRouter()
 
 
+@protected_router.post(
+    "/proxy/telemetry",
+    summary="代理指标埋点上报",
+    tags=["代理信誉系统"],
+    response_model=ApiResponse[ProxyTelemetryReportResponse],
+)
+async def report_proxy_telemetry(
+    payload: ProxyTelemetryReportRequest,
+    db: AsyncSession = Depends(get_db),
+):
+    """
+    客户端上报代理节点调用质量指标(会话创建、查号、预约),触发信誉分与状态机计算
+    """
+    await ProxyReputationService.record_telemetry(db, payload)
+    return success(data=ProxyTelemetryReportResponse(recorded=True))
+
+
+@protected_router.get(
+    "/proxy/reputation/{plugin_name}",
+    summary="插件代理信誉字典查询",
+    tags=["代理信誉系统"],
+    response_model=ApiResponse[ProxyReputationMapResponse],
+)
+async def get_proxy_reputation_map(
+    plugin_name: str,
+    db: AsyncSession = Depends(get_db),
+):
+    """
+    获取指定插件的代理 IP 信誉全景字典(包含 score, state, success_rate, last_seen)
+    """
+    res = await ProxyReputationService.get_reputation_map(db, plugin_name)
+    return success(data=res)
+
+
 @admin_required_router.post("/proxy/create", summary="创建代理", tags=["代理管理"], response_model=ApiResponse[ProxyOut])
 async def proxy_create(
     payload: ProxyCreate,

+ 10 - 1
app/main.py

@@ -8,7 +8,8 @@ from starlette.exceptions import HTTPException as StarletteHTTPException
 
 import time
 from app.api import router
-from app.core.database import AsyncSessionLocal
+from app.core.database import AsyncSessionLocal, engine, Base
+import app.models  # 确保所有模型注册至 Base.metadata
 from app.core.auth import RoleLevel, require_min_role
 from app.core.config import settings
 from app.core.payment import init_stripe
@@ -21,6 +22,14 @@ async def lifespan(app: FastAPI):
     init_stripe()
     logger.info("🟢 Stripe config done")
 
+    # 自动校验/创建缺失的数据表
+    try:
+        async with engine.begin() as conn:
+            await conn.run_sync(Base.metadata.create_all)
+        logger.info("🟢 Database tables checked/created")
+    except Exception as e:
+        logger.error(f"⚠️ Database tables init error: {e}")
+
     yield
 
 

+ 1 - 1
app/models/__init__.py

@@ -14,4 +14,4 @@ from .node_configuration import (
     NodeConfigurationRevision,
 )
 from .provider import Provider
-
+from .proxy_reputation import ProxyReputation, ProxyTelemetryLog

+ 68 - 0
app/models/proxy_reputation.py

@@ -0,0 +1,68 @@
+from datetime import datetime
+from sqlalchemy import (
+    Column,
+    Integer,
+    BigInteger,
+    String,
+    Boolean,
+    DateTime,
+    UniqueConstraint,
+    Index,
+)
+from app.core.database import Base
+
+
+class ProxyReputation(Base):
+    """
+    代理出口 IP 维度信誉状态表
+    以 (plugin_name, egress_ip) 为主键聚合分析各 IP 的健康度与信誉分
+    """
+    __tablename__ = "proxy_reputation"
+
+    id = Column(BigInteger().with_variant(Integer, "sqlite"), primary_key=True, autoincrement=True)
+    plugin_name = Column(String(64), nullable=False, comment="插件名称,如 vfs_plugin")
+    egress_ip = Column(String(64), nullable=False, comment="公网出口IP")
+    score = Column(Integer, nullable=False, default=60, comment="信誉分 0-100")
+    state = Column(String(16), nullable=False, default="probation", comment="trusted, probation, blocked")
+    total_calls = Column(Integer, nullable=False, default=0, comment="总调用次数")
+    success_calls = Column(Integer, nullable=False, default=0, comment="成功调用次数")
+    consecutive_successes = Column(Integer, nullable=False, default=0, comment="连续成功次数")
+    consecutive_fails = Column(Integer, nullable=False, default=0, comment="连续失败次数")
+    last_http_code = Column(Integer, nullable=True, comment="最近一次 HTTP 响应码")
+    last_error_type = Column(String(128), nullable=True, comment="最近一次错误类型")
+    last_seen = Column(Integer, nullable=True, comment="最近一次调用秒级时间戳")
+    unblock_time = Column(DateTime, nullable=True, comment="封禁解封时间点")
+    created_at = Column(DateTime, default=datetime.utcnow, nullable=False)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow, nullable=False)
+
+    __table_args__ = (
+        UniqueConstraint("plugin_name", "egress_ip", name="uk_plugin_ip"),
+        Index("idx_plugin_state", "plugin_name", "state"),
+    )
+
+
+class ProxyTelemetryLog(Base):
+    """
+    代理调用流水日志表
+    用于原始调用记录留存及全局故障率滑动窗口统计
+    """
+    __tablename__ = "proxy_telemetry_log"
+
+    id = Column(BigInteger().with_variant(Integer, "sqlite"), primary_key=True, autoincrement=True)
+    client_id = Column(String(64), nullable=False, comment="上报客户端ID")
+    plugin_name = Column(String(64), nullable=False, comment="插件名称")
+    egress_ip = Column(String(64), nullable=False, comment="出口IP")
+    local_port = Column(Integer, nullable=True, comment="客户端本地代理端口")
+    node_name = Column(String(128), nullable=True, comment="节点标签名称")
+    action = Column(String(32), nullable=False, comment="调用场景: spawn, query, book 等")
+    success = Column(Boolean, nullable=False, comment="是否成功")
+    http_code = Column(Integer, nullable=False, comment="HTTP状态码")
+    error_type = Column(String(128), nullable=True, comment="错误描述")
+    latency_ms = Column(Integer, nullable=False, default=0, comment="耗时毫秒")
+    timestamp = Column(Integer, nullable=False, comment="客户端上报时间戳")
+    created_at = Column(DateTime, default=datetime.utcnow, nullable=False)
+
+    __table_args__ = (
+        Index("idx_telemetry_created_at", "created_at"),
+        Index("idx_telemetry_plugin_created", "plugin_name", "created_at"),
+    )

+ 48 - 0
app/schemas/proxy_reputation.py

@@ -0,0 +1,48 @@
+from typing import Optional, Dict
+from pydantic import BaseModel, Field
+
+
+class ProxyTelemetryReportRequest(BaseModel):
+    """
+    代理指标埋点上报请求参数
+    """
+    client_id: str = Field(..., description="上报客户端唯一标识,如 Jerry_Win11_PC")
+    plugin_name: str = Field(..., description="业务插件名称,如 vfs_plugin")
+    egress_ip: str = Field(..., description="真实公网出口 IP,如 104.28.198.42")
+    local_port: Optional[int] = Field(None, description="客户端本地代理端口,如 16001")
+    node_name: Optional[str] = Field(None, description="节点标签名称,如 🇭🇰 香港 01丨1x HK")
+    action: str = Field(..., description="调用场景:spawn (登录/创建会话), query (查号), book (预约提交)")
+    success: bool = Field(..., description="是否成功:true (成功), false (失败)")
+    http_code: int = Field(..., description="响应 HTTP 状态码,如 200, 403, 429, 502")
+    error_type: Optional[str] = Field(None, description="错误归因描述,如 cf-mitigated (403202)")
+    latency_ms: Optional[int] = Field(0, description="请求耗时(毫秒)")
+    timestamp: int = Field(..., description="客户端上报时间戳(秒级)")
+
+
+class ProxyTelemetryReportResponse(BaseModel):
+    """
+    代理指标埋点上报响应
+    """
+    recorded: bool = True
+
+
+class ProxyReputationItemOut(BaseModel):
+    """
+    单个出口 IP 的信誉评分与状态详情
+    """
+    score: int = Field(..., description="综合信誉评分 (0~100)")
+    state: str = Field(..., description="状态枚举: trusted, probation, blocked")
+    success_rate: float = Field(..., description="近期成功率 (0.00 ~ 1.00)")
+    last_seen: int = Field(..., description="最近一次调用时间戳(秒级)")
+
+
+class ProxyReputationMapResponse(BaseModel):
+    """
+    插件代理信誉全景字典响应
+    """
+    plugin_name: str = Field(..., description="插件名称")
+    version: int = Field(..., description="字典版本号或时间戳")
+    reputation_map: Dict[str, ProxyReputationItemOut] = Field(
+        default_factory=dict,
+        description="核心信誉字典,Key 为公网出口 IP"
+    )

+ 313 - 0
app/services/proxy_reputation_service.py

@@ -0,0 +1,313 @@
+import time
+from datetime import datetime, timedelta
+from typing import Optional, Dict, Any, Tuple
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select, func, and_
+
+from app.models.proxy_reputation import ProxyReputation, ProxyTelemetryLog
+from app.schemas.proxy_reputation import (
+    ProxyTelemetryReportRequest,
+    ProxyReputationMapResponse,
+    ProxyReputationItemOut,
+)
+from app.core.logger import logger
+
+
+class ProxyReputationService:
+    """
+    云端代理信誉分与指标埋点系统业务服务
+    实现:
+    1. 代理指标埋点上报及流水日志记录
+    2. IP 评分与状态机模型 (trusted / probation / blocked)
+    3. 目标站严重系统错误豁免 (500, 502, 503, 504, 520~526)
+    4. 黑名单 30 分钟 TTL 与半开自动复活 (Half-Open Revival)
+    5. 全网故障防雪崩保护熔断机制 (Global Outage Breaker)
+    6. 插件 IP 全景信誉字典查询
+    """
+
+    # 严重系统错误豁免状态码集合(目标站点自身故障,不扣除 IP 分数)
+    EXEMPT_HTTP_CODES = {500, 502, 503, 504}
+    CLOUDFLARE_OUTAGE_MIN = 520
+    CLOUDFLARE_OUTAGE_MAX = 526
+
+    # 黑名单封禁 TTL(分钟)
+    BLOCKED_TTL_MINUTES = 30
+
+    @classmethod
+    def is_exempt_http_code(cls, http_code: int) -> bool:
+        """
+        判断是否属于目标站点自身的严重系统错误(豁免扣分)
+        """
+        if http_code in cls.EXEMPT_HTTP_CODES:
+            return True
+        if cls.CLOUDFLARE_OUTAGE_MIN <= http_code <= cls.CLOUDFLARE_OUTAGE_MAX:
+            return True
+        return False
+
+    @classmethod
+    def is_waf_blocked(cls, http_code: int, error_type: Optional[str]) -> bool:
+        """
+        判断是否命中 Cloudflare WAF 阻断 (403202 / cf-mitigated / WAF Blocked)
+        """
+        if not error_type and http_code == 403:
+            return True
+        if error_type:
+            lowered = error_type.lower()
+            if (
+                "403202" in lowered
+                or "cf-mitigated" in lowered
+                or "waf blocked" in lowered
+                or "waf" in lowered
+                or (http_code == 403 and "mitigated" in lowered)
+            ):
+                return True
+        return http_code == 403
+
+    @classmethod
+    async def check_global_outage_breaker(
+        cls,
+        db: AsyncSession,
+        plugin_name: str,
+        lookback_minutes: int = 3,
+        min_samples: int = 5,
+        outage_failure_rate_threshold: float = 0.85,
+    ) -> bool:
+        """
+        检查目标站全网故障保护 (Global Outage Breaker)
+        统计最近 lookback_minutes (默认3分钟) 内该插件的所有上报事件:
+        若样本数 >= min_samples 且失败率突发超过 85%,判定处于全网故障期,暂停降分与拉黑。
+        """
+        since_time = datetime.utcnow() - timedelta(minutes=lookback_minutes)
+        stmt = (
+            select(
+                func.count(ProxyTelemetryLog.id).label("total_cnt"),
+                func.sum(
+                    func.case((ProxyTelemetryLog.success.is_(False), 1), else_=0)
+                ).label("fail_cnt"),
+            )
+            .where(
+                and_(
+                    ProxyTelemetryLog.plugin_name == plugin_name,
+                    ProxyTelemetryLog.created_at >= since_time,
+                )
+            )
+        )
+        res = await db.execute(stmt)
+        row = res.one_or_none()
+        if not row:
+            return False
+
+        total_cnt = row.total_cnt or 0
+        fail_cnt = row.fail_cnt or 0
+
+        if total_cnt >= min_samples:
+            fail_rate = fail_cnt / total_cnt
+            if fail_rate > outage_failure_rate_threshold:
+                logger.warning(
+                    f"🚨 [Global Outage Breaker] 触发全网故障保护: plugin={plugin_name}, "
+                    f"样本数={total_cnt}, 失败数={fail_cnt}, 失败率={fail_rate:.2%}"
+                )
+                return True
+
+        return False
+
+    @classmethod
+    async def record_telemetry(
+        cls,
+        db: AsyncSession,
+        payload: ProxyTelemetryReportRequest,
+    ) -> bool:
+        """
+        接收并处理客户端上报的指标数据:
+        1. 写入 proxy_telemetry_log 流水表;
+        2. 更新/初始化 proxy_reputation 信誉表;
+        3. 应用状态机、豁免规则、降级与防雪崩熔断算法。
+        """
+        now = datetime.utcnow()
+        now_ts = payload.timestamp or int(time.time())
+
+        # 1. 记录流水日志
+        log_entry = ProxyTelemetryLog(
+            client_id=payload.client_id,
+            plugin_name=payload.plugin_name,
+            egress_ip=payload.egress_ip,
+            local_port=payload.local_port,
+            node_name=payload.node_name,
+            action=payload.action,
+            success=payload.success,
+            http_code=payload.http_code,
+            error_type=payload.error_type,
+            latency_ms=payload.latency_ms or 0,
+            timestamp=now_ts,
+            created_at=now,
+        )
+        db.add(log_entry)
+
+        # 2. 检查全网目标故障保护 (Global Outage Breaker)
+        is_global_outage = await cls.check_global_outage_breaker(db, payload.plugin_name)
+
+        # 3. 查询当前 IP 的信誉记录
+        stmt = select(ProxyReputation).where(
+            and_(
+                ProxyReputation.plugin_name == payload.plugin_name,
+                ProxyReputation.egress_ip == payload.egress_ip,
+            )
+        )
+        res = await db.execute(stmt)
+        record = res.scalar_one_or_none()
+
+        if not record:
+            # 初始状态:新上报公网 IP 初始分 60 分,状态 probation
+            record = ProxyReputation(
+                plugin_name=payload.plugin_name,
+                egress_ip=payload.egress_ip,
+                score=60,
+                state="probation",
+                total_calls=0,
+                success_calls=0,
+                consecutive_successes=0,
+                consecutive_fails=0,
+                last_http_code=payload.http_code,
+                last_error_type=payload.error_type,
+                last_seen=now_ts,
+                unblock_time=None,
+                created_at=now,
+                updated_at=now,
+            )
+            db.add(record)
+        else:
+            # 4. 黑名单租期与自动半开复活检查 (TTL & Half-Open Revival)
+            if record.state == "blocked":
+                if record.unblock_time and now >= record.unblock_time:
+                    logger.info(
+                        f"🔄 [Half-Open Revival] 代理节点解封复活: plugin={record.plugin_name}, ip={record.egress_ip}"
+                    )
+                    record.state = "probation"
+                    record.score = 50
+                    record.consecutive_successes = 0
+                    record.unblock_time = None
+
+        # 更新调用计数与元数据
+        record.total_calls += 1
+        record.last_seen = now_ts
+        record.last_http_code = payload.http_code
+        record.last_error_type = payload.error_type
+        record.updated_at = now
+
+        # 5. 评分与状态机更新计算
+        if is_global_outage:
+            # 全网故障期:暂停所有 IP 的降分与拉黑计算,保持信誉字典冻结
+            if payload.success:
+                record.success_calls += 1
+            # 记录维持不变
+            logger.info(
+                f"🛡️ [Breaker Active] 处于全网故障期,保持 IP 字典打分冻结: ip={record.egress_ip}, score={record.score}"
+            )
+        else:
+            if payload.success:
+                # 成功调用
+                record.success_calls += 1
+                record.consecutive_successes += 1
+                record.consecutive_fails = 0
+                # 加分规则:一次成功调用 +5 分(上限 100 分)
+                record.score = min(100, record.score + 5)
+
+                # 晋升规则:连续成功 3 次且分数 >= 75 晋升为 trusted
+                if record.consecutive_successes >= 3 and record.score >= 75:
+                    record.state = "trusted"
+                    record.unblock_time = None
+                elif record.state == "blocked":
+                    # 试探成功脱离 blocked
+                    record.state = "probation"
+                    record.unblock_time = None
+            else:
+                # 失败调用
+                # 检查严重系统错误豁免
+                if cls.is_exempt_http_code(payload.http_code):
+                    logger.info(
+                        f"🕊️ [Exempt Error] 目标系统严重故障豁免扣分: http_code={payload.http_code}, ip={record.egress_ip}"
+                    )
+                    # 豁免时不扣分,不累积失败
+                else:
+                    record.consecutive_fails += 1
+                    record.consecutive_successes = 0
+
+                    # 判断是否命中 WAF 阻断
+                    if cls.is_waf_blocked(payload.http_code, payload.error_type):
+                        # 直接扣除 40 分
+                        record.score = max(0, record.score - 40)
+                    else:
+                        # 普通业务错误或客户端超时:扣除 2 分
+                        record.score = max(0, record.score - 2)
+
+                    # 状态机降级逻辑
+                    if record.score < 40:
+                        record.state = "blocked"
+                        record.unblock_time = now + timedelta(minutes=cls.BLOCKED_TTL_MINUTES)
+                        logger.warning(
+                            f"⛔ [Blocked] 代理节点降级拉黑: ip={record.egress_ip}, score={record.score}, "
+                            f"unblock_at={record.unblock_time}"
+                        )
+                    elif record.state == "trusted" and record.score < 75:
+                        record.state = "probation"
+
+        await db.commit()
+        return True
+
+    @classmethod
+    async def get_reputation_map(
+        cls,
+        db: AsyncSession,
+        plugin_name: str,
+    ) -> ProxyReputationMapResponse:
+        """
+        获取指定插件的代理信誉全景字典
+        同时对已达 30 分钟 TTL 的 blocked IP 执行半开自动复活 (Half-Open Revival)
+        """
+        now = datetime.utcnow()
+        stmt = select(ProxyReputation).where(ProxyReputation.plugin_name == plugin_name)
+        res = await db.execute(stmt)
+        records = res.scalars().all()
+
+        reputation_map: Dict[str, ProxyReputationItemOut] = {}
+        max_updated_at: Optional[datetime] = None
+        has_revived = False
+
+        for r in records:
+            # 检查自动复活
+            if r.state == "blocked" and r.unblock_time and now >= r.unblock_time:
+                r.state = "probation"
+                r.score = 50
+                r.consecutive_successes = 0
+                r.unblock_time = None
+                r.updated_at = now
+                has_revived = True
+
+            if max_updated_at is None or (r.updated_at and r.updated_at > max_updated_at):
+                max_updated_at = r.updated_at
+
+            success_rate = (
+                round(r.success_calls / r.total_calls, 2) if r.total_calls > 0 else 1.0
+            )
+
+            last_seen_ts = r.last_seen
+            if not last_seen_ts:
+                last_seen_ts = int(r.updated_at.timestamp()) if r.updated_at else int(time.time())
+
+            reputation_map[r.egress_ip] = ProxyReputationItemOut(
+                score=r.score,
+                state=r.state,
+                success_rate=success_rate,
+                last_seen=last_seen_ts,
+            )
+
+        if has_revived:
+            await db.commit()
+
+        version = int(max_updated_at.timestamp()) if max_updated_at else int(time.time())
+
+        return ProxyReputationMapResponse(
+            plugin_name=plugin_name,
+            version=version,
+            reputation_map=reputation_map,
+        )

+ 45 - 0
scripts/create_proxy_reputation_tables.sql

@@ -0,0 +1,45 @@
+-- ====================================================================
+-- 云端代理信誉分与指标埋点系统 (Proxy Reputation API) 数据库建表脚本
+-- 适用数据库: MySQL 5.7+ / 8.0+ / MariaDB
+-- 字符集: utf8mb4
+-- ====================================================================
+
+-- 1. IP 维度信誉状态表
+CREATE TABLE IF NOT EXISTS `proxy_reputation` (
+  `id` BIGINT AUTO_INCREMENT PRIMARY KEY,
+  `plugin_name` VARCHAR(64) NOT NULL COMMENT '插件名称,如 vfs_plugin',
+  `egress_ip` VARCHAR(64) NOT NULL COMMENT '公网出口IP',
+  `score` INT NOT NULL DEFAULT 60 COMMENT '信誉分 0-100',
+  `state` VARCHAR(16) NOT NULL DEFAULT 'probation' COMMENT 'trusted, probation, blocked',
+  `total_calls` INT NOT NULL DEFAULT 0 COMMENT '总调用次数',
+  `success_calls` INT NOT NULL DEFAULT 0 COMMENT '成功调用次数',
+  `consecutive_successes` INT NOT NULL DEFAULT 0 COMMENT '连续成功次数',
+  `consecutive_fails` INT NOT NULL DEFAULT 0 COMMENT '连续失败次数',
+  `last_http_code` INT DEFAULT NULL COMMENT '最近一次 HTTP 响应码',
+  `last_error_type` VARCHAR(128) DEFAULT NULL COMMENT '最近一次错误类型',
+  `last_seen` INT DEFAULT NULL COMMENT '最近一次调用秒级时间戳',
+  `unblock_time` DATETIME DEFAULT NULL COMMENT '封禁解封时间点',
+  `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
+  `updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
+  UNIQUE KEY `uk_plugin_ip` (`plugin_name`, `egress_ip`),
+  INDEX `idx_plugin_state` (`plugin_name`, `state`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='代理出口IP信誉分与状态表';
+
+-- 2. 原始调用指标流水日志表
+CREATE TABLE IF NOT EXISTS `proxy_telemetry_log` (
+  `id` BIGINT AUTO_INCREMENT PRIMARY KEY,
+  `client_id` VARCHAR(64) NOT NULL COMMENT '客户端唯一标识',
+  `plugin_name` VARCHAR(64) NOT NULL COMMENT '插件名称',
+  `egress_ip` VARCHAR(64) NOT NULL COMMENT '公网出口IP',
+  `local_port` INT DEFAULT NULL COMMENT '客户端本地代理端口',
+  `node_name` VARCHAR(128) DEFAULT NULL COMMENT '节点标签名称',
+  `action` VARCHAR(32) NOT NULL COMMENT '调用场景: spawn, query, book',
+  `success` TINYINT(1) NOT NULL COMMENT '是否成功: 1成功, 0失败',
+  `http_code` INT NOT NULL COMMENT 'HTTP响应状态码',
+  `error_type` VARCHAR(128) DEFAULT NULL COMMENT '错误类型归因',
+  `latency_ms` INT NOT NULL DEFAULT 0 COMMENT '耗时毫秒',
+  `timestamp` INT NOT NULL COMMENT '客户端上报时间戳(秒级)',
+  `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '服务端接收时间',
+  INDEX `idx_telemetry_created_at` (`created_at`),
+  INDEX `idx_telemetry_plugin_created` (`plugin_name`, `created_at`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='代理指标埋点流水日志表';

+ 26 - 0
scripts/init_proxy_reputation_tables.py

@@ -0,0 +1,26 @@
+import asyncio
+import os
+import sys
+
+# 保证根目录在 sys.path
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from app.core.database import engine, Base
+import app.models.proxy_reputation  # 导入模型,确保注册到 Base.metadata
+
+
+async def init_tables():
+    print("⏳ 正在连接数据库并创建代理信誉相关数据表...")
+    try:
+        async with engine.begin() as conn:
+            # 仅创建未存在的表
+            await conn.run_sync(Base.metadata.create_all)
+        print("✅ 数据库表 proxy_reputation 和 proxy_telemetry_log 校验/创建完成!")
+    except Exception as e:
+        print(f"❌ 建表失败: {e}")
+    finally:
+        await engine.dispose()
+
+
+if __name__ == "__main__":
+    asyncio.run(init_tables())

+ 459 - 0
tests/test_proxy_reputation.py

@@ -0,0 +1,459 @@
+# -*- coding: utf-8 -*-
+import pytest
+import pytest_asyncio
+import time
+from datetime import datetime, timedelta
+from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession, async_sessionmaker
+from sqlalchemy import select
+from fastapi.testclient import TestClient
+
+from app.core.database import Base, get_db
+from app.core.auth import get_current_user, require_min_role, RoleLevel
+from app.models.proxy_reputation import ProxyReputation, ProxyTelemetryLog
+from app.services.proxy_reputation_service import ProxyReputationService
+from app.schemas.proxy_reputation import ProxyTelemetryReportRequest
+from app.main import app
+
+# 使用 SQLite 内存数据库进行测试
+TEST_DATABASE_URL = "sqlite+aiosqlite:///:memory:"
+
+test_engine = create_async_engine(TEST_DATABASE_URL, echo=False)
+TestSessionLocal = async_sessionmaker(
+    bind=test_engine,
+    class_=AsyncSession,
+    autoflush=False,
+    expire_on_commit=False,
+)
+
+
+@pytest_asyncio.fixture(scope="function")
+async def async_db():
+    async with test_engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+
+    async with TestSessionLocal() as session:
+        yield session
+
+    async with test_engine.begin() as conn:
+        await conn.run_sync(Base.metadata.drop_all)
+
+
+class DummyUser:
+    id = 1
+    role = "user"
+
+
+@pytest.fixture
+def test_client():
+    async def override_get_db():
+        async with TestSessionLocal() as session:
+            yield session
+
+    app.dependency_overrides[get_db] = override_get_db
+    app.dependency_overrides[get_current_user] = lambda: DummyUser()
+    app.dependency_overrides[require_min_role(RoleLevel.user)] = lambda: DummyUser()
+
+    with TestClient(app) as client:
+        yield client
+
+    app.dependency_overrides.clear()
+
+
+@pytest.mark.asyncio
+async def test_new_ip_telemetry_initialization(async_db: AsyncSession):
+    """
+    测试新 IP 首次上报初始化:
+    初始分 60 分,状态为 probation,流水表与信誉表正常生成
+    """
+    payload = ProxyTelemetryReportRequest(
+        client_id="Client_01",
+        plugin_name="vfs_plugin",
+        egress_ip="104.28.198.42",
+        local_port=16001,
+        node_name="HK_01",
+        action="spawn",
+        success=True,
+        http_code=200,
+        error_type=None,
+        latency_ms=350,
+        timestamp=int(time.time()),
+    )
+
+    recorded = await ProxyReputationService.record_telemetry(async_db, payload)
+    assert recorded is True
+
+    # 验证信誉表数据
+    res = await async_db.execute(
+        select(ProxyReputation).where(ProxyReputation.egress_ip == "104.28.198.42")
+    )
+    rep = res.scalar_one_or_none()
+    assert rep is not None
+    assert rep.plugin_name == "vfs_plugin"
+    # 初始 60 分 + 成功 1 次 (5分) = 65分
+    assert rep.score == 65
+    assert rep.state == "probation"
+    assert rep.total_calls == 1
+    assert rep.success_calls == 1
+    assert rep.consecutive_successes == 1
+    assert rep.consecutive_fails == 0
+
+    # 验证流水日志
+    logs = (await async_db.execute(select(ProxyTelemetryLog))).scalars().all()
+    assert len(logs) == 1
+    assert logs[0].egress_ip == "104.28.198.42"
+    assert logs[0].http_code == 200
+
+
+@pytest.mark.asyncio
+async def test_success_score_increment_and_promotion_to_trusted(async_db: AsyncSession):
+    """
+    测试加分与晋升规则:
+    一次成功调用 +5 分;连续成功 3 次且分数 >= 75 晋升为 trusted;分数上限 100
+    """
+    ip = "104.28.198.50"
+    plugin = "vfs_plugin"
+
+    # 第 1 次成功:初始 60 + 5 = 65,consecutive = 1
+    await ProxyReputationService.record_telemetry(
+        async_db,
+        ProxyTelemetryReportRequest(
+            client_id="Client_01",
+            plugin_name=plugin,
+            egress_ip=ip,
+            action="query",
+            success=True,
+            http_code=200,
+            timestamp=int(time.time()),
+        ),
+    )
+    # 第 2 次成功:65 + 5 = 70,consecutive = 2
+    await ProxyReputationService.record_telemetry(
+        async_db,
+        ProxyTelemetryReportRequest(
+            client_id="Client_01",
+            plugin_name=plugin,
+            egress_ip=ip,
+            action="query",
+            success=True,
+            http_code=200,
+            timestamp=int(time.time()),
+        ),
+    )
+    res = await async_db.execute(select(ProxyReputation).where(ProxyReputation.egress_ip == ip))
+    rep = res.scalar_one()
+    assert rep.score == 70
+    assert rep.state == "probation"
+    assert rep.consecutive_successes == 2
+
+    # 第 3 次成功:70 + 5 = 75,consecutive = 3 -> 满足 >= 75 且 consecutive >= 3,晋升为 trusted
+    await ProxyReputationService.record_telemetry(
+        async_db,
+        ProxyTelemetryReportRequest(
+            client_id="Client_01",
+            plugin_name=plugin,
+            egress_ip=ip,
+            action="query",
+            success=True,
+            http_code=200,
+            timestamp=int(time.time()),
+        ),
+    )
+    await async_db.refresh(rep)
+    assert rep.score == 75
+    assert rep.state == "trusted"
+    assert rep.consecutive_successes == 3
+
+
+@pytest.mark.asyncio
+async def test_exempt_system_errors(async_db: AsyncSession):
+    """
+    测试目标系统严重故障豁免:
+    若 http_code 为 500, 502, 503, 504 或 Cloudflare 520~526,绝对不扣减 IP 分数
+    """
+    ip = "104.28.198.60"
+    plugin = "vfs_plugin"
+
+    # 初始化 IP(初始 60 分)
+    await ProxyReputationService.record_telemetry(
+        async_db,
+        ProxyTelemetryReportRequest(
+            client_id="Client_01",
+            plugin_name=plugin,
+            egress_ip=ip,
+            action="query",
+            success=True,
+            http_code=200,
+            timestamp=int(time.time()),
+        ),
+    )
+    res = await async_db.execute(select(ProxyReputation).where(ProxyReputation.egress_ip == ip))
+    rep = res.scalar_one()
+    assert rep.score == 65
+
+    # 上报 502 Bad Gateway 失败
+    await ProxyReputationService.record_telemetry(
+        async_db,
+        ProxyTelemetryReportRequest(
+            client_id="Client_01",
+            plugin_name=plugin,
+            egress_ip=ip,
+            action="query",
+            success=False,
+            http_code=502,
+            error_type="Bad Gateway",
+            timestamp=int(time.time()),
+        ),
+    )
+    await async_db.refresh(rep)
+    # 分数依然维持 65 分,不扣分
+    assert rep.score == 65
+    assert rep.consecutive_fails == 0
+
+    # 上报 Cloudflare 521 Web server is down
+    await ProxyReputationService.record_telemetry(
+        async_db,
+        ProxyTelemetryReportRequest(
+            client_id="Client_01",
+            plugin_name=plugin,
+            egress_ip=ip,
+            action="query",
+            success=False,
+            http_code=521,
+            error_type="Web server is down",
+            timestamp=int(time.time()),
+        ),
+    )
+    await async_db.refresh(rep)
+    assert rep.score == 65
+
+
+@pytest.mark.asyncio
+async def test_waf_blocked_penalty_and_blocked_state(async_db: AsyncSession):
+    """
+    测试命中 WAF 阻断扣除 40 分并降级拉黑:
+    命中 403202 / cf-mitigated / WAF Blocked 直接扣 40 分,分数 < 40 降级为 blocked 并设置 30分钟 TTL
+    """
+    ip = "104.28.198.70"
+    plugin = "vfs_plugin"
+
+    # 新 IP 初始 60 分,遭遇 WAF 阻断
+    await ProxyReputationService.record_telemetry(
+        async_db,
+        ProxyTelemetryReportRequest(
+            client_id="Client_01",
+            plugin_name=plugin,
+            egress_ip=ip,
+            action="spawn",
+            success=False,
+            http_code=403,
+            error_type="cf-mitigated (403202)",
+            timestamp=int(time.time()),
+        ),
+    )
+    res = await async_db.execute(select(ProxyReputation).where(ProxyReputation.egress_ip == ip))
+    rep = res.scalar_one()
+    # 60 - 40 = 20 分
+    assert rep.score == 20
+    assert rep.state == "blocked"
+    assert rep.unblock_time is not None
+    # unblock_time 应约为当前时间后 30 分钟
+    assert rep.unblock_time > datetime.utcnow() + timedelta(minutes=25)
+
+
+@pytest.mark.asyncio
+async def test_general_error_penalty_and_trusted_downgrade(async_db: AsyncSession):
+    """
+    测试普通错误扣除 2 分以及 trusted 降级为 probation
+    """
+    ip = "104.28.198.80"
+    plugin = "vfs_plugin"
+
+    # 先将其提升至 trusted (75分)
+    for _ in range(3):
+        await ProxyReputationService.record_telemetry(
+            async_db,
+            ProxyTelemetryReportRequest(
+                client_id="Client_01",
+                plugin_name=plugin,
+                egress_ip=ip,
+                action="query",
+                success=True,
+                http_code=200,
+                timestamp=int(time.time()),
+            ),
+        )
+    res = await async_db.execute(select(ProxyReputation).where(ProxyReputation.egress_ip == ip))
+    rep = res.scalar_one()
+    assert rep.score == 75
+    assert rep.state == "trusted"
+
+    # 发生普通业务超时错误,扣除 2 分 -> 73 分,降级回 probation
+    await ProxyReputationService.record_telemetry(
+        async_db,
+        ProxyTelemetryReportRequest(
+            client_id="Client_01",
+            plugin_name=plugin,
+            egress_ip=ip,
+            action="query",
+            success=False,
+            http_code=408,
+            error_type="Network Timeout",
+            timestamp=int(time.time()),
+        ),
+    )
+    await async_db.refresh(rep)
+    assert rep.score == 73
+    assert rep.state == "probation"
+    assert rep.consecutive_fails == 1
+    assert rep.consecutive_successes == 0
+
+
+@pytest.mark.asyncio
+async def test_half_open_revival_after_ttl(async_db: AsyncSession):
+    """
+    测试黑名单 30 分钟 TTL 自动半开复活 (Half-Open Revival):
+    进入 blocked 的 IP 在 30 分钟后自动重置为 probation(恢复至 50 分)
+    """
+    ip = "104.28.198.90"
+    plugin = "vfs_plugin"
+
+    # 触发拉黑
+    await ProxyReputationService.record_telemetry(
+        async_db,
+        ProxyTelemetryReportRequest(
+            client_id="Client_01",
+            plugin_name=plugin,
+            egress_ip=ip,
+            action="spawn",
+            success=False,
+            http_code=403,
+            error_type="cf-mitigated",
+            timestamp=int(time.time()),
+        ),
+    )
+    res = await async_db.execute(select(ProxyReputation).where(ProxyReputation.egress_ip == ip))
+    rep = res.scalar_one()
+    assert rep.state == "blocked"
+
+    # 模拟时间流逝:将 unblock_time 修改为 5 分钟前(已过 TTL)
+    rep.unblock_time = datetime.utcnow() - timedelta(minutes=5)
+    await async_db.commit()
+
+    # 触发查询字典接口
+    map_resp = await ProxyReputationService.get_reputation_map(async_db, plugin)
+    assert ip in map_resp.reputation_map
+    item = map_resp.reputation_map[ip]
+    # 已半开复活
+    assert item.state == "probation"
+    assert item.score == 50
+
+    # 验证数据库中也已更新
+    await async_db.refresh(rep)
+    assert rep.state == "probation"
+    assert rep.score == 50
+    assert rep.unblock_time is None
+
+
+@pytest.mark.asyncio
+async def test_global_outage_breaker(async_db: AsyncSession):
+    """
+    测试全局目标故障保护 (Global Outage Breaker):
+    全网 3 分钟内失败率 > 85% 时,冻结打分与拉黑
+    """
+    plugin = "vfs_plugin"
+    # 模拟在最近 1 分钟内,其他节点产生了大面积失败(10 次全部失败,失败率 100%)
+    now = datetime.utcnow()
+    for i in range(10):
+        log = ProxyTelemetryLog(
+            client_id=f"Client_{i}",
+            plugin_name=plugin,
+            egress_ip=f"192.168.1.{i}",
+            action="query",
+            success=False,
+            http_code=403,
+            error_type="cf-mitigated",
+            latency_ms=1000,
+            timestamp=int(time.time()),
+            created_at=now,
+        )
+        async_db.add(log)
+    await async_db.commit()
+
+    # 此时有一个正常 IP (score=60) 上报失败
+    test_ip = "104.28.198.100"
+    await ProxyReputationService.record_telemetry(
+        async_db,
+        ProxyTelemetryReportRequest(
+            client_id="Client_X",
+            plugin_name=plugin,
+            egress_ip=test_ip,
+            action="query",
+            success=False,
+            http_code=403,
+            error_type="cf-mitigated",
+            timestamp=int(time.time()),
+        ),
+    )
+
+    res = await async_db.execute(select(ProxyReputation).where(ProxyReputation.egress_ip == test_ip))
+    rep = res.scalar_one()
+    # 因为处于全网故障保护期,分数冻结,不扣 40 分,不拉黑
+    assert rep.score == 60
+    assert rep.state == "probation"
+
+
+def test_http_api_endpoints(test_client):
+    """
+    测试 HTTP 接口:
+    1. POST /api/proxy/telemetry
+    2. GET /api/proxy/reputation/{plugin_name}
+    """
+    import asyncio
+    async def setup_db():
+        async with test_engine.begin() as conn:
+            await conn.run_sync(Base.metadata.create_all)
+    asyncio.run(setup_db())
+
+    # 1. 代理指标埋点上报 (POST /api/proxy/telemetry)
+    payload = {
+        "client_id": "Jerry_Win11_PC",
+        "plugin_name": "vfs_plugin",
+        "local_port": 16001,
+        "node_name": "🇭🇰 香港 01丨1x HK",
+        "egress_ip": "104.28.198.42",
+        "action": "spawn",
+        "success": True,
+        "http_code": 200,
+        "error_type": None,
+        "latency_ms": 1150,
+        "timestamp": 1758985800,
+    }
+
+    resp = test_client.post(
+        "/api/proxy/telemetry",
+        json=payload,
+        headers={"Authorization": "Bearer tok_test_token"},
+    )
+    assert resp.status_code == 200
+    data = resp.json()
+    assert data["code"] == 0
+    assert data["message"] == "success"
+    assert data["data"]["recorded"] is True
+
+    # 2. 插件代理信誉字典查询 (GET /api/proxy/reputation/vfs_plugin)
+    resp2 = test_client.get(
+        "/api/proxy/reputation/vfs_plugin",
+        headers={"Authorization": "Bearer tok_test_token"},
+    )
+    assert resp2.status_code == 200
+    data2 = resp2.json()
+    assert data2["code"] == 0
+    assert data2["data"]["plugin_name"] == "vfs_plugin"
+    assert "version" in data2["data"]
+    assert "104.28.198.42" in data2["data"]["reputation_map"]
+
+    ip_info = data2["data"]["reputation_map"]["104.28.198.42"]
+    assert ip_info["score"] == 65
+    assert ip_info["state"] == "probation"
+    assert ip_info["success_rate"] == 1.0
+    assert ip_info["last_seen"] == 1758985800