# BIZ-46 Phase3: NVIDIA Sidecar Follow-up 架构设计

> **架构师**: 梁思筑 (architect)  
> **日期**: 2026-06-24  
> **状态**: 已批准，推进实施  
> **来源**: BIZ-42 Phase2 二轮评审 follow-up  

---

## 1. 架构解耦 / 依赖注入 — SidecarContext

### 1.1 现状分析

当前 `server.py` 使用 **模块级全局变量** 管理所有核心组件：

```python
# server.py 全局状态（当前）
_config: SidecarConfig
_http_client: httpx.AsyncClient
_priority_queue: PriorityRequestQueue
_token_bucket: AdaptiveTokenBucket
_prometheus: PrometheusMetrics
_health_service: HealthService
_pending_requests: dict[str, tuple[asyncio.Future, float]]
_stats: dict[str, int]
_stats_lock: asyncio.Lock
```

**问题**：
- `webui.py` 通过 `from nvidia_sidecar import server` 反向导入全局变量（循环依赖风险）
- 单元测试需要 mock 模块级变量，无法并行运行测试
- 未来多实例/多租户扩展需重写全部模块访问逻辑

### 1.2 设计方案 — SidecarContext + FastAPI Dependency Injection

#### 1.2.1 核心数据结构

```python
# context.py
from dataclasses import dataclass, field
import asyncio
import httpx
from typing import Any

@dataclass
class SidecarContext:
    """Sidecar 全局运行时上下文 — 所有核心组件的唯一容器。
    
    通过 app.state.sidecar 注入 FastAPI，路由通过 Depends 获取。
    """
    config: 'SidecarConfig'
    http_client: httpx.AsyncClient
    token_bucket: 'AdaptiveTokenBucket'
    priority_queue: 'PriorityRequestQueue'
    prometheus: 'PrometheusMetrics'
    health: 'HealthService'
    pending_requests: dict[str, tuple['asyncio.Future', float]] = field(default_factory=dict)
    stats: dict[str, int] = field(default_factory=lambda: {
        "total_requests": 0,
        "nvidia_requests": 0,
        "passthrough_requests": 0,
        "ratelimited_requests": 0,
        "queue_full_rejects": 0,
        "upstream_errors": 0,
        "start_time": 0,
    })
    stats_lock: asyncio.Lock = field(default_factory=asyncio.Lock)
    
    async def increment_stat(self, key: str, delta: int = 1) -> None:
        """线程安全的统计计数器自增。"""
        async with self.stats_lock:
            self.stats[key] = self.stats.get(key, 0) + delta
```

#### 1.2.2 注入方式

```python
# server.py — lifespan 中创建 context
from nvidia_sidecar.context import SidecarContext

@asynccontextmanager
async def lifespan(app: FastAPI):
    ctx = SidecarContext(
        config=load_config(),
        http_client=httpx.AsyncClient(...),
        token_bucket=AdaptiveTokenBucket(...),
        priority_queue=PriorityRequestQueue(...),
        prometheus=PrometheusMetrics(),
        health=HealthService(),
    )
    app.state.sidecar = ctx  # 注入 FastAPI
    # ... worker 启动 ...
    yield
    # ... 清理 ...

# 依赖注入函数
def get_context(request: Request) -> SidecarContext:
    return request.app.state.sidecar

# 路由使用
@app.post("/v1/chat/completions")
async def chat_completions(request: Request, ctx: SidecarContext = Depends(get_context)):
    return await _handle_proxy_request(request, "/v1/chat/completions", ctx)
```

#### 1.2.3 webui.py 解耦

```python
# webui.py — 不再反向导入 server
from nvidia_sidecar.context import SidecarContext
from fastapi import Depends

def get_webui_router():
    router = APIRouter(prefix="/api", tags=["webui"])
    
    def _get_ctx(request: Request) -> SidecarContext:
        return request.app.state.sidecar
    
    @router.get("/dashboard/stream")
    async def dashboard_stream(request: Request, ctx: SidecarContext = Depends(_get_ctx)):
        return await _dashboard_stream(request, ctx)
    
    @router.get("/admin/config")
    async def admin_get_config(ctx: SidecarContext = Depends(_get_ctx)):
        return await get_config(ctx)
    
    return router
```

#### 1.2.4 Trade-off 分析

| 维度 | 当前（全局变量） | 方案A（SidecarContext） | 方案B（FastAPI Dependency 全函数式） |
|------|------------------|------------------------|-------------------------------------|
| 可测试性 | 差（需 mock 模块） | 好（注入 mock context） | 优（每个依赖独立注入） |
| 改动量 | 无 | 中等（~8 文件） | 大（每个函数签名变更） |
| 可读性 | 一般 | 好（ctx 一目了然） | 差（参数列表膨胀） |
| 多实例支持 | 不支持 | 支持（多 app 多 ctx） | 支持 |
| 循环依赖 | 有（webui→server） | 消除 | 消除 |

**决策**: 采用方案A（SidecarContext），平衡改动量与收益。

### 1.3 迁移计划

分 3 步渐进迁移，每步可独立合入：

1. **Step 1**: 创建 `context.py`，定义 `SidecarContext`，在 `lifespan` 中实例化并挂到 `app.state`
2. **Step 2**: 路由函数改为 `Depends(get_context)`，删除模块级 `_config`、`_http_client` 等
3. **Step 3**: `webui.py` 移除 `from nvidia_sidecar import server`，改用依赖注入

---

## 2. Prometheus 标签基数治理

### 2.1 现状

当前使用 `model_id` 作为 label 的指标：

| 指标 | Label | 风险 |
|------|-------|------|
| `sidecar_upstream_latency_seconds` | `model_id` | **高** — NVIDIA 模型名含版本号，可能无界增长 |
| `sidecar_upstream_errors_total` | `status_code`, `model_id` | **中** — 组合基数 = 模型数 × 状态码数 |

### 2.2 基数评估

NVIDIA API 当前已知模型约 20-30 个，但：
- 新模型持续发布（每月 2-5 个）
- 模型名含版本后缀（`nvidia/deepseek-ai/deepseek-v4-pro`、`nvidia/llama-3.1-70b-instruct` 等）
- 长期运行（6 个月+）可能累积 100+ 标签组合

**结论**: 当前基数可控（<200 组合），但长期存在膨胀风险，应提前治理。

### 2.3 治理方案

| 指标 | 当前 Label | 调整后 Label | 理由 |
|------|-----------|-------------|------|
| `upstream_latency_seconds` | `model_id` | `provider` | provider 固定为 `nvidia`，基数=1 |
| `upstream_errors_total` | `status_code`, `model_id` | `status_code`, `provider` | 同上 |

**模型级信息迁移路径**：
- 模型 ID → 结构化 JSON 日志（structlog 已支持）
- 需要模型级延迟分析时 → 临时 `/status` API 查询或日志聚合

```python
# metrics.py 调整
self.upstream_latency_seconds: Histogram = Histogram(
    "sidecar_upstream_latency_seconds",
    "Upstream response latency in seconds",
    labelnames=["provider"],  # 原: ["model_id"]
    buckets=(...),
)

self.upstream_errors_total: Counter = Counter(
    "sidecar_upstream_errors_total",
    "Upstream error count by status code",
    labelnames=["status_code", "provider"],  # 原: ["status_code", "model_id"]
)
```

```python
# server.py 调整 — 模型信息改记日志
model_id = _extract_model(payload) or "unknown"
provider = "nvidia"  # 固定值，因为只有 NVIDIA 请求走 worker
_prometheus.record_upstream_latency(provider, upstream_latency)
if not resp.is_success:
    _prometheus.record_upstream_error(resp.status_code, provider)
logger.info("request_completed", model_id=model_id, ...)  # JSON 日志保留模型信息
```

### 2.4 Trade-off

| 维度 | 保留 model_id | 收敛为 provider |
|------|--------------|----------------|
| 基数风险 | 高（无界） | 无（固定=1） |
| 模型级分析 | Prometheus 原生查询 | 需日志聚合 |
| 迁移成本 | 无 | 低（改 2 个指标定义 + 调用点） |

**决策**: 收敛为 `provider`，模型级分析通过 JSON 日志 + 日志聚合系统（ELK/Loki）完成。

---

## 3. SSE 快照共享缓存

### 3.1 现状

每个 SSE 客户端每秒独立调用 `_build_snapshot()`，该方法：
- 获取 `_stats` 字典（需锁）
- 调用 `_token_bucket.get_status()`（需锁）
- 调用 `_priority_queue.get_stats()`（需 asyncio.Lock）

当 N 个仪表盘同时打开时，每秒 N 次锁竞争 + N 次重复计算。

### 3.2 设计方案 — 1s TTL 共享缓存

```python
# webui.py
_snapshot_cache: tuple[dict[str, Any], float] | None = None  # (data, timestamp)
_snapshot_lock: asyncio.Lock = asyncio.Lock()
_SNAPSHOT_TTL: float = 1.0  # 1 秒 TTL

async def _build_snapshot_cached(ctx: SidecarContext) -> dict[str, Any]:
    """带 1s TTL 的共享快照缓存。
    
    多个 SSE 客户端共享同一份快照，避免重复计算和锁竞争。
    """
    global _snapshot_cache
    
    now = time.monotonic()
    if _snapshot_cache is not None:
        data, ts = _snapshot_cache
        if now - ts < _SNAPSHOT_TTL:
            return data
    
    async with _snapshot_lock:
        # Double-check（避免多个协程同时 miss 后重复构建）
        if _snapshot_cache is not None:
            data, ts = _snapshot_cache
            if now - ts < _SNAPSHOT_TTL:
                return data
        
        snapshot = await _build_snapshot(ctx)
        _snapshot_cache = (snapshot, now)
        return snapshot
```

### 3.3 性能收益

| 场景 | 当前 | 优化后 |
|------|------|--------|
| 1 客户端 | 1 次/s 计算 | 1 次/s 计算（无变化） |
| 5 客户端 | 5 次/s 计算，5 次锁竞争 | 1 次/s 计算，1 次锁竞争 |
| 20 客户端 | 20 次/s 计算，20 次锁竞争 | 1 次/s 计算，1 次锁竞争 |

---

## 4. 部署支撑

### 4.1 Dockerfile

```dockerfile
# services/nvidia_sidecar/Dockerfile
FROM python:3.12-slim AS base

WORKDIR /app

# 安装依赖（利用 Docker 层缓存）
COPY pyproject.toml .
RUN pip install --no-cache-dir -e .

# 复制源码
COPY . .

# 非 root 用户运行
RUN useradd -r -s /bin/false sidecar
USER sidecar

# 健康检查
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
    CMD python -c "import httpx; r=httpx.get('http://127.0.0.1:9190/health'); exit(0 if r.status_code==200 else 1)"

EXPOSE 9190 9191

CMD ["uvicorn", "nvidia_sidecar.server:app", "--host", "0.0.0.0", "--port", "9190"]
```

### 4.2 systemd Service

```ini
# services/nvidia_sidecar/deploy/nvidia-sidecar.service
[Unit]
Description=NVIDIA Sidecar Rate-Limiting Proxy
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=sidecar
Group=sidecar
WorkingDirectory=/opt/nvidia-sidecar
ExecStart=/opt/nvidia-sidecar/.venv/bin/uvicorn nvidia_sidecar.server:app \
    --host 127.0.0.1 \
    --port 9190 \
    --log-level info
Restart=always
RestartSec=5

# 环境变量
EnvironmentFile=/opt/nvidia-sidecar/.env

# 安全加固
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
ReadWritePaths=/opt/nvidia-sidecar/logs

# 资源限制
LimitNOFILE=65536
MemoryMax=512M

[Install]
WantedBy=multi-user.target
```

### 4.3 环境变量清单

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `SIDECAR_HOST` | `127.0.0.1` | 监听地址 |
| `SIDECAR_PORT` | `9190` | 代理端口 |
| `SIDECAR_METRICS_PORT` | `9191` | Prometheus 指标端口 |
| `SIDECAR_UPSTREAM` | `https://integrate.api.nvidia.com/v1` | 上游 API |
| `SIDECAR_API_KEY` | (必填) | NVIDIA API Key |
| `SIDECAR_RATE_RPM` | `40` | 限流速率 (RPM) |
| `SIDECAR_BUCKET_CAPACITY` | `40` | 令牌桶容量 |
| `SIDECAR_TIMEOUT` | `60` | 请求超时 (秒) |
| `SIDECAR_QUEUE_MAX` | `500` | 队列最大容量 |
| `SIDECAR_LOW_TIMEOUT` | `2` | 低优先级超时 (秒) |
| `SIDECAR_FALLBACK_PASSTHROUGH` | `true` | 队列满时是否直通 |
| `SIDECAR_LOG_LEVEL` | `INFO` | 日志级别 |
| `SIDECAR_ADMIN_TOKEN` | (可选) | Admin API 认证 Token |

### 4.4 防火墙建议

```
# 仅允许内网访问代理端口
sudo ufw allow from 192.168.1.0/24 to any port 9190
sudo ufw allow from 192.168.1.0/24 to any port 9191
# 禁止外网访问
sudo ufw deny 9190
sudo ufw deny 9191
```

---

## 5. Readiness HTTP Client 复用

### 5.1 现状

`HealthService.check_upstream()` 每次调用创建新的 `httpx.AsyncClient`：

```python
# health.py — 当前
async def check_upstream(self, upstream_url: str, timeout: float = 5.0, api_key: str = "") -> bool:
    async with httpx.AsyncClient(timeout=timeout) as client:  # 每次新建！
        resp = await client.get(...)
```

K8s/systemd 每 10-30s 探测一次，每次创建+销毁 HTTP client 带来不必要的 TCP 连接开销。

### 5.2 方案 — 复用主 http_client

```python
# health.py — 优化后
async def check_upstream(
    self,
    upstream_url: str,
    http_client: httpx.AsyncClient,  # 注入主 client
    api_key: str = "",
    timeout: float = 5.0,
) -> bool:
    try:
        headers = {}
        if api_key:
            headers["authorization"] = f"Bearer {api_key}"
        resp = await http_client.get(
            f"{upstream_url.rstrip('/')}/v1/models",
            headers=headers,
            timeout=timeout,
        )
        return resp.status_code < 500
    except Exception:
        return False
```

```python
# server.py — 路由调用处
@app.get("/health/ready")
async def health_ready(ctx: SidecarContext = Depends(get_context)):
    queue_size = await ctx.priority_queue.get_queue_size()
    bucket_status = ctx.token_bucket.get_status()
    return await ctx.health.readiness(
        upstream_url=ctx.config.upstream_url,
        http_client=ctx.http_client,  # 复用主 client
        upstream_api_key=ctx.config.upstream_api_key or "",
        queue_current_size=queue_size,
        queue_max_size=ctx.config.queue_max_size,
        available_tokens=bucket_status["tokens"],
        bucket_capacity=bucket_status["capacity"],
    )
```

**注意**: readiness 检查使用较短 timeout (5s)，不影响主代理请求的 timeout 配置。httpx 支持per-request timeout 覆盖。

---

## 6. Retreat 并发/死锁回归测试

### 6.1 风险点

`AdaptiveTokenBucket` 有两把锁：
- `_lock` (Lock): 保护令牌消费/补充
- `_retreat_lock` (RLock): 保护避退状态机

潜在死锁路径：
1. `evaluate_retreat()` 持有 `_retreat_lock` → 调用 `get_429_rate()` (也获取 `_retreat_lock`，RLock 可重入 ✅)
2. `evaluate_retreat()` → `_apply_retreat()` → `set_rate()` → 获取 `_lock` (另一把锁)
3. Worker 线程: `consume()` 持有 `_lock` → 不调用 `_retreat_lock` (无交叉 ✅)

当前设计使用 RLock 已规避了重入死锁，但需要回归测试确保未来修改不引入死锁。

### 6.2 测试用例

```python
# tests/test_retreat_concurrency.py
import pytest
import asyncio
import threading
from nvidia_sidecar.rate_limiter import AdaptiveTokenBucket, RetreatState

class TestRetreatConcurrency:
    """避退模式并发安全回归测试。"""

    @pytest.mark.asyncio
    async def test_concurrent_record_and_evaluate(self):
        """多线程同时 record_response + evaluate_retreat 不死锁。"""
        bucket = AdaptiveTokenBucket(rate=40/60, capacity=40)
        errors: list[Exception] = []
        
        def worker_record():
            for i in range(1000):
                try:
                    bucket.record_response(is_429=(i % 10 == 0))
                except Exception as e:
                    errors.append(e)
        
        def worker_evaluate():
            for _ in range(1000):
                try:
                    bucket.evaluate_retreat()
                except Exception as e:
                    errors.append(e)
        
        threads = [
            threading.Thread(target=worker_record),
            threading.Thread(target=worker_record),
            threading.Thread(target=worker_evaluate),
            threading.Thread(target=worker_evaluate),
        ]
        for t in threads:
            t.start()
        for t in threads:
            t.join(timeout=10)
        
        # 所有线程必须在 10s 内完成（无死锁）
        assert all(not t.is_alive() for t in threads), "线程未完成，疑似死锁"
        assert not errors, f"并发错误: {errors}"

    @pytest.mark.asyncio
    async def test_concurrent_consume_and_retreat(self):
        """多线程同时 consume + evaluate_retreat 不死锁。"""
        bucket = AdaptiveTokenBucket(rate=40/60, capacity=40)
        errors: list[Exception] = []
        
        def worker_consume():
            for _ in range(500):
                try:
                    bucket.consume(tokens=1)
                except Exception as e:
                    errors.append(e)
        
        def worker_retreat():
            for _ in range(500):
                try:
                    bucket.record_response(is_429=False)
                    bucket.evaluate_retreat()
                except Exception as e:
                    errors.append(e)
        
        threads = [
            threading.Thread(target=worker_consume),
            threading.Thread(target=worker_consume),
            threading.Thread(target=worker_retreat),
            threading.Thread(target=worker_retreat),
        ]
        for t in threads:
            t.start()
        for t in threads:
            t.join(timeout=10)
        
        assert all(not t.is_alive() for t in threads), "线程未完成，疑似死锁"
        assert not errors, f"并发错误: {errors}"

    def test_retreat_state_transitions_under_load(self):
        """高负载下避退状态转换正确。"""
        bucket = AdaptiveTokenBucket(
            rate=40/60, capacity=40,
            retreat_429_threshold=0.05,
            retreat_factor=0.75,
        )
        
        # 模拟高 429 率
        for _ in range(100):
            bucket.record_response(is_429=True)
        
        state = bucket.evaluate_retreat()
        assert state == RetreatState.RETREAT
        assert bucket.get_effective_rate_rpm() < bucket.get_base_rate_rpm()
        
        # 模拟恢复
        for _ in range(200):
            bucket.record_response(is_429=False)
        
        # 需要等待 RECOVER_WINDOW
        import time
        time.sleep(0.1)  # 确保时间窗口过去
        bucket._last_state_change = 0  # 强制触发时间条件
        state = bucket.evaluate_retreat()
        assert state in (RetreatState.RECOVER, RetreatState.NORMAL)
```

---

## 7. Dashboard UX 优化

### 7.1 优化项清单

| # | 优化项 | 实现方式 | 优先级 |
|---|--------|---------|--------|
| 1 | 队列柱状图 300ms 平滑动画 | CSS `transition: height 300ms ease` | P1 |
| 2 | SSE 断连 5s 遮罩 | JS 定时器 + DOM 遮罩层 | P1 |
| 3 | 队列图标题显示总排队数 | SSE 数据已有 `current_size`，更新标题 | P2 |
| 4 | 页面加载同步配置 | `fetch('/api/admin/config')` 初始化表单 | P2 |

### 7.2 关键实现

```javascript
// dashboard.html — SSE 断连检测
let lastSSETime = Date.now();
let reconnectMask = document.getElementById('reconnect-mask');

eventSource.onmessage = (event) => {
    lastSSETime = Date.now();
    reconnectMask.style.display = 'none';
    // ... 更新 UI ...
};

// 5s 无数据 → 显示遮罩
setInterval(() => {
    if (Date.now() - lastSSETime > 5000) {
        reconnectMask.style.display = 'flex';
    }
}, 1000);

// 队列柱状图动画
// CSS: .queue-bar { transition: height 0.3s ease; }
```

```javascript
// 页面加载时同步配置
async function loadConfig() {
    try {
        const resp = await fetch('/api/admin/config');
        if (resp.ok) {
            const config = await resp.json();
            document.getElementById('rate-rpm').value = config.rate_rpm;
            document.getElementById('queue-max').value = config.queue_max_size;
            // ...
        }
    } catch (e) {
        console.warn('配置加载失败（可能需要 Admin Token）', e);
    }
}
loadConfig();
```

---

## 8. 实施排期

| 阶段 | 内容 | 预估工时 | 依赖 |
|------|------|---------|------|
| **D1** | SidecarContext Step 1-3（解耦迁移） | 8h | 无 |
| **D2** | Prometheus 标签收敛 + 日志增强 | 2h | D1 |
| **D2** | SSE 共享缓存 | 2h | D1 |
| **D2** | Readiness HTTP client 复用 | 1h | D1 |
| **D3** | Dockerfile + systemd service | 2h | 无 |
| **D3** | Dashboard UX 优化 | 3h | 无 |
| **D3** | Retreat 并发回归测试 | 3h | 无 |
| **D4** | 集成测试 + mypy strict | 4h | D1-D3 |
| **合计** | | **25h** | |

---

## 9. 验收标准映射

| Issue 要求 | 本文档章节 | 状态 |
|-----------|-----------|------|
| SidecarContext / DI 方案落地或 ADR | §1 | ✅ 详细设计 + 迁移计划 |
| Prometheus 高基数 label 收敛 | §2 | ✅ 收敛为 provider |
| SSE snapshot 共享缓存 | §3 | ✅ 1s TTL 设计 |
| Dockerfile + systemd + 部署 SOP | §4 | ✅ 完整文件 |
| readiness 复用 HTTP client | §5 | ✅ 注入主 client |
| retreat 并发/死锁回归测试 | §6 | ✅ 测试用例 |
| Dashboard UX 细节 | §7 | ✅ 4 项优化 |