Gin服务部署核心卡点是配置隔离、进程守护和反向代理三层；需用os.Getenv+Viper分离dev/prod配置，Docker中禁用gin.Default()改用gin.New()，Nginx必须配置Host、X-Real-IP和proxy_buffering off。
直接上结论：Gin服务部署不是“编译完扔到服务器就完事”，核心卡点在配置隔离、进程守护和反向代理三层。漏掉任意一层，上线后大概率会遇到环境错乱、服务闪退或 502 错误。
如何用环境变量隔离 dev / prod 配置
硬编码配置（比如 dbHost := "localhost"）在生产环境必然出问题。必须把配置从代码中抽离，靠运行时注入。
推荐组合：os.Getenv + viper 加载 YAML 文件，再被命令行 flag 覆盖：
-
viper.SetConfigName(fmt.Sprintf("config.%s", os.Getenv("GIN_ENV")))自动加载config.prod.yaml或config.dev.yaml - 所有敏感字段（如
DB_PASSWORD）只通过环境变量传入，不写进配置文件 - 启动时加
-env=prod参数，避免依赖 shell 环境变量，更可控
常见错误：viper 没调 viper.AutomaticEnv()，导致 os.Getenv("PORT") 生效但 viper.GetString("server.port") 读不到；或者 YAML 中写了 port: ${PORT} 却没开 viper.SetEnvPrefix，变量替换失败。
Docker 镜像里为什么不能用 gin.Default() 启动
gin.Default() 默认开启 Logger 和 Recovery 中间件，适合开发调试，但在容器里会干扰日志采集和健康检查。
生产镜像应显式构造引擎：
r := gin.New() r.Use(gin.Recovery()) // 保留 panic 捕获 // 移除 Logger，改用 zap 或 stdout 格式化输出，方便 Docker 日志驱动收集
关键点：
- 关闭
gin.Logger()，否则每条请求打两遍日志（Docker 日志 + Gin 自己的 log） - 确保
r.Run()绑定的是:8080这类端口，不是0.0.0.0:8080—— 容器内网绑定无需指定 IP - Dockerfile 中用
EXPOSE 8080声明端口，但不要依赖它做实际暴露，靠docker run -p控制
Nginx 反向代理配置最容易漏的三项
Gin 是纯 HTTP 服务，没有静态文件托管和 TLS 终止能力，必须靠 Nginx 补足。以下三项不配齐，用户访问会直接报错：
-
proxy_set_header Host $host;—— 不设这个，Gin 的c.Request.Host会变成上游地址（如127.0.0.1:8080），影响生成绝对 URL 或 JWT issuer 校验 -
proxy_set_header X-Real-IP $remote_addr;和proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;—— 缺失会导致所有客户端 IP 变成127.0.0.1，限流、日志、风控全失效 -
proxy_buffering off;—— 如果 Gin 接口有流式响应（如 SSE 或大文件下载），不关缓冲会卡住首字节，用户长时间白屏
别信“默认配置够用”。Nginx 默认不透传头信息，也不处理连接复用，这些都得手写补全。
健康检查接口为什么不能只返回 200 OK
写个 GET /health 返回 {"status":"ok"} 是入门做法，但 K8s 或 Consul 的探针会因这三点失败：
- 没检查依赖组件：数据库连不上、Redis 超时、下游 HTTP 服务不可达，
/health却仍返回 200 - 没设超时：依赖检查耗时 3s，而 K8s
timeoutSeconds默认是 1s，直接判定探针失败 - 没区分就绪与存活：K8s 要求
livenessProbe和readinessProbe分开实现，一个管“要不要重启”，一个管“能不能收流量”
最简健壮写法：在 handler 里用 context.WithTimeout 包裹所有依赖检查，任一失败就返回 503，且整个 handler 执行控制在 500ms 内。
