用 Docker Compose 编排一个 Go 聊天室：从踩坑到跑通

项目NetChat —— 一个纯 Go 标准库实现的 TCP 聊天室无任何第三方依赖目标服务端、客户端各跑一个容器用 Docker Compose 编排环境Windows 11 Docker Desktop Docker Compose v5.5.0githubhttps://github.com/Lucky-Wen-tx/NetChat/tree/docker目录一、项目背景与目标二、动手前的两个认知准备三、前置改造让客户端地址可配置四、Dockerfile 逐段拆解五、docker-compose.yml 逐段拆解六、.dockerignore别把垃圾送进构建引擎七、完整操作流程八、构建知识补充重点九、up还是run一次性容器全解十、踩坑实录十一、速查表一、项目背景与目标NetChat 的项目结构NetChat/ ├── cmd/ │ ├── server/main.go # 服务端入口监听 :8080 │ └── client/main.go # 客户端入口交互式读 stdin ├── internal/ │ ├── model/ # Message / User 数据结构 │ ├── server/ # ChatServer / ClientConn │ └── client/ # ChatClient ├── pkg/utils/ # 消息打包、格式化、校验 ├── go.mod # module netChatgo 1.26.5零第三方依赖 ├── Dockerfile ├── docker-compose.yml └── .dockerignore两个关键特性决定了整个编排方案服务端是常驻服务net.Listen(tcp, :8080)for { Accept() }循环每个连接起一个 goroutine客户端是交互式程序读os.Stdin输昵称、发消息exit退出这两点差异直接导致两个容器需要用完全不同的启动方式。最终产出两个镜像体积都很小镜像大小netchat-server:latest15.8 MBnetchat-client:latest15.9 MB二、动手前的两个认知准备在写 Dockerfile 之前先把两个最容易搞混的概念理清楚。2.1 Dockerfile 是「脚本」不是「产物」一个 Dockerfile 里可以有任意多个FROM。每一个FROM开启一个新的「构建阶段stage」。FROM golang:1.26.5-alpine AS builder # ← 阶段 1 FROM alpine:3.20 AS server # ← 阶段 2 FROM alpine:3.20 AS client # ← 阶段 32.2 一次docker build只产出「一个」镜像这就是「一个 Dockerfile 怎么会构建出两个镜像」这个疑问的答案Dockerfile 被docker build执行了两次每次执行到不同位置停下各产出一个镜像。不是「一次构建变出两个」而是「同一个脚本跑了两遍两遍的停止点不同」。--target决定停止点dockerbuild--targetserver.# 执行 builder → 执行 server → 停dockerbuild--targetclient.# 执行 builder → 执行 client → 停docker history可以看到两个镜像的顶层指令完全不同证明它们是两段不同的脚本代码分别执行的netchat-server镜像层netchat-client镜像层ENTRYPOINT [/app/server]ENTRYPOINT [/app/client]USER netchatUSER netchatEXPOSE [8080/tcp](client 阶段没写 EXPOSE)COPY /out/server /app/serverCOPY /out/client /app/client实测验证两个镜像的 ID 完全不同创建时间也可能相差很远取决于你什么时候构建的它们。三、前置改造让客户端地址可配置3.1 问题客户端硬编码了127.0.0.1原代码cmd/client/main.goiferr:cli.Connect(127.0.0.1:8080);err!nil{根本原因每个容器有独立的 network namespace其中包括一块独立的 loopback 网卡。客户端容器里的127.0.0.1指向的是它自己的回环设备跟服务端容器毫无关系——就像两台不同的电脑你在 A 电脑上 ping127.0.0.1永远 ping 不到 B 电脑。结果必然是connection refused。3.2 解决方案环境变量 默认值兜底// defaultServerAddr 本地直接运行时的默认服务端地址。// 容器编排场景下不会走到这里而是由环境变量 SERVER_ADDR 覆盖// 原因容器内的 127.0.0.1 指向客户端容器自身连不到服务端容器。constdefaultServerAddr127.0.0.1:8080funcmain(){// 服务端地址优先读环境变量 SERVER_ADDR未设置时回退到本地默认值。// 这样同一份二进制既能本地 go run也能在 docker-compose 里用服务名互联。serverAddr:os.Getenv(SERVER_ADDR)ifserverAddr{serverAddrdefaultServerAddr}// ...}为什么要保留默认值而不是直接写死server:8080因为在宿主机上执行go run ./cmd/client时宿主机并不存在名为server的 DNS 记录一样连不上。「环境变量优先 合理默认值兜底」是十二要素应用12-Factor App的 Config 原则配置存在环境里代码里只留默认值。一份二进制同时适配两种运行环境。四、Dockerfile 逐段拆解# 阶段 1builder —— 编译环境不会进入最终镜像 FROM golang:1.26.5-alpine AS builder WORKDIR /build COPY go.mod ./ RUN go mod download COPY . . RUN CGO_ENABLED0 GOOSlinux go build -trimpath -ldflags-s -w -o /out/server ./cmd/server \ CGO_ENABLED0 GOOSlinux go build -trimpath -ldflags-s -w -o /out/client ./cmd/client # 阶段 2server —— 服务端运行时镜像 FROM alpine:3.20 AS server RUN adduser -D -u 10001 netchat WORKDIR /app COPY --frombuilder /out/server /app/server EXPOSE 8080 USER netchat ENTRYPOINT [/app/server] # 阶段 3client —— 客户端运行时镜像 FROM alpine:3.20 AS client RUN adduser -D -u 10001 netchat WORKDIR /app COPY --frombuilder /out/client /app/client USER netchat ENTRYPOINT [/app/client]4.1 为什么用多阶段构建Go 官方构建镜像带着完整工具链编译器、链接器、git 等解压后 300MB而最终运行的二进制只有几 MB。多阶段构建 阶段 1 拿全套工具把活干完阶段 2 只把产物拿过来。三个收益体积从 ~300MB 降到 ~16MB攻击面镜像里没有编译器、没有包管理器被攻破后能利用的东西少得多构建依赖不泄漏构建机的目录结构、中间文件都不会出现在生产镜像里4.2 为什么用「单文件双 target」而不是两个 Dockerfile两个二进制来自同一个 Go module依赖完全相同。用两个 Dockerfile构建 server 时要准备一遍构建环境、构建 client 时又要重新下载依赖——两份一模一样的COPY go.modgo mod download层。单文件双 target 的 builder 阶段只有一份被两个 target 共享。这就是为什么第二次构建几乎瞬间完成改完客户端代码重新构建服务端镜像时builder 阶段完全命中缓存。4.3 分层顺序为什么不能随便换Docker 分层缓存的规则某一条指令的输入变了它和它之后的所有层缓存全部失效。正确的顺序COPY go.mod ./ # 第 1 层很少变 RUN go mod download # 第 2 层只要第 1 层没变就永远命中缓存 COPY . . # 第 3 层经常变 RUN go build ... # 第 4 层反例如果先COPY . .再go mod download你每改一行代码第 3 层就失效于是go mod download每次都要把所有依赖重新下一遍。⚠️注意网上大量模板写COPY go.mod go.sum ./但这个项目没有 go.sum零第三方依赖。Docker 的COPY遇到不存在的源文件会直接报COPY failed: no source files were specified构建失败。所以这里只能写COPY go.mod ./。另外本项目当前go mod download实际不下载任何东西。这个结构是为将来引入依赖预留的。4.4 四个编译参数各解决什么问题CGO_ENABLED0 GOOSlinux go build -trimpath -ldflags-s -w参数解决什么问题不加的后果CGO_ENABLED0关闭 cgo产出纯静态二进制动态依赖构建机的 glibc换到 alpine(musl) 直接跑不起来GOOSlinux明确目标平台在 Windows 上构建不指定会产出.exe容器里报exec format error-trimpath去掉二进制内嵌的本地绝对路径把E:\Golang\study\NetChat\...编译进去泄漏构建机结构且不可复现-ldflags-s -w-s去符号表-w去 DWARF 调试信息体积大 25%~30%-s -w会影响调试吗不影响 panic 堆栈。Go 用自己的 pclntab 表记录函数信息不依赖 ELF 符号表所以线上 panic 依然能打出完整函数名和行号。4.5 构建镜像 tag 为什么要锁版本用的是golang:1.26.5-alpine而不是golang:latest锁定版本保证可复现——latest会随上游漂移今天能构建不代表明天能与go.mod里声明的go 1.26.5保持一致——如果构建镜像内置的 Go 低于这个版本Go 会自动联网下载指定 toolchain构建会变慢甚至失败用 alpine 版而不是 debian 版构建镜像 270MB vs 800MB五、docker-compose.yml 逐段拆解services:server:build:context:.# 构建上下文为项目根目录target:server# 指定使用 Dockerfile 中的 server 阶段image:netchat-server:latestcontainer_name:netchat-serverrestart:nonetworks:-netchatclient:build:context:.target:clientimage:netchat-client:latestcontainer_name:netchat-clientdepends_on:-serverenvironment:-SERVER_ADDRserver:8080stdin_open:truetty:truerestart:nonetworks:-netchatnetworks:netchat:driver:bridge5.1server:8080是怎么被解析出来的Compose 为本项目创建一个 bridge 网络名叫netchat_netchat格式是项目名_网络名两个服务都加入该网络各自获得一个容器 IPDocker 在每个容器的 network namespace 里跑一个内置 DNS 服务地址固定在127.0.0.11:53容器里/etc/resolv.conf的 nameserver 指向127.0.0.11服务名和容器名自动注册成 A 记录——客户端容器查server就能拿到服务端容器 IP所以不需要手动配 IP不需要links那是 Compose V1 的遗留写法已废弃不需要改 hosts。为什么不用network_mode: host绕过这一切Windows 上 Docker 实际跑在 WSL2 虚拟机里host模式语义跟 Linux 原生完全不同而且会丢掉容器隔离两个进程还会争抢宿主机端口。5.2 不映射端口容器之间照样能通这是最常见的误区要区分三件事机制作用范围是否影响容器互访ports: 8080:8080打通「宿主机 → 容器」不影响EXPOSE 8080纯粹的文档声明不影响同一个自定义网络打通「容器 → 容器」这是唯一的依赖容器之间通信走的是 bridge 网络里的虚拟网卡对veth pair数据包直接在内核网桥里转发压根不经过宿主机的端口映射层。所以本方案去掉ports后客户端容器访问server:8080✅ 正常宿主机上的本地go run客户端访问localhost:8080❌ 连不上想恢复宿主机调试能力给 server 补一行ports: - 8080:8080即可。5.3 客户端为什么绝对不能配restartrestart: unless-stopped的语义是「容器只要退出就重启」。而客户端的正常生命周期就是聊天结束即退出——这在 restart 策略看来跟崩溃没区别。结果就是退出 → 重启 → 秒退 → 重启……无限循环还反复冲击服务端。5.4depends_on的真实语义depends_on只保证「启动顺序」不保证服务就绪。它先起 server 容器再起 client 容器但不会等待服务端真正 listen 成功。所以理论上客户端首次连接有小概率失败。本项目服务端是毫秒级启动实测不触发。要彻底解决需要给服务端加healthcheckdepends_on: condition: service_healthy。六、.dockerignore别把垃圾送进构建引擎docker build会把 context 目录整个打包发给构建引擎。不排除无关文件会拖慢构建并可能把敏感文件带进镜像层。# 编译产物容器内会重新编译 linux 二进制宿主机产物无用 *.exe netchat-server netchat-client bin/ out/ # 版本控制 .git .gitignore # IDE / 编辑器 .idea/ .vscode/ *.swp # 敏感信息禁止进入镜像 .env .env.* *.local # 备份文件 *.bak # Docker 自身配置由构建引擎直接读取无需进上下文 Dockerfile docker-compose.yml .dockerignore # 文档 *.md排除项理由*.exe、bin/、out/宿主机产物是 Windows 二进制容器内会重新编译.git体积极大且每次 commit 都变会每次都击穿构建缓存.env敏感信息绝不进镜像镜像层删了也还在历史里*.bak改代码时的备份文件不该进上下文红线这是排除清单绝不能把cmd/、internal/、pkg/、go.mod写进去否则COPY . .会缺文件构建直接失败。七、完整操作流程# 0. 前置Docker Desktop 必须处于运行状态# 1. 构建 后台启动服务端dockercompose up-d--buildserver# 2. 看服务端日志确认起来了dockercompose logs-fserver# 期望输出TCP 聊天服务端[摸鱼小组]已启动监听 :8080# 3. 进入客户端聊天-it 交互退出后容器自动删除dockercompose run--rm--no-deps client# 按提示输昵称 → 发消息 → 输 exit 退出# 4. 想模拟多人聊天另开终端再执行一次可开任意多个dockercompose run--rmclient# 5. 全部停止并清理dockercompose down推荐给客户端的命令加上--no-depsdockercompose run--rm--no-deps client理由见第十节踩坑实录 #3。八、构建知识补充重点这一节是整篇的核心知识点。8.1 什么时候会自动构建情况docker compose up -d的行为服务有build:配置但本地没有该镜像✅ 自动构建本地已有该镜像但源码改了❌不构建直接用旧镜像本地已有镜像容器配置也没变❌ 不构建、不重建容器保持 running核心原因Compose 不会去追踪 Dockerfile 或源码文件的变更。要做这件事它得对整个构建上下文算哈希并保存比对代价不小所以设计上就交给显式的--build来处理。证据docker compose up --help原文--build Build images before starting containers --no-build Dont build an image, even if its policy注意--no-build的措辞是「即使策略要求构建也不构建」——说明默认的构建与否是由策略决定的策略 镜像缺失才构建而不是由「源码有没有改」决定的。8.2--build的必要性真实踩坑案例本项目的真实案例修改了cmd/server/main.go执行docker compose up -d server没加--build现象容器被重建了因为 compose 文件也改过但日志里还是旧行为原因拆解容器重建是因为compose 配置漂移容器配置 ≠ compose 文件二进制没更新是因为镜像已存在Compose 直接复用没有重新编译所以「容器重建了」和「代码更新了」是两件独立的事。改代码后必须--build。8.3 多阶段构建与--target的执行细节以docker build --target server .为例① 执行 builder 阶段 → 编译出 /out/server 和 /out/client 两个二进制 结果被丢弃不留镜像 ② 执行 server 阶段 → alpine COPY --frombuilder /out/server ✅ 这个就是最终镜像 ③ client 阶段 → 根本不执行注意builder 阶段会完整执行编译两个二进制但它的产物不会成为镜像中间阶段默认被丢弃第二次用--target client构建时builder 阶段100% 命中缓存直接复用8.4 Compose 如何把「两个服务」翻译成「两次构建」看两个服务的 build 配置——context相同、dockerfile相同只有target不同server:build:{context:.,target:server}# → docker build --target server .client:build:{context:.,target:client}# → docker build --target client .Compose 的逻辑「构建一个服务」 「以该服务的build:配置为参数发起一次docker build」。所以两个服务 → 两次独立的docker build→ 两个镜像你说「只构建 server」Compose 就只发起那一次 build。它在机制上没有能力顺带构建 client因为那是另一次独立调用这就解释了为什么docker compose up -d --build server只看到 server 在构建——不是漏了是按你点名的粒度执行。8.5 client 镜像是怎么被构建的在第一次执行docker compose run --rm client时被自动构建的。Compose 对镜像有默认策略缺就构建。第一次run时它发现netchat-client:latest不存在就按 client 服务的 build 配置自动发起了一次docker build --target client。实测复刻过程步骤1docker compose build server → Image mstest-server:latest Built → 镜像列表只有 mstest-server 步骤2docker compose run --rm client ← 此时 client 镜像还不存在 → Image mstest-client:latest Built ← 自动构建了 → 我是 client 进程 步骤3再看镜像列表 → mstest-client:latest ID5d081f3704c0 创建于1 秒前 → mstest-server:latest IDc74366c7c6e2 创建于8 秒前两个镜像 ID 完全不同——铁证「两次独立构建」。8.6 构建缓存与提速分层缓存的机制在 4.3 已讲。这里补充几个实践要点dockercompose build# 构建两个服务dockercompose build server# 只构建 serverdockercompose build --no-cache server# 完全不用缓存排查诡异问题时用--no-cache是排查「明明改了代码却没生效」类问题的终极武器——虽然 99% 的情况是因为忘了--build。8.7 Compose Watch真正的「改代码自动重建」如果确实想要「改代码自动生效」官方有专门的机制不是靠up自己判断dockercomposewatch# 长驻进程带状态界面需要在服务里配置develop.watchdevelop:watch:-action:rebuild# 重建镜像 重建容器path:./cmd-action:rebuildpath:./internal-action:rebuildpath:./pkg三个注意点对 Go 只能用action: rebuild。另外两个动作sync把文件拷进运行中的容器和restart不适用——服务端是编译型二进制把.go源码拷进容器不会有任何效果。sync是给 Node/Python 那种解释型运行时准备的。每次 rebuild 都会重启容器→ 本项目ChatServer.clients是内存 map在线用户列表会被清空、所有连接断开。别拿它当热更新。rebuild会走 BuildKit 层缓存通常几秒不会重下依赖。生产环境不要用 Watch。正经流程是 CI 里docker compose build完把镜像推到仓库用不可变 tag如 git commit sha部署。九、up还是run一次性容器全解9.1 命名规则容器名字来源服务端netchat-servercompose 里的container_name: netchat-server客户端netchat-client-run-4979ef2cfe25docker compose run专用的一次性命名默认命名规则是项目名-服务名-序号即netchat-server-1写了container_name才会被覆盖。一次性容器的命名格式是固定的项目名-服务名-run-随机哈希 netchat - client - run - 4979ef2cfe25看到-run-这个中缀就说明它是docker compose run创建的。9.2 为什么run不理container_namedocker compose run故意无视container_name。设计原因一次性容器要能同时开好几个。你想模拟多人聊天就会开 3 个客户端如果第一个占用了netchat-client第二个就会因「名字已被占用」起不来。所以每次run都生成随机后缀保证任意多个并存互不干扰。副作用docker-compose.yml里那行container_name: netchat-client在实际工作流中从未生效因为只用run从没用过up client。实测验证$dockerps-a--filtername^netchat-client$不存在 → container_name: netchat-client 从未生效9.3 Compose 靠标签识别不靠名字容器名只是给人看的显示层。Compose 完全靠 labels 识别「谁属于哪个项目、哪个服务」。实测两个容器的标签标签netchat-server一次性客户端容器com.docker.compose.oneoffFalseTrue← 分水岭com.docker.compose.serviceserverclientcom.docker.compose.container-number1空com.docker.compose.projectnetchatnetchat两个容器的project和service标签都齐全Compose 靠它们正确认领。但oneoff这一个字段把它们划成了两类决定了一堆实际行为。9.4oneoffTrue的三个实际差别①docker compose ps默认看不到它$dockercomposepsnetchat-serverserviceserver# 只有它$dockercomposeps-anetchat-client-run-4979ef2cfe25serviceclient# 加 -a 才出现netchat-serverserviceserver②up/down根本不管理它实测$dockercompose down Container oneofftest-web-1 Removed# 服务容器被删了Network oneofftest_default Removing Network oneofftest_default Resource is stillinuse# ⚠️ 网络删不掉$dockerps-aoneofftest-cli-run-e5134960a6f5 Up3seconds# 一次性容器还活着⚠️坑只要还有一次性容器在跑它就占着那个网络docker compose down会报Resource is still in use网络清理不干净。解决办法就是正常退出客户端——有了--rm容器一退出就自动删除。③--rm让它「用完即焚」客户端容器在你还连着的时候是Up输exit退出后整个容器会自动消失。这就是--rm的价值——不加的话每聊一次天就在磁盘上留一个Exited容器攒几十个之后docker ps -a就没法看了。9.5 总表服务容器一次性容器谁创建docker compose updocker compose run命名container_name或默认项目-服务-序号项目-服务-run-随机哈希oneoff标签FalseTruedocker compose ps✅ 显示❌ 不显示要-aup/down管理✅❌还会挡住网络清理能否同时开多个受名字限制✅ 随机名随便开生命周期长期常驻一次任务用完即走本项目用途服务端常驻监听坐下聊一次天所以netchat-server和netchat-client-run-xxxx这个命名差异不是 bug是两个容器角色不同导致的自然结果。十、踩坑实录坑1服务端会「自动重启」现象启动服务端后一执行客户端命令服务端就重新启动了。排查证据证据实测值说明服务端容器Created02:48:17.248Z客户端 run 容器Created02:48:17.632Z只比服务端晚 0.38 秒服务端RestartCount0重启策略从未触发过服务端FinishedAt0001-01-01这个容器从出生起一直在跑服务端日志只有 1 条启动横幅没有反复启动docker compose up -d --dry-run serverContainer netchat-server Running当前配置与运行容器一致两个容器创建时间只差 0.38 秒—— 你不可能手动在两条命令之间只隔 0.38 秒。所以服务端容器是那条docker compose run顺手创建出来的。真相不是「重启」是旧容器被销毁、重新创建了一个新容器。根本原因docker compose run 服务执行时会先「确保」它的depends_on依赖处于与当前 compose 文件一致的状态。一旦发现依赖的配置和启动它时不一样了Compose 就会销毁旧容器、按新配置创建新容器。触发条件任何影响容器配置的字段变更——environment、command、ports、volumes、container_name以及镜像变了重新--build之后。对照实验临时项目已清理步骤操作web容器创建时间结论1docker compose up -d web02:52:37.368基线2什么都不改docker compose run cli02:52:37.368没变 →不漂移就不碰它3改了 compose 里 web 的FOO1→2再run cli02:52:44.674变了→ 被销毁重建解决方案给客户端命令加--no-depsdockercompose run--rm--no-deps client--no-deps的官方说明是Dont start linked services——别管我依赖的服务。客户端连的是已经在跑的server:8080不需要 Compose 去确保服务端状态。代价服务端没在跑时会直接报「连接服务器失败」。但这是好事——错误明确而不是偷偷把服务端重建一遍。十一、速查表构建相关命令作用docker compose build构建两个服务的镜像不启动容器docker compose build server只构建 server 镜像docker compose build --no-cache server完全不用缓存构建docker build --target server -t netchat-server .手动构建等价于 compose 做的事启动相关命令作用于是否重建镜像docker compose up -d serverserver❌ 镜像存在就复用docker compose up -d --build serverserver✅ 强制重建docker compose up -d clientclient❌客户端会因无 stdin 秒退docker compose up -d --build两个✅会连 client 一起启动docker compose run --rm clientclient一次性仅当镜像缺失docker compose run --rm --no-deps clientclient一次性仅当镜像缺失不动依赖排查相关命令作用docker compose ps只显示服务容器docker compose ps -a连一次性容器一起显示docker compose logs -f server跟踪服务端日志docker compose up -d --dry-run server不改动任何东西预览会被重建还是保持docker inspect 容器 --format {{.Created}}看容器真实创建时间docker inspect 容器 --format {{.RestartCount}}看是否被 restart 策略重启过docker inspect 容器 --format {{json .Config.Env}}看容器实际生效的环境变量docker inspect 容器 --format {{index .Config.Labels com.docker.compose.oneoff}}判断是否一次性容器docker history 镜像看镜像分层构成attach 时的按键按键效果Ctrl-P然后Ctrl-Q只断开 attach容器继续跑docker 客户端侧拦截的转义序列Ctrl-C转成 SIGINT 转发进容器会杀掉容器附录完整的容器层结构netchat-server:latest (15.8MB) ├── FROM alpine:3.20 ├── RUN adduser -D -u 10001 netchat ├── WORKDIR /app ├── COPY /out/server /app/server (2.51MB) ← 唯一的业务内容 ├── EXPOSE [8080/tcp] ├── USER netchat └── ENTRYPOINT [/app/server] netchat-client:latest (15.9MB) ├── FROM alpine:3.20 ├── RUN adduser -D -u 10001 netchat ├── WORKDIR /app ├── COPY /out/client /app/client (2.63MB) ← 唯一的业务内容 ├── USER netchat └── ENTRYPOINT [/app/client]两个镜像共享同一个alpine:3.20基础层在磁盘上只存一份其余层各自独立。本文基于 NetChat 项目的实际容器化过程整理所有命令输出和容器时间戳均为真实运行结果。NetChat 项目: https://github.com/Lucky-Wen-tx/NetChat/tree/docker