Docker 系列——Golang 项目容器化

前言

Golang 的静态编译特性使其天然适合容器化部署——编译出的二进制文件不需要任何运行时依赖，可以直接运行在最小化的容器镜像中。

这篇文章将介绍如何将 Golang 项目打包成 Docker 镜像，包括单阶段构建、多阶段构建、优化技巧等实战内容。

项目准备

假设我们有一个简单的 Go Web 服务：

myapp/
├── main.go
├── go.mod
├── go.sum
├── config/
│   └── config.go
├── handler/
│   └── handler.go
└── Dockerfile

main.go：

package main

import (
    "fmt"
    "log"
    "net/http"
    "os"
)

func main() {
    port := os.Getenv("PORT")
    if port == "" {
        port = "8080"
    }

    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        hostname, _ := os.Hostname()
        fmt.Fprintf(w, "Hello from %s!\n", hostname)
    })

    http.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
        w.WriteHeader(http.StatusOK)
        w.Write([]byte("ok"))
    })

    log.Printf("Server starting on port %s...\n", port)
    log.Fatal(http.ListenAndServe(":"+port, nil))
}

go.mod：

module myapp

go 1.21

方式一：单阶段构建

最简单的方式，直接在 Go 镜像中编译和运行：

FROM golang:1.21

WORKDIR /app

# 复制依赖文件
COPY go.mod go.sum ./
RUN go mod download

# 复制源码
COPY . .

# 编译
RUN go build -o main .

# 运行
EXPOSE 8080
CMD ["./main"]

构建和运行：

docker build -t myapp:v1 .
docker run -d -p 8080:8080 myapp:v1

问题：镜像体积过大（约 800MB+），包含了编译工具链和源码。

方式二：多阶段构建（推荐）

使用多阶段构建，最终镜像只包含编译好的二进制文件：

# ========== 构建阶段 ==========
FROM golang:1.21-alpine AS builder

WORKDIR /app

# 安装必要的构建工具（如果需要 CGO）
# RUN apk add --no-cache gcc musl-dev

# 复制依赖文件并下载
COPY go.mod go.sum ./
RUN go mod download

# 复制源码
COPY . .

# 编译（静态链接，禁用 CGO）
RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build \
    -ldflags="-w -s" \
    -o main .

# ========== 运行阶段 ==========
FROM alpine:3.19

WORKDIR /app

# 安装 CA 证书（HTTPS 请求需要）
RUN apk --no-cache add ca-certificates tzdata

# 设置时区
ENV TZ=Asia/Shanghai

# 从构建阶段复制二进制文件
COPY --from=builder /app/main .

# 创建非 root 用户（安全最佳实践）
RUN adduser -D -g '' appuser
USER appuser

EXPOSE 8080

CMD ["./main"]

构建和运行：

docker build -t myapp:v2 .
docker run -d -p 8080:8080 myapp:v2

镜像大小对比：

docker images myapp
# REPOSITORY   TAG   SIZE
# myapp        v1    812MB
# myapp        v2    15MB    ← 显著减小！

方式三：使用 scratch 镜像（最小化）

如果追求极致小的镜像，可以使用 scratch（空镜像）：

# ========== 构建阶段 ==========
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 GOARCH=amd64 go build \
    -ldflags="-w -s -extldflags '-static'" \
    -o main .

# ========== 运行阶段 ==========
FROM scratch

WORKDIR /app

# 复制 CA 证书（如果需要 HTTPS）
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/

# 复制时区信息（如果需要）
COPY --from=builder /usr/share/zoneinfo /usr/share/zoneinfo
ENV TZ=Asia/Shanghai

# 复制二进制文件
COPY --from=builder /app/main .

EXPOSE 8080

ENTRYPOINT ["./main"]

镜像大小：约 8-10MB

⚠️ 注意：scratch 镜像没有 shell，无法使用 docker exec 进入容器调试。

编译参数详解

CGO_ENABLED

CGO_ENABLED=0  # 禁用 CGO，纯 Go 编译，无 C 依赖
CGO_ENABLED=1  # 启用 CGO，可调用 C 库

大多数 Go 应用不需要 CGO，禁用后可以静态编译。

GOOS 和 GOARCH

GOOS=linux GOARCH=amd64    # Linux x86_64（最常见）
GOOS=linux GOARCH=arm64    # Linux ARM64（Apple Silicon、AWS Graviton）
GOOS=darwin GOARCH=amd64   # macOS x86_64
GOOS=darwin GOARCH=arm64   # macOS M1/M2
GOOS=windows GOARCH=amd64  # Windows x86_64

ldflags 优化

-ldflags="-w -s"
# -w 禁用 DWARF 调试信息
# -s 禁用符号表
# 可减少二进制文件 20-30% 大小

注入版本信息

ARG VERSION=dev
ARG COMMIT=unknown
ARG BUILD_TIME=unknown

RUN CGO_ENABLED=0 go build \
    -ldflags="-w -s \
        -X main.Version=${VERSION} \
        -X main.Commit=${COMMIT} \
        -X main.BuildTime=${BUILD_TIME}" \
    -o main .

在代码中读取：

var (
    Version   = "dev"
    Commit    = "unknown"
    BuildTime = "unknown"
)

func main() {
    log.Printf("Version: %s, Commit: %s, BuildTime: %s\n", 
        Version, Commit, BuildTime)
    // ...
}

构建时注入：

docker build \
    --build-arg VERSION=1.0.0 \
    --build-arg COMMIT=$(git rev-parse --short HEAD) \
    --build-arg BUILD_TIME=$(date -u +%Y-%m-%dT%H:%M:%SZ) \
    -t myapp:1.0.0 .

完整的生产级 Dockerfile

# ========== 构建阶段 ==========
FROM golang:1.21-alpine AS builder

# 构建参数
ARG VERSION=dev
ARG COMMIT=unknown
ARG BUILD_TIME=unknown

WORKDIR /app

# 安装 git（如果有私有依赖）
RUN apk add --no-cache git

# 复制依赖文件
COPY go.mod go.sum ./

# 下载依赖（利用 Docker 缓存）
RUN go mod download && go mod verify

# 复制源码
COPY . .

# 编译
RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build \
    -ldflags="-w -s \
        -X main.Version=${VERSION} \
        -X main.Commit=${COMMIT} \
        -X main.BuildTime=${BUILD_TIME}" \
    -trimpath \
    -o /app/main .

# ========== 运行阶段 ==========
FROM alpine:3.19

# 设置标签
LABEL maintainer="[email protected]"
LABEL version="${VERSION}"

WORKDIR /app

# 安装运行时依赖
RUN apk --no-cache add \
    ca-certificates \
    tzdata \
    && rm -rf /var/cache/apk/*

# 设置时区
ENV TZ=Asia/Shanghai

# 创建非 root 用户
RUN addgroup -g 1000 -S appgroup && \
    adduser -u 1000 -S appuser -G appgroup

# 复制二进制文件
COPY --from=builder /app/main .

# 复制配置文件（如果有）
# COPY --from=builder /app/config ./config

# 设置文件权限
RUN chown -R appuser:appgroup /app

# 切换到非 root 用户
USER appuser

# 暴露端口
EXPOSE 8080

# 健康检查
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
    CMD wget --no-verbose --tries=1 --spider http://localhost:8080/health || exit 1

# 启动命令
CMD ["./main"]

构建脚本

创建 build.sh 简化构建流程：

#!/bin/bash

# 配置
IMAGE_NAME="myapp"
REGISTRY="registry.example.com"

# 获取版本信息
VERSION=${1:-$(git describe --tags --always --dirty 2>/dev/null || echo "dev")}
COMMIT=$(git rev-parse --short HEAD 2>/dev/null || echo "unknown")
BUILD_TIME=$(date -u +%Y-%m-%dT%H:%M:%SZ)

echo "Building ${IMAGE_NAME}:${VERSION}"
echo "Commit: ${COMMIT}"
echo "Build Time: ${BUILD_TIME}"

# 构建镜像
docker build \
    --build-arg VERSION=${VERSION} \
    --build-arg COMMIT=${COMMIT} \
    --build-arg BUILD_TIME=${BUILD_TIME} \
    -t ${IMAGE_NAME}:${VERSION} \
    -t ${IMAGE_NAME}:latest \
    .

# 推送到仓库（可选）
if [ "$2" == "--push" ]; then
    docker tag ${IMAGE_NAME}:${VERSION} ${REGISTRY}/${IMAGE_NAME}:${VERSION}
    docker push ${REGISTRY}/${IMAGE_NAME}:${VERSION}
fi

echo "Done!"
docker images ${IMAGE_NAME}

使用：

chmod +x build.sh
./build.sh v1.0.0
./build.sh v1.0.0 --push  # 构建并推送

多架构构建

支持多平台（如同时支持 AMD64 和 ARM64）：

# 创建 buildx 构建器
docker buildx create --name mybuilder --use

# 构建多架构镜像并推送
docker buildx build \
    --platform linux/amd64,linux/arm64 \
    --build-arg VERSION=1.0.0 \
    -t registry.example.com/myapp:1.0.0 \
    --push \
    .

docker-compose 开发环境

创建 docker-compose.yml 用于本地开发：

version: '3.8'

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
      args:
        VERSION: dev
    ports:
      - "8080:8080"
    environment:
      - PORT=8080
      - DB_HOST=db
      - DB_PORT=5432
      - DB_NAME=myapp
      - DB_USER=postgres
      - DB_PASS=postgres
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped

  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: myapp
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

volumes:
  postgres_data:

使用：

# 启动所有服务
docker-compose up -d

# 查看日志
docker-compose logs -f app

# 停止并删除
docker-compose down

# 停止并删除数据卷
docker-compose down -v

开发环境热重载

使用 Air 实现开发时热重载：

docker-compose.dev.yml：

version: '3.8'

services:
  app:
    image: golang:1.21-alpine
    working_dir: /app
    command: |
      sh -c "go install github.com/cosmtrek/air@latest && air"
    ports:
      - "8080:8080"
    volumes:
      - .:/app
      - go_mod_cache:/go/pkg/mod
    environment:
      - PORT=8080

volumes:
  go_mod_cache:

.air.toml：

root = "."
tmp_dir = "tmp"

[build]
cmd = "go build -o ./tmp/main ."
bin = "./tmp/main"
include_ext = ["go", "tpl", "tmpl", "html"]
exclude_dir = ["tmp", "vendor"]
delay = 1000

[log]
time = false

[color]
main = "yellow"
watcher = "cyan"
build = "green"
runner = "magenta"

使用：

docker-compose -f docker-compose.dev.yml up

常见问题

Q1: 编译报错 “standard_init_linux.go: exec format error”

原因：编译的目标平台与运行平台不匹配。

解决：

# 明确指定目标平台
RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o main .

Q2: 容器内时间不对

解决：安装 tzdata 并设置时区

RUN apk --no-cache add tzdata
ENV TZ=Asia/Shanghai

Q3: HTTPS 请求报错 “x509: certificate signed by unknown authority”

原因：容器内没有 CA 证书。

解决：

RUN apk --no-cache add ca-certificates

Q4: 私有仓库依赖下载失败

解决：配置 Git 和私钥

RUN apk add --no-cache git openssh-client
RUN git config --global url."[email protected]:".insteadOf "https://github.com/"

# 复制私钥（注意安全）
COPY --chown=root:root id_rsa /root/.ssh/id_rsa
RUN chmod 600 /root/.ssh/id_rsa

或使用 --mount=type=ssh：

RUN --mount=type=ssh go mod download

下一步

下一篇文章将介绍如何使用 Docker 快速启动测试数据库（PostgreSQL、MySQL），帮助你在本地开发和测试时快速搭建数据库环境。

参考资料

（采用 CC BY-NC-SA 4.0 许可协议进行授权）

本文标题：《 Docker 系列——Golang 项目容器化》

本文链接：http://localhost:3015/ai/Docker-Golang%E5%AE%B9%E5%99%A8%E5%8C%96.html

本文最后一次更新为天前，文章中的某些内容可能已过时！