本地Echo服务Docker中报exec format error或panic，主因是CGO_ENABLED=0和GOOS=linux未显式设置，导致二进制动态链接宿主机libc，与Alpine/musl或scratch镜像不兼容；必须静态编译并正确配置多阶段构建、健康探针与信号处理。
本地能跑的 Echo 服务，一进 Docker 就 exec format error 或直接 panic，八成是编译参数和镜像没对齐——不是框架问题，是构建链路断在了 CGO 和系统 ABI 上。
CGO_ENABLED=0 和 GOOS=linux 必须显式设置
Go 默认构建会链接宿主机 libc（比如 macOS 的 dylib 或 Ubuntu 的 glibc），但 Alpine 镜像用的是 musl libc；scratch 镜像干脆没 libc。Echo 本身不依赖 cgo，但不关它，go build 就可能产出动态链接二进制。
-
CGO_ENABLED=0强制生成纯静态可执行文件，彻底避开 libc 适配问题 -
GOOS=linux确保跨平台构建正确（你在 macOS 或 Windows 上写代码，容器跑在 Linux 内核） - 漏掉任一个，
docker run可能报exec format error、no such file or directory（其实是找不到动态链接器） - 别信“alpine 自带 go build”，builder 阶段必须显式加这两个环境变量：
RUN CGO_ENABLED=0 GOOS=linux go build -o main .
Dockerfile 多阶段构建要分清 builder 和 runner
常见错误是把 go.mod、源码、go build 全塞在一个 stage 里，导致每次改一行代码都重下全部依赖，构建慢还破坏层缓存。
- builder 阶段先
COPY go.mod go.sum .，再RUN go mod download—— 这层能被复用 - 再
COPY . .，然后RUN CGO_ENABLED=0 GOOS=linux go build -o main . - runner 阶段用
FROM alpine:latest，必须RUN apk --no-cache add ca-certificates，否则调 HTTPS 第三方 API 会卡在x509: certificate signed by unknown authority - 别用
FROM scratch除非你真确认没任何外部依赖（比如日志打到 syslog、或用了某些 syscall）
/health 端点不能查 DB，liveness 和 readiness 要分开
很多人把健康检查写成 e.GET("/health", func(c echo.Context) error { return db.Ping() })，结果 DB 延迟一抖，K8s 就反复重启容器。
立即学习“go语言免费学习笔记（深入）”；
-
/health应只检查服务监听状态 + 内存基础指标（如runtime.ReadMemStats），响应时间控制在 100ms 内 - 真要验 DB 连通性，单独开个
/readyz，并在 Kubernetes 中配readinessProbe指向它 - Dockerfile 里
HEALTHCHECK要设超时：HEALTHCHECK --interval=10s --timeout=3s --start-period=30s --retries=3 CMD curl -f http://localhost:8080/health || exit 1 - Echo 启动时记得绑定
:8080，别写死127.0.0.1:8080，否则curl在容器内连不上
日志和信号处理别依赖框架默认行为
Echo 的 middleware.Logger() 默认写到 os.Stderr，这没问题；但很多人忽略 SIGTERM 处理，容器 docker stop 时直接 kill -9，连接没 graceful shutdown。
- 启动前加
signal.Notify捕获os.Interrupt和syscall.SIGTERM - 停服用
e.Shutdown()，给 HTTP 连接留几秒缓冲：ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second); defer cancel(); e.Shutdown(ctx) - 别在中间件里做耗时操作（比如每次请求都读配置文件），Echo 的
echo.Context是复用的，但底层 buffer 不一定清空干净 - 环境变量用
os.Getenv("PORT")读取，别硬编码:8080，K8s Service 或 Docker Compose 都靠这个注入端口
最常被跳过的其实是 ca-certificates 和 CGO_ENABLED=0 的组合——它们不出错时不显眼，一出就是连不上外网或容器起不来，而且错误信息极其模糊。构建镜像前，先 docker run --rm -it <your-image> ./main 手动跑一下二进制，比等 CI 报错快得多。
