跨docker-compose复用VPN容器网络栈的配置问题及文档查询

• network_mode: service:<服务名>是Docker Compose专属的单个项目上下文内引用语法，解析时只会检索当前配置文件中定义的services段内容，不会跨项目查找宿主机上已经运行的容器
• 跨独立Compose项目时，哪怕两个项目接入同一个外部桥接网络，只要当前配置内没有定义名为vpn的服务，就会直接抛出服务未定义的错误，和VPN容器是否正常运行无关
• 同一份compose.yml下该配置可正常工作，是因为被引用的vpn服务就在当前配置的services定义中，完全匹配Compose的解析规则。

1. 固定VPN容器的全局标识 #

首先调整VPN所在的Compose配置，给VPN服务指定固定的容器名，避免Compose自动生成带项目前缀的动态容器名：

version: '3'
services:
  vpn:
    container_name: shared_vpn_container # 固定全局唯一容器名
    # 原有VPN容器的镜像、环境变量、设备映射等配置
  vpn_user1:
    # 同项目内的服务依然可保留原配置，或替换为容器级引用
    network_mode: 'service:vpn'
networks:
  default:
    external:
      name: vpn_network

启动该配置，确认shared_vpn_container处于正常运行状态。

2. 调整独立项目的网络配置 #

将独立项目中原来的network_mode: 'service:vpn'替换为Docker原生支持的跨场景容器网络共享语法：

version: '3'
services:
  vpn_user2:
    # 原有业务容器的镜像、环境变量等配置
    network_mode: 'container:shared_vpn_container' # 直接引用固定名称的VPN容器
networks:
  default:
    external:
      name: vpn_network

该配置启动后，业务容器会直接挂载到VPN容器的网络命名空间下，所有流量的转发行为和同项目内复用VPN网络的效果完全一致。

• 跨项目引用时不要使用service:前缀：这个前缀是Compose专属的项目内引用语法，脱离单个Compose配置文件的上下文就无法完成解析
• 必须为VPN容器设置固定名称：如果依赖Compose自动生成的动态容器名，一旦项目重命名、容器重建，跨项目引用就会失效，固定名称是长期运行的最稳妥方案
• 启动顺序适配：container:模式是Docker引擎层面的挂载能力，只要VPN容器处于运行状态，依赖它的业务容器就能正常启动；建议给VPN容器配置restart: always自启规则，避免宿主机重启后业务容器因找不到VPN容器启动失败

network_mode相关的网络共享能力本质依赖Linux内核的网络命名空间机制：

1. 当两个容器共享网络命名空间时，它们会共用同一套网卡、IP地址、路由规则和端口空间，不需要额外配置端口映射或静态路由，所有出入站流量都会通过共享的网络栈走VPN容器的出口
2. Compose提供的service:XXX语法，本质是一层便捷封装：在项目启动阶段自动匹配对应服务的运行容器ID，最终转换为network_mode: container:<对应容器ID>的原生Docker参数下发给引擎
3. 同项目内使用service:XXX的优势是Compose会自动处理依赖启动顺序、自动更新容器引用ID，不需要手动维护容器名称；跨项目场景下没有这层自动封装，因此需要手动指定固定的容器名，走原生的container:引用路径。

内容的提问来源于stack exchange，提问作者user10685