CGO_ENABLED=0是Iris容器化部署的前提，否则Alpine镜像因musl libc与glibc不兼容而报“no such file or directory”；必须配合GOOS=linux、GOARCH=amd64静态编译，并采用多阶段Dockerfile精简镜像。
CGO_ENABLED=0 静态编译是 Docker 部署 Iris 的前提
Go 项目容器化最常踩的坑，就是没关 cgo 导致镜像内 libc 版本不兼容、启动报 standard_init_linux.go:228: exec user process caused: no such file or directory。Iris 本身不依赖 C 库，但默认启用 cgo 会链接宿主机的动态 libc，而 Alpine 镜像（常用轻量基础镜像）用的是 musl libc，完全不兼容。
必须在构建阶段禁用：CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o iris-app ./main.go
- 若你用的是 Alpine 基础镜像（如
golang:alpine或alpine:latest），CGO_ENABLED=0是强制要求 - 若坚持用
cgo（比如用了 SQLite 或自定义 DNS 解析），就得换gcr.io/distroless/static:nonroot或debian:slim，并确保目标 libc 版本一致 - Windows 或 macOS 本地构建时，必须显式指定
GOOS和GOARCH，否则生成的二进制无法在 Linux 容器中运行
Dockerfile 要精简，别套用通用 Go 模板
Iris 应用最终就一个可执行文件，不需要源码、go.mod、测试文件或开发工具链。多层 COPY 或保留 /go 目录只会让镜像变大、攻击面变宽。
推荐写法（多阶段构建）：
FROM golang:1.23-alpine AS builder WORKDIR /app COPY go.mod go.sum ./ RUN go mod download COPY . . RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -a -ldflags '-extldflags "-static"' -o iris-app ./main.go FROM alpine:latest RUN apk --no-cache add ca-certificates WORKDIR /root/ COPY --from=builder /app/iris-app . EXPOSE 8080 CMD ["./iris-app", "--port=8080"]
- 第一阶段用
golang:1.23-alpine编译，第二阶段用纯alpine:latest运行，镜像体积通常压到 15MB 以内 -
-a参数强制重新编译所有依赖，配合-ldflags '-extldflags "-static"'进一步加固静态链接 - 别在运行阶段装
curl、bash等调试工具——生产镜像应最小化；真要调试，临时docker run -it --rm your-image sh即可
端口与反向代理不能在容器里硬编码
Iris 启动时监听的端口（如 --port=8080）不该写死在 CMD 里，而应通过环境变量或命令行参数注入。否则每次改端口都要重打镜像。
修改 main.go 中的启动逻辑，例如：
port := os.Getenv("PORT")
if port == "" {
port = "8080"
}
app.Run(iris.Addr(":" + port))
- Docker 启动时用
docker run -e PORT=9000 -p 9000:9000 your-iris-app - Kubernetes 中可通过
env:字段注入，或挂载 ConfigMap - 务必用
EXPOSE声明端口（虽不强制，但利于文档和工具识别），且EXPOSE值应与默认PORT一致，避免混淆 - 生产环境仍建议前置 Nginx/Caddy：容器内 Iris 只处理业务逻辑，HTTPS 终止、静态文件、限流都交给反向代理
日志输出必须走 stdout/stderr
Docker 默认只捕获容器主进程的标准输出和标准错误。如果你在 Iris 里用了 log.Printf 或自定义文件写入，日志会丢失，docker logs 查不到任何内容。
Iris 默认日志已适配 stdout，但需确认未被覆盖：
- 禁用
iris.TCPKeepAlive以外的非标准日志配置（如写文件、发 HTTP） - 若用了第三方日志库（如
zerolog），确保初始化时设为zerolog.New(os.Stdout) - 避免在
app.UseRouter或中间件中调用fmt.Print*到文件句柄——它们不会被 Docker 捕获 - 健康检查路径（如
/healthz）返回状态码即可，不要混入 HTML 或长文本，干扰日志解析
真正麻烦的不是怎么写 Dockerfile，而是忘记容器没有“后台服务”概念——它只认一个 PID 1 进程。Iris 必须是那个进程，且不能 fork 出子进程再退出，否则容器立刻终止。
