XXL-Job Docker 部署中“登录无响应”的排查与解决

前言最近在 Ubuntu 服务器上使用 Docker 部署 XXL-Job 分布式任务调度平台时遇到了一个典型但容易踩坑的网络问题调度中心容器与 MySQL 容器无法正常通信导致登录界面点击后毫无反应。本文将复盘整个部署过程并重点分享如何通过 Docker 自定义网络彻底解决该问题。如果你也正准备在 Linux 环境下用 Docker 搭建 XXL-Job或者遇到类似的容器互联问题相信这篇文章能帮你少走弯路。环境说明操作系统Ubuntu 20.04 / 22.04Intel 芯片Docker 版本20.10MySQL已通过 Docker 运行amd64/mysql:5.7.36容器端口映射3306:3306容器名mysqlroot 密码rootXXL-Job 版本2.4.0数据挂载路径/data/docker/xxl-job/logs第一阶段初始化数据库XXL-Job 依赖 MySQL 存储任务元数据首先需要执行官方提供的初始化脚本。# 下载 2.4.0 版本的 SQL 脚本wgethttps://raw.githubusercontent.com/xuxueli/xxl-job/2.4.0/doc/db/tables_xxl_job.sql# 将脚本导入已运行的 MySQL 容器dockerexec-imysql mysql-uroot-proottables_xxl_job.sql验证表是否创建成功dockerexec-itmysql mysql-uroot-proot-eUSE xxl_job; SHOW TABLES;若看到xxl_job_info、xxl_job_log等表说明数据库初始化完成。第二阶段启动调度中心首次尝试方案一按照常规思路我将 MySQL 端口映射到了宿主机3306于是尝试让 XXL-Job 容器通过127.0.0.1:3306连接数据库dockerrun-d\--namexxl-job-admin\--restartalways\-p8080:8080\-v/data/docker/xxl-job/logs:/data/applogs\-ePARAMS--spring.datasource.urljdbc:mysql://127.0.0.1:3306/xxl_job?useUnicodetruecharacterEncodingUTF-8autoReconnecttrueserverTimezoneAsia/Shanghai \ --spring.datasource.usernameroot \ --spring.datasource.passwordroot \ --xxl.job.accessTokendefault_token\xuxueli/xxl-job-admin:2.4.0容器启动正常访问http://服务器IP:8080/xxl-job-admin也能看到登录页。然而输入账号admin密码123456点击登录后页面毫无反应浏览器控制台也没有明显报错。第三阶段问题排查1. 查看容器日志dockerlogs-f--tail100xxl-job-admin日志中抛出了关键异常org.mybatis.spring.MyBatisSystemException: nested exception is org.apache.ibatis.exceptions.PersistenceException: ### Error querying database. Cause: org.springframework.jdbc.CannotGetJdbcConnectionException: Failed to obtain JDBC Connection; nested exception is java.sql.SQLNonTransientConnectionException: Could not create connection to database server. Attempted reconnect 3 times. Giving up.很明显调度中心根本无法连接到 MySQL 数据库。2. 分析网络隔离原因问题的根源在于 Docker 容器的网络隔离机制XXL-Job 容器内使用的127.0.0.1指向的是容器自身而不是宿主机。MySQL 虽然通过-p 3306:3306将端口映射到了宿主机但容器想要访问宿主机网络不能直接使用127.0.0.1。3. 尝试方案一host.docker.internal在 Mac/Windows 的 Docker Desktop 中可以使用特殊域名host.docker.internal来访问宿主机。我尝试在 Linux 下也使用该方式将连接地址改为jdbc:mysql://host.docker.internal:3306/xxl_job?...重新启动容器后问题依旧。查阅文档发现在 Linux 系统上Docker 默认并不支持host.docker.internal除非在docker run时添加--add-host参数手动映射。因此方案一失败。第四阶段最终解决方案方案二—— 使用 Docker 自定义网络最标准、最稳定的做法是将两个容器置于同一个自定义 Docker 网络中直接通过容器名互相访问。步骤详解1. 创建自定义桥接网络dockernetwork create xxl-net2. 将已运行的 MySQL 容器连接到该网络dockernetwork connect xxl-net mysql3. 启动 XXL-Job 容器并加入同一网络注意数据库连接地址直接使用 MySQL 容器名mysql# 如果之前启动过 xxl-job-admin先停止并删除dockerstop xxl-job-admindockerrmxxl-job-admin# 使用新网络启动dockerrun-d\--namexxl-job-admin\--networkxxl-net\--restartalways\-p8080:8080\-v/data/docker/xxl-job/logs:/data/applogs\-ePARAMS--spring.datasource.urljdbc:mysql://mysql:3306/xxl_job?useUnicodetruecharacterEncodingUTF-8autoReconnecttrueserverTimezoneAsia/Shanghai \ --spring.datasource.usernameroot \ --spring.datasource.passwordroot \ --xxl.job.accessTokendefault_token\xuxueli/xxl-job-admin:2.4.0原理说明同一个自定义网络内的容器Docker 会提供内置的 DNS 服务。容器名mysql会被解析为 MySQL 容器的内部 IP无需关心端口映射直接通过容器的3306端口通信。这种方式避免了宿主机端口暴露带来的安全隐患也绕过了127.0.0.1的歧义问题。4. 验证结果再次访问http://服务器IP:8080/xxl-job-admin输入admin/123456登录成功如果遇到密码错误可以进入 MySQL 容器手动将xxl_job_user表中admin用户的密码改为 MD5 值e10adc3949ba59abbe56e057f20f883e对应123456因为 2.4.0 版本存在密码加密方式不一致的已知问题。总结本次部署的核心卡点在于Docker 容器间的网络通信。通过自定义网络xxl-net我们实现了调度中心与 MySQL 的稳定互联配置简洁无需关心宿主机 IP 变化符合 Docker 最佳实践易于后续扩展如增加更多执行器容器完整部署架构图简化版一些经验教训在 Linux 上不要依赖host.docker.internal除非你手动在docker run中添加--add-host host.docker.internal:host-gateway。优先使用 Docker 自定义网络来处理容器间通信这是官方推荐的方式。遇到问题时第一时间查看容器日志docker logs 容器名往往能直接定位错误。希望这篇记录能帮助你在 Docker 上顺利部署 XXL-Job也为你处理类似的容器网络问题提供一个清晰的思路。