gin框架中健康检查端点必须手动注册，如router.get("/health", func(c *gin.context) { c.string(200, "ok") })，且需监听0.0.0.0:8080、禁用干扰日志、避免依赖下游服务，ansible应通过http探针而非端口检测判断就绪。
健康检查端点必须暴露在 Gin 路由中
Gin 默认不提供内置健康检查路由，/health 或 /healthz 需手动注册。如果 Ansible 部署后反复失败，第一反应应是检查该端点是否存在、是否返回 200，而非直接排查网络或服务状态。
常见错误现象：Ansible 的 wait_for 模块超时，但 curl http://localhost:8080/health 在容器内能通——说明端点没暴露，或监听地址不对。
- 确保使用
router.GET("/health", func(c *gin.Context) { c.String(200, "OK") })显式注册 - 避免仅在 dev 环境启用，生产构建中该路由必须保留（不要用
if os.Getenv("ENV") == "dev"包裹） - 监听地址必须为
0.0.0.0:8080，而非127.0.0.1:8080，否则容器外无法访问
Ansible 的 wait_for 必须匹配 Gin 启动节奏
Gin 启动是同步阻塞的，router.Run(":8080") 之后代码不再执行。这意味着 Ansible 不能依赖“进程存在”作为就绪信号，而必须靠 HTTP 探针。
典型误用：wait_for: port=8080 —— 这只检测端口开放，Gin 可能刚 bind 完、还没 ready 处理请求。
- 改用
wait_for: url=http://127.0.0.1:8080/health timeout=30 - 加上
sleep: 2在启动命令后、探针前，给 Gin 初始化留出缓冲（尤其加载配置或连接 DB 时） - 若使用 systemd 管理服务，确保
Type=simple（非forking），否则 Ansible 可能误判进程状态
部署时需绕过 Gin 的默认日志干扰
Gin 的 gin.DefaultWriter 默认输出到 stdout，Ansible 的 shell 模块会捕获全部输出。一旦健康检查失败，你看到的可能是大段 Gin 日志，而非真实错误原因。
容易踩的坑：把 curl -f http://.../health 放进 shell 任务里，却因 Gin 日志混入导致 failed_when 判断失效。
- 启动 Gin 时禁用控制台日志：
gin.SetMode(gin.ReleaseMode) - 或重定向日志：
gin.DefaultWriter = io.Discard（仅保留健康检查逻辑所需的 minimal 输出） - Ansible 中明确用
ignore_errors: yes+register: health_check_result，再用assert检查health_check_result.stdout == "OK"
健康检查逻辑不能依赖未就绪的下游服务
很多团队把数据库连通性、Redis ping、外部 API 可达性全塞进 /health，结果 Ansible 部署卡死——不是 Gin 没起来，而是它等不到 MySQL 容器启动完毕。
真正该放在这里的，只有 Gin 自身状态：监听正常、路由注册完成、无 panic 崩溃。
- 基础版足够：
c.Status(200)+ 空响应体，不调任何外部依赖 - 若需依赖检查，拆出
/health/ready（带依赖）和/health/live（仅进程存活），Ansible 只轮询后者 - 注意：Ansible 的
wait_for不支持 HTTP status code 分辨，所以/health/live必须返回 200，哪怕 DB 挂了
