本文详解如何通过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服务赋予唯一、语义化服务名：
# 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+端口，无需映射宿主机端口 |
遵循以上三步，即可让 mgmt-service 稳定调用 api-service，为后续集成测试、Mock网关、分布式调试奠定坚实网络基础。
