Docker Compose 自定义网络并用服务名互相访问

Docker Compose 里的服务互相访问时，不要把容器 IP 写进配置。更稳妥的做法是：让相关服务加入同一个 Compose 网络，然后把服务名直接当成主机名。下面用 api 和 client 两个服务完成一次可见、可复查的最小实验：client 访问 http://api:80，无需发布端口，也无需查询 IP。

官方文档：https://docs.docker.com/compose/how-tos/networking/

先理解结果：服务名稳定，容器 IP 不稳定

Compose 会为同一网络里的服务提供内部 DNS。服务启动后，名称 api 会被解析为当前 api 容器的地址；容器重建时 IP 可能变化，但服务名仍然不变。因此，应用连接串应写 api:80，而不是某个 172.x.x.x 地址。

另一个容易混淆的点是端口：容器之间通信使用容器端口。即使配置了 8080:80，同网络服务仍应访问 api:80；8080 是宿主机从外部进入容器时使用的端口。本例只验证内部通信，所以不需要 ports。

步骤一：在 compose.yaml 同时声明网络和成员

沿着 文件树 > 项目根目录 > compose.yaml 打开配置文件。把下面内容保存进去。动作只有两层：先在每个服务下面写服务级 networks，再在文件底部用顶层 networks 声明同名网络。

services:
  api:
    image: nginx:alpine
    # api 只开放容器内的 80 端口，不需要映射到宿主机
    expose:
      - "80"
    networks:
      - app_net

  client:
    image: alpine:3.20
    # 保持容器运行，便于进入 Exec 页面执行连通测试
    command: ["sh", "-c", "sleep infinity"]
    depends_on:
      - api
    networks:
      - app_net

# 顶层声明自定义 bridge 网络，供两个服务共同引用
networks:
  app_net:
    driver: bridge

保存后，界面里应同时看到两处服务级 - app_net 和一处顶层 app_net。如果只写了底部声明却没有把服务加入网络，网络会被创建，但该服务不会自动成为成员。

步骤二：启动项目并在 Containers 页面确认成员

在保存了 compose.yaml 的项目目录执行下面两组命令。先让 Compose 展开并检查最终配置，再后台启动两个服务：

# 展开 Compose 配置，先发现缩进、字段名和网络引用错误
docker compose config

# 后台创建自定义网络并启动 api 与 client
docker compose -p compose-net-demo up -d

命令结束后，打开容器管理界面，进入 Containers > compose-net-demo 并展开项目。单一动作是确认两行状态：api 和 client 都应显示 Running。在网络列或详情页中，两者都应出现 app_net；运行时完整网络名通常会带项目名前缀，例如 compose-net-demo_app_net。

步骤三：在 client 的 Exec 页面验证服务名访问

进入 Containers > compose-net-demo > client > Exec。在命令输入框只执行下面这一条请求：

# 从 client 通过服务名 api 和容器端口 80 访问目标服务
wget -qO- http://api:80

输出中出现 Welcome to nginx!，就同时证明了三件事：两个容器共享网络、内部 DNS 能把 api 解析到当前容器、目标的 80 端口可达。这里不需要先执行 docker inspect 查 IP，也不需要给 api 配置 container_name。

步骤四：按固定顺序排查“服务名访问失败”

如果第三步没有返回内容，不要先改成固定 IP。按“配置、运行、成员、解析、端口”的顺序检查，能更快找到边界。

1. 配置是否生效：执行 docker compose config，确认两个服务展开后都含有 app_net。
2. 容器是否运行：执行 docker compose ps，确认 api 不是退出或反复重启状态。
3. 网络成员是否一致：先列出网络，再检查项目网络的 Containers 字段。
4. 服务名是否正确：Compose DNS 默认使用服务键名，也就是本例的 api，不是镜像名 nginx。
5. 端口是否写成容器端口：服务间使用 80，不要误写宿主机映射端口。

# 查看服务状态，先排除容器未运行
docker compose -p compose-net-demo ps

# 找到实际网络名；Compose 通常会添加项目前缀
docker network ls --filter label=com.docker.compose.project=compose-net-demo

# 把网络名替换为上一条命令显示的值，核对两个容器是否都在 Containers 中
docker network inspect compose-net-demo_app_net

# 直接从 client 再做一次内部访问，避免宿主机端口干扰判断
docker compose -p compose-net-demo exec client wget -qO- http://api:80

为什么不建议写 container_name 或固定 IP

container_name 会把运行实例名称固定下来，却不能替代 Compose 的服务发现模型，还会给扩容和并行项目带来命名冲突。固定 IP 的问题更直接：容器重建后地址可能变化，旧连接也会失效。官方建议始终通过服务名重新解析当前地址。

如果要让一个服务使用额外别名，可以在对应网络下配置 alias；如果是两个不同 Compose 项目共享网络，则应创建 external 网络，并让两边显式加入。那是跨项目场景，不要和本文单项目自定义网络混在一起。

清理本次实验

验证完成后，在项目目录执行：

# 停止并删除本项目的容器与由 Compose 管理的网络
docker compose -p compose-net-demo down

看到项目容器消失、compose-net-demo_app_net 被删除，就完成了资源清理。以后把示例替换成真实应用时，只需保留同一个原则：需要互通的服务加入同一网络，连接地址写“服务名 + 容器端口”。

常见问题

没有声明自定义网络，服务名还能访问吗？

可以。Compose 默认会创建一个项目级 default bridge 网络，并让未显式配置网络的服务加入其中。自定义网络的价值在于明确成员边界、组织多层拓扑以及设置 driver、internal、external 等属性。

depends_on 能保证 api 已经可以响应吗？

短写法只表达启动顺序，不等同于应用已经就绪。真实项目若要求依赖服务健康后再启动，应给目标服务添加 healthcheck，再使用支持健康条件的依赖配置；客户端自身也应保留重试机制。

同一网络上的服务还需要 ports 吗？

内部互访不需要。只有宿主机或网络外部客户端需要访问容器时，才配置 ports。把内部流量和外部入口分开，能减少无意义的端口暴露。