Go HTTP 服务偶发 503 如何区分应用和代理

Go HTTP 服务偶发 503，不能只凭响应页面或 Server 头判断是应用还是代理。先把同一次请求的入口最终状态、代理上游状态与应用拒绝日志关联起来：应用记录了同一请求并明确写出 503，是应用生成响应的重要证据；上游状态缺失且代理错误日志能解释本地拒绝，则优先检查代理或更前面的入口层。还要区分“谁生成 503”和“哪项依赖引发失败”，两者可能不是同一层。

Go HTTP 官方文档：https://pkg.go.dev/net/http

Nginx 官方文档：https://nginx.org/en/docs/

503 只能说明不可用，不能指出哪层生成

503 表示服务器暂时无法处理请求，例如临时过载或维护；它本身没有编码“来自反向代理”或“来自数据库”。HTTP 语义见 https://www.rfc-editor.org/rfc/rfc9110.html#name-503-service-unavailable。在负载高峰、发布切换和依赖降级时，同一个对外状态可能由不同组件生成。

先画清楚系统边界：入口与代理分组包含客户端、入口、代理；业务与依赖分组包含 Go 应用、数据库、外部服务。客户端依赖入口，入口关联代理，代理选择 Go 应用作为上游，Go 应用再依赖数据库与外部服务。本文图中连线只是静态依赖，并不证明某次请求实际经过全部节点。

完整日志关联、单点直连与临时响应标记三种方法各有成本。日志关联覆盖真实故障但需要统一字段；直连对照简便但可能改变路由条件；响应标记容易看到却可能被代理替换。应以关联日志为主，其他方法作为条件受控的补充。

让代理记录最终状态与每次上游尝试

以 Nginx 为例，至少记录 request_id、status、upstream_status、upstream_addr 与耗时。下面的 log_format 和 access_log 放在已有 http 配置块内；不是完整 Nginx 配置，不应覆盖原配置文件。

# 放在 http 块：记录最终状态和上游尝试，保留逗号分隔的多次结果。
log_format layer_diag escape=json
    '{"rid":"$request_id","status":"$status",'
    '"upstream_status":"$upstream_status","upstream_addr":"$upstream_addr",'
    '"request_time":"$request_time","upstream_time":"$upstream_response_time"}';
access_log /var/log/nginx/layer-diag.log layer_diag;

# 放在已有代理 location 中：覆盖客户端输入，使用代理生成的关联标识。
proxy_set_header X-Request-ID $request_id;
# 对外只保留代理这一份标识，失败响应也携带它。
proxy_hide_header X-Request-ID;
add_header X-Request-ID $request_id always;

status 是最终对客户端的状态，upstream_status 是上游响应状态记录，两者不一定相同。发生多次上游尝试时，地址、状态和耗时可以包含多个值，不能仅截取最后一项丢弃前面的失败。无法选出服务器时，Nginx 的 upstream_status 可以记为 502，不能把它机械解释成应用发回了 502。

字段定义见 https://nginx.org/en/docs/http/ngx_http_upstream_module.html，日志格式说明见 https://nginx.org/en/docs/http/ngx_http_log_module.html。本文示例将数值字段写成字符串，便于保留缺失值及多次尝试记录。

实施前还需检查配置继承：当前 location 已经存在 proxy_set_header 或 add_header 时，合并规则可能影响其他必要头。保留原 Host、转发和响应头约定，不因增加诊断字段而悄悄改变请求条件。边缘入口如果已有可信追踪标识，可以按系统契约传递，但不能无条件信任公网客户端传来的身份字段。

在 Go 的 503 分支留下明确原因

只记录“handler 被调用”不够，还应在应用确定拒绝的分支写出 status 与稳定的 reason。下面给出用于已有服务的 Handler 构造函数，ready 必须能够安全地被并发调用；它不是实际数据库探测实现。

package diag

import (
    "log"
    "net/http"
)

func ReportHandler(ready func() bool) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // 仅在应用位于可信代理后且不开放公网直连时信任该标识。
        rid := r.Header.Get("X-Request-ID")
        log.Printf("rid=%q component=app event=begin", rid)
        if !ready() {
            // 在写状态前标记失败来源；具体依赖细节只留在内部日志。
            w.Header().Set("X-App-Error-Code", "report_not_ready")
            log.Printf("rid=%q component=app status=503 reason=report_not_ready", rid)
            http.Error(w, "service temporarily unavailable",
                http.StatusServiceUnavailable)
            return // 防止失败后继续生成成功响应。
        }
        w.Header().Set("Content-Type", "text/plain; charset=utf-8")
        w.WriteHeader(http.StatusOK)
        log.Printf("rid=%q component=app status=200", rid)
        // 写入错误单独记录，它不等于自动把已提交的 200 改成 503。
        if _, err := w.Write([]byte("report ready\n")); err != nil {
            log.Printf("rid=%q component=app write_error=%q", rid, err.Error())
        }
    })
}

这里应用的失败原因是 report_not_ready，不是凭空声称数据库连接池耗尽。实际项目应按限流、熔断、维护、依赖超时等明确分支记录，并在日志中加入实例身份及相关依赖调用标识。不要记录认证令牌、完整请求体或敏感查询参数。

Go 应用自身的包装器也可能生成 503。例如 http.TimeoutHandler 在处理超过指定时限时会返回 503；它不等于代理的超时配置。因此应查看实际的 handler 包装链，不能把所有“业务函数没写 503”的情况都归到代理。

把应用响应和依赖根因分开判断

关联证据分组包括 request_id、代理日志、应用日志；责任字段分组包括 upstream_status、reason、依赖日志。request_id 关联两种日志，代理日志包含 upstream_status，应用日志包含 reason，reason 的业务解释需要依赖日志支撑。这些关系帮助确认响应生成层，也帮助继续追踪根因。

proxy_intercept_errors 配合 error_page 可以处理上游错误，最终页面因而可能看起来像代理页面；proxy_next_upstream 还可能产生多次尝试。缓存也可能让返回内容不来自当次应用处理。相关配置见 https://nginx.org/en/docs/http/ngx_http_proxy_module.html。响应头与页面样式只能当线索，不能当单独定论。

如果应用因外部服务不可用主动返回 503，响应生成层仍是应用，根因候选才是依赖。进一步查看依赖的错误类型、调用耗时与资源状态，避免看到“应用返回”就认定应用逻辑错误，也避免直接把所有 503 映射成数据库故障。

用受控对照收尾而不是盲目重试

若要比较代理入口与应用直连，必须使用授权的测试或内网环境，保持方法、路径、Host、认证条件及实例选择一致。一次直连成功只证明那个时刻和那个实例成功，不足以排除偶发应用故障。优先使用无副作用的诊断请求；不要为了排障重复提交订单等非幂等操作。

修复选择也应跟证据一致：配置拒绝就修入口策略，应用过载就核对容量和限流，依赖失败就设计有界超时与降级。增加重试会放大负载并掩盖第一次失败，多层同时重试尤其需要总预算与幂等约束。诊断所需额外日志有成本，可以限定故障时间窗，但应保留失败分支和请求标识。

落地清单包括：标识在可信入口生成并贯穿应用；代理保留最终与所有上游尝试；应用记录明确的 503 分支；依赖记录可关联；实例和时间可对照；缓存与错误重写可解释。本文代码与配置为原创说明示例，未在本地执行，也没有宣称发现真实线上故障。

Server: nginx 能证明 Nginx 生成 503 吗？

不能。代理可以在转发上游错误时仍使用自己的响应头，必须结合日志和实际配置。

应用没有 503 分支是不是一定由代理返回？

不一定。还可能有应用包装器、中间件或另一实例；先检查完整处理链。

收到 Retry-After 就能无限重试吗？

不能。还需遵守请求幂等性、最大次数和总时限，重试提示不代表后端已经恢复。