Docker多阶段构建后Spring后端无法访问SQL Server的原因排查

问题描述 #

我有一个基于Spring框架的后端服务，原本通过本地执行mvn package生成.jar文件，用单阶段Dockerfile构建的容器能正常运行并访问SQL Server。

为了实现自动化构建和流水线部署，我把Maven打包步骤整合进Dockerfile，采用多阶段构建方式。但构建运行后出现如下错误：

com.microsoft.sqlserver.jdbc.SQLServerException: The TCP/IP connection to the host BACKENDSERV, port 1433 has failed. Error: "BACKENDSERV Verify the connection properties. Make sure that an instance of SQL Server is running on the host and accepting TCP/IP connections at the port. Make sure that TCP connections to the port are not blocked by a firewall.

源码没有任何改动，为什么多阶段构建后后端就无法访问SQL Server了？问题出在哪里？

问题根源分析 #

核心原因是多阶段构建的打包环节与本地构建的环境/配置处理逻辑不一致，具体分这几个常见情况：

• Maven打包时的配置文件替换错误
  本地执行mvn package时，大概率用的是本地的开发环境配置（比如application-dev.properties），其中数据库地址BACKENDSERV在本地的hosts文件或DNS中已有映射，能正常解析。但把打包步骤放进Docker多阶段构建后，若Dockerfile里的Maven命令没有指定正确的配置profile（比如默认用了生产环境配置），就会把无法在容器网络中解析的BACKENDSERV地址硬编码进最终的jar包，导致运行时连接失败。

• 构建阶段的网络/环境变量缺失
  本地打包时可能手动设置了环境变量来覆盖数据库配置，或者依赖本地hosts映射来解析BACKENDSERV，但多阶段构建的Maven容器是独立的隔离环境，没有这些配置，导致打包出来的jar包使用了错误的数据库地址。

• 容器运行时的网络解析问题
  单阶段构建时，你可能给容器配置了host网络模式，或者容器和SQL Server在同一个Docker自定义网络中，能直接解析BACKENDSERV。但多阶段构建的最终容器如果网络配置变更（比如默认用了bridge网络），而BACKENDSERV在该网络中没有对应的服务或hosts映射，就会出现解析失败。

解决步骤 #

1. 核对Maven打包命令的配置profile
   确保Dockerfile中Maven打包命令和本地一致，比如本地用mvn package -Pdev，Dockerfile里也要加上对应的profile参数：

   FROM maven:3.8.6-openjdk-11 AS builder
   WORKDIR /app
   COPY pom.xml .
   COPY src ./src
   RUN mvn package -Pdev -DskipTests
   

2. 对比本地与容器中jar包的配置文件
   把本地打好的jar和多阶段构建出来的jar里的配置文件做对比，验证数据库地址是否一致：

   • 本地：unzip -q -c target/your-app.jar BOOT-INF/classes/application.properties
   • 容器：docker run --rm your-image cat /app/BOOT-INF/classes/application.properties

3. 改用外部配置注入数据库地址
   不要把数据库地址硬编码进jar包，而是在容器运行时通过环境变量或命令行参数传入，比如：

   docker run -e SPRING_DATASOURCE_URL="jdbc:sqlserver://host.docker.internal:1433;databaseName=your-db" your-image
   

   （host.docker.internal是Docker提供的宿主机器别名，Windows/macOS直接可用，Linux需额外配置）

4. 检查容器网络配置
   如果SQL Server在Docker容器中，确保后端容器和SQL Server容器在同一个自定义网络中，并用容器名/服务名作为数据库地址；如果SQL Server在宿主机器，用宿主的实际IP替换BACKENDSERV。

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