Docker Compose中Redis连接失败的隐藏陷阱：项目名称下划线引发的血案（Unable to connect to redis-cache/＜unresolved＞:6379）

在微服务开发中，Docker Compose是本地环境搭建的神器，但一个不起眼的下划线却让我在Redis连接上耗费了数小时。本文将揭示这个隐藏陷阱及其解决方案。

问题现象：Redis神秘连接失败

在使用Docker Compose启动Spring Boot应用时，出现了以下Redis连接错误：

org.springframework.data.redis.RedisConnectionFailureException: Unable to connect to Redis
...
Caused by: io.lettuce.core.RedisConnectionException: 
Unable to connect to redis-cache/<unresolved>:6379
...
Caused by: io.lettuce.core.RedisCommandExecutionException: 
NOAUTH HELLO must be called with the client already authenticated

诡异的是：

• MySQL连接完全正常

• Redis配置看似正确（服务名、密码都正确）

• 仅Redis服务受影响

问题根源：下划线的诅咒

经过深入排查，问题出在Docker Compose的  name 属性上：

# 问题配置
version: '3.8'
name: "xm_lease"  # 这里使用了下划线

为什么下划线会导致问题？

1. DNS规范限制：

   • 标准DNS名称只允许字母、数字和连字符（-）

   • 下划线（_）是非法字符

2. Docker网络名称生成规则：

   # Docker会自动生成网络名称：
   {project_name}_{network_name}
   
   # 使用下划线时：
   xm_lease_app-network → 包含非法字符"_"

3. Redis客户端的严格解析：

   • Lettuce（Redis客户端）严格遵循DNS规范

   • 遇到非法字符直接拒绝解析

   • 日志中可见<unresolved>标记

为什么MySQL不受影响？

JDBC驱动对主机名解析更宽松：

• 自动尝试多种解析方式

• 对非法字符有更好的容错处理

• 底层TCP连接不受DNS名称影响

解决方案：一字之差的救赎

只需将下划线改为连字符：

version: '3.8'
- name: "xm_lease"
+ name: "xm-lease"  # 关键修改

完整解决方案

# compose.yaml 配置
version: '3.8'
name: "xm-lease"  # 使用连字符代替下划线

services:
  admin:
    environment:
      REDIS_HOST: redis-cache
      REDIS_PASSWORD: 123456

  redis-cache:
    image: redis:6-alpine
    environment:
      REDIS_PASSWORD: 123456

networks:
  app-network:
    driver: bridge

深入理解：Docker网络名称解析机制

Docker DNS工作原理

1. 每个容器加入Docker网络

2. Docker内置DNS服务器

3. 通过服务名进行容器间通信

名称解析流程对比

最佳实践与预防措施

1. 命名规范：

   # 推荐
   name: "project-name"
   
   # 避免
   name: "project_name"
   name: "project name"

2. 显式网络命名：

   networks:
     app-network:
       name: my-app-network  # 自定义合法名称
       driver: bridge

3. 连接测试命令：

   # 进入应用容器
   docker exec -it xm_lease_admin sh
   
   # 测试DNS解析
   nslookup redis-cache
   
   # 测试端口连通性
   nc -zv redis-cache 6379

4. Redis配置检查清单：

   • 服务名称匹配

   • 密码正确

   • 使用合法DNS字符

   • 网络配置正确

总结与反思

这个看似简单的下划线问题揭示了容器网络中一些重要原理：

1. DNS规范的重要性：基础设施必须遵循标准

2. 客户端实现的差异：不同服务对错误的容忍度不同

3. 排错思维：相同环境不同表现往往是关键线索

经验教训：在分布式系统中，命名不仅是约定，更是基础设施的基础。一个字符的差异可能导致整个系统瘫痪，规范命名是避免这类"幽灵问题"的第一道防线。

最后建议：在Docker Compose项目中始终使用连字符命名，这不仅是Redis的要求，更是遵循DNS标准的最佳实践。