Traefik 健康检查实战：/ping 端点与 traefik healthcheck CLI 的配置、退出码与底层原理

本文围绕 Traefik 安装配置文档中的 Health Check 主题展开，讲解如何通过内置 /ping 存活探测端点和 traefik healthcheck CLI 子命令检查 Traefik 实例的健康状态，并结合 cmd/healthcheck/healthcheck.go、pkg/ping/ping.go 等源码，说明端点注册链路、退出码语义、manualRouting 与 terminatingStatusCode 选项的底层实现。读完后你可以把健康检查接入 Docker HEALTHCHECK、Kubernetes LivenessProbe 等编排机制，并理解优雅停机期间状态码是如何被切换的。

两种健康检查手段概览

Traefik 提供了两条互补的健康检查路径：

1. CLI 子命令：traefik healthcheck 向 /ping 端点发起一次请求，根据结果输出退出码——健康时退出码为 0，否则为 1。这个语义专为容器与编排系统（HEALTHCHECK 指令、K8s probe 等）设计。
2. /ping HTTP 端点：通过命令行 --ping 或配置文件 [ping] 段启用。存活状态下返回 200，优雅停机期间可返回自定义状态码。

两者是配套关系：CLI 本质上是替你调用 /ping 端点的一个“外部探针”。

/ping 端点

/ping 健康检查 URL 由命令行的 --ping 或配置文件的 [ping] 选项启用，默认处于关闭状态。端点所在的 EntryPoint 可以通过 entryPoint 选项自定义，默认值是 traefik（端口 8080）。

端点行为定义如下：

Path	Method	说明
/ping	GET, HEAD	检查 Traefik 进程存活性的端点，返回状态码 200，响应内容为 OK

启用配置示例

分别以 YAML、TOML、CLI 三种方式启用 ping handler：

# File (YAML)
ping: {}

# File (TOML)
[ping]

# CLI
--ping=true

在静态配置结构体中，ping 段对应 Ping *ping.Handler 字段（见 static_config.go），字段带 allowEmpty 标记，因此 ping: {} 这种空写法是合法的——只要字段非 nil，ping 功能即被启用。

配置选项

字段	说明	默认值	必填
ping.entryPoint	在指定 EntryPoint 上启用 /ping	traefik	否
ping.manualRouting	设为 true 时禁用默认内部路由，允许你为 ping@internal 服务自建路由	false	否
ping.terminatingStatusCode	定义优雅停机（graceful shut down）期间 ping handler 返回的状态码，详见下文	503	否

manualRouting：手动接管 /ping 路由

从源码结构看，默认路由是在内置 provider 中自动生成的。internal.go 中的 pingConfiguration 方法展示了它的逻辑：

• 只要静态配置中 Ping != nil，就会注册一个空的 ping 内部服务；
• 当 manualRouting 为 false 时，额外创建一条高优先级（math.MaxInt）的内部路由，规则为 PathPrefix(\/ping`)，绑定到 ping.entryPoint指定的入口点，服务指向ping@internal`；
• 当 manualRouting 为 true 时，跳过上述默认路由的创建，仅保留 ping@internal 服务，从而允许用户在动态配置中自定义路由规则（例如限定 Host、挂接中间件等）。

而 ping@internal 服务的解析入口在 internalhandler.go：服务名为 ping@internal 时，若 ping 未启用（handler 为 nil）会返回 "ping is not enabled" 错误；handler 实例则由 managerfactory.go 在 staticConfiguration.Ping != nil 时注入。

terminatingStatusCode：优雅停机期间的状态码

在 Traefik 优雅停机（graceful shut down）期间，ping handler 默认返回 503 状态码。如果 Traefik 部署在某个执行健康检查的负载均衡器（例如 Kubernetes LivenessProbe）之后，外部系统可能期望另一个特定状态码作为“正在优雅退出”的信号。此时可以用 terminatingStatusCode 设置停机期间 ping handler 返回的状态码，例如设为 204：

# File (YAML)
ping:
  terminatingStatusCode: 204

# File (TOML)
[ping]
  terminatingStatusCode = 204

# CLI
--ping.terminatingStatusCode=204

集成测试中就存在一份对应的真实配置样例 custom_ping_termination_status_code.toml，其中设置了 terminatingStatusCode = 204，可用于验证该选项的端到端行为。

底层实现（pkg/ping/ping.go）非常简洁，Handler 的关键行为有：

• SetDefaults() 将 EntryPoint 置为 traefik、TerminatingStatusCode 置为 503（http.StatusServiceUnavailable），与文档表格中的默认值一致；
• WithContext(ctx) 启动一个 goroutine 监听 ctx.Done()，一旦停机信号到来就置位内部 terminating 布尔标志；
• ServeHTTP 在 terminating 为假时返回 200，为真时返回 TerminatingStatusCode 配置的值，响应体为对应的状态文本（如 OK）。

这意味着状态码切换不依赖进程退出，而是由 server 的 context 取消事件驱动，停机窗口内的探测请求会立即拿到新的状态码。

CLI：traefik healthcheck

CLI 子命令可以直接向 /ping 端点发请求来检查 Traefik 的健康状态：退出码在 Traefik 健康时为 0，否则为 1。这个特性可以配合 Docker HEALTHCHECK 指令或任何其它健康检查编排机制使用。

用法

traefik healthcheck [command] [flags] [arguments]

示例输出：

$ traefik healthcheck
OK: http://:8082/ping

实现细节（源码印证）

CLI 的实现位于 cmd/healthcheck/healthcheck.go，有几个值得注意的行为细节：

1. 依赖静态配置定位端点。命令通过 NewCmd(traefikConfiguration, loaders) 接收与主进程相同的静态配置加载器（见文件中的 NewCmd 函数），执行时会调用 traefikConfiguration.SetEffectiveConfiguration() 解析配置，因此 CLI 能够自动找到 ping 端点所在 EntryPoint 的地址——示例输出中的 http://:8082/ping 即按配置解析出的入口点地址拼接而成。
2. ping 未启用会直接报错。Do() 函数在 staticConfiguration.Ping == nil 时返回错误 please enable 'ping' to use health check 并以退出码 1 结束，这提醒使用者：健康检查的前提是主实例已开启 [ping]。
3. 入口点必须存在。若 ping.entryPoint 指定的入口点不存在，返回 ping: missing <name> entry point 错误。
4. 使用 HEAD 请求且超时 5 秒。Do() 创建了一个超时为 5 秒的 http.Client，通过 client.Head(...) 发起请求；协议目前硬编码为 http（源码中留有 TODO 注释，说明 TLS 场景的 ping 尚未处理）。因此对 ping 入口点启用 TLS 时，CLI 健康检查的行为需以仓库当前实现为准。
5. 退出码语义。执行成功且响应状态为 200 时打印 OK: <url> 并以 0 退出；请求出错或状态码非 200 时分别打印 Error calling healthcheck: ... 或 Bad healthcheck status: ... 并以 1 退出。

在 cmd/traefik/traefik.go 中，healthcheck 被注册为 traefik 主命令的子命令，因此与 traefik --help 看到的其它子命令并列存在。

实战建议

• Docker 场景：容器镜像中使用 traefik healthcheck 作为 HEALTHCHECK CMD，配合 --ping 启动参数即可获得标准的 0/1 退出码探针。
• Kubernetes 场景：LivenessProbe 直接请求 /ping；若希望区分“正常运行（200）”与“正在优雅退出（自定义码）”，配置 ping.terminatingStatusCode，并参考 custom_ping_termination_status_code.toml 的取值（204）。
• 自定义路由：需要给 /ping 加中间件、限定 Host 或改变路径前缀时，将 ping.manualRouting 设为 true，然后在动态配置中自建指向 ping@internal 服务的 router；从 internalhandler.go 的解析逻辑可见，该内部服务在 ping 启用后始终可被引用。
• 注意事项：ping 默认不启用，CLI 健康检查依赖主实例的静态配置来定位端点地址；当前仓库实现中 CLI 仅以明文 HTTP 访问端点（cmd/healthcheck/healthcheck.go 中 TLS 处理仍为 TODO），对 ping 入口启用 TLS 时应改由外部探针（curl/K8s probe）直接访问。

小结

Traefik 的健康检查体系由三个部分构成：静态配置中的 ping 段（entryPoint / manualRouting / terminatingStatusCode 三个选项）、内置 provider 自动生成的 ping@internal 高优先级路由、以及退出码驱动的 traefik healthcheck CLI。三者共同覆盖了从“进程存活探测”到“优雅停机信号”的完整需求，且各环节均可在 pkg/ping/ping.go、pkg/provider/traefik/internal.go、cmd/healthcheck/healthcheck.go 中找到对应源码印证。