服务器生命周期

相关源文件

• listeners.go
• listeners_test.go
• modules/caddyhttp/app.go
• modules/caddyhttp/server.go

本文档解释了Caddy的HTTP系统中HTTP服务器如何创建、启动、管理和关闭。它涵盖了从服务器供应到优雅关闭的完整生命周期，包括连接管理和请求处理。

有关正在运行的服务器中请求路由和处理程序执行的信息，请参阅请求路由。有关TLS连接处理的详细信息，请参阅连接策略。

概述

Caddy的HTTP服务器生命周期由HTTP App 和各个 Server 实例管理的几个不同阶段组成。该生命周期确保了可靠的启动、高效的请求处理和资源清理妥善的优雅关闭。

服务器生命周期阶段

来源: modules/caddyhttp/app.go166-410 modules/caddyhttp/app.go446-645 modules/caddyhttp/app.go647-772

服务器供应

HTTP App 管理多个 Server 实例，每个实例由一个任意名称标识。在供应过程中，服务器会配置其监听器、路由和策略。

App供应流程

来源: modules/caddyhttp/app.go166-410 modules/caddyhttp/server.go45-263

供应过程验证了HTTP/2和H2C协议不能在没有HTTP/1.1的情况下启用，这是Go标准库实现的要求。

配置	默认值	目的
协议	["h1", "h2", "h3"]	启用的HTTP协议
IdleTimeout	5分钟	连接空闲超时
ReadHeaderTimeout	1分钟	头部读取超时
ClientIPHeaders	["X-Forwarded-For"]	受信任的代理头部

服务器启动

服务器启动会创建网络监听器并开始接受跨多个协议的连接。

启动过程

来源: modules/caddyhttp/app.go446-645 modules/caddyhttp/server.go601-633 listeners.go135-205

监听器创建

Caddy使用 NetworkAddress 系统创建监听器，该系统支持端口范围和多种网络类型。

来源: listeners.go135-205 listeners.go308-374 modules/caddyhttp/app.go532-594

请求处理生命周期

每个HTTP请求在服务器内部遵循标准化的处理流程。

ServeHTTP 流程

来源: modules/caddyhttp/server.go265-451 modules/caddyhttp/server.go871-897

请求上下文设置

PrepareRequest() 函数用Caddy特定的信息丰富请求上下文。

上下文键	类型	目的
ServerCtxKey	*Server	服务器实例引用
VarsCtxKey	map[string]any	请求变量
OriginalRequestCtxKey	http.Request	未修改的请求副本
ConnCtxKey	net.Conn	底层连接
TrustedProxyVarKey	bool	代理信任状态
ClientIPVarKey	字符串	真实客户端IP

来源: modules/caddyhttp/server.go871-897 modules/caddyhttp/server.go1071-1090

优雅停机

Caddy实现了复杂的优雅关闭过程，该过程尊重现有连接，同时阻止新连接。

关机流程

来源: modules/caddyhttp/app.go647-772

关闭配置

设置	默认	目的
GracePeriod	永久	优雅关闭的最长时间
ShutdownDelay	0	开始关闭前的延迟

关闭过程确保：

• 不再接受新连接
• 现有连接在宽限期内自然完成
• 资源得到妥善清理
• 已注册的停止钩子被执行

连接状态管理

服务器可以注册各种连接生命周期事件的回调。

回调注册

来源: modules/caddyhttp/server.go635-685 modules/caddyhttp/server.go258-262

HTTP协议支持

Caddy同时支持多种HTTP协议

协议	网络	需要TLS	备注
HTTP/1.1	TCP	可选	基本协议
HTTP/2	TCP	是	需要启用h1
H2C	TCP	否	明文HTTP/2
HTTP/3	UDP	是	QUIC传输

来源: modules/caddyhttp/app.go521-628 modules/caddyhttp/server.go601-633

错误处理

服务器实现了全面的错误处理，包括日志记录和自定义错误路由。

错误处理。

当主处理程序链返回错误时，服务器会：

1. 恢复原始请求状态
2. 将错误信息添加到请求上下文
3. 如果已配置，则执行错误处理程序链
4. 记录具有相应严重级别的错误
5. 发送适当的HTTP状态响应

来源: modules/caddyhttp/server.go378-451 modules/caddyhttp/server.go687-731

错误处理系统在保留请求可追溯性的同时，通过错误路由提供了灵活的错误响应定制。