使用Dockerfile构建Go程序运行的镜像，实现在容器环境稳定运行Gin

为什么容器化部署Gin

Gin作为Go语言生态的轻量级Web框架，其程序部署时选择“打包成镜像再上线”的核心原因，是为了解决环境一致性、部署标准化、资源隔离三大核心问题，同时提升部署效率、降低运维成本。

而镜像（如Docker镜像）本质是“程序+运行环境”的打包集合——打包时会将Gin程序的二进制文件、依赖库、配置模板、系统基础镜像（如Alpine、Ubuntu）等所有运行必需的组件封装在一起。部署时，线上服务器只需运行镜像，即可直接复用打包好的一致环境，从根源上消除“环境差异”导致的部署故障。

如何构建容器镜像

Gin-demo的Dockerfile核心配置

Dockerfile主要内容分为以下2部分：采用多阶段构建（Multi-stage build）减小镜像体积
第一阶段使用 golang:1.25 镜像编译 Go 程序，生成 gin-demo 可执行文件
第二阶段使用轻量级 alpine:latest 镜像运行编译后的二进制文件

# ============================================
# 第一阶段：构建阶段 (Builder Stage)
# ============================================
# 使用 Go 1.25 官方镜像作为构建环境
# AS builder: 将此阶段命名为 builder，方便后续引用
FROM docker.1ms.run/golang:1.25 AS builder

# 设置工作目录为 /build
# 后续的命令都会在此目录下执行
WORKDIR /build

# ============================================
# 设置 Go 编译环境变量
# ============================================
# GO111MODULE=on: 启用 Go Modules 依赖管理
# GOPROXY: 使用国内 Go 代理加速依赖下载，direct 表示失败时直接访问源
# CGO_ENABLED=0: 禁用 CGO，生成纯静态可执行文件（不依赖系统动态库）
# GOOS=linux: 目标操作系统为 Linux
# GOARCH=amd64: 目标架构为 64 位 x86
ENV GO111MODULE=on \
    GOPROXY=https://goproxy.cn,direct \
    CGO_ENABLED=0 \
    GOOS=linux \
    GOARCH=amd64

# ============================================
# 复制依赖文件（利用 Docker 缓存层机制）
# ============================================
# 先复制 go.mod 和 go.sum，如果依赖未变化，Docker 会使用缓存
# 这样可以避免每次修改源代码都重新下载依赖，加快构建速度
COPY go.mod go.sum ./

# ============================================
# 下载 Go 项目依赖
# ============================================
# 将依赖下载到 Go Module 缓存中
RUN go mod download

# ============================================
# 复制项目源代码
# ============================================
# 复制整个项目目录到工作目录
# 注意：这会触发 Docker 缓存失效，后续命令都会重新执行
COPY . .

# ============================================
# 编译 Go 程序
# ============================================
# -ldflags="-s -w":
#   -s: 去除符号表（symbol table）
#   -w: 去除调试信息（DWARF debug info）
#   这两个选项可以显著减小可执行文件体积（通常减少 30-50%）
# -o gin-demo: 指定输出文件名为 gin-demo
# main.go: 入口文件
RUN go build -ldflags="-s -w" -o gin-demo main.go

# ============================================
# 第二阶段：cho "Asia/Shanghai" > /etc/timezone

# ============================================
# 设置运行时工作目录
# ============================================
# 程序将在 /service 目录下运行
WORKDIR /service

# ============================================
# 从构建阶段复制可执行文件
# ============================================
# --from=builder: 从名为 builder 的构建阶段复制文件
# /build/gin-demo: 源文件路径（构建阶段的输出）
# /service/gin-demo: 目标文件路径（运行阶段的工作目录）
# 只复制最终的可执行文件，不包含源代码和构建工具
COPY --from=builder /build/gin-demo /service/gin-demo

# ============================================
# 设置环境变量
# ============================================
# 设置默认端口为 8992
# 程序可以通过读取此环境变量来决定监听哪个端口
ENV PORT=8992

# ============================================
# 声明容器监听的端口
# ============================================
# EXPOSE 只是文档说明，告诉用户容器会监听 8992 端口
# 实际的端口映射需要在运行容器时通过 -p 参数指定
# 例如: docker run -p 8992:8992 gin-demo
EXPOSE 8992

# ============================================
# 容器启动时执行的命令
# ============================================
# CMD 指定了容器启动后要运行的命令
# ["./gin-demo"]: 使用 JSON 数组格式，这是推荐的方式
# 相比于字符串格式，JSON 数组格式不会通过 shell 解析，更安全
CMD ["./gin-demo"]
运行阶段 (Runtime Stage)
# ============================================
# 使用 Alpine Linux 作为运行环境
# Alpine 是一个轻量级 Linux 发行版，镜像体积仅约 5MB
# 不包含 Go 编译器和源代码，只包含运行时必需的文件
FROM docker.1ms.run/alpine:latest

# ============================================
# 设置系统时区为上海时间 (UTC+8)
# ============================================
# ln -sf: 创建符号链接，-f 表示强制覆盖已存在的文件
# 将 /etc/localtime 链接到上海的时区文件
# echo: 将时区信息写入 /etc/timezone 文件
RUN ln -sf /usr/share/zoneinfo/Asia/Shanghai /etc/localtime && \
    e

Docker-Compose配置文件

---
# This docker compose file is used for developer to setup
# dev enironment quickly. Only local machine with
# docker and docker-compose is required.
version: "3.3"
services:
  gin_demo:
    image: "gin-demo:latest"
    build:
      context: ./
      dockerfile: Dockerfile
    env_file:
      - .env
    ports:
      - "8992:8992"
    hostname: gin-demo.local
    command: ./gin-demo
    networks:
      - platform-common-net
networks:
  platform-common-net:
    # 声明这个网络是外部定义的
    external: true

Build镜像

中间镜像构建过程的内容已经省略，最终会得到gin-demo:latest

ctyun@00gcbjih-0OqRgn1nUE:/media/vdb/code/gin-demo$ docker-compose build 
[+] Building 974.6s (16/16) FINISHED                                                                                                                                
 => [gin_demo internal] load build definition from Dockerfile                                                                                                    0.0s
 => => transferring dockerfile: 940B                                                                                                                             0.0s
 256:c99f77b3fe9114fe940a17366b6f4afbfce09e8ebf78f598d37eb0fde1953845                                                                     0.0s
 => => naming to docker.io/library/gin-demo:latest                                                                                                               0.0s

Image产物

在经过2阶段镜像编译执行，最终gin-demo的镜像只有不到30MB，相当完美。

ctyun@00gcbjih-0OqRgn1nUE:~$ docker image ls|grep gin-demo
gin-demo                                                       latest                               c99f77b3fe91   10 hours ago    28.5MB

部署容器和测试验证

启用gin-demo

ctyun@00gcbjih-0OqRgn1nUE:~$ docker ps
CONTAINER ID   IMAGE                                                           COMMAND                   CREATED          STATUS                  PORTS                                                                                                                           NAMES
1db96312ae8d   gin-demo:latest                                                 "./gin-demo"              11 seconds ago   Up 10 seconds           0.0.0.0:8992->8992/tcp, [::]:8992->8992/tcp                                                                                     gin-demo-gin_demo-1

测试验证程序

使用Curl命令验证我们启动的gin-demo容器，发现API是正常的，说明程序服务也是OK的。

ctyun@00gcbjih-0OqRgn1nUE:~$ curl http://localhost:8992/api/health
{"message":"服务健康","status":"ok"}ctyun@00gcbjih-0OqRgn1nUE:~$ 
ctyun@00gcbjih-0OqRgn1nUE:~$ 
ctyun@00gcbjih-0OqRgn1nUE:~$ curl http://localhost:8992/
{"message":"Gin应用运行成功！","port":8992,"status":"running"}

谢谢关注收藏

⏰ 刚刷到的朋友注意啦！
点击【关注】锁定宝藏库，从此升职加薪不迷路 ✨

我的博客网站：

我的技术博客：Tesla，https://funkygod.vip/

我的投资博客：MakeMoney，https://blog-demo-559.pages.dev/

我的微信公众号

轻量云主机限时优惠

RackNerd

☁ 主机显示特惠：只要80元（3TB流量，1vcpu，50GB硬盘）
购买地址：https://my.racknerd.com/aff.php?aff=14942

CloudCone

CloudCone 特惠轻量云主机：购买地址：https://app.cloudcone.com/?ref=12332

📢 腾讯云资源限时福利

有云服务器、CDN、对象存储、网络防护等需求的朋友，欢迎联系下方腾讯云官方销售 👇
✔️ 内部专属折扣，价格更优 ✔️ 量大可谈，支持定制方案 ✔️ 技术咨询与售后无忧

智谱Ai GLM Coding 超值订阅

🚀 速来拼好模，智谱 GLM Coding 超值订阅，邀你一起薅羊毛！Claude Code、Cline 等 20+ 大编程工具无缝支持，“码力”全开，越拼越爽！立即开拼，享限时惊喜价！ 链接：https://www.bigmodel.cn/glm-coding?ic=RTWWS8HOD6
活动截止时间：2026年1月15日