Docker Swarm中通过Docker Stack部署的Jenkins节点无法被检测

我在Docker Swarm环境中通过Docker Stack配合docker-compose.yml部署Jenkins主节点和工作节点，Jenkins容器已安装Swarm插件。此前启动时所有工作节点都能被主节点自动检测并添加，但现在该功能突然失效，主节点无法发现工作节点。

用到的关键命令：
初始化Docker Swarm：

docker swarm init

部署Stack服务：

docker stack deploy --compose-file <path_to_compose_file> <name_of_stack>

精简后的docker-compose.yml配置：

version: '3'

services:

  jenkins-master:
    image: jenkins-master:latest
    volumes:
      - /var/docker-data/master-volume:/var/jenkins_home
      - /var/docker-data/backup-volume:/var/lib/backup
    ports:
      - "443:8443"
      - "80:8080"
      - "50000:50000"
    networks:
      - jenkins_swarm
    deploy:
      placement:
        constraints:
          - node.role == manager

  jenkins-worker:
    image: jenkins-worker:latest
    networks:
      - jenkins_swarm
    command: -labels "worker" -executors 8 -master "http://<IP of master>/"
    deploy:
      mode: replicated
      replicas: 1
      placement:
        constraints:
          - node.role == manager

networks:
  jenkins_swarm:

可能的问题点及排查步骤 #

1. 网络与地址配置错误 #

• 同一Swarm overlay网络内，工作节点可以直接通过服务名jenkins-master访问主节点，没必要用外部IP。建议把工作节点的-master参数改成http://jenkins-master:8080/，避免主节点IP变更导致连接失败。
• 在工作节点容器内执行curl http://jenkins-master:8080，确认能正常访问主节点的Jenkins页面；同时检查50000端口的连通性（telnet jenkins-master 50000），Swarm主从通信依赖该端口。

2. Swarm插件配置异常 #

• 登录Jenkins主节点，进入系统管理→Swarm插件配置，确认已开启“允许自动注册新节点”，且没有设置节点名称白名单、标签过滤等限制规则。
• 查看主节点系统日志（系统管理→系统日志），搜索swarm关键词，排查是否有认证失败、连接拒绝等错误信息。

3. 工作节点启动参数缺失 #

• 如果Jenkins主节点后来开启了安全认证，工作节点的启动命令需要添加-username和-password（或-passwordEnvVariable）参数，否则会因认证失败无法注册。
• 查看工作节点服务日志：docker service logs <stack_name>_jenkins-worker，直接获取连接失败的具体原因，比如超时、认证错误等。

4. Docker Swarm集群状态异常 #

• 执行docker node ls，确认manager节点状态为Ready，没有出现Down或Unreachable的情况。
• 执行docker service ls，检查jenkins-worker服务的副本数是否符合配置，容器是否处于Running状态；若容器反复重启，说明启动命令或镜像存在问题。

5. 主节点配置文件损坏 #

• 主节点挂载的/var/jenkins_home数据卷可能存在配置损坏，比如Swarm插件的配置文件出错。可以临时创建一个不挂载旧数据卷的主节点容器，测试工作节点是否能正常注册，以此排除数据卷的问题。

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