必须用多阶段构建+非root用户+静态编译，因单阶段镜像超1GB、含冗余工具链、默认root运行且存在CGO兼容性风险；多阶段仅保留二进制、CA证书和配置，体积压至约12MB，并确保GOOS=linux、CGO_ENABLED=0和-ldflags="-w -s"。
为什么不能直接 go run main.go 构建镜像
开发时用 go run 很方便，但生产镜像里这么干等于埋雷：
– 镜像里要装完整 Go 工具链（golang:1.21-alpine 镜像本身就 300MB+）
– 运行时依赖 GOPATH、go.mod、源码路径，稍一错位就 exec: "go": executable file not found in $PATH
– 无法剥离调试符号，二进制体积大、启动慢、有安全风险
– 默认以 root 身份运行，违反最小权限原则
Dockerfile 必须用多阶段构建
多阶段构建不是“可选项”，而是生产环境的硬性要求。关键在于分离构建环境和运行环境：
- 第一阶段用
golang:1.21-alpine编译，启用CGO_ENABLED=0确保静态链接 - 第二阶段用
alpine:3.18（不含 Go），只拷贝编译好的二进制和必要配置 - 务必加
-ldflags="-w -s"：去掉调试信息和符号表，镜像体积能从 ~80MB 降到 ~12MB - 用
adduser -D -g '' appuser创建非 root 用户，并通过USER appuser切换身份
示例核心片段：
minimax-mcp-docker版（适配极空间）
下载
MiniMax 图片理解 + 网络搜索 MCP 工具。适配 Docker 环境（极空间等），支持图片 OCR 识别、图像内容理解、网络搜索。API Key 安全存储在本地 credentials 文件，不暴露在代码中。
FROM golang:1.21-alpine AS builder WORKDIR /app COPY go.mod go.sum ./ RUN go mod download COPY . . RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-w -s" -o /app/gin-app . FROM alpine:3.18 RUN apk --no-cache add ca-certificates tzdata WORKDIR /root COPY --from=builder /app/gin-app . COPY --from=builder /app/configs ./configs RUN adduser -D -g '' appuser && chown appuser /root USER appuser EXPOSE 8080 ENTRYPOINT ["./gin-app"]
配置文件不能硬编码进二进制，也不能塞进镜像层
把 config.yaml 直接 COPY 进镜像，会导致不同环境（dev/staging/prod）必须打多个镜像——违背“一次构建、随处运行”原则。
- 正确做法：镜像只含二进制和默认配置骨架，实际配置通过
volume挂载或Kubernetes ConfigMap注入 - 代码中用
viper.AutomaticEnv()+viper.SetEnvKeyReplacer(strings.NewReplacer(".", "_"))支持环境变量覆盖，例如SERVER_PORT=8081覆盖server.port - 避免在
Dockerfile中COPY configs/ ./configs—— 除非那是完全无敏感信息的公共模板
健康检查（liveness/readiness）必须显式实现
Gin 默认不暴露健康端点，K8s 的 livenessProbe 会因超时反复重启 Pod。别指望 tcpSocket 或 httpGet 对 / 就够用。
- 加一个专用路由，比如
GET /healthz，只返回200 OK，不做 DB 查询、不调外部服务 - 在
livenessProbe中用httpGet指向该路径，超时设为1s，失败阈值3 - 如果用了自定义中间件（如 JWT 鉴权），确保
/healthz跳过所有中间件，否则可能因 header 缺失 401 - 不要用
exec执行ps aux | grep gin-app类命令——容器里没ps，且逻辑不可靠
GOOS=linux 和运行时的用户权限映射。本地 macOS 编译再 COPY 进 Linux 容器，大概率 panic；而用 root 启动的进程一旦被提权，整个容器就失控。这两处不处理，其他优化都是补丁。 
