排查 docker swarm 节点与管理节点通信加密失败,核心是检查 tls 证书链是否完整、ca 签名是否有效以及网络端口(2377)是否可达。通常通过 `docker swarm init` 或 `docker swarm join` 的报错信息定位是证书过期、cn/san 不匹配还是防火墙拦截。确保管理节点生成的 join token 未过期,且所有节点的系统时间同步,避免因时间偏差导致证书验证失败。

如何验证 TLS 证书链与 CA 信任关系
当节点无法加入集群时,首要步骤是确认管理节点的 CA 证书是否被工作节点正确信任。Docker Swarm 使用 PKI 体系,如果工作节点持有的 CA 证书与管理节点不一致,或者中间证书缺失,握手就会失败。可以通过在管理节点导出 CA 证书,并在工作节点上手动验证其有效性来排查。重点检查证书的 Subject Alternative Name (SAN) 是否包含当前节点的主机名或 IP,因为 Docker 默认严格校验主机名。

# 在管理节点生成 CA 证书 openssl x509 -in /var/lib/docker/swarm/certs/ca.pem -text -noout # 在工作节点验证证书 openssl verify -CAfile /var/lib/docker/swarm/certs/ca.pem /var/lib/docker/swarm/certs/ca.pem
上述命令会输出证书的详细字段。若验证失败,提示 "certificate has expired" 或 "self-signed certificate",则说明证书状态异常。确保所有节点的时间戳一致,NTP 服务正常运行。如果 SAN 中缺少当前节点 IP,需重新初始化集群或使用 docker swarm ca --rotate 轮换证书以更新 SAN 记录。
如何检查网络连通性与端口防火墙设置
TLS 握手成功的前提是 TCP 连接能建立。Docker Swarm 管理节点监听 2377 端口,若防火墙规则阻止了该端口的入站连接,节点将无法发送 Join 请求。即使证书正确,网络隔离也会导致超时错误。需要在工作节点上使用 telnet 或 nc 测试管理节点 2377 端口的连通性。同时,Swarm 内部还使用 UDP 4789 端口进行 VXLAN 覆盖网络通信,虽然这不影响加入过程,但影响后续服务调度,排查时应一并确认。
通过 Docker 或 docker compose 部署独立的 LYGO 协议栈社区节点。构建 lygo-node镜像,启动健康检查 API 于端口 8787,可选 Phase 4...

# 在工作节点测试管理节点 2377 端口 nc -zv <MANAGER_IP> 2377 # 检查本地防火墙规则 sudo iptables -L -n | grep 2377 # 如果使用 firewalld sudo firewall-cmd --list-ports
如果 nc 命令返回 Connection refused 或 Timeout,说明网络层不通。检查云服务商的安全组或本地 iptables/firewalld 配置,确保允许来自工作节点网段的 2377/TCP 流量。对于多网卡环境,确认 dockerd 绑定的 IP 地址是工作节点可访问的地址,而非仅 localhost。
基于 Join Token 过期或失效的具体问题
Docker Swarm 的 Join Token 具有有效期,默认为 3 小时(Manager Token)或 3 天(Worker Token)。如果节点在 Token 过期后尝试加入,或者 Token 已被撤销,通信加密将因身份验证失败而终止。此时报错通常指向 "token expired" 或 "unauthorized"。解决此问题的方法是重新生成新的 Join Token,并在节点上执行加入命令。不要重复使用旧 Token,因为 Swarm 会在首次成功后将其标记为已使用或过期。
# 在管理节点查看当前 Token docker swarm join-token worker # 重新生成 Worker Token docker swarm join-token worker -r # 在新终端使用新 Token 加入 docker swarm join --token <NEW_TOKEN> <MANAGER_IP>:2377
执行 join-token -r 会强制刷新 Token 列表。注意,轮换 Token 不会影响已存在的节点,但会影响尚未加入的新节点。如果节点反复加入失败,检查 /var/log/syslog 或 journalctl -u docker 中的详细日志,确认是否为 Token 认证环节报错。确保在生成 Token 后,立即在目标节点执行加入操作,避免长时间延迟导致意外过期。

















