容器与云原生 / 系统课时

服务名能解析但端口连不上怎么办

服务名能解析但端口连不上怎么办

当 api 这样的 Compose 服务名能解析到 IP,却仍然出现连接拒绝或超时,说明 DNS 只完成了第一步。真正建立连接还要求目标端口正确、应用监听在可被其他容器访问的地址上,并且进程已经可用。本节按这条链路逐层定位。

学习目标

  • 区分服务名解析成功与 TCP 连接成功代表的不同事实
  • 判断服务间通信应该使用容器端口还是宿主机映射端口
  • 定位只监听 127.0.0.1、端口配置错误和进程未就绪等问题

DNS 成功只证明名字找到了容器

默认情况下,同一个 Compose 项目的服务会加入项目网络,并可通过服务名互相发现。服务名解析成功,只能证明客户端得到了目标容器的网络地址;它不能证明目标进程已经监听端口,也不能证明应用已经完成启动。服务间通信应使用容器端口,不是宿主机端口映射。([Docker Documentation][3])

例如把宿主端口 8080 映射到容器端口 8000 后,另一个 Compose 服务仍应连接 api:8000;把目标写成 api:8080,通常会连到一个没有进程监听的端口。

服务名解析成功但 TCP 端口失败的排查链路

用最小案例复现“能解析但拒绝连接”

下面故意让 api 的 HTTP 服务只绑定 127.0.0.1:8000。client 与它处在同一 Compose 网络,因此能解析 api,但访问目标容器 IP 的 8000 会被拒绝。

bash
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 返回拒绝。

text
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。

bash
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。

text
http_status=200

用错误类型缩小范围

现象 优先检查
服务名无法解析 两个服务是否共享网络、服务名是否正确
能解析但 ECONNREFUSED 目标端口是否正确、进程是否监听该端口、是否只绑定 127.0.0.1
能解析但连接超时 网络路径或防火墙是否丢包、目标进程是否卡住
TCP 可连但 HTTP 报错 应用路由、协议、认证和上游依赖

因此,“能 ping 通”或“能解析”都不能结束排查。把问题拆成 名称解析 → 容器 IP → 容器端口 → 监听地址 → 应用就绪,在哪一层第一次失败,就从那一层修复,通常比反复修改 Compose 网络配置更快。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

服务名能解析但端口连不上怎么办

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通