Echo服务Docker部署失败主因是未用多阶段构建且未静态编译，须设CGO_ENABLED=0、GOOS=linux、监听0.0.0.0并配健康检查。
docker-compose 启动 Echo 服务失败？八成是镜像没做多阶段构建，或者 CMD 指向了源码而非静态二进制 —— 直接用 golang:alpine 运行 go run 或挂载源码进容器，在生产环境等于裸奔。
为什么不能直接用 golang 镜像跑 Echo
官方 golang:1.23-alpine 镜像体积约 380MB，含全套编译工具链和调试依赖，但你的 Echo 服务只需要一个可执行文件 + ca-certificates。更关键的是：go run main.go 或 go build && ./main 在容器里运行，会继承宿主机的 CGO 环境，导致 Alpine 下动态链接失败（典型报错：standard_init_linux.go:228: exec user process caused: no such file or directory）。
- CGO_ENABLED=0 是硬性要求，否则编译出的二进制依赖系统 libc，而 Alpine 用的是 musl
-
go run无法用于生产：它每次启动都重新编译，无缓存、无优化、无 panic 捕获上下文 - 不分离构建与运行阶段，镜像里会残留
go.mod、vendor、.git，增大攻击面
Dockerfile 必须用多阶段构建
以下是最小可行 Dockerfile，适配 Echo v4 + Alpine 运行时：
FROM golang:1.23-alpine AS builder WORKDIR /app COPY go.mod go.sum ./ RUN go mod download COPY . . RUN CGO_ENABLED=0 GOOS=linux go build -a -ldflags '-extldflags "-static"' -o /app/server . <p>FROM alpine:latest RUN apk --no-cache add ca-certificates WORKDIR /root/ COPY --from=builder /app/server . EXPOSE 8080 CMD ["./server"]
-
GOOS=linux必须显式指定，本地 macOS/Windows 构建时容易遗漏 -
-a -ldflags '-extldflags "-static"'强制全静态链接，避免运行时缺库 - 第二阶段不装
git、bash、curl等任何非必需工具，镜像压到 ~15MB -
EXPOSE不影响实际端口绑定，Echo 必须在代码里监听0.0.0.0:8080，不是127.0.0.1:8080
docker-compose.yml 要配对健康检查和网络
仅靠 restart: always 不够 —— Echo 启动后可能卡在 DB 连接或配置加载，docker-compose up 会认为服务已就绪，但实际不可用。
立即学习“go语言免费学习笔记（深入）”；
version: '3.8'
services:
echo-api:
build: .
ports:
- "8080:8080"
environment:
- ENV=production
- DB_HOST=postgres
- DB_PORT=5432
depends_on:
postgres:
condition: service_healthy
healthcheck:
test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:8080/health"]
interval: 10s
timeout: 3s
retries: 3
start_period: 40s
networks:
- backend
<p>postgres:
image: postgres:15-alpine
environment:
POSTGRES_DB: echo_demo
POSTGRES_PASSWORD: devpass
volumes:</p><ul><li>pgdata:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres -d echo_demo"]
interval: 30s
timeout: 10s
retries: 5
networks:</li><li>backend</li></ul><p>volumes:
pgdata:</p><p>networks:
backend:
driver: bridge
- 健康检查用
wget而非curl：Alpine 默认不含curl，装它反而破坏最小化原则 -
start_period: 40s给 Echo 留足初始化时间（加载中间件、连接 DB、预热缓存） - 所有服务共用
backend自定义网络，echo-api可直接用postgres当 DNS 名连数据库 - 不要用
host网络模式：端口冲突、Mac/Windows 行为不一致、绕过 Docker 网络策略
Go 代码里必须监听 0.0.0.0
这是最容易被忽略的部署细节。Echo 默认 e.Start(":8080") 实际绑定的是 127.0.0.1:8080，只接受本机回环请求 —— 容器内 wget http://localhost:8080 能通，但外部流量、docker-compose 网络、健康检查探针全失败。
正确写法：
e.Logger.Fatal(e.Start("0.0.0.0:8080"))
- 别信文档里 “默认监听所有地址” 的说法，Echo v4/v5 默认就是
127.0.0.1 - 如果用了
e.Listener自定义 listener，也必须传0.0.0.0:8080地址字符串 - 加个
/health路由返回200 OK，别用/，避免和业务路由耦合
Echo + Docker-Compose 的核心就三件事：静态编译、0.0.0.0 监听、独立健康检查。其余都是锦上添花 —— 多阶段构建不是炫技，是防止 Alpine 下 no such file or directory；0.0.0.0 不是可选项，是容器网络生效的前提；健康检查不配 start_period，服务大概率启动成功却不可用。
