Levi Blog

1. 三个高频报错#

1. connection refused
2. temporary failure in name resolution
3. no route to host

这些报错看起来类似，但根因完全不同。

2. 先看网络拓扑#

1
docker compose ps
2
docker network ls
3
docker network inspect <network_name>

目标：确认服务是否在同一个 compose network。

3. 服务名解析规则#

在 Compose 网络内，服务间应通过 service name:port 互访。

错误示例：

• 在容器 A 里访问 localhost:5432 连接数据库 B

正确示例：

• 使用 db:5432（db 为服务名）

4. depends_on 不是“服务就绪”#

depends_on 只保证启动顺序，不保证数据库已经可连接。

建议加健康检查和重试逻辑：

1
services:
2
  app:
3
    depends_on:
4
      db:
5
        condition: service_healthy
6
  db:
7
    healthcheck:
8
      test: ["CMD", "pg_isready", "-U", "postgres"]
9
      interval: 5s
10
      timeout: 3s
11
      retries: 10

5. 端口映射与容器内访问的区别#

• ports 用于“宿主机 <-> 容器”
• 容器之间互访不依赖 ports，依赖内部网络

很多人误以为不映射端口就不能互访，这是典型误区。

6. 快速诊断命令#

在容器内执行：

1
getent hosts db
2
nc -vz db 5432
3
curl -I http://api:8080

这三步能快速判断是 DNS、端口还是服务本身问题。

7. 常见修复动作#

1. 统一服务到同一个 user-defined network
2. 把跨容器访问地址改为服务名
3. 为依赖服务加 healthcheck
4. 应用端加启动重试机制

总结#

Compose 网络故障的本质是“认知模型错误”。 只要你把“容器内 localhost 只指向自己”这件事吃透，80% 的互访问题都能一次定位。

延伸阅读#

• Nginx 502/504 排错指南
• Cloudflare Pages 性能与安全优化
• Linux 服务器安全基线实战