┌─────────────────────────────────────────────────────────────┐
│                      客户端层 (Web / Mobile / Desktop)       │
│                    gRPC-Web / WebTransport                    │
└──────────────────────────┬────────────────────────────────────┘
                           │ HTTPS (TLS 1.3)
┌──────────────────────────▼────────────────────────────────────┐
│                     Envoy 边缘网关集群                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐            │
│  │  TLS 终结   │  │  熔断限流   │  │  灰度路由   │  核心过滤器链 │
│  │  JWT 鉴权   │  │  重试超时   │  │  头部改写   │            │
│  └─────────────┘  └─────────────┘  └─────────────┘            │
└──────────────────────────┬────────────────────────────────────┘
                           │ gRPC (h2c)
┌──────────────────────────▼────────────────────────────────────┐
│                  信令微服务集群 (K8s Deployment)                │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐          │
│  │ 会话管理 │ │ 媒体协商 │ │ 设备管理 │ │ 录制控制 │  业务模块   │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘          │
└─────────────────────────────────────────────────────────────────┘

# envoy-rate-limit-config.yaml
domain: signaling-gateway
descriptors:
  # 维度 1：按用户 ID 限流（防止单用户刷接口）
  - key: "x-user-id"
    rate_limit:
      unit: minute
      requests_per_unit: 120
  
  # 维度 2：按会议 ID 限流（防止热门会议雪崩）
  - key: "x-meeting-id"
    rate_limit:
      unit: second
      requests_per_unit: 50
  
  # 维度 3：按 IP + 接口组合（防爬虫/恶意探测）
  - key: "x-forwarded-for"
    key: ":method"
    key: ":path"
    rate_limit:
      unit: minute
      requests_per_unit: 300

# 连接池配置
circuit_breakers:
  thresholds:
    - max_connections: 10000        # 单上游最大连接数
      max_pending_requests: 5000    # 排队请求上限
      max_requests: 20000           # 并发请求上限
      max_retries: 3                # 重试预算
      track_remaining: true
      retry_budget:
        budget_percent: 20          # 重试预算占比 20%
        min_retry_concurrency: 10

# HTTP/2 流控制
http2_protocol_options:
  max_concurrent_streams: 1000      # 单连接最大并发流
  initial_stream_window_size: 65535 # 流级窗口
  initial_connection_window_size: 1048576 # 连接级窗口

outlier_detection:
  consecutive_5xx: 3                # 连续 3 次 5xx 触发异常
  interval: 10s                     # 检测间隔
  base_ejection_time: 30s           # 最小驱逐时长
  max_ejection_percent: 50          # 最大驱逐比例 50%
  min_health_percent: 30            # 最小健康实例比例
  split_external_local_origin_errors: true
  consecutive_local_origin_failure: 5
  consecutive_gateway_failure: 3

// 示例：会议创建接口限流
@SentinelResource(value = "createMeeting", 
                  blockHandler = "createMeetingFallback")
public MeetingResponse createMeeting(CreateMeetingRequest request) {
    // 业务逻辑
}

// 热点参数限流：按企业 ID 限制并发创建会议数
@SentinelResource(value = "createMeeting",
                  blockHandler = "fallback",
                  parameterType = CreateMeetingRequest.class)
public MeetingResponse createMeeting(CreateMeetingRequest request) {
    // 通过 ContextUtil.enter("enterprise-" + request.getEnterpriseId()) 
    // 实现热点参数隔离
}

route_config:
  virtual_hosts:
    - name: signaling
      domains: ["api.meeting.example.com"]
      routes:
        - match:
            prefix: "/"
            headers:
              - name: "x-canary"
                exact_match: "true"
          route:
            weighted_clusters:
              clusters:
                - name: signaling_v2
                  weight: 100
        - match:
            prefix: "/"
            headers:
              - name: "x-enterprise-tier"
                exact_match: "premium"
          route:
            weighted_clusters:
              clusters:
                - name: signaling_v2
                  weight: 50
                - name: signaling_v1
                  weight: 50
        - match:
            prefix: "/"
          route:
            weighted_clusters:
              clusters:
                - name: signaling_v1
                  weight: 90
                - name: signaling_v2
                  weight: 10

sequenceDiagram
    participant Client
    participant Envoy
    participant V1
    participant V2
    
    Note over Client,V2: 灰度发布启动
    Client->>Envoy: gRPC-Web 连接 (携带 x-client-version)
    Envoy->>V1: 路由至旧版本
    
    Note over Client,V2: V2 就绪，下发灰度标记
    Envoy-->>Client: GOAWAY (gRPC) / 404 (gRPC-Web) + Retry-After
    Client->>Client: 指数退避重连 (携带 x-canary: true)
    Client->>Envoy: 新连接
    Envoy->>V2: 路由至新版本
    V2-->>Client: 会话状态同步 (Session State Sync)
    Client->>Client: 无感切换完成

# bootstrap.yaml
admin:
  access_log_path: /dev/stdout
  address:
    socket_address:
      address: 0.0.0.0
      port_value: 9901

static_resources:
  listeners:
    - name: https_listener
      address:
        socket_address:
          address: 0.0.0.0
          port_value: 443
      filter_chains:
        - filter_chain_match:
            transport_protocol: "tls"
          tls_context:
            common_tls_context:
              tls_certificates:
                - certificate_chain:
                    filename: "/etc/envoy/certs/tls.crt"
                  private_key:
                    filename: "/etc/envoy/certs/tls.key"
              validation_context:
                trusted_ca:
                  filename: "/etc/envoy/certs/ca.crt"
                verify_subject_alt_name:
                  - "spiffe://cluster.local/ns/signaling/sa/signaling-service"
          filters:
            - name: envoy.filters.network.http_connection_manager
              typed_config:
                "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
                stat_prefix: ingress_https
                route_config:
                  name: local_route
                  virtual_hosts:
                    - name: signaling
                      domains: ["*"]
                      routes:
                        - match:
                            prefix: "/"
                            grpc: {}
                          route:
                            cluster: signaling_backend
                            timeout: 30s
                            retry_policy:
                              retry_on: "connect-failure,refused-stream,unavailable,cancelled,retriable-status-codes"
                              num_retries: 3
                              per_try_timeout: 10s
                              back_off:
                                base_interval: 0.025s
                                max_interval: 10s
                http_filters:
                  - name: envoy.filters.http.grpc_web
                  - name: envoy.filters.http.router
  clusters:
    - name: signaling_backend
      type: EDS
      lb_policy: LEAST_REQUEST
      least_request_lb_config:
        choice_count: 2
      health_checks:
        - timeout: 5s
          interval: 10s
          unhealthy_threshold: 2
          healthy_threshold: 1
          grpc_health_check:
            service_name: "signaling.SignalingService"
      circuit_breakers:
        thresholds:
          - max_connections: 10000
            max_pending_requests: 5000
            max_requests: 20000
      outlier_detection:
        consecutive_5xx: 3
        interval: 10s
        base_ejection_time: 30s
        max_ejection_percent: 50

# deployment.yaml 关键配置
spec:
  replicas: 6
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 25%
      maxUnavailable: 0  # 保证零停机
  template:
    spec:
      containers:
        - name: envoy
          image: envoyproxy/envoy:v1.29-latest
          resources:
            requests:
              cpu: "500m"
              memory: "512Mi"
            limits:
              cpu: "2000m"
              memory: "2Gi"
          ports:
            - containerPort: 443
            - containerPort: 9901
          readinessProbe:
            httpGet:
              path: /ready
              port: 9901
            initialDelaySeconds: 5
            periodSeconds: 5
          lifecycle:
            preStop:
              exec:
                command: ["/bin/sh", "-c", "sleep 15"]  # 等待连接排空
      terminationGracePeriodSeconds: 30

// TypeScript gRPC-Web 客户端封装
import { GrpcWebFetchTransport } from '@protobuf-ts/grpcweb-transport';
import { SignalingServiceClient } from './gen/signaling_service.client';

const transport = new GrpcWebFetchTransport({
  baseUrl: 'https://api.meeting.example.com',
  // 自动携带认证头
  meta: () => ({
    'authorization': `Bearer ${getAccessToken()}`,
    'x-client-version': CLIENT_VERSION,
    'x-platform': 'web',
  }),
  // 连接保活
  keepAlive: true,
  keepAliveIntervalMs: 30000,
});

const client = new SignalingServiceClient(transport);

// 重连封装
async function withReconnect<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (e) {
      if (isRetriable(e) && i < maxRetries - 1) {
        await sleep(2 ** i * 1000 + Math.random() * 1000);
        continue;
      }
      throw e;
    }
  }
}

typed_config:
  "@type": type.googleapis.com/envoy.extensions.filters.http.dynamic_forward_proxy.v3.FilterConfig
  dns_cache_config:
    name: dynamic_forward_proxy_cache
    dns_lookup_family: V4_ONLY
  transport_socket:
    name: envoy.transport_socket.tls
    typed_config:
      "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.UpstreamTlsContext
      common_tls_context:
        tls_certificates:
          - certificate_chain:
              filename: "/etc/envoy/certs/client.crt"
            private_key:
              filename: "/etc/envoy/certs/client.key"

{
  "timestamp": "2024-01-15T10:30:45.123Z",
  "level": "INFO",
  "service": "signaling-gateway",
  "trace_id": "a1b2c3d4e5f6...",
  "span_id": "1234567890ab...",
  "method": "CreateSession",
  "protocol": "grpc-web",
  "user_id": "usr_abc123",
  "meeting_id": "mtg_xyz789",
  "enterprise_id": "ent_001",
  "client_version": "2.4.1",
  "platform": "web",
  "duration_ms": 45,
  "response_code": 200,
  "upstream_cluster": "signaling_v2",
  "upstream_host": "10.0.1.15:50051",
  "bytes_sent": 1024,
  "bytes_received": 2048
}

# Envoy 上游集群 mTLS 配置
transport_socket:
  name: envoy.transport_socket.tls
  typed_config:
    "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.UpstreamTlsContext
    common_tls_context:
      tls_certificates:
        - certificate_chain:
            filename: "/etc/envoy/certs/client.pem"
          private_key:
            filename: "/etc/envoy/certs/client.key"
      validation_context:
        trusted_ca:
          filename: "/etc/envoy/certs/ca.pem"
        verify_subject_alt_name:
          - "spiffe://cluster.local/ns/signaling/sa/signaling-service"
    sni: "signaling-service.signaling.svc.cluster.local"

// proto/signaling/v1/encrypted.proto
message EncryptedEnvelope {
  string key_id = 1;           // 密钥版本标识
  string algorithm = 2;        // "AES-256-GCM" / "XChaCha20-Poly1305"
  bytes nonce = 3;             // 96-bit 随机数
  bytes ciphertext = 4;        // 加密后的原始信令 Payload
  bytes associated_data = 5;   // AAD: meeting_id + user_id + timestamp
}

# 审计日志过滤器配置 (envoy.filters.http.ext_authz + 自定义审计服务)
http_filters:
  - name: envoy.filters.http.ext_authz
    typed_config:
      "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthz
      transport_api_version: V3
      grpc_service:
        envoy_grpc:
          cluster_name: audit_service
      failure_mode_allow: false  # 审计服务不可用时拒绝请求
      with_request_body:
        max_request_bytes: 8192
        allow_partial: true

graph TB
    Client[客户端] --> GSLB[全局负载均衡<br/>Cloudflare/AWS Route53/阿里云 GTM]
    GSLB -->|就近解析/健康检查| Region1[华东集群<br/>Envoy Cluster]
    GSLB -->|故障切换| Region2[华南集群<br/>Envoy Cluster]
    Region1 --> Sync[(配置同步<br/>xDS/ConfigMap)]
    Region2 --> Sync
    Region1 --> State[(会话状态同步<br/>Redis Geo-Replication)]
    Region2 --> State

{
  "RecordType": "A",
  "SetIdentifier": "cn-hangzhou-primary",
  "HealthCheckId": "hc-signaling-hz",
  "Region": "cn-north-1",
  "Failover": "PRIMARY",
  "Weight": 100
},
{
  "RecordType": "A", 
  "SetIdentifier": "cn-shenzhen-dr",
  "Region": "cn-south-1",
  "Failover": "SECONDARY",
  "Weight": 0
}

# ArgoCD ApplicationSet 多集群部署模板
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: signaling-gateway-multicluster
spec:
  generators:
    - clusters:
        selector:
          matchLabels:
            environment: production
            role: signaling-dataplane
  template:
    metadata:
      name: '{{name}}-signaling-gateway'
    spec:
      project: signaling
      source:
        repoURL: https://github.com/your-org/infra-config.git
        targetRevision: main
        path: overlays/{{metadata.labels.region}}
        helm:
          valueFiles:
            - values.yaml
            - values-{{metadata.labels.region}}.yaml
      destination:
        server: '{{server}}'
        namespace: signaling-system
      syncPolicy:
        automated:
          prune: true
          selfHeal: true
        syncOptions:
          - CreateNamespace=true
          - RespectIgnoreDifferences=true

所需 Envoy 实例数 = ceil( 
    (峰值并发连接数 × 单连接内存占用 + 安全冗余 30%) 
    / 单实例内存上限 
)

单连接内存占用 ≈ 
  基础连接状态 (2-4KB) 
  + HTTP/2 流控窗口 (默认 64KB) 
  + gRPC-Web 缓冲区 (平均 8KB) 
  + TLS 会话缓存 (约 1KB)
  ≈ 80-100 KB / 连接 (含 Go/Java 上游进程分摊)

# HPA 多指标自动扩缩容
metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 60
  - type: Pods
    pods:
      metric:
        name: envoy_http_downstream_cx_active
      target:
        type: AverageValue
        averageValue: "45000"  # 单 Pod 连接数触发扩容
  - type: External
    external:
      metric:
        name: rls_global_limit_remaining_ratio
      target:
        type: Value
        value: "0.3"  # 全局限流剩余额度 < 30% 扩容
behavior:
  scaleDown:
    stabilizationWindowSeconds: 600  # 缩容冷却 10 分钟
    policies:
      - type: Percent
        value: 10
        periodSeconds: 60

# .gitlab/ci/chaos-engineering.yml
chaos_weekly_validation:
  stage: chaos
  image: chaosiq/chaostoolkit:latest
  only:
    - schedules  # 每周日凌晨 02:00 定时触发
  script:
    - chaosiq login --token $CHAOSIQ_TOKEN
    - chaos run experiment/ce-01-upstream-crash.yaml --no-dry
    - chaos run experiment/ce-03-network-partition.yaml --no-dry
    - |
      # 结果判定与通知
      if [ $? -ne 0 ]; then
        curl -X POST "$DINGTALK_WEBHOOK" 
          -d "{"msgtype":"markdown","markdown":{"title":"混沌实验失败","text":"**实验失败**: $CI_JOB_URLn请立即排查熔断限流配置"}}"
        exit 1
      fi
  artifacts:
    reports:
      junit: chaos-report.xml

// packages/signaling-sdk/src/types.ts
export interface SignalingClientConfig {
  endpoint: string;                 // 网关接入地址
  authProvider: () => Promise<string>; // Token 获取函数
  retryPolicy: RetryPolicy;         // 统一重试策略
  observability: {
    metricsExporter: MetricsExporter; // 指标上报 (Prometheus/OTel)
    traceSampler: Sampler;          // 采样决策
  };
  lifecycle: {
    onConnecting: () => void;
    onConnected: (session: SessionContext) => void;
    onDisconnected: (reason: DisconnectReason) => void;
    onReconnecting: (attempt: number, delay: number) => void;
    onSignal: <T extends SignalType>(type: T, payload: SignalPayload<T>) => void;
  };
}

export interface RetryPolicy {
  maxAttempts: number;              // 最大重试次数 (建议 5)
  baseDelayMs: number;              // 基础延迟 (建议 1000ms)
  maxDelayMs: number;               // 最大延迟 (建议 30000ms)
  jitterFactor: number;             // 抖动系数 (建议 0.3)
  retriableCodes: GrpcStatusCode[]; // 可重试错误码 [UNAVAILABLE, DEADLINE_EXCEEDED, RESOURCE_EXHAUSTED]
}

# docs/COMPATIBILITY_MATRIX.md

| SDK Version | Min Gateway Version | Max Gateway Version | Deprecation Date | Notes |
|-------------|---------------------|---------------------|------------------|-------|
| 3.2.x       | 2.4.0               | 3.0.x               | 2025-06-30       | 支持 Stream Resumption |
| 3.1.x       | 2.2.0               | 2.5.x               | 2024-12-31       | 仅支持基础重连 |
| 3.0.x       | 2.0.0               | 2.3.x               | 2024-06-30       | **停止维护**，强制升级 |

runbooks/
├── 01-gateway-overload.md           # 网关过载/限流触发处理
├── 02-upstream-cascade-failure.md   # 上游级联故障熔断处理
├── 03-canary-rollback.md            # 灰度发布异常自动/手动回滚
├── 04-cross-region-failover.md      # 跨地域故障切流操作手册
├── 05-cert-emergency-rotation.md    # 证书泄露/过期紧急轮换
├── 06-rls-unavailable.md            # 限流服务不可用降级处理
└── 99-contact-list.md               # 核心依赖团队/人员联系方式