Docker多环境容器间通信实战：3步打通管理服务与API服务网络-js教程-PHP中文网

Docker多环境容器间通信实战：3步打通管理服务与API服务网络

本文详解如何通过docker自定义桥接网络、统一网络命名与服务发现机制，实现两个独立开发环境（mgmt-service与api-service）间的可靠http通信，彻底解决enotfound域名解析失败与500代理错误问题。

本文详解如何通过docker自定义桥接网络、统一网络命名与服务发现机制，实现两个独立开发环境（mgmt-service与api-service）间的可靠http通信，彻底解决enotfound域名解析失败与500代理错误问题。

在微服务本地开发中，常需让多个Docker Compose项目中的服务跨环境通信——例如管理前端（Next.js + Express）调用后端API服务。但若未显式共享网络或正确配置服务别名，容器将无法通过服务名互相解析，典型报错如 Error: getaddrinfo ENOTFOUND ocd-api-service-app-1，本质是DNS服务发现失效，而非代码逻辑或端口问题。

✅ 正确做法：三步构建可通信的跨服务网络

第一步：统一并复用外部网络（关键！）

两个Compose项目必须接入同一个外部桥接网络，而非各自创建同名但隔离的内部网络。先确认该网络已存在（由任一项目首次docker-compose up创建），再在另一项目中声明为external：

# mgmt-service/compose-dev.yaml
networks:
  ocd-network:
    external: true  # ← 必须设为true，指向已存在的网络
    name: ocd-network  # ← 显式指定网络全名（含项目前缀）

services:
  app:
    networks:
      - ocd-network  # ← 加入共享网络
      - default      # ← 保留默认网络（可选，用于host访问）

同样，在 api-service/compose-dev.yaml 中也需配置完全一致的 networks 块。注意：不要重复定义 driver: bridge，否则会因“网络已存在”报错。

第二步：重命名服务以启用DNS解析

Docker内置DNS仅基于服务名（service name） 解析，而非容器名或自定义别名。当前两项目均将服务命名为 app，导致DNS冲突（app 指向哪个容器？）。必须为API服务赋予唯一、语义化服务名：

Docker Compose Linter

检查 docker-compose.yml 文件的安全问题、最佳实践和端口冲突

下载

# api-service/compose-dev.yaml
services:
  api:  # ← 改为明确的服务名，不再是 'app'
    image: docker/dev-environments-javascript:stable-1
    networks:
      - ocd-network
    # ... 其他配置保持不变

同时，确保API服务监听的端口在容器内暴露（EXPOSE 3001 或 ports: ["3001:3001"]），且应用实际绑定到 0.0.0.0:3001（而非仅 localhost:3001）。

第三步：在代码中使用服务名+端口直连

Express代理路由中，直接使用服务名 api（非容器名、非自定义主机名）作为HTTP请求目标：

// mgmt-service/app.cjs
server.get("/api/proxy", async (req, res) => {
  console.log("hit1");
  try {
    // ✅ 正确：使用服务名 'api' + 容器内端口 3001
    const response = await axios.get("http://api:3001/test");
    res.json(response.data);
  } catch (error) {
    console.error("Error fetching from api service:", error.message);
    res.status(500).json({ error: "Failed to reach API service" });
  }
});

⚠️ 注意事项：

不加 http:// 会导致 Axios 报错；必须写全协议。

端口是容器内端口（3001），不是宿主机映射端口（除非你故意用宿主机网络模式）。

若API服务启动慢，可在 mgmt-service 中添加健康检查或重试逻辑，避免启动时请求失败。

? 验证与调试技巧

查看网络状态：docker network inspect ocd-network → 确认 mgmt-service_app_1 和 api_service_api_1（或类似）均在 Containers 列表中。

进入容器测试连通性：

docker exec -it ocd-mgmt-service-app-1 sh
ping api          # 应能解析并通
curl -v http://api:3001/test  # 应返回JSON

检查API服务日志：docker logs ocd-api-service-api-1，确认其监听 0.0.0.0:3001 且无启动异常。

? 总结：容器通信的核心原则

误区	正解
用容器名（如 ocd-api-service-app-1）做HTTP请求	✅ 用服务名（api）做DNS解析
各自定义同名网络（ocd-network）以为自动互通	✅ 创建一次，其余项目声明为 external: true 复用
认为 ports: ["3001:3001"] 是容器间通信必需	❌ 容器间通信走内部网络IP+端口，无需映射宿主机端口