Frappe_docker多项目共享MariaDB时的服务命名冲突解决方案

问题背景

在使用Frappe_docker进行单服务器多工作台(Single Server Multi Bench)部署时，当多个项目共享同一个MariaDB服务时，可能会出现Redis队列作业执行失败的问题。这是因为默认配置下，不同项目的Docker服务使用相同的名称，导致Redis队列作业被错误地分配到其他项目的worker上执行。

问题现象

具体表现为Rq Worker日志中出现类似错误：

frappe.exceptions.IncorrectSitePath: 404 Not Found: <sitename> does not exist

这是因为ProjectA的worker错误地从ProjectB的Redis队列中获取了作业，而ProjectA的worker环境中并不存在ProjectB的站点配置。

根本原因分析

当多个Docker Compose项目共享同一个网络(如mariadb-network)并且使用相同的服务名称时，Docker的DNS解析行为会导致服务发现不可预测。虽然Docker的网络隔离机制理论上可以防止冲突，但当服务共享网络时，Docker无法保证名称解析会指向哪个具体的服务实例。

解决方案

方案一：为每个服务指定唯一名称

最彻底的解决方案是为每个项目中的服务指定唯一的名称。例如：

• 将backend改为backend-projectA
• 将websocket改为websocket-projectA
• 其他服务同理

这种方法完全避免了名称冲突的可能性，是最推荐的解决方案。

方案二：为每个服务指定唯一主机名

如果不想修改服务名称，也可以通过覆盖配置为每个服务指定唯一的主机名。创建一个override文件(如override_compose.hostname.yml)：

services:
  configurator:
    hostname: ${ROUTER}-configurator
  backend:
    hostname: ${ROUTER}-backend
  websocket:
    hostname: ${ROUTER}-websocket
  # 其他服务...

然后在docker compose命令中引用这个覆盖文件。

方案三：使用独立的MariaDB实例

如果不希望共享MariaDB，可以为每个项目配置独立的MariaDB实例。这样就不需要共享mariadb-network，自然也就避免了服务名称冲突的问题。不过这种方法会增加资源消耗。

实施建议

1. 统一命名规范：建议采用<service>-<project>的命名模式，如backend-erpnext、backend-healthcare等

2. 环境变量管理：可以使用环境变量来动态设置服务名称，便于维护

3. 配置检查：修改后应检查common_site_config.json中的相关配置，确保服务发现指向正确的地址

4. 测试验证：修改后应充分测试队列作业的执行情况，确认作业被正确分配到对应项目的worker

总结

在Frappe_docker的多项目部署场景中，服务命名冲突是一个常见但容易被忽视的问题。通过为每个项目的服务指定唯一名称或主机名，可以彻底解决Redis队列作业被错误分配的问题。这种方法不仅解决了当前的错误，也为后续可能的扩展提供了更好的基础架构支持。