关键在于服务依赖顺序、配置注入及二进制构建：必须用多阶段构建+cgo_enabled=0静态编译，gin需显式监听0.0.0.0:8080，docker-compose中通过healthcheck和service_healthy控制启动顺序，并设gin_mode=release确保生产安全。
docker-compose 部署 Gin 应用不是“配好 yaml 就能跑”，关键在于服务间依赖顺序、配置注入方式、以及二进制文件如何进入容器——直接 COPY 本地编译产物最稳，但必须确保 GOOS=linux 和静态链接。
确认 Gin 服务是否暴露了正确端口且不阻塞
很多部署失败是因为 Gin 启动后没监听 0.0.0.0:8080，而是默认只绑 127.0.0.1:8080（开发模式常见）。启动代码里必须显式写：
router.Run("0.0.0.0:8080")
否则容器内其他服务（如 Nginx 或前端）根本连不上。另外，router.Run() 是阻塞调用，别跟在它后面写日志或 defer，否则那些代码永远不会执行。
Dockerfile 必须用多阶段构建 + 静态编译
Go 编译出的二进制默认动态链接 libc，而 Alpine 镜像没这玩意儿，一运行就报 standard_init_linux.go:228: exec user process caused: no such file or directory。解决方法：
- 第一阶段用
golang:1.21-alpine编译，加CGO_ENABLED=0 - 第二阶段用
alpine:latest，只 COPY 二进制，不带 Go 环境 - ENTRYPOINT 设为绝对路径，比如
["/app/server"]，不是["./server"]
示例关键片段：
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 -a -installsuffix cgo -o server . <p>FROM alpine:latest RUN apk --no-cache add ca-certificates WORKDIR /root/ COPY --from=builder /app/server . CMD ["/root/server"]</p>
docker-compose.yml 要控制启动顺序和配置注入
depends_on 默认只等容器创建，不等服务就绪，所以 MySQL 或 Redis 常出现 “connection refused”。必须配合健康检查 + restart_policy：
- 给
mysql加healthcheck，用mysqladmin ping检查 - 给
server加restart: on-failure，避免因依赖未就绪直接退出 - 用
environment或env_file注入配置，不要硬编码数据库地址为localhost—— 容器内应是服务名，如mysql:3306
典型片段：
server:
build: ./server
ports: ["8080:8080"]
environment:
- DB_HOST=mysql
- DB_PORT=3306
- REDIS_ADDR=redis:6379
depends_on:
mysql:
condition: service_healthy
redis:
condition: service_healthy
restart: on-failure
前端与 Gin 同容器 or 分离？取决于部署模式
如果前端是 Vue/Vite 构建的静态资源，有两种主流做法：
-
前后端分离部署：前端用 Nginx 容器，反向代理
/api到server容器（注意跨域已在 Gin 中处理，Nginx 不再需要额外 header） -
前后端合并部署：把
dist/COPY 进 Gin 容器，用router.StaticFS("/static", http.Dir("./dist"))和router.NoRoute()返回index.html—— 这种方式省掉 Nginx，但更新前端要重打后端镜像
选哪种，取决于 CI/CD 流程是否允许前端独立发布。多数团队后期都会切到分离模式，因为 nginx 容器可以复用、缓存策略更灵活、SSL 终止也更标准。
最容易被忽略的是：Gin 的 mode 默认是 debug，日志会打印完整堆栈和文件路径，暴露源码结构；上线前务必通过环境变量设 GIN_MODE=release，否则等于把调试接口直接暴露在公网。
