Envoy HTTP 协议实现技术文档

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)

  1. 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;  }}
  1. 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 架构的关联

  1. 连接管理: HTTP 连接建立在 TCP 连接之上,使用 ConnectionImpl 管理底层连接

  2. 数据传输: HTTP 数据通过 TCP 连接传输,使用 Network::ReadFilter 接收数据

  3. 错误处理: TCP 错误会导致 HTTP 连接关闭,HTTP 协议错误也会影响 TCP 连接状态

11.2 与 libevent 架构的关联

  1. 事件驱动: HTTP 连接和流管理使用 event_base 进行事件调度

  2. 定时器: HTTP 超时(连接、请求、响应)使用 Event::Timer 实现

  3. 文件事件: 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 工具函数
相关推荐
牛大兵7 小时前
IP扫描,局域网内扫描IP地址,找出有用,未使用的。正在使用的信息
服务器·网络·tcp/ip
CDN3607 小时前
告别“慢”与“不安全”:360CDN动态API加速与HTTPS配置实战
网络协议·安全·https
minji...7 小时前
Linux 网络套接字编程(七)TCP服务端和客户端的实现——网络版本计算器
linux·运维·服务器·网络·c++·tcp/ip·udp
aodunsoft7 小时前
安全月报 | 傲盾DDoS攻击防御2026年4月简报
网络·安全·ddos
Lucis__7 小时前
HTTP协议深度解析—从HTTP原理到手写实现服务器
服务器·网络协议·http
S1998_1997111609•X7 小时前
iOS栈被恶意篡改变成开发者模式漏洞裸露内核系统核心功能栈被泄露于政府黑客集团泄漏安全系统置门的犯罪行为原理
数据库·网络协议·百度·ssh·开闭原则
byoass7 小时前
企业云盘全文检索技术选型:Elasticsearch、MeiliSearch、Typesense实战对比
大数据·网络·安全·elasticsearch·云计算·全文检索
mounter6257 小时前
【Linux 网络进阶】下一代虚拟网络设备 netkit 详解:超越 veth 的云原生基石
linux·服务器·网络·io_uring·netkit·devmem·hard lease
pengyi8710158 小时前
代理IP选型优化,从源头降低HTTP代理延迟
网络协议·tcp/ip·http