1. 概述
HTTP 是 Envoy 代理的核心协议,负责处理应用层通信。Envoy 的 HTTP 实现建立在其强大的网络层基础之上,与 TCP 和 libevent 架构深度关联。
核心特性
-
多协议支持: HTTP/1.1、HTTP/2、HTTP/3
-
自动协议检测: 根据数据流自动识别协议版本
-
连接管理: 完整的连接生命周期管理
-
流控制: 支持多路复用和流量控制
-
过滤器链: 可扩展的请求/响应处理管道
2. HTTP 连接管理器 - ConnectionManagerImpl
2.1 类定义
ruby
class ConnectionManagerImpl : Logger::Loggable<Logger::Id::http>, public Network::ReadFilter, public ServerConnectionCallbacks, public Network::ConnectionCallbacks, public Http::ApiListener {public: ConnectionManagerImpl(ConnectionManagerConfig& config, const Network::DrainDecision& drain_close, Random::RandomGenerator& random_generator, Http::Context& http_context, Runtime::Loader& runtime, const LocalInfo::LocalInfo& local_info, Upstream::ClusterManager& cluster_manager, Server::OverloadManager& overload_manager, TimeSource& time_system); ~ConnectionManagerImpl() override;
// Network::ReadFilter Network::FilterStatus onData(Buffer::Instance& data, bool end_stream) override; Network::FilterStatus onNewConnection() override; void initializeReadFilterCallbacks(Network::ReadFilterCallbacks& callbacks) override;
// Http::ServerConnectionCallbacks RequestDecoder& newStream(ResponseEncoder& response_encoder, bool is_internally_created = false) override;
// Network::ConnectionCallbacks void onEvent(Network::ConnectionEvent event) override; void onAboveWriteBufferHighWatermark() override; void onBelowWriteBufferLowWatermark() override;};
2.2 核心功能
| 功能模块 | 描述 |
|---|---|
| HTTP 协议处理 | 解析和封装 HTTP 协议数据,处理请求和响应 |
| 与网络层关联 | 作为 Network::ReadFilter 集成到 TCP 连接处理流程中 |
| 协议版本支持 | HTTP/1.1、HTTP/2、HTTP/3,支持自动协议检测和选择 |
2.3 实现细节
php
// HTTP 数据处理流程Network::FilterStatus ConnectionManagerImpl::onData(Buffer::Instance& data, bool end_stream) { // 延迟创建编解码器,直到有数据到达 if (!codec_) { createCodec(data); }
// 将数据传递给编解码器处理 codec_->dispatch(data);
// 继续处理下一个网络过滤器(如果有) return Network::FilterStatus::Continue;}
// 编解码器创建流程void ConnectionManagerImpl::createCodec(Buffer::Instance& data) { // 根据数据判断协议版本 if (isHttp2(data)) { codec_ = createHttp2Codec(); } else if (isHttp1(data)) { codec_ = createHttp1Codec(); } else { handleCodecError("Unsupported protocol"); return; }
codec_->initialize();}
3. HTTP 编解码器客户端 - CodecClient
3.1 类定义
cpp
class CodecClient : protected Logger::Loggable<Logger::Id::client>, public Http::ConnectionCallbacks, public Network::ConnectionCallbacks, public Event::DeferredDeletable {public: CodecClient(CodecType type, Network::ClientConnectionPtr&& connection, Upstream::HostDescriptionConstSharedPtr host, Event::Dispatcher& dispatcher);
void connect(); RequestEncoder& newStream(ResponseDecoder& response_decoder); void close();
Protocol protocol() { return codec_->protocol(); } size_t numActiveRequests() { return active_requests_.size(); }
// Http::ConnectionCallbacks void onGoAway(GoAwayErrorCode error_code) override; void onSettings(ReceivedSettings& settings) override; void onMaxStreamsChanged(uint32_t num_streams) override;
// Network::ConnectionCallbacks void onEvent(Network::ConnectionEvent event) override; void onAboveWriteBufferHighWatermark() override; void onBelowWriteBufferLowWatermark() override;};
3.2 核心功能
| 功能模块 | 描述 |
|---|---|
| HTTP 客户端抽象 | 提供统一的 HTTP 客户端接口,支持多协议版本 |
| 与网络层关联 | 封装 Network::ClientConnection,接收网络事件 |
| 流管理 | 处理流的创建、销毁、状态管理和超时控制 |
3.3 实现细节
cpp
// HTTP 流创建流程RequestEncoder& CodecClient::newStream(ResponseDecoder& response_decoder) { auto active_request = std::make_unique<ActiveRequest>(*this, response_decoder); RequestEncoder& encoder = codec_->newStream(response_decoder); active_request->encoder_ = &encoder; active_requests_.push_back(std::move(active_request)); return encoder;}
// 网络事件处理void CodecClient::onEvent(Network::ConnectionEvent event) { switch (event) { case Network::ConnectionEvent::Connected: codec_->initialize(); break; case Network::ConnectionEvent::RemoteClose: case Network::ConnectionEvent::LocalClose: remote_closed_ = true; resetAllStreams(); break; }}
4. HTTP 协议栈架构
4.1 整体架构图

4.2 实体关系图 (ER)

- HTTP 与 TCP 连接的协作流程
5.1 连接建立流程图

5.2 流程说明
| 步骤 | 组件 | 动作 |
|---|---|---|
| 1-2 | Client → TcpListener → ConnectionImpl | TCP 连接建立与接受 |
| 3-4 | ConnectionImpl → ConnectionManager | HTTP 连接管理器初始化 |
| 5 | ConnectionManager → CodecClient | 建立到上游服务器的连接 |
| 6-7 | Client → ConnectionManager | HTTP 请求接收 |
| 8-9 | ConnectionManager → CodecClient | 请求转发与响应接收 |
| 10-11 | ConnectionManager → Client | 响应返回客户端 |
6. HTTP 与 libevent 事件驱动的关联
6.1 定时器管理
kotlin
// ConnectionManagerImpl 中的定时器使用void ConnectionManagerImpl::initializeTimers() { // 连接空闲超时定时器 connection_idle_timer_ = dispatcher_.createTimer([this]() { this->onIdleTimeout(); }); connection_idle_timer_->enableTimer(config_.idle_timeout());
// 连接持续时间定时器 if (config_.connection_duration_timeout().has_value()) { connection_duration_timer_ = dispatcher_.createTimer( [this]() { this->onConnectionDurationTimeout(); }); connection_duration_timer_->enableTimer(config_.connection_duration_timeout().value()); }}
// ActiveStream 中的定时器使用ActiveStream::ActiveStream(ConnectionManagerImpl& connection_manager, uint32_t buffer_limit) : connection_manager_(connection_manager) { // 请求超时定时器 request_timer_ = connection_manager_.dispatcher_.createTimer( [this]() { this->onRequestTimeout(); }); request_timer_->enableTimer(config_.request_timeout());
// 请求头超时定时器 request_header_timer_ = connection_manager_.dispatcher_.createTimer( [this]() { this->onRequestHeaderTimeout(); }); request_header_timer_->enableTimer(config_.request_header_timeout());
// 流空闲超时定时器 stream_idle_timer_ = connection_manager_.dispatcher_.createTimer( [this]() { this->onIdleTimeout(); }); stream_idle_timer_->enableTimer(config_.stream_idle_timeout());}
6.2 定时器类型说明
| 定时器类型 | 作用 | 超时处理 |
|---|---|---|
| connection_idle_timer | 连接空闲超时 | 关闭空闲连接 |
| connection_duration_timer | 连接最大持续时间 | 强制关闭连接 |
| request_timer | 请求处理超时 | 返回 504 错误 |
| request_header_timer | 请求头接收超时 | 关闭连接 |
| stream_idle_timer | 流空闲超时 | 重置流 |
6.3 文件事件使用
php
// CodecClient 中的连接事件处理void CodecClient::onEvent(Network::ConnectionEvent event) { switch (event) { case Network::ConnectionEvent::Connected: connected_ = true; codec_->initialize(); break; case Network::ConnectionEvent::RemoteClose: remote_closed_ = true; resetAllStreams(StreamResetReason::RemoteReset, "Connection closed by remote"); break; case Network::ConnectionEvent::LocalClose: resetAllStreams(StreamResetReason::LocalReset, "Connection closed locally"); break; case Network::ConnectionEvent::ConnectError: handleConnectionError(); break; }}
- HTTP 协议版本支持
7.1 HTTP/1.1 实现
特点:
-
文本协议,易于调试
-
无状态协议,通过 Cookie 保持会话
-
支持流水线请求,效率不高
-
每个请求/响应都有独立的头信息
配置示例:
javascript
http1_settings: enable_trailing_headers: true allow_chunked_length: true enable_keep_alives: true max_concurrent_streams: 100 initial_window_size: 65536
7.2 HTTP/2 实现
特点:
-
二进制协议,效率更高
-
支持多路复用,多个流共享一个 TCP 连接
-
头部压缩(HPACK),减少带宽消耗
-
流量控制和优先级支持
配置示例:
apache
quic_options: connection_timeout: 5s max_concurrent_connections: 1000 idle_timeout: 300s max_datagram_size: 1452
7.3 HTTP/3 实现
特点:
-
基于 QUIC 协议,提供可靠的 UDP 传输
-
减少连接建立延迟(0-RTT 握手)
-
更好的多路复用性能(无队头阻塞)
-
天然的加密支持
配置示例:
apache
quic_options: connection_timeout: 5s max_concurrent_connections: 1000 idle_timeout: 300s max_datagram_size: 1452
7.4 协议对比
| 特性 | HTTP/1.1 | HTTP/2 | HTTP/3 |
|---|---|---|---|
| 传输协议 | TCP | TCP | UDP (QUIC) |
| 消息格式 | 文本 | 二进制 | 二进制 |
| 多路复用 | 不支持 | 支持 | 支持 |
| 队头阻塞 | 存在 | 存在(TCP层) | 不存在 |
| 头部压缩 | 无 | HPACK | QPACK |
| 连接建立延迟 | 较高 | 较高 | 较低(0-RTT) |
8. HTTP 与 TCP 实现的区别
8.1 协议层次
| 维度 | TCP | HTTP |
|---|---|---|
| 协议层次 | 传输层 | 应用层 |
| 依赖关系 | 独立 | 建立在 TCP/UDP 之上 |
| 数据模型 | 字节流服务 | 请求-响应式通信模型 |
8.2 数据处理
| 维度 | TCP | HTTP |
|---|---|---|
| 数据单元 | 字节流 | 结构化数据(请求、响应) |
| 应用语义 | 无 | 有(方法、路径、状态码) |
| 内容感知 | 不关心数据内容 | 关心数据内容 |
8.3 连接管理
| 维度 | TCP | HTTP |
|---|---|---|
| 连接类型 | 面向连接 | 无状态协议 |
| 建立方式 | 三次握手 | 可复用 TCP 连接 |
| 关闭方式 | 四次挥手 | 支持流水线请求 |
9. 性能优化与架构设计
9.1 连接池管理
cpp
class ConnectionPoolBase : public std::enable_shared_from_this<ConnectionPoolBase> {public: virtual ClientConnectionPtr connect() = 0; virtual void addConnectionCallback(ConnectionCallback& callback) = 0; virtual void removeConnectionCallback(ConnectionCallback& callback) = 0;};
class ConnectionPoolImpl : public ConnectionPoolBase {public: ClientConnectionPtr connect() override { // 从连接池中获取或创建新连接 if (!idle_connections_.empty()) { auto connection = std::move(idle_connections_.front()); idle_connections_.pop_front(); return connection; }
if (active_connections_.size() < max_connections_) { return createNewConnection(); }
// 连接池已满,等待空闲连接 return nullptr; }
private: std::list<ClientConnectionPtr> idle_connections_; std::unordered_set<ClientConnectionPtr> active_connections_; size_t max_connections_;};
9.2 流管理优化
cpp
struct ActiveStream final : LinkedObject<ActiveStream>, public Event::DeferredDeletable, public StreamCallbacks, public RequestDecoder { void completeRequest() { // 标记流完成 state_.codec_saw_local_complete_ = true;
// 清理定时器 disarmRequestTimeout(); resetIdleTimer();
// 统计信息更新 updateStats();
// 延迟删除流,避免在回调中删除对象 connection_manager_.doDeferredStreamDestroy(*this); }
void onIdleTimeout() { resetStream(StreamResetReason::IdleTimeout); }};
9.3 优化技术总结
| 优化技术 | 实现方式 | 收益 |
|---|---|---|
| 连接池 | 复用 TCP 连接 | 减少连接建立开销 |
| 流多路复用 | HTTP/2 多流共享连接 | 提高连接利用率 |
| 延迟删除 | DeferredDeletable 机制 | 避免回调中对象销毁 |
| 定时器优化 | ScaledTimer 自适应超时 | 减少定时器开销 |
| 零拷贝 | Buffer 引用传递 | 减少内存拷贝 |
10. HTTP 过滤器链
10.1 过滤器架构
cpp
class FilterManager : public FilterManagerCallbacks {public: FilterManager(ActiveStream& stream, ConnectionManagerImpl& connection_manager, const ConnectionManagerConfig& config);
// 应用请求过滤器链 void applyRequestFilters(RequestHeaderMapPtr&& headers);
// 应用响应过滤器链 void applyResponseFilters(ResponseHeaderMapPtr&& headers);
private: std::vector<RequestDecoderFilterPtr> request_filters_; std::vector<ResponseEncoderFilterPtr> response_filters_; ActiveStream& stream_; ConnectionManagerImpl& connection_manager_;};
10.2 内置过滤器
| 过滤器名称 | 功能描述 |
|---|---|
envoy.filters.http.router |
路由转发,必选过滤器 |
envoy.filters.http.jwt_authn |
JWT 认证 |
envoy.filters.http.rate_limit |
速率限制 |
envoy.filters.http.cors |
跨域资源共享 |
envoy.filters.http.gzip |
压缩解压 |
envoy.filters.http.ext_authz |
外部授权 |
10.3 过滤器配置示例
bash
http_filters: # 认证过滤器 - name: envoy.filters.http.jwt_authn typed_config: "@type": type.googleapis.com/envoy.extensions.filters.http.jwt_authn.v3.JwtAuthentication providers: my_provider: issuer: example.com audiences: - api.example.com remote_jwks: http_uri: uri: https://example.com/.well-known/jwks.json timeout: 5s cache_duration: 300s
# 速率限制过滤器 - name: envoy.filters.http.rate_limit typed_config: "@type": type.googleapis.com/envoy.extensions.filters.http.rate_limit.v3.RateLimit domain: example_domain stage: 0
# 路由过滤器(必须最后) - name: envoy.filters.http.router typed_config: "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
11. 架构关联总结
11.1 与 TCP 架构的关联
-
连接管理: HTTP 连接建立在 TCP 连接之上,使用 ConnectionImpl 管理底层连接
-
数据传输: HTTP 数据通过 TCP 连接传输,使用 Network::ReadFilter 接收数据
-
错误处理: TCP 错误会导致 HTTP 连接关闭,HTTP 协议错误也会影响 TCP 连接状态
11.2 与 libevent 架构的关联
-
事件驱动: HTTP 连接和流管理使用 event_base 进行事件调度
-
定时器: HTTP 超时(连接、请求、响应)使用 Event::Timer 实现
-
文件事件: HTTP 数据传输通过 FileEventImpl 监听 socket 事件
11.3 架构优势
| 维度 | 优势说明 |
|---|---|
| 高性能 | 事件驱动架构支持高并发;连接池减少连接开销;多路复用提高连接利用率 |
| 可靠性 | 完整的错误处理和恢复机制;超时管理防止资源泄漏;健康检查保证服务可用性 |
| 可扩展性 | 模块化设计易于添加新功能;过滤器链支持功能扩展;插件化设计允许自定义协议 |
12. 配置示例
12.1 完整 HTTP 代理配置
css
static_resources: listeners: - name: http_listener address: socket_address: { address: 0.0.0.0, port_value: 8080 } filter_chains: - 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 codec_type: AUTO route_config: name: local_route virtual_hosts: - name: local_service domains: ["*"] routes: - match: { prefix: "/" } route: { cluster: "example_cluster" } http_filters: - name: envoy.filters.http.router
clusters: - name: example_cluster connect_timeout: 0.25s type: STRICT_DNS lb_policy: ROUND_ROBIN http2_protocol_options: {} load_assignment: cluster_name: example_cluster endpoints: - lb_endpoints: - endpoint: address: socket_address: { address: 127.0.0.1, port_value: 80 }
12.2 关键配置参数说明
| 参数 | 说明 | 推荐值 |
|---|---|---|
codec_type |
编解码器类型(AUTO/HTTP1/HTTP2/HTTP3) | AUTO |
idle_timeout |
连接空闲超时 | 300s |
request_timeout |
请求处理超时 | 30s |
stream_idle_timeout |
流空闲超时 | 60s |
max_requests_per_connection |
单连接最大请求数 | 100 |
13. HTTP 请求完整生命周期流程
13.1 阶段概览

13.2 详细处理流程
13.2.1 请求接受阶段
php
// ConnectionManagerImpl 构造函数ConnectionManagerImpl::ConnectionManagerImpl(ConnectionManagerConfig& config, const Network::DrainDecision& drain_close, Random::RandomGenerator& random_generator, Http::Context& http_context, Runtime::Loader& runtime, const LocalInfo::LocalInfo& local_info, Upstream::ClusterManager& cluster_manager, Server::OverloadManager& overload_manager, TimeSource& time_source) : config_(config), stats_(config_.stats()), conn_length_(new Stats::HistogramCompletableTimespanImpl( stats_.named_.downstream_cx_length_ms_, time_source)), drain_close_(drain_close), user_agent_(http_context.userAgentContext()), random_generator_(random_generator), http_context_(http_context), runtime_(runtime), local_info_(local_info), cluster_manager_(cluster_manager), listener_stats_(config_.listenerStats()), overload_state_(overload_manager.getThreadLocalOverloadState()), time_source_(time_source) {}
// 初始化读取过滤器回调void ConnectionManagerImpl::initializeReadFilterCallbacks(Network::ReadFilterCallbacks& callbacks) { read_callbacks_ = &callbacks; stats_.named_.downstream_cx_total_.inc(); stats_.named_.downstream_cx_active_.inc();
// 创建连接超时定时器 if (config_.idleTimeout()) { connection_idle_timer_ = read_callbacks_->connection().dispatcher().createScaledTimer( Event::ScaledTimerType::HttpDownstreamIdleConnectionTimeout, [this]() -> void { onIdleTimeout(); }); connection_idle_timer_->enableTimer(config_.idleTimeout().value()); }}
13.2.2 请求解码阶段
cpp
RequestDecoder& ConnectionManagerImpl::newStream(ResponseEncoder& response_encoder, bool is_internally_created) { if (connection_idle_timer_) { connection_idle_timer_->disableTimer(); }
// 创建 ActiveStream 实例 auto& buffer_factory = read_callbacks_->connection().dispatcher().getWatermarkFactory(); Buffer::BufferMemoryAccountSharedPtr downstream_stream_account = buffer_factory.createAccount(response_encoder.getStream()); response_encoder.getStream().setAccount(downstream_stream_account);
ActiveStreamPtr new_stream(new ActiveStream(*this, response_encoder.getStream().bufferLimit(), std::move(downstream_stream_account)));
accumulated_requests_++; if (config_.maxRequestsPerConnection() > 0 && accumulated_requests_ >= config_.maxRequestsPerConnection()) { if (codec_->protocol() < Protocol::Http2) { new_stream->state_.saw_connection_close_ = true; drain_state_ = DrainState::Closing; } }
new_stream->response_encoder_ = &response_encoder; new_stream->response_encoder_->getStream().addCallbacks(*new_stream); LinkedList::moveIntoList(std::move(new_stream), streams_);
return **streams_.begin();}
13.2.3 请求处理阶段
php
void ConnectionManagerImpl::ActiveStream::decodeHeaders(RequestHeaderMapPtr&& headers, bool end_stream) { request_headers_ = std::move(headers); filter_manager_.requestHeadersInitialized();
// 路径规范化处理 const auto action = ConnectionManagerUtility::maybeNormalizePath(*request_headers_, connection_manager_.config_); if (action == ConnectionManagerUtility::NormalizePathAction::Reject) { sendLocalReply(Code::BadRequest, "", nullptr, absl::nullopt, StreamInfo::ResponseCodeDetails::get().PathNormalizationFailed); return; }
// 应用过滤器链 filter_manager_.decodeHeaders(*request_headers_, end_stream);}
13.2.4 响应生成与发送
php
void ConnectionManagerImpl::ActiveStream::encodeHeaders(ResponseHeaderMap& headers, bool end_stream) { // 设置 Date 头部 if (!headers.Date()) { connection_manager_.config_.dateProvider().setDateHeader(headers); }
// 设置 Server 头部 const auto transformation = connection_manager_.config_.serverHeaderTransformation(); if (transformation == ConnectionManagerConfig::HttpConnectionManagerProto::OVERWRITE || (transformation == ConnectionManagerConfig::HttpConnectionManagerProto::APPEND_IF_ABSENT && headers.Server() == nullptr)) { headers.setReferenceServer(connection_manager_.config_.serverName()); }
chargeStats(headers); response_encoder_->encodeHeaders(headers, end_stream);}
void ConnectionManagerImpl::ActiveStream::encodeData(Buffer::Instance& data, bool end_stream) { filter_manager_.streamInfo().addBytesSent(data.length()); response_encoder_->encodeData(data, end_stream);}
13.3 关键性能优化点
| 优化点 | 实现方式 | 说明 |
|---|---|---|
| 连接持续时间控制 | max_connection_duration 定时器 |
防止连接长期占用 |
| 连接空闲超时 | idle_timeout 定时器 |
释放空闲连接资源 |
| 流空闲超时 | stream_idle_timeout 定时器 |
清理不活跃的流 |
| 请求超时控制 | request_timeout 定时器 |
防止请求挂起 |
| 延迟删除 | deferredDelete 机制 |
避免回调中删除对象 |
| 协议自动检测 | 数据流分析 | 减少手动配置 |
13.4 配置优化建议
apache
http_connection_manager: # 连接管理配置 idle_timeout: 300s max_connection_duration: 3600s max_requests_per_connection: 100 delayed_close_timeout: 15s
# 超时配置 stream_idle_timeout: 60s request_timeout: 30s request_headers_timeout: 5s max_stream_duration: 120s
# 协议配置 codec_type: AUTO http1_settings: accept_http_10: true default_host_for_http_10: "example.com" http2_settings: initial_stream_window_size: 65536 initial_connection_window_size: 1048576 max_concurrent_streams: 256
附录
A. 错误码说明
| 错误码 | 说明 | 处理建议 |
|---|---|---|
| 400 | Bad Request | 检查请求格式 |
| 408 | Request Timeout | 增加超时配置 |
| 431 | Request Header Fields Too Large | 增加 header 限制 |
| 500 | Internal Server Error | 检查上游服务 |
| 502 | Bad Gateway | 检查上游连接 |
| 503 | Service Unavailable | 检查上游健康状态 |
| 504 | Gateway Timeout | 增加超时配置 |
B. 相关源码文件
| 文件路径 | 说明 |
|---|---|
source/common/http/conn_manager_impl.cc |
HTTP 连接管理器实现 |
source/common/http/codec_client.cc |
HTTP 编解码器客户端 |
source/common/http/filter_manager.cc |
过滤器管理器 |
source/common/http/http1/codec_impl.cc |
HTTP/1 编解码器 |
source/common/http/http2/codec_impl.cc |
HTTP/2 编解码器 |
source/common/http/utility.cc |
HTTP 工具函数 |