容器与云原生 / 系统课时
服务名能解析但端口连不上怎么办
服务名能解析但端口连不上怎么办
当 api 这样的 Compose 服务名能解析到 IP,却仍然出现连接拒绝或超时,说明 DNS 只完成了第一步。真正建立连接还要求目标端口正确、应用监听在可被其他容器访问的地址上,并且进程已经可用。本节按这条链路逐层定位。
学习目标
- 区分服务名解析成功与 TCP 连接成功代表的不同事实
- 判断服务间通信应该使用容器端口还是宿主机映射端口
- 定位只监听
127.0.0.1、端口配置错误和进程未就绪等问题
DNS 成功只证明名字找到了容器
默认情况下,同一个 Compose 项目的服务会加入项目网络,并可通过服务名互相发现。服务名解析成功,只能证明客户端得到了目标容器的网络地址;它不能证明目标进程已经监听端口,也不能证明应用已经完成启动。服务间通信应使用容器端口,不是宿主机端口映射。([Docker Documentation][3])
例如把宿主端口 8080 映射到容器端口 8000 后,另一个 Compose 服务仍应连接 api:8000;把目标写成 api:8080,通常会连到一个没有进程监听的端口。

用最小案例复现“能解析但拒绝连接”
下面故意让 api 的 HTTP 服务只绑定 127.0.0.1:8000。client 与它处在同一 Compose 网络,因此能解析 api,但访问目标容器 IP 的 8000 会被拒绝。
cat > compose.yaml <<'YAML'
services:
api:
image: python:3.13-alpine
command: ["python", "-m", "http.server", "8000", "--bind", "127.0.0.1"]
client:
image: python:3.13-alpine
command: ["python", "-c", "import time; time.sleep(10**9)"]
YAML
docker compose up -d
docker compose exec client python -c 'import socket; print("resolved=" + socket.gethostbyname("api"))'
docker compose exec client python -c 'import errno,socket; s=socket.socket(); s.settimeout(2); code=s.connect_ex(("api",8000)); print("tcp=" + errno.errorcode.get(code,str(code)))'预期输出的 IP 会随 Docker 网络变化,因此用 <IP> 表示动态值;关键是 DNS 成功而 TCP 返回拒绝。
resolved=<IP>
tcp=ECONNREFUSED这时不要继续纠结 DNS。api 已经能被解析,失败发生在“目标 IP + 目标端口”之后。
从端口到监听地址逐层检查
先确认客户端使用的是应用真正监听的容器端口。若 Compose 写的是 8080:8000,服务间应访问 api:8000。宿主端口映射不会把容器内部的 8080 自动变成监听端口。
接着检查应用绑定地址。进程监听 127.0.0.1:<PORT> 时,只接受来自同一容器网络命名空间的回环连接;其他容器访问的是该容器的网卡 IP,因此连接不到。多数需要被同网络服务访问的服务器,应监听 0.0.0.0:<PORT>,或者明确监听容器网卡地址。
最后确认“进程存在”和“服务可用”不是一回事。容器状态为 Running 时,应用可能仍在初始化,也可能已经启动但健康检查失败。此时应结合应用日志、健康检查和实际请求判断,不要只看 docker compose ps 的运行状态。
修复监听地址并重新验证
把示例中的 HTTP 服务改为监听所有 IPv4 接口,再重建 api。客户端仍然通过服务名和容器端口访问,不需要知道目标容器的具体 IP。
cat > compose.yaml <<'YAML'
services:
api:
image: python:3.13-alpine
command: ["python", "-m", "http.server", "8000", "--bind", "0.0.0.0"]
ports:
- "8080:8000"
client:
image: python:3.13-alpine
command: ["python", "-c", "import time; time.sleep(10**9)"]
YAML
docker compose up -d --force-recreate api client
docker compose exec -T client python - <<'PY'
import time
import urllib.request
for _ in range(20):
try:
response = urllib.request.urlopen("http://api:8000", timeout=1)
print("http_status=" + str(response.status))
break
except OSError:
time.sleep(0.2)
else:
raise SystemExit("api not ready")
PY预期输出如下;8080 只是宿主访问入口,容器间验证仍使用 api:8000。
http_status=200用错误类型缩小范围
| 现象 | 优先检查 |
|---|---|
| 服务名无法解析 | 两个服务是否共享网络、服务名是否正确 |
能解析但 ECONNREFUSED |
目标端口是否正确、进程是否监听该端口、是否只绑定 127.0.0.1 |
| 能解析但连接超时 | 网络路径或防火墙是否丢包、目标进程是否卡住 |
| TCP 可连但 HTTP 报错 | 应用路由、协议、认证和上游依赖 |
因此,“能 ping 通”或“能解析”都不能结束排查。把问题拆成 名称解析 → 容器 IP → 容器端口 → 监听地址 → 应用就绪,在哪一层第一次失败,就从那一层修复,通常比反复修改 Compose 网络配置更快。