滚动发布时,新实例刚起来,旧实例收到编排系统发来的 SIGTERM。进程没有做任何处理,默认行为就是立刻退出;正在上传文件、正在提交订单的请求全部断开,用户看到的是连接被重置。发布窗口不长,但每次都有几条失败请求,日志里只有一行「进程退出」,没有上下文。

另一种故障更危险:健康检查只判断进程还在不在,数据库连接已经断了,接口全部返回 500,健康检查仍然返回 200。负载均衡继续把流量发给这台机器,用户持续报错,直到有人手工摘除实例。进程活着和服务可用不是一回事,用一个检查覆盖两件事,迟早会误判。

这篇讲上线前的最后一段:怎么编译出可复现的二进制、配置怎么在启动时校验、日志怎么写成可检索的 JSON、两个健康检查怎么分工、收到停止信号后怎么排空请求,以及容器内存限制下怎么设置 GOMEMLIMIT。示例的交叉编译、健康检查和 JSON 日志都在本机实际跑过,涉及数据库就绪检查与真实 SIGTERM 排空的部分会单独说明未验证。

构建:静态、可复现、带版本

Go 默认把依赖和运行时编进二进制,部署时不需要在服务器上装 Go。但如果启用了 CGO,二进制会动态链接系统库,换到精简镜像或另一台机器就可能报找不到库。发布用的构建应该显式关闭 CGO,并指定目标系统和架构:

$env:CGO_ENABLED="0"
$env:GOOS="linux"
$env:GOARCH="amd64"
go build -trimpath -ldflags "-s -w -X main.version=1.2.3" -o deploydemo-linux .
module demo/deploydemo

go 1.27.3

require github.com/gin-gonic/gin v1.10.1

-trimpath 去掉构建路径,让不同机器编出的二进制更接近;-s -w 去掉符号表和调试信息,体积更小;-X main.version=1.2.3 在链接阶段把版本写进变量。版本号应该来自 CI 的提交号或标签,不要手工改代码。本机实际执行这条命令,得到一个 Linux 可执行文件,大小是 8,671,392 字节,健康检查返回的版本号正是 1.2.3。

发布产物要可追溯。镜像或压缩包里带上版本号、提交号、构建时间,启动日志里也打一份。线上出问题时,第一件事往往是确认「这台机器跑的是哪一版」,如果只能靠部署记录去猜,排查会慢很多。版本信息通过 -X 注入,不要写死在源码里,否则每次发版都要改代码、提交、再构建。

可复现意味着同一份代码、同一组依赖,在哪台构建机上都能得到行为一致的产物。锁住依赖版本、提交 go.sum、在 CI 里固定 Go 版本,是最基本的三件事。不要在发布前临时执行 go get 最新版,也不要在服务器上现场编译;构建和运行分离,产物只构建一次,再分发到各环境。

CGO 关闭也有代价。某些库依赖 C 实现,关闭后无法编译;DNS 解析会走纯 Go 实现,行为和系统解析器略有差异;涉及系统证书、时区的功能仍然需要镜像里带证书和 tzdata。静态编译解决的是「不依赖系统库」,不是「什么都不需要」。

配置:环境变量加启动校验

十二要素应用把配置放在环境里,Go 服务用环境变量最直接。端口、环境名、数据库地址、JWT 密钥、日志级别都从环境读,启动时解析成结构体并校验。缺端口可以给默认值,缺生产密钥必须拒绝启动;格式错误、范围越界也要在启动阶段报错,而不是等第一个请求。

变量用途缺失时
APP_PORT监听端口开发环境可用默认值,生产建议必填
APP_ENV区分开发、预发、生产默认开发,但不能用于生产判断
DATABASE_URL数据库连接串生产必须存在,启动时探活
JWT_SECRET令牌签名密钥生产必须存在且不能是示例值
LOG_LEVEL日志级别默认 info,解析失败直接退出

配置不要散落在各个包里。os.Getenv 出现在 handler 深处时,你无法一眼看出这个服务依赖哪些变量,也没法在启动时统一校验。集中到一个 config.Load(),返回结构体和错误,main 里只判断一次。测试可以传入不同的环境值,不必改全局状态。

密钥不要打进镜像,不要提交到仓库,也不要完整打印。日志里只记录「已加载配置、环境名、端口、版本」,不记录连接串和密钥。容器编排的密钥注入方式各有不同,但原则相同:运行时注入、只读挂载、最小权限,进程退出后不在磁盘上留明文。

日志:一行一个 JSON,带请求 ID

标准库的 log/slog 已经够用,不需要额外引日志框架。生产环境用 slog.NewJSONHandler 输出到标准输出,由容器运行时收集;开发环境可以用文本格式,方便人读。级别、时间、消息、字段名保持稳定,日志平台才能做聚合和告警。

var version = "dev"

slog.SetDefault(slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
	Level: slog.LevelInfo,
})))

slog.Info("server starting", "addr", srv.Addr, "version", version)

本机实际启动这个示例,输出了下面这一行。时间是带时区的,版本号来自链接参数,字段名和值都是真实的:

{"time":"2026-11-07T08:28:38.3390289+08:00","level":"INFO","msg":"server starting","addr":":18090","version":"1.2.3"}

访问日志要带请求 ID,才能把一次请求的多条日志串起来。请求 ID 由入口中间件生成或从上游透传,写进响应头和日志字段;下游调用也带上,跨服务排查时不会断链。没有请求 ID 时,只能靠时间戳和路径去猜,日志一多就没法用。

不要记录请求体、Authorization 头、Cookie 和完整连接串。密码、令牌、个人信息一旦进日志,清理成本很高,还可能违反合规要求。需要排查时记录字段名、长度、哈希前缀,或者只记录业务 id。日志级别也要克制,debug 在生产默认关闭,需要时按请求 ID 临时打开,而不是长期全量输出。

健康检查:healthz 与 readyz 分工

两个端点回答两个不同的问题。/healthz 是存活检查:进程还在运行、还能处理 HTTP 吗;失败时编排系统重启实例。/readyz 是就绪检查:这个实例现在能接业务流量吗;失败时从负载均衡里摘掉,但不重启。把两者合成一个,就会在数据库短暂抖动时重启所有实例,把小故障放大成雪崩。

healthz只看进程自身,不查数据库、不调下游,快速返回 200。它用于「要不要重启」,不是「业务是否正常」。
readyz检查依赖是否可用,带很短的超时;数据库不可用、迁移未完成、启动未就绪时返回 503。它用于「要不要接流量」。
业务监控错误率、延迟、队列深度,这些不该塞进健康检查。健康检查是二值开关,不是仪表盘。

就绪检查里的数据库探活要用独立的短超时,几秒即可,不要复用业务查询。探活频率高,每次都跑复杂 SQL 会给数据库增加无谓压力;一条 SELECT 1 或驱动提供的 Ping 足够。数据库连接池刚建立时可能还没连上,启动阶段可以给一个宽限期,或者让 readyz 在首次成功探活前一直返回 503。

本机实际请求这两个端点,返回如下。示例的 readyz 没有接数据库,只验证路由和格式;真实项目要把数据库探活加进去,失败时返回 503。

go mod tidy
$env:APP_PORT="18090"
go run .

curl -i http://127.0.0.1:18090/healthz
curl -i http://127.0.0.1:18090/readyz
GET /healthz
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 33

{"status":"ok","version":"1.2.3"}
GET /readyz
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 18

{"status":"ready"}

健康检查的判定要保守。检查太敏感,依赖抖一下就把所有实例摘掉,流量无处可去;检查太宽松,坏实例一直留在池子里。实际做法是连续失败若干次才判失败,恢复后连续成功若干次才重新放量,给系统一点抖动空间。具体次数由编排系统配置,不要写死在应用里。

优雅停机:先摘流量,再排空

收到 SIGTERM 后,进程还有一小段宽限期,编排系统到点才强杀。这段时间应该做三件事:把就绪状态切成失败,让负载均衡停止发新请求;等待一小段时间,让已经在途的请求到达;调用 Shutdown,等待正在处理的请求完成,再关闭数据库连接池和后台任务。

一次发布中的停机顺序
收到 SIGTERM
readyz 返回 503
等待在途流量
Shutdown 排空
关闭资源退出
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
<-ctx.Done()

srv.SetKeepAlivesEnabled(false)
shutdownCtx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
defer cancel()
if err := srv.Shutdown(shutdownCtx); err != nil {
	slog.Error("shutdown failed", "err", err)
}

Shutdown 会停止接受新连接,关闭空闲连接,等待正在处理的请求返回。它不会强制中断处理函数,所以慢请求会一直占着,直到超时。超时时间要小于编排系统的宽限期,留出关闭连接池和写最后一条日志的时间。超时后 Shutdown 返回错误,进程再退出,这时仍在跑的请求会被切断,属于兜底而非正常路径。

处理函数要尊重请求上下文。数据库查询、下游调用都用带 ctx 的方法,这样客户端断开或停机超时时,它们能提前退出,不会把连接拖到最后一刻。如果处理函数里写的是不接受上下文的长循环,Shutdown 只能干等,最后仍然超时。

本机在 Windows 上验证时,测试脚本用强制结束进程来清理,SIGTERM 的完整排空路径没有实际跑过;Linux 上可以用 kill -TERM 进程号 配合一个故意慢 2 秒的接口观察:请求应该正常返回,日志里出现「收到停止信号」和「服务已停止」,而不是连接重置。

反向代理、超时与可信代理

Go 服务通常跑在 Nginx、云负载均衡或网关后面。代理有自己的连接超时、读超时、写超时,应用也有 http.Server 的超时,任何一层设置不当都会表现为 502 或 504。排查时先确认请求停在拿一层,不要只盯着应用日志。

层常见设置作用
客户端请求超时用户愿意等多久,决定前端重试策略
负载均衡后端响应超时超过就返回 504,不再等应用
反向代理连接、读、写超时保护自己不被慢连接拖住
应用ReadHeaderTimeout、WriteTimeout限制慢请求和慢响应占用连接

用 Gin 的 r.Run 启动时,底层是 http.ListenAndServe,没有设置读写超时。生产上更稳的做法是自己构造 http.Server,设置 ReadHeaderTimeout、ReadTimeout、WriteTimeout 和 IdleTimeout,再调用 ListenAndServe。超时值要能容纳正常的长请求,比如文件上传或报表导出,不能一刀切设得很短。

代理转发时会带上 X-Forwarded-For 和 X-Forwarded-Proto,Gin 默认信任所有代理,c.ClientIP() 可能被客户端伪造的头部欺骗。部署时必须调用 SetTrustedProxies 指定代理网段,或者设置为 nil 表示不信任任何代理。限流、审计、风控如果依赖客户端 IP,这一点尤其重要。

内存:GOMEMLIMIT 与容器限制

Go 的垃圾回收由 GOGC 控制,默认在堆增长到上次回收后的两倍时触发。容器有内存上限,堆之外的运行时结构、栈、CGO、文件映射也占内存,所以不能把 GOMEMLIMIT 设成容器上限本身。留出一部分余量,让 GC 在接近上限前更积极地工作。

GOMEMLIMIT 是软限制,不是硬上限。它告诉运行时「尽量把总内存控制在这个值附近」,但不会阻止一次性大分配,也不能保证绝对不超。超过容器限制时,内核 OOM killer 直接杀进程,退出码通常是 137。看到 137 时先区分是 Go 堆涨得太快,还是非堆内存或子进程占用,再决定调 GOMEMLIMIT 还是查内存泄漏。

设置方式可以用环境变量 GOMEMLIMIT=800MiB,也可以在代码里用运行时接口。数值要结合压测和实际内存曲线,不要照搬。把限制设得太低,GC 会频繁运行,CPU 升高、延迟变差;设得太高,等于没设。上线后观察 GC 频率、堆大小和容器内存使用,再逐步调整。

容器与 systemd:两种交付方式

容器

镜像自带运行时依赖,滚动发布、扩缩容、健康探针都由编排系统管理。代价是需要维护镜像、仓库和编排配置;静态二进制仍然需要证书和时区数据,镜像不能一味追求小。

systemd

一个二进制加一个 unit 文件就能跑,启动快、排查直接,适合单机或少量实例的服务。代价是发布、回滚、扩缩容要自己写脚本,进程守护和日志轮转依赖系统配置。

两种方式对应用的要求相同:配置从环境来、日志写标准输出、健康检查有明确语义、收到停止信号能排空。把这些做对,换交付方式只是外围脚本的差别。反过来,应用本身没有就绪检查和优雅停机,容器编排也救不了发布时的请求中断。

容器里不要以 root 运行,文件系统尽量只读,时区显式设置为业务时区,证书目录确认存在。systemd 里写清 ExecStart、Restart、TimeoutStopSec 和环境变量,KillSignal 用 SIGTERM 而不是直接 SIGKILL。这些细节决定停机时有没有机会排空。

现象、原因与第一步

现象真实原因第一步查什么
发布时请求被重置进程收到 SIGTERM 直接退出,没有 Shutdown 排空看停止信号处理、就绪切换和编排宽限期
健康检查 200 但接口全 500只有存活检查,没有就绪检查或没查依赖确认 readyz 是否检查数据库并返回 503
网关返回 502应用没监听、端口不对,或进程启动即退出看应用启动日志、监听地址和代理 upstream 配置
网关返回 504应用处理超过代理超时,或代理读超时太短对比应用耗时、代理超时和负载均衡超时
容器退出码 137超过内存限制被 OOM 杀掉,或收到 SIGKILL看容器内存曲线、GOMEMLIMIT 和 GC 指标
外部访问连接被拒绝只监听 127.0.0.1,或安全组未放行ss -lntp 看监听地址,从另一台机器测端口
定时任务在错误时间执行容器时区是 UTC,表达式按本地时间写打印进程时区,确认镜像里有 tzdata
启动后立刻退出配置缺失或校验失败,迁移未完成看启动日志第一条错误和退出码
日志平台收不到日志写进了容器内文件,没有输出到标准输出检查日志 handler 的目标和容器日志驱动

边界与代价

零停机不是 Shutdown 一个函数就能保证的。它需要就绪检查先失败、负载均衡停止转发、在途请求走完、代理支持重试,任何一环缺失都会有失败请求。应用能做的是把状态暴露准确、把排空时间留够;剩下的靠部署平台配合。承诺「绝对零停机」之前,先把这些环节逐一验证。

健康检查有成本。探针频率太高会给应用和数据库增加压力,频率太低会延迟故障发现;判定阈值太敏感会误摘实例,太宽松会留坏实例。把它当成一个需要调参的监控项,而不是配一个路径就结束。就绪检查尤其不要放重查询,它会被高频调用。

静态编译让部署简单,但不改变运行时的资源需求。二进制小不代表内存占用小,堆、goroutine、连接池、缓存仍然要按实际负载配置。容器限制和 GOMEMLIMIT 只是让运行时更早做决定,不能替代内存泄漏排查。

发布流程越自动,越要保留可回滚的版本和可观测的入口。新版本启动失败时,编排系统应该停止继续放量;旧版本要能继续服务。版本号、启动日志、健康检查、关键接口的冒烟请求,这四样东西是发布后五分钟内判断「这次成没成」的最低配置。

当天能自己验证的练习

  1. 用 CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -ldflags "-s -w -X main.version=1.2.3" 编译一个服务,在 Linux 或容器里执行 file 二进制,确认是静态链接,并记录体积。
  2. 启动服务后分别请求 /healthz 和 /readyz,记录状态码和响应体;如果把 readyz 里的数据库探活指向一个关闭的实例,观察它是否变成 503。
  3. 在 Linux 上给服务发 SIGTERM,同时请求一个故意慢 2 秒的接口,确认请求正常完成、日志出现停机顺序,而不是连接被重置。
  4. 设置一个较小的 GOMEMLIMIT,用压测工具持续分配内存,观察 GC 频率和容器内存曲线,记录进程是否被 137 杀掉。
  5. 给应用设置 1 秒的 WriteTimeout,让处理函数 sleep 2 秒,通过反向代理请求,观察客户端拿到的是超时、空响应还是 504,并对照代理配置。

小结

三句话:发布产物要静态、可复现、带版本,配置在启动时校验;healthz 管存活、readyz 管就绪,两者不能混用;收到停止信号先摘流量再 Shutdown,超时留得比编排系统短。

这一组六篇走完了从空目录到上线的链路:起服务、管路由、访问数据库、做鉴权、跑后台任务、安全发布。它们共同的前提是「请求有边界、失败可观察、状态可恢复」。下一步可以按自己的项目挑一个最薄弱的环节动手,比如先给现有服务补上 /readyz 和优雅停机,再回头看连接池和任务队列;能验证的改动,比读一遍文档更值。