Go程序必须监听0.0.0.0:8080而非127.0.0.1或localhost，Docker端口映射（-p）决定外部可达性，容器内监听地址与映射配置需协同，调试需分三层验证：容器内监听、Docker映射、宿主机访问。
Go 本身不提供容器运行时能力，net/http 启动的服务器只是监听本地端口，端口映射必须由外部容器引擎（如 Docker）完成 —— Go 程序只需确保监听 0.0.0.0:8080 而非 127.0.0.1:8080。
Go 程序必须绑定 0.0.0.0 才能在容器内被外部访问
Docker 默认将容器网络设为 bridge 模式，宿主机无法访问绑定在 127.0.0.1 上的服务。Go 启动 HTTP 服务时若写死 localhost:8080 或 127.0.0.1:8080，容器内虽运行成功，但端口映射后仍无法从宿主机 curl 通。
-
http.ListenAndServe("0.0.0.0:8080", handler)✅ 正确：监听所有接口 -
http.ListenAndServe("localhost:8080", handler)❌ 容器内等价于127.0.0.1:8080，外部不可达 - 可改用环境变量控制监听地址：
addr := os.Getenv("ADDR"); if addr == "" { addr = "0.0.0.0:8080" }
Docker run 的 -p 参数决定端口映射行为
docker run -p 是唯一影响端口可达性的关键配置，Go 代码完全不参与该过程。常见写法差异直接影响调试体验：
-
docker run -p 8080:8080 myapp→ 宿主机 8080 → 容器 8080 -
docker run -p 127.0.0.1:8080:8080 myapp→ 仅限本机访问（更安全，适合开发） -
docker run -p 8080→ Docker 随机分配宿主机端口（需docker port查看） - 若容器内服务监听
8080，但Dockerfile中未声明EXPOSE 8080，不影响功能，仅丢失元信息和部分 IDE 提示
使用 docker-compose.yml 管理多端口更可靠
手动记 -p 参数易出错，尤其涉及多个端口（如 API + metrics + pprof）。docker-compose.yml 可显式分离配置，且支持环境变量注入：
立即学习“go语言免费学习笔记（深入）”；
version: '3.8'
services:
api:
image: my-go-app
ports:
- "8080:8080" # HTTP API
- "9090:9090" # Prometheus metrics
- "6060:6060" # pprof
environment:
- GIN_MODE=release
- ADDR=0.0.0.0:8080
注意：ports 字段只控制映射，不改变容器内程序行为；environment 才真正传给 Go 进程用于设置 http.ListenAndServe 的地址。
调试时用 netstat 和 curl 验证三层连通性
端口不通时，按顺序排查这三层，避免在 Go 代码里盲目加日志：
- 容器内是否真在监听？进容器执行：
netstat -tlnp | grep :8080（需安装net-tools）或ss -tln | grep :8080 - Docker 是否做了映射？运行
docker ps看 PORTS 列，确认有0.0.0.0:8080->8080/tcp类似输出 - 宿主机能否访问该端口？
curl -v http://localhost:8080/healthz，失败时看是 connection refused（映射没生效）还是 timeout（防火墙或 Docker Desktop 网络异常）
很多问题其实卡在第一层：Go 程序启动时 panic 了，根本没起来，但 docker ps 显示容器状态是 Up 2 seconds，容易误判为端口问题。
