滚动发布时,新实例刚起来,旧实例收到编排系统发来的 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 是就绪检查:这个实例现在能接业务流量吗;失败时从负载均衡里摘掉,但不重启。把两者合成一个,就会在数据库短暂抖动时重启所有实例,把小故障放大成雪崩。
就绪检查里的数据库探活要用独立的短超时,几秒即可,不要复用业务查询。探活频率高,每次都跑复杂 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,等待正在处理的请求完成,再关闭数据库连接池和后台任务。
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 只是让运行时更早做决定,不能替代内存泄漏排查。
发布流程越自动,越要保留可回滚的版本和可观测的入口。新版本启动失败时,编排系统应该停止继续放量;旧版本要能继续服务。版本号、启动日志、健康检查、关键接口的冒烟请求,这四样东西是发布后五分钟内判断「这次成没成」的最低配置。
当天能自己验证的练习
- 用
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -ldflags "-s -w -X main.version=1.2.3"编译一个服务,在 Linux 或容器里执行file 二进制,确认是静态链接,并记录体积。 - 启动服务后分别请求
/healthz和/readyz,记录状态码和响应体;如果把readyz里的数据库探活指向一个关闭的实例,观察它是否变成 503。 - 在 Linux 上给服务发
SIGTERM,同时请求一个故意慢 2 秒的接口,确认请求正常完成、日志出现停机顺序,而不是连接被重置。 - 设置一个较小的
GOMEMLIMIT,用压测工具持续分配内存,观察 GC 频率和容器内存曲线,记录进程是否被 137 杀掉。 - 给应用设置 1 秒的
WriteTimeout,让处理函数 sleep 2 秒,通过反向代理请求,观察客户端拿到的是超时、空响应还是 504,并对照代理配置。
小结
三句话:发布产物要静态、可复现、带版本,配置在启动时校验;healthz 管存活、readyz 管就绪,两者不能混用;收到停止信号先摘流量再 Shutdown,超时留得比编排系统短。
这一组六篇走完了从空目录到上线的链路:起服务、管路由、访问数据库、做鉴权、跑后台任务、安全发布。它们共同的前提是「请求有边界、失败可观察、状态可恢复」。下一步可以按自己的项目挑一个最薄弱的环节动手,比如先给现有服务补上 /readyz 和优雅停机,再回头看连接池和任务队列;能验证的改动,比读一遍文档更值。