Higress Pilot 工作原理详解

本文档详细说明 Higress Pilot 组件的架构设计和工作原理，帮助开发者深入理解 Higress 控制面的核心机制。

---

1. 概述

1.1 什么是 Higress Pilot

Higress Pilot 是 Higress 控制面的核心组件之一（另一个是 Controller），它基于 Istio Pilot-Discovery 进行二次定制化开发，主要负责：

• 服务发现：监控服务注册中心，实时感知服务实例变化
• 配置管理：将高级路由规则转换为 Envoy 配置
• 配置下发：通过 xDS 协议动态下发配置到数据面
• 流量调度：控制流量路由规则和负载均衡策略

1.2 在 Higress 架构中的位置

flowchart TB
    subgraph "控制面 (Control Plane)"
        Controller[Higress Controller<br/>监控 K8s API 资源]
        Pilot[Higress Pilot<br/>Pilot-Discovery]
    end

    subgraph "数据面 (Data Plane)"
        Gateway[Higress Gateway<br/>Pilot Agent + Envoy]
    end

    subgraph "外部系统"
        K8s[Kubernetes API Server]
        Registry[(服务注册中心<br/>Nacos/Consul/Eureka)]
    end

    K8s --> Controller
    Registry --> Controller
    Controller -->|MCP over xDS| Pilot
    Pilot -->|xDS 协议| Gateway

    style Controller fill:#e1f5fe
    style Pilot fill:#fff9c4
    style Gateway fill:#c8e6c9

---

2. 核心架构

2.1 Pilot 内部组件结构

flowchart TB
    subgraph "Higress Pilot (pilot-discovery)"
        Environment[model.Environment<br/>核心环境对象]

        subgraph "配置层"
            ConfigStore[ConfigStore<br/>配置存储]
            ConfigController[ConfigController<br/>配置控制器]
        end

        subgraph "发现层"
            ServiceDiscovery[ServiceDiscovery<br/>服务发现]
            RegistryWatcher[RegistryWatcher<br/>注册中心监听]
        end

        subgraph "协议层"
            XDSServer[xDS Server<br/>配置下发服务]
            MCPClient[MCP Client<br/>配置协议客户端]
        end

        Environment --> ConfigStore
        Environment --> ServiceDiscovery
        ConfigController --> ConfigStore
        RegistryWatcher --> ServiceDiscovery
        MCPClient --> ConfigController
        ConfigController --> XDSServer
    end

    subgraph "数据面"
        Envoy[Envoy Proxy]
        PilotAgent[Pilot Agent]
    end

    XDSServer -->|gRPC xDS| PilotAgent
    PilotAgent --> Envoy

    style Environment fill:#ffecb3
    style XDSServer fill:#b3e5fc
    style MCPClient fill:#f8bbd0

2.2 核心对象：model.Environment

model.Environment 是 Pilot 中的核心环境对象，集成了多个关键组件：

type Environment struct {
    // 推送上下文
    PushContext *PushContext

    // 域名后缀
    DomainSuffix string

    // 服务发现接口
    ServiceDiscovery ServiceDiscovery

    // 配置存储
    IstioConfigStore ConfigStoreCache

    // MCP 模式开关
    MCPMode bool

    // Ledger - 状态版本管理
    Ledger Ledger
}

---

3. 工作流程

3.1 配置流转全流程

sequenceDiagram
    participant K8s as Kubernetes API
    participant Controller as Higress Controller
    participant Pilot as Higress Pilot
    participant Envoy as Envoy Proxy

    K8s->>Controller: 1. Ingress/Gateway 资源变更
    Controller->>Controller: 2. 转换为 Istio 资源
    Controller->>Pilot: 3. MCP over xDS 推送配置
    Pilot->>Pilot: 4. 合并配置生成 PushContext
    Pilot->>Envoy: 5. xDS 协议下发配置
    Envoy->>Envoy: 6. 动态更新配置生效

3.2 详细处理流程

flowchart TB
    Start([配置变更事件]) --> Watch[Informer 监听资源]
    Watch --> Validate{配置验证}
    Validate -->|失败| Drop([丢弃配置])
    Validate -->|成功| Convert[转换为 Istio 资源]

    Convert --> Merge{配置合并}
    Merge --> IngressConfig[Ingress 配置]
    Merge --> GatewayConfig[Gateway API 配置]
    Merge --> WasmPluginConfig[WasmPlugin 配置]
    Merge --> McpBridgeConfig[McpBridge 配置]

    IngressConfig --> PushContext
    GatewayConfig --> PushContext
    WasmPluginConfig --> PushContext
    McpBridgeConfig --> PushContext

    PushContext[生成 PushContext] --> XDSGen[生成 xDS 配置]
    XDSGen --> LDS[LDS - Listener]
    XDSGen --> CDS[CDS - Cluster]
    XDSGen --> RDS[RDS - Route]
    XDSGen --> EDS[EDS - Endpoint]
    XDSGen --> ADS[ADS - Aggregated]

    LDS --> Push[推送到数据面]
    CDS --> Push
    RDS --> Push
    EDS --> Push
    ADS --> Push

    Push --> End([配置生效])

    style Start fill:#e1f5fe
    style End fill:#c8e6c9
    style PushContext fill:#fff9c4
    style XDSGen fill:#b3e5fc

---

4. xDS 协议详解

4.1 xDS 协议类型

xDS（Discovery Service）是 Envoy 的动态配置协议，Higress Pilot 支持以下类型：

xDS 类型	全称	作用
ADS	Aggregated Discovery Service	聚合发现服务，按顺序下发所有配置
LDS	Listener Discovery Service	监听器发现，配置监听器和过滤器链
CDS	Cluster Discovery Service	集群发现，配置上游服务集群
RDS	Route Discovery Service	路由发现，配置 HTTP 路由规则
EDS	Endpoint Discovery Service	端点发现，配置服务实例地址

4.2 xDS 配置下发顺序

flowchart LR
    A[ADS 连接建立] --> B[EDS<br/>端点配置]
    B --> C[CDS<br/>集群配置]
    C --> D[LDS<br/>监听器配置]
    D --> E[RDS<br/>路由配置]

    style A fill:#e1f5fe
    style E fill:#c8e6c9

4.3 ADS 聚合下发流程

sequenceDiagram
    participant Envoy as Envoy
    participant Pilot as Higress Pilot

    Envoy->>Pilot: ADS StreamRequest
    Pilot->>Pilot: 验证连接身份
    Pilot->>Envoy: EDS Response (端点)
    Pilot->>Envoy: CDS Response (集群)
    Pilot->>Envoy: LDS Response (监听器)
    Pilot->>Envoy: RDS Response (路由)

    Note over Envoy: 配置动态生效

---

5. MCP 协议

5.1 MCP 在 Higress 中的角色

MCP（Mesh Configuration Protocol）是一种基于 xDS 协议的配置管理协议。

flowchart TB
    subgraph "Higress Controller"
        McpServer[MCP Server]
        IngressController[Ingress Controller]
        GatewayController[Gateway Controller]
        WasmPluginController[WasmPlugin Controller]
    end

    subgraph "Higress Pilot"
        McpClient[MCP Client]
        XdsServer[xDS Server]
    end

    IngressController --> McpServer
    GatewayController --> McpServer
    WasmPluginController --> McpServer

    McpServer -->|MCP over xDS| McpClient
    McpClient --> XdsServer

    style McpServer fill:#f8bbd0
    style McpClient fill:#b3e5fc

5.2 MCP 配置同步流程

1. Higress Controller 监听 Kubernetes 资源变化
2. Higress Core 将资源转换为 Istio 配置
3. MCP Server 通过 MCP over xDS 推送到 Pilot
4. Pilot 将配置合并到 PushContext
5. xDS Server 通过 xDS 协议下发到 Envoy

---

6. 配置控制器详解

6.1 IngressConfig 控制器结构

classDiagram
    class IngressConfig {
        +map~string,IngressController~ remoteIngressControllers
        +IngressRouteCollection ingressRouteCache
        +IngressDomainCollection ingressDomainCache
        +McpBridgeController mcpbridgeController
        +WasmPluginController wasmPluginController
        +Http2RpcController http2rpcController
        +ConfigmapMgr configmapMgr
        +XDSUpdater XDSUpdater
        +RegisterEventHandler()
        +AddOrUpdateWasmPlugin()
        +DeleteWasmPlugin()
        +AddOrUpdateMcpBridge()
        +DeleteMcpBridge()
        +List()
    }

    class IngressController {
        +ServiceInformer
        +IngressInformer
        +Run()
        +List()
        +RegisterEventHandler()
    }

    class WasmPluginController {
        +WasmPluginLister
        +AddEventHandler()
        +Get()
    }

    class McpBridgeController {
        +McpBridgeLister
        +AddEventHandler()
        +Get()
    }

    IngressConfig "1" --> "*" IngressController
    IngressConfig "1" --> "1" WasmPluginController
    IngressConfig "1" --> "1" McpBridgeController

6.2 核心控制器说明

控制器	功能	监听资源	输出资源
Ingress Controller	K8s Ingress 转换	Ingress	Gateway, VirtualService, DestinationRule
Gateway Controller	Gateway API 转换	Gateway, HTTPRoute	Gateway, VirtualService
McpBridge Controller	注册中心桥接	McpBridge	ServiceEntry, WorkloadEntry
WasmPlugin Controller	Wasm 插件管理	WasmPlugin	Istio WasmPlugin
Http2Rpc Controller	协议转换	Http2Rpc	VirtualService
ConfigmapMgr	全局配置管理	ConfigMap	EnvoyFilter

---

7. 服务发现机制

7.1 服务发现架构

flowchart TB
    subgraph "服务注册中心"
        K8sService[Kubernetes Service]
        Nacos[Nacos]
        Consul[Consul]
        Eureka[Eureka]
    end

    subgraph "McpBridge"
        Bridge1[服务发现桥接]
    end

    subgraph "Pilot"
        ServiceDiscovery[ServiceDiscovery 接口]
        ServiceInstance[ServiceEntry]
        WorkloadEntry[WorkloadEntry]
    end

    K8sService --> ServiceDiscovery
    Nacos --> Bridge1 --> ServiceInstance
    Consul --> Bridge1
    Eureka --> Bridge1

    ServiceDiscovery --> EDSGenerator[EDS 配置生成器]
    EDSGenerator --> Envoy[Envoy Endpoint]

    style ServiceDiscovery fill:#fff9c4
    style EDSGenerator fill:#b3e5fc

7.2 服务发现流程

1. Kubernetes 原生服务：直接通过 ServiceInformer 获取
2. 外部注册中心：通过 McpBridge 配置桥接，转换为 ServiceEntry
3. DNS 服务：通过 DNS 解析获取服务地址
4. 固定地址：通过 WorkloadEntry 配置静态服务

---

8. 配置推送机制

8.1 PushContext 生成

flowchart TB
    Start([配置变更]) --> Trigger[触发推送条件]

    Trigger --> Build[构建 PushContext]
    Build --> MergeConfig[合并所有配置源]
    MergeConfig --> Sort[按优先级排序]
    Sort --> Validate[配置校验]

    Validate -->|成功| GenXDS[生成 xDS 配置]
    Validate -->|失败| Rollback[回滚配置]

    GenXDS --> Push[推送到连接的 Proxy]
    Push --> ACK[等待 ACK]
    ACK -->|成功| Success([推送成功])
    ACK -->|失败| Retry[重试推送]

    Retry --> Push

    style Start fill:#e1f5fe
    style Success fill:#c8e6c9
    style Rollback fill:#ffcdd2

8.2 推送触发条件

配置推送在以下情况触发：

• 配置资源变更：Ingress/Gateway/WasmPlugin 等资源更新
• 服务实例变化：Service Endpoint 变化
• 密钥变更：Secret 资源更新
• 定时全量推送：根据配置的间隔时间

---

9. 本地开发调试

9.1 环境准备

# 1. 克隆 Higress 仓库
git clone https://github.com/alibaba/higress.git
cd higress

# 2. 初始化子模块（包含 Istio 上游代码）
git submodule update --init

# 3. 应用 Higress 补丁
make prebuild

9.2 提取配置文件

# 创建配置目录
mkdir -p /tmp/pilot-config
cd /tmp/pilot-config

# 提取配置
kubectl get configmap higress-config -n higress-system \
    -o=jsonpath='{.data.mesh}' > ./mesh

kubectl get configmap higress-config -n higress-system \
    -o=jsonpath='{.data.meshNetworks}' > ./meshNetworks

9.3 配置环境变量

export CUSTOM_CA_CERT_NAME=higress-ca-root-cert
export JWT_POLICY=none
export PILOT_ENABLE_GATEWAY_API=true
export PILOT_SCOPE_GATEWAY_TO_NAMESPACE=true
export POD_NAME=higress-controller
export POD_NAMESPACE=higress-system
export REVISION=default
export VALIDATION_ENABLED=false

9.4 启动 Pilot

# 启动 Pilot Discovery
cd external/istio
go run pilot/cmd/pilot-discovery/main.go \
    discovery \
    --monitoringAddr=:15014 \
    --log_output_level=default:info \
    --domain cluster.local \
    --meshConfig /tmp/pilot-config/mesh \
    --networksConfig /tmp/pilot-config/meshNetworks

9.5 调试配置

修改 higress-config ConfigMap 使 Gateway 连接到本地 Pilot：

apiVersion: v1
kind: ConfigMap
metadata:
  name: higress-config
  namespace: higress-system
data:
  mesh: |
    discoveryAddress: 192.168.1.100:15010  # 修改为本地 IP
    controlPlaneAuthPolicy: NONE            # 添加认证豁免

重启 Gateway 使配置生效：

kubectl rollout restart deployment/higress-gateway -n higress-system

---

10. 核心源码分析

10.1 启动流程

pkg/cmd/server.go

func NewServer(args *ServerArgs) (*Server, error) {
    // 1. 初始化 Environment
    e := &model.Environment{
        PushContext:  model.NewPushContext(),
        DomainSuffix: constants.DefaultKubernetesDomain,
        MCPMode:      true,
    }

    // 2. 设置 Ledger
    e.SetLedger(buildLedger(args.RegistryOptions))

    // 3. 设置服务发现
    e.ServiceDiscovery = aggregate.NewController(...)

    // 4. 创建 Server
    s := &Server{
        environment: e,
        server:      server.New(),
    }

    // 5. 初始化各个组件
    initFuncList := []func() error{
        s.initKubeClient,
        s.initXdsServer,
        s.initHttpServer,
        s.initConfigController,
        s.initRegistryEventHandlers,
    }

    for _, f := range initFuncList {
        if err := f(); err != nil {
            return nil, err
        }
    }

    return s, nil
}

10.2 xDS 服务初始化

func (s *Server) initXdsServer() error {
    // 创建 xDS Server
    s.xdsServer = xds.NewDiscoveryServer(
        s.environment,
        nil,
        PodName,
        PodNamespace,
        s.RegistryOptions.KubeOptions.ClusterAliases,
    )

    // 注册 MCP 生成器
    s.xdsServer.McpGenerators[gvk.WasmPlugin.String()] = &mcp.WasmpluginGenerator{Server: s.xdsServer}
    s.xdsServer.McpGenerators[gvk.Gateway.String()] = &mcp.GatewayGenerator{Server: s.xdsServer}
    s.xdsServer.McpGenerators[gvk.VirtualService.String()] = &mcp.VirtualServiceGenerator{Server: s.xdsServer}

    // 配置推送条件
    s.xdsServer.ProxyNeedsPush = func(proxy *model.Proxy, req *model.PushRequest) bool {
        return true
    }

    return nil
}

---

11. 与 Istio Pilot 的差异

特性	Istio Pilot	Higress Pilot
定位	Service Mesh 控制面	API 网关控制面
配置来源	Kubernetes + MCP	Kubernetes (Ingress/Gateway API)
MCP 模式	可选	默认启用
Gateway API	实验性支持	完整支持
Wasm 插件	基础支持	扩展支持（多级配置）
注册中心	Kubernetes	K8s + Nacos/Consul/Eureka
轻量化	较重	轻量化设计

---

12. 参考资料

• Higress 官方文档
• Higress Pilot 调试教程
• Higress 源码分析
• Istio xDS 协议说明
• Envoy xDS 协议

---