Envoy HTTP Connection Manager (HCM) 技术文档

1. 概述

1.1 组件定位

HTTP Connection Manager (HCM) 是 Envoy 代理的核心网络过滤器组件，负责处理 HTTP 协议的连接管理和请求处理全生命周期。

1.2 功能特性

多协议支持: 完整支持 HTTP/1.1、HTTP/2 和 HTTP/3 协议
统一抽象: 提供协议无关的连接和流管理接口
可扩展架构: 通过过滤器链机制支持功能扩展
企业级特性: 支持超时控制、负载均衡、追踪监控等

2. 核心类设计

2.1 ConnectionManagerImpl 类

2.1.1 继承关系

ruby 复制代码

class ConnectionManagerImpl :     public Logger::Loggable<Logger::Id::Http>,      // 日志支持    public Network::ReadFilter,                      // 网络读过滤器    public ServerConnectionCallbacks,                // 服务端连接回调    public Network::ConnectionCallbacks,             // 网络连接回调    public Http::ApiListener                         // API监听器

2.1.2 继承职责说明

基类	职责
`Network::ReadFilter`	作为网络过滤器处理连接上的HTTP数据读取
`ServerConnectionCallbacks`	管理HTTP连接生命周期回调
`Network::ConnectionCallbacks`	处理底层网络连接事件（高低水位、连接事件）
`Http::ApiListener`	支持API监听器模式，处理无网络连接的内部请求

2.1.3 核心成员变量

cpp 复制代码

class ConnectionManagerImpl {private:    ConnectionManagerConfig& config_;                     // HCM配置对象    ConnectionManagerStats& stats_;                      // 统计信息收集器    ServerConnectionPtr codec_;                          // HTTP协议编解码器    std::list<ActiveStreamPtr> streams_;                 // 活跃流链表    DrainState drain_state_{DrainState::NotDraining};    // 连接耗尽状态
    // 定时器组    Event::TimerPtr connection_idle_timer_;              // 连接空闲检测定时器    Event::TimerPtr connection_duration_timer_;          // 连接持续时间定时器    Event::TimerPtr drain_timer_;                        // 优雅关闭定时器
    // 依赖组件    Upstream::ClusterManager& cluster_manager_;          // 上游集群管理器    Router::RouteConfigProvider* route_config_provider_; // 路由配置提供者
    // 过载保护    const Server::OverloadActionState&         overload_stop_accepting_requests_ref_;           // 停止接收请求过载状态    const Server::OverloadActionState&         overload_disable_keepalive_ref_;                 // 禁用Keep-Alive过载状态
    // 统计计数    uint64_t accumulated_requests_{0};                   // 连接累积请求数};

2.2 主要方法接口

2.2.1 网络过滤器接口

cpp 复制代码

// 新连接建立时调用Network::FilterStatus onNewConnection() override;
// 接收到数据时调用Network::FilterStatus onData(Buffer::Instance& data, bool end_stream) override;
// 初始化过滤器回调void initializeReadFilterCallbacks(    Network::ReadFilterCallbacks& callbacks) override;

2.2.2 HTTP连接回调接口

cpp 复制代码

// 处理GoAway帧（HTTP/2协议）void onGoAway(GoAwayErrorCode error_code) override;
// 创建新的HTTP流RequestDecoder& newStream(    ResponseEncoder& response_encoder,     bool is_internally_created = false) override;

2.2.3 网络连接回调接口

cs 复制代码

// 处理网络连接事件（本地/远程关闭、连接错误等）void onEvent(Network::ConnectionEvent event) override;
// 写入缓冲区高水位事件处理void onAboveWriteBufferHighWatermark() override;
// 写入缓冲区低水位事件处理void onBelowWriteBufferLowWatermark() override;

3. 配置管理

3.1 ConnectionManagerConfig 接口

3.1.1 配置分类

超时配置组

cpp 复制代码

virtual absl::optional<std::chrono::milliseconds> idleTimeout() const;virtual absl::optional<std::chrono::milliseconds> maxConnectionDuration() const;virtual std::chrono::milliseconds streamIdleTimeout() const;virtual std::chrono::milliseconds requestTimeout() const;virtual std::chrono::milliseconds requestHeadersTimeout() const;virtual std::chrono::milliseconds delayedCloseTimeout() const;virtual absl::optional<std::chrono::milliseconds> maxStreamDuration() const;

限制配置组

cs 复制代码

virtual uint32_t maxRequestHeadersKb() const;      // 最大请求头大小(KB)virtual uint32_t maxRequestHeadersCount() const;   // 最大请求头数量virtual uint64_t maxRequestsPerConnection() const; // 单连接最大请求数

协议配置组

cpp 复制代码

virtual const Http::Http1Settings& http1Settings() const;virtual HttpConnectionManagerProto::ServerHeaderTransformation     serverHeaderTransformation() const;virtual envoy::config::core::v3::HttpProtocolOptions::HeadersWithUnderscoresAction    headersWithUnderscoresAction() const;

功能配置组

cpp 复制代码

virtual FilterChainFactory& filterFactory() const;        // 过滤器工厂virtual Router::RouteConfigProvider* routeConfigProvider() const; // 路由配置virtual Tracing::HttpTracerSharedPtr tracer() const;      // 追踪器virtual bool generateRequestId() const;                   // 是否生成请求ID

3.2 配置示例

python 复制代码

http_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_http    route_config:      name: local_route      virtual_hosts:      - name: backend        domains: ["*"]        routes:        - match:            prefix: "/"          route:            cluster: backend    http_filters:    - name: envoy.filters.http.router    http_protocol_options:      max_headers_count: 100    stream_idle_timeout: 300s    request_timeout: 30s

4. 流管理

4.1 ActiveStream 结构体

4.1.1 继承关系

cpp 复制代码

struct ActiveStream final :     public LinkedObject<ActiveStream>,           // 链表节点支持    public Event::DeferredDeletable,             // 延迟删除支持    public StreamCallbacks,                      // 流事件回调    public RequestDecoder,                       // 请求解码器    public Tracing::Config,                      // 追踪配置    public ScopeTrackedObject,                   // 作用域跟踪    public FilterManagerCallbacks                // 过滤器管理器回调

4.1.2 核心成员

cpp 复制代码

struct ActiveStream {    // 基础信息    ConnectionManagerImpl& connection_manager_;   // 所属连接管理器    const uint64_t stream_id_;                    // 全局唯一流ID
    // HTTP消息组件    RequestHeaderMapPtr request_headers_;         // 请求头    RequestTrailerMapPtr request_trailers_;       // 请求尾    ResponseHeaderMapPtr response_headers_;       // 响应头    ResponseTrailerMapPtr response_trailers_;     // 响应尾    ResponseHeaderMapPtr informational_headers_;  // 1xx信息性响应
    // 处理组件    FilterManager filter_manager_;                // 过滤器管理器    ResponseEncoder* response_encoder_;           // 响应编码器
    // 路由相关    Router::ConfigConstSharedPtr snapped_route_config_;        // 路由配置快照    Router::ScopedConfigConstSharedPtr snapped_scoped_routes_config_; // 作用域路由快照    absl::optional<Router::RouteConstSharedPtr> cached_route_; // 缓存的路由
    // 追踪    Tracing::SpanPtr active_span_;                // 活动追踪Span
    // 定时器组    Event::TimerPtr stream_idle_timer_;           // 流空闲定时器    Event::TimerPtr request_timer_;               // 请求定时器    Event::TimerPtr request_header_timer_;        // 请求头定时器    Event::TimerPtr max_stream_duration_timer_;   // 最大流持续时间定时器
    // 状态管理    State state_;                                 // 流状态标志位};

4.1.3 流状态标志

cs 复制代码

struct State {    bool codec_saw_local_complete_{false};    // 编解码器本地完成标志    bool saw_connection_close_{false};        // Connection: close标志    bool successful_upgrade_{false};          // 协议升级成功标志    bool is_internally_created_{false};       // 内部创建流标志    bool is_tunneling_{false};                // 隧道模式标志    bool decorated_propagate_{true};          // 装饰信息传播标志};

5. 核心流程

5.1 连接生命周期管

5.2 请求处理流程

5.3 超时管理机制

超时类型	触发条件	超时后的行为
连接空闲超时	连接上无任何活动	发送GoAway，关闭连接
连接最大持续时间	连接存活超过配置时长	发送GoAway，优雅关闭
流空闲超时	流上无请求/响应活动	重置流，发送错误
请求头超时	接收请求头超时	发送408 Request Timeout
请求超时	完整请求处理超时	发送504 Gateway Timeout
最大流持续时间	流存在时间超限	重置流
单连接最大请求数	请求数达到上限	发送Connection: close

6. 组件交互

6.1 与编解码器的交互

cpp 复制代码

// 编解码器创建与使用流程void ConnectionManagerImpl::createCodec(Buffer::Instance& data) {    // 通过配置工厂创建对应协议的编解码器    codec_ = config_.createCodec(        read_callbacks_->connection(),         data,         *this  // 作为ServerConnectionCallbacks    );}
// 编解码器回调触发流创建RequestDecoder& ConnectionManagerImpl::newStream(    ResponseEncoder& response_encoder,     bool is_internally_created) {
    // 创建新的ActiveStream    auto stream = std::make_unique<ActiveStream>(*this, response_encoder);    stream->is_internally_created_ = is_internally_created;
    // 添加到活跃流列表    streams_.push_back(std::move(stream));    return *streams_.back();}

6.2 与过滤器链的交互

cpp 复制代码

// ActiveStream中初始化过滤器链void ActiveStream::createFilterChain() {    // 通过配置工厂创建过滤器链    filter_manager_.addStreamFilter(        std::make_shared<StreamFilter>(...));
    // 遍历所有配置的过滤器    for (auto& filter_factory : connection_manager_.config_.filterFactory()) {        auto filter = filter_factory();        filter_manager_.addFilter(std::move(filter));    }
    // 最后添加Router过滤器    filter_manager_.addStreamFilter(        std::make_shared<Router::Filter>());}

6.3 与路由器的交互

cpp 复制代码

// 路由决策过程Router::RouteConstSharedPtr ActiveStream::route() {    if (cached_route_.has_value()) {        return cached_route_.value();    }
    // 获取路由配置    auto route_config = connection_manager_.config_.routeConfigProvider()                        ->config();
    // 执行路由匹配    auto route = route_config->route(*request_headers_, stream_id_);
    // 缓存路由结果    cached_route_ = route;    return route;}

7. 统计指标体系

7.1 连接级指标

指标名称	类型	说明
`downstream_cx_total`	Counter	总连接数
`downstream_cx_active`	Gauge	当前活跃连接数
`downstream_cx_http1_total`	Counter	HTTP/1.1连接总数
`downstream_cx_http2_total`	Counter	HTTP/2连接总数
`downstream_cx_length_ms`	Histogram	连接持续时间分布
`downstream_cx_idle_timeout`	Counter	空闲超时连接数
`downstream_cx_destroy_local`	Counter	本地关闭连接数
`downstream_cx_destroy_remote`	Counter	远程关闭连接数

7.2 请求级指标

指标名称	类型	说明
`downstream_rq_total`	Counter	总请求数
`downstream_rq_active`	Gauge	当前活跃请求数
`downstream_rq_2xx`	Counter	2xx响应数
`downstream_rq_4xx`	Counter	4xx响应数
`downstream_rq_5xx`	Counter	5xx响应数
`downstream_rq_time`	Histogram	请求处理时间分布
`downstream_rq_timeout`	Counter	请求超时数
`downstream_rq_rx_reset`	Counter	接收端重置数
`downstream_rq_tx_reset`	Counter	发送端重置数

7.3 流控指标

指标名称	类型	说明
`downstream_flow_control_paused_reading_total`	Counter	读暂停次数
`downstream_flow_control_resumed_reading_total`	Counter	读恢复次数
`downstream_cx_rx_bytes_buffered`	Gauge	接收缓冲区字节数
`downstream_cx_tx_bytes_buffered`	Gauge	发送缓冲区字节数

8. 性能优化建议

8.1 对象池化优化

cpp 复制代码

class ConnectionManagerImpl {public:    // 预分配ActiveStream对象池    void preAllocateStreamPool(uint32_t pool_size) {        for (uint32_t i = 0; i < pool_size; ++i) {            stream_pool_.push_back(std::make_unique<ActiveStream>(*this));        }    }
    ActiveStreamPtr acquireStream() {        if (!stream_pool_.empty()) {            auto stream = std::move(stream_pool_.back());            stream_pool_.pop_back();            stream->reset();            return stream;        }        return std::make_unique<ActiveStream>(*this);    }
    void releaseStream(ActiveStreamPtr stream) {        stream->clear();  // 清空状态        stream_pool_.push_back(std::move(stream));    }
private:    std::vector<ActiveStreamPtr> stream_pool_;};

优化效果：

减少动态内存分配次数 60-80%
降低内存碎片
提升高并发场景下的吞吐量

8.2 头部复用优化

cpp 复制代码

class HeaderMapPool {public:    RequestHeaderMapPtr allocate() {        if (!pool_.empty()) {            auto headers = std::move(pool_.back());            pool_.pop_back();            headers->clear();            return headers;        }        return std::make_unique<RequestHeaderMap>();    }
    void deallocate(RequestHeaderMapPtr headers) {        if (pool_.size() < max_pool_size_) {            pool_.push_back(std::move(headers));        }    }
private:    std::vector<RequestHeaderMapPtr> pool_;    static constexpr size_t max_pool_size_ = 1024;};

8.3 批处理优化

cpp 复制代码

// 批量处理多个流的事件void ConnectionManagerImpl::processPendingEvents() {    std::vector<ActiveStream*> pending_streams;    pending_streams.reserve(streams_.size());
    // 收集待处理的流    for (auto& stream : streams_) {        if (stream->hasPendingEvents()) {            pending_streams.push_back(stream.get());        }    }
    // 批量处理    for (auto* stream : pending_streams) {        stream->processEvents();    }}

9. 故障处理与恢复

9.1 错误码映射表

场景	HTTP状态码	Envoy内部错误	处理行为
请求头过大	431	`HeadersTooLarge`	关闭连接
请求头超时	408	`RequestTimeout`	发送错误响应
请求体过大	413	`PayloadTooLarge`	重置流
无效HTTP消息	400	`BadRequest`	发送错误响应
上游超时	504	`UpstreamTimeout`	网关超时
过载保护	503	`Overload`	服务不可用

9.2 优雅关闭流程

cpp 复制代码

void ConnectionManagerImpl::drainConnections() {    // 1. 设置耗尽状态    drain_state_ = DrainState::Draining;
    // 2. 停止接收新请求    codec_->goAway();
    // 3. 设置耗尽定时器    drain_timer_ = dispatcher_.createTimer([this]() {        // 强制关闭剩余连接        for (auto& stream : streams_) {            stream->resetStream();        }        read_callbacks_->connection().close();    });    drain_timer_->enableTimer(config_.drainTimeout());
    // 4. 响应Connection: close头部    for (auto& stream : streams_) {        stream->response_headers_->setReferenceConnection(            Headers::get().ConnectionValues.Close);    }}

10. 最佳实践

10.1 配置建议

场景	idleTimeout	streamIdleTimeout	requestTimeout	maxRequestsPerConnection
API网关	60s	30s	30s	1000
文件服务	300s	300s	300s	100
流媒体	3600s	3600s	不设置	1
内部RPC	30s	15s	15s	10000

10.2 监控告警阈值

bash 复制代码

alerts:  - name: HighActiveConnections    expr: downstream_cx_active > 10000    severity: warning
  - name: HighRequestLatency    expr: histogram_quantile(0.99, downstream_rq_time) > 5000    severity: critical
  - name: HighConnectionErrorRate    expr: rate(downstream_cx_protocol_error[5m]) > 0.01    severity: warning
  - name: HighResetRate    expr: rate(downstream_rq_rx_reset[1m]) > 10    severity: critical

11. 总结

11.1 架构优势

协议抽象 ：统一的ServerConnection接口屏蔽协议差异
流式处理 ：ActiveStream封装完整的请求-响应生命周期
过滤器链：灵活的扩展机制支持自定义业务逻辑
超时管理：多层次的超时控制保障系统稳定性
可观测性：丰富的统计指标支持精细化运维

11.2 适用场景

API网关：统一入口的请求路由、认证、限流
服务网格Sidecar：微服务间通信的流量管理
边缘代理：边缘节点的协议转换和安全防护
负载均衡器：七层负载均衡和流量分发

11.3 演进方向

QUIC/HTTP3优化：提升UDP传输性能和连接迁移能力
内存管理增强：进一步减少对象分配开销
智能超时控制：基于机器学习动态调整超时阈值
零拷贝优化：减少数据拷贝次数，提升吞吐量

附录

A. 关键数据结构

perl 复制代码

// 耗尽状态枚举enum class DrainState {    NotDraining,      // 正常状态    Draining,         // 耗尽中    Closing           // 关闭中};
// 流状态枚举enum class State {    NotStarted,       // 未开始    HeadersReceived,  // 头部已接收    HeadersOnly,      // 仅有头部    HeadersSent,      // 头部已发送    Complete,         // 完成    Closed            // 已关闭};

B. 参考资料

Envoy官方文档: https://www.envoyproxy.io/docs
HTTP/2规范: RFC 7540
HTTP/3规范: RFC 9114
Envoy源码仓库: https://github.com/envoyproxy/envoy