Beego健康检查需手动注册且版本差异大：v2用app.AddHealthCheck("/healthcheck", checker)，v1无此接口；checker须超时控制、避免阻塞，响应体严禁泄露敏感信息。
Beego 的健康检查端点默认不启用，需手动注册
Beego 框架本身不自动暴露 /healthcheck 或类似路径，必须显式调用 app.AddHealthCheck 才能启用。否则访问 http://localhost:8088/healthcheck 会直接返回 404。
常见错误现象：启动服务后 curl /healthcheck 得到 404，或日志里完全没看到健康检查相关路由注册记录。
- 确保在
main.go中、app.Run()之前调用app.AddHealthCheck("/healthcheck", healthChecker) -
healthChecker是一个符合func() error签名的函数，返回nil表示健康，非nil错误表示不健康 - Beego v2 推荐使用
server/web子包下的app.AddHealthCheck；v1 版本路径不同，容易导入错包
自定义探针要避免阻塞主线程和超时拖垮整个健康检查
Beego 的健康检查是同步执行的，如果某个 healthChecker 函数里做了数据库连接、HTTP 调用或无超时的 I/O，会导致所有健康请求 hang 住，进而让 Kubernetes readiness probe 失败、反复重启 Pod。
典型场景：你写了检查 Redis 连接的探针，但没设超时，Redis 临时不可达时整个 /healthcheck 响应卡死 30 秒。
- 所有外部依赖检查必须加 context 超时，例如用
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second) - 不要在
healthChecker里启动 goroutine 后直接返回 —— Beego 不等异步结果，会立刻判定为健康 - 若需异步状态缓存（如定时刷新 DB 连接池健康快照），应另起 goroutine 维护全局变量，
healthChecker只读该变量并快速返回
Beego v1 和 v2 的健康检查 API 不兼容，混用会编译失败
Beego v1（github.com/astaxie/beego）根本没有内置健康检查注册机制，所谓“/healthcheck”是用户自己手写 controller 实现的；而 v2（github.com/beego/beego/v2）才提供 app.AddHealthCheck 标准接口。
常见错误现象：undefined: app.AddHealthCheck，或 go mod tidy 报错找不到符号，本质是 import 路径和实际版本不匹配。
- 确认
go.mod里引用的是github.com/beego/beego/v2 v2.x.x，不是 v1 路径 - v1 项目升级到 v2 时，不能只改 import，还要重写健康检查逻辑 —— v1 没有统一入口，得自己在 controller 里做状态聚合
- 如果项目同时依赖 v1 和 v2 模块（极少见），必须用
replace显式隔离，否则构建失败
生产环境别把敏感信息直接塞进健康响应体
Beego 默认的健康检查响应只有 {"status":"ok"} 或错误文本，但很多人会顺手加 withDetail("db_url", cfg.DBURL) 之类逻辑，导致数据库地址、账号等泄露到监控平台或前端调试工具中。
更隐蔽的风险：某些公司安全扫描工具会主动 GET 所有 /health* 路径并存档响应内容。
- 健康响应里只放必要指标：连接池活跃数、缓存命中率、配置加载时间戳等脱敏后数值
- 绝对不要放原始配置项、密码、token、内网 IP、服务发现地址等
- 若需诊断用详细字段，建议通过独立的管理端点（如
/admin/debug/health）且加鉴权，而非公开的/healthcheck
