Go 项目用 docker init 生成容器配置后哪些默认值必须改

Go 项目执行 docker init 后，最容易犯的错误是把生成文件当成最终配置直接提交。它更像一份能跑起来的起点：Docker 会根据项目猜测 Go 版本、主程序目录和端口，但这些默认值并不了解你的发布环境、CGO 依赖和秘密管理方式。

官方地址：https://docs.docker.com/reference/cli/docker/init/

实用做法是先保留生成效率，再逐项审查版本、入口、端口、运行时用户和构建上下文。只有这些边界与项目事实一致，生成的 Dockerfile 和 Compose 配置才适合继续维护。

先把生成文件当作待审清单

Docker 官方文档当前说明，docker init 会在项目目录交互式生成 .dockerignore、Dockerfile、compose.yaml 和 README.Docker.md。如果目标文件已存在，命令会提示覆盖；因此第一步不是再次执行生成，而是先看版本库差异并备份已有配置。

可以把四个文件分成四个问题：

• Dockerfile：构建用哪个 Go 版本，最终运行在哪里，程序从哪个入口启动？
• compose.yaml：本地端口怎样映射，是否需要数据库、缓存或环境变量？
• .dockerignore：哪些本地文件不能进入构建上下文？
• README.Docker.md：生成的启动说明是否仍然符合项目的真实命令？

如果项目已经有自定义 Dockerfile 或 Compose 文件，先复制到备份目录，再决定是否让 docker init 覆盖。这个动作不能靠 Git 回滚完全替代，因为未提交的本地配置和密钥文件可能并不在版本库里。

Go 版本、主包路径和端口必须对齐

生成器给出的 Go 版本只是推断值。先看 go.mod 的 go 指令和项目实际需要的工具链，再决定构建镜像标签。生产构建不要把 latest 当成可追踪版本；版本化标签或经过团队认可的镜像摘要更容易复现。

主程序也不能默认假设在模块根目录。如果项目采用 cmd/api 布局，构建目标应明确写成 ./cmd/api。端口同样要分开看：Dockerfile 的 EXPOSE 只是文档提示，真正把宿主机端口映射进容器的是 Compose 的 ports。

# 下面的目标值需要替换成项目自己的 go.mod、入口包和监听端口
ARG GO_VERSION=1.27.0
FROM golang:${GO_VERSION} AS build
WORKDIR /src

# 先缓存依赖，再编译真正的主包，避免把目录布局写死成根目录
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -o /out/server ./cmd/api

# EXPOSE 只记录容器端口，宿主机映射放在 compose.yaml 中
EXPOSE 8080

如果服务监听地址写成了 127.0.0.1:8080，即使 Compose 映射正确，容器外部也可能访问不到。容器内的 HTTP 服务通常需要监听 0.0.0.0，而不是只监听回环地址。

生产镜像要重新确认构建与运行边界

Go 官方 Docker 指南推荐用多阶段构建把编译环境和运行环境分开。生成配置里常见的合理骨架是：第一阶段使用 Go 镜像下载依赖并编译，第二阶段只复制二进制和运行所需文件。审查时重点看四项：是否需要 CGO、是否需要 CA 证书、是否需要时区数据、进程是否以非 root 用户运行。

# 构建阶段保留编译工具，运行阶段只保留二进制和必要运行数据
FROM alpine:3.22 AS runtime

# HTTPS 请求和时区处理可能依赖这两类系统数据
RUN apk add --no-cache ca-certificates tzdata \
    && addgroup -S app \
    && adduser -S -G app app

# 只复制构建产物，不把 Go 工具链带进最终镜像
COPY --from=build /out/server /usr/local/bin/server
USER app
EXPOSE 8080

# 以明确的二进制作为容器进程入口
ENTRYPOINT ["/usr/local/bin/server"]

如果程序依赖 CGO、动态链接库或特定系统工具，就不能机械套用上面的运行时镜像。此时要根据依赖选择兼容的基础镜像，并把决定写进 Dockerfile 注释和项目说明；不要为了镜像更小而删掉运行所需的库。

收紧构建上下文和 Compose 默认值

.dockerignore 至少应排除 .git、本地构建产物、编辑器目录、日志和含有凭据的环境文件。忽略文件不是秘密管理系统，真正的密钥仍应通过运行时环境、Compose secrets 或部署平台的凭据能力注入，不能把密码写进 Dockerfile 的 ARG 或镜像层。

# 只保留构建需要的项目文件，避免把本地状态带进上下文
.git
.env
.env.*
bin/
tmp/
*.log
.DS_Store

# 运行时凭据必须走外部注入，不把密钥复制进镜像
secrets/
coverage/

Compose 文件则重点复核服务名、端口、健康检查、依赖服务和环境变量。生成的单服务配置适合快速启动，不代表数据库、缓存或消息队列已经配置好。端口映射建议写成可读的显式值，例如 8080:8080；如果只需要本机访问，可以绑定到 127.0.0.1，避免无意暴露到所有网卡。

# 本地开发的启动入口；端口和环境变量按项目实际接口调整
services:
  api:
    build:
      context: .
      target: runtime
    ports:
      - "127.0.0.1:8080:8080"
    environment:
      # 非敏感配置可以直接声明，敏感值改用 secrets 或外部注入
      APP_ENV: development

最后用结果复查，而不是只看文件存在

修改完成后，先确认构建上下文没有秘密文件，再执行一次本地构建和 Compose 启动。重点不是看到“构建成功”四个字，而是确认容器内进程使用了正确入口、端口能从预期地址访问、非 root 用户生效、HTTPS 和时区行为符合服务需要。

# 重新构建并启动，观察生成的入口和端口是否与项目约定一致
docker compose up --build

# 另开终端确认容器状态与端口映射；名称按实际 Compose 服务替换
docker compose ps

# 停止本地服务，避免调试容器长期占用端口
docker compose down

可以把这次复查结果写回 README.Docker.md，让下一位开发者知道哪些值是生成器默认值、哪些值是项目有意修改过的决定。

常见问题

docker init 生成的 Dockerfile 能直接用于生产吗？通常不能直接视为生产定稿。它能提供合理起点，但 Go 版本、构建目标、CGO、运行用户、证书、时区、端口和秘密注入都需要结合项目核对。

为什么 Dockerfile 写了 EXPOSE，宿主机还是访问不到？EXPOSE 主要是端口声明，不等于发布端口。还要在 Compose 的 ports 或 docker run -p 中建立宿主机到容器的映射，并确认 Go 服务监听的地址不是容器内的回环地址。

总结一下：docker init 适合减少容器化的重复劳动，但它生成的是可读、可修改的起点。把版本、入口、端口、运行时和构建上下文逐项改成项目真实边界，才能让这份默认配置变成可维护的 Go 容器方案。