健康检查接口应放在独立的HealthController中，新建controllers/health.go文件，定义嵌入beego.Controller的结构体，仅实现Get()方法，并在router.go中显式注册/health路由，避免混入业务控制器或被中间件拦截。
健康检查接口该放在哪个控制器里
Beego 默认不内置健康检查路由，得自己加。别塞进业务控制器里——比如 UserController 或 OrderController，这会让职责混乱，也影响部署时的探针隔离。推荐新建一个独立的 HealthController，专管 /health、/healthz 这类路径。
实操建议：
- 在
controllers/下新建health.go，定义HealthController，只保留Get()方法 - 在
router/router.go中显式注册：beego.Router("/health", &controllers.HealthController{}, "get:Get") - 避免用
NSCond或嵌套路由包装它，Kubernetes livenessProbe 通常只认 200 状态码和纯文本响应
返回什么内容才算真正“健康”
只返回 {"status": "up"} 是假健康。真实场景下，健康检查必须验证关键依赖是否就绪：数据库连通性、Redis 是否可写、必要配置项是否存在。Beego 的 orm 和 cache 模块都支持同步探测，但要注意超时控制。
常见错误现象：服务启动后立即返回 200，但 MySQL 还没完成初始化，K8s 把流量导过来导致报错。
实操建议：
- 在
HealthController.Get()里调用orm.NewOrm().Raw("SELECT 1").Exec()，并设context.WithTimeout(ctx, 2*time.Second) - 缓存层用
cache.GetCache("redis").IsConnected()（需提前在conf/app.conf配好 redis 名称） - 不要在健康检查里做耗时操作，比如读大文件、调外部 HTTP 接口；失败时直接
this.Abort("503")，别吞异常
如何让健康检查绕过 Beego 的中间件链
默认情况下，所有路由都会经过你注册的 InsertFilter，比如 JWT 鉴权、日志记录、跨域头注入。但 /health 不该被鉴权拦截，也不该被慢日志打点拖慢——否则探针超时，K8s 会反复重启容器。
Beego 没有“排除中间件”的语法糖，得靠路由匹配顺序或条件跳过。
实操建议：
- 把健康路由注册放在所有
InsertFilter调用之前（即main.go中beego.Router()写在beego.InsertFilter()上方） - 或者在鉴权中间件里加白名单判断：
if strings.HasPrefix(this.Ctx.Input.URL, "/health") { return } - 确认
beego.BConfig.WebConfig.DisableStatic = true不影响它——静态文件中间件默认不干扰 API 路由
为什么 /health 返回 404 或 panic
最常踩的坑是：写了控制器、注册了路由，但 HealthController 没继承 beego.Controller，或 Get() 方法签名不对（比如漏了 func (c *HealthController) Get() 中的指针接收者），Beego 在反射时找不到合法方法，就 fallback 到 404 或 panic。
另一个隐蔽问题是：Beego 启动时未加载该控制器包。Go 的包导入机制不会自动扫描子目录，controllers/health.go 必须被某个已导入的包显式引用。
实操建议：
- 检查
HealthController结构体是否嵌入beego.Controller：type HealthController struct { beego.Controller } - 确保
func (c *HealthController) Get()方法存在且首字母大写 - 在
main.go顶部加一行_ "your-app/controllers"（如果 health.go 在 controllers 目录下但没被其他文件 import） - 启动时加
beego.BeeLogger.Level = logs.LevelDebug，看日志里有没有skip controller或no method found提示
健康检查不是摆设，它得在数据库挂掉、配置热更新失败、甚至磁盘写满时准确暴露问题——而这些，全取决于你是否在 Get() 里真正去试了那几行连接代码。
