Mac M1环境下Python连接Docker中SQL Server超时问题排查求助

1. 确认Docker容器端口映射正确性 #

执行docker ps查看SQL Server容器的PORTS列，确认容器的1433端口已映射到主机的对应端口（比如0.0.0.0:1433->1433/tcp）。如果映射到非1433端口，连接字符串的Server部分要加上端口，例如Server=localhost,1434。

2. 替换localhost为主机局域网IP #

M1 Mac的Docker网络可能存在localhost路由问题，尝试用主机的局域网IP（通过ipconfig getifaddr en0获取）替换localhost，连接字符串改为Server=192.168.x.x,1433（替换为实际IP）。

3. 调整ODBC连接字符串的加密参数 #

ODBC Driver 18默认强制加密，而Docker中默认运行的SQL Server未配置有效证书，这是常见的超时原因。修改连接字符串添加以下参数之一：

• 关闭加密：

  db_connection_string = "Driver={ODBC Driver 18 for SQL Server};Server=" + server + ";Database=" + database + ";UID=" + username + ";PWD=" + password + ";Encrypt=No;"
  

• 信任自签证书（保留加密）：

  db_connection_string = "Driver={ODBC Driver 18 for SQL Server};Server=" + server + ";Database=" + database + ";UID=" + username + ";PWD=" + password + ";TrustServerCertificate=Yes;"
  

4. 对比Azure Data Studio的连接配置 #

打开Azure Data Studio的连接属性，查看它使用的服务器地址、加密选项、端口等参数，将这些配置完全复制到Python的连接字符串中。例如Azure Data Studio可能使用了特定的端口或加密设置，照搬即可。

5. 验证容器内SQL Server的监听状态 #

进入SQL Server容器，执行以下命令：

• 测试容器内本地连接：

  docker exec -it <container-name> /opt/mssql-tools/bin/sqlcmd -S localhost -U sa -P password
  

  若能正常连接，说明SQL Server本身运行正常。
• 检查监听地址：

  docker exec -it <container-name> netstat -an
  

  确认输出中有0.0.0.0:1433的监听记录（允许外部访问）。若仅监听127.0.0.1，需修改容器内的/var/opt/mssql/mssql.conf，添加：

  [network]
  ipaddress = 0.0.0.0
  

  然后重启容器：docker restart <container-name>。

6. 测试网络连通性 #

在终端执行以下命令，验证主机到容器端口的连通性：

nc -zv localhost 1433

若提示Connection refused，说明网络层面存在问题：

• 检查Mac系统防火墙是否阻止了Python访问该端口；
• 重新确认Docker端口映射配置是否正确。

7. 确认pyodbc使用的驱动匹配 #

运行驱动检查代码，确保连接字符串中的Driver名称与输出完全一致：

import pyodbc
drivers = pyodbc.drivers()
for d in drivers:
    print(d)

例如输出为ODBC Driver 18 for SQL Server，则连接字符串中的Driver={ODBC Driver 18 for SQL Server}必须完全匹配，注意大小写和空格。

内容的提问来源于stack exchange，提问作者Nigel Verlè