Frappe Docker 项目中 WebSocket 服务连接 Redis 失败问题分析

问题背景

在使用 Frappe Docker 项目部署 ERPNext 系统时，WebSocket 服务频繁重启并报错，错误信息显示无法连接到 Redis 服务。具体表现为 WebSocket 服务尝试连接本地 127.0.0.1:12311 端口失败，而实际上 Redis 服务运行在 redis-queue:6379 地址。

错误现象

从日志中可以看到以下关键错误信息：

Error: connect ECONNREFUSED 127.0.0.1:12311

这表明 WebSocket 服务尝试连接本地 Redis 端口失败。查看容器状态会发现 WebSocket 服务处于不断重启状态，而其他服务如 Redis、数据库等运行正常。

配置分析

检查项目的 docker-compose 配置文件(mac.yml)，其中已经正确配置了 Redis 相关参数：

environment:
  DB_HOST: db
  DB_PORT: "3306"
  REDIS_CACHE: redis-cache:6379
  REDIS_QUEUE: redis-queue:6379
  SOCKETIO_PORT: "9000"

同时，容器内的 common_site_config.json 文件也显示配置正确：

{
 "db_host": "db",
 "db_port": 3306,
 "redis_cache": "redis://redis-cache:6379",
 "redis_queue": "redis://redis-queue:6379",
 "socketio_port": 9000
}

问题根源

尽管配置文件中正确指定了 Redis 连接地址，但 WebSocket 服务仍然尝试连接本地地址，这表明：

1. WebSocket 服务可能没有正确读取 common_site_config.json 中的配置
2. 或者配置加载顺序存在问题，导致使用了默认值(localhost:12311)
3. 也可能是权限问题导致配置文件无法被正确访问

解决方案建议

1. 验证配置文件加载：进入 WebSocket 容器内部，确认 common_site_config.json 文件确实存在且内容正确

2. 检查服务启动顺序：确保 Redis 服务完全启动并可用后，再启动 WebSocket 服务

3. 增加等待逻辑：在 WebSocket 服务启动前添加对 Redis 服务的健康检查，确保 Redis 完全就绪

4. 调试日志：修改 WebSocket 服务的启动命令，增加调试日志输出，确认它实际使用的 Redis 连接地址

5. 权限检查：确认 WebSocket 进程有权限读取 common_site_config.json 文件

技术细节

Frappe 框架的 WebSocket 服务依赖 Redis 进行消息队列处理。当 Redis 连接配置缺失或无效时，服务会回退到默认的本地地址(localhost:12311)。在 Docker 环境中，服务间需要通过容器名称进行通信，因此必须确保配置中的地址指向正确的容器名称(redis-queue)。

总结

这个问题典型地展示了容器化环境中服务间通信的配置挑战。虽然表面上看配置文件正确，但实际运行时可能由于各种原因导致配置未生效。建议开发者遇到类似问题时，首先进入容器内部验证配置文件的真实状态，然后逐步排查服务依赖关系和启动顺序。