Kratos框架需自建Dockerfile实现轻量容器化，必须采用多阶段构建、禁用CGO、显式静态链接，并正确挂载配置路径与服务网络；否则将因镜像臃肿、运行报错或DNS解析失败导致部署失败。
Kratos 框架本身不提供开箱即用的 Docker 部署方案，但它的 Go 语言特性 + 标准构建流程，让它比 Spring Boot 等框架更轻量、更易容器化——关键在于你得自己写好 Dockerfile，并避开几个 Go 容器化典型坑。
为什么 Kratos 的 Dockerfile 不能直接抄别人的？
Kratos 默认使用 go build -o 生成静态二进制，但很多网上示例仍沿用 FROM golang:1.21 做单阶段构建，导致镜像体积大（>900MB）、启动慢、存在多余构建工具。它本该是“编译一次、扔掉 Go 环境”的典型场景。
- 必须用多阶段构建：第一阶段用
golang:1.21-alpine编译，第二阶段用alpine:3.20或scratch运行 - 要显式关闭 CGO：
CGO_ENABLED=0，否则 Alpine 镜像里缺 libc，运行时报standard_init_linux.go:228: exec user process caused: no such file or directory - Kratos 的
config默认读取./configs/目录，但容器里没这个路径——要么 COPY 进去，要么用-conf参数指定绝对路径
一个能跑通的最小可行 Dockerfile
假设你的 Kratos 项目根目录下有 cmd/main.go 和 configs/app.yaml：
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 -ldflags '-extldflags "-static"' -o /app/kratos cmd/main.go <p>FROM alpine:3.20 RUN apk --no-cache add ca-certificates WORKDIR /root/ COPY --from=builder /app/kratos . COPY --from=builder /app/configs ./configs EXPOSE 9000 CMD ["./kratos", "-conf", "./configs"]
注意点：
-
go build -a -ldflags '-extldflags "-static"'是为了彻底静态链接，避免 Alpine 缺共享库 - 别漏掉
COPY --from=builder /app/configs ./configs，否则启动就 panic：找不到配置文件 - 如果用了 MySQL 或 Redis，记得在
configs/app.yaml里把地址从127.0.0.1改成对应服务名（比如mysql），并在docker-compose.yml里定义网络
docker-compose.yml 怎么配才不踩 DNS 解析失败？
Kratos 启动时若连不上依赖服务（如 etcd、MySQL），常见错误是 context deadline exceeded 或 dial tcp: lookup mysql on 127.0.0.11:53: no such host——这说明容器内 DNS 解析失败，本质是服务未就绪或网络未对齐。
- 必须用自定义 bridge 网络，不能依赖默认
bridge：默认网络里容器间无法用服务名通信 - 加
depends_on不够，它只控制启动顺序，不等服务真正 ready；要用healthcheck+condition: service_healthy - Kratos 容器的
restart策略建议设为on-failure:3，而不是always，避免反复拉起失败实例掩盖真实问题
示例片段：
version: '3.8'
services:
kratos:
build: .
restart: on-failure:3
depends_on:
mysql:
condition: service_healthy
environment:
- CONF_PATH=./configs
networks:
- kratos-net
<p>mysql:
image: mysql:8.0
healthcheck:
test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "root", "-p$$MYSQL_ROOT_PASSWORD"]
timeout: 20s
retries: 10
networks:</p><ul><li>kratos-net</li></ul><p>networks:
kratos-net:
driver: bridge
部署后第一个要验证的不是接口，而是日志和探针
Kratos 默认暴露 /debug/health 和 /debug/metrics，但很多人部署完直接 curl http://localhost:9000/health 返回 404，其实是因为：
- 没在
main.go里注册 debug server：kratos.NewServer(..., debug.Server())必须显式加上 - 端口映射漏了：
docker run -p 9000:9000或docker-compose.yml里没写ports字段 - 防火墙或宿主机 SELinux 拦截了端口（尤其 CentOS/RHEL 系统）
建议上线前必做三件事：
- 进容器执行
ps aux | grep kratos，确认进程在跑且没立刻退出 - 查容器日志：
docker logs kratos，重点看有没有failed to connect to etcd或open configs/app.yaml: no such file - 从同网络另一容器（比如
alpine:3.20）里nslookup kratos和telnet kratos 9000，验证服务发现和端口可达性
最常被忽略的是：Kratos 的 app.yaml 里 server.http.addr 默认是 0.0.0.0:9000，但如果你写成 127.0.0.1:9000，容器外部就完全访问不到——这个细节在本地开发时没问题，一上 Docker 就失效。
